SimBiology.AbstractKineticLaw

Kinetic law information in library

Description

The SimBiology.AbstractKineticLaw object represents a kinetic law definition, which provides a mechanism for applying a rate law to multiple reactions. The information in this object acts as a mapping template for the reaction rate. The kinetic law definition specifies a mathematical relationship that defines the rate at which reactant species are produced and product species are consumed in the reaction. The expression is shown in the Expression property. The species variables are defined in the SpeciesVariables property, and the parameter variables are defined in the ParameterVariables property of the abstract kinetic law object. For an explanation of how the kinetic law definition relates to the kinetic law object, see KineticLaw object.

Create your own kinetic law definition and add it to the kinetic law library with the sbioaddtolibrary function. You can then use the kinetic law to define a reaction rate. To retrieve a kinetic law definition from the user-defined library, first create a root object using sbioroot, then use the command get(rootObj.UserDefinedLibrary,'KineticLaws').

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 and kinetic laws to your model and edit them. For an example, see Add and Configure Reactions. For more information about built-in libraries, see SimBiology Model Component Libraries.

Creation

Use sbioabstractkineticlaw to create a SimBiology.AbstractKineticLaw object.

Properties

Expression — Mathematical expression to determine reaction rate equation

string scalar | character vector

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 | string

Name — SimBiology.AbstractKineticLaw object name

character vector | string

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

Data Types: char | string

ParameterVariables — Parameters in kinetic law definition

cell array of character vectors

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 details, see Kinetic Law Definition.

Data Types: cell

Parent — Parent object

[] (default) | SimBiology.Root object

This property is read-only.

Parent object, specified as an empty array [] or SimBiology Root object.

The default value is [] until SimBiology.AbstractKineticLaw is added to the library. The Parent property becomes the SimBiology.Root object after addition to the library.

SpeciesVariables — Names of species in kinetic law definition

cell array of character vectors

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

'abstract_kinetic_law' (default)

This property is read-only.

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

delete	Delete SimBiology object
display	Display summary of SimBiology object
findUsages	Find out how an AbstractKineticLaw object is used
get	Get SimBiology object properties
rename	Rename SimBiology model component and update expressions
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 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.