Detailed Description

A reference to an SBML species in a reaction.

The Reaction_t structure provides a way to express which species act as reactants and which species act as products in a reaction. In a given reaction, references to those species acting as reactants and/or products are made using instances of SpeciesReference_t structures in a Reaction_t object's lists of reactants and products.

A species can occur more than once in the lists of reactants and products of a given Reaction_t instance. The effective stoichiometry for a species in a reaction is the sum of the stoichiometry values given on the SpeciesReference_t object in the list of products minus the sum of stoichiometry values given on the SpeciesReference_t objects in the list of reactants. A positive value indicates the species is effectively a product and a negative value indicates the species is effectively a reactant. SBML places no restrictions on the effective stoichiometry of a species in a reaction; for example, it can be zero. In the following SBML fragment, the two reactions have the same effective stoichiometry for all their species:

<reaction id="x">
    <listOfReactants>
        <speciesReference species="a"/>
        <speciesReference species="a"/>
        <speciesReference species="b"/>
    </listOfReactants>
    <listOfProducts>
        <speciesReference species="c"/>
        <speciesReference species="b"/>
    </listProducts>
</reaction>
<reaction id="y">
    <listOfReactants>
        <speciesReference species="a" stoichiometry="2"/>
    </listOfReactants>
    <listOfProducts>
        <speciesReference species="c"/>
    </listProducts>
</reaction>

The precise structure of SpeciesReference_t differs between SBML Level 2 and Level 3. We discuss the two variants in separate sections below.

SpeciesReference_t in SBML Level 2

The mandatory "species" attribute of SpeciesReference_t must have as its value the identifier of an existing species defined in the enclosing Model_t. The species is thereby designated as a reactant or product in the reaction. Which one it is (i.e., reactant or product) is indicated by whether the SpeciesReference_t appears in the Reaction_t's "reactant" or "product" lists.

Product and reactant stoichiometries can be specified using either "stoichiometry" or "stoichiometryMath" in a SpeciesReference_t object. The "stoichiometry" attribute is of type double and should contain values greater than 0 (false). 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 SpeciesReference_t instance defaults to 1.

For maximum interoperability, the "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 Reaction_t list of reactants, products and modifiers.

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 the parameter x:

<model>
    ...
    <listOfReactions>
        <reaction id="J1">
            <listOfReactants>
                <speciesReference species="X0">
                    <stoichiometryMath>
                        <math xmlns="http://www.w3.org/1998/Math/MathML">
                            <ci>x</ci>
                        </math>
                    </stoichiometryMath>
                </speciesReference>
            </listOfReactants>
            ...
        </reaction>
        ...
    </listOfReactions>
    ...
</model>

SpeciesReference_t in SBML Level 3

In Level 2's definition of a reaction, the stoichiometry attribute of a SpeciesReference_t is actually a combination of two factors, the standard biochemical stoichiometry and a conversion factor that may be needed to translate the units of the species quantity to the units of the reaction rate. Unfortunately, Level 2 offers no direct way of decoupling these two factors, or for explicitly indicating the units. The only way to do it in Level 2 is to use the StoichiometryMath_t object associated with SpeciesReferences, and to reference SBML Parameter_t objects from within the StoichiometryMath_t formula. This works because Parameter_t offers a way to attach units to a numerical value, but the solution is indirect and awkward for something that should be a simple matter. Moreover, the question of how to properly encode stoichiometries in SBML reactions has caused much confusion among implementors of SBML software.

SBML Level 3 approaches this problem differently. It (1) extends the the use of the SpeciesReference_t identifier to represent the value of the "stoichiometry" attribute, (2) makes the "stoichiometry" attribute optional, (3) removes StoichiometryMath_t, and (4) adds a new "constant" boolean attribute on SpeciesReference_t.

As in Level 2, the "stoichiometry" attribute is of type double and should contain values greater than zero (0). A missing "stoichiometry" implies that the stoichiometry is either unknown, or to be obtained from an external source, or determined by an InitialAssignment_t object or other SBML construct elsewhere in the model.

