{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "56649e05",
   "metadata": {},
   "source": [
    "# Integration\n",
    "\n",
    "A neuron model is a system of differential equations: the membrane potential,\n",
    "gating variables, and ion concentrations all evolve in time according to a\n",
    "right-hand side $f(t, y)$. **Integration** is the act of advancing that system\n",
    "forward in time. `braincell` keeps this concern in its own module,\n",
    "{mod}`braincell.quad`, shared by both cell types.\n",
    "\n",
    "This page is the conceptual overview. For hands-on use — comparing solvers,\n",
    "writing your own — see the full {doc}`../integration/index` guide.\n",
    "\n",
    "## The protocol: describing the equations\n",
    "\n",
    "Two small abstractions describe *what* to integrate:\n",
    "\n",
    "- {class}`braincell.DiffEqState` — a state variable that carries its own\n",
    "  derivative (and, for cable diffusion, a diffusion term).\n",
    "- {class}`braincell.DiffEqModule` — a module that exposes a right-hand side over\n",
    "  such states.\n",
    "\n",
    "Cells implement this protocol, so any solver knows how to step them. You rarely\n",
    "touch it unless you are building a new dynamical component.\n",
    "\n",
    "## The registry: choosing a solver\n",
    "\n",
    "`braincell.quad` holds a **registry of solvers**, each selectable by name. You\n",
    "pick one when constructing a cell:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bade3b55",
   "metadata": {},
   "outputs": [],
   "source": [
    "import braincell\n",
    "hh = braincell.SingleCompartment(size, solver='ind_exp_euler')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7ef8a035",
   "metadata": {},
   "source": [
    "The available integrators span the usual families:\n",
    "\n",
    "```{list-table}\n",
    ":header-rows: 1\n",
    ":widths: 30 70\n",
    "\n",
    "* - Family\n",
    "  - Members (by name)\n",
    "* - **Explicit Runge–Kutta**\n",
    "  - `euler`, `midpoint`, `rk2`, `rk3`, `rk4`, `heun2`, `heun3`, `ssprk3`,\n",
    "    `ralston2/3/4`\n",
    "* - **Exponential Euler**\n",
    "  - `exp_euler`, `ind_exp_euler`, `exp_exp_euler`\n",
    "* - **Implicit**\n",
    "  - `backward_euler`, `implicit_euler`, `implicit_exp_euler`, `implicit_rk4`\n",
    "* - **Composite / cable**\n",
    "  - `cn_exp_euler`, `cn_rk4` (Crank–Nicolson), `splitting`, `staggered`,\n",
    "    `dhs_voltage`\n",
    "```\n",
    "\n",
    "You can list everything available at runtime:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9f202f66",
   "metadata": {},
   "outputs": [],
   "source": [
    "import braincell.quad as quad\n",
    "sorted(quad.all_integrators)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "322932cb",
   "metadata": {},
   "source": [
    "## Choosing wisely: stiffness\n",
    "\n",
    "Biophysical neuron models are **stiff** — they mix very fast (sodium spike) and\n",
    "slow (calcium, adaptation) timescales. Explicit solvers like `rk4` must take\n",
    "tiny time steps to stay stable on stiff systems, which is slow.\n",
    "\n",
    "```{tip}\n",
    "For single-compartment HH-style models, **exponential-Euler** variants\n",
    "(`exp_euler`, `ind_exp_euler`) handle the stiff gating kinetics stably at\n",
    "practical step sizes and are a good default. For multi-compartment cable\n",
    "equations, the **staggered** / Crank–Nicolson solvers are designed for the\n",
    "spatial coupling.\n",
    "```\n",
    "\n",
    "## Differentiability\n",
    "\n",
    "Because every solver is written in JAX, the entire time loop is differentiable.\n",
    "Gradients of an output (a spike count, a voltage trace, a loss) with respect to\n",
    "parameters (conductances, time constants) flow straight back through the\n",
    "integration — this is what makes gradient-based model fitting possible.\n",
    "\n",
    "## Writing your own integrator\n",
    "\n",
    "The registry is open: decorate a stepping function with\n",
    "`@register_integrator` and it becomes selectable by name like any built-in. The\n",
    "{doc}`../integration/advanced` guide walks through this.\n",
    "\n",
    "## See also\n",
    "\n",
    "- {doc}`../integration/index` — the full integration guide (overview, protocol,\n",
    "  solvers, advanced).\n",
    "- {doc}`../apis/integration` — every integrator and its signature.\n",
    "- {doc}`discretization` — what the cable solvers operate on."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}