File Exchange

image thumbnail

Stoichiometry Tools

version 1.3 (73.3 KB) by

Parse chemical formulas for molecular weights and stoichiometric analysis.



View License

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.


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+','SO4-2'}).

*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:


* |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.


* |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.


* |[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.


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.

Comments and Ratings (2)


Marc (view profile)

Very nice set of tools. I am not sure what Bojan is looking for below but it seems to work just fine. There is an excellent tutorial and the examples are great. Thanks


Bojan (view profile)

After first look, it seems to work if number of species is sufficient. For too few species it should report error, but it doesn't. Example:
stoich({'Na3AlF6', 'HF', 'NaF', 'AlF3'})

Na3AlF6 <=> 3 NaF + AlF3



Update as Matlab Toolbox.


Fixed error in molweight, reordered published files so they are easier to follow in Matlab Central.


The functions have been cleaned up, the parser has been rewritten, sample homework problems added.

MATLAB Release
MATLAB 7.11 (R2010b)

Inspired by: Stoichiometry

Download apps, toolboxes, and other File Exchange content using Add-On Explorer in MATLAB.

» Watch video