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

Michael Hucka, Frank Bergmann, Claudine Chaouiya, Andreas Dräger, Stefan Hoops, Sarah Keating, Matthias König, Nicolas Le Novère, Chris Myers, Brett Olivier, et al.

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

To cite this version:

Michael Hucka, Frank Bergmann, Claudine Chaouiya, Andreas Dräger, Stefan Hoops, et al. The Systems Biology Markup Language (SBML): Language Specification for Level 3 Version 2 Core Release 2. Journal of Integrative Bioinformatics, 2019, 16 (2), 10.1515/jib-2019-0021. hal-02564234

HAL Id: hal-02564234

https://hal.science/hal-02564234v1

Submitted on 22 Jun 2025

HAL is a multi-disciplinary open access
archive for the deposit and dissemination of sci-
entific research documents, whether they are pub-
lished or not. The documents may come from
teaching and research institutions in France or
abroad, or from public or private research centers.

L'archive ouverte pluridisciplinaire HAL, est
destinée au dépôt et à la diffusion de documents
scientifiques de niveau recherche, publiés ou non,
émanant des établissements d'enseignement et de
recherche français ou étrangers, des laboratoires
publics ou privés.

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

Distributed under a Creative Commons Attribution 4.0 International License
Michael Hucka<fnref n="1" /> / Frank T. Bergmann<fnref n="1" /> / Claudine Chaouiya<fnref n="2" /> / Andreas Dräger<fnref n="3" />,<fnref n="4" />,<fnref n="5" /> / Stefan Hoops<fnref n="6" />
/ Sarah M. Keating<fnref n="7" /> / Matthias König<fnref n="8" /> / Nicolas Le Novère<fnref n="9" /> / Chris J. Myers<fnref n="10" /> / Brett G. Olivier<fnref n="11" /> / 
Sven Sahle<fnref n="12" /> / James C. Schaff<fnref n="13" /> / Rahuman Sheriff<fnref n="7" /> / Lucian P. Smith<fnref n="14" /> / Dagmar Waltemath<fnref n="15" /> / 
Darren J. Wilkinson<fnref n="16" /> / Fengkai Zhang<fnref n="17" />

# 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/.

**Keywords:** Systems Biology Markup Language, Standards, Visualization, Representation

**DOI:** 10.1515/jib-2019-0021

**Received:** March 30, 2019; **Accepted:** May 20, 2019

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

<footnote n="1">¹ California Institute of Technology, Pasadena, CA, USA. https://orcid.org/0000-0001-9105-5960, https://orcid.org/0000-0001-5553-4702.</footnote>

<footnote n="2">² Aix-Marseille University, CNRS, I2M, Marseille, France. https://orcid.org/0000-0003-2350-0756.</footnote>

<footnote n="3">³ Department of Computer Science, University of Tübingen, Tübingen, Germany. https://orcid.org/0000-0002-1240-5553.</footnote>

<footnote n="4">⁴ Computational Systems Biology of Infection and Antimicrobial-Resistant Pathogens, Institute for Biomedical Informatics (IBMI), University of Tübingen, Tübingen, Germany. https://orcid.org/0000-0002-1240-5553.</footnote>

<footnote n="5">⁵ German Center for Infection Research (DZIF), Tübingen, Germany. https://orcid.org/0000-0002-1240-5553.</footnote>

<footnote n="6">⁶ Virginia Bioinformatics Institute, Blacksburg, VA, USA. https://orcid.org/0000-0001-8503-8371.</footnote>

<footnote n="7">⁷ European Bioinformatics Institute, Cambridge, UK. https://orcid.org/0000-0002-3356-3542, https://orcid.org/0000-0003-0705-9809.</footnote>

<footnote n="8">⁸ Humboldt University Berlin, Berlin, Germany. https://orcid.org/0000-0003-1725-179X.</footnote>

<footnote n="9">⁹ Babraham Institute, Cambridge, UK. https://orcid.org/0000-0002-6309-7327.</footnote>

<footnote n="10">¹⁰ University of Utah, Salt Lake City, UT, USA. https://orcid.org/0000-0002-8762-8444.</footnote>

<footnote n="11">¹¹ VU University Amsterdam, Amsterdam, Netherlands. https://orcid.org/0000-0002-5293-5321.</footnote>

<footnote n="12">¹² University of Heidelberg, Heidelberg, Germany</footnote>

<footnote n="13">¹³ University of Connecticut, Storrs, CT, USA. https://orcid.org/0000-0003-3286-7736.</footnote>

<footnote n="14">¹⁴ University of Washington, Seattle, WA, USA, E-mail: lpsmith@uw.edu. https://orcid.org/0000-0001-7002-6386.</footnote>

<footnote n="15">¹⁵ University Medicine Greifswald, Greifswald, Germany. https://orcid.org/0000-0002-5886-5563.</footnote>

<footnote n="16">¹⁶ Newcastle University, Newcastle, Germany. https://orcid.org/0000-0003-0736-802X.</footnote>

<footnote n="17">¹⁷ NIAID/NIH, Bethesda, MD, USA. https://orcid.org/0000-0001-7112-9328.</footnote>
# The Systems Biology Markup Language (SBML):
## Language Specification for Level 3 Version 2 Core

Michael Hucka (Chair)

Frank T. Bergmann

Claudine Chaouiya

Andreas Dräger

Stefan Hoops

Sarah M. Keating

Matthias König

Nicolas Le Novère

Chris J. Myers

Brett G. Olivier

Sven Sahle

James C. Schaff

Rahuman Sheriff

Lucian P. Smith

Dagmar Waltemath

Darren J. Wilkinson

Fengkai Zhang

California Institute of Technology, US

California Institute of Technology, US

Aix-Marseille University, CNRS, I2M, FR

University of Tübingen, DE

Virginia Bioinformatics Institute, US

European Bioinformatics Institute, GB

Humboldt University Berlin, DE

Babraham Institute, GB

University of Utah, US

VU University Amsterdam, NL

University of Heidelberg, DE

University of Connecticut, US

European Bioinformatics Institute, GB

University of Washington, US

University of Rostock, DE

Newcastle University, GB

NIAID/NIH, US

sbml-editors@sbml.org

## SBML Level 3 Version 2 Core

### Release 2

29 March 2019

Corrections and other changes to this SBML language specification may appear over time.
Notifications of new releases are broadcast on the mailing list sbml.org/forums/sbml-announce

The latest release of the SBML Level 3 Version 2 Core specification is available at
http://sbml.org/specifications/sbml-level-3/version-2/core

This release of the specification is available at
http://sbml.org/specifications/sbml-level-3/version-2/core/release-2/

The list of known issues in all releases of SBML Level 3 Version 2 Core is available at
http://sbml.org/specifications/sbml-level-3/version-2/core/errata/

Formal schemas for use with XML are available at
http://sbml.org/specifications/sbml-level-3/version-2/schemas/

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

Systems Biology
Markup Language
# Contents

<table><tr><td>1</td><td>Introduction</td><td>3</td></tr><tr><td>1.1</td><td>Developments, discussions, and notifications of updates</td><td>3</td></tr><tr><td>1.2</td><td>SBML Levels, Versions, and Releases</td><td>3</td></tr><tr><td>1.3</td><td>SBML Level 3 Packages</td><td>4</td></tr><tr><td>1.4</td><td>Document conventions</td><td>4</td></tr><tr><td>2</td><td>Overview of SBML</td><td>9</td></tr><tr><td>3</td><td>Preliminary definitions and principles</td><td>11</td></tr><tr><td>3.1</td><td>Primitive data types</td><td>11</td></tr><tr><td>3.2</td><td>Type SBase</td><td>14</td></tr><tr><td>3.3</td><td>The id and name attributes on SBase</td><td>18</td></tr><tr><td>3.4</td><td>Mathematical formulas in SBML Level 3</td><td>20</td></tr><tr><td>4</td><td>SBML components</td><td>34</td></tr><tr><td>4.1</td><td>The SBML container</td><td>34</td></tr><tr><td>4.2</td><td>Model</td><td>36</td></tr><tr><td>4.3</td><td>Function definitions</td><td>40</td></tr><tr><td>4.4</td><td>Unit definitions</td><td>42</td></tr><tr><td>4.5</td><td>Compartments</td><td>46</td></tr><tr><td>4.6</td><td>Species</td><td>49</td></tr><tr><td>4.7</td><td>Parameters</td><td>53</td></tr><tr><td>4.8</td><td>Initial assignments</td><td>56</td></tr><tr><td>4.9</td><td>Rules</td><td>59</td></tr><tr><td>4.10</td><td>Constraints</td><td>66</td></tr><tr><td>4.11</td><td>Reactions</td><td>68</td></tr><tr><td>4.12</td><td>Events</td><td>79</td></tr><tr><td>5</td><td>The Systems Biology Ontology and the sboTerm attribute</td><td>91</td></tr><tr><td>5.1</td><td>Principles</td><td>91</td></tr><tr><td>5.2</td><td>Using SBO and sboTerm</td><td>92</td></tr><tr><td>5.3</td><td>Relationships to the SBML annotation element</td><td>97</td></tr><tr><td>5.4</td><td>Discussion</td><td>98</td></tr><tr><td>6</td><td>A standard format for the annotation element</td><td>100</td></tr><tr><td>6.1</td><td>Motivation</td><td>100</td></tr><tr><td>6.2</td><td>XML namespaces in the standard annotation</td><td>100</td></tr><tr><td>6.3</td><td>General syntax for the standard annotation</td><td>101</td></tr><tr><td>6.4</td><td>Use of URIs</td><td>102</td></tr><tr><td>6.5</td><td>Relation elements</td><td>103</td></tr><tr><td>6.6</td><td>History</td><td>105</td></tr><tr><td>6.7</td><td>Examples</td><td>106</td></tr><tr><td>7</td><td>Example models expressed in XML using SBML</td><td>113</td></tr><tr><td>7.1</td><td>A simple example application of SBML</td><td>113</td></tr><tr><td>7.2</td><td>A simple example using the conversionFactor attribute</td><td>115</td></tr><tr><td>7.3</td><td>An alternative formulation of the conversionFactor example</td><td>118</td></tr><tr><td>7.4</td><td>Example of a discrete version of a simple dimerization reaction</td><td>120</td></tr><tr><td>7.5</td><td>Example involving assignment rules</td><td>124</td></tr><tr><td>7.6</td><td>Example involving algebraic rules</td><td>126</td></tr><tr><td>7.7</td><td>Example with combinations of boundaryCondition and constant values on Species with RateRule objects</td><td>128</td></tr><tr><td>7.8</td><td>Example of translation from a multi-compartmental model to ODEs</td><td>130</td></tr><tr><td>7.9</td><td>Example involving function definitions</td><td>133</td></tr><tr><td>7.10</td><td>Example involving delay functions</td><td>134</td></tr><tr><td>7.11</td><td>Example involving events</td><td>135</td></tr><tr><td>7.12</td><td>Example involving two-dimensional compartments</td><td>137</td></tr><tr><td>7.13</td><td>Example of a reaction located at a membrane</td><td>141</td></tr><tr><td>7.14</td><td>Example using an event with a non-persistent trigger and a delay</td><td>143</td></tr><tr><td>8</td><td>Recommended practices</td><td>146</td></tr><tr><td>8.1</td><td>Recommended practices concerning common SBML attributes and objects</td><td>146</td></tr><tr><td>8.2</td><td>Recommended practices concerning specific SBML components</td><td>148</td></tr><tr><td>A</td><td>Validation and consistency rules for SBML</td><td>155</td></tr><tr><td>B</td><td>A method for assessing whether an SBML model is overdetermined</td><td>175</td></tr><tr><td>C</td><td>A mathematical technique for maintaining unit consistency in a kinetic law with variable stoichiometry</td><td>178</td></tr><tr><td></td><td>Acknowledgments</td><td>179</td></tr><tr><td></td><td>References</td><td>180</td></tr></table>
# 1 Introduction

This document defines Version 2 of the Systems Biology Markup Language (SBML) Level 3 Core, an electronic model representation format for systems biology. 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. SBML is defined neutrally with respect to programming languages and software encoding; however, it is oriented primarily towards allowing models to be encoded using XML, the eXtensible Markup Language (Bray et al., 2004). This document contains many examples of SBML models written in XML. Formal schemas describing the syntax of SBML, as well as other materials and software, are available from the SBML project web site, http://sbml.org/.

The SBML project is not an attempt to define a universal language for representing quantitative models. The rapidly evolving views of biological function, coupled with the vigorous rates at which new computational techniques and individual tools are being developed today, are incompatible with a one-size-fits-all idea of a universal language. A more realistic alternative is to acknowledge the diversity of approaches and methods being explored by different software tool developers, and seek a common intermediate format—a *lingua franca*—enabling communication of the most essential aspects of the models.

The definition of the model description language presented here does not specify *how* programs should communicate or read/write SBML. We assume that for a simulation program to communicate a model encoded in SBML, the program will have to translate its internal data structures to and from SBML, use a suitable transmission medium and protocol, etc., but these issues are outside the scope of this document.

## 1.1 Developments, discussions, and notifications of updates

SBML has been, and continues to be, developed in collaboration with an international community of researchers and software developers. As in many projects, the primary medium for interactions between members is electronic messaging. Discussions about SBML take place on the combination web forum and mailing list https://groups.google.com/d/forum/sbml-discuss. The mailing list archives and a web-browser-based interface to the list are available at the same location.

A low-volume, broadcast-only web forum/mailing list is available where notifications of revisions to the SBML specification, notices of votes on SBML technical issues, and other critical matters are announced. This list is https://groups.google.com/d/forum/sbml-announce and anyone may subscribe to it freely. This list will never be used for advertising and its membership will never be disclosed. It is vitally important that all users of SBML stay informed about new releases and other developments by subscribing to sbml-announce, even if they do not wish to participate in discussions on sbml-discuss. Please visit sbml.org/Forums/ for information about how to subscribe to the list as well as for access to the list archives.

## 1.2 SBML Levels, Versions, and Releases

Major editions of SBML are termed *levels* and represent substantial changes to the composition and structure of the language. The edition of SBML defined in this document, SBML Level 3, represents an evolution of the language resulting from the practical experiences of users and developers working with SBML since its introduction in the year 2001 (Hucka et al., 2001, 2003). All of the constructs of Level 1 can be mapped to Level 2; likewise, all of the constructs from Level 2 can be mapped to Level 3 (when Level 3 is considered in terms of the Core and Level 3 packages; see next section). In addition, a subset of Level 3 constructs can be mapped to Level 2, and a subset of Level 2 constructs can be mapped to Level 1. However, the levels remain distinct; a valid SBML Level 1 document is not a valid SBML Level 2 document, and so on.

In practice, once a new level of SBML is defined, no further development is undertaken on lower levels. An exception is made for the correction of problems and other issues that may be identified in the specifications of lower levels; such corrections are handled as described below.

Minor revisions of SBML are termed *versions* and constitute changes within a level to correct, adjust, and refine language features. The present document defines Level 3 *Version 2 Core*. A separate document provides information about the changes between SBML Level 3 and SBML Level 2.
Specification documents inevitably require minor editorial changes as their users discover errors and ambiguities. As a practical reality, these discoveries occur over time. In the context of SBML, such problems are formally announced publicly as *errata* in a given specification document. Borrowing concepts from the World Wide Web Consortium (Jacobs, 2004), we define SBML *errata* as changes of the following types: (a) formatting changes that do not result in changes to textual content; (b) corrections that do not affect conformance of software implementing support for a given combination of SBML level and version; and (c) corrections that *may* affect such software conformance, but add no new language features. A change that affects conformance is one that either turns conforming data, processors, or other conforming software into non-conforming software, or turns non-conforming software into conforming software, or clears up an ambiguity or insufficiently-documented part of the specification in such a way that software whose conformance was once unclear now becomes clearly conforming or non-conforming (Jacobs, 2004). In short, *errata* do not change the fundamental semantics or syntax of SBML; they clarify and disambiguate the specification and correct errors. (New syntax and semantics are only introduced in SBML versions and levels.) A public tracking system for reporting and monitoring such issues is available at http://sbml.org/issue-tracker, and we urge readers to use that system to report any issues found in this document.

SBML *errata* eventually result in new *Releases* of the specification. Each such release is numbered, with the first release of the specification being number 1. Subsequent releases of an SBML specification document contain a section describing the accumulated issues corrected since the first release. If *errata* are acknowledged for SBML Level 3 Version 2 Core since the publication of Release 1, they are listed publicly at http://sbml.org/specifications/sbml-level-3/version-2/core/errata/. Announcements of *errata*, updates to the SBML specification and other major changes are made on the https://groups.google.com/d/forum/sbml-announce web forum and mailing list.

## 1.3 SBML Level 3 Packages

SBML Level 3 is being developed as a modular language, with a central core comprising a self-sufficient model definition language, and extension packages layered on top of this core to provide additional, optional sets of features. This document defines the core of Level 3. The definition is based largely on SBML Level 2, with some modifications to address sources of problems found by experience with Level 2, and some simplifications to remove Level 2 constructs that are expected to be supported more thoroughly through SBML Level 3 packages. Section 4.1.3 on p. 35 describes the mechanism by which models defined in SBML Level 3 can declare which packages they use.

The specifications for packages available for SBML Level 3 is maintained separately on the SBML website at http://sbml.org/Documents/Specifications. A list of packages is not provided in this specification document (i.e., for Level 3 Core) because the development of packages for Level 3 proceeds independently, and new ones may be introduced over time after Level 3 Core is published. The SBML website provides information about ongoing activities in this area, as well as about the process whereby individuals and groups may propose new packages.

## 1.4 Document conventions

In this section, we describe the conventions used in this specification document to communicate information more effectively.

### 1.4.1 Color conventions

Throughout this document, we use coloring to carry additional information for the benefit of those viewing the document on media that can display color:

* We use red color in text and figures to indicate changes between this version of the specification, namely SBML Level 3 Version 2 Core Release 2, and the *most recent previous release* of the specification (which, for the present case, is SBML Level 3 Version 2 Core Release 1). The changes may be either additions or deletions of text; in the case of deletions, entire sentences, paragraphs or sections are colored to indicate a change has occurred inside them. In UML diagrams, a red *box* is used to indicate a deletion, and red *text* to indicate a semantic change or addition.
* We use blue color in text to indicate a hyperlink from one point in this document to another. Clicking your computer's pointing device on blue-colored text will cause a jump to the section, figure, table or page to which the link refers. (Of course, this capability is only available when using electronic formats that support hyperlinking, such as PDF and HTML.)

## 1.4.2 Typographical conventions for names

We use the following typographical conventions to distinguish objects and data types from other entities:

**AbstractClass:** Abstract classes are classes that are never instantiated directly, but rather serve as parents of other object classes. Their names begin with a capital letter and they are printed in a slanted, bold, sans-serif typeface. In electronic document formats, the class names are also hyperlinked to their definitions in the specification. For example, in the PDF and HTML versions of this document, clicking on the word **SBase** will send the reader to the section containing the definition of this class.

**Class:** Names of ordinary (concrete) classes begin with a capital letter and are printed in an upright, bold, sans-serif typeface. In electronic document formats, the class names are also hyperlinked to their definitions in the specification. For example, in the PDF and HTML versions of this document, clicking on the word **Species** will send the reader to the section containing the definition of this class.

**Something, otherThing:** Attributes of classes, data type names, literal XML, and generally all tokens other than SBML UML class names, are printed in an upright typewriter typeface. Primitive types defined by SBML begin with a capital letter; SBML also makes use of primitive types defined by XML Schema 1.0 (Biron and Malhotra, 2000; Fallside, 2000; Thompson et al., 2000), but unfortunately, XML Schema does not follow any capitalization convention and primitive types drawn from the XML Schema language may or may not start with a capital letter.

