addreaction

Create reaction object and add to model

Syntax

rxnObj = addreaction(modelObj,rxnEquation)

rxnObj = addreaction(modelObj,reactantNames,productNames)

rxnObj = addreaction(modelObj,reactantNames,RStoichCoefficients,productNames,PStoichCoefficients)

rxnObj = addreaction(___,Name=Value)

Description

rxnObj = addreaction(modelObj,rxnEquation) creates and returns a SimBiology.Reaction object rxnObj. The function also assigns

• rxnEquation to the Reaction property of rxnObj.

• Reactant species to the Reactants property of rxnObj.

• Product species to the Products property of rxnObj.

• modelObj to the Parent property of rxnObj.

• rxnObj to the Reactions property of modelObj.

Note

• If there are multiple compartments in your model, you need to qualify the species names with a compartment name. If you qualify any species name with a compartment name, then you must qualify every species with the corresponding compartment name. For details, see Add Reactions to SimBiology Model.

• If you use addreaction to create 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.

rxnObj = addreaction(modelObj,reactantNames,productNames) specifies the reactant species and product species. By default, the stoichiometric values are set to 1.

rxnObj = addreaction(modelObj,reactantNames,RStoichCoefficients,productNames,PStoichCoefficients) also specifies the stoichiometric coefficients for reactants and products and sets the Stoichiometry property of rxnObj.

rxnObj = addreaction(___,Name=Value) also sets the properties of rxnObj using one or more name-value arguments. Name is the property name and Value is the corresponding value.

Examples

Create and Add Reactions to SimBiology Model

Create a model.

modelObj = sbiomodel("m1");

Add a reaction.

rxnObj = addreaction(modelObj, 'a -> c + d');

Create a kinetic law object for the reaction object, of the type 'Henri-Michaelis-Menten'.

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

The 'Henri-Michaelis-Menten' kinetic law has two parameter variables (Vm and Km) and one species variable (S) that should to be set. To set these variables, first create the parameter variables as parameter objects (parameterObj1, parameterObj2) with names Vm_d, and Km_d, and assign the objects Parent property value to the kineticlawObj.

parameterObj1 = addparameter(kineticlawObj,"Vm_d");
parameterObj2 = addparameter(kineticlawObj,"Km_d");

Set the variable names for the kinetic law object.

kineticlawObj.ParameterVariableNames = ["Vm_d","Km_d"];
kineticlawObj.SpeciesVariableNames = "a";

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

rxnObj.ReactionRate

ans = 
'Vm_d*a/(Km_d+a)'

Input Arguments

modelObj — SimBiology model

SimBiology.Model

SimBiology model, specified as a Model object.

rxnEquation — Reaction equation

character vector | string scalar

Reaction equation, specified as a character vector or string scalar.

A hyphen preceded by a space and followed by a right angle bracket (->) indicates reactants going forward to products. A hyphen with left and right angle brackets (<->) indicates a reversible reaction. Coefficients before reactant or product names must be followed by a space.

Examples are 'A -> B', 'A + B -> C', '2 A + B -> 2 C', and 'A <-> B'. Enter reactions with spaces between the species.

If there are multiple compartments, or to specify the compartment name, use compartmentName.speciesName to qualify the species name.

Examples are 'cytoplasm.A -> cytoplasm.B', 'cytoplasm.A -> nucleus.A', and 'cytoplasm.A + cytoplasm.B -> nucleus.AB'.

Data Types: char | string

reactantNames — Names of reactant species

character vector | string scalar | string vector | cell array of character vectors

Names of reactant species, specified as a character vector, string scalar, string vector, or cell array of character vectors. Qualify with compartment names if there are multiple compartments.

Data Types: char | string | cell

productNames — Names of product species

character vector | string scalar | string vector | cell array of character vectors

Names of product species, specified as a character vector, string scalar, string vector, or cell array of character vectors. Qualify with compartment names if there are multiple compartments.

Data Types: char | string | cell

RStoichCoefficients — Stoichiometry coefficients of reactants

positive numeric scalar | positive numeric vector

Stoichiometry coefficients of reactants, specified as a positive numeric scalar or positive numeric vector. If it is a vector, it must have the same length as reactantNames.

Data Types: double

PStoichCoefficients — Stoichiometry coefficients of products

positive numeric scalar | positive numeric vector

Stoichiometry coefficients of products, specified as a positive numeric scalar or positive numeric vector. If it is a vector, it must have the same length as productNames.

Data Types: double

More About

Add Reactions to SimBiology Model

When you define a reaction with a new species:

• If no compartment objects exist in the model, the function creates a compartment object (called 'unnamed') in the model and adds the newly created species to that compartment.

• If only one compartment object exists in the model, the function creates a species object in that compartment.

• If there is more than one compartment object in the model, you must qualify the species name with the compartment name.

  For example, cell.glucose denotes that you want to put the species named glucose into a compartment named cell. Additionally, if the compartment named cell does not exist, the process of adding the reaction creates the compartment and names it cell.

You can manually add a species to a compartment object with addspecies.

You can add species to a reaction object using addreactant or addproduct. You can remove species from a reaction object with rmreactant or rmproduct. The property Reaction is modified by adding or removing species from the reaction equation.

Version History

Introduced in R2006a

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.