{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "9a8a9102",
   "metadata": {},
   "source": [
    "# Defining Differential Equations\n",
    "\n",
    "This page shows how to express a differential-equation system in `braincell`\n",
    "using the two protocol pieces introduced in the [overview](overview):\n",
    "`DiffEqState` and `DiffEqModule`. By the end you will have built a runnable\n",
    "model from scratch and integrated it with a real solver."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "f3792182",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-25T08:58:06.898009Z",
     "iopub.status.busy": "2026-05-25T08:58:06.897711Z",
     "iopub.status.idle": "2026-05-25T08:58:10.294367Z",
     "shell.execute_reply": "2026-05-25T08:58:10.293389Z"
    }
   },
   "outputs": [],
   "source": [
    "import brainstate\n",
    "import numpy as np\n",
    "import jax.numpy as jnp\n",
    "import matplotlib.pyplot as plt\n",
    "\n",
    "import braincell\n",
    "from braincell import DiffEqState, DiffEqModule"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3a5cfcce",
   "metadata": {},
   "source": [
    "## `DiffEqState`: a variable the solver integrates\n",
    "\n",
    "`DiffEqState` extends `brainstate.HiddenState` with two extra slots that the\n",
    "solver reads and writes during a step:\n",
    "\n",
    "- **`derivative`** — the right-hand side $f(t, y)$ of an ODE $\\dot y = f(t, y)$,\n",
    "  or the *drift* term of an SDE. You set this inside `compute_derivative`.\n",
    "- **`diffusion`** — the noise coefficient of an SDE. It stays `None` for\n",
    "  ordinary (deterministic) systems. See\n",
    "  [Advanced Integration](advanced) for the current status of stochastic solvers.\n",
    "\n",
    "### The units rule\n",
    "\n",
    "If your state carries physical units, the derivative must carry units such that\n",
    "\n",
    "$$\\text{unit}(\\texttt{derivative}) \\times \\text{unit}(\\texttt{dt}) = \\text{unit}(\\texttt{value}).$$\n",
    "\n",
    "For a membrane potential in `mV` integrated with `dt` in `ms`, the derivative\n",
    "must be in `mV/ms`. The examples below stay dimensionless for clarity, but this\n",
    "constraint is what lets `braincell` integrate fully unit-aware neuron models."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a7469d90",
   "metadata": {},
   "source": [
    "## `DiffEqModule`: the integrable container\n",
    "\n",
    "`DiffEqModule` is a mixin that exposes the per-step lifecycle. To build a model\n",
    "you combine it with a `brainstate` node so its states are discoverable by the\n",
    "solver:\n",
    "\n",
    "```python\n",
    "class MyModel(brainstate.nn.Dynamics, DiffEqModule):\n",
    "    ...\n",
    "```\n",
    "\n",
    "You override:\n",
    "\n",
    "- **`compute_derivative`** (required) — write `state.derivative` for every\n",
    "  `DiffEqState` the module owns.\n",
    "- **`pre_integral`** / **`post_integral`** (optional) — one-time-per-step work\n",
    "  before and after the solver combines values and derivatives."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "232b058a",
   "metadata": {},
   "source": [
    "## Worked example 1 — scalar exponential decay\n",
    "\n",
    "The simplest non-trivial ODE is exponential decay,\n",
    "\n",
    "$$\\frac{dy}{dt} = -\\frac{y}{\\tau}, \\qquad y(0) = 1,$$\n",
    "\n",
    "whose exact solution is $y(t) = e^{-t/\\tau}$. We model it as a single\n",
    "`DiffEqState`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "92776ee5",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-25T08:58:10.297974Z",
     "iopub.status.busy": "2026-05-25T08:58:10.297313Z",
     "iopub.status.idle": "2026-05-25T08:58:10.302626Z",
     "shell.execute_reply": "2026-05-25T08:58:10.301591Z"
    }
   },
   "outputs": [],
   "source": [
    "class Decay(brainstate.nn.Dynamics, DiffEqModule):\n",
    "    def __init__(self, tau=10.0):\n",
    "        super().__init__(in_size=1)\n",
    "        self.tau = tau\n",
    "\n",
    "    def init_state(self, *args):\n",
    "        # the one variable we integrate, initialised to 1.0\n",
    "        self.y = DiffEqState(jnp.ones(1))\n",
    "\n",
    "    def compute_derivative(self, *args):\n",
    "        # dy/dt = -y / tau\n",
    "        self.y.derivative = -self.y.value / self.tau"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "10c7542c",
   "metadata": {},
   "source": [
    "To run it we pick a solver from the registry and step inside a\n",
    "`brainstate.environ` context that supplies `dt` (and `t` each step)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "d8a77473",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-25T08:58:10.304576Z",
     "iopub.status.busy": "2026-05-25T08:58:10.304335Z",
     "iopub.status.idle": "2026-05-25T08:58:11.914633Z",
     "shell.execute_reply": "2026-05-25T08:58:11.913772Z"
    }
   },
   "outputs": [
    {
     "data": {
      "image/png": "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",
      "text/plain": [
       "<Figure size 600x350 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "max abs error (rk4): 2.1823778006968553e-07\n"
     ]
    }
   ],
   "source": [
    "def integrate(model, solver_name, dt=0.1, t_end=50.0):\n",
    "    brainstate.nn.init_all_states(model)\n",
    "    step = braincell.quad.get_integrator(solver_name)\n",
    "    n = int(t_end / dt)\n",
    "    ts, ys = [], []\n",
    "    with brainstate.environ.context(dt=dt):\n",
    "        for i in range(n):\n",
    "            with brainstate.environ.context(t=i * dt):\n",
    "                step(model)\n",
    "            ts.append((i + 1) * dt)\n",
    "            ys.append(float(model.y.value[0]))\n",
    "    return np.array(ts), np.array(ys)\n",
    "\n",
    "t, y_rk4 = integrate(Decay(tau=10.0), \"rk4\")\n",
    "t_exact = np.linspace(0, t[-1], 400)\n",
    "y_exact = np.exp(-t_exact / 10.0)\n",
    "\n",
    "plt.figure(figsize=(6, 3.5))\n",
    "plt.plot(t_exact, y_exact, \"k-\", label=\"exact  $e^{-t/\\\\tau}$\")\n",
    "plt.plot(t[::5], y_rk4[::5], \"o\", ms=4, label=\"rk4\")\n",
    "plt.xlabel(\"t\"); plt.ylabel(\"y\"); plt.legend(); plt.title(\"Exponential decay\")\n",
    "plt.tight_layout(); plt.show()\n",
    "\n",
    "print(\"max abs error (rk4):\", np.max(np.abs(y_rk4 - np.exp(-t / 10.0))))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "26340e1c",
   "metadata": {},
   "source": [
    "The Runge-Kutta solution sits right on top of the analytic curve — the\n",
    "error is at the level of floating-point noise for this smooth, well-conditioned\n",
    "problem."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "de43dcc4",
   "metadata": {},
   "source": [
    "## Worked example 2 — a two-state system\n",
    "\n",
    "A module can own several `DiffEqState`s. Here is an undamped harmonic\n",
    "oscillator,\n",
    "\n",
    "$$\\frac{dx}{dt} = v, \\qquad \\frac{dv}{dt} = -\\omega^2 x,$$\n",
    "\n",
    "which traces $x(t) = \\cos(\\omega t)$ for $x(0)=1,\\ v(0)=0$. Each variable is its\n",
    "own `DiffEqState`, and `compute_derivative` fills both in one pass."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "c4907745",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-25T08:58:11.916515Z",
     "iopub.status.busy": "2026-05-25T08:58:11.916322Z",
     "iopub.status.idle": "2026-05-25T08:58:14.580539Z",
     "shell.execute_reply": "2026-05-25T08:58:14.579625Z"
    }
   },
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAAk4AAAFUCAYAAADS/LOVAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjEwLjgsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvwVt1zgAAAAlwSFlzAAAPYQAAD2EBqD+naQAAfm9JREFUeJzt3Xd8U9X7B/BPkqbpoHsX6GK1pWUVKRUElErLEnCCIIgIgiBTVBzgRnH8GCoIgoDi/goiQrGUKZQCLQUKpawOoJu26V7J+f1R77Whg44k9yZ53q9Xvn6b3tz7JL3c++Sc55wjYYwxEEIIIYSQe5IKHQAhhBBCiKGgxIkQQgghpIUocSKEEEIIaSFKnAghhBBCWogSJ0IIIYSQFqLEiRBCCCGkhShxIoQQQghpIUqcCCGEEEJaiBInQgghhJAWosSJEGJyDh8+DIlEgsOHDwsdSqs1Fvuzzz4LHx8fje0kEgnefvttvcZGiCmgxIkQE7J161ZIJBKcOXOm0d8PGzYMQUFBeo6KiMmlS5fw9ttvIy0tTehQCBElM6EDIIQQfRsyZAgqKipgbm4udCitpuvYL126hHfeeQfDhg1r0IpFCKEWJ0KIjjDGUFFRIXQYjZJKpbCwsIBUaniXQEONvby8XOgQCNEKw/qXRwjRu2+//RYPPfQQXF1doVAoEBgYiPXr1zfYzsfHB2PGjMH+/fvRv39/WFpa4uuvv+Zrcn755Re888476NixI2xsbPD4449DqVSiqqoKCxcuhKurKzp06IDp06ejqqpKY9+1tbV477330KVLFygUCvj4+OD1119vsB0Xwz///IMBAwbAwsICfn5+2L59u8Z2TdU4xcXFYdSoUXBwcIC1tTV69eqFNWvW3PMzunHjBp544gk4OjrCysoKAwcOxF9//dVgu3Xr1qFnz56wsrKCg4MD+vfvjx9++EFjm9u3b2PGjBnw9PSEQqGAr68v5syZg+rq6mZjv5f09HS8+OKL6NGjBywtLeHk5IQnnnhCo0tu69ateOKJJwAADz74ICQSSYNjffXVV+jZsycUCgU8PT0xd+5cFBUVaRyL6/KNj4/HkCFDYGVlhddff71V8RIiVtRVR4gJUiqVyM/Pb/B8TU1Ng+fWr1+Pnj174pFHHoGZmRn+/PNPvPjii1Cr1Zg7d67GtikpKZg0aRJeeOEFzJw5Ez169OB/t3LlSlhaWuK1117DtWvXsG7dOsjlckilUhQWFuLtt9/GyZMnsXXrVvj6+mL58uX8a59//nls27YNjz/+OJYsWYK4uDisXLkSycnJ2Llzp0YM165dw+OPP44ZM2Zg2rRp2LJlC5599lmEhISgZ8+eTX4m0dHRGDNmDDw8PLBgwQK4u7sjOTkZe/bswYIFC5p8XU5ODu6//36Ul5dj/vz5cHJywrZt2/DII4/gt99+w4QJEwAAmzZtwvz58/H4449jwYIFqKysxPnz5xEXF4enn34aAJCZmYkBAwagqKgIs2bNgr+/P27fvo3ffvsN5eXl7eqeO336NE6cOIGJEyeiU6dOSEtLw/r16zFs2DBcunQJVlZWGDJkCObPn4+1a9fi9ddfR0BAAADw/3377bfxzjvvIDw8HHPmzEFKSgrWr1+P06dP4/jx45DL5fzx7ty5g5EjR2LixImYMmUK3Nzc2hw7IaLCCCEm49tvv2UAmn307NlT4zXl5eUN9hMREcH8/Pw0nvP29mYAWFRUlMbzhw4dYgBYUFAQq66u5p+fNGkSk0gkbOTIkRrbh4WFMW9vb/7nxMREBoA9//zzGtu9/PLLDAA7ePBggxiOHj3KP5ebm8sUCgVbsmRJg5gOHTrEGGOstraW+fr6Mm9vb1ZYWKhxHLVa3eD917dw4UIGgB07dox/rqSkhPn6+jIfHx+mUqkYY4yNGzeuwWd7t6lTpzKpVMpOnz7d4HdcHHfHzhhj06ZN0/jMGGMMAFuxYgX/c2N/x9jYWAaAbd++nX/u119/bbB/xuo+R3NzczZixAj+PTHG2BdffMEAsC1btvDPDR06lAFgGzZsaPb9EmKIqKuOEBP05ZdfIjo6usGjV69eDba1tLTk/z/XUjV06FDcuHEDSqVSY1tfX19EREQ0esypU6dqtEiEhoaCMYbnnntOY7vQ0FDcvHkTtbW1AIC9e/cCABYvXqyx3ZIlSwCgQZdYYGAgHnjgAf5nFxcX9OjRAzdu3Gj8wwBw9uxZpKamYuHChbC3t9f4nUQiafJ1XHwDBgzA4MGD+ec6dOiAWbNmIS0tDZcuXQIA2Nvb49atWzh9+nSj+1Gr1di1axfGjh2L/v37N/j9veK4l/p/x5qaGty5cwddu3aFvb09EhIS7vn6AwcOoLq6GgsXLtSor5o5cyZsbW0b/B0UCgWmT5/erpgJESPqqiPEBA0YMKDRm7ODg0ODLrzjx49jxYoViI2NbVDgq1QqYWdnx//s6+vb5DG9vLw0fuZe17lz5wbPq9VqKJVKODk5IT09HVKpFF27dtXYzt3dHfb29khPT2/2ONz7KiwsbDK269evA0CbpmJIT09HaGhog+e57q309HQEBQXh1VdfxYEDBzBgwAB07doVI0aMwNNPP41BgwYBAPLy8lBcXKyz6SAqKiqwcuVKfPvtt7h9+zYYY/zv7k6AG8N9zvW7XwHA3Nwcfn5+Df4OHTt2NMhRi4TcC7U4EUKadP36dQwfPhz5+fn4/PPP8ddffyE6OhqLFi0CUNdKUl/9Vo27yWSyVj1f/8YOtLzFpaX707eAgACkpKTgp59+wuDBg/G///0PgwcPxooVK/Ry/JdeegkffPABnnzySfzyyy/4+++/ER0dDScnpwZ/R21o7lwgxJBRixMhpEl//vknqqqqsHv3bo2WnEOHDuktBm9vb6jValy9epVvxQHqirKLiorg7e3d7mN06dIFAJCUlITw8PBWx5eSktLg+cuXL/O/51hbW+Opp57CU089herqajz66KP44IMPsGzZMri4uMDW1hZJSUnteCdN++233zBt2jR89tln/HOVlZUNRsQ1laBy7yMlJQV+fn7889XV1UhNTW3150aIoaIWJ0JIk7jWm7u7db799lu9xTBq1CgAwOrVqzWe//zzzwEAo0ePbvcx+vXrB19fX6xevbpBInGvlqpRo0bh1KlTiI2N5Z8rKyvDxo0b4ePjg8DAQAB1o8zqMzc3R2BgIBhjqKmpgVQqxfjx4/Hnn382OrN7e1vMZDJZg32sW7cOKpVK4zlra2sAaPA5hIeHw9zcHGvXrtXYz+bNm6FUKrXydyDEEFCLEyGkSSNGjIC5uTnGjh2LF154AaWlpdi0aRNcXV2RlZWllxh69+6NadOmYePGjSgqKsLQoUNx6tQpbNu2DePHj8eDDz7Y7mNIpVKsX78eY8eORZ8+fTB9+nR4eHjg8uXLuHjxIvbv39/ka1977TX8+OOPGDlyJObPnw9HR0ds27YNqamp+N///scXUo8YMQLu7u4YNGgQ3NzckJycjC+++AKjR4+GjY0NAODDDz/E33//jaFDh2LWrFkICAhAVlYWfv31V/zzzz8NCtdbY8yYMfjuu+9gZ2eHwMBAxMbG4sCBA3ByctLYrk+fPpDJZPj444+hVCqhUCj4ebyWLVuGd955B5GRkXjkkUeQkpKCr776Cvfddx+mTJnS5tgIMSSUOBFCmtSjRw/89ttvePPNN/Hyyy/D3d0dc+bMgYuLS4PRcLr0zTffwM/PD1u3bsXOnTvh7u6OZcuWabU+KCIiAocOHcI777yDzz77DGq1Gl26dMHMmTObfZ2bmxtOnDiBV199FevWrUNlZSV69eqFP//8U6MV5oUXXsCOHTvw+eefo7S0FJ06dcL8+fPx5ptv8tt07NgRcXFxeOutt7Bjxw4UFxejY8eOGDlyJKysrNr1/tasWQOZTIYdO3agsrISgwYNwoEDBxqMgnR3d8eGDRuwcuVKzJgxAyqVCocOHYKrqyvefvttuLi44IsvvsCiRYvg6OiIWbNm4cMPP9QYMUmIMZMwoSsmCSGEEEIMBNU4EUIIIYS0ECVOhBBCCCEtRIkTIYQQQkgLUeJECCGEENJClDgRQgghhLQQJU6EEEIIIS1E8zhpgVqtRmZmJmxsbNq9gjkhhBBC9IsxhpKSEnh6evKT1jaFEictyMzMbLDCOyGEEEIMy82bN9GpU6dmt6HESQu45RJu3rwJW1tbgaMhhBBCSGsUFxejc+fO/P28OZQ4aQHXPWdra0uJEyGEEGKgWlJuQ8XhhBBCCCEtRIkTIYQQQkgLUeJECCGEENJClDgRQgghhLSQQSVOR48exdixY+Hp6QmJRIJdu3bd8zWHDx9Gv379oFAo0LVrV2zdurXBNl9++SV8fHxgYWGB0NBQnDp1SvvBE0IIIcTgGVTiVFZWht69e+PLL79s0fapqakYPXo0HnzwQSQmJmLhwoV4/vnnsX//fn6bn3/+GYsXL8aKFSuQkJCA3r17IyIiArm5ubp6G4QQQggxUBLGGBM6iLaQSCTYuXMnxo8f3+Q2r776Kv766y8kJSXxz02cOBFFRUWIiooCAISGhuK+++7DF198AaBuFvDOnTvjpZdewmuvvdaiWIqLi2FnZwelUqm16QiikrKw+sBVpOaXwdfZGgvDuyEyyEMr+yaEEELIf1pzHzeoFqfWio2NRXh4uMZzERERiI2NBQBUV1cjPj5eYxupVIrw8HB+GyFEJWVh9vcJSMkuQVWtGinZJZj9fQKikrIEi4kYjsLCQqSnp+PPxJuIXH0UPd7ch8jVR+n8Ic2qqalBRkYG8vPzhQ6FGJg7d+4gPT0dNTU1QoeiF0adOGVnZ8PNzU3jOTc3NxQXF6OiogL5+flQqVSNbpOdnd3kfquqqlBcXKzx0KbVB65CAoBrCmT//u//Rado9TjEeKjVamzevBm9evWCo6MjAkZMwks/ncflrGJKvkmzrly5gsmTJ8Pe3h7e3t5wcXFB165d8emnn6Kqqkro8IhI1dbWYt26dfD394ezszN8fHxgY2ODJ554AhcuXBA6PJ0y6sRJV1auXAk7Ozv+oe116lLzy9Cw/1SClMwipKRQ8kQ05eTk4OGHH8bzzz/PX7AcBk8GU6uBf2fBZaj7v2tirgoYKRGbjRs3ok+fPvjhhx9QXl4Oc3NzSCQSXL9+HUuXLsWAAQOQnp4udJhEZDIyMjBkyBDMnz+fvyfJ5XJUVVXht99+Q9++ffHpp5/CQCuB7smoEyd3d3fk5ORoPJeTkwNbW1tYWlrC2dkZMpms0W3c3d2b3O+yZcugVCr5x82bN7Uat6+zNe6e9J0xNarzbyIsLAzx8fFaPR4xXJmZmRg2bBgOHjwIKysrfPLJJ7hz5w46ePhBctcK34wBN/LKBIqUiM1HH32EF154ARUVFQgPD8epU6dQUVGB4uJifPPNN3B1dcX58+cx8PHZePDjaOryJQCAtLQ0PPDAA4iNjYWtrS2++OILFBUVobKyEgkJCRg/fjxUKhWWLl2KN9980yiTJ6NOnMLCwhATE6PxXHR0NMLCwgAA5ubmCAkJ0dhGrVYjJiaG36YxCoWCX5dOF+vTLQzvxrcQ4N//SiRSuOXFo7CwEGPGjEFGRoZWj0kMT3l5OUaOHInLly+jc+fOSEhIwMsvvwxHR8fGk2+1GtbqUkFiJeLyzTffYNmyZQCAFStWYP/+/bjvvvsglUrRoUMHzJgxA2fOnEHAiElQDJ+H1IJK6vIlKCwsRHh4ODIyMtC9e3ecO3cOc+fOhZ2dHaRSKfr27Yvff/8dn332GQDgww8/xP/93/8JHLX2GVTiVFpaisTERCQmJgKom24gMTGRTyKWLVuGqVOn8tvPnj0bN27cwCuvvILLly/jq6++wi+//IJFixbx2yxevBibNm3Ctm3bkJycjDlz5qCsrAzTp0/X63urLzLIAxum9IO/uw0UZlL4u9tgw5QQHPlhLYKDg5GdnY1HH33UZArxSEOMMbzwwgs4f/483NzccOTIEfTo0YP//d3JN8AgkUpx+bf/w759+4QImYhEfHw85s6dCwBYvnw53n77bUilDW8FnTt3hufDzwNMDUjqfk9dvqaLMYZnn30W169fh4+PDw4ePAgfH58G20kkEixevBiffPIJAOCVV17B8ePH9RytjjEDcujQIYa6f7saj2nTpjHGGJs2bRobOnRog9f06dOHmZubMz8/P/btt9822O+6deuYl5cXMzc3ZwMGDGAnT55sVVxKpZIBYEqlso3vrOUyMjKYg4MDA8CWL1+u8+MRcfr5558ZACaTydiRI0ca3WbfhUwWufoI6/7GXha5+gh7bMG7DABzd3dn+fn5eo6YiEFlZSXr0aMHA8AeeeQRplKpmt2++xt7mferexo8ur+xV08RE7HYsGEDA8DMzc3ZmTNn7rm9Wq1mkyZNYgCYl5cXKykp0UOUbdea+7jBzuMkJrqYx6k5P/30EyZNmgSZTIbExEQEBQXp/JhEPAoLCxEQEICcnBysWLECb7/9doteV1FRgZCQECQnJ+PZZ5/Ft99+q9tAiei8/fbbeOedd+Du7o5Lly7BwcGh2e0jVx9FSnaJxmAVCQB/DxvsWzBEp7ES8cjOzoa/vz+USiU+//xzjV6b5pSWliI4OBg55h7oNn4BKuW2op2XkOZxMnITJ07kC/AWLVpklMV3pGkrVqxATk4OAgIC+DqVlrC0tMSWLVsAAFu3bsXp06d1FSIRoRs3buDDDz8EAKxZs+aeSRPQsMuXqdVgABYM7667QInovPLKK1AqlQgJCcH8+fNb/LoOHTpg5jtfwnXCGyhiVkZTJ0eJk4H67LPPYG5ujgMHDmDv3r1Ch0P05Pr169iwYQMAYN26dVAoFK16/cCBA/HMM88AACXdJmbFihWoqalBeHg4nnjiiRa9pn69pVwK1OSnIff3D2BdSDVOpiAqKQvDPvobR1wnwGP6Ojz75v9BJpO1ah9HCzoAjPGjfI2hTo4SJwPl5+eHhQsXAqgr8KQboGlYvnw5ampqEBERgeHDh7dpHytXroSFhQWOHz+O6OhoLUdIxOj8+fPYsWMHAODjjz+GRHL3mMumRQZ5YN+CIbj64Wg8Yn4RFVdjW9w9TAwXt4JFWmE1JGbmMHfxwacni1vdUpSaX1Z/lAoAw58ahRInA7Z06VJYW1sjISGBWp1MwI0bN/DTTz8BAN/l0hYdO3bECy+8AAB45513KOk2AStXrgRjDE8++ST69evX5v28/vrrkMvlOHjwII4eParFCInYcCtY1J8Xpy0tRY1NjSKRAH4u1toIUxCUOBkwZ2dnfljxe++9J3A0RNc+//xzqNVqREZGtuvmB9TVLCgUCpw4cYJugEYuLS0Nv/76K4C6xKc9vLy8MGPGDAB1yRgxXo2tYNGWliK+To7bh1oNxgy7To4SJwO3ZMkSmJubIy4uDqdOnRI6HKIj+fn5fGH30qVL270/T09Pfq6ytWvXtnt/RLxWr14NlUqFhx9+GL179273/pYuXQqJRIKoqChaAsqIdbIzr1u2qZ62tBTxdXIeNpCoa1GTl4ZexScRGdT06hxiR4mTgXN1dcXEiRMBAF988YXA0RBdWb9+PSoqKtCvXz88+OCDWtnnSy+9BADYtWsXrUdmpAoLC/HNN98AAF5++WWt7NPPzw9jx44FQNccY+aae6auoJvVJU8SCdrcUsTVye0Y74KsrfOxf/MqZGdnaztkvaHEyQjMmzcPAPDzzz8jNzdX4GiItqlUKnz99dcA6loYW1PY25zAwEAMHz4carUa69ev18o+ibhs374dZWVlCA4OxsMPP6y1/XJD0rdu3QqlUqm1/RJxqKiowL5NK5G78wN07CDVWMGiPS1F999/P8LCwlBdXY1NmzZpMWL9osTJCNx3330IDQ1FdXU1Nm7cKHQ4RMuioqJw+/ZtODk54bHHHtPqvrkb4KZNm1BZWanVfRPhRCVlIXL1UfzfLW94TF+Hh6Yu0lrCDQAPPfQQAgMDUVpaim3btmltv0Qc/ve//0GpVMKtOgvH3hiJlPdHYt+CIVrpXnvxxRcBAFu2bIH6rq5AQ0GJk5HgisS3bNlCo6SMDNfVMnXq1FbP23Qvo0ePhpeXFwoKCrB7926t7psIgxtGnpJdAsjkkLt4Y1e+q1YnHJRIJJgzZw6AulYnYlw2b94MAJg+fXqj6xi2x2OPPQY7OzukpaXh4MGDWt23vlDiZCQee+wxdOjQAampqfjnn3+EDodoSVZWFv78808AwMyZM7W+f5lMxk+ISS0HxoEbRs59fZJIpDqZcHDSpEmQy+U4e/Yszp8/r9V9E+Fcu3YNhw8fhkQi0cli95aWlnj66acB/JegGRpKnIyElZUVPxsw3QCNx3fffQeVSoVBgwYhICBAJ8eYOnUqAGD//v0GXbBJ6mhrGPm9ODk58UXidM0xHtzo3YiICHTu3Fknx3j++ecBAL///jsKCgp0cgxdosTJiEybNg0A8Msvv6CiokLgaIg2/PDDDwD++9vqQvfu3REWFgaVSsXPLk0Ml6+zNXBX6qSrCQefffZZAMCOHTtQU1Oj9f0T/WKM8dec5557TmfH6devH3r37o3q6mr89ttvOjuOrlDiZEQeeOAB+Pj4oKSkBLt27RI6HNJOycnJOHfuHMzMzLReFH43LjHbvn27To9DdG9heDcAEn4OnvYMI7+XyMhIuLi4ICcnh5bvMQJxcXFIT09Hhw4dMGbMGJ0ea9KkSQDqRoMbGkqcjIhUKsWUKVMAGObJSDRxy6tERETA0dFRp8d68sknYWZmhvPnz9OkhgZuYCdLFP75MWry0iCXQivDyJsil8vx1FNPAQA/OzkxXNw1Z9y4cbC0tNTpsbjz5vDhwwZXIkCJk5Hh6pyioqJQUlIicDSkLbih5NvK+8Jj+jr0GjVV58d0cHBAeHg4ALoBGrpdu3ah+NIxOJ3ZiKsfjtbaMPKmPP744/xxq6urdXYcolsqlQq//PILAPCTKuuSj48PQkNDoVarDa67jhInIxMcHIxu3bqhqqoKf/31l9DhkFZqMJTc2Rs/ZFhrdSh5U7ik29AuYkQT12qgj5sfAAwePBhubm4oKioy2OHlBPjnn3+QlZUFe3t7jBgxQi/H5M5R7pw1FJQ4GRmJRMJ/A6QboOFpMJRcqpuh5I0ZN24cZDIZzp07h6tXdX88on1FRUWIiYkBUNf9qg8ymYyvwaPWSsPF3S8mTJgAc3NzvRzziSeegEQiwfHjx5GZmamXY2qDwSVOX375JXx8fGBhYYHQ0NBmF7YdNmwYJBJJg8fo0aP5bZ599tkGv4+MjNTHW9EZLnHau3cvysq0OwSZ6Ja+hpI3xsnJCQ899BAASroN1b59+1BbW4vAwEB069ZNb8et311Ho+sMD2OMnwD30Ucf1dtxO3bsiNDQUADAnj179Hbc9jKoxOnnn3/G4sWLsWLFCiQkJKB3796IiIhocn2233//HVlZWfwjKSkJMpmM75LgREZGamz3448/6uPt6Ezfvn3h5+eHiooKREVFCR0OaQVfZ2vcvTCGroaSN4a7Ae7cuVMvxyPaxd38xo0bp9fjDhkyBC4uLigoKMDx48f1emzSfufPn0dGRgYsLS0xfPhwvR77kUceAQCDWrnAoBKnzz//HDNnzsT06dMRGBiIDRs2wMrKip+w626Ojo5wd3fnH9HR0RoTRXIUCoXGdg4ODvp4OzojkUj4k5HqnAzLwvBuYIBehpI3hpvQ8PTp08jJydHLMYl2VFdXY+/evQD+uxnpi0wmw6hRowAYVssBqcMlLSNGjND5aLq7cefqgQMHDKaHxGASp+rqasTHx/Mjf4C64ffh4eGIjY1t0T42b96MiRMnwtpa89v74cOH4erqih49emDOnDm4c+eOVmMXAjcHx969ew12IUVTFBnkAbdru1GTlwYZ1DodSt4YDw8PhISEAAB/EyaG4ejRoyguLoarqysGDBig9+Nz1xxKnAwPlzjpO+EGgMDAQPj5+aGqqspg5gIzmMQpPz8fKpUKbm5uGs+7ubm1aA6IU6dOISkpiZ/qnRMZGYnt27cjJiYGH3/8MY4cOYKRI0dCpVI1ua+qqioUFxdrPMTmgQcegI2NDXJycpCQkCB0OKSFCgsLEb9rM7K2zsffMwN1PpS8MdwNkForDQt38xs7dqzWF2ZtiREjRsDMzAwpKSk0uMCA3L59G2fOnGlQ/6svEomEb+k2lO46g0mc2mvz5s0IDg5u8E1s4sSJeOSRRxAcHIzx48djz549OH36NA4fPtzkvlauXAk7Ozv+oav1fNrD3NwcDz/8MAC6ARqSffv2QaVSoWfPnujSpYsgMXAXz7///pvm5TEQjDH88ccfAPRf38SxtbXF0KFDAdA1x5BwLYQDBw5s0DChL1xL1549e5pttBALg0mcnJ2dIZPJGtRd5OTkwN29+W/kZWVl+OmnnzBjxox7HsfPzw/Ozs64du1ak9ssW7YMSqWSf9y8ebNlb0LPuBsgNZ0bDu6Gw30DE0JISAjc3NxQUlKCY8eOCRYHabmkpCTBinvro+46wyNkNx3ngQcegJ2dHfLy8hAXFydYHC1lMImTubk5QkJC+DlKAECtViMmJgZhYWHNvvbXX39FVVUVvxxJc27duoU7d+7Aw8OjyW0UCgVsbW01HmLEFWueOXPG4Ka0N0VqtRp///03AGDkyJGCxSGVSinpNjD79+8HADz44IOwsrISLA4ucTpy5IgoSxiIpqqqKhw6dAjAf/cLIcjlcn4aIO5cFjODSZwAYPHixdi0aRO2bduG5ORkzJkzB2VlZZg+fToAYOrUqVi2bFmD123evBnjx4+Hk5OTxvOlpaVYunQpTp48ibS0NMTExGDcuHHo2rUrIiIi9PKedMnd3R39+/cHUNcFRMQtMTER+fn56NChwz2/DOgaJU6GhUu49TXjc1O6du2KHj16oLa2lo+JiNfx48dRUVEBd3d3BAcHCxoLd+4awnljUInTU089hU8//RTLly9Hnz59kJiYiKioKL5fNiMjA1lZmktTpKSk4J9//mm0m04mk+H8+fN45JFH0L17d8yYMQMhISE4duwYFAqFXt6TrnE3QEqcxI/7pvXQQw9BLpcLGsvDDz8MMzMzXLt2DampqYLGQppXUVGBo0ePAhA+cQLAtxwYyggpU1Y/4ZZI7p5BTr+4mtxTp06hsLBQ0FjuxaASJwCYN28e0tPTUVVVhbi4OH7WUaBuWoGtW7dqbN+jRw8wxvg/Sn2WlpbYv38/cnNzUV1djbS0NGzcuFGwAjldsA8aCo/p6xDnNQmRq4/qZc0z0jbcRUwMrZ02NjYYOHAggLr5VYh4HTt2DFVVVejUqRP8/f2FDoe/1tJ5I35iaakEgM6dOyMgIABqtVr0ax4aXOJEWi4qKQurz5RD7uINiZk5UrJLMPv7BEqeRKi0tJSfcVkMFzEA/JxpdAMUN66lUgytBkDdLOJmZma4ceMGbty4IXQ4pAm5ubk4e/YsAGjMjygkQ+muo8TJiHELxkokdX9mBuhtwVjSOocPH0ZNTQ18fX0Fm4bgblzLQUxMDE2iKmJiaqkEqLXSUHB/mz59+oiml4VLnPbv3w/G7l61UzwocTJiQi4YS1qn/s1PDK0GAHDffffBxsYGd+7cQWJiotDhkEZkZmYiKSkJEolE0GkI7kbddeInpm46ztChQyGXy5Gent7slEBCo8TJiDW6YCz0t2AsaTmukLaxWjyhyOVyDBs2DADdAMWKO2/69+/fYNSwkLiun5iYGIOY0NDUMMZEmThZW1tj8ODBAMQ9LQElTkaMWzCWa8BgajUY9LdgLGmZ7OxsXL58GRKJBA8++KDQ4WigOidx4+bgEVNrEwAMGDAANjY2KCgooNZKEUpJSUFWVhYsLCwwaNAgocPRwH15FHOBOCVORiwyyAMbpvSDv7sNJEyFmrw0PCBJ1vvaZ6R5R44cAVBXa+Dg4CBwNJq4i9ixY8dQWVkpcDTkbtzSUGJLuM3MzPiYaFoC8eHOm7CwMFhYWAgbzF248+bIkSOira2kxMnIRQZ5YN+CIXinZxGyts5HSswvQodE7sJdxLhuMTHx9/eHp6cnKisrERsbK3Q4pJ60tDSkp6fDzMwM999/v9DhNMC1Voq55cBUcV/WxHjNCQkJgbW1NQoKCnDx4kWhw2kUJU4m4qGHHgIAJCQkoKSkROBoSH1iTpwkEgkfF3exJeLA/T369++PDh06CBxNQ9yCvydOnEBNTY3A0RAOY0zU1xy5XM53H3Jxig0lTiaiU6dO8PX1hUqlwokTJ4QOh/yrfn3TAw88IHQ4jeJugNzs1EQcxHzzA4CgoCA4ODigrKyMny+ICO/KlSvIzs6GQqHAgAEDhA6nUdw5TYkTEdyQIUMA0A1QTLhWg969e4uuvokzZMgQWHYPQ4rvY+j+5j6agV4kxJ44SaVS/ssAtVaKB/e3EGN9E6f+lzUx1jlR4mRCKHESH7Hf/AAgtcYOrhPegJmTF6pr1TQDvQikp6cjLS0NMplMdKOi6qPWSvExhGtO//79YWVlhfz8fFy6dEnocBqgxMmEcInTqVOnUFFRIXA0BDCMi9iamKsAY5BIaQZ6sRB7fROHu+YcO3aM5nMSgfr1TVxSK0bm5ub8gAcxdtdR4mRCunTpAk9PT1RXV+PUqVNCh2PyDKG+CaibgZ6fDOxfNAO9sAwh4QbqptiwsbGBUqnEhQsXhA7H5F27dg1ZWVlQKBT8sjhiJeZBKZQ4mRCJRELddSJSv77J0dFR4Gia1ugM9BKagV5IhpI4mZmZ8V2JYrwBmhruvBk4cKBo65s49RMnsa1bR4mTieESJ7qICY/7G4i5yRz4bwZ69m+RpgR1LU40A70wMjIykJqaKvr6Jg7VOYmHoSTcQN1amZaWlsjLyxNdnRMlTiaGS5xOnDiB6upqgaMxbcePHwcAUXfTAf/NQG9ZXQBWWw0nWSU2TAmhGegFwp03ffv2hY2NjcDR3Fv9Vm6xtRyYmn/++QfAf38TMTM3N0dYWBiA/+IWC0qcTExAQACcnJxQUVGBhIQEocMxWcXFxXzNhxhnfb5bZJAHnu+Uh4zPHkXHpO2UNAmIm4fNEFqbgLoCdktLS+Tn5yM5OVnocEzWrVu3kJGRAZlMJtr5m+7GnePclwWxoMTJxNDcKuJw8uRJMMbg6+sLDw8PocNpkfojpMQ4t4qp4G4ihpBwA5otB9RdJxxuyaTevXuLeiRmfVziJLZJmw0ucfryyy/h4+MDCwsLhIaGNjs6bOvWrZBIJBqPuwviGGNYvnw5PDw8YGlpifDwcFy9atzDrLnESWwnoynhPntDufkBdV1DlpaWKCwsREpKitDhmKTS0lKcO3cOgGGdO9wNkNY7FI6hJdxAXRG7RCLB9evXkZOTI3Q4PINKnH7++WcsXrwYK1asQEJCAnr37o2IiAjk5uY2+RpbW1tkZWXxj/T0dI3fr1q1CmvXrsWGDRsQFxcHa2trREREGPVK8Nw/nNjYWKo5EAh3ETOU7hagbg2p++67DwDdAIVy6tQpqNVqeHl5oVOnTkKH02JcixOdN8IxxC9rdnZ2CAoKAiCuL/oGlTh9/vnnmDlzJqZPn47AwEBs2LABVlZW2LJlS5OvkUgkcHd35x9ubm787xhjWL16Nd58802MGzcOvXr1wvbt25GZmYldu3bp4R0Jo2/fvjA3N0deXh6uX78udDgmR6VS4eTJkwAMK3EC/rvoiukiZkoMsdUAqGs5sOwehtLB89H9jb20bI+elZeX8+sFGuo1R0x1TgaTOFVXVyM+Ph7h4eH8c1KpFOHh4c1+iyktLYW3tzc6d+6McePG4eLFi/zvUlNTkZ2drbFPOzs7hIaGGvU3I4VCgZCQEAD0DVAIFy5cQGlpKWxtbdGzZ0+hw2kVajkQlqEVhnPiblfCdcIbkDt7o1rFaNkePTt9+jRqa2vRsWNHdO7cWehwWkWMBeIGkzjl5+dDpVJptBgBgJubG7Kzsxt9TY8ePbBlyxb88ccf+P7776FWq3H//ffj1q1bAMC/rjX7BICqqioUFxdrPAwN3QCFw938Bg4cCJlMJnA0rcOdN5cuXUJhYaHA0ZgWtVrN/3s1tBan1Qdo2R4h1e+mk0juns5W3LjEKT4+XjQlNAaTOLVFWFgYpk6dij59+mDo0KH4/fff4eLigq+//rpd+125ciXs7Oz4h6Fl8AB1uQjJULtbAMDFxQVdu3YFAMTFxQkcjWm5dOkSlEolrK2t0atXL6HDaRVatkdYhljfxPH19YWbmxtqampw5swZocMBYECJk7OzM2QyWYPK+pycHLi7t2xOGblcjr59++LatWsAwL+utftctmwZlEol/7h582Zr3ooocC0HFy5cQElJicDRmBZD7W7hUGulMLjzJjQ0FGZmZgJH0zq0bI9w1Gq1QV9zJBKJ6KYlMJjEydzcHCEhIYiJieGfU6vViImJ4S/k96JSqXDhwgV+3hxfX1+4u7tr7LO4uBhxcXHN7lOhUMDW1lbjYWg8PT3h5eUFtVqN06dPCx2OycjMzERaWhqkUilCQ0OFDqdNqLVSGIbcUknL9gjnypUrKCgogKWlJfr06SN0OG0itjong0mcAGDx4sXYtGkTtm3bhuTkZMyZMwdlZWWYPn06AGDq1KlYtmwZv/27776Lv//+Gzdu3EBCQgKmTJmC9PR0PP/88wDqMtmFCxfi/fffx+7du3HhwgVMnToVnp6eGD9+vBBvUa/oBqh/3Gfdq1cvg1guozHcl4q4uDioVCqBozEdhtxqwC3bY1F1B6y2Gs5mVbRsj55w5819990HuVwucDRtU/9eJYYpdAyqvfepp55CXl4eli9fjuzsbPTp0wdRUVF8cXdGRgak0v9ywcLCQsycORPZ2dlwcHBASEgITpw4gcDAQH6bV155BWVlZZg1axaKioowePBgREVFiX7laG0ICwvDTz/9RF0uemTIrQacoKAgdOjQASUlJbh48aLB1dsYopycHFy7dg0SiQQDBw4UOpw2iQzywBTnm1i+fDoGTZqEyKBHhQ7JJBjDNadfv35QKBTIz8/H9evX+TpLwTDSbkqlkgFgSqVS6FBa5dSpUwwAc3R0ZGq1WuhwTEJoaCgDwL7//nuhQ2mX4cOHMwBsw4YNQodiEnbu3MkAsJ49ewodSrtER0czAMzb21voUEyGv78/A8B2794tdCjtEhYWxgCw7777Tif7b8193KC66oh29e7dGxYWFigoKMCVK1eEDsfoVVdX85PQGWqrAaf+7PNE97ilpVpazylWAwYMgFQqRXp6OjIzM4UOx+gVFRXh8uXLAAz/3OGumWIYzUuJkwkzNzfnl9CgOifdO3/+PKqrq+Ho6Ag/Pz+hw2kX7iJM541+cImToaxq3xRbW1t+CQ1KunWPG77v5+cHZ2dngaNpH24wDbfqgpAocTJxNLRcf7hvSgMGDDC4Sejuxn37u3r1KvLz8wWOxrjVH/lq6IkTQNccfap/zTF03DUnMTERFRUVgsZCiZOJ4y5iYsjijZ2xtBoAgIODA3r06AEANJ2FjqWkpKC4uBhWVlYGt0RPY7iWAzpvdM+YrjleXl5wd3dHbW0tX/IgFEqcTBz3D+rixYsoK6NZfHWJu4gZ6vxNd+POHe59Ed3gPt+QkBCDm/iyMdx5Ex8fT9NZ6BBjzKhanCQSiWi66yhxMnGenp7w9PSEWq0WPIs3Zkqlki/S5OrKDB0lTvphTK0GAODv748OHTqgrKwMycnJQodjtG7duoWcnBzIZDL069dP6HC0Ys6cOdi6dSsef/xxQeOgxInQDVAPuG4JX19fuLi4CByNdnAJ4OnTp0UxKZ2xMqZWAwCQyWQICQkBQNccXeI+2169esHS0lLgaLQjIiIC06ZNg5eXl6BxUOJENG6ARDeMrZsOqJvOQi6XIy8vD+np6UKHY5QqKytx7tw5AMaTOAH0ZU0fjK2lUkwocSJ0EdMDY7yIWVhY8LOGU9KtG4mJiaitrYWLiwu8vb2FDkdruH8HdN7ojrG1VIoJJU4E/fv3BwDcuHEDd+7cETga42NsRZr1UdKtW/VbKg19Cov6uFbu8+fPCz603BipVCp+Didju+aIASVOBPb29ujevW6VcvoGqH23bt1CdnY2ZDIZ+vbtK3Q4WkXdvLplrAm3l5cXXF1dUVtbi8TERKHDMSpRSVkY/kkMnGZ/h44zvkSG2kHokIwOJU4EAN0Adal+kaaVlZXA0WgXd0M/c+YMDS3XAWPs4gXqhpZTd532RSVlYfb3CUgrqobEzBxmTp3x4g+JiErKEjo0o0KJEwFAXS66ZKw3P6BuaLm1tTXKysr46RaIdhQUFODatWsAjGcKi/romqN9qw9cRV2H7r/duhIpJBJgTcxVAaMyPpQ4EQA0tFyXjDlxkslkfI0c3QC1i2uJ6dq1KxwdHQWORvuolVv7UvPLcPfVmzHgRh5NbqxNlDgRAECfPn1gZmaGnJwc3Lx5U+hwjEb9Ik1jmoqgPmo50A2uvslYzxsucbpy5QoKCwsFjsY4+Dpb4+4hBBIJ4OdiLUg8xooSJwIAsLS0RHBwMAD6BqhNycnJKC0tRYcOHeDv7y90ODpBLQe6YcwtlQDg5OSELl26AAD/5YK0z8LwbmAAmFoNoC5pYgxYMLy7sIEZGUqcCI9aDrSPSyZCQkIgk8kEjkY3uPPm3LlzqKysFDga48AYM/rECaCkW9sigzww2i4TNXlpkKhr4e9ugw1TQhAZ5C50aEaFEifCo4uY9nHfpLk6IGPk5eUFFxcX1NbW8rNck/a5efMm8vLyIJPJ0Lt3b6HD0Rn6sqZ9hRcOIWvrfMywvYB9C4ZQ0qQDBpc4ffnll/Dx8YGFhQVCQ0Ob/Qe3adMmPPDAA3BwcICDgwPCw8MbbP/ss89CIpFoPCIjI3X9NkSp/tBy9b9NvaR9EhISAIBfm8sY1R9aTjdA7YiPjwcA9OzZ02jWGWsMTUmgfdy5Y8xf1oRmUInTzz//jMWLF2PFihVISEhA7969ERERgdzc3Ea3P3z4MCZNmoRDhw4hNjYWnTt3xogRI3D79m2N7SIjI5GVlcU/fvzxR328HdEJCAiAlZUVSkpKkJKSInQ4Bq9+C4wxJ04AtVZqG3fzM/bzpm/fvpDJZMjMzGxwXSatV1xcjCtXrgAA+vXrJ3A0xsugEqfPP/8cM2fOxPTp0xEYGIgNGzbAysoKW7ZsaXT7HTt24MUXX0SfPn3g7++Pb775Bmq1GjExMRrbKRQKuLu78w8HB9OcadXMzIxWLdei5ORkVFRUwMbGBl27dhU6HJ2ilgPtMoWWSgCwsrJCz549AVCBuDZws7B36tQJrq6uwgZjxAwmcaqurkZ8fDzCw8P556RSKcLDwxEbG9uifZSXl6OmpqbBnCiHDx+Gq6srevTogTlz5pj0em3chZr7xkvajvsM+/XrB6nUYP6ptQl33qSkpKCkpETgaAwbY8xkWpwAuuZokymdN0IymKt5fn4+VCoV3NzcNJ53c3NDdnZ2i/bx6quvwtPTUyP5ioyMxPbt2xETE4OPP/4YR44cwciRI5tdPqKqqgrFxcUaD2NBFzHtMaWLmKurKzp16gTGGK091k63b99Gbm6u0ReGc+iaoz2mdM0RkpnQAejLRx99hJ9++gmHDx+GhYUF//zEiRP5/x8cHIxevXqhS5cuOHz4MIYPH97ovlauXIl33nlH5zELgfsHl5iYCJVKZbRD6PXB1C5iISEhuHXrFuLj4/HAAw8IHY5BikrKwru/J8Jrye+Qld/BketFiAwy3uJwQDNxYoxBIrl7CkfSUqZ2zRGKwbQ4OTs7QyaTIScnR+P5nJwcuLs3P9zy008/xUcffYS///4bvXr1anZbPz8/ODs782tENWbZsmVQKpX8w5hm2u7evTusra1RXl5OBeLtUH/Vd1O5iFHLQftwC7RmlgMSM3Oobdwx+/sEo1+gtXfv3vy1PTMzU+hwDFb9QT2mcs0RisEkTubm5ggJCdEo7OYKvcPCwpp83apVq/Dee+8hKiqqRcMzb926hTt37sDDw6PJbRQKBWxtbTUexkImk6Fv374A6AbYHpcvX0ZFRQU6dOiAbt26CR2OXlDi1D4NF2iVmMQCrZaWlggMDARA5057JCYmgjGGjh07NihpIdplMIkTACxevBibNm3Ctm3bkJycjDlz5qCsrAzTp08HAEydOhXLli3jt//444/x1ltvYcuWLfDx8UF2djays7NRWloKACgtLcXSpUtx8uRJpKWlISYmBuPGjUPXrl0REREhyHsUA7oBth/32fXt29foC8M53Hlz+fJl/t8YaTlTXqCVrjntx43EpGkIdM+gapyeeuop5OXlYfny5cjOzkafPn0QFRXFZ9cZGRkaN6n169ejuroajz/+uMZ+VqxYgbfffhsymQznz5/Htm3bUFRUBE9PT4wYMQLvvfceFAqFXt+bmNBFrP1MZTh5fW5ubujYsSNu376NxMREDB48WOiQDIqvszVSsks0kidTWaA1JCQEW7dubfSawxhDbW1tswN2CHDjxg14e3tjyJAhtPRRI2QyGczMzLRSQ2dQiRMAzJs3D/PmzWv0d4cPH9b4OS0trdl9WVpaYv/+/VqKzHhwN/uzZ89SgXgbmWqRZkhICG7fvo34+HhKnFppYXg3zP4+AUythkQqNakFWpv6slZdXY2srCyUl5cLEZZBeeSRRzBy5Ei4uroiNTVV6HBEycrKCh4eHjA3N2/XfgwucSK616NHD1hbW6OsrAxXrlxBQECA0CEZFJVKhbNnzwIwzcRp9+7d1FrZBpFBHnhQfg37b0mhcPWGv4c9FgzvbhJrjfXu3RtSqRTZ2dnIzMyEp6cn1Go1UlNTIZPJ4OnpCXNzcxpx1wSVSoWysrou3a5du7Y7MTA2jDFUV1cjLy8Pqamp6NatW7tKKChxIg3IZDL06dMHx48fR3x8PCVOrZSSkoLy8nJYW1uje3fjby2oj7p52yc/8QCy9uzBmjVrMH/+fKHD0RsrKysEBATg4sWLiI+Ph6enJ6qrq6FWq9G5c2dYWVkJHaKocTWFcrncqAYraZOlpSXkcjnS09NRXV2tMS1Ra5lG1SppNa7AkG6ArVe/MNzUujnrF4hz34BJy5lqFy/QdNJtKoMr2oP7t0YJZvO0dS7RGUkaRS0HbWfKNz93d3e+m4VmEG8dbpFxiURiEjOG342uOW3H1YBZWxv/QAIxoMSJNKp+gbharRY4GsNSf406U0StlW3DfV7+/v7o0KGDwNHoHyVObcclTtTipB+UOJFG+fv7w9LSEqWlpbhy5YrQ4RgMUy4M59ANsG1MuaUSAPr06QOpVMq3vJGWUalUqKioAECJk75Q4kQaZWZmhj59+gD4b04icm9XrlxBWVkZrKys4O/vL3Q4gqDEqW1Mce6v+qytrfl/M3TutByXNMnlcsjlcoGjubc7d+7A1dX1ntMFtcbEiRPx2WefaW1/90KJE2kS3QBbJyopC9N/vgqvJb/DY/o6RCfnCh2SILjzJjk5mQrEW8HUW5wAuua0Rf1uOm66hmHDhmHhwoUCRtW0Dz74AOPGjYOPj0+b97Fo0SI8+uij/M9vvvkmPvjgAyiVSi1EeG+UOJEm0UWs5bgFWrMrpJCYmaPW2tUkFmhtjKenJ9zd3aFWq3Hu3DmhwzEIOTk5uH37NiQSCb9WpCmia07rGdKIuvLycmzevBkzZsxo135OnTqlsfZsUFAQunTpgu+//769IbYIJU6kSdxFLCEhgQrE74FfoFViWgu0NoVugK3DfU49evQwycJwjrGcN2q1GitXroSvry8sLS3Ru3dv/PbbbwCAvLw8uLu748MPP+S3P3HiBMzNzflF7KOiojB48GDY29vDyckJY8aMwfXr1xscY9WqVRg6dCjuv/9+hIaG4oMPPsCzzz6LI0eOYM2aNZBIJJBIJK3qFuP227VrVygUCnh5eeGDDz4AAFRVVWH+/PlwdXWFhYUFBg8ejNOnT2u8/rfffkNwcDAsLS3h5OSE8PBwPrnbu3cvFAoFBg4cqPGaOXPmNLnSQKdOnfDRRx8BqJtJXi6X48SJE3jjjTcgkUj4fY0dOxY//fRTi99ne9AEmKRJAQEBsLS0RElJCa5du2Zykzm2hikv0NqYkJAQ/PXXXwZ/A9QXUx+JyenTpw8kEgkyMzORl5en8TvGmGBLr9TvBmuJlStX4vvvv8eGDRvQrVs3HD16FFOmTIGLiwuGDh2KLVu2YPz48RgxYgR69OiBZ555BvPmzcPw4cMB1LUiLV68GL169UJpaSmWL1+OCRMmIDExkZ+LaNmyZdi0aRPmz5+PPn36wM7ODtevX8e8efNw5coVBAUF4d133wUAuLi4tDh2br//93//h8GDByMrKwuXL18GALzyyiv43//+h23btsHb2xurVq1CREQErl27BkdHR2RlZWHSpElYtWoVJkyYgJKSEhw7dgyM1V0djx071qAr+uLFi9i4cSOOHTvWaDwBAQH81CZmZmY4fvw4QkNDkZiYCDc3N34iywEDBuCDDz5AVVWV7teaZaTdlEolA8CUSqXQoWjdwIEDGQD2ww8/CB2KqEX83xHm8+oe5l3v4fPaHha5+ojQoQnijz/+YABYUFCQ0KEYhHHjxjEA7LPPPhM6FMEFBAQwAGzfvn3s0qVLrKKigjHGWGlpKQMgyKO0tLTF8VdWVjIrKyt24sQJjednzJjBJk2axP/84osvsu7du7Onn36aBQcHs8rKyib3mZeXxwCwCxcuMMYYKy4uZgqFgq1bt46dPn2anT17lqnVan77oUOHsgULFrQ4Zg63302bNjX4XWlpKZPL5WzHjh38c9XV1czT05OtWrWKMcZYfHw8A8DS0tIa3f+4cePYc889p/HctGnTWGhoaJMxPfnkk2zo0KH8zzt37mROTk4Ntjt37lyzx2aMsYqKCo1zqr7W3Mepq440i+bkaZmF4d3qrrD/dmma0gKtjeG+VV66dIkWaG0BKgz/D/cZXLx4UeBI2ubatWsoLy/Hww8/jA4dOvCP7du3a3S3ffrpp6itrcWvv/6KHTt2aLSSXL16FZMmTYKfnx9sbW35QuqMjAwAdQMvqqqqEBoaCqD1LWJN4fbLtXzVd/36ddTU1GDQoEH8c3K5HAMGDEBycjKAujUHhw8fjuDgYDzxxBPYtGkTCgsL+e0rKio0ljqpra3F77//jscee4x/7oUXXsDmzZv5n0tKSmBpacn/fPbs2UYniOW20cf1hrrqSLOMpeZA1yKDPDCw9gKO3rGGhas3epjQAq2N8fT0hJubG3JycnDu3DmEhYUJHZJo5ebm4tatWwBg0oXhnJCQEHz//fe4ePEiRo0axT9vZWXFr8mmb60pvOZi/Ouvv9CxY0eN39VPjq5fv47MzEyo1WqkpaUhODiY/93YsWPh7e2NTZs28TPxBwUFobq6GsB/SUJlZSUsLS21NmN4/QSlLWQyGaKjo3HixAn8/fffWLduHd544w3ExcXB19cXzs7OGonU9evXUVJSwr93tVqNX3/9VSNxO3/+PJ566in+58TExEYTp4KCAgCt65ZsK2pxIs2iAvGWyz4Thayt8/GW/x3sWzDEZJMmAJBIJJR0txA3f1P37t1pgVY03eIkkUhgbW0tyKM1rTmBgYFQKBTIyMhA165dNR6dO3cGUFfkPGXKFDz11FN477338PzzzyM3t276kjt37iAlJQVvvvkmhg8fjoCAAI1kAwC6desGS0tLHDx4EEDDxM7c3Bwqlap1H3y9/XJF6vV16dIF5ubmOH78OP9cTU0NTp8+jcDAQP45iUSCQYMG4Z133sHZs2dhbm6OnTt3Aqj7YnDp0iV+26KiIgDgB0Ts378fhYWFfKvUyZMncfv2bUyYMIF/zYULF/g5ButLSkpCp06d4Ozs3Or33VrU4kSaxV0EiouLcf36dXTr1k3okERJrVab/ASGdwsJCcHevXspcboH6qbT1LdvX0gkEuTk5LTp5i80GxsbvPzyy1i0aBHUajUGDx4MpVKJ48ePw9bWFtOmTcMbb7wBpVKJtWvXokOHDti7dy+ee+457NmzBw4ODnBycsLGjRvh4eGBjIwMvPbaaxrHsLCwwCuvvILPP/8cAPDEE08gJSUFFy9exIwZM+Dj44O4uDikpaWhQ4cOcHR0bNECtxYWFnj11VfxyiuvwNzcHIMGDUJeXh6/3zlz5mDp0qVwdHSEl5cXVq1ahfLycn56gbi4OMTExGDEiBFwdXVFXFwc8vLyEBAQAACIiIjAsmXLUFhYCAcHB3h7e0MikeDHH3+EtbU1Xn75ZYwePRp//PEHOnfujNmzZyM8PFxjxJ1arUZKSgoyMzNhbW0NOzs7AHWF5yNGjNDK3/Ce7lkFRe7JmIvDGWNswIABDAD78ccfhQ5FtK5cucIAMAsLC1ZTUyN0OKKwa9cuBoAFBwcLHYqoTZgwgQFgn376qdChiIa/vz/z9vZm8fHxjRbyip1arWarV69mPXr0YHK5nLm4uLCIiAh25MgRdujQIWZmZsaOHTvGb5+amspsbW3ZV199xRhjLDo6mgUEBDCFQsF69erFDh8+zACwnTt38q8pLi5mc+bMYR4eHkwulzMvLy/24YcfMsYYS0lJYQMHDmSWlpYMAEtNTW1x7CqVir3//vvM29u7wX4rKirYSy+9xJydnZlCoWCDBg1ip06d4l976dIlFhERwVxcXJhCoWDdu3dn69at09j/gAED2IYNG/ifP/zwQ2Zra8vc3NzY5s2bWWJiIvP29mbW1tZs4sSJrKCgQOP13333HfP09GQA2Msvv8zHZWdnx2JjY5t9b9oqDqfESQuMPXGaM2eOxklKGvrxxx8ZgGZHh5iamzdvMgBMJpOx8vJyocMRLS8vLwaAHTx4UOhQRGPy5MnM29ubnThxwiATJ33Iyclhp0+fZikpKUKH0ip79uxhAQEBTKVSaW2fX331FXv44YfvuZ3Jjqr78ssv4ePjAwsLC4SGhuLUqVPNbv/rr7/C398fFhYWCA4Oxt69ezV+zxjD8uXL4eHhAUtLS4SHh+PqVdOctLApVKtyb9Td0lDHjh3h6uoKlUpFM4g3IT8/nx8pZepzONXH/TviiqFJQ9zoMW0VhuvL6NGjMWvWLNy+fVtr+5TL5Vi3bp3W9ncvBpU4/fzzz1i8eDFWrFiBhIQE9O7dGxEREXxR3d1OnDiBSZMmYcaMGTh79izGjx+P8ePHIykpid9m1apVWLt2LTZs2IC4uDhYW1sjIiIClZWV+npbosddxM6ePctPZEY0UeLUEBWI3xv3uXTt2pWv1SCUOLVE/TXqDM3ChQv5QnlteP7559GjRw+t7e9eWp04HTp0qMnfff311+0K5l4+//xzzJw5E9OnT0dgYCA2bNgAKysrbNmypdHt16xZg8jISCxduhQBAQF477330K9fP3zxxRcA6lqbVq9ejTfffBPjxo1Dr169sH37dmRmZmLXrl06fS+GpGfPnlAoFCgqKsKNGzeEDkd0GGNUGN6E+qMySUOUcDeOm5ZBpVKhpqZG4GjER61Wo6KiAoBhJk6GrtWJE5eI1D+Z8/PzMXbs2AaV/9pUXV2N+Ph4hIeH889JpVKEh4cjNja20dfExsZqbA/UVfVz26empiI7O1tjGzs7O4SGhja5T1Mkl8vRq1cvANRy0Jjr169DqVRCoVBoDMsl1M17L5RwN87Gxga+vr4AQK3/jaioqABjDGZmZjA3Nxc6HJPTphannTt34r777sOlS5fw119/ISgoCMXFxfx6MrqQn58PlUoFNzc3jefd3NyQnZ3d6Guys7Ob3Z77b2v2CdQtdFhcXKzxMHZ0A2wa95n06tULcrlc4GjEpf6cPHQDbIhanJrWs2dPAOBbVsh/6nfTaWPGcNI6rU6c7r//fiQmJiIoKAj9+vXDhAkTsGjRIhw+fBje3t66iFF0Vq5cCTs7O/6hzb5asaKlV5pGN7+mderUCS4uLqitrcX58+eFDkdU7ty5w69aT4XhDVHi1DRDrm8yBm0qDr9y5QrOnDmDTp06wczMDCkpKTpfH8bZ2RkymQw5OTkaz+fk5MDdvfEZmt3d3Zvdnvtva/YJ1K0erVQq+cfNmzdb/X4MTf1aFSoQ10SJU9MkEgkl3U3guun8/Pxgb28vbDAixCVO1FLZUFlZGQBKnITS6sTpo48+QlhYGB5++GEkJSXh1KlTOHv2LHr16qXTuiBzc3OEhIRoTAWvVqsRExPT5DpYYWFhDaaOj46O5rf39fWFu7u7xjbFxcWIi4trdm0thUIBW1tbjYexCwoKgm3gA7AY/y66v7kPkauPIiopS+iwBEeF4fdG3byNo4S7edxs0zU1NVQgXk/9wnBDm4rAWLQ6cVqzZg127dqFdevWwcLCAkFBQTh16hQeffRRDBs2TAch/mfx4sXYtGkTtm3bhuTkZMyZMwdlZWWYPn06AGDq1KlYtmwZv/2CBQsQFRWFzz77DJcvX8bbb7+NM2fOYN68eQDqvg0vXLgQ77//Pnbv3o0LFy5g6tSp8PT0xPjx43X6XgzNwSt34DD2VcidvVGjYkjJLsHs7xNMPnlKTU1FUVERzM3N+W/IRBMlTo2jxKl5NjY2MDOrWxVMHyveGwquMFwmk1FhuEBavVbdhQsXGiyiJ5fL8cknn2DMmDFaC6wxTz31FPLy8rB8+XJkZ2ejT58+iIqK4ou7MzIyNNbjuf/++/HDDz/gzTffxOuvv45u3bph165dCAoK4rd55ZVXUFZWhlmzZqGoqAiDBw9GVFQUv8ggqbP6wFWAMUj+/XwZAIkEWBNzFZFBHsIGJ6D6heF0EWsclxgkJSWhsrKS/m39ixKne+P+TZWXlxv8PFcSiQQ7d+5s95dyKgwXXqtbnJpbeXjo0KHtCqYl5s2bh/T0dFRVVSEuLg6hoaH87w4fPoytW7dqbM8tflhVVYWkpCSMGjVK4/cSiQTvvvsusrOzUVlZiQMHDqB79+46fx+GJjW/rC5Tqocx4EZemUARiQN386Pi3qZ5eXnByckJtbW1GpPPmrLCwkKkpqYCoHOnOfUTJ1Mye/ZsSCQSrF69usHvDHXGcGNiUDOHE+H4Olvj7u82Egng52La/3ip1eDeaAbxhri6OF9fXzg6OgocjXgpFAoA/xVDG6rWzIC+c+dOnDx5Ep6eno3+ngrDhUeJE2mRheHdwAAwtRoAIEFdi9OC4abbOscYo8SphShx0kTnTctwLU7V1dWora1t0z6ikrIQufooeuhxUMuwYcMwb948LFy4EM7OzoiIiGiwzYoVK+Dh4aExTcft27fx0ksvYceOHY3OCUczhosDJU6kRSKDPLBhSj+YleWA1VbD3VKNDVNCEBnU9LQNxi4tLQ2FhYWQy+UadXOkIUqcNFHi1DJSqbRd3XVRSVmY/X0CUrJLUFWr1uuglm3btsHc3BzHjx/Hhg0b+OcZY3jppZewfft2HDt2jF+VQa1W45lnnsHSpUubHGhSWVnJF4ZzrXFE/yhxIi0WGeSB4TWnkPHZo3iwKtakkybgv5tfcHAwXcTugavjuXDhAqqqqgSORniUOLUcN5igLd11qw9crWsd//fn+oNadK1bt25YtWoVevTowS9AW1tbiylTpiAmJgb//PMPunbtym//8ccfw8zMDPPnz29yn/W76agwXDiUOJFWoZaD/9DNr+V8fHzg4OCAmpoaky8QLyoqwvXr1wFQYXhLWFpaAmhbi1Nqfhnunq5XX4NaGrsuLFq0CHFxcTh69Cg6duzIPx8fH481a9Zg69atzSZEVBguDpQ4kVapnziZ+gzilDi1HBWI/4crDPfx8YGTk5PA0YhfexInIQe1NJbcPPzww7h9+zb279+v8fyxY8eQm5sLLy8vmJmZwczMDOnp6ViyZAl8fHz47WipFXGgxIm0SnBwMORyOe7cuYOMjAyhwxEMFYa3HiVOdei8aR2uq66qqqrVBeLcoBauEUciEXZQyyOPPIIffvgBzz//PH766Sf++WeeeQbnz59HYmIi//D09MTSpUv5JEutVlPiJBKtngCTmDaFQoGgoCCcPXsW8fHxJrOw893S09NRUFAAuVyO4OBgocMxCPXXOzRllDi1jpmZGRQKBaqqqlBeXt6qJa64QS1rYq7iRl4Z/FyssWB4d0HrMydMmIDvvvsOzzzzDMzMzPD444/DycmpQeujXC6Hu7s7Xx9FheHiQYkTabWQkBA+cXr00UeFDkcQ3M0vKCiILmItxCUK58+fR3V1tcnOtE6JU+tZWVm1KXEC6pInsa1u8Pjjj/Oj6KRSaYuuo1QYLh6UOJFWCwkJwTfffGPSXS5082s9X19fODg4oLCwEBcvXkTfvn2FDknvlEolrl27BoDOndawsrJCYWGhwUyEefjw4QbP3V0T+uSTT+LJJ59sch9paWkaP1M3nXhQ4kRajRsJxBWIm+K3H0qcWk8ikaD7Q08iwzYIj/9yG92OlGBheDfRtQboEtdN6e3tTYXhrcAVWpva0iv10Yg68aDicNJqvXr1gpmZGfLz83Hz5k2hw9E7Kgxvm6ikLGR3HQu5szdUTKLXyQjFgs6btuFaWdpSIG4MqDBcXChxIq1mYWHBz2xrit11GRkZuHPnDszMzKgwvBVWH7gKgEEirbvs6HMyQrGgxKltzMzMTHbBX4AKw8WGEifSJqY8tLx+YTg3VJrcW2p+GXDXrDr6moxQLChxajuupcUUE6f6rU2mWBohNpQ4kTahxIlufq0l5GSEYqBUKnH1al3rGp07rWfKdU71R9QR4VHiRNrElGcQp8SpbbjJCMHU/z7DBJ2MUN/Onj0LAPDy8oKzs7PA0RgO7vrCJQ2GMrJOm6i+STu0da+ixIm0Sa9evSCTyZCXl4dbt24JHY7eUGF423GTEdqhHKy2GjaqEmyYEmIyi0XTedM6crkcQMOkwdQKxBljNKJOS7jPkTu32oqmIyBtYmlpiZ49e+L8+fOIj49H586dhQ5JL27evIn8/HyYmZmhV69eQodjcCKDPFDUl2HSpEcRGhqKyE8mCR2S3lDi1DoymQz29vbIzc0FUJc4yeVy1NTUQKlUmkwSUVFRwU/7whhDZWWl0CEZHC75zM3Nhb29PWQyWbv2ZzCJU0FBAV566SX8+eefkEqleOyxx7BmzRp06NChye1XrFiBv//+GxkZGXBxccH48ePx3nvvwc7Ojt+usUK7H3/8ERMnTtTZezEWISEhOH/+PBISEjB+/Hihw9EL7ubXs2dPKgxvIy5xOHfuHGpra2FmZjCXoXahxKn13N3rWiO55EmpVKK8vBwqlarVM4gbqtLSUty5cwcKhaLBpJikdezt7flzqj0M5oo1efJkZGVlITo6GjU1NZg+fTpmzZqFH374odHtMzMzkZmZiU8//RSBgYFIT0/H7NmzkZmZid9++01j22+//RaRkZH8z/b29rp8K0YjJCQE3377rUkViNPNr/26dOkCGxsblJSU4NKlSybRcldcXIwrV64AoHOnNSQSCTw8PODq6oqamhpERUVhzZo1GDNmDD799FOhw9OL9957Dzt27MD06dPx6quvCh2OwZLL5e1uaeIYROKUnJyMqKgonD59Gv379wcArFu3DqNGjcKnn34KT0/PBq8JCgrC//73P/7nLl264IMPPsCUKVMafMvVVhZqau4uEDeFYbKUOLWfVCpFv379cOTIEcTHx5tE4sQVhnfu3BkuLi4CR2N4ZDIZZDIZ/P39kZ6ejujoaJNp8T148CDS09PRrVs3k3nPYmcQxeGxsbGwt7fnkyYACA8Ph1QqRVxcXIv3o1QqYWtr26BrYO7cuXB2dsaAAQOwZcuWe1beV1VVobi4WONhinr37g2ZTIacnBxkZmYKHY7OUWG49pjadBZ03mgH9/lduXLFJK67tbW1OHfuHAA6d8TEIBKn7OxsuLq6ajxnZmYGR0dHZGdnt2gf+fn5eO+99zBr1iyN599991388ssviI6OxmOPPYYXX3wR69ata3ZfK1euhJ2dHf8wlcLou1laWiIwMBCAadwAb926hby8PMhkMpNoJdEl7ibArd1m7Chx0g5XV1d06tQJAJCYmChsMHqQnJyMiooK2NjYoFu3bkKHQ/4laOL02muvQSKRNPu4fPlyu49TXFyM0aNHIzAwEG+//bbG79566y0MGjQIffv2xauvvopXXnkFn3zySbP7W7ZsGZRKJf8wxfXaOKbUclC/MNzS0lLgaAwbd94kJiaaxNBySpy0p8vQx+AxfR2m71UicvVRo17rkDtv+vbtC6nUINo5TIKgf4klS5YgOTm52Yefnx/c3d35URWc2tpaFBQU3LM2qaSkBJGRkbCxscHOnTvvOX9DaGgobt26haqqqia3USgUsLW11XiYKlNMnOjm137dunWDjY0NKioqtPLlSMxKSkqoMFxLopKykNbp4bqFoiE1+oWi6ZojToIWh7u4uLSoUDIsLAxFRUWIj4/nT6CDBw9CrVYjNDS0ydcVFxcjIiICCoUCu3fvblFhXWJiIhwcHGghxRYypcTp9OnTAID77rtP4EgMn1QqRd++fXH06FHEx8cjKChI6JB0JiEhAYwxdO7cuUHJAWmd1Qeu1i3b08hC0ZFBHkKGphOUOImTQbT9BQQEIDIyEjNnzsSpU6dw/PhxzJs3DxMnTuRH1N2+fRv+/v44deoUgLqkacSIESgrK8PmzZtRXFyM7OxsZGdnQ6VSAQD+/PNPfPPNN0hKSsK1a9ewfv16fPjhh3jppZcEe6+Gpnfv3pBKpcjOzjbqAnHGGJ84DRgwQOBojIOpJN3cNYnOm/ZLzS/D3UN3jHWh6JqaGr4GkM4dcTGI6QgAYMeOHZg3bx6GDx/OT4C5du1a/vc1NTVISUnhp1RPSEjgR9x17dpVY1+pqanw8fGBXC7Hl19+iUWLFoExhq5du+Lzzz/HzJkz9ffGDJyVlRUCAgJw8eJFxMfHNzo1hDG4ceMGCgoKYG5ujuDgYKHDMQr9+vUDYPyJEyXc2uPrbI2U7BKN5MlYF4q+cOECqqqqYG9v3+AeRoRlMImTo6Njk5NdAoCPj4/GNALDhg2757QCkZGRGhNfkrYJCQnhE6exY8cKHY5OcK0Gffv2hbm5ucDRGAduepGzZ88a9Qzi3LlDXbzttzC8G2Z/n1C3ULREirqFoiVGuVB0/dIAU5gjz5AYRFcdETfumzR3gzBGVN+kfd27d4etrS0qKipw8eJFocPRidzcXKSnp0MikVCdihZwC0U7yqrAaqthVVVotAtFUxeveFHiRNqtfuJ0r1Y+Q0UXMe2TSqV8ImqsSTeXcPv7+5v06FttigzywKqH7JHx2aOo/GOFUSZNAF1zxIwSJ9JuvXr1grm5Oe7cuYPU1FShw9G62tpavkiTWpy0y9hbK+nmpxtcN29qairy8vIEjkb7SktLcenSJQB0zREjSpxIuykUCvTp0wcAWrUEjqG4ePEiKioqYGtri+7dja+WQkjGnjhRYbhu2Nvbo0ePHgD++4yNSUJCAtRqNTp16gQPD+ObZsHQUeJEtIKbT8sYb4D165to9l7t4hKKpKQklJaWChyNdjHGqDBch4w56aaWSnGjuwDRClO4iNHNT/s8PT3RqVMnqNVqo1u3LjU1FXfu3IG5uTmtbagDxvxlja454kaJE9EKLnFKSEhATU2NwNFoF3W36JaxJt3cedO7d29aiUAHjHlQCl1zxI0SJ6IV3bp1g729PSorK3HhwgWhw9Ga8vJy/v3Qtz/dMNbEibpbdKv+oJQbN24IHY7W5ObmIi0tjaawEDFKnIhWSCQSo7wBnj17FiqVCh4eHujYsaPQ4Rgl7rwxtoEFNPeXbtUflGJM1xzuvOnRowfs7OwEjoY0hhInojXGeAOk2Xt1r3///pBIJMjIyEB2drbQ4WhFbW0tv5QMtTjpjjHWOVFLpfhR4kS0xhhbnOgipns2NjYIDAwEYDxDyy9duoTy8nLY2Njww+aJ9hnjNYdaKsWPEieiNdxFLDk5GcXFxQJHox10EdMPY7sBcudN//79aQoLHTK2QSn1p7CgL2viRf+iida4ubnB29sbjDGcOXNG6HDaraCgANeuXQPw30zFRDeMrZuXbn760bVrV6MalMJNYSGXy9G7d2+hwyFNoMSJaJUxtRxwN/Fu3brB0dFR4GiMG3fenD59Gmq1WuBo2o87d6ilUreMab3DqKQsPL09CV5Lfkfnmetx6GqB0CGRJlDiRLTKmIo1T5w4AQC4//77BY7E+AUHB8PCwgJFRUV8K5+hKikp4Vs/wsLCBI7G+BnDNScqKQuzv09AdoUUEjNzqDq4Yfb3CYhKyhI6NNIISpyIVhlTi1NsbCwAuvnpg1wuR79+/QAY/rlz6tQpqNVqeHt7w9PTU+hwjJ4xdPOuPnAVEgDgRu5KJJBIgDUxV4UMizSBEieiVf369YNUKsXt27dx69YtocNpM5VKxV+IKXHSD+4GePLkSYEjaR8u4aaWSv2oPyilqKhI2GDaKDW/DHfPfc4YcCOvTJB4SPMocSJaZW1tza/Lxd1ADBG36KyNjQ169uwpdDgmgUs0uC5SQ8XFTwm3fri5uaFLly5gjBlsq5OvszXuniVOIgH8XKwFiYc0z2ASp4KCAkyePBm2trawt7fHjBkz7rma+rBhwyCRSDQes2fP1tgmIyMDo0ePhpWVFVxdXbF06VLU1tbq8q0YvUGDBgEAjh8/LnAkbcclfaGhoZDJZAJHYxq4xOncuXMoKSkROJq2UavVfIsZJU76Y+hJ98LwbmAA2L8DIySSuhanBcO7CxsYaZTBJE6TJ0/GxYsXER0djT179uDo0aOYNWvWPV83c+ZMZGVl8Y9Vq1bxv1OpVBg9ejSqq6tx4sQJbNu2DVu3bsXy5ct1+VaMnqFfxACqbxJCx44d4e3tDbVabbB1TikpKSgsLISlpSUNJ9cj7ppjqF/WIoM84H3rb9TkpUEGNfzdbbBhSggig9yFDo00hhmAS5cuMQDs9OnT/HP79u1jEomE3b59u8nXDR06lC1YsKDJ3+/du5dJpVKWnZ3NP7d+/Xpma2vLqqqqWhyfUqlkAJhSqWzxa4xZWloaA8DMzMxYWVmZ0OG0SdeuXRkAtm/fPqFDMSmTJk1iANg777wjdChtsnnzZgaADRkyROhQTMr58+cZANahQwdWU1MjdDitplarmYuLCwPATpw4IXQ4Jqk193GDaHGKjY2Fvb29xiSE4eHhkEql9+zT3rFjB5ydnREUFIRly5ahvLxcY7/BwcFwc3Pjn4uIiEBxcTEuXrzY5D6rqqpQXFys8SD/8fLygqenJ2praw1yCY28vDx+SDw31Jnoh6G3VtIUFsIIDAyEra0tSktLkZSUJHQ4rXb9+nXk5eXB3NycH11KxMsgEqfs7Gy4urpqPGdmZgZHR8dmFwV9+umn8f333+PQoUNYtmwZvvvuO0yZMkVjv/WTJgD8z83td+XKlbCzs+MfnTt3bsvbMloSicSg65y4GpWAgAA4ODgIHI1p4c6b2NhYqFQqgaNpPeriFYZMJuM/c0NMurnzJiQkBAqFQuBoyL0Imji99tprDYq3735cvny5zfufNWsWIiIiEBwcjMmTJ2P79u3YuXMnrl+/3q64ly1bBqVSyT9u3rzZrv0ZI0NOnKjVQDjBwcGwtrZGcXExLl26JHQ4rVJYWMjHTImT/hlynRONxDQsZkIefMmSJXj22Web3cbPzw/u7u7Izc3VeL62thYFBQVwd2958RzX7XLt2jV06dIF7u7uDYpQc3JyAKDZ/SoUCvpWcA/cRSw2NhZqtdqgFjqlVgPhmJmZYeDAgYiJicGJEycQHBwsdEgtEpWUhfd2JsBrye+QlOYhPqcWkS5CR2VaDLmbl+b+MiyC3s1cXFzg7+/f7MPc3BxhYWEoKipCfHw8/9qDBw9CrVa3qgYlMTERAODh4QGg7sZ44cIFjaQsOjoatra2CAwM1M6bNFF9+vSBpaUlCgsL29VqqG81NTV8XRZdxIRhaC0H3HIZt8sYJGbmgJ0nLZchgNDQUEilUqSlpSEzM1PocFqMlugxPAbRDBAQEIDIyEjMnDkTp06dwvHjxzFv3jxMnDiRX9Lg9u3b8Pf351uQrl+/jvfeew/x8fFIS0vD7t27MXXqVAwZMoSfoHHEiBEIDAzEM888g3PnzmH//v148803MXfuXGpRaie5XM7P6GtI3wDPnz+P8vJy2Nvbo0ePHkKHY5K4bl5DOW/45TJAy2UIycbGhr+2G8q5A9ASPYbIIBInoG50nL+/P4YPH45Ro0Zh8ODB2LhxI//7mpoapKSk8KPmzM3NceDAAYwYMQL+/v5YsmQJHnvsMfz555/8a2QyGfbs2cMXFk6ZMgVTp07Fu+++q/f3Z4wMsc7pn3/+AVD3zc+QuheNycCBAyGRSHD9+nW+61zMaLkM8TDE7jqqqTQ8gtY4tYajoyN++OGHJn/v4+MDxv67fHXu3BlHjhy55369vb2xd+9ercRINBlalwsAHD16FAAwZMgQgSMxXXZ2dggKCsKFCxdw4sQJTJgwQeiQmuXrbI2U7BKN5ImWyxDGoEGD8NVXXxlU4sRdc7gvmkT86Cs10Rmuv/7q1avIy8sTOJp7Y4xR4iQShpR003IZ4sGdNwkJCaioqBA4mnurqanhk7yhQ4cKHA1pKUqciM44OjryRfaGcAO8fPky8vPzYWlpqTHZKtE/7tv3sWPHBI7k3mi5DPHg6oRqamoMYsHf+Ph4lJeXw8nJiQYkGRBKnIhOcS03Lek2FRoXY1hYGMzNzQWOxrRx5018fLzoF/xVq9W4sPc7ZG2djx8fdcO+BUMoaRKIRCLBsGHDAACHDx8WNJaW4K45DzzwANVUGhD6SxGdMqSLGHXTiYe3tzd8fX2hUqlE31p58eJFFBYWwtrampbLEAFDuuZwiRN10xkWSpyITnEXhHPnzqGgoEDgaJpG9U3iYyg3QO7mN2jQIJiZGcx4G6PFXXNOnjyJyspKgaNpmkql4kfx0jXHsFDiRHTK3d0d/v7+YIyJul4lNTUVt2/fhlwup4V9RYJLnMTezUsJt7h069YNHh4eqKqqEnWdU2JiIkpKSmBnZ4fevXsLHQ5pBUqciM6JveUgKikLk7aeh9eS3+E1awOO3lAKHRLBfy0Hp0+fRmlpqcDRNI4xRt0tImModU5cwj148GDIZDKBoyGtQYkT0TkxX8S45TJyqswgMTNHbQdXWi5DJLy9veHj4yPqOqcrV64gNzcXFhYWuO+++4QOh/xLzNccDpdwU0ul4aHEieicmOuc+OUyJP8ulwFaLkNMxH4D5FoNBg4cSMs0iQh3zYmNjRVlnZNareZLF6il0vBQ4kR0Tsx1TrRchriJPXHi4qJWA3Hp3r073N3dRVvnlJSUhIKCAhqJaaAocSJ6IdYboK+zNXBX6kTLZYiHmOucGGM4cOAAAOChhx4SOBpSn9jrnGJiYgDU1TfJ5XKBoyGtRYkT0QuxXsQWhncDIKHlMkTKx8dHtHVOSUlJyM3NhZWVFb+8EBEPsV5zAPAJ98MPPyxwJKQtKHEielG/zik/P1/gaP4zItANVTFfoCYvDXIpaLkMEeJugNy3dLGIjo4GUHdu00zz4vPggw8CAE6cOIGyMvF0vVdXV/OF4eHh4QJHQ9qCEieiF+7u7ggKCgJjTFQ3wAsXLiD7TBSKf12Gi28/TMtliNCIESMAAH///bfAkWjiWg3o5idO3bp1g7e3N6qrq/kifjE4efIkysrK4OrqiuDgYKHDIW1AiRPRm4iICADA/v37BY7kP9zNj1oNxItLTM6dO4fs7GyBo6lTVVXFtxpQd4s4SSQSUSbdXEvl8OHDaX06A0V/NaI39S9ijN09lk0Y1Gogfi4uLvzII+7vJbSTJ0+ivLwcrq6uCAoKEjoc0gQxJk5U32T4KHEievPAAw/AwsICt2/fRnJystDhoKqqim/Cp8RJ3LgboFhaK+sn3BJ+DjAiNg899BCkUikuXbqEW7duCR0OioqKcOrUKQB0zTFklDgRvbG0tOTnuxHDDTA2Nhbl5eVwc3OjVgOR47p5o6Ojof53BKSQuO4WajUQN0dHR35Gd+5vJqTDhw9DrVajR48e6Ny5s9DhkDYymMSpoKAAkydPhq2tLezt7TFjxoxm53VJS0uDRCJp9PHrr7/y2zX2+59++kkfb8kkcTdAMTSd7927F0Bdawa1GohbWFgYrK2tkZOTgwsXLggaS35+PrUaGBAxdddxXxjpvDFsBpM4TZ48GRcvXkR0dDT27NmDo0ePYtasWU1u37lzZ2RlZWk83nnnHXTo0AEjR47U2Pbbb7/V2G78+PE6fjema8SIEbDsHobznmPQ/c19iFx9VLB14fbs2QMAGDNmjCDHJy2nUCj4aQmEbq3ct28fGGPo3bs3OnXqJGgs5N64xEno1krGGH/NGT16tGBxkPYziMQpOTkZUVFR+OabbxAaGorBgwdj3bp1+Omnn5CZmdnoa2QyGdzd3TUeO3fuxJNPPokOHTpobGtvb6+xnYWFhT7elkm6yZzgOuENmDl5obpWjZTsEkEW1U1NTUVycjJkMhl/YSXixrVW7tu3T9A4/vrrLwCUcBuK0NBQ2Nra4s6dO3xLoRDOnTuHW7duwcrKip9jihgmg0icYmNjYW9vj/79+/PPhYeHQyqVtngdovj4eCQmJmLGjBkNfjd37lw4OztjwIAB2LJlyz1HfFVVVaG4uFjjQVpmTcxVgDFI/h2GywBBFtXlbn6DBw+Gvb29Xo9N2ob7ln7s2DEUFhYKEkNNTQ2ioqIAUOJkKORyOd/L8OeffwoWB9faFB4eTl/ODZxBJE7Z2dlwdXXVeM7MzAyOjo4tntdl8+bNCAgIwP3336/x/LvvvotffvkF0dHReOyxx/Diiy9i3bp1ze5r5cqVsLOz4x9U5NdyqflldZlSPUIsqkvddIbHz88PQUFBUKlUfH2avh0/fhxKpRLOzs580TERv0ceeQQA8McffwgWA11zjIegidNrr73WZAE397h8+XK7j1NRUYEffvih0damt956C4MGDULfvn3x6quv4pVXXsEnn3zS7P6WLVsGpVLJP27evNnuGE2Fr7M17i7D1veiuqWlpTh06BAAqjUwNNwNcPfu3YIcn7v5jRo1CjKZTJAYSOuNHDkSMpkMFy9exPXr1/V+/JycHL6bcNSoUXo/PtEuQROnJUuWIDk5udmHn58f3N3dkZubq/Ha2tpaFBQUwN393stj/PbbbygvL8fUqVPvuW1oaChu3bqFqqqqJrdRKBSwtbXVeJCWWRjeDQwAGFekyfS+qG5MTAyqq6vh6+sLf39/vR2XtN+4ceMA1NU5NfdvVFeouNcwOTg48FOhCNFdxw0o6NevHzp27Kj34xPtEjRxcnFxgb+/f7MPc3NzhIWFoaioCPHx8fxrDx48CLVajdDQ0HseZ/PmzXjkkUfg4uJyz20TExPh4OAAhULRrvdGGhcZ5IENU/rBzUIFVlsNWXG23hfV5S6co0ePpmkIDEz//v3h4eGBkpISfskTfbl69SpSUlJgZmZGAwoMEJd0C9FayV1zxo4dq/djEx1gBiIyMpL17duXxcXFsX/++Yd169aNTZo0if/9rVu3WI8ePVhcXJzG665evcokEgnbt29fg33u3r2bbdq0iV24cIFdvXqVffXVV8zKyootX768VbEplUoGgCmVyra9OROUm5vLpFIpA8DS09P1dtzq6mrm6OjIALCDBw/q7bhEe2bNmsUAsBdffFGvx125ciUDwMLDw/V6XKId169fZwCYTCZjBQUFejtuaWkps7S0ZADYmTNn9HZc0jqtuY8bRHE4AOzYsQP+/v4YPnw4Ro0ahcGDB2Pjxo3872tqapCSkoLy8nKN123ZsgWdOnVq9BuiXC7Hl19+ibCwMPTp0wdff/01Pv/8c6xYsULn78fUubi48IX6+vwGePjwYRQUFMDFxQUPPPCA3o5LtKd+nZM+5+XhJs594okn9HZMoj31BxdwXa76sHfvXlRUVMDX15dfc5EYOD0kckaPWpza5tNPP2UA2JAhQ/R2TK61YtasWXo7JtGuiooK5tj7IeYxfR3rumwPi/i/I2zfhUydHrN+a0Vubq5Oj0V0Z8WKFQwAGzNmjN6O+eSTTzIA7JVXXtHbMUnrGWWLEzE+Tz75JIC6eXn0sQBnbW0tfv/9dwDA448/rvPjEd04fK0QNpGLIXf2Ro0aeplE9bfffgMADBs2rEW1kkScnnrqKQB1s88XFBTo/Hjl5eV86xa1VBoPSpyIYDp37owHHngAjDH8/PPPOj/ekSNHkJ+fDycnJ375DmJ4Vh+4Cgmg10lUucSJEm7DFhAQgF69eqGmpgY7d+7U+fH27duH8vJy+Pj4ICQkROfHI/pBiRMR1MSJEwFALwsr79ixAwAwYcIEyOVynR+P6EZqfhnunttfl5OoXrlyBadPn4ZMJsOECRN0cgyiP/q85vz4448A6hJuGsFrPChxIoJ64oknIJPJcObMGVy9qrsWg7KyMr64tyXzeRHx0vckqtu3bwdQt1aem5ubTo5B9Ifrrjt48GCLV55oizt37vDTEDzzzDM6Ow7RP0qciKBcXFwQHh4O4L8blC7s3LkTpaWl8PPzw+DBg3V2HKJ73CSqXPLE1GqdTaKqVqv583LatGla3z/RPz8/PwwcOBBqtRrfffedzo7z008/obq6Gn379kWvXr10dhyif5Q4EcE999xzAIBvv/0WtbW1OjkGd/ObOnUqNZkbOG4SVX93G0BVg5q8NDzVUamTSVQPHTqEmzdvwt7enp8GgRg+bvmtzZs333NR97baunUrAEq4jRElTkRw48aNg5OTE27fvs2vPK9NN2/exIEDBwBQN52xiAzywL6FQzDb6TKyts7H8Z+/0slxtm3bBqCuLoZWtDceTz31FByCH0Tx/fPQ/Y29iFx9VKujMi9evIgzZ87AzMwMTz/9tNb2S8SBEiciOIVCwX8r27Rpk9b3v2HDBjDG8OCDD8LX11fr+yfCmTZtGmQyGY4fP47k5GSt7jsvLw+//PILAODZZ5/V6r6JsI6nl8J21BKdTWmxYcMGAMCYMWNo+gojRIkTEYXnn38eAPDXX39pdU6nyspKfob5efPmaW2/RBw8PDwwZswYAMDXX3+t1X1/8803qKqqQv/+/TFgwACt7psIS5dTWiiVSr6bbu7cue3eHxEfSpyIKAQEBGDo0KFQqVRYu3at1vb7888/Iz8/H507d6YaFSM1Z84cAHX1KkVFRVrZZ01NDb76qq77b/78+VQXZ2R0OaXFt99+i9LSUgQGBmL48OHt3h8RH0qciGi8/PLLAOpaDpRKZbv3xxjDunXrAAAvvvgizMzM2r1PIj4jRoxAcHAwSktL+S6S9tq1axdu3boFV1dXfoZ7YjwandIC7Z/SQqVS8dccSriNFyVORDRGjRqFgIAAFBcXayzg3FbR0dGIj4+HhYUF3xVIjI9EIuGT7rVr16Kqqqpd+2OM4aOPPgIAvPDCC1AoFO2OkYgLP6XFv3kNU6vB0P4pLXbu3IkbN27A3t4eU6ZMaXecRJwocSKiIZVKsXTpUgDA6tWrUVFR0eZ9McbwzjvvAABmz54NZ2dnrcRIxGnixIno2LEjsrKy+JFwbfXXX38hISEB1tbWmD9/vpYiJGJSf0oLGdSoyUuD2cktGN7Dqc37VKvV/DVn/vz5sLbWzYSsRAR0utywiWjNqsqkeZWVlaxz584MAPvkk0/avJ/9+/czAEyhULDMzEwtRkjEavXq1QwA8/T0ZGVlZW3ah0qlYiEhIbSavQkpLi5mzs7ODADbuHFjm/fzyy+/MADMzs6OFRQUaDFCog+tuY9TixMRFYVCgXfffRcA8OGHH6KwsLDV+6itrcXixYsB1BUOe3h4aDVGIk6zZ8+Gt7c3MjMz2zzAYMeOHYiPj0eHDh347j9i3GxsbPDmm28CAN5++22UlbWuQDwqKQsR/3cES0/J4TF9HSa89A4cHBx0ESoRCUqciOg888wz6NmzJwoLC/H666+3+vUbN27ExYsX4ejoiLfeeksHERIxqp90v//++8jIyGjV60tKSvDqq68CAN58802af8eEzJ49Gz4+PsjMzOTPoZaISsrC7O8TkJJTAsjkkLt441BNV61OpknEhxInIjoymQxffPEFgLqJ5I4dO9bi16alpeG1114DALz77rtwdHTUSYxEnKZMmYJBgwahrKwMc+fObdVyGkuXLkVWVha6dOmChQsX6i5IIjoKhYIfDffZZ58hMTGxRa/j5oPiVk6USKRamw+KiBclTkSUhg0bxo+Ee+aZZ3Dnzp17vqa2thbTpk1DSUkJBg0ahNmzZ+s6TCIyUqkUGzduhFwux549e/i5mJoSlZSFyNVH0XXZHuyuDoJl9zBs3LiRRtKZoDFjxuCxxx6DSqXCxIkTUVJScs/X3NDhfFBEvAwmcfrggw9w//33w8rKCvb29i16DWMMy5cvh4eHBywtLREeHo6rVzW/CRQUFGDy5MmwtbWFvb09ZsyYgdLSUh28A9Jan3zyCbp06YL09HRMmjQJ1dXVTW7LGMPcuXNx9OhRWFtbY9u2bZDJZHqMlohFYGAgP53AokWLcPTo0Ua347tZsktQyySQO3vDdcIbqHYN0Ge4RETWr1+Pjh07IiUlBdOmTWt20XG1Wg2z8jtgarXG8xJJ++eDIuJmMIlTdXU1nnjiCX6W4JZYtWoV1q5diw0bNiAuLg7W1taIiIhAZWUlv83kyZNx8eJFREdHY8+ePTh69ChmzZqli7dAWsne3h6///47rKysEB0djUcffRTl5eX877nWgu5v7kPvV3/Gd4cvQCKR4Pvvv0eXLl0EjJwIbdGiRXj88cdRU1ODUaNG4dChQw224bpZuBYDiZS6WUydi4sLfv31V8jlcuzcuRPPPPNMo/OCVVdX44UXXkDaX1/VnTf/Pi+R1LU4tXc+KCJuEtaaIgAR2Lp1KxYuXHjPpRUYY/D09MSSJUv40TFKpRJubm7YunUrJk6ciOTkZAQGBuL06dPo378/ACAqKgqjRo3CrVu34Onp2aKYiouLYWdnB6VSCVtb23a9P9JQdHQ0HnnkEVRWVqJ79+5Yu3YtVB5BePGHRP7Gx9RqSKRSPOKUg7VLnxM6ZCICFRUVGDduHKKjoyGVSvHyyy9jyZIlcHV1hVKpRL+VR6Fq5LujwkyKlPdHChAxEYs//vgDjz/+OGpra9GrVy+sWbMGQ4YMgUQiQWxsLF5++WXExsZCIpHglXU/4FytJ27klcHPxRoLhndHZJC70G+BtFJr7uMG0+LUWqmpqcjOzkZ4eDj/nJ2dHUJDQxEbGwsAiI2Nhb29PZ80AUB4eDikUini4uKa3HdVVRWKi4s1HkR3Hn74Yezfvx+enp64cuUKIiMjMWvNLjCm1mwtAMNV866CxkrEw9LSErt378YzzzwDtVqNVatWwc3NDa6urnB0dERFbjp1s5BGjRs3Dn/++SecnZ1x/vx5PPjgg7Czs4OdnR0GDRqE2NhY2NjYYPfu3fho7kTsWzAEKe+PxL4FQyhpMgFGmzhlZ2cDANzc3DSed3Nz43+XnZ0NV1dXjd+bmZnB0dGR36YxK1eu5P8R2dnZoXPnzlqOntxtyJAhSEpKwoIFC2BrawuZgyckEs3Tl0FCRZlEg4WFBbZv345du3bhvvvuAwDk5eVBrVbDJv0Y3z0HUDcL0RQZGYmkpCS88MIL6NChA0pLS1FSUgIrKytMnz4dSUlJGDNmjNBhEgEImji99tprkEgkzT4uX74sZIiNWrZsGZRKJf+4efOm0CGZBAcHB6xevRp37tyBn0uHhot0UmsBacK4ceNw6tQp5Obm4ty5c8jMzMTlAz/xy24ozKTwd7fBhikh1GJAeG5ubtiwYQMKCgqQnJyMS5cuoaCgAFu2bIGXl5fQ4RGBCLpc/JIlS/Dss882u42fn1+b9u3uXnfxy8nJ0Zg5OicnB3369OG3yc3N1XhdbW0tCgoK+Nc3RqFQ0HBlAZmZmeHV0UGY/X0C30pArQWkJVxcXDQmtowM8kBkEM0sT5onl8vh7+8vdBhEJARNnO6+iGmTr68v3N3dERMTwydKxcXFiIuL40fmhYWFoaioCPHx8QgJCQEAHDx4EGq1GqGhoTqJi2gHt0jnmpirVJRJCCFEbwRNnFojIyMDBQUFyMjIgEql4md27dq1Kzp06AAA8Pf3x8qVKzFhwgRIJBIsXLgQ77//Prp16wZfX1+89dZb8PT0xPjx4wEAAQEBiIyMxMyZM7FhwwbU1NRg3rx5mDhxYotH1BHhUGsBIYQQfTOYxGn58uXYtm0b/3Pfvn0BAIcOHcKwYcMAACkpKVAqlfw2r7zyCsrKyjBr1iwUFRVh8ODBiIqKgoWFBb/Njh07MG/ePAwfPhxSqRSPPfZYmxcIJYQQQohxM7h5nMSI5nEihBBCDBfN40QIIYQQogOUOBFCCCGEtBAlToQQQgghLUSJEyGEEEJICxnMqDox4+rrac06QgghxPBw9++WjJejxEkLSkpKAIDWrCOEEEIMWElJCezs7JrdhqYj0AK1Wo3MzEzY2NhAIrl7BbW2Ky4uRufOnXHz5k2a5kDH6LPWD/qc9Yc+a/2hz1o/dPk5M8ZQUlICT09PSKXNVzFRi5MWSKVSdOrUSWf7t7W1pX+MekKftX7Q56w/9FnrD33W+qGrz/leLU0cKg4nhBBCCGkhSpwIIYQQQlqIEicRUygUWLFiBRQKhdChGD36rPWDPmf9oc9af+iz1g+xfM5UHE4IIYQQ0kLU4kQIIYQQ0kKUOBFCCCGEtBAlToQQQgghLUSJk0h9+eWX8PHxgYWFBUJDQ3Hq1CmhQzI6K1euxH333QcbGxu4urpi/PjxSElJETosk/DRRx9BIpFg4cKFQodilG7fvo0pU6bAyckJlpaWCA4OxpkzZ4QOy6ioVCq89dZb8PX1haWlJbp06YL33nuvRUt2kOYdPXoUY8eOhaenJyQSCXbt2qXxe8YYli9fDg8PD1haWiI8PBxXr17VW3yUOInQzz//jMWLF2PFihVISEhA7969ERERgdzcXKFDMypHjhzB3LlzcfLkSURHR6OmpgYjRoxAWVmZ0KEZtdOnT+Prr79Gr169hA7FKBUWFmLQoEGQy+XYt28fLl26hM8++wwODg5Ch2ZUPv74Y6xfvx5ffPEFkpOT8fHHH2PVqlVYt26d0KEZvLKyMvTu3Rtffvllo79ftWoV1q5diw0bNiAuLg7W1taIiIhAZWWlfgJkRHQGDBjA5s6dy/+sUqmYp6cnW7lypYBRGb/c3FwGgB05ckToUIxWSUkJ69atG4uOjmZDhw5lCxYsEDoko/Pqq6+ywYMHCx2G0Rs9ejR77rnnNJ579NFH2eTJkwWKyDgBYDt37uR/VqvVzN3dnX3yySf8c0VFRUyhULAff/xRLzFRi5PIVFdXIz4+HuHh4fxzUqkU4eHhiI2NFTAy46dUKgEAjo6OAkdivObOnYvRo0drnN9Eu3bv3o3+/fvjiSeegKurK/r27YtNmzYJHZbRuf/++xETE4MrV64AAM6dO4d//vkHI0eOFDgy45aamors7GyNa4idnR1CQ0P1do+ktepEJj8/HyqVCm5ubhrPu7m54fLlywJFZfzUajUWLlyIQYMGISgoSOhwjNJPP/2EhIQEnD59WuhQjNqNGzewfv16LF68GK+//jpOnz6N+fPnw9zcHNOmTRM6PKPx2muvobi4GP7+/pDJZFCpVPjggw8wefJkoUMzatnZ2QDQ6D2S+52uUeJECOpaQpKSkvDPP/8IHYpRunnzJhYsWIDo6GhYWFgIHY5RU6vV6N+/Pz788EMAQN++fZGUlIQNGzZQ4qRFv/zyC3bs2IEffvgBPXv2RGJiIhYuXAhPT0/6nI0cddWJjLOzM2QyGXJycjSez8nJgbu7u0BRGbd58+Zhz549OHToEDp16iR0OEYpPj4eubm56NevH8zMzGBmZoYjR45g7dq1MDMzg0qlEjpEo+Hh4YHAwECN5wICApCRkSFQRMZp6dKleO211zBx4kQEBwfjmWeewaJFi7By5UqhQzNq3H1QyHskJU4iY25ujpCQEMTExPDPqdVqxMTEICwsTMDIjA9jDPPmzcPOnTtx8OBB+Pr6Ch2S0Ro+fDguXLiAxMRE/tG/f39MnjwZiYmJkMlkQodoNAYNGtRgWo0rV67A29tboIiMU3l5OaRSzVuoTCaDWq0WKCLT4OvrC3d3d417ZHFxMeLi4vR2j6SuOhFavHgxpk2bhv79+2PAgAFYvXo1ysrKMH36dKFDMypz587FDz/8gD/++AM2NjZ8/7idnR0sLS0Fjs642NjYNKgds7a2hpOTE9WUadmiRYtw//3348MPP8STTz6JU6dOYePGjdi4caPQoRmVsWPH4oMPPoCXlxd69uyJs2fP4vPPP8dzzz0ndGgGr7S0FNeuXeN/Tk1NRWJiIhwdHeHl5YWFCxfi/fffR7du3eDr64u33noLnp6eGD9+vH4C1MvYPdJq69atY15eXszc3JwNGDCAnTx5UuiQjA6ARh/ffvut0KGZBJqOQHf+/PNPFhQUxBQKBfP392cbN24UOiSjU1xczBYsWMC8vLyYhYUF8/PzY2+88QarqqoSOjSDd+jQoUavzdOmTWOM1U1J8NZbbzE3NzemUCjY8OHDWUpKit7ikzBG05wSQgghhLQE1TgRQgghhLQQJU6EEEIIIS1EiRMhhBBCSAtR4kQIIYQQ0kKUOBFCCCGEtBAlToQQQgghLUSJEyGEEEJIC1HiRAghhBDSQpQ4EUIIIYS0ECVOhBDSjGHDhmHhwoVCh0EIEQlKnAghhBBCWojWqiOEkCY8++yz2LZtm8Zzqamp8PHxESYgQojgKHEihJAmKJVKjBw5EkFBQXj33XcBAC4uLpDJZAJHRggRipnQARBCiFjZ2dnB3NwcVlZWcHd3FzocQogIUI0TIYQQQkgLUeJECCGEENJClDgRQkgzzM3NoVKphA6DECISlDgRQkgzfHx8EBcXh7S0NOTn50OtVgsdEiFEQJQ4EUJIM15++WXIZDIEBgbCxcUFGRkZQodECBEQTUdACCGEENJC1OJECCGEENJClDgRQgghhLQQJU6EEEIIIS1EiRMhhBBCSAtR4kQIIYQQ0kKUOBFCCCGEtBAlToQQQgghLUSJEyGEEEJIC1HiRAghhBDSQpQ4EUIIIYS0ECVOhBBCCCEtRIkTIYQQQkgL/T+JscYGlhjd/AAAAABJRU5ErkJggg==",
      "text/plain": [
       "<Figure size 600x350 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "class Oscillator(brainstate.nn.Dynamics, DiffEqModule):\n",
    "    def __init__(self, omega=1.0):\n",
    "        super().__init__(in_size=1)\n",
    "        self.omega = omega\n",
    "\n",
    "    def init_state(self, *args):\n",
    "        self.x = DiffEqState(jnp.ones(1))   # position, x(0) = 1\n",
    "        self.v = DiffEqState(jnp.zeros(1))  # velocity, v(0) = 0\n",
    "\n",
    "    def compute_derivative(self, *args):\n",
    "        self.x.derivative = self.v.value\n",
    "        self.v.derivative = -(self.omega ** 2) * self.x.value\n",
    "\n",
    "\n",
    "osc = Oscillator(omega=2.0)\n",
    "brainstate.nn.init_all_states(osc)\n",
    "step = braincell.quad.get_integrator(\"rk4\")\n",
    "\n",
    "dt, n = 0.01, 1000\n",
    "ts, xs = [], []\n",
    "with brainstate.environ.context(dt=dt):\n",
    "    for i in range(n):\n",
    "        with brainstate.environ.context(t=i * dt):\n",
    "            step(osc)\n",
    "        ts.append((i + 1) * dt)\n",
    "        xs.append(float(osc.x.value[0]))\n",
    "ts, xs = np.array(ts), np.array(xs)\n",
    "\n",
    "plt.figure(figsize=(6, 3.5))\n",
    "plt.plot(ts, np.cos(2.0 * ts), \"k-\", label=r\"exact  $\\cos(\\omega t)$\")\n",
    "plt.plot(ts[::40], xs[::40], \"o\", ms=4, label=\"rk4\")\n",
    "plt.xlabel(\"t\"); plt.ylabel(\"x\"); plt.legend(); plt.title(\"Harmonic oscillator\")\n",
    "plt.tight_layout(); plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e2b30188",
   "metadata": {},
   "source": [
    "Both `DiffEqState`s are advanced together by the same solver step — you\n",
    "never integrate them by hand. That is the payoff of the protocol: you write the\n",
    "right-hand side, and `braincell.quad` does the stepping.\n",
    "\n",
    "## Where to go next\n",
    "\n",
    "- [Choosing and Using Solvers](solvers) — the full solver catalog, how to pick\n",
    "  one for stiff neural dynamics, and the high-level `solver=` shortcut.\n",
    "- [Advanced Integration](advanced) — per-subsystem solvers, the stochastic\n",
    "  `diffusion` slot, and registering your own integrator."
   ]
  }
 ],
 "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
}
