USGS logo - Archived Page (no longer updated)

Chemistry Toy Box

Dr. Charles R. Denham, U.S. Geological Survey, Woods Hole, MA 02543
Send suggestions and comments to


We present a simple chemical algebra, implemented with some of the object-oriented features of Matlab-5. The main idea is to use the Periodic Table of the Elements to construct atoms from fermions (protons, electrons, and neutrons), and then to combine those atoms into compounds. Several Matlab operators are overloaded, in order to explore algebraic notation in elementary chemistry.


The "elements.m" function returns a "cell" or "struct" of the elements through #107, containing atomic symbol, number, weight, and common valences, one row per element. Because of a notational conflict between the Nitrogen +1 ion and Neptunium, the latter is given the symbol "Npt". Symbols for the "unnamed" elements (#104-107) are given in uppercase.


Classes known as "proton", "electron" and "neutron" are available for the assembly atoms. For example, helium can be constructed as:

   helium4 = 2*proton + 2*electron + 2*neutron
   helium3 = helium4 - neutron
The meaning of "2*proton" here is "two protons", not one proton with a super-charge of 2.


The "atom" constructor accepts several arguments, starting with the atomic symbol. Alternatively, one can add components to an "empty-atom" to construct an atom of any atomic symbol, number, weight, and valence. Thus, for common helium:

   He = atom('He', 2, 2, 2)
   He = atom('He') + 2*proton + 2*electron + 2*neutron
   He = atom + 'He' + 2*proton + 2*electron + 2*neutron
The "atoms.m" function creates neutral atoms, using the Periodic Table available from the "elements.m" function. By default, the atoms are placed in the caller's workspace, named by their atomic symbol. If an output argument is given, a "struct" is returned, whose fieldnames are the atomic symbols. Common ions can be returned as well, depending on the calling syntax.

The "atom" class can be interrogated with several methods: atomic "symbol", "number", "weight", and "valence".


Valence can be imposed on an atom in several ways. To derive bivalent (ferrous) iron from iron, use any of the following:

   Fepp = Fe - 2*electron
   Fepp = Fe(+2)
   Fepp = Fe + 2 

Our notation gives names to ions according to their valence, using "p" for "plus" and "m" for "minus". Only one conflict exists in the Periodic Table: Np could be +1 valence Nitrogen or neutral Neptunium. We have given Neptunium the symbol Npt to resolve the problem.

Note how the Matlab arithmetic operators are overloaded here to accomodate the fact that our objects are chemical entities, not numbers.


Compounds can be assembled from atoms, typically ions, using the "+" operator:

   water = 2*(H+1) + (O-2)
   common_table_salt = (Na+1) + (Cl-1)
   ammonia_ion = (N-3) + 4*(H+1)

Compounds are automatically created whenever an atom or compound is added to another atom or compound. Some common compounds are constructed in this fashion and placed in the caller's workspace by the "compounds.m" script.

Overloaded Operators

The "+", "-", "*", and "()" operators have been overloaded in "chem", for the purpose of assembling components and setting valence. These are handled by the "plus", "minus", "mtimes", and "subsref" methods.

   fermion = {proton | electron | neutron}
   fermions = fermion * count   % Default count = 1.

   atom = 'symbol' + fermions
   atom = atom {+ | -} fermions
   atoms = atom * count

   ion = atom {+ | -} electron
   ion = atom {+ | -} valence
   ion = atom({+ | -} valence)
   ions = ion * count 

   compound = {atoms | ions | compounds} + {atoms | ions | compounds}
   compounds = compound * count

Any of the Matlab symbolic operators can be overloaded easily, so the syntax of "chem" is not limited to the above.

The most difficult methods to overload are "subsref" for interpreting indices on the right-hand side of an assignment; "subsasgn" on the left; and "subsindex", to return a value for an object when it is used as an index. The first two methods process ".", "()", and "{}", which typically refer to parts of a "struct", a "double-precision array", and a "cell", respectively. When overloaded, these and other Matlab operators can be given whatever meaning the programmer desires.

Future Work

Whether the "Chemistry Toy Box" should be extended depends on the utility of simple algebraic notation for the representation of meaningful chemistry.


Here is chem_install.p for Matlab 5.2/5.3, an installer in the form of a Matlab P-code function. For Matlab 5.0/5.1, get chem_install.p50, then delete "50" from its name. Execute "chem_install" at the Matlab prompt to unbundle the software into a new or existing local folder called "chem". Then, add "chem" to your Matlab path, restart Matlab, and execute "chem_test".

lighthouse graphic