This page will look better in a graphical browser that supports web standards, but is accessible to any browser or internet device.

Served by Samwise.

JSim and SBML (JSim 2.06 and below)

This page is for the current JSim version 2.0 and higher. Click here for the earlier JSim 1.6 version.

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.

Prerequisites:

Contents:

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 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.

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, and compartment. The units of the species are set to 'substance' if the SBML attribute 'hasOnlySubstanceUnits' is true, or if its compartment has spatialDimensions of 0. Otherwise, its units are set 'substance/volume'. Species that are set 'constant=true' in SBML are defined in JSim to not vary over time, and those set 'constant=false' are defined to vary over the 'time' domain. Initial values or formulas for variable species are set using the 'when (time=time.min)' construct.

Any Reaction in SBML becomes a variable in JSim that varies over the 'time' domain with units of 'substance/time'. 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.

All SBML Parameters are defined without units, with those set 'constant=true' defined in JSim to not vary over time, and those set 'constant=false' to vary over the 'time' domain. Like species, any initial values or formulas for variable parameters are set using the 'when (time=time.min)' construct.

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 in 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:

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 "algebraicRule" declarations are processed, but the translator does not yet recognized which variables they solved, so such variables are declared extern (meaning they must be specified by the user at run-time). This leads to a compiler error message that the model is over-specified, naming the algebraicRule equation as the culprit. Until such a time as the translator is improved, this situation can be corrected by the user removing the "extern" declarations in the translated MML for appropriate variables.

SBML rules and equations using the MathML tag <piecewise> without an <otherwise> are not yet supported, and will be ignored by the translator.

All translated MML variables have global scope, posing a potential problem for repeatedly used local SBML variables.

SBML metaunits "substance", "volume", etc are used in declaring MML variables, which is technically correct but gives users suboptimal run-time feedback, since they must refer to the MML source code to check how the metaunits are defined. In the future, metaunits will be removed from MML declarations.

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:

Comments or Questions?

[This page was last modified 06Jul12, 3:13 pm.]

Model development and archiving support at physiome.org 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.