Systems biology markup language (SBML) level 3 package: multistate, multicomponent and multicompartment species, version 1, release 2

Abstract Rule-based modeling is an approach that permits constructing reaction networks based on the specification of rules for molecular interactions and transformations. These rules can encompass details such as the interacting sub-molecular domains and the states and binding status of the involved components. Conceptually, fine-grained spatial information such as locations can also be provided. Through “wildcards” representing component states, entire families of molecule complexes sharing certain properties can be specified as patterns. This can significantly simplify the definition of models involving species with multiple components, multiple states, and multiple compartments. The systems biology markup language (SBML) Level 3 Multi Package Version 1 extends the SBML Level 3 Version 1 core with the “type” concept in the Species and Compartment classes. Therefore, reaction rules may contain species that can be patterns and exist in multiple locations. Multiple software tools such as Simmune and BioNetGen support this standard that thus also becomes a medium for exchanging rule-based models. This document provides the specification for Release 2 of Version 1 of the SBML Level 3 Multi package. No design changes have been made to the description of models between Release 1 and Release 2; changes are restricted to the correction of errata and the addition of clarifications.

] that supports encoding models with molecular complexes that have multiple compo-3 nents and can exist in multiple states and in multiple compartments. One of its goals is to provide a platform for 4 sharing models based on the specifications of molecular transformations/interactions and the rules governing such 5 reactions [Angermann et al. (2012); Feret et al. (2009) ;Hlavacek et al. (2006); Zhang et al. (2013)]. This specification 6 covers the goals and features described in the previous Multi proposal [Le Novère and Oellrich (2010)] for extending 7 SBML to carry the information for multistate multicomponent species with revised data structure. In addition, this 8 specification includes the feature for multicompartment species as described in the releases of the Multi proposal 9 [Zhang and Meier-Schellersheim (2013a), ]. 10 1.1 Proposal and specifications 11 The proposal corresponding to this package specification is available at:  18 The Multi package has no dependencies on other SBML Level 3 packages. For other matters involving the use of UML, XML and typographical conventions, this document follows the 31 conventions used in the SBML Level 3 Core specification document [Hucka et al. (2016)].

32
For simplicity, "..." in all example code refers to some unspecified code content, that is not important for the 33 purpose of illustrating the issue at hand. 34 We use red color in text to indicate changes between this version of the specification, namely SBML Multi Package 35 Version 1 Release 2, and the most recent previous release of the specification (which, for the present case, is SBML 36 Multi Package Version 1 Release 1). 37 2 Background and context 1 Rule-based, domain-detailed modeling has been extremely valuable in systems biology related studies [Manes et al. 2 (2015) and Miskov-Zivanov1 et al. (2013)]. Rule-based, domain-detailed modeling approaches (BioNetGen [Faeder 3 et al. (2009)], Kappa [Danos and Laneve (2004)], and Simmune [Angermann et al. (2012); Meier-Schellersheim 4 et al. (2006)]) define rules for transformations of molecular domains and interactions between pairs of molecule 5 domains, specifying how the transformations/interactions depend on particular states of the molecules (pattern) 6 and their locations in specific compartments. In order to generate networks of biochemical reactions these rules 7 are applied to the molecular components of the systems to be modeled, either at the beginning of the modeling 8 (simulation) process or "on the fly" (as molecule complexes emerge from the interaction rules). Expressing such 9 rule-based, domain-detailed reaction networks using the concepts of Species and Compartment in SBML (L3 core 10 and L2) can be difficult for rules and molecule sets that lead to large numbers of resulting molecular complexes. It 11 would therefore be desirable to have an SBML standard for encoding rule-based, domain-detailed models using 12 their "native" concepts for describing reactions instead of having to apply the rules and unfold the networks prior to 13 encoding in an SBML format. 14 We proposed a revised proposal of the Multi package: "Multistate, Multicomponent and Multicompartment Species 15 Package for SBML Level 3" (abbreviated as Multi)  and Zhang and Meier-Schellersheim (2013a)] 16 which takes the scopes and some data structures developed in the previous Multi proposal [Le Novère and Oellrich 17 (2010)] and addresses main issues arising from a rule-based, domain-detailed modeling point of view with the data 18 structures consistent with that used in the available rule-based, domain-detailed modeling tools.  Oellrich (2010)]. However, it was realized that a more detailed treatment of molecular binding sites and their 27 state-dependent interactions would be desirable. 28 ■ In August 2012, Fengkai Zhang from the Simmune group presented " Draft for discussion SBML Proposals 29 for Revised Multi, Simple Spatial and Multi-Spatial Extensions" at COMBINE 2012 ]. The 30 three proposals cover the goals and scope of the previous Multi proposal (2010), revise it and add some new 31 features that improve usage of the proposal for rule-based approaches.  z: release of the Multi package at its version y. 8 status: "draft", "release candidate", or "release". Absence of status means "release". 9 For example, the current version is "1.1.2" 10 x = "1" • Fix issues raised by the community after "Version 1 release 1". 18 • Revise parts of the text.

