Main Content

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

expand all

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

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 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

Compile options, specified as a CompileOptions object. Use this object to specify the default species dimension and to enable unit conversion.

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 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

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.

Data Types: double

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.

Data Types: double

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

Additional information that you can add for SimBiology.Configset, specified as a character vector or string.

Data Types: char | string

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.

Options for local sensitivity analysis, specified as a SensitivityAnalysisOptions object.

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

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

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

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

copyobjCopy SimBiology object and its children
deleteDelete SimBiology object
displayDisplay summary of SimBiology object
getGet SimBiology object properties
setSet SimBiology object properties

Examples

collapse all

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

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));

Figure contains an axes object. The axes object with title States versus Time, xlabel Time, ylabel States contains 2 objects of type line. These objects represent y1, y2.

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));

Figure contains an axes object. The axes object with title States versus Time, xlabel Time, ylabel States contains 4 objects of type line. These objects represent x, y1, y2, z.

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

expand all