1. Welcome to the NSR Physiome Project!
  2. Physiome JSim
  3. The JSim Documentation Set
  4. MML Debugging Guide

MML Debugging Guide

Introduction

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.

Prerequisites:

Contents:

  • Common problems during model compilation:
    • Compiler aborts with unit compatibility errors
    • Compilation takes a very long time
  • Common problems during model runs:
    • Mysterious NaNs appear in output results
    • ODE/PDE solvers abort during run
    • Model run aborts with OutOfMemoryError
  • Tools for model diagnosis:
    • Planner output
    • Trace switches
  • Comments or Questions?
    Give feedback

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?

Give feedback

Model development and archiving support at https://www.imagwiki.nibib.nih.gov/physiome 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.