{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "945f5c36",
   "metadata": {},
   "source": [
    "# Ions & Channels\n",
    "\n",
    "The electrical behavior of a neuron comes from **ion channels** — pores that\n",
    "let specific **ion species** flow across the membrane. `braincell` models these\n",
    "as two cooperating layers: ion species ({mod}`braincell.ion`) own a reversal\n",
    "potential and (optionally) concentration dynamics, and channels\n",
    "({mod}`braincell.channel`) carry current driven by that reversal potential.\n",
    "\n",
    "## Ion species\n",
    "\n",
    "An ion species tracks the reversal potential `E` and, in detailed models, the\n",
    "intra/extracellular concentration. The families in {mod}`braincell.ion`:\n",
    "\n",
    "```{list-table}\n",
    ":header-rows: 1\n",
    ":widths: 30 70\n",
    "\n",
    "* - Class family\n",
    "  - Behavior\n",
    "* - `*Fixed` (e.g. {class}`~braincell.ion.SodiumFixed`, {class}`~braincell.ion.PotassiumFixed`, {class}`~braincell.ion.CalciumFixed`)\n",
    "  - constant reversal potential `E` — the simplest, fastest choice.\n",
    "* - {class}`~braincell.ion.CalciumDetailed`, {class}`~braincell.ion.CalciumFirstOrder`\n",
    "  - calcium with concentration dynamics (buffering, pumps, diffusion), so `E`\n",
    "    follows the Nernst equation as concentration changes.\n",
    "* - `*InitNernst`\n",
    "  - reversal potential initialized from the Nernst equation.\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "16baa977",
   "metadata": {},
   "outputs": [],
   "source": [
    "import brainunit as u\n",
    "import braincell\n",
    "\n",
    "# constant sodium reversal at +50 mV\n",
    "na = braincell.ion.SodiumFixed(size, E=50. * u.mV)\n",
    "\n",
    "# calcium with first-order concentration decay\n",
    "ca = braincell.ion.CalciumDetailed(size, C_rest=5e-5 * u.mM,\n",
    "                                   tau=10. * u.ms, d=0.5 * u.um)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cfb6a368",
   "metadata": {},
   "source": [
    "## Channels\n",
    "\n",
    "A channel produces a current as a function of voltage (and possibly an ion\n",
    "concentration). {mod}`braincell.channel` ships a large, literature-derived\n",
    "library, named by `<current>_<source><year>` convention:\n",
    "\n",
    "```{list-table}\n",
    ":header-rows: 1\n",
    ":widths: 26 74\n",
    "\n",
    "* - Group\n",
    "  - Examples\n",
    "* - Sodium\n",
    "  - {class}`~braincell.channel.Na_HH1952`, {class}`~braincell.channel.Na_Ba2002`\n",
    "* - Potassium (delayed rectifier, A-type, M-type, Kv, Kir, …)\n",
    "  - {class}`~braincell.channel.K_HH1952`, {class}`~braincell.channel.KDR_Ba2002`\n",
    "* - Calcium (L/N/T/P-type, Cav families)\n",
    "  - {class}`~braincell.channel.CaL_IS2008`, {class}`~braincell.channel.CaT_HM1992`\n",
    "* - Potassium–calcium (Ca-activated K)\n",
    "  - {class}`~braincell.channel.AHP_De1994`, `Kca1p1_*`, `Kca2p2_*`\n",
    "* - Hyperpolarization-activated (H-current)\n",
    "  - {class}`~braincell.channel.HCN_HM1992`\n",
    "* - Leak\n",
    "  - {class}`~braincell.channel.IL`, {class}`~braincell.channel.LeakageChannel`\n",
    "```\n",
    "\n",
    "See the {doc}`../apis/braincell.channel` reference for the complete list.\n",
    "\n",
    "## How ions and channels connect\n",
    "\n",
    "Most channels carry a specific ion's current, so they are **added to that ion**.\n",
    "The ion provides the reversal potential the channel's current depends on:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4df5e377",
   "metadata": {},
   "outputs": [],
   "source": [
    "na = braincell.ion.SodiumFixed(size, E=50. * u.mV)\n",
    "na.add(INa=braincell.channel.Na_HH1952(size))   # INa uses na.E"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4100ddb8",
   "metadata": {},
   "source": [
    "For a multi-compartment {class}`~braincell.Cell` you express the same\n",
    "relationship declaratively, naming the channel as a string in a\n",
    "{class}`~braincell.mech.Channel` (see {doc}`mechanisms`).\n",
    "\n",
    "## Channels that depend on two ions: `MixIons`\n",
    "\n",
    "Some channels (calcium-activated potassium currents, for example) depend on\n",
    "*two* ion species at once — a potassium reversal potential **and** an\n",
    "intracellular calcium concentration. {class}`braincell.MixIons` bundles the\n",
    "relevant ions so such a channel can read both:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d192f4ea",
   "metadata": {},
   "outputs": [],
   "source": [
    "k  = braincell.ion.PotassiumFixed(size, E=-90. * u.mV)\n",
    "ca = braincell.ion.CalciumDetailed(size, ...)\n",
    "\n",
    "kca = braincell.MixIons(k, ca)\n",
    "kca.add(IAHP=braincell.channel.AHP_De1994(size, g_max=0.3 * (u.mS / u.cm**2)))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f4e25a49",
   "metadata": {},
   "source": [
    "The convenience function {func}`braincell.mix_ions` builds the same combination.\n",
    "\n",
    "## The registry\n",
    "\n",
    "Channels and ions self-register at import time via the\n",
    "`@register_channel` / `@register_ion` / `@register_synapse` decorators in\n",
    "{mod}`braincell.mech`. That registry is what lets you refer to a channel by\n",
    "string name (`mech.Channel(\"Na_Ba2002\", ...)`). To add your own, see\n",
    "{doc}`../developer/extending`.\n",
    "\n",
    "## See also\n",
    "\n",
    "- {doc}`mechanisms` — declaring channels/ions on a multi-compartment cell.\n",
    "- {doc}`../apis/braincell.ion` and {doc}`../apis/braincell.channel` — full lists.\n",
    "- {doc}`../tutorials/index` — building neurons from ions and channels."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}