StoichiometryMath (LibSBML Java API)

java.lang.Object
- org.sbml.libsbml.SBase
- - org.sbml.libsbml.StoichiometryMath

```
public class StoichiometryMath
extends SBase
```
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 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

Constructor Summary

Constructors
Constructor and Description
`StoichiometryMath(long level, long version)` Creates a new `StoichiometryMath` object using the given SBML `level` values.
`StoichiometryMath(SBMLNamespaces sbmlns)` Creates a new `StoichiometryMath` object using the given `SBMLNamespaces` object `sbmlns`.
`StoichiometryMath(StoichiometryMath orig)` Copy constructor creates a copy of this `StoichiometryMath`.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`StoichiometryMath`	`cloneObject()` Creates and returns a deep copy of this `StoichiometryMath` object.
`boolean`	`containsUndeclaredUnits()` Predicate returning `true` if the math expression of this `StoichiometryMath` object contains literal numbers or parameters with undeclared units.
`void`	`delete()` Explicitly deletes the underlying native object.
`UnitDefinition`	`getDerivedUnitDefinition()` Calculates and returns a `UnitDefinition` object that expresses the units returned by the math expression in this `StoichiometryMath` object.
`java.lang.String`	`getElementName()` Returns the XML element name of this object, which for `StoichiometryMath`, is always `'stoichiometryMath'.`
`ASTNode`	`getMath()` Retrieves the mathematical formula within this `StoichiometryMath` and return it as an AST.
`int`	`getTypeCode()` Returns the libSBML type code of this object instance.
`boolean`	`hasRequiredElements()` Predicate returning `true` if all the required elements for this `StoichiometryMath` object have been set.
`boolean`	`isSetMath()` Predicate to test whether the math for this `StoichiometryMath` object is set.
`int`	`removeFromParentAndDelete()` Finds this `StoichiometryMath`'s `SpeciesReference` parent and calls unsetStoichiometryMath() on it, indirectly deleting itself.
`void`	`renameSIdRefs(java.lang.String oldid, java.lang.String newid)` Replaces all uses of a given `SIdRef` type attribute value with another value.
`void`	`renameUnitSIdRefs(java.lang.String oldid, java.lang.String newid)` Replaces all uses of a given `UnitSIdRef` type attribute value with another value.
`int`	`setMath(ASTNode math)` Sets the 'math' expression of this `StoichiometryMath` instance to a copy of the given `ASTNode`.

Methods inherited from class org.sbml.libsbml.SBase
addCVTerm, addCVTerm, appendAnnotation, appendAnnotation, appendNotes, appendNotes, connectToChild, deleteDisabledPlugins, deleteDisabledPlugins, disablePackage, enablePackage, equals, getAncestorOfType, getAncestorOfType, getAnnotation, getAnnotationString, getColumn, getCVTerm, getCVTerms, getDisabledPlugin, getElementByMetaId, getElementBySId, getLevel, getLine, getListOfAllElements, getListOfAllElements, getListOfAllElementsFromPlugins, getListOfAllElementsFromPlugins, getMetaId, getModel, getModelHistory, getNamespaces, getNotes, getNotesString, getNumCVTerms, getNumDisabledPlugins, getNumPlugins, getPackageName, getPackageVersion, getParentSBMLObject, getPlugin, getPlugin, getPrefix, getResourceBiologicalQualifier, getResourceModelQualifier, getSBMLDocument, getSBOTerm, getSBOTermAsURL, getSBOTermID, getURI, getVersion, hashCode, hasValidLevelVersionNamespaceCombination, isPackageEnabled, isPackageURIEnabled, isPkgEnabled, isPkgURIEnabled, isSetAnnotation, isSetMetaId, isSetModelHistory, isSetNotes, isSetSBOTerm, isSetUserData, matchesRequiredSBMLNamespacesForAddition, matchesSBMLNamespaces, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, renameMetaIdRefs, replaceTopLevelAnnotationElement, replaceTopLevelAnnotationElement, setAnnotation, setAnnotation, setMetaId, setModelHistory, setNamespaces, setNotes, setNotes, setNotes, setSBOTerm, setSBOTerm, toSBML, toXMLNode, unsetAnnotation, unsetCVTerms, unsetId, unsetMetaId, unsetModelHistory, unsetName, unsetNotes, unsetSBOTerm, unsetUserData

