### 4.6.8 Additional considerations for interpreting the numerical value of a species

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 the attribute value `hasOnlySubstanceUnits="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 the attribute value `hasOnlySubstanceUnits="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. Section 4.12.5 on p. 86 describes the handling of species in event assignments.)

Note that the above only matters if a species has the attribute value `hasOnlySubstanceUnits="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 attribute value `constant="true"` in combination with attribute value `hasOnlySubstanceUnits="false"`. Suppose this species is given a value for `initialConcentration`. Does `constant="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.

### 4.6.9 Example

The following example shows a species definition within an abbreviated SBML model definition. The example shows that species are listed under the heading `listOfSpecies` in the model:

```xml
<model ...>
  ...
  <listOfSpecies>
    <species id="Glucose" compartment="cell" initialConcentration="4"
              hasOnlySubstanceUnits="false" boundaryCondition="false" constant="false"/>
  </listOfSpecies>
  ...
</model>
```

## 4.7 Parameters

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. The definition of **Parameter** is shown in Figure 15 on the following page.

The use of the term *parameter* in SBML sometimes leads to confusion among readers who have a particular notion of what something called “parameter” should be. It has been the source of heated debate, but despite this, no one has yet found an adequate replacement term that does not have different connotations to different
<figure><img src="image_18.png" /><figcaption>**Figure 15:** The definition of class *Parameter*. A sequence of zero or more instances of *Parameter* objects can be located in an instance of * ListOfParameters* in *Model*, as shown in Figure 10 on p. 37.</figcaption></figure>

people and hence leads to confusion among *some* subset of users. Perhaps it would have been better to have two constructs, one called “constants” and the other called “variables”. The current approach in SBML is simply more parsimonious, using a single **Parameter** construct with the **boolean** flag **constant** to indicate which flavor the parameter is. In any case, readers are implored to look past their particular definition of a “parameter” and simply view SBML’s **Parameter** as a single mechanism for defining both constants and (additional) variables in a model. (We write *additional* because the species in a model are usually considered to be the central variables.) After all, software tools are not required to expose to users the actual names of particular SBML constructs, and thus tools can present to their users whatever terms their designers feel best matches their target audience.

### 4.7.1 The *id* attribute

**Parameter** inherits the *id* attribute from *SBase*, but on **Parameter** it is defined as being required instead of optional. The attribute otherwise behaves as described in Section 3.3 on p. 18.

A parameter's identifier (its *id* attribute value) may be used in a model's mathematical expressions. The identifier stands for the value of the parameter, with a unit of measurement as described in Section 4.7.3 on the following page. It may be the target of **InitialAssignment**, **EventAssignment**, or **Rule** objects elsewhere in a model, to set or redefine the value of the parameter.

A **Parameter** *id* will most often represent a **double** value, but the identifier may be used in other contexts. For example, it is possible to have a **Parameter** that is only assigned Boolean values and only used in Boolean contexts. The units of such a **Parameter** should be **dimensionless**. In such cases, it would also be appropriate to set the **Parameter**'s **sboTerm** attribute to the value for “logical parameter” (“SBO:0000602”).

### 4.7.2 The *value* attribute

The optional attribute **value** determines the value (of type **double**) assigned to the identifier. A missing **value** implies that the **value** either is unknown, or to be obtained from an external source, or determined by an initial assignment (Section 4.8 on p. 56) or other SBML construct elsewhere in the model.

A parameter's value is set by its **value** attribute exactly once. If the parameter's **constant** attribute (Section 4.7.4) has the value “true”, then the value is fixed and cannot be changed except by an **InitialAssignment**. These two methods of setting the parameter's value differ in that the **value** attribute can only be used to set it to a literal floating-point number, whereas **InitialAssignment** 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 parameter's **constant** attribute has the value “false”, the parameter's value may be overridden by an **InitialAssignment** or changed by **AssignmentRule** or **AlgebraicRule**, and in addition, for simulation time *t* > 0, it may also be changed by a **RateRule** or **Event**. (However, some of these constructs are mutually exclusive; see Section 4.9 and Section 4.12.) It is not an error to define **value** on a parameter and also redefine the value using an **InitialAssignment**, but the **value** in that case is ignored. Section 3.4.8 on p. 28 provides additional information about the semantics of assignments, rules and values for simulation time *t* ≤ 0.
### 4.7.3 The units attribute

The unit of measurement associated with the value of the parameter can be specified using the optional attribute `units`. The attribute's value must have the data type `UnitIdRef` (Section 3.1.10 on p. 13). 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`).

The unit of measurement associated with a parameter's value is used in the following ways:

* When the identifier of the parameter appears as a numerical quantity in a mathematical formula expressed in MathML (discussed in Section 3.4.3 on p. 23), it represents the value of the parameter, and the unit associated with the value is set by the parameter's `units` attribute.

* The `math` elements of `AssignmentRule`, `InitialAssignment` and `EventAssignment` objects setting the value of the parameter should all have the same units as the `units` attribute value of the parameter.

* In a `RateRule` object that defines the rate of change of the parameter's value (Section 4.9.4 on p. 63), the unit associated with the rule's `math` element should be equal to the parameter's `units` attribute value divided by the model-wide unit of `time`. (In other words, `{parameter units}/{unit of time}.`)

The fact that the `units` attribute value is optional means that models can define parameters with undeclared units. Leaving the units of parameter values undefined in an SBML model does not render the model invalid; however, as mentioned elsewhere, as a matter of best practice, we strongly recommend that all models specify units of measurement for all parameters.

### 4.7.4 The constant attribute

The `Parameter` object has a mandatory `boolean` attribute named `constant` that indicates whether the parameter's value can vary during a simulation. A value of `true` indicates the parameter's `value` cannot be changed by any construct except `InitialAssignment`. Conversely, if `constant`="false", other constructs in SBML, such as rules and events, can change the `value` of the parameter. More information about the effects of `constant` on `value` is presented in Section 4.7.2 on the preceding page.

What if a 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 (why is the parameter in question not flagged as being constant?), 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.

### 4.7.5 The sboTerm attribute

`Parameter` inherits an optional `sboTerm` attribute of type `SBOTerm` from its parent class `SBase` (see Section 3.1.12 on p. 14 and Section 5 on p. 91). When a value is given to this attribute in a `Parameter` instance, it should be an SBO identifier belonging to the branch for type `Parameter` indicated in Table 6 on p. 98. The relationship is of the form "the parameter is-a X", where X is the SBO term. The term chosen should be the most precise (narrow) one that captures the role of the parameter in the model.

As discussed in Section 5 on p. 91, SBO labels are optional information on a model. Applications are free to ignore `sboTerm` values. A model must be interpretable without the benefit of SBO labels.

### 4.7.6 Example

The following is an example of parameters defined at the `Model` level:

```xml
<model ...>
  ...
  <listOfParameters>
    <parameter id="tau2" value="3e-2" units="second" constant="true"/>
    <parameter id="Km1" value="10.7" units="molesperlitre" constant="true"/>
  </listOfParameters>
  ...
</model>
```
## 4.8 Initial assignments

SBML Level 3 Version 2 Core provides 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 (Section 4.7). 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. This is the reason for the existence of **InitialAssignment**: to permit the calculation of the value of a constant or the initial value of a variable from the values of *other* quantities in a model. The definition of **InitialAssignment** is shown in Figure 16.

<figure><img src="image_19.png" /><figcaption>**Figure 16:** The definition of class **InitialAssignment**. The contents of the **Math** class can be any MathML permitted in SBML; see Section 3.4.1 on p. 20. A sequence of zero or more instances of **InitialAssignment** objects can be located in an instance of **ListOfInitialAssignments** in **Model**, as shown in Figure 10 on p. 37.</figcaption></figure>

As explained below, the provision of **InitialAssignment** does not mean that models necessarily must use this construct when defining initial values of quantities. If a value can be set 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.

Initial assignments have some similarities to assignment rules (Section 4.9.3 on p. 62). The main differences are (a) unlike **AssignmentRule**, an **InitialAssignment** definition only applies up to and including the beginning of simulation time, i.e., $t \le 0$, while an **AssignmentRule** applies at all times; and (b) an **InitialAssignment** can set the value of a constant whereas an **AssignmentRule** cannot.

### 4.8.1 The id attribute

**InitialAssignment** inherits an optional **id** attribute of type **SId** from **SBase**. The identifier of an **InitialAssignment** has no mathematical meaning in an SBML Level 3 Version 2 Core model.

### 4.8.2 The symbol attribute

**InitialAssignment** contains the mandatory attribute **symbol**, of type **SIdRef**. The purpose of **InitialAssignment** is to define 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; see Section 4.8.5 on the next page.)

The value of the **symbol** attribute must be the identifier of an object in the **SId** namespace of the model; moreover, the object must be of a class that is defined to have mathematical meaning in SBML. In SBML Level 3 Core, the types of objects whose identifiers are permitted as the values of **InitialAssignment** **symbol** attributes are **Compartment**, **Species**, **SpeciesReference** and (global) **Parameter** objects in the model. In addition, classes of objects defined by SBML Level 3 packages to have mathematical meaning may also be defined by those packages to be permissible targets of **InitialAssignment** objects; in other words, **InitialAssignment** **symbol** attributes may also reference identifiers in the **SId** namespace defined by SBML Level 3 packages.

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 (see Section 4.9.5 on p. 64). It may also not reference the **id** of a **FunctionDefinition**.
If the **symbol** attribute of an **InitialAssignment** object references an object in an SBML namespace that is not recognized 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 symbol must not be assigned by the construct if the interpreter cannot understand the package. If an interpreter cannot establish whether a referenced object is missing from the model or instead is defined in an SBML namespace not recognized by the interpreter, it may produce a warning to the user. (The latter situation can only arise if an SBML package is present in the SBML document with a `package:required` attribute of "true".)

### 4.8.3 The math element

The **math** element contains a MathML expression used to calculate the value of the entity referenced by **symbol**. The unit of measurement associated with the value should match the unit associated with the identifier given in the **symbol** attribute.

An **InitialAssignment** with no **math** child leaves undefined what assignment is to be made to the corresponding **symbol**. The absence of a **math** element is permitted because it is possible for SBML Level 3 packages to add constructs that extend **InitialAssignment** and define how a value is to be computed. In the absence of such constructs in a given model, no assignments or other changes to the model are carried out when there is no **math** element. This leaves the model unchanged: any SBML component that had a value will continue to have that value; any component whose value was undefined will continue to have an undefined value. A simulator encountering this situation may choose to produce a warning. No other validation rules are affected by the absence of a **math** child: it is still invalid to have an **InitialAssignment** and an **AssignmentRule** that assign to the same model element, for example.

### 4.8.4 The sboTerm attribute

**InitialAssignment** inherits an optional **sboTerm** attribute of type **SBOTerm** from its parent class **SBase** (see Section 3.1.12 and Section 5). When a value is given to this attribute in a **InitialAssignment** instance, it should be an SBO identifier belonging to the branch for type **InitialAssignment** indicated in Table 6 on p. 98. The relationship is of the form "the initial assignment is-a X", where X is the SBO term. The term chosen should be the most precise (narrow) one that captures the role of the initial assignment in the model.

As discussed in Section 5 on p. 91, SBO labels are optional information on a model. Applications are free to ignore **sboTerm** values. A model must be interpretable without the benefit of SBO labels.

### 4.8.5 Semantics of initial assignments

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** is set in its definition, and the model also contains an **InitialAssignment** having that compartment's **id** as its **symbol** value, then the interpretation is that the **size** assigned in the **Compartment** object definition should be ignored and the value assigned based on the computation defined in the **InitialAssignment**. For SBML Level 3 Core, initial assignments can take place for **Compartment**, **Species**, **SpeciesReference** and global **Parameter** objects regardless of the value of their **constant** attribute.

This does not mean that a definition of a symbol can be omitted if there is an **InitialAssignment** object for that symbol; the symbols must always be defined even if they are assigned a value separately. For example, there must be a **Parameter** definition for a given parameter if there is an **InitialAssignment** for that parameter.

The actions of all **InitialAssignment** objects are in general terms the same, but differ in the precise details depending on the type of symbol being set:

* In the case of a species, an **InitialAssignment** sets the referenced species' initial quantity (concentration or amount) to the value determined by the formula in **math**. The unit associated with the value produced by the **math** formula should be equal to the unit associated with the species' quantity. (See Section 4.6.5 on p. 51 for an explanation of how a species' quantity is determined.)

* In the case of a species reference, an **InitialAssignment** sets the initial stoichiometry of the reactant or product referenced by the **SpeciesReference** object 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 `InitialAssignment` sets the referenced compartment's initial size to the size determined by the formula in `math`. The unit associated with the value produced by the `math` formula should be the same as that specified for the compartment's size. (See Section 4.5.4 on p. 48 for more information about compartment units.)

* In the case of a parameter, an `InitialAssignment` sets the parameter's initial value to the value of the formula in `math`. The unit associated with the value produced by the `math` formula should be the same as parameter's `units` attribute value. (See Section 4.7.3 on p. 55 for more information about parameter units.)

* 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).

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 \le 0$. Section 3.4.8 on p. 28 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` (Section 3.4.6 on p. 25).

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. (See also Section 4.9.5 on p. 64.)

The ordering of `InitialAssignment` objects in a model is not significant. The collection of `InitialAssignment`, `AssignmentRule` and `KineticLaw` objects forms 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 statements assigning the symbol and end at statements containing the symbol in their `math` elements. Such a graph must be acyclic.) Examples of valid and invalid set of assignment statements are given in Section 4.9.5 on p. 64.

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, (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 at the defined at the beginning of this section and in Section 3.4.8 on p. 28: if an `InitialAssignment` object exists for a given symbol, then the symbol's value is overridden by that initial assignment.

### 4.8.6 Example

The following example shows how the species "x" can be assigned the initial value $2 \cdot y$, where "y" is an identifier defined elsewhere in the model:

```xml
<listOfSpecies>
  <species id="x" compartment="C" substanceUnits="mole"
           hasOnlySubstanceUnits="true" boundaryCondition="false"
```
```xml
constant="false"/>
</listOfSpecies>
...
<listOfInitialAssignments>
<initialAssignment symbol="x">
<math xmlns="http://www.w3.org/1998/Math/MathML"
      xmlns:sbml="http://www.sbml.org/sbml/level3/version2/core">
<apply>
<times/>
<ci> y </ci>
<cn sbml:units="dimensionless"> 2 </cn>
</apply>
</math>
</initialAssignment>
</listOfInitialAssignments>
```

The next example illustrates the more complex behavior discussed above, when a symbol has a value assigned in its definition but there also exists an **InitialAssignment** for it and another **InitialAssignment** uses its value in its mathematical formula.

```xml
<listOfSpecies>
<species id="x" initialAmount="50" compartment="C" substanceUnits="item"
          hasOnlySubstanceUnits="true" boundaryCondition="false" constant="false"/>
</listOfSpecies>
...
<listOfInitialAssignments>
<initialAssignment symbol="x">
<math xmlns="http://www.w3.org/1998/Math/MathML"
      xmlns:sbml="http://www.sbml.org/sbml/level3/version2/core">
<cn sbml:units="item"> 10 </cn>
</math>
</initialAssignment>
<initialAssignment symbol="othersymbol">
<math xmlns="http://www.w3.org/1998/Math/MathML"
      xmlns:sbml="http://www.sbml.org/sbml/level3v/version2/core">
