SimBiology.Reaction

Object containing model reaction information

Description

The SimBiology.Reaction object represents a reaction, which describes a transformation, transport, or binding process that changes one or more species. Typically, the change is the amount of a species.

When you write a reaction string, use spaces before and after species names and stoichiometric values. Some examples of reactions are as follows.

Creatine + ATP <-> ADP + phosphocreatine

glucose + 2 ADP + 2 Pi -> 2 lactic acid + 2 ATP + 2 H2O

Use dot notation to query the object properties or change properties that are not read-only. You can also use the get and set commands.

The SimBiology Model Builder app also enables you to add reactions to your model and edit them. For an example, see Add and Configure Reactions.

Note

If you create a new reaction at the command line and do not specify its name, the reaction gets an automatic name Reaction_N, where N is a positive integer. N increases monotonically as you add more reactions.

If you copy a reaction using copyobj, the name of the copied reaction is generated by appending _N, where N is the smallest integer not in use by that prefix. For example, GivenName_1 gets copied to GivenName_1_1.

Creation

Use addreaction (model) to create and add a reaction to a SimBiology model.

Properties

Active — Flag to use reaction object during simulation

true or 1 (default) | false or 0

Flag to use the reaction object during simulation, specified as a numeric or logical 1 (true) or 0 (false). Use this property to test a model with and without a reaction.

Data Types: double | logical

KineticLaw — Kinetic law used for reaction rate

[] (default) | SimBiology.KineticLaw

Kinetic law used to define the reaction rate, specified as a KineticLaw object.

For information on dimensional analysis for reaction rates, see How Reaction Rates Are Evaluated.

Name — SimBiology.Reaction object name

character vector | string

SimBiology.Reaction object name, specified as a character vector or string.

For details on requirements and recommendations for naming SimBiology^® components, see Guidelines for Naming Model Components.

Data Types: char | string

Notes — Additional information

empty character array (default) | character vector | string

Additional information that you can add for SimBiology.Reaction, specified as a character vector or string.

Data Types: char | string

Parent — Parent object

SimBiology.Model object

This property is read-only.

Parent object, specified as a SimBiology.Model object.

Products — Reaction products

[] (default) | SimBiology.Species | array

Reaction products, specified as a SimBiology.Species object or array of such objects.

This property contains a 1-by-n species object array that indicates the species that are changed by the reaction. If the Reaction property is modified to use a different species, the Products property is updated accordingly.

You can add product species to the reaction with addproduct function. You can remove product species from the reaction with rmproduct. You can also update reaction products by setting the Reaction property with the function set.

Reactants — Reaction reactants

[] (default) | SimBiology.Species | array

Reaction reactants, specified as a SimBiology.Species object or array of such objects.

The Reactants property is a 1-by-n species object array of reactants in the reaction. If you modify the Reaction property to use a different reactant, the Reactants property will be updated accordingly.

You can add reactant species to the reaction with the addreactant method.

You can remove reactant species from the reaction with the rmreactant method. You can also update reactants by setting the Reaction property with the function set.

Reaction — Reaction

'' (default) | character vector | string

Reaction, specified as a character vector of string containing a valid reaction.

This property represents the chemical reaction that can change the amount of one or more species, for example, 'A + B –> C'.

See addreaction for more information on how the Reaction property is set.

Data Types: char | string

ReactionRate — Reaction rate equation

'' (default) | character vector | string

Reaction rate equation, specified as a character vector or string.

You can define a ReactionRate with or without the KineticLaw property. KineticLaw defines the type of reaction rate. The addkineticlaw function configures the ReactionRate based on the KineticLaw and the species and parameters specified in the kinetic law object properties SpeciesVariableNames and ParameterVariableNames.

The reaction takes place in the reverse direction if the Reversible property is true. This is reflected in ReactionRate. The ReactionRate includes the forward and reverse rate if reversible.

Use dot notation or the set function to specify the reaction rate equation. SimBiology adds species variables while creating a SimBiology.Reaction object using the addreaction method. You must add the parameter variables (to the SimBiology.Model object in this case).

