diff --git a/braintrace/__init__.py b/braintrace/__init__.py index bbd47c4..31a47c4 100644 --- a/braintrace/__init__.py +++ b/braintrace/__init__.py @@ -41,7 +41,10 @@ hidden->weight / hidden->hidden Jacobian computations. 4. **Algorithms** — online-learning orchestrators: the exact algorithms :class:`D_RTRL` / :func:`pp_prop` / :class:`ES_D_RTRL`, and the SNN family - :class:`EProp`, :class:`OSTLRecurrent`, :class:`OSTLFeedforward`. + :class:`EProp`, :class:`OSTLRecurrent`, :class:`OSTLFeedforward`. Every one + of them carries the two sequence drivers of + :class:`SequenceDriverMixin` — ``etrace_grad`` and ``etrace_evolve`` — so a + caller never writes the per-step gradient-accumulation loop by hand. The :mod:`braintrace.nn` subpackage provides ready-made ETP-wired layers (linear maps, convolutions, recurrent cells, read-outs). @@ -49,7 +52,13 @@ Notes ----- The convenience entry point :func:`compile` wraps a model together with an -algorithm into a single trainable object and is the recommended starting point. +algorithm into a single trainable object and is the recommended starting point: +one call replaces ``init_all_states`` + algorithm construction + +``compile_graph`` (+ the vmap wrapper, with ``vmap=True``). The object it +returns drives a sequence with :meth:`~SequenceDriverMixin.etrace_grad` +(accumulate online gradients under a loss) or +:meth:`~SequenceDriverMixin.etrace_evolve` (advance hidden state and the +eligibility trace with no loss). The ``braintrace.MatMulOp`` / ``ETraceParam`` style names from the v0.1.x API are deprecated shims served lazily with a :class:`DeprecationWarning`; new code should mark parameters by routing them through ETP ops instead. diff --git a/braintrace/_algorithm/d_rtrl.py b/braintrace/_algorithm/d_rtrl.py index d0f8743..0b1e211 100644 --- a/braintrace/_algorithm/d_rtrl.py +++ b/braintrace/_algorithm/d_rtrl.py @@ -80,11 +80,19 @@ class D_RTRL(ParamDimVjpAlgorithm): >>> import brainstate >>> import braintrace + >>> import jax.numpy as jnp >>> >>> model = braintrace.nn.ValinaRNNCell(2, 4, activation='tanh') >>> x0 = brainstate.random.randn(2) >>> learner = braintrace.compile(model, braintrace.D_RTRL, x0) >>> y = learner.update(x0) + >>> + >>> # etrace_grad drives the sequence and accumulates the online gradients + >>> xs = brainstate.random.randn(10, 2) # (T, ...) + >>> ys = brainstate.random.randn(10, 4) + >>> def step_loss(x, y): + ... return jnp.mean((learner(x) - y) ** 2) + >>> grads, losses = learner.etrace_grad(xs, ys, step_fn=step_loss, return_value=True) References ---------- diff --git a/braintrace/_algorithm/e_prop.py b/braintrace/_algorithm/e_prop.py index 15086e0..d220d23 100644 --- a/braintrace/_algorithm/e_prop.py +++ b/braintrace/_algorithm/e_prop.py @@ -151,6 +151,7 @@ class EProp(ParamDimVjpAlgorithm): >>> import brainstate >>> import braintrace + >>> import jax.numpy as jnp >>> >>> class RSNN(brainstate.nn.Module): ... def __init__(self): @@ -165,6 +166,13 @@ class EProp(ParamDimVjpAlgorithm): >>> # one call: initialise states, build the trace graph, return a learner >>> learner = braintrace.compile(model, braintrace.EProp, x0, kappa_filter_decay=0.9) >>> y = learner(x0) # forward pass + eligibility-trace update + >>> + >>> # etrace_grad drives the sequence and accumulates the online gradients + >>> xs = brainstate.random.randn(10, 1) # (T, ...) + >>> ys = brainstate.random.randn(10, 1) + >>> def step_loss(x, y): + ... return jnp.mean((learner(x) - y) ** 2) + >>> grads, losses = learner.etrace_grad(xs, ys, step_fn=step_loss, return_value=True) References ---------- diff --git a/braintrace/_algorithm/io_dim_vjp.py b/braintrace/_algorithm/io_dim_vjp.py index 8da5060..6d21a04 100644 --- a/braintrace/_algorithm/io_dim_vjp.py +++ b/braintrace/_algorithm/io_dim_vjp.py @@ -753,6 +753,7 @@ class IODimVjpAlgorithm(ETraceVjpAlgorithm): >>> import brainstate >>> import braintrace + >>> import jax.numpy as jnp >>> >>> class RNN(brainstate.nn.Module): ... def __init__(self): @@ -767,6 +768,13 @@ class IODimVjpAlgorithm(ETraceVjpAlgorithm): >>> # one call: initialise states, build the trace graph, return a learner >>> learner = braintrace.compile(model, braintrace.pp_prop, x0, decay_or_rank=0.9) # or rank: decay_or_rank=19 >>> y = learner(x0) # forward pass + eligibility-trace update + >>> + >>> # etrace_grad drives the sequence and accumulates the online gradients + >>> xs = brainstate.random.randn(10, 1) # (T, ...) + >>> ys = brainstate.random.randn(10, 1) + >>> def step_loss(x, y): + ... return jnp.mean((learner(x) - y) ** 2) + >>> grads, losses = learner.etrace_grad(xs, ys, step_fn=step_loss, return_value=True) References ---------- diff --git a/braintrace/_algorithm/ostl.py b/braintrace/_algorithm/ostl.py index fc7d314..59c3b2b 100644 --- a/braintrace/_algorithm/ostl.py +++ b/braintrace/_algorithm/ostl.py @@ -118,6 +118,7 @@ class OSTLRecurrent(ParamDimVjpAlgorithm): >>> import brainstate >>> import braintrace + >>> import jax.numpy as jnp >>> >>> class Net(brainstate.nn.Module): ... def __init__(self): @@ -132,6 +133,13 @@ class OSTLRecurrent(ParamDimVjpAlgorithm): >>> # one call: initialise states, build the trace graph, return a learner >>> learner = braintrace.compile(model, braintrace.OSTLRecurrent, x0) >>> y = learner(x0) + >>> + >>> # etrace_grad drives the sequence and accumulates the online gradients + >>> xs = brainstate.random.randn(10, 1) # (T, ...) + >>> ys = brainstate.random.randn(10, 1) + >>> def step_loss(x, y): + ... return jnp.mean((learner(x) - y) ** 2) + >>> grads, losses = learner.etrace_grad(xs, ys, step_fn=step_loss, return_value=True) References ---------- @@ -204,6 +212,7 @@ class OSTLFeedforward(pp_prop): >>> import brainstate >>> import braintrace + >>> import jax.numpy as jnp >>> >>> class Net(brainstate.nn.Module): ... def __init__(self): @@ -218,6 +227,13 @@ class OSTLFeedforward(pp_prop): >>> # one call: initialise states, build the trace graph, return a learner >>> learner = braintrace.compile(model, braintrace.OSTLFeedforward, x0) >>> y = learner(x0) + >>> + >>> # etrace_grad drives the sequence and accumulates the online gradients + >>> xs = brainstate.random.randn(10, 1) # (T, ...) + >>> ys = brainstate.random.randn(10, 1) + >>> def step_loss(x, y): + ... return jnp.mean((learner(x) - y) ** 2) + >>> grads, losses = learner.etrace_grad(xs, ys, step_fn=step_loss, return_value=True) References ---------- diff --git a/braintrace/_algorithm/param_dim_vjp.py b/braintrace/_algorithm/param_dim_vjp.py index d12a044..887f28b 100644 --- a/braintrace/_algorithm/param_dim_vjp.py +++ b/braintrace/_algorithm/param_dim_vjp.py @@ -1073,6 +1073,7 @@ class ParamDimVjpAlgorithm(ETraceVjpAlgorithm): >>> import brainstate >>> import braintrace + >>> import jax.numpy as jnp >>> >>> class RNN(brainstate.nn.Module): ... def __init__(self): @@ -1088,6 +1089,13 @@ class ParamDimVjpAlgorithm(ETraceVjpAlgorithm): >>> # initialises states, builds the trace graph, and returns a learner. >>> learner = braintrace.compile(model, braintrace.D_RTRL, x0) >>> y = learner(x0) # forward pass + eligibility-trace update + >>> + >>> # etrace_grad drives the sequence and accumulates the online gradients + >>> xs = brainstate.random.randn(10, 1) # (T, ...) + >>> ys = brainstate.random.randn(10, 1) + >>> def step_loss(x, y): + ... return jnp.mean((learner(x) - y) ** 2) + >>> grads, losses = learner.etrace_grad(xs, ys, step_fn=step_loss, return_value=True) References ---------- diff --git a/braintrace/_algorithm/pp_prop.py b/braintrace/_algorithm/pp_prop.py index 3741283..14d017d 100644 --- a/braintrace/_algorithm/pp_prop.py +++ b/braintrace/_algorithm/pp_prop.py @@ -82,6 +82,7 @@ class pp_prop(IODimVjpAlgorithm): >>> import brainstate >>> import braintrace + >>> import jax.numpy as jnp >>> >>> class RNN(brainstate.nn.Module): ... def __init__(self): @@ -96,6 +97,13 @@ class pp_prop(IODimVjpAlgorithm): >>> # one call: initialise states, build the trace graph, return a learner >>> learner = braintrace.compile(model, braintrace.pp_prop, x0, decay_or_rank=0.9) # or rank: decay_or_rank=19 >>> y = learner(x0) # forward pass + eligibility-trace update + >>> + >>> # etrace_grad drives the sequence and accumulates the online gradients + >>> xs = brainstate.random.randn(10, 1) # (T, ...) + >>> ys = brainstate.random.randn(10, 1) + >>> def step_loss(x, y): + ... return jnp.mean((learner(x) - y) ** 2) + >>> grads, losses = learner.etrace_grad(xs, ys, step_fn=step_loss, return_value=True) References ---------- diff --git a/braintrace/_algorithm/snap_n.py b/braintrace/_algorithm/snap_n.py index c999308..c47ac5f 100644 --- a/braintrace/_algorithm/snap_n.py +++ b/braintrace/_algorithm/snap_n.py @@ -160,6 +160,7 @@ class SnAp(ParamDimVjpAlgorithm): >>> import brainstate >>> import braintrace + >>> import jax.numpy as jnp >>> >>> class Net(brainstate.nn.Module): ... def __init__(self): @@ -173,6 +174,13 @@ class SnAp(ParamDimVjpAlgorithm): >>> x0 = brainstate.random.randn(1) >>> learner = braintrace.compile(model, braintrace.SnAp, x0, n=2) >>> y = learner(x0) + >>> + >>> # etrace_grad drives the sequence and accumulates the online gradients + >>> xs = brainstate.random.randn(10, 1) # (T, ...) + >>> ys = brainstate.random.randn(10, 1) + >>> def step_loss(x, y): + ... return jnp.mean((learner(x) - y) ** 2) + >>> grads, losses = learner.etrace_grad(xs, ys, step_fn=step_loss, return_value=True) """ __module__ = 'braintrace' diff --git a/braintrace/_algorithm/three_factor.py b/braintrace/_algorithm/three_factor.py index a4f6732..83e28b1 100644 --- a/braintrace/_algorithm/three_factor.py +++ b/braintrace/_algorithm/three_factor.py @@ -130,6 +130,21 @@ class ThreeFactor(ParamDimVjpAlgorithm): The keyword takes precedence for the call it appears on. + Over a sequence, the per-step reward is simply a second sequence: + ``etrace_grad`` slices every sequence in lockstep and hands the slices to + ``step_fn`` positionally, and ``step_fn`` -- not the driver -- owns the + model call, so there is nowhere the modulator has to be threaded through. + + .. code-block:: python + + >>> xs = jnp.zeros((10, 1, 4)) + >>> rewards = jnp.linspace(-1.0, 1.0, 10) + >>> ys = jnp.zeros((10, 1, 4)) + >>> def step_loss(x, reward, y): + ... return jnp.mean((learner.update(x, modulator=reward) - y) ** 2) + >>> grads, losses = learner.etrace_grad( + ... xs, rewards, ys, step_fn=step_loss, return_value=True) + Notes ----- Under single-step, every **plain** (non-ETP) parameter's gradient is exactly diff --git a/braintrace/_algorithm/uoro.py b/braintrace/_algorithm/uoro.py index 7a5637e..ac7382b 100644 --- a/braintrace/_algorithm/uoro.py +++ b/braintrace/_algorithm/uoro.py @@ -118,6 +118,21 @@ class UORO(RandomProjectionVjpAlgorithm): >>> learner.compile_graph(braintrace.MultiStepData(jnp.zeros((1, 1, 4)))) >>> learner.init_etrace_state() + UORO is multi-step by construction, so ``etrace_grad`` drives it in **window + mode**: pass ``chunk_size=k`` with ``k >= 2``, and ``step_fn`` receives a + ``(k, ...)`` slice, wraps its model input in :class:`MultiStepData`, and + returns a ``(k,)`` vector of per-step losses rather than a scalar. + + .. code-block:: python + + >>> xs = jnp.zeros((10, 1, 4)) + >>> ys = jnp.zeros((10, 1, 4)) + >>> def window_loss(x, y): # x, y are (k, 1, 4) + ... out = learner(braintrace.MultiStepData(x)) + ... return jnp.mean((out - y) ** 2, axis=(1, 2)) # (k,) + >>> grads, losses = learner.etrace_grad( + ... xs, ys, step_fn=window_loss, chunk_size=5, return_value=True) + Notes ----- **Variance grows with the number of window boundaries.** The estimate is diff --git a/braintrace/_compile.py b/braintrace/_compile.py index cc96a19..294195b 100644 --- a/braintrace/_compile.py +++ b/braintrace/_compile.py @@ -253,6 +253,7 @@ def compile( >>> import brainstate >>> import braintrace + >>> import jax.numpy as jnp >>> >>> class RNN(brainstate.nn.Module): ... def __init__(self): @@ -276,6 +277,16 @@ def compile( >>> config = braintrace.ETraceConfig() >>> by_config = braintrace.compile( ... model, config, x0, batch_size=1) + >>> + >>> # Every learner compile returns carries the two sequence drivers. + >>> xs = brainstate.random.randn(10, 1, 3) # (T, batch, features) + >>> ys = brainstate.random.randn(10, 1, 1) + >>> def step_loss(x, y): + ... return jnp.mean((by_name(x) - y) ** 2) + >>> grads, losses = by_name.etrace_grad(xs, ys, step_fn=step_loss, return_value=True) + >>> # etrace_evolve is the same drive with no loss: it advances hidden + >>> # state and the eligibility trace, optionally stacking the outputs. + >>> outs = by_name.etrace_evolve(xs, return_outputs=True) """ cls = _resolve_algorithm(algorithm) if isinstance(algorithm, ETraceConfig): diff --git a/docs/advanced/batching.ipynb b/docs/advanced/batching.ipynb index 3806855..845b760 100644 --- a/docs/advanced/batching.ipynb +++ b/docs/advanced/batching.ipynb @@ -194,7 +194,13 @@ "cell_type": "markdown", "id": "a1b2c3d4e5f60016", "metadata": {}, - "source": "**What happens in `train_step`:**\n\n1. `weights` collects all `ParamState` objects from the model.\n2. `braintrace.compile(model, braintrace.D_RTRL, inputs[0], batch_size=B, vmap=True)` initialises per-sample hidden states, compiles the computation graph using a single time step's batched input (`inputs[0]`, shape `(batch_size, n_in)`), and wraps the result in `brainstate.nn.Vmap` for batch-parallel execution — all in one call.\n3. `brainstate.transform.scan` iterates over the time dimension (`inputs` has shape `(n_steps, batch_size, n_in)`). At each step, `step_fn` computes the loss and its gradients with respect to `weights`, then accumulates them.\n4. The returned `grads` dictionary can be passed to an optimizer (e.g., `braintools.optim.Adam`) for a parameter update." + "source": [ + "**What happens in `train_step`:**\n", + "\n", + "1. `braintrace.compile(model, braintrace.D_RTRL, inputs[0], batch_size=B, vmap=True)` initialises per-sample hidden states, compiles the computation graph using a single time step's batched input (`inputs[0]`, shape `(batch_size, n_in)`), and wraps the result in a `braintrace.ETraceVmap` (a `brainstate.nn.Vmap` that also carries the sequence drivers) for batch-parallel execution — all in one call.\n", + "2. `vmapped_algo.etrace_grad` iterates over the time dimension (`inputs` has shape `(n_steps, batch_size, n_in)`). At each step it calls `step_fn` for the loss and takes its online gradient, then accumulates; `reduction='sum'` accumulates without dividing. The vmapped learner carries the same drivers as an unbatched one, so this line is identical in both batching strategies.\n", + "3. The returned `grads` dictionary can be passed to an optimizer (e.g., `braintools.optim.Adam`) for a parameter update." + ] }, { "cell_type": "markdown", diff --git a/docs/quickstart/concepts.ipynb b/docs/quickstart/concepts.ipynb index 99c7c6b..1bf3cc9 100644 --- a/docs/quickstart/concepts.ipynb +++ b/docs/quickstart/concepts.ipynb @@ -101,10 +101,10 @@ "id": "f6a7b8c9d0e1f2a3", "metadata": { "execution": { - "iopub.execute_input": "2026-07-27T03:54:40.747320Z", - "iopub.status.busy": "2026-07-27T03:54:40.746322Z", - "iopub.status.idle": "2026-07-27T03:54:43.061174Z", - "shell.execute_reply": "2026-07-27T03:54:43.061174Z" + "iopub.execute_input": "2026-07-28T15:24:07.543013Z", + "iopub.status.busy": "2026-07-28T15:24:07.542853Z", + "iopub.status.idle": "2026-07-28T15:24:10.553048Z", + "shell.execute_reply": "2026-07-28T15:24:10.552027Z" } }, "outputs": [], @@ -127,10 +127,10 @@ "id": "a7b8c9d0e1f2a3b4", "metadata": { "execution": { - "iopub.execute_input": "2026-07-27T03:54:43.063229Z", - "iopub.status.busy": "2026-07-27T03:54:43.063229Z", - "iopub.status.idle": "2026-07-27T03:54:43.068436Z", - "shell.execute_reply": "2026-07-27T03:54:43.067429Z" + "iopub.execute_input": "2026-07-28T15:24:10.555587Z", + "iopub.status.busy": "2026-07-28T15:24:10.555051Z", + "iopub.status.idle": "2026-07-28T15:24:10.559680Z", + "shell.execute_reply": "2026-07-28T15:24:10.558826Z" } }, "outputs": [], @@ -207,10 +207,10 @@ "id": "d0e1f2a3b4c5d6e7", "metadata": { "execution": { - "iopub.execute_input": "2026-07-27T03:54:43.070434Z", - "iopub.status.busy": "2026-07-27T03:54:43.069463Z", - "iopub.status.idle": "2026-07-27T03:54:43.073884Z", - "shell.execute_reply": "2026-07-27T03:54:43.073884Z" + "iopub.execute_input": "2026-07-28T15:24:10.561273Z", + "iopub.status.busy": "2026-07-28T15:24:10.560994Z", + "iopub.status.idle": "2026-07-28T15:24:10.564917Z", + "shell.execute_reply": "2026-07-28T15:24:10.564161Z" } }, "outputs": [], @@ -255,10 +255,10 @@ "id": "a3b4c5d6e7f8a9b0", "metadata": { "execution": { - "iopub.execute_input": "2026-07-27T03:54:43.075931Z", - "iopub.status.busy": "2026-07-27T03:54:43.075931Z", - "iopub.status.idle": "2026-07-27T03:54:44.160096Z", - "shell.execute_reply": "2026-07-27T03:54:44.160096Z" + "iopub.execute_input": "2026-07-28T15:24:10.566817Z", + "iopub.status.busy": "2026-07-28T15:24:10.566461Z", + "iopub.status.idle": "2026-07-28T15:24:13.777817Z", + "shell.execute_reply": "2026-07-28T15:24:13.776730Z" } }, "outputs": [], @@ -280,10 +280,10 @@ "id": "b4c5d6e7f8a9b0c1", "metadata": { "execution": { - "iopub.execute_input": "2026-07-27T03:54:44.162099Z", - "iopub.status.busy": "2026-07-27T03:54:44.162099Z", - "iopub.status.idle": "2026-07-27T03:54:46.646904Z", - "shell.execute_reply": "2026-07-27T03:54:46.646904Z" + "iopub.execute_input": "2026-07-28T15:24:13.780365Z", + "iopub.status.busy": "2026-07-28T15:24:13.779894Z", + "iopub.status.idle": "2026-07-28T15:24:16.895093Z", + "shell.execute_reply": "2026-07-28T15:24:16.894369Z" } }, "outputs": [ @@ -292,10 +292,10 @@ "output_type": "stream", "text": [ "initial loss: 0.24410992860794067\n", - "final loss: 0.21328341960906982\n", - "initial prediction: [[0.00592518]]\n", - "final prediction: [[0.03817382]]\n", - "parameter change: 0.05644569918513298\n" + "final loss: 0.2132834494113922\n", + "initial prediction: [[0.00592517]]\n", + "final prediction: [[0.03817381]]\n", + "parameter change: 0.05644570291042328\n" ] } ], @@ -363,11 +363,11 @@ "source": [ "### Code comparison with BPTT\n", "\n", - "A fair comparison holds model structure, initialization, inputs, targets, loss, and reset policy fixed. The online path differentiates one step at a time and accumulates gradients during the forward scan. The BPTT path first constructs the full sequence loss and differentiates through the complete `for_loop`.\n", + "A fair comparison holds model structure, initialization, inputs, targets, loss, and reset policy fixed. The online path differentiates one step at a time and accumulates gradients during the forward drive, which `learner.etrace_grad` performs. The BPTT path first constructs the full sequence loss and differentiates through the complete `for_loop`.\n", "\n", "| Online learning | BPTT |\n", "|---|---|\n", - "| `grad(step_loss)` inside `brainstate.transform.scan` | `grad(sequence_loss)` outside `brainstate.transform.for_loop` |\n", + "| `learner.etrace_grad(..., step_fn=step_loss)` drives the sequence | `grad(sequence_loss)` outside `brainstate.transform.for_loop` |\n", "| Eligibility state carries temporal information forward | Reverse mode traverses the unrolled sequence |\n", "| No stored trajectory for the online update | Stores or rematerializes the sequence trajectory |\n", "\n", @@ -380,10 +380,10 @@ "id": "online-bptt-code", "metadata": { "execution": { - "iopub.execute_input": "2026-07-27T03:54:46.648910Z", - "iopub.status.busy": "2026-07-27T03:54:46.648910Z", - "iopub.status.idle": "2026-07-27T03:54:47.436066Z", - "shell.execute_reply": "2026-07-27T03:54:47.436066Z" + "iopub.execute_input": "2026-07-28T15:24:16.896810Z", + "iopub.status.busy": "2026-07-28T15:24:16.896668Z", + "iopub.status.idle": "2026-07-28T15:24:17.865728Z", + "shell.execute_reply": "2026-07-28T15:24:17.864837Z" } }, "outputs": [ @@ -411,7 +411,6 @@ "online_learner = braintrace.compile(\n", " online_model, braintrace.D_RTRL, sequence_inputs[0], batch_size=1\n", ")\n", - "online_weights = online_model.states(brainstate.ParamState)\n", "bptt_weights = bptt_model.states(brainstate.ParamState)\n", "brainstate.nn.init_all_states(bptt_model, batch_size=1)\n", "\n", @@ -422,19 +421,13 @@ "def online_sequence_gradient(inputs, targets):\n", " brainstate.nn.reset_all_states(online_model, batch_size=1)\n", " online_learner.reset_state(batch_size=1)\n", - " zero_grads = jax.tree.map(jnp.zeros_like, online_weights.to_dict_values())\n", - "\n", - " def step(accumulated, sample):\n", - " x, y = sample\n", - " step_grads, step_loss = brainstate.transform.grad(\n", - " online_step_loss, online_weights, return_value=True\n", - " )(x, y)\n", - " accumulated = jax.tree.map(\n", - " lambda total, current: total + current, accumulated, step_grads\n", - " )\n", - " return accumulated, step_loss\n", - "\n", - " return brainstate.transform.scan(step, zero_grads, (inputs, targets))\n", + " # The scan this replaces accumulated the per-step gradients without\n", + " # dividing, which is exactly reduction='sum'. return_value=True keeps the\n", + " # per-step losses the comparison below prints.\n", + " return online_learner.etrace_grad(\n", + " inputs, targets, step_fn=online_step_loss,\n", + " reduction='sum', return_value=True,\n", + " )\n", "\n", "def bptt_sequence_loss(inputs, targets):\n", " brainstate.nn.reset_all_states(bptt_model, batch_size=1)\n", @@ -527,7 +520,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.11.8" + "version": "3.13.11" } }, "nbformat": 4, diff --git a/docs/quickstart/quickstart.ipynb b/docs/quickstart/quickstart.ipynb index 198779c..64d860d 100644 --- a/docs/quickstart/quickstart.ipynb +++ b/docs/quickstart/quickstart.ipynb @@ -16,10 +16,10 @@ "id": "1d85c39c", "metadata": { "execution": { - "iopub.execute_input": "2026-07-27T06:23:31.692310Z", - "iopub.status.busy": "2026-07-27T06:23:31.692310Z", - "iopub.status.idle": "2026-07-27T06:23:35.733682Z", - "shell.execute_reply": "2026-07-27T06:23:35.733682Z" + "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": [ @@ -29,7 +29,7 @@ "SGD(\n", " momentum=0.0,\n", " nesterov=False,\n", - " param_states=,\n", + " param_states=,\n", " weight_decay=0.0,\n", " step_count=OptimState(\n", " value=ShapedArray(int32[], weak_type=True)\n", @@ -64,10 +64,10 @@ " ],\n", " param_groups_opt_states=[],\n", " _schedulers=[],\n", - " _lr_scheduler=,\n", + " _lr_scheduler=,\n", " _base_lr=0.08,\n", " _current_lr=OptimState(...),\n", - " tx=GradientTransformationExtraArgs(init=.init_fn at 0x00000201DFE43740>, update=.update_fn at 0x00000201DFE43560>),\n", + " tx=GradientTransformationExtraArgs(init=.init_fn at 0x779af84f4860>, update=.update_fn at 0x779af84f4a40>),\n", " opt_state=OptimState(\n", " value=(ScaleByScheduleState(count=ShapedArray(int32[])),)\n", " )\n", @@ -85,7 +85,6 @@ "import brainstate\n", "import braintools\n", "import braintrace\n", - "import jax\n", "import jax.numpy as jnp\n", "import matplotlib.pyplot as plt\n", "\n", @@ -131,10 +130,10 @@ "id": "1718c191", "metadata": { "execution": { - "iopub.execute_input": "2026-07-27T06:23:35.735801Z", - "iopub.status.busy": "2026-07-27T06:23:35.735801Z", - "iopub.status.idle": "2026-07-27T06:23:35.741506Z", - "shell.execute_reply": "2026-07-27T06:23:35.741506Z" + "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": [], @@ -147,7 +146,7 @@ "\n", "def evaluate():\n", " reset_sequence()\n", - " predictions = brainstate.transform.for_loop(learner, inputs)\n", + " predictions = learner.etrace_evolve(inputs, return_outputs=True)\n", " return jnp.mean((predictions - targets) ** 2)\n", "\n", "\n", @@ -158,25 +157,13 @@ "\n", "def train_epoch(_):\n", " reset_sequence()\n", - "\n", - " def scan_step(accumulated_grads, sample):\n", - " x, target = sample\n", - " grad_fn = brainstate.transform.grad(\n", - " local_loss, weights, return_value=True\n", - " )\n", - " step_grads, step_loss = grad_fn(x, target)\n", - " accumulated_grads = jax.tree.map(\n", - " lambda total, current: total + current,\n", - " accumulated_grads,\n", - " step_grads,\n", - " )\n", - " return accumulated_grads, step_loss\n", - "\n", - " zero_grads = jax.tree.map(jnp.zeros_like, weights.to_dict_values())\n", - " grads, step_losses = brainstate.transform.scan(\n", - " scan_step, zero_grads, (inputs, targets)\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", - " grads = jax.tree.map(lambda grad: grad / inputs.shape[0], grads)\n", " optimizer.update(grads)\n", " return step_losses.mean()" ] @@ -187,10 +174,10 @@ "id": "3a715e09", "metadata": { "execution": { - "iopub.execute_input": "2026-07-27T06:23:35.743521Z", - "iopub.status.busy": "2026-07-27T06:23:35.743521Z", - "iopub.status.idle": "2026-07-27T06:23:36.458457Z", - "shell.execute_reply": "2026-07-27T06:23:36.458457Z" + "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": [ @@ -204,7 +191,7 @@ }, { "data": { - "image/png": "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LiGoAAAAAOASggoAAAAALiGoAAAAAOASggoAAAAALiGoAACcUXZ2tpkgKTk5+bym8Xbp6enmO+vEgwDgj5j8DgC83M6dO+XPP/886zY9evSQ6tWrl3jfOruqzrS7cuVKM/Pu+Urj7fbu3SuxsbGyadMmM3M1APibYHdnAADgmj179siXX35pe/3zzz9LRESEdO7c2bauZcuWTgUVoaGhMnToUKlcufJ5TQMA8G4EFQDg5S677DKzWHXv3l3q1KkjM2bMsDXNmT9/vtSrV88EIFu2bJF27dpJgwYNZPbs2ZKbmytBQUFSt25ds16DAquQkBAZOHCgqXmw39dVV10liYmJ5s587dq1pW3bti6lsdq2bZts3LhRGjZsKC1atJDPP/9cevfuLVWrVj3j99cmR8uWLZO8vDyzzxo1atjes//sgwcPyubNm81xaN26dZH96PsrVqyQsLAw6dq1q1SsWLHINidOnJDly5ebY9alSxeJjIwsss2OHTvO+h0BwCdZAAA+5bLLLrMMGzbM9johIcGil/urrrrK0qRJE8uQIUMsv/76q3nvlltusQwdOtQyePBg817Tpk0tu3btsqVNTk42aVeuXFlgX1dffbWlWbNmZp8VK1a0jBw50qU0atKkSZbQ0FBLr169LK1bt7ZcccUVJt0ff/xxxu86b948S+XKlS2XXHKJpV+/fpaoqCjLq6++WuS7674aNWpkufzyyy0RERGW++67r8B+3nrrLUu5cuUs3bt3t1x44YWWSpUqWX766acC28ydO9cSHR1tadOmjdlPXFycZcmSJSX6jgDgqwgqAMBPgopBgwZZcnJyzpguNzfXBBg333zzOQOE4cOHm+3V4sWLzbr4+Hin02zbts0SFBRkggSr22677axBxe7duy3ly5e3LFq0yLbu77//toSHh1s2bNhQ4LN79OhhyczMNOtWrVplPuuXX34xr3fs2GGCmRkzZtj2M2bMGEvdunUt6enptm3CwsIsL774om2bw4cPFwkqzvYdAcCXMfoTAPiJ++67zzRzKkyb6nzzzTemqZE2M9ImQOcyYsQICQzM/xOiTYW0ydPWrVudTjNv3jzTHEubTVk99NBDZ92fjrYUHR0tSUlJphmX5l+bT+l3+P333wtsO3r0aFuzrvbt20uvXr1k1qxZ5vXcuXNNk6lhw4bZth8/frxpKrZ06VLbZ1WpUkUeeOAB2zbVqlUz38PV4wIAvoA+FQDgJ2rWrFngdWZmplxzzTUmiOjQoYMpoO/bt08OHz58zn3Zd8IOCAgwBfaMjAyn0yQkJEj9+vULbF/4dWG7du2SnJwc+eKLLwqs79atm8TExJx1XxrA7N692zzXR+3DYU8DiKioKNs2GmDExcXZAgZnviMA+DKCCgDwE1rItffJJ5/Ihg0bTMHZ2in5nXfekccee6zM86aFcR2K1t655rnQTtK6aC3CuRTel762dv7WR63tKDzXhnYAt26jAdfRo0cd/j4A4G9o/gQAfkpHO6pVq1aBUY7mzJnjlrxo7cKaNWtsNQNKR206m379+pnmTosWLSoyQtPx48cLrLMfcleDhR9//NF8prr44otNcGXfTEmbRGnTJes8G3379jWjUq1atarAfnU0KwAANRUA4Ld0mNWnnnpK7r//fjPEqhbiCxeay0qfPn3MsLhaeB81apQprE+dOrXYGhb7oXP/7//+zzTh0jTaPEkDAw0Ivv322wLDvX766admyNnmzZvLlClTTFOw22+/3bzXs2dP05dDP3vs2LEmIHnuuefkiSeesDUZ08kDdXvdRvtn6JwfX331ldxwww0yfPjwMjlGAODJqKkAAB+jhWSdQ8FKJ8LTyegKz6nQpk0bWbJkiY4CaB4vv/xyc0d/8ODBZ5zI7kz7GjJkiJkbw9k0Sgvpd999t/z1118SHBxsXqvi5ouwevPNN00QkZaWZr6Ddp7Wx8aNGxfYTjui64zX2n+kf//+snjx4gLzcWin7X//+9+mtkRnx9Yg5MknnyywDw1GPvzwQ1PDs379ehNcWAMKR78jAPiqAB0Cyt2ZAABA+zXYd3SeNm2ardYiPDzcqQOkAYIGEzrCVdOmTTnIAHCe0FEbAOARnn76aTOakw75qs2Y3njjDVN74GxAAQAoOzR/AgB4hJdeekkuvPBC+fPPP83rBQsWyKOPPurSPs/ULAkAULpo/gQAAADAJdRUAAAAAHAJQQUAAAAAlxBUAAAAACCoAAAAAOA+1FQAAAAAcAlBBQAAAACXEFQAAAAAcAlBBQAAAACXEFQAAAAAEFf8P+/BTTo98i1sAAAAAElFTkSuQmCC", + "image/png": "iVBORw0KGgoAAAANSUhEUgAAAxUAAAGGCAYAAAANcKzOAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjEwLjgsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvwVt1zgAAAAlwSFlzAAAPYQAAD2EBqD+naQAAbOxJREFUeJzt3XlcFPX/B/DX7AK73CinKIKCigdCHiB4liSopWglWnmQ2emJmUeeZV8rS630m18t0/plmmVkaSSRmgqeoGaCihdeXKIsh1y78/sDWF1YleUajtfz8dgHO5/5zGfeg29W3sx8ZgRRFEUQERERERFVkUzqAIiIiIiIqGFjUUFERERERNXCooKIiIiIiKqFRQUREREREVULiwoiIiIiIqoWFhVERERERFQtLCqIiIiIiKhaWFQQEREREVG1sKggIiIiIqJqYVFBRHQfNzc3TJgwQbu8d+9eCIKAvXv3ShZTVW3cuBGCIODy5csGb9uQj1sqEyZMgJubW5W2Xbx4MQRBqNmAKqk6cRMRlWFRQUQN0r///osXX3wRLVu2hEKhgLOzM1544QX8+++/UofWZKlUKrz//vvo0aMHrK2toVAo4OrqitDQUOzcuVOnb1nRUvaSy+VwcHDAs88+i4SEhApjDxgwAF26dNG734yMDAiCgMWLFz80vhs3bmDx4sU4ceJEVQ+RiIgewEjqAIiIDLV9+3aMGTMGzZs3x8SJE9GmTRtcvnwZX331FX788Uds2bIFI0aMqJF99evXD3fv3oWJiUmNjFeXxo4di9GjR0OhUBi8raHHnZSUhKCgIFy5cgUjRozAuHHjYGFhgatXr2LXrl146qmn8M0332Ds2LE6202dOhU9e/ZEUVERTp06hbVr12Lv3r04ffo0nJycDI77YW7cuIElS5bAzc0NPj4+NTo2AKxfvx4ajaZK286fPx9z5syp4YiIiOoOiwoialAuXLiAsWPHom3btvj7779hb2+vXTdt2jT07dsXY8eOxalTp9C2bdtq708mk0GpVFZ7HCnI5XLI5fIqbWvIcRcXF2PEiBFITU3Fvn370Lt3b531ixYtwu7du6FWqyts27dvXzz77LPa5Q4dOuD111/HN998g7fffrtKsdeUvLw8mJmZVbq/sbFxlfdlZGQEIyP+l0xEDRcvfyKiBmX58uXIy8vDunXrdAoKALCzs8P//vc/5Obm4qOPPtK2l12vnpSUhAkTJsDGxgbW1tYICwtDXl7eQ/enb25B2aU4Z86cweOPPw4zMzO0bNlSZ59lCgoKsGjRInh4eEChUMDFxQVvv/02CgoKHnmsZfs5deoU+vfvDzMzM3h4eODHH38EAOzbtw9+fn4wNTVFhw4d8Oeff+psr29OhZubG5566ikcOHAAvr6+UCqVaNu2Lb755ptHHveDbNu2DadPn8aCBQsqFBRlBg0ahMGDBz9yrL59+wIoKR5r0t69e9GzZ08AQFhYmPayq40bNwK4970+fvw4+vXrBzMzM8ybNw8A8Msvv2Do0KFwdnaGQqGAu7s73nvvvQpFUvm5CZcvX4YgCPj444+xbt06uLu7Q6FQoGfPnjh69KjOtvrmVAiCgMmTJyMiIgJdunSBQqFA586dERkZqff4evToAaVSCXd3d/zvf/+r1jyN3NxczJw5Ey4uLlAoFOjQoQM+/vhjiKKo0y8qKgp9+vSBjY0NLCws0KFDB+33rcznn3+Ozp07w8zMDM2aNUOPHj2wefPmKsVFRPUX/yxCRA3Kr7/+Cjc3N+0vn+X169cPbm5uFa7hB4BRo0ahTZs2WLZsGeLi4vDll1/CwcEBH374ocFx3L59G8HBwRg5ciRGjRqFH3/8EbNnz4aXl5f2l2eNRoNhw4bhwIEDeOWVV9CxY0f8888/WLlyJc6dO4eIiIhK7eepp57C6NGj8dxzz+GLL77A6NGj8d1332H69Ol47bXX8Pzzz2P58uV49tlncfXqVVhaWj50zKSkJDz77LOYOHEixo8fjw0bNmDChAno3r07OnfubPD34tdffwUAvPjiiwZvW15ZAdSsWbNqj3W/jh074t1338XChQvxyiuvaPMnICBA2+fWrVsYPHgwRo8ejRdffBGOjo4ASoozCwsLhIeHw8LCAn/99RcWLlwIlUqF5cuXP3LfmzdvRnZ2Nl599VUIgoCPPvoII0eOxMWLFx95duPAgQPYvn073njjDVhaWuKzzz7DM888g+TkZNja2gIA4uPjERwcjBYtWmDJkiVQq9V49913KxTdlSWKIoYNG4Y9e/Zg4sSJ8PHxwR9//IFZs2bh+vXrWLlyJYCSeU1PPfUUunbtinfffRcKhQJJSUk4ePCgdqz169dj6tSpePbZZzFt2jTk5+fj1KlTOHz4MJ5//vkqxUdE9ZRIRNRA3LlzRwQgDh8+/KH9hg0bJgIQVSqVKIqiuGjRIhGA+NJLL+n0GzFihGhra6vT5urqKo4fP167vGfPHhGAuGfPHm1b//79RQDiN998o20rKCgQnZycxGeeeUbb9u2334oymUzcv3+/zj7Wrl0rAhAPHjz40OMo28/mzZu1bYmJiSIAUSaTiYcOHdK2//HHHyIA8euvv9a2ff311yIA8dKlSzrHB0D8+++/tW1paWmiQqEQZ86c+dDjfpDHHntMtLGxqdCek5Mjpqena19ZWVkVxt+wYYOYnp4u3rhxQ4yMjBQ9PDxEQRDEI0eOVPhedO7cWe/+09PTRQDiokWLHhrn0aNHK3yP7h8fgLh27doK6/Ly8iq0vfrqq6KZmZmYn5+vbRs/frzo6uqqXb506ZIIQLS1tRUzMzO17b/88osIQPz111+1bWU5ej8AoomJiZiUlKRtO3nypAhA/Pzzz7VtTz/9tGhmZiZev35d23b+/HnRyMiowpj6lI87IiJCBCAuXbpUp9+zzz4rCoKgjWflypUiADE9Pf2BYw8fPvyB/25E1Ljw8iciajCys7MB4JF/iS9br1KpdNpfe+01neW+ffvi1q1bFfpVhoWFhc5f5k1MTODr64uLFy9q27Zt24aOHTvC09MTGRkZ2tcTTzwBANizZ0+l9jN69GjtcocOHWBjY4OOHTvCz89P2172/v79P0inTp10zvTY29ujQ4cOldpWH5VKBQsLiwrt77zzDuzt7bUvfX+Zfumll2Bvbw9nZ2cEBwcjKysL3377rfZSpbqkUCgQFhZWod3U1FT7Pjs7GxkZGejbty/y8vKQmJj4yHFDQ0N1zryUfe8r8/0ODAyEu7u7drlr166wsrLSbqtWq/Hnn38iJCQEzs7O2n4eHh6VutxMn127dkEul2Pq1Kk67TNnzoQoivj9998BADY2NgBKLg970AR1GxsbXLt2rcLlXkTU+LCoIKIGo6xYKCsuHuRBxUfr1q11lst+0bt9+7bBsbRq1arC9erNmjXTGev8+fP4999/dX6xtre3R/v27QEAaWlpVdqPtbU1XFxcKrRV9ljKfx/0xV5eTk4OUlJStK/09HTtOktLS+Tk5FTY5o033kBUVBSioqK0lxKVt3DhQkRFReHnn3/GuHHjkJWVBZmsav81Vfc5Dy1bttR7t6t///0XI0aMgLW1NaysrGBvb68tKLOysh45bnXy7lH/Vmlpabh79y48PDwq9NPXVhlXrlyBs7NzhZ+fjh07atcDJcVS79698fLLL8PR0RGjR4/GDz/8oFNgzJ49GxYWFvD19UW7du3w5ptv6lweRUSNB+dUEFGDYW1tjRYtWuDUqVMP7Xfq1Cm0bNkSVlZWOu0PuhOSWG7yaWVUZiyNRgMvLy+sWLFCb9/yhYEh+6nOsVRl248//hhLlizRLru6umrnP3h6euLEiRO4fv06WrZsqe3Tvn17bQH1oDtJeXl5ITAwEAAQEhKCvLw8TJo0CX369NH5/iiVSty9e1fvGGWT7at7l677z0iUuXPnDvr37w8rKyu8++67cHd3h1KpRFxcHGbPnl2pW8jW9b9VXTE1NcXff/+NPXv2YOfOnYiMjMTWrVvxxBNPYPfu3ZDL5ejYsSPOnj2L3377DZGRkfjpp5/w3//+FwsXLtTJJyJq+HimgogalKeeegqXLl3CgQMH9K7fv38/Ll++jKeeeqqOI6vI3d0dmZmZGDhwIAIDAyu8OnToIHWIlTZu3DjtWYeoqCh899132nVl3+v726rqgw8+QH5+Pt5//32ddldXV1y9elVvYXH27Fltn4epypmMvXv34tatW9i4cSOmTZuGp556CoGBgTU+kbyqHBwcoFQqkZSUVGGdvrbKcHV1xY0bNyqcESy71Ov+77NMJsPAgQOxYsUKnDlzBu+//z7++usvnUv7zM3NERoaiq+//hrJyckYOnQo3n//feTn51cpPiKqn1hUEFGDMmvWLJiamuLVV1/FrVu3dNZlZmbitddeg5mZGWbNmiVRhPeMGjUK169fx/r16yusu3v3LnJzcyWIqmratm2rUxDdf+vYUaNGoVOnTnjvvfdw6NAhvdtX9i/r7u7ueOaZZ7Bx40akpKRo24cMGYKioiL873//0+mv0WjwxRdfwMTEBAMHDnzo2Obm5gBKzj5UVtmZgvvjLywsxH//+99Kj1Gb5HI5AgMDERERgRs3bmjbk5KStHMfDDVkyBCo1WqsXr1ap33lypUQBEE7VyMzM7PCtmUPFSy7ZXL5n1ETExN06tQJoiiiqKioSvERUf3Ey5+IqEFp164dNm3ahBdeeAFeXl4VnqidkZGB77//Xmdyq1TGjh2LH374Aa+99hr27NmD3r17Q61WIzExET/88AP++OMP9OjRQ+owq83Y2Bg///wzgoKC0KdPH4wcORJ9+/aFubk5rl+/jh07dmj/Ql0Zs2bNwg8//IBVq1bhgw8+AAA8/fTTGDRoEGbMmIEjR44gICAAeXl52LFjBw4ePIilS5c+8haq7u7usLGxwdq1a2FpaQlzc3P4+fmhTZs2D9wmICAAzZo1w/jx4zF16lQIgoBvv/22Xlx+VGbx4sXYvXs3evfujddff11bEHTp0gUnTpwweLynn34ajz/+ON555x1cvnwZ3t7e2L17N3755RdMnz5d+7P17rvv4u+//8bQoUPh6uqKtLQ0/Pe//0WrVq3Qp08fACXPJ3FyckLv3r3h6OiIhIQErF69GkOHDn3kDReIqGFhUUFEDc5zzz0HT09PLFu2TFtI2Nra4vHHH8e8efPQpUsXqUMEUHJpSEREBFauXIlvvvkGP//8M8zMzNC2bVtMmzZNO9+gMWjfvj1OnDiBzz77DD///DN+//13FBYWwtHREX5+fli0aFGlL0nr0aMHBgwYgC+++AJz586FtbU1ZDIZduzYgQ8++ABbtmzB9u3bYWRkBC8vL/zf//0fXnjhhUeOa2xsjE2bNmHu3Ll47bXXUFxcjK+//vqhRYWtrS1+++03zJw5E/Pnz0ezZs3w4osvYuDAgQgKCqr096c2de/eHb///jveeustLFiwAC4uLnj33XeRkJBQqbtTlVf2vV64cCG2bt2Kr7/+Gm5ubli+fDlmzpyp7Tds2DBcvnwZGzZsQEZGBuzs7NC/f38sWbJEe+OAV199Fd999x1WrFiBnJwctGrVClOnTsX8+fNr7PiJqH4QxPr05xYiIiKqESEhIfj3339x/vx5qUMhoiaAcyqIiIgauPIT2M+fP49du3ZhwIAB0gRERE0Oz1QQERE1cC1atMCECRPQtm1bXLlyBV988QUKCgoQHx+Pdu3aSR0eETUBnFNBRETUwAUHB+P7779HSkoKFAoF/P398Z///IcFBRHVGZ6pICIiIiKiauGcCiIiIiIiqhYWFUREREREVC2cU6GHRqPBjRs3YGlpCUEQpA6HiIiIiKhOiKKI7OxsODs7Qyar/PkHFhV63LhxAy4uLlKHQUREREQkiatXr6JVq1aV7s+iQg9LS0sAJd9MKyurOt+/RqNBeno67O3tDaoQqXFjXpA+zAsqjzlB+jAvSB99eaFSqeDi4qL9fbiyWFToUXbJk5WVlWRFRX5+PqysrPiDT1rMC9KHeUHlMSdIH+YF6fOwvDB0CgCzioiIiIiIqoVFBRERERERVQuLCiIiIiIiqhYWFUREREREVC0sKoiIiIiIqFpYVBARERERUbWwqCAiIiIiomqRvKhYs2YN3NzcoFQq4efnhyNHjjy0/7Zt2+Dp6QmlUgkvLy/s2rVLZ31OTg4mT56MVq1awdTUFJ06dcLatWtr8xCIiIiIiJo0SYuKrVu3Ijw8HIsWLUJcXBy8vb0RFBSEtLQ0vf1jYmIwZswYTJw4EfHx8QgJCUFISAhOnz6t7RMeHo7IyEj83//9HxISEjB9+nRMnjwZO3bsqKvDIiIiIiJqUiQtKlasWIFJkyYhLCxMe0bBzMwMGzZs0Nv/008/RXBwMGbNmoWOHTvivffeQ7du3bB69Wptn5iYGIwfPx4DBgyAm5sbXnnlFXh7ez/yDEh9U6TWSB0CEREREVGlSFZUFBYW4vjx4wgMDLwXjEyGwMBAxMbG6t0mNjZWpz8ABAUF6fQPCAjAjh07cP36dYiiiD179uDcuXMYNGhQ7RxIDcspKMaY9YcRtPYk8gqLpQ6HiIiIiOiRjKTacUZGBtRqNRwdHXXaHR0dkZiYqHeblJQUvf1TUlK0y59//jleeeUVtGrVCkZGRpDJZFi/fj369ev3wFgKCgpQUFCgXVapVAAAjUYDjaZuzxiYGgm4mpmHvCINjlzKxIAODnW6f6q/NBoNRFGs85yk+o15QeUxJ0gf5gXpoy8vqpojkhUVteXzzz/HoUOHsGPHDri6uuLvv//Gm2++CWdn5wpnOcosW7YMS5YsqdCenp6O/Pz82g65gsdamuFGVj7+/OcqOjWr891TPaXRaJCVlQVRFCGTSX6PBaonmBdUHnOC9GFekD768iI7O7tKY0lWVNjZ2UEulyM1NVWnPTU1FU5OTnq3cXJyemj/u3fvYt68efj5558xdOhQAEDXrl1x4sQJfPzxxw8sKubOnYvw8HDtskqlgouLC+zt7WFlZVXlY6yqJzoVYueZTJy4eRcODjxTQSU0Gg0EQYC9vT3/QyAt5gWVx5wgfZgXpI++vFAqlVUaS7KiwsTEBN27d0d0dDRCQkIAlBxYdHQ0Jk+erHcbf39/REdHY/r06dq2qKgo+Pv7AwCKiopQVFRU4YdFLpc/9FSOQqGAQqGo0C6TyST5wevtYQcASEjJRtbdYjQzN6nzGKh+EgRBsryk+ot5QeUxJ0gf5gXpUz4vqpofkl7+FB4ejvHjx6NHjx7w9fXFqlWrkJubi7CwMADAuHHj0LJlSyxbtgwAMG3aNPTv3x+ffPIJhg4dii1btuDYsWNYt24dAMDKygr9+/fHrFmzYGpqCldXV+zbtw/ffPMNVqxYIdlxGsrBSom2tkpcvJWP2Iu3MMSrhdQhERERERE9kKRFRWhoKNLT07Fw4UKkpKTAx8cHkZGR2snYycnJOtVSQEAANm/ejPnz52PevHlo164dIiIi0KVLF22fLVu2YO7cuXjhhReQmZkJV1dXvP/++3jttdfq/Piqo4eLFS7eysfBpAwWFURERERUrwmiKIpSB1HfqFQqWFtbIysrS5I5FRqNBj/GnsPbv15AGztz7HlrQJ3HQPWPRqNBWloaHBwceOqatJgXVB5zgvRhXpA++vKiqr8HM6vqqW6tLCETgEsZubhx567U4RARERERPRCLinrKQiFH11bWAICDSRkSR0NERERE9GAsKuqxAPeSu0DFXLglcSRERERERA/GoqIeC3C3BVBypoJTX4iIiIiovmJRUY91b20DhZEMadkFSErLkTocIiIiIiK9WFTUYwpjOXq4NQPAeRVEREREVH+xqKjnyuZVHOS8CiIiIiKqp1hU1HN9PEqKikMXb6FYrZE4GiIiIiKiilhU1HNdWlrDSmmE7PxinL6hkjocIiIiIqIKWFTUc3KZgF5t790FioiIiIiovmFR0QD09ih7XgWLCiIiIiKqf1hUNAC9PUrOVBy7fBv5RWqJoyEiIiIi0sWiogFwt7eAg6UCBcUaxF25LXU4REREREQ6WFQ0AIIgaC+BOshLoIiIiIionmFR0UAEuJdcAnUgic+rICIiIqL6hUVFA1F2puKfa3eQdbdI4miIiIiIiO5hUdFAONuYoo2dOTQicPgiz1YQERERUf3BoqIBKbsLVMwFFhVEREREVH+wqGhAeruXTtbmQ/CIiIiIqB5hUdGA+LvbQhCA82k5SFPlSx0OEREREREAFhUNio2ZCTo7WwHgJVBEREREVH+wqGhgeAkUEREREdU3LCoamIDSW8vGXLgFURQljoaIiIiIiEVFg9PTrRmM5QKu37mLK7fypA6HiIiIiIhFRUNjZmKEx1o3AwAc4CVQRERERFQPsKhogMrmVcRcYFFBRERERNJjUdEAlT0EL/bCLWg0nFdBRERERNJiUdEAebvYwNxEjtt5RThzUyV1OERERETUxNWLomLNmjVwc3ODUqmEn58fjhw58tD+27Ztg6enJ5RKJby8vLBr1y6d9YIg6H0tX768Ng+jzhjLZfBrW3K2gpdAEREREZHUJC8qtm7divDwcCxatAhxcXHw9vZGUFAQ0tLS9PaPiYnBmDFjMHHiRMTHxyMkJAQhISE4ffq0ts/Nmzd1Xhs2bIAgCHjmmWfq6rBqXYB7SVFxMIkPwSMiIiIiaUleVKxYsQKTJk1CWFgYOnXqhLVr18LMzAwbNmzQ2//TTz9FcHAwZs2ahY4dO+K9995Dt27dsHr1am0fJycnndcvv/yCxx9/HG3btq2rw6p1vUufV3HkUiYKizUSR0NERERETZmRlDsvLCzE8ePHMXfuXG2bTCZDYGAgYmNj9W4TGxuL8PBwnbagoCBERETo7Z+amoqdO3di06ZND4yjoKAABQUF2mWVqmSegkajgUZT97+wazQaiKL40H23szeHrbkJbuUWIu5KJnzbNK/DCEkKlckLanqYF1Qec4L0YV6QPvryoqo5ImlRkZGRAbVaDUdHR512R0dHJCYm6t0mJSVFb/+UlBS9/Tdt2gRLS0uMHDnygXEsW7YMS5YsqdCenp6O/Pz8Rx1GjdNoNMjKyoIoipDJHnwy6bGW5vjzXCGiTiXDzby4DiMkKVQ2L6hpYV5QecwJ0od5Qfroy4vs7OwqjSVpUVEXNmzYgBdeeAFKpfKBfebOnatz9kOlUsHFxQX29vawsrKqizB1aDQaCIIAe3v7h/7gP9G5AH+eu42TKflwcHCowwhJCpXNC2pamBdUHnOC9GFekD768uJhvzM/jKRFhZ2dHeRyOVJTU3XaU1NT4eTkpHcbJyenSvffv38/zp49i61btz40DoVCAYVCUaFdJpNJ9oMnCMIj99/Hwx4AcOLqHdwt0sBc0ehrxCavMnlBTQ/zgspjTpA+zAvSp3xeVDU/JM0qExMTdO/eHdHR0do2jUaD6Oho+Pv7693G399fpz8AREVF6e3/1VdfoXv37vD29q7ZwOuJ1rZmaNXMFMUaEUcuZUodDhERERE1UZKXquHh4Vi/fj02bdqEhIQEvP7668jNzUVYWBgAYNy4cToTuadNm4bIyEh88sknSExMxOLFi3Hs2DFMnjxZZ1yVSoVt27bh5ZdfrtPjqWu93UvuAnUwic+rICIiIiJpSH69TGhoKNLT07Fw4UKkpKTAx8cHkZGR2snYycnJOqdhAgICsHnzZsyfPx/z5s1Du3btEBERgS5duuiMu2XLFoiiiDFjxtTp8dS13u3ssPXYVRy8wOdVEBEREZE0BFEURamDqG9UKhWsra2RlZUl2UTttLQ0ODg4PPK6toycAvRY+icA4Pj8QNhaVJwbQo2DIXlBTQfzgspjTpA+zAvSR19eVPX3YGZVA2dnoYCnkyUAIPYiz1YQERERUd1jUdEIBGjnVbCoICIiIqK6x6KiEejtYQsAiLnAydpEREREVPdYVDQCvm2aQy4TcOVWHq7dzpM6HCIiIiJqYlhUNAKWSmN4t7IGAMTwEigiIiIiqmMsKhqJ3h4l8yoO8HkVRERERFTHWFQ0EmWTtWMu3ALvEkxEREREdYlFRSPRzdUGSmMZMnIKcC41R+pwiIiIiKgJYVHRSCiM5Ojp1hwAcJCXQBERERFRHWJR0YiUzavgrWWJiIiIqC6xqGhEepfOqzh8MRPFao3E0RARERFRU8GiohHp5GwFa1NjZBcU49T1LKnDISIiIqImgkVFIyKXCfBvW/p0bc6rICIiIqI6wqKikentUVJUHORD8IiIiIiojrCoaGQCSidrH79yG3cL1RJHQ0RERERNAYuKRqatnTmcrJQoVGtw7Eqm1OEQERERURPAoqKREQQBAbwEioiIiIjqEIuKRqgPn1dBRERERHWIRUUjVPYQvH+uZyErr0jiaIiIiIiosWNR0Qg5Winhbm8OUQRiL/ISKCIiIiKqXSwqGqnevASKiIiIiOoIi4pGKsC9pKg4yIfgEREREVEtY1HRSPm3tYVMAC6k5yIlK1/qcIiIiIioEat2UaFWq3HixAncvn27JuKhGmJtZowuLa0B8BIoIiIiIqpdBhcV06dPx1dffQWgpKDo378/unXrBhcXF+zdu7em46NquHcJFCdrExEREVHtMbio+PHHH+Ht7Q0A+PXXX3Hp0iUkJiZixowZeOedd2o8QKq63tqH4GVAFEWJoyEiIiKixsrgoiIjIwNOTk4AgF27duG5555D+/bt8dJLL+Gff/6p8QCp6nq4NoeJXIYUVT4uZuRKHQ4RERERNVIGFxWOjo44c+YM1Go1IiMj8eSTTwIA8vLyIJfLazxAqjpTEzm6uzYDAMTwLlBEREREVEsMLirCwsIwatQodOnSBYIgIDAwEABw+PBheHp6GhzAmjVr4ObmBqVSCT8/Pxw5cuSh/bdt2wZPT08olUp4eXlh165dFfokJCRg2LBhsLa2hrm5OXr27Ink5GSDY2sM7l0CxXkVRERERFQ7DC4qFi9ejC+//BKvvPIKDh48CIVCAQCQy+WYM2eOQWNt3boV4eHhWLRoEeLi4uDt7Y2goCCkpaXp7R8TE4MxY8Zg4sSJiI+PR0hICEJCQnD69GltnwsXLqBPnz7w9PTE3r17cerUKSxYsABKpdLQQ20UAkofghd78RbUGs6rICIiIqKaJ4g1MIP3zp07sLGxMXg7Pz8/9OzZE6tXrwYAaDQauLi4YMqUKXoLlNDQUOTm5uK3337TtvXq1Qs+Pj5Yu3YtAGD06NEwNjbGt99+W7WDAaBSqWBtbY2srCxYWVlVeZyq0mg0SEtLg4ODA2Sy6t31t1itwWPvRiG7oBi/Tu4Dr1bWNRQl1bWazAtqPJgXVB5zgvRhXpA++vKiqr8HGxm68w8//BBubm4IDQ0FAIwaNQo//fQTWrRogV27dqFr166VGqewsBDHjx/H3LlztW0ymQyBgYGIjY3Vu01sbCzCw8N12oKCghAREQGg5Buzc+dOvP322wgKCkJ8fDzatGmDuXPnIiQk5IGxFBQUoKCgQLusUqm042k0mkodT03SaDQQRbFG9i0TAN82zRGdmIYDSeno7GxZAxGSFGoyL6jxYF5QecwJ0od5Qfroy4uq5ojBRcXatWvx3XffAQCioqIQFRWF33//HT/88APeeust7N69u1LjZGRkQK1Ww9HRUafd0dERiYmJerdJSUnR2z8lJQUAkJaWhpycHHzwwQdYunQpPvzwQ0RGRmLkyJHYs2cP+vfvr3fcZcuWYcmSJRXa09PTkZ9f90+j1mg0yMrKgiiKNfLXhK6OJohOBPaeuYkRnhY1ECFJoabzghoH5gWVx5wgfZgXpI++vMjOzq7SWAYXFSkpKXBxcQEA/Pbbbxg1ahQGDRoENzc3+Pn5VSmImlJWWQ0fPhwzZswAAPj4+CAmJgZr1659YFExd+5cnTMgKpUKLi4usLe3l+zyJ0EQYG9vXyM/+IO8TbFy3zWcvJkD6+a2UBjxLl0NUU3nBTUOzAsqjzlB+jAvSB99eVHVecgGFxXNmjXD1atX4eLigsjISCxduhQAIIoi1Gp1pcexs7ODXC5HamqqTntqaqr2ORjlOTk5PbS/nZ0djIyM0KlTJ50+HTt2xIEDBx4Yi0Kh0E44v59MJpPsB08QhBrbv2cLK9hZKJCRU4CT11To1da2BiIkKdRkXlDjwbyg8pgTpA/zgvQpnxdVzQ+Dtxo5ciSef/55PPnkk7h16xYGDx4MAIiPj4eHh0elxzExMUH37t0RHR2tbdNoNIiOjoa/v7/ebfz9/XX6AyWXYJX1NzExQc+ePXH27FmdPufOnYOrq2ulY2tsBEFAgPu9p2sTEREREdUkg89UrFy5Em5ubrh69So++ugjWFiUXKN/8+ZNvPHGGwaNFR4ejvHjx6NHjx7w9fXFqlWrkJubi7CwMADAuHHj0LJlSyxbtgwAMG3aNPTv3x+ffPIJhg4dii1btuDYsWNYt26ddsxZs2YhNDQU/fr1w+OPP47IyEj8+uuv2Lt3r6GH2qj09rDFjpM3cDApAzMHdZA6HCIiIiJqRAwuKoyNjfHWW29VaC+bw2CI0NBQpKenY+HChUhJSYGPjw8iIyO1k7GTk5N1TsEEBARg8+bNmD9/PubNm4d27dohIiICXbp00fYZMWIE1q5di2XLlmHq1Kno0KEDfvrpJ/Tp08fg+BqT3qXPqzh5LQvZ+UWwVBpLHBERERERNRZVek7FhQsXsGrVKiQkJAAAOnXqhOnTp6Nt27Y1HqAUGtNzKu7Xf/keXLmVh6/G98DAjo6P3oDqFd5jnPRhXlB5zAnSh3lB+tTkcyoMzqo//vgDnTp1wpEjR9C1a1d07doVhw8fRqdOnRAVFWXocFSHAtxLzlYcTLolcSRERERE1JgYfPnTnDlzMGPGDHzwwQcV2mfPno0nn3yyxoKjmtXbwxbfH0lGzAVO1iYiIiKimmPwmYqEhARMnDixQvtLL72EM2fO1EhQVDv8S28lm5iSjYycgkf0JiIiIiKqHIOLCnt7e5w4caJC+4kTJ+Dg4FATMVEtsbVQoGOLkmvjYi7wEigiIiIiqhkGX/40adIkvPLKK7h48SICAgIAAAcPHsSHH36o81Rqqp96u9si4aYKMUkZGObtLHU4RERERNQIGFxULFiwAJaWlvjkk08wd+5cAICzszMWL16MqVOn1niAVLN6e9jhywOXcIAPwSMiIiKiGmJwUSEIAmbMmIEZM2YgOzsbAGBpaVnjgVHt8G3THEYyAddu30XyrTy0tjWTOiQiIiIiauCqdaNiS0tLFhQNjLnCCD4uNgCAg7wLFBERERHVgEqdqXjssccgCEKlBoyLi6tWQFT7envY4diV2ziYlIExvq2lDoeIiIiIGrhKFRUhISG1HAbVpd4edvg0+jxiL9yCRiNCJqtcwUhEREREpE+liopFixbVdhxUh3xcbGBqLMet3EKcTc3W3maWiIiIiKgqqjWnghomEyMZfNs0BwAc5F2giIiIiKiaWFQ0Ub09Sp6uzYfgEREREVF1sahoogLc7QAAhy/eQpFaI3E0RERERNSQsahoojq1sEIzM2PkFqpx6todqcMhIiIiogasykVFYWEhzp49i+Li4pqMh+qITCbA373kEqgD53kJFBERERFVncFFRV5eHiZOnAgzMzN07twZycnJAIApU6bggw8+qPEAqfaUXQLFydpEREREVB0GFxVz587FyZMnsXfvXiiVSm17YGAgtm7dWqPBUe3q394eAHD0SiaSb+VJHA0RERERNVQGFxURERFYvXo1+vTpo/OU7c6dO+PChQs1GhzVLpfmZujbzg6iCHx76LLU4RARERFRA2VwUZGeng4HB4cK7bm5uTpFBjUMEwLcAABbj15FXiHnxxARERGR4QwuKnr06IGdO3dql8sKiS+//BL+/v41FxnViQEdHNC6uRlU+cWIiL8hdThERERE1AAZGbrBf/7zHwwePBhnzpxBcXExPv30U5w5cwYxMTHYt29fbcRItUguEzDO3xVLdyZgU8xljPF14RknIiIiIjKIwWcq+vTpgxMnTqC4uBheXl7YvXs3HBwcEBsbi+7du9dGjFTLnuvhAlNjOc6mZuPQxUypwyEiIiKiBsbgMxUA4O7ujvXr19d0LCQRa1NjjOjWEpsPJ2NTzGXt8yuIiIiIiCrD4DMVu3btwh9//FGh/Y8//sDvv/9eI0FR3Rvv7wYA2H0mBdfv3JU2GCIiIiJqUAwuKubMmQO1Wl2hXRRFzJkzp0aCorrXwckS/m1toRGB/zt0RepwiIiIiKgBMbioOH/+PDp16lSh3dPTE0lJSTUSFEljfOntZbccSUZ+UcXCkYiIiIhIH4OLCmtra1y8eLFCe1JSEszNzasUxJo1a+Dm5galUgk/Pz8cOXLkof23bdsGT09PKJVKeHl5YdeuXTrrJ0yYAEEQdF7BwcFViq0pCezogJY2pridV4QdJ3l7WSIiIiKqHIOLiuHDh2P69Ok6T89OSkrCzJkzMWzYMIMD2Lp1K8LDw7Fo0SLExcXB29sbQUFBSEtL09s/JiYGY8aMwcSJExEfH4+QkBCEhITg9OnTOv2Cg4Nx8+ZN7ev77783OLamxkguw4u9XAEAm2IuQxRFiSMiIiIioobA4KLio48+grm5OTw9PdGmTRu0adMGHTt2hK2tLT7++GODA1ixYgUmTZqEsLAwdOrUCWvXroWZmRk2bNigt/+nn36K4OBgzJo1Cx07dsR7772Hbt26YfXq1Tr9FAoFnJyctK9mzZoZHFtTNLqnCxRGMvx7Q4XjV25LHQ4RERERNQBVuvwpJiYGO3fuxBtvvIGZM2ciOjoaf/31F2xsbAwaq7CwEMePH0dgYOC9gGQyBAYGIjY2Vu82sbGxOv0BICgoqEL/vXv3wsHBAR06dMDrr7+OW7duGRRbU9XM3ATDfZwBABtjLksbDBERERE1CFV6ToUgCBg0aBAGDRpUrZ1nZGRArVbD0dFRp93R0RGJiYl6t0lJSdHbPyUlRbscHByMkSNHok2bNrhw4QLmzZuHwYMHIzY2FnK5vMKYBQUFKCgo0C6rVCoAgEajgUajqfLxVZVGo4EoipLsGwDG9XLFD8euIfJ0Cm7eyYOjlVKSOEiX1HlB9RPzgspjTpA+zAvSR19eVDVHqlRUREdHIzo6GmlpaRV2/KDLlurS6NGjte+9vLzQtWtXuLu7Y+/evRg4cGCF/suWLcOSJUsqtKenpyM/P79WY9VHo9EgKysLoihCJjP4ZFK12RkB3s4WOHkjB+v3JOIVf+c6j4EqkjovqH5iXlB5zAnSh3lB+ujLi+zs7CqNZXBRsWTJErz77rvo0aMHWrRoAUEQqrRjALCzs4NcLkdqaqpOe2pqKpycnPRu4+TkZFB/AGjbti3s7OyQlJSkt6iYO3cuwsPDtcsqlQouLi6wt7eHlZWVIYdUIzQaDQRBgL29vWQ/+C/3U2PKlhP45fQtzBrqBYVRxTM8VLfqQ15Q/cO8oPKYE6QP84L00ZcXSmXVrlAxuKhYu3YtNm7ciLFjx1Zph/czMTFB9+7dER0djZCQEAAlBxcdHY3Jkyfr3cbf3x/R0dGYPn26ti0qKgr+/v4P3M+1a9dw69YttGjRQu96hUIBhUJRoV0mk0n2gycIgqT7D/ZqAaddiUhR5SPy31SMeKyVJHGQLqnzguon5gWVx5wgfZgXpE/5vKhqfhi8VWFhIQICAqq0M33Cw8Oxfv16bNq0CQkJCXj99deRm5uLsLAwAMC4ceMwd+5cbf9p06YhMjISn3zyCRITE7F48WIcO3ZMW4Tk5ORg1qxZOHToEC5fvozo6GgMHz4cHh4eCAoKqrG4GztjuQwv+LUGAGyM4RO2iYiIiOjBDC4qXn75ZWzevLnGAggNDcXHH3+MhQsXwsfHBydOnEBkZKR2MnZycjJu3ryp7R8QEIDNmzdj3bp18Pb2xo8//oiIiAh06dIFACCXy3Hq1CkMGzYM7du3x8SJE9G9e3fs379f79kIerAxfq1hIpfh5NU7OHH1jtThEBEREVE9JYgGPuFs2rRp+Oabb9C1a1d07doVxsbGOutXrFhRowFKQaVSwdraGllZWZLNqUhLS4ODg4PkpyjDt57A9vjrGPFYS6wM9ZE0lqauPuUF1R/MCyqPOUH6MC9IH315UdXfgw2eU3Hq1Cn4+PgAQIWnWFdn0jbVT+MD3LA9/jp+O3UD84Z0hL0lz/YQERERkS6Di4o9e/bURhxUT3m72MDHxQYnrt7B90eSMXVgO6lDIiIiIqJ6psrnv5KSkvDHH3/g7t27AAADr6KiBmRCgBsA4LvDV1Ck5kNziIiIiEiXwUXFrVu3MHDgQLRv3x5DhgzRTqKeOHEiZs6cWeMBkvSGeLWAnYUCqaoCRJ5OefQGRERERNSkGFxUzJgxA8bGxkhOToaZmZm2PTQ0FJGRkTUaHNUPJkYyPF96e9lNMZelDYaIiIiI6h2Di4rdu3fjww8/RKtWug9Da9euHa5c4fMMGqsX/FrDSCbg2JXbOH09S+pwiIiIiKgeMbioyM3N1TlDUSYzM5PPgWjEHK2UGOxV8kRynq0gIiIiovsZXFT07dsX33zzjXZZEARoNBp89NFHePzxx2s0OKpfJgS4AgB+OXkDmbmFEkdDRERERPWFwbeU/eijjzBw4EAcO3YMhYWFePvtt/Hvv/8iMzMTBw8erI0YqZ7o1roZurS0wunrKmw5mow3BnhIHRIRERER1QMGn6no0qULzp07hz59+mD48OHIzc3FyJEjER8fD3d399qIkeoJQRAw3t8NAPB/sVdQzNvLEhERERGqcKYCAKytrfHOO+/UdCzUADzt7YxlvyfiRlY+/kxIRXCXFlKHREREREQSM7io+Pvvvx+6vl+/flUOhuo/pbEco3u64L97L2BjzGUWFURERERkeFExYMCACm2CIGjfq9XqagVE9d+LvVzxv78v4tDFTCSmqODpZCV1SEREREQkIYPnVNy+fVvnlZaWhsjISPTs2RO7d++ujRipnnG2McWgTo4AgE0xfDYJERERUVNn8JkKa2vrCm1PPvkkTExMEB4ejuPHj9dIYFS/jQ9ww++nUxARfx1zgj1hbWYsdUhEREREJBGDz1Q8iKOjI86ePVtTw1E959emOTydLHG3SI0fjl2VOhwiIiIikpDBZypOnTqlsyyKIm7evIkPPvgAPj4+NRUX1XOCIGB8gBvmbv8H3xy6jJf6tIFcJjx6QyIiIiJqdAwuKnx8fCAIAkRR1Gnv1asXNmzYUGOBUf0X4tMSH/yeiKuZd7EnMQ2BpfMsiIiIiKhpMbiouHTpks6yTCaDvb09lEpljQVFDYOpiRyhPV2w7u+L2BR7mUUFERERURNlcFHh6upaG3FQAzW2lyu+3H8R+89nICktBx4OFlKHRERERER1zOCi4rPPPqt036lTpxo6PDUwLs3NMLCjI6LOpOKb2Mt4d3gXqUMiIiIiojpmcFGxcuVKpKenIy8vDzY2NgCAO3fuwMzMDPb29tp+giCwqGgiJgS4IepMKn46fg2zgjrAUsnbyxIRERE1JQbfUvb999+Hj48PEhISkJmZiczMTCQkJKBbt25YunQpLl26hEuXLuHixYu1ES/VQwHutmjnYIHcQjV+PH5N6nCIiIiIqI4ZXFQsWLAAn3/+OTp06KBt69ChA1auXIn58+fXaHDUMAiCgHEBbgCAb2KvQKMRH74BERERETUqBhcVN2/eRHFxcYV2tVqN1NTUGgmKGp6Rj7WEpdIIlzJy8ff5dKnDISIiIqI6ZHBRMXDgQLz66quIi4vTth0/fhyvv/46AgMDazQ4ajjMFUZ4rrsLAGBTzGVpgyEiIiKiOmVwUbFhwwY4OTmhR48eUCgUUCgU8PX1haOjI7788svaiJEaiHH+rhAEYO+5dFzOyJU6HCIiIiKqIwbf/cne3h67du3CuXPnkJiYCADw9PRE+/btazw4aljc7MwxoL099pxNxzexV7Dw6U5Sh0REREREdcDgMxVl3Nzc0KFDBwwZMqTaBcWaNWvg5uYGpVIJPz8/HDly5KH9t23bBk9PTyiVSnh5eWHXrl0P7Pvaa69BEASsWrWqWjFS5YwvnbC97dhV5BZUnHtDRERERI2PwUVFXl4eJk6cCDMzM3Tu3BnJyckAgClTpuCDDz4wOICtW7ciPDwcixYtQlxcHLy9vREUFIS0tDS9/WNiYjBmzBhMnDgR8fHxCAkJQUhICE6fPl2h788//4xDhw7B2dnZ4Lioavq1s0cbO3NkFxRje/x1qcMhIiIiojpgcFExd+5cnDx5Env37oVSqdS2BwYGYuvWrQYHsGLFCkyaNAlhYWHo1KkT1q5dCzMzM2zYsEFv/08//RTBwcGYNWsWOnbsiPfeew/dunXD6tWrdfpdv34dU6ZMwXfffQdjYz6Mra7IZALG+bsCAL6JuQxR5O1liYiIiBo7g4uKiIgIrF69Gn369IEgCNr2zp0748KFCwaNVVhYiOPHj+vcNUomkyEwMBCxsbF6t4mNja1wl6mgoCCd/hqNBmPHjsWsWbPQuXNng2Ki6nu2eyuYm8hxPi0HMRduSR0OEREREdUygydqp6enw8HBoUJ7bm6uTpFRGRkZGVCr1XB0dNRpd3R01E4CLy8lJUVv/5SUFO3yhx9+CCMjI0ydOrVScRQUFKCgoEC7rFKpAJQUJxqNplJj1CSNRgNRFCXZd00wN5FjZLeW+PZQMjYevAT/ts2lDqlRaOh5QbWDeUHlMSdIH+YF6aMvL6qaIwYXFT169MDOnTsxZcoUANAWEl9++SX8/f2rFERNOn78OD799FPExcVVushZtmwZlixZUqE9PT0d+fn5NR3iI2k0GmRlZUEURchkVZ5LL6mh7S3x7SEgOjENJ85fhbO1QuqQGrzGkBdU85gXVB5zgvRhXpA++vIiOzu7SmMZXFT85z//weDBg3HmzBkUFxfj008/xZkzZxATE4N9+/YZNJadnR3kcnmFJ3GnpqbCyclJ7zZOTk4P7b9//36kpaWhdevW2vVqtRozZ87EqlWrcPny5Qpjzp07F+Hh4dpllUoFFxcX2Nvbw8rKyqBjqgkajQaCIMDe3r7B/uA7OAB9PFJwIOkWIpNyMWewi9QhNXiNIS+o5jEvqDzmBOnDvCB99OXF/XOmDWFwUdGnTx+cOHECH3zwAby8vLB7925069YNsbGx8PLyMmgsExMTdO/eHdHR0QgJCQFQcnDR0dGYPHmy3m38/f0RHR2N6dOna9uioqK0Z0nGjh2rd87F2LFjERYWpnfMsof4lSeTyST7wRMEQdL914QJAW1wIOkWth67hhlPdoCpiVzqkBq8xpAXVPOYF1Qec4L0YV6QPuXzoqr5YXBRAQDu7u5Yv359lXZYXnh4OMaPH48ePXrA19cXq1atQm5urrYAGDduHFq2bIlly5YBAKZNm4b+/fvjk08+wdChQ7FlyxYcO3YM69atAwDY2trC1tZWZx/GxsZwcnJChw4daiRmqpzHPR3g0twUVzPv4pcT1zHat/WjNyIiIiKiBsfgUiQuLg7//POPdvmXX35BSEgI5s2bh8LCQoMDCA0Nxccff4yFCxfCx8cHJ06cQGRkpHYydnJyMm7evKntHxAQgM2bN2PdunXw9vbGjz/+iIiICHTp0sXgfVPtkssEjOvlBgDYyNvLEhERETVagmjgb3o9e/bEnDlz8Mwzz+DixYvo1KkTRo4ciaNHj2Lo0KGN4snVKpUK1tbWyMrKkmxORVpaGhwcHBr8KcqsvCL0WhaNu0VqbH2lF/za2j56I9KrMeUF1RzmBZXHnCB9mBekj768qOrvwQZn1blz5+Dj4wMA2LZtG/r374/Nmzdj48aN+Omnnwwdjho5azNjhDzWEgCwKfaytMEQERERUa0wuKi4/162f/75J4YMGQIAcHFxQUZGRs1GR43C+ICSJ2z/8W8qbty5K3E0RERERFTTDC4qevTogaVLl+Lbb7/Fvn37MHToUADApUuXKjyUjggAPJ2s0Kttc6g1Ir46cEnqcIiIiIiohhlcVKxatQpxcXGYPHky3nnnHXh4eAAAfvzxRwQEBNR4gNQ4vNrfHQDw9cFLOH4lU+JoiIiIiKgmGXxL2a5du+rc/anM8uXLIZfzOQSk3+MdHDDysZbYHn8d4T+cxK6pfWGuqNIdjYmIiIionqmx6f9KpRLGxsY1NRw1QouGdYaztRJXbuVh2e8JUodDRERERDWE9xSjOmNtaozlz3kDAP7vUDL2nUuXOCIiIiIiqgksKqhO9faww4QANwDA2z+exJ08wx+YSERERET1C4sKqnOzgz3R1t4cqaoCLPjlX6nDISIiIqJqYlFBdc7URI4Vo3wglwn49eQN7Dh5Q+qQiIiIiKgaDL79jlqtxsaNGxEdHY20tDTtg/DK/PXXXzUWHDVePi42ePNxD3wWfR4LIk7Dr01zOFoppQ6LiIiIiKrA4KJi2rRp2LhxI4YOHYouXbpAEITaiIuagClPeOCvxFScvq7C2z+ewsawnswnIiIiogbI4KJiy5Yt+OGHHzBkyJDaiIeaEGO5DCtH+WDo5wew71w6Nh9Jxgt+rlKHRUREREQGMnhOhYmJifYp2kTV1c7RErODPQEAS39LwOWMXIkjIiIiIiJDGVxUzJw5E59++ilEUayNeKgJCgtwQ6+2zXG3SI2Z205CrWFuERERETUkBl/+dODAAezZswe///47OnfuXOEp2tu3b6+x4KhpkMkEfPycN4JX7cfxK7ex7u+LeH2Au9RhEREREVElGVxU2NjYYMSIEbURCzVhrZqZYdHTnTDrx1NYEXUWAzrYo2MLK6nDIiIiIqJKMLio+Prrr2sjDiI8270Vdp9JRdSZVMzYegK/TO4NhZFc6rCIiIiI6BH48DuqNwRBwLKRXrA1N0FiSjZWRp2XOiQiIiIiqgSDz1QAwI8//ogffvgBycnJKCws1FkXFxdXI4FR02RnocD7I7zw2v8dx//+voCBHR3Q06251GERERER0UMYfKbis88+Q1hYGBwdHREfHw9fX1/Y2tri4sWLGDx4cG3ESE1McBcnPNOtFUQRmPnDSeQWFEsdEhERERE9hMFFxX//+1+sW7cOn3/+OUxMTPD2228jKioKU6dORVZWVm3ESE3QomGd0NLGFMmZeXh/V4LU4RARERHRQxhcVCQnJyMgIAAAYGpqiuzsbADA2LFj8f3339dsdNRkWSmNsfy5rgCAzYeTsedsmsQREREREdGDGFxUODk5ITMzEwDQunVrHDp0CABw6dIlPhCPalSAux1e6t0GADD7x1O4nVv4iC2IiIiISAoGFxVPPPEEduzYAQAICwvDjBkz8OSTTyI0NJTPr6Aa93ZwB7jbmyMtuwALfjktdThEREREpIfBd39at24dNBoNAODNN9+Era0tYmJiMGzYMLz66qs1HiA1bUpjOVaG+mDEf2Pw26mbGNT5BoZ5O0sdFhERERHdx+CiQiaTQSa7d4Jj9OjRGD16dI0GRXS/rq1sMOUJD6z68zwWRJyGr1tzOFkrpQ6LiIiIiEpV6eF3+/fvx4svvgh/f39cv34dAPDtt9/iwIEDNRocUZk3H/dA11bWyLpbhLd/OsX5O0RERET1iMFFxU8//YSgoCCYmpoiPj4eBQUFAICsrCz85z//qVIQa9asgZubG5RKJfz8/HDkyJGH9t+2bRs8PT2hVCrh5eWFXbt26axfvHgxPD09YW5ujmbNmiEwMBCHDx+uUmxUPxjLZVgxygcKIxn+PpeO7w4nSx0SEREREZUyuKhYunQp1q5di/Xr18PY2Fjb3rt37yo9TXvr1q0IDw/HokWLEBcXB29vbwQFBSEtTf8tRGNiYjBmzBhMnDgR8fHxCAkJQUhICE6fvjeJt3379li9ejX++ecfHDhwAG5ubhg0aBDS09MNjo/qDw8HC8wZ7AkAeH9nAi5l5EocEREREREBVSgqzp49i379+lVot7a2xp07dwwOYMWKFZg0aRLCwsLQqVMnrF27FmZmZtiwYYPe/p9++imCg4Mxa9YsdOzYEe+99x66deuG1atXa/s8//zzCAwMRNu2bdG5c2esWLECKpUKp06dMjg+ql/G+7shwN0Wd4vUmPnDCRSrNVKHRERERNTkGTxR28nJCUlJSXBzc9NpP3DgANq2bWvQWIWFhTh+/Djmzp2rbZPJZAgMDERsbKzebWJjYxEeHq7TFhQUhIiIiAfuY926dbC2toa3t7fePgUFBdrLuABApVIBADQajfZOV3VJo9FAFEVJ9t0QfPiMFwZ/egBxyXewdt8FvDHAXeqQ6gTzgvRhXlB5zAnSh3lB+ujLi6rmiMFFxaRJkzBt2jRs2LABgiDgxo0biI2NxVtvvYUFCxYYNFZGRgbUajUcHR112h0dHZGYmKh3m5SUFL39U1JSdNp+++03jB49Gnl5eWjRogWioqJgZ2end8xly5ZhyZIlFdrT09ORn59vyCHVCI1Gg6ysLIiiqHOnLSphDCC8fyu8u/syVv15Hl3t5GjvYCZ1WLWOeUH6MC+oPOYE6cO8IH305UV2dnaVxjK4qJgzZw40Gg0GDhyIvLw89OvXDwqFAm+99RamTJlSpSBqw+OPP44TJ04gIyMD69evx6hRo3D48GE4ODhU6Dt37lydsx8qlQouLi6wt7eHlZVVXYYNoOQfWBAE2Nvb8wf/Acbb2+PQtbvYfSYVS6Ov4pc3A6AwkksdVq1iXpA+zAsqjzlB+jAvSB99eaFUVu22/QYXFYIg4J133sGsWbOQlJSEnJwcdOrUCRYWFgbv3M7ODnK5HKmpqTrtqampcHJy0ruNk5NTpfqbm5vDw8MDHh4e6NWrF9q1a4evvvpK51KrMgqFAgqFokJ7+Wdy1CVBECTdf0OwbKQX4pJv41xqDlZFJ2Hu4I5Sh1TrmBekD/OCymNOkD7MC9KnfF5UNT+qnFUmJibo1KkTfH19q1RQlI3RvXt3REdHa9s0Gg2io6Ph7++vdxt/f3+d/gAQFRX1wP73j3v/vAlq+GwtFPjPCC8AwLq/L+Lo5UyJIyIiIiJqmip9puKll16qVL8H3bXpQcLDwzF+/Hj06NEDvr6+WLVqFXJzcxEWFgYAGDduHFq2bIlly5YBAKZNm4b+/fvjk08+wdChQ7FlyxYcO3YM69atAwDk5ubi/fffx7Bhw9CiRQtkZGRgzZo1uH79Op577jmDYqP6b1BnJzzXvRW2Hb+G8B9O4Pdp/WChMPgEHBERERFVQ6V/+9q4cSNcXV3x2GOP1ejTjENDQ5Geno6FCxciJSUFPj4+iIyM1E7GTk5O1jkNExAQgM2bN2P+/PmYN28e2rVrh4iICHTp0gUAIJfLkZiYiE2bNiEjIwO2trbo2bMn9u/fj86dO9dY3FR/LHy6E2Iu3MLVzLt4f2cClo30kjokIiIioiZFECtZIbz55pv4/vvv4erqirCwMLz44oto3rx5bccnCZVKBWtra2RlZUk2UTstLQ0ODg687rGSDl28hTHrD0EUga8n9MTjnhUn5Dd0zAvSh3lB5TEnSB/mBemjLy+q+ntwpbNqzZo1uHnzJt5++238+uuvcHFxwahRo/DHH3/U6JkLoqro1dYWE3u3AQC8/dMpZOYWShwRERERUdNhUKmqUCgwZswYREVF4cyZM+jcuTPeeOMNuLm5IScnp7ZiJKqUt4I6oJ2DBdKzCzA/4h8Wu0RERER1pMrnv2QyGQRBgCiKUKvVNRkTUZUojeVYMcoHRjIBu/5Jwao/z7OwICIiIqoDBhUVBQUF+P777/Hkk0+iffv2+Oeff7B69WokJydX+bayRDXJq5U15gz2BAB8Gn0eC345DbWGhQURERFRbar03Z/eeOMNbNmyBS4uLnjppZfw/fffw87OrjZjI6qSl/u2hYmRDIt2/Iv/O5SMWzmFWBnqA6Vx437iNhEREZFUKl1UrF27Fq1bt0bbtm2xb98+7Nu3T2+/7du311hwRFU1zt8NtuYKzNh6Ar+fTsHtvCNYN64HrJTGUodGRERE1OhUuqgYN24cBEGozViIatTQri3QzMwYr3x7HIcuZmL0/w5h40s94WCplDo0IiIiokbFoIffETU0AR522PJKL0z4+gjO3FThmS9i8O1LfnCzM5c6NCIiIqJGg08/oUavS0tr/PR6AFo3N8PVzLt45osY/HMtS+qwiIiIiBoNFhXUJLjamuOn1wPQ2dkKt3ILMXpdLA6cz5A6LCIiIqJGgUUFNRn2lgpseaUXAtxtkVuoRtjGI/jt1A2pwyIiIiJq8FhUUJNiqTTG12E9McTLCUVqEVO+j8emmMtSh0VERETUoLGooCZHYSTH52O6YZy/K0QRWLTjX3z8x1k+fZuIiIioilhUUJMklwlYMqwzZj7ZHgCwek8S5vz0D4rVGokjIyIiImp4WFRQkyUIAqYMbIdlI70gE4Ctx67i9e/ikF+kljo0IiIiogaFRQU1eWN8W+O/L3SHiZEMUWdSMfarw8jKK5I6LCIiIqIGg0UFEYDgLk749iVfWCqNcPTybYz6XyxSsvKlDouIiIioQWBRQVTKr60tfnjVHw6WCpxNzcYzX8QgKS1H6rCIiIiI6j0WFUT36djCCj+9HoC2dua4fucunlsbgxNX70gdFhEREVG9xqKCqByX5mbY9po/vFtZ43ZeEcasO4S9Z9OkDouIiIio3mJRQaSHrYUCmyf1Qt92drhbpMbLm47h5/hrUodFREREVC+xqCB6AHOFEb4a3xPDfZxRrBExY+tJfLn/otRhEREREdU7LCqIHsLESIaVo3zwUu82AIClOxOwbFcCn75NREREdB8WFUSPIJMJWPBUR8wZ7AkA+N/fF/HWtlMo4tO3iYiIiACwqCCqFEEQ8Fp/dyx/tivkMgE/xV3DK98cQ15hsdShEREREUmORQWRAZ7r4YJ1Y7tDaSzDnrPpeOHLw7idWyh1WERERESSYlFBZKCBHR3x3ct+sDY1RnzyHYz470HsO5cudVhEREREkqkXRcWaNWvg5uYGpVIJPz8/HDly5KH9t23bBk9PTyiVSnh5eWHXrl3adUVFRZg9eza8vLxgbm4OZ2dnjBs3Djdu3Kjtw6AmpLtrc/z4mj+crZW4fCsP4zccwUsbj+JCOp/ATURERE2P5EXF1q1bER4ejkWLFiEuLg7e3t4ICgpCWpr+h43FxMRgzJgxmDhxIuLj4xESEoKQkBCcPn0aAJCXl4e4uDgsWLAAcXFx2L59O86ePYthw4bV5WFRE9DO0RK/T++Hl/u0gZFMwF+JaQha+Tfe/fUMsvKKpA6PiIiIqM4IosT3xvTz80PPnj2xevVqAIBGo4GLiwumTJmCOXPmVOgfGhqK3Nxc/Pbbb9q2Xr16wcfHB2vXrtW7j6NHj8LX1xdXrlxB69atHxmTSqWCtbU1srKyYGVlVcUjqzqNRoO0tDQ4ODhAJpO87qNKuJieg//sSsCfCSXFcDMzY4Q/2R5jfFvDSF4z/4bMC9KHeUHlMSdIH+YF6aMvL6r6e7CkWVVYWIjjx48jMDBQ2yaTyRAYGIjY2Fi928TGxur0B4CgoKAH9geArKwsCIIAGxubGombqLy29hb4cnxPfPOSL9o7WuB2XhEW/PIvBn+6H39zvgURERE1ckZS7jwjIwNqtRqOjo467Y6OjkhMTNS7TUpKit7+KSkpevvn5+dj9uzZGDNmzAOrrYKCAhQUFGiXVSoVgJLqTaOp+2cRaDQaiKIoyb6pevp42OK3yb3x/dGrWPXneZxPy8G4DUfwhKc95g32RFt7iyqPzbwgfZgXVB5zgvRhXpA++vKiqjkiaVFR24qKijBq1CiIoogvvvjigf2WLVuGJUuWVGhPT09Hfn5+bYaol0ajQVZWFkRR5CnKBiqorSn8x3XChsM3se1kGv5KTMe+c+l4ztsBL/m1gJXS8B895gXpw7yg8pgTpA/zgvTRlxfZ2dlVGkvSosLOzg5yuRypqak67ampqXByctK7jZOTU6X6lxUUV65cwV9//fXQa8Lmzp2L8PBw7bJKpYKLiwvs7e0lm1MhCALs7e35g9+AOQD4T2tnvDwgB+/vSsSes+nYEp+GP87exozAdhjd08Wg+RbMC9KHeUHlMSdIH+YF6aMvL5RKZZXGkrSoMDExQffu3REdHY2QkBAAJQcXHR2NyZMn693G398f0dHRmD59urYtKioK/v7+2uWyguL8+fPYs2cPbG1tHxqHQqGAQqGo0C6TyST7wRMEQdL9U83xcLTC12G+2HcuHUt/O4PzaTlYuOMM/u9wMhY81Ql929lXeizmBenDvKDymBOkD/OC9CmfF1XND8mzKjw8HOvXr8emTZuQkJCA119/Hbm5uQgLCwMAjBs3DnPnztX2nzZtGiIjI/HJJ58gMTERixcvxrFjx7RFSFFREZ599lkcO3YM3333HdRqNVJSUpCSkoLCQj75mKTTv709fp/WF+8O7wwbM2OcS83B2K+O4OVNR3GRz7cgIiKiBkzyORWhoaFIT0/HwoULkZKSAh8fH0RGRmonYycnJ+tUTAEBAdi8eTPmz5+PefPmoV27doiIiECXLl0AANevX8eOHTsAAD4+Pjr72rNnDwYMGFAnx0Wkj5FchnH+bhju3RKros/h29gr+DMhDfvOpWO8vxumDGwHa1NjqcMkIiIiMojkz6moj/icCqorSWk5eH/nGew5W3Lb2ebmJgh/sr3e+RbMC9KHeUHlMSdIH+YF6dNonlNB1NR5OFjg6zBfbAzrCQ8HC2TmFmJ+xGkM/ewADiZlSB0eERERUaWwqCCqBwZ0cMDv0/piybCS+RZnU7PxwpeH8fKmY7iUkSt1eEREREQPxaKCqJ4wlsswPsANe98agAkBbpDLBPyZkIpBK/fh/Z1noLpbJHWIRERERHqxqCCqZ2zMTLB4WGf8Mb0vBnSwR5FaxPr9l/DEJ/vw7bEUpKrq/oGMRERERA/DooKonvJwsMTGMF98HdYT7vbmyMwrwpoD19H7wz0Y+9VhRMRfR15hsdRhEhEREUl/S1kierjHOzigj4cdfjx+Fd8fuoRTN3Kx/3wG9p/PgLmJHMFdWuCZbi3Rq60tZDJB6nCJiIioCWJRQdQAGMtlCO3hgsdbK3BXbo5fTt7E9rjrSM7Mw09x1/BT3DU4Wysx/LGWeKZbS3g4WEodMhERETUhLCqIGhhXW3NMD2yPaQPb4fiV2/gp7jp2nrqBG1n5+GLvBXyx9wK6trLGyMda4mlvZ9haKKQOmYiIiBo5FhVEDZQgCOjh1hw93Jpj0dOd8FdiGrbHXcPes+k4dS0Lp65lYenOBAzoYI+R3VrhCU8HKI3lUodNREREjRCLCqJGQGksxxCvFhji1QK3cgrw68kb2B5/HaeuZeHPhDT8mZAGK6URhnZ1xjPdWqK7azMIAudfEBERUc1gUUHUyNhaKDChdxtM6N0GSWnZ2B53HT/HX8fNrHx8fyQZ3x9JhqutGUJ8WmJkt5ZwtTWXOmQiIiJq4FhUEDViHg6WeDvYE28N6oBDF2/hp7jriDx9E1du5eHT6PP4NPo8erg2w8hurTDUqwWszYylDpmIiIgaIBYVRE2ATCYgwMMOAR52eC+kM3b/m4qf4q7hYFIGjl25jWNXbmPxjn8R2MkBIx9rhf4d7GEs52NsiIiIqHJYVBA1MWYmRgh5rCVCHmuJVFU+fjlxHT8dv46zqdnY9U8Kdv2TgubmJujtYQdft2bo2aY52jtY8hkYRERE9EAsKoiaMEcrJV7p545JfdvizE0Vfo67jogTN5BROtn715M3AADWpsbo6dYMPd2ao2eb5ujibA0TI57JICIiohIsKogIgiCgs7M1OjtbY85gTxy9fBtHLmXi6OVMxCXfRtbdIu1dpABAaSzDYy4lZzH82jTHY61tYGbCjxMiIqKmir8FEJEOI7kM/u628He3BQAUqTU4c0OFI5cyceRyJo5dzsTtvCLEXryF2Iu3SraRCejc0rrkcim35ujp1hzNzE2kPAwiIiKqQywqiOihjOUyeLvYwNvFBpP6tYVGI+JCeg6OXM7E0UuZOHIpEzey8nHy6h2cvHoH6/dfAgC0d7RAT7fm8G1TUmQ425hKfCRERERUW1hUEJFBZDIB7Rwt0c7REi/4uQIArt3Ow9HLmThy6TaOXs5EUloOzqWWvL47nAwAaNXMFL6lczJ6ujWHu705H8BHRETUSLCoIKJqa9XMDK2amWHEY60AALdyCnD0ckmBcfRyJv69ocK123dx7fZ1bI+/DgCwNTdBD7dm6OHaHO0cLeDhYAFna1PeZYqIiKgBYlFBRDXO1kKB4C5OCO7iBADIKShGfHLJ5O8jlzJx4uod3MotxB//puKPf1O125kay+HuYA4P+5Iio+zlamvO52YQERHVYywqiKjWWSiM0LedPfq2swcAFBSrcfp6Fo5cuo1T1+4gKS0Hl2/l4m6RGqevq3D6ukpneyOZgNa2ZhWKDXd7C5gr+DFGREQkNf5vTER1TmEkR3fX5uju2lzbVqTWIDkzDxfScpCUnoOktJyS92k5yC1U42J6Li6m52L3mVSdsZytlXAvV2h4OFjA1tyEczaIiIjqCIsKIqoXjOUyuNuXFAWD7msXRREpqnwklRYYZa8L6bnIyCnAjax83MjKx/7zGTrj2ZgZ65zZcHewgJutOVpYK6E0ltftwRERETVyLCqIqF4TBAEtrE3RwtpUe/lUmTt5hbiQrltsJKXn4Nrtu7iTV4RjV27j2JXbFcZsZmYMJ2tTtLBWwslaCWdrpc5yC2slH+ZHRERkAP6vSUQNlo2ZSYXLqAAgv0iNC+klZzPuv4wqOTMPd4vUuJ1XhNt5RUi4qXrAyICV0ggtrE1Lig4bJZysdIsOJ2slLJXGtX2IREREDQKLCiJqdJTGcnR2tkZnZ2uddlEUocovRkpWPm5m3UVK6aVTKVl3cTMrHymlr+yCYqjyi6HKz8bZ1OwH7sdCYVSu0LhXeNhbKNDM3ATNzUxgasLLrYiIqHFjUUFETYYgCLA2NYa1qTE6OFk+sF92fhFSVfm4cSe/tADJR4rqXuFx485dqPKLkVNQjPNpOTiflvPQ/SqNZWhuZlJSZJiboJnZ/V+N0dxcgWbmxmheWoTYmJnAxIi30CUiooZD8qJizZo1WL58OVJSUuDt7Y3PP/8cvr6+D+y/bds2LFiwAJcvX0a7du3w4YcfYsiQIdr127dvx9q1a3H8+HFkZmYiPj4ePj4+dXAkRNRYWCqNYak0hofDgwuP3IJipKjuKzpKz3aUvTJzC5CZW4gitYj8Io12QnmlY1AYoZl5aSFiZqw961G+MLFWylGYWwhz62JYKI15xysiIpKEpEXF1q1bER4ejrVr18LPzw+rVq1CUFAQzp49CwcHhwr9Y2JiMGbMGCxbtgxPPfUUNm/ejJCQEMTFxaFLly4AgNzcXPTp0wejRo3CpEmT6vqQiKiJMFcYae9W9SCiKCK3UI3buYXIzC1EZl6h9v3tvEJk5haVLJe2l7QVQiMC2QXFyC4oRnJmXiUj+gdymQALhREslUawUBjBSmkMS2XpstKotFgq/Vrar6ytrL+F0ghyPtWciIgMJIiiKEq1cz8/P/Ts2ROrV68GAGg0Gri4uGDKlCmYM2dOhf6hoaHIzc3Fb7/9pm3r1asXfHx8sHbtWp2+ly9fRps2bap0pkKlUsHa2hpZWVmwsrIy/MCqSaPRIC0tDQ4ODpDJeAkElWBeNA0ajQhVftEDC4/M+4qP23kl/bLzi6CpwU9ycxO53iLEQmEEM4UcZiZymJkYwdRYDnOFHKYmRjAzLm1XGMHMRF66ruS9wkjGMyh1iJ8VpA/zgvTRlxdV/T1YsjMVhYWFOH78OObOnattk8lkCAwMRGxsrN5tYmNjER4ertMWFBSEiIiI2gyViKjOyGQCbErnVVSGRqNBamoqLJvZIrdQg+z8opL5HvnFyM4vRnZ+UcnXgvvel37NKbjXR5VfjMJiDQAgt1CN3EI1UlUFNXNMAmBqrFtwmJmUFB1l701NjGBucu+9qbEMSmN56UsGhbEcSiM5FMYyKI1K2u5frzSSQ8YzLEREkpGsqMjIyIBarYajo6NOu6OjIxITE/Vuk5KSord/SkpKtWIpKChAQcG9/zxVqpLbTGo0Gmg0mmqNXRUajQaiKEqyb6q/mBekT1k+KI1kMDMxgr1F5YoRfQqK1SXFSGmxkVOuGMnJL0ZekRp3C9XIKyz5mltYXLJcVG65UI2C0iJFI94rVGqTiVyAyf0Fh1HJV0VZYWJUVpCUFielfUyMStaZGMlgIi/9aiSDwkiubbt/vfZ9uTYjef346y8/K0gf5gXpoy8vqpojkk/Urg+WLVuGJUuWVGhPT09Hfn7lJ1bWFI1Gg6ysLIiiyFOUpMW8IH1qIy/MAJgZA47GACwFACalL8OoNSWT1O8Wa3C3SI38Ig3yijQlbUVq3C3SaF/55ZYLijXILy75WqjWoKBYREHp8r2XiOL7rvsqVIsoVBcjp2ZOsBhMJgDGcgEmcpn2q4mRAGO5DCZyAcZyAcayknVGcgHGspI2o9K2kvel/eSye+9lpf3lsnvblPWVlfa9bzy5ANzNzUEzVQFMjOQwkgk6L7kMvBytCeL/IaSPvrzIzn7wrdQfRrKiws7ODnK5HKmpqTrtqampcHJy0ruNk5OTQf0ra+7cuTqXValUKri4uMDe3l6yORWCIMDe3p4/+KTFvCB9mnpeqDUiCopLCpb8InVJIVKkRn5RyZmSe+1qFJTvU6zR9isse6lLvhaUWy7UFje6y+r7ihqNiNLip3bPyNQEI1lZYVJW5Mi0RY9R2bKePkalRUz5ZXlZ0SIXSt/L7hUxpePKZSXrjO/vIy8rdO6NJy8tluTy+8bQjiXTXb7vpV0WSr6ycNLV1D8rSD99eaFUKqs0lmRFhYmJCbp3747o6GiEhIQAKDmw6OhoTJ48We82/v7+iI6OxvTp07VtUVFR8Pf3r1YsCoUCCoWiQrtMJpPsB08QBEn3T/UT84L0acp5IZMBxkZyWFTt/8BqK1brFh4F+gqTYg0K1erSryKKijUoUpe8CtViyfvicstl64vLLevZvli7XkRh6VgFxWqoNSKKNCL03Y6lWFN2lqfxXgqjU2wIJcWNTuFRWjCV9ZEJ94qissJE5yUIkJX1LV2+/71cXnE7Wbk+RvKSNrkMkMtkkAslccruG79sjHvvUbpNybb3+kJPX0Hbt/x2AkTczi2CzKwIRqWFoCDcOzahNJay9yzKmo7y/4dU9f8SSS9/Cg8Px/jx49GjRw/4+vpi1apVyM3NRVhYGABg3LhxaNmyJZYtWwYAmDZtGvr3749PPvkEQ4cOxZYtW3Ds2DGsW7dOO2ZmZiaSk5Nx48YNAMDZs2cBlJzlqO4ZDSIiovsZyUvmUlRyXn2dKH83F7WmpDAp1pQVICKKNRoUq++1F6lLlos1pevVIopK+5QVTrrry7YTodaUjS1q91GsEaHW3NtPWYGjLhuztKhRl46n1tzb9v73ZeOUxawuXVZr7m3zIGV9Cuvwe9+YyEqLDEG4/+zP/YXHvcLlXvGCe0VPaQEkE1Dh/f1FjKzce23/0sJJ+7507LLtZaWX8clL1wnl+gkC7sWhZ/39+xK0+yzb9t64OutlZcv3x1lubJ3xygo03ePQ3b7i+DIBMJLJ4GZnLnUaGETSoiI0NBTp6elYuHAhUlJS4OPjg8jISO1k7OTkZJ1qKSAgAJs3b8b8+fMxb948tGvXDhEREdpnVADAjh07tEUJAIwePRoAsGjRIixevLhuDoyIiKieKPmrtVzqMGqFKIrQiECxRgONBtrCo/i+okNzXwFTVvxoxPv6lBY1avFe0XNvudxLvH+8e+NoNCLUGkCt0ZRuV/peg9I+pe/LYio/dum4ZfssW6/RoGKbCG1fnW2073Hf9rpjlixX7nurEQGNWgQg2ZMHmjR7SwWOvhModRgGkfQ5FfUVn1NB9RHzgvRhXlB5zAnS5/68AISSwkMsuTyurLAR7ytixNL12iKmrDApV7iIYrltNPfGvb+PTlEklo1VMnb592X7FcsVUtp+9xVUGo0IEdBZV3ZMmvvi0OgbU2d92fK99eL9+yuNQURJsfegse/vL4q6MVTc14O3tzU3QfTMAXWaFw32ORVEREREVPdkMgEyCPwlkGoU/4RBRERERETVwqKCiIiIiIiqhUUFERERERFVC4sKIiIiIiKqFhYVRERERERULSwqiIiIiIioWlhUEBERERFRtbCoICIiIiKiamFRQURERERE1cKigoiIiIiIqoVFBRERERERVYuR1AHUR6IoAgBUKpUk+9doNMjOzoZSqYRMxrqPSjAvSB/mBZXHnCB9mBekj768KPv9t+z34cpiUaFHdnY2AMDFxUXiSIiIiIiI6l52djasra0r3V8QDS1DmgCNRoMbN27A0tISgiDU+f5VKhVcXFxw9epVWFlZ1fn+qX5iXpA+zAsqjzlB+jAvSB99eSGKIrKzs+Hs7GzQWS2eqdBDJpOhVatWUocBKysr/uBTBcwL0od5QeUxJ0gf5gXpUz4vDDlDUYYX1RERERERUbWwqCAiIiIiomphUVEPKRQKLFq0CAqFQupQqB5hXpA+zAsqjzlB+jAvSJ+azAtO1CYiIiIiomrhmQoiIiIiIqoWFhVERERERFQtLCqIiIiIiKhaWFTUQ2vWrIGbmxuUSiX8/Pxw5MgRqUMiiSxevBiCIOi8PD09pQ6L6tjff/+Np59+Gs7OzhAEARERETrrRVHEwoUL0aJFC5iamiIwMBDnz5+XJliqM4/KiwkTJlT4/AgODpYmWKoTy5YtQ8+ePWFpaQkHBweEhITg7NmzOn3y8/Px5ptvwtbWFhYWFnjmmWeQmpoqUcRUFyqTFwMGDKjwefHaa68ZtB8WFfXM1q1bER4ejkWLFiEuLg7e3t4ICgpCWlqa1KGRRDp37oybN29qXwcOHJA6JKpjubm58Pb2xpo1a/Su/+ijj/DZZ59h7dq1OHz4MMzNzREUFIT8/Pw6jpTq0qPyAgCCg4N1Pj++//77OoyQ6tq+ffvw5ptv4tChQ4iKikJRUREGDRqE3NxcbZ8ZM2bg119/xbZt27Bv3z7cuHEDI0eOlDBqqm2VyQsAmDRpks7nxUcffWTYjkSqV3x9fcU333xTu6xWq0VnZ2dx2bJlEkZFUlm0aJHo7e0tdRhUjwAQf/75Z+2yRqMRnZycxOXLl2vb7ty5IyoUCvH777+XIEKSQvm8EEVRHD9+vDh8+HBJ4qH6IS0tTQQg7tu3TxTFks8GY2Njcdu2bdo+CQkJIgAxNjZWqjCpjpXPC1EUxf79+4vTpk2r1rg8U1GPFBYW4vjx4wgMDNS2yWQyBAYGIjY2VsLISErnz5+Hs7Mz2rZtixdeeAHJyclSh0T1yKVLl5CSkqLzuWFtbQ0/Pz9+bhD27t0LBwcHdOjQAa+//jpu3boldUhUh7KysgAAzZs3BwAcP34cRUVFOp8Xnp6eaN26NT8vmpDyeVHmu+++g52dHbp06YK5c+ciLy/PoHGNaixCqraMjAyo1Wo4OjrqtDs6OiIxMVGiqEhKfn5+2LhxIzp06ICbN29iyZIl6Nu3L06fPg1LS0upw6N6ICUlBQD0fm6UraOmKTg4GCNHjkSbNm1w4cIFzJs3D4MHD0ZsbCzkcrnU4VEt02g0mD59Onr37o0uXboAKPm8MDExgY2NjU5ffl40HfryAgCef/55uLq6wtnZGadOncLs2bNx9uxZbN++vdJjs6ggqscGDx6sfd+1a1f4+fnB1dUVP/zwAyZOnChhZERU340ePVr73svLC127doW7uzv27t2LgQMHShgZ1YU333wTp0+f5jw80vGgvHjllVe07728vNCiRQsMHDgQFy5cgLu7e6XG5uVP9YidnR3kcnmFuzCkpqbCyclJoqioPrGxsUH79u2RlJQkdShUT5R9NvBzgx6lbdu2sLOz4+dHEzB58mT89ttv2LNnD1q1aqVtd3JyQmFhIe7cuaPTn58XTcOD8kIfPz8/ADDo84JFRT1iYmKC7t27Izo6Wtum0WgQHR0Nf39/CSOj+iInJwcXLlxAixYtpA6F6ok2bdrAyclJ53NDpVLh8OHD/NwgHdeuXcOtW7f4+dGIiaKIyZMn4+eff8Zff/2FNm3a6Kzv3r07jI2NdT4vzp49i+TkZH5eNGKPygt9Tpw4AQAGfV7w8qd6Jjw8HOPHj0ePHj3g6+uLVatWITc3F2FhYVKHRhJ466238PTTT8PV1RU3btzAokWLIJfLMWbMGKlDozqUk5Oj89eiS5cu4cSJE2jevDlat26N6dOnY+nSpWjXrh3atGmDBQsWwNnZGSEhIdIFTbXuYXnRvHlzLFmyBM888wycnJxw4cIFvP322/Dw8EBQUJCEUVNtevPNN7F582b88ssvsLS01M6TsLa2hqmpKaytrTFx4kSEh4ejefPmsLKywpQpU+Dv749evXpJHD3VlkflxYULF7B582YMGTIEtra2OHXqFGbMmIF+/fqha9euld9Rte4dRbXi888/F1u3bi2amJiIvr6+4qFDh6QOiSQSGhoqtmjRQjQxMRFbtmwphoaGiklJSVKHRXVsz549IoAKr/Hjx4uiWHJb2QULFoiOjo6iQqEQBw4cKJ49e1baoKnWPSwv8vLyxEGDBon29vaisbGx6OrqKk6aNElMSUmROmyqRfryAYD49ddfa/vcvXtXfOONN8RmzZqJZmZm4ogRI8SbN29KFzTVukflRXJystivXz+xefPmokKhED08PMRZs2aJWVlZBu1HKN0ZERERERFRlXBOBRERERERVQuLCiIiIiIiqhYWFUREREREVC0sKoiIiIiIqFpYVBARERERUbWwqCAiIiIiomphUUFERERERNXCooKIiIiIiKqFRQURET2Um5sbVq1aVen+e/fuhSAIuHPnTq3FVJ8Y+v0hImqMWFQQETUSgiA89LV48eIqjXv06FG88sorle4fEBCAmzdvwtraukr7IyKihsdI6gCIiKhm3Lx5U/t+69atWLhwIc6ePatts7Cw0L4XRRFqtRpGRo/+b8De3t6gOExMTODk5GTQNkRE1LDxTAURUSPh5OSkfVlbW0MQBO1yYmIiLC0t8fvvv6N79+5QKBQ4cOAALly4gOHDh8PR0REWFhbo2bMn/vzzT51xy1/eIwgCvvzyS4wYMQJmZmZo164dduzYoV1f/vKnjRs3wsbGBn/88Qc6duwICwsLBAcH6xRBxcXFmDp1KmxsbGBra4vZs2dj/PjxCAkJeegxHzhwAH379oWpqSlcXFwwdepU5Obm6sT+3nvvYcyYMTA3N0fLli2xZs0anTGSk5MxfPhwWFhYwMrKCqNGjUJqaqpOn19//RU9e/aEUqmEnZ0dRowYobM+Ly8PL730EiwtLdG6dWusW7fuoXETETU2LCqIiJqQOXPm4IMPPkBCQgK6du2KnJwcDBkyBNHR0YiPj0dwcDCefvppJCcnP3ScJUuWYNSoUTh16hSGDBmCF154AZmZmQ/sn5eXh48//hjffvst/v77byQnJ+Ott97Srv/www/x3Xff4euvv8bBgwehUqkQERHx0BguXLiA4OBgPPPMMzh16hS2bt2KAwcOYPLkyTr9li9fDm9vb8THx2POnDmYNm0aoqKiAAAajQbDhw9HZmYm9u3bh6ioKFy8eBGhoaHa7Xfu3IkRI0ZgyJAhiI+PR3R0NHx9fXX28cknn6BHjx6Ij4/HG2+8gddff13nLBERUaMnEhFRo/P111+L1tbW2uU9e/aIAMSIiIhHbtu5c2fx888/1y67urqKK1eu1C4DEOfPn69dzsnJEQGIv//+u86+bt++rY0FgJiUlKTdZs2aNaKjo6N22dHRUVy+fLl2ubi4WGzdurU4fPjwB8Y5ceJE8ZVXXtFp279/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": [ "
" ] @@ -246,7 +233,7 @@ "\n", "## What happened\n", "\n", - "`braintrace.compile` discovers which MiniGRU parameters reach recurrent hidden state through ETP primitives. `brainstate.transform.grad` obtains a per-step online gradient, while `brainstate.transform.scan` carries the gradient accumulator across time. `brainstate.transform.for_loop` performs the repeated updates without repeatedly dispatching model calls from Python.\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", @@ -272,7 +259,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.11.8" + "version": "3.13.11" } }, "nbformat": 4, diff --git a/docs/specs/2026-07-28-compile-and-driver-migration.md b/docs/specs/2026-07-28-compile-and-driver-migration.md new file mode 100644 index 0000000..41e9826 --- /dev/null +++ b/docs/specs/2026-07-28-compile-and-driver-migration.md @@ -0,0 +1,243 @@ +# Migration onto `compile`, `etrace_grad` and `etrace_evolve` + +Status: spec, describing work carried out +Baseline: commit `f935856` (squash-merge of PR #151) +Target release: 0.3.0 + +## Goal + +Make the repository teach **one** way to set a learner up and **one** way to run +it over a sequence. + +`braintrace.compile` has been the documented entry point since before 0.2, and +PR #151 landed the two sequence drivers. Neither migration finished. #151's own +spec scoped a list of call sites, `main` moved underneath it twice (#148 +reorganized the tutorials, #150 rewrote the API reference per-class), and +`examples/` has no CI coverage at all — `.github/workflows/CI.yml` runs +`pytest braintrace/`, nothing else. The result is that the answer to "how do I +train a model with braintrace?" depends on which file the reader opens: + +| what the reader finds | where | +|---|---| +| `compile(...)` + `etrace_grad(...)` | `examples/drtrl/01`, `docs/advanced/batching.ipynb` | +| `compile(...)`, then a hand-written `scan`-accumulate | `docs/quickstart/quickstart.ipynb`, `docs/tutorials/drtrl.ipynb` | +| `Algo(model)` + `init_all_states` + `compile_graph` + `Vmap` | `examples/004`, `examples/100-gru` `'batch'` arm | + +Two of those un-migrated sites did not merely look dated — they raised on the +first call. Neither was caught, because nothing runs them. + +## Scope + +**In scope.** Every remaining `examples/` site that constructs a learner the old +way or drives a sequence by hand; the docs notebooks; the class-level `Examples` +blocks in the library, which #150 turned into the per-class API reference pages +and which therefore *are* the API documentation for each algorithm. + +**Out of scope.** Changing any algorithm's numerics. Changing `compile` or the +drivers themselves — the limitations found while auditing are recorded in +"Declared limitations" below and left in place. Dated spec documents under +`docs/specs/` other than this one. A user-facing migration page: this document +is a record of a completed change, not a guide, and the migration is small +enough that the class docstrings and `docs/advanced/batching.ipynb` carry the +teaching load. + +## Measured facts this migration rests on + +**M1. Both driver substitutions are bit-exact.** Checked against the code as +merged, not assumed from the #151 spec: + +- `etrace_evolve(xs, return_outputs=True)` returns outputs **identical** to + `brainstate.transform.for_loop(learner, xs)`. +- `etrace_grad(..., reduction='mean')` returns a gradient tree whose maximum + absolute difference from the hand-written `scan`-accumulate-then-divide loop + is **0.0**. + +This is what licenses re-executing the notebooks and *requiring* the printed +numbers to be unchanged. Drift would mean the rewrite is not the equivalence +claimed, and would be investigated rather than accepted. + +**M2. `compile` inside `jit` is fine.** `examples/100-gru-on-copying-task.py` +called `compile` inside `@brainstate.transform.jit` in one branch of an `if` +while the sibling branch carried a comment claiming compile "must live outside +jit". Both branches now run, in the same jitted function, and both pass. + +**M3. `compile(vmap=True)` *is* the manual vmap expansion.** `_compile.py:308-330` +is literally `vmap_new_states(state_tag='new')` + `init_all_states` + +`compile_graph` on the axis-stripped sample + `ETraceVmap(learner, +vmap_states='new')` — the four steps `examples/drtrl/02-batching-vmap.py` writes +out by hand. + +**M4. `jax.ShapeDtypeStruct` is not subscriptable.** `compile`'s vmap branch +strips the batch axis with `jax.tree.map(lambda a: a[0], example_inputs)`, so a +shape-only example input raises `TypeError` there. The `003-*` benchmarks build +their graph from a shape, never from data. + +## The three canonical replacements + +| old | new | +|---|---| +| `Algo(model)` + `init_all_states(model, batch_size=B)` + `compile_graph(x0)` | `compile(model, Algo, x0, batch_size=B)` | +| `Algo(model)` + `vmap_new_states(state_tag='new')` + `compile_graph(x0[0])` + `Vmap(..., vmap_states='new')` | `compile(model, Algo, x0, batch_size=B, vmap=True)` | +| `for_loop(learner, xs)` | `learner.etrace_evolve(xs)`, or `etrace_evolve(xs, return_outputs=True)` to keep the stack | +| `scan`-accumulate, then `grads / T` | `learner.etrace_grad(..., reduction='mean')` | +| `scan`-accumulate, no divide | `learner.etrace_grad(..., reduction='sum')` | + +In the vmap row, `x0` carries the batch axis in **both** columns: `compile` +strips axis 0 itself to recover the per-sample example. Passing `x0[0]` to +`compile` is the one easy mistake, and it is why `docs/advanced/batching.ipynb` +says so in a comment at the call. + +The last two rows are the same method; the distinction is only which reduction +reproduces the site's existing gradient scale. **Every migrated site declares +which of the two it was** — that declaration is the reviewable claim, since +choosing wrong rescales the effective learning rate by `T` and the smoke +assertion (loss decreases) would not necessarily catch it. + +## Two bugs the migration fixes + +Both shipped. Both are invisible to CI, which does not run `pytest examples/`. + +**B1. `examples/drtrl/02-batching-vmap.py`** raised `AttributeError: 'Vmap' +object has no attribute 'etrace_grad'`. #151 migrated its training loop to +`etrace_grad` but left the wrapper as `brainstate.nn.Vmap`; only +`braintrace.ETraceVmap` carries the drivers. Fixed by switching the wrapper — +the file deliberately keeps the manual expansion (see below). + +**B2. `examples/004-feedforward-conv-snn.py:302`** raised `TypeError: +ParamDimVjpAlgorithm.__init__() got multiple values for argument 'model'`. The +line was `D_RTRL(self.target, self.decay_or_rank, model=brainstate.mixin.Batching())` +— the model passed both positionally and by keyword, plus a `decay_or_rank` +positional that `D_RTRL` does not take (that belongs to `ES_D_RTRL`, whose +commented-out line directly above it was the original). It survived because +`OnlineBatchTrainer` is never instantiated in `main()` and `004` is skipped in +the smoke tests, which need the NMNIST dataset. + +B2 is fixed by the migration itself: `compile(model, D_RTRL, inputs[0], +batch_size=B)` has nowhere to put either bad argument. The sibling batched paths +(`100-gru`'s `'batch'` arm, `003-batched`) pass no `Batching()` mixin either. + +Because `004` is skipped, neither arm is reachable from any test. Both were +exercised directly against a synthetic batch, with `tonic` (the dataset library, +not installed) stubbed at import. That run is the only evidence B2 is *fixed* +rather than merely rewritten, and it also confirms both trainers compile the +same eligibility-trace graph (identical hidden groups and weight associations). + +## What stays manual, and why + +Five sites carried a `# kept manual:` comment. Checked against `_compile.py`, +**all five reasons were false or imprecise.** The code at three of them was +migrated; at the other two the code stays and the reason is corrected. Stating a +wrong reason is worse than stating none: it tells the next reader that a working +API does not work. + +- **`examples/drtrl/02-batching-vmap.py`** — claimed the `vmap_states='new'` path + was "not yet covered by `compile()`". By M3 it is exactly what `compile` + covers. The file stays manual because it *is* the worked expansion: it is the + one place a reader can see which state gets the per-sample axis and on which + unbatched sample the trace graph is built. The docstring now says so and + names the one-call form. +- **`examples/pp_prop/05-batching-vmap.py`** — carried the same false claim, and + its docstring was stale on top of it: the file routes through + `_shared.online_train_epoch`, which has used `compile(..., vmap=True)` since + #151. The note is dropped and the docstring retitled to what the file does. +- **`examples/003-snn-memory-and-speed-evaluation-{all,batched,vmap}.py`** — the + reasons were true but vague. They are now stated as the precise limitations + (below): `-all` and `-batched` use a third state scheme `compile` does not + offer, and all three pass a `ShapeDtypeStruct` example input, which M4 rules + out of the vmap branch. These files also keep their **Python step loop**, which + is not a `compile` question at all: `get_mem_usage()` is sampled between + steps, and a fused `etrace_grad` scan would leave nowhere to sample. The loop + is the measurement, not an un-migrated leftover. + +BPTT baselines and eval-only re-init blocks keep their annotations unchanged. +They construct no learner and hold no trace, so there is nothing to migrate. + +## Declared limitations + +Found while auditing. Recorded, not fixed — each is a real gap that a caller can +hit, and naming it here is cheaper than the reader rediscovering it. + +1. **`ETraceVmap` does not forward the introspection surface.** It carries + `etrace_grad` / `etrace_evolve` and the `Vmap` call, but not `show_graph`, + `graph`, `report` or `param_states`. A vmapped caller wanting a post-compile + diagnostic must reach through `.module`. This is safe and is what + `examples/004`'s vmap trainer now does, with a comment: `ETraceVmap`'s + docstring warns against `.module`, but that warning is about **driving** the + unbatched learner, which would give per-lane-wrong results. A read-only + diagnostic is not driving. +2. **`compile(**options)` cannot carry an option named `model`.** It collides + with the positional parameter. No current algorithm needs one, so this is a + latent constraint on the option namespace rather than a present blocker. +3. **`compile` has no path for the `003-*` state scheme** — + `vmap_init_all_states(state_tag='new')` for the per-sample states, + `compile_graph` on a **batched** example, no wrapper at all, and an explicit + `brainstate.transform.vmap(in_states=...)` used only for the reset. `compile` + offers two schemes; this is a third. +4. **`compile(vmap=True)` cannot take a `jax.ShapeDtypeStruct` example input** + (M4). Building a graph from a shape rather than from data is what a benchmark + does, so the gap and limitation 3 are usually hit together. + +## Sites changed + +**Initialization → `compile`** (3 sites): `examples/100-gru-on-copying-task.py` +`'batch'` arm; `examples/004-feedforward-conv-snn.py` `OnlineVmapTrainer` and +`OnlineBatchTrainer` (the latter fixing B2). + +**Hand-driven sequence → drivers** (2 sites): `examples/drtrl/08-operator-conv.py` +and `09-classification-mnist.py`, whose warm-up `for_loop` becomes +`etrace_evolve`. Both compute their loss at the final step only, so the gradient +below stays a single-step `grad` rather than an `etrace_grad` — the warm-up is +the only part the driver replaces. + +**Docs notebooks.** One `scan`-accumulate block, byte-identical in +`docs/quickstart/quickstart.ipynb`, `docs/tutorials/drtrl.ipynb` and +`docs/tutorials/pp_prop.ipynb`, becomes `etrace_grad(..., reduction='mean')` — +`'mean'` because the block ended in `grads / inputs.shape[0]`. Their `evaluate()` +becomes `etrace_evolve(..., return_outputs=True)`. `docs/quickstart/concepts.ipynb` +collapses `online_sequence_gradient` to one `etrace_grad(..., reduction='sum')`, +`'sum'` because it accumulated without dividing. +`docs/tutorials/neural_network_layers.ipynb` swaps a `for_loop(learner, ...)` for +`etrace_evolve`. `import jax` becomes unused in three notebooks once `jax.tree` +does, and is dropped. + +**Docs prose.** Four passages still named `brainstate.transform.scan` as the +mechanism — `quickstart` "What happened", the `drtrl` and `pp_prop` section +headings, `concepts`'s BPTT comparison table, and `batching`'s numbered +walkthrough. This matters as much as the code: prose describing the old +mechanism is why a reader would write a `scan` after reading migrated code. + +**Docstrings.** Nine `Examples` blocks built a learner and stopped at one +forward call, so the per-class API pages never showed a driver. Each gains the +same tail, adapted to its own shapes. Two differ on purpose: `ThreeFactor` rides +its per-step `modulator` as a **second sequence**, which is the clearest +demonstration of why `step_fn` owns the model call — there is nowhere the +modulator needs threading through. `UORO` is multi-step by construction, so its +tail is the only documented example of **window mode**, with `chunk_size=k`, +`MultiStepData` inside `step_fn`, and a `(k,)` return. + +`braintrace/__init__.py`'s layer-4 bullet now names the drivers, and its `Notes` +paragraph says what the one `compile` call replaces. + +## Verification + +`braintrace/_docs_examples_test.py`, which executed docstring snippets, was +deleted by #150. **Nothing in the repo runs them now**, so: + +1. `pytest examples/ -q` — the only coverage these files have. Reaches + `drtrl/02`, `08`, `09`, both `100-gru` arms, and `003-all`. +2. `examples/004`'s two trainers driven directly on a synthetic batch with + `tonic` stubbed, since the file is skipped. This is the only proof of B2. +3. Every changed notebook re-executed with `nbclient`. By M1 the printed numbers + must be **unchanged**; the two notebooks that ship without stored outputs are + executed in a copy so the migration does not add outputs the docs never had. +4. All docstring snippets extracted and executed, sharing a namespace per file + so blocks that continue each other across a `.. code-block::` directive + resolve their names. +5. `python -m mypy braintrace` (the CI gate); every + `docs/apis/algorithm_details/braintrace.*` toctree entry still resolves. +6. `pytest braintrace/ -n 6 -q` for regression. + +The standing gap this exercise exposed is that items 1, 2 and 4 are all manual. +`examples/` and the docstring snippets are documentation that can break silently, +and both B1 and B2 are what that costs. Wiring either into CI is future work, +and is the change that would stop this document from needing a sequel. diff --git a/docs/tutorials/drtrl.ipynb b/docs/tutorials/drtrl.ipynb index ed64de9..cf1712b 100644 --- a/docs/tutorials/drtrl.ipynb +++ b/docs/tutorials/drtrl.ipynb @@ -46,10 +46,10 @@ "id": "drtrl-imports", "metadata": { "execution": { - "iopub.execute_input": "2026-07-27T03:55:03.417817Z", - "iopub.status.busy": "2026-07-27T03:55:03.417817Z", - "iopub.status.idle": "2026-07-27T03:55:05.816680Z", - "shell.execute_reply": "2026-07-27T03:55:05.815668Z" + "iopub.execute_input": "2026-07-28T15:24:21.586239Z", + "iopub.status.busy": "2026-07-28T15:24:21.585904Z", + "iopub.status.idle": "2026-07-28T15:24:24.420178Z", + "shell.execute_reply": "2026-07-28T15:24:24.419116Z" } }, "outputs": [], @@ -57,7 +57,6 @@ "import brainstate\n", "import braintools\n", "import braintrace\n", - "import jax\n", "import jax.numpy as jnp\n", "import matplotlib.pyplot as plt\n", "import warnings\n", @@ -81,10 +80,10 @@ "id": "drtrl-model", "metadata": { "execution": { - "iopub.execute_input": "2026-07-27T03:55:05.818720Z", - "iopub.status.busy": "2026-07-27T03:55:05.817681Z", - "iopub.status.idle": "2026-07-27T03:55:07.343817Z", - "shell.execute_reply": "2026-07-27T03:55:07.343300Z" + "iopub.execute_input": "2026-07-28T15:24:24.422919Z", + "iopub.status.busy": "2026-07-28T15:24:24.422529Z", + "iopub.status.idle": "2026-07-28T15:24:28.037564Z", + "shell.execute_reply": "2026-07-28T15:24:28.036691Z" } }, "outputs": [], @@ -125,9 +124,9 @@ "id": "drtrl-training-heading", "metadata": {}, "source": [ - "## 4. Scan gradients over the sequence\n", + "## 4. Drive the sequence with `etrace_grad`\n", "\n", - "Hidden state and eligibility state are reset together at sequence boundaries. Each scan step differentiates one local loss; the scan carries the accumulated gradient forward. Repeated updates use `brainstate.transform.for_loop`, not a Python training loop.\n" + "Hidden state and eligibility state are reset together at sequence boundaries. `etrace_grad` owns the loop: it differentiates one local loss per step, carries the accumulated gradient forward, and divides by the step count when `reduction='mean'`. Repeated epoch updates use `brainstate.transform.for_loop`, not a Python training loop.\n" ] }, { @@ -136,10 +135,10 @@ "id": "drtrl-training", "metadata": { "execution": { - "iopub.execute_input": "2026-07-27T03:55:07.345823Z", - "iopub.status.busy": "2026-07-27T03:55:07.345823Z", - "iopub.status.idle": "2026-07-27T03:55:08.790986Z", - "shell.execute_reply": "2026-07-27T03:55:08.790986Z" + "iopub.execute_input": "2026-07-28T15:24:28.040222Z", + "iopub.status.busy": "2026-07-28T15:24:28.039875Z", + "iopub.status.idle": "2026-07-28T15:24:28.788468Z", + "shell.execute_reply": "2026-07-28T15:24:28.787459Z" } }, "outputs": [ @@ -157,7 +156,7 @@ }, { "data": { - "image/png": "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", + "image/png": "iVBORw0KGgoAAAANSUhEUgAAArEAAAFyCAYAAADiToKqAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjEwLjgsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvwVt1zgAAAAlwSFlzAAAPYQAAD2EBqD+naQAAZH1JREFUeJzt3XlYVPX+B/D3mQFm2JFdFEUFFVwgURBcSwrSVLQSzXLJa2XiEqmJ1/Vq17Q0Syl/ejO75UqamZmluKSJK3rNEnelVBZFGRbZ5pzfHyMjA6gM2zDD+/U8PM6c+Z5zPsOHqTeH7zlHkCRJAhERERGREZEZugAiIiIiIn0xxBIRERGR0WGIJSIiIiKjwxBLREREREaHIZaIiIiIjA5DLBEREREZHYZYIiIiIjI6DLFEREREZHQYYomIiIjI6DDEEhE9wahRo+Dl5VWldefOnQtBEGq2IBPn5eWFUaNGVWnd3r17o3fv3jVaT2VVp24i0h9DLJEJW7t2LQRB0H4plUp4eHggPDwcn376KbKzsyu9rVGjRulsS6FQoHXr1pg9ezby8/MBaP4nXnrMo77Wrl0LAOWW29nZoVevXvjxxx8f+V5OnDhRI9+b+uzq1auIjo5G69atYWVlBSsrK/j5+WH8+PE4c+aMztiSkFzyZW5uDi8vL0ycOBH37t0rt21BEBAdHV3hfr/99lsIgoD9+/c/tr7Dhw9j7ty5FW6fiKiumBm6ACKqff/617/QokULFBUVITU1Ffv378fkyZOxdOlSbN++HR07dqzUdhQKBf7zn/8AALKysvD9999j/vz5uHz5MtatW4dly5YhJydHO37nzp3YsGEDPv74Yzg7O2uXh4aGah8/++yzGDFiBCRJwvXr1/H555+jf//++OmnnxAeHl5D34HqWb16NURRrNK6M2fOxPTp0ys9fseOHYiKioKZmRmGDx8Of39/yGQyJCcnY+vWrfj8889x9epVNG/eXGe9zz//HDY2NsjNzUVCQgKWL1+OpKQkHDp0qEp1P87hw4cxb948jBo1Cg4ODjW+/fPnz0Mmq9oxll9++aWGqyGi+oohlqgBeP7559G5c2ft89jYWOzduxcvvPACBgwYgHPnzsHS0vKJ2zEzM8Orr76qff72228jNDQUGzZswNKlSxEZGakzPjU1FRs2bEBkZOQj/xzfunVrnW2++OKL8PPzwyeffFJvQqy5uXmV1zUzM4OZWeX+U3v58mUMHToUzZs3R0JCAho3bqzz+qJFi/DZZ59VGPBeeukl7S8Kb775JoYOHYpNmzbh2LFjCAoKqnL91SWKIgoLC6FUKiu9jkKhqPL+LCwsqrwuERkXTicgaqCeeeYZzJo1C9evX8c333xTpW0IgoDu3btDkiRcuXKlRury9fWFs7MzLl++XCPbAx7+CT0+Ph5+fn6wtLRESEgIfv/9dwDA//3f/8Hb2xtKpRK9e/fGtWvXdNYvOyf22rVrEAQBH330EVatWoVWrVpBoVCgS5cuOH78uM66+syJXbx4MXJzc/Hll1+WC7CAJhBPnDgRnp6eT9xWjx49AKBGv4+A5v1MnToVANCiRQvtNIaS71nJ93rdunVo164dFAoFdu3aBQD46KOPEBoaCicnJ1haWiIwMBDffvttuX2UnVtaMpXkt99+Q0xMDFxcXGBtbY1BgwYhIyNDZ92yc2L3798PQRCwefNmvP/++2jatCmUSiX69OmDS5culdt3XFwcWrZsCUtLSwQFBeHgwYPVmmd75coVvPzyy3B0dISVlRW6du1a4XSZ5cuXo127drCyskKjRo3QuXNnrF+/Xvt6dnY2Jk+eDC8vLygUCri6uuLZZ59FUlJSleoiMgU8EkvUgL322muYMWMGfvnlF4wdO7ZK2ygJL40aNaqRmrKysnD37l20atWqRrZX4uDBg9i+fTvGjx8PAFi4cCFeeOEFTJs2DZ999hnefvtt3L17F4sXL8brr7+OvXv3PnGb69evR3Z2Nt58800IgoDFixdj8ODBuHLlSpWO3u7YsQPe3t4IDg7We92yarovJQYPHowLFy6Umybi4uKiHbN3715s3rwZ0dHRcHZ21v4C8Mknn2DAgAEYPnw4CgsLsXHjRrz88svYsWMH+vXr98R9T5gwAY0aNcKcOXNw7do1LFu2DNHR0di0adMT1/3ggw8gk8kwZcoUZGVlYfHixRg+fDiOHj2qHfP5558jOjoaPXr0wDvvvINr164hMjISjRo1QtOmTfX8TgFpaWkIDQ1FXl4eJk6cCCcnJ3z11VcYMGAAvv32WwwaNAiAZrrKxIkT8dJLL2HSpEnIz8/HmTNncPToUbzyyisAgLfeegvffvstoqOj4efnhzt37uDQoUM4d+4cOnXqpHdtRKaAIZaoAWvatCns7e31Olp3+/ZtAJqwuW3bNmzZsgXt27dHmzZtqlRDfn4+bt++DUmSkJKSgpkzZ0KtVuOll16q0vYe5fz580hOTtYGqkaNGuHNN9/EggULcOHCBdja2gIA1Go1Fi5ciGvXrj3xigQpKSm4ePGiNii2adMGAwcOxM8//4wXXnhBr/pUKhVu3rxZbkoGANy7dw/FxcXa59bW1uWmf2RmZgIAcnNzsXfvXsTFxcHFxQU9e/bUq44n6dixIzp16vTYaSLnz5/H77//Dj8/P53lFy5c0Kk7OjoanTp1wtKlSysVYp2cnPDLL79oj2yLoohPP/0UWVlZsLe3f+y6+fn5OH36tHa6QaNGjTBp0iScPXsW7du3R2FhIWbNmoUuXbpg79692ikgHTt2xKhRo6oUYj/44AOkpaXh4MGD6N69OwBg7Nix6NixI2JiYjBw4EDIZDL8+OOPaNeuHeLj4x+5rR9//BFjx47FkiVLtMumTZumd01EpoTTCYgaOBsbm0pfpSA3NxcuLi5wcXGBt7c3pkyZgm7duuH777+v8mWkvvjiC7i4uMDV1RWdO3dGQkICpk2bhpiYmCpt71H69OmjE7hKjna++OKL2gBbenllpkdERUXpHOks+RN+VaZWqFQqAJp+lNW7d2/t993FxQVxcXHlxrRp0wYuLi7w8vLC66+/Dm9vb/z000+wsrLSu5bq6tWrV7kAC0AnwN69exdZWVno0aNHpf8k/sYbb+j8nPXo0QNqtRrXr19/4rqjR4/WmS9btlcnTpzAnTt3MHbsWJ05zMOHD6/y0eydO3ciKChIG2ABTX/feOMNXLt2DX/++ScAwMHBAX///Xe5qSilOTg44OjRo7h582aVaiEyRTwSS9TA5eTkwNXVFQBw//59ZGVl6bzu7u6ufaxUKvHDDz8AAP7++28sXrwY6enplTop7FEGDhyI6OhoFBYW4vjx4/j3v/+NvLy8Kp+d/ijNmjXTeV5y5K7s/NKS5Xfv3tV7myVh53HrZmZmorCwUPvc0tIS9vb22iBd+uoOJf7v//4P2dnZSEtL0zkJrrQtW7bAzs4OGRkZ+PTTT3H16tUq96W617Vt0aJFhct37NiBBQsW4PTp0ygoKNB7f1X5fld23ZIg7O3trTPOzMysytcIvn79eoVTQ3x9fbWvt2/fHu+99x727NmDoKAgeHt747nnnsMrr7yCbt26addZvHgxRo4cCU9PTwQGBqJv374YMWIEWrZsWaXaiEwBj8QSNWB///03srKytP/j3rRpExo3bqzzVZpcLkdYWBjCwsIwatQoJCQkIDU1FW+++WaVa2jatCnCwsLQt29fzJkzB0uXLsWKFSuwdevWar23suRyuV7LJUmq8jYft+7gwYN1vr+TJk0CoAnPjRs3xtmzZ8utExwcjLCwMJ1QU1bPnj0RFhaGYcOGYffu3bC0tMTw4cPLXRpMoVDg/v37FW4jLy8PAPS6kkBFKgrPBw8exIABA6BUKvHZZ59h586d2L17N1555ZVKfa+Buu9VXfH19cX58+exceNGdO/eHVu2bEH37t0xZ84c7ZghQ4bgypUrWL58OTw8PPDhhx+iXbt2+OmnnwxYOZFhMcQSNWBff/01AGgvZRUeHo7du3frfD1O48aN8c477+CHH37AkSNHaqSmN998E61atcLMmTPrRcCoaUuWLNH5/pae19ivXz9cunQJx44dq9Y+bGxsMGfOHJw+fRqbN2/Wea158+Y4f/58heuVLC97DdqyqnKkdsuWLVAqlfj555/x+uuv4/nnn0dYWJje26ktJe+57BULiouLy12tQp9tVvS9Tk5O1tknoJnnHBUVhS+//BIpKSno168f3n//fe2NRADN5+3tt9/Gtm3bcPXqVTg5OeH999+vUm1EpoAhlqiB2rt3L+bPn48WLVpg+PDhADT/kyw50lry9SQTJkyAlZUVPvjggxqpy8zMDO+++y7OnTuH77//vka2WZ8EBgbqfH9Lzx2dNm0arKys8PrrryMtLa3cuvqE+uHDh6Np06ZYtGiRzvK+ffviyJEjOHnypM7ye/fuYd26dQgICNCZQlIRa2tr7TqVJZfLIQgC1Gq1dtm1a9ewbdu2Sm+jNnXu3BlOTk5YvXq1zkl069atq9R0hYr07dsXx44dQ2JionZZbm4uVq1aBS8vL23v79y5o7OehYUF/Pz8IEkSioqKoFary03zcXV1hYeHh860DKKGhnNiiRqAn376CcnJySguLkZaWhr27t2L3bt3o3nz5ti+fXu1/nzs5OSE0aNH47PPPsO5c+e08/2qY9SoUZg9ezYWLVpU7mz9NWvWaK87WtqkSZN0TtAyRj4+Pli/fj2GDRuGNm3aaO/YJUkSrl69ivXr10Mmk1XqTHlzc3NMmjQJU6dOxa5duxAREQEAmD59OuLj49GzZ0+8+eabaNu2LW7evIm1a9fi1q1b+PLLL5+47cDAQADAP//5TwwdOhTm5ubo37+/NtxWpF+/fli6dCkiIiLwyiuvID09HXFxcfD29i53K11DsLCwwNy5czFhwgQ888wzGDJkCK5du4a1a9eiVatWVTr6PH36dGzYsAHPP/88Jk6cCEdHR3z11Ve4evUqtmzZop33/dxzz8Hd3R3dunWDm5sbzp07hxUrVqBfv36wtbXFvXv30LRpU7z00kvw9/eHjY0N9uzZg+PHj+tcrYCooWGIJWoAZs+eDUDzP2pHR0d06NABy5Ytw+jRo2sk+MXExGDlypVYtGgR1q5dW+3tWVpaIjo6GnPnzsX+/ft1LjT/+eefV7jOqFGjjD7EApoT3X7//XcsWbIEv/zyC9asWQNBENC8eXP069cPb731Fvz9/Su1rTfeeAMLFizABx98oA2xbm5uOHr0KObOnYvNmzcjLS0NdnZ2CA0NxaZNmyp1jdouXbpg/vz5WLlyJXbt2gVRFHH16tXHhthnnnkGX3zxBT744ANMnjwZLVq0wKJFi3Dt2rV6EWIBzSW/JEnCkiVLMGXKFPj7+2P79u2YOHFilX7Rc3Nzw+HDh/Hee+9h+fLlyM/PR8eOHfHDDz/oXFLszTffxLp167B06VLk5OSgadOmmDhxImbOnAkAsLKywttvv41ffvkFW7duhSiK8Pb2xmeffYZx48bV2PsnMjaCZIqTzoiIiGqAKIpwcXHB4MGDsXr1akOXQ0SlcE4sERERNDdEKHtc57///S8yMzOrfNtZIqo9PBJLREQEYP/+/XjnnXfw8ssvw8nJCUlJSfjiiy/g6+uLkydP6twsgYgMj3NiiYiIAHh5ecHT0xOffvopMjMz4ejoiBEjRuCDDz5ggCWqh3gkloiIiIiMDufEEhEREZHRYYglIiIiIqPDObEVEEURN2/ehK2tbZUucE1ERERETyZJErKzs+Hh4aG9AUhlMcRW4ObNm/D09DR0GUREREQNwl9//VWpuxGWxhBbgZK7/vz111+ws7Or9f2JooiMjAy4uLjo/VsI1R/so+lgL00D+2g62EvTUbaXKpUKnp6eVbrjIkNsBUqmENjZ2dVZiM3Pz4ednR0/nEaMfTQd7KVpYB9NB3tpOh7Vy6pM3+RPAhEREREZHYZYIiIiIjI6DLFEREREZHQYYomIiIjI6DDEEhEREZHRYYglIiIiIqNj8BAbFxcHLy8vKJVKBAcH49ixY48dHx8fj7Zt20KpVKJDhw7YuXOnzus5OTmIjo5G06ZNYWlpCT8/P6xcubI23wIRERER1TGDhthNmzYhJiYGc+bMQVJSEvz9/REeHo709PQKxx8+fBjDhg3DmDFjcOrUKURGRiIyMhJnz57VjomJicGuXbvwzTff4Ny5c5g8eTKio6Oxffv2unpbRERERFTLDBpily5dirFjx2L06NHaI6ZWVlZYs2ZNheM/+eQTREREYOrUqfD19cX8+fPRqVMnrFixQjvm8OHDGDlyJHr37g0vLy+88cYb8Pf3f+IRXiIiIiIyHgYLsYWFhTh58iTCwsIeFiOTISwsDImJiRWuk5iYqDMeAMLDw3XGh4aGYvv27bhx4wYkScK+fftw4cIFPPfcc7XzRqpp44F8DJ6fhS1H9L9TBREREVFDZbDbzt6+fRtqtRpubm46y93c3JCcnFzhOqmpqRWOT01N1T5fvnw53njjDTRt2hRmZmaQyWRYvXo1evbs+chaCgoKUFBQoH2uUqkAaG6NJoqi3u9NH5nZavz5lxoutkKt74tqlyiKkCSJfTQB7KVpYB9NB3tpOsr2sjo9NViIrS3Lly/HkSNHsH37djRv3hy//vorxo8fDw8Pj3JHcUssXLgQ8+bNK7c8IyMD+fn5tVqvtzMAmOH0NSAtLR1yucHPtaMqEkURWVlZkCSJ9/Y2cuylaWAfTQd7aTrK9jI7O7vK2zJYiHV2doZcLkdaWprO8rS0NLi7u1e4jru7+2PH379/HzNmzMB3332Hfv36AQA6duyI06dP46OPPnpkiI2NjUVMTIz2uUqlgqenJ1xcXGBnZ1fl91gZPRtJsDC7i6w8GfIkJ7RyNa/V/VHtEUURgiDAxcWF/5E1cuylaWAfTQd7aTrK9lKpVFZ5WwYLsRYWFggMDERCQgIiIyMBaN5YQkICoqOjK1wnJCQECQkJmDx5snbZ7t27ERISAgAoKipCUVFRuR9wuVz+2MPVCoUCCoWi3HKZTFbrHxalAujYwgwnLhbj5GU1fJqWr4OMhyAIdfJzQ7WPvTQN7KPpYC9NR+leVqefBv1JiImJwerVq/HVV1/h3LlzGDduHHJzczF69GgAwIgRIxAbG6sdP2nSJOzatQtLlixBcnIy5s6dixMnTmhDr52dHXr16oWpU6di//79uHr1KtauXYv//ve/GDRokEHeY2V0aa35XeLkxWIDV0JERERkHAw6JzYqKgoZGRmYPXs2UlNTERAQgF27dmlP3kpJSdFJ6KGhoVi/fj1mzpyJGTNmwMfHB9u2bUP79u21YzZu3IjY2FgMHz4cmZmZaN68Od5//3289dZbdf7+KivQ2xxAPo4zxBIRERFViiBJkmToIuoblUoFe3t7ZGVl1fqcWABQ5akRPDkTalHA/kWN4OEkr/V9Us0TRRHp6elwdXXln7uMHHtpGthH08Femo6yvaxO5uJPQj1goxTg01jz+MTFIsMWQ0RERGQEGGLriY5emgPixy9wSgERERHRkzDE1hP+D0Isj8QSERERPRlDbD3RsbkmxF6+pUZmNu9IQkRERPQ4DLH1hL0V4OOhOaGLR2OJiIiIHo8hth7p7KO54tmJCwyxRERERI/DEFuPBJaEWF4vloiIiOixGGLrkc4+5gCAP1OKkXOf82KJiIiIHoUhth5xbyRDU2cZRAlIusyjsURERESPwhBbz3RprTkay3mxRERERI/GEFvPlEwpOM4rFBARERE9EkNsPVNyJPbM1WIUFEkGroaIiIiofmKIrWeau8rgYi+gqFgTZImIiIioPIbYekYQhIdTCjgvloiIiKhCDLH1UOeSk7s4L5aIiIioQgyx9VDJkdhTl4pRrOa8WCIiIqKyGGLrodZN5LCzEpBbIOHcX5wXS0RERFQWQ2w9JJcJCPTW3IL2+AWGWCIiIqKyGGLrqZIpBZwXS0RERFQeQ2w91aXUyV2iyHmxRERERKUxxNZTfs3NoLQA7uVIuHxLbehyiIiIiOoVhth6ysJMQEBLTikgIiIiqghDbD1WMqWAJ3cRERER6WKIrcc6+zy4QsHFIkgS58USERERlWCIrccCWprDTA6k3RXx923R0OUQERER1Rv1IsTGxcXBy8sLSqUSwcHBOHbs2GPHx8fHo23btlAqlejQoQN27typ87ogCBV+ffjhh7X5NmqcpUJA++Yl14vlvFgiIiKiEgYPsZs2bUJMTAzmzJmDpKQk+Pv7Izw8HOnp6RWOP3z4MIYNG4YxY8bg1KlTiIyMRGRkJM6ePasdc+vWLZ2vNWvWQBAEvPjii3X1tmpM6UttEREREZGGwUPs0qVLMXbsWIwePRp+fn5YuXIlrKyssGbNmgrHf/LJJ4iIiMDUqVPh6+uL+fPno1OnTlixYoV2jLu7u87X999/j6effhotW7asq7dVYzozxBIRERGVY9AQW1hYiJMnTyIsLEy7TCaTISwsDImJiRWuk5iYqDMeAMLDwx85Pi0tDT/++CPGjBlTc4XXoUBvMwgCcC1NREYW58USERERAYCZIXd++/ZtqNVquLm56Sx3c3NDcnJyheukpqZWOD41NbXC8V999RVsbW0xePDgR9ZRUFCAgoIC7XOVSgUAEEURolj7wVEURUiSVOG+bJRAmyZyJP+txvHzhYjobFHr9VDVPK6PZFzYS9PAPpoO9tJ0lO1ldXpq0BBbF9asWYPhw4dDqVQ+cszChQsxb968csszMjKQn59fm+UB0DQwKysLkiRBJit/cNyvqQzJf8tw8IwKnZrxA1xfPamPZDzYS9PAPpoO9tJ0lO1ldnZ2lbdl0BDr7OwMuVyOtLQ0neVpaWlwd3evcB13d/dKjz948CDOnz+PTZs2PbaO2NhYxMTEaJ+rVCp4enrCxcUFdnZ2lX07VSaKIgRBgIuLS4Ufzp4dC7H1SA7++Nscrq72tV4PVc2T+kjGg700Deyj6WAvTUfZXj7uIOOTGDTEWlhYIDAwEAkJCYiMjASgeXMJCQmIjo6ucJ2QkBAkJCRg8uTJ2mW7d+9GSEhIubFffPEFAgMD4e/v/9g6FAoFFApFueUymazOPiyCIDxyf13aaKYQnL+hRk4+YGfFD3B99bg+knFhL00D+2g62EvTUbqX1emnwX8SYmJisHr1anz11Vc4d+4cxo0bh9zcXIwePRoAMGLECMTGxmrHT5o0Cbt27cKSJUuQnJyMuXPn4sSJE+VCr0qlQnx8PP7xj3/U6fupDS72Mni5ySBJwMlLvAUtERERkcHnxEZFRSEjIwOzZ89GamoqAgICsGvXLu3JWykpKTopPTQ0FOvXr8fMmTMxY8YM+Pj4YNu2bWjfvr3Odjdu3AhJkjBs2LA6fT+1pbOPOa6lFeDEhSI83ZEndxEREVHDJkiSJBm6iPpGpVLB3t4eWVlZdTYnNj09Ha6uro88rL71t3xM/zIHT7Uyw6ZYh1qvifRXmT6ScWAvTQP7aDrYS9NRtpfVyVz8STASJXfu+v1aMe4X8PcOIiIiatgYYo1EU2cZ3BvJUKwGTl/h3buIiIioYWOINRKCIKCzT8ktaHlyFxERETVsDLFGpEtrzXl4xy/wSCwRERE1bAyxRqTkSOzpK0UoLOa8WCIiImq4GGKNSKvGcjjYCMgvBP68zikFRERE1HAxxBoRmUxAoHfJvFhOKSAiIqKGiyHWyJRcaovzYomIiKghY4g1MiUnd528VAxR5LxYIiIiapgYYo2Mr6cZrBUCVHkSLtxQG7ocIiIiIoNgiDUyZnIBT3k/uNQW58USERFRA8UQa4S0Nz3gvFgiIiJqoBhijVDJyV0nLhZBkjgvloiIiBoehlgj1LGFGczNgIwsCdfTRUOXQ0RERFTnGGKNkMJcQMcWmnmxvF4sERERNUQMsUaqiw+vF0tEREQNF0OskercmnfuIiIiooaLIdZIdWplBpkA/JUhIjWT14slIiKihoUh1kjZWMrg16xkXmyxgashIiIiqlsMsUassw9P7iIiIqKGiSHWiJXMi+XJXURERNTQMMQasZI7d128qcbdHF4vloiIiBoOhlgj5mgrQ6vGcgDASU4pICIiogaEIdbIPbwFLU/uIiIiooaDIdbIlZzcxXmxRERE1JAwxBq5kiOxf6YUIzdfMnA1RERERHXD4CE2Li4OXl5eUCqVCA4OxrFjxx47Pj4+Hm3btoVSqUSHDh2wc+fOcmPOnTuHAQMGwN7eHtbW1ujSpQtSUlJq6y0YVGNHOZo4yaAWgdOXeTSWiIiIGgaDhthNmzYhJiYGc+bMQVJSEvz9/REeHo709PQKxx8+fBjDhg3DmDFjcOrUKURGRiIyMhJnz57Vjrl8+TK6d++Otm3bYv/+/Thz5gxmzZoFpVJZV2+rzmkvtcWTu4iIiKiBECRJMtjfoIODg9GlSxesWLECACCKIjw9PTFhwgRMnz693PioqCjk5uZix44d2mVdu3ZFQEAAVq5cCQAYOnQozM3N8fXXX1e5LpVKBXt7e2RlZcHOzq7K26ksURSRnp4OV1dXyGT6/16x+dd8zPxvDoJam+GbaQ41XyBVSnX7SPUHe2ka2EfTwV6ajrK9rE7mMqulGp+osLAQJ0+eRGxsrHaZTCZDWFgYEhMTK1wnMTERMTExOsvCw8Oxbds2AJpvzI8//ohp06YhPDwcp06dQosWLRAbG4vIyMhH1lJQUICCggLtc5VKpd2eKNb+9VdFUYQkSVXeVydvzWW2Tl8pRn6BGhbmQk2WR5VU3T5S/cFemgb20XSwl6ajbC+r01O9Q+yuXbtgY2OD7t27A9DMaV29ejX8/PwQFxeHRo0aVWo7t2/fhlqthpubm85yNzc3JCcnV7hOampqheNTU1MBAOnp6cjJycEHH3yABQsWYNGiRdi1axcGDx6Mffv2oVevXhVud+HChZg3b1655RkZGcjPz6/U+6kOURSRlZUFSZKq9BumtQA0spbjbq6AX09loKNXzddIT1bdPlL9wV6aBvbRdLCXpqNsL7Ozs6u8Lb1D7NSpU7Fo0SIAwO+//453330XMTEx2LdvH2JiYvDll19WuZjqKknzAwcOxDvvvAMACAgIwOHDh7Fy5cpHhtjY2FidI7wqlQqenp5wcXGps+kEgiDAxcWlyh/OLm2y8UtSES7fsUVYkGUNV0iVURN9pPqBvTQN7KPpYC9NR9leVuecJb1D7NWrV+Hn5wcA2LJlC1544QX8+9//RlJSEvr27Vvp7Tg7O0MulyMtLU1neVpaGtzd3Stcx93d/bHjnZ2dYWZmpq2vhK+vLw4dOvTIWhQKBRQKRbnlMpmszj4sgiBUa39BrS3wS1IRTlwsxrh+/IAbSnX7SPUHe2ka2EfTwV6ajtK9rE4/9V7TwsICeXl5AIA9e/bgueeeAwA4Ojpq55JWdjuBgYFISEjQLhNFEQkJCQgJCalwnZCQEJ3xALB7927teAsLC3Tp0gXnz5/XGXPhwgU0b9680rUZo5IrFCRdKoZa5PViiYiIyLTpfSS2e/fuiImJQbdu3XDs2DFs2rQJgCYoNm3aVK9txcTEYOTIkejcuTOCgoKwbNky5ObmYvTo0QCAESNGoEmTJli4cCEAYNKkSejVqxeWLFmCfv36YePGjThx4gRWrVql3ebUqVMRFRWFnj174umnn8auXbvwww8/YP/+/fq+VaPSpqkcNpYCcu5LSP5LjXbNDXbOHhEREVGt0/tI7IoVK2BmZoZvv/0Wn3/+OZo0aQIA+OmnnxAREaHXtqKiovDRRx9h9uzZCAgIwOnTp7Fr1y7tyVspKSm4deuWdnxoaCjWr1+PVatWwd/fH99++y22bduG9u3ba8cMGjQIK1euxOLFi9GhQwf85z//wZYtW7QnopkquUxAoLcmuJ7g9WKJiIjIxBn0OrH1lbFdJ7bE/+3Mw5KteXiukwVWvF37dZMuXsfQdLCXpoF9NB3spemoyevE6v2TkJSUhN9//137/Pvvv0dkZCRmzJiBwsJCfTdHNajLg3mxJy4Wgb+bEBERkSnTO8S++eabuHDhAgDgypUrGDp0KKysrBAfH49p06bVeIFUee29zKAwBzKzJVxJVRu6HCIiIqJao3eIvXDhAgICAgAA8fHx6NmzJ9avX4+1a9diy5YtNV0f6cHCTEBAS83R2OMXig1cDREREVHt0TvElr5V2J49e7TXhvX09MTt27drtjrSW+fWPLmLiIiITJ/eIbZz585YsGABvv76axw4cAD9+vUDoLkJQtlbwlLd6+zzYF7sBYZYIiIiMl16h9hly5YhKSkJ0dHR+Oc//wlvb28AwLfffovQ0NAaL5D081Qrc5jJgZuZIm7c4bxYIiIiMk16XxG/Y8eOOlcnKPHhhx9CLpfXSFFUdVYKAX7NzHDmajFOXChCkxD2hIiIiExPlW/rdPLkSZw7dw4A4Ofnh06dOtVYUVQ9XVqb48zVYhy/WISBIUpDl0NERERU4/QOsenp6YiKisKBAwfg4OAAALh37x6efvppbNy4ES4uLjVdI+mpi48ZvvgZOMErFBAREZGJ0ntO7IQJE5CTk4M//vgDmZmZyMzMxNmzZ6FSqTBx4sTaqJH01Mlbc3LXlVQ17qhEA1dDREREVPP0DrG7du3CZ599Bl9fX+0yPz8/xMXF4aeffqrR4qhqHGxkaNNEMxeWl9oiIiIiU6R3iBVFEebm5uWWm5uba68fS4YXWOoWtERERESmRu8Q+8wzz2DSpEm4efOmdtmNGzfwzjvvoE+fPjVaHFVdF5+SO3cxxBIREZHp0TvErlixAiqVCl5eXmjVqhVatWqFFi1aQKVSYfny5bVRI1VByZ27kv9SIzuPR8iJiIjItOh9dQJPT08kJSVhz549SE5OBgD4+voiLCysxoujqnNzkKOZiwwpGSKSLhejVwcLQ5dEREREVGOqdJ1YQRDw7LPP4tlnn63peqgGdWltjpSMAhw8W8gQS0RERCalUiH2008/rfQGeZmt+iM8UIEtvxVg+5ECTHvJGhbmgqFLIiIiIqoRlQqxH3/8caU2JggCQ2w90qO9OdwayZB2V8TuU4XoF6QwdElERERENaJSIfbq1au1XQfVArlMwEvdFIjbcR+bD+YzxBIREZHJ0PvqBGRcXuyuhCAAieeKkJKhNnQ5RERERDWCIdbENXWWI9RXc83YLYfyDVwNERERUc1giG0AXu6hBABs+a0AxWrJwNUQERERVR9DbAMQFmABBxsB6fdEHDzLO3gRERGR8WOIbQAszAUMCtGc1LX5IKcUEBERkfGrUog9ePAgXn31VYSEhODGjRsAgK+//hqHDh2q0eKo5pRMKdh/phDp93gbWiIiIjJueofYLVu2IDw8HJaWljh16hQKCgoAAFlZWfj3v/9dpSLi4uLg5eUFpVKJ4OBgHDt27LHj4+Pj0bZtWyiVSnTo0AE7d+7UeX3UqFEQBEHnKyIiokq1mQpvDzN0amUGtQh8d5hHY4mIiMi46R1iFyxYgJUrV2L16tUwNzfXLu/WrRuSkpL0LmDTpk2IiYnBnDlzkJSUBH9/f4SHhyM9Pb3C8YcPH8awYcMwZswYnDp1CpGRkYiMjMTZs2d1xkVERODWrVvarw0bNuhdm6kpORobfzAfksQTvIiIiMh46R1iz58/j549e5Zbbm9vj3v37uldwNKlSzF27FiMHj0afn5+WLlyJaysrLBmzZoKx3/yySeIiIjA1KlT4evri/nz56NTp05YsWKFzjiFQgF3d3ftV6NGjfSuzdREdFbAWikgJUPEsfM8wYuIiIiMV6Xu2FWau7s7Ll26BC8vL53lhw4dQsuWLfXaVmFhIU6ePInY2FjtMplMhrCwMCQmJla4TmJiImJiYnSWhYeHY9u2bTrL9u/fD1dXVzRq1AjPPPMMFixYACcnpwq3WVBQoJ0WAQAqlQoAIIoiRLH254+KoghJkmp9X5YWQL8uFth8sACbD+ajS2u920+PUVd9pNrHXpoG9tF0sJemo2wvq9NTvVPM2LFjMWnSJKxZswaCIODmzZtITEzElClTMGvWLL22dfv2bajVari5ueksd3NzQ3JycoXrpKamVjg+NTVV+zwiIgKDBw9GixYtcPnyZcyYMQPPP/88EhMTIZfLy21z4cKFmDdvXrnlGRkZyM+v/fmjoigiKysLkiRBJqvdC0b0aQdsPmiGn08W4K2wPNha1uruGpS67CPVLvbSNLCPpoO9NB1le5mdnV3lbekdYqdPnw5RFNGnTx/k5eWhZ8+eUCgUmDJlCiZMmFDlQmrS0KFDtY87dOiAjh07olWrVti/fz/69OlTbnxsbKzO0V2VSgVPT0+4uLjAzs6u1usVRRGCIMDFxaXWP5wuLhLaNFXh/N9qJF62w6vPKGt1fw1JXfaRahd7aRrYR9PBXpqOsr1UKqueQ/QOsYIg4J///CemTp2KS5cuIScnB35+frCxsdF7587OzpDL5UhLS9NZnpaWBnd39wrXcXd312s8ALRs2RLOzs64dOlShSFWoVBAoVCUWy6TyerswyIIQp3t7+UeSizYkIv4QwV4rY8lBEGo9X02FHXZR6pd7KVpYB9NB3tpOkr3sjr9rPKaFhYW8PPzQ1BQUJUCbMk2AgMDkZCQoF0miiISEhIQEhJS4TohISE64wFg9+7djxwPAH///Tfu3LmDxo0bV6lOUzMgWAELM+D832qcvV5s6HKIiIiI9Kb3kdjc3Fx88MEHSEhIQHp6erkJuVeuXNFrezExMRg5ciQ6d+6MoKAgLFu2DLm5uRg9ejQAYMSIEWjSpAkWLlwIAJg0aRJ69eqFJUuWoF+/fti4cSNOnDiBVatWAQBycnIwb948vPjii3B3d8fly5cxbdo0eHt7Izw8XN+3a5IcbGQID1Tgh6MFiD9YgA5e5k9eiYiIiKge0TvE/uMf/8CBAwfw2muvoXHjxtX+U3RUVBQyMjIwe/ZspKamIiAgALt27dKevJWSkqJzqDk0NBTr16/HzJkzMWPGDPj4+GDbtm1o3749AEAul+PMmTP46quvcO/ePXh4eOC5557D/PnzK5wy0FC93EMTYn84WoDpQ6xhpeCUAiIiIjIegqTnVe8dHBzw448/olu3brVVk8GpVCrY29sjKyurzk7sSk9Ph6ura53N9RFFCc/98y5SMkR8MNoGg7vxBK/qMkQfqXawl6aBfTQd7KXpKNvL6mQuvX8SGjVqBEdHR31Xo3pGJhPw0oM7eG0+yNvQEhERkXHRO8TOnz8fs2fPRl5eXm3UQ3VoUKgCchmQdKkYl27yBC8iIiIyHnrPiV2yZAkuX74MNzc3eHl5wdxc96SgpKSkGiuOapebgxy9O1og4XQhvj1UgOlDeAcvIiIiMg56p5bIyMhaKIMM5eXuCiScLsR3h/MRM8gKFuY8wYuIiIjqP71D7Jw5c2qjDjKQnh0s4GovQ3qWiIT/FeL5zryCAxEREdV/PMWvgTOTCxjcTRNc43mCFxERERmJSoVYR0dH3L59G8DDqxM86ouMz0vdNVcp+O3PIvx9W23gaoiIiIierFLTCT7++GPY2toCAJYtW1ab9ZABNHOVo2tbcxxJLsKW3/IxaaC1oUsiIiIieqxKhdiRI0dW+JhMx5CeSk2IPVSA6P5WkMt4ghcRERHVX5UKsSqVqtIbrIs7XFHNe/YpCzhYC0i9K+LQH0Xo1cHC0CURERERPVKlQqyDgwME4fFH5iRJgiAIUKs5p9IYKcwFDAxR4Ks9+Yg/mM8QS0RERPVapULsvn37arsOqgde6q7EV3vysfd/hbidJcLZnhevICIiovqpUiG2V69etV0H1QNtmprBv6UZ/nelGNsS8/GPCCtDl0RERERUoSrdZ/TevXs4duwY0tPTIYqizmsjRoyokcLIMF7ursT/ruQg/mABxoRbPnEaCREREZEh6B1if/jhBwwfPhw5OTmws7PTCTmCIDDEGrm+QRb49ybgapoaJy4Wo0trc0OXRERERFSO3pMe3333Xbz++uvIycnBvXv3cPfuXe1XZmZmbdRIdchGKUPfLryDFxEREdVveofYGzduYOLEibCy4nxJUzWkh+YOXrtOFkCVJz5hNBEREVHd0zvEhoeH48SJE7VRC9UT/i3N4OMhR34hsONogaHLISIiIipH7zmx/fr1w9SpU/Hnn3+iQ4cOMDfXnTM5YMCAGiuODEMQBLzcQ4l/b8pF/MF8vPK0paFLIiIiItKhd4gdO3YsAOBf//pXudd4swPTMaCrAh9uycUfKWr8cb0Y7ZpX6UIWRERERLVC7+kEoig+8osB1nQ42srw7FOau3bFH+IJXkRERFS/8JZM9EgvPzjB64cjBbhfIBm4GiIiIqKHqhRiDxw4gP79+8Pb2xve3t4YMGAADh48WNO1kYGFtDVHU2cZsu9L+DmJJ3gRERFR/aF3iP3mm28QFhYGKysrTJw4ERMnToSlpSX69OmD9evX10aNZCAymYCXumuOxvKasURERFSf6H22zvvvv4/FixfjnXfe0S6bOHEili5divnz5+OVV16p0QLJsAaHKvDp93k4fqEYV1KL0dKdJ3gRERGR4el9JPbKlSvo379/ueUDBgzA1atXq1REXFwcvLy8oFQqERwcjGPHjj12fHx8PNq2bQulUokOHTpg586djxz71ltvQRAELFu2rEq1NXTujnL07KC5jNq3BzmlgIiIiOoHvUOsp6cnEhISyi3fs2cPPD099S5g06ZNiImJwZw5c5CUlAR/f3+Eh4cjPT29wvGHDx/GsGHDMGbMGJw6dQqRkZGIjIzE2bNny4397rvvcOTIEXh4eOhdFz1UcoLXd4fzUVjME7yIiIjI8PQOse+++y4mTpyIcePG4euvv8bXX3+Nt956C5MnT8aUKVP0LmDp0qUYO3YsRo8eDT8/P6xcuRJWVlZYs2ZNheM/+eQTREREYOrUqfD19cX8+fPRqVMnrFixQmfcjRs3MGHCBKxbt67cDRlIP707WMDZTsCdbAn7/ldo6HKIiIiI9J8TO27cOLi7u2PJkiXYvHkzAMDX1xebNm3CwIED9dpWYWEhTp48idjYWO0ymUyGsLAwJCYmVrhOYmIiYmJidJaFh4dj27Zt2ueiKOK1117D1KlT0a5duyfWUVBQgIKCh38qV6lU2u2IoqjPW6oSURQhSVKd7Ksq5DJgUKgCq3flI/5gPp59ir8UVKS+95Eqj700Deyj6WAvTUfZXlanp1U6S2fQoEEYNGhQlXda4vbt21Cr1XBzc9NZ7ubmhuTk5ArXSU1NrXB8amqq9vmiRYtgZmaGiRMnVqqOhQsXYt68eeWWZ2RkID+/9s/KF0URWVlZkCQJMln9vHRv77bA6l1mOPhHIX6/kA43B0NXVP8YQx+pcthL08A+mg720nSU7WV2dnaVt2Vyp5qfPHkSn3zyCZKSkiAIQqXWiY2N1Tm6q1Kp4OnpCRcXF9jZ2dVWqVqiKEIQBLi4uNTbD6erKxDUWoVjF4rx6wVbjH/B0tAl1TvG0EeqHPbSNLCPpoO9NB1le6lUKqu8LYOGWGdnZ8jlcqSlpeksT0tLg7u7e4XruLu7P3b8wYMHkZ6ejmbNmmlfV6vVePfdd7Fs2TJcu3at3DYVCgUUCkW55TKZrM4+LIIg1On+qmJITyWOXcjBlkMFePsFK8hllfsloSExhj5S5bCXpoF9NB3speko3cvq9NOgPwkWFhYIDAzUudqBKIpISEhASEhIheuEhISUuzrC7t27teNfe+01nDlzBqdPn9Z+eXh4YOrUqfj5559r7800AM91UsDOSsDNTBGJ54oMXQ4RERE1YAafThATE4ORI0eic+fOCAoKwrJly5Cbm4vRo0cDAEaMGIEmTZpg4cKFAIBJkyahV69eWLJkCfr164eNGzfixIkTWLVqFQDAyckJTk5OOvswNzeHu7s72rRpU7dvzsQoLQQM6KrAN3s1J3h1b2dh6JKIiIiogTJ4iI2KikJGRgZmz56N1NRUBAQEYNeuXdqTt1JSUnQONYeGhmL9+vWYOXMmZsyYAR8fH2zbtg3t27c31FtoUF7uocQ3e/Ox51QhMrNFONryzzpERERU9wRJkvS6er1arcbatWuRkJCA9PT0cpdG2Lt3b40WaAgqlQr29vbIysqqsxO70tPT4erqahRzfQYvuIez14oxfYg1Xn+OJ3iVMLY+0qOxl6aBfTQd7KXpKNvL6mQuvY/ETpo0CWvXrkW/fv3Qvn37Sl8BgEzHkB4KnL1WjPiD+Rj9rJI/A0RERFTn9A6xGzduxObNm9G3b9/aqIeMwAtBCizclIvLt9Q4eakYnX148wMiIiKqW3ofk7ewsIC3t3dt1EJGwsZShn5BmkuSfbA5F2pRrxkpRERERNWmd4h999138cknn0DPqbRkYiZFWsHGUsCZq8VYt6/272pGREREVJre0wkOHTqEffv24aeffkK7du1gbq77p+StW7fWWHFUf7k5yDFlsBXmrsvFx1vz8OxTFmjsKDd0WURERNRA6B1iHRwcMGjQoNqohYzM0F5KbD9SgKTLxfjX+lx8Nt6WJ3kRERFRndA7xH755Ze1UQcZIZlMwL9G2CDyX/eQcLoQvyQVIjyw/O17iYiIiGoaL7ZG1dK6iRnGRmiuFTt/Qy6y88QnrEFERERUfVW6Y9e3336LzZs3IyUlBYWFhTqvJSUl1UhhZDzG9bPCzuMFuJ4uYsl3eZg73MbQJREREZGJ0/tI7KefforRo0fDzc0Np06dQlBQEJycnHDlyhU8//zztVEj1XNKCwH/ek0TXDfsz8epy0UGroiIiIhMnd4h9rPPPsOqVauwfPlyWFhYYNq0adi9ezcmTpyIrKys2qiRjECIrwUGhyogScCs/+agsJiXYCMiIqLao3eITUlJQWhoKADA0tIS2dnZAIDXXnsNGzZsqNnqyKi8N8QajWwEXLihxhc/3zd0OURERGTC9A6x7u7uyMzMBAA0a9YMR44cAQBcvXqVN0Bo4BrZyDAjyhoAEPdDHq6lqQ1cEREREZkqvUPsM888g+3btwMARo8ejXfeeQfPPvssoqKieP1YwoCuCnTzM0dhMTD76xz+YkNERES1Qu+rE6xatQqiqLmM0vjx4+Hk5ITDhw9jwIABePPNN2u8QDIugiBg3qs26DfnLo4kF+G7wwUY3E1p6LKIiIjIxOgdYmUyGWSyhwdwhw4diqFDh9ZoUWTcmrnKMWGAFT7akocP4nPRu6MFHG15SWIiIiKqOVVKFgcPHsSrr76KkJAQ3LhxAwDw9ddf49ChQzVaHBmv0c9aok1TOe7lSFi4OdfQ5RAREZGJ0TvEbtmyBeHh4bC0tMSpU6dQUFAAAMjKysK///3vGi+QjJO5mYAFI2wgCMD3iQX47Y/CJ69EREREVEl6h9gFCxZg5cqVWL16NczNzbXLu3Xrxrt1kQ7/luZ49WnNfNjZ3+TgfgFP8iIiIqKaoXeIPX/+PHr27Fluub29Pe7du1cTNZEJeWeQFdwayfBXhoi4HXmGLoeIiIhMRJWuE3vp0qVyyw8dOoSWLVvWSFFkOmwsZZjziubasWt+uY/kv4oNXBERERGZAr1D7NixYzFp0iQcPXoUgiDg5s2bWLduHaZMmYJx48bVRo1k5MKeUuDZpyxQrAZmfZ0DtchpBURERFQ9el9ia/r06RBFEX369EFeXh569uwJhUKBKVOmYMKECbVRI5mAWa9Y4/C5IvzvSjHW78/Ha89YGrokIiIiMmJ6H4kVBAH//Oc/kZmZibNnz+LIkSPIyMjA/Pnza6M+MhHujeSY8qIVAGDp1jykZvKWtERERFR1Vb4CvYWFBfz8/BAUFAQbG5uarIlM1LBeSgS0NENuvoR/beC1Y4mIiKjqKj2d4PXXX6/UuDVr1uhdRFxcHD788EOkpqbC398fy5cvR1BQ0CPHx8fHY9asWbh27Rp8fHywaNEi9O3bV/v63LlzsXHjRvz111+wsLBAYGAg3n//fQQHB+tdG9UcmUzA/BE2GDT/HvacKsQvSQV4rpPC0GURERGREar0kdi1a9di3759uHfvHu7evfvIL31t2rQJMTExmDNnDpKSkuDv74/w8HCkp6dXOP7w4cMYNmwYxowZg1OnTiEyMhKRkZE4e/asdkzr1q2xYsUK/P777zh06BC8vLzw3HPPISMjQ+/6qGa1aWqGf4Rr5sP+a30ucu6LBq6IiIiIjJEgSVKlThUfP348NmzYgObNm2P06NF49dVX4ejoWO0CgoOD0aVLF6xYsQIAIIoiPD09MWHCBEyfPr3c+KioKOTm5mLHjh3aZV27dkVAQABWrlxZ4T5UKhXs7e2xZ88e9OnT54k1lYzPysqCnZ1dFd9Z5YmiiPT0dLi6ukImq/IMD6ORXyih/9y7uJ4uYvjTSswZbhrTURpaH00Ze2ka2EfTwV6ajrK9rE7mqvRPQlxcHG7duoVp06bhhx9+gKenJ4YMGYKff/4ZlczB5RQWFuLkyZMICwt7WJBMhrCwMCQmJla4TmJios54AAgPD3/k+MLCQqxatQr29vbw9/evUp1Us5QWAua9pgmu6/fn4/TlIgNXRERERMZGr0tsKRQKDBs2DMOGDcP169exdu1avP322yguLsYff/yh9wlet2/fhlqthpubm85yNzc3JCcnV7hOampqheNTU1N1lu3YsQNDhw5FXl4eGjdujN27d8PZ2bnCbRYUFKCgoED7XKVSAdD8tiCKtf/nblEUIUlSneyrvujaxgwDQyzwfWIh/vlVDrbOtIO5mWDosqqlIfbRVLGXpoF9NB3speko28vq9FTv68SWkMlkEAQBkiRBra5/l0t6+umncfr0ady+fRurV6/GkCFDcPToUbi6upYbu3DhQsybN6/c8oyMDOTn59d6raIoIisrC5IkNag/k4zpDez/nxwXb6qx/LvbeLWXcd8EoaH20RSxl6aBfTQd7KXpKNvL7OzsKm9LrxBbUFCArVu3Ys2aNTh06BBeeOEFrFixAhEREVX6oXJ2doZcLkdaWprO8rS0NLi7u1e4jru7e6XGW1tbw9vbG97e3ujatSt8fHzwxRdfIDY2ttw2Y2NjERMTo32uUqng6ekJFxeXOpsTKwgCXFxcGtSH0xXAjKgCvPdlLr7aL8eLvezR3FVu6LKqrKH20RSxl6aBfTQd7KXpKNtLpVJZ5W1VOsS+/fbb2LhxIzw9PfH6669jw4YNj/zzfGWVXP4qISEBkZGRADRvLiEhAdHR0RWuExISgoSEBEyePFm7bPfu3QgJCXnsvkRR1JkyUJpCoYBCUf5STzKZrM4+LIIg1On+6ovIUCW2HSlE4rkizF2Xh7UxdhAE451W0FD7aIrYS9PAPpoO9tJ0lO5ldfpZ6RC7cuVKNGvWDC1btsSBAwdw4MCBCsdt3bpVrwJiYmIwcuRIdO7cGUFBQVi2bBlyc3MxevRoAMCIESPQpEkTLFy4EAAwadIk9OrVC0uWLEG/fv2wceNGnDhxAqtWrQIA5Obm4v3338eAAQPQuHFj3L59G3Fxcbhx4wZefvllvWqj2icIAv71qg1emHsXieeKsC2xAINCq/5bGRERETUMlQ6xI0aMqJUjZFFRUcjIyMDs2bORmpqKgIAA7Nq1S3vyVkpKik5KDw0Nxfr16zFz5kzMmDEDPj4+2LZtG9q3bw8AkMvlSE5OxldffYXbt2/DyckJXbp0wcGDB9GuXbsar5+qr7mbHOP7W2Hp1jws3JyLXh0s4GjL37SJiIjo0Sp9ndiGhNeJrXtFxRIGzb+HCzfUiAxRYPEYW0OXpDf20XSwl6aBfTQd7KXpMMh1Yolqk7mZgAUjbCAIwLbEAhw+V2jokoiIiKgeY4ileiOglTle6a2ZDzv7vzm4X8A/EhAREVHFGGKpXnl3sBXcGsmQkiEi+jMV8gsZZImIiKg8hliqV2wsZVg61haWFsDBP4owboWKR2SJiIioHIZYqne6tDbHfybbw0oB/PZnEd5cziBLREREuhhiqV4qCbLWCgFHkovwxqcq5DHIEhER0QMMsVRvdfYxxxfv2MFaKeDo+SKM/SQLufkMskRERMQQS/VcJ29zfPmOHWwsBRy/UIx/fJKFnHzR0GURERGRgTHEUr0X0EoTZG0tBZy8WIx/fKxCzn0GWSIiooaMIZaMgn9Lc6x91w52VgKSLhfj9Y9VyM5jkCUiImqoGGLJaHTwMsdX79rD3krA6SvFGP2xCioGWSIiogaJIZaMSrvmZvhqij0crAWcuVqMUUtVyMplkCUiImpoGGLJ6Pg1exBkbQScvVaMUUuycC+HQZaIiKghYYglo+TraYavp9jD0VbAHylqjFyShbsMskRERA0GQywZrTZNNUHWyVbAub/UGPFRFjKzGWSJiIgaAoZYMmo+Tczw9VR7uNgLOP+3JsjeUTHIEhERmTqGWDJ63h6aIOtqL8OFG2q89lEWbmcxyBIREZkyhlgyCS3dHwRZBxku3dQE2QwGWSIiIpPFEEsmo4W7HOum2sO9kQyXb6nx6odZSLunNnRZREREVAsYYsmkNHeT45up9mjsKMPVVDVe+zALqXcZZImIiEwNQyyZnGaumiDbxEmGa2miJshmMsgSERGZEoZYMkmeLnJ8PdUeTZ1luJ4uYviHWbh5h0GWiIjIVDDEkslq6qw5IuvpIsNfGSJe/TALNxhkiYiITAJDLJk0DydNkG3mIsPft0W8ujgLf2UwyBIRERk7hlgyeY0d5fhmmj283GS4cUdzRPb4hSJDl0VERETVUC9CbFxcHLy8vKBUKhEcHIxjx449dnx8fDzatm0LpVKJDh06YOfOndrXioqK8N5776FDhw6wtraGh4cHRowYgZs3b9b226B6zL2RHN9MdUALdzluZYoYvjgLM9Zm424OryVLRERkjAweYjdt2oSYmBjMmTMHSUlJ8Pf3R3h4ONLT0yscf/jwYQwbNgxjxozBqVOnEBkZicjISJw9exYAkJeXh6SkJMyaNQtJSUnYunUrzp8/jwEDBtTl26J6yNVBhs2x9ojqqQQAfHuoABEz7+K7w/mQJMnA1REREZE+BMnA//cODg5Gly5dsGLFCgCAKIrw9PTEhAkTMH369HLjo6KikJubix07dmiXde3aFQEBAVi5cmWF+zh+/DiCgoJw/fp1NGvW7Ik1qVQq2NvbIysrC3Z2dlV8Z5UniiLS09Ph6uoKmczgv1c0CCcvFmH21zm4eFMzP7ZrW3PMe9UGLdzlVd4m+2g62EvTwD6aDvbSdJTtZXUyl0F/EgoLC3Hy5EmEhYVpl8lkMoSFhSExMbHCdRITE3XGA0B4ePgjxwNAVlYWBEGAg4NDjdRNxi/QxxzfzXbAu4OtoDAHjiQX4YW5d7F8ex4Ki3hUloiIqL4zM+TOb9++DbVaDTc3N53lbm5uSE5OrnCd1NTUCsenpqZWOD4/Px/vvfcehg0b9siEX1BQgIKCAu1zlUoFQPPbgijW/pxJURQhSVKd7IseMpMBYyOUiAg0x7z1eTj0RxGWb8/DjqP5mPuqNYLbmOu1PfbRdLCXpoF9NB3speko28vq9NSgIba2FRUVYciQIZAkCZ9//vkjxy1cuBDz5s0rtzwjIwP5+fm1WSIATQOzsrIgSRL/TGIACgDvDwX2nhWw/EcZrqaJGLkkGxFPiXg7QoSDdeW2wz6aDvbSNLCPpoO9NB1le5mdnV3lbRk0xDo7O0MulyMtLU1neVpaGtzd3Stcx93dvVLjSwLs9evXsXfv3sfOs4iNjUVMTIz2uUqlgqenJ1xcXOpsTqwgCHBxceGH04CGuQH9QkR8/N19bPy1ALtOyZB4QY5pL1lhcKgFBEF47Prso+lgL00D+2g62EvTUbaXSqWyytsyaIi1sLBAYGAgEhISEBkZCUDz5hISEhAdHV3hOiEhIUhISMDkyZO1y3bv3o2QkBDt85IAe/HiRezbtw9OTk6PrUOhUEChUJRbLpPJ6uzDIghCne6PKuZgI8O812wxKFSJWV/n4Pzfavzzq1xsSyzAvFdt4O3x+I8M+2g62EvTwD6aDvbSdJTuZXX6afCfhJiYGKxevRpfffUVzp07h3HjxiE3NxejR48GAIwYMQKxsbHa8ZMmTcKuXbuwZMkSJCcnY+7cuThx4oQ29BYVFeGll17CiRMnsG7dOqjVaqSmpiI1NRWFhYUGeY9kfAJamWPrTAdMe8kKlhbA8QvFGDjvHj7ZlosCnvhFRERkcAafExsVFYWMjAzMnj0bqampCAgIwK5du7Qnb6WkpOik9NDQUKxfvx4zZ87EjBkz4OPjg23btqF9+/YAgBs3bmD79u0AgICAAJ197du3D717966T90XGz9xMwD8irBDRWYF563Jw4PcixO24jx3HCjD3VRt087MwdIlEREQNlsGvE1sf8TqxVJYkSfj5ZCEWbMhFepbmTMoBwQrERlnDyU7TM/bRdLCXpoF9NB3spekwmevEEhkLQRAQ0VmBn+Y74NVnlBAEYPtRzR2/Nv+aD1Hk74JERER1iSGWSA+2VjLMfsUGm2Pt4espR1aehJn/zcEri7Nw8WaxocsjIiJqMBhiiarAv6U5tsx0wPQh1rBSAEmXijHoXyp8vkuGtLu8GDcREVFtY4glqiIzuYDXn7PEzn81Qp8ACxSLwIZDMjwTew/jVqiw/0wh1JxmQEREVCsMfnUCImPn4STH59F22JOUj5U/ZuPMdQEJpwuRcLoQjR1leLmHEi91U8DdUW7oUomIiEwGQyxRDXkmwALtPdTIVjsh/lABth0uwK1MEZ9+n4cV2/PQu6MFonoq0bODOeSyx9/9i4iIiB6PIZaohrVqLMeMKBu8O9gavyQVYOOBfBy/UIy9/yvE3v8Vwr3Rg6Oz3RVozKOzREREVcIQS1RLFOYC+gcr0T9Yicu3irH513x8d7gAqXdFLN+eh7gf8tCrg/mDo7MWMJPz6CwREVFlMcQS1YFWjc0QG2WDmMHW2J1UiE2/5uPo+SLsO6P5cmskw0vdFXi5uxIeTjw6S0RE9CQMsUR1SGEu4IVgBV4IVuBKajE2/1qArYfzkXZXRNwP9/H5jvvo+eDobC8enSUiInokhlgiA2npbobpQ8wQM8gKv5wqxOZf83EkuQj7z2i+XB1keLm7Ai/1UKIJj84SERHpYIglMjALcwEvBCnwQpACV1PViD+Yjy2/5SP9noi4Hffx2Y/30aOdOV7srkRIW3M42PDyzkRERAyxRPVIC3c5pr1sjcmRVth9SjN39khyEX49q/kSBMDPU44QXwuE+Joj0MccVgpOOSAiooaHIZaoHrIwF9AvSIF+QQpcS9Mcnd37v0JcvqXGHylq/JFyH//5+T7M5YB/SzOE+Fqga1tz+Lc0g4UZQy0REZk+hliies7LTY6pL1lj6kvWSLunxtHkIiSe03zdzBRx4mIxTlwsxvLtgKUF0NnHHCG+5gjxtUBbTzlvrEBERCaJIZbIiLg5yDGgqxwDuiohSRL+yhBx+FwRjiQX4khyETKzJRz8owgH/ygCkAd7KwHBbTWhtmtbc7R0l0MQGGqJiMj4McQSGSlBENDMVY5mrnIM7aWEKEq4cEONI8lFSDxXiGMXipGVJ+GXpEL8klQIAHB1kKFrW3OE+mqCLe8YRkRExoohlshEyGQC2nqaoa2nGUY9a4litYSz14o1Uw+Si5B0qQjp90RsP1KA7UcKAADNXWUI8bVAZx8ztG5ihpaN5ZxTS0RERoEhlshEmckFBLQyR0Arc4x7AcgvlJB0WTOX9khyEX6/Wozr6SKup+dj44GSdTRzcFs3kaN1EzPNv03N0NRJBhnn1hIRUT3CEEvUQCgtBIT6WiDU1wIAkJ0n4vgFzVHa368V4+INNbLvS7h0U41LN9XYebxQu66VAvD2MHsYbpvK0drDDM72vGYtEREZBkMsUQNlayXDMwEKPBOgAABIkoTUuyLO/63GxRvFOH9D8++lW2rkFQBnrhbjzNViAAXabTjaCtojtj5NzNCmiRzeTeSwUTLcEhFR7WKIJSIAmhPFGjvK0dhRjt4dLbTLi9USrqerceGGGhf+Ltb8e6MYKRkiMrMlHEnWTE8oramzDK2bmMGniRwt3ORo4iSDh5Mc7o1kMOecWyIiqgEMsUT0WGZyAa0am6FVYzM831mhXX6/QMKlW5ppCOcfhNuLN9RIzxLx920Rf98uxN7/6W5LEDRXSGjiqAm1jR1l2oDr4SSDh5OMR3GJiKhSGGKJqEosFQI6eJmjg5e5zvK7OaIm2N4oxoW/1UjJUONWpho374goLAbS7opIuysi6XJxhdu1txLQ2EmGJk5yeDjKHoRbzeMmTnI42Qm81i0RETHEElHNamQjQ1AbGYLa6IZbUZRwJ1vCzTtq3MwUNf/eEXUeZ+VJD77USP5LXeH2LcwADycZGjvK4eYgg5OdDE62AhxtZXC0lcHJToDTg8dKC4ZdIiJTZfAQGxcXhw8//BCpqanw9/fH8uXLERQU9Mjx8fHxmDVrFq5duwYfHx8sWrQIffv21b6+detWrFy5EidPnkRmZiZOnTqFgICAOngnRPQ4MpkAF3sBLvYy+LeseExOvohbd0TcuCOWCrsibj44kpt+T3M091qaiGtp4hP3aa0Q4Pgg1DrZyeD4IOw6PQi72uBrK0MjG4HzdYmIjIhBQ+ymTZsQExODlStXIjg4GMuWLUN4eDjOnz8PV1fXcuMPHz6MYcOGYeHChXjhhRewfv16REZGIikpCe3btwcA5Obmonv37hgyZAjGjh1b12+JiKrBRimDTxMZfJpU/HpRsYS0e5pge+OOGrezRNzJlnAnW0RmtohM1cPnRcVAboGE3AzN7Xkrw8G6JNgKsDSTwblRDuytZLC1ksHOSoCtpQA7KwF2VjLYWmke21sJsFIIvI4uEVEdEyRJkgy18+DgYHTp0gUrVqwAAIiiCE9PT0yYMAHTp08vNz4qKgq5ubnYsWOHdlnXrl0REBCAlStX6oy9du0aWrRoUaUjsSqVCvb29sjKyoKdnZ3+b0xPoigiPT0drq6ukMl4UouxYh/rD0mSkHNfM30hM1vEnWwRd1QPHqtEZOboPr+bI0Gsxn8JZQJgaylog62dlUwbeG0fPLcr9bqNUoCVUhN+rRUCrJUCLBUCzOQMwjWJn0nTwV6ajrK9rE7mMtiR2MLCQpw8eRKxsbHaZTKZDGFhYUhMTKxwncTERMTExOgsCw8Px7Zt22qzVCIyMoKgCYy2Vpo7kD2JWpSQlfsw1N5WqfF3qgqS3AbZ94Hs+xJUeSKy8ySo7ktQ5UnIztPM4S0qBkQJ2vm8D7ZYpboV5oB1qXBrpRS0z61Knit0l1krHy63UgiwVGhubGFpIUBpIUBpDh4lJiKTZLAQe/v2bajVari5ueksd3NzQ3JycoXrpKamVjg+NTW1WrUUFBSgoODhBdxVKhUAzW8Loli5P0NWhyiKkCSpTvZFtYd9NF4CAAdrwMFahpbuMoiiDBkZIlxcFE886lNQVBJqJWSVCro6/+ZJ2iCsypOQVyAhNx8P/pWgFku2pdleZnbN/oHMwgwPQq0m4CpLHpsL2sCrsIBO8NUuN3+4XGEOKMw1/5qblX4uQGEGmD/410yOenEFCX4mTQd7aTrK9rI6PTX4iV31wcKFCzFv3rxyyzMyMpCfn1/r+xdFEVlZWZAkiX8mMWLso+moSi9t5ICNLQBb/fYlSUCRGsgrAO4XPvzKKxA0jx8szysE7pcsKyw7XtA+zy/ShOHC4ochsrAYKCyWkJUHALU/g0wmSLAw04Rn8wf/6n5JOs/NzQBzueaxmfZfCebyh6/pPC61zEwulVnv4Ri5IOJ+bhaKiiWYm8lQD3I1VRH/+2o6yvYyOzu7ytsyWIh1dnaGXC5HWlqazvK0tDS4u7tXuI67u7te4ysrNjZWZ5qCSqWCp6cnXFxc6mxOrCAIcHFx4YfTiLGPpsMUeqkWJRQUAfmF0oMv4H6hhIIiSRN2H7e8qNTyQgn3H4wrKJIeBGQJhUVAQbFmvcIiTRAvIUoC8os0gbpidZkmXbSPHoZfQRN2zYQHQVjz2EwbkEuWCzA3033dotQyswfbMXuwTbms/HKzB9vSvPZgeenHZoCZrNT4Uo/lcgFmMkBesk0ZtPuoD0e665IpfCZJo2wvlUpllbdlsBBrYWGBwMBAJCQkIDIyEoDmjSUkJCA6OrrCdUJCQpCQkIDJkydrl+3evRshISHVqkWhUEChUJRbLpPJ6uzDIghCne6Pagf7aDqMvZcymSaQ2VjWzf5EUUJh8cOgW1AkobD4Qegt0oTdguKSx7qvFxRp5hYXFj/mX7Vm3cJizVUqdP5Va4J0oVpCUcm/FdxLo6gYD5aXHI022HnN1SYTHoTbB4G45LG8VNiVlwrQOoFYpgnc8gfP5aWfyx5uSyZ7MFZe6rVHrqepQyYD5IJmf3LZgzpLbbfsc7mg2Y9cJjzYX8XPBUi4d1dAsZkEc7kE2YN9C8LD/ZcsK9kH54LXX6X/+1qd/8YadDpBTEwMRo4cic6dOyMoKAjLli1Dbm4uRo8eDQAYMWIEmjRpgoULFwIAJk2ahF69emHJkiXo168fNm7ciBMnTmDVqlXabWZmZiIlJQU3b94EAJw/fx6A5ihudY/YEhFRxWSyh3Nu6wNJklBQKOJmagYcHJ2hFmUofhBuix78W6zWPC5Wa4JysVoTjEuWa8ZCu57O+mpNIFaLknaMWv1wfLEaUIsPt1esllAs4uFjdQWPxYdji9SAKEI7X7osUQLEYkBzsLt0GDfeYP5kZgCy9FqjJNTKSgfdMs8fht6SsYLOeiXLyo6TywRtiBZKhfOSx9r9CgKEUuFaEACZIJR6XGr5g/3IdPb/iLEly0vGCg/CYan1H64jPNi+7nKZAAgl+9Q+1/xyoTAXENDK/MnfZAMyaIiNiopCRkYGZs+ejdTUVAQEBGDXrl3ak7dSUlJ0EnpoaCjWr1+PmTNnYsaMGfDx8cG2bdu014gFgO3bt2tDMAAMHToUADBnzhzMnTu3bt4YEREZlCAIsDAXYKXQnLBnrEfUJelhIC4WNUFZ/SAMq8VSr6l1H6tF3celxxerAbHUdtUioH4QsjXBWfOaKALFD55rxmhq0C5X676mlh7WJ0oPXiv7XHy4T/HBc1G7rNRzSfN6sbr06yJESdA+r8xl8dTig2uFaKe7lF3JlEN/9bg3kuHXDx0NXcZjGfQ6sfUVrxNLVcE+mg720jSwj6ajol5KkgRJKh2SHwbjkjAsPgjDagmlArOkE4S1y6Ty60gPArVaBKQHy8RS64mSVGZfmmUPg7juMlGC7n5KLy+1b7Hcfh61Dc0ySXq4XCq9jVLrl10ulXpdKtl+qfHOdjL8d4p9rffSKK8TS0RERFRVgvDwT+SllhqqHDIA/mpKREREREaHIZaIiIiIjA5DLBEREREZHYZYIiIiIjI6DLFEREREZHQYYomIiIjI6DDEEhEREZHRYYglIiIiIqPDEEtERERERochloiIiIiMDm87WwFJkgAAKpWqTvYniiKys7OhVCp5f28jxj6aDvbSNLCPpoO9NB1le1mStUqylz4YYiuQnZ0NAPD09DRwJURERESmLzs7G/b29nqtI0hVib4mThRF3Lx5E7a2thAEodb3p1Kp4Onpib/++gt2dna1vj+qHeyj6WAvTQP7aDrYS9NRtpeSJCE7OxseHh56H2XnkdgKyGQyNG3atM73a2dnxw+nCWAfTQd7aRrYR9PBXpqO0r3U9whsCU4sISIiIiKjwxBLREREREaHIbYeUCgUmDNnDhQKhaFLoWpgH00He2ka2EfTwV6ajprsJU/sIiIiIiKjwyOxRERERGR0GGKJiIiIyOgwxBIRERGR0WGINbC4uDh4eXlBqVQiODgYx44dM3RJpKe5c+dCEASdr7Zt2xq6LKqEX3/9Ff3794eHhwcEQcC2bdt0XpckCbNnz0bjxo1haWmJsLAwXLx40TDF0iM9qY+jRo0q9xmNiIgwTLH0SAsXLkSXLl1ga2sLV1dXREZG4vz58zpj8vPzMX78eDg5OcHGxgYvvvgi0tLSDFQxPUpletm7d+9yn8u33npLr/0wxBrQpk2bEBMTgzlz5iApKQn+/v4IDw9Henq6oUsjPbVr1w63bt3Sfh06dMjQJVEl5Obmwt/fH3FxcRW+vnjxYnz66adYuXIljh49Cmtra4SHhyM/P7+OK6XHeVIfASAiIkLnM7phw4Y6rJAq48CBAxg/fjyOHDmC3bt3o6ioCM899xxyc3O1Y9555x388MMPiI+Px4EDB3Dz5k0MHjzYgFVTRSrTSwAYO3aszudy8eLF+u1IIoMJCgqSxo8fr32uVqslDw8PaeHChQasivQ1Z84cyd/f39BlUDUBkL777jvtc1EUJXd3d+nDDz/ULrt3756kUCikDRs2GKBCqoyyfZQkSRo5cqQ0cOBAg9RDVZeeni4BkA4cOCBJkubzZ25uLsXHx2vHnDt3TgIgJSYmGqpMqoSyvZQkSerVq5c0adKkam2XR2INpLCwECdPnkRYWJh2mUwmQ1hYGBITEw1YGVXFxYsX4eHhgZYtW2L48OFISUkxdElUTVevXkVqaqrOZ9Te3h7BwcH8jBqh/fv3w9XVFW3atMG4ceNw584dQ5dET5CVlQUAcHR0BACcPHkSRUVFOp/Jtm3bolmzZvxM1nNle1li3bp1cHZ2Rvv27REbG4u8vDy9tmtWYxWSXm7fvg21Wg03Nzed5W5ubkhOTjZQVVQVwcHBWLt2Ldq0aYNbt25h3rx56NGjB86ePQtbW1tDl0dVlJqaCgAVfkZLXiPjEBERgcGDB6NFixa4fPkyZsyYgeeffx6JiYmQy+WGLo8qIIoiJk+ejG7duqF9+/YANJ9JCwsLODg46IzlZ7J+q6iXAPDKK6+gefPm8PDwwJkzZ/Dee+/h/Pnz2Lp1a6W3zRBLVE3PP/+89nHHjh0RHByM5s2bY/PmzRgzZowBKyMiABg6dKj2cYcOHdCxY0e0atUK+/fvR58+fQxYGT3K+PHjcfbsWZ5fYAIe1cs33nhD+7hDhw5o3Lgx+vTpg8uXL6NVq1aV2janExiIs7Mz5HJ5ubMq09LS4O7ubqCqqCY4ODigdevWuHTpkqFLoWoo+RzyM2p6WrZsCWdnZ35G66no6Gjs2LED+/btQ9OmTbXL3d3dUVhYiHv37umM52ey/npULysSHBwMAHp9LhliDcTCwgKBgYFISEjQLhNFEQkJCQgJCTFgZVRdOTk5uHz5Mho3bmzoUqgaWrRoAXd3d53PqEqlwtGjR/kZNXJ///037ty5w89oPSNJEqKjo/Hdd99h7969aNGihc7rgYGBMDc31/lMnj9/HikpKfxM1jNP6mVFTp8+DQB6fS45ncCAYmJiMHLkSHTu3BlBQUFYtmwZcnNzMXr0aEOXRnqYMmUK+vfvj+bNm+PmzZuYM2cO5HI5hg0bZujS6AlycnJ0fuu/evUqTp8+DUdHRzRr1gyTJ0/GggUL4OPjgxYtWmDWrFnw8PBAZGSk4Yqmch7XR0dHR8ybNw8vvvgi3N3dcfnyZUybNg3e3t4IDw83YNVU1vjx47F+/Xp8//33sLW11c5ztbe3h6WlJezt7TFmzBjExMTA0dERdnZ2mDBhAkJCQtC1a1cDV0+lPamXly9fxvr169G3b184OTnhzJkzeOedd9CzZ0907Nix8juq1rUNqNqWL18uNWvWTLKwsJCCgoKkI0eOGLok0lNUVJTUuHFjycLCQmrSpIkUFRUlXbp0ydBlUSXs27dPAlDua+TIkZIkaS6zNWvWLMnNzU1SKBRSnz59pPPnzxu2aCrncX3My8uTnnvuOcnFxUUyNzeXmjdvLo0dO1ZKTU01dNlURkU9BCB9+eWX2jH379+X3n77balRo0aSlZWVNGjQIOnWrVuGK5oq9KRepqSkSD179pQcHR0lhUIheXt7S1OnTpWysrL02o/wYGdEREREREaDc2KJiIiIyOgwxBIRERGR0WGIJSIiIiKjwxBLREREREaHIZaIiIiIjA5DLBEREREZHYZYIiIiIjI6DLFEREREZHQYYomIaomXlxeWLVtW6fH79++HIAi4d+9erdVUn+j7/SEiKo0hlogaPEEQHvs1d+7cKm33+PHjeOONNyo9PjQ0FLdu3YK9vX2V9kdE1JCYGboAIiJDu3Xrlvbxpk2bMHv2bJw/f167zMbGRvtYkiSo1WqYmT35P58uLi561WFhYQF3d3e91iEiaqh4JJaIGjx3d3ftl729PQRB0D5PTk6Gra0tfvrpJwQGBkKhUODQoUO4fPkyBg4cCDc3N9jY2KBLly7Ys2ePznbL/rlcEAT85z//waBBg2BlZQUfHx9s375d+3rZ6QRr166Fg4MDfv75Z/j6+sLGxgYRERE6obu4uBgTJ06Eg4MDnJyc8N5772HkyJGIjIx87Hs+dOgQevToAUtLS3h6emLixInIzc3VqX3+/PkYNmwYrK2t0aRJE8TFxelsIyUlBQMHDoSNjQ3s7OwwZMgQpKWl6Yz54Ycf0KVLFyiVSjg7O2PQoEE6r+fl5eH111+Hra0tmjVrhlWrVj22biKiEgyxRESVMH36dHzwwQc4d+4cOnbsiJycHPTt2xcJCQk4deoUIiIi0L9/f6SkpDx2O/PmzcOQIUNw5swZ9O3bF8OHD0dmZuYjx+fl5eGjjz7C119/jV9//RUpKSmYMmWK9vVFixZh3bp1+PLLL/Hbb79BpVJh27Ztj63h8uXLiIiIwIsvvogzZ85g06ZNOHToEKKjo3XGffjhh/D398epU6cwffp0TJo0Cbt37wYAiKKIgQMHIjMzEwcOHMDu3btx5coVREVFadf/8ccfMWjQIPTt2xenTp1CQkICgoKCdPaxZMkSdO7cGadOncLbb7+NcePG6RwFJyJ6JImIiLS+/PJLyd7eXvt83759EgBp27ZtT1y3Xbt20vLly7XPmzdvLn388cfa5wCkmTNnap/n5ORIAKSffvpJZ193797V1gJAunTpknaduLg4yc3NTfvczc1N+vDDD7XPi4uLpWbNmkkDBw58ZJ1jxoyR3njjDZ1lBw8elGQymXT//n1t7RERETpjoqKipOeff16SJEn65ZdfJLlcLqWkpGhf/+OPPyQA0rFjxyRJkqSQkBBp+PDhj6yjefPm0quvvqp9Loqi5OrqKn3++eePXIeIqASPxBIRVULnzp11nufk5GDKlCnw9fWFg4MDbGxscO7cuSceie3YsaP2sbW1Nezs7JCenv7I8VZWVmjVqpX2eePGjbXjs7KykJaWpnN0Uy6XIzAw8LE1/O9//8PatWthY2Oj/QoPD4coirh69ap2XEhIiM56ISEhOHfuHADg3Llz8PT0hKenp/Z1Pz8/ODg4aMecPn0affr0eWwtpb8fJdM4Hvf9ICIqwRO7iIgqwdraWuf5lClTsHv3bnz00Ufw9vaGpaUlXnrpJRQWFj52O+bm5jrPBUGAKIp6jZckSc/qdeXk5ODNN9/ExIkTy73WrFmzam27NEtLyyeO0ff7QURUgkdiiYiq4LfffsOoUaMwaNAgdOjQAe7u7rh27Vqd1mBvbw83NzccP35cu0ytViMpKemx63Xq1Al//vknvL29y31ZWFhoxx05ckRnvSNHjsDX1xcA4Ovri7/++gt//fWX9vU///wT9+7dg5+fHwDNUdaEhIRqv08ioorwSCwRURX4+Phg69at6N+/PwRBwKxZswxyBHHChAlYuHAhvL290bZtWyxfvhx3796FIAiPXOe9995D165dER0djX/84x+wtrbGn3/+id27d2PFihXacb/99hsWL16MyMhI7N69G/Hx8fjxxx8BAGFhYejQoQOGDx+OZcuWobi4GG+//TZ69eqlnXoxZ84c9OnTB61atcLQoUNRXFyMnTt34r333qvdbwoRNQg8EktEVAVLly5Fo0aNEBoaiv79+yM8PBydOnWq8zree+89DBs2DCNGjEBISIh2fqtSqXzkOh07dsSBAwdw4cIF9OjRA0899RRmz54NDw8PnXHvvvsuTpw4gaeeegoLFizA0qVLER4eDkDzZ//vv/8ejRo1Qs+ePREWFoaWLVti06ZN2vV79+6N+Ph4bN++HQEBAXjmmWdw7Nix2vlGEFGDI0jVnVxFRET1hiiK8PX1xZAhQzB//vwqb8fLywuTJ0/G5MmTa644IqIaxOkERERG7Pr16/jll1/Qq1cvFBQUYMWKFbh69SpeeeUVQ5dGRFSrOJ2AiMiIyWQyrF27Fl26dEG3bt3w+++/Y8+ePdoTsIiITBWnExARERGR0eGRWCIiIiIyOgyxRERERGR0GGKJiIiIyOgwxBIRERGR0WGIJSIiIiKjwxBLREREREaHIZaIiIiIjA5DLBEREREZHYZYIiIiIjI6/w//BUqszq76PgAAAABJRU5ErkJggg==", "text/plain": [ "
" ] @@ -174,7 +173,7 @@ "\n", "def evaluate():\n", " reset_sequence()\n", - " predictions = brainstate.transform.for_loop(learner, inputs)\n", + " predictions = learner.etrace_evolve(inputs, return_outputs=True)\n", " return jnp.mean((predictions - targets) ** 2)\n", "\n", "\n", @@ -185,24 +184,13 @@ "\n", "def train_epoch(_):\n", " reset_sequence()\n", - "\n", - " def scan_step(accumulated_grads, sample):\n", - " x, target = sample\n", - " step_grads, step_loss = brainstate.transform.grad(\n", - " local_loss, weights, return_value=True\n", - " )(x, target)\n", - " accumulated_grads = jax.tree.map(\n", - " lambda total, current: total + current,\n", - " accumulated_grads,\n", - " step_grads,\n", - " )\n", - " return accumulated_grads, step_loss\n", - "\n", - " zero_grads = jax.tree.map(jnp.zeros_like, weights.to_dict_values())\n", - " grads, step_losses = brainstate.transform.scan(\n", - " scan_step, zero_grads, (inputs, targets)\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", - " grads = jax.tree.map(lambda grad: grad / inputs.shape[0], grads)\n", " optimizer.update(grads)\n", " return step_losses.mean()\n", "\n", @@ -285,7 +273,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.11.8" + "version": "3.13.11" } }, "nbformat": 4, diff --git a/docs/tutorials/neural_network_layers.ipynb b/docs/tutorials/neural_network_layers.ipynb index 665ed88..cbfbb00 100644 --- a/docs/tutorials/neural_network_layers.ipynb +++ b/docs/tutorials/neural_network_layers.ipynb @@ -125,7 +125,7 @@ "sequence = jnp.linspace(-1.0, 1.0, 6).reshape(6, 1)\n", "brainstate.nn.reset_all_states(model)\n", "learner.reset_state()\n", - "outputs = brainstate.transform.for_loop(learner, sequence)\n", + "outputs = learner.etrace_evolve(sequence, return_outputs=True)\n", "print(\"Sequence output shape:\", outputs.shape)\n" ] }, diff --git a/docs/tutorials/pp_prop.ipynb b/docs/tutorials/pp_prop.ipynb index 3925962..35b7f07 100644 --- a/docs/tutorials/pp_prop.ipynb +++ b/docs/tutorials/pp_prop.ipynb @@ -46,10 +46,10 @@ "id": "pp-imports", "metadata": { "execution": { - "iopub.execute_input": "2026-07-27T05:26:34.824006Z", - "iopub.status.busy": "2026-07-27T05:26:34.824006Z", - "iopub.status.idle": "2026-07-27T05:26:37.048605Z", - "shell.execute_reply": "2026-07-27T05:26:37.048605Z" + "iopub.execute_input": "2026-07-28T15:24:28.680802Z", + "iopub.status.busy": "2026-07-28T15:24:28.680629Z", + "iopub.status.idle": "2026-07-28T15:24:31.478191Z", + "shell.execute_reply": "2026-07-28T15:24:31.477258Z" } }, "outputs": [], @@ -57,7 +57,6 @@ "import brainstate\n", "import braintools\n", "import braintrace\n", - "import jax\n", "import jax.numpy as jnp\n", "import matplotlib.pyplot as plt\n", "import warnings\n", @@ -81,10 +80,10 @@ "id": "pp-model", "metadata": { "execution": { - "iopub.execute_input": "2026-07-27T05:26:37.051284Z", - "iopub.status.busy": "2026-07-27T05:26:37.050731Z", - "iopub.status.idle": "2026-07-27T05:26:38.557587Z", - "shell.execute_reply": "2026-07-27T05:26:38.557587Z" + "iopub.execute_input": "2026-07-28T15:24:31.480929Z", + "iopub.status.busy": "2026-07-28T15:24:31.480472Z", + "iopub.status.idle": "2026-07-28T15:24:35.014892Z", + "shell.execute_reply": "2026-07-28T15:24:35.013964Z" } }, "outputs": [], @@ -126,7 +125,7 @@ "id": "pp-training-heading", "metadata": {}, "source": [ - "## 4. Scan factorized traces over the sequence\n", + "## 4. Drive the factorized traces over the sequence\n", "\n", "The training structure is intentionally identical to the D-RTRL notebook. Only the compiler algorithm and its decay are different.\n" ] @@ -137,10 +136,10 @@ "id": "pp-training", "metadata": { "execution": { - "iopub.execute_input": "2026-07-27T05:26:38.559593Z", - "iopub.status.busy": "2026-07-27T05:26:38.559593Z", - "iopub.status.idle": "2026-07-27T05:26:39.215072Z", - "shell.execute_reply": "2026-07-27T05:26:39.215072Z" + "iopub.execute_input": "2026-07-28T15:24:35.017647Z", + "iopub.status.busy": "2026-07-28T15:24:35.017193Z", + "iopub.status.idle": "2026-07-28T15:24:35.731428Z", + "shell.execute_reply": "2026-07-28T15:24:35.730398Z" } }, "outputs": [ @@ -158,7 +157,7 @@ }, { "data": { - "image/png": "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rwf2oYcewksvvYTHH388088kh9mVciBVXmS8j2x/7NixHB+fQawPkzIT0nuXkTyWBGm5LU3aJLcus7Yraf91KSpWrOilqyJPSR40X5e+4/Lly2pwkJRcksGwZrM5/WeuEkzZvQ75GvQdkusqH0KGDBmCd95551+3d41FyM3rkEGsD5NcrVWrVmX6tCkv5nbt2mV6QZNvj7TNOvpdUgvq1avntWsiz1+XcttZcmAzvi6ltyjr7U3SxutSBg3JGy5fl75BxnxIAFumTBn88MMPCAwMzPRzuZslgzDlZxmDXhk4JK9P8j6p8CJtIb2t77333r++BsXKlStVJ13t2rVzfB5OduDDJAfos88+U6VF5HbXH3/8geXLl2Pt2rXevjTKoTZt2qgcn4YNG6p/su+++67qKZBPpuSbpMyLkCBVbmfK46CgoPRBJP3798eHH36I7t27qxznHTt2YN68efjpp5+8fOUk4uLiVNUB4XQ6VaktaUO5A1KjRg21/u6771aLtKkEsPImGx4ejmeffZZPopdJGa277rpLfX3llVdUMORSp04dFCtWTH0/YcIE9OjRQ92VlA8fEydORN26ddOrhpD3SMUPVxqIxC+u/6muygWSDiLrpM369OmjJkLYuHGjeiz5z7eqDpOVTorF5tPvQXlAeu6kG15672TGrmeeeQYtW7bkc6sRV69exUcffaTyfKTMSIsWLdQHkqw9C+QbpOxS+/btb1gvPT8LFizIVBZGPpDIAD3pfZUPnHfccUcBXy3drI6vvMaykqDVNbBEPqB88skn6o1TPqDIqHb538oZn3xjINdjjz2W7c8kcG3btm36Y7lT+eWXX6rBQdKGEvS6Sm6R90hn283q2UvvueuDiFTukaogMqhL0kbkA4h8gMkNBrFEREREpDnMiSUiIiIizWEQS0RERESawyCWiIiIiDSHQSwRERERaQ6DWCIiIiLSHAaxRERERKQ5DGKJiIiISHMYxBIRFZCff/4ZR44cyfd9tE4Kop84ccLbl0FEPo6THRAR/S0+Ph7Lli275fPRoEEDNf2lO2S+d5kZSpb83EfrZIa0t956CwMGDPD2pRCRDzN6+wKIiHwpiP3f//6X/nj37t04c+YM7r333vR1ZrPZ7SBWjlOjRo1834eIqDBgEEtE9LeyZctiwYIF6c/Hq6++isWLF2da57rVHRAQgG3b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", + "image/png": "iVBORw0KGgoAAAANSUhEUgAAArEAAAFyCAYAAADiToKqAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjEwLjgsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvwVt1zgAAAAlwSFlzAAAPYQAAD2EBqD+naQAAcWpJREFUeJzt3XlYVGX7B/DvmZ0dFwRRBMUNFEVREdwySXDH5Rea5ZJpiztlqZV70VtZvqlF9qaWaZotWm6luKWi5p4bihumsqixw8DMOb8/JidHUBkEhwPfz3XNdTnPPOece+bm4M0zz3mOIEmSBCIiIiIiGVHYOgAiIiIiImuxiCUiIiIi2WERS0RERESywyKWiIiIiGSHRSwRERERyQ6LWCIiIiKSHRaxRERERCQ7LGKJiIiISHZYxBIRERGR7LCIJSIqpeXLl0MQBFy+fNnqbXfu3AlBELBz584yj6uyGjFiBHx8fEq17axZsyAIQtkGVEKPEjcR3R+LWCIimcjMzMQ777yDNm3awMXFBVqtFt7e3oiKisLGjRst+t4pku88lEolatWqhUGDBuHMmTNF9v3EE0+gefPmxR735s2bEAQBs2bNemB8169fx6xZs3Ds2LHSvkUiohJT2ToAIiK5eu655zB48GBotVqrt+3cuTPy8vKg0WhK1D8xMRHh4eG4cuUK+vfvj2HDhsHR0RFXr17Fpk2b0Lt3b3z99dd47rnnLLabMGEC2rZti8LCQpw4cQKxsbHYuXMnTp48CQ8PD6vjfpDr169j9uzZ8PHxQWBgYJnuGwC++OILiKJYqm3feustTJ06tYwjIiJbYhFLRBWGwWCAKIolLuxsTalUQqlUlmpbhUIBnU5Xor4GgwH9+/dHSkoKdu3ahQ4dOli8PnPmTPz2228wGo1Ftu3UqRMGDRpkft6kSRO8/PLL+Prrr/H666+XKvaykpubC3t7+xL3V6vVpT6WSqWCSsX/8ogqE04nIKoC7swHPHv2LJ5++mk4OzujRo0amDhxIvLz8y36CoKAcePGYeXKlWjSpAl0Oh2CgoKwe/fuEh1rxIgRcHR0xMWLFxEeHg4HBwd4enpizpw5kCTJ3O/y5csQBAEffvghFixYAF9fX2i1Wpw+fRoAsH37dnTq1AkODg5wdXVFv379inwNbs37Ks6dr9BPnDiBLl26wN7eHg0bNsT3338PANi1axeCg4NhZ2eHJk2aYNu2bRbbFzcn1sfHB71798aePXvQrl076HQ6NGjQAF9//bXFttbMiV27di1OnjyJt99+u0gBe0f37t3Ro0ePh+6rU6dOAIALFy48tK81du7cibZt2wIARo4caZ7GsHz5cgD/ftaHDx9G586dYW9vj+nTpwMA1q9fj169esHT0xNarRa+vr6YO3dukaL83rmld/8MLVmyxPwz1LZtW/zxxx8W2xY3J/bOz/q6devQvHlzaLVaNGvWDFu2bCn2/bVp0wY6nQ6+vr74/PPPH2mebU5ODl599VV4eXlBq9WiSZMm+PDDDy3OEQDYunUrOnbsCFdXVzg6OqJJkybmz+2OhQsXolmzZrC3t0e1atXQpk0brFq1qlRxEckJ/ywlqkKefvpp+Pj4ICYmBvv378cnn3yCv//+u0iBtWvXLqxZswYTJkyAVqvFp59+ioiICBw8ePC+8ybvZjQaERERgfbt2+P999/Hli1bMHPmTBgMBsyZM8ei77Jly5Cfn48xY8ZAq9WievXq2LZtG3r06IEGDRpg1qxZyMvLw8KFC9GhQwccOXKkyEUyJX1fxfn777/Ru3dvDB48GP/3f/+Hzz77DIMHD8bKlSsxadIkvPTSS3jmmWfwwQcfYNCgQbh69SqcnJweuM/ExEQMGjQIo0aNwvDhw7F06VKMGDECQUFBaNas2UNjutcvv/wCAHj22Wet3vZedwruatWqPfK+7ubn54c5c+ZgxowZGDNmjLlYDg0NNfe5desWevTogcGDB+PZZ5+Fu7s7ANMfA46OjoiOjoajoyO2b9+OGTNmIDMzEx988MFDj71q1SpkZWXhxRdfhCAIeP/99zFgwABcvHjxoaO3e/bswY8//ohXXnkFTk5O+OSTTzBw4EAkJSWhRo0aAICjR48iIiICtWvXxuzZs2E0GjFnzhy4ubmV6rOSJAl9+/bFjh07MGrUKAQGBuLXX3/FlClTcO3aNXz88ccAgFOnTqF3795o0aIF5syZA61Wi8TEROzdu9e8ry+++AITJkzAoEGDzH+8nThxAgcOHMAzzzxTqviIZEMiokpv5syZEgCpb9++Fu2vvPKKBEA6fvy4uQ2ABEA6dOiQue3KlSuSTqeT+vfv/9BjDR8+XAIgjR8/3twmiqLUq1cvSaPRSGlpaZIkSdKlS5ckAJKzs7OUmppqsY/AwECpVq1a0q1bt8xtx48flxQKhTRs2LBSva/idOnSRQIgrVq1ytx29uxZCYCkUCik/fv3m9t//fVXCYC0bNkyc9uyZcskANKlS5fMbd7e3hIAaffu3ea21NRUSavVSq+++qq5bceOHRIAaceOHQ+MUZIkqVWrVpKrq2uR9uzsbCktLc38yMjIKLL/pUuXSmlpadL169elLVu2SA0bNpQEQZAOHjxY5LNo1qxZscdPS0uTAEgzZ858YJx//PFHkc/o7v0DkGJjY4u8lpubW6TtxRdflOzt7aX8/Hxz2/DhwyVvb2/z8zs/QzVq1JBu375tbl+/fr0EQPrll1/MbXd+Vu4GQNJoNFJiYqK57fjx4xIAaeHChea2Pn36SPb29tK1a9fMbefPn5dUKlWRfRbn3rjXrVsnAZDmzZtn0W/QoEGSIAjmeD7++GMJgPmcKU6/fv3umzeiyo7TCYiqkLFjx1o8Hz9+PABg06ZNFu0hISEICgoyP69Xrx769euHX3/9tdh5l8UZN26c+d93vrYtKCgo8pX8wIEDLUa0bty4gWPHjmHEiBGoXr26ub1FixZ46qmnisRqzfsqjqOjIwYPHmx+3qRJE7i6usLPzw/BwcHm9jv/vnjx4kP36e/vbx6JBAA3Nzc0adKkRNsWJzMzE46OjkXa33zzTbi5uZkfxY28Pf/883Bzc4OnpyciIiKQkZGBFStWmL/6f5y0Wi1GjhxZpN3Ozs7876ysLNy8eROdOnVCbm4uzp49+9D9RkVFWYws3/nsS/J5h4WFwdfX1/y8RYsWcHZ2Nm9rNBqxbds2REZGwtPT09yvYcOGJZq+UZxNmzZBqVRiwoQJFu2vvvoqJEnC5s2bAQCurq4ATNMt7ndBm6urK/76668i0yeIqgIWsURVSKNGjSye+/r6QqFQFFnn9N5+ANC4cWPk5uYiLS0NBQUFSE5OtnjcXdwqFAo0aNCgyPYAihyrfv36Fs+vXLkCwFRM3svPzw83b95ETk5Oqd5XcerWrVtkXqOLiwu8vLyKtAGm6QcPU69evSJt1apVe+C22dnZFp9nWlqa+TUnJydkZ2cX2eaVV17B1q1bsXXrVvNX8/eaMWMGtm7dip9++gnDhg1DRkYGFIrS/ep/1HVW69SpU+xFe6dOnUL//v3h4uICZ2dnuLm5madOZGRkPHS/937edwrasshVamoq8vLy0LBhwyL9imsriStXrsDT07PItBQ/Pz/z64CpOO/QoQNeeOEFuLu7Y/Dgwfjuu+8sCto33ngDjo6OaNeuHRo1aoSxY8daTDcgqsxYxBJVYaUtSvbt24fatWtbPK5evVqqfd09CldWrHlf91td4H7t0j0X3pTVth9++KHF53n3SGnTpk2Rnp6Oa9euWWzTuHFjhIWFISws7L4rHQQEBCAsLAyRkZH46quv0LdvX4wePbpIvnQ6HfLy8ordR25urrnPoygu1+np6ejSpQuOHz+OOXPm4JdffsHWrVvxn//8BwBKtKTW487V42JnZ4fdu3dj27ZteO6553DixAlERUXhqaeeMv/R6Ofnh4SEBKxevRodO3bEDz/8gI4dO2LmzJk2jp6o/LGIJapCzp8/b/E8MTERoigWuVDq3n4AcO7cOdjb28PNzQ0tW7Y0jwDeedy95qgoikW+yj137hwAPPTORd7e3gCAhISEIq+dPXsWNWvWhIODQ6neV0U2bNgwi89z5cqV5td69+4NABZtpfXee+8hPz8f77zzjkW7t7c3rl69WmwheycXd3JzP6X5o2jnzp24desWli9fjokTJ6J3794ICwsr8wvPSqtWrVrQ6XRITEws8lpxbSXh7e2N69evIysry6L9ztSJuz9nhUKBbt264aOPPsLp06fxzjvvYPv27dixY4e5j4ODA6KiorBs2TIkJSWhV69eeOedd0q0QgeRnLGIJapCFi9ebPF84cKFAFBkbl98fDyOHDlifn716lWsX78e3bt3h1KpRLVq1cwjgPcbCVy0aJH535IkYdGiRVCr1ejWrdsDY6xduzYCAwPx1VdfIT093dx+8uRJ/Pbbb+jZs2ep31dF1qBBA4vP8+6ltJ5++mn4+/tj7ty52L9/f7Hbl3Tk0NfXFwMHDsTy5cuRnJxsbu/ZsycKCwvx+eefW/QXRRGfffYZNBrNQ3N354+Lu/P2MHdGQu+Ov6CgAJ9++mmJ91GelEolwsLCsG7dOly/ft3cnpiYaJ67aq2ePXvCaDRanCMA8PHHH0MQBPPP7e3bt4tse+cmEnq9HoBpxYe7aTQa+Pv7Q5IkFBYWlio+IrngEltEVcilS5fQt29fREREID4+Ht988w2eeeYZtGzZ0qJf8+bNER4ebrHEFgDMnj27RMfR6XTYsmULhg8fjuDgYGzevBkbN27E9OnTS7Qs0QcffIAePXogJCQEo0aNMi+x5eLiUuytT0v6vuRKrVbjp59+Qnh4ODp27IgBAwaY19C9du0afv75Z/MIXElMmTIF3333HRYsWID33nsPANCnTx90794dkydPxsGDBxEaGorc3Fz8/PPP2Lt3L+bNm/fQ3Pn6+sLV1RWxsbFwcnKCg4MDgoODi8x7vltoaCiqVauG4cOHY8KECRAEAStWrKgQX+ffMWvWLPz222/o0KEDXn75ZXMB2rx581LdYrdPnz7o2rUr3nzzTVy+fBktW7bEb7/9hvXr12PSpEnmC83mzJmD3bt3o1evXvD29kZqaio+/fRT1K1bFx07dgRgWh/Yw8MDHTp0gLu7O86cOYNFixahV69eD10Kjkj2bLUsAhE9PneWFzp9+rQ0aNAgycnJSapWrZo0btw4KS8vz6IvAGns2LHSN998IzVq1EjSarVSq1atSrQUlCSZlhNycHCQLly4IHXv3l2yt7eX3N3dpZkzZ0pGo9Hc787ySB988EGx+9m2bZvUoUMHyc7OTnJ2dpb69OkjnT59utTvqzj3W1bK29tb6tWrV5H2O5/NHfdbYqu4bbt06SJ16dLF/NyaJbbuSE9Pl+bMmSO1atVKcnR0lDQajeTl5SUNGjTIYjmpu/e/du3aYvf1xBNPSM7OzlJ6erq5LT8/X5o1a5bUtGlTSavVSg4ODlL79u2lb775psQxrl+/XvL39zcvP3Vnua0HLeG1d+9eqX379pKdnZ3k6ekpvf766+Ylze7+fO63xFZxP0O4Z0mw+y2xdXc+7/D29paGDx9u0RYXFye1atVK0mg0kq+vr/S///1PevXVVyWdTvfgD6SYuCVJkrKysqTJkydLnp6eklqtlho1aiR98MEHkiiKFsfs16+f5OnpKWk0GsnT01MaMmSIdO7cOXOfzz//XOrcubNUo0YNSavVSr6+vtKUKVMsllsjqqwESapAf+4SUbmYNWsWZs+ejbS0NNSsWfOBfQVBwNixY4t81VlSI0aMwPfff1/s1fRlzZr3RVTWIiMjcerUqWLnkBNR+eOcWCIiooe494K38+fPY9OmTXjiiSdsExARcU4sERHRwzRo0AAjRoxAgwYNcOXKFfPFbq+//rqtQyOqsljEEhERPURERAS+/fZbJCcnQ6vVIiQkBO+++26xNwYhoseDc2KJiIiISHY4J5aIiIiIZIdFLBERERHJDufElpIoirh+/TqcnJxKff95IiIioqpMkiRkZWXB09MTCoV1Y6ssYkvp+vXr8PLysnUYRERERLJ39epV1K1b16ptWMSW0p3b+V29ehXOzs7leixRFJGWlgY3Nzer/0qhioE5lD/mUP6YQ/ljDuXv3hxmZmbCy8urVLdJZhFbSnemEDg7Oz+WIjY/Px/Ozs48aWWKOZQ/5lD+mEP5Yw7l7345LM3UTP4EEBEREZHssIglIiIiItlhEUtEREREssMiloiIiIhkh0UsEREREckOi1giIiIikh0WsUREREQkOzYvYhcvXgwfHx/odDoEBwfj4MGDD+y/du1aNG3aFDqdDgEBAdi0aZPF69nZ2Rg3bhzq1q0LOzs7+Pv7IzY21qJPfn4+xo4dixo1asDR0REDBw5ESkpKmb83IiIiIiofNi1i16xZg+joaMycORNHjhxBy5YtER4ejtTU1GL779u3D0OGDMGoUaNw9OhRREZGIjIyEidPnjT3iY6OxpYtW/DNN9/gzJkzmDRpEsaNG4eff/7Z3Gfy5Mn45ZdfsHbtWuzatQvXr1/HgAEDyv39lpahQIKx0NZREBEREVUcgiRJkq0OHhwcjLZt22LRokUATHdx8PLywvjx4zF16tQi/aOiopCTk4MNGzaY29q3b4/AwEDzaGvz5s0RFRWFt99+29wnKCgIPXr0wLx585CRkQE3NzesWrUKgwYNAgCcPXsWfn5+iI+PR/v27UsUe2ZmJlxcXJCRkVGud+zKzRSxamoW7GsUIGpWdSiVynI7FpUfURSRmpqKWrVq8S4zMsUcyh9zKH/Mofzdm8NHqads9hNQUFCAw4cPIyws7N9gFAqEhYUhPj6+2G3i4+Mt+gNAeHi4Rf/Q0FD8/PPPuHbtGiRJwo4dO3Du3Dl0794dAHD48GEUFhZa7Kdp06aoV6/efY9rSzcSjEj604gz25X4/Ru9rcMhIiIiqhBUtjrwzZs3YTQa4e7ubtHu7u6Os2fPFrtNcnJysf2Tk5PNzxcuXIgxY8agbt26UKlUUCgU+OKLL9C5c2fzPjQaDVxdXR+4n3vp9Xro9f8WkZmZmQBMf1GIovjwN1xK9YOU6DFBh00L8hG3JB/VPRVo3k1Tbsej8iGKIiRJKtefFSpfzKH8MYfyxxzK3705fJRc2qyILS8LFy7E/v378fPPP8Pb2xu7d+/G2LFj4enpWWQU1xoxMTGYPXt2kfa0tDTk5+c/SsgP5d1BRJOTRiRsc8CP7+TAqM5A7aY2mwVCpSCKIjIyMiBJEr8CkynmUP6YQ/ljDuXv3hxmZWWVel82K2Jr1qwJpVJZZFWAlJQUeHh4FLuNh4fHA/vn5eVh+vTp+Omnn9CrVy8AQIsWLXDs2DF8+OGHCAsLg4eHBwoKCpCenm4xGvug4wLAtGnTEB0dbX6emZkJLy8vuLm5leucWMCU8K6j04A8FRL2GrDlfQ1Gf+6I6nU4P1YuRFGEIAhwc3PjL16ZYg7ljzmUP+ZQ/u7NoU6nK/W+bFbEajQaBAUFIS4uDpGRkQBMbywuLg7jxo0rdpuQkBDExcVh0qRJ5ratW7ciJCQEAFBYWIjCwsIiP9hKpdI8XB0UFAS1Wo24uDgMHDgQAJCQkICkpCTzfoqj1Wqh1WqLtCsUisdyIilVAgbNdMCy8dm4nmDEytdzMOZzZ9g58ySWC0EQHtvPC5UP5lD+mEP5Yw7l7+4cPkoebTqdIDo6GsOHD0ebNm3Qrl07LFiwADk5ORg5ciQAYNiwYahTpw5iYmIAABMnTkSXLl0wf/589OrVC6tXr8ahQ4ewZMkSAICzszO6dOmCKVOmwM7ODt7e3ti1axe+/vprfPTRRwAAFxcXjBo1CtHR0ahevTqcnZ0xfvx4hISElHhlAlvR2AkY+h8nLHkxEzeTRHw7PRvDPnaCSi3YOjQiIiKix8qmRWxUVBTS0tIwY8YMJCcnIzAwEFu2bDFfvJWUlGRRoYeGhmLVqlV46623MH36dDRq1Ajr1q1D8+bNzX1Wr16NadOmYejQobh9+za8vb3xzjvv4KWXXjL3+fjjj6FQKDBw4EDo9XqEh4fj008/fXxv/BE4uynw7PuO+N/Lmbh01ICf/5OD/m86QBBYyBIREVHVYdN1YuXsca0TCxS/Lt75AwX4Zko2RCPQbbQdnhhhV64x0KPh2obyxxzKH3Mof8yh/FWKdWLp0TQK1qB3tD0AIO6LPBz/jWvIEhERUdXBIlbG2kbq0GGI6aq+n97NwZXjvDctERERVQ0sYmWu+yt28OushrEQWDUtG7euGm0dEhEREVG5YxErcwqFgEEzHVHHT4ncDAkrpmQhN4N3MiEiIqLKjUVsJaDRmZbecnFX4NZV09JbhgJer0dERESVF4vYSsKphgLPfegIrYOAy8cMWPdeDrjwBBEREVVWLGIrEfcGKgye5wiFEjj+awF2LMu3dUhERERE5YJFbCXTsJ0afV4zLb2148s8HPuVS28RERFR5cMithJq01eHTs+alt5a924OLh/j0ltERERUubCIraTCXrRDs65qGA3AqqnZSLvCpbeIiIio8mARW0kpFAIGvu2Iuv5K5GVJ+GZKFnLSufQWERERVQ4sYisxtda09JZrbQVuXxOxalo2CvVcsYCIiIjkj0VsJedYXYHnPnCCzlFA0gkDforh0ltEREQkfyxiq4Ba9ZUY/I5p6a0/txZg+//ybB0SERER0SNhEVtF+LZRo+/rDgCAncvzcXQTl94iIiIi+WIRW4UE9dai8zDT0lvr/5ODi4e59BYRERHJE4vYKqbbaDs076aB0QB8+yaX3iIiIiJ5YhFbxSgUAga86YB6ASrkZ0lY8VoWsv/m0ltEREQkLyxiqyC1VsAzMY6o5qnA39dFfDUpC7mZLGSJiIhIPljEVlEO1RQYNt8JjtUFJCca8fXkLORns5AlIiIieWARW4XVrKfEiP86wd5VwLWzRnwdnQV9DteQJSIiooqPRWwV595AhRELnGDnJODqKSNWvJaFgjwWskRERFSxsYgl1G6kwvAFprt6XTlhwMo3snh7WiIiIqrQWMQSAKBOUxWGzXeCxg64eNiAVdOyWcgSERFRhcUilsy8mpsKWbUOSDxQiDVvZ8NQyEKWiIiIKh4WsWTBu6Uaz77vBJUGSNhbiO9mZMNoYCFLREREFQuLWCqiQZAaQ99zglINnNldiO/n5LCQJSIiogqFRSwVq2GwGkPedYRSBZyMK8BPMTkQjSxkiYiIqGJgEUv31SRUg6fnOEKhBI5vKcD693MgiixkiYiIyPYqRBG7ePFi+Pj4QKfTITg4GAcPHnxg/7Vr16Jp06bQ6XQICAjApk2bLF4XBKHYxwcffGDu4+PjU+T19957r1zen5z5d9Fg0EwHCArgyIYCbPwoF5LEQpaIiIhsy+ZF7Jo1axAdHY2ZM2fiyJEjaNmyJcLDw5Gamlps/3379mHIkCEYNWoUjh49isjISERGRuLkyZPmPjdu3LB4LF26FIIgYODAgRb7mjNnjkW/8ePHl+t7lauAbloMfMsBggAc/EmPzf9lIUtERES2ZfMi9qOPPsLo0aMxcuRI+Pv7IzY2Fvb29li6dGmx/f/73/8iIiICU6ZMgZ+fH+bOnYvWrVtj0aJF5j4eHh4Wj/Xr16Nr165o0KCBxb6cnJws+jk4OJTre5WzluFa9Jtq+nzi1+rx26d5LGSJiIjIZlS2PHhBQQEOHz6MadOmmdsUCgXCwsIQHx9f7Dbx8fGIjo62aAsPD8e6deuK7Z+SkoKNGzfiq6++KvLae++9h7lz56JevXp45plnMHnyZKhUxX8ker0eer3e/DwzMxMAIIoiRFF84Pt8VKIoQpKkcj/Ow7TqqYahwA4b5udhz6p8KNQSur1gZ9OY5KKi5JBKjzmUP+ZQ/phD+bs3h4+SS5sWsTdv3oTRaIS7u7tFu7u7O86ePVvsNsnJycX2T05OLrb/V199BScnJwwYMMCifcKECWjdujWqV6+Offv2Ydq0abhx4wY++uijYvcTExOD2bNnF2lPS0tDfn7+fd9jWRBFERkZGZAkCQqFbQfPvUOBjn8rsGepCru/0iNfn4O2/8dfJg9TkXJIpcMcyh9zKH/Mofzdm8OsrKxS78umRezjsHTpUgwdOhQ6nc6i/e7R3BYtWkCj0eDFF19ETEwMtFptkf1MmzbNYpvMzEx4eXnBzc0Nzs7O5fcGYEq4IAhwc3OrECftUyMBe10+fvs0HwdXq+DiqkPHobqHb1iFVbQckvWYQ/ljDuWPOZS/e3N4b31mDZsWsTVr1oRSqURKSopFe0pKCjw8PIrdxsPDo8T9f//9dyQkJGDNmjUPjSU4OBgGgwGXL19GkyZNiryu1WqLLW4VCsVjOZEEQXhsxyqJTkPtYTQIiFuSh62x+VBpFAiNYiH7IBUth2Q95lD+mEP5Yw7l7+4cPkoebfoToNFoEBQUhLi4OHObKIqIi4tDSEhIsduEhIRY9AeArVu3Ftv/yy+/RFBQEFq2bPnQWI4dOwaFQoFatWpZ+S6qrieG2+GJkabCdfMnuTj4U/lOqyAiIiK6w+bTCaKjozF8+HC0adMG7dq1w4IFC5CTk4ORI0cCAIYNG4Y6deogJiYGADBx4kR06dIF8+fPR69evbB69WocOnQIS5YssdhvZmYm1q5di/nz5xc5Znx8PA4cOICuXbvCyckJ8fHxmDx5Mp599llUq1at/N90JfLkKDsYC4Hfv8nHLx/mQqkSENSn6Ig1ERERUVmyeREbFRWFtLQ0zJgxA8nJyQgMDMSWLVvMF28lJSVZDDWHhoZi1apVeOuttzB9+nQ0atQI69atQ/PmzS32u3r1akiShCFDhhQ5plarxerVqzFr1izo9XrUr18fkydPLrLqAT2cIAh46iU7GAokxH+nx/r/5EChAlr1YCFLRERE5UeQuNhnqWRmZsLFxQUZGRmP5cKu1NRU1KpVq8LOAZIkCRs+ysXBH/UQFMD/zXRAQBgL2TvkkEN6MOZQ/phD+WMO5e/eHD5KPcWfACoTgiCg12R7BPXRQhKB7+fk4NTOAluHRURERJUUi1gqMwqFgL6v2yMwQgPRCHw3IxvHftU/fEMiIiIiK7GIpTKlUAjoP90BLcNNhewPc3KwbzVXLSAiIqKyxSKWypxCKWDAWw4Iedo0J3bzwlz8+mkuOP2aiIiIygqLWCoXCoWAHhPs8dRLdgCAPSvz8dO7OTAaWMgSERHRo2MRS+VGEAR0fs4OkdMcICiAo5sK8O30bBTks5AlIiKiR8MilspdUG8thrzrCJUGSNhbiK8mZyEvU7R1WERERCRjLGLpsfDrpMGIBU7QOQlIOmHA/17JQmYaC1kiIiIqHRax9Nh4t1Rj1GInONUUkHrJiCUvZiLtitHWYREREZEMsYilx8rDV4UxnzujhpcCGSki/vdyJv46bbB1WERERCQzLGLpsXP1UGL0Z86o46dEboaEpeMzcf4A7+5FREREJccilmzCoZoCIz9xRsN2KhTmA99MycZx3t2LiIiISohFLNmM1l7A0PedEPCU6e5e38/Jwb41vLsXERERPRyLWLIplVrAoBkOaP9//9zd65Nc/PYZ7+5FRERED8YilmxOoRDQc6I9wl403d3r92/yse493t2LiIiI7o9FLFUIgiCgyzA7RE413d3ryAbe3YuIiIjuj0UsVShBfXh3LyIiIno4FrFU4fh10mD4x07QOf5zd6+xvLsXERERWWIRSxWST6Aaoz51glMNAakXjfjiJd7di4iIiP7FIpYqLA9fFUb/c3ev9GQR/3slE3+d4d29iIiIiEUsVXDVav9zd6+mSuSmS1g2PhOJBwptHRYRERHZGItYqvDu3N3Lt60KBXnAiilZOLaFd/ciIiKqyljEkixoHQQ8+4ETAsJMd/f6YW4OtizK5VqyREREVRSLWJINlVrAoJkO6DJcBwDY+20+VryWhVwuwUVERFTlsIglWVEoBISNsUfUXEeodcCFPwz4/IVMpFzkBV9ERERVidVF7JYtW7Bnzx7z88WLFyMwMBDPPPMM/v777zINjuh+mj+pwehYZ7jWVuD2NRFLxmTi9O4CW4dFREREj4nVReyUKVOQmZkJAPjzzz/x6quvomfPnrh06RKio6PLPECi+6ndSIWX/ueM+q1NF3x9Oy0b27/MhShyniwREVFlZ3URe+nSJfj7+wMAfvjhB/Tu3RvvvvsuFi9ejM2bN5d5gEQP4uCqwPCPnRDyf1oAwI6l+Vj9Zjb0OSxkiYiIKjOri1iNRoPc3FwAwLZt29C9e3cAQPXq1c0jtESPk1IloOckB/Sf7gClGjizuxCfj8nErb94hy8iIqLKyuoitmPHjoiOjsbcuXNx8OBB9OrVCwBw7tw51K1bt1RBLF68GD4+PtDpdAgODsbBgwcf2H/t2rVo2rQpdDodAgICsGnTJovXBUEo9vHBBx+Y+9y+fRtDhw6Fs7MzXF1dMWrUKGRnZ5cqfqoYWvfSYtRiZzjVEJB22YjYFzJx/gDnyRIREVVGVhexixYtgkqlwvfff4/PPvsMderUAQBs3rwZERERVgewZs0aREdHY+bMmThy5AhatmyJ8PBwpKamFtt/3759GDJkCEaNGoWjR48iMjISkZGROHnypLnPjRs3LB5Lly6FIAgYOHCguc/QoUNx6tQpbN26FRs2bMDu3bsxZswYq+OnisWrmQovL3WBVzMl8rMkrHgtG3tW5UGSOL2AiIioMhEkG//vHhwcjLZt22LRokUAAFEU4eXlhfHjx2Pq1KlF+kdFRSEnJwcbNmwwt7Vv3x6BgYGIjY0t9hiRkZHIyspCXFwcAODMmTPw9/fHH3/8gTZt2gAwrbrQs2dP/PXXX/D09Hxo3JmZmXBxcUFGRgacnZ2tft/WEEURqampqFWrFhQKropWEoYCCRvm5+LwBtOdvVp01yByqgPUWsEm8TCH8sccyh9zKH/Mofzdm8NHqadU1h78yJEjUKvVCAgIAACsX78ey5Ytg7+/P2bNmgWNRlPifRUUFODw4cOYNm2auU2hUCAsLAzx8fHFbhMfH19kFYTw8HCsW7eu2P4pKSnYuHEjvvrqK4t9uLq6mgtYAAgLC4NCocCBAwfQv3//IvvR6/XQ6/+91emd+b+iKEIUy3exfVEUIUlSuR+nMlGogD6v6+DeUIEtC/Nw4rcCpF02YvC7DnB1f/y/+JhD+WMO5Y85lD/mUP7uzeGj5NLqIvbFF1/E1KlTERAQgIsXL2Lw4MHo378/1q5di9zcXCxYsKDE+7p58yaMRiPc3d0t2t3d3XH27Nlit0lOTi62f3JycrH9v/rqKzg5OWHAgAEW+6hVq5ZFP5VKherVq993PzExMZg9e3aR9rS0NOTn5xe7TVkRRREZGRmQJIl/eVqpfiegbzUBW+arcOOcEbGjMhDxmgGe/o/3CwjmUP6YQ/ljDuWPOZS/e3OYlZVV6n1ZXcSeO3cOgYGBAEwXWHXu3BmrVq3C3r17MXjwYKuK2Mdh6dKlGDp0KHQ63SPtZ9q0aRYjwJmZmfDy8oKbm9tjmU4gCALc3Nx40pZCrSeB+v4ivp2eg+TzRqyfpUbPSXZoG6l9bDEwh/LHHMofcyh/zKH83ZvDR6nPrC5i7x4C3rZtG3r37g0A8PLyws2bN63aV82aNaFUKpGSkmLRnpKSAg8Pj2K38fDwKHH/33//HQkJCVizZk2Rfdx74ZjBYMDt27fve1ytVguttmjRo1AoHsuJJAjCYztWZVTdU4HRsc746d0cnIwrwIb5eUhOFNFrsj1U6sczT5Y5lD/mUP6YQ/ljDuXv7hw+Sh6t3rJNmzaYN28eVqxYgV27dpmX2Lp06VKRr/kfRqPRICgoyHzBFWCq0OPi4hASElLsNiEhIRb9AWDr1q3F9v/yyy8RFBSEli1bFtlHeno6Dh8+bG7bvn07RFFEcHCwVe+B5EOjE/D0bAc89ZIdBAE4tF6PZROykH2bc6uIiIjkxuoidsGCBThy5AjGjRuHN998Ew0bNgQAfP/99wgNDbU6gOjoaHzxxRf46quvcObMGbz88svIycnByJEjAQDDhg2zuPBr4sSJ2LJlC+bPn4+zZ89i1qxZOHToEMaNG2ex38zMTKxduxYvvPBCkWP6+fkhIiICo0ePxsGDB7F3716MGzcOgwcPLtHKBCRfgiCg83N2ePZ9R+gcBSSdMOCz5zNw7YzB1qERERGRFayeTtCiRQv8+eefRdo/+OADKJVKqwOIiopCWloaZsyYgeTkZAQGBmLLli3mUd2kpCSLoebQ0FCsWrUKb731FqZPn45GjRph3bp1aN68ucV+V69eDUmSMGTIkGKPu3LlSowbNw7dunWDQqHAwIED8cknn1gdP8lT41ANXvxCiZVTs3Dzioj/vZKJfm84IDDi8c2TJSIiotIr9Tqxhw8fxpkzZwAA/v7+aN26dZkGVtFxndjKIT9bxPdzcpCwtxAAEDpYh+4v20GpKtt5ssyh/DGH8sccyh9zKH82XSc2NTUVUVFR2LVrF1xdXQEA6enp6Nq1K1avXg03Nzdrd0lkMzpHBZ55zxHb/5eHXV/lY9/qfFz9sxD/N8sR1Tyt/2aBiIiIHg+r/4wZP348srOzcerUKdy+fRu3b9/GyZMnkZmZiQkTJpRHjETlSqEQEDbGHoPnmebJXj1lxOIRmTixVf/wjYmIiMgmrC5it2zZgk8//RR+fn7mNn9/fyxevBibN28u0+CIHqdmXTV4Zbkz6gWooM+RsHZWDn58Jxv6XJvemZmIiIiKYXURK4oi1Gp1kXa1Ws3bwJHsVautxPOLnPDESB0EBXB0U4Fp9YKzXL2AiIioIrG6iH3yyScxceJEXL9+3dx27do1TJ48Gd26dSvT4IhsQakS0O0Fezy/0AnOtRS4dVXEFy9mYs+qPIgiR2WJiIgqAquL2EWLFiEzMxM+Pj7w9fWFr68v6tevj8zMTCxcuLA8YiSyCZ9ANcZ+5Qz/LmoYDcCvi/Ow4tUsZN3iNw5ERES2ZvXqBF5eXjhy5Ai2bduGs2fPAjDdPCAsLKzMgyOyNXtnBQa/44hD6/XY/EkuEg8asHh4Bga86YDGIRpbh0dERFRlWV3EAqa7Hj311FN46qmnyjoeogpHEAS0jdTBu6Ua383MRsoFI1a8lo2Qp7Xo/rI9VJqyXVOWiIiIHq5ERaw1d7LiMltUWdWqr8SLXzjjt09zsf97PeK/0+PSUQOenu0IN2+uKUtERPQ4laiI/fjjj0u0M0EQWMRSpabWCug12QEN26nx47s5SD5vxGfPZ6DXJAe07q2BIHBUloiI6HEoURF76dKl8o6DSFaadNBg7HIVfpiXjYuHDFj3Xg7OHyxEv9ftYefEWyESERGVN/5vS1RKzm4KDP/YCU+9bAeFEji1vQCLh2fiyolCW4dGRERU6bGIJXoECoWAzs/aYXSsM6p5KpCRIuLLsVnYvjQPRgPXlCUiIiovLGKJykBdfxVeWe6CluEaSCKw48s8LJuQhfRko61DIyIiqpRYxBKVEZ2DgEEzHDFwhgM0dsCV4wYsHpGJUzsKbB0aERFRpcMilqiMBYZrMXa5C+r6K5GfJWH1W9n4+f1cFOptHRkREVHlUaoi9vfff8ezzz6LkJAQXLt2DQCwYsUK7Nmzp0yDI5Kr6nWVeOEzZ3R6VgdBAA7/UoDvXlPjynGDrUMjIiKqFKwuYn/44QeEh4fDzs4OR48ehV5vGl7KyMjAu+++W+YBEsmVUiWg+8v2GL7ACU41BaRfF7B0XDY2zM+BPocXfRERET0Kq4vYefPmITY2Fl988QXUarW5vUOHDjhy5EiZBkdUGfi2UWPs107w62a6yOvAj3osfC4D5w9wriwREVFpWV3EJiQkoHPnzkXaXVxckJ6eXhYxEVU6dk4KPPmKEcM+doBrbdNSXF9HZ+OHudnIzRRtHR4REZHsWF3Eenh4IDExsUj7nj170KBBgzIJiqiy8m2jxvgVLgh5WgtBAI5tKcAnz2TgJFcwICIisorVRezo0aMxceJEHDhwAIIg4Pr161i5ciVee+01vPzyy+URI1GlorET0HOiA16IdYKbjwI5f0tY81Y2vp2ehaybHJUlIiIqCZW1G0ydOhWiKKJbt27Izc1F586dodVq8dprr2H8+PHlESNRpVSvuRqvLHPBzuV5+P2bfJzeVYiLRzLQY7w9WvXUQBAEW4dIRERUYVk9EisIAt58803cvn0bJ0+exP79+5GWloa5c+eWR3xElZpKIyBsjD1e+tIZnk1M68r+9G4Ovpqchb9v8G5fRERE91Pqmx1oNBr4+/ujXbt2cHR0LMuYiKqc2o1UGLPEGd1fsYNKA1z4w4BFz2Vg/9p8iCKX4yIiIrqX1dMJcnJy8N577yEuLg6pqakQRcs5fBcvXiyz4IiqEqVKQKehdvDrpMG693Jw5bgBGxfk4s/tBYic6gA3b6WtQyQiIqowrC5iX3jhBezatQvPPfccateuzXl7RGWsZj0lnl/khD/W6fHbp7lIOmHA4uEZ6DrSDh2H6qBU8ZwjIiKyuojdvHkzNm7ciA4dOpRHPEQEQKEQEDxAhyahavz8QS7O7y/EtiV5OLmjAP2nO8CzsdWnLhERUaVi9ZzYatWqoXr16uURCxHdw9VDiec+dMTAtx1g5ywg+bwRn7+Qia2xuSjUc64sERFVXVYXsXPnzsWMGTOQm5tbJgEsXrwYPj4+0Ol0CA4OxsGDBx/Yf+3atWjatCl0Oh0CAgKwadOmIn3OnDmDvn37wsXFBQ4ODmjbti2SkpLMrz/xxBMQBMHi8dJLL5XJ+yEqa4IgIDBCiwkrXdDsSQ1EI7B7RT4+HZGBKycKbR0eERGRTVhdxM6fPx+//vor3N3dERAQgNatW1s8rLFmzRpER0dj5syZOHLkCFq2bInw8HCkpqYW23/fvn0YMmQIRo0ahaNHjyIyMhKRkZE4efKkuc+FCxfQsWNHNG3aFDt37sSJEyfw9ttvQ6fTWexr9OjRuHHjhvnx/vvvW/tRED1WjtUVGDzXEUPedYRjDQE3k0R8+UoWNnyUg/wcjsoSEVHVIkiSZNX/frNnz37g6zNnzizxvoKDg9G2bVssWrQIACCKIry8vDB+/HhMnTq1SP+oqCjk5ORgw4YN5rb27dsjMDAQsbGxAIDBgwdDrVZjxYoV9z3uE088gcDAQCxYsKDEsd4rMzMTLi4uyMjIgLOzc6n3UxKiKCI1NRW1atWCQlHqVdHIhso6h3mZIrYsysWRjabb1TrWEBD+ij1adNdAoeCFX+WB56H8MYfyxxzK3705fJR6yuqrQ6wpUh+koKAAhw8fxrRp08xtCoUCYWFhiI+PL3ab+Ph4REdHW7SFh4dj3bp1AEwfzMaNG/H6668jPDwcR48eRf369TFt2jRERkZabLdy5Up888038PDwQJ8+ffD222/D3t7+vvHq9Xro9Xrz88zMTPMx711mrKyJoghJksr9OFR+yjqHWkeg31R7NO+mxoaP8nD7LxE/zM3BwZ/y0XOSHTyb8MKvssbzUP6YQ/ljDuXv3hw+Si5t9j/dzZs3YTQa4e7ubtHu7u6Os2fPFrtNcnJysf2Tk5MBAKmpqcjOzsZ7772HefPm4T//+Q+2bNmCAQMGYMeOHejSpQsA4JlnnoG3tzc8PT1x4sQJvPHGG0hISMCPP/5433hjYmKKHYVOS0tDfn6+Ve/dWqIoIiMjA5Ik8S9PmSqvHDp5A09/CBzfoMAf3ytx9aQRn4/Ogn83Ee2fMcLOpcwOVeXxPJQ/5lD+mEP5uzeHWVlZpd5XiYrY6tWr49y5c6hZsyaqVav2wLVhb9++XepgHtWdar5fv36YPHkyACAwMBD79u1DbGysuYgdM2aMeZuAgADUrl0b3bp1w4ULF+Dr61vsvqdNm2YxCpyZmQkvLy+4ubk9lukEgiDAzc2NJ61MlXcOa78IhA4QsfWzPJzYWojT25S4uF+JrqPs0DZSw7VlywDPQ/ljDuWPOZS/e3N47zVL1ihREfvxxx/DyckJAB5pHundatasCaVSiZSUFIv2lJQUeHh4FLuNh4fHA/vXrFkTKpUK/v7+Fn38/PywZ8+e+8YSHBwMAEhMTLxvEavVaqHVaou0KxSKx3IiCYLw2I5F5aO8c+jqrsD/zXJCu/6F2PBxLpLPG7H5v3k4/HMBek22R4MgdbkctyrheSh/zKH8MYfyd3cOHyWPJSpihw8fXuy/H4VGo0FQUBDi4uLM81VFUURcXBzGjRtX7DYhISGIi4vDpEmTzG1bt25FSEiIeZ9t27ZFQkKCxXbnzp2Dt7f3fWM5duwYAKB27dqlf0NEFYR3SzVe/tIZh3/RY9uSPKReMmLZhCw0e1KDiLF2cPXg7WuJiEj+SlTE3rmIqSSs+Wo9Ojoaw4cPR5s2bdCuXTssWLAAOTk5GDlyJABg2LBhqFOnDmJiYgAAEydORJcuXTB//nz06tULq1evxqFDh7BkyRLzPqdMmYKoqCh07twZXbt2xZYtW/DLL79g586dAExLcK1atQo9e/ZEjRo1cOLECUyePBmdO3dGixYtShw7UUWmUApoG6lDsyc12P5FHg6u0+PU9gKc21uATs+abl+r1nKKARERyVeJilhXV9cHzoMFAEmSIAgCjEZjiQ8eFRWFtLQ0zJgxA8nJyQgMDMSWLVvMF28lJSVZDDOHhoZi1apVeOuttzB9+nQ0atQI69atQ/Pmzc19+vfvj9jYWMTExGDChAlo0qQJfvjhB3Ts2BGAabR227Zt5oLZy8sLAwcOxFtvvVXiuInkwt5Zgd6vOqBNPy02LsjF5aMGbP8yD0c26dFjvD38Oqsfem4TERFVRCVaJ3bXrl0l3uGdi6cqO64TS9aoCDmUJAkn4wqwZXEeMlNNF0H6tlGh52QH1PLhFIOHqQg5pEfDHMofcyh/j32d2KpSmBJVZoIgICBMiyYdNNi9Ig97v83HhUMGLB6WgfaDtOj6vB10jvxPgYiI5KFU68Smp6fj4MGDSE1NLbJI7bBhw8okMCIqHxo7AWFj7NG6lxabF+bi7O+F2LdGj+O/FeCpl+zRqifv+kVERBWf1UXsL7/8gqFDhyI7OxvOzs4W8+kEQWARSyQT1esoMfQ9J5w/UIBNC3JxM0nEupgc/LEuH72jHVDXn3f9IiKiisvq7w5fffVVPP/888jOzkZ6ejr+/vtv88OWNzogotJpFKzB2K9dEDHODlp74NoZIz4fnYmf3s1G9m3e2pGIiComq4vYa9euYcKECbC3ty+PeIjIBlRqAR2G2GHit65o1UMDADiysQALotKxY2ke9DkPvf6TiIjosbK6iA0PD8ehQ4fKIxYisjGnmgoMeMsRYz53Rp2mSuhzge1f5uHjp9Oxf20+DIUsZomIqGKwetJbr169MGXKFJw+fRoBAQFQqy1vZdm3b98yC46IbMOruQpjvnDGqR0F2LYkD7f/ErFxQS72rslHt9F2aPEUL/4iIiLbKtE6sXd70Lps1t7sQM64TixZQ845NBokHNmgx46leci6Zfp14d5QiadetEPjkKpzswQ555BMmEP5Yw7lryzXibX6J0AUxfs+qkoBS1SVKFWmW9hO+s4VYS/aQecoICXRiG+mZOPLsVlI+rPQ1iESEVEVxD9jiKhENDoBXYbZYfJaF3R8RgeVBrhy3IAvXsrCyjeykHLRYOsQiYioCilVEbtr1y706dMHDRs2RMOGDdG3b1/8/vvvZR0bEVVA9s4KhI+1x6Q1rgjqo4WgAM7uKcTiYZn4cV420pP5jQwREZU/q4vYb775BmFhYbC3t8eECRMwYcIE2NnZoVu3bli1alV5xEhEFZBLLQUipzpg/Dcu8H9CDUkCjm4uwILBGdj03xzkpHONWSIiKj9WX9jl5+eHMWPGYPLkyRbtH330Eb744gucOXOmTAOsqHhhF1mjKuTwr9MG/PZZLi4dMU0r0NoDHZ6xQ2iUDlp7+V/8VRVyWNkxh/LHHMqfTS/sunjxIvr06VOkvW/fvrh06ZK1uyOiSqKuvwojP3HC8I+cULvxP2vM/u+fNWa/5xqzRERUtqwuYr28vBAXF1ekfdu2bfDy8iqToIhIngRBQMNgNV760hlPz3ZA9boK5PwtYePHufjkmQwc/1UPUWQxS0REj87qmx28+uqrmDBhAo4dO4bQ0FAAwN69e7F8+XL897//LfMAiUh+FAoBAWFa+D+hweFf9NixLA9/Xxfx/Zwc/L4qH91ftEOjKrTGLBERlT2ri9iXX34ZHh4emD9/Pr777jsApnmya9asQb9+/co8QCKSL6VKQLv+OgRGaBH/XT5+X5mPlEQjVkzJRr0AFboM16FRexazRERkPauLWADo378/+vfvX9axEFElpbET0GW4HdpGarF7RT4O/JCPpD8NWPFaNuo0VaLLCDs07chiloiISo6X9hHRY2PvokDEOHtEr3VF6GAd1Drg2lkjVk3NxuIRmTi5vQCikXNmiYjo4VjEEtFj51RTgR7j7fHq967o/JwOWnsgJdGINW9nY+FzGTj2qx5GA4tZIiK6PxaxRGQzDtUUeOole0T/4Iquz+ugcxJw84qIH+bk4JNnMnB4g55LcxERUbFYxBKRzdk7K/DkKHu8+oMrwl60g72rgNvXRKyLycGCqAwc/CkfhgIWs0RE9C8WsURUYegcBHQZZodXv3dFxDg7OFYXkJEi4pcPc/HR/6Uj/rt8FOSzmCUiolKsTmA0GrF8+XLExcUhNTUVomh5f/Tt27eXWXBEVDVp7AR0GGKHdgN0OPyLHr+vzEdmqohN/83Frq/z0GGIDu0iddA6cDUDIqKqyuoiduLEiVi+fDl69eqF5s2bc0kcIio3aq2A9oN0aNNXi6Ob9di9Ih/pN0T89mkefv8mH6FROrQfpIXOkV8qERFVNVYXsatXr8Z3332Hnj17lkc8RERFqDQC2vbToXUvLU78VoBdX+fh1lURcV/kYe+3+QgeqEVolA72LixmiYiqCquLWI1Gg4YNG5ZHLERED6RUCWjVU4uW4Rqc3F6AXV/lI/WSEbu+ykf8d/loN0CHDkN0cKzGYpaIqLKz+jf9q6++iv/+97+QJF5cQUS2oVAKaPGUFmO/dsbgdxxRu7ESBXnAnpX5mD8gHT+/n4O0K0Zbh0lEROXI6pHYPXv2YMeOHdi8eTOaNWsGtVpt8fqPP/5YZsERET2IQiGg2RMa+HdR41x8IXYuy8Nfp434Y70ef6zXo0kHNToM1sGnlYrz94mIKhmrR2JdXV3Rv39/dOnSBTVr1oSLi4vFw1qLFy+Gj48PdDodgoODcfDgwQf2X7t2LZo2bQqdToeAgABs2rSpSJ8zZ86gb9++cHFxgYODA9q2bYukpCTz6/n5+Rg7dixq1KgBR0dHDBw4ECkpKVbHTkQVgyAIaBKqwZglzhi12AlNO6ohCEDC3kIsHZ+F2FGZOM67gBERVSpWj8QuW7aszA6+Zs0aREdHIzY2FsHBwViwYAHCw8ORkJCAWrVqFem/b98+DBkyBDExMejduzdWrVqFyMhIHDlyBM2bNwcAXLhwAR07dsSoUaMwe/ZsODs749SpU9DpdOb9TJ48GRs3bsTatWvh4uKCcePGYcCAAdi7d2+ZvTcievwEQYBPoBo+gWrcTDIi/rt8HN2kx/UEI76fk4PfYvMQMkiLoL5a2Dlx3iwRkZwJkg0ntwYHB6Nt27ZYtGgRAEAURXh5eWH8+PGYOnVqkf5RUVHIycnBhg0bzG3t27dHYGAgYmNjAQCDBw+GWq3GihUrij1mRkYG3NzcsGrVKgwaNAgAcPbsWfj5+SE+Ph7t27cvUeyZmZlwcXFBRkYGnJ2drXrf1hJFEampqahVqxYUCv7HK0fMoe3kpIv4Y70eB77PR/Zt0687jR0Q1FuLkKd1qOapLNF+mEP5Yw7ljzmUv3tz+Cj1lNUjsQDw/fff47vvvkNSUhIKCgosXjty5EiJ9lFQUIDDhw9j2rRp5jaFQoGwsDDEx8cXu018fDyio6Mt2sLDw7Fu3ToApg9m48aNeP311xEeHo6jR4+ifv36mDZtGiIjIwEAhw8fRmFhIcLCwsz7aNq0KerVq/fAIlav10Ov15ufZ2Zmmo957w0fypooipAkqdyPQ+WHObQdO2eg83NahEZp8OfWAuz7To/UiyLi1+qx/wc9/DqrETpYC69mD/51yBzKH3Mof8yh/N2bw0fJpdVF7CeffII333wTI0aMwPr16zFy5EhcuHABf/zxB8aOHVvi/dy8eRNGoxHu7u4W7e7u7jh79myx2yQnJxfbPzk5GQCQmpqK7OxsvPfee5g3bx7+85//YMuWLRgwYAB27NiBLl26IDk5GRqNBq6urvfdT3FiYmIwe/bsIu1paWnIz88vyVsuNVEUkZGRAUmS+JenTDGHFUOdtsCgNsDV4wKO/azE1eMKnN5ZiNM7C+HRRERgHyPqt5OgKGZwljmUP+ZQ/phD+bs3h1lZWaXel9VF7KeffoolS5ZgyJAhWL58OV5//XU0aNAAM2bMwO3bt0sdSFm4U83369cPkydPBgAEBgZi3759iI2NRZcuXUq972nTplmMAmdmZsLLywtubm6PZTqBIAhwc3PjSStTzGHF4t4daNMdSLloRPwaPU5sLUByggJbEhSoVluB9k9r0aqnBlr7f1c0YA7ljzmUP+ZQ/u7N4d3XLFnL6iI2KSkJoaGhAAA7OztzBf3cc8+hffv25vmtD1OzZk0olcoiqwKkpKTAw8Oj2G08PDwe2L9mzZpQqVTw9/e36OPn54c9e/aY91FQUID09HSL0dgHHRcAtFottFptkXaFQvFYTiRBEB7bsah8MIcVT+2GCgx4U42nXhJx4Id8HPxJj79viNj83zzsWJqPtv20CB6og0stU86YQ/ljDuWPOZS/u3P4KHm0eksPDw/ziGu9evWwf/9+AMClS5esugGCRqNBUFAQ4uLizG2iKCIuLg4hISHFbhMSEmLRHwC2bt1q7q/RaNC2bVskJCRY9Dl37hy8vb0BAEFBQVCr1Rb7SUhIQFJS0n2PS0SVm1MNBcLG2OO1n1zR5zV71PBSID9Lwu/f5OOjQen4fk42bpwz2DpMIiK6i9UjsU8++SR+/vlntGrVCiNHjsTkyZPx/fff49ChQxgwYIBV+4qOjsbw4cPRpk0btGvXDgsWLEBOTg5GjhwJABg2bBjq1KmDmJgYAMDEiRPRpUsXzJ8/H7169cLq1atx6NAhLFmyxLzPKVOmICoqCp07d0bXrl2xZcsW/PLLL9i5cycAwMXFBaNGjUJ0dDSqV68OZ2dnjB8/HiEhISVemYCIKieNTkC7/jq06adFwt5C7Fudj8vHDDj+awGO/1oAz2YqdHi6AP5dtFCpefMEIiJbsrqIXbJkiXnu6Z0bBuzbtw99+/bFiy++aNW+oqKikJaWhhkzZiA5ORmBgYHYsmWL+eKtpKQki2Hm0NBQrFq1Cm+99RamT5+ORo0aYd26deY1YgGgf//+iI2NRUxMDCZMmIAmTZrghx9+QMeOHc19Pv74YygUCgwcOBB6vR7h4eH49NNPrf0oiKiSUigE+HXSwK+TBtfOGLB3TT5ObS/A9VMKrJ2ZC8caeWjTR4s2/f6dakBERI+XTdeJlTOuE0vWYA7l7+9kA3Z/+zfObleZ15tVKIEmHdQIHqBD/SAVFAqOzlZkPA/ljzmUv7JcJ7ZUPwG///47nn32WYSEhODatWsAgBUrVpgvniIiqmxcaikQPMSIyd874+k5DqjfSgXRCJzZXYjlk7LwyTMZ2Lc6H3mZXL+SiOhxsLqI/eGHHxAeHg47OzscPXrUfAOAjIwMvPvuu2UeIBFRRaJSCwjopsXzi5wx/hsXBA/UQmsP3LoqYvPCXHwQmY6fYrJx7SwvBCMiKk9WF7Hz5s1DbGwsvvjiC6jVanN7hw4dSny3LiKiyqBWfSV6Rztgyvpq6Pu6PdwbKlGoB45sKEDsqEzEvpCBIxv1KNRz1hYRUVmz+sKuhIQEdO7cuUi7i4sL0tPTyyImIiJZ0doLaNtPhzZ9tbh60oADP+pxakcBrp0x4qczOdiyMBete2vRNlKLGnWLuR0YERFZzeoi1sPDA4mJifDx8bFo37NnDxo0aFBWcRERyY4gCKgXoEa9ADV6ThBxeKMef/ykR3qyiL3f5mPvt/loGKxGu/5aNAlVQ6HkhWBERKVldRE7evRoTJw4EUuXLoUgCLh+/Tri4+Px2muv4e233y6PGImIZMehmgKdn7VDxyE6nD9QiIM/6nF+fyESD5geLu4KtOmnRZs+WjhW51XWRETWsrqInTp1KkRRRLdu3ZCbm4vOnTtDq9Xitddew/jx48sjRiIi2VIoBTQJ1aBJqAZ/Xzfij/V6HP5Fj4wUEXFL8rBzaR78n9CgTV8tfFpxmS4iopIq9TqxBQUFSExMRHZ2Nvz9/eHo6FjWsVVoXCeWrMEcyl9Z5rBQL+HUzgIc/FGPqyf/XcWgmqcCrXpq0aqHBq4enDtb1ngeyh9zKH9luU6s1SOxd2g0Gvj7+5d2cyKiKkutFRAYrkVguBY3zhnwx3o9/txWgL+vi9j+vzzs+DIPvm1VaN1LC7/OGqg0HJ0lIrpXiYvY559/vkT9li5dWupgiIiqmtqNVeg7RYWI8fY4s6sAhzfocemIAYkHTQ8751y07K5B615a1G5c6nEHIqJKp8S/EZcvXw5vb2+0atUKvFMtEVHZ0ugEtAzXomW4FrevGXF0kx5HNhUgM1XE/u/12P+9HrUbKxHUW4sWT2lg58yvUomoaitxEfvyyy/j22+/xaVLlzBy5Eg8++yzqF69ennGRkRUJVWvo0S30fbo+rwdLhwqxJENBTjzewFunDNiw0e52LIoF35dNAjqpUX9IF4MRkRVU4n/lF+8eDFu3LiB119/Hb/88gu8vLzw9NNP49dff+XILBFROVAoBTQK1iBqriNeX++KnpNMdwUzFAB/bi3A8klZ+Pj/MrD9y1ykJxttHS4R0WNV6tUJrly5guXLl+Prr7+GwWDAqVOnqtQKBVydgKzBHMpfRcmhJEm4cc6Iwxv0OLG1APlZpl/hggA0CFKhdW/TxWBqLUdn71VRckilxxzKX4VYnUChUEAQBEiSBKORIwBERI+DIAjwbKKCZxMVIsbZ48xu08VgFw8ZcOGfh84pFy2f0qB1by08m/BiMCKqnKz67abX6/Hjjz9i6dKl2LNnD3r37o1FixYhIiKCfxERET1maq2AFk9p0eIpLf6+8c/FYBsLkJEi4sCPehz4UQ/3hkoEhmvQ4iktnN34e5qIKo8SF7GvvPIKVq9eDS8vLzz//PP49ttvUbNmzfKMjYiISqhabSWeHGWPJ0ba4eIhA45s1OP0rgKkJBrxa2Iefvs0D/Vbq9AyXAv/LmroHFnQEpG8lbiIjY2NRb169dCgQQPs2rULu3btKrbfjz/+WGbBERGRdRQKAQ3bqdGwnRq5mSJO7SjA8V8LcOW4ARcPmx6/fAg07ahBi+4aNGqvhkrN+bNEJD8lLmKHDRsGQeAvOiIiubB3VqBtPx3a9tPh7xtGnPitAMd/0yPtsoiT2wtwcnsB7JwFBHTToGW4Bl7NVfw9T0SyYdXNDoiISJ6q1Vaiy3A7dB6mw43zRhz/tQAntuqRfUvCwZ/0OPiTHtU8FWjxlAYtw7Vw81baOmQiogfiZatERFWIIAjwbKyCZ2MVwl+xw8XDBhz/1TR/9u/rInZ9lY9dX+WjTlMlWoZrERCmgWN1zp8looqHRSwRURWlUP47f7bPFAln95jmzyYeKMS1s0ZcO5uLzQtz4dtWjZbhGvh10kBrz+kGRFQxsIglIiJodAJahGnRIkyLnL9F/BlXgBO/6XH1lBGJBwqReKAQal0O/Dpr0LK7Br5t1VCqWNASke2wiCUiIgsO1RRoP0iH9oN0uPWXEcd/K8DxX/W4/ZeIE78V4MRvBXCoJqB5Vw2ad9OgXoAKCiULWiJ6vFjEEhHRfdWoq8STz9uh60gdrp0x4vivevy5rQA5f0vmGyo41RDQrKsGzZ/UwCtABYWCBS0RlT8WsURE9FCCIKCuvwp1/VWIGG+PC38U4uT2ApzZXYisWxL2f6/H/u/1cHYT0OwJDZqHaVDXnwUtEZUfFrFERGQVpUpA4xANGodoYJgi4cKhQpyMK8CZ3wuRmSYhfq0e8Wv1cHFXmEdo6/oruQYtEZUpFrFERFRqKo2AJqEaNAnVwFAgIfGgaYT27O8FyEgRsW91Pvatzoerxz8FbTcN6jRlQUtEj45FLBERlQmVRkDTjho07ahBoV7C+QOmgjZhTwHSk0Xs/TYfe7/Nh2ttBZo/aRqh9WzCgpaISqdCrGC9ePFi+Pj4QKfTITg4GAcPHnxg/7Vr16Jp06bQ6XQICAjApk2bLF4fMWIEBEGweERERFj08fHxKdLnvffeK/P3RkRUFam1Avw7a/D0LEdM3VgNg99xRPNuGqh1QPoNEXtW5iN2VCYWRGVga2wubpwzQJIkW4dNRDJi85HYNWvWIDo6GrGxsQgODsaCBQsQHh6OhIQE1KpVq0j/ffv2YciQIYiJiUHv3r2xatUqREZG4siRI2jevLm5X0REBJYtW2Z+rtVqi+xrzpw5GD16tPm5k5NTGb87IiJSa00XezV7QoOCfAnn4k0jtOf2FuD2NRG7V+Rj94p81PAyjdA266qBR0OO0BLRg9m8iP3oo48wevRojBw5EgAQGxuLjRs3YunSpZg6dWqR/v/9738RERGBKVOmAADmzp2LrVu3YtGiRYiNjTX302q18PDweOCxnZycHtqHiIjKjkb3z/qyXTUoyJOQsK/AVNDuK8Stq//e9raapwL+XTTw66yGV3OuckBERdm0iC0oKMDhw4cxbdo0c5tCoUBYWBji4+OL3SY+Ph7R0dEWbeHh4Vi3bp1F286dO1GrVi1Uq1YNTz75JObNm4caNWpY9Hnvvfcwd+5c1KtXD8888wwmT54Mlar4j0Sv10Ov15ufZ2ZmAgBEUYQoiiV+z6UhiiIkSSr341D5YQ7ljzkseyot0KyrGs26qqHPlXBuXyFObjfdHezv6//OoXWsLqBpJzX8Oqnh01oFlbp0BS1zKH/Mofzdm8NHyaVNi9ibN2/CaDTC3d3dot3d3R1nz54tdpvk5ORi+ycnJ5ufR0REYMCAAahfvz4uXLiA6dOno0ePHoiPj4dSqQQATJgwAa1bt0b16tWxb98+TJs2DTdu3MBHH31U7HFjYmIwe/bsIu1paWnIz8+36n1bSxRFZGRkQJIkKBQVYhozWYk5lD/msPy5tzA9OuUBSccEXDygwJXDCmTfBg6tL8Ch9QXQ2EvwDhLhGyyiXisJal3J988cyh9zKH/35jArK6vU+7L5dILyMHjwYPO/AwIC0KJFC/j6+mLnzp3o1q0bAFiM5rZo0QIajQYvvvgiYmJiip0/O23aNIttMjMz4eXlBTc3Nzg7O5fjuzElXBAEuLm58aSVKeZQ/pjDx6uuNxDaDzAUSrh8xIAzvxfi7O+FyL4NnP9difO/K6HSAL7tVPDrpEaTDmrYuzw4L8yh/DGH8ndvDnU6K/4SvYdNi9iaNWtCqVQiJSXFoj0lJeW+c1U9PDys6g8ADRo0QM2aNZGYmGguYu8VHBwMg8GAy5cvo0mTJkVe12q1xRa3CoXisZxIgiA8tmNR+WAO5Y85fPw0WqBxiBKNQ7To86qEq6cMOLO7EKd3FeDv6yIS9hiQsMcAhTIPPoEq+HXWwK+zBi61is8Rcyh/zKH83Z3DR8mjTX8CNBoNgoKCEBcXZ24TRRFxcXEICQkpdpuQkBCL/gCwdevW+/YHgL/++gu3bt1C7dq179vn2LFjUCgUxa6IQEREtqdQCvBuoUbEOHtM/s4FY79yRtdRdnBvqIRoBC4eNmDjx7n4sH86Yl/IwK6v85B2xWjrsImonNh8OkF0dDSGDx+ONm3aoF27dliwYAFycnLMqxUMGzYMderUQUxMDABg4sSJ6NKlC+bPn49evXph9erVOHToEJYsWQIAyM7OxuzZszFw4EB4eHjgwoULeP3119GwYUOEh4cDMF0cduDAAXTt2hVOTk6Ij4/H5MmT8eyzz6JatWq2+SCIiKjEBEGAR0MVPBqq8OTzdrh9zYgzuwtwenchrv5pwLUzRlw7k4dtn+fBzUcBv84aNO2kgoq/4okqDZsXsVFRUUhLS8OMGTOQnJyMwMBAbNmyxXzxVlJSksVQc2hoKFatWoW33noL06dPR6NGjbBu3TrzGrFKpRInTpzAV199hfT0dHh6eqJ79+6YO3eueTqAVqvF6tWrMWvWLOj1etSvXx+TJ08usuoBERHJQ/U6SnQYYocOQ+yQdUvE2d9NBe2lw4VIuywi7XI+dn8NONZQo2nHXDTtqEGDIDXUWi7dRSRXgsRbpJRKZmYmXFxckJGR8Vgu7EpNTUWtWrU4B0immEP5Yw7lKS9LxLl40xza8/sLUXjXYjJqHeDbxnRRWJNQDZxqMq8VHc9D+bs3h49ST9l8JJaIiKi82Dkp0LK7Fi27a6HPM+Lo9ptIOeWAc/EGZKaKOLunEGf3FALIRR0/JZp00KBpBzU8GvGOYUQVHYtYIiKqEtRaAT5BEtr1sIcgCEg+b8TZvYVI2Fvwzxxa0zza7f/Lg3MtBZqEqtG0gxr1Oe2AqEJiEUtERFWOIAio3ViF2o1V6DrSDlk3RSTsK0DC3kJc+KMQmaki/linxx/r9KZpB23VaNpBg8ahajjV4NfYRBUBi1giIqrynGoq0KavDm366lCol3DpcKF5lDYzTcLZf262AIDTDogqCBaxREREd1FrBTQO1aBxqAbSa/a4cd6IhD2FSNhXdNqBi7tp2kGTDmrUb81pB0SPE4tYIiKi+xAEAZ6NVfBsrELX54tOO8hIEXHwJz0O/qSHSgPUb61G4/ZqNApRo0Zdpa3DJ6rUWMQSERGV0L3TDi4eLjSN0sab5tGe31+I8/sLgQVA9boKU0HbnqO0ROWBRSwREVEpqLUCmoRq0CRUA0mSkHLRaCpi4wtx5YQBt/8Ssf97PfZ/z1FaovLAIpaIiOgRCYIAD18VPHxV6DTUDvk5Ei4eMo3KntvPUVqi8sAiloiIqIzpHAT4d9HAv4tplDb1khHn4wtxjqO0RGWGRSwREVE5EgQB7g1UcG+gQkeO0hKVGRaxREREj9F9R2n3F+LK8eJHaRu2VcO3nQq16nNdWqI7WMQSERHZiFWjtACcagr/FLRq+LZVw7Ea7x5GVReLWCIiogqiuFHaxIOFSDxowOWjhci6KeHo5gIc3VwAAPBopETDdmo0bKdGvQAVpx5QlcIiloiIqAK6e5S2w2CgUC8h6U/DP0VtIZLPG82PPSvzodYC3oFqNGynQsN2ak49oEqPRSwREZEMqLUCfNuo4dtGjfBXgOzbIi78YbpzWOLBQmTdkpB4oBCJBwoB5MGphgDftqZRWt+2ajhW59QDqlxYxBIREcmQY3UFWoZr0TJcW2TqwZVjpqL22JYCHNtyz9SDtmrUa8GpByR/LGKJiIhkztqpByoN4NNKDd8gFRq0UcOjkRIKBYtakhcWsURERJVMsVMPDhXiwsHipx7YOQuo31oF3zZqNAhSo4aXgvNpqcJjEUtERFTJOVZXoGV3LVp2t5x6cPGwadWDvEwJp3cW4vRO01JezrUU8A1SoX6QqRB2duN8Wqp4WMQSERFVIfdOPTAaJFw7Y8CFQwZcPFyIqycNyEwVLZbyqllPgQb/jNLWb62CvTOLWrI9FrFERERVmFIloF6AGvUC1Og60g4F+RKSTpgK2ouHCnE9wYibSSJuJulx8Ec9BAGo3ViJBkFqNGijgncLNTR2nHpAjx+LWCIiIjLT6ATzDRQAIC9TxKWjBlw8VIiLRwqRdlnE9QQjricYsWcVoFQBXs1V5qK2rr8KShWLWip/LGKJiIjovuycFea7iAFAZpqIi0dMo7QXDxuQkSLi8jEDLh8zYPuXgMYO8G6pRoPWKvi0VqN2IyWLWioXLGKJiIioxJzdFAgM1yLwn/Vpb/8l4uLhQlw4bMClw4XIzZBwfn8hzu83rXygdRDg3VKF+q1UqN9KjdqNlVAoWdTSo2MRS0RERKUiCAJqeClRw0uJtpGAKEpISTTi0hEDLh0txOVjBuRnSzi3rxDn9v1b1PoEmopan1amkVoWtVQaLGKJiIioTCgUAmo3VqF2YxVCB+sgGiUkJxpx6WghLh0x4MpxU1GbsLcQCXtNRa3O8Z+R2tamkVqPhixqqWRYxBIREVG5UCgFeDZRwbOJaTkv0SjhxnkjLh8txKWjBvNIbXFFbYPWavi0VsHDl0UtFY9FLBERET0WCqWAOk1VqNNUhQ5D/ilqz/0zUnvUgCvHCu8pagGdkwCflirUb62Gd6ACCicbvwmqMCrEasWLFy+Gj48PdDodgoODcfDgwQf2X7t2LZo2bQqdToeAgABs2rTJ4vURI0ZAEASLR0REhEWf27dvY+jQoXB2doarqytGjRqF7OzsMn9vREREVDyFUkAdPxU6PmOH5z5wwrTN1fDi/5wR/oodGoeoobUH8rMknN1TiM2f5CL2+Wx8OUKNlW9kY8/KPFw9ZYDRINn6bZCN2Hwkds2aNYiOjkZsbCyCg4OxYMEChIeHIyEhAbVq1SrSf9++fRgyZAhiYmLQu3dvrFq1CpGRkThy5AiaN29u7hcREYFly5aZn2u1Wov9DB06FDdu3MDWrVtRWFiIkSNHYsyYMVi1alX5vVkiIiK6L6VKQF0/Fer6qdBxqOluYuaR2iMGXDleCH2OgHP7DDi3zwAgD2odUK+5Ct6BavgEmtapVWs5/aAqECRJsumfMMHBwWjbti0WLVoEABBFEV5eXhg/fjymTp1apH9UVBRycnKwYcMGc1v79u0RGBiI2NhYAKaR2PT0dKxbt67YY545cwb+/v74448/0KZNGwDAli1b0LNnT/z111/w9PR8aNyZmZlwcXFBRkYGnJ2drX3bVhFFEampqahVqxYUigoxeE5WYg7ljzmUP+ZQ/goLjDhz8CYyk5xw5YQRV44bkJdpWcYo1UBdPxW8A1XwCVShXnM1tA4saiuKe8/DR6mnbDoSW1BQgMOHD2PatGnmNoVCgbCwMMTHxxe7TXx8PKKjoy3awsPDixSsO3fuRK1atVCtWjU8+eSTmDdvHmrUqGHeh6urq7mABYCwsDAoFAocOHAA/fv3L3JcvV4PvV5vfp6ZmQnAlAxRFK1741YSRRGSJJX7caj8MIfyxxzKH3Mof4JCgpuvCP/2GoQOVkAUJaRdFnHluAFXjplWP8i6JeHKCQOunDBg99eAoABqN1LCu6UK3i2VqNdCBQdX/hFjK/eeh49yPtq0iL158yaMRiPc3d0t2t3d3XH27Nlit0lOTi62f3Jysvl5REQEBgwYgPr16+PChQuYPn06evTogfj4eCiVSiQnJxeZqqBSqVC9enWL/dwtJiYGs2fPLtKelpaG/Pz8Er3f0hJFERkZGZAkiaMHMsUcyh9zKH/MofwVl0PBEfDpYHpIEpCRDFw/rcCN0wKun1YgM1Uw3yY3/jvTfqp7ifD0l+DpL6G2nwjHGjZ8U1XMvTnMysoq9b5sPie2PAwePNj874CAALRo0QK+vr7YuXMnunXrVqp9Tps2zWIEODMzE15eXnBzc3ss0wkEQYCbmxt/8coUcyh/zKH8MYfyV5IcursDjVv++zwjVUTSCdNyXleOG5B2WcTtqwrcvgqc/NXUp3odBeq1+GekNkCFGl4KCAKnIJSHe3Oo0+lKvS+bFrE1a9aEUqlESkqKRXtKSgo8PDyK3cbDw8Oq/gDQoEED1KxZE4mJiejWrRs8PDyQmppq0cdgMOD27dv33Y9Wqy1ycRhgmv7wOH4ZCoLw2I5F5YM5lD/mUP6YQ/mzNofVPBSo5qFCy+6m5zl/i7hywoDLxwpx5bgBN84bcfuaiNvXCnBss6mPg6tgKmpbqFCvhelWuSo1i9qycncOH+VctGkRq9FoEBQUhLi4OERGRgIwVehxcXEYN25csduEhIQgLi4OkyZNMrdt3boVISEh9z3OX3/9hVu3bqF27drmfaSnp+Pw4cMICgoCAGzfvh2iKCI4OLhs3hwRERFVOA7VFPDvooF/Fw0AID9bRNKfppHapD8NuHbGgJx0CWd2F+LMbtMNGNRaoK6/ylzYejVXQefIP4RszebTCaKjozF8+HC0adMG7dq1w4IFC5CTk4ORI0cCAIYNG4Y6deogJiYGADBx4kR06dIF8+fPR69evbB69WocOnQIS5YsAQBkZ2dj9uzZGDhwIDw8PHDhwgW8/vrraNiwIcLDwwEAfn5+iIiIwOjRoxEbG4vCwkKMGzcOgwcPLtHKBERERFQ56BwVaByiQeMQU1FrKJBwPcF0YVjSPxeI5WVKuHTUgEtHDQAAQQDcfZX/jNSaClsXd6Ut30aVZPMiNioqCmlpaZgxYwaSk5MRGBiILVu2mC/eSkpKshhqDg0NxapVq/DWW29h+vTpaNSoEdatW2deI1apVOLEiRP46quvkJ6eDk9PT3Tv3h1z5861mA6wcuVKjBs3Dt26dYNCocDAgQPxySefPN43T0RERBWKSiOgXoAa9QLUwFBAFCXcTBKRdMI0/SDpTwNuXxORnGhEcqIRB340rVzk4q6AdwsVvFuqUC9AhVr1ebvc8mbzdWLliuvEkjWYQ/ljDuWPOZS/ipLDrJsirvxpQNLxQlw5YUByohGi0bKPzlGAV3OVebS2jp8KGh2L2kqzTiwRERGR3DjVVKB5Vw2adzVNQdDnSvjr9D9TEI4X4uopA/KzJZzfX4jz+wsBAAqlab1arwAV6jU3jdZyCsKjYRFLRERE9Ai09gJ826jh20YNwA5Gg4SUC0bTTReOFyLpTwOybkq4dtaIa2eN2L/WNAXBuZYC9ZqbLhSrF6CCRyOugmANFrFEREREZUipEuDZRAXPJiqE/J8OkiQhI0VE0kkDrv5pmlebnGhEZqqIk9sLcHJ7AQBApQHq+JkKWq/mphFbh2qc+nI/LGKJiIiIypEgCHD1UMLVQ4kWYaaLzAvyJFw7Yypok04acPWkaRWEK8dNN2W4o4bXP6O1Aabi1s1HCYWCo7UAi1giIiKix05jJ6B+azXqt1YDMK2CcOuqiKsn/yls/zQg7bIRt66KuHW1AEc3m0ZrtQ4CvJop4RWgRr3mKtT1V1bZNWtZxBIRERHZmEIhwM1bCTdvJVr3Mo3W5mWKuHrKVNBePWnAX6cN0OdISDxoQOLBf9esdfNRwquZCnWbKeHVvOqM1rKIJSIiIqqA7Jwtb8RgNEhIuWg0zav9Z8Q2/YaI1EtGpF4y4vAG03ZaBwF1/ZSo28w0t9armQr2LpVvtJZFLBEREZEMKFUCPBur4NlYheCBprbs26bR2qsnDfjrlAF/nTGN1l44ZMCFQ5Zza+s2MxW0Xs1UcPdVQqmS92gti1giIiIimXKsroBfJw38Ov07Wpt6yWguaq+eMuBmkmieW3t8i2lurVoH1GmqsihsnWrKa7SWRSwRERFRJaFUCajdSIXajVRo19/Ulpsp4tpp0xSEv04Z8NdpI/KzJVw+ZsDlY/+O1rp6WI7W1m6shEpTcUdrWcQSERERVWL2zgo0aq9Bo/am0VpRlHAzSTSN1J40jdamXjQiPVlEenIBTsaZRmv7T3cwX2RWEbGIJSIiIqpCFAoBtXyUqOXz70oI+hwJ187+W9RePWWAV/OKXSZW7OiIiIiIqNxpHQQ0CFKjQZBp3VpJkmwc0cOxiCUiIiIiC4JQcefC3iGvy9CIiIiIiMAiloiIiIhkiEUsEREREckOi1giIiIikh0WsUREREQkOyxiiYiIiEh2WMQSERERkeywiCUiIiIi2WERS0RERESywzt2ldKd27FlZmaW+7FEUURWVhZ0Oh0UCv7dIUfMofwxh/LHHMofcyh/9+bwTh1VmtvcsogtpaysLACAl5eXjSMhIiIikresrCy4uLhYtY0glab0JYiiiOvXr8PJyanc7y+cmZkJLy8vXL16Fc7OzuV6LCofzKH8MYfyxxzKH3Mof/fmUJIkZGVlwdPT0+rRdY7ElpJCoUDdunUf6zGdnZ150soccyh/zKH8MYfyxxzK3905tHYE9g5OKCEiIiIi2WERS0RERESywyJWBrRaLWbOnAmtVmvrUKiUmEP5Yw7ljzmUP+ZQ/soyh7ywi4iIiIhkhyOxRERERCQ7LGKJiIiISHZYxBIRERGR7LCIreAWL14MHx8f6HQ6BAcH4+DBg7YOiawwa9YsCIJg8WjatKmtw6IH2L17N/r06QNPT08IgoB169ZZvC5JEmbMmIHatWvDzs4OYWFhOH/+vG2CpWI9LIcjRowocl5GRETYJlgqIiYmBm3btoWTkxNq1aqFyMhIJCQkWPTJz8/H2LFjUaNGDTg6OmLgwIFISUmxUcR0r5Lk8IknnihyHr700ktWHYdFbAW2Zs0aREdHY+bMmThy5AhatmyJ8PBwpKam2jo0skKzZs1w48YN82PPnj22DokeICcnBy1btsTixYuLff3999/HJ598gtjYWBw4cAAODg4IDw9Hfn7+Y46U7udhOQSAiIgIi/Py22+/fYwR0oPs2rULY8eOxf79+7F161YUFhaie/fuyMnJMfeZPHkyfvnlF6xduxa7du3C9evXMWDAABtGTXcrSQ4BYPTo0Rbn4fvvv2/dgSSqsNq1ayeNHTvW/NxoNEqenp5STEyMDaMia8ycOVNq2bKlrcOgUgIg/fTTT+bnoihKHh4e0gcffGBuS09Pl7RarfTtt9/aIEJ6mHtzKEmSNHz4cKlfv342iYesl5qaKgGQdu3aJUmS6ZxTq9XS2rVrzX3OnDkjAZDi4+NtFSY9wL05lCRJ6tKlizRx4sRH2i9HYiuogoICHD58GGFhYeY2hUKBsLAwxMfH2zAystb58+fh6emJBg0aYOjQoUhKSrJ1SFRKly5dQnJyssV56eLiguDgYJ6XMrNz507UqlULTZo0wcsvv4xbt27ZOiS6j4yMDABA9erVAQCHDx9GYWGhxXnYtGlT1KtXj+dhBXVvDu9YuXIlatasiebNm2PatGnIzc21ar+qMouQytTNmzdhNBrh7u5u0e7u7o6zZ8/aKCqyVnBwMJYvX44mTZrgxo0bmD17Njp16oSTJ0/CycnJ1uGRlZKTkwGg2PPyzmtU8UVERGDAgAGoX78+Lly4gOnTp6NHjx6Ij4+HUqm0dXh0F1EUMWnSJHTo0AHNmzcHYDoPNRoNXF1dLfryPKyYisshADzzzDPw9vaGp6cnTpw4gTfeeAMJCQn48ccfS7xvFrFE5ahHjx7mf7do0QLBwcHw9vbGd999h1GjRtkwMqKqa/DgweZ/BwQEoEWLFvD19cXOnTvRrVs3G0ZG9xo7dixOnjzJawlk7H45HDNmjPnfAQEBqF27Nrp164YLFy7A19e3RPvmdIIKqmbNmlAqlUWutkxJSYGHh4eNoqJH5erqisaNGyMxMdHWoVAp3Dn3eF5WLg0aNEDNmjV5XlYw48aNw4YNG7Bjxw7UrVvX3O7h4YGCggKkp6db9Od5WPHcL4fFCQ4OBgCrzkMWsRWURqNBUFAQ4uLizG2iKCIuLg4hISE2jIweRXZ2Ni5cuIDatWvbOhQqhfr168PDw8PivMzMzMSBAwd4XsrYX3/9hVu3bvG8rCAkScK4cePw008/Yfv27ahfv77F60FBQVCr1RbnYUJCApKSkngeVhAPy2Fxjh07BgBWnYecTlCBRUdHY/jw4WjTpg3atWuHBQsWICcnByNHjrR1aFRCr732Gvr06QNvb29cv34dM2fOhFKpxJAhQ2wdGt1Hdna2xUjApUuXcOzYMVSvXh316tXDpEmTMG/ePDRq1Aj169fH22+/DU9PT0RGRtouaLLwoBxWr14ds2fPxsCBA+Hh4YELFy7g9ddfR8OGDREeHm7DqOmOsWPHYtWqVVi/fj2cnJzM81xdXFxgZ2cHFxcXjBo1CtHR0ahevTqcnZ0xfvx4hISEoH379jaOnoCH5/DChQtYtWoVevbsiRo1auDEiROYPHkyOnfujBYtWpT8QI+0tgGVu4ULF0r16tWTNBqN1K5dO2n//v22DomsEBUVJdWuXVvSaDRSnTp1pKioKCkxMdHWYdED7NixQwJQ5DF8+HBJkkzLbL399tuSu7u7pNVqpW7dukkJCQm2DZosPCiHubm5Uvfu3SU3NzdJrVZL3t7e0ujRo6Xk5GRbh03/KC53AKRly5aZ++Tl5UmvvPKKVK1aNcne3l7q37+/dOPGDdsFTRYelsOkpCSpc+fOUvXq1SWtVis1bNhQmjJlipSRkWHVcYR/DkZEREREJBucE0tEREREssMiloiIiIhkh0UsEREREckOi1giIiIikh0WsUREREQkOyxiiYiIiEh2WMQSERERkeywiCUiIiIi2WERS0T0mPj4+GDBggUl7r9z504IgoD09PRyi6kisfbzIaKqjUUsEdE9BEF44GPWrFml2u8ff/yBMWPGlLh/aGgobty4ARcXl1Idj4ioMlPZOgAioormxo0b5n+vWbMGM2bMQEJCgrnN0dHR/G9JkmA0GqFSPfzXqZubm1VxaDQaeHh4WLUNEVFVwZFYIqJ7eHh4mB8uLi4QBMH8/OzZs3BycsLmzZsRFBQErVaLPXv24MKFC+jXrx/c3d3h6OiItm3bYtu2bRb7vffrckEQ8L///Q/9+/eHvb09GjVqhJ9//tn8+r3TCZYvXw5XV1f8+uuv8PPzg6OjIyIiIiyKboPBgAkTJsDV1RU1atTAG2+8geHDhyMyMvKB73nPnj3o1KkT7Ozs4OXlhQkTJiAnJ8ci9rlz52LIkCFwcHBAnTp1sHjxYot9JCUloV+/fnB0dISzszOefvpppKSkWPT55Zdf0LZtW+h0OtSsWRP9+/e3eD03NxfPP/88nJycUK9ePSxZsuSBcRNR1cUiloioFKZOnYr33nsPZ86cQYsWLZCdnY2ePXsiLi4OR48eRUREBPr06YOkpKQH7mf27Nl4+umnceLECfTs2RNDhw7F7du379s/NzcXH374IVasWIHdu3cjKSkJr732mvn1//znP1i5ciWWLVuGvXv3IjMzE+vWrXtgDBcuXEBERAQGDhyIEydOYM2aNdizZw/GjRtn0e+DDz5Ay5YtcfToUUydOhUTJ07E1q1bAQCiKKJfv364ffs2du3aha1bt+LixYuIiooyb79x40b0798fPXv2xNGjRxEXF4d27dpZHGP+/Plo06YNjh49ildeeQUvv/yyxSg4EZGZRERE97Vs2TLJxcXF/HzHjh0SAGndunUP3bZZs2bSwoULzc+9vb2ljz/+2PwcgPTWW2+Zn2dnZ0sApM2bN1sc6++//zbHAkBKTEw0b7N48WLJ3d3d/Nzd3V364IMPzM8NBoNUr149qV+/fveNc9SoUdKYMWMs2n7//XdJoVBIeXl55tgjIiIs+kRFRUk9evSQJEmSfvvtN0mpVEpJSUnm10+dOiUBkA4ePChJkiSFhIRIQ4cOvW8c3t7e0rPPPmt+LoqiVKtWLemzzz677zZEVHVxJJaIqBTatGlj8Tw7OxuvvfYa/Pz84OrqCkdHR5w5c+ahI7EtWrQw/9vBwQHOzs5ITU29b397e3v4+vqan9euXdvcPyMjAykpKRajm0qlEkFBQQ+M4fjx41i+fDkcHR3Nj/DwcIiiiEuXLpn7hYSEWGwXEhKCM2fOAADOnDkDLy8veHl5mV/39/eHq6uruc+xY8fQrVu3B8Zy9+dxZxrHgz4PIqq6eGEXEVEpODg4WDx/7bXXsHXrVnz44Ydo2LAh7OzsMGjQIBQUFDxwP2q12uK5IAgQRdGq/pIkWRm9pezsbLz44ouYMGFCkdfq1av3SPu+m52d3UP7WPt5EFHVxZFYIqIysHfvXowYMQL9+/dHQEAAPDw8cPny5ccag4uLC9zd3fHHH3+Y24xGI44cOfLA7Vq3bo3Tp0+jYcOGRR4ajcbcb//+/Rbb7d+/H35+fgAAPz8/XL16FVevXjW/fvr0aaSnp8Pf3x+AaZQ1Li7ukd8nERHAkVgiojLRqFEj/Pjjj+jTpw8EQcDbb79tkxHE8ePHIyYmBg0bNkTTpk2xcOFC/P333xAE4b7bvPHGG2jfvj3GjRuHF154AQ4ODjh9+jS2bt2KRYsWmfvt3bsX77//PiIjI7F161asXbsWGzduBACEhYUhICAAQ4cOxYIFC2AwGPDKK6+gS5cu5qkXM2fORLdu3eDr64vBgwfDYDBg06ZNeOONN8r3QyGiSokjsUREZeCjjz5CtWrVEBoaij59+iA8PBytW7d+7HG88cYbGDJkCIYNG4aQkBDz/FadTnffbVq0aIFdu3bh3Llz6NSpE1q1aoUZM2bA09PTot+rr76KQ4cOoVWrVpg3bx4++ugjhIeHAzB97b9+/XpUq1YNnTt3RlhYGBo0aIA1a9aYt3/iiSewdu1a/PzzzwgMDMSTTz6JgwcPls8HQUSVniA96mQqIiKqsERRhJ+fH55++mnMnTu31Pvx8fHBpEmTMGnSpLILjojoEXA6ARFRJXLlyhX89ttv6NKlC/R6PRYtWoRLly7hmWeesXVoRERlitMJiIgqEYVCgeXLl6Nt27bo0KED/vzzT2zbts18ARYRUWXB6QREREREJDsciSUiIiIi2WERS0RERESywyKWiIiIiGSHRSwRERERyQ6LWCIiIiKSHRaxRERERCQ7LGKJiIiISHZYxBIRERGR7LCIJSIiIiLZ+X8oj5POkHEilgAAAABJRU5ErkJggg==", "text/plain": [ "
" ] @@ -175,7 +174,7 @@ "\n", "def evaluate():\n", " reset_sequence()\n", - " predictions = brainstate.transform.for_loop(learner, inputs)\n", + " predictions = learner.etrace_evolve(inputs, return_outputs=True)\n", " return jnp.mean((predictions - targets) ** 2)\n", "\n", "\n", @@ -186,24 +185,13 @@ "\n", "def train_epoch(_):\n", " reset_sequence()\n", - "\n", - " def scan_step(accumulated_grads, sample):\n", - " x, target = sample\n", - " step_grads, step_loss = brainstate.transform.grad(\n", - " local_loss, weights, return_value=True\n", - " )(x, target)\n", - " accumulated_grads = jax.tree.map(\n", - " lambda total, current: total + current,\n", - " accumulated_grads,\n", - " step_grads,\n", - " )\n", - " return accumulated_grads, step_loss\n", - "\n", - " zero_grads = jax.tree.map(jnp.zeros_like, weights.to_dict_values())\n", - " grads, step_losses = brainstate.transform.scan(\n", - " scan_step, zero_grads, (inputs, targets)\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", - " grads = jax.tree.map(lambda grad: grad / inputs.shape[0], grads)\n", " optimizer.update(grads)\n", " return step_losses.mean()\n", "\n", @@ -279,7 +267,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.11.8" + "version": "3.13.11" } }, "nbformat": 4, diff --git a/examples/003-snn-memory-and-speed-evaluation-all.py b/examples/003-snn-memory-and-speed-evaluation-all.py index 872ff46..171cb2d 100644 --- a/examples/003-snn-memory-and-speed-evaluation-all.py +++ b/examples/003-snn-memory-and-speed-evaluation-all.py @@ -352,8 +352,16 @@ def _step(i, inp): return losses.mean(), acc def _compile_etrace_function(self, input_info): - # kept manual: uses vmap_init_all_states with state_tag='new' and Batching() mode; - # braintrace.compile uses init_all_states which is incompatible with this vmap state scheme + # kept manual: braintrace.compile has no path for this state scheme. + # It offers two: init_all_states(batch_size=B) (vmap=False), or + # vmap_new_states(state_tag='new') + compile_graph on an *unbatched* + # sample + an ETraceVmap wrapper (vmap=True). This benchmark uses a + # third -- vmap_init_all_states(state_tag='new') for the per-sample + # states, compile_graph on the *batched* example, no wrapper, and an + # explicit brainstate.transform.vmap(in_states=...) only for the reset. + # compile's vmap branch would also reject `input_info`: it strips the + # batch axis with `a[0]`, and a jax.ShapeDtypeStruct is not + # subscriptable. if self.args.method == 'expsm_diag': model = braintrace.ES_D_RTRL(self.target, self.args.etrace_decay) elif self.args.method == 'diag': @@ -416,6 +424,12 @@ def etrace_train(self, inputs, targets): inputs = np.reshape(inputs, (inputs.shape[0], inputs.shape[1], -1)) # [n_steps, n_samples, n_in] self._etrace_reset_fun() + # Kept manual on purpose -- this is a memory/speed benchmark. A single + # ``learner.etrace_grad(...)`` would fuse the whole sequence into one + # scan, which is what an application should do but leaves nowhere to + # sample ``get_mem_usage()`` between steps. The Python loop over a + # jitted step is the measurement, not an un-migrated leftover. + # # initial gradients -- a pytree of zeros matching the grad_states pytree # used in ``_etrace_step`` (``opt.param_states.to_pytree()``), so the # per-step ``jax.tree.map(a + b, ...)`` accumulation aligns. diff --git a/examples/003-snn-memory-and-speed-evaluation-batched.py b/examples/003-snn-memory-and-speed-evaluation-batched.py index 97818b3..fb23afc 100644 --- a/examples/003-snn-memory-and-speed-evaluation-batched.py +++ b/examples/003-snn-memory-and-speed-evaluation-batched.py @@ -476,8 +476,16 @@ def _step(i, inp): return losses.mean(), acc def _compile_etrace_function(self, input_info): - # kept manual: uses vmap_init_all_states with state_tag='new' and Batching() mode; - # braintrace.compile uses init_all_states which is incompatible with this vmap state scheme + # kept manual: braintrace.compile has no path for this state scheme. + # It offers two: init_all_states(batch_size=B) (vmap=False), or + # vmap_new_states(state_tag='new') + compile_graph on an *unbatched* + # sample + an ETraceVmap wrapper (vmap=True). This benchmark uses a + # third -- vmap_init_all_states(state_tag='new') for the per-sample + # states, compile_graph on the *batched* example, no wrapper, and an + # explicit brainstate.transform.vmap(in_states=...) only for the reset. + # compile's vmap branch would also reject `input_info`: it strips the + # batch axis with `a[0]`, and a jax.ShapeDtypeStruct is not + # subscriptable. if self.args.method == 'expsm_diag': model = braintrace.ES_D_RTRL(self.target, self.args.etrace_decay) elif self.args.method == 'diag': @@ -526,6 +534,12 @@ def etrace_train(self, inputs, targets): inputs = np.reshape(inputs, (inputs.shape[0], inputs.shape[1], -1)) # [n_steps, n_samples, n_in] self._etrace_reset_fun() + # Kept manual on purpose -- this is a memory/speed benchmark. A single + # ``learner.etrace_grad(...)`` would fuse the whole sequence into one + # scan, which is what an application should do but leaves nowhere to + # sample ``get_mem_usage()`` between steps. The Python loop over a + # jitted step is the measurement, not an un-migrated leftover. + # # initial gradients grads = jax.tree.map(lambda a: jnp.zeros_like(a), self.opt.param_states.to_pytree_value()) diff --git a/examples/003-snn-memory-and-speed-evaluation-vmap.py b/examples/003-snn-memory-and-speed-evaluation-vmap.py index 62cc69f..4bbf370 100644 --- a/examples/003-snn-memory-and-speed-evaluation-vmap.py +++ b/examples/003-snn-memory-and-speed-evaluation-vmap.py @@ -458,8 +458,12 @@ def _step(i, inp): return losses.mean(), acc def _compile_etrace_function(self, input_info): - # kept manual: data-dependent (DVSGesture) — no smoke coverage to verify a - # compile() migration; uses ShapeDtypeStruct example incompatible with compile's vmap axis-strip + # kept manual: this *is* compile(..., vmap=True)'s scheme -- + # vmap_new_states(state_tag='new') + init_all_states + compile_graph on + # the unbatched sample + a Vmap wrapper -- but compile cannot take this + # example input. It strips the batch axis with `a[0]`, and `input_info` + # is an unbatched jax.ShapeDtypeStruct, which is not subscriptable. + # (A benchmark builds the graph from a shape, never from real data.) if self.args.method == 'expsm_diag': model = braintrace.ES_D_RTRL(self.target, self.args.etrace_decay, ) elif self.args.method == 'diag': @@ -515,18 +519,18 @@ def etrace_train(self, inputs, targets): inputs = np.reshape(inputs, (inputs.shape[0], inputs.shape[1], -1)) # [n_steps, n_samples, n_in] self._etrace_reset_fun() + # Kept manual on purpose -- this is a memory/speed benchmark. A single + # ``learner.etrace_grad(...)`` would fuse the whole sequence into one + # scan, which is what an application should do but leaves nowhere to + # sample ``get_mem_usage()`` between steps. The Python loop over a + # jitted step is the measurement, not an un-migrated leftover. + # # initial gradients grads = jax.tree.map(lambda a: jnp.zeros_like(a), self.param_weights.to_dict_values()) # training indices = np.arange(inputs.shape[0]) n_sim = _format_sim_epoch(self.args.warmup_ratio, inputs.shape[0]) - # brainstate.transform.for_loop(self._etrace_pred_fun, indices[:n_sim], inputs[:n_sim]) - # grads, (outs, losses) = brainstate.transform.scan( - # functools.partial(self._etrace_train_fun, targets=targets), - # grads, - # (indices[n_sim:], inputs[n_sim:]) - # ) outs, losses = [], [] for i in indices: if i < n_sim: diff --git a/examples/004-feedforward-conv-snn.py b/examples/004-feedforward-conv-snn.py index b9c3289..4dcf684 100644 --- a/examples/004-feedforward-conv-snn.py +++ b/examples/004-feedforward-conv-snn.py @@ -246,26 +246,25 @@ def batch_train(self, inputs, targets): # inputs: [n_step, n_batch, ...] # targets: [n_batch, n_out] - # kept manual: uses vmap_states='new' — cannot replace with braintrace.compile - # model = braintrace.ES_D_RTRL(self.target, self.decay_or_rank) - model = braintrace.D_RTRL(self.target) - - @brainstate.transform.vmap_new_states( - state_tag='new', - axis_size=inputs.shape[1], - ) - def init(): - brainstate.nn.init_all_states(self.target) - # initialize the online learning model - with brainstate.environ.context(fit=True): - model.compile_graph(inputs[0, 0]) - - init() - # show_graph() is a post-compile diagnostic: call it once *after* init(). - # The vmap_new_states discovery probe runs init() with compilation deferred - # to the real mapped pass, so the graph is only available after init(). - model.show_graph() - model = brainstate.nn.Vmap(model, vmap_states='new') + # One call replaces init_all_states + compile_graph + Vmap. Pass the + # batched single step inputs[0]; compile strips axis 0 to recover the + # per-sample example, so this is the same graph the manual expansion in + # examples/drtrl/02-batching-vmap.py builds by hand. + # model = braintrace.compile(self.target, braintrace.ES_D_RTRL, inputs[0], + # batch_size=inputs.shape[1], vmap=True, + # decay_or_rank=self.decay_or_rank) + with brainstate.environ.context(fit=True): + model = braintrace.compile( + self.target, braintrace.D_RTRL, inputs[0], + batch_size=inputs.shape[1], vmap=True, + ) + + # show_graph() is a post-compile diagnostic and lives on the learner, not + # on the vmap wrapper -- ETraceVmap forwards the drivers, not the + # introspection surface. Reading through .module is fine here; only + # *driving* through it would be wrong (it would drive the unbatched + # learner and give per-lane-wrong results). + model.module.show_graph() def _etrace_grad(inp): with brainstate.environ.context(fit=True): @@ -298,15 +297,18 @@ def batch_train(self, inputs, targets): # inputs: [n_step, n_batch, ...] # targets: [n_batch, n_out] - # kept manual: re-initializes states inside @jit every batch; braintrace.compile must live outside jit - # model = braintrace.ES_D_RTRL(self.target, self.decay_or_rank, model=brainstate.mixin.Batching()) - model = braintrace.D_RTRL(self.target, self.decay_or_rank, model=brainstate.mixin.Batching()) - - # initialize the online learning model - brainstate.nn.init_all_states(self.target, batch_size=inputs.shape[1]) + # Same call as OnlineVmapTrainer above, minus vmap=True: the model sees + # the batch axis itself, so compile only has to init the states with + # batch_size and build the graph on the batched example inputs[0]. + # model = braintrace.compile(self.target, braintrace.ES_D_RTRL, inputs[0], + # batch_size=inputs.shape[1], + # decay_or_rank=self.decay_or_rank) with brainstate.environ.context(fit=True): - model.compile_graph(inputs[0]) - model.show_graph() + model = braintrace.compile( + self.target, braintrace.D_RTRL, inputs[0], + batch_size=inputs.shape[1], + ) + model.show_graph() def _etrace_grad(inp): with brainstate.environ.context(fit=True): diff --git a/examples/100-gru-on-copying-task.py b/examples/100-gru-on-copying-task.py index cf4add5..7cd3f5b 100644 --- a/examples/100-gru-on-copying-task.py +++ b/examples/100-gru-on-copying-task.py @@ -125,11 +125,10 @@ def batch_train(self, inputs, target): vjp_method=self.vjp_method) elif self.batch_train_method == 'batch': - # kept manual: re-initializes states inside @jit every batch; braintrace.compile must live outside jit - model = braintrace.ParamDimVjpAlgorithm( - self.target, vjp_method=self.vjp_method) - brainstate.nn.init_all_states(self.target, batch_size=inputs.shape[1]) - model.compile_graph(inputs[0]) + # 同一个调用,只是没有 vmap:模型自己看到 batch 维度 + model = braintrace.compile(self.target, braintrace.ParamDimVjpAlgorithm, inputs[0], + batch_size=inputs.shape[1], + vjp_method=self.vjp_method) else: raise ValueError diff --git a/examples/drtrl/02-batching-vmap.py b/examples/drtrl/02-batching-vmap.py index fed4c48..2c8c7ab 100644 --- a/examples/drtrl/02-batching-vmap.py +++ b/examples/drtrl/02-batching-vmap.py @@ -1,11 +1,21 @@ # Copyright 2026 BrainX Ecosystem Limited. Licensed under the Apache License, 2.0. -# kept manual: vmap_states='new' path not yet covered by compile() +# kept manual: this file *is* the worked expansion of compile(..., vmap=True) """02 · Batching via ``vmap_new_states``. Shows the per-sample-init pattern explicitly: 1. wrap model in D_RTRL 2. inside a vmapped new-states scope: init_all_states + compile_graph - 3. outside, wrap the online model in brainstate.nn.Vmap + 3. outside, wrap the online model in braintrace.ETraceVmap + +``braintrace.compile(model, braintrace.D_RTRL, inputs[0], batch_size=B, +vmap=True)`` does exactly these three steps in one call, and that is what an +application should write. The steps are spelled out here so the wiring is +visible — which state gets the per-sample axis, and on which *unbatched* +sample the eligibility-trace graph is built. + +Step 3 uses ``braintrace.ETraceVmap`` rather than ``brainstate.nn.Vmap``: it +*is* a ``brainstate.nn.Vmap`` (same call, same isinstance checks) and adds the +sequence drivers, which a bare ``Vmap`` does not carry. Pick this pattern when every sample needs its own eligibility trace state (the usual case). @@ -53,7 +63,8 @@ def init(): online_model.compile_graph(inputs[0, 0]) init() - vmap_model = brainstate.nn.Vmap(online_model, vmap_states='new') + # ETraceVmap, not brainstate.nn.Vmap: same wrapper, plus the drivers. + vmap_model = braintrace.ETraceVmap(online_model, vmap_states='new') def step_loss(inp, tar): out = vmap_model(inp) diff --git a/examples/drtrl/08-operator-conv.py b/examples/drtrl/08-operator-conv.py index 24ff9d3..5ec9061 100644 --- a/examples/drtrl/08-operator-conv.py +++ b/examples/drtrl/08-operator-conv.py @@ -66,7 +66,10 @@ def main(*, n_epochs: int = 30, batch_size: int = 16, plot: bool = True) -> dict @brainstate.transform.jit def f_train(inputs, targets): - brainstate.transform.for_loop(lambda inp: online(inp), inputs[:-1]) + # Free-run the prefix: hidden states and the eligibility trace advance, + # no loss is computed. The loss here is at the final step only, so the + # gradient below stays a single-step grad rather than an etrace_grad. + online.etrace_evolve(inputs[:-1]) def final_loss(): out = online(inputs[-1]) diff --git a/examples/drtrl/09-classification-mnist.py b/examples/drtrl/09-classification-mnist.py index 7cb9ef5..e0df9b2 100644 --- a/examples/drtrl/09-classification-mnist.py +++ b/examples/drtrl/09-classification-mnist.py @@ -72,7 +72,10 @@ def main(*, n_epochs: int = 1, batch_size: int = 64, max_batches: int | None = 1 @brainstate.transform.jit def online_step(inputs, targets): - brainstate.transform.for_loop(lambda inp: om(inp), inputs[:-1]) + # Free-run the prefix: hidden states and the eligibility trace advance, + # no loss is computed. The loss here is at the final step only, so the + # gradient below stays a single-step grad rather than an etrace_grad. + om.etrace_evolve(inputs[:-1]) def final_loss(): out = om(inputs[-1]) diff --git a/examples/pp_prop/05-batching-vmap.py b/examples/pp_prop/05-batching-vmap.py index 7e19c77..ad91bf3 100644 --- a/examples/pp_prop/05-batching-vmap.py +++ b/examples/pp_prop/05-batching-vmap.py @@ -1,11 +1,16 @@ # Copyright 2026 BrainX Ecosystem Limited. Licensed under the Apache License, 2.0. -# kept manual: vmap_states='new' path not yet covered by compile() -"""05 · Batching via brainstate.nn.Vmap(vmap_states='new'). +"""05 · Batching via ``braintrace.compile(..., vmap=True)``. -The network and the pp_prop algorithm are defined unbatched, then replicated -across the batch dimension via vmap_new_states. pp_prop's per-rule init is -aware of batching and allocates batched eligibility traces automatically. -This is the default batching path used by examples 01-04. +The network and the pp_prop algorithm are defined unbatched; ``compile`` with +``vmap=True`` replicates them across the batch dimension (it initializes the +states inside a ``vmap_new_states`` scope, builds the eligibility-trace graph +on one unbatched sample, and returns an ``ETraceVmap``). pp_prop's per-rule +init is aware of batching and allocates batched eligibility traces +automatically. This is the default batching path used by examples 01-04, and +it lives in ``_shared.online_train_epoch``, which this file calls. + +For the same three steps written out by hand, see +``examples/drtrl/02-batching-vmap.py``. """ import pathlib