# Definition of reactions and reaction rules

Now that different instances of the species types have been defined using species and selectors, we can use them to choose between alternative conditional reactions, and to set-up the characteristics of the entities resulting from those conditional reactions. This is done by creating, for each relevant reaction, a list of reaction rules that contains alternative kinetic laws.

Reaction and all the associated classes of multi Version 1.
SimpleSpeciesReference and all the associated classes of multi Version 1.

A reaction rule applies when a list of conditions is fulfilled by the reacting species, and a reaction rule produces outcomes described in a list of results. Reaction rules must not produce mass or cause unexplained disappearance of it. In other words, once the various selections are applied, what is on the left should be on the right. In order to ensure that, what is not explicitly represented must be left untouched by the reactions. $*-A + B \rightarrow *-A-B$

Can represent:

$C-A + B \rightarrow C-A-B$

or

$D-A + B \rightarrow D-A-B$

But not:

$C-A + B \rightarrow D-A-B$

Such a complex reaction must be explicitely described if needed.

ReactionRule and all the associated classes of multi Version 1.

## Reaction

In order to encode the structures needed to propose alternative kinetic laws selected based on the state and connectivity of involved partners, we extend the element Reaction of SBML Level 3 Version 1 core by linking it to a list of ReactionRules.

Definition of the extended version of Reaction and its relation with SBase.
<reaction id="react" reversible="false" fast="false"
xmlns:multi="http://www.sbml.org/sbml/level3/version1/multi/version1">

<listOfReactants>
<!-- some reactants -->
</listOfReactants>

<listOfProducts>
<!-- some products -->
</listOfProducts>

<kineticLaw />

<multi:listOfReactionRules>
<!-- some reaction rules-->
</multi:listOfReactionRules>
</reaction>


## SimpleSpeciesReference

In order to decide which kinetic law to choose, one needs to have a list of the necessary states and connectivities for the partners involved. This is done by linking the SimpleSpeciesReference of SBML Level 3 Version 1 core to a list of SpeciesTypeRestrictions. There can be any number of SpeciesTypeRestrictions per SimpleSpeciesReference. They always represent alternatives, and only one can be used per ReactionRule. However, if one wants to discriminate between two instances of the same Species involved in the same ReactionRule but with different roles in the reaction, one must create two SimpleSpeciesReferences pointing to the same Species.

Definition of the extended version of SimpleSpeciesReference and its relation with SBase.
<speciesReference
species="species1"
stoichiometry="1"
xmlns:multi="http://www.sbml.org/sbml/level3/version1/multi/version1">

<multi:listOfSpeciesTypeRestriction>
<!-- some species type restrictions -->
</multi:listOfSpeciesTypeRestriction>

</speciesReference>


## ProductSpeciesReference

In the cases where several instances of the same molecule are use in a reaction, we must explicit the correspondence between the reactants in the product. Otherwise, the following reactions will be selected by the same reaction rule:

   A1 - P + A2 → A1 + A2  - P
A1 - P + A2 → A1 - P + A2


In order to do so, we create a new element ProductSpeciesReference that inherits from SimpleSpeciesReference. The element carries an attribute  correspondingReactant  that precises from which reactant instance the product originates. In an agent-based approach, this would apply to each molecule, while in a population-based framework, this would apply to pools.

Definition of the extended version of ProductSpeciesReference and its relation with SBase.
<listOfReactants>
<speciesReference id="R1" species="species1" stoichiometry="1" />
<speciesReference id="R2" species="species1" stoichiometry="1" />
</listOfReactants>

<listOfProducts>
<multi:productSpeciesReference
species="species1"
stoichiometry="1"
xmlns:multi="http://www.sbml.org/sbml/level3/version1/multi/version1"
multi:correspondingReactant="R1" />
<multi:productSpeciesReference
species="species1"
stoichiometry="1"
xmlns:multi="http://www.sbml.org/sbml/level3/version1/multi/version1"
multi:correspondingReactant="R2" />
</listOfProducts>


## SpeciesTypeRestriction

A SpeciesTypeRestriction points to a SpeciesTypeInstances, and creates a conditional species reference. Those various SpeciesTypeRestrictions can then be used to decide on the ReactionRule to use, and which Results to produce. As all elements derived from SBase, it can link to Notes and Annotation, and carry a  metaid , and an  sboTerm .

Definition of SpeciesTypeRestriction and its relation with SBase.
<multi:speciesTypeRestriction
multi:id="speciesRest1"
multi:speciesTypeInstance="speciesTypeInstance1"
xmlns:multi="http://www.sbml.org/sbml/level3/version1/multi/version1" />


## ReactionRule

The ReactionRule element is used to describe a process that is dependent on states or connectivity. As all elements derived from SBase, it can link to Notes and Annotation, and carry a  metaid , and an  sboTerm . When the conditions are fulfilled, the ReactionRule replaces the regular Reaction.

Definition of ReactionRule and its relation with SBase.
<multi:reactionRule
multi:id="bindingNonPhospho"
xmlns:multi="http://www.sbml.org/sbml/level3/version1/multi/version1" >

<multi:listOfConditions>
<!-- some conditions for the rule to be used-->
</multi:listOfConditions>

<multi:listOfResults>
<!-- some results of the application of the rule -->
</multi:listOfResults>

<kineticLaw />
</multi:reactionRule>


## SpeciesTypeRestrictionReference

In order to precise the conditions for a reaction rule to apply, and describe the results to obtain, a SpeciesTypeRestrictionReference points to a species type restriction using the attribute  speciesTypeRestriction . As all elements derived from SBase, it can link to Notes and Annotation, and carry a  metaid , and an  sboTerm . The SpeciesTypeRestrictions used to decide if a rule applies are called in ListOfConditions. The SpeciesTypeRestrictions used to decide if the result of a rule are called in ListOfResults.

Definition of SpeciesTypeRestrictionReference and its relation with SBase.
<multi:speciesTypeRestrictionReference
multi:speciesTypeRestriction="freeRnonP"
xmlns:multi="http://www.sbml.org/sbml/level3/version1/multi/version1" />


## ReactionRule specific KineticLaw

A ReactionRule optionally contains a KineticLaw. If the conditions apply, this KineticLaw is used to compute the results instead of the one contained in the reaction element of SBML Level 3 Version 1.

## Complete examples of use

The following example describes a binding reaction that takes place ten times faster on the phosphorylated receptor than on the non-phosphorylated one.

<reaction id="receptLigBinding" reversible="false" fast="false">
<listOfReactants>
<speciesReference
id="spRef_Rec"
species="receptor"
stoichiometry="1">
<multi:listOfSpeciesRestriction>
<multi:speciesRestriction
multi:id="restriction1"
multi:speciesTypeInstance="receptorNP" />
<multi:speciesRestriction
multi:id="restriction2"
multi:speciesTypeInstance="receptorP" />
</multi:listOfSpeciesRestriction>
</speciesReference>
<speciesReference species="ligand" stoichiometry="1" />
</listOfReactants>
<listOfProducts>
<productSpeciesReference
species="receptor"
stoichiometry="1"
correspondingReactant="spRef_Rec">
<multi:listOfSpeciesRestriction>
<multi:speciesRestriction
multi:id="restriction3"
multi:speciesTypeInstance="receptorBound" />
</multi:listOfSpeciesRestriction>
</productSpeciesReference>
</listOfProducts>

<kineticLaw>
<math xmlns="http://www.w3.org/1998/Math/MathML" />
</kineticLaw>

<multi:listOfReactionRules>
<multi:reactionRule multi:id="reactionRule1">
<multi:listOfConditions>
<multi:speciesTypeRestrictionReference multi:speciesTypeRestriction="restriction1"/>
</multi:listOfConditions>
<multi:listOfResults>
<multi:speciesTypeRestrictionReference multi:speciesTypeRestriction="restriction3"/>
</multi:listOfResults>
<kineticLaw>
<math xmlns="http://www.w3.org/1998/Math/MathML" >
<ci> parameter1 </ci>
[/itex]
<listOfLocalParameters>
<localParameter id="parameter1" value="1">
</listOfLocalParameters>
</kineticLaw>
</multi:reactionRule>

<multi:reactionRule multi:id="reactionRule2">
<multi:listOfConditions>
<multi:speciesTypeRestrictionReference multi:speciesTypeRestriction="restriction2"/>
</multi:listOfConditions>
<multi:listOfResults>
<multi:speciesTypeRestrictionReference multi:speciesTypeRestriction="restriction3"/>
</multi:listOfResults>
<kineticLaw>
<math xmlns="http://www.w3.org/1998/Math/MathML" >
<ci> parameter2 </ci>
[/itex]
<listOfLocalParameters>
<localParameter id="parameter2" value="10">
</listOfLocalParameters>
</kineticLaw>
</multi:reactionRule>
</multi:listOfReactionRules>
</reaction>