19
• Add a paragraph to clarify "XML Namespace use"(see Section 3.1 on page 9).

20
• Validate the complete models and add "demonstration only" notes to those "incomplete" models in the 21 example section (see Section 4 on page 36).

39
Revise the specification text with minor changes towards a version of the official release candidate. 40 ■ Version: 1.1.rc1 (release candidate), November 2016 1 Revise the specification text with minor changes towards a version of the official release candidate. This version has been developed from the previous release v1.0.4 with the following modifications based on 15 the discussion during and after COMBINE 2015 [Zhang (2015)]: 16 • Drop the occur attribute in the class of SpeciesTypeInstance. 17 • Drop the occur attribute in the class of SpeciesTypeComponentIndex. 18 • Drop the class of DenotedSpeciesTypeComponentIndex. 19 • Revise the scope of PossibleSpeciesFeatureValue ids to be global. This version has been developed from the previous release v1.0.2 mainly based on the discussion in COMBINE 26 2014 with focus on how to facilitate tools to export and import models encoded in the Multi format [Zhang 27 and Meier-Schellersheim (2014)] 28 ■ Version 1.0.2 (draft), November 2014 29 This version has been developed from the previous release v1.0.1 with the following modifications: 30 • A new BindingSiteSpeciesType sub-class inheriting the SpeciesType class for binding sites. Accord-31 ingly, the isBindingSite attribute has been dropped from SpeciesType. 32 • Restriction on binding sites which have to be atomic.

33
• Restriction on SpeciesType that a speciesType cannot have a listOfSpeciesFeatureTypes if it has a 34 listOfInSpeciesTypeBonds.

35
• A new IntraSpeciesReaction sub-class inheriting the Reaction class for the reactions happening within a 36 Species object. Accordingly, the isIntraSpeciesReaction attribute has been dropped from Reaction. 37 • Validation rules. This was released and presented in COMBINE 2013 [Zhang and Meier-Schellersheim (2013c)], mainly 40 addressing the scenario of multiple occurrences of identical components and/or identical features.   1 This section contains a definition of the syntax and semantics of the Multi package for SBML Level 3 Core. 2 3.1 Namespace URI and other declarations necessary for using this package 3 The following is the namespace URI for this version of the Multi package for SBML Level 3 Core: 4 "http://www.sbml.org/sbml/level3/version1/multi/version1" 5 In addition, SBML documents using a given package must indicate whether the package can be used to change the 6 mathematical interpretation of a model. This is done using the attribute required on the <sbml> element in the 7 SBML document. For the Multi package, the value of this attribute must be "true". 8 The following fragment illustrates the beginning of a typical SBML model using SBML Level 3 Core and this version 9 of the Multi package: 10 11 <?xml version="1.0" encoding="UTF-8"?> 12 <sbml xmlns="http://www.sbml.org/sbml/level3/version1/core" level="3" version="1" 13 xmlns:multi="http://www.sbml.org/sbml/level3/version1/multi/version1" multi:required="true"> 14 15 XML Namespace use 16 For element names, XML has clear rules about how to declare and use namespaces. In typical SBML documents, 17 the Multi package namespace will be defined as above, and the Multi package elements will therefore need to be 18 prefixed with "multi:". 19 In contrast to element names, XML attribute names are completely defined by the element in which they appear, 20 and never have a 'default' namespace defined: the element itself declares whether any attributes should be defined 21 with a namespace prefix or not. 22 Any attribute that appears in a UML diagram in this specification may either be defined with no namespace prefix, 23 or be defined with the multi namespace as a prefix. For attributes added to SBML core elements (Compartment,24 Species, SimpleSpeciesReference, and within MathML), the multi namespace prefix is required. 25 If the Multi package is used in an SBML Level 3 Version 2 document, any element defined here may have either an 26 id or a name with no prefix, as id and name were added to SBase in that level/version. 27 3.2 Primitive data types 28 The Multi package uses a number of the primitive data types described in section 3.1 of the SBML Level 3 Core 29 Release 2 [Hucka et al. (2016)] specification such as SId, SIdRef, string, boolean, int and positiveInteger, 30 and adds three additional primitive types described below. The BindingStatus primitive data type is used in the definition of the OutwardBindingSite class. BindingStatus 33 is derived from type string and its values are restricted to be one of the following possibilities: "bound", "unbound", 34 and "either". Attributes of type BindingStatus cannot take on any other values. The meaning of these three 35 values is discussed in the context of the OutwardBindingSite class in Section 3.16 on page 23.

