{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### NMODL integration of ODEs\n",
    "\n",
    "This is an overview of\n",
    "  - the different ways a user can specify the equations that define the system they want to simulate in the MOD file\n",
    "  - how these equations can be related to each other\n",
    "  - how these equations are solved in NMODL\n",
    "\n",
    "***\n",
    "\n",
    "The user can specify information about the system in a variety of ways:\n",
    "  - A high level way to describe a system is to specify a Mass Action Kinetic scheme of reaction equations in a `KINETIC` block\n",
    "  - Alternatively a system of ODEs can be specified in a `DERIVATIVE` block (any kinetic scheme can also be written as a system of ODEs)\n",
    "  - Finally a system of linear/non-linear algebraic equations can be specified in a `LINEAR`/`NONLINEAR` block (a numerical integration scheme, such as backwards Euler, transforms a system of ODEs into a system of linear or non-linear equations)\n",
    "\n",
    "To reduce duplication of functionality for dealing with these related systems, we implement a hierarchy of transformations:\n",
    "  - `KINETIC` blocks of reaction statements are translated to `DERIVATIVE` blocks of equivalent ODE systems using the law of Mass Action\n",
    "  - `DERIVATIVE` blocks of ODEs are translated to `(NON)LINEAR` blocks of algebraic equations using a numerical integration scheme\n",
    "\n",
    "After these transformations we are left with only `LINEAR`/`NONLINEAR` blocks that are then solved numerically (by Gaussian Elimination, LU factorization or Newton iteration)\n",
    "\n",
    "***\n",
    "\n",
    "#### `KINETIC` block\n",
    "\n",
    " - Mass Action kinetics: a set of reaction equations with associated reaction rates\n",
    " - converted to a `DERIVATIVE` blocking containing an equivalent system of ODEs using the law of Mass Action\n",
    " - see the [nmodl-kinetic-schemes](nmodl-kinetic-schemes.ipynb) notebook for more details\n",
    "\n",
    "***\n",
    "\n",
    "#### `DERIVATIVE` block\n",
    " - system of ODEs & associated solve method: `cnexp`, `sparse`, `derivimplicit` or `euler`\n",
    " - `cnexp`\n",
    "   - applicable if ODEs are linear & independent\n",
    "   - exact analytic integration\n",
    "   - see the [nmodl-sympy-solver-cnexp](nmodl-sympy-solver-cnexp.ipynb) notebook for more details\n",
    " - `sparse`\n",
    "   - applicable if ODEs are linear & coupled\n",
    "   - backwards Euler numerical integration scheme: $f(t+\\Delta t) = f(t) + dt f'(t+ \\Delta t)$\n",
    "   - results in a linear algebraic system to solve\n",
    "   - numerically stable\n",
    "   - $\\mathcal{O}(\\Delta t)$ integration error\n",
    "   - see the [nmodl-sympy-solver-sparse](nmodl-sympy-solver-sparse.ipynb) notebook for more details\n",
    " - `derivimplcit`\n",
    "   - always applicable\n",
    "   - backwards Euler numerical integration scheme: $f(t+\\Delta t) = f(t) + dt f'(t+ \\Delta t)$\n",
    "   - results in a non-linear algebraic system to solve\n",
    "   - numerically stable\n",
    "   - $\\mathcal{O}(\\Delta t)$ integration error\n",
    "   - see the [nmodl-sympy-solver-sparse](nmodl-sympy-solver-derivimplicit.ipynb) notebook for more details\n",
    " - `euler`\n",
    "   - always applicable\n",
    "   - forwards Euler numerical integration scheme: $f(t+\\Delta t) = f(t) + \\Delta t f'(t)$\n",
    "   - numerically unstable\n",
    "   - $\\mathcal{O}(\\Delta t)$ integration error\n",
    "   - not recommended due to instability of scheme\n",
    "\n",
    "***\n",
    "\n",
    "#### `LINEAR` block\n",
    "  - system of linear algebraic equations\n",
    "  - for small systems ($N<=3$)\n",
    "    - solve at compile time by Gaussian elimination\n",
    "  - for larger systems\n",
    "    - solve at run-time by LU factorization with partial pivoting\n",
    "  - see the [nmodl-linear-solver](nmodl-linear-solver.ipynb) notebook for more details \n",
    "\n",
    "***\n",
    "\n",
    "#### `NONLINEAR` block\n",
    " - system of non-linear algebraic equations\n",
    " - solve by Newton iteration\n",
    "   - construct $F(X)$, with Jacobian $J(X)=\\frac{\\partial F_i}{\\partial X_j}$\n",
    "   - such that desired solution $X^*$ satisfies condition $F(X^*) = 0$\n",
    "   - iterative solution given by $X_{n+1} = X_n + J(X_n)^{-1} F(X_n)$\n",
    "  - see the [nmodl-nonlinear-solver](nmodl-nonlinear-solver.ipynb) notebook for more details \n",
    "***"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.7.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}