{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "63117032",
   "metadata": {},
   "source": [
    "# Installation\n",
    "\n",
    "`braincell` is a pure-Python package built on [JAX](https://github.com/jax-ml/jax)\n",
    "and [brainstate](https://github.com/chaobrain/brainstate). It runs on Linux,\n",
    "macOS, and Windows (via WSL), and requires **Python 3.10 or newer**.\n",
    "\n",
    "## Quick install\n",
    "\n",
    "The fastest way to get a working CPU install:\n",
    "\n",
    "```bash\n",
    "pip install -U braincell[cpu]\n",
    "```\n",
    "\n",
    "This pulls in `braincell` together with a CPU build of JAX.\n",
    "\n",
    "## Choosing a hardware backend\n",
    "\n",
    "`braincell` inherits JAX's hardware support. Pick the extra that matches your\n",
    "accelerator:\n",
    "\n",
    "````{tab-set}\n",
    "```{tab-item} CPU\n",
    "    pip install -U braincell[cpu]\n",
    "```\n",
    "\n",
    "```{tab-item} GPU (CUDA)\n",
    "    pip install -U braincell[cuda12]\n",
    "\n",
    "    # or, for CUDA 13\n",
    "    pip install -U braincell[cuda13]\n",
    "```\n",
    "\n",
    "```{tab-item} TPU\n",
    "    pip install -U braincell[tpu]\n",
    "```\n",
    "````\n",
    "\n",
    "```{note}\n",
    "If you install plain `braincell` without a hardware extra and no JAX build is\n",
    "present, JAX falls back to CPU. If you have an NVIDIA GPU but installed only the\n",
    "CPU build, you will see a message like *\"An NVIDIA GPU may be present … falling\n",
    "back to cpu\"* — install the matching `cuda` extra to use the GPU.\n",
    "```\n",
    "\n",
    "## Optional feature groups\n",
    "\n",
    "Several capabilities depend on optional libraries, grouped as install extras:\n",
    "\n",
    "| Extra | Installs | Enables |\n",
    "|-------|----------|---------|\n",
    "| `braincell[vis]` | matplotlib, pyvista, plotly | 2-D and 3-D visualization ({mod}`braincell.vis`) |\n",
    "| `braincell[io]` | requests | the NeuroMorpho.Org client ({mod}`braincell.io`) |\n",
    "| `braincell[all]` | all of the above | every optional feature |\n",
    "\n",
    "Extras combine, so you can request several at once:\n",
    "\n",
    "```bash\n",
    "pip install -U \"braincell[cpu,vis,io]\"\n",
    "```\n",
    "\n",
    "## Install with the full ecosystem\n",
    "\n",
    "`braincell` is part of the [BrainX ecosystem](https://brainx.chaobrain.com/).\n",
    "To get `braincell` together with the rest of the stack:\n",
    "\n",
    "```bash\n",
    "pip install -U BrainX\n",
    "```\n",
    "\n",
    "## Development install\n",
    "\n",
    "To work on `braincell` itself, clone the repository and install it in editable\n",
    "mode with the testing extras:\n",
    "\n",
    "```bash\n",
    "git clone https://github.com/chaobrain/braincell.git\n",
    "cd braincell\n",
    "pip install -e \".[testing]\"\n",
    "```\n",
    "\n",
    "Then install the pre-commit hooks and run the test suite to confirm everything\n",
    "works:\n",
    "\n",
    "```bash\n",
    "pre-commit install\n",
    "pytest braincell/\n",
    "```\n",
    "\n",
    "See the {doc}`Developer Guide <../developer/index>` for the project layout,\n",
    "testing conventions, and contribution workflow.\n",
    "\n",
    "## Verifying the install"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ffef2fe1",
   "metadata": {},
   "outputs": [],
   "source": [
    "import braincell\n",
    "print(braincell.__version__)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0390528c",
   "metadata": {},
   "source": [
    "A successful import that prints a version string means you are ready to go.\n",
    "Continue to {doc}`overview` for a map of the library, or jump straight to\n",
    "{doc}`first_steps` to run your first model.\n",
    "\n",
    "## Windows + NEURON (optional)\n",
    "\n",
    "Some validation examples compare `braincell` against the\n",
    "[NEURON](https://neuron.yale.edu) simulator. If you are on Windows and want a\n",
    "WSL-based development setup with `NEURON 8.2.6` and `nrnivmodl`. NEURON is\n",
    "**not** required to use `braincell`."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}