SBML level 3 package: spatial processes, version 1, release 1

Abstract While many biological processes can be modeled by abstracting away the space in which those processes occur, some modeling (particularly at the cellular level) requires space itself to be modeled, with processes happening not in well-mixed compartments, but spatially-defined compartments. The SBML Level 3 Core specification does not include an explicit mechanism to encode geometries and spatial processes in a model, but it does provide a mechanism for SBML packages to extend the Core specification and add additional syntactic constructs. The SBML Spatial Processes package for SBML Level 3 adds the necessary features to allow models to encode geometries and other spatial information about the elements and processes it describes.


Introduction 1
There is no better test of our understanding of a biological system than to create a mechanistic model of that system 2 and show that it possesses all known properties of the system -i.e., that it is consistent with all measurements or 3 observations of the system in hand. However, the creation of such models is even more useful when a system is not 4 already understood, because the model may suggest mechanisms by which known behaviors are accomplished, or 5 predict behaviors not previously expected. Extensive work has been done on the creation of methods for simulating 6 biochemical systems (Andrews and Bray, 2004;Blinov et al., 2004;Hoops et al., 2006;Loew and Schaff, 2001;Stiles 7 et al., 1998;Tomita et al., 1999), including the development of languages, such as the Systems Biology Markup 8 Language (SBML), for saving and exchanging the definition of the system being simulated and the simulation 9 parameters used (Hucka et al., 2003;Keating et al., 2020). Historically, most tools for biochemical simulations 10 either did not consider possible spatial relationships or compartmentalization of system components, or used a 11 compartmental modeling approach (Jacquez et al., 1985) in which spatial organization is approximated by a set 12 of compartments (e.g. membrane-bound organelles in a cell) containing well-mixed populations of molecules. 13 However, a growing number of modeling and simulation tools do permit specification of the size, shape and 14 positions of compartments and the initial spatial distributions of components (typically referred to as a 'geometry' 15 definition). While SBML Level 3 Core has explicit support for multi-compartmental modeling, it does not have a 16 standardized mechanism to store or exchange geometries. We address this deficit here through the definition of a 17 package of extensions to SBML termed SBML spatial. 18 Saving geometries in a standardized way is useful to ensure that the definition is complete (which is important when, 19 for example, provided as part of supplementary information for published studies), and to permit comparison of 20 simulations of the same spatial system using different simulation tools, to enable simulations of a new biochemical 21 model using the same geometry as a previous model (or vice versa). Historically, the creation of a geometry 22 has been done (often through painstaking manual work) by the same investigators who defined a biochemical 23 model and performed a simulation. The advent of SBML has permitted a partial division of this labor, by enabling 24 databases of biochemical models, such as the BioModels database (Le Novere et al., 2006;Li et al., 2010;Malik-Sheriff 25 et al., 2020), to be created. Building on this theme, having a mechanism to exchange geometries will enable an 26 open access 'marketplace' in which some investigators focus on the creation of well-characterized geometries 27 (and distribute them through databases or repositories) enabling others to focus on biochemical model creation 28 and/or performance of simulations. These geometries, however, typically need to be more than raw images. To be 29 most broadly useful across different modeling approaches, they need, for example, to define explicit watertight 30 boundaries for cells and intracellular compartments and contain statistically accurate estimates of concentrations 31 of components at various locations. This can be accomplished for individual images by hand segmentation (Loew 32 and Schaff, 2001) or automated segmentation (Perez et al., 2014). An alternative is to produce synthetic geometries 33 that are drawn from generative models of cell shape and organization learned from many images (Zhao and Murphy,34 2007). In both cases, the availability of well-characterized geometries for examples of different cell types (and 35 multiple cells of each type) can enhance the use of simulation methods. 36 Examples of simulations using biochemical models and geometries from different sources have already occurred 37 using a preliminary version of the SBML spatial standard (Donovan et al., 2016;Sullivan et al., 2015). In these, 38 cell geometries created using CellOrganizer and saved using the SBML spatial extension were combined with 39 biochemical models created using BioNetGen and saved in SBML. 40 Additionally, properties of molecules or reactions may vary spatially, and rates of transport between locations need 41 to be specified. 42 In summary, the purpose of this SBML Level 3 extension is to meet the needs identified above by defining standard-43 ized ways of representing geometries, spatial mappings of species and reactions, and explicit species transport. 44 1 This specification for Spatial in SBML Level 3 Version 1 is available at the following URL: 2 https://github.com/sbmlteam/sbml-specifications/tree/release/sbml-level-3/version-1/spatial/specification 3 The Package Working Group for the Spatial package is coordinated on the mailing list https://lists.sour 4 ceforge.net/lists/listinfo/sbml-spatial. More information about the spatial package is available at 5 http://sbml.org/Documents/Specifications/SBML_Level_3/Packages/spatial. 6

Package dependencies 7
The Spatial package has no dependencies on other SBML Level 3 packages. 8 9 UML 1.0 (Unified Modeling Language; Eriksson and Penker 1998;Oestereich 1999) notation is used in this document 10 to define the constructs provided by this package. Colors in the diagrams carry the following additional information 11 for the benefit of those viewing the document on media that can display color:

12
Black: Items colored black in the UML diagrams are components taken unchanged from their definition in 13 the SBML Level 3 Core specification document.
14 Green: Items colored green are components that exist in SBML Level 3 Core, but are extended by this package. 15 Class boxes are also drawn with dashed lines to further distinguish them. 16 Blue: Items colored blue are new components introduced in this package specification. They have no 17 equivalent in the SBML Level 3 Core specification. 18 Red lines: Classes with red lines in the corner are fully defined in a different figure. 19 The following typographical conventions distinguish the names of objects and data types from other entities; these 20 conventions are identical to the conventions used in the SBML Level 3 Core specification document: 21 AbstractClass: Abstract classes are never instantiated directly, but rather serve as parents of other classes. Their 22 names begin with a capital letter and they are printed in a slanted, bold, sans-serif typeface. In electronic 23 document formats, the class names defined within this document are also hyperlinked to their definitions; 24 clicking on these items will, given appropriate software, switch the view to the section in this document 25 containing the definition of that class. (However, for classes that are unchanged from their definitions in 26 SBML Level 3 Core, the class names are not hyperlinked because they are not defined within this document.) 27 Class: Names of ordinary (concrete) classes begin with a capital letter and are printed in an upright, bold, sans-serif 28 typeface. In electronic document formats, the class names are also hyperlinked to their definitions in this 29 specification document. (However, as in the previous case, class names are not hyperlinked if they are for 30 classes that are unchanged from their definitions in the SBML Level 3 Core specification.) 31 SomeThing, otherThing: Attributes of classes, data type names, literal XML, and tokens other than SBML class 32 names, are printed in an upright typewriter typeface. 33 [elementName]: In some cases, an element may contain a child of any class inheriting from an abstract base class. 34 In this case, the name of the element is indicated by giving the abstract base class name in brackets, meaning 35 that the actual name of the element is the de-capitalized form of whichever subclass is used. 36 For other matters involving the use of UML and XML, this document follows the conventions used in the SBML 37 Level 3 Core specification document. There is no standard way of specifying spatial models in SBML short of introducing an explicit spatial discretization 3 in the form of a large number of compartments with duplicate species and reaction information, with additional 4 reactions for coupling due to transport. This approach hard-codes the numerical methods and discretization 5 schema which destroys portability and is not practical beyond a few compartments. Tools have been forced to resort 6 to proprietary extensions (e.g. MesoRD custom annotations) to encode geometry. 7 2.2 Past work on this problem or similar topics 8 There are many standards for the exchange of geometric information of engineered parts in Computer Aided Design 9 and Manufacturing. These formats are designed for geometric shapes which are directly specified by a designer 10 rather than the data driven, freeform biological structures encountered in cell biology. 11 There also exist standards for the representation of unstructured computational meshes that can encode these 12 freeform biological structures more readily. However, it is important to note that while a computational mesh 13 necessarily encodes an approximation to the shapes of geometric objects, the particular form will be algorithm 14 dependent. 15 To ensure model interoperability, we must encode the geometric shapes in a way that is independent of the 16 numerical methods and even the mathematical framework. The representation of a spatial model within SBML 17 should be largely invariant of the particular encoding of the geometry definition within that model. For example, a 18 spatial model represented in SBML that encodes geometry as a set of geometric primitives (e.g. spheres, cylinders) 19 should be easily portable to a tool that only supports polygonal surface tessellation. It is expected that a geometry 20 translation library will be very useful for interoperability the same way that libSBML greatly improved model 21 interchange by solving similar implementation problems in a standard way. 22 3 Package syntax and semantics 1 This section contains a definition of the syntax and semantics of the Spatial package for SBML Level 3 Version 1 Core. 2 The Spatial package involves several new object classes, and extends the existing Model, Compartment, Species, 3 Reaction, and Parameter object class. Section 4 on page 46 contains complete examples of using the constructs in 4 SBML models. 5 3.1 Overview of spatial extension 6 The SBML Compartment, Reaction and Species, and molecular transport mechanisms (DiffusionCoefficient, Advec-7 tionCoefficient, BoundaryCondition) are mapped to geometric domains to describe spatial models within SBML. 8 The primary mechanism to accomplish this mapping is to simply map Compartments to collections of geometric 9 Domains called DomainTypes. Each Domain is a contiguous patch of volumetric space or a contiguous surface 10 patch that is ultimately described by a single system of equations (whichever mathematical framework is used). 11 In analogy with initial conditions, the mathematical system defined within a domain often needs a definition 12 of what happens at the domain boundary (e.g. boundary conditions) to complete the specification. Because of 13 this, the boundaries between adjacent domains need to be identified so that appropriate boundary conditions  The Geometry object within a model is completely modular and does not reference the rest of the model, promoting 19 reuse of the same geometry in different models. The geometry separately defines a coordinate system, a list of 20 domain types, a list of domains and their adjacency relationships, and a list of alternate geometric representations.  22 Modeling and simulation tools will each natively support some subset (often just one) of the possible GeometryDefi-23 nitions (analytic, sampled field, constructive solid geometry, parametric, or mixed shapes). Interoperability will be 24 enhanced if tools write as many geometry definitions as they are able. Upon reading the model, a tool will typically 25 choose the most convenient geometry definition, i.e. the one that it natively supports. If a tool does not edit the 26 geometry, it has the ability to preserve the alternate representations during model editing (because the mapping of 27 the model to the geometry is not stored in the geometry). 28 There are two general classes of geometric representation specification: those that explicitly specify surfaces and 29 those that implicitly specify surfaces. For example, a level set is a field where a specific isosurface of the field specifies 30 a geometric surface. A geometry described using constructive solid geometry of geometric primitives (e.g. spheres, 31 cylinders) specifies directly which points are "inside" an object. Alternatively, explicit surface representations 32 explicitly declare the set of points belonging to surfaces (e.g. polygonal tessellations). 33 3.2 Namespace URI and other declarations necessary for using this package 34 Every SBML Level 3 package is identified uniquely by an XML namespace URI. For an SBML document to be able 35 to use a given Level 3 package, it must declare the use of that package by referencing its URI. The following is the 36 namespace URI for this version of the Spatial package for SBML Level 3 Version 1 Core: 37 "http://www.sbml.org/sbml/level3/version1/spatial/version1" 38 In addition, SBML documents using a given package must indicate whether the package can be used to change the 39 mathematical interpretation of a model. This is done using the attribute required on the <sbml> element in the package can change the mathematical meaning of a model. 1 The following fragment illustrates the beginning of a typical SBML model using SBML Level 3 Version 1 Core and 2 this version of the Spatial package: 3 4 <?xml version="1.0" encoding="UTF-8"?> 5 <sbml xmlns="http://www.sbml.org/sbml/level3/version1/core" level="3" version="1" 6 xmlns:spatial="http://www.sbml.org/sbml/level3/version1/spatial/version1" 7 spatial:required="true"> 8 9 3.3 Primitive data types 10 The Spatial package uses a number of the primitive data types described in Section 3.1 of the SBML Level 3 Version 1 11 Core specification, and adds several additional primitive types described below. The type SpId is derived from SId (SBML Level 3 Version 1 Core specification Section 3.1.7) and has identical syntax.

