SimBiology.KineticLaw

Kinetic law information for reaction

Description

The kinetic law object holds information about the abstract kinetic law applied to a reaction and provides a template for the reaction rate. SimBiology^® uses the information you provide in a fully defined kinetic law object to determine the ReactionRate property in the reaction object.

When you first create a kinetic law object, you must specify the name of the abstract kinetic law to use. SimBiology fills in the KineticLawName property and the Expression property in the kinetic law object with the name of the abstract kinetic law you specified and the mathematical expression respectively. The software also fills in the ParameterVariables property and the SpeciesVariables property of the kinetic law object with the values found in the corresponding properties of the abstract kinetic law object.

To obtain the reaction rate, you must fully define the kinetic law object:

1. In the ParameterVariableNames property, specify the parameters from the model that you want to substitute in the expression (Expression property).

2. In the SpeciesVariableNames property, specify the species from the model that you want to substitute in the expression.

   SimBiology substitutes in the expression, the names of parameter variables and species variables in the order specified in the ParameterVariables and SpeciesVariables properties respectively.

   The software then shows the substituted expression as the reaction rate in the ReactionRate property of the reaction object. If the kinetic law object is not fully defined, the ReactionRate property remains '' (empty).

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.

Creation

Use addkineticlaw (reaction) to create and add a KineticLaw object and add to a reaction.

Properties

Expression — Mathematical expression to determine reaction rate equation

character vector

This property is read-only.

Mathematical expression to determine the reaction rate equation, specified as character vector.

The property contains a mathematical expression that is used to determine the ReactionRate property of a SimBiology.Reaction object. It is a reaction rate expression assigned by the kinetic law definition used by the reaction. The kinetic law being used is indicated by the property KineticLawName. You can configure Expression for user-defined kinetic laws, but not for built-in kinetic laws.

Note

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

For details, see Kinetic Law Definition.

Example: 'Vm*S/(Km + S)'

Data Types: char

KineticLawName — Name of kinetic law applied to reaction

character vector

This property is read-only.

Name of kinetic law applied to reaction, specified as a character vector. The property can be any valid name from the built-in or user-defined kinetic law library. See for more information.

You can find the KineticLawName list in the kinetic law library by using the command sbiowhos -kineticlaw. You can create a kinetic law definition with sbioabstractkineticlaw and add it to the library using sbioaddtolibrary.

Data Types: char

Name — SimBiology.KineticLaw object name

character vector | string

SimBiology.KineticLaw 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.KineticLaw, specified as a character vector or string.

Data Types: char | string

ParameterVariableNames — Names of reaction rate parameters

cell array of character vectors

Names of reaction rate parameters, specified as a cell array of character vectors.

The property shows the parameters used by the kinetic law object to determine the ReactionRate equation in the reaction object. Use setparameter (kineticlaw) to assign ParameterVariableNames. When you assign species to ParameterVariableNames, SimBiology maps these parameter names to ParameterVariables in the kinetic law object.

If the reaction is using a kinetic law, the ReactionRate property of a reaction object shows the result of a mapping from a Kinetic Law Definition. The ReactionRate is determined by the kinetic law object Expression property by mapping ParameterVariableNames to ParameterVariables and SpeciesVariableNames to SpeciesVariables.

Data Types: cell

ParameterVariables — Parameters in kinetic law definition

cell array of character vectors

This property is read-only.

Parameters used in the kinetic law definition, specified as a cell array of character vectors.

The property contains the names of parameter variables that are used in the Expression property of the kinetic law object. This property specifies the parameters in the ReactionRate equation.

For more information, see Kinetic Law Definition.

Data Types: cell

Parameters — Parameter objects

array of SimBiology.Parameter objects

This property is read-only.

Parameter objects in a SimBiology.KineticLaw object, specified as an array of SimBiology.Parameter objects.

The scope of a parameter object is hierarchical and is defined by the parameter’s parent. If a parameter is defined with a kinetic law object as its parent, then only the kinetic law object can use the parameter. If a parameter object is defined with a model object as its parent, then components such as rules, events, and kinetic laws (reaction rate equations) can use the parameter.

You can add a parameter to a model object, or kinetic law object with addparameter (model, kineticlaw) and delete it with the method delete.

You can view parameter object properties with the get command and configure properties with the set command.

Parent — Parent object

SimBiology.Reaction object

This property is read-only.

Parent object, specified as a SimBiology.Reaction object.

SpeciesVariableNames — Names of species in reaction rate equation

cell array of character vectors

Names of species in the reaction rate equation, specified as a cell array of character vectors.

The property shows the species used by the kinetic law object to determine the ReactionRate equation in the reaction object. Use setspecies to assign SpeciesVariableNames. When you assign species to SpeciesVariableNames, SimBiology maps these species names to SpeciesVariables in the kinetic law object.

The ReactionRate property of a reaction object shows the result of a mapping from the Kinetic Law Definition. The ReactionRate is determined by the kinetic law object Expression property by mapping ParameterVariableNames to ParameterVariables and SpeciesVariableNames to SpeciesVariables.

