StoichTools comprises a set of Matlab functions for doing stoichiometric analysis. These functions parse standard chemical notation for a variety of stoichiometric calculations including finding molecular weights, balancing reactions for atom and charge conservation, finding independent reactions, and displaying formulas in Hill notation. The functions account for both change and atomic balances so they can be used to balance ionic reactions and chemical half reactions.
StoichTools has extensive documentation including a set of worked homework problems demonstrating use of the functions. These functions were developed to support undergraduate teaching in chemical engineering. Comments are welcome and appreciated.
DATA TYPES
StoichTools works with two types of data:
*Chemical formulas* Each chemical formula is a string written in a nearly universal chemical notation. For example, H2SO4 represents Sulfuric Acid. Grouping is allowed (e.g., CH3(CH2)6CH3 for octane) witheither parentheses '()' or brackets '[]'. Charge is indicated by a trailing + or  followed by an optional number (e.g., Fe+3 or HSO4). Phase information may be included as a terminal (aq), (l), (g), or (s). Cell arrays can be used in most places to work with multiple formulas at one time (e.g., {'H2SO4','H+','SO42'}).
*Atomic representation*. Many calculations require knowledge of the charge, and of number of atoms of each type in a chemical species. This is maintained in a Matlab structure where r.C, for example, is the number of carbon atoms. The symbol after the dot is the standard 1 or 2
character symbol for an element. The symbol Q is reserved to indicated charge. A Matlab structure array is used to store multiple atomic reprentations in a single variable.
StoichTools provides functions for the following types of chemical calculations:
WORKING WITH CHEMICAL FORMULAS
* r = parse_formula(s) processes a chemical formula to produce an atomic representation. This function is mainly used by other functions to process chemical formulas.
* hillformula processes a chemical formula or atomic reprentation to produce a chemical formula in standard Hill notation. The Hill notation widely used to represent species in chemical databases, such as the NIST Chemistry Webbook.
CALCULATING MOLECULAR WEIGHTS
* mw = molweight(s) computes the molecular weights of chemical compounds. Input can be a chemical formula, a cell array of chemical formulas, or an array of atomic representations. If no output is indicated, then a table of molecular weights is printed.
STOICHIOMETRY
* [A,atoms,species] = atomic(s) constructs the atomic matrix for a set of chemical compounds. Element A(i,j) is the number of atoms{i} in species{j}. Inputs may be chemical formula, a cell array of chemical formulas, If there are ionic species, then a special atom 'Q' is indicates the charge of the species. If no output is indicated, then the atomic matrix is displayed in tabular form.
* V = stoich(s) computes the stoichiometric matrix for a set of chemical compounds. The input is a cell array of chemical formulas, or an array of atomic representations. The columns of V correspond to independent chemical reactions satisfying atomic and charge balances. Element V(j,k) is the stoichiometric coefficient for species j in reaction k. A negative value denotes a reactant, a positive value denotes a product. If no output is indicated, then disp_reaction is used to display all independent reactions.
* Vout = disp_reaction(V,s) If no output is indicated, then format and displays the chemical reactions denoted by stoichiometric matrix V and the array of species s. The species may be cell array of formulas or an array of atomic representations. If feasible, the coefficients are scaled to integers. It integer coefficients are too long, then either rational or floating point coefficients are displayed. If an output is indicated, then Vout is a stoichiometric matrix with rescaled coefficients, and the reactions are not displayed.
HOMEWORK PROBLEMS WITH SOLUTIONS
The StoichTools folder includes a number of worked homework problems. These are Matlab scripts with titles in the pattern HW_xx.m. Each script begins with a cell containing the problem statement. Subsequent cells demonstrate solution to the problem. The homework files can be viewed by using the Matlab publishing function.
