The Systems Biology Markup Language (SBML): Language Specification for Level 3 Version 2 Core Release 2

Abstract Computational models can help researchers to interpret data, understand biological functions, and make quantitative predictions. The Systems Biology Markup Language (SBML) is a file format for representing computational models in a declarative form that different software systems can exchange. SBML is oriented towards describing biological processes of the sort common in research on a number of topics, including metabolic pathways, cell signaling pathways, and many others. By supporting SBML as an input/output format, different tools can all operate on an identical representation of a model, removing opportunities for translation errors and assuring a common starting point for analyses and simulations. This document provides the specification for Release 2 of Version 2 of SBML Level 3 Core. The specification defines the data structures prescribed by SBML as well as their encoding in XML, the eXtensible Markup Language. Release 2 corrects some errors and clarifies some ambiguities discovered in Release 1. This specification also defines validation rules that determine the validity of an SBML document, and provides many examples of models in SBML form. Other materials and software are available from the SBML project website at http://sbml.org/.

and red text to indicate a semantic change or addition. 48 2 Overview of SBML 1 The following is an example of a simple network of biochemical reactions that can be represented in SBML: In this particular set of chemical equations above, the symbols in square brackets (e.g., "[S 1 ]") represent 4 concentrations of molecular species, the arrows represent reactions, and the formulas above the arrows 5 represent the rates at which the reactions take place. (And while this example uses concentrations, it could 6 equally have used other measures such as molecular counts.) Broken down into its constituents, this model 7 contains a number of components: reactant species, product species, reactions, reaction rates, and parameters 8 in the rate expressions. To analyze or simulate this network, additional components must be made explicit, 9 including compartments for the species, and units on the various quantities.
10 SBML allows models of arbitrary complexity to be represented. Each type of component in a model is 11 described using a specific type of data object that organizes the relevant information. The top level of an 12 SBML model definition consists of lists of these components, with every list being optional: list of constraints (optional) (Section 4.10) 23 list of reactions (optional) (Section 4.11) 24 list of events (optional) (Section 4.12) most other classes of objects in SBML, this base type is designed to allow a modeler or a software package to 23 attach arbitrary information to each major element or list in an SBML model. The definition of SBase is 24 presented in Figure 8. SBase contains four attributes and two subobjects, all of which are optional: id, name, metaid, sboTerm, 26 Notes, and Annotation. These are discussed separately in the following subsections. 27 14 XML namespace requirements for notes 1 In XML, the notes elements must declare the use of the XHTML XML namespace. This can be done in 2 multiple ways. One way is to place a namespace declaration for the appropriate namespace URI (which is 3 http://www.w3.org/1999/xhtml) on the top-level SBML object (see Section 4.1 on p. 34) and then reference 4 the namespace in the notes content using a prefix. The following example illustrates this approach: 5 <sbml xmlns="http://www.sbml.org/sbml/level3/version2/core" level="3" version="2" 6 xmlns:xhtml="http://www.w3.org/1999/xhtml"> 7 ... .. 16 Another approach is to declare the XHTML namespace within the notes content itself, as in the following 17 example: 18 ... ... 26 The xmlns="http://www.w3.org/1999/xhtml" declaration on body as shown above changes the default XML 27 namespace within it, such that all of its content is by default in the XHTML namespace. This is a particularly 28 convenient approach because it obviates the need to prefix every element with a namespace prefix (i.e., 29 "xhtml:" in the earlier example). Other approaches are also possible. 30 The XHTML content of notes 31 SBML Level 3 does not require the content of a Notes object to be any particular XHTML element; the 32 content simply should be any well-formed XHTML content. There is only one restriction, and it comes 33 from the requirements of XML: the notes element must not contain an XML declaration or a DOCTYPE 34 declaration. That is, notes must not contain 35 <?xml version="1.0" encoding="UTF-8"?> 36 nor the following (where the following is only one specific example of a DOCTYPE declaration): Whereas Notes is a container for content to be shown directly to humans, Annotation is a container for optional 41 software-generated content not meant to be shown to humans. Every object derived from SBase can have its 42 own Annotation object instance. In XML, the Annotation content type is any, allowing essentially arbitrary 43 well-formed XML data content. SBML places only a few restrictions on the organization of the content; 44 these are intended to help software tools read and write the data as well as help reduce conflicts between 45 annotations added by different tools. 46 The use of XML namespaces in annotations At the outset, software developers should keep in mind that multiple software tools may attempt to read 48 and write annotation content. To reduce the potential for collisions between annotations written by different 49 applications, SBML Level 3 Version 2 Core stipulates that tools must use XML namespaces (Bray et al., 1999) 1 to specify the intended vocabulary of every annotation. The namespace may be declared on the root element 2 using that namespace, or on any XML element containing it, up to and including the root <sbml> object itself. 3 The application's developers must choose a URI (Universal Resource Identifier ; Harold and Means 2001;4 W3C 2000a) reference that uniquely identifies the vocabulary the application will use, and a prefix string for 5 the annotations. Here is an example. Suppose an application uses the URI http://www.mysim.org/ns and 6 the prefix mysim when writing annotations related to molecules. The content of an annotation might look like 7 the following: example is small, but it should be clear that there could easily have been an arbitrarily large amount of data 16 placed inside the mysim:molecule element. 17 Similarly, if the mysim namespace was declared in a containing element such as the <sbml> object, the 18 annotation might look like: 19 <annotation> 20 <mysim:molecule mysim:weight="18.02" mysim:atomCount="3"/> 21 </annotation> 22 The key point of both examples above is that application-specific annotation data are entirely contained 23 inside a single top-level element within the SBML annotation container. SBML Level 3 Version 2 Core places 24 the following restrictions on annotations:

25
• Within a given annotation element, there can only be one top-level element using a given namespace. An 26 annotation element can contain multiple top-level elements but each must be in a different namespace.

27
• The ordering of top-level elements within a given annotation element is not significant. An application 28 should not expect that its annotation content appears first in the annotation element, nor in any other 29 particular location. Moreover, the ordering of top-level annotation elements may be changed by different 30 applications as they read and write the same SBML file. 31 The use of XML namespaces in this manner is intended to improve the ability of multiple applications to place 32 annotations on SBML model elements with reduced risks of interference or name collisions. Annotations stored 33 by different simulation packages can therefore coexist in the same model definition. The rules governing the 34 content of annotation elements are designed to enable applications to easily add, change, and remove their 35 annotations from SBML elements while simultaneously preserving annotations inserted by other applications 36 when mapping SBML from input to output. Some more examples hopefully will make these points more clear. The following example is invalid because it 46 contains two top-level elements using the same XML namespace, http://www.mysim.org/ns. Note that it does not matter that these are two different top-level elements (<molecule> and <atom>); what matters for 48 SBML is that these separate elements are both in the same namespace rather than having been collected and 49 placed inside one overall container element for that namespace: 50 <annotation> 1 <mysim:molecule xmlns:mysim="http://www.mysim.org/ns" mysim:weight="18.02" mysim:atoms="3"/> 2 <mysim:atom xmlns:mysim="http://www.mysim.org/ns" mysim:weight="18.02" mysim:atoms="3"/> 3 </annotation> 4 On the other hand, the following example is valid. The elements molecule, bonds, and icon inside the 5 annotation each use a separate XML namespace (i.e., http://www.mysim.org/ns, http://www.struct.org/ns, 6 and http://othersim.com, respectively, declared in the elements where they appear): 7 <annotation> 8 <mysim:molecule xmlns:mysim="http://www.mysim.org/ns" mysim:weight="18.02" mysim:atoms="3"/> 9 <struct:bonds xmlns:struct="http://www.struct.org/ns" struct:number="2" struct:type="ionic"/> 10 <othersim:icon xmlns:othersim="http://www.othersim.com/">WS2002</othersim:icon> 11 </annotation> 12 For completeness, we note that annotations legally can be empty (but such annotations have no meaning): 13 <annotation /> 14 It is worth keeping in mind that although XML namespace names must be URIs, they are (like all XML 15 namespace names) not required to be directly usable in the sense of identifying an actual, retrieval document 16 or resource on the Internet (Bray et al., 1999). URIs such as http://www.mysim.org/ may appear as though 17 they are (e.g.,) Internet addresses, but they are not the same thing. This style of URI strings, using a domain 18 name and other parts, is only a simple and commonly-used way of creating a unique name string. 19 Finally, note that the namespaces being referred to here are XML namespaces specifically in the context of 20 the annotation element on SBase. The namespace issue here is unrelated to the namespaces discussed in 21 Section 3.3.1 in the context of component identifiers in SBML.

22
Content of annotations and implications for software tools 23 Annotation exists as a subobject of SBase in order that software developers may attach optional application- 24 specific data to the elements in an SBML model. However, it is important that this facility is not misused. In 25 particular, it is critical that data essential to a model definition or that can be encoded in existing SBML 26 elements is not stored in annotations. Parameter values, functional dependencies between model elements, etc., 27 should not be recorded as annotations. It is crucial to keep in mind the fact that data placed in annotations 28 can be freely ignored by software applications. If such data affect the interpretation of a model, then software 29 interoperability is greatly impeded. Recommendations regarding the use of any sort of annotation are given 30 in Section 8.1.4 on p. 147. 31 3.3 The id and name attributes on SBase 32 Every object whose class is derived from SBase may have values for the id and name attributes. In this 33 section, we elaborate on the use of id and name and discuss some of the implications. 34 3.3.1 The id attribute and identifier scoping 35 A model can contain a large number of components representing different parts. This leads to a problem in 36 deciding the scope of an identifier: in what contexts does a given identifier X represent the same thing? The 37 approaches used in existing simulation software tend to fall into two categories which we may call global and 38 local. The global approach places all identifiers into a single global space of identifiers, so that an identifier 39 X represents the same thing wherever it appears in a given model definition. The local approach places 40 symbols in separate identifier namespaces, depending on the context, where the context may be, for example, 41 individual reaction rate expressions. The latter approach means that a model may use the same identifier X 42 in different rate expressions and have each instance represent a different quantity. 43 The scoping rules in SBML Level 3 are intended as a compromise to help support both scenarios: 44 • The identifier (i.e., the value of the attribute id) of every SBase-derived class that does not stipulate 45 otherwise must be unique across the set of all such identifiers in the model. This means, for example, 46 that a reaction and a species definition cannot both have the same identifier.

47
• The identifier of every UnitDefinition must be unique across the set of all such identifiers in the model 1 plus the set of base unit definitions in Table 2 on p. 44. However, unit identifiers live in a separate 2 space of identifiers from other identifiers in the model, by virtue of the fact that the data type of unit 3 identifiers is UnitSId (Section 3.1.9 on p. 13) and not SId. 4 • Each Reaction instance (see Section 4.11 on p. 68) establishes a separate private local space for local 5 parameters represented by objects of class LocalParameter. Within the definition of that reaction, local 6 parameter identifiers override (shadow) identical identifiers from the SId namespace of the model 7 outside of that reaction. Conversely, local parameters in a given KineticLaw object are not visible outside 8 of that kinetic law's Reaction. To emphasize this, a LocalParameter's id attribute has type LocalSId 9 (Section 3.1.11 on p. 14) rather than SId. to have a type derived from SId, whether it is defined in SBML Level 3 Core or one defined by that 13 Level 3 package. Elements with an id of that type follow the rules of uniqueness defined for the type.
14 For example, the SBML Level 3 Hierarchical Model Composition package defines a PortSId type, and 15 Port objects have an id attribute of that type. The Hierarchical Model Composition package stipulates 16 that all Port element id values in a given Model must be unique only among the other Port objects in 17 that Model. 18 19 SBML Level 3 Version 2 Core puts the id and name attributes directly on the SBase abstract class. This 20 is a departure from previous Level/Version combinations of SBML, in which id and name were defined on 21 individual SBML component classes. The following were the motivations for this change.

22
• Object classes in SBML originally were given id attributes only if they had meaning for mathematical 23 expressions. (For instance, the concentrations of species, the sizes of compartments, etc.) As SBML 24 evolved, more objects were given id attributes but these were not always associated with a mathematical 25 meaning. When SBML Level 3 packages were introduced, not only did further uses of id become 26 apparent: it also became possible for Level 3 packages to add nuances of meanings that Level 3 Core did 27 not. Thus, while Level 3 Core may not define a use for an id attribute on a given object, a Level 3 package 28 might. Examples exist in the SBML Level 3 Graphical Layout and Hierarchical Model Composition 29 packages. 30 • The metaid attribute on SBase may seem to fulfill a similar role as an identifier for every object in 31 an SBML document. However, for several reasons it is unsuitable for use as a substitute for id. First, 32 owing to the fact that its data type is the XML type ID, it has a less restricted syntax (for instance, 33 allowing Unicode characters). Second, its scope cannot be ammended as needed for elements such as 34 the UnitDefinition or LocalParameter, because XML ID is defined to have document-wide uniqueness 35 properties. Finally, having a model -wide scope instead of a document-wide scope has been found desirable 36 for the SBML Level 3 Hierarchical Model Composition package.

37
• Because SBML Level 3 Version 2 Core objects may reference objects in SBML Level 3 packages directly, 38 and because package objects themselves may reference Core objects as well as objects from other 39 packages, the simplest means of achieving this is to put the id attribute on SBase directly.

40
• The name attribute is logically paired with id, to provide the option of a user-readable moniker for any 41 object with an id attribute. With id on SBase, it makes sense to put name on SBase too.   45 Packages created and designed for use with SBML Level 3 Version 1 may be used in SBML Level 3 Version 2 46 documents, and be interpreted in exactly the same manner as before. They may not, however, take full 47 advantage of the new features and constructs in Version 2. This means the following: 1 • Any object class in an SBML Level 3 Version 1 package that inherits from SBase will not inherit the 2 new id and name attributes on SBase. 3 • An object identifier from a SBML Level 3 Version 1 package may not be used in Math constructs in 4 SBML Level 3 Version 2 Core, nor as the value of any SIdRef type attribute in a Core construct. 5 • No object from a SBML Level 3 Version 1 package is considered to have mathematical meaning in core: 6 no such object's SId may be used as the target of a rule nor of an assignment, nor may it be used in 7 any MathML outside of that package. 8 However, if a package defines an SIdRef that may refer to any SBase, it is legal for those references to point 9 to SBML Level 3 Version 2 SIds. In particular:

10
• An SIdRef defined in a SBML Level 3 Version 1 package may be used to reference an element from 11 Level 3 Version 2 Core that has an SId, but did not have one in Version 1.

12
• An SIdRef defined in a SBML Level 3 Version 1 package may be used to reference an element from an 13 SBML Level 3 Version 2 package. 14 • Any Math object defined in a SBML Level 3 Version 1 package may reference any SBML Level 3 15 Version 2 package SId defined as having mathematical meaning. 16 To take some examples: the reference attribute of a SBML Level 3 Version 1 Layout GeneralGlyph is of 17 type SIdRef, and was designed to be able to point to arbitrary SBML Level 3 Version 1 core and package 18 elements. If used in a Level 3 Version 2 Core document, it could now point to an AssignmentRule, which it 19 would not have been able to do in a SBML Level 3 Version 1 document. Alternatively, it could point to an 20 SBML Level 3 Version 2 package element that inherited an SId from SBase. Similarly, any Math element 21 in an SBML Level 3 Version 1 package must be designed to be able to contain SIdRefs to SBML Level 3 22 Version 1 Core elements with mathematical meaning, but whose meaning might have been changed by a 23 SBML Level 3 Version 1 package. These formulas may now skip the middle man and refer directly to SBML 24 Level 3 Version 2 package SIds that have their own mathematical meaning. international standard for encoding mathematical expressions using XML. There are two principal facets 28 of MathML, one for encoding content (i.e., the semantic interpretation of a mathematical expression), and 29 another for encoding presentation or display characteristics. SBML only makes direct use of a subset of the The following are the only attributes permitted on MathML elements in SBML (in addition to the xmlns 23 attribute on math elements): 24 • style, class and id on any element;

25
• encoding on csymbol, annotation and annotation-xml elements; 26 • definitionURL on ci, csymbol and semantics elements; and 27 • type and sbml:units (see Section 3.4.2) on cn elements. 28 Missing values for the MathML attributes are to be treated in the same way as defined by MathML 2.0. 29 These restrictions on attributes are designed to confine the MathML elements to their default semantics and 30 to avoid conflicts in the interpretation of the type of token elements. 31 32 In MathML, literal numbers are written as the content portion of a particular element called cn. This element 33 takes an optional attribute, type, used to indicate the type of the number (such as whether it is meant to be 34 an integer or a floating-point quantity). Here is an example of its use: 35 <math xmlns="http://www.w3.org/1998/Math/MathML"> <apply> <times/> <cn type="integer"> 42 </cn> <cn type="real"> 3.3 </cn> </apply> </math> the compact notation "2e-5" is in fact allowed. In other words, within MathML expressions contained in 23 SBML (and only within such MathML expressions), numbers in scientific notation must take the form <cn 24 type="e-notation"> 2 <sep/> -5 </cn>, and everywhere else they must take the form "2e-5" or "2E-5". 25 This is a regrettable difference between two standards that SBML replies upon, but it is not feasible to 26 redefine these types within SBML because the result would be incompatible with parser libraries written to 27 conform to the MathML and XML Schema standards. It is also not possible to use XML Schema to define 28 a data type for SBML attribute values permitting the use of the <sep/> notation, because XML attribute 29 values cannot contain XML elements-that is, <sep/> cannot appear in an XML attribute value. 30 Units associated with numbers in MathML cn expressions 31 What units should be attributed to numbers appearing inside MathML cn elements? One answer is to assume 32 that the units should be "whatever units are appropriate in the context where the number appears". This 33 implies that units can always be assigned unambiguously to any number by inspecting the expression in which 34 it appears, and this turns out to be false. Another answer is that numbers should be considered "dimensionless". 35 Many people argue that this is the correct interpretation, but even if it is, there is an overriding practical 36 reason why it cannot be adopted for SBML's domain of application: when numbers appear in expressions in 37 SBML, they are rarely intended by the modeler to have the unit "dimensionless" even if the unit is not 38 declared-instead, the numbers are supposed to have specific units, but the units are usually undeclared. 39 (Being "dimensionless" is not the same as having undeclared units!) If SBML defined numbers as being by 40 default dimensionless, it would result in many models being technically incorrect without the modeler being 41 aware of it unless their software tools performed dimensional analysis. Many software tools do not perform 42 unit analysis, and so potential errors due to inconsistent units in a model would not be detected until other 43 researchers and database curators attempted to use the model in software packages that did check units. We 44 believe the negative impact on interoperability would be too high. 45 SBML borrows an idea from CellML (Hedley et al., 2001), another model definition language with goals 46 similar to SBML's, and allows an additional attribute to appear on MathML cn elements; the value of this 47 attribute can be used to indicate the unit of measurement to be associated with the number in the content of As noted already in Section 3.1.2 on p. 11, there is another unfortunate difference between the XML Schema 1.0 23 and MathML 2.0 standards that impacts mathematical expressions in SBML: in XML Schema, the value 24 space of type boolean includes "true", "false", "1", and "0", whereas in MathML, only "true" and "false" 25 count as Boolean values. 26 The impact of this difference is, thankfully, minimal because the XML Schema definition is only used for 27 attribute values on SBML objects, and those values turn out never to be accessible from MathML content in 28 SBML-values of boolean attributes on SBML objects can never enter into MathML expressions. Nevertheless, 29 software authors and users should be aware of the difference.

Numbers and cn elements
Level 3 Version 2, the numerical value is taken to be the one recommended by the 2006 edition of 23 CODATA (Mohr et al., 2008), but the unit of the value is dimensionless. In other words, the value of 24 this csymbol is equivalent to the following: 25 (6.02214179 · 10 23 ) · dimensionless 26 If the value of the constant is revised by international standards-setting organizations in the future, a 27 future Version of the SBML Level 3 specification may stipulate a new value to be used for this csymbol 28 constant. However, all software applications reading models expressed in this Version of SBML Level 3 29 should always use the value of Avogadro's constant given above. (In other words, changes will apply 30 only beginning with a possible new Version of SBML Level 3 and not this existing version.) 31 • http://www.sbml.org/sbml/symbols/rateOf. This represents the instantaneous rate of change, with 32 respect to time, of an entity in the model. It is a function that takes a single argument, an identifier of 33 type SId. The allowable identifiers for use with rateOf in SBML Level 3 Version 2 Core are restricted to of that RateRule, using the current values of all symbols referenced in the rule's formula. 48 3. The rateOf for the amount of a Species having attribute boundaryCondition="false" and 1 appearing in one or more reactions can be calculated from the stoichiometries and KineticLaw Math 2 of every Reaction in which the species appears, plus appropriate conversionFactor values (see 3 Section 4.11.7 on p. 77). If the species quantity is in terms of its concentration, the rate must be 4 converted by the size of the Compartment in which it appears, which may itself be changing in 5 time. This can be calculated as follows, where [x] is the concentration of species X, x the amount 6 of species X, and V the size of the compartment in which species X is located: the rate of change is defined as the right-handed rateOf for the symbol, that is, the derivative with 23 respect to time of the symbol moving forward in time from the current time, and not the derivative 24 with respect to time from the recent past up until the current time. Thus, the rateOf of a symbol will 25 always be calculable from the set of current values of symbols in the model. No Event can affect the 26 rateOf for a symbol except indirectly.

27
In simulations that progress in a stepwise fashion, such as stochastic simulations, the rateOf csymbol is 28 still calculated as above, from any appropriate RateRule or KineticLaw. This effectively means that for 29 stepwise simulations, the rateOf indicates the expected average rate of change of the corresponding 30 symbol over time, even when the actual rate of change may be zero or discontinuous. 31 The following examples demonstrate these concepts. The XML fragment below encodes the formula x + t, 32 where t stands for time. 33 <math xmlns="http://www.w3.org/1998/Math/MathML"> In the fragment above, the use of the token t is mostly a convenience for human readers-the string inside the 43 csymbol could have been almost anything, because it is essentially ignored by MathML parsers and SBML. 44 It can even be empty. Some MathML and SBML processors will take note of the token and use it when 45 presenting the mathematical formula to users, but the token used has no impact on the interpretation of 46 the model and it does not enter into the SBML component identifier namespace. In other words, the SBML model cannot refer to t in the example above. The content of the csymbol element is for rendering purposes 48 only and can be ignored by the parser. 49 As a further example, the following XML fragment encodes the equation k + delay(x, 0.1) or, alternatively, The use of Avogadro's number is illustrated in the following XML fragment, which encodes the formula 15 avogadro * x: 16 <math xmlns="http://www.w3.org/1998/Math/MathML"> 17 <apply> 18 <times/> 19 <csymbol encoding="text" definitionURL="http://www.sbml.org/sbml/symbols/avogadro" /> 20 <ci> x </ci> 21 </apply> 22 </math> 23 Finally, the use of a rateOf function call is illustrated in the following XML fragment, and encodes the 24 formula k + rateOf (S1): <csymbol encoding="text" definitionURL="http://www.sbml.org/sbml/symbols/rateOf"/> 31 <ci> S1 </ci> 32 </apply> 33 </apply> 34 </math> 35 36 The principal use of SBML is to represent quantitative dynamical models whose behaviors manifest over 37 time. In defining an SBML model using constructs such as reactions, time is most often implicit and does 38 not need to be referred to in the mathematical expressions themselves. However, sometimes an explicit time 39 dependency needs to be stated, and for this purpose, the time csymbol (described above in Section 3.4.6) 40 may be used. This time symbol refers to "instantaneous current time" in a simulation, frequently given the 41 literal name t in one's equations. 42 An assumption in SBML is that "start time" or "initial time" in a simulation is zero, that is, if t 0 is the 43 initial time in the system, t 0 = 0. This corresponds to the most common scenario. Initial conditions in SBML 44 take effect at time t = 0. There is no mechanism in SBML for setting the initial time to a value other than 0. 3) can be used to express mathematical statements that hold true at 1 all moments, so using an assignment rule with the expression above will result in the value being equal to 2 t − 2 at every point in time. A parameter assigned this value could then be used elsewhere in the model. 3 3.4.8 Initial conditions and special considerations 4 The identifiers of Species, SpeciesReference, Compartment, Parameter, and Reaction object instances in a 5 given SBML model refer to the main symbols in a model. Depending on certain attributes of these objects 6 (e.g., the attribute constant on species, species references, compartments and parameters-this and other 7 conditions are explained in the relevant sections elsewhere in this document), some of the symbols may have 8 constant values throughout a simulation, and others' values may change. These changes in values over time 9 are determined by the system of equations constructed from the model's reactions, initial assignments, rules, 10 and events. 11 As described in Section 3.4.7, an SBML model's simulation is assumed to begin at t = 0. The availability of  16 The following is how the definitions of the model should be applied: 17 1. At time t i : 18 • Every Species, SpeciesReference, Compartment, Parameter, and package element with mathematical 19 meaning whose definition includes an initial value is assigned that value. If an element has 20 constant="false", its value may be changed by other constructs or reactions in a model according 21 to the steps below; if constant="true", only an InitialAssignment can override the value.

