Running SBML Models under JSim

This page is for the older JSim version 1.6. Click here for the latest JSim 2.0 version.

Introduction

SBML is an XML based open standard for exchange of computer based mathematical models. JSim currently support importing most CellML models. SBML export support is currently under development.

This page reflects JSim version 1.6.84 and above. See here for information about previous versions.

Prerequisites:

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

Importing SBML Files into JSim

Assuming no tranlation problems, importing SBML into JSim is quite easy. Select "Import model file" from the "Add" menu under the JSim GUI's "Project" tab, which allows you to select a model file to import. 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 level 2 SBML file. Level 1 SBML is not yet supported). Alternatively, you can load a SBML file via the -f switch on the command line of either jsim or jsbatch.

If translation is successful, a new model tab will appear in the project containing the translated MML source code. If the translator has a problem, an appropriate error message will be generated. No partial translation will appear in the event of a translation error.

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

SBML to MML translation on the command line may be accomplished using jsbatch:

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

Translator characteristics

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" represent modeling time, regardless of what name or names it may be known as in the original SBML.

The translator creates up to three variables for an SBML species S: the initial value, amount and concentration. S.init denotes the initial value variable (amount or concentration). If the species SBML declares hasOnlySubstanceUnits=true or the compartment has zero spatial dimension then S will denote the amount and S.cont the concentration, otherwise S will denote the concentration and S.amt the amount. This naming convention allows the MML variable S to always have the same intepretation as the SBML identifier S.

The translator defines 3 variable properties to provide SBML contextual information. These properties will also be used in the planned JSIM export to SBML. The defined properties are:

sbmlName: the "name" clause from SBML species, parameter, and compartment tags;
sbmlRole: one of "speciesInitialAmount", "speciesInitialConcentration", "speciesAmount", "speciesConcentration, "compartment", "parameter", "rate" and "delay" (special variable created for delay function);
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.

Project Status

JSim version 1.6.84 provides a significant upgrade in SBML capabilities. However, support is not yet perfect as we would like. The test base consists of 4 model suites from the SBML models page . Most models in each set compile and run successfully. Those that don't use SBML features described in the the Bugs and Limitations section below. The accuracy of the resulting computational results has not yet been closely scrutinized.

The following results for each model suite are valid as of 19 Aug 2008:

test-suite version 1.3: a suite of 10 basic tests of SBML functionality. All models compile successfully under JSim. One model contains unsupported SBML events.
BioModels database: a data resource that allows biologists to store, search and retrieve published mathematical models of biological interests. 171/172 models compile successfully under JSim. 46 models contain upsupported SBML events.
JWS database: an archive of published models from JWS online. 61/68 models compile successfully under JSim.
KEGG Models: SBML versions of over 12,000 models from the Kyoto Encyclopedia of Genes and Genomes . All of these models compile successfully under JSim.
See the JSim Models Page for access to the various archives

Bugs and Limitations (as of 19 Aug 2008)

Only level-2 SBML models are supported.

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

SBML function definitions are supported only if they are not nested. That is, no function is defined in terms of another function.

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.

Multiple "assignmentRule" declarations for a single variable are not supported. This is because JSim treats equations as logical constraints, while SBML treats assignmentRules as user-ordered calculations. This semantic gap may potentially be problematic down the road and will bear closer scrutiny in the future. The following procedural calculations are legal in SBML (as assignmentRules), but can't yet be translated into corresponding MML:

      a <= Time
      b <= 2*a
      a <= b + 1

SBML rules and equations using the following MathML tags are not yet supported, and will cause the translator to abort:

      <partialdiff>
      <import>
      <sum>
      <domainofapplication>
      <lowlimit>
      <uplimit>
      <piecewise> without <otherwise>

The mapping from SBML variable name to MML variable name (required due to JSim reserved words and namespace limitations) is theoretically imperfect. However, it is works for all models in databases so far tested.

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.

Due to bug the JigCell SBML toolkit JSim uses, SBML models with an two distinct id's differing only in an initial underscore (e.g. ADG and _ADG) will not be translated correctly.

The JSim GUI does not deal well with very long variable names, such as those used in the KEGG model archive.

[This page was last modified 02Feb11, 3:22 pm.]

Model development and archiving support at physiome.org provided by the following grants: 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.

Running SBML Models under JSim

Introduction

Contents:

Importing SBML Files into JSim

Translator characteristics

Project Status

Bugs and Limitations (as of 19 Aug 2008)