A species reference's stoichiometry is set by its "stoichiometry" attribute exactly once. If the SpeciesReference_t object's "constant" attribute has the value true, then the stoichiometry is fixed and cannot be changed except by an InitialAssignment_t object. These two methods of setting the stoichiometry (i.e., using "stoichiometry" directly, or using InitialAssignment_t) differ in that the "stoichiometry" attribute can only be set to a literal floating-point number, whereas InitialAssignment_t allows the value to be set using an arbitrary mathematical expression. (As an example, the approach could be used to set the stoichiometry to a rational number of the form p/q, where p and q are integers, something that is occasionally useful in the context of biochemical reaction networks.) If the species reference's "constant" attribute has the value false, the species reference's value may be overridden by an InitialAssignment_t or changed by AssignmentRule_t or AlgebraicRule_t, and in addition, for simulation time t > 0, it may also be changed by a RateRule_t or Event_t objects. (However, some of these constructs are mutually exclusive; see the SBML Level 3 Core specifiation for more details.) It is not an error to define "stoichiometry" on a species reference and also redefine the stoichiometry using an InitialAssignment_t, but the "stoichiometry" attribute in that case is ignored.

The value of the "id" attribute of a SpeciesReference_t can be used as the content of a <ci> element in MathML formulas elsewhere in the model. When the identifier appears in a MathML <ci> element, it represents the stoichiometry of the corresponding species in the reaction where the SpeciesReference_t object instance appears. More specifically, it represents the value of the "stoichiometry" attribute on the SpeciesReference_t object.

In SBML Level 3, the unit of measurement associated with the value of a species' stoichiometry is always considered to be dimensionless. This has the following implications:

When a species reference's identifier appears in mathematical formulas elsewhere in the model, the unit associated with that value is dimensionless.
The units of the "math" elements of AssignmentRule_t, InitialAssignment_t and EventAssignment_t objects setting the stoichiometry of the species reference should be dimensionless.
If a species reference's identifier is the subject of a RateRule_t, the unit associated with the RateRule_t object's value should be dimensionless/time, where time is the model-wide unit of time set on the Model_t object.

Examples:: createExampleSBML.c, printAnnotation.c, printNotes.c, printUnits.c, spec_example1.c, unsetAnnotation.c, and unsetNotes.c.

Public Member Functions
SpeciesReference_t *	SpeciesReference_clone (const SpeciesReference_t *sr)
	Creates and returns a deep copy of the given SpeciesReference_t structure. More...

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

SpeciesReference_t *	SpeciesReference_createModifier (unsigned int level, unsigned int version)
	Creates a new ModifierSpeciesReference_t (SpeciesReference_t) structure using the given SBMLNamespaces_t structure. More...

SpeciesReference_t *	SpeciesReference_createModifierWithNS (SBMLNamespaces_t *sbmlns)
	Creates a new ModifierSpeciesReference_t (SpeciesReference_t) structure using the given SBMLNamespaces_t structure. More...

StoichiometryMath_t *	SpeciesReference_createStoichiometryMath (SpeciesReference_t *sr)
	Creates a new, empty StoichiometryMath_t structure, adds it to the `sr` SpeciesReference_t, and returns it. More...

SpeciesReference_t *	SpeciesReference_createWithNS (SBMLNamespaces_t *sbmlns)
	Creates a new SpeciesReference_t structure using the given SBMLNamespaces_t structure. More...

void	SpeciesReference_free (SpeciesReference_t *sr)
	Frees the given SpeciesReference_t structure. More...

int	SpeciesReference_getConstant (const SpeciesReference_t *sr)
	Get the value of the "constant" attribute. More...

int	SpeciesReference_getDenominator (const SpeciesReference_t *sr)
	Get the value of the "denominator" attribute, for the case of a rational-numbered stoichiometry or a model in SBML Level 1. More...

const char *	SpeciesReference_getId (const SpeciesReference_t *sr)
	Get the value of the "id" attribute of the given SpeciesReference_t structure. More...

