public class Rule extends SBase
In SBML, rules provide additional ways to define the values of
variables in a model, their relationships, and the dynamical behaviors
of those variables. They enable encoding relationships that cannot be
expressed using Reaction
nor InitialAssignment
objects alone.
The libSBML implementation of rules mirrors the SBML Level 3
Version 1 Core definition (which is in turn is very similar to the
Level 2 Version 4 definition), with Rule
being the parent
class of three subclasses as explained below. The Rule
class itself
cannot be instantiated by user programs and has no constructor only the
subclasses AssignmentRule
, AlgebraicRule
and RateRule
can be
instantiated directly.
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) |
InitialAssignment
.)
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.
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.
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 |
---|
Rule(Rule orig)
Copy constructor creates a copy of this
Rule . |
Modifier and Type | Method and Description |
---|---|
Rule |
cloneObject()
Creates and returns a deep copy of this
Rule . |
boolean |
containsUndeclaredUnits()
Predicate returning
true if
the math expression of this Rule contains
parameters/numbers with undeclared units. |
void |
delete()
Explicitly deletes the underlying native object.
|
UnitDefinition |
getDerivedUnitDefinition()
Calculates and returns a
UnitDefinition that expresses the units of
measurement assumed for the 'math' expression of this Rule . |
String |
getElementName()
Returns the XML element name of this object
|
String |
getFormula()
Returns the mathematical expression of this
Rule in text-string form. |
String |
getId()
Renames all the UnitSIdRef attributes on this element
|
int |
getL1TypeCode()
Returns the SBML Level 1 type code for this
Rule object. |
ASTNode |
getMath()
|
int |
getType()
Get the type of rule this is.
|
int |
getTypeCode()
Returns the libSBML type code for this SBML object.
|
String |
getUnits()
Returns the units for the
mathematical formula of this
Rule . |
String |
getVariable()
Get the value of the 'variable' attribute of this
Rule object. |
boolean |
hasRequiredAttributes()
Predicate returning
true if all the
required attributes for this Rule object have been set. |
boolean |
hasRequiredElements()
Predicate returning
true if all the
required elements for this Rule object have been set. |
boolean |
isAlgebraic()
|
boolean |
isAssignment()
|
boolean |
isCompartmentVolume()
Predicate returning
true if this Rule is an CompartmentVolumeRule
or equivalent. |
boolean |
isParameter()
Predicate returning
true if this Rule is an ParameterRule or
equivalent. |
boolean |
isRate()
|
boolean |
isScalar()
Predicate returning
true if this Rule
is an AssignmentRule (SBML Levels 2&ndash3) or has a 'type'
attribute value of 'scalar' (SBML Level 1). |
boolean |
isSetFormula()
Predicate returning
true if this
Rule 's mathematical expression is set. |
boolean |
isSetMath()
Predicate returning
true if this
Rule 's mathematical expression is set. |
boolean |
isSetUnits()
Predicate returning
true
if this Rule 's 'units' attribute is set. |
boolean |
isSetVariable()
Predicate returning
true if this
Rule 's 'variable' attribute is set. |
boolean |
isSpeciesConcentration()
Predicate returning
true if this Rule is a
SpeciesConcentrationRule or equivalent. |
void |
renameSIdRefs(String oldid,
String newid)
Renames all the SIdRef attributes on this element, including any found in MathML
|
void |
renameUnitSIdRefs(String oldid,
String newid)
Renames all the UnitSIdRef attributes on this element
|
int |
setFormula(String formula)
Sets the 'math' subelement of this
Rule to an expression in
text-string form. |
int |
setL1TypeCode(int type)
Sets the SBML Level 1 type code for this
Rule . |
int |
setMath(ASTNode math)
|
int |
setUnits(String sname)
Sets the units for this
Rule . |
int |
setVariable(String sid)
Sets the 'variable' attribute value of this
Rule object. |
int |
unsetUnits()
Unsets the 'units' for this
Rule . |
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, 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
public Rule(Rule orig)
Rule
.
orig
- the object to copy.
SBMLConstructorException
- Thrown if the argument orig
is null.
public Rule cloneObject()
Rule
.
cloneObject
 in class SBase
