├── 00-q-learning.ipynb ├── 01-dqn.ipynb ├── 02-policy-gradient.ipynb ├── 03-actor-critic.ipynb ├── 04-ppo.ipynb ├── 05-ddpg.ipynb ├── 06-sac.ipynb ├── Readme.md ├── assets ├── cart-pole.png ├── discretize.png ├── dqn-2-networks.png ├── policy.png ├── q-network.png └── q-table.png └── util └── cartpole.py /00-q-learning.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "id": "pleasant-witch", 6 | "metadata": {}, 7 | "source": [ 8 | "# Q-Learning in Reinforcement Learning\n", 9 | "\n", 10 | "Q-Learning is most primitive, but big part of algorithms to learn reinforcement learning.\n", 11 | "\n", 12 | "In order to understand how it works, first let's consider the expected rewards as follows.\n", 13 | "\n", 14 | "$$ R = \\sum_{t=0}^{\\infty} {\\gamma^t r_t} $$\n", 15 | "\n", 16 | "where $r_t$ is a reward value obtained at $t$ and $\\gamma$ is discount.\n", 17 | "\n", 18 | "For instance, when you try to grab an object, you will do the following 3 actions :\n", 19 | "\n", 20 | "- action #1 : Stretch your arm ($t=0$)
\n", 21 | " Getting reward 0.\n", 22 | "- action #2 : Open your hand ($t=1$)
\n", 23 | " Getting reward 0.\n", 24 | "- action #3 : Grab an object ($t=2$)
\n", 25 | " Getting reward 10.\n", 26 | "\n", 27 | "In this case, you will get a reward value 10 on action #3 ($t=2$), however the action #1 ($t=0$) is obviously contributing to the final rewards. Hence, we consider that the action #1 will have the following expected cumulative reward.
\n", 28 | "Here we assume $\\gamma$ is 0.99.\n", 29 | "\n", 30 | "$$ R_{t=0} = 0 + 0.99 \\times 0 + 0.99^2 \\times 10 = 9.801 $$\n", 31 | "\n", 32 | "Same as above, $R_{t=1} = 9.9, R_{t=2} = 10$.\n", 33 | "\n", 34 | "Q-value is based on this idea of expected cumulative reward. Depending on each state (observation), the each action will have the corresponding expected reward.
\n", 35 | "In above example, if you see an object in front of you (i.e, the **state** of \"you see an object\"), the **action** \"stretching your arm\" will have high value of expected reward. However, if you cannot see an object anywhere, the action \"stretching your arm\" will have low value of expected reward.\n", 36 | "\n", 37 | "Q-value of each corresponding state and action is denoted as $Q(s, a)$. Suppose both action and state has 1 dimension of discrete values, $Q(s, a)$ will be written as a table (called Q-Table) as follows.
\n", 38 | "If the state is s2, the optimal action to pick up will be action a2. If s3, the optimal action will be action a4.\n", 39 | "\n", 40 | "![Q-Table](assets/q-table.png)\n", 41 | "\n", 42 | "In practice, both action space and observation space may have more than 1 dimension. For instance, in CartPole example (below example), the returned state (observation) has 4 elements of float values, i.e, 4 dimensions. (See [readme.md](https://github.com/tsmatz/reinforcement-learning-tutorials/) for CartPole.) Then Q-Table will be the combination of 1 dimension (action space) and 4 dimension (observation space).\n", 43 | "\n", 44 | "In Q-Learning, we optimize this table by the following iterative updates ($t=0,1,2,\\ldots$).
\n", 45 | "In the following equation, $ Q_t(s_t,a_t) $ is current Q-value and $ Q_{t+1}(s_t,a_t) $ is the updated Q-value.\n", 46 | "\n", 47 | "$$ Q_{t+1}(s_t,a_t) = Q_t(s_t,a_t) + \\alpha \\left( r_t + \\gamma \\max_a{Q_t(s_{t+1},a)} - Q_t(s_t,a_t) \\right) $$\n", 48 | "\n", 49 | "where $\\alpha$ is learning rate.\n", 50 | "\n", 51 | "This equation means that :\n", 52 | "\n", 53 | "- Suppose, you executed an action $a_t$ on state $s_t$, and as a result, you got reward $r_t$ and the state has changed to $s_{t+1}$.\n", 54 | "- The optimal next action will satisfy $a_{t+1}=\\max_{a}{Q(s_{t+1},a)}$.
\n", 55 | " By taking this optimal action, you will then get the expected reward : $r_t + \\gamma \\max_{a}{Q(s_{t+1},a)}$.\n", 56 | "- Compare this optimal q-value with current q-value $Q(s_t,a_t)$ in q-table. Then update this current value $Q(s_t,a_t)$ by learning rate $\\alpha$.
\n", 57 | " This will result into above equation.\n", 58 | "\n", 59 | "Now let's build this Python example with CartPole environment. (See [readme.md](https://github.com/tsmatz/reinforcement-learning-tutorials/) about CartPole.)\n", 60 | "\n", 61 | "*(back to [index](https://github.com/tsmatz/reinforcement-learning-tutorials/))*" 62 | ] 63 | }, 64 | { 65 | "cell_type": "markdown", 66 | "id": "terminal-minute", 67 | "metadata": {}, 68 | "source": [ 69 | "First, please install the required packages and import these modules." 70 | ] 71 | }, 72 | { 73 | "cell_type": "code", 74 | "execution_count": null, 75 | "id": "promotional-portfolio", 76 | "metadata": {}, 77 | "outputs": [], 78 | "source": [ 79 | "!pip install numpy gymnasium matplotlib" 80 | ] 81 | }, 82 | { 83 | "cell_type": "code", 84 | "execution_count": 1, 85 | "id": "creative-chess", 86 | "metadata": {}, 87 | "outputs": [], 88 | "source": [ 89 | "import gymnasium as gym\n", 90 | "import numpy as np" 91 | ] 92 | }, 93 | { 94 | "cell_type": "markdown", 95 | "id": "together-perspective", 96 | "metadata": {}, 97 | "source": [ 98 | "CartPole has 4 elements of continuos (float) observation space. In order for applying primitive Q-Learning, we should convert continuous state to discrete state (i.e, **discretize**).
\n", 99 | "In this example, we will convert Tuple(Box, Box, Box, Box) into Tuple(Discrete(20), Discrete(20), Discrete(20), Discrete(20)) - which converts float value to the bin of value for each segment.\n", 100 | "\n", 101 | "![discretize](assets/discretize.png)" 102 | ] 103 | }, 104 | { 105 | "cell_type": "code", 106 | "execution_count": 2, 107 | "id": "honey-house", 108 | "metadata": {}, 109 | "outputs": [ 110 | { 111 | "name": "stdout", 112 | "output_type": "stream", 113 | "text": [ 114 | "[-4.32000017 -3.84000015 -3.36000013 -2.88000011 -2.4000001 -1.92000008\n", 115 | " -1.44000006 -0.96000004 -0.48000002 0. 0.48000002 0.96000004\n", 116 | " 1.44000006 1.92000008 2.4000001 2.88000011 3.36000013 3.84000015\n", 117 | " 4.32000017]\n", 118 | "[-3.6 -3.2 -2.8 -2.4 -2. -1.6 -1.2 -0.8 -0.4 0. 0.4 0.8 1.2 1.6\n", 119 | " 2. 2.4 2.8 3.2 3.6]\n", 120 | "[-0.37699113 -0.33510323 -0.29321532 -0.25132742 -0.20943952 -0.16755161\n", 121 | " -0.12566371 -0.08377581 -0.0418879 0. 0.0418879 0.08377581\n", 122 | " 0.12566371 0.16755161 0.20943952 0.25132742 0.29321532 0.33510323\n", 123 | " 0.37699113]\n", 124 | "[-3.6 -3.2 -2.8 -2.4 -2. -1.6 -1.2 -0.8 -0.4 0. 0.4 0.8 1.2 1.6\n", 125 | " 2. 2.4 2.8 3.2 3.6]\n" 126 | ] 127 | } 128 | ], 129 | "source": [ 130 | "import math\n", 131 | "\n", 132 | "env = gym.make(\"CartPole-v1\")\n", 133 | "\n", 134 | "new_observation_shape = (20, 20, 20, 20)\n", 135 | "\n", 136 | "bins = []\n", 137 | "for i in range(4):\n", 138 | " item = np.linspace(\n", 139 | " env.observation_space.low[i] if (i == 0) or (i == 2) else -4,\n", 140 | " env.observation_space.high[i] if (i == 0) or (i == 2) else 4,\n", 141 | " num=new_observation_shape[i],\n", 142 | " endpoint=False)\n", 143 | " item = np.delete(item, 0)\n", 144 | " bins.append(item)\n", 145 | " print(bins[i])\n", 146 | "\n", 147 | "# define function to convert to discrete state\n", 148 | "def get_discrete_state(s):\n", 149 | " new_s = []\n", 150 | " for i in range(4):\n", 151 | " new_s.append(np.digitize(s[i], bins[i]))\n", 152 | " return new_s" 153 | ] 154 | }, 155 | { 156 | "cell_type": "markdown", 157 | "id": "ignored-cincinnati", 158 | "metadata": {}, 159 | "source": [ 160 | "Now we generate Q-Table $Q(s,a)$ and initialize all values by 0. (Here it's 5 dimensional table.)" 161 | ] 162 | }, 163 | { 164 | "cell_type": "code", 165 | "execution_count": 3, 166 | "id": "needed-communications", 167 | "metadata": {}, 168 | "outputs": [ 169 | { 170 | "data": { 171 | "text/plain": [ 172 | "(20, 20, 20, 20, 2)" 173 | ] 174 | }, 175 | "execution_count": 3, 176 | "metadata": {}, 177 | "output_type": "execute_result" 178 | } 179 | ], 180 | "source": [ 181 | "q_table = np.zeros(new_observation_shape + (env.action_space.n,))\n", 182 | "q_table.shape" 183 | ] 184 | }, 185 | { 186 | "cell_type": "markdown", 187 | "id": "julian-sacrifice", 188 | "metadata": {}, 189 | "source": [ 190 | "Now, update Q-Table with above Q-Learning algorithm.\n", 191 | "\n", 192 | "However, in the beginning, Q-Table was initialized all by zeros (not optimized at all) and will always pick up wrong actions. Therefore, the action is randomly picked up to explore in the first stage, and when it grows to learn, it then picks up the optimal actions with Q-Table gradually using the following coefficient parameter $\\epsilon$ to control. (This exploration algorithm is called **Epsilon-Greedy**.)" 193 | ] 194 | }, 195 | { 196 | "cell_type": "code", 197 | "execution_count": 4, 198 | "id": "fitted-torture", 199 | "metadata": {}, 200 | "outputs": [ 201 | { 202 | "name": "stdout", 203 | "output_type": "stream", 204 | "text": [ 205 | "Run episode5999 with rewards 500.0\n", 206 | "Done\n" 207 | ] 208 | } 209 | ], 210 | "source": [ 211 | "gamma = 0.99\n", 212 | "alpha = 0.1\n", 213 | "epsilon = 1\n", 214 | "epsilon_decay = epsilon / 4000\n", 215 | "\n", 216 | "# pick up action from q-table with greedy exploration\n", 217 | "def pick_sample(s, epsilon):\n", 218 | " # get optimal action,\n", 219 | " # but with greedy exploration (to prevent picking up same values in the first stage)\n", 220 | " if np.random.random() > epsilon:\n", 221 | " a = np.argmax(q_table[tuple(s)])\n", 222 | " else:\n", 223 | " a = np.random.randint(0, env.action_space.n)\n", 224 | " return a\n", 225 | "\n", 226 | "env = gym.make(\"CartPole-v1\")\n", 227 | "reward_records = []\n", 228 | "for i in range(6000):\n", 229 | " # Run episode till done\n", 230 | " done = False\n", 231 | " total_reward = 0\n", 232 | " s, _ = env.reset()\n", 233 | " s_dis = get_discrete_state(s)\n", 234 | " while not done:\n", 235 | " a = pick_sample(s_dis, epsilon)\n", 236 | " s, r, term, trunc, _ = env.step(a)\n", 237 | " done = term or trunc\n", 238 | " s_dis_next = get_discrete_state(s)\n", 239 | "\n", 240 | " # Update Q-Table\n", 241 | " maxQ = np.max(q_table[tuple(s_dis_next)])\n", 242 | " q_table[tuple(s_dis)][a] += alpha * (r + gamma * maxQ - q_table[tuple(s_dis)][a])\n", 243 | "\n", 244 | " s_dis = s_dis_next\n", 245 | " total_reward += r\n", 246 | "\n", 247 | " # Update epsilon for each episode\n", 248 | " if epsilon - epsilon_decay >= 0:\n", 249 | " epsilon -= epsilon_decay\n", 250 | "\n", 251 | " # Record total rewards in episode (max 500)\n", 252 | " print(\"Run episode{} with rewards {}\".format(i, total_reward), end=\"\\r\")\n", 253 | " reward_records.append(total_reward)\n", 254 | "\n", 255 | "print(\"\\nDone\")\n", 256 | "env.close()" 257 | ] 258 | }, 259 | { 260 | "cell_type": "code", 261 | "execution_count": 5, 262 | "id": "12ac75ce", 263 | "metadata": {}, 264 | "outputs": [ 265 | { 266 | "data": { 267 | "text/plain": [ 268 | "[]" 269 | ] 270 | }, 271 | "execution_count": 5, 272 | "metadata": {}, 273 | "output_type": "execute_result" 274 | }, 275 | { 276 | "data": { 277 | "image/png": "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\n", 278 | "text/plain": [ 279 | "
" 280 | ] 281 | }, 282 | "metadata": {}, 283 | "output_type": "display_data" 284 | } 285 | ], 286 | "source": [ 287 | "import matplotlib.pyplot as plt\n", 288 | "# Generate recent 50 interval average\n", 289 | "average_reward = []\n", 290 | "for idx in range(len(reward_records)):\n", 291 | " avg_list = np.empty(shape=(1,), dtype=int)\n", 292 | " if idx < 50:\n", 293 | " avg_list = reward_records[:idx+1]\n", 294 | " else:\n", 295 | " avg_list = reward_records[idx-49:idx+1]\n", 296 | " average_reward.append(np.average(avg_list))\n", 297 | "# Plot\n", 298 | "plt.plot(reward_records)\n", 299 | "plt.plot(average_reward)" 300 | ] 301 | }, 302 | { 303 | "cell_type": "markdown", 304 | "id": "lyric-butterfly", 305 | "metadata": {}, 306 | "source": [ 307 | "As you can see above, this method won't work in large continuous and stochastic spaces (e.g, continuos action space), since this method will need so many discrete mesh for solving problems.
\n", 308 | "In the next tutorial, we'll learn the idea of policy gradient methods, which will take effects in such a case." 309 | ] 310 | }, 311 | { 312 | "cell_type": "code", 313 | "execution_count": null, 314 | "id": "modified-champagne", 315 | "metadata": {}, 316 | "outputs": [], 317 | "source": [] 318 | } 319 | ], 320 | "metadata": { 321 | "kernelspec": { 322 | "display_name": "Python 3 (ipykernel)", 323 | "language": "python", 324 | "name": "python3" 325 | }, 326 | "language_info": { 327 | "codemirror_mode": { 328 | "name": "ipython", 329 | "version": 3 330 | }, 331 | "file_extension": ".py", 332 | "mimetype": "text/x-python", 333 | "name": "python", 334 | "nbconvert_exporter": "python", 335 | "pygments_lexer": "ipython3", 336 | "version": "3.12.3" 337 | } 338 | }, 339 | "nbformat": 4, 340 | "nbformat_minor": 5 341 | } 342 | -------------------------------------------------------------------------------- /03-actor-critic.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "id": "recent-bunch", 6 | "metadata": {}, 7 | "source": [ 8 | "# Actor-Critic Method in Reinforcement Learning\n", 9 | "\n", 10 | "Many successful algorithms in today's reinforcement learning (such as, PPO, SAC, etc) include the idea of dividing into value and advantage.
\n", 11 | "Now we improve the previous vanilla [on-policy learning](./02-policy-gradient.ipynb) architecture with this idea and see Actor-Critic architecture intuitively.
\n", 12 | "In this example, I'll explain about Advantage Actor-Critic (shortly, A2C) algorithm.\n", 13 | "\n", 14 | "> Note : The idea of dividing into value and advantage can be applied on many of algorithms including both on-policy and off-policy. See [DDPG](./05-ddpg.ipynb), which algorithm also divides into value and advantage in off-policy algorithm.\n", 15 | "\n", 16 | "Actor-Critic is the mixed approach on both value-based Q-Learning method and policy-based method.
\n", 17 | "As we saw in [Q-Learning](./00-q-learning.ipynb), it holds $ Q(s_t,a_t) = r_t + \\gamma \\max_a{Q_t(s_{t+1},a)} $.
\n", 18 | "As you know, $ \\max_a{Q_t(s_{t+1},a)} $ won't depend on action $ a $. Then we can denote $ Q(s_t,a_t) = r_t + \\gamma V(s_{t+1}) $ where $ V(s) $ only depends on state $ s $. This $ V(s) $ is called a value-function.\n", 19 | "\n", 20 | "Now we separate $ Q(s_t,a_t) $ into the following two parts :\n", 21 | "\n", 22 | "- one is potential value $ V(s_t) $ not depending on $ a_t $\n", 23 | "- the other part is $ A(a_t, s_t) $ (which is called **advantage**) depending on $ a_t $ in state $ s_t $.\n", 24 | "\n", 25 | "Then $ A(a_t, s_t) $ can be written as :\n", 26 | "\n", 27 | "$$ A(a_t, s_t) = r_t + \\gamma V(s_{t+1}) - V(s_t) $$\n", 28 | "\n", 29 | "In this method, we generate a value-function (which can also be implemented by neural networks) $ V(s) $ and apply policy gradient for an advantage-function $ A(a, s) $. We should then generate 2 functions - value function and policy function - and optimize parameters in these 2 functions.
\n", 30 | "Intuitively, the value function is optimized for the value estimation in each state, and the policy function is optimized to take an appropriate action in that state.\n", 31 | "\n", 32 | "Remind that we have applied gradient descent (ascent) on $ E\\left[\\sum{\\gamma r}\\right] $ in [vanilla on-policy learning](./02-policy-gradient.ipynb) (previous example). By applying policy gradient on the reduced $ A(a, s) $ instead of $ E\\left[\\sum{\\gamma r}\\right] $, we can expect the stable convergence in complex problems, compared with vanilla policy gradient.\n", 33 | "\n", 34 | "For instance, imagine that the reward becomes so large.
\n", 35 | "In this situation, value will become large, and the value loss will then be larger rather than policy loss.
\n", 36 | "However, if the network (function) of policy and value are separated, both parameters can be appropriately optimized in the training respectively. (When these are not separated, it could happen that the policy loss will be ignored because it's relatively small, and not optimized enough eventually.)
\n", 37 | "Even when sharing parameters in the network (function) between value and policy, you can adjust the ratio for policy loss and value loss in Actor-Critic method, and both can then be appropriately optimized.\n", 38 | "\n", 39 | "You can run Actor-Critic-based training on both batch processing and non-batch processing.
\n", 40 | "For instance, when you run optimization on each episode (as a batch), you can estimate advantage $ A_t $ with $ \\sum{\\gamma r} - V(s_t) $.
\n", 41 | "When it's in the middle of episode, you can estimate with $ r_{t} + \\gamma r_{t+1} + \\cdots + \\gamma^{T-1-t} r_{T-1} + \\gamma^{T-t} V(s_T) - V(s_t) $.\n", 42 | "\n", 43 | "> Note : This latter approach is known as **temporal difference (TD)** learning, and I don't cover this topic in this repository. (See [GAE (generalized advantage estimation)](https://arxiv.org/pdf/1506.02438) to get generalized advantages between bias and variance in TD learning.)\n", 44 | "\n", 45 | "*(back to [index](https://github.com/tsmatz/reinforcement-learning-tutorials/))*" 46 | ] 47 | }, 48 | { 49 | "cell_type": "markdown", 50 | "id": "following-cement", 51 | "metadata": {}, 52 | "source": [ 53 | "First, please install the required packages and import these modules." 54 | ] 55 | }, 56 | { 57 | "cell_type": "code", 58 | "execution_count": null, 59 | "id": "secure-latex", 60 | "metadata": {}, 61 | "outputs": [], 62 | "source": [ 63 | "!pip install torch numpy gymnasium matplotlib" 64 | ] 65 | }, 66 | { 67 | "cell_type": "code", 68 | "execution_count": 1, 69 | "id": "scenic-detective", 70 | "metadata": {}, 71 | "outputs": [], 72 | "source": [ 73 | "import gymnasium as gym\n", 74 | "import numpy as np\n", 75 | "import torch\n", 76 | "import torch.nn as nn\n", 77 | "from torch.nn import functional as F" 78 | ] 79 | }, 80 | { 81 | "cell_type": "markdown", 82 | "id": "engaged-chaos", 83 | "metadata": {}, 84 | "source": [ 85 | "The idea of Actor-Critic is similar to [policy gradient example](https://github.com/tsmatz/reinforcement-learning-tutorials/blob/master/02-policy-gradient.ipynb).
\n", 86 | "However, in Actor-Critic, we use a value function (the following ```ValueNet```) which estimates value (Q-value).\n", 87 | "\n", 88 | "In this example, we separate weight's parameters between policy network (actor) and value network.
\n", 89 | "However, you can also use shared network between policy and value. In that case, you should specify the ratio between policy loss and values loss.\n", 90 | "\n", 91 | "> In order to speed up learning, I have reduced the number of hidden neurons, compared with previous policy gradient example." 92 | ] 93 | }, 94 | { 95 | "cell_type": "code", 96 | "execution_count": 2, 97 | "id": "f9a3a9d5", 98 | "metadata": {}, 99 | "outputs": [], 100 | "source": [ 101 | "device = torch.device(\"cuda\" if torch.cuda.is_available() else \"cpu\")\n", 102 | "\n", 103 | "class ActorNet(nn.Module):\n", 104 | " def __init__(self, hidden_dim=16):\n", 105 | " super().__init__()\n", 106 | "\n", 107 | " self.hidden = nn.Linear(4, hidden_dim)\n", 108 | " self.output = nn.Linear(hidden_dim, 2)\n", 109 | "\n", 110 | " def forward(self, s):\n", 111 | " outs = self.hidden(s)\n", 112 | " outs = F.relu(outs)\n", 113 | " logits = self.output(outs)\n", 114 | " return logits\n", 115 | "\n", 116 | "class ValueNet(nn.Module):\n", 117 | " def __init__(self, hidden_dim=16):\n", 118 | " super().__init__()\n", 119 | "\n", 120 | " self.hidden = nn.Linear(4, hidden_dim)\n", 121 | " self.output = nn.Linear(hidden_dim, 1)\n", 122 | "\n", 123 | " def forward(self, s):\n", 124 | " outs = self.hidden(s)\n", 125 | " outs = F.relu(outs)\n", 126 | " value = self.output(outs)\n", 127 | " return value\n", 128 | "\n", 129 | "actor_func = ActorNet().to(device)\n", 130 | "value_func = ValueNet().to(device)" 131 | ] 132 | }, 133 | { 134 | "cell_type": "markdown", 135 | "id": "incident-completion", 136 | "metadata": {}, 137 | "source": [ 138 | "Now we optimize both policy gradient loss (following ```pi_loss```) and value loss (following ```vf_loss```) as follows.\n", 139 | "\n", 140 | "In this example,\n", 141 | "\n", 142 | "- I have separately optimized actor and critic with policy loss $ p $ (```pi_loss```) and value loss $ v $ (```vf_loss```) respectively. When they are shared, you should specify loss ratio $ 0 \\lt \\rho \\lt 1$ by computing $ (1-\\rho) p + \\rho v $.\n", 143 | "- I have simply used cumulative rewards $\\sum{\\gamma r}$ as an estimated value in batch. (When it's in the middle of episode, you can also use $ r_{t} + \\gamma V(s_{t+1}) $ instead. See above note for TD approach.)\n", 144 | "\n", 145 | "> Note : The log probability is equivalent to the negative value of cross-entropy error in categorical distribution. Same like [policy gradient example](https://github.com/tsmatz/reinforcement-learning-tutorials/blob/master/02-policy-gradient.ipynb), I have used ```-torch.nn.functional.cross_entropy()``` to get log probability in the following code." 146 | ] 147 | }, 148 | { 149 | "cell_type": "code", 150 | "execution_count": 3, 151 | "id": "sublime-basin", 152 | "metadata": {}, 153 | "outputs": [ 154 | { 155 | "name": "stdout", 156 | "output_type": "stream", 157 | "text": [ 158 | "Run episode1052 with rewards 500.0\n", 159 | "Done\n" 160 | ] 161 | } 162 | ], 163 | "source": [ 164 | "gamma = 0.99\n", 165 | "\n", 166 | "# pick up action with above distribution policy_pi\n", 167 | "def pick_sample(s):\n", 168 | " with torch.no_grad():\n", 169 | " # --> size : (1, 4)\n", 170 | " s_batch = np.expand_dims(s, axis=0)\n", 171 | " s_batch = torch.tensor(s_batch, dtype=torch.float).to(device)\n", 172 | " # Get logits from state\n", 173 | " # --> size : (1, 2)\n", 174 | " logits = actor_func(s_batch)\n", 175 | " # --> size : (2)\n", 176 | " logits = logits.squeeze(dim=0)\n", 177 | " # From logits to probabilities\n", 178 | " probs = F.softmax(logits, dim=-1)\n", 179 | " # Pick up action's sample\n", 180 | " a = torch.multinomial(probs, num_samples=1)\n", 181 | " # Return\n", 182 | " return a.tolist()[0]\n", 183 | "\n", 184 | "env = gym.make(\"CartPole-v1\")\n", 185 | "reward_records = []\n", 186 | "opt1 = torch.optim.AdamW(value_func.parameters(), lr=0.001)\n", 187 | "opt2 = torch.optim.AdamW(actor_func.parameters(), lr=0.001)\n", 188 | "for i in range(1500):\n", 189 | " #\n", 190 | " # Run episode till done\n", 191 | " #\n", 192 | " done = False\n", 193 | " states = []\n", 194 | " actions = []\n", 195 | " rewards = []\n", 196 | " s, _ = env.reset()\n", 197 | " while not done:\n", 198 | " states.append(s.tolist())\n", 199 | " a = pick_sample(s)\n", 200 | " s, r, term, trunc, _ = env.step(a)\n", 201 | " done = term or trunc\n", 202 | " actions.append(a)\n", 203 | " rewards.append(r)\n", 204 | "\n", 205 | " #\n", 206 | " # Get cumulative rewards\n", 207 | " #\n", 208 | " cum_rewards = np.zeros_like(rewards)\n", 209 | " reward_len = len(rewards)\n", 210 | " for j in reversed(range(reward_len)):\n", 211 | " cum_rewards[j] = rewards[j] + (cum_rewards[j+1]*gamma if j+1 < reward_len else 0)\n", 212 | "\n", 213 | " #\n", 214 | " # Train (optimize parameters)\n", 215 | " #\n", 216 | "\n", 217 | " # Optimize value loss (Critic)\n", 218 | " opt1.zero_grad()\n", 219 | " states = torch.tensor(states, dtype=torch.float).to(device)\n", 220 | " cum_rewards = torch.tensor(cum_rewards, dtype=torch.float).to(device)\n", 221 | " values = value_func(states)\n", 222 | " values = values.squeeze(dim=1)\n", 223 | " vf_loss = F.mse_loss(\n", 224 | " values,\n", 225 | " cum_rewards,\n", 226 | " reduction=\"none\")\n", 227 | " vf_loss.sum().backward()\n", 228 | " opt1.step()\n", 229 | "\n", 230 | " # Optimize policy loss (Actor)\n", 231 | " with torch.no_grad():\n", 232 | " values = value_func(states)\n", 233 | " opt2.zero_grad()\n", 234 | " actions = torch.tensor(actions, dtype=torch.int64).to(device)\n", 235 | " advantages = cum_rewards - values\n", 236 | " logits = actor_func(states)\n", 237 | " log_probs = -F.cross_entropy(logits, actions, reduction=\"none\")\n", 238 | " pi_loss = -log_probs * advantages\n", 239 | " pi_loss.sum().backward()\n", 240 | " opt2.step()\n", 241 | "\n", 242 | " # Output total rewards in episode (max 500)\n", 243 | " print(\"Run episode{} with rewards {}\".format(i, sum(rewards)), end=\"\\r\")\n", 244 | " reward_records.append(sum(rewards))\n", 245 | "\n", 246 | " # stop if reward mean > 475.0\n", 247 | " if np.average(reward_records[-50:]) > 475.0:\n", 248 | " break\n", 249 | "\n", 250 | "print(\"\\nDone\")\n", 251 | "env.close()" 252 | ] 253 | }, 254 | { 255 | "cell_type": "code", 256 | "execution_count": 4, 257 | "id": "every-appointment", 258 | "metadata": {}, 259 | "outputs": [ 260 | { 261 | "data": { 262 | "text/plain": [ 263 | "[]" 264 | ] 265 | }, 266 | "execution_count": 4, 267 | "metadata": {}, 268 | "output_type": "execute_result" 269 | }, 270 | { 271 | "data": { 272 | "image/png": "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\n", 273 | "text/plain": [ 274 | "
" 275 | ] 276 | }, 277 | "metadata": {}, 278 | "output_type": "display_data" 279 | } 280 | ], 281 | "source": [ 282 | "import matplotlib.pyplot as plt\n", 283 | "# Generate recent 50 interval average\n", 284 | "average_reward = []\n", 285 | "for idx in range(len(reward_records)):\n", 286 | " avg_list = np.empty(shape=(1,), dtype=int)\n", 287 | " if idx < 50:\n", 288 | " avg_list = reward_records[:idx+1]\n", 289 | " else:\n", 290 | " avg_list = reward_records[idx-49:idx+1]\n", 291 | " average_reward.append(np.average(avg_list))\n", 292 | "plt.plot(reward_records)\n", 293 | "plt.plot(average_reward)" 294 | ] 295 | }, 296 | { 297 | "cell_type": "code", 298 | "execution_count": null, 299 | "id": "designing-three", 300 | "metadata": {}, 301 | "outputs": [], 302 | "source": [] 303 | } 304 | ], 305 | "metadata": { 306 | "kernelspec": { 307 | "display_name": "Python 3 (ipykernel)", 308 | "language": "python", 309 | "name": "python3" 310 | }, 311 | "language_info": { 312 | "codemirror_mode": { 313 | "name": "ipython", 314 | "version": 3 315 | }, 316 | "file_extension": ".py", 317 | "mimetype": "text/x-python", 318 | "name": "python", 319 | "nbconvert_exporter": "python", 320 | "pygments_lexer": "ipython3", 321 | "version": "3.12.3" 322 | } 323 | }, 324 | "nbformat": 4, 325 | "nbformat_minor": 5 326 | } 327 | -------------------------------------------------------------------------------- /04-ppo.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "id": "recent-bunch", 6 | "metadata": {}, 7 | "source": [ 8 | "# PPO (Proximal Policy Optimization)\n", 9 | "\n", 10 | "Proximal Policy Optimization (PPO) is one of successful algorithms in today's reinforcement learning.\n", 11 | "\n", 12 | "PPO is an algorithm that optimizes stochastic policy in on-policy way. However, in order to avoid the loss of performance, PPO algorithm prevents the update from stepping so far.
\n", 13 | "To prevent large updates in PPO algorithm, there are two variants: PPO-Penalty and PPO-Clip. In this example, we'll focus on PPO-Penalty which is widely used in practical works.\n", 14 | "\n", 15 | "> Note : The idea of PPO-Clip is more simple rather than PPO-Penalty. PPO-Clip limits the update by just clipping with $ \\epsilon $.
\n", 16 | "> For details about PPO-Clip, see [OpenAI document](https://spinningup.openai.com/en/latest/algorithms/ppo.html).\n", 17 | "\n", 18 | "As you saw in [Actor-Critic method](https://github.com/tsmatz/reinforcement-learning-tutorials/blob/master/03-actor-critic.ipynb) (previous example), the algorithm will learn policy parameters $ \\theta $ with advantages $ A $.
\n", 19 | "When we assume that the agent takes large advantage $ A $ on action $ a $, $ P(a | \\pi_\\theta (s)) $ must be increased much more than $ P(a | \\pi_{\\theta_{old}} (s)) $, with new parameters $ \\theta $.
\n", 20 | "Hence you can expect new $ \\theta $ as follows to optimize policy. :\n", 21 | "\n", 22 | "$$ \\max_{\\theta} E \\left[ \\frac{P(a | \\pi_\\theta (s))}{P(a | \\pi_{\\theta_{old}} (s))} A \\right] $$\n", 23 | "\n", 24 | "In order to prevent large policy updates, PPO penaltizes for this expectation as follows :\n", 25 | "\n", 26 | "$$ \\max_{\\theta} E \\left[ \\frac{P(a | \\pi_\\theta (s))}{P(a | \\pi_{\\theta_{old}} (s))} A - \\beta \\cdot \\verb|penalty| \\right] $$\n", 27 | "\n", 28 | "where $ \\beta $ is the coefficient for the weight of penalty.\n", 29 | "\n", 30 | "In PPO-Penalty, KL-divergence is used for this penalty term. :\n", 31 | "\n", 32 | "$$ \\verb|penalty| := \\verb|KL| \\left( P(\\cdot | \\pi_{\\theta_{old}} (s)) \\| P(\\cdot | \\pi_\\theta (s)) \\right) $$\n", 33 | "\n", 34 | "Now I briefly explain about KL-divergence (Kullback-Leibler divergence).
\n", 35 | "We assume that both $ P(x) $ and $ Q(x) $ are stochastic distributions. KL-divergence $\\verb|KL|( P \\| Q )$ is then defined as follows and often used in information theory, such as, approximate inference.\n", 36 | "\n", 37 | "$$ \\verb|KL|( P \\| Q ) := -\\int{P(x) \\ln{\\frac{Q(x)}{P(X)}}}dx $$\n", 38 | "\n", 39 | "By this definition, $ \\verb|KL|( P \\| Q ) $ will be always positive or zero, and zero if and only if both distributions are same.
\n", 40 | "This means that $ \\verb|KL|( P \\| Q ) $ indicates how far between these distributions, $ P $ and $ Q $. If $ Q $ is so far from $ P $, $ \\verb|KL|( P \\| Q ) $ will become largely positive.\n", 41 | "\n", 42 | "> Note : For details about entropy and KL-divergence, see chapter 1.6 in \"[Pattern Recognition and Machine Learning](http://wordpress.redirectingat.com/?id=725X1342&isjs=1&jv=15.1.0-stackpath&sref=https%3A%2F%2Ftsmatz.wordpress.com%2F2020%2F06%2F01%2Fsvm-and-kernel-functions-mathematics%2F&url=https%3A%2F%2Fwww.microsoft.com%2Fen-us%2Fresearch%2Fuploads%2Fprod%2F2006%2F01%2FBishop-Pattern-Recognition-and-Machine-Learning-2006.pdf&xguid=&xs=1&xtz=-540&xuuid=c861da822b99f831a421716ca3a51d33&xcust=8982&xjsf=other_click__auxclick%20%5B2%5D)\" (Christopher M. Bishop, Microsoft).
\n", 43 | "> KL-divergence is not symmetric, $ \\verb|KL|( P \\| Q ) \\neq \\verb|KL|( Q \\| P ) $, and also $ arg\\,min_Q \\verb|KL|( P \\| Q ) \\neq arg\\,min_Q \\verb|KL|( Q \\| P ) $ when $P$ is given.\n", 44 | "\n", 45 | "Now go back to our equation. In order to penaltize for large update between $ P(\\cdot | \\pi_{\\theta_{old}} (s)) $ and $ P(\\cdot | \\pi_\\theta (s)) $, we look for the optimal parameters $ \\theta $, such as :\n", 46 | "\n", 47 | "$$ \\max_{\\theta} E \\left[ \\frac{P(a | \\pi_\\theta (s))}{P(a | \\pi_{\\theta_{old}} (s))} A - \\beta \\cdot \\verb|KL| \\left( P(\\cdot | \\pi_{\\theta_{old}} (s)) \\| P(\\cdot | \\pi_\\theta (s)) \\right) \\right] \\;\\;\\;\\;\\; (1) $$\n", 48 | "\n", 49 | "Even if the first term $ \\frac{P(a | \\pi_\\theta (s))}{P(a | \\pi_{\\theta_{old}} (s))} A $ largely increases, new $ \\theta $ might be rejected when the difference between $ P(\\cdot | \\pi_{\\theta_{old}} (s)) $ and $ P(\\cdot | \\pi_\\theta (s)) $ is so large.\n", 50 | "\n", 51 | "Finally we optimize policy function by maximizing (1), and optimize value function by minimizing value loss. \n", 52 | "\n", 53 | "See [this paper](https://arxiv.org/pdf/1707.06347.pdf) for more details about PPO.\n", 54 | "\n", 55 | "> Note : In this example, we ignore (don't consider) an entropy regularizer. (See [SAC algorithm](./06-sac.ipynb) for entropy regularizer.)\n", 56 | "\n", 57 | "*(back to [index](https://github.com/tsmatz/reinforcement-learning-tutorials/))*" 58 | ] 59 | }, 60 | { 61 | "cell_type": "markdown", 62 | "id": "following-cement", 63 | "metadata": {}, 64 | "source": [ 65 | "First, please install the required packages and import these modules." 66 | ] 67 | }, 68 | { 69 | "cell_type": "code", 70 | "execution_count": null, 71 | "id": "secure-latex", 72 | "metadata": {}, 73 | "outputs": [], 74 | "source": [ 75 | "!pip install torch numpy gymnasium matplotlib" 76 | ] 77 | }, 78 | { 79 | "cell_type": "code", 80 | "execution_count": 1, 81 | "id": "scenic-detective", 82 | "metadata": {}, 83 | "outputs": [], 84 | "source": [ 85 | "import gymnasium as gym\n", 86 | "import numpy as np\n", 87 | "import torch\n", 88 | "import torch.nn as nn\n", 89 | "from torch.nn import functional as F" 90 | ] 91 | }, 92 | { 93 | "cell_type": "markdown", 94 | "id": "engaged-chaos", 95 | "metadata": {}, 96 | "source": [ 97 | "As you saw in [Actor-Critic](https://github.com/tsmatz/reinforcement-learning-tutorials/blob/master/03-actor-critic.ipynb), now we build network (function) for actor and critic. (i.e, This is a network for both policy function and value function.)" 98 | ] 99 | }, 100 | { 101 | "cell_type": "code", 102 | "execution_count": 2, 103 | "id": "065feae8", 104 | "metadata": {}, 105 | "outputs": [], 106 | "source": [ 107 | "device = torch.device(\"cuda\" if torch.cuda.is_available() else \"cpu\")\n", 108 | "\n", 109 | "class ActorNet(nn.Module):\n", 110 | " def __init__(self, hidden_dim=16):\n", 111 | " super().__init__()\n", 112 | "\n", 113 | " self.hidden = nn.Linear(4, hidden_dim)\n", 114 | " self.output = nn.Linear(hidden_dim, 2)\n", 115 | "\n", 116 | " def forward(self, s):\n", 117 | " outs = self.hidden(s)\n", 118 | " outs = F.relu(outs)\n", 119 | " logits = self.output(outs)\n", 120 | " return logits\n", 121 | "\n", 122 | "class ValueNet(nn.Module):\n", 123 | " def __init__(self, hidden_dim=16):\n", 124 | " super().__init__()\n", 125 | "\n", 126 | " self.hidden = nn.Linear(4, hidden_dim)\n", 127 | " self.output = nn.Linear(hidden_dim, 1)\n", 128 | "\n", 129 | " def forward(self, s):\n", 130 | " outs = self.hidden(s)\n", 131 | " outs = F.relu(outs)\n", 132 | " value = self.output(outs)\n", 133 | " return value\n", 134 | "\n", 135 | "actor_func = ActorNet().to(device)\n", 136 | "value_func = ValueNet().to(device)" 137 | ] 138 | }, 139 | { 140 | "cell_type": "markdown", 141 | "id": "incident-completion", 142 | "metadata": {}, 143 | "source": [ 144 | "As I have mentioned above, we optimize policy function (actor) by maximizing (1), and optimize value function (critic) by minimizing value loss.\n", 145 | "\n", 146 | "Instead of maximizing $ \\frac{P(a | \\theta_{new})}{P(a | \\theta_{old})} A - \\beta \\cdot \\verb|KL| \\left( P(\\theta_{old}) \\| P(\\theta_{new}) \\right) $ and minimizing value loss $L$, here we simply minimize the following total loss value :\n", 147 | "\n", 148 | "$$ (-1) \\frac{P(a | \\theta_{new})}{P(a | \\theta_{old})} A + \\beta \\cdot \\verb|KL| \\left( P(\\theta_{old}) \\| P(\\theta_{new}) \\right) + L $$\n", 149 | "\n", 150 | "In this example, both $P$ and $Q$ are discrete (categorical distribution), and KL-divergence is then :\n", 151 | "\n", 152 | "$$ \\verb|KL| \\left( P(\\theta_{old}) \\| P(\\theta_{new}) \\right) = -\\sum_a \\left( P(a | \\theta_{old}) \\ln{\\frac{P(a | \\theta_{new})}{P(a | \\theta_{old})}} \\right) $$\n", 153 | "\n", 154 | "Unlike previous [Actor-Critic example](https://github.com/tsmatz/reinforcement-learning-tutorials/blob/master/03-actor-critic.ipynb), we'll train both policy and value in a single optimization. Therefore, we'll assign loss ratio (the following ```vf_coeff```) in this example.\n", 155 | "\n", 156 | "For temporal difference (TD) and GAE, see the description in [previous example](https://github.com/tsmatz/reinforcement-learning-tutorials/blob/master/03-actor-critic.ipynb). (For simplicity, I don't apply TD learning in this example.)\n", 157 | "\n", 158 | "> Note : The log probability is equivalent to the negative value of cross-entropy error in categorical distribution. Same like previous examples, I have used ```-torch.nn.functional.cross_entropy()``` to get log probability in the following code.\n", 159 | "\n", 160 | "> Note : For the purpose of your learning, here I implment computation for distributions from scratch, but you can also use ```torch.distributions``` package to simplify your code in PyTorch. (You can then use ```torch.distributions.kl.kl_divergence()``` to get KL-divergence.)\n", 161 | "\n", 162 | "> Note : For stable training, advantage can also be normalized as $(A-\\mu) / \\sigma$, where $\\mu$ is a mean and $\\sigma$ is a standard deviation of advantages.
\n", 163 | "> In this training, I haven't used normalized advantage." 164 | ] 165 | }, 166 | { 167 | "cell_type": "code", 168 | "execution_count": 3, 169 | "id": "sublime-basin", 170 | "metadata": {}, 171 | "outputs": [ 172 | { 173 | "name": "stdout", 174 | "output_type": "stream", 175 | "text": [ 176 | "Run episode2335 with rewards 500.0\n", 177 | "Done\n" 178 | ] 179 | } 180 | ], 181 | "source": [ 182 | "gamma = 0.99 # discount\n", 183 | "\n", 184 | "# These coefficients are experimentally determined in practice.\n", 185 | "kl_coeff = 0.20 # weight coefficient for KL-divergence loss\n", 186 | "vf_coeff = 0.50 # weight coefficient for value loss\n", 187 | "\n", 188 | "# Pick up action and following properties for state (s)\n", 189 | "# Return :\n", 190 | "# action (int) action\n", 191 | "# logits (list[int]) logits defining categorical distribution\n", 192 | "# logprb (float) log probability\n", 193 | "def pick_sample_and_logp(s):\n", 194 | " with torch.no_grad():\n", 195 | " # --> size : (1, 4)\n", 196 | " s_batch = np.expand_dims(s, axis=0)\n", 197 | " s_batch = torch.tensor(s_batch, dtype=torch.float).to(device)\n", 198 | " # Get logits from state\n", 199 | " # --> size : (1, 2)\n", 200 | " logits = actor_func(s_batch)\n", 201 | " # --> size : (2)\n", 202 | " logits = logits.squeeze(dim=0)\n", 203 | " # From logits to probabilities\n", 204 | " probs = F.softmax(logits, dim=-1)\n", 205 | " # Pick up action's sample\n", 206 | " # --> size : (1)\n", 207 | " a = torch.multinomial(probs, num_samples=1)\n", 208 | " # --> size : ()\n", 209 | " a = a.squeeze(dim=0)\n", 210 | " # Calculate log probability\n", 211 | " logprb = -F.cross_entropy(logits, a, reduction=\"none\")\n", 212 | "\n", 213 | " # Return\n", 214 | " return a.tolist(), logits.tolist(), logprb.tolist()\n", 215 | "\n", 216 | "env = gym.make(\"CartPole-v1\")\n", 217 | "reward_records = []\n", 218 | "all_params = list(actor_func.parameters()) + list(value_func.parameters())\n", 219 | "opt = torch.optim.AdamW(all_params, lr=0.0005)\n", 220 | "for i in range(5000):\n", 221 | " #\n", 222 | " # Run episode till done\n", 223 | " #\n", 224 | " done = False\n", 225 | " states = []\n", 226 | " actions = []\n", 227 | " logits = []\n", 228 | " logprbs = []\n", 229 | " rewards = []\n", 230 | " s, _ = env.reset()\n", 231 | " while not done:\n", 232 | " states.append(s.tolist())\n", 233 | " a, l, p = pick_sample_and_logp(s)\n", 234 | " s, r, term, trunc, _ = env.step(a)\n", 235 | " done = term or trunc\n", 236 | " actions.append(a)\n", 237 | " logits.append(l)\n", 238 | " logprbs.append(p)\n", 239 | " rewards.append(r)\n", 240 | "\n", 241 | " #\n", 242 | " # Get cumulative rewards\n", 243 | " #\n", 244 | " cum_rewards = np.zeros_like(rewards)\n", 245 | " reward_len = len(rewards)\n", 246 | " for j in reversed(range(reward_len)):\n", 247 | " cum_rewards[j] = rewards[j] + (cum_rewards[j+1]*gamma if j+1 < reward_len else 0)\n", 248 | "\n", 249 | " #\n", 250 | " # Train (optimize parameters)\n", 251 | " #\n", 252 | " opt.zero_grad()\n", 253 | " # Convert to tensor\n", 254 | " states = torch.tensor(states, dtype=torch.float).to(device)\n", 255 | " actions = torch.tensor(actions, dtype=torch.int64).to(device)\n", 256 | " logits_old = torch.tensor(logits, dtype=torch.float).to(device)\n", 257 | " logprbs = torch.tensor(logprbs, dtype=torch.float).to(device)\n", 258 | " logprbs = logprbs.unsqueeze(dim=1)\n", 259 | " cum_rewards = torch.tensor(cum_rewards, dtype=torch.float).to(device)\n", 260 | " cum_rewards = cum_rewards.unsqueeze(dim=1)\n", 261 | " # Get values and logits with new parameters\n", 262 | " values_new = value_func(states)\n", 263 | " logits_new = actor_func(states)\n", 264 | " # Get advantages\n", 265 | " advantages = cum_rewards - values_new\n", 266 | " ### # Uncomment if you use normalized advantages (see above note)\n", 267 | " ### advantages = (advantages - advantages.mean()) / advantages.std()\n", 268 | " # Calculate P_new / P_old\n", 269 | " logprbs_new = -F.cross_entropy(logits_new, actions, reduction=\"none\")\n", 270 | " logprbs_new = logprbs_new.unsqueeze(dim=1)\n", 271 | " prob_ratio = torch.exp(logprbs_new - logprbs)\n", 272 | " # Calculate KL-div for Categorical distribution (see above)\n", 273 | " l0 = logits_old - torch.amax(logits_old, dim=1, keepdim=True) # reduce quantity\n", 274 | " l1 = logits_new - torch.amax(logits_new, dim=1, keepdim=True) # reduce quantity\n", 275 | " e0 = torch.exp(l0)\n", 276 | " e1 = torch.exp(l1)\n", 277 | " e_sum0 = torch.sum(e0, dim=1, keepdim=True)\n", 278 | " e_sum1 = torch.sum(e1, dim=1, keepdim=True)\n", 279 | " p0 = e0 / e_sum0\n", 280 | " kl = torch.sum(\n", 281 | " p0 * (l0 - torch.log(e_sum0) - l1 + torch.log(e_sum1)),\n", 282 | " dim=1,\n", 283 | " keepdim=True)\n", 284 | " # Get value loss\n", 285 | " vf_loss = F.mse_loss(\n", 286 | " values_new,\n", 287 | " cum_rewards,\n", 288 | " reduction=\"none\")\n", 289 | " # Get total loss\n", 290 | " loss = -advantages * prob_ratio + kl * kl_coeff + vf_loss * vf_coeff\n", 291 | " # Optimize\n", 292 | " loss.sum().backward()\n", 293 | " opt.step()\n", 294 | "\n", 295 | " # Output total rewards in episode (max 500)\n", 296 | " print(\"Run episode{} with rewards {}\".format(i, np.sum(rewards)), end=\"\\r\")\n", 297 | " reward_records.append(np.sum(rewards))\n", 298 | "\n", 299 | " # stop if reward mean > 475.0\n", 300 | " if np.average(reward_records[-50:]) > 475.0:\n", 301 | " break\n", 302 | "\n", 303 | "print(\"\\nDone\")\n", 304 | "env.close()" 305 | ] 306 | }, 307 | { 308 | "cell_type": "code", 309 | "execution_count": 4, 310 | "id": "8c088ba8", 311 | "metadata": {}, 312 | "outputs": [ 313 | { 314 | "data": { 315 | "text/plain": [ 316 | "[]" 317 | ] 318 | }, 319 | "execution_count": 4, 320 | "metadata": {}, 321 | "output_type": "execute_result" 322 | }, 323 | { 324 | "data": { 325 | "image/png": "iVBORw0KGgoAAAANSUhEUgAAAigAAAGdCAYAAAA44ojeAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjcuMCwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy88F64QAAAACXBIWXMAAA9hAAAPYQGoP6dpAACCwklEQVR4nO3dd3gU1foH8O/MttRNSCAJAULovdfQpEkRsYBeVBBEREVAAUXFq+DFguLPclFsVwQboKigooJIFQmIoVdpIbSEEtLLljm/P5ZsdrMlO7uzO7Ob9/M8edidOXPmbGHm3VM5xhgDIYQQQoiC8HIXgBBCCCGkKgpQCCGEEKI4FKAQQgghRHEoQCGEEEKI4lCAQgghhBDFoQCFEEIIIYpDAQohhBBCFIcCFEIIIYQojlruAnhDEARcvHgR0dHR4DhO7uIQQgghxAOMMRQWFiI5ORk8776OJCgDlIsXL6JBgwZyF4MQQgghXjh37hzq16/vNk1QBijR0dEALC9Qr9fLXBpCCCGEeKKgoAANGjSw3sfdCcoApaJZR6/XU4BCCCGEBBlPumdQJ1lCCCGEKA4FKIQQQghRHApQCCGEEKI4FKAQQgghRHEoQCGEEEKI4lCAQgghhBDFoQCFEEIIIYpDAQohhBBCFIcCFEIIIYQojqgA5cUXXwTHcXZ/LVu2tO4vKyvD1KlTER8fj6ioKIwePRo5OTl2eWRlZWHEiBGIiIhAQkICZs+eDZPJJM2rIYQQQkhIED3VfZs2bfD7779XZqCuzGLmzJn4+eefsWrVKsTExGDatGkYNWoU/vzzTwCA2WzGiBEjkJSUhB07duDSpUsYP348NBoNXn31VQleDiGEEEJCgegARa1WIykpyWF7fn4+lixZguXLl2PgwIEAgKVLl6JVq1bYuXMnevbsid9++w1HjhzB77//jsTERHTs2BEvvfQSnnnmGbz44ovQarW+vyJCCCGEBD3RAcqJEyeQnJyMsLAwpKWlYcGCBUhJSUFGRgaMRiMGDx5sTduyZUukpKQgPT0dPXv2RHp6Otq1a4fExERrmqFDh2LKlCk4fPgwOnXq5PSc5eXlKC8vtz4vKCgQW2xCCLG6XFiG7/dcwF1d6qN2lK7a9Fv/uYLc4nLc2cn98vAVVvyVhca1I9GjcTx+2HcBhy7ko3liNO7u2sBp+sIyI5bvykKrunr8efIq/skpRFJMGF66vS3OXy/Fb0eyEa5VY+vxKygsM6JxnSg81r8JTl8txoRP/8KU/k3wzLCW+Gn/RbzwwyG8fEdbXCsy4L3NJ7Ficg80TYjGmr0XsPHYZYzp2gB9mtXGrwcv4cf9F5Fx9joYgKeGNIfBJGDrP1eRXVCK+rERWHc4G3d2qofVey/gwd6NcL3EgNV7L1jLnajXIafAcm1OjY/AE4ObIVyjxrHsApgFhs/TzyK/1IhaERoIDMgvNTp9/Y3rRKLUYEZhmQkdG8Ri+8mrAIB+zevg1OUi5JcaUVRu6QqQHBOGi/llAIAO9WOw/3w+ACBMw6PMKKB7ahz+ysy15q1V8zCYBIztkYL8UiP2ncvD+eulDmW4vWMyfth3EQDQLbUWMq+V4EphOdQ8h/b1Y7AnK6+yvLUjcfpqsd3xozrVw75zeQ7b68aE4VJ+GZrUicSpK5Z9+jA1CspMaFwnEqevFEOj4tCnaW1sPn7Fbn+FcI0KpUYz4iK1yC02ICFahz7NamP7iau4XFhufQ9PXylGanwEMq+VoH39GBy48d7UitDgeokRA1rUwebjV5DWOB7/5BTiphZ1cPJyEQ6cz8eglgnYeOyy9fXFR2kxoVcqbm2f7PQzCwSOMcY8Tfzrr7+iqKgILVq0wKVLl/Cf//wHFy5cwKFDh/DTTz9h4sSJdoEEAHTv3h0DBgzA66+/jocffhhnz57F+vXrrftLSkoQGRmJX375BcOHD3d63hdffBH/+c9/HLbn5+fTasaEENFGvrsdBy/ko1tqLax6tFe16VOf/RkAsPmp/mhUO9Jt2t2Zubj7w3QAwI5nB6LXa5us+355vC9aJztes55atR/fZpx32D5vZGu8tPYIBA+u0mun98Gt7253um/b7AHo98Zm6/MDLw5B+xd/qz5TUqMNbZOIj+7vKmmeBQUFiImJ8ej+LaoGxTaAaN++PXr06IGGDRvim2++QXh4uHel9cCcOXMwa9Ys6/OCggI0aOD8lwghhFTn4AXLL8vdmddFHXelsLzaACXT5hd0brHBbl92QanTACX91DWneR2+WOBRcALAaa1AhStF9j8cS8rNnmVKarQWidGynt+nYcaxsbFo3rw5Tp48iaSkJBgMBuTl5dmlycnJsfZZSUpKchjVU/HcWb+WCjqdDnq93u6PEEKUyPM6acnPLNeJSYga0sb1fTkQfApQioqKcOrUKdStWxddunSBRqPBxo0brfuPHz+OrKwspKWlAQDS0tJw8OBBXL582Zpmw4YN0Ov1aN26tS9FIYSQkCNVsMNx0uRDSCCJClCeeuopbN26FZmZmdixYwfuvPNOqFQq3HvvvYiJicGkSZMwa9YsbN68GRkZGZg4cSLS0tLQs2dPAMCQIUPQunVr3H///di/fz/Wr1+P559/HlOnToVOV31HNUIIkdPuzFw88sXfuJDnujmFyVaTQVEIkRYvc2Qrqg/K+fPnce+99+LatWuoU6cO+vTpg507d6JOnToAgLfffhs8z2P06NEoLy/H0KFD8f7771uPV6lUWLt2LaZMmYK0tDRERkZiwoQJmD9/vrSvihBC/OCN9ccBAHklRnz9SJrTNJ72GZEeNfEQacld8yYqQFm5cqXb/WFhYVi8eDEWL17sMk3Dhg3xyy+/iDktIYQoitsaFDdxgiCIO49UNwiqWyHekDtAobV4CCFEQu6aeB76/G8YzZ5HKWL6oIhJK/eNhwQHuZt4KEAhhBCR3AUD1QUKFZNnyUm+kUYkmMgdx1KAQgghErK99yulpoJTSkFIUJH7a0MBCiGEiOT2wm1TPaHUmgq5bzwkOMgd2FKAQgghElJoTEKIaHLHsRSgEEKISO5H6lTuDOQPUAqMiNSoBoUQQkKIJ4GCIDBcdDNUuTIvacIOuX8Jk+DEUx8UQggJLu5+WFbf74Rh2oo96PXaJvx68JKUxSJEEjfx+/GKegki//lB1nJQgEIIISK5HWbswfG/HMwGAHy47bQ0BSJEQp34Exir3oiwCztkLQcFKIQQIiEm4dAdTkTjjFJHDJHg05I7BwAQIurIWg4KUAghRKHkW3iQ1GQD+H0AABaml7UcFKAQQohIvvVBscnH96J4dh7qJUtEyEckAMBUu7Ws5aAAhRBCRDp/vRTrD2c73Sdlrcf3ey5Ikk/VpiKKV4gz7blTeE+zCAlcHgBAiK4na3koQCGEEC888kWG0+3UF4QEo4mqX/Gj7gXcqtpZuVGjk69AoACFEEIkJVd8Qv1V/IuDABXMchfDL1K4HMzTfOG4Q00BCiGEhAzbGhQxo3CIsn2hWYCN2qeghVHuonhNAxN4CHbb0vjD+Fb7H6fpOXV4IIrlEgUohBAiIduaDKXUalAnWd/MUH+LPqrDSOVz0IE7JXdxvDJBtR7HdBOQoXsUjbmL1u2LNO9a+5w4UGsDUzgXKEAhhNQoJrNQfSIfVNcHhfqoKJNW5fx2mIyrmKH+3vpczQVnM09/fh9UHEMtrgid+RMAgObcOdThCpymPykkg1eHBbKIDtSynp0QQgLsr8zcgJ3rerEymwO+3JUldxEUh+cBZ11MorkSu+cPqX5ButAmMIWSUDhnsD7WwoQh/G58rH3bLs0v5u54zDgDYSgHAKTLXPVGAQohpEbxdw2G7UyyM7/Z5zZtxfVfivuAmNe1aOMJ308YYlQuPoRwGOyep3CXA1EcyYXfCDoAQAcDmto081R4yXg/AKAMls6xcjcNUhMPIYRISLAJFK4UlrtOaIOafeTHuwpQOPvPsBl/AfKN1fJevE1Tjg5Gh9cFAJcQb/eckzlCoQCFEFKjSBkM7Dh1FXcs/hOHL+b7JX8xgu+WqSw87/xm3Jw7DwA4JjSwbgu2jrJduWOoz121Pk/jj6AzV1mLtkdoig5lHzscRzUohBASpO773y7sO5eHiUt3W7dVN3Jn2z9XHLb5+0Yg940mGKhcBCgVTTo6m6aeRO56QMokBS2M+FY3327bTaoD6K06DAB4y3gXRhnmIx9RDsfK/bWhAIUQUqP442adW1x586quBmXRppPSFwDy30xCVTjKAABbhI74w9z2xjbPmu78x/P6siiUut1fse6OM66avQKFAhRCSI3i906yItJWXP6lKBM18UiPh4D71JsBAGdYEkpgGXY7XLUbd6m2Qg2TX877lPprfK+di1TuEkbyO5CMyuaZFlwWdusew1jV79Xmc69qI55Wr3Sb5ldzd5f75K55o1E8hJCQk3WtBC//fASP9m+Czim1AntyBfZ4pRltvWMbBBwSGqETb6n9GqbajWGq3eDAsMrcX6KzMaggwAwVpql/AABs0T0JAChmOrQv/wRmqPCqZgnqcPl4RfMpvjIPdpvfAs0Sl3vvMTyPg0IjFMP1bLFUg0IIIRKb8lUGfjuSg1Hv7wj4ub0JT6QZZqy8wCiYVP0I2nOn8JJmGQBgl9ASe1hzGJjGLk1X7h+3eepgwB38dsShAKncJdyr2uhiPR+Gr7UvYaduKupzjn2UIrlyRMMyH4vGw1obV81Q75ruwDemm7BTaOU2OFECqkEhhIScrGslLvf5+0ehQIFCUKr6qX2sfcv6eL5xvGWbeQTGqLdYt1dd16aqGervMEX9Ew4JqWjLZwKwzKvyqXm4XbpwlKMHfwwAMEu9ymle/fiDWCv0RBsu07qtDvJwBbFO08eh0GHbs8aHsNI80G2ZbcndxEM1KISQGkVs/OBJzYTthZzik9CQZDNSp/jGxGWnWD3MNEyxbh+m2o145GOs6ndEwTEovpXfCQDW4AQAevOHHNLZTgY3SrXdaXkWad/D6bBxUHGVXzBnc5lUeEPzkd3zvUJTUcGJElANCiGE+EjpQYncv4SDXQmrXJNmN2thfRzNlWKd7hnU4QrQkTuJ2aZH7Y4rh32TEACEVZmZFgAi3AQa7rgbodNLdcTu+S6hpej85e67RDUohJCQo/B4gSiQ/a3Y/htUeqMGBQDOszo4IdSzPq9YbG+o6m+HPJvyjtPJO1tsMMzLYcvOApTb+B1oydmvtVTAIrDUNExU3vNGtoZWLW+IQAEKIYT4iGoogl9FSNKdO4o9ukes282MQ4lNgAJweNQ4w+F4PVeCzdqZ1s6srs9T+WXRwIQolKAL73ptpNnGh13uu1mVgfGq9dbSd+JOYJH2PazTPWuXrnP5h8hBnNtyVTWxdyNR6f2BAhRCSMiRMl4Q23wjJlgJ1FonFEB5bo5mBeK4IuvzEYYFMENll+Yycz50vRGfg7b8GcSgCM1uTJFfVU/+KD7WvIlwlOE77TwcCnvI6cidCqvM/ZFathxmZvkQnzdOxHazZTXlyepfMF/zGXryRwEA9Wyms7dlCtLeHMFZakIIUSil90ch7qVwOdbHGUIzHGMpDmkKEYER5a/gZ92/HfbpUYwftC8glc9x2FdhiCoDE4Tf0J4/AwCYrl7jNJ1tv5FxxufQmTuBVeabcKtqp126ldqX8aM5Dbep0h3yeNgw02U5lI5qUAghIYdiBCJWRSWTwaZjaz5zPQ38YdYI9xmec9geyxW7DU4qJHG5bvffVP4W7jU8b32eLrTBYvMdKIcWRwXHoMlZcAIAvwndqi2LUlGAQgghbogNduRqTnFXcyP3aIxgUPH2GZjaZpv7922H0Aa3lr+MZ4yTcVhoCAC4W7XVo/NFc+77qmSzOAgubtFvm+6yns+d/UJjj8qiVBSgEEKIzKiPiPyGCtuxSPMuanGVE5y9bRpdzVEcDrHG+No8ALsFy/Djrrzz2WWnG6bZPR/tYr4TANgnNEE5tC73FyASX5hvdnN8Y5gZh/Xmru4Kr3jUB4UQEnKC5X4fLOUMdSqYsYC9A9u+sNMM03GIeV4DUYAIp9tnGx/GenNXFCAK7+I9t3nMNEzBVqED8hBV7fkOuKgdyWORuMPwEngwlzUwwSK4S08IIU4EWx8U6lgrr9rId9i2S2glKo/jTvqF3Gv4N74z90PBjYDjkJDqkObm8oX4xnQTjggNsUXogFzoPQosjrBUjDPMceiPMtLwMgAu6IMTgAIUQghxy6Op7hVeFxIMTUhaGDGIz8Bk1VroURzQc+ud9AfJh+sOss78LPTAE4bH7LalC23sAoV1ZscOq2dYEp42PYJbDAtwHXpR59wutMMHptuszz8wjcQ5ligqDyWjJh5CCJGZJKsZB129kb2lmoXorToMAIjnCvGa6d6AndtZQGRwMk29exx+EPogzxCN1zT/wxzjQw4p3jffjp1CK3yrm2/d5uscJVuE9vjZ3B0CeLxhGuNTXkpDNSiEkBol2G/koagJd8EanABAX/5AQM8fw0lXY7NV6IC08vewRejosE8Aj79ZS0wxPIEjQkMMKn/D5/MVIApTjTMw3fh4SDTr2AqtV0MIITVUMPdj+U37tN3zetxV3KfaCJ2ThfW89Yp6Cd7XvANnPZT01UxPL7VfhR64xbAAp1i96hPXYBSgEEJqFLH9RYL4vm+l9OBFxdkXMJYrxquaJXha/bUk+Wtgwlj1Rtyi+gtNuQsO+/VValDy3EzQRgKHAhRCCJGQmAAoGDqvyulu1RZJ8rFdwE8Ho8P+ihqUHebW+M7cB48ag3d6+FBCnWQJITWKv/ugUB8XsVy/X3qu1KecdTBghvo75LHKeUU68qdQLIQhk9W1nr9i2vmDrBEWmMb6dE4iHQpQCCEkxCk5aIpAuWR5aWHE/aoN2Cs0xR7WHGNVGzFF/ZNdmlc0nwIAmpR9ATNUeE/zrnXxvQJq2lEUClAIITWK6D4oyr232wmWclYVBd9qSWyNUv2BFzRfooiFoW35p6jHXXV7Xg7MbmXgy4iVrCzEdxSgEEJqFH/XJih90jaliaqmGUcLo8dzkrTlztzIswwAUIRwl2ljuGKMUW2227bG3Mej85DAoE6yhBAiITEBkElgeGDpXziX63stwi8HL7kuk4JrVypqUC6yOIw1zMF5Vttuf6SIGpbm/HmbZwzTVatdpq2FQrTmztptM9JvdkWhT4MQEnI8mZ5eUl5WmuzNypOsCBuPXZYsr0Bqz58GABSyCPwptEP9Ks0ykVwZrrPqp4Dvwh1Hd/649fk/uvHgOdffg6nqHzBAtd/6PAdxYotO/IxqUAghNYr4eVDEBTvUxCNOHS4PAJDIXQcAFDOd3f5IlFWfB/Lwne4/dtu0nNnueSGzb+4Zosqwe/4cP8OT4pIAogCFEBJyODcTjCh5RIu/KLmJp2Jekh/NvQAADxmfstvvSYBSl7tWbZqdblYnfsQwE3u51tXmQQKLAhRCCCGyqRhmfB3RACwrALcq+xRHhIYAgG+08/Gm5n1wEJwer4URL2mWVnuebUJ7p9tnGB7DeqEr1XspEAUohJCQE/A+KMRr4TcClFKmtW4rRRiKEAYAUHMCRqu2oxGX7fT41dq56HCjH4srA8rfxCGhkcP2iywOa4Q+ALgaWK+mfBSgEEKIGxTr+BPD3eptAIBS2Pc90cC+D0lt5DvNoQ1/1ul2W2dYXexjTfCRaQT+FppbtyffmEGWKBMFKIQQEuKU2u+mjk3QsVdoarcvvMoMsx9r33LZzFNhn9DEYdsLxgcAAAw8FpjG4i7Di94VlgQcBSiEkJDjrpMskdYofhteUH8Bb9Z9rsUVAgDyWQQOMPvgompusVwxPtW84Ta/fxnmOmy7UGVeFVfoG6M8PgUor732GjiOw4wZM6zbysrKMHXqVMTHxyMqKgqjR49GTk6O3XFZWVkYMWIEIiIikJCQgNmzZ8NkMvlSFEIIsaI+KIHzlvZDTFL/ijXauRAbpMxSfwsAuM6inex1DBls5y0BAJVNM9AP5l4wQIPFpttgYpW3NtuVjN2hb4zyeB2g7N69Gx999BHat7fvGT1z5kz89NNPWLVqFbZu3YqLFy9i1KhR1v1msxkjRoyAwWDAjh078Nlnn2HZsmWYO9cx8iWEEOI7f8VrbbhM6+OO/Cl04k56fGxrLhPDVLsBAKl8jsP+Q0Kq0+NiUGR9XOvGY4FxeNL4KADgDdM9aFb+Ob4x3YTLLBZbhQ4el4koi1cBSlFREcaOHYv//e9/qFWrlnV7fn4+lixZgrfeegsDBw5Ely5dsHTpUuzYsQM7d1oWZPrtt99w5MgRfPnll+jYsSOGDx+Ol156CYsXL4bBYJDmVRFCSADZ/tavSa1LCzUf2T2P4wo8PrYvf9Dt/rdMd2OlqT/eNd1ht3259hW8qfkAjbmL1vlPLiMWJpuJ0Rl4PG16BD3K30MeHGtnKoKfqtPqE2XxKkCZOnUqRowYgcGDB9ttz8jIgNFotNvesmVLpKSkID09HQCQnp6Odu3aITEx0Zpm6NChKCgowOHDh52er7y8HAUFBXZ/hBBC5OXJCBpXUrjKqflXmvo77L+EeDxrehhvm+5yOOdo1R94Qf2FdaHBPBbl9BzMxS3uEcNMfGa6GWMNz1m31aC4MmiIDlBWrlyJPXv2YMGCBQ77srOzodVqERsba7c9MTER2dnZ1jS2wUnF/op9zixYsAAxMTHWvwYNGogtNiGEeOVSfvUzmdZURSzM7nk4PK8Fr+ggu0toiXmmB1ymE8BjTPkLDtu78CesI33KoHXY784F1ME800ScZUnWbdQHRXlEBSjnzp3DE088ga+++gphYWHVHyCROXPmID8/3/p37ty5gJ2bEFJz7c7MxYD/2yJ3MRSrEBF2z1vzZ+HprT4GxQCA5aaBKK8mwNjFWuExw+N22xgqAyKxAQoJDqIClIyMDFy+fBmdO3eGWq2GWq3G1q1bsWjRIqjVaiQmJsJgMCAvL8/uuJycHCQlWSLVpKQkh1E9Fc8r0lSl0+mg1+vt/gghxN+W78qSuwiKFnYjQDgqpAAAHlP/iPGq3zw6Vs9ZApR8RHqUvupEbjFcCZrzlh+rtrPQktAhKkAZNGgQDh48iH379ln/unbtirFjx1ofazQabNy40XrM8ePHkZWVhbS0NABAWloaDh48iMuXK9sfN2zYAL1ej9atabEmQoh/iRnRQsOV3atoYrHtbDpf81m1x0WjBO34TABAAfMsQLnKYhy2PaFeDYBqUEKVuvoklaKjo9G2bVu7bZGRkYiPj7dunzRpEmbNmoW4uDjo9XpMnz4daWlp6NmzJwBgyJAhaN26Ne6//34sXLgQ2dnZeP755zF16lTodDqHcxJCiFgUVtgzmN3PwOoNDgLCOMtKxMUIc9jnqoMqABwMe8j62NMalIOsEc4IiWjkZEiyq06yJLhJPpPs22+/jVtvvRWjR49Gv379kJSUhO+//966X6VSYe3atVCpVEhLS8O4ceMwfvx4zJ8/X+qiEEKIAzHDgEMl0Bn1/g7J8wyz6RBbwux/XK7XPuNyWvqq2/M9Di44LDMPc7onHxSghCJRNSjObNmyxe55WFgYFi9ejMWLF7s8pmHDhvjll198PTUhhDgV6CGjNWnukwq2I3aqBgjN+QsYwO/DJqGzw3FhVUb65DqZp8QVo4tb1i6hpcd5uFIDP0LFo7V4CCE1ij+6ldTErirWIb5MgxXmgQ77K0bpVBVRZRFAQcRtKL9Kf5XvzX0wqPwNbBY6eZyHKzXwI1Q8ClAIISGHbjb+F8ZZakJKoUMWS0Rq2Vd2+81QOT0unKsMUJ4xThZ1zt+Fzlhl6md9/qO5F06xeqLyIMHD5yYeQggJJqL6oHgY6dTMJh5LoFFqHUHD4aiQgla8ZWh25I1ZXquKhmX7FRaDr80DRJ2zHFrMNj0KAzRoxZ/FdqFt9QeRoEUBCiGkRhE1zNh/xQh6FX1JSm06yI4zzEFG2BQAQCScz8BbMYNsrtMVjD3zb9Mkr491pQbGmIpHTTyEkJAj5maz/1weer+2CT8fuBTwcwez8BtNPLazwF5DDL4wWdZii3JRg1Ib+QCA6yI6xwYCBaPKQwEKISTkiLnZPPzF37iQV4qpy/cE/NzBzLGJx6IY4QCAKDgGKONUG7BIaxnheVqo6+cSkmBHAQohpEYrM0o/iVlNUNnEYx+gVCwg6KyJ52XNUuvjHFbLj6UjoYACFEJIjZFfYsRH2055nN7Tqe45m4admtbEU3WNnIpZZXvwR3ELvxN6F8ONqy40KLea8rkFEwpQCCE1xlPf7sefJ69Jni+rMQ07lW7l0wE4roNTdKOJpzGfjfe1i7BaO9fp8YU30ilFzfsElY8CFEJIjbHtnytyFyEkNOEuoK/qEACAVal7KGL2gUcT3tL5WI8it+kIqYoCFEJIjSbFisVcDWsgSODyrI/VMNvtK3JRM6KvMqpHaU08RHkoQCGEEBc8DV1qUhNPKncJK7SvWJ8LVYKzKyzW6XG6KmvwKK0GpWaFmMGBJmojhBDisS26J6tssb+1n2TJDsc8rV6JAmZfY0J9UEh1KEAhhBBXPJ3qvgb//q76FpmgRuOyL3ELvwvvad8FADym/tHhuGwWF4DSETEa147E6avOR13JgZp4CCE1hrM1c+iXs2+Kb8x7YksAj7VCmvvjFFaDUtPUiw3HxN6pchfDLQpQCCE1hgT9YUkV35r7udxX5CR4Icrw57MDcXeXBnIXwy0KUAghxAWvOr+G8NLG0Sixez7NMB1/s5Yu01cdglzhScOjkpaLhCYKUAghNYbT2EHqWpUQrqbpzR+yPn7ROL7aZpwdQhuHbeMMc/Cd4LrWhZAKFKAQQmoMsbGDp+lDuNLEzquaTwAAl1kslpmHVZv+ZdNY5LIou207hVZ+KRsRr1liVPWJZEQBCiGkRpOivsMukAnhaCWOs8wGaztRmzvnWCK6ln9ot81Eg0cVQ6PiMbKD47BwpaAAhRBSY4Rw7KBYAnhsMneUuxjEBZXt/wmF/f+gAIUQUmP4q3tITQl8rt9ornnM8Lio46rONkuUg7P98iqs+xQFKISQkCNVIOJpPiHcL9ZO6Y2Vi8+xBFHH/SVYRvqcFcQdR/xPirWo/IUaAwkhNYazmo6icpPd83O5JZj97X5M7ts4QKVStmiUIInLxQlWHxEoBwCUQCcqj8/NQ1CCMGugQhRKYRVdFKAQQkKOqyYXT34sPvv9Aew8nYudp3MxtE2iT+cLBT9r5yCFv4Lby+cj/EaAUsrEBShl0OFL883+KB6RksIqU6iJhxBCbFwrMlSfqAZJ4a8AAMarf4OOs9Q2ia1BIcrFKTi6pgCFEBJyXNWUKPharHijVdutj0spQAkZSu6DQgEKIYS4oOBrd0CoYHbYZmI8yqGRoTSkpqEAhRBCiFN6FDtsM0EFxfWmJCGJAhRCSMiRqinH0woUBc915ZNYzjFA+cB0mwwlCV19m9VGm2S9bOenPiiEEBJAVZtmyoxm7Dp9DYLgp/O5eBys6uA6VDCjHXfGYV8m82xkU7CR6zb933s6Ye30PjKdXdlomDEhJORNW74Xvx/NkbsYQaENl4mfdc/hD3Nb9FUdcti/jzWVoVT+J2dgKWctBnWSJYQQGfk7OCkxmPHG+mMAgr+J5x7VJgBwGpwAQC6TrzkilC0c3V7uIigOBSiEEOKCmB+Xizef8l9BAsjs5LZQxipH7RQhLJDFCXkVAW2HBrHynF/BfVCoiYcQQmwcyy60eabc6m9/6cYftz7OY5GI5Yox2vAiyqGBEWow+l1LAoQCFEIICUEcBHTnjuMwa4giRFSbnoeACJShDX/Wuq1iFM8VFovLqOW3shL5KLkPCgUohBASYqJRgvtUGzFHswKbzR0w0fiM3X4dDCi/sTIxADytXolxqt+RxyKd5pcP59uJ7xTcwiI7qqsjhJCg5fjrN40/jINhD2GOZgUAYIBqv93+caoNOB72AG7m/7Zue0z9I/RciXXdHVvlTE0zx4YwJfdBoQCFEEJcUHDtN5JxFZlhY5Gum4ZaKMAw/i/oYMAK7Stuj3tZsxQA8J5mkUfnKUAkgn9skm++nNTD7+dQcJwgG2riIYSQIDRdvRoAUJfLRYZuCniOIVNwNYkaQ9Ugg/OwA3AdLt+HUoaGPs1qy10Ev1FyHxSqQSGEkCAUxhmsj3nOcpNJ5Z3P9xKJModt9INdGTj6JFyiAIUQQoJEGn8Yt/Lp6M/vRV0u1+PjUjnHwEXDWVYqdrZi8fdmmnq9plByHxRq4iGEhBwm0fwlyqr8ZtX2L3Flmno1phhnOt1XtXZlnGEO+vP7vDoPIVKiGhRCCAkCUSj1+thwWJqDnNWW2OY7qPwNbBfaQQOTddu9hn97fV7iAc7un4CjPiiEECKxQFxYlXTxflT9k6j0d5TPx/PGiQCAcK4cAJDKZdulWap5HTvCHgcA5LBYnGL1AAB6rsSaJl1o43WZCfEFNfEQQoJOqcGMW9/9A72a1MZLd7R12C9nx0N/NOnX565gmvoHUcfsY03BCTc6z3LZmKlehXtVm+3S2M6RclBoZH2cxRJ8KC0JJtQHhRBCJPTTgYs4daUYp64UOw1QpOqDsvm448Rl1fFHpUsd5Lndf0qoCwPUaMWfs9t+llmGHSdyeXjixrBkV/YLTayPPzKNRBKuY63Q07sCEyIBClAIIUHHX00vT3+7v/pEMoi2aXKp8IBhNv4RGmCCej0+Nw3BBdRGZthYAEAui7L8i2gUsnBEc9X3X9kidLQ+LkEYnjE9LE3hiVtyV2AoqRmzKgpQCCHkhm/+Pu9zHv644cSi2GHbFqETAGCBaax1W7ey9/Gwei2WmwdVlMaj4ASgZh2iPBSgEEKIwsVwRQCAX8zdcYLVw0GhsdN0VxCLV0zjvDpHCcK8Lh/xnVw1KUrug0KjeAghROHiUAgAyGNReNt0N34Xunh87BpzL4dt11i0wzYj/V6VhXLDA/lRgEIIIRLxV3t+Gz4TAJDJXK2149pF5riOTD6LtHv+melmr8pFgp+S+6BQgEIIIRIR/HCtT8ZVDFFlAABOs2TRx281d7A+LmJhuMaisVNoZd2WzyIwzzTR94ISIjGq0yOEBB2lLrAm+OHXaMVEagCQV6XmwxO7WCuMLp+HsywJ1xEFNcyYqf7Ouj/GyQghUnMouQ8KBSiEkKAj1TwnUjMLTNLgaTS/ze65s+YaT2SwFtbHZqggKDTAq4kqAwT6TKqiJh5CCJGQVMGTGia8qf3QbttFeBegVGWmSz+5gfqgEEKIhJTaxCPltX6C6je751+aBrlIKV4JoyHFRPlEBSgffPAB2rdvD71eD71ej7S0NPz666/W/WVlZZg6dSri4+MRFRWF0aNHIycnxy6PrKwsjBgxAhEREUhISMDs2bNhMpmqnooQQoIOg3RNPJ34k9bHy00D8LxpkiT5AsCX5sHWxzMMj0mWLxFP7lA7ZPqg1K9fH6+99hqaNWsGxhg+++wz3H777di7dy/atGmDmTNn4ueff8aqVasQExODadOmYdSoUfjzzz8BAGazGSNGjEBSUhJ27NiBS5cuYfz48dBoNHj11Vf98gIJITWPXLXWUp5XDbP18RLzLdJlDKAQEUgtWw6AQf5bJCHOiQpQRo4caff8lVdewQcffICdO3eifv36WLJkCZYvX46BAwcCAJYuXYpWrVph586d6NmzJ3777TccOXIEv//+OxITE9GxY0e89NJLeOaZZ/Diiy9Cq9VK98oIISTApIyLkrhc6+P8G2vrSI+Ck5ouJPugmM1mrFy5EsXFxUhLS0NGRgaMRiMGD66sOmzZsiVSUlKQnp4OAEhPT0e7du2QmFg52dDQoUNRUFCAw4cPuzxXeXk5CgoK7P4IIcQVBddaeywaluG/281tcBUxMpeG+FsofGelJjpAOXjwIKKioqDT6fDoo49i9erVaN26NbKzs6HVahEbG2uXPjExEdnZ2QCA7Oxsu+CkYn/FPlcWLFiAmJgY61+DBg3EFpsQQvxOml+jDAP4vWjCXwIAzDeNlyBPolQUmLgmOkBp0aIF9u3bh127dmHKlCmYMGECjhw54o+yWc2ZMwf5+fnWv3Pnzvn1fISQ4CZbHxQAlwvLfMrjbtVWLNW+YX1edVr6UDKqUz25i1DjhUwnWQDQarVo2rQpAKBLly7YvXs3/vvf/2LMmDEwGAzIy8uzq0XJyclBUlISACApKQl//fWXXX4Vo3wq0jij0+mg0+nEFpUQQgJqwS9HseIv335AjVVttHuej9ANUKgLjHg9G8dh5+nc6hN6KCT7oFQQBAHl5eXo0qULNBoNNm6s/M91/PhxZGVlIS0tDQCQlpaGgwcP4vLly9Y0GzZsgF6vR+vWrX0tCiGEyMrX4ASA3Syv5UyNMtDggVCm1Dl9lEBUDcqcOXMwfPhwpKSkoLCwEMuXL8eWLVuwfv16xMTEYNKkSZg1axbi4uKg1+sxffp0pKWloWfPngCAIUOGoHXr1rj//vuxcOFCZGdn4/nnn8fUqVOphoQQ4rlqrukKrrV2K4XLQWeb+U90nAlUzVAz0KfsSFSAcvnyZYwfPx6XLl1CTEwM2rdvj/Xr1+Pmmy1Ldb/99tvgeR6jR49GeXk5hg4divfff996vEqlwtq1azFlyhSkpaUhMjISEyZMwPz586V9VYSQ0FZNrbSCa63d2qabKXcRyA0N4sJxLrdU7mL4Xcj0QVmyZInb/WFhYVi8eDEWL17sMk3Dhg3xyy+/iDktIYQQQvwgpPugEEJIwCn3R59PrrFouYtAAkxsBYaC4wnJiR7FQwghgXb+eglOXi5C/xYJchdFMuEoQxTKcAWxAIBIlCKeKwQATDU8jo78Sfxg7iVjCWu2mhQIKBUFKIQQxevz+mYAwOcPdke/5nVkLo00NuqeQjKXi65lH+AqYjBP/bl132UWi1dM42QsHQk0T/uCSN1lRMl9UKiJhxASNHZnSjf/g5x4CEi+sdZON/4YAIbbVDus+0tpaDEJECX3QaEaFEIICbD/at6zPh6k2ovxqg0I44zWbZdYvBzFIkFAwfGE5ChAIYQEjVC5OI9U7bQ+vku1zWH/NegDWRziRKh814IZNfEQQojiKLdfQE31QK9UuYsAgPqgEEII8aM8NwsADil/PYAlIZ568bY2fslXyvhgZIdkzL01dJaNoSYeQggJoMmqtYjlil3uP8PqBrA0RCk8jVPcNT29e28nHDyfL+q8Su4kSzUohJCgo9xKafc4CPi3ZrnbNEb63RjUakfRunJSof8JhJCgU91vPqX+JqyFIrvni0x34HH1GjxvnAgVBBwUGslUMiIXuVczVnIfFApQCCFBgyk29PBMrRszxVZ4y/QvvGW6G8FbJxS6vG368Pf9XsHxhOSoiYcQEnSqu0Yr9RoejwLr45Wm/jceKbW0xBv+/jSl7jJiG4hNH9QUAHB7x2RpT+IlqkEhhISccpMgdxGcirtRg3JAaIRnTZNlLg1REiXUjNzZqT66pcYhOSZc7qIAoBoUQkiIuZhXKncRXIrnLDUo2SwOVHMinSdvbi53Ebwmd2BStQ9K/VoR4HllfDcpQCGEhJSVu8/JXQSX4m408VxjNFOslKYPaiZ5nt62pFAfFOlQEw8hJGS8+ONhLNuRKXcxXKpo4rmOaJlLQvzF36Ny/NkHRWmoBoUQEjQqrqWuhkYqOTgBKgOUa4wClFAltoajBlWIiEYBCiEk6Cj5V587FU08udTEo3iB/orJNR+KkudBoQCFEEIChJp4CPEcBSiEkKBR8aNWyb/63Im5sQZPHouSuSTEX4Ltm6nk2kgKUAghIW3doWy5iwAAGMDvRX3uKgAgH65XMybi/PeejnIXwY7Y4FnqYDtIY3enKEAhhIS0R7/MkLsIAICl2jesj/MZBShSiY/0z+J8wbqsgtgKESXXRlKAQgghfmd/1yhAhEzlIJ5K1IfJXYQajwIUQgjxMx2Mds9NNAWV4r17byf0aVobXz3UIyDnk6siQ8l9UOh/CSGE+FkYDHIXgYjUMD4SX3oRnCi4xSToUA0KISRoOPuxd/+SXci6VhL4wnjoI81b2B/2sPX5I4YZ8hUmBFFAYE/0RHEKfgMpQCGEBLU/TlzFjK/3yl0Mp3gIGKr62/q8lGmxXuguY4lqjka1I/HD1N4BP6/Y+73Ydfmqa5BRcIuNaBSgEEKC3p6sPDzz7QG5i+GgNvLtnodz1NQjNVc35EdvaoyUOGV3Rt4/d4jsNRhK7oNCAQohJOg4u6R//bfyVjGO5pTb9FQT+PveXztK69PxMREa0ccot0FGehSgEEKCjnJ/89mLQqncRQh5roKQQKxtU7+WYw2NXGvqVGdgywSn2+WuwXGHAhRCCPGTKM4+QPnB3EumkhB/cHZv9/f93tvgvFli8C2vQMOMCSFBo2J2T+X+5qtUB3l4T/MuAGC30BzTDI/jCmLlLVQNwsBkqc0Ihu+mLSX3QaEAhRBC/GB32GPWx0UsHDmIk7E0vokOU6OwzCR3MQiCLwDyBQUohBDigwiUYb5mGVK5bKw298E35v4wVrm0FiFcptJJoybdFMUIhfdFyX1QKEAhhBAvjVNtwMuapdbnXfl/0Js/hDnGh+zSGSB+tAbxDQdOlgjC2xu+p4cpt0FGehSgEEKIV5hdcFLhFtVfuEX1l922XvzhQBWKyMzfMVGkViVpfkrug0KjeAghQSf99DVZz18b+cgMG+tx+jJGNSj+otwGCmnFR2pxZ6d66N/C+XDhUEQBCiEkeNz4sfdtxnlZi/F32BRR6UsQ5lG65n4aCtoiMdov+SoZA/P7kF+nzTl+OueDfRrh7TEdwYudG78aSu6DQgEKIYT4UTlT4wXjRLmLEbKU20DhJwpukpEaBSiEECKSmTn+6lxr7uGwTWAc2pd/gj2seSCK5RKrebdxcDLN6ertOeWqyaA+KISQkFJqMMtdBFllscp+ADuFVhhevgDTjdMd0pVAh3J4vl6LEu8VnVJi5S6CW3I2UCi3cSQ0UIBCCBFlx8mraDV3HV5fd0ye85+6GpDzJOA6RvPboIXRYZ/tFPZ/C81xlDUEA488FmmX7mHjLFHn9Fd84kvg89H9XaQrSA3g95oQifOnPiiEkJAxf+0RAMAHW04F/Nzn80px3/92+f08jbhL+CtsKt7Ufohxqt8d9kehDACw0dwJ75nusG7/2tzf+vgCi8cOoa2/i+pX3VPjkBDtWQdfpbF0klXuzddrSqxm8xMKUAghosh50c+6VuK3vHkIeFezCMd0E7BZ96R1ezfevqZIBTPCOQMA4CnjIyiDzrrvK/Ng6+NaKPJbWcXy+pYWDPd3hZVxbI8Uv+Trr74i1AeFEBIy5Lwf+LOz5038foxU7UQYZ9+kM1y12+65HsXWx8VVprDPYolYZ+4GAFhuHii6DEq+WSiWi7csEF1kq8bqqx/rhQlpqd7l5XtxQg7NJEsIIQBmqL9zul1gHHgIEG78nmvNnwUAFLAIp1PYzzJOwXfmvtgmtPdfYUWqqYFPoG/6nVJq+S1vf9VcKrkZjGpQCCGiyHk98+d9Np4rcLqd5xj68fsBAEm4hq+0CwAAZ5nzGT1LEIYNQldRo3eI/N4f21nuIpAqKEAhhBAAxcx1Z9Bl2jfQhLuAnWGVQ4nb8ZkBKJU0vI3rIiRe98UvJAiY7+nWAD0bx3txaumi9ZpZx+UeBSiEEFEUXCPstVgUohl3wW5batlXds836mb7vRxKu0lFhwXvGkJiprr39jsdyAnwamIzHQUohBBRxPxq/HT7GYxY9Adyiw2SnNtf1+h4rgA8Z8n8V3M33F0+F7J0W/TbRCjeHRalo26KRD4UoBBCRLH9tfnlzrNu085fewSHLxbgvU0nJTm3v+7f0bBMvHZOqIMpxpnYzVoCAGYbH3Z5zMtGz1czDlZhmuC9RYhrfpG/WrC6Eii5M6u/BO+3jxAiu3c3nfAoXblJ2VPjd+GPAwCKqgwbXmUz8ZqtGYbH8Il5hL+LJRkGoG+z2qKPk2c1G+n4u/zB/v4oHQUohBBRZJ0HxU9tPC9oLP1N6nNXPEp/gYm/2XvCn70MFt3TyY+510zUB8W/KEAhhIgTYlXNYSi3Pl5r7unRMf+w+v4qjl8wxhAbIb7Dq1Qf9dKJ3dCxQazXx+954WY8elMTUce46iSbEK1z3KiA7snyl0B5KEAhhPidkmOau1TbrI9fNTn2K3ncMM1hWz6i/FKWUP2VPKBFAtZM7Y36tcKrT+xEXKQWWrXz25WczSwR2uDpRKxTBd/tPvhKTAiRFWf3OLA3B3/cv402E2oXwvEG+qPQC6lly6U/cRDw96fbPDHa5zxcNbO4+m66Su2NF29r49VxgGPQ7s9Osm3r6TGpb2Ovj5eLqABlwYIF6NatG6Kjo5GQkIA77rgDx48ft0tTVlaGqVOnIj4+HlFRURg9ejRycnLs0mRlZWHEiBGIiIhAQkICZs+eDZPJ5PurIYT4nZJrQ7wRcWNl4p/N3eHuNjHTMAXXWRT+Vf5CgEomHQbljQKZObg5HuzdyOm+9TP6+e28Uga59WLD0bquXvRxjw9sig0zb5KuINVYO70vYsKdN/Hd1jEZANCodmTAyuMpUQHK1q1bMXXqVOzcuRMbNmyA0WjEkCFDUFxcuXjWzJkz8dNPP2HVqlXYunUrLl68iFGjRln3m81mjBgxAgaDATt27MBnn32GZcuWYe7cudK9KkKI3yjrNue7WM6y6nAuc3+jWS30Rafyj/AXa+W3ssjRwJMaH+Fynz9jmicGN3PZbNMiyUnNiovIQq4mnqFtEl2WvzqzhrRA0wRxzYT+av4b0CIBvz7RFz8/3scv+ftCVAPaunXr7J4vW7YMCQkJyMjIQL9+/ZCfn48lS5Zg+fLlGDjQspLn0qVL0apVK+zcuRM9e/bEb7/9hiNHjuD3339HYmIiOnbsiJdeegnPPPMMXnzxRWi1tH4FIcQ5f4yaqAVLgHLdo34l/r0ZytEF5YtJPdB34ebAn1hRxL3x+jA1Prq/q4wlkFYrL2qBAsGnPij5+fkAgLi4OABARkYGjEYjBg8ebE3TsmVLpKSkID09HQCQnp6Odu3aITEx0Zpm6NChKCgowOHDh52ep7y8HAUFBXZ/hBB5yNlU4I8beEUNSh7zvT9EMGoQF4EkvfN1iKT+rH36/Lwoi8JatYhIXgcogiBgxowZ6N27N9q2bQsAyM7OhlarRWxsrF3axMREZGdnW9PYBicV+yv2ObNgwQLExMRY/xo0aOBtsQkhMpCqGt4fvzJjK2pQmH9G5ihBdYFBIOfzkJ+z1yp/JEMzyTryOkCZOnUqDh06hJUrV0pZHqfmzJmD/Px869+5c+f8fk5CiHOhdpmM5yw1snl+GjoshtIChVD7rINZqA5Bd8erAGXatGlYu3YtNm/ejPr1KycsSkpKgsFgQF5enl36nJwcJCUlWdNUHdVT8bwiTVU6nQ56vd7ujxAiD9sfcoH+USf1RToCZWjBWX7wZLEESfNWkuoCn0B1NHX2ffm/uzvgnm4e1Ip78dmH4lT0NSlMERWgMMYwbdo0rF69Gps2bUKjRvZDxLp06QKNRoONGzdatx0/fhxZWVlIS0sDAKSlpeHgwYO4fPmyNc2GDRug1+vRunVrX14LISQAQumi34X/B2pOwBUWg1OsntzFkaWTLOAmgJH4o3b2+u7qUh+vjW4v7YlEloEok6hRPFOnTsXy5cvxww8/IDo62tpnJCYmBuHh4YiJicGkSZMwa9YsxMXFQa/XY/r06UhLS0PPnpYppIcMGYLWrVvj/vvvx8KFC5GdnY3nn38eU6dOhU7nbApiQoiiSHzTWrP3Aj798ww+GNcF9WLdzzQq5b2lG3cMX2hfAwCcYskS5qw8IXFTDvFOsp5+REH0knwmqgblgw8+QH5+Pvr374+6deta/77++mtrmrfffhu33norRo8ejX79+iEpKQnff/+9db9KpcLatWuhUqmQlpaGcePGYfz48Zg/f750r4oQIouD5/Ox4q8sUU0xM77ehwPn8zF3zSE/lszRePVv1seFzLsp2ENdMNSWiQ1CgjVWq+gkG6zl94aoGhRPLjphYWFYvHgxFi9e7DJNw4YN8csvv4g5NSFEIdzdD0a+tx0AEB+pxZA2lX3KtvxzGWM+Sscbd3VAiouJwQrLPJhNWsKrswqC9fF1hQwx9ldNR0jUoLgQKq+tujiLOskSQogIri6q/+QU2j0/l1uKXWdy8dSq/S7zMjOGXaevYds/V1ymkfIS3YE/ZX38tbm/hDmHDkU1kXjVSZYEMwpQCCGi+HLTulZc7nJfxtnrGPPxToz/9C9cK3KdTgpaGFGPuwYAuNfwb2SwFn49nzv9W9SR7dwVAvXj3B+1AKKbeIK8JqImBV0UoBBCFOdqkcGv+deCpYbHxHjsFPy3to4nlHzDkbpsPoUGiqrOkV51701N7INCAQohRBQ+ADeKJ1buxc8HLjlsl+rXb8XkbNcRDSbzZdD2Ffnr171Sag0CXQxns68q450QTymfYSBRgEIIEcWT+MTVtNyeTtd9LLsQU5fvcdgu1SU6jrPUoFyrZgXjms7Vx3Vv95TAFkQhbm5tWZblwT6NqkkpXmjXD3lH1CgeQgixJXZ9EKX8CmzOnQcAXFVYgOKvd0fKfL+b0gvt68dgxV9ZEuYKfPpAVzz97UG8PaaD3fb5t7exPFDAd+e9+zrh8MUCdKgfK3dRagSqQSGEiCLn3Bhnr5VIkk9DzjLJ5BGWKkl+wc7Vrd/ZZ92lYS1oVN7dOtxNuT+wZSJ2/3sQ+jaz7zSs5r2/TTn7pvoS5+jUKnROqQUV7/7/wLAbQ+zH9ayZNU1SoRoUQojklFJT4ko4LJ1wlTL/ib8p/OOwclsjF0SdZN+5pyN2Z+aiR6N4fLlTmpqmmriaMQUohBBRQuE6Gc5ZhjGXQitzSezJFUi4+kil/qz98frEFjEQwXOYRuVQE1Sd6krlTbnv6lIfozrJv8aUtyhAIYQEjFJ+BYajIkBR1vpf1a06LHW+FU0VgYqLvDmPL18ZhXzdZPN/d3eoPpGCUR8UQkLIdxnnMeydbTiXK01fDbn9efIqhry9VfJ8Y7liAEApkz9AkbP5RVXNHVwJ9/fq3p8gab2qlhLea6WhAIWQEPLkqv04ll2IF37w38J7gawFGfvJLvyTUyR5vq25swCAY6yB5Hl7Y+qAJgCAF0e28Uv+rm7y1XX2DHZKqbEj3qEAhZAQVGIwS5rfrwcvYdT7f+JcbknQ/9ILRxkibvRBucBqy1waSzPE7KEtceDFIRjerm5Az10RoLj8TH24wdev5bhCtCL6oEhfBOIn1AeFEFKtKV9ZJk17bvVBj351K/mXa8UssmVMg2KEyVyaypu2Pkzjv3O42O6vCpSXbm+D+CgdHvuq6mR7AQwPlPsVdIoCJ0dUg0II8VhBqVHuIvgsHpYA5SpiEHR3MYlZa1BcvA3evjv3p6UiXKvy8ugqZfC2ECF6x0+Nj5S7CAFDAQohxHOcnNO0SaM2lw8AyFXIHChyVjbpw/1Xa+OMN0081R0jurZOoYGLp6+ibzP5myUDhQIUQojnfOxEYDILEAR57xBjVRsBAGdZoqzlqCDmLW2aECXZOZonRuHDcV0AuF4AUvJ5UKTNzpKnyO9k19RafihF4Ci5+VRqFKAQQkTx5QKZea0Ety/+U8LSiFMb+Rio2gcA+MJ0s2zl8NaEXqmS5fXbzJvQqq5lLaKacMt76fY2mD6wadDPDVKTUIBCCBHF9mbmTaxy8EK+ZGURq6J55yrT4y/WSrZyBJ53dRdB3aBXpegp8ZF4ckgLxEfJP/eNrx4f1AyNa4d+XxQKUAghHlNo873HYjnLnCp5zLumErn5K1wIVLOBN9O1V1c0l2UP9i+rG7Nubo5NT/WXuxh+RwEKIaTGaMRdAgBcYnEyl8Q73t5zve06VIO6OxAFogCFEFJj1OWuAQDOsMBOiKZ0gQpE5KzUUPoK28QRBSiEBNjlwjIs+PUozl4rlrsoogXbNT4RuRjB7wQPAQAQeWORwCI4znIayqr72KSeB0VKwfadI9KhAIWQAJu2fC8+2noao97fIXdRZBOoX7O7wqZhsXYRxqg2AwAiUQoAKGbyzyAb8uQOLJQQXRGfUIBCSID9nZkLALhWbJC5JL6z/eVdWOb5LLOBmAolhcuxPh7EW6Zcj+MKAUARU9x7w+tJVasJCF2N1pF8HhQvPnepymB7aiUONZY7nlMiClAIqcFyiw0oLjd5nJ65uYy+tPaIx/kIAahBqY3K4cyDVXsxnN+FIaoMAMA/rL7fz+8P/nrX/NIHxUmeAe0H4uZUd3WpjyPzhwauLAGUoA/+YdQVaLFAQmqo/FIjOr+0ARwHnFkwwuf8/s687nHaQAQo8zSf2z3/QPtf6+MjQkO/n99Tj97UxO/nqPpuvziytUfHeTP8+K4uroM/f3zqnhaxarIIrbJuf65eRof6Mdh/Ph8jOyR7lE+iPgxLH+iGqDBlvT5vBP8rIIR45dgly6J5YmIFqSbuCsQP6Q78aZf78qCMeVD2vHAz4iK1fj9Pv2Z17J7XqxVh99yXT3XagKZ4b/NJAECHBrF44672PuTmqLrviqffJX995dKaxOPIpQJo1f5pkPj+sd4oKjMhJsLzdZMGtEzwS1kCjZp4CCEec9fEI4a/a1BUMKOARTjdN8XwBJTSgzIQwUndmDC8fGdbt2l8majN9tC4CI01L61K5tuLFy9p1s3NAQDTBzb1+JinhrTA3Ftb4/eZN4k/oQsP9m4EAJgxuBlUPCcqOAklVINCaoSdp6/h422n8Z/b2qBBnPMbV6BQZzj/d5JN5q5Cz5WglGnxnHES3tZ+AAD4r+lO/Cr08O/JffTITY3x0VbntT/ehBHpcwZVm8aXcM3VsT0bx+Om5nXQPNGmtkrGTrKemD6wKe7sVA/1a3k+DD1cq8KDfRpJWo6ZNzfDxN6posoRiqgGhdQI93y8E5uOXcbjK/fKXRTF8DZGsL1heNvk4+8alHo3JmTLZrWwWuhr3X6OKb/qe85w12sESfWuOXxqruZB8SE4UPEcPnuwO/49wrP+LtUZ0tqy+nTtKmvpuCyjV8EQhwZxEbKvGKyUcsiNalBIjZKdXyZ3EYKaVHEFE6TJx5X23CkAwHGWAgAYXT4PvfnDWG3u498TS6xWhAbXSzwfvi236m6ovnx92taLwean+iMhWgeTmaHD/N98yI0EA6pBIYQEnL9rUOJuLAp4ntUGAGSwFlhkHgUzVH49b1VROjU+f7C718e/NlraDqcVqsYRvIvAQmwNWXXDiH0dZtyodiQideoa2yfDnUEh0jHWFgUohASYUipt5ZxC3N8BSiwsE7IVsOBekj4uUhuQzqauvpMnLxf5/dwBI9P3fcGodkiI1iE+AB2iQw0FKIQEmJjrZHG5CbszcyEEYupVD3gaV7yx/jiO3hjG7DQficrjSls+EwCQi2g/n8m/qr7fgQ5u3X2GiqeQXwL3dk/BrucGoUVScH8X5UABCiEKNvaTXbj7w3R8lp4pd1FEm/P9QZf7/F2D0vDGNPf7BN8mQVsowZwe3vRzvKl5HTSqHYmODWLttgdiJtlvHkmzPuZF3iH82QfFV1INkfeGJ51dvSndc7e0tD6uF4IjfqiTLCEKtu9cHgBg1d/nMbG3tEMZvblgH7lUgCMe/qrm3VyTpY9PGKJRikJEoBF3CdFcKcyMw2nm2eybrrRNjvG5ZN6MdFo2sRsYA3h3b6IP3N0vk/SV6xRJNTFfhYA2Kyqj0tGvHu7XBK3q6vHDvot4ckgLuYsjOQpQCCFec3ejU7v5+S11Dcor6k9xr2oTPjaPwKPqtQAsQ4pLfFwUUIpRnpE68R1zOY4L6PwftoGI3TByBTSTRFczZbunRXQXbNWOkr9/iLdvdd9mddC3ykzBoYKaeAghfuGueUDKLjVqmDBWvRE8x6zBCQBEcqXSncQHVZtplMhVICJ1fCKm1u7VO9thdOf6GN62bjV5WvzntjYY07WBqHO/P7YzRrSrG5D1kJQQ7AUbqkEhpKbycxW42xqUGxGKWYJI5RZ+l9Pt042P+5y3FDiOw6hO9fD93gteHa/0vhP+cl+PFNzXI8Xj9BN6pQIAvv77nGWDB0W/pV1d3NLOfQBE5EM1KIQEAYExnLxciHKTWe6ieEytcn2HqGjh+abiZuKDRdrFDtteNd6LnYI0M5hKYc4trdCveR18OK6zX/IXu1Bd1eYOV4FIMPzqD4IiEi9RDQohQeBYdiEGv7UNAJD52gjJ82eMSf5rWe2mg2dFH5RjEg9jzWa1oIYZn5uHSJKfVG9JnWid1xO2edJdx9diujre1QRu3qJOskQMClAIqaFsr9+MOd6MjWYBJjNDuNZ1J093ty+VBwGKr0FRPPKtjx8wPI0MoTk4CCiDzs1RoUf0vdjDt13sp1NdeooZiBjUxEMIceqmhZvRau46lBo8a1aqevPxJEC5WlTubfEAAO34MwCAU0JdbBE6ohARKEBUNUcFl0A0s7g6R0UNSnSYZ1PLKyoAUVjbj9RDtmsCClAICUGeXAptq9ud3Vgu3lhY8dDFfCd7neVnn4vKg1m+1h645FHergzkLatTH2CNfcpHyQLSxONqaPGNxx/d3wXNE6Pwyfiuvp0ogBGMqkrUJefSDsQ71MRDSA1lOzrEElw4v83d/WG6h/nZc9NHVrKbRQve0sl2u7mdNBnWUK5+3VdsbVsvBr/NvMmDfJTDXSdtEhyoBoUQDzDGFLMejjMfbzuFdzeekLUMDuvGuGmb8PadTOUuIY0/DAC4R7UJPfhjAIBTPswY+6CbGXr9WS3vrglMLLHNQFWT2x5v+zlK3bwUyCHTUnfwJYFHNSiEeGDckl24VmTA2ul9oA7A6rJilBnNePWXYz7lIcVto+rN5/z1EtdpvTihDgb8rp0NNSc47Mti3i81P3dka3z65xmvj/eWpwHKg30a4eNtpzG0TaKfS+QoGG7yroooZQBI5EEBCiEe+PPkNQDAictFaFVXL3Np7Hk72ZldHxQvI5TMayXILTYgLlLrkMfuzOveZepEfe4KtuuecLrvU9Mw5EJZn4knqvaRcOXpoS0wqGUCOjSIxaqM807TiP38qtZu2T7zpQaluvSB7AdC8UnwowCFkGrYdv6kjnaO5v14GIwxnL/u+dTyx3MKRa1/4io4AYD5pvEe56Mk7uaJsUun4tGjcTwAoJPNtPn392yIL3aeBSDB2kY2kYVtXh7VoNikqa4Y/vjv4+qcVTtpy/1/NwgqoxSHAhRCqiH3ha06Ulz4fOkb8E92IY7nFIo65vEVe70+n61FpjskyUcO3qxU3LZeDL5+uCeSY8PRIC7CGqD4umSAbUlEBzsK/Q+isJZY4gX6CIniFZYZMfy/f+Cd3/+R5fx2E5rZPDt9pQgD39yC71xUuytd1Yna7PaJuOmIDU68cYnFWR9vMHdGq7JPkVq2HG+Z/uXX8/oa/Ll7Hz2tQamqR+N4NIiLsNvma/9tu06ydtuV/7O/ujlcSPCiAIUo3ufpZ3H0UgHe+V2eUSqubjLPfncQp68U48lV+0XmJ0Wp/EtpZYyGpcNtNquFOcbJKEWYzCXynZydON2d2fb7Lnom2Wr7oATui0WdZIMfNfEQxTOaHUdtBJKrS2qJ0RTQcrjij2u+kuKTZFxFFGeZNO6W8gUB6xArdgE+Z9zVQMgaoFQ5tX0TT+XjYL7He9oJmSgX1aAQUg1Xo128DQykn1vCy+PcdP4N5C/d6gxX7QIAZAjNAjpaR4qPyd37qKRf+E8Mbg4AuKtL/SqjeMR1kq2Of75Vzs/vTR8foixUg0JINVx1IFXKPVxJwYT0GF7QfAUA2GruIEmOtSI0aBgfiX3n8iTJz5vzXy8xom+zOrKc35mbmtfBnhduRq0IDY5lV/YpkvoW75+vqvNMqwaAofy/JFRRDQpRPLkX2VL6/d8fk6wp5SXHo8D6eIPQxef8eA5Y+3hf6MM9W/zOH9+8n6b3wQu3tsbzI1r5IXfLujneiIvUguM48fOgKPQ/iNI6yVbMWHxTc+UEpkonOkDZtm0bRo4cieTkZHAchzVr1tjtZ4xh7ty5qFu3LsLDwzF48GCcOGHfuTE3Nxdjx46FXq9HbGwsJk2ahKKiIp9eCAk8QWAoM3q20m0o8r5pxbfzFpYZJcnP/Sge7/KUWlPuIgDgCtPjKGvoc34P9m6EerHhPufjKWdNJPVrRWBSn0aI1PmnArttvZhq07gL+u2DVWXd5MXwdpSUvwxomYAdzw7Epw90c7o/Ulv5fVBa2eUiOkApLi5Ghw4dsHjxYqf7Fy5ciEWLFuHDDz/Erl27EBkZiaFDh6KsrMyaZuzYsTh8+DA2bNiAtWvXYtu2bXj44Ye9fxVEFmM+TkfLF9Yht9ggd1H8ynUfFHnu4u9vOSV5nlVfSSDXTHGnA38SALBPaCppvoH67IKx+S34iuz8Zp5aOzLA5ahecmy4y75HMREa/Peejnjvvk4I06gCXDJlEh3CDx8+HMOHD3e6jzGGd955B88//zxuv/12AMDnn3+OxMRErFmzBvfccw+OHj2KdevWYffu3eja1bJ097vvvotbbrkF//d//4fkZO8X/SKBVTGV+e9Hc/Cvrg38dh65a2qVcrOucL1qQOiPUTwKeMkduZOYrP4ZAPCHIM1qxQp4WYrg7v+U6Ina7DKT/5f/nhduRrnJjBgPm/GU5PaO9eQugqJI2gflzJkzyM7OxuDBg63bYmJi0KNHD6SnW5ZsT09PR2xsrDU4AYDBgweD53ns2rVLyuIQ4rN95/Jw+kqx9bm/g5V95/Jw6oq45k5Py3T6ShH2ZNmsj6OA2iBX4lCANbq5qMNZ+qBsEjrJXKKaI8VuEjhlfS88ERepRd0Yx2Y8pX3HSfUkbQTNzs4GACQm2q+6mZiYaN2XnZ2NhAT7lUfVajXi4uKsaaoqLy9HeXm59XlBQYHTdIRIKTu/DHcs/tPlfqmvdzkFlefLfG2Ex8d5Wo6Bb24FAGx/ZgDq17KfidShiUfma3kqZ38tOO/DasXOBGqGVKXNxHp7x2ScyClC90ZxLtPERni+RhIA2b4sI9rVxbnrJehosz4RCS1BMcx4wYIF+M9//iN3MYgLyroESyfzWrHDNrs+KBL/ujyXW+LVcWJLcfpKMcI0Khw4n+8mT3kjlDpcnvXxO6ZRkufv6a9pX98Ff/9qv6tLfXybcR5D2yRi/eGcatP/955OYIx5HDjJHai6s3hsZ1GvhQQfSZt4kpKSAAA5Ofb/UXJycqz7kpKScPnyZbv9JpMJubm51jRVzZkzB/n5+da/c+fOSVlsonByXX6qXZlV4ov34Yve1QyKvQlyHND15d/xts3aRkobxdOTPwoAuM6isFjCBQHlfl1Se/mOtvj8we549U7P++iE0g1dzGvxdGg5UQ5JA5RGjRohKSkJGzdutG4rKCjArl27kJaWBgBIS0tDXl4eMjIyrGk2bdoEQRDQo0cPp/nqdDro9Xq7P6Iccl3wDp7PR+/XNuGn/Rddpnlq1X7c+b7rZhqxmIvHUpj34+HKvN3cSX29yTo9vmqA4tspfDZRvR4A8IO5F4wyVvQqPaAJ06jQr3kd6GxGfUj5v9Gjl6/wgOe1Ue0wqU8j9HDTrEWUSfT//KKiIpw8edL6/MyZM9i3bx/i4uKQkpKCGTNm4OWXX0azZs3QqFEjvPDCC0hOTsYdd9wBAGjVqhWGDRuGyZMn48MPP4TRaMS0adNwzz330AgeIsqjX2bgQl4ppq/Yi5EdnH93vnWx0vCn288gtXYEBrZMdLrflUB1tDMLDGqVh9XwIvP+bEemy32r/j4HrZrHwJbS9vkQg0fl2ks/m3tKmrev91KtiodBxNpQgQreI7UqNIgLh8EkIFEf/AspSume7ilyF4F4SXSA8vfff2PAgAHW57NmzQIATJgwAcuWLcPTTz+N4uJiPPzww8jLy0OfPn2wbt06hIVV/qf56quvMG3aNAwaNAg8z2P06NFYtGiRBC+HhCJX1/hyk3eTxO3Juo75a48AENcZFQAu5JWiU0otAP4NVkwCg9rDqRA8KYZtWTceu+yw/+a3t2LBqHaY/e0BAJahmnJpxF0CABiYCntYM0nzrngb+jWrgz9OXIVWJa4SeVjbJPzopsbO8XyBCWg5jsPmJ/sDkHaNH2+aDwmRiugApX///m6/tBzHYf78+Zg/f77LNHFxcVi+fLnYUxMiiZz8suoTwfnFdtryvWiaEIWWSXq3NRe/Hc6GSWC4pV1dr8ooZi6K6jq05pUY8NWuLLdpLheWY9Jnf1ufm2RcQfoz7esAAC1nhhn+mbBqYu9UJOh16Jbqvtq/6nurpAX+qlKLDLYk42bRSUJ8QWvxkKAl18Vw/aEbncBdnL/cZMbDX2Tgsa/2IK/Eu1l2zUL1L+5yQZnlx4KTpLvO5OKtDZZOsLO+2Y831h8Xd36Z3twWXBbqc1cBAKcF553mpaBW8bi9Yz0ki5z2vqbVEEj9LRjcytJ02M6D6fgJoQCF+KyGXbOtN29XtRxGc+X2onKT27wMJuc1Fbszc90e90V6Jrq/uhH/99txlzeRRRsta2Bt/eeK27ycMZnlCVDW6561Pp5mfFyWMtiq+hGP6yluPaBgHzHjUZxq8xqre7lv/qsj5t/eBksnOl+PhhBbFKAQxXN1kb/m5RpAnt56Nx51Pq/Eoo0ncDGv1KtzV/W/P0473f7gsr+dbq/wwg+WET+LN5/yS01Sfqmx+kQuqGFCGn8YYSivPrEbx5n0yyf4Mr/LpidvQucb/Y88Ph+1ediJCddgfFoqakfp5C4KCQIUoJCgVF3NhBT+98cZl/ue/f6gJNXfO09fE31MICZRu/Xd7V4fO1v9NVZoX8E7mvfttrfgsvCm5gO045wHZQvVH1kfjzc847f+J96qE13zbqoUXhE5UYBCZGU0C9X2t3DWDOJJHw1/svT/sN/m7agib9hWKsk962uFSJTiR+2/8ciNBf6GqXbjP+qlqLjNrdc9i9GqP/CT7nnUhW1gxtCIu4R/qbdatxwVxDWl+AtVgBAiHwpQiGwMJgFpCzbilv/+4TLN5+mZ+O+NvhRKYumbWnn3WnfoElo8vw5f7TrrtE/OkYsFWPDLUVwr8q3Zo4LtOaq7iQaqF8Rs9ddoz9vXOk1Qb0BT7gK6csfsto9V/175WLURm3VPWp8vNw3AFcT6tayesv2MvelPEvx9UFx/ufRhlkGgcs6ZQ0JbUKzFQ5TN22vwPzmFuFpkwNUi131J5v5w2Ol2ua/7DMwuMHj0yz0AgH+vPmS3ZHpFmlsWWYKwpX9m2uXzx4mrOHA+D8vcTJ7mcG7FzPrKwIOhE3cCB1gTpPFHnKZqxGXjf9q37LZNUP2G/zONAQC8ovnUbt+rprH+KS58qxHx5isXyn1Qtj87EDn5ZWiWGC13UUiIogCFhByjWcCu07no3DDWb+dw18Jke1Pqu3AzHurTyPrc2Sykt70nfip+juOsd1upamXESMZV/KKbg1jOsqDiYtNtiOWKrPublH2BPbpHEMOVOAQnABDNlaI+dwXnWR0YmApaztI8VsTCUIQIh/SB0qquHg1qheO3Izl4oHeqbOUIBvowDfRhtL4N8R9q4pFAmdGM//x0GH+evCp3UQJG6l+GomesdLPvrQ3/YNySXXjkiww3qXwjMOby13jV4OWT7a4723rL9vV7E+D4aq7mC2twAgBT1T8ikcuDmXFoW/YJzFDhBKvvcNy9hn9bH2/XPQEdDDCg8iZ3ivl3uYvqat44AIvu7YSvH+6J2UNaiDqW1LwpB4h/UYAigSXbz2Dpn5kY+8kuuYsCwNK3Y0/Wdb91JD14Ph89Xt1YfUIRxMY7zpIXlBlx6EI+vtp5FoCl+cRf3JZXorfdVc0Ig2UqfE/548Y6TLXb6fYV5oHWGpBW3Fnr9gyhGcYbnkG60MYu/Q/aFxDFVc7s+6FppGRl7Ne8Diak2Xe2rba/DmdZgK9H43ioVbyo72XdmNBbAyeEW6hIEKAARQLnckvkLoKdZ787gFHv78DCdceqT+yFaSv24HKhtM0KFdfBEzmFeO3XY9XOwOrswjnkrW249d3tKChzPwRZiosuY8xlrY9Uo2q6vPx79Ylk0JrLtD6eZHgS11hlH4RXbPqPPG18xPr438ZJ2CZ0AGBfi9KSPwfAsu7Og4an8KvQXbJyvnx7W/QX2YHTXTDHUf1AtUIxSCPyoQBFAkqr+v1+7wUAwEfbnM834auqs4xK8forbvY3v70NH249hefXHKrmAMdN2QWerbEjBfd9UPx7bjH5j//0L8nL05SrXCxvo9AFPcsX403jXbi5fCFKUXmD+lnoiR/MvbBLaIl/bJp70oU2GFb+ml2e803jsUnoDCkbCZwFit0buV97x10QorT/54HgabC9dGI33NExGbOqNIsR4gvqJEsUoepl8MD5/GrSy1v3LDDXJfB3ydJPed50tc2Lae7diUQpZqpXAQC+NfcDABihxrvmUU7TP2Gc5nT7MdYAX5kGYax6I1aa+uMr8yBJy2lV5cMY3tb9+j41MQiRwoAWCRjQgoYbE2lRgFKNS/mlSIgOc7uKKbXT+k50HxQv3/NL+WWYunyP3bbTV4oQpVMjQe959fT5666nuvf30NKLHq7GLLVIlGK77gnUujFaJ0vw5YbE4d+mSfi3aZLP5VLxnNP+VjHhjiNMqpuXpOremv5/u6a/fiIvauJxY/uJq0hbsAkPLP1L7qKEvKoL71VXQyLVdXPFX1kY+OZWdH91o7UvUXG5CZ/6MPImFK/pHAR8p33RGpxcYnFYYR4gc6ksEl1MQR8bofW4pm1MV8u6PzMGN3eZpibVrtzR0TKaauqApjKXhNRkFKC4UTF5VtXRIAaTgMKyysXUatKFSymkmlb+/9Yftz6uWPX3pbVHMH+t80nHPBFqvzqTcRWvqT+xdmgtZOHoV/4OrkDcwnn+8qmblXE9/SxeG90Oe164GQOqdKoV05QYSp/722M6Ys8LN6N309pyF4XUYNTE44X+b2zGxfwy7J87BDERNW+ioqoBmRSjG8Re3NMWbPL5nEDVNW2AvzNzsXL3OZ/ylLt/jJRqIx/bdDOg5ionmLup/G0YFXTpaJmkd7nP0+8Vx3GIi9S6T1ODRvF48n4Q4m9Ug+KFij4AGVm5MpfEvWCq2RFzUy8xSLmSsf2bdNeH6b5nGTrxCdJ10+yCk9nGh5EL1wEBIYRIhQIUtzy90wRRJCCBqoHPkUsFPufp6S/dlX9lofXc9T6fr4Lda5Gojj6Y45NHVT/iO+083KXaipZcFjScfVPaAaGxTCXzjq+fhe1XouK74irwD6WaM0KUQDn1tEFI6W3OgQqbPt52Gs/d0sqnPDx9K5/9/qBP56nKLj6RKE+lfy9ciUMBntWsBAB04e1XkL7K9NgjNMNx1kCOoilCzfoZQoj8KEAJYUpf6t2u/4dMd3X7MkiTZzD9kuYh4B7VZvTjD7icvn6x6Ta8YRqDYLxF+/q9Cp5PkpDQQwFKADDGZAkW/HVGqToL2t47fL0RmJysEuwJ29ciVZDkpyWQJMdDwD7dZOg5+zldZhqmIJYrwjzNF1hr7oE3TPfIVEL52X4nKv4Pc/D8+9o6mfrrEOItClDc8uxG7C72KDOaccuiP9C+XgzeuaeTROXyjMIrUOww7+ILqz9PXfPqONv3yCxRYLHrtHdl8VUb7gyacJfwo9Cr2rQpXA6mqdY4BCdLTMOxWugLAFhqHga5ak26NqyFv89e9zmfVnUrA4TF93X2Ka+Kd4LjOKfVbbab6sWGY0DLOpg2oJlP5ySkJqMAxS3P7ljufnhvP3EVp68U4/SV4oAEKD8fuGR9bBYYXl93DL2axKNvszp+P7cvfG0WmfCpd5Pp2feRlSZCmfXNfknyqepO/g88q1mBnUJrzDNOQB6ioYIZQ/i/8aD6V3Tj/wEALMJ7aF/2PxQg0u74llwW1umeRaaQiFQ+x25fatlyJ2eUL8JdPrknmj//q8/5NIiLwI/TeqNWhBYN4iIkKJlnmidG4eU72gXsfISEIhrF4wNP7mcqVWAv8rbTuAsM+GDLKdy/RPkz4SqhY2nV2WyVJBlX8bb2AyRyebhdtQP7wh7BSH4HToXdjw+0/7UGJxXe0yyCfYDNsE73LAA4BCf3GZ7zc+nF06qluzS1rx8rSXBiHcXjc06EEE9QDYoTO05dxf5z+SImeXK9T8NXXmjl6osiNX+8hKpvNWPA5+mZ0p+oCtt1bbzsxhIQ/VQHHLa9q33PTfqDyFSNBQBcZHFI5pzP2fOoYQZ2CG2lKaSMakfpcLWoXPJ8nV0C3ruvEx79co+TPYQQKVENihP3/W8XXl93DBuPXRZ97I4qK82qbWpQDH64Ay7Zfga3vvsHrhcbRB/LGMPpK0UeN21cLiizm+LfVsU6NmLY1lhULcP566WY+8Nh0Xn6Qhk1KAyPqH7CPapN0KLyve7NHwIAnGeOU4/PM05A57IP0bTsc6c5Vg1OVpt7Y6/QFP9nvBvrhO4Sll0+yyf3wM2tEyXP134eFMv/5WFt6+L4y8MkPxchxB4FKCJVdzO/73+77J5rbAMUk/QByktrj+DQhQK8v+Wk6GMXbz6JgW9uxRs269G4cq2oHN1f3Yh2L/7mtIq778LN2Cmyc+j0FXutj5UQGlwuCOwqwQ25bGSG3YddusdQB9dxl2orMsPGYo5mBV7TfIJ/wiYgDOVowl3ASNVOAJZgpG/52yhg4TgtJKFl2VJ8Zh6KXOhhghqtyj7F9+Y+Ts/3uGEqUsu+wkzjVNxpmI/3zHcG8uX6VfPEaPxvfNeAnU+nVjlsYwBGd64PgBbZI0QK1MQj0o/7L1ofe3JTVds08UgVoOQUlCEhWmfXXFRmFJ/3//1m6bfw/pZTeHpYS7dpN3lQm/Rdxnn0bBzv8fnPXqusdVFC5cVn6WcDdq77VBvxqmYJACCRy8N63TOIu7FSsK1jYRPtnu8TmuIaYtCp/GMI4MCq/MYoRRhmGx/BHqEZtgttkcui0Zs/jA1CF5jov7uknry5OU5dKcKafZXXhP+7uz3m3dYa+rCat0YXIVKjK5ZIT6zc57DN0y4Z5TYByt+ZubhcWI5b2tUVdf5fD17ClK/24MHejTCuZ0plGbzoF6JV8x4FTQfO52H2t459IKpyVoY/T15FucmMgS3dV78H0+RmvhrFb7MGJxVsg5NSpkU459hkt9bcA9cQAwAww/EXfAUzVPjSfLP1+a9CD1+LXIO5/l5OH2QZQmwboHAcR8EJIRKhJh4/s+3XYLaZweuuD9Px2Fd7cPKy5cZUWGZ0aD5y1t/j9XXHAACf/nkGA9/c6lPZ9GGexafLd2XZPXfV0Zevst1kFjD2k114cNnf1feRCfL4JAJleE/zX3ymeQ0c3Ad9afwR6+OHDE/iaeNk6/PXjfegVfkyh2G/h4RUPGGcJm2hCSFEwagGxc9sZxV11gnzQl4pVDyHAf+3BQNbJuDTB7oBANYfzsYjX2Rg+sCmeHJIC2v6OtE6ZF5z7JDqzcCaqgGFK56OPKpIdim/FG+sP467brTHA0BRuQm13CzfHiyzr9riIeAJ9fd4Qv09zrPaqM9ZOki/wpbgFdM4FCMczbjzeE79FTYLHTGI34ubbEbjLDT+C78LXQAAu4WWiEMBMljlZ71XaIpOvKVv0QTDM25rTfwlXKNCqdFcfUI/WD65B87lluCZ78SvvyTVSDMxTY9KaKYkJJRQDYoEql4My02WC3pxucmuVsTZTZjnLCv0Avb9PF5YYxm18e4m+86vuzOdz65ZajTbdTp1xmQW8OQ3+7Hixvlsy/3p9jMuj6v6+s5cLXaVEgCQtmATvt9zAfd9UtlhWMVzMJoFu1okW1O+ysCmYzlO9ykTw638Tjyh/h4ArMEJANyn3oxPNG8CYHhJsxQDVPsxX/OZXXACAF+bB1gfn2F17YITALjTMB93lM9Hn/L/Wpt2Aq1erXDc37OhLOfu1aQ2xnRLqT4hcdAsIQoA0Iam2idBjGpQfOBqRE+buevRo3Ecdpy6hjs61rNud1aDwoHzeFKq/BLnQ3wB4Ju/z7s99uTlQizbkYnv9pzHd3vO497uKXY1KPPXHkFKXAQGOxmqyXv4a9RdunKTgD6vb0JqfCS+fiTNYf/erDw8uOxvz07kM4bHVD8ihivCe6Y7UQhxk3hNUv2CFzRfuk2TpjpinYfEmaNCA4+Cjn1M3tEgHCzBpT9oVbxfht4DntcOhqrPJ3XHVzuzME6m4JIQKVCAYsNoNKC8tAiRKEUxwj0+rmrcYRIY/jxpGXK7eu8F63ZBYFiz9wL2ZNnXgmhVjgGKs9DHKHh/MR/81jaHbVUv4dNW7MGxl4Y7Sef5xd5VDUn6qWvIKShHToFlMi0hgG060SgBB4be/CHU4fIwX/OZdd8j6p9xSqiLJvwlrDH3wizjYxDcVCzexO93CE4yhGa4zqKw0HQPHlb/jLtUju91hVvKX0UjLhu/Bsn8Iyqe81uAcken5GoDa7H0YWoUlJnQsUGsJPkFa6tN3ZhwPDW0RfUJCVEwClBs7Pn+bfQ4+ire0HTHY8YZkucvMGDG1/vstvEcoKmmBmX13vO4s1N9t2m84WnfEk/vT1/tysJXVTrUVrhSWDnL54/7L+LxapqjxGjPncI7msU4yerhoNAIPwi9MYz/C+uFbvhE8yaa8RfcHt+Et6xfdIdqB86xBLxp+peTVAx6FOMz7et2W48L9XG/YQ5KEAYAeMr4KF42jsW+sEesaaYaHscCzf+w1DwcR1gqjrBUn15vIGlUvN8CFKlWxba1ZmpvfLHzLB69qYnkeRNCAosCFFtqSydO2xk83flqVxbOXivxuEPe9pNXHbYJDHjzN/cTpc38en+1AYqK51zWXjhjFFG1LsX0/CUGk/WxVMFJHAqwJ+xR6/PGyMYQVQaexLcAgOewwuWxkw2zcL9qA/qp7DtgTlevAQPwVpUg5SvNq+itqpzZ9h7D89gptHaadx6i0bJsKTrzJ3D8RlPOz+U9xb48v2mTrMfhiwUepdWo/BFG+E/jOlGYN7KNZPmJ6/garPUthCgTBSg2GK8DAGhhqialxdZ/rmDrP1cwsGWCR+m3HHec7GzNvgswmm060goMPM85vTAWlLoOnMQEJwDw9e5z4D3sIl3RqdYXYsvnCg8BPfkjUMOMkXy66ONPCsn4l2EucqHHBqEroo0laMNnIkNojmWa19FbdRiPq9fgcfUazDY+jBfVn2Gv0NQuOAGAnUIrt+cpg06xa9x8PL4rer+2yaO0ahXv8RCx3k3jrU2bnvA07uW54BzlRQjxDQUottSWAEXHeVaDUiHfTeBgy1mtRXa+/fTqJoFBy3Nw9mvM13lPbF3KL3WoYq9YoE8fpsEdnSo795ZLMAOuVDeYyaqfMUdjXzOy3dwGn5hvwRuaj1GHywcAfGi6FQUsEtuEdhDA4zH1j1hhHoA/hXZ2xxYiwloTMt74LI7xD0DDWUZhvaH5GADQxyY4+dbcD88YJyOY17R1VfJF93ZyqN3SqDiPKwZ4jkN8pBbXPFwXytMAZeecQTieU4j29WLx2rpjkgTM/tAwPlLuIhASUihAscHdaOLRedjEU8HT5hKT2fFKX7XZx1VNg7sRPN44cD7fyfBowbpA3+0dkyVdeVmKhfhG89scgpN9QhOMMz4HgEO38g9cHjvN+Hi1+Zuhwr8Mc7FaN89hXwGLwHTjdGwVOogut9I4+1gHt0rEbR2SnQQo9tVsD/RKRXJsGF795ZiTfDmRjRyefb8S9GFI0Fv6+CwY1S6gAYonC2mufqwXlmw/g2eHu18ughAiDgUoNpjKchH0tImnwoHz+R6lM3pQjWAUBJjLGa4W2f8K7TD/N1Flqs4fJxz7w9iVw8ygVXsXoPAQHEbCLNuR6VVe3bmjeF3zMRrxlXOknBPq4GbDQjTkcnCJxUHK2oy9rNmNWVwZnlWvQBKXi1eM43AFsZKdQ251onSIi9Qi16amo060JTif0r8JPthyyrpdzfN2QceLt7VBmdHsPEDxW4ntrZvRF8Pe+SNAZ6tep5RaeO++WnIXg5CQQwGKDU5kJ1mxTB7UtJjMDE9/u98v5xfj9NUiNK4dZXcTc0WPYkxQrUccV4ihqt1I5nIBAMeEBvjSPNhuXRgxWnFn8Zn2dYd1ae4xPI8y6HCc+XMSLw6vme7zY/7yUat47JwzCJ+nZ+LN3/5Bz8ZxmD3U8uv/mWEtMX1gU7Seux4A0KtJPLKrrPIs94ypLZP06NggFvvO5fn9XNT1hYSSm5rXwdZ/rqBXE88XdZUTBSg2mNpSg+KsiWfTsRynTTRieNJRdMEvR/H7Ud9mVI1AGR5Qrccx1gCvaz7G/0wjUAodzrEEjFL9gfbcaawReuM7c1+cY84X8Zv3w2GUGc3YX03tUBp/GG9qPrAGJbZa8ufwMr8UPfijeMr4KMrheqp7W3VwHa9qluBm1R7HPMuWogw6j/IhrmnVPB7q2xgP9W3ssC9Cq8a22QOw68w13NmpHt5Ybz/KzNXCjmJbBH1pQQzUPGyeTqJISDBYdG8n/HLwEoa3TZK7KB6hAMWGEGaZ2bMWV+iwT+wsp3VxDXFcAY6zBtZl7j3pq7Iqw7eJq8JRhg262ajHVY6meE7jONx2Bv89Zqi/x7umO/C26S4I4MFDQATKkMxdQ35pNI5lO74PtmarV2Kq+kfrcyNToQjhqGWzMi8AjFTtxD6hCZaYRzjkEYcC9Of3oRhh0HMleEL9vd208QDwpvEutOSzsMR0CwUnAZISH4GUeMsMu1XDEbWL4V8cLL/QVu+9gCR9mEPNi7P0StepQSxGdkhGwzhxsw0TokQx4Rrc2z14lo+gAMWGOcIyXDiKK8NE1a/4wdwb72gWY53QHcvNgzzKIxxlSNdNRyxXuV7NItMdaMxlo3n+OfBahvsNc2ACjyuobLfWwYBYFCEHcR6dh4eAQfwe3MxnoCWfhfa867V03JmuXoPp6jUO27cU34SHMMkaXDliuF/1u/XZiPJXcJg1skvRhsvEz7rnAAAvaL7CIaExdrGW0MIEAzRIwjXsDJvusmzzjfdjpXmAZRI0edarC7gODWKxPwBNF77QqnksfaAbDGYBj3yRYd3OcRzm394GbevF4JZ2SUhb4H4osy8ju6J0gbl0cRyHd+/tFJBzEULsUYBiSxeNYqZDJFeOeZovME/zBQCgn+ogmnAX8a25H46yhkjAdfTgj6IdfwYCOOwRmuEYS8Fs9dcYqdrpkO3jVQKA9Co35dNCEiK4ciRx13GF6bHe3A2DVXuQyZJgYGr8n+lfOMgaIQLlKEY47lFtwmuaT9y+lLXmnvjUNAz7WRPU566AB0MJ0+E6omGABgDDRu1T1llUq+pv3IqTYVtxSqiLwywVOawWPjMPwXlmCeIeUa2FnrOsqtyl7AOn68ocZqkYWf4yftI9DwD4WveS2zJXWGIajpdM4xAcv7HdqxWhwXUPR2CtejQN3VLjsOPkVbuFFsUY2SEZP+2/CACYM7wl7uxcD+dySzH6gx0AgHqxni/h4M6AG3P/PD6wKRbdWNCSAxAdpsGkPo3cHFnJkxEyrrx6Zzs89tUeTO7n2ERFCAkNFKDYUPEcclgtNOayHfZNUv+KSepfPc5riWk4ODA05S6gN38ImSwJMVwxanOOM3g25ivPV4crwDj1RgBAEmdZs6fqbKdV7RcaI4W7DAbgBKuPd0yjkS5UzqZ5ljlrb+Rwl2EeWvNn8ap6CcI4A/7P9C/U564iCqXW19qEv4QmsAQxk9W/OOTyrbmf20XvDrJG+MPcFn1Vh1ymmWucgB/NvVCASLfr4ASjCK3a4wClInjo1bS26PM0TYjCbR2SMaFXqjVAqVcrHAnRYbhmMyJsxWTxM9re0q4uPt52Gg3iHIObWUNaVAYoIuNJV/HJrJubV3tsg7gI/DS9j7gTEkKCCgUoNtQ8j1Xm/niGX2m3falpKPrwh6pd0wUAypkaDxmfwh9Ce+u2OBQgH5EwQwWAIRnXkMDloQV/Dh24k7hbtQ1/CS3BAMRzhWjFVz/PwypTPyw0jbFrJhLrOvT4U2iHmwzvOOz7xHQLHlT/ChNUuEu1FXWcBFYnhWT82/hgNWfhcL/xOeiNRRih2gUGDpdZLAbzGbiCWPxm7obDQbQ2jVgRWpXHacXWJ8we2sLagTU1PgKPD2pmtz/5RsBj27m7fi3xNSgdG8Ri05M3ISkmrJqU4iIUBobH+jfB+zbDmtfN6IsWidGiy0gICT0UoNhQ8cCH5lvRmLuIcmjwvGmS3f4ULgePqn7CaNUfuM3wEjJZEkxQ4V7VJryg/hLPGSfhO6GfQ7650Ns843ARtXGR1cY+c1N8jQF4zjTZZZl4CGjDZSKey0cjLhtjVRtxliVijukhN/1DfHcJ8XjFNA4AsNA0Bt2445ik/hXHWAp4CIhHAV42jfN4ZE4BorDCph/PJqGzX8qtNAazgCPzh+K9TSdRK0KLfefy8PNB581qrlZ4ntg7FUv/zES4RoW7u9ZHmEaFR/o1RnyUzhqg2E6q9+G4zsjKLUHnFEvwahuU8F4u/Ne4TpRXx1VYMbkn7v2fffOnwICnh7XE+eul+PFGrU/LJL2zwwkhNRAFKDY0Kh4MPGabHnW6P4sl4jnTQ3jO9JDd9i/NN3s910d1BPA4yBoDDNgCYKl5uF/OUyFMw6PMaD/aiIHHX6wV/jK6X38mEJ4Y1Az/3XhC7mJ4rHliNCK0ajw9zDLPyKkrRS4DlDCN89qWf9/SCre2T0b7+jEOM7tWsI07hrWta7evVqQWm568CeEianO84a6JJ61JPNZO74N/cgox6xvLPD8VswvTXCOEEGdCq8HfR00TfPuVGAqqBidy6d+ijtPtrualuKWd83H9zWw+07b1LL/On7vFtynJR9msU+TKz4/3wbieKXj1Tvu1fxKiXQ+TruNin1rFo0vDWi6DE8CyDo47jetEoW6MNB1kq0q6MQ191bkVRnZIBgDrsMa29WIQHaax7h/cyjIHz82tLf/GR3pWG0cIqRmoBsVGhFaNQS0TsPGY46rDNcWt7eti7QHnv/ArROvUKCwXtxyAKze3TsSGI/YT093XIwU5+e7n0KjqrX91xImc7Thx2X4Olrb1YqzbVkzuif3n8pHWJN7pVO1ROjWKPHhdQ9ok4fu97vsjtUmOwct3tHPYHh2mwa9P9MXlwnLEhGsw+oMdMAsMres6b9qo2q/EleoCFH/69Ym+OJpdgLTG9rNTvnFXe/yra310b1Q5dF4fVnnJqQhoRravi9pRWmreIYTYoRqUKpY80A2zbm4eVJPZSGXF5J6oFVH9r9hfnugryflOv3oLXrmjrcP2V+9sB5WLvhKu7sNhGhXG90p12D5vZGuM6lwPyyf3QHSYBn2a1Xaa979vaYUuDSs7HD81pDmeHtbC+nxy38qhszofZxdtVVePm5rXQccGsfhpWh+M6lQPH93fxS7Nx/d3wZiuDfBY/yYe5SljfIJakVr0alLbYXHJMI0KfZvVgU5d2bTUvVEcHurTCAtGtbOm5zgOvZrURhzVoBBCbFCA4sTjg5phwah2WPVoGsI0ynqLhrdNwmcPdsdaPwyx1Ko5u2aEf3Wt7zRdg7gIzBvZ2mU+dasZ7bH8oR7Y9ORN4HkOCfowdGwQa913e0dLs8CsIZahpmN7VAaKY3uk2E3Q9cKtrstQITZCi7f+1RG9mrgeuntr+7qY3K8xZg9tAZ4DHrmpMaYNbIbH+jdF90ZxiNSq8MTg5vj8we7YNnsAejSOs95Mv5zUwyG/+be3cdjmSutkPd4a0xENqsxUOqRNEl6/q73LfilVJeqrG2GjDBzH4flbW9fIHwCEEHGoiceNbqlxmDG4OV771bE5oDrHXx6GC9dLMfDNrU73D26VgAEtE/Dv1ZXzg/zf3R3w1CpLB8L/je+K1XvP45eDljlSPhzXGf1bJHh0w3p7TAesP5SD+3qkYPynf1m392teB9v+uQIAaBAXjtZ19Zh/e1v0eNUy74qK55HWJB6f/nkGGhWHhXd1wJXCcmw+fsWaR/SNKvqJvRvhvh4p0PA8DGYBD332N7afvIrlk3ugTpQOC9cfR7OEKHybcR6XC8vtyld1no81U3tjzd4L+O1INl650WejZZIex18eBhXH4atdlmHXTw9tic3HK5vfxvZIwb5zeRh0Y9Kw1nUrh6fe2r6utW+DO5uf6o/UG1O6t60XgyPzh9m9xysn94RJYNCqefRrXtkvZuecQVDzHMpMlVPcHp0/DGbGAjbLKQB8dH8X/LDvAp4Y7FlTECGEBAuO+TKdo0wKCgoQExOD/Px86PX+bbc2mgX8tP8i3lh/HJdu9IuYN7I1OqXUQkGpEWlN4tHs344TuGW+Zll3ZsvxyzALDJM+s6zlo1XxCNeqsG/uzeA4DqnP/gzA0q/j4H+GYtOxHCREh6FtPcvkZ7e9tx2nLhdhx7ODEBOhsTvHgfN5eHntUfyVWblQ3ztjOuIOm06cq/eex8yv92P+7W0wPi0V14rKseX4FdzSri7CtSowxtBojmUCtp+m9UHbenqsO5SNDg1ikRwbjsuFZdhy/Apu65CMXw9dQrfUONSvJX5dklV/n8Psbw/g+RGtnC5Q587fmbkwmAX0alIbeSUGdJy/Ae3rx+DHaY61SOsPZyM1PhItktzPpbH/XB7yS412QYe3dp22rHvUo3FwrBBKCCFyEXP/pgDFQ5lXi/H8mkO4r0cKbmlnP4yz1GBGicEEs8Dw5Kr9GNezIYa2sR/RUFxuQphGBaNZAMfB2i4/8M0tOH2lGHd3qY837u7gcF6zwFBqNLv9VV5QZsSb649DreKdNnvklxoRE65xcqRFRZC0c84gDybj8l5BmRH6MNfl8FSJwQStiofazagWQgghykMBShDJKSjD+sPZGN25PiID2DRga8fJqygqN2FIm+BYgpsQQkhwEnP/lvUn6OLFi5GamoqwsDD06NEDf/31V/UHhZhEfRjGp6XKFpwAlj4hFJwQQghREtkClK+//hqzZs3CvHnzsGfPHnTo0AFDhw7F5cs1dw4SQgghhFjIFqC89dZbmDx5MiZOnIjWrVvjww8/REREBD799FO5ikQIIYQQhZAlQDEYDMjIyMDgwYMrC8LzGDx4MNLT0x3Sl5eXo6CgwO6PEEIIIaFLlgDl6tWrMJvNSEy0n6ciMTER2dnZDukXLFiAmJgY61+DBg0CVVRCCCGEyCAoxmnOmTMH+fn51r9z587JXSRCCCGE+JEsQ0dq164NlUqFnBz7ReJycnKQlOQ4mkSn00Gnc70KLCGEEEJCiyw1KFqtFl26dMHGjRut2wRBwMaNG5GWliZHkQghhBCiILJNvjFr1ixMmDABXbt2Rffu3fHOO++guLgYEydOlKtIhBBCCFEI2QKUMWPG4MqVK5g7dy6ys7PRsWNHrFu3zqHjLCGEEEJqHprqnhBCCCEBETRT3RNCCCGEOEMBCiGEEEIUhwIUQgghhCiOfEvo+qCi2wxNeU8IIYQEj4r7tifdX4MyQCksLAQAmvKeEEIICUKFhYWIiYlxmyYoR/EIgoCLFy8iOjoaHMdJmndBQQEaNGiAc+fO0QghGdD7Lz/6DORF77/86DPwH8YYCgsLkZycDJ5338skKGtQeJ5H/fr1/XoOvV5PX0wZ0fsvP/oM5EXvv/zoM/CP6mpOKlAnWUIIIYQoDgUohBBCCFEcClCq0Ol0mDdvHq2eLBN6/+VHn4G86P2XH30GyhCUnWQJIYQQEtqoBoUQQgghikMBCiGEEEIUhwIUQgghhCgOBSiEEEIIURwKUGwsXrwYqampCAsLQ48ePfDXX3/JXaSQ8OKLL4LjOLu/li1bWveXlZVh6tSpiI+PR1RUFEaPHo2cnBy7PLKysjBixAhEREQgISEBs2fPhslkCvRLCRrbtm3DyJEjkZycDI7jsGbNGrv9jDHMnTsXdevWRXh4OAYPHowTJ07YpcnNzcXYsWOh1+sRGxuLSZMmoaioyC7NgQMH0LdvX4SFhaFBgwZYuHChv19aUKju/X/ggQcc/k8MGzbMLg29/95bsGABunXrhujoaCQkJOCOO+7A8ePH7dJIdd3ZsmULOnfuDJ1Oh6ZNm2LZsmX+fnk1BgUoN3z99deYNWsW5s2bhz179qBDhw4YOnQoLl++LHfRQkKbNm1w6dIl69/27dut+2bOnImffvoJq1atwtatW3Hx4kWMGjXKut9sNmPEiBEwGAzYsWMHPvvsMyxbtgxz586V46UEheLiYnTo0AGLFy92un/hwoVYtGgRPvzwQ+zatQuRkZEYOnQoysrKrGnGjh2Lw4cPY8OGDVi7di22bduGhx9+2Lq/oKAAQ4YMQcOGDZGRkYE33ngDL774Ij7++GO/vz6lq+79B4Bhw4bZ/Z9YsWKF3X56/723detWTJ06FTt37sSGDRtgNBoxZMgQFBcXW9NIcd05c+YMRowYgQEDBmDfvn2YMWMGHnroIaxfvz6grzdkMcIYY6x79+5s6tSp1udms5klJyezBQsWyFiq0DBv3jzWoUMHp/vy8vKYRqNhq1atsm47evQoA8DS09MZY4z98ssvjOd5lp2dbU3zwQcfML1ez8rLy/1a9lAAgK1evdr6XBAElpSUxN544w3rtry8PKbT6diKFSsYY4wdOXKEAWC7d++2pvn1118Zx3HswoULjDHG3n//fVarVi27z+CZZ55hLVq08PMrCi5V33/GGJswYQK7/fbbXR5D77+0Ll++zACwrVu3Msaku+48/fTTrE2bNnbnGjNmDBs6dKi/X1KNQDUoAAwGAzIyMjB48GDrNp7nMXjwYKSnp8tYstBx4sQJJCcno3Hjxhg7diyysrIAABkZGTAajXbvfcuWLZGSkmJ979PT09GuXTskJiZa0wwdOhQFBQU4fPhwYF9ICDhz5gyys7Pt3vOYmBj06NHD7j2PjY1F165drWkGDx4Mnuexa9cua5p+/fpBq9Va0wwdOhTHjx/H9evXA/RqgteWLVuQkJCAFi1aYMqUKbh27Zp1H73/0srPzwcAxMXFAZDuupOenm6XR0Uaum9IgwIUAFevXoXZbLb7IgJAYmIisrOzZSpV6OjRoweWLVuGdevW4YMPPsCZM2fQt29fFBYWIjs7G1qtFrGxsXbH2L732dnZTj+bin1EnIr3zN33PTs7GwkJCXb71Wo14uLi6HORwLBhw/D5559j48aNeP3117F161YMHz4cZrMZAL3/UhIEATNmzEDv3r3Rtm1bAJDsuuMqTUFBAUpLS/3xcmqUoFzNmASX4cOHWx+3b98ePXr0QMOGDfHNN98gPDxcxpIRIo977rnH+rhdu3Zo3749mjRpgi1btmDQoEEyliz0TJ06FYcOHbLr90aCA9WgAKhduzZUKpVDD+6cnBwkJSXJVKrQFRsbi+bNm+PkyZNISkqCwWBAXl6eXRrb9z4pKcnpZ1Oxj4hT8Z65+74nJSU5dBA3mUzIzc2lz8UPGjdujNq1a+PkyZMA6P2XyrRp07B27Vps3rwZ9evXt26X6rrjKo1er6cfXxKgAAWAVqtFly5dsHHjRus2QRCwceNGpKWlyViy0FRUVIRTp06hbt266NKlCzQajd17f/z4cWRlZVnf+7S0NBw8eNDugr1hwwbo9Xq0bt064OUPdo0aNUJSUpLde15QUIBdu3bZved5eXnIyMiwptm0aRMEQUCPHj2sabZt2waj0WhNs2HDBrRo0QK1atUK0KsJDefPn8e1a9dQt25dAPT++4oxhmnTpmH16tXYtGkTGjVqZLdfqutOWlqaXR4Vaei+IRG5e+kqxcqVK5lOp2PLli1jR44cYQ8//DCLjY2168FNvPPkk0+yLVu2sDNnzrA///yTDR48mNWuXZtdvnyZMcbYo48+ylJSUtimTZvY33//zdLS0lhaWpr1eJPJxNq2bcuGDBnC9u3bx9atW8fq1KnD5syZI9dLUrzCwkK2d+9etnfvXgaAvfXWW2zv3r3s7NmzjDHGXnvtNRYbG8t++OEHduDAAXb77bezRo0asdLSUmsew4YNY506dWK7du1i27dvZ82aNWP33nuvdX9eXh5LTExk999/Pzt06BBbuXIli4iIYB999FHAX6/SuHv/CwsL2VNPPcXS09PZmTNn2O+//846d+7MmjVrxsrKyqx50PvvvSlTprCYmBi2ZcsWdunSJetfSUmJNY0U153Tp0+ziIgINnv2bHb06FG2ePFiplKp2Lp16wL6ekMVBSg23n33XZaSksK0Wi3r3r0727lzp9xFCgljxoxhdevWZVqtltWrV4+NGTOGnTx50rq/tLSUPfbYY6xWrVosIiKC3XnnnezSpUt2eWRmZrLhw4ez8PBwVrt2bfbkk08yo9EY6JcSNDZv3swAOPxNmDCBMWYZavzCCy+wxMREptPp2KBBg9jx48ft8rh27Rq79957WVRUFNPr9WzixImssLDQLs3+/ftZnz59mE6nY/Xq1WOvvfZaoF6iorl7/0tKStiQIUNYnTp1mEajYQ0bNmSTJ092+DFE77/3nL33ANjSpUutaaS67mzevJl17NiRabVa1rhxY7tzEN9wjDEW6FobQgghhBB3qA8KIYQQQhSHAhRCCCGEKA4FKIQQQghRHApQCCGEEKI4FKAQQgghRHEoQCGEEEKI4lCAQgghhBDFoQCFEEIIIYpDAQohhBBCFIcCFEIIIYQoDgUohBBCCFEcClAIIYQQojj/D2NyWOsS0tuOAAAAAElFTkSuQmCC\n", 326 | "text/plain": [ 327 | "
" 328 | ] 329 | }, 330 | "metadata": {}, 331 | "output_type": "display_data" 332 | } 333 | ], 334 | "source": [ 335 | "import matplotlib.pyplot as plt\n", 336 | "# Generate recent 50 interval average\n", 337 | "average_reward = []\n", 338 | "for idx in range(len(reward_records)):\n", 339 | " avg_list = np.empty(shape=(1,), dtype=int)\n", 340 | " if idx < 50:\n", 341 | " avg_list = reward_records[:idx+1]\n", 342 | " else:\n", 343 | " avg_list = reward_records[idx-49:idx+1]\n", 344 | " average_reward.append(np.average(avg_list))\n", 345 | "plt.plot(reward_records)\n", 346 | "plt.plot(average_reward)" 347 | ] 348 | }, 349 | { 350 | "cell_type": "code", 351 | "execution_count": null, 352 | "id": "e33556ba", 353 | "metadata": {}, 354 | "outputs": [], 355 | "source": [] 356 | } 357 | ], 358 | "metadata": { 359 | "kernelspec": { 360 | "display_name": "Python 3 (ipykernel)", 361 | "language": "python", 362 | "name": "python3" 363 | }, 364 | "language_info": { 365 | "codemirror_mode": { 366 | "name": "ipython", 367 | "version": 3 368 | }, 369 | "file_extension": ".py", 370 | "mimetype": "text/x-python", 371 | "name": "python", 372 | "nbconvert_exporter": "python", 373 | "pygments_lexer": "ipython3", 374 | "version": "3.12.3" 375 | } 376 | }, 377 | "nbformat": 4, 378 | "nbformat_minor": 5 379 | } 380 | -------------------------------------------------------------------------------- /Readme.md: -------------------------------------------------------------------------------- 1 | # Reinforcement Learning Algorithms Tutorial (Python) 2 | 3 | This repository shows you theoretical fundamentals for typical reinforcement learning methods (model-free algorithms) with intuitive (but mathematical) explanations and several lines of Python code. 4 | 5 | ## Table of Contents 6 | 7 | - [Q-Learning](00-q-learning.ipynb) 8 | - [Deep Q-Network (DQN)](01-dqn.ipynb) (off-policy) 9 | - [Policy Gradient method](02-policy-gradient.ipynb) (on-policy) 10 | - [Actor Critic method](03-actor-critic.ipynb) 11 | - [PPO (Proximal Policy Optimization)](04-ppo.ipynb) (on-policy) 12 | - [DDPG (Deep Deterministic Policy Gradient)](05-ddpg.ipynb) (off-policy) 13 | - [SAC (Soft Actor-Critic)](06-sac.ipynb) (off-policy) 14 | 15 | All these examples are written in Python from scratch without any RL (reinforcement learning) libraries - such as, RLlib, Stable Baselines, etc.
16 | See [here (Minecraft example)](https://github.com/tsmatz/minecraft-rl-example) for building scripts with RLlib library. 17 | 18 | > Note : To simplify, any example doesn't run inference as a batch. (The agent always runs inference one-by-one.)
19 | > To speed up, please apply batch in practice to collect data. 20 | 21 | ## Example Environemnt (CartPole-v1) 22 | 23 | In all examples, I commonly use a widely used CartPole environment version 1. 24 | 25 | See below for the specification of this environment (```CartPole-v1```) - such as, actions, states (observations), and rewards. 26 | 27 | **Action Space** - Type : ```Discrete(2)``` 28 | 29 | - ```0``` : Push cart to the left 30 | - ```1``` : Push cart to the right 31 | 32 | **Observation Space** - Type : ```Box(-num, num, (4,), float32)``` 33 | 34 | - Cart Position ```(-4.8, 4.8)``` 35 | - Cart Velocity ```(-inf, inf)``` 36 | - Pole Angle ```(-0.41, 0.41)``` 37 | - Pole Velocity At Tip ```(-inf, inf)``` 38 | 39 | **Reward** - Type : ```float32``` 40 | 41 | It always returns ```1.0``` as reward.
42 | If completely succeeded, you can then take max ```500.0``` rewards in a single episode, because a single episode will be truncated on max ```500``` actions. 43 | 44 | **Done Flag (Termination and Truncation)** - Type : ```bool``` 45 | 46 | It returns the following 2 types of done flag, which is used to check whether the episode is done or not. 47 | 48 | - Termination flag : When the agent fails and cannot work any more, termination flag is ```True```, otherwise ```False```. 49 | - Truncation flag : When the agent reaches to max 500 actions (successful at final action), truncation flag is ```True```, otherwise ```False```. (The agent cannot work any more, also in this case.) 50 | 51 | **Sample Code to run CartPole** 52 | 53 | Here is the sample source code to run CartPole agent. 54 | 55 | source code (Python) 56 | 57 | ``` 58 | import gymnasium as gym 59 | import random 60 | 61 | def pick_sample(): 62 | return random.randint(0, 1) 63 | 64 | env = gym.make("CartPole-v1") 65 | for i in range(1): 66 | print("start episode {}".format(i)) 67 | done = False 68 | s, _ = env.reset() 69 | while not done: 70 | a = pick_sample() 71 | s, r, term, trunc, _ = env.step(a) 72 | done = term or trunc 73 | print("action: {}, reward: {}".format(a, r)) 74 | print("state: {}, {}, {}, {}".format(s[0], s[1], s[2], s[3])) 75 | env.close() 76 | ``` 77 | 78 | output result 79 | 80 | ``` 81 | start episode 0 82 | action: 0, reward: 1.0 83 | state: 0.006784938861824417, -0.18766506871206354, 0.0287443864274386, 0.27414982492533896 84 | action: 0, reward: 1.0 85 | state: 0.0030316374875831464, -0.383185104857609, 0.03422738292594538, 0.5757584135859465 86 | action: 1, reward: 1.0 87 | state: -0.004632064609569034, -0.18855925062821827, 0.04574255119766431, 0.2940515065957076 88 | ``` 89 | 90 | > Note : Call ```render()``` when you want to show the current state in visual UI as follows.
91 | > ![CartPole rendering](assets/cart-pole.png) 92 | 93 | *Tsuyoshi Matsuzaki @ Microsoft* 94 | -------------------------------------------------------------------------------- /assets/cart-pole.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tsmatz/reinforcement-learning-tutorials/d34677967c7fd62e0aa4541e316ab5244400ce3d/assets/cart-pole.png -------------------------------------------------------------------------------- /assets/discretize.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tsmatz/reinforcement-learning-tutorials/d34677967c7fd62e0aa4541e316ab5244400ce3d/assets/discretize.png -------------------------------------------------------------------------------- /assets/dqn-2-networks.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tsmatz/reinforcement-learning-tutorials/d34677967c7fd62e0aa4541e316ab5244400ce3d/assets/dqn-2-networks.png -------------------------------------------------------------------------------- /assets/policy.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tsmatz/reinforcement-learning-tutorials/d34677967c7fd62e0aa4541e316ab5244400ce3d/assets/policy.png -------------------------------------------------------------------------------- /assets/q-network.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tsmatz/reinforcement-learning-tutorials/d34677967c7fd62e0aa4541e316ab5244400ce3d/assets/q-network.png -------------------------------------------------------------------------------- /assets/q-table.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tsmatz/reinforcement-learning-tutorials/d34677967c7fd62e0aa4541e316ab5244400ce3d/assets/q-table.png -------------------------------------------------------------------------------- /util/cartpole.py: -------------------------------------------------------------------------------- 1 | """ 2 | Classic cart-pole system implemented by Rich Sutton et al. 3 | Copied from http://incompleteideas.net/sutton/book/code/pole.c 4 | permalink: https://perma.cc/C9ZM-652R 5 | """ 6 | 7 | import math 8 | import random 9 | 10 | class CartPole(): 11 | def __init__(self): 12 | self._cart_mass = 0.31 # (kg) 13 | self._pole_mass = 0.055 # (kg) 14 | self._pole_length = 0.4 # (m) 15 | 16 | self.x_threshold = 1.0 17 | self.theta_threshold = 12 * 2 * math.pi / 360 18 | 19 | self._state = [] 20 | self._done = True 21 | 22 | def reset(self): 23 | self._step = 0 24 | self._cart_position = math.tanh(random.gauss(0.0, 0.01)) * 4.8 # (m) 25 | self._cart_velocity = random.uniform(-0.05, 0.05) # (m/s) 26 | initial_pole_angle=random.uniform(-0.05, 0.05) 27 | self._pole_angle = (initial_pole_angle + math.pi) % (2 * math.pi) - math.pi # (rad) 28 | self._pole_angular_velocity = random.uniform(-0.05, 0.05) # (rad/s) 29 | 30 | # (CartPole-v0 uses numpy.ndarray for state, 31 | # but here returns Python array.) 32 | self._state = [self._cart_position, self._cart_velocity, self._pole_angle, self._pole_angular_velocity] 33 | self._done = False 34 | return self._state 35 | 36 | def step(self, action: float): 37 | """ 38 | Args: 39 | action: float value between -1.0 and 1.0 40 | """ 41 | if self._done: 42 | raise Exception("Cannot run step() before reset") 43 | 44 | self._step += 1 45 | 46 | # Add a small random noise 47 | # (The agent won't succeed by applying zero force each time.) 48 | force = 1.0 * (action + random.uniform(-0.02, 0.02)) 49 | 50 | total_mass = self._cart_mass + self._pole_mass 51 | pole_half_length = self._pole_length / 2 52 | pole_mass_length = self._pole_mass * pole_half_length 53 | 54 | cosTheta = math.cos(self._pole_angle) 55 | sinTheta = math.sin(self._pole_angle) 56 | 57 | temp = ( 58 | force + pole_mass_length * self._pole_angular_velocity ** 2 * sinTheta 59 | ) / total_mass 60 | angularAccel = (9.8 * sinTheta - cosTheta * temp) / ( 61 | pole_half_length 62 | * (4.0 / 3.0 - (self._pole_mass * cosTheta ** 2) / total_mass) 63 | ) 64 | linearAccel = temp - (pole_mass_length * angularAccel * cosTheta) / total_mass 65 | 66 | self._cart_position = self._cart_position + 0.02 * self._cart_velocity 67 | self._cart_velocity = self._cart_velocity + 0.02 * linearAccel 68 | 69 | self._pole_angle = ( 70 | self._pole_angle + 0.02 * self._pole_angular_velocity 71 | ) 72 | self._pole_angle = (self._pole_angle + math.pi) % (2 * math.pi) - math.pi 73 | 74 | self._pole_angular_velocity = ( 75 | self._pole_angular_velocity + 0.02 * angularAccel 76 | ) 77 | 78 | # (CartPole-v0 uses numpy.ndarray for state, 79 | # but here returns Python array.) 80 | self._state = [self._cart_position, self._cart_velocity, self._pole_angle, self._pole_angular_velocity] 81 | term = self._state[0] < -self.x_threshold or \ 82 | self._state[0] > self.x_threshold or \ 83 | self._state[2] < -self.theta_threshold or \ 84 | self._state[2] > self.theta_threshold 85 | term = bool(term) 86 | trunc = (self._step == 500) 87 | trunc = bool(trunc) 88 | self._done = bool(term or trunc) 89 | return self._state, 1.0, term, trunc, {} 90 | --------------------------------------------------------------------------------