Methods inherited from class java.lang.Object
getClass, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - StoichiometryMath
```
public StoichiometryMath(long level,
                         long version)
                  throws SBMLConstructorException
```
    Creates a new StoichiometryMath object using the given SBML level values.
    
    Parameters:
    
    level - a long integer, the SBML Level to assign to this StoichiometryMath
    
    version - a long integer, the SBML Version to assign to this StoichiometryMath
    
    Throws:
    
    SBMLConstructorException - Thrown if the given level and version combination are invalid or if this object is incompatible with the given level and version.
    
    "Note:"
    
    The StoichiometryMath construct exists only in SBML Level 2. It is an optional construct available for defining the stoichiometries of reactants and products in Reaction objects. Note that a different mechanism is used in SBML Level 3, where StoichiometryMath is not available. Please consult the top of this libSBML StoichiometryMath documentation for more information about the differences between SBML Level 2 and 3 with respect to stoichiometries.
    
    , Attempting to add an object to an SBMLDocument 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), 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
```
public StoichiometryMath(SBMLNamespaces sbmlns)
                  throws SBMLConstructorException
```
    Creates a new StoichiometryMath object using the given SBMLNamespaces object sbmlns.
    
    The SBMLNamespaces object encapsulates SBML Level/Version/namespaces information. It is used to communicate the SBML Level, Version, and (in Level 3) packages used in addition to SBML Level 3 Core. A common approach to using libSBML's SBMLNamespaces facilities is to create an SBMLNamespaces object somewhere in a program once, then hand that object as needed to object constructors that accept SBMLNamespaces as arguments.
    
    Parameters:
    
    sbmlns - an SBMLNamespaces object.
    
    Throws:
    
    SBMLConstructorException - Thrown if the given sbmlns is inconsistent or incompatible with this object.
    
    "Note:"
    
    The StoichiometryMath construct exists only in SBML Level 2. It is an optional construct available for defining the stoichiometries of reactants and products in Reaction objects. Note that a different mechanism is used in SBML Level 3, where StoichiometryMath is not available. Please consult the top of this libSBML StoichiometryMath documentation for more information about the differences between SBML Level 2 and 3 with respect to stoichiometries.
    
    , Attempting to add an object to an SBMLDocument 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), 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
```
public StoichiometryMath(StoichiometryMath orig)
                  throws SBMLConstructorException
```
    Copy constructor creates a copy of this StoichiometryMath.
    
    Parameters:
    
    orig - the object to copy.
    
    Throws:
    
    SBMLConstructorException
- Method Detail
  - delete
```
public void delete()
```
    Explicitly deletes the underlying native object.
    In general, application software will not need to call this method directly. The Java language binding for libSBML is implemented as a language wrapper that provides a Java interface to libSBML's underlying C++/C code. Some of the Java methods return objects that are linked to objects created not by Java code, but by C++ code. The Java objects wrapped around them will be deleted when the garbage collector invokes the corresponding C++ finalize() methods for the objects. The finalize() methods in turn call the StoichiometryMath.delete() method on the libSBML object.
    This method is exposed in case calling programs want to ensure that the underlying object is freed immediately, and not at some arbitrary time determined by the Java garbage collector. In normal usage, callers do not need to invoke StoichiometryMath.delete() themselves.
    
    Overrides:
    
    delete in class SBase
  - cloneObject
```
public StoichiometryMath cloneObject()
```
    Creates and returns a deep copy of this StoichiometryMath object.
    
    Overrides:
    
    cloneObject in class SBase
    
    Returns:
    
    the (deep) copy of this StoichiometryMath object.
  - getMath
```
public ASTNode getMath()
```
    Retrieves the mathematical formula within this StoichiometryMath and return it as an AST.
    
    Returns:
    
    the math of this StoichiometryMath.
    
    "Note:"
    
    The StoichiometryMath construct exists only in SBML Level 2. It is an optional construct available for defining the stoichiometries of reactants and products in Reaction objects. Note that a different mechanism is used in SBML Level 3, where StoichiometryMath is not available. Please consult the top of this libSBML StoichiometryMath documentation for more information about the differences between SBML Level 2 and 3 with respect to stoichiometries.
  - isSetMath
