This chapter describes the SBML support of the Systems Biology Extras for SystemModeler.

Introduction

The Systems Biology Markup Language (SBML) is a model representation format for systems biology. SBML is used to describe models of biochemical reaction networks such as cell-signaling pathways, metabolic networks, and regulatory networks. The Systems Biology Extras support import of a large subset of the SBML Level 1 and Level 2 formats, and export to SBML Level 2. The supported SBML subset is described in detail in the next section. As Modelica is a more general modeling language, certain constraints must be fulfilled in order for a Modelica model to be exportable to the SBML format. For more information on these constraints, see the section on SBML export constraints.

SBML Subset

The SBML element subset supported by the SBML importer is specified in this section. No deprecated or removed attributes are supported, no matter in what SBML version the attribute was deprecated or removed. For instance, an attribute deprecated in SBML Level 2, Version 3 is not supported, even if the version of the SBML document is Level 2, Version 1.

Any SBML identifiers and references that are reserved words in Modelica or that are used by the BioChem Modelica library will be given the suffix _sbml if required.

Model

See the table below for a list of supported and unsupported attributes of the SBML Model element.

Attribute	Support	Comments
metaid	no
sboTerm	no
notes	yes
annotation	partial	only RDF annotations are supported
id	yes
name	yes
listOfFunctionDefinitions	yes	see Function Definition
listOfUnitDefinitions	no
listOfCompartmentTypes	no
listOfSpeciesTypes	no
listOfCompartments	yes	see Compartment
listOfSpecies	yes	see Species
listOfParameters	yes	see Parameter
listOfInitialAssignments	no
listOfRules	yes	see Rule
listOfConstraints	no
listOfReactions	yes	see Reaction
listOfEvents	yes	see Event

Function Definition

The table below lists all supported and unsupported attributes of the SBML FunctionDefinition element.

Attribute	Support	Comments
metaid	no
sboTerm	no
notes	yes
annotation	partial	only RDF annotations are supported
id	yes
name	yes
math	partial	the following functions are not supported: xor, arccot, arcsec, arcscs, arcsinh, arccosh, arctanh, arccoth, arcsech, arccsch

Compartment

See the table below for a list of supported and unsupported attributes of the SBML element Compartment.

Attribute	Support	Comments
metaid	no
sboTerm	no
notes	yes
annotation	partial	only RDF annotations are supported
id	yes
name	yes
compartmentType	no
spatialDimensions	partial	the number of spatial dimensions must be three
size	yes
units	no
outside	yes
constant	yes

Species

See the table below for a complete listing of all attributes of the SBML Species element and whether they are supported or not.

Attribute	Support	Comments
metaid	no
sboTerm	no
notes	yes
annotation	partial	only RDF annotations are supported
id	yes
name	yes
speciesType	no
compartment	yes
initialAmount	yes
initialConcentration	yes
hasOnlySubstanceUnits	no
boundaryCondition	yes
charge	no
constant	yes

Parameter

See the table below for a list of supported and unsupported attributes of the SBML Parameter element.

Attribute	Support	Comments
metaid	no
sboTerm	no
notes	no
annotation	no
id	yes
name	yes
value	yes
units	no
constant	yes

Rule

The table below lists all supported and unsupported attributes of the SBML Rule element.

Attribute	Support	Comments
metaid	no
sboTerm	no
notes	no
annotation	no
math	yes
AlgebraicRule	yes
AssignmentRule	yes
RateRule	yes

Reaction

See the table below for a list of supported and unsupported attributes of the SBML element Reaction.

Attribute	Support	Comments
metaid	no
sboTerm	no
notes	yes
annotation	partial	only RDF annotations are supported
reversible	yes
fast	no
listOfReactants	partial	the following functions are not supported in the math attribute of the StoichiometryMath element: xor, arccot, arcsec, arcscs, arcsinh, arccosh, arctanh, arccoth, arcsech, arccsch
listOfProducts	partial	the following functions are not supported in the math attribute of the StoichiometryMath element: xor, arccot, arcsec, arcscs, arcsinh, arccosh, arctanh, arccoth, arcsech, arccsch
listOfModifiers	yes
kineticLaw	partial	Reactions without a kineticLaw element are not supported. The following functions are not supported in the math attribute of the kineticLaw element: xor, arccot, arcsec, arcscs, arcsinh, arccosh, arctanh, arccoth, arcsech, arccsch. The units attribute of the Parameter element is not supported.

Event

See the table below for a complete listing of all attributes of the SBML Event element and whether they are supported or not.