Alternative GeometryDefinitions
14 The SpId type is used as the data type for the identifiers of various objects in the Spatial Processes package. The 15 purpose of having a separate type for such identifiers is to enable the space of possible spatial identifier values to 16 be separated from the space of all other identifier values in SBML. The equality of SpId values is determined by 17 an exact character sequence match; i.e., comparisons of these identifiers must be performed in a case-sensitive 18 manner. All spatial objects with id attributes must have unique values among the other spatial objects in the same 19 Model, but need not be unique among elements in other namespaces, such as the SId core namespace.

21
Type SpIdRef is used for all attributes that refer to identifiers of type SpId. It is derived from SpId, but with the 22 restriction that the value of an attribute having type SpIdRef must match the value of a SpId attribute in the relevant 23 model; in other words, the value of the attribute must be an existing spatial identifier in the referenced model. As 24 with SpId, the equality of SpIdRef values is determined by exact character sequence match; i.e., comparisons of 25 these identifiers must be performed in a case-sensitive manner. The BoundaryConditionKind primitive data type is used in the definition of the BoundaryCondition class. It is 28 derived from type string and its values are restricted to being one of the following possibilities: "Neumann" or 29 "Dirichlet". Attributes of type BoundaryConditionKind cannot take on any other values. The meaning of these 30 values is discussed in the context of the BoundaryCondition class's definition in Section 3.12 on page 16.

32
The CoordinateKind primitive data type is used in the definition of the CoordinateComponent class. It is de- 33 rived from type string and its values are restricted to being one of the following possibilities: "cartesianX", 34 "cartesianY", and "cartesianZ". Attributes of type CoordinateKind cannot take on any other values. The mean- 35 ing of these values is discussed in the context of the CoordinateComponent class's definition in Section 3.15 on 36 page 18. The DataKind primitive data type is used in the definition of the SampledField and ParametricGeometry classes. It is 39 derived from type string and its values are suggested to be limited to the following three options: "uint", "int", or 40 "double". For backwards compatibility, and for space reasons, the values "float", "uint8", "uint16", and "uint32" 41 are also allowed. Attributes of type DataKind cannot take on any other values. The meaning of these values is 42 discussed in the context of the classes' definitions in Section 3.16 on page 20 and Section 3.45 on page 40.

Type DiffusionKind 1
The DiffusionKind primitive data type is used in the definition of the DiffusionCoefficient class. It is derived from 2 type string and its values are restricted to being one of the following possibilities: "isotropic", "anisotropic", 3 and "tensor". Attributes of type DiffusionKind cannot take on any other values. The meaning of these values is 4 discussed in the context of the DiffusionCoefficient class's definition in Section 3.10 on page 15. The CompressionKind primitive data type is used in the definition of the SampledField and ParametricObject classes. 7 It is derived from type string and its values are restricted to being one of the following possibilities: "uncompressed", 8 and "deflated". Attributes of type CompressionKind cannot take on any other values. The meaning of these values 9 is discussed in the context of the classes' definitions in Section 3.46 on page 40, Section 3.47 on page 42, and 10 Section 3.16 on page 20.  The GeometryKind primitive data type is used in the definition of the Geometry class. It is derived from type string 18 and its values are restricted to being the single possibility "cartesian". Other GeometryKind types may be used in  The InterpolationKind primitive data type is used in the definition of the SampledField class. It is derived 23 from type string and its values are restricted to being one of the following possibilities: "nearestNeighbor" and 24 "linear". Attributes of type InterpolationKind cannot take on any other values. The meaning of these values is 25 discussed in the context of the SampledField class's definition in Section 3.16 on page 20. The PolygonKind primitive data type is used in the definition of the ParametricObject class. It is derived from type 28 string and its values are restricted to be the single value "triangle". Other PolygonKind types are held in reserve 29 for future versions of this specification, and may include "quadrilateral". Attributes of type PolygonKind cannot  The PrimitiveKind primitive data type is used in the definition of the CSGPrimitive class. It is derived from type 34 string and its values are restricted to being one of the following possibilities: "sphere", "cube", "cylinder", and 35 "cone", for three-dimensional CSGObject elements, and "circle", and "square", for two-dimensional CSGObject The SetOperation primitive data type is used in the definition of the CSGSetOperator class. It is derived from 2 type string and its values are restricted to being one of the following possibilities: "union", "intersection", and 3 "difference". Attributes of type SetOperation cannot take on any other values. The meaning of these values is 4 discussed in the context of the CSGSetOperator class's definition in Section 3.36 on page 35. The doubleArray primitive data type is a space-delimited list of double values in a single string. The arrayData primitive data type is used in the definition of the SampledField and ParametricObject classes.

The extended Model object 13
The Model object is extended in the spatial package to contain a new Geometry child, as seen in Figure 1. The 14 Geometry element is contained in the Model element in the 'spatial' namespace. In order to specify a spatial 15 geometry, some of the existing SBML elements need to be extended (Compartment, Species, Parameter, and 16 Reaction). These extensions to the SBML elements are discussed in the sections that follow.  18 The Compartment in the SBML core is extended while defining a spatial model. An SBML model with spatial 19 geometry defines domain types (classes of domains that are anatomically and physiologically similar). These 20 domain types need to be mapped to a compartment in the SBML model. Compartments are extended to define 21 CompartmentMappings that map compartments to DomainTypes such that each corresponding DomainType is 22 assigned the same biological and mathematical function. Within SBML L3 Core, the compartment Sid refers to 23 the size of that compartment and is specified by the size attribute or may be set by a rule. For spatial models, the 24 compartment size is calculated as the product of the unit size specified in the compartment mapping and the size 25 of the current domain. The definition for the extension of the Compartment element is shown in Figure 2 on the 26 following page.

27
The Compartment element has an optional CompartmentMapping child which indicates the DomainType to which 28 the Compartment is mapped. If there is no CompartmentMapping for a Compartment in a spatial model, then that 29 Compartment is excluded from the spatial version of the model. In the same way, if a DomainType is not mapped to one or more Compartments, then the corresponding Domains in the geometry have no assigned function.

