stoiCreate {rodeo}

Stoichiometry Matrix from Reaction Equations

Description

Creates a stoichiometry matrix from a set of reaction equations.

Usage

stoiCreate(
  reactions,
  eval = FALSE,
  env = globalenv(),
  toRight = "_forward",
  toLeft = "_backward"
)

Arguments

reactions

A named vector of character strings, each representing a (chemical) reaction. See syntax details below.

eval

Logical. If FALSE (default), the returned matrix is of type character and any mathematical expressions are returned as text. If TRUE, an attempt is made to return a numeric matrix by evaluating the expression making use env.

env

Only relevant if eval is TRUE. Must be an environment or list supplying constants, functions, and operators needed to evaluate expressions in the generated matrix.

toRight

Only relevant for reversible reactions. The passed character string is appended to the name of the respective element of reactions to create a unique name for the forward reaction.

toLeft

Like toRight, but this is the suffix for the backward reaction.

Value

A matrix with the following properties:

• The number of columns equals the total number of components present in reactions. The components' names are used as column names.

• The number of rows equals the length of reactions plus the number of reversible reactions. Thus, a single row is created for each non-reversible reaction but two rows are created for reversible ones. The latter represent the forward and backward reaction (in that order). The row names are constructed from the names of reactions, making use of the suffixes toRight and toLeft in the case of reversible reactions.

• The matrix is filled with the stoichiometric factors extracted from reactions. Empty elements are set to zero.

• The type of the matrix (character or numeric) depends on the value of eval.

Note

The syntax rules for reaction equations are as follows (see examples):

• There must be a left hand side and a right hand side. Sides must be separated by one of the arrows '->', '<-', or '<->' with the latter indicating a reversible reaction.

• Names of component(s) must appear at each side of the reaction. These must be legal row/column names in R. If multiple components are consumed or produced, they must be separated by '+'.

• Any stoichiometric factors need to appear before the respective component name using '*' as the separating character. Stoichiometric factors being equal to unity can be omitted.

• A stoichiometric factor is treated as a mathematical expression. In common cases, it is just a numeric constant. However, the expression can also involve references to variables or functions. If such an expression contains math operators '*' or '+' it needs to be enclosed in parenthesis.

Author(s)

David Kneis [e-mail]

See Also

Use stoiCheck to validate the mass balance of the generated matrix.

Examples

# EXAMPLE 1: From https://en.wikipedia.org/wiki/Petersen_matrix (July 2016)
#
reactions <- c(
  formS=  "A + 2 * B -> S",
  equiES= "E + S <-> ES",
  decoES= "ES -> E + P"
)
stoi <- stoiCreate(reactions, eval=TRUE, toRight="_f", toLeft="_b")
print(stoi)

# EXAMPLE 2: Decomposition of organic matter (selected equations only)
#
# Eq. 1 and 2 are from Soetaert et al. (1996), Geochimica et Cosmochimica
# Acta, 60 (6), 1019-1040. 'OM' is organic matter. Constants 'nc' and 'pc'
# represent the nitrogen/carbon and phosphorus/carbon ratio, respectively.
reactions <- c(
  oxicDegrad= "OM + O2 -> CO2 + nc * NH3 + pc * H3PO4 + H2O",
  denitrific= "OM + 0.8*HNO3 -> CO2 + nc*NH3 + 0.4*N2 + pc*H3PO4 + 1.4*H2O",
  dissPhosp1= "H3PO4 <-> H + H2PO4",
  dissPhosp2= "H2PO4 <-> H + HPO4"
)
# Non-evaluated matrix
stoi <- stoiCreate(reactions, toRight="_f", toLeft="_b")
print(stoi)
# Evaluated matrix ('nc' and 'pc' according to Redfield ratio)
pars <- list(nc=16/106, pc=1/106)
stoi <- stoiCreate(reactions, eval=TRUE, env=pars, toRight="_f", toLeft="_b")
print(stoi)