Definitions and Evaluations of Reactions in SimBiology Models

A reaction is a mathematical expression that describe a transformation, transport, or binding process that changes one or more species. Typically, an amount of a species is changed through a reaction.

In SimBiology^®, a reaction is represented by a SimBiology.Reaction object, which has the following properties.

Reaction property — Mathematical expression that describes the reaction
ReactionRate property — Mathematical expression that defines the rate at which the reactants combine to form products. You can provide this information explicitly or use the KineticLaw property to populate this information.
KineticLaw property — SimBiology.KineticLaw object that specifies a rate law that defines the type of reaction rate, or []. Examples include Henri-Michaelis-Menten and Mass Action. The object also specifies species, or parameters. It serves as a template for a reaction rate and provides a convenient way of applying a specific rate law to multiple reactions. If you use this property, it automatically populates the ReactionRate property.

A reaction is scoped to a model.

For information about...	See...
Creating and adding a reaction to a model	`addreaction`
Methods and properties of a reaction	`SimBiology.Reaction`
Creating and adding a kinetic law to a reaction	`addkineticlaw`
Methods and properties of a kinetic law	`SimBiology.KineticLaw`

Writing Reaction Expressions

Use standard chemistry reaction notation to create the mathematical expression for a reaction (Reaction property of SimBiology.Reaction).

Following are rules for writing reaction expressions:

Use spaces before and after species names and stoichiometric values.
Stoichiometry values must be positive.
If a stoichiometry value is not specified, it is assumed to be 1.
In a model with a single compartment, specify species using speciesName. In a model with multiple compartments, specify species using qualified names: compartmentName.speciesName. For example, nucleus.DNA denotes the species DNA in the compartment nucleus.
Enclose names with non-alphanumeric characters (including spaces) in brackets.
Reactions can be reversible (<->) or irreversible (->).

Examples of reaction expressions include:

Creatine + ATP <-> ADP + phosphocreatine
glucose + 2 ADP + 2 Pi -> 2 lactic acid + 2 ATP + 2 H2O
cytoplasm.A -> nucleus.A
[compartment 1].[species A] -> [compartment 2].[species A]

Note

Same species can be used multiple times in the list of reactions or products. The expression '2 A' is equivalent to 'A + A'.

Writing Reaction Rate Expressions Explicitly

Use any valid MATLAB^® code to create the mathematical expression for a reaction rate (ReactionRate property of SimBiology.Reaction). The reaction rate can specify compartments, species, or parameters.

Following are rules for writing reaction rate expressions:

The expression must be a single MATLAB statement that returns a scalar.
In a model with a single compartment, specify species using speciesName. In a model with multiple compartments, specify species using qualified names: compartmentName.speciesName. For example, nucleus.DNA denotes the species DNA in the compartment nucleus.
Enclose names with non-alphanumeric characters (including spaces) in brackets.
Do not end the reaction rate expression with any of the following:
- Semicolon
- Comma
- Comment text preceded by %
- Line continuations indicated by ...

For example, if you have the following reaction expression:

Creatine + ATP <-> ADP + phosphocreatine

and the reaction follows Mass Action kinetics, then the reaction rate expression would be:

K*Creatine*ATP - Krev*ADP*phosphocreatine

Tip

If your reaction rate expression is not continuous and differentiable, see Using Events to Address Discontinuities in Rule and Reaction Rate Expressions before simulating your model.

Creating Reaction Rate Expressions Using Kinetic Law Objects

A SimBiology.KineticLaw object is scoped to a reaction and specifies:

A rate law that defines the type of reaction rate. Examples include Henri-Michaelis-Menten and Mass Action.
species and parameters

A SimBiology.KineticLaw object serves as a template for a reaction rate and provides a convenient way of applying a specific rate law to multiple reactions. You can use this object to create a reaction rate, which populates the ReactionRate property of the SimBiology.Reaction object.

For example, if you create a SimBiology.KineticLaw object that specifies Henri-Michaelis-Menten for the KineticLawName, species S, and parameters Vm and Km, the reaction rate law is:

$\frac{V_{m} S}{K_{m} + S}$

Then if you create a reaction object that specifies the previous SimBiology.KineticLaw object and species the following reaction expression:

A -> B

with Vm = Va and Km = Ka and S = A, then the reaction rate equation is:

$\frac{V_{a} A}{K_{a} + A}$

