## 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 `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 — Object that specifies a rate law that defines the type of reaction rate. Examples include Henri-Michaelis-Menten and Mass Action. The object also specifies `species objects`, or ```parameter objects```. This property is optional. 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.

Creating and adding a reaction to a model`addreaction`
Methods and properties of a reaction```reaction object```
Creating and adding a kinetic law to a reaction`addkineticlaw`
Methods and properties of a kinetic law```KineticLaw object```

### Writing Reaction Expressions

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

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 a ```reaction object```). 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 `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 `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 ```reaction object```.

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

`${V}_{m}*S/\left({K}_{m}+S\right)$`

Then if you create a `reaction object` that specifies the previous `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:

### 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 the software 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 Deriving ODEs from 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.