Manual Information

Preface:

Welcome to the Pettus Chemistry Calculator program and operating manual.

This manual is provided to address the needs of a variety of users. There are new users, students, and advanced users. There can be an overlap between the categories. This manual has sections that address the problems/challenges faced by each group as well as by all users. The major objectives are to make the program useful to all users, to improve the current functionality, and to develop the program to its full potential. Such changes necessitate having a source of information and instructions so any user can learn to use the latest version of the program. So, there are sections with information about the program and detailed instructions on how to use the various objects/widgets. The sections are labeled so users can determine where they need to go to become proficient – at their current level. There is a section that describes the sequence and content of revisions – so users can see what needs to be learned or relearned. Several sections are under development. They are included so the user can see what can potentially be developed with the site. In the meantime, ignore them.

An abbreviated version of the information and instructions is available in the left-hand panel of the program. They are only included as an introduction to the program.

The program and this manual will only be useful if users provide feedback about what they like or don’t like, what works or doesn’t work, and obviously, what is wrong. Opinions will vary, but what is wrong should be undisputable.

The information panel of the program has contact information for feedback.

Table of Contents:

Preface:

General Information:

Recent Changes:

Form layout:

Program flow:

Widgets:

Default Processes:

Special Processes:

Instructions:

Stoichiometry:

Multiple Substance Manipulations:

Multiple Substance Stoichiometry:

Explanations:

Miscellaneous:

General Information:

General purpose:

What the program does:

The program is designed to allow users to perform many non-graphical computations of general chemistry problems and chemistry-related processes, and to provide an explanation of each process – the program is not a black box.

What the program does not do:

It does not do graphical problems such as Lewis structures or calculations involving energy that do not use the substances depicted in the GUI and it does not explain vocabulary or theories.

Current state and future development:

This is the first version of the web-based program. The intent is to let users see and do some of the basic processes and calculations that can be done with the program. The initial version is very basic. If there is enough interest in paid versions of the program, a chemistry instructor and chemist, and programmers will be hired to develop the program to its full potential. The program currently has some building blocks for the decomposition (parsing) of compounds such as AlCl3 into AL and CL (or AL and CL2) – into ions and elements – so the program will eventually be able to do complete molecular equations, complete ionic equations, and net ionic equations -- CME, CIE, and NIE. Currently, after an equation has been balanced, the user can change a substance quantity or a mole quantity and that change will cascade through the rest of the formulas – changing all the other quantities.

Note that fully calculated values are displayed. Since the program does not know when the final process has been completed, or the rules a specific user has for determining significant digits, the program does not round numbers. Also, the displayed temperature quantity and units are changed to a calculated temperature in K, and the displayed pressure quantity and units are changed to a calculated pressure in atm, and those calculated temperature and pressure quantities are used in gas law calculations.

Some functions do not always work and shouldn't work by default. For example, if the user inputs a substance and calculates molarity (or molality) and then wants to change the main substance quantity or mole quantity, the program doesn't know whether to change the number of liters or the molarity. So, there isn’t a default process. Instead, the user needs to specify the kind of change desired by selecting the appropriate minor process, e.g., “molarity or moles to liters.” Also, some functions may require units to be reset so the function works, e.g., liters(l) to kilograms and back to liters(l) for molarity changes. Some functions may also require the user to click on the "Continue" button to complete the function. These issues will be explained further in the instructions section.

At the top of the form, there is a section that will allow paid users to save a record of the process. At the bottom of the form, there is a section that will allow users to add additional information about a process. Both of these sections will only be developed if there is sufficient interest and funding. Paid users will also have access to additional functionality and a larger database of substances. These will all take time to implement. Users are encouraged to critique the program, provide suggestions for future improvements and comment on their willingness to fund future development with a monthly fee or a donation. Do so by sending comments and suggestions to grdnpettus@outlook.com. Some parts of the program don’t work, but have been included so users can see the potential for the program.

Known issues: data errors may cause an incorrect or no display of a property. There is a normal (default) sequential flow for most processes and a special process flow for other processes. Some processes can handle some steps out of sequence, but others can't; so, if you enter data out of sequence, a process may not produce the correct results.