The CompartmentMapping class 2
Each Compartment in a model that defines a spatial geometry may contain an optional CompartmentMapping. 3 A CompartmentMapping is defined as part of the model rather than part of the geometry so that the geometry is 4 modular and may be readily shared between models and reused. A CompartmentMapping maps a Compartment 5 defined in the model to a DomainType defined in the geometry such that each corresponding DomainType is 6 assigned the same biological and mathematical function described by the set of Compartments that are mapped to 7 that DomainType. 8 This mapping need not be one-to-one. In fact, it is common to map er-lumen, er-membrane, and cytosol to the same 9 cell interior volume or 3D DomainType. The unitSize attribute specifies the relative quantity of each Compartment 10 that is mapped to the DomainType. The id attribute is a mandatory attribute of type SpId that is used to uniquely identify a CompartmentMapping in 13 the model. All identifiers of type SpId must be unique within the Model. The mathematical value of a Compart-14 mentMapping is its unitSize attribute, and can be bound to a Parameter by using a SpatialSymbolReference to the 15 CompartmentMapping id. The optional name attribute is of type string, may be used to add a human-readable 16 label to the object, and has no uniqueness requirements. 17 3.6.2 The domainType attribute 18 The mandatory domainType attribute is of type SpIdRef that indicates a DomainType defined in the Geometry 19 element. The unitSize attribute is of type double and represents the relative size of the Compartment with respect to the 22 size of the Domains to which they are mapped. Thus for any infinitesimal subset of the Domain with size S, there 23 exists an amount of Compartment i of size (S*unitSize i ) for i=1..N compartments mapped to that DomainType. For 24 example, a 3D Compartment (and DomainType) which is mapped to a 3D DomainType has a unitSize which is a 25 volume fraction of dimensionless unit. The total set of all such volume fractions mapped to a particular DomainType 26 will typically sum to one.

27
If the spatialDimensions attribute of the parent Compartment is different than the spatialDimensions attribute 28 of referenced DomainType, the unitSize attribute is a conversion factor between the two. The most common example of this would be a 2D Compartment being mapped to a 3D DomainType, such as an ER-membrane being 1 mapped to a volumetric cell interior. In this case, the unitSize is a surface-to-volume ratio.
2 If connected to a Parameter via a SpatialSymbolReference, an InitialAssignment may override the value of the 3 unitSize attribute. It is theoretically possible to have this value change in time through the use of a Rule or Event, 4 but some (if not all) software tools may not support this setup. If the value is set to change, and the dimensionality 5 of the parent Compartment and referenced DomainType is the same, the other CompartmentMapping elements for 6 the same DomainType will typically change in concert, so that they continue to sum to one. Also note that Species 7 amounts are preserved in SBML, so a changing unitSize may induce a corresponding change in any correlated 8 Species concentration. 9 Any bound Parameter's units should be equivalent to the units of the parent Compartment divided by the units of 10 the referenced DomainType. 11 Here is an example of a Compartment element extended to have spatial information: 12 13 <compartment id="Extracellular" spatialDimensions="3" constant="true"> 14 <spatial:compartmentMapping spatial:id="spatialExtracellular" 15 spatial:domainType="Extracellular" spatial:unitSize="1"/> 16 </compartment> 17 18

The extended Species object 19
The SBML core Species is extended when a spatial geometry is defined in the model with the addition of a single 20 new required boolean "isSpatial" attribute. The extension to the Species element is shown in Figure 3. 3.7.1 The isSpatial attribute 22 The isSpatial attribute is of data type boolean. If it is set to true, the Species is spatially distributed in a possibly 23 nonhomogeneous manner within the Domains of the DomainType of the Compartment in which the Species resides.

24
For continuous deterministic models (described by partial differential equations), a spatial Species will result in a 25 concentration field described by a partial differential equation which incorporates contributions from Reactions, 26 diffusion (DiffusionCoefficient) and advection (AdvectionCoefficient) and are subject to boundary conditions 27 (BoundaryCondition) and initial conditions (InitialAssignment and Rule). All of these quantities can be explicit 28 functions of the spatial coordinates as well as spatial and nonspatial Parameters and Species. 29 For stochastic models, the Species is represented as a collection of particles that are distributed throughout the 30 Domains and are subject to reactions, diffusion and advection. Simulation algorithms either track individual 31 particles (e.g. Particle-based methods) or use spatial discretization to track a large number of well stirred pools (e.g.

32
Next-Subvolume Method). 33 The compartment of any Species set isSpatial = "true" must have a child CompartmentMapping: if it did not, its 34 compartment would not actually be a part of the spatial model. 1 When an SBML model defines a spatial geometry, the SBML core Parameter is used to define the diffusion coefficient, 2 transport velocity (advection) and boundary conditions for species and the coordinate components defined in the 3 Geometry. One Parameter is created for each quantity, by adding a child DiffusionCoefficient, AdvectionCoefficient, 4 or BoundaryCondition. Conversely, some elements defined in the spatial package may need to be referenced by 5 mathematics in core constructs, or even have their value set by core constructs such as InitialAssignment or Rule. 6 These spatial elements can be semantically linked to a Parameter by giving it a child SpatialSymbolReference 7 pointing to that element. 8 A Parameter that has been extended for the Spatial package can have only one of the above listed objects. For 9 example, if a Parameter is extended to represent the diffusion coefficient of a species, the existing attributes of 10 the Parameter (id, name, value, units, constant) are defined according to SBML core specifications, along with a 11 DiffusionCoefficient child that contains the information about the species it represents. Figure 4  The spatialRef attribute of SpatialSymbolReference, is of type SpIdRef and refers to the SpId of any element with 6 mathematical meaning defined in the Geometry of the model. 3.10 The DiffusionCoefficient class 8 When a species in a spatial model has a diffusion rate constant, a Parameter for this diffusion constant is created in 9 the SBML model with a DiffusionCoefficient child, which is used to identify the Species whose diffusion rate the the DiffusionCoefficient will inherit the model units of length 2 /time (typically cm 2 s −1 or um 2 s −1 ).

The extended Parameter object
14 It is possible to define both diffusion and advection for the same Species. The required variable attribute of DiffusionCoefficient is of type SIdRef and is the SId of the Species or Parameter 17 in the model whose diffusion coefficient is being set. The required type attribute of DiffusionCoefficient is of type DiffusionKind and indicates whether the diffusion co-20 efficient is "isotropic" (i.e. applies equally in all dimensions/directions), "anisotropic" (i.e. applies only for a sin-21 gle coordinate), or "tensor" (i.e. applies only for a particular pair of coordinates). Coefficients of type "isotropic" 22 may not have any coordinateReference attributes defined, since diffusion is defined for all axes. Coefficients 23 of type "anisotropic" must define the coordinateReference1 attribute and not the coordinateReference2 24 attribute, and applies in the direction of that axis. Coefficients of type "tensor" must define both the attributes 25 coordinateReference1 and coordinateReference2, defining diffusion in relation to the direction due to a gradi-26 ent in the diagonal term of the diffusion tensor for the two coordinates. In no case may coordinateReference2 be 27 defined but not coordinateReference1.  Tensor diffusion coefficients may not be defined for one-dimensional geometries, as they apply in two dimensions. The AdvectionCoefficient is the extension to Parameter in SBML core that is used to represent transport velocity of a It is possible to define both diffusion and advection for the same Species. The variable attribute of AdvectionCoefficient is of type SIdRef and is the SId of the Species or Parameter in the 22 model whose advection coefficient (transport velocity) is being set. The coordinate is of type CoordinateKind and represents the coordinate component of the velocity. For example, 25 if the Geometry is defined in the Cartesian coordinate system and is 2-dimensional, the species can have velocity 26 terms for both X and Y. If the Parameter represents the transport velocity of the species in the X-coordinate, the 27 coordinate attribute will take a value of "cartesianX", and if it represents the velocity in the Y-coordinate, the 28 attribute will take a value of "cartesianY". Only one AdvectionCoefficient may be defined per Species per valid 29 coordinate.

The BoundaryCondition class 31
A Species in a spatial model that has a diffusion rate or an advection velocity needs to have specified boundary 32 conditions. A boundary condition is either the concentration of the species or the flux density of the species at 33 a boundary. The boundary refers to either an internal membrane boundary or a face of the box defined by the 34 minimum and maximum coordinates of the geometry (the geometries bounding box). 35 When creating a spatial SBML model, species boundary conditions are created as parameters, one for each boundary 36 condition, by adding a child BoundaryCondition that points to the corresponding Species and boundary, depending 37 on the coordinate system. For Cartesian Geometries, there are two boundaries for every axis being modeled. For example, in a 2D cartesian 1 geometry for the external boundaries, there could be up to four parameters or parameter sets created for each 2 spatial Species whose Compartments abut the minimum and maximums of the X and Y axes). 3 For internal boundaries, one may either define a BoundaryCondition for a Species at that boundary, or one may 4 define one or more transport reactions that describe how the physical entities that Species represent are moved 5 (or converted) from one side of the boundary to the other. One may not define both a BoundaryCondition and a 6 Reaction that describes the same phenomenon, as this would result in the equivalent of an overdetermined system, 7 not dissimilar from the reason that the change in a Species may not be defined by both a Reaction and a RateRule. 8 If neither a BoundaryCondition nor a Reaction is defined for a particular Species/boundary pair, the flux of that 9 Species at that boundary is zero.

10
The boundaryCondition attribute on an SBML core Species defines whether it is ("false") or is not ("true") 11 changed by any Reaction it may appear in as a product or reactant. In a spatial context, setting this attribute to "true" 12 additionally means that is will not be changed by advection, diffusion, or (confusingly) any BoundaryCondition.