After you specify the ReactionRate without KineticLaw and you later configure the reactionObj to use KineticLaw, the ReactionRate is unset until you specify SpeciesVariableNames and ParameterVariableNames.

For information on dimensional analysis for reaction rates, see How Reaction Rates Are Evaluated.

Note

If you set the ReactionRate property to an expression that is not continuous and differentiable, see Using Events to Address Discontinuities in Rule and Reaction Rate Expressions before simulating your model.

Data Types: char | string

Reversible — Flag to indicate if reaction is reversible

false or 0 (default) | true or 1

Flag to indicate if the reaction is reversible or irreversible, specified as a numeric or logical 1 (true) or 0 (false).

The rate of the reaction is defined by the ReactionRate property. For a reversible reaction, the reaction rate equation is the sum of the rate of the forward and reverse reactions. The type of reaction rate is defined by the KineticLaw property. If a reaction is changed from reversible to irreversible or vice versa after KineticLaw is assigned, the new ReactionRate is determined only if Type is MassAction. All other Types result in unchanged ReactionRate. For MassAction, the first parameter specified is assumed to be the rate of the forward reaction

Data Types: logical

Stoichiometry — Species coefficients in reaction

[] (default) | numeric array

Species coefficients in a reaction, specified as a 1-by-n numeric array. n is the sum of total number of products and reactants. In other words, the length of the Stoichiometry array is the sum of the Reactants array and the Products array.

Enter an array of nonzero numbers indicating the stoichiometry of reactants and products. The reactants of the reaction are defined with a negative number. The products of the reaction are defined with a positive number. For example, the reaction 3 H + A -> 2 C + F has the Stoichiometry value of [-3 -1 2 1].

When you configure this property, the Reaction property updates accordingly. In the above example, if you set the Stoichiometry value to [-2 -1 2 3], the reaction is updated to 2 H + A -> 2 C + 3 F.

To remove a product or reactant from a reaction, use the rmproduct or rmreactant function. Add a product or reactant and set stoichiometry with methods addproduct and addreactant.

ODE solvers support double stoichiometry values such as 0.5. Stochastic solvers and dimensional analysis currently support only integers in Stoichiometry, therefore you must balance the reaction equation and specify integer values for these two cases.

A -> null has a stoichiometry value of [-1]. null -> B has a stoichiometry value of [1].

Data Types: double

Tag — Object label

empty character array (default) | character vector | string

Object label, specified as a character vector or string.

Tip

Use this property to group objects and then use sbioselect to retrieve. For example, use the Tag property of reaction objects to group synthesis or degradation reactions. You can then retrieve all synthesis reactions using sbioselect. Similarly, for species objects you can enter and store classification information, for example, membrane protein, transcription factor, enzyme classifications, or whether a species is an independent variable. You can also enter the full form of the name of the species.

Data Types: char | string

Type — Object type

'reaction' (default)

This property is read-only.

Object type, specified as 'reaction'. When you create a SimBiology object, the value of Type is automatically defined.

Data Types: char

UserData — Data to associate with object

scalar | vector | string | ...

Data to associate with the object, specified as a numeric scalar, vector, string, or any other MATLAB data type.

The object does not use this data directly, but you can access it using dot notation or get.

Object Functions

addkineticlaw (reaction)	Create kinetic law object and add to reaction object
addproduct (reaction)	Add product species object to reaction object
addreactant (reaction)	Add species object as reactant to reaction object
copyobj	Copy SimBiology object and its children
delete	Delete SimBiology object
display	Display summary of SimBiology object
get	Get SimBiology object properties
rename	Rename SimBiology model component and update expressions
rmproduct (reaction)	Remove species object from reaction object products
rmreactant (reaction)	Remove species object from reaction object reactants
set	Set SimBiology object properties

Examples

Define Michaelis Menten Reaction Kinetics in SimBiology Model

Create a SimBiology model with a reaction.

m1 = sbiomodel("m1");
r1 = addreaction(m1,"A -> B");

Add a kinetic law for the reaction by using the built-in kinetic law (Michaelis Menten). Check the expression of the kinetic law.

kl = addkineticlaw(r1,"Henri-Michaelis-Menten");
kl.Expression

ans = 
'Vm*S/(Km + S)'

Query the parameters and species variables defined in the kinetic law.

kl.ParameterVariables

ans = 2x1 cell
    {'Vm'}
    {'Km'}

kl.SpeciesVariables

ans = 1x1 cell array
    {'S'}

Define Va and Ka as ParameterVariableNames, which correspond to the ParameterVariables Vm and Km defined in the Expression property of the kinetic law. To set these variables, first create the parameter variables as parameter objects (p1, p2) with the names Va and Ka, and then add them to the kinetic law object kl. The species object with the name A is created when the reaction object r1 is created and need not be redefined.

p1 = addparameter(kl,"Va");
p2 = addparameter(kl,"Ka");

Set the variable names for the kinetic law object.

kl.ParameterVariableNames = ["Va","Ka"];
kl.SpeciesVariableNames   = ["A"];

Verified that the reaction rate is expressed correctly in the ReactionRate property of the reaction object

r1.ReactionRate

ans = 
'Va*A/(Ka+A)'

Define a Custom Hill Kinetic Law that Works with Dimensional Analysis

This example shows how to define a custom reaction rate for the Hill kinetics that is compatible with DimensionalAnalysis feature of SimBiology.

This example is useful especially if you are using the built-in Hill kinetic law, but have the kinetic reaction with a non-integer exponent and cannot verify the model because dimensional analysis failed. The built-in Hill kinetic law has the following expression: $$\frac{V_m*S^n}{K_p+S^n}$$. Suppose $$K_p=K_h{}^n$$, then you can rewrite the equation as follows: $$\frac{V_m}{{\left(\frac{K_h}{S}\right)}^n+1}$$. The redefined Hill kinetic equation is compatible with Dimensional Analysis and allows you to have a non-integer exponent.

Create a SimBiology model.

m1 = sbiomodel('m1');

Add a compartment, two species, and a reaction.

c1 = addcompartment(m1, 'cell');
s1 = addspecies(m1,'a');
s2 = addspecies(m1,'b');
r1 = addreaction(m1, 'a -> b');

Add a predefined a Hill kinetic law for the reaction.

k1 = addkineticlaw(r1, 'Hill-Kinetics');

Display the rate expression of the built-in kinetic law.

k1.Expression

ans =

Vm*S^n/(Kp + S^n)

Define parameters, values, and units.

p1 = addparameter(k1, 'Vm', 1.0);
p2 = addparameter(k1, 'n', 1.5);
p3 = addparameter(k1, 'Kp', 2.828);

set(k1, 'ParameterVariableNames', {'Vm','n','Kp'});
set(k1, 'SpeciesVariableNames', {'a'});
set(s1, 'InitialAmount', 2.0);

set(s1, 'InitialAmountUnits', 'mole/liter');
set(s2, 'InitialAmountUnits', 'mole/liter');
set(c1, 'CapacityUnits', 'liter');
set(p1, 'ValueUnits', 'mole/liter/second');
set(p2, 'ValueUnits', 'dimensionless');
set(p3, 'ValueUnits', 'mole/liter');

Verify the model.

verify(m1)

Error using SimBiology.Model/verify
--> Error reported from Dimensional Analysis:
Dimensional analysis failed for reaction 'a -> b'.
When using the power function, both the base and exponent must be dimensionless or the exponent must be an explicit
integer constant (for example 2 in 'x^2').

You are seeing the error message because SimBiology only allows exponentiation of any dimensionless quantity to any dimensionless power.

Redefine the reaction rate so that it is compatible with dimensional analysis and allows a non-integer exponent.

r1.ReactionRate = 'Vm / ( (Kh/a)^n + 1 )';
k1.KineticLaw = 'Unknown';

Define the value and units for Kh parameter.

p4 = addparameter(k1, 'Kh', 2.0);
set(p4, 'ValueUnits', 'mole/liter');

Verify the model.

verify(m1)

You no longer see the error message.

Simulate the model.

[t,x,names] = sbiosimulate(m1);

Plot the results.

plot(t,x);
xlabel('Time');
ylabel('Amount');
legend(names);

Version History

Introduced in R2006b