Rule
.public boolean containsUndeclaredUnits()
true
if
the math expression of this Rule
contains
parameters/numbers with undeclared units.
true
if the math expression of this Rule
includes parameters/numbers
with undeclared units, false
otherwise.
Rule.getDerivedUnitDefinition()
true
indicates that the UnitDefinition
returned by getDerivedUnitDefinition() may not accurately represent
the units of the expression.
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 Rule.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 Rule.delete()
themselves.
public UnitDefinition getDerivedUnitDefinition()
UnitDefinition
that expresses the units of
measurement assumed for the 'math' expression of this Rule
.
The units are calculated based on the mathematical expression in the
Rule
and the model quantities referenced by <ci>
elements used within that expression. The 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.
UnitDefinition
that expresses the units of the math
expression of this Rule
, or null
if one cannot be constructed.
Rule.containsUndeclaredUnits()
Rule
contains pure numbers or parameters with undeclared units. In those
cases, it is not possible to calculate the units of the overall
expression without making assumptions. LibSBML does not make
assumptions about the units, and getDerivedUnitDefinition() only
returns the units as far as it is able to determine them. For
example, in an expression X + Y, if X has
unambiguously-defined units and Y does not, it will return
the units of X. It is important that callers also
invoke the method
Rule.containsUndeclaredUnits()
to determine whether this situation holds. Callers may
wish to take suitable actions in those scenarios.
public String getElementName()
The returned value can be any of a number of different strings,
depending on the SBML Level in use and the kind of Rule
object this
is. The rules as of libSBML version 5.8.0
are the following:
'rateRule'
'assignmentRule'
'algebraicRule'
'specieConcentrationRule'
'speciesConcentrationRule'
'compartmentVolumeRule'
'parameterRule'
'unknownRule'
Beware that the last ('unknownRule'
) is not a valid SBML element
name.
getElementName
 in class SBase
public String getFormula()
Rule
in text-string form.
The text string is produced by
libsbml.formulaToString()
please consult
the documentation for that function to find out more about the format
of the text-string formula.
Rule
.
Rule.getMath()
public String getId()
getId
 in class SBase
SBase.isSetMetaId()
,
SBase.setMetaId(String metaid)
public int getL1TypeCode()
Rule
object.
This method only applies to SBML Level 1 model objects. If this
is not an SBML Level 1 rule object, this method will return SBML_UNKNOWN
.
Rule
(namely, SBML_COMPARTMENT_VOLUME_RULE
, SBML_PARAMETER_RULE
, SBML_SPECIES_CONCENTRATION_RULE
, or SBML_UNKNOWN
).public ASTNode getMath()
ASTNode
, the value of the 'math' subelement of this Rule
.
Rule.getFormula()
public int getType()
Rule
. The value
will be either RULE_TYPE_RATE
or RULE_TYPE_SCALAR
.
Rule
objects is present only in SBML
Level 1. In SBML Level 2 and later, the type has been
replaced by subclassing the Rule
object.public int getTypeCode()
LibSBML attaches an identifying code to every
kind of SBML object. These are known as SBML type codes. In
other languages, the set of type codes is stored in an enumeration in
the Java language interface for libSBML, the type codes are defined as
static integer constants in the interface class libsbmlConstants
. The names of the type codes all begin with the
characters SBML_.
getTypeCode
 in class SBase
SBML_UNKNOWN
(default).
Rule.getElementName()
public String getUnits()
Rule
.
Rule
.
public String getVariable()
Rule
object.
In SBML Level 1, the different rule types each have a different
name for the attribute holding the reference to the object
constituting the left-hand side of the rule. (E.g., for
SBML Level 1's SpeciesConcentrationRule the attribute is 'species', for
CompartmentVolumeRule it is 'compartment', etc.) In SBML
Levels 2 and 3, the only two types of Rule
objects with a
left-hand side object reference are AssignmentRule
and RateRule
, and
both of them use the same name for attribute: 'variable'. In order to
make it easier for application developers to work with all Levels of
SBML, libSBML uses a uniform name for all of such attributes, and it
is 'variable', regardless of whether Level 1 rules or
Level 2&ndash3 rules are being used.
Rule
, or null
if this object is an AlgebraicRule
object.public boolean hasRequiredAttributes()
true
if all the
required attributes for this Rule
object have been set.
The required attributes for a Rule
object depend on the type of Rule
it is. For AssignmentRule
and RateRule
objects (and SBML
Level 1's SpeciesConcentrationRule, CompartmentVolumeRule, and
ParameterRule objects), the required attribute is 'variable' for
AlgebraicRule
objects, there is no required attribute.
hasRequiredAttributes
 in class SBase
public boolean hasRequiredElements()
true
if all the
required elements for this Rule
object have been set.
The only required element for a Rule
object is the 'math' subelement.
hasRequiredElements
 in class SBase
