Documentation

Definitions and Evaluations of Rules

Overview

Rules are mathematical expressions that allow you to define or modify model quantities, namely compartment capacity, species amount, or parameter value.

Rules can take the form of initial assignments, assignments during the course of a simulation (repeated assignments), algebraic relationships, or differential equations (rate rules). Details of each type of rule are described next.

Initial Assignment

An initial assignment rule lets you specify the initial value of a model quantity as a numeric value or as a function of other model quantities. It is evaluated once at the beginning of a simulation.

An initial assignment rule is expressed as ```Variable = Expression```, and the rule is specified as the `Expression`. For example, you could write an initial assignment rule to set the initial amount of `species2` to be proportional to `species1` as ```species2 = k * species1``` where `k` is a constant parameter.

Initial assignments are evaluated in the order in which they occur in the model. Note that their effects can change when you reorder them.

Repeated Assignment

A repeated assignment rule lets you specify the value of a quantity as a numeric value or as a function of other quantities repeatedly during the simulation. It is evaluated at every time step, which are determined by the solver during the simulation process.

A repeated assignment rule is expressed as ```Variable = Expression```, and the rule is specified as the `Expression`. For example, to repeatedly assign the value of `50` to species `x` throughout the simulation, define the repeated assignment rule as `x = 100`.

Repeated assignments are reordered automatically and evaluated as a set of simultaneous constraints. Thus it is not possible to create circular sets of assignments such as `a = b + 1` and ```b = a + 1```.

Algebraic Rules

An algebraic rule lets you specify mathematical constraints on one or more model quantities that must hold during a simulation. It is evaluated continuously during a simulation.

An algebraic rule takes the form `0 = Expression`, and the rule is specified as the `Expression`. For example, if you have a mass conservation equation such as ```species_total = species1 + species2```, write the corresponding algebraic rule as `species1 + species2 - species_total`.

However, repeated assignment rules are mathematically equivalent to algebraic rules, but result in exact solutions instead of approximated solutions. Therefore, it is recommended that you use repeated assignment rules instead of algebraic rules whenever possible. Use algebraic rules only when:

• You cannot analytically solve the equations to get a closed-form solution. For example, there is no closed-form solution for `x^4 + ax^3 + bx^2 + cx + k = 0` whereas the closed-form solution for `kx – c = 0` is ```x = c/k```.

• You have multiple equations with multiple unknowns, and they could be inconvenient to solve.

 Tip   If you use an algebraic or rate rule to vary the value of a parameter or compartment during the simulation, make sure the `ConstantValue` property of the parameter or `ConstantCapacity` of the compartment is set to `false`.

Repeated Assignment vs. Algebraic Rules

Repeated assignment rules are mathematically equivalent to algebraic rules, but result in exact solutions. However, algebraic rules are solved numerically, and the accuracy depends on the error tolerances specified in the simulation settings. In addition, there are several advantages to repeated assignment rules such as better computational performance, more accurate results since no rules have to be solved numerically (hence no approximations), and sensitivity analysis support.

 Tip   If you can analytically solve for a variable, use a repeated assignment rule instead of an algebraic rule.In repeated assignment rules, the constrained variable is explicitly defined as the left-hand side, whereas in algebraic rules it is inferred from the degrees of freedom in the system of equations. See also Considerations When Imposing Constraints.

Rate Rules

A rate rule represents a differential equation and lets you specify the time derivative of a model quantity. It is evaluated continuously during a simulation.

A rate rule is represented as $\frac{dVariable}{dt}=Expression$, which is expressed in SimBiology as `Variable = Expression`. For example, if you have a differential equation for species x, $\frac{dx}{dt}=k\left(y+z\right)$, write the rate rule as: ```x = k * (y + z)```.

For examples of rate rules, see Create Rate Rules.

Writing Rule Expressions

Use MATLAB® syntax to write a mathematical expression for a rule. Note that no semicolon or comma is needed at the end of a rule expression. If your algebraic, repeated assignment, or rate rule expression is not continuous or differentiable, see Using Events to Address Discontinuities in Rule and Reaction Rate Expressions before simulating your model.

Considerations When Imposing Constraints

Suppose you have a species `y` whose amount is determined by the equation `y = m * x - c`. In SimBiology, the algebraic rule to describe this constraint is written as `m * x - c - y`. If you want to use this rule to determine the value of `y`, then `m`, `x`, and `c` must be variables or constants whose values are known or determined by other equations. Therefore, you must ensure that the system of equations is not overconstrained or underconstrained. For instance, if you have more equations than unknowns, then the system is overconstrained. Conversely, if you have more unknowns than the equations, then the system is underconstrained.

 Tip   The behavior of an underconstrained system could be fixed by adding additional rules or by setting the `ConstantValue` or `ConstantCapacity` or `ConstantAmount` property of some of the components in the model.

Conservation of Amounts When Simulation Time = 0 and Time > 0

During a simulation (i.e., at simulation time > 0), if there are any changes to the volume of a compartment where the species reside, SimBiology® conserves species amounts rather than concentrations.

At the beginning of a simulation (i.e., at time = 0), SimBiology evaluates the initial assignment rules one after another based on the order they appear in the model rather than as a set of mathematical constraints to be analyzed together. More specifically, at time = 0, SimBiology:

1. Initializes variables for species, compartments, and parameters using the `InitialAmount`, `Capacity`, and `Value` properties.

2. Updates the variables by evaluating initial assignment rules in the order they appear, thus not conserving species amounts if the compartment's volume changes.

3. Updates the variables by evaluating repeated assignment rules as a set of constraints that conserve species amounts when the compartment's volume changes.

At time > 0, SimBiology:

• Updates the variables by evaluating repeated assignment rules as a set of constraints that conserve species amounts when the compartment's volume changes.

SimBiology defines a compartment's volume before evaluating repeated assignments, and if you have a repeated assignment rule or an event that changes the volume and depends on time (either explicitly or implicitly), then you will see the effect of conservation of species amount(s) at time > 0.

Illustration of Conservation of Amounts

Consider the following example that illustrates such conservation of amounts. Suppose there is a one-compartment model with a drug that degrades according to the mass action kinetics with the forward reaction rate `k`. In order to distinguish the amount and concentration units, the drug is represented in two different species: one in an amount unit (milligram) and another one in a concentration unit (milligram/liter).

Compartment, Species, and ParameterInitial Values
`cell` (compartment)1.0 liter
`Amount_A` (drug A in amount units)0.0 milligram
`Concentration_A` (drug A in concentration units)100.0 milligram/liter
`k` (forward rate parameter)0.1 hour-1

Here is an initial assignment, repeated assignment, and event as they appear in the model.

Rules and EventFormula
Initial assignment`cell = 2.0`
Repeated assignment`Amount_A = Concentration_A * cell`
EventTrigger: `time >= 5`; EventFcns:``` cell = 4.0```

The initial compartment volume is doubled at time = 0 by the initial assignment, and doubled again at time >= 5 by the event.

The model is simulated, and the final results are shown in the following States versus Time figure.

At time = 0, the volume of the cell is doubled to 2.0 liters via the initial assignment, and consequently the amount of drug A becomes 200 milligram as defined by the repeated assignment. But the concentration does not change and is still 100 milligram/liter. This illustrates that the amount is not conserved at time = 0. However, at time >= 5, the volume of the `cell` becomes 5.0 liter and causes a drop in the concentration (milligram/liter) to conserve the amount (milligram) of drug A. Thus this example illustrates that at time > 0 the amount (instead of the concentration) of drug A is conserved at all times, but not at time = 0.