{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "4e4dcf0f",
   "metadata": {},
   "source": [
    "# Quickstart\n",
    "\n",
    "This example trains a small `braintrace.nn.MiniGRU` on one fixed sequence. It shows the complete online-learning path: compile the model, differentiate each time step, scan over the sequence, update parameters, and compare loss from clean initial states."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "1d85c39c",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-07-28T15:23:57.613186Z",
     "iopub.status.busy": "2026-07-28T15:23:57.612959Z",
     "iopub.status.idle": "2026-07-28T15:24:04.370665Z",
     "shell.execute_reply": "2026-07-28T15:24:04.369946Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "SGD(\n",
       "  momentum=0.0,\n",
       "  nesterov=False,\n",
       "  param_states=<braintools.optim.UniqueStateManager object at 0x779af84e4050>,\n",
       "  weight_decay=0.0,\n",
       "  step_count=OptimState(\n",
       "    value=ShapedArray(int32[], weak_type=True)\n",
       "  ),\n",
       "  param_groups=[\n",
       "    {\n",
       "      'params': {\n",
       "        ('readout', 'weight'): ParamState(\n",
       "          value={\n",
       "            'bias': ShapedArray(float32[1]),\n",
       "            'weight': ShapedArray(float32[6,1])\n",
       "          }\n",
       "        ),\n",
       "        ('rnn', 'W_x', 'weight'): ParamState(\n",
       "          value={\n",
       "            'bias': ShapedArray(float32[6], weak_type=True),\n",
       "            'weight': ShapedArray(float32[1,6])\n",
       "          }\n",
       "        ),\n",
       "        ('rnn', 'W_z', 'weight'): ParamState(\n",
       "          value={\n",
       "            'bias': ShapedArray(float32[6], weak_type=True),\n",
       "            'weight': ShapedArray(float32[7,6])\n",
       "          }\n",
       "        )\n",
       "      },\n",
       "      'lr': OptimState(\n",
       "        value=ShapedArray(float32[], weak_type=True)\n",
       "      ),\n",
       "      'weight_decay': 0.0\n",
       "    }\n",
       "  ],\n",
       "  param_groups_opt_states=[],\n",
       "  _schedulers=[],\n",
       "  _lr_scheduler=<braintools.optim.ConstantLR object at 0x779af84e4440>,\n",
       "  _base_lr=0.08,\n",
       "  _current_lr=OptimState(...),\n",
       "  tx=GradientTransformationExtraArgs(init=<function chain.<locals>.init_fn at 0x779af84f4860>, update=<function chain.<locals>.update_fn at 0x779af84f4a40>),\n",
       "  opt_state=OptimState(\n",
       "    value=(ScaleByScheduleState(count=ShapedArray(int32[])),)\n",
       "  )\n",
       ")"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import brainstate\n",
    "import braintools\n",
    "import braintrace\n",
    "import jax.numpy as jnp\n",
    "import matplotlib.pyplot as plt\n",
    "\n",
    "# Fixed model initialization and fixed data make the result reproducible.\n",
    "brainstate.random.seed(7)\n",
    "\n",
    "\n",
    "class SequenceModel(brainstate.nn.Module):\n",
    "    def __init__(self):\n",
    "        super().__init__()\n",
    "        self.rnn = braintrace.nn.MiniGRU(in_size=1, out_size=6)\n",
    "        self.readout = braintrace.nn.Linear(6, 1)\n",
    "\n",
    "    def update(self, x):\n",
    "        return self.readout(self.rnn(x))\n",
    "\n",
    "\n",
    "model = SequenceModel()\n",
    "inputs = jnp.linspace(-1.0, 1.0, 12).reshape(12, 1, 1)\n",
    "targets = 0.7 * inputs + 0.2\n",
    "\n",
    "# Compile once. inputs[0] is one batched time step with shape (1, 1).\n",
    "# The compiler reports that the readout is non-temporal because it does not\n",
    "# feed a recurrent state.\n",
    "learner = braintrace.compile(\n",
    "    model,\n",
    "    braintrace.D_RTRL,\n",
    "    inputs[0],\n",
    "    batch_size=1,\n",
    ")\n",
    "weights = model.states(brainstate.ParamState)\n",
    "optimizer = braintools.optim.SGD(lr=0.08)\n",
    "optimizer.register_trainable_weights(weights)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "1718c191",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-07-28T15:24:04.373217Z",
     "iopub.status.busy": "2026-07-28T15:24:04.372699Z",
     "iopub.status.idle": "2026-07-28T15:24:04.377439Z",
     "shell.execute_reply": "2026-07-28T15:24:04.376586Z"
    }
   },
   "outputs": [],
   "source": [
    "def reset_sequence():\n",
    "    # Hidden states and eligibility traces are independent state systems.\n",
    "    brainstate.nn.reset_all_states(model, batch_size=1)\n",
    "    learner.reset_state(batch_size=1)\n",
    "\n",
    "\n",
    "def evaluate():\n",
    "    reset_sequence()\n",
    "    predictions = learner.etrace_evolve(inputs, return_outputs=True)\n",
    "    return jnp.mean((predictions - targets) ** 2)\n",
    "\n",
    "\n",
    "def local_loss(x, target):\n",
    "    prediction = learner(x)\n",
    "    return jnp.mean((prediction - target) ** 2)\n",
    "\n",
    "\n",
    "def train_epoch(_):\n",
    "    reset_sequence()\n",
    "    # etrace_grad owns the loop, the accumulation and the reduction; local_loss\n",
    "    # owns the model call. 'mean' divides by the total mask weight -- here T --\n",
    "    # which is exactly the hand-written `grads / inputs.shape[0]` it replaces.\n",
    "    grads, step_losses = learner.etrace_grad(\n",
    "        inputs, targets, step_fn=local_loss,\n",
    "        reduction='mean', return_value=True,\n",
    "    )\n",
    "    optimizer.update(grads)\n",
    "    return step_losses.mean()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "3a715e09",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-07-28T15:24:04.379771Z",
     "iopub.status.busy": "2026-07-28T15:24:04.379560Z",
     "iopub.status.idle": "2026-07-28T15:24:05.093432Z",
     "shell.execute_reply": "2026-07-28T15:24:05.092718Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "initial loss: 0.0802\n",
      "final loss: 0.0086\n"
     ]
    },
    {
     "data": {
      "image/png": "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vyiTycS7d+9qYw8ODtbpExoaKg4ePFgURVHcvXu3KJfLxeTkZO36f//9VwQgHjlyRBRFUfT39xdfeOGFB8bh6uoqvvjii9pljUYjOjg4iF988cUDtyEiamx4poKIqAnp0aOHznJOTg7eeustdOzYETY2NrCwsEBCQsIjz1R07dpV+97c3BxWVlZIS0t7YH8zMzO4u7trl1u0aKHtn5WVhdTUVJ2//svlcnTv3v2hMZw8eRIbN26EhYWF9hUUFASNRoNLly5p+/n7++ts5+/vj4SEBABAQkICXFxc4OLiol3fqVMn2NjYaPucOHECAwcOfGgs938/yi47e9j3g4ioseFEbSKiJsTc3Fxn+a233kJUVBQ+/vhjeHh4wNTUFM8++ywKCwsfOo6xsbHOsiAI0Gg0BvUXRdHA6HXl5OTg1VdfxdSpUyusa926dbXGvp+pqekj+xj6/SAiamx4poKIqAk7ePAgJkyYgBEjRsDLywtOTk64fPlyncZgbW0NR0dHHD16VNumVqsRFxf30O26deuGM2fOwMPDo8LLxMRE2+/QoUM62x06dAgdO3YEAHTs2BFXr17F1atXtevPnDmDO3fuoFOnTgBKzkJER0dX+ziJiBoznqkgImrC2rVrh+3bt+Ppp5+GIAhYsGCBJH9hnzJlCpYtWwYPDw94enri888/x+3btyEIwgO3mT17Nnr16oXJkyfj5Zdfhrm5Oc6cOYOoqCisXr1a2+/gwYP46KOPEBISgqioKGzbtg07d+4EAAQGBsLLywsvvPACVq1aheLiYrzxxhvo37+/9lKxRYsWYeDAgXB3d8fo0aNRXFyMXbt2Yfbs2bX7TSEiakB4poKIqAlbsWIFmjVrhoCAADz99NMICgpCt27d6jyO2bNnY8yYMRg3bhz8/f218yOUSuUDt+natSv27duHc+fOoW/fvnjsscewcOFCODs76/SbOXMmjh07hsceewxLly7FihUrEBQUBKDkMqVffvkFzZo1Q79+/RAYGIi2bdti69at2u0HDBiAbdu2YceOHfDx8cETTzyBI0eO1M43goiogRLE6l7USkREVMM0Gg06duyIUaNG4b333qvyOG5ubpg+fTqmT59ec8EREVEFvPyJiIgkd+XKFezevRv9+/dHQUEBVq9ejUuXLuH555+XOjQiIqoEXv5ERESSk8lk2LhxI3r27InevXvjn3/+wZ9//qmdUE1ERPUbL38iIiIiIqJq4ZkKIiIiIiKqFhYVRERERERULSwqiIiIiIioWlhUEBERERFRtbCoICIiIiKiamFRQURERERE1cKigoiIiIiIqoVFBRERERERVQuLCiIiIiIiqpb/B3KBoJALIIrAAAAAAElFTkSuQmCC",
      "text/plain": [
       "<Figure size 800x400 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "initial_loss = evaluate()\n",
    "training_losses = brainstate.transform.for_loop(\n",
    "    train_epoch, jnp.arange(25)\n",
    ")\n",
    "final_loss = evaluate()\n",
    "\n",
    "print(f\"initial loss: {float(initial_loss):.4f}\")\n",
    "print(f\"final loss: {float(final_loss):.4f}\")\n",
    "\n",
    "with plt.style.context(\"default\"), plt.rc_context({\n",
    "    \"figure.facecolor\": \"white\",\n",
    "    \"axes.facecolor\": \"white\",\n",
    "    \"savefig.facecolor\": \"white\",\n",
    "}):\n",
    "    fig, ax = plt.subplots(figsize=(8, 4))\n",
    "    ax.plot(training_losses)\n",
    "    ax.set(xlabel=\"Training epoch\", ylabel=\"Mean sequence loss\")\n",
    "    ax.set_title(\"Online mini-GRU training loss\")\n",
    "    ax.grid(True, alpha=0.3)\n",
    "    fig.tight_layout()\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ff37b222",
   "metadata": {},
   "source": [
    "With the fixed seed, the final loss should be lower than the initial loss. The example deliberately resets both recurrent and eligibility state before each sequence; otherwise the two loss values would not describe the same initial condition.\n",
    "\n",
    "## What happened\n",
    "\n",
    "`braintrace.compile` discovers which MiniGRU parameters reach recurrent hidden state through ETP primitives. `learner.etrace_grad` then drives the whole sequence: it takes the per-step online gradient at each step, carries the accumulator across time, and applies the reduction — `'mean'` divides by the number of steps. `learner.etrace_evolve` is the same drive without a loss, used by `evaluate` to advance hidden state and eligibility traces and return the outputs. `brainstate.transform.for_loop` performs the repeated epoch updates without repeatedly dispatching model calls from Python.\n",
    "\n",
    "## Next steps\n",
    "\n",
    "- [Core Concepts](concepts.ipynb) explains how ETP primitives select trainable pathways.\n",
    "- [RNN Online Learning](../tutorials/rnn_online_learning.ipynb) develops the rate-RNN workflow.\n",
    "- [SNN Online Learning](../tutorials/snn_online_learning.ipynb) develops the spiking-network workflow."
   ]
  }
 ],
 "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
}