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: . Suppose , then you can rewrite the equation as follows: . 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
MATLAB 命令
您点击的链接对应于以下 MATLAB 命令:
请在 MATLAB 命令行窗口中直接输入以执行命令。Web 浏览器不支持 MATLAB 命令。
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)