## 1.4.3 UML notation

Previous specifications of SBML used a notation that was at one time (in the days of SBML Level 1) fairly close to UML, the Unified Modeling Language (Eriksson and Penker, 1998; Oestereich, 1999), though many details were omitted from the UML diagrams themselves. Over the years, the notation used in successive specifications of SBML grew increasingly less UML-like. Beginning with SBML Level 2 Version 3, we have completely overhauled the specification's use of UML and once again define the XML syntax of SBML using, as much as possible, proper and complete UML 1.0. We then systematically map this UML notation to XML. In the rest of this section, we summarize the UML notation used in this document and explain the few embellishments needed to support transformation to XML form.

We see three main advantages to using UML as a basis for defining SBML data objects. First, compared to using other notations or a programming language, the UML visual representations are generally easier to grasp by readers who are not computer scientists. Second, the notation is implementation-neutral: the objects can be encoded in any concrete implementation language—not just XML, but C, Java and other languages as well. Third, UML is a de facto industry standard that is documented in many resources. Readers are therefore more likely to be familiar with it than other notations.

### Object class definitions

Object classes in UML diagrams are drawn as simple tripartite boxes, as shown in Figure 1 on the next page (left). UML allows for operators as well as data attributes to be defined, but SBML only uses data attributes, so all SBML class diagrams use only the top two portions of a UML class box (Figure 1 on the following page, right).

As mentioned above, the names of ordinary (concrete) classes begin with a capital letter and are printed in an upright, bold, sans-serif typeface. The names of attributes begin with a lower-case letter and generally use a mixed case (sometimes called “camel case”) style when the name consists of multiple words. Attributes and their data types appear in the part below the class name, with one attribute defined per line. The colon character on each line separates the name of the attribute (on the left) from the type of data that it stores (on the right). The subset of data types permitted for SBML attributes is given in Section 3.1 on p. 11.
<figure><img src="image_5.png" /><figcaption>**Figure 1:** (Left) The general form of a UML class diagram. (Right) Example of a class diagram of the sort seen in SBML. SBML classes never use operators, so SBML class diagrams only show the top two parts.</figcaption></figure>

In the right-hand diagram of Figure 1, the symbols **attribute** and **anotherAttribute** represent attributes of the object class **ExampleClass**. The data type of **attribute** is **int**, and the data type of **anotherAttribute** is **double**. In the scheme used by SBML for translating UML to XML, object attributes map directly to XML attributes. Thus, in XML, **ExampleClass** would yield an element of the form `<element attribute="42" anotherAttribute="10.0">`.

Notice that the element name is not `<ExampleClass ...>`. Somewhat paradoxically, the name of the element is *not* the name of the UML class defining its structure. The reason for this may be subtle at first, but quickly becomes obvious: object classes define the form of an object's *content*, but a class definition by itself does not define the *label* or *symbol* referring to an instance of that content. It is this label that becomes the name of the XML element. In XML, this symbol is most naturally equated with an element name. This point will hopefully become clearer with additional examples below.

## Subelements

We use UML *composition* to indicate a class object can have other class objects as parts. Such containment hierarchies map directly to element-subelement relationships in XML. Figure 2 gives an example.

<figure><img src="image_6.png" /><figcaption>**Figure 2:** Example illustrating composition: the definition of one class of objects employing another class of objects in a part-whole relationship. In this particular example, an instance of a **Whole** class object must contain exactly one instance of a **Part** class object, and the label referring to the **Part** class object is **inside**. In XML, this symbol becomes the name of a subelement and the content of the subelement follows the definition of **Part**.</figcaption></figure>

The line with the black diamond indicates composition, with the diamond located on the “container” side and the other end located at the object class being contained. The label on the line is used to refer to instances of the contained object, which in XML, maps directly to the name of an XML element. The class pointed to by the composition relationship (**Part** in Figure 2) defines the *contents* of that element. Thus, if we are told that some element named **barney** is of class **Whole**, the following is an example XML fragment consistent with the class definition of Figure 2:

```xml
<barney A="110" B="some string">
  <inside C="444.4">
  </barney>
```

Sometimes numbers are placed above the line near the “contained” side of a composition to indicate how many instances can be contained. The common cases in SBML are the following: `[0..*]` to signify a list containing zero or more; `[1..*]` to signify a list containing at least one; and `[0..1]` to signify exactly zero or one. The absence of a numerical label means “exactly 1”. This notation appears throughout this specification document.
## Inheritance

Classes can inherit properties from other classes. Since SBML only uses data attributes and not operators, inheritance in SBML simply involves data attributes from a parent class being inherited by child classes. Inheritance is indicated by a line between two classes, with an open triangle next to the parent class; Figure 3 illustrates this. In this example, the instances of object class **Child** would have not only attributes **C** and **D**, but also attributes **A** and **B**. All of these attributes would be required (not optional) on instances of class **Child** because they are mandatory on both the **Parent** and **Child** classes.

<figure><img src="image_7.png" /><figcaption>Figure 3: Inheritance.</figcaption></figure>

## Additional notations for XML purposes

Not everything is easily expressed in plain UML. For example, it is often necessary to indicate some constraints placed on the values of an attribute. In computer programming uses of UML, such constraints are often expressed using Object Constraint Language (OCL), but since we are most interested in the XML rendition of SBML, in this specification we use XML Schema 1.0 (when possible) as the language for expressing value constraints. Constraints on the values of attributes are written as expressions surrounded by braces (`{}`) after the data type declaration, as in the example of Figure 4.

<figure><img src="image_8.png" /><figcaption>Figure 4: A more complex example definition drawing on the concepts introduced so far in this section. Both SBML and Model are derived from SBase; further, SBML contains a single Model object named model. Note the constraints on the values of the attributes in SBML; they are enclosed in braces and often written in XML Schema language. The particular constraints here state that the xmlns, level and version attributes must be present, and that the values are fixed as indicated. In addition, other attributes are permitted (for example, such as those added by Level 3 packages).</figcaption></figure>

In other situations, when something cannot be concisely expressed using a few words of XML Schema, we write constraints using English language descriptions surrounded by braces (`{}`). To help distinguish these from literal XML Schema, we set the English text in a slanted typeface. The text accompanying all SBML component definitions provides explanations of the constraints and any other conditions applicable to the use of the components.

## XML Namespace

XML defines how to declare namespaces on XML elements. In most SBML documents, the SBML namespace will be the default namespace for the document, and thus individual elements in the document will not need to be prefixed with the SBML namespace. However, it is legal to declare an SBML namespace and use it to place SBML elements explicitly in that namespace. On the other hand, it is possible to create documents with no default namespace, in which case, elements in the document *must* be prefixed.

In contrast to element names, XML *attribute* names are completely defined by the XML element in which they appear, and never have a default namespace defined for them. The XML element itself declares whether any attributes appearing on it should be written with a namespace prefix.

For SBML Core, any attribute shown in any UML diagram in this specification *must* be written *without* a namespace prefix in an SBML document, even if a namespace prefix is defined in the SBML document.
1

2

3

4

5

6

The convention for SBML packages is to allow attributes to be defined *either* with no namespace prefix, *or* to be defined with that package's namespace as a prefix, for any new element defined by that package. When a package extends an existing SBML element to have a new attribute, the convention is to *require* that this attribute be prefixed with that package's namespace. Previously-released SBML packages did not make this explicit, but are assumed to follow this convention. As these packages undergo updates in the future, these rules will be made explicit.
## 2 Overview of SBML

The following is an example of a simple network of biochemical reactions that can be represented in SBML:

$$ 
\begin{array}{l}
S_1 \xrightarrow{k_1 [S_1]/([S_1]+k_2)} S_2 \\
\\
S_2 \xrightarrow{k_3 [S_2]} S_3 + S_4
\end{array}
$$

In this particular set of chemical equations above, the symbols in square brackets (e.g., "$[S_1]$") represent concentrations of molecular species, the arrows represent reactions, and the formulas above the arrows represent the rates at which the reactions take place. (And while this example uses concentrations, it could equally have used other measures such as molecular counts.) Broken down into its constituents, this model contains a number of components: reactant species, product species, reactions, reaction rates, and parameters in the rate expressions. To analyze or simulate this network, additional components must be made explicit, including compartments for the species, and units on the various quantities.

SBML allows models of arbitrary complexity to be represented. Each type of component in a model is described using a specific type of data object that organizes the relevant information. The top level of an SBML model definition consists of lists of these components, with every list being optional:

beginning of model definition

list of function definitions (optional) (Section 4.3)

list of unit definitions (optional) (Section 4.4)

list of compartments (optional) (Section 4.5)

list of species (optional) (Section 4.6)

list of parameters (optional) (Section 4.7)

list of initial assignments (optional) (Section 4.8)

list of rules (optional) (Section 4.9)

list of constraints (optional) (Section 4.10)

list of reactions (optional) (Section 4.11)

list of events (optional) (Section 4.12)

end of model definition

The meaning of each component is as follows:

*   **Function definition:** A named mathematical function that may be used throughout the rest of a model.

*   **Unit definition:** A named definition of a new unit of measurement. Named units can be used in the expression of quantities in a model.

*   **Compartment:** A well-stirred container of finite size where species may be located. Compartments may or may not represent actual physical structures.

*   **Species:** A pool of entities of the same kind located in a compartment and participating in reactions (processes). In biochemical network models, common examples of species include ions, proteins and other molecules; however, in practice, an SBML species can be any kind of entity that makes sense in the context of a given model.

*   **Parameter:** A quantity with a symbolic name. In SBML, the term *parameter* is used in a generic sense to refer to named quantities regardless of whether they are constants or variables in a model. SBML Level 3 provides the ability to define parameters that are global to a model as well as parameters that are local to a single reaction.

*   **Initial Assignment:** A mathematical expression used to determine the initial conditions of a model. This type of object can only be used to define how the value of a symbol can be calculated from other values and symbols at the start of simulated time.
**Rule:** A mathematical expression added to the set of equations constructed based on the reactions defined in a model. Rules can be used to define how a symbol's value can be calculated from other symbols, or used to define the rate of change of a symbol. The set of rules in a model can be used with the reaction rate equations to determine the behavior of the model with respect to time. Rules constrain the model for the entire duration of simulated time.

**Constraint:** A means of detecting out-of-bounds conditions during a dynamical simulation and optionally issuing diagnostic messages. Constraints are defined by an arbitrary mathematical expression computing a true/false value from model symbols. An SBML constraint applies at all instants of simulated time; however, the set of constraints in model should not be used to *determine* the behavior of the model with respect to time.

**Reaction:** A statement describing some transformation, transport or binding process that can change the amount of one or more species. For example, a reaction may describe how certain entities (reactants) are transformed into certain other entities (products). Reactions have associated kinetic rate expressions describing how quickly they take place.

**Event:** A statement describing an instantaneous, discontinuous change in one or more symbols of any type (species, compartment, parameter, etc.) when a triggering condition is satisfied.

A software package can read an SBML model description and translate it into its own internal format for model analysis. For example, a package might provide the ability to simulate the model by constructing differential equations representing the network and then perform numerical time integration on the equations to explore the model's dynamic behavior. By supporting SBML as an input and output format, different software tools can all operate on an identical external representation of a model, removing opportunities for errors in translation and assuring a common starting point for analyses and simulations.
# 3 Preliminary definitions and principles

This section covers certain concepts and constructs that are used repeatedly in the rest of SBML Level 3.

## 3.1 Primitive data types

Most primitive types in SBML are taken from the data types defined in XML Schema 1.0 (Biron and Malhotra, 2000; Fallside, 2000; Thompson et al., 2000). A few other primitive types are defined by SBML itself. What follows is a summary of the XML Schema types and the definitions of the SBML-specific types. Note that, while we have tried to provide accurate and complete summaries of the XML Schema types, the following descriptions should not be taken to be normative definitions of these types. Readers should consult the XML Schema 1.0 specification for the normative definitions of the XML data types used by SBML.

### 3.1.1 Type string

The XML Schema 1.0 type **string** is used to represent finite-length strings of characters. The characters permitted to appear in XML Schema **string** include all Unicode characters (Unicode Consortium, 1996) except for two delimiter characters, 0xFFFF and 0xFFFF (Biron and Malhotra, 2000). In addition, the following quoting rules specified by XML for character data (Bray et al., 2004) must be obeyed:

* The ampersand (`&`) character must be escaped using the entity `&amp;`;

* The apostrophe (`'`) and quotation mark (`"`) characters must be escaped using the entities `&apos;` and `&quot;`, respectively, when those characters are used to delimit a string attribute value.

Other XML built-in character or entity references, e.g., `&lt;` and `&x1A;`, are permitted in strings.

### 3.1.2 Type boolean

The XML Schema 1.0 type **boolean** is used for SBML object attributes that represent binary true/false values. XML Schema 1.0 defines the possible literal values of **boolean** as the following: `true`, `false`, `1`, and `0`. The value `1` maps to `true` and the value `0` maps to `false` in attribute values.

Note that there is a discrepancy between the value spaces of type **boolean** as defined by XML Schema 1.0 and MathML: the latter uses only `true` and `false` to represent Boolean values, with `0` and `1` reserved for numbers. Software tools should take care not to attempt using `0` and `1` as Boolean values in MathML expressions. See further discussion in Section 3.4.4 on p. 24.

### 3.1.3 Type int

The XML Schema 1.0 type **int** is used to represent decimal integer numbers in SBML. The literal representation of an **int** is a finite-length sequence of decimal digit characters with an optional leading sign (`+` or `-`). If the sign is omitted, `+` is assumed. The value space of **int** is the same as a standard 32-bit signed integer in programming languages such as C, i.e., $2147483647$ to $-2147483648$.

### 3.1.4 Type positiveInteger

The XML Schema 1.0 type **positiveInteger** is used to represent nonzero, nonnegative, decimal integers: i.e., $1, 2, 3, ...$. The literal representation of an integer is a finite-length sequence of decimal digit characters, optionally preceded by a positive sign (`+`). There is no restriction on the absolute size of **positiveInteger** values in XML Schema; however, the only situations where this type is used in SBML involve very low-numbered integers. Consequently, applications may safely treat **positiveInteger** as unsigned 32-bit integers.

### 3.1.5 Type double

The XML Schema 1.0 type **double** is the data type of floating-point numerical quantities in SBML. It is restricted to IEEE double-precision 64-bit floating-point type IEEE 754-1985. The value space of **double**
consists of (a) the numerical values $m \cdot 2^x$, where *m* is an integer whose absolute value is less than $2^{53}$, and *x* is an integer between -1075 and 970, inclusive, (b) the special value positive infinity (**INF**), (c) the special value negative infinity (**-INF**), and (d) the special value not-a-number (**NaN**). The order relation on the values is the following: *x* < *y* if and only if *y* - *x* is positive for values of *x* and *y* in the value space of **double**. Positive infinity is greater than all other values other than **NaN**. **NaN** is equal to itself but is neither greater nor less than any other value in the value space. (Software implementors should consult the XML Schema 1.0 definition of **double** for additional details about equality and relationships to IEEE 754-1985.)

The general form of **double** numbers is “*x*ey”, where *x* is a decimal number (the mantissa), “e” is a separator character, and *y* is an exponent; the meaning of this is “*x* multiplied by 10 raised to the power of *y*”, i.e., *x* · 10<sup>*y*</sup>. More precisely, a **double** value consists of a mantissa with an optional leading sign (“+” or “-”), optionally followed by the character **E** or **e** followed by an integer (the exponent). The mantissa must be a decimal number: an integer optionally followed by a period (.) optionally followed by another integer. If the leading sign is omitted, “+” is assumed. An omitted **E** or **e** (and associated exponent) means that a value of 0 is assumed for the exponent. If the **E** or **e** is present, it must be followed by an integer, or else an error results. The integer exponent must consist of a decimal number optionally preceded by a leading sign (“+” or “-”). If the sign is omitted, “+” is assumed. The following are examples of legal literal **double** values:

-1E4, +4, 234.234e3, 6.02E-23, 0.3e+11, 2, 0, -0, INF, -INF, NaN

As described in Section 3.4, SBML uses a subset of the MathML 2.0 standard (W3C, 2000b) for expressing mathematical formulas in XML. This is done by stipulating that the MathML language be used whenever a mathematical formula must be written into an SBML model. Doing this, however, requires facing two problems: first, the syntax of numbers in scientific notation (“e-notation”) is different in MathML from that just described for **double**, and second, the value space of integers and floating-point numbers in MathML is not defined in the same way as in XML Schema 1.0. We elaborate on these issues in Section 3.4.2; here we summarize the solution taken in SBML. First, within MathML, the mantissa and exponent of numbers in “e-notation” format must be separated by one `<sep/>` element. This leads to numbers of the form `<cn type="e-notation"> 2 <sep/> -5 </cn>`. Second, SBML stipulates that the representation of numbers in MathML expressions obey the same restrictions on values as defined for types **double** and **int** (Section 3.1.3).

### 3.1.6 Type ID

The XML Schema 1.0 type **ID** is identical to the XML 1.0 type **ID**. The literal representation of this type consists of strings of characters restricted as summarized in Figure 5. Note that this definition is different from that in the XML 1.1 specification, where the definition of the **ID** type was expanded and changed. SBML uses the original 1.0 version.

NameChar ::= letter | digit | '.' | '-' | '-' | ':' | CombiningChar | Extender
ID ::= ( letter | '-' | ':' ) NameChar*