37
The Relation primitive data type is used in the definition of the SubListOfSpeciesFeatures class. Relation is 38 derived from type string and its values are restricted to be one of the following possibilities: "and", "or", and "not".

39
Attributes of type Relation cannot take on any other values. The meaning of these three values is discussed in the 40 context of the SubListOfSpeciesFeatures class in Section 3.17 on page 25.

Type RepresentationType 2
The RepresentationType primitive data type is used in the extension of the ci element.

3
RepresentationType is derived from type string and its values are restricted to be one of the following possibi-4 lities: "sum" or "numericValue". If present, attributes of type RepresentationType cannot take on any other values. 5 The meaning of these values is discussed in the context of the ci element in Section 3.26 on page 33. The Multi package extends the following object classes: 8 Model, Compartment, Species, Reaction, SimpleSpeciesReference, and SpeciesReference. 9 The Multi package defines the following object classes:  18 All the classes in the Multi package are directly or indirectly derived from SBase, and SBase provides the ability to 19 attach SBO terms as well as MIRIAM annotations. The semantics of a given class in the Multi package can be made 20 more precise by referencing to external controlled vocabularies and ontologies. 21 Like the classes in SBML Level 3 Core, most new Multi classes have the attribute id (typically mandatory but not 22 all, and of type SId), which serves as an identifier to provide a way to identify the class object. The identifier of 23 a class object reference may or may not carry mathematical interpretation or be used in mathematical formulas, 24 depending on its class and the class object referencing it. The scope of ids is described in the section of "Namespace 25 scoping rules for identifiers"(Section 3.27 on page 35).

27
The Multi package extends the Model class of SBML Level 3 Core and adds an optional ListOfSpeciesTypes child to 28 Model. Figure 1 provides the UML diagram for the extended Model class.

ListOfSpeciesTypes
1 ListOfSpeciesTypes is defined in Figure 1 on the preceding page. If present, a ListOfSpeciesTypes object must 2 contain at least one SpeciesType object. Since ListOfSpeciesTypes is derived from SBase, it inherits the sboTerm 3 and metaid attributes, as well as the optional child Notes and Annotation objects.

5
A Compartment object in SBML Level 3 Core represents a bounded space in which species are located. In the 6 Multi package, Compartment is extended. A Multi compartment can be a type that multiple referencing compart-7 ments can map to. A Multi compartment can also be a composite compartment or a container that includes other 8 compartments. 9 The extension of Compartment is defined in Figure 2. The extended Compartment class has a new required attribute 10 isType, a new optional attribute compartmentType and an optional ListOfCompartmentReferences child. The 11 example at Section 4.1 on page 36 illustrates the use of the extended Compartment class. The required attribute isType, of type boolean, on the Compartment class serves to provide a way to indicate 14 whether the Compartment object is a compartment type. 15 A Compartment object is a type of compartment if the value of its isType attribute is "true". A type of compartment 16 is a template (in the sense of prototype) for all Compartment objects referencing it (via compartmentType attributes).

17
Note: 18 A Species object directly referencing a compartment type is not a fully defined species (see Section 3.19 on page 29). 19 If the value of the isType attribute is "false", the Compartment object is a "not-a-type" compartment , and it is 20 similar to a SBML core compartment except it can reference a compartment type and can have a ListOfCompart-21 mentReferences child. The optional attribute compartmentType, of type SIdRef, is used for a "not-a-type" compartment to reference a 24 compartment type. A compartment with the "true" value of its isType attribute cannot have the compartmentType 25 attribute defined. ListOfCompartmentReferences is defined in Figure 2 on the preceding page, and is extended from the ListOf class.

