{ "cells": [ { "cell_type": "markdown", "id": "0", "metadata": {}, "source": [ "# Hydrological modelling - HYDROTEL\n", "\n", "
WARNING\n", " \n", "`xHydro` provides tools to execute HYDROTEL, but will not prepare the model itself. This should be done beforehand.\n", "\n", "
\n", "\n", "
INFO\n", " \n", "The HYDROTEL executable can be acquired from this [GitHub repository](https://github.com/INRS-Modelisation-hydrologique/hydrotel).\n", "\n", "
\n", "\n", "`xHydro` provides a collection of functions designed to facilitate hydrological modelling, focusing on two key models: [HYDROTEL](https://github.com/INRS-Modelisation-hydrologique/hydrotel) and a suite of models emulated by the [Raven Hydrological Framework](https://raven.uwaterloo.ca/). It is important to note that Raven already possesses an extensive Python library, [RavenPy](https://github.com/CSHS-CWRA/RavenPy), which enables users to build, calibrate, and execute models. `xHydro` wraps some of these functions to support multi-model assessments with HYDROTEL, though users seeking advanced functionalities may prefer to use `RavenPy` directly. \n", "\n", "The primary contribution of `xHydro` to hydrological modelling is thus its support for HYDROTEL, a model that previously lacked a dedicated Python library. However, building a HYDROTEL project is best done using PHYSITEL and the HYDROTEL GUI, both of which are proprietary software. Therefore, for the time being, `xHydro` is designed to facilitate the execution and modification of an already established HYDROTEL project, rather than assist in building one from scratch.\n", "\n", "A similar Notebook to this one, but that covers `RavenPy` models, is available [here](hydrological_modelling_raven.ipynb).\n", "\n", "## Basic information" ] }, { "cell_type": "code", "execution_count": 1, "id": "1", "metadata": {}, "outputs": [], "source": [ "from IPython.display import clear_output\n", "import xhydro as xh\n", "import xhydro.modelling as xhm\n", "clear_output(wait=False)" ] }, { "cell_type": "code", "execution_count": 2, "id": "2", "metadata": { "editable": true, "nbsphinx": "hidden", "slideshow": { "slide_type": "" }, "tags": [] }, "outputs": [], "source": [ "import logging\n", "\n", "logger = logging.getLogger()\n", "logger.setLevel(logging.CRITICAL)" ] }, { "cell_type": "markdown", "id": "3", "metadata": {}, "source": [ "The `xHydro` modelling framework is based on a `model_config` dictionary, which is meant to contain all necessary information to execute a given hydrological model. For example, depending on the model, it can store meteorological datasets directly, paths to datasets (netCDF files or other), csv configuration files, parameters, and basically anything that is required to configure and execute an hydrological model.\n", "\n", "The list of required inputs for the dictionary can be obtained one of two ways. The first is to look at the hydrological model's class, such as `xhydro.modelling.Hydrotel`. The second is to use the `xh.modelling.get_hydrological_model_inputs` function to get a list of the required keys for a given model, as well as the documentation." ] }, { "cell_type": "code", "execution_count": 3, "id": "4", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Help on function get_hydrological_model_inputs in module xhydro.modelling.hydrological_modelling:\n", "\n", "get_hydrological_model_inputs(model_name: str, required_only: bool = False) -> tuple[dict, str]\n", " Get the required inputs for a given hydrological model.\n", "\n", " Parameters\n", " ----------\n", " model_name : str\n", " The name of the hydrological model to use.\n", " Currently supported models are [\"HYDROTEL\", \"Blended\", \"GR4JCN\", \"HBVEC\", \"HMETS\", \"HYPR\", \"Mohyse\", \"SACSMA\"].\n", " required_only : bool\n", " If True, only the required inputs will be returned.\n", "\n", " Returns\n", " -------\n", " dict\n", " A dictionary containing the required configuration for the hydrological model.\n", " str\n", " The documentation for the hydrological model.\n", "\n" ] } ], "source": [ "help(xhm.get_hydrological_model_inputs)" ] }, { "cell_type": "code", "execution_count": 4, "id": "5", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "{'model_name': 'HYDROTEL',\n", " 'project_dir': str | os.PathLike,\n", " 'project_file': str,\n", " 'executable': str | os.PathLike,\n", " 'project_config': dict | None,\n", " 'simulation_config': dict | None,\n", " 'output_config': dict | None}" ] }, "execution_count": 4, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# This function can be called to get a list of the keys for a given model, as well as its documentation.\n", "inputs, docs = xhm.get_hydrological_model_inputs(\"Hydrotel\", required_only=False)\n", "inputs" ] }, { "cell_type": "code", "execution_count": 5, "id": "6", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "\n", "Class to handle HYDROTEL simulations.\n", "\n", "Parameters\n", "----------\n", "project_dir : str or Path\n", " Path to the project folder.\n", "project_file : str\n", " Name of the project file (e.g. 'projet.csv').\n", "executable : str or Path\n", " Command to execute HYDROTEL.\n", " On Windows, this should be the path to hydrotel.exe.\n", "project_config : dict, optional\n", " Dictionary of configuration options to overwrite in the project file.\n", "simulation_config : dict, optional\n", " Dictionary of configuration options to overwrite in the simulation file. See the Notes section for more details.\n", "output_config : dict, optional\n", " Dictionary of configuration options to overwrite in the output file (output.csv).\n", "\n", "Notes\n", "-----\n", "The name of the simulation file must match the name of the 'SIMULATION COURANTE' option in the project file.\n", "\n", "This class is designed to handle the execution of HYDROTEL simulations, with the ability to overwrite configuration options,\n", "but it does not handle the creation of the project folder itself. The project folder must be created beforehand.\n", "\n", "For more information on how to configure the project, refer to the documentation of HYDROTEL:\n", "https://github.com/INRS-Modelisation-hydrologique/hydrotel\n", "\n" ] } ], "source": [ "print(docs)" ] }, { "cell_type": "markdown", "id": "7", "metadata": {}, "source": [ "HYDROTEL and Raven vary in terms of required inputs and available functions, but an effort will be made to standardize the outputs as much as possible. Currently, all models include the following three functions:\n", "\n", "- `.run()`: Executes the model, reformats the outputs to be compatible with analysis tools in `xHydro`, and returns the simulated streamflow as a `xarray.Dataset`.\n", " - The streamflow variable will be named `q` and will have units of `m3 s-1`.\n", " - For 1D data (such as hydrometric stations), the corresponding dimension in the dataset will be identified by the `cf_role: timeseries_id` attribute.\n", " \n", "- `.get_inputs()`: Retrieves the meteorological inputs used by the model.\n", "\n", "- `.get_outputs()`: Retrieves the simulated outputs from the model.\n", " - Use `.get_outputs(\"q\")` to obtain the simulated streamflow as a `xarray.Dataset`.\n", "\n", "- `.standardize_outputs()`: Standardizes the outputs to ensure consistency across different models, facilitating comparison and analysis. This function is used by default in the `.run()` method, but can also be called separately if needed.\n", "\n", "## Initializing and running a calibrated model\n", "\n", "A typical HYDROTEL project consists of multiple subfolders and files that describe meteorological inputs, watershed characteristics, and more. An example is given in the cell below. The model primarily relies on three key files:\n", "\n", "- A project file located in the main directory, which may have any given name (e.g., `SLNO.csv`). It contains basic information about the project, including the name of the current simulation (`SIMULATION COURANTE`).\n", "- A `simulation/[simulation_name]/[simulation_name].csv` file that manages all the parameters for the run, including simulation dates, the path to meteorological data, and the physical processes to be used.\n", "- A `simulation/[simulation_name]/output.csv` file that specifies which results to produce, such as which variables and river reaches to output results for.\n", "\n", "Default files are not provided with `xHydro`, but you can find an example of a HYDROTEL project in the `DemoProject` folder of the (HYDROTEL repository)[https://github.com/INRS-Modelisation-hydrologique/hydrotel]. Configuration options for `project_config`, `simulation_config`, or `output_config` can nonetheless be specified when initializing the HYDROTEL model, or through the `.update_config()` function later. This will update the corresponding CSV files accordingly. " ] }, { "cell_type": "code", "execution_count": 6, "id": "8", "metadata": {}, "outputs": [], "source": [ "# For this example, we will use the DemoProject prepared for the HYDROTEL model.\n", "import os\n", "from dotenv import load_dotenv\n", "from pathlib import Path\n", "import tempfile\n", "notebook_folder = Path(tempfile.TemporaryDirectory().name)\n", "\n", "load_dotenv(dotenv_path=Path.cwd().parents[1] / \"tests\" / \".env\")\n", "hydrotel_demo = os.getenv(\"HYDROTEL_DEMO\", None)\n", "hydrotel_executable = os.getenv(\"HYDROTEL_EXECUTABLE\", None)\n", "\n", "# Copy the demo project to a temporary folder, so that we can run the model without modifying the original files.\n", "import shutil\n", "shutil.copytree(hydrotel_demo, notebook_folder / \"hydrotel_demo\")\n", "# Remove the input and output files\n", "for f in (notebook_folder / \"hydrotel_demo\" / \"meteo\").glob(\"*\"):\n", " f.unlink()\n", "for f in (notebook_folder / \"hydrotel_demo\" / \"simulation\" / \"simulation\" / \"resultat\").glob(\"*\"):\n", " f.unlink()" ] }, { "cell_type": "code", "execution_count": 7, "id": "9", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "DELISLE.csv\n", "meteo\n", "physitel\n", " proprietehydrolique.sol\n", " uhrh.prj\n", " rivieres.dbf\n", " noeuds.nds\n", " point.rdx\n", " uhrh.csv\n", " lacs.shx\n", " rivieres.shp\n", " pente.tif\n", " type_sol.cla\n", " troncon.trl\n", " occupation_sol.tif\n", " uhrh.shx\n", " lacs.prj\n", " uhrh.dbf\n", " occupation_sol.cla\n", " rivieres.prj\n", " uhrh.shp\n", " uhrh.tif\n", " rivieres.shx\n", " orientation.tif\n", " lacs.shp\n", " occupation_sol.csv\n", " lacs.dbf\n", " altitude.tif\n", " type_sol.tif\n", "simulation\n", " simulation\n", " thorsen.csv\n", " bv3c.csv\n", " degre_jour_modifie.csv\n", " thornthwaite.csv\n", " degre-jour-glacier.csv\n", " milieux_humides_isoles.csv\n", " rankinen.csv\n", " cequeau.csv\n", " etp-mc-guiness.csv\n", " stats.txt\n", " hydro_quebec.csv\n", " degre-jour-bande.csv\n", " penman.csv\n", " rayonnement_net.csv\n", " corrections.csv\n", " grillemeteo.csv\n", " penman_monteith.csv\n", " linacre.csv\n", " simulation.gsb\n", " simulation.csv\n", " moyenne_3_stations.csv\n", " output.csv\n", " troncons_stations.csv\n", " submodels-versions.txt\n", " milieux_humides_riverains.csv\n", " thiessen.csv\n", " grilleprevision.csv\n", " onde_cinematique.csv\n", " onde_cinematique_modifiee.csv\n", " priestlay_taylor.csv\n", " resultat\n", " simulation-global\n", " corrections.csv\n", " simulation-global.gsb\n", " troncons_stations.csv\n", " parametres_sous_modeles.csv\n", " milieux_humides_riverains.csv\n", " stats.txt\n", " submodels-versions.txt\n", " output.csv\n", " simulation-global.csv\n", " milieux_humides_isoles.csv\n", "neige\n", " station.stn\n", " NEIGE01.nei\n", " NEIGE02.nei\n", " NEIGE03.nei\n", " station.p3s\n", "etats\n", " ruisselement_surface_surf_2020010100.csv\n", " bilan_vertical_2020070100.csv\n", " acheminement_riviere_MH_2020010100.csv\n", " ruisselement_surface_2020010100.csv\n", " fonte_neige_2020070100.csv\n", " ruisselement_surface_hypo_2020070100.csv\n", " ruisselement_surface_base_2020010100.csv\n", " acheminement_riviere_2020010100.csv\n", " ruisselement_surface_2020070100.csv\n", " fonte_neige_2020010100.csv\n", " ruisselement_surface_hypo_2020010100.csv\n", " acheminement_riviere_2020070100.csv\n", " ruisselement_surface_base_2020070100.csv\n", " bilan_vertical_2020010100.csv\n", " ruisselement_surface_surf_2020070100.csv\n", " acheminement_riviere_MH_2020070100.csv\n", "hydro\n", " 02MC036.hyd\n", " station.sth\n", "hgm\n", " hydrogramme.hgm\n", "physio\n", " shreve.csv\n", " troncon_width_depth.csv\n", " wet_pixel_info.csv\n", " pro_rac.def\n", " ind_fol.def\n", " strahler.csv\n" ] } ], "source": [ "from pathlib import Path\n", "\n", "def print_file_structure(directory, indent=0):\n", " path = Path(directory)\n", " for item in path.iterdir():\n", " print(\" \" * indent + item.name)\n", " # If the item is a directory, recurse into it\n", " if item.is_dir():\n", " print_file_structure(item, indent + 2)\n", "\n", "\n", "# Example usage\n", "print_file_structure(notebook_folder / \"hydrotel_demo\")" ] }, { "cell_type": "code", "execution_count": 8, "id": "10", "metadata": {}, "outputs": [], "source": [ "model_config = {\n", " \"model_name\": \"Hydrotel\",\n", " \"project_dir\": notebook_folder / \"hydrotel_demo\",\n", " \"project_file\": \"DELISLE.csv\",\n", " \"simulation_config\": {\n", " \"DATE DEBUT\": \"1981-01-01\",\n", " \"DATE FIN\": \"1981-12-31\",\n", " \"FICHIER STATIONS METEO\": \"meteo/ERA5.nc\",\n", " \"PAS DE TEMPS\": 24,\n", " },\n", " \"output_config\": {\"TRONCONS\": \"tous\", \"DEBITS_AVAL\": 1, \"OUTPUT_NETCDF\": 1},\n", " \"executable\": hydrotel_executable,\n", "}" ] }, { "cell_type": "markdown", "id": "11", "metadata": {}, "source": [ "With `model_config` on hand, an instance of the hydrological model can be initialized using `xhydro.modelling.hydrological_model` or the `xhydro.modelling.Hydrotel` class directly." ] }, { "cell_type": "code", "execution_count": 9, "id": "12", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Simulation directory, taken from the project file: '/tmp/tmpbn030vdz/hydrotel_demo/simulation/simulation'\n", "\n", "Project configuration: '{'PROJET HYDROTEL VERSION': '4.3.1.0000', 'FICHIER ALTITUDE': 'physitel/altitude.tif', 'FICHIER PENTE': 'physitel/pente.tif', 'FICHIER ORIENTATION': 'physitel/orientation.tif', 'FICHIER ZONE': 'physitel/uhrh.tif', 'FICHIER NOEUD': 'physitel/noeuds.nds', 'FICHIER TRONCON': 'physitel/troncon.trl', 'FICHIER PIXELS': 'physitel/point.rdx', 'FICHIER MILIEUX HUMIDES PROFONDEUR TRONCONS': 'physio/troncon_width_depth.csv', 'SIMULATION COURANTE': 'simulation'}'\n", "\n", "Simulation configuration: '{'SIMULATION HYDROTEL VERSION': '4.3.1.0000', 'FICHIER OCCUPATION SOL': 'physitel/occupation_sol.cla', 'FICHIER PROPRIETE HYDROLIQUE': 'physitel/proprietehydrolique.sol', 'FICHIER TYPE SOL COUCHE1': 'physitel/type_sol.cla', 'FICHIER TYPE SOL COUCHE2': 'physitel/type_sol.cla', 'FICHIER TYPE SOL COUCHE3': 'physitel/type_sol.cla', 'COEFFICIENT ADDITIF PROPRIETE HYDROLIQUE': '0', 'FICHIER INDICE FOLIERE': 'physio/ind_fol.def', 'FICHIER PROFONDEUR RACINAIRE': 'physio/pro_rac.def', 'FICHIER GRILLE METEO': '', 'FICHIER STATIONS METEO': 'meteo/ERA5.nc', 'FICHIER STATIONS HYDRO': 'hydro/station.sth', 'PREVISION METEO': '0', 'FICHIER GRILLE PREVISION': '', 'DATE DEBUT PREVISION': '1973-06-01 00:00', 'DATE DEBUT': '1981-01-01 00:00', 'DATE FIN': '1981-12-31 00:00', 'PAS DE TEMPS': 24, 'TRONCON EXUTOIRE': '1', 'TRONCONS DECONNECTER': 'off', 'NOM FICHIER CORRECTIONS': '1', 'LECTURE ETAT FONTE NEIGE': 'etats/fonte_neige_2020010100.csv', 'LECTURE ETAT TEMPERATURE DU SOL': '', 'LECTURE ETAT BILAN VERTICAL': 'etats/bilan_vertical_2020010100.csv', 'LECTURE ETAT RUISSELEMENT SURFACE': 'etats/ruisselement_surface_2020010100.csv', 'LECTURE ETAT ACHEMINEMENT RIVIERE': 'etats/acheminement_riviere_2020010100.csv', 'ECRITURE ETAT FONTE NEIGE': '2020-07-01 00:00', 'ECRITURE ETAT TEMPERATURE DU SOL': '', 'ECRITURE ETAT BILAN VERTICAL': '2020-07-01 00:00', 'ECRITURE ETAT RUISSELEMENT SURFACE': '2020-07-01 00:00', 'ECRITURE ETAT ACHEMINEMENT RIVIERE': '2020-07-01 00:00', 'REPERTOIRE ECRITURE ETAT FONTE NEIGE': 'etats', 'REPERTOIRE ECRITURE ETAT TEMPERATURE DU SOL': '', 'REPERTOIRE ECRITURE ETAT BILAN VERTICAL': 'etats', 'REPERTOIRE ECRITURE ETAT RUISSELEMENT SURFACE': 'etats', 'REPERTOIRE ECRITURE ETAT ACHEMINEMENT RIVIERE': 'etats', 'INTERPOLATION DONNEES': 'THIESSEN', 'FONTE DE NEIGE': 'DEGRE JOUR MODIFIE', 'FONTE GLACIER': '', 'TEMPERATURE DU SOL': '', 'EVAPOTRANSPIRATION': 'HYDRO-QUEBEC', 'BILAN VERTICAL': 'BV3C', 'RUISSELEMENT': 'ONDE CINEMATIQUE', 'ACHEMINEMENT RIVIERE': 'ONDE CINEMATIQUE MODIFIEE', 'MILIEUX HUMIDES ISOLES': '1', 'MILIEUX HUMIDES RIVERAINS': '1', 'FICHIER DE PARAMETRE GLOBAL': '0', 'LECTURE INTERPOLATION DONNEES': 'lecture_interpolation.csv', 'THIESSEN': 'thiessen.csv', 'MOYENNE 3 STATIONS': 'moyenne_3_stations.csv', 'LECTURE FONTE NEIGE': 'lecture_fonte_neige.csv', 'DEGRE JOUR MODIFIE': 'degre_jour_modifie.csv', 'LECTURE TEMPERATURE DU SOL': 'lecture_tempsol.csv', 'RANKINEN': 'rankinen.csv', 'THORSEN': 'thorsen.csv', 'LECTURE EVAPOTRANSPIRATION': 'lecture_etp.csv', 'HYDRO-QUEBEC': 'hydro_quebec.csv', 'THORNTHWAITE': 'thornthwaite.csv', 'LINACRE': 'linacre.csv', 'PENMAN': 'penman.csv', 'PRIESTLAY-TAYLOR': 'priestlay_taylor.csv', 'PENMAN-MONTEITH': 'penman_monteith.csv', 'LECTURE BILAN VERTICAL': 'lecture_bilan_vertical.csv', 'BV3C': 'bv3c.csv', 'CEQUEAU': 'cequeau.csv', 'LECTURE RUISSELEMENT SURFACE': 'lecture_ruisselement.csv', 'ONDE CINEMATIQUE': 'onde_cinematique.csv', 'LECTURE ACHEMINEMENT RIVIERE': 'lecture_acheminement.csv', 'ONDE CINEMATIQUE MODIFIEE': 'onde_cinematique_modifiee.csv', 'FICHIER MILIEUX HUMIDES ISOLES': 'milieux_humides_isoles.csv', 'FICHIER MILIEUX HUMIDES RIVERAINS': 'milieux_humides_riverains.csv'}'\n", "\n", "Output configuration: '{'TRONCONS': 'tous', 'TRONCONS_MOYENNES_PONDEREES': '1', 'TMIN': '1', 'TMAX': '1', 'TMIN_JOUR': '1', 'TMAX_JOUR': '1', 'PLUIE': '1', 'NEIGE': '1', 'APPORT': '1', 'COUVERT_NIVAL': '1', 'HAUTEUR_NEIGE': '1', 'ALBEDO_NEIGE': '1', 'APPORT_GLACIER': '1', 'EAU_GLACIER': '1', 'PROFONDEUR_GEL': '1', 'ETP': '1', 'ETR1': '1', 'ETR2': '1', 'ETR3': '1', 'ETR_TOTAL': '1', 'PRODUCTION_BASE': '1', 'PRODUCTION_HYPO': '1', 'PRODUCTION_SURF': '1', 'Q12': '1', 'Q23': '1', 'Q23_SOMME_ANNUELLE': '1', 'QRECHARGE': '1', 'THETA1': '1', 'THETA2': '1', 'THETA3': '1', 'APPORT_LATERAL': '1', 'APPORT_LATERAL_UHRH': '1', 'ECOULEMENT_SURF': '1', 'ECOULEMENT_HYPO': '1', 'ECOULEMENT_BASE': '1', 'DEBITS_AMONT': '1', 'DEBITS_AVAL': 1, 'DEBITS_AVAL_MOY7J_MIN': '1', 'HAUTEUR_AVAL': '1', 'OUTPUT_NETCDF': 1}'\n" ] } ], "source": [ "hm = xhm.hydrological_model(model_config)\n", "\n", "print(f\"Simulation directory, taken from the project file: '{hm.simulation_dir}'\\n\")\n", "print(f\"Project configuration: '{hm.project_config}'\\n\")\n", "print(f\"Simulation configuration: '{hm.simulation_config}'\\n\")\n", "print(f\"Output configuration: '{hm.output_config}'\")" ] }, { "cell_type": "markdown", "id": "13", "metadata": {}, "source": [ "As we can see, the DemoProject outputs every available variable for all river reaches. This is because the `output_config` key only overwrites the specified keys, but leaves the rest of the configuration unchanged. Therefore, if we want to only keep the few variables that are relevant for our analysis, we can use the `update_config` method once the model has been initialized." ] }, { "cell_type": "code", "execution_count": 10, "id": "14", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Updated output configuration: '{'TRONCONS': 'tous', 'TRONCONS_MOYENNES_PONDEREES': '0', 'TMIN': '0', 'TMAX': '0', 'TMIN_JOUR': '0', 'TMAX_JOUR': '0', 'PLUIE': '0', 'NEIGE': '0', 'APPORT': '0', 'COUVERT_NIVAL': '0', 'HAUTEUR_NEIGE': '0', 'ALBEDO_NEIGE': '0', 'APPORT_GLACIER': '0', 'EAU_GLACIER': '0', 'PROFONDEUR_GEL': '0', 'ETP': '0', 'ETR1': '0', 'ETR2': '0', 'ETR3': '0', 'ETR_TOTAL': '0', 'PRODUCTION_BASE': '0', 'PRODUCTION_HYPO': '0', 'PRODUCTION_SURF': '0', 'Q12': '0', 'Q23': '0', 'Q23_SOMME_ANNUELLE': '0', 'QRECHARGE': '0', 'THETA1': '0', 'THETA2': '0', 'THETA3': '0', 'APPORT_LATERAL': '0', 'APPORT_LATERAL_UHRH': '0', 'ECOULEMENT_SURF': '0', 'ECOULEMENT_HYPO': '0', 'ECOULEMENT_BASE': '0', 'DEBITS_AMONT': '0', 'DEBITS_AVAL': '1', 'DEBITS_AVAL_MOY7J_MIN': '0', 'HAUTEUR_AVAL': '0', 'OUTPUT_NETCDF': '1'}'\n" ] } ], "source": [ "output = hm.output_config.copy()\n", "output = {k: \"0\" if str(output[k]) == \"1\" else output[k] for k in output.keys()}\n", "output[\"DEBITS_AVAL\"] = \"1\"\n", "output[\"OUTPUT_NETCDF\"] = \"1\"\n", "hm.update_config(output_config=output)\n", "print(f\"Updated output configuration: '{hm.output_config}'\")" ] }, { "cell_type": "markdown", "id": "15", "metadata": {}, "source": [ "### Formatting meteorological data\n", "\n", "The acquisition of raw meteorological data is covered in the [GIS notebook](gis.ipynb) and [Use Case Example](use_case.ipynb) notebooks. Therefore, this notebook will use a test dataset." ] }, { "cell_type": "code", "execution_count": 11, "id": "16", "metadata": {}, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "
<xarray.Dataset> Size: 69kB\n",
       "Dimensions:      (time: 366, lat: 3, lon: 5)\n",
       "Coordinates:\n",
       "  * time         (time) datetime64[ns] 3kB 1981-01-01 1981-01-02 ... 1982-01-01\n",
       "  * lat          (lat) float64 24B 48.5 48.75 49.0\n",
       "  * lon          (lon) float64 40B -65.5 -65.25 -65.0 -64.75 -64.5\n",
       "    z            (lat, lon) float32 60B ...\n",
       "    spatial_agg  <U7 28B ...\n",
       "    timestep     <U1 4B ...\n",
       "    HYBAS_ID     int64 8B ...\n",
       "    source       <U29 116B ...\n",
       "Data variables:\n",
       "    tasmax       (time, lat, lon) float32 22kB ...\n",
       "    tasmin       (time, lat, lon) float32 22kB ...\n",
       "    pr           (time, lat, lon) float32 22kB ...\n",
       "Attributes: (12/30)\n",
       "    GRIB_NV:                                  0\n",
       "    GRIB_Nx:                                  1440\n",
       "    GRIB_Ny:                                  721\n",
       "    GRIB_cfName:                              unknown\n",
       "    GRIB_cfVarName:                           t2m\n",
       "    GRIB_dataType:                            an\n",
       "    ...                                       ...\n",
       "    GRIB_totalNumber:                         0\n",
       "    GRIB_typeOfLevel:                         surface\n",
       "    GRIB_units:                               K\n",
       "    long_name:                                2 metre temperature\n",
       "    standard_name:                            unknown\n",
       "    units:                                    K
" ], "text/plain": [ " Size: 69kB\n", "Dimensions: (time: 366, lat: 3, lon: 5)\n", "Coordinates:\n", " * time (time) datetime64[ns] 3kB 1981-01-01 1981-01-02 ... 1982-01-01\n", " * lat (lat) float64 24B 48.5 48.75 49.0\n", " * lon (lon) float64 40B -65.5 -65.25 -65.0 -64.75 -64.5\n", " z (lat, lon) float32 60B ...\n", " spatial_agg tuple[xr.Dataset, dict]\n", " Reformat CF-compliant meteorological data for use in hydrological models. See the \"Notes\" section for important details.\n", "\n", " Parameters\n", " ----------\n", " ds : xr.Dataset\n", " A dataset containing the meteorological data. See the \"Notes\" section for more information on the expected format.\n", " model : str\n", " The name of the hydrological model to use.\n", " Currently supported models are:\n", " - \"HYDROTEL\", \"Raven\" (which is an alias for all RavenPy models), \"Blended\", \"GR4JCN\", \"HBVEC\", \"HMETS\", \"HYPR\", \"Mohyse\", \"SACSMA\".\n", " convert_calendar_missing : float | str | dict | bool, optional\n", " The value to use for missing values when converting the calendar to \"standard\".\n", " If the value is a float, it will be used as the fill value for all variables.\n", " If the value is a string \"interpolate\", the new dates will be linearly interpolated over time.\n", " A dictionary can be used to specify a different fill value for each variable.\n", " Keys should be the names of the variables as they appear in the first entry in the \"variable_name\" lists of the \"Notes\" section.\n", " If True, temperatures will be interpolated and precipitation will be filled with 0.\n", " If False, the calendar will not be converted. Only possible for \"Raven\" models.\n", " save_as : str, optional\n", " Where to save the reformatted data. If None, the data will not be saved.\n", " This can be useful when multiple files are needed for a single model run (e.g. HYDROTEL needs a configuration file).\n", " \\*\\*kwargs : dict\n", " Additional keyword arguments to pass to the save function.\n", "\n", " Returns\n", " -------\n", " xr.Dataset\n", " The reformatted dataset.\n", " dict\n", " For HYDROTEL, a dictionary containing the configuration for the meteorological data.\n", " If `save_as` is provided, the configuration will have been saved to a file with the same name as `save_as`, but with a \".nc.config\" extension.\n", " For Raven, a dictionary containing the 'data_type' and 'alt_names_meteo' keys required for the 'model_config' argument.\n", "\n", " Notes\n", " -----\n", " The input dataset should ideally be CF-compliant and follow CMIP6's Controlled Vocabulary, but this function will attempt to detect the\n", " variables based on the standard_name attribute, the cell_methods attribute, or the variable name.\n", " More information on those attributes can be found here: https://wcrp-cmip.org/cmip-model-and-experiment-documentation/, and specifically\n", " the 'CMIP6 MIP table' link provided in the 'Search for variables' section.\n", "\n", " Specifically:\n", "\n", " - If using 1D time series, the station dimension should have an attribute `cf_role` set to \"timeseries_id\".\n", " - Units don't need to be canonical, but they should be convertible to the expected units and be understood by `xclim`.\n", " - Elevation represents the altitude of the meteorological data / model grid cell, not the altitude of the ground.\n", " - Snowfall units should be in water equivalent of precipitation (e.g. mm/day or kg/m²/s), NOT height (e.g. cm of fresh snow on the ground).\n", " - The function will try to detect the variables based on the attributes and the variable name. The following attempts will be made:\n", " - Longitude:\n", " - standard_name: \"longitude\"\n", " - variable name: \"longitude\", \"lon\"\n", " - Latitude:\n", " - standard_name: \"latitude\"\n", " - variable name: \"latitude\", \"lat\"\n", " - Elevation:\n", " - standard_name: \"surface_altitude\"\n", " - variable name: \"elevation\", \"orog\", \"z\", \"altitude\", \"height\"\n", " - Precipitation:\n", " - standard_name: \"*precipitation*\" (e.g. \"lwe_thickness_of_precipitation_amount\")\n", " - variable name: \"pr\", \"precip\", \"precipitation\"\n", " - Rainfall:\n", " - standard_name: \"*rainfall*\" (e.g. \"rainfall_flux\", \"rainfall_amount\")\n", " - variable name: \"prra\", \"prlp\", \"rainfall\", \"rain\", \"precipitation_rain\"\n", " - Snowfall:\n", " - standard_name: \"*snowfall*\" (e.g. \"snowfall_flux\", \"snowfall_amount\")\n", " - variable name: \"prsn\", \"snowfall\", \"precipitation_snow\"\n", " - Maximum temperature:\n", " - standard_name: \"air_temperature\"\n", " - cell_methods: \"time: maximum\"\n", " - variable name: \"tasmax\", \"tmax\", \"t2m_max\", \"temperature_max\"\n", " - Minimum temperature:\n", " - standard_name: \"air_temperature\"\n", " - cell_methods: \"time: minimum\"\n", " - variable name: \"tasmin\", \"tmin\", \"t2m_min\", \"temperature_min\"\n", " - Mean temperature:\n", " - standard_name: \"air_temperature\"\n", " - cell_methods: \"time: mean\"\n", " - variable name: \"tas\", \"tmean\", \"t2m\", \"temperature_mean\"\n", "\n", " HYDROTEL requires the following variables: [\"longitude\", \"latitude\", \"elevation\", \"time\", \"tasmax\", \"tasmin\", \"pr\"].\n", " Raven requires the following variables: [\"longitude\", \"latitude\", \"elevation\", \"time\", \"tasmax/tasmin\" or \"tas\", \"pr\" or \"prlp/prsn\"].\n", "\n" ] } ], "source": [ "help(xh.modelling.format_input)" ] }, { "cell_type": "code", "execution_count": 13, "id": "19", "metadata": {}, "outputs": [ { "name": "stderr", "output_type": "stream", "text": [ "/exec/rondeau/.conda/envs/xhydro-20260311/lib/python3.14/site-packages/clisops/utils/dataset_utils.py:1772: UserWarning: For coordinate variable 'longitude' no bounds can be identified.\n" ] } ], "source": [ "# You can also use the 'save_as' argument to save the new file(s) in your project folder.\n", "ds_reformatted, config = xh.modelling.format_input(\n", " ds,\n", " \"Hydrotel\",\n", " save_as=notebook_folder / \"hydrotel_demo\" / \"meteo\" / \"ERA5.nc\",\n", ")" ] }, { "cell_type": "markdown", "id": "20", "metadata": {}, "source": [ "HYDROTEL requires a configuration file to accompany the meteorological file. This configuration file must have the same name as the corresponding NetCDF file, but with a `.nc.config` extension. If the `save_as` option is used, this configuration file will also be saved along with the meteorological data.\n", "\n", "Note that a third file, with a `.pth` extension, may also be provided. This file is used to specify the weight to apply to each station in the meteorological data in relation to each computational unit (RHHU, or \"Relatively Homogeneous Hydrological Unit\"). This file is optional, and if it is not provided, the model will compute it automatically during initialization. `xHydro` does not currently provide a function to create this file, but this might be added in the future." ] }, { "cell_type": "code", "execution_count": 14, "id": "21", "metadata": {}, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "
<xarray.Dataset> Size: 38kB\n",
       "Dimensions:      (time: 366, station_id: 8)\n",
       "Coordinates:\n",
       "  * time         (time) int64 3kB 5785920 5787360 5788800 ... 6310080 6311520\n",
       "  * station_id   (station_id) int64 64B 0 1 2 3 4 5 6 7\n",
       "    elevation    (station_id) float32 32B 100.0 100.0 100.0 ... 100.0 100.0\n",
       "    latitude     (station_id) float64 64B 48.5 48.5 48.75 ... 48.75 48.75 49.0\n",
       "    longitude    (station_id) float64 64B -65.25 -65.0 -65.5 ... -64.5 -65.5\n",
       "    spatial_agg  <U7 28B 'polygon'\n",
       "    timestep     <U1 4B 'D'\n",
       "    HYBAS_ID     int64 8B 7120035110\n",
       "    source       <U29 116B 'era5_reanalysis_single_levels'\n",
       "Data variables:\n",
       "    tasmax       (time, station_id) float32 12kB -9.085 -8.085 ... -2.062 -4.993\n",
       "    tasmin       (time, station_id) float32 12kB -15.94 -14.57 ... -13.86 -18.4\n",
       "    pr           (time, station_id) float32 12kB 0.1025 0.1063 ... 0.5474 0.9813\n",
       "Attributes: (12/30)\n",
       "    GRIB_NV:                                  0\n",
       "    GRIB_Nx:                                  1440\n",
       "    GRIB_Ny:                                  721\n",
       "    GRIB_cfName:                              unknown\n",
       "    GRIB_cfVarName:                           t2m\n",
       "    GRIB_dataType:                            an\n",
       "    ...                                       ...\n",
       "    GRIB_totalNumber:                         0\n",
       "    GRIB_typeOfLevel:                         surface\n",
       "    GRIB_units:                               K\n",
       "    long_name:                                2 metre temperature\n",
       "    standard_name:                            unknown\n",
       "    units:                                    K
" ], "text/plain": [ " Size: 38kB\n", "Dimensions: (time: 366, station_id: 8)\n", "Coordinates:\n", " * time (time) int64 3kB 5785920 5787360 5788800 ... 6310080 6311520\n", " * station_id (station_id) int64 64B 0 1 2 3 4 5 6 7\n", " elevation (station_id) float32 32B 100.0 100.0 100.0 ... 100.0 100.0\n", " latitude (station_id) float64 64B 48.5 48.5 48.75 ... 48.75 48.75 49.0\n", " longitude (station_id) float64 64B -65.25 -65.0 -65.5 ... -64.5 -65.5\n", " spatial_agg str | xr.Dataset method of xhydro.modelling._hydrotel.Hydrotel instance\n", " Run the simulation.\n", "\n", " Parameters\n", " ----------\n", " run_options : list[str] | None\n", " Additional options to pass to the HYDROTEL executable.\n", " Common arguments include:\n", " - `-t NUM`: Run the simulation using a given number of threads (default is 1).\n", " - `-c`: Skip the validation of the input files.\n", " - `-s`: Skip the interpolation of missing values in the input files. Only use this if you are sure that the input files are complete.\n", " Call the executable without arguments to see the full list of available options.\n", " dry_run : bool\n", " If True, returns the command to run the simulation without actually running it.\n", " overwrite : bool\n", " If True, overwrite the output files if they already exist. Default is False.\n", " standardize : bool\n", " If True, standardize the output files to ensure they are in a consistent format. Default is True.\n", " return_streamflow : bool\n", " If True, return the simulated streamflow. Default is True.\n", "\n", " Returns\n", " -------\n", " str\n", " The command to run the simulation, if 'dry_run' is True.\n", " xr.Dataset\n", " The streamflow file, if 'dry_run' is False.\n", "\n" ] } ], "source": [ "# HYDROTEL has a few specific options\n", "help(hm.run)" ] }, { "cell_type": "code", "execution_count": 19, "id": "28", "metadata": {}, "outputs": [], "source": [ "ds_out = hm.run()\n", "clear_output(wait=False)" ] }, { "cell_type": "code", "execution_count": 20, "id": "29", "metadata": {}, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "
<xarray.Dataset> Size: 303kB\n",
       "Dimensions:        (time: 364, subbasin_id: 196)\n",
       "Coordinates:\n",
       "  * time           (time) datetime64[ns] 3kB 1981-01-01 ... 1981-12-30\n",
       "  * subbasin_id    (subbasin_id) <U3 2kB '1' '2' '3' '4' ... '194' '195' '196'\n",
       "    dowsub_id      (subbasin_id) <U3 2kB ...\n",
       "    station_id     (subbasin_id) <U7 5kB ...\n",
       "    lon            (subbasin_id) float64 2kB ...\n",
       "    lat            (subbasin_id) float64 2kB ...\n",
       "    drainage_area  (subbasin_id) float64 2kB ...\n",
       "Data variables:\n",
       "    q              (time, subbasin_id) float32 285kB ...\n",
       "Attributes:\n",
       "    description:              Variable de sortie simulation Hydrotel\n",
       "    creation_time:            01-04-2026 12:59:03\n",
       "    HYDROTEL_version:         4.3.6.0000\n",
       "    HYDROTEL_config_version:  4.3.1.0000
" ], "text/plain": [ " Size: 303kB\n", "Dimensions: (time: 364, subbasin_id: 196)\n", "Coordinates:\n", " * time (time) datetime64[ns] 3kB 1981-01-01 ... 1981-12-30\n", " * subbasin_id (subbasin_id) ]" ] }, "execution_count": 21, "metadata": {}, "output_type": "execute_result" }, { "data": { "image/png": "iVBORw0KGgoAAAANSUhEUgAAAjMAAAHFCAYAAAAHcXhbAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjEwLjgsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvwVt1zgAAAAlwSFlzAAAPYQAAD2EBqD+naQAAnilJREFUeJztnQeYE1XXxw9bgQUWlt57b6IggiKggmIXrCCC3Q8bovCC+io2UGxYXnsBVBQbKlYQBVQU6b0ovdeFXdrWfM+5yZ3cTCZ9Umby/z1P2GQSkslk7p1zz/mfc8o4HA4HAQAAAABYlJR47wAAAAAAQCTAmAEAAACApYExAwAAAABLA2MGAAAAAJYGxgwAAAAALA2MGQAAAABYGhgzAAAAALA0MGYAAAAAYGlgzAAAAADA0sCYsTlz5syhMmXK0Oeffx7wtUOHDqUKFSpQrGnUqJH47Gh+f/4bCN4H3pdYsnr1aho2bBh169aNsrKygt7XcBg7dqx4f6vC+37XXXfF9JwL5fyJBRMnTqT+/ftT48aNxX716tUr6p+5a9cuce4sW7Ys7PdYs2aNeI8tW7YkxLiz0zkBnKS5/gIQN6ZPn06VKlWKynufeuqp9Oeff1KbNm0oEVm0aBF99dVX1KlTJzr33HNpxowZ8d6lpCCa51w0eeONN4TRe84558TsXGFj5rHHHhMX+1NOOSVsY4bfg40vveHy3//+l+69916KN1Y9J4ATGDMg7vCFPFrw5HTGGWdQojJ48GAaMmSIuM/eMxgz1j/nogkbBSkpTod6u3btyA40bdqUEgGrnhPACcJMCcj+/fvptttuo/r161NmZiZVr16dzjzzTPr5558DukR55WPkej558iSNGDGCatWqReXKlaOePXvS0qVLfYY+2EvAK0D+bHbtHz9+3OM1//vf/+jss8+mGjVqiNe1b9+eJkyYQEVFRR6v48+4+OKLxev4u9SpU4cuuugi2rFjh8/vIt24H3/8MT300EPi/7BRct5559H69etDOpa+XMKTJk2ili1bin1q3bo1TZkyheKBvDCZzXfffSdW0fz9OCTx3HPPGb6Oz4sxY8aI12RkZFDdunXpzjvvpMOHD2uvGTlyJGVnZ1NJSYm27e677xbH9dlnn9W2HTx4UHyfV155RTwuLS2lJ598UhxnPucqV65MHTp0oJdeeilgiMFfSOzNN9+kFi1aiO/GHrdPPvkk5ONjNH7WrVtHF1xwAZUvX56qVatGd9xxB+Xn51MiEY3z5bPPPqOuXbuK35i/e5MmTeimm24Sz/G46dKli7h/4403it+Eb/z7SM/itddeK44n/8b897rrrqOtW7d6jLWrrrpK3O/du7f2Hrzd1zkQzHnJ8P/j+eXHH38UXljeh1atWtF7772XNOcEcALPTIKu1pcsWUJPPfWUmLR5APNjvliEy4MPPigG+zvvvENHjhwRkxEbPWxs8OQlYWPkwgsvpNtvv51Gjx5N8+fPFxcknpxUr8HGjRtp4MCB2mSzfPlysb88+OVEcuzYMerTp494DRs/NWvWpD179tCvv/4a1ITA+8xGHO9zXl4e/ec//6FLLrmE1q5dS6mpqWEfC55EeWK+7LLL6Pnnn9eOR0FBQVAXC75I8y0QPGFHsp/hMnv2bPHdWIfDF3o2QtjQ3Lt3r8frHA4HXX755eL1fOHo0aMHrVixgh599FERmuMbGwxsRLIx9Pfff4v3ZNiw5gvHrFmzhLEjP5ffk1/P8GfycX344YeF4cvnFp8f+gtSKHzzzTfi/Hn88ceFEf3aa6+Ji2daWhpdeeWVYb8vHxs28NPT08V78rn60UcfBa3R4e+tGnv+4H1NFPg3vuaaa8SNf6uyZcuKsf7LL7+I53nOeP/998V44d+RFyJMvXr1xF/WwLCxygZNTk4O7d69m15//XVhALEXiQ0A/j/jxo0T45nnAX5Pfx6ZYM9LCc89999/v5iv+Hfj+eLmm2+mZs2aifMuXJL1nLAsDpBwVKhQwTF8+HC/r2nYsKFjyJAhXtt79uwpbpJff/3VwT/zqaee6igtLdW2b9myxZGenu645ZZbtG38fvzal156yeM9n3rqKbH9999/N9yXkpISR1FRkWPKlCmO1NRUx6FDh8T2RYsWif/31VdfhfRd5D5feOGFHq/79NNPxfY///zTESzyvfiv3Nc6der4PB68L4GQxynQTf0dguGzzz7z2Ndw6dq1q/iOJ06c0Lbl5eU5cnJyxPtLfvzxR/F4woQJHv9/2rRpYvtbb70lHh87dsyRkZHhePzxx8XjHTt2iOf/85//OMqVK+c4efKk2H7rrbeKz5VcfPHFjlNOOSXgsTQ65o8++qjHvjL8mD9vz5492rbi4mJHq1atHM2aNXOEgv6c4+9SpkwZx7Jlyzxe16dPn6B+E3meBXPbvHmzwwzatm0b8jmm57nnnhP7dPjwYZ+vWbhwoXjN+++/H/D9+Pc4evSoIysry2Me8Xdu68+BYM9Lhv9f2bJlHVu3btW28XnP5/rtt9/uSLZzIplBmCkBOf3004X3gD0if/31l1foJhzYi6K67Rs2bEjdu3cXq1w9gwYN8vq/jPpa9uhceumlVLVqVeF94NXLDTfcIFYiGzZsEK/hlVGVKlWER4WFi7xSCwV+fxUOUTCqCztUOEzFgkZfxyMYeAW7cOHCgDcOh8Qa9obxZ3PGC6+yJRUrVhReLRW5+ta71jkkwF4PXhkz7GJnj4wMc7I3hkNG7JEpLCyk33//XWzn56VXRp7HvGrmbK2ffvpJeNcihcOfvEKW8LnHXoV///3XI3QZKnxut23bljp27Gh47gfitNNOC+qc4BuHTf1RXFzscXPacdFBhpCuvvpq+vTTT2nnzp0h/f+jR4+K8c1jnb0LfOOMSD4P2YMaDsGelxIOpzZo0EB7zOc9e7QjmScS7ZwAgYFvKwGZNm2aMGTYXcpKf54crrjiCuG2Z81LOBj9P97GFxsVnozYQDH6vzLMtW3bNuH6Zfcy6x841swTCIchOK594sQJ8TqOwc+dO1eEn9jFnJubS7Vr16Zbb71VuKzZAPKHfj+ka1m+fzjI7+DreBiljurhiVO62f0RjzRoPsYcAvP1/fTHgn9v1kXp95tfq4Y12Uh54oknxEWKjRbOpuHfhydsfsyhys2bN4uMFQmHCPji8+GHHwpjlg0Pdvs/88wz1Llz57C+n7/vxfsbzO9iBP9fDocG83lG8BgNNtMnUEhBPy44zBOt0gX8e3A23csvvywWIxxq5Qs4a9U4fBcIvrCzccHzFBtGrG3j84dD1eGO01DOS6N5Qs4VkcwTiXZOgMDAM5OAcJyZ60nwhZVXF+PHj6cvv/zSY0Jj44EnHj0HDhwwfE/Wqhht008EvBLUTxby/8rX8uTHFzXep+uvv57OOusscXFi7YweFgazboPfk+tU8Cqa9Q6sVYkH8jv4Oh7BwOJIvuAEurEXIdawJ4wn/WC+Hx8L/r1ZcK7CngB+LZ+HEv4u7IWZN2+euHixFkpuZ08N3+RjdYJm0TnrvQ4dOiQE3du3b6fzzz9fE5SbdR7L7xMu/H8jOSfYaA/mnOBbIINZv2rXe9TMhvVV/JuydowFv2wQspHC2hR/8Ou//fZbGjVqlNCr8G/PBg2Pef69wyWU8zKaJNI5AQIDczDBYS8AC854svnjjz+07ewNYVGcCod3OIxiNNj5QsIXFuktYCOJxb28GtPDIrd77rlHezx16lTxV2ZJyfdQRXg80bz99ts+vwf/H3bXvvjiiyKExhe4eMDeJPYO+Toewbh7OcwUjAiQQzuxhj0hHN5hQ5MzjWSoiQXX+rRvvviwt489J/fdd5+2/YsvvhDGqmqY8HvyqpuNbJ7MpTHDHhv2tHCIgjOLfB0/DkuxQJfDGMOHDxeTN7+ez+N9+/YJsaUMH7HRxGEpI3gcqK/lsCZ7MllMGq5XRmbZ8LFgT6UaVpDnfrAhhWAIdI6F67WKFB7PLHjl34qPP4eSObzoyyPKY4fHvToPMOxR1gtfQ/GqhnJeRpNEOidAYGDMJBi82uFBxCsjTjHkCyIPCE49ZB2EmvHEXhHWIwwYMEBcjHng6V2zEr5gcKiKQzz8GZwZwBc6DgWosHeFvSYcC+dVlsxm6tevn/DAMHwh49exG5pXZZxGyRkMHOJQ4VUbZwFwZgKHIXji44ssZ7PIi2Gs4WwlDpfccsst2vHg/WEDJVj3MV+AzapYyh6K77//XtxnfZRc0bFngg0TPu4S9sxNnjxZhHP8fT5/P04n5WPMWR58YWGDg99PXTHz8+wlYc0D61k4c0xmjXDNDT7HJBwi4gsdG0TsepeZKPx/+ELFRoZqADPsUeBaKHxx5vOSz1E2hlif1Lx5c/Ea9tQ98sgjIhuGNTh8LnHIw1cWCBvqHOLisIbMZuIMqXDSs1XYwOIsPM684fNdZq7wewcDj9NYGCGcCi1X8fyb8ZiS1b15vPKxZfg1/DtxDSOZAm0EH3vWGrGBwMYgjwUOHbO3gH9vhn9rzlzj48FlDDh8whdfvnGYio1m/l34nORz99133xUGkYqsifPWW2+JY8VzD++fkTctlPMymiTaOSHHvOrF4d+Nj3lxcbG2jT3ffOMxKX9Dfg2/ln9vvtmSeCuQgSecGXLHHXc4OnTo4KhUqZLI3mjZsqXI7uCsEgln4rDav0mTJkLN37lzZ8cvv/ziM5vpgw8+cNxzzz2O6tWrOzIzMx09evQQ2UYqrOTnLIQVK1Y4evXqJT6bswL+7//+T2QoqMyYMcPRsWNH8dl169Z1jBw50vHDDz94qPzXrVvnuO666xxNmzYV75Wdne04/fTTHZMmTQoqm4kzIFRY8R9sVoX+vfSZB++8846jefPmIkunRYsWjvfee89nZk00kd/J6KbflwEDBojjmJubG/B9v/nmG3EO8fdr0KCB4+mnnzbMEOLMD87a4M/ibK7atWuL39voMzg7hf8/Zy0ZZXfwZ6o8//zzju7duzuqVaum7cfNN98sMsdUvv/+e5H1xN+Nz+dXX33VZzbTnXfe6XjttdfEOcX7y5lMH330kSNUjLIB16xZI74Ln9N83vO+fv3116ZkmJmFv0w6dVysXLlSbBs9erTf9/v2228d/fr1E2OYf6MaNWqILMLffvvN43Uff/yxONZ8zPl9+feRmW18XlapUsVRsWJFxwUXXOBYtWqV4fGdOHGio3HjxiLjUd1fo3EX7HnJz1900UVe30s/D9rhnOBxdMYZZ3hs4++oHyePusaOun9yHpS/mx0pw//E26ACAASGPUe8KlUL1QFgBHus2GvK9aDU7C9gTTgTlIXZ7O2WtX6AJxAAA2ABuCozh6TY9Q5AMGnFHPaDIWOf35P1SzBkfAPPDLAkwVTXZJ2HlbtEg9BRtQO+NFPRaiEBEhOcE8kBRjWwJCyEDZTuyKI3kFwEOidkzyGQPOCcSA7gmQGWhOvWcFZPoDTseKRHg/jB2T7+kFk3IHnAOZEcwJgBAAAAgKVBmAkAAAAAlsb2RfO4Tw03FuRwA8SgAAAAgHUSPbh6ORdoDCTct70xw4ZM/fr1470bAAAAAAgD7ukWqF2J7Y0ZKQDlg8G9ZQAAAACQ+HA7C3ZGBJPIYXtjRoaW2JCBMQMAAABYi2AkIinxLmb08MMPi4Zj3MiMmxFygyzWuagxM24CyDEzfg13buZqqAAAAAAAcTdmuJPvG2+8Qa+++iqtXbtWdH3mvjOvvPKK9hre9sILL4jXcPdo7k/DXVVZFAQAAAAAEFdj5s8//6TLLrtM9JvgQlZXXnkl9e3bVytyxF6ZiRMn0kMPPUT9+/cXbeS58iv3qJk6dSp+PQAAAADE15g566yzaPbs2bRhwwbxePny5fT777/ThRdeKB5zhdc9e/YIA0eSmZlJPXv2pPnz58dtvwEAAACQOMRVAMwdgI8cOUKtWrUSTQG5ceBTTz1F1113nXieDRlG3/mVH2/dutXwPQsKCsRNVUMDAAAAwL7E1TMzbdo0+vDDD0XIaMmSJSKE9Nxzz4m//pTMHH7ypW4eP348ZWdnazfUmAEAAADsTVyNmZEjR9Lo0aPp2muvpfbt29PgwYPpvvvuEwYJw2Jf1UMj2bdvn5e3RjJmzBjh7ZE3ri8DAAAAAPsSV2OGhbz6EsUcbpKp2ZyyzQbNrFmztOcLCwtp7ty51L17d8P3ZE2NrCmD2jIAAACA/YmrZuaSSy4RGpkGDRpQ27ZtaenSpSIN+6abbhLPcyhp+PDhNG7cOGrevLm48f3y5cvTwIED47nrAAAAAEgQ4mrMcD2Z//73vzRs2DAROuLCeLfffjs98sgj2mtGjRpFJ06cEK/Jzc2lrl270syZM4MqbwwAAAAA+1PGwWpaG8PZTCwEZv0M2hkAAAAA9rt+x1UzAwAAAAAQKTBmAEgwThaVUGmprR2mAABgKjBmAEggjhwvolOfmEVD3v873rsCAACWAcYMAAnEzDV76HhhCf32z4F47woAAFgGGDMAJBD5J4vjvQsAAGA5YMwAkEDAmAEAgNCBMQNAApF/sijeuwAAAJYDxgwACeqZQUYTAAAEB4wZABKIPMUzU+TqUQYAAMA/MGYASFDPTHEJas0AAEAwwJgBIEE1MzBmAAAgOGDMAJBA5CmeGYSZAAAgOGDMAJBAHDpWqN2HZwYAAIIDxgwACUJxSSkdOaEIgEsgAAYAgGCAMQNAgnBYMWSYYjSbBACAoIAxA0CCkKuEmKSnBgAAQGBgzACQgHoZpgip2QAAEBQwZgBIUGOmGEXzAAAgKGDMAJAg5B731MzAMwMAAMEBYwaABEHviYFmBgAAggPGDAAJQokuewnZTAAAEBwwZgBIUGMGdWYAACA4YMwAkCA4dH0lUQEYAACCA8YMAAlCic6aQTYTAAAEB4wZABI2zKRz1QAAADAExgwACYIDnhkAAAgLGDMAJAj67gXwzAAAQHDAmAEgUTUzCDMBAEBQwJgBIEFAmAkAAMIDxgwACQIEwAAAEB4wZgBI2DCTTkQDAADAEBgzACRq0TxdqjYAAABjYMwAkCCgnQEAAFjQmGnUqBGVKVPG63bnnXdqgsixY8dSnTp1qFy5ctSrVy9avXp1PHcZgNg1mkQ2EwAAJL4xs3DhQtq9e7d2mzVrlth+1VVXib8TJkygF154gV599VXx2lq1alGfPn0oPz8/nrsNQEyymYpKoZkBAICEN2aqV68uDBR5+/bbb6lp06bUs2dPMbFPnDiRHnroIerfvz+1a9eOJk+eTMePH6epU6fGc7cBiAqoMwMAABbXzBQWFtKHH35IN910kwg1bd68mfbs2UN9+/bVXpOZmSkMnfnz5/t8n4KCAsrLy/O4AWAF9MlLyGYCAACLGTNfffUVHT58mIYOHSoesyHD1KxZ0+N1/Fg+Z8T48eMpOztbu9WvXz/Kew6AuWGmjFTnsCxCNhMAAFjLmHn33XepX79+Quyrwl4a/YSv36YyZswYOnLkiHbbvn171PYZgGgIgDPTnMMSnhkAAAiONEoAtm7dSj///DN9+eWX2jbW0DDshaldu7a2fd++fV7eGhUORfENAKtqZjLYmClANhMAAFjKM/P+++9TjRo16KKLLtK2NW7cWBg0MsNJ6mrmzp1L3bt3j9OeAhA9ZDKT9MwgzAQAABbxzJSWlgpjZsiQIZSW5t4dDiUNHz6cxo0bR82bNxc3vl++fHkaOHBgXPcZgKiGmdJTxV+EmQAAwCLGDIeXtm3bJrKY9IwaNYpOnDhBw4YNo9zcXOratSvNnDmTKlasGJd9BSAWYSbNM4OieQAAYA1jhlOv9cXCVO8MVwDmGwBJk80kBcAomgcAANbRzAAAjLKZ0GgSAACCAcYMAAlWNC8zzamZKdJX0QMAAGAIjBkAEjbMBM8MAAAEA4wZABJUAIxsJgAACA4YMwAkqGYG2UwAABAcMGYASBBkUh+ymQAAIDRgzACQcJ4ZWTQPmhkAAAgGGDMAJGrRPNSZAQCAoIAxA0CCZjOVwDMDAABBAWMGgAQNM6HRJAAABAeMGQASBOmIyUxHajYAAIQCjBkAEi3MlIp2BgAAEAowZgBItDCTyzMDATAAAAQHjBkAEgSkZgMAQHjAmAEgQSg16M0kQ08AAAB8A2MGgARB9pWUdWYYNJsEAIDAwJgBIEEo1fVmYlAFGAAAAgNjBoAEqwAsw0wMRMAAABAYGDMAJJhmBp4ZAAAIDRgzACQIshVTWkoKpZRx3i8ucW0EAADgExgzACRYanZqShlKcxXOQ0sDAAAIDIwZABIszFSmDFG6yzUDzwwATgqKS+iLxTtoX/5JHBLgRRoFQU5ODoVCmTJlaMmSJdSwYcOQ/h8AyYw0ZtyemRIqQudsAAQvzNpAb87dRE2rZ9Hs+3vhqIDQjZnDhw/TxIkTKTs7O+BrucjXsGHDqKSkJJi3BgDow0xlylCayzMjtwGQ7ExfslP83bj/WLx3BVjVmGGuvfZaqlGjRlCvvfvuuyPZJwCSEmm3sGczBcYMAB7knyzGEQGRGTOlMs0iSPLz80N6PQDAXTRPhJlcxowMPQGQ7Jwogrcf+AYCYACUEGneyaK4F83jMFMKq4DRzgAAAGJrzOTm5tKUKVPMejsAYs7Yb1ZTh7Ezaf7GA3HPZmLvDAPNDAAAxNCY2bZtG914441mvR0AMWfyn1vF3wk/ro/L0ZfRXDXMBGMGAE8yXDWYAAhLAJyXl+f3eehkgF04GafYvBZmSoEAGABfVCwb9GULJBFBnxWVK1cWWRb+9Ab+ngfAKsTLmFHDTBAAA2AMjBkQkTFTsWJFeuihh6hr166Gz//zzz90++23B/t2AFgma4Kr8C7fcZg61KtM6VFycfNiQCYuQQAMgO8FRsWy6Tg8wIugZ+ZTTz1V/O3Zs6fhrUuXLmJCDpWdO3fS9ddfT1WrVqXy5cvTKaecQosXL9ae5/ccO3Ys1alTh8qVK0e9evWi1atXh/w5AATLySLPUgTPzdxAA17/k576bm3UDqKqjeEwkxQAy3RtAJKZw8fdWYblMlLjui/A4sbMwIEDqWzZsj6fr1WrFj366KMhZ0CdeeaZlJ6eTj/88AOtWbOGnn/+eRHSkkyYMIFeeOEFevXVV2nhwoXic/r06QONDoiZZ+aNuRvF30nzt0TtM1WbhcO1yGYCwM3hE4Xa/XAWzcD+BB1muvXWW/0+X7NmzZCNmWeeeYbq169P77//vratUaNGHictt1Hg8Fb//v3FtsmTJ4vPmjp1KsJaICoUFhsXicwuFz33tlocT/XMFMMzAwAdUTwzGBLAiIgEADt27Ai5OrDKN998Q507d6arrrpKtEro1KkTvf3229rzmzdvpj179lDfvn21bZmZmSKsNX/+fMP3LCgoEJlX6g2AcFFXgY2qZcUmzMSeGZeYHhWAAWDPjGrMwDMDTDZm2rRpQ1u2hO9637RpE73++uvUvHlz+umnn+iOO+6ge+65Ryu+x4YMw54YFX4sn9Mzfvx40RBT3tjzA0C4HDzmdm/Xr1IuagdSnaDVonnwzABAdMTDmMERASYbM5HGLtmrw8LicePGCa8MZ0NxOIsNHBV9yre/NPAxY8bQkSNHtNv27dsj2keQ3GxSOvRmpEWvWJfq4IQAGAA/YSZYM8CAuJZSrF27tvDuqLRu3VpUE2ZY7MvovTD79u3z8taoYahKlSp53AAIl437j2r3o+ndlgXztDATKgADYCgARpgJmG7MPPjgg5STkxP2/+dMpvXrPUvHb9iwgRo2bCjuN27cWBg0s2bN0p4vLCykuXPnUvfu3SPYcwCCK5O+STFmojmJqu+dogiA0c4AAISZQJSNGQ7pcDG9ZcuWiTTrULnvvvvor7/+EmGmf//9V2QovfXWW3TnnXeK5zmUNHz4cPH89OnTadWqVTR06FBRj4ZTxQEwk7Lp3sNh8wF3mCma3m3pOnfZMFrXbNVjA0CycuREsXYfqdnAFGOGjYt3331X3C8pKRGZRax7YaHtnDlzQnovLrTHRsrHH39M7dq1oyeeeEKkYg8aNEh7zahRo8RnDhs2TGQ+cZG9mTNnCiMKADMpm57qNWEeKyiJSaxe7cvEoNEkAMr4UERl8FYCI0Lu2PX555+Lir3MjBkzREbSunXrRAYS14P5448/Qnq/iy++WNx8wd4ZrgDMNwCiiVpZtKC4VBg3DnLEKMzk6ZFBmAkAY4E8NDPAFM/MgQMHNGHu999/T1dffTW1aNGCbr75Zlq5cmWobwdAwlA2zW3MHC90emRUZ0xUjRktzFRG080wWIUCQB6LCkRegSnGDGcRcdsBDjH9+OOPdN5554ntx48fp9RU9MwA1kXN9j9eWOwVn4+mZkYaLQgzAeCNOvagIwOmhJluvPFG4Y3htGoOAXGfJGbBggXUqlWrUN8OgIRBXfGdcHlm1G3RFB5Krw8EwAAYjc3YhHtBEhkzrF1hsS4Xo+M2BFzXhWGvzOjRo6OxjwDEBHWSPKaFmWLjmdGMGQiAAfBCtV8i6KADbEzIxgxz5ZVXem0bMmSIGfsDQNxQDRctzKQ8H039SolrgpY9maCZAcB4bCI1GyRcBWAAEnX1d7wgxgJgnWdG1u+DABgAaGZAYGDMAOBCNVWOF7nqy3isCKN3qKTRIjUzaSnOoQl9AACeYxOtmYARMGYAMAozFRTHxTOjhZlcf9E1GwDP0BLCTMAIGDMAGGpmjATAMSiapwszoUMwALET4oMkNmb27t2rdbkGwMqoWRInXGEmjyyKmISZpDHjHJrwzADgOQ6hIwMRGTP5+fmijQF3tObMJe5ezQ0hud4Md7fmHk15eXnBvh0ACc0xLcykrAhLYxBmggAYAJ/jQ38fgJCNmQcffJAWL15MDzzwgPDEcOG8efPm0W+//SYaTB46dIieeeaZYN8OAEuEmXw9b/pn6wTA0jODiRsAffFKHBEQQZ2Zr7/+miZPnky9e/emAQMGUL169cS2M888UzzPhsyIESPoqaeeCvYtAUj4OjOxitXLEu1amAkCYAA0EGYCpnlm9u3bR82aNRP369SpQ+XKlaOWLVtqz7dt21ZUBQbAqqjGitSqxKydgSyaBwEwAAZjE2EmYJIxU7VqVdq/f7/2+LLLLqPKlStrj48ePaq1NgDAihi5smPezkAnAIbYEQDPOjMIM4GIjJkOHTrQwoULtcdTp06lGjVqaI/5udatWwf7dgAkHKrnRRoRntlMUWxnoFUAdj5GBWAAjMcedGQgIs3MRx99RClypjWgZs2a0MsA202YserNJAXA+qJ50sgBIJlRhx7GBIjImMnJyfH7fL9+/YJ9KwASEqNqv54N7qL/2fqu2agzA4B3WxH2opZxGfwAiDkznMNw8uRJWrFihRAFl+r6sV966aU4ssDyYSZ5WscszORVNM/5FxWAAfDWq/FQhC0DIjJmfvzxR7rhhhvowIEDXs+xpVxS4l2fAwDLpX8aeGZi2ZsJAmAAvMeHOj5TCJ4ZEEE7g7vuuouuuuoq2r17t/DKqDcYMsDKeIaUjFKzo//ZEAAD4I1+7EEEDCI2Zji0xMXxWPALgG1Fhlo2kyMuYSYIgAEgn2MPungQsTFz5ZVXivYFANgNh5K7JA2bWGVR6HszpaW6spnQIhgAeGaA+ZqZV199VYSZuCdT+/btKT093eP5e+65J9S3BCBhs5k8DJzSKH626729PDMwZgDwGIcYF8AUY4aL5f3000+inQF7aNT0OL4PYwZYFaOQUmmM2hm4ezORh4cGxgwA3tlMsPFBxMbMww8/TI8//jiNHj3abxE9AOyhmTF+3ixemf0P1csp5y6ap6szA2MGAO+FRDQXFiBJjJnCwkK65pprYMgAm3tmjLaZO4Gu3nWEnp+1Qdx/6op24i8EwAAYjU3Px/DMAD0hu1aGDBlC06ZNC/W/AWAtzYzrQTQbTeafLNbuFxWXehgzUgCMonkAGNSZgTUDIvXMcC2ZCRMmCN0MN5/UC4BfeOGFUN8SgLijd1sb9WYy2zOT7jJYmDyXYSPDTNKoQTsDADzHodF4BSBkY2blypXUqVMncX/VqlUez6FXRvJRUFxC63bnU/u62VpfISuiX+iVyNRs5QmzjRn1Mw8fLxJ/5TGEABgAdazoFxs4OiBCY+bXX38N9b8AGzPx53/o9Tkb6eXrOtGlHeuQ3QSGHp4Zk2fQgiJ3rnfeySLDbCZUOgXAuywCOmcDPUhHAhGxI/eE+LvrsPOvfVI/o9/OgL1akiMnijx7MyHMBIBPoCUDYRkz/fv3p7y8PAqWQYMGibYHwP6UuJZMVhfkeQsMo5/NVOAS/arGjD7MhEkbALQzACYZM19//TXt379fGDSBbkeOHKEZM2bQ0aNHA77v2LFjhc5GvdWqVUt7ni8k/Jo6deqIIn29evWi1atXB7PLIEYUucQlxVJkYlH0doo0YqLZzkD1zOSdMA4zQQAMgJFmxtrzDYiTZoYn9hYtWkTh44natm1LP//8s/Y4NTVVu89ZU5wdNWnSJPH5Tz75JPXp04fWr19PFStWjMr+gNAodrkwpIfGbuXSo5ma7aGZkWEmeGYA8B6fXgJ9GDMgDGMmHNFv3bp1g3pdWlqahzdGNaAmTpxIDz30kAhzMZMnTxbdurmlwu233x7yPgHzkZ4Dq3sQfGpmopgOahhmkpoZWQEYkzYAXuMTqdkgLGOmZ8+eFC3++ecfEUbKzMykrl270rhx46hJkya0efNm2rNnD/Xt21d7Lb+G92X+/Pk+jZmCggJxk4Si9QGhI8NL1jdmjFM/jaoCRyPMdKywxNiYsfhxBSA6daBwXEECZTOx8TJlyhRRgO/tt98Wxkv37t3p4MGD4j7DnhgVfiyfM2L8+PGUnZ2t3erXrx/175HMFLvCS5bXzJQGzmYyO05/UgkzSbQwE7pmA+Aen7pjAc0MSChjpl+/fjRgwABq3749nXfeefTdd99p4SRfhfjYQvdXnG/MmDFChCxv27dvj+I3AFIAnAyaGb5rpntb9cxI4JkBwBu0MwCWqjOTlZUlDBsOPUkdjd4Lwynfem+NCoeiKlWq5HEDMfDMWNzv6x2TN95u5tdUBcCSVNeIRJgJAO/x6Osx8GZf3kn65O9tdMIVwrY7CWXMsNZl7dq1VLt2bWrcuLEwaGbNmuXRsXvu3LkiFAUSAxlesrq2w2jlZ+SFMdO9rQqAJeiaDUDg8YkwU2AuffUPGv3lSnr3901JcUqFbMywtoU9J2bwwAMPCOOExb4LFiygK6+8Ugh2uTM3h5KGDx8uBMHTp08XfaCGDh1K5cuXp4EDB5ry+SBy7JPN5D1ZGtktpdEOM6Xou2ab9nEA2Cc12+LzTSzYk3dS/F20NZeSgZB7Mz3//PN0xx13iFAPZxZxITv+26pVq5A/fMeOHXTdddfRgQMHqHr16nTGGWfQX3/9RQ0bNhTPjxo1ik6cOEHDhg2j3NxcIRieOXMmaswkZJ0Zi08uBqnZRt/ITPe2kWfGu50BrBkApJeUhwXftfp0E232ugwZpk3t5JBahGzMrFu3TuhYuPYMe1VefPFFYWywMcKGzSeffBL0ewV6LXtnuAIw30CCVwC2+OxipI0x8sKY6pkx0Mx4N5oMLHoHwO7I8ZmWUkbMOagz45+l2w5r9zPSEkpNkjjGDMNaFvaoXHrppfT7778Lo+TDDz+kzz//3Pw9BBZJzS61oWbG6HUUkzCTNGbkvsiwEwDJiByfTk2ZA56ZACzd7g4tWb1sRtSMmR9++EF4ZObMmUPLly8X7QjOPvts+uKLL6hHjx7R2UuQsMjwkh01M0ZeGDPDaf7CTNKoEZ/pcIS36gDAJshRx56ZAjuEtWPomSmy+EIzWEKeIy+66CIRUrr//vtFsTsuTAeSF3edGWtPLnq7pdSHZ8bcOjOlvgXAijED2QxIduS4kx5LhJl8s+3gcVq05ZDXHG13Qg6mcePHM888k5599llq2bIlXXPNNfT666+LlGqQfMjwUrHdjBnWqhhIgKMeZpKeGUUjAxEwSHY0zYyrEJPFp5uo8vZvmzyOT7LMHyEbM5wu/eWXX9L+/ftFDRgOLXHX644dO4r6MCC5KCq1RwVgL82MCDMFfl20i+aJz7T2oQXAdM8M6swYc7SgmD5d5Kx6371pVfEXnpkALF26VBgxnCr9yy+/UGlpKdWrVw/DNlk1MxZ3ZeonR548Y1U0r1HV8l79mqR2hkHnbJDsqNlMDMaEMQePFoh5pXxGKp3VvJotkjOi5pnhDKacnBzq0qULffTRR9SiRQv64IMP6NChQ7Rw4cLo7CVISPhiL40Zy2tmdI/5+xh9JUcUwkzjrmivbatWIVPTzkh7JlncxAAYoS4qoJnxT4lr0uLjlJ7ivLxDAOwDNl5uu+02kcGEvkfJjeq+lOEmq6L3woivo2ziBSFvi0Y2U41KZennEWfTN8t20UUd3KFa9s4Uc7gLtgxIYtShKT0zGBPGlLqOFWvu0l3lHKw+N0ctm+m5556Lzp4Ay6F6DKyvmSGPCqP675eWkkKFJaVR0cxkpqVQ/ZzyNKJvS4/neXXFwmp4ZkAyo445rQErOk36PVapKWU0sTTCTH7gOjOXXHIJNWvWjJo3by5CT7/99puJpy+wmmfGLpoZNSVa9cK43dvmeYJkmCkz3Tjaq4kdrW0nAhAR6pDjRYXYBmMmQHFB0jwzVp+bo6aZ4Uq/5513nmj4eM8999Bdd91F5cqVo3PPPZemTp0anb0ECYl6sbe8ZsbhnUWkppubnUXB7y3fPjMt1fA1WIUCYOyZsfh0EzVKXAeG259Iww9hJh889dRTNGHCBLrvvvu0bffee6+oP/PEE0+go3USobovrW7MuD0zPAF4Ns/k0JMU45r1NU8WuWvMcJjJrzED1wxIYtT1A1KzgztWqWzMaJ6Z5HDthuyZ2bRpkwgx6eFQ0+bNm83aL2ABVIvfLkXz1B5I8juxmE4WsTPLM6NW//VpzLg+M0nmIgCCNmasvniKRZgpIzW5splCNmbq169Ps2fP9trO2/g5kDzY0zOjamac34+3yM3c5sBMY4Y72vrqiI2JGwDPBYTUgUAyY0yJXIApAuBkKZoXcjYT92RircyyZcuoe/fuYiLmztmTJk2il156KTp7CRIS1Rtjdevfn2bG0zNjzucVuMJMvrwy6r5Y3VAEwCxjxmwPqZ1Ts9NkmClJwtQhGzP/93//R7Vq1aLnn3+ePv30U7GtdevWNG3aNLrsssuisY8gQVFV8vbSzHh+P54/ZQNIs8NMvsS/6sSNNFSQzHhkM7ku0Fafb2KRmp3umsuSJZspZGOGueKKK8QNJDeqN8bqmplSA8+MKgDWwkymGzO+PTPuiTs5VlYAGOFQTv9ULTUbx8qIUmXOkvOH1b3mUdPMAGBkwFh9pSTrVrDR4m4j4B1mcpgdZvJRY4aBABgAzwWEVgEY1owhJdIzo1YAhmfGTZUqVXyKFPVwjyaQHKgeA6vHZeV0yUaLbCOgeWaiEKsPJswEzQwAnmEm1Jnxj8OjnUFyVQAOKsw0ceLE6O8JsByqxW91z4zqnnUaLu42AvxY2vJmfc9gwkwwZgDQFc2Djiz4bKYUFM3zYvny5aIgXlZWFs2bN09kMaWlhSW3ATZCFZbZRTMjQko8B5Qohotm4JiYzeRqZVDWT5gJAmAA3MYMD0F0zQ6nnUFpUpxGQWlmXnnlFTp69Ki437t3b4SSgKBICS3xGLKyd0ZqZtyeGU/NjNmTqGwymeEnzCQFfGbVtgHAkigLDa0StwljolApXGnvRpMOSgaCcq80atSIXn75Zerbt6+YzP/880+hozHi7LPPNnsfQYJSohskHJZJTfF9cbaSZkb9fqoo2Cy7gjtwMxlKxWE9eqMKgGREcZCa5iF95OtVNHXBNpp9f09qWDWL7EKpyz5z9mZyCYAtrmc01Zh59tln6Y477qDx48eLg+QrLZufKylx95wB9kYv+rWyZ8btynav/qQRwdvMFgBL169a10YPNDMA8EJDzSr0HK/hMuXPreLvG3M30fj+7W2YzUSiujiDbCaFyy+/XNw41FSpUiVav3491ahRIz6/FkgY9IPEyh4Et2bG24hIiUKdGXns1F5QemDMAKB4ZqJQvNJuehKHpplxe2Z4HuPtwWYkW5WQVLwVKlSgX3/9lRo3bgwBMPD2zFg4NquKDN3hHfn9FM+MSXOffG+ZPmkEMjcAMMo0NC/ca2VvcuB2Bikei6eMNBgzHvTs2VP83bdvn7iV6mb3Dh06xOAnA4mAnTwzqsgwxcAzI1c1ZntmZMaBERAAA+BGDTOZZYRYes7ym5pNHnMLL54ybF4jN+T86iVLltANN9xAa9eu9crsgGYmudBPKHbRzMgJU2YBOLOZPF8XKfK91dWTHgiAAVDTjdVK3OaMQyvPWYGOVZqix0sG3UzIxszQoUOpRYsW9O6771LNmjVtH4cDwcebrVwF2EMzo8siUt3bZlVR18JMSi8oPVq1U5tNuACEnc2kaWbMOYZWnrMCNppMLWNbbZApxszmzZvpyy+/pGbNmkVnj4B1w0wlNvDMuLwzarsGZ32L6ISZ/HlmpDFjN1c4AOHXgCJTx6HdrvGlSmq2TM/m+SMZPDMhB9HOPfdcUREYAP2qxsoXXbWniZER4Z5EydzUbH+aGandQVM9kMS4s5lUIb5Zxoy9rJkSJTWbSabO2SF7Zt555x0aMmQIrVq1itq1a0fp6ekez1966aVm7h9IYPTGi5Xjz2pKo15kyKFnrbWAycLD9GDqzCTBRARAMB3tzc5msvICLNA8JueXk1Rqu+9pijEzf/58+v333+mHH37wei4SATAX5HvwwQfp3nvv1Rpb8g/z2GOP0VtvvUW5ubnUtWtX+t///kdt27YN6zOAuejDSlaOPxvVstA0M+SuCmyW8LAoBM9MMkxEAARTndvs4pVWXoAZUeKaguUcJueXZNDMhBxmuueee2jw4MG0e/dukZat3sI1ZBYuXCgMFn1a94QJE+iFF16gV199VbymVq1a1KdPH8rPzw/rc4C56AeIlScGozoznqnZ8nXmGoJ+68y4vDZWPq4AmDs25TZzjqvdFgqlihdL1eRBM2PAwYMH6b777hOZTGbAVYUHDRpEb7/9tke/J14Bs4fmoYceov79+4uQ1uTJk+n48eM0depUUz4bREaRbiKw8sRg1JtJTc02e0Uo+6VI74sR0s6x8nEFIFIcqmbG5ArAdlsolCrZTEyGZszAM+MFGxZcBdgs7rzzTrrooovovPPO88qa2rNnj2huKcnMzBRF+zjU5YuCggLKy8vzuIHoYKc6M2qsWXphNHGgCD3Fvs4MPDMAeHobzBYA222hUKr0k/MIM1lYAhA1zQzXmBkzZozQzbRv395LAMxhqGD55JNPRBE+DiHpYUOG0XuA+PHWrc4mYb60N6yzAdFHb+1b2fpXXdn6bCbPYl1mtzOAZgaAoDwzoq2IHK/mHDP7ZTORQHqXtc7ZSZCaHVY2E/domjt3rripsDUYrDGzfft2IfadOXMmlS1b1ufr9EX5AjXMYkNrxIgR2mP2zNSvXz+ofQKRCYCt7JlR6zPoNTOetWdMrjMTRDYTiuaBZMZdNkHNZjLXQ2rHzC9Vk2e372la0TwzWLx4sejtdNppp2nbWEA8b948IfjlztzSQ1O7dm3tNfx//Ol1OBTFNxB9bFVnhpQJ08AzIx0oZnfrRTYTACG0GoFmJqhjlaLLZpIaPTsTt85TXHxv5cqVtGzZMu3WuXNnIQbm+02aNBHZS7NmzdL+T2FhofAGde/ePV67Dfx5Zixs/Xv2f/E0OKLRziCYRpOprufs5goHIPJsJpMEwA6bpmaXkWEmeGb8smPHDvrmm29o27ZtwsBQ4VTqYKhYsaLIUFLJysqiqlWratuHDx9O48aNo+bNm4sb3y9fvjwNHDgwhJ8XRAu9J8bSnhmlnYF3b6ZotDOQ2Uy+1xOoMwOArzoz5hwZK4fGg0nNzkiibKaQw0yzZ88WVX4bN24sQkFseGzZskVcDE499VRTd27UqFF04sQJGjZsmFY0jzU2bAiB+KMfIFaeGIxKpqt1ZqJV38KvZwZ1ZgDQVQB2jcMIBqJa+NJuWpJS13GReju0M/ADC2zvv/9+evzxx4VR8cUXX1CNGjVEeOiCCy6I6IeYM2eOx2O+sIwdO1bcQOJhpwrAHiJDXX0XNcxktmbGX9E8eGYA0C00TNDMqHaQleesQMdKLf1gN6PNFM3M2rVrRW8mJi0tTXhOOLuJjZtnnnkmGvsIrCIAto1mRu+Z4UnU83Wx7JptZS0SAOYVzTOnN5PqQbayN9l/o8ky4m+6lsxgL6PNFGOGdS1cmI6pU6cObdy4UXvuwIED5u4dSGjs2GhSnTDdvZmiUazL5ZnxUwEYnhkAFAGw2r0+gnGoLkisrPMLJjU7Teuaba/vaYpm5owzzqA//viD2rRpIyr3csiJs5K+/PJL8RxI5jCTdQeM3HWnF8Yzi0jV0Zjdmykoz0wSrKoACMVrGomH1MMzY7OLfIn0JmuaGQiAfcLZStxPiWEtC9+fNm0aNWvWjF588cXY/GIgQQXApTbxzJCuN5P5KaFabyZUAAYgwOA0N5tJTce28gIs0KJMzWaysgQgap4Zrv8i4TTp1157zex9AhZBTgQ8YApLSi09MaiTQKq+AnA02hnIOjP+KgC7JiIrh+8AME/Uas6iQg1R2b3RZJpsZ2DhhWZUi+YdPnxYtDXgzKZDhw6JbdxjaefOnWbvH0hgpPGSmW79i65amEtmArgrALu3mS8AhmYGAH84XK4Zs7KZ1HnKbhf5UiUDM9mymUL2zKxYsUJ0uM7Ozhb1ZW699VbKycmh6dOniwaQU6ZMic6egoRDpheXTU+l/JPFlvbMuFOzy5CUsbh7M7mrAptVMTSYRpNuzYx1jysA5nlNVSF++O+njmG+y+NLjjXbZTOluhZmSVA0L2TPDDdxHDp0KP3zzz8eDSL79esn+iqB5EFa++XSUy0/YNyrPzWbyd3OQE52ZoeZUAEYgFDaGZhQZ0Y3TRUWW3fe8rcoU+eXoiRYEIVszCxcuJBuv/12r+1169YVTSFB8iBdtGVdYSb7ZTN5h57MSs3W2hkE5Zmxz2QLQGQCYDJVAGw3Y6ZEl82UnubSzNjoO5pmzLA3Ji8vz2s7tzaoXr26WfsFLDRwMtNSLR8O8axl4d01O3rtDAKnZidDvBuAoLpmm+KZ8fy/BSUltu3NlC4bTVp4bo6aMXPZZZeJar9FRUXaCcYNJ0ePHk0DBgyIxj6CBEVeZO3gmfHQzEh9jIcxY54AmNPA5XvLbAMj5HNWNhIBMC2bSfE4mCUAtptnptT11aRmJpl6M4VszDz33HO0f/9+0Y+JWxn07NlT1JjhPk1PPfVUdPYSJCQFxc4VTfmMNMtfdLXKmSmKZ8ZlrKkpoWqTunBRq3H6L5pnfSMRgKg0mkSYya/XKUWGmZDN5JtKlSrR77//Tr/88otIxy4tLRXdsjnDCSQXBa4VTfkMKQB22KqZnVpnRmpmzMhmUldJ/rKZ4JkBQKdnM0G7pv+/XCPLjmLpZKszE1JqdnFxsdDMLFu2jM455xxxA8mLdM+WcxkzVhaqGvV/0bKZFP2KGU4S1ejzl82E1GwAPKtzy4t0RGEmOwuAHZ6p2clUZyakMBN3yW7YsCGV2EgwBcKfYOSKRvPM2KbOjL5rtrntDNRVEjwzAAQYm66/7B11LyqgmTE8Vg59OwNoZnzy8MMPe1T+BckJ6z7kwMlyaWasbP2rcXkZUpLaFtW9bUadGXeNGXf4ym82k4U9XgBEI9MwknWTfgzbyjNTatxo0soLzahVAH755Zfp33//pTp16ggvTVZWlsfzrKMB9keNM0sBsJUHjKqZ0WczmV1nJpgaM+rzVhZWA2CuZsa1rdTEbCYbamZSyiRfqDotnNRsf6tJkByoq5nydtLMqF2zPRpNyteZWGPGj16GQTYTAMaZhtDMhNhossS6c3PUjJmxY8dGZ0+AJY0ZHixa/w8LW/9yz8VkqfVmcguAzawzUxysZyaJVlUA+EIOOWePtMjDTLbOZip1/pUOBxlmSoY5JOQ6M02aNKGDBw8adtLm50By1ZjJTEuhVBsMGNU9a1gB2AThoXfH7ECeGesbiQCY2jctJfJ6T3Yumleiz2ZKojkkZM8Md8o2ymYqKCigHTt2mLVfIMGRE0BGWoriynTYIgugjIFmxsxsJq1jdoBOvfDMAOD2NqSYVO/JzqnZDh+aGSs3ATbdmPnmm2+0+z/99BNlZ2drj9m4mT17NjVu3Nj8PQQJXTCPjRm5CjDjQh8vNNczi31d2zx7M5lXZyZkz0wSTEQABKNn0+aaCIaEV9fsEhs3mkxNnlB10MbM5ZdfLv6yZTxkyBCP59LT06lRo0b0/PPPm7+HIPGNGRtoO1TNjDRmjDwzjphqZqwfvgPAzLEJAXDwmV9qEoGVveamGzPctoBh78vChQupWrVq0dwvkOBI1yx3zLaDMaNqZqQ5Y9TOwIyEraCzmWwgrAYgOr2ZTOyabctsJkq6UHXImpnNmzcbin8rV65s1j4BCyBdsxmpKV69jKyvmfH0mKiiYDN7MyGbCYDAuKcVZVERSaNJGwuASzXDTy8Ats93NC2b6ZlnnqFp06Zpj6+66irKycmhunXr0vLly83eP2AhAbCVjRmj3kwSZ28mz9eZUgE4hGwmM8JbAFh7oaH2SDNRAGwjzUypIpZWF0zJ4N0N2Zh58803qX79+uL+rFmz6Oeff6Yff/yR+vXrRyNHjozGPoIETs1mY8ZMr0Xca1mICsB6z4zJ7QyCzGZS9yMJ5iIAgi5oGck41IeZ7CSwL9F5ZrTCm9DMeLN7927NmPn222/p6quvpr59+woBcNeuXWP4s4HE0MzYyzOj1pTRUNsZmFpnJoAxozzPBlBqirPSMgDJqZlRUrMjaWegG8N28lo4klgzE7JnpkqVKrR9+3Zxnz0y5513nnYQ0U07OY0ZewiAvfUxEo+eMKakZrs8MwHCTHIisvqxBcCsbKZodM22k9eiREla8Awz2cf7ZJoAuH///jRw4EBq3ry5qATM4SVm2bJl1KxZs2jsI0hkATCHmWxgzDgMXNkS1cAxVTMTKMykPG+n1SMA4daAMiXMZGPPTKkuNRsVgP3w4osvipASe2cmTJhAFSpU0MJPw4YNi8HPBRKBgiJ3NpMcMKV20czojAxnTxgyr2u2a5UUSAAs68wwJTZaPQIQftdsMzwz+sd2Ts1OSZr5I2TPDBfIe+CBB7y2Dx8+3Kx9AhbyzHCdGX0vI6trZrxSs7lbb4r5nhlZndMXqk1l5WMLgDlhJqfnNFIvsJcA2EZjq1TzMEsBsKvVjI0MNtM0M2by+uuvU4cOHahSpUri1q1bN/rhhx88XP/cpbtOnTpUrlw56tWrF61evTqeuwwMKgDLuKwZXovE0MzonzW7nUFwmhmekOzg9QLAlBCwcnGOqGiePsxkI69Fictm0RpNJlE7g7gaM/Xq1aOnn36aFi1aJG7nnHMOXXbZZZrBwmGsF154gV599VVRdbhWrVrUp08fys/Pj+duA12dGTt4ZlTNjD7MlGJ2OwPXcVLDSL5A52yQ7KgFLc3QgOizmex0oXd4Fc1zpWbb6DsmpDFzySWX0IUXXkgtWrQQt6eeekpocP766y/xo0ycOJEeeughITpu164dTZ48mY4fP05Tp06N524DXZ0Z2/VmMshmMqPyqL6uRaAwk0dqpY1WjwCEGzoxQwPiHWayY6NJ8pg/+BBaeX5OeGNGhdO6P/nkEzp27JgIN3HbhD179ogaNpLMzEzq2bMnzZ8/P677CozrzFg5FKJOmPqiec4Mp9jXmfH0zIQ+4a7edYQGv7uAVuw4HMZeApAYaMlMZczRgNg5NbtUXzRPV6vKzoQsADablStXCuPl5MmTwiszffp0atOmjWaw1KxZ0+P1/Hjr1q0+36+goEDcJHl5eVHc++TFbmEmf5oZtc6MGasbOakEE2aSGU/hfO5905bRhr1H6bd/DtCWpy8KY08BiD8Ol9+Ux6DUmUVWNM/zsZXnLT0O11eRRp/azNbunpm0YAvl6V3vvjh06FBIO9CyZUtRo4abVX7xxRc0ZMgQmjt3rva8/nM5/ORvX8aPH0+PPfZYSPsAIms0qYny7NKbyaD+i/yOprQzCDKbSf3ccCbcw8eLwtg7ABJXM6N5Zkqc/cqCvS6pyHmK34rv2ukiX6J0GGdU/Z/0CCe1McPaFQkXynvyySfp/PPPFx4V5s8//6SffvqJ/vvf/4a8AxkZGVqxvc6dOwuh70svvUT/+c9/xDYONdWuXVt7/b59+7y8NSpjxoyhESNGeHhmZPsFYH6dGbUCsKVXOHLCTHFnLhlrZswMMwXhmYlAj9SoWhbty3d6KcOd+AGIN9L44NNXLTTJm4NYD/i84HNZiRNFJVp2oZ27ZjN2MtrCNmbYWyIZMGAAPf7443TXXXdp2+655x6RccRNJ++7776IdognXQ4TNW7cWGQvcTPLTp06iecKCwuF14Y7d/uCdTV8A7GrM2Mrz4xY/Xk+p1YFNqXOTJCNJplIDMUGOeXp781OT+mBo4VUvSLGBbAe8swXAmAT+pXJizqHyNmYsdNFvlTXNdu5OHMafnbXzIQsAGYPzAUXXOC1nT01bMyEwoMPPki//fYbbdmyRWhnOHNpzpw5NGjQIHHiciG+cePGCR3NqlWraOjQoVS+fHnRTgEkjmZG8x7YQABs3JtJFQBTnDwzoU9Eahjr331HQ/7/ACRaCFjVmYUr3JWLLp67xPvYyZhxyArA7rGvpWcjzORJ1apVhXExcuRIj+1fffWVeC4U9u7dS4MHDxatELKzs0UBPW5eybVkmFGjRtGJEydEm4Tc3FzRlXvmzJlUsWLFMH9qEBUBsA3CTO72L8ZhJlPrzLi8WiFlM4UxEan/59/9R6lb09DGJwCJ1s7A0zMT3liUiy7W+znfp9SGjSbJcw4pQZjJCxbX3nzzzcKDIjUzXBeGjZB33nknpAP/7rvv+n2evTNcAZhvIEHrzLAAWHotLGzMuEWG3p4ZXhJKvYkZLmlVPB0Ira5GGJ+r/p+N8MwAq6J4TVUNiFwUhIqcpzLT7eexKNVlMzHCACyy9mIzKqnZHOpp3bo1vfzyy/Tll1+KlSqnUv/xxx/CcwKSq50BTwipNggzqZUz9TaG2GZimEkTT6enRlUzo/4fhJmAVXHXmXEK8XlMsKFeYpJnxlaaGYenAJjRqibbSOhsWp0ZNlo++ugj8/cGWDo1m8cRr3qMUputIwD2LgfgTNc2L8ykiaeD8MxEUl1Z/T+5xwtD/v8AJFKdGTkspTFTFK4x47qmcyYmYyePRakuNVvV5tnpe5pWAXjjxo308MMPCyEup0ozHGZCE8jk1MyoLk2remfU1V9qlNsZyBCddHNHzzPjXonZKf0UJK9mxowWH/KCz5mYdtXMpBh4ZuzkgTLFmOHU6Pbt29OCBQtEkbujR51ZEitWrKBHH300GvsIEjnMpKRmW3nAuHszub0w0WpnoBmCUc5mUn8LuxfMAsmRzcS4m02GZ4SoqdnisY3GhkNn+DHuQoP2MdpMMWZGjx4tiuZx/RcueCfp3bu3KJ4HktAzU8YGxowSa9YLgNkr464zY67eKFaaGfl7AWDlgpZmhE3kHCVLF4QbrkpESlzfRV1gmtECwpbGDNeDueKKK7y2V69eXVQHBsnXaNIeYSZ3XN5vnZlSMz0zgQXAMhU1Us2M1OkAYOWx6SlodUS0cJFhJjtd5Et1x4qxRYX2aBgzlStXFnVh9CxdupTq1q1r1n4Bq6Rm640Zi7pspcdaZkuoqLVnzDDWQvPMhJ8+qv4fu7uYgX1Ra0CZEmaS2UxSAGyjsVFqWDQvMuPPtsYMi365bxL3TOKJv7S0VKRlP/DAA3TDDTdEZy9BQsGDX04w7JlRr/1W9cyonXn1ZWZ4W0aaeemNqlcrEJGI9zw0MwgzARvUgDInzEQ2rgBM3gJgl3fXTkJnU4yZp556iho0aCC8MCz+5RozZ599NnXv3l1kOAH7o4YseEJQvRlWddmqk4A+m8nZ4C7FNCGt6tWKXTaTNX8XAHw1T4y0nYG9U7PLeHl3rTo3R63OTHp6uqgx88QTT9CSJUuEZ4YbQTZv3jw6ewgSDlVMKjNy2AAoofALWSWOANgtNJSwsSZFdGZoT9wdx4PQzERQkNBDAFxSis7ZwNJjU60zY2aYyapzltFxcui8WOocYvcFTcieGe6Yffz4cWrSpAldeeWVdPXVVwtDhnso8XPA/kjNhygvLo0Zm3hmyEdvJhlmMkN7UiALDobgmSkJ43P1K1c7rUBB8iDPWlnrSc454c41+kaT/D5mFMOMN6XKVzDSzFh1bo6aMcO9mWRtGRU2cPg5YH/cmg+3Z8HqxozDR/8XhudQ6ZmJVETHnxOOZiYcQ0T/WyA9G9iqzkyYY1F6ZtT5yw6GfonyHdQq5tDM+JmM9eXemeXLl1NOTk40fiOQYJwocmo+ymW4JwN5/beqAFjVzEjDRf1uZoWZ9HqjQEQS79a74WOV0XTkeBF9v3I3/fHvAcsatyCBKwBrgtbI6syoiwk7nKelytyremYiyYi0pWamSpUqWqOvFi1aeBg0JSUlwltzxx13RGs/QQJx0mXMlFUmg0hdvwnjmUlxF9OScEqoNGbYIPBl0IcSoouLZyZGxszj366hL5bsEPfvO68F3Xse9HTAxGymCBsnyou+WoG72GbGTIoyPaVb3GtuujEzceJEMYnfdNNNIpyUnZ2tPceVgBs1akTdunWL1n6CBOJEocuY8fDMWHvAqLUs9J4Z/mpy4uP5gr+jXB2aIZ72R2oERfP0E3SsBIC7j5zQ7m87dDwmnwmSRwAsMwsj9swodZ7sUGumVDkchu0MbJ6aHbQxM2TIEPG3cePGIg2bs5pAciLDTGWVmLPVRWZqZ169ocJeGHUbGwVBJCL59czIlPZYemZiVWtGdWfLNHQAwkU6HNwC4Eh7Mzn/ptvMM1OifAejOjNWnZujlprds2dP7T5nMBUVFXk8X6lSJXP2DCQsJ12pxapmxuoCYDkviswlP5oZGa4pR+FZM5r4NwivjOdxLTXBMxMbY0YNZ0F0DMyunaKlZkfYNZvLSfBigceJVectFYePMFNakmhmQs5m4qylu+66i2rUqEEVKlQQWhr1BpJHM1MuXQkzpVhdAOyeMKX+R+IUBZcxxSUtPRXBtDIw2zOj6nWiibpijtVnAvuihYB1YaZwDRD5/7ielJ06Spcox8OwnYHNw0whGzMjR46kX375hV577TXKzMykd955R2ho6tSpQ1OmTInOXoLEFAArF2Q5wZjRiDG+rmyjMJMsnBd58Sl3k8lgPTOuiTus3kzxyWZSV4DwzAAzW414FIELt86M1r/IXh2lS5WvoIaw0WjSBzNmzBCGDBfMS0tLox49eog2BuPGjROVgUESaWZUz0wZa8eeVc2M3tCQE4Oa0RR5k8ngwlRyVwId1+OFxTR96Q7xVyIn6FhXAFWPDzQzwLxsJk/NTDiFJD08M0obFqvOW4GaTHpkmiLM5MmhQ4eECFjqY/gxc9ZZZ9G8efN0rwbJYszIAWRVz4xay8KraJ7rrxm1ZsL2zAQ4rlP+3Er3TVtO/V+br22TE7QMB8bMM6NrowCAWSnHkYZe1bHEc5adOkqXKoU/VSL1ZNk2zMRtDLZs2SLuc5PJTz/9VPPYVK5c2fw9BIkrAPYwZqzdtE3VzPAkpyYayRWhO8yUeJqZOev3ib/r9uTT4eOFHpO2TKGPlWGhZk3JPlQAmOWZiXSu8dTH2UdPUqo7TmYkEdjamLnxxhtFtV9mzJgxmnbmvvvuE3oakEQCYI9sJmsLgFXNjNDHSEWzstLRwkzFsdTMBDcRtarlziL8fPEOkdkgJ/vyrt8pVqnZ6goQnhlgtsdBLirCL5qnemFtpJkp9cz6kmjHywbf0dTUbDZaJL1796Z169bRokWLqGnTptSxY0ez9w9YpAKwXC2V2qA3k5wAXLUBNS+NGWEmt2bGXM+MmjX07YrddOOZzlCw6kGLlWGhXmTM8Mzwb8PfTw1rguStM5NqYpjJnc1kzXkrGM1MapKkZodszOhp0KCBuIHkrgAsE4Csav270z/VzrwlOgFwZCtCj6J5QXpmpAEVKMVZFdpymEl1m0sjIC7ZTCZ85n3TltH3q/bQvJG9qVZ22YjfD1g7mynSDCQ1m8nqxT5VSlzfQV+L007fMWJj5uWXXw76De+5555I9gdYgJOuC6taAdj6AmBPF61aV0YvAI5kFad5ZoIsIVy1Qob4e+hoof/3VTwgLNBWJy5NABxBeCwU1LLpBS4vXiR8tWyX+Dt1wVYa0bdlxO8HrIV2Ouk8M+GOQzWbyY6amVSvbCb7fMeIjZkXX3wxqDfjFSyMmeTxzBhVALaqZ0ZzZbseqxV/pYEju1xH4uHQNDNBNJlkqlfIFH/35Z8M2jPDv4/6O8jfKXZhpuhoZvJOutPOQfJqZtzl+UtNCDPZJwRTqluQSeyUsRWxMbN58+bo7wmwdNE8zTNjWQGw50SgFs5zVx4tY4JmxpXNFKQxU6OS05jZn18Q4H1LPTxnak2JWKZmq8Jj52c6hLeOq61GytECGDPJiDybtLEZoWdG387ALiGYUh/GjNUzTaOWzQSAUTuDYOuhWKVkupFnxpSieUWhembKal4Jedz9va/0/kiDi3ddio1jYcwYXWDM8s7kn/TsAweSrGu2SXON2s7AHYKx5rxlHD4jD2TI3Kpzc9QEwDfddJPf5997771I9gdYtWie5QXAOs2MkpotDRxTwkwloWlmKpVLE5/LBgp7Z9buzqOPFmyjidecQlWynHoa5qSuO7X0YvDKU4qNY9FawCguz4aWGZlI8MwkJ/o6M+kR9hpStSXuEEypbY5Tqlc2k336T5lqzOTm5no85q7Zq1atosOHD9M555xj5r6BhA8z2UkArPPMpKlhpjLmCYBD9MzwZ7NuZufhE7Qvv4Bu+2Cx2P763I304IWtvd5XctSlL+HfxZ1SHv3fxujYFJTw+ZIe1vup51M+NDNJiVxoyLGZqmUVRi4AtrrWz9f3UrFTKM1UY2b69Ole20pLS2nYsGGiOjBI1grArgFjUc2MjMy74/JGRfMiX+EUloSmmZG6GTZmVu447N5b3XEu8OmZSTElPBYs6gqXvyNreSKpNaOGqKSBBpILfdmEdJPCTKqhb4cLfanO6NP3ZrKDwRZ1zUxKSooophds1hOwb28mq04K7qqg5FUHpowrWu+uABw7zYya0TR96U5tm94u0dehkcaMmLBdXqZYVACWEyZ/rjTYIuplpfzffAiAk1wArAubRFpnRvHM/PfrVfT0D+vInkXzytgmlBYTAfDGjRupuDi0ldP48eOpS5cuVLFiRapRowZdfvnltH79eo/X8Ap07NixVKdOHSpXrhz16tWLVq9ebdZuA5MEwNKjYV1jRq5qvLOZvNoZRBCucWtmQvPMMMt3HNG2HTrmmd2kFwdLLwZ7kzJi6JmRuhz+XNkZPCLPjGKA5Z2AADgZ0WcaugWtEXbNVormcQjzjbkbaW+e/xIIVuzNlGajUJqpYaYRI0Z4nWi7d++m7777joYMGRLSe82dO5fuvPNOYdCwIfTQQw9R3759ac2aNZSVlSVeM2HCBHrhhRdo0qRJ1KJFC3ryySepT58+wuhhIwjEFv693Z6ZFNvEZaU2Q0vDVj0zujBTRKnZRaEbMzKjSeXgsUJDzwyvwvg3UD0zGTHUzMgJk0MB7s81x5jh73i8sJjKZ0RcuBxYWTPjCjNFnJotBMCe43DNrjyqWamsxXszkQdyLrPq3BwsIc8KS5cu9QoxVa9enZ5//vmAmU56fvzxR4/H77//vvDQLF68mM4++2xx4Zw4caIwcvr37y9eM3nyZKpZsyZNnTqVbr/99lB3H0QIX5ikXENtZyDriFh1wOhrWWR41JkxLzU71Gwm1TOjcsiHMZNdLl0856GZkeGeWISZXN+PPVsyJTySKsD6fT54tJDK58CYSebeTJEunDTNDIeZlHHOrNp5hHq3qkFWpARF80Lj119/jdJPQXTkiNONnpOToxXr27Nnj/DWSLhDd8+ePWn+/PmGxkxBQYG4SfLy8qK2v8nIyUL3xUUNM6VZXACsrwDsKQA2sc6MS6gbimammkszw1zSsQ7NWL6LchVjhg0IOUFX1hkzqsgxlnVmeDVoimdG93/ZI1U/p3yEewnsUAE43PPZo86Mzo2xcqc7lGu31Oxim7czSJiieeyF4RDWWWedRe3atRPb2JBh2BOjwo/lc0Y6nOzsbO1Wv379GOx98iDrmagXSfmYUSvPWgk5McqJUnozGDk1SAMkkrLg0tMQSpipgXLxHtarqXZRl1oC2SuLyS6f7qGZcdaZiV2dCTlhci0QszUzzMGj/ishAxtnM7lGYqTJBqq2RB9mWr0rzwaNJsskZdG8kI2ZgwcPCp1LmzZtqFq1asKLot7C5a677qIVK1bQxx9/7PWc/sfhSVy/TTJmzBjh4ZG37du3h71PwE9fJl0RNE0AbFHPjKb1cBlosjAXI+c7UzQzIfZmYlrWqkgvXtORpg/rrhk2Tv1IiVcYh8NMzLG4eWakUZhCmSZ4ZvRZWnqtEEgCdJmG8nwOV9Bq1M5AwiUQ9CFcq1CqdANXiVRjZBVCDj5ff/31InPp5ptvFh4SX0ZFKNx99930zTff0Lx586hevXra9lq1aom/7IWpXbu2tn3fvn1e3ho1DMU3EB2MxL9WFwCzcSz3W34P1eskV4RyFWdGo8lQNDPMFZ3qafsq67fwpJuVmeY2kFJTKMsljpVpzPEqmpeuamZ0NXAi8cxY9UIDzBQAR5ZqrGYz6TUzzPo9+dStaVWyW6PJEgvOzVE1Zn7//Xdx69ixY8QfzhMzGzJciG/OnDnUuHFjj+f5MRs0s2bNok6dOolthYWFIgvqmWeeifjzgTnVf60uAFZXLFL5b9RoUmtnUOyIqWdGhRcPVbMyaNeRk+LCzvoR+Z5s5EgDQgszcWq2tt+xEAC7PVxmtFHQG0LSGwWSB33ZhEjDJmo2k+qBlUivZjDn5tdLd9FZzatRncrlKN6UlgZKzba3ZiZkY6ZVq1Z04sQJUz6cw1WclfT111+LNGupg2GtC9eU4ZN3+PDhNG7cOGrevLm48f3y5cvTwIEDTdkHEHnBPKsLgNVBLidK40aTkWlP2Hjf56pjkaP0VQqVnApuY0Y1MNmQkeG/Y4XSM+OuAGxWw0d/FJUaZDNFYMzoDaFIvDyAbJFpGGnYxCObSaeZUee4QExdsI0em7GGKpZNo5Vjz6fEyWYiD+zUTNNUY+a1116j0aNH0yOPPCKEuunpnj1XKlWqFPR7vf766+IvF8LTp2gPHTpU3B81apQwnrhdAveF6tq1K82cORM1ZuKEFHN6aWYsLAD28My4JjdpuBh10g7XKNh/tICOFZaIyaZ+TvgruSrlMzz0I27PTKpmZHoIgGUF4Ji0M5DhOnM8M/pjHYmYGCQ+LPDmHmSta1cyEABHHjbhBYUmAFa6ZodjzCzddlgruOdPxxkrHD4qAMs5LZLEBVsaM5UrVxbCWn1TSfljlrh6zwSDvr+MEfyeXAGYbyD+yIGuN2Z4lWNZz4xywZRGjFo0z6zU7C0Hjou/7JIOVTOjwmEmtQpwgYFnxig1O5Z1ZoRmxvUd4ZkBwTL43b9pze48IXbv1KCKc6P0OKR4GjPSCxgKqv1jJAA2qqbti2Y1Kmj3dx85GfdQU4nrcOiNKqu3momaMTNo0CDKyMgQ4SGzBMDAOkjNggwhSNIs3DVb7SekL5DnkZqdGtkKZ8uBY+Jv42rO6tbhkpOV6dMzU85VyNBdNC+22UzSkyI8My6tjqnGDDwztoYNGebNuZvojcGnGTaalN6UcC7O6v8xqjOjZmwGQvWArNhxOO7GTKmSpWUcZrK3VzNkY2bVqlWiCnDLli2js0cgoTl60tkfp1LZdMMwkxXjslo6sTI5qcJA/SQabphpy0GnMdOoaqTGjPPY5+o1MywAdhkQ0uj0TM12xE4ArOxLRNlMumMt6xwBe/P7vwe8BcAmhE3UCzqPd1UzI7MEgw0zqUY69027oJ074zau2Uwpntvl+I9kUWEFQk6p6Ny5M2q3JDFyxV8h09MOlqsBOaCshJqBI/EomufVaDJCYyZCz0y2SzNzxNV4UU5SnC4vPTPqhC2NilgXzZOemYg0M/DMJO08IwXuckpxC4DD9zSo5xOPC1UzU72i0+MZrDGjvtdKpQlsoqVmZ7nKNQTrcUoazwynUt977700cuRIat++vZcAuEOHDmbuH0gwWOzGsIJfRdZrsKLITE6K6sSmemm8NTPhfcfNLs1Mo6qRleOv5Dr2emNGhJn0WiY1m6k4lu0MzNHMqIbayaJSeGZsjvydmXkb9tPlnep6XaQjCTPJ84nHN+vi1HHObUN25J4IOpSpjqe1rvBYIqZml3MtcNhrzvscblkI2xkz11xzjfirNpVkN3w4AmBgPfI0YybdNgLgQlfdGLW0uTrg5XwXSVYQj4+tZnlmXFV+j5wo9gjj8ErTKGXejMrFoTeaTDHVM8Pn28miAmhmbI66UNh15ISu0STpilc6Iu5ar+peNM9MkB6MQuVaJz3W8aRE0f6plFe8tdx1PiMt/LIQtjJmuPkjSF60MJPeM2NpAbCsoKt6ZnyHmcK5OLNYl3Us/F71q5Q3xZjJc3lm5EqWeyF5eWZSYysA1tpCKOGtiATArn1mT+D+/ALbx/2TGZ47VG+LNDwcrkozbmMmEs+MTGBwjhO9ZybcMBOfl7z/UjsYDwqVTEIVWcCSn+c5qLJN+7SGbMw0bNgwOnsCLEG+SwDsFWaytADY3elZ4lkB2DPMFM53lFVFszLSInbzuj0zMszkKmSoVACWOOvMxE4AXGjomYm8nYEUnAebNmsn+Dvf/+ly6tWyOl3V2b6Nc/Wp1vJcUhtDRto1W62WzaQqY756hYywjRkpTi/v0qfEg2Jl7OnhUFPhCXc/NzsS1JHnvkn9+vUT+hi+749LL73UrH0DCayZkboNL8+MBcNM7knAbcDINGxGbo3Ew+Grp1Ukxgx7yXjfNde5UmdGomYz8UqWb3o3dNTaGZjgmZGGmjSek9Ez89GCbfTdyt3iZmtjRmdsy/PaVzZTRJ4Z17lZooxlGWYK1mD2yrQrKiWXNj8uFCteUT0cauLFD4eZktqYufzyy0WrgRo1aoj7voBmxv7IyrIVMnWaGa35mwWNGW0SMPbMeLUzCOOCKkNBek1LOFRyGTNSw2RUZ8bIMyNXk/rXRK9onnmaGfmdk9EzI1tg2B39uNI0KUrFXn15/lAr70oDSY6Jk8pnVq0QomZGt7/BenSiH2ZK8XpOjvmk98yUKu4/9T5IPnyGmSycmq3VmVEMGI+ieV7tDEL/jnKCNMOY4f3IykgVrRF4taXWmSmb5p3NxK9lY5NXsnkni6JqzBRp3cfVOjMmGDNJ7JlJlu+s93j69sy4xymf00YtCXyhGv5641gKZcOpMyP+X5xDOMUG4XJJVhKkZ9szRwvEPjXbwiWzjSYBVURnRjsDWexNHwYyQzfjTl/29szw9+CVq3z94eNOYzSW7QyMPDPr9+QHlc7qFgAnr2cmFsLtRMCrD5frvNFXAFbDpKHq1/RhJtVwkWMzbM1MnM/NYh8C4GTxzARtzCxYsIB++OEHj21Tpkyhxo0bi/DTbbfdRgUFzl4xwJ6wWv9oof9sJisKgNVCb/48MxmRGDOaZ8ac9UMlJaPJIzXbyzPj3PnKmjHjLEQWizozbs1Mideke/7EedTvpd/oSADjysgzE0xPNzuhnm92Nmz0mhn528tsJjk81bEZujHj1peJx0pNGXnBD7rOTElihZmKZLjcwDMjvU7HbKyZCXpm5UaPK1as0B6vXLmSbr75ZjrvvPNEF+0ZM2bQ+PHjo7WfIAHggSCvI/p2BlYWAKsXYMPUbJeDOz2COjPSM2NGmMnLM6PUziibYdwzK7u8y5hxZUBFC3lseEKVhpt+kufwmGT5Dmfn4UAXH1UnFIt6OYmEqkOz88raK8zkGjNS2WDkmSkJMeTrHivOcVivSjnbeGaKZEFAA89MFsJMbpYtW0bnnnuu9viTTz6hrl270ttvv00jRoygl19+mT799NNY/GYgziEmVdxpizCT9Mz4CjO5NqsVgEP1DpwoNE8A7B1mctfO0FcBlr1nqsgWCFEPM7lXh1IkfqzAc5JX4/aBQk361GxVTJ0sqKvpE0llzHg+ljaMqpkJpnM2ewL35Z80DDMN7taQbj+7CX186xna2Az2GOv3N96/TbFBIkMyhZmCTorPzc0VXbIlc+fOpQsuuEB73KVLF/RsSqK+TF5t5stY15jRPDO+wkzSM6NMEjxxGMWmfSFXe9HVzDj3Lycrg3YePuHxnWSYKTfaYSbZGiKljBaK1FdHVVe+K3d697T5d99Reu3Xf6lJ9SzafeSk5ibnr8Knl/OC5OkZtDOqzsnOqbW+wkz6dgY890hBe6D5hhcdt0xZRHPW76fv7+nhVWeGjf8xF7YW97koozw/g8mSkvvH4VS+H/cwk0Eigz7MZOfzJ+gwExsysvpvYWEhLVmyhLp166Y9n5+f79WnCdg1k8n7d5Zpk9Y0ZryLTXmmZpNHmEn9P8EiXdBmaWbUKsB7XBf8yuWc3peqruJfqscsVmEmVUxdweXa5ole1c2oE+oKgwZ9Uxdsoy+X7qTnZm6gbYeOaxcMrddTknlmZHFEu6+sfXlmjELX0kgPpJmZuWavMGSYxdtyvbKZVFTxfDAZZNKYkWMx7mGmEt+p2bKYn53Pn6BnVvbCsDbmt99+ozFjxlD58uWpR48e2vOsp2natGm09hMkVF8mb4deJCXG4407NOKjaJ4umymc2ikno+SZ2Zt3kjbuPyrut6lTSfytmuU2ZtyemYzYZDNpIbsylJXp/q5qqEmd9NlY0YuSjxZ476MwZqRoM4KKwlZEtq2w+8XIq86MFADrKgB7GDMBFhXP/LBOu19QVOIlAFbhCtqhhIykdkuOxbiHmUq85zFvz4x9z5+gjZknn3ySUlNTqWfPnkInw7eMDPek+d5771Hfvn2jtZ8goQrmpfn2zFhSACxDI6pnxrjOjDRGQjUK3J4Zk4wZl6dlweZDIvRSrUIG1XBVMM3Jcv5Vu5lXdr3+yInCmDXtTFOOl2znYDShrt7lqZsxWhWrmVrJpplRvWl2DhN4p2aXeCyQVCmI7K3k71zgcb3pgLO5q1Hmnx7RgsM17oMJGRXoPTNxrgdUpNR4SsYwU9CamerVqwuvzJEjR6hChQrCsFH57LPPxHaQDDVm0v14ZshyaMK5AHVmmGoVM2j7oRN04GhBSN2vT5hszEhBrNSUtK2TrXmQ1DCT5pmRYaYYemYY1s3wd5fnjtEKVq/jMQojZaSmJqVnhi/IqvFn55W1ql3jMSmNhUKD0BCn6h86VugRgtOjD/vwa+UYMQozyTAwG1XBGDP6MFP8PTOlfjwzCDN5kZ2d7WXIMDk5OR6eGmBfzYy+L5OnANh61ozRJOApAHZT3VXynI2ZeLUzUCdQSVtXiEkKgPXZTNEsmrdq5xHq+eyvNGP5Lo9sJtWLp4qAvVK1dQJhmcauDzOVTULNjP5ibW9jxvm7ZrnOGWksFLi2q2059M1WjdB7+FSxvJFnRtXNBDJMWCAsPUlyPoxEM7Np/1H68K+topZXdDQzqQlhcEWT+LX4BNbNZjIwZqwtAPauM2M0ITDVXMbM/qOhhWvc2UzmCIAbVi3v8Zg9M0bGjPTMaKnZURAA/+eLFbT14HG6++Ol1LVxjvNzpWdGM2Z86z6O6lK3DT0zimbGyNixMr+u2yeyzwZ1beCVQaM3Pk/YOEwgL8Z8zkjDQxgNMmtIGZOy7lConhk5TxlpZhgZFg3k/XP2hSJPz0yYxgx/x3Oen6s1uzy/ba0I57EUP6nZ9j1/0M4ARNzKwPICYC2d2DibSdUByc66Mo0zWFh8aKZnpkn1CnR/nxba4/Z13caMKgBO9Qozma+ZUVd7MmQnj6XbmHG/Rr861Htm5IVE9QA6s5m8q7bagRsnLaSHv1olumPr0V+s1YKDdkNejN0d0ks8dDSqARKMZ0avp1E9M6phpOKuNeP/HFMTACINM6nlCXa7SiqYEeJNNgEwPDMgaORFR8Zf7SIANsoCUGvKqAZatTDDTJpnxsQmj3ed04xyKmSIi3sDxVOT4yebiS+GPBGrLvtIUQ00t6u7jEfIQIrHjSsCFxtehBpXr0DLtx92C4C1VbO9jBnJo9+spgGn1vM4R9RMpmQLM7FxoxokqgGilibwhd67wsaMFMdLAbHPMFMAL4tqzGgd3cM8L79YvMNrHo3EGExHajYA/lEbGuqRF00LSmYM3bOqYaOWk6/m8swcCNEzIydlX8LDcOCQxKCuDemmsxp7bK+qZjO5fhde7coIxmGTM5rU2jlykpfHUq6y1TBTsJ6ZhjnlDT0z8a7nYSZqajEbzTPX7PF4Xv9bJUuYSaJqrYyMmdA8M8V+s5kYqcsKaMy49pXHlzS+wvHMcIhpxord2mN9gcnwsjLLJKVnBmEmEDT+JgKZ8SNdnVZvNOnR/0XxzEgB8P5QPTOF5ntmfKFmM8lJl1d82gXAZBGw6uXhujce2UwGYSY5ocpJV9/uQBrN9XPKeVzIMm3omdGnI+867Dx+Ev1vZecwkzSEVWNGJh3w7696LYLyzLgMEvl+IjU7wKJCjk/ZGDbQvvJ+SZ1NOEY2n8uclSU5rhsLoVDs1zMDzQwAHgPPl2fG3ZvJHp4ZVYjZqJrbQ1C9YkZ42Uyy0aSJ4R1fyIlLv3J1tzQw15hRV3vyveWE6i/MJEN2+tWoFmaqVsHTmLGhZ0ZffFF/XslClRI7Z6PIccjzixx+UqenD4uGks1Uo1KmZjjK1/vMZgqy2aQ0Qtlo13Q24RgzOu9RJF2ti/y2M0jzaNVgR6CZAUEjLyKGBac0Y8Z61oyvSWDl2L5iQlTr6miamfzCoPq3SE7G0DOj7pM62deoWJa2HDxOu4+ELzI0wmh1LM8H4zBTsSam3pN30ivDQnoAOzWoTAO7NhBGGK/KtXYGdvLMBDBm1DHH39vO2ShyHMqQIhu1mmcmDGNGHruc8hm0NeW48LDKhpO+spmCNUzcfZlS3d6cMIwZfWaePuRqdmq2w+FcLMRiHoo1MGZA0Pir0SA9M6q+xHJ1ZnSVM9mIqah7rTRmeLJjl79RNWQjpDjQrGymYMlSxNpNa2TR31sOiUaOZqL3HhjVmVFDSW7PTIZxarZyrMZd0d5Lm2OnonkFAYwZ+TyLurlAop01D3IcZqSWEZ44pzFTbDjnBGXMSG9oeqp4PYdzpOfQd5jJ+TmBjrO7kB/XPwq+arDXPnqJ4UtMKP5Zxus5tY0Ke3/saMxAMwOCRos3G1yQZTjhuAXdmFoZ8CC6YPP3lKucUETAmmYmRsbM/waeSv3a1aIbz2ykbWta3Rm2MdOY4d/a0DOj08zkG7QzkIahuhrlomHyQqEPyWXasJ2BlzGTr6uG7LogV3bVCbKzMVOoaD7kHCMNZb1nJrg6M+5u8voik77CTFI8HyiMLMNMvF/B6myC+f0j8cwUaxWUDTSNKWXcITSbnkMwZoApAmBpzLAr12oXG7kiNCo2ZUSo6dl8wZerRF/ubbO5qENtev360zxCZM1rOv1M/+w7Sou35poiBObVqFHnYjmhujUz3tlMsmaPOoF71hXxNPzs6Znx/C76c0oadlLvZGdjRguTpLl7JKkC4JA1MzJEl56qGT8SX+OwVnZZ8Vd2og9FAGyGZyYSAXCRH80MU6mccyyqgmM7AWMmTH77Zz89NmM1fb1sJyUL/kryl1e2RZJeGA/kiobd28FQ2zXh/bXpYFCvd1YypZh6ZoxoVsPtmRnw+nwa8v7fEZVPZ/JOGP/W8uLj1sz4FgCrxowqiMxMAs+M5oVyXVwPHS/0SNdWw0zJkprt9MxIY6bY0PiQjVb5+PjSqsjQLp9H3p6ZVHOMGaX+UXjGjOe5bEZqdoaPRVnDHGcvua2HjpMdgTETJit2HKH3/9hCf/x7gJIFf5oZdmO69RHWmnD9dZs14trT64u/b83bFJR3Q71Ax1ozo1Inu6xHptOy7Yfp+1XuGhfhkKd4XCR84ZBeF0PNjAwzSc9MoTs0KT1YrMHSCxndnhn7GTM1K5Ullp3xYWCDRn/uyArOdk7N1owZRewts+D0F+gKGWniePlLz1Y71QcbZpILFRam+0OrJKyGmYqc7Rci8swUmhBmSvVhzLgKa25ROonbibgaM/PmzaNLLrmE6tSpIzIwvvrqK4/n+cQYO3aseL5cuXLUq1cvWr16NSUCyVCESE+gglNZma4JyGLGjDvMFJxn5tKOdallzYoinj/5zy0BXy9XbJzh46vnUyzgMaY3pp6fuSEijZO8kHAClUyiem9oZ22Cl2EmGS4wEgBzaFJeHNx1QLyPk5bNZKPUbPm92WMnvS+qbsatmUmMzszRpLDY4Q4zuX5/X9lMvHgKpJvRhORpbMx4CvV9zWG1KpXVQjH+spM0zUyq2zOjfma4GaKRGKtFWlsW43msUTWnZ2bLQRgzpnPs2DHq2LEjvfrqq4bPT5gwgV544QXx/MKFC6lWrVrUp08fys/Pp3hjdzGVX8+MD++Cpo+wnDHju9iUEew1uPXsJuL+9yt3Bz1hxTPEJKniuijK77H5wLGAq1B/yAsJ94b64v+60/zR59BpDZ3NJvVhJmk06QXA8vlABrP0zITb0C8RUbNijLRY8qIpG4Xyyt1qAvuwwkyu318KgI3CQoF0M27PTIrWzkPiaw7j95Tn2b68guDCTMq5Gur1QIbCjEKuYYfL04znsUZVXWGmgwgzmU6/fv3oySefpP79+3s9xwN24sSJ9NBDD4nn27VrR5MnT6bjx4/T1KlTKd4E28PDLqjda32taipaNszkf0VjxLmtaghjYN2efNoeIAYtzxFfE2gseXpAB+pYL5u+uvNMalrdObmt250fcZipUtl0OrVBFapT2V21Vw0zcSRP6gPk8VAzw6Tw0Z8uS3ouDobYsTyRUcMVRsaM9FRJY4aPo53CbEaVuFm7JucYLcxkMOcENmbc1X7V3mXOz0jx6b2sne08h/3VY1KNGQ7ryPcL9Xqg1cJxndts6IejY3M4HEqTV+N5DGGmOLF582bas2cP9e3bV9uWmZlJPXv2pPnz5/v8fwUFBZSXl+dxiwZylZ0sYSZ1Ai2b5J4ZpkpWBnVuWEXc/3nt3iCbTMZfotalUQ59fddZdEr9ytSqViWxbe2evIgFwDJTQg8bK3JyPXisQISU5IWAx5CsTBqMZ6ZamK0kEpnCEvl9U7Wwm4cxI7OZFI+a1cZXyGEmD8+McZhJGtD+w0xuz4wUvzMcDjWqxSKp6aoY7M9jWeh6b7lf4XoNZchUbUHC5S3CrZ7sTzMjw0wHjxUaat2sTvxnVx+wIcPUrFnTYzs/ls8ZMX78eMrOztZu9es7xZpmIydhO5VW94e/LBOrGzOBUhp90aeN89yctca/MaO5u01sMmkGrWpXjNwz47qQyAuL0UpXrgg37T/mIXBkQ6eCS2cly7i7Rebex6qGSzDMega1X5aVKTT0zLg9T6rhJz2f/voR2SfMlOqZzWRwga5T2alv4arW/uYsXnypxgxH6fxV7paeGX8ZTTL8J/dL6ncOK+LtYJDnO3uZpEPleBjzZ7FSed2XocZeUnmObT1gv1BTwhozEv1JF6iE/JgxY+jIkSPabfv27VHZr2ArRdoFucrhAefLjWnZMJPWbTa04XBOqxri78Ith/x+Z00zk2BVN1u7PDPr95gQZtJli6g0r+GubyNXrjyE2SjWG8CqzkEPu+L5/7EhkxviRcMXnI127vNz6Okf1lG8MwRlDyH1Iqp5qtJTgioUZ5s6MzoBsFFdmDa1nefvml15AcW1voxtf+nZXHHZ97566lPquAwgfaPQQKgLnSzXAjkcEXCRy6sVyMPc2NVnbtMBc6uAJwIJa8yw2JfRe2H27dvn5a1R4VBUpUqVPG7RoFy6u3FXMqCumH0Zk0ZNBa2AvzLg/mhcLYvqVSknJjauOfPvvnwa9tFieue3TR7ZO5oOJEE9Mxv3Hw27EJ0WZnIJfQPVt1ErIfN5lOWawKVmxp9nht3nUjsSaqNPX3y1bCdt3H+M3pi7MS7CWtUz0yDHeaHZpmiwNE1Nqju92PbGjEjNdhkzLiPXSOPS2mXMrN2dF1RjXDVU5w+Z0eTPM6NqnVQv0a7DofU9U6sUl5deyjAWg0WKZ8af9q9tnWzx9/d/7FdSJGGNmcaNGwuDZtasWdq2wsJCmjt3LnXv3p0SRgCcJJ4ZbZXjp4Kte5VtrWMSqD6DL/hifHaL6uL+vA376ZVf/qXvV+6hJ79bS/dNW669Tlbc9KUriRc8abMRwsbcP3vDW6nJC6s/z4w0ZjYqnhkp/M3STeCqJ8KI6lI3E0IriWBRwzuxwm2ssDEjs02OGWQQptjemPFoZ+AyEqR9aaSZaV3HaczsPHzCMLyj9/JJYzEQUiy8cucRnwauWgGYqe0Svvvz5gSqhSPnz3CMmWKtlUEZv5GL89s6nQQz1+zVjEe7EFdj5ujRo7Rs2TJxk6Jfvr9t2zbxgwwfPpzGjRtH06dPp1WrVtHQoUOpfPnyNHDgQIo3cjK2c0t1XzUbfKHpHywbZgrNM8Oc3dxlzPxzgBZsOqRtX7DpoJaVILMiZCw+UeAx1qmBU8Q8f2N4KzUW9arZGH49M/uPamFZuVr2DjP59sww1Sqa65lR9Sf/7I19yQfVWJHaIm6GKA0WNYNQGjO21cwUe4eZJEbnA4eO6uc4x9QaA++M1kLE9X/rB2nMnNG4qjCA2Egyel/1d+F9lQUpGf4/oeBuc6KGmYqjpvs7vXEOVc3KEOfXnxuDq2BuFeJqzCxatIg6deokbsyIESPE/UceeUQ8HjVqlDBohg0bRp07d6adO3fSzJkzqWJFfS/j+HlmRHaGzSxcIwKtmNU03KOFVg0zhT4cujerKsJTsl6LXBSxe3yza4W92xVHr+1yRScSvVo6jbE56/eH9f/3uTwkNSr6/m7c4JKPC3uoZBq7XAzoq0a7++n498zoGzKGi9x/ZkMcjBn3Ct+5MpcCzW0uUascd3xxt7tnRopYeTzpjRdftVP86WY0w9h1Lg06vYH421wRA/ua23u4FikzV+/1m4UmPTOyJIG/dO5AYSa3l7IkIvG0P7icxPntnN6Z6Uvt1YonrsYMV/Rlr4b+NmnSJG3lyBWAd+/eTSdPnhQhJq43kwioBdBOFiaBMeOnMqvVNTPuiSB0zwyvDi9oV1t7zLVWZMr28u2Hxd9drglOigQTiV4t3SJmVecTDDxWZWExmWnk6+JQ1zXZf7Fkp0cHb71nxl/LjGDTs/m9/vfrv0GVbd+X7w4LsEA53ouERrLk/MFjwrMnhaZ8cZdhSllIzm5oolqu26L7/X0bM04NCDdO9Z2a7ZyruzerRt/cdSZ9dke3gPvS15Wp+NPqPYaed1XrpHpdzRAAh9PSoDiEBdk1nZ0ZvtxXkBdhdiFhNTOJDp808uJ3vMiek4uKP2GmxKq9mcKpM6MyqKtzxSdXih3rV/YwZqSQUPZ9SSRYxMwXUL6QhNpnjI0GqYGRmTi+aOcSHrK2iOnaOMejpscu1zHyVzSPkT2fDvjRzNw0aSE9+9N6euLbNSF5ZsLVDUWCXnvR0FWllUXAHh3EVc+MCd3OExEtdKNoZiS+jNtzWzuN8dlr93kdFyPhfYd6lamyS0Tuj3Nb1xSGChfF/Gb5Lq/npfEtF7XSWA/UBsGfSDkSzWFRCKFynp+46CfbPxN/3kB2AcZMBMgJNxnSs/2lzEoqGHRItpJ7O9Q6MxK+MEuPQb/2tTRjZtkOp4BQigL11XETBZ64mc8X7wjp/0lDgI1YWXfJF+e388xAPL1xVfG3fhWnJ0KGnwL1/wrkmeFww9+bndql2ev2BfwOqpB4w778mOvf9Ct8tUqrWtspGcJMRu0MAnlm2tapRK1qVRSG3zfLd4actOAL1oDd3buZuP/YjDVeGi2umSQXAwx7zWToNJSMJnVelWGmcOrMFIW4ILuvTwvx9+tlu2i+TZolw5gxQwScBMZMMJ4ZKxbN44uXnAhCrTMj4XAou68n3diFujetRqfUcxoza3YdEW5cPnasGeHOyInIQJdniS/+obidgwkxeax0ZYGxsmniAqSKMnfkSmMmkADYfzbT+39s9uoL5TdMprzP4eNFQnwbS/RhNWnMbD103Ku2U9LUmWHNjM4z56/9wJWn1RP3P/57u4cxqk/NDpXbezYV5yl7W+7/dLkm6OfGtNKYkeJ2ZxuEwPVpfIfvlWrY4YSZSkILlberm02Dz2go7o+ZvtIWxV9hzJjRbNIGJ0IgAq2YrRpmUivJhqOZkbDXRepPOMOCa2CwkfTS7H80j4Kv1WW8Yf1K75bVRRrs279tCvr/Sb2JDP0E0hb1aF5Ny6jgrseqMcNp0awVCOQB1ATAPjwzO3Ldq2KuHusvJMM1cqRnRNbJCVXAGSn6fmfyeOzMPeFV28n+nhm3d0F+V4m/vmb9T60nFpaceSSrcbPhIY+t2ggyFHi8vnxdJ3Euzt2wnyb/uUVs3557QniCeLsML6meV7VOULDZTPxesqXBfj8NLn1RFEZ5iVEXtBTlGbjx5MSfnfOUlUnM2dUilHNZ0knlmQkimykcNX68kMK5cOrM+IIvPEO7N9TcuGrqZqJy29lNxd+pC7bR0Pf/pjs+WBww/Vl6R2oE6XEa1ruZyCQZ2r2xto0vWtKQ2H7I8wJuRN0q5YSXi40fI++MTBWX+Luw7D96UtsHWVvEX6G0aKBmKzHVstwtG/SF2exuzEiNEKc761P9fXlmGH7tjWc2EvdfmLVBGDJqL7lIGry2qFmRHrqwtbjPOixOvebij0yTahU0o5zp5Aovf7did1h1ZmRXaxZ/hx0qTwl+QVaxbDo9cbkzoYYXMYu3uktLWBEYMxFQznVhTwbNjOoODRRm4kkp3IqysUYtHBVOnRlfXHZKXY+Ko4lWY0ZPt6ZV6QJXQS1O0/5x9R4a/O7f9MLM9XTPx0tpimtVapyWHdgzw5zWsArNGtGTznJ5aCTSG8G6mUDZTHxBl20YuOqyHlmgUHpNt7vCV/7CZOxZ0qq++mkuGA20Hj+ucZXjWp2zt/fIiUKPY2HXOjNfLd1JZz3ziyIALiNqoaj48wgzt/VoKsKKLNj9buVuj/knXM+MZFDXhiJDkef5+6Yto9W7jojtar8n5qrO9YWh/fu/BzwKHwabmq3ppXz0mgpmHssI8btyf7mLO9QWHuqbJy+KS60ls4AxEwHJ1GwyGAFwltJ7yCreGbXbbLjZTEbwSutB14ouEav/GvHfS9qIVS7f+GLCZeJf/uVfkc3xyNeradEW98qNwzFc0TcUY8YXmgg497jHStWf4cXM1xX94hW51LxwV/BAnhnVGJN6pr0x9szoBcA8hqQXQqb5Sm+o1MxwDSO7NNr8cskOGj5tmUd4kL9/TojGTHb5dLq1RxNx/8WfN2j9jXiBEqnHlb0vTw/oIDzPLC6XIRm9McNGuaxPM2m+t/Hvv3+U2zPDBnmo3rcipQJwqEy4soMYL6wZ4wVMqIX/EgUYMyYUzksKz0wQAmCeNKSxYxXdjBTO8YqKC0qZydWd69M95zQTK82+bZxej0SG4/9zRvaiP8ecI2px3HxWY5F2LoXuD3+1Shwv9qD0fm6Oli0UjGbGH7KKq2eYyffU1K1JVUPPDF8A5EVeZpTJLCl/mp8acfTM6L8vhyjlhVyGvKRxo+pI7OKdMeoRxIsKTp9Wh2MwHgcONVUpny7Eua/+8k9QRlCwsOHyxvWneRgLRsX3ZLiLjRmuAh5qOwM5loL17ETakkUuyt8f2kV8Rz7/r3vrL61oo5WAMRMBEAB7k+Oq4eDvIpJIFMliU2FmMgViRN+WtOqx8+k8VxGuRIeFumywNqlegf57cRt66or29Md/zhEXCXbhf7l0J322eIfmHg9U/TcYtDBT7vGAFYCZ05vkiAsdZ16p2VcHXSEmDjc0qe6u1+KLPUecnhn2ytR0aZr2hCG+NNMzw0hjRmbFyAUEX+SlYSm7lVsdo+/B35MXFrKpaLDGDGtA/nNBKy2zKZJMJiM4PPrhLV1FbSQ2ME9p4DSYVXq3rCGyq1hMf88nSwNqsNwZV87v19jlnQm1mF2xSzPjT1vkjypZGfTBzaeL/lU8Zga8Md9nA89EBcaMKanZ1vBCREIwK2bmDFcIgNX/VvLMhFtjJhj8ebOsAE90/9fLKRB+efY/NG3hNi9RbiSwkJJZtv2wlhnorwcYG1xnudz5//1qlZaOe9AlWOYQmQxdcSE8X/otWQ+Es1BkWu2eOGUzqRchtzFzwsuws5sIWHZdr+jS26lZhWqoKdgxdE2X+nRFp7peBq5ZnNGkKs0d2Zt+H93bpw5u7KVthZdjb14B3TJloc+Kvnze6tPHG1VzpeaH6BkpLI58HuPv8/kd3UQ6Oovrr37zT1EZ3CrAmImAZCyaFygzgFcmzC9BFCxLBCKJNScTg89oJNLLWdvAkzTrByZecwqNvaSNVjgsXDhVm8XSPIGudvXYkWJyXzx2aVthWLPY8rNFOzzEv3wRbF8vW/xlt/lzP603fA+tzUTlcu4wU8yzmUq9xpXeM6MaOrYzZlyemd6tnPMGI7s+q8ZMsMJW/r/j+7fXejbJv2bP+/68kTw23hvSRez/qp15NPyTZVqNGhWPjCutzpAroylkz4wjolpZEs5MnHZ7N+rSqIoobXD9Owto9lrj/lSJBowZkzpn251gPTPcRZpdxNznxgqhJndzOwyFQPqwp/u31y4wvAK+vFNdGnqmO806XPhCdWF7Z38r1rywq5szn/zBBtT9fZ1VTJ/5cZ2oJyNX4VUrZIoLyjMDOojHb/+2WXh99EiBLXtlZJiJ+x7FstRCgR/PjDSsVENHaiq4Dk0iwjok9t6N/Wa15i3wh9T+sDarSbUsrRYRI+uuhJqlw8bGV3eeSY9e0oaevCI+vfw41f+twaeJ33Xmmr304PSVXgaNmjgiF8ZyYbByp7N6eLSK5vmDDeYpN3UVLQ/4/Lztg8X02SJn2C6RwQxuhmYmmVKzA3hmOKvgtAbOC9Gb8zaSVdzcUswNfMO6n4UPnUe/jepNY/o5tQlmcfkp7tDAyPNbBin4bCzc+WzEcHFC6ZmRab2cdtrfFXJ48ts1HhcHvpDIOjosfOYwh1ycxFIEbNSNXjNmXPuhLiC4GCMjPViJBF+sL33lD1HrhQWwwXhnZdNM9gjMvr8nTb7xdO05zzBTaJcqPn/4/ODGr/Gic6Mcev7qjkLf9cnC7V4GjdSd8eJPLqY4jMXnIS8Gf/LRsduIwgj7y+nh+fCNwadR/1PrigXGyM9X0NM/rEvoLDoYMxFQLqk8M4ErAEv+r7dTX/HhX9tEEbZEZv2ePJ+ZCcAbnnhZsGtWgUEJ1/Hgbr7XdqlPF7m8NIHgifuRi9uI+x8u2KoJFtWL4KgLWolFx6KtuaIDskR6PVh4ySEuDk/EI9TkTzMjUccc9yJiZK2TRAsZqYZgIP0RXxhl6xMunMi/gVqEjrVRkkStnh2ISzrWoRevOUUzaM5+9le66o35NO77tVo2nVoHh397ziJkJvy0LuhO9sVR0P7x+Hruyo50l6tH1RtzN9LtHyxO2HY11jxDEqzOTDJoZoINM0ndzL3nNhf3eTXy4V9bKVFZszvfY8UL4gNfxJ65soOo56Fe0ALBYQkOSbFR8MOqPV7GQK3ssnRLD+fF4bU5GzXvjKqXkRoNWQV41c7YGAq8L+6iee5xpS8Yl2FgzKzdnZ9wq2S9jkfte2XEUZdXRmYi6VF1U+Fm6SQCXECTDRpeCLDmbOGWXHpr3iZRpM4o4+qWHk3EOcAp5kPfXxiUPqo4SlmZPBYfOL8lvXTtKeI8/HntXrry9fkJKSGw7hmSAJTLSEnConnBhWOGn9dcq7nw369XaT1TEg25mocxY03YEJGGs5HWghnavZHwwKzYcYT++Pegh16mjpKR0rOFM0Nq9rq9MROfy8iXmq3D2WMq6nONq1UQnib2Boeavhtt9BddFooHI/7l72PkeVEbhZpVLyaeBg2XOJh22xn0/FUdhfZJtuPQz6msWZl80+nCW7V4ay5d8doftGm/s0BloArAaVHKyuT9533nJAAu0XDRy795eDoTAWufIXGmXDo8M/4uMhwC4I7MoubCx0tF9cxEgle26/fAM2N12DvT3VUSgMlx9TeSsCD42i7OzuBPfb9WeHF2a2nZ7qyU81o7awHxytlfg0qzkF4ZRr2Y+yvlz6v7VrUrJmSoiSvIqsgwSiDjx1d1bNnrjZHeMyvDXsKuTarSgNPq0Rd3dBdCd196Pe5q/clt3URPN/bQXP6/P/yWuyjSBMDRu6R3alCFvrnrTOrUoLLQOnHI6bEZqxOmdQ2MGTM0M0kUZgolds0TEKfQ8oqXV5LcwPCXGK16g4GrbPJ+8cUi0vRiED/4POMCf/rO2ip39m4mCv+xJ+6VX/7RwkxqrRDWArWoWUEYuXM2RL+0gCwQ6Ktoni+vRLs62T57UyWSZ8aoEaiRZ0bVxugv/naFQ5qf/183URNHalL0tKlTib5SjIch7/1Nj89YYxgJKNYEwNE1+jgs++nt3ei2s52tI97/Ywtd/r/5CdHTCcZMBMjsh2NJUDRPplD6mnh8wSuFNwefJlbPrC3iOPErs/8xrLsQa9hdyrSsVdH0VgYgtnCY8LmrOtKdvZtSa5fnQoXd+o9d5kzTfeWXf+n7lXsMC/5xBhTz7u+bo36OSs8M1zhSzz99KX+9MdOvnbM1xpdLdgbsbB5LDrvmCNkwMZBmRmYSyp5TRm0rOETICyI7wrVqWEvDJQ78vebjW8+gwWc0FI/f+2MzXfbqH7RkW65xvazU6F/SeU7nvnPvDe0sDG9eIFz8yu9x10bCmIkAuQLkFUgoNQGsBn83OVGpnaCDhWPC7w7pQtef4Qw5PT9rA90yZZFW4TReyEaJLWp6X/yA9eAy8iPPb+UzJHFpxzpapgh7EZpWz6ILXIaBZGj3xiJNm/U1ny92FuOLZSsDhg0b9ZzUl0PgRpsd62ULb+mkP4JraBjLBY/MDORUeX+1ZtyeGeMwE/+OXE13SHen9i5Z4fnzicvbCeOhWoUMWr83nwa8Pp9Gfracbpm8iPq+OFcYObGul3VOq5r04/AedHaL6uJc3BfjvmZ6YMxEgHSDssdB1kuwIxyKkZMSrxrDgSfsJy9vT88MaC8yE7gGRZ8X5tGUP7fELSuDewExMnYN7M9DF7YWzT+vO70BTb/zTC9PI3tw7j2vuZYam3usMGreD38ZglwV2VcmD1/kZXuJ9//YHDCcE+swE3d/lhW19/s5dtL4McpkAsbGw0/Dz9Z6P3GPNM4u2rDXLQ5OjbG2iD1Hk4Z2oRev6Uj36IT4sQbGTIQWM8fh41EGPZbkuoR9HI/NirC43DVdGtC395wl4sBcr+CRr1fTBRPniWynWHu3OE2SqRdhbyFgHTjVlJt/csl7XyHTG7o1Eo0qDxwtpE5PzKLOT/4szlGzU7YPuIwQWeLBlzFj1HSTu7Czd+ZYYQlN/HkDJQKHjxdq3lvuRM74W63LBaAvATDwhsXsHE7lzCLWIt5yVmOadGMX7XirgvZYjqkrOtWLSYjL737E9dNtQC2XgDDeIZPYTFIZpmQVsAv98zu60+OXtRUTH1e7vHXKIrrqjT9pUQwbm0nPjOzaDID0IspifKq+6o4PF3sVMePmlt+u2EUrd4Ru6MjsFNVwkZzeyL3NKFTDFxDWLTBT/96WEKUPpGcmu3wGVXcVIPSnmwlXhwdIZEVx+vbDF7ehXi1riOaXLMztf2q9pD08MGYixN1t176eGZlyWdmHUC8cWBfAK2AehOwyZ1c7V2m98o0/RRx4qU7gZjZcMXO3q9YIPDNAD18gWHj6QN8Won0DnyPsyXtw+ipNGMwGTLfxv9BdU5eKDsOynUKwcIiAObe1u8mihMv7S3wVTeMLmtShcemDGct3JYYxUy5Yz4xMzYYxY0Zm7emNc5I6kQHGTITUdE06ssOtHcl1eWaqhKmX8QdPfP+5oJUwariUPY9FnuSveG2+qDT53YrdQTWsCxUuu85VMzl0VtNPB1yQvLDw9K5zmgvP3QtXOyu4ssHAtWrYoJm2aJuWkcS6so+CzObg7I+bJy2kjfuPCW0JCyiN4MaeHetXpkFdnZksRjx6SVvq1dJZ+uDuj5eK/jnxSkaQix7VmPFXOE/LZoJnBpgAjJkISSbPDDeRjKaYmkvZz7zPKXBjI4M9NXdOXULdn/6Fxv+wVnhrzEqXlXoZbjIYSvl8kJzwqpeNC5m2ffPkhVq2EzfjY6b8tdWjBghrwrguyLnPz6Hf/nGGlNgwH/bREprtasLI7+vrYn7t6Q3o6zvP9FtvhbNX3r6hM919jrt/zmMzPJtqxgoZNmIPbpPqFTwqbPv3zEAzAyIHZ1GEyIlmd5zT0mKhmZFi52jSrEZFIXDjzskf/LmVpi3aLrI13py7Sdy4nPY5rarTua1r0pnNqnlUCQ0GnuS54dv/fv1XPIZeBgTLVZ3ri5DOw1+vol/X79fSisdd0Z7m/3tQePue+m6tSKNlo3vwuwto6bbD4nW3TVlM/xvUSfRUkm0ILmhbSxTzixQ2aO7v21LMRQ9NXyU6VnNVVs4ejGXYQQ0zcb8sZvG2XDHmjLR2MiwHzwwwAxgzpnlm7CwALopamMlf+I4bnHGa7Oy1e2nGit00b/1+kSb76aId4iYvJlxFc3C3hsIQ8gengN/7yVL6dsVubRv0MiAUru5Sn5rVrED9X5uvdUXmrMZx/dvRTZMW0Qd/bRXCcm4IyYYMZ/9xJVdukcDPSzibitPDzYTDUdzHadTny+njv7cLY2HClR2FcRFtuJw+Z1Yx/HlcKZZ1cDx3bDpwjJq6PDWS+RsP0L/7joowG+o8ATOAMWOSMWNvzUz0w0z+Vp0XtKstbuyiX7jlkNDUzF67j7YdOi7SOyf/uVXc2DBhjUHrWhVF6Ijrx3CbgnpVyosJ9uO/twlDhidQ2WWW6yQAEAqnNqhCs+47W4SZbnZ15OYaIOxNfPan9TRn/X5xY27o3kiEgJ77aQN9uGArZaam0HVdG9DVnetH5aBziJYNqHs/WUY/rd5Li7fOoYcuak2Xn1JXGBZcOZaztbo3rWaq10YVKbOgl9+7Y73K9PeWQ6JZomrMsKdmwo/rxX3u3WbntgUgdsCYMSk1O/9ksRjQsVgFxS/MFDvPjBE8CXNoiW+cOsuGzIodh2ny/C00b8MBoYPhG4uGVXhi5dLoq1yN+XhyZy/NlD+30kUdasfp2wAr07xmRRrjSo2WcMiIWw08P3MDfbdyt+gGzRWHuY7MI5e0odH9WoXc3ywc+rWvTTUqZdKoz1cIkfF905YLnc+2g07jX3qUXrrmFL96Ma6r8+KsDTTojAbCWAvGmOFO19JI6tTQacws2ZrrYbz99s8BWrb9sDg+d7m0PgBECoyZCGHNBq/+OQ7+yd/b6PaezsqcdkJrZZBAhhrH4Nlw7NG8urhx/Q8uQb98x2HauO+YWP1tPHCMduaeEKGp3/89oJVav/6MhsLjc0sPZ7M0AMyCha+vDuxEV66vJ6oJs8ZLEm0jRuW0hjn0w71n09u/bRKNNVftdApx2Vu56/AJkZXFc9cTl7U1LHbG8xk3Njx4rFCMnc/u6CYKtn22aLsoacCiZ04N9yrfoHhvuzbOETo37iHFiwYep8xrc5x6NQ6zwTMKzALGjAkM69WURn6+QmQSXHFq3YQZoByW+XvzITqlQeWQhbJGqdnhtjKIBVwSXXptjCbm3//ZLwp4cVO3WPYvAckHG9q9W3nXjok1bDyxt+iaLvXp4wXbhKHBBsSMFbtoxKesq9lGq3cdoQGn1hM9qmSZCfZa3v3xEmHIcFYht124/p0FwuMiQ86fL9lBI/q0oNvPbiKMoTnrndlZDXPc3ed7tqghRM4/rt4jDKOrTqtPVStk0F+bDon3vcUVogPADMo47NwhkdP/8vIoOzubjhw5QpUqVYpaAba+L84TQjeOV7Nug1dAnPbLB3fNrjwt/JQlPDnlRZVMFq9yfJmfY0U/pyiygM8MOO3xjg8W0/yNB6l+Tjl66dpOItYfDqc+MUuICbmpWKta0TmGAIDY8eOq3TR82jI6WeSu4VSrUlnRQZ7DP2yAcMjoqzvPpAc+W65lZbWpXUnMbfw8w806ueosh7F4jnht0Kl0YXt36Jazqjjc9fUyz4J+t53dRKtgDIAZ129LGDOvvfYaPfvss7R7925q27YtTZw4kXr06JEwxgyzfk8+jfx8uQh1RAJnAAjjply6MIx41cOCVfYm8EqrbHqKMHj4Lzegk9udz6VS2bQUSk1NoXd/20RbDjrL9TO8qrqxeyPq1KAKlc/k1/F7O2PbMmrO2ZOsi+W0Ul5dZrre88KXfxOrtb/GnAuxHgA2YW/eSRFu+n7lblriMlZUOAQ1uFsj4eF9fc5G4aEddUFLYeyw+PnJ79Z6CH958TZ3ZC/DsNWCTQdFuIlF+1d3qScEyWa0RgH2Js9Oxsy0adNo8ODBwqA588wz6c0336R33nmH1qxZQw0aNEgYY4ZhI2Dp9lzacuC4SM/k2DRPBO3qZtOJwhJhLBw6VkQ7clmIVyQqYPJfnhBYQGw2dbLL0nNXdxRpmmaUOl/3xAXCuAEA2AvWnG3Ymy96UPHCjPVx957Xwm/GE89b7OGZsZyNoVx66op2ouEgAGZhK2Oma9eudOqpp9Lrr7+ubWvdujVdfvnlNH78+IQyZiKBPR9cMZSraEpD51hBMRWXllJRiUP8ZcOI49dcZbSgqFSUUudt/Je387aTxfxcCTXIyaJ7z20u0qn5J/5x1R6atXavyGjg17Bxxb+8/PH5NXw/pUwZYXTxc/w+J8X7ltA5rWvSK9d1ivNRAgAAkCzkhXD9TmgBcGFhIS1evJhGjx7tsb1v3740f76zaJWegoICcVMPhhXgFRCHl6KR2s3uXE7X5BsAAABgNxI6rePAgQNUUlJCNWt61jjgx3v2OAVoethbw5acvNWvH53iVAAAAABIDBLamJHohWK+en0wY8aMES4pedu+fXuM9hIAAAAA8SChw0zVqlWj1NRULy/Mvn37vLw1kszMTHEDAAAAQHKQ0J6ZjIwMOu2002jWrFke2/lx9+7d47ZfAAAAAEgcEtozw4wYMUKkZnfu3Jm6detGb731Fm3bto3uuOOOeO8aAAAAABKAhDdmrrnmGjp48CA9/vjjomheu3bt6Pvvv6eGDRvGe9cAAAAAkAAkfJ2ZSLFKnRkAAAAAhHf9TmjNDAAAAABAIGDMAAAAAMDSwJgBAAAAgKWBMQMAAAAASwNjBgAAAACWBsYMAAAAACwNjBkAAAAAWJqEL5oXKbKMDuerAwAAAMAayOt2MOXwbG/M5Ofni7/169eP964AAAAAIIzrOBfPS+oKwKWlpbRr1y6qWLEilSlTxnSrkY2k7du3o7owjhHOqRiD8YdjhnPM3mPS4XAIQ6ZOnTqUkpKS3J4ZPgD16tWL6mfwj4ZWCThGOKfiA8YfjhnOMfuOyUAeGQkEwAAAAACwNDBmAAAAAGBpYMxEQGZmJj366KPiL8AxMgOcUzhW0QTnF46XXc8v2wuAAQAAAGBv4JkBAAAAgKWBMQMAAAAASwNjBgAAAACWBsYMAMBWcHHMr776Kt67AQCIIUltzMybN48uueQSUV3QaALcu3cvDR06VDxfvnx5uuCCC+iff/7xeM2ePXto8ODBVKtWLcrKyqJTTz2VPv/8c4/XPPXUU9S9e3fxHpUrVyarw8eEj9cdd9zh9dywYcPEc/wagGNl1vl2+eWX43Tyw759++j222+nBg0aiEwSno/OP/98+vPPP3HcfMxfTz/9tMd2nv/NrhJvRebF4Lq4ZcsWuvnmm6lx48ZUrlw5atq0qciCKiwsDHu/k9qYOXbsGHXs2JFeffVVr+c4yYsn0E2bNtHXX39NS5cupYYNG9J5550n/p+Ef7D169fTN998QytXrqT+/fvTNddcI14v4R/oqquuov/7v/8ju8Alqz/55BM6ceKEtu3kyZP08ccfiwk1EoqKishORPNYAcAMGDCAli9fTpMnT6YNGzaI+ahXr1506NAhHCADypYtS8888wzl5ubi+MThurhu3TrRaujNN9+k1atX04svvkhvvPEGPfjggxQ2nJoNRHq6Y/r06dqhWL9+vdi2atUqbVtxcbEjJyfH8fbbb2vbsrKyHFOmTPE4hPyad955x+uwvv/++47s7GzLH+4hQ4Y4LrvsMkf79u0dH374obb9o48+Etv4OX4N88MPPzjOPPNM8b35uFx00UWOf//9V/s/mzdvFsd52rRpjp49ezoyMzMd7733nsMumHmsevfu7bjzzjs93v/AgQOOjIwMx+zZsx12RR5DpmHDho4XX3zR4/mOHTs6Hn30UZ9j2e7k5uaK7zxnzhyfrzl8+LDj1ltvdVSvXt1RsWJFcS4tW7ZMe56PHx/HN954w1GvXj1HuXLlHFdeeaV4bzueTxdffLGjVatWjpEjR2rb+ZxRL4mff/65o02bNmJ88Xn33HPPac+NHj3a0bVrV6/35jH9yCOPOOwCxeC6KJkwYYKjcePGYe9rUntm/FFQUKBZ8JLU1FTKyMig33//Xdt21lln0bRp08QKiC1NXoHz/+VVkd258cYb6f3339cev/fee3TTTTd5vIat9REjRtDChQtp9uzZolfWFVdcIY6Vyn/+8x+65557aO3atcI9bjfMOFa33HILTZ06VTs3mY8++ki4e3v37h3DbwMSiQoVKogbhwPUc0PC16SLLrpIuP6///57Wrx4sXD7n3vuuR6em3///Zc+/fRTmjFjBv3444+0bNkyuvPOO8mO8Fw+btw4euWVV2jHjh1ez/Mxuvrqq+naa68VnoWxY8fSf//7X5o0aZJ4ftCgQbRgwQLauHGj9n/Yw8Cv5efsSkEUr4tHjhyhnJyc8HcubDPIZugt0MLCQmGNX3XVVY5Dhw45CgoKHOPHjxev69u3r8eK5/zzzxfb09LSHJUqVXLMnDnT8DPs5pnZv3+/8KSwd2XLli2OsmXLim2qt0HPvn37xLFauXKlh2dm4sSJDjti5rE6efKkWN2wF0tyyimnOMaOHeuwM/DMBIa9CFWqVBHnVffu3R1jxoxxLF++XDzHXjuel/j8UWnatKnjzTff1Dwzqampju3bt2vPs6cwJSXFsXv3boddz6czzjjDcdNNN3l5ZgYOHOjo06ePx/9jLw57aiQdOnRwPP7449pjPuZdunRx2AmKwXWRYQ80v0b17oQKPDM+SE9Ppy+++ELEn9laZKHTnDlzqF+/fsISlTz88MMi7vrzzz/TokWLxMqa9TFsodudatWqiRUfx+nZ68D3eZsKr1wGDhxITZo0EV1UWfDFbNu2zeN1nTt3JjtjxrFiYef1118vvDoMr5xZJwGxNWDNzK5du4RGgT2bPFex94U9CexlOHr0KFWtWlXz4vBt8+bNHp4F1m/Vq1dPe9ytWzexqmbtg11h3QyPyTVr1nhsZw/xmWee6bGNH7PQtaSkRDxmDwx7Rhm+7rMGzs5emWhdF/m8ZRExP8/e53BJC/t/JgGnnXaauGCw+4tFvNWrV6euXbtqF16eCFgktWrVKmrbtq3YxsKp3377jf73v/8JQZPd4VDJXXfdJe7zd9bDqngWwL799tsiHMKTY7t27bxU66x4tztmHCse7KeccopwjbNRw6ECFuAlCxx603dgsZtgPFzY9d+nTx9xe+SRR8S5whkinGFYu3ZtcdHR4y+7Umb22DnD5+yzzxbGHwtP1UUBn2P6760/73jhMXr0aFqyZIkQ92/fvl2EpezOaSZeF9mQ4RA5G85vvfVWRPsFYyYIsrOzxV+2ytnKfOKJJ8Tj48ePaxOsCluoek2IXWGLWl5s9VqXgwcPihUOK9Z79Oghtqlx1WTDjGPVvn17MWmwwcP6GY75JxM8ce7evVt7nJeXJzwMwJs2bdoIHQ17aFgvk5aWRo0aNfJ5qNgDyBcXNqQZTuvmua1Fixa2Prycos0LBPV78rHTj7/58+eL10gPBHux2Bhi7wwbM5zRU7NmTUoWsiO8Lu7cuVMYMmwcsbda//pQSWpjhl2vLHqT8KTIFie7z9jl+tlnn4nJk++ze+zee+8VaWl9+/YVr2/VqhU1a9ZM1Hd47rnnhBuXJ49Zs2bRt99+6zFJsBCK/7KLkj+D4f/L7l4rwycoX4TlfZUqVaqIY8IWN68M+fvzSiZZMetY8YqbPTzs4mWBcDJxzjnniNAJe7H4mLEoU38skw02hNlFz56/Dh06UMWKFcXFZcKECXTZZZeJiyyvfHnu4rBKy5YthdHCYmDeJlfU7NkZMmSImMvYSGRBPotguVaIneEFAoeH1IXB/fffT126dBEXaE4pZsOOvQ2vvfaax//l/8fiYF6kcHqxHTgag+sin38sBub34Nfs379f+7ywzzdHEvPrr78KgZL+JgWZL730kkhTTE9PdzRo0MDx8MMPC8GTyoYNGxz9+/d31KhRw1G+fHkhCtOnpPH7GX0Of77VBXRGqKLWWbNmOVq3bi3Er3xsOH1UFZVJAfDSpUsddsTMYyXJz88X59qwYcMcycDgwYMdAwYMEPePHDniuPrqq4VYsH79+o5JkyYlfWo2C3s5VfjUU08VCQZ8brRs2VLMV8ePHxfHLS8vz3H33Xc76tSpI+YzPnaDBg1ybNu2zSM1+7XXXhOvYSExz2ss8kyGMcmifB53RqnZcv5/9tlnvd6LU9f5//Ex53FpB36NwXWRk2GMPiMSk6QM/xOpJQcAiB0cm+dwAadwcwghGcJzvNIzKuIFzIG9C7x6ll5jAKwGspkAsAgsdOXwE9fkOeOMM2xvyHA2xHfffSeEqxwqAQAAXyS1ZgYAK/HHH38IwRyLEPX9v+wIa0DY+8T6BdZ+AACALxBmAgAAAIClQZgJAAAAAJYGxgwAAAAALA2MGQAAAABYGhgzAAAAALA0MGYAAAkJp2Rzf5zDhw/He1cAAAkOspkAAAkBlzfnHjkTJ04Uj7lEPLcB4X43dm52CACIHNSZAQAkJBkZGbbvCwQAMAeEmQAAcWfo0KE0d+5ceumll4QXhm/cUFINM/HjypUri2Z13CyRG21eeeWVdOzYMZo8ebJo8cDNJ++++27R0FXCHp5Ro0ZR3bp1KSsri7p27SpCWAAA+wDPDAAg7rARs2HDBmrXrh09/vjjYtvq1au9Xnf8+HF6+eWX6ZNPPqH8/Hzq37+/uLGRw12gN23aRAMGDKCzzjpLdDtmbrzxRtqyZYv4P3Xq1KHp06eLfk/c8bd58+Yx/64AAPOBMQMAiDvZ2dkirMTeFhlaWrdunWF/qtdff52aNm0qHrNn5oMPPqC9e/dShQoVqE2bNqLlw6+//iqMmY0bN9LHH39MO3bsEIYM88ADD9CPP/5I77//Po0bNy7G3xQAEA1gzAAALAMbO9KQYVgczOElNmTUbfv27RP3lyxZQg6HQ/SzUikoKKCqVavGcM8BANEExgwAwDKkp6d7PGZNjdG20tJScZ//pqam0uLFi8VfFdUAAgBYGxgzAICEgMNMqnDXDDp16iTekz01PXr0MPW9AQCJA7KZAAAJAYeLFixYIMS6Bw4c0LwrkcDhpUGDBtENN9xAX375JW3evJkWLlxIzzzzjBAMAwDsAYwZAEBCwMJcDgWxiLd69eq0bds2U96Xhb5szNx///0ipfvSSy8VRlP9+vVNeX8AQPxBBWAAAAAAWBp4ZgAAAABgaWDMAAAAAMDSwJgBAAAAgKWBMQMAAAAASwNjBgAAAACWBsYMAAAAACwNjBkAAAAAWBoYMwAAAACwNDBmAAAAAGBpYMwAAAAAwNLAmAEAAACApYExAwAAAACyMv8P8Ex06Ta8yjgAAAAASUVORK5CYII=", "text/plain": [ "
" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "ds_out[\"q\"].isel(subbasin_id=0).plot()" ] }, { "cell_type": "markdown", "id": "31", "metadata": {}, "source": [ "## Retrieving additional outputs\n", "\n", "The `output_config` allows users to specify which variables to output. It is thus easy to retrieve additional variables by simply updating the configuration and re-running the model." ] }, { "cell_type": "code", "execution_count": 22, "id": "32", "metadata": {}, "outputs": [], "source": [ "# \"Couvert nival\" is the snow water equivalent\n", "hm.update_config(output_config={\"COUVERT_NIVAL\": \"1\"})\n", "hm.run(overwrite=True, return_streamflow=False)\n", "clear_output(wait=False)" ] }, { "cell_type": "markdown", "id": "33", "metadata": {}, "source": [ "The `.get_outputs()` function can be used to retrieve any of these variables as a `xarray.Dataset`." ] }, { "cell_type": "code", "execution_count": 23, "id": "34", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Help on method get_outputs in module xhydro.modelling._hydrotel:\n", "\n", "get_outputs(output: str, return_paths: bool = False, **kwargs) -> xr.Dataset | Path | list[Path] method of xhydro.modelling._hydrotel.Hydrotel instance\n", " Get the outputs of the simulation.\n", "\n", " Parameters\n", " ----------\n", " output : str\n", " \"path\" to return the output directory.\n", " Otherwise, the name of the output to retrieve, or \"q\" for the streamflow.\n", " This should match the name of the output file without the extension (e.g. \"neige\" for \"neige.nc\").\n", " return_paths : bool\n", " If True, return the path to the output file(s) instead of the dataset. Default is False.\n", " \\*\\*kwargs : dict\n", " Keyword arguments to pass to :py:func:`xarray.open_dataset`.\n", "\n", " Returns\n", " -------\n", " xr.Dataset\n", " The requested output variable.\n", " Path\n", " The path to the output directory if output is set to \"path\".\n", " list[Path]\n", " The path to the output file(s) if return_path is True.\n", "\n" ] } ], "source": [ "help(hm.get_outputs)" ] }, { "cell_type": "code", "execution_count": 24, "id": "35", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "[PosixPath('/tmp/tmpbn030vdz/hydrotel_demo/simulation/simulation/resultat/couvert_nival.nc'),\n", " PosixPath('/tmp/tmpbn030vdz/hydrotel_demo/simulation/simulation/resultat/debit_aval.nc')]" ] }, "execution_count": 24, "metadata": {}, "output_type": "execute_result" } ], "source": [ "files = hm.get_outputs(\"*\", return_paths=True)\n", "files" ] }, { "cell_type": "code", "execution_count": 25, "id": "36", "metadata": {}, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "
<xarray.Dataset> Size: 791kB\n",
       "Dimensions:                  (time: 364, unit_id: 495)\n",
       "Coordinates: (12/14)\n",
       "  * time                     (time) datetime64[ns] 3kB 1981-01-01 ... 1981-12-30\n",
       "  * unit_id                  (unit_id) <U3 6kB '1' '2' '3' ... '493' '494' '495'\n",
       "    dowsub_id                (unit_id) <U3 6kB dask.array<chunksize=(495,), meta=np.ndarray>\n",
       "    station_id               (unit_id) <U7 14kB dask.array<chunksize=(495,), meta=np.ndarray>\n",
       "    subbasin_id              (unit_id) <U3 6kB dask.array<chunksize=(495,), meta=np.ndarray>\n",
       "    lon                      (unit_id) float64 4kB dask.array<chunksize=(495,), meta=np.ndarray>\n",
       "    ...                       ...\n",
       "    unit_centroid_latitude   (unit_id) float64 4kB dask.array<chunksize=(495,), meta=np.ndarray>\n",
       "    drainage_area            (unit_id) float64 4kB dask.array<chunksize=(495,), meta=np.ndarray>\n",
       "    subbasin_drainage_area   (unit_id) float64 4kB dask.array<chunksize=(495,), meta=np.ndarray>\n",
       "    unit_drainage_area       (unit_id) float64 4kB dask.array<chunksize=(495,), meta=np.ndarray>\n",
       "    subbasin_elevation       (unit_id) float64 4kB dask.array<chunksize=(495,), meta=np.ndarray>\n",
       "    unit_elevation           (unit_id) float64 4kB dask.array<chunksize=(495,), meta=np.ndarray>\n",
       "Data variables:\n",
       "    couvert_nival            (time, unit_id) float32 721kB dask.array<chunksize=(364, 495), meta=np.ndarray>\n",
       "Attributes:\n",
       "    description:              Variable de sortie simulation Hydrotel\n",
       "    creation_time:            01-04-2026 12:59:08\n",
       "    HYDROTEL_version:         4.3.6.0000\n",
       "    HYDROTEL_config_version:  4.3.1.0000
" ], "text/plain": [ " Size: 791kB\n", "Dimensions: (time: 364, unit_id: 495)\n", "Coordinates: (12/14)\n", " * time (time) datetime64[ns] 3kB 1981-01-01 ... 1981-12-30\n", " * unit_id (unit_id) \n", " station_id (unit_id) \n", " subbasin_id (unit_id) \n", " lon (unit_id) float64 4kB dask.array\n", " ... ...\n", " unit_centroid_latitude (unit_id) float64 4kB dask.array\n", " drainage_area (unit_id) float64 4kB dask.array\n", " subbasin_drainage_area (unit_id) float64 4kB dask.array\n", " unit_drainage_area (unit_id) float64 4kB dask.array\n", " subbasin_elevation (unit_id) float64 4kB dask.array\n", " unit_elevation (unit_id) float64 4kB dask.array\n", "Data variables:\n", " couvert_nival (time, unit_id) float32 721kB dask.array\n", "Attributes:\n", " description: Variable de sortie simulation Hydrotel\n", " creation_time: 01-04-2026 12:59:08\n", " HYDROTEL_version: 4.3.6.0000\n", " HYDROTEL_config_version: 4.3.1.0000" ] }, "execution_count": 25, "metadata": {}, "output_type": "execute_result" } ], "source": [ "snow = hm.get_outputs(\"nival\")\n", "snow" ] }, { "cell_type": "code", "execution_count": 26, "id": "37", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "[]" ] }, "execution_count": 26, "metadata": {}, "output_type": "execute_result" }, { "data": { "image/png": "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8Td//fXXHrcpLy9X/vznPys5OTlKSkqKOJ7Wrl2r/Zz3H+/H559/XunatauSmJioXHzxxeK+ZTyezj33XKV///7KX//6V+12PmYcT5vvvfeeMmDAAPEa4+Puscce03525513KiNGjDjqvvl1ff/99yuyoBCcF1WPPvqo0rNnT78eJzI7AWhoaNA+AahiYmLIYrHQd999p9126qmn0ttvvy0+QXGkyp/i+f/ypyrZXX311fTKK69o37/88st0zTXXOG3D0f706dNp1apV9OWXX4q1yi688EKxrxz97W9/o1tvvZU2b94s0u8y0WM/XXfddfTmm29qxyV74403RCp5zJgxIfxrINwkJyeLLx5ucDw+VHzOOuecc8TQwpIlS2j16tViWGHs2LFOmZ/t27fTO++8Qx9//DF99tlntHbtWrrppptIRvxePmfOHHr66adp//79R/2c99GUKVPosssuE5mJWbNm0X333Uevvvqq+PkVV1xBP/30E+3YsUP7P5yh4G35Z7JqCOJ5saKigjIzM/17YH6FSBHKNYJtbGwU0fwll1yilJaWKg0NDcrcuXPFdhMmTHD6xHTmmWeK22NjY5XU1FRl6dKlbn+HbJmdI0eOiEwMZ2d2796tJCQkiNscMxauioqKxL7asGGDU2Zn3rx5imz03E/19fXikxFnwFRDhw5VZs2apcgOmZ2OcRYiIyNDHFsjR45U7rrrLmXdunXiZ5z54/clPoYc9e7dW/nXv/6lZXZiYmKUffv2aT/nbGN0dLRSWFioyMTxeDrppJOUa6655qjMzuWXX66MHz/e6f9xFogzParBgwcrDz74oPY97/MTTzxRkQmF4LzIOIvN2zhmh3yBzE4A4uLi6P333xfj3xxtciHW119/TRMnThSRrOree+8V475ffPEF/fLLL+LTOdfncIQvu+zsbPGJkesEOHPB1/k2R/zJ5/LLL6devXqJVXC5II3t3bvXabvhw4eTrPTYT1x0euWVV4qsEONP3VyjgUJwUGt2Dh48KGokODPK71WcveFMBGcpqqurKSsrS8sC8deuXbucMhNcQ9a1a1ft+5NPPll8KufaC1lx3Q6/Ln/77Ten2znDfMoppzjdxt9zIW5LS4v4njM4nF1lHBdwHZ7MWZ1gnRf5uOUiZ/45Z7D9EevX/wLNsGHDxEmF02tcZJyTk0MjRozQTsz8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", "text/plain": [ "
" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "snow[\"couvert_nival\"].isel(unit_id=0).plot()" ] }, { "cell_type": "markdown", "id": "38", "metadata": {}, "source": [ "A few important notes regarding these additional outputs:\n", "- There is currently no standardization of the variable names or their units.\n", "- In an effort to standardize the outputs across different models, the following aggregation levels have been defined. These are noted in a `aggregation_level` attribute in the variable's metadata, and can be used to identify the spatial resolution of the output:\n", " - `ComputationalUnit`: In HYDROTEL, this corresponds to the Relatively Homogeneous Hydrological Units (RHHUs).\n", " - `Subbasin`: Following the Raven convention, this corresponds to the immediate drainage area of a river segment, excluding the upstream drainage area.\n", " - `DrainageArea`: This corresponds to the cumulative drainage area of a river segment.\n", "\n", "With one exception which is at the subbasin level (`APPORT LATERAL`), all additional outputs in HYDROTEL are provided at the computational unit level. The `aggregate_outputs` function has thus been implemented in `xHydro` to allow the aggregation of outputs in post-processing, if needed. Note that this function relies on multiple watershed properties which are deduced from the model's files." ] }, { "cell_type": "code", "execution_count": 27, "id": "39", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Help on method aggregate_outputs in module xhydro.modelling._hydrotel:\n", "\n", "aggregate_outputs(\n", " to: Literal['subbasin', 'drainage_area'],\n", " subset: list[str] | None = None,\n", " **kwargs\n", ") -> None method of xhydro.modelling._hydrotel.Hydrotel instance\n", " Aggregate the model outputs to a different spatial unit. See the Notes section for more details.\n", "\n", " Parameters\n", " ----------\n", " to : {\"subbasin\", \"drainage_area\"}\n", " The spatial unit to aggregate to.\n", " subset : list[str] | None\n", " The list of variables to aggregate. If None, all variables will be processed.\n", " The strings should match the names produced by the HYDROTEL model.\n", " \\*\\*kwargs : dict\n", " Keyword arguments to pass to :py:func:`xarray.open_dataset`.\n", "\n", " Returns\n", " -------\n", " None\n", " The aggregated outputs will be saved as new NetCDF files in the output directory, with a name pattern\n", " roughly following what is produced by HYDROTEL (e.g. \"variable}_By{aggregation}.nc\").\n", " Aggregation will be 'BySubbasin' or 'ByDrainageArea', depending on the 'to' parameter.\n", "\n", " Notes\n", " -----\n", " Unlike Raven, HYDROTEL always produces output files at the RHHU level, which is the finest spatial unit in the model.\n", " Therefore, unlike its Raven variant, this method does not need a 'by' parameter to specify the spatial unit of the input files.\n", " Furthermore, this method expects that the 'standardize_outputs' method has been called beforehand to ensure that the output\n", " files are in a consistent format and contain the necessary spatial information for the aggregation.\n", "\n" ] } ], "source": [ "help(hm.aggregate_outputs)" ] }, { "cell_type": "code", "execution_count": 28, "id": "40", "metadata": {}, "outputs": [], "source": [ "hm.aggregate_outputs(to=\"drainage_area\")" ] }, { "cell_type": "code", "execution_count": 29, "id": "41", "metadata": {}, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "
<xarray.Dataset> Size: 589kB\n",
       "Dimensions:        (time: 364, subbasin_id: 196)\n",
       "Coordinates:\n",
       "  * time           (time) datetime64[ns] 3kB 1981-01-01 ... 1981-12-30\n",
       "  * subbasin_id    (subbasin_id) <U3 2kB '1' '2' '3' '4' ... '194' '195' '196'\n",
       "    dowsub_id      (subbasin_id) <U3 2kB dask.array<chunksize=(196,), meta=np.ndarray>\n",
       "    station_id     (subbasin_id) <U7 5kB dask.array<chunksize=(196,), meta=np.ndarray>\n",
       "    lon            (subbasin_id) float64 2kB dask.array<chunksize=(196,), meta=np.ndarray>\n",
       "    lat            (subbasin_id) float64 2kB dask.array<chunksize=(196,), meta=np.ndarray>\n",
       "    drainage_area  (subbasin_id) float64 2kB dask.array<chunksize=(196,), meta=np.ndarray>\n",
       "Data variables:\n",
       "    couvert_nival  (time, subbasin_id) float64 571kB dask.array<chunksize=(364, 196), meta=np.ndarray>\n",
       "Attributes:\n",
       "    description:              Variable de sortie simulation Hydrotel\n",
       "    creation_time:            01-04-2026 12:59:08\n",
       "    HYDROTEL_version:         4.3.6.0000\n",
       "    HYDROTEL_config_version:  4.3.1.0000
" ], "text/plain": [ " Size: 589kB\n", "Dimensions: (time: 364, subbasin_id: 196)\n", "Coordinates:\n", " * time (time) datetime64[ns] 3kB 1981-01-01 ... 1981-12-30\n", " * subbasin_id (subbasin_id) \n", " station_id (subbasin_id) \n", " lon (subbasin_id) float64 2kB dask.array\n", " lat (subbasin_id) float64 2kB dask.array\n", " drainage_area (subbasin_id) float64 2kB dask.array\n", "Data variables:\n", " couvert_nival (time, subbasin_id) float64 571kB dask.array\n", "Attributes:\n", " description: Variable de sortie simulation Hydrotel\n", " creation_time: 01-04-2026 12:59:08\n", " HYDROTEL_version: 4.3.6.0000\n", " HYDROTEL_config_version: 4.3.1.0000" ] }, "execution_count": 29, "metadata": {}, "output_type": "execute_result" } ], "source": [ "snow_agg = hm.get_outputs(\"nival_ByDrainageArea\")\n", "snow_agg" ] }, { "cell_type": "markdown", "id": "42", "metadata": {}, "source": [ "## Model calibration\n", "\n", "
WARNING\n", " \n", "Only Raven-based models are currently implemented.\n", "\n", "
" ] } ], "metadata": { "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.14.3" } }, "nbformat": 4, "nbformat_minor": 5 }