<caption>**Figure 5:** Type ID expressed in the variant of BNF used by the XML 1.0 specification (Bray et al., 2004). The characters ( and ) are used for grouping, the character * indicates "zero or more times", and the character | indicates "or". The production letter consists of the basic upper and lower case alphabetic characters of the Latin alphabet along with a large number of related characters defined by Unicode 2.0; similarly, the production digit consists of the numerals 0..9 along with related Unicode 2.0 characters. The CombiningChar production is a list of characters that add such things as accents to the preceding character. (For example, the Unicode character #x030A when combined with 'a' produces 'á'.) The Extender production is a list of characters that extend the shape of the preceding character. Please consult the XML 1.0 specification (Bray et al., 2004) for the complete definitions of letter, digit, CombiningChar, and Extender.</caption>

In SBML, type **ID** is the data type of the **metaID** attribute on **SBase**, described in Section 3.2 on p. 14. An important aspect of **ID** is the XML requirement that a given value of **ID** must be unique throughout an XML document. All data values of type **ID** are considered to reside in a single common global namespace spanning the entire XML document, regardless of the attribute where type **ID** is used and regardless of the level of nesting of the objects (or XML elements).
### 3.1.7 Type SId

The type `SId` is the type of the `id` attribute found on the abstract class `SBase`, and thus available on every component class derived from `SBase` in SBML Level 3 Version 2 Core. `SId` is a data type derived from the basic XML type `string`, but with restrictions about the characters permitted and the sequences in which those characters may appear. The definition is shown in Figure 6.

<figure><img src="image_9.png" /><figcaption>Figure 6: The definition of the type `SId`. (Please see the caption of Figure 5 for an explanation of the notation.)</figcaption></figure>

The equality of `SId` values is determined by an exact character sequence match; i.e., comparisons of these identifiers must be performed in a case-sensitive manner. This applies to all uses of `SId`.

Type `SId` is purposefully not derived from the XML `ID` type (Section 3.1.6). Using `ID` would force all SBML identifiers to exist in a single global namespace, affecting not only **Reaction** local parameter definitions but also SBML packages for (e.g.) hierarchical model composition. Further, the use of `ID` for SBML identifiers would have limited utility because MathML 2.0 `ci` elements are not of the type `IDREF` (see Section 3.4). Since the `IDREF`/`ID` linkage cannot be exploited in MathML constructs, the utility of XML's `ID` type is greatly reduced. Finally, unlike `ID`, `SId` does not include Unicode character codes; the identifiers are plain text.

### 3.1.8 Type SIdRef

Type `SIdRef` is used for all attributes that refer to identifiers of type `SId` in a **Model** object. This type is derived from `SId`, but with the restriction that the value of an attribute having type `SIdRef` must equal the value of some `SId` attribute in the model where it appears. In other words, a `SIdRef` value must be an existing identifier in a model.

As with `SId`, the equality of `SIdRef` values is determined by exact character sequence match; i.e., comparisons of these identifiers must be performed in a case-sensitive manner.

### 3.1.9 Type UnitSId

The type `UnitSId` is derived from `SId` (Section 3.1.7) and has identical syntax. The `UnitSId` type is used as the data type for the identifiers of units (Section 4.4.1 on p. 42) in SBML objects. The purpose of having a separate type for such identifiers is to enable the space of possible unit identifier values to be separated from the space of all other identifier values in SBML. The equality of `UnitSId` values is determined by an exact character sequence match; i.e., comparisons of these identifiers must be performed in a case-sensitive manner.

A number of reserved symbols are defined in the space of values of `UnitSId`. These reserved symbols are the list of base unit names defined in Table 2 on p. 44.

### 3.1.10 Type UnitSIdRef

Type `UnitSIdRef` is used for all attributes that refer to identifiers of type `UnitSId`, which are the identifiers of units (Section 4.4.1 on p. 42) in SBML objects. This type is derived from `UnitSId`, but with the restriction that the value of an attribute having type `UnitSIdRef` must match either the value of a `UnitSId` attribute in the model, or one of the base units in Table 2 on p. 44. In other words, the value of a `UnitSIdRef` attribute must be an existing unit identifier in the model or in SBML.

As with `UnitSId`, the equality of `UnitSIdRef` values is determined by exact character sequence match; i.e., comparisons of these identifiers must be performed in a case-sensitive manner.
### 3.1.11 Type LocalSId

The `LocalSId` type is used as the data type for the `id` attribute of `LocalParameter`. The type `LocalSId` is derived from `SId` (Section 3.1.7) and has identical syntax; it is defined as its own type to make it easier to specify a modified scope for identifiers referenced by mathematical formulas inside `Reaction` objects.

As explained in Section 3.3.1 on p. 18, each `Reaction` object introduces a local namespace for local parameter identifiers (i.e., the `id` attribute values of `LocalParameter` objects within that `Reaction`). The consequence is that any `math <ci>` child of the `KineticLaw` whose text matches the `id` value of a `LocalParameter` in that same `KineticLaw` is taken to refer to that `LocalParameter` object, and not to any other object that may have the same `id` value in the rest of the `Model`. The `LocalSId` value of a `LocalParameter` object's `id` attribute is not part of the `SId` namespace of the model, nor of the `LocalSId` namespace of any other `Reaction` object.

### 3.1.12 Type SBOTerm

The type `SBOTerm` is used as the data type of the attribute `sboTerm` on `SBase`. The type consists of strings of characters matching the restricted pattern described in Figure 7.

<figure><img src="image_10.png" /><figcaption>Figure 7: The definition of `SBOTerm`. (Please see the caption of Figure 5 for an explanation of the notation.)</figcaption></figure>

Examples of valid string values of type `SBOTerm` are `"SBO:0000014"` and `"SBO:0003204"`. These values are meant to be the identifiers of terms from an ontology whose vocabulary describes entities and processes in computational models. Section 5 on p. 91 provides more information about the ontology and principles for the use of these terms in SBML models.

## 3.2 Type SBase

Nearly every object composing an SBML Level 3 model definition has a specific data type that is derived directly or indirectly from a single abstract type called `SBase`. In addition to serving as the parent class for most other classes of objects in SBML, this base type is designed to allow a modeler or a software package to attach arbitrary information to each major element or list in an SBML model. The definition of `SBase` is presented in Figure 8.

<figure><img src="image_11.png" /><figcaption>Figure 8: The definition of abstract class `SBase`. Please refer to Section 1.4 for a summary of the notation used here.</figcaption></figure>

`SBase` contains four attributes and two subobjects, all of which are optional: `id`, `name`, `metaid`, `sboTerm`, `Notes`, and `Annotation`. These are discussed separately in the following subsections.
### 3.2.1 The id attribute

The `id` attribute is an optional attribute on the `SBase` class. The `id` attribute value on an object serves as its identifier. The data type of `id` on `SBase` is `SId` (Section 3.1.7 on p. 13). Every `SId` attribute value in a `Model` object must be unique within that `Model` object. In certain well-specified circumstances, other SBML objects can refer to the object using its identifier.

SBML components may stipulate that `id` takes on a value taken from a type derived from `SId` in order to impose additional requirements or restrictions, such as scope restrictions. (For example, this is the case with unit identifiers and `UnitSId`, Section 3.1.9 on p. 13.) When SBML Level 3 packages define new classes that inherit from `SBase`, they may also refine the type of the `id` attribute on those classes. In addition, although `id` is optional on `SBase`, object classes derived from `SBase` may stipulate that `id` is a required attribute for those classes. Outside of the specializations of `SId`, the set of `SId` values in a model is referred to as the “`SId` namespace of the model”.

In lower Level/Version combinations of SBML, the attributes `id` and `name` are defined on individual object subclasses. The placement of these attributes on `SBase` in SBML Level 3 Version 2 is a notable change in the internal SBML class hierarchy, although it has no practical effect for any class that has mathematical meaning—all the same objects with meaning (e.g., species, parameters, etc.) have exactly the same `id` attributes as in SBML Level 3 Version 1. This topic is discussed further in Section 3.3 on p. 18.

### 3.2.2 The name attribute

The attribute `name` is an optional attribute on `SBase` of type `string`. In contrast to the `id` attribute, the `name` attribute is not intended to be used for cross-referencing purposes within a model. Its purpose instead is to provide a human-readable label for a component. The data type of `name` is the type `string` defined in XML Schema (Biron and Malhotra, 2000; Thompson et al., 2000) and discussed further in Section 3.1 on p. 11. SBML imposes no restrictions as to the content of `name` attributes beyond those restrictions defined by the `string` type in XML Schema. In addition, there are no restrictions on the uniqueness of `name` values in a model (unlike the restrictions on `id` values discussed in Section 3.3.1 on p. 18).

### 3.2.3 The metaid attribute

The `metaid` attribute is present for supporting metadata annotations using RDF (Resource Description Format; Lassila and Swick, 1999). It has a data type of XML `ID` (the XML identifier type; see Section 3.1.6 on p. 12), which means each `metaid` value must be globally unique within an SBML file. The `metaid` value serves to identify a model component for purposes such as referencing that component from metadata placed within `annotation` elements (see Section 3.2.6 on the following page). Such metadata can use RDF `description` elements, in which an RDF attribute called `"rdf:about"` points to the `metaid` identifier of an object defined in the SBML model. This topic is discussed in greater detail in Section 6 on p. 100.

### 3.2.4 The sboTerm attribute

The attribute called `sboTerm` is provided on `SBase` to support the use of the Systems Biology Ontology (SBO; see Section 5 on p. 91). When a value is given to this attribute, it must conform to the data type `SBOTerm` (Section 3.1.12 on the previous page). SBO terms are a type of optional annotation, and each different class of SBML object derived from `SBase` imposes its own requirements about the values permitted for `sboTerm`. Specific details on the permitted values are provided with the definitions of SBML classes throughout this specification document, and a broader discussion is provided in Section 5 on p. 91.

### 3.2.5 Notes

The subcomponent `Notes` in `SBase` is a container for XHTML 1.0 (Pemberton et al., 2002) content. It is intended to serve as a place for storing optional information intended to be seen by humans. An example use of `Notes` would be to contain formatted user comments about the model element in which the `Notes` object is enclosed. Every object derived directly or indirectly from type `SBase` can have a separate `Notes` object instance, allowing users considerable freedom when adding comments to their models.
## XML namespace requirements for notes

In XML, the **notes** elements must declare the use of the XHTML XML namespace. This can be done in multiple ways. One way is to place a namespace declaration for the appropriate namespace URI (which is http://www.w3.org/1999/xhtml) on the top-level **SBML** object (see Section 4.1 on p. 34) and then reference the namespace in the **notes** content using a prefix. The following example illustrates this approach:

```xml
<sbml xmlns="http://www.sbml.org/sbml/level3/version2/core" level="3" version="2"
      xmlns:xhtml="http://www.w3.org/1999/xhtml">
  ...
  <notes>
    <xhtml:body>
      <xhtml:center><xhtml:h2>A Simple Mitotic Oscillator</xhtml:h2></xhtml:center>
      <xhtml:p>A minimal cascade model for the mitotic oscillator
      involving cyclin and cdc2 kinase</xhtml:p>
    </xhtml:body>
  </notes>
  ...
</sbml>
```

Another approach is to declare the XHTML namespace within the **notes** content itself, as in the following example:

```xml
...
<notes>
  <body xmlns="http://www.w3.org/1999/xhtml">
    <center><h2>A Simple Mitotic Oscillator</h2></center>
    <p>A minimal cascade model for the mitotic oscillator involving cyclin and cdc2 kinase</p>
  </body>
</notes>
...
```

The `xmlns="http://www.w3.org/1999/xhtml"` declaration on **body** as shown above changes the default XML namespace within it, such that all of its content is by default in the XHTML namespace. This is a particularly convenient approach because it obviates the need to prefix every element with a namespace prefix (i.e., `"xhtml:"` in the earlier example). Other approaches are also possible.

### The XHTML content of notes

SBML Level 3 does not require the content of a **Notes** object to be any particular XHTML element; the content simply should be any well-formed XHTML content. There is only one restriction, and it comes from the requirements of XML: the **notes** element must not contain an XML declaration or a DOCTYPE declaration. That is, **notes** must not contain

```xml
<?xml version="1.0" encoding="UTF-8"?>
```

nor the following (where the following is only one specific example of a DOCTYPE declaration):

```xml
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
```

### 3.2.6 Annotation

Whereas **Notes** is a container for content to be shown directly to humans, **Annotation** is a container for optional software-generated content *not* meant to be shown to humans. Every object derived from **SBase** can have its own **Annotation** object instance. In XML, the **Annotation** content type is **any**, allowing essentially arbitrary well-formed XML data content. SBML places only a few restrictions on the organization of the content; these are intended to help software tools read and write the data as well as help reduce conflicts between annotations added by different tools.

### The use of XML namespaces in annotations

At the outset, software developers should keep in mind that multiple software tools may attempt to read and write annotation content. To reduce the potential for collisions between annotations written by different
```xml
<annotation>
  <mysim:molecule xmlns:mysim="http://www.mysim.org/ns" mysim:weight="18.02" mysim:atoms="3"/>
  <mysim:atom xmlns:mysim="http://www.mysim.org/ns" mysim:weight="18.02" mysim:atoms="3"/>
</annotation>
```

On the other hand, the following example is valid. The elements `molecule`, `bonds`, and `icon` inside the annotation each use a separate XML namespace (i.e., `http://www.mysim.org/ns`, `http://www struct.org/ns`, and `http://othersim.com`, respectively, declared in the elements where they appear):

```xml
<annotation>
  <mysim:molecule xmlns:mysim="http://www.mysim.org/ns" mysim:weight="18.02" mysim:atoms="3"/>
  <struct:bonds xmlns:struct="http://www struct.org/ns" struct:number="2" struct:type="ionic"/>
  <othersim:icon xmlns:othersim="http://www.othersim.com/">WS2002</othersim:icon>
</annotation>
```

For completeness, we note that annotations legally can be empty (but such annotations have no meaning):

`<annotation />`

It is worth keeping in mind that although XML namespace names must be URIs, they are (like all XML namespace names) *not required* to be directly usable in the sense of identifying an actual, retrieval document or resource on the Internet (Bray et al., 1999). URIs such as `http://www.mysim.org/` may appear as though they are (e.g.,) Internet addresses, but they are not the same thing. This style of URI strings, using a domain name and other parts, is only a simple and commonly-used way of creating a unique name string.

Finally, note that the namespaces being referred to here are XML namespaces specifically in the context of the `annotation` element on `SBase`. The namespace issue here is unrelated to the namespaces discussed in Section 3.3.1 in the context of component identifiers in SBML.

## Content of annotations and implications for software tools

**Annotation** exists as a subobject of `SBase` in order that software developers may attach optional application-specific data to the elements in an SBML model. However, it is important that this facility is not misused. In particular, it is *critical* that data essential to a model definition or that can be encoded in existing SBML elements is *not* stored in annotations. Parameter values, functional dependencies between model elements, etc., should not be recorded as annotations. It is crucial to keep in mind the fact that data placed in annotations can be freely ignored by software applications. If such data affect the interpretation of a model, then software interoperability is greatly impeded. Recommendations regarding the use of any sort of annotation are given in Section 8.1.4 on p. 147.

## 3.3 The id and name attributes on SBase

Every object whose class is derived from `SBase` may have values for the `id` and `name` attributes. In this section, we elaborate on the use of `id` and `name` and discuss some of the implications.

### 3.3.1 The id attribute and identifier scoping

A model can contain a large number of components representing different parts. This leads to a problem in deciding the scope of an identifier: in what contexts does a given identifier *X* represent the same thing? The approaches used in existing simulation software tend to fall into two categories which we may call global and local. The *global* approach places all identifiers into a single global space of identifiers, so that an identifier *X* represents the same thing wherever it appears in a given model definition. The *local* approach places symbols in separate identifier namespaces, depending on the context, where the context may be, for example, individual reaction rate expressions. The latter approach means that a model may use the same identifier *X* in different rate expressions and have each instance represent a different quantity.

The scoping rules in SBML Level 3 are intended as a compromise to help support both scenarios:

* The identifier (i.e., the value of the attribute `id`) of every `SBase`-derived class that does not stipulate otherwise must be unique across the set of all such identifiers in the model. This means, for example, that a reaction and a species definition cannot both have the same identifier.
* The identifier of every **UnitDefinition** must be unique across the set of all such identifiers in the model plus the set of base unit definitions in Table 2 on p. 44. However, unit identifiers live in a separate space of identifiers from other identifiers in the model, by virtue of the fact that the data type of unit identifiers is **UnitSId** (Section 3.1.9 on p. 13) and not **SId**.

* Each **Reaction** instance (see Section 4.11 on p. 68) establishes a separate private local space for local parameters represented by objects of class **LocalParameter**. Within the definition of that reaction, local parameter identifiers override (shadow) identical identifiers from the **SId** namespace of the model outside of that reaction. Conversely, local parameters in a given **KineticLaw** object are not visible outside of that kinetic law's **Reaction**. To emphasize this, a **LocalParameter**'s **id** attribute has type **LocalSId** (Section 3.1.11 on p. 14) rather than **SId**.

* The identifier of every **SBase**-derived class defined by an SBML Level 3 package is part of the **SId** namespace of the model by default. However, a package may declare the **id** attribute of a new class to have a type derived from **SId**, whether it is defined in SBML Level 3 Core or one defined by that Level 3 package. Elements with an **id** of that type follow the rules of uniqueness defined for the type. For example, the SBML Level 3 Hierarchical Model Composition package defines a **PortSId** type, and **Port** objects have an **id** attribute of that type. The Hierarchical Model Composition package stipulates that all **Port** element **id** values in a given **Model** must be unique only among the other **Port** objects in that **Model**.

### 3.3.2 Motivations for defining *id* and *name* on SBase

SBML Level 3 Version 2 Core puts the **id** and **name** attributes directly on the **SBase** abstract class. This is a departure from previous Level/Version combinations of SBML, in which **id** and **name** were defined on individual SBML component classes. The following were the motivations for this change.

* Object classes in SBML originally were given **id** attributes only if they had meaning for mathematical expressions. (For instance, the concentrations of species, the sizes of compartments, etc.) As SBML evolved, more objects were given **id** attributes but these were not always associated with a mathematical meaning. When SBML Level 3 packages were introduced, not only did further uses of **id** become apparent: it also became possible for Level 3 packages to add nuances of meanings that Level 3 Core did not. Thus, while Level 3 Core may not define a use for an **id** attribute on a given object, a Level 3 package might. Examples exist in the SBML Level 3 Graphical Layout and Hierarchical Model Composition packages.

* The **metaid** attribute on **SBase** may seem to fulfill a similar role as an identifier for every object in an SBML document. However, for several reasons it is unsuitable for use as a substitute for **id**. First, owing to the fact that its data type is the XML type **ID**, it has a less restricted syntax (for instance, allowing Unicode characters). Second, its scope cannot be ammended as needed for elements such as the **UnitDefinition** or **LocalParameter**, because XML **ID** is defined to have document-wide uniqueness properties. Finally, having a *model*-wide scope instead of a *document*-wide scope has been found desirable for the SBML Level 3 Hierarchical Model Composition package.

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

* The **name** attribute is logically paired with **id**, to provide the option of a user-readable moniker for any object with an **id** attribute. With **id** on **SBase**, it makes sense to put **name** on **SBase** too.

This design change (moving **id** and **name**) does not have an impact on the final written XML form of SBML for constructs that had **id** and **name** attributes in SBML Level 3 Version 1 (or earlier versions of SBML).

### 3.3.3 Use of SBML Level 3 Version 1 packages and implications for identifiers

Packages created and designed for use with SBML Level 3 Version 1 may be used in SBML Level 3 Version 2 documents, and be interpreted in exactly the same manner as before. They may not, however, take full
advantage of the new features and constructs in Version 2. This means the following:

* Any object class in an SBML Level 3 Version 1 package that inherits from **SBase** will not inherit the new **id** and **name** attributes on **SBase**.

* An object identifier from a SBML Level 3 Version 1 package may not be used in **Math** constructs in SBML Level 3 Version 2 Core, nor as the value of any **SIdRef** type attribute in a Core construct.

* No object from a SBML Level 3 Version 1 package is considered to have mathematical meaning in core: no such object's **SId** may be used as the target of a rule nor of an assignment, nor may it be used in any MathML outside of that package.

However, if a package defines an **SIdRef** that may refer to any **SBase**, it is legal for those references to point to SBML Level 3 Version 2 **SIds**. In particular:

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

* An **SIdRef** defined in a SBML Level 3 Version 1 package may be used to reference an element from an SBML Level 3 Version 2 package.

* Any **Math** object defined in a SBML Level 3 Version 1 package may reference any SBML Level 3 Version 2 package **SId** defined as having mathematical meaning.

To take some examples: the **reference** attribute of a SBML Level 3 Version 1 Layout **GeneralGlyph** is of type **SIdRef**, and was designed to be able to point to arbitrary SBML Level 3 Version 1 core and package elements. If used in a Level 3 Version 2 Core document, it could now point to an **AssignmentRule**, which it would not have been able to do in a SBML Level 3 Version 1 document. Alternatively, it could point to an SBML Level 3 Version 2 package element that inherited an **SId** from **SBase**. Similarly, any **Math** element in an SBML Level 3 Version 1 package must be designed to be able to contain **SIdRefs** to SBML Level 3 Version 1 Core elements with mathematical meaning, but whose meaning might have been changed by a SBML Level 3 Version 1 package. These formulas may now skip the middle man and refer directly to SBML Level 3 Version 2 package **SIds** that have their own mathematical meaning.

## 3.4 Mathematical formulas in SBML Level 3

Mathematical expressions in SBML Level 3 are represented using MathML 2.0 (W3C, 2000b). MathML is an international standard for encoding mathematical expressions using XML. There are two principal facets of MathML, one for encoding content (i.e., the semantic interpretation of a mathematical expression), and another for encoding presentation or display characteristics. SBML only makes direct use of a subset of the content portion of MathML. However, it is not possible to produce a completely smooth and conflict-free interface between MathML and other standards used by SBML (in particular, XML Schema). Two specific issues and their resolutions are discussed in Section 3.4.2 on the following page.

The XML namespace URI for all MathML elements is http://www.w3.org/1998/Math/MathML. Everywhere MathML content is allowed in SBML, the MathML elements must be properly placed within the MathML 2.0 namespace. In XML, this can be accomplished in a number of ways, and the examples throughout this specification illustrate the use of this namespace and MathML in SBML. Please refer to the W3C document by Bray et al. (1999) for more technical information about using XML namespaces.

### 3.4.1 Subset of MathML used in SBML Level 3 Core

The subset of MathML elements used in SBML Level 3 Version 2 Core is listed below. An SBML Level 3 package may extend this subset (and if so, must define `required="true"` on the SBML container Section 4.1).

* `token`: `cn`, `ci`, `csymbol`, `sep`

* `general`: `apply`, `piecewise`, `piece`, `otherwise`, `lambda` (however, as discussed elsewhere, `lambda` is restricted to use in `FunctionDefinition`)
* relational operators: `eq`, `neq`, `gt`, `lt`, `geq`, `leq`

* arithmetic operators: `plus`, `minus`, `times`, `divide`, `power`, `root`, `abs`, `exp`, `ln`, `log`, `floor`, `ceiling`, `factorial`, `quotient`, `max`, `min`, `rem`

* logical operators: `and`, `or`, `xor`, `not`, `implies`

* qualifiers: `degree`, `bvar`, `logbase`

* trigonometric operators: `sin`, `cos`, `tan`, `sec`, `csc`, `cot`, `sinh`, `cosh`, `tanh`, `sech`, `csch`, `coth`, `arcsin`, `arccos`, `arctan`, `arcsec`, `arccsc`, `arccot`, `arcsinh`, `arccosh`, `arctanh`, `arcsech`, `arccsch`, `arccoth`

* constants: `true`, `false`, `notanumber`, `pi`, `infinity`, `exponentiale`

* MathML annotations: `semantics`, `annotation`, `annotation-xml`

The inclusion of logical operators, relational operators, `piecewise`, `piece`, and `otherwise` elements facilitates the encoding of discontinuous expressions.

As defined by MathML 2.0, the semantic interpretation of the mathematical functions listed above follows the definitions of the functions laid out by Abramowitz and Stegun (1977) and Zwillinger (1996). Readers are directed to these sources and the MathML specification for information for further information, such as which principal values of the inverse trigonometric functions to use.

Software authors should take particular note of the MathML semantics of the N-ary operators `plus`, `times`, `and`, `or` and `xor`, when they are used with different numbers of arguments. The MathML specification (W3C, 2000b) appendix C.2.3 describes the semantics for these operators with zero, one, and more arguments. However, while `min` and `max` are also defined as N-ary operators, MathML does not define their meaning when used with no arguments. This SBML specification also does not define the meaning of `min` and `max` with zero arguments, though a Level 3 package may add a definition. In the absence of such a package, the use of `min` or `max` with zero arguments is discouraged.

The following are the only attributes permitted on MathML elements in SBML (in addition to the `xmlns` attribute on `math` elements):

* `style`, `class` and `id` on any element;

* `encoding` on `csymbol`, `annotation` and `annotation-xml` elements;

* `definitionURL` on `ci`, `csymbol` and `semantics` elements; and

* `type` and `sbml:units` (see Section 3.4.2) on `cn` elements.

Missing values for the MathML attributes are to be treated in the same way as defined by MathML 2.0. These restrictions on attributes are designed to confine the MathML elements to their default semantics and to avoid conflicts in the interpretation of the type of token elements.

### 3.4.2 Numbers and `cn` elements

In MathML, literal numbers are written as the content portion of a particular element called `cn`. This element takes an optional attribute, `type`, used to indicate the `type` of the number (such as whether it is meant to be an integer or a floating-point quantity). Here is an example of its use:

```xml
<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 content of a `cn` element must be a number. The number can be preceded and succeeded by whitespace (see Section 3.4.5 on p. 24). The following are the only permissible values for the `type` attribute on MathML `cn` elements: `e-notation`, `real`, `integer`, and `rational`. The value of the `type` attribute defaults to `real` if it is not specified on a given `cn` element.

#### Value space restrictions on `cn` content

SBML imposes certain restrictions on the value space of numbers allowed in MathML expressions. According to the MathML 2.0 specification, the values of the content of `cn` elements do not necessarily have to conform
to any specific floating-point or integer representations designed for CPU implementation. For example, in strict MathML, the value of a `cn` element could exceed the maximum value that can be stored in an IEEE 64 bit floating-point number (IEEE 754). This is different from the XML Schema type **double** that is used in the definition of floating-point attributes of objects in SBML; the XML Schema **double** is restricted to IEEE double-precision 64-bit floating-point type IEEE 754-1985. To avoid an inconsistency that would result between numbers elsewhere in SBML and numbers in MathML expressions, SBML Level 3 Version 2 Core imposes the following restriction on MathML content appearing in SBML:

* Integer values (i.e., the values of `cn` elements having `type="integer"` and both values in `cn` elements having `type="rational"`) must conform to the `int` type (Section 3.1.3 on p. 11)

* Floating-point values (i.e., the content of `cn` elements having `type="real"` or `type="e-notation"`) must conform to the **double** type (Section 3.1.5 on p. 11)

### Syntactic differences in the representation of numbers in scientific notation

It is important to note that MathML uses a style of scientific notation that differs from what is defined in XML Schema, and consequently what is used in SBML attribute values. The MathML 2.0 type `e-notation` (as well as the type `rational`) requires the mantissa and exponent to be separated by one `<sep/>` element. The mantissa must be a real number and the exponent part must be a signed integer. This leads to expressions such as

`<cn type="e-notation"> 2 <sep/> -5 </cn>`

for the number $2 \cdot 10^{-5}$. It is especially important to note that the following expression,

`<cn type="e-notation"> 2e-5 </cn>`

is not valid in MathML 2.0 and therefore cannot be used in MathML content in SBML. However, elsewhere in SBML, when an attribute value is declared to have the data type **double** (a type taken from XML Schema), the compact notation `2e-5` is in fact allowed. In other words, within MathML expressions contained in SBML (and only within such MathML expressions), numbers in scientific notation must take the form `<cn type="e-notation"> 2 <sep/> -5 </cn>`, and everywhere else they must take the form `2e-5` or `2E-5`.

This is a regrettable difference between two standards that SBML replies upon, but it is not feasible to redefine these types within SBML because the result would be incompatible with parser libraries written to conform to the MathML and XML Schema standards. It is also not possible to use XML Schema to define a data type for SBML attribute values permitting the use of the `<sep/>` notation, because XML attribute values cannot contain XML elements—that is, `<sep/>` cannot appear in an XML attribute value.

### Units associated with numbers in MathML cn expressions

What units should be attributed to numbers appearing inside MathML `cn` elements? One answer is to assume that the units should be “whatever units are appropriate in the context where the number appears”. This implies that units can always be assigned unambiguously to any number by inspecting the expression in which it appears, and this turns out to be false. Another answer is that numbers should be considered “dimensionless”. Many people argue that this is the correct interpretation, but even if it is, there is an overriding practical reason why it cannot be adopted for SBML’s domain of application: when numbers appear in expressions in SBML, they are *rarely intended* by the modeler to have the unit “dimensionless” even if the unit is not declared—instead, the numbers are *supposed* to have specific units, but the units are usually undeclared. (Being “dimensionless” is not the same as having *undeclared* units!) If SBML defined numbers as being *by default* dimensionless, it would result in many models being technically incorrect without the modeler being aware of it unless their software tools performed dimensional analysis. Many software tools do not perform unit analysis, and so potential errors due to inconsistent units in a model would not be detected until other researchers and database curators attempted to use the model in software packages that *did* check units. We believe the negative impact on interoperability would be too high.

SBML borrows an idea from CellML (Hedley et al., 2001), another model definition language with goals similar to SBML’s, and allows an additional attribute to appear on MathML `cn` elements; the value of this
attribute can be used to indicate the unit of measurement to be associated with the number in the content of the `cn` element. The attribute is named `units` but, because it appears inside `MathML` element (which is in the XML namespace for `MathML` and not the namespace for `SBML`), it must always be prefixed with an XML namespace prefix for the `SBML Level 3 Version 2 Core` namespace. The value of the attribute must have the data type `UnitIdRef` (Section 3.1.10 on p. 13) and can be the identifier of a `UnitDefinition` object in the model or a base unit listed in Table 2 on p. 44. The following example illustrates how this attribute can be used to define a number with value `10` and unit of measurement `second`:

```xml
<math xmlns="http://www.w3.org/1998/Math/MathML"
      xmlns:sbml="http://www.sbml.org/sbml/level3/version2/core">
  <cn type="integer" sbml:units="second"> 10 </cn>
</math>
```

In this example, we chose to use the string `sbml` as the XML namespace prefix for the `SBML Level 3 Version 2 Core` namespace, which leads to the use of `sbml:units` as the attribute on the `cn` element. We could have used another prefix string besides `sbml`, and the definition of the prefix could also have appeared on a higher-level element in the model. Section 4.1 on p. 34 provides more information about the XML namespace for `SBML Level 3 Version 2 Core`.

An alternative approach to specifying units is to avoid using `cn` elements altogether, and always use `ci` elements to reference `Parameter` objects having both value and units defined. In the example above, we could have avoided putting the literal number `10` inside the mathematical expression, and instead, defined a parameter in the model, given it the value `10` and unit `second`, and finally, referred to that parameter in the `math` content above. The approach of using named parameters provides additional power and advantages over simply using `sbml:units` attributes on `cn` elements; for example, `Parameter` allows the association of terms from the Systems Biology Ontology (SBO; Section 5) as well as MIRIAM annotations (Section 6).

In summary, a literal number within `MathML` content without an `SBML units` attribute has no declared unit associated with it. Either of the approaches described above (i.e., avoiding `cn` in favor of `ci` elements and `Parameter` objects, or using an `sbml:units` attribute on `cn`) leads to formulas whose units can be fully determined, enabling software tools to perform dimensional analysis and, potentially, detect and report problems with the model. Conversely, in the absence of an `SBML units` attribute on a `MathML cn` element, no unit is associated with the number within the `cn` element. If the example above lacked the attribute `sbml:units`, the value `10` would have no declared unit associated with it.

Finally, although `SBML` provides ways of associating units with numbers and entities, `SBML` does not stipulate that implicit unit conversions be performed. Section 3.4.13 explores this topic in more detail.

### 3.4.3 Use of ci elements in MathML expressions in SBML

The content of a `ci` element must be an `SBML` identifier that is declared elsewhere in the model. The identifier can be preceded and succeeded by whitespace within the `ci`. The set of possible identifiers that can appear in a `ci` element depends on the containing element in which the `ci` is used:

* If a `ci` element appears in the `math` body of a `FunctionDefinition` object (Section 4.3 on p. 40), the referenced identifier must be either (i) one of the declared arguments to that function, or (ii) the identifier of another `FunctionDefinition` object in the model.

* Otherwise, the identifier referenced by the `ci` element must belong to an `SBML` object that (a) is in the `SIId` namespace of the `Model`, (b) has mathematical meaning in `SBML`, and (c) is within the relevant scope. Table 1 on the next page lists the only possible such identifiers in `SBML Level 3 Version 2 Core`.

The content of `ci` elements in `MathML` formulas outside of a `KineticLaw` or `FunctionDefinition` must always refer to objects declared in the top-level global namespace; i.e., `SBML` uses *early binding* semantics. Inside of `KineticLaw`, `ci` elements can additionally refer to identifiers of `LocalParameter` objects defined within that `KineticLaw` instance; see Section 4.11.5 on p. 74 for more information.

If a `MathML ci` element references an identifier in an `SBML` namespace that is not recognized by the interpreter reading a given `SBML` document (that is, if the referent object is defined by an `SBML Level 3`
<table><caption>**Table 1:** The possible interpretations of different SBML component identifiers when they appear in MathML ci elements outside the body of a **FunctionDefinition** object. (Inside a **FunctionDefinition** object's mathematical formula, different rules apply, as described in Section 3.4.3 on the previous page.)</caption><thead><tr><th>Identifier kind</th><th>Interpretation</th><th>Units</th></tr></thead><tbody><tr><td>FunctionDefinition</td><td>a call to the function (using a MathML <strong>apply</strong> element)</td><td>See Section 4.3.4 on p. 41</td></tr><tr><td>Compartment</td><td>the size of the compartment</td><td>See Section 4.5.4 on p. 48</td></tr><tr><td>Species</td><td>the quantity of the species, which may be either an <strong>amount of substance</strong> or a <strong>concentration</strong>, depending on the value of the <strong>Species</strong> object's attribute <strong>hasOnlySubstanceUnits</strong></td><td>See Section 4.6.5 on p. 51</td></tr><tr><td>Parameter</td><td>the value of the parameter</td><td>See Section 4.7.3 on p. 55</td></tr><tr><td>Reaction</td><td>the rate of the reaction</td><td>See Section 4.11.7 on p. 78</td></tr><tr><td>SpeciesReference</td><td>the stoichiometry of the indicated reactant or product in the reaction where the <strong>SpeciesReference</strong> object is defined</td><td>See Section 4.11.3 on p. 72</td></tr><tr><td>LocalParameter</td><td>the value of the local parameter within the reaction where the <strong>LocalParameter</strong> object is defined</td><td>See Section 4.11.6 on p. 75</td></tr><tr><td>Object class defined in a Level 3 package</td><td>the value defined for that object by the package</td><td>See that package's specification</td></tr></tbody></table>

package not supported by that software), the **math** element in which it appears no longer has a mathematical interpretation and may be ignored by the interpreter. If the interpreter cannot establish whether a referenced object is entirely missing from the model or is merely defined in an SBML namespace not recognized by the interpreter, it may produce a warning to the user. (The latter situation may arise if an SBML package is present in the SBML document with a **package:required** attribute of "true".)

### 3.4.4 Interpretation of boolean values

As noted already in Section 3.1.2 on p. 11, there is another unfortunate difference between the XML Schema 1.0 and MathML 2.0 standards that impacts mathematical expressions in SBML: in XML Schema, the value space of type **boolean** includes "true", "false", "1", and "0", whereas in MathML, only "true" and "false" count as Boolean values.

The impact of this difference is, thankfully, minimal because the XML Schema definition is only used for attribute values on SBML objects, and those values turn out never to be accessible from MathML content in SBML—values of **boolean** attributes on SBML objects can never enter into MathML expressions. Nevertheless, software authors and users should be aware of the difference.

SBML also allows models to use Boolean values in numerical contexts, and visa versa. In numerical contexts, the Boolean value **true** becomes the numerical value **1**, and the Boolean value **false** becomes the value **0**. The unit of measurement of **0** and **1** in such cases is considered to be **dimensionless**. In Boolean contexts, the numerical value **0** becomes the Boolean value **false**, and all other numerical values (positive and negative) become **true**. Converted numerical quantities (e.g., parameters) should have the unit **dimensionless** before conversion. Note that after conversions between Boolean and numerical values are performed, strict type checking may no longer be possible in some contexts, but the tradeoff is greater flexibility and simplicity for modelers.

### 3.4.5 Handling of whitespace

MathML 2.0 defines "whitespace" in the same way as XML does, i.e., the space character (Unicode hexadecimal code 0020), horizontal tab (code 0009), newline or line feed (code 000A), and carriage return (code 000D). In MathML, the content of elements such as **cn** and **ci** can be surrounded by whitespace characters. Prior to
using the content, this whitespace is “trimmed” from both ends: all whitespace at the beginning and end of the content is removed (Ausbrooks et al., 2003). For example, in <cn> 42 </cn>, the amount of white space on either side of the “42” inside the <cn> ... </cn> container does not matter. Prior to interpreting the content, the whitespace is removed altogether.

### 3.4.6 Use of `csymbol` elements in MathML expressions in SBML

SBML Level 3 uses the MathML `csymbol` element to denote certain built-in mathematical entities without introducing reserved names into the component identifier namespace. The `encoding` attribute of `csymbol` must be set to “text”. The `definitionURL` should be set to one of the following URIs defined by SBML:

* http://www.sbml.org/sbml/symbols/time. This represents the current simulation time. See Section 3.4.7 on p. 27 for more information. The unit of measurement associated with time is determined by the value of the attribute `timeUnits` on `Model`.

* http://www.sbml.org/sbml/symbols/delay. This represents a delay function. The delay function has the form `delay(x, d)`, taking two MathML expressions as arguments. The function's value is the value of argument `x`, but taken at a time `d` before the current time. There are no restrictions on the form of `x`. Since the parameter `d` represents a time value, the unit of measurement associated with `d` is expected to match the unit of time in the model as specified by the value of the `Model` attribute `timeUnits`. The value of the `d` parameter, when evaluated, must be numerical (i.e., a number in MathML real, integer, rational, or “e-notation” format) and be greater than or equal to 0. The unit of measurement associated with the return value of the delay function is identical to that of the parameter `x`. See Section 3.4.7 on p. 27 below for additional considerations surrounding the use of this `csymbol`.

* http://www.sbml.org/sbml/symbols/avogadro. This represents the numerical value of Avogadro's constant. The value of Avogadro's constant is determined experimentally; for the purposes of SBML Level 3 Version 2, the numerical value is taken to be the one recommended by the 2006 edition of CODATA (Mohr et al., 2008), but the unit of the value is `dimensionless`. In other words, the value of this `csymbol` is equivalent to the following:

$$ (6.02214179 \cdot 10^{23}) \cdot \text{dimensionless} $$

If the value of the constant is revised by international standards-setting organizations in the future, a future Version of the SBML Level 3 specification may stipulate a new value to be used for this `csymbol` constant. However, all software applications reading models expressed in this Version of SBML Level 3 should always use the value of Avogadro's constant given above. (In other words, changes will apply only beginning with a possible new Version of SBML Level 3 and not this existing version.)

* http://www.sbml.org/sbml/symbols/rateOf. This represents the instantaneous rate of change, with respect to time, of an entity in the model. It is a function that takes a single argument, an identifier of type `SId`. The allowable identifiers for use with `rateOf` in SBML Level 3 Version 2 Core are restricted to those of `Compartment`, `LocalParameter`, `Parameter`, `Species`, and `SpeciesReference` objects in the enclosing model; in addition, SBML Level 3 packages may define entities with mathematical meaning whose `rateOf`'s can be referenced. Note that `rateOf` is not allowed for `Reaction` objects, because their identifiers already represent the rate of change of the reaction, and calculating second derivatives is beyond the scope of this construct. Likewise, there is no sensible meaning to be given to the `rateOf` of a `FunctionDefinition`, `Event`, `Priority`, `Delay`, or other SBML entities.

The intent of this `csymbol` is to provide a means for models to refer to quantities that must naturally be computed as part of doing a dynamical analysis of a model. The `rateOf` `csymbol` is not intended to provide full numerical differentiation capabilities. The value of `rateOf` function for a symbol can be determined more straightforwardly as follows:

1. The `rateOf` for any symbol declared constant is zero. Note that in SBML Level 3 Version 2 Core, `LocalParameter` objects must always be constant; therefore, their `rateOf` value is always zero.

2. The `rateOf` for a symbol whose `SId` appears as the `variable` of a `RateRule` is the numerical value of that `RateRule`, using the current values of all symbols referenced in the rule's formula.
3. The rateOf for the amount of a Species having attribute boundaryCondition="false" and appearing in one or more reactions can be calculated from the stoichiometries and KineticLaw Math of every Reaction in which the species appears, plus appropriate conversionFactor values (see Section 4.11.7 on p. 77). If the species quantity is in terms of its concentration, the rate must be converted by the size of the Compartment in which it appears, which may itself be changing in time. This can be calculated as follows, where [x] is the concentration of species X, x the amount of species X, and V the size of the compartment in which species X is located:

$$
\begin{align*}
\frac{d[x]}{dt} &= \frac{d(x/V)}{dt} \\
&= \frac{1}{V} \cdot \frac{dx}{dt} + x \cdot \frac{d(1/V)}{dt} \\
&= \frac{1}{V} \cdot \frac{dx}{dt} - \frac{x}{V^2} \cdot \frac{dV}{dt}
\end{align*}
$$

When $dV/dt$ is equal to zero, the final term in the last line is zero.

4. The rateOf value for any valid target in SBML for time $t < 0$ will always be zero. This is because the rateOf csymbol may only point to SBML elements that change due to a RateRule or a Reaction, and neither of those constructs apply at $t < 0$.

An object whose SId identifier appears as the variable of an AssignmentRule, or which is calculated from an AlgebraicRule, may not be referenced by the rateOf csymbol. Similarly, it is also not valid to use the rateOf csymbol to reference a Species with a hasOnlySubstanceUnits attribute value of "false" and whose compartment appears as the variable of an AssignmentRule or whose size is calculated from an AlgebraicRule. In other words, anything whose value is directly or indirectly determined by an algebraic rule or an assignment rule is excluded.

In the event of a discontinuity, such as might happen due to an Event, a piecewise function, the beginning of a time course simulation (i.e., at $t = 0$), or due to a new construct defined in a package, the rate of change is defined as the right-handed rateOf for the symbol, that is, the derivative with respect to time of the symbol moving forward in time from the current time, and not the derivative with respect to time from the recent past up until the current time. Thus, the rateOf of a symbol will always be calculable from the set of current values of symbols in the model. No Event can affect the rateOf for a symbol except indirectly.

In simulations that progress in a stepwise fashion, such as stochastic simulations, the rateOf csymbol is still calculated as above, from any appropriate RateRule or KineticLaw. This effectively means that for stepwise simulations, the rateOf indicates the expected average rate of change of the corresponding symbol over time, even when the actual rate of change may be zero or discontinuous.

The following examples demonstrate these concepts. The XML fragment below encodes the formula $x + t$, where $t$ stands for time.

<math xmlns="http://www.w3.org/1998/Math/MathML">
<apply>
<plus/>
<ci> x </ci>
<csymbol encoding="text" definitionURL="http://www.sbml.org/sbml/symbols/time">
  <t>
  </csymbol>
</apply>
</math>

In the fragment above, the use of the token t is mostly a convenience for human readers—the string inside the csymbol could have been almost anything, because it is essentially ignored by MathML parsers and SBML. It can even be empty. Some MathML and SBML processors will take note of the token and use it when presenting the mathematical formula to users, but the token used has no impact on the interpretation of 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 only and can be ignored by the parser.
As a further example, the following XML fragment encodes the equation $k + delay(x, 0.1)$ or, alternatively, $k_t + x_{t-0.1}$:

```xml
<math xmlns="http://www.w3.org/1998/Math/MathML"
      xmlns:sbml="http://www.sbml.org/sbml/level3/version2/core">
  <apply>
    <plus/>
    <ci> k </ci>
    <apply>
      <csymbol encoding="text" definitionURL="http://www.sbml.org/sbml/symbols/delay" />
      <ci> x </ci>
      <cn sbml:units="second"> 0.1 </cn>
    </apply>
  </apply>
</math>
```

The use of Avogadro's number is illustrated in the following XML fragment, which encodes the formula $\text{avogadro} * x$:

```xml
<math xmlns="http://www.w3.org/1998/Math/MathML">
  <apply>
    <times/>
    <csymbol encoding="text" definitionURL="http://www.sbml.org/sbml/symbols/avogadro" />
    <ci> x </ci>
  </apply>
</math>
```

Finally, the use of a *rateOf* function call is illustrated in the following XML fragment, and encodes the formula $k + \text{rateOf}(S1)$:

```xml
<math xmlns="http://www.w3.org/1998/Math/MathML">
  <apply>
    <plus/>
    <ci> k </ci>
    <apply>
      <csymbol encoding="text" definitionURL="http://www.sbml.org/sbml/symbols/rateOf" />
      <ci> S1 </ci>
    </apply>
  </apply>
</math>
```

### 3.4.7 Simulation time

The principal use of SBML is to represent quantitative dynamical models whose behaviors manifest over time. In defining an SBML model using constructs such as reactions, time is most often implicit and does not need to be referred to in the mathematical expressions themselves. However, sometimes an explicit time dependency needs to be stated, and for this purpose, the *time csymbol* (described above in Section 3.4.6) may be used. This *time* symbol refers to “instantaneous current time” in a simulation, frequently given the literal name *t* in one’s equations.

An assumption in SBML is that “start time” or “initial time” in a simulation is zero, that is, if $t_0$ is the initial time in the system, $t_0 = 0$. This corresponds to the most common scenario. Initial conditions in SBML take effect at time $t = 0$. There is no mechanism in SBML for setting the initial time to a value other than 0. To refer to a different time in a model, one approach is to define a **Parameter** for a new time variable and use an **AssignmentRule** in which the assignment expression subtracts a value from the *csymbol time*. For example, if the desired offset is 2 seconds, the MathML expression would be

```xml
<math xmlns="http://www.w3.org/1998/Math/MathML"
      xmlns:sbml="http://www.sbml.org/sbml/level3/version2/core">
  <apply>
    <minus/>
    <csymbol encoding="text" definitionURL="http://www.sbml.org/sbml/symbols/time" />
    <cn sbml:units="second"> 2 </cn>
  </apply>
</math>
```
SBML's assignment rules (Section 4.9.3) can be used to express mathematical statements that hold true at all moments, so using an assignment rule with the expression above will result in the value being equal to $t - 2$ at every point in time. A parameter assigned this value could then be used elsewhere in the model.

### 3.4.8 Initial conditions and special considerations

The identifiers of **Species**, **SpeciesReference**, **Compartment**, **Parameter**, and **Reaction** object instances in a given SBML model refer to the main symbols in a model. Depending on certain attributes of these objects (e.g., the attribute **constant** on species, species references, compartments and parameters—this and other conditions are explained in the relevant sections elsewhere in this document), some of the symbols may have constant values throughout a simulation, and others' values may change. These changes in values over time are determined by the system of equations constructed from the model's reactions, initial assignments, rules, and events.

As described in Section 3.4.7, an SBML model's simulation is assumed to begin at $t = 0$. The availability of the *delay csymbol* (Section 3.4.6 on p. 25) introduces the possibility that at $t \ge 0$, mathematical expressions in a model may draw on values of model components from time *prior* to $t = 0$. A simulator may therefore need to compute the values of symbols at time points $t_i \le 0$ to allow the calculation of values required for the evaluation of delay expressions in the model for $t \ge 0$. If there are no delays in the model, then $t_i = 0$.

The following is how the definitions of the model should be applied:

1. At time $t_i$:

* Every **Species**, **SpeciesReference**, **Compartment**, **Parameter**, and package element with mathematical meaning whose definition includes an initial value is assigned that value. If an element has **constant**=“false”, its value may be changed by other constructs or reactions in a model according to the steps below; if **constant**=“true”, only an **InitialAssignment** can override the value.

* All **InitialAssignment** definitions take effect, overriding any initial values on any **Species**, **Species-Reference**, **Compartment**, **Parameter**, or package element with mathematical meaning.

* All **AssignmentRule** and **AlgebraicRule** definitions take effect. These rules also override any initial values of any **Species**, **SpeciesReference**, **Compartment**, **Parameter**, or package element with mathematical meaning. Only elements set **constant**=“false” can be affected in this way. (Note there cannot be both an **AssignmentRule** and an **InitialAssignment** for the same identifier, nor may an **AlgebraicRule** determine the value of any element that has an **InitialAssignment**; see Section 4.9.)

* The identifier of any **Reaction** has the value of its **KineticLaw**. This cannot yet affect the **Species** referenced by the **Reaction**, but the identifier may appear in other **Math** elements calculated above.

* The value of any **Event Trigger** is the value of that **Trigger's** *initialValue* attribute. This cannot be overridden.

2. For time $t_i < t < 0$

* Any element with mathematical meaning with no **InitialAssignment** or **Rule** that targets it continues to have its initial value, as defined by the relevant attribute.

* Any **InitialAssignment** definition continues to take effect. Since these contain mathematical formulas, different values may be computed at each time step $t$ in $t_i \le t \le 0$.

* Any **AssignmentRule** or **AlgebraicRule** definition continues to take effect, and may not be overridden. Again, different values may be computed at each time step $t$ in $t_i \le t \le 0$.

* The identifier of any **Reaction** continues to be the value of its **KineticLaw**. Again, different values may be computed at each time step $t$ in $t_i \le t \le 0$.

* The value of any **Event Trigger** continues to be the value of that **Trigger's** *initialValue* attribute.

3. At time $t = 0$:

* The value of any **Event Trigger** is now calculated according to the **Trigger's Math** child, and may therefore cause the **Event** to *trigger* and its **EventAssignment** children to *execute*. This can happen
directly due to its value changing from an **initialValue** of “**false**” to a now-calculated value of “**true**”; it can happen indirectly due to an event cascade initiated by a direct change in a different **Event**. (Note that an **Event** cannot be defined to change the value of a symbol that is also the subject of an **AssignmentRule**, nor can it change the value of a symbol whose value is determined by an **AlgebraicRule**; see Section 4.12 on p. 79.)

* The identifier of any **Reaction** continues to be the value of its **KineticLaw**.

* Any element with mathematical meaning with no **InitialAssignment** or **Rule** that targets it continues to have its initial value, as defined by the relevant attribute, but may now be overridden by any **EventAssignment**, executed as above.

* Any **InitialAssignment** definition continues to take effect, but may now be overridden by any **EventAssignment**, executed as above.

* Any **AssignmentRule** or **AlgebraicRule** definition continues to take effect, and may not be overridden.

* **Constraint** definitions begin to take effect (and a constraint violation may result; see Section 4.10).

4. For time $t > 0$:

* The value of any element with mathematical meaning may now be overridden (subject to normal restrictions) by any construct in SBML (though it may retain its original value if no such constructs apply).

* The value of any element with an **InitialAssignment** may also now be overridden by any construct in SBML (though it may retain the value set by the **InitialAssignment** if no such constructs apply).

* Any **AssignmentRule** or **AlgebraicRule** definition continues to take effect, and still may not be overridden by any other SBML construct.

* **RateRule** definitions can begin to take effect.

* Any **Reaction** can begin to affect its referenced **Species**. Its identifier continues to have the value of its **KineticLaw**.

* Each **Event** may fire, and their **EventAssignment** children execute.

* System simulation proceeds.

To reiterate: in modeling situations that do not involve the use of the *delay csymbol*, then $t_i$ becomes $t_i = 0$, but this does not alter the steps numbers 1–4 above.

### 3.4.9 Underdetermined models

A valid SBML model must not be *overdetermined*: the value of any symbol must not be established by more than one construct in the model. The rules governing SBML constructs such as **InitialAssignment** and **Rule** are designed to prevent the creation of overdetermined models because such models are self-contradictory.

The opposite situation, in which a model is *underdetermined*, is not invalid. An SBML model may contain one or more symbols whose values are not established by the model directly, as when a **Parameter** has no **initialValue** attribute and is not the target of an **InitialAssignment** or a relevant **Rule** object; a model may also have multiple solutions, such as when an **AlgebraicRule** object determines either one—but not both—of two different symbols in the model, or when an **AlgebraicRule** object has multiple solutions (such as $0 = x^2 - 4$). Such models cannot be simulated without additional information, but although they are *incomplete* models, they are not *contradictory*, and therefore not invalid.

Underdetermined models may arise for various reasons. For example, a model may be created to reflect the current state of knowledge about a biological system, and that knowledge may itself be incomplete. In other cases, a model may be a work in progress, or a part of an automated model-creation pipeline. In still other situations, a model may be intended for non-numerical simulation such as structural analysis, where having numerical values for all symbols, or mathematical formulas establishing the rates of reactions, may not be required. Finally, it is also possible that the (apparently) missing information (from the perspective of an SBML Level 3 Core model) is actually provided by an SBML Level 3 package. Package information
may provide the missing information needed to resolve the system, or provide a new context for the model indicating the type(s) of analyses for which the model was designed. In all these scenarios, practical exigencies demand that these SBML Level 3 Core models be considered valid even if they are incomplete (as long as the parts that *are* present are not overdetermined or invalid for other reasons!).

SBML Level 3 Version 2 Core does not stipulate a particular course of action for handling underdetermined models; software systems may handle them as they see fit. For example, numerical simulation systems could reasonably refuse to process such models (and inform the user why); other types of software may find it more appropriate to take other actions, such as asking the user to fill in the missing information.

### 3.4.10 Use and interpretation of the 'constant' attribute

All SBML elements with mathematical meaning whose value can be assigned via a *Rule* have a *constant* attribute that can be “true” or “false”. One purpose of this attribute is to help model validation: if an element that is meant to be constant appears as the target of (e.g.) a *RateRule* or an *AssignmentRule*, the *Model* has an internal inconsistency that must be corrected before it can be interpreted properly.

Another use of the *constant* attribute is to provide information crucial to constructing systems of equations for models that include *AlgebraicRule*. To produce a unique solution, the number of symbols appearing in *AlgebraicRule math* expressions must not exceed the number of *AlgebraicRule* objects. When more symbols appear in a model’s set of *AlgebraicRule math* expressions than there are *AlgebraicRule* objects to establish their values, the model is underdetermined, and there will not be a single solution to the overall system of equations derived from the model. However, flagging one or more of the symbols as constant sets those symbols’ values; when done correctly, it can lead to an equal number of *AlgebraicRule* objects as there are variables that may be determined by those rules. Consequently, the system can have a unique solution again. (See Section 4.9.2 on p. 61 for more details about *AlgebraicRule* and additional requirements.)

The *constant* attribute is also often used by software tools to determine how an element should be displayed to the user. For example, an element marked `constant="true"` might be listed in a table along with its (known, fixed) value, while an element marked `constant="false"` might be instead be displayed in a graph with its value plotted over the time course of a simulation. Moreover, it may be possible for software to implement more efficient internal handling of constant symbols.

### 3.4.11 MathML expression data types

MathML operators in SBML return results in one of two possible types: Boolean and numerical. By numerical type, we mean either (1) a number in MathML real, integer, rational, or "e-notation" format; or (2) the `csymbol` for *time*, the `csymbol` for the *delay* function, or the `csymbol` for the *rateOf* function described in Section 3.4.6 on p. 25. However, a Boolean value may be used in a numerical context, and visa versa, as described in Section 3.4.4 on p. 24. It is still important to understand which contexts are considered Boolean and which are considered numeric, so the following guidelines summarize the different possible cases.

The relational operators (`eq`, `neq`, `gt`, `lt`, `geq`, `leq`), the logical operators (`and`, `or`, `xor`, `not`, `implies`), and the Boolean constants (`false`, `true`) always return Boolean values, or `0` and `1` in numerical contexts.

The type of an operator referring to a *FunctionDefinition* is determined by the type of the top-level operator of the expression in the *math* element of the *FunctionDefinition* instance, and can be Boolean or numerical.

All other operators, values and symbols return numerical results.

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

* the arguments of the MathML logical operators (`and`, `or`, `xor`, `not`, `implies`);

* the second argument of a MathML *piece* operator;

* the *trigger* element of an SBML *Event*; and

* the *math* element of an SBML *Constraint*.

The roots of the expression trees used in the following contexts can yield Boolean or numerical values:

* the arguments to the `eq` and `neq` operators;
* the first arguments of MathML `piece` and `otherwise` operators; and

* the top-level expression of a function definition.

The roots of expression trees in other contexts will be interpreted as numerical values.

The type of expressions should be used consistently. The set of expressions that make up the first arguments of the `piece` and `otherwise` operators within the same `piecewise` operator should all return values of the same type. The arguments of the `eq` and `neq` operators should return the same type.

### 3.4.12 Consistency of units in mathematical expressions and treatment of unspecified units

Strictly speaking, physical validity of mathematical formulas requires not only that physical quantities added to or equated with each other have the same fundamental dimensions and units of measurement; it also requires that the application of operators and functions to quantities produces sensible results. Yet, in real-life models today, these conditions are often and sometimes legitimately disobeyed.

In a public vote held in late 2007, the SBML community decided to revoke the requirement (present up through Level 2 Version 3) for strict unit consistency in SBML. As a result, SBML Level 3 follows this decision; the units on quantities and the results of mathematical formulas in a model *should* be consistent, but it is not a strict error of SBML model representation if they are not. The following are thus formulated as recommendations that *should* be followed except in special circumstances.

#### Recommendations for unit consistency of mathematical expressions

The consistency of units is defined in terms of dimensional analysis applied recursively to every operator and function and every argument to them. The following conditions should hold true in a model (and software developers may wish to consider having their software warn users if one or more of the following conditions is not true):

1. All arguments to the following operators should have the same units (regardless of what those units happen to be): `plus`, `minus`, `eq`, `neq gt`, `lt`, `geq`, `leq`, `max`, `min`. If one or more arguments are Boolean and one or more numeric, all the numeric arguments should have units of `dimensionless`.

2. The units associated with each argument in a call to a `FunctionDefinition` should match the units expected by the `lambda` expression within the `math` expression of that `FunctionDefinition` instance.

3. All of the possible return values from `piece` and `otherwise` subelements of a `piecewise` expression should have the same units, regardless of what they are. (Without this guideline, the `piecewise` expression would return values having different units depending on which case evaluated to true.) If one or more return values are Boolean and one or more numeric, all the numeric arguments should have units of `dimensionless`.

4. For the `delay` `csymbol` (Section 3.4.6 on p. 25) function, which has the form `delay(x, d)`, the second argument `d` should match the model's unit of `time` (as determined by the `Model` object's `timeUnits` attribute).

5. The units of the value returned by the `delay` `csymbol` (Section 3.4.6 on p. 25) function should match the units associated with the first argument `x`.

6. The units of the value returned by the `rateOf` `csymbol` (Section 3.4.6 on p. 25) function should be units appropriate for a rate of change. The units of `rateOf(x)` should be equal to `{unit of x}/{unit of time}`, where the unit of `time` is determined by the value of the attribute `timeUnits` on the enclosing `Model` object. The kinds of identifiers permitted for use as `x` are explained in Section 3.4.6 on p. 25.

7. The units of each argument to the following operators should be `dimensionless` or be Boolean: `exp`, `ln`, `log`, `factorial`, `sin`, `cos`, `tan`, `sec`, `csc`, `cot`, `sinh`, `cosh`, `tanh`, `sech`, `csch`, `coth`, `arcsin`, `arccos`, `arctan`, `arcsec`, `arccsc`, `arccot`, `arcsinh`, `arccosh`, `arctanh`, `arcsech`, `arccsch`, `arccoth`.

8. Numerical values used in Boolean contexts should have units of `dimensionless`. That is, all the arguments to the MathML logical operators `and`, `or`, `xor`, `not`, and `implies`; the second argument of a
MathML **piece** operator; the **trigger** element of an SBML **Event**; and the **math** element of an SBML **Constraint**, should either be Boolean or have units of **dimensionless**.

9. The two arguments to **power**, which are of the form power(a, b) with the meaning $a^b$, should be as follows: (1) if the second argument is an integer, then the first argument can have any unit; (2) if the second argument b is a rational number $n/m$, it should be possible to derive the m-th root of $(a{\{unit\}})^n$, where ${\{unit\}}$ signifies the unit associated with a; otherwise, (3) the unit of the first argument should be "dimensionless". The second argument (b) should always have the unit of "dimensionless".

10. The two arguments to **root**, which are of the form root(n, a) with the meaning $\sqrt[n]{a}$ and where the degree n is optional (defaulting to "2"), should be as follows: (1) if the optional degree qualifier n is an integer, then it should be possible to derive the n-th root of a; (2) if the optional degree qualifier n is a rational $n/m$ then it should be possible to derive the n-th root of $(a{\{unit\}})^m$, where ${\{unit\}}$ signifies the unit associated with a; otherwise, (3) the unit of a should be "dimensionless".

11. Where the units of literal numbers have not been specified directly in SBML, it is possible for the unit of a **FunctionDefinition** object's return value to be effectively different in different contexts where it is called (see below). If a **FunctionDefinition**'s mathematical formula contains literal constants (i.e., numbers within MathML cn elements with no sbml:units attribute), the units of the constants should be identical in all contexts the function is called.

The units of other operators such as **abs**, **floor**, and **ceiling**, can be anything.

Item number 9 above, regarding **FunctionDefinition**, merits additional elaboration. An example may help illustrate the problem. Suppose the formula $x + 5$ is defined as a function, where $x$ is an argument and the literal number 5 has no specified unit. If this function is called with an argument whose unit of measurement 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 have a unit of **second**. Now suppose that a modeler decides to change all uses of seconds to milliseconds in the model. To make the function definition return the same quantity in terms of seconds, the 5 in the formula would need to be changed, but doing so would change the result of the function everywhere it is called—with the wrong consequences in the context where moles were intended. This illustrates the subtle danger of using numbers with unspecified units in function definitions. There are at least two approaches for avoiding this: (1) define separate functions for each case where the units of the constants are supposed to be different, optionally explicitly defining the units of literal numbers; or (2) declare the necessary constants as **Parameter** objects in the model (with declared units!) and pass those parameters as arguments to the function, avoiding the use of literal numbers in the function's formula.

## Treatment of unspecified units

If an expression contains literal numbers and/or SBML components without declared units, the consistency or inconsistency of units may be impossible to determine. In the absence of a verifiable *inconsistency*, an expression in SBML is accepted as-is; the writer of the model is assumed to have written what they intended. However, this is *not* equivalent to assuming the expression *does* have consistent units. The lack of declared units on quantities in an SBML model does not render the model invalid insofar as the SBML specification is concerned, but it reduces the types of consistency checks and useful operations (such as conversions and translations) that software systems can perform.

In some cases, it may be possible to determine that expressions containing unspecified units are inconsistent regardless of what units would be attributed to the unspecified quantities. For example, the expression

$$ \frac{dX}{dt} = \frac{[Y] \cdot [Z]^n}{[Z]^m + 1} \cdot V $$

with X, Y and Z in units of substance, V in units of volume, and $m \neq n$, cannot ever be consistent, no matter what units the literal 1 takes on. (This also illustrates the need not to stop verifying the units of an expression immediately upon encountering an unspecified quantity—the rest of the expression may still be profitably evaluated and checked for inconsistency.)
### 3.4.13 SBML does not define implicit unit conversions

Implicit unit conversions do not exist in SBML. Consider the following example. Suppose that in some model, a species $S_1$ has been declared as having a mass of 1 kg, and a second species $S_2$ has been declared as having a mass of 500 g. What should be the result of evaluating an expression such as $S_1 > S_2$? If the numbers alone are considered,

$$1 > 500$$

would evaluate to “false”, but if the units were implicitly converted by the software tool interpreting the model,

$$1 \text{ kg} > 500 \text{ g}$$

would evaluate to “true”. This is a trivial example, but the problem for SBML is that implicit unit conversions of this kind can lead to controversial situations where even humans do not agree on the answer. Consequently, SBML only requires that mathematical expressions be evaluated numerically. It is up to the model writer to ensure that the units on both sides of an expression match, by inserting explicit unit conversion factors if necessary.
# 4 SBML components

In this section, we define each of the major components of SBML. We use the UML notation described in Section 1.4.3 for defining classes of objects. We also illustrate the use of SBML components by giving partial model definitions in XML. Section 7 provides many complete example models encoded in SBML.

Unless otherwise specified, SBML Level 3 documents must follow the XML specification: anything allowed in XML is allowed in SBML documents, and anything disallowed in XML is not allowed in SBML. All well-formed SBML documents must begin with an XML declaration, specifying both the version of XML used and the document character encoding. The declaration begins with the characters `<?xml` followed by the attributes `version` and `encoding`. SBML requires XML version 1.0, and UTF-8 as the document encoding.

## 4.1 The SBML container

Following the XML declaration, the outermost portion of a model expressed in Level 3 consists of an object of class **SBML**, defined in Figure 9. This class contains three required attributes (`level`, `version` and `xmlns`), and an optional **model** element.

<figure><img src="image_12.png" /><figcaption>**Figure 9:** The definition of class SBML for SBML Level 3 Version 2 Core. The class Model is defined in Section 4.2 on p. 36. Note that SBML and Model are subclasses of SBase, and therefore inherit the attributes of that abstract class.</figcaption></figure>

The **SBML** class defines the structure and content of the **sbml** outermost element in an SBML file. The following is an abbreviated example of an **SBML** class object translated into XML form for an SBML Level 3 Version 2 Core document. Here, ellipses (`...`) are used to indicate content elided from this example:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<sbml xmlns="http://www.sbml.org/sbml/level3/version2/core" level="3" version="2">
  ...
  <model ...> ...
  </model>
</sbml>
```

The attribute `xmlns` declares the XML namespace used within the **sbml** element. The URI for SBML Level 3 Version 2 Core is `http://www.sbml.org/sbml/level3/version2/core`. All SBML Level 3 Version 2 Core elements and attributes must be placed in this namespace either by assigning the default namespace as shown in the example above, or using a tag prefix on every element. The **sbml** element may contain additional attributes, in particular, attributes to support the inclusion of SBML Level 3 packages; see Section 4.1.3 on the following page. For purposes of checking conformance to the SBML Level 3 Core specification, only the elements and attributes in the SBML Level 3 Core XML namespace are considered.

### 4.1.1 The id and name attributes

Because **SBML** inherits from **SBase**, it has optional `id`, `name`, `sboTerm` and `metaid` attributes. SBML Level 3 Version 2 Core does not define a purpose for these attributes; moreover, being outside of the **Model** namespace, the `id` attribute is not subject to the uniqueness constraints of **SId** values inside **Model** objects.

### 4.1.2 The model element

The actual model contained within an SBML document is defined by an instance of the **Model** class element. The structure of this object and its use are described in Section 4.2 on p. 36. An SBML document may contain at most one model definition.
### 4.1.3 Package declarations

SBML Level 3 is modular, in the sense of having a defined core set of features and optional packages adding features on top of the core. This modular approach means that models can declare which feature-sets they use, and likewise, software tools can declare which packages they support. The mechanism for models to declare which packages they use involves two parts: a standard XML namespace declaration, and an attribute that every package must declare in this namespace.

1. Every SBML Level 3 package is identified uniquely by an XML namespace URI. The use of a given SBML Level 3 package must be declared by a model using the standard XML namespace declaration approach. The declaration is made using the character sequence `xmlns:` (without the quotes), followed by additional characters providing a prefix by which elements and attributes in that namespace are known in the rest of the SBML document, and finally followed by the namespace URI as a value. The following is an example of namespace declarations for a package nicknamed `comp` and another package nicknamed `layout` (and here, ellipses are used to indicate content elided from this example):

```xml
<sbml xmlns="http://www.sbml.org/sbml/level3/version2/core" level="3" version="2"
      xmlns:comp="http://www.sbml.org/sbml/level3/version2/comp/version2"
      xmlns:layout="http://www.sbml.org/sbml/level3/version2/layout/version2" ...>
    ...
</sbml>
```

There are no restrictions on the prefixes used for XML namespaces referring to SBML Level 3 packages beyond those imposed by the relevant specifications of XML 1.0 and XML namespaces. (In other words, the prefix strings `comp` and `layout` in the example above are arbitrarily chosen, and could have been something else.)

2. SBML Level 3 requires that every package defines the addition of at least one attribute named **required**. The attribute, being in the namespace of the Level 3 package in question, must be referenced by the XML namespace prefix described in point number 1 above. The value of the **required** attribute indicates whether constructs in that package may change the mathematical interpretation of constructs defined in SBML Level 3 Core. A **required** value of `true` indicates that the package may do so. The value is set by the relevant Level 3 package specification, and does *not* depend on the presence or absence of particular package constructs in a given SBML document: in other words, it is a property of the package. For example, if a package defines new object classes with mathematical meanings and with identifiers that may be used in core **Math** elements, that package's **required** attribute must always be set to `true` for all SBML documents declaring the use of that package's namespace. The following is a complete example:

```xml
<sbml xmlns="http://www.sbml.org/sbml/level3/version2/core" level="3" version="2"
      xmlns:comp="http://www.sbml.org/sbml/level3/version2/comp/version2"
      xmlns:layout="http://www.sbml.org/sbml/level3/version2/layout/version2"
      comp:required="true" layout:required="false">
    <model /> <!-- sbml model is complete -->
</sbml>
```

In this example, because the Hierarchical Model Composition ("comp") package can change the mathematical interpretation of a model, the `comp:required` attribute must always be set to `true`, even if a model is completely empty. The Graphical Layout ("layout") package, by contrast, cannot ever change the mathematical interpretation of any model; thus, its `required` attribute must be set to `false`.

If a package is declared optional (i.e., its `required` flag is set to `false`), it means the time-course dynamics of the model can be correctly inferred even if the elements and attributes added by that particular SBML package are ignored. "Ignoring" a package can be accomplished in multiple ways: a reader could either skip those elements or attributes altogether during parsing, or read them but not interpret them, or do something similar. The following are some ways in which packages with `required="true"` may change the time-course dynamics of a model:

* An element with a (potential) mathematical meaning may be left undefined in the core specification of SBML Level 3, but may have a value defined by a package.
* An element with mathematical meaning may have a value defined by a package such that the value overrides the value given in the core SBML specification.

* The definition of how an element changes over time may be altered or augmented by a package.

* An element may be defined within a package to have mathematical meaning, and its `SId` may be used to determine one or more mathematical functions in core SBML. (However, no package may ever give mathematical meaning to the `SId` of an element that was defined as not having mathematical meaning: no `SId` of this type may ever appear in any mathematical context.)

The XML namespace declaration for an SBML Level 3 package is an indication that a model makes use of features defined by that package, while the `required` attribute indicates whether the features may be ignored without compromising the mathematical meaning of the model. Both are necessary for a complete reference to an SBML Level 3 package. (On the other hand, no declaration is necessary for the Level 3 Core package, since it is the base package and support for it is required in any case.)

## 4.2 Model

The definition of `Model` is shown in Figure 10 on the following page. Only one instance of a `Model` object is allowed per instance of an SBML Level 3 Version 2 Core document or data stream, and it must be located inside the `<sbml> ... </sbml>` element as described in Section 4.1 on p. 34.

`Model` serves as a container for components of classes `FunctionDefinition`, `UnitDefinition`, `Compartment`, `Species`, `Parameter`, `InitialAssignment`, `Rule`, `Constraint`, `Reaction` and `Event`. Instances of the classes are placed inside instances of classes `>ListOfFunctionDefinitions`, `ListOfUnitDefinitions`, `ListOfCompartments`, `ListOfSpecies`, `ListOfParameters`, `ListOfInitialAssignments`, `ListOfRules`, `ListOfConstraints`, `ListOfReactions`, and `ListOfEvents`. The "list" classes are defined in Figure 10 on the following page. All of the lists are optional, and, if present, may be empty; this is semantically equivalent to omitting the list. The resulting XML data object for a full model containing every possible list would have the following form:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<sbml xmlns="http://www.sbml.org/sbml/level3/version2/core" level="3" version="2">
  <model id="My_Model">
    <listOfFunctionDefinitions>
      <zero or more <functionDefinition> ... </functionDefinition> elements } optional
    </listOfFunctionDefinitions>
    <listOfUnitDefinitions>
      <zero or more <unitDefinition> ... </unitDefinition> elements } optional
    </listOfUnitDefinitions>
    <listOfCompartments>
      <zero or more <compartment> ... </compartment> elements } optional
    </listOfCompartments>
    <listOfSpecies>
      <zero or more <species> ... </species> elements } optional
    </listOfSpecies>
    <listOfParameters>
      <zero or more <parameter> ... </parameter> elements } optional
    </listOfParameters>
    <listOfInitialAssignments>
      <zero or more <initialAssignment> ... </initialAssignment> elements } optional
    </listOfInitialAssignments>
    <listOfRules>
      <zero or more elements of subclasses of Rule } optional
    </listOfRules>
    <listOfConstraints>
      <zero or more <constraint> ... </constraint> elements } optional
    </listOfConstraints>
    <listOfReactions>
      <zero or more <reaction> ... </reaction> elements } optional
    </listOfReactions>
    <listOfEvents>
      <zero or more <event> ... </event> elements } optional
    </listOfEvents>
  </model>