2
A listOfCompartmentReferences must have one or more CompartmentReference children. Since ListOfCompart-3 mentReferences is derived from SBase through ListOf, it inherits the sboTerm and metaid attributes, as well as the 4 optional child Notes and Annotation objects. CompartmentReference is defined in Figure 2 on the previous page. It has two optional attributes id and name, and 7 a required attribute compartment. Since CompartmentReference is derived from SBase, it inherits the sboTerm and 8 metaid attributes, as well as the optional child Notes and Annotation objects. The optional id attribute, of type SId, serves to provide a way to identify a compartmentReference. Compartment- 11 Reference also has an optional name attribute of type string.

13
If some or all compartmentReferences within a ListOfCompartmentReferences object reference the same compart-14 ment, those compartmentReferences are required to have their id attributes defined to distinguish them. The required compartment attribute, of type SIdRef, serves to provide a way to reference a Compartment object.

17
Note: 18 A compartmentReference cannot reference a compartment that directly or indirectly contains the compartment-

19
Reference. In other words, circular references are not allowed when constructing compartments and compartment-20 References. In a ListOfCompartmentReferences object, every child compartmentReferences must exclusively reference, directly 24 or indirectly, "not-a-type" compartment which can be of the same compartment type. See the extended Compart-25 ment objects in the example in Section 4.1 on page 36.

26
All compartments referenced by a listOfCompartmentReferences must have the values of their isType attributes 27 the same as that in the parent compartment of the listOfCompartmentReferences. For example, a compartment 28 "A" with isType="true" has a listOfCompartmentReferences referencing two compartments "A1" and "A2". Then, 29 "A1" and "A2" must have isType="true".

31
SpeciesType is defined in Figure 3 on the next page and serves to provide backbone structures for species. Speci-32 esType has one required attribute, id, two optional attributes, name and compartment and four optional ListOf 33 objects, including ListOfSpeciesFeatureTypes, ListOfSpeciesTypeInstances, ListOfInSpeciesTypeBonds and List-34 OfSpeciesTypeComponentIndexes. Since SpeciesType is derived from SBase, it inherits the sboTerm and metaid 35 attributes, as well as the optional child Notes and Annotation objects.

36
The ListOfSpeciesTypeInstances element provides a way to define multicomponents which are instances of other 37 SpeciesType objects.

38
The ListOfSpeciesFeatureTypes element and its SpeciesFeatureType child set up a framework for the referencing 39 species or the instances of speciesTypes to be able to have multistates. The ListOfSpeciesTypeComponent-40 Indexes element provides a way to reference a component in a speciesType. The required id attribute, of type SId, serves to provide a way to identify a speciesType. SpeciesType also has an 3 optional name attribute of type string. SpeciesType has an optional attribute compartment, of type SIdRef, to be used to identify the compartment where 6 the speciesType is located. The attribute value must be the identifier of an existing compartment in the model.

7
If present, it must be consistent with the compartment attributes of the referencing species (see Section 3.14 on 8 page 22) and the compartmentReference attributes of its instances (see Section 3.11.3 on page 16). The example in 9 Section 4.1 on page 36 illustrates how to keep the consistency of this attribute.

11
ListOfSpeciesFeatureTypes is defined in Figure 3, and is extended from the ListOf class. If present, a ListOfSpecies-

12
FeatureTypes object must have one or more SpeciesFeatureType children. Since ListOfSpeciesFeatureTypes is 13 derived from SBase through ListOf, it inherits the sboTerm and metaid attributes, as well as the optional child 14 Notes and Annotation objects.

16
ListOfSpeciesTypeInstances is defined in Figure 3, and is extended from the ListOf class. If present, a ListOfSpeci-17 esTypeInstances object must have one or more SpeciesTypeInstance children. Since ListOfSpeciesTypeInstances 18 is derived from SBase through ListOf, it inherits the sboTerm and metaid attributes, as well as the optional child 19 Notes and Annotation objects.

2
ListOfInSpeciesTypeBonds class is defined in Figure 3 on the previous page, and is extended from the ListOf 3 class. If present, a ListOfInSpeciesTypeBonds object must have one or more InSpeciesTypeBond children. Since 4 ListOfInSpeciesTypeBonds is derived from SBase through ListOf, it inherits the sboTerm and metaid attributes, as 5 well as the optional child Notes and Annotation objects. ListOfSpeciesTypeComponentIndexes is defined in Figure 3 on the preceding page, and is extended from the ListOf 8 class. If present, a ListOfSpeciesTypeComponentIndexes object must have one or more SpeciesTypeComponent-9 Index children. Since ListOfSpeciesTypeComponentIndexes is derived from SBase through ListOf, it inherits the 10 sboTerm and metaid attributes, as well as the optional child Notes and Annotation objects.

