Learn more about SimBiology

Changing Model Component Values Using Rules

On this page…
What Is a Rule? What Is an initialAssignment Rule? What Is a repeatedAssignment Rule? What Is an Algebraic Rule? What Is a Rate Rule? Typical Uses of Rate Rules

What Is a Rule?

A rule is a model component that specifies a mathematical relationship between model component values during a simulation. Rules let you specify mathematical relationships involving the following model components values:

• parameter value

• species amount

• compartment capacity

Examples of using a rule include:

• Specify values for model components that are required for comparison with experimental data. For example, specify the active fraction of total protein.

• Assign values to model components based on the values of other components in the model. For example, define a parameter's value as being proportional to a species or another parameter.

• Define mass balance equations.

• For species, use rate rules as an alternative to the differential rate expression generated from reactions.

The types of rules in SimBiology are as follows:

• initialAssignment — Lets you specify the initial value of a parameter, species, or compartment capacity, as a function of other model component values in the model.

• repeatedAssignment — Lets you specify a value that holds at all times during simulation, and is a function of other model component values in the model.

• algebraic — Lets you specify mathematical constraints on one or more parameters, species, or compartments that must hold during a simulation.

• rate — Lets you specify the time derivative of a parameter value, species amount, or compartment capacity.

Back to Top

What Is an initialAssignment Rule?

initialAssignment rules are evaluated once at the beginning of a simulation. initialAssignment rules are expressed as Variable = Expression.

For example, use the rule to set the initial amount of species1 to be proportional to species2. This lets you change the initial conditions for both species by updating the value for one.

species1 = k*species2

Back to Top

What Is a repeatedAssignment Rule?

repeatedAssignment rules are evaluated at every time step during a simulation. repeatedAssignment rules are expressed as Variable = Expression.

For example, if you want the capacity of a compartment (cytoplasm) to change in response to a change in the concentration of a species (x), use the rule to set the capacity of cytoplasm to be proportional to x.

cytoplasm = k*x

Where k is a specified constant.

repeatedAssignment rules are mathematically equivalent to algebraic rules, but result in exact solutions, compared to algebraic rules whose accuracy depends on the tolerance specified in the configuration set used while performing simulations.

Tip   If you can solve for the variable, use a repeatedAssignment rule instead of an algebraic rule. In repeatedAssignment 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 in the SimBiology User's Guide.

Back to Top

What Is an Algebraic Rule?

An algebraic rule is a convenient way to define mathematical relationships between states. A model can consist of a combination of differential and algebraic relationships.

An algebraic rule is a constraint that is enforced by the solver during simulation. You can use algebraic rules to specify the dynamics for parameters, species, and compartments that are not driven by one or more reactions. The accuracy of the solution depends on the tolerance specified in the configuration set used while performing simulations.

An algebraic rule is defined by the equation:

f(t,x)= 0

Where t is simulation time. The variable x is species amount, parameter value, or compartment capacity.

An example of an algebraic rule is,

x*log(x) - 3

Considerations When Imposing Constraints

Consider the mathematical constraint y = m*x - c. In the software this rule 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. In general, the degree of freedom available must match the number of constraints. Therefore, you must ensure that the equation is not overconstrained or underconstrained. In this example, if the equation is underconstrained, it is unclear which variable is being determined by the expression.

Back to Top

What Is a Rate Rule?

A rate rule is defined by the equation:

dx/dt = f(t,W)

The variable x can be a species amount, parameter value, or compartment capacity. The function f(W) is an expression that can include other species and parameters. Enter a rate rule using the form

x = f(t,W)

Back to Top

Typical Uses of Rate Rules

When the Rate of Change Is Constant

You can increase or decrease the amount or concentration of a species by a constant value using a zero order rate rule. For example, suppose species c increases by a constant rate k.

     reaction: none
rate equation: none
    rate rule: dc/dt = k
     species : c = 10 mole(initial amount)
   parameters: k = 1 mole/second

The analytical solution is c = kt + c_o, where c_o is the initial amount or concentration of the species c.

Enter the rule described above as c = k. From the RuleType list, select rate, enter the values for c and k, and then simulate.

Alternatively, you could model a constant increase in a species using Mass Action reaction null -> C.

When the Rate of Change Is Exponential

You can change the amount of a species similar to a first-order reaction using a first-order rate rule. For example, suppose the species c decays exponentially.

The solution for the rate rule dc/dt = -k*c is .

Enter the rate rule described above and the simulate.

Notice that if the amount of a species c is determined by a rate rule and c is also in a reaction, c must have itsBoundaryCondition property set to true. For example, with a reaction a -> c and a rate rule dc/dt = k*c, select the BoundaryCondtion for c so that a differential rate term is not created from the reaction. The amount of c is determined solely by a differential rate term from the rate rule.

If the boundary condition is not selected, you will get the following error message:

Invalid rule variable 'in a reaction or another rule'.

When the Rate of Change Is Determined by Another Species

A species from one reaction can determine the rate of another reaction if it is in the second reaction rate equation. Similarly, a species from a reaction can determine the rate of another species if it is in the rate rule that defines that other species.

     reaction: a -> b
rate equation: v = -k1*a
    rate rule: dc/dt = k2*a
      species: a = 10 mole
               b =  0 mole
               c =  5 mole
   parameters: k1 = 1 1/second
               k2 = 1 1/second 

The solution for the species in the reaction are:

 and 

With the rate rule dc/dt = k₂*a dependent on the reaction, dc/dt = k₂(a_oe^-k1t), and the solution is:

c = co + k2ao/k1(1 - e-k1t)

Enter the reaction and rule described above and simulate.

Expressing Differential Rate Equations as Rules

Many mathematical models in the literature are described with differential rate equations for the species. You could manually convert the equations to reactions, or you could enter the equations as rate rules. For example, you could enter the following differential rate equation for a species C,

as a rate rule in SimBiology:

C = vi - (vd*X*C)/(Kc + C) - kd*C

Back to Top

Scoping Parameters for Reactions, Rules, and Events

Changing Model Component Values Using Events

© 1984-2009- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS