RateRule_t Class Reference

Detailed Description

An SBML rate rule representing dx/dt = f(Y).

The rule type RateRule_t is derived from the parent class Rule_t. 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_t 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_t 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_t 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_t "variable" attribute and a SpeciesReference_t "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_t 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_t sets the rate of change of the compartment's size to the value determined by the formula in the "math" subelement of the RateRule_t 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_t sets the rate of change of the parameter's value to that determined by the formula in the "math" subelement of the RateRule_t 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_t object's "unit" attribute value divided by the model-wide unit of time.

• (For SBML Level 3 Version 2 only) In the case of an object from an SBML Level 3 package, a RateRule_t sets the rate of change of the referenced object's value (as defined by that package) to the value of the formula in "math". The unit of measurement associated with the value produced by the formula should be the same as that object's units attribute value (if it has such an attribute) divided by the model-wide unit of time, or be equal to the units of model components of that type (if objects of that class are defined by the package as having the same units) divided by the model-wide unit of time.

In SBML Level 2 and Level 3 Version 1, the "math" subelement of the RateRule_t is required. In SBML Level 3 Version 2, this rule is relaxed, and the subelement is optional. If a RateRule_t with no "math" child is present in the model, the rate at which its referenced "variable" changes over time is undefined. This may represent a situation where the model itself is unfinished, or the missing information may be provided by an SBML Level 3 package.

If the variable attribute of a RateRule_t object references an object in an SBML namespace that is not understood by the interpreter reading a given SBML document (that is, if the object is defined by an SBML Level 3 package that the software does not support), the rate rule must be ignored–the object's value will not need to be set, as the interpreter could not understand that package. If an interpreter cannot establish whether a referenced object is missing from the model or instead is defined in an SBML namespace not understood by the interpreter, it may produce a warning to the user. (The latter situation may only arise if an SBML package is present in the SBML document with a package:required attribute of "true".)

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_t, a model must not contain more than one RateRule_t or AssignmentRule_t 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_t.)

