Main Content

SimBiology^{®} uses `AbsoluteTolerance`

and `RelativeTolerance`

to control the accuracy
of integration during simulation. Specifically, `AbsoluteTolerance`

is used to control
the largest allowable absolute error at any step during simulation.
It controls the error when a solution is small. Intuitively, when
the solution approaches 0, `AbsoluteTolerance`

is
the threshold below which you do not worry about the accuracy of the
solution since it is effectively 0. `RelativeTolerance`

controls
the relative error of a single step of the integrator. Intuitively,
it controls the number of significant digits in a solution, except
when it is smaller than the absolute tolerance, and $$-{\mathrm{log}}_{10}\left(RelativeTolerance\right)$$ is
the number of correct digits.

At each simulation step `i`

, the solver estimates
the local error `e`

in the state `j`

of
the simulation. The solver reduces the size of time step `i`

until
the error of the state satisfies:

$$\left|e\left(i,j\right)\right|\le \mathrm{max}\left(RelativeTolerance\ast \left|y\left(i,j\right)\right|,AbsoluteTolerance\left(i,j\right)\right)$$

Thus at state values of larger magnitude, the accuracy is determined
by `RelativeTolerance`

. As the state values approach
zero, the accuracy is controlled by `AbsoluteTolerance`

.

The correct choice of values for `RelativeTolerance`

and `AbsoluteTolerance`

varies
depending on the problem. The default values may work for first trials
of the simulation. As you adjust the tolerances, consider that there
are trade-offs between speed and accuracy:

If the simulation takes too long, you can increase (or loosen) the values of

`RelativeTolerance`

and`AbsoluteTolerance`

at the cost of some accuracy.If the results seem inaccurate, you can decrease (or tighten) the relative tolerance values by dividing with 10

^{N}, where N is a real positive number. But this tends to slow down the solver.If the magnitude of the state values is high, you can decrease the relative tolerance to get more accurate results.

How SimBiology uses `AbsoluteTolerance`

to
determine the error depends on whether the `AbsoluteToleranceScaling`

property
is enabled. By default, `AbsoluteToleranceScaling`

is
enabled which means each state has its own absolute tolerance that
may increase over the course of simulation:

$$AbsoluteTolerance\left(i,j\right)=CSAbsTol*Scale\left(i,j\right)$$

`CSAbsTol`

is the `AbsoluteTolerance`

property
defined in `SolverOptions`

of the active configuration
set object.

For a state that has a nonzero initial value, the scale is the maximum magnitude over the state, as seen over the simulation thus far:

$$Scale\left(i,j\right)=\mathrm{max}\left(\left|y(1:i,j)\right|\right)$$

For a state that has an initial value of zero, the scale is
estimated as the state value after taking a trial step of size `AbsoluteToleranceStepSize`

using the Euler
method. Let us call this value `ye(j)`

. Then:

$$Scale\left(i,j\right)=\mathrm{max}\left(\left|\left[ye(j);y(2:i,j)\right]\right|\right)$$

If an initial state is zero and has no dynamic at time = 0, then:

$$AbsoluteTolerance\left(i,j\right)=CSAbsTol$$

Doses, events, and initial assignment rules at simulation time = 0 are not considered when calculating absolute tolerance scaling.