public class AlgebraicRule extends Rule
The rule type AlgebraicRule
is derived from the parent class Rule
. It
is used to express equations that are neither assignments of model
variables nor rates of change. AlgebraicRule
does not add any
attributes to the basic Rule
its role is simply to distinguish this
case from the other cases.
In the context of a simulation, algebraic rules are in effect at all times, t ≥ 0. For purposes of evaluating expressions that involve the delay 'csymbol' (see the SBML specification), algebraic rules are considered to apply also at 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.
An SBML model must not be overdetermined. The ability to define
arbitrary algebraic expressions in an SBML model introduces the
possibility that a model is mathematically overdetermined by the overall
system of equations constructed from its rules, reactions and events.
Therefore, if an algebraic rule is introduced in a model, for at least
one of the entities referenced in the rule's 'math' element the value of
that entity must not be completely determined by other constructs in the
model. This means that at least this entity must not have the attribute
'constant'=true
and there must also not be a rate rule or assignment
rule for it. Furthermore, if the entity is a Species
object, its value
must not be determined by reactions, which means that it must either
have the attribute 'boundaryCondition'=true
or else not be involved
in any reaction at all. These restrictions are explained in more detail
in the SBML specification documents.
In SBML Levels 2 and 3, Reaction
object identifiers can be
referenced in the 'math' expression of an algebraic rule, but reaction
rates can never be determined by algebraic rules. This is true
even when a reaction does not contain a KineticLaw
element. (In such
cases of missing KineticLaw
elements, the model is valid but incomplete
the rates of reactions lacking kinetic laws are simply undefined, and
not determined by the algebraic rule.)
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 |
---|
AlgebraicRule(long level,
long version)
|
AlgebraicRule(SBMLNamespaces sbmlns)
|
Modifier and Type | Method and Description |
---|---|
AlgebraicRule |
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 AlgebraicRule object
have been set. |
containsUndeclaredUnits, getDerivedUnitDefinition, getElementName, getFormula, getId, getL1TypeCode, getMath, getType, getTypeCode, getUnits, getVariable, hasRequiredElements, isAlgebraic, isAssignment, isCompartmentVolume, isParameter, isRate, isScalar, isSetFormula, isSetMath, isSetUnits, isSetVariable, isSpeciesConcentration, renameSIdRefs, renameUnitSIdRefs, setFormula, setL1TypeCode, setMath, setUnits, setVariable, unsetUnits
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 AlgebraicRule(long level, long version) throws SBMLConstructorException
level
- a long integer, the SBML Level to assign to this AlgebraicRule
version
- a long integer, the SBML Version to assign to this
AlgebraicRule
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.
AlgebraicRule
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 AlgebraicRule
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 AlgebraicRule
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
.public AlgebraicRule(SBMLNamespaces sbmlns) throws SBMLConstructorException
AlgebraicRule
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.
sbmlns
- an SBMLNamespaces
object.
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.
AlgebraicRule
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 AlgebraicRule
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 AlgebraicRule
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
.public AlgebraicRule cloneObject()
Rule
.
cloneObject
 in class Rule
Rule
.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 AlgebraicRule.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 AlgebraicRule.delete()
themselves.
public boolean hasRequiredAttributes()
true
if
all the required attributes for this AlgebraicRule
object
have been set.
hasRequiredAttributes
 in class Rule
true
if the required attributes have been set, false
otherwise.AlgebraicRule
object. For Level 1, the only required
attribute is 'formula'.