• 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_t structure containing a subelement, "math", to hold the right-hand side expression, then to derive subtypes of Rule_t 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_t (AssignmentRule_t, AlgebraicRule_t, RateRule_t) inherit the the "math" subelement and other fields from SBase_t. The AssignmentRule_t and RateRule_t classes add an additional attribute, "variable". See the definitions of AssignmentRule_t, AlgebraicRule_t and RateRule_t 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_t, AssignmentRule_t and KineticLaw_t objects in a model constitute a set of assignment statements that should be considered as a whole. (A KineticLaw_t object is counted as an assignment because it assigns a value to the symbol contained in the "id" attribute of the Reaction_t 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.

Similarly, the combined set of RateRule_t and Reaction_t objects constitute a set of definitions for the rates of change of various model entities (namely, the objects identified by the values of the 'variable' attributes of the RateRule_t objects, and the 'species' attributes of the SpeciesReference_t objects in each Reaction_t). In SBML Level 3 Version 2, these rates of change may be referenced directly using the rateOf csymbol, but may not thereby contain algebraic loops—dependency chains between these statements must terminate. More formally, consider a directed graph in which the nodes are the definitions of different variables' rates of change, and directed arcs exist for each occurrence of a variable referenced by a rateOf csymbol from any RateRule_t or KineticLaw_t object in the model. Let the directed arcs point from the variable referenced by the rateOf csymbol (call it x) to the variable(s) determined by the 'math' expression in which x appears. 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. A valid SBML model that does not contain AlgebraicRule_t structures cannot be overdetermined.

LibSBML implements the static analysis procedure described in Appendix B of the SBML Level 3 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_t 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 a libSBML enumeration type, RuleType_t, whose values are 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.

Public Member Functions
RateRule_t *	RateRule_clone (RateRule_t *rr)
	Creates a deep copy of the given RateRule_t structure. More...
RateRule_t *	RateRule_create (unsigned int level, unsigned int version)
	Creates a new RateRule_t structure using the given SBML level and version values. More...
RateRule_t *	RateRule_createWithNS (SBMLNamespaces_t *sbmlns)
	Creates a new RateRule_t structure using the given SBMLNamespaces_t structure, sbmlns. More...
void	RateRule_free (RateRule_t *rr)
	Frees the given RateRule_t structure. More...
const char *	RateRule_getFormula (const RateRule_t *r)
const ASTNode_t *	RateRule_getMath (const RateRule_t *rr)
	Gets the mathematical expression of this RateRule_t structure as an ASTNode_t structure. More...
const char *	RateRule_getVariable (const RateRule_t *rr)
	Returns the value of the "variable" attribute of the given RateRule_t structure. More...
int	RateRule_hasRequiredAttributes (const RateRule_t *rr)
	Predicate returning 1 (true) or 0 (false) depending on whether all the required attributes of the given RateRule_t structure have been set. More...
int	RateRule_hasRequiredElements (const RateRule_t *rr)
	Predicate returning 1 (true) or 0 (false) depending on whether all the required sub-elements of the given RateRule_t structure have been set. More...
int	RateRule_isSetFormula (const RateRule_t *r)
int	RateRule_isSetMath (const RateRule_t *rr)
	Predicate returning 1 (true) if the given RateRule_t structure's "math" is set. More...
int	RateRule_isSetVariable (const RateRule_t *rr)
	Predicate returning 1 (true) if the given RateRule_t structure's "variable" is set. More...
int	RateRule_setFormula (RateRule_t *r, const char *formula)
	Sets the formula of this RateRule_t to a copy of string. More...
int	RateRule_setMath (RateRule_t *rr, const ASTNode_t *math)
	Sets the mathematical expression of the given RateRule_t structure. More...
int	RateRule_setVariable (RateRule_t *rr, const char *variable)
	Sets the "variable" attribute of the given RateRule_t structure. More...
int	RateRule_unsetVariable (RateRule_t *ar)
	Unsets the value of the "variable" attribute of the given RateRule_t structure. More...

Member Function Documentation

RateRule_t * RateRule_clone

(

RateRule_t *

rr

)

Creates a deep copy of the given RateRule_t structure.

Parameters

rr	the RateRule_t structure to be copied.

Returns

a (deep) copy of the given RateRule_t structure, or a null pointer if a failure occurred.

RateRule_t * RateRule_create	(	unsigned int	level,
		unsigned int	version
	)

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

Parameters

level	an unsigned int, the SBML level to assign to this RateRule_t structure.
version	an unsigned int, the SBML version to assign to this RateRule_t structure.

Returns

the newly-created RateRule_t structure, or a null pointer if an error occurred during construction.

Note

Attempting to add an object to an SBMLDocument_t 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_t), 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.

RateRule_t * RateRule_createWithNS

(

SBMLNamespaces_t *

sbmlns

)

Creates a new RateRule_t structure using the given SBMLNamespaces_t structure, sbmlns.

The SBMLNamespaces_t 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_t facilities is to create an SBMLNamespaces_t object somewhere in a program once, then hand that object as needed to object constructors that accept SBMLNamespaces_t as arguments.

Parameters

sbmlns

an SBMLNamespaces_t structure.

Returns

the newly-created RateRule_t structure, or a null pointer if an error occurred during construction.

Note

Attempting to add an object to an SBMLDocument_t 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_t), 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.

void RateRule_free

(

RateRule_t *

rr

)

Frees the given RateRule_t structure.

Parameters

rr	the RateRule_t structure to be freed.

const char * RateRule_getFormula

(

const RateRule_t *

r

)

Note

SBML Level 1 uses a text-string format for mathematical formulas. Other levels of SBML use MathML, an XML format for representing mathematical expressions. LibSBML provides an Abstract Syntax Tree API for working with mathematical expressions; this API is more powerful than working with formulas directly in text form, and ASTs can be translated into either MathML or the text-string syntax. The libSBML methods that accept text-string formulas directly (such as this one) are provided for SBML Level 1 compatibility, but developers are encouraged to use the AST mechanisms.

Returns

the formula for this RateRule_t.

const ASTNode_t * RateRule_getMath

(

const RateRule_t *

rr

)

