Implementation of SBML's Rule construct.
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.
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.
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.
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.