The basic structure of an SBML model definition is given in Example 3.1, “ The basic structure of an SBML file used in MesoRD is ”. The leading ?xml tag should alway be included, as the character encoding for SBML is always UTF-8. The outermost enclosing sbml tag should used verbatim in any models used with MesoRD, since MesoRD only supports SBML level 2 version 4. Not all of the features built into SBML are utilised in MesoRD. Similarly, there are some features required by MesoRD which are not provided in SBML. The departures in SBML files for use with MesoRD with respect to standard level 2 version 4 are briefly listed in the section called “ Departures from Standard SBML Level 2 ”.

<?xml version="1.0" encoding="UTF-8"?>
  <sbml xmlns="http://www.sbml.org/sbml/level2/version4" level="2" version="4">
    <model id="My_Model">
      <listOfUnitDefinitions>
        ...
      </listOfUnitDefinitions>

      <listOfCompartments>
        ...
      </listOfCompartments>

      <listOfSpecies>
        ...
      </listOfSpecies>

      <listOfParameters>
        ...
	 
      </listOfParameters>

      <listOfReactions>
        ...
      </listOfReactions>
    </model>
  </sbml>
	

Note that the above outline is a subset of the structures available in SBML. MesoRD does not support Functions, Events, SpeciesTypes, CompartmentTypes, Rules, Initial assignments, or Constraints. Note that none of the components in the skeletal SBML file above, or the structures directly above, are actually mandatory: if there are no parameters in a model, it makes no sense to include an empty listOfParameters. This also means that MesoRD is not breaking any SBML standard by not implementing them. The following sections discuss each part in turn, focusing on where the user has to take special care when writing model definitions for MesoRD.

This section briefly presents the key topics where MesoRD and SBML disagree as far as the format of input files is concerned. It would seem that by introducing these changes, we are breaking the major purpose of SBML: interchangeability. This is entirely true. It is also the reason why we have attempted to make this section as small as possible. On the other hand: if we didn't reinterpret SBML a little, we could not have achieved what we wanted.

Note that in cases where MesoRD requires additional information in form of SBML annotations, these elements are defined in the name space identified by http://www.icm.uu.se. Note also that the URI reference in arguments such as xmlns:MesoRD="http://www.icm.uu.se", is not directly usable; it does not identify an actual, retrievable document or resource on the Internet. It is simply intended to make the name space unique.

SBML gives the user the possibility to define a name for a unit. The defined name can subsequently be used in the expression of quantities in a model. Novel units in SBML are composed of a set of predefined units. These predefined units are listed in [Hucka et al 2008]. A new unitdefinition is constructed as follows: u_new = ({multiplier}*10^{scale} * u)^{exponent}, where u is one of predefined units. Units are constructed through multiplication of unitdefinitions as U = u₁ * ... * u_N, where U is the constructed unit and u_1...N are unitdefinitions. For instance, some of the sample model files included in the distribution define a unit um for micrometre. This unit is then used when defining the geometry of the system.

<listOfUnitDefinitions>
  <unitDefinition id="um">
    <listOfUnits>
      <unit kind="metre" scale="-6"/>
    </listOfUnits>
  </unitDefinition>
</listOfUnitDefinitions>
	  

It may be interesting to know that MesoRD internally only uses basic SI units, as defined in for instance [Physics Handbook]. Any units are converted to products of these units when parsing the SBML. Thus you could for instance define a unit fulmeter as one Joule per Newton, and specify all your lengths in fulmeter in the unit definitions.

In SBML, a compartment is a container of finite size for substances. Note that compartments do not necessarily have to correspond to actual structures inside or outside of a cell ^[7]. It is important to remember that we cannot have a substance without having a unique compartment to contain it. This is the source of some trouble when it comes to species that can cross compartment boundaries. MesoRD's approach to resolve the problem is discussed in the section called “ Species ”. When using a concentration for defining the initial concentration of species, units has to be defined. See the section called “ Species ” for more information

The most important modification of compartments for use in MesoRD compared to their definition in SBML, is that every compartment needs a geometry definition. Exactly how these geometries are defined is discussed in Chapter 4, Constructive Solid Geometry . Suffice it here to say that the model excerpt below will result in ellipsoid spanning two micrometres in the x-direction, and one micrometre in the y- and z-direction respectively.

<listOfCompartments>
  <compartment id="CompartmentOne">
    <annotation>
      <MesoRD:csg xmlns:mesoRD="http://www.icm.uu.se">
        <MesoRD:scale MesoRD:x="2"
                      MesoRD:y="1"
                      MesoRD:z="1">
          <MesoRD:sphere MesoRD:radius="1"
                         MesoRD:units="um"/>
        </MesoRD:scale>
      </MesoRD:csg>
    </annotation>
  </compartment>
</listOfCompartments>
	