Gets the mathematical expression of this RateRule_t structure as an ASTNode_t structure.

Parameters

rr	the RateRule_t structure.

Returns

the math for this RateRule_t, as an ASTNode_t.

const char * RateRule_getVariable

(

const RateRule_t *

rr

)

Returns the value of the "variable" attribute of the given RateRule_t structure.

Parameters

rr	the RateRule_t structure.

Returns

the variable of this structure.

int RateRule_hasRequiredAttributes

(

const RateRule_t *

rr

)

Predicate returning 1 (true) or 0 (false) depending on whether all the required attributes of the given RateRule_t structure have been set.

Parameters

rr	the RateRule_t structure to check.

Returns

1 (true) if all the required attributes for this structure have been defined, 0 (false) otherwise.

int RateRule_hasRequiredElements

(

const RateRule_t *

rr

)

Predicate returning 1 (true) or 0 (false) depending on whether all the required sub-elements of the given RateRule_t structure have been set.

Parameters

rr	the RateRule_t structure to check.

Returns

1 (true) if all the required sub-elements for this structure have been defined, 0 (false) otherwise.

int RateRule_isSetFormula

(

const RateRule_t *

r

)

Returns

1 (true) if the formula (or equivalently the math) for this RateRule_t is set, 0 (false) otherwise.

int RateRule_isSetMath

(

const RateRule_t *

rr

)

Predicate returning 1 (true) if the given RateRule_t structure's "math" is set.

Parameters

rr	the RateRule_t structure.

Returns

1 (true) if the "math" of this RateRule_t structure is set, 0 (false) otherwise.

int RateRule_isSetVariable

(

const RateRule_t *

rr

)

Predicate returning 1 (true) if the given RateRule_t structure's "variable" is set.

Parameters

rr	the RateRule_t structure.

Returns

1 (true) if the "variable" of this RateRule_t structure is set, 0 (false) otherwise.

int RateRule_setFormula	(	RateRule_t *	r,
		const char *	formula
	)

Sets the formula of this RateRule_t to a copy of string.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

• LIBSBML_OPERATION_SUCCESS
• LIBSBML_INVALID_OBJECT

Note

SBML Level 1 uses a text-string format for mathematical formulas. Other levels of SBML use MathML, an XML format for representing mathematical expressions. LibSBML provides an Abstract Syntax Tree API for working with mathematical expressions; this API is more powerful than working with formulas directly in text form, and ASTs can be translated into either MathML or the text-string syntax. The libSBML methods that accept text-string formulas directly (such as this one) are provided for SBML Level 1 compatibility, but developers are encouraged to use the AST mechanisms.

int RateRule_setMath	(	RateRule_t *	rr,
		const ASTNode_t *	math
	)

Sets the mathematical expression of the given RateRule_t structure.

Parameters

rr	the RateRule_t structure.
math	an ASTNode_t structure to be assigned as the "math" subelement of this RateRule_t.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

• LIBSBML_OPERATION_SUCCESS
• LIBSBML_INVALID_OBJECT

int RateRule_setVariable	(	RateRule_t *	rr,
		const char *	variable
	)

Sets the "variable" attribute of the given RateRule_t structure.

This function copies the string given in variable. If the string is a null pointer, this function is equivalent to calling RateRule_unsetVariable().

Parameters

rr	the RateRule_t structure.
variable	the string to which the structures "variable" attribute should be set.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

• LIBSBML_OPERATION_SUCCESS
• LIBSBML_INVALID_ATTRIBUTE_VALUE
• LIBSBML_INVALID_OBJECT

Note

Using this function with a null pointer for variable is equivalent to unsetting the value of the "variable" attribute.

int RateRule_unsetVariable

(

RateRule_t *

ar

)

Unsets the value of the "variable" attribute of the given RateRule_t structure.

Parameters

ar	the RateRule_t structure.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

• LIBSBML_OPERATION_SUCCESS
• LIBSBML_UNEXPECTED_ATTRIBUTE
• LIBSBML_INVALID_OBJECT
• LIBSBML_OPERATION_FAILED