13
This is because the 'boundary' of a BoundaryCondition refers to a physical boundary, while the 'boundary' of 14 the boundaryCondition attribute refers to the conceptual boundary of the reaction network. As in SBML Core, 15 a Species with a boundaryCondition of "true" may only be changed by a Rule (AssignmentRule, RateRule, or 16 AlgebraicRule).

17
The Parameter's value is set either through the value attribute or an InitialAssignment. If the boundary condition 18 changes in time, it can be set with a Rule or Event. If set, the Parameter unit must be equal to the appropriate unit 19 for its type (see below). Only one BoundaryCondition may be defined per Species per boundary (regardless of type). The variable attribute of BoundaryCondition is of type SIdRef and is the SId of the Species or Parameter in the 22 model whose boundary condition is being set. The type attribute is of type BoundaryConditionKind and indicates the type of boundary condition. The boundary 25 condition types come in two groups: for Neumann boundaries, "Neumann" (the inward normal flux) is used. For 26 Dirichlet boundaries, "Dirichlet" (the value) is used.

27
The unit of the boundary condition is determined by the type, and the unit for density and velocity. For "Dirichlet", 28 the unit would be the unit of concentration. For "Neumann", the unit would be concentration*length/time.  3.12.4 The boundaryDomainType attribute 35 The boundaryDomainType attribute is of type SpIdRef and refers to the SpId of the DomainType of the location of 36 the species whose boundary condition is being defined. A Parameter that is extended with a BoundaryCondition 37 object can only define the coordinateBoundary attribute or the boundaryDomainType attribute, but not both.

Extended Parameter examples 39
As an example, here are four examples of parameters that have been extended with spatial information. These 40 four parameters are extended with the four different possible spatial extensions: the SpatialSymbolReference to Section 3.14 The extended Reaction object allow the model to refer to the spatial id "x" as the SBML core id "x"; a BoundaryCondition to define the boundary 1 condition for "s1_nuc" to be zero; a DiffusionCoefficient to define the diffusion coefficient for "s1_nuc" to be "0.1"; 2 and an AdvectionCoefficient to define the advection coefficient for "s2_nuc" to be "0.13".

28
If a Reaction is defined to be a local (having an isLocal value of "true"), the value of the compartment attribute of 29 the Reaction must be defined. This is because the interpretation of the Reaction is very different if the reaction takes throughout the volume). The first will give you gradients in the solution, while the other will not. 33 If the referenced Species come from multiple compartments, the compartment of the Reaction must be a Compart-34 ment that makes physical sense for the individual Species to meet. CoordinateComponent is the local value of the coordinate, and can be bound to a Parameter by using a SpatialSym-5 bolReference to the CoordinateComponent id. The optional name attribute is of type string, may be used to add a 6 human-readable label to the object, and has no uniqueness requirements.

7
Because a CoordinateComponent represents an entire axis, it is not appropriate (should it be connected to a 8 Parameter via a SpatialSymbolReference) for it to be set via an InitialAssignment or Rule. Rather, it is treated like the 9 SBML core csymbol "time", and can be used as an independent variable in other calculations. The type attibute of type CoordinateKind represents the type of the coordinate component, and may take one of 12 a subset of all possible CoordinateKind values depending on its parent Geometry, as defined in Table 1 on the 13 next page. For Cartesian geometries, one-dimensional geometries must be defined by having a single "cartesianX" 14 CoordinateComponent; two-dimensional geometries must be defined by having exactly two CoordinateComponent 15 children with type values of "cartesianX" and "cartesianY", and three-dimensional geometries must be defined 16 by having exactly three CoordinateComponent children with type values of "cartesianX", "cartesianY", and 17 "cartesianZ". No Geometry may have two CoordinateComponent children with the same type. The unit of a CoordinateComponent is represented by the unit attribute, of type UnitSIdRef. If not specified, the 24 unit of a CoordinateComponent inherits from the lengthUnits attribute of the Model object, and if that in turn is 25 not specified, the CoordinateComponent units cannot be determined.

The SampledField class 9
A SampledField is a sampled scalar field such as an image or samples from a level set. The attributes of SampledField The id attribute identifies a SampledField. It is of type SpId and is a required attribute. The mathematical value 17 of a SampledField is the value and dimensionality of the field itself, and can be bound to a Parameter by using a 18 SpatialSymbolReference to the SampledField id. If used in conjunction with the SBML Level 3 "arrays" package,

19
it can be used and manipulated as if it was an array of the appropriate dimensions, even though its meaning is 20 the value of the field at all points within its borders, not just those at the lattice points. However, even without 21 the use of the "arrays" package, it can be used in SBML Level 3 Version 1 Core MathML to set the value of a 22 spatially-distributed SBML symbol such as a Species or Parameter, such as through an InitialAssignment, Rule, or 23 EventAssignment. The optional name attribute is of type string, may be used to add a human-readable label to the 24 object, and has no uniqueness requirements. 25 The size of the field is assumed to match the axes (the CoordinateComponent children) of the parent Geometry, 26 and is assumed to be regularly spaced in each dimension, but is not required to be spaced the same way in all 27 dimensions. In other words, if the Geometry defines a 10 cm by 10 cm square, and a SampledField is a 10x5 array, the 28 "[0,0]" entry in the array will correspond to the point "0 cm, 0 cm" in the Geometry, and the " [9,4]" entry in the array will correspond to the point "10 cm, 10 cm" in the Geometry. Off-latice points (such as the value at "9 cm, 1 9 cm" in this example) have no direct corresponding value in the SampledField, and are determined according to 2 the interpolationType attribute, defined below. 3 When tied to a SpatialSymbolReference, regardless of its useage, each SampledField still must represent values 4 across the entire Geometry. If used in an InitialAssignment to assign values to a Species that only exists in a particular 5 DomainType within the Geometry, entries in the SampledField that correspond to areas of space not covered by 6 that DomainType will simply be ignored. Those values may be set to zero, or could be used in other contexts. For 7 example, a SampledField could represent 'the concentration of ATP in the Geometry', and one InitialAssignment 8 could be used to apply the field to the species 'ATP in the cytosol' and a second InitialAssignment could be used to 9 apply the same field to the species 'ATP in the nucleus', with different values being examined and used in each case.

10
When used in a SampledFieldGeometry, again, the values of the field are interpolated to all off-lattice points to 11 determine whether or not any arbitrary location within the Geometry is part of a given SampledVolume or not. The required interpolationType attribute is type InterpolationKind. It is used to specify how values at off-14 lattice locations are to be calculated. A value of "nearestNeighbor" means that the nearest lattice point value is to 15 be returned, calculated using the L2 norm (or Euclidean distance). A value of "linear" means that the value to be   3.16.4 The compression attribute 28 The required compression attribute is of type CompressionKind. It is used to specify the compression used when 29 encoding the data, and can have the value "uncompressed" if no compression was used, or "deflated" if the 30 deflation algorithm was used to compress the data. The deflation compression algorithm to be used is gzip, which 31 adds a header to the deflated data. This algorithm is freely available. The version of the data to be compressed is the 32 string version of the values in the array, which may consist of numbers, whitespace, commas, and semicolons. The samplesLength attribute is of type positive int and is required. It represents the array length of the 35 arrayData text child of this node. If uncompressed, this will equal the product of the numSamples* attributes, but 36 if compressed, this will equal the new compressed length of the array, not including any added whitespace. It is 37 included for convenience and validation purposes. The dataType attribute is of type DataKind and is optional. It is used to specify the type of the data being stored, so 40 that the uncompressed data can be stored in an appropriate storage type. The three main value types are "uint" 41 for unsigned integers, "int" for signed integers, and "double" for double-precision floating point values. For 42 backwards compatibility, and for cases where storage space might be an issue, other values may also be used: "float" to indicate single-precision (32-bit) floating point values, and "uint8", "uint16", and "uint32" to indicate 1 8-bit, 16-bit, and 32-bit unsigned integer values, respectively. 3.16.7 The Samples text child 3 The Samples text child of the SampledField is where the data for the SampledField resides. It is of type arrayData, 4 which is defined as whitespace-delimited, possibly-compressed numerical values. Whether or not the data is 5 compressed (and how, if so) is stated with the compression attribute, and the type of numerical values included 6 is stated in the dataType attribute. The total number of entries in the array can be derived from the numSamples 7 attributes, by multiplying them together (if present). A semicolon may be used in uncompressed data to visually 8 distinguish grouped values. 9 The order of data points in the Samples should be the same as the dimensionality of the object, that is, first by the 10 first (x) dimension, then by the second (y) dimension (if present), and then by the third (z) dimension (if present).

11
Thus, the array is indexed such that to access data point (x, y, z), one would look in entry:

The Geometry class 48
A single geometry must be defined within the model if the spatial extension is to be used. Figure 8 on the next page 49 shows the definition of the Geometry element.  The id attribute is of type SpId, uniquely identifies the Geometry element, and is optional. It has no mathematical 2 meaning, and cannot be connected to a Parameter via a SpatialSymbolReference element. The optional name 3 attribute is of type string, may be used to add a human-readable label to the object, and has no uniqueness 4 requirements. 3.17.2 The coordinateSystem attribute 1 The coordinateSystem attribute is a required attribute and is of type GeometryKind. It represents the coordinate 2 system used by the Geometry. A value of "cartesian" indicates that the geometry is a cartesian coordinate system, 3 with the coordinate components corresponding to the x, y, and z components of that system (which could be 1-, 4 2-, or 3-dimensional). This is the only coordinate system defined in this version of the specification-in the future, 5 if necessary, "cylendrical", "spherical", and "polar" may be added as possibilities, along with n-dimensional 6 cartesian modeling, should there be interest in the modeling community to exchange these types of models. The Geometry has listOfCoordinateComponents, listOfDomainTypes, listOfDomains, listOfAdjacentDomains, listOf- 9 GeometryDefinitions, and listOfSampledFields that help define the geometry. The ListOfCoordinateComponents is 10 a list of CoordinateComponent objects, the ListOfDomainTypes is a list of DomainType objects, the ListOfDomains is 11 a list of Domain objects, ListOfAdjacentDomains is a list of AdjacentDomains objects, the ListOfGeometryDefinitions 12 is a list of alternative GeometryDefinitions (ParametricGeometry, CSGeometry, SampledFieldGeometry, Analytic-13 Geometry, and MixedGeometry), and the ListOfSampledFields is a list of SampledField objects. Of these, only the 14 ListOfCoordinateComponents is required, but, if present, none of them may be empty.

15
Note that the children of the ListOfGeometryDefinitions object are not called geometryDefinition but rather 16 take the name of the derived class, decapitalized. Thus, they may be called analyticGeometry, csGeometry, 17 parametricGeometry, sampledFieldGeometry, or mixedGeometry. 18 The ListOfCoordinateComponents is unique in that it defines the dimensions of the Geometry. Thus, every Geometry 19 must have a child ListOfCoordinateComponents with exactly one, two, or three children. When there is one child, 20 it must be of type cartesianX; when there are two, they must be of type cartesianX and cartesianY, and when 21 there are three, they must be of types cartesianX, cartesianY, and cartesianZ.

The Boundary class 23
The minimum and the maximum for a CoordinateComponent represent the bounds in each coordinate. For example, 24 for three dimensional Cartesian coordinate system with x, y, and z coordinates, the minimum and maximum limits 25 for each coordinates define planes orthogonal to each coordinate axis and passing through the minimum or 26 maximum. If max-min is the same for each x,y,z then the bounds on the geometry is a cube. The Boundary 27 class interacts with the BoundaryCondition class, allowing modelers to define how model elements behave at the 28 boundary of the model. For species defined within volumes adjacent to these surfaces, BoundaryCondition elements 29 must be introduced. 30 The minimum limit of a CoordinateComponent is represented by the boundaryMin object and the maximum limit is 31 represented by the boundaryMax object, and apply to CoordinateComponent elements. Both are Boundary objects, 32 and have the following attributes: The id attribute of the Boundary object identifies the object. The attribute is required and is of type SpId. This 35 attribute is used when specifying the BoundaryCondition for a species as an extension of an SBML core Parameter. 36 The mathematical value of a Boundary is its value attribute, and can be bound to a Parameter by using a Spatial-37 SymbolReference to the Boundary id. The units are the same as its parent CoordinateComponent, and are not set 38 separately. The optional name attribute is of type string, may be used to add a human-readable label to the object, 39 and has no uniqueness requirements. The value attribute is of type double. In a boundaryMin object, it represents the minimum limit of the Coordinate-If connected to a Parameter via a SpatialSymbolReference, this value may be overridden by an InitialAssignment. 1 However, the Parameter must be set constant="true", because it may not change over the course of the simulation.  3 In this example, a CoordinateComponent is used to define an X axis that goes from 0 to 10 um. 4 5 <spatial:coordinateComponent spatial:id="x" spatial:type="cartesianX" spatial:unit="um"> 6 <spatial:boundaryMin spatial:id="Xmin" spatial:value="0"/> 7 <spatial:boundaryMax spatial:id="Xmax" spatial:value="10"/> 8 </spatial:coordinateComponent> 9 10 3.19 The DomainType class 11 A DomainType is a class of domains that are identified as being anatomically and physiologically similar. For 12 example, a DomainType "cytosol" may be defined in a Geometry as identifying the structure and function of the cell 13 interior. If there is one cell, then there is one domain, if there are multiple cells, then there are multiple disjoint 14 domains ("cytosol1","cytosol2", etc.) identified with the DomainType "cytosol". CompartmentMappings, defined as 15 an extension to an SBML core Compartment, map compartments to domain types such that each corresponding 16 domain is assigned the same biological and mathematical function. Figure 9 shows the DomainType object.

17
Each SBML Compartment maps to a single DomainType, meaning that the initial condition of each Species in 18 each Compartment will be defined consistently across Domains that map to a given DomainType. If those Species 19 are spatially distributed, they will subsequently evolve independently from each other. However, if modeling two 20 Domains that are similar but whose Species have initial conditions that must be defined in different ways, those 21 Domains should be modeled as separate DomainTypes. 22 id: SpId name: string {use="optional"} spatialDimensions: int DomainType SBase Figure 9: The definition of the DomainType class. One or more instances of DomainType in a ListOfDomainTypes instance can be present in a Geometry object.

The id and name attributes 23
Each DomainType is identified with a id of type SpId. The mathematical value of a CompartmentMapping is the 24 sum of the sizes of all domains associated with this DomainType, and can be bound to a Parameter by using a 25 SpatialSymbolReference to the CompartmentMapping id. The optional name attribute is of type string, may be 26 used to add a human-readable label to the object, and has no uniqueness requirements.

27
As a derived quantity, if connected to a Parameter via a SpatialSymbolReference, this value may not be overridden 28 by an InitialAssignment, nor by the use of a Rule or Event. Its value is always connected to the size of its component  1 The spatialDimensions attribute of the DomainType is of type int and can take on a value of 0, 1, 2, or 3. The 2 spatial dimension is specified for a DomainType, rather than being repeated for each Domain that is represented by 3 the DomainType. 4 The spatialDimensions attribute of a DomainType may be the same dimensionality as the Geometry to which it 5 refers (via the Domain), or may be one less. In the latter case, it is considered to describe the surface of that Geometry 6 in the 3D case, the perimeter of the Geometry in the 2D case, or the end point of the Geometry in the 1D case. Since 7 there is no defined perimeter of a 3D object, it is illegal to have a DomainType with a spatialDimensions of "1" 8 where the corresponding Geometry is three-dimensional. Similarly, there is no end point of a 3D or 2D object, 9 making it illegal to have a DomainType with a spatialDimensions of "0" where the corresponding Geometry is two-10 or three-dimensional. A DomainType may also not have a higher dimensionality than the Geometry.

The id and name attributes 18
A Domain is identified with an id attribute of type SpId. This id may be used within a SpatialSymbolReference 19 object that is extended from an SBML core Parameter and can be used in an expression. The mathematical value of 20 a Domain is the absolute size of that domain as used by the simulator (the meshed size), and can be bound to a 21 Parameter by using a SpatialSymbolReference to the SpatialSymbolReference id. The optional name attribute is of 22 type string, may be used to add a human-readable label to the object, and has no uniqueness requirements.

23
As a derived quantity, if connected to a Parameter via a SpatialSymbolReference, this value may not be overridden by an InitialAssignment, nor by the use of a Rule or Event. Its value is always connected to the size of the corresponding 1 Geometry instead. The units of the Domain are the same as the units of the corresponding DomainType. The domainType attribute refers to the SpId of the DomainType that describes the anatomy and physiology of this 4 domain. The attribute is of type SpIdRef. It is through this association that compartments, and hence the whole 5 SBML model, gets mapped to the individual domains.  This list is optional for a Domain if it is the only Domain defined for its DomainType, but is required otherwise.

20
Each InteriorPoint must define the same number of attributes as there are dimensions of the corresponding Geometry 21 to which it belongs.

22
In the case of surfaces, interior points are sometimes required to make unambiguous identification of multiple 23 surfaces (e.g multiple plasma membranes for multiple cells present in a geometry). Due to roundoff error and finite 24 word lengths, it is difficult to find a three dimensional point that lies on a surface. In this case, the distance from the 25 surface will be used to provide unambiguous identification. approximation. Figure 11 on the next page shows the definition of the AdjacentDomains object. This attribute identifies an AdjacentDomains object. The attribute is of type SpId. It has no mathematical meaning, 33 and cannot be connected to a Parameter via a SpatialSymbolReference element. The optional name attribute is of 34 type string, may be used to add a human-readable label to the object, and has no uniqueness requirements.

3.24.2
The isActive attribute 1 The isActive attribute that is common to all the GeometryDefinition types is used to identify the GeometryDef-2 inition that is considered the active GeometryDefinition for the document. When multiple GeometryDefinition 3 elements define the same underlying geometry, each may set their isActive attribute to "true". At least one 4 GeometryDefinition in a Model must have an isActive attribute of "true", and any other GeometryDefinition that 5 does not describe that same underlying physical geometry must have an isActive value of "false". The AnalyticGeometry is a class of GeometryDefinition where the geometry of each domain is defined by an analytic 8 expression. An AnalyticGeometry is defined as a collection of AnalyticVolumes, one AnalyticVolume for each 9 volumetric domain in the geometry. In this representation, the surfaces are treated as the boundaries between 10 dissimilar AnalyticVolumes. The AnalyticGeometry object contains a ListOfAnalyticVolumes. Figure 13 on the next 11 page shows the definition of the AnalyticGeometry object.