```
public boolean isSetMath()
```
    Predicate to test whether the math for this StoichiometryMath object is set.
    
    Returns:
    
    true if the formula (meaning the math subelement) of this StoichiometryMath is set, false otherwise.
    
    "Note:"
    
    The StoichiometryMath construct exists only in SBML Level 2. It is an optional construct available for defining the stoichiometries of reactants and products in Reaction objects. Note that a different mechanism is used in SBML Level 3, where StoichiometryMath is not available. Please consult the top of this libSBML StoichiometryMath documentation for more information about the differences between SBML Level 2 and 3 with respect to stoichiometries.
  - setMath
```
public int setMath(ASTNode math)
```
    Sets the 'math' expression of this StoichiometryMath instance to a copy of the given ASTNode.
    Parameters:
    
    math - an ASTNode representing a formula tree.
    
    Returns:
    integer value indicating success/failure of the function. The possible values returned by this function are:
    
    LIBSBML_OPERATION_SUCCESS
    LIBSBML_INVALID_OBJECT
    "Note:"
    
    The StoichiometryMath construct exists only in SBML Level 2. It is an optional construct available for defining the stoichiometries of reactants and products in Reaction objects. Note that a different mechanism is used in SBML Level 3, where StoichiometryMath is not available. Please consult the top of this libSBML StoichiometryMath documentation for more information about the differences between SBML Level 2 and 3 with respect to stoichiometries.
  - getDerivedUnitDefinition
```
public UnitDefinition getDerivedUnitDefinition()
```
    Calculates and returns a UnitDefinition object that expresses the units returned by the math expression in this StoichiometryMath object.
    The units are calculated based on the mathematical expression in the StoichiometryMath and the model quantities referenced by <ci> elements used within that expression. The StoichiometryMath.getDerivedUnitDefinition() method returns the calculated units.
    Note that the functionality that facilitates unit analysis depends on the model as a whole. Thus, in cases where the object has not been added to a model or the model itself is incomplete, unit analysis is not possible and this method will return null.
    
    Overrides:
    
    getDerivedUnitDefinition in class SBase
    
    Returns:
    
    a UnitDefinition that expresses the units of the math, or null if one cannot be constructed.
    
    See Also:
    
    StoichiometryMath.containsUndeclaredUnits()
    
    "Warning:"
    
    Note that it is possible the 'math' expression in the StoichiometryMath instance contains literal 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. When using this method, it is critical that callers also invoke the method StoichiometryMath.containsUndeclaredUnits() to determine whether this situation holds. Callers should take suitable action in those situations.
  - containsUndeclaredUnits
```
public boolean containsUndeclaredUnits()
```
    Predicate returning true if the math expression of this StoichiometryMath object contains literal numbers or parameters with undeclared units.
    The StoichiometryMath.getDerivedUnitDefinition() method returns what libSBML computes the units of the Stoichiometry to be, to the extent that libSBML can compute them. However, if the expression contains literal numbers or parameters with undeclared units, libSBML may not be able to compute the full units of the expression and will only return what it can compute. Callers should always use StoichiometryMath.containsUndeclaredUnits() when using StoichiometryMath.getDerivedUnitDefinition() to decide whether the returned units may be incomplete.
    
    Overrides:
    
    containsUndeclaredUnits in class SBase
    
    Returns:
    
    true if the math expression of this StoichiometryMath includes numbers/parameters with undeclared units, false otherwise.
    
    See Also:
    
    StoichiometryMath.getDerivedUnitDefinition()
    
    "Note:"
    
    A return value of true indicates that the UnitDefinition returned by StoichiometryMath.getDerivedUnitDefinition() may not accurately represent the units of the expression.
  - getTypeCode
```
public int getTypeCode()
```
    Returns the libSBML type code of this object instance.
    
    LibSBML attaches an identifying code to every kind of SBML object. These are integer constants known as SBML type codes. The names of all the codes begin with the characters SBML_. In the Java language interface for libSBML, the type codes are defined as static integer constants in the interface class libsbmlConstants. Note that different Level 3 package plug-ins may use overlapping type codes to identify the package to which a given object belongs, call the getPackageName() method on the object.
    
    Overrides:
    
    getTypeCode in class SBase
    
    Returns:
    
    the SBML type code for this object: SBML_STOICHIOMETRY_MATH (default).
    
    See Also:
    
    StoichiometryMath.getElementName(), SBase.getPackageName()
    
    "Warning:"
    
    The specific integer values of the possible type codes may be reused by different Level 3 package plug-ins. Thus, to identifiy the correct code, it is necessary to invoke both getTypeCode() and getPackageName().
  - getElementName
