KineticLaw object

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. In the model, the SimBiology^® software 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. The SimBiology software 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.

   The SimBiology software 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).

For links to kinetic law object property reference pages, see Property Summary.

Properties define the characteristics of an object. Use the get and set commands to list object properties and change their values at the command line. You can interactively change object properties in the SimBiology Model Builder app.

For an explanation of how relevant properties relate to one another, see Command Line.

The following sections use a kinetic law example to show how you can fully define your kinetic law object to obtain the reaction rate in the SimBiology Model Builder app and at the command line.

The Henri-Michaelis-Menten kinetic law is expressed as follows:

$$V_m*S/(K_m+S)$$

In the SimBiology software Henri-Michaelis-Menten is a built-in abstract kinetic law, where Vm and Km are defined in the ParameterVariables property of the abstract kinetic law object, and S is defined in the SpeciesVariables property of the abstract kinetic law object.

SimBiology Model Builder app

To fully define a kinetic law in the app, define the names of the species variables and parameter variables that participate in the reaction rate. For an example, see Add and Configure Reactions.

Command Line

To fully define the kinetic law object at the command line, define the names of the parameters in the ParameterVariableNames property of the kinetic law object, and define the species names in the SpeciesVariableNames property of the kinetic law object. For example, to apply the Henri-Michaelis-Menten abstract kinetic law to a reaction

  A -> B
  where Vm = Va, Km = Ka
  and S = A

Define Va and Ka in the ParameterVariableNames property to substitute the variables that are in the ParameterVariables property (Vm and Km). Define A in the SpeciesVariableName property to be used to substitute the species variable in the SpeciesVariables property (S). Specify the order of the model parameters to be used for substitution in the same order that the parameter variables are listed in the ParameterVariables property. Similarly, specify species order if more than one species variable is represented.

% Find the order of the parameter variables 
% in the kinetic law expression. 

get(kineticlawObj, 'ParameterVariables')

ans = 

    'Vm'    'Km'

% Find the species variable in the
% kinetic law expression

get(kineticlawObj, 'SpeciesVariables')
ans = 

    'S'

% Specify the parameters and species variables 
% to be used in the substitution. 
% Remember to specify order, for example Vm = Va 
% Vm is listed first in 'ParameterVariables', 
% therefore list Va first in 'ParameterVariableNames'.

set(kineticlawObj,'ParameterVariableNames', {'Va' 'Ka'});
set(kineticlawObj,'SpeciesVariableNames', {'A'});

The rate equation is assigned in the reaction object as follows:

$$\text{Va*A/(Ka + A)}$$

For a detailed procedure, see Examples.

The following table summarizes the relationships between the properties in the abstract kinetic law object and the kinetic law object in the context of the above example.

Property	Property Purpose	Abstract Kinetic Law Object	Kinetic Law Object
Name (abstract kinetic law object) KineticLawName (kinetic law object)	Name of abstract kinetic law applied to a reaction. For example: Henri-Michaelis -Menten	Read-only for built-in abstract kinetic law. User-determined for user-defined abstract kinetic law.	Read-only
Expression	Mathematical expression used to determine the reaction rate equation. For example: $$V_m*S/(K_m+S)$$	Read-only for built-in abstract kinetic law. User-determined for user-defined abstract kinetic law.	Read-only; depends on abstract kinetic law applied to reaction.
ParameterVariables	Variables in Expression that are parameters. For example: Vm and Km	Read-only for built-in abstract kinetic law. User-determined for user-defined abstract kinetic law.	Read-only; depends on abstract kinetic law applied to reaction.
SpeciesVariables	Variables in Expression that are species. For example: S	Read-only for built-in abstract kinetic law. User-determined for user-defined abstract kinetic law.	Read-only; depends on abstract kinetic law applied to reaction.
ParameterVariableNames	Variables in ReactionRate that are parameters. For example: Va and Ka	Not applicable	Define these variables corresponding to ParameterVariables.
SpeciesVariablesNames	Variables in ReactionRate that are species. For example: A	Not applicable	Define these variables corresponding to SpeciesVariables.

Constructor Summary

addkineticlaw (reaction)

Create kinetic law object and add to reaction object

Method Summary

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

Property Summary

Expression	Expression to determine reaction rate equation or expression of observable object
KineticLawName	Name of kinetic law applied to reaction
Name	Specify name of object
Notes	HTML text describing SimBiology object
ParameterVariableNames	Cell array of reaction rate parameters
ParameterVariables	Parameters in kinetic law definition
Parameters	Array of parameter objects
Parent	Indicate parent object
SpeciesVariableNames	Cell array of species in reaction rate equation
SpeciesVariables	Species in abstract kinetic law
Tag	Specify label for SimBiology object
Type	Display SimBiology object type
UserData	Specify data to associate with object

Examples

This example shows how to define the reaction rate for a reaction.

1. Create a model object, and add a reaction object to the model.

   modelObj = sbiomodel ('my_model');
   reactionObj = addreaction (modelObj, 'A -> B');

2. Define a kinetic law for the reaction object.

   kineticlawObj = addkineticlaw(reactionObj, 'Henri-Michaelis-Menten');
   

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

   get(kineticlawObj, 'ParameterVariables')
   
   ans = 
   
       'Vm'    'Km'
   
   get(kineticlawObj, 'SpeciesVariables')
   ans = 
   
       'S'
   

4. Define Va and Ka as ParameterVariableNames, which correspond to the ParameterVariables Vm and Km. To set these variables, first create the parameter variables as parameter objects (parameterObj1, parameterObj2) with the names Va and Ka, and then add them to kineticlawObj. The species object with Name A is created when reactionObj is created and need not be redefined.

   parameterObj1 = addparameter(kineticlawObj, 'Va');
   parameterObj2 = addparameter(kineticlawObj, 'Ka');

5. Set the variable names for the kinetic law object.

   set(kineticlawObj,'ParameterVariableNames', {'Va' 'Ka'});
   set(kineticlawObj,'SpeciesVariableNames', {'A'});

6. Verify that the reaction rate is expressed correctly in the reaction object ReactionRate property.

   get (reactionObj, 'ReactionRate')
   

   MATLAB^® returns:

   ans =
   
   Va*A/(Ka+A)