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 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
get the values of the model immediately after applying initial and
repeated assignment rules. If you set the value to
and the simulation fails with the integration error, then it probably
indicates an error with the assignment rules.
the model repeatedly using the same conditions that produce the error.
The model might simulate without error until you reach a certain value
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,
where x is the variable that is responsible for
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
your solver for stiff ODEs.
Turn off AbsoluteToleranceScaling.
SimBiology uses AbsoluteTolerance and RelativeTolerance to control the accuracy
of integration during simulation. Specifically,
the largest allowable absolute error at any step during simulation.
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
while another is
0.1. By turning off
you might be able to simulate the model.
If the simulation tolerance error still exists after disabling AbsoluteToleranceScaling, try loosening the relative and absolute tolerances.
RelativeTolerance to ,
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.
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.
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 (
but in some edge cases, you may need to change it.
a unit so that the simulated values are not too large (that is, greater
106) or too small
(that is, smaller than
Suppose that you have a model with a state that takes on values
10-12 moles for
the entire simulation. It might be appropriate to set
In this case, the internal simulation values would be around
instead of around
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
MaximumWallClock. Depending on whether you are using the
command line or graphical interface, the way to access and change the options
Using the Command line
To access and change the
use the following commands, where m1 is a SimBiology
configset = getconfigset(m1); configset.SolverOptions.AbsoluteTolerance = 1e-5; configset.SolverOptions.RelativeTolerance = 1e-5; configset.SolverOptions.AbsoluteToleranceScaling = false;
Access simulation options directly from the
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.