rodeo (version 0.8.2)

stoiCreate: 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"
)

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.

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.

Author

David Kneis

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)