</sbml>
```
<figure><img src="image_13.png" /><figcaption>Figure 10: The definition of Model and the many helper classes ListOfFunctionDefinitions, ListOfUnitDefinitions, ListOfCompartments, ListOfSpecies, ListOfParameters, ListOfInitialAssignments, ListOfRules, ListOfConstraints, ListOfReactions, and ListOfEvents.</figcaption></figure>
Although the lists are optional, there are dependencies between SBML components such that defining some components requires defining others. For example, defining a species requires defining a compartment, and defining a species reference in a reaction requires defining a species. Such dependencies are explained throughout this document.

### 4.2.1 The sboTerm attribute

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

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

### 4.2.2 The substanceUnits attribute

The **substanceUnits** attribute is used to specify the unit of measurement associated with substance quantities of **Species** objects that do not specify units explicitly. The attribute's value must be of type **UnitSIdRef** (Section 3.1.10 on p. 13). A list of recommended units is given in Section 8.2.1 on p. 148.

If a given **Species** object definition does not specify its unit of substance quantity via the **substanceUnits** attribute on **Species** (described in Section 4.6 on p. 49), then the species inherits the value of the **Model substanceUnits** attribute. If the **Model** does not define a value for this attribute, then there is no unit to inherit, and all species that do not specify individual **substanceUnits** attribute values then have no declared units for their quantities. Section 4.6.4 provides more information about the units of species quantities.

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

### 4.2.3 The timeUnits attribute

The **timeUnits** attribute is used to specify the unit in which time is measured in the model. The value of this attribute must be of type **UnitSIdRef** (Section 3.1.10 on p. 13). A list of recommended units is given in Section 8.2.1 on p. 148.

This attribute on **Model** is the *only* way to specify a unit for time in a model. It is a global attribute; time is measured in the model everywhere in the same way. This is particularly relevant to **Reaction** and **RateRule** objects in a model: all **Reaction** and **RateRule** objects in SBML define per-time values, and the unit of time is given by the **timeUnits** attribute on the **Model** object instance. If the **Model timeUnits** attribute has no value, it means that the unit of time is not defined for the model's reactions and rate rules. Leaving it unspecified in an SBML model does not result in an invalid model; however, as a matter of best practice, we strongly recommend that all models specify units of measurement for time.

### 4.2.4 The volumeUnits, areaUnits and lengthUnits attributes

The attributes **volumeUnits**, **areaUnits** and **lengthUnits** together are used to set the units of measurements for the sizes of **Compartment** objects in the model when those objects do not otherwise specify units. The three attributes correspond to the most common cases of compartment dimensions: **volumeUnits** for compartments having attribute value **spatialDimensions**="3", **areaUnits** for compartments having **spatialDimensions**="2", and **lengthUnits** for compartments having **spatialDimensions**="1". The values of these attributes must be of type **UnitSIdRef** (Section 3.1.10 on p. 13). A list of recommended units is given in Section 8.2.1 on p. 148. The attributes are not applicable to compartments whose **spatialDimensions** attribute values are not one of "1", "2" or "3".

If a given **Compartment** object instance does not provide a value for its **units** attribute, then the unit of measurement of that compartment's size is inherited from the value specified by the **Model volumeUnits**,
**areaUnits** or **lengthUnits** attribute, as appropriate based on the **Compartment** object's **spatialDimensions** attribute value. If the **Model** object does not define the relevant attribute, then there are no units to inherit, and all compartments that do not set a value for their **units** attribute then have **no** units associated with their compartment sizes. Section 4.5.4 provides more information about units of compartment sizes.

The use of three separate attributes is a carry-over from SBML Level 2. Note that it is entirely possible for a model to define a value for two or more of the attributes **volumeUnits**, **areaUnits** and **lengthUnits** simultaneously, because SBML models may contain compartments with different numbers of dimensions.

### 4.2.5 The extentUnits attribute

Reactions are processes that occur over time. These processes involve events of some sort, where a single "reaction event" is one in which some set of entities (known as reactants, products and modifiers in SBML) interact, once. The **extent** of a reaction is a measure of how many times the reaction has occurred, while the time derivative of the extent gives the instantaneous rate at which the reaction is occurring. Thus, what is colloquially referred to as the "rate of the reaction" is in fact equal to the rate of change of reaction extent.

The combination of **extentUnits** and **timeUnits** defines the units of kinetic laws in SBML and establishes how the numerical value of each **KineticLaw**'s mathematical formula (Section 4.11.5 on p. 74) is meant to be interpreted in a model. The units of the kinetic laws are taken to be **extentUnits** divided by **timeUnits**. A list of recommended units is given in Section 8.2.1 on p. 148.

Note that this embodies an important principle in SBML models: *all reactions in an SBML model must have the same units* for the rate of change of extent. In other words, the units of all reaction rates in the model *must be the same*. There is only one global value for **extentUnits** and one global value for **timeUnits**.

### 4.2.6 The conversionFactor attribute

The attribute **conversionFactor** defines a global value inherited by all **Species** object instances that do not define separate values for their **conversionFactor** attributes. The value of this attribute must be of type **SIdRef** (Section 3.1.8 on p. 13) and refer to a **Parameter** object instance defined in the model. The **Parameter** object in question must be a constant; i.e., it must have its **constant** attribute value set to **"true"**.

If a given **Species** object definition does not specify a conversion factor via the **conversionFactor** attribute on **Species** (described in Section 4.6 on p. 49), then the species inherits the conversion factor specified by the **Model** **conversionFactor** attribute. If the **Model** does not define a value for this attribute, then there is no conversion factor to inherit. Section 4.11.7 on p. 77 describes how to interpret the effects of reactions on species in that situation. More information about conversion factors in SBML is provided in Section 4.6 on p. 49 and Section 4.11 on p. 68.

### 4.2.7 The ListOf container classes

The various **ListOf** classes defined in Figure 10 on p. 37 are merely containers used for organizing the main components of an SBML document. **ListOfFunctionDefinitions**, **ListOfUnitDefinitions**, **ListOfCompartments**, **ListOfSpecies**, **ListOfParameters**, **ListOfInitialAssignments**, **ListOfRules**, **ListOfConstraints**, **ListOfReactions**, and **ListOfEvents** are all derived from the abstract class **SBase** (Section 3.2 on p. 14), and inherit **SBase**'s various attributes and subelements. The **ListOf** classes do not add any attributes of their own.

There are several motivations for grouping SBML components within XML elements with names of the form **listOfClassNames** rather than placing all the components directly at the top level. First, the fact that the container classes are derived from **SBase** means that software tools can add information about the lists themselves into each list container's **Annotation**, a feature that a number of today's software tools exploit. Second, we believe the grouping leads to a more modular structure that is helpful when working with elements from multiple SBML Level 3 packages. Third, we believe that it makes visual reading of models in XML easier, for situations when humans must inspect and edit SBML directly.

Lists are allowed to be empty for two reasons. First, this allows model writers to add **Annotation** and **Notes** objects to a given list even when the list is empty in a model; this can be useful, for instance, to let a modeler explain *why* the components are absent from the model. Second, it enables SBML Level 3 package
specifications to define new elements to be children of these lists, and for these child elements to be used without the requirement that at least one SBML Level 3 Core element always be present.

## 4.3 Function definitions

The **FunctionDefinition** object associates an identifier with a function definition. This identifier can then be used as the function called in subsequent MathML **apply** elements. **FunctionDefinition** is shown in Figure 11.

<figure><img src="image_14.png" /><figcaption>Figure 11: The definition of class **FunctionDefinition**. A Lambda class object must contain a single MathML lambda expression (or a lambda surrounded by a semantics element). A function definition may contain no more than one math element defined by the Lambda class. Note also that Lambda is not derived from SBase, which means that the attributes defined on SBase are not available on the math element. A sequence of zero or more instances of FunctionDefinition objects can be located in an instance of ListOfFunctionDefinitions in Model, as shown in Figure 10 on p. 37.</figcaption></figure>

Function definitions in SBML (also informally known as “user-defined functions”) have purposefully limited capabilities. As is made clearer below, a function cannot reference parameters or other model quantities outside of itself; values must be passed as parameters to the function. Moreover, recursive and mutually-recursive functions are not permitted. The purpose of these limitations is to balance power against complexity of implementation. With the restrictions as they are, function definitions could, if desired, be implemented as textual substitutions. Software implementations therefore do not need the full function-definition machinery typically associated with programming languages.

### 4.3.1 The id attribute

**FunctionDefinition** inherits the **id** attribute from **SBase**, but defines **id** as being *required* rather than optional. The **id** attribute otherwise obeys the behavior described in Section 3.3 on p. 18.

A function's identifier can be used in **math** elements as the first target of an **apply** element, but the identifier has no value associated with it, and may not be the target of an **InitialAssignment**, **EventAssignment**, or **Rule** object in the model. MathML **ci** elements in an SBML model can refer to the function defined by a **FunctionDefinition** using the value of its **id** attribute.

### 4.3.2 The math element

The optional **math** element is a container for MathML content that defines the function. The content of this element can only be a MathML **lambda** element or a MathML **semantics** element containing a **lambda** element. **FunctionDefinition** is the only place in SBML Level 3 Core where a **lambda** element can be used. If present, the **lambda** element must begin with zero or more **bvar** elements, followed by any other of the elements in the MathML subset listed in Section 3.4.1 on p. 20 except **lambda** (i.e., a **lambda** element cannot contain another **lambda** element).

A further restriction on the content of **math** is it cannot contain references to identifiers other than the symbols declared in the **lambda** itself. That is, the contents of MathML **ci** elements inside the body of the **lambda** can only be one of three kinds of identifiers: (i) the symbols declared by its **bvar** elements, or (ii) the identifiers of other **FunctionDefinition** objects defined in the same model. This restriction also applies to the **csymbol** elements for *time*, *avogadro*, *delay*, and *rateOf*. Functions must be written so that all model symbols they use are passed to them via their parameters.

If the **math** element is not present in the **FunctionDefinition**, the function has no mathematical meaning defined in SBML Level 3 Core. This situation may arise when models are incomplete, or when additional meaning or
subobjects are provided by an SBML Level 3 package. (However, from the perspective of a model reader that only understands SBML Level 3 Core, the additional meaning will not be recognized.)

### 4.3.3 The sboTerm attribute

**FunctionDefinition** inherits an optional **sboTerm** attribute of type **SBOTerm** from its parent class **SBase** (see Section 3.1.12 and Section 5 on p. 91). When a value is given to this attribute in a **FunctionDefinition** instance, it should be an SBO identifier belonging to the branch for type **FunctionDefinition** indicated in Table 6 on p. 98. The relationship is of the form "the function definition 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 function in the model.

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

### 4.3.4 Calling user-defined functions

Within MathML expressions in an SBML model, all calls to a function defined by a **FunctionDefinition** must use the same number of arguments as specified in the function's definition. The number of arguments is equal to the number of **bvar** elements inside the **lambda** element of the function definition. If the **FunctionDefinition** has no **math** child, SBML Level 3 Core places no restriction on the number of arguments the function may take when used in MathML elsewhere in a model. Additional restrictions may be placed by SBML Level 3 packages. However, without additional content or meaning defined by SBML Level 3 packages, a call to a function that has no **math** content is mathematically meaningless in a model.

Note that **FunctionDefinition** does not have a separate attribute for defining the unit of measurement associated with the value returned by the function. The unit is taken to be whatever results from evaluating the expression when the **FunctionDefinition**'s **math** is applied to the arguments supplied in the call to that function. (See also Section 3.4.12 on p. 31.)

### 4.3.5 Examples

The following abbreviated SBML example shows a **FunctionDefinition** object instance defining `pow3` as the identifier of a function computing the mathematical expression $x^3$, and after that, the invocation of that function in the mathematical formula of a rate law. Note how the invocation of the function uses its identifier.

```xml
<model ...>
<listOfFunctionDefinitions>
<functionDefinition id="pow3">
<math xmlns="http://www.w3.org/1998/Math/MathML"
      xmlns:sbml="http://www.sbml.org/sbml/level3/version2/core">
  <lambda>
    <bvar><ci> x </ci></bvar>
    <apply> <power/> <ci> x </ci> <cn sbml:units="dimensionless"> 3 </cn>
  </apply>