```
public java.lang.String getElementName()
```
    Returns the XML element name of this object, which for StoichiometryMath, is always 'stoichiometryMath'.
    
    Overrides:
    
    getElementName in class SBase
    
    Returns:
    
    the name of this element, i.e., 'stoichiometryMath'.
  - hasRequiredElements
```
public boolean hasRequiredElements()
```
    Predicate returning true if all the required elements for this StoichiometryMath object have been set.
    Overrides:
    
    hasRequiredElements in class SBase
    
    Returns:
    
    a boolean value indicating whether all the required elements for this object have been defined.
    
    "Note:"
    The required elements for a StoichiometryMath object are:
    
    'math'
  - removeFromParentAndDelete
```
public int removeFromParentAndDelete()
```
    Finds this StoichiometryMath's SpeciesReference parent and calls unsetStoichiometryMath() on it, indirectly deleting itself.
    Overridden from the SBase function since the parent is not a ListOf.
    Overrides:
    
    removeFromParentAndDelete in class SBase
    
    Returns:
    integer value indicating success/failure of the function. The possible values returned by this function are:
    
    LIBSBML_OPERATION_SUCCESS
    LIBSBML_OPERATION_FAILED
  - renameSIdRefs
```
public void renameSIdRefs(java.lang.String oldid,
                          java.lang.String newid)
```
    Replaces all uses of a given SIdRef type attribute value with another value.
    
    In SBML, object identifiers are of a data type called SId. In SBML Level 3, an explicit data type called SIdRef was introduced for attribute values that refer to SId values in previous Levels of SBML, this data type did not exist and attributes were simply described to as 'referring to an identifier', but the effective data type was the same as SIdRefin Level 3. These and other methods of libSBML refer to the type SIdRef for all Levels of SBML, even if the corresponding SBML specification did not explicitly name the data type.
    This method works by looking at all attributes and (if appropriate) mathematical formulas in MathML content, comparing the referenced identifiers to the value of oldid. If any matches are found, the matching values are replaced with newid. The method does not descend into child elements.
    
    Overrides:
    
    renameSIdRefs in class SBase
    
    Parameters:
    
    oldid - the old identifier
    
    newid - the new identifier
  - renameUnitSIdRefs
```
public void renameUnitSIdRefs(java.lang.String oldid,
                              java.lang.String newid)
```
    Replaces all uses of a given UnitSIdRef type attribute value with another value.
    
    In SBML, unit definitions have identifiers of type UnitSId. In SBML Level 3, an explicit data type called UnitSIdRef was introduced for attribute values that refer to UnitSId values in previous Levels of SBML, this data type did not exist and attributes were simply described to as 'referring to a unit identifier', but the effective data type was the same as UnitSIdRef in Level 3. These and other methods of libSBML refer to the type UnitSIdRef for all Levels of SBML, even if the corresponding SBML specification did not explicitly name the data type.
    This method works by looking at all unit identifier attribute values (including, if appropriate, inside mathematical formulas), comparing the referenced unit identifiers to the value of oldid. If any matches are found, the matching values are replaced with newid. The method does not descend into child elements.
    
    Overrides:
    
    renameUnitSIdRefs in class SBase
    
    Parameters:
    
    oldid - the old identifier
    
    newid - the new identifier

Class StoichiometryMath

Stoichiometries in SBML Level 2

Stoichiometries in SBML Level 3

Constructor Summary

Method Summary

Methods inherited from class org.sbml.libsbml.SBase

Methods inherited from class java.lang.Object

Constructor Detail

StoichiometryMath

StoichiometryMath

StoichiometryMath

Method Detail

delete

cloneObject

getMath

isSetMath

setMath

getDerivedUnitDefinition

containsUndeclaredUnits

getTypeCode

getElementName

hasRequiredElements

removeFromParentAndDelete

renameSIdRefs

renameUnitSIdRefs