Attribute	Support	Comments
metaid	no
sboTerm	no
notes	no
annotation	no
id	yes
name	yes
trigger	partial	the following functions and symbols are not supported in the math attribute of the Trigger element: xor, arccot, arcsec, arcscs, arcsinh, arccosh, arctanh, arccoth, arcsech, arccsch
delay	no
listOfEventAssignments	partial	the following functions are not supported in the math attribute of the EventAssignment element: xor, arccot, arcsec, arcscs, arcsinh, arccosh, arctanh, arccoth, arcsech, arccsch

SBML Export Constraints

This section describes the constraints that must be fulfilled in order for a Modelica model to be exportable to the SBML format.

Identifiers

Translator Constraints

• The following identifiers are reserved by the BioChem library and must not be used in the exported SBML model: "c", "n", "V".
• The following identifiers are reserved for constants in the BioChem library and Modelica library and must not be used to declare parameters, variables, or functions: "e", "inf", "INF", "pi".

Constants

Translator Constraints

• The following constants are supported: "e", "inf" (or "INF"), "pi", "true", "false".

SBML Constraints

• All identifiers must be legal SBML identifiers, i.e. the first character of the identifier must be a letter ("a", …, "z" or "A", …, "Z") or an underscore ("_"), and all consecutive characters must be a letter, digit ("0", …, "9") or an underscore. See SBML L2/V3 Specification, 3.1.7.
• The identifier of every function, compartment, substance, parameter (and variable), and reaction must be unique across the set of all such identifiers in the exported SBML model. The only exception is local parameter identifiers within a reaction model. Within the definition of a reaction, local parameter identifiers override identical identifiers outside of that reaction. See SBML L2/V3 Specification, 3.3.1.

Compartments

Translator Constraints

• All compartment models must extend one of the models in the BioChem.Compartments package. The main compartment model sets the mainCompartment parameter to true by modifying it in the extends clause.
• The volume of a compartment must be specified by modifying the start parameter (initial value) of the V variable V.start in the extends clause. Initial equations are not supported.
• Arrays of compartments are not supported.

SBML Constraints

• The volume of a compartment must be a numeric value of type Real. Expressions are not supported.

Functions

Translator Constraints

• Custom functions referenced in reaction models and equations must be defined in the same Modelica package as the compartment model containing the reaction or equation.
• References to functions in reaction models and equations must consist of only the function name (besides the list of arguments), i.e. if a BioChem function is referenced, either the specific function or the BioChem.Math package must be imported in the compartment model containing the reaction or equation.
• The body of the function must be defined using a single assignment.
• The arguments of a function call must be numeric values of type Real. Expressions are not supported.

SBML Constraints

• The parameters and return value of custom functions must be of type Real.
• A custom function must not reference parameters or other model quantities outside of itself; values must be passed as arguments to the function.
• Recursive and mutually recursive custom functions are not permitted.

Parameters and Variables

Translator Constraints

• Arrays of parameters or variables are not supported.
• Equations when declaring variables are not supported.
• The value of parameters and the initial value of variables must be specified as a modifier when declaring the parameter or variable. Initial equations are not supported.

SBML Constraints

• Parameters and variables must be of type Real.
• The value of a parameter and the initial value of a variable must be a numeric value of type Real. Expressions are not supported.

Substances

Translator Constraints

• If the concentration and amount of a substance are determined by reactions, either the substance component must be declared as BioChem.Substances.Substance or the substance model must inherit BioChem.Substances.Substance.
• If the concentration and amount of a substance are determined by a compartment equation, either the substance component must be declared as the class BioChem.Substances.SignalSubstance or the substance model must inherit BioChem.Substances.SignalSubstance.
• Declare a substance as BioChem.Substances.BoundarySubstance or create a substance model inheriting BioChem.Substances.BoundarySubstance if the substance's concentration and amount are not determined by a reaction or a compartment equation, i.e. the substance is on the boundary of the reaction system. The concentration or amount of a boundary substance can only be changed by events.
• Arrays of substances are not supported.

SBML Constraints

• If a substance is given an initial concentration, the parameter use must be set to StateVariable.c and all references to the substance must be to its concentration in equations. No references to its amount are allowed.
• If a substance is given an initial amount, the parameter use must be set to StateVariable.n and all references to the substance must be to its amount in equations. No references to its concentration are allowed. In reaction rate formulas, the reference to the amount of a substance must be of the form concentration/volume, as the amount of the substance is not available as a variable in the substance connectors, e.g. s1.c/s1.V for substrate connector 1 of a reaction.
• The initial concentration or initial amount of a substance must be a numeric value of type Real. Expressions are not supported.

Compartment Equations

Translator Constraints

