SimBiology.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:
csObj.SolverOptions.PropertyName =
value
, where 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, csObj.SolverOptions
returns the
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
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.
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 theStopTime
property as criteria for stopping a simulation.The length of
OutputTimes
overrides theMaximumNumberOfLogs
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
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,
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 persistent 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
Commande MATLAB
Vous avez cliqué sur un lien qui correspond à cette commande MATLAB :
Pour exécuter la commande, saisissez-la dans la fenêtre de commande de MATLAB. Les navigateurs web ne supportent pas les commandes MATLAB.
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)