# SolverOptions

SimBiology model solver options

## Description

The `SolverOptions`

object holds the model solver options, and it
is a property of the `configset`

object.

Changing the `SolverType`

property of `configset`

changes
the options specified in the `SolverOptions`

object (or property).

You can add a number of `configset`

objects with different
`SolverOptions`

to the model object with the
`addconfigset`

method. Only one `configset`

object in the
model object can be `Active`

at any given
time. To change or update any of properties of the `SolverOptions`

property
object, use dot notation syntax:

, where *csObj*.SolverOptions.*PropertyName* =
value*csObj* is the configset object of a SimBiology
model and *PropertyName* is the name of the property of
`SolverOptions`

.

## Creation

Use dot notation syntax on a `configset`

object to return the property
object. That is,

returns the
*csObj*.SolverOptions`SolverOptions`

property object of the `configset`

object
*csObj*.

## Properties

`AbsoluteTolerance`

— Absolute error tolerance applied to state value during simulation

`1e-6`

(default) | positive scalar

Absolute error tolerance applied to a state value during simulation, specified as a
positive scalar. This property is available for the ODE solvers
(`ode15s`

, `ode23t`

, `ode45`

,
and `sundials`

).

SimBiology uses `AbsoluteTolerance`

to determine the largest
allowable absolute error at any step in a simulation. How the software uses
`AbsoluteTolerance`

to determine this error depends on whether the
`AbsoluteToleranceScaling`

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

**Data Types: **`double`

`AbsoluteToleranceScaling`

— Control scaling of absolute error tolerance during simulation

`true`

or 1 (default) | `false`

or 0

Control scaling of absolute error tolerance during simulation, specified as a
numeric or logical 1 ( `true`

) or 0 (`false`

).

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 one reaction can be on the order of
10^{22}, while another is 0.1. By turning off
`AbsoluteToleranceScaling`

, you might be able to simulate the
model. For more tips, see Troubleshooting Simulation Problems.

**Data Types: **`double`

| `logical`

`AbsoluteToleranceStepSize`

— Initial guess for time step size for scaling of absolute error tolerance

`[]`

(default) | positive scalar

Initial guess for time step size for scaling of absolute error tolerance, specified
as a positive scalar. The property uses the time units specified by the
`TimeUnits`

property of the corresponding
`configset`

object.

**Data Types: **`double`

`ErrorTolerance`

— Error tolerance of explicit or implicit tau stochastic solver

`3e-2`

(default) | positive scalar between 0 and 1

Error tolerance of an explicit or implicit tau stochastic solver, specified as a positive scalar between 0 and 1.

The explicit and implicit tau solvers automatically chooses a time interval (tau) such that the relative change in the propensity function for each reaction is less than the user-specified error tolerance. A propensity function describes the probability that the reaction will occur in the next smallest time interval, given the conditions and constraints. If the error tolerance is too large, there may not be a solution to the problem and that could lead to an error. If the error tolerance is small, the solver will take more steps than when the error tolerance is large leading to longer simulation times. The error tolerance should be adjusted depending upon the problem, but a good value for the error tolerance is between 1% and 5%.

**Data Types: **`double`

`LogDecimation`

— Specify frequency to log stochastic simulation output

1 (default) | positive integer

Specify the frequency to log stochastic simulation output, specified as a positive
integer. This property is available only for stochastic solvers (`ssa`

,
`expltau`

, and `impltau`

).

Use `LogDecimation`

to specify how frequently you want to record
the output of the simulation. For example, if you set `LogDecimation`

to 1, for the command `[t,x] = sbiosimulate(modelObj)`

, at each
simulation step the time will be logged in *t* and the quantity of each
logged species will be logged as a row in *x*. If
`LogDecimation`

is 10, then every 10th simulation step will be
logged in *t* and *x*.

**Data Types: **`double`

`MaxIterations`

— Maximum number of iterations for nonlinear solver in implicit tau

15 (default) | positive integer

Maximum number of iterations for the nonlinear solver in implicit tau
(`impltau`

), specified as a positive integer.

The implicit tau solver in SimBiology internally uses a nonlinear solver to solve a
set of algebraic nonlinear equations at every simulation step. Starting with an initial
guess at the solution, the nonlinear solver iteratively tries to find the solution to
the algebraic equations. The closer the initial guess is to the solution, the fewer the
iterations the nonlinear solver will take before it finds a solution.
`MaxIterations`