12
BindingSiteSpeciesType inherits the SpeciesType class and is defined in Figure 3

21
SpeciesFeatureType is defined in Figure 4 on the following page, and serves to provide frameworks or templates to 22 define the referencing SpeciesFeature objects. SpeciesFeatureType has two required attributes id and occur, an 23 optional attribute name, and a required child ListOfPossibleSpeciesFeatureValues element.  The required id attribute, of type SId, serves to provide a way to identify a speciesFeatureType. Its value must be 30 unique within its direct parent speciesType. When a speciesFeatureType is referenced by a speciesFeature, a 31 SpeciesTypeComponentIndex object indexing the containing component can be used to avoid ambiguity.

32
SpeciesFeatureType also has an optional name attribute of type string.  dren. Since ListOfPossibleSpeciesFeatureValues is derived from SBase through ListOf, it inherits the sboTerm and 1 metaid attributes, as well as the optional child Notes and Annotation objects. PossibleSpeciesFeatureValue is defined in Figure 4, and is used to define the possible values a speciesFeature 4 can take. It has a required attribute id and two optional attributes name and numericValue. Since PossibleSpecies-5 FeatureValue is derived from SBase, it inherits the sboTerm and metaid attributes, as well as the optional child 6 Notes and Annotation objects. The required id attribute, of type SId, serves to provide a way to identify a possibleSpeciesFeatureValue. 9 If the id of a possibleSpeciesFeatureValue is the content of a ci element in a MathML expression, it can either 10 represent the numericValue ( when the ci has representationType="numericValue") or the count of the feature 11 instances (default) which have this value.

12
PossibleSpeciesFeatureValue also has an optional name attribute of type string.   SpeciesTypeInstance serves to provide a way to construct speciesTypes and species with multiple components.

2
A speciesType can contain a list of instances of other speciesTypes which can also have their own species-3 TypeInstances, so a speciesType has a tree structure. A speciesType cannot contain an instance of any other 4 speciesType that already contains an instance of it. In other words, circular references are not allowed when 5 constructing speciesTypes. For example, if a speciesType "A" contains an instance of another speciesType "B", "B" 6 must not contain an instance of "A" anywhere in the complete structure of "B".

7
SpeciesTypeInstance is defined in Figure 5. It has two required attributes, id, and speciesType, and two optional 8 attributes name and compartmentReference. Since SpeciesTypeInstance is derived from SBase, it inherits the 9 sboTerm and metaid attributes, as well as the optional child Notes and Annotation objects. The required attribute id , of type SId, serves to provide a way to identify a speciesTypeInstance. Its value must 12 be unique within its direct parent speciesType.

13
SpeciesTypeInstance also has an optional name attribute of type string. 14 3.11.2 The speciesType attribute 15 The required attribute speciesType, of type SIdRef, is used to reference a speciesType. The optional attribute compartmentReference, of type SIdRef, can be used to indicate which sub-compartment 18 in a composite compartment the speciesTypeInstance is located in.

18
SpeciesTypeComponentIndex is defined in Figure 6. It has two required attributes, id, and component, and two 19 optional attributes name and identifyingParent. Since SpeciesTypeComponentIndex is derived from SBase, it 20 inherits the sboTerm and metaid attributes, as well as the optional child Notes and Annotation objects.  The id attribute, of type SId, provides a way to identify a speciesTypeComponentIndex. The value must be unique 28 within the direct parent speciesType. SpeciesTypeComponentIndex also has an optional name attribute of type 29 string. The component attribute, of type of SIdRef, references a speciesTypeInstance in the speciesType, or the 32 speciesType itself. The value of this attribute can be the id of a speciesTypeInstance or a speciesType-

20
In many cases, to reference a component, the id of the referenced component will be sufficient and it is not necessary 21 to create an index (speciesTypeComponentIndex). The example in Section 3.12.3 on the previous page illustrates 22 two equivalent ways to reference a component, for example, the "B1" component in the "stA" speciesType. The 23 creation of a speciesTypeComponentIndex cannot be avoided when a speciesType (indirectly) has two species-

24
TypeInstances that have the same id.

26
An InSpeciesTypeBond object defines a bond existing within a speciesType. The bond therefore exists in every 27 species that references the speciesType.

28
InSpeciesTypeBond is defined in Figure 7. It has two optional attributes, id and name, and two required attributes, 29 bindingSite1 and bindingSite2. Since InSpeciesTypeBond is derived from SBase, it inherits the sboTerm and 30 metaid attributes, as well as the optional child Notes and Annotation objects.

