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 10²², 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 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 2¹⁴⁹² 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