specifies the maximum number of iterations the
nonlinear solver should take before it issues a *failed to converge*
error. If you get this error during simulation, try increasing
`MaxIterations`

.

**Data Types: **`double`

`MaxStep`

— Maximum step size

`[]`

(default) | positive scalar

Maximum step size taken by an ODE solver, specified as a positive scalar. This
property sets an upper bound on the size of any step taken by the solver. This property
is available only for the ODE solvers (`ode15s`

,
`ode23t`

, `ode45`

, and
`sundials`

).

By default, `MaxStep`

is set to `[]`

, which is
equivalent to setting the value to infinity.

If the differential equation has periodic coefficients or solutions, it might be a
good idea to set `MaxStep`

to some fraction (such as 1/4) of the
period. This guarantees that the solver does not enlarge the time step too much and step
over a period of interest. For more information, see `odeset`

.

**Data Types: **`double`

`OutputTimes`

— Times to log deterministic simulation output

`[]`

(default) | vector of nonnegative values

Times to log deterministic (ODE) simulation output, specified as a vector of
nonnegative monotonically increasing values. This property specifies the times during an
ODE simulation that data is recorded. This property is available only for the ODE
solvers (`ode15s`

, `ode23t`

,
`ode45`

, and `sundials`

).

By default, the property is set to `[]`

, which instructs SimBiology
to log data every time the solver takes a step. The unit for this property is specified
by the `TimeUnits`

property of the corresponding
`configset`

object.

If the criteria set in the `MaximumWallClock`

property causes a
simulation to stop before all time values in `OutputTimes`

are
reached, then no data is recorded for the latter time values.

The `OutputTimes`

property can also control when a simulation
stops:

The last value in

`OutputTimes`

overrides the`StopTime`

property as criteria for stopping a simulation.The length of

`OutputTimes`

overrides the`MaximumNumberOfLogs`

property as criteria for stopping a simulation.

**Data Types: **`double`

`RandomState`

— State of random number generator

`[]`

(default) | integer

State of the random number generator for stochastic solvers, specified as an
integer. This property is available only for these solvers: `ssa`

,
`expltau`

, and `impltau`

.

SimBiology uses a pseudorandom number generator. The sequence of numbers generated
is determined by the state of the generator, which can be specified by the
`RandomState`

property. If `RandomState`

is set
to an integer *J*, the random number generator is initialized to its
*J*th state. The random number generator can generate all the
floating-point numbers in the closed interval [2^{-53},
1-2^{-53}]. Theoretically, it can generate over
2^{1492} values before repeating itself. But for a given
state, the sequence of numbers generated will be the same. To change the sequence,
change `RandomState`

. SimBiology resets the state at startup. The
default value of `RandomState`

is `[]`

.

**Data Types: **`double`

`RelativeTolerance`

— Allowable error tolerance relative to state value during a simulation

`1e-3`

(default) | positive scalar less than 1

Allowable error tolerance relative to a state value during a simulation, specified
as a positive scalar less than 1. This property is available only for the ODE solvers
(`ode15s`

, `ode23t`

, `ode45`

,
and `sundials`

).

The `RelativeTolerance`

property specifies the allowable error
tolerance relative to the state vector at each simulation step. The state vector
contains values for all the state variables, for example, amounts for all the
species.

For example, if you set the `RelativeTolerance`

to
`1e-2`

, you are specifying that an error of 1% relative to each state
value is acceptable at each simulation step. For details, see Selecting Absolute Tolerance and Relative Tolerance for Simulation.

**Data Types: **`double`

`SensitivityAnalysis`

— Flag to enable or disable sensitivity analysis

`false`

or 0 (default) | `true`

or 1

Flag to enable or disable sensitivity analysis, specified as a numeric or logical 1
(`true`

) or 0 (`false`

).

This property lets you compute the time-dependent sensitivities of all the species
states defined by the `StatesToLog`

property with respect to the
`Inputs`

that you specify in the SensitivityAnalysisOptions property of the configuration set object.

SimBiology always uses the SUNDIALS solver to perform sensitivity analysis on a model, regardless of what you have selected as the SolverType in the configuration set.

For more information on setting up sensitivity analysis, see SensitivityAnalysisOptions. For a description of sensitivity analysis calculations, see Sensitivity Analysis in SimBiology.