22
• All InitialAssignment definitions take effect, overriding any initial values on any Species, Species- 23 Reference, Compartment, Parameter, or package element with mathematical meaning. 24 • All AssignmentRule and AlgebraicRule definitions take effect. These rules also override any initial 25 values of any Species, SpeciesReference, Compartment, Parameter, or package element with math- 26 ematical meaning. Only elements set constant="false" can be affected in this way. (Note there 27 cannot be both an AssignmentRule and an InitialAssignment for the same identifier, nor may an 28 AlgebraicRule determine the value of any element that has an InitialAssignment; see Section 4.9.) 29 • The identifier of any Reaction has the value of its KineticLaw. This cannot yet affect the Species 30 referenced by the Reaction, but the identifier may appear in other Math elements calculated above. 31 • The value of any Event Trigger is the value of that Trigger's initialValue attribute. This cannot 32 be overridden. 33 2. For time t i < t < 0 34 • Any element with mathematical meaning with no InitialAssignment or Rule that targets it continues 35 to have its initial value, as defined by the relevant attribute. 36 • Any InitialAssignment definition continues to take effect. Since these contain mathematical formulas, 37 different values may be computed at each time step t in t i ≤ t ≤ 0.

38
• Any AssignmentRule or AlgebraicRule definition continues to take effect, and may not be overridden. 39 Again, different values may be computed at each time step t in t i ≤ t ≤ 0.  therefore cause the Event to trigger and its EventAssignment children to execute. This can happen 46 directly due to its value changing from an initialValue of "false" to a now-calculated value of 1 "true"; it can happen indirectly due to an event cascade initated by a direct change in a different 2 Event. (Note that an Event cannot be defined to change the value of a symbol that is also the 3 subject of an AssignmentRule, nor can it change the value of a symbol whose value is determined 4 by an AlgebraicRule; see Section 4.12 on p. 79.) 5 • The identifier of any Reaction continues to be the value of its KineticLaw. 6 • Any element with mathematical meaning with no InitialAssignment or Rule that targets it continues 7 to have its initial value, as defined by the relevant attribute, but may now be overridden by any 8 EventAssignment, executed as above. 9 • Any InitialAssignment definition continues to take effect, but may now be overridden by any 10 EventAssignment, executed as above. 11 • Any AssignmentRule or AlgebraicRule definition continues to take effect, and may not be overridden.

12
• Constraint definitions begin to take effect (and a constraint violation may result; see Section 4.10). 13 4. For time t > 0: 14 • The value of any element with mathematical meaning may now be overridden (subject to normal 15 restrictions) by any construct in SBML (though it may retain its original value if no such constructs 16 apply). 17 • The value of any element with an InitialAssignment may also now be overridden by any construct 18 in SBML (though it may retain the value set by the InitialAssignment if no such constructs apply). 19 • Any AssignmentRule or AlgebraicRule definition continues to take effect, and still may not be 20 overridden by any other SBML construct.

21
• RateRule definitions can begin to take effect.

22
• Any Reaction can begin to affect its referenced Species. Its identifier continues to have the value 23 of its KineticLaw. 24 • Each Event may fire, and their EventAssignment children execute.

25
• System simulation proceeds. 26 To reiterate: in modeling situations that do not involve the use of the delay csymbol, then t i becomes t i = 0, 27 but this does not alter the steps numbers 1-4 above. 28 3.4.9 Underdetermined models 29 A valid SBML model must not be overdetermined : the value of any symbol must not be established by more 30 than one construct in the model. The rules governing SBML constructs such as InitialAssignment and Rule 31 are designed to prevent the creation of overdetermined models because such models are self-contradictory. 32 The opposite situation, in which a model is under determined, is not invalid. An SBML model may contain 33 one or more symbols whose values are not established by the model directly, as when a Parameter has no 34 initialValue attribute and is not the target of an InitialAssignment or a relevant Rule object; a model may 35 also have multiple solutions, such as when an AlgebraicRule object determines either one-but not both-of 36 two different symbols in the model, or when an AlgebraicRule object has multiple solutions (such as 0 = x 2 −4).

37
Such models cannot be simulated without additional information, but although they are incomplete models, 38 they are not contradictory, and therefore not invalid. may provide the missing information needed to resolve the system, or provide a new context for the model 1 indicating the type(s) of analyses for which the model was designed. In all these scenarios, practical exigencies 2 demand that these SBML Level 3 Core models be considered valid even if they are incomplete (as long as the 3 parts that are present are not overdetermined or invalid for other reasons!). 4 SBML Level 3 Version 2 Core does not stipulate a particular course of action for handling underdetermined 5 models; software systems may handle them as they see fit. For example, numerical simulation systems could 6 reasonably refuse to process such models (and inform the user why); other types of software may find it more 7 appropriate to take other actions, such as asking the user to fill in the missing information. All SBML elements with mathematical meaning whose value can be assigned via a Rule have a constant 10 attribute that can be "true" or "false". One purpose of this attribute is to help model validation: if an 11 element that is meant to be constant appears as the target of (e.g.) a RateRule or an AssignmentRule, the 12 Model has an internal inconsistency that must be corrected before it can be interpreted properly. 13 Another use of the constant attribute is to provide information crucial to constructing systems of equations The constant attribute is also often used by software tools to determine how an element should be displayed 23 to the user. For example, an element marked constant="true" might be listed in a table along with its 24 (known, fixed) value, while an element marked constant="false" might be instead be displayed in a graph 25 with its value plotted over the time course of a simulation. Moreover, it may be possible for software to 26 implement more efficient internal handling of constant symbols.

3.4.11
MathML expression data types 28 MathML operators in SBML return results in one of two possible types: Boolean and numerical. By numerical 29 type, we mean either (1) a number in MathML real, integer, rational, or "e-notation" format; or (2) the 30 csymbol for time, the csymbol for the delay function, or the csymbol for the rateOf function described in 31 Section 3.4.6 on p. 25. However, a Boolean value may be used in a numerical context, and visa versa, as 32 described in Section 3.4.4 on p. 24. It is still important to understand which contexts are considered Boolean 33 and which are considered numeric, so the following guidelines summarize the different possible cases. 34 The relational operators (eq, neq, gt, lt, geq, leq), the logical operators (and, or, xor, not, implies), and 35 the Boolean constants (false, true) always return Boolean values, or 0 and 1 in numerical contexts. 36 The type of an operator referring to a FunctionDefinition is determined by the type of the top-level operator 37 of the expression in the math element of the FunctionDefinition instance, and can be Boolean or numerical.

38
All other operators, values and symbols return numerical results.

39
The roots of the expression trees used in the following contexts will be interpreted as Boolean values:

40
• the arguments of the MathML logical operators (and, or, xor, not, implies);

41
• the second argument of a MathML piece operator;

42
• the trigger element of an SBML Event; and 43 • the math element of an SBML Constraint. 44 The roots of the expression trees used in the following contexts can yield Boolean or numerical values:

45
• the arguments to the eq and neq operators;

46
• the first arguments of MathML piece and otherwise operators; and 1 • the top-level expression of a function definition.

2
The roots of expression trees in other contexts will be interpreted as numerical values. 3 The type of expressions should be used consistently. The set of expressions that make up the first arguments 4 of the piece and otherwise operators within the same piecewise operator should all return values of the 5 same type. The arguments of the eq and neq operators should return the same type.  as recommendations that should be followed except in special circumstances. 16 Recommendations for unit consistency of mathematical expressions 17 The consistency of units is defined in terms of dimensional analysis applied recursively to every operator and 18 function and every argument to them. second argument b is a rational number n/m, it should be possible to derive the m-th root of (a{unit}) n , 5 where {unit} signifies the unit associated with a; otherwise, (3) the unit of the first argument should be 6 "dimensionless". The second argument (b) should always have the unit of "dimensionless". 7 10. The two arguments to root, which are of the form root (n, a) with the meaning n √ a and where the 8 degree n is optional (defaulting to "2"), should be as follows: (1) if the optional degree qualifier n is an 9 integer, then it should be possible to derive the n-th root of a; (2) if the optional degree qualifier n is a 10 rational n/m then it should be possible to derive the n-th root of (a{unit}) m , where {unit} signifies 11 the unit associated with a; otherwise, (3) the unit of a should be "dimensionless". it is called (see below). If a FunctionDefinition's mathematical formula contains literal constants (i.e., 15 numbers within MathML cn elements with no sbml:units attribute), the units of the constants should 16 be identical in all contexts the function is called. 17 The units of other operators such as abs, floor, and ceiling, can be anything. 18 Item number 9 above, regarding FunctionDefinition, merits additional elaboration. An example may help 19 illustrate the problem. Suppose the formula x + 5 is defined as a function, where x is an argument and the 20 literal number 5 has no specified unit. If this function is called with an argument whose unit of measurement 21 is mole, the only possible consistent unit for the return value is mole. If in another context in the same model, the function is called with an argument whose unit of measurement is second, the function return value will 23 have a unit of second. would evaluate to "true". This is a trivial example, but the problem for SBML is that implicit unit conversions 10 of this kind can lead to controversial situations where even humans do not agree on the answer. Consequently, 11 SBML only requires that mathematical expressions be evaluated numerically. It is up to the model writer to 12 ensure that the units on both sides of an expression match, by inserting explicit unit conversion factors if 13 necessary. 14 4 SBML components 1 In this section, we define each of the major components of SBML. We use the UML notation described in 2 Section 1.4.3 for defining classes of objects. We also illustrate the use of SBML components by giving partial 3 model definitions in XML. Section 7 provides many complete example models encoded in SBML. 4 Unless otherwise specified, SBML Level 3 documents must follow the XML specification: anything allowed 5 in XML is allowed in SBML documents, and anything disallowed in XML is not allowed in SBML. All 6 well-formed SBML documents must begin with an XML declaration, specifying both the version of XML 7 used and the document character encoding. The declaration begins with the characters <?xml followed by the 8 attributes version and encoding. SBML requires XML version 1.0, and UTF-8 as the document encoding.   33 The actual model contained within an SBML document is defined by an instance of the Model class element. 34 The structure of this object and its use are described in Section 4.2 on p. 36. An SBML document may 35 contain at most one model definition. features on top of the core. This modular approach means that models can declare which feature-sets they 3 use, and likewise, software tools can declare which packages they support. The mechanism for models to 4 declare which packages they use involves two parts: a standard XML namespace declaration, and an attribute 5 that every package must declare in this namespace. 6 1. Every SBML Level 3 package is identified uniquely by an XML namespace URI. The use of a given 7 SBML Level 3 package must be declared by a model using the standard XML namespace declaration 8 approach. The declaration is made using the character sequence "xmlns:" (without the quotes), followed 9 by additional characters providing a prefix by which elements and attributes in that namespace are 10 known in the rest of the SBML document, and finally followed by the namespace URI as a value. The 11 following is an example of namespace declarations for a package nicknamed "comp" and another package 12 nicknamed "layout" (and here, ellipses are used to indicate content elided from this example): 13 <sbml xmlns="http://www.sbml.org/sbml/level3/version2/core" level="3" version="2" since it is the base package and support for it is required in any case.)

Model 13
The definition of Model is shown in Figure 10   Although the lists are optional, there are dependencies between SBML components such that defining 1 some components requires defining others. For example, defining a species requires defining a compartment, 2 and defining a species reference in a reaction requires defining a species. Such dependencies are explained 3 throughout this document. Model inherits an optional sboTerm attribute of type SBOTerm from its parent class SBase (see Section 3.1.12 6 and Section 5). When a value is given to this attribute in a Model instance, it should be an SBO identifier 7 belonging to the branch for type Model indicated in Table 6 on p. 98. The relationship is of the form "the 8 model definition is-a X", where X is the SBO term. The term chosen should be the most precise (narrow) 9 one that captures the overall process or phenomenon represented by the overall SBML model.

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

4.2.2
The substanceUnits attribute 13 The substanceUnits attribute is used to specify the unit of measurement associated with substance quantities 14 of Species objects that do not specify units explicitly. The attribute's value must be of type UnitSIdRef 15 (Section 3.1.10 on p. 13). A list of recommended units is given in Section 8.2.1 on p. 148. 16 If a given Species object definition does not specify its unit of substance quantity via the substanceUnits 17 attribute on Species (described in Section 4.6 on p. 49), then the species inherits the value of the Model 18 substanceUnits attribute. If the Model does not define a value for this attribute, then there is no unit to 19 inherit, and all species that do not specify individual substanceUnits attribute values then have no declared 20 units for their quantities. Section 4.6.4 provides more information about the units of species quantities.

21
Note that when the identifier of a species appears in a model's mathematical expressions, the unit of measurement associated with that identifier is not solely determined by setting substanceUnits on Model or 23 Species. Section 4.6.5 and Section 4.6.8 explain this point in more detail.

The timeUnits attribute 25
The timeUnits attribute is used to specify the unit in which time is measured in the model. The value of 26 this attribute must be of type UnitSIdRef (Section 3.1.10 on p. 13). A list of recommended units is given in 27 Section 8.2.1 on p. 148. 28 This attribute on Model is the only way to specify a unit for time in a model. It is a global attribute; time is 29 measured in the model everywhere in the same way. This is particularly relevant to Reaction and RateRule 30 objects in a model: all Reaction and RateRule objects in SBML define per-time values, and the unit of time is 31 given by the timeUnits attribute on the Model object instance. If the Model timeUnits attribute has no value, 32 it means that the unit of time is not defined for the model's reactions and rate rules. Leaving it unspecified 33 in an SBML model does not result in an invalid model; however, as a matter of best practice, we strongly 34 recommend that all models specify units of measurement for time.  36 The attributes volumeUnits, areaUnits and lengthUnits together are used to set the units of measurements 37 for the sizes of Compartment objects in the model when those objects do not otherwise specify units.

38
The three attributes correspond to the most common cases of compartment dimensions: volumeUnits 39 for compartments having attribute value spatialDimensions="3", areaUnits for compartments having 40 spatialDimensions="2", and lengthUnits for compartments having spatialDimensions="1". The values 41 of these attributes must be of type UnitSIdRef (Section 3.1.10 on p. 13). A list of recommended units is given 42 in Section 8.2.1 on p. 148. The attributes are not applicable to compartments whose spatialDimensions 43 attribute values are not one of "1", "2" or "3".
If a given Compartment object instance does not provide a value for its units attribute, then the unit of 45 measurement of that compartment's size is inherited from the value specified by the Model volumeUnits, 46 areaUnits or lengthUnits attribute, as appropriate based on the Compartment object's spatialDimensions 1 attribute value. If the Model object does not define the relevant attribute, then there are no units to inherit, 2 and all compartments that do not set a value for their units attribute then have no units associated with 3 their compartment sizes. Section 4.5.4 provides more information about units of compartment sizes. 4 The use of three separate attributes is a carry-over from SBML Level 2. Note that it is entirely possible 5 for a model to define a value for two or more of the attributes volumeUnits, areaUnits and lengthUnits 6 simultaneously, because SBML models may contain compartments with different numbers of dimensions. Reactions are processes that occur over time. These processes involve events of some sort, where a single 9 "reaction event" is one in which some set of entities (known as reactants, products and modifiers in SBML) 10 interact, once. The extent of a reaction is a measure of how many times the reaction has occurred, while the 11 time derivative of the extent gives the instantaneous rate at which the reaction is occurring. Thus, what is 12 colloquially referred to as the "rate of the reaction" is in fact equal to the rate of change of reaction extent. 13 The combination of extentUnits and timeUnits defines the units of kinetic laws in SBML and establishes  The attribute conversionFactor defines a global value inherited by all Species object instances that do not 22 define separate values for their conversionFactor attributes. The value of this attribute must be of type 23 SIdRef (Section 3.1.8 on p. 13) and refer to a Parameter object instance defined in the model. The Parameter 24 object in question must be a constant; i.e., it must have its constant attribute value set to "true".

25
If a given Species object definition does not specify a conversion factor via the conversionFactor attribute 26 on Species (described in Section 4.6 on p. 49), then the species inherits the conversion factor specified by 27 the Model conversionFactor attribute. If the Model does not define a value for this attribute, then there is 28 no conversion factor to inherit. Section 4.11.7 on p. 77 describes how to interpret the effects of reactions on 29 species in that situation. More information about conversion factors in SBML is provided in Section 4.6 on   32 The various ListOf classes defined in Figure 10  specifications to define new elements to be children of these lists, and for these child elements to be used 1 without the requirement that at least one SBML Level 3 Core element always be present. The FunctionDefinition object associates an identifier with a function definition. This identifier can then be 4 used as the function called in subsequent MathML apply elements. FunctionDefinition is shown in Figure 11. Function definitions in SBML (also informally known as "user-defined functions") have purposefully limited 6 capabilities. As is made clearer below, a function cannot reference parameters or other model quantities outside 7 of itself; values must be passed as parameters to the function. Moreover, recursive and mutually-recursive 8 functions are not permitted. The purpose of these limitations is to balance power against complexity of 9 implementation. With the restrictions as they are, function definitions could, if desired, be implemented as 10 textual substitutions. Software implementations therefore do not need the full function-definition machinery 11 typically associated with programming languages. FunctionDefinition inherits the id attribute from SBase, but defines id as being required rather than optional.

The ListOf container classes
14 The id attribute otherwise obeys the behavior described in Section 3.3 on p. 18.

15
A function's identifier can be used in math elements as the first target of an apply element, but the identifier 16 has no value associated with it, and may not be the target of an InitialAssignment, EventAssignment, or 17 Rule object in the model. MathML ci elements in an SBML model can refer to the function defined by a 18 FunctionDefinition using the value of its id attribute. The optional math element is a container for MathML content that defines the function. The content of 21 this element can only be a MathML lambda element or a MathML semantics element containing a lambda 22 element. FunctionDefinition is the only place in SBML Level 3 Core where a lambda element can be used. 23 If present, the lambda element must begin with zero or more bvar elements, followed by any other of the 24 elements in the MathML subset listed in Section 3.4.1 on p. 20 except lambda (i.e., a lambda element cannot 25 contain another lambda element). 26 A further restriction on the content of math is it cannot contain references to identifiers other than the symbols 27 declared in the lambda itself. That is, the contents of MathML ci elements inside the body of the lambda can 28 only be one of three kinds of identifiers: (i) the symbols declared by its bvar elements, or (ii) the identifiers 29 of other FunctionDefinition objects defined in the same model. This restriction also applies to the csymbol 30 elements for time, avogadro, delay, and rateOf. Functions must be written so that all model symbols they 31 use are passed to them via their parameters. 32 If the math element is not present in the FunctionDefinition, the function has no mathematical meaning defined 33 in SBML Level 3 Core. This situation may arise when models are incomplete, or when additional meaning or 34 subobjects are provided by an SBML Level 3 package. (However, from the perspective of a model reader that 1 only understands SBML Level 3 Core, the additional meaning will not be recognized.) FunctionDefinition inherits an optional sboTerm attribute of type SBOTerm from its parent class SBase (see 4 Section 3.1.12 and Section 5 on p. 91). When a value is given to this attribute in a FunctionDefinition instance, 5 it should be an SBO identifier belonging to the branch for type FunctionDefinition indicated in Table 6 on   6 p. 98. The relationship is of the form "the function definition is-a X", where X is the SBO term. The term 7 chosen should be the most precise (narrow) one that captures the role of the function in the model. As discussed in Section 5 on p. 91, SBO labels are optional information on a model. Applications are free to 9 ignore sboTerm values. A model must be interpretable without the benefit of SBO labels. packages. However, without additional content or meaning defined by SBML Level 3 packages, a call to a 17 function that has no math content is mathematically meaningless in a model. 18 Note that FunctionDefinition does not have a separate attribute for defining the unit of measurement associated 19 with the value returned by the function. The unit is taken to be whatever results from evaluating the expression

Examples 23
The following abbreviated SBML example shows a FunctionDefinition object instance defining pow3 as the 24 identifier of a function computing the mathematical expression x 3 , and after that, the invocation of that 25 function in the mathematical formula of a rate law. Note how the invocation of the function uses its identifier.     The unit of measurement associated with the value produced by a mathematical formula is whatever arises 2 naturally from the components and mathematical expressions comprising the formula, or in other words, the 3 unit obtained by doing dimensional analysis on the formula. To support this, units may be supplied in a 4 number of contexts in an SBML model and associated with a variety of components, and SBML provides a 5 facility for defining units that can be reused and referenced throughout a model. The unit definition facility 6 uses two classes of objects, UnitDefinition and Unit. Their definitions are shown in Figure 12 and explained in 7 more detail below. 8 Before delving further into the definition of SBML units, we must highlight two important and sometimes-9 confusing points. First, unit declarations in SBML models are optional. The consequence of this is that a 10 model must be numerically self-consistent independently of unit declarations, for the benefit of software with the example given in Section 7.2 on p. 115. 16 Second, the vast majority of situations that require new SBML unit definitions involve simple multiplicative 17 combinations of base units and factors. An example is "moles per litre per second". What distinguishes 18 these sorts of unit definitions from more complex ones is that they may be expressed without the use of an 19 additive offset from a zero point. The use of offsets complicates all unit definition systems, yet in the domain 20 of SBML, the real-life cases requiring offsets are few (and in fact, to the best of our knowledge, only involve 21 temperature). Consequently, the SBML unit system has been consciously designed to simplify implementation 22 of unit support for the most common cases in systems biology. The cost of this simplification is to require 23 units with offsets to be handled explicitly by the modeler. Section 8.2.1 on p. 148 discusses approaches for 24 handling situations requiring units with offsets. The approach to defining units in SBML is compositional; for example, metre second −2 is constructed by 27 combining a Unit object representing metre with another Unit object representing second −2 . The combination 28 is wrapped inside a UnitDefinition, which provides for assigning an identifier and optional name to the 29 combination. These object classes are defined in Figure 12. Once a unit is defined using a UnitDefinition object, 30 it can then be referenced from elsewhere in a model.    Figure 10). ListOfUnits has no attributes (beyond those it inherits from class SBase); it merely acts as a container for zero or more instances of Unit objects. Note that the only permitted values of kind on Unit are the reserved words in Table 2 on p. 44, but these symbols are excluded from the permitted values of UnitDefinition's id because SBML's unit system does not allow redefining the base units.
The id attribute 32 UnitDefinition inherits the id attribute from SBase, but defines id as being required rather than optional, 33 and in addition, refines the data type of id to be UnitSId instead of SId. This is done to provide each unit  Table 2 on the following page, the list of reserved 2 base unit names. This constraint simply prevents the redefinition of base units. 3 The list of Units 4 A UnitDefinition object may contain a ListOfUnits container which may contain zero or more Unit objects. 5 Section 4.4.2 explains the meaning and use of Unit. 6 In SBML Level 3 Version 2 Core, the list of units in a UnitDefinition object may be empty. This is permitted 7 for the same reasons that other lists are permitted to be empty. (See the discussion in Section 4.2.7 on p. 39.) 8 An empty unit definition is synonymous with an undefined unit. For example, suppose a given component in 9 a model is defined to have a unit of measurement "u". If the UnitDefinition object with identifier "u" has an 10 empty ListOfUnits subobject, then this is identical to leaving the unit undefined on the component. The following skeleton of a unit definition illustrates an example use of UnitDefinition:

Unit 29
A Unit object represents a reference to a (possibly transformed) base unit chosen from the list in Table 2 on 30 the next page. The attribute kind indicates the base unit, whereas the attributes exponent, scale, and 31 multiplier define how the base unit is being transformed. The attributes are described in detail below. 32 The kind attribute 33 The Unit attribute kind specifies a base unit to serve as the starting point for a new unit definition. The value 34 of the attribute must be taken from the list of reserved words given in Table 2 on the following page. These   The presence of avogadro in Table 2  substance amounts (e.g., "a mole of X " to mean a number of X equal to Avogadro's number, 6.022 · 10 23 ), 50 such usage is not strictly correct. We believe it is even less correct in the context of reactions: although in 51 SBML they are called "reactions", there is nothing preventing the SBML Reaction construct from being used 52 to represent other kinds of processes not involving substances. Consequently, we avoid using "mole" loosely 53 where substances may not be involved, and instead use "Avogadro's number of X ". In order to make it  Mesures, 2006), except for "avogadro", "dimensionless" and "item", which are SBML additions. The unit "dimensionless" is intended for cases where a quantity is a ratio whose units cancel out, the unit "avogadro" is the unit "dimensionless" multiplied with Avogadro's number, and "item" is used for expressing such things as "N items" when "mole" is not an appropriate unit. The gram and litre are not strictly part of SI; however, they are frequently used in SBML's areas of application and therefore are included as predefined unit identifiers. (The standard SI unit of mass is the kilogram, and volume in SI is defined in terms of cubic metres.) Comparisons of these values, like all values of type UnitSId, must be performed in a case-sensitive manner. easier for models to define units in these terms, the SBML unit system includes the pseudo-unit "avogadro", 19 whose definition is identical to the definition of the avogadro csymbol described in Section 3.4.6 on p. 25.

20
The numerical value is taken to be the one recommended by CODATA (  The exponent, scale and multiplier attributes 30 The attributes exponent, scale and multiplier work together to permit the use of Unit for expressing new 31 units in terms of the base units listed in Table 2. The formula underlying this definition is the following: 32 u new = (multiplier · 10 scale · u kind ) exponent (1) 33 This formula defines a new unit, u new , in terms of another unit, u kind . The unit u kind is one of the units listed 34 in • The multiplier attribute can be used to multiply the kind unit by a real-numbered factor. This 38 enables the definition of units that are not power-of-ten multiples of SI units. For instance, a multiplier 39 of 0.3048 could be used to define "foot" as a measure of length in terms of a "metre". A value of 40 multiplier must always be provided in a Unit object instance, but the value can be "1".

41
• The scale attribute can be used to set the exponent for a power-of-ten multiplier that rescales the unit.

42
For example, a unit having a kind value of "gram" and a scale value of "-3" signifies 10 −3 · gram, or 43 milligrams. In those cases where a unit does not need to be scaled by a power of ten, the value of scale 44 can be set to "0" (zero), because 10 0 = 1.

45
• The exponent attribute can be used to specify an overall exponent on the unit definition. This provides 46 a way to define units such as "cubic metre" in terms of the base unit "metre" (for which an exponent value of "3" would be appropriate). A value of exponent must always be provided.

Semantics of Unit and UnitDefinition 49
A single Unit object instance takes one of the base units from Table 2 and specifies how it should be transformed.

50
A UnitDefinition object instance combines one or more Unit objects to define a new, composed unit, u. The new 51 unit u created by a UnitDefinition is defined as the product of all the Unit objects contained in the ListOfUnits 1 within the UnitDefinition object instance. More formally, u = (m 1 · 10 s1 · u b1 ) x1 · (m 2 · 10 s2 · u b2 ) x2 · . . . · (m n · 10 sn · u bn ) xn As a concrete example to illustrate the definitions above, let us define a unit for "foot" in terms of the base 18 unit "metre". This requires using multiplier="0.3048", scale="0", and exponent="1": The following fragment of SBML illustrates how this could be represented in XML: <unit kind="mole" exponent="1" scale="-3" multiplier="1"/> 34 <unit kind="litre" exponent="-1" scale="0" multiplier="1"/> 35 <unit kind="second" exponent="-1" scale="0" multiplier="1"/>  An example may help make this more clear. We know that one metre equals 1000 millimetres: 3 1 m = 1000 mm 4 However, the equality above relies on interpreting the units on both sides, and taking the "1" and "1000" to 5 be dimensionless. If readers ignored unit labels altogether or were unable to process them, they would see which is obviously incorrect. In an SBML model, the necessary factor must be included explicitly, even if it is 8 part of the definition of the unit. A ramification of this is that units attached to SBML quantities must be 9 viewed as a kind of independent annotation or label that does not enter into the numerical interpretation 10 of the actual quantity or the mathematical formulas appearing in a model. In the present simple formula, 11 an explicit factor such as the following needs to be inserted (and here we put unit names in { } braces to 12 indicate they are annotations that do not enter into the mathematics): This is despite the fact that a unit definition for millimetres in SBML would take the following form:

Compartments 32
A compartment in SBML represents a bounded space in which species are located. Compartments do not 33 necessarily have to correspond to actual structures inside or outside of a biological system, although models 34 are often designed that way. The definition of Compartment is shown in Figure 13 on the following page. 35 It is important to note that although compartments are optional in the overall definition of Model, every 36 species in an SBML model must be located in a compartment. This in turn means that if a model defines any 37 species, the model must also define at least one compartment. The reason is simply that species represent 38 physical things, and therefore must exist somewhere. Compartments represent the somewhere.  volve compartments with integer values of spatialDimensions="3" (i.e., a three-dimensional compartment, 6 which is to say, a volume), spatialDimensions="2" (i.e., a two-dimensional compartment, a surface), or 7 spatialDimensions="1" (i.e., a one-dimensional compartment, which is to say, a line). However, SBML 8 Level 3 does not restrict compartments' spatialDimensions values, in order to allow for the possibility of 9 representing structures with fractal dimensions.

10
In SBML Level 3 Version 2 Core, the number of spatial dimensions possessed by a compartment cannot 11 enter into mathematical formulas, and therefore cannot directly alter the numerical interpretation of a model.

12
However, the value of spatialDimensions does affect the interpretation of units. Specifically, the value of 13 spatialDimensions is used to select among the Model attributes volumeUnits, areaUnits and lengthUnits 14 when a Compartment object does not define a value for its units attribute. This is described in more detail 15 below in Section 4.5.4 on the following page. The optional Compartment attribute size, with a data type of double, can be used to set the initial size of 18 the compartment. The size may correspond to a volume (if the compartment is a three-dimensional one), or it 19 may be an area (if the compartment is two-dimensional), or a length (if the compartment is one-dimensional).

20
A compartment's size is set by its size attribute exactly once. If the compartment's attribute constant has 21 the value "true", then the compartment's size is fixed and cannot be changed except by an InitialAssignment in 22 the model. The approach of using an InitialAssignment differs from setting the size attribute in that size can 23 only be used to set the compartment size to a literal floating-point number, whereas InitialAssignment allows 24 the value to be set using an arbitrary mathematical expression (which, thanks to MathML's expressiveness, 25 may evaluate to a rational number). If the compartment's constant attribute is "false", the size value may 26 be overridden by an InitialAssignment or changed by an AssignmentRule or AlgebraicRule, and in addition,

27
for simulation time t > 0, it may also be changed by a RateRule or Event. (However, some constructs are 28 mutually exclusive; see Section 4.9 on p. 59 and Section 4.12 on p. 79.) It is not an error to set the value of 29 size on a compartment and also redefine the value using an InitialAssignment, but the original size value in 30 that case is ignored. Section 3.4.8 provides additional information about the semantics of assignments, rules 31 and values for simulation time t ≤ 0.

32
It is important to note that in SBML Level 3, a missing size value does not imply that the compartment 33 size is "1". A missing value for size for a given compartment signifies that the value either is unknown, 34 or to be obtained from an external source, or determined by an initial assignment (Section 4.8 on p. 56) 35 or other SBML construct elsewhere in the model. Further, due to the fact that alternative methods exist for setting the size of a compartment, the size attribute must be defined as optional; however, it is good practice to specify a value for the size of every compartment in a model, no matter what method is used, 1 when compartment size values are available. The reasons for this are explained in Section 8.2.2 on p. 150. The measurement unit associated with the value of the compartment's size attribute may be specified using 4 the optional attribute units. This attribute's value must have the data type UnitSIdRef (Section 3.1.10). 5 The units attribute may be left unspecified for a given compartment in a model; in that case, the compartment 6 inherits the unit of measurement specified by one of the attributes on the enclosing Model object instance. 7 The applicable attribute on Model depends on the value of the compartment's spatialDimensions attribute; 8 the relationship is shown in The unit of measurement associated with a compartment's size, as defined by the units attribute or (if units 18 is not set) the inherited value from Model according to Table 3, is used in the following ways: 19 • When the identifier of the compartment appears as a numerical quantity in a mathematical formula  Compartment inherits an optional sboTerm attribute of type SBOTerm from its parent class SBase (see Sec-4 tion 3.1.12 on p. 14 and Section 5 on p. 91). When a value is given to this attribute in a Compartment instance, 5 it should be an SBO identifier belonging to the branch for type Compartment indicated in Table 6 on p. 98. 6 The relationship is of the form "the compartment is-a X", where X is the SBO term. The term chosen should 7 be the most precise (narrow) one that captures the role of the compartment in the model.

8
As discussed in Section 5 on p. 91, SBO labels are optional information on a model. Applications are free to 9 ignore sboTerm values. A model must be interpretable without the benefit of SBO labels. The following example illustrates three compartments in an abbreviated SBML example of a model definition.

Species 32
A species in SBML refers to a pool of entities that (a) are considered indistinguishable from each other for 33 the purposes of the model, (b) may participate in reactions, and (c) are located in a specific compartment. 34 The SBML Species object class is intended to represent these pools. Its definition is shown in Figure 14    in Table 6 on p. 98. The relationship is of the form "the species is-a X", where X is the SBO term. The term 1 chosen should be the most precise (narrow) one that captures the role of the species in the model.

2
As discussed in Section 5 on p. 91, SBO labels are optional information on a model. Applications are free to 3 ignore sboTerm values. A model must be interpretable without the benefit of SBO labels. The required attribute compartment, of type SIdRef, is used to identify the compartment in which the species 6 is located. The attribute's value must be the identifier of an existing Compartment object in the model. Note  The optional attributes initialAmount and initialConcentration, both having a data type of double, can 12 be used to set the initial quantity of the species in the compartment where the species is located. These values implies that their values either are unknown, or to be obtained from an external source, or determined 16 by an initial assignment (Section 4.8 on p. 56) or other SBML construct elsewhere in the model.

17
A species' initial quantity is set by the initialAmount or initialConcentration attributes exactly once. 18 If the constant attribute is "true", then the value of the species' quantity is fixed and cannot be changed 19 except by an InitialAssignment. These methods differ in that the initialAmount and initialConcentration 20 attributes can only be used to set the species' quantity to a literal floating-point number, whereas the 21 use of an InitialAssignment object allows the value to be set using an arbitrary mathematical expression 22 (which, thanks to MathML's expressiveness, may evaluate to a rational number). If the species' constant 23 attribute is "false", the species' quantity value may be overridden by an InitialAssignment or changed by 24 AssignmentRule or AlgebraicRule, and in addition, for t > 0, it may also be changed by a RateRule, Event, 25 and as a result of being a reactant or product in one or more Reaction constructs. (However, some constructs 26 are mutually exclusive; see Section 4.9 on p. 59 and Section 4.12 on p. 79.) It is not an error to define 27 initialAmount or initialConcentration on a species and also redefine the value using an InitialAssignment, 28 but the initialAmount or initialConcentration setting in that case is ignored. Section 3.4.8 provides 29 additional information about the semantics of assignments, rules and values for simulation time t ≤ 0. 30 When the attribute initialAmount is set, the unit of measurement associated with its value is specified by 31 the Species attribute substanceUnits, whose value must have the data type UnitSIdRef (Section 3.1.10 on 32 p. 13). When the initialConcentration attribute is set, the unit of measurement associated with this 33 concentration value is {unit of amount}/{unit of size}, where the unit of amount is specified by the Species substanceUnits attribute, and the unit of size is specified by the units attribute of the Compartment object 1 in which the species is located. Note that in either case, a unit of amount is involved and determined by 2 the substanceUnits attribute. If the substanceUnits attribute is not set on a given Species object instance, 3 then the unit of amount for that species is inherited from the substanceUnits attribute on the enclosing 4 Model object instance. If that attribute on Model is not set either, then the unit associated with the species' 5 quantity is undefined. Leaving units of species quantities undefined in an SBML model does not render the 6 model invalid; however, as a matter of best practice, we strongly recommend that all models specify the units 7 of measurement for all species quantities. A list of recommended units is given in Section 8.2.1 on p. 148.

8
Simply setting initialAmount or initialConcentration alone does not determine whether a species identifier 9 represents an amount or a concentration when it appears elsewhere in an SBML model. Instead, that aspect 10 is controlled by the attribute hasOnlySubstanceUnits, discussed in Section 4.6.5 below. hasOnlySubstanceUnits has the value "true", then the value is interpreted as having a unit of amount only. 18 Although it may seem as though this intention could be determined by either (i) determining whether the 19 initialAmount or initialConcentration attribute is set on a given Species object or (ii) examining the 20 particular unit declared by the Species or Model object's substanceUnits attributes, the fact that all of these 21 attributes are optional means that a separate flag is needed. (Consider the situation where neither is set, 22 and instead the species' quantity is established by an InitialAssignment or AssignmentRule-something else is 23 then needed to indicate whether the species' identifier represents a concentration or an amount.) 24 The unit of measurement associated with a species' quantity is used in the following ways in SBML:

25
• When the species' identifier appears in a MathML formula (discussed in Section 3.4.3 on p. 23), it 26 represents the species' quantity, and the unit of measurement associated with the quantity is as described 27 above.

28
• The math elements of AssignmentRule, InitialAssignment and EventAssignment objects referring to this 29 species should all have the same units as the unit of measurement associated with the species quantity. 30 • In a RateRule object that defines the rate of change of the species' quantity, the unit associated with  The Species object has two other mandatory boolean attributes named constant and boundaryCondition, 35 used to indicate whether and how the amount of that species can vary during a simulation. Table 4 on the 36 next page shows how to interpret the combined values of the boundaryCondition and constant attributes.

37
When a species is a product or reactant of one or more reactions, its amount is determined by those reactions.

46
In SBML, it is possible to indicate that a given species' amount is not determined by the set of reactions even when that species occurs as a product or reactant; i.e., the species is on the boundary of the reaction 48 system, and its amount is not determined by the reactions. The boolean attribute boundaryCondition with 49 value "true" can be used to indicate this. A value of "false" indicates that the species is part of the reaction 50 system.

51
The constant attribute indicates whether the species' amount can be changed at all, regardless of whether 52 by reactions, rules, or constructs other than InitialAssignment. A value of "false" indicates that the species' 53 amount can be changed. This is the most common situation because the purpose of many models is precisely 54 to calculate changes in species quantities over time. Note that the initial quantity of a species can be set by 55 an InitialAssignment irrespective of the value of the constant attribute. 19 In practice, a boundaryCondition value of "true" means a differential equation derived from the reaction 20 definitions should not be generated for the species. However, the species' amount may still be changed by has boundaryCondition="false" and constant="true", then it cannot appear as a reactant or product, or 28 as the target of any AssignmentRule, RateRule or EventAssignment object in the model.  The attribute conversionFactor defines a conversion factor that applies to a particular species. The value 39 of the attribute must have the data type SIdRef and must be the identifier of a Parameter object instance 40 defined in the model. That Parameter object must be a constant, meaning its constant attribute must be set 41 to "true". If a given Species object definition defines a value for its conversionFactor attribute, it takes 42 precedence over any factor defined by the Model object's conversionFactor attribute.

43
In SBML, the unit of measurement associated with a species' quantity can be different from the unit of extent  Note that the unit conversion factor is only applied when calculating the effect of a reaction on a species. It 50 is not used in any rules or other SBML constructs that affect the species, and it is also not used when the 51 value of the species is referenced in a mathematical expression. identifier when it is referenced in a mathematical formula or in rules or other SBML constructs; however, it 5 remains to specify what happens to a species when the compartment in which it is located changes in size. 6 When a species definition has the attribute value hasOnlySubstanceUnits="false" and the size of the 7 compartment in which the species is located changes, the default in SBML is to assume that it is the 8 concentration that must be updated to account for the size change. This follows from the principle that, 9 all other things held constant, if a compartment simply changes in size, the size change does not in itself 10 cause an increase or decrease in the number of entities of any species in that compartment. In a sense, the 11 default is that the amount of a species is preserved across compartment size changes. Upon such size changes, 12 the value of the concentration or density must be recalculated from the simple relationship concentration 13 = amount/size if the value of the concentration is needed (for example, if the species identifier appears 14 in a mathematical formula or is otherwise referenced in an SBML construct). There is one exception: if 15 the species' quantity is determined by an AssignmentRule, RateRule, AlgebraicRule, or an EventAssignment 16 and the species has the attribute value hasOnlySubstanceUnits="false", it means that the concentration 17 is assigned by the rule or event; in that case, the amount must be calculated when the compartment size 18 changes. (Events also require additional care in this situation, because an event with multiple assignments 19 could conceivably reassign both a species quantity and a compartment size simultaneously. Section 4.12.5 on 20 p. 86 describes the handling of species in event assignments.)