const char *	SpeciesReference_getName (const SpeciesReference_t *sr)
	Get the value of the "name" attribute of the given SpeciesReference_t structure. More...

const XMLNamespaces_t *	SpeciesReference_getNamespaces (SpeciesReference_t *sr)
	Returns a list of XMLNamespaces_t associated with this SpeciesReference_t structure. More...

const char *	SpeciesReference_getSpecies (const SpeciesReference_t *sr)
	Get the value of the "species" attribute of the given SpeciesReference_t structure. More...

double	SpeciesReference_getStoichiometry (const SpeciesReference_t *sr)
	Get the value of the "stoichiometry" attribute of the given SpeciesReference_t structure. More...

StoichiometryMath_t *	SpeciesReference_getStoichiometryMath (SpeciesReference_t *sr)
	Get the content of the "stoichiometryMath" subelement of the given SpeciesReference_t structure. More...

int	SpeciesReference_hasRequiredAttributes (SpeciesReference_t *sr)
	Predicate returning `1` (true) or `0` (false) depending on whether all the required attributes for this SpeciesReference_t structure have been set. More...

void	SpeciesReference_initDefaults (SpeciesReference_t *sr)
	Initializes the attributes of the given SpeciesReference_t structure to their defaults: More...

int	SpeciesReference_isModifier (const SpeciesReference_t *sr)
	Predicate returning `1` (true) or `0` (false) depending on whether the given SpeciesReference_t structure is a modifier. More...

int	SpeciesReference_isSetConstant (const SpeciesReference_t *sr)
	Predicate returning `1` (true) or `0` (false) depending on whether the "constant" attribute of the given SpeciesReference_t structure is set. More...

int	SpeciesReference_isSetId (const SpeciesReference_t *sr)
	Predicate returning `1` (true) or `0` (false) depending on whether the "id" attribute of the given SpeciesReference_t structure is set. More...

int	SpeciesReference_isSetName (const SpeciesReference_t *sr)
	Predicate returning `1` (true) or `0` (false) depending on whether the "name" attribute of the given SpeciesReference_t structure is set. More...

int	SpeciesReference_isSetSpecies (const SpeciesReference_t *sr)
	Predicate returning `1` (true) or `0` (false) depending on whether the "species" attribute of the given SpeciesReference_t structure is set. More...

int	SpeciesReference_isSetStoichiometry (const SpeciesReference_t *sr)
	Predicate returning `1` (true) or `0` (false) depending on whether the "stoichiometry" attribute of the given SpeciesReference_t structure is set. More...

int	SpeciesReference_isSetStoichiometryMath (const SpeciesReference_t *sr)
	Predicate returning `1` (true) or `0` (false) depending on whether the "stoichiometryMath" subelement of the given SpeciesReference_t structure is non-empty. More...

int	SpeciesReference_setConstant (SpeciesReference_t *sr, int value)
	Assign the "constant" attribute of a SpeciesReference_t structure. More...

int	SpeciesReference_setDenominator (SpeciesReference_t *sr, int value)
	Sets the value of the "denominator" attribute of the given SpeciesReference_t structure. More...

int	SpeciesReference_setId (SpeciesReference_t sr, const char sid)
	Sets the value of the "id" attribute of the given SpeciesReference_t structure. More...

int	SpeciesReference_setName (SpeciesReference_t sr, const char name)
	Sets the value of the "name" attribute of the given SpeciesReference_t structure. More...

int	SpeciesReference_setSpecies (SpeciesReference_t sr, const char sid)
	Sets the value of the "species" attribute of the given SpeciesReference_t structure. More...

int	SpeciesReference_setStoichiometry (SpeciesReference_t *sr, double value)
	Sets the value of the "stoichiometry" attribute of the given SpeciesReference_t structure. More...

int	SpeciesReference_setStoichiometryMath (SpeciesReference_t sr, const StoichiometryMath_t math)
	Sets the content of the "stoichiometryMath" subelement of the given SpeciesReference_t structure. More...