The AnalyticVolume class 13
The AnalyticVolume is used to specify the analytic expression of a domain. The analytic expression for the Analyt-14 icVolume is defined in the Math element. Despite the word 'volume' in the name, an AnalyticVolume may be defined 15 for geometries of any dimension. The only difference is that the Math of an AnalyticVolume for a 3-dimensional 16 geometry will contain references to the three CoordinateComponent axes (i.e. "x", "y", and "z"), but will contain 17 fewer for lower-dimensional geometries. The id attribute uniquely identifies the AnalyticVolume. The attribute is required and is of type SpId. It has no 20 mathematical meaning, and cannot be connected to a Parameter via a SpatialSymbolReference element. The 21 optional name attribute is of type string, may be used to add a human-readable label to the object, and has no 22 uniqueness requirements. The functionType attribute is of type FunctionKind and is currently limited to just "layered" (a possibility for 25 future versions of the specification is to allow the value "R-function"). A "layered" function type implies that the Math child element contains an inequality in the spatial dimensions (e.g. x,y,z) such that evaluation to "true" 1 indicates that the point (x,y,z) is within that shape, and "false" indicates that it is not covered by that shape. The domainType attribute of type SpIdRef is a required attribute. It represents the SpId of the DomainType of the 4 Domain that is represented by this AnalyticVolume. 5 3.26.4 The ordinal attribute 6 The ordinal attribute is of type int, and is required. It is used to represent the order of the AnalyticVolume. The 7 ordinal is useful while reconstructing the geometry in the specific software tool -it represents the order in which 8 the AnalyticVolumes representing geometric domains have to be evaluated. 9 Rather than struggle with the task of preventing overlapping regions of space from different AnalyticVolumes, 10 the AnalyticVolumes are to be considered to be evaluated in the reverse order of their ordinals. In this way, any 11 AnalyticVolumes that have already been processed will cover those with a smaller ordinal, thus resolving any 12 ambiguities and removing the constraint that all AnalyticVolumes be disjoint and cover the entire geometric domain.

13
The AnalyticVolume with ordinal 0 can be the "background" layer (typically the extracellular space).
14 No two AnalyticVolume elements should have the same ordinal value, even if they should not overlap, because 15 some tools may not calculate the geometries to the same level of precision as other tools, and may end up with 16 overlap due to rounding errors, and will still need to resolve the ambiguity for their own purposes. If a software 17 tool discovers two overlapping AnalyticVolume elements with the same ordinal value, it may resolve the situation 18 however it sees fit.

The Math class 1
The Math element is a required element for an AnalyticVolume. The Math element contains a MathML expression 2 that defines the analytic expression for the AnalyticVolume referencing the coordinate components that are specified 3 in the ListOfCoordinateComponents in the Geometry, according to the functionType. 4 3.28 AnalyticGeometry example 5 The following is an example of an analytic geometry, with a single volume described by the formula "8 * (x − 1) 2 + 8 * 6 (y − 1) 2 + 8 * (z − 1) 2 < 1" (the formula for a sphere). 7 8 <spatial:analyticGeometry spatial:id="spatial3d_spheres" spatial:isActive="true"> 9 <spatial:listOfAnalyticVolumes> 10 <spatial:analyticVolume spatial:id="Nucleus1" spatial:functionType="layered" spatial:ordinal="2" 3.29 The SampledFieldGeometry class 25 SampledFieldGeometry is a type of GeometryDefinition that defines a sampled image-based geometry or a geometry 26 based on samples from a level set. SampledFieldGeometry is defined by referencing a SampledField from the ListOf-

27
SampledFields on the Geometry element that specifies the sampled image, together with a a list of SampledVolumes 28 that represent the volumetric domains as sampled image regions. Figure 14 on the following page shows the 29 definition of the SampledFieldGeometry object. It may be used for geometries of any dimension. The sampledField attribute is of type SpIdRef, and must reference a SampledField from the same Geometry. That 32 referenced field is to be used to set up the different spatial areas in the geometry of the Model, according to the 33 SampledVolume child elements.  The id attribute identifies a SampledVolume object. The attribute is of type SpId and is required when specifying a erence element. The optional name attribute is of type string, may be used to add a human-readable label to the 1 object, and has no uniqueness requirements. The required domainType attribute is of type SpIdRef. It is the SpId of the DomainType that represents this class of 4 anatomical features. If there are more than one contiguous regions, then more than one domain will be defined 5 corresponding to each SampledVolume. The optional sampledValue attribute is of type double. It represents the pixel value of a SampledVolume. When 8 used, all pixels with this particular value are to be assigned to this SampledVolume, and no pixel without this value is 9 assigned to the SampledVolume. It is illegal to define a sampledValue attribute for a SampledVolume that also has a 10 minValue and maxValue defined. The optional minValue attribute is of type double. It represents the minimum of the pixel value (sampledValue) 13 range to be assigned to this SampledVolume. If a minValue attribute is defined, a maxValue attribute must also be 14 defined, and the sampledValue attribute must not be defined. Areas in the SampledField with exactly this value are 15 to be included in this SampledVolume. The optional maxValue attribute is of type double. It represents the maximum of the pixel value (sampledValue) 18 range to be assigned to this SampledVolume. If a maxValue attribute is defined, a minValue attribute must also be 19 defined, and the sampledValue attribute must not be defined. Areas in the SampledField with exactly this value are Section 3.31 SampledFieldGeometry example to be excluded from this SampledVolume. 1 Having the minValue be included and the maxValue be excluded allows modelers to define adjacent volumes 2 without ambiguity at the boundaries. One SampledVolume may be defined from 0 to 100, and a second volume 3 defined from 100 to 200, and any location with a SampledField value of exactly 100 is only assigned to the first 4 SampledVolume, and every location with a value close to 100 is included in exactly one SampledVolume. 5 3.31 SampledFieldGeometry example 6 The following is an example of a sampled field geometry with three volumes. The referenced SampledField (defined 7 in Section 3.16 on page 20) is also included (though truncated). 8 9 <spatial:listOfGeometryDefinitions> 10 <spatial:sampledFieldGeometry spatial:isActive="true" spatial:sampledField="imgvals"> 11 <spatial:listOfSampledVolumes> 12 <spatial:sampledVolume spatial:id="Extracellular2" spatial:domainType="Extracellular" 13 spatial:minValue="0" spatial:maxValue="64"/> 14 <spatial:sampledVolume spatial:id="Cytosol2" spatial:domainType="Cytosol2" 15 spatial:minValue="64" spatial:maxValue="192"/> 16 <spatial:sampledVolume spatial:id="Nucleus2" spatial:domainType="Nucleus" 17 spatial:minValue="192" spatial:maxValue="256"/> 18 </spatial:listOfSampledVolumes> 19 </spatial:sampledFieldGeometry> 20 </spatial:listOfGeometryDefinitions> 21 <spatial:listOfSampledFields> 22 <spatial:sampledField spatial:id="imgvals" spatial:dataType="uint8" spatial:numSamples1="51" 23 spatial:numSamples2="59" spatial:numSamples3="23" 24 spatial:interpolationType="linear" spatial:compression="uncompressed"  Figure 15 on the following page 35 shows the definition of the CSGeometry object.

The CSGObject class 37
Each CSGObject is a scene graph representing a particular geometric object using constructed solid geometry. A 38 node in a tree (scene graph) is made up of CSGPrimitives, CSGSetOperators, and CSGTransformations. Note that 39 the CSGPrimitives are always leaves in this tree. The CSGObject is analogous to an AnalyticVolume element in the 40 sense that it is a constructed geometry (from primitives) used to specify a volumetric (3-dimensional) domain.

41
The CSGObject element has three attributes : id, domainType and ordinal. The definition of the CSGObject is 42 completed by defining a CSGNode which is the root of the CSGObject scene graph. The id attribute uniquely identifies the CSGObject element. The attribute is required and is of type SpId. It has 45 no mathematical meaning, and cannot be connected to a Parameter via a SpatialSymbolReference element. The 46 optional name attribute is of type string, may be used to add a human-readable label to the object, and has no 47 uniqueness requirements.

The domainType attribute 1
The domainType attribute is of type SpIdRef and is a required attribute. It is a reference to the id of the DomainType 2 that this CSGObject represents. 3 All InteriorPoints of the corresponding DomainType must be points inside the geometry this CSGObject describes. The ordinal attribute is of type int. It is used to represent the order of the CSGObject. The ordinal is useful 6 while reconstructing the geometry in the specific software tool -it represents the order in which the CSGObjects 7 representing geometric domains have to be placed. 8 No two CSGObject elements should have the same ordinal value, even if they should not overlap, because some 9 tools may not calculate the geometries to the same level of precision as other tools, and may end up with overlap due 10 to rounding errors, and will still need to resolve the ambiguity for their own purposes. If a software tool discovers 11 two overlapping CSGObject elements with the same ordinal value, it may resolve the situation however it sees fit. The child [csgNode] element represents the geometry that is to be linked to the domainType of the CSGObject. Note 14 that the child of the CSGObject element is not called "csgNode" but rather takes the name of the derived class, 15 decapitalized. Thus, a CSGObject may have a csgPrimitive, csgSetOperator, csgTranslation, csgRotation, 16 csgScale, or csgHomogeneousTransformation child. 3.34 The CSGNode class 18 The operators and operands used to construct a constructed solid geometry are generalized as a CSGNode, defined 19 in Figure 16 on the next page as an abstract base class. The classes that inherit from CSGNode can be one of the 20 following: CSGSetOperator, CSGTransformation (operators; itself another abstract base class), or CSGPrimitive 0,1 Figure 16: The definition of the abstract base class CSGNode, and its subclasses CSGPrimitive, and CSGSetOperator. The abstract base class CSGTransformation (also a subclass of CSGNode) is defined in Section 3.38 on the next page.