Errors. Errors are bound to happen. In order to help resolve programming errors, if you are using Chrome, please do the following: When you recognize that an error has occurred, right-click on the web page, go to the bottom of the menu, and click on “inspect page.” That will open a panel on the right side of the form. In the top area of that panel, find “Console” and click on it. When the page is filled, click on the text and select all text, this can be done by holding down the CTRL key and pressing the “a” key. Next, find the contact email address (grdnpettus@outlook.com) and open a new email. Paste the copied text into the body of the email. Add a description of the error you detected. Add a subject line: such as Chemistry program error text. And send the email. The information provided will greatly aid in finding and resolving the problem. Firefox and other browsers may have the inspection panel in a different location, but it should function essentially the same way.

Explore the settings:

If you have font size preferences, they will be saved if you are a registered user.

Contact info: grdnpettus@outlook.com

Recent Change:

No changes yet; this is the initial version of the manual.

Form layout:

There are several major areas of the form.

The topmost line has the page title and various navigation widgets that allow the user to register, log in, subscribe to a free or paid program, set default values for fonts, and access this manual.

The top section has a lot of advanced functions that are under development – such as saving a record of a process and searching for that record so it can be redisplayed without recreating everything. There are a few special functions that will be used by most users; they will be described in the instructions section. They include choosing major and minor processes, clearing the explanations text, setting Process Yield, and designating a process as being a balanced equation.

The main part of the program is below the top section and consists of three columns – the left, center, and right columns. The left column contains accordion widgets that expand and contract when clicked. They contain information about the program, instructions on how to do the basic operations, and explanations of what the user selected or input and what the program did in response. The center and right columns each contain 3 substance containers. The substance containers contain a variety of widgets that allow the user to manipulate the extrinsic property values of the selected substance. These widgets operate the same in each of the containers. So, when you learn how to use a widget in the substance 1 container, the corresponding widget in each other container will work the same way. The bottom two rows of widgets in all substance containers are there so users can see the potential for the development of thermodynamic calculations and parsing compounds into ions. They can currently be ignored.

The center and right columnscenter and right columns each contain 3 substance containers. The substance containers contain a variety of widgets that allow the user to manipulate the extrinsic property values of the selected substance. That is, you can’t change intrinsic values – such as the atomic weight of an element, its valence, melting, boiling point, etc., but you can change extrinsic/calculated values, such as mass, volume, mole quantity, displayed temperature and pressure, quantity and units, molarity, etc. These widgets operate the same in each of the containers. So, when you learn how to use a widget in the substance 1 container, the corresponding widget in each other container will work the same way. The bottom two rows of widgets in all substance containers are there so users can see the potential for the development of thermodynamic calculations and parsing compounds into ions. They can currently be ignored.

Below the three main columns, there is a row of widgets that will eventually be used to specify properties associated with chemical processes – such as equipment used, type of energy used, amount of energy, catalysts, by-products, side-effects, etc. They are under development and can currently be ignored.

Below that row of widgets, there is another section for explanations that are better suited to a wide section of text.

The footer has information about the copyright and the current version of the program.

Program flow:

The program is event-driven. This means that nothing is supposed to happen unless the user clicks on a button, selects an option from a combo box, or inputs a value in an entry widget. Most of the time, when an event is initiated, the program will start an automatic default process and complete it. When a process needs to happen that is different from the default, the user needs to select a specific process to perform – such as by selecting a major or minor process. That process will be performed when the necessary condition has been activated. Thus, you could select the minor process “molarity and moles to liters(g)” and nothing will happen until you changed either the quantity of molarity or of moles. Similarly, if you change the “Process Yield” quantity to less than 1.0, the yield calculation will not be done until a multi-substance quantity adjustment is performed. Activating the “Clear Explanations Text” button will immediately clear the explanation text. However, selecting the “Equation is Balanced” button will activate a process and send a message to the explanations panel, but the majority of the process will not occur until a quantity input has been made. Other widgets work the same.

Widgets:

There are three main types of widgets: buttons, combo boxes, and entry objects.

Buttons are activated by clicking on them.

Combo boxes work by selecting one of the available options – except for formula and compound name combo boxes where the user can select an option or start entering a formula or name. These combo boxes have an autocomplete feature that allows the user to input a letter or number that will narrow the search for valid options. For compounds, the program will attempt to find a match in the substances database; when a match can’t be found, the program will search Wikipedia for a possible match. If a match is found, that option is displayed in the combo box and the user can click on it to select it -- additional substance properties will also be scraped off the web. If no match is found, the program stops and waits for the user to do something the program can respond to.