int	SpeciesReference_unsetConstant (SpeciesReference_t *sr)
	Unsets the value of the "constant" attribute of the given SpeciesReference_t structure. More...

int	SpeciesReference_unsetId (SpeciesReference_t *sr)
	Unsets the value of the "id" attribute of the given SpeciesReference_t structure. More...

int	SpeciesReference_unsetName (SpeciesReference_t *sr)
	Unsets the value of the "name" attribute of the given SpeciesReference_t structure. More...

int	SpeciesReference_unsetSpecies (SpeciesReference_t *sr)
	Unsets the value of the "species" attribute of the given SpeciesReference_t structure. More...

int	SpeciesReference_unsetStoichiometry (SpeciesReference_t *sr)
	Unsets the content of the "stoichiometry" attribute of the given SpeciesReference_t structure. More...

int	SpeciesReference_unsetStoichiometryMath (SpeciesReference_t *sr)
	Unsets the content of the "stoichiometryMath" subelement of the given SpeciesReference_t structure. More...

Member Function Documentation

SpeciesReference_t * SpeciesReference_clone ( const SpeciesReference_t * sr )

Creates and returns a deep copy of the given SpeciesReference_t structure.

Parameters

sr	the SpeciesReference_t structure to use.

Returns: a (deep) copy of this SpeciesReference_t.

SpeciesReference_t * SpeciesReference_create	(	unsigned int	level,
		unsigned int	version
	)

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

Parameters

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

Returns: a pointer to the newly created SpeciesReference_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.

SpeciesReference_t * SpeciesReference_createModifier	(	unsigned int	level,
		unsigned int	version
	)

Creates a new ModifierSpeciesReference_t (SpeciesReference_t) structure using the given SBMLNamespaces_t structure.

Parameters

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

Returns: a pointer to the newly created SpeciesReference_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.

SpeciesReference_t * SpeciesReference_createModifierWithNS ( SBMLNamespaces_t * sbmlns )

Creates a new ModifierSpeciesReference_t (SpeciesReference_t) structure using the given SBMLNamespaces_t structure.

Parameters

sbmlns SBMLNamespaces_t, a pointer to an SBMLNamespaces_t structure to assign to this modifier SpeciesReference_t.

Returns: a pointer to the newly created SpeciesReference_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 * SpeciesReference_createStoichiometryMath ( SpeciesReference_t * sr )

Creates a new, empty StoichiometryMath_t structure, adds it to the sr SpeciesReference_t, and returns it.

Returns: the newly created StoichiometryMath_t structure instance.

See also: Reaction_addReactant(); Reaction_addProduct()

Note: This function has no effect on SBML Level 1 or Level 3 SpeciesReference_t elements, neither of which have StoichiometryMath_t children.

SpeciesReference_t * SpeciesReference_createWithNS ( SBMLNamespaces_t * sbmlns )

Creates a new SpeciesReference_t structure using the given SBMLNamespaces_t structure.

Parameters

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

Returns: a pointer to the newly created SpeciesReference_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 SpeciesReference_free ( SpeciesReference_t * sr )

Frees the given SpeciesReference_t structure.

Parameters

sr	the SpeciesReference_t structure.

int SpeciesReference_getConstant ( const SpeciesReference_t * sr )

Get the value of the "constant" attribute.

Parameters

sr	the SpeciesReference_t structure to use.

Returns: the constant attribute of this SpeciesReference_t.

int SpeciesReference_getDenominator ( const SpeciesReference_t * sr )

Get the value of the "denominator" attribute, for the case of a rational-numbered stoichiometry or a model in SBML Level 1.

The "denominator" attribute is only actually written out in the case of an SBML Level 1 model. In SBML Level 2, rational-number stoichiometries are written as MathML elements in the "stoichiometryMath" subelement. However, as a convenience to users, libSBML allows the creation and manipulation of rational-number stoichiometries by supplying the numerator and denominator directly rather than having to manually create an ASTNode_t structure. LibSBML will write out the appropriate constructs (either a combination of "stoichiometry" and "denominator" in the case of SBML Level 1, or a "stoichiometryMath" subelement in the case of SBML Level 2). However, as the "stoichiometryMath" subelement was removed in SBML Level 3, automatic translation of the "denominator" attribute is no longer supported for that level.

