org.sbml.libsbml
Class RateRule

java.lang.Object
  org.sbml.libsbml.SBase
      org.sbml.libsbml.Rule
          org.sbml.libsbml.RateRule

public class RateRule
extends Rule

Implementation of SBML's RateRule construct.

The rule type RateRule is derived from the parent class Rule. It is used to express equations that determine the rates of change of variables. The left-hand side (the 'variable' attribute) can refer to the identifier of a species, compartment, or parameter (but not a reaction). The entity identified must have its 'constant' attribute set to false. The effects of a RateRule are in general terms the same, but differ in the precise details depending on which variable is being set:

• In the case of a species, a RateRule sets the rate of change of the species' quantity (concentration or amount of substance) to the value determined by the formula in the 'math' subelement of the RateRule object. The overall units of the formula in 'math' should (in SBML Level 2 Version 4 and in SBML Level 3) or must (in SBML releases prior to Level 2 version 4) be equal to the unit of species quantity divided by the model-wide unit of time. Restrictions: There must not be both a RateRule 'variable' attribute and a SpeciesReference 'species' attribute having the same value, unless that species has its 'boundaryCondition' attribute is set to true. This means a rate rule cannot be defined for a species that is created or destroyed in a reaction, unless that species is defined as a boundary condition in the model.

• (For SBML Level 3 only) In the case of a species reference, a RateRule sets the rate of change of the stoichiometry of the referenced reactant or product to the value determined by the formula in 'math'. The unit associated with the value produced by the 'math' formula should be consistent with the unit 'dimensionless' divided by the model-wide unit of time.

• In the case of a compartment, a RateRule sets the rate of change of the compartment's size to the value determined by the formula in the 'math' subelement of the RateRule object. The overall units of the formula should (in SBML Level 2 Version 4 and in SBML Level 3) or must (in SBML releases prior to Level 2 version 4) be the units of the compartment's size divided by the model-wide unit of time.

• In the case of a parameter, a RateRule sets the rate of change of the parameter's value to that determined by the formula in the 'math' subelement of the RateRule object. The overall units of the formula should (in SBML Level 2 Version 4 and in SBML Level 3) or must (in SBML releases prior to Level 2 version 4) be the Parameter object's 'unit' attribute value divided by the model-wide unit of time.

In the context of a simulation, rate rules are in effect for simulation time t < 0. Please consult the relevant SBML specification for additional information about the semantics of assignments, rules, and entity values for simulation time t ≤ 0.

As mentioned in the description of AssignmentRule, a model must not contain more than one RateRule or AssignmentRule object having the same value of 'variable'; in other words, in the set of all assignment rules and rate rules in an SBML model, each variable appearing in the left-hand sides can only appear once. This simply follows from the fact that an indeterminate system would result if a model contained more than one assignment rule for the same variable or both an assignment rule and a rate rule for the same variable.

General summary of SBML rules

In SBML Level 3 as well as Level 2, rules are separated into three subclasses for the benefit of model analysis software. The three subclasses are based on the following three different possible functional forms (where x is a variable, f is some arbitrary function returning a numerical result, V is a vector of variables that does not include x, and W is a vector of variables that may include x):

Algebraic:	left-hand side is zero	0 = f(W)
Assignment:	left-hand side is a scalar:	x = f(V)
Rate:	left-hand side is a rate-of-change:	dx/dt = f(W)

In their general form given above, there is little to distinguish between assignment and algebraic rules. They are treated as separate cases for the following reasons:

• Assignment rules can simply be evaluated to calculate intermediate values for use in numerical methods. They are statements of equality that hold at all times. (For assignments that are only performed once, see InitialAssignment.)

• SBML needs to place restrictions on assignment rules, for example the restriction that assignment rules cannot contain algebraic loops.

• Some simulators do not contain numerical solvers capable of solving unconstrained algebraic equations, and providing more direct forms such as assignment rules may enable those simulators to process models they could not process if the same assignments were put in the form of general algebraic equations;

• Those simulators that can solve these algebraic equations make a distinction between the different categories listed above; and

• Some specialized numerical analyses of models may only be applicable to models that do not contain algebraic rules.

The approach taken to covering these cases in SBML is to define an abstract Rule structure containing a subelement, 'math', to hold the right-hand side expression, then to derive subtypes of Rule that add attributes to distinguish the cases of algebraic, assignment and rate rules. The 'math' subelement must contain a MathML expression defining the mathematical formula of the rule. This MathML formula must return a numerical value. The formula can be an arbitrary expression referencing the variables and other entities in an SBML model. Each of the three subclasses of Rule (AssignmentRule, AlgebraicRule, RateRule) inherit the the 'math' subelement and other fields from SBase. The AssignmentRule and RateRule classes add an additional attribute, 'variable'. See the definitions of AssignmentRule, AlgebraicRule and RateRule for details about the structure and interpretation of each one.

