{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "814336fa",
   "metadata": {},
   "source": [
    "# Troubleshooting & FAQ\n",
    "\n",
    "Common errors, what they mean, and how to fix them.\n",
    "\n",
    "## \"TypeError: expected a quantity\" (or a bare-number rejection)\n",
    "\n",
    "**Cause.** You passed a plain `float`/`int` where `braincell` expects a united\n",
    "quantity. Units are mandatory everywhere (see {doc}`../concepts/units`).\n",
    "\n",
    "**Fix.** Attach a unit:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "954528a6",
   "metadata": {},
   "outputs": [],
   "source": [
    "# wrong\n",
    "g_max = 0.03\n",
    "# right\n",
    "import brainunit as u\n",
    "g_max = 0.03 * (u.mS / u.cm**2)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6153980f",
   "metadata": {},
   "source": [
    "## \"An NVIDIA GPU may be present … falling back to cpu\"\n",
    "\n",
    "**Cause.** JAX found a GPU but no CUDA-enabled `jaxlib` is installed, so it runs\n",
    "on CPU. This is a *warning*, not an error — everything still works.\n",
    "\n",
    "**Fix (to use the GPU).** Install the matching CUDA build:\n",
    "\n",
    "```bash\n",
    "pip install -U braincell[cuda12]   # or braincell[cuda13]\n",
    "```\n",
    "\n",
    "If you *intend* to run on CPU, you can ignore the message.\n",
    "\n",
    "## \"Cell.run(...) requires at least one placed probe\"\n",
    "\n",
    "**Cause.** A multi-compartment {class}`~braincell.Cell` simulation returns probe\n",
    "traces, so it needs at least one probe to know what to record.\n",
    "\n",
    "**Fix.** `place` a probe before running:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e3e634bc",
   "metadata": {},
   "outputs": [],
   "source": [
    "import braincell.mech as mech\n",
    "from braincell.filter import RootLocation\n",
    "\n",
    "cell.place(RootLocation(0.5), mech.StateProbe(\"V\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ae1e4823",
   "metadata": {},
   "source": [
    "See {doc}`../concepts/mechanisms`.\n",
    "\n",
    "## \"dt\"/\"duration\" rejected as zero, negative, or unitless\n",
    "\n",
    "**Cause.** `Cell.run(dt=..., duration=...)` validates its time arguments: they\n",
    "must be positive `brainunit` time quantities.\n",
    "\n",
    "**Fix.**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b70fefa5",
   "metadata": {},
   "outputs": [],
   "source": [
    "result = cell.run(dt=0.1 * u.ms, duration=100 * u.ms)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "27291a94",
   "metadata": {},
   "source": [
    "## `ImportError` / `ModuleNotFoundError` for matplotlib, pyvista, plotly\n",
    "\n",
    "**Cause.** Visualization backends are optional dependencies, imported lazily.\n",
    "\n",
    "**Fix.** Install the visualization extra:\n",
    "\n",
    "```bash\n",
    "pip install -U braincell[vis]\n",
    "```\n",
    "\n",
    "Likewise, the NeuroMorpho client needs `braincell[io]`.\n",
    "\n",
    "## A solver name isn't recognized\n",
    "\n",
    "**Cause.** The `solver=` string doesn't match a registered integrator.\n",
    "\n",
    "**Fix.** List the available names and pick one:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d4002fc1",
   "metadata": {},
   "outputs": [],
   "source": [
    "import braincell.quad as quad\n",
    "sorted(quad.all_integrators)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9c2fda8d",
   "metadata": {},
   "source": [
    "See {doc}`../concepts/integration`.\n",
    "\n",
    "## My simulation is unstable / blows up\n",
    "\n",
    "**Cause.** Biophysical models are **stiff**; an explicit solver (e.g. `euler`,\n",
    "`rk4`) needs a very small `dt` to stay stable.\n",
    "\n",
    "**Fix.** Reduce `dt`, or switch to a solver designed for stiff systems —\n",
    "`exp_euler` / `ind_exp_euler` for single-compartment channel kinetics, or the\n",
    "staggered / Crank–Nicolson solvers for cable equations. See\n",
    "{doc}`../integration/index`.\n",
    "\n",
    "## An SWC/ASC file fails to load\n",
    "\n",
    "**Cause.** Reconstructions often have irregularities (unknown structure ids,\n",
    "non-soma roots, disconnected points).\n",
    "\n",
    "**Fix.** Read with a report and/or relaxed options to see and handle the issue:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "eb51f0ae",
   "metadata": {},
   "outputs": [],
   "source": [
    "morpho, report = braincell.Morphology.from_swc(\"neuron.swc\", return_report=True)\n",
    "print(report)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0f641cfd",
   "metadata": {},
   "source": [
    "See {doc}`../file_formats/swc`.\n",
    "\n",
    "## Still stuck?\n",
    "\n",
    "- Re-read the relevant {doc}`concept page <../concepts/architecture>`.\n",
    "- Check the {doc}`API reference <../apis/braincell>` for exact signatures.\n",
    "- Search or open an issue at\n",
    "  [github.com/chaobrain/braincell/issues](https://github.com/chaobrain/braincell/issues)."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}