## 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 `1022`, 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 `106`) 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 `SolverOptions`, use the following commands, where m1 is a SimBiology model.

```configset = getconfigset(m1); solverOpts = configset.SolverOptions; solverOpts.AbsoluteTolerance = 1e-5; solverOpts.RelativeTolerance = 1e-5; solverOpts.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.