SimBiology.Configset
Solver settings information for model simulation
Description
A SimBiology.Configset
object, also known as the configuration
set object, contains the options that the solver uses during simulation of a SimBiology® model.
Use dot notation to query the object properties or change properties that are not
read-only. You can also use the get
and set
commands.
The configuration set object contains the following options for you to choose:
Type of solver
Stop time for the simulation
Solver error tolerances, and for ode solvers — the maximum time step the solver should take
Whether to perform sensitivity analysis during simulation
Whether to perform dimensional analysis and unit conversion during simulation
Species and parameter input factors for sensitivity analysis
A SimBiology model can contain multiple configsets with one being active at any given time.
The active SimBiology.Configset
object contains the settings that are used
during the simulation. Use the method setactiveconfigset
to define the active configset. Use the method getconfigset
to return a list of configset
objects contained by
a model. Use the method addconfigset
to add a new
configset
to a model.
Creation
Use addconfigset (model)
to create and add a
configset
object to a SimBiology model. Use getconfigset (model)
to get an existing configset
object from a
model.
Properties
Active
— Flag to use SimBiology.Configset
object during simulation
true
or 1 (default) | false
or 0
This property is read-only.
Flag to use the SimBiology.Configset
object during simulation, specified as
a numeric or logical 1 (true
) or 0 (false
). The
property is true for the default configset
object. For any added
configset
object, the default is false.
Use setactiveconfigset (model)
to set this
property of a configset
object.
Warning
The Active
property will be removed in a future release.
Explicitly specify a configset
object that you want to use as an
input argument when you simulate a model using sbiosimulate
.
Data Types: double
| logical
AmountUnits
— Amount units
'<automatic>'
(default) | character vector | string
Amount units that SimBiology uses internally during simulation when UnitConversion is on, specified as a character vector or string.
You can set this property to any character vector or string representing an amount
unit such as molecule, mole, or mole with any valid prefix. It can also be a custom unit
if it is consistent with amount as its dimension. The default is
<automatic>
, which means SimBiology automatically selects an
amount unit for simulation. SimBiology examines the units on all of the states and
selects an amount unit such that AbsoluteTolerance of the states in amount, or amount per volume is at
least as stringent as the simulation absolute tolerance multiplied by the smallest
amount unit. This stringency is relaxed appropriately for states that become large when
AbsoluteToleranceScaling is on.
It is recommended that you use the default unit
(<automatic>
) or choose units for states such that the
simulated values are neither too large (greater than 106) or
too small (less than 10-6).
However, for some edge cases, you may need to change
AmountUnits
. Suppose you have a model with a state that takes on
values around 10-12 moles for the entire simulation, and you
need to use mole
as its unit. Then it may 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. AbsoluteTolerance of the simulation is determined using this internal
value. Thus by choosing picomole
as the amount unit, you effectively
reduce the size of AbsoluteTolerance
. Changing the
AmountUnits
property is closely related to changing
AbsoluteTolerance
when considering the effects on simulation
results.
Even when using the default unit, it may be still necessary to change AbsoluteTolerance. For details, see Selecting Absolute Tolerance and Relative Tolerance for Simulation.
If you need to recover the simulation behavior from releases prior to R2015b:
Set the
AmountUnit
tomole
. However, if the model has quantity units inmolecule
, set the unit tomolecule
instead.Set the MassUnits to
kilogram
.
Tip
If you have a custom function and UnitConversion is on (whether or not you are using the default unit
<automatic>
), follow the recommendation below.
Non-dimensionalize the parameters that are passed to the function if they are not already dimensionless.
Suppose you have a custom function defined as
y = f(t)
wheret
is the time in hour andy
is the concentration of a species in mole/liter. When you use this function in your model to define a repeated assignment rule for instance, define it as:s1 = f(time/t0)*s0
, wheretime
is the simulation time,t0
is a parameter defined as 1.0 hour,s0
is a parameter defined as 1.0 mole/liter, ands1
is the concentration of a species in mole/liter. Note thattime
ands1
do not have to be in the same units ast0
ands0
, but they must be dimensionally consistent. For example, thetime
ands1
units can be set to minute and picomole/liter, respectively.
Data Types: char
| string
CompileOptions
— Compile options
SimBiology.CompileOptions
(default)
Compile options, specified as a CompileOptions
object. Use this object to specify the default species
dimension and to enable unit conversion.
MassUnits
— Mass units
'<automatic>'
(default) | character vector | string
Mass units that SimBiology uses internally during simulation when UnitConversion is on, specified as a character vector or string.
You can set this to any string representing a mass unit such as gram, or gram with
any valid prefix. It can also be a custom unit if it is consistent with mass as its
dimension. The default is <automatic>
, which means SimBiology
automatically selects a mass unit for simulation. SimBiology examines the units on all
of the states and selects a mass unit such that AbsoluteTolerance of the states in mass or mass per volume is at least as
stringent as the simulation absolute tolerance multiplied by the smallest mass unit.
This stringency is relaxed appropriately for states that become large when AbsoluteToleranceScaling is on.
It is recommended that you use the default unit
(<automatic>
) or choose units for states such that the
simulated values are neither too large (greater than 106) or
too small (less than 10-6).
However, for some edge cases, you may need to change MassUnits
.
Suppose you have a model with a state that takes on values around
10-12
gram
for the entire simulation, and you need to use
gram
as its unit. Then it may be appropriate to set
MassUnits
to picogram
. In this case, the
internal simulation values would be around 1, instead of around
10-12 as in the default case. AbsoluteTolerance of the simulation is determined using this internal
value. Thus by choosing picogram
as the mass unit, you effectively
reduce the size of AbsoluteTolerance
. Changing the
MassUnits
property is closely related to changing
AbsoluteTolerance
when considering the effects on simulation
results.
Even when using the default unit, it may be still necessary to change AbsoluteTolerance. For details, see Selecting Absolute Tolerance and Relative Tolerance for Simulation.
If you need to recover the simulation behavior from releases prior to R2015b:
Set the
MassUnits
tokilogram
.Set the AmountUnits to
mole
. However, if the model has quantity units inmolecule
, set the unit tomolecule
instead.Tip
If you have a custom function and UnitConversion is on (whether or not you are using the default unit
<automatic>
), follow the recommendation below.Non-dimensionalize the parameters that are passed to the function if they are not already dimensionless.
Suppose you have a custom function defined as
y = f(t)
wheret
is the time in hour andy
is the concentration of a species in mole/liter. When you use this function in your model to define a repeated assignment rule for instance, define it as:s1 = f(time/t0)*s0
, wheretime
is the simulation time,t0
is a parameter defined as 1.0 hour,s0
is a parameter defined as 1.0 mole/liter, ands1
is the concentration of a species in mole/liter. Note thattime
ands1
do not have to be in the same units ast0
ands0
, but they must be dimensionally consistent. For example, thetime
ands1
units can be set to minute and picomole/liter, respectively.
Data Types: char
| string
MaximumNumberOfLogs
— Maximum number of logs criteria to stop simulation
Inf
(default) | positive number
Maximum number of logs criteria to stop a simulation, specified as a positive number.
A simulation stops when it meets any of the criteria specified by
StopTime
, MaximumNumberOfLogs
, or
MaximumWallClock
. However, if you specify the
OutputTimes
property of the SolverOptions
property of the Configset
object, then StopTime
and MaximumNumberOfLogs
are ignored. Instead, the last value in
OutputTimes
is used as the StopTime
criteria,
and the length of OutputTimes
is used as the
MaximumNumberOfLogs
criteria.
For more tips on using this property to resolve simulation issues, see Debug the Model Using MaximumNumberOfLogs and MaximumWallClock.
Data Types: double
MaximumWallClock
— Maximum elapsed wall clock time to stop simulation
Inf
(default) | positive number
Maximum elapsed wall clock time (seconds) to stop a simulation, specified as a positive number.
A simulation stops when it meets any of the criteria specified by
StopTime
, MaximumNumberOfLogs
, or
MaximumWallClock
. However, if you specify the
OutputTimes
property of the SolverOptions
property of the Configset
object, then StopTime
and MaximumNumberOfLogs
are ignored. Instead, the last value in
OutputTimes
is used as the StopTime
criteria,
and the length of OutputTimes
is used as the
MaximumNumberOfLogs
criteria.
For more tips on using this property to resolve simulation issues, see Debug the Model Using MaximumNumberOfLogs and MaximumWallClock.
Data Types: double
Name
— SimBiology.Configset
object name
character vector | string
SimBiology.Configset
object name, specified as a character vector or string.
For details on requirements and recommendations for naming SimBiology components, see Guidelines for Naming Model Components.
Data Types: char
| string
Notes
— Additional information
empty character array (default) | character vector | string
Additional information that you can add for SimBiology.Configset
, specified as a
character vector or string.
Data Types: char
| string
RuntimeOptions
— Options for logged species and parameters
SimBiology.RuntimeOptions
Options for logged species and parameters, specified as a RuntimeOptions
object. This object contains information on which species,
parameters, or compartments are logged during simulation.
SensitivityAnalysisOptions
— Options for local sensitivity analysis
SimBiology.SensitivityAnalysisOptions
Options for local sensitivity analysis, specified as a SensitivityAnalysisOptions
object.
SolverOptions
— SimBiology model solver options
SolverOptions
SimBiology model solver options, specified as a SolverOptions
object.
SolverType
— Solver to use for simulation
'ode15s'
(default) | 'ode23t'
| 'ode45'
| 'sundials'
| 'ssa'
| 'expltau'
| 'impltau'
Solver to use for simulation, specified as 'ode15s'
,
'ode23t'
, 'ode45'
,
'sundials'
, 'ssa'
, 'expltau'
,
or 'impltau'
. For details, see Choosing a Simulation Solver.
Changing the solver type changes the options (properties) specified in the
SolverOptions
property of the configset
object.
If you change any SolverOptions
, these changes are persistent when
you switch SolverType
. For example, if you set the
ErrorTolerance
for the expltau
solver and then
change to impltau
when you switch back to expltau
,
the ErrorTolerance
will have the value you assigned.
Note
If your model contains events, you cannot specify
'expltau'
or'impltau'
for theSolverType
property.If your model contains doses, you cannot specify
'ssa'
,'expltau'
, or'impltau'
for theSolverType
property.If your model contains algebraic rules, you cannot use
'ode45'
.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.
Data Types: char
| string
StopTime
— Simulation time criteria to stop simulation
10 (default) | nonnegative scalar
Simulation time criteria to stop simulation, specified as a nonnegative scalar.
This property sets the maximum simulation time criteria to stop a simulation. Time units
are specified by the TimeUnits
property of the
Configset
object.
A simulation stops when it meets any of the criteria specified by
StopTime
, MaximumNumberOfLogs
, or
MaximumWallClock
. However, if you specify the
OutputTimes
property of the SolverOptions
property of the Configset
object, then StopTime
and MaximumNumberOfLogs
are ignored. Instead, the last value in
OutputTimes
is used as the StopTime
criteria,
and the length of OutputTimes
is used as the
MaximumNumberOfLogs
criteria.
Data Types: double
TimeUnits
— Time units for simulation
'second'
(default) | character vector | string
Time units for simulation, specified as a character vector or string.
If you change the value of the TimeUnits
property, make
sure:
You update raw numbers used in any event triggers that use the keyword
time
accordingly.The units, if any, associated with expressions used in any event triggers that use the keyword
time
, are consistent with the updatedTimeUnits
property. For more information, see Trigger.
Tip
If UnitConversion is on and your model has any
event, non-dimensionalize any parameters used in the event Trigger
if they are not already dimensionless. For example, suppose you have
a trigger x > 1
, where x is the species
concentration in mole/liter. Non-dimensionalize x by scaling (dividing)
it with a constant such as x/x0 > 1
, where x0 is a
parameter defined as 1.0 mole/liter. Note that x does not have to have
the same unit as the constant x0, but must be dimensionally consistent
with it. For example, the unit of x can be picomole/liter instead of
mole/liter.
Data Types: char
| string
Type
— Object type
'configset'
(default)
This property is read-only.
Object type, specified as 'configset'
. When you create a
SimBiology object, the value of Type
is automatically
defined.
Data Types: char
Object Functions
Examples
Set Maximum Number of Logs Criteria to Stop Simulation
Set the maximum number of logs that triggers a simulation to stop.
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);
Configure the simulation stop criteria by setting the MaximumNumberOfLogs
property to 50
. Leave the StopTime
and MaximumWallClock
properties at their default values of 10
seconds and Inf
, respectively.
set(configsetObj, 'MaximumNumberOfLogs', 50)
View the properties of configsetObj
.
get(configsetObj)
Active: 1 CompileOptions: [1x1 SimBiology.CompileOptions] Name: 'default' Notes: '' RuntimeOptions: [1x1 SimBiology.RuntimeOptions] SensitivityAnalysisOptions: [1x1 SimBiology.SensitivityAnalysisOptions] SolverOptions: [1x1 SimBiology.ODESolverOptions] SolverType: 'ode15s' StopTime: 10 MaximumNumberOfLogs: 50 MaximumWallClock: Inf TimeUnits: 'second' AmountUnits: '<automatic>' MassUnits: '<automatic>' Type: 'configset'
When you simulate modelObj
, the simulation stops when 50
logs are created or when the simulation time reaches 10
seconds, whichever comes first.
Set Maximum Wall Clock Criteria to Stop Simulation
Set the maximum wall clock time (in seconds) that triggers a simulation to stop.
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);
Configure the simulation stop criteria by setting the MaximumWallClock
property to 20
seconds. Leave the StopTime
and MaximumNumberOfLogs
properties at their default values of 10
seconds and Inf
, respectively.
set(configsetObj, 'MaximumWallClock', 20)
View the properties of configsetObj
.
get(configsetObj)
Active: 1 CompileOptions: [1x1 SimBiology.CompileOptions] Name: 'default' Notes: '' RuntimeOptions: [1x1 SimBiology.RuntimeOptions] SensitivityAnalysisOptions: [1x1 SimBiology.SensitivityAnalysisOptions] SolverOptions: [1x1 SimBiology.ODESolverOptions] SolverType: 'ode15s' StopTime: 10 MaximumNumberOfLogs: Inf MaximumWallClock: 20 TimeUnits: 'second' AmountUnits: '<automatic>' MassUnits: '<automatic>' Type: 'configset'
When you simulate modelObj
, the simulation stops when the simulation time reaches 10
seconds or the wall clock time reaches 20
seconds, whichever comes first.
Specify a List of Species to be Logged During Simulation
Load the Lotka-Volterra model.
sbioloadproject lotka;
Get the configset object of the lotka model m1
.
configset = getconfigset(m1);
Display the list of species whose data are logged by default during the simulation.
configset.RuntimeOptions.StatesToLog
ans = SimBiology Species Array Index: Compartment: Name: Value: Units: 1 unnamed x 1 2 unnamed y1 900 3 unnamed y2 900 4 unnamed z 0
Suppose you want to log just species y1
and y2
data. You can specify their names as a cell array of strings and set it to StatesToLog
property.
configset.RuntimeOptions.StatesToLog = {'y1','y2'};
Confirm the setting.
configset.RuntimeOptions.StatesToLog
ans = SimBiology Species Array Index: Compartment: Name: Value: Units: 1 unnamed y1 900 2 unnamed y2 900
Alternatively, you can specify an array of species objects (instead of strings) to StatesToLog
property.
y1 = m1.Species(2); y2 = m1.Species(3); configset.RuntimeOptions.StatesToLog = [y1, y2];
Simulate and plot the results. Notice that simulation results of only y1
and y2
are plotted.
sbioplot(sbiosimulate(m1));
To reset to the default list, set StatesToLog
to a string 'all'
, which means all species objects, all nonconstant compartment objects and all nonconstant parameter objects are logged by default. A nonconstant compartment or parameter means that its Constant property is set to false.
configset.RuntimeOptions.StatesToLog = 'all';
Simulate again. Notice all the species data are plotted.
sbioplot(sbiosimulate(m1));
Do not specify 'all'
as a cell string such as {'all'}
. If so, SimBiology interprets it as a species named all
.
Version History
Introduced in R2006bR2024a: Having duplicate model component names is no longer allowed
When you load a model that contains duplicate names, SimBiology automatically updates those names. SimBiology disambiguates the duplicate names by adding a suffix
"_N"
, where N is the first positive integer that results in a unique name. If there is an existing suffix, N will be incremented from that suffix. For example, if there are two model components named x_3, the function updates one of the names to x_4. If the existing suffix has leading zeros, the function omits the zeros in the new name. For instance, if x_003 is a duplicate name, it gets renamed to x_4. However, the function assumes that names with leading zeros and without leading zeros are different. For instance, x_005 and x_5 are considered to be different names.SimBiology issues an error if multiple model components (model, compartment, species, parameter, reaction, rule, event, observable, dose, and variant) have the same name. Within a single model, these components are required to have unique names even when they are of different types with the following two exceptions:
Species in different compartments can have the same name.
Parameters can have the same name if they are scoped to different parents. Specifically, you can use the same name for a model-scoped parameter and reaction-scoped parameters, where each reaction-scoped parameter belongs to a different reaction.
For details on how to reference model component names in expressions, see Guidelines for Referencing Names in Expressions.
R2022b: Having duplicate model component names issues a warning
SimBiology issues a warning if multiple model components have the same name.
R2022a: Having duplicate model component names will not be allowed in a future release
SimBiology will not allow you to have duplicate names for model components within a model.
R2016b: Active
property will be removed
The Active
property will be removed in a future release. Explicitly
specify a configset
object that you want to use as an input argument when
you simulate a model using sbiosimulate
.
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)