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

-->

Running SBML Models under JSim

Introduction

SBML is an XML based open standard for exchange of computer based mathematical models. JSim (versions 1.6.65 and above) currently support importing most CellML models. Extended import and export support is currently under development.

Prerequisites:

Contents:

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

Project Status

JSim's SBML translator is far from complete and should be viewed as a first stage toward a complete and robust translator. The test base consists of 3 model suites from the SBML models page . Most models in each set compile 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 1 May 2006:

Further details and live demos of the BioModels and KEGG model suites may be found on the JSim SBML Models Page .

Bugs and Limitations (as of 1 May 2006)

Only level-2 SBML models are supported.

SBML "event" and "functionDefinition" tags are not yet supported. Presence of these tags will cause the SBML -> MML translator to abort.

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>
      <degree>
      <import>
      <sum>
      <domainofapplication>
      <lowlimit>
      <uplimit>
      <piecewise> without <otherwise>

SBML unit and variable names are translated "as is" into MML, with the exception of removing leading underscores, which are illegal in MML. No provision is made for collision avoidance with JSim reserved words or predefined NSR units. All translated MML variables have global scope, posing a potential problem for repeatedly used local SBML variables.

SBML models are converted to MML with unit conversion off. This appears to be correct by my reading of the SBML specificiation. If you believe I'm mistaken please let me know. Unit conversion off requires equations include any required unit conversions. This is not currently being done, meaning that, for example, reactions with some species in micromoles and others in picomoles may not compute correctly. This subject needs further research.

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 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 03Mar08, 3:11 pm.]

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