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 10⁶) 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 to mole. However, if the model has quantity units in molecule, set the unit to molecule 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) where t is the time in hour and y 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, where time is the simulation time, t0 is a parameter defined as 1.0 hour, s0 is a parameter defined as 1.0 mole/liter, and s1 is the concentration of a species in mole/liter. Note that time and s1 do not have to be in the same units as t0 and s0, but they must be dimensionally consistent. For example, the time and s1 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 10⁶) 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 to kilogram.

• Set the AmountUnits to mole. However, if the model has quantity units in molecule, set the unit to molecule 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) where t is the time in hour and y 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, where time is the simulation time, t0 is a parameter defined as 1.0 hour, s0 is a parameter defined as 1.0 mole/liter, and s1 is the concentration of a species in mole/liter. Note that time and s1 do not have to be in the same units as t0 and s0, but they must be dimensionally consistent. For example, the time and s1 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 the SolverType property.

• If your model contains doses, you cannot specify 'ssa', 'expltau', or 'impltau' for the SolverType 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 updated TimeUnits 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

copyobj	Copy SimBiology object and its children
delete	Delete SimBiology object
display	Display summary of SimBiology object
get	Get SimBiology object properties
set	Set SimBiology object properties

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 R2006b

R2024a: 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.