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.

Cardiac Physiome Society workshop: November 6-9, 2017 , Toronto

Running CellML Models under JSim

This page describes CellML support in JSim version 2.05 and above. See here for infomation on CellML support in JSim version 2.04 and below.

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

Prerequisites:

Contents:

Importing CellML Files into JSim

Assuming no translation problems, importing CellML 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. CellML files have the extension .cellml or .xml. (Note that .xml is used by many XML-based files besides CellML, so be sure to pick a real CellML file). Alternatively, you can load a CellML 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. Errors at this stage are most likely because the model tried to import a component, or used an unsupported MathML tag (see Bugs and Limitations below).

The model will by default have the statement 'unit conversion on' if the models units are consistent. If they are not correct, the model will have the statement 'unit conversion off'. Having unit conversion off means that there are unit errors in the model; these errors can be discovered by turning unit conversion back on and attempting to compile the model.

Now push the "Compile" button to compile the model. Errors at this stage are rare, and were seen in only four unvalidated models in our 1055-model test bed.

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

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

At run-time users should be advised that:

  1. Time stepping parameters are not defined in CellML files, and must be entered by the user.
  2. Many CellML archive models (71 of our 1055-model test bed) do not have valid initial conditions. Initial conditions of '0' are automatically set when the initial conditions are underspecified, and existing initial conditions are suppressed when the initial conditions are overspecified. In both cases, a comment is written indicating what has been changed.

Exporting CellML Files from JSim

To export CellML from the JSim GUI (version 2.06 or greater), compile it, click on the model "Debug" tab and select "View CellML" from the "View" menu. Translated CellML 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 CellML from the command line, use the "-ocellml" switch in jsbatch:

jsbatch -f somemodel.mod -ocellml > somemodel.cellml
   or
jsbatch -f somemodel.proj -ocellml > somemodel.cellml

The produced CellML model will not be modular: all the variables and equations will be created inside a single CellML component. If future versions of JSim allow the creation of modular models, that modularity may be able to be translated to CellML's component structure. Note also that any domain-specific variables (time.max, time.min, etc.) will not be translated to CellML, as those concepts are not present in CellML models, but instead are only present in the simulator itself.

Known bugs: If constants are used in the JSim model without declared units, but whose units are implied, the implied units are not translated to CellML. To properly format a JSim model for export to CellML, therefore, all lines like:

S1 = 10+y;
should be changed to:
S1 = (10 mM)+y;
Future versions of JSim will relax this restriction.