</lambda>
</math>
</functionDefinition>
</listOfFunctionDefinitions>
...
<listOfReactions>
<reaction id="reaction_1" reversible="true">
  ...
  <kineticLaw>
    <math xmlns="http://www.w3.org/1998/Math/MathML">
      <apply> <ci> pow3 </ci> <ci> S1 </ci>
    </apply>
  </kineticLaw>
  ...
</reaction>
</listOfReactions>
...
</model>
```
## 4.4 Unit definitions

The unit of measurement associated with the value produced by a mathematical formula is whatever arises naturally from the components and mathematical expressions comprising the formula, or in other words, the unit obtained by doing dimensional analysis on the formula. To support this, units may be supplied in a number of contexts in an SBML model and associated with a variety of components, and SBML provides a facility for defining units that can be reused and referenced throughout a model. The unit definition facility uses two classes of objects, **UnitDefinition** and **Unit**. Their definitions are shown in Figure 12 and explained in more detail below.

Before delving further into the definition of SBML units, we must highlight two important and sometimes-confusing points. First, unit declarations in SBML models are *optional*. The consequence of this is that a model must be numerically self-consistent independently of unit declarations, for the benefit of software tools that cannot interpret or manipulate units. Unit declarations in SBML are thus more akin to a type of annotation; they can indicate intentions, and can be used by model readers for checking the consistency of the model, labeling simulation output, etc., but any transformations of values implied by different units must be incorporated *explicitly* into a model. We revisit this topic in Section 4.4.4 on p. 45, and illustrate it again with the example given in Section 7.2 on p. 115.

Second, the vast majority of situations that require new SBML unit definitions involve simple multiplicative combinations of base units and factors. An example is “moles per litre per second”. What distinguishes these sorts of unit definitions from more complex ones is that they may be expressed without the use of an additive offset from a zero point. The use of offsets complicates all unit definition systems, yet in the domain of SBML, the real-life cases requiring offsets are few (and in fact, to the best of our knowledge, only involve temperature). Consequently, the SBML unit system has been consciously designed to simplify implementation of unit support for the most common cases in systems biology. The cost of this simplification is to require units with offsets to be handled explicitly by the modeler. Section 8.2.1 on p. 148 discusses approaches for handling situations requiring units with offsets.

### 4.4.1 UnitDefinition

The approach to defining units in SBML is compositional; for example, *metre second*⁻² is constructed by combining a **Unit** object representing *metre* with another **Unit** object representing *second*⁻². The combination is wrapped inside a **UnitDefinition**, which provides for assigning an identifier and optional name to the combination. These object classes are defined in Figure 12. Once a unit is defined using a **UnitDefinition** object, it can then be referenced from elsewhere in a model.

<figure><img src="image_15.png" /><figcaption>Figure 12: The definition of classes **UnitDefinition** and **Unit**. A sequence of zero or more instances of **UnitDefinition** can be located in an instance of **ListOfUnitDefinitions** in 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.</figcaption></figure>

#### The **id** attribute

**UnitDefinition** inherits the **id** attribute from **SBase**, but defines **id** as being required rather than optional, and in addition, refines the data type of **id** to be **UnitSId** instead of **SId**. This is done to provide each unit definition with a unique identifier by which other components of a model may refer to it. (See Section 3.3 on p. 18 for more details.)
There is one important restriction about the use of unit definition `id` values: the `id` of a `UnitDefinition` must not be equal to one of the reserved base unit names listed in Table 2 on the following page, the list of reserved base unit names. This constraint simply prevents the redefinition of base units.

## The list of Units

A `UnitDefinition` object may contain a `ListOfUnits` container which may contain zero or more `Unit` objects. Section 4.4.2 explains the meaning and use of `Unit`.

In SBML Level 3 Version 2 Core, the list of units in a `UnitDefinition` object may be empty. This is permitted for the same reasons that other lists are permitted to be empty. (See the discussion in Section 4.2.7 on p. 39.) An empty unit definition is synonymous with an undefined unit. For example, suppose a given component in a model is defined to have a unit of measurement “u”. If the `UnitDefinition` object with identifier “u” has an empty `ListOfUnits` subobject, then this is identical to leaving the unit undefined on the component.

## Example

The following skeleton of a unit definition illustrates an example use of `UnitDefinition`:

```xml
<model ...>
  <listOfUnitDefinitions>
    <unitDefinition id="unit1">
      <listOfUnits>
        ...
      </listOfUnits>
    </unitDefinition>
    <unitDefinition id="unit2">
      <listOfUnits>
        ...
      </listOfUnits>
    </unitDefinition>
  </listOfUnitDefinitions>
  ...
