JSim and SBML

Introduction

SBML is an XML based open standard for exchange of computer based mathematical models. JSim imports SBML models by translating them to MML. JSim can also export many MML models to SBML, although this functionality is somewhat limited because MML contains many mathematical constructs that have no corresponding construct in SBML.

JSim currently uses SBML library (libsbml) version: 5.13.0

Prerequisites:

Introductory Survey of MML (required)
Introduction to the JSim GUI (recommended)
Familiarity with SBML (recommended)

Importing SBML Files into JSim

To import an SBML model into JSim, select "Import model file" from the "Add" menu under the JSim GUI's "Project" tab. SBML files have extension .xml or .sbml. (Note that .xml is used by many XML-based files besides SBML, so be sure to pick a real SBML file.) Alternatively, you can load a SBML file via the -f switch on the command line of either jsim or jsbatch.

Note that some SBML features do not yet translate to MML. In this case, warning comments will appear at the beginning of the generated MML.

Push the "Compile" button to compile the model. There is no guarantee that the code will compile successfully since SBML models are subject to the same sorts of formulation errors MML models are. Problems may also occur because JSim's SBML translator is not yet complete. See SBML Import Bugs and Limitations for details.

Batch translation of SBML files to MML may be accomplished as follows:

jsbatch -f somemodel.xml -omml > somemodel.mod

Windows users: If you are receiving errors from JSim concerning libSBML please see Installing JSim under MS Windows: SBML, Antimony, and Matlab.

Exporting SBML Files from JSim

To export SBML from the JSim GUI, compile it, click on the model "Debug" tab and select "View SBML" from the "View" menu. Translated SBML will appear in the text area. If any warnings are generated in the translation, a button "Show N translator warnings" will appear. Clicking this button will display the warnings in the JSim message area (right half of GUI).

To export SBML from the command line, use the "-osbml" switch in jsbatch:

jsbatch -f somemodel.mod -osbml > somemodel.xml
   or
jsbatch -f somemodel.proj -osbml > somemodel.xml

Windows users: If you are receiving errors from JSim concerning libSBML please see Installing JSim under MS Windows: SBML, Antimony, and Matlab.

Project Status

The SBML translator is now quite robust, correctly translating and simulating the 812 models in the SBML test suite with the 'component' tags:

Algebraic rules
Assignment rules
Compartments
CSymbolAvogadro
CSymbolDelay
CSymbolTime
FunctionDefinition
InitialAssignment
Parameter
RateRule
Reaction
Species
StoichiometryMath

and/or the 'test tags':

0D-Compartment
Amount
AssignedConstantStoichiometry
AssignedVariableStoichiometry
BoundaryCondition
Concentration
ConstantSpecies
ConversionFactors
HasOnlySubstanceUnits
InitialValueReassigned
LocalParameters
MultiCompartment
NonConstantCompartment
NonConstantParameter
NonUnityCompartment
NonUnityStoichiometry

But excluding the following tags and concepts:

Events (all tags with 'Event' in them)
FastReaction
The MathML constructs <factorial>, <xor>, <infinity>, <notanumber>, <true>, and <false>
Delay equations that rely on variables changing before the simulation begins.

Overall, JSim correctly translates and simulates 812 cases from the test suite (in all SBML levels and versions), and does not fully simulate or translate the 299 cases with the above elements (mostly events).

SBML Import Technical Details

SBML models are converted to MML with unit conversion off. Any required unit conversion factors must be part the original SBML equations.

The MML variable "time" is used to represent modeling time, regardless of what name or names it may be known as in the original SBML.

The translator creates one variable per species, reaction, parameter, compartment, and named species reference (stoichiometry). If the units of those variables are set (whether explicitly or by default) those units will be translated to their most compact form using nsrunit. If the variable is found to change, it will be defined to vary in the 'time' domain in JSim. Initial values or formulas for these variables are set using the 'when (time=time.min)' construct.

Any Reaction in SBML becomes a variable in JSim that varies over the 'time' domain. Its value is set to equal the 'kinetic law' of the reaction. These reaction variables are then used to construct the ODEs for the species they contain. The rate of change for each species over time (species:time) is set to the sum of the reactions in which it is produced, less the sum of the reactions in which it is consumed, each multiplied by the stoichiometry of that species in that reaction.

When a species is defined to be interpreted as a concentration within the model, the reactions in the model nonetheless define how the species amount changes in time. Therefore, the rates of change for these species are defined as '(species*compartment):time'. The math of this construct works out to properly simulate the model even when the compartment volume is not '1', or if it changes over time.

SBML models may also contain 'assignment rules' (formulas assigned to variables which must be true at all points during the simulation), 'rate rules' (formulas defining directly how an element changes over time) and 'algebraic rules' (formlas which must be true at all points during the simulation, but which may end up being used to determine any of the involved variables). All three are translated directly to JSim, with assignment rules becoming 'variable=formula', rate rules becoming 'variable:time=formula' and algebraic rules becoming 'formula=0'.

Finally, SBML models may define functions, which are translated to JSim on a case-by-case basis. In other words, if SBML defines a function func(x,y) = 2x+3y, and uses it two different times, (func(p, q) and func(z, w)), the translator will expand those two calls individually to 'func.call0' and 'func.call1', which in turn will be defined as '2p+3q' and '2z+3w', respectively.

When translating formulas in any of the above scenarios, delays in SBML equations that define a delay 'd' for a variable 'X' are translated into the JSim form "X(if (time<d) time.min else time-d)"

The translator defines 3 variable properties to provide SBML contextual information. The defined properties are:

sbmlName: the "name" clause from SBML species, parameter, and compartment tags;
sbmlRole: one of "species", "compartment", "parameter", and "rate";
sbmlCompartment: the compartment ID for species variables.

Due to MML keywords and namespace limitations, some SBML variables may be renamed in the MML translation. If so, an appropriate warning message appears at the beginning of the translated MML.

SBML Import Bugs and Limitations

SBML "event" tags are not yet supported. The event will be ignored and the translator will insert a warning message in the resulting MML.

SBML has the concept of a 'fast reaction' (a reaction which goes to completion instantly) which is currently untranslatable to JSim. Translations of models containing reactions of this type will result in a warning message in the MML.

The following MathML elements may appear in SBML models, but are not (yet) translatable to JSim: <factorial>, <xor>, <infinity>, and <notanumber>. Formulas with these elements are not translated to MML at all, with a warning message resulting in the MML.

The MathML constructs <true> and <false> are translated to MML, but the MML parser does not yet recognize them as valid boolean constructs. When the parser is updated, these translated constructs will succeed.

SBML has the concept of 'values that change before the simulation begins' which is currently untranslatable to JSim. Delay equations that rely on this feature will produce unexpected results. Only models that utilize the 'delay' construct in SBML are potentially affected by this limitation.

The mapping from SBML variable name to MML variable name (required due to JSim reserved words and namespace limitations) is theoretically imperfect. For example, SBML models with two distinct id's differing only in an initial underscore (e.g. ADG and _ADG) will not be translated correctly. However, it works for all models in databases so far tested.

SBML Export Technical Details

JSim elements are translated into SBML parameters, rules, and initial assignments. Even if the model was originally SBML, having species and reactions, the current translator does not attempt to reconstruct those species and reactions.

All JSim variables become SBML parameters. If those variables varied over time, the SBML parameter is set 'constant=false', and set 'constant=true' otherwise. If the initial value of the parameter was a double, that double is used as the 'value' of the parameter; otherwise, the formula is used in an initial assignment to that parameter.

Rates of change for variables become SBML 'rate rules' that assign to the variable.

Formulas that define the value for a variable over all time become SBML 'assignment rules' that assign the given formula to the variable.

'Delay equations' in JSim of the form "X(if (time<delay) time.min else time-delay)" or similar are translated to SBML using the csymbol 'delay'.

SBML Export Bugs and Limitations

This following JSim constructs can not be exported to SBML, and you will get a warning message:

Multiple domains. Heuristics are defined to guess which domain should be used for SBML implicit time, but any domains beyond that one, and formulas that include constructs involving multiple domains, will be ignored.
Events. JSim events are conceptually incompatible with SBML events, and are not translated.
Formulas involving rates of change. It is possible to define a rate of change in SBML, but not to then use that in another equation (y = x:t). In JSim, rates of change can even be determined implicitly by their use in such equations. In a future version of the translator, these formulas may be abstracted to separate variables and used intead, but for now, the translator does not attempt to translate these formulas.
Subvariables. It is possible in JSim to define variables of the type X.Y, adding a semantic connection between that variable and 'X'. It is theoretically possible to 'flatten' these types of variables for translation to SBML, but the current translator does not attempt to do so, and any such variables (and formulas that contain those variables) will be ignored.
Partial differential equations. Because SBML does not (yet) allow multiple domains, any attempt to define partial differential equations will be ignored by the translator.
Procedures. JSim constructs that call external functions (blocks of Java or C code, for example) can not be translated to SBML, and are ignored.
State variables. State variables are a part of JSim's event handling, and are not yet translatable to SBML.
Integration. JSim constructs involving integration can not be translated to SBML, and are ignored.

Comments or Questions?

Model development and archiving support at https://www.imagwiki.nibib.nih.gov/physiome provided by the following grants: NIH U01HL122199 Analyzing the Cardiac Power Grid, 09/15/2015 - 05/31/2020, NIH/NIBIB BE08407 Software Integration, JSim and SBW 6/1/09-5/31/13; NIH/NHLBI T15 HL88516-01 Modeling for Heart, Lung and Blood: From Cell to Organ, 4/1/07-3/31/11; NSF BES-0506477 Adaptive Multi-Scale Model Simulation, 8/15/05-7/31/08; NIH/NHLBI R01 HL073598 Core 3: 3D Imaging and Computer Modeling of the Respiratory Tract, 9/1/04-8/31/09; as well as prior support from NIH/NCRR P41 RR01243 Simulation Resource in Circulatory Mass Transport and Exchange, 12/1/1980-11/30/01 and NIH/NIBIB R01 EB001973 JSim: A Simulation Analysis Platform, 3/1/02-2/28/07.