For input or entry widgets, the form will allow entry in the form of integers, decimal numbers, or scientific notation, but not numbers with a comma. After a calculation has been made, the number will be displayed with integers or decimal numbers. It will not display numeric values using scientific notation. If you try to display a non-number in a number box or if a non-number is calculated, the program will display "NAN" -- which stands for Not A Number.

Default Process

The program has three main ways of controlling process flow. The main way is with default process logic. This is the way a calculation is most frequently done. If the user wants to do a process differently, a special process needs to be selected. A third way is to click on a button.

Special Processes

Special processes, (those different from the default) need to be activated by selecting either a major or a minor process. For example, if you are doing gas calculations, changing the temperature or pressure or the number of moles will cause the program to change the volume. Also, if you change the volume, the default process is to change the number of moles of the substance. However, if you want to change the volume and have the temperature, or pressure, changed, you need to select the applicable minor process. Similarly, if you want to change the temperature and see the effect on pressure, you need to select the applicable minor process. Similarly, once liters(l) or kilograms have been selected, molarity or molality will be calculated. After the initial calculation, changes in liters(l) or kilograms will change units of molarity or molality, but all other changes need to be selected using a minor process. Some of these processes are still under development.

The major and minor process combo boxes have lists of special processes currently available. Occasionally, additional processes will be added and, if selected, will display a note that the function is not currently functional. The main reason for doing so is to let users know what is being developed – so they won’t need to request it in an email comment.

Instructions

Quick start. Find out if the program will be helpful before you register, login or do anything else with it. To get an idea of how to use the program, there is a top section that is full width; ignore it for now -- there are a couple widgets that will be explained in the instruction section. Below the top section, there are three columns. The center and right columns each have three containers.
Important: to get the most of the program, check the explanations text to see what you did and what the program did. Does the explanation help you learn? Please provide feebback.

Stoichiometry

Go to the top of the center column: find the label Select Substance 1 type from ComboBox 1
Select 'element' as the type of substance.
Directly below that combo box, find the label Substance 1
When you select a substance type, the program will fill in the combo boxes below the Substance 1 label with formulas and names.
Under the label Substance 1, select any formula.
The program will fill in the formula combo box with the formula you selected, and it will find the associated name and insert it in the combo box below the formula.
(Likewise, selecting a substance name will fill in the formula.)
Also, the program will always set the initial substance units to 'grams', fill in the atomic or molecular mass in the quantity field and set the mole quantity to 1 and units to 'moles'.
Repeat the above steps for substance 4 except select ‘compound’ type and select any compound. Also, after doing each of the following for substance 1, do the same thing for substance 4.
Under the label Substance 1 Qty, enter a new quantity and press return.
The program will retrieve the atomic weight of the substance you selected, divide the quantity you just entered by the atomic weight, calculate a new mole quantity, and insert that mole quantity in the mole quantity box.
Enter a new mole quantity.
The program will retrieve the atomic weight of the substance you selected, multiply the mole quantity you just entered times the atomic weight, calculate a new mass quantity, and insert that quantity into the Substance 1 Qty box.

Change the mole quantity back to 1.
Under the label Substance 1 Units, change the units from grams to liters(g).
The program will access the displayed quantities and units for moles, temperature, and pressure and convert them to calculated quantities and units and use these quantities to calculate the volume of the gas using the standard gas formula.

Note that the program will allow the user to make mistakes! If you select a substance that is solid at the temperature and pressure displayed, the program will not complain about you doing gas law calculations on a substance that is not a gas!

Three rows below the Substance 1 Qty label, find the Temp Qty | Change label.
Change the temperature quantity. The new volume will be calculated and displayed.
To the right of the Temp Units label, find the Press Qty | Change label.
Change the pressure quantity. The new volume will be calculated and displayed.
Find the Temp Units label.
Change the temperature units. The new volume will be calculated and displayed.
Find the Press Units label.
Change the pressure units to ‘torr.’ The new volume will be calculated based on the current press qty.
Change the pressure quantity to ‘760’ The new volume will be calculated and will be equal to 1 atm pressure.
Reset all the temperature and pressure units to 0 degrees C and 1 atm.