</model>
```

## 4.4.2 Unit

A `Unit` object represents a reference to a (possibly transformed) base unit chosen from the list in Table 2 on the next page. The attribute `kind` indicates the base unit, whereas the attributes `exponent`, `scale`, and `multiplier` define how the base unit is being transformed. The attributes are described in detail below.

### The kind attribute

The `Unit` attribute `kind` specifies a base unit to serve as the starting point for a new unit definition. The value of the attribute must be taken from the list of reserved words given in Table 2 on the following page. These reserved symbols are defined in the value space of the data type `UnitId` (Section 3.1.9 on p. 13).

Note that the set of acceptable values for the attribute `kind` does not include units defined by `UnitDefinition` objects. This means that the unit definition system in SBML is not hierarchical: user-defined units cannot be built on top of other user-defined units, only on top of base units.

The presence of `avogadro` in Table 2 on the following page warrants an explanation. The Bureau International des Poids et Mesures specifically states, “When the mole is used, the elementary entities must be specified and may be atoms, molecules, ions, electrons, other particles, or specified groups of such particles” (Bureau International des Poids et Mesures, 2006, p. 115)—in other words, the SI unit `mole` is technically a unit of measure for substance amount. Although people sometimes use “mole” loosely to refer to other things besides substance amounts (e.g., “a mole of X” to mean a number of X equal to Avogadro’s number, $6.022 \cdot 10^{23}$), such usage is not strictly correct. We believe it is even less correct in the context of reactions: although in SBML they are called “reactions”, there is nothing preventing the SBML `Reaction` construct from being used to represent other kinds of processes not involving substances. Consequently, we avoid using “mole” loosely where substances may not be involved, and instead use “Avogadro’s number of X”. In order to make it
<table><caption>**Table 2:** Base units defined in SBML. These symbols are predefined values of type UnitSId (Section 3.1.9 on p. 13). All are names of base or derived SI units (Bureau International des Poids et 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.</caption><tr><td>ampere</td><td>coulomb</td><td>gray</td><td>joule</td><td>litre</td><td>mole</td><td>radian</td><td>steradian</td><td>weber</td></tr><tr><td>avogadro</td><td>dimensionless</td><td>henry</td><td>katal</td><td>lumen</td><td>newton</td><td>second</td><td>tesla</td><td></td></tr><tr><td>becquerel</td><td>farad</td><td>hertz</td><td>kelvin</td><td>lux</td><td>ohm</td><td>siemens</td><td>volt</td><td></td></tr><tr><td>candela</td><td>gram</td><td>item</td><td>kilogram</td><td>metre</td><td>pascal</td><td>sievert</td><td>watt</td><td></td></tr></table>

easier for models to define units in these terms, the SBML unit system includes the pseudo-unit "avogadro", whose definition is identical to the definition of the avogadro csymbol described in Section 3.4.6 on p. 25. The numerical value is taken to be the one recommended by CODATA (Mohr et al., 2008), but the unit is dimensionless. In other words, it is defined as

$$ (6.02214179 \cdot 10^{23}) \cdot \text{dimensionless} $$

where the dot (·) indicates simple scalar multiplication. If the value of Avogadro's constant is revised by international standards-setting organizations in the future, a future Version of the SBML Level 3 specification may stipulate a new value to be used for **avogadro**. However, all software reading models expressed in this version of SBML Level 3 should always use the value of Avogadro's constant given above.

Software tools must use identical numerical values of Avogadro's constant for both the base unit **mole** and the unit **avogadro**.

### The exponent, scale and multiplier attributes

The attributes **exponent**, **scale** and **multiplier** work together to permit the use of **Unit** for expressing new units in terms of the base units listed in Table 2. The formula underlying this definition is the following:

$$ u_{\text{new}} = (\text{multiplier} \cdot 10^{\text{scale}} \cdot u_{\text{kind}})^{\text{exponent}} \quad (1) $$

This formula defines a new unit, $u_{\text{new}}$, in terms of another unit, $u_{\text{kind}}$. The unit $u_{\text{kind}}$ is one of the units listed in Table 2; in a given **Unit** object, it is chosen by setting the **kind** attribute. Each of the other components on the right-hand side of Equation 1 corresponds to the remaining attributes in a **Unit** object instance, and their meanings are as follows:

* The **multiplier** attribute can be used to multiply the **kind** unit by a real-numbered factor. This enables the definition of units that are not power-of-ten multiples of SI units. For instance, a **multiplier** of 0.3048 could be used to define "foot" as a measure of length in terms of a "metre". A value of **multiplier** must always be provided in a **Unit** object instance, but the value can be "1".

* The **scale** attribute can be used to set the exponent for a power-of-ten multiplier that rescales the unit. For example, a unit having a **kind** value of "gram" and a **scale** value of "-3" signifies $10^{-3} \cdot \text{gram}$, or milligrams. In those cases where a unit does not need to be scaled by a power of ten, the value of **scale** can be set to "0" (zero), because $10^0 = 1$.

* The **exponent** attribute can be used to specify an overall exponent on the unit definition. This provides 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.

### 4.4.3 Semantics of Unit and UnitDefinition

A single **Unit** object instance takes one of the base units from Table 2 and specifies how it should be transformed. A **UnitDefinition** object instance combines one or more **Unit** objects to define a new, composed unit, *u*. The new
unit u created by a **UnitDefinition** is defined as the product of all the **Unit** objects contained in the **OfUnits** within the **UnitDefinition** object instance. More formally,

$$u = u_1 \cdot u_2 \cdot \dots \cdot u_n \qquad (2)$$

where the {$u_i$}'s are individual **Unit** definitions as defined by Equation 1. Now, let the value of the **multiplier** attribute of a given unit {$u_i$} be represented by the symbol $m_i$. Similarly, let the value of the **scale** attribute be represented by $s_i$, and the value of the **exponent** attribute be represented by $x_i$. Equation 2 can be rewritten in expanded form as

$$ \begin{aligned} u &= (m_1 \cdot 10^{s_1} \cdot u_{b_1})^{x_1} \cdot (m_2 \cdot 10^{s_2} \cdot u_{b_2})^{x_2} \cdot \dots \cdot (m_n \cdot 10^{s_n} \cdot u_{b_n})^{x_n} \\ &= m_1^{x_1} \cdot m_2^{x_2} \cdot \dots \cdot m_n^{x_n} \cdot 10^{(s_1 x_1 + s_2 x_2 + \dots + s_n x_n)} \cdot u_{b_1}^{x_1} \cdot u_{b_2}^{x_2} \cdot \dots \cdot u_{b_n}^{x_n} \\ &= m \cdot 10^s \cdot u_{b_1}^{x_1} \cdot u_{b_2}^{x_2} \cdot \dots \cdot u_{b_n}^{x_n} \end{aligned} \qquad (3) $$

where the terms $m$ and $s$ in the last line (Equation 3) are defined as

$$ \begin{aligned} m &= m_1^{x_1} \cdot m_2^{x_2} \cdot \dots \cdot m_n^{x_n} \\ s &= s_1 x_1 + s_2 x_2 + \dots + s_n x_n \end{aligned} $$

Equation 3 expresses how a **UnitDefinition** object instance combines multiple **Unit** object instances to produce a new unit definition in an SBML model.

### Examples

As a concrete example to illustrate the definitions above, let us define a unit for “foot” in terms of the base unit “metre”. This requires using `multiplier="0.3048", scale="0", exponent="1":`

$$\text{foot} = 0.3048 \cdot 10^0 \cdot \text{metre}$$

The following fragment of SBML illustrates how this could be represented in XML:

```xml
<listOfUnitDefinitions>
  <unitDefinition id="foot">
    <listOfUnits>
      <unit kind="metre" multiplier="0.3048" scale="0" exponent="1"/>
    </listOfUnits>
  </unitDefinition>
</listOfUnitDefinitions>
```

To give another example, the following illustrates the definition of an abbreviation "mmls" for the unit millimoles $l^{-1} s^{-1}$:

```xml
<listOfUnitDefinitions>
  <unitDefinition id="mmls">
    <listOfUnits>
      <unit kind="mole" exponent="1" scale="-3" multiplier="1"/>
      <unit kind="litre" exponent="-1" scale="0" multiplier="1"/>
      <unit kind="second" exponent="-1" scale="0" multiplier="1"/>
    </listOfUnits>
  </unitDefinition>
</listOfUnitDefinitions>
```

Section 8.2.1 on p. 148 provides suggestions for possible ways of handling cases that involve offsets, which happen in particular with temperature measurements.

### 4.4.4 Use of units in a model

As already mentioned, unit declarations are optional in SBML. This design decision was a consensus choice among SBML developers and users, driven by the exigencies of non-commercial software development and the realities of models found in existence. It has an important and possibly counterintuitive implication that
must be kept in mind when writing and interpreting SBML models: units associated with quantities do not alter the numerical interpretation of those quantities.

An example may help make this more clear. We know that one metre equals 1000 millimetres:

$$1 \text{ m} = 1000 \text{ mm}$$

However, the equality above relies on interpreting the units on both sides, and taking the “1” and “1000” to be dimensionless. If readers ignored unit labels altogether or were unable to process them, they would see

$$1 = 1000$$

which is obviously incorrect. In an SBML model, the necessary factor must be included explicitly, even if it is part of the definition of the unit. A ramification of this is that units attached to SBML quantities must be viewed as a kind of independent annotation or label that does not enter into the numerical interpretation of the actual quantity or the mathematical formulas appearing in a model. In the present simple formula, an explicit factor such as the following needs to be inserted (and here we put unit names in {} braces to indicate they are annotations that do not enter into the mathematics):

$$1 \{\text{m}\} = 1000 \cdot \frac{1 \{\text{m}\}}{1000 \{\text{mm}\}} \{\text{mm}\} \quad (4)$$

This is despite the fact that a unit definition for millimetres in SBML would take the following form:

```xml
<listOfUnitDefinitions>
  <unitDefinition id="millimetre">
    <listOfUnits>
      <unit kind="metre" exponent="1" scale="-3" multiplier="1"/>
    </listOfUnits>
  </unitDefinition>