21
Note that the above only matters if a species has the attribute value hasOnlySubstanceUnits="false", 22 meaning that the species identifier refers to a concentration wherever the identifier appears in a mathematical 23 formula. If instead the attribute's value is "true", then the identifier of the species always stands for an 24 amount wherever it appears in a mathematical formula or is referenced by an SBML construct. In that case, 25 there is never a question about whether an assignment or event is meant to affect the amount or concentration: 26 it is always the amount.

27
A particularly confusing situation can occur when the species has attribute value constant="true" in 28 combination with attribute value hasOnlySubstanceUnits="false". Suppose this species is given a value 29 for initialConcentration. Does constant="true" mean that the concentration is held constant if the 30 compartment size changes? No; it is still the amount that is kept constant across a compartment size change. 31 The fact that the species was initialized using a concentration value is irrelevant.

Parameters 44
A Parameter is used in SBML to define a symbol associated with a value; this symbol can then be used in 45 mathematical formulas in a model. The definition of Parameter is shown in Figure 15 on the following page.

46
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 48 this, no one has yet found an adequate replacement term that does not have different connotations to different  Parameter inherits the id attribute from SBase, but on Parameter it is defined as being required instead of 11 optional. The attribute otherwise behaves as described in Section 3.3 on p. 18.

12
A parameter's identifier (its id attribute value) may be used in a model's mathematical expressions. The 13 identifier stands for the value of the parameter, with a unit of measurement as described in Section 4.7.3 on 14 the following page. It may be the target of InitialAssignment, EventAssignment, or Rule objects elsewhere in 15 a model, to set or redefine the value of the parameter. 16 A Parameter id will most often represent a double value, but the identifier may be used in other contexts. 17 For example, it is possible to have a Parameter that is only assigned Boolean values and only used in Boolean 18 contexts. The units of such a Parameter should be dimensionless. In such cases, it would also be appropriate 19 to set the Parameter's sboTerm attribute to the value for "logical parameter" ("SBO:0000602"). The optional attribute value determines the value (of type double) assigned to the identifier. A missing 22 value implies that the value either is unknown, or to be obtained from an external source, or determined by 23 an initial assignment (Section 4.8 on p. 56) or other SBML construct elsewhere in the model.

24
A parameter's value is set by its value attribute exactly once. If the parameter's constant attribute (Sec-25 tion 4.7.4) has the value "true", then the value is fixed and cannot be changed except by an InitialAssignment. 26 These two methods of setting the parameter's value differ in that the value attribute can only be used to set 27 it to a literal floating-point number, whereas InitialAssignment allows the value to be set using an arbitrary 28 mathematical expression (which, thanks to MathML's expressiveness, may evaluate to a rational number). If 29 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, 31 it may also be changed by a RateRule or Event. (However, some of these constructs are mutually exclusive; 32 see Section 4.9 and Section 4.12.) It is not an error to define value on a parameter and also redefine the value 33 using an InitialAssignment, but the value in that case is ignored. Section 3.4.8 on p. 28 provides additional 34 information about the semantics of assignments, rules and values for simulation time t ≤ 0. The unit of measurement associated with the value of the parameter can be specified using the optional 2 attribute units. The attribute's value must have the data type UnitSIdRef (Section 3.1.10 on p. 13). There 3 are no constraints on the units that can be assigned to parameters in a model; there are also no units to 4 inherit from the enclosing Model object (unlike the case for, e.g., Species and Compartment). 5 The unit of measurement associated with a parameter's value is used in the following ways: 6 • When the identifier of the parameter appears as a numerical quantity in a mathematical formula   What if a parameter has its constant attribute set to "false", but the model does not contain any rules, 25 events or other constructs that ever change its value over time? Although the model may be suspect (why is 26 the parameter in question not flagged as being constant?), this situation is not strictly an error. A value of 27 "false" for constant only indicates that a parameter can change value, not that it must. Parameter inherits an optional sboTerm attribute of type SBOTerm from its parent class SBase (see Sec-30 tion 3.1.12 on p. 14 and Section 5 on p. 91). When a value is given to this attribute in a Parameter instance, 31 it should be an SBO identifier belonging to the branch for type Parameter indicated in Table 6 on p. 98. The 32 relationship is of the form "the parameter is-a X", where X is the SBO term. The term chosen should be the 33 most precise (narrow) one that captures the role of the parameter in the model. 34 As discussed in Section 5 on p. 91, SBO labels are optional information on a model. Applications are free to 35 ignore sboTerm values. A model must be interpretable without the benefit of SBO labels. <parameter id="tau2" value="3e-2" units="second" constant="true"/> 42 <parameter id="Km1" value="10.7" units="molesperlitre" constant="true"/> 43 </listOfParameters> 44 ...

45
</model> 46 4.8 Initial assignments 1 SBML Level 3 Version 2 Core provides two ways of assigning initial values to entities in a model. The simplest 2 and most basic is to set the values of the appropriate attributes in the relevant components; for example, 3 the initial value of a model parameter (whether it is a constant or a variable) can be assigned by setting its 4 value attribute directly in the model definition (Section 4.7). However, this approach is not suitable when 5 the value must be calculated, because the initial value attributes on different components such as species, 6 compartments, and parameters are single values and not mathematical expressions. This is the reason for As explained below, the provision of InitialAssignment does not mean that models necessarily must use this 11 construct when defining initial values of quantities. If a value can be set using the relevant attribute of a 12 component in a model, then that approach may be more efficient and more portable to other software tools.

13
InitialAssignment should be used when the other mechanism is insufficient for the needs of a particular model.   The value of the symbol attribute must be the identifier of an object in the SId namespace of the model; 27 moreover, the object must be of a class that is defined to have mathematical meaning in SBML. In SBML Level 3 28 Core, the types of objects whose identifiers are permitted as the values of InitialAssignment symbol attributes 29 are Compartment, Species, SpeciesReference and (global) Parameter objects in the model. In addition, classes 30 of objects defined by SBML Level 3 packages to have mathematical meaning may also be defined by those 31 packages to be permissible targets of InitialAssignment objects; in other words, InitialAssignment symbol 32 attributes may also reference identifiers in the SId namespace defined by SBML Level 3 packages. 33 An initial assignment cannot be made to reaction identifiers; that is, the symbol attribute value of an 34 InitialAssignment cannot be an identifier that is the id attribute value of a Reaction object in the model. This 35 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 36 FunctionDefinition.

37
If the symbol attribute of an InitialAssignment object references an object in an SBML namespace that is not 1 recognized by the interpreter reading a given SBML document (that is, if the object is defined by an SBML 2 Level 3 package that the software does not support), the assignment must be ignored-the symbol must if an SBML package is present in the SBML document with a package:required attribute of "true".) The math element contains a MathML expression used to calculate the value of the entity referenced by symbol. 9 The unit of measurement associated with the value should match the unit associated with the identifier given 10 in the symbol attribute.

11
An InitialAssignment with no math child leaves undefined what assignment is to be made to the corresponding 12 symbol. The absence of a math element is permitted because it is possible for SBML Level 3 packages to add 13 constructs that extend InitialAssignment and define how a value is to be computed. In the absence of such  be an SBO identifier belonging to the branch for type InitialAssignment indicated in Table 6 on p. 98. The 24 relationship is of the form "the initial assignment is-a X", where X is the SBO term. The term chosen should 25 be the most precise (narrow) one that captures the role of the initial assignment in the model. 26 As discussed in Section 5 on p. 91, SBO labels are optional information on a model. Applications are free to 27 ignore sboTerm values. A model must be interpretable without the benefit of SBO labels.  29 The value calculated by an InitialAssignment object overrides the value assigned to the given symbol by the 30 object defining that symbol. For example, if a Compartment's size is set in its definition, and the model 31 also contains an InitialAssignment having that compartment's id as its symbol value, then the interpretation 32 is that the size assigned in the Compartment object definition should be ignored and the value assigned 33 based on the computation defined in the InitialAssignment. For SBML Level 3 Core, initial assignments can 34 take place for Compartment, Species, SpeciesReference and global Parameter objects regardless of the value 35 of their constant attribute. 36 This does not mean that a definition of a symbol can be omitted if there is an InitialAssignment object for 37 that symbol; the symbols must always be defined even if they are assigned a value separately. For example, 38 there must be a Parameter definition for a given parameter if there is an InitialAssignment for that parameter.

39
The actions of all InitialAssignment objects are in general terms the same, but differ in the precise details product referenced by the SpeciesReference object to the value determined by the formula in math.

47
The unit associated with the value produced by the math formula should be consistent with the unit 1 dimensionless, because reactant and product stoichiometries in reactions are dimensionless quantities.

2
• In the case of a compartment, an InitialAssignment sets the referenced compartment's initial size to of that type (if objects of that class are defined by the package as having the same units). 15 In the context of a simulation, initial assignments establish values that are in effect prior to and including the

20
There cannot be two initial assignments for the same symbol in a model; that is, a model must not contain 21 two or more InitialAssignment objects that both have the same identifier as their symbol attribute value. A 22 model must also not define initial assignments and assignment rules for the same entity. That is, there cannot 23 be both an InitialAssignment and an AssignmentRule for the same symbol in a model, because both kinds of 24 constructs apply prior to and at the start of simulated time-allowing both to exist for a given symbol would 25 result in indeterminism. (See also Section 4.9.5 on p. 64.) 26 The ordering of InitialAssignment objects in a model is not significant. The collection of InitialAssignment,