Go to the upper part of the form; in the bottom left area, find the label Minor Process.
Select the minor process: “temperature to pressure”.
Change the temperature quantity, e.g., to 100. Notice the change in the pressure quantity!
This is an example of the difference between a default process and a special process. For the special process, the user needs to select a special process so the program can do something that is not the default process.

Note: Some minor processes are displayed that are not yet functional. These processes are displayed so the user will know what is in development and won’t need to request it in a feedback email.

Change the mole quantity to 0.25.
In the entry widget below that quantity, input 0.5.
In the units combo box to the right, select “liters(l).”

The program now has the data it needs to calculate molarity; so it calculates molarity and displays the calculated molarity and the units “molarity” in the widgets to the right of liters(l).
Change the liters(l) to kilograms. The molarity will be changed to molality.

Once these initial entries have been made, changing the liters(l) and kilogram units and the changes to molarity and molality are the only default changes that can be made!

In order to change the mole quantity, have the molarity quantity remain unchanged, and have the liters(l) quantity change, go up to the upper section, find the Select Minor process label, and in the combo box to the right, select the minor process “molarity and moles to liters”.
Change the mole quantity to .5 or 0.5. The liters(l) quantity will be recalculated using the mole and the molarity quantities.
Keep the same minor process selected. Change the molarity quantity to .6. The liters(l) quantity will be recalculated using the mole and the molarity quantities.
Look at the other minor processes to see what other options exist.
The “Parse Compounds to ions” and Parse Compounds to elements” functions are building blocks that will be used when the major process “Balance Equation” is developed.
Meanwhile, compounds are automatically parsed, and the parsed ions and quantities are displayed in the bottom row of the substance container. The displayed ions should be correct for ionic compounds, but not for covalent ones. Covalent compounds are currently reversed; so CH4 shows “C” as the cation and 4 “H” as the ion.
You have now learned how to use most of the 29+ widgets in all 6 substance containers. Those at the bottom of the container, e.g., Heat Qty, etc. can be ignored for now.

Multiple Substance Manipulations

The prior section on stoichiometry dealt with manipulating the properties of a single substance. Now, shift to multiple substance manipulations!
This is where you can create substance equations, evaluate them, and modify them until you are satisfied with the results – without writing, erasing, scratching out entries, or rewriting anything!

Follow these steps:
Set substance 1 type to element; select Al.
Set substance 2 type to element; select Cl.
Set substance 4 type to compound; select AlCl3.
Balance the equation.
Since you shouldn’t have a diatomic element represented as a stand-alone substance (element) in an equation, make the following changes.
Set substance 2 type to diatomic; select Cl2.
Balance the equation.
See how easy that was!

Next equation:
Set substance 1 type to element; select Al.
Set substance 2 type to compound; select HCl.
Set substance 4 type to compound; select AlCl3.
Set substance 5 type to diatomic; select H2.
Balance the equation.
See how easy that was!
When you are ready, practice creating, analyzing, and balancing other equations.

Multiple Substance Stoichiometry

Now learn how the program can help with adjusting the quantities of balanced equations.
Set all 6 substance types to compound; select all substances to be CH4.
Chemically, this doesn’t make sense; it is only used to demonstrate quantity adjustments.
Set the following mole quantities for substances 1 through 6: 2, 3, 5, 4, 6, and 7.
Clear the Explanation text.
In the top section, near the bottom right corner, click on the button labeled, “Equation is Balanced”
Look at the Explanation text. It will display: EquationIsBalanced = True 0,2,3,5,4,6,7,0
This is a zero-based list. That means the first item is item 0, the second item is item 1, etc.
In this list, the first and last items are set to 0. The second through seventh items are set to the mole coefficients of substances 1 though 6.
We are going to make mole-to-mole calculations using mole-to-mole ratios and calculations using multiples of .25 – because they are easy to calculate mentally.

On paper, write down all the mole coefficients. On paper, change the mole quantity of substance 2 to .75.

Now, calculate all the new substance mole quantities using mole-to-mole ratios. For example, the mole-to-mole ration of substance 1 to substance 2 is 2 to 3.
Since substance 2 mole quantity is now .75, using the 3 to 2 ration, substance 1 mole coefficient should be .5. Calculate the rest of the new mole coefficients.

Now, on the form, change the mole quantity of substance 2 to .75.
The rest of the mole quantities and the gram quantities should have been recalculated!

Check the Explanation text to see the calculations the program made.

