libSBML C API  libSBML 5.8.0 C API
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Constraint_t Class Reference

Detailed Description

Implementation of SBML's Constraint construct.

The Constraint object class was introduced in SBML Level 2 Version 2 as a mechanism for stating the assumptions under which a model is designed to operate. The constraints are statements about permissible values of different quantities in a model. Constraints are not used to compute dynamical values for simulation or analysis, but rather, they serve an advisory role for simulation/analysis tools.

SBML's Constraint object class has one required attribute, "id", to give the parameter a unique identifier by which other parts of an SBML model definition can refer to it. A Constraint object can also have an optional "name" attribute of type string. Identifiers and names must be used according to the guidelines described in the SBML specification (e.g., Section 3.3 in the Level 2 Version 4 specification).

Constraint has one required subelement, "math", containing a MathML formula defining the condition of the constraint. This formula must return a boolean value of true when the model is a valid state. The formula can be an arbitrary expression referencing the variables and other entities in an SBML model. The evaluation of "math" and behavior of constraints are described in more detail below.

A Constraint structure also has an optional subelement called "message". This can contain a message in XHTML format that may be displayed to the user when the condition of the formula in the "math" subelement evaluates to a value of false. Software tools are not required to display the message, but it is recommended that they do so as a matter of best practice. The XHTML content within a "message" subelement must follow the same restrictions as for the "notes" element on SBase described in in the SBML Level 2 specification; please consult the SBML specification document corresponding to the SBML Level and Version of your model for more information about the requirements for "notes" content.

Constraint was introduced in SBML Level 2 Version 2. It is not available in earlier versions of Level 2 nor in any version of Level 1.

Semantics of Constraints

In the context of a simulation, a Constraint has effect at all times t $\geq$ 0. Each Constraint's "math" subelement is first evaluated after any InitialAssignment definitions in a model at t = 0 and can conceivably trigger at that point. (In other words, a simulation could fail a constraint immediately.)

Constraint structures cannot and should not be used to compute the dynamical behavior of a model as part of, for example, simulation. Constraints may be used as input to non-dynamical analysis, for instance by expressing flux constraints for flux balance analysis.

The results of a simulation of a model containing a constraint are invalid from any simulation time at and after a point when the function given by the "math" subelement returns a value of false. Invalid simulation results do not make a prediction of the behavior of the biochemical reaction network represented by the model. The precise behavior of simulation tools is left undefined with respect to constraints. If invalid results are detected with respect to a given constraint, the "message" subelement may optionally be displayed to the user. The simulation tool may also halt the simulation or clearly delimit in output data the simulation time point at which the simulation results become invalid.

SBML does not impose restrictions on duplicate Constraint definitions or the order of evaluation of Constraint objects in a model. It is possible for a model to define multiple constraints all with the same mathematical expression. Since the failure of any constraint indicates that the model simulation has entered an invalid state, a system is not required to attempt to detect whether other constraints in the model have failed once any one constraint has failed.