<apply>
<times/>
<ci> x </ci>
<cn sbml:units="dimensionless"> 2 </cn>
</apply>
</math>
</initialAssignment>
</listOfInitialAssignments>
```

The value of `othersymbol` in the SBML fragment above will be `20`. The case illustrates the rule of thumb that if there is an initial assignment for a symbol, the value assigned to the symbol in its definition (here, the value of `initialAmount`) must be ignored and the value created by the initial assignment used instead.

## 4.9 Rules

In SBML, *Rules* provide additional ways to define the values of variables in a model, their relationships, and the dynamical behaviors of those variables. *Rules* enable the encoding of relationships that cannot be expressed using reactions alone (Section 4.11 on p. 68) nor by the assignment of an initial value to a variable in a model (Section 4.8 on p. 56).

SBML separates rules 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 symbols that does not include *x*, and **W** is a vector of symbols that may include *x*):

<table><tr><td>Algebraic</td><td>left-hand side is zero:</td><td>0 = f(W)</td></tr><tr><td>Assignment</td><td>left-hand side is a scalar:</td><td>x = f(V)</td></tr><tr><td>Rate</td><td>left-hand side is a rate-of-change:</td><td>dx/dt = f(W)</td></tr></table>
In their general form given above, there is little to distinguish between *assignment* and *algebraic* rules. They are treated as separate cases for the following reasons:

* Assignment rules can simply be evaluated to calculate intermediate values for use in numerical methods;

* SBML needs to place restrictions on assignment rules, for example the restriction that assignment rules cannot contain algebraic loops (discussed further in Section 4.9.5 on p. 64);

* Many simulators do not contain numerical solvers capable of solving unconstrained algebraic equations, and providing more direct forms such as assignment rules may enable those simulators to process models they could not process if the same assignments were put in the form of general algebraic equations;

* Those simulators that *can* solve these algebraic equations make a distinction between the different categories listed above; and

* Some specialized numerical analyses of models may only be applicable to models that do not contain *algebraic* rules.

The approach taken to covering these cases in SBML is to define an abstract **Rule** class containing an element, **math**, to hold the right-hand side expression, then to derive subclasses of **Rule** that add attributes to distinguish the cases of algebraic, assignment and rate rules. Figure 17 gives the definitions of **Rule** and the subclasses derived from it. The figure shows there are three subclasses, **AlgebraicRule**, **AssignmentRule** and **RateRule** derived directly from **Rule**. These correspond to the cases *Algebraic*, *Assignment*, and *Rate* described above, respectively.

<figure><img src="image_20.png" /><figcaption>Figure 17: The definition of **Rule** and derived types **AlgebraicRule**, **AssignmentRule** and **RateRule**.</figcaption></figure>

### 4.9.1 Common attributes in Rule

The classes derived from **Rule** inherit **math** and the attributes and elements that **Rule** itself inherits from **SBase**, including **id**, **name**, and **sboTerm**.

#### The id attribute

**Rule** inherits an optional **id** attribute from **SBase**, of type **SId**. The identifier of a **Rule**-derived object has no mathematical meaning in an Level 3 Version 2 Core model.

#### The math element

A **Rule** object has an optional element called **math**, containing 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. The interpretation of **math** and its associated unit of measurement are described in more detail in Section 4.9.2, Section 4.9.3 and Section 4.9.4.
A **Rule** with no **math** child element leaves undefined how the rule behaves mathematically. The **Rule math** element is defined as optional in SBML Level 3 Core because it is possible for SBML Level 3 packages to add constructs that extend **Rule** and define the missing behavior. In the absence of such constructs in a given model, no assignments or other changes to the model are carried out when there is no **math** element. This leaves the model unchanged: any SBML component that had a value will continue to have that value; any component whose value was undefined will continue to have an undefined value. A simulator encountering this situation may choose to produce a warning. No other validation rules are affected by the absence of a **Rule math** element: it is still invalid to have an **InitialAssignment** and an **AssignmentRule** that assign to the same model element, for example.

### The sboTerm attribute

**Rule** inherits an optional **sboTerm** attribute of type **SBOTerm** from its parent class **SBase** (see Section 3.1.12 on p. 14 and Section 5 on p. 91). When a value is given to this attribute in an **AlgebraicRule**, **AssignmentRule**, or **RateRule** instance, it should be an SBO identifier belonging to the branch for type **AlgebraicRule**, **AssignmentRule**, or **RateRule** indicated in Table 6 on p. 98. The relationship is of the form “the rule *is-a* X”, where X is the SBO term. The term chosen should be the most precise (narrow) one that captures the role of the rule in the model.

As discussed in Section 5 on p. 91, SBO labels are optional information on a model. Applications are free to ignore **sboTerm** values. A model must be interpretable without the benefit of SBO labels.

## 4.9.2 AlgebraicRule

The rule type **AlgebraicRule** is used to express equations that are neither assignments of model variables nor rates of change. The **AlgebraicRule** class does not add any attributes to the basic **Rule**; its role is simply to distinguish this case from the other cases. An example of the use of **AlgebraicRule** is given in Section 7.6.

In the context of a simulation, algebraic rules are in effect at all times, $t \ge 0$. To allow evaluating expressions that involve the *delay csymbol* (Section 3.4.6), algebraic rules are considered to apply also at $t \le 0$. Section 3.4.8 describes the semantics of assignments, rules, and entity values for simulation time $t \le 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**="false" or else not be involved in any reaction at all. These restrictions are explained in more detail in Section 4.9.5 below.

Reaction identifiers can be referenced in the **math** expression of an algebraic rule, but reaction rates can never be *determined* by algebraic rules. This is true even when a reaction does not contain a **KineticLaw** element. (In such cases of missing **KineticLaw** elements, the model is valid but incomplete; the rates of reactions lacking kinetic laws are simply undefined, and not determined by the algebraic rule.)

Finally, any symbol that appears as the target of a *rateOf csymbol* 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.

Although the rules above directly stipulate the symbols that may not be determined by the **AlgebraicRule** construct, note that they can also be used to discover the symbol that *is* determined by a given **AlgebraicRule** object. For instance, if three symbols appear in the **math** portion of **AlgebraicRule**, and the first has **constant**="true" and the second symbol is a **Reaction** identifier, one may deduce that the **AlgebraicRule** is being used to determine the value of the third symbol that appears in the mathematical expression. This is, in fact, one of the principal uses (in addition to model validation) of the **constant** attribute: it allows software to identify the dependent variables in a model's **AlgebraicRule** objects.
### 4.9.3 AssignmentRule

The rule type **AssignmentRule** is used to express equations that set the values of variables. The left-hand side (the required **variable** attribute) of an assignment rule is of type **SIdRef**, and must refer to an SBML object in the **SId** namespace with mathematical meaning and the ability to be assigned. In SBML Level 3 Core, this consists of **Species**, **SpeciesReference**, **Compartment**, and global **Parameter** objects in the model (but not reactions nor function definitions). The entity identified must have its **constant** attribute set to the value **false**. The effects of an **AssignmentRule** 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 **AssignmentRule** sets the referenced species' quantity (whether a concentration or amount) to the value determined by the formula in **math**. The unit associated with the value produced by the **math** formula should be equal to the unit associated with the species' quantity. (See Section 4.6.5 on p. 51 for an explanation of how a species' quantity is determined.)

**Restrictions:** There must not be both an **AssignmentRule** variable attribute and a **SpeciesReference** species attribute having the same value, unless that species 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.

* In the case of a species reference, an **AssignmentRule** sets the stoichiometry of the corresponding 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 **AssignmentRule** sets the referenced compartment's size to the size determined by the formula in **math**. The unit associated with the value produced by the **math** formula should be the same as that specified for the compartment's size. (See Section 4.5.4 on p. 48 for more information about compartment units.)

* In the case of a parameter, an **AssignmentRule** sets the referenced parameter's value to the value of the formula in **math**. The unit associated with the value produced by the formula should be the same as parameter's **units** attribute value. (See Section 4.7.3 for more information about parameter units.)

* 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).

If the **variable** attribute of an **AssignmentRule** object references an object in an SBML namespace not recognized 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 must not be assigned by the rule if the interpreter cannot understand the package. If an interpreter cannot establish whether a referenced object is missing from the model or instead is defined in an SBML namespace not recognized by the interpreter, it may produce a warning to the user. (The latter situation can 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 \ge 0$. For purposes of evaluating expressions that involve the `delay` csymbol (Section 3.4.6), assignment rules are considered to apply also at $t \le 0$. Section 3.4.8 on p. 28 provides additional information about how $t \le 0$ should be handled.

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** for the same variable, because both kinds of constructs apply prior to and at the start of simulation time, i.e., $t \le 0$. If a
model contained both an initial assignment and an assignment rule for the same variable, an indeterminate system would result. (See also Section 4.8.5 on p. 57.)

The value calculated by an **AssignmentRule** object overrides the value assigned to the given symbol by the object defining that symbol. For example, if a **Compartment**'s **size** is set in its definition, and the model also contains an **AssignmentRule** having that compartment's **id** as its **variable** value, then the **size** assigned in the **Compartment** 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 for it. For example, there must be a **Parameter** definition for a given parameter if there is an **AssignmentRule** for that parameter.

### 4.9.4 RateRule

The rule type **RateRule** is used to express equations that determine the rates of change of variables. The left-hand side (the required **variable** attribute) of a rate rule has type `SIdRef`, and must refer to an SBML object in the `SId` namespace with mathematical meaning and the ability to be assigned. In Level 3 Core, this consists of `Species`, `SpeciesReference`, `Compartment`, and global `Parameter` objects in the model (but not reactions nor function definitions). 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*) to the value determined by the formula in *math*. The unit associated with the rule's *math* element should be equal to the unit of the species' quantity (Section 4.6.5 on p. 51) divided by the model-wide unit of *time* (Section 4.2.3 on p. 38), or in other words, `{unit of species quantity}/{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.

* 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 formula should be consistent with `{unit derived from dimensionless}/{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 *math*. 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 the case of a parameter, a **RateRule** sets the rate of change of the parameter's value to that determined by the formula in *math*. The unit associated with the rule's *math* element should be equal to the parameter's **units** attribute value divided by the model-wide unit of *time*. (In other words, `{parameter units}/{unit of time}`.)

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

If the **variable** attribute of a **RateRule** object references an object in an SBML namespace that is not recognized 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 must not be assigned by the rule if the interpreter cannot understand the package. If an interpreter cannot establish whether a referenced object is missing from the model or instead is defined in an SBML namespace not
recognized by the interpreter, it may produce a warning to the user. (The latter situation can 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$. Other types of rules and initial assignments are in effect at different times; Section 3.4.8 on p. 28 describes these conditions.

As mentioned in Section 4.9.3 for **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.

### 4.9.5 Additional restrictions on rules

An important design goal of SBML rule semantics is to ensure that a model's simulation and analysis results will not be dependent on when or how often rules are evaluated. To achieve this, SBML needs to place two additional restrictions on rule use in addition to the conditions described above regarding the use of **AlgebraicRule**, **AssignmentRule** and **RateRule**. The first concerns algebraic loops in the system of assignments in a model, and the second concerns overdetermined systems.

#### The model must not contain algebraic loops

The combined set of **InitialAssignment**, **AssignmentRule** and **KineticLaw** objects 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, species reference, compartment or parameter symbol in an assignment statement's **math** element. Let the directed arcs point from the statement assigning the symbol to the statements that contain the symbol in their **math** element 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**). 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 following equations:

$$x = x + 1, \quad y = z + 200, \quad 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, \quad y = z + 200, \quad z = x + 100$$

#### The model must not be overdetermined

An SBML model must not be overdetermined; that is, a model must not define more equations than there are unknowns in a model. An SBML model without **AlgebraicRule** objects cannot be overdetermined.
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. It should be noted that when a model contains both reactions and events, there are several sets of equations to consider in order to assess whether a model is overdetermined. The set of equations derived from the combined set of rules and reactions and, for each event, the set of equations derived from the combined set of rules and event assignments for the particular event.

One approach is to construct a bipartite graph in which one set of vertices represents the variables and the other set of vertices represents the equations. The approach involves placing edges between vertices such that variables in the system are linked to the equations that determine them. A mathematical model is overdetermined if the maximal matchings (Chartrand, 1977) 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.) Appendix Section B describes a method of applying this procedure to specific SBML data objects. In some cases it is possible to avoid the use of an AlgebraicRule. This is discussed in more detail in Section 8.2.3 on p. 151.

### 4.9.6 Example of rule use

This section contains an example set of rules. Consider the following set of equations:

$$k = \frac{k_3}{k_2}, \quad s_2 = \frac{k \cdot x}{1 + k_2}, \quad A = 0.10 \cdot x$$

This can be encoded by the following scalar rule set (where the definitions of x, s, k, k2, k3 and A are assumed to be located elsewhere in the model and not shown in this abbreviated example):

```xml
<listOfRules>
  <assignmentRule variable="k">
    <math xmlns="http://www.w3.org/1998/Math/MathML">
      <apply>
        <divide/>
        <ci> k3 </ci>
        <ci> k2 </ci>
      </apply>
    </math>
  </assignmentRule>
  <assignmentRule variable="s2">
    <math xmlns="http://www.w3.org/1998/Math/MathML">
      <apply>
        <divide/>
        <apply>
          <times/>
          <ci> k </ci>
          <ci> x </ci>
        </apply>
      </apply>
      <apply>
        <plus/>
        <cn> 1 </cn>
        <ci> k2 </ci>
      </apply>
    </math>
  </assignmentRule>
  <assignmentRule variable="A">
    <math xmlns="http://www.w3.org/1998/Math/MathML">
      <apply>
        <times/>
        <cn> 0.10 </cn>
        <ci> x </ci>
      </apply>
      <apply>
        <math>
          <cn> 0.10 </cn>
        </math>
      </apply>
    </math>
  </assignmentRule>
</listOfRules>
```
## 4.10 Constraints

The **Constraint** object is 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. Figure 18 shows the definition of the **Constraint** object class.

<figure><img src="image_21.png" /><figcaption>**Figure 18:** The definition of class **Constraint**. The contents of the **Math** class can be any MathML permitted in SBML, and will be interpreted as a Boolean value. As shown above, an instance of **Constraint** can also contain zero or one instances of **Message** objects; this class of object is simply a wrapper (in the XML form, `<message> ... </message>`) for XHTML content. The same guidelines for XHTML content as explained in Section 3.2.5 on p. 15 for notes on **SBase** also apply to the XHTML within messages in a **Constraint**. A sequence of zero or more instances of **Constraint** objects can be located in an instance of ** ListOfConstraints** in **Model**, as shown in Figure 10 on p. 37.</figcaption></figure>

The essential meaning of a constraint is this: if a dynamical analysis of a model (such as a simulation) reaches a state in which a constraint is no longer satisfied, the results of the analysis are deemed invalid beginning with that point in time. The exact behavior of a software tool, upon encountering a constraint violation, is left up to the software; however, a software tool must somehow indicate to the user when a model's constraints are no longer satisfied. (Otherwise, a user may not realize that the analysis has reached an invalid state and is potentially producing nonsense results.) If a software tool does not have support for constraints, it should indicate this to the user when encountering a model containing constraints.

### The id attribute

**Constraint** inherits an optional **id** attribute from **SBase**, of type **SId**. The identifier of a **Constraint** object has no mathematical meaning in an SBML Level 3 Version 2 Core model.

### The sboTerm attribute

**Constraint** inherits an optional **sboTerm** attribute of type **SBOTerm** from its parent class **SBase** (see Section 3.1.12 on p. 14 and Section 5 on p. 91). When a value is given to this attribute in a **Constraint** instance, it should be an SBO identifier belonging to the branch for type **Constraint** indicated in Table 6 on p. 98. The relationship is of the form “the constraint *is-a* X”, where X is the SBO term. The term chosen should be the most precise (narrow) one that captures the role of the constraint in the model.

As discussed in Section 5 on p. 91, SBO labels are optional information on a model. Applications are free to ignore **sboTerm** values. A model must be interpretable without the benefit of SBO labels.

### 4.10.1 The math element

**Constraint** has one optional subelement, **math**, containing a MathML formula defining the condition of the constraint. This formula must return a Boolean value of “**true**” (or any non-zero numerical value) when the model is in 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 in Section 4.10.3 below.
A **Constraint** with no **math** child does not define a mathematical constraint. The absence of a **math** element is permitted because it is possible for SBML Level 3 packages to add constructs that extend **Constraint** and define how a value is to be computed. In the absence of any such construct, no restriction on the model's behavior is implied. A simulator encountering this situation may choose to produce a warning.

### 4.10.2 Message

A **Constraint** object can contain an optional element named **message** whose content is determined by object class **Message**. This element can contain a message in XHTML format that may be displayed to the user when the condition of the constraint in **math** 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** object must follow the same restrictions as for **Notes** objects described in Section 3.2.5 on p. 15. In particular, the element must declare the use of the XHTML XML namespace, and must not contain an XML declaration nor a DOCTYPE declaration.

### 4.10.3 Semantics of constraints

In the context of a simulation, a **Constraint** has effect at all times $t \ge 0$. Each **Constraint**'s **math** element 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.)

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** 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 contents of the **Message** subobject (Section 4.10.2) 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.

There are no 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 **math** element. Since the failure of any constraint indicates the simulation has entered an invalid state, a system is not required to attempt detecting whether other constraints in the model have failed once any one constraint has failed.

### 4.10.4 Example

As an example, the following SBML fragment demonstrates the constraint that species "S1" should only have values between 1 and 100:

```xml
<model ...>
  ...
  <listOfConstraints>
    <constraint>
      <math xmlns="http://www.w3.org/1998/Math/MathML"
        xmlns:sbml="http://www.sbml.org/sbml/level3/version2/core">
        <apply>
          <and/>
          <apply> <lt/> <cn sbml:units="mole"> 1 </cn> <ci> S1 </ci> </apply>
          <apply> <lt/> <ci> S1 </ci> <cn sbml:units="mole"> 100 </cn> </apply>
        </apply>
      </math>
      <message>
        <p xmlns="http://www.w3.org/1999/xhtml"> Species S1 is out of range. </p>
      </message>
    </constraint>
  </listOfConstraints>
  ...
</model>
```
4.11 Reactions

A reaction in SBML represents any kind of process that can change the quantity of one or more species in a model. Examples of such processes can include transformation, transport, molecular interactions, and more. In SBML, the notion of a reaction is generalized to allow entities that may not be chemical substances; thus, a reaction in SBML does not necessarily have to be a biochemical reaction—a biochemical reaction is just one possible kind of process.

At minimum, to describe a reaction in SBML, it is necessary to define its structural properties, specifically the participating reactants and/or products (and their corresponding stoichiometries) and the reversibility of the process. In addition, an SBML reaction can also contain a quantitative description of the rate of the reaction; this aspect consists of a mathematical formula expressing describing the rate at which the reaction process takes place, together with an optional list of modifier species and parameters influencing the reaction rate. The various parts of a reaction are recorded in the SBML Reaction object class and other supporting data classes, defined in Figure 19.

<figure><img src="image_22.png" /><figcaption>**Figure 19:** The definitions of Reaction, KineticLaw, SpeciesReference, ModifierSpeciesReference, LocalParameter, as well as the container classes ListOfSpeciesReferences, ListOfModifierSpeciesReferences, and ListOfLocalParameters. Note: SimpleSpeciesReference is an abstract class only used to provide some common attributes to derived classes.</figcaption></figure>
### 4.11.1 Reaction

Each reaction in an SBML model is defined using an instance of a **Reaction** object. As shown in Figure 19 on the previous page, it contains several scalar attributes and several lists of other objects.

#### The id attribute

**Reaction** inherits the **id** attribute from **SBase**; however, **Reaction** defines **id** as being required rather than optional. The attribute otherwise behaves as described in Section 3.3 on p. 18.

The identifier (the **id** attribute value) of a **Reaction** object may be used in mathematical expressions in a model. The identifier stands for the reactions rate; this role and the units of measurement associated with the reaction identifier are explained in more detail in Section 4.11.8 on p. 79. A reaction's identifier cannot be the target of an **InitialAssignment**, **EventAssignment**, or **Rule** object, nor may its value be determined by an **AlgebraicRule** object in a model.

#### The lists of reactants, products and modifiers

Each species participating as a reactant, product, and/or modifier in a reaction must be declared using a **SpeciesReference** and/or **ModifierSpeciesReference** object stored in the list elements `listOfReactants`, `listOfProducts` and `listOf modifiers`. The object classes **SpeciesReference** and **ModifierSpeciesReference** are described in more detail in Section 4.11.3 and Section 4.11.4 below. Throughout this text, we use the informal expressions “list of reactants”, “list of products” and “list of modifiers” to mean, respectively, the list of species identified by **SpeciesReference** objects within a **Reaction** `listOfReactants` element, the list of species identified by **SpeciesReference** objects within a **Reaction** `listOfProducts` element, and the list of species identified by **ModifierSpeciesReference** objects within a **Reaction** `listOf modifiers` element.

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 combinations of the attributes **constant** and **boundaryCondition** on the **Species** object instance; see Section 4.6.6 on p. 51 for more information.

* Any species appearing in the **math** element of the **kineticLaw** of a **Reaction** instance must be declared in at least one of that **Reaction**'s lists of reactants, products, and/or modifiers. 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 definition can contain an empty list of reactants or an empty list of products, but it must have at least one reactant or product; in other words, a reaction without any reactant or product species is not permitted. (This restriction does not apply to modifier species, which are always optional.)

#### The kineticLaw element

A **Reaction** object can contain up to one **KineticLaw** object, in the **kineticLaw** element. This “kinetic law” defines the speed at which the process defined by the reaction takes place. A more detailed description of **KineticLaw** is left to Section 4.11.5 on p. 74 below.

The inclusion of a **KineticLaw** object in an instance of a **Reaction** is optional. For some modeling purposes, models containing reactions without defined rates are an acceptable alternative (and may even be the only possible option, such as when the kinetics of the reactions are unknown). However, missing kinetic laws preclude the application of many model analysis techniques, including simulation. In the absence of any additional definition, some simulators choose to give an error and refuse to simulate models that have a **Reaction** with no **KineticLaw**. Others assume that the effective rate of a **Reaction** with no **KineticLaw** is zero. Still others define this value to be “not a number” (NaN). This behavior is not standardized, and should not be relied on when exchanging models for simulation.
### The reversible attribute

The mandatory **boolean** attribute **reversible** on **Reaction** indicates whether the reaction is reversible. To say that a reaction is *reversible* is to say it can proceed in either the forward or the reverse direction. This information may be redundant in cases where the reversibility of the reaction can be deduced by inspecting the rate formula given in the kinetic law. However, a reaction is not required to have a kinetic law, and besides, when a rate expression is present, it may not always be possible to deduce the reversibility by inspecting it. Having a separate attribute for **reversible** allows certain kinds of structural analysis, such as elementary mode analysis, even in these cases.

Mathematically, the **reversible** attribute on **Reaction** has no impact on the construction of the equations for change of the species' quantities. However, labeling a reaction as irreversible is interpreted as an assertion that the rate expression will not have negative values during a simulation. Software developers may wish to provide their software systems with a means of testing that this condition holds.

The presence of reversibility information in two places (i.e., the rate expression in the kinetic law, and the **reversible** flag) leaves open the possibility that a model could contain contradictory information, but this would be considered to be an error of the encoded model, rather than an invalid SBML encoding.

### The fast attribute (removed)

In SBML Level 3 Version 2, the **fast** attribute has been removed: every **Reaction** in a Level 3 Version 2 Core model is equivalent to an SBML Level 3 Version 1 **Reaction** with a **fast** value of "false". This means that for Level 3 Version 2 Core, the speed of every **Reaction** will always be determined by its **KineticLaw**. To achieve the same or similar effects as setting the **fast** attribute to "true" in a previous version of SBML, the **KineticLaw** should be constructed to produce a value in the desired time scale, or the reaction can be replaced with an **AssignmentRule** or **AlgebraicRule** object as in the example of Section 7.5 on p. 124.

### The compartment attribute on Reaction

The optional attribute **compartment**, of data type **SIdRef**, 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 reaction has a kinetic law, the compartment location may already be implicit in the kinetic law (though 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.

### The sboTerm attribute on Reaction

**Reaction** inherits an optional **sboTerm** attribute of type **SBOTerm** from its parent class **SBase** (see Section 3.1.12 on p. 14 and Section 5 on p. 91). When a value is given to this attribute in a **Reaction** instance, it should be an SBO identifier belonging to the branch for type **Reaction** indicated in Table 6 on p. 98. The relationship is of the form "the reaction *is-a* X", where X is the SBO term. The term chosen should be the most precise (narrow) one that captures the role of the reaction in the model.

As discussed in Section 5 on p. 91, SBO labels are optional information on a model. Applications are free to ignore **sboTerm** values. A model must be interpretable without the benefit of SBO labels.

## 4.11.2 SimpleSpeciesReference

As mentioned above, every species that enters into a given reaction must appear in that reaction's lists of reactants, products and/or modifiers. In an SBML model, all species that may participate in any reaction are listed in the ** ListOfSpecies ** object of the top-level ** Model ** object instance (see Section 4.2 on p. 36). The lists of products, reactants and modifiers in **Reaction** objects do not introduce new species, but rather, they refer back to those listed in the model's top-level ** ListOfSpecies ** object. For reactants and products, the connection
is made using a **SpeciesReference** object; for modifiers, it is made using a **ModifierSpeciesReference** object. **SimpleSpeciesReference**, defined in Figure 19 on p. 68, is an abstract type that serves as the parent class of both **SpeciesReference** and **ModifierSpeciesReference**. It is used simply to hold the attributes and elements that are common to the latter two objects.

### The species attribute

The **SimpleSpeciesReference** object class has a required attribute, **species**, of data type **SIdRef**, inherited by **SpeciesReference** and **ModifierSpeciesReference**. The value of **species** must be the identifier of a species defined in the enclosing **Model**; the referenced species is thereby declared as participating in the reaction being defined. The precise role of that species as a reactant, product, or modifier in the reaction is determined by the subtype of **SimpleSpeciesReference** (i.e., either **SpeciesReference** or **ModifierSpeciesReference**) in which the identifier appears and by the specific list of species references in which the **SpeciesReference** appears.

### The sboTerm attribute

**SimpleSpeciesReference** inherits an optional **sboTerm** attribute of type **SBOTerm** from its parent class **SBase** (see Section 3.1.12 and Section 5). When a value is given to this attribute in a **SimpleSpeciesReference** instance, it should be an SBO identifier belonging to the branch for type **SimpleSpeciesReference** indicated in Table 6 on p. 98. The relationship is of the form “the species reference is-a X”, where X is the SBO term. The term chosen should be the most precise (narrow) one that captures the role of the species reference in the model.

As discussed in Section 5 on p. 91, SBO labels are optional information on a model. Applications are free to ignore **sboTerm** values. A model must be interpretable without the benefit of SBO labels.

### 4.11.3 SpeciesReference

**Reaction** provides a way to express which species act as reactants and which species act as products in a reaction, and to declare their stoichiometries. This is done using **SpeciesReference** objects. As mentioned above in Section 4.11.2 on the previous page, **SpeciesReference** inherits the mandatory attribute **species** and optional attributes **id**, **name**, and **sboTerm** from the parent type **SimpleSpeciesReference**. It also defines the optional attribute **stoichiometry** and the mandatory attribute **constant**, described below.

### The id attribute

The **id** attribute that **SpeciesReference** inherits from **SBase** is still optional, and behaves as described in Section 3.3 on p. 18. It also acquires the mathematical meaning of the value of its **stoichiometry** attribute, and may be the target of an **InitialAssignment**, **EventAssignment**, or **Rule** object defined in the enclosing model.

### The stoichiometry attribute

The **stoichiometry** of a species in a reaction describes how much of the species changes when a reaction event takes place. In SBML, product and reactant stoichiometries are specified using the optional **stoichiometry** on **SpeciesReference** object. The **stoichiometry** attribute is of type **double**. A missing **stoichiometry** implies that the stoichiometry is either unknown, or to be obtained from an external source, or determined by an initial assignment (Section 4.8 on p. 56) or other SBML construct elsewhere in the model.

A species reference's stoichiometry is set by its **stoichiometry** attribute exactly once. If the **SpeciesReference** object's **constant** attribute (see below) has the value “true”, then the stoichiometry is fixed and cannot be changed except by an **InitialAssignment**. These two methods of setting the stoichiometry (i.e., using **stoichiometry** directly, or using an **InitialAssignment**) differ in that the **stoichiometry** attribute can only be set to a literal floating-point number, whereas **InitialAssignment** allows the value to be set using an arbitrary mathematical expression. (As an example, the approach could be used to set the stoichiometry to a rational number of the form $p/q$, where *p* and *q* are integers, something that is occasionally useful in the context of biochemical reaction networks.) If the species reference's **constant** attribute has the value “false”, the species reference's value may be overridden by an **InitialAssignment** or changed by **AssignmentRule** or **AlgebraicRule**,
and in addition, for simulation time $t > 0$, it may also be changed by a **RateRule** or **Event**. (However, some of these constructs are mutually exclusive; see Section 4.9 on p. 59 and Section 4.12 on p. 79.) It is not an error to define **stoichiometry** on a species reference and also redefine the stoichiometry using an **InitialAssignment**, but the **stoichiometry** attribute in that case is ignored. Section 3.4.8 on p. 28 provides additional information about the semantics of assignments, rules and values for simulation time $t \le 0$. Real-world examples of variable stoichiometries in models include genome-scale models (O'Brien et al., 2013), and can generally be found in searches such as https://scholar.google.com/scholar?q+variable+stoichiometry.

An explanation of how exactly the stoichiometry is used in the mathematical interpretation of the model is given in Section 4.11.7 on p. 77.

### The constant attribute

The **SpeciesReference** attribute **constant** is a mandatory **boolean** attribute used to indicate whether the **stoichiometry** value can vary during a simulation. If **constant**="true", the corresponding species' stoichiometry in the reaction cannot be changed by other constructs elsewhere in the model except by an **InitialAssignment**. A value of "false" means the stoichiometry can be changed by other SBML constructs such as rules (see Section 4.9 on p. 59), as described above in the section on the **stoichiometry** attribute.

### Use of species reference identifiers in mathematical expressions

The value of the **id** attribute of a **SpeciesReference** can be used as the content of a **ci** element in MathML formulas elsewhere in the model. When the identifier appears in a **ci** element, it represents the stoichiometry of the corresponding species in the reaction where the **SpeciesReference** object instance appears. More specifically, it represents the value of the **stoichiometry** attribute on the **SpeciesReference** object.

### The unit of measurement associated with a SpeciesReference's stoichiometry value

The unit associated with the value of a species' stoichiometry is always considered to be **dimensionless**. This has the following implications:

* When a species reference's identifier appears in mathematical formulas elsewhere in the model, the unit associated with that value is **dimensionless**.

* The units of the **math** elements of **AssignmentRule**, **InitialAssignment** and **EventAssignment** objects setting the stoichiometry of the species reference should be **dimensionless**.

* If a species reference's identifier is the subject of a **RateRule**, the unit associated with the **RateRule** object's value should be **dimensionless**/time, where *time* is the model-wide unit of *time* (Section 4.2.3 on p. 38).

### Examples

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":

```xml
<model ...>
  ...
  <listOfReactions>
    <reaction id="J1" reversible="false">
      <listOfReactants>
        <speciesReference species="X0" stoichiometry="2" constant="true"/>
      </listOfReactants>
      ...
    </reaction>
    ...
  </listOfReactions>
  ...
</model>
```

The following is a more complex example of a species reference with an id "sr01" and an initial assignment that assigns a rational number to the stoichiometry:
```xml
<model ...>
  ...
  <listOfInitialAssignments>
    <initialAssignment symbol="sr01">
      <math xmlns="http://www.w3.org/1998/Math/MathML"
             xmlns:sbml="http://www.sbml.org/sbml/level3/version2/core">
        <cn type="rational" sbml:units="dimensionless"> 3 <sep/> 2 </cn>
      </math>
    </initialAssignment>
    ...
  </listOfInitialAssignments>
  ...
  <listOfReactions>
    <reaction id="J1" reversible="true">
      <listOfReactants>
        <speciesReference id="sr01" species="X0" constant="true"/>
      </listOfReactants>
    </reaction>
    ...
  </listOfReactions>
  ...
</model>
```

A species can occur more than once in the lists of reactants and products of a given **Reaction** instance. The effective stoichiometry for the species is the sum of the stoichiometry values given in the **SpeciesReference** objects in the list of products *minus* the sum of stoichiometry values given in the **SpeciesReference** objects in the list of reactants. A positive value indicates the species is effectively a product and a negative value indicates the species is effectively a reactant. SBML places no restrictions on the effective stoichiometry of a species in a reaction; for example, it can be zero. In the following SBML fragment, the two reactions have the same effective stoichiometry for all their species:

```xml
<reaction id="x" reversible="false">
  <listOfReactants>
    <speciesReference species="a" stoichiometry="1" constant="true"/>
    <speciesReference species="a" stoichiometry="1" constant="true"/>
    <speciesReference species="b" stoichiometry="1" constant="true"/>
  </listOfReactants>
  <listOfProducts>
    <speciesReference species="c" stoichiometry="1" constant="true"/>
    <speciesReference species="b" stoichiometry="1" constant="true"/>
  </listOfProducts>
</reaction>
<reaction id="y" reversible="false">
  <listOfReactants>
    <speciesReference species="a" stoichiometry="2" constant="true"/>
  </listOfReactants>
  <listOfProducts>
    <speciesReference species="c" stoichiometry="1" constant="true"/>
  </listOfProducts>
</reaction>
```

### 4.11.4 ModifierSpeciesReference

Sometimes a species appears in the kinetic rate formula of a reaction but is 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 *manifiers* without regard to the detailed role of those species in the model (though a model could use SBO terms to clarify the roles; see Section 5 on p. 91). The **Reaction** object class 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** object.

Because its sibling class **SpeciesReference** has mathematical meaning, it is probably worth noting that no meaning is assigned to the identifier of **ModifierSpeciesReference** object instances in SBML Level 3 Version 2 Core, but the identifiers are available for possible use by SBML Level 3 packages. Note that modifiers in reactions also have no stoichiometries and therefore do not possess a **stoichiometry** attribute.
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.

### 4.11.5 KineticLaw

The **KineticLaw** object class is used to describe the rate at which the process defined by the **Reaction** takes place. As shown in Figure 19 on p. 68, **KineticLaw** has elements called **math** and **listOfLocalParameters**, in addition to the attributes and elements it inherits from **SBase**.

#### The id attribute

**KineticLaw** inherits an optional **id** attribute from **SBase**, of type **SId**. Despite having a **math** child, the **id** of a **KineticLaw** takes on no mathematical meaning; the value of that **math** element is instead associated with the enclosing **Reaction** object's identifier.

#### The math element

As shown in Figure 19 on p. 68, **KineticLaw** has an element called **math** for holding a MathML formula defining the rate of the reaction. The expression in **math** may refer to global identifiers defined in the model as well as **LocalParameter** object identifiers from the **KineticLaw**'s list of local parameters (see below). However, the only **Species** identifiers that can be used in **math** are those declared in the lists of reactants, products and modifiers in the **Reaction** object (see Section 4.11.2, Section 4.11.3 and Section 4.11.4).

Section 4.11.7 provides important discussions about the meaning and interpretation of SBML "kinetic laws".

A **KineticLaw** with no **math** child leaves undefined the mathematics of the corresponding **Reaction**. The absence of a **math** element is permitted because it is possible for SBML Level 3 packages to add constructs that extend **KineticLaw** and define other ways for a value to be computed. In the absence of such package constructs, the model behaves mathematically as if the **KineticLaw** is not defined. This can be sometime useful, for example, when a model needs to define one or more **LocalParameter** objects (which are placed within **KineticLaw** objects) but has no mathematical formula for the kinetics of the reaction involved.

#### The list of local parameters

An instance of **KineticLaw** can contain a list of zero or more **LocalParameter** objects (Section 4.11.6 on the next page) defining new parameters whose identifiers can be used in the **math** formula. These "local parameters" are optional—a kinetic law can always refer to global **Parameter** objects. The local parameter facility simply provides a way to add additional parameters that may be relevant only to a specific reaction, and that may therefore be better handled by encapsulating their definitions within that kinetic law.

As discussed in Section 3.3.1 on p. 18, reactions introduce local namespaces for local parameter identifiers, and within a **KineticLaw** object (as well as within the parent **Reaction**), a local parameter whose identifier is identical to a global identifier defined in the model takes precedence over the value associated with the global identifier. Note that this introduces the potential for a local parameter definition to shadow a global identifier. SBML does not separate symbols by class of object; consequently, inside the kinetic law mathematical formula, the value of a local parameter having the same identifier as a species, compartment, parameter or other global model entity will override the global value. Modelers and software developers may wish to take precautions to avoid this happening accidentally.

#### The sboTerm attribute

**KineticLaw** inherits an optional **sboTerm** attribute of type **SBOTerm** from its parent class **SBase** (see Section 3.1.12 on p. 14 and Section 5 on p. 91). When a value is given to this attribute in a **KineticLaw** instance, it should be an SBO identifier belonging to the branch for type **KineticLaw** indicated in Table 6 on p. 98. The
relationship is of the form “the kinetic law *is-a* X”, where X is the SBO term. The term chosen should be the most precise (narrow) one that captures the role of the kinetic law in the model.

As discussed in Section 5 on p. 91, SBO labels are optional information on a model. Applications are free to ignore **sboTerm** values. A model must be interpretable without the benefit of SBO labels.

### 4.11.6 LocalParameter

The **KineticLaw** object within a **Reaction** object can contain a **ListOfLocalParameters** object containing the definitions of *local parameter* that are only accessible within the scope of that particular reaction. The list contains **LocalParameter** objects, each of which associates an identifier with a value. This identifier can then be used in the kinetic law. The definition of **LocalParameter** is shown in Figure 19 on p. 68.

#### The id attribute

**LocalParameter** inherits the **id** attribute from **SBase**; however, **LocalParameter** defines **id** as being required rather than optional, and in addition, its type is defined to be the derived type of **LocalSId** instead of **SId**. It otherwise behaves as described in Section 3.3 on p. 18.

The identifier (the **id** attribute value) of a **LocalParameter** may be used in the mathematical expression within the enclosing **KineticLaw** object. The identifier stands for the value of the parameter's **value** attribute, and within the scope of a **KineticLaw** object and within the scope of the **Reaction** itself, a local parameter's identifier shadows any identical identifiers from the **SId** namespace of the model. Because of its limited local scope, the identifier also cannot be the target of an **InitialAssignment**, **EventAssignment**, or **Rule** object in the model. The units of measurement associated with the identifier are described in Section 4.11.6.

A **LocalParameter** must not have the same **id** value as a **Species** referenced by any of the parent **Reaction**'s **SpeciesReference** objects. (If this were permitted, the local scoping would mean that the **SpeciesReference** would refer to a **LocalParameter**, which is not a **Species**—which would create an inconsistency.)

The effective scope of where a **LocalParameter** **id** can be used in SBML Level 3 Core is restricted to the **math** of the **KineticLaw**, since no other construct within a **Reaction** can reference an **SId**. However, SBML Level 3 packages may introduce new ways of referencing **SId** values within a **Reaction** that could also refer to **LocalParameter** objects. Packages could therefore introduce cases where a **KineticLaw** can exist without a **math** element but with a new package construct that (for example) uses a **ListOfLocalParameters** to provide the package construct with locally-scoped parameters to reference.

#### The value attribute

The optional attribute **value** determines the value (of type **double**) assigned to the identifier. A missing **value** attribute implies that the value either is unknown, or to be obtained from an external source. (Note that, unlike the case with global **Parameter** objects, there is no way in SBML Level 3 Version 2 Core for **InitialAssignment** or other SBML constructs to be used for setting the value of **LocalParameter** objects, because local parameters are local to reactions.)

#### The units attribute

The unit of measurement associated with the value of the parameter can be specified using the optional attribute **units**. The attribute's value must have the data type **UnitSIdRef** (Section 3.1.10 on p. 13). There are no constraints on the units that can be assigned to local 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**).

The **units** attribute is used in the following way: when a local parameter's identifier appears in the content of the **math** element of the enclosing **KineticLaw** object, the unit of measurement associated with the local parameter's value is determined by the **LocalParameter** object's **units** attribute.
## The sboTerm attribute

**LocalParameter** inherits an optional **sboTerm** attribute of type **SBOTerm** from its parent class **SBase** (see Section 3.1.12 and Section 5). When a value is given to this attribute in a **LocalParameter** instance, it should be an SBO identifier belonging to the branch for type **LocalParameter** indicated in Table 6 on p. 98. The relationship is of the form “the local parameter is-a X”, where X is the SBO term. The term chosen should be the most precise (narrow) one that captures the role of the local parameter in the model.

As discussed in Section 5 on p. 91, SBO labels are optional information on a model. Applications are free to ignore **sboTerm** values. A model must be interpretable without the benefit of SBO labels.

## Example

The following is an example of a **Reaction** object that defines a reaction with identifier $J_1$, in which $X_0 \rightarrow S_1$ at a rate given by $k \cdot [X_0] \cdot [S_2]$, where $S_2$ is a catalyst and $k$ is a parameter, and the square brackets symbolizes that the species quantities are in terms of concentrations. The reaction is assumed to take place all in one compartment identified as “c1”. The example demonstrates the use of species references, **KineticLaw** objects and local parameters. The units associated with the species identifiers here are *amount/volume* (see Section 4.6 on p. 49), and so the rate expression $k \cdot [X_0] \cdot [S_2]$ needs to be multiplied by the compartment volume (represented by its identifier, “c1”) to produce the desired units of *amount/time* for the rate expression.

```xml
<model timeUnits="second" extentUnits="mole" substanceUnits="mole">
  <listOfUnitDefinitions>
    <unitDefinition id="per_concent_per_time">
      <listOfUnits>
        <unit kind="litre" exponent="1" scale="0" multiplier="1"/>
        <unit kind="mole" exponent="-1" scale="0" multiplier="1"/>
        <unit kind="second" exponent="-1" scale="0" multiplier="1"/>
      </listOfUnits>
    </unitDefinition>
  </listOfUnitDefinitions>
  <listOfCompartments>
    <compartment id="c1" units="litre" size="0.001" spatialDimensions="3" constant="true"/>
  </listOfCompartments>
  <listOfSpecies>
    <species id="S1" compartment="c1" initialConcentration="2.0"
              hasOnlySubstanceUnits="false" boundaryCondition="false" constant="false"/>
    <species id="S2" compartment="c1" initialConcentration="0.5"
              hasOnlySubstanceUnits="false" boundaryCondition="false" constant="false"/>
    <species id="X0" compartment="c1" initialConcentration="1.0"
              hasOnlySubstanceUnits="false" boundaryCondition="false" constant="false"/>
  </listOfSpecies>
  <listOfReactions>
    <reaction id="J1" reversible="false">
      <listOfReactants>
        <speciesReference species="X0" stoichiometry="1" constant="true"/>
      </listOfReactants>
      <listOfProducts>
        <speciesReference species="S1" stoichiometry="1" constant="true"/>
      </listOfProducts>
      <listOfModifier>
        <modifierSpeciesReference species="S2"/>
      </listOfModifier>
      <kineticLaw>
        <math xmlns="http://www.w3.org/1998/Math/MathML">
          <apply>
            <times/> <ci> k </ci> <ci> S2 </ci> <ci> X0 </ci> <ci> c1 </ci>
          </apply>
        </math>
        <listOfLocalParameters>
          <localParameter id="k" value="0.1" units="per_concent_per_time"/>
        </listOfLocalParameters>
      </kineticLaw>
    </reaction>
  </listOfReactions>
</model>
```
### 4.11.7 Mathematical interpretation of SBML reactions and kinetic laws

In SBML, *reactions* are the central mechanism for describing processes that change the quantities of species in a model. The *kinetic law* of an SBML reaction provides a quantitative description of the speed with which this happens. In this section, we provide an interpretation of SBML kinetic laws in the framework of a system of ordinary differential equations (ODEs). However, the choice of ODEs as the framework is only for exposition purposes here, in order to allow us to present a concrete mathematical expression of the model in terms that many readers will be familiar with; it is equally possible to translate a model into other frameworks, and some formulations, such as discrete stochastic systems, are indeed quite common.

#### Semantics of rate law and stoichiometry

The *stoichiometry* of a species *S* in a reaction describes the proportion, relative to other species participating in that reaction, of *S* involved in each reaction event. For example, in a reaction $S_1 + 2S_2 \rightarrow S_3$, twice as many entities of $S_2$ as entities of $S_1$ are involved each time a reaction event is counted. The value of the expression in the **KineticLaw**'s math element describes the *rate* at which the reaction takes place. The product of the reaction rate (of a given reaction) and the stoichiometry (of a given species in the reaction) describes the reaction's contribution to the rate of change of the species' quantity in the overall system.

It is important to make clear that a “kinetic law” in SBML is *not* identical to a traditional rate law. When modeling species as continuous amounts (e.g., concentrations), the rate laws used are traditionally expressed in terms of *concentration per time*. Unfortunately, this approach only works well in cases where certain assumptions hold. Three assumptions in particular are incompatible with generalized multicompartamental modeling; they are listed in Table 5 along with the problems they entail.

<table><caption>**Table 5:** Assumptions behind “traditional” rate laws, and the problems they imply for general multicompartamental modeling.</caption><thead><tr><td>Assumption</td><td>Problem</td></tr></thead><tbody><tr><td>All species that participate in a given reaction are located in one compartment</td><td>SBML must support reaction processes (e.g., transport) that move species between compartments</td></tr><tr><td>Compartments are three-dimensional volume containers</td><td>SBML must support models where reactions may take place at interfaces (e.g., 2-D membranes) between compartments, thus involving compartments with different dimensions</td></tr><tr><td>Compartment volumes are constant over time</td><td>SBML must support systems with compartments that can change size over time</td></tr></tbody></table>

A simple example can illustrate the problems that arise when describing reactions between multiple volumes using *concentration/time* units (which is to say, *amount/volume/time*). Suppose we have two species pools $S_1$ and $S_2$, with $S_1$ located in a compartment having volume $V_1$, and $S_2$ located in a compartment having volume $V_2$. Let the volume $V_2 = 3V_1$. Now consider a transport reaction $S_1 \rightarrow S_2$ in which the species $S_1$ is moved from the first compartment to the second. Assume we only want to model the overall effect, without getting into the molecular details (which might in reality involve such things as pores in a membrane between the compartments). Let us use the simplest type of chemical kinetics, in which the rate of the transport reaction is controlled by the activity of $S_1$ and this rate is equal to some constant $k$ times the activity of $S_1$. For the sake of simplicity, assume $S_1$ is in a diluted solution and thus that the activity of $S_1$ can be taken to be equal to its concentration $[S_1]$. The rate expression will therefore be $k \cdot [S_1]$, with $k$ having the unit $1/time$. Then:

$$ \frac{d[S_2]}{dt} = -\frac{d[S_1]}{dt} = k \cdot [S_1] $$

So far, this looks normal—until we consider the number of molecules of $S_1$ that disappear from the compartment of volume $V_1$ and appear in the compartment of volume $V_2$. The number of molecules of $S_1$ (call this $n_{S_1}$) is given by $[S_1] \cdot V_1$ and the number of molecules of $S_2$ (call this $n_{S_2}$) is given by $[S_2] \cdot V_2$. Since our volumes have
the relationship $V_2/V_1 = 3$, the relationship above implies that $n_{S_1} = k \cdot [S_1] \cdot V_1$ molecules disappear from the first compartment per unit of time and $n_{S_2} = 3 \cdot k \cdot [S_1] \cdot V_1$ molecules appear in the second compartment. In other words, we have created matter out of nothing!

The problem lies in the use of concentrations as the measure of what is transferred by the reaction, because concentrations depend on volumes and the scenario involves multiple unequal volumes. The problem is not limited to using concentrations or volumes; the same problem also exists when using density, i.e., mass/volume, as well as dependency on other spatial distributions (i.e., areas or lengths). What must be done instead is to consider the number of “items” being acted upon by a reaction process irrespective of their distribution in space (volume, area or length). An “item” in this context may be a molecule, particle, mass, or other “thing”, as long as the substance measurement is independent of the size of the space in which the items are located and the processes take place.

In multicompartmental models, to be able to specify a rate law only once and then use it unmodified in equations for different species, the rate law needs to be expressed in terms of an intensive property, that is, species quantity/time, rather than the extensive property typically used, species quantity/size/time. As a result, modelers and software tools in general cannot insert traditional textbook rate laws unmodified into the math element of a KineticLaw. The unusual term “kinetic law” was chosen to alert users to this difference.

## Constructing rate-of-change equations for the species

A consequence of the approach to “kinetic laws” discussed in the previous section is this: when constructing equations describing the time-rates of change of different species defined by an SBML model, the equations are assumed to be in terms of time-rates of changes to amounts, not concentrations (or more generally densities, i.e., amount per size of compartment). A kinetic law does not describe how often a reaction would take place in a compartment of unit size, but rather how often it takes place (per time unit) given the actual size of the compartment. The dimension of the kinetic law is therefore number of reaction events per time.

When constructing a system of equations dictating the rates of change of the species in an SBML model, we only need to consider species having attribute values **constant**=“false” and **boundaryCondition**=“false”, because as discussed in Section 4.6.6 on p. 51, these are the only species affected by the reactions in the model. (Other species not meeting these criteria may be affected by other SBML constructs, but here, we are focusing specifically on the implications of reactions.)

Assume now a model in which N species $S_1, S_2, ..., S_N$ having attribute values **constant**=“false” and **boundaryCondition**=“false” participate in M reactions $R_1, R_2, ..., R_M$. Let $v_{R_j}$ represent the rate or velocity of reaction $R_j$ as given by the formula in the math element of KineticLaw object for $R_j$. The unit of measurement associated with this rate expression is extent/time, where the extent and time units are specified by the extentUnits and timeUnits attributes on the Model object, respectively. Let stoich$_{S_i,R_j}$ represent the effective stoichiometry of species $S_i$ in reaction $R_j$. (By “effective stoichiometry”, we mean the number that results from taking the sum of the stoichiometry values of all references to $S_i$ in $R_j$’s listOfReactants and subtracting the sum of the stoichiometric values of all references to $S_i$ in $R_j$’s listOfProducts.) If $S_i$ is neither a reactant nor product in some reaction $R_x$, then stoich$_{S_i,R_x}$ = 0. Finally, let $n_{S_i}$ represent the amount of species $S_i$ in the model (and note that this value is not a concentration or density).

There are three possible cases to consider when constructing rate-of-change equations for the species:

1. No conversion factors defined. If neither the Species object for $S_i$ nor the Model object define values for their respective conversionFactor attributes, then the rate of change of the species amount is determined as follows (and note the implication that the unit of reaction extent should be identical to the unit in which the amount of species $S_i$ is measured):

$$ \frac{dn_{S_i}}{dt} = \sum_{j=1}^{M} \text{stoich}_{S_i, R_j} \cdot v_{R_j} $$

2. Global conversion factor defined. If the Model object instance defines a value for its conversionFactor attribute, and the Species object for $S_i$ does not define a value for its conversionFactor, then the global conversion factor is used to convert between the unit of reaction extent in the model and the
unit in which the amount of species $S_i$ is measured. Let $c_{model}$ represent the value of the parameter object identified by the **conversionFactor** attribute value on **Model** (see Section 4.2.6 on p. 39). The formula for the rate of change of $S_i$'s amount then becomes the following:

$$ \frac{dn_{S_i}}{dt} = c_{model} \cdot \sum_{j=1}^{M} \text{stoich}_{S_i, R_j} \cdot v_{R_j} $$

3. Conversion factor defined for the species. If the **Species** object instance for $S_i$ defines a value for its **conversionFactor** attribute, then this factor is used to convert between the unit of reaction extent in the model and the unit in which the amount of species $S_i$ is measured. (The factor defined by the individual species overrides any value that may exist for the **Model** object's **conversionFactor**.) Let $c_{S_i}$ represent the value of the parameter object identified by $S_i$'s **conversionFactor** attribute value (see Section 4.6.7 on p. 52). The formula for the rate of change of $S_i$'s amount then becomes the following:

$$ \frac{dn_{S_i}}{dt} = c_{S_i} \cdot \sum_{j=1}^{M} \text{stoich}_{S_i, R_j} \cdot v_{R_j} $$

In Section 8.2.4, we present some recommendations for how to encode rate laws and models in SBML.

### Species with negative or zero values

In many models, a **Species** will represent an amount of a physical entity. In those cases, the level of that species should never go negative. Similarly, many reactions represent physical conversion of physical entities. In those cases, if the entities to be converted have reached a level of zero, no conversion can take place. However, in both cases, it is the duty of the modeler to ensure that the **KineticLaw** of the **Reaction** is encoded in such a way that these physical restrictions are obeyed. Other systems and models use the **Species** construct to represent quantities that can go negative, such as charge. Thus, mathematically, if a model dictates that a **Species** level goes negative, or if a **Reaction** process acts on zero- or negative-level **Species**, proper interpretation of that model requires that to happen.

### 4.11.8 Use of reaction identifiers in mathematical expressions

The value of the **id** attribute of a **Reaction** can be used as the content of a **ci** element in MathML formulas elsewhere in the model. Such a **ci** element or symbol represents the rate of the given reaction as given by the reaction's **KineticLaw** object. As explained above, the unit of measurement associated with the mathematical expression in a **KineticLaw** object is *extent/time*; therefore, this is the unit associated with the **id** attribute of a **Reaction** when the identifier appears in MathML expressions.

A **KineticLaw** object in effect forms an assignment statement assigning the evaluated value of the **math** element to the symbol value contained in the **Reaction** **id** attribute. No other object can assign a value to such a reaction symbol; i.e., the **variable** or **symbol** attributes of **InitialAssignment**, **RateRule**, **AssignmentRule** and **EventAssignment** objects cannot contain the value of a **Reaction** **id** attribute.

The combined set of **InitialAssignment**, **AssignmentRule** and **KineticLaw** objects form a set of assignment statements that should be considered as a whole. The combined set of assignment rules 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 statements and directed arcs exist for each occurrence of a symbol in an assignment statement **math** element. The directed arcs start from the statement defining the symbol to the statements that contain the symbol in their **math** elements. Such a graph must be acyclic.) Examples of valid and invalid set of assignment statements are given in Section 4.9.5 on p. 64.

## 4.12 Events

**Model** has an optional list of **Event** objects that describe the time and form of instantaneous, discontinuous state changes in the model. For example, an event may describe that a certain species quantity in a model is halved when another species' quantity exceeds a given threshold value.
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. Conceptually, the operation of every event is divided into two phases (even when it is not delayed): the first phase when the event is *triggered* and the second phase when the event is *executed*. The object classes **Event**, **Trigger**, **Delay**, **Priority**, **EventAssignment** and **ListOfEventAssignments** are derived from **SBase** (see Section 3.2 on p. 14) and are defined in Figure 20. An example of a model which uses events is given in Section 7 on p. 113.

<figure><img src="image_23.png" /><figcaption>**Figure 20:** The definitions of **Event**, **Trigger**, **Delay**, **Priority**, **EventAssignment**, and **ListOfEventAssignments**.</figcaption></figure>
### 4.12.1 Event

In addition to the attributes and children it inherits from **SBase**, an **Event** definition has one required attribute, **useValuesFromTriggerTime**, and five optional subobjects, **Trigger**, **Delay**, **Priority**, **ListOfEventAssignments**, and **EventAssignment**. These various features of **Event** are described below.

**The id attribute**

**Event** inherits an optional **id** attribute of type **SId** from **SBase**. The identifier of an **Event** has no mathematical meaning in an SBML Level 3 Version 2 Core model.

**The optional sboTerm attribute on Event**

**Event** inherits an optional **sboTerm** attribute of type **SBOTerm** from **SBase** (see Section 3.1.12 on p. 14 and Section 5 on p. 91). When this attribute is present on a given **Event** object instance, its value should be an SBO identifier belonging to the branch for type **Event** indicated in Table 6 on p. 98. The relationship is of the form "the event is-a X", where X is the SBO term. The term chosen should be the most precise (narrow) one that captures the role of the event in the model.

As discussed in Section 5 on p. 91, SBO labels are optional information on a model. Applications are free to ignore **sboTerm** values. A model must be interpretable without the benefit of SBO labels.

**The useValuesFromTriggerTime attribute**

The possibility of defining an optional **Delay** within **Event**, and the potential for multiple simultaneously-triggered events, means there are two times to consider when interpreting an event: the moment at which the event *triggered*, and the moment at which its assignments are *executed*. (If a **Delay** subobject is present, these moments are separated by simulation time. If multiple events are triggered simultaneously, these moments are separated by the sequential execution of the event assignments.) Similarly, it is also possible to distinguish between the moment at which the mathematical expression of an **EventAssignment** object is evaluated, and the moment at which this value is assigned to the entity referenced by the **EventAssignment**'s **variable** attribute. A model could intend the **EventAssignment** expression to be evaluated either at the moment the event is triggered, or at the moment the event assignments are executed. (In the former case, a model interpreter would have to save the calculated values until the moment of execution.)

The attribute **useValuesFromTriggerTime** allows a model to indicate the moment at which the event's assignments are to be evaluated. A value of **"true"** indicates the values assignments are to be computed at the moment the event is *triggered*. Conversely, **useValuesFromTriggerTime=**"**false**" means the assignments are to be computed at the moment the event is *executed*. The attribute has no default value.

### 4.12.2 Trigger

As shown in Figure 20 on the preceding page, an **Event** object may contain exactly one object of class **Trigger**. This object in turn must contain two attributes, **persistent** and **initialValue**, and may contain a MathML **math** element. The expression in the **math** element will be interpreted as a value of type **boolean**. The exact moment at which this expression evaluates to **"true"** during a simulation is taken to be the time point when the **Event** is *triggered*.

An event only triggers when the expression within its **Trigger** object makes the transition in value from **"false"** to **"true"**. The event will trigger again at any subsequent moments when the trigger makes the transition from **"false"** to **"true"**; in other words, an event can trigger multiple times during a simulation if its trigger condition makes the transition from **"false"** to **"true"** more than once. The behavior at the very start of simulation time (i.e., $t = 0$, where $t$ stands for time) is determined in part by the **boolean** flag **initialValue**, discussed below.

If an instance of an **Event** contains no **Trigger** child, that **Event** has no way of being triggered or executed in a model according to the SBML Level 3 Version 2 Core specification. The **Event** may nevertheless be present in a model as part of (e.g.) a partially unknown system, for annotation purposes, or as part of constructs defined by an SBML Level 3 package.
A **Trigger** with no **math** child leaves undefined when the corresponding **Event** will trigger. The absence of a **math** element is permitted because it is possible for SBML Level 3 packages to add constructs that extend **Trigger** and define how a value is to be computed. In the absence of such constructs, the event is never triggered. A simulator encountering this situation may choose to produce a warning.

### The id attribute on Trigger

**Trigger** inherits an optional **id** attribute from **SBase**, of type **SId**. The identifier has no mathematical meaning in an SBML Level 3 Version 2 Core model.

### The persistent attribute on Trigger

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 (see Section 4.12.3 on the next page), SBML does not mandate a particular ordering of event execution in the case of simultaneous events (see Section 4.12.7 on p. 89). 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.

### The initialValue attribute on Trigger

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 optional sboTerm attribute on Trigger

**Trigger** inherits an optional **sboTerm** attribute of type **SBOTerm** from its parent class **SBase** (see Section 3.1.12 and Section 5). The value given to this attribute should be an SBO identifier belonging to the branch for type **Trigger** indicated in Table 6 on p. 98. The relationship is of the form “the trigger *is-a* X”, where X is
the SBO term. The term chosen should be the most precise (narrow) one that captures the role of the trigger in the model.

As discussed in Section 5 on p. 91, SBO labels are optional information on a model. Applications are free to ignore **sboTerm** values. A model must be interpretable without the benefit of SBO labels.

### 4.12.3 Priority

As shown in Figure 20 on p. 80, an **Event** object can contain an optional **Priority** subobject. The **Priority** object class, 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.

A **Priority** with no **math** child leaves the priority of the event undefined. The absence of a **math** element is permitted because it is possible for SBML Level 3 packages to add constructs that extend **Priority** and define how a value is to be computed. In the absence of such constructs, the event behaves as if it does not have a priority. A simulator encountering this situation may choose to produce a warning.

#### The interpretation of priorities on events in a model

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 this SBML 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. See Section 4.12.2 on the preceding page for more information about the attribute **persistent**.

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.)

Section 4.12.7 on p. 89 includes additional discussion of these topics.

### Evaluation of Priority expressions

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. Section 8.2.5 on p. 153 provides further discussion about implementing support for events.

### Units of Priority object's mathematical expressions

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.

### The id attribute on Priority

**Priority** inherits an optional **id** attribute from **SBase**, of type **SId**. The identifier has no mathematical meaning in an SBML Level 3 Version 2 Core model.

### The optional sboTerm attribute on Priority

**Priority** inherits an optional **sboTerm** attribute of type **SBOTerm** from its parent class **SBase** (see Section 3.1.12 and Section 5). When a value is given to this attribute in a **Priority** instance, it should be an SBO identifier belonging to the branch for type **Priority** indicated in Table 6 on p. 98. The relationship is of the form "the priority is-a X", where X is the SBO term. The term chosen should be the most precise (narrow) one that captures the role of the priority in the model.

As discussed in Section 5 on p. 91, SBO labels are optional information on a model. Applications are free to ignore **sboTerm** values. A model must be interpretable without the benefit of SBO labels.

### 4.12.4 Delay

As shown in Figure 20 on p. 80, an **Event** object can contain an optional **Delay** object. The **Delay** class is derived from **SBase** and contains a mathematical formula stored in **math**. The formula is used to compute the length of time between when the event has *triggered* and when the event's assignments (see below) are actually *executed*. If no delay is present on a given **Event**, no delay is defined for that event.

Similarly, a **Delay** with no **math** child leaves the delay of the event undefined. The absence of a **math** element is permitted because it is possible for SBML Level 3 packages to add constructs that extend **Delay** and define how a value is to be computed. In the absence of such constructs, the event is considered to execute as if it had no **Delay**. A simulator encountering this situation may choose to produce a warning.
The expression in the **Delay** object's **math** element 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!).

## Units of delay expressions

The unit associated with the value of a **Delay** object's **math** expression should match the model's unit of *time* (see Section 4.2.3 on p. 38). Note that, as in other cases of MathML expressions in SBML, units are *not* automatically predefined or assumed. As discussed in Section 3.4.12 on p. 31, expressions containing only literal numbers and/or **Parameter** objects without declared units are considered to have unspecified units. In such cases, the correspondence between the needed entity units and the (unknown) unit for the **Delay**'s **math** expression cannot be proven, and while such expressions are not considered inconsistent, all that can be assumed by model interpreters (whether software or human) is that the units *may* be consistent.

The following **Event** example fragment helps illustrate this:

```xml
<model timeUnits="second" ...>
  ...
  <listOfEvents>
    <event useValuesFromTriggerTime="true">
      ...
      <delay>
        <math xmlns="http://www.w3.org/1998/Math/MathML">
          <cn> 10 </cn>
        </math>
      </delay>
      ...
    </event>
    <listOfEvents>
      ...
    </listOfEvents>
  </model>
```

Note that the `<cn> 10 </cn>` within the mathematical formula has no specified unit attached to it. The model is not invalid because of this, but a recipient of the model may justifiably be concerned about what “10” really means. (Ten seconds? What if the global unit of time on the model were changed from seconds to milliseconds? Would the modeler remember to change “10” to “10 000”?) A better approach would be to declare the unit explicitly, as in the following example:

```xml
<model timeUnits="second" ...>
  ...
  <listOfEvents>
    <event useValuesFromTriggerTime="true">
      ...
      <delay>
        <math xmlns="http://www.w3.org/1998/Math/MathML">
          <nsbml:sbml="http://www.sbml.org/sbml/level3/version2/core">
            <cn sbml:units="second"> 10 </cn>
          </math>
        </delay>
      </delay>
      ...
    </event>
    <listOfEvents>
      ...
    </listOfEvents>
  </model>
```

While this approach will not solve the problem of updating the value if the model's global unit of time is changed, it will at least inform readers of the intended duration of the delay itself as well as make it possible for software tools to potentially detect unit inconsistencies if the tools can perform unit analysis.

Another, different approach is to define a global **Parameter** object for the time delay (with an appropriate unit attached), and to replace the **cn** element above with a **ci** element containing the parameter's identifier. This has advantages because **Parameter** objects can have annotations and SBO terms associated with them.
### The id attribute on Delay

Delay inherits an optional id attribute from SBase, of type SId. The identifier has no mathematical meaning in an SBML Level 3 Version 2 Core model.

### The optional sboTerm attribute on Delay

Delay inherits an optional sboTerm attribute of type SBOTerm from its parent class SBase (see Section 3.1.12 and Section 5). When a value is given to this attribute in a Delay instance, it should be an SBO identifier belonging to the branch for type Delay indicated in Table 6 on p. 98. The relationship is of the form “the delay is-a X”, where X is the SBO term. The term chosen should be the most precise (narrow) one that captures the role of the delay in the model.

As discussed in Section 5 on p. 91, SBO labels are optional information on a model. Applications are free to ignore sboTerm values. A model must be interpretable without the benefit of SBO labels.

## 4.12.5 EventAssignment

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 may have zero or more eventAssignment elements of class EventAssignment. The object class EventAssignment has one required attribute, variable, and the optional element, math. Being derived from SBase, it also has all the usual attributes and elements of its parent class.

An “event assignment” has effect when the event is executed. (As noted above, the operation of event is divided conceptually into two phases: the first phase when the event is triggered and the second phase when the event is executed.) See Section 4.12.7 on p. 89 below for more information about events and event assignments.

### The variable attribute

The EventAssignment required attribute variable has type SIdRef. The value of the attribute must be the identifier of an object in the SId namespace of the model with mathematical meaning and the ability to be assigned. In SBML Level 3 Core, the permitted objects classes are Compartment, Species, SpeciesReference, and Parameter. The set also includes SBML Level 3 package objects with identifiers in the SId namespace of the model and mathematical meaning defined to allow assignment.

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. For components defined by SBML Level 3 Core, this means that 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 variable attribute must not have its constant attribute set to “true”. (Constants cannot be affected by events.)

* The variable attribute must not contain the identifier of a reaction; in core, only species, species references, compartment and parameter values may be set by an Event.

* The value of every variable attribute must be unique among the set of EventAssignment objects within a given Event instance. In other words, a single event cannot have multiple EventAssignment children assigning the same variable. (All of them would be performed at the same time, when that particular Event triggers, resulting in indeterminacy.) Separate Event instances can refer to the same variable.

* A variable cannot be assigned a value in an EventAssignment object instance and also be assigned a value by an AssignmentRule, i.e., the value of the variable attribute in an EventAssignment instance cannot be the same as the value of a variable attribute in an AssignmentRule instance. (Assignment rules hold at all times, therefore it would be inconsistent to also define an event that reassigns the value of the same variable.)
If the **variable** attribute of an **EventAssignment** object references an object in an SBML namespace that is not recognized 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 must not be assigned if the interpreter cannot understand the package. If an interpreter cannot establish whether a referenced object is missing from the model or instead is defined in an SBML namespace not recognized by the interpreter, it may produce a warning to the user. (The latter situation can 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 **variable** is always the time at which the **Event** is executed, not when it is triggered. The timing is controlled by the optional **Delay**. The time of assignment is not affected by the **Event** attribute `useValuesFromTriggerTime`—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 optional `sboTerm` attribute on `EventAssignment`

**EventAssignment** inherits an optional `sboTerm` attribute of type `SBOTerm` from its parent class `SBase` (see Section 3.1.12 on p. 14 and Section 5 on p. 91). When a value is given to this attribute in a **EventAssignment** instance, it should be an SBO identifier belonging to the branch for type **EventAssignment** indicated in Table 6 on p. 98. The relationship is of the form "the event assignment *is-a* X", where X is the SBO term. The term chosen should be the most precise (narrow) one that captures the role of the event assignment in the model.

As discussed in Section 5 on p. 91, SBO labels are optional information on a model. Applications are free to ignore `sboTerm` values. A model must be interpretable without the benefit of SBO labels.

### The optional `id` attribute on `EventAssignment`

**EventAssignment** inherits an optional `id` attribute from `SBase`, of type `SId`. The identifier has no mathematical meaning in an SBML Level 3 Version 2 Core model.

### EventAssignment's math

The **math** element contains a MathML expression that defines the new value to be given to the object identified by the **EventAssignment** attribute **variable**.

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** attributes in the **EventAssignment**'s **math** expression are the values they have at the point when the event *executed*.

An **EventAssignment** with no **math** child leaves undefined what assignment is to be made to the corresponding **symbol**. The absence of a **math** element is permitted because it is possible for SBML Level 3 packages to add constructs that extend **EventAssignment** and define how a value is to be computed. In the absence of any such construct, no assignment is carried out when there is no **math** element. This leaves the model unchanged: any element that had a value will continue to have that value; any element whose value was undefined will continue to have its value undefined. A simulator encountering this situation may choose to produce a warning. No other validation rules are affected by the absence of a **math** child: it is still invalid to have an **EventAssignment** and an **AssignmentRule** that assign to the same model element, for example.

### Units of the math formula in EventAssignment

In all cases, as would be expected, the unit of measurement associated with value of the formula contained in the **math** element of an **EventAssignment** object should be consistent with the unit associated with the object identified by the **variable** attribute value. More precisely, for objects defined by SBML Level 3 Core:
* In the case of a species, an **EventAssignment** sets the referenced species' quantity (*concentration* or *amount*) to the value determined by the formula in **math**. The unit associated with the value produced by the **math** formula should be equal to the unit associated with the species' quantity. (See Section 4.6.5 on p. 51 for an explanation of how a species' quantity is determined.)

* 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 **math**. 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 **math**. The unit associated with the value produced by the **math** formula should be the same as that specified for the compartment's size. (See Section 4.5.4 on p. 48 for more.)

* In the case of a parameter, an **EventAssignment** sets the parameter's value to the value of the formula in **math**. The unit associated with the value produced by the **math** formula should be the same as parameter's **units** attribute value. (Section 4.7.3 on p. 55 for more information about parameter units.)

* In the case of an object from an SBML Level 3 package, an **EventAssignment** 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).

Note that the formula in **math** has no assumed unit of measurement associated with it. The consistency of the units between the formula and the entity affected by the assignment should be established explicitly.

### 4.12.6 Example Event definitions

The following is an example of an event. This structure makes the assignment $k_2 = 0$ when $P_1 \le P_2$:

```xml
<model>
  ...
  <listOfUnitDefinitions>
    <unitDefinition id="per_second">
      <listOfUnits>
        <unit kind="second" exponent="-1" multiplier="1" scale="0"/>
      </listOfUnits>
    </unitDefinition>
  </listOfUnitDefinitions>
  ...
  <listOfParameters>
    <parameter id="k2" value="0.05" units="per_second" constant="false"/>
    <parameter id="k2reset" value="0.0" units="per_second" constant="true"/>
  </listOfParameters>
  ...
  <listOfEvents>
    <event useValuesFromTriggerTime="true">
      <trigger initialValue="false" persistent="true">
        <math xmlns="http://www.w3.org/1998/Math/MathML">
          <apply> <leq/> <ci> P_1 </ci> <ci> P_2 </ci> </apply>
        </math>
      </trigger>
      <listOfEventAssignments>
        <eventAssignment variable="k2">
          <math xmlns="http://www.w3.org/1998/Math/MathML">
            <ci> k2reset </ci>
          </math>
        </eventAssignment>
      </listOfEventAssignments>
    </event>
  </listOfEvents>
</model>
```

A complete example of a model using events is given in Section 7.11 on p. 135.
### 4.12.7 Detailed semantics of events

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 $t_1$ and $t_2$. The **EventAssignment** within the **Event** object will have effect at $t_1 + d$ and $t_2 + d$ irrespective of the relative times of $t_1$ and $t_2$. For example, events can "overlap" so that $t_1 < t_2 < t_1 + d$ still causes an event assignments to occur at $t_1 + d$ and $t_2 + 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 the assignments from a given event in order to account for the possibility that the assignments cause 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** has the value **false** must have its trigger expression reevaluated continuously between when the event has been 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. (See also Section 4.12.3 on p. 83.)

* 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**. (See Section 4.12.3 on p. 83.)
* 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*.
# 5 The Systems Biology Ontology and the sboTerm attribute

The values of **id** attributes on SBML components allow the components to be cross-referenced within a model. The values of **name** attributes on SBML components provide the opportunity to assign them meaningful labels suitable for display to humans (Section 3.3 on p. 18). The specific identifiers and labels used in a model necessarily must be unrestricted by SBML, so that software and users are free to pick whatever they need. However, this freedom makes it more difficult for software tools to determine, without additional human intervention, the semantics of models more precisely than the semantics provided by the SBML object classes defined in other sections of this document. For example, there is nothing inherent in a parameter with identifier “k” that would indicate to a software tool it is a first-order rate constant (if that’s what “k” happened to be in some given model). However, one may need to convert a model between different representations (e.g., Henri-Michaelis-Menten vs. elementary steps), or to use it with different modeling approaches (discrete or continuous). One may also need to relate the model components with other description formats such as SBGN (http://www.sbgn.org/) using deeper semantics. Although an advanced software tool might be able to deduce the semantics of some model components through detailed analysis of the kinetic rate expressions and other parts of the model, this quickly becomes infeasible for any but the simplest of models.

An approach to solving this problem is to associate model components with terms from carefully curated controlled vocabularies (CVs). This is the purpose of the optional **sboTerm** attribute provided on the SBML class **SBase**. The **sboTerm** attribute always refers to terms belonging to the Systems Biology Ontology (SBO, (Courtot et al., 2011)). In this section, we discuss the **sboTerm** attribute, SBO, the motivations and theory behind their introduction, and guidelines for their use.

SBO is not part of SBML; it is being developed separately, to allow the modeling community to evolve the ontology independently of SBML. However, the terms in the ontology are being designed keeping SBML components in mind, and are classified into subsets that can be directly related with SBML components such as reaction rate expressions, parameters, and a few others, see below. The use of **sboTerm** attributes is optional, and the presence of **sboTerm** on an element does not change the way the model is *interpreted*. Annotating SBML elements with SBO terms adds additional semantic information that may be used to *convert* the model into another model, or another format. Although SBO support provides an important source of information to understand the meaning of a model, software does not need to support **sboTerm** to be considered SBML-compliant.

## 5.1 Principles

Labeling model components with terms from shared controlled vocabularies allows a software tool to identify each component using identifiers that are not tool-specific. An example of where this is useful is the desire by many software developers to provide users with meaningful names for reaction rate equations. Software tools with editing interfaces frequently provide these names in menus or lists of choices for users. However, without a standardized set of names or identifiers shared between developers, a given software package cannot reliably interpret the names or identifiers of reactions used in models written by other tools.

The first solution that might come to mind is to stipulate that certain common reactions always have the same name (e.g., “Michaelis-Menten”), but this is simply impossible to do: not only do humans often disagree on the names themselves, but it would not allow for correction of errors or updates to the list of predefined names except by issuing new releases of the SBML specification—to say nothing of many other limitations with this approach. Moreover, the parameters and variables that appear in rate expressions also need to be identified in a way that software tools can interpret mechanically, implying that the names of these entities would also need to be regulated.

The Systems Biology Ontology provides terms for identifying most elements of SBML. The relationship implied by an **sboTerm** on an SBML model component is “is-a” between the characteristic of the component meant to be described by SBO on this element and the SBO term identified by the value of the **sboTerm**. By adding SBO term references on the components of a model, a software tool can provide additional details using shared vocabularies that can enable *other* software tools to recognize precisely what the component is meant to be. Those tools can then act on that information. For example, if the SBO identifier **SBO:0000049** is assigned to the concept of “first-order irreversible mass-action kinetics, continuous framework”, and a
given **KineticLaw** object in a model has an **sboTerm** attribute with this value, then regardless of the identifier and name given to the reaction itself, a software tool could use this to inform users that the reaction is a first-order irreversible mass-action reaction. This kind of reverse engineering of the meaning of reactions in a model would be difficult to do otherwise, especially for more complex reaction types.

The presence of SBO labels on **Compartment**, **Species**, and **Reaction** objects in SBML can help map those entities to equivalent concepts in other standards, such as (but not limited to) BioPAX (https://www.biopax.org/), PSI-MI (http://www.psidev.info/index.php?q=node/60), or the Systems Biology Graphical Notation (SBGN, http://www.sbgn.org/). Such mappings can be used in conversion procedures, or to build interfaces, with SBO becoming a kind of “glue” between standards of representation.

The presence of the label on a kinetic expression can also allow software tools to make more intelligent decisions about reaction rate expressions. For example, an application could recognize certain types of reaction formulas as being ones it knows how to solve with optimized procedures. The application could then use internal, optimized code implementing the rate formula indexed by identifiers such as `SBO:0000049` ("mass action rate law for first order irreversible reactions, continuous scheme") appearing in SBML models.

Finally, SBO labels may be very valuable when it comes to model integration, by helping identify interfaces, convert mathematical expressions and parameters etc.

Although the use of SBO can be beneficial, it is critical to keep in mind that the presence of an **sboTerm** value on an object *must not change the fundamental mathematical meaning* of the model. An SBML model must be defined such that it stands on its own and does not depend on additional information added by SBO terms for a correct mathematical interpretation. SBO term definitions will not imply any alternative mathematical semantics for any SBML object labeled with that term. Two important reasons motivate this principle. First, it would be too limiting to require all software tools to be able to understand the SBO vocabularies in addition to understanding SBML. Supporting SBO is not only additional work for the software developer; for some kinds of applications, it may not make sense. If SBO terms on a model are optional, it follows that the SBML model *must* remain unambiguous and fully interpretable without them, because an application reading the model may ignore the terms. Second, we believe allowing the use of **sboTerm** to alter the mathematical meaning of a model would allow too much leeway to shoehorn inconsistent concepts into SBML objects, ultimately reducing the interoperability of the models.

## 5.2 Using SBO and sboTerm

The **sboTerm** attribute data type is always **SBOTerm**, defined in Section 3.1.12 on p. 14. When present in a given model object instance, the attribute's value must be an identifier that refers to a single SBO term that best defines the entity encoded by the SBML object in question. An example of the type of relationship intended is: *the KineticLaw in reaction R1 is a first-order irreversible mass action rate law*.

Note the careful use of the words “defines” and “entity encoded by the SBML object” in the paragraph above. As mentioned, the relationship between the SBML object and the URI is:

> The “thing” encoded by this SBML object has a characteristic that is an instance of the “thing” represented by the referenced SBO term.

The characteristic relevant for each SBML object is described in the second column of Table 6 on p. 98.

### 5.2.1 The structure of the Systems Biology Ontology

The goal of SBO labeling for SBML is to clarify to the fullest possible extent the nature of each element in a model. The approach taken in the Systems Biology Ontology begins with a hierarchically-structured set of controlled vocabularies with seven main divisions: (1) physical entity representation, (2) participant role, (3) systems description parameter, (4) modeling framework, (5) mathematical expression, (6) occurring entity representation, and (7) metadata representation. Figure 21 on the following page illustrates the highest level of SBO.

Each of the seven branches of Figure 21 on the next page has a hierarchy of terms underneath them. At this time, we can only begin to list some initial concepts and terms in SBO; what follows is not meant to be
complete, comprehensive or even necessarily consistent with future versions of SBO. It reflects SBO as it existed in December, 2015. The web site for SBO (http://biomodels.net/sbo/) should be consulted for the current version of the ontology. Section 5.4.1 on p. 98 describes how the impact of SBO changes on software applications is minimized.

<figure><img src="image_24.png" /><figcaption>**Figure 21:** The seven controlled vocabularies (CVs) that make up the main branches of SBO.</figcaption></figure>

Figure 22 shows the structure for the *physical entity representation* branch, which reflects the hierarchical groupings of the types of entities that can be represented by a **Compartment** or **Species** object. Note that the values taken by the **sboTerm** attribute on those elements should refer to SBO terms belonging to the *material entity* branch, so as to distinguish whether the element represents a macromolecule, a simple chemical, etc. Indeed, this information remains valid for the whole model. The term should not belong to the *functional entity* branch, representing the function of the entity within a certain functional context. If one wants to use this information, one should refer to the SBO terms using a controlled RDF annotation instead (Section 6 on p. 100), carefully choosing the qualifiers (Section 6.5 on p. 103) to reflect the fact that a given **Species** object, for instance, can fulfill different functions within a given model (e.g., EGF receptor is a receptor and an enzyme).

<figure><img src="image_25.png" /><figcaption>**Figure 22:** Partial expansion of some of the terms in the *entity* branch of SBO.</figcaption></figure>

Figure 23 shows the structure for the *participant role* branch, also grouping the concepts in a hierarchical manner. For example, in reaction rate expressions, there are a variety of possible modifiers. Some classes of modifiers can be further subdivided and grouped. All of this is easy to capture in the ontology. As more agreement is reached in the modeling community about how to define and name modifiers for different cases, the ontology can grow to accommodate it.

<figure><img src="image_26.png" /><figcaption>**Figure 23:** Partial expansion of some of the terms in the *participant role* branch of SBO.</figcaption></figure>
The controlled vocabulary for quantitative parameters is illustrated in Figure 24. Note the separation of *kinetic constant* into separate terms for unimolecular, bimolecular, etc. reactions, as well as for forward and reverse reactions. The need to have separate terms for forward and reverse rate constants arises in reversible mass-action reactions. This distinction is not always necessary for all quantitative parameters; for example, there is no comparable concept for the Michaelis constant. Another distinction for some quantitative parameters is decomposition into different versions based on the modeling framework being assumed. For example, different terms for continuous and discrete formulations of kinetic constants represent specializations of the constants for particular simulation frameworks. Not all quantitative parameters will need to be distinguished along this dimension.

<figure><img src="image_27.png" /><figcaption>**Figure 24:** *Partial expansion of some of the terms in the quantitative parameter branch.*</figcaption></figure>

The terms of the SBO quantitative systems description parameter branch contain mathematical formulas that are encoded using MathML 2.0; these formulas define the parameter value using other SBO parameters. The main use of this approach is to avoid listing all the variants of a mathematical expression, escaping a combinatorial explosion.

The *modeling framework* controlled vocabulary is needed to elucidate how to simulate a mathematical expression used in models. Figure 25 illustrates the structure of this branch, which is at this point fairly simple, but we expect that more terms will evolve in the future.

<figure><img src="image_28.png" /><figcaption>**Figure 25:** *Partial expansion of some of the terms in the modeling framework branch.*</figcaption></figure>

The *mathematical expression* vocabulary encompasses the various mathematical expressions that constitute a model. Figure 26 on the next page illustrates a portion of the hierarchy. Rate law or conservation law formulas are part of the mathematical expression hierarchy, and subdivided by successively more refined distinctions until the leaf terms represent precise statements of common reaction or rule types. Other types of mathematical expressions may be included in the future in order to be able to further characterize mathematical components of a model, such as initial assignments, assignment rules, rate rules, algebraic rules, constraints, and event triggers and assignments.

The leaf terms of the mathematical expression branch contain the mathematical formulas encoded using MathML 2.0. There are many potential uses for this. One is to allow a software application to obtain the formula corresponding to a term and use it as the basis of an expression to insert into a model. In effect, the formulas given in the CV act as templates for what to put into an SBML construct such as **KineticLaw** or
<figure><img src="image_29.png" /><figcaption>**Figure 26:** *Partial expansion of some of the terms in the mathematical expression branch.*</figcaption></figure>

**Rule.** The MathML definition also acts as a precise statement about the rate law in question. In particular, it carries information about the modeling framework to use in order to interpret the formula. Some of the non-leaf terms also contain formulas encoded using MathML 2.0. In that case, the formulas contained in the children terms are specific versions of the formula contained in the parent term. Those formulas may be generic, containing MathML constructs not yet supported by SBML, and need to be expanded into the MathML subset allowed in SBML before they can be used in conjunction with SBML models.

To make this discussion concrete, here is an example definition of an entry in the SBO rate law hierarchy at the time of this writing. This term represents second-order, irreversible, mass-action rate laws with one reactant, formulated for use in a continuous modeling framework:

ID: SBO:0000052

Name: mass-action rate law for second-order irreversible reactions, one reactant, continuous scheme

Definition: Reaction scheme where the products are created from the reactants and the change of a product quantity is proportional to the product of reactant activities. The reaction scheme does not include any reverse process that creates the reactants from the products. The change of a product quantity is proportional to the square of one reactant quantity. It is to be used in a reaction modeled using a continuous framework.

Parent(s):

SBO:0000050: mass-action rate law for second-order irreversible reactions, one reactant (is-a).

SBO:0000163: mass-action rate law for irreversible reactions, continuous scheme (is-a).

MathML:

<math xmlns="http://www.w3.org/1998/Math/MathML">
<semantics definitionURL="http://biomodels.net/sbo/#SBO:0000062">
<lambda>
<bvar><ci definitionURL="http://biomodels.net/sbo/#SBO:0000036">k</ci></bvar>
<bvar><ci definitionURL="http://biomodels.net/sbo/#SBO:0000509">R</ci></bvar>
<apply>
<times/>
<ci>k</ci>
<ci>R</ci>
<ci>R</ci>
</apply>
</lambda>
</semantics>
</math>
In the MathML definition of the term shown above, the bound variables in the `lambda` expression are tagged with references to terms in the SBO *systems description parameter* branch (for `k` and `R`). This makes it possible for software applications to interpret the intended meanings of the parameters in the expression. This also permits to convert an expression into another, by using the MathML 2.0 formula contained in the SBO terms associated with the parameters.

The *occurring entity representation* branch of SBO defines types of biological processes, events or relationship involving entities. It lists the types of biochemical reactions, such as binding, conformational transition, or cleavage, and also the different controls that modify a biochemical reaction, such as inhibition, catalysis, etc.

<figure><img src="image_30.png" /><figcaption>**Figure 27:** Partial expansion of some of the terms in the occurring entity representation branch.</figcaption></figure>

One of the goals of SBO is to permit a tool to traverse up and down the hierarchy in order to find equivalent terms in different frameworks. The hope is that when a software tool encounters a given rate formula in a model, the formula will be a specific form (say, "mass-action rate law, second order, one reactant, for discrete simulation"), but by virtue of the consistent organization of the reaction rate CV into framework-specific definitions, and the declaration of every parameters involved in each expression, the tool should in principle be able to determine the definitions for other frameworks (say, "mass-action rate law, second order, one reactant for continuous simulation"). If the software tool is designed for continuous simulation and it encounters an SBML model with rate laws formulated for discrete simulation, it could in principle look up the rate laws' identifiers in the CV and search for alternative definitions intended for discrete simulation. And of course, the converse is true, for when a tool designed for discrete simulation encounters a model with rate laws formulated for continuous simulation.

<figure><img src="image_31.png" /><figcaption>**Figure 28:** Current expansion of the terms in the annotation branch of SBO (under metadata representation).</figcaption></figure>
The controlled vocabulary for annotations is illustrated in Figure 28 on the preceding page, the single child of the *metadata representation* branch of SBO. As this branch is for annotating annotations themselves, its branches cannot usually be used for *SBase*-derived objects, as those generally depict basic model information, and not annotations of that model. However, there are packages which may be able to use this branch of SBO: the “*port*” element exactly corresponds to the *Port* class from the SBML Level 3 Hierarchical Model Composition package, for example.

### 5.2.2 Tradeoffs in using SBO terms

The SBO-based approach to annotating SBML components with controlled terms has the following strengths:

1. The syntax is minimally intrusive and maximally simple, requiring only one string-valued attribute.

2. It supports a significant fraction of what SBML users have wanted to do with controlled vocabularies.

3. It does not interfere with any other scheme. The more general annotation-based approach described in Section 6 on p. 100 can still be used simultaneously in the same model.

The scheme has the following weaknesses:

1. An object can only have one **sboTerm** attribute; therefore, it can only be related to a single term in SBO. (This also impacts the design of SBO: it must be structured such that a class of SBML elements can logically only be associated with one class of terms in the ontology.)

2. The only relationship that can be expressed by **sboTerm** is “is a”. It is not possible to represent different relationships (known as *verbs* in ontology-speak). This limits what can be expressed using SBO.

The weaknesses are not shared by the annotation scheme described in Section 6 on p. 100.

### 5.2.3 Relationships between individual SBML components and SBO terms

The **sboTerm** attribute is defined on the abstract class **SBase** and can be used in all derived elements. However, not all SBO terms should be used to annotate all SBML elements. Table 6 on the next page summarizes the relationships between SBML components and the branches within SBO that apply to that component. (There are currently no specific SBO term that correspond to the **SBML**, **UnitDefinition**, **Unit**, and various **ListOf** ______ list classes.)

The parent identifiers shown in Table 6 on the following page are provided for reference. They are the highest-level terms in their respective branch; however, these are *not* the terms that would be used to annotate an element in SBML, because there are more specific terms underneath the parents shown here. A software tool should use the most specific SBO term available for a given concept rather than using the top-level identifier acting as the root of that particular vocabulary.

## 5.3 Relationships to the SBML annotation element

Another way to provide this information would be to place SBO terms inside the **SBase** annotation element (Section 3.2 on p. 14 and Section 6 on p. 100). However, in the interest of making the use of SBO in SBML as interoperable as possible between software tools, the best-practice recommendation is to place SBO references in the **sboTerm** attribute rather than inside the **annotation** element of an object. If instead the approach of using **annotation** is taken, the qualifiers (Section 6.5 on p. 103) linking the SBML element and SBO term should be chosen extremely carefully, since it will no longer be possible to assume an “instance to class” relationship.

Although **sboTerm** is just another kind of optional annotation in SBML, SBO references are separated into their own attribute on SBML components, both to simplify their use for software tools and because doing so asserts a stronger and more focused connection in a more regimented fashion. SBO references are intended to allow a modeler to make a statement of the form “this object is identical in meaning and intention to the object defined in the term X of SBO”, and do so in a way that a *software tool can interpret unambiguously*.
<table><caption>**Table 6:** SBML components and the main types of SBO terms that may be assigned to them. The identifiers of the highest-level SBO terms in each branch are provided for guidance, but actual values used for sboTerm attributes should be more specific child terms within these branches. Note that the important aspect here is the set of specific SBO identifiers, not the SBO term names, because the names may change as SBO continues to evolve. See text for further explanations.</caption><thead><tr><th>SBML Component</th><th>SBO Branch</th><th>Branch Identifier</th></tr></thead><tbody><tr><td>SBML</td><td>modeling framework</td><td>SBO:0000004</td></tr><tr><td>Model</td><td>occurring entity representation or modeling framework</td><td>SBO:0000231 or SBO:0000004</td></tr><tr><td>FunctionDefinition</td><td>mathematical expression</td><td>SBO:0000064</td></tr><tr><td>Compartment</td><td>physical entity representation</td><td>SBO:0000236</td></tr><tr><td>Species</td><td>physical entity representation</td><td>SBO:0000236</td></tr><tr><td>Reaction</td><td>occurring entity representation</td><td>SBO:0000231</td></tr><tr><td>Parameter</td><td>systems description parameter</td><td>SBO:0000545</td></tr><tr><td>SpeciesReference</td><td>participant role</td><td>SBO:0000003</td></tr><tr><td>ModifierSpeciesReference</td><td>participant role</td><td>SBO:0000003</td></tr><tr><td>KineticLaw</td><td>rate law</td><td>SBO:0000001</td></tr><tr><td>LocalParameter</td><td>systems description parameter</td><td>SBO:0000545</td></tr><tr><td>InitialAssignment</td><td>mathematical expression</td><td>SBO:0000064</td></tr><tr><td>AlgebraicRule</td><td>mathematical expression</td><td>SBO:0000064</td></tr><tr><td>AssignmentRule</td><td>mathematical expression</td><td>SBO:0000064</td></tr><tr><td>RateRule</td><td>mathematical expression</td><td>SBO:0000064</td></tr><tr><td>Constraint</td><td>mathematical expression</td><td>SBO:0000064</td></tr><tr><td>Event</td><td>occurring entity representation</td><td>SBO:0000231</td></tr><tr><td>Trigger</td><td>mathematical expression</td><td>SBO:0000064</td></tr><tr><td>Priority</td><td>mathematical expression</td><td>SBO:0000064</td></tr><tr><td>Delay</td><td>mathematical expression</td><td>SBO:0000064</td></tr><tr><td>EventAssignment</td><td>mathematical expression</td><td>SBO:0000064</td></tr></tbody></table>

Some software applications may have their own vocabulary of terms similar in purpose to SBO. For maximal software interoperability, the best-practice recommendation in SBML is nonetheless to use SBO terms in preference to using application-specific annotation schemes. Software applications should therefore attempt to translate their private terms to and from SBO terms when writing and reading SBML, respectively.

## 5.4 Discussion

Here we discuss some additional points about the SBO-based approach.

### 5.4.1 Frequency of change in the ontology

The SBO development approach follows conventional ontology development approaches in bioinformatics. One of the principles being followed is that identifiers and meanings of terms in the CVs never change and the terms are never deleted. Where some terms are deemed obsolete, the introduction of new terms refine or supersede existing terms, but the existing identifiers are left in the CV. Thus, references never end up pointing to nonexistent entries. In the case where synonymous terms are merged after agreement that multiple terms are identical, the term identifiers are again left in the CV and they still refer to the same concept as before. Out-of-date terms cached or hard-coded by an application remain usable in all cases. (Moreover, machine-readable CV encodings and appropriate software design should render possible the development of API libraries that automatically map older terms to newer terms as the CVs evolve.) Therefore, a model is never in danger of ending up with SBO identifiers that cannot be dereferenced. If an application finds an old model with a term SBO:0000065, it can be assured that it will be able to find this term in SBO, even if it has been superseded by other, more preferred terms.

### 5.4.2 Consistency of information

If you have a means of linking (say) a reaction rate formula to a term in a CV, it is possible to have an inconsistency between the formula in the SBML model and the one defined for the CV term. However, this
is not a new problem; it arises in other situations involving SBML models already. The guideline for these
situations is that the model must be self-contained and stand on its own. Therefore, in cases where they
differ, the definitions in the SBML model take precedence over the definitions referenced by the CV. In other
words, the model (and its MathML) is authoritative.

**5.4.3 Implications for network access**

A software tool does not need to have the ability to access the network or read the CV every time it encounters
a model or otherwise works with SBML. Since the SBO will likely stabilize and change infrequently once a
core set of terms is defined, applications can cache the controlled vocabulary, and not make network accesses
to the master SBO copy unless something forces them to (e.g., detecting a reference in a model to an SBO
term that the application does not recognize). Applications could have user preference settings indicating how
often the CV definitions should be refreshed (similar to how modern applications provide a setting dictating
how often they should check for new versions of themselves). Simple applications may go further and hard
code references to terms in SBO that have reached stability and community consensus. SBO is available for
download under different formats (http://biomodels.net/sbo/). Web services are also available to provide
programmatic access to the ontology.
# 6 A standard format for the annotation element

This section describes the recommended non-proprietary format for the content of **Annotation** objects in SBML 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 its modification history. Such a structured format should facilitate the generation of models compliant with the MIRIAM guidelines for model curation (Le Novère et al., 2005).

The format described in this section is intended to be the form of one of the top-level elements that could reside in an **Annotation** object attached to an SBML object derived from **SBase**. The element is named **rdf:RDF**. The format described here is compliant with the constraints placed on the form of annotation elements described in Section 3.2.6 on p. 16. We refer readers to Section 3.2.6 for important information on the structure and organization of application-specific annotations; these are not described here.

The annotations described in this section are optional on a model, but if present, they must conform to the details specified here in order to be considered valid annotations in this format. If they do not conform to the format described here, it does not render the overall SBML model invalid, but the annotations are then considered to be in a proprietary format rather than being SBML MIRIAM annotations.

## 6.1 Motivation

The SBML structures described elsewhere in this document do not have any biochemical or biological semantics. This section provides a scheme for linking SBML structures to external resources so that those structures can be given semantics. The motivation for the introduction of this scheme is similar to that given for the introduction of **sboTerm**; however, the general annotation scheme here is more flexible.

It is generally not recommended that this format be used to refer to SBO terms. In most cases, the SBO terms should be assigned using the attribute **sboTerm** on objects derived from **SBase** (Section 3.2.4 on p. 15). However in certain situations, for instance to be able to add additional information about the functional role of a species, it is necessary to add the information using the annotation format described here.

Annotations only add additional qualifying information and never change existing information. They can be ignored without changing the (broader) meaning of the model. The same is true of nested annotations (described below), which qualify their parent annotation but never change the meaning of that annotation.

## 6.2 XML namespaces in the standard annotation

This format uses a restricted form of Dublin Core (Dublin Core Metadata Initiative, 2005) and BioModels.net qualifier elements (see https://co.mbine.org/standards/qualifiers) embedded in the XML form of RDF (W3C, 2004b). The scheme defined here uses a number of external XML standards and associated XML namespaces. Table 7 lists these namespaces and relevant documentation on those namespaces. The format constrains the order of elements in these namespaces beyond the constraints defined in the standard definitions for those namespaces. For each standard listed, the format only uses a subset of the possible syntax defined by the given standard. Thus, it is possible for an **annotation** element to include XML that is compliant with those external standards but is not compliant with the format described here.

<table><caption>**Table 7:** The XML standards used in the SBML standard format for annotations. The namespace prefixes are only shown to indicate the prefix used in the main text; the prefixes are not required to be the specific strings shown here.</caption><thead><tr><td>Prefix used</td><td>Namespace URI</td><td>Reference/description</td></tr></thead><tbody><tr><td>rdf</td><td>http://www.w3.org/1999/02/22-rdf-syntax-ns#</td><td>W3C (2004a)</td></tr><tr><td>dcterms</td><td>http://purl.org/dc/terms/</td><td>Kokkelink and Schwänzl (2002), DCMI Usage Board (2005)</td></tr><tr><td>vcard4</td><td>http://www.w3.org/2006/vcard/ns#</td><td>Perreault (2011)</td></tr><tr><td>bqbiol</td><td>http://biomodels.net/biology-qualifiers/</td><td>https://co.mbine.org/standards/qualifiers</td></tr><tr><td>bqmmodel</td><td>http://biomodels.net/model-qualifiers/</td><td>https://co.mbine.org/standards/qualifiers</td></tr></tbody></table>

Note that **vCard** 3 has been deprecated in favor of **vCard** 4. Models using **vCard** 3 will continue to be legal,
but tools may issue a warning that `vCard` 4 is preferred. Future versions of SBML will drop `vCard` 3 as part of the officially supported annotation 'standard format'.

## 6.3 General syntax for the standard annotation

This standard format for an SBML annotation is placed in a single `rdf:RDF` element contained within the SBML annotation element. It can contain other elements in any order as described in Section 3.2.6 on p. 16. The format described in this section only defines the form of the `rdf:RDF` element. The containing SBML SBase element must have a `metaid` attribute value (and note that, because it is of XML type `ID`, its value must be unique to the entire SBML document). An outline of the format's syntax is shown below.

<figure><img src="image_32.png" /></figure>

The outline above shows the expected order of the elements. The capitalized identifiers refer to generic strings of specific types, as follows: `SBMLElement` refers to any SBML element name that can contain an annotation element; `SBML_META_ID` is an XML ID string; `RELATION element` refers to element names in either the namespace `http://biomodels.net/biology-qualifiers/` or `http://biomodels.net/model-qualifiers/` (see Section 6.5); `URI` is a URI identifying a resource (see Section 6.4); and `[HISTORY]` refers to optional content described in Section 6.6.

`[NESTED CONTENT]` has the same format and restrictions as `RELATION element`:

<figure><img src="image_33.png" /></figure>

`[NESTED CONTENT]` is used to describe a clarification or another annotation about the `RELATION ELEMENT` in which it appears, using such elements as `bqbiol:isDescribedBy`. Nested content permits, for example, describing protein modifications on species, or adding evidence codes for an annotation. Nested content relates to its containing `RELATION ELEMENT`, not the other way around. It qualifies, but does not change, its meaning. Ignoring a `[NESTED CONTENT]` does not affect the information provided by the containing `RELATION ELEMENT`. These elements may be nested arbitrarily deep, with each successive layer describing or clarifying the annotation it is embedded within.
The string `+++` is a placeholder for either no content or valid XML content that is not defined by the annotation scheme described here but is consistent with the relevant standards for the enclosing elements. Finally, the string `...` is a placeholder for zero or more elements of the same form as the immediately preceding element. The precise form of whitespace and the XML namespace prefix definitions is not constrained; however, the elements and attributes must be in the namespaces shown. The rest of this section describes the format formally in English.

The first element of the **rdf:RDF** element must be an **rdf:Description** element with an **rdf:about** attribute. The value of the **rdf:about** attribute must be of the form `#<string>` where the string component is equal to the value of the **metaid** attribute of the containing SBML element. This format doesn't define the form of subsequent subelements of the **rdf:RDF** element. In particular, the unique **rdf:RDF** element contained in the annotation can contain other **rdf:Description**, which content can be any valid RDF.

The **rdf:Description** element can contain only an optional history section (see Section 6.6) followed by zero or more BioModels.net relation elements. The specific relation elements used will depend on the intended relationship between the SBML component and referenced information or resource. Although Section 6.5 describes the detailed semantics of each of the relation element types, the content of these elements follows the same form shown in the template above. A BioModels.net relation element must only contain a single **rdf:Bag** element which in turn must contain one or more **rdf:li** elements. The **rdf:li** elements must only have a **rdf:resource** attribute containing a URI referring to an information resource (see Section 6.4). The relation element may also contain nested content (indicated by **[NESTED CONTENT]** in the diagram above) with annotations *about* the contents of the **rdf:Bag**.

Note that the various namespaces (`xmlns:rdf`, `xmlns:dcterms`, etc.) may be declared in any order, and that only the namespaces that are actually used need be declared. If no `vcard4` terms are used in a particular annotation, for example, the line `xmlns:vcard4="http://www.w3.org/2006/vcard/ns#"` is optional.

## 6.4 Use of URIs

The SBML MIRIAM annotation format allows the expression of relationships between SBML elements on the one hand, and resources referred to by values of **rdf:resource** attributes on the other. The BioModels.net relation elements (see Section 6.5 on the following page) simply define the nature of the relationship.

The value of a **rdf:resource** attribute is a URI that uniquely identifies both the resource and the data within the resource. Since a URI is not a URL, it does not have to map to a physical Web object; it simply needs to identify, uniquely, a controlled vocabulary term or database object. It is essentially just a label. For instance, an actual URL for an Internet resource might be https://www.uniprot.org/uniprot/P12999, and this might correspond to the URI https://identifiers.org/uniprot/P12999 (Juty et al., 2012).

It is important that the portion of a **rdf:resource** value that identifies a data entry is always a perennial identifier. For example, a **Species** object representing a protein could be annotated with a reference to the database UniProt by the resource identifier https://identifiers.org/uniprot/P12999, thereby identifying exactly the intended protein. This identifier maps to a unique entry in UniProt which is never deleted from the database. In the case of UniProt, this is known as the “accession” portion of the entry. When the entry is merged with another one, both “accession” entries are conserved. A UniProt entry also possesses an “entry name” (the Swiss-Prot “identifier”), a “protein name”, “synonyms”, and other parts, but only the “accession” is perennial, and that is what should be used.

SBML does not define how to interpret URIs. There may be several ways of transforming a URI into a physical URL; e.g., https://identifiers.org/go/GO:0007268 can be translated into any of the following:

* http://amigo.geneontology.org/amigo/term/GO:0007268

* https://www.ebi.ac.uk/QuickGO/GTerm?id=GO:0007268

* http://www.informatics.jax.org/vocab/gene_ontology/GO:0007268

Similarly, https://identifiers.org/ec-code/3.5.4.4 can refer to any of the following (among many):

* https://www.ebi.ac.uk/intenz/query?cmd=SearchEC&ec=3.5.4.4

* https://www.metanetx.org/cgi-bin/mnxweb/search?query=3.5.4.4

* https://enzyme.expasy.org/EC/3.5.4.4
To enable interoperability of URIs between software systems, the community has standardized the URI rules for use within the SBML MIRIAM annotation format. These URIs are not part of the SBML standard per se, and will grow independently from specific SBML levels and versions. As the set changes, existing URIs will not be modified, although the physical resources associated with each one may change (for example, to use updated URLs). The form of the URIs will always have the form *resource:identifier*. An up-to-date list and explanations of the URIs are available online at the address https://www.ebi.ac.uk/miriam/main/collections. Each entry lists the database in question, the URI to be used to reference that database, and example URIs for referencing particular entries in those databases. The URI rule list will evolve with the evolution of databases and resources.

Note this means that all **rdf:resource** *must* be MIRIAM URIs and thus cannot refer to, for example, other elements in the model. While it would be possible to place such information in RDF content elsewhere (e.g., after the first **rdf:Description** element), the information will be outside the scope of the simple annotation scheme described here, and as such, there is no guarantee that other software could understand it.

## 6.5 Relation elements

Different BioModels.net qualifier elements encode different types of relationships. As described above, when appearing in an annotation, each qualifier element encloses a set of **rdf:li** elements. Its appearance in a relation element implies a specific relationship between the enclosing SBML object and the resources referenced by the **rdf:li** elements. When several relation elements with the same name are placed in the same SBML element's annotation, they represent alternatives. For example, two **bqbiol:hasPart** elements within a **Species** object represent two different sets of references to the parts making up the biological entity represented by the species. (The species is not made up of *all* the entities represented by all the references combined; they are alternatives.)

Table 8 on the next page lists the elements defined at the time of this writing. The list is divided into two symbol namespaces: **http://biomodels.net/model-qualifiers/** is for model qualifiers (for which we use the prefix **bqmodel** in examples shown in this section). The other namespace is for biological qualifiers; this has the URI **http://biomodels.net/biology-qualifiers/** (for which we use the prefix **bqbiol**). The list will only grow; i.e., no element will be removed from the list.
<table><caption>**Table 8:** *BioModels.net qualifiers at the time of this writing, and a summary of their meanings. The complete list of the qualifier elements is documented online at http://biomodels.net/qualifiers/. (The definitions given above are slightly modified compared to the originals, to reflect the SBML-specific nature of this SBML specification document.)*</caption><thead><tr><td>Qualifier element</td><td>Meaning</td></tr></thead><tbody><tr><td>bqmodel:hasInstance</td><td>The subject of the referenced resource is an instance of the modeling object. This could be used, for example, to link a generic model with its specific forms.</td></tr><tr><td>bqmodel:is</td><td>The modeling object encoded by the SBML component is the subject of the referenced resource. This might be used, e.g., to link the model to an entry in a model database.</td></tr><tr><td>bqmodel:isDerivedFrom</td><td>The modeling object represented by the component of the encoded model is derived from the modeling object represented by the referenced resource. For instance, they can be the fruit of a refinement or their adaptation for use in a different context.</td></tr><tr><td>bqmodel:isDescribedBy</td><td>The modeling object encoded by the SBML component is described by the referenced resource. This could link a component (e.g., a reaction) to a publication describing it.</td></tr><tr><td>bqmodel:isInstanceOf</td><td>The modeling object represented by the model element is an instance of the subject of the referenced resource.</td></tr><tr><td>bqbiol:encodes</td><td>The biological entity represented by the model component encodes, either directly or by virtue of transitivity, the subject of the referenced resource.</td></tr><tr><td>bqbiol:hasPart</td><td>The biological entity represented by the SBML component includes the subject of the referenced resource, either physically or logically. This relation might be used to link a complex to a description of its components.</td></tr><tr><td>bqbiol:hasProperty</td><td>The subject of the referenced resource is a property of the biological entity represented by the model component. This relation might be used when a biological entity has a given activity or exerts a specific function.</td></tr><tr><td>bqbiol:hasVersion</td><td>The subject of the referenced resource is a version or an instance of the biological entity represented by the SBML component.</td></tr><tr><td>bqbiol:is</td><td>The biological entity represented by the SBML component is the subject of the referenced resource. This could serve to link a reaction to its counterpart in (e.g.) the ChEBI or Reactome databases.</td></tr><tr><td>bqbiol:isDescribedBy</td><td>The biological entity represented by the SBML component is described by the referenced resource. This relation could be used, for example, to link a species or a parameter to a publication describing the quantity of the species or the value of the parameter.</td></tr><tr><td>bqbiol:isEncodeBy</td><td>The biological entity represented by the model component is encoded, either directly or by virtue of transitivity, by the subject of the referenced resource.</td></tr><tr><td>bqbiol:isHomologTo</td><td>The biological entity represented by the SBML component is homolog, to the subject of the referenced resource, i.e., they share a common ancestor.</td></tr><tr><td>bqbiol:isPartOf</td><td>The biological entity represented by the SBML component is a physical or logical part of the subject of the referenced resource. This relation might be used to link a component to the description of the complex to which it belongs.</td></tr><tr><td>bqbiol:isPropertyOf</td><td>The biological entity represented by the SBML component is a property of the referenced resource.</td></tr><tr><td>bqbiol:isVersionOf</td><td>The biological entity represented by the SBML component is a version or an instance of the subject of the referenced resource.</td></tr><tr><td>bqbiol:occursIn</td><td>The biological entity represented by the SBML component takes place in the subject of the referenced resource.</td></tr><tr><td>bqbiol:hasTaxon</td><td>The biological entity represented by the SBML component is taxonomically restricted, where the restriction is the subject of the referenced resource. This relation may be used to ascribe a species restriction to a biochemical reaction.</td></tr></tbody></table>
## 6.6 History

The SBML MIRIAM annotation format described in Section 6.3 on p. 101 can include additional elements to describe the history of the SBML encoding of the model or its individual components. (Note the emphasis on the SBML encoding—the history of the conceptual model underlying the encoding is not addressed by this scheme.) If this history data is present, it must occur immediately before the first BioModels.net relation elements of an annotation. The history encodes information about the creator(s) of the encoding and a sequence of dates recording the dates of creation and subsequent modifications of the SBML model encoding. The syntax for these elements is outlined below.

<figure><img src="image_34.png" /></figure>

Or, to more closely match vCard 3, `vCard4:hasName` may be used instead of `vCard4:fn`:

<figure><img src="image_35.png" /></figure>

The order of elements must be as shown above, except that elements of the format contained in the light gray box (`vCard4:fn` or `vCard4:hasName`, plus `vCard4:hasEmail`, and `vCard4:organization-name`) can occur in any order. The elements of the format contained between `[` and `]` (`vCard4:organization-name`, and `vCard4:hasEmail`) are optional, but everything else is required. The precise form of the whitespace, and the specific XML namespace prefixes used ("dcterms", "rdf", and "vcard4") are not constrained.

The `dcterms:creator` element describes the person(s) who created the SBML encoding of the model or model component. It must contain a single `rdf:Bag` element. The `rdf:Bag` element can contain any number of elements; however, the first such element must be `rdf:li`. The `rdf:li` element can in turn contain any number of elements in any order. Among those elements can be the following: `vCard4:fn` or `vCard4:hasName`, plus `vCard4:hasEmail`, and `vCard4:organization-name`. The `dcterms:created`, and `dcterms:modified` elements must have the attribute `rdf:parseType` set to the literal value "Resource".

Note that `dcterms:creator` has been added to http://purl.org/dc/terms/ relatively recently, but the same term (with the same meaning) exists in the http://purl.org/dc/elements/1.1/ namespace. It is legal to continue using the old namespace (called "dc" in previous versions of the SBML specifications), but since all the terms defined there are now also defined in http://purl.org/dc/terms/, we recommend using the latter.

The content placeholders `FAMILY_NAME` and `GIVEN_NAME` stand for the family name (surname) and the first (given) name, respectively, of a person who created the model; when using `vCard4`, `FULL_NAME` stands for the full name of that person. `EMAIL_ADDRESS` is the email address of the same person who created the model; and `ORGANIZATION_NAME` is the name of the organization with which the same person who created the model is affiliated. The string `DATE` is a date in W3C date format (Wolf and Wicksteed, 1998), which is a profile of (i.e., a restricted form of) ISO 8601. Finally, as in the overall template shown in Section 6.3 on p. 101, `+++`
is a placeholder for either no content or valid XML syntax that is not defined by this scheme but is consistent with the relevant standards for the enclosing elements, and ellipses (‘...’) are placeholders for zero or more elements of the same form as the immediately preceding element.

Section 6.7 below provides an example of using these history elements in the SBML MIRIAM annotation format.

## 6.7 Examples

The following shows the annotation of a model with model creation data and links to external resources:

<figure><img src="image_36.png" /></figure>

The following example shows a Reaction object annotated with a reference to its exact Reactome counterpart.

<figure><img src="image_37.png" /></figure>
```xml
<bqbiol:is>
  <rdf:Bag>
    <rdf:li rdf:resource="https://identifiers.org/reactome/REACT_6327"/>
  </rdf:Bag>
</bqbiol:is>
</rdf:Description>
</rdf:RDF>
</annotation>
<listOfReactants>
  <speciesReference species="cdc2" stoichiometry="1"/>
</listOfReactants>
<listOfProducts>
  <speciesReference species="cdc2-Y15P" stoichiometry="1"/>
</listOfProducts>
<listOfModifiers>
  <modifierSpeciesReference species="wee1"/>
</listOfModifiers>
</reaction>
```

The following example describes a species that represents a complex between the protein calmodulin and calcium ions:

```xml
<species id="Ca_calmodulin" metaid="cacam" compartment="C"
          hasOnlySubstanceUnits="false" boundaryCondition="false"
          constant="false">
  <annotation>
    <rdf:RDF
      xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
      xmlns:bqbiol="http://biomodels.net/biology-qualifiers/"
    >
      <rdf:Description rdf:about="#cacam">
        <bqbiol:hasPart>
          <rdf:Bag>
            <rdf:li rdf:resource="https://identifiers.org/uniprot/P62158"/>
            <rdf:li rdf:resource="https://identifiers.org/chebi/CHEBI:29108"/>
          </rdf:Bag>
        </bqbiol:hasPart>
      </rdf:Description>
    </rdf:RDF>
  </annotation>
</species>
```

The following example describes a species that represents either “Calcium/calmodulin-dependent protein kinase type II alpha chain” or “Calcium/calmodulin-dependent protein kinase type II beta chain”. This is the case, for example, in the somatic cytoplasm of striatal medium-size spiny neurons, where both are present but they cannot be functionally differentiated.

```xml
<species id="calcium_calmodulin" metaid="cacam" compartment="C"
          hasOnlySubstanceUnits="false" boundaryCondition="false"
          constant="false">
  <annotation>
    <rdf:RDF
      xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
      xmlns:bqbiol="http://biomodels.net/biology-qualifiers/"
    >
      <rdf:Description rdf:about="#cacam">
        <bqbiol:hasVersion>
          <rdf:Bag>
            <rdf:li rdf:resource="https://identifiers.org/uniprot/Q9UQM7"/>
            <rdf:li rdf:resource="https://identifiers.org/uniprot/Q13554"/>
          </rdf:Bag>
        </bqbiol:hasVersion>
      </rdf:Description>
    </rdf:RDF>
  </annotation>
</species>
```

The above approach should not be used to describe “any Calcium/calmodulin-dependent protein kinase