For three-dimensional models the computed volume of a subvolume is recorded as global parameter with the id volume_subvolume. For two-dimensional models the computed area of a subarea is recorded as area_subarea. The area or volumes of compartments are recorded as global parameters with the id of the compartment. If one wishes to include these parameters in kinetic rate expressions the correct procedure is to define parameters with the id and name that are the same as the compartment id. The value of a particular parameter is irrelevant. When simulating, MesoRD will replace the value, in litres for volumes and micrometre squared for areas, with the volume or area as computed. The side length of a subvolume and a subarea are stored as size_subvolume and size_subarea, respectively.

The most common problem during early development of MesoRD turned out to be that the geometry of the compartment was empty. It is not very difficult to inadvertently accomplish such a feat. If one for instance were to model a box, the shortest side of which is 10 nanometre, using cubic subvolumes of side length 100 nanometre, the resulting geometry may not contain any subvolumes, even though the specified volume is in fact three dimensional.

SBML defines species as substances or entities that take part in one or more reactions. Clearly, ATP and glucose are species. However, large complexes such as ribosomes fit the SBML definition of species as well. In SBML, species are defined in exactly one compartment. We shall call this compartment the "home compartment" of a species for the remainder of this section. The existence of a unique home compartment leads to problems when we have species that can cross compartment boundaries. The way the problem is solved in MesoRD is that a species that can occur in several compartment is defined several times, once for every compartment in which it can occur. To prevent violation of the uniqueness criteria for SBML ID:s, every definition must have a unique ID. In order to keep track of which species are actually the same, such species must share the same name. One may think that this is extremely redundant. However, the next paragraph explains why it is in fact only very redundant. ^[8]

Another requirement that MesoRD introduces that is absent in SBML is the need for diffusion rate constant. This is accomplished by the species_diffusion annotation. Every species definition must define a rate constant for diffusion from the home compartment into every other compartment, including the diffusion rate within the home compartment itself. Thus we see that this partially offsets the redundancy introduced by having to define the same species several times: it need not be the case the diffusion constant for diffusion from compartment one to compartment two is equal to the diffusion constant from compartment two to compartment one, which could be useful to model active transport. The diffusion rate constant must be defined with a length unit squared per time, and we recommend using centimetres squared per second.

To set the initial number to a fixed value regardless of the compartment size use the initialAmount, and set the hasOnlySubstanceUnits to true. To set the initial concentration of a molecule in a compartment set the hasOnlySubstanceUnits to false and substanceUnits to either mole or item. Finally set the units in the corresponding compartment to a unit that can be reduced to m³ in a three-dimensional model and m² in a two-dimensional model.

The example below defines an hypothetical species A in a two-compartment system. Note that the initial amount in CompartmentOne is given in number of molecules since hasOnlySubstanceUnits="true", but that the initial amount in CompartmentTwo is given as a concentration in units of mole per litre. Furthermore, note that the diffusion constants are different for diffusion within two compartments.

<listOfCompartments>
  <compartment id="CompartmentOne"
               units="litre">
    <annotation>
      <MesoRD:csg xmlns:MesoRD="http://www.icm.uu.se">
        <MesoRD:translation MesoRD:x="0"
                            MesoRD:y="1"
                            MesoRD:z="0"
                            MesoRD:units="um">
          <MesoRD:box MesoRD:x="0.4"
                      MesoRD:y="0.4"
                      MesoRD:z="0.4"
                      MesoRD:units="um"/>
        </MesoRD:translation>
      </MesoRD:csg>
    </annotation>
  </compartment>

  <compartment id="CompartmentTwo" units="litre">
    <annotation>
      <MesoRD:csg xmlns:MesoRD="http://www.icm.uu.se">
        <MesoRD:difference>
          <MesoRD:box MesoRD:x="0.4"
                      MesoRD:y="4.0"
                      MesoRD:z="0.4"
                      MesoRD:units="um">
            <MesoRD:pbc MesoRD:x="false"
                        MesoRD:y="true"
                        MesoRD:z="false"/>
          </MesoRD:box>
          <MesoRD:compartment MesoRD:id="CompartmentOne"/>
        </MesoRD:difference>
      </MesoRD:csg>
    </annotation>
  </compartment>
</listOfCompartments>