3.34.1
The id and name attributes 3 The id attribute uniquely identifies the CSGNode element. The attribute is optional and is of type SpId. It has 4 no mathematical meaning, and cannot be connected to a Parameter via a SpatialSymbolReference element. The 5 optional name attribute is of type string, may be used to add a human-readable label to the object, and has no 6 uniqueness requirements.  Table 2 on the following page with a predefined orientation and fitting within the unit cube 10 (+/-1 in x, y, and z) or unit square (+/-1 in x and y). This element has one required attribute : primitiveType of 11 type PrimitiveKind. The primitiveType attribute is a required attribute that is of type PrimitiveKind. It represents one of the prede-14 fined primitive shapes. The meaning and definition of those types is listed in Table 2 on the next page. A cylinder with a base circle of radius 1, centered at (0,0,-1), and top circle of radius 1, centered at (0,0,1). The height is 2. 20 cone 3 A cone with a base circle of radius 1, centered at (0,0,-1), and top vertex at (0,0,1). 21 circle 2 A circle with radius 1, centered at the origin. 22 square 2 A square with sides of length 2, centered at the origin The operationType attribute is of type SetOperation and represents an operation that can be performed on a 14 set of CSGNodes. The possible values that the operationType attribute can take are "union", "intersection", 15 or "difference". The values "union" and "intersection" are n-ary, meaning they are defined for any number 16 of child nodes of this CSGSetOperator. The intersection or union of the empty set (zero children) is defined as 17 the empty set, and the intersection or union of a single child is defined as that child. The union of multiple sets is 18 defined as including any element that appears in any of those component sets, and the intersection of multiple sets 19 is defined as including only those elements that appear in all of the component sets.

20
The value "difference" is binary, meaning that it must have exactly two children. Its meaning is defined according 21 to the complement attributes, below. The complement attributes are of type SpIdRef. If the operationType of the CSGSetOperator has the value 24 "difference", they both must be set to indicate the order in which the complement is to be carried out, and 25 must refer, respectively, to the two csgNode children of this CSGSetOperator. The relative complement of the chil-26 dren (and thus the meaning of this node) is defined as the set of elements in complementB, but not in complementA.

27
If the operationType of the CSGSetOperator is not "difference", neither complement attribute may be set. 28

The ListOfCSGNodes class 29
The ListOfCSGNodes must contain one or more csgNode children that are to be combined according to the set 30 operation of the parent CSGSetOperator. While having a single child is legal, this is semantically equivalent to 31 simply putting that child in the model instead of the CSGSetOperator, and therefore has limited modeling benefit.

32
Note that the children of the ListOfCSGNodes object are not called csgNode but rather take the name of the derived 33 class, decapitalized. Thus, they may be called csgPrimitive, csgSetOperator, csgTranslation, csgRotation, 34 csgScale, or csgHomogeneousTransformation.   The child csgNode element represents the geometry that is to be transformed by the CSGTransformation el-2 ement. Note that this child is not called csgNode but rather takes the name of the derived class, decapital-3 ized. Thus, it may be called csgPrimitive, csgSetOperator, csgTranslation, csgRotation, csgScale, or 4 csgHomogeneousTransformation. 3.39 The CSGTranslation class 6 The CSGTranslation element represents a translation transformation on a CSGNode (a transformation or set 7 operation on one or a set of CSGPrimitives) or a CSGPrimitive along the axes defined in the Geometry. This element 8 has three attributes: The translateX required attribute is of type double. It represents the translation of the CSGNode along the x-axis 11 (the CoordinateComponent with the type of "cartesianX"). The translateY attribute is of type double. It represents the translation of the CSGNode along the y-axis (the 2 CoordinateComponent with the type of "cartesianY"). This attribute must not be defined if no such Coordinate-3 Component is present in the parent Geometry, and is required otherwise. The translateZ attribute is of type double. It represents the translation of the CSGNode along the z-axis (the 6 CoordinateComponent with the type of "cartesianZ"). This attribute must not be defined if no such Coordinate-7 Component is present in the parent Geometry, and is required otherwise.  The rotateAngleInRadians attribute is of type double. It represents the rotation angle of the CSGNode, in radians,

21
along the defined axis. In three-dimensional space, this rotation is defined as counterclockwise from the perspective 22 of the origin, viewing the constructed vector. In two-dimensional space, this rotation is defined the same way, as a 23 counterclockwise rotation along the Z axis emerging from the defined point. From the perspective of the surface of 24 the shape, this view looks down the negative side of the Z axis, appearing as a clockwise rotation. 25 Overall, the rotate attributes define where the rotation is to occur, and the rotateAngleInRadians define how 26 much rotation is to take place. A rotateAngleInRadians value of "0" would therefore define a CSGRotation that 27 left the shape fixed in space.  This element has three attributes: The scaleX required attribute is of type double. It represents the amount of scaling of the CSGNode along the x-axis 38 (the CoordinateComponent with the type of "cartesianX").

The scaleY attribute 1
The scaleY attribute is of type double. It represents the amount of scaling of the CSGNode along the y-axis (the 2 CoordinateComponent with the type of "cartesianY"). This attribute must not be defined if no such Coordinate-3 Component is present in the parent Geometry, and is required otherwise. The scaleZ attribute is of type double. It represents the amount of scaling of the CSGNode along the z-axis (the 6 CoordinateComponent with the type of "cartesianZ"). This attribute must not be defined if no such Coordinate-7 Component is present in the parent Geometry, and is required otherwise. 8 The amount of scaling for all three attributes is relative to the original size of the object. In other words, if a CSGScale 9 object has a scaleX value of "1.0", is it not scaled along the X axis at all, with "0.5" halving it, "2.0" doubling it, and 10 "0.0" making the entire object disappear completely. Negative values produce effective inversions of the object, e.g.

11
inverting a unit cone by giving it a scaleZ scaling factor of "-1".  The TransformationComponent element represents an affine transformation that can be applied to a CSGNode. This 18 element has the following two attributes: The components attribute is of type doubleArray, whose values represent the 4x4 affine transformation matrix.

21
This attribute is required.  The componentsLength attribute is of type int, is required, and must be 16. It represents the array length of the 27 components attribute (number of values in the components array), which must be a 4x4 matrix.

The ParametricGeometry class 23
ParametricGeometry is a type of GeometryDefinition that parametrically defines geometric strucutures/domains.

24
The ParametricGeometry element is defined with a SpatialPoints object and a listOfParametricObjects that is a 25 collection of ParametricObjects. Each point in the SpatialPoints list is given an index, and those indices are used in 26 the creation of each ParametricObject. There may be points whose indices are never used; this does not affect the 27 ParametricGeometry. Figure 18 on the next page shows the definition of the ParametricGeometry object.

The SpatialPoints class 29
The SpatialPoints element represents the set of points to be used as vertices in the ParametricGeometry. In essence, 30 the SpatialPoints defines a lattice on which each ParametricObject is to be drawn. There may be unused points in 31 the list if no ParametricObject ever uses that index to draw its shape. The required compression attribute is of type CompressionKind. It is used to specify the compression used when 34 encoding the data, and can have the value "uncompressed" if no compression was used, or "deflated" if the 35 deflation algorithm was used to compress the data. The deflation compression algorithm to be used is gzip, which 36 adds a header to the deflated data. This algorithm is freely available. The version of the data to be compressed is the 37 string version of the values in the array, which may consist of numbers, whitespace, commas, and semicolons. The arrayDataLength attribute is of type int and is required. It represents the array length of the arrayData text 40 child of this node. If uncompressed, this will equal the total number of coordinates, but if compressed, this will 41 equal the new compressed length of the array, not including any added whitespace. It is included for convenience 42 and validation purposes. The dataType attribute is of type DataKind and is optional. It is used to specify the type of the data being stored, so 45 that the uncompressed data can be stored in an appropriate storage type. The three main value types are "uint" for unsigned integers, "int" for signed integers, and "double" for double-precision floating point values. For 1 backwards compatibility, and for cases where storage space might be an issue, other values may also be used: 2 "float" to indicate single-precision (32-bit) floating point values, and "uint8", "uint16", and "uint32" to indicate  The ArrayData text child of the SpatialPoints is in arrayData format, and represents an ordered list of sets of 6 coordinates that will be used as the vertices of ParametricObject elements in this ParametricGeometry, with "0" 7 representing the first such coordinate, "1" the second, etc. The list will define vertexes with as many values as there 8 are CoordinateComponent children of the parent Geometry: three values for representing the X, Y, and Z coordinates 9 (respectively) of 3-dimensional geometries, or two values for representing the X and Y coordinates (respectively)  Each SpatialPoints is identified with a id of type SpId. A SpatialPoints has no mathematical value. The optional 2 name attribute is of type string, may be used to add a human-readable label to the object, and has no uniqueness 3 requirements. 3.47 The ParametricObject class 5 The ParametricObject element represents a single parametric geometry object. It contains a list of point indices 6 from the parent ParametricGeometry's SpatialPoints, which collectively define the faces of the object. The id attribute is a required attribute of type SpId. It uniquely identifies the ParametricObject element. It has 9 no mathematical meaning, and cannot be connected to a Parameter via a SpatialSymbolReference element. The 10 optional name attribute is of type string, may be used to add a human-readable label to the object, and has no 11 uniqueness requirements.  The domainType attribute is of type SpIdRef and is a required attribute. It is a reference to the id of the DomainType 18 that this ParametricObject represents. The required compression attribute is of type CompressionKind. It is used to specify the compression used when 21 encoding the data, and can have the value "uncompressed" if no compression was used, or "deflated" if the 22 deflation algorithm was used to compress the data. The deflation compression algorithm to be used is gzip, which 23 adds a header to the deflated data. This algorithm is freely available. The version of the data to be compressed is the 24 string version of the values in the array, which may consist of numbers, whitespace, commas, and semicolons.  The dataType attribute is of type DataKind and is optional. It is used to specify the type of the data being stored, so 32 that the uncompressed data can be stored in an appropriate storage type. Because all the data will be indexes into 33 the ArrayData of the SpatialPoints element, "uint" is the suggested value for this attribute (indicating unsigned 34 integer values), with "uint8", "uint16", and "uint32" (indicating 8-bit, 16-bit, and 32-bit unsigned integer values, 35 respectively) also being allowed. No other value is allowed, including the other types of DataKind ("int", "float", 36 and "double"), since the data will never be that type. The PointIndex text child of the ParametricObject is in arrayData format, and represents an ordered list of indices 2 that refer to elements in the SpatialPoints array and are interpreted by considering the polygonType attribute of the 3 ParametricObject with a value of "triangle" indicating that the data is to be grouped in sets of three. The sequence 4 of indices must follow adjacent edges, with an implied edge between the first and last vertex. Additionally, the order 5 of that sequence should be consistently clockwise or counter-clockwise for any contiguous surface. This can be 6 accomplished by ensuring that when an edge is used for two different faces, the order of that edge is reversed for the 7 second face. A semicolon may be used in uncompressed data to visually distinguish grouped values. Each set of 8 indices that define a polygon face should each refer to a different location. This means that one should not re-use 9 index values with a single polygon face, nor should one use two index values in the same face that are mapped to 10 the same location. <parametricObject id="pyramid" polygonType="triangle" domainType="dt1" order, as observed from 'outside' the pyramid. This can be seen, for example, in the last two faces defined, where 30 the shared edge is defined in the order '5 6' in the first face, but '6 5' in the second.