In a balanced equation in the proper form, all the coefficients are supposed to be whole numbers. However, from the point of view of calculations, decimal coefficients work the same. To illustrate this, click on the “Equation is Balanced” button again.
Change one of the substance coefficients to its original value, e.g., change substance 1 coefficient to 2. All the coefficients should have returned to their original numbers – sometimes a coefficient will be changed to the number plus or minus .0000000000001. This is the result of the way the computer calculates.

In the upper section of the form, find the label, “Process Yield”; change the value to .8.
For substance 4, change the units from grams to liters(g).

Clear the Explanation text.
Click on the “Equation is Balanced” button again.
Change substance 2 mole quantity from 3 to .75. (Again.)
All the prior mole quantity adjustments have been made again, except that the product substances have been adjusted by the Process Yield, and substance 4 quantity has been calculated as liters(g) instead of grams.

Also, if this were a valid equation with a limited reaction, you could have entered the actual quantity of one reactant, done the quantity adjustments, and compared the quantity of the other reaction to the quantity calculated by the program adjustment. For example, suppose you had 9 grams of substance 1 and 25 grams of substance 2 and did the calculations. If the calculations showed that you need less than 25 grams of substance 2 to complete the reaction, then substance 1 would be the limiting reactant, and substance 2 would be the excess substance. Similarly, if you needed more than 25 grams of substance 2 to complete the reaction, than substance 2 would be the limiting reactant.

Molarity worksheet problem

The program can’t solve some problems directly; but it has the flexibility to help solve them.

Given the equation: 2 HCL(ag) + Na2O(ag) -> 2 NaCl(ag) + H2O(l).
HCl: 35.3 ml 0.500 Molarity reacts with Na2O: 21.0 ml.
How many grams of Na2O are in the solution?
What was the concentration of Na2O solution (in molar units)?

Set up equation: 2 HCL + Na2O -> 2 NaCl + H2O.
Set substance 1 type to compound; select HCL; mole qty = 2.
Since the correct mole quantity needs to be calculated, it can be done by setting the quantity and units of liters and the quantity and units of molarity, and using the special process which calculates moles from molarity and liters.
Set substance 1 “liter” qty to 0.0353, and select liters(l) The molarity will be calculated.
Select the minor process “molarity and liters to moles”.
Set molarity quantity to 0.500. The new mole quantity 0.01765 is calculated.
Set substance 2 type to compound; select Na2O. Mole quantity 1 is set automatically.
The “Equation is Balanced” adjustments do not work when a minor process has been selected; so the mole-to-mole calculation must be done manually.
Using the mole-to-more ratio for substance 1 to 2, manually calculate the mole quantity of substance 2 (0.008825) and enter it as the mole quantity.
Since the mole quantity was changed, the number of grams was recalculated as 0.547+ grams
Enter 0.021 ml quantity and select liters(l). The correct molarity of 0.42023 is calculated.
Note: Entering the rest of the equation has no effect on the calculations.
Set substance 4 type to compound; select NaCl, set mole qty is 2.
Set substance 5 type to compound; select H2O.

Other problems can’t be solved directly now. If there is sufficient demand and support, many problems are solvable either as default or as special processes. A major issue is integrating each solution into the program. For example, if the main units are liters(g) and a minor process has been selected which involves the main quantity or the number of moles, the program needs to gather data from at least 11 variables in order to make the correct calculation. A miniature version of this issue is the above problem with the molarity worksheet. The problem calculations aren’t unusual, but the sequence is.

Explanations

The program is not a black box. When you select a process, a substance, units, etc., or when you input a value, the program will create a text explaining what you selected or input, any equations and calculations that were performed, and the results; and display them in the "Explanations" text area. When the first selection or input is made, this initial explanation text will be deleted.
There are several reasons for having the explanations section. First, it is designed to provide the user with information about what the user selected or input and what the program did with that input. The purpose is to help the user understand enough about the program to have confidence in what it is doing. If there is an error in the program, the explanation will allow the user to copy evidence of the error and paste it into an email to get the error fixed.
A second reason for the explanation section is to help student users reinforce their learning by seeing what they selected, how the program used that selection and input, and the results, e.g., what equation was used and the calculated results.
Note that explanation text may be “copied and pasted,” but it can’t be “cut.”
When the explanation text gets too long, it can all be deleted by clicking on the “Clear Explanations Text” button near the top right corner of the top section of the form.