|
libSBML C++ API
5.20.2
|
Forward declarations for all opaque C types. More...
Macros | |
| #define | CLASS_OR_STRUCT class |
| Defined as a class when compiling for C++ and as a C struct when compiling for C. More... | |
Forward declarations for all opaque C types.
Declaring all types up-front avoids compilation errors of the form "Redefinition of type 'Foo'", and allows our combined C/C++ headers to depend minimally upon each other. Put another way, the type definitions below serve the same purpose as class Foo; forward declarations in C++ code.
| #define CLASS_OR_STRUCT class |
Defined as a class when compiling for C++ and as a C struct when compiling for C.
| typedef class AlgebraicRule AlgebraicRule_t |
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 \(\geq\) 0. For purposes of evaluating expressions that involve the delay "csymbol" (see the SBML specification), algebraic rules are considered to apply also at t \(\leq\) 0. Please consult the relevant SBML specification for additional information about the semantics of assignments, rules, and entity values for simulation time t \(\leq\) 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 object. (In such cases of missing kinetic law definitions, 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 2 and Level 3 Version 1, the "math" subelement of the AlgebraicRule is required. In SBML Level 3 Version 2, this rule is relaxed, and the subelement is optional. If an AlgebraicRule with no "math" child is present in the model, no additional mathematical constraints on the model are added by the rule. This may represent a situation where the model itself is unfinished, or the missing information may be provided by an SBML Level 3 package.
Finally, any symbol that appears as the target of a rateOf csymbol (AST_FUNCTION_RATE_OF, introduced in SBML Level 3 Version 2) may not be determined by an AlgebraicRule. This is because the rateOf csymbol is defined as applying only to symbols whose rates of change are easily determinable.
Users should note that these rules about what symbols may not be determined by an AlgebraicRule may be used to discover what symbol is being determined by an AlgebraicRule. If three symbols appear in the math element of an AlgebraicRule, the first of which is flagged constant=true, and the second of which appears as the target of a rateOf csymbol, one may conclude that the AlgebraicRule must be used to determine the value of the third symbol. This is, in fact, a principle use (outside of validation) of the constant attribute: its use in allowing software to properly identify the dependent variable in an AlgebraicRule.
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:
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.
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.
Similarly, the combined set of RateRule and Reaction 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 objects, and the 'species' attributes of the SpeciesReference objects in each Reaction). 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 or KineticLaw 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.
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 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.)
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.
| typedef class AssignmentRule AssignmentRule_t |
The rule type AssignmentRule is derived from the parent class Rule. It is used to express equations that set the values of variables. The left-hand side (the attribute named "variable") of an assignment rule must refer to the identifier of a Species, SpeciesReference (in SBML Level 3), Compartment, or global Parameter object in the model (but not a Reaction). In SBML Level 3 Version 2, it may also refer to the SId of an element defined in an SBML Level 3 package with mathematical meaning and the ability to be assigned. The entity identified must have its "constant" attribute set to false. The effects of an assignment rule construct are in general terms the same, but differ in the precise details depending on the type of SBML component being set:
In the case of a species, an SBML assignment rule sets the referenced species' quantity (whether a "concentration" or "amount") to the value determined by the formula in the MathML subelement "math". The unit associated with the value produced by the "math" 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 equal to the unit associated with the species' quantity. Restrictions: There must not be both an AssignmentRule "variable" attribute and a SpeciesReference "species" attribute having the same value in a model, unless the referenced Species object has its "boundaryCondition" attribute set to true. In other words, an assignment 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, an assignment rule sets 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", because reactant and product stoichiometries in reactions are dimensionless quantities.
In the case of a compartment, an SBML assignment rule sets the referenced compartment's size to the value determined by the formula in the "math" subelement of the AssignmentRule 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 the same as the units of the size of the compartment.
In the case of a parameter, an assignment rule sets the referenced parameter's value to that determined by the formula in the "math" subelement of the AssignmentRule object. The overall units of the formula in the "math" subelement 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 same as the units defined for the parameter.
(For SBML Level 3 Version 2 only) In the case of an object from an SBML Level 3 package, an AssignmentRule sets 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), 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).
In SBML Level 2 and Level 3 Version 1, the "math" subelement of the AssignmentRule is required. In SBML Level 3 Version 2, this rule is relaxed, and the subelement is optional. If an AssignmentRule with no "math" child is present in the model, the value of its referenced "variable" 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 an AssignmentRule object references an object in an SBML namespace 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 assignment 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, assignment rules are in effect at all times, t \(\geq\) 0. For purposes of evaluating expressions that involve the delay "csymbol" (see the SBML Level 2 specification), assignment rules are considered to apply also at t \(\leq\) 0. Please consult the relevant SBML specification for additional information about the semantics of assignments, rules, and entity values for simulation time t \(\leq\) 0.
A model must not contain more than one AssignmentRule or RateRule 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.
Similarly, a model must also not contain both an AssignmentRule and an InitialAssignment definition for the same variable, because both kinds of constructs apply prior to and at the start of simulation time, i.e., t \(\leq\) 0. If a model contained both an initial assignment and an assignment rule for the same variable, an indeterminate system would result.
The value calculated by an AssignmentRule object overrides the value assigned to the given symbol by the model component defining that symbol. For example, if a Compartment object's "size" attribute value is set in its definition, and the model also contains an AssignmentRule object having that compartment's "id" as its "variable" value, then the "size" assigned in the Compartment object definition is ignored and the value assigned based on the computation defined in the AssignmentRule. This does not mean that a definition for a given symbol can be omitted if there is an AssignmentRule object involving it. For example, there must be a Parameter object definition for a given parameter if there is an AssignmentRule definition for that parameter. It is only a question of which value definition takes precedence.
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:
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.
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.
Similarly, the combined set of RateRule and Reaction 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 objects, and the 'species' attributes of the SpeciesReference objects in each Reaction). 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 or KineticLaw 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.
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 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.)
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.
This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.
Abstract Syntax Trees (ASTs) are a simple kind of data structure used in libSBML for storing mathematical expressions. The ASTNode is the cornerstone of libSBML's AST representation. An AST "node" represents the most basic, indivisible part of a mathematical formula and come in many types. For instance, there are node types to represent numbers (with subtypes to distinguish integer, real, and rational numbers), names (e.g., constants or variables), simple mathematical operators, logical or relational operators and functions. LibSBML ASTs provide a canonical, in-memory representation for all mathematical formulas regardless of their original format (which might be MathML or might be text strings).
"1 + 2" is represented as an AST with one plus node having two integer children nodes for the numbers 1 and 2. The figure also shows the corresponding MathML representation:| Infix | AST | MathML |
|---|---|---|
1 + 2
|
<math xmlns="http://www.w3.org/1998/Math/MathML"> <apply> <plus/> <cn type="integer"> 1 </cn> <cn type="integer"> 2 </cn> </apply></math>
|
The following are other noteworthy points about the AST representation in libSBML:
double data type. This is done so that when an SBML model is read in and then written out again, the amount of change introduced by libSBML to the SBML during the round-trip activity is minimized.For many applications, the details of ASTs are irrelevant because libSBML provides text-string based translation functions such as SBML_formulaToL3String() and SBML_parseL3Formula(). If you find the complexity of using the AST representation of expressions too high for your purposes, perhaps the string-based functions will be more suitable.
| AST_CONSTANT_E | AST_FUNCTION_CSC | AST_LOGICAL_AND |
| AST_CONSTANT_FALSE | AST_FUNCTION_CSCH | AST_LOGICAL_IMPLIES2 |
| AST_CONSTANT_PI | AST_FUNCTION_DELAY | AST_LOGICAL_NOT |
| AST_CONSTANT_TRUE | AST_FUNCTION_EXP | AST_LOGICAL_OR |
| AST_DIVIDE | AST_FUNCTION_FACTORIAL | AST_LOGICAL_XOR |
| AST_FUNCTION | AST_FUNCTION_FLOOR | AST_MINUS |
| AST_FUNCTION_ABS | AST_FUNCTION_LN | AST_NAME |
| AST_FUNCTION_ARCCOS | AST_FUNCTION_LOG | AST_NAME_AVOGADRO1 |
| AST_FUNCTION_ARCCOSH | AST_FUNCTION_MAX2 | AST_NAME_TIME |
| AST_FUNCTION_ARCCOT | AST_FUNCTION_MIN2 | AST_ORIGINATES_IN_PACKAGE2 |
| AST_FUNCTION_ARCCOTH | AST_FUNCTION_PIECEWISE | AST_PLUS |
| AST_FUNCTION_ARCCSC | AST_FUNCTION_POWER | AST_POWER |
| AST_FUNCTION_ARCCSCH | AST_FUNCTION_QUOTIENT2 | AST_RATIONAL |
| AST_FUNCTION_ARCSEC | AST_FUNCTION_RATE_OF2 | AST_REAL |
| AST_FUNCTION_ARCSECH | AST_FUNCTION_REM2 | AST_REAL_E |
| AST_FUNCTION_ARCSIN | AST_FUNCTION_ROOT | AST_RELATIONAL_EQ |
| AST_FUNCTION_ARCSINH | AST_FUNCTION_SEC | AST_RELATIONAL_GEQ |
| AST_FUNCTION_ARCTAN | AST_FUNCTION_SECH | AST_RELATIONAL_GT |
| AST_FUNCTION_ARCTANH | AST_FUNCTION_SIN | AST_RELATIONAL_LEQ |
| AST_FUNCTION_CEILING | AST_FUNCTION_SINH | AST_RELATIONAL_LT |
| AST_FUNCTION_COS | AST_FUNCTION_TAN | AST_RELATIONAL_NEQ |
| AST_FUNCTION_COSH | AST_FUNCTION_TANH | AST_TIMES |
| AST_FUNCTION_COT | AST_INTEGER | AST_UNKNOWN |
| AST_FUNCTION_COTH | AST_LAMBDA | |
| 1 (Level 3 only) | ||
| 2 (Level 3 Version 2+ only) |
The types have the following meanings:
"+"), then the node's type will be AST_PLUS, AST_MINUS, AST_TIMES, AST_DIVIDE, or AST_POWER, as appropriate.AST_FUNCTION_X, AST_LOGICAL_X, or AST_RELATIONAL_X, as appropriate. (Examples: AST_FUNCTION_LOG, AST_RELATIONAL_LEQ.)"ExponentialE", "Pi", "True" or "False"), then the node's type will be AST_CONSTANT_E, AST_CONSTANT_PI, AST_CONSTANT_TRUE, or AST_CONSTANT_FALSE.time, the value of the node will be AST_NAME_TIME. (Note, however, that the MathML csymbol delay is translated into a node of type AST_FUNCTION_DELAY. The difference is due to the fact that time is a single variable, whereas delay is actually a function taking arguments.)avogadro, the value of the node will be AST_NAME_AVOGADRO.rateOf, the value of the node will be AST_FUNCTION_RATE_OF.The text-string form of mathematical formulas produced by SBML_formulaToString() and SBML_formulaToL3String(), and read by SBML_parseFormula() and SBML_parseL3Formula() are in a simple C-inspired infix notation. A formula in this text-string form can be handed to a program that understands SBML mathematical expressions, or used as part of a translation system. The libSBML distribution comes with an example program in the "examples" subdirectory called translateMath that implements an interactive command-line demonstration of translating infix formulas into MathML and vice-versa.
The formula strings may contain operators, function calls, symbols, and white space characters. The allowable white space characters are tab and space. The following are illustrative examples of formulas expressed in the syntax:
0.10 * k4^2
(vm * s1)/(km + s1)
The following table shows the precedence rules in this syntax. In the Class column, operand implies the construct is an operand, prefix implies the operation is applied to the following arguments, unary implies there is one argument, and binary implies there are two arguments. The values in the Precedence column show how the order of different types of operation are determined. For example, the expression a * b + c is evaluated as (a * b) + c because the * operator has higher precedence. The Associates column shows how the order of similar precedence operations is determined; for example, a - b + c is evaluated as (a - b) + c because the + and - operators are left-associative. The precedence and associativity rules are taken from the C programming language, except for the symbol ^, which is used in C for a different purpose. (Exponentiation can be invoked using either ^ or the function power.)
| Token | Operation | Class | Precedence | Associates |
|---|---|---|---|---|
| name | symbol reference | operand | 6 | n/a |
(expression) | expression grouping | operand | 6 | n/a |
f(...) | function call | prefix | 6 | left |
- | negation | unary | 5 | right |
^ | power | binary | 4 | left |
* | multiplication | binary | 3 | left |
/ | divison | binary | 3 | left |
+ | addition | binary | 2 | left |
- | subtraction | binary | 2 | left |
, | argument delimiter | binary | 1 | left |
A program parsing a formula in an SBML model should assume that names appearing in the formula are the identifiers of Species, Parameter, Compartment, FunctionDefinition, Reaction (in SBML Levels 2 and 3), or SpeciesReference (in SBML Level 3 only) objects defined in a model. When a function call is involved, the syntax consists of a function identifier, followed by optional white space, followed by an opening parenthesis, followed by a sequence of zero or more arguments separated by commas (with each comma optionally preceded and/or followed by zero or more white space characters), followed by a closing parenthesis. There is an almost one-to-one mapping between the list of predefined functions available, and those defined in MathML. All of the MathML functions are recognized; this set is larger than the functions defined in SBML Level 1. In the subset of functions that overlap between MathML and SBML Level 1, there exist a few differences. The following table summarizes the differences between the predefined functions in SBML Level 1 and the MathML equivalents in SBML Levels 2 and 3:
| Text string formula functions | MathML equivalents in SBML Levels 2 and 3 |
|---|---|
acos | arccos |
asin | arcsin |
atan | arctan |
ceil | ceiling |
log | ln |
log10(x) | log(x) or log(10, x) |
pow(x, y) | power(x, y) |
sqr(x) | power(x, 2) |
sqrt(x) | root(x) or root(2, x) |
| typedef class Compartment Compartment_t |
A compartment in SBML represents a bounded space in which species are located. Compartments do not necessarily have to correspond to actual structures inside or outside of a biological cell.
It is important to note that although compartments are optional in the overall definition of Model, every species in an SBML model must be located in a compartment. This in turn means that if a model defines any species, the model must also define at least one compartment. The reason is simply that species represent physical things, and therefore must exist somewhere. Compartments represent the somewhere.
Compartment has one required attribute, "id", to give the compartment a unique identifier by which other parts of an SBML model definition can refer to it. A compartment can also have an optional "name" attribute of type string. Identifiers and names must be used according to the guidelines described in the SBML specifications.
Compartment also has an optional attribute "spatialDimensions" that is used to indicate the number of spatial dimensions possessed by the compartment. Most modeling scenarios involve compartments with integer values of "spatialDimensions" of 3 (i.e., a three-dimensional compartment, which is to say, a volume), or 2 (a two-dimensional compartment, a surface), or 1 (a one-dimensional compartment, a line). In SBML Level 3, the type of this attribute is double, there are no restrictions on the permitted values of the "spatialDimensions" attribute, and there are no default values. In SBML Level 2, the value must be a positive integer, and the default value is 3; the permissible values in SBML Level 2 are 3, 2, 1, and 0 (for a point).
Another optional attribute on Compartment is "size", representing the initial total size of that compartment in the model. The "size" attribute must be a floating-point value and may represent a volume (if the compartment is a three-dimensional one), or an area (if the compartment is two-dimensional), or a length (if the compartment is one-dimensional). There is no default value of compartment size in SBML Level 2 or Level 3. In particular, a missing "size" value does not imply that the compartment size is 1. (This is unlike the definition of compartment "volume" in SBML Level 1.) When the compartment's "spatialDimensions" attribute does not have a value of 0, a missing value of "size" for a given compartment signifies that the value either is unknown, or to be obtained from an external source, or determined by an InitialAssignment, AssignmentRule, AlgebraicRule or RateRule object elsewhere in the model. In SBML Level 2, there are additional special requirements on the values of "size"; we discuss them in a separate section below.
The units associated with a compartment's "size" attribute value may be set using the optional attribute "units". The rules for setting and using compartment size units differ between SBML Level 2 and Level 3, and are discussed separately below.
Finally, the Compartment attribute named "constant" is used to indicate whether the compartment's size stays constant after simulation begins. A value of true indicates the compartment's "size" cannot be changed by any other construct except InitialAssignment; a value of false indicates the compartment's "size" can be changed by other constructs in SBML. In SBML Level 2, there is an additional explicit restriction that if "spatialDimensions"="0", the value cannot be changed by InitialAssignment either. Further, in Level 2, "constant" is optional, and has a default value of true. In SBML Level 3, there is no default value for the "constant" attribute, and it is required.
In SBML Level 2, the default units of compartment size, and the kinds of units allowed as values of the attribute "units", interact with the number of spatial dimensions of the compartment. The value of the "units" attribute of a Compartment object must be one of the base units (see Unit), or the predefined unit identifiers volume, area, length or dimensionless, or a new unit defined by a UnitDefinition object in the enclosing Model, subject to the restrictions detailed in the following table:
Value ofspatialDimensions | sizeallowed? | unitsallowed? | Allowable kinds of units | Default value of attribute units |
|---|---|---|---|---|
3 | yes | yes | units of volume, or dimensionless | volume |
2 | yes | yes | units of area, or dimensionless | area |
1 | yes | yes | units of length, or dimensionless | length |
0 | no | no | (no units allowed) |
In SBML Level 2, the units of the compartment size, as defined by the "units" attribute or (if "units" is not set) the default value listed in the table above, are used in the following ways when the compartment has a "spatialDimensions" value greater than 0:
The value of the "units" attribute is used as the units of the compartment identifier when the identifier appears as a numerical quantity in a mathematical formula expressed in MathML.
The math element of an AssignmentRule or InitialAssignment referring to this compartment must (in Level 2 Versions 1-3) or should (in Level 2 Version 4) have identical units.
In RateRule objects that set the rate of change of the compartment's size, the units of the rule's math element must (in Level 2 Versions 1–3) or should (in Level 2 Version 4) be identical to the compartment's units (whether defined by the "units" attribute or by taking the default value from the Model) divided by the default time units. (In other words, the units for the rate of change of compartment size are compartment size/time units.
Compartments with "spatialDimensions"=0 require special treatment in this framework. As implied above, the "size" attribute must not have a value on an SBML Level 2 Compartment object if the "spatialDimensions" attribute has a value of 0. An additional related restriction is that the "constant" attribute must default to or be set to true if the value of the "spatialDimensions" attribute is 0, because a zero-dimensional compartment cannot ever have a size.
If a compartment has no size or dimensional units, how should such a compartment's identifier be interpreted when it appears in mathematical formulas? The answer is that such a compartment's identifier should not appear in mathematical formulas in the first place—it has no value, and its value cannot change. Note also that a zero-dimensional compartment is a point, and species located at points can only be described in terms of amounts, not spatially-dependent measures such as concentration. Since SBML KineticLaw formulas are already in terms of substance/time and not (say) concentration/time, volume or other factors in principle are not needed for species located in zero-dimensional compartments.
Finally, in SBML Level 2 Versions 2–4, each compartment in a model may optionally be designated as belonging to a particular compartment type. The optional attribute "compartmentType" is used identify the compartment type represented by the Compartment structure. The "compartmentType" attribute's value must be the identifier of a CompartmentType instance defined in the model. If the "compartmentType" attribute is not present on a particular compartment definition, a unique virtual compartment type is assumed for that compartment, and no other compartment can belong to that compartment type. The values of "compartmentType" attributes on compartments have no effect on the numerical interpretation of a model. Simulators and other numerical analysis software may ignore "compartmentType" attributes. The "compartmentType" attribute and the CompartmentType class of objects are not present in SBML Level 3 Core nor in SBML Level 1.
One difference between SBML Level 3 and lower Levels of SBML is that there are no restrictions on the permissible values of the "spatialDimensions" attribute, and there is no default value defined for the attribute. The value of "spatialDimensions" does not have to be an integer, either; this is to allow for the possibility of representing structures with fractal dimensions.
The number of spatial dimensions possessed by a compartment cannot enter into mathematical formulas, and therefore cannot directly alter the numerical interpretation of a model. However, the value of "spatialDimensions" does affect the interpretation of the units associated with a compartment's size. Specifically, the value of "spatialDimensions" is used to select among the Model attributes "volumeUnits", "areaUnits" and "lengthUnits" when a Compartment structure does not define a value for its "units" attribute.
The "units" attribute may be left unspecified for a given compartment in a model; in that case, the compartment inherits the unit of measurement specified by one of the attributes on the enclosing Model object instance. The applicable attribute on Model depends on the value of the compartment's "spatialDimensions" attribute; the relationship is shown in the table below. If the Model object does not define the relevant attribute ("volumeUnits", "areaUnits" or "lengthUnits") for a given "spatialDimensions" value, the unit associated with that Compartment object's size is undefined. If a given Compartment's "units" are left unset and the "spatialDimensions" either has a value other than 1, 2, or 3 or is left unset itself (as it has no default value), then no unit can be chosen from among the Model's "volumeUnits", "areaUnits" or "lengthUnits" attributes (even if the Model instance provides values for those attributes), because there is no basis to select between them. Leaving the units of compartments' sizes undefined in an SBML model does not render the model invalid; however, as a matter of best practice, we strongly recommend that all models specify the units of measurement for all compartment sizes.
| Value of attribute "spatialDimensions" | Attribute of Model used for inheriting the unit | Recommended candidate units |
|---|---|---|
3 | "volumeUnits" | units of volume, or dimensionless |
2 | "areaUnits" | units of area, or dimensionless |
1 | "lengthUnits" | units of length, or dimensionless |
| other | no units inherited | no specific recommendations |
The unit of measurement associated with a compartment's size, as defined by the "units" attribute or (if "units" is not set) the inherited value from Model according to the table above, is used in the following ways:
When the identifier of the compartment appears as a numerical quantity in a mathematical formula expressed in MathML, it represents the size of the compartment, and the unit associated with the size is the value of the "units" attribute.
When a Species is to be treated in terms of concentrations or density, the unit associated with the spatial size portion of the concentration value (i.e., the denominator in the formula amount/size) is specified by the value of the "units" attribute on the compartment in which the species is located.
The "math" elements of AssignmentRule, InitialAssignment and EventAssignment objects setting the value of the compartment size should all have the same units as the unit associated with the compartment's size.
In a RateRule object that defines a rate of change for a compartment's size, the unit of the rule's "math" element should be identical to the compartment's "units" attribute divided by the model-wide unit of time. (In other words, {unit of compartment size}/{unit of time}.)
In SBML Level 1 and Level 2, Compartment has an optional attribute named "outside", whose value can be the identifier of another Compartment object defined in the enclosing Model object. Doing so means that the other compartment contains it or is outside of it. This enables the representation of simple topological relationships between compartments, for those simulation systems that can make use of the information (e.g., for drawing simple diagrams of compartments). It is worth noting that in SBML, there is no relationship between compartment sizes when compartment positioning is expressed using the "outside" attribute. The size of a given compartment does not in any sense include the sizes of other compartments having it as the value of their "outside" attributes. In other words, if a compartment B has the identifier of compartment A as its "outside" attribute value, the size of A does not include the size of B. The compartment sizes are separate.
In Level 2, there are two restrictions on the "outside" attribute. First, because a compartment with "spatialDimensions" of 0 has no size, such a compartment cannot act as the container of any other compartment except compartments that also have "spatialDimensions" values of 0. Second, the directed graph formed by representing Compartment structures as vertexes and the "outside" attribute values as edges must be acyclic. The latter condition is imposed to prevent a compartment from being contained inside itself. In the absence of a value for "outside", compartment definitions in SBML Level 2 do not have any implied spatial relationships between each other.
| typedef class CompartmentType CompartmentType_t |
SBML Level 2 Versions 2–4 provide the compartment type as a grouping construct that can be used to establish a relationship between multiple Compartment objects. A CompartmentType object only has an identity, and this identity can only be used to indicate that particular Compartment objects in the model belong to this type. This may be useful for conveying a modeling intention, such as when a model contains many similar compartments, either by their biological function or the reactions they carry. Without a compartment type construct, it would be impossible within SBML itself to indicate that all of the compartments share an underlying conceptual relationship because each SBML compartment must be given a unique and separate identity. A CompartmentType has no mathematical meaning in SBML—it has no effect on a model's mathematical interpretation. Simulators and other numerical analysis software may ignore CompartmentType definitions and references to them in a model.
There is no mechanism in SBML Level 2 for representing hierarchies of compartment types. One CompartmentType instance cannot be the subtype of another CompartmentType instance; SBML provides no means of defining such relationships.
As with other major structures in SBML, CompartmentType has a mandatory attribute, "id", used to give the compartment type an identifier. The identifier must be a text string conforming to the identifer syntax permitted in SBML. CompartmentType also has an optional "name" attribute, of type string. The "id" and "name" must be used according to the guidelines described in the SBML specification (e.g., Section 3.3 in the Level 2 Version 4 specification).
CompartmentType was introduced in SBML Level 2 Version 2. It is not available in SBML Level 1 nor in Level 3.
| typedef class Constraint Constraint_t |
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 subelement, "math", containing a MathML formula defining the condition of the constraint. This formula will 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.
In SBML Level 2 and SBML Level 3 Version 1, the "math" subelement is required, and its formula must be a Boolean value. In SBML Level 3 Version 2, these restrictions were relaxed: the "math" subelement is optional, and numeric values are allowed in Boolean contexts (a '0' is interpreted as false, and all other values are interpreted as true). If a Constraint with no "math" is present in a Model, no restriction on the Model's behavior is implied or enforced.
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.
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.
| typedef class ConversionOption ConversionOption_t |
| typedef class ConversionProperties ConversionProperties_t |
This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.
The SBML Level 2 and Level 3 specifications define a simple format for annotating models when (a) referring to controlled vocabulary terms and database identifiers that define and describe biological and biochemical entities, and (b) describing the creator of a model and the model's modification history. This SBML format is a concrete syntax that conforms to the guidelines of MIRIAM ("Minimum Information Requested in the Annotation of biochemical Models", Nature Biotechnology, vol. 23, no. 12, Dec. 2005). The format uses a subset of W3C RDF (Resource Description Format). In order to help application developers work with annotations in this format, libSBML provides several helper classes that provide higher-level interfaces to the data elements; these classes include CVTerm, ModelCreator, ModelHistory, RDFAnnotationParser, and Date.
The SBML annotation format consists of RDF-based content placed inside an <annotation> element attached to an SBML component such as Species, Compartment, etc. A small change was introduced in SBML Level 2 Version 5 and SBML Level 3 Version 2 to permit nested annotations: lower Versions of the SBML specifications did not explicitly allow this. We first describe the different parts of SBML annotations in XML form for SBML Level 2 below Version 5 and SBML Level 3 below Version 2:
<SBML_ELEMENT +++ metaid="meta id" +++> +++ <annotation> +++ <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:dcterm="http://purl.org/dc/terms/" xmlns:vcard="http://www.w3.org/2001/vcard-rdf/3.0#" xmlns:bqbiol="http://biomodels.net/biology-qualifiers/" xmlns:bqmodel="http://biomodels.net/model-qualifiers/" > <rdf:Description rdf:about="#meta id"> HISTORY <RELATION_ELEMENT> <rdf:Bag> <rdf:li rdf:resource="URI" /> ... </rdf:Bag> </RELATION_ELEMENT> ... </rdf:Description> +++ </rdf:RDF> +++ </annotation> +++ </SBML_ELEMENT>
In the template above, the placeholder SBML_ELEMENT stands for the XML tag name of an SBML model component (e.g., model, reaction, etc.) and the placeholder meta id stands for the element's meta identifier, which is a field available on all SBML components derived from the SBase base object class. The dotted portions are optional, the symbol +++ is a placeholder for either no content or valid XML content that is not defined by this annotation scheme, and the ellipses ... are placeholders for zero or more elements of the same form as the immediately preceding element. The optional content HISTORY is a creation and modification history; in libSBML, this is stored using ModelHistory objects.
The placeholder RELATION_ELEMENT refers to a BioModels.net qualifier element name. This is an element in either the XML namespace "http://biomodels.net/model-qualifiers" (for model qualifiers) or "http://biomodels.net/biology-qualifiers" (for biological qualifier). Note that these namespace URIs are only labels, and not actual Web locations, which means you cannot visit an address such as "http://biomodels.net/model-qualifiers" in your browser or try to have your application access it. Refer instead to the enumerations ModelQualifierType_t and BiolQualifierType_t for a list of the available relationship elements that can be used for RELATION_ELEMENT.
The URI is a required data value that uniquely identifies a resource and data within that resource to which the annotation refers. Again, being URIs, these do not refer to physical Web locations; nevertheless, applications will often want a means of finding the resource to which a given URI refers. Providing the facilities for this task is the purpose of MIRIAM Resources, described in detail online at http://biomodels.net/miriam) and also in the paper "MIRIAM Resources: tools to generate and resolve robust cross-references in Systems Biology", BMC Systems Biology, 58(1), 2007.
Finally, the following is the same template as above, but this time showing the nested content permitted by the most recent SBML specifications (SBML Level 2 Version 5 and Level 3 Version 2):
<SBML_ELEMENT +++ metaid="meta id" +++> +++ <annotation> +++ <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:dcterm="http://purl.org/dc/terms/" xmlns:vcard="http://www.w3.org/2001/vcard-rdf/3.0#" xmlns:bqbiol="http://biomodels.net/biology-qualifiers/" xmlns:bqmodel="http://biomodels.net/model-qualifiers/" > <rdf:Description rdf:about="#meta id"> HISTORY <RELATION_ELEMENT> <rdf:Bag> <rdf:li rdf:resource="URI" /> NESTED_CONTENT ... </rdf:Bag> </RELATION_ELEMENT> ... </rdf:Description> +++ </rdf:RDF> +++ </annotation> +++ </SBML_ELEMENT>
The placeholder NESTED_CONTENT refers to other optional RDF elements such as "bqbiol:isDescribedBy" that describe a clarification or another annotation about the RELATION_ELEMENT in which it appears. Nested content allows one to, for example, describe protein modifications on species, or to add evidence codes for an annotation. Nested content relates to its containing RELATION_ELEMENT, not the other way around. It qualifies it, but does not change its meaning. As such, ignoring a NESTED_CONTENT does not affect the information provided by the containing RELATION_ELEMENT.
For more information about SBML annotations in general, please refer to Section 6 in the SBML Level 2 (Versions 2–4) or Level 3 specification documents.
Annotations that refer to controlled vocabularies are managed in libSBML using CVTerm objects. The relation-resource pairs discussed in the previous section are the "controlled vocabulary" terms that CVTerm is designed to store and manipulate. A set of RDF-based annotations attached to a given SBML <annotation> element are read by RDFAnnotationParser and converted into a list of these CVTerm objects. Each CVTerm object instance stores the following components of an annotation:
The qualifier, which can be a BioModels.net "biological qualifier", a BioModels.net "model qualifier", or an unknown qualifier (as far as the CVTerm class is concerned). Qualifiers are used in MIRIAM to indicate the nature of the relationship between the object being annotated and the resource. In CVTerm, the qualifiers can be manipulated using the methods CVTerm::getQualifierType(), CVTerm::setQualifierType(), and related methods.
The resource, represented by a URI (which, we must remind developers, is not the same as a URL). In the CVTerm class, the resource component can be manipulated using the methods CVTerm::addResource() and CVTerm::removeResource().
Note that a CVTerm contains a single qualifier, but possibly more than one resource. This corresponds to the possibility of an annotation that points to multiple resources, all of which are qualified by the same BioModels.net qualifier. The CVTerm object class supports this by supporting a list of resources.
Detailed explanations of the qualifiers defined by BioModels.net can be found at http://co.mbine.org/standards/qualifiers.
This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.
A Date object stores a reasonably complete representation of date and time. Its purpose is to serve as a way to store dates to be read and written in the W3C date format used in RDF Dublin Core annotations within SBML. The W3C date format is a restricted form of ISO 8601, the international standard for the representation of dates and times. A time and date value in this W3C format takes the form YYYY-MM-DDThh:mm:ssXHH:ZZ (e.g., 1997-07-16T19:20:30+01:00) where XHH:ZZ is the time zone offset. The libSBML Date object contains the following fields to represent these values:
2011.1 represents January, and so on.0 signifying + and 1 signifying -). See the paragraph below for further explanations.To illustrate the time zone offset, a value of -05:00 would correspond to USA Eastern Standard Time. In the Date object, this would require a value of 1 for the sign field, 5 for the hour offset and 0 for the minutes offset.
In the restricted RDF annotations used in SBML, described in Section 6 of the SBML Level 2 and Level 3 specification documents, date/time stamps can be used to indicate the time of creation and modification of a model. The following SBML model fragment illustrates this:
<model metaid="_180340" id="GMO" name="Goldbeter1991_MinMitOscil">
<annotation>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:dcterms="http://purl.org/dc/terms/"
xmlns:vCard="http://www.w3.org/2001/vcard-rdf/3.0#" >
<rdf:Description rdf:about="#_180340">
<dc:creator>
<rdf:Bag>
<rdf:li rdf:parseType="Resource">
<vCard:N rdf:parseType="Resource">
<vCard:Family>Shapiro</vCard:Family>
<vCard:Given>Bruce</vCard:Given>
</vCard:N>
<vCard:EMAIL>bshapiro@jpl.nasa.gov</vCard:EMAIL>
<vCard:ORG rdf:parseType="Resource">
<vCard:Orgname>NASA Jet Propulsion Laboratory</vCard:Orgname>
</vCard:ORG>
</rdf:li>
</rdf:Bag>
</dc:creator>
<dcterms:created rdf:parseType="Resource">
<dcterms:W3CDTF>2005-02-06T23:39:40+00:00</dcterms:W3CDTF>
</dcterms:created>
<dcterms:modified rdf:parseType="Resource">
<dcterms:W3CDTF>2005-09-13T13:24:56+00:00</dcterms:W3CDTF>
</dcterms:modified>
</rdf:Description>
</rdf:RDF>
</annotation>
</model>
An Event object defines when the event can occur, the variables that are affected by the event, and how the variables are affected. The effect of the event can optionally be delayed after the occurrence of the condition which invokes it. An event delay is defined using an object of class Delay.
The object class Delay is derived from SBase and adds a single subelement called "math". This subelement is used to hold MathML content. The mathematical formula represented by "math" must evaluate to a numerical value. It is used as the length of time between when the event is triggered and when the event's assignments are actually executed. If no delay is present on a given Event, a time delay of zero is assumed.
The expression in "math" must be evaluated at the time the event is triggered. The expression must always evaluate to a nonnegative number (otherwise, a nonsensical situation could arise where an event is defined to execute before it is triggered!).
In SBML Level 2 versions before Version 4, the units of the numerical value computed by the Delay's "math" expression are required to be in units of time, or the model is considered to have a unit consistency error. In Level 2 Version 4 as well as SBML Level 3, this requirement is relaxed; these specifications only stipulate that the units of the numerical value computed by a Delay instance's "math" expression should match the model's units of time (meaning the definition of the time units in the model). LibSBML respects these requirements, and depending on whether an earlier Version of SBML Level 2 is in use, libSBML may or may not flag unit inconsistencies as errors or merely warnings.
Note that units are not predefined or assumed for the contents of "math" in a Delay object; rather, they must be defined explicitly for each instance of a Delay object in a model. This is an important point to bear in mind when literal numbers are used in delay expressions. For example, the following Event instance would result in a warning logged by SBMLDocument::checkConsistency() about the fact that libSBML cannot verify the consistency of the units of the expression. The reason is that the formula inside the "math" element does not have any declared units, whereas what is expected in this context is units of time:
<model>
...
<listOfEvents>
<event useValuesFromTriggerTime="true">
...
<delay>
<math xmlns="http://www.w3.org/1998/Math/MathML">
<cn> 1 </cn>
</math>
</delay>
...
</event>
</listOfEvents>
...
</model>
The <cn> 1 </cn> within the mathematical formula of the delay above has no units declared. To make the expression have the needed units of time, literal numbers should be avoided in favor of defining Parameter objects for each quantity, and declaring units for the Parameter values. The following fragment of SBML illustrates this approach:
<model>
...
<listOfParameters>
<parameter id="transcriptionDelay" value="10" units="second"/>
</listOfParameters>
...
<listOfEvents>
<event useValuesFromTriggerTime="true">
...
<delay>
<math xmlns="http://www.w3.org/1998/Math/MathML">
<ci> transcriptionDelay </ci>
</math>
</delay>
...
</event>
</listOfEvents>
...
</model>
In SBML Level 3, an alternative approach is available in the form of the units attribute, which SBML Level 3 allows to appear on MathML cn elements. The value of this attribute can be used to indicate the unit of measurement to be associated with the number in the content of a cn element. The attribute is named units but, because it appears inside MathML element (which is in the XML namespace for MathML and not the namespace for SBML), it must always be prefixed with an XML namespace prefix for an SBML Level 3 namespace. The following is an example of this approach:
<model timeUnits="second" ...>
...
<listOfEvents>
<event useValuesFromTriggerTime="true">
...
<delay>
<math xmlns="http://www.w3.org/1998/Math/MathML"
xmlns:sbml="http://www.sbml.org/sbml/level3/version1/core">
<cn sbml:units="second"> 10 </cn>
</math>
</delay>
...
</event>
</listOfEvents>
...
</model>
In SBML Level 3 Version 2, the requirement that a Delay have a "math" subelement was relaxed, making it optional. In this case, the Delay remains undefined, and unless that information is provided in some other form (such as with an SBML Level 3 package), the Event behaves as if it had no Delay.
| typedef class ElementTransformer ElementTransformer_t |
An SBML Event object defines when the event can occur, the variables that are affected by it, how the variables are affected, and the event's relationship to other events. The effect of the event can optionally be delayed after the occurrence of the condition which invokes it.
The operation of Event is divided into two phases (even when the event is not delayed): one when the event is triggered, and the other when the event is executed. Trigger objects define the conditions for triggering an event, Delay objects define when the event is actually executed, EventAssignment objects define the effects of executing the event, and (in SBML Level 3) Priority objects influence the order of EventAssignment performance in cases of simultaneous events. Please consult the descriptions of Trigger, Delay, EventAssignment and Priority for more information.
In SBML Level 2 versions before Version 4, the semantics of Event time delays were defined such that the expressions in the event's assignments were always evaluated at the time the event was triggered. This definition made it difficult to define an event whose assignment formulas were meant to be evaluated at the time the event was executed (i.e., after the time period defined by the value of the Delay element, or after any other simultaneous event may have been executed and changed the model state). In SBML Level 2 Version 4 and in Level 3, the attribute "useValuesFromTriggerTime" on Event was added to allow a model to indicate the time at which the event's assignments are to be calculated, whether at the moment the event is triggered (if the value of the attribute is true), or at the moment of execution (if "useValuesFromTriggerTime"=false). If the event has a delay, the "useValuesFromTriggerTime" is likely to make a significant difference in the values used in the assignment, but the possibility of simultaneous events mean that even zero-delay events can have different results depending on the value of this attribute.
The definition of Event in SBML Level 2 Versions 1 and 2 includes an additional attribute called "timeUnits", which allowed the time units of the Delay to be set explicitly. Later Versions of SBML Level 2 as well as SBML Level 3 do not define this attribute. LibSBML supports this attribute for compatibility with previous versions of SBML Level 2; however, if a model in SBML Level 3 or Level 2 Versions 3–4 format sets the attribute, the consistency-checking method SBMLDocument::checkConsistency() will report an error.
The attribute "useValuesFromTriggerTime" was introduced in SBML Level 2 Version 4. Models defined in prior Versions of SBML Level 2 cannot use this attribute, and SBMLDocument::checkConsistency() will report an error if they do.
SBML Level 3 introduces several changes to the structure and components of Events compared to SBML Level 2. These changes fall into two main categories: changes to what is optional or required, and additions of new attributes and elements.
true); The changes to the attributes of Event are described below; the changes to Trigger and Priority are described in their respective sections.
The detailed semantics of events are described in the specification documents for each SBML Level/Version. Here we include the description from the SBML Level 1 Version 1. Any transition of a Trigger object's "math" formula from the value false to true will cause the enclosing Event object to trigger. Such a transition is not possible at the very start of a simulation (i.e., at time t = 0) unless the Trigger object's "initialValue" attribute has a value of false; this defines the value of the trigger formula to be false immediately prior to the start of simulation, thereby giving it the potential to change in value from false to true when the formula is evaluated at t = 0. If "initialValue"=true, then the trigger expression cannot transition from false to true at t = 0 but may do so at some time t > 0.
Consider an Event object definition E with delay d in which the Trigger object's "math" formula makes a transition in value from false to true at times t1 and t2. The EventAssignment within the Event object will have effect at t1 + d and t2 + d irrespective of the relative times of t1 and t2. For example, events can "overlap" so that t1 < t2 < t1 + d still causes an event assignments to occur at t1 + d and t2 + d.
It is entirely possible for two events to be executed simultaneously, and it is possible for events to trigger other events (i.e., an event assignment can cause an event to trigger). This leads to several points:
A software package should retest all event triggers after executing an event assignment in order to account for the possibility that the assignment causes another event trigger to transition from false to true. This check should be made after each individual Event object's execution, even when several events are to be executed simultaneously.
Any Event object whose Trigger "persistent" attribute has the value false must have its trigger expression reevaluated continuously between when the event is triggered and when it is executed. If its trigger expression ever evaluates to false, it must be removed from the queue of events pending execution and treated as any other event whose trigger expression evaluates to false.
Although the precise time at which events are executed is not resolved beyond the given execution point in simulated time, it is assumed that the order in which the events occur is resolved. This order can be significant in determining the overall outcome of a given simulation. When an event X triggers another event Y and event Y has zero delay, then event Y is added to the existing set of simultaneous events that are pending execution. Events X and Y form a cascade of events at the same point in simulation time. An event such as Y may have a special priority if it contains a Priority subobject.
All events in a model are open to being in a cascade. The position of an event in the event queue does not affect whether it can be in the cascade: event Y can be triggered whether it is before or after X in the queue of events pending execution. A cascade of events can be potentially infinite (never terminate); when this occurs a simulator should indicate this has occurred—it is incorrect for a simulator to break a cascade arbitrarily and continue the simulation without at least indicating that the infinite cascade occurred.
Simultaneous events having no defined priorities are executed in an undefined order. This does not mean that the behavior of the simulation is completely undefined; merely that the order of execution of these particular events is undefined. A given simulator may use any algorithm to choose an order as long as every event is executed exactly once.
Events with defined priorities are executed in the order implied by their Priority "math" formula values, with events having higher priorities being executed ahead of events with lower priorities, and events with identical priorities being executed in a random order with respect to one another (as determined at run-time by some random algorithm equivalent to coin-flipping). Newly-triggered events that are to be executed immediately (i.e., if they define no delays) should be inserted into the queue of events pending execution according to their priorities: events with higher priority values value must be inserted ahead of events with lower priority values and after any pending events with even higher priorities, and inserted randomly among pending events with the same priority values. Events without Priority objects must be inserted into the queue in some fashion, but the algorithm used to place it in the queue is undefined. Similarly, there is no restriction on the order of a newly-inserted event with a defined Priority with respect to any other pending Event without a defined Priority.
A model variable that is the target of one or more event assignments can change more than once when simultaneous events are processed at some time point t. The model's behavior (output) for such a variable is the value of the variable at the end of processing all the simultaneous events at time t.
In SBML Level 3 Version 2, several restrictions were lifted that have the potential to affect the semantics of an Event:
The Trigger subobject of an Event is optional. If missing, an Event is never triggered, unless an alternate triggering scheme is introduced by an SBML Level 3 package.
The "math" subelements of an Event Trigger, Delay, Priority, and EventAssignment are all optional. If any of these elements lack a "math" subelement, and that information is not supplied in an SBML Level 3 package, it is mathematically equivalent to the Trigger, Delay, Priority, or EventAssignment not being present at all.
The ListOfEventAssignments may be empty, which is mathematically equivalent to the Event not having a ListOfEventAssignments at all.
false, and all other values are interpreted as true. If a Boolean value is used in a numeric context, a true is interpreted as a 1, and a false is interpreted as a 0. This means (for example) that a Trigger value that changes from 0.0 to anything else is equivalent to changing from false to true. | typedef class EventAssignment EventAssignment_t |
Event contains an optional element called "listOfEventAssignments", of class ListOfEventAssignments. In every instance of an event definition in a model, the object's "listOfEventAssignments" element must have a non-empty list of one or more "eventAssignment" elements of class EventAssignment. The object class EventAssignment has one required attribute, "variable", and a required element, "math". Being derived from SBase, it also has all the usual attributes and elements of its parent class.
An Event object defines when the event can occur, the variables that are affected by the event, and how the variables are affected. The purpose of the EventAssignment object class is to define how variables are affected by an Event. In SBML Level 2, every Event object instance must have a nonempty list of event assignments; in SBML Level 3, the list of assignments is optional.
The operation of an Event is divided into two phases (regardless of whether a delay is involved): one phase when the event is triggered, and the other when the event is executed. EventAssignment objects are interpreted when an event is executed. The effects are described below.
The EventAssignment attribute "variable" must be the identifier of an existing Compartment, Species, SpeciesReference, or Parameter instance defined in the model. In SBML Level 3 Version 2, this list was expanded to include identifiers of SBML Level 3 package variables that have both mathematical meaning and the ability to be assigned. When the event is executed, the value of the model component identified by "variable" is changed by the EventAssignment to the value computed by the "math" element; that is, a species' quantity, species reference's stoichiometry, compartment's size or parameter's value are reset to the value computed by "math".
Certain restrictions are placed on what can appear in "variable":
The object identified by the value of the EventAssignment attribute "variable" must not have its "constant" attribute set to or default to true. (Constants cannot be affected by events.)
The "variable" attribute must not contain the identifier of a reaction. In SBML Level 2 and SBML Level 3 Version 1, only species, species references, compartment and parameter values may be set by an Event. In SBML Level 3 Version 2, the "variable" attribute may also be the identifier of an SBML Level 3 package element with mathematical meaning and the ability to be assigned a value. This situation may only arise if the SBML package is present in the SBML document with a package:required attribute of true
The value of every "variable" attribute must be unique among the set of EventAssignment structures within a given Event structure. In other words, a single event cannot have multiple EventAssignment objects assigning the same variable. (All of them would be performed at the same time when that particular Event triggers, resulting in indeterminacy.) However, separate Event instances can refer to the same variable.
If the variable attribute of an EventAssignment 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 event assignment 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".)
Note that the time of assignment of the object identified by the value of the "variable" attribute is always the time at which the Event is executed, not when it is triggered. The timing is controlled by the optional Delay in an Event. The time of assignment is not affected by the "useValuesFromTriggerTime" attribute on Event—that attribute affects the time at which the EventAssignment's "math" expression is evaluated. In other words, SBML allows decoupling the time at which the "variable" is assigned from the time at which its value expression is calculated.
The MathML expression contained in an EventAssignment defines the new value of the variable being assigned by the Event.
As mentioned above, the time at which the expression in "math" is evaluated is determined by the attribute "useValuesFromTriggerTime" on Event. If the attribute value is true, the expression must be evaluated when the event is triggered; more precisely, the values of identifiers occurring in MathML <ci> elements in the EventAssignment's "math" expression are the values they have at the point when the event triggered. If, instead, "useValuesFromTriggerTime"'s value is false, it means the values at execution time should be used; that is, the values of identifiers occurring in MathML <ci> elements in the EventAssignment's "math" expression are the values they have at the point when the event executed.
Between Version 4 and previous versions of SBML Level 2, the requirements regarding the matching of units between an EvengAssignment's formula and the units of the object identified by the "variable" attribute changed. Previous versions required consistency, but in SBML Level 2 Version 4 and in SBML Level 3, unit consistency is only recommended. More precisely:
In the case of a species, an EventAssignment sets the referenced species' quantity (concentration or amount of substance) to the value determined by the formula in the EventAssignment's "math" subelement. The units of the "math" formula should (in SBML Level 2 Version 4 and in Level 3) or must (in previous Versions of Level 2) be identical to the units of the species.
(SBML Level 3 only.) In the case of a species reference, an EventAssignment sets the stoichiometry of the reactant or product referenced by the SpeciesReference object to the value determined by the formula in the "math" element. The unit associated with the value produced by the "math" formula should be dimensionless, because reactant and product stoichiometries in reactions are dimensionless quantities.
In the case of a compartment, an EventAssignment sets the referenced compartment's size to the size determined by the formula in the "math" subelement of the EventAssignment. The overall units of the formula should (in SBML Level 2 Version 4 and in Level 3) or must (in previous Versions of Level 2) be identical to the units specified for the size of the compartment identified by the EventAssignment's "variable" attribute.
In the case of a parameter, an EventAssignment sets the referenced parameter's value to that determined by the formula in "math". The overall units of the formula should (in SBML Level 2 Version 4 and Level 3) or must (in previous Versions of Level 2) be identical to the units defined for the parameter.
Note that the formula placed in the "math" element has no assumed units. The consistency of the units of the formula, and the units of the entity which the assignment affects, must be explicitly established just as in the case of the value of the Delay subelement. An approach similar to the one discussed in the context of Delay may be used for the formula of an EventAssignment.
In SBML Level 3 Version 2, the requirement that an EventAssignment have a "math" subelement was relaxed, making it optional. In this case, the EventAssignment remains undefined, and unless that information is provided in some other form (such as with an SBML Level 3 package), the Event behaves as if it had no EventAssignment.
| typedef class ExpectedAttributes ExpectedAttributes_t |
| typedef class FunctionDefinition FunctionDefinition_t |
The FunctionDefinition structure associates an identifier with a function definition. This identifier can then be used as the function called in subsequent MathML content elsewhere in an SBML model.
FunctionDefinition has one required attribute, "id", to give the function a unique identifier by which other parts of an SBML model definition can refer to it. A FunctionDefinition instance 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).
FunctionDefinition has a "math" subelement containing a MathML expression defining the function body. In SBML Level 2 and SBML Level 3 Version 1, that "math" subelement is required; in SBML Level 3 Version 2, this restriction was relaxed, making the "math" subelement optional. The content of this element can only be a MathML "lambda" element. The "lambda" element must begin with zero or more "bvar" elements, followed by any other of the elements in the MathML subset allowed in SBML Level 2 except "lambda" (i.e., a "lambda" element cannot contain another "lambda" element). This is the only place in SBML where a "lambda" element can be used. The function defined by a FunctionDefinition is only available for use in other MathML elements that follow the FunctionDefinition definition in the model. (These restrictions prevent recursive and mutually-recursive functions from being expressed.)
A further restriction on the content of "math" is that it cannot contain references to variables other than the variables declared to the "lambda" itself. That is, the contents of MathML "ci" elements inside the body of the "lambda" can only be the variables declared by its "bvar" elements, or the identifiers of other FunctionDefinition instances in the model. This means must be written so that all variables or parameters used in the MathML content are passed to them via their function parameters. In SBML Level 2, this restriction applies also to the MathML csymbol elements for time and delay; in SBML Level 3, it additionally applies to the csymbol element for avogadro.
In SBML Level 3 Version 2, if no math element is present in the FunctionDefinition, the function has no mathematical meaning defined in SBML Level 3 Core. This situation may arise when models are incomplete, or when additional meanings are provided by an SBML Level 3 package.
| typedef class IdentifierTransformer IdentifierTransformer_t |
| typedef class InitialAssignment InitialAssignment_t |
SBML Level 2 Versions 2–4 and SBML Level 3 provide two ways of assigning initial values to entities in a model. The simplest and most basic is to set the values of the appropriate attributes in the relevant components; for example, the initial value of a model parameter (whether it is a constant or a variable) can be assigned by setting its "value" attribute directly in the model definition. However, this approach is not suitable when the value must be calculated, because the initial value attributes on different components such as species, compartments, and parameters are single values and not mathematical expressions. In those situations, the InitialAssignment construct can be used; it permits the calculation of the value of a constant or the initial value of a variable from the values of other quantities in a model.
As explained below, the provision of InitialAssignment does not mean that models necessarily must use this construct when defining initial values of quantities in a model. If a value can be set directly using the relevant attribute of a component in a model, then that approach may be more efficient and more portable to other software tools. InitialAssignment should be used when the other mechanism is insufficient for the needs of a particular model.
The InitialAssignment construct has some similarities to AssignmentRule. The main differences are: (a) an InitialAssignment can set the value of a constant whereas an AssignmentRule cannot, and (b) unlike AssignmentRule, an InitialAssignment definition only applies up to and including the beginning of simulation time, i.e., t \(\leq\) 0, while an AssignmentRule applies at all times.
InitialAssignment has a required attribute, "symbol", whose value must follow the guidelines for identifiers described in the SBML specification (e.g., Section 3.3 in the Level 2 Version 4 specification). The value of this attribute in an InitialAssignment object can be the identifier of a Compartment, Species, SpeciesReference (in SBML Level 3), global Parameter, or (as of SBML Level 3 Version 2) the identifier of a SBML Level 3 package element with mathematical meaning. The InitialAssignment defines the initial value of the constant or variable referred to by the "symbol" attribute. (The attribute's name is "symbol" rather than "variable" because it may assign values to constants as well as variables in a model.) Note that an initial assignment cannot be made to reaction identifiers, that is, the "symbol" attribute value of an InitialAssignment cannot be an identifier that is the "id" attribute value of a Reaction object in the model. This is identical to a restriction placed on rules.
InitialAssignment also has a "math" subelement that contains a MathML expression used to calculate the value of the constant or the initial value of the variable. This subelement is required in SBML Level 2 and SBML Level 3 Version 1, but the requirement was relaxed in SBML Level 3 Version 2, making it optional. The units of the value computed by the formula in the "math" subelement should (in SBML Level 2 Version 4 and in SBML Level 3) or must (in previous Versions) be identical to be the units associated with the identifier given in the "symbol" attribute. (That is, the units are the units of the species, compartment, or parameter, as appropriate for the kind of object identified by the value of "symbol".)
InitialAssignment was introduced in SBML Level 2 Version 2. It is not available in SBML Level 2 Version 1 nor in any version of Level 1.
The value calculated by an InitialAssignment object overrides the value assigned to the given symbol by the object defining that symbol. For example, if a compartment's "size" attribute is set in its definition, and the model also contains an InitialAssignment having that compartment's identifier as its "symbol" attribute value, then the interpretation is that the "size" assigned in the Compartment object should be ignored and the value assigned based on the computation defined in the InitialAssignment. Initial assignments can take place for Compartment, Species, global Parameter, SpeciesReference (in Level 3), and SBML Level 3 package elements (in Level 3 Version 2), regardless of the value of their "constant" attribute.
The actions of all InitialAssignment objects are in general terms the same, but differ in the precise details depending on the type of variable being set:
In the case of a species, an InitialAssignment sets the referenced species' initial quantity (concentration or amount of substance) to the value determined by the formula in the "math" subelement. The overall units of the formula should (in SBML Level 2 Version 4 and in SBML Level 3) or must (in previous Versions) be the same as the units specified for the species.
In the case of a compartment, an InitialAssignment sets the referenced compartment's initial size to the size determined by the formula in "math". The overall units of the formula should (in SBML Level 2 Version 4 and in SBML Level 3) or must (in previous Versions) be the same as the units specified for the size of the compartment.
In the case of a parameter, an InitialAssignment sets the referenced parameter's initial value to that determined by the formula in "math". The overall units of the formula should (in SBML Level 2 Version 4 and SBML Level 3) or must (in previous Versions) be the same as the units defined for the parameter.
(For SBML Level 3 only) In the case of a species reference, an initial assignment sets the initial value 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", because reactant and product stoichiometries in reactions are dimensionless quantities.
(For SBML Level 3 Version 2 only) In the case of an object from an SBML Level 3 package, an InitialAssignment sets the referenced object's initial value (however such values are defined by the 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), 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).
If the symbol attribute of an InitialAssignment 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 assignment must be ignored–the object's initial 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, initial assignments establish values that are in effect prior to and including the start of simulation time, i.e., t \(\leq\) 0. Section 3.4.8 in the SBML Level 2 Version 4 and SBML Level 3 specifications provides information about the interpretation of assignments, rules, and entity values for simulation time up to and including the start time t = 0; this is important for establishing the initial conditions of a simulation if the model involves expressions containing the delay "csymbol".
There cannot be two initial assignments for the same symbol in a model; that is, a model must not contain two or more InitialAssignment objects that both have the same identifier as their "symbol" attribute value. A model must also not define initial assignments and assignment rules for the same entity. That is, there cannot be both an InitialAssignment and an AssignmentRule for the same symbol in a model, because both kinds of constructs apply prior to and at the start of simulated time—allowing both to exist for a given symbol would result in indeterminism).
The ordering of InitialAssignment objects is not significant. The combined set of InitialAssignment, AssignmentRule and KineticLaw objects form a set of assignment statements that must be considered as a whole. The combined set of assignment statements should not contain algebraic loops: a chain of dependency between these statements should terminate. (More formally, consider the directed graph of assignment statements where nodes are a model's assignment statements and directed arcs exist for each occurrence of a symbol in an assignment statement "math" attribute. The directed arcs in this graph start from the statement assigning the symbol and end at the statement that contains the symbol in their math elements. Such a graph must be acyclic.)
Finally, it is worth being explicit about the expected behavior in the following situation. Suppose (1) a given symbol has a value x assigned to it in its definition, and (2) there is an initial assignment having the identifier as its "symbol" value and reassigning the value to y, and (3) the identifier is also used in the mathematical formula of a second initial assignment. What value should the second initial assignment use? It is y, the value assigned to the symbol by the first initial assignment, not whatever value was given in the symbol's definition. This follows directly from the behavior described above: if an InitialAssignment object exists for a given symbol, then the symbol's value is overridden by that initial assignment.
| typedef class KineticLaw KineticLaw_t |
An object of class KineticLaw is used to describe the rate at which the process defined by a given Reaction takes place. KineticLaw has subelements called "math" (for MathML content) and "listOfParameters" (of class ListOfParameters), in addition to the attributes and subelements it inherits from SBase.
KineticLaw's "math" subelement for holding a MathML formula (required through SBML Level 3 Version 1, but optional as of SBML Level 3 Version 2) defines the rate of the reaction. The formula may refer to other entities in a model as well as local parameter definitions within the scope of the Reaction (see below). It is important to keep in mind, however, that the only Species identifiers that can be used in this formula are those declared in the lists of reactants, products and modifiers in the Reaction structure. (In other words, before a species can be referenced in the KineticLaw, it must be declared in one of those lists.)
KineticLaw provides a way to define local parameters whose identifiers can be used in the "math" formula of that KineticLaw instance. Prior to SBML Level 3, these parameter definitions are stored inside a "listOfParameters" subelement containing Parameter objects; in SBML Level 3, this is achieved using a specialized object class called LocalParameter and the containing subelement is called "listOfLocalParameters". In both cases, the parameters so defined are only visible within the KineticLaw (or, as of SBML Level 3 Version 2, only visible within the parent Reaction); they cannot be accessed outside. A local parameter within one reaction is not visible from within another reaction, nor is it visible to any other construct outside of the KineticLaw in which it is defined. In addition, another important feature is that if such a Parameter (or in Level 3, LocalParameter) object has the same identifier as another object in the scope of the enclosing Model, the definition inside the KineticLaw takes precedence. In other words, within the KineticLaw's "math" formula, references to local parameter identifiers shadow any identical global identifiers.
The values of local parameters defined within KineticLaw objects cannot change. In SBML Level 3, this quality is built into the LocalParameter construct. In Level 2, where the same kind of Parameter object class is used as for global parameters, the Parameter objects' "constant" attribute must always have a value of true (either explicitly or left to its default value).
A common misconception is that different classes of objects (e.g., species, compartments, parameters) in SBML have different identifier scopes. They do not. The implication is that if a KineticLaw's local parameter definition uses an identifier identical to any other identifier defined in the model outside the KineticLaw, even if the other identifier does not belong to a parameter type of object, the local parameter's identifier takes precedence within that KineticLaw's "math" formula. It is not an error in SBML for identifiers to shadow each other this way, but can lead to confusing and subtle errors.
In SBML Level 2 Version 1, the SBML specification included two additional attributes on KineticLaw called "substanceUnits" and "timeUnits". They were removed beginning with SBML Level 2 Version 2 because further research determined they introduced many problems. The most significant problem was that their use could easily lead to the creation of valid models whose reactions nevertheless could not be integrated into a system of equations without outside knowledge for converting the quantities used. Examination of real-life models revealed that a common reason for using "substanceUnits" on KineticLaw was to set the units of all reactions to the same set of substance units, something that is better achieved by using UnitDefinition to redefine "substance" for the whole Model.
As mentioned above, in SBML Level 2 Versions 2–4, local parameters are of class Parameter. In SBML Level 3, the class of object is LocalParameter.
In SBML Level 3 Version 2, the scope of the LocalParameter was expanded to the entire Reaction, instead of just the KineticLaw. This introduced a single new restriction: an L3v2 LocalParameter may not now shadow the id of any Species referenced by a SpeciesReference in the same Reaction. Other than that, there is no difference in any core construct. However, packages may take advantage of this new scope by adding elements to the Reaction that may now reference a LocalParameter defined in the same Reaction.
| typedef class L3ParserSettings L3ParserSettings_t |
This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.
This class implements basic vanilla lists for libSBML. It was developed in the time before libSBML was converted to C++ and used C++ STL library classes more extensively. At some point in the future, this List class may be removed in favor of using standard C++ classes.
This class is distinct from ListOf because the latter is derived from the SBML SBase class, whereas this List class is not. ListOf can only be used when a list is actually intended to implement an SBML ListOfX class. This is why libSBML has both a List and a ListOf.
This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.
The ListOf class in libSBML is a utility class that serves as the parent class for implementing the ListOf__ classes. It provides methods for working generically with the various SBML lists of objects in a program. LibSBML uses this separate list class rather than ordinary C++; lists, so that it can provide the methods and features associated with SBase.
Whether a given ListOf element may be empty or not depends on the element in question, and on what level and version of SBML it is being used for. For ListOf elements in SBML Level 3 Version 1 and prior, no core list and few package lists could be empty. As of SBML Level 3 Version 2, the rules were relaxed, and lists were allowed to be empty. In libSBML, documents created for Level 3 Version 2 will be written with empty ListOf's if that ListOf contains some other 'extra' information: an attribute such as metaid or sboTerm, a child '<notes>' or '<annotation>', or information from a SBML Level 3 package.
The relationship between the lists and the rest of an SBML model is illustrated by the following (for SBML Level 2 Version 4):
SBML Level 3 Version 1 has essentially the same structure as Level 2 Version 4, depicted above, but SBML Level 3 Version 2 allows containers to contain zero or more of the relevant object, instead of requiring at least one. As such, libsbml will write out an otherwise-empty ListOf___ element that has any optional attribute set (such as 'id' or 'metaid'), that has an optional child (such as a 'notes' or 'annotation'), or that has attributes or children set from any SBML Level 3 package, whether or not the ListOf___ has any other children.
Readers may wonder about the motivations for using the ListOf___ containers in SBML. A simpler approach in XML might be to place the components all directly at the top level of the model definition. The choice made in SBML is to group them within XML elements named after ListOfClassname, in part because it helps organize the components. More importantly, the fact that the container classes are derived from SBase means that software tools can add information about the lists themselves into each list container's "annotation".
| typedef class LocalParameter LocalParameter_t |
LocalParameter has been introduced in SBML Level 3 to serve as the object class for parameter definitions that are intended to be local to a Reaction. Objects of class LocalParameter never appear at the Model level; they are always contained within ListOfLocalParameters lists which are in turn contained within KineticLaw objects.
Like its global Parameter counterpart, the LocalParameter object class is used to define a symbol associated with a value; this symbol can then be used in a model's mathematical formulas (and specifically, for LocalParameter, reaction rate formulas). Unlike Parameter, the LocalParameter class does not have a "constant" attribute: local parameters within reactions are always constant.
LocalParameter 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 parameter can also have an optional "name" attribute of type string. Identifiers and names must be used according to the guidelines described in the SBML specifications.
The optional attribute "value" determines the value (of type double) assigned to the parameter. A missing value for "value" implies that the value either is unknown, or to be obtained from an external source, or determined by an initial assignment. The unit of measurement associated with the value of the parameter can be specified using the optional attribute "units". Here we only mention briefly some notable points about the possible unit choices, but readers are urged to consult the SBML specification documents for more information:
In SBML Level 3, there are no constraints on the units that can be assigned to parameters in a model; there are also no units to inherit from the enclosing Model object.
"substance", "time", "volume", "area" or "length"; or the identifier of a new unit defined in the list of unit definitions in the enclosing Model structure. There are no constraints on the units that can be chosen from these sets. There are no default units for local parameters. As with all other major SBML components, LocalParameter is derived from SBase, and the methods defined on SBase are available on LocalParameter.
In SBML Level 3 Version 2, the scope of the LocalParameter was expanded slightly to officially encompass the entire Reaction instead of just the KineticLaw in which it appears. This has no effect on models using only SBML Level 3 Core constructs, but has the potential to allow SBML Level 3 Packages to include elements in a Reaction that could reference a LocalParameter from that Reaction's KineticLaw. It also means that no LocalParameter may have the same "id" as a referenced Species in any SimpleSpeciesReference in that Reaction.
In an SBML model definition, a single object of class Model serves as the overall container for the lists of the various model components. All of the lists are optional, but if a given list container is present within the model, the list must not be empty; that is, it must have length one or more. The following are the components and lists permitted in different Levels and Versions of SBML in version 5.20.2 of libSBML:
In SBML Level 1, the components are: UnitDefinition, Compartment, Species, Parameter, Rule, and Reaction. Instances of the classes are placed inside instances of classes ListOfUnitDefinitions, ListOfCompartments, ListOfSpecies, ListOfParameters, ListOfRules, and ListOfReactions.
In SBML Level 2 Version 1, the components are: FunctionDefinition, UnitDefinition, Compartment, Species, Parameter, Rule, Reaction and Event. Instances of the classes are placed inside instances of classes ListOfFunctionDefinitions, ListOfUnitDefinitions, ListOfCompartments, ListOfSpecies, ListOfParameters, ListOfRules, ListOfReactions, and ListOfEvents.
In SBML Level 2 Versions 2, 3 and 4, the components are: FunctionDefinition, UnitDefinition, CompartmentType, SpeciesType, Compartment, Species, Parameter, InitialAssignment, Rule, Constraint, Reaction and Event. Instances of the classes are placed inside instances of classes ListOfFunctionDefinitions, ListOfUnitDefinitions, ListOfCompartmentTypes, ListOfSpeciesTypes, ListOfCompartments, ListOfSpecies, ListOfParameters, ListOfInitialAssignments, ListOfRules, ListOfConstraints, ListOfReactions, and ListOfEvents.
Although all the lists are optional, there are dependencies between SBML components such that defining some components requires defining others. An example is that defining a species requires defining a compartment, and defining a reaction requires defining a species. The dependencies are explained in more detail in the SBML specifications.
In addition to the above lists and attributes, the Model class in both SBML Level 2 and Level 3 has the usual two attributes of "id" and "name", and both are optional. As is the case for other SBML components with "id" and "name" attributes, they must be used according to the guidelines described in the SBML specifications. (Within the frameworks of SBML Level 2 and Level 3, a Model object identifier has no assigned meaning, but extension packages planned for SBML Level 3 are likely to make use of this identifier.)
Finally, SBML Level 3 has introduced a number of additional Model attributes. They are discussed in a separate section below.
LibSBML provides two main mechanisms for creating objects: class constructors (e.g., Species::Species() ), and createObject() methods (such as Model::createSpecies()) provided by certain Object classes such as Model. These multiple mechanisms are provided by libSBML for flexibility and to support different use-cases, but they also have different implications for the overall model structure.
In general, the recommended approach is to use the createObject() methods. These methods both create an object and link it to the parent in one step. Here is an example:
The createObject() methods return a pointer to the object created, but they also add the object to the relevant list of object instances contained in the parent. (These lists become the <listOfObjects> elements in the finished XML rendition of SBML.) In the example above, Model::createSpecies() adds the created species directly to the <listOfSpecies> list in the model. Subsequently, methods called on the species change the species in the model (which is what is expected in most situations).
To make it easier for applications to do whatever they need, libSBML version 5.20.2 is relatively lax when it comes to enforcing correctness and completeness of models during model construction and editing. Essentially, libSBML will not in most cases check automatically that a model's components have valid attribute values, or that the overall model is consistent and free of errors—even obvious errors such as duplication of identifiers. This allows applications great leeway in how they build their models, but it means that software authors must take deliberate steps to ensure that the model will be, in the end, valid SBML. These steps include such things as keeping track of the identifiers used in a model, manually performing updates in certain situations where an entity is referenced in more than one place (e.g., a species that is referenced by multiple SpeciesReference objects), and so on.
That said, libSBML does provide powerful features for deliberately performing validation of SBML when an application decides it is time to do so. The interfaces to these facilities are on the SBMLDocument class, in the form of SBMLDocument::checkInternalConsistency() and SBMLDocument::checkConsistency(). Please refer to the documentation for SBMLDocument for more information about this.
While applications may play fast and loose and live like free spirits during the construction and editing of SBML models, they should always make sure to call SBMLDocument::checkInternalConsistency() and/or SBMLDocument::checkConsistency() before writing out the final version of an SBML model.
As mentioned above, the Model class has a number of optional attributes in SBML Level 3. These are "substanceUnits", "timeUnits", "volumeUnits", "areaUnits", "lengthUnits", "extentUnits", and "conversionFactor. The following provide more information about them.
The "substanceUnits" attribute is used to specify the unit of measurement associated with substance quantities of Species objects that do not specify units explicitly. If a given Species object definition does not specify its unit of substance quantity via the "substanceUnits" attribute on the Species object instance, then that species inherits the value of the Model "substanceUnits" attribute. If the Model does not define a value for this attribute, then there is no unit to inherit, and all species that do not specify individual "substanceUnits" attribute values then have no declared units for their quantities. The SBML Level 3 specifications provide more details.
Note that when the identifier of a species appears in a model's mathematical expressions, the unit of measurement associated with that identifier is not solely determined by setting "substanceUnits" on Model or Species. Please see the discussion about units given in the documentation for the Species class.
The "timeUnits" attribute on SBML Level 3's Model object is used to specify the unit in which time is measured in the model. This attribute on Model is the only way to specify a unit for time in a model. It is a global attribute; time is measured in the model everywhere in the same way. This is particularly relevant to Reaction and RateRule objects in a model: all Reaction and RateRule objects in SBML define per-time values, and the unit of time is given by the "timeUnits" attribute on the Model object instance. If the Model "timeUnits" attribute has no value, it means that the unit of time is not defined for the model's reactions and rate rules. Leaving it unspecified in an SBML model does not result in an invalid model in SBML Level 3; however, as a matter of best practice, we strongly recommend that all models specify units of measurement for time.
The attributes "volumeUnits", "areaUnits" and "lengthUnits" together are used to set the units of measurements for the sizes of Compartment objects in an SBML Level 3 model when those objects do not otherwise specify units. The three attributes correspond to the most common cases of compartment dimensions: "volumeUnits" for compartments having a "spatialDimensions" attribute value of "3", "areaUnits" for compartments having a "spatialDimensions" attribute value of "2", and "lengthUnits" for compartments having a "spatialDimensions" attribute value of "1". The attributes are not applicable to compartments whose "spatialDimensions" attribute values are not one of "1", "2" or "3".
If a given Compartment object instance does not provide a value for its "units" attribute, then the unit of measurement of that compartment's size is inherited from the value specified by the Model "volumeUnits", "areaUnits" or "lengthUnits" attribute, as appropriate based on the Compartment object's "spatialDimensions" attribute value. If the Model object does not define the relevant attribute, then there are no units to inherit, and all Compartment objects that do not set a value for their "units" attribute then have no units associated with their compartment sizes.
The use of three separate attributes is a carry-over from SBML Level 2. Note that it is entirely possible for a model to define a value for two or more of the attributes "volumeUnits", "areaUnits" and "lengthUnits" simultaneously, because SBML models may contain compartments with different numbers of dimensions.
Reactions are processes that occur over time. These processes involve events of some sort, where a single ``reaction event'' is one in which some set of entities (known as reactants, products and modifiers in SBML) interact, once. The extent of a reaction is a measure of how many times the reaction has occurred, while the time derivative of the extent gives the instantaneous rate at which the reaction is occurring. Thus, what is colloquially referred to as the "rate of the reaction" is in fact equal to the rate of change of reaction extent.
In SBML Level 3, the combination of "extentUnits" and "timeUnits" defines the units of kinetic laws in SBML and establishes how the numerical value of each KineticLaw object's mathematical formula is meant to be interpreted in a model. The units of the kinetic laws are taken to be "extentUnits" divided by "timeUnits".
Note that this embodies an important principle in SBML Level 3 models: all reactions in an SBML model must have the same units for the rate of change of extent. In other words, the units of all reaction rates in the model must be the same. There is only one global value for "extentUnits" and one global value for "timeUnits".
The attribute "conversionFactor" in SBML Level 3's Model object defines a global value inherited by all Species object instances that do not define separate values for their "conversionFactor" attributes. The value of this attribute must refer to a Parameter object instance defined in the model. The Parameter object in question must be a constant; ie it must have its "constant" attribute value set to "true".
If a given Species object definition does not specify a conversion factor via the "conversionFactor" attribute on Species, then the species inherits the conversion factor specified by the Model "conversionFactor" attribute. If the Model does not define a value for this attribute, then there is no conversion factor to inherit. More information about conversion factors is provided in the SBML Level 3 specifications.
| typedef class ModelCreator ModelCreator_t |
This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.
The SBML specification beginning with Level 2 Version 2 defines a standard approach to recording model history and model creator information in a form that complies with MIRIAM ("Minimum Information Requested in the Annotation of biochemical Models", Nature Biotechnology, vol. 23, no. 12, Dec. 2005). For the model creator, this form involves the use of parts of the vCard representation. LibSBML provides the ModelCreator class as a convenience high-level interface for working with model creator data. Objects of class ModelCreator can be used to store and carry around creator data within a program, and the various methods in this object class let callers manipulate the different parts of the model creator representation.
The ModelCreator class mirrors the structure of the MIRIAM model creator annotations in SBML. The following template illustrates these different fields when they are written in XML form:
<vCard:N rdf:parseType="Resource"> <vCard:Family>family name</vCard:Family> <vCard:Given>given name</vCard:Given> </vCard:N> ... <vCard:EMAIL>email address</vCard:EMAIL> ... <vCard:ORG rdf:parseType="Resource"> <vCard:Orgname>organization</vCard:Orgname> </vCard:ORG>
Each of the separate data values family name, given name, email address, and organization can be set and retrieved via corresponding methods in the ModelCreator class. These methods are documented in more detail below.
| typedef class ModelHistory ModelHistory_t |
This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.
The SBML specification beginning with Level 2 Version 2 defines a standard approach to recording optional model history and model creator information in a form that complies with MIRIAM ("Minimum Information Requested in the Annotation of biochemical Models", Nature Biotechnology, vol. 23, no. 12, Dec. 2005). LibSBML provides the ModelHistory class as a convenient high-level interface for working with model history data.
Model histories in SBML consist of one or more model creators, a single date of creation, and one or more modification dates. The overall XML form of this data takes the following form:
<dc:creator>
<rdf:Bag>
<rdf:li rdf:parseType="Resource">
+++
<vCard:N rdf:parseType="Resource">
<vCard:Family>family name</vCard:Family>
<vCard:Given>given name</vCard:Given>
</vCard:N>
+++
<vCard:EMAIL>email address</vCard:EMAIL>
+++
<vCard:ORG rdf:parseType="Resource">
<vCard:Orgname>organization name</vCard:Orgname>
</vCard:ORG>
+++
</rdf:li>
...
</rdf:Bag>
</dc:creator>
<dcterms:created rdf:parseType="Resource">
<dcterms:W3CDTF>creation date</dcterms:W3CDTF>
</dcterms:created>
<dcterms:modified rdf:parseType="Resource">
<dcterms:W3CDTF>modification date</dcterms:W3CDTF>
</dcterms:modified>
...
In the template above, the underlined portions are optional, the symbol +++ is a placeholder for either no content or valid XML content that is not defined by the annotation scheme, and the ellipses ... are placeholders for zero or more elements of the same form as the immediately preceding element. The various placeholders for content, namely family name, given name, email address, organization, creation date, and modification date are data that can be filled in using the various methods on the ModelHistory class described below.
| typedef class ModifierSpeciesReference ModifierSpeciesReference_t |
Sometimes a species appears in the kinetic rate formula of a reaction but is itself neither created nor destroyed in that reaction (for example, because it acts as a catalyst or inhibitor). In SBML, all such species are simply called modifiers without regard to the detailed role of those species in the model. The Reaction structure provides a way to express which species act as modifiers in a given reaction. This is the purpose of the list of modifiers available in Reaction. The list contains instances of ModifierSpeciesReference structures.
The ModifierSpeciesReference structure inherits the mandatory attribute "species" and optional attributes "id" and "name" from the parent class SimpleSpeciesReference. See the description of SimpleSpeciesReference for more information about these.
The value of the "species" attribute must be the identifier of a species defined in the enclosing Model; this species is designated as a modifier for the current reaction. A reaction may have any number of modifiers. It is permissible for a modifier species to appear simultaneously in the list of reactants and products of the same reaction where it is designated as a modifier, as well as to appear in the list of reactants, products and modifiers of other reactions in the model.
| typedef class Parameter Parameter_t |
A Parameter is used in SBML to define a symbol associated with a value; this symbol can then be used in mathematical formulas in a model. By default, parameters have constant value for the duration of a simulation, and for this reason are called parameters instead of variables in SBML, although it is crucial to understand that SBML parameters represent both concepts. Whether a given SBML parameter is intended to be constant or variable is indicated by the value of its "constant" attribute.
SBML's Parameter has a required attribute, "id", that gives the parameter a unique identifier by which other parts of an SBML model definition can refer to it. A parameter can also have an optional "name" attribute of type string. Identifiers and names must be used according to the guidelines described in the SBML specifications.
The optional attribute "value" determines the value (of type double) assigned to the parameter. A missing value for "value" implies that the value either is unknown, or to be obtained from an external source, or determined by an initial assignment. The unit of measurement associated with the value of the parameter can be specified using the optional attribute "units". Here we only mention briefly some notable points about the possible unit choices, but readers are urged to consult the SBML specification documents for more information:
In SBML Level 3, there are no constraints on the units that can be assigned to parameters in a model; there are also no units to inherit from the enclosing Model object (unlike the case for, e.g., Species and Compartment).
"substance", "time", "volume", "area" or "length"; or the identifier of a new unit defined in the list of unit definitions in the enclosing Model structure. There are no constraints on the units that can be chosen from these sets. There are no default units for parameters. The Parameter structure has another boolean attribute named "constant" that is used to indicate whether the parameter's value can vary during a simulation. (In SBML Level 3, the attribute is mandatory and must be given a value; in SBML Levels below Level 3, the attribute is optional.) A value of true indicates the parameter's value cannot be changed by any construct except InitialAssignment. Conversely, if the value of "constant" is false, other constructs in SBML, such as rules and events, can change the value of the parameter.
SBML Level 3 uses a separate object class, LocalParameter, for parameters that are local to a Reaction's KineticLaw. In Levels prior to SBML Level 3, the Parameter class is used both for definitions of global parameters, as well as reaction-local parameters stored in a list within KineticLaw objects. Parameter objects that are local to a reaction (that is, those defined within the KineticLaw structure of a Reaction) cannot be changed by rules and therefore are implicitly always constant; consequently, in SBML Level 2, parameter definitions within Reaction structures should not have their "constant" attribute set to false.
What if a global parameter has its "constant" attribute set to false, but the model does not contain any rules, events or other constructs that ever change its value over time? Although the model may be suspect, this situation is not strictly an error. A value of false for "constant" only indicates that a parameter can change value, not that it must.
As with all other major SBML components, Parameter is derived from SBase, and the methods defined on SBase are available on Parameter.
In SBML Level 3 Version 2, many restrictions were lifted requiring only Boolean values in Boolean contexts, and numeric values in numeric contexts. This means that a Parameter may now be used as a Boolean, despite canonically having a numeric value. To be consistent, one should always assign it a value of true or false, and use it in Boolean contexts exclusively. It would be appropriate to give it an SBO value of 602 ('Logical parameter') if one chooses to do this.
| typedef class Priority Priority_t |
The Priority object class (which was introduced in SBML Level 3 Version 1), like Delay, is derived from SBase and contains a MathML formula stored in the element "math". This formula is used to compute a dimensionless numerical value that influences the order in which a simulator is to perform the assignments of two or more events that happen to be executed simultaneously. The formula may evaluate to any double value (and thus may be a positive or negative number, or zero), with positive numbers taken to signifying a higher priority than zero or negative numbers. If no Priority object is present on a given Event object, no priority is defined for that event.
For the purposes of SBML, simultaneous event execution is defined as the situation in which multiple events have identical times of execution. The time of execution is calculated as the sum of the time at which a given event's Trigger is triggered plus its Delay duration, if any. Here, identical times means mathematically equal instants in time. (In practice, simulation software adhering to this specification may have to rely on numerical equality instead of strict mathematical equality; robust models will ensure that this difference will not cause significant discrepancies from expected behavior.)
If no Priority subobjects are defined for two or more Event objects, then those events are still executed simultaneously but their order of execution is undefined by the SBML Level 3 specification. A software implementation may choose to execute such simultaneous events in any order, as long as each event is executed only once and the requirements of checking the "persistent" attribute (and acting accordingly) are satisfied.
If Priority subobjects are defined for two or more simultaneously-triggered events, the order in which those particular events must be executed is dictated by their Priority objects, as follows. If the values calculated using the two Priority objects' "math" expressions differ, then the event having the higher priority value must be executed before the event with the lower value. If, instead, the two priority values are mathematically equal, then the two events must be triggered in a random order. It is important to note that a random order is not the same as an undefined order: given multiple runs of the same model with identical conditions, an undefined ordering would permit a system to execute the events in (for example) the same order every time (according to whatever scheme may have been implemented by the system), whereas the explicit requirement for random ordering means that the order of execution in different simulation runs depends on random chance. In other words, given two events A and B, a randomly-determined order must lead to an equal chance of executing A first or B first, every time those two events are executed simultaneously.
A model may contain a mixture of events, some of which have Priority subobjects and some do not. Should a combination of simultaneous events arise in which some events have priorities defined and others do not, the set of events with defined priorities must trigger in the order determined by their Priority objects, and the set of events without Priority objects must be executed in an undefined order with respect to each other and with respect to the events with Priority subobjects. (Note that undefined order does not necessarily mean random order, although a random ordering would be a valid implementation of this requirement.)
The following example may help further clarify these points. Suppose a model contains four events that should be executed simultaneously, with two of the events having Priority objects with the same value and the other two events having Priority objects with the same, but different, value. The two events with the higher priorities must be executed first, in a random order with respect to each other, and the remaining two events must be executed after them, again in a random order, for a total of four possible and equally-likely event executions: A-B-C-D, A-B-D-C, B-A-C-D, and B-A-D-C. If, instead, the model contains four events all having the same Priority values, there are 4! or 24 possible orderings, each of which must be equally likely to be chosen. Finally, if none of the four events has a Priority subobject defined, or even if exactly one of the four events has a defined Priority, there are again 24 possible orderings, but the likelihood of choosing any particular ordering is undefined; the simulator can choose between events as it wishes. (The SBML specification only defines the effects of priorities on Event objects with respect to other Event objects with priorities. Putting a priority on a single Event object in a model does not cause it to fall within that scope.)
An event's Priority object "math" expression must be evaluated at the time the Event is to be executed. During a simulation, all simultaneous events have their Priority values calculated, and the event with the highest priority is selected for next execution. Note that it is possible for the execution of one Event object to cause the Priority value of another simultaneously-executing Event object to change (as well as to trigger other events, as already noted). Thus, after executing one event, and checking whether any other events in the model have been triggered, all remaining simultaneous events that either (i) have Trigger objects with attributes "persistent"=false or (ii) have Trigger expressions that did not transition from true to false, must have their Priority expression reevaluated. The highest-priority remaining event must then be selected for execution next.
The unit associated with the value of a Priority object's "math" expression should be dimensionless. This is because the priority expression only serves to provide a relative ordering between different events, and only has meaning with respect to other Priority object expressions. The value of Priority objects is not comparable to any other kind of object in an SBML model.
In SBML Level 3 Version 2, the requirement that a Priority have a "math" subelement was relaxed, making it optional. In this case, the Priority remains undefined, and unless that information is provided in some other form (such as with an SBML Level 3 package), the Event behaves as if it had no Priority.
| typedef class RateRule RateRule_t |
The rule type RateRule is derived from the parent class Rule. 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 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 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 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 "variable" attribute and a SpeciesReference "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 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 sets the rate of change of the compartment's size to the value determined by the formula in the "math" subelement of the RateRule 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 sets the rate of change of the parameter's value to that determined by the formula in the "math" subelement of the RateRule 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 object's "unit" attribute value divided by the model-wide unit of time.
In SBML Level 2 and Level 3 Version 1, the "math" subelement of the RateRule is required. In SBML Level 3 Version 2, this rule is relaxed, and the subelement is optional. If a RateRule 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 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 \(\leq\) 0.
As mentioned in the description of AssignmentRule, a model must not contain more than one RateRule or AssignmentRule 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.
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:
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.
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.
Similarly, the combined set of RateRule and Reaction 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 objects, and the 'species' attributes of the SpeciesReference objects in each Reaction). 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 or KineticLaw 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.
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 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.)
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.
| typedef class Reaction Reaction_t |
A reaction represents any transformation, transport or binding process, typically a chemical reaction, that can change the quantity of one or more species. In SBML, a reaction is defined primarily in terms of the participating reactants and products (and their corresponding stoichiometries), along with optional modifier species, an optional rate at which the reaction takes place, and optional parameters.
As with other major objects in SBML, Reaction has a mandatory attribute, "id", used to give the reaction an identifier. The identifier must be a text string conforming to the identifer syntax permitted in SBML. In SBML Level 2 and Level 3, the reaction "id" identifier can be used in mathematical formulas elsewhere in an SBML model to represent the rate of that reaction; this usage is explained below. Reaction also has an optional "name" attribute, of type string. The "id" and "name" must be used according to the guidelines described in the SBML specification.
The species participating as reactants, products, and/or modifiers in a reaction are declared using lists of SpeciesReference and/or ModifierSpeciesReference instances stored in subelements "listOfReactants", "listOfProducts" and "listOfModifiers". Certain restrictions are placed on the appearance of species in reaction definitions:
The ability of a species to appear as a reactant or product of any reaction in a model is governed by certain flags in that species' definition; see the definition of Species for more information.
Any species appearing in the mathematical formula of the subelement "kineticLaw" (described below) of a Reaction must be declared in at least one of that Reaction's lists of reactants, products, and/or modifiers. Put another way, it is an error for a reaction's kinetic law formula to refer to species that have not been declared for that reaction.
A reaction can contain up to one KineticLaw object in a subelement named "kineticLaw". It defines the speed at which the process defined by the reaction takes place. The description of KineticLaw provides more details about its use. Note that although the inclusion of a KineticLaw object in an instance of a Reaction component is optional, there is no useful default that can be substituted in place of a missing rate expression in a reaction. Moreover, a reaction's rate cannot be defined in any other way in SBML—InitialAssignment, AssignmentRule, RateRule, AlgebraicRule, Event, and other constructs in SBML cannot be used to set the reaction rate separately. Nevertheless, for some modeling applications, reactions without any defined rate can be perfectly acceptable.
Reaction also has a boolean attribute named "reversible" for indicating whether the reaction is reversible. This attribute is optional in SBML Level 2, with a default of true; it is mandatory in SBML Level 3 (with no default value). To say that a reaction is reversible is to say it can proceed in either the forward or the reverse direction. Although the reversibility of a reaction can sometimes be deduced by inspecting its rate expression, this is not always the case, especially for complicated expressions. Moreover, the need in SBML to allow rate expressions (i.e., KineticLaw) to be optional leads to the need for a separate flag indicating reversibility. Note that labeling a reaction as irreversible is an assertion that the reaction always proceeds in the given forward direction. (Why else would it be flagged as irreversible?) This implies the rate expression in the KineticLaw always has a non-negative value during simulations. Software tools could provide a means of optionally testing that this condition holds. The presence of reversibility information in two places (i.e., the rate expression and the "reversible" attribute on Reaction) leaves open the possibility that a model could contain contradictory information, but the creation of such a model would be an error on the part of the software generating it.
The Reaction object class has another boolean attribute called "fast". This attribute is optional in SBML Level 2, with a default of false; it is mandatory in SBML Level 3 (with no default value). In SBML Level 3 Version 2, a value of true for the "fast" attribute is deprecated in favor of all reactions having a "fast" value of false. It is used to indicate that a reaction occurs on a vastly faster time scale than others in a system. Readers are directed to the SBML Level 2 Version 4 specification, which provides more detail about the conditions under which a reaction can be considered to be fast in this sense. SBML Level 1 and Level 2 Version 1 incorrectly claimed that software tools could ignore this attribute if they did not implement support for the corresponding concept; however, further research in SBML has revealed that this is not true, and "fast" cannot be ignored if it is set to true. SBML Level 2 Versions 2–4 therefore stipulate that if a model has any reactions with "fast" set to true, a software tool must be able to respect the attribute or else indicate to the user that it does not have the capacity to do so. Analysis software cannot ignore the value of the "fast" attribute because doing so may lead to different results as compared to a software system that does make use of "fast".
false. Users should be aware that even for previous levels/versions of the specification, "fast" attribute values of true never achieved widespread support, and many software packages may ignore it. To achieve the same or similar effects as setting the fast attribute to true for a given reaction, the KineticLaw attribute should be constructed to produce a value in the desired time scale, or else the reaction could be replaced with an AssignmentRule or AlgebraicRule.In SBML Level 3, the Reaction object has an additional optional attribute named "compartment", whose value must be the identifier of a compartment defined in the enclosing Model object. The "compartment" attribute can be used to indicate the compartment in which the reaction is assumed to take place. If the attribute is present, its value must be the identifier of a Compartment object defined in the enclosing Model object. Similar to the "reversible" attribute, the value of the "compartment" attribute has no direct impact on the construction of mathematical equations for the SBML model. When a kinetic law is given for a reaction, the compartment location may already be implicit in the kinetic law (although this cannot always be guaranteed). Nevertheless, software tools may find the "compartment" attribute value useful for such purposes as analyzing the structure of the model, guiding the modeler in constructing correct rate formulas, and visualization purposes.
Readers are urged to read the SBML specification for more details about the proper use of Reaction.
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 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) |
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:
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.
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.
Similarly, the combined set of RateRule and Reaction 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 objects, and the 'species' attributes of the SpeciesReference objects in each Reaction). 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 or KineticLaw 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.
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 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.)
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.
Most components in SBML are derived from a single abstract base type, SBase. In addition to serving as the parent class for most other classes of objects in SBML, this base type is designed to allow a modeler or a software package to attach arbitrary information to each major element or list in an SBML model.
SBase has an optional subelement called "notes". It is intended to serve as a place for storing optional information intended to be seen by humans. An example use of the "notes" element would be to contain formatted user comments about the model element in which the "notes" element is enclosed. There are certain conditions on the XHTML content permitted inside the "notes" element; 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.
SBase has another optional subelement called "annotation". Whereas the "notes" element described above is a container for content to be shown directly to humans, the "annotation" element is a container for optional software-generated content not meant to be shown to humans. The element's content type is XML type "any", allowing essentially arbitrary data content. SBML places only a few restrictions on the organization of the content; these are intended to help software tools read and write the data as well as help reduce conflicts between annotations added by different tools. As is the case with "notes", it is important to refer to the SBML specification document corresponding to the SBML Level and Version of your model for more information about the requirements for "annotation" content.
It is worth pointing out that the "annotation" element in the definition of SBase exists in order that software developers may attach optional application-specific data to the elements in an SBML model. However, it is important that this facility not be misused. In particular, it is critical that data essential to a model definition or that can be encoded in existing SBML elements is not stored in "annotation". Parameter values, functional dependencies between model elements, etc., should not be recorded as annotations. It is crucial to keep in mind the fact that data placed in annotations can be freely ignored by software applications. If such data affects the interpretation of a model, then software interoperability is greatly impeded.
SBML Level 2 introduced an optional SBase attribute named "metaid" for supporting metadata annotations using RDF (Resource Description Format). The attribute value has the data type XML ID, the XML identifier type, which means each "metaid" value must be globally unique within an SBML file. (Importantly, this uniqueness criterion applies across any attribute with type XML ID, not just the "metaid" attribute used by SBML—something to be aware of if your application-specific XML content inside the "annotation" subelement happens to use XML ID.) The "metaid" value serves to identify a model component for purposes such as referencing that component from metadata placed within "annotation" subelements.
Beginning with SBML Level 2 Version 2, SBase has an optional attribute named "sboTerm" for supporting the use of the Systems Biology Ontology. In SBML proper, the data type of the attribute is a string of the form "SBO:NNNNNNN", where "NNNNNNN" is a seven digit integer number; libSBML simplifies the representation by only storing the "NNNNNNN" integer portion. Thus, in libSBML, the "sboTerm" attribute on SBase has data type int, and SBO identifiers are stored simply as integers. (For convenience, SBase offers methods for returning both the integer form and a text-string form of the SBO identifier.) SBO terms are a type of optional annotation, and each different class of SBML object derived from SBase imposes its own requirements about the values permitted for "sboTerm". More details can be found in SBML specifications for Level 2 Version 2 and above.
Finally, note that, in the list of methods on SBase, there is no public constructor because SBase is an abstract class. The constructors reside in the subclasses derived from SBase.
SBML Level 2 Versions 2, 3 and 4, and Level 3, define a proposed regular format for encoding two particular categories of annotations: (a) references to controlled vocabulary terms and database identifiers which define and describe biological and biochemical entities in a model; and (b) descriptions of the provenance of a model, including its author(s) and modification history.
| typedef class SBaseExtensionPoint SBaseExtensionPoint_t |
This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.
The use of SBaseExtensionPoint is relatively straightforward. The class needs to be used for each extended SBML object implemented using SBMLDocumentPlugin or SBasePlugin. Doing so requires knowing just two things:
"core", but a SBML Level 3 package could conceivably extend another Level 3 package.The typical use of SBaseExtensionPoint is illustrated by the following code fragment:
The code above shows two core SBML components being extended: the document object, and the Model object. These extended objects are created elsewhere (not shown) as the GroupsSBMLDocumentPlugin and GroupsModelPlugin objects. The corresponding SBaseExtensionPoint objects are handed as arguments to the constructor for SBasePluginCreator to create the connection between the extended core components and the overall package extension (here, for the Groups package, with the GroupsExtension object).
The code above is typically placed in the implementation of the init() method of the package class derived from SBMLExtension. (For the example above, it would be in the GroupsExtension.cpp file.)
| typedef class SBasePlugin SBasePlugin_t |
| typedef class SBasePluginCreatorBase SBasePluginCreatorBase_t |
| typedef class SBMLDocument SBMLDocument_t |
LibSBML uses the class SBMLDocument as a top-level container for storing SBML content and data associated with it (such as warnings and error messages). The two primary means of reading an SBML model, SBMLReader::readSBML() and SBMLReader::readSBMLFromString(), both return a pointer to an SBMLDocument object. From there, callers can inquire about any errors encountered (e.g., using SBMLDocument::getNumErrors()), access the Model object, and perform other actions such as consistency-checking and model translation.
When creating fresh models programmatically, the starting point is typically the creation of an SBMLDocument object instance. The SBMLDocument constructor accepts arguments for the SBML Level and Version of the model to be created. After creating the SBMLDocument object, calling programs then typically call SBMLDocument::createModel() almost immediately, and then proceed to call the methods on the Model object to fill out the model's contents.
SBMLDocument corresponds roughly to the class Sbml defined in the SBML Level 2 specification and SBML in the Level 3 specification. It does not have a direct correspondence in SBML Level 1. (However, to make matters simpler for applications, libSBML creates an SBMLDocument no matter whether the model is Level 1, Level 2 or Level 3.) In its barest form, when written out in XML format for (e.g.) SBML Level 2 Version 4, the corresponding structure is the following:
<sbml xmlns="http://www.sbml.org/sbml/level2/version4" level="2" version="4"> ... </sbml>
SBMLDocument is derived from SBase, and therefore contains the usual SBase attributes (in SBML Level 2 and Level 3) of "metaid" and "sboTerm", as well as the subelements "notes" and "annotation". It also contains the attributes "level" and "version" indicating the Level and Version of the SBML data structure. These can be accessed using the methods defined by the SBase class for that purpose.
One of the most important features of libSBML is its ability to perform SBML validation to ensure that a model adheres to the SBML specification for whatever Level+Version combination the model uses. SBMLDocument provides the methods for running consistency-checking and validation rules on the SBML content.
First, a brief explanation of the rationale is in order. In libSBML versions up to and including the version 3.3.x series, the individual methods for creating and setting attributes and other components were quite lenient, and allowed a caller to compose SBML entities that might not, in the end, represent valid SBML. This allowed applications the freedom to do things such as save incomplete models (which is useful when models are being developed over long periods of time). In the version 4.x series, libSBML is somewhat stricter, but still permits structures to be created independently and the results to be combined in a separate step. In all these cases, it means that a separate validation step is necessary when a calling program finally wants to finish a complete SBML document.
The primary interface to this validation facility is SBMLDocument's SBMLDocument::checkInternalConsistency() and SBMLDocument::checkConsistency(). The former verifies the basic internal consistency and syntax of an SBML document, and the latter implements more elaborate validation rules (both those defined by the SBML specifications, as well as additional rules offered by libSBML).
The checks performed by SBMLDocument::checkInternalConsistency() are hardwired and cannot be changed by calling programs, but the validation performed by SBMLDocument::checkConsistency() is under program control using the method SBMLDocument::setConsistencyChecks(). Applications can selectively disable specific kinds of checks that they may not be interested in, by calling SBMLDocument::setConsistencyChecks() with appropriate parameters.
These methods have slightly different relevance depending on whether a model is created programmaticaly from scratch, or whether it is read in from a file or data stream. The following list summarizes the possible scenarios.
Scenario 1: Creating a model from scratch. Before writing out the model,
Scenario 2: Reading a model from a file or data stream. After reading the model,
An example of using the consistency-checking and validation facilities is provided in this manual in the section Tutorial: creating a complete model.
It should be noted that as of SBML Level 3 Version 2, the Model became an optional child of SBMLDocument, instead of being required. This means that one can no longer use SBMLDocument::getModel() as a cheap method of checking if an SBML document was read in properly: the more robust getError methods detailed above must be used instead.
LibSBML provides facilities for limited translation of SBML between Levels and Versions of the SBML specifications. The method for doing is is setLevelAndVersion() . In general, models can be converted upward without difficulty (e.g., from SBML Level 1 to Level 2, or from an earlier Version of Level 2 to the latest Version of Level 2). Sometimes models can be translated downward as well, if they do not use constructs specific to more advanced Levels of SBML.
Calling SBMLDocument::setLevelAndVersion() will not necessarily lead to a successful conversion. The method will return a boolean value to indicate success or failure. Callers must check the error log (see next section) attached to the SBMLDocument object after calling SBMLDocument::setLevelAndVersion() in order to assess whether any problems arose.
If an application is interested in translating to a lower Level and/or Version of SBML within a Level, the following methods allow for prior assessment of whether there is sufficient compatibility to make a translation possible:
Some changes between Versions of SBML Level 2 may lead to unexpected behaviors when attempting conversions in either direction. For example, SBML Level 2 Version 4 relaxed the requirement for consistency in units of measurement between expressions annd quantities in a model. As a result, a model written in Version 4, if converted to Version 3 with no other changes, may fail validation as a Version 3 model because Version 3 imposed stricter requirements on unit consistency.
Other changes between SBML Level 2 and Level 3 make downward conversions challenging. In some cases, it means that a model converted to Level 2 from Level 3 will contain attributes that were not explicitly given in the Level 3 model, because in Level 2 these attributes may have been optional or have default values.
Upon reading a model, SBMLDocument logs any problems encountered while reading the model from the file or data stream. The log contains objects that record diagnostic information about any notable issues that arose. Whether the problems are warnings or errors, they are both reported through a single common interface involving the object class SBMLError.
The methods SBMLDocument::getNumErrors(), SBMLDocument::getError() and SBMLDocument::printErrors() allow callers to interact with the warnings or errors logged. Alternatively, callers may retrieve the entire log as an SBMLErrorLog object using the method SBMLDocument::getErrorLog(). The SBMLErrorLog object provides some alternative methods for interacting with the set of errors and warnings. In either case, applications typically should first call SBMLDocument::getNumErrors() to find out if any issues have been logged after specific libSBML operations such as the ones discussed in the sections above. If they have, then an application will should proceed to inspect the individual reports using either the direct interfaces on SBMLDocument or using the methods on the SBMLErrorLog object.
An example of using the error facility is provided in this manual in the section Tutorial: creating a complete model.
| typedef class SBMLDocumentPlugin SBMLDocumentPlugin_t |
This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.
The SBMLDocumentPlugin class is a specialization of SBasePlugin designed specifically for extending SBMLDocument. All package extensions must extend SBMLDocument to implement support for SBML Level 3 packages; these extensions can be subclasses of this class or from a derived class of this class.
All packages must additionally define a required flag named required, which indicates whether that package's constructs can be used to change the core mathematics of the <model> child of the <sbml> element. If they can, this attribute must be set true, and if they cannot, this attribute must be set false.
The specification for a SBML Level 3 package will define the changes to the SBML <sbml> element. Packages typically do not make any changes beyond adding an attribute named "required" (discussed below), so in most cases, the extension of SBMLDocument is very simple. However, some packages do more. For instance, the Hierarchical Model Composition package adds subobjects for lists of model definitions. SBMLDocumentPlugin supports all these cases.
A package extension will only define one subclass of SBMLDocumentPlugin. Below, we describe in detail the different parts of a subclass definition.
The derived class must override the constructor, copy constructor, assignment operator (operator=) and clone() methods from SBasePlugin.
At minimum, it is necessary for a package implementation to add the "required" attribute to the SBML <sbml> element mandated by SBML for all Level 3 packages, and this is done using this class as a base. If the 'required' attribute is the only addition necessary for a particular SBML Level 3 package, then the subclass of SBMLDocumentPlugin for the package can have a very simple implementation. Some Level 3 packages add additional attributes or elements to <sbml>, and their implementations would go into the subclassed SBMLDocumentPlugin.
SBMLDocumentPlugin provides methods with default implementations that support managing the "required" attribute, so package extension code does not need to provide implementations—they only need to set the correct value for the SBML Level 3 package based on its specification. The following are the virtual methods for working with the "required" attribute. Package extensions would only need to override them in special circumstances:
setRequired(bool value): This method sets the value of the flag.getRequired(): This method gets the value of the "required" flag.isSetRequired(): This method tests if the value has been set.unsetRequired(): This method unsets the value of the "required" flag.An extended SBMLDocument object may need more than just the "required" attribute, depending on what is defined in the specification for the package being implemented. Data attributes on the extended <sbml> object in an SBML package will have one of the data types std::string, double, int, or bool. Subelements/subobjects will normally be derived from the ListOf class or from SBase.
The additional data members must be properly initialized in the class constructor, and must be properly copied in the copy constructor and assignment operator.
If the extended component is defined by the SBML Level 3 package to have attributes, then the extended SBMLDocumentPlugin class definition needs to override the following internal methods that come from SBasePlugin (the base class of SBMLDocumentPlugin) and provide appropriate implementations:
addExpectedAttributes(ExpectedAttributes& attributes): This method should add the attributes that are expected to be found on this kind of extended component in an SBML file or data stream.readAttributes(XMLAttributes& attributes, ExpectedAttributes& expectedAttributes): This method should read the attributes expected to be found on this kind of extended component in an SBML file or data stream.hasRequiredAttributes(): This method should return true if all of the required attribute for this extended component are present on instance of the object.writeAttributes(XMLOutputStream& stream): This method should write out the attributes of an extended component. The implementation should use the different kinds of writeAttribute methods defined by XMLOutputStream to achieve this.If the extended component is defined by the Level 3 package to have subcomponents (i.e., full XML elements rather than mere attributes), then the extended class definition needs to override the following internal methods on SBasePlugin (the base class of SBMLDocumentPlugin) and provide appropriate implementations:
createObject(XMLInputStream& stream): Subclasses must override this method to create, store, and then return an SBML object corresponding to the next XMLToken in the XMLInputStream. To do this, implementations can use methods like peek() on XMLInputStream to test if the next object in the stream is something expected for the package. For example, LayoutModelPlugin uses peek() to examine the next element in the input stream, then tests that element against the Layout namespace and the element name "listOfLayouts" to see if it's the single subcomponent (ListOfLayouts) permitted on a Model object using the Layout package. If it is, it returns the appropriate object.connectToParent(SBase *sbase): This creates a parent-child relationship between a given extended component and its subcomponent(s).setSBMLDocument(SBMLDocument* d): This method should set the parent SBMLDocument object on the subcomponent object instances, so that the subcomponent instances know which SBMLDocument contains them.enablePackageInternal(std::string& pkgURI, std::string& pkgPrefix, bool flag): This method should enable or disable the subcomponent based on whether a given XML namespace is active.writeElements(XMLOutputStream& stream): This method must be overridden to provide an implementation that will write out the expected subcomponents/subelements to the XML output stream.readOtherXML(SBase* parentObject, XMLInputStream& stream): This function should be overridden if elements of annotation, notes, MathML content, etc., need to be directly parsed from the given XMLInputStream object.hasRequiredElements(): This method should return true if a given object contains all the required subcomponents defined by the specification for that SBML Level 3 package.If the package needs to add additional xmlns attributes to declare additional XML namespace URIs, the extended class should override the following method coming from SBasePlugin (the parent class of SBMLDocumentPlugin):
writeXMLNS(XMLOutputStream& stream): This method should write out any additional XML namespaces that might be needed by a package implementation.Extended SBMLDocumentPlugin implementations can add whatever additional utility methods are useful for their implementation.
| typedef class SBMLError SBMLError_t |
This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.
When a libSBML operation on SBML content results in an error, or when there is something wrong with the SBML content, the problems are reported as SBMLError objects. These are generally stored in an SBMLErrorLog object; this log object, in turn, is kept in the SBMLDocument object containing the SBML content. Applications can obtain the list of logged errors using SBMLDocument::getErrorLog() and then use the methods provided by SBMLErrorLog to access individual SBMLError objects. (Note that despite the word "error" in the name, SBMLError objects are used to represent not only "true" errors, but also warnings and some informational diagnostics. The name is a historical hold-over from early versions of libSBML, in which the object really was only used to report errors.)
Each SBMLError object instance has an identification number that identifies the nature of the problem. This "error id" number will be up to five digits long, and it will be listed in one of two enumerations: SBMLErrorCode_t (described below) or XMLErrorCode_t (described in the documentation for the class XMLError). The former enumeration contains all the SBML validation rule numbers listed in the appendices of the SBML specification documents, as well as some additional libSBML-specific error codes.
Error codes are useful mainly for software. For human readers, SBMLError also includes text messages that describe the nature of a given problem. The messages can be accessed using SBMLError::getShortMessage() and SBMLError::getMessage(). The former provides a brief one-line description of the issue, while SBMLError::getMessage() provides a more detailed text, including (if appropriate) references to sections of the SBML specifications where relevant topics are discussed. These text strings are suitable for displaying to human users.
An SBMLError object also contains a category code; its value may be retrieved using the method SBMLError::getCategory(). Category values are drawn from the enumeration SBMLErrorCategory_t described below. Categories are used to partition errors into distinct conceptual groups. This is principally used by the libSBML validation system to group classes of validation checks. For example, LIBSBML_CAT_IDENTIFIER_CONSISTENCY is the category for tests that check identifier consistency; LIBSBML_CAT_MATHML_CONSISTENCY is the category for MathML consistency checking; and so on.
In addition, SBMLError also has a severity code. Its value may be retrieved using the method SBMLError::getSeverity(). The possible severity values are the same as those reported by XMLError. Severity levels currently range from informational (LIBSBML_SEV_INFO) to fatal errors (LIBSBML_SEV_FATAL). They can be used by an application to evaluate how serious a given problem is.
SBMLError also tracks the Level 3 package extension, if any, was responsible for a given warning or error. Each diagnostic code logged by an libSBML extension for SBML Level 3 packages includes a record of the package that logged it. It can be retrieved using SBMLError::getPackage(). The information is a simple text string; the string will be the nickname of the package, such as "comp" for the Hierarchical Model Composition package, "fbc" for the Flux Balance Constraints package, and so on. If the value returned by SBMLError::getPackage() is an empty string or has the value "core", then the error came from libSBML core.
Finally, SBMLError records the line and column near where the problem occurred in the SBML content. The values may be retrieved using the methods SBMLError::getLine() and SBMLError::getColumn(). We say "near", because a lot of factors affect how accurate the line/column information ultimately is. For example, different XML parsers have different conventions for which line and column number they report for a particular problem (which makes a difference when a problem involves an opening XML tag on one line and a closing tag on another line). In some situations, some parsers report invalid line and/or column numbers altogether. If this occurs, libSBML sets the line and/or column number in the SBMLError object to the the value of the maximum unsigned long integer representable on the platform where libSBML is running. (This is equal to the constant named ULONG_MAX in C and C++.) The probability that a true line or column number in an SBML model would equal this value is vanishingly small; thus, if an application encounters these values in an XMLError object, it can assume no valid line/column number could be provided by libSBML in that situation.
SBMLErrorCode_t is an enumeration of all SBML-level error, warning and informational diagnostic codes. Every SBMLError object has an error code value that can be either a value from this enumeration, or a value from the XMLErrorCode_t enumeration (see the documentation for XMLError). The latter values apply when the error or warning signifies a basic XML issue rather than an SBML issue per se. The values of SBMLErrorCode_t are distinguished from those of XMLErrorCode_t by being numbered 10000 and higher, while the XML layer's codes are 9999 and lower. The method SBMLError::getErrorId() returns the error code of a given SBMLError object instance.
The following is a table of the symbolic names of SBMLErrorCode_t values and the meaning of each code. In this table, the right-hand columns titled "L1V1", "L1V2", etc. refer to Levels and Versions of the SBML specifications, and the entries in each column refer to whether the severity of the condition in that particular Level+Version of SBML. The codes stand for the following:
| = Not applicable | |
| = Warning | |
| = Error | |
| = Fatal |
The text shown in the "Meaning" is the text returned by the SBMLError::getShortMessage() method on a given SBMLError object. A longer and (hopefully) clearer explanation of the issue is returned by SBMLError::getMessage().
The error codes come from different lists depending on whether they're from libSBML core or from an SBML Level 3 package extension. The errors below come from XMLErrorCode_t and SBMLErrorCode_t (for core), and CompSBMLErrorCode_t, FbcSBMLErrorCode_t, LayoutSBMLErrorCode_t, and QualSBMLErrorCode_t (for packages).
| Enumerator | Meaning | L1 V1 | L1 V2 | L2 V1 | L2 V2 | L2 V3 | L2 V4 | L3 V1 | L3 V2 |
|---|---|---|---|---|---|---|---|---|---|
| XMLUnknownError | Unknown error | ||||||||
| XMLOutOfMemory | Out of memory | ||||||||
| XMLFileUnreadable | File unreadable | ||||||||
| XMLFileUnwritable | File unwritable | ||||||||
| XMLFileOperationError | File operation error | ||||||||
| XMLNetworkAccessError | Network access error | ||||||||
| InternalXMLParserError | Internal XML parser error | ||||||||
| UnrecognizedXMLParserCode | Unrecognized XML parser code | ||||||||
| XMLTranscoderError | Transcoder error | ||||||||
| MissingXMLDecl | Missing XML declaration | ||||||||
| MissingXMLEncoding | Missing XML encoding attribute | ||||||||
| BadXMLDecl | Bad XML declaration | ||||||||
| BadXMLDOCTYPE | Bad XML DOCTYPE | ||||||||
| InvalidCharInXML | Invalid character | ||||||||
| BadlyFormedXML | Badly formed XML | ||||||||
| UnclosedXMLToken | Unclosed token | ||||||||
| InvalidXMLConstruct | Invalid XML construct | ||||||||
| XMLTagMismatch | XML tag mismatch | ||||||||
| DuplicateXMLAttribute | Duplicate attribute | ||||||||
| UndefinedXMLEntity | Undefined XML entity | ||||||||
| BadProcessingInstruction | Bad XML processing instruction | ||||||||
| BadXMLPrefix | Bad XML prefix | ||||||||
| BadXMLPrefixValue | Bad XML prefix value | ||||||||
| MissingXMLRequiredAttribute | Missing required attribute | ||||||||
| XMLAttributeTypeMismatch | Attribute type mismatch | ||||||||
| XMLBadUTF8Content | Bad UTF8 content | ||||||||
| MissingXMLAttributeValue | Missing attribute value | ||||||||
| BadXMLAttributeValue | Bad attribute value | ||||||||
| BadXMLAttribute | Bad XML attribute | ||||||||
| UnrecognizedXMLElement | Unrecognized XML element | ||||||||
| BadXMLComment | Bad XML comment | ||||||||
| BadXMLDeclLocation | Bad XML declaration location | ||||||||
| XMLUnexpectedEOF | Unexpected EOF | ||||||||
| BadXMLIDValue | Bad XML ID value | ||||||||
| BadXMLIDRef | Bad XML IDREF | ||||||||
| UninterpretableXMLContent | Uninterpretable XML content | ||||||||
| BadXMLDocumentStructure | Bad XML document structure | ||||||||
| InvalidAfterXMLContent | Invalid content after XML content | ||||||||
| XMLExpectedQuotedString | Expected quoted string | ||||||||
| XMLEmptyValueNotPermitted | Empty value not permitted | ||||||||
| XMLBadNumber | Bad number | ||||||||
| XMLBadColon | Colon character not permitted | ||||||||
| MissingXMLElements | Missing XML elements | ||||||||
| XMLContentEmpty | Empty XML content | ||||||||
| UnknownError | Encountered unknown internal libSBML error | ||||||||
| NotUTF8 | File does not use UTF-8 encoding | ||||||||
| UnrecognizedElement | Encountered unrecognized element | ||||||||
| NotSchemaConformant | Document does not conform to the SBML XML schema | ||||||||
| L3NotSchemaConformant | Document is not well-formed XML | ||||||||
| InvalidMathElement | Invalid MathML | ||||||||
| DisallowedMathMLSymbol | Disallowed MathML symbol found | ||||||||
| DisallowedMathMLEncodingUse | Use of the MathML 'encoding' attribute is not allowed on this element | ||||||||
| DisallowedDefinitionURLUse | Use of the MathML 'definitionURL' attribute is not allowed on this element | ||||||||
| BadCsymbolDefinitionURLValue | Invalid <csymbol> 'definitionURL' attribute value | ||||||||
| DisallowedMathTypeAttributeUse | Use of the MathML 'type' attribute is not allowed on this element | ||||||||
| DisallowedMathTypeAttributeValue | Disallowed MathML 'type' attribute value | ||||||||
| LambdaOnlyAllowedInFunctionDef | Use of <lambda> not permitted outside of FunctionDefinition objects | ||||||||
| BooleanOpsNeedBooleanArgs | Non-Boolean argument given to Boolean operator | ||||||||
| NumericOpsNeedNumericArgs | Non-numerical argument given to numerical operator | ||||||||
| ArgsToEqNeedSameType | Arguments to <eq> and <neq> must have the same data types | ||||||||
| PiecewiseNeedsConsistentTypes | Terms in a <piecewise> expression must have consistent data types | ||||||||
| PieceNeedsBoolean | The second argument of a <piece> expression must yield a Boolean value | ||||||||
| ApplyCiMustBeUserFunction | A <ci> element in this context must refer to a function definition | ||||||||
| ApplyCiMustBeModelComponent | A <ci> element in this context must refer to a model component | ||||||||
| KineticLawParametersAreLocalOnly | Cannot use a KineticLaw local parameter outside of its local scope | ||||||||
| MathResultMustBeNumeric | A formula's result in this context must be a numerical value | ||||||||
| OpsNeedCorrectNumberOfArgs | Incorrect number of arguments given to MathML operator | ||||||||
| InvalidNoArgsPassedToFunctionDef | Incorrect number of arguments given to function invocation | ||||||||
| DisallowedMathUnitsUse | Attribute 'units' is only permitted on <cn> elements | ||||||||
| InvalidUnitsValue | Invalid value given for the 'units' attribute | ||||||||
| CiCannotReference0DCompartment | A <ci> element cannot reference a 0D compartment | ||||||||
| RateOfTargetMustBeCi | A 'rateOf' <csymbol> must target only a single <ci> element | ||||||||
| RateOfTargetCannotBeAssigned | The target of a 'rateOf' <csymbol> cannot be assigned | ||||||||
| RateOfSpeciesTargetCompartmentNot | Compartments of non-substance <species> referenced by 'rateOf' must not vary | ||||||||
| DuplicateComponentId | Duplicate 'id' attribute value | ||||||||
| DuplicateUnitDefinitionId | Duplicate unit definition 'id' attribute value | ||||||||
| DuplicateLocalParameterId | Duplicate local parameter 'id' attribute value | ||||||||
| MultipleAssignmentOrRateRules | Multiple rules for the same variable are not allowed | ||||||||
| MultipleEventAssignmentsForId | Multiple event assignments for the same variable are not allowed | ||||||||
| EventAndAssignmentRuleForId | An event assignment and an assignment rule must not have the same value for 'variable' | ||||||||
| DuplicateMetaId | Duplicate 'metaid' attribute value | ||||||||
| InvalidSBOTermSyntax | Invalid syntax for an 'sboTerm' attribute value | ||||||||
| InvalidMetaidSyntax | Invalid syntax for a 'metaid' attribute value | ||||||||
| InvalidIdSyntax | Invalid syntax for an 'id' attribute value | ||||||||
| InvalidUnitIdSyntax | Invalid syntax for the identifier of a unit | ||||||||
| InvalidNameSyntax | Invalid syntax for a 'name' attribute value | ||||||||
| DanglingUnitReference | Dangling reference to a unit. | ||||||||
| MissingAnnotationNamespace | Missing declaration of the XML namespace for the annotation | ||||||||
| DuplicateAnnotationNamespaces | Multiple annotations using the same XML namespace | ||||||||
| SBMLNamespaceInAnnotation | The SBML XML namespace cannot be used in an Annotation object | ||||||||
| MultipleAnnotations | Only one Annotation object is permitted under a given SBML object | ||||||||
| InconsistentArgUnits | The units of the function call's arguments are not consistent with its definition | ||||||||
| InconsistentKineticLawUnitsL3 | The kinetic law's units are inconsistent with those of other kinetic laws in the model | ||||||||
| AssignRuleCompartmentMismatch | Mismatched units in assignment rule for compartment | ||||||||
| AssignRuleSpeciesMismatch | Mismatched units in assignment rule for species | ||||||||
| AssignRuleParameterMismatch | Mismatched units in assignment rule for parameter | ||||||||
| AssignRuleStoichiometryMismatch | Mismatched units in assignment rule for stoichiometry | ||||||||
| InitAssignCompartmenMismatch | Mismatched units in initial assignment to compartment | ||||||||
| InitAssignSpeciesMismatch | Mismatched units in initial assignment to species | ||||||||
| InitAssignParameterMismatch | Mismatched units in initial assignment to parameter | ||||||||
| InitAssignStoichiometryMismatch | Mismatched units in initial assignment to stoichiometry | ||||||||
| RateRuleCompartmentMismatch | Mismatched units in rate rule for compartment | ||||||||
| RateRuleSpeciesMismatch | Mismatched units in rate rule for species | ||||||||
| RateRuleParameterMismatch | Mismatched units in rate rule for parameter | ||||||||
| RateRuleStoichiometryMismatch | Mismatched units in rate rule for stoichiometry | ||||||||
| KineticLawNotSubstancePerTime | The units of the kinetic law are not 'substance'/'time' | ||||||||
| SpeciesInvalidExtentUnits | The species' units are not consistent with units of extent | ||||||||
| DelayUnitsNotTime | The units of the delay expression are not units of time | ||||||||
| EventAssignCompartmentMismatch | Mismatched units in event assignment for compartment | ||||||||
| EventAssignSpeciesMismatch | Mismatched units in event assignment for species | ||||||||
| EventAssignParameterMismatch | Mismatched units in event assignment for parameter | ||||||||
| EventAssignStoichiometryMismatch | Mismatched units in event assignment for stoichiometry | ||||||||
| PriorityUnitsNotDimensionless | The units of a priority expression must be 'dimensionless' | ||||||||
| OverdeterminedSystem | The model is overdetermined | ||||||||
| InvalidModelSBOTerm | Invalid 'sboTerm' attribute value for a Model object | ||||||||
| InvalidFunctionDefSBOTerm | Invalid 'sboTerm' attribute value for a FunctionDefinition object | ||||||||
| InvalidParameterSBOTerm | Invalid 'sboTerm' attribute value for a Parameter object | ||||||||
| InvalidInitAssignSBOTerm | Invalid 'sboTerm' attribute value for an InitialAssignment object | ||||||||
| InvalidRuleSBOTerm | Invalid 'sboTerm' attribute value for a Rule object | ||||||||
| InvalidConstraintSBOTerm | Invalid 'sboTerm' attribute value for a Constraint object | ||||||||
| InvalidReactionSBOTerm | Invalid 'sboTerm' attribute value for a Reaction object | ||||||||
| InvalidSpeciesReferenceSBOTerm | Invalid 'sboTerm' attribute value for a SpeciesReference object | ||||||||
| InvalidKineticLawSBOTerm | Invalid 'sboTerm' attribute value for a KineticLaw object | ||||||||
| InvalidEventSBOTerm | Invalid 'sboTerm' attribute value for an Event object | ||||||||
| InvalidEventAssignmentSBOTerm | Invalid 'sboTerm' attribute value for an EventAssignment object | ||||||||
| InvalidCompartmentSBOTerm | Invalid 'sboTerm' attribute value for a Compartment object | ||||||||
| InvalidSpeciesSBOTerm | Invalid 'sboTerm' attribute value for a Species object | ||||||||
| InvalidCompartmentTypeSBOTerm | Invalid 'sboTerm' attribute value for a CompartmentType object | ||||||||
| InvalidSpeciesTypeSBOTerm | Invalid 'sboTerm' attribute value for a SpeciesType object | ||||||||
| InvalidTriggerSBOTerm | Invalid 'sboTerm' attribute value for an Event Trigger object | ||||||||
| InvalidDelaySBOTerm | Invalid 'sboTerm' attribute value for an Event Delay object | ||||||||
| InvalidLocalParameterSBOTerm | Invalid 'sboTerm' attribute value for a LocalParameter object | ||||||||
| InvalidSBMLElementSBOTerm | Invalid 'sboTerm' attribute value for the <sbml> element | ||||||||
| NotesNotInXHTMLNamespace | Notes must be placed in the XHTML XML namespace | ||||||||
| NotesContainsXMLDecl | XML declarations are not permitted in Notes objects | ||||||||
| NotesContainsDOCTYPE | XML DOCTYPE elements are not permitted in Notes objects | ||||||||
| InvalidNotesContent | Invalid notes content found | ||||||||
| OnlyOneNotesElementAllowed | Only one Notes subobject is permitted on a given SBML object | ||||||||
| InvalidNamespaceOnSBML | Invalid XML namespace for the SBML container element | ||||||||
| MissingOrInconsistentLevel | Missing or inconsistent value for the 'level' attribute | ||||||||
| MissingOrInconsistentVersion | Missing or inconsistent value for the 'version' attribute | ||||||||
| PackageNSMustMatch | Inconsistent or invalid SBML Level/Version for the package namespace declaration | ||||||||
| LevelPositiveInteger | The 'level' attribute must have a positive integer value | ||||||||
| VersionPositiveInteger | The 'version' attribute must have a positive integer value | ||||||||
| AllowedAttributesOnSBML | Invalid attribute found on the SBML container element | ||||||||
| L3PackageOnLowerSBML | An L3 package ns found on the SBML container element | ||||||||
| MissingModel | No model definition found | ||||||||
| IncorrectOrderInModel | Incorrect ordering of components within the Model object | ||||||||
| EmptyListElement | Empty ListOf___ object found | ||||||||
| NeedCompartmentIfHaveSpecies | The presence of a species requires a compartment | ||||||||
| OneOfEachListOf | Only one of each kind of ListOf___ object is allowed inside a Model object | ||||||||
| OnlyFuncDefsInListOfFuncDefs | Only FunctionDefinition, Notes and Annotation objects are allowed in ListOfFunctionDefinitions | ||||||||
| OnlyUnitDefsInListOfUnitDefs | Only UnitDefinition, Notes and Annotation objects are allowed in ListOfUnitDefinitions objects | ||||||||
| OnlyCompartmentsInListOfCompartments | Only Compartment, Notes and Annotation objects are allowed in ListOfCompartments objects | ||||||||
| OnlySpeciesInListOfSpecies | Only Species, Notes and Annotation objects are allowed in ListOfSpecies objects | ||||||||
| OnlyParametersInListOfParameters | Only Parameter, Notes and Annotation objects are allowed in ListOfParameters objects | ||||||||
| OnlyInitAssignsInListOfInitAssigns | Only InitialAssignment, Notes and Annotation objects are allowed in ListOfInitialAssignments objects | ||||||||
| OnlyRulesInListOfRules | Only Rule, Notes and Annotation objects are allowed in ListOfRules objects | ||||||||
| OnlyConstraintsInListOfConstraints | Only Constraint, Notes and Annotation objects are allowed in ListOfConstraints objects | ||||||||
| OnlyReactionsInListOfReactions | Only Reaction, Notes and Annotation objects are allowed in ListOfReactions objects | ||||||||
| OnlyEventsInListOfEvents | Only Event, Notes and Annotation objects are allowed in ListOfEvents objects | ||||||||
| L3ConversionFactorOnModel | A 'conversionFactor' attribute value must reference a Parameter object | ||||||||
| L3TimeUnitsOnModel | Invalid 'timeUnits' attribute value | ||||||||
| L3VolumeUnitsOnModel | Invalid 'volumeUnits' attribute value | ||||||||
| L3AreaUnitsOnModel | Invalid 'areaUnits' attribute value | ||||||||
| L3LengthUnitsOnModel | Invalid 'lengthUnits' attribute value | ||||||||
| L3ExtentUnitsOnModel | Invalid 'extentUnits' attribute value | ||||||||
| AllowedAttributesOnModel | Invalid attribute found on the Model object | ||||||||
| AllowedAttributesOnListOfFuncs | Invalid attribute found on the ListOfFunctionDefinitions object | ||||||||
| AllowedAttributesOnListOfUnitDefs | Invalid attribute found on the ListOfUnitDefinitions object | ||||||||
| AllowedAttributesOnListOfComps | Invalid attribute found on the ListOfCompartments object | ||||||||
| AllowedAttributesOnListOfSpecies | Invalid attribute found on the ListOfSpecies object | ||||||||
| AllowedAttributesOnListOfParams | Invalid attribute found on the ListOfParameters object | ||||||||
| AllowedAttributesOnListOfInitAssign | Invalid attribute found on the ListOfInitialAssignments object | ||||||||
| AllowedAttributesOnListOfRules | Invalid attribute found on the ListOfRules object | ||||||||
| AllowedAttributesOnListOfConstraints | Invalid attribute found on the ListOfConstraints object | ||||||||
| AllowedAttributesOnListOfReactions | Invalid attribute found on the ListOfReactions object | ||||||||
| AllowedAttributesOnListOfEvents | Invalid attribute found on the ListOfEvents object | ||||||||
| L3V2SubstanceUnitsOnModel | Invalid 'substanceUnits' attribute value | ||||||||
| FunctionDefMathNotLambda | Invalid expression found in the function definition | ||||||||
| InvalidApplyCiInLambda | Invalid forward reference in the MathML <apply><ci>...</ci></apply> expression | ||||||||
| RecursiveFunctionDefinition | Recursive function definitions are not permitted | ||||||||
| InvalidCiInLambda | Invalid <ci> reference found inside the <lambda> mathematical formula | ||||||||
| InvalidFunctionDefReturnType | A function's return type must be either a number or a Boolean | ||||||||
| OneMathElementPerFunc | A FunctionDefinition object may contain one <math> element | ||||||||
| AllowedAttributesOnFunc | Invalid attribute found on the FunctionDefinition object | ||||||||
| InvalidUnitDefId | Invalid 'id' attribute value for a UnitDefinition object | ||||||||
| InvalidSubstanceRedefinition | Invalid redefinition of built-in type 'substance' | ||||||||
| InvalidLengthRedefinition | Invalid redefinition of built-in type 'length' | ||||||||
| InvalidAreaRedefinition | Invalid redefinition of built-in type name 'area' | ||||||||
| InvalidTimeRedefinition | Invalid redefinition of built-in type name 'time' | ||||||||
| InvalidVolumeRedefinition | Invalid redefinition of built-in type name 'volume' | ||||||||
| VolumeLitreDefExponentNotOne | Must use 'exponent'=1 when defining 'volume' in terms of litres | ||||||||
| VolumeMetreDefExponentNot3 | Must use 'exponent'=3 when defining 'volume' in terms of metres | ||||||||
| EmptyListOfUnits | An empty list of Unit objects is not permitted in a UnitDefinition object | ||||||||
| InvalidUnitKind | Invalid value for the 'kind' attribute of a UnitDefinition object | ||||||||
| OffsetNoLongerValid | Unit attribute 'offset' is not supported in this Level+Version of SBML | ||||||||
| CelsiusNoLongerValid | Unit name 'Celsius' is not defined in this Level+Version of SBML | ||||||||
| EmptyUnitListElement | A ListOfUnits object must not be empty | ||||||||
| OneListOfUnitsPerUnitDef | At most one ListOfUnits object is allowed inside a UnitDefinition object | ||||||||
| OnlyUnitsInListOfUnits | Only Unit, Notes and Annotation objects are allowed in ListOfUnits objects | ||||||||
| AllowedAttributesOnUnitDefinition | Invalid attribute found on the UnitDefinition object | ||||||||
| AllowedAttributesOnListOfUnits | Invalid attribute found on the ListOfUnits object | ||||||||
| AllowedAttributesOnUnit | Invalid attribute found on the Unit object | ||||||||
| ZeroDimensionalCompartmentSize | Invalid use of the 'size' attribute for a zero-dimensional compartment | ||||||||
| ZeroDimensionalCompartmentUnits | Invalid use of the 'units' attribute for a zero-dimensional compartment | ||||||||
| ZeroDimensionalCompartmentConst | Zero-dimensional compartments must be defined to be constant | ||||||||
| UndefinedOutsideCompartment | Invalid value for the 'outside' attribute of a Compartment object | ||||||||
| RecursiveCompartmentContainment | Recursive nesting of compartments via the 'outside' attribute is not permitted | ||||||||
| ZeroDCompartmentContainment | Invalid nesting of zero-dimensional compartments | ||||||||
| Invalid1DCompartmentUnits | Invalid value for the 'units' attribute of a one-dimensional compartment | ||||||||
| Invalid2DCompartmentUnits | Invalid value for the 'units' attribute of a two-dimensional compartment | ||||||||
| Invalid3DCompartmentUnits | Invalid value for the 'units' attribute of a three-dimensional compartment | ||||||||
| InvalidCompartmentTypeRef | Invalid value for the 'compartmentType' attribute of a compartment | ||||||||
| OneDimensionalCompartmentUnits | No units defined for 1-D compartment | ||||||||
| TwoDimensionalCompartmentUnits | No units defined for 2-D compartment | ||||||||
| ThreeDimensionalCompartmentUnits | No units defined for 3-D Compartment object | ||||||||
| AllowedAttributesOnCompartment | Invalid attribute found on Compartment object | ||||||||
| NoUnitsOnCompartment | No units defined for Compartment object | ||||||||
| InvalidSpeciesCompartmentRef | Invalid value found for Species 'compartment' attribute | ||||||||
| HasOnlySubsNoSpatialUnits | Attribute 'spatialSizeUnits' must not be set if 'hasOnlySubstanceUnits'='true' | ||||||||
| NoSpatialUnitsInZeroD | Attribute 'spatialSizeUnits' must not be set if the compartment is zero-dimensional | ||||||||
| NoConcentrationInZeroD | Attribute 'initialConcentration' must not be set if the compartment is zero-dimensional | ||||||||
| SpatialUnitsInOneD | Invalid value for 'spatialSizeUnits' attribute of a one-dimensional compartment | ||||||||
| SpatialUnitsInTwoD | Invalid value for the 'spatialSizeUnits' attribute of a two-dimensional compartment | ||||||||
| SpatialUnitsInThreeD | Invalid value for the 'spatialSizeUnits' attribute of a three-dimensional compartment | ||||||||
| InvalidSpeciesSusbstanceUnits | Invalid value for a Species 'units' attribute | ||||||||
| BothAmountAndConcentrationSet | Cannot set both 'initialConcentration' and 'initialAmount' attributes simultaneously | ||||||||
| NonBoundarySpeciesAssignedAndUsed | Cannot use a non-boundary species in both reactions and rules simultaneously | ||||||||
| NonConstantSpeciesUsed | Cannot use a constant, non-boundary species as a reactant or product | ||||||||
| InvalidSpeciesTypeRef | Invalid value for the 'speciesType' attribute of a species | ||||||||
| MultSpeciesSameTypeInCompartment | Cannot have multiple species of the same species type in the same compartment | ||||||||
| MissingSpeciesCompartment | Missing value for the 'compartment' attribute | ||||||||
| SpatialSizeUnitsRemoved | Attribute 'spatialSizeUnits' is not supported in this Level+Version of SBML | ||||||||
| SubstanceUnitsOnSpecies | No substance units defined for the species | ||||||||
| ConversionFactorOnSpecies | Invalid value for the 'conversionFactor' attribute | ||||||||
| AllowedAttributesOnSpecies | Invalid attribute found on Species object | ||||||||
| InvalidParameterUnits | Invalid value for the 'units' attribute of a Parameter object | ||||||||
| ParameterUnits | No units defined for the parameter | ||||||||
| ConversionFactorMustConstant | A conversion factor must reference a Parameter object declared to be a constant | ||||||||
| AllowedAttributesOnParameter | Invalid attribute found on Parameter object | ||||||||
| InvalidInitAssignSymbol | Invalid value for the 'symbol' attribute of an InitialAssignment object | ||||||||
| MultipleInitAssignments | Multiple initial assignments for the same 'symbol' value are not allowed | ||||||||
| InitAssignmentAndRuleForSameId | Cannot set a value using both an initial assignment and an assignment rule simultaneously | ||||||||
| OneMathElementPerInitialAssign | An InitialAssignment object may contain one <math> element | ||||||||
| AllowedAttributesOnInitialAssign | Invalid attribute found on an InitialAssignment object | ||||||||
| InitAssignmentCannotRef0DComp | InitialAssignment cannot reference 0D compartment | ||||||||
| InvalidAssignRuleVariable | Invalid value for the 'variable' attribute of an AssignmentRule object | ||||||||
| InvalidRateRuleVariable | Invalid value for the 'variable' attribute of a RateRule object | ||||||||
| AssignmentToConstantEntity | An assignment rule cannot assign an entity declared to be constant | ||||||||
| RateRuleForConstantEntity | A rate rule cannot assign an entity declared to be constant | ||||||||
| CircularRuleDependency | Circular dependencies involving rules and reactions are not permitted | ||||||||
| OneMathElementPerRule | A rule object may contain one <math> element | ||||||||
| AllowedAttributesOnAssignRule | Invalid attribute found on an AssignmentRule object | ||||||||
| AllowedAttributesOnRateRule | Invalid attribute found on a RateRule object | ||||||||
| AllowedAttributesOnAlgRule | Invalid attribute found on an AlgebraicRule object | ||||||||
| RuleCannotRef0DComp | Rule cannot reference 0D compartment | ||||||||
| CircularDependencyRateOf | Circular dependencies are not permitted in RateRule and KineticLaw objects | ||||||||
| ConstraintMathNotBoolean | A Constraint object's <math> must evaluate to a Boolean value | ||||||||
| IncorrectOrderInConstraint | Subobjects inside the Constraint object are not in the prescribed order | ||||||||
| ConstraintNotInXHTMLNamespace | A Constraint's Message subobject must be in the XHTML XML namespace | ||||||||
| ConstraintContainsXMLDecl | XML declarations are not permitted within Constraint's Message objects | ||||||||
| ConstraintContainsDOCTYPE | XML DOCTYPE elements are not permitted within Constraint's Message objects | ||||||||
| InvalidConstraintContent | Invalid content for a Constraint object's Message object | ||||||||
| OneMathElementPerConstraint | A Constraint object may contain one <math> element | ||||||||
| OneMessageElementPerConstraint | A Constraint object can only have one Message subobject | ||||||||
| AllowedAttributesOnConstraint | Invalid attribute found on Constraint object | ||||||||
| NoReactantsOrProducts | Cannot have a reaction with neither reactants nor products | ||||||||
| IncorrectOrderInReaction | Subobjects inside the Reaction object are not in the prescribed order | ||||||||
| EmptyListInReaction | Reaction components, if present, cannot be empty | ||||||||
| InvalidReactantsProductsList | Invalid object found in the list of reactants or products | ||||||||
| InvalidModifiersList | Invalid object found in the list of modifiers | ||||||||
| OneSubElementPerReaction | A Reaction object can only contain one of each allowed type of object | ||||||||
| CompartmentOnReaction | Invalid value for the Reaction 'compartment' attribute | ||||||||
| AllowedAttributesOnReaction | Invalid attribute for a Reaction object | ||||||||
| InvalidSpeciesReference | Invalid 'species' attribute value in SpeciesReference object | ||||||||
| BothStoichiometryAndMath | The 'stoichiometry' attribute and StoichiometryMath subobject are mutually exclusive | ||||||||
| AllowedAttributesOnSpeciesReference | Invalid attribute found on the SpeciesReference object | ||||||||
| AllowedAttributesOnModifier | Invalid attribute found on the ModifierSpeciesReference object | ||||||||
| UndeclaredSpeciesRef | Unknown species referenced in the kinetic law <math> formula | ||||||||
| IncorrectOrderInKineticLaw | Incorrect ordering of components in the KineticLaw object | ||||||||
| EmptyListInKineticLaw | The list of parameters, if present, cannot be empty | ||||||||
| NonConstantLocalParameter | Parameters local to a KineticLaw object must have a 'constant' attribute value of 'true' | ||||||||
| SubsUnitsNoLongerValid | Attribute 'substanceUnits' is not supported in this Level+Version of SBML | ||||||||
| TimeUnitsNoLongerValid | Attribute 'timeUnits' is not supported in this Level+Version of SBML | ||||||||
| OneListOfPerKineticLaw | Only one ListOfLocalParameters object is permitted within a KineticLaw object | ||||||||
| OnlyLocalParamsInListOfLocalParams | Only LocalParameter, Notes and Annotation objects are allowed in ListOfLocalParameter objects | ||||||||
| AllowedAttributesOnListOfLocalParam | Invalid attribute found on the ListOfLocalParameters object | ||||||||
| OneMathPerKineticLaw | Only one <math> element is allowed in a KineticLaw object | ||||||||
| UndeclaredSpeciesInStoichMath | Unknown species referenced in the StoichiometryMath object's <math> formula | ||||||||
| AllowedAttributesOnKineticLaw | Invalid attribute found on the KineticLaw object | ||||||||
| AllowedAttributesOnListOfSpeciesRef | Invalid attribute found on the ListOfSpeciesReferences object | ||||||||
| AllowedAttributesOnListOfMods | Invalid attribute found on the ListOfModifiers object | ||||||||
| L3V2FastDeprecated | Fast attribute deprecated | ||||||||
| AllowedAttributesOnLocalParameter | Invalid attribute found on the LocalParameter object | ||||||||
| LocalParameterShadowsSpecies | Invalid attribute found on the LocalParameter object | ||||||||
| MissingTriggerInEvent | The Event object is missing a Trigger subobject | ||||||||
| TriggerMathNotBoolean | A Trigger object's <math> expression must evaluate to a Boolean value | ||||||||
| MissingEventAssignment | The Event object is missing an EventAssignment subobject | ||||||||
| TimeUnitsEvent | Units referenced by 'timeUnits' attribute are not compatible with units of time | ||||||||
| IncorrectOrderInEvent | Incorrect ordering of components in Event object | ||||||||
| ValuesFromTriggerTimeNeedDelay | Attribute 'useValuesFromTriggerTime'='false', but the Event object does not define a delay | ||||||||
| DelayNeedsValuesFromTriggerTime | The use of a Delay object requires the Event attribute 'useValuesFromTriggerTime' | ||||||||
| OneMathPerTrigger | A Trigger object may have one <math> element | ||||||||
| OneMathPerDelay | A Delay object may have one <math> element | ||||||||
| InvalidEventAssignmentVariable | Invalid 'variable' attribute value in Event object | ||||||||
| EventAssignmentForConstantEntity | An EventAssignment object cannot assign to a component having attribute 'constant'='true' | ||||||||
| OneMathPerEventAssignment | An EventAssignment object may have one <math> element | ||||||||
| AllowedAttributesOnEventAssignment | Invalid attribute found on the EventAssignment object | ||||||||
| OnlyOneDelayPerEvent | An Event object can only have one Delay subobject | ||||||||
| OneListOfEventAssignmentsPerEvent | An Event object can only have one ListOfEventAssignments subobject | ||||||||
| OnlyEventAssignInListOfEventAssign | Only EventAssignment, Notes and Annotation objects are allowed in ListOfEventAssignments | ||||||||
| AllowedAttributesOnListOfEventAssign | Invalid attribute found on the ListOfEventAssignments object | ||||||||
| AllowedAttributesOnEvent | Invalid attribute found on the Event object | ||||||||
| AllowedAttributesOnTrigger | Invalid attribute found on the Trigger object | ||||||||
| AllowedAttributesOnDelay | Invalid attribute found on the Delay object | ||||||||
| PersistentNotBoolean | The Trigger attribute 'persistent' must evaluate to a Boolean value | ||||||||
| InitialValueNotBoolean | The Trigger attribute 'initialValue' must evaluate to a Boolean value | ||||||||
| OnlyOnePriorityPerEvent | An Event object can only have one Priority subobject | ||||||||
| OneMathPerPriority | A Priority object may have one <math> element | ||||||||
| AllowedAttributesOnPriority | Invalid attribute found on the Priority object | ||||||||
| CompartmentShouldHaveSize | It's best to define a size for every compartment in a model | ||||||||
| SpeciesShouldHaveValue | It's best to define an initial amount or initial concentration for every species in a model | ||||||||
| ParameterShouldHaveUnits | It's best to declare units for every parameter in a model | ||||||||
| ParameterShouldHaveValue | It's best to declare values for every parameter in a model | ||||||||
| LocalParameterShadowsId | Local parameters defined within a kinetic law shadow global object symbols | ||||||||
| CannotConvertToL1V1 | Cannot convert to SBML Level 1 Version 1 | ||||||||
| NoEventsInL1 | SBML Level 1 does not support events | ||||||||
| NoFunctionDefinitionsInL1 | SBML Level 1 does not support function definitions | ||||||||
| NoConstraintsInL1 | SBML Level 1 does not support constraints | ||||||||
| NoInitialAssignmentsInL1 | SBML Level 1 does not support initial assignments | ||||||||
| NoSpeciesTypesInL1 | SBML Level 1 does not support species types | ||||||||
| NoCompartmentTypeInL1 | SBML Level 1 does not support compartment types | ||||||||
| NoNon3DCompartmentsInL1 | SBML Level 1 only supports three-dimensional compartments | ||||||||
| NoFancyStoichiometryMathInL1 | SBML Level 1 does not support non-integer nor non-rational stoichiometry formulas | ||||||||
| NoNonIntegerStoichiometryInL1 | SBML Level 1 does not support non-integer 'stoichiometry' attribute values | ||||||||
| NoUnitMultipliersOrOffsetsInL1 | SBML Level 1 does not support multipliers or offsets in unit definitions | ||||||||
| SpeciesCompartmentRequiredInL1 | In SBML Level 1, a value for 'compartment' is mandatory in species definitions | ||||||||
| NoSpeciesSpatialSizeUnitsInL1 | SBML Level 1 does not support species 'spatialSizeUnits' settings | ||||||||
| NoSBOTermsInL1 | SBML Level 1 does not support the 'sboTerm' attribute | ||||||||
| StrictUnitsRequiredInL1 | SBML Level 1 requires strict unit consistency | ||||||||
| ConversionFactorNotInL1 | SBML Level 1 does not support the 'conversionFactor' attribute | ||||||||
| CompartmentNotOnL1Reaction | SBML Level 1 does not support the 'compartment' attribute on Reaction objects | ||||||||
| ExtentUnitsNotSubstance | Units of extent must be compatible with units of substance | ||||||||
| GlobalUnitsNotDeclared | Global units must be refer to unit kind or unitDefinition | ||||||||
| HasOnlySubstanceUnitsNotinL1 | The concept of hasOnlySubstanceUnits was not available in SBML Level 1 | ||||||||
| AvogadroNotSupported | Avogadro not supported in Levels 2 and 1 | ||||||||
| NoConstraintsInL2v1 | SBML Level 2 Version 1 does not support Constraint objects | ||||||||
| NoInitialAssignmentsInL2v1 | SBML Level 2 Version 1 does not support InitialAssignment objects | ||||||||
| NoSpeciesTypeInL2v1 | SBML Level 2 Version 1 does not support SpeciesType objects | ||||||||
| NoCompartmentTypeInL2v1 | SBML Level 2 Version 1 does not support CompartmentType objects | ||||||||
| NoSBOTermsInL2v1 | SBML Level 2 Version 1 does not support the 'sboTerm' attribute | ||||||||
| NoIdOnSpeciesReferenceInL2v1 | SBML Level 2 Version 1 does not support the 'id' attribute on SpeciesReference objects | ||||||||
| NoDelayedEventAssignmentInL2v1 | SBML Level 2 Version 1 does not support the 'useValuesFromTriggerTime' attribute | ||||||||
| StrictUnitsRequiredInL2v1 | SBML Level 2 Version 1 requires strict unit consistency | ||||||||
| IntegerSpatialDimensions | SBML Level 2 Version 1 requires that compartments have spatial dimensions of 0-3 | ||||||||
| StoichiometryMathNotYetSupported | Conversion to StoichiometryMath objects not yet supported | ||||||||
| PriorityLostFromL3 | SBML Level 2 Version 1 does not support priorities on Event objects | ||||||||
| NonPersistentNotSupported | SBML Level 2 Version 1 does not support the 'persistent' attribute on Trigger objects | ||||||||
| InitialValueFalseEventNotSupported | SBML Level 2 Version 1 does not support the 'initialValue' attribute on Trigger objects | ||||||||
| SBOTermNotUniversalInL2v2 | The 'sboTerm' attribute is invalid for this component in SBML Level 2 Version 2 | ||||||||
| NoUnitOffsetInL2v2 | This Level+Version of SBML does not support the 'offset' attribute on Unit objects | ||||||||
| NoKineticLawTimeUnitsInL2v2 | This Level+Version of SBML does not support the 'timeUnits' attribute on KineticLaw objects | ||||||||
| NoKineticLawSubstanceUnitsInL2v2 | This Level+Version of SBML does not support the 'substanceUnits' attribute on KineticLaw objects | ||||||||
| NoDelayedEventAssignmentInL2v2 | This Level+Version of SBML does not support the 'useValuesFromTriggerTime' attribute | ||||||||
| ModelSBOBranchChangedBeyondL2v2 | The allowable 'sboTerm' attribute values for Model objects differ for this SBML Level+Version | ||||||||
| StrictUnitsRequiredInL2v2 | SBML Level 2 Version 2 requires strict unit consistency | ||||||||
| StrictSBORequiredInL2v2 | SBML Level 2 Version 2 requires strict SBO term consistency | ||||||||
| DuplicateAnnotationInvalidInL2v2 | Duplicate top-level annotations are invalid in SBML Level 2 Version 2 | ||||||||
| NoUnitOffsetInL2v3 | This Level+Version of SBML does not support the 'offset' attribute on Unit objects | ||||||||
| NoKineticLawTimeUnitsInL2v3 | This Level+Version of SBML does not support the 'timeUnits' attribute on KineticLaw objects | ||||||||
| NoKineticLawSubstanceUnitsInL2v3 | This Level+Version of SBML does not support the 'substanceUnits' attribute on KineticLaw objects | ||||||||
| NoSpeciesSpatialSizeUnitsInL2v3 | This Level+Version of SBML does not support the 'spatialSizeUnit' attribute on Species objects | ||||||||
| NoEventTimeUnitsInL2v3 | This Level+Version of SBML does not support the 'timeUnits' attribute on Event objects | ||||||||
| NoDelayedEventAssignmentInL2v3 | This Level+Version of SBML does not support the 'useValuesFromTriggerTime' attribute | ||||||||
| ModelSBOBranchChangedBeyondL2v3 | The allowable 'sboTerm' attribute values for Model objects differ for this SBML Level+Version | ||||||||
| StrictUnitsRequiredInL2v3 | SBML Level 2 Version 3 requires strict unit consistency | ||||||||
| StrictSBORequiredInL2v3 | SBML Level 2 Version 3 requires strict SBO term consistency | ||||||||
| DuplicateAnnotationInvalidInL2v3 | Duplicate top-level annotations are invalid in SBML Level 2 Version 3 | ||||||||
| NoUnitOffsetInL2v4 | This Level+Version of SBML does not support the 'offset' attribute on Unit objects | ||||||||
| NoKineticLawTimeUnitsInL2v4 | This Level+Version of SBML does not support the 'timeUnits' attribute on KineticLaw objects | ||||||||
| NoKineticLawSubstanceUnitsInL2v4 | This Level+Version of SBML does not support the 'substanceUnits' attribute on KineticLaw objects | ||||||||
| NoSpeciesSpatialSizeUnitsInL2v4 | This Level+Version of SBML does not support the 'spatialSizeUnit' attribute on Species objects | ||||||||
| NoEventTimeUnitsInL2v4 | This Level+Version of SBML does not support the 'timeUnits' attribute on Event objects | ||||||||
| ModelSBOBranchChangedInL2v4 | The allowable 'sboTerm' attribute values for Model objects differ for this SBML Level+Version | ||||||||
| DuplicateAnnotationInvalidInL2v4 | Duplicate top-level annotations are invalid in SBML Level 2 Version 4 | ||||||||
| NoSpeciesTypeInL3v1 | SBML Level 3 Version 1 does not support SpeciesType objects | ||||||||
| NoCompartmentTypeInL3v1 | SBML Level 3 Version 1 does not support CompartmentType objects | ||||||||
| NoUnitOffsetInL3v1 | This Level+Version of SBML does not support the 'offset' attribute on Unit objects | ||||||||
| NoKineticLawTimeUnitsInL3v1 | This Level+Version of SBML does not support the 'timeUnits' attribute on KineticLaw objects | ||||||||
| NoKineticLawSubstanceUnitsInL3v1 | This Level+Version of SBML does not support the 'substanceUnits' attribute on KineticLaw objects | ||||||||
| NoSpeciesSpatialSizeUnitsInL3v1 | This Level+Version of SBML does not support the 'spatialSizeUnit' attribute on Species objects | ||||||||
| NoEventTimeUnitsInL3v1 | This Level+Version of SBML does not support the 'timeUnits' attribute on Event objects | ||||||||
| ModelSBOBranchChangedInL3v1 | The allowable 'sboTerm' attribute values for Model objects differ for this SBML Level+Version | ||||||||
| DuplicateAnnotationInvalidInL3v1 | Duplicate top-level annotations are invalid in SBML Level 3 Version 1 | ||||||||
| NoCompartmentOutsideInL3v1 | This Level+Version of SBML does not support the 'outside' attribute on Compartment objects | ||||||||
| NoStoichiometryMathInL3v1 | This Level+Version of SBML does not support the StoichiometryMath object | ||||||||
| DoubleExponentNotSupported | Exponent of type double not supported in Levels 2 and 1. | ||||||||
| MathMLElementNotSupported | This MathML element is only permitted in L3V2 | ||||||||
| EmptyListOfElementNotSupported | Empty 'ListOf' element is only permitted in L3V2 | ||||||||
| MissingMathElementNotSupported | Missing <math> element is only permitted in L3V2 | ||||||||
| MissingTriggerElementNotSupported | missing <trigger> element is only permitted in L3V2 | ||||||||
| BooleanNumericDiscrepancy | Interchange of Boolean and numeric values only permitted in L3V2 | ||||||||
| IdNameSBaseInL3V2 | Conversion will lose attributes only available in L3V2 and higher | ||||||||
| MissingParticipantsNotSupported | Omission of both <listOfReactants> and <listOfProducts> is only valid in L3V2 | ||||||||
| ConvertibleMathInitialAssignment | Some L3V2-specific MathML elements are not permitted in InitialAssignment objects | ||||||||
| FastReactionsNotSupported | Conversion of reactions employing the 'fast' attribute is not supported | ||||||||
| InvalidSBMLLevelVersion | Unknown Level+Version combination of SBML | ||||||||
| AnnotationNotesNotAllowedLevel1 | Annotation objects on the SBML container element are not permitted in SBML Level 1 | ||||||||
| InvalidRuleOrdering | Invalid ordering of rules | ||||||||
| RequiredPackagePresent | The SBML document requires an SBML Level 3 package unavailable in this software | ||||||||
| UnrequiredPackagePresent | The SBML document uses an SBML Level 3 package unavailable in this software | ||||||||
| PackageRequiredShouldBeFalse | This package expects required to be false | ||||||||
| SubsUnitsAllowedInKL | Disallowed value for attribute 'substanceUnits' on KineticLaw object | ||||||||
| TimeUnitsAllowedInKL | Disallowed value for attribute 'timeUnits' on KineticLaw object | ||||||||
| FormulaInLevel1KL | Only predefined functions are allowed in SBML Level 1 formulas | ||||||||
| L3SubstanceUnitsOnModel | Invalid 'substanceUnits' attribute value | ||||||||
| StoichiometryMathMissingMath | The <stoichiometryMath> element must contain a <math> element | ||||||||
| TimeUnitsRemoved | This Level+Version of SBML does not support the 'timeUnits' attribute on Event objects | ||||||||
| BadMathML | Invalid MathML expression | ||||||||
| FailedMathMLReadOfDouble | Missing or invalid floating-point number in MathML expression | ||||||||
| FailedMathMLReadOfInteger | Missing or invalid integer in MathML expression | ||||||||
| FailedMathMLReadOfExponential | Missing or invalid exponential expression in MathML | ||||||||
| FailedMathMLReadOfRational | Missing or invalid rational expression in MathML | ||||||||
| BadMathMLNodeType | Invalid MathML element | ||||||||
| InvalidMathMLAttribute | Invalid MathML attribute | ||||||||
| NoTimeSymbolInFunctionDef | Use of <csymbol> for 'time' not allowed within FunctionDefinition objects | ||||||||
| NoBodyInFunctionDef | There must be a <lambda> body within the <math> element of a FunctionDefinition object | ||||||||
| DanglingUnitSIdRef | Units must refer to valid unit or unitDefinition | ||||||||
| RDFMissingAboutTag | RDF missing the <about> tag | ||||||||
| RDFEmptyAboutTag | RDF empty <about> tag | ||||||||
| RDFAboutTagNotMetaid | RDF <about> tag is not metaid | ||||||||
| RDFNotCompleteModelHistory | RDF does not contain valid ModelHistory | ||||||||
| RDFNotModelHistory | RDF does not result in a ModelHistory | ||||||||
| AnnotationNotElement | Annotation must contain element | ||||||||
| NestedAnnotationNotAllowed | Nested annotations not allowed | ||||||||
| UndeclaredUnits | Missing unit declarations on parameters or literal numbers in expression | ||||||||
| UndeclaredTimeUnitsL3 | Unable to verify consistency of units: the unit of time has not been declared | ||||||||
| UndeclaredExtentUnitsL3 | Unable to verify consistency of units: the units of reaction extent have not been declared | ||||||||
| UndeclaredObjectUnitsL3 | Unable to verify consistency of units: encountered a model entity with no declared units | ||||||||
| CannotVerifyUnitsObjectNoMath | Unable to verify consistency of units: encountered an object with no <math> element | ||||||||
| UnrecognisedSBOTerm | Unrecognized 'sboTerm' attribute value | ||||||||
| ObseleteSBOTerm | Obsolete 'sboTerm' attribute value | ||||||||
| IncorrectCompartmentSpatialDimensions | In SBML Level 1, only three-dimensional compartments are allowed | ||||||||
| CompartmentTypeNotValidAttribute | CompartmentType objects are not available in this Level+Version of SBML | ||||||||
| ConstantNotValidAttribute | This Level+Version of SBML does not support the 'constant' attribute on this component | ||||||||
| MetaIdNotValidAttribute | Attribute 'metaid' is not available in SBML Level 1 | ||||||||
| SBOTermNotValidAttributeBeforeL2V3 | The 'sboTerm' attribute is not available on this component before SBML Level 2 Version 3 | ||||||||
| InvalidL1CompartmentUnits | Invalid units for a compartment in SBML Level 1 | ||||||||
| L1V1CompartmentVolumeReqd | In SBML Level 1, a compartment's volume must be specified | ||||||||
| CompartmentTypeNotValidComponent | CompartmentType objects are not available in this Level+Version of SBML | ||||||||
| ConstraintNotValidComponent | Constraint objects are not available in this Level+Version of SBML | ||||||||
| EventNotValidComponent | Event objects are not available in this Level+Version of SBML | ||||||||
| SBOTermNotValidAttributeBeforeL2V2 | The 'sboTerm' attribute is invalid for this component before Level 2 Version 2 | ||||||||
| FuncDefNotValidComponent | FunctionDefinition objects are not available in this Level+Version of SBML | ||||||||
| InitialAssignNotValidComponent | InitialAssignment objects are not available in this Level+Version of SBML | ||||||||
| VariableNotValidAttribute | Attribute 'variable' is not available on this component in this Level+Version of SBML | ||||||||
| UnitsNotValidAttribute | Attribute 'units' is not available on this component in this Level+Version of SBML | ||||||||
| ConstantSpeciesNotValidAttribute | Attribute 'constant' is not available on Species objects in SBML Level 1 | ||||||||
| SpatialSizeUnitsNotValidAttribute | Attribute 'spatialSizeUnits' is not available on Species objects in SBML Level 1 | ||||||||
| SpeciesTypeNotValidAttribute | Attribute 'speciesType' is not available on Species objects in SBML Level 1 | ||||||||
| HasOnlySubsUnitsNotValidAttribute | Attribute 'hasOnlySubstanceUnits' is not available on Species objects in SBML Level 1 | ||||||||
| IdNotValidAttribute | Attribute 'id' is not available on SpeciesReference objects in SBML Level 1 | ||||||||
| NameNotValidAttribute | Attribute 'name' is not available on SpeciesReference objects in SBML Level 1 | ||||||||
| SpeciesTypeNotValidComponent | The SpeciesType object is not supported in SBML Level 1 | ||||||||
| StoichiometryMathNotValidComponent | The StoichiometryMath object is not supported in SBML Level 1 | ||||||||
| MultiplierNotValidAttribute | Attribute 'multiplier' on Unit objects is not supported in SBML Level 1 | ||||||||
| OffsetNotValidAttribute | Attribute 'offset' on Unit objects is only available in SBML Level 2 Version 1 | ||||||||
| L3SpatialDimensionsUnset | No value given for 'spatialDimensions' attribute; assuming a value of 3 | ||||||||
| PackageConversionNotSupported | Conversion of SBML Level 3 package constructs is not yet supported | ||||||||
| InvalidTargetLevelVersion | The requested SBML Level/Version combination is not known to exist | ||||||||
| L3NotSupported | SBML Level 3 is not yet supported | ||||||||
| CompUnknown | |||||||||
| CompNSUndeclared | The comp ns is not correctly declared | ||||||||
| CompElementNotInNs | Element not in comp namespace | ||||||||
| CompDuplicateComponentId | Duplicate 'id' attribute value | ||||||||
| CompUniqueModelIds | Model and ExternalModelDefinitions must have unique ids | ||||||||
| CompUniquePortIds | Ports must have unique ids | ||||||||
| CompInvalidSIdSyntax | Invalid SId syntax | ||||||||
| CompInvalidSubmodelRefSyntax | Invalid submodelRef syntax | ||||||||
| CompInvalidDeletionSyntax | Invalid deletion syntax | ||||||||
| CompInvalidConversionFactorSyntax | Invalid conversionFactor syntax | ||||||||
| CompInvalidNameSyntax | Invalid name syntax | ||||||||
| CompReplacedUnitsShouldMatch | Units of replaced elements should match replacement units. | ||||||||
| CompOneListOfReplacedElements | Only one <listOfReplacedElements> allowed. | ||||||||
| CompLOReplaceElementsAllowedElements | Allowed children of <listOfReplacedElements> | ||||||||
| CompLOReplacedElementsAllowedAttribs | Allowed <listOfReplacedElements> attributes | ||||||||
| CompEmptyLOReplacedElements | <listOfReplacedElements> must not be empty | ||||||||
| CompOneReplacedByElement | Only one <replacedBy> object allowed. | ||||||||
| CompAttributeRequiredMissing | Required comp:required attribute on <sbml> | ||||||||
| CompAttributeRequiredMustBeBoolean | The comp:required attribute must be Boolean | ||||||||
| CompRequiredTrueIfElementsRemain | The comp:required attribute must be 'true' if math changes | ||||||||
| CompRequiredFalseIfAllElementsReplaced | The comp:required attribute must be 'false' if math does not change | ||||||||
| CompOneListOfModelDefinitions | Only one <listOfModelDefinitions> allowed. | ||||||||
| CompEmptyLOModelDefs | <listOfModelDefinitions> and <listOfExternalModelDefinitions> must not be empty | ||||||||
| CompLOModelDefsAllowedElements | Only <modelDefinitions> in <listOfModelDefinitions> | ||||||||
| CompLOExtModelDefsAllowedElements | Only <externalModelDefinitions> in <listOfExternalModelDefinitions> | ||||||||
| CompLOModelDefsAllowedAttributes | Allowed <listOfModelDefinitions> attributes | ||||||||
| CompLOExtModDefsAllowedAttributes | Allowed <listOfExternalModelDefinitions> attributes | ||||||||
| CompOneListOfExtModelDefinitions | Only one <listOfExternalModelDefinitions> allowed. | ||||||||
| CompAttributeRequiredMustBeTrue | The comp:required attribute must be 'true' | ||||||||
| CompExtModDefAllowedCoreAttributes | Allowed <externalModelDefinitions> core attributes | ||||||||
| CompExtModDefAllowedElements | Allowed <externalModelDefinitions> elements | ||||||||
| CompExtModDefAllowedAttributes | Allowed <externalModelDefinitions> attributes | ||||||||
| CompReferenceMustBeL3 | External models must be L3 | ||||||||
| CompModReferenceMustIdOfModel | 'modelRef' must be the 'id' of a model in the 'source' document | ||||||||
| CompExtModMd5DoesNotMatch | MD5 checksum does not match the 'source' document | ||||||||
| CompInvalidSourceSyntax | The 'comp:source' attribute must be of type 'anyURI' | ||||||||
| CompInvalidModelRefSyntax | The 'comp:modelRef' attribute must have the syntax of 'SId' | ||||||||
| CompInvalidMD5Syntax | The 'comp:md5' attribute must have the syntax of 'string' | ||||||||
| CompCircularExternalModelReference | Circular reference in <externalModelDefinition> | ||||||||
| CompOneListOfOnModel | Only one <listOfSubmodels> and one <listOfPorts> allowed | ||||||||
| CompNoEmptyListOfOnModel | No empty listOf elements allowed | ||||||||
| CompLOSubmodelsAllowedElements | Allowed elements on <listOfSubmodels> | ||||||||
| CompLOPortsAllowedElements | Allowed elements on <listOfPorts> | ||||||||
| CompLOSubmodelsAllowedAttributes | Allowed attributes on <listOfSubmodels> | ||||||||
| CompLOPortsAllowedAttributes | Allowed attributes on <listOfPorts> | ||||||||
| CompSubmodelAllowedCoreAttributes | Allowed core attributes on <submodel> | ||||||||
| CompSubmodelAllowedElements | Allowed elements on <submodel> | ||||||||
| CompOneListOfDeletionOnSubmodel | Only one <listOfDeletions> on a <submodel> allowed | ||||||||
| CompSubmodelNoEmptyLODeletions | No empty listOfDeletions elements allowed | ||||||||
| CompLODeletionsAllowedElements | Allowed elements on <listOfDeletions> | ||||||||
| CompLODeletionAllowedAttributes | Allowed <listOfDeletions> attributes | ||||||||
| CompSubmodelAllowedAttributes | Allowed <submodel> attributes | ||||||||
| CompModReferenceSyntax | 'comp:modelRef' must conform to SId syntax | ||||||||
| CompInvalidTimeConvFactorSyntax | 'comp:timeConversionFactor' must conform to SId syntax | ||||||||
| CompInvalidExtentConvFactorSyntax | 'comp:extentConversionFactor' must conform to SId syntax | ||||||||
| CompSubmodelMustReferenceModel | The 'comp:modelRef' attribute must reference a model | ||||||||
| CompSubmodelCannotReferenceSelf | The 'comp:modelRef' attribute cannot reference own model | ||||||||
| CompModCannotCircularlyReferenceSelf | <model> may not reference <submodel> that references itself. | ||||||||
| CompTimeConversionMustBeParameter | The 'comp:timeConversionFactor' must reference a parameter | ||||||||
| CompExtentConversionMustBeParameter | The 'comp:extentConversionFactor' must reference a parameter | ||||||||
| CompPortRefMustReferencePort | The 'comp:portRef' attribute must be the 'id' of a <port> | ||||||||
| CompIdRefMustReferenceObject | The 'comp:idRef' attribute must be the 'id' of a model element | ||||||||
| CompUnitRefMustReferenceUnitDef | The 'comp:unitRef' attribute must be the 'id' of a UnitDefinition | ||||||||
| CompMetaIdRefMustReferenceObject | The 'comp:metaIdRef' attribute must be the 'metaid' of an object | ||||||||
| CompParentOfSBRefChildMustBeSubmodel | If <sBaseRef> has a child <sBaseRef> its parent must be a <submodel> | ||||||||
| CompInvalidPortRefSyntax | The 'comp:portRef' attribute must have the syntax of an SBML SId | ||||||||
| CompInvalidIdRefSyntax | The 'comp:idRef' attribute must have the syntax of an SBML SId | ||||||||
| CompInvalidUnitRefSyntax | The 'comp:unitRef' attribute must have the syntax of an SBML SId | ||||||||
| CompInvalidMetaIdRefSyntax | The 'comp:metaIdRef' attribute must have the syntax of an XML ID | ||||||||
| CompOneSBaseRefOnly | Only one <sbaseRef> | ||||||||
| CompDeprecatedSBaseRefSpelling | The spelling 'sbaseRef' is deprecated | ||||||||
| CompSBaseRefMustReferenceObject | An SBaseRef must reference an object. | ||||||||
| CompSBaseRefMustReferenceOnlyOneObject | An SBaseRef must reference only one other object. | ||||||||
| CompNoMultipleReferences | Objects may not be referenced by mutiple SBaseRef constructs. | ||||||||
| CompPortMustReferenceObject | Port must reference an object | ||||||||
| CompPortMustReferenceOnlyOneObject | Port must reference only one other object. | ||||||||
| CompPortAllowedAttributes | Allowed attributes on a Port | ||||||||
| CompPortReferencesUnique | Port definitions must be unique. | ||||||||
| CompDeletionMustReferenceObject | Deletion must reference an object | ||||||||
| CompDeletionMustReferOnlyOneObject | Deletion must reference only one other object. | ||||||||
| CompDeletionAllowedAttributes | Allowed attributes on a Deletion | ||||||||
| CompReplacedElementMustRefObject | ReplacedElement must reference an object | ||||||||
| CompReplacedElementMustRefOnlyOne | ReplacedElement must reference only one other object. | ||||||||
| CompReplacedElementAllowedAttributes | Allowed attributes on <replacedElement> | ||||||||
| CompReplacedElementSubModelRef | The 'comp:submodelRef' attribute must point to a <submodel> | ||||||||
| CompReplacedElementDeletionRef | The 'comp:deletion' attribute must point to a <deletion> | ||||||||
| CompReplacedElementConvFactorRef | The 'comp:conversionFactor attribute must point to a <parameter> | ||||||||
| CompReplacedElementSameReference | No <replacedElement> refer to same object | ||||||||
| CompReplacedElementNoDelAndConvFact | No <replacedElement> with deletion and conversionfactor | ||||||||
| CompReplacedByMustRefObject | ReplacedBy must reference an object | ||||||||
| CompReplacedByMustRefOnlyOne | ReplacedBy must reference only one other object. | ||||||||
| CompReplacedByAllowedAttributes | Allowed attributes on <replacedBy> | ||||||||
| CompReplacedBySubModelRef | The 'comp:submodelRef' attribute must point to a <submodel> | ||||||||
| CompMustReplaceSameClass | Replaced classes must match. | ||||||||
| CompMustReplaceIDs | Replaced IDs must be replaced with IDs. | ||||||||
| CompMustReplaceMetaIDs | Replaced metaids must be replaced with metaids. | ||||||||
| CompMustReplacePackageIDs | Replaced package IDs must be replaced with package IDs. | ||||||||
| CompUnresolvedReference | Unresolved reference. | ||||||||
| CompNoModelInReference | No model in referenced document. | ||||||||
| CompExtModDefBad | Referenced <externalModelDefinition> unresolvable. | ||||||||
| CompModelFlatteningFailed | Model failed to flatten. | ||||||||
| CompFlatModelNotValid | Flat model not valid. | ||||||||
| CompLineNumbersUnreliable | Line numbers unreliable. | ||||||||
| CompFlatteningNotRecognisedReqd | Flattening not implemented for required package. | ||||||||
| CompFlatteningNotRecognisedNotReqd | Flattening not implemented for unrequired package. | ||||||||
| CompFlatteningNotImplementedNotReqd | Flattening not implemented for unrequired package. | ||||||||
| CompFlatteningNotImplementedReqd | Flattening not implemented for required package. | ||||||||
| CompFlatteningWarning | Flattening reference may come from package. | ||||||||
| CompDeprecatedDeleteFunction | The performDeletions functions is deprecated. | ||||||||
| CompDeprecatedReplaceFunction | The performReplacementsAndConversions fuctions is deprecated. | ||||||||
| CompDeletedReplacement | Element deleted before a subelement could be replaced. | ||||||||
| CompIdRefMayReferenceUnknownPackage | The 'comp:idRef' attribute must be the 'id' of a model element | ||||||||
| CompMetaIdRefMayReferenceUnknownPkg | The 'comp:metaIdRef' attribute must be the 'metaid' of a model element | ||||||||
| FbcUnknown | |||||||||
| FbcNSUndeclared | The fbc ns is not correctly declared | ||||||||
| FbcElementNotInNs | Element not in fbc namespace | ||||||||
| FbcDuplicateComponentId | Duplicate 'id' attribute value | ||||||||
| FbcSBMLSIdSyntax | Invalid 'id' attribute | ||||||||
| FbcAttributeRequiredMissing | Required fbc:required attribute on <sbml> | ||||||||
| FbcAttributeRequiredMustBeBoolean | The fbc:required attribute must be Boolean | ||||||||
| FbcRequiredFalse | The fbc:required attribute must be 'false' | ||||||||
| FbcOnlyOneEachListOf | One of each list of allowed | ||||||||
| FbcNoEmptyListOfs | ListOf elements cannot be empty | ||||||||
| FbcLOFluxBoundsAllowedElements | Allowed elements on ListOfFluxBounds | ||||||||
| FbcLOObjectivesAllowedElements | Allowed elements on ListOfObjectives | ||||||||
| FbcLOFluxBoundsAllowedAttributes | Allowed attributes on ListOfFluxBounds | ||||||||
| FbcLOObjectivesAllowedAttributes | Allowed attributes on ListOfObjectives | ||||||||
| FbcActiveObjectiveSyntax | Type of activeObjective attribute | ||||||||
| FbcActiveObjectiveRefersObjective | ActiveObjective must reference Objective | ||||||||
| FbcModelMustHaveStrict | 'Strict' attribute required on <model> | ||||||||
| FbcModelStrictMustBeBoolean | 'Strict' attribute must be Boolean | ||||||||
| FbcLOGeneProductsAllowedElements | Allowed elements on ListOfGeneProducts | ||||||||
| FbcLOGeneProductsAllowedAttributes | Allowed attributes on ListOfGeneProducts | ||||||||
| FbcSpeciesAllowedL3Attributes | Species allowed attributes | ||||||||
| FbcSpeciesChargeMustBeInteger | Charge must be integer | ||||||||
| FbcSpeciesFormulaMustBeString | Chemical formula must be string | ||||||||
| FbcFluxBoundAllowedL3Attributes | <fluxBound> may only have 'metaId' and 'sboTerm' from L3 namespace | ||||||||
| FbcFluxBoundAllowedElements | <fluxBound> may only have <notes> and <annotations> from L3 Core | ||||||||
| FbcFluxBoundRequiredAttributes | Invalid attribute found on <fluxBound> object | ||||||||
| FbcFluxBoundRectionMustBeSIdRef | Datatype for 'fbc:reaction' must be SIdRef | ||||||||
| FbcFluxBoundNameMustBeString | The attribute 'fbc:name' must be of the data type string | ||||||||
| FbcFluxBoundOperationMustBeEnum | The attribute 'fbc:operation' must be of data type FbcOperation | ||||||||
| FbcFluxBoundValueMustBeDouble | The attribute 'fbc:value' must be of the data type double | ||||||||
| FbcFluxBoundReactionMustExist | 'fbc:reaction' must refer to valid reaction | ||||||||
| FbcFluxBoundsForReactionConflict | Conflicting set of FluxBounds for a reaction | ||||||||
| FbcObjectiveAllowedL3Attributes | <objective> may only have 'metaId' and 'sboTerm' from L3 namespace | ||||||||
| FbcObjectiveAllowedElements | <objective> may only have <notes> and <annotations> from L3 Core | ||||||||
| FbcObjectiveRequiredAttributes | Invalid attribute found on <objective> object | ||||||||
| FbcObjectiveNameMustBeString | The attribute 'fbc:name' must be of the data type string | ||||||||
| FbcObjectiveTypeMustBeEnum | The attribute 'fbc:type' must be of data type FbcType. | ||||||||
| FbcObjectiveOneListOfObjectives | An <objective> must have one <listOfFluxObjectives>. | ||||||||
| FbcObjectiveLOFluxObjMustNotBeEmpty | <listOfFluxObjectives> subobject must not be empty | ||||||||
| FbcObjectiveLOFluxObjOnlyFluxObj | Invalid element found in <listOfFluxObjectives> | ||||||||
| FbcObjectiveLOFluxObjAllowedAttribs | <listOfFluxObjectives> may only have 'metaId' and 'sboTerm' from L3 core | ||||||||
| FbcFluxObjectAllowedL3Attributes | <fluxObjective> may only have 'metaId' and 'sboTerm' from L3 namespace | ||||||||
| FbcFluxObjectAllowedElements | <fluxObjective> may only have <notes> and <annotations> from L3 Core | ||||||||
| FbcFluxObjectRequiredAttributes | Invalid attribute found on <fluxObjective> object | ||||||||
| FbcFluxObjectNameMustBeString | The attribute 'fbc:name' must be of the data type string | ||||||||
| FbcFluxObjectReactionMustBeSIdRef | Datatype for 'fbc:reaction' must be SIdRef | ||||||||
| FbcFluxObjectReactionMustExist | 'fbc:reaction' must refer to valid reaction | ||||||||
| FbcFluxObjectCoefficientMustBeDouble | The attribute 'fbc:coefficient' must be of the data type double | ||||||||
| FbcFluxObjectCoefficientWhenStrict | The 'fbc:coefficient' must be declared when strict | ||||||||
| FbcReactionOnlyOneGeneProdAss | One GeneProductAssociation in a Reaction | ||||||||
| FbcReactionAllowedAttributes | Fbc attributes on a Reaction | ||||||||
| FbcReactionLwrBoundSIdRef | LowerBound must be SIdRef | ||||||||
| FbcReactionUpBoundSIdRef | UpperBound must be SIdRef | ||||||||
| FbcReactionLwrBoundRefExists | LowerBound must point to Parameter | ||||||||
| FbcReactionUpBoundRefExists | UpperBound must point to Parameter | ||||||||
| FbcReactionMustHaveBoundsStrict | Reaction must have bounds when strict | ||||||||
| FbcReactionConstantBoundsStrict | Reaction bounds constant when strict | ||||||||
| FbcReactionBoundsMustHaveValuesStrict | Reaction bounds must have values when strict | ||||||||
| FbcReactionBoundsNotAssignedStrict | Reaction bounds not assigned when strict | ||||||||
| FbcReactionLwrBoundNotInfStrict | LowerBound cannot be INF when strict | ||||||||
| FbcReactionUpBoundNotNegInfStrict | UpperBound cannot be -INF when strict | ||||||||
| FbcReactionLwrLessThanUpStrict | LowerBound less than upperBound when strict | ||||||||
| FbcSpeciesReferenceConstantStrict | SpeciesReferences must be constant when strict | ||||||||
| FbcSpeciesRefsStoichMustBeRealStrict | Stoichiometry of SpeciesReferences must be real valued when strict | ||||||||
| FbcSpeciesRefNotAssignedStrict | SpeciesReference not target of InitialAssignment when strict | ||||||||
| FbcGeneProdAssocAllowedCoreAttribs | Allowed core attributes on <GeneProductAssociation> | ||||||||
| FbcGeneProdAssocAllowedCoreElements | Allowed core elements on <GeneProductAssociation> | ||||||||
| FbcGeneProdAssocAllowedAttribs | Allowed fbc attributes on <GeneProductAssociation> | ||||||||
| FbcGeneProdAssocIdSyntax | 'fbc:id' must have SId syntax | ||||||||
| FbcGeneProdAssocContainsOneElement | <GeneProductAssociation> must contain one concrete object | ||||||||
| FbcGeneProdAssocNameMustBeString | 'fbc:name' must be string | ||||||||
| FbcGeneProdRefAllowedCoreAttribs | Allowed core attributes on <GeneProductRef> | ||||||||
| FbcGeneProdRefAllowedCoreElements | Allowed core elements on <GeneProductRef> | ||||||||
| FbcGeneProdRefAllowedAttribs | Allowed fbc attributes on <GeneProductRef> | ||||||||
| FbcGeneProdRefGeneProductSIdRef | 'fbc:geneProduct' must be SIdRef | ||||||||
| FbcGeneProdRefGeneProductExists | 'fbc:geneProduct' must point to existing <GeneProduct> | ||||||||
| FbcAndAllowedCoreAttributes | Allowed core attributes on <And> | ||||||||
| FbcAndAllowedCoreElements | Allowed core attributes on <And> | ||||||||
| FbcAndTwoChildren | <And> must have at least two child elements | ||||||||
| FbcOrAllowedCoreAttributes | Allowed core attributes on <Or> | ||||||||
| FbcOrAllowedCoreElements | Allowed core elements on <Or> | ||||||||
| FbcOrTwoChildren | <Or> must have at least two child elements | ||||||||
| FbcGeneProductAllowedCoreAttributes | Allowed core attributes on <GeneProduct> | ||||||||
| FbcGeneProductAllowedCoreElements | Allowed core elements on <GeneProduct> | ||||||||
| FbcGeneProductAllowedAttributes | Allowed fbc attributes on <GeneProduct> | ||||||||
| FbcGeneProductLabelMustBeString | 'fbc:label' must be string | ||||||||
| FbcGeneProductLabelMustBeUnique | 'fbc:label' must be unique | ||||||||
| FbcGeneProductNameMustBeString | 'fbc:name' must be string | ||||||||
| FbcGeneProductAssocSpeciesMustExist | 'fbc:associatedSpecies' must point to existing <species> | ||||||||
| QualUnknown | |||||||||
| QualNSUndeclared | The qual ns is not correctly declared | ||||||||
| QualElementNotInNs | Element not in qual namespace | ||||||||
| QualFunctionTermBool | FunctionTerm should return Boolean | ||||||||
| QualMathCSymbolDisallowed | CSymbol time or delay not allowed | ||||||||
| QualDuplicateComponentId | Duplicate 'id' attribute value | ||||||||
| QualAttributeRequiredMissing | Required qual:required attribute on <sbml> | ||||||||
| QualAttributeRequiredMustBeBoolean | The qual:required attribute must be Boolean | ||||||||
| QualRequiredTrueIfTransitions | The qual:required attribute must be 'true' if math changes | ||||||||
| QualOneListOfTransOrQS | Only one <listOfTransitions> or <listOfQualitativeSpecies> allowed. | ||||||||
| QualEmptyLONotAllowed | Empty <listOfTransitions> or <listOfQualitativeSpecies> not allowed. | ||||||||
| QualLOTransitiondAllowedElements | Elements allowed on <listOfTransitions>. | ||||||||
| QualLOQualSpeciesAllowedElements | Elements allowed on <listOfTransitions>. | ||||||||
| QualLOQualSpeciesAllowedAttributes | Attributes allowed on <listOfQualitativeSpecies>. | ||||||||
| QualLOTransitionsAllowedAttributes | Attributes allowed on <listOfTransitions>. | ||||||||
| QualQualSpeciesAllowedCoreAttributes | Core attributes allowed on <qualitativeSpecies>. | ||||||||
| QualQualSpeciesAllowedElements | Elements allowed on <qualitativeSpecies>. | ||||||||
| QualQualSpeciesAllowedAttributes | Attributes allowed on <qualitativeSpecies>. | ||||||||
| QualConstantMustBeBool | Attribute 'constant' on <qualitativeSpecies> must be Boolean. | ||||||||
| QualNameMustBeString | Attribute 'name' on <qualitativeSpecies> must be string. | ||||||||
| QualInitialLevelMustBeInt | Attribute 'initialLevel' on <qualitativeSpecies> must be integer. | ||||||||
| QualMaxLevelMustBeInt | Attribute 'maxLevel' on <qualitativeSpecies> must be integer. | ||||||||
| QualCompartmentMustReferExisting | Attribute 'compartment' on <qualitativeSpecies> must reference compartment. | ||||||||
| QualInitialLevelCannotExceedMax | Attribute 'initialLevel' on <qualitativeSpecies> cannot exceed maxLevel. | ||||||||
| QualConstantQSCannotBeOutput | Constant <qualitativeSpecies> cannot be an Output. | ||||||||
| QualQSAssignedOnlyOnce | A <qualitativeSpecies> can only be assigned once. | ||||||||
| QualInitalLevelNotNegative | Attribute 'initialLevel' on <qualitativeSpecies> cannot be negative. | ||||||||
| QualMaxLevelNotNegative | Attribute 'maxLevel' on <qualitativeSpecies> cannot be negative. | ||||||||
| QualTransitionAllowedCoreAttributes | Core attributes allowed on <transition>. | ||||||||
| QualTransitionAllowedElements | Elements allowed on <transition>. | ||||||||
| QualTransitionAllowedAttributes | Attributes allowed on <transition>. | ||||||||
| QualTransitionNameMustBeString | Attribute 'name' on <transition> must be string. | ||||||||
| QualTransitionLOElements | ListOf elements on <transition>. | ||||||||
| QualTransitionEmptyLOElements | ListOf elements on <transition> not empty. | ||||||||
| QualTransitionLOInputElements | Elements on <listOfInputs>. | ||||||||
| QualTransitionLOOutputElements | Elements on <listOfOutputs>. | ||||||||
| QualTransitionLOFuncTermElements | Elements on <listOfFunctionTerms>. | ||||||||
| QualTransitionLOInputAttributes | Attributes allowed on <listOfInputs>. | ||||||||
| QualTransitionLOOutputAttributes | Attributes allowed on <listOfOutputs>. | ||||||||
| QualTransitionLOFuncTermAttributes | Attributes allowed on <listOfFunctionTerms>. | ||||||||
| QualTransitionLOFuncTermExceedMax | <listOfFunctionTerms> cannot make qualitativeSpecies exceed maxLevel. | ||||||||
| QualTransitionLOFuncTermNegative | <listOfFunctionTerms> cannot make qualitativeSpecies negative. | ||||||||
| QualInputAllowedCoreAttributes | Core attributes allowed on <input>. | ||||||||
| QualInputAllowedElements | Elements allowed on <input>. | ||||||||
| QualInputAllowedAttributes | Attributes allowed on <input>. | ||||||||
| QualInputNameMustBeString | Attribute 'name' on <input> must be string. | ||||||||
| QualInputSignMustBeSignEnum | Attribute 'sign' on <input> must be enum. | ||||||||
| QualInputTransEffectMustBeInputEffect | Attribute 'transitionEffect' on <input> must be enum. | ||||||||
| QualInputThreshMustBeInteger | Attribute 'thresholdLevel' on <input> must be non negative integer. | ||||||||
| QualInputQSMustBeExistingQS | Attribute 'qualitativeSpecies' on <input> must refer to existing | ||||||||
| QualInputConstantCannotBeConsumed | Constant <input> cannot be consumed. | ||||||||
| QualInputThreshMustBeNonNegative | Attribute 'thresholdLevel' on <input> must be non negative integer. | ||||||||
| QualOutputAllowedCoreAttributes | Core attributes allowed on <output>. | ||||||||
| QualOutputAllowedElements | Elements allowed on <output>. | ||||||||
| QualOutputAllowedAttributes | Attributes allowed on <output>. | ||||||||
| QualOutputNameMustBeString | Attribute 'name' on <output> must be string. | ||||||||
| QualOutputTransEffectMustBeOutput | Attribute 'transitionEffect' on <output> must be enum. | ||||||||
| QualOutputLevelMustBeInteger | Attribute 'outputLevel' on <output> must be non negative integer. | ||||||||
| QualOutputQSMustBeExistingQS | Attribute 'qualitativeSpecies' on <output> must refer to existing | ||||||||
| QualOutputConstantMustBeFalse | Constant 'qualitativeSpecies' cannot be <output> | ||||||||
| QualOutputProductionMustHaveLevel | <output> being produced must have level | ||||||||
| QualOutputLevelMustBeNonNegative | Attribute 'outputLevel' on <output> must be non negative integer. | ||||||||
| QualDefaultTermAllowedCoreAttributes | Core attributes allowed on <defaultTerm>. | ||||||||
| QualDefaultTermAllowedElements | Elements allowed on <defaultTerm>. | ||||||||
| QualDefaultTermAllowedAttributes | Attributes allowed on <defaultTerm>. | ||||||||
| QualDefaultTermResultMustBeInteger | Attribute 'resultLevel' on <defaultTerm> must be non negative integer. | ||||||||
| QualDefaultTermResultMustBeNonNeg | Attribute 'resultLevel' on <defaultTerm> must be non negative integer. | ||||||||
| QualFuncTermAllowedCoreAttributes | Core attributes allowed on <functionTerm>. | ||||||||
| QualFuncTermAllowedElements | Elements allowed on <functionTerm>. | ||||||||
| QualFuncTermAllowedAttributes | Attributes allowed on <functionTerm>. | ||||||||
| QualFuncTermOnlyOneMath | Only one <math> on <functionTerm>. | ||||||||
| QualFuncTermResultMustBeInteger | Attribute 'resultLevel' on <functionTerm> must be non negative integer. | ||||||||
| QualFuncTermResultMustBeNonNeg | Attribute 'resultLevel' on <functionTerm> must be non negative integer. | ||||||||
| GroupsUnknown | |||||||||
| GroupsNSUndeclared | The Groups namespace is not correctly declared. | ||||||||
| GroupsElementNotInNs | Element not in Groups namespace | ||||||||
| GroupsDuplicateComponentId | Duplicate 'id' attribute value | ||||||||
| GroupsIdSyntaxRule | Invalid SId syntax | ||||||||
| GroupsAttributeRequiredMissing | Required groups:required attribute on <sbml> | ||||||||
| GroupsAttributeRequiredMustBeBoolean | The groups:required attribute must be Boolean | ||||||||
| GroupsAttributeRequiredMustHaveValue | The groups:required attribute must be 'false' | ||||||||
| GroupsModelAllowedElements | Elements allowed on <model>. | ||||||||
| GroupsModelEmptyLOElements | No Empty ListOf elements allowed on <Model>. | ||||||||
| GroupsModelLOGroupsAllowedCoreElements | Core elements allowed on <model>. | ||||||||
| GroupsModelLOGroupsAllowedCoreAttributes | Core attributes allowed on <model>. | ||||||||
| GroupsGroupAllowedCoreAttributes | Core attributes allowed on <group>. | ||||||||
| GroupsGroupAllowedCoreElements | Core elements allowed on <group>. | ||||||||
| GroupsGroupAllowedAttributes | Attributes allowed on <group>. | ||||||||
| GroupsGroupAllowedElements | Elements allowed on <group>. | ||||||||
| GroupsGroupKindMustBeGroupKindEnum | Kind attribute must be GroupKind. | ||||||||
| GroupsGroupNameMustBeString | Name attribute must be String. | ||||||||
| GroupsGroupEmptyLOElements | No Empty ListOf elements allowed on <group>. | ||||||||
| GroupsGroupLOMembersAllowedCoreElements | Core elements allowed on <listOfMembers>. | ||||||||
| GroupsGroupLOMembersAllowedCoreAttributes | Core attributes allowed on <listOfMembers>. | ||||||||
| GroupsGroupLOMembersAllowedAttributes | Attributes allowed on <listOfMembers>. | ||||||||
| GroupsLOMembersNameMustBeString | Name attribute must be String. | ||||||||
| GroupsLOMembersConsistentReferences | Consistent references by multiple <member> objects. | ||||||||
| GroupsNotCircularReferences | Circular references by multiple <member> objects. | ||||||||
| GroupsMemberAllowedCoreAttributes | Core attributes allowed on <member>. | ||||||||
| GroupsMemberAllowedCoreElements | Core elements allowed on <member>. | ||||||||
| GroupsMemberAllowedAttributes | Attributes allowed on <member>. | ||||||||
| GroupsMemberNameMustBeString | Name attribute must be String. | ||||||||
| GroupsMemberIdRefMustBeSBase | Attribute 'idRef' must point to SBase object. | ||||||||
| GroupsMemberMetaIdRefMustBeSBase | Attribute 'metaIdRef' must point to SBase object. | ||||||||
| GroupsMemberIdRefMustBeSId | Attribute 'idRef' must be type 'SId'. | ||||||||
| GroupsMemberMetaIdRefMustBeID | Attribute 'metaIdRef' must be type 'ID'. | ||||||||
| LayoutUnknownError | |||||||||
| LayoutNSUndeclared | The layout ns is not correctly declared | ||||||||
| LayoutElementNotInNs | Element not in layout namespace | ||||||||
| LayoutDuplicateComponentId | Duplicate 'id' attribute value | ||||||||
| LayoutSIdSyntax | 'id' attribute incorrect syntax | ||||||||
| LayoutXsiTypeAllowedLocations | 'xsi:type' allowed locations | ||||||||
| LayoutXsiTypeSyntax | 'xsi:type' attribute incorrect syntax | ||||||||
| LayoutAttributeRequiredMissing | Required layout:required attribute on <sbml> | ||||||||
| LayoutAttributeRequiredMustBeBoolean | The layout:required attribute must be Boolean | ||||||||
| LayoutRequiredFalse | The layout:required attribute must be 'false' | ||||||||
| LayoutOnlyOneLOLayouts | Only one listOfLayouts on <model> | ||||||||
| LayoutLOLayoutsNotEmpty | ListOf elements cannot be empty | ||||||||
| LayoutLOLayoutsAllowedElements | Allowed elements on ListOfLayouts | ||||||||
| LayoutLOLayoutsAllowedAttributes | Allowed attributes on ListOfLayouts | ||||||||
| LayoutLayoutAllowedElements | Allowed elements on Layout | ||||||||
| LayoutLayoutAllowedCoreAttributes | Allowed core attributes on Layout | ||||||||
| LayoutOnlyOneEachListOf | Only one each listOf on <layout> | ||||||||
| LayoutNoEmptyListOfs | ListOf elements cannot be empty | ||||||||
| LayoutLayoutAllowedAttributes | <layout> must have 'id' and may have 'name' | ||||||||
| LayoutLayoutNameMustBeString | 'name' must be string | ||||||||
| LayoutLOCompGlyphAllowedAttributes | Attributes allowed on <listOfCompartmentGlyphs>. | ||||||||
| LayoutLOCompGlyphAllowedElements | Elements allowed on <listOfCompartmentGlyphs>. | ||||||||
| LayoutLOSpeciesGlyphAllowedAttributes | Attributes allowed on <listOfSpeciesGlyphs>. | ||||||||
| LayoutLOSpeciesGlyphAllowedElements | Elements allowed on <listOfSpeciesGlyphs>. | ||||||||
| LayoutLORnGlyphAllowedAttributes | Attributes allowed on <listOfReactionGlyphs>. | ||||||||
| LayoutLORnGlyphAllowedElements | Elements allowed on <listOfReactionGlyphs>. | ||||||||
| LayoutLOAddGOAllowedAttribut | Attributes allowed on <listOfAdditionalGraphicalObjectGlyphs>. | ||||||||
| LayoutLOAddGOAllowedElements | Elements allowed on <listOfAdditionalGraphicalObjectGlyphs>. | ||||||||
| LayoutLayoutMustHaveDimensions | Layout must have <dimensions>. | ||||||||
| LayoutLOTextGlyphAllowedAttributes | Attributes allowed on <listOfTextGlyphs>. | ||||||||
| LayoutLOTextGlyphAllowedElements | Elements allowed on <listOfTextGlyphs>. | ||||||||
| LayoutGOAllowedCoreElements | Core elements allowed on <graphicalObject>. | ||||||||
| LayoutGOAllowedCoreAttributes | Core attributes allowed on <graphicalObject>. | ||||||||
| LayoutGOAllowedElements | Layout elements allowed on <graphicalObject>. | ||||||||
| LayoutGOAllowedAttributes | Layout attributes allowed on <graphicalObject>. | ||||||||
| LayoutGOMetaIdRefMustBeIDREF | Layout 'metaidRef' must be IDREF. | ||||||||
| LayoutGOMetaIdRefMustReferenceObject | Layout 'metaidRef' must reference existing object. | ||||||||
| LayoutGOMustContainBoundingBox | A <graphicalObject> must contain a <boundingBox>. | ||||||||
| LayoutCGAllowedCoreElements | Core elements allowed on <compartmentGlyph>. | ||||||||
| LayoutCGAllowedCoreAttributes | Core attributes allowed on <compartmentGlyph>. | ||||||||
| LayoutCGAllowedElements | Layout elements allowed on <compartmentGlyph>. | ||||||||
| LayoutCGAllowedAttributes | Layout attributes allowed on <compartmentGlyph>. | ||||||||
| LayoutCGMetaIdRefMustBeIDREF | Layout 'metaidRef' must be IDREF. | ||||||||
| LayoutCGMetaIdRefMustReferenceObject | Layout 'metaidRef' must reference existing object. | ||||||||
| LayoutCGCompartmentSyntax | CompartmentGlyph 'compartment' must have SIdRef syntax. | ||||||||
| LayoutCGCompartmentMustRefComp | CompartmentGlyph compartment must reference existing compartment. | ||||||||
| LayoutCGNoDuplicateReferences | CompartmentGlyph cannot reference two objects. | ||||||||
| LayoutCGOrderMustBeDouble | CompartmentGlyph order must be double. | ||||||||
| LayoutSGAllowedCoreElements | Core elements allowed on <speciesGlyph>. | ||||||||
| LayoutSGAllowedCoreAttributes | Core attributes allowed on <speciesGlyph>. | ||||||||
| LayoutSGAllowedElements | Layout elements allowed on <speciesGlyph>. | ||||||||
| LayoutSGAllowedAttributes | Layout attributes allowed on <speciesGlyph>. | ||||||||
| LayoutSGMetaIdRefMustBeIDREF | Layout 'metaidRef' must be IDREF. | ||||||||
| LayoutSGMetaIdRefMustReferenceObject | Layout 'metaidRef' must reference existing object. | ||||||||
| LayoutSGSpeciesSyntax | SpeciesGlyph 'species' must have SIdRef syntax. | ||||||||
| LayoutSGSpeciesMustRefSpecies | SpeciesGlyph species must reference existing species. | ||||||||
| LayoutSGNoDuplicateReferences | SpeciesGlyph cannot reference two objects. | ||||||||
| LayoutRGAllowedCoreElements | Core elements allowed on <reactionGlyph>. | ||||||||
| LayoutRGAllowedCoreAttributes | Core attributes allowed on <reactionGlyph>. | ||||||||
| LayoutRGAllowedElements | Layout elements allowed on <reactionGlyph>. | ||||||||
| LayoutRGAllowedAttributes | Layout attributes allowed on <reactionGlyph>. | ||||||||
| LayoutRGMetaIdRefMustBeIDREF | Layout 'metaidRef' must be IDREF. | ||||||||
| LayoutRGMetaIdRefMustReferenceObject | Layout 'metaidRef' must reference existing object. | ||||||||
| LayoutRGReactionSyntax | ReactionGlyph 'reaction' must have SIdRef syntax. | ||||||||
| LayoutRGReactionMustRefReaction | ReactionGlyph reaction must reference existing reaction. | ||||||||
| LayoutRGNoDuplicateReferences | ReactionGlyph cannot reference two objects. | ||||||||
| LayoutLOSpeciesRefGlyphAllowedElements | Allowed elements on ListOfSpeciesReferenceGlyphs | ||||||||
| LayoutLOSpeciesRefGlyphAllowedAttribs | Allowed attributes on ListOfSpeciesReferenceGlyphs | ||||||||
| LayoutLOSpeciesRefGlyphNotEmpty | ListOfSpeciesReferenceGlyphs not empty | ||||||||
| LayoutGGAllowedCoreElements | Core elements allowed on <generalGlyph>. | ||||||||
| LayoutGGAllowedCoreAttributes | Core attributes allowed on <generalGlyph>. | ||||||||
| LayoutGGAllowedElements | Layout elements allowed on <generalGlyph>. | ||||||||
| LayoutGGAllowedAttributes | Layout attributes allowed on <generalGlyph>. | ||||||||
| LayoutGGMetaIdRefMustBeIDREF | Layout 'metaidRef' must be IDREF. | ||||||||
| LayoutGGMetaIdRefMustReferenceObject | Layout 'metaidRef' must reference existing object. | ||||||||
| LayoutGGReferenceSyntax | GeneralGlyph 'reference' must have SIdRef syntax. | ||||||||
| LayoutGGReferenceMustRefObject | GeneralGlyph 'reference' must reference existing element. | ||||||||
| LayoutGGNoDuplicateReferences | GeneralGlyph cannot reference two objects. | ||||||||
| LayoutLOReferenceGlyphAllowedElements | Allowed elements on ListOfReferenceGlyphs | ||||||||
| LayoutLOReferenceGlyphAllowedAttribs | Allowed attributes on ListOfReferenceGlyphs | ||||||||
| LayoutLOSubGlyphAllowedElements | |||||||||
| LayoutLOSubGlyphAllowedAttribs | Allowed attributes on ListOfSubGlyphs | ||||||||
| LayoutTGAllowedCoreElements | Core elements allowed on <textGlyph>. | ||||||||
| LayoutTGAllowedCoreAttributes | Core attributes allowed on <textGlyph>. | ||||||||
| LayoutTGAllowedElements | Layout elements allowed on <textGlyph>. | ||||||||
| LayoutTGAllowedAttributes | Layout attributes allowed on <textGlyph>. | ||||||||
| LayoutTGMetaIdRefMustBeIDREF | Layout 'metaidRef' must be IDREF. | ||||||||
| LayoutTGMetaIdRefMustReferenceObject | Layout 'metaidRef' must reference existing object. | ||||||||
| LayoutTGOriginOfTextSyntax | TextGlyph 'originOfText' must have SIdRef syntax. | ||||||||
| LayoutTGOriginOfTextMustRefObject | TextGlyph 'originOfText' must reference existing element. | ||||||||
| LayoutTGNoDuplicateReferences | TextGlyph cannot reference two objects. | ||||||||
| LayoutTGGraphicalObjectSyntax | TextGlyph 'graphicalObject' must have SIdRef syntax. | ||||||||
| LayoutTGGraphicalObjectMustRefObject | TextGlyph 'graphicalObject' must reference existing element. | ||||||||
| LayoutTGTextMustBeString | TextGlyph 'text' must be string. | ||||||||
| LayoutSRGAllowedCoreElements | Core elements allowed on <speciesReferenceGlyph>. | ||||||||
| LayoutSRGAllowedCoreAttributes | Core attributes allowed on <speciesReferenceGlyph>. | ||||||||
| LayoutSRGAllowedElements | Layout elements allowed on <speciesReferenceGlyph>. | ||||||||
| LayoutSRGAllowedAttributes | Layout attributes allowed on <speciesReferenceGlyph>. | ||||||||
| LayoutSRGMetaIdRefMustBeIDREF | Layout 'metaidRef' must be IDREF. | ||||||||
| LayoutSRGMetaIdRefMustReferenceObject | Layout 'metaidRef' must reference existing object. | ||||||||
| LayoutSRGSpeciesReferenceSyntax | SpeciesReferenceGlyph 'speciesReference' must have SIdRef syntax. | ||||||||
| LayoutSRGSpeciesRefMustRefObject | SpeciesReferenceGlyph 'speciesReference' must reference existing element. | ||||||||
| LayoutSRGNoDuplicateReferences | SpeciesReferenceGlyph cannot reference two objects. | ||||||||
| LayoutSRGSpeciesGlyphSyntax | SpeciesReferenceGlyph 'speciesGlyph' must have SIdRef syntax. | ||||||||
| LayoutSRGSpeciesGlyphMustRefObject | SpeciesReferenceGlyph 'speciesGlyph' must reference existing element. | ||||||||
| LayoutSRGRoleSyntax | SpeciesReferenceGlyph 'role' must be string from enumeration. | ||||||||
| LayoutREFGAllowedCoreElements | Core elements allowed on <referenceGlyph>. | ||||||||
| LayoutREFGAllowedCoreAttributes | Core attributes allowed on <referenceGlyph>. | ||||||||
| LayoutREFGAllowedElements | Layout elements allowed on <referenceGlyph>. | ||||||||
| LayoutREFGAllowedAttributes | Layout attributes allowed on <referenceGlyph>. | ||||||||
| LayoutREFGMetaIdRefMustBeIDREF | Layout 'metaidRef' must be IDREF. | ||||||||
| LayoutREFGMetaIdRefMustReferenceObject | Layout 'metaidRef' must reference existing object. | ||||||||
| LayoutREFGReferenceSyntax | ReferenceGlyph 'reference' must have SIdRef syntax. | ||||||||
| LayoutREFGReferenceMustRefObject | ReferenceGlyph 'reference' must reference existing element. | ||||||||
| LayoutREFGNoDuplicateReferences | ReferenceGlyph cannot reference two objects. | ||||||||
| LayoutREFGGlyphSyntax | ReferenceGlyph 'glyph' must have SIdRef syntax. | ||||||||
| LayoutREFGGlyphMustRefObject | ReferenceGlyph 'glyph' must reference existing element. | ||||||||
| LayoutREFGRoleSyntax | ReferenceGlyph 'role' must be string. | ||||||||
| LayoutPointAllowedCoreElements | Core elements allowed on <point>. | ||||||||
| LayoutPointAllowedCoreAttributes | Core attributes allowed on <point>. | ||||||||
| LayoutPointAllowedAttributes | Layout attributes allowed on <point>. | ||||||||
| LayoutPointAttributesMustBeDouble | Layout 'x', 'y' and 'z' must be double. | ||||||||
| LayoutBBoxAllowedCoreElements | Core elements allowed on <boundingBox>. | ||||||||
| LayoutBBoxAllowedCoreAttributes | Core attributes allowed on <boundingBox>. | ||||||||
| LayoutBBoxAllowedElements | Layout elements allowed on <boundingBox>. | ||||||||
| LayoutBBoxAllowedAttributes | Layout attributes allowed on <boundingBox>. | ||||||||
| LayoutBBoxConsistent3DDefinition | Layout consistent dimensions on a <boundingBox> | ||||||||
| LayoutCurveAllowedCoreElements | Core elements allowed on <curve>. | ||||||||
| LayoutCurveAllowedCoreAttributes | Core attributes allowed on <curve>. | ||||||||
| LayoutCurveAllowedElements | Layout elements allowed on <curve>. | ||||||||
| LayoutCurveAllowedAttributes | Layout attributes allowed on <curve>. | ||||||||
| LayoutLOCurveSegsAllowedAttributes | Allowed attributes on ListOfCurveSegments | ||||||||
| LayoutLOCurveSegsAllowedElements | Allowed elements on ListOfCurveSegments | ||||||||
| LayoutLOCurveSegsNotEmpty | No empty ListOfCurveSegments | ||||||||
| LayoutLSegAllowedCoreElements | Core elements allowed on <lineSegment>. | ||||||||
| LayoutLSegAllowedCoreAttributes | Core attributes allowed on <lineSegment>. | ||||||||
| LayoutLSegAllowedElements | Layout elements allowed on <lineSegment>. | ||||||||
| LayoutLSegAllowedAttributes | Layout attributes allowed on <lineSegment>. | ||||||||
| LayoutCBezAllowedCoreElements | Core elements allowed on <cubicBezier>. | ||||||||
| LayoutCBezAllowedCoreAttributes | Core attributes allowed on <cubicBezier>. | ||||||||
| LayoutCBezAllowedElements | Layout elements allowed on <cubicBezier>. | ||||||||
| LayoutCBezAllowedAttributes | Layout attributes allowed on <cubicBezier>. | ||||||||
| LayoutDimsAllowedCoreElements | Core elements allowed on <dimensions>. | ||||||||
| LayoutDimsAllowedCoreAttributes | Core attributes allowed on <dimensions>. | ||||||||
| LayoutDimsAllowedAttributes | Layout attributes allowed on <dimensions>. | ||||||||
| LayoutDimsAttributesMustBeDouble | Layout 'width', 'height' and 'depth' must be double. |
SBMLErrorCategory_t is an enumeration of category codes for SBMLError diagnostics. The category can be retrieved from an SBMLError object using the method SBMLError::getCategory(). These enumeration values are distinct from (and in addition to) the XMLErrorCategory_t codes used by the parent XMLError object. User programs receiving an SBMLError object can use this distinction to check whether the error represents a low-level XML problem or an SBML problem.
The following table lists each possible value and a brief description of its meaning.
| Enumerator | Meaning |
|---|---|
| LIBSBML_CAT_SBML | General error not falling into another category below. |
| LIBSBML_CAT_SBML_L1_COMPAT | Category of errors that can only occur during attempted translation from one Level/Version of SBML to another. This particular category applies to errors encountered while trying to convert a model from SBML Level 2 to SBML Level 1. |
| LIBSBML_CAT_SBML_L2V1_COMPAT | Category of errors that can only occur during attempted translation from one Level/Version of SBML to another. This particular category applies to errors encountered while trying to convert a model to SBML Level 2 Version 1. |
| LIBSBML_CAT_SBML_L2V2_COMPAT | Category of errors that can only occur during attempted translation from one Level/Version of SBML to another. This particular category applies to errors encountered while trying to convert a model to SBML Level 2 Version 2. |
| LIBSBML_CAT_GENERAL_CONSISTENCY | Category of errors that can occur while validating general SBML constructs. With respect to the SBML specification, these concern failures in applying the validation rules numbered 2xxxx in the Level 2 Versions 2–4 and Level 3 Versions 1–2 specifications. |
| LIBSBML_CAT_IDENTIFIER_CONSISTENCY | Category of errors that can occur while validating symbol identifiers in a model. With respect to the SBML specification, these concern failures in applying the validation rules numbered 103xx in the Level 2 Versions 2–4 and Level 3 Versions 1–2 specifications. |
| LIBSBML_CAT_UNITS_CONSISTENCY | Category of errors that can occur while validating the units of measurement on quantities in a model. With respect to the SBML specification, these concern failures in applying the validation rules numbered 105xx in the Level 2 Versions 2–4 and Level 3 Versions 1–2 specifications. |
| LIBSBML_CAT_MATHML_CONSISTENCY | Category of errors that can occur while validating MathML formulas in a model. With respect to the SBML specification, these concern failures in applying the validation rules numbered 102xx in the Level 2 Versions 2–4 and Level 3 Versions 1–2 specifications. |
| LIBSBML_CAT_SBO_CONSISTENCY | Category of errors that can occur while validating SBO identifiers in a model. With respect to the SBML specification, these concern failures in applying the validation rules numbered 107xx in the Level 2 Versions 2–4 and Level 3 Versions 1–2 specifications. |
| LIBSBML_CAT_OVERDETERMINED_MODEL | Error in the system of equations in the model: the system is overdetermined, therefore violating a tenet of proper SBML. With respect to the SBML specification, this is validation rule #10601 in the SBML Level 2 Versions 2–4 and Level 3 Versions 1–2 specifications. |
| LIBSBML_CAT_SBML_L2V3_COMPAT | Category of errors that can only occur during attempted translation from one Level/Version of SBML to another. This particular category applies to errors encountered while trying to convert a model to SBML Level 2 Version 3. |
| LIBSBML_CAT_MODELING_PRACTICE | Category of warnings about recommended good practices involving SBML and computational modeling. (These are tests performed by libSBML and do not have equivalent SBML validation rules.) |
| LIBSBML_CAT_INTERNAL_CONSISTENCY | Category of errors that can occur while validating libSBML's internal representation of SBML constructs. (These are tests performed by libSBML and do not have equivalent SBML validation rules.) |
| LIBSBML_CAT_SBML_L2V4_COMPAT | Category of errors that can only occur during attempted translation from one Level/Version of SBML to another. This particular category applies to errors encountered while trying to convert a model to SBML Level 2 Version 4. |
| LIBSBML_CAT_SBML_L3V1_COMPAT | Category of errors that can only occur during attempted translation from one Level/Version of SBML to another. This particular category applies to errors encountered while trying to convert a model to SBML Level 3 Version 1. |
This is an enumeration of severity codes for SBMLError diagnostics. User programs receiving an SBMLError object can use this distinction to check whether the error represents a low-level XML problem or an SBML problem.
In libSBML version 5.20.2 there are no additional severity codes in SBMLErrorSeverity_t beyond those defined in XMLErrorSeverity_t.
| typedef class SBMLErrorLog SBMLErrorLog_t |
This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.
The error log is a list. Each SBMLDocument maintains its own SBMLErrorLog. When a libSBML operation on SBML content results in an error, or when there is something worth noting about the SBML content, the issue is reported as an SBMLError object stored in the SBMLErrorLog list.
SBMLErrorLog is derived from XMLErrorLog, an object class that serves exactly the same purpose but for the XML parsing layer. XMLErrorLog provides crucial methods such as getNumErrors() for determining how many SBMLError or XMLError objects are in the log. SBMLErrorLog inherits these methods.
The general approach to working with SBMLErrorLog in user programs involves first obtaining a pointer to a log from a libSBML object such as SBMLDocument. Callers should then use getNumErrors() to inquire how many objects there are in the list. (The answer may be 0.) If there is at least one SBMLError object in the SBMLErrorLog instance, callers can then iterate over the list using SBMLErrorLog::getError()const, using methods provided by the SBMLError class to find out the error code and associated information such as the error severity, the message, and the line number in the input.
If you wish to simply print the error strings for a human to read, an easier and more direct way might be to use SBMLDocument::printErrors().
| typedef class SBMLExtension SBMLExtension_t |
This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.
The SBMLExtension class is a component of the libSBML package extension mechanism. It is an abstract class that is extended by each package extension implementation. The SBMLExtension class provides methods for managing common attributes of package extensions (e.g., package name, package version), registration of instantiated SBasePluginCreator objects, and initialization/registration of package extensions when the library code for the package is loaded.
GroupsExtension serves this purpose for the SBML Level 3 Groups package extension in libSBML. The following subsections detail the basic steps involved in implementing such an extended class.Define a method named getPackageName() that returns the name of the package as a string. The following is an example from the implementation of the Groups package extension:
Define a set of methods that return the default SBML Level, SBML Version and version of the package. These methods must be named getDefaultLevel(), getDefaultVersion() and getDefaultPackageVersion(), respectively. The following are examples drawn from the Groups package implementation:
Define methods that return strings representing the XML namespace URI for the package. One method should be defined for each SBML Level/Version combination for which the package can be used. For instance, if a package is only usable in SBML Level 3 Version 1, and the libSBML extension for the package implements version 1 of the package, the necessary method is getXmlnsL3V1V1().
Define other similar methods to return additional namespace URIs if the package extension implements other package versions or supports other SBML Level/Version combinations.
Override the following pure virtual methods on SBMLExtension:
virtual const std::string& getName() const =0. This method returns the nickname of the package (e.g., "layout", "groups").virtual unsigned int getLevel(const std::string& uri) const =0. This method returns the SBML Level with the given URI of this package.virtual unsigned int getVersion(const std::string& uri) const =0. This method returns the SBML Version with the given URI of this package.virtual unsigned int getPackageVersion(const std::string &uri) const =0. This method returns the package version with the given URI of this package.virtual unsigned int getURI(unsigned int sbmlLevel, unsigned int sbmlVersion, unsigned int pkgVersion) const =0. This method returns the URI (namespace) of the package corresponding to the combination of the given SBML Level, SBML Version, and package versionvirtual SBMLExtension* clone() const = 0. This method creates and returns a deep copy of this derived object.As an example, the following are the versions of these methods for the Groups package:
Constructor, copy constructor, and destructor methods also must be overridden if additional data members are defined in the derived class.
Define typedef and template instantiation code for a package-specific subclass of the SBMLExtensionNamespaces template class. The SBMLExtensionNamespaces template class is a derived class of SBMLNamespaces and can be used as an argument of constructors of SBase-derived classes defined in the package extensions.
Define a typedef. For example, the typedef for GroupsExtension is implemented in the file GroupsExtension.h as follows:
Define a template instantiation for the typedef. For example, the template instantiation code for GroupsExtension is implemented in the file GroupsExtension.cpp as follows:
Here is example of how the resulting class is used. The definitions above allow a GroupsPkgNamespaces object to be used when creating a new Group object. The GroupsPkgNamespaces is handed to the constructor as an argument, as shown below:
The GroupsPkgNamespaces object can also be used when creating an SBMLDocument object with the Groups package. The code fragment below shows an example of this:
Override the pure virtual method getSBMLExtensionNamespaces(), which returns an SBMLNamespaces derived object. For example, the method is overridden in the class GroupsExtension as follows:
Define an enum type for representing the type code of the objects defined in the package extension. For example, the enumeration SBMLGroupsTypeCode_t for the Groups package is defined in GroupsExtension.h as follows:
In the enumeration above, SBML_GROUPS_GROUP corresponds to the Group class (for the <group> element defined by the SBML Level 3 Groups package) and SBML_GROUPS_MEMBER corresponds to the Member class (for the <member> element defined by the Level 3 Groups package), respectively.
Similarly, SBMLLayoutTypeCode_t for the Layout package is defined in the file LayoutExtension.h as follows:
These enum values are returned by corresponding getTypeCode() methods. (E.g., SBML_GROUPS_GROUP is returned in Group::getTypeCode().)
Note that libSBML does not require that type codes are unique across all packages—the same type codes may be used within individual package extensions. LibSBML development must permit this because package implementations are developed by separate groups at different times; coordinating the type codes used is impractical. It does mean that callers must check two things when identifying objects: to distinguish the type codes of different packages, callers much check not only the return value of the method getTypeCode() method but also that of the method getPackageName(). Here is an example of doing that:
Readers may have noticed that in the SBMLLayoutTypeCode_t and SBMLGroupsTypeCode_t enumerations above, unique values are in fact assigned to the enumeration values. This can be convenient when it can be arranged, but it is not required by libSBML.
Override the pure virtual method getStringFromTypeCode(), which returns a string corresponding to the given type code. Here is an example, again drawn from the implementation of the Groups package:
For example, the method for the Groups extension is implemented as shown below:
Implement a static void init() method in the derived class. This method serves to encapsulate initialization code that creates an instance of the derived class and registration code that registers the instance with the SBMLExtensionRegistry class.
For example, the init() method for the Groups package is implemented as follows:
Instantiate a global SBMLExtensionRegister object using the class derived from SBMLExtension (discussed above). Here is an example for the Groups package extension, for the object GroupsExtension. This could is placed in the GroupsExtension.cpp:
The init() method on GroupsExtension is automatically invoked when the "register" object is instantiated. This results in initialization and registration of the package extension with libSBML.
This has the following consequence. If an application queries for the presence of Layout in an SBML Level 2 document by testing only for the existence of the plugin object, it will always get a positive result; in other words, the presence of a Layout extension object is not an indication of whether a read-in Level 2 document does or does not use SBML Layout. Instead, callers have to query explicitly for the existence of layout information. An example of such a query is the following code:
The special, always-available Level 2 Layout behavior was motivated by a desire to support legacy applications. In SBML Level 3, the Layout package uses the normal SBML Level 3 scheme of requiring declarations on the SBML document element. This means that upon reading a model, libSBML knows right away whether it contains layout information. In SBML Level 2, there is no top-level declaration because layout is stored as annotations in the body of the model. Detecting the presence of layout information when reading a Level 2 model requires parsing the annotations. For efficiency reasons, libSBML normally does not parse annotations automatically when reading a model. However, applications that predated the introduction of Level 3 Layout and the updated version of libSBML never had to do anything special to enable parsing layout; the facilities were always available for every Level 2 model as long as libSBML was compiled with Layout support. To avoid burdening developers of legacy applications with the need to modify their software, libSBML provides backward compatibility by always preloading the Layout package extension when reading Level 2 models. The same applies to the creation of Level 2 models: with the plugin-oriented libSBML, applications normally would have to take deliberate steps to activate package code, instantiate objects, manage namespaces, and so on. LibSBML again loads the Layout package plugin automatically when creating a Level 2 model, thereby making the APIs available to legacy applications without further work on their part.
The mechanisms for triggering this Level 2-specific behavior involves a set of virtual methods on the SBMLExtension class that must be implemented by individual package extensions. These methods are SBMLExtension::addL2Namespaces(), SBMLExtension::removeL2Namespaces(), and SBMLExtension::enableL2NamespaceForDocument().
| typedef class SBMLExtensionNamespaces SBMLExtensionNamespaces_t |
This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.
SBMLExtensionNamespaces is a template class. It is extended from SBMLNamespaces and is meant to be used by package extensions to store the SBML Level, Version within a Level, and package version of the SBML Level 3 package implemented by a libSBML package extension.
typedef. The following sections explain these steps in detail.Each package needs to declare a package-specific version of the SBMLExtensionNamespaces class using a typedef. The following example code demonstrates how this is done in the case of the Layout package:
This creates a new type called LayoutPkgNamespaces. The code above is usually placed in the same file that contains the SBMLExtension-derived definition of the package extension base class. In the case of the Layout package, this is in the file src/packages/layout/extension/LayoutExtension.h in the libSBML source distribution.
Each package needs to instantiate a template instance of the SBMLExtensionNamespaces class. The following example code demonstrates how this is done in the case of the Layout package:
In the case of the Layout package, the code above is located in the file src/packages/layout/extension/LayoutExtension.cpp in the libSBML source distribution.
Each SBase-derived class in the package extension should implement a constructor that accepts the SBMLExtensionNamespaces-derived class as an argument. For example, in the Layout package, the class BoundBox has a constructor declared as follows
The implementation of this constructor must, among other things, take the argument namespace object and use it to set the XML namespace URI for the object. Again, for the BoundingBox example:
| typedef class SBMLNamespaces SBMLNamespaces_t |
This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.
There are differences in the definitions of components between different SBML Levels, as well as Versions within Levels. For example, the "sboTerm" attribute was not introduced until Level 2 Version 2, and then only on certain component classes; the SBML Level 2 Version 3 specification moved the "sboTerm" attribute to the SBase class, thereby allowing nearly all components to have SBO annotations. As a result of differences such as those, libSBML needs to track the SBML Level and Version of every object created.
The purpose of the SBMLNamespaces object class is to make it easier to communicate SBML Level and Version data between libSBML constructors and other methods. The SBMLNamespaces object class tracks 3-tuples (triples) consisting of SBML Level, Version, and the corresponding SBML XML namespace.
The plural name (SBMLNamespaces) is not a mistake, because in SBML Level 3, objects may have extensions added by Level 3 packages used by a given model and therefore may have multiple namespaces associated with them; however, until the introduction of SBML Level 3, the SBMLNamespaces object only records one SBML Level/Version/namespace combination at a time. Most constructors for SBML objects in libSBML take a SBMLNamespaces object as an argument, thereby allowing the constructor to produce the proper combination of attributes and other internal data structures for the given SBML Level and Version.
| typedef class SBMLReader SBMLReader_t |
This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.
The SBMLReader class provides the main interface for reading SBML content from files and strings. The methods for reading SBML all return an SBMLDocument object representing the results. In the case of failures (such as if the SBML contains errors or a file cannot be read), the errors will be recorded with the SBMLErrorLog object kept in the SBMLDocument returned by SBMLReader. Consequently, immediately after calling a method on SBMLReader, callers should always check for errors and warnings using the methods for this purpose provided by SBMLDocument.
For convenience as well as easy access from other languages besides C++, this file also defines two global functions, @sbmlglobalfunction{readSBML, String} and @sbmlglobalfunction{readSBMLFromString, String}. They are equivalent to creating an SBMLReader object and then calling the SBMLReader::readSBML() and SBMLReader::readSBMLFromString() methods, respectively.
LibSBML provides support for reading (as well as writing) compressed SBML files. The process is transparent to the calling application—the application does not need to do anything deliberate to invoke the functionality. If a given SBML filename ends with an extension for the gzip, zip or bzip2 compression formats (respectively, .gz, .zip, or .bz2), then the methods SBMLReader::readSBML() and SBMLWriter::writeSBML() will automatically decompress and compress the file while reading and writing it. If the filename has no such extension, it will be read and written uncompressed as normal.
The compression feature requires that the zlib (for gzip and zip formats) and/or bzip2 (for bzip2 format) be available on the system running libSBML, and that libSBML was configured with their support compiled-in. Please see the libSBML installation instructions for more information about this. The methods hasZlib() and hasBzip2() can be used by an application to query at run-time whether support for the compression libraries is available in the present copy of libSBML.
Support for compression is not mandated by the SBML standard, but applications may find it helpful, particularly when large SBML models are being communicated across data links of limited bandwidth.
| typedef class SBMLWriter SBMLWriter_t |
This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.
The SBMLWriter class is the converse of SBMLReader, and provides the main interface for serializing SBML models into XML and writing the result to an output stream or to files and text strings. The methods for writing SBML all take an SBMLDocument object and a destination. They return a boolean or integer value to indicate success or failure.
LibSBML provides support for writing (as well as reading) compressed SBML files. The process is transparent to the calling application—the application does not need to do anything deliberate to invoke the functionality. If a given SBML filename ends with an extension for the gzip, zip or bzip2 compression formats (respectively, ".gz", ".zip", or ".bz2"), then the methods SBMLWriter::writeSBML() and SBMLReader::readSBML() will automatically compress and decompress the file while writing and reading it. If the filename has no such extension, it will be written and read uncompressed as normal.
The compression feature requires that the zlib (for gzip and zip formats) and/or bzip2 (for bzip2 format) be available on the system running libSBML, and that libSBML was configured with their support compiled-in. Please see the libSBML installation instructions for more information about this. The methods SBMLWriter::hasZlib() and SBMLWriter::hasBzip2() can be used by an application to query at run-time whether support for the compression libraries is available in the present copy of libSBML.
Support for compression is not mandated by the SBML standard, but applications may find it helpful, particularly when large SBML models are being communicated across data links of limited bandwidth.
A species in SBML refers to a pool of entities that (a) are considered indistinguishable from each other for the purposes of the model, (b) participate in reactions, and (c) are located in a specific compartment. The SBML Species object class is intended to represent these pools.
As with other major constructs in SBML, Species has a mandatory attribute, "id", used to give the species type an identifier in the model. The identifier must be a text string conforming to the identifer syntax permitted in SBML. Species also has an optional "name" attribute, of type string. The "id" and "name" must be used according to the guidelines described in the SBML specifications.
The required attribute "compartment" is used to identify the compartment in which the species is located. The attribute's value must be the identifier of an existing Compartment object. It is important to note that there is no default value for the "compartment" attribute on Species; every species in an SBML model must be assigned a compartment explicitly. (This also implies that every model with one or more Species objects must define at least one Compartment object.)
The optional attributes "initialAmount" and "initialConcentration", both having a data type of double, can be used to set the initial quantity of the species in the compartment where the species is located. These attributes are mutually exclusive; i.e., only one can have a value on any given instance of a Species object. Missing "initialAmount" and "initialConcentration" values implies that their values either are unknown, or to be obtained from an external source, or determined by an InitialAssignment or other SBML construct elsewhere in the model.
A species' initial quantity in SBML is set by the "initialAmount" or "initialConcentration" attribute exactly once. If the "constant" attribute is true, then the value of the species' quantity is fixed and cannot be changed except by an InitialAssignment. These methods differ in that the "initialAmount" and "initialConcentration" attributes can only be used to set the species quantity to a literal floating-point number, whereas the use of an InitialAssignment object allows the value to be set using an arbitrary mathematical expression (which, thanks to MathML's expressiveness, may evaluate to a rational number). If the species' "constant" attribute is false, the species' quantity value may be overridden by an InitialAssignment or changed by AssignmentRule or AlgebraicRule, and in addition, for t > 0, it may also be changed by a RateRule, Event objects, and as a result of being a reactant or product in one or more Reaction objects. (However, some constructs are mutually exclusive; see the SBML specifications for the precise details.) It is not an error to define "initialAmount" or "initialConcentration" on a species and also redefine the value using an InitialAssignment, but the "initialAmount" or "initialConcentration" setting in that case is ignored. The SBML specifications provide additional information about the semantics of assignments, rules and values for simulation time t \(\leq\) 0.
SBML Level 2 additionally stipulates that in cases where a species' compartment has a "spatialDimensions" value of 0 (zero), the species cannot have a value for "initialConcentration" because the concepts of concentration and density break down when a container has zero dimensions.
When the attribute "initialAmount" is set, the unit of measurement associated with the value of "initialAmount" is specified by the Species attribute "substanceUnits". When the "initialConcentration" attribute is set, the unit of measurement associated with this concentration value is {unit of amount} divided by {unit of size}, where the {unit of amount} is specified by the Species "substanceUnits" attribute, and the {unit of size} is specified by the "units" attribute of the Compartment object in which the species is located. Note that in either case, a unit of amount is involved and determined by the "substanceUnits" attribute. Note these two attributes alone do not determine the units of the species when the species identifier appears in a mathematical expression; that aspect is determined by the attribute "hasOnlySubstanceUnits" discussed below.
In SBML Level 3, if the "substanceUnits" attribute is not set on a given Species object instance, then the unit of amount for that species is inherited from the "substanceUnits" attribute on the enclosing Model object instance. If that attribute on Model is not set either, then the unit associated with the species' quantity is undefined.
In SBML Level 2, if the "substanceUnits" attribute is not set on a given Species object instance, then the unit of amount for that species is taken from the predefined SBML unit identifier "substance". The value assigned to "substanceUnits" must be chosen from one of the following possibilities: one of the base unit identifiers defined in SBML, the built-in unit identifier "substance", or the identifier of a new unit defined in the list of unit definitions in the enclosing Model object. The chosen units for "substanceUnits" must be be "dimensionless", "mole", "item", "kilogram", "gram", or units derived from these.
As noted at the beginning of this section, simply setting "initialAmount" or "initialConcentration" alone does not determine whether a species identifier represents an amount or a concentration when it appears elsewhere in an SBML model. The role of the attribute "hasOnlySubstanceUnits" is to indicate whether the units of the species, when the species identifier appears in mathematical formulas, are intended to be concentration or amount. The attribute takes on a boolean value. In SBML Level 3, the attribute has no default value and must always be set in a model; in SBML Level 2, it has a default value of false.
The units of the species are used in the following ways:
When the species' identifier appears in a MathML formula, it represents the species' quantity, and the unit of measurement associated with the quantity is as described above.
The "math" elements of AssignmentRule, InitialAssignment and EventAssignment objects referring to this species should all have the same units as the unit of measurement associated with the species quantity.
In a RateRule object that defines the rate of change of the species' quantity, the unit associated with the rule's "math" element should be equal to the unit of the species' quantity divided by the model-wide unit of time; in other words, {unit of species quantity}/{unit of time}.
The Species object class has two boolean attributes named "constant" and "boundaryCondition", used to indicate whether and how the quantity of that species can vary during a simulation. In SBML Level 2 they are optional; in SBML Level 3 they are mandatory. The following table shows how to interpret the combined values of these attributes.
constantvalue |
boundaryConditionvalue |
Can have assignment or rate rule? |
Can be reactant or product? |
Species' quantity can be changed by |
|---|---|---|---|---|
true |
true |
no | yes | (never changes) |
false |
true |
yes | yes | rules and events |
true |
false |
no | no | (never changes) |
false |
false |
yes | yes | reactions or rules (but not both at the same time), and events |
By default, when a species is a product or reactant of one or more reactions, its quantity is determined by those reactions. In SBML, it is possible to indicate that a given species' quantity is not determined by the set of reactions even when that species occurs as a product or reactant; i.e., the species is on the boundary of the reaction system, and its quantity is not determined by the reactions. The boolean attribute "boundaryCondition" can be used to indicate this. A value of false indicates that the species is part of the reaction system. In SBML Level 2, the attribute has a default value of false, while in SBML Level 3, it has no default.
The "constant" attribute indicates whether the species' quantity can be changed at all, regardless of whether by reactions, rules, or constructs other than InitialAssignment. A value of false indicates that the species' quantity can be changed. (This is also a common value because the purpose of most simulations is precisely to calculate changes in species quantities.) In SBML Level 2, the attribute has a default value of false, while in SBML Level 3, it has no default. Note that the initial quantity of a species can be set by an InitialAssignment irrespective of the value of the "constant" attribute.
In practice, a "boundaryCondition" value of true means a differential equation derived from the reaction definitions should not be generated for the species. However, the species' quantity may still be changed by AssignmentRule, RateRule, AlgebraicRule, Event, and InitialAssignment constructs if its "constant" attribute is false. Conversely, if the species' "constant" attribute is true, then its value cannot be changed by anything except InitialAssignment.
A species having "boundaryCondition"=false and "constant"=false can appear as a product and/or reactant of one or more reactions in the model. If the species is a reactant or product of a reaction, it must not also appear as the target of any AssignmentRule or RateRule object in the model. If instead the species has "boundaryCondition"= false and "constant"=true, then it cannot appear as a reactant or product, or as the target of any AssignmentRule, RateRule or EventAssignment object in the model.
Finally, it is worth clarifying that while the constant and boundaryCondition attributes restrict whether and how the species amount changes, the same is not true of a species' concentration. In SBML, the concentration of a species is a quantity that depends on the size of the compartment in which it is located. A compartment's size may change, and therefore, so can the concentration of a species even if the amount of the species remains unchanged. A species' concentration may therefore vary even if the Species object's constant attribute is set to true in a model.
In SBML Level 3, Species has an additional optional attribute, "conversionFactor", that defines a conversion factor that applies to a particular species. The value must be the identifier of a Parameter object instance defined in the model. That Parameter object must be a constant, meaning its "constant" attribute must be set to true. If a given Species object definition defines a value for its "conversionFactor" attribute, it takes precedence over any factor defined by the Model object's "conversionFactor" attribute.
The unit of measurement associated with a species' quantity can be different from the unit of extent of reactions in the model. SBML Level 3 avoids implicit unit conversions by providing an explicit way to indicate any unit conversion that might be required. The use of a conversion factor in computing the effects of reactions on a species' quantity is explained in detail in the SBML Level 3 specification document. Because the value of the "conversionFactor" attribute is the identifier of a Parameter object, and because parameters can have units attached to them, the transformation from reaction extent units to species units can be completely specified using this approach.
Note that the unit conversion factor is only applied when calculating the effect of a reaction on a species. It is not used in any rules or other SBML constructs that affect the species, and it is also not used when the value of the species is referenced in a mathematical expression.
In SBML Level 2 Versions 2–4, each species in a model may optionally be designated as belonging to a particular species type. The optional attribute "speciesType" is used to identify the species type of the chemical entities that make up the pool represented by the Species objects. The attribute's value must be the identifier of an existing SpeciesType object in the model. If the "speciesType" attribute is not present on a particular species definition, it means the pool contains chemical entities of a type unique to that pool; in effect, a virtual species type is assumed for that species, and no other species can belong to that species type. The value of "speciesType" attributes on species have no effect on the numerical interpretation of a model; simulators and other numerical analysis software may ignore "speciesType" attributes.
There can be only one species of a given species type in any given compartment of a model. More specifically, for all Species objects having a value for the "speciesType" attribute, the pair
must be unique across the set of all Species object in a model.
In versions of SBML Level 2 before Version 3, the class Species included an attribute called "spatialSizeUnits", which allowed explicitly setting the units of size for initial concentration. LibSBML retains this attribute for compatibility with older definitions of Level 2, but its use is strongly discouraged because many software tools do no properly interpret this unit declaration and it is incompatible with all SBML specifications after Level 2 Version 3.
Species are unique in SBML in that they have a kind of duality: a species identifier may stand for either substance amount (meaning, a count of the number of individual entities) or a concentration or density (meaning, amount divided by a compartment size). The previous sections explain the meaning of a species identifier when it is referenced in a mathematical formula or in rules or other SBML constructs; however, it remains to specify what happens to a species when the compartment in which it is located changes in size.
When a species definition has a "hasOnlySubstanceUnits" attribute value of false and the size of the compartment in which the species is located changes, the default in SBML is to assume that it is the concentration that must be updated to account for the size change. This follows from the principle that, all other things held constant, if a compartment simply changes in size, the size change does not in itself cause an increase or decrease in the number of entities of any species in that compartment. In a sense, the default is that the amount of a species is preserved across compartment size changes. Upon such size changes, the value of the concentration or density must be recalculated from the simple relationship concentration = amount / size if the value of the concentration is needed (for example, if the species identifier appears in a mathematical formula or is otherwise referenced in an SBML construct). There is one exception: if the species' quantity is determined by an AssignmentRule, RateRule, AlgebraicRule, or an EventAssignment and the species has a "hasOnlySubstanceUnits" attribute value of false, it means that the concentration is assigned by the rule or event; in that case, the amount must be calculated when the compartment size changes. (Events also require additional care in this situation, because an event with multiple assignments could conceivably reassign both a species quantity and a compartment size simultaneously. Please refer to the SBML specifications for the details.)
Note that the above only matters if a species has a "hasOnlySubstanceUnits" attribute value of false, meaning that the species identifier refers to a concentration wherever the identifier appears in a mathematical formula. If instead the attribute's value is true, then the identifier of the species always stands for an amount wherever it appears in a mathematical formula or is referenced by an SBML construct. In that case, there is never a question about whether an assignment or event is meant to affect the amount or concentration: it is always the amount.
A particularly confusing situation can occur when the species has "constant" attribute value of true in combination with a "hasOnlySubstanceUnits" attribute value of false. Suppose this species is given a value for "initialConcentration". Does a "constant" value of true mean that the concentration is held constant if the compartment size changes? No; it is still the amount that is kept constant across a compartment size change. The fact that the species was initialized using a concentration value is irrelevant.
| typedef class SimpleSpeciesReference SpeciesReference_t |
In C, a SpeciesReference_t is actually a synonym for the SimpleSpeciesReference base class.
| typedef class SpeciesType SpeciesType_t |
The term species type refers to reacting entities independent of location. These include simple ions (e.g., protons, calcium), simple molecules (e.g., glucose, ATP), large molecules (e.g., RNA, polysaccharides, and proteins), and others.
SBML Level 2 Versions 2–4 provide an explicit SpeciesType class of object to enable Species objects of the same type to be related together. SpeciesType is a conceptual construct; the existence of SpeciesType objects in a model has no effect on the model's numerical interpretation. Except for the requirement for uniqueness of species/species type combinations located in compartments, simulators and other numerical analysis software may ignore SpeciesType definitions and references to them in a model.
There is no mechanism in SBML Level 2 for representing hierarchies of species types. One SpeciesType object cannot be the subtype of another SpeciesType object; SBML provides no means of defining such relationships.
As with other major structures in SBML, SpeciesType has a mandatory attribute, "id", used to give the species type an identifier. The identifier must be a text string conforming to the identifer syntax permitted in SBML. SpeciesType also has an optional "name" attribute, of type string. The "id" and "name" must be used according to the guidelines described in the SBML specification (e.g., Section 3.3 in the Level 2 Version 4 specification).
SpeciesType was introduced in SBML Level 2 Version 2. It is not available in SBML Level 1 nor in Level 3.
| typedef class StoichiometryMath StoichiometryMath_t |
In SBML Level 2, product and reactant stoichiometries can be specified using either the "stoichiometry" attribute or a "stoichiometryMath" element in a SpeciesReference object. The "stoichiometry" attribute is of type double and should contain values greater than zero (0). The "stoichiometryMath" element is implemented as an element containing a MathML expression. These two are mutually exclusive; only one of "stoichiometry" or "stoichiometryMath" should be defined in a given SpeciesReference instance. When neither the attribute nor the element is present, the value of "stoichiometry" in the enclosing SpeciesReference instance defaults to 1.
For maximum interoperability, SpeciesReference's "stoichiometry" attribute should be used in preference to "stoichiometryMath" when a species' stoichiometry is a simple scalar number (integer or decimal). When the stoichiometry is a rational number, or when it is a more complicated formula, "stoichiometryMath" must be used. The MathML expression in "stoichiometryMath" may also refer to identifiers of entities in a model (except reaction identifiers). However, the only species identifiers that can be used in "stoichiometryMath" are those referenced in the enclosing Reaction's list of reactants, products and modifiers.
The "stoichiometry" attribute and the "stoichiometryMath" element, when either is used, is each interpreted as a factor applied to the reaction rate to produce the rate of change of the species identified by the "species" attribute in the enclosing SpeciesReference. This is the normal interpretation of a stoichiometry, but in SBML, one additional consideration has to be taken into account. The reaction rate, which is the result of the KineticLaw's "math" element, is always in the model's substance per time units. However, the rate of change of the species will involve the species' substance units (i.e., the units identified by the Species object's "substanceUnits" attribute), and these units may be different from the model's default substance units. If the units are different, the stoichiometry must incorporate a conversion factor for converting the model's substance units to the species' substance units. The conversion factor is assumed to be included in the scalar value of the "stoichiometry" attribute if "stoichiometry" is used. If instead "stoichiometryMath" is used, then the product of the model's "substance" units times the "stoichiometryMath" units must match the substance units of the species. Note that in either case, if the species' units and the model's default substance units are the same, the stoichiometry ends up being a dimensionless number and equivalent to the standard chemical stoichiometry found in textbooks. Examples and more explanations of this are given in the SBML specification.
The following is a simple example of a species reference for species "X0", with stoichiometry 2, in a list of reactants within a reaction having the identifier "J1":
<model>
...
<listOfReactions>
<reaction id="J1">
<listOfReactants>
<speciesReference species="X0" stoichiometry="2">
</listOfReactants>
...
</reaction>
...
</listOfReactions>
...
</model>
The following is a more complex example of a species reference for species "X0", with a stoichiometry formula consisting of a rational number:
<model>
...
<listOfReactions>
<reaction id="J1">
<listOfReactants>
<speciesReference species="X0">
<stoichiometryMath>
<math xmlns="http://www.w3.org/1998/Math/MathML">
<cn type="rational"> 3 <sep/> 2 </cn>
</math>
</stoichiometryMath>
</speciesReference>
</listOfReactants>
...
</reaction>
...
</listOfReactions>
...
</model>
Additional discussions of stoichiometries and implications for species and reactions are included in the documentation of SpeciesReference class.
The StoichiometryMath construct is not defined in SBML Level 3. Instead, Level 3 defines the identifier of SpeciesReference objects as a stand-in for the stoichiometry of the reactant or product being referenced, and allows that identifier to be used elsewhere in SBML models, including (for example) InitialAssignment objects. This makes it possible to achieve the same effect as StoichiometryMath, but with other SBML objects. For instance, to produce a stoichiometry value that is a rational number, a model can use InitialAssignment to assign the identifier of a SpeciesReference object to a MathML expression evaluating to a rational number. This is analogous to the same way that, in Level 2, the model would use StoichiometryMath with a MathML expression evaluating to a rational number.
In SBML Level 2, the stoichiometry of a reactant or product is a combination of both a biochemical stoichiometry (meaning, the standard stoichiometry of a species in a reaction) and any necessary unit conversion factors. The introduction of an explicit attribute on the Species object for a conversion factor allows Level 3 to avoid having to overload the meaning of stoichiometry. In Level 3, the stoichiometry given by a SpeciesReference object in a reaction is a "proper" biochemical stoichiometry, meaning a dimensionless number free of unit conversions.
An Event object defines when the event can occur, the variables that are affected by the event, and how the variables are affected. The Trigger construct in SBML is used to define a mathematical expression that determines when an Event is triggered.
A Trigger object in SBML Level 2 and Level 3 contains one subelement named "math" containing a MathML expression. The expression is evaluated as a value of type boolean. The exact moment at which the expression evaluates to true is the time point when the Event is triggered. In SBML Level 3, Trigger has additional attributes that must be assigned values; they are discussed in a separate section below.
In SBML Level 2 and SBML Level 3 Version 1, the "math" subelement is required, and it must evaluate to a boolean expression. In SBML Level 3 Version 2, those restrictions are relaxed: the "math" element is optional, and numeric values are allowed in Boolean contexts (a '0' is interpreted as false, and all other values are interpreted as true). If a Trigger with no "math" is present in an Event, that Event will never trigger, unless that missing information is included in an SBML Level 3 package.
An event only triggers when its Trigger expression makes the transition in value from false to true. The event will also trigger at any subsequent time points when the trigger makes this transition; in other words, an event can be triggered multiple times during a simulation if its trigger condition makes the transition from false to true more than once. In SBML Level 3, the behavior at the very start of simulation (i.e., at t = 0, where t stands for time) is determined in part by the boolean flag "initialValue". This and other additional features introduced in SBML Level 3 are discussed further below.
SBML Level 3 Version 1 introduces two required attributes on the Trigger object: "persistent" and "initialValue". The rest of this introduction describes these two attributes.
In the interval between when an Event object triggers (i.e., its Trigger object expression transitions in value from false to true) and when its assignments are to be executed, conditions in the model may change such that the trigger expression transitions back from true to false. Should the event's assignments still be made if this happens? Answering this question is the purpose of the "persistent" attribute on Trigger.
If the boolean attribute "persistent" has a value of true, then once the event is triggered, all of its assignments are always performed when the time of execution is reached. The name persistent is meant to evoke the idea that the trigger expression does not have to be re-checked after it triggers if "persistent"=true. Conversely, if the attribute value is false, then the trigger expression is not assumed to persist: if the expression transitions in value back to false at any time between when the event triggered and when it is to be executed, the event is no longer considered to have triggered and its assignments are not executed. (If the trigger expression transitions once more to true after that point, then the event is triggered, but this then constitutes a whole new event trigger-and-execute sequence.)
The "persistent" attribute can be especially useful when Event objects contain Delay objects, but it is relevant even in a model without delays if the model contains two or more events. As explained in the introduction to this section, the operation of all events in SBML (delayed or not) is conceptually divided into two phases, triggering and execution; however, unless events have priorities associated with them, SBML does not mandate a particular ordering of event execution in the case of simultaneous events. Models with multiple events can lead to situations where the execution of one event affects another event's trigger expression value. If that other event has "persistent"=false, and its trigger expression evaluates to false before it is to be executed, the event must not be executed after all.
As mentioned above, an event triggers when the mathematical expression in its Trigger object transitions in value from false to true. An unanswered question concerns what happens at the start of a simulation: can event triggers make this transition at t = 0, where t stands for time?
In order to determine whether an event may trigger at t = 0, it is necessary to know what value the Trigger object's "math" expression had immediately prior to t = 0. This starting value of the trigger expression is determined by the value of the boolean attribute "initialValue". A value of true means the trigger expression is taken to have the value true immediately prior to t = 0. In that case, the trigger cannot transition in value from false to true at the moment simulation begins (because it has the value true both before and after t = 0), and can only make the transition from false to true sometime after t = 0. (To do that, it would also first have to transition to false before it could make the transition from false back to true.) Conversely, if "initialValue"=false, then the trigger expression is assumed to start with the value false, and therefore may trigger at t = 0 if the expression evaluates to true at that moment.
The SBML unit definition facility uses two classes of objects, UnitDefinition and Unit. The approach to defining units in SBML is compositional; for example, meter second –2 is constructed by combining a Unit object representing meter with another Unit object representing second –2. The combination is wrapped inside a UnitDefinition, which provides for assigning an identifier and optional name to the combination. The identifier can then be referenced from elsewhere in a model. Thus, the UnitDefinition class is the container, and Unit instances are placed inside UnitDefinition instances.
A Unit has four attributes named "kind", "exponent", "scale" and "multiplier". It represents a (possibly transformed) reference to a base unit. The attribute "kind" on Unit indicates the chosen base unit. Its value must be one of the text strings listed below; this list corresponds to SBML Level 3:
| ampere | farad | joule | lux | radian | volt |
| avogadro | gram | katal | metre | second | watt |
| becquerel | gray | kelvin | mole | siemens | weber |
| candela | henry | kilogram | newton | sievert | |
| coulomb | hertz | litre | ohm | steradian | |
| dimensionless | item | lumen | pascal | tesla |
A few small differences exist between the Level 3 list of base units and the list defined in other Level/Version combinations of SBML. Specifically, Levels of SBML before Level 3 do not define avogadro; conversely, Level 2 Version 1 defines Celsius, and Level 1 defines celsius, meter, and liter, none of which are available in Level 3. In libSBML, each of the predefined base unit names is represented by an enumeration value in UnitKind_t, discussed in a separate section below.
The attribute named "exponent" on Unit represents an exponent on the unit. In SBML Level 2, the attribute is optional and has a default value of 1 (one); in SBML Level 3, the attribute is mandatory and there is no default value. A Unit also has an attribute called "scale"; its value must be an integer exponent for a power-of-ten multiplier used to set the scale of the unit. For example, a unit having a "kind" value of gram and a "scale" value of -3 signifies 10 –3 \(\times\) gram, or milligrams. In SBML Level 2, the attribute is optional and has a default value of 0 (zero), because 10 0 = 1; in SBML Level 3, the attribute is mandatory and has no default value. Lastly, the attribute named "multiplier" can be used to multiply the unit by a real-numbered factor; this enables the definition of units that are not power-of-ten multiples of SI units. For instance, a multiplier of 0.3048 could be used to define foot as a measure of length in terms of a metre. The "multiplier" attribute is optional in SBML Level 2, where it has a default value of 1 (one); in SBML Level 3, the attribute is mandatory and has no default value.
As discussed above, SBML defines a set of base units which serves as the starting point for new unit definitions. This set of base units consists of the SI units and a small number of additional convenience units.
Until SBML Level 2 Version 3, there existed a data type in the SBML specifications called UnitKind, enumerating the possible SBML base units. Although SBML Level 2 Version 3 removed this type from the language specification, libSBML maintains the corresponding enumeration type UnitKind_t as a convenience and as a way to provide backward compatibility to previous SBML Level/Version specifications. (The removal in SBML Level 2 Version 3 of the enumeration UnitKind was also accompanied by the redefinition of the data type UnitSId to include the previous UnitKind values as reserved symbols in the UnitSId space. This change has no net effect on permissible models, their representation or their syntax. The purpose of the change in the SBML specification was simply to clean up an inconsistency about the contexts in which these values were usable.)
As a consequence of the fact that libSBML supports models in all Levels and Versions of SBML, libSBML's set of UNIT_KIND_ values is a union of all the possible base unit names defined in the different SBML specifications. However, not every base unit is allowed in every Level+Version combination of SBML. Note in particular the following exceptions:
The alternate spelling "meter" is included in addition to the official SI spelling "metre". This spelling is only permitted in SBML Level 1 models.
The alternate spelling "liter" is included in addition to the official SI spelling "litre". This spelling is only permitted in SBML Level 1 models.
The unit "Celsius" is included because of its presence in specifications of SBML prior to SBML Level 2 Version 2.
avogadro was introduced in SBML Level 3, and is only permitted for use in SBML Level 3 models. The table below lists the symbols defined in the UnitKind_t enumeration, and their meanings.
| Enumerator | Meaning |
|---|---|
UNIT_KIND_AMPERE | The ampere unit. |
UNIT_KIND_AVOGADRO | The unit
dimensionless multiplied by the numerical value of Avogadro's
constant. (Only usable in SBML Level 3 models.) |
UNIT_KIND_BECQUEREL | The becquerel unit. |
UNIT_KIND_CANDELA | The candela unit. |
UNIT_KIND_CELSIUS | The Celsius unit. (Only usable in SBML Level 1 and SBML Level 2 Version 1 models.) |
UNIT_KIND_COULOMB | The coulomb unit. |
UNIT_KIND_DIMENSIONLESS | A pseudo-unit indicating a dimensionless quantity. |
UNIT_KIND_FARAD | The farad unit. |
UNIT_KIND_GRAM | The gram unit. |
UNIT_KIND_GRAY | The gray unit. |
UNIT_KIND_HENRY | The henry unit. |
UNIT_KIND_HERTZ | The hertz unit. |
UNIT_KIND_ITEM | A pseudo-unit representing a single "thing". |
UNIT_KIND_JOULE | The joule unit. |
UNIT_KIND_KATAL | The katal unit. |
UNIT_KIND_KELVIN | The kelvin unit. |
UNIT_KIND_KILOGRAM | The kilogram unit. |
UNIT_KIND_LITER | Alternate spelling of litre. |
UNIT_KIND_LITRE | The litre unit. |
UNIT_KIND_LUMEN | The lumen unit. |
UNIT_KIND_LUX | The lux unit. |
UNIT_KIND_METER | Alternate spelling of metre. |
UNIT_KIND_METRE | The metre unit. |
UNIT_KIND_MOLE | The mole unit. |
UNIT_KIND_NEWTON | The newton unit. |
UNIT_KIND_OHM | The ohm unit. |
UNIT_KIND_PASCAL | The pascal unit. |
UNIT_KIND_RADIAN | The radian unit. |
UNIT_KIND_SECOND | The second unit. |
UNIT_KIND_SIEMENS | The siemens unit. |
UNIT_KIND_SIEVERT | The sievert unit. |
UNIT_KIND_STERADIAN | The steradian unit. |
UNIT_KIND_TESLA | The tesla unit. |
UNIT_KIND_VOLT | The volt unit. |
UNIT_KIND_WATT | The watt unit. |
UNIT_KIND_WEBER | The weber unit. |
UNIT_KIND_INVALID | Marker used by libSBML to indicate an invalid or unset unit. |
| typedef class UnitDefinition UnitDefinition_t |
Units of measurement may be supplied in a number of contexts in an SBML model. The SBML unit definition facility uses two classes of objects, UnitDefinition and Unit. The approach to defining units in SBML is compositional; for example, meter second –2 is constructed by combining a Unit object representing meter with another Unit object representing second –2. The combination is wrapped inside a UnitDefinition, which provides for assigning an identifier and optional name to the combination. The identifier can then be referenced from elsewhere in a model. Thus, the UnitDefinition class is the container, and Unit instances are placed inside UnitDefinition instances.
Two points are worth discussing in the context of SBML units. First, unit declarations in SBML models are optional. The consequence of this is that a model must be numerically self-consistent independently of unit declarations, for the benefit of software tools that cannot interpret or manipulate units. Unit declarations in SBML are thus more akin to a type of annotation; they can indicate intentions, and can be used by model readers for checking the consistency of the model, labeling simulation output, etc., but any transformations of values implied by different units must be incorporated explicitly into a model.
Second, the vast majority of situations that require new SBML unit definitions involve simple multiplicative combinations of base units and factors. An example is moles per litre per second. What distinguishes these sorts of unit definitions from more complex ones is that they may be expressed without the use of an additive offset from a zero point. The use of offsets complicates all unit definition systems, yet in the domain of SBML, the real-life cases requiring offsets are few (and in fact, to the best of our knowledge, only involve temperature). Consequently, the SBML unit system has been consciously designed to simplify implementation of unit support for the most common cases in systems biology. The cost of this simplification is to require units with offsets to be handled explicitly by the modeler.
UnitDefinition has two attributes and one subelement. The two attributes are "id" and "name", and the subelement is ListOfUnits.
The required attribute "id" and optional attribute "name" are both strings. The "id" attribute is used to give the defined unit a unique identifier by which other parts of an SBML model definition can refer to it. The "name" attribute is intended to be used for giving the unit definition an optional human-readable name. Please see the next section for information about the values permitted for "id".
A UnitDefinition may contain exactly one ListOfUnits, and this list may contain one or more Unit definitions; see the definitions of these other object classes for more information about them. In SBML Level 2 and SBML Level 3 Version 1, if the ListOfUnits was present, it must have one or more Unit definitions. In SBML Level 3 Version 2, this restriction was relaxed, and a ListOfUnits was allowed to be empty. In either case, if a UnitDefinition had no child Unit elements, the unit was considered to be undefined.
The following example illustrates a complete unit definition (when written in XML) when all the pieces are combined together. This defines "mmls" to be millimoles per litre per second.
<listOfUnitDefinitions>
<unitDefinition id="mmls">
<listOfUnits>
<unit kind="mole" scale="-3"/>
<unit kind="litre" exponent="-1"/>
<unit kind="second" exponent="-1"/>
</listOfUnits>
</unitDefinition>
</listOfUnitDefinitions>
The attribute "id" in UnitDefinition cannot be given simply any value, and the precise details of the values permitted differ slightly between Levels of SBML:
The "id" of a UnitDefinition must not contain a value from the list of SBML's predefined base unit names (i.e., the strings gram, litre, etc.). In SBML Level 3, this list consists of the following:
| ampere | farad | joule | lux | radian | volt |
| avogadro | gram | katal | metre | second | watt |
| becquerel | gray | kelvin | mole | siemens | weber |
| candela | henry | kilogram | newton | sievert | |
| coulomb | hertz | litre | ohm | steradian | |
| dimensionless | item | lumen | pascal | tesla |
This list of predefined base units is nearly identical in SBML Level 2 Version 4, the exception being that Level 2 does not define avogadro. SBML Level 2 Version 1 (and only this Level+Version combination) provides an additional predefined unit name, Celsius, not available in Level 3. Finally, SBML Level 1 Versions 2–3 provide two more additional predefined unit names, meter and liter. This is explained in somewhat greater detail in the description of the Unit class.
substance, volume, area, length, and time. Using one of these values for the attribute "id" of a UnitDefinition has the effect of redefining the model-wide default units for the corresponding quantities. The list of special unit names in SBML Level 2 is given in the table below: | Identifier | Possible scalable units | Default units |
|---|---|---|
substance | mole, item, gram, kilogram, dimensionless | mole |
volume | litre, cubic metre, dimensionless | litre |
area | square metre, dimensionless | square metre |
length | metre, dimensionless | metre |
time | second, dimensionless | second |
Also, SBML Level 2 imposes two limitations on redefining the predefined unit substance, volume, area, length, and time: (1) The UnitDefinition of a predefined SBML unit can only contain a single Unit object within it. (2) The value of the "kind" attribute in a Unit instance must be drawn from one of the values in the second column of the table above.
The special unit names substance, volume, area, length, and time are not defined by SBML Level 3, which uses a different approach to setting model-wide inherited units.
The vast majority of modeling situations requiring new SBML unit definitions involve simple multiplicative combinations of base units and factors. An example of this might be moles per litre per second. What distinguishes these sorts of simpler unit definitions from more complex ones is that they may be expressed without the use of an additive offset from a zero point. The use of offsets complicates all unit definition systems, yet in the domain of SBML the real-life cases requiring offsets are few (and in fact, to the best of our knowledge, only involve temperature). Consequently, the SBML unit system has been consciously designed in a way that attempts to simplify implementation of unit support for the most common cases in systems biology.
As of SBML Level 2 Version 2, Unit no longer has the attribute called "offset" introduced in SBML Level 2 Version 1. It turned out that the general case involving units with offsets was incorrectly defined, and few (if any) developers even attempted to support offset-based units in their software. In the development of Level 2 Version 2, a consensus among SBML developers emerged that a fully generalized unit scheme is so confusing and complicated that it actually impedes interoperability. SBML Level 2 Version 2, Version 3 and Version 4 acknowledge this reality by reducing and simplifying the unit system, specifically by removing the "offset" attribute on Unit and Celsius as a pre-defined unit.
The following guidelines suggest methods for handling units that do require the use of zero offsets for their definitions:
Handling Celsius. A model in which certain quantities are temperatures measured in degrees Celsius can be converted straightforwardly to a model in which those temperatures are in kelvin. A software tool could do this by performing a straightforward substitution using the following relationship: T kelvin = TCelsius + 273.15. In every mathematical formula of the model where a quantity (call it x) in degrees Celsius appears, replace x with xk+ 273.15, where xk is now in kelvin. An alternative approach would be to use a FunctionDefinition object to define a function encapsulating this relationship above and then using that in the rest of the model as needed. Since Celsius is a commonly-used unit, software tools could help users by providing users with the ability to express temperatures in Celsius in the tools' interfaces, and making substitutions automatically when writing out the SBML.
Other units requiring offsets. One approach to handling other kinds of units is to use a FunctionDefinition to define a function encapsulating the necessary mathematical relationship, then substituting a call to this function wherever the original quantity appeared in the model. For example, here is a possible definition for converting Fahrenheit to Celsius degrees:
<functionDefinition id="Fahrenheit_to_kelvin">
<math xmlns="http://www.w3.org/1998/Math/MathML">
<lambda>
<bvar><ci> temp_in_fahrenheit </ci></bvar>
<apply>
<divide/>
<apply>
<plus/>
<ci> temp_in_fahrenheit </ci>
<cn> 459.67 </cn>
</apply>
<cn> 1.8 </cn>
</apply>
</lambda>
</math>
</functionDefinition>
An alternative approach not requiring the use of function definitions is to use an AssignmentRule for each variable in Fahrenheit units. The AssignmentRule could compute the conversion from Fahrenheit to (say) kelvin, assign its value to a variable (in Kelvin units), and then that variable could be used elsewhere in the model.
Please consult the SBML specifications for more information about this and other issues involving units.
| typedef class XMLAttributes XMLAttributes_t |
This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.
In libSBML's XML interface layer, attributes on an element are stored as a list of values kept in an XMLAttributes object. XMLAttributes has methods for adding and removing individual attributes as well as performing other actions on the list of attributes. Classes in libSBML that represent nodes in an XML document (i.e., XMLNode and its parent class, XMLToken) use XMLAttributes objects to manage attributes on XML elements.
Attributes on an XML element can be written in one of two forms:
name="value" prefix:name="value"An attribute in XML must always have a value, and the value must always be a quoted string; i.e., it is always name="value" and not name=value. An empty value is represented simply as an empty string; i.e., name="".
In cases when a prefix is provided with an attribute name, general XML validity rules require that the prefix is an XML namespace prefix that has been declared somewhere else (possibly as an another attribute on the same element). However, the XMLAttributes class does not test for the proper existence or declaration of XML namespaces—callers must arrange to do this themselves in some other way. This class only provides facilities for tracking and manipulating attributes and their prefix/URI/name/value components.
| typedef class XMLError XMLError_t |
This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.
LibSBML can be configured to use any of a number of XML parsers; at the time of this writing, libSBML supports Xerces versions 2.4 through 3.1, Expat version 1.95.x and higher, and libxml2 version 2.6.16 and higher. These parsers each report different status codes for the various exceptions that can occur during XML processing. The XMLError object class abstracts away from the particular diagnostics reported by the different parsers and presents a single uniform interface and set of status codes, along with operations for manipulating the error objects.
When the libSBML XML parser layer encounters an error in the XML content being processed, or when there is something else wrong (such as an out-of-memory condition), the problems are reported as XMLError objects. Each XMLError object instance has an identification number that identifies the nature of the problem. This error identifier will be up to five digits long and drawn from the enumeration XMLErrorCode_t. Applications can use the error identifiers as a means of recognizing the error encountered and changing their behavior if desired.
Integer error codes are useful for software, but not so much for telling humans what happened. For this reason, XMLError also provides two text messages describing the nature of the error. These messages are accessible by means of the methods XMLError::getShortMessage() and XMLError::getMessage(). The method XMLError::getShortMessage() returns a very brief synopsis of the warning or error condition, whereas XMLError::getMessage() returns a longer explanation. These text strings are suitable for displaying to human users.
Each XMLError object also contains a category code; its value may be retrieved using the method XMLError::getCategory(). Category values are drawn from the enumeration XMLErrorCategory_t described below. Categories are used by libSBML to provide more information to calling programs about the nature of a given error.
In addition to category codes, each XMLError object also has a severity code; its value may be retrieved using the method XMLError::getSeverity(). Severity code values are drawn from the enumeration XMLErrorSeverity_t, described below. Severity levels range from informational (LIBSBML_SEV_INFO) to fatal errors (LIBSBML_SEV_FATAL).
Finally, XMLError objects record the line and column near where the problem occurred in the XML content. The values can be retrieved using the methods XMLError::getLine() and XMLError::getColumn(). We say "near
where the problem occurred", because many factors affect how accurate the line/column information ultimately is. For example, sometimes, the underlying XML parsers can only report such information for the parent XML element where an error occurs, and not for the specific point where the problem occurs. In other situations, some parsers report invalid line and/or column numbers altogether. If this occurs, libSBML sets the line and/or column number in the XMLError object to either 0 or the value of the maximum unsigned long integer representable on the platform where libSBML is running. The probability that a true line or column number in an SBML model would equal this value is vanishingly small; thus, if an application encounters these values in an XMLError object, it can assume no valid line/column number could be provided by libSBML in that situation.
This is an enumeration of all the error and warning codes returned by the XML layer in libSBML. Each code is an integer with a 4-digit value less than 10000. The following table lists each possible value and a brief description of its meaning.
| Enumerator | Meaning | Category | Severity |
|---|---|---|---|
| XMLUnknownError | Unrecognized error encountered internally | INTERNAL | FATAL |
| XMLOutOfMemory | Out of memory | SYSTEM | FATAL |
| XMLFileUnreadable | File unreadable | SYSTEM | ERROR |
| XMLFileUnwritable | File unwritable | SYSTEM | ERROR |
| XMLFileOperationError | Error encountered while attempting file operation | SYSTEM | ERROR |
| XMLNetworkAccessError | Network access error | SYSTEM | ERROR |
| InternalXMLParserError | Internal XML parser state error | INTERNAL | FATAL |
| UnrecognizedXMLParserCode | XML parser returned an unrecognized error code | INTERNAL | FATAL |
| XMLTranscoderError | Character transcoder error | INTERNAL | FATAL |
| MissingXMLDecl | Missing XML declaration at beginning of XML input | XML | ERROR |
| MissingXMLEncoding | Missing encoding attribute in XML declaration | XML | ERROR |
| BadXMLDecl | Invalid or unrecognized XML declaration or XML encoding | XML | ERROR |
| BadXMLDOCTYPE | Invalid, malformed or unrecognized XML DOCTYPE declaration | XML | ERROR |
| InvalidCharInXML | Invalid character in XML content | XML | ERROR |
| BadlyFormedXML | XML content is not well-formed | XML | ERROR |
| UnclosedXMLToken | Unclosed XML token | XML | ERROR |
| InvalidXMLConstruct | XML construct is invalid or not permitted | XML | ERROR |
| XMLTagMismatch | Element tag mismatch or missing tag | XML | ERROR |
| DuplicateXMLAttribute | Duplicate XML attribute | XML | ERROR |
| UndefinedXMLEntity | Undefined XML entity | XML | ERROR |
| BadProcessingInstruction | Invalid, malformed or unrecognized XML processing instruction | XML | ERROR |
| BadXMLPrefix | Invalid or undefined XML namespace prefix | XML | ERROR |
| BadXMLPrefixValue | Invalid XML namespace prefix value | XML | ERROR |
| MissingXMLRequiredAttribute | Missing a required XML attribute | XML | ERROR |
| XMLAttributeTypeMismatch | Data type mismatch for the value of an attribute | XML | ERROR |
| XMLBadUTF8Content | Invalid UTF8 content | XML | ERROR |
| MissingXMLAttributeValue | Missing or improperly formed attribute value | XML | ERROR |
| BadXMLAttributeValue | Invalid or unrecognizable attribute value | XML | ERROR |
| BadXMLAttribute | Invalid, unrecognized or malformed attribute | XML | ERROR |
| UnrecognizedXMLElement | Element either not recognized or not permitted | XML | ERROR |
| BadXMLComment | Badly formed XML comment | XML | ERROR |
| BadXMLDeclLocation | XML declaration not permitted in this location | XML | ERROR |
| XMLUnexpectedEOF | Reached end of input unexpectedly | XML | ERROR |
| BadXMLIDValue | Value is invalid for XML ID, or has already been used | XML | ERROR |
| BadXMLIDRef | XML ID value was never declared | XML | ERROR |
| UninterpretableXMLContent | Unable to interpret content | XML | ERROR |
| BadXMLDocumentStructure | Bad XML document structure | XML | ERROR |
| InvalidAfterXMLContent | Encountered invalid content after expected content | XML | ERROR |
| XMLExpectedQuotedString | Expected to find a quoted string | XML | ERROR |
| XMLEmptyValueNotPermitted | An empty value is not permitted in this context | XML | ERROR |
| XMLBadNumber | Invalid or unrecognized number | XML | ERROR |
| XMLBadColon | Colon characters are invalid in this context | XML | ERROR |
| MissingXMLElements | One or more expected elements are missing | XML | ERROR |
| XMLContentEmpty | Main XML content is empty | XML | ERROR |
As discussed above, each XMLError object contains a value for a category identifier, describing the type of issue that the XMLError object represents. The category can be retrieved from an XMLError object using the method XMLError::getCategory(). The value is chosen from the enumeration of category codes XMLErrorCategory_t. The following table lists each possible value and a brief description of its meaning.
| Enumerator | Meaning |
|---|---|
| LIBSBML_CAT_INTERNAL | A problem involving the libSBML software itself or the underlying XML parser. This almost certainly indicates a software defect (i.e., bug) in libSBML. Please report instances of this to the libSBML developers. |
| LIBSBML_CAT_SYSTEM | A problem reported by the operating system, such as an inability to read or write a file. This indicates something that is not a program error but is outside of the control of libSBML. |
| LIBSBML_CAT_XML | A problem in the XML content itself. This usually arises from malformed XML or the use of constructs not permitted in SBML. |
As described above, each XMLError object contains a value for a severity code, describing how critical is the issue that the XMLError object represents. The severity can be retrieved from an XMLError object using the method XMLError::getSeverity(). The value is chosen from the enumeration of category codes XMLErrorSeverity_t. The following table lists each possible value and a brief description of its meaning.
| Enumerator | Meaning |
|---|---|
| LIBSBML_SEV_INFO | The error is actually informational and not necessarily a serious problem. |
| LIBSBML_SEV_WARNING | The error object represents a problem that is not serious enough to necessarily stop the problem, but applications should take note of the problem and evaluate what its implications may be. |
| LIBSBML_SEV_ERROR | The error object represents a serious error. The application may continue running but it is unlikely to be able to continue processing the same XML file or data stream. |
| LIBSBML_SEV_FATAL | A serious error occurred, such as an out-of-memory condition, and the software should terminate immediately. |
| typedef class XMLErrorLog XMLErrorLog_t |
This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.
The error log is a list. The XML layer of libSBML maintains an error log associated with a given XML document or data stream. When an operation results in an error, or when there is something wrong with the XML content, the problem is reported as an XMLError object stored in the XMLErrorLog list. Potential problems range from low-level issues (such as the inability to open a file) to XML syntax errors (such as mismatched tags or other problems).
A typical approach for using this error log is to first use getNumErrors() to inquire how many XMLError object instances it contains, and then to iterate over the list of objects one at a time using getError(unsigned int n) const. Indexing in the list begins at 0.
In normal circumstances, programs using libSBML will actually obtain an SBMLErrorLog rather than an XMLErrorLog. The former is subclassed from XMLErrorLog and simply wraps commands for working with SBMLError objects rather than the low-level XMLError objects. Classes such as SBMLDocument use the higher-level SBMLErrorLog.
| typedef class XMLNamespaces XMLNamespaces_t |
This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.
This class serves to organize functionality for tracking XML namespaces in a document or data stream. The namespace declarations are stored as a list of pairs of XML namespace URIs and prefix strings. These correspond to the parts of a namespace declaration on an XML element. For example, in the following XML fragment,
<annotation>
<mysim:nodecolors xmlns:mysim="urn:lsid:mysim.org"
mysim:bgcolor="green" mysim:fgcolor="white"/>
</annotation>
there is one namespace declaration. Its URI is urn:lsid:mysim.org and its prefix is mysim. This pair could be stored as one item in an XMLNamespaces list.
XMLNamespaces provides various methods for manipulating the list of prefix-URI pairs. Individual namespaces stored in a given XMLNamespace object instance can be retrieved based on their index using XMLNamespaces::getPrefix(int index), or by their characteristics such as their URI or position in the list.
LibSBML implements an XML abstraction layer. This layer presents a uniform XML interface to calling programs regardless of which underlying XML parser libSBML has actually been configured to use. The basic data object in the XML abstraction is a node, represented by XMLNode.
An XMLNode can contain any number of children. Each child is another XMLNode, thereby forming a tree. The methods XMLNode::getNumChildren() and XMLNode::getChild() can be used to access the tree structure starting from a given node.
Each XMLNode is subclassed from XMLToken, and thus has the same methods available as XMLToken. These methods include XMLToken::getNamespaces(), XMLToken::getPrefix(), XMLToken::getName(), XMLToken::getURI(), and XMLToken::getAttributes().
LibSBML provides the following utility functions for converting an XML string (e.g., <annotation>...</annotation>) to/from an XMLNode object.
The returned XMLNode object by XMLNode::convertStringToXMLNode() is a dummy root (container) XMLNode if the given XML string has two or more top-level elements (e.g., "<p>...</p><p>...</p>"). In the dummy root node, each top-level element in the given XML string is contained as a child XMLNode. XMLToken::isEOF() can be used to identify if the returned XMLNode object is a dummy node or not. Here is an example:
| typedef class XMLToken XMLToken_t |
This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.
The libSBML XML parser interface can read an XML file or data stream and convert the contents into tokens. The tokens represent items in the XML stream, either XML elements (start or end tags) or text that appears as content inside an element. The XMLToken class is libSBML's low-level representation of these entities.
Each XMLToken has the following information associated with it:
<mytag>, the name is "mytag"), but this name may be qualified with a namespace (e.g., it may appear as <someNamespace:mytag> in the input). An XMLToken stores the name of a token, along with any namespace qualification present, through the use of an XMLTriple object. This object stores the bare name of the element, its XML namespace prefix (if any), and the XML namespace with which that prefix is associated. The XMLToken class serves as base class for XMLNode. XML lends itself to a tree-structured representation, and in libSBML, the nodes in an XML document tree are XMLNode objects. Most higher-level libSBML classes and methods that offer XML-level functionality (such as the methods on SBase for interacting with annotations) work with XMLNode objects rather than XMLToken objects directly.
| typedef class XMLTriple XMLTriple_t |
This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.
A "triple" in the libSBML XML layer encapsulates the notion of qualified name, meaning an element name or an attribute name with an optional namespace qualifier. Triples by themselves are not entities in an XML stream—they are not, for example, elements or attributes; rather, XMLTriple is used in libSBML to construct these other kinds of objects.
An XMLTriple instance carries up to three data items:
mysim and it appears on both the element someelement and the attribute attribA. When both the element and the attribute are stored as XMLTriple objects, their prefix is mysim. <mysim:someelement mysim:attribA="value" />
XMLTriple objects are the lowest-level data item in the XML layer of libSBML. Other objects such as XMLToken make use of XMLTriple objects.