AmountUnits

Amount unit used internally during simulation when UnitConversion is on

Description

This property defines the amount unit that SimBiology uses internally during model simulation when UnitConversion is on. You can set this to any character vector 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.

Note

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.

Characteristics

Applies to	Object: Configset
Data type	Character vector
Data values	Character vector specifying any amount unit. The default is <automatic>.
Access	Read/write for properties of Configset