From 90e9ed0d512e78a025adb7b2d880cfc058693857 Mon Sep 17 00:00:00 2001 From: Carl Boettiger Date: Tue, 20 Feb 2024 19:05:31 +0000 Subject: [PATCH] update --- .github/workflows/run-tests.yml | 44 ++++ Equations.md | 32 +++ README.md | 11 +- Scenarios.md | 37 ++++ hyperpars/ppo-caribou-v0-1.yml | 11 + hyperpars/rllib/ppo-asm.yml | 30 +++ hyperpars/tqc-caribou-v0-1.yml | 11 + notebooks/compare-solutions.ipynb | 209 ++++++++++++++++++ notebooks/optimal-fixed-policy.ipynb | 313 +++++++++++++++++++++++++++ noxfile.py | 13 ++ pyproject.toml | 11 + scripts/train.py | 11 + src/rl4caribou/__init__.py | 3 + src/rl4caribou/envs/caribou.py | 166 ++++++++++++++ tests/test_caribou.py | 7 + 15 files changed, 907 insertions(+), 2 deletions(-) create mode 100644 .github/workflows/run-tests.yml create mode 100644 Equations.md create mode 100644 Scenarios.md create mode 100644 hyperpars/ppo-caribou-v0-1.yml create mode 100644 hyperpars/rllib/ppo-asm.yml create mode 100644 hyperpars/tqc-caribou-v0-1.yml create mode 100644 notebooks/compare-solutions.ipynb create mode 100644 notebooks/optimal-fixed-policy.ipynb create mode 100644 noxfile.py create mode 100644 pyproject.toml create mode 100644 scripts/train.py create mode 100644 src/rl4caribou/__init__.py create mode 100644 src/rl4caribou/envs/caribou.py create mode 100644 tests/test_caribou.py diff --git a/.github/workflows/run-tests.yml b/.github/workflows/run-tests.yml new file mode 100644 index 0000000..1b680dc --- /dev/null +++ b/.github/workflows/run-tests.yml @@ -0,0 +1,44 @@ +name: Pytest unit/integration + +on: + pull_request: + push: + branches: + - main + +# Use bash by default in all jobs +defaults: + run: + shell: bash + +jobs: + build-test: + name: Test Run (${{ matrix.python-version }}, ${{ matrix.os }}) + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + os: ["ubuntu-latest"] +# os: ["ubuntu-latest", "macos-latest", "windows-latest"] + python-version: ["3.10", "3.11"] + + steps: + - uses: actions/checkout@v4 + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v4 + with: + python-version: ${{ matrix.python-version }} + - name: Install dependencies + run: | + python -m pip install --upgrade pip + python -m pip install nox + - name: List installed packages + run: pip list + - name: Run tests with pytest & nox + run: | + nox -s test-${{ matrix.python-version }} +# Codecov is only free for open source / public repos. Not really needed anyway +# - name: Upload coverage to Codecov +# if: ${{ matrix.os == 'ubuntu-latest' && matrix.python-version == '3.10'}} +# uses: codecov/codecov-action@v3 + diff --git a/Equations.md b/Equations.md new file mode 100644 index 0000000..0a31501 --- /dev/null +++ b/Equations.md @@ -0,0 +1,32 @@ +**Equations** + +$$ dW/dt = W*( \frac{(B^x*aB)}{(1 + M^x*hM* aM + B^x*hB* aB)} + \frac{(u*aM*M^x)}{( + 1 + M^x*hM* aM + B^x*hB* aB)} - d - \omega)$$ + +$$ dB/dt = B*(rb - \frac{(rb*\alpha_{bb} *B)}{Kb} - \frac{(B^{x - 1}*W *aB)}{( + 1 + M^x*hM* aM + B^x*hB* aB)} - \frac{(rb*\alpha_{bm} *M)}{Kb} )$$ + +$$ dM/dt = M*(rm - \frac{(rm*\alpha_{mm}*M)}{Km} - \frac{(M^{x - 1}*W *aM)}{( + 1 + B^x*hB* aB + M^x*hM* aM)} - \frac{(rm*\alpha_{mb}*B)}{Km} - \mu$$ + +**Parameter Definitions** + ++ W: Wolves ++ M: Moose ++ B: Caribou ++ rb or rm: per capita intrinsic growth rate for caribou and moose, respectively units - #/indiv ++ $$\alpha_{ik}$$: the per capita impact of interaction of species k on species i ++ $$\alpha_{ii}$$: the per capita impact of intraspecific competition (equal to one) ++ u: conversion factor - moose or primary prey might be bigger or more preferable than endangered species unitless? ++ x: type of functional response (1 = linear, 2 = logarithmic, 3 = logistic) unitless +hM. ++ hB: PER CAPITA handling time of prey (moose, caribou) units - time/1 caribou|moose ++ $$\omega | \mu$$: per capita or percentage cull (wolves, moose) units - proportion ++ a : predation efficiency = search efficiency * attack efficiency = km^2/time * (# successful kills)/(total # attempts) = units km^2/time + +**Notes** + ++ alpha_bb ->1 & alpha_mm->1 here because we'll want to keep the meaning of Kb and Km as the carrying capacities in the absence of predation or competition. + ++ We changed the structure of predation in the equation to reflect the overall time spent for predation depends both moose and caribou, thus if a wolf is currently eating a moose, it cannot also be eating a caribou. This change was made after Niki had suspicions about the immediate lack of of impact moose culls on caribou. Niki thought that moose culls, while eventually good for caribou, might immediately be bad as the predation pressure on caribou would increase before wolves had a change to re-equilibrate to a decrease in prey (more predators than prey present). + diff --git a/README.md b/README.md index ee30c5e..55b5cd4 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,9 @@ -# rl4caribou -RL for Caribou Conservation +# Caribou RL + +A DRL-based approach to Caribou conservation based on the methods of the +[approx-model-or-approx-soln](https://github.com/boettiger-lab/approx-model-or-approx-soln) project: + +[![DOI](https://zenodo.org/badge/572256056.svg)](https://zenodo.org/badge/latestdoi/572256056) + +A three-species foodweb is considered, including interactions between Caribou, Elk and Wolf populations. + diff --git a/Scenarios.md b/Scenarios.md new file mode 100644 index 0000000..5ecdd8e --- /dev/null +++ b/Scenarios.md @@ -0,0 +1,37 @@ +**Equilibrium Points** +There are two equilibrium points in our system: ++ moose-wolf system with caribou at zero (unstable for caribou) ++ moose-wolf-caribou system + +two-species equilibrium: + +$$ eqM: \frac{(d + \omega)}{(aM (u - d hM - hM \omega))} $$ + +$$ eqW: \frac{(u (rm - \mu))}{(aM (u - (d + \omega) hM))} - \frac{( + u (d + \omega) rm)}{(aM^2 Km (u - (d + \omega) hM)^2)} $$ + +*note* $$(d hM-u+hM \omega) < 0 $$ for eqM to be positive + +add notes about stability *NIKI* + +three-species equilibrium: *NIKI* + +**Scenario** + +We are trying to assess how to get from a 2 species system to a stable 3 species system. + +Management Strategies ++ wolf cull (proportional harvest or fixed escapement harvest rules?) ++ moose cull (prop. harvest) ++ habitat restoration (longer time scale than immediate strategies above) - implemented every 10th timestep? + +Implementation ++ pulsed management ++ gradual decline ++ effectiveness in short vs. long-term strategy + +We are trying to maximize caribou growth rate while retaining all 3 species on the landscape and keeping costs low. + ++ budget - curriculum learning? + + diff --git a/hyperpars/ppo-caribou-v0-1.yml b/hyperpars/ppo-caribou-v0-1.yml new file mode 100644 index 0000000..0f13a68 --- /dev/null +++ b/hyperpars/ppo-caribou-v0-1.yml @@ -0,0 +1,11 @@ +# stable-baselines3 configuration + +algo: "PPO" +env_id: "Caribou-v0" +n_envs: 12 +tensorboard: "/home/rstudio/logs" +total_timesteps: 6000000 +config: {} +use_sde: True +id: "1" +repo: "cboettig/rl-ecology" diff --git a/hyperpars/rllib/ppo-asm.yml b/hyperpars/rllib/ppo-asm.yml new file mode 100644 index 0000000..fd31c5d --- /dev/null +++ b/hyperpars/rllib/ppo-asm.yml @@ -0,0 +1,30 @@ +asm: + env: rl4fisheries.asm.Asm + run: PPO + stop: + time_total_s: 24000 + config: + lambda: 0.95 + kl_coeff: 0.5 + clip_param: 0.2 + vf_clip_param: 400.0 + entropy_coeff: 0.0001 + rollout_fragment_length: auto + num_sgd_iter: 10 + num_envs_per_worker: 24 + min_time_s_per_iteration: 360 + lr: 0.0003 + + # Run with Learner- and RLModule API (new stack). + _enable_learner_api: true + _enable_rl_module_api: true + # Use N Learner worker on the GPU + num_learner_workers: 2 + num_gpus_per_learner_worker: 1 + num_gpus: 0 # No GPU needed for driver. + # Since we are using learner workers, the driver process does not need + # a CPU in particular. + num_cpus_for_local_worker: 1 + # Need to unset this b/c we are using the RLModule API, which + # provides exploration control via the RLModule's `forward_exploration` method. + exploration_config: {} diff --git a/hyperpars/tqc-caribou-v0-1.yml b/hyperpars/tqc-caribou-v0-1.yml new file mode 100644 index 0000000..dba7db2 --- /dev/null +++ b/hyperpars/tqc-caribou-v0-1.yml @@ -0,0 +1,11 @@ +# stable-baselines3 configuration + +algo: "TQC" +env_id: "Caribou-v0" +n_envs: 12 +tensorboard: "/home/rstudio/logs" +total_timesteps: 6000000 +config: {} +use_sde: True +id: "1" +repo: "cboettig/rl-ecology" diff --git a/notebooks/compare-solutions.ipynb b/notebooks/compare-solutions.ipynb new file mode 100644 index 0000000..3647f35 --- /dev/null +++ b/notebooks/compare-solutions.ipynb @@ -0,0 +1,209 @@ +{ + "cells": [ + { + "cell_type": "code", + "execution_count": 3, + "id": "cff325f3-71d3-469c-aec5-e340219ce0e4", + "metadata": {}, + "outputs": [], + "source": [ + "import ibis\n", + "from ibis import _\n", + "import polars as pl\n", + "from polars import col\n", + "import ray\n", + "import numpy as np\n", + "from plotnine import geom_point, ggplot, aes, geom_density, geom_bar\n", + "from rl4eco.utils import load_hf_agent\n", + "from rl4caribou import Caribou" + ] + }, + { + "cell_type": "code", + "execution_count": 22, + "id": "e60f49f8-91c2-45a8-b234-6881fd450f03", + "metadata": {}, + "outputs": [], + "source": [ + "env = Caribou()\n", + "ppo_agent = load_hf_agent(\"PPO\", env, \"sb3/PPO-Caribou-v0-1.zip\")\n", + "tqc_agent = load_hf_agent(\"TQC\", env, \"sb3/TQC-Caribou-v0-1.zip\")" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "8f3168e4-cb0e-4508-880b-40708b0276a5", + "metadata": {}, + "outputs": [], + "source": [ + "class simulator:\n", + " def __init__(self, env, agent):\n", + " self.env = env\n", + " self.agent = agent\n", + " def simulate(self, reps=10):\n", + " results = []\n", + " env = self.env\n", + " agent = self.agent\n", + " for rep in range(reps): # try score as average of 100 replicates, still a noisy measure\n", + " episode_reward = 0.0\n", + " observation, _ = env.reset()\n", + " for t in range(env.Tmax):\n", + " action, _ = agent.predict(observation, deterministic=True)\n", + " observation, reward, terminated, done, info = env.step(action)\n", + " episode_reward += reward\n", + " if terminated or done:\n", + " break\n", + " results.append(episode_reward) \n", + " return results\n" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "c1e61858-f098-4427-a121-d049b182a5ff", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "(19.018271214663983, 22.595691994936807)" + ] + }, + "execution_count": 7, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "ppo_sims = simulator(Caribou(), ppo_agent).simulate(100)\n", + "np.mean(ppo_sims), np.std(ppo_sims)" + ] + }, + { + "cell_type": "code", + "execution_count": 23, + "id": "6f1f1f1a-4d82-4866-a58d-65aef9e9a9b5", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "(369.7309132088113, 11.430750945078708)" + ] + }, + "execution_count": 23, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "tqc_sims = simulator(Caribou(), tqc_agent).simulate(100)\n", + "np.mean(tqc_sims), np.std(tqc_sims)" + ] + }, + { + "cell_type": "code", + "execution_count": 24, + "id": "f4547611-e1c0-43f0-9782-46b733bb0e44", + "metadata": {}, + "outputs": [], + "source": [ + "class fixed_effort:\n", + " def __init__(self, action):\n", + " self.effort = np.array(action, dtype=np.float32)\n", + "\n", + " def predict(self, observation, **kwargs):\n", + " action = self.effort * 2 - 1\n", + " return action, {}\n", + "msy_agent = fixed_effort([0.1625976286665279, 0.05916838814404951])" + ] + }, + { + "cell_type": "code", + "execution_count": 25, + "id": "92c90e5a-df70-4e36-9908-000c4dd4dd37", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "(170.85768672216255, 18.094249655767953)" + ] + }, + "execution_count": 25, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "msy_sims = simulator(Caribou(), msy_agent).simulate(100)\n", + "np.mean(msy_sims), np.std(msy_sims)" + ] + }, + { + "cell_type": "code", + "execution_count": 30, + "id": "ce14812d-0594-4fe7-8719-fa6d272c2f96", + "metadata": {}, + "outputs": [ + { + "data": { + "image/png": "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qg3Jqqqqmt3fSevjv34IARFNCR8Aer1eHXfcccrNzdWKFSs0aNCgOvcUFBRo69atkqR+/foFPXbfvn21fv16ffPNNw3es3LlSuvexuTn52v16tWSpLPPPjvoOTSkrKzMCh/bt2/f5P1XX321rr766gavFxQUBH1Ccrxwu93KzMxUUVFRQvxBkWgyMzPldrtVXV3d7L63jgSsn/jHGopvrKH4xvqJb6yf+Mcaim/xuoZ822OZMoI+fNM/YD548GBCfL/5r59EqmhE/IuvmmCHDBs2TJK0ePFi5efn17n+5ptvyjRNtWnTRn369Al63CFDhsgwDOXl5Wnp0qV1rn/++efKy8uTYRjWHBry8ccfq7q6WsnJyTrzzDObfO+m/sXktddeU0VFhQzD0GmnndbkeAAAAAAAOMW/AjBY/hVy8RRmAs3REREAjhgxQh06dFBZWZkmT56sjRs3Sqr5F4g5c+bovffek1RTBefxBP4wuv7663XhhRfqmWeeqTNuVlaWhgwZIkmaOnWqli1bJtM0ZZqmli1bpueff15STQDZtWvXRufoO/134MCBSk9Pb/Jzuv/++/X6669r48aNAT8It2zZomeffVbz5s2TJJ177rlRbycGAAAAAMBf7R6AwVe9GYZhnQRMuzkQmYRvAZakpKQkTZgwQePHj9emTZt0++23Ky0tTWVlZdYPkQsuuEDDhw8PeexbbrlFO3bsUG5urh577DElJydLkioqKiTV7Oc3duzYRsf47rvvtGPHDknBH/6Rn5+vmTNnaubMmXK73UpLS1NFRUXAqcNDhw7VTTfdFPLnBAAAAACAnawKQE9SSM+5XC4dOlRNAAhE6IgIACWpa9eumjp1qubOnavly5eroKBA6enp6tGjh7KzszVgwICwxvV6vZoyZYrmz5+vnJwc5eXlSZJ69uypYcOGKTs7u05V4eF8h38cffTRTe4V6HPdddfp22+/1fr167V3714dOHBAbrdbHTt21AknnKBzzjkn6LEAAAAAAHBSVVWVpNBagCXJZbh1SFUEgECEjpgAUJJat26tMWPGaMyYMUE/89e//rXJezwejy666CJddNFFYc3rtttu02233RbSM2eccYbOOOOMsN4PAAAAAIBosgJAV2gxhOGq2QeQPQCByBwRewACAAAAAIDYCbsC8Mc9A6kABCJDAAgAAAAAABwVzinA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Y/3EP9ZQfIuXNZScnGy9TktLV2pqakjPe71pfq+9CfM9R5CJaCMARFBKS0tVXl4e62mExO12KyMjQ/v372eviDiUkZEht9utQ4cOaf/+/bGeDg7D+ol/rKH4xhqKb6yf+Mb6iX+sofgWb2vI/3ukquqQysrKQnq+oqLCen3gwAHt3bvXtrnFgv/6IQRENBEAIiimacbFHx7hOHToULOd+5GCr0/8Yv00D3yN4hdrKP7x9YlfrJ/mga9R/IqXNRRYSGKEsY+fYb2qrKyMi88JaI6a16ZuAAAAAACg2aiqqrJeezxhnAJscAgIomPTpk0yDEOGYei6665z/P187zVs2DDH30siAAQAAAAAAA7xDwANI/QIwuV3cjDVf0D4CAABAAAAAIAjfAGg250kwzCauLsu/1ODTdO0bV7AkYYAEAAAAAAAOMIXAHrc4R1B4F81SAUgED4CQAAAAAAA4IjKykpJkivMANC/BZg9AIHwEQACAAAAAABH+Kr23FQAAjFFAAgAAAAAABzhqwB0u8KtACQAjLVFixZZJ9ZOnDhRkrRhwwbdfvvtOv7445Wenq4OHTrovPPO04cffljn+c8//1xXXnmlevbsqdTUVLVv316XXXaZvv3226Def968ebriiivUvXt3paWlKSMjQ71799bNN9+sr7/+OujP44svvtBVV12lLl26KDU1VZ06ddLPf/5zvf7660GP4W/x4sW68cYb1bt3b7Vu3Vqpqanq0qWLRo8erblz58bdnpXhrUAAAAAAAIAmWIeAeCKvAIy3QOVINW/ePF1zzTU6ePCg9bGSkhItXLhQCxcu1COPPKLx48fLNE1NnDhRkyZNCnh+9+7dmjNnjt5++23NnTtXo0aNqvd98vPzNXr0aH366ad1rq1bt07r1q3T9OnTNXbsWD333HNyu931jFJj4sSJmjx5ckAbeV5envLy8rRgwQK98cYbeuyxx4L6/Pft26df//rXmj9/fp1r27Zt07Zt2/Tmm29qyJAhmjt3ro4++uigxnUaASAAAAAAAHCEFQCGXQFYG+pQARh7K1as0B//+Ee53W7deuutOv300+V2u7Vo0SL97W9/U1VVlSZMmKDBgwdrxYoVmjRpkrp166brrrtOJ5xwgoqLi/X666/rww8/VGVlpa677jp9//33dUKygwcPasiQIVq3bp0kqW3btvrNb36jfv36qaKiQosXL9bMmTNVWVmpadOmaf/+/frnP/9Z75yffvppPfzww9avL774Yp1//vlq2bKl1q5dq1deeUVz5swJao/J/fv3a/Dgwfruu+8kSccdd5wuu+wy9e7dW8nJyfrf//6n1157TatWrdLixYs1fPhwLVu2TKmpqeH+ltuGABAAAAAAADjCagEOew9Aw3rNISCx9+6776p79+76+OOPlZWVZX38yiuv1BlnnKFrr71WknTbbbdp/fr1ys7O1htvvCGv12vdO2bMGF177bX6xz/+ocLCQv3tb3/T3XffHfA+9957rxX+nXLKKfr3v/8dEBJed911+t3vfqdzzz1Xe/fu1cyZMzVq1ChdfvnlAeP873//0/333y9Jcrvdmj17ti699NKAe+68805dcMEFevPNN5v8/G+66SYr/Js4caImTJhQp/Lwnnvu0T333KMnn3xS3377rR555BE98sgjTY7tNPYABAAAAAAAjvBV7bkaac9sTM3ec66AsRBbs2bNCgj/fK655hodd9xxkqQ1a9aoVatWevXVVwPCP59HHnnECnf//e9/B1zLz8/XK6+8IklKS0trsI32lFNO0QsvvGD9esqUKXXuef7551VWViZJGjduXJ3wT5IyMjL0r3/9Sy1btmzwc5akVatWafbs2ZJqQsyHHnqo3rZjl8ulP/3pTxo8eLA1h/Ly8kbHjgYCQAAAAAAA4AhfBaDHnRT2GL42YCoAY+/kk0/WoEGDGrzuC72kmkAwIyOj3vu6dOmibt26SZJVUefz/vvvW6HdFVdcYd1Xn8svv1w9e/aUJH3zzTfauHFjwHVfVZ/L5dK4ceMaHKdjx466+uqrG7wuSX//+9+t1/fcc0+j90o1n78kFRUV6YsvvmjyfqfRAgwAAAAAABxh7QEYZguwJLkMlw6JADAeDBgwoNHrHTp0sF6ffvrpTd67adMm7d27N+Dj/mHZeeed1+gYhmHovPPOsyoBly1bZlUn7t69W5s3b5YknXDCCTrmmGMaHeucc84JqCg83OLFiyVJqamp+u677+oEl4fbvn279fq7777TkCFDGr3faQSAAAAAAADAEb4A0BXmISA1z9Y0LxIAxt5RRx3V6PWUlJSQ7z28PXbHjh3W6169ejU5J/97/J/Ny8uzXh977LFNjtPUPZs2bZIklZWV6eKLL25yPH+FhYUh3e8E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UG+99ZZatmyp9evX68EHH9QVV1yhM844Qz/88IP27dunffv26eabb5YkPffcc1q7dq013muvvaZPPvlEXq9Xf//731VSUqK9e/eqrKxM27Zt08svv6xBgwZZ96elpemqq66SJL388sv1zrG6ulozZsyQJF1//fURfb62n67hO/03nOfCfRYAAAAAAMQX/7bGSCoAOQUYTti3b59mz56t7OxsuVwuud1u/eIXv9Ddd98tqSYgTE1N1bx589SjRw9JUkZGhv785z/r2GOPlWmamjNnjjXe0qVLJUnXXHONrrnmGnm9Xkk1xXKdOnXSb3/7Wz3xxBMBc7jxxhsl1RTGbd++vc4cFy5cqC1btsjr9erKK6+M6PPleF0AAAAAAGA7u/YA5BAQOGHgwIEaOnRonY8PHz7cen3XXXfV6VZ1uVw666yzJNWcheGTkZEhSdq5c2fQczjppJN02mmnBVT6+fNVBo4ePVqtW7cOetz6xEUAWFJSIklWzzUAAAAAAGje7DoFmBZgOKFPnz71frxdu3bW6xNPPLHee9q3by9J2rt3r/Wx888/X5L09ttva9SoUXrjjTeUn5/f5DxuuOEGSTV7/fl3xu7Zs0dvv/22JGnMmDFNjtOUuAgAly1bJinwNxkAAAAAADRfnAKMeNaxY8d6P+52u4O+x7/NfejQoZo8ebI8Ho/mz5+vyy+/XO3atVOvXr102223adWqVfWO9atf/UotW7bU//73Py1atMj6+D//+U9VVFTo2GOPrbdSMVRhr8BVq1Zp5cqV9V77+OOPtW/fvkafN01TxcXFWrFihWbOnCnDMHTaaaeFOx0AAAAAABBH/MORiAJATgFGMzFhwgT9+te/1uuvv66cnBx9/vnnWr9+vdavX68///nPevzxx3XvvfcGPNOiRQv96le/0vTp0/XKK69Y7cW+9t/f/va3Mgwj4rmFvQLnzZunSZMm1fm4aZqaOnVqSGOZpinDMKyTVAAAAAAAQPPmv2dfRHsAcggImpFu3brp7rvv1t13363q6motW7ZMjz76qN5//33df//9GjlyZJ324xtvvFHTp0/X3Llz9fzzz+v777/XmjVr5Ha7dd1119kyr4hagH0n9x5+gu/hH2/qv/bt2+ull17S2WefHfEnBAAAAAAAYi/gFGCXu5E7G+d7lgAQzY3L5dKgQYM0b948HXXUUaqu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/liGYahv3752TseyYMEC7dy5UykpKXrwwQetoDElJUWXX365zj//fEnSzJkzrRLlYGzcuFGLFy+WJN12220aOHCgDMOQYRgaOHCgbr31VknSokWLtHnzZls/p1i+NwAAAAAATbGtAtBFBSAQKVsDwL59++qhhx6SaZqqrKzUl19+qT179sg0TfXp00d33313nWdWr16tdevWSaqphHPCokWLJElDhgxR27Zt61wfPXq0DMNQYWGhVq9eHfS4OTk5Mk1THTt21MCBA+tcHzRokDp27CjTNK1TkO0Sy/cGAAAAAKApdh0CYhi1ewASAALhsTUAlKQHHnhAb731lrKzs9WrVy+dfPLJ+r//+z8tXrxYXq+3zv1Tp06VVHPCzIgRI+yejkpLS7V+/XpJ0sknn1zvPW3btlXnzp0lSd9++23QY/sONunfv3/ADyQfwzDUv3//gHvtEsv3BgAAAACgKbUBYGSHgPhXANICHB2+DsPm8h+a5sgRsRdeeKEuvPDCoO6dPn26pk+f7sQ0JEnbtm2zjq/u1q1bg/d169ZNW7du1datW4Ma1zRNbdu2rclxu3btKkmNjrtq1SrddNNNys/PV3Jysjp27KhTTjlF2dnZyszMdPS9AQAAAABwQm0LcGQVgLQAA5FzJACMJ4WFhdbrNm3aNHif79revXuDGre0tFRlZWVBj1taWqrS0tJ6qyALCgrkdrvl9XpVUlKiH374QT/88IM++OAD3XPPPerXr59j7w0AAAAAgBN81Xr+AV44/Cu8qACMruse/6269m648CiWtqzdrBn3vRLraTQbCR8A+oIyqebQj4b4rpWWlgY1rv99wYzre8Y/hOvZs6d69eql0047TUcddZRcLpdKSkq0fPlyzZgxQ4WFhXrsscf01FNPqVOnTra+NwAAAAAATvJVAHqoAGy2uvbupl6nHx/racAGtu8BiOCNGjVKI0eOVNu2ba1jzdPS0jRs2DA98cQTatGihUpLS/Xaa6/FeKYAAAAAAATPNM3aCsAI9wA0jNroggAQCI9jFYArV67UBx98oDVr1mjv3r0BlXgNMQxDH330ka3zSE1NtV6Xl5crLS2t3vvKy8slKegqOf/7fM82Nm4oY0tSu3btlJ2drX/961/66quvVF1dbYWETrz3zJkz9eqrrzZ4/dJLL9W1114b7PTjgq9MvFWrVtY+kIgfvu9nl8tV716XiC3WT/xjDcU31lB8Y/3EN9ZP/GMNxbd4WUO+6j9JSk1Ni6gjzetN83vtbdbfd/7rB4gm2wPAHTt26De/+Y0WLlwY0nOmaTpycov/HnmFhYUNBoC+vQKD/UHi9Xrl9XpVWloasM9gQ+P67g9Fr169JEklJSU6cOCAWrVq5dh7FxcXa/fu3Q1eLykpifjkpljhB2t8Mwyj2X5vHQlYP/GPNRTfWEPxjfUT31g/8Y81FN9ivYYqKiqs1x5PUkR/3/f/XBLl+46TaxFttgaABw8e1FlnnaX169fHzb/Wde7cWYZhyDRNbdmyRZ07d673vi1btkiSunTpEtS4hmGoc+fOWr9+vfWsHePG6r3T09PVrl27Bq+npaU1u81WDcOQy+VSdXV13Hw/opbL5bLWJmX88Yf1E/9YQ/GNNRTfWD/xjfUT/1hD8S1e1pB/F6DL5Y5oLi6/FuCKiopm93dTf/7rhxAQ0WRrAPj0008rNzfXCqjGjx+vc889V507d1ZycrKdbxU0r9er4447Trm5uVqxYoUGDRpU556CggJt3bpVkuqcuNuYvn37av369frmm28avGflypXWvaHKzc2VVPM5tGzZ0tH3vvrqq3X11Vc3eL2goCDoE5LjhdvtVmZmpoqKipr1HxCJKjMzU263W9XV1c3ue+tIwPqJf6yh+MYaim+sn/jG+ol/rKH4Fi9ryP97o7raDPrAzfpUVFZZr/fv39+sv+/8108iVDKi+bC1JnjevHmSpA4dOujLL7/UTTfdpB49esQs/PMZNmyYJGnx4sXKz8+vc/3NN9+UaZpq06aN+vTpE/S4Q4YMkWEYysvL09KlS+tc//zzz5WXlyfDMKw5+DT1rx/5+fl6//33JUmnnnpqnfLtSN4bAAAAAAAn+e8B6HZFVnvk8quUo+oUCI+tAeAPP/wgwzB0yy23qH379nYOHZERI0aoQ4cOKisr0+TJk7Vx40ZJNYdkzJkzR++9956kmio4jyfwB9P111+vCy+8UM8880ydcbOysjRkyBBJ0tSpU7Vs2TKZpinTNLVs2TI9//zzkmoCyK5duwY8u2jRIj3++ONatmyZ9u/fb328tLRUOTk5uvfee3XgwAF5vV796le/svW9AQAAAABwUlVVbdWe2x1ZAGi4aivlCACB8NjaAuxbiMcff7ydw0YsKSlJEyZM0Pjx47Vp0ybdfvvtSktLU1lZmTXnCy64QMOHDw957FtuuUU7duxQbm6uHnvsMava0bfh6QknnKCxY8fWea66ulpLly61qve8Xq88Ho+Ki4utObVq1Up33313g/sWhvveAAAAAAA4KTAAjKzV1X8PQLYGAMJjawDYrVs3rV27VgcOHLBzWFt07dpVU6dO1dy5c7V8+XIVFBQoPT1dPXr0UHZ2tgYMGBDWuF6vV1OmTNH8+fOVk5OjvLw8SVLPnj01bNgwZWdn16kqlKQ+ffro6quv1tq1a7V9+3bt379fJSUlSk9PV5cuXXTqqadqxIgRdfb+s+O9AQAAAABwUkALsDsporH8t8QiAATCY2s6dOGFF+q7777TkiVL9Jvf/MbOoW3RunVrjRkzRmPGjAn6mb/+9a9N3uPxeHTRRRfpoosuCnrcdu3a6fLLLw/6fjvfGwAAAAAAJ/lXALoirQCkBRiImK17AN52223KzMzUrFmztG7dOjuHBgAAAAAAzYR/BWCSJyWisQy/FmACQCA8tgaAHTt21OzZs+XxeHTuuedq8eLFdg4PAAAAAACagcAW4AhPAXYRAMI+w4YNk2EYmjhxosrKyvTwww+rd+/e8nq9atu2rS6//HJ99913dZ5btGiRDMOQ8eOp1J9//rlGjRqltm3byuv1qm/fvnr66aebbFN///33deGFF6pDhw5KTk5Whw4d9Itf/EL//ve/Hfl8fWxtAZ40aZIkafjw4Xr77bd11lln6aSTTtLAgQN19NFHByzahjz44IN2TgkAAAAAAESZ73BKSfJ4ItsD0OAQEDigvLxcZ599tpYuXark5GSlpqaqoKBAb7zxht555x298847Ou+88+p99s0339QVV1yhqqoqtW7dWlVVVVq9erXuuOMOLViwQO+88451UKuPaZoaO3as/vKXv0iqCbYzMjKUn59vvd/vfvc7TZ061QoZ7WRrADhx4kRrkoZhyDRNrVy5UitXrgx6DAJAAAAAAACaN/89AD2e5EbubJr/HoAEgLDLCy+8oMrKSv3973/Xr371KyUlJWnVqlUaM2aMvvrqK11xxRVau3atOnToUOfZ3/72txo+fLimTZumrKwslZSU6MUXX9Q999yjBQsW6KGHHtLjjz8e8MzTTz9thX/33nuv7r33XmVmZqqwsFCPPfaYnnzySf35z39Wr1699Pvf/972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GKEnnnhCY8aMUVJS3QVfWVmpV155Rffee6+qqqpkGIbGjh1r53QAAAAAAECU+QeASTZVABo/tgATAEZXt669dXyv02M9DdjA1gBwxIgRGjNmjF5++WUVFxfrd7/7ne6//34NHjxYxx57rNLS0lRSUqINGzZoyZIlKioqsvq0x4wZ0+x6zAEAAAAAQCD/cwE8SZwCDMQDWwNASZo+fbrS0tL0/PPPyzRN7du3T++//36d+3zBn2EYuu222/T000/bPRUAAAAAABBlTlQAugwCQCASth4CItUEes8++6wWL16siy66SMnJyTJNs85/KSkpuvjii/Xpp5/qmWeekWEYdk8FAAAAAABEWeAegCm2jOly1bQAc9orEB7bKwB9Bg8erMGDB6uiokLffvut8vLydPDgQbVo0UKdOnVS3759lZxsz78EAAAAAACA+ODfApxkUwuwQQswEBHHAkCf5ORknXbaaU6/DQAAAAAAiAOBFYD2tgBzCAgQHttbgAEAAAAAwJGLCkAg/jheAQgAAAAAAI4cjlQA/rgHIBWAiNSMGTO0adMmDRs2TMOGDYv1dKKGABAAAAAAANimrKzMep1k0yEgBi3AsMmMGTOUk5MjSUdUAEgLMAAAAAAAsE1ABaBNLcAuWoCBiBAAAgAAAAAA2/gHgEm0AANxgQAQAAAAAADYxv8QELv2APS1AFMBiHDNmDFDhmFY7b8PP/ywDMMI+M/f7t279bvf/U5du3ZVamqqunbtqptuuknbt2/XokWL6n3GX1FRkR577DENGDBAbdq0UWpqqnr06KELLrhAf//73wNa5aOBPQABAAAAAIBtAioAbW4BNk3TlvFw5PF6vWrfvr0KCwtVWVmp9PR0tWjRot57v//+ew0bNkw7d+60ni0sLNT06dP11ltv6bHHHmv0vb744gv94he/0K5duyRJHo9HGRkZ2rp1qzZu3Kj33ntP/fr100knnWTr59gYKgABAAAAAIBtAisA7TkExEUFICJ0xRVXaOfOnRo0aJAk6a677tLOnTsD/pOkyspKXXbZZdq5c6c6d+6sBQsWqLi4WAcPHtQnn3yi9PR03XnnnQ2+z6ZNm3T++edr165dOuGEE/Tee++ppKREe/bsUUlJiZYsWaKbbrpJycn2hOPBogIQAAAAAADYxpkKwJo9AAkA4bR//etfWr16tdxut+bPn69+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1X+S84eA8OcWEDoCQAAAgCPEo48+qnvvvVeFhYWSpOLiYj333HO66aabZJpmjGcHAGjOKioqrNdOHQJCCzAQPgJAAACAI8Bbb72lZ599VpLUtV1bPXj1r9Q3K0uS9M477+gvf/lLLKcHAGjm/CsAnWoBdrtoAQbCRQAIAACQ4Pbu3at7771XktS2VSvNeeB+Xf/zEZp9/z069piOkqQpU6Zo586dsZwmAKAZC2gBdqgC0KAFGAgbASAAAECCe/LJJ6223/93w2/VITNTktTC69Ufr/+tpJp24KeeeipmcwQANG8BLcAeZ1uAqQAEQkcACAAAkMB2796tv//975Kks/v11dkn9Qu4flqv4/TzU0+RJM2ePVt79uyJ+hwBAM1fWVmZ9dq5PQBrIgz2AARCRwAIAACQwKZPn279pWzc6IvrvefmC86XJJWWlmrmzJlRmxsAIHH4VwB6HDoF2O3ySKIFGAgHASAAAECCqqys1KuvvipJGvzTn6hfj6x67zv52GOtA0Fmz57NicAAgJAFVgA6EwD6KgBpAQZCRwAIAACQoD766CPl5+dLkq48a1ij914+5AxJ0oYNG/T11187PDMAQKIJ2APQsRZg9gAEwkUACAAAkKBmzZolScps0ULnndK/0XsvHDRAHnfNX6zef/99x+cGAEgsgYeAOFUBWNMCzB6AQOgIAAEAABLQzp07tXDhQknSxYMHKiUpqdH7W6en62cnHC9J+uCDDxyfHwAgsUTzEBD2AARCRwAIAACQgN566y2rReqXw4YE9YyvSnDDhg3asGGDY3MDACSegENAaAEG4g4BIAAAQALytfH26txJJ3TpEtQzw/ufZL1esGCBE9MCACSogApAx1qAawJAWoCB0BEAAgAAJJiCggJ98cUXkqSfn3Jy0M91adtWvbvWhIW0AQMAQhGNQ0DcP+5VSwswEDoCQAAAgASzYMECqzrivFNPCenZ806uaQP+8ssvtXfvXtvnBgBITAEtwE5VABq0AAPhIgAEAABIML7232OOaqM+3buF9OzQvn0k1bRXLV261Pa5AQASk68F2DBccrs9jryH8eMhIASAQOgIAAEAABLIwYMHlZOTI0k675STZRhGSM/365Elb0pN5cZnn31m+/wAAInJVwGYlJQc8p89wfIPFtkHEAgNASAAAEAC+fzzz1VeXi5JOu/k4Pf/80nyeHRar17WWAAABMP3Z49T+/9JtYeASOwDCISKABAAACCBLFq0SJKUmpys044/LqwxBvY+QZL03//+V4WFhXZNDQCQwHwBoFP7/0mSy1UbYdAGDISGABAAACCB+ALAASccr5SkpLDGGPiTE6zXVAECAIJhVQB6HKwANGorAAkAgdAQAAIAACSI7du3a/369ZKkIX1ODHucPt27Ky2l5i9wS5YssWVuAIDEFpUWYDcBIBAuAkAAAIAE4av+k6QzT/xp2OMkeTw6/Xj2AQQABM//EBCn+O8BSAAIhIYAEAAAIEH4Tv9t17q1enXuFNFYvv0D165dq4MHD0Y8NwBAYov2ISAEgEBoCAABAAASgGma+vTTTyXVVP8ZhhHReP17HmuNu3LlykinBwBIcNE4BMRNAAiEjQAQAAAgAWzYsEEFBQWSpEF+h3iEq1+PLCtE/OqrryIeDwCQ2GorAGkBBuIRASAAAEACWLZsmfX6tOOPj3i8lmleHdfpGEnS119/HfF4AIDEFpVTgF21EQYBIBAaAkAAAIAE4AsA27VurW7t2toy5sk9e0qqCQBN07RlTABAYvIdAuJxtALQY70mAARC42n6lsRRVFSkOXPmaPny5dqzZ49SUlLUs2dPjRw5UgMGDAh73KqqKs2fP185OTnKy8uTJHXq1ElDhw5Vdna2PJ76f5t/+OEHffHFF/rvf/+rLVu26ODBg0pNTVXnzp31s5/9TCNHjlRaWlq9z+7atUs33HBDk3O79957NXjw4LA/NwAA0DwsXbpUknT68b0i3v/Pp/+xPTU7Z7Hy8/O1ZcsWdevWzZZxAQCJp7YFONWx96AFGAjfERMAbtmyRePHj1dRUZEkyev1qri4WCtXrtTKlSs1atSooAK1w5WWluqBBx5Qbm6uJCk5ueZfOzZs2KANGzZoyZIlmjRpklJTA38ILlq0SE899ZT1a8MwlJaWppKSEn3//ff6/vvv9cEHH+ihhx5S165dG51DRkZGQCm0P998AABA4tq+fbu2bt0qqSYAtMvJx/a0Xn/99dcEgACABtW2ADtZAUgLMBCuIyIArKys1COPPKKioiJ169ZNd9xxh7KyslReXq63335bs2bN0rvvvqusrCwNHz48pLGnTZum3Nxcpaen6/e//71VSbhs2TI999xzWrdunV544QWNGzcu4LlDhw4pOTlZQ4YM0ZAhQ9S7d2+lpKSorKxMn3/+uV555RXl5+dr8uTJev7555WS0vA+Ck8++aTat28f+m8MAABICP77/9kZAB7b6Ri1SE3VwbIyffXVV7rkkktsGxsAkFhqKwCd3AOQCkAgXEfEHoALFizQzp07lZKSogcffFBZWVmSpJSUFF1++eU6//zzJUkzZ85UVVVV0ONu3LhRixcvliTddtttGjhwoAzDkGEYGjhwoG699VZJNdV+mzdvDnj2+OOP10svvaTf//73Oumkk6yALzU1VWeffbbuueceSTWtvkuWLInsNwAAACQ0XwCYkebV8V062zau2+VSv549JHEQCACgcdHYA9Dtrq1hCuXv7gCOkABw0aJFkqQhQ4aobdu6m2KPHj1ahmGosLBQq1evDnrcnJwcmaapjh07auDAgXWuDxo0SB07dpRpmsrJyQm41rlzZ2VmZjY4dt++fdWuXTtJNXsFAgAANMQXAJ563HFyN7AtSLj6/xgArlmzxqruAADgcGVlZZKcbQE2/P6Mq66udux9gESU8AFgaWmp1q9fL0k6+eST672nbdu26ty55l/Lv/3226DHXrVqlSSpf//+9W62bRiG+vfvH3BvKDIyMiRR2gwcifLz8zVv3jzNmTNHO3fujPV0AMSxwsJCrVu3TpJ0mo3tvz79f9wHsKKiIqR/KAUAHFl8FYCOtgAbtAAD4Ur4PQC3bdsm0zQlqdGNq7t166atW7daG2g3xTRNbdu2rclxfQd4BDuuz4EDB6y24aYOAXniiSeUl5en8vJytWrVSr169dLw4cN12mmnhfSeAGKvurpaTz/9tJ566qnaNgqPR3feeafuuOOOBg/8AXDkWr58ufX69BOOt338/j1rDwL56quvdOqpp9r+HgCA5s00TatK3ONgBaDbTQAIhCvh/yZZWFhovW7Tpk2D9/mu7d27N6hxS0tLrRLnYMYtLS1VaWlpUGNL0uzZs1VZWSmv16vBgwc3eu/69etlmqZcLpf27NmjpUuXavLkyfrjH/+oysrKoN8TQGyZpqk777xTU6ZMscI/qWZ/kz/+8Y964IEHYjg7APHKFwCmJHnUN6u77eMf3SpDXX7cQmXFihW2jw8AaP78/79rcpQOAWEPQCA0CV8B6AvpJDV6kq7vWrAhnf99wYzre8br9TY59pdffqn33ntPknTllVeqVatWde5JTk7WyJEjdeaZZyorK0tpaWmSpC1btmju3Ln65JNPtGTJEqWnp1uHkQCIby+88IJmzpwpSep8Qhdd+9hvJEkz/u8Vbc/dpunTp+vUU0/VxRdfHMtpAogzX331lSSpT1aWUpKSHHmPk3pmaWt+vr755htHxgcANG/+AaAnSgEgewACoUn4CsDm5n//+5+efPJJVVdXa8CAAbrwwgvrvS8zM1M333yzfvrTn1rhn1TTLjxu3Dj94he/kCQtXLjQalUGEL/Wrl2rRx55RJLUoWdH/d/r43Xcqb103Km9dM9r96l1+5pDg+69917t27cvhjMFEE+qqqqs/Yt9h3U4wdcGvGnTJu3Zs8ex9wEANE/+hTeO7gHotx0OLcBAaBK+AjA1NdV6XV5eHhCW+fPtVxBMhd7h9zV2Ip7/tabG3rp1qx566CGVlJSoT58+uuuuu+o9XCQYV111lT744ANVVFToyy+/tA45acjMmTP16quvNnj90ksv1bXXXhvWXGLF93vXqlUrax9IxA/fH94ul6vRE7GPFI8++qgqKyvlTvLojpfvUtuOtSeWe7t6ddNTY/XHqx7T3r179Ze//EVTpkxxdD6sn/jHGopv0VpD3377rUpKSiRJp/fuHfT/jwnV6T85wXq9fv16HXvssY68T7SwfuIbfwbFP9ZQfIvFGjp48KD1Oj2thWN/HqV5063XqampzfL7z3/9ANGU8AGg//58hYWFDQaAvr0Cg/0B4vV65fV6VVpaGrDPYEPj+u5vSF5enh544AEVFRXp+OOP14QJE5ScHP7mqampqeratas2bNigXbt2NXl/cXGxdu/e3eD1kpKSgA1XmxN+sMY3wzCa7feWXf7zn/9owYIFkqTzrz9f3U/MqnPPKSNOVd9h/bRq0beaNm2a7rvvvkb3H7UL6yf+sYbim9Nr6Msvv7Ren3Z8r7D/4bApfXv0kNvl0qHqan399de64IILHHmfaGP9xDf+DIp/rKH4Fs015L8fX1JSimN/HrncgRFGc/7+c+r3CGhIwgeAnTt3lmEYMk1TW7ZsabASbsuWLZKkLl26BDWuYRjq3Lmz1q9fbz0b7rg7d+7UhAkTVFhYqB49euihhx5y7F9MGpKenq527do1eD0tLa3ZlVgbhiGXy6Xq6mr+9TgOuVwua20eyft3VFdX6+6775YkpbdK18XjRjf4/Xrp3Zdr1aKaap8///nPuv/++x2bF+sn/rGG4lu01tCyZcskSe1at9YxR7Vx7L28ycnq3a2r1mzcpGXLljW7/09wONZPfOPPoPjHGopvsVhDxcXF1uukpGTH3tdl1IaalZWVzfLPI//1QwiIaEr4ANDr9eq4445Tbm6uVqxYoUGDBtW5p6CgQFu3bpUk9evXL+ix+/btq/Xr1ze6IfbKlSute+uze/dujR8/XgUFBerWrZsmTZqkFi1aBD2HhpSVlVnhY/v27Zu8/+qrr9bVV1/d4PWCgoKgT0iOF263W5mZmSoqKmqWfzAkuszMTLndblVXVze77y07/ec//7F+Tlxw2y/kTvU0eBhR1z7d1PPkY/XDig36y1/+ohtvvNGxf/Vk/cQ/1lB8i9YaWrp0qaSaQzr8919yQt/u3bVm4yYtX75chYWFzfovLayf+MafQfGPNRTfYrGGCgoKrNfV1cEfrhmqysraSsOioqJm+f3nv36acwUjmp8joq5+2LBhkqTFixcrPz+/zvU333xTpmmqTZs26tOnT9DjDhkyRIZhKC8vz/o/4P4+//xz5eXlyTAMaw7+9uzZowkTJig/P1+dOnXSpEmTlJGREdR7N/UvKq+99poqKipkGIZOO+20oMYEEH3Tp0+XVFP9d/avz2ny/rOvrrln+/btWrx4saNzAxDf9u/fr9zcXEnSST8e0uGk/sfWHDJSWFiozZs3O/5+AIDmIxaHgPi3HQNo2hERAI4YMUIdOnRQWVmZJk+erI0bN0qqOaBjzpw5eu+99yTVVMF5PIFFkddff70uvPBCPfPMM3XGzcrK0pAhQyRJU6dO1bJly2SapkzT1LJly/T8889Lqgkgu3btGvDsvn37NGHCBO3cuVMdOnTQI488EtIGpvfff79ef/11bdy4MeBfdbZs2aJnn31W8+bNkySde+65TR4AAiA2cnNz9cknn0iShl55llK8Tf+fpVOzT1dqi5rDjV5//XVH5wcgvn3zzTfWPwg6eQKwz0k9at+jse4HAMCRp6Kiwnrt8TgZANZWzNF+DoQm4VuAJSkpKUkTJkzQ+PHjtWnTJt1+++1KS0tTWVmZ9UPjggsu0PDhw0Me+5ZbbtGOHTuUm5urxx57zDq4w/cD8IQTTtDYsWPrPPfvf/9b27dvl1RTujxu3LgG3+OEE06os9dXfn6+Zs6cqZkzZ8rtdistLU0VFRUBpw4PHTpUN910U8ifE4DoeOmllyRJLrdL51x7blDPpHhTdMqIU7Vk7mf68MMPVVFREdGBQQCar6+//lpSzV5PfbPqHh5kt2M7HaO0lBSVlJfr66+/1sUXX+z4ewIAmofACkDn/r+p/yEgVAACoTkiAkBJ6tq1q6ZOnaq5c+dq+fLlKigoUHp6unr06KHs7GwNGDAgrHG9Xq+mTJmi+fPnKycnR3l5eZKknj17atiwYcrOzq5TVSgF/mtFaen/b+++46Mu0/3/v6dlUkiFhJBe6SUUpSMCil3XLmDFsmeLuurunq+sropl9+euW466HnU9K+raUFcEBBRFRHqRAIHQISCBBEJ6Qsr8/gifIZGWhGQ+M5PX8/Hg4ZhMuZTck5n3XPd9VZ7xjITGI9UNd9xxh9avX69t27apqKhIpaWlstls6tatm3r27Knx48ef9txBAOYrLy/Xhx9+KEkafMkQdY7r3OzbDrqkIQAsKSnRd999pwsvvLC9ygTgxdauXStJyoyPU2hw+w8Ps1mt6p+aouVbct2PDQCA1LQDsD23ANsadQASAAIt02ECQEmKiIjQ1KlTNXXq1Gbf5vXXXz/rdex2u6655hpdc801zb7fSZMmadKkSc2+/o+NGjVKo0aNavXtAZhrzpw57mlpYyeNa9Ft+47pp4DAAB2rOqa5c+cSAAIdkMvlcodwgzxw/p9hQHqalm/J1YYNG1RTUyOHw+GxxwYAeK8mAaC9/ToAbbYTv3cIAIGW6RBnAAKAt3nvvfckSVHdotRrRO8W3dYZ5FS/sQ0dvp9//jnnnwAdUF5ennuwWVZG+5//ZzDOGqyqqtLmzZs99rgAAO/msSEgNjoAgdYiAAQAD9u3b5+WLFkiSRpx7UhZbS1/Kh40cYgk6eDBg+5zwAB0HN9//7378oC09j//z5CVziAQAMDJmg4Bab8OQDsdgECrEQACgId98MEH7smdI68f3ar7yBo/UBarRZLck4QBdBxGAOh02NU9Pt5jj9stKkrR4eGSxIcPAAA3j3UANjoDsK6urt0eB/BHBIAA4GGzZs2SJKUNTFe39LhW3UdIRIhS+zd04nz77bdtVhsA35CdnS1J6p2UJMcpho21F4vF4u4CpAMQAGDwVAegrdEU4JqamnZ7HMAfEQACgAft2LFDmzZtkiSdf8XQc7ov4+zANWvWuAeKAPB/LpfL3QHY34Pbfw1Z6Q2PmZubq7KyMo8/PgDA+xgBoM3mkNXafjGDxWJxdwGyBRhoGQJAAPAgo/tPkoZcev453ZcRANbU1GjlypXndF8AfMfu3btVXFwsSeqXkuLxx886PnXY5XJp/fr1Hn98AID3qa6uliQ5HO3X/WewWRu6ANkCDLQMASAAeNBnn30mSUodkKYuCV3O6b4yz+sue0DDCyC2AQMdR+MBIP3TUjz++P1TTzwm5wACAKQTHYDtuf3XYEwCZgsw0DIEgADgIbt27dKGDRskSedddm7df5LkDHIqfVCGJLmnCgPwf8b5f4EBAcqIa905ouciPCRE6d1iJUlr1671+OMDALyPMQTE4YEA0DgHkC3AQMsQAAKAhxjdf5I0pA0CQEnqPaKPJGn9+vXuLYEA/JvRAdgnOUl2m+3MV24nA44PAlm9erV7qjkAoOMyOgDbcwKwgQAQaB0CQADwECMATO6bopjkmDa5z57De0mS6uvr2YoHdAD19fXuc/f6NdqK62nnde8uSTp48KB27dplWh0AAO9gnAFo98AZgAwBAVqHABAAPGDv3r3urp222P5rSOmfKpu94UXQ6tWr2+x+AXinXbt2qbS0VJLUP9XzE4ANw3r2cF9eunSpaXUAALyDuwPQ3v4dgHabQxIBINBSBIAA4AHz5s1zXx5y2Xltdr/OIKcSeyVJklatWtVm9wvAOzWeumvGABBDWrdYRYeHSZKWLVtmWh0AAO/g7gD04BAQAkCgZQgAAcADFixYIEnqlhGn2LRubXrfxiCQtWvXqr6+vk3vG4B3MTqJg51OpXdr2+eSlrBYLDq/R0MXIAEgAMAIAB0e2AJss3IGINAaBIAA0M5KSkr03XffSZKyxg9s8/s3AsCSkhJt3bq1ze8fgPcwOgD7JCfLZjX3ZdywXg0BYF5envLy8kytBQBgLoaAAN6PABAA2tlXX33lfoGSNaHtA8CMQZnuy5wDCPivxgNAzNz+axja6BxAugABoGPz5BZgAkCgdQgAAaCdzZ8/X5LUKbKTMgZnnuXaLRedFK2wLg1ncREAAv5rx44dKi8vlyT1S0kxtxhJ3ePjFdEpRJL07bffmlwNAMBMJ4aAEAAC3ooAEADaUW1trb788ktJUv8Ls9wTe9uSxWJR+vEuQAJAwH95ywAQg9Vq1ag+fSRJCxcu5AxSAOjA3B2AHtgCbD1+BmBdXV27PxbgTwgAAaAdrVixQkePHpUkDbxoULs9TlpWmiRp69atKisra7fHAWAeYwBISGCg0mJjzS3muHFZAyRJBQUF2rBhg8nVAADM4h4C4pEOwIYP1Gtqatr9sQB/QgAIAO3ImP5rc9jUd0zfdnuclH6pkiSXy6VNmza12+MAMI8RAPZNSZbV5AEghgsH9JPFYpEkffHFFyZXAwAwi2eHgDgksQUYaCnvePUIAH7KOP+v1/DeCgoNbrfHSe6b4r7ceJsgAP9QV1fn7rDrn5pibjGNdA4LU1ZawwcQBIAA0HEZAaDd4bkOQAJAoGUIAAGgnWzfvl07duyQ1D7TfxsL6xymqLjOkggAAX+0fft2VVRUSJL6p6aaXE1TxjbgdevWqaCgwORqAABm8OQWYOMMQAJAoGUIAAGgnRjdf5KUNaH9zv8zGF2AnMMF+B9j+6/kHQNAGjMCQJfLpXnz5plcDQDADO4hIEwBBrwWASAAtBMjAEzslaQuCV3a/fFS+qVIknJzc92dQgD8gxEAhgYFKTkmxtxifqRvSrISoxue4z7++GOTqwEAeJrL5TrRAeiRLcAEgEBrEAACQDsoKirSypUrJbX/9l+DMQikvr6eQSCAnzG29nvTABCDxWLR1cOHSZK+++47/fDDDyZXBADwpMbTeB2OwHZ/PKuVMwCB1vCuV5AA4CcWLlyouro6SZ4LABkEAvinuro6d6jvTQNAGvvJyBGSGrpA3nrrLZOrAQB4kjEARPLMFmD78SnAxmttAM1DAAgA7WDBggWSpLAuYUodkOaRx4yIiVBE10hJUnZ2tkceE0D727Ztm3tbfz8vDQAz4+M0rGcPSdKMGTPcW8EAAP6v8XO+R4aAHJ8C3LjzEMDZEQACQBurqanRwoULJUkDxmV5dLteUp8kSVJOTo7HHhNA+2o8AMRbA0BJuv3iCZKkQ4cO6d133zW5GgCApzQOAO0eOQOwoQOQLcBAyxAAAkAbW7FihUpKSiRJA8Z7ZvuvIbFnQwCYm5vLiyLATxhb+sOCvW8ASGOXDBmsjLhukqQ///nPKi0tNbkiAIAnNA4AAxzOdn882/EzANkCDLQMASAAtDFj+689wK6+Y/p59LETeyVKkqqqqrRr1y6PPjaA9nFiAEiK1w0Aacxmterh66+VJOXn5+v3v/+9yRUBADzB02cAGlOA2QIMtIzd7AIAwN/Mnz9fktRzeC8FhrT/JLTGEnomui/n5OQoMzPTo48PoG3V1tZq48aNkqR+KckmV3N2l503ROMG9NdX67P11ltvKT4+Xg899JAsFosk6ejRo1q2bJlWrVqlo0ePKj4+XldddRXPVQDgw5qcAeiJDsDjASC7XYCWIQAEgDa0Y8cO7dy5U5KU5eHtv5IUm9ZNNodNdTV1ysnJ0dVXX+3xGgC0nW3btqmyslKSd5//Z7BYLHr+3qm6+vdPaV/hYf3hD3/QRx99pF69emnHjh3KycmRy+Vqcps//vGP+uUvf6lp06Z5dYcjAODUPN0BaLUSAAKtwassAGhDRvefJGVNGOTxx7c77IrLjJfEIBDAHxjbfyWpf2qqiZU0X3R4uN75718rIy5OUkOIOWvWLG3atMkd/gUGBCihS2dZLBa5XC79/e9/17Rp08wsGwDQSp6eAmw7PgWYABBoGToAAaANGQFgQs9EdUnoYkoNiT2TlJezlwAQ8ANNBoB09d4BID+WGhurOdN/r/e+WayF69arsLhYXSMjdV73TJ3fs4ey0tMUYLdrd/5B/fTvLypnb55ef/11jRgxQldeeaXZ5QMAWsDzW4CZAgy0BgEgALSRo0ePasWKFZKkrPFZptVhDALZu3evSktLFRoaalotAM5N4wEgxjl6viLI6dSdF1+kOy++6LTXSYntqrd/+2tNfPQxFRQX67e//a0uvPBCderUyYOVAgDORZMtwA46AAFvxRZgAGgjX331lerq6iSZs/3X0HgQyObNm02rA8C5aTIAxAfO/2utLuFhevqOWyVJBQUFeuONN0yuCADQEp7eAswZgEDrEAACQBsxtv+GRoUqLSvdtDoSfzQJGIBv8rUBIOfikiGDlZWeJkn6xz/+0eTNJADAuzV+zrZ7cApwfX296uvr2/3xAH9BAAgAbaC2tlYLFy6UJPUflyWrzbyn1/CYCIVGNWz7JQAEfFeTASApKeYV4gEWi0U/v/JySVJhYaHmzJljckUAgOby/BCQEyeZ0QUINB8BIAC0gRUrVqi4uFiSlDVhoKm1WCwW9zZgAkDAd33//feSfG8ASGuNH5ilblFRkqQZM2aYXA0AoLkanwHomSEgBIBAaxAAAkAb+OKLLyRJNodNfUf3NbkaKbFXkqSGANDlcplcDYDWyM7OluSbA0Baw26z6YbRIyVJS5cuVX5+vskVAQCao8kQEE90AFpt7svG+dsAzo4AEADagHH+X89hvRQUGmxyNScGgZSWlmrfvn0mVwOgpTrKAJAfu3LYUEmSy+XSp59+anI1AIDmMLYAWyyWJt157cXa6DFqamra/fEAf0EACADnaNu2bdq+fbskKWu8udt/DYlMAgZ82tatWzvMAJDGeiQmKDM+TpI0d+5ck6sBADSHEQDa7QEe6VhnCzDQOgSAAHCOGh9WP2jiYBMrOSEuM859OTc318RKALRGkwEgqakmVuJ5Fw1q+CBlxYoVKikpMbkaAMDZGAGgw97+5/9Jks1KAAi0BgEgAJwjIwBM7Z+qzvFdTK6mgTM4UNGJ0ZKkLVu2mFwNgJYyAsCw4GAlx0SbXI1njcsaIKnhXKevv/7a5GoAAGdjnAHoiQEgkmSznTgDkAAQaD4CQAA4B/v27XNP6hx0yRBzi/mRuMx4SQ1bCQH4lhMDQJI7xACQxgZlpCssuOEs1UWLFplbDADgrIwA0O5o/wEgkmSzOdyXCQCB5iMABIBz0PiMqsGXnGdiJSdrHADW19ebXA2A5mo8AKR/Wsfa/is1TAMe2rOHJGn58uUmVwMAOJsTW4A9EwBa6QAEWoUAEADOgREAdsuIU1xG3Fmu7Vnx3RsCwIqKCiYBAz6kyQCQlBRzizHJ0J7dJUnbt2/XoUOHTK4GAHAm7iEgnuoA5AxAoFUIAAGglQoLC7Vs2TJJ0mAv2/4rSXHHA0CJQSCAL2k8AKQjTQBubGjPnu7LdAECgHfzdAcgU4CB1iEABIBWmj9/vntr7eCJXhgAZhAAAr6oIw8AMfRJTlJIYKAkuT9oAQB4J88PASEABFqDABAAWsmY/hsV11kp/b3vnK7AkEB1TmiYSkwACPgOIwDsl5rS4QaAGOw2m4ZkZkgiAAQAb+ceAmJCB2BNTY1HHhPwBwSAANAKZWVl+uabbyRJgycO9to36fFMAgZ8Sm1trTZt2iSp427/NRiDQHJyclRUVGRyNQCA03FvAfZQB2DjoJEAEGg+AkAAaIUvvvjC/Wnn4Eu9a/pvY8Y5gLm5uXK5XCZXA+BsGABywvnHA0CXy6VVq1aZXA0A4HTcQ0A81AFotzncl43X4wDOjgAQAFph1qxZkqTQqFB1P6+HydWcntEBWF5erv3795tcDYCzaTwApH9ainmFeIH+qSmyWRteqjb+/wIA8C4e7wBsNG2YABBoPgJAAGih0tJSffnll5Kk8y4/X1ab9z6VxmWeGASyZcsWEysB0Bzff/+9JCk8JERJ0R1zAIghMCBAmfFxkggAAcCbuYeAeKoD0E4HINAa3vuuFQC81Lx581RVVSVJOv/KYSZXc2aNA0DOAQS8X3Z2tiSpb0qy154t6kn9UxsGLBnBKADA+7iHgDg8FQCe6DQkAASajwAQAFroP//5jyQpomukV2//laSgTkGKiussiUnAgLerra3Vxo0bJTEAxNAvNVmSdPDgQeXn55tcDQDgVIwPxukABLwbASAAtEBRUZG+/vprSdL5Vwz16u2/hrjMhi10BICAd8vNzXW/iepPACjpRAegxDZgAPBW7g5Au2fOAGwcNBIAAs3n/e9cAcCLzJkzRzU1NZKkoVd59/ZfQ3z3BElMAga8XeOAiw7ABr2SEhkEAgBezuNDQAgAgVYhAASAFjC2/3ZJjFZaVrq5xTSTcQ5gWVmZDhw4YHI1AE6HASAnCwwIUI+EhucwzgEEAO/kHgLisTMA2QIMtAYBIAA006FDh/Ttt99Katj+6ysH9MczCRjwCUbA1T81xWeeXzzB6IZcv349XcwA4GXq6upUW1srqWlnXnuyWm2yWm2SCACBliAABIBm+uyzz1RfXy9JGnrVcJOraT4mAQPe79ixY9q0aZMkaUBa6lmu3bH0S0mR1PAhzMGDB80tBgDQhLH9V/JcB6B04hxA42geAGdHAAgAzWRs/41N76ak3knmFtMCwWHBioyNlEQHIOCtcnJy3F0MBIBN9UxKdF/evHmziZUAAH6scQeepzoAJcl2fBtw4wASwJkRAAJAM+Tl5Wn58uWSpKFXDPO57XmNB4EA8D7r1q1zXx6QlmZiJd6nZ2KC+zIBIAB4l6YdgJ4ZAiJJjuMTh+kABJqPABAAmuGDDz5wXx5+7UgTK2kdYxvw1q1bOUML8EJGABgTEaHYqEiTq/EuYcHBiu/cWVJDpyQAwHs07gA0QjlPsNMBCLQYASAAnIXL5dL7778vScoYnKnY1FiTK2o5IwAsKSlRfn6+ydUA+DFjAAjbf0+tx/EuQDoAAcC7NNkC7MEzAI0twHQAAs1HAAgAZ7Fy5Urt2rVLkjTq+tEmV9M68d1PDAJhGzDgXcrLy93rkgDw1HolNpwDuHXrVve0SQCA+aqqqtyXHR48A9B4LKYAA81HAAgAZ2F0/9mdDp13xVCTq2mduAwCQMBbZWdnuyeMEwCemnEOYFVVlfsDGQCA+RoHgAEBQR57XDsBINBiBIAAcAaVlZXu6b+DLh6skPAQcwtqpZCIEEXEREgiAAS8jbH9V5L6pxIAnkrjQSCcAwgA3qNpABjoscclAARajgAQAM5g3rx5Ki0tleS7238NTAIGvJMxACQpJlqRoZ1MrsY7pXWLlcNmk8Q5gADgTSoqKtyXPRsANpwBSAAINB8BIACcwXvvvSdJCo8OV5/RfU2u5tzEZcZJYhIw4G2MAJDtv6fnsNuVEd/wHEYACADeo0kHoMNzAaDDQQcg0FIEgABwGvn5+Vq0aJEkafi1I2Wz28wt6BwZk4CPHj2qQ4cOmVwNAEkqKirS7t27JREAnk3PBCYBA4C3aRIAOj13BqDNRgAItBQBIACcxsyZM90H8/v69l/pRAAosQ0Y8BZG958kDUhLM7ES75cR302StGfPniZvOAEA5qEDEPAdBIAAcAoul0tvvfWWJCmlX6oSeiSaXNG5i+9OAAh4GyMAtFos6puSbHI13i0zruE5rL6+Xjt37jS5GgCA1DAwz+DRMwBtnAEItBQBIACcwnfffed+gzl20oUmV9M2OkWGKiw6XFLDOYAAzGdMAM6Ij1NIoOfeOPkiowNQ4kMMAPAWjQNAh8Ppsce10wEItBgBIACcwowZMyRJgSGBGnr1cJOraTvxx7cBb9myxeRKAEiNBoCkcv7f2STHxLgnAW/bts3kagAA0oktwA6HUxaLxWOPSwcg0HIEgADwI4WFhZozZ44kadjVwxXUyXMHGre3uOPbgHNzc5kEDJjswIEDOnjwoCQGgDSHw25XSmxXSXQAAoC3MAJAZ4BnXy8b3YY1NTUefVzAlxEAAsCPvP/+++5PE8dOGmdyNW3L6AAsKipSYWGhydUAHVvTASAEgM2RERcniQ5AAPAWxhZghwfP/5Mkm50OQKClCAABoBGXy+Xe/pvcN0Up/f3rTTmTgAHvYQSADptNPZN8f9CQJ3SPbwgAd+zYodraWpOrAQAYHYCeHAAisQUYaA0CQABoZOnSpX43/KOx+O4J7ssEgIC5jAEgvZKS5HQ4zC3GRxgdgMeOHdOePXtMrgYA4A4AHZ4NAB0MAQFajAAQABoxuv+cwU4N86PhH4bQqFCFdg6TRAAImMnlcrkDQLb/Nl/m8Q5AiWnmAOANjC3AAR4+A9BuIwAEWooAEACOKygo0OzZsyVJQ68arqDQYJMrah9xmQ1voHnzDJhn165dOnr0qCQCwJZI6xbrnjLJhxgAYL4TAaCHtwAf7wCsq6tTXV2dRx8b8FUEgABw3IwZM9yfIo6bMt7katqPsQ2YN8+AeYzuP4kAsCUCAwKUGN1FEoNAAMAbmHYGoP3E0Rl0AQLNQwAIAJJqamr0r3/9S5KUMTjT74Z/NGYMAiksLGQSMGASYwBIsNOpjEbbWnF2xjZgPsQAAPOZdQag3R7gvkwACDQPASAASJo9e7by8/MlSRPuvNjkatpXfKNJwGwDBsxhBID9UlNks/JyrCWMQSDbtm1TfX29ydUAQMdmBIAOj3cAEgACLWU3uwD4BovFIquPvUGx2WxN/gnv5Q1/R//85z8lSRFdI3T+5UN97ue9JRJ7Jrovb9u2TaNHjz7pOqwf38Lfk/c50xqqra1Vdna2JCkrPc2vn2/aQ/f4hg8xKioqdPDgQSUkJJzlFmfG+vE+/A7yLfw9eR9PriHjDECnM8ijv8+cjQLH2tpafg6BZiAARLMEBQUpONg3ByKEhYWZXQLOwGazKTIy0tQa1q1bpxUrVkiSLr7zEnUK7WRqPe3NGe9UaFSoSo+Uavfu3Wf8/8/68X7esIZweqdaQ9nZ2e43TEN69FBgoGe7Jnxd30ZnJu7fv1/9+vVr9X2xfrwbv4O8H2vIu3liDVVXV0uSgoM6efT3WadOJ/7b7Ha7T/4cElrC0wgA0SyVlZXuJ3dfYbPZFBYWppKSEiZDeaGwsDDZbDbV1dWppKTE1Fr+9Kc/SZLsAXaNvukC91YGfxaXGa/cFVuUnZ2toqKik77P+vF+3rSGcLIzraFFixa5L/dOTOgQzzltKalLF/flNWvWaOjQoS2+D9aPd+N3kPdjDXk3T66hiooKSZLVavfo7zOL5cQQkPz8fMXGxnrssc9V4/VDCAhPIgBEs7hcLp99AcZoeO9n5t9PYWGhPvroI0nS+VcMU2jn0A5xppQRAG7evPmM//9ZP76BvyPvdao1tHbtWklSZKdOSujSuUM857SlkECnukZG6GDRUeXm5p7zzz/rx3vxO8g38HfkvTyxhtxnADqcHv195nA43ZdLS0v5OQSagUNnAHRob731lru7dcKdF5lcjecYk4ALCgp05MgRk6sBOhYjAOyfmiKLxWJyNb7JGATCICMAME99fb37dXSAh4eAOJ0njqcyjtUAcGYEgAA6rOrqar322muSpPRBGUobkG5yRZ4TnxnnvswbaMBzKioqlJOTI0nKyug4zzltLTOum6SGQUYAAHM03vIb4DAvADS2IQM4MwJAAB3Whx9+qIKCAknSpfddbnI1nmV0AEpSbm6uiZUAHcv69evd25QGEQC2mtEBeOTIERUWFppcDQB0TGVlZe7LgYGeHaLXeAowASDQPASAADqk+vp6vfzyy5KkrildNejiwSZX5FnhMREKCQ+RRAAIeJKx/VeSstLSTKzEt2XE08UMAGZrGgCGePSx2QIMtBwBIIAO6YsvvnBvHZt4z6Wy2jrW06HFYnF3AfLmGfCcNWvWSJJSunZVZKhnuyX8ScbxLcAS24ABwCyNA8CgIM/+TgsICHJfpgMQaJ6O9Y4XAI578cUXJUmhUaEadcMYk6sxhxEA0gEIeI7RATgwne6/cxEdHq6w4IbuDz7EAABzlJaWui97ugPQbnfIZnNIogMQaC4CQAAdzpo1a7R8+XJJ0vjbL1JAYIDJFZkjvntDAJifn6+jR4+aWwzQAeTn52v//v2SpIGc/3dOLBaLMuOZBAwAZiovL3df9nQHoCQ5nUEn1QHg9AgAAXQ4L730kiQpIDBA42+/yORqzJPQM9F92ZhKCqD9GNt/JToA20IGk4ABwFRmDgGRJOfxbcBsAQaahwAQQIeyfft2zZkzR5I06sYxCo0KNbki8xAAAp5lBIBOh129kpNMrsb3GZOA9+/f3+RNKADAM5qcAejhLcDSiUEgbAEGmocAEECH8pe//EX19fWy2qy65J7LzC7HVGGdwxQREyGJABDwBOP8vz7JyQqw202uxvc1HgSyfft2EysBgI6p6RmAZmwBbggA6QAEmocAEECHsXPnTs2cOVOSNPK6UYpJjjG5IvMl9GroAiQABNpXXV2d1q1bJ4nz/9pKxvEzACXOAQQAMxgdgAEBgbLZPP/BVkBAoCQ6AIHmIgAE0GH89a9/VX19vSxWi674xVVml+MVEns2bEPcvHmz6uvrTa4G8F9btmxxdyhw/l/bSOjSRU5HwwRIAkAA8DwjADSj+0+iAxBoKQJAAB3Cnj179MEHH0iShl8zUl1TYk2uyDskHu8ArKio0O7du80tBvBjxvZfScpKpwOwLdisVqV3a3guZxAIAHjeiQDQ8+f/SQwBAVqKABBAh/DXv/5VdXV1slgsuvKXdP8ZEnudGETANmCg/axevVqS1DksVInRXUyuxn8Yg0DoAAQAzzMCwCCTOwDZAgw0DwEgAL+Xl5en9957T5I09Kph6pYed5ZbdBzd0uNks9skEQAC7cnoAByYni6LxWJyNf7DOAdw165dOnbsmMnVAEDHYgwBMa0D0EkHINASBIAA/N4LL7yg2trahu6/X1xtdjlexR5gV7eMhjfQBIBA+ygtLVVubq4kaWAG5/+1JWMScF1dnXbt2mVyNQDQsbg7AIPM6QAMYAsw0CIEgAD82rZt2/Tvf/9bknTeFUMV3yPB5Iq8j3EO4KZNm0yuBPBP33//vVwulyTO/2trmXFMAgYAszAEBPAtBIAA/Nqzzz6r+vp62ew2Xffr680uxysZk4B3797tfiEHoO0Y5/9ZLBYNSEs1uRr/khLbVdbjW6oZBAIAnlVeXi5JCjJpC3BgYLC7jvr6elNqAHwJASAAv7V27VrNnj1bknTBLWOZ/HsaCcc7ACVpy5YtJlYC+Cfj/L+MuG4KCw42uRr/4nQ4lNw1RhIBIAB42okzAM3pAAwJiZAkuVwulZSUmFID4EsIAAH4JZfLpenTp0uSAoKcuur+a8wtyIsZHYAS5wACbc3lcmnNmjWSGgaAoO0xCRgAPK+2tlZHjhyRJIWGRplSQ2inSPflw4cPm1ID4EsIAAH4pS+++EJLliyRJF08daIiukae5RYdV0TXCHWKbPjkduPGjSZXA/iXvLw8FRQUSJKy0hkA0h6MQSDbt29nCxgAeMjhw4fd59tGhMeYUkOnRgFgUVGRKTUAvoQAEIDfqa6u1u9+9ztJUmjnMF320ytMrsi7WSwWJfZq6AIkAATa1ooVK9yXh3TPMLES/2V0AFZUVGj//v0mVwMAHcOhQ4fcl8PDu5hSQ+MA0OhGBHB6BIAA/M6rr76qXbt2SZKu/80NCg7jzK2zSe6XIqlhEnBdXZ25xQB+xAgAw4KD1D0+3uRq/FNmPJOAAcDTjO52SQoPjzalBjoAgZYhAATgV/Lz8/XnP/9ZkpTcN0Wjb7zA5Ip8Q0q/hsmkFRUVHKQPtCEjAByUkSGrlZdd7SG9Wzf3ZZ6/AMAzmnQAhpnUAXh8CIhEAAg0B69EAfiV6dOnq7y8XJI0+YlbZbXxNNccRgAoSevXrzexEsB/lJSUuAfrDM5k+297CQ0OUmxkQxcIHYAA4BlGAGixWBQa2tmUGgICAuV0Nuz0YQswcHa8MwbgNxYtWqQPPvhAkjTs6uHqfn4PkyvyHTHJMQrsFChJys7ONrkawD8sX77cfUD6kO6ZJlfj3zLimQQMAJ5kbAHu1ClSdrvDtDqMbcAEgMDZEQAC8AtlZWV6+OGHJUkh4SG6+bHJJlfkW6xWq5L7pkiiAxBoK999950kyWa1amB6usnV+LfM44NAtmzZ4g5dAQDtx+gANOv8PwMBINB8BIAA/MIf/vAH7d27V5J08+OTFRETYW5BPsjYBrxhwwYGgQBtwAgAeycnKTjQaXI1/q1nYoIkqbi4WAcOHDC5GgDwf0YHYITJAWBopwhJnAEINAcBIACft2rVKr366quSpD6j+2rU9aNNrsg3NR4Esn37dpOrAXxbbW2tewDIkEy2/7Y3IwCU5D53EQDQPlwul3JzcyVJUVFxZ7l2++oU0tABSAAInB0BIACfVlxcrPvuu08ul0sBQU7d8dxdslgsZpflk4wtwBLbgIFzlZOTo7KyMkmc/+cJ3RPi3Zc3b95sYiUA4P927tzp3gLcPWOIqbUYW5Dp/gbOjgAQgM9yuVx68MEHlZeXJ0ma/OStik6KMbkq3xWbFqvAkIZBIASAwLkxuv8kaQgTgNtdSGCgkmIa3gQSAAJA+6isrNT999+vqVOnur/Wo8f5JlYkxcQkSWo4A7CkpMTUWgBvRwAIwGfNmDFDs2fPliQNvWqYxtx0gckV+Tar1aqkPsmSCACBc2UEgPFdOqtb5yiTq+kYjG3AbAEGgLZXWVmp2267Te+++642bdokSQoPi1Zs11RT64qJTnJf3rNnj4mVAN6PABCAT1qzZo2mTZsmSYpOitHtz7L1ty0Y5wBmZ2ervr7e5GoA3+RyubRs2TJJ0nndu5tcTcfRM6EhANy2bZtqampMrgYA/Mu8efO0aNGiJl/r3+8C019/EwACzWc3uwAAaKn9+/fr1ltvVXV1tewBdv3XSz9XcFiw2WX5BeMcwLKyMm3btk0xMWypBlpq586d7rOIRvTpZXI1HUePxERJ0rFjx7Rz50716NHD5IoAwH98++23kiSbza47bntGmRmDFB9n/odcXbokui8TAAJnRgcggCbKysr0ww8/aP/+/SouLpbL5TK7pCaKiop0yy23qKCgQJJ05x/vVtqAdJOr8h+p/U9s41i1apWJlQC+a+nSpe7Lw3sRAHoKk4ABoP0YAWBW/3G68IJblBDfw/TuP0lyOoMUEdHwgTUBIHBmdAACHVxubq7mzZunxYsXKycnR4WFhU2+HxISooyMDA0ZMkSjR4/WiBEjFBkZaUqtZWVluuWWW9wHvF/x8ys18rpRptTir2LTuykoLFiVJRVavny5Lr/8crNLAnzOd999J0nqFhWllK4xXvdBir9Kje0qp8Ou6ppa5eTk6Cc/+YnZJQGAX9i3b592794tSerTx/tee8dEJ+no0UPatWuX2aUAXo0AEOiAXC6XZs+erf/93/9tMqnyVMrLy7V+/XqtX79e//znP2Wz2TR27Fhdd911uvTSS9WpUyeP1Gx0/q1Zs0aSNObmC3Tdb270yGN3JFarVelZ6dq4eIP7DDMAzedyudwB4Ig+vWWxWAgAPcRusykzPl4bd+/Rxo0bzS4HAPxG4+nqGekDTazk1OK6ZWjrttXasmWL2aUAXo0AEOhgVq1apWnTpmndunVNvp7UJ1kZgzIUm9ZNnSI7yWK1qrK0QgV7C7QvN0/bVm1VVXmV6urqtHDhQi1cuFChoaG66aabNHXqVGVkZLRbzXv27NGUKVPcv9TPv3KY7nhuqldsO/BH6QMztHHxBq1fv17l5eUKDAw0uyTAZ+zcuVP5+fmSpJF9e5tcTcfTNyVZG3fv0YYNG8wuBQD8xs6dO92XY2PTTKzk1BISGs58zc/PV1FRkWm7lQBvRwAIdBCVlZV67rnn9Morr7i7UcKjwzXu1gkadeMYdY7rfMbb19bUatf6nVozb7WWf7pMRw8WqbS0VK+//rpef/11jR07VnfddZcuvvhi2Wy2Nqt74cKF+ulPf6qjR49KksbcPFZ3PHeXrDaOMG0v6YMbwty6ujqtX79eQ4cONbkiwHc0Pv9vZJ8+JlbSMfVNTpYkHTx4UPn5+YqNjTW5IgDwfTt27JAkhYdFKzgo1ORqTmYEgJK0ZcsWDR8+3MRqAO9FAAh0APv27dNtt93m7ohwBjt15S+u1kVTJ8oZ5GzWfdgddmUO6a7MId114/+7WTnfbdJXb32pdV+slavepUWLFmnRokVKSEjQ5MmTNWnSJMXFxbW65qNHj+rJJ5/U22+/7f7a1Q/+RNf86lo6/9pZetaJbs5Vq1YRAAItYGz/7RoZqbRusaqurja5oo6lb2qy+/KGDRsIAAGgDRgdgLGxqWe5pjkSE3q6LxMAAqdHAAj4uaVLl2rq1Knu4R69RvTWXc/fo+jE6Fbfp9VmVd8x/dR3TD8d3l+or99eqG/eXaTSI6Xat2+f/vjHP+r555/XhAkTdP3112v8+PEKCwtr1n0fPnxY//rXv/SPf/xDxcXFkqTgsGDd85efauBFg1pdM5ovJCJEcZnx+mHbfiYBAy3Q+Py/4b168mGFCXolJspqsaje5VJ2drYuuugis0sCAJ9ndAB64/ZfSQoP66KEhB6Kj49RVFSU2eUAXosAEPBj//nPf/Rf//Vfqq2tlSRd8YurdO3D17fp9tnO8V10/W9v0tUPXqtVc1Zo0Ttfaeuqraqvr9eCBQu0YMECORwOjRw5UoMHD1ZWVpYyMjKUkZEhh8Oh0tJSbdjQcN7cN998o4ULF6qmpsZ9/4MvGaJbp9+uiK6c5eFJ6YMy3AGgy+UiyACaofH5f8N79zzLtdEegpxOZcTHaeu+/ZwDCABtoKqqSvv27ZMkxXZNMbeYM/jD01+ob3+H4hOJOIDTYXUAfuq9997TAw88oPr6egUEOXX3n+7R+VcOa7fHczgdGnHtKI24dpR+2LZf37y3SEs//k6lh0tUU1Pj3iLcXBmDM3Xtw9ep18g+hE8myBzcXd++/40KCgq0a9cupaV55ye+gDdZsmSJ+/LwXgSAZumTnEQACABt5IcffnBfjo5ONLESAOeKABDwQ2+++aYeeeQRSVJQWLAefvPXyhic6bHHj8uM1y2PTdZNj96ibau3au381dqyfIv2bclTXW3daW8XnRSj/hcO0KjrRyulfyrBn4l6DD1xmPLSpUsJAIFm+PrrryVJ8Z07K5Wz50zTLyVFn3y3THv37mUaJACcowMHDrgvR0Xyuw3wZQSAgJ/54IMP3OFfp8hOeuTt3yqlnzkH9lptVvUY2lM9hjZ0whyrOqZ9uXk6vP+wqkurJFlkD7ArLDpUsendFNXtzJOI4Tmxad0UHhOh4kNHtWzZMk2ZMsXskgCvVltbq8WLF0uSxvTvywcYJuqbcmIQSHZ2ti644AITqwEA32YcbSFJkREEgIAvIwAE/Mi8efN0//33S2oI//77g2lK6OE9rfoBgQFKG5CutAHpCgoKksVikcvlUmVlpdml4UcsFot6D++tZZ8u1bJly8wuB/B6a9euVWlpqSRpTL++JlfTsfVJTnb/flmzZg0BIACcg8YdgJGRXU2sBMC5artJAABMtXTpUt19992qq6tTYEigHp7xG68K/+B7eo3oI0nKy8tTXl6eydUA3s3Y/mu1WDSyT2+Tq+nYQoOD1D0+XpK0evVqk6sBAN9mBIBhoZ1ltweYXA2Ac0EACPiB7du36/bbb1d1dbXsToceeOMhpQ7gzDacm94jToQYS5cuNbESwPsZQ46y0tMUERJibjHQoMx0SdKaNWvkcrlMrgYAfJcRAEZy/h/g8wgAAR9XWFioW265RUePHpXFYtFP//4z9RpO9wnOXUKPRHWK7CRJbAMGzqCoqEhr166VxPZfbzE4I0OSdOTIEe3cudPkagDAdxlnALL9F/B9BICAD6uqqtJtt92m3bt3S5JunHaLhlx6nrlFwW9YrVb1GNpLkrRkyRK6aIDT+PLLL1VfXy9JGjugn8nVQDrRASixDRgAzgUdgID/IAAEfFR9fb3uv/9+rVq1SpJ04ZTxuuSeS02uCv6mz+iGbqY9e/Zo165dJlcDeKd58+ZJkqLDw5SVxvEL3iAtNlZhwcGSCAABoLXq6+vdHYBRBICAzyMABHzUH//4R33yySeSpL4X9NOUp26TxWIxuSr4m35jTnQzGWecATihurpaX331lSRp/MAsWa28tPIGVqtVgzIaugCND8oAAC1TWFio2tpaSVJkBAEg4Ot4lQr4oPfff18vvPCCJCmhZ6J+/vIvZbPbTK4K/qhraqyik2IknZhyCuCEpUuXqqysTJJ00aCBJleDxgZlNpwDuHnzZvffEQCg+YztvxJbgAF/QAAI+Jhly5bpV7/6lSQpLDpcv/q/hxUUGmxyVfBnfY93AX777beqqakxuRrAuxjbfwMDAjSqDwOYvMn5PbpLatjCxiRzAGg5Y/uvxBZgwB8QAAI+ZOfOnbrjjjtUU1Mjh9OhB//5kDrHdzG7LPi5vmMazgEsLy9nKx3QSH19vT7//HNJ0qg+vRXkdJpcERoblJEup8MhqWGQEQCgZegABPwLASDgI44ePapJkybpyJEjkqR7//pfSstKP8utgHPXa0QfWW0Nvy6Ms84ASCtWrHC/Obp8KBPYvU1gQICGdM+UJC1evNjkagDA9xi/4xwOp0JCwk2uBsC5IgAEfEBNTY3uuusu7dixQ5J0/W9u1HmXn29yVegogsOClTmkYSvd/PnzTa4G8B7GICanw66LBw0yuRqcysjj27I3bdqkwsJCk6sBAN9iBICRkbEMGwT8AAEg4OVcLpd+85vf6Ntvv5Ukjbx+tC7/+ZUmV4WOZtDEwZKkLVu2uINooCOrra3VrFmzJEnjsgYoNDjI5IpwKiN793JfZhswALSMEQBy/h/gHwgAAS/3/PPP6+2335Yk9RjWU3f+YSqfwMHjBl082H3ZGHoAdGTffvutDh8+LEm6cthQk6vB6fRLTVFoUEM4SwAIAC1jDAHh/D/APxAAAl7s9ddf1/PPPy9Jik2L1S//9wHZA+wmV4WOKDopRom9kyRJc+fONbkawHwffvihJCkkMFDjswaYXA1Ox26zaVivnpKkr7/+Wi6Xy+SKAMB3uLcARxAAAv6AABDwUh9//LEeffRRSVJUtyj9+p3/VqfIUJOrQkdmdAGuWrVKhw4dMrkawDxFRUXu7b+XnTeE6b9ebtzxgHbv3r3auHGjydUAgG+oqKhQcXGxJCkqsqvJ1QBoCwSAgBf68ssv9fOf/1wul0shEZ30yNu/Vef4LmaXhQ5u0MQhkhrOpfzss89MrgYwz4cffqjq6mpJ0qRxY80tBmd18eCB7qMz6GAGgOYxuv8ktgAD/oIAEPAyCxYs0O23367a2lo5g5166M1HFJcZb3ZZgJJ6J6lbRpwkaebMmSZXA5jD5XJpxowZkqSeiQkalJFuckU4m+jwcA3OzJBEAAgAzWWc/ycRAAL+ggAQ8CJz5szRHXfcoWPHjsnhdOj+136l9IEZZpcFSJIsFouG/2SkJGn16tXauXOnyRUBnrd8+XLl5uZKkiZdOJahTD7i0iENRxjk5ORo165dJlcDAN6vcQcgU4AB/0AACHiJf//737r77rtVU1OjgCCnHnrz1+ozuq/ZZQFNDL9mhPsyXYDoiF566SVJUpAzQNeMHG5yNWiuiUNOTDKfPXu2iZUAgG9oHABGRMSYWAmAtkIACJjM5XLpueee0wMPPODe9vvwjF+r14jeZpcGnCQ6MVrdz+8hqeEcNCZqoiPZvHmz5s+fL6mh+y8iJMTcgtBsSTHR6puSLEl67733eO7CKdXW1ppdAuA1jAAwLKyL7PYAk6sB0BYIAAETlZWV6b777tMLL7wgSQqPDtf/++B36jG0p8mVAac34tpRkqTdu3dryZIlJlcDeM7f//53SZLDZtO9l15icjVoqZsvGCNJ2rp1q7777juTq4G3eeONN3Tttdfq8OHDZpcCnDOXy6WNGzfq+eef1zvvvNOq+zACQM7/A/wHASBgkpycHF100UX65JNPJEnx3RP0+KwnldI/1eTKgDMbdvVwBYUGSZL++c9/mlwN4Bnbtm1zP19fO2qEunWOMrkitNQ1I4crMKChi+X11183uRp4k2+++UaPPvqoli1bpokTJ+qHH34wuyTgnCxdulT9+vXTc889p0cffbTJdt7m2rdvnySpc1S3ti4PgEkIAAEPq6ur0yuvvKKJEydq+/btkqSBFw3Sox89ps7xXUyuDji7wJBAjbxutCTp888/d79ABPzZ448/rrq6OtltNv3sysvNLgetEBYcrCuGniep4QzToqIikyuCN3C5XHrkkUdUV1cnSdqzZ4/eeustk6sCzs3LL7/svlxRUaHp06e3+D6M13dduiS0WV0AzEUACHhQdna2Jk6cqMcee0xVVVWyOWy65fEpuv/1XykknLOk4DvG3TZBklRfX6//+7//M7kaoH0tXLhQX375pSTpjosmKDWW7VC+atKFYyVJVVVV7oEu6NjWr1+v3bt3N/na+++/r/r6enMKAs7Rnj17NG/evCZfmzVrlsrKypp9H+Xl5SosLJQkdelMAAj4CwJAwAN2796tn/3sZ5owYYLWr18vSUrokaBpHz+uiXdfIovFYnKFQMvEZcS5p1S/+eabKikpMbkioH2Ul5fr0UcflSRFduqk+39ylckV4VwMzszQ4MwMSdKf//xnHT161NyCYLr//Oc/kiSr1aZbbpomScrLy9PKlStNrApova+//to96OjO25+VJFVXV+ubb75p9n3s37/ffblL5/i2LRCAaQgAgXaUnZ2t+++/X8OHD3dPTLU7HbruNzfoiTlPK21AutklAq122U+vkCQVFxfrtddeM7kaoH089thj2rlzpyTp1zdcx+RfH2exWPTQdT+RJB09elR/+ctfTK4IZjO6e3v3GqGxY26WxdLw9qglYQngTYwBbZ07x+nCC25RcFCYJJ3UFXgmeXl57svR0XQAAv6CABBoY0eOHNGMGTN0+eWXa/z48Xr33XdVW1sri9WiUTeM1nNf/X+68hdX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", + "text/plain": [ + "
" + ] + }, + "metadata": { + "image/png": { + "height": 480, + "width": 640 + } + }, + "output_type": "display_data" + }, + { + "data": { + "text/plain": [ + "
" + ] + }, + "execution_count": 30, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "df_ppo = pl.from_records(ppo_sims, \"x\").with_columns(pl.lit(\"ppo\").alias(\"model\"))\n", + "df_tqc = pl.from_records(tqc_sims, \"x\").with_columns(pl.lit(\"tqc\").alias(\"model\"))\n", + "df_msy = pl.from_records(msy_sims, \"x\").with_columns(pl.lit(\"msy\").alias(\"model\"))\n", + "df = df_tqc.extend(df_ppo).extend(df_msy)\n", + "\n", + "(ggplot(df, aes(\"x\", fill=\"model\")) +# geom_bar(stat=\"bin\", binwidth=1, alpha=0.5) + \n", + " geom_density(alpha=0.5) \n", + ")" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.12" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/notebooks/optimal-fixed-policy.ipynb b/notebooks/optimal-fixed-policy.ipynb new file mode 100644 index 0000000..5b1b806 --- /dev/null +++ b/notebooks/optimal-fixed-policy.ipynb @@ -0,0 +1,313 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "ba1c2a7a-d99f-499d-9481-f5516c547246", + "metadata": {}, + "source": [ + "This notebook tries to search for optimal fixed policies (e.g. constant mortality) that maximize the objective (i.e. expected net reward). Here I try [scikit-optimize](https://scikit-optimize.github.io/stable/index.html) routines which are designed for noisy functions and compare to a brute-force parallel grid search. " + ] + }, + { + "cell_type": "code", + "execution_count": 47, + "id": "f15d4b8e-ef57-4bce-899b-89bb32d396f6", + "metadata": { + "scrolled": true + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Obtaining file:///home/rstudio/rl4fisheries\n", + " Installing build dependencies ... \u001b[?25ldone\n", + "\u001b[?25h Checking if build backend supports build_editable ... \u001b[?25ldone\n", + "\u001b[?25h Getting requirements to build editable ... \u001b[?25ldone\n", + "\u001b[?25h Installing backend dependencies ... \u001b[?25ldone\n", + "\u001b[?25h Preparing editable metadata (pyproject.toml) ... \u001b[?25ldone\n", + "\u001b[?25hRequirement already satisfied: gymnasium in /opt/venv/lib/python3.10/site-packages (from rl4fisheries==1.0.0) (0.28.1)\n", + "Requirement already satisfied: numpy in /opt/venv/lib/python3.10/site-packages (from rl4fisheries==1.0.0) (1.26.4)\n", + "Requirement already satisfied: matplotlib in /opt/venv/lib/python3.10/site-packages (from rl4fisheries==1.0.0) (3.8.2)\n", + "Requirement already satisfied: typing in /opt/venv/lib/python3.10/site-packages (from rl4fisheries==1.0.0) (3.7.4.3)\n", + "Requirement already satisfied: jax-jumpy>=1.0.0 in /opt/venv/lib/python3.10/site-packages (from gymnasium->rl4fisheries==1.0.0) (1.0.0)\n", + "Requirement already satisfied: cloudpickle>=1.2.0 in /opt/venv/lib/python3.10/site-packages (from gymnasium->rl4fisheries==1.0.0) (3.0.0)\n", + "Requirement already satisfied: typing-extensions>=4.3.0 in /opt/venv/lib/python3.10/site-packages (from gymnasium->rl4fisheries==1.0.0) (4.9.0)\n", + "Requirement already satisfied: farama-notifications>=0.0.1 in /opt/venv/lib/python3.10/site-packages (from gymnasium->rl4fisheries==1.0.0) (0.0.4)\n", + "Requirement already satisfied: contourpy>=1.0.1 in /opt/venv/lib/python3.10/site-packages (from matplotlib->rl4fisheries==1.0.0) (1.2.0)\n", + "Requirement already satisfied: cycler>=0.10 in /opt/venv/lib/python3.10/site-packages (from matplotlib->rl4fisheries==1.0.0) (0.12.1)\n", + "Requirement already satisfied: fonttools>=4.22.0 in /opt/venv/lib/python3.10/site-packages (from matplotlib->rl4fisheries==1.0.0) (4.48.1)\n", + "Requirement already satisfied: kiwisolver>=1.3.1 in /opt/venv/lib/python3.10/site-packages (from matplotlib->rl4fisheries==1.0.0) (1.4.5)\n", + "Requirement already satisfied: packaging>=20.0 in /opt/venv/lib/python3.10/site-packages (from matplotlib->rl4fisheries==1.0.0) (23.2)\n", + "Requirement already satisfied: pillow>=8 in /opt/venv/lib/python3.10/site-packages (from matplotlib->rl4fisheries==1.0.0) (10.2.0)\n", + "Requirement already satisfied: pyparsing>=2.3.1 in /opt/venv/lib/python3.10/site-packages (from matplotlib->rl4fisheries==1.0.0) (3.1.1)\n", + "Requirement already satisfied: python-dateutil>=2.7 in /opt/venv/lib/python3.10/site-packages (from matplotlib->rl4fisheries==1.0.0) (2.8.2)\n", + "Requirement already satisfied: six>=1.5 in /opt/venv/lib/python3.10/site-packages (from python-dateutil>=2.7->matplotlib->rl4fisheries==1.0.0) (1.16.0)\n", + "Building wheels for collected packages: rl4fisheries\n", + " Building editable for rl4fisheries (pyproject.toml) ... \u001b[?25ldone\n", + "\u001b[?25h Created wheel for rl4fisheries: filename=rl4fisheries-1.0.0-0.editable-py3-none-any.whl size=2176 sha256=aebb65ca4f07d99d588c7fb0de18b7cdbb9aff0bb29ab44fe3dd315eb92caf22\n", + " Stored in directory: /tmp/pip-ephem-wheel-cache-t5m_i4it/wheels/d3/ce/fe/d5af67bb4edf309f6a59d59140b2b78d5a336b2ad4b93a1fb4\n", + "Successfully built rl4fisheries\n", + "Installing collected packages: rl4fisheries\n", + " Attempting uninstall: rl4fisheries\n", + " Found existing installation: rl4fisheries 1.0.0\n", + " Uninstalling rl4fisheries-1.0.0:\n", + " Successfully uninstalled rl4fisheries-1.0.0\n", + "Successfully installed rl4fisheries-1.0.0\n", + "Note: you may need to restart the kernel to use updated packages.\n", + "Requirement already satisfied: scikit-optimize in /opt/venv/lib/python3.10/site-packages (0.9.0)\n", + "Requirement already satisfied: joblib>=0.11 in /opt/venv/lib/python3.10/site-packages (from scikit-optimize) (1.3.2)\n", + "Requirement already satisfied: pyaml>=16.9 in /opt/venv/lib/python3.10/site-packages (from scikit-optimize) (23.12.0)\n", + "Requirement already satisfied: numpy>=1.13.3 in /opt/venv/lib/python3.10/site-packages (from scikit-optimize) (1.26.4)\n", + "Requirement already satisfied: scipy>=0.19.1 in /opt/venv/lib/python3.10/site-packages (from scikit-optimize) (1.12.0)\n", + "Requirement already satisfied: scikit-learn>=0.20.0 in /opt/venv/lib/python3.10/site-packages (from scikit-optimize) (1.4.0)\n", + "Requirement already satisfied: PyYAML in /opt/venv/lib/python3.10/site-packages (from pyaml>=16.9->scikit-optimize) (6.0.1)\n", + "Requirement already satisfied: threadpoolctl>=2.0.0 in /opt/venv/lib/python3.10/site-packages (from scikit-learn>=0.20.0->scikit-optimize) (3.2.0)\n", + "Note: you may need to restart the kernel to use updated packages.\n" + ] + } + ], + "source": [ + "%pip install -e ..\n", + "# %pip install scikit-optimize" + ] + }, + { + "cell_type": "code", + "execution_count": 45, + "id": "8a7920aa-5e69-4690-be6d-f03308ddf449", + "metadata": {}, + "outputs": [], + "source": [ + "from rl4caribou import Caribou\n", + "from skopt import gp_minimize, gbrt_minimize\n", + "import polars as pl\n", + "import numpy as np\n", + "from plotnine import ggplot, aes, geom_point, geom_ribbon\n" + ] + }, + { + "cell_type": "markdown", + "id": "49794040-34a0-4491-8a3d-12ad3f114068", + "metadata": {}, + "source": [ + "Here is an example of a simple fixed action policy. It will apply a fixed hunting effort (potentially zero) each year to Moose, and another fixed effort to Wolves. " + ] + }, + { + "cell_type": "code", + "execution_count": 30, + "id": "51c9e6d9-9299-4296-b647-cf498b0b92cb", + "metadata": {}, + "outputs": [], + "source": [ + "class fixed_effort:\n", + " def __init__(self, action):\n", + " self.effort = np.array(action, dtype=np.float32)\n", + "\n", + " def predict(self, observation, **kwargs):\n", + " action = self.effort * 2 - 1\n", + " return action, {}\n", + "\n", + "pacifist = fixed_effort([0., 0.])" + ] + }, + { + "cell_type": "code", + "execution_count": 37, + "id": "cdeb4bd8-9620-4c4f-829d-a3a2c0e8dfd3", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "(array([-0.4943695 , -0.48672426, -0.8089408 ], dtype=float32),\n", + " 0.250531405210495,\n", + " False,\n", + " False,\n", + " {})" + ] + }, + "execution_count": 37, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "env = Caribou()\n", + "obs = env.reset()\n", + "action, _ = pacifist.predict(obs)\n", + "env.step(action)" + ] + }, + { + "cell_type": "markdown", + "id": "8a5b4db8-e98f-482e-b2b8-751bee389cc1", + "metadata": {}, + "source": [ + "## Fixed policy evaluation helpers\n", + "\n", + "This function simulates the dynamics under any given manager. Each timestep, the manager gets an observation of the population (Caribou, Moose, Wolves), and decides (\"predicts\") what harvest action to take on wolves and moose to maximize the overall net utility over the full simulation.\n", + "\n", + "A helper utility runs this simulation 10 times and returns the mean and summary statistics. " + ] + }, + { + "cell_type": "code", + "execution_count": 54, + "id": "6fa4681c-fbca-4ade-a8ab-e021cd9d07e5", + "metadata": {}, + "outputs": [], + "source": [ + "def gen_ep_rew(manager, env):\n", + " episode_reward = 0.0\n", + " observation, _ = env.reset()\n", + " for t in range(env.Tmax):\n", + " action, _ = manager.predict(observation)\n", + " observation, reward, terminated, done, info = env.step(action)\n", + " episode_reward += reward\n", + " if terminated or done:\n", + " break\n", + " return episode_reward\n", + "\n", + "def gather_stats(manager, env, N=10):\n", + " results = [gen_ep_rew(manager, env) for _ in range(N)]\n", + " y = np.mean(results)\n", + " sigma = np.std(results)\n", + " ymin = y - sigma\n", + " ymax = y + sigma\n", + " return y, ymin, ymax " + ] + }, + { + "cell_type": "code", + "execution_count": 40, + "id": "f3ddd3b8-6696-4f0d-a9a1-c6d722deb3b1", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "(23.70720968544483, 5.766838293769911, 41.64758107711975)" + ] + }, + "execution_count": 40, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "gen_ep_rew(pacifist, env)\n", + "gather_stats(pacifist, env)" + ] + }, + { + "cell_type": "markdown", + "id": "95cc6d29-7dde-4785-9f64-8562ce093f36", + "metadata": {}, + "source": [ + "## Determine optimal mortality policy\n", + "\n", + "Use Bayesian optimization techniques for nonlinear and stochastic functions from Scikit-Optimize (e.g. Gaussian Process estimation) to estimate the optimal fixed mortality policy for both wolves and moose: (err, maybe this can be done analytically too). Note we define the function to be minimized, `g(x)` as a function of the actions, `x`. Note we report the _negative_ mean reward since the optimizer tries to _minimize_ the value. " + ] + }, + { + "cell_type": "code", + "execution_count": 49, + "id": "d876df99-b2ab-49ab-aaa0-3b545cc7ae4b", + "metadata": {}, + "outputs": [], + "source": [ + "def g(x):\n", + " manager = fixed_effort(x)\n", + " out = gather_stats(manager, env)\n", + " return - out[0]" + ] + }, + { + "cell_type": "code", + "execution_count": 50, + "id": "812edc32-f0f9-4ff4-9792-77acf6962179", + "metadata": { + "scrolled": true + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "CPU times: user 2min 42s, sys: 9min 48s, total: 12min 31s\n", + "Wall time: 1min 40s\n" + ] + }, + { + "data": { + "text/plain": [ + "(-192.28646437703884, [0.17790704682764627, 0.061024282615602])" + ] + }, + "execution_count": 50, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "%%time\n", + "res = gp_minimize(g, [(0.0, 0.3), (0, 0.3)], n_calls = 300)\n", + "res.fun, res.x" + ] + }, + { + "cell_type": "code", + "execution_count": 53, + "id": "4c5c2ec8-f61b-4dae-bc1b-ba70310a694b", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "CPU times: user 3min 41s, sys: 644 ms, total: 3min 42s\n", + "Wall time: 3min 40s\n" + ] + }, + { + "data": { + "text/plain": [ + "(-183.45138428616946, [0.1625976286665279, 0.05916838814404951])" + ] + }, + "execution_count": 53, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "%%time\n", + "res = gbrt_minimize(g, [(0.0, 0.3), (0, 0.3)], n_calls = 300)\n", + "res.fun, res.x" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.12" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/noxfile.py b/noxfile.py new file mode 100644 index 0000000..3ab8264 --- /dev/null +++ b/noxfile.py @@ -0,0 +1,13 @@ +# This code would live in a noxfile.py file located at the root of your project directory +import nox + +# For this to run you will need to have python3.9, python3.10 and python3.11 installed on your computer. Otherwise nox will skip running tests for whatever versions are missing + +@nox.session(python=["3.10", "3.11"]) +def test(session): + + # install + session.install(".[tests]") + + # Run tests + session.run("pytest") diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..5b4f5df --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,11 @@ +[project] +name = "rl4caribou" +version = "1.0.0" + +dependencies = ["gymnasium", + "numpy", + "matplotlib", + "typing"] + +[project.optional-dependencies] +tests = ["pytest", "pytest-cov", "stable_baselines3"] diff --git a/scripts/train.py b/scripts/train.py new file mode 100644 index 0000000..a652f3b --- /dev/null +++ b/scripts/train.py @@ -0,0 +1,11 @@ +#!/opt/venv/bin/python +import argparse +parser = argparse.ArgumentParser() +parser.add_argument("-f", "--file", help="Path config file", type=str) +args = parser.parse_args() + +import rl4caribou + + +from rl4eco.utils import sb3_train +sb3_train(args.file) diff --git a/src/rl4caribou/__init__.py b/src/rl4caribou/__init__.py new file mode 100644 index 0000000..2c51852 --- /dev/null +++ b/src/rl4caribou/__init__.py @@ -0,0 +1,3 @@ +from rl4caribou.envs.caribou import Caribou +from gymnasium.envs.registration import register +register(id="Caribou-v0", entry_point="rl4caribou.envs.caribou:Caribou") diff --git a/src/rl4caribou/envs/caribou.py b/src/rl4caribou/envs/caribou.py new file mode 100644 index 0000000..37cc71f --- /dev/null +++ b/src/rl4caribou/envs/caribou.py @@ -0,0 +1,166 @@ +import numpy as np + + +# pop = elk, caribou, wolves +# Caribou Scenario +def dynamics(pop, effort, harvest_fn, p, timestep=1): + pop = harvest_fn(pop, effort) + X, Y, Z = pop[0], pop[1], pop[2] + + K = p["K"] # - 0.2 * np.sin(2 * np.pi * timestep / 3200) + D = p["D"] + 0.5 * np.sin(2 * np.pi * timestep / 3200) + beta = p["beta"] + 0.2 * np.sin(2 * np.pi * timestep / 3200) + + X += ( + p["r_x"] * X * (1 - (X + p["tau_xy"] * Y) / K) + - (1 - D) * beta * Z * (X**2) / (p["v0"] ** 2 + X**2) + + p["sigma_x"] * X * np.random.normal() + ) + + Y += ( + p["r_y"] * Y * (1 - (Y + p["tau_yx"] * X) / K) + - D * beta * Z * (Y**2) / (p["v0"] ** 2 + Y**2) + + p["sigma_y"] * Y * np.random.normal() + ) + + Z += ( + p["alpha"] + * beta + * Z + * ( + (1 - D) * (X**2) / (p["v0"] ** 2 + X**2) + + D * (Y**2) / (p["v0"] ** 2 + Y**2) + ) + - p["dH"] * Z + + p["sigma_z"] * Z * np.random.normal() + ) + + pop = np.array([X, Y, Z], dtype=np.float32) + pop = np.clip(pop, [0, 0, 0], [np.Inf, np.Inf, np.Inf]) + return pop + + +initial_pop = [0.5, 0.5, 0.2] + +parameters = { + "r_x": np.float32(0.13), + "r_y": np.float32(0.2), + "K": np.float32(1), + "beta": np.float32(0.1), + "v0": np.float32(0.1), + "D": np.float32(0.8), + "tau_yx": np.float32(0.7), + "tau_xy": np.float32(0.2), + "alpha": np.float32(0.4), + "dH": np.float32(0.03), + "sigma_x": np.float32(0.05), + "sigma_y": np.float32(0.05), + "sigma_z": np.float32(0.05), +} + + +def harvest(pop, effort): + q0 = 0.5 # catchability coefficients -- erradication is impossible + q2 = 0.5 + pop[0] = pop[0] * (1 - effort[0] * q0) # pop 0, elk + pop[2] = pop[2] * (1 - effort[1] * q2) # pop 2, wolves + return pop + + +def utility(pop, effort): + benefits = 0.5 * pop[1] # benefit from Caribou + costs = 0.00001 * (effort[0] + effort[1]) # cost to culling + if np.any(pop <= 0.01): + benefits -= 1 + return benefits - costs + + +import gymnasium as gym + + +class Caribou(gym.Env): + """A 3-species ecosystem model with two control actions""" + + def __init__(self, config=None): + config = config or {} + + ## these parameters may be specified in config + self.Tmax = config.get("Tmax", 800) + self.max_episode_steps = self.Tmax + self.threshold = config.get("threshold", np.float32(1e-4)) + self.init_sigma = config.get("init_sigma", np.float32(1e-3)) + self.training = config.get("training", True) + self.initial_pop = config.get("initial_pop", initial_pop) + self.parameters = config.get("parameters", parameters) + self.dynamics = config.get("dynamics", dynamics) + self.harvest = config.get("harvest", harvest) + self.utility = config.get("utility", utility) + self.observe = config.get( + "observe", lambda state: state + ) # default to perfectly observed case + self.bound = 2 * self.parameters["K"] + + self.action_space = gym.spaces.Box( + np.array([-1, -1], dtype=np.float32), + np.array([1, 1], dtype=np.float32), + dtype=np.float32, + ) + self.observation_space = gym.spaces.Box( + np.array([-1, -1, -1], dtype=np.float32), + np.array([1, 1, 1], dtype=np.float32), + dtype=np.float32, + ) + self.reset(seed=config.get("seed", None)) + + def reset(self, *, seed=None, options=None): + self.timestep = 0 + self.initial_pop += np.multiply( + self.initial_pop, np.float32(self.init_sigma * np.random.normal(size=3)) + ) + self.state = self.state_units(self.initial_pop) + info = {} + return self.observe(self.state), info + + def step(self, action): + action = np.clip(action, self.action_space.low, self.action_space.high) + pop = self.population_units() # current state in natural units + effort = (action + 1.0) / 2 + + # harvest and recruitment + reward = self.utility(pop, effort) + nextpop = self.dynamics( + pop, effort, self.harvest, self.parameters, self.timestep + ) + + self.timestep += 1 + terminated = bool(self.timestep > self.Tmax) + + # in training mode only: punish for population collapse + if any(pop <= self.threshold) and self.training: + terminated = True + reward -= 50 / self.timestep + + self.state = self.state_units(nextpop) # transform into [-1, 1] space + observation = self.observe(self.state) # same as self.state + return observation, reward, terminated, False, {} + + def state_units(self, pop): + self.state = 2 * pop / self.bound - 1 + self.state = np.clip( + self.state, + np.repeat(-1, self.state.__len__()), + np.repeat(1, self.state.__len__()), + ) + return np.float32(self.state) + + def population_units(self): + pop = (self.state + 1) * self.bound / 2 + return np.clip( + pop, np.repeat(0, pop.__len__()), np.repeat(np.Inf, pop.__len__()) + ) + + +# verify that the environment is defined correctly +# from stable_baselines3.common.env_checker import check_env +# env = s3a2() +# check_env(env, warn=True) diff --git a/tests/test_caribou.py b/tests/test_caribou.py new file mode 100644 index 0000000..1c1a66b --- /dev/null +++ b/tests/test_caribou.py @@ -0,0 +1,7 @@ +# Confirm environment is correctly defined: +from stable_baselines3.common.env_checker import check_env +from rl4caribou import Caribou + +def test_Caribou(): + check_env(Caribou(), warn=True) +