Complex Symbols Package

As powerful as Mathematica™ is, it does not handle standard chemistry notation very well. The package described here smooths the way for using Mathematica™ to solve chemistry problems in chemistry-standard notation. It is very likely that this package could be used in other fields as well, so I have designed this package to be as general as possible. This package will be required for many of the other, more chemistry-specific packages found on this site.

Understanding Mathematica’s Limitations

Below are some examples of chemistry-standard notation that cause Mathematica™ some problems:

  • Chemical Formulas:
  • Thermodynamic Functions:
  • Rate Constants:
  • Isotopes:
  • Concentrations:

The reason for these problems stem from the assumptions that Mathematica™ makes about what notations mean. A superscript nearly always means an exponent, parentheses nearly always mean grouping to change the order of mathematical operations, square brackets are used to denote functional parameters, and subscripts are found only at the end of a symbol.

Examples illustrating these problems are shown to the right.

General Approach to Improve Notation

In all of these cases, we would like to have some mechanism to indicate to Mathematica™ that a particular formatted structure, which I will call the “label,” should be treated as a symbol. We would like to use these labels both in the input and output cells. There are several approaches to solving this problem for output cells, but input cells pose a particular problem, because hidden information designating the symbol as something to be treated differently needs to be included. The solution requires several somewhat-obscure features of Mathematica™, not all of which are well documented.

  • We need to represent our labels as “strings” (i.e., within quotation marks) in order to preserve the specific notation we specify without allowing Mathematica™ to parse the input.
  • We need to define a “style” that hides the display of the quotation marks for our labels, prevents Mathematica™ from coloring different parts of the labels differently, shrinking the spaces to zero in cases where the parser thinks multiplication is happening, and several other tweaks. This style is normally added to a stylesheet, but it is more convenient for it to be added programmaticly when the package is loaded.
  • We need to define a “notation,” using the external Mathematica™ Notation package, that associates the label, complete with style designation, with internal hidden symbols that Mathematica™ will use in its internal computations.
  • We need a mechanism to enter the label in a natural way into input cells that includes the style designation and notation association.

The ComplexSymbols Package: Contents

The ComplexSymbols package contains the following functions.

  • symbolList=AssignLables[list]
    • list is a list of string representations of the symbols to define.
    • This sets up the labels and the simple internal symbols that will be used to represent the labels.
    • The function returns the list of symbols.
  • AllSymbols[]
    • This function returns a list of all symbols currently defined within the ComplexSymbols package.
  • UnassignLabels[list]
    • list is a list of the symbols to undefine (i.e., not the string representations).
    • This un-does the AssignLabels action for a list of symbols.
  • UnassignAllLabels[]
    • This un-does the AssignLabels action for all symbols that are currently defined within the ComplexSymbols package.
  • SymbolPalette[“title“,list,width];
    • title is the heading for the palette.
    • list is a list of the symbols (i.e., not the string representations).
    • width specifies how many columns the list entries should be put in.
    • This generates a palette with one entry for each symbol. Depending on your preferred entry style, you should probably pick one of SymbolPalette or EscMenu to use.
  • EscMenu[“shortcut“,”title“,”list];
    • shortcut is the keystroke sequence to enter between <esc> key presses to bring up the menu. Ensure that you do not overwrite an existing keystroke sequence that you may need.
    • title is the title of the menu.
    • list is the list of the symbols to be included in the menu (i.e., not the string representations).
    • This associates a menu-entry method with an <esc> sequence.

Usage Examples

We will start by loading the ComplexSymbols package and assigning labels for the problematic example terms described above.

The symbols in the returned list can be copied-and-pasted for use as standard Mathematica™ symbols:

Each of these symbols is represented internally by a simple symbol name, although in practice you should never need to use that name:

More conveniently, these symbols can be grouped into a Mathematica™ palette to ease entry:

If you prefer keyboard entry to mouse-based selection of symbols from a palette, you can instead (or in addition) create an <Esc> alias menu, which responds to both keyboard arrow keys and mouse selection:

If you ever forget which symbols have been defined, you can access them using the AllSymbols function. You can remove specific symbols using UnassignLabels. And you can remove all of the symbols using UnassignAllLabels.

Strategies for Use

This system allows you to have multiple lists of label/symbol assignments. So you could have a separate list (and a separate palette and/or input alias menu) for different reactions, for species vs. rate constants, etc. The descriptions of other packages on this site will demonstrate some chemistry-specific applications in detail.


Funding to develop this package was provided by the National Science Foundation award CHE-1522036, “CAREER: Aqueous Fullerene Colloids.” I am also indebted to members of the Mathematica Stack Exchange community, especially Carl Woll, and b3m2a1, for helpful discussions and coding suggestions.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s