**Note**

Models containing the following active components do not support sensitivity analysis:

Nonconstant compartments

Algebraic rules

Events

**Data Types: **`double`

| `logical`

`Type`

— SimBiology object type

`'solveroptions'`

(default)

This property is read-only.

SimBiology object type, specified as `'solveroptions'`

.

**Data Types: **`char`

## Examples

### Change Solver Options and Simulation Options

The solver and simulation options are stored in the configuration set (`configset`

object) of a SimBiology model. Solver options contain settings such as relative and absolute tolerances. Simulation options are settings such as `MaximumNumberOfLogs`

and `MaximumWallClock`

.

Depending on the solver type, the available solver options differ. Inspect the default ODE solver.

```
m1 = sbiomodel("m1");
cs = getconfigset(m1);
cs.SolverType
```

ans = 'ode15s'

Change the ODE solver to `ode45`

, which is one of the supported ODE solvers. For details, see Choosing a Simulation Solver.

```
cs.SolverType = "ode45";
cs.SolverOptions
```

ans = SimBiology Solver Settings: (ode) AbsoluteTolerance: 1e-06 AbsoluteToleranceScaling: true RelativeTolerance: 0.001 SensitivityAnalysis: false

If you change a common option for the ODE solvers, that change is persistant across all the ODE solver types. For example, change the `AbsoluteTolerance`

of the current solver.

cs.SolverOptions.AbsoluteTolerance = 1e-3

cs = Configuration Settings - default (active) SolverType: ode45 StopTime: 10 SolverOptions: AbsoluteTolerance: 0.001 AbsoluteToleranceScaling: true RelativeTolerance: 0.001 SensitivityAnalysis: false RuntimeOptions: StatesToLog: all CompileOptions: UnitConversion: false DimensionalAnalysis: true SensitivityAnalysisOptions: Inputs: 0 Outputs: 0

Change the solver to `ode23t`

and check the value of `AbsoluteTolerance`

, which is still the value you set previously.

```
cs.SolverType = "ode23t";
cs.SolverOptions.AbsoluteTolerance
```

ans = 1.0000e-03

If you specify a stochastic solver as the solver type, the associated solver options are updated automatically, and these options are different from the ODE solver options. For details on the supported stochastic solvers, see Stochastic Solvers.

Change to the explicit tau-leaping algorithm.

`cs.SolverType = "expltau"`

cs = Configuration Settings - default (active) SolverType: expltau StopTime: 10 SolverOptions: ErrorTolerance: 0.03 LogDecimation: 1 RuntimeOptions: StatesToLog: all CompileOptions: UnitConversion: false DimensionalAnalysis: true SensitivityAnalysisOptions: Inputs: 0 Outputs: 0

You can also change the simulation settings, which are the properties of the `configset`

object. For example, change the maximum number of logs criterion to decide when to stop the simulation. Setting it to 1 returns simulated values of the model quantities immediately after applying initial and repeated assignment rules of the model. If you change the value to 2, and the subsequent simulation fails with the integration error, then it probably indicates an error with the assignment rules. For more tips on how to use these simulation settings to troubleshoot some of the common simulation problems, see Troubleshooting Simulation Problems.

cs.MaximumNumberOfLogs = 1;

### Specify Times to Log Deterministic Simulation Output

Specify the times during a deterministic (ODE) simulation that data is recorded.

Create a `model`

object named `cell`

and save it in a variable named `modelObj`

.

`modelObj = sbiomodel('cell');`

Retrieve the configuration set from `modelObj`

and save it in a variable named `configsetObj`

.

configsetObj = getconfigset(modelObj);

Specify to log output every second for the first `10`

seconds of the simulation. Do this by setting the `OutputTimes`

property of the `SolverOptions`

property of `ConfigsetObj`

.

sopt = configsetObj.SolverOptions; sopt.OutputTimes = [1:10]; sopt.OutputTimes

`ans = `*10×1*
1
2
3
4
5
6
7
8
9
10

When you simulate `modelObj`

, output is logged every second for the first `10`

seconds of the simulation. Also, the simulation stops after the 10th log.

## Version History

**Introduced in R2006b**

## Open Example

You have a modified version of this example. Do you want to open this example with your edits?

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

## How to Get Best Site Performance

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)