SimBiology model solver options
SolverOptions object holds the model solver options, and it
is a property of the
SolverType property of
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
object, use dot notation syntax:
value, where csObj is the configset object of a SimBiology
model and PropertyName is the name of the property of
Use dot notation syntax on a
configset object to return the property
object. That is,
csObj.SolverOptions returns the
SolverOptions property object of the
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
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.
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 (
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
1022, while another is 0.1. By turning off
AbsoluteToleranceScaling, you might be able to simulate the
model. For more tips, see Troubleshooting Simulation Problems.
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
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%.
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 (
LogDecimation to specify how frequently you want to record
the output of the simulation. For example, if you set
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.
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
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 (
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
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
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
TimeUnits property of the corresponding
If the criteria set in the
MaximumWallClock property causes a
simulation to stop before all time values in
reached, then no data is recorded for the latter time values.
OutputTimes property can also control when a simulation
The last value in
StopTimeproperty as criteria for stopping a simulation.
The length of
MaximumNumberOfLogsproperty as criteria for stopping a simulation.
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:
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
Jth 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
21492 values before repeating itself. But for a given
state, the sequence of numbers generated will be the same. To change the sequence,
RandomState. SimBiology resets the state at startup. The
default value of
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
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
For example, if you set the
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.
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 (
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.
Models containing the following active components do not support sensitivity analysis:
Type — SimBiology object type
This property is read-only.
SimBiology object type, specified as
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
Depending on the solver type, the available solver options differ. Inspect the default ODE solver.
m1 = sbiomodel("m1");
cs = getconfigset(m1);
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";
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";
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.
model object named
cell and save it in a variable named
modelObj = sbiomodel('cell');
Retrieve the configuration set from
modelObj and save it in a variable named
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
sopt = configsetObj.SolverOptions; sopt.OutputTimes = [1:10]; sopt.OutputTimes
ans = 10×1
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.
Introduced in R2006b