stoichiometric_matrix

Julia

stoichiometric_matrix(rxn_sys::ReactionSystem)

stoichiometric_matrix(rxn_sys::ReactionSystem) -> Matrix{Float64}

Compute the net stoichiometric matrix (species × reactions).

The stoichiometric matrix S has dimensions (n_species × n_reactions) where:

• S[i,j] = net stoichiometry of species i in reaction j
• Net stoichiometry = products - reactants
• Positive values indicate production, negative values indicate consumption

Values are Float64 because v0.2.x allows fractional stoichiometries (e.g. ISOP+O3 → 0.87 CH2O). Integer-only systems produce a matrix whose entries happen to be exact integers stored as Float64.

Arguments

• rxn_sys::ReactionSystem: Input reaction system

Returns

• Matrix{Float64}: Stoichiometric matrix with dimensions (n_species, n_reactions)

Examples

# For reaction A + B -> 2C:
# S = [-1  # A consumed
#      -1  # B consumed
#       2] # C produced (2 molecules)

Source

Example (reactions)

doc = load_path(joinpath(FIXTURES, "ozone.esm"))
rs = doc.reaction_systems["Ozone"]
@assert rs isa ReactionSystem
@assert length(rs.reactions) == 2

odes = derive_odes(rs)  # a Model with one D(species)/dt per species
for eq in odes.equations
    println(to_ascii(eq))
end
@assert [to_ascii(eq) for eq in odes.equations] == [
    "D(O3)/Dt = -1 * k1 * NO * O3 + jNO2 * NO2",
    "D(NO)/Dt = -1 * k1 * NO * O3 + jNO2 * NO2",
    "D(NO2)/Dt = k1 * NO * O3 + -1 * jNO2 * NO2",
]

# Rows are species (O3, NO, NO2), columns are reactions (R1, R2).
@assert stoichiometric_matrix(rs) == [-1.0 1.0; -1.0 1.0; 1.0 -1.0]

From docs/api/examples/julia/reactions.jl

TypeScript

function stoichiometricMatrix(system: ReactionSystem): { matrix: number[][]; species: string[]; reactions: string[] }

Compute stoichiometric matrix from a reaction system

Returns the net stoichiometric matrix (species × reactions) where:

• Rows are species (in declaration order)
• Columns are reactions (in array order)
• Entry [i][j] = (stoichiometry as product) - (stoichiometry as substrate) for species i in reaction j
• Null substrates contribute 0 to substrate stoichiometry
• Null products contribute 0 to product stoichiometry

Parameters

• system — ReactionSystem to compute matrix from

Returns

Object containing matrix, species list, and reactions list

Source

Example (reactions)

const doc = loadPath(fixture('ozone.esm'))
const system = doc.reaction_systems!.Ozone
assert.ok(!('ref' in system)) // narrows away an unresolved `{ ref }` mount

// Mass-action kinetics: one ODE per species.
const odes = deriveOdes(system)
assert.deepEqual(odeStates(odes).sort(), ['NO', 'NO2', 'O3'])
assert.deepEqual(
  odes.equations.map((eq) => toAscii(eq)),
  [
    'D(O3)/Dt = -1 * k1 * NO * O3 + jNO2 * NO2',
    'D(NO)/Dt = -1 * k1 * NO * O3 + jNO2 * NO2',
    'D(NO2)/Dt = k1 * NO * O3 + -1 * jNO2 * NO2',
  ],
)

// Net stoichiometry: rows are species, columns are reactions.
const { matrix, species, reactions } = stoichiometricMatrix(system)
assert.deepEqual(species, ['O3', 'NO', 'NO2'])
assert.deepEqual(reactions, ['R1', 'R2'])
assert.deepEqual(matrix, [
  [-1, 1],
  [-1, 1],
  [1, -1],
])

From docs/api/examples/typescript/reactions.ts

Python

stoichiometric_matrix(system: ReactionSystem) -> np.ndarray

Compute the net stoichiometric matrix for a reaction system.

The stoichiometric matrix S is defined such that S[i,j] gives the net stoichiometric coefficient of species i in reaction j. Negative values indicate reactants (consumed), positive values indicate products (formed).

Parameters

• system (ReactionSystem) — ReactionSystem containing species and reactions

Returns

• np.ndarray — np.ndarray: Stoichiometric matrix with shape (n_species, n_reactions) where S[i,j] = net stoichiometric coefficient of species i in reaction j

Raises

• ValueError — If system is empty

Source

Example (stoichiometric_matrix)

# Rows are species (O3, NO, NO2) and columns are reactions (R1, R2).
net = earthsci_ast.stoichiometric_matrix(system)
assert np.array_equal(net, [[-1, 1], [-1, 1], [1, -1]])

consumed = earthsci_ast.substrate_matrix(system)
produced = earthsci_ast.product_matrix(system)
assert np.array_equal(produced - consumed, net)

From docs/api/examples/python/reactions.py

Rust

pub fn stoichiometric_matrix(system: &ReactionSystem) -> Vec<Vec<f64>>

Generate stoichiometric matrix from a reaction system

Creates a matrix where rows represent species and columns represent reactions. matrix[i][j] is the stoichiometric coefficient of species i in reaction j. Negative values indicate reactants, positive values indicate products.

Arguments

• system - The reaction system to analyze

Returns

• Vec<Vec<f64>> - Matrix with species as rows and reactions as columns

Source · Rust docs

Example (stoichiometric_matrix)

// Rows are species in declaration order (O3, NO, NO2), columns reactions
// (R1: NO + O3 -> NO2, R2: NO2 -> NO + O3).
let s = stoichiometric_matrix(system);
assert_eq!(s, [[-1.0, 1.0], [-1.0, 1.0], [1.0, -1.0]]);

From docs/api/examples/rust/reactions.rs

Go

func StoichiometricMatrix(system *ReactionSystem) [][]float64

StoichiometricMatrix returns the NET stoichiometric matrix of a reaction network: rows are species in declaration order (see the file header), columns are reactions in declaration order, and entry

is products − substrates for species i in reaction j. Negative means consumed, positive means produced.

Values are float64 because esm permits fractional coefficients (ISOP + O3 → 0.87 CH2O); an integer-only network yields exact integers stored as float64.

A species appearing more than once on the same side of one reaction has its coefficients SUMMED, which is why the entry accumulates rather than assigns. (That is a warning-level defect — duplicate_reaction_species — not an error, so the matrix must still have an answer for it.)

Source · Go docs

Example (reactions)

doc, err := esm.LoadPath(fixture("ozone.esm"))
if err != nil {
	log.Fatal(err)
}
system := doc.ReactionSystems["Ozone"]
odes, err := esm.DeriveODEs(&system)
if err != nil {
	log.Fatal(err)
}
for _, eq := range odes.Equations {
	fmt.Println(esm.ToASCII(eq.LHS), "=", esm.ToASCII(eq.RHS))
}

// One row per species, one column per reaction.
fmt.Println(esm.StoichiometricMatrix(&system))

From docs/api/examples/go/reactions_test.go