Additional restrictions on SBML rules

An important design goal of SBML rule semantics is to ensure that a model's simulation and analysis results will not be dependent on when or how often rules are evaluated. To achieve this, SBML needs to place two restrictions on rule use. The first concerns algebraic loops in the system of assignments in a model, and the second concerns overdetermined systems.

A model must not contain algebraic loops

The combined set of InitialAssignment, AssignmentRule and KineticLaw objects in a model constitute a set of assignment statements that should be considered as a whole. (A KineticLaw object is counted as an assignment because it assigns a value to the symbol contained in the 'id' attribute of the Reaction object in which it is defined.) This combined set of assignment statements must not contain algebraic loops—dependency chains between these statements must terminate. To put this more formally, consider a directed graph in which nodes are assignment statements and directed arcs exist for each occurrence of an SBML species, compartment or parameter symbol in an assignment statement's 'math' subelement. Let the directed arcs point from the statement assigning the symbol to the statements that contain the symbol in their 'math' subelement expressions. This graph must be acyclic. SBML does not specify when or how often rules should be evaluated. Eliminating algebraic loops ensures that assignment statements can be evaluated any number of times without the result of those evaluations changing. As an example, consider the set of equations x = x + 1, y = z + 200 and z = y + 100. If this set of equations were interpreted as a set of assignment statements, it would be invalid because the rule for x refers to x (exhibiting one type of loop), and the rule for y refers to z while the rule for z refers back to y (exhibiting another type of loop). Conversely, the following set of equations would constitute a valid set of assignment statements: x = 10, y = z + 200, and z = x + 100.

A model must not be overdetermined

An SBML model must not be overdetermined; that is, a model must not define more equations than there are unknowns in a model. An SBML model that does not contain AlgebraicRule structures cannot be overdetermined. LibSBML implements the static analysis procedure described in Appendix B of the SBML Level 3 Version 1 Core specification for assessing whether a model is overdetermined. (In summary, assessing whether a given continuous, deterministic, mathematical model is overdetermined does not require dynamic analysis; it can be done by analyzing the system of equations created from the model. One approach is to construct a bipartite graph in which one set of vertices represents the variables and the other the set of vertices represents the equations. Place edges between vertices such that variables in the system are linked to the equations that determine them. For algebraic equations, there will be edges between the equation and each variable occurring in the equation. For ordinary differential equations (such as those defined by rate rules or implied by the reaction rate definitions), there will be a single edge between the equation and the variable determined by that differential equation. A mathematical model is overdetermined if the maximal matchings of the bipartite graph contain disconnected vertexes representing equations. If one maximal matching has this property, then all the maximal matchings will have this property; i.e., it is only necessary to find one maximal matching.)

Rule types for SBML Level 1

SBML Level 1 uses a different scheme than SBML Level 2 and Level 3 for distinguishing rules; specifically, it uses an attribute whose value is drawn from an enumeration of 3 values. LibSBML supports this using methods that work with the enumeration values listed below.

• RULE_TYPE_RATE: Indicates the rule is a 'rate' rule.
• RULE_TYPE_SCALAR: Indicates the rule is a 'scalar' rule.
• RULE_TYPE_INVALID: Indicates the rule type is unknown or not yet set.

Constructor Summary

RateRule(long level, long version)
Creates a new RateRule using the given SBML level and version values.

RateRule(SBMLNamespaces sbmlns)
Creates a new RateRule using the given SBMLNamespaces object sbmlns.

Method Summary

RateRule	cloneObject() Creates and returns a deep copy of this Rule.
void	delete() Explicitly deletes the underlying native object.
boolean	hasRequiredAttributes() Predicate returning true if all the required attributes for this RateRule object have been set.
void	renameSIdRefs(String oldid, String newid) Renames all the SIdRef attributes on this element, including any found in MathML

Methods inherited from class org.sbml.libsbml.Rule

containsUndeclaredUnits, getDerivedUnitDefinition, getElementName, getFormula, getId, getL1TypeCode, getMath, getType, getTypeCode, getUnits, getVariable, hasRequiredElements, isAlgebraic, isAssignment, isCompartmentVolume, isParameter, isRate, isScalar, isSetFormula, isSetMath, isSetUnits, isSetVariable, isSpeciesConcentration, renameUnitSIdRefs, setFormula, setL1TypeCode, setMath, setUnits, setVariable, unsetUnits