This function returns 0 if the SpeciesReference_t structure is a Modifer (see SpeciesReference_isModifier()).

Parameters

sr	the SpeciesReference_t structure to use.

Returns: the denominator of this SpeciesReference_t.

const char * SpeciesReference_getId ( const SpeciesReference_t * sr )

Get the value of the "id" attribute of the given SpeciesReference_t structure.

Parameters

sr	the SpeciesReference_t structure to use.

Returns: the identifier of the SpeciesReference_t instance.

const char * SpeciesReference_getName ( const SpeciesReference_t * sr )

Get the value of the "name" attribute of the given SpeciesReference_t structure.

Parameters

sr	the SpeciesReference_t structure to use.

Returns: the name of the SpeciesReference_t instance.

const XMLNamespaces_t * SpeciesReference_getNamespaces ( SpeciesReference_t * sr )

Returns a list of XMLNamespaces_t associated with this SpeciesReference_t structure.

Parameters

sr	the SpeciesReference_t structure.

Returns: pointer to the XMLNamespaces_t structure associated with this structure.

const char * SpeciesReference_getSpecies ( const SpeciesReference_t * sr )

Get the value of the "species" attribute of the given SpeciesReference_t structure.

Parameters

sr	the SpeciesReference_t structure to use.

Returns: the "species" attribute value.

Examples:: printAnnotation.c, and printNotes.c.

double SpeciesReference_getStoichiometry ( const SpeciesReference_t * sr )

Get the value of the "stoichiometry" attribute of the given SpeciesReference_t structure.

This function returns 0 if the SpeciesReference_t structure is a Modifer (see SpeciesReference_isModifier()).

Parameters

sr	the SpeciesReference_t structure to use.

Returns: the "stoichiometry" attribute value.

StoichiometryMath_t * SpeciesReference_getStoichiometryMath ( SpeciesReference_t * sr )

Get the content of the "stoichiometryMath" subelement of the given SpeciesReference_t structure.

This function returns NULL if the SpeciesReference_t structure is a Modifer (see SpeciesReference_isModifier()).

Parameters

sr	the SpeciesReference_t structure to use.

Returns: the stoichiometryMath of this SpeciesReference_t.

Note: This function has no effect on SBML Level 1 or Level 3 SpeciesReference_t objects, neither of which have StoichiometryMath_t children.

Examples:: printUnits.c.

int SpeciesReference_hasRequiredAttributes ( SpeciesReference_t * sr )

Predicate returning 1 (true) or 0 (false) depending on whether all the required attributes for this SpeciesReference_t structure have been set.

The required attributes for a SpeciesReference_t structure are:

species
constant (in L3 only)

Parameters

sr	the SpeciesReference_t structure to check.

Returns: 1 (true) if all the required attributes for this object have been defined, 0 (false) otherwise.

void SpeciesReference_initDefaults ( SpeciesReference_t * sr )

Initializes the attributes of the given SpeciesReference_t structure to their defaults:

stoichiometry is set to 1
denominator is set to 1

This function has no effect if the SpeciesReference_t structure is a modifer (see SpeciesReference_isModifier()).

Parameters

sr	the SpeciesReference_t structure to use.

int SpeciesReference_isModifier ( const SpeciesReference_t * sr )

Predicate returning 1 (true) or 0 (false) depending on whether the given SpeciesReference_t structure is a modifier.

Parameters

sr	the SpeciesReference_t structure to use.

Returns: 1 (true) if this SpeciesReference_t represents a modifier species, 0 (false)if it is a plain SpeciesReference_t.

int SpeciesReference_isSetConstant ( const SpeciesReference_t * sr )

Predicate returning 1 (true) or 0 (false) depending on whether the "constant" attribute of the given SpeciesReference_t structure is set.