31
A more realistic example can be found below, though most of the values are elided for reasons of space: 32 33 <spatial:parametricGeometry spatial:id="id051101043048054" spatial:isActive="true"> 34 <spatial:spatialPoints spatial:compression="uncompressed" spatial:arrayDataLength="179901"> Here, an array of 179901 values is defined in the SpatialPoints object. Because this is a model with 3D geometry  Because so many values were included, a decision was made to omit the optional ";" characters, which would have 10 principally served to increase the file size. The tokengeometryDefinition attribute is of type SpIdRef, and is required. It must reference a direct child Geome-6 tryDefinition of this MixedGeometry. The ordinal value is then taken to refer to that geometry. The ordinal attribute is of type int, and is required. It is used to represent the order of the corresponding 9 GeometryDefinition within this MixedGeometry. The ordinal is useful while reconstructing the geometry in the 10 specific software tool -it represents the order in which each GeometryDefinition have to be evaluated.

11
Rather than struggle with the task of preventing overlapping regions of space from each different GeometryDefinition, 12 they are to be considered to be evaluated in the reverse order of their ordinals. In this way, any GeometryDefini-13 tion that has already been processed will cover those with a smaller ordinal, thus resolving any ambiguities and 14 removing the constraint that each GeometryDefinition be disjoint and cover the entire geometric domain. The

15
GeometryDefinition with ordinal 0 can be the "background" layer (typically the extracellular space).

16
No two GeometryDefinition elements should have the same ordinal value, even if they should not overlap, because 17 some tools may not calculate the geometries to the same level of precision as other tools, and may end up with 18 overlap due to rounding errors, and will still need to resolve the ambiguity for their own purposes. If a software tool 19 discovers two overlapping GeometryDefinition elements with the same ordinal value, it may resolve the situation 20 however it sees fit.

21
Note that these ordinals only apply at the level of the immediate parent MixedGeometry. Any ordinal attribute  The SBML Spatial package was designed to be orthogonal to other SBML packages, and as such should interact 2 freely with all of them. However, there are no current implementations that take use of these interactions, so the 3 following descriptions should all be taken as guidelines for future development, and do not represent established 4 protocols at this time. 5

SBML Level 3 Version 2 6
This package may be used with either SBML Level 3 Version 1 Core, or SBML Level 3 Version 2 Core, with no essential 7 change in functionality. SBML L3v2 adds an 'id' and 'name' to all constructs, so a few more Spatial elements that  The Hierarchical Model Composition package allows models to be composed hierarchically, with submodels 15 that become part of the containing model, and connections that define how to integrate the submodels into the 16 containing model. Spatial models may be composed in this way just like other SBML constructs, with the caveat 17 that because Spatial ids are in the SpId namespace, and because comp does not come with an element of type 18 SpIdRef, metaids must be used instead.

19
Also, since there may only be a single Geometry object child of the Model, the Geometry of any child submodel 20 must be integrated into the parent model's Geometry: the id, name, and coordinateSystem of the parent remains 21 unchanged, and the children of the Geometry should be merged into the parent Geometry in much the same way 22 that the children of the child Model are merged into the parent Model.

The distrib package 24
The Distributions package allows modelers to include new MathML csymbol constructs that define draws from 25 distributions, and the ability to define the uncertainty in any element with mathematical meaning. Both could 26 be employed as-is by users of the Spatial package: the csymbol constructs can be used in spatial MathML, and 27 in core MathML to affect spatial elements through the SpatialSymbolReference link. Any Spatial element with 28 mathematical meaning could additionally be given an Uncertainty child defining its uncertainty.

5.4
The multi package 30 The Multistate and Multicomponent package allows modelers to define template species and reactions that are only 31 realized upon actually simulating the model. In principle, the extended Species and Reaction objects defined in 32 that package should be able to be placed in a spatial context. 33 The work involved in interpreting and simulating such a model would be substantial, however, and more research 34 needs to be done to identify best practices in using the two packages together. 35

The qual package 36
The Qualitative Models package allows modelers to define interaction networks that are defined by element state 37 instead of element levels. In principle, such state transition modeling could be modeled in a spatially-distinguished 38 context, but no effort has been made to do so at this time. Mechanically, new extensions would have to be created Section 5.6 The layout and render packages to allow the QualitativeSpecies and Transition elements from the qual package to be spatially defined before any 1 such model definitions could be created. 2 5.6 The layout and render packages 3 The Layout Package and the Render Package allow the visualization of SBML models. In principle, both could 4 be used as-is to display the underlying reaction networks being used in a spatial model. However, there are no 5 special constructs available to visualize the geometry defined in the spatial package: simulators typically display this 6 geometry to the user with species levels superimposed, but nothing in layout or render would help the simulator 7 displaying this information. Thus, at present, the Geometry itself is used for visualization of spatial simulations, 8 while layout and render are used separately to visualize the reaction network. This section summarizes all the conditions that must (or in some cases, at least should) be true of an SBML Level 3 3 Version 1 model that uses the Spatial Processes. We use the same conventions as are used in the SBML Level 3 4 Version 1 Core specification document. In particular, there are different degrees of rule strictness. Formally, the 5 differences are expressed in the statement of a rule: either a rule states that a condition must be true, or a rule 6 states that it should be true. Rules of the former kind are strict SBML validation rules-a model encoded in SBML 7 must conform to all of them in order to be considered valid. Rules of the latter kind are consistency rules. To help 8 highlight these differences, we use the following three symbols next to the rule numbers: The validation rules listed in the following subsections are all stated or implied in the rest of this specification 21 document. They are enumerated here for convenience. Unless explicitly stated, all validation rules concern objects 22 and attributes specifically defined in the Spatial Processes package.

23
For convenience and brevity, we use the shorthand "spatial:x" to stand for an attribute or element name x in the ☞ 24 namespace for the Spatial Processes package, using the namespace prefix spatial. In reality, the prefix string may 25 be different from the literal "spatial" used here (and indeed, it can be any valid XML namespace prefix that the 26 modeler or software chooses). We use "spatial:x" because it is shorter than to write a full explanation everywhere 27 we refer to an attribute or element in the Spatial Processes namespace. 28 Attributes from this package are listed in these rules as having the "spatial:" prefix, but as is convention for SBML 29 packages, this prefix is optional.   defined in SBML; that is, the value must be one of the following: "double", "float", "int", 27 "uint", "uint8", "uint16" or "uint32". (Reference: SBML Level 3 Specification for Spatial DataKind defined in SBML; that is, the value must be one of the following: "uint", "uint8",  PrimitiveKind defined in SBML; that is, the value must be one of the following: "sphere", 25 "cube", "cylinder", "cone", "circle" or "square". spatial-23205 ✓ The value of the attribute spatial:operationType of a CSGSetOperator object must con-10 form to the syntax of SBML data type SetOperation and may only take on the allowed values 11 of SetOperation defined in SBML; that is, the value must be one of the following: "union", 12 "intersection", or "difference".  Rules for Geometry object 10 spatial-23701 ✓ A Geometry object may have the optional SBML Level 3 Core attributes metaid and sboTerm.