public boolean isAlgebraic()
true
if this Rule
is an AlgebraicRule
, false
otherwise.public boolean isAssignment()
true
if this Rule
is an AssignmentRule
, false
otherwise.public boolean isCompartmentVolume()
true
if this Rule
is an CompartmentVolumeRule
or equivalent.
This libSBML method works for SBML Level 1 models (where there is
such a thing as an explicit CompartmentVolumeRule), as well as other Levels of
SBML. For Levels above Level 1, this method checks the symbol
being affected by the rule, and returns true
if the symbol is the
identifier of a Compartment
object defined in the model.
true
if this Rule
is a CompartmentVolumeRule, false
otherwise.public boolean isParameter()
true
if this Rule
is an ParameterRule or
equivalent.
This libSBML method works for SBML Level 1 models (where there is
such a thing as an explicit ParameterRule), as well as other Levels of
SBML. For Levels above Level 1, this method checks the symbol
being affected by the rule, and returns true
if the symbol is the
identifier of a Parameter
object defined in the model.
true
if this Rule
is a ParameterRule, false
otherwise.public boolean isRate()
public boolean isScalar()
true
if this Rule
is an AssignmentRule
(SBML Levels 2&ndash3) or has a 'type'
attribute value of 'scalar'
(SBML Level 1).
true
if this Rule
is an AssignmentRule
(Level 2) or has
type 'scalar' (Level 1), false
otherwise.public boolean isSetFormula()
true
if this
Rule
's mathematical expression is set.
This method is equivalent to isSetMath(). This version is present for easier compatibility with SBML Level 1, in which mathematical formulas were written in text-string form.
true
if the mathematical formula for this Rule
is
set, false
otherwise.
Rule.isSetMath()
public boolean isSetMath()
true
if this
Rule
's mathematical expression is set.
This method is equivalent to isSetFormula().
true
if the formula (or equivalently the math) for this
Rule
is set, false
otherwise.
Rule.isSetFormula()
public boolean isSetUnits()
true
if this Rule
's 'units' attribute is set.
true
if the units for this Rule
is set, false
otherwise
public boolean isSetVariable()
true
if this
Rule
's 'variable' attribute is set.
In SBML Level 1, the different rule types each have a different
name for the attribute holding the reference to the object
constituting the left-hand side of the rule. (E.g., for
SBML Level 1's SpeciesConcentrationRule the attribute is 'species', for
CompartmentVolumeRule it is 'compartment', etc.) In SBML
Levels 2 and 3, the only two types of Rule
objects with a
left-hand side object reference are AssignmentRule
and RateRule
, and
both of them use the same name for attribute: 'variable'. In order to
make it easier for application developers to work with all Levels of
SBML, libSBML uses a uniform name for all such attributes, and it is
'variable', regardless of whether Level 1 rules or
Level 2&ndash3 rules are being used.
true
if the 'variable' attribute value of this Rule
is
set, false
otherwise.public boolean isSpeciesConcentration()
true
if this Rule
is a
SpeciesConcentrationRule or equivalent.
This libSBML method works for SBML Level 1 models (where there is
such a thing as an explicit SpeciesConcentrationRule), as well as
other Levels of SBML. For Levels above Level 1, this method
checks the symbol being affected by the rule, and returns true
if
the symbol is the identifier of a Species
object defined in the model.
true
if this Rule
is a SpeciesConcentrationRule, false
otherwise.public void renameSIdRefs(String oldid, String newid)
renameSIdRefs
 in class SBase
oldid
- the old identifiernewid
- the new identifierpublic void renameUnitSIdRefs(String oldid, String newid)
renameUnitSIdRefs
 in class SBase
oldid
- the old identifiernewid
- the new identifierpublic int setFormula(String formula)
Rule
to an expression in
text-string form.
This is equivalent to setMath(ASTNode math). The provision of
using text-string formulas is retained for easier SBML Level 1
compatibility. The formula is converted to an ASTNode
internally.
formula
- a mathematical formula in text-string form.
Rule.setMath(ASTNode math)
public int setL1TypeCode(int type)
Rule
.
type
- the SBML Level 1 type code for this Rule
. The
allowable values are SBML_COMPARTMENT_VOLUME_RULE
, SBML_PARAMETER_RULE
, and
SBML_SPECIES_CONCENTRATION_RULE
.
LIBSBML_OPERATION_SUCCESS
LIBSBML_INVALID_ATTRIBUTE_VALUE
if given type
value is not one of the above.
public int setMath(ASTNode math)
math
- the ASTNode
structure of the mathematical formula.
Rule.setFormula(String formula)
public int setUnits(String sname)
Rule
.
sname
- the identifier of the units
public int setVariable(String sid)
Rule
object.
In SBML Level 1, the different rule types each have a different
name for the attribute holding the reference to the object
constituting the left-hand side of the rule. (E.g., for
SBML Level 1's SpeciesConcentrationRule the attribute is 'species', for
CompartmentVolumeRule it is 'compartment', etc.) In SBML
Levels 2 and 3, the only two types of Rule
objects with a
left-hand side object reference are AssignmentRule
and RateRule
, and
both of them use the same name for attribute: 'variable'. In order to
make it easier for application developers to work with all Levels of
SBML, libSBML uses a uniform name for all such attributes, and it is
'variable', regardless of whether Level 1 rules or
Level 2&ndash3 rules are being used.
sid
- the identifier of a Compartment
, Species
or Parameter
elsewhere in the enclosing Model
object.
public int unsetUnits()
Rule
.