{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "42d9bdd4",
   "metadata": {},
   "source": [
    "# Defining new reactions\n",
    "\n",
    "SimBio includes a comprehensive set of predefined reactions\n",
    "that relate reactants with products\n",
    "and a well defined kinetics.\n",
    "But,\n",
    "new reactions can be easily defined,\n",
    "to extend SimBio's capabilities.\n",
    "\n",
    "There are two main types of reactions,\n",
    "\n",
    "- `SingleReaction`, which models elementary chemical reactions,\n",
    "- `ReactionGroup`, which consists of multiple `SingleReaction` and/or `ReactionGroup`."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7c573009",
   "metadata": {},
   "source": [
    "## Single reactions\n",
    "\n",
    "A `SingleReaction`\n",
    "converting species $A$ and $B$ to $C$,\n",
    "\n",
    "$$ n_A A + n_B B \\xrightarrow{k} n_C C $$\n",
    "\n",
    "where $n_A$, $n_B$, and $n_C$ are the stoichiometric coefficients,\n",
    "corresponds to the following differential equations:\n",
    "\n",
    "$$\n",
    "\\begin{cases}\n",
    "\\frac{dA}{dt} = -n_A \\; R(t, A^{n_A}, B^{n_B}, k) \\\\\n",
    "\\frac{dB}{dt} = -n_B \\; R(t, A^{n_A}, B^{n_B}, k) \\\\\n",
    "\\frac{dC}{dt} = +n_C \\; R(t, A^{n_A}, B^{n_B}, k)\n",
    "\\end{cases}\n",
    "$$\n",
    "\n",
    "where $R(t, A, B, k)$ is the reaction rate.\n",
    "\n",
    "For a reaction following mass action kinetics,\n",
    "the reaction rate is\n",
    "\n",
    "$$ R(t, A, B, k) = k A B $$\n",
    "\n",
    "For a Michaelis-Menten reaction,\n",
    "\n",
    "$$ S + E ↔ ES → P + E $$\n",
    "\n",
    "where an enzyme $E$ converts a substrate $S$ to a product $P$,\n",
    "under certain assumptions can be modeled as a single-step reaction with rate:\n",
    "\n",
    "$$ R(t, S, V_{max}, K_M) = V_{max} * S / (K_M + S) $$\n",
    "\n",
    "To define a `SingleReaction`,\n",
    "we need to declare the species and parameters it relates,\n",
    "which corresponds to reactants and products,\n",
    "and the reaction rate function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "c8c7e41b",
   "metadata": {},
   "outputs": [],
   "source": [
    "from simbio.components import SingleReaction, Species, Parameter\n",
    "\n",
    "\n",
    "class Synthesis(SingleReaction):\n",
    "    \"\"\"A + B → AB\"\"\"\n",
    "    A: Species\n",
    "    B: Species\n",
    "    AB: Species\n",
    "    rate: Parameter\n",
    "\n",
    "    def reactants(self):\n",
    "        return (self.A, self.B)\n",
    "\n",
    "    def products(self):\n",
    "        return (self.AB,)\n",
    "\n",
    "    @staticmethod\n",
    "    def reaction_rate(t, A, B, rate):\n",
    "        return rate * A * B"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "82d76ad5",
   "metadata": {},
   "source": [
    "## Compound reactions\n",
    "\n",
    "Compound reactions are a convenience to englobe a series of reactions into one.\n",
    "They can be composed of many single or compound reactions.\n",
    "For instance,\n",
    "the `MichaelisMenten` reaction,\n",
    "\n",
    "$$ S + E ↔ ES → P + E $$\n",
    "\n",
    "which is included in `simbio.reactions.enzymatic`,\n",
    "is defined as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "fcd4da09",
   "metadata": {},
   "outputs": [],
   "source": [
    "from simbio.components import ReactionGroup, Species, Parameter\n",
    "from simbio.reactions.compound import ReversibleSynthesis\n",
    "from simbio.reactions.single import Dissociation\n",
    "\n",
    "\n",
    "class MichaelisMenten(ReactionGroup):\n",
    "    \"\"\"S + E ↔ ES → P + E\"\"\"\n",
    "    E: Species\n",
    "    S: Species\n",
    "    ES: Species\n",
    "    P: Species\n",
    "    forward_rate: Parameter\n",
    "    reverse_rate: Parameter\n",
    "    catalytic_rate: Parameter\n",
    "\n",
    "    binding_reaction = ReversibleSynthesis(\n",
    "        A=E,\n",
    "        B=S,\n",
    "        AB=ES,\n",
    "        forward_rate=forward_rate,\n",
    "        reverse_rate=reverse_rate,\n",
    "    )\n",
    "    dissociation_reaction = Dissociation(\n",
    "        AB=ES,\n",
    "        A=E,\n",
    "        B=P,\n",
    "        rate=catalytic_rate,\n",
    "    )"
   ]
  }
 ],
 "metadata": {
  "jupytext": {
   "text_representation": {
    "extension": ".md",
    "format_name": "myst",
    "format_version": 0.13,
    "jupytext_version": "1.14.0"
   }
  },
  "kernelspec": {
   "display_name": "Python 3.10.6 64-bit ('simbio')",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.8"
  },
  "source_map": [
   12,
   28,
   69,
   89,
   103
  ]
 },
 "nbformat": 4,
 "nbformat_minor": 5
}