Parameters

sr	the SpeciesReference_t structure to use.

Returns: 1 (true) if the "constant" attribute of given SpeciesReference_t structure is set, 0 (false) otherwise.

int SpeciesReference_isSetId ( const SpeciesReference_t * sr )

Predicate returning 1 (true) or 0 (false) depending on whether the "id" attribute of the given SpeciesReference_t structure is set.

Parameters

sr	the SpeciesReference_t structure to use.

Returns: 1 (true) if the "id" attribute of given SpeciesReference_t structure is set, 0 (false) otherwise.

int SpeciesReference_isSetName ( const SpeciesReference_t * sr )

Predicate returning 1 (true) or 0 (false) depending on whether the "name" attribute of the given SpeciesReference_t structure is set.

Parameters

sr	the SpeciesReference_t structure to use.

Returns: 1 (true) if the "name" attribute of given SpeciesReference_t structure is set, 0 (false) otherwise.

int SpeciesReference_isSetSpecies ( const SpeciesReference_t * sr )

Predicate returning 1 (true) or 0 (false) depending on whether the "species" attribute of the given SpeciesReference_t structure is set.

Parameters

sr	the SpeciesReference_t structure to use.

Returns: 1 (true) if the "species" attribute of given SpeciesReference_t structure is set, 0 (false) otherwise.

int SpeciesReference_isSetStoichiometry ( const SpeciesReference_t * sr )

Predicate returning 1 (true) or 0 (false) depending on whether the "stoichiometry" attribute of the given SpeciesReference_t structure is set.

Parameters

sr	the SpeciesReference_t structure to use.

Returns: 1 (true) if the "stoichiometry" attribute of given SpeciesReference_t structure is set, 0 (false) otherwise.

int SpeciesReference_isSetStoichiometryMath ( const SpeciesReference_t * sr )

Predicate returning 1 (true) or 0 (false) depending on whether the "stoichiometryMath" subelement of the given SpeciesReference_t structure is non-empty.

This function returns false if the SpeciesReference_t structure is a Modifer (see SpeciesReference_isModifier()).

Parameters

sr	the SpeciesReference_t structure to use.

Returns: 1 (true) if the "stoichiometryMath" subelement has content, 0 (false) otherwise.

Examples:: printUnits.c.

int SpeciesReference_setConstant	(	SpeciesReference_t *	sr,
		int	value
	)

Assign the "constant" attribute of a SpeciesReference_t structure.

Parameters

sr	the SpeciesReference_t structure to set.
value	the value to assign as the "constant" attribute of the SpeciesReference_t, either `zero` for false or `nonzero` for true.

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:

Examples:: spec_example1.c.

int SpeciesReference_setDenominator	(	SpeciesReference_t *	sr,
		int	value
	)

Sets the value of the "denominator" attribute of the given SpeciesReference_t structure.

The "denominator" attribute is only actually written out in the case of an SBML Level 1 model. In SBML Level 2, rational-number stoichiometries are written as MathML elements in the "stoichiometryMath" subelement. However, as a convenience to users, libSBML allows the creation and manipulation of rational-number stoichiometries by supplying the numerator and denominator directly rather than having to manually create an ASTNode_t structure. LibSBML will write out the appropriate constructs (either a combination of "stoichiometry" and "denominator" in the case of SBML Level 1, or a "stoichiometryMath" subelement in the case of SBML Level 2). However, as the "stoichiometryMath" subelement was removed in SBML Level 3, automatic translation of the "denominator" attribute is no longer supported for that level.

This function has no effect if the SpeciesReference_t structure is a Modifer (see SpeciesReference_isModifier()).

Parameters

sr	the SpeciesReference_t structure to use.
value	the value to assign to the "denominator" attribute.

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:

int SpeciesReference_setId	(	SpeciesReference_t *	sr,
		const char *	sid
	)

Sets the value of the "id" attribute of the given SpeciesReference_t structure.

The string in sid will be copied.

Parameters