Curating a CellML model with JSim

  1. Run jsbatch with the command:

    jsbatch -f somemodel.cellml -omml > somemodel.mod
    If this command completes successfully, it will create a JSim version of the CellML model.

  2. Next, examine the model for warnings. These usually mean that JSim had to change something from the original model to create a working model. Warning messages that indicate something awry in the CellML model are:

    • //Warning:  the following variables were set 'extern' or given
      //  an initial value of '0' because the model would otherwise be
      //  underdetermined:  [List of variables]
      This warning is put at the top of a model when the translator had to fix what it saw as an underdetermined model. You can find the variables in question by searching for for the warning message:
      //Warning:  Assuming zero initial condition; nothing provided in original CellML model.
      and for the 'extern' keyword.
    • //Warning:  the following variables had initial values which were
      //  suppressed because the model would otherwise be overdetermined: [List of variables]
      This warning is put at the top of a model where the translator had to fix what it saw as an overdetermined model. You can find the variables in question by searching for the warning message:
      //Warning: CellML initial value suppressed to prevent overdetermining model.  Original initial value: [value]
      The model can be fixed by removing the initial value for this variable, or by removing some equation from the model. NOTE: it is possible, though not likely, that a model may be flagged as being both over- and under-determined. This happens when sets of equations do not overlap in terms of what variables can be determined from them, and one set is overdetermined and a different set is underdetermined. Ten models in our test bed had this feature, all of which were marked as either being unchecked or as being unable to run in OpenCell.
    • // Warning: unit conversion turned off due to unit errors in [number] equation(s).
      The units are not consistent in the model, perhaps due to units not being properly imported, or perhaps due to actual mistakes in the model. If there are any other warnings in the unit section of the model (see below) try fixing them first. If unit conversion is still off, the next step is to find out what the model errors actually are: change the unit conversion off; line to 'on', then run jsbatch in verbose mode on the translated model:
      jsbatch -v -f somemodel.mod -oplan
      Note that loading the original CellML file will not work, as the translator will turn off unit conversion automatically. After fixing the CellML model, re-create 'somemodel.mod'. If this warning goes away and unit conversion is now on, you now have consistent units!
    • //Warning:  unit [unit_] renamed from [unit], as the latter is predefined in JSim with different fundamental units.
      The common meaning of a particular unit was overridden by this CellML model. The single most common error of this type is getting the order of magnitude wrong: for example, when warned about 'picoA' being redefined, you'll then see:
      unit picoA_=1E-9 ampere^1;
      which is of course nanoamperes, not picoamperes. Looking at the original model, you'll find something like this (from butera_rinzel_smith_1999_model2):
        <units name="picoA">
          <unit units="ampere" prefix="nano"/>
        </units>
      which is easily fixed by changing the name of the unit.
    • //Warning:  unit [unit] unknown; assuming it is equivalent to the JSim predefined unit of the same name.
      and
      //Warning:  unit [unit] unknown; assuming it is a fundamental unit.
      The unit in question was used without being defined. The difference in the two messages is that JSim is making different assumptions to try to fix the problem, but the problem in the original CellML model is the same. If the unit was imported, you get this warning because JSim cannot yet handle imported elements. Otherwise, a unit definition needs to be added to the model.
    • //Warning:  the unit 'celsius' is not well defined.
      //  It may mean 'distance from 0 degrees C' in some contexts,  and 'distance in C degrees' in others.
      //  We assume this model meant the latter, and have converted the unit to the equivalent but better-defined 'kelvin' instead.
      Although 'celsius' is a predefined unit in CellML, JSim does not like it, for the reasons stated. It is indeed probably a better idea to go with kelvin units instead.

  3. Finally, run jsbatch again with the command
    jsbatch -f somemodel.cellml -oplan
    If this command completes successfully, it will create a JSim version of the CellML model together with an outline of how to perform a simulation using the model. Once the time parameters are set, the model can be simulated in JSim. If this command produces errors (but running jsbatch with '-omml' did not) it means that JSim was not able to determine how to solve the model. Of our test bed of 1055 models, there are four models of this type, and it is unclear whether JSim's inability to simulate the model is a fault of JSim or of the model itself--none of the four models have been fully validated.

You may also wish to refer to the jsbatch manual .

Project Status

JSim's CellML translator is quite robust, lacking mostly the ability to handle importing components and units from other files. It was developed based the CellML 1.1 specification with the intent of providing a simulatable translation of the majority of the models in the CellML repository. As of 1 Dec 2011, of the 1055 models used as a test bed, 884 translate to MML without error, and can be compiled to a working simulatable model, 141 cannot be translated due to those models attempting to import a component from a separate file, 3 fail due to errors in the CellML model itself, and only 27 fail due to some other reason, mostly use of unsupported MathML elements.

Features of the translator

In the interest of creating workable JSim models from CellML files, the following transformations are performed:

Bugs and Limitations

The following limitations are based on experience with the 1055 model test bed (see above).

Change Log

See What's New with JSim for a complete list of all changes made to JSim, by version number. The following changes are specific to the CellML-to-JSim translator:

Changes in v2.05

Overall, of all the .cellml files from the repository that we could download (1055 models), the old algorithm could translate, parse, and compile 660 models (with unit checking off), and failed at one of those stages for 395 models. The new algorithm translates, parses, and comes up with a solution plan for 884 models, setting unit checking on or off automatically, and fails for 171 models. Of those 171 models, 141 of them fail because they use the CellML 1.1 'import component' construct, 3 fail due to obvious errors in the CellML model itself, and most of the rest fail because they use MathML constructs we don't support. This was accomplished with the following changes:

In addition, the following features were changed or added:

Comments or Questions?

[This page was last modified 01Jun16, 4:50 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.