• Compartment equations must be of the form 0=…, <target≥…, or der(<target>)=…, where <target> can be the concentration or the amount of a substance, the volume of a compartment, or a variable.
• Compartment volumes can be referenced in compartment equations directly by referencing the variable V of a compartment. If the compartment to be referenced is located outside the compartment containing the equation, consider moving the equation. If moving the equation is not an option, the compartment volume reference must be of the form <compartment>_V, where <compartment> is the name of the compartment. Use Modelica inner/outer constructs to associate the variable <compartment>_V with the correct value.
• Parameters and variables can be referenced in compartment equations directly. If the parameter or variable to be referenced is located outside the compartment containing the equation, consider moving the equation. If moving the equation is not an option, the parameter or variable reference must consist of the parameter or variable name only. Use Modelica inner/outer constructs to associate the parameter or variable with the correct value.
• The concentration and amount of a substance must be referenced in compartment equations directly. Modelica inner/outer constructs are not supported.

SBML Constraints

• If a substance is given an initial concentration, all references to the substance must be to its concentration in compartment equations. No references to its amount are allowed.
• If a substance is given an initial amount, all references to the substance must be to its amount in compartment equations. No references to its concentration are allowed.

Reactions

Translator Constraints

• Reaction models must inherit one of the BioChem reaction interface models available in BioChem.Interfaces.Reactions in order to define the number of substrates and products of the reaction, and determine if the reaction is reversible or irreversible. Reaction models with one or more modifiers must also inherit one of the reaction interface models available in BioChem.Interfaces.Reactions.Modifiers.
• The reaction rate formula must be described as a single equation of the form rr=… or …=rr in the reaction model.
• Compartment volumes can be referenced in the rate formula by referencing the variable V of a substance involved in the reaction, e.g. s1.V. If no substance involved in the reaction is associated with the compartment in question, the compartment volume reference must be of the form <compartment>_V, where <compartment> is the name of the compartment.
• All substrate, product, and modifier connectors of a reaction component must be connected to a substance. If the reaction has either no substrate or no product, connect the substrate connector or product connector to a substance of type BioChem.Substances.AmbientSubstance.
• Arrays of substrates, products, and modifiers are not supported.
• Arrays of reactions are not supported.

SBML Constraints

• Only substances that are part of a reaction, i.e. substrates, products, and modifiers, may be referenced in the rate formula of the reaction model. See SBML L2/V3 Specification, 4.13.1.
• A reaction must have at least one substrate or product, i.e. both the substrate connector and the product connector must not be connected to a substance of type BioChem.Substances.AmbientSubstance. See SBML L2/V3 Specification, 4.13.1.
• If a substance is given an initial concentration, all references to the substance must be to its concentration in the rate formula. No references to its amount are allowed.
• If a substance is given an initial amount, all references to the substance must be to its amount in the rate formula. No references to its concentration are allowed. The reference to the amount of a substance must be of the form concentration/volume, as the amount of the substance is not available as a variable in the substance connectors, e.g. s1.c/s1.V for substrate connector 1 of a reaction.
• If a stoichiometry is defined for a substrate or product of the reaction, it must not refer to substances that are not substrates, products, or modifiers of the reaction. See SBML L2/V3 Specification, 4.13.3.
• Parameters within a reaction model must be of type Boolean, Integer, or Real.
• Local parameters within a reaction model must not be referenced outside the reaction model.

Compartment when Equations

Translator Constraints

• Compartment equations must be of the form when <condition> then reinit(<variable>, <expression>); end when;. Multiple reinit() statements are allowed within a single when equation.
• Compartment volumes can be referenced in compartment when equations directly by referencing the variable V of a compartment. If the compartment to be referenced is located outside the compartment containing the when equation, consider moving the when equation. If moving the when equation is not an option, the compartment volume reference must be of the form <compartment>_V, where <compartment> is the name of the compartment. Use Modelica inner/outer constructs to associate the variable <compartment>_V with the correct value.
• Parameters and variables can be referenced in compartment when equations directly. If the parameter or variable to be referenced is located outside the compartment containing the when equation, consider moving the equation. If moving the when equation is not an option, the parameter or variable reference must consist of the parameter or variable name only. Use Modelica inner/outer constructs to associate the parameter or variable with the correct value.
• The concentration and amount of a substance must be referenced in compartment when equations directly. Modelica inner/outer constructs are not supported.

SBML Constraints

• If a substance is given an initial concentration, all references to the substance must be to its concentration in compartment equations. No references to its amount are allowed.
• If a substance is given an initial amount, all references to the substance must be to its amount in compartment equations. No references to its concentration are allowed.