Methods inherited from class org.sbml.libsbml.SBase

addCVTerm, addCVTerm, appendAnnotation, appendAnnotation, appendNotes, appendNotes, disablePackage, enablePackage, equals, getAncestorOfType, getAncestorOfType, getAnnotation, getAnnotationString, getColumn, getCVTerm, getCVTerms, getElementByMetaId, getElementBySId, getLevel, getLine, getListOfAllElements, getListOfAllElementsFromPlugins, getMetaId, getModel, getModelHistory, getNamespaces, getNotes, getNotesString, getNumCVTerms, getNumPlugins, getPackageName, getPackageVersion, getParentSBMLObject, getPlugin, getPlugin, getResourceBiologicalQualifier, getResourceModelQualifier, getSBMLDocument, getSBOTerm, getSBOTermAsURL, getSBOTermID, getVersion, hashCode, hasValidLevelVersionNamespaceCombination, isPackageEnabled, isPackageURIEnabled, isPkgEnabled, isPkgURIEnabled, isSetAnnotation, isSetMetaId, isSetModelHistory, isSetNotes, isSetSBOTerm, matchesRequiredSBMLNamespacesForAddition, matchesSBMLNamespaces, removeFromParentAndDelete, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, renameMetaIdRefs, replaceTopLevelAnnotationElement, replaceTopLevelAnnotationElement, setAnnotation, setAnnotation, setMetaId, setModelHistory, setNamespaces, setNotes, setNotes, setNotes, setSBOTerm, setSBOTerm, toSBML, unsetAnnotation, unsetCVTerms, unsetId, unsetMetaId, unsetModelHistory, unsetName, unsetNotes, unsetSBOTerm

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RateRule

public RateRule(long level,
                long version)
         throws SBMLConstructorException

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

Parameters:

level - a long integer, the SBML Level to assign to this RateRule

version - a long integer, the SBML Version to assign to this RateRule

Throws:

SBMLConstructorException - Thrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.

Note:

Upon the addition of a RateRule object to an SBMLDocument (e.g., using Model.addRule(Rule r), the SBML Level, SBML Version and XML namespace of the document override the values used when creating the RateRule object via this constructor. This is necessary to ensure that an SBML document is a consistent structure. Nevertheless, the ability to supply the values at the time of creation of a RateRule is an important aid to producing valid SBML. Knowledge of the intented SBML Level and Version determine whether it is valid to assign a particular value to an attribute, or whether it is valid to add an object to an existing SBMLDocument.

RateRule

public RateRule(SBMLNamespaces sbmlns)
         throws SBMLConstructorException

Creates a new RateRule 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 this class constructor is to create an SBMLNamespaces object somewhere in a program, once, then pass it to object constructors such as this one when needed.

Parameters:

sbmlns - an SBMLNamespaces object.

Throws:

SBMLConstructorException - Thrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.

Note:

Upon the addition of a RateRule object to an SBMLDocument (e.g., using Model.addRule(Rule r), the SBML XML namespace of the document overrides the value used when creating the RateRule object via this constructor. This is necessary to ensure that an SBML document is a consistent structure. Nevertheless, the ability to supply the values at the time of creation of a RateRule is an important aid to producing valid SBML. Knowledge of the intented SBML Level and Version determine whether it is valid to assign a particular value to an attribute, or whether it is valid to add an object to an existing SBMLDocument.

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 RateRule.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 RateRule.delete() themselves.

Overrides:

delete in class Rule

cloneObject

public RateRule cloneObject()

Creates and returns a deep copy of this Rule.

Overrides:

cloneObject in class Rule

Returns:

a (deep) copy of this Rule.

hasRequiredAttributes

public boolean hasRequiredAttributes()

Predicate returning true if all the required attributes for this RateRule object have been set.

Overrides:

hasRequiredAttributes in class Rule

Returns:

true if the required attributes have been set, false otherwise.

Note:

In SBML Levels 2–3, the only required attribute for a RateRule object is 'variable'. For Level 1, where the equivalent attribute is known by different names ('compartment', 'species', or 'name', depending on the type of object), there is an additional required attribute called 'formula'.

renameSIdRefs

public void renameSIdRefs(String oldid,
                          String newid)

Renames all the SIdRef attributes on this element, including any found in MathML

Overrides:

renameSIdRefs in class Rule

Parameters:

oldid - the old identifier

newid - the new identifier