31
The binding relationship in an inSpeciesTypeBond is one-to-one (see Section 3.8.7 on page 14). The uniqueness 32 of an inSpeciesTypeBond is ensured by the pair of referenced bindingSites. A speciesType cannot have two 33 inSpeciesTypeBonds containing the same pair of bindingSites. The optional id attribute, of type SId, provides a way to identify an inSpeciesTypeBond. If present, the value of 36 the id attribute must be unique within its direct parent speciesType.

37
InSpeciesTypeBond also has an optional name attribute of type string. InSpeciesTypeBond has two required attributes, bindingSite1 and bindingSite2, both of type SIdRef, used to 2 reference a pair of binding sites of the InSpeciesTypeBond object in a speciesType. The referenced identifiers of the 3 binding sites can be the ids of the speciesTypeInstances (binding sites), or the ids of the speciesTypeComponent-4 Indexes indexing the binding sites and the ultimately referenced components must be the BindingSiteSpeciesType 5 objects. Obviously, bindingSite1 and bindingSite2 must not reference the same BindingSiteSpeciesType object. 3.14 Uniqueness of SpeciesType definitions 7 In some special cases, it may be possible to define a speciesType in multiple equivalent ways.

57
It is up to the modeler (parser) to identify whether the two speciesTypes such as those in the example above are 58 identical.

1
A species in SBML Level 3 Core refers to a pool of entities. A species in the Multi package is extended from a pool 2 to a template or pattern to which multiple pools may map to. An extended species can reference a speciesType 3 that provides the backbone for the species such as components (including binding sites) and speciesFeature-4 Types. When referencing a speciesType, a species can be further defined with regard to the binding statuses of 5 its outwardBindingSites and the speciesFeatures. With the options to have variable values selected, such as 6 "either" for the bindingStatus attribute and multiple possibleSpeciesFeatureValues for a speciesFeature, 7 an extended species can work as a template or pattern how species participate in reactions.

8
The extension of the Species class is illustrated in Figure 9. It has a new optional attribute speciesType, and The optional attribute speciesType, of type SIdRef, references a SpeciesType object.

17
ListOfOutwardBindingSites is defined in Figure 9 and is extended from the ListOf class. A listOfOutwardBinding-

18
Sites can only be defined when the speciesType attribute is defined. If present, it must have one or more 19 OutwardBindingSite children. Since ListOfOutwardBindingSites is derived from SBase through ListOf, it inherits 20 the sboTerm and metaid attributes, as well as the optional child Notes and Annotation objects.

22
The listOfOutwardBindingSites of a species is not necessary to list all the outwardBindingSites (the binding 23 sites not involved in any inSpeciesTypeBond) defined by the referenced speciesType. If an outwardBindingSite 1 is not listed in the listOfOutwardBindingSites, the value of its bindingStatus is "either". In other words, the 2 binding site is in a "don't care" state. 3

4
ListOfSpeciesFeatures is defined in Figure 9 on the preceding page and is extended from the ListOf class. A list-

5
OfSpeciesFeatures can only be defined when the speciesType attribute is defined. If present, it must have one 6 or more children. A child can be a SpeciesFeature, or a SubListOfSpeciesFeatures object. implicit speciesFeature having all the listOfPossibleSpeciesFeatureValues and "or" relationships between 12 them. In other words, the implicit speciesFeature has a "don't care" state.

13
Since ListOfSpeciesFeatures is derived from SBase through ListOf, it inherits the sboTerm and metaid attributes, 14 as well as the optional child Notes and Annotation objects. 15 The example at Section 3.18.7 on page 27 illustrates the usage of the ListOfSpeciesFeatures class.

17
OutwardBindingSite is defined in Figure 10. It has two optional attributes, id and name, and two required attributes, 18 bindingStatus and component. A binding site not involved in any InSpeciesTypeBond object in the species-

19
Type referenced by a species is an outwardBindingSite. Since OutwardBindingSite is derived from SBase, it 20 inherits the sboTerm and metaid attributes, as well as the optional child Notes and Annotation objects. The optional id attribute, of type SId, can serve to provide a way to identify an outwardBindingSite. If present, 23 the value must be unique within the species. OutwardBindingSite also has an optional name attribute of type 24 string. The bindingStatus attribute takes a value of type BindingStatus.  There are three scenarios for the component attribute to have its value as an identifier of a SpeciesType, Species-1 TypeInstance, or SpeciesTypeComponentIndex object.