27
AssignmentRule and KineticLaw objects forms a set of assignment statements that must be considered as a 28 whole. The combined set of assignment statements should not contain algebraic loops: a chain of dependency 29 between these statements should terminate. (More formally, consider the directed graph of assignment 30 statements where nodes are a model's assignment statements and directed arcs exist for each occurrence of a 31 symbol in an assignment statement math attribute. The directed arcs in this graph start from statements 32 assigning the symbol and end at statements containing the symbol in their math elements. Such a graph must 33 be acyclic.) Examples of valid and invalid set of assignment statements are given in Section 4.9.5 on p. 64. 34 Finally, it is worth being explicit about the expected behavior in the following situation. Suppose (1) a given 35 symbol has a value x assigned to it in its definition, (2) there is an initial assignment having the identifier 36 as its symbol value and reassigning the value to y, and (3) the identifier is also used in the mathematical 37 formula of a second initial assignment. What value should the second initial assignment use? It is y, the value 38 assigned to the symbol by the first initial assignment, not whatever value was given in the symbol's definition.

39
This follows directly from the behavior at the defined at the beginning of this section and in Section 3.4.8 on 40 p. 28: if an InitialAssignment object exists for a given symbol, then the symbol's value is overridden by that 41 initial assignment. The following example shows how the species "x" can be assigned the initial value 2 · y, where "y" is an <species id="x" compartment="C" substanceUnits="mole" hasOnlySubstanceUnits="true" boundaryCondition="false" The next example illustrates the more complex behavior discussed above, when a symbol has a value assigned 16 in its definition but there also exists an InitialAssignment for it and another InitialAssignment uses its value 17 in its mathematical formula. <species id="x" initialAmount="50" compartment="C" substanceUnits="item" 20 hasOnlySubstanceUnits="true" boundaryCondition="false" constant="false"/> The value of "othersymbol" in the SBML fragment above will be "20". The case illustrates the rule of thumb 42 that if there is an initial assignment for a symbol, the value assigned to the symbol in its definition (here, the 43 value of initialAmount) must be ignored and the value created by the initial assignment used instead. Algebraic left-hand side is zero: Assignment left-hand side is a scalar: In their general form given above, there is little to distinguish between assignment and algebraic rules. • SBML needs to place restrictions on assignment rules, for example the restriction that assignment rules 4 cannot contain algebraic loops (discussed further in Section 4.9.5 on p. 64);

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

8
• Those simulators that can solve these algebraic equations make a distinction between the different 9 categories listed above; and 10 • Some specialized numerical analyses of models may only be applicable to models that do not contain 11 algebraic rules.

12
The approach taken to covering these cases in SBML is to define an abstract Rule class containing an element, 13 math, to hold the right-hand side expression, then to derive subclasses of Rule that add attributes to distinguish 14 the cases of algebraic, assignment and rate rules. Figure 17 gives the definitions of Rule and the subclasses 15 derived from it. The figure shows there are three subclasses, AlgebraicRule, AssignmentRule and RateRule 16 derived directly from Rule. These correspond to the cases Algebraic, Assignment, and Rate described above, 17 respectively.  19 The classes derived from Rule inherit math and the attributes and elements that Rule itself inherits from 20 SBase, including id, name, and sboTerm.

21
The id attribute 22 Rule inherits an optional id attribute from SBase, of type SId. The identifier of a Rule-derived object has no 23 mathematical meaning in an Level 3 Version 2 Core model. 24 The math element 25 A Rule object has an optional element called math, containing a MathML expression defining the mathematical 26 formula of the rule. This MathML formula must return a numerical value. The formula can be an arbitrary 27 expression referencing the variables and other entities in an SBML model. The interpretation of math and its 28 associated unit of measurement are described in more detail in Section 4.9.2, Section 4.9.3 and Section 4.9.4.

60
A Rule with no math child element leaves undefined how the rule behaves mathematically. The Rule math 1 element is defined as optional in SBML Level 3 Core because it is possible for SBML Level 3 packages to add 2 constructs that extend Rule and define the missing behavior. In the absence of such constructs in a given 3 model, no assignments or other changes to the model are carried out when there is no math element. This 4 leaves the model unchanged: any SBML component that had a value will continue to have that value; any 5 component whose value was undefined will continue to have an undefined value. A simulator encountering 6 this situation may choose to produce a warning. No other validation rules are affected by the absence of a 7 Rule math element: it is still invalid to have an InitialAssignment and an AssignmentRule that assign to the 8 same model element, for example. 9 The sboTerm attribute 10 Rule inherits an optional sboTerm attribute of type SBOTerm from its parent class SBase (see Section 3.1.12 on 11 p. 14 and Section 5 on p. 91). When a value is given to this attribute in an AlgebraicRule, AssignmentRule, 12 or RateRule instance, it should be an SBO identifier belonging to the branch for type AlgebraicRule, Assign-13 mentRule, or RateRule indicated in Table 6 on p. 98. The relationship is of the form "the rule is-a X", where 14 X is the SBO term. The term chosen should be the most precise (narrow) one that captures the role of the 15 rule in the model. 16 As discussed in Section 5 on p. 91, SBO labels are optional information on a model. Applications are free to 17 ignore sboTerm values. A model must be interpretable without the benefit of SBO labels.

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

22
In the context of a simulation, algebraic rules are in effect at all times, t ≥ 0. To allow evaluating expressions 23 that involve the delay csymbol (Section 3.4.6), algebraic rules are considered to apply also at t ≤ 0. Section 3.4.8 24 describes the semantics of assignments, rules, and entity values for simulation time t ≤ 0.

25
An SBML model must not be overdetermined. The ability to define arbitrary algebraic expressions in an 26 SBML model introduces the possibility that a model is mathematically overdetermined by the overall system 27 of equations constructed from its rules, reactions and events. Therefore, if an algebraic rule is introduced in 28 a model, for at least one of the entities referenced in the rule's math element the value of that entity must 29 not be completely determined by other constructs in the model. This means that at least this entity must 30 not have the attribute constant="true" and there must also not be a rate rule or assignment rule for it. 31 Furthermore, if the entity is a Species object, its value must not be determined by reactions, which means 32 that it must either have the attribute boundaryCondition="false" or else not be involved in any reaction 33 at all. These restrictions are explained in more detail in Section 4.9.5 below. 34 Reaction identifiers can be referenced in the math expression of an algebraic rule, but reaction rates can never 35 be determined by algebraic rules. This is true even when a reaction does not contain a KineticLaw element. 36 (In such cases of missing KineticLaw elements, the model is valid but incomplete; the rates of reactions lacking 37 kinetic laws are simply undefined, and not determined by the algebraic rule.) 38 Finally, any symbol that appears as the target of a rateOf csymbol may not be determined by an AlgebraicRule. 39 This is because the rateOf csymbol is defined as applying only to symbols whose rates of change are easily 40 determinable.

41
Although the rules above directly stipulate the symbols that may not be determined by the AlgebraicRule 42 construct, note that they can also be used to discover the symbol that is determined by a given Alge-43 braicRule object. For instance, if three symbols appear in the math portion of AlgebraicRule, and the first has 44 constant="true" and the second symbol is a Reaction identifier, one may deduce that the AlgebraicRule is 45 being used to determine the value of the third symbol that appears in the mathematical expression. This  The rule type AssignmentRule is used to express equations that set the values of variables. The left-hand 2 side (the required variable attribute) of an assignment rule is of type SIdRef, and must refer to an SBML 3 object in the SId namespace with mathematical meaning and the ability to be assigned. In SBML Level 3 4 Core, this consists of Species, SpeciesReference, Compartment, and global Parameter objects in the model 5 (but not reactions nor function definitions). The entity identified must have its constant attribute set to 6 the value "false". The effects of an AssignmentRule are in general terms the same, but differ in the precise 7 details depending on the type of variable being set: 8 • In the case of a species, an AssignmentRule sets the referenced species' quantity (whether a concentration 9 or amount) to the value determined by the formula in math. The unit associated with the value produced 10 by the math formula should be equal to the unit associated with the species' quantity. (See Section 4.6.5 on 11 p. 51 for an explanation of how a species' quantity is determined.)

12
Restrictions: There must not be both an AssignmentRule variable attribute and a SpeciesReference 13 species attribute having the same value, unless that species has its boundaryCondition attribute set to 14 "true". In other words, an assignment rule cannot be defined for a species that is created or destroyed 15 in a reaction unless that species is defined as a boundary condition in the model. 16 • In the case of a species reference, an AssignmentRule sets the stoichiometry of the corresponding reactant 17 or product to the value determined by the formula in math. The unit associated with the value produced 18 by the math formula should be consistent with the unit dimensionless, because reactant and product 19 stoichiometries in reactions are dimensionless quantities. of that class are defined by the package as having the same units). 32 If the variable attribute of an AssignmentRule object references an object in an SBML namespace not 33 recognized by the interpreter reading a given SBML document (that is, if the object is defined by an SBML 34 Level 3 package that the software does not support), the assignment rule must be ignored-the object's value The value calculated by an AssignmentRule object overrides the value assigned to the given symbol by the 3 object defining that symbol. For example, if a Compartment's size is set in its definition, and the model also 4 contains an AssignmentRule having that compartment's id as its variable value, then the size assigned  The rule type RateRule is used to express equations that determine the rates of change of variables. The 11 left-hand side (the required variable attribute) of a rate rule has type SIdRef, and must refer to an SBML 12 object in the SId namespace with mathematical meaning and the ability to be assigned. In Level 3 Core, 13 this consists of Species, SpeciesReference, Compartment, and global Parameter objects in the model (but not 14 reactions nor function definitions). The entity identified must have its constant attribute set to "false". 15 The effects of a RateRule are in general terms the same, but differ in the precise details depending on which 16 variable is being set: 17 • In the case of a species, a RateRule sets the rate of change of the species' quantity (concentration or  Restrictions: There must not be both a RateRule variable attribute and a SpeciesReference species 23 attribute having the same value, unless that species has its boundaryCondition attribute is set to 24 "true". This means a rate rule cannot be defined for a species that is created or destroyed in a reaction, 25 unless that species is defined as a boundary condition in the model.  If the variable attribute of a RateRule object references an object in an SBML namespace that is not 44 recognized by the interpreter reading a given SBML document (that is, if the object is defined by an SBML 45 Level 3 package that the software does not support), the rate rule must be ignored-the object's value must In the context of a simulation, rate rules are in effect for simulation time t > 0. Other types of rules and 3 initial assignments are in effect at different times; Section 3.4.8 on p. 28 describes these conditions. 4 As mentioned in Section 4.9.3 for AssignmentRule, a model must not contain more than one RateRule or 5 AssignmentRule object having the same value of variable; in other words, in the set of all assignment rules 6 and rate rules in an SBML model, each variable appearing in the left-hand sides can only appear once. This 7 simply follows from the fact that an indeterminate system would result if a model contained more than one 8 assignment rule for the same variable or both an assignment rule and a rate rule for the same variable. An important design goal of SBML rule semantics is to ensure that a model's simulation and analysis results 11 will not be dependent on when or how often rules are evaluated. To achieve this, SBML needs to place 12 two additional restrictions on rule use in addition to the conditions described above regarding the use of 13 AlgebraicRule, AssignmentRule and RateRule. The first concerns algebraic loops in the system of assignments 14 in a model, and the second concerns overdetermined systems. 15 The model must not contain algebraic loops 16 The combined set of InitialAssignment, AssignmentRule and KineticLaw objects constitute a set of assignment 17 statements that should be considered as a whole. (A KineticLaw object is counted as an assignment because 18 it assigns a value to the symbol contained in the id attribute of the Reaction object in which it is defined.) 19 This combined set of assignment statements must not contain algebraic loops-dependency chains between 20 these statements must terminate. To put this more formally, consider a directed graph in which nodes are 21 assignment statements and directed arcs exist for each occurrence of an SBML species, species reference, 22 compartment or parameter symbol in an assignment statement's math element. Let the directed arcs point 23 from the statement assigning the symbol to the statements that contain the symbol in their math element 24 expressions. This graph must be acyclic. the RateRule objects, and the species attributes of the SpeciesReference objects in each Reaction). These 28 rates of change may be referenced directly using the rateOf csymbol, but may not thereby contain algebraic 29 loops-dependency chains between these statements must terminate. More formally, consider a directed graph 30 in which the nodes are the definitions of different variables' rates of change, and directed arcs exist for each 31 occurrence of a variable referenced by a rateOf csymbol from any RateRule or KineticLaw object in the model. 32 Let the directed arcs point from the variable referenced by the rateOf csymbol (call it x ) to the variable(s) 33 determined by the math expression in which x appears. This graph must be acyclic. 34 SBML does not specify when or how often rules should be evaluated. Eliminating algebraic loops ensures 35 that assignment statements can be evaluated any number of times without the result of those evaluations 36 changing. As an example, consider the following equations: If this set of equations were interpreted as a set of assignment statements, it would be invalid because the 39 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  assignments for the particular event. 6 One approach is to construct a bipartite graph in which one set of vertices represents the variables and the 7 other set of vertices represents the equations. The approach involves placing edges between vertices such 8 that variables in the system are linked to the equations that determine them. A mathematical model is 9 overdetermined if the maximal matchings (Chartrand, 1977) of the bipartite graph contain disconnected 10 vertexes representing equations. (If one maximal matching has this property, then all the maximal matchings 11 will have this property; i.e., it is only necessary to find one maximal matching.) Appendix Section B describes 12 a method of applying this procedure to specific SBML data objects. In some cases it is possible to avoid the 13 use of an AlgebraicRule. This is discussed in more detail in Section 8.2.3 on p. 151. 14 4.9.6 Example of rule use 15 This section contains an example set of rules. Consider the following set of equations: This can be encoded by the following scalar rule set (where the definitions of x, s, k, k2, k3 and A are assumed 18 to be located elsewhere in the model and not shown in this abbreviated example): The Constraint object is a mechanism for stating the assumptions under which a model is designed to operate.

2
The constraints are statements about permissible values of different quantities in a model. Figure 18 shows  The id attribute 12 Constraint inherits an optional id attribute from SBase, of type SId. The identifier of a Constraint object has 13 no mathematical meaning in an SBML Level 3 Version 2 Core model. 14 The sboTerm attribute 15 Constraint inherits an optional sboTerm attribute of type SBOTerm from its parent class SBase (see Sec-16 tion 3.1.12 on p. 14 and Section 5 on p. 91). When a value is given to this attribute in a Constraint instance, 17 it should be an SBO identifier belonging to the branch for type Constraint indicated in Table 6 on p. 98. The 18 relationship is of the form "the constraint is-a X", where X is the SBO term. The term chosen should be the 19 most precise (narrow) one that captures the role of the constraint in the model.

20
As discussed in Section 5 on p. 91, SBO labels are optional information on a model. Applications are free to 21 ignore sboTerm values. A model must be interpretable without the benefit of SBO labels. in Section 4.10.3 below. 28 A Constraint with no math child does not define a mathematical constraint. The absence of a math element is 1 permitted because it is possible for SBML Level 3 packages to add constructs that extend Constraint and 2 define how a value is to be computed. In the absence of any such construct, no restriction on the model's 3 behavior is implied. A simulator encountering this situation may choose to produce a warning. A Constraint object can contain an optional element named message whose content is determined by object 6 class Message. This element can contain a message in XHTML format that may be displayed to the user 7 when the condition of the constraint in math evaluates to a value of "false". Software tools are not required 8 to display the message, but it is recommended that they do so as a matter of best practice. 9 The XHTML content within a Message object must follow the same restrictions as for Notes objects described 10 in Section 3.2.5 on p. 15. In particular, the element must declare the use of the XHTML XML namespace, 11 and must not contain an XML declaration nor a DOCTYPE declaration.   As an example, the following SBML fragment demonstrates the constraint that species "S1" should only have 29 values between 1 and 100:  A reaction in SBML represents any kind of process that can change the quantity of one or more species in a 2 model. Examples of such processes can include transformation, transport, molecular interactions, and more. 3 In SBML, the notion of a reaction is generalized to allow entities that may not be chemical substances; thus, 4 a reaction in SBML does not necessarily have to be a biochemical reaction-a biochemical reaction is just 5 one possible kind of process. 6 At minimum, to describe a reaction in SBML, it is necessary to define its structural properties, specifically 7 the participating reactants and/or products (and their corresponding stoichiometries) and the reversibility 8 of the process. In addition, an SBML reaction can also contain a quantitative description of the rate of the 9 reaction; this aspect consists of a mathematical formula expressing describing the rate at which the reaction 10 process takes place, together with an optional list of modifier species and parameters influencing the reaction

Reaction 1
Each reaction in an SBML model is defined using an instance of a Reaction object. As shown in Figure 19 on 2 the previous page, it contains several scalar attributes and several lists of other objects. 3 The id attribute 4 Reaction inherits the id attribute from SBase; however, Reaction defines id as being required rather than 5 optional. The attribute otherwise behaves as described in Section 3.3 on p. 18. 6 The identifier (the id attribute value) of a Reaction object may be used in mathematical expressions in a 7 model. The identifier stands for the reactions rate; this role and the units of measurement associated with 8 the reaction identifier are explained in more detail in Section 4.11.8 on p. 79. A reaction's identifier cannot be 9 the target of an InitialAssignment, EventAssignment, or Rule object, nor may its value be determined by an 10 AlgebraicRule object in a model. 11 The lists of reactants, products and modifiers 12 Each species participating as a reactant, product, and/or modifier in a reaction must be declared using 13 a SpeciesReference and/or ModifierSpeciesReference object stored in the list elements listOfReactants, 14 listOfProducts and listOfModifiers. The object classes SpeciesReference and ModifierSpeciesReference 15 are described in more detail in Section 4.11.3 and Section 4.11.4 below. Throughout this text, we use the 16 informal expressions "list of reactants", "list of products" and "list of modifiers" to mean, respectively, the 17 list of species identified by SpeciesReference objects within a Reaction listOfReactants element, the list see Section 4.6.6 on p. 51 for more information. 24 • Any species appearing in the math element of the kineticLaw of a Reaction instance must be declared in 25 at least one of that Reaction's lists of reactants, products, and/or modifiers. It is an error for a reaction's 26 kinetic law formula to refer to species that have not been declared for that reaction.

27
• A reaction definition can contain an empty list of reactants or an empty list of products, but it must 28 have at least one reactant or product; in other words, a reaction without any reactant or product species 29 is not permitted. (This restriction does not apply to modifier species, which are always optional.) 30 The kineticLaw element 31 A Reaction object can contain up to one KineticLaw object, in the kineticLaw element. This "kinetic law" 32 defines the speed at which the process defined by the reaction takes place. A more detailed description of 33 KineticLaw is left to Section 4.11.5 on p. 74 below. 34 The inclusion of a KineticLaw object in an instance of a Reaction is optional. For some modeling purposes, 35 models containing reactions without defined rates are an acceptable alternative (and may even be the only 36 possible option, such as when the kinetics of the reactions are unknown). However, missing kinetic laws 37 preclude the application of many model analysis techniques, including simulation. In the absence of any 38 additional definition, some simulators choose to give an error and refuse to simulate models that have a 39 Reaction with no KineticLaw. Others assume that the effective rate of a Reaction with no KineticLaw is zero.

40
Still others define this value to be "not a number" (NaN). This behavior is not standardized, and should not 41 be relied on when exchanging models for simulation.

42
The reversible attribute 1 The mandatory boolean attribute reversible on Reaction indicates whether the reaction is reversible. To 2 say that a reaction is reversible is to say it can proceed in either the forward or the reverse direction. This 3 information may be redundant in cases where the reversibility of the reaction can be deduced by inspecting 4 the rate formula given in the kinetic law. However, a reaction is not required to have a kinetic law, and besides, 5 when a rate expression is present, it may not always be possible to deduce the reversibility by inspecting it. 6 Having a separate attribute for reversible allows certain kinds of structural analysis, such as elementary 7 mode analysis, even in these cases. 8 Mathematically, the reversible attribute on Reaction has no impact on the construction of the equations 9 for change of the species' quantities. However, labeling a reaction as irreversible is interpreted as an assertion 10 that the rate expression will not have negative values during a simulation. Software developers may wish to 11 provide their software systems with a means of testing that this condition holds.

12
The presence of reversibility information in two places (i.e., the rate expression in the kinetic law, and the 13 reversible flag) leaves open the possibility that a model could contain contradictory information, but this 14 would be considered to be an error of the encoded model, rather than an invalid SBML encoding. 15 The fast attribute (removed) 16 In SBML Level 3 Version 2, the fast attribute has been removed: every Reaction in a Level 3 Version 2 17 Core model is equivalent to an SBML Level 3 Version 1 Reaction with a fast value of "false". This means 18 that for Level 3 Version 2 Core, the speed of every Reaction will always be determined by its KineticLaw. To 19 achieve the same or similar effects as setting the fast attribute to "true" in a previous version of SBML, 20 the KineticLaw should be constructed to produce a value in the desired time scale, or the reaction can be 21 replaced with an AssignmentRule or AlgebraicRule object as in the example of Section 7.5 on p. 124.

22
The compartment attribute on Reaction 23 The optional attribute compartment, of data type SIdRef, can be used to indicate the compartment in 24 which the reaction is assumed to take place. If the attribute is present, its value must be the identifier of a 25 Compartment object defined in the enclosing Model object. 26 Similar to the reversible attribute, the value of the compartment attribute has no direct impact on the 27 construction of mathematical equations for the SBML model. When a reaction has a kinetic law, the 28 compartment location may already be implicit in the kinetic law (though this cannot always be guaranteed). 29 Nevertheless, software tools may find the compartment attribute value useful for such purposes as analyzing 30 the structure of the model, guiding the modeler in constructing correct rate formulas, and visualization. 31 The sboTerm attribute on Reaction 32 Reaction inherits an optional sboTerm attribute of type SBOTerm from its parent class SBase (see Sec-33 tion 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 34 should be an SBO identifier belonging to the branch for type Reaction indicated in Table 6 on p. 98. The 35 relationship is of the form "the reaction is-a X", where X is the SBO term. The term chosen should be the 36 most precise (narrow) one that captures the role of the reaction in the model.

37
As discussed in Section 5 on p. 91, SBO labels are optional information on a model. Applications are free to 38 ignore sboTerm values. A model must be interpretable without the benefit of SBO labels. As mentioned above, every species that enters into a given reaction must appear in that reaction's lists of 41 reactants, products and/or modifiers. In an SBML model, all species that may participate in any reaction are 42 listed in the ListOfSpecies object of the top-level Model object instance (see Section 4.2 on p. 36). The lists of 43 products, reactants and modifiers in Reaction objects do not introduce new species, but rather, they refer 44 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. 1 SimpleSpeciesReference, defined in Figure 19 on p. 68, is an abstract type that serves as the parent class of 2 both SpeciesReference and ModifierSpeciesReference. It is used simply to hold the attributes and elements 3 that are common to the latter two objects. 4 The species attribute 5 The SimpleSpeciesReference object class has a required attribute, species, of data type SIdRef, inherited 6 by SpeciesReference and ModifierSpeciesReference. The value of species must be the identifier of a species 7 defined in the enclosing Model; the referenced species is thereby declared as participating in the reaction being 8 defined. The precise role of that species as a reactant, product, or modifier in the reaction is determined by 9 the subtype of SimpleSpeciesReference (i.e., either SpeciesReference or ModifierSpeciesReference) in which 10 the identifier appears and by the specific list of species references in which the SpeciesReference appears. 11 The sboTerm attribute 12 SimpleSpeciesReference inherits an optional sboTerm attribute of type SBOTerm from its parent class SBase 13 (see Section 3.1.12 and Section 5). When a value is given to this attribute in a SimpleSpeciesReference 14 instance, it should be an SBO identifier belonging to the branch for type SimpleSpeciesReference indicated 15 in Table 6 on p. 98. The relationship is of the form "the species reference is-a X", where X is the SBO term. 16 The term chosen should be the most precise (narrow) one that captures the role of the species reference in 17 the model. 18 As discussed in Section 5 on p. 91, SBO labels are optional information on a model. Applications are free to 19 ignore sboTerm values. A model must be interpretable without the benefit of SBO labels. Reaction provides a way to express which species act as reactants and which species act as products in a 22 reaction, and to declare their stoichiometries. This is done using SpeciesReference objects. As mentioned 23 above in Section 4.11.2 on the previous page, SpeciesReference inherits the mandatory attribute species 24 and optional attributes id, name, and sboTerm from the parent type SimpleSpeciesReference. It also defines 25 the optional attribute stoichiometry and the mandatory attribute constant, described below. 26 The id attribute 27 The id attribute that SpeciesReference inherits from SBase is still optional, and behaves as described in 28 Section 3.3 on p. 18. It also acquires the mathematical meaning of the value of its stoichiometry attribute, 29 and may be the target of an InitialAssignment, EventAssignment, or Rule object defined in the enclosing model. 30 The stoichiometry attribute 31 The stoichiometry of a species in a reaction describes how much of the species changes when a reaction event 32 takes place. In SBML, product and reactant stoichiometries are specified using the optional stoichiometry on 33 SpeciesReference object. The stoichiometry attribute is of type double. A missing stoichiometry implies 34 that the stoichiometry is either unknown, or to be obtained from an external source, or determined by an 35 initial assignment (Section 4.8 on p. 56) or other SBML construct elsewhere in the model. 36 A species reference's stoichiometry is set by its stoichiometry attribute exactly once. If the SpeciesReference 37 object's constant attribute (see below) has the value "true", then the stoichiometry is fixed and cannot 38 be changed except by an InitialAssignment. These two methods of setting the stoichiometry (i.e., using 39 stoichiometry directly, or using an InitialAssignment) differ in that the stoichiometry attribute can only be 40 set to a literal floating-point number, whereas InitialAssignment allows the value to be set using an arbitrary 41 mathematical expression. (As an example, the approach could be used to set the stoichiometry to a rational 42 number of the form p/q, where p and q are integers, something that is occasionally useful in the context of 43 biochemical reaction networks.) If the species reference's constant attribute has the value "false", the species 44 reference's value may be overridden by an InitialAssignment or changed by AssignmentRule or AlgebraicRule, 45 and in addition, for simulation time t > 0, it may also be changed by a RateRule or Event. (However, some of 1 these constructs are mutually exclusive; see Section 4.9 on p. 59 and Section 4.12 on p. 79.) It is not an error 2 to define stoichiometry on a species reference and also redefine the stoichiometry using an InitialAssignment, 3 but the stoichiometry attribute in that case is ignored. Section 3.4.8 on p. 28  found in searches such as https://scholar.google.com/scholar?q=model+variable+stoichiometry. 7 An explanation of how exactly the stoichiometry is used in the mathematical interpretation of the model is 8 given in Section 4.11.7 on p. 77. 9 The constant attribute 10 The SpeciesReference attribute constant is a mandatory boolean attribute used to indicate whether the 11 stoichiometry value can vary during a simulation. If constant="true", the corresponding species' sto-12 ichiometry in the reaction cannot be changed by other constructs elsewhere in the model except by an 13 InitialAssignment. A value of "false" means the stoichiometry can be changed by other SBML constructs 14 such as rules (see Section 4.9 on p. 59), as described above in the section on the stoichiometry attribute. 15 Use of species reference identifiers in mathematical expressions 16 The value of the id attribute of a SpeciesReference can be used as the content of a ci element in MathML 17 formulas elsewhere in the model. When the identifier appears in a ci element, it represents the stoichiometry 18 of the corresponding species in the reaction where the SpeciesReference object instance appears. More 19 specifically, it represents the value of the stoichiometry attribute on the SpeciesReference object.

20
The unit of measurement associated with a SpeciesReference's stoichiometry value 21 The unit associated with the value of a species' stoichiometry is always considered to be dimensionless. This 22 has the following implications: 23 • When a species reference's identifier appears in mathematical formulas elsewhere in the model, the unit 24 associated with that value is dimensionless.

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

27
• If a species reference's identifier is the subject of a RateRule, the unit associated with the RateRule object's  The following is a simple example of a species reference for species "X0", with stoichiometry "2", in a list of 32 reactants within a reaction having the identifier "J1":  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: indicates the species is effectively a reactant. SBML places no restrictions on the effective stoichiometry of a 28 species in a reaction; for example, it can be zero. In the following SBML fragment, the two reactions have the 29 same effective stoichiometry for all their species: 30 <reaction id="x" reversible="false"> 31 <listOfReactants> 32 <speciesReference species="a" stoichiometry="1" constant="true"/> 33 <speciesReference species="a" stoichiometry="1" constant="true"/> 34 <speciesReference species="b" stoichiometry="1" constant="true"/> 35 </listOfReactants> 36 <listOfProducts> 37 <speciesReference species="c" stoichiometry="1" constant="true"/> 38 <speciesReference species="b" stoichiometry="1" constant="true"/> 39 </listOfProducts> 40 </reaction> 41 <reaction id="y" reversible="false"> 42 <listOfReactants> 43 <speciesReference species="a" stoichiometry="2" constant="true"/> 44 </listOfReactants> 45 <listOfProducts> 46 <speciesReference species="c" stoichiometry="1" constant="true"/> Sometimes a species appears in the kinetic rate formula of a reaction but is neither created nor destroyed in 51 that reaction (for example, because it acts as a catalyst or inhibitor). In SBML, all such species are simply 52 called modifiers without regard to the detailed role of those species in the model (though a model could use 53 SBO terms to clarify the roles; see Section 5 on p. 91). The Reaction object class provides a way to express 54 which species act as modifiers in a given reaction. This is the purpose of the list of modifiers available in 55 Reaction. The list contains instances of ModifierSpeciesReference object.

56
Because its sibling class SpeciesReference has mathematical meaning, it is probably worth noting that no 57 meaning is assigned to the identifier of ModifierSpeciesReference object instances in SBML Level 3 Version 2 58 Core, but the identifiers are available for possible use by SBML Level 3 packages. Note that modifiers in 59 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 1 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 3 same reaction where it is designated as a modifier, as well as to appear in the list of reactants, products and 4 modifiers of other reactions in the model. The KineticLaw object class is used to describe the rate at which the process defined by the Reaction takes 7 place. As shown in Figure 19 on p. 68, KineticLaw has elements called math and listOfLocalParameters, in 8 addition to the attributes and elements it inherits from SBase. 9 The id attribute 10 KineticLaw inherits an optional id attribute from SBase, of type SId. Despite having a math child, the id of 11 a KineticLaw takes on no mathematical meaning; the value of that math element is instead associated with 12 the enclosing Reaction object's identifier. 13 The math element 14 As shown in Figure 19 on p. 68, KineticLaw has an element called math for holding a MathML formula defining 15 the rate of the reaction. The expression in math may refer to global identifiers defined in the model as well 16 as LocalParameter object identifiers from the KineticLaw's list of local parameters (see below). However, the 17 only Species identifiers that can be used in math are those declared in the lists of reactants, products and 18 modifiers in the Reaction object (see Section 4.11.2, Section 4.11.3 and Section 4.11.4). 19 Section 4.11.7 provides important discussions about the meaning and interpretation of SBML "kinetic laws". but has no mathematical formula for the kinetics of the reaction involved. 26 The list of local parameters 27 An instance of KineticLaw can contain a list of zero or more LocalParameter objects (Section 4.11.6 on the next 28 page) defining new parameters whose identifiers can be used in the math formula. These "local parameters" 29 are optional-a kinetic law can always refer to global Parameter objects. The local parameter facility simply 30 provides a way to add additional parameters that may be relevant only to a specific reaction, and that may 31 therefore be better handled by encapsulating their definitions within that kinetic law. 32 As discussed in Section 3.3.1 on p. 18, reactions introduce local namespaces for local parameter identifiers, 33 and within a KineticLaw object (as well as within the parent Reaction), a local parameter whose identifier is 34 identical to a global identifier defined in the model takes precedence over the value associated with the global 35 identifier. Note that this introduces the potential for a local parameter definition to shadow a global identifier.  The sboTerm attribute 41 KineticLaw inherits an optional sboTerm attribute of type SBOTerm from its parent class SBase (see Sec-42 tion 3.1.12 on p. 14 and Section 5 on p. 91). When a value is given to this attribute in a KineticLaw instance, 43 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 1 most precise (narrow) one that captures the role of the kinetic law in the model.

2
As discussed in Section 5 on p. 91, SBO labels are optional information on a model. Applications are free to 3 ignore sboTerm values. A model must be interpretable without the benefit of SBO labels.  Figure 19 on p. 68. 9 The id attribute 10 LocalParameter inherits the id attribute from SBase; however, LocalParameter defines id as being required 11 rather than optional, and in addition, its type is defined to be the derived type of LocalSId instead of SId. It 12 otherwise behaves as described in Section 3.3 on p. 18.

13
The identifier (the id attribute value) of a LocalParameter may be used in the mathematical expression the package construct with locally-scoped parameters to reference. 28 The value attribute 29 The optional attribute value determines the value (of type double) assigned to the identifier. A missing 30 value attribute implies that the value either is unknown, or to be obtained from an external source. (Note 31 that, unlike the case with global Parameter objects, there is no way in SBML Level 3 Version 2 Core for 32 InitialAssignment or other SBML constructs to be used for setting the value of LocalParameter objects, because 33 local parameters are local to reactions.) 34 The units attribute 35 The unit of measurement associated with the value of the parameter can be specified using the optional 36 attribute units. The attribute's value must have the data type UnitSIdRef (Section 3.1.10 on p. 13). There 37 are no constraints on the units that can be assigned to local parameters in a model; there are also no units to 38 inherit from the enclosing Model object (unlike the case for, e.g., Species and Compartment). 39 The units attribute is used in the following way: when a local parameter's identifier appears in the content 40 of the math element of the enclosing KineticLaw object, the unit of measurement associated with the local 41 parameter's value is determined by the LocalParameter object's units attribute.
The sboTerm attribute 1 LocalParameter inherits an optional sboTerm attribute of type SBOTerm from its parent class SBase (see 2 Section 3.1.12 and Section 5). When a value is given to this attribute in a LocalParameter instance, it should 3 be an SBO identifier belonging to the branch for type LocalParameter indicated in Table 6 on p. 98. The 4 relationship is of the form "the local parameter is-a X", where X is the SBO term. The term chosen should 5 be the most precise (narrow) one that captures the role of the local parameter in the model. 6 As discussed in Section 5 on p. 91, SBO labels are optional information on a model. Applications are free to 7 ignore sboTerm values. A model must be interpretable without the benefit of SBO labels. The following is an example of a Reaction object that defines a reaction with identifier J 1 , in which X 0 → S 1 10 at a rate given by k · [X 0 ] · [S 2 ], where S 2 is a catalyst and k is a parameter, and the square brackets symbolizes 11 that the species quantities are in terms of concentrations. The reaction is assumed to take place all in 12 one compartment identified as "c1". The example demonstrates the use of species references, KineticLaw 13 objects and local parameters. The units associated with the species identifiers here are amount/volume (see 14 Section 4.6 on p. 49), and so the rate expression k ·[X 0 ]·[S 2 ] needs to be multiplied by the compartment volume 15 (represented by its identifier, "c1") to produce the desired units of amount/time for the rate expression. 16 <model timeUnits="second" extentUnits="mole" substanceUnits="mole"> 17 <listOfUnitDefinitions> 18 <unitDefinition id="per_concent_per_time"> 19 <listOfUnits> 20 <unit kind="litre" exponent="1" scale="0" multiplier="1"/> 21 <unit kind="mole" exponent="-1" scale="0" multiplier="1"/> <unit kind="second" exponent="-1" scale="0" multiplier="1"/> <species id="S1" compartment="c1" initialConcentration="2.0" 31 hasOnlySubstanceUnits="false" boundaryCondition="false" constant="false"/> 32 <species id="S2" compartment="c1" initialConcentration="0.5" 33 hasOnlySubstanceUnits="false" boundaryCondition="false" constant="false"/> 34 <species id="X0" compartment="c1" initialConcentration="1.0" In SBML, reactions are the central mechanism for describing processes that change the quantities of species 2 in a model. The kinetic law of an SBML reaction provides a quantitative description of the speed with 3 which this happens. In this section, we provide an interpretation of SBML kinetic laws in the framework 4 of a system of ordinary differential equations (ODEs). However, the choice of ODEs as the framework is 5 only for exposition purposes here, in order to allow us to present a concrete mathematical expression of the 6 model in terms that many readers will be familiar with; it is equally possible to translate a model into other 7 frameworks, and some formulations, such as discrete stochastic systems, are indeed quite common.

8
Semantics of rate law and stoichiometry 9 The stoichiometry of a species S in a reaction describes the proportion, relative to other species participating 10 in that reaction, of S involved in each reaction event. For example, in a reaction S 1 + 2S 2 → S 3 , twice as  It is important to make clear that a "kinetic law" in SBML is not identical to a traditional rate law. When modeling; they are listed in Table 5 along with the problems they entail. 20 Table 5: Assumptions behind "traditional" rate laws, and the problems they imply for general multicompartmental modeling.

22
Assumption Problem 23 All species that participate in a given reaction are located in one compartment SBML must support reaction processes (e.g., transport) that move species between compartments 24 Compartments are three-dimensional volume containers SBML must support models where reactions may take place at interfaces (e.g., 2-D membranes) between compartments, thus involving compartments with different dimensions and S 2 , with S 1 located in a compartment having volume V 1 , and S 2 located in a compartment having volume 28 V 2 . Let the volume V 2 = 3V 1 . Now consider a transport reaction S 1 → S 2 in which the species S 1 is moved 29 from the first compartment to the second. Assume we only want to model the overall effect, without getting 30 into the molecular details (which might in reality involve such things as pores in a membrane between the 31 compartments). Let us use the simplest type of chemical kinetics, in which the rate of the transport reaction 32 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 33 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 34 to its concentration [S 1 ]. The rate expression will therefore be k · [S 1 ], with k having the unit 1/time. Then: So far, this looks normal-until we consider the number of molecules of S 1 that disappear from the compartment 37 of volume V 1 and appear in the compartment of volume V 2 . The number of molecules of S 1 (call this n S1 ) is 38 given by [S 1 ] · V 1 and the number of molecules of S 2 (call this n S2 ) is given by [S 2 ] · V 2 . Since our volumes have the relationship V 2 /V 1 = 3, the relationship above implies that n S1 = k · [S 1 ] · V 1 molecules disappear from 1 the first compartment per unit of time and n S2 = 3 · k · [S 1 ] · V 1 molecules appear in the second compartment.

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

11
In multicompartmental models, to be able to specify a rate law only once and then use it unmodified in 12 equations for different species, the rate law needs to be expressed in terms of an intensive property, that is, 13 species quantity/time, rather than the extensive property typically used, species quantity/size/time. As a 14 result, modelers and software tools in general cannot insert traditional textbook rate laws unmodified into 15 the math element of a KineticLaw. The unusual term "kinetic law" was chosen to alert users to this difference. 16 Constructing rate-of-change equations for the species 17 A consequence of the approach to "kinetic laws" discussed in the previous section is this: when constructing

38
There are three possible cases to consider when constructing rate-of-change equations for the species: Section 4.6.7 on p. 52). The formula for the rate of change of S i 's amount then becomes the following: In Section 8.2.4, we present some recommendations for how to encode rate laws and models in SBML.

12
Species with negative or zero values 13 In many models, a Species will represent an amount of a physical entity. In those cases, the level of that species   and ListOfEventAssignments are derived from SBase (see Section 3.2 on p. 14) and are defined in Figure 20. 6 An example of a model which uses events is given in Section 7 on p. 113. In addition to the attributes and children it inherits from SBase, an Event definition has one required attribute, 2 useValuesFromTriggerTime, and five optional subobjects, Trigger, Delay, Priority, ListOfEventAssignments, 3 and EventAssignment. These various features of Event are described below. 4 The id attribute 5 Event inherits an optional id attribute of type SId from SBase. The identifier of an Event has no mathematical 6 meaning in an SBML Level 3 Version 2 Core model. 7 The optional sboTerm attribute on Event 8 Event inherits an optional sboTerm attribute of type SBOTerm from SBase (see Section 3.1.12 on p. 14 and 9 Section 5 on p. 91). When this attribute is present on a given Event object instance, its value should be an 10 SBO identifier belonging to the branch for type Event indicated in Table 6 on p. 98. The relationship is of 11 the form "the event is-a X", where X is the SBO term. The term chosen should be the most precise (narrow) 12 one that captures the role of the event in the model. 13 As discussed in Section 5 on p. 91, SBO labels are optional information on a model. Applications are free to 14 ignore sboTerm values. A model must be interpretable without the benefit of SBO labels. 15 The useValuesFromTriggerTime attribute 16 The possibility of defining an optional Delay within Event, and the potential for multiple simultaneously-  26 The attribute useValuesFromTriggerTime allows a model to indicate the moment at which the event's 27 assignments are to be evaluated. A value of "true" indicates the values assignments are to be computed at 28 the moment the event is triggered. Conversely, useValuesFromTriggerTime="false" means the assignments 29 are to be computed at the moment the event is executed. The attribute has no default value. As shown in Figure 20 on the preceding page, an Event object may contain exactly one object of class Trigger. 32 This object in turn must contain two attributes, persistent and initialValue, and may contain a MathML 33 math element. The expression in the math element will be interpreted as a value of type boolean. The exact 34 moment at which this expression evaluates to "true" during a simulation is taken to be the time point when 35 the Event is triggered. 36 An event only triggers when the expression within its Trigger object makes the transition in value from "false" 37 to "true". The event will trigger again at any subsequent moments when the trigger makes the transition 38 from "false" to "true"; in other words, an event can trigger multiple times during a simulation if its trigger 39 condition makes the transition from "false" to "true" more than once. The behavior at the very start of  math element is permitted because it is possible for SBML Level 3 packages to add constructs that extend 2 Trigger and define how a value is to be computed. In the absence of such constructs, the event is never 3 triggered. A simulator encountering this situation may choose to produce a warning. 4 The id attribute on Trigger 5 Trigger inherits an optional id attribute from SBase, of type SId. The identifier has no mathematical meaning 6 in an SBML Level 3 Version 2 Core model. 7 The persistent attribute on Trigger 8 In the interval between when an Event object triggers (i.e., its Trigger object expression transitions in value 9 from "false" to "true") and when its assignments are to be executed, conditions in the model may change 10 such that the trigger expression transitions back from "true" to "false". Should the event's assignments 11 still be made if this happens? Answering this question is the purpose of the persistent attribute on Trigger.

12
If the boolean attribute persistent has a value of "true", then once the event is triggered, all of its 13 assignments are always performed when the time of execution is reached. The name "persistent" is meant to 14 evoke the idea that the trigger expression does not have to be re-checked after it triggers if persistent="true". 15 Conversely, if the attribute value is "false", then the trigger expression is not assumed to persist: if the 16 expression transitions in value back to "false" at any time between when the event triggered and when it is 17 to be executed, the event is no longer considered to have triggered and its assignments are not executed. (If 18 the trigger expression transitions once more to "true" after that point, then the event is triggered, but this 19 then constitutes a whole new event trigger-and-execute sequence.) 20 The persistent attribute can be especially useful when Event objects contain Delay objects, but it is relevant and its trigger expression evaluates to "false" before it is to be executed, the event must not be executed 28 after all. 29 The initialValue attribute on Trigger 30 As mentioned above, an event triggers when the mathematical expression in its Trigger object transitions in 31 value from "false" to "true". An unanswered question concerns what happens at the start of a simulation: 32 can event triggers make this transition at t = 0, where t stands for time? 33 In order to determine whether an event may trigger at t = 0, it is necessary to know what value the Trigger 34 object's math expression had immediately prior to t = 0. This starting value of the trigger expression 35 is determined by the value of the boolean attribute initialValue. A value of "true" means the trigger 36 expression is taken to have the value "true" immediately prior to t = 0. In that case, the trigger cannot 37 transition in value from "false" to "true" at the moment simulation begins (because it has the value "true" 38 both before and after t = 0), and can only make the transition from "false" to "true" sometime after t = 0.

39
(To do that, it would also first have to transition to "false" before it could make the transition from "false" 40 back to "true".) Conversely, if initialValue="false", then the trigger expression is assumed to start with 41 the value "false", and therefore may trigger at t = 0 if the expression evaluates to "true" at that moment.

42
The optional sboTerm attribute on Trigger

43
Trigger inherits an optional sboTerm attribute of type SBOTerm from its parent class SBase (see Section 3.1.12 44 and Section 5). The value given to this attribute should be an SBO identifier belonging to the branch for 45 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 1 in the model.

2
As discussed in Section 5 on p. 91, SBO labels are optional information on a model. Applications are free to 3 ignore sboTerm values. A model must be interpretable without the benefit of SBO labels. formula is used to compute a dimensionless numerical value that influences the order in which a simulator is 8 to perform the assignments of two or more events that happen to be executed simultaneously. The formula 9 may evaluate to any double value (and thus may be a positive or negative number, or zero), with positive 10 numbers taken to signifying a higher priority than zero or negative numbers. If no Priority object is present 11 on a given Event object, no priority is defined for that event.

12
A Priority with no math child leaves the priority of the event undefined. The absence of a math element is 13 permitted because it is possible for SBML Level 3 packages to add constructs that extend Priority and define 14 how a value is to be computed. In the absence of such constructs, the event behaves as if it does not have a 15 priority. A simulator encountering this situation may choose to produce a warning. 16 The interpretation of priorities on events in a model 17 For the purposes of SBML, simultaneous event execution is defined as the situation in which multiple events 18 have identical times of execution. The time of execution is calculated as the sum of the time at which a given 19 event's Trigger is triggered plus its Delay duration, if any. Here, "identical times" means mathematically equal 20 instants in time. (In practice, simulation software adhering to this specification may have to rely on numerical 21 equality instead of strict mathematical equality; robust models will ensure that this difference will not cause 22 significant discrepancies from expected behavior.) 23 If no Priority subobjects are defined for two or more Event objects, then those events are still executed the preceding page for more information about the attribute persistent. 28 If Priority subobjects are defined for two or more simultaneously-triggered events, the order in which those 29 particular events must be executed is dictated by their Priority objects, as follows. If the values calculated 30 using the two Priority objects' math expressions differ, then the event having the higher priority value must 31 be executed before the event with the lower value. If, instead, the two priority values are mathematically 32 equal, then the two events must be triggered in a random order. It is important to note that a random order 33 is not the same as an undefined order : given multiple runs of the same model with identical conditions, an 34 undefined ordering would permit a system to execute the events in (for example) the same order every time 35 (according to whatever scheme may have been implemented by the system), whereas the explicit requirement 36 for random ordering means that the order of execution in different simulation runs depends on random chance.

37
In other words, given two events "A" and "B", a randomly-determined order must lead to an equal chance of 38 executing "A" first or "B" first, every time those two events are executed simultaneously. The following example may help further clarify these points. Suppose a model contains four events that 46 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 1 events must be executed after them, again in a random order, for a total of four possible and equally-likely priority is selected for next execution. Note that it is possible for the execution of one Event object to cause 14 the Priority value of another simultaneously-executing Event object to change (as well as to trigger other 15 events, as already noted). Thus, after executing one event, and checking whether any other events in the model 16 have been triggered, all remaining simultaneous events that either (i) have Trigger objects with attributes 17 persistent="false" or (ii) have Trigger expressions that did not transition from "true" to "false", must 18 have their Priority expression reevaluated. The highest-priority remaining event must then be selected for 19 execution next. Section 8.2.5 on p. 153 provides further discussion about implementing support for events.

20
Units of Priority object's mathematical expressions 21 The unit associated with the value of a Priority object's math expression should be dimensionless. This is 22 because the priority expression only serves to provide a relative ordering between different events, and only 23 has meaning with respect to other Priority object expressions. The value of Priority objects is not comparable 24 to any other kind of object in an SBML model.

25
The id attribute on Priority 26 Priority inherits an optional id attribute from SBase, of type SId. The identifier has no mathematical meaning 27 in an SBML Level 3 Version 2 Core model. 28 The optional sboTerm attribute on Priority 29 Priority inherits an optional sboTerm attribute of type SBOTerm from its parent class SBase (see Section 3.1.12 30 and Section 5). When a value is given to this attribute in a Priority instance, it should be an SBO identifier 31 belonging to the branch for type Priority indicated in Table 6 on p. 98. The relationship is of the form "the 32 priority is-a X", where X is the SBO term. The term chosen should be the most precise (narrow) one that 33 captures the role of the priority in the model. 34 As discussed in Section 5 on p. 91, SBO labels are optional information on a model. Applications are free to 35 ignore sboTerm values. A model must be interpretable without the benefit of SBO labels.  The expression in the Delay object's math element must be evaluated at the time the event is triggered. The 1 expression must always evaluate to a nonnegative number (otherwise, a nonsensical situation could arise 2 where an event is defined to execute before it is triggered!). 3 Units of delay expressions 4 The unit associated with the value of a Delay object's math expression should match the model's unit of time  In such cases, the correspondence between the needed entity units and the (unknown) unit for the Delay's 9 math expression cannot be proven, and while such expressions are not considered inconsistent, all that can be 10 assumed by model interpreters (whether software or human) is that the units may be consistent. 11 The following Event example fragment helps illustrate this:   milliseconds? Would the modeler remember to change "10" to "10 000"?) A better approach would be to 31 declare the unit explicitly, as in the following example:  Another, different approach is to define a global Parameter object for the time delay (with an appropriate 52 unit attached), and to replace the cn element above with a ci element containing the parameter's identifier.

53
This has advantages because Parameter objects can have annotations and SBO terms associated with them.

54
The id attribute on Delay 1 Delay inherits an optional id attribute from SBase, of type SId. The identifier has no mathematical meaning 2 in an SBML Level 3 Version 2 Core model. 3 The optional sboTerm attribute on Delay 4 Delay inherits an optional sboTerm attribute of type SBOTerm from its parent class SBase (see Section 3.1.12 5 and Section 5). When a value is given to this attribute in a Delay instance, it should be an SBO identifier 6 belonging to the branch for type Delay indicated in Table 6 on p. 98. The relationship is of the form "the 7 delay is-a X", where X is the SBO term. The term chosen should be the most precise (narrow) one that 8 captures the role of the delay in the model. 9 As discussed in Section 5 on p. 91, SBO labels are optional information on a model. Applications are free to 10 ignore sboTerm values. A model must be interpretable without the benefit of SBO labels.  An "event assignment" has effect when the event is executed. (As noted above, the operation of event is divided 18 conceptually into two phases: the first phase when the event is triggered and the second phase when the event 19 is executed.) See Section 4.12.7 on p. 89 below for more information about events and event assignments.

20
The variable attribute 21 The EventAssignment required attribute variable has type SIdRef. The value of the attribute must be the 22 identifier of an object in the SId namespace of the model with mathematical meaning and the ability to be 23 assigned. In SBML Level 3 Core, the permitted objects classes are Compartment, Species, SpeciesReference, 24 and Parameter. The set also includes SBML Level 3 package objects with identifiers in the SId namespace of 25 the model and mathematical meaning defined to allow assignment. 26 When the event is executed, the value of the model component identified by variable is changed by the 27 EventAssignment to the value computed by the math element. For components defined by SBML Level 3 Core, 28 this means that a species' quantity, species reference's stoichiometry, compartment's size or parameter's value 29 are reset to the value computed by math. 30 Certain restrictions are placed on what can appear in variable: 31 • The object identified by the value of the variable attribute must not have its constant attribute set 32 to "true". (Constants cannot be affected by events.) 33 • The variable attribute must not contain the identifier of a reaction; in core, only species, species 34 references, compartment and parameter values may be set by an Event. 35 • The value of every variable attribute must be unique among the set of EventAssignment objects within  If the variable attribute of an EventAssignment object references an object in an SBML namespace that 1 is not recognized by the interpreter reading a given SBML document (that is, if the object is defined by 2 an SBML Level 3 package that the software does not support), the event assignment must be ignored-the 3 object's value must not be assigned if the interpreter cannot understand the package. If an interpreter cannot 4 establish whether a referenced object is missing from the model or instead is defined in an SBML namespace 5 not recognized by the interpreter, it may produce a warning to the user. (The latter situation can only arise 6 if an SBML package is present in the SBML document with a package:required attribute of "true".) 7 Note that the time of assignment of the object identified by the value of variable is always the time at 8 which the Event is executed, not when it is triggered. The timing is controlled by the optional Delay. The time 9 of assignment is not affected by the Event attribute useValuesFromTriggerTime-that attribute affects the 10 time at which the EventAssignment's math expression is evaluated. In other words, SBML allows decoupling 11 the time at which the variable is assigned from the time at which its value expression is calculated.

12
The optional sboTerm attribute on EventAssignment 13 EventAssignment inherits an optional sboTerm attribute of type SBOTerm from its parent class SBase (see 14 Section 3.1.12 on p. 14 and Section 5 on p. 91). When a value is given to this attribute in a EventAssignment 15 instance, it should be an SBO identifier belonging to the branch for type EventAssignment indicated in 16 Table 6 on p. 98. The relationship is of the form "the event assignment is-a X", where X is the SBO term. 17 The term chosen should be the most precise (narrow) one that captures the role of the event assignment in 18 the model. 19 As discussed in Section 5 on p. 91, SBO labels are optional information on a model. Applications are free to 20 ignore sboTerm values. A model must be interpretable without the benefit of SBO labels.  The math element contains a MathML expression that defines the new value to be given to the object identified 26 by the EventAssignment attribute variable.

27
As mentioned above, the time at which the expression in math is evaluated is determined by the attribute 28 useValuesFromTriggerTime on Event. If the attribute value is "true", the expression must be evaluated 29 when the event is triggered ; more precisely, the values of identifiers occurring in MathML ci elements in the  An EventAssignment with no math child leaves undefined what assignment is to be made to the corresponding 35 symbol. The absence of a math element is permitted because it is possible for SBML Level 3 packages to add 36 constructs that extend EventAssignment and define how a value is to be computed. In the absence of any such 37 construct, no assignment is carried out when there is no math element. This leaves the model unchanged: any 38 element that had a value will continue to have that value; any element whose value was undefined will continue 39 to have its value undefined. A simulator encountering this situation may choose to produce a warning. No of that class are defined by the package as having the same units). 19 Note that the formula in math has no assumed unit of measurement associated with it. The consistency of 20 the units between the formula and the entity affected by the assignment should be established explicitly.