The built-in Abstract Kinetic Laws library provides a list of predefined reaction rates that follow particular kinetics, such as the mass action or Michaelis-Menten kinetics. If you are using SimBiology Model Builder to create a reaction, the app uses MassAction by default and automatically creates and maps the species and parameters needed by the reaction rate. For other kinetic laws, only parameters are created and mapped. You need to create and map the species manually. You may use the Unknown kinetic law to define a custom reaction rate with its own parameters. You must define and add the species and parameters needed by the custom rate. For more information, see SimBiology Model Component Libraries or SimBiology.AbstractKineticLaw.

As long as the reaction rates are equivalent, there is no practical difference among using Unknown kinetic law, any other kinetic law, or not using a kinetic law at all. However, there are two exceptions.

For some models with linear differential equations using the MassAction kinetic law, SimBiology automatically uses a linear solver which is faster than other solvers.
If you have reactions involving multiple compartments, then there is a difference in behavior for using MassAction versus Unknown kinetic law. For details, see Reactions Spanning Multiple Compartments.

Examples of Creating Reaction Rates

Example of Creating a Zero-Order Reaction

With a zero-order reaction, the reaction rate does not depend on the concentration of reactants. Examples of zero-order reactions are synthesis from a null species, and modeling a source species that is added to the system at a specified rate.

     reaction: null -> P
reaction rate: k mole/second
      species: P =  0 mole
   parameters: k =  1 mole/second

Note

When specifying a null species, the reaction rate must be defined in units of amount per unit time not concentration per unit time.

Entering the reaction above into SimBiology Model Analyzer and simulating produces the following result.

Zero-Order Mass Action Kinetics

Note

If the amount of a reactant with zero-order kinetics reaches zero before the end of a simulation, then the amount of reactant can go below zero regardless of the solver or tolerances you set.

Examples of Creating Other Reactions

For examples of creating other reaction rates, see Define Reaction Rates with Mass Action Kinetics and Define Reaction Rates with Enzyme Kinetics.

How Reaction Rates Are Evaluated

Reaction Rate Dimensions

When calculating species fluxes, SimBiology must determine whether you specified reaction rates in dimensions of amount/time or concentration/time. When all compartments in a model have a capacity of one unit, amount and concentration are numerically equivalent.

For all other models, the numerical results of the simulation depend on which interpretation SimBiology selects. SimBiology determines whether a reaction rate is in dimensions of amount/time or concentration/time via dimensional analysis of ReactionRate expressions. This minimum level of dimensional analysis always occurs, even when DimensionalAnalysis and UnitConversion are off.

The DefaultSpeciesDimension property defines the dimensions of species appearing in a reaction rate. SimBiology infers the dimensions of parameters appearing in a reaction rate from their ValueUnits property. If any parameters appearing in a reaction rate expression do not have units, SimBiology interprets the reaction rate in dimensions of amount/time. Therefore, the only way to specify that a reaction rate has dimensions of concentration/time is to assign appropriate units to all parameters.

Reactions Spanning Multiple Compartments

Specify reactions that span compartments using the syntax compartment1Name.species1Name –> compartment2Name.species2Name. The reaction rate dimensions must resolve to amount/time if either of the following conditions are true:

Reactant species are in different compartments.
The reaction is reversible mass action and the products are in multiple compartments.

Note

The MassAction and Unknown kinetic laws can have different simulation results even when the reaction rate is the same. This can happen when you have a reversible reaction with species in different compartments. The difference in simulation results is because of the volume-scaling performed by SimBiology during the dimensional analysis. For details, see Derive ODEs from SimBiology Reactions. Specifically, for MassAction, SimBiology uses corresponding compartment volumes to multiply the forward and reverse rates. However, for Unknown and other built-in kinetic laws, SimBiology multiplies the entire rate by only one compartment which contains the reactants. To see exactly what compartment volumes are used for scaling, use getequations or open the Equations view from the SimBiology app and check the ODEs section.

Examples

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

If, in the previous example, you specify that initial amounts of a and b are 0.01 and 0.005 respectively, without specifying units, SimBiology checks whether DefaultSpeciesDimension is substance or concentration. If DefaultSpeciesDimension is concentration, and you set units on the rate constant such that the reaction rate dimensions resolve to concentration/time, SimBiology scales the species amounts for compartment capacity, and returns the species values in concentration.

If you specify initial amounts of a and b as 0.01 molarity and 0.005 mole respectively, include the volume scaling for b in the reaction rate expression. Include volume scaling in the rate constant, and set the units of the rate constant accordingly (1/(mole*second) for concentration/time, or 1/(molarity*second) for amount/time).

Viewing Equations for Reactions

You can view the system of equations that SimBiology creates when you build a model using reaction expressions. For details, see View Model Equations.