Chemistry Package

This package contains a wide variety of extensions to Mathematica™ that focus on entering and manipulating chemical species and reactions. New functionality will be added regularly to this package.

Download the Package

ChemistryPackage.wl (v. 2.0, 7/10/2019)

Note: This package also requires the Complex Symbols package.

Note: Before version 1.02, this package was called simply Chemistry. Unfortunately, v. 12.0 of Mathematica has a context called Chemistry, which caused problems with recognizing that the package needed to be loaded. I have therefore changed the name of the package.

How to install and load Mathematica™ packages

Functionality

The various functions of the package fall into the following categories:

The Chemistry Package: Detailed Contents

The palette that is automatically loaded contains several of the most-commonly needed structures: assigning species including states, setting up either symbol palettes or escape menu entry methods, reactions (also enterable using <Esc>rxn<Esc>), equilibria (also enterable using <Esc>eq<Esc>), and concentrations and pressures of species. The usage of these structures will be discussed in detail below. If you accidentally close the palette, you can recreate it by calling:

RecreateChemistryPalette;

Assigning and Manipulating Chemical Species

  • AssignSpecies[{{“label“,”state“},…}]
    • label is a string representation of the chemical formula or other identifier for the species
    • state is the physical state of the species. Generally this will be “s”, “l”, “g”, “aq”, or “sol”. Other state designations are allowed, but are not recognized by other functions in this package, and so behavior will be unpredictable
    • Creates the symbols for the species in the list and returns that list of symbols
  • AssignpSpecies[hydroniumSpecies,hydroxideSpecies]
    • hydroniumSpecies is a chemical species assigned by AssignSpecies
    • hydroxideSpecies is a chemical species assigned by AssignSpecies
    • Internally sets the two specified species as the ones to be referenced when calculating pH or pOH of a sample
  • State[species]
    • species is a chemical species assigned by AssignSpecies
    • Returns the physical state of that species
  • AssignMolarMasses[speciesList,molarMassList]
    • speciesList is a list of the species symbols, assigned by AssignSpecies, to which the molar masses are to be assigned
    • molarMassList is a list of the molar masses, in the same order as speciesList, to assign to those species
  • CalcMolarMass[“chemicalFormula“]
    • chemicalFormula is a string in standard chemistry notation representing a molecular formula. Typically, these are the same strings passed to AssignSpecies as labels
    • Returns the molar mass for the compound represented by chemicalFormula
  • AssignMolarMassesFromLabels[speciesList]
    • speciesList is a list of the species symbols, assigned by AssignSpecies, to which molar masses are to be calculated from their labels and assigned
  • MolarMass[species]
    • species is a chemical species assigned by AssignSpecies
    • Returns the molar mass of species as assigned by AssignMolarMasses or AssignMolarMassesFromLabels
  • AssignDensities[speciesList,densityList]
    • speciesList is a list of the species symbols, assigned by AssignSpecies, to which the densities are to be assigned
    • densityList is a list of the densities, in the same order as speciesList, to assign to those species
  • Density[species]
    • species is a chemical species assigned by AssignSpecies
    • Returns the density of the given species, as set by AssignDensities
  • concentrations[species]
    • species is a chemical species assigned by AssignSpecies
    • Returns the Mathematica™ symbol that represents the concentration of the given species
  • pressures[species]
    • species is a chemical species assigned by AssignSpecies
    • Returns the Mathematica™ symbol that represents the pressure of the given species

Reaction/Equilibrium Queries and Manipulations

  • Reactants[reaction]
    • reaction is a chemical reaction or equilibrium
    • Returns a list of the reactant species
  • Products[reaction]
    • reaction is a chemical reaction or equilibrium
    • Returns a list of the product species
  • Species[reaction]
    • reaction is a chemical reaction or equilibrium
    • Returns a combined list of the reactant and product species
  • ReactantStoichiometry[reaction]
    • reaction is a chemical reaction or equilibrium
    • Returns a list of the stoichiometric coefficients for the reactant species, in the same order as the list of species returned by Reactants[reaction]
  • ProductStoichiometry[reaction]
    • reaction is a chemical reaction or equilibrium
    • Returns a list of the stoichiometric coefficients for the product species, in the same order as the list of species returned by Products[reaction]
  • Coeff[reaction,species]
    • reaction is a chemical reaction or equilibrium
    • species is a chemical species assigned by AssignSpecies
    • Returns the net stoichiometric coefficient of the given species (product coefficient minus reactant coefficient)
  • StoicCalc[reaction,{startSpecies,startMass},targetSpecies]
    • reaction is a chemical reaction or equilibrium
    • startSpecies is a chemical species assigned by AssignSpecies that is present in reaction
    • startMass is the mass of the starting species to use in the stoichiometric calculation
    • targetSpecies is the species to determine the mass of via a stoichiometric calculation
    • Returns the mass of targetSpecies
  • ReduceReaction[reaction]
    • reaction is a chemical reaction or equilibrium
    • Returns a chemical reaction where species that are present on both sides of the given reaction have been removed
  • Keq[equilibrium]
    • equilibrium is the reaction equilibrium to return the equilibrium constant expression for
    • Returns the equilibrium constant expression in terms of concentrations of solutes and/or partial pressures of gases
  • EqConst[equilibrium]
    • equilibrium is the reaction equlibrium to return the equilibrium constant for
    • Returns the equilibrium constant value for the given equilibrium; this is the value that is placed over the equilibrium double-arrow

