## 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 ^{22}`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 ^{6}`10`

). ^{-6}

Suppose that you have a model with a state that takes on values
around `10`

moles for
the entire simulation. It might be appropriate to set ^{-12}`AmountUnits`

to `picomole`

.
In this case, the internal simulation values would be around `1`

,
instead of around `10`

as
in the default case.^{-12}

### 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 `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.

## See Also

`Configset object`

| `SolverOptions`

| AbsoluteTolerance | RelativeTolerance | `MaximumNumberOfLogs`

| `MaximumWallClock`

| `getequations`