{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "17f52c94",
   "metadata": {},
   "source": [
    "# How to use surrogate gradients\n",
    "\n",
    "**Task.** Make a spiking network trainable by replacing the non-differentiable\n",
    "spike threshold with a surrogate gradient, and see how the choice of surrogate\n",
    "affects training.\n",
    "\n",
    "**Audience.** Training. Assumes {doc}`../tutorials/04-train-an-snn`.\n",
    "\n",
    "The spike function is a hard threshold, so its derivative is zero almost\n",
    "everywhere and a delta at threshold — useless for gradient descent. A\n",
    "**surrogate gradient** keeps the forward spike exact but substitutes a smooth\n",
    "derivative on the backward pass. In `brainpy.state` you select one by passing a\n",
    "`braintools.surrogate` object as the neuron's `spk_fun=`. This guide trains the\n",
    "same tiny network with several surrogates and compares the loss curves."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "0ff4a60f",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-06-17T09:09:10.808202Z",
     "iopub.status.busy": "2026-06-17T09:09:10.807857Z",
     "iopub.status.idle": "2026-06-17T09:09:14.953109Z",
     "shell.execute_reply": "2026-06-17T09:09:14.952161Z"
    }
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "An NVIDIA GPU may be present on this machine, but a CUDA-enabled jaxlib is not installed. Falling back to cpu.\n"
     ]
    }
   ],
   "source": [
    "import brainpy\n",
    "import brainstate\n",
    "import braintools\n",
    "import brainunit as u\n",
    "import matplotlib.pyplot as plt\n",
    "import numpy as np"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2d19179d",
   "metadata": {},
   "source": [
    "## A network parametrized by its surrogate\n",
    "\n",
    "We pass the surrogate function in, so we can rebuild the same architecture with a\n",
    "different `spk_fun`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "408ef323",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-06-17T09:09:14.955637Z",
     "iopub.status.busy": "2026-06-17T09:09:14.955030Z",
     "iopub.status.idle": "2026-06-17T09:09:14.960992Z",
     "shell.execute_reply": "2026-06-17T09:09:14.960184Z"
    }
   },
   "outputs": [],
   "source": [
    "class SNN(brainstate.nn.Module):\n",
    "    def __init__(self, n_in, n_rec, n_out, spk_fun):\n",
    "        super().__init__()\n",
    "        self.i2r = brainstate.nn.Sequential(\n",
    "            brainstate.nn.Linear(\n",
    "                n_in, n_rec,\n",
    "                w_init=braintools.init.KaimingNormal(unit=u.mA),\n",
    "                b_init=braintools.init.ZeroInit(unit=u.mA)),\n",
    "            brainpy.state.Expon(n_rec, tau=5. * u.ms,\n",
    "                                g_initializer=braintools.init.Constant(0. * u.mA)))\n",
    "        self.r = brainpy.state.LIF(\n",
    "            n_rec, tau=20. * u.ms, V_rest=0. * u.mV, V_reset=0. * u.mV,\n",
    "            V_th=1. * u.mV, spk_fun=spk_fun)\n",
    "        self.r2o = brainstate.nn.Linear(\n",
    "            n_rec, n_out, w_init=braintools.init.KaimingNormal())\n",
    "        self.o = brainpy.state.Expon(\n",
    "            n_out, tau=10. * u.ms, g_initializer=braintools.init.Constant(0.))\n",
    "\n",
    "    def update(self, spike):\n",
    "        return self.o(self.r2o(self.r(self.i2r(spike))))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a3230395",
   "metadata": {},
   "source": [
    "## Train with each surrogate\n",
    "\n",
    "A compact training routine: build the network with the given surrogate, then run\n",
    "a short optimization loop. Each `train_step` is JIT-compiled; the outer epoch\n",
    "loop is a plain Python loop (which is fine — it only calls the compiled step)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "a3578046",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-06-17T09:09:14.962711Z",
     "iopub.status.busy": "2026-06-17T09:09:14.962556Z",
     "iopub.status.idle": "2026-06-17T09:09:14.967726Z",
     "shell.execute_reply": "2026-06-17T09:09:14.966877Z"
    }
   },
   "outputs": [],
   "source": [
    "def train(spk_fun, n_epoch=150):\n",
    "    with brainstate.environ.context(dt=1.0 * u.ms):\n",
    "        n_in, n_rec, n_out = 100, 4, 2\n",
    "        num_step, num_sample = 200, 256\n",
    "        net = SNN(n_in, n_rec, n_out, spk_fun)\n",
    "        x_data = (brainstate.random.rand(num_step, num_sample, n_in)\n",
    "                  < 5. * u.Hz * brainstate.environ.get_dt()).astype(float)\n",
    "        y_data = u.math.asarray(brainstate.random.rand(num_sample) < 0.5, dtype=int)\n",
    "\n",
    "        optimizer = braintools.optim.Adam(lr=3e-3)\n",
    "        optimizer.register_trainable_weights(net.states(brainstate.ParamState))\n",
    "\n",
    "        def loss_fn():\n",
    "            preds = brainstate.transform.for_loop(net.update, x_data)\n",
    "            preds = u.math.mean(preds, axis=0)\n",
    "            return braintools.metric.softmax_cross_entropy_with_integer_labels(\n",
    "                preds, y_data).mean()\n",
    "\n",
    "        @brainstate.transform.jit\n",
    "        def train_step():\n",
    "            brainstate.nn.init_all_states(net, batch_size=num_sample)\n",
    "            grads, l = brainstate.transform.grad(\n",
    "                loss_fn, net.states(brainstate.ParamState), return_value=True)()\n",
    "            optimizer.update(grads)\n",
    "            return l\n",
    "\n",
    "        return [float(train_step()) for _ in range(n_epoch)]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "fc1626f6",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-06-17T09:09:14.969352Z",
     "iopub.status.busy": "2026-06-17T09:09:14.969203Z",
     "iopub.status.idle": "2026-06-17T09:09:26.751128Z",
     "shell.execute_reply": "2026-06-17T09:09:26.749925Z"
    }
   },
   "outputs": [],
   "source": [
    "surrogates = {\n",
    "    'ReluGrad': braintools.surrogate.ReluGrad(),\n",
    "    'Sigmoid': braintools.surrogate.Sigmoid(),\n",
    "    'Arctan': braintools.surrogate.Arctan(),\n",
    "}\n",
    "curves = {name: train(fn) for name, fn in surrogates.items()}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e4f0f84f",
   "metadata": {},
   "source": [
    "## Compare the loss curves\n",
    "\n",
    "All three surrogates drive the loss down; they differ in smoothness and\n",
    "therefore in optimization dynamics. `ReluGrad` is a common default. Browse the\n",
    "full set in the API reference."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "8a47e20d",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-06-17T09:09:26.753853Z",
     "iopub.status.busy": "2026-06-17T09:09:26.753422Z",
     "iopub.status.idle": "2026-06-17T09:09:26.833989Z",
     "shell.execute_reply": "2026-06-17T09:09:26.833399Z"
    }
   },
   "outputs": [
    {
     "data": {
      "image/png": "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",
      "text/plain": [
       "<Figure size 600x350 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "plt.figure(figsize=(6, 3.5))\n",
    "for name, losses in curves.items():\n",
    "    plt.plot(np.asarray(losses), label=name)\n",
    "plt.xlabel('Epoch'); plt.ylabel('Training loss'); plt.legend()\n",
    "plt.title('Effect of the surrogate gradient')\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e42c53a9",
   "metadata": {},
   "source": [
    "## See also\n",
    "\n",
    "- {doc}`/concepts/differentiability` — surrogate gradients and BPTT explained.\n",
    "- {doc}`train-readouts` — add a trainable rate readout.\n",
    "- {doc}`train-long-rollouts-checkpoint` — bound memory for long sequences."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.13.11"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