Sample Creation and Manipulation

  • CreateSample[{{species1,amount1},{species2,amount2},…}]
    • species1, species2, etc. are chemical species assigned by AssignSpecies
    • amount1, amount2, etc. are the amounts of each species to place in the sample. These values can be in a wide variety of unit types, including:
      • liquids: volume, mass (if density has been assigned), moles (if density and molar mass have been assigned). Internally, liquid amounts are stored as volume.
      • solutes: moles, concentration, mass (if molar mass has been assigned). Internally, solute amounts are stored as moles.
      • solids: moles, mass (if molar mass has been assigned). Internally, solid amounts are stored as moles.
      • gases: pressure, moles (based on conditions… see below), mass (if molar mass has been assigned, and based on conditions). Internally, gas amounts are stored as partial pressures.
    • Returns a sample structure that contains component information where amounts have been converted to a standard form (see above) and gas-phase conditions.
    • Options:
      • gasEffectivelyInfinite (default True): indicates that the gas-phase portion of the sample is effectively infinite (e.g., the sample is open to the atmosphere). This prevents equilibria involving gases in React from changing the partial pressures of the gases. A value of False indicates that there is a specified, finite amount of gas present, and that equilibria can change that amount within React.
      • T (default 298.15 K): the temperature of the gas. This is only used for converting partial pressures to and/or from number of moles; it has no effect on equilibrium constants, which must be entered for the temperature at which the equilibrium will be run.
      • V (default is the molar volume of an ideal gas at 298.15 K): the volume of the gas. This is only used for converting partial pressures to and/or from number of moles.
      • p (default n R T/V, a.k.a. the ideal gas law): Theoretically this is present to allow alternate equations of state to be used; however the package has not been tested with any option other than the default, and if your problem involves conditions where the ideal gas law doesn’t apply, then other assumptions are probably breaking down, so you should be handling the problem more manually.
  • Mix[sample1, sample2, …]
    • sample1, sample2, etc. are virtual samples created by CreateSample, Mix, or React
    • Returns a sample that combines all components in the source samples, and where the gas conditions are taken from the first sample in the list. Identical species amounts are added. For liquids, volumes are considered to be additive. For gases, partial pressures are considered to be additive. For solids and solutes, number of moles are considered to be additive.
  • Solutes[sample]
    • sample is a virtual sample created by CreateSample, Mix, or React
    • Returns a list of the species in the sample that have states “aq” or “sol”
  • Solvents[sample]
    • sample is a virtual sample created by CreateSample, Mix, or React
    • Returns a list of the species in the sample that have state “l”. For equilibria to work in React, there should only be one such species
  • Gases[sample]
    • sample is a virtual sample created by CreateSample, Mix, or React
    • Returns a list of the species in the sample that have state “g”
  • Solids[sample]
    • sample is a virtual sample created by CreateSample, Mix, or React
    • Returns a list of the species in the sample that have state “s”
  • Moles[sample,species]
    • sample is a virtual sample created by CreateSample, Mix, or React
    • species is a chemical species assigned by AssignSpecies
    • Returns the number of moles of species within sample. If species is a liquid, the density of species must have been assigned by AssignDensities, and the molar mass of species must have been assigned by AssignMolarMasses or AssignMolarMassesFromLabels. If species is a gas, the number of moles is calculated using the gas-phase conditions specified in sample
  • Mass[sample,species]
    • sample is a virtual sample created by CreateSample, Mix, or React
    • species is a chemical species assigned by AssignSpecies
    • Returns the mass of species within sample. If species is a liquid, the density of species must have been assigned by AssignDensities. If species is a gas, the number of moles is calculated using the gas-phase conditions specified in sample, and the molar mass of species must have been assigned by AssignMolarMasses or AssignMolarMassesFromLabels. if species is a solute or a solid, the molar mass of species must have been assigned
  • Pressure[sample,species]
    • sample is a virtual sample created by CreateSample, Mix, or React
    • species is a chemical species assigned by AssignSpecies
    • Returns the pressure of species within sample. This value is only meaningful if species is a gas
  • Concentration[sample,species]
    • sample is a virtual sample created by CreateSample, Mix, or React
    • species is a chemical species assigned by AssignSpecies
    • Returns the concentration of species within sample. The volume for the concentration calculation is determined from the total volume of the liquid components within species. The result is only meaningful if species is a solute.
  • pH[sample]
    • sample is a virtual sample created by CreateSample, Mix, or React
    • Returns the pH of the sample based on the concentration of the hydronium species assigned by AssignpSpecies. Be certain to call React if you want post-equilibration pH.
  • pOH[sample]
    • sample is a virtual sample created by CreateSample, Mix, or React
    • Returns the pOH of the sample based on the concentration of the hydroxide species assigned by AssignpSpecies. Be certain to call React if you want post-equilibration pOH.
  • React[sample,equilibriaList]
    • sample is a virtual sample created by CreateSample, Mix, or React
    • equilibriaList is a list of equilibria, including specified values for equilibrium constants
    • Returns a new sample that corresponds to the original sample that has been allowed to equilibrate. Equilibria involving solids have the possibility of no solid being present (e.g., a solubility product where the concentration is below saturation), in which case those equilibria are ignored. There can be at most a single liquid (solvent) phase, which is considered to be unchanging in amount to make concentration calculations tractable. Gases can be considered to be infinite (e.g., open to the atmosphere), in which case the partial pressures of the gases are fixed, or finite (e.g., in a sealed flask), in which case the partial pressures of the gases are allowed to change; this option is a sample property set by CreateSample.
    • Options:
      • WorkingPrecision (default 100): the number of digits to maintain during calculations. Because equilibria that nearly use up a species involve subtractions of numbers that may be extremely close to each other, this needs to be a large value.
      • ResultPrecision (default 10): the number of digits to report in ICE tables and in the resulting equilibrated sample. If you expect this system to model reality to better than 10 digits, you should probably rethink the problem.
      • ShowICE (default True): Whether to print all ICE tables
      • ICEEoRTypes (default “concentration”): The extent-of-reaction type to use for ICE tables. Allowed choices are “concentration”, “moles”, and “pressure.” A single value for this option specifies that choice for all ICE tables. A list of values (of the same length as equilibriaList) specifies the choice for each equilibrium reaction individually.

Acknowledgements

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, for helpful discussions and coding suggestions.

Leave a Reply

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

WordPress.com Logo

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

Google photo

You are commenting using your Google 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