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

MML Debugging Guide

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


This document suggests approaches for reasonably advanced MML model writers to debugging some common problems with model compilation and run results. It is a rough guide that is expected to grow over time. It is not meant to be encyclopedic.



Compiler aborts with unit compatibility errors

Such error messages are usually fairly specific about the offending construct. If there are questions about common standard unit definitions, you may examine the common units file in $JSIMHOME/common/nsrunit.mod. Alternatively, this file may be viewed in a model's "Debug" tab in the JSim GUI by selecting "View system units file" from the "View" menu. The following facts about JSim unit correction are often a source of confusion:

  1. Variables not explicitly assigned units at declaration time will be assigned units based on equation context. This is not the same as declaring a variable dimensionless. An error will result if the variable is used in conflicting contexts, although the resulting cascade of assignments may make the original error difficult to trace. Assigning units to some variables explicitly may help in diagnosis.
  2. Transcendental functions (e.g. exp(), sin()) must take dimensionless arguments and return dimensionless results.
  3. The exponent of the power function must be dimensionless.
  4. United variables may only be raised to constant powers.
  5. integral() has units that are the product of the expression being integrated and the variable of integration. sum() has the same units as the expression being summed.

Compilation takes a very long time

Model compilation times over about 30 seconds usually result from the compiler attempting to solve a large number of simultaneous implicit equations . This may occur because your model actually has such equations, but more ofter occurs because there are missing equations in your model. One common cause is missing initial conditions for ODE/PDE state variables.

Mysterious NaNs appear in output results

NaN (Not A Number) is an IEEE standard for non-sensical numbers, e.g. 0/0. Some causes of NaN calculations include:

  1. MML code not protected from zero divides, negative sqrt() arguments and the like.
  2. Numerically unstable ODE/PDE equations being fed into adaptive time-step solvers (e.g. radau).
  3. Planning errors caused by unsupported use of variable functions .
  4. Cancelled or aborted runs will leave NaNs in all variables that had not yet been calculated.

Use the planner output and/or trace switches can sometimes facilitate the diagnosis of such problems.

ODE/PDE solvers abort during run

If these aborts relate to NaNs, see the item above. If not, the equations may be too sophisticated for the solvers and/or settings you are using. See the model "Solvers" page to see the various options for which solvers are available. The default solver settings are appropriate for many problems, but not all. Try different solvers as see if they improve your results.

Model run aborts with OutOfMemoryError

This problem may occur when running models that have very large numbers of variables, or use very large time or spatial grids. For a more complete guide to dealing with such problems see here .

Planner Output

The JSim planner is that part of the JSim compiler that turns MML mathematical constructs into a specific sequence of calculations. A simple text representation of this sequence may be viewed in a model's "Debug" tab in the JSim GUI by selecting "View plan text" within the "View" menu. Examining this text can give the modeler insight into how JSim is attempting to calculate the model and suggesting what the problem is.

In theory, the planner sequence is internally checked so that each variable is calculated from previously calculated variables. In practice, variable functions sometimes poses difficult sequencing problems which the planner doesn't correctly solve. This results in NaN calculations, since variables are initialized to NaNs before each model run.

Trace Switches

Debugging switches -trace, -traceNaN and -abortNaN are described in the Batch Processing Manual . The example below suggests an approach to tracing the appearance of NaNs in JSim output.

Run jsbatch on your model/project using the -abortNaN switch. This will cause the model run to abort the first time a NaN is calculated, with an error text on the offending variable. Use the JSim planner output (above) to figure out which variables are used in calculating the NaN occurance. If it is still unclear what the problem is, use the -trace switch to trace those variables. Repeat process until the problem is found.

Comments or Questions?

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

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