{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Delayed and non-stationary multi-armed bandit problems\n",
    "\n",
    "The traditional setup for multi-armed bandits is that the reward is given immediately after the action is taken. However, in many real-world applications, the reward is delayed. For example, in dynamic pricing, the reward is given after the customer makes the purchase, which can be days or weeks after the price is set. The problem becomes more complicated if the bandit is non-stationary, i.e., the reward distribution changes over time. In this notebook, we will show how to use `bayesianbandits` to approach this family of problems.\n",
    "\n",
    "## How can we implement a geographic pricing strategy?\n",
    "\n",
    "Suppose we are a company that sells a product in multiple cities. We want to maximize our profit by setting the price for each city. The demand for the product is different in each city, and the demand changes over time. We want to learn the demand distribution for each city and set the price accordingly. The reward is the profit, which is the price minus the cost. The cost is the same for all cities, so we can ignore it for now, and we'll make the simplifying assumption that supply is infinite.\n",
    "\n",
    "## Simulating the problem\n",
    "\n",
    "We will simulate the problem using the GeographicPricing class.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "np.random.seed(2)\n",
    "\n",
    "\n",
    "class GeographicPricing:\n",
    "    def __init__(self, num_locations: int):\n",
    "        # Randomly generate demand parameters for each location\n",
    "        self.demand_intercepts = np.random.uniform(low=50, high=100, size=num_locations)\n",
    "        self.demand_slopes = np.random.uniform(low=-2, high=-0.1, size=num_locations)\n",
    "\n",
    "        self.num_locations = num_locations\n",
    "\n",
    "    def demand(self, location: int, price: int) -> float:\n",
    "        # Linear demand function\n",
    "        return max(\n",
    "            self.demand_intercepts[location] + self.demand_slopes[location] * price, 0\n",
    "        )\n",
    "\n",
    "    def margin(self, location: int, price: int) -> float:\n",
    "        # Margin is price times demand, as we're assuming zero marginal cost\n",
    "        return price * self.demand(location, price)\n",
    "\n",
    "    def adjust_demand(self):\n",
    "        # Time-based step changes\n",
    "        if hasattr(self, \"step_counter\"):\n",
    "            self.step_counter += 1\n",
    "        else:\n",
    "            self.step_counter = 0\n",
    "\n",
    "        # Create step changes at fixed intervals\n",
    "        if self.step_counter % 20 == 0:\n",
    "            # Alternate between increasing and decreasing steps\n",
    "            direction = 1 if (self.step_counter // 20) % 2 == 0 else -1\n",
    "            step_size_intercept = direction * np.abs(\n",
    "                np.random.uniform(8, 20, size=self.num_locations)\n",
    "            )\n",
    "            step_size_slope = direction * np.abs(\n",
    "                np.random.uniform(0.1, 0.5, size=self.num_locations)\n",
    "            )\n",
    "\n",
    "            self.demand_intercepts += step_size_intercept\n",
    "            self.demand_slopes += step_size_slope\n",
    "\n",
    "        # Constant upward drift for all locations\n",
    "        drift_intercept = np.full(\n",
    "            self.num_locations, 0.05\n",
    "        )  # fixed small positive drift\n",
    "        drift_slope = np.full(self.num_locations, 0.001)  # fixed small positive drift\n",
    "\n",
    "        self.demand_intercepts += drift_intercept\n",
    "        self.demand_slopes += drift_slope\n",
    "\n",
    "        # Ensure demand parameters stay within reasonable bounds\n",
    "        self.demand_intercepts = np.clip(self.demand_intercepts, 20, 150)\n",
    "        self.demand_slopes = np.clip(self.demand_slopes, -3, -0.05)\n",
    "\n",
    "    def reset_demand(self):\n",
    "        # Reset demand parameters to original values\n",
    "        self.demand_intercepts = np.random.uniform(\n",
    "            low=50, high=100, size=self.num_locations\n",
    "        )\n",
    "        self.demand_slopes = np.random.uniform(\n",
    "            low=-2, high=-0.1, size=self.num_locations\n",
    "        )\n",
    "\n",
    "\n",
    "oracle = GeographicPricing(10)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We'll again use Thompson sampling as the bandit algorithm. We'll have a global intercept, as well as an intercept for each location. This, combined with the regularization behavior of the `NormalInverseGamma` regressor, will create a sort of \"poor man's hierarchical model\" where the intercepts for each location are pulled towards the global intercept. Let's say from historical data, we know that we make about 1000 dollars per market per day, so we'll set the prior for the mean of the global intercept to 1000, and all others to 0.\n",
    "\n",
    "First, we'll define our action space. To keep things single, we'll consider a discrete action space with 5 possible prices:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "from enum import Enum\n",
    "\n",
    "\n",
    "class Price(Enum):\n",
    "    price_5 = 5\n",
    "    price_8 = 8\n",
    "    price_11 = 11\n",
    "    price_14 = 14\n",
    "    price_17 = 17\n",
    "\n",
    "    def take_action(self, location: int) -> float:\n",
    "        return oracle.margin(location, self.value)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, we'll create our `ContextualAgent`.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "from bayesianbandits import (\n",
    "    Arm,\n",
    "    ContextualAgent,\n",
    "    NormalInverseGammaRegressor,\n",
    "    ThompsonSampling,\n",
    ")\n",
    "\n",
    "est = NormalInverseGammaRegressor(mu=np.array([1000] + [0] * 10))\n",
    "policy = ThompsonSampling()\n",
    "\n",
    "arms = [\n",
    "    Arm(\n",
    "        Price.price_5,\n",
    "        learner=NormalInverseGammaRegressor(mu=np.array([1000] + [0] * 10)),\n",
    "    ),\n",
    "    Arm(\n",
    "        Price.price_8,\n",
    "        learner=NormalInverseGammaRegressor(mu=np.array([1000] + [0] * 10)),\n",
    "    ),\n",
    "    Arm(\n",
    "        Price.price_11,\n",
    "        learner=NormalInverseGammaRegressor(mu=np.array([1000] + [0] * 10)),\n",
    "    ),\n",
    "    Arm(\n",
    "        Price.price_14,\n",
    "        learner=NormalInverseGammaRegressor(mu=np.array([1000] + [0] * 10)),\n",
    "    ),\n",
    "    Arm(\n",
    "        Price.price_17,\n",
    "        learner=NormalInverseGammaRegressor(mu=np.array([1000] + [0] * 10)),\n",
    "    ),\n",
    "]\n",
    "\n",
    "agent = ContextualAgent(arms=arms, policy=policy, random_seed=111)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For the first round, we'll assume that demand is constant, so our measure of success will be the Bandit learning the true demand distribution. However, we only get to update our agent once per day, so we'll have to make decisions for all 10 cities at once, then gather the rewards.\n",
    "\n",
    "In this simulation, the reward for any city-price combination is constant over time, so computing regret is easy. We just have to figure out the best price for each city, and compute the difference between that and the price we chose.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "one_hot_encoding = np.append(np.ones((10, 1)), np.eye(10), axis=-1)\n",
    "\n",
    "regret: list[float] = []\n",
    "\n",
    "best_price_per_city = np.array(\n",
    "    [\n",
    "        [oracle.margin(location, price.value) for price in Price]\n",
    "        for location in range(10)\n",
    "    ]\n",
    ").max(axis=1)\n",
    "\n",
    "for iteration in range(365):\n",
    "    # Pick prices for each location\n",
    "    decisions = agent.pull(one_hot_encoding)\n",
    "\n",
    "    # End of the day, collect rewards\n",
    "    rewards = [token.take_action(location) for location, token in enumerate(decisions)]\n",
    "    regret.append((best_price_per_city - np.array(rewards)).sum())\n",
    "\n",
    "    # Update the agent\n",
    "    for token, reward, context_row in zip(decisions, rewards, one_hot_encoding):\n",
    "        agent.select_for_update(token).update(\n",
    "            np.atleast_2d(context_row), np.atleast_1d(reward)\n",
    "        )"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can see that the agent achieves sublinear regret quick quickly.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAAk0AAAHHCAYAAACiOWx7AAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjEwLjAsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvlHJYcgAAAAlwSFlzAAAPYQAAD2EBqD+naQAAYvZJREFUeJzt3XlYVNX/B/D3sMwAwrDIrmzuG+KOlGuSYGa5tLhU7mWp5ZILfTM1S1wy27VV/X7TSvtlmVqKuGWgmYqKC7mguLAoyAz7MnN+fxA3J0BndOAy8H49z30e5p5z7/0chryfzjn3XIUQQoCIiIiI7shK7gCIiIiILAGTJiIiIiIjMGkiIiIiMgKTJiIiIiIjMGkiIiIiMgKTJiIiIiIjMGkiIiIiMgKTJiIiIiIjMGkiIiIiMgKTJiIiIiIjMGkisgBr166FQqGQNhsbGzRq1AhjxozBtWvX5A7vrvLz87FgwQLs3btX7lCqTVxcHBYsWIDs7Gyznjc2Nhbjxo1DixYt4ODggCZNmmDChAlITU2tUHfnzp0YP3482rVrB2trawQGBlZ6zgULFhj8Pf17+/3336W6Y8aMqbROq1atKpz37bffxmOPPQYvLy8oFAosWLDgntv99ttvQ6FQoF27dvd8DiJzs5E7ACIy3ptvvomgoCAUFhbi4MGDWLt2LQ4cOIDExETY2dnJHV6V8vPzsXDhQgBAnz595A2mmsTFxWHhwoUYM2YMXFxczHbeOXPmICsrC08++SSaN2+Oixcv4qOPPsLWrVuRkJAAb29vqe6GDRvw3XffoVOnTvD19a3ynEOHDkWzZs0q7H/ttdeQm5uLrl27GuxXqVT44osvDPY5OztXOP7111+Ht7c3OnbsiB07dpjaVMnVq1exePFiNGjQ4J7PQVQdmDQRWZABAwagS5cuAIAJEybA3d0dS5cuxZYtW/DUU0/VWBxCCBQWFsLe3r7Grllfvfvuu+jRowesrP4ZGIiMjETv3r3x0Ucf4a233pL2L168GJ9//jlsbW3x6KOPIjExsdJztm/fHu3btzfYd+XKFVy9ehUTJkyAUqk0KLOxscEzzzxz11iTk5MRGBiImzdvwsPDw5RmGnj11VfRvXt36HQ63Lx5857PQ2RuHJ4jsmA9e/YEAFy4cMFg/9mzZ/HEE0/Azc0NdnZ26NKlC7Zs2VLh+BMnTqB3796wt7dH48aN8dZbb2HNmjVQKBS4dOmSVC8wMBCPPvooduzYgS5dusDe3h6ffvopACA7OxvTpk2Dn58fVCoVmjVrhqVLl0Kv1wMALl26JN1AFy5cKA3v3G3oxtjYAOCTTz5B27ZtoVKp4Ovri8mTJ1c6THbo0CFERkbC2dkZDg4O6N27t8FQFADk5ORg2rRpCAwMhEqlgqenJx5++GEcPXq0ylgXLFiAWbNmAQCCgoKkNpbHWVpaikWLFqFp06ZQqVQIDAzEa6+9hqKiojv+DgCgV69eBglT+T43NzecOXPGYL+vry9sbW3ves7KfPPNNxBCYNSoUZWW63Q6aLXaO56jquFAU+zfvx/ff/893nvvvfs+F5G5saeJyIKV35RdXV2lfadOncKDDz6IRo0aYe7cuWjQoAE2btyIwYMH4//+7/8wZMgQAMC1a9fQt29fKBQKREVFoUGDBvjiiy+gUqkqvVZSUhJGjBiBF154ARMnTkTLli2Rn5+P3r1749q1a3jhhRfg7++PuLg4REVFITU1Fe+99x48PDywatUqvPjiixgyZAiGDh0KABV6Om5nSmwLFizAwoULER4ejhdffBFJSUlYtWoVDh8+jN9//11KInbv3o0BAwagc+fOmD9/PqysrLBmzRo89NBD+O2339CtWzcAwKRJk/D9999jypQpaNOmDTIzM3HgwAGcOXMGnTp1qjTeoUOH4q+//sI333yDlStXwt3dHQCkZHHChAlYt24dnnjiCcycOROHDh1CdHQ0zpw5g82bN1f5e6hKbm4ucnNzpeuYw/r16+Hn54devXpVKMvPz4darUZ+fj5cXV0xYsQILF26FI6Ojma7PlCWmE2dOhUTJkxAcHCwWc9NZBaCiGq9NWvWCABi165d4saNG+LKlSvi+++/Fx4eHkKlUokrV65Idfv16yeCg4NFYWGhtE+v14sHHnhANG/eXNo3depUoVAoxLFjx6R9mZmZws3NTQAQycnJ0v6AgAABQPz6668GcS1atEg0aNBA/PXXXwb7586dK6ytrUVKSooQQogbN24IAGL+/PlGtdfY2DIyMoRSqRT9+/cXOp1OqvvRRx8JAOKrr76S2t+8eXMREREh9Hq9VC8/P18EBQWJhx9+WNrn7OwsJk+ebFSct1u+fHmF35sQQiQkJAgAYsKECQb7X331VQFA7N692+RrLVq0SAAQsbGxVdYZOHCgCAgIMOp8iYmJAoCYPXt2hbK5c+eKOXPmiO+++0588803YvTo0QKAePDBB0VJSUml5zP1+y730UcfCWdnZ5GRkSGEEKJ3796ibdu2Jp2DqDoxaSKyAOVJ07+3wMBAsWPHDqleZmamUCgUYtGiReLGjRsG28KFCwUAcfXqVSGEEM2bNxcPPPBAhWtNnTq10qQpKCioQt327duLyMjICtfatWuXACC+/vprIYTpN1FjY9uwYYMAILZv325Qr6ioSKjVajFs2DAhhBBHjx4VAMS6desqxDphwgShUqmkpCsgIEB06dJFXLt2zahYy1WVNC1evFgAEKdPnzbYn5qaKgCImTNnmnSdffv2CRsbG/HUU0/dsZ4pSVNUVJQAII4fP25U/bffflsAEN98802l5feSNN28eVO4ubmJd955R9rHpIlqGw7PEVmQjz/+GC1atIBGo8FXX32F/fv3GwxZnT9/HkIIzJs3D/Pmzav0HBkZGWjUqBEuX76MsLCwCuWVPVUFlM3V+bdz587hxIkTVU76zcjIMKZZFRgb2+XLlwEALVu2NNivVCrRpEkTqfzcuXMAgNGjR1d5TY1GA1dXVyxbtgyjR4+Gn58fOnfujEceeQTPPfccmjRpcs9tsbKyqhC7t7c3XFxcpBiNcfbsWQwZMgTt2rWr8DTbvRJCYMOGDWjXrt0dh0xvN336dMybNw+7du3C8OHDzRLH66+/Djc3N0ydOtUs5yOqDkyaiCxIt27dpKfnBg8ejB49emDkyJFISkqCo6OjNPn61VdfRURERKXnqCopupvKnpTT6/V4+OGHMXv27EqPadGixT1dy9zKfy/Lly9Hhw4dKq1TPj/nqaeeQs+ePbF582bs3LkTy5cvx9KlS/HDDz9gwIAB9xyDQqG452OBsqfb+vfvD2dnZ2zfvh1OTk73db5yv//+Oy5fvozo6Gijj7G3t0fDhg2RlZVllhjOnTuHzz77DO+99x6uX78u7S8sLERJSQkuXboEtVoNNzc3s1yP6F4xaSKyUNbW1oiOjkbfvn3x0UcfYe7cuVJviK2tLcLDw+94fEBAAM6fP19hf2X7qtK0aVPk5ube9VqmJgzGxhYQEACgbJL67T1BxcXFSE5OluJq2rQpAECtVt81VgDw8fHBSy+9hJdeegkZGRno1KkT3n777TsmTVW1MSAgAHq9HufOnUPr1q2l/enp6cjOzpbacCeZmZno378/ioqKEBsbCx8fn7seY6z169dDoVBg5MiRRh+Tk5Nz38sK3O7atWvQ6/V4+eWX8fLLL1coDwoKwiuvvMIn6kh2XHKAyIL16dMH3bp1w3vvvYfCwkJ4enqiT58++PTTTytdMfrGjRvSzxEREYiPj0dCQoK0LysrC+vXrzf6+k899RTi4+MrXcgwOzsbpaWlAAAHBwdpnzGMjS08PBxKpRIffPABhBDS/i+//BIajQYDBw4EAHTu3BlNmzbFO++8g9zc3ArXK/+96HQ6aDQagzJPT0/4+vredXmA8oUY/93GRx55BAAq3PDfffddAJBirEpeXh4eeeQRXLt2Ddu3b0fz5s3vWN8UJSUl2LRpE3r06AF/f/8K5YWFhcjJyamwf9GiRRBCIDIy8p6ue/PmTZw9exb5+fkAgHbt2mHz5s0VtrZt28Lf3x+bN2/G+PHj7+laRObEniYiCzdr1iw8+eSTWLt2LSZNmoSPP/4YPXr0QHBwMCZOnIgmTZogPT0d8fHxuHr1Ko4fPw4AmD17Nr7++ms8/PDDmDp1qvRYv7+/P7KysozqHZo1axa2bNmCRx99FGPGjEHnzp2Rl5eHkydP4vvvv8elS5fg7u4Oe3t7tGnTBt999x1atGgBNzc3tGvXrspXZBgbm4eHB6KiorBw4UJERkbiscceQ1JSEj755BN07dpVWpDRysoKX3zxBQYMGIC2bdti7NixaNSoEa5du4Y9e/ZArVbj559/Rk5ODho3bownnngCISEhcHR0xK5du3D48GGsWLHijr+Lzp07AwD+85//YPjw4bC1tcWgQYMQEhKC0aNH47PPPkN2djZ69+6NP/74A+vWrcPgwYPRt2/fO5531KhR+OOPPzBu3DicOXPGYG0mR0dHDB48WPp84sQJaT2u8+fPQ6PRSItfhoSEYNCgQQbn3rFjBzIzM6tcmyktLQ0dO3bEiBEjpNem7NixA9u3b0dkZCQef/xxg/r/+9//cPnyZSkZ2r9/v3T9Z599VupV++ijj7Bw4ULs2bMHffr0gbu7u0E7ypUnmpWVEclC3nnoRGSM8qfnDh8+XKFMp9OJpk2biqZNm4rS0lIhhBAXLlwQzz33nPD29ha2traiUaNG4tFHHxXff/+9wbHHjh0TPXv2FCqVSjRu3FhER0eLDz74QAAQaWlpUr2AgAAxcODASmPLyckRUVFRolmzZkKpVAp3d3fxwAMPiHfeeUcUFxdL9eLi4kTnzp2FUqk06skqY2MTouxR9VatWglbW1vh5eUlXnzxRXHr1q1Kzzl06FDRsGFDoVKpREBAgHjqqaekR/eLiorErFmzREhIiHBychINGjQQISEh4pNPPrljrOUWLVokGjVqJKysrAyepCspKRELFy4UQUFBwtbWVvj5+YmoqCiDZSGqUr7cQ2Xbv5+Oq+opSwBi9OjRFc49fPhwYWtrKzIzMyu99q1bt8QzzzwjmjVrJhwcHIRKpRJt27YVixcvNvhuy/Xu3bvK6+/Zs0eqN3/+/Ar7KsOn56i2UQhxW582EdV706ZNw6efforc3FxYW1vLHY6B2hwbEdV9nNNEVI8VFBQYfM7MzMT//vc/9OjRQ/akpDbHRkT1E+c0EdVjYWFh6NOnD1q3bo309HR8+eWX0Gq1Va7xxNiIqD5j0kRUjz3yyCP4/vvv8dlnn0GhUKBTp0748ssvK33/GGMjovqOc5qIiIiIjMA5TURERERGYNJEREREZARZ5zRFR0fjhx9+wNmzZ2Fvb48HHngAS5culV6+mZWVhfnz52Pnzp1ISUmBh4cHBg8ejEWLFsHZ2Vk6T2WL8H3zzTcGL5Lcu3cvZsyYgVOnTsHPzw+vv/46xowZY3DMxx9/jOXLlyMtLQ0hISH48MMP0a1bN6Paotfrcf36dTg5Od33O6aIiIioZgghkJOTA19fX1hZ3aUvSc5FoiIiIsSaNWtEYmKiSEhIEI888ojw9/cXubm5QgghTp48KYYOHSq2bNkizp8/L2JjY0Xz5s3FsGHDDM4DQKxZs0akpqZKW0FBgVR+8eJF4eDgIGbMmCFOnz4tPvzwQ2FtbS1+/fVXqc63334rlEql+Oqrr8SpU6fExIkThYuLi0hPTzeqLVeuXKlyUTdu3Lhx48aNW+3erly5ctd7fa2aCH7jxg14enpi3759VT4hs2nTJjzzzDPIy8uDjU1ZR5lCocDmzZurXGp/zpw52LZtGxITE6V9w4cPR3Z2Nn799VcAQGhoKLp27YqPPvoIQFnPkZ+fH6ZOnYq5c+feNXaNRgMXFxdcuXIFarXalGYTERGRTLRaLfz8/JCdnW0wilWZWrXkQPmLMt3c3O5YR61WSwlTucmTJ2PChAlo0qQJJk2ahLFjx0rDZPHx8RXebB4REYFp06YBKHsj+pEjRxAVFSWVW1lZITw8HPHx8ZXGUVRUZPACz/KXWqrVaiZNREREFsaYqTW1JmnS6/WYNm0aHnzwwSpf4nnz5k0sWrQIzz//vMH+N998Ew899BAcHBywc+dOvPTSS8jNzcXLL78MoOylk15eXgbHeHl5QavVoqCgALdu3YJOp6u0ztmzZyuNJTo6GgsXLrzX5hIREZGFqTVJ0+TJk5GYmIgDBw5UWq7VajFw4EC0adMGCxYsMCi7fYXgjh07Ii8vD8uXL5eSpuoQFRWFGTNmGMTn5+dXbdcjIiIiedWKJQemTJmCrVu3Ys+ePWjcuHGF8pycHERGRsLJyQmbN2+Gra3tHc8XGhqKq1evSsNn3t7eSE9PN6iTnp4OtVoNe3t7uLu7w9rautI63t7elV5DpVJJQ3EckiMiIqr7ZE2ahBCYMmUKNm/ejN27dyMoKKhCHa1Wi/79+0OpVGLLli2ws7O763kTEhLg6uoKlUoFoOwdVrGxsQZ1YmJiEBYWBgBQKpXo3LmzQR29Xo/Y2FipDhEREdVvsg7PTZ48GRs2bMBPP/0EJycnpKWlAQCcnZ1hb28vJUz5+fn4+uuvodVqodVqAQAeHh6wtrbGzz//jPT0dHTv3h12dnaIiYnB4sWL8eqrr0rXmTRpEj766CPMnj0b48aNw+7du7Fx40Zs27ZNqjNjxgyMHj0aXbp0Qbdu3fDee+8hLy8PY8eOrdlfChEREdVORi1CVE1QxVoJa9asEUIIsWfPnirrJCcnCyGE+OWXX0SHDh2Eo6OjaNCggQgJCRGrV68WOp3O4Fp79uwRHTp0EEqlUjRp0kS6xu0+/PBD4e/vL5RKpejWrZs4ePCg0W3RaDQCgNBoNPf66yAiIqIaZsr9u1at02TJtFotnJ2dpSURiIiIqPYz5f5dKyaCExEREdV2TJqIiIiIjMCkiYiIiMgITJqIiIiIjMCkiYiIiMgIteY1KkRERET/ptcLpGkLoRcC9rbWaOioki0WJk1ERERU6wgh8N6uc/jfwcvIyisGADwW4osPRnSULSYmTURERCQLnV5g459XkJlbVKHsXEYufkq4DgCwsVLA2koBG2tFTYdogEkTERERyWLHqTRE/XDyjnUWPtYWI0P9YWst/zRsJk1EREQki4Qr2QCAVt5O6ODnUqH8oVae6N/Wu2aDugMmTURERCSLM6laAMDoBwIxopu/zNHcnfx9XURERFTvCCFw+npZ0tTW1zLe2cqkiYiIiGpcRk4RMvOKYW2lQAsvJ7nDMQqTJiIiIqpx5b1MTT0awM7WWuZojMM5TURERGQW3/6Rgk/3X4ROL+5aN7eoFADQxscyhuYAJk1ERERkBtrCEry97Qxy/k6GjPVAM/dqisj8mDQRERERACAztwjJN/Pu6dgdp9KQU1SKZp6OWPZEe6OOcVTZoLmn4z1dTw5MmoiIiOqxv9JzMOf/TuDarQJk5FRcmdtUL/Zuik7+rmaIrPZh0kRERFSLZOYW4eLfvT3FpXocS7mFG2ZIZqqyPTHN4PyNXOxhe4+vK2nto8ZjHXzNFVqtw6SJiIjqtc/3X8TauEso1evlDgVCwCy9PaZq6eWEJcOC0djVAR5Oqhq/vqVg0kRERLVSiU6PE1ezUaq7+5NYxhAALmfm4UxqDvSi7JxZecXYeiLVLOc3Jz83e9haWQGKsoSmmacjqutVtY52Nniysx9cGyir6Qp1B5MmIiIyWnGpHpqCkmq/Tk5hCV5afxRn03Kq/VoAMC28OR5u41Uj17obTyc79vbUUkyaiIhIUlyqR8zpdGTlFxvszy8qxcGLmTh4MQsFJboai8dJZQMPtfkSCDcHJToHuEJ122KKbX3ViKhFL4Wl2otJExFRPVOi0+NmbsV5M0IA87ecQszp9LueQ1FdY0W3aeOjxqpRneHf0KH6L0ZkBCZNRET1hF4v8Na2M/jucAryiqvuLVLaWOGhlp4GiZGVlQIhjZ3Rs7kHWnk7QVETWRNRLcOkiYiontj7Vwa++j0ZAGBjpYBVJYmPWwMloocGo28rz5oOj6jWY9JERFRPrPn9EgDgubAALBjUFlZW7C0iMgWTJiKiWq5Up0dSek6VL0Et0Qkcv5KNNG0hUjWFOH4lG6W6imsOXdcUQqEAJvZswoSJ6B4waSIiquXe2HIKGw6lmOVcj7b3hZ8bJ1YT3QsmTUREtdiNnCJs+vMKAMDX2a7KCdhNPBqgtY8aDZQ26BroCic72wp1rKyAFl5O1RovUV3GpImIqAaV6vQ4flVj9LvE9iZloEQn0NHfBZtferCaoyOiO2HSRERUhbIEJxv7/7qJy5l5yMovwdHLt1BUeu+LO+r0AlVMTbqjMQ8E3vM1icg8mDQRUb0Rd+Empm44hrziUqPq6/QCJWZ679ntXBxs0dTD+HeJNfVwxCPBPmaPg4hMw6SJiOqNn4+nIjOv+O4Vb+PiYIsHm7mjfSNnOCit0SnAFQ0b3PtrPRQKwN1RBWs+vUZkcZg0EVG9cSEjFwCwYFAbhBvxclaFQgFvtR0THCICAFjJefHo6Gh07doVTk5O8PT0xODBg5GUlGRQp7CwEJMnT0bDhg3h6OiIYcOGIT3d8L1IKSkpGDhwIBwcHODp6YlZs2ahtNSw+33v3r3o1KkTVCoVmjVrhrVr11aI5+OPP0ZgYCDs7OwQGhqKP/74w+xtJiL5XLhRljR1CXRDY1eHu26NXOyZMBGRRNakad++fZg8eTIOHjyImJgYlJSUoH///sjLy5PqTJ8+HT///DM2bdqEffv24fr16xg6dKhUrtPpMHDgQBQXFyMuLg7r1q3D2rVr8cYbb0h1kpOTMXDgQPTt2xcJCQmYNm0aJkyYgB07dkh1vvvuO8yYMQPz58/H0aNHERISgoiICGRkZNTML4OIqtWtvGJpaK6JRwOZoyEiiyRqkYyMDAFA7Nu3TwghRHZ2trC1tRWbNm2S6pw5c0YAEPHx8UIIIbZv3y6srKxEWlqaVGfVqlVCrVaLoqIiIYQQs2fPFm3btjW41tNPPy0iIiKkz926dROTJ0+WPut0OuHr6yuio6ONil2j0QgAQqPRmNhqIqoJfyRnioA5W8UD0bFyh0JEtYgp929Ze5r+TaPRAADc3NwAAEeOHEFJSQnCw8OlOq1atYK/vz/i4+MBAPHx8QgODoaX1z/zEyIiIqDVanHq1Cmpzu3nKK9Tfo7i4mIcOXLEoI6VlRXCw8OlOkRk2crnMzX1dJQ5EiKyVLVmIrher8e0adPw4IMPol27dgCAtLQ0KJVKuLi4GNT18vJCWlqaVOf2hKm8vLzsTnW0Wi0KCgpw69Yt6HS6SuucPXu20niLiopQVPTP4nRardbEFhNRdcvQFiKnqGx+47GUbABAUw7NEdE9qjVJ0+TJk5GYmIgDBw7IHYpRoqOjsXDhQrnDIKJKCCGw5Nez+HTfxQplzdjTRET3qFYkTVOmTMHWrVuxf/9+NG7cWNrv7e2N4uJiZGdnG/Q2paenw9vbW6rz76fcyp+uu73Ov5+4S09Ph1qthr29PaytrWFtbV1pnfJz/FtUVBRmzJghfdZqtfDz8zOx5UR0J7Fn0jHn/07iZq5xrxypjLP9P+9gc3dU4qFWnuYIjYjqIVmTJiEEpk6dis2bN2Pv3r0ICgoyKO/cuTNsbW0RGxuLYcOGAQCSkpKQkpKCsLAwAEBYWBjefvttZGRkwNOz7B/DmJgYqNVqtGnTRqqzfft2g3PHxMRI51AqlejcuTNiY2MxePBgAGXDhbGxsZgyZUqlsatUKqhU977AHRFVbdXeC/j64GWkagru6ZUjAGBna4U3H2uHp7ryf2aIyDxkTZomT56MDRs24KeffoKTk5M0B8nZ2Rn29vZwdnbG+PHjMWPGDLi5uUGtVmPq1KkICwtD9+7dAQD9+/dHmzZt8Oyzz2LZsmVIS0vD66+/jsmTJ0tJzaRJk/DRRx9h9uzZGDduHHbv3o2NGzdi27ZtUiwzZszA6NGj0aVLF3Tr1g3vvfce8vLyMHbs2Jr/xRDVYzdzi7Ay5i8U6/QAgCc6N8acyFYwdbkkB6UN7JXW1RAhEdVb1f4s3x0AqHRbs2aNVKegoEC89NJLwtXVVTg4OIghQ4aI1NRUg/NcunRJDBgwQNjb2wt3d3cxc+ZMUVJSYlBnz549okOHDkKpVIomTZoYXKPchx9+KPz9/YVSqRTdunUTBw8eNLotXHKAyDw+2PWXCJizVXRetFNcvJErdzhEVMeZcv9WCCHM/zbKekir1cLZ2RkajQZqtVrucIhqtcRrGkzecBSXM/OrrPPe0x0wuGOjGoyKiOojU+7ftWIiOBFZFiEEfjt3E1m3vfz2Vn4x/rx8C0Ulurse/+flW8jOL6myvJmnIx4J9jFLrERE5sKkiYhMtvtsBsav+/O+zhHcyBmrn+0MlU3FNXZdHZR85xsR1TpMmojIZL+duwkA8HdzQEBDBwCA0toKnQJc0bCB8q7H2yutEd7aCw1U/CeIiCwH/8UiIpP9eTkLADAroiUGhfjKHA0RUc2oVe+eI6LaL6+oFGdScwAAXQJdZY6GiKjmMGkiIpMkXMmGTi/QyMUePs72codDRFRjODxHREYpLNFh9vcnsOX4dQBA5wD2MhFR/cKkiageEkIgJSsf+cU6HL+SjeuaQqmsVKdHwpVspGkLDY7JLSxFRk7ZO+CsFMCj7bkkABHVL0yaiOqwvUkZWL4jCSV/v5KkXFZeMW7mFldxVNWcVDb4eFQndPR3gZOd7d0PICKqQ5g0EdVhq/ZewKnr2krLlDZWcFTZIMi9AVr7OMFK8c+6SE09HNHK2wkKheFaSS29nODswGSJiOonJk1EdVRRqQ7HrmQDAN4f3gEejiqpzE5pjba+aqhs+EJbIiJjMWkiqqNOXNWguFQPd0clHgvxrdBrREREpuGSA0R11KGLmQCAbkFuTJiIiMyAPU1EFkAIgd/PZ+Lqrfw71ssuKMGRy7dQUKxDUnrZApTdAt1qIkQiojqPSRORjApLdCgo1t213me/XcSqvRdMPr9CAfRo7nEvoRER0b8waSKSyaY/r2DeT4koLNHfvfLferXwgNK66lF1pY0CHf1c4eFUNunbv6EDmnk63nesRETEpIlIFrtOp2P2/52AEMbVt7e1xqyIlhjXI6h6AyMioioxaSKSwee/XYQQwFNdGiN6aHsYM03byoqTuYmI5MSkiaiG3b5+0gu9m8KayRARkUXgkgNENeyf9ZNUaOLeQO5wiIjISEyaiGrYH8lZAIBQrp9ERGRRODxHVM1OXtXgywMXpafkTlzNBlC26CQREVkOJk1U7yRcyca5vxd+rG6FJTos/TUJuUWlFcoebNawRmIgIiLzYNJE9cq59BwMWxUHnd7IZ/3NpGugKx7r0Ej63MS9AZp5OtVoDEREdH+YNFG98t6uc9DpBQIbOiCwhiZhBzZsgFcjWsJRxf/ciIgsGf8Vp3ojKS0H206mQqEAVj/bGa281XKHREREFoRPz1G98WPCNQDAw629mDAREZHJmDRRvbHjVBoA4NEQX5kjISIiS8ThOarThBDQ6QUu3szDxRt5sLVWoG9LD7nDIiIiC8SkiSxWdn4xfjh6DceuZKOkVF+hvESnx7Er2cjKK5b2PdDUHU52tjUZJhER1RFMmsgiZeQU4ulPDyL5Zp7Rx1hbKTAy1L8aoyIiorqMSRNZHCEEJv73CJJv5sHX2Q6jugfA2b5i75FCATT3dEILL0cooIDSxgr2SmsZIiYiorqASRNZnDOpOTh+JRsqGyt883x3BDTkS2+JiKj68ek5sjg7T5c9BderhQcTJiIiqjFMmsii5BSW4LvDVwAA/dt4yRwNERHVJxyeI4uxNykDY9YcBgBYKYB+rZk0ERFRzZG1p2n//v0YNGgQfH19oVAo8OOPPxqUKxSKSrfly5dLdQIDAyuUL1myxOA8J06cQM+ePWFnZwc/Pz8sW7asQiybNm1Cq1atYGdnh+DgYGzfvr1a2kz37oej16SfR3Tzh1sDpYzREBFRfSNr0pSXl4eQkBB8/PHHlZanpqYabF999RUUCgWGDRtmUO/NN980qDd16lSpTKvVon///ggICMCRI0ewfPlyLFiwAJ999plUJy4uDiNGjMD48eNx7NgxDB48GIMHD0ZiYmL1NJxMptML/HbuBgBg4wtheHtIsMwRERFRfSPr8NyAAQMwYMCAKsu9vb0NPv/000/o27cvmjRpYrDfycmpQt1y69evR3FxMb766isolUq0bdsWCQkJePfdd/H8888DAN5//31ERkZi1qxZAIBFixYhJiYGH330EVavXn0/TSQzSbymwa38EjiqbNDR30XucIiIqB6ymIng6enp2LZtG8aPH1+hbMmSJWjYsCE6duyI5cuXo7S0VCqLj49Hr169oFT+M5QTERGBpKQk3Lp1S6oTHh5ucM6IiAjEx8dXU2voTtK1hdh9Nh27Tqdjx6k0rNiZhMc//h0A8EDThrC1tpg/WyIiqkMsZiL4unXr4OTkhKFDhxrsf/nll9GpUye4ubkhLi4OUVFRSE1NxbvvvgsASEtLQ1BQkMExXl5eUpmrqyvS0tKkfbfXSUtLqzKeoqIiFBUVSZ+1Wu19tY+A1fsuYPPRa0hKz6myTr/WnjUYERER0T8sJmn66quvMGrUKNjZ2RnsnzFjhvRz+/btoVQq8cILLyA6Ohoqlara4omOjsbChQur7fz1zaWbeVjyy1kAZSt5t/Rygp1t2erd/m4OaNdIDVcHJYZ0bCRnmEREVI9ZRNL022+/ISkpCd99991d64aGhqK0tBSXLl1Cy5Yt4e3tjfT0dIM65Z/L50FVVaeqeVIAEBUVZZCwabVa+Pn5Gd0mMlTeu9Tc0xEbXwiDK5+MIyKiWsYiJod8+eWX6Ny5M0JCQu5aNyEhAVZWVvD0LBvGCQsLw/79+1FSUiLViYmJQcuWLeHq6irViY2NNThPTEwMwsLCqryOSqWCWq022Ojenc/IBQC0a+TMhImIiGolWZOm3NxcJCQkICEhAQCQnJyMhIQEpKSkSHW0Wi02bdqECRMmVDg+Pj4e7733Ho4fP46LFy9i/fr1mD59Op555hkpIRo5ciSUSiXGjx+PU6dO4bvvvsP7779v0Ev0yiuv4Ndff8WKFStw9uxZLFiwAH/++SemTJlSvb8AkpQnTc08HWWOhIiIqApCRnv27BEAKmyjR4+W6nz66afC3t5eZGdnVzj+yJEjIjQ0VDg7Ows7OzvRunVrsXjxYlFYWGhQ7/jx46JHjx5CpVKJRo0aiSVLllQ418aNG0WLFi2EUqkUbdu2Fdu2bTOpLRqNRgAQGo3GpOOozKMf/CYC5mwVv5xMlTsUIiKqR0y5fyuEEELGnK3O0Gq1cHZ2hkaj4VCdifR6gbbzd6CgRIddM3qzt4mIiGqMKfdvi5jTRHXbdU0BCkp0sLVWIKChg9zhEBERVcoinp6juiOnsASf/5aMDG0hAODqrQIcOH8TABDYsAEXriQiolqLSRNVu7yiUhxKzsT5jFxsOX4didcqXwi0dwuPGo6MiIjIeEyaqNpoC0swa9Nx7D6bgRLdP1Pn3BooMeaBQFhbKaC2s0HnADeo7W3QyMVexmiJiIjujEkTVZtP913AjlNli4Y2drVHJ39XuDrYYuyDQQh0byBzdERERKZh0kRmpykowe/nb2Lt75cAAO8P74DHQnyhUCjkDYyIiOg+MGkis3t103HEnC7rYWrrq2bCREREdQIfVSKzKirVYf9fNwCUvWh38ZBgJkxERFQnsKeJzOpYSjaKSvVwd1Rh36w+TJiIiKjOYE8TmVXchUwAwANNGzJhIiKiOoU9TWQWOr3Apj+v4IPYcwDKkiYiIqK6hEkT3ZfiUj1OXddg/aEUfH/kqrT/wWbuMkZFRERkfkya6L7M/eEEfjh6DQBgpQCGd/NHaJAb/Nz4DjkiIqpbmDTRPUvVFOCnhOsAAG+1HV5/tDUebe8rc1RERETVg0kT3ZNSnR6f70+GTi8QGuSG714IkzskIiKiasWkiUymLSzBwA9+w5WsAgDA2AcD5Q2IiIioBjBpIpPFX8jElawC2NlaYWS3ADzcxlvukIiIiKodkyYy2dHLtwAAQzo2whuD2sgcDRERUc0weXHL/fv3o7S0tML+0tJS7N+/3yxBUe12NKUsaero7ypzJERERDXH5KSpb9++yMrKqrBfo9Ggb9++ZgmKaq/iUj1OXNUAADoHMGkiIqL6w+SkSQhR6esxMjMz0aBBA7MERbXX6VQtikr1cHGwRRN3ft9ERFR/GD2naejQoQAAhUKBMWPGQKVSSWU6nQ4nTpzAAw88YP4IqVbZczYDANDJ35XvliMionrF6KTJ2dkZQFlPk5OTE+zt7aUypVKJ7t27Y+LEieaPkGqNwhId1h+6DAAY3LGRzNEQERHVLKOTpjVr1gAAAgMD8eqrr3Iorh7aknAdN3OL4etshwHtuMwAERHVLybPaZo/fz5UKhV27dqFTz/9FDk5OQCA69evIzc31+wBUu0RezYdADCqewBsrU3+0yEiIrJoJq/TdPnyZURGRiIlJQVFRUV4+OGH4eTkhKVLl6KoqAirV6+ujjipFkjTFAIAmns6yhwJERFRzTO5u+CVV15Bly5dcOvWLYN5TUOGDEFsbKxZg6PaJfXvpMnb2U7mSIiIiGqeyT1Nv/32G+Li4qBUKg32BwYG4tq1a2YLjGqXUp0eN3OLAADeaiZNRERU/5jc06TX66HT6Srsv3r1KpycnMwSFNU+N3KLoBeAjZUCDR1Vdz+AiIiojjE5aerfvz/ee+896bNCoUBubi7mz5+PRx55xJyxUS1SPp/J00kFayuuz0RERPWPycNz77zzDiIjI9GmTRsUFhZi5MiROHfuHNzd3fHNN99UR4xUC6Rry5ImL85nIiKiesrkpMnPzw/Hjx/Hd999h+PHjyM3Nxfjx4/HqFGjDCaGU91S3tPE+UxERFRfmZQ0lZSUoFWrVti6dStGjRqFUaNGVVdcVMukacsmgXsxaSIionrKpDlNtra2KCwsrK5YqBYrH57jcgNERFRfmTwRfPLkyVi6dClKS0urIx6qpTg8R0RE9Z3Jc5oOHz6M2NhY7Ny5E8HBwRXeQffDDz+YLTiS16nrGoz64hA0BSUQomwfh+eIiKi+MrmnycXFBcOGDUNERAR8fX3h7OxssJli//79GDRoEHx9faFQKPDjjz8alI8ZMwYKhcJgi4yMNKiTlZWFUaNGQa1Ww8XFBePHj6/wDrwTJ06gZ8+esLOzg5+fH5YtW1Yhlk2bNqFVq1aws7NDcHAwtm/fblJb6qIPY88jO/+fhMndUYU2vmp5gyIiIpKJyT1Na9asMdvF8/LyEBISgnHjxmHo0KGV1omMjDS4pkpluLDiqFGjkJqaipiYGJSUlGDs2LF4/vnnsWHDBgCAVqtF//79ER4ejtWrV+PkyZMYN24cXFxc8PzzzwMA4uLiMGLECERHR+PRRx/Fhg0bMHjwYBw9ehTt2rUzW3stSUpmPnaeTgMA/N+LD8DfzQFqexuobKxljoyIiEgeCiHK+xHkpVAosHnzZgwePFjaN2bMGGRnZ1fogSp35swZtGnTBocPH0aXLl0AAL/++iseeeQRXL16Fb6+vli1ahX+85//IC0tTXr1y9y5c/Hjjz/i7NmzAICnn34aeXl52Lp1q3Tu7t27o0OHDka/gFir1cLZ2RkajQZqtWX3xgghMGXDMWw7mYreLTywblw3uUMiIiKqFqbcv03uaerYsSMUioorQisUCtjZ2aFZs2YYM2YM+vbta+qpK7V37154enrC1dUVDz30EN566y00bNgQABAfHw8XFxcpYQKA8PBwWFlZ4dChQxgyZAji4+PRq1cvg3flRUREYOnSpbh16xZcXV0RHx+PGTNmGFw3IiKiymQNAIqKilBUVCR91mq1Zmmv3IQQWL4jCdtOpsLGSoGX+zWXOyQiIqJaweQ5TZGRkbh48SIaNGiAvn37om/fvnB0dMSFCxfQtWtXpKamIjw8HD/99NN9BxcZGYn//ve/iI2NxdKlS7Fv3z4MGDBAevddWloaPD09DY6xsbGBm5sb0tLSpDpeXl4Gdco/361OeXlloqOjDeZy+fn53V9jZXT1Vj4W/nwKr20+iYn/PYJP9l4AALw9pB06B7jKHB0REVHtYHJP082bNzFz5kzMmzfPYP9bb72Fy5cvY+fOnZg/fz4WLVqExx9//L6CGz58uPRzcHAw2rdvj6ZNm2Lv3r3o16/ffZ37fkVFRRn0Tmm1WotNnBZsOYVdZzIM9r3xaBs83dVfpoiIiIhqH5OTpo0bN+LIkSMV9g8fPhydO3fG559/jhEjRuDdd981S4C3a9KkCdzd3XH+/Hn069cP3t7eyMgwvNmXlpYiKysL3t7eAABvb2+kp6cb1Cn/fLc65eWVUalUFSalW6Lkm3mIPVv2O5zStxmUNlboGuiGsKYNZY6MiIiodjF5eM7Ozg5xcXEV9sfFxcHOrmwNH71eL/1sTlevXkVmZiZ8fHwAAGFhYcjOzjZI4nbv3g29Xo/Q0FCpzv79+1FSUiLViYmJQcuWLeHq6irViY2NNbhWTEwMwsLCzN6G2uarA8kQAujXyhOvRrTEy/2aM2EiIiKqhMk9TVOnTsWkSZNw5MgRdO3aFUDZgpdffPEFXnvtNQDAjh070KFDh7ueKzc3F+fPn5c+JycnIyEhAW5ubnBzc8PChQsxbNgweHt748KFC5g9ezaaNWuGiIgIAEDr1q0RGRmJiRMnYvXq1SgpKcGUKVMwfPhw+Pr6AgBGjhyJhQsXYvz48ZgzZw4SExPx/vvvY+XKldJ1X3nlFfTu3RsrVqzAwIED8e233+LPP//EZ599Zuqvx6JcycrHd4evAADG9wySORoiIqJaTtyDr7/+WnTv3l24uroKV1dX0b17d7F+/XqpPD8/XxQUFNz1PHv27BEAKmyjR48W+fn5on///sLDw0PY2tqKgIAAMXHiRJGWlmZwjszMTDFixAjh6Ogo1Gq1GDt2rMjJyTGoc/z4cdGjRw+hUqlEo0aNxJIlSyrEsnHjRtGiRQuhVCpF27ZtxbZt20z6nWg0GgFAaDQak46T08vfHBUBc7aKUZ8fFHq9Xu5wiIiIapwp9+9as06TpbO0dZrOZ+Qg/N39AICtU3ugXSPTVnMnIiKqC0y5f5s8pwkAsrOzpeG4rKwsAMDRo0dx7dq1ezkdyWDV3osAgIi2XkyYiIiIjGDynKYTJ04gPDwczs7OuHTpEiZMmAA3Nzf88MMPSElJwX//+9/qiJPuU1ZeMWJOp+Gv9FzkFJbgp4SyBPfFPs1kjoyIiMgymJw0zZgxA2PGjMGyZcvg5OQk7X/kkUcwcuRIswZH5iGEwKAPD+BadoHB/oi2Xujg5yJPUERERBbG5KTp8OHD+PTTTyvsb9So0R1X0Cb55BaVSgnT+B5BaKC0Rgd/F/Rs7iFzZERERJbD5KRJpVJV+p61v/76Cx4evAnXRtn5ZWtUqWysMO/RNjJHQ0REZJlMngj+2GOP4c0335QWi1QoFEhJScGcOXMwbNgwswdI9+9WfjEAwNVBeZeaREREVBWTk6YVK1YgNzcXnp6eKCgoQO/evdGsWTM4Ojri7bffro4Y6T7d+runycXBVuZIiIiILJfJw3POzs6IiYnBgQMHcOLECeTm5qJTp04IDw+vjvjIDLLZ00RERHTfTE6ayvXo0QM9evSQPh89ehRvvPEGtm7dapbAyHxu5f2dNDVgTxMREdG9Mml4bseOHXj11Vfx2muv4eLFssURz549i8GDB6Nr167Q6/XVEiTdn+yC8uE59jQRERHdK6N7mr788ktMnDgRbm5uuHXrFr744gu8++67mDp1Kp5++mkkJiaidevW1Rkr3aPyp+dcOaeJiIjonhnd0/T+++9j6dKluHnzJjZu3IibN2/ik08+wcmTJ7F69WomTLUYn54jIiK6f0YnTRcuXMCTTz4JABg6dChsbGywfPlyNG7cuNqCI/P45+k5Jk1ERET3yuikqaCgAA4ODgDK1mZSqVTw8fGptsDIfMqfnnOx5/AcERHRvTLp6bkvvvgCjo6OAIDS0lKsXbsW7u7uBnVefvll80VHZiENz/HpOSIionumEEIIYyoGBgZCoVDc+WQKhfRUXX2j1Wrh7OwMjUYDtVotdzgGgufvQE5RKWJn9kZTD0e5wyEiIqo1TLl/G93TdOnSpfuNi2RQotMjp6gUACeCExER3Q+TX6NClkVTUP6OQMCZc5qIiIjuGZOmOq58ErjazhbWVnceXiUiIqKqMWmq425xYUsiIiKzYNJUx2VoiwAA7o4qmSMhIiKybEya6riMnEIAgKeaSRMREdH9uKek6cKFC3j99dcxYsQIZGRkAAB++eUXnDp1yqzB0f3LyCnrafJ0spM5EiIiIstmctK0b98+BAcH49ChQ/jhhx+Qm5sLADh+/Djmz59v9gDp/pQPz3k4saeJiIjofpicNM2dOxdvvfUWYmJioFT+s+7PQw89hIMHD5o1OLp/0vAckyYiIqL7YnLSdPLkSQwZMqTCfk9PT9y8edMsQZH53CgfnlNzeI6IiOh+mJw0ubi4IDU1tcL+Y8eOoVGjRmYJisznnzlN7GkiIiK6HyYnTcOHD8ecOXOQlpYGhUIBvV6P33//Ha+++iqee+656oiR7lFxqR5ZeWWLWzJpIiIiuj8mJ02LFy9Gq1at4Ofnh9zcXLRp0wa9evXCAw88gNdff706YqR7dDO3rJfJxkrB984RERHdJ6Nf2FtOqVTi888/x7x585CYmIjc3Fx07NgRzZs3r4746D6UD815OKlgxVeoEBER3ReTk6YDBw6gR48e8Pf3h7+/f3XERGaSoeWTc0REROZi8vDcQw89hKCgILz22ms4ffp0dcREZnI9uwAA4MGFLYmIiO6byUnT9evXMXPmTOzbtw/t2rVDhw4dsHz5cly9erU64qN7dOhiJt7Z+RcAoIWXo8zREBERWT6TkyZ3d3dMmTIFv//+Oy5cuIAnn3wS69atQ2BgIB566KHqiJFMVKLTY+am48gtKkVYk4Z4sU9TuUMiIiKyePf1wt6goCDMnTsXS5YsQXBwMPbt22euuOg+fH/kKq7eKoC7owpfjukCJztbuUMiIiKyePecNP3+++946aWX4OPjg5EjR6Jdu3bYtm2bOWOje6DTC3y0+zwA4KU+TeGgNHmuPxEREVXC5KQpKioKQUFBeOihh5CSkoL3338faWlp+N///ofIyEiTzrV//34MGjQIvr6+UCgU+PHHH6WykpISzJkzB8HBwWjQoAF8fX3x3HPP4fr16wbnCAwMhEKhMNiWLFliUOfEiRPo2bMn7Ozs4Ofnh2XLllWIZdOmTWjVqhXs7OwQHByM7du3m9SW2mL/XzdwLbsALg62GBnKpxuJiIjMxeSkaf/+/Zg1axauXbuGrVu3YsSIEXBwcLini+fl5SEkJAQff/xxhbL8/HwcPXoU8+bNw9GjR/HDDz8gKSkJjz32WIW6b775JlJTU6Vt6tSpUplWq0X//v0REBCAI0eOYPny5ViwYAE+++wzqU5cXBxGjBiB8ePH49ixYxg8eDAGDx6MxMTEe2qXnDb8kQIAGNqxMexsrWWOhoiIqO5QCCGE3EEAgEKhwObNmzF48OAq6xw+fBjdunXD5cuXpTWiAgMDMW3aNEybNq3SY1atWoX//Oc/SEtLg1JZtir23Llz8eOPP+Ls2bMAgKeffhp5eXnYunWrdFz37t3RoUMHrF692qj4tVotnJ2dodFooFarjTrG3M6l5yDy/d+g0wvETO+F5l5OssRBRERkKUy5fxs14WXLli0YMGAAbG1tsWXLljvWrawnyFw0Gg0UCgVcXFwM9i9ZsgSLFi2Cv78/Ro4cienTp8PGpqxp8fHx6NWrl5QwAUBERASWLl2KW7duwdXVFfHx8ZgxY4bBOSMiIgyGC/+tqKgIRUVF0metVnv/DbwPmvwSTPjvn9DpBXq38GDCREREZGZGJU2DBw9GWloaPD0979gTpFAooNPpzBWbgcLCQsyZMwcjRowwyARffvlldOrUCW5uboiLi0NUVBRSU1Px7rvvAgDS0tIQFBRkcC4vLy+pzNXVFWlpadK+2+ukpaVVGU90dDQWLlxorubdty3Hr+FyZj4au9pj5dMd5A6HiIiozjEqadLr9ZX+XFNKSkrw1FNPQQiBVatWGZTd3kPUvn17KJVKvPDCC4iOjoZKVX2vD4mKijK4tlarhZ+fX7Vd727StWW9Xv1aecKtAV/OS0REZG4mTwT/73//azAsVa64uBj//e9/zRLU7coTpsuXLyMmJuau442hoaEoLS3FpUuXAADe3t5IT083qFP+2dvb+451yssro1KpoFarDTY5ZeUXAwBcmTARERFVC5OTprFjx0Kj0VTYn5OTg7Fjx5olqHLlCdO5c+ewa9cuNGzY8K7HJCQkwMrKCp6engCAsLAw7N+/HyUlJVKdmJgYtGzZEq6urlKd2NhYg/PExMQgLCzMjK2pXrfyypIm9jIRERFVD5NXPhRCQKFQVNh/9epVODs7m3Su3NxcnD9/XvqcnJyMhIQEuLm5wcfHB0888QSOHj2KrVu3QqfTSXOM3NzcoFQqER8fj0OHDqFv375wcnJCfHw8pk+fjmeeeUZKiEaOHImFCxdi/PjxmDNnDhITE/H+++9j5cqV0nVfeeUV9O7dGytWrMDAgQPx7bff4s8//zRYlqC2y/o7aXJ1YNJERERULYSROnToIDp27CisrKxEcHCw6Nixo7S1b99eODk5iSeffNLY0wkhhNizZ48AUGEbPXq0SE5OrrQMgNizZ48QQogjR46I0NBQ4ezsLOzs7ETr1q3F4sWLRWFhocF1jh8/Lnr06CFUKpVo1KiRWLJkSYVYNm7cKFq0aCGUSqVo27at2LZtm0lt0Wg0AoDQaDQmHWcu/d/dJwLmbBUHzt2Q5fpERESWyJT7t9E9TeVPzSUkJCAiIgKOjo5SmVKpRGBgIIYNG2ZSwtanTx+IOywTdacyAOjUqRMOHjx41+u0b98ev/322x3rPPnkk3jyySfveq7aSprTxJ4mIiKiamF00jR//nwAZYtJPv3007Czs6u2oMg0QghpTpNrA76cl4iIqDqYPKdp9OjR1REH3YecolKU6st65djTREREVD1MTpp0Oh1WrlyJjRs3IiUlBcXFxQblWVlZZguOjJOdV/ZkoIPSmu+bIyIiqiYmLzmwcOFCvPvuu3j66aeh0WgwY8YMDB06FFZWVliwYEE1hEh3w/lMRERE1c/kpGn9+vX4/PPPMXPmTNjY2GDEiBH44osv8MYbbxg1KZvMj2s0ERERVT+Tk6a0tDQEBwcDABwdHaWFLh999FFs27bNvNGRUcrXaHJx4CRwIiKi6mJy0tS4cWOkpqYCAJo2bYqdO3cCAA4fPlyt73qjqt3KZ08TERFRdTM5aRoyZIj0ypGpU6di3rx5aN68OZ577jmMGzfO7AHS3d3inCYiIqJqZ/LTc0uWLJF+fvrpp+Hv74/4+Hg0b94cgwYNMmtwZJysv5+eY08TERFR9TE5afq3sLAwi3qxbV0jhMCp62XzytwdOTxKRERUXYxKmrZs2WL0CR977LF7DoZMF38hEyeuaqCysUL/tl5yh0NERFRnGZU0lb937m4UCgV0Ot39xENGKi7V47mvDuFYSjYAYHhXP/Y0ERERVSOjkia9Xl/dcZCJzqRqcfBi2errjiobPN+7qcwRERER1W33PaeJ5JGqKQAAqO1s8Nvsh+DMNZqIiIiqlclJ05tvvnnH8jfeeOOegyHjXcsuBAD0bO7BhImIiKgGmJw0bd682eBzSUkJkpOTYWNjg6ZNmzJpqiGp2WU9Tb4udjJHQkREVD+YnDQdO3aswj6tVosxY8ZgyJAhZgmK7u66pjxpspc5EiIiovrB5BXBK6NWq7Fw4ULMmzfPHKcjI5QPz/k4M2kiIiKqCWZJmgBAo9FIL++l6lc+PNeIPU1EREQ1wuThuQ8++MDgsxACqamp+N///ocBAwaYLTCqWnGpHjdyiwAAPpzTREREVCNMTppWrlxp8NnKygoeHh4YPXo0oqKizBYYVS1dWwghAKWNFRryfXNEREQ1wuSkKTk5uTriIBNcu21oTqFQyBwNERFR/WC2OU1Uc8oXtvRx5tAcERFRTTG5p6mwsBAffvgh9uzZg4yMjAqvWDl69KjZgqPKXf/7yTkuN0BERFRzTE6axo8fj507d+KJJ55At27dODwkg/LhOV/2NBEREdUYk5OmrVu3Yvv27XjwwQerIx4ywj+rgbOniYiIqKaYPKepUaNGcHJyqo5YyEgcniMiIqp5JidNK1aswJw5c3D58uXqiIeM8M8rVDg8R0REVFNMHp7r0qULCgsL0aRJEzg4OMDW1tagPCsry2zBUUXawhLkFJYC4CtUiIiIapLJSdOIESNw7do1LF68GF5eXpwIXsNS/x6ac7a3RQOVyV8fERER3SOT77pxcXGIj49HSEhIdcRDd/HP0Bx7mYiIiGqSyXOaWrVqhYKCguqIhYxwXVoNnPOZiIiIapLJSdOSJUswc+ZM7N27F5mZmdBqtQYbVa/y4TnOZyIiIqpZJg/PRUZGAgD69etnsF8IAYVCAZ1OZ57IqFJp2rKkyZsLWxIREdUok5OmPXv2VEccZKT84rIn55zsOAmciIioJpl85+3du3d1xEFGKiwpe9efnY21zJEQERHVLybPadq/f/8dN1PPNWjQIPj6+kKhUODHH380KBdC4I033oCPjw/s7e0RHh6Oc+fOGdTJysrCqFGjoFar4eLigvHjxyM3N9egzokTJ9CzZ0/Y2dnBz88Py5YtqxDLpk2b0KpVK9jZ2SE4OBjbt283qS01paC4bPjTTsmkiYiIqCaZ3NPUp0+fCvtuX6vJlDlNeXl5CAkJwbhx4zB06NAK5cuWLcMHH3yAdevWISgoCPPmzUNERAROnz4NO7uyOT2jRo1CamoqYmJiUFJSgrFjx+L555/Hhg0bAABarRb9+/dHeHg4Vq9ejZMnT2LcuHFwcXHB888/D6BsGYURI0YgOjoajz76KDZs2IDBgwfj6NGjaNeunSm/nmpXWFr2+7W3ZdJERERUo4SJsrOzDbYbN26InTt3itDQULFr1y5TTycBIDZv3ix91uv1wtvbWyxfvtzg2iqVSnzzzTdCCCFOnz4tAIjDhw9LdX755RehUCjEtWvXhBBCfPLJJ8LV1VUUFRVJdebMmSNatmwpfX7qqafEwIEDDeIJDQ0VL7zwgtHxazQaAUBoNBqjj7kXESv3iYA5W8X+vzKq9TpERET1gSn3b5OH55ydnQ02d3d3PPzww1i6dClmz55ttmQuOTkZaWlpCA8PN7h2aGgo4uPjAQDx8fFwcXFBly5dpDrh4eGwsrLCoUOHpDq9evWCUqmU6kRERCApKQm3bt2S6tx+nfI65depTFFRkSzLLRSWsKeJiIhIDiYnTVXx8vJCUlKSuU6HtLQ06bz/vk55WVpaGjw9PQ3KbWxs4ObmZlCnsnPcfo2q6pSXVyY6OtogefTz8zO1ifdEmgjOpImIiKhGmTyn6cSJEwafhRBITU3FkiVL0KFDB3PFVetFRUVhxowZ0metVlsjiVPB3z1NTJqIiIhqlslJU4cOHaBQKCCEMNjfvXt3fPXVV2YLzNvbGwCQnp4OHx8faX96erqUnHl7eyMjI8PguNLSUmRlZUnHe3t7Iz093aBO+ee71Skvr4xKpYJKpbqHlt0faXiOT88RERHVKJOH55KTk3Hx4kUkJycjOTkZly9fRn5+PuLi4tCqVSuzBRYUFARvb2/ExsZK+7RaLQ4dOoSwsDAAQFhYGLKzs3HkyBGpzu7du6HX6xEaGirV2b9/P0pKSqQ6MTExaNmyJVxdXaU6t1+nvE75dWoLvV6gqLR8nSazjawSERGREUzuaQoICDDbxXNzc3H+/Hnpc3JyMhISEuDm5gZ/f39MmzYNb731Fpo3by4tOeDr64vBgwcDAFq3bo3IyEhMnDgRq1evRklJCaZMmYLhw4fD19cXADBy5EgsXLgQ48ePx5w5c5CYmIj3338fK1eulK77yiuvoHfv3lixYgUGDhyIb7/9Fn/++Sc+++wzs7XVHMqXGwDY00RERFTjjH0kLzY2VrRu3brSR/Kys7NFmzZtxP79+015yk/s2bNHAKiwjR49WghRtuzAvHnzhJeXl1CpVKJfv34iKSnJ4ByZmZlixIgRwtHRUajVajF27FiRk5NjUOf48eOiR48eQqVSiUaNGoklS5ZUiGXjxo2iRYsWQqlUirZt24pt27aZ1JaaWHIgM7dIBMzZKgLmbBU6nb7arkNERFRfmHL/Vgjxr8lJVXjsscfQt29fTJ8+vdLyDz74AHv27MHmzZvNk81ZGK1WC2dnZ2g0GqjV6mq5xrXsAjy4ZDeUNlb4660B1XINIiKi+sSU+7fRE2OOHz+OyMjIKsv79+9vMLeIzI9rNBEREcnH6KQpPT0dtra2VZbb2Njgxo0bZgmKKie9d86Wk8CJiIhqmtF330aNGiExMbHK8hMnThgsDUDmx54mIiIi+RidND3yyCOYN28eCgsLK5QVFBRg/vz5ePTRR80aHBniauBERETyMXrJgddffx0//PADWrRogSlTpqBly5YAgLNnz+Ljjz+GTqfDf/7zn2oLlLgaOBERkZyMTpq8vLwQFxeHF198EVFRUdKK4AqFAhEREfj4448rvL+NzIvDc0RERPIxaXHLgIAAbN++Hbdu3cL58+chhEDz5s2llbWpev3T08SJ4ERERDXN5BXBAcDV1RVdu3Y1dyx0F3zvHBERkXzYZWFBCjmniYiISDZMmixIQTGfniMiIpILkyYLUv7CXk4EJyIiqnlMmiwIVwQnIiKSD+++FoRLDhAREcmHSZMF4URwIiIi+TBpsiBcEZyIiEg+TJosSPm75zg8R0REVPOYNFkQ9jQRERHJh0mTBflnRXB+bURERDWNd18LwongRERE8mHSZEHyi5k0ERERyYVJkwXRFpQAANR2tjJHQkREVP8wabIQer1ATlEpAMDZnkkTERFRTWPSZCFyCkshRNnPTJqIiIhqHpMmC6H5e2jO3tYaSht+bURERDWNd18LUZ40sZeJiIhIHkyaLASTJiIiInkxabIQTJqIiIjkxaTJQpQnTWomTURERLJg0mQh2NNEREQkLyZNFoJJExERkbyYNFkIJk1ERETyYtJkIbRS0mQjcyRERET1E5MmC8GJ4ERERPJi0mQhODxHREQkLyZNFoJJExERkbyYNFkIJk1ERETyqvVJU2BgIBQKRYVt8uTJAIA+ffpUKJs0aZLBOVJSUjBw4EA4ODjA09MTs2bNQmlpqUGdvXv3olOnTlCpVGjWrBnWrl1bU028K71eQFvIpImIiEhOtf5RrMOHD0On00mfExMT8fDDD+PJJ5+U9k2cOBFvvvmm9NnBwUH6WafTYeDAgfD29kZcXBxSU1Px3HPPwdbWFosXLwYAJCcnY+DAgZg0aRLWr1+P2NhYTJgwAT4+PoiIiKiBVt5ZTlEphCj7mRPBiYiI5FHrkyYPDw+Dz0uWLEHTpk3Ru3dvaZ+DgwO8vb0rPX7nzp04ffo0du3aBS8vL3To0AGLFi3CnDlzsGDBAiiVSqxevRpBQUFYsWIFAKB169Y4cOAAVq5cWSuSpryisl4xW2sF7GytZY6GiIiofqr1w3O3Ky4uxtdff41x48ZBoVBI+9evXw93d3e0a9cOUVFRyM/Pl8ri4+MRHBwMLy8vaV9ERAS0Wi1OnTol1QkPDze4VkREBOLj46uMpaioCFqt1mCrLjp9WTeTrbVFfV1ERER1Sq3vabrdjz/+iOzsbIwZM0baN3LkSAQEBMDX1xcnTpzAnDlzkJSUhB9++AEAkJaWZpAwAZA+p6Wl3bGOVqtFQUEB7O3tK8QSHR2NhQsXmrN5VSrR6QEA1laKu9QkIiKi6mJRSdOXX36JAQMGwNfXV9r3/PPPSz8HBwfDx8cH/fr1w4ULF9C0adNqiyUqKgozZsyQPmu1Wvj5+VXLtdjTREREJD+LSZouX76MXbt2ST1IVQkNDQUAnD9/Hk2bNoW3tzf++OMPgzrp6ekAIM2D8vb2lvbdXketVlfaywQAKpUKKpXqntpiqhJdWdLEniYiIiL5WEzXxZo1a+Dp6YmBAwfesV5CQgIAwMfHBwAQFhaGkydPIiMjQ6oTExMDtVqNNm3aSHViY2MNzhMTE4OwsDAztuDelfc02TBpIiIiko1FJE16vR5r1qzB6NGjYWPzT+fYhQsXsGjRIhw5cgSXLl3Cli1b8Nxzz6FXr15o3749AKB///5o06YNnn32WRw/fhw7duzA66+/jsmTJ0s9RZMmTcLFixcxe/ZsnD17Fp988gk2btyI6dOny9LefyvRl81psrFm0kRERCQXi0iadu3ahZSUFIwbN85gv1KpxK5du9C/f3+0atUKM2fOxLBhw/Dzzz9LdaytrbF161ZYW1sjLCwMzzzzDJ577jmDdZ2CgoKwbds2xMTEICQkBCtWrMAXX3xRK5YbAG7vabKIr4uIiKhOUghRvmwi3Q+tVgtnZ2doNBqo1Wqznjvuwk2M/PwQmns6ImZG77sfQEREREYx5f7NrgsLUN7TxIngRERE8mHSZAFKdVxygIiISG68C1uAUvY0ERERyY5JkwUo/XtFcFs+PUdERCQbJk0WgD1NRERE8mPSZAFK9eU9Tfy6iIiI5MK7sAUo5WtUiIiIZMekyQKUcnFLIiIi2fEubAFK+e45IiIi2TFpsgDlT8/x3XNERETyYdJkAXTsaSIiIpIdkyYLUPL3RHAbPj1HREQkG96FLYDu7yUH2NNEREQkHyZNFuCfniYmTURERHJh0mQBdFxygIiISHa8C1uAEg7PERERyY5JkwXQla8IzuE5IiIi2TBpsgDli1vacniOiIhINrwLW4DyF/by3XNERETyYdJkAcpf2GvL4TkiIiLZMGmyAOXDc9YcniMiIpIN78IWQHr3HIfniIiIZMOkyQKU9zRxcUsiIiL5MGmyAOVzmtjTREREJB8mTRbgn54mfl1ERERy4V3YAnDJASIiIvkxabIA5e+e45IDRERE8mHSZAFKdOU9Tfy6iIiI5MK7sAWQepo4PEdERCQbJk0WoKT8hb1MmoiIiGTDpMkC/DOniV8XERGRXHgXtgD/zGliTxMREZFcmDRZAB1XBCciIpIdkyYLIC1uyafniIiIZMO7sAUoX9ySPU1ERETyYdJkAfjuOSIiIvnV6qRpwYIFUCgUBlurVq2k8sLCQkyePBkNGzaEo6Mjhg0bhvT0dINzpKSkYODAgXBwcICnpydmzZqF0tJSgzp79+5Fp06doFKp0KxZM6xdu7Ymmmc0Ds8RERHJr9bfhdu2bYvU1FRpO3DggFQ2ffp0/Pzzz9i0aRP27duH69evY+jQoVK5TqfDwIEDUVxcjLi4OKxbtw5r167FG2+8IdVJTk7GwIED0bdvXyQkJGDatGmYMGECduzYUaPtvBNOBCciIpKfjdwB3I2NjQ28vb0r7NdoNPjyyy+xYcMGPPTQQwCANWvWoHXr1jh48CC6d++OnTt34vTp09i1axe8vLzQoUMHLFq0CHPmzMGCBQugVCqxevVqBAUFYcWKFQCA1q1b48CBA1i5ciUiIiJqtK1VKV9ygMNzRERE8qn1PU3nzp2Dr68vmjRpglGjRiElJQUAcOTIEZSUlCA8PFyq26pVK/j7+yM+Ph4AEB8fj+DgYHh5eUl1IiIioNVqcerUKanO7ecor1N+jqoUFRVBq9UabNVFx+E5IiIi2dXqu3BoaCjWrl2LX3/9FatWrUJycjJ69uyJnJwcpKWlQalUwsXFxeAYLy8vpKWlAQDS0tIMEqby8vKyO9XRarUoKCioMrbo6Gg4OztLm5+f3/02t0rSRHAOzxEREcmmVg/PDRgwQPq5ffv2CA0NRUBAADZu3Ah7e3sZIwOioqIwY8YM6bNWq622xElacoDDc0RERLKp1T1N/+bi4oIWLVrg/Pnz8Pb2RnFxMbKzsw3qpKenS3OgvL29KzxNV/75bnXUavUdEzOVSgW1Wm2wVQe9XuDv0TnY8N1zREREsrGou3Bubi4uXLgAHx8fdO7cGba2toiNjZXKk5KSkJKSgrCwMABAWFgYTp48iYyMDKlOTEwM1Go12rRpI9W5/RzldcrPIbfy5QYAvnuOiIhITrU6aXr11Vexb98+XLp0CXFxcRgyZAisra0xYsQIODs7Y/z48ZgxYwb27NmDI0eOYOzYsQgLC0P37t0BAP3790ebNm3w7LPP4vjx49ixYwdef/11TJ48GSqVCgAwadIkXLx4EbNnz8bZs2fxySefYOPGjZg+fbqcTZeUD80BHJ4jIiKSU62e03T16lWMGDECmZmZ8PDwQI8ePXDw4EF4eHgAAFauXAkrKysMGzYMRUVFiIiIwCeffCIdb21tja1bt+LFF19EWFgYGjRogNGjR+PNN9+U6gQFBWHbtm2YPn063n//fTRu3BhffPFFrVlu4PaeJk4EJyIiko9CCCHuXo3uRqvVwtnZGRqNxqzzm7LyitFpUQwA4MLiRzhER0REZEam3L9r9fAc/TM8p1BwThMREZGcmDTVcnxZLxERUe3ApKmW42rgREREtQPvxLUc3ztHRERUOzBpquWkniY+OUdERCQrJk21XMnfc5qsOTxHREQkK96Ja7nyniZb9jQRERHJiklTLVfy95IDXG6AiIhIXkyaarl/epr4VREREcmJd+JarvzpOfY0ERERyYtJUy33zzpNTJqIiIjkxKSplpNWBOdEcCIiIlkxaarlSrkiOBERUa3AO3EtV8oVwYmIiGoFJk21XClXBCciIqoVmDRZAHtba9jZWssdBhERUb1mI3cAdGeDQnwxKMRX7jCIiIjqPfY0ERERERmBSRMRERGREZg0ERERERmBSRMRERGREZg0ERERERmBSRMRERGREZg0ERERERmBSRMRERGREZg0ERERERmBSRMRERGREZg0ERERERmBSRMRERGREZg0ERERERmBSRMRERGREWzkDqCuEEIAALRarcyREBERkbHK79vl9/E7YdJkJjk5OQAAPz8/mSMhIiIiU+Xk5MDZ2fmOdRTCmNSK7kqv1+P69etwcnKCQqEw67m1Wi38/Pxw5coVqNVqs567NmO72e66rj62GWC72e7aRQiBnJwc+Pr6wsrqzrOW2NNkJlZWVmjcuHG1XkOtVtfKP7jqxnbXL/Wx3fWxzQDbXd/U5nbfrYepHCeCExERERmBSRMRERGREZg0WQCVSoX58+dDpVLJHUqNYrvZ7rquPrYZYLvZbsvFieBERERERmBPExEREZERmDQRERERGYFJExEREZERmDQRERERGYFJUy338ccfIzAwEHZ2dggNDcUff/whd0hmtWDBAigUCoOtVatWUnlhYSEmT56Mhg0bwtHREcOGDUN6erqMEd+b/fv3Y9CgQfD19YVCocCPP/5oUC6EwBtvvAEfHx/Y29sjPDwc586dM6iTlZWFUaNGQa1Ww8XFBePHj0dubm4NtsJ0d2v3mDFjKnz/kZGRBnUsrd3R0dHo2rUrnJyc4OnpicGDByMpKcmgjjF/1ykpKRg4cCAcHBzg6emJWbNmobS0tCabYhJj2t2nT58K3/ekSZMM6lhau1etWoX27dtLCzeGhYXhl19+kcrr4ncN3L3ddfG7Bpg01WrfffcdZsyYgfnz5+Po0aMICQlBREQEMjIy5A7NrNq2bYvU1FRpO3DggFQ2ffp0/Pzzz9i0aRP27duH69evY+jQoTJGe2/y8vIQEhKCjz/+uNLyZcuW4YMPPsDq1atx6NAhNGjQABER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",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "\n",
    "cumsum_regret = np.cumsum(regret)\n",
    "plt.plot(cumsum_regret)\n",
    "plt.xlabel(\"Round\")\n",
    "plt.ylabel(\"Cumulative Regret\")\n",
    "plt.title(f\"Regret goes to {cumsum_regret[-1]:0.1f}\")\n",
    "\n",
    "summary_of_regrets = {\"Regret without drift (and no decay)\": cumsum_regret[-1]}"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Because we chose a linear demand function, we know for a fact that the $17 price is optimal for all cities. We can see that the agent's learned expected reward per city for the $17 price is very close to the true maximum reward.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([ 983.33767831,  585.41802181,  813.26334668,  923.8723854 ,\n",
       "        730.97890979,  983.68947051,  914.73678633, 1069.20311469,\n",
       "        991.20894353,  543.6045211 ])"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "agent.arm(Price.price_17).learner.coef_[0] + agent.arm(Price.price_17).learner.coef_[1:]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([ 983.66025439,  584.58922102,  813.11095419,  924.02978011,\n",
       "        730.588562  ,  984.01212752,  914.86917212, 1069.7657688 ,\n",
       "        991.55338423,  542.53651526])"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "best_price_per_city"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "While that was a fun simulation, it's not very realistic. In reality, demand changes over time. Let's simulate that by making the demand for each city a step function with some drift (given by the the `adjust_demand` method above). This is still fairly unrealistic, but we can use this setting to see how the agent performs when the demand is non-stationary.\n",
    "\n",
    "We'll define some helper functions to focus on the most interesting part of the simulation.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "def build_contextual_agent(\n",
    "    policy, prior_mean: np.ndarray = np.array([1000] + [0] * 10), random_seed: int = 111\n",
    ") -> ContextualAgent:\n",
    "    return ContextualAgent(\n",
    "        arms=[\n",
    "            Arm(\n",
    "                Price.price_5,\n",
    "                learner=NormalInverseGammaRegressor(mu=prior_mean),\n",
    "            ),\n",
    "            Arm(\n",
    "                Price.price_8,\n",
    "                learner=NormalInverseGammaRegressor(mu=prior_mean),\n",
    "            ),\n",
    "            Arm(\n",
    "                Price.price_11,\n",
    "                learner=NormalInverseGammaRegressor(mu=prior_mean),\n",
    "            ),\n",
    "            Arm(\n",
    "                Price.price_14,\n",
    "                learner=NormalInverseGammaRegressor(mu=prior_mean),\n",
    "            ),\n",
    "            Arm(\n",
    "                Price.price_17,\n",
    "                learner=NormalInverseGammaRegressor(mu=prior_mean),\n",
    "            ),\n",
    "        ],\n",
    "        policy=policy,\n",
    "        random_seed=random_seed,\n",
    "    )\n",
    "\n",
    "\n",
    "def compute_best_price_per_city(oracle: GeographicPricing) -> np.ndarray:\n",
    "    best_price_per_city = np.array(\n",
    "        [\n",
    "            [oracle.margin(location, price.value) for price in Price]\n",
    "            for location in range(10)\n",
    "        ]\n",
    "    ).max(axis=1)\n",
    "\n",
    "    return best_price_per_city"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "agent = build_contextual_agent(policy=policy)\n",
    "\n",
    "np.random.seed(2)\n",
    "one_hot_encoding = np.append(np.ones((10, 1)), np.eye(10), axis=-1)\n",
    "\n",
    "oracle.reset_demand()\n",
    "regret: list[float] = []\n",
    "\n",
    "for iteration in range(1000):\n",
    "    # Start of each week, randomly adjust demand\n",
    "    if iteration % 7 == 0:\n",
    "        oracle.adjust_demand()\n",
    "\n",
    "    # Recompute best price per city\n",
    "    best_price_per_city = compute_best_price_per_city(oracle)\n",
    "\n",
    "    # Start of the day, adjust prices\n",
    "    decisions = agent.pull(one_hot_encoding)\n",
    "\n",
    "    # End of the day, collect rewards\n",
    "    rewards = [token.take_action(location) for location, token in enumerate(decisions)]\n",
    "    regret.append((best_price_per_city - np.array(rewards)).sum())\n",
    "\n",
    "    # Update the agent\n",
    "    for token, reward, context_row in zip(decisions, rewards, one_hot_encoding):\n",
    "        agent.select_for_update(token).update(\n",
    "            np.atleast_2d(context_row), np.atleast_1d(reward)\n",
    "        )"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, we see that the agent's performance is much worse. This is because the agent is not able to adapt to the changing demand. As we can see in the below plot, the agent begins to learn the true demand distribution, but then it changes, and the agent has already found a very narrow posterior distribution for the demand. Unfortunately, this posterior is out of date, so the agent will be slow to adapt.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "\n",
    "plt.plot(np.cumsum(regret))\n",
    "plt.xlabel(\"Round\")\n",
    "plt.ylabel(\"Cumulative Regret\")\n",
    "regret_without_decay = np.cumsum(regret)[-1]\n",
    "plt.title(f\"Regret goes to {regret_without_decay:0.1f}\")\n",
    "summary_of_regrets[\"Regret with drift and without decay\"] = regret_without_decay"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Instead, we can utilize the `Agent.decay` method to increase the variance of our posterior distributions, thereby encouraging the agent to maintain a baseline level of exploration. The choice of `decay_rate` is arbitrary, it is essentially an exponential decay rate that increases the variance of the posterior distributions. We can see that this helps the agent adapt to the changing demand. However, decaying too often can prevent the agent from ever learning how to maximize the reward.\n",
    "\n",
    "We will write a function to run the whole simulation so we can then tune the `decay_rate` hyperparameter. We'll start with `decay_rate` = 0.999 just to see how it goes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "def run_decay_simulation(decay_rate: float, oracle: GeographicPricing) -> list[float]:\n",
    "    np.random.seed(2)\n",
    "\n",
    "    oracle.reset_demand()\n",
    "\n",
    "    agent = build_contextual_agent(policy=policy)\n",
    "\n",
    "    one_hot_encoding = np.append(np.ones((10, 1)), np.eye(10), axis=-1)\n",
    "\n",
    "    regret: list[float] = []\n",
    "\n",
    "    for iteration in range(1000):\n",
    "        # Start of each week, randomly adjust demand\n",
    "        if iteration % 7 == 0:\n",
    "            oracle.adjust_demand()\n",
    "\n",
    "        # Recompute best price per city\n",
    "        best_price_per_city = compute_best_price_per_city(oracle)\n",
    "\n",
    "        # Start of the day, adjust prices\n",
    "        decisions = agent.pull(one_hot_encoding)\n",
    "\n",
    "        # End of the day, collect rewards\n",
    "        rewards = [\n",
    "            token.take_action(location) for location, token in enumerate(decisions)\n",
    "        ]\n",
    "        regret.append((best_price_per_city - np.array(rewards)).sum())\n",
    "\n",
    "        # Update the agent\n",
    "        for token, reward, context_row in zip(decisions, rewards, one_hot_encoding):\n",
    "            agent.select_for_update(token).update(\n",
    "                np.atleast_2d(context_row), np.atleast_1d(reward)\n",
    "            )\n",
    "\n",
    "        # End of each month, decay the bandit\n",
    "        if iteration % 30 == 0:\n",
    "            agent.decay(one_hot_encoding[0], decay_rate=decay_rate)\n",
    "\n",
    "    return regret\n",
    "\n",
    "\n",
    "regret = run_decay_simulation(0.999, oracle)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this case, we can see that the agent is able to keep up with the changing demand, but that does not necessarily result in lower cumulative regret. This is because the agent is exploring more, and therefore choosing suboptimal prices more often. \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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X3/9NZo1a4b169ejTZs25X7WwsICQgidsvz8/BL1rK2tdd7LZDJoNJoniJqIzBWH54ioWrCwsMC7776L2bNno06dOpDL5Th27Ji0PT8/H6dOnULjxo0BAO7u7sjIyEBWVpZUJyYmxqB91qlTB9bW1jh58qRUlpaWhitXrjzZwRCRSTBpIqJqY+DAgbC0tMTq1avx5ptvYvr06dizZw8uX76MMWPG4MGDBwgPDwcAtGvXDnZ2dnj33Xdx/fp1bN26FRs3bjRofw4ODggPD8f06dNx4MABXLx4ESNHjoSFBf/0ElVFHJ4jomrDysoKEyZMwOLFixEfHw+NRoNhw4YhIyMDrVu3xt69e+Hi4gKgaO7RN998g+nTp2Pt2rXo3r075s2bh7Fjxxq0zyVLliAzMxN9+vSBo6Mj3n77bahUqoo4PCKqYDLx70F7IiIiIiqBfcREREREemDSRERERKQHJk1EREREemDSRERERKQHJk1EREREemDSRERERKQHJk1EREREemDSRERERKQHJk1EREREemDSRERERKQHJk1EREREemDSRERERKSH/weLAHkwD5sDvAAAAABJRU5ErkJggg==",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "plt.plot(np.cumsum(regret))\n",
    "zero_ninety_eight_decay_regret = np.cumsum(regret)[-1]\n",
    "plt.xlabel(\"Round\")\n",
    "plt.ylabel(\"Cumulative Regret\")\n",
    "plt.title(f\"Cumulative regret for 0.999 decay: {zero_ninety_eight_decay_regret:0.1f}\")\n",
    "summary_of_regrets[\"Regret with drift and a 0.999 decay rate\"] = (\n",
    "    zero_ninety_eight_decay_regret\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we'll optimize the `decay_rate` hyperparameter using `optuna`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "import optuna\n",
    "\n",
    "optuna.logging.set_verbosity(optuna.logging.WARNING)\n",
    "\n",
    "\n",
    "def objective(trial: optuna.Trial):\n",
    "    np.random.seed(3)\n",
    "    decay_rate = trial.suggest_float(\"decay_rate\", 0.95, 1.0)\n",
    "    regret = run_decay_simulation(decay_rate, oracle)\n",
    "    return np.cumsum(regret)[-1]\n",
    "\n",
    "\n",
    "study = optuna.create_study(direction=\"minimize\")\n",
    "study.optimize(objective, n_trials=50)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "({'decay_rate': 0.997843414009486}, 22657.478449147064)"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# In case you want to get the whole regret array:\n",
    "# optimal_decay = study.best_params['decay_rate']\n",
    "# optimal_decay_regret = run_decay_simulation(decay_rate=optimal_decay, oracle=oracle)\n",
    "\n",
    "summary_of_regrets[\"Regret with drift and optimal decay rate\"] = study.best_value\n",
    "\n",
    "study.best_params, study.best_value"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To show how a bad decay rate can hurt us, we'll also record the worst value obtained from the optuna trials.\n",
    "In this case, the worst decay rate is near 0.9, which shows that too much decay can be worse than no decay at all."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Worst decay rate: 0.964\n"
     ]
    }
   ],
   "source": [
    "worst_trial = np.argmax([trial.values[0] for trial in study.trials])\n",
    "worst_decay_rate = study.trials[worst_trial].params[\"decay_rate\"]\n",
    "summary_of_regrets[\"Regret with drift and worst decay rate\"] = study.trials[\n",
    "    worst_trial\n",
    "].values[0]\n",
    "print(f\"Worst decay rate: {worst_decay_rate:0.3f}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Below is a table summary of the five different scenarios / strategies that we tried.\n",
    "As with many hyperparameters, choosing the right one can help us, but choosing the wrong one can hurt us. In this case, the worst decay rate gives much worse results than the case without any sort of decay.\n",
    "\n",
    "Note that there is a lot of variation between runs. If we wanted to deploy a strategy, we should run multiple runs with each strategy to verify the distribution of the results (check the median and some other percentiles)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Strategy                                  Regret\n",
      "--------------------------------------------------\n",
      "Regret without drift (and no decay)      21751.4\n",
      "Regret with drift and without decay      48109.2\n",
      "Regret with drift and a 0.999 decay rate      21433.8\n",
      "Regret with drift and optimal decay rate      22657.5\n",
      "Regret with drift and worst decay rate     303682.4\n",
      "--------------------------------------------------\n"
     ]
    }
   ],
   "source": [
    "print(f\"{'Strategy':<35} {'Regret':>12}\")\n",
    "print(\"-\" * 50)\n",
    "for strategy, regret in summary_of_regrets.items():\n",
    "    print(f\"{strategy:<35} {regret:>12.1f}\")\n",
    "print(\"-\" * 50)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "bayesianbandits",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.16"
  },
  "orig_nbformat": 4
 },
 "nbformat": 4,
 "nbformat_minor": 2
}