libSBML C API  libSBML 5.8.0 C API
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
StoichiometryMath_t Class Reference

Detailed Description

Implementation of SBML Level 2's StoichiometryMath construct.

Stoichiometries in SBML Level 2

In SBML Level 2, product and reactant stoichiometries can be specified using either the "stoichiometry" attribute or a "stoichiometryMath" element in a SpeciesReference object. The "stoichiometry" attribute is of type double and should contain values greater than zero (0). The "stoichiometryMath" element is implemented as an element containing a MathML expression. These two are mutually exclusive; only one of "stoichiometry" or "stoichiometryMath" should be defined in a given SpeciesReference instance. When neither the attribute nor the element is present, the value of "stoichiometry" in the enclosing SpeciesReference instance defaults to 1.

For maximum interoperability, SpeciesReference's "stoichiometry" attribute should be used in preference to "stoichiometryMath" when a species' stoichiometry is a simple scalar number (integer or decimal). When the stoichiometry is a rational number, or when it is a more complicated formula, "stoichiometryMath" must be used. The MathML expression in "stoichiometryMath" may also refer to identifiers of entities in a model (except reaction identifiers). However, the only species identifiers that can be used in "stoichiometryMath" are those referenced in the enclosing Reaction's list of reactants, products and modifiers.

The "stoichiometry" attribute and the "stoichiometryMath" element, when either is used, is each interpreted as a factor applied to the reaction rate to produce the rate of change of the species identified by the "species" attribute in the enclosing SpeciesReference. This is the normal interpretation of a stoichiometry, but in SBML, one additional consideration has to be taken into account. The reaction rate, which is the result of the KineticLaw's "math" element, is always in the model's substance per time units. However, the rate of change of the species will involve the species' substance units (i.e., the units identified by the Species object's "substanceUnits" attribute), and these units may be different from the model's default substance units. If the units are different, the stoichiometry must incorporate a conversion factor for converting the model's substance units to the species' substance units. The conversion factor is assumed to be included in the scalar value of the "stoichiometry" attribute if "stoichiometry" is used. If instead "stoichiometryMath" is used, then the product of the model's "substance" units times the "stoichiometryMath" units must match the substance units of the species. Note that in either case, if the species' units and the model's default substance units are the same, the stoichiometry ends up being a dimensionless number and equivalent to the standard chemical stoichiometry found in textbooks. Examples and more explanations of this are given in the SBML specification.

The following is a simple example of a species reference for species "X0", with stoichiometry 2, in a list of reactants within a reaction having the identifier "J1":

<model>
    ...
    <listOfReactions>
        <reaction id="J1">
            <listOfReactants>
                <speciesReference species="X0" stoichiometry="2">
            </listOfReactants>
            ...
        </reaction>
        ...
    </listOfReactions>
    ...
</model>

The following is a more complex example of a species reference for species "X0", with a stoichiometry formula consisting of a rational number:

<model>
    ...
    <listOfReactions>
        <reaction id="J1">
            <listOfReactants>
                <speciesReference species="X0">
                    <stoichiometryMath>
                        <math xmlns="http://www.w3.org/1998/Math/MathML"> 
                            <cn type="rational"> 3 <sep/> 2 </cn>
                        </math>
                    </stoichiometryMath>
                </speciesReference>
            </listOfReactants>
            ...
        </reaction>
        ...
    </listOfReactions>
    ...
</model>

Additional discussions of stoichiometries and implications for species and reactions are included in the documentation of SpeciesReference class.

Stoichiometries in SBML Level 3

The StoichiometryMath construct is not defined in SBML Level 3 Version 1 Core. Instead, Level 3 defines the identifier of SpeciesReference objects as a stand-in for the stoichiometry of the reactant or product being referenced, and allows that identifier to be used elsewhere in SBML models, including (for example) InitialAssignment objects. This makes it possible to achieve the same effect as StoichiometryMath, but with other SBML objects. For instance, to produce a stoichiometry value that is a rational number, a model can use InitialAssignment to assign the identifier of a SpeciesReference object to a MathML expression evaluating to a rational number. This is analogous to the same way that, in Level 2, the model would use StoichiometryMath with a MathML expression evaluating to a rational number.

In SBML Level 2, the stoichiometry of a reactant or product is a combination of both a biochemical stoichiometry (meaning, the standard stoichiometry of a species in a reaction) and any necessary unit conversion factors. The introduction of an explicit attribute on the Species object for a conversion factor allows Level 3 to avoid having to overload the meaning of stoichiometry. In Level 3, the stoichiometry given by a SpeciesReference object in a reaction is a "proper" biochemical stoichiometry, meaning a dimensionless number free of unit conversions.

See Also
SpeciesReference
Reaction