2
(1) When a species references a bindingSiteSpeciesType, the component attribute of its outwardBinding-

3
Site can only have value of the referenced speciesType's id.

4
(2) When a species references a speciesType with a speciesTypeInstance being a binding site (have an 5 id of BindingSiteSpeciesType as its speciesType attribute) and the id of the speciesTypeInstance can 6 identify the binding site within the speciesType (referenced by the species) unambiguously, and therefore, 7 an outwardBindingSite of the species can have its component attribute with value of a speciesType-8 Instance's id. 9 (3) When a species references a speciesType with a speciesTypeInstance being a binding site (directly or   Figure 11 illustrates the usage of the OutwardBindingSite class. Species "sp_x" references speciesType "st_x", 15 which has three speciesTypeInstances "sti_a", "sti_b" and "sti_c". SpeciesTypeInstance "sti_a" has 16 bindingSites "_1" and "_3", speciesTypeInstance "sti_b" has bindingSites "_2" and "_4", and speciesType-

23
SubListOfSpeciesFeatures is defined in Figure 9 on page 22, and is extended from the ListOf class. A SubListOf-

24
SpeciesFeatures object must have two or more SpeciesFeature children. Since SubListOfSpeciesFeatures is de-25 rived from SBase through ListOf, it inherits the sboTerm and metaid attributes, as well as the optional child Notes 26 and Annotation objects. The optional id attribute, of type SId, can serve to provide a way to identify a SubListOfSpeciesFeatures object.

