Detailed Description

Stochiometry expressions in SBML Level 2 reactions.

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_t 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_t instance. When neither the attribute nor the element is present, the value of "stoichiometry" in the enclosing SpeciesReference_t instance defaults to 1.

For maximum interoperability, SpeciesReference_t'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_t'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_t. 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_t'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_t 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_t class.

Stoichiometries in SBML Level 3

The StoichiometryMath_t construct is not defined in SBML Level 3. Instead, Level 3 defines the identifier of SpeciesReference_t 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_t objects. This makes it possible to achieve the same effect as StoichiometryMath_t, but with other SBML objects. For instance, to produce a stoichiometry value that is a rational number, a model can use InitialAssignment_t to assign the identifier of a SpeciesReference_t 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_t 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_t 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_t object in a reaction is a "proper" biochemical stoichiometry, meaning a dimensionless number free of unit conversions.

See also: SpeciesReference_t; Reaction_t

Examples:: printUnits.c.

Public Member Functions
StoichiometryMath_t *	StoichiometryMath_clone (const StoichiometryMath_t *t)

int	StoichiometryMath_containsUndeclaredUnits (StoichiometryMath_t *math)
	Predicate returning `1` (true) or `0` (false) depending on whether the math expression of this StoichiometryMath_t contains parameters/numbers with undeclared units. More...

StoichiometryMath_t *	StoichiometryMath_create (unsigned int level, unsigned int version)
	Creates a new StoichiometryMath_t structure using the given SBML `level` and `version` values. More...

StoichiometryMath_t *	StoichiometryMath_createWithNS (SBMLNamespaces_t *sbmlns)
	Creates a new StoichiometryMath_t structure using the given SBMLNamespaces_t structure. More...

void	StoichiometryMath_free (StoichiometryMath_t *t)
	Frees the given StoichiometryMath_t. More...

UnitDefinition_t *	StoichiometryMath_getDerivedUnitDefinition (StoichiometryMath_t *math)
	Calculates and returns a UnitDefinition_t that expresses the units returned by the math expression in this StoichiometryMath_t. More...

const ASTNode_t *	StoichiometryMath_getMath (const StoichiometryMath_t *t)

const XMLNamespaces_t *	StoichiometryMath_getNamespaces (StoichiometryMath_t *sm)
	Returns a list of XMLNamespaces_t associated with this StoichiometryMath_t structure. More...

int	StoichiometryMath_isSetMath (const StoichiometryMath_t *t)

int	StoichiometryMath_setMath (StoichiometryMath_t t, const ASTNode_t math)
	Sets the math of this StoichiometryMath_t to a copy of the given ASTNode_t. More...

Member Function Documentation

StoichiometryMath_t * StoichiometryMath_clone ( const StoichiometryMath_t * t )

Returns: a (deep) copy of this StoichiometryMath_t.

int StoichiometryMath_containsUndeclaredUnits ( StoichiometryMath_t * math )

Predicate returning 1 (true) or 0 (false) depending on whether the math expression of this StoichiometryMath_t contains parameters/numbers with undeclared units.

Parameters

math	the StoichiometryMath_t structure to check.

Returns: 1 (true) if the math expression of this StoichiometryMath_t includes parameters/numbers with undeclared units, 0 (false) otherwise.

Note: a return value of 1 (true) indicates that the UnitDefinition_t returned by StoichiometryMath_getDerivedUnitDefinition() may not accurately represent the units of the expression.

See also: StoichiometryMath_getDerivedUnitDefinition()

Examples:: printUnits.c.

StoichiometryMath_t * StoichiometryMath_create	(	unsigned int	level,
		unsigned int	version
	)

Creates a new StoichiometryMath_t structure using the given SBML level and version values.

Parameters

level	an unsigned int, the SBML Level to assign to this StoichiometryMath_t.
version	an unsigned int, the SBML Version to assign to this StoichiometryMath_t.

Returns: a pointer to the newly created StoichiometryMath_t structure.

Note: Attempting to add an object to an SBMLDocument_t having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument_t), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

StoichiometryMath_t * StoichiometryMath_createWithNS ( SBMLNamespaces_t * sbmlns )

Creates a new StoichiometryMath_t structure using the given SBMLNamespaces_t structure.

Parameters

sbmlns SBMLNamespaces_t, a pointer to an SBMLNamespaces_t structure to assign to this StoichiometryMath_t.

Returns: a pointer to the newly created StoichiometryMath_t structure.

Note: Attempting to add an object to an SBMLDocument_t having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument_t), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

void StoichiometryMath_free ( StoichiometryMath_t * t )

Frees the given StoichiometryMath_t.

UnitDefinition_t * StoichiometryMath_getDerivedUnitDefinition ( StoichiometryMath_t * math )

Calculates and returns a UnitDefinition_t that expresses the units returned by the math expression in this StoichiometryMath_t.

Parameters

math	the StoichiometryMath_t structure to check.

Returns: A UnitDefinition_t that expresses the units of the math

The units are calculated based on the mathematical expression in the StoichiometryMath_t and the model quantities referenced by <ci> elements used within that expression. The StoichiometryMath_getDerivedUnitDefinition() method returns the calculated units.

Warning: Note that it is possible the "math" expression in the StoichiometryMath_t contains pure numbers or parameters with undeclared units. In those cases, it is not possible to calculate the units of the overall expression without making assumptions. LibSBML does not make assumptions about the units, and StoichiometryMath_getDerivedUnitDefinition() only returns the units as far as it is able to determine them. For example, in an expression X + Y, if X has unambiguously-defined units and Y does not, it will return the units of X. It is important that callers also invoke the method StoichiometryMath_containsUndeclaredUnits() to determine whether this situation holds. Callers may wish to take suitable actions in those scenarios.

See also: containsUndeclaredUnits()

Examples:: printUnits.c.

const ASTNode_t * StoichiometryMath_getMath ( const StoichiometryMath_t * t )

Returns: the math of this StoichiometryMath_t as an ASTNode_t.

const XMLNamespaces_t * StoichiometryMath_getNamespaces ( StoichiometryMath_t * sm )

Returns a list of XMLNamespaces_t associated with this StoichiometryMath_t structure.

Parameters

sm	the StoichiometryMath_t structure.

Returns: pointer to the XMLNamespaces_t structure associated with this structure

int StoichiometryMath_isSetMath ( const StoichiometryMath_t * t )

Returns: 1 (true) if the math (or equivalently the formula) of this StoichiometryMath_t is set, 0 (false) otherwise.

int StoichiometryMath_setMath	(	StoichiometryMath_t *	t,
		const ASTNode_t *	math
	)

Sets the math of this StoichiometryMath_t to a copy of the given ASTNode_t.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Detailed Description

Stoichiometries in SBML Level 2

Stoichiometries in SBML Level 3

Public Member Functions

Member Function Documentation