Troubleshooting Simulation Problems

SimBiology^® uses ODE solvers for model simulation. Solver errors can cause simulation problems. Many solver errors relate to the stiffness of the model and the relative and absolute tolerances. As a result, the simulation can take long. You might also see one of the following error messages, indicating that the solver is not able to solve the problem within the tolerances.

Integration tolerance not met
CVODES returned -4 from module CVODES function CVode: At t = ... and h = ... the corrector convergence test failed repeatedly or with |h| = hmin.

You might also see one or more of the following warning messages, which are precursors to potential solver tolerance issues.

The right-hand side of the system of SimBiology ODEs results in complex numbers. The imaginary part of the result will be ignored.
The right-hand side of the system of SimBiology ODEs results in infinite or NaN values. This usually indicates a modeling error and can lead to solver integration errors.
The repeated assignment rules of the SimBiology model result in complex numbers. The imaginary part of the result will be ignored.

Tips for Solving Simulation Problems

To fix the simulation problems that solver errors can cause, try the following troubleshooting tips.

Improve Performance by Acceleration

You can accelerate the simulation by converting the model to compiled C code, which executes faster. For details, see Accelerating Model Simulations and Analyses. If the simulation is still slow after acceleration, there might be solver tolerance issues. Try the remaining tips without accelerating the model.

Debug the Model Using `MaximumNumberOfLogs` and `MaximumWallClock`

MaximumNumberOfLogs and MaximumWallClock are some of the configuration options you can use to stop the simulation just before the error happens. Then you can check for unusual simulated values, such as negative species amounts.

For instance, set MaximumNumberOfLogs to 1 to get the values of the model immediately after applying initial and repeated assignment rules. If you set the value to 2, and the simulation fails with the integration error, then it probably indicates an error with the assignment rules.

While varying MaximumNumberOfLogs, simulate the model repeatedly using the same conditions that produce the error. The model might simulate without error until you reach a certain value of MaximumNumberOfLogs. Then check the simulated values at the final simulation time. If you see negative values for certain states, such as negative species amounts, examine the expressions in your model that can affect those states. Update the expressions to account for possible issues, such as negative values or division-by-0, by either rearranging the equations and/or inserting some protections, such as max(0,x) or max(eps,x), where x is the variable that is responsible for the error.

Alternatively, you can look at the model equations to check the initial conditions, such as species amounts and parameter values at simulation time = 0 to see if the values are as expected. For details, see getequations or Show Model Equations and Initial Conditions.

Check the ODE Solver

If your model is stiff, and you have selected an inappropriate solver, the step size taken by the solver might be forced down to an unreasonably small level compared to the interval of integration. Make sure that you have selected either ode15s or sundials as your solver for stiff ODEs.

Disable `AbsoluteToleranceScaling`

Turn off AbsoluteToleranceScaling.

SimBiology uses AbsoluteTolerance and RelativeTolerance to control the accuracy of integration during simulation. Specifically, AbsoluteTolerance controls the largest allowable absolute error at any step during simulation.

When AbsoluteToleranceScaling is enabled (by default), each state has its own absolute tolerance that can increase over the course of simulation. Sometimes the automatic scaling is inadequate for models that have kinetics at largely different scales. For example, the reaction rate of a reaction can be in the order of 10²², while another is 0.1. By turning off AbsoluteToleranceScaling, you might be able to simulate the model.

Loosen Tolerances

If the simulation tolerance error still exists after disabling AbsoluteToleranceScaling, try loosening the relative and absolute tolerances.

Set RelativeTolerance to $10^{- m + 1}$ , where m is the number of significant digits desired in the solution X. If X has multiple scales, start with using the smaller X and increase from there if the tolerance is not met.

Set AbsoluteTolerance to a value of X that is negligibly small for your problem. Similarly, start from the smaller X and increase from there.

For details, see Selecting Absolute Tolerance and Relative Tolerance for Simulation.

Set `MassUnits` and `AmountUnits`

The MassUnits and AmountUnits properties define the appropriate mass or amount unit that SimBiology uses internally during model simulation when UnitConversion is on. It is recommended that you use the default unit (<automatic>) but in some edge cases, you may need to change it.

Change MassUnits or AmountUnits to a unit so that the simulated values are not too large (that is, greater than 10⁶) or too small (that is, smaller than 10^-6).

Suppose that you have a model with a state that takes on values around 10^-12 moles for the entire simulation. It might be appropriate to set AmountUnits to picomole. In this case, the internal simulation values would be around 1, instead of around 10^-12 as in the default case.

How to Change Solver Options and Simulation Options

Solver and simulation options are stored in the configuration set object (configset object) of the model. Solver options contain settings such as relative and absolute tolerances. Simulation options are settings such as MaximumNumberOfLogs and MaximumWallClock. Depending on whether you are using the command line or graphical interface, the way to access and change the options differs.

Using the Command line

To access and change the SimBiology.SolverOptions, use the following commands, where m1 is a SimBiology model.

configset = getconfigset(m1);
configset.SolverOptions.AbsoluteTolerance = 1e-5;
configset.SolverOptions.RelativeTolerance = 1e-5;
configset.SolverOptions.AbsoluteToleranceScaling = false;

Access simulation options directly from the configset object.

configset = getconfigset(m1);
configset.MaximumNumberOfLogs = 1;
configset.MaximumWallClock = 10;

Using the Graphical Interface

If you are using the SimBiology Model Analyzer app, you can access the options by clicking Simulation Settings from the Home tab.