29
If present, its value must be unique within the species. SubListOfSpeciesFeatures also has an optional name 30 attribute of type string.  SpeciesFeatures cannot be identified only based on its speciesFeatureType attribute. The optional id attribute, of type SId, can serve to provide a way to identify a speciesFeature. If present, the 2 value must be unique within the species. SpeciesFeature also has an optional name attribute of type string. SpeciesFeature has a required attribute speciesFeatureType, of type SIdRef, used to reference a speciesFeature-5 Type.  The value of the occur attribute cannot be larger than the occur of the referenced speciesFeatureType. When a 10 speciesFeatureType has multiple instances (speciesFeatureType's occur > "1"), the speciesFeature's occur 11 attribute provides a way for a species to define the instances of the speciesFeatureType differently.

16
If the occur of a speciesFeature is less than the occur of the referenced speciesFeatureType, the rest of the un-17 specified instances of the speciesFeatureType are in don't care state which means that the value of an unspecified 18 instance can be any from the listOfPossibleSpeciesFeatureValues.

19
For example, in a speciesType, a speciesFeatureType "phosphorylation" has two possibleSpeciesFeature-20 Values "phosphorylated" and "unphosphorylated" and the occur is "5". A species referencing the speciesType 21 can be defined to have a speciesFeature of the "phosphorylation" with the value of "phosphorylated" and 22 the occur of "1". Then, the species is a pattern species with at least one "phosphorylated" site (the other four 23 "phosphorylation" sites are in don't care state). This pattern species can be mapped by anyone of the fully defined 24 species (see Section 3.19 on page 29) of the same type and with any of "1" to "5" phosphorylated sites. ListOfSpeciesFeatureValues is defined in Figure 12 on the preceding page, and is extended from the ListOf class.

24
■ Each speciesFeature occurrence can only have one speciesFeatureValue, and every occurrence of every 25 speciesFeatureType of every component of the referenced speciesType must be referenced by exactly one 26 speciesFeature occurrence.

27
■ Only "and" values are allowed for the relation attributes of the SubListOfSpeciesFeatures objects.

28
■ Only one single SpeciesFeatureValue object is allowed for any speciesFeature.

29
■ The referenced compartment cannot be a compartment type, which means the value of the isType attribute 30 of the referenced compartment can only be "false". 31 The mapping from a fully defined species to a pattern species is implicit and can be inferred from the structure 32 of the species. For example, a speciesType "stA" has one speciesFeatureType with two possibleSpecies-33 FeatureValues "v1" and "v2". The species "spA1" references "stA" and has the speciesFeature with the value 34 of "v1". Another species "spA" also references "stA" and has no speciesFeature explicitly defined. Thus, the 35 species "spA1" is a fully defined species and can map to the pattern species "spA" because species "spA" 36 has an implicit speciesFeature which can take either value "v1" or value "v2" (see the note in Section 3.15.3 on 37 page 23). SpeciesReference and SpeciesReference are extended to handle some requirements specific to the Multi package.

43
A new class, IntraSpeciesReaction, is derived from Reaction to explicitly define those reactions within the same 44 Species object.

45
The changes under the Reaction class in the Multi package are illustrated in Figure 14 on the following page. ("unbound").

12
SpeciesTypeComponentMapInProduct is defined in Figure 16. It has two optional attributes, id and name, and three 13 required attributes, reactant, reactantComponent and productComponent. Since SpeciesTypeComponentMap-14 InProduct is derived from SBase, it inherits the sboTerm and metaid attributes, as well as the optional child Notes 15 and Annotation objects.  The optional id attribute, of type SId, can serve to provide a way to identify a speciesTypeComponentMapIn-

23
Product. If present, the value must be unique within the reaction. SpeciesTypeComponentMapInProduct also 24 has an optional name attribute of type string.      The optional speciesReference attribute, of type SIdRef, can only be used when the content of the ci element is 23 a species id, or when the content of the ci element is a speciesFeature id. The speciesReference attribute 24 can identify which species is referenced in a reaction, and the speciesReference attribute must have a value of 25 a speciesReference id within the same reaction.

26
If the ci content references a species' id, the id represents the concentration or amount of the species.

27
If the ci content references a speciesFeature's id, the id represents the count of the speciesFeature instances 28 with the speciesFeatureValue (also see Section 3.18.1 on page 26).

29
The example in Section 3.22 on page 30 can be further extended with a block of kineticLaw in the reaction to 30 illustrate the use of the speciesReference attribute with a species' id. Two "spA" species are distinguished by the "r1" and "r2" speciesReferences respectively. The optional representationType attribute, of type RepresentationType, can only be used when the content 9 of the ci element is a species' id or a possibleSpeciesFeatureValue's id. The representationType and 10 speciesReference attributes can both be used for the same ci element at the same time.

11
The representationType attribute can only have the value of "sum" when the content of the ci is the id of a numericValue attribute. 18 The following example demonstrates the use of this attribute for "sum" of species concentrations.
19 20 k1*Si/(k2+SUM(Si)) 21 22 In this example, the reactant "Si" is a pattern species which may have multiple fully defined species mapping 23 to it, for example species "S1", "S2", ..., "Sn". "SUM(Si)" is a function to calculate the total concentration of all fully 24 defined species mapping to "Si". The product can be another pattern species "Pi".

7
For species Sn: k1*Sn/(k2 + (S1 + S2 + ... + Sn)) 8 9 3.27 Namespace scoping rules for identifiers 10 In the Multi package, as in SBML Level 3 Version 1 Core, the Model object contains the main components of an 11 SBML model, such as species, compartments and reactions. The package defines new classes within a model and 12 the scope of the identifiers of those new classes should be defined to prevent identifier collisions. In this section, we 13 describe the scoping rules for all of the types and classes defined in Section 3.3 to Section 3.26 on pages 10-33.

23
For convenience and brevity, we use the shorthand "multi:x" to stand for an attribute or element name x in the 24 namespace for the Multi package, using the namespace prefix multi. We use "multi:x" because it is shorter than 25 to write a full explanation everywhere we refer to an attribute or element in the Multi package namespace. The value of the multi:speciesReference attribute on a given ci element must be the iden-

multi-20102
The multi:required attribute on the <sbml> element must be Boolean.

multi-20103
The value of the multi:required attribute on the <sbml> element must be "true". (Refer- The value of the multi:isType attribute of the Compartment object referenced by a Compart-28 mentReference object must be the same as that of the multi:isType attribute of the par- The multi:compartmentType attribute on a Compartment object must not be defined if the 32 value of the multi:isType is "true". (References: Section 3.5.2 on page 11.) 33

multi-20306
There may be at most one ListOfCompartmentReferences container object within a

multi-20805
The value of the multi:speciesType attribute on a given SpeciesTypeInstance object must   The value of the multi:identifyingParent attribute on a given SpeciesTypeComponent-

multi-21104
The value of the multi:bindingSite1 attribute on a given InSpeciesTypeBond object must 17 be the identifier of a SpeciesTypeInstance object or SpeciesTypeComponentIndex which ulti- The multi:bindingSite1 and multi:bindingSite2 attributes must not reference the same   The value of the multi:value attribute on a given SpeciesFeatureValue object must be the The value of the multi:productComponent attribute on a given SpeciesTypeComponentMap- 21 InProduct object must be the identifier of an object of SpeciesTypeInstance, SpeciesType-