sr	the SpeciesReference_t structure to use.
sid	the identifier string that will be copied and assigned as the "id" attribute value.

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:

Note: Using this function with an sid of NULL is equivalent to unsetting the "id" attribute.

int SpeciesReference_setName	(	SpeciesReference_t *	sr,
		const char *	name
	)

Sets the value of the "name" attribute of the given SpeciesReference_t structure.

The string in sid will be copied.

Parameters

sr	the SpeciesReference_t structure to use.
name	the identifier string that will be copied and assigned as the "name" attribute value.

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:

Note: Using this function with the name set to NULL is equivalent to unsetting the "name" attribute.

int SpeciesReference_setSpecies	(	SpeciesReference_t *	sr,
		const char *	sid
	)

Sets the value of the "species" attribute of the given SpeciesReference_t structure.

The string in sid will be copied.

Parameters

sr	the SpeciesReference_t structure to use.
sid	the identifier string that will be copied and assigned as the "species" attribute value.

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:

Note: Using this function with an sid of NULL is equivalent to unsetting the "species" attribute.

Examples:: createExampleSBML.c, and spec_example1.c.

int SpeciesReference_setStoichiometry	(	SpeciesReference_t *	sr,
		double	value
	)

Sets the value of the "stoichiometry" attribute of the given SpeciesReference_t structure.

This function has no effect if the SpeciesReference_t structure is a Modifer (see SpeciesReference_isModifier()).

Parameters

sr	the SpeciesReference_t structure to use.
value	the value to assign to the "stoichiometry" attribute.

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:

Examples:: spec_example1.c.

int SpeciesReference_setStoichiometryMath	(	SpeciesReference_t *	sr,
		const StoichiometryMath_t *	math
	)

Sets the content of the "stoichiometryMath" subelement of the given SpeciesReference_t structure.

This function has no effect if the SpeciesReference_t structure is a Modifer (see SpeciesReference_isModifier()).

Parameters

sr	the SpeciesReference_t structure to use.
math	the StoichiometryMath_t structure to use in the given SpeciesReference_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:

Note: This function has no effect on SBML Level 1 or Level 3 SpeciesReference_t elements, neither of which have StoichiometryMath_t children.

int SpeciesReference_unsetConstant ( SpeciesReference_t * sr )

Unsets the value of the "constant" attribute of the given SpeciesReference_t structure.

Parameters

sr	the SpeciesReference_t structure to use.

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:

int SpeciesReference_unsetId ( SpeciesReference_t * sr )

Unsets the value of the "id" attribute of the given SpeciesReference_t structure.

Parameters

sr	the SpeciesReference_t structure to use.

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:

int SpeciesReference_unsetName ( SpeciesReference_t * sr )

Unsets the value of the "name" attribute of the given SpeciesReference_t structure.

Parameters

sr	the SpeciesReference_t structure to use.

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:

int SpeciesReference_unsetSpecies ( SpeciesReference_t * sr )

Unsets the value of the "species" attribute of the given SpeciesReference_t structure.

Parameters

sr	the SpeciesReference_t structure to use.

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:

int SpeciesReference_unsetStoichiometry ( SpeciesReference_t * sr )

Unsets the content of the "stoichiometry" attribute of the given SpeciesReference_t structure.

This function has no effect if the SpeciesReference_t structure is a Modifer (see SpeciesReference_isModifier()).

Parameters

sr	the SpeciesReference_t structure to use.

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:

int SpeciesReference_unsetStoichiometryMath ( SpeciesReference_t * sr )

Unsets the content of the "stoichiometryMath" subelement of the given SpeciesReference_t structure.

This function has no effect if the SpeciesReference_t structure is a Modifer (see SpeciesReference_isModifier()).

Parameters

sr	the SpeciesReference_t structure to use.

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:

Note: This function has no effect on SBML Level 1 or Level 3 SpeciesReference_t elements, neither of which have StoichiometryMath_t children.

Detailed Description

SpeciesReference_t in SBML Level 2

SpeciesReference_t in SBML Level 3

Public Member Functions

Member Function Documentation