{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "b418d982",
   "metadata": {},
   "source": [
    "# Discretization\n",
    "\n",
    "A morphology is *continuous* cable, but a simulation works on a *finite* set of\n",
    "state variables. **Discretization** is the step that divides the continuous\n",
    "geometry into discrete **control volumes** (CVs), each treated as a single\n",
    "isopotential compartment. This concept applies only to multi-compartment\n",
    "{class}`~braincell.Cell` models.\n",
    "\n",
    "## Control volumes\n",
    "\n",
    "A {class}`braincell.CV` is one isopotential chunk of cable. The collection of\n",
    "CVs for a cell forms a {class}`~braincell.CVTree` whose connectivity mirrors the\n",
    "morphology. Each CV holds the membrane voltage and the channel states for its\n",
    "patch of membrane; adjacent CVs exchange current through axial resistance.\n",
    "\n",
    "```text\n",
    "   one branch                          discretized into 3 CVs\n",
    "   ●━━━━━━━━━━━━━━━━━━━━━●     ──▶      ●━━━━●━━━━●━━━━●\n",
    "                                        CV0  CV1  CV2\n",
    "```\n",
    "\n",
    "The finer the discretization (more, shorter CVs), the more accurately voltage\n",
    "gradients along a dendrite are resolved — at the cost of more state and\n",
    "computation. Choosing the resolution is the job of a **CV policy**.\n",
    "\n",
    "## CV policies\n",
    "\n",
    "A {class}`braincell.CVPolicy` decides how many CVs each branch receives.\n",
    "`braincell` provides several, which you can mix:\n",
    "\n",
    "```{list-table}\n",
    ":header-rows: 1\n",
    ":widths: 32 68\n",
    "\n",
    "* - Policy\n",
    "  - Rule\n",
    "* - {class}`~braincell.CVPerBranch`\n",
    "  - a fixed number of CVs per branch (e.g. one).\n",
    "* - {class}`~braincell.MaxCVLen`\n",
    "  - cap each CV's physical length; long branches get more CVs.\n",
    "* - {class}`~braincell.DLambda`\n",
    "  - the classic **d-λ rule**: size CVs as a fraction of the AC length constant,\n",
    "    so electrically long cable is discretized more finely.\n",
    "* - {class}`~braincell.CVPolicyByTypeRule`\n",
    "  - apply different rules to different branch types (e.g. fine soma, coarse axon).\n",
    "* - {class}`~braincell.CompositeByTypePolicy`\n",
    "  - compose several by-type policies into one.\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4e4069b1",
   "metadata": {},
   "outputs": [],
   "source": [
    "import brainunit as u\n",
    "import braincell\n",
    "\n",
    "# the d-lambda rule at 100 Hz\n",
    "policy = braincell.DLambda(frequency=100. * u.Hz)\n",
    "\n",
    "# or: no CV longer than 20 microns\n",
    "policy = braincell.MaxCVLen(20. * u.um)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b919e899",
   "metadata": {},
   "source": [
    "```{tip}\n",
    "The **d-λ rule** ({class}`~braincell.DLambda`) is the standard default in\n",
    "detailed modeling: it puts compartments where the cable physics needs them and\n",
    "spares them where it doesn't. Start there unless you have a reason not to.\n",
    "```\n",
    "\n",
    "## From CVs to runtime\n",
    "\n",
    "Once the CVs are fixed, `braincell`'s runtime layer (`braincell._compute`)\n",
    "builds an execution graph over them — a {class}`~braincell.Node`/\n",
    "{class}`~braincell.NodeTree` of compute points — and assembles the frozen,\n",
    "JAX-friendly state that the {doc}`integrator <integration>` advances. You do not\n",
    "interact with this layer directly; it is what `paint`/`place` + a CV policy\n",
    "compile into.\n",
    "\n",
    "## See also\n",
    "\n",
    "- {doc}`morphology` — the geometry being discretized.\n",
    "- {doc}`integration` — advancing the discretized state in time.\n",
    "- {doc}`../apis/braincell` — `CV`, `CVPolicy`, and policy classes."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}