Example Event definitions 22
The following is an example of an event. This structure makes the assignment k 2 = 0 when P 1 ≤ P 2 : <parameter id="k2" value="0.05" units="per_second" constant="false"/> 35 <parameter id="k2reset" value="0.0" units="per_second" constant="true"/>   1 Any transition of a Trigger object's math formula from the value "false" to "true" will cause the enclosing 2 Event object to trigger. Such a transition is not possible at the very start of a simulation (i.e., at time t = 0) 3 unless the Trigger object's initialValue attribute has a value of "false"; this defines the value of the trigger 4 formula to be "false" immediately prior to the start of simulation, thereby giving it the potential to change 5 in value from "false" to "true" when the formula is evaluated at t = 0. If initialValue="true", then the 6 trigger expression cannot transition from "false" to "true" at t = 0 but may do so at some time t > 0. 7 Consider an Event object definition E with delay d in which the Trigger object's math formula makes a 8 transition in value from "false" to "true" at times t 1 and t 2 . The EventAssignment within the Event object 9 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 10 "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. 11 It is entirely possible for two events to be executed simultaneously, and it is possible for events to trigger 12 other events (i.e., an event assignment can cause an event to trigger). This leads to several points: 13 • A software package should retest all event triggers after executing the assignments from a given event in 14 order to account for the possibility that the assignments cause another event trigger to transition from 15 "false" to "true". This check should be made after each individual Event object's execution, even when 16 several events are to be executed simultaneously. 17 • Any Event object whose Trigger persistent attribute has the value "false" must have its trigger 18 expression reevaluated continuously between when the event has been triggered and when it is executed. 19 If its trigger expression ever evaluates to "false", it must be removed from the queue of events pending 20 execution and treated as any other event whose trigger expression evaluates to "false".

