public class RateRule extends Rule
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:
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.
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.
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.
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.
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:
InitialAssignment
.)
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.
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.
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&mdashdependency
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.
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.)
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 and Description |
---|
RateRule(long level,
long version)
|
RateRule(SBMLNamespaces sbmlns)
|
Modifier and Type | Method and Description |
---|---|
RateRule |
cloneObject()
Creates and returns a deep copy of this
RateRule object. |
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)
Replaces all uses of a given
SIdRef type attribute value with another
value. |
containsUndeclaredUnits, getDerivedUnitDefinition, getElementName, getFormula, 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, unsetVariable
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, removeFromParentAndDelete, 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
public RateRule(long level, long version) throws SBMLConstructorException
level
- a long integer, the SBML Level to assign to this RateRule
version
- a long integer, the SBML Version to assign to this
RateRule
SBMLConstructorException
- Thrown if the given level
and version
combination are invalid
or if this object is incompatible with the given level and version.
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.public RateRule(SBMLNamespaces sbmlns) throws SBMLConstructorException
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 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.
sbmlns
- an SBMLNamespaces
object.
SBMLConstructorException
- Thrown if the given sbmlns
is inconsistent or incompatible
with this object.
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.public void delete()
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.
public RateRule cloneObject()
RateRule
object.
cloneObject
 in class Rule
RateRule
object.public boolean hasRequiredAttributes()
true
if
all the required attributes for this RateRule
object
have been set.
In SBML Levels 2&ndash3, 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'.
hasRequiredAttributes
 in class Rule
true
if the required attributes have been set, false
otherwise.public void renameSIdRefs(String oldid, 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 SIdRef
in 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.
renameSIdRefs
 in class Rule
oldid
- the old identifiernewid
- the new identifier