</listOfUnitDefinitions>
```

In other words, the definition also includes a factor of 1/1000. While the result is that information is duplicated between the definition of millimetre above and the explicit factor inserted into Equation 4, the machinery provided by UnitDefinition is still necessary in order to allow units themselves to be properly defined. The result is still useful and powerful: it permits software tools to check the consistency of a model, perform unit conversions, label numbers in the outputs of simulations, and so on.

Finally, as mentioned above, unit definitions in SBML Level 3 Version 2 Core may have empty ListOfUnits substructures. A UnitDefinition with no child Unit elements is not fully defined, and a model component that references this UnitDefinition is taken to have no defined unit. A model with an empty unit definition may indicate an incomplete model or a model that needs external information.

## 4.5 Compartments

A compartment in SBML represents a bounded space in which species are located. Compartments do not necessarily have to correspond to actual structures inside or outside of a biological system, although models are often designed that way. The definition of Compartment is shown in Figure 13 on the following page.

It is important to note that although compartments are optional in the overall definition of Model, every species in an SBML model must be located in a compartment. This in turn means that if a model defines any species, the model must also define at least one compartment. The reason is simply that species represent physical things, and therefore must exist somewhere. Compartments represent the somewhere.

### 4.5.1 The id attribute

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

The identifier (the id attribute value) of a Compartment object may be used in a model's mathematical expressions. The identifier stands for the value of the compartment's size attribute, with a unit of mea-
<figure><img src="image_16.png" /><figcaption>**Figure 13:** The definition of class **Compartment**. A sequence of zero or more instances of **Compartment** objects can be located in an instance of ** ListOfCompartments in Model**, as shown in Figure 10 on p. 37.</figcaption></figure>

surement as defined in Section 4.5.4. A compartment's identifier may be the target of an **InitialAssignment**, **EventAssignment**, or **Rule** in the model, to set or redefine the value of the compartment size.

### 4.5.2 The spatialDimensions attribute

A **Compartment** object has an optional floating-point attribute named **spatialDimensions** whose value indicates the number of spatial dimensions possessed by the compartment. Most modeling scenarios involve compartments with integer values of **spatialDimensions**=“3” (i.e., a three-dimensional compartment, which is to say, a volume), **spatialDimensions**=“2” (i.e., a two-dimensional compartment, a surface), or **spatialDimensions**=“1” (i.e., a one-dimensional compartment, which is to say, a line). However, SBML Level 3 does not restrict compartments' **spatialDimensions** values, in order to allow for the possibility of representing structures with fractal dimensions.

In SBML Level 3 Version 2 Core, the number of spatial dimensions possessed by a compartment cannot enter into mathematical formulas, and therefore cannot directly alter the numerical interpretation of a model. However, the value of **spatialDimensions** does affect the interpretation of units. Specifically, the value of **spatialDimensions** is used to select among the **Model** attributes **volumeUnits**, **areaUnits** and **lengthUnits** when a **Compartment** object does not define a value for its **units** attribute. This is described in more detail below in Section 4.5.4 on the following page.

### 4.5.3 The size attribute

The optional **Compartment** attribute **size**, with a data type of **double**, can be used to set the initial size of the compartment. The size may correspond to a volume (if the compartment is a three-dimensional one), or it may be an area (if the compartment is two-dimensional), or a length (if the compartment is one-dimensional).

A compartment's size is set by its **size** attribute exactly once. If the compartment's attribute **constant** has the value **true**, then the compartment's size is fixed and cannot be changed except by an **InitialAssignment** in the model. The approach of using an **InitialAssignment** differs from setting the **size** attribute in that **size** can only be used to set the compartment size to a literal floating-point number, whereas **InitialAssignment** allows the value to be set using an arbitrary mathematical expression (which, thanks to MathML's expressiveness, may evaluate to a rational number). If the compartment's **constant** attribute is **false**, the size value may be overridden by an **InitialAssignment** or changed by an **AssignmentRule** or **AlgebraicRule**, and in addition, for simulation time $t > 0$, it may also be changed by a **RateRule** or **Event**. (However, some constructs are 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 **size** on a compartment and also redefine the value using an **InitialAssignment**, but the original **size** value in that case is ignored. Section 3.4.8 provides additional information about the semantics of assignments, rules and values for simulation time $t \le 0$.

It is important to note that in SBML Level 3, a missing **size** value does not imply that the compartment size is “1”. A missing value for **size** for a given compartment signifies that the value either is unknown, or to be obtained from an external source, or determined by an initial assignment (Section 4.8 on p. 56) or other SBML construct elsewhere in the model. 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, when compartment size values are available. The reasons for this are explained in Section 8.2.2 on p. 150.

### 4.5.4 The units attribute

The measurement unit associated with the value of the compartment's **size** attribute may be specified using the optional attribute **units**. This attribute's value must have the data type **UnitSIIdRef** (Section 3.1.10).

The **units** attribute may be left unspecified for a given compartment in a model; in that case, the compartment inherits the unit of measurement specified by one of the attributes on the enclosing **Model** object instance. The applicable attribute on **Model** depends on the value of the compartment's **spatialDimensions** attribute; the relationship is shown in Table 3. If the **Model** object does not define the relevant attribute (**volumeUnits**, **areaUnits** or **lengthUnits**) for a given **spatialDimensions** value, the unit associated with that **Compartment** object's size is undefined. If both **spatialDimensions** and **units** are left unset on a given **Compartment** object instance, then no unit can be chosen from among the **Model**'s **volumeUnits**, **areaUnits** or **lengthUnits** attributes (even if the **Model** instance provides values for those attributes), because there is no basis to select between them and there is no default value of **spatialDimensions**. Leaving the units of compartments' sizes undefined in an SBML model does not render the model invalid; however, as a matter of best practice, we strongly recommend that all models specify the units of measurement for all compartment sizes. A discussion of recommended units is given in Section 8.2.1 on p. 148.

The unit of measurement associated with a compartment's size, as defined by the **units** attribute or (if **units** is not set) the inherited value from **Model** according to Table 3, is used in the following ways:

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

* When a **Species** is to be treated in terms of concentrations or density, the unit associated with the spatial size portion of the concentration value (i.e., the denominator in the formula *amount/size*) is specified by the value of the **units** attribute on the compartment in which the species is located.

* The **math** elements of **AssignmentRule**, **InitialAssignment** and **EventAssignment** objects setting the value of the compartment size should all have the same units as the unit associated with the compartment's size (see Section 4.9.3 on p. 62 and Section 4.8 on p. 56).

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

<table><caption>**Table 3:** When a **Compartment** object instance does not specify a value for the attribute **units**, but does specify a value for **spatialDimensions**, a value for **units** is inherited from the enclosing **Model** instance according to the rules listed above. The left-hand column indicates the value of the compartment's **spatialDimensions** attribute, and the middle column indicates the attribute on **Model** whose value should be used in that case. The right-hand column lists the kinds of units recommended for use in each case.</caption><thead><tr><th>Value of attribute<br>spatialDimensions</th><th>Attribute of Model used<br>for inheriting the unit</th><th>Recommended candidate units</th></tr></thead><tbody><tr><td>"3"</td><td>volumeUnits</td><td>units of volume, or dimensionless</td></tr><tr><td>"2"</td><td>areaUnits</td><td>units of area, or dimensionless</td></tr><tr><td>"1"</td><td>lengthUnits</td><td>units of length, or dimensionless</td></tr><tr><td>other</td><td>no units inherited</td><td>no specific recommendations</td></tr></tbody></table>

### 4.5.5 The constant attribute

A **Compartment** also has a mandatory **boolean** attribute called **constant** that indicates whether the compartment's size stays constant or can vary during a simulation. A value of "false" indicates the compartment's
size can be changed by other constructs in SBML. A value of “true” indicates the compartment's size cannot be changed by any construct except **InitialAssignment**. Section 4.5.3 on p. 47 provides more information.

### 4.5.6 The sboTerm attribute

**Compartment** inherits an optional **sboTerm** attribute of type **SBOTerm** from its parent class **SBase** (see Section 3.1.12 on p. 14 and Section 5 on p. 91). When a value is given to this attribute in a **Compartment** instance, it should be an SBO identifier belonging to the branch for type **Compartment** indicated in Table 6 on p. 98. The relationship is of the form “the compartment 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 compartment in the model.

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

### 4.5.7 Examples

The following example illustrates three compartments in an abbreviated SBML example of a model definition. The compartment definitions do not set their **units** attribute, so these compartments inherit units from the **model** element attributes **areaUnits** and **volumeUnits**.

```xml
<model areaUnits="area" volumeUnits="litre" ...>
  ...
  <listOfUnitDefinitions>
    <unitDefinition id="area">
      <listOfUnits>
        <unit kind="metre" exponent="2" scale="-6" multiplier="1"/>
      </listOfUnits>
    </unitDefinition>
  </listOfUnitDefinitions>
  ...
  <listOfCompartments>
    <compartment id="Extracellular" spatialDimensions="3" size="1e-14" constant="true"/>
    <compartment id="PlasmaMembrane" spatialDimensions="2" size="1e-14" constant="true"/>
    <compartment id="Cytosol" spatialDimensions="3" size="1e-15" constant="true"/>
  </listOfCompartments>
  ...
</model>
```

## 4.6 Species

A species in SBML refers to a pool of entities that (a) are considered indistinguishable from each other for the purposes of the model, (b) may participate in reactions, and (c) are located in a specific compartment. The SBML **Species** object class is intended to represent these pools. Its definition is shown in Figure 14 on the next page.

### 4.6.1 The id attribute

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

The identifier (the **id** attribute value) of a **Species** object may be used in a model's mathematical expressions. The identifier stands for the given species' amount or concentration, depending on the value of its **hasOnlySubstanceUnits** attribute as described below, with units of measurement as described in Section 4.6.4 on the next page. A species' identifier may be the target of **InitialAssignment**, **EventAssignment**, or **Rule** objects in a model, to set or redefine the value of the species amount or concentration.

### 4.6.2 The sboTerm attribute

**Species** inherits an optional **sboTerm** attribute of type **SBOTerm** from its parent class **SBase** (see Section 3.1.12 and Section 5). Values for this attribute should be SBO identifiers taken the branch for type **Species** indicated
<figure><img src="image_17.png" /><figcaption>**Figure 14:** The definition of class *Species*. Zero or more instances of *Species* objects can be located in an instance of * ListOfSpecies* in *Model*, as shown in Figure 10 on p. 37.</figcaption></figure>

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 chosen should be the most precise (narrow) one that captures the role of the species in the model.

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

### 4.6.3 The compartment attribute

The required attribute `compartment`, of type `SIdRef`, is used to identify the compartment in which the species is located. The attribute's value must be the identifier of an existing **Compartment** object in the model. Note that SBML does not have a concept of a default compartment—every species in an SBML model must be assigned a compartment *explicitly*, by setting the value of the **compartment** attribute. (This also implies that every model with one or more **Species** objects must define at least one **Compartment** object.)

### 4.6.4 The initialAmount, initialConcentration, and substanceUnits attributes

The optional attributes `initialAmount` and `initialConcentration`, both having a data type of `double`, can be used to set the initial quantity of the species in the compartment where the species is located. These two attributes are mutually exclusive—either one can be used, but *only one* can have a value on any given instance of a **Species** object. (Setting both is an error.) Missing `initialAmount` and `initialConcentration` values implies that their values either are unknown, or to be obtained from an external source, or determined by an initial assignment (Section 4.8 on p. 56) or other SBML construct elsewhere in the model.

A species' initial quantity is set by the `initialAmount` or `initialConcentration` attributes exactly once. If the `constant` attribute is “true”, then the value of the species' quantity is fixed and cannot be changed except by an **InitialAssignment**. These methods differ in that the `initialAmount` and `initialConcentration` attributes can only be used to set the species' quantity to a literal floating-point number, whereas the use of an **InitialAssignment** object allows the value to be set using an arbitrary mathematical expression (which, thanks to MathML's expressiveness, may evaluate to a rational number). If the species' `constant` attribute is “false”, the species' quantity value may be overridden by an **InitialAssignment** or changed by **AssignmentRule** or **AlgebraicRule**, and in addition, for $t > 0$, it may also be changed by a **RateRule**, **Event**, and as a result of being a reactant or product in one or more **Reaction** constructs. (However, some constructs are mutually exclusive; see Section 4.9 on p. 59 and Section 4.12 on p. 79.) It is not an error to define `initialAmount` or `initialConcentration` on a species and also redefine the value using an **InitialAssignment**, but the `initialAmount` or `initialConcentration` setting in that case is ignored. Section 3.4.8 provides additional information about the semantics of assignments, rules and values for simulation time $t \le 0$.

When the attribute `initialAmount` is set, the unit of measurement associated with its value is specified by the **Species** attribute `substanceUnits`, whose value must have the data type `UnitSIdRef` (Section 3.1.10 on p. 13). When the `initialConcentration` attribute is set, the unit of measurement associated with this 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 in which the species is located. Note that in either case, a unit of *amount* is involved and determined by the **substanceUnits** attribute. If the **substanceUnits** attribute is not set on a given **Species** object instance, then the unit of *amount* for that species is inherited from the **substanceUnits** attribute on the enclosing **Model** object instance. If that attribute on **Model** is not set either, then the unit associated with the species' quantity is undefined. Leaving units of species quantities undefined in an SBML model does not render the model invalid; however, as a matter of best practice, we strongly recommend that all models specify the units of measurement for all species quantities. A list of recommended units is given in Section 8.2.1 on p. 148.

Simply setting `initialAmount` or `initialConcentration` alone does not determine whether a species identifier represents an amount or a concentration when it appears elsewhere in an SBML model. Instead, that aspect is controlled by the attribute `hasOnlySubstanceUnits`, discussed in Section 4.6.5 below.

### 4.6.5 The `hasOnlySubstanceUnits` attribute

Independently from how the initial value of a species' quantity is set (Section 4.6.4 on the preceding page), SBML allows choosing the meaning intended for a species' identifier when the identifier appears in mathematical expressions or as the subject of SBML rules or assignments. The interpretation is controlled by the attribute `hasOnlySubstanceUnits`. If the attribute has the value `false`, then the unit of measurement associated with the value of the species is `{unit of *amount*}/{unit of *size*}` (i.e., concentration or density). If `hasOnlySubstanceUnits` has the value `true`, then the value is interpreted as having a unit of *amount* only.

Although it may seem as though this intention could be determined by either (i) determining whether the `initialAmount` or `initialConcentration` attribute is set on a given **Species** object or (ii) examining the particular unit declared by the **Species** or **Model** object's **substanceUnits** attributes, the fact that all of these attributes are optional means that a separate flag is needed. (Consider the situation where neither is set, and instead the species' quantity is established by an **InitialAssignment** or **AssignmentRule**—something else is then needed to indicate whether the species' identifier represents a concentration or an amount.)

The unit of measurement associated with a species' quantity is used in the following ways in SBML:

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

* The **math** elements of **AssignmentRule**, **InitialAssignment** and **EventAssignment** objects referring to this species should all have the same units as the unit of measurement associated with the species quantity.

* In a **RateRule** object that defines the rate of change of the species' quantity, the unit associated with the rule's **math** element should be equal to the unit of the species' quantity (Section 4.6.5) divided by the model-wide unit of *time* (Section 4.2.3); in other words, `{unit of *species quantity*}/{unit of *time*}`.

### 4.6.6 The `constant` and `boundaryCondition` attributes

The **Species** object has two other mandatory **boolean** attributes named **constant** and **boundaryCondition**, used to indicate whether and how the amount of that species can vary during a simulation. Table 4 on the next page shows how to interpret the combined values of the **boundaryCondition** and **constant** attributes.

When a species is a product or reactant of one or more reactions, its amount is determined by those reactions. 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 system, and its amount is not determined by the reactions. The **boolean** attribute **boundaryCondition** with value `true` can be used to indicate this. A value of `false` indicates that the species *is* part of the reaction system.

The **constant** attribute indicates whether the species' amount can be changed at all, regardless of whether by reactions, rules, or constructs other than **InitialAssignment**. A value of `false` indicates that the species' amount can be changed. This is the most common situation because the purpose of many models is precisely to calculate changes in species quantities over time. Note that the initial quantity of a species can be set by
<table><caption>**Table 4:** How to interpret the values of the constant and boundaryCondition attributes on Species. Note that column four is specifically about reactants and products and not also about species acting as modifiers; the latter are by definition unchanged by reactions.</caption><thead><tr><th>constant value</th><th>boundaryCondition value</th><th>Can have assignment or rate rule?</th><th>Can be reactant or product?</th><th>What can change the species' amount?</th></tr></thead><tbody><tr><td>true</td><td>true</td><td>no</td><td>yes</td><td>(never changes)</td></tr><tr><td>false</td><td>true</td><td>yes</td><td>yes</td><td>rules and events</td></tr><tr><td>true</td><td>false</td><td>no</td><td>no</td><td>(never changes)</td></tr><tr><td>false</td><td>false</td><td>yes</td><td>yes</td><td>reactions or rules (but not both), and events</td></tr></tbody></table>

an **InitialAssignment** irrespective of the value of the **constant** attribute.

In practice, a **boundaryCondition** value of “**true**” means a differential equation derived from the reaction definitions should not be generated for the species. However, the species’ amount may still be changed by **AssignmentRule**, **RateRule**, **AlgebraicRule**, **Event**, and **InitialAssignment** constructs if its **constant** attribute is “**false**”. Conversely, if both the species’ **boundaryCondition** and **constant** attributes are “**true**”, then its amount cannot be changed by anything except **InitialAssignment**.

A species having **boundaryCondition**=“**false**” and **constant**=“**false**” can appear as a product and/or reactant of one or more reactions in the model. If the species is a reactant or product of a reaction, it must not also appear as the target of any **AssignmentRule** or **RateRule** object in the model. If instead the species has **boundaryCondition**=“**false**” and **constant**=“**true**”, then it cannot appear as a reactant or product, or as the target of any **AssignmentRule**, **RateRule** or **EventAssignment** object in the model.

The example model in Section 7.7 on p. 128 contains all four possible combinations of the **boundaryCondition** and **constant** attributes on **species** elements. Section 7.8 on p. 130 gives an example of how one can translate into ODEs a model with species of mixed **boundaryCondition** attribute values.

Finally, it is worth clarifying that while the **constant** and **boundaryCondition** attributes restrict whether and how the species amount changes, the same is not true of a species’ concentration. In SBML, the concentration of a species is a quantity that depends on the size of the compartment in which it is located. A compartment’s size may change, and therefore, so can the concentration of a species even if the *amount* of the species remains unchanged. A species’ concentration may vary even if the **Species** object’s **constant**=“**true**” in a model.

### 4.6.7 The conversionFactor attribute

The attribute **conversionFactor** defines a conversion factor that applies to a particular species. The value of the attribute must have the data type **SIIdRef** and must be the identifier of a **Parameter** object instance defined in the model. That **Parameter** object must be a constant, meaning its **constant** attribute must be set to “**true**”. If a given **Species** object definition defines a value for its **conversionFactor** attribute, it takes precedence over any factor defined by the **Model** object’s **conversionFactor** attribute.

In SBML, the unit of measurement associated with a species’ quantity can be different from the unit of extent of reactions in the model. SBML avoids implicit unit conversions by providing an explicit way to indicate any unit conversion that might be required. The use of a conversion factor in computing the effects of reactions on a species’ quantity is explained in Section 4.11.7 on p. 78. Because the value of the **conversionFactor** attribute is the identifier of a **Parameter** object, and because parameters can have units attached to them, the transformation from reaction extent units to species units can be completely specified using this approach.

Note that the unit conversion factor is only applied when calculating the effect of a reaction on a species. It is not used in any rules or other SBML constructs that affect the species, and it is also not used when the value of the species is referenced in a mathematical expression.