# 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/\left({K}_{m}+S\right)$`

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:

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 PurposeAbstract Kinetic Law ObjectKinetic 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/\left({K}_{m}+S\right)$`

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 applicableDefine these variables corresponding to `ParameterVariables`.
`SpeciesVariablesNames`Variables in `ReactionRate` that are species. For example:
`A`
Not applicableDefine these variables corresponding to `SpeciesVariables`.

## 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)```

SimBiology property `Expression`