Main Content

SimBiology.CompileOptions

Compile options for SimBiology models

Description

This object defines the compile options for simulating SimBiology models. For instance, you can specify whether to perform unit conversion for the model before simulation. Compile options are checked during compile time.

Creation

This object is a property of a Configset object. Use dot notation or get or set to access and modify this object from a configset object.

Properties

expand all

Dimension of species name in expression, specified as 'concentration' or 'substance'.

This property specifies how SimBiology® interprets species names in expressions (namely reaction rate, rule, or event expressions). The valid property values are substance or concentration. If you specify InitialAmountUnits, SimBiology interprets species names appearing in expressions as concentration or substance amount according to the units specified, regardless of the value in DefaultSpeciesDimension. Thus, if DefaultSpeciesDimension is concentration and you specify species units as molecule, SimBiology interprets species names in expressions as substance. This interpretation applies even when DimensionalAnalysis is off.

You can find DefaultSpeciesDimension in the CompileOptions property.

When you set DefaultSpeciesDimension to substance, if you do not specify units, SimBiology interprets species names appearing in expressions as substance amounts, and does not scale by compartment capacity. To include a species concentration in an expression, divide by the appropriate compartment capacity in the expression. To specify compartment capacity in an expression enter the compartment name.

When you set DefaultSpeciesDimension to concentration, SimBiology interprets species names appearing in expressions as concentrations, and scales by compartment capacity in the expressions. To include a species amount in an expression, multiply by the species name by the appropriate compartment name in the expression.

For information on dimensional analysis for reaction rates, see How Reaction Rates Are Evaluated.

Data Types: char | string

Flag to perform dimensional analysis on a SimBiology model, specified as a numeric or logical 1 (true) or 0 (false).

The DimensionalAnalysis property specifies whether to perform dimensional analysis on the model before simulation. When DimensionalAnalysis is set to true, SimBiology checks whether the physical quantities of the units involved in reactions and rules, match and are applicable.

For example, consider a reaction a + b —> c. Using mass action kinetics, the reaction rate is defined as a*b*k, where k is the rate constant of the reaction. If you specify that initial amounts of a and b are 0.01M and 0.005M respectively, then units of k are 1/(M*second). If you specify k with another equivalent unit definition, for example, 1/[(moles/liter)*second], DimensionalAnalysis checks whether the physical quantities match. If the physical quantities do not match, you see an error and the model is not simulated.

Unit conversion requires dimensional analysis. If DimensionalAnalysis is off, and you turn UnitConversion on, then DimensionalAnalysis is turned on automatically. If UnitConversion is on and you turn off DimensionalAnalysis, then UnitConversion is turned off automatically.

If you have MATLAB® function calls in your model, dimensional analysis ignores any expressions containing function calls and generates a warning.

Warning

This property will be removed in a future release. Use UnitConversion instead.

Data Types: double | logical

This property is read-only.

Object type, specified as 'compileoptions'. When you create a SimBiology object, the value of Type is automatically defined.

Data Types: char

Flag to perform unit conversion for a SimBiology model before simulation, specified as numeric or logical 1 (true) or 0 (false).

When UnitConversion is set to true, SimBiology converts the matching physical quantities to one consistent unit system in order to resolve them. This conversion is in preparation for correct simulation, but species amounts are returned in the user-specified units.

For example, consider a reaction a + b —> c. Using mass action kinetics the reaction rate is defined as a*b*k where k is the rate constant of the reaction. If you specify that initial amounts of a and b are 0.01M and 0.005M respectively, then units of k are 1/(M*second). If you specify k with another equivalent unit definition, for example, 1/((molecules/liter)*second), UnitConversion occurs after DimensionalAnalysis.

Unit conversion requires dimensional analysis. If DimensionalAnalysis is off, and you turn UnitConversion on, then DimensionalAnalysis is turned on automatically. If UnitConversion is on and you turn off DimensionalAnalysis, then UnitConversion is turned off automatically.

If UnitConversion fails, then you see an error when you simulate.

If UnitConversion is set to false, the simulation uses the given object values.

Note

SimBiology uses units including empty units in association with DimensionalAnalysis and UnitConversion features.

  • When DimensionalAnalysis and UnitConversion are both false, units are not used. However, SimBiology still performs a minimum level of dimensional analysis to decide whether a reaction rate is in dimensions of amount/time or concentration/time.

  • When DimensionalAnalysis is true and UnitConversion is false, units (if not empty) must have consistent dimensions so that SimBiology can perform dimensional analysis. However, the units are not converted.

  • When UnitConversion is set to true (which requires DimensionalAnalysis to be true), SimBiology performs a dimensional analysis and converts everything to consistent units. Hence, you must specify consistent units, and no units can be empty. If you have a dimensionless parameter, you must still set its unit to dimensionless.

  • SimBiology allows exponentiation of any dimensionless quantity to any dimensionless power. For example, you can write the following expression if both x and a are dimensionless: (x + 3)^(a + 0.5)

Tip

If you have a custom function and UnitConversion is on, 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: double | logical

Examples

collapse all

Create a model.

m1 = sbiomodel("m1");

Get the configset object from the model.

cs = getconfigset(m1);

Get the CompileOptions object from the configset object.

copt = cs.CompileOptions;

Turn on unit conversion.

copt.UnitConversion = true;

Version History

Introduced in R2006b

expand all

See Also