Data Types: cell

SpeciesVariables — Names of species in kinetic law definition

cell array of character vectors

This property is read-only.

Species used in the kinetic law definition, specified as a cell array of character vectors.

The property shows species variables that are used in the Expression property of the kinetic law object to determine the ReactionRate equation in the reaction object.

Data Types: cell

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

'kineticlaw' (default)

This property is read-only.

Object type, specified as 'kineticlaw'. 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

addparameter (model, kineticlaw)	Create parameter object and add to model or kinetic law object
copyobj	Copy SimBiology object and its children
delete	Delete SimBiology object
display	Display summary of SimBiology object
get	Get SimBiology object properties
getparameters (kineticlaw)	Get specific parameters in kinetic law object
getspecies (kineticlaw)	Get specific species in kinetic law object
rename	Rename SimBiology model component and update expressions
reorder (model, compartment, kinetic law)	Reorder component lists
set	Set SimBiology object properties
setparameter (kineticlaw)	Specify specific parameters in kinetic law object
setspecies (kineticlaw)	Specify species in kinetic law object

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 Mass Action Reaction Kinetics in SimBiology Model

Create a SimBiology model with a reaction.

m1 = sbiomodel("m1");
r1 = addreaction(m1,"a + b -> c + d");

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

kl = addkineticlaw(r1,"MassAction");
kl.Expression

ans = 
'MassAction'

Assign the rate constant for the reaction.

kl.ParameterVariableNames = "k";

Check the reaction rate.

r1.ReactionRate

ans = 
'k*a*b'

More About

Kinetic Law Definition

The kinetic law definition provides a mechanism for applying a specific rate law to multiple reactions. It acts as a mapping template for the reaction rate. The kinetic law is defined by a mathematical expression, which is defined in the property Expression, and includes the species and parameter variables used in the expression. The species variables are defined in the SpeciesVariables property, and the parameter variables are defined in the ParameterVariables property of the kinetic law object.

If a reaction is using a kinetic law definition, the ReactionRate property of the reaction object shows the result of a mapping from the kinetic law definition. To determine ReactionRate, the species variables and parameter variables that participate in the reaction rate should be mapped in the kinetic law for the reaction. In this case, SimBiology determines the ReactionRate by using the Expression property of the abstract kinetic law object, and by mapping SpeciesVariableNames to SpeciesVariables and ParameterVariableNames to ParameterVariables.

For example, the kinetic law definition Henri-Michaelis-Menten has the Expression Vm*S/(Km+S), where Vm and Km are defined as parameters in the ParameterVariables property of the abstract kinetic law object, and S is defined as a species in the SpeciesVariable property of the abstract kinetic law object.

By applying the Henri-Michaelis-Menten kinetic law to a reaction A -> B with Va mapping to Vm, A mapping to S, and Ka mapping to Km, the rate equation for the reaction becomes Va*A/(Ka+A).

The exact expression of a reaction using MassAction kinetic law varies depending upon the number of reactants. Thus, for mass action kinetics the Expression property is set to MassAction because in general for mass action kinetics the reaction rate is defined as

$$r=k{\displaystyle \prod _{i=1}^{nr}{[Si]}^{m_i}}$$

where [Si] is the concentration of the ith reactant, mi is the stoichiometric coefficient of [Si], nr is the number of reactants, and k is the mass action reaction rate constant.

SimBiology software contains some built-in kinetic laws. You can also define your own kinetic laws. To find the list of available kinetic laws, use the sbiowhos -kineticlaw command (sbiowhos). You can create a kinetic law definition with the function sbioabstractkineticlaw and add it to the library using sbioaddtolibrary.

Version History

Introduced in R2006b

R2024a: Having duplicate model component names is no longer allowed

• When you load a model that contains duplicate names, SimBiology automatically updates those names. SimBiology disambiguates the duplicate names by adding a suffix "_N", where N is the first positive integer that results in a unique name. If there is an existing suffix, N will be incremented from that suffix. For example, if there are two model components named x_3, the function updates one of the names to x_4. If the existing suffix has leading zeros, the function omits the zeros in the new name. For instance, if x_003 is a duplicate name, it gets renamed to x_4. However, the function assumes that names with leading zeros and without leading zeros are different. For instance, x_005 and x_5 are considered to be different names.

• SimBiology issues an error if multiple model components (model, compartment, species, parameter, reaction, rule, event, observable, dose, and variant) have the same name. Within a single model, these components are required to have unique names even when they are of different types with the following two exceptions:

  • Species in different compartments can have the same name.

  • Parameters can have the same name if they are scoped to different parents. Specifically, you can use the same name for a model-scoped parameter and reaction-scoped parameters, where each reaction-scoped parameter belongs to a different reaction.

  For details on how to reference model component names in expressions, see Guidelines for Referencing Names in Expressions.

R2022b: Having duplicate model component names issues a warning

SimBiology issues a warning if multiple model components have the same name.

R2022a: Having duplicate model component names will not be allowed in a future release

SimBiology will not allow you to have duplicate names for model components within a model.