{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "8c8f2d9874f8753f",
   "metadata": {},
   "source": [
    "# Single-Compartment Neurons\n",
    "\n",
    "`braincell` builds every neuron on the Hodgkin–Huxley (HH) framework. Two concrete cell classes share this framework through inheritance:\n",
    "\n",
    "- `HHTypedNeuron`: the abstract base class that provides the interface for HH-type neurons.\n",
    "- `SingleCompartment`: a single-compartment (point) neuron model, suitable for neurons with simple structure.\n",
    "- `MultiCompartment`: a spatially detailed, multi-compartment neuron model — covered in the [Cell](cell.ipynb) tutorial.\n",
    "\n",
    "Together these components form a modeling system that spans from local membrane regions to the complete neuronal structure. Through inheritance they share a unified modeling interface and, with the acceleration and computational power of `brainstate`, provide strong support for neuronal modeling at the cellular level.\n",
    "\n",
    "This tutorial focuses on `HHTypedNeuron` and `SingleCompartment`. For neurons whose spatial structure matters, continue to the [Cell](cell.ipynb) tutorial.\n",
    "\n",
    "## HHTypedNeuron\n",
    "\n",
    "### Electrophysiological Properties\n",
    "\n",
    "`HHTypedNeuron` is a fundamental abstract class in `braincell` for constructing Hodgkin–Huxley-type neuron models. In this modeling framework, the membrane potential of a neuron is determined by multiple currents:\n",
    "- Active currents: Controlled by sodium and potassium channels with voltage-gated properties.\n",
    "- Passive currents: Such as leak currents.\n",
    "- Capacitive currents: Arising from changes in membrane potential.\n",
    "\n",
    "This modeling approach was first proposed by Hodgkin and Huxley in 1952 to explain the mechanism of action potentials in the squid giant axon.\n",
    "The HH model not only laid the foundation of modern neuronal modeling but also remains a core component of many models today.\n",
    "\n",
    "The equivalent circuit diagram of the classical HH model is shown below:\n",
    "\n",
    "![Equivalent circuit diagram](../_static/hh.png)\n",
    "\n",
    "In the classical HH model, the membrane potential $V$ is governed by the following equation:\n",
    "\n",
    "$$\n",
    "C_m \\frac{dV}{dt} = - (I_{\\text{Na}} + I_{\\text{K}} + I_L) + I_{\\text{ext}}\n",
    "$$\n",
    "\n",
    "Where:\n",
    "- $C_m$: Membrane capacitance\n",
    "- $I_{\\text{Na}}, I_{\\text{K}}$: Ionic currents from sodium and potassium channels\n",
    "- $I_L$: Leak current\n",
    "- $I_{\\text{ext}}$: External injected current (e.g., current applied through a stimulating electrode)\n",
    "\n",
    "### Modeling Implementation\n",
    "\n",
    "`HHTypedNeuron` inherits from:\n",
    "- `Dynamics`: For defining state variables and differential equations.\n",
    "- `Container`: For managing modules.\n",
    "- `DiffEqModule`: A differential equation module that supports automatic modeling.\n",
    "\n",
    "With `HHTypedNeuron`, you can flexibly combine ion channels to construct diverse dynamical configurations.\n",
    "Moreover, since `HHTypedNeuron` is deeply integrated with `brainstate`, it also supports automatic differentiation and vectorized simulations, enabling batch simulations and model training.\n",
    "\n",
    "Notably, in `braincell`, all neuron models are built upon the HH framework.\n",
    "Specifically, both `SingleCompartment` and `MultiCompartment` inherit from `HHTypedNeuron`, sharing a unified interface and modeling framework. This allows us to reuse the same ion channel mechanisms and dynamical modeling strategies across neurons with different structural complexities.\n",
    "\n",
    "## SingleCompartment\n",
    "\n",
    "### Electrophysiological Properties\n",
    "\n",
    "`SingleCompartment` represents a neuron model without explicit spatial structure, used for modeling conductance-based neurons with a single compartment. Its membrane potential is governed by the following differential equation:\n",
    "\n",
    "$$\n",
    "C_m \\frac{dV}{dt} = \\sum_j g_j(E_j - V) + I_{\\text{ext}}\n",
    "$$\n",
    "\n",
    "Where:\n",
    "- $C_m$: Membrane capacitance\n",
    "- $V$: Membrane potential\n",
    "- $g_j$: Conductance of the $j$-th ion channel\n",
    "- $E_j$: Reversal potential of the $j$-th channel\n",
    "- $I_{\\text{ext}}$: External injected current\n",
    "\n",
    "The conductance $g_j$ of each channel is determined by its gating variables:\n",
    "\n",
    "$$\n",
    "g_j = \\bar{g}_j \\cdot M^x \\cdot N^y\n",
    "$$\n",
    "\n",
    "Where:\n",
    "- $\\bar{g}_j$: Maximum conductance\n",
    "- $M$: Activation variable\n",
    "- $N$: Inactivation variable\n",
    "- $x, y$: Exponents depending on channel type\n",
    "\n",
    "The gating variables follow first-order kinetics:\n",
    "\n",
    "$$\n",
    "\\frac{dx}{dt} = \\phi_x \\cdot \\frac{x_\\infty(V) - x}{\\tau_x(V)}\n",
    "$$\n",
    "\n",
    "Or equivalently:\n",
    "\n",
    "$$\n",
    "\\frac{dx}{dt} = \\phi_x \\left( \\alpha_x (1 - x) - \\beta_x x \\right)\n",
    "$$\n",
    "\n",
    "Where:\n",
    "- $x \\in \\{M, N\\}$\n",
    "- $\\phi_x$: Temperature factor\n",
    "- $x_\\infty$: Steady-state value\n",
    "- $\\tau_x$: Time constant\n",
    "- $\\alpha_x$, $\\beta_x$: Rate constants\n",
    "\n",
    "### Modeling Implementation\n",
    "\n",
    "The implementation of `SingleCompartment` is relatively straightforward: simply inherit from `HHTypedNeuron` and define the corresponding ion channels.\n",
    "\n",
    "Here is an example:\n",
    "\n",
    "```python\n",
    "class HH(braincell.SingleCompartment):\n",
    "    def __init__(self, size, solver='rk4'):\n",
    "        super().__init__(size, solver=solver)\n",
    "\n",
    "        self.na = braincell.ion.SodiumFixed(size, E=50. * u.mV)\n",
    "        self.na.add(INa=braincell.channel.Na_HH1952(size))\n",
    "\n",
    "        self.k = braincell.ion.PotassiumFixed(size, E=-77. * u.mV)\n",
    "        self.k.add(IK=braincell.channel.K_HH1952(size))\n",
    "\n",
    "        self.IL = braincell.channel.IL(\n",
    "            size,\n",
    "            E=-54.387 * u.mV,\n",
    "            g_max=0.03 * (u.mS / u.cm **2)\n",
    "        )\n",
    "```\n",
    "\n",
    "In this example, we use `SingleCompartment` to construct a classical HH neuron with sodium (`INa`), potassium (`IK`), and leak (`IL`) currents, which together determine the electrophysiological properties of the neuron.\n",
    "\n",
    "As this example shows, `SingleCompartment` serves as a convenient modeling interface in `braincell`, greatly simplifying the construction of neurons and improving modeling efficiency.\n",
    "\n",
    "## Next steps\n",
    "\n",
    "`SingleCompartment` treats the neuron as a single isopotential point. To model dendrites, axons, and the soma as a spatially connected cable system, continue to the [Cell](cell.ipynb) tutorial, which builds `MultiCompartment` models from a `Morphology`."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}