21
• Although the precise time at which events are executed is not resolved beyond the given execution point 22 in simulated time, it is assumed that the order in which the events occur is resolved. This order can be 23 significant in determining the overall outcome of a given simulation. When an event X triggers another 24 event Y and event Y has zero delay, then event Y is added to the existing set of simultaneous events 25 that are pending execution. Events X and Y form a cascade of events at the same point in simulation 26 time. An event such as Y may have a special priority if it contains a Priority subobject. The values of id attributes on SBML components allow the components to be cross-referenced within a model.

2
The values of name attributes on SBML components provide the opportunity to assign them meaningful 3 labels suitable for display to humans (Section 3.3 on p. 18). The specific identifiers and labels used in a model 4 necessarily must be unrestricted by SBML, so that software and users are free to pick whatever they need. 5 However, this freedom makes it more difficult for software tools to determine, without additional human 6 intervention, the semantics of models more precisely than the semantics provided by the SBML object classes 7 defined in other sections of this document. For example, there is nothing inherent in a parameter with identifier 8 "k" that would indicate to a software tool it is a first-order rate constant (if that's what "k" happened to be 9 in some given model). However, one may need to convert a model between different representations (e.g., 10 Henri-Michaelis-Menten vs. elementary steps), or to use it with different modeling approaches (discrete or 11 continuous). One may also need to relate the model components with other description formats such as 12 SBGN (http://www.sbgn.org/) using deeper semantics. Although an advanced software tool might be able 13 to deduce the semantics of some model components through detailed analysis of the kinetic rate expressions 14 and other parts of the model, this quickly becomes infeasible for any but the simplest of models. 15 An approach to solving this problem is to associate model components with terms from carefully curated 16 controlled vocabularies (CVs). This is the purpose of the optional sboTerm attribute provided on the SBML 17 class SBase. The sboTerm attribute always refers to terms belonging to the Systems Biology Ontology (SBO, 18 (Courtot et al., 2011)). In this section, we discuss the sboTerm attribute, SBO, the motivations and theory 19 behind their introduction, and guidelines for their use.

20
SBO is not part of SBML; it is being developed separately, to allow the modeling community to evolve the 21 ontology independently of SBML. However, the terms in the ontology are being designed keeping SBML 22 components in mind, and are classified into subsets that can be directly related with SBML components 23 such as reaction rate expressions, parameters, and a few others, see below. The use of sboTerm attributes 24 is optional, and the presence of sboTerm on an element does not change the way the model is interpreted.

25
Annotating SBML elements with SBO terms adds additional semantic information that may be used to 26 convert the model into another model, or another format. Although SBO support provides an important 27 source of information to understand the meaning of a model, software does not need to support sboTerm to 28 be considered SBML-compliant. 29

Principles 30
Labeling model components with terms from shared controlled vocabularies allows a software tool to identify 31 each component using identifiers that are not tool-specific. An example of where this is useful is the desire by 32 many software developers to provide users with meaningful names for reaction rate equations. Software tools 33 with editing interfaces frequently provide these names in menus or lists of choices for users. However, without 34 a standardized set of names or identifiers shared between developers, a given software package cannot reliably 35 interpret the names or identifiers of reactions used in models written by other tools. 36 The first solution that might come to mind is to stipulate that certain common reactions always have the 37 same name (e.g., "Michaelis-Menten"), but this is simply impossible to do: not only do humans often disagree 38 on the names themselves, but it would not allow for correction of errors or updates to the list of predefined 39 names except by issuing new releases of the SBML specification-to say nothing of many other limitations 40 with this approach. Moreover, the parameters and variables that appear in rate expressions also need to be 41 identified in a way that software tools can interpret mechanically, implying that the names of these entities 42 would also need to be regulated. 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 1 and name given to the reaction itself, a software tool could use this to inform users that the reaction is a 2 first-order irreversible mass-action reaction. This kind of reverse engineering of the meaning of reactions in a 3 model would be difficult to do otherwise, especially for more complex reaction types. 4 The presence of SBO labels on Compartment, Species, and Reaction objects in SBML can help map those 5 entities to equivalent concepts in other standards, such as (but not limited to) BioPAX (https://www. 6 biopax.org/), PSI-MI (http://www.psidev.info/index.php?q=node/60), or the Systems Biology Graphical 7 Notation (SBGN, http://www.sbgn.org/). Such mappings can be used in conversion procedures, or to build 8 interfaces, with SBO becoming a kind of "glue" between standards of representation. 9 The presence of the label on a kinetic expression can also allow software tools to make more intelligent 10 decisions about reaction rate expressions. For example, an application could recognize certain types of reaction 11 formulas as being ones it knows how to solve with optimized procedures. The application could then use 12 internal, optimized code implementing the rate formula indexed by identifiers such as SBO:0000049 ("mass 13 action rate law for first order irreversible reactions, continuous scheme") appearing in SBML models.
14 Finally, SBO labels may be very valuable when it comes to model integration, by helping identify interfaces, 15 convert mathematical expressions and parameters etc. 16 Although the use of SBO can be beneficial, it is critical to keep in mind that the presence of an sboTerm 17 value on an object must not change the fundamental mathematical meaning of the model. An SBML model 18 must be defined such that it stands on its own and does not depend on additional information added by 19 SBO terms for a correct mathematical interpretation. SBO term definitions will not imply any alternative 20 mathematical semantics for any SBML object labeled with that term. Two important reasons motivate this 21 principle. First, it would be too limiting to require all software tools to be able to understand the SBO 22 vocabularies in addition to understanding SBML. Supporting SBO is not only additional work for the software 23 developer; for some kinds of applications, it may not make sense. If SBO terms on a model are optional, it 24 follows that the SBML model must remain unambiguous and fully interpretable without them, because an 25 application reading the model may ignore the terms. Second, we believe allowing the use of sboTerm to alter 26 the mathematical meaning of a model would allow too much leeway to shoehorn inconsistent concepts into 27 SBML objects, ultimately reducing the interoperability of the models. 28

29
The sboTerm attribute data type is always SBOTerm, defined in Section 3.1.12 on p. 14. When present in a 30 given model object instance, the attribute's value must be an identifier that refers to a single SBO term 31 that best defines the entity encoded by the SBML object in question. An example of the type of relationship 32 intended is: the KineticLaw in reaction R1 is a first-order irreversible mass action rate law. 33 Note the careful use of the words "defines" and "entity encoded by the SBML object" in the paragraph above. 34 As mentioned, the relationship between the SBML object and the URI is: 35 The "thing" encoded by this SBML object has a characteristic that is an instance of the "thing" 36 represented by the referenced SBO term.

37
The characteristic relevant for each SBML object is described in the second column of Table 6 on p. 98.      The controlled vocabulary for quantitative parameters is illustrated in Figure 24. Note the separation of kinetic  The terms of the SBO quantitative systems description parameter branch contain mathematical formulas 10 that are encoded using MathML 2.0; these formulas define the parameter value using other SBO parameters. 11 The main use of this approach is to avoid listing all the variants of a mathematical expression, escaping a 12 combinatorial explosion. 13 The modeling framework controlled vocabulary is needed to elucidate how to simulate a mathematical 14 expression used in models. Figure 25 illustrates the structure of this branch, which is at this point fairly 15 simple, but we expect that more terms will evolve in the future. The mathematical expression vocabulary encompasses the various mathematical expressions that constitute a 17 model. Figure 26 on the next page illustrates a portion of the hierarchy. Rate law or conservation law formulas 18 are part of the mathematical expression hierarchy, and subdivided by successively more refined distinctions 19 until the leaf terms represent precise statements of common reaction or rule types. Other types of mathematical 20 expressions may be included in the future in order to be able to further characterize mathematical components 21 of a model, such as initial assignments, assignment rules, rate rules, algebraic rules, constraints, and event 22 triggers and assignments. 23 The leaf terms of the mathematical expression branch contain the mathematical formulas encoded using 24 MathML 2.0. There are many potential uses for this. One is to allow a software application to obtain the 25 formula corresponding to a term and use it as the basis of an expression to insert into a model. In effect, the  Rule. The MathML definition also acts as a precise statement about the rate law in question. In particular, 1 it carries information about the modeling framework to use in order to interpret the formula. Some of the 2 non-leaf terms also contain formulas encoded using MathML 2.0. In that case, the formulas contained in 3 the children terms are specific versions of the formula contained in the parent term. Those formulas may 4 be generic, containing MathML constructs not yet supported by SBML, and need to be expanded into the 5 MathML subset allowed in SBML before they can be used in conjunction with SBML models. 6 To make this discussion concrete, here is an example definition of an entry in the SBO rate law hierarchy  In the MathML definition of the term shown above, the bound variables in the lambda expression are tagged 1 with references to terms in the SBO systems description parameter branch (for k and R). This makes it 2 possible for software applications to interpret the intended meanings of the parameters in the expression. 3 This also permits to convert an expression into another, by using the MathML 2.0 formula contained in the 4 SBO terms associated with the parameters. 5 The occurring entity representation branch of SBO defines types of biological processes, events or relationship 6 involving entities. It lists the types of biochemical reactions, such as binding, conformational transition, or 7 cleavage, and also the different controls that modify a biochemical reaction, such as inhibition, catalysis, etc.  One of the goals of SBO is to permit a tool to traverse up and down the hierarchy in order to find equivalent 9 terms in different frameworks. The hope is that when a software tool encounters a given rate formula in a 10 model, the formula will be a specific form (say, "mass-action rate law, second order, one reactant, for discrete 11 simulation"), but by virtue of the consistent organization of the reaction rate CV into framework-specific 12 definitions, and the declaration of every parameters involved in each expression, the tool should in principle be 13 able to determine the definitions for other frameworks (say, "mass-action rate law, second order, one reactant 14 for continuous simulation"). If the software tool is designed for continuous simulation and it encounters an 15 SBML model with rate laws formulated for discrete simulation, it could in principle look up the rate laws' 16 identifiers in the CV and search for alternative definitions intended for discrete simulation. And of course, the 17 converse is true, for when a tool designed for discrete simulation encounters a model with rate laws formulated 18 for continuous simulation.  The controlled vocabulary for annotations is illustrated in Figure 28 on the preceding page, the single child of the relationships between SBML components and the branches within SBO that apply to that component. The parent identifiers shown in Table 6 on the following page are provided for reference. They are the 26 highest-level terms in their respective branch; however, these are not the terms that would be used to annotate 27 an element in SBML, because there are more specific terms underneath the parents shown here. A software 28 tool should use the most specific SBO term available for a given concept rather than using the top-level 29 identifier acting as the root of that particular vocabulary. 30

Relationships to the SBML annotation element 31
Another way to provide this information would be to place SBO terms inside the SBase annotation element 32 (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 33 interoperable as possible between software tools, the best-practice recommendation is to place SBO references 34 in the sboTerm attribute rather than inside the annotation element of an object. If instead the approach of 35 using annotation is taken, the qualifiers (Section 6.5 on p. 103) linking the SBML element and SBO term 36 should be chosen extremely carefully, since it will no longer be possible to assume an "instance to class" 37 relationship.

38
Although sboTerm is just another kind of optional annotation in SBML, SBO references are separated into 39 their own attribute on SBML components, both to simplify their use for software tools and because doing so 40 asserts a stronger and more focused connection in a more regimented fashion. SBO references are intended to 41 allow a modeler to make a statement of the form "this object is identical in meaning and intention to the 42 object defined in the term X of SBO", and do so in a way that a software tool can interpret unambiguously. software interoperability, the best-practice recommendation in SBML is nonetheless to use SBO terms in 2 preference to using application-specific annotation schemes. Software applications should therefore attempt 3 to translate their private terms to and from SBO terms when writing and reading SBML, respectively.

5
Here we discuss some additional points about the SBO-based approach.  7 The SBO development approach follows conventional ontology development approaches in bioinformatics.

8
One of the principles being followed is that identifiers and meanings of terms in the CVs never change and 9 the terms are never deleted. Where some terms are deemed obsolete, the introduction of new terms refine 10 or supersede existing terms, but the existing identifiers are left in the CV. Thus, references never end up 11 pointing to nonexistent entries. In the case where synonymous terms are merged after agreement that multiple 12 terms are identical, the term identifiers are again left in the CV and they still refer to the same concept 13 as before. Out-of-date terms cached or hard-coded by an application remain usable in all cases. (Moreover, 14 machine-readable CV encodings and appropriate software design should render possible the development of 15 API libraries that automatically map older terms to newer terms as the CVs evolve.) Therefore, a model is 16 never in danger of ending up with SBO identifiers that cannot be dereferenced. If an application finds an old 17 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 18 been superseded by other, more preferred terms.

Consistency of information 20
If you have a means of linking (say) a reaction rate formula to a term in a CV, it is possible to have an 21 inconsistency between the formula in the SBML model and the one defined for the CV term. However, this 22 is not a new problem; it arises in other situations involving SBML models already. The guideline for these 1 situations is that the model must be self-contained and stand on its own. Therefore, in cases where they 2 differ, the definitions in the SBML model take precedence over the definitions referenced by the CV. In other 3 words, the model (and its MathML) is authoritative.   The format described in this section is intended to be the form of one of the top-level elements that could 7 reside in an Annotation object attached to an SBML object derived from SBase. The element is named 8 rdf:RDF. The format described here is compliant with the constraints placed on the form of annotation 9 elements described in Section 3.2.6 on p. 16. We refer readers to Section 3.2.6 for important information on 10 the structure and organization of application-specific annotations; these are not described here.

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

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

20
It is generally not recommended that this format be used to refer to SBO terms. In most cases, the SBO 21 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 23 of a species, it is necessary to add the information using the annotation format described here. 24 Annotations only add additional qualifying information and never change existing information. They can 25 be ignored without changing the (broader) meaning of the model. The same is true of nested annotations 26 (described below), which qualify their parent annotation but never change the meaning of that annotation.  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 1 of the officially supported annotation 'standard format'. This standard format for an SBML annotation is placed in a single rdf:RDF element contained within the 4 SBML annotation element. It can contain other elements in any order as described in Section 3.2.6 on p. 16.

5
The format described in this section only defines the form of the rdf:RDF element. The containing SBML 6 SBase element must have a metaid attribute value (and note that, because it is of XML type ID, its value 7 must be unique to the entire SBML document). An outline of the format's syntax is shown below. clarifying the annotation it is embedded within.

55
The string ' +++ ' is a placeholder for either no content or valid XML content that is not defined by the 1 annotation scheme described here but is consistent with the relevant standards for the enclosing elements.
2 Finally, the string ' ... ' is a placeholder for zero or more elements of the same form as the immediately 3 preceding element. The precise form of whitespace and the XML namespace prefix definitions is not constrained; 4 however, the elements and attributes must be in the namespaces shown. The rest of this section describes the 5 format formally in English. 6 The first element of the rdf:RDF element must be an rdf:Description element with an rdf:about attribute.   The value of a rdf:resource attribute is a URI that uniquely identifies both the resource and the data 28 within the resource. Since a URI is not a URL, it does not have to map to a physical Web object; it simply 29 needs to identify, uniquely, a controlled vocabulary term or database object. It is essentially just a label. For

32
It is important that the portion of a rdf:resource value that identifies a data entry is always a perennial 33 identifier. For example, a Species object representing a protein could be annotated with a reference to the 34 database UniProt by the resource identifier https://identifiers.org/uniprot/P12999, thereby identifying 35 exactly the intended protein. This identifier maps to a unique entry in UniProt which is never deleted from 36 the database. In the case of UniProt, this is known as the "accession" portion of the entry. When the entry is 37 merged with another one, both "accession" entries are conserved. A UniProt entry also possesses an "entry 38 name" (the Swiss-Prot "identifier"), a "protein name", "synonyms", and other parts, but only the "accession" To enable interoperability of URIs between software systems, the community has standardized the URI rules 1 for use within the SBML MIRIAM annotation format. These URIs are not part of the SBML standard per se, 2 and will grow independently from specific SBML levels and versions. As the set changes, existing URIs will not 3 be modified, although the physical resources associated with each one may change (for example, to use updated 4 URLs). The form of the URIs will always have the form resource:identifier. An up-to-date list and explanations 5 of the URIs are available online at the address https://www.ebi.ac.uk/miriam/main/collections. Each 6 entry lists the database in question, the URI to be used to reference that database, and example URIs for 7 referencing particular entries in those databases. The URI rule list will evolve with the evolution of databases 8 and resources. 9 Note this means that all rdf:resource must be MIRIAM URIs and thus cannot refer to, for example, other 10 elements in the model. While it would be possible to place such information in RDF content elsewhere (e.g., 11 after the first rdf:Description element), the information will be outside the scope of the simple annotation 12 scheme described here, and as such, there is no guarantee that other software could understand it.  will only grow; i.e., no element will be removed from the list.     The syntax for these elements is outlined below. The order of elements must be as shown above, except that elements of the format contained in the light 12 gray box (vCard4:fn or vCard4:hasName, plus vCard4:hasEmail, and vCard4:organization-name) can occur 13 in any order. The elements of the format contained between [ and ] (vCard4:organization-name, and 14 vCard4:hasEmail) are optional, but everything else is required. The precise form of the whitespace, and the 15 specific XML namespace prefixes used ("dcterms", "rdf", and "vcard4") are not constrained. 16 The dcterms:creator element describes the person(s) who created the SBML encoding of the model or  Note that dcterms:creator has been added to http://purl.org/dc/terms/ relatively recently, but the same 23 term (with the same meaning) exists in the http://purl.org/dc/elements/1.1/ namespace. It is legal to 24 continue using the old namespace (called "dc" in previous versions of the SBML specifications), but since all 25 the terms defined there are now also defined in http://purl.org/dc/terms/, we recommend using the latter. 26 The content placeholders FAMILY NAME and GIVEN NAME stand for the family name (surname) and the first 27 (given) name, respectively, of a person who created the model; when using vCard4, FULL NAME stands for the 28 full name of that person. EMAIL ADDRESS is the email address of the same person who created the model; 29 and ORGANIZATION NAME is the name of the organization with which the same person who created the model 30 is affiliated. The string DATE is a date in W3C date format (Wolf and Wicksteed, 1998), which is a profile of 31 (i.e., a restricted form of) ISO 8601. Finally, as in the overall template shown in Section 6.3 on p. 101, ' +++ ' 32 is a placeholder for either no content or valid XML syntax that is not defined by this scheme but is consistent 1 with the relevant standards for the enclosing elements, and ellipses (' ... ') are placeholders for zero or more 2 elements of the same form as the immediately preceding element. 3 Section 6.7 below provides an example of using these history elements in the SBML MIRIAM annotation 4 format. 5

Examples 6
The following shows the annotation of a model with model creation data and links to external resources: 7 <model metaid="_180340" id="GMO" name="Goldbeter1991_MinMitOscil"> The following example shows a Reaction object annotated with a reference to its exact Reactome counterpart. 55 <reaction id="cdc2Phospho" metaid="jb007" reversible="true"> The following example describes a species that represents a complex between the protein calmodulin and 19 calcium ions: 20 <species id="Ca_calmodulin" metaid="cacam" compartment="C" 21 hasOnlySubstanceUnits="false" boundaryCondition="false" The following example describes a species that represents either "Calcium/calmodulin-dependent protein 40 kinase type II alpha chain" or "Calcium/calmodulin-dependent protein kinase type II beta chain". This is 41 the case, for example, in the somatic cytoplasm of striatal medium-size spiny neurons, where both are present 42 but they cannot be functionally differentiated. 43 <species id="calcium_calmodulin" metaid="cacam" compartment="C" 44 hasOnlySubstanceUnits="false" boundaryCondition="false" The above approach should not be used to describe "any Calcium/calmodulin-dependent protein kinase type II chain", because such an annotation requires referencing the products of other genes such as gamma 1 or delta. All the known proteins could be enumerated, but such an approach would almost surely lead to 2 inaccuracies because biological knowledge continues to evolve. Instead, the annotation should refer to generic 3 information such as Ensembl family ENSFM00250000000111 "CALCIUM/CALMODULIN DEPENDENT 4 KINASE TYPE II CHAIN" or PIR superfamily PIRSF000594 "Calcium/calmodulin-dependent protein kinase 5 type II". 6 The following two examples show how to use the qualifier isVersionOf. The first example is the relationship 7 between a reaction and an EC code. An EC code describes an enzymatic activity and an enzymatic reaction 8 involving a particular enzyme can be seen as an instance of this activity. For example, the following reaction 9 represents the phosphorylation of a glutamate receptor by a complex calcium/calmodulin kinase II. 10 <reaction id="NMDAR_phosphorylation" metaid="thx1138" The second example of the use of isVersionOf is the complex between Calcium/calmodulin-dependent 55 protein kinase type II alpha chain and Calcium/calmodulin, that is only one of the "calcium-and calmodulin-56 dependent protein kinase complexes" described by the Gene Ontology term GO:0005954. (Note also how the 57 GO identifier is written-we return to this point below.) 58 <species id="CaCaMKII" metaid="C8H10N4O2" compartment="C" 59 hasOnlySubstanceUnits="false" boundaryCondition="false"  Thus, when an identifier contains a colon character as part of it (as GO, ChEBI, and certain other identifiers 18 do), the colon characters must be percent-encoded. The sequence "%3A" is the percent-encoded form of ":". 19 Applications must percent-encode ":" characters that appear in entity identifiers (whether from ECO, ChEBI,  The previous case is different from the following one, although they could seem similar at first sight. The

23
"Calcium/calmodulin-dependent protein kinase type II alpha chain" is a part of the above mentioned "calcium- 24 and calmodulin-dependent protein kinase complex". 25 <species id="CaMKIIalpha" metaid="C10H14N2" compartment="C" The following example presents a reaction being actually the combination of three different elementary 14 molecular reactions. We annotate it with the three corresponding KEGG reactions, but also with the three 15 corresponding enzymatic activities. Again the two hasPart elements represent two alternative annotations. 16 The process represented by the Reaction structure is composed of three parts, and not six parts. 17 <reaction id="adenineProd" metaid="adeprod" reversible="true"> As formally defined above it is possible to use different qualifiers in the same annotation element. The following 8 phosphorylation is annotated by its exact KEGG counterpart and by the generic GO term "phosphorylation". 9 <reaction id="phosphorylation" metaid="phosphorylation" The following example demonstrates the use of nested terms to describe both that a species is in a particular 32 compartment, and the evidence that the species belongs there: 33 <species id="S1" metaid="_000004" compartment="lysosome" 34 hasOnlySubstanceUnits="false" boundaryCondition="false" In descriptive terms, the SBML species "S1" (with metaid " 000004") occurs in "go/GO:0005764" (the 61 lysosome). This is described by the publication "pubmed/1111111", and is believed to be true because of the 62 evidence "eco/ECO:0000004" (cell fractionation evidence).

59
The example above also demonstrates the use of unit specifications throughout the model. The model  This example involves the same enzymatic reaction as in the example of Section 7.1 on p. 113: In this new version of the model, we deliberately define the species with different units from the unit of 4 reaction extent in the model. This leads to two illustrative problems: (1) the reaction rate expressions must 5 be changed in order to reconcile the differences between the species units and the unit of reaction extent in 6 the model, and (2) the formulas constructed for species' rate-of-change equations must use conversion factors 7 to reconcile the differences between the units of the reaction rate expressions and the units in which the 8 species quantities are measured. 9 We begin with the following new Species object definitions: that is, the overall unit of extent in the model is mole and the unit of time is second, set by assigning 16 appropriate values to the attributes extentUnits and timeUnits, respectively, on the Model object definition. 17 The differences between these and the units of the species means that we have to adjust the reaction rate 18 expressions from their original versions in the model. In what follows, we illustrate one approach to doing so, 19 and in Section 7.3 on p. 118 we illustrate a second approach. The method in the present section involves 20 changing the values of the kinetic rate constants in the reaction rate formulas, while the example of Section 7.3 21 does not change the kinetic constants but does require the introduction of additional parameters.

22
The reaction rate formulas (i.e., the formulas in the math elements of KineticLaw objects) were previously The "mole/millimole" portion of the units are admittedly unconventional for mass-action kinetic rate constants.

37
They are unlikely to correspond to values found in textbooks or databases. The logic of this approach is 38 that in an actual experimental situation, with the units of the species as given in the model (presumably 39 representing how the species are being measured), the kinetic rate constants are likely to be measured in 1 terms of the units above. However, if that is not the case, then the approach of Section 7.3 on p. 118 may be 2 more appropriate. 3 Taking these new k * on , k * off and k * cat parameters and replacing the original parameters in the reaction rate 4 equations finally leads to the following: Next, we turn to the rates-of-change equations for the species. There are two cases: species S, whose unit of 8 substance is millimole, and species P , whose unit of substance is gram. We use SBML Level 3's conversion factor 9 mechanism to effectuate the necessary transformations, following the guidelines described in Section 4.11.7 on The portion inside the gray box in Equation 9 is simply Equation 7, and its value will have the unit mole/second. 17 Multiplying this by c model will produce a result in millimole/second. The stoichiometry of species S in the 18 reaction is "1", but it is a reactant, thus the need for the negative sign. 19 For species P , we need a different conversion factor, to convert between the units of gram and mole. We Model object. Let c P represent this conversion factor. The equation for the rate-of-change of P is the following:

25
The portion inside the gray box in Equation 10 is simply Equation 8, with a value in mole/second. Multiplying 26 by the conversion factor "convertToGram" defined in the model below will yield gram/second. The species P 27 is a product, and its stoichiometry is "1"; thus, the right-hand side has a positive sign. 28 The following is the SBML encoding of this model:

8
where [X 0 ], [X 1 ], [S 1 ], and [S 2 ] are species in concentration units, and k 1 , k 2 , k f , k r , and K eq are parameters. 9 This system of reactions can be approximated with the following new system: where T is a new species. The following example SBML model encodes the second system.

23
The value of S 1 in the system is determined over time by the rate rule: The species S 2 and S 3 are not affected by the either the reaction or the rate rule, and have the following is "true" and the boundaryCondition attribute is "false". Finally, [S 4 ] is a product whose value is determined 37 by a kinetic law and therefore in the SBML representation has "false" for both its boundaryCondition and 38 constant attributes.

54
The following is the text of the model's SBML representation.

2
These recommendations are non-normative, but we advocate them strongly; ignoring them will not render a 3 model invalid, but may hinder interoperability between different software systems exchanging SBML content. 4 8.1 Recommended practices concerning common SBML attributes and objects 5 Many SBML components share some or all of the following attributes and objects. We describe recommenda- 6 tions concerning them here, separately from discussing the specific SBML components. In Section 8.2 on 7 p. 148, we turn to the specific SBML components, but the recommendations described here also apply to 8 them. The id attribute is available on most (but not all) objects in SBML, and all objects that have id attributes 11 also have an optional name attribute. How should models treat identifiers and names?

12
The following is the recommended practice for handling name. can be created without defining a value for its size attribute; a Species object can be created without defining 26 a value for either its initialConcentration or initialAmount attribute; Parameter and LocalParameter 27 objects can be created without giving a value to their value attributes; and a SpeciesReference object can be 28 created without assigning a value to its stoichiometry attribute. A missing value in the case of Compartment, 29 Species, Parameter, and SpeciesReference objects implies that the value is either set via an InitialAssignment 30 object elsewhere in the model, or is meant to be obtained from an external source (e.g., by querying the user 31 of a software system), or is unknown. In the case of LocalParameter objects, a missing value implies that the 32 value is either unknown or meant to be obtained from an external source. 33 Where initial values are available and are decimal numbers that can be set using the appropriate attribute 34 on an object, the best practice recommendation is to do that in preference to using an There is a mandatory boolean attribute called constant on the Compartment, Species, SpeciesReference and 2 Parameter components. A value of "true" means that the SBML object in question will not be changed by 3 other constructs in SBML except possibly an InitialAssignment. A value of "false" indicates an intention to 4 change the element's value by an AssignmentRule, RateRule, AlgebraicRule, Reaction or Event in the model.

5
A constant attribute value of "false" does not require that the object in question is changed; strictly 6 speaking, an SBML model is valid even if it sets all constant attributes to "false" but never actually 7 modify any of the values. However, the best practice recommendation is to communicate intentions by setting 8 constant to "true" unless an entity in a model really is intended to be changed. The exception to this is 9 Species, which are usually part of the reaction system and thus usually need to have constant="false". for URIs used in annotations is that they should be chosen to be as persistent as possible, so future consumers 16 of SBML documents can continue to dereference and understand the annotations. 17 Appropriate uses of annotations 18 In the description of the • Identification information for cross-referencing components in a model with items in a data resource 23 such as a database. This is the purpose of the annotation scheme described in Section 6 on p. 100.

24
• Application-specific processing instructions that do not change the essential meaning of a model, but 25 help a particular application with tasks such as managing the model, maintaining state data across 26 editing sessions, etc.

27
• Evidence codes for annotating a model with controlled vocabulary terms that indicate (e.g.) the quality 28 of biological evidence supporting the inclusion of each component in the model. The annotation scheme 29 of Section 6 on p. 100 can be used in this capacity. 30 • Information about the model that cannot be readily encoded in existing SBML elements, but that does 31 not alter the mathematical meaning of the model. 32 Specificity of annotations 33 The annotation data (Section 3.2.6 on p. 16) attached to a specific SBML object in a model is assumed 34 by other applications to be directly associated with that particular object. Therefore, it is important to The annotation scheme described in Section 6 on p. 100 is useful for many, but not all, situations. It is tempting 41 to develop new annotation syntaxes for situations that fall outside the scope of the SBML MIRIAM annotation 42 scheme. However, a proliferation of proprietary annotation schemes will hinder software interoperability in 43 the long run. 44 We recommend the following approach when faced with a need to use alternate annotation syntaxes:  18 We advise modelers and software tools to declare the units of all quantities in a model, insofar as this is   One approach to handling this is to use a FunctionDefinition to define a function encapsulating the 34 relationship above, then to substitute a call to this function wherever the original temperature in 35 Fahrenheit appears in the model's mathematical formulas. We provide a candidate definition in 36 Figure 30 on the following page. Celsius and thermodynamic temperature can be handled rather easily by the simple substitution described 51 <listOfUnitDefinitions> <unitDefinition id="degree_Fahrenheit"> <notes><p xmlns="http://www.w3.org/1999/xhtml"> This captures the notion that the size of a degree in Fahrenheit is 5/9 the size of a degree on the kelvin scale. </notes> <listOfUnits> <unit kind="kelvin" multiplier="5" scale="0" exponent="1"/> <unit kind="dimensionless" multiplier="9" scale="0" exponent="-1"/> </listOfUnits> </unitDefinition> </listOfUnitDefinitions> ... <listOfFunctionDefinitions> <functionDefinition id="Fahrenheit_to_kelvin"> <notes><p xmlns="http://www.w3.org/1999/xhtml"> This function takes a number assumed to be in Fahrenheit degrees and returns a number in kelvin degrees. Callers could use the definition of unit "degree_Fahrenheit" to attach units to the argument passed to the call to this function. </notes> <math xmlns="http://www.w3.org/1998/Math/MathML" xmlns:sbml="http://www.sbml.org/sbml/level3/version2/core"> <lambda> <bvar><ci> arg_temp_in_Fahrenheit </ci></bvar> <apply> <divide/> <apply> <plus/> <ci> arg_temp_in_fahrenheit </ci> <cn sbml:units="degree_Fahrenheit"> 459.67</cn> </apply> <apply> <divide/> <cn sbml:units="degree_Fahrenheit"> 1.8 </cn> <cn sbml:units="kelvin"> 1 </cn> </apply> </apply> </lambda> </math> </functionDefinition> </listOfFunctionDefinitions>

Compartments 1
Setting the size attribute on a compartment 2 As mentioned in Section 4.5.3 on p. 47, we highly recommend that every Compartment object in a model 3 has its size set. There are three major technical reasons for this. First, if the model contains any species 4 whose initial amounts are given in terms of concentrations, and there is at least one reaction in the model 5 referencing such a species, then the model will be numerically incomplete if it lacks a value for the size of the 6 compartment in which the species is located. The reason is that SBML reactions are expected to be in terms 7 of intensive properties such as amount/time (or more generally, extent units/time units; see Section 4.11.7 on 8 p. 78), and converting from concentration to amount requires knowing the compartment size. Second, models 9 ideally should be capable of being instantiated in a variety of simulation frameworks. A commonly-used one is 10 the discrete stochastic framework (Gillespie, 1977;Wilkinson, 2006) in which species are represented as item 11 counts (e.g., molecule counts). If species' initial quantities are given in terms of concentrations or densities, it 12 is impossible to convert the values to item counts without knowing compartment sizes. Third, if a model 13 contains multiple compartments whose sizes are not all identical to each other, it is impossible to quantify 14 the reaction rate expressions without knowing the compartment volumes. The reason for the latter is again 15 that reaction rates in SBML are defined in terms extent/time, and when species quantities are given in terms 16 of concentrations or densities, the compartment sizes usually become factors in the reaction rate expressions.

48
In this example, as is often the case when an AlgebraicRule has been used, the AlgebraicRule could be replaced 49 by Consider a very simple model consisting of a single enzymatic reaction R that converts S 1 to S 2 for which a 5 traditional kinetic law v R is given: with v R and v max given in units of concentration per time.

10
As mentioned above, when a rate law is presented in the traditional way, it usually embodies (implicitly or 11 explicitly) several assumptions: that all species are located in the same compartment, that the compartment 12 size does not change, and that the reaction takes place uniformly throughout the volume of the compartment, 13 i.e. the enzyme is not localized in any special way. Under these circumstances it is possible to construct rate 14 equations for the concentration of the species: In SBML, however, the rate equations are constructed for the rate of change of the amount of the species: wherev R is the modified SBML kinetic law and V is the volume of the compartment. Since the traditional 19 kinetic law v R describes how fast the amount of the species changes per volume, the SBML kinetic lawv R The following recommendations concern Event objects and their subcomponents. 29 Undefined ordering 30 Section 4.12 on p. 79 describes how to interpret SBML events; however, the explanation explicitly leaves 31 undefined how events should be ordered in the absense of priorites attached to the events. This curious 32 omission in the specification reflects the state of agreement in biological modeling software today, but at the 33 same time, it does not help software developers with the goal of implementing support for SBML events. 34 In practice, a variety of simple approaches can satisfy the "undefined ordering" requirement. For example, 35 a software system could assign an arbitrary priority value to all events with undefined priorities. Another 36 approach is for a simulator to execute the events in whatever order they happen to be stored in the 37 implementation of the software. This part of SBML event behavior is left up to developers. 10, one with priority 4, and one with an undefined priority (call it X ), there are three valid results for an 2 implementation following the combined priority and "undefined ordering" requirements in SBML: 10-4-X, 3 10-X-4, and X-10-4. The implementation could always pick the same option among those three (as would 4 happen if it assigned events with undefined priorities an artificial priority value, as mentioned above), or it 5 could pick randomly between the three alternatives on different simulation runs, as it would if it were trying 6 to be robustly stochastic. But the simulator should never execute the events in the order 4-10-X, nor should 7 it quit unexpectedly. By defining the events in the model in this way, the creator of the model has clearly 8 stated that the event with priority 10 should be executed before the event with priority 4, and that the event 9 with X must also be executed at some point. Beyond that, nothing more can be said or assumed about the 10 modeler's intention. 11 Simultaneous event execution 12 Another concern with SBML events is how to implement true "simultaneous" execution of events. same delay equation (which should also be cached if need be, for the same reason), they will then execute 30 simultaneously, as they were intended to do in the model. 31 When creating models containing (e.g.) two events A and B that have different delays, model authors should 32 not expect to achieve simultaneous execution simply by arranging for the sum of A's trigger time plus 33 A's delay to be equal to the sum of B's trigger time plus B's delay. It is unlikely that different software 34 implementations will resolve the execution times precisely in the same way, so it is unlikely the model will 35 behave as the author expected in this scenario.

36
A Validation and consistency rules for SBML 1 This section summarizes all the conditions that must (or in some cases, at least should ) be true of a model 2 encoded in SBML Level 3 Core format. We use the following conventions in the list of rules that follow: 3 • There are different degrees of rule strictness. Formally, the differences are expressed in the statement of 4 a rule: either a rule states that a condition must be true, or a rule states that it should be true. Rules 5 of the former kind are strict SBML validation rules-a model encoded in SBML must conform to all of 6 them in order to be considered valid. Rules of the latter kind are consistency rules. To help highlight 7 these differences, we use the following three symbols next to the rule numbers: of the rule will be the same. 23 • Rules that may have been introduced in lower Levels/Versions of SBML sometimes are removed in 24 higher Levels/Versions. (This can happen, for example, if they become irrelevant due to changes in the 25 language in a higher Level or Version of SBML.) Rule numbers, however, remain unique and are never 26 reused for a different purpose. Consequently, there exist gaps in the sequence numbers of the rules.

27
• New rules introduced by this SBML Level 3 specification are indicated by an underlined rule number 28 (e.g., 10104 instead of 10104).

29
• XML element attributes mentioned in the following validation and consistency rules have no XML 30 namespace prefix, and must appear in SBML documents without any explicit XML namespace, even if 31 the declared namespace is otherwise correct for SBML Level 3.

32
General rules concerning basic XML requirements 33 10101.
An SBML XML file must use UTF-8 as the character encoding. More precisely, the encoding must define required="true" on the SBML container element <sbml>.

10207.
The only permitted values for the attribute type on MathML cn elements are "e-notation", "real", 35 "integer", and "rational". An SBML package may allow new values for the type attribute, and if 36 so, the package must define required="true" on the SBML container element <sbml>.

10218.
A MathML operator must be supplied the number of arguments appropriate for that operator.

10305.
In every Event object, the value of the attribute variable within each EventAssignment subobject 29 must be unique across the set of all such EventAssignment subobjects within that particular Event 30 object. In other words, a single Event cannot make more than one assignment to the same model    The value of the attribute extentUnits on a Model object should be either the units "mole", fined in SBML. That is, the identifier must not be the same as any of the following base units: 23 "ampere", "avogadro", "becquerel", "candela", "coulomb", "dimensionless", "farad", "gram", 24 "gray", "henry", "hertz", "item", "joule", "katal", "kelvin", "kilogram", "litre", "lumen",

20415.
Apart from the general notes and annotation subobjects permitted on all SBML components, a and KineticLaw objects in a model. Each of these constructs has the effect of assigning a value to 23 an identifier (i.e., the identifier given in the attribute symbol in InitialAssignment, the attribute 24 variable in AssignmentRule, and the attribute id on the KineticLaw's enclosing Reaction). Each 25 of these constructs computes the value using a mathematical formula. The formula for a given 26 identifier cannot make reference to a second identifier whose own definition depends directly or B A method for assessing whether an SBML model is overdetermined 1 As explained in Section 4.9.5 on p. 64, an SBML model must not be overdetermined. It is possible to use 2 purely static analysis to assess this condition for the system of equations implied by a model, by constructing a 3 bipartite graph of the model's variables and equations and then searching for a maximal matching (Chartrand, 4 1977). An efficient algorithm for finding a maximal matching is described by Hopcroft and Karp (1973). In this 5 appendix, we provide a concrete application to SBML of the general approach described in Section 4.9.5 on 6 p. 64. The approach is defined in terms of the ordinary differential equations (ODEs) implied by an SBML 7 model; despite our use of a differential equation framework for this explanation, it should be understood that 8 this use of ODEs has no implication about the framework actually used to simulate the model. Definition of the method 10 First, we assume that an ODE is constructed for each species determined by one or more Reaction's KineticLaw 11 math expressions. We also assume that the model has already been determined to be valid in all other 12 respects (e.g., there are no undefined variables in the equations), and what remains is to evaluate whether it 13 is overdetermined.
2 This generates two vertices, for "S1" and "S2". for "R". 5 Note that it is not necessary to include parameters declared within KineticLaw objects because they are local 6 to a particular reaction and cannot be affected by rules. With the steps above, we have the following set of 7 graph nodes: 8 Vertices for equations 9 S1 S2 rule law S1 S2 R 10 Vertices for variables 11 Next, we create edges following the procedure described above. Doing so results in the following graph:

14
Vertices for variables 15 The algorithm of Hopcroft and Karp (1973) can now be applied to search for a maximal matching of the 16 bipartite graph. A maximal matching is a graph in which each vertex is connected to at most one other vertex 17 and the maximum possible number of connections have been made. Doing so here results in the following: 18 Vertices for equations 19 S1 S2 rule law S1 S2 R simulation. This can be useful in some cases, such as reactions where the stoichiometry depends upon pH. 5 However, it can be difficult to get the KineticLaw of such reactions to maintain the correct units as the 6 stoichiometry of the reaction changes. For example, let us assume that we are modeling the following set of 7 chemical reactions: where we would like to allow n to be a variable. In order to allow for this, we can approximate the above set where K eq is equal to k f /k r . The rate law for the above reaction is: 17 k r · K eq n−1 · A n − k r · A n 18 Let us assume that all species A, A 2 , . . . , A n have units of mole, k f is in units of (mole · second) −1 , and k r 19 is in units of second −1 . Therefore, K eq is in units of mole −1 which makes the rate law above have units of 20 mole/second as desired, regardless of the value of n, the stoichiometry of A.

17
Fengkai Zhang was supported by the intramural program of NIAID, NIH.

18
The following individuals served as past SBML Editors and authors of SBML specifications. Their efforts 19 helped shape what SBML is today: since. Many discussions are archived online in the mailing list/forums area of http://sbml.org; many more 28 discussions took place during meetings and workshops (a list of which is also available at http://sbml.org). 29 SBML Level 3 has benefitted from so many contributions, large and small, by so many people who constitute 30 the international SBML Forum, that we regret it has become infeasible to list individuals by name. We thank 31 everyone who has participated in SBML's development throughout the years, and we hope that this latest 32 specification before you is a good step forward in SBML's continued evolution.