<listOfSpecies>
  <species id="A1"
           compartment="CompartmentOne"
           hasOnlySubstanceUnits="true"
           initialAmount="10000"
           name="A"
           substanceUnits="item">
    <annotation>
      <MesoRD:species_diffusion xmlns:MesoRD="http://www.icm.uu.se">
        <MesoRD:diffusion MesoRD:compartment="CompartmentOne"
                          MesoRD:rate="6e-8"
                          MesoRD:units="cm2ps"/>
        <MesoRD:diffusion MesoRD:compartment="CompartmentTwo"
                          MesoRD:rate="6e-8"
                          MesoRD:units="cm2ps"/>
      </MesoRD:speces_diffusion>
    </annotation>
  </species>

  <species id="A2"
           compartment="CompartmentTwo"
           hasOnlySubstanceUnits="false"
           initialConcentration="1e-5"
           name="A"
           substanceUnits="mole">
    <annotation>
      <MesoRD:species_diffusion xmlns:MesoRD="http://www.icm.uu.se">
        <MesoRD:diffusion MesoRD:compartment="CompartmentOne"
                          MesoRD:rate="6e-8"
                          MesoRD:units="cm2ps"/>
        <MesoRD:diffusion MesoRD:compartment="CompartmentTwo"
                          MesoRD:rate="3e-8"
                          MesoRD:units="cm2ps"/>
      </MesoRD:species_diffusion>
    </annotation>
  </species>
<listOfSpecies>
      

Other things to keep in mind when defining species are listed below.

A parameter in SBML associates a quantity with a symbolic name. The symbols may be used in mathematical formula which in turn define kinetic rate laws that control the reactions. Note also that reactions can have local parameters, as well as access to the global ones.

An SBML reaction is a statement describing some transformation, transport or binding process that can change the amount of one or more species. Typically, an SBML reaction represents a chemical reaction which in turn describes how certain reactants are transformed into products. Reactions have associated kinetic rate expressions describing how often they take place.

Note that [Hucka et al 2008] states that reaction rate expressions should be written such that their units evaluate to "per second". This is a little awkward for the type of reactions MesoRD deals with, because doing so would require one to include the reaction volume in the mathematical expression. In MesoRD the reaction volume is identical to the volume of a subvolume, and this quantity in turn is not necessarily part of the model. Therefore, MesoRD allows reaction rates to be specified in molar per second. If a rate expression evaluates in concentration per time MesoRD attempts to transform the rate to in molar per second automatically. If the reaction rate has the per second unit, MesoRD will assume you know what you are doing and apply no transformations. Thus MesoRD has relaxed the SBML specification a little, not restricted it. However, to make thing simple we strongly recommend that your rate expressions evaluates in concentration per time, or you will have problems every time you change the subvolume size.

The example below show the very hypothetical reaction A+B->C , with a reaction-rate constant k.

<reaction id="Reaction1" reversible="false">
  <listOfReactants>
    <speciesReference species="A"/>
    <speciesReference species="B"/>
  </listOfReactants>
  <listOfProducts>
    <speciesReference species="C"/>
  </listOfProducts>
  <kineticLaw>
    <math xmlns="http://www.w3.org/1998/Math/MathML">
      <apply>
        <times/>
          <ci>k</ci>
          <ci>A</ci>
          <ci>B</ci>
      </apply>
    </math>
  </kineticLaw>
</reaction>
	  

    
<listOfReactions>
  <reaction id="Reaction1" reversible="false">
    <listOfReactants>
      <speciesReference species="A"/>
      <speciesReference species="B"/>        
    </listOfReactants>
    <listOfProducts>
      <speciesReference species="C"/>
    </listOfProducts>
    <kineticLaw>
      <math xmlns="http://www.w3.org/1998/Math/MathML">
        <apply>
          <times/>
            <ci>ka</ci>
            <ci>A</ci>
            <ci>B</ci>
        </apply>
      </math>
    </kineticLaw>

    <annotation>
      <MesoRD:microscopicParameters xmlns:MesoRD="http://www.icm.uu.se">
        <MesoRD:associationRateConstant MesoRD:rate="7.5672e9" 
                                        MesoRD:units="pMps"/>
        <MesoRD:reactionRadius MesoRD:size="10" 
                               MesoRD:units="nm"/>
      </MesoRD:microscopicParameters>
    </annotation>
  </reaction>

  <reaction id="Reaction2" reversible="false">
    <listOfReactants>
      <speciesReference species="C"/>
    </listOfReactants>
    <listOfProducts>
      <speciesReference species="A"/>
      <speciesReference species="B"/>
    </listOfProducts>
    <kineticLaw>
      <math xmlns="http://www.w3.org/1998/Math/MathML">
        <apply>
          <times/>
            <ci>kd</ci>
            <ci>C</ci>
        </apply>
      </math>
    </kineticLaw>
  </reaction>
<listOfReactions>
	    

SBML provides events for modelling instantaneous, discontinuous change in a set of variables of any type. Events are triggered by certain conditions. Events are also not supported by MesoRD.

SBML allows the definition of named mathematical functions that may be used throughout the rest of a model. This is a feature MesoRD does not support.

Rules in SBML are mathematical expressions used in combination with any equations derived from the reactions. Rules can be used to establish constraints between variables, define variable values in terms of other variables or define the rate of change of a variable. Rules are not supported at all by MesoRD.