Main Content

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

expand all

This property is read-only.

Mathematical expression to determine 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. For details, see Kinetic Law Definition.

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.

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

Data Types: char

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

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

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

Data Types: char | string

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

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

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.

This property is read-only.

Parent object, specified as a SimBiology.Reaction object.

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

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

The 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

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

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
copyobjCopy SimBiology object and its children
deleteDelete SimBiology object
displayDisplay summary of SimBiology object
getGet SimBiology object properties
getparameters (kineticlaw)Get specific parameters in kinetic law object
getspecies (kineticlaw)Get specific species in kinetic law object
renameRename SimBiology model component and update expressions
reorder (model, compartment, kinetic law)Reorder component lists
setSet SimBiology object properties
setparameter (kineticlaw)Specify specific parameters in kinetic law object
setspecies (kineticlaw)Specify species in kinetic law object

Examples

collapse all

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)'

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

expand all

Version History

Introduced in R2006b