08_4_Developing a Sequence-to-Sequence Model__M2.ipynb

{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "4a934e05-f1c9-439a-bd3a-73ee0b9d7d4f"
      },
      "source": [
        "<p style=\"text-align:center\">\n",
        "    <a href=\"https://skills.network\" target=\"_blank\">\n",
        "    <img src=\"https://cf-courses-data.s3.us.cloud-object-storage.appdomain.cloud/assets/logos/SN_web_lightmode.png\" width=\"200\" alt=\"Skills Network Logo\">\n",
        "    </a>\n",
        "</p>\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "6f37a590-1558-420f-bd94-8685e20ccf6d"
      },
      "source": [
        "# Sequence-to-Sequence RNN Models: Translation Task\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "5fcf47af-54dd-437e-9d88-c54294aa7899"
      },
      "source": [
        "Estimated time needed: **60** minutes\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "787ac050-69e1-45e0-bd02-bcdbe31ac9c8"
      },
      "source": [
        "In this hands-on guide, you will explore the fundamentals of sequence-to-sequence models and learn how to implement an RNN-based model for a translation task using PyTorch.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "739017fd-e86a-41d7-a3be-30ee5fe385b6"
      },
      "source": [
        "## __Table of Contents__\n",
        "\n",
        "<ol>\n",
        "    <li><a href=\"#Objectives\">Objectives</a></li>\n",
        "    <li>\n",
        "        <a href=\"#Setup\">Setup</a>\n",
        "        <ol>\n",
        "            <li><a href=\"#Installing-required-libraries\">Installing required libraries</a></li>\n",
        "            <li><a href=\"#Importing-required-libraries\">Importing required libraries</a></li>\n",
        "        </ol>\n",
        "    </li>\n",
        "    <li>\n",
        "        <a href=\"#Background\">Background</a>\n",
        "        <ol>\n",
        "            <li><a href=\"#History-of-sequence-to-sequence-models\">History of sequence-to-sequence models</a></li>\n",
        "            <li><a href=\"#Introduction-to-RNNs\">Introduction to RNNs</a></li>\n",
        "            <li><a href=\"#Sequence-to-sequence-architecture\">Sequence-to-sequence architecture</a></li>    \n",
        "        </ol>\n",
        "    <li><a href=\"#Encoder-implementation-in-PyTorch\">Encoder implementation in PyTorch</a></li>\n",
        "    <li><a href=\"#Decoder-implementation-in-PyTorch\">Decoder implementation in PyTorch</a></li>\n",
        "    <li><a href=\"#Sequence-to-sequence-model-implementation-in-PyTorch\">Sequence-to-sequence model implementation in PyTorch</a>\n",
        "    <li><a href=\"#Training-model-in-PyTorch\">Training model in PyTorch</a></li>\n",
        "    <li><a href=\"#Evaluating-model-in-PyTorch\">Evaluating model in PyTorch</a></li>\n",
        "    <li><a href=\"#Data-preprocessing\">Data preprocessing</a></li>\n",
        "    <li><a href=\"#Training-the-model\">Training the model</a></li>\n",
        "    <ol>\n",
        "        <li><a href=\"#Initializations\">Initializations</a></li>\n",
        "        <li><a href=\"#Training\">Training</a></li>\n",
        "    </ol>\n",
        "    <li><a href=\"#Model-inference\">Model inference</a></li>\n",
        "    <li><a href=\"#BLEU-score-metric-for-evaluation\">BLEU score metric for evaluation</a></li>\n",
        "    <li><a href=\"#Exercises\">Exercises</a></li>\n",
        "\n",
        "</ol>\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "165eee23-dee0-424f-b720-57a14118ed3c"
      },
      "source": [
        "## Objectives\n",
        "After completing this lab, you will be able to:\n",
        "\n",
        " - Comprehend recurrent neural networks (RNN) architecture\n",
        " - Create an Encoder-Decoder model for a translation task\n",
        " - Train and evaluate the model\n",
        " - Create a generator for the translation task\n",
        " - Explain concepts related to Perplexity and BLEU score and use them for evaluating translations\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "470ad959-a5f6-45d4-bcd3-82a493fad704"
      },
      "source": [
        "----\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "fa6e1221-3c6d-44b2-b32a-67b8bde6d3e4"
      },
      "source": [
        "## Setup\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "6c7a9478-7e85-4d6d-9b51-47d54c817e3c"
      },
      "source": [
        "### Installing required libraries\n",
        "\n",
        "All the required libraries are pre-installed in the Skills Network Labs environment. However, if you run this notebook commands in a different Jupyter environment (e.g. Watson Studio or Ananconda), you will need to install these libraries by removing the `#` sign before `!mamba` in the code cell below.\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "ca6403a0-009d-483f-8429-5d9552c90aa3"
      },
      "outputs": [],
      "source": [
        "# All Libraries required for this lab are listed below. The libraries pre-installed on Skills Network Labs are commented.\n",
        "# !mamba install -qy numpy==1.21.4 seaborn==0.9.0\n",
        "# Note: If your environment doesn't support \"!mamba install\", use \"!pip install\"\n",
        "# The working version of each package is commented in front of each package name"
      ],
      "execution_count": 1
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "e21b80b3-b219-41d7-8e53-8c8b4c4d2922"
      },
      "source": [
        "The following required libraries are __not__ pre-installed in the Skills Network Labs environment. __You will need to run the following cell__ to install them:\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "a21f23c5-1528-43de-b835-81215e46f392",
        "outputId": "466a44f4-d88b-4a3e-ed02-09b6ba347131"
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "Collecting torchtext==0.15.1\n",
            "  Downloading torchtext-0.15.1-cp310-cp310-manylinux1_x86_64.whl.metadata (7.4 kB)\n",
            "Requirement already satisfied: tqdm in /usr/local/lib/python3.10/dist-packages (from torchtext==0.15.1) (4.66.6)\n",
            "Requirement already satisfied: requests in /usr/local/lib/python3.10/dist-packages (from torchtext==0.15.1) (2.32.3)\n",
            "Collecting torch==2.0.0 (from torchtext==0.15.1)\n",
            "  Downloading torch-2.0.0-cp310-cp310-manylinux1_x86_64.whl.metadata (24 kB)\n",
            "Requirement already satisfied: numpy in /usr/local/lib/python3.10/dist-packages (from torchtext==0.15.1) (1.26.4)\n",
            "Collecting torchdata==0.6.0 (from torchtext==0.15.1)\n",
            "  Downloading torchdata-0.6.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.metadata (919 bytes)\n",
            "Requirement already satisfied: filelock in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0->torchtext==0.15.1) (3.16.1)\n",
            "Requirement already satisfied: typing-extensions in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0->torchtext==0.15.1) (4.12.2)\n",
            "Requirement already satisfied: sympy in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0->torchtext==0.15.1) (1.13.1)\n",
            "Requirement already satisfied: networkx in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0->torchtext==0.15.1) (3.4.2)\n",
            "Requirement already satisfied: jinja2 in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0->torchtext==0.15.1) (3.1.4)\n",
            "Collecting nvidia-cuda-nvrtc-cu11==11.7.99 (from torch==2.0.0->torchtext==0.15.1)\n",
            "  Downloading nvidia_cuda_nvrtc_cu11-11.7.99-2-py3-none-manylinux1_x86_64.whl.metadata (1.5 kB)\n",
            "Collecting nvidia-cuda-runtime-cu11==11.7.99 (from torch==2.0.0->torchtext==0.15.1)\n",
            "  Downloading nvidia_cuda_runtime_cu11-11.7.99-py3-none-manylinux1_x86_64.whl.metadata (1.6 kB)\n",
            "Collecting nvidia-cuda-cupti-cu11==11.7.101 (from torch==2.0.0->torchtext==0.15.1)\n",
            "  Downloading nvidia_cuda_cupti_cu11-11.7.101-py3-none-manylinux1_x86_64.whl.metadata (1.6 kB)\n",
            "Collecting nvidia-cudnn-cu11==8.5.0.96 (from torch==2.0.0->torchtext==0.15.1)\n",
            "  Downloading nvidia_cudnn_cu11-8.5.0.96-2-py3-none-manylinux1_x86_64.whl.metadata (1.6 kB)\n",
            "Collecting nvidia-cublas-cu11==11.10.3.66 (from torch==2.0.0->torchtext==0.15.1)\n",
            "  Downloading nvidia_cublas_cu11-11.10.3.66-py3-none-manylinux1_x86_64.whl.metadata (1.6 kB)\n",
            "Collecting nvidia-cufft-cu11==10.9.0.58 (from torch==2.0.0->torchtext==0.15.1)\n",
            "  Downloading nvidia_cufft_cu11-10.9.0.58-py3-none-manylinux2014_x86_64.whl.metadata (1.5 kB)\n",
            "Collecting nvidia-curand-cu11==10.2.10.91 (from torch==2.0.0->torchtext==0.15.1)\n",
            "  Downloading nvidia_curand_cu11-10.2.10.91-py3-none-manylinux1_x86_64.whl.metadata (1.6 kB)\n",
            "Collecting nvidia-cusolver-cu11==11.4.0.1 (from torch==2.0.0->torchtext==0.15.1)\n",
            "  Downloading nvidia_cusolver_cu11-11.4.0.1-2-py3-none-manylinux1_x86_64.whl.metadata (1.6 kB)\n",
            "Collecting nvidia-cusparse-cu11==11.7.4.91 (from torch==2.0.0->torchtext==0.15.1)\n",
            "  Downloading nvidia_cusparse_cu11-11.7.4.91-py3-none-manylinux1_x86_64.whl.metadata (1.6 kB)\n",
            "Collecting nvidia-nccl-cu11==2.14.3 (from torch==2.0.0->torchtext==0.15.1)\n",
            "  Downloading nvidia_nccl_cu11-2.14.3-py3-none-manylinux1_x86_64.whl.metadata (1.8 kB)\n",
            "Collecting nvidia-nvtx-cu11==11.7.91 (from torch==2.0.0->torchtext==0.15.1)\n",
            "  Downloading nvidia_nvtx_cu11-11.7.91-py3-none-manylinux1_x86_64.whl.metadata (1.7 kB)\n",
            "Collecting triton==2.0.0 (from torch==2.0.0->torchtext==0.15.1)\n",
            "  Downloading triton-2.0.0-1-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.whl.metadata (1.0 kB)\n",
            "Requirement already satisfied: urllib3>=1.25 in /usr/local/lib/python3.10/dist-packages (from torchdata==0.6.0->torchtext==0.15.1) (2.2.3)\n",
            "Requirement already satisfied: setuptools in /usr/local/lib/python3.10/dist-packages (from nvidia-cublas-cu11==11.10.3.66->torch==2.0.0->torchtext==0.15.1) (75.1.0)\n",
            "Requirement already satisfied: wheel in /usr/local/lib/python3.10/dist-packages (from nvidia-cublas-cu11==11.10.3.66->torch==2.0.0->torchtext==0.15.1) (0.45.0)\n",
            "Requirement already satisfied: cmake in /usr/local/lib/python3.10/dist-packages (from triton==2.0.0->torch==2.0.0->torchtext==0.15.1) (3.30.5)\n",
            "Collecting lit (from triton==2.0.0->torch==2.0.0->torchtext==0.15.1)\n",
            "  Downloading lit-18.1.8-py3-none-any.whl.metadata (2.5 kB)\n",
            "Requirement already satisfied: charset-normalizer<4,>=2 in /usr/local/lib/python3.10/dist-packages (from requests->torchtext==0.15.1) (3.4.0)\n",
            "Requirement already satisfied: idna<4,>=2.5 in /usr/local/lib/python3.10/dist-packages (from requests->torchtext==0.15.1) (3.10)\n",
            "Requirement already satisfied: certifi>=2017.4.17 in /usr/local/lib/python3.10/dist-packages (from requests->torchtext==0.15.1) (2024.8.30)\n",
            "Requirement already satisfied: MarkupSafe>=2.0 in /usr/local/lib/python3.10/dist-packages (from jinja2->torch==2.0.0->torchtext==0.15.1) (3.0.2)\n",
            "Requirement already satisfied: mpmath<1.4,>=1.1.0 in /usr/local/lib/python3.10/dist-packages (from sympy->torch==2.0.0->torchtext==0.15.1) (1.3.0)\n",
            "Downloading torchtext-0.15.1-cp310-cp310-manylinux1_x86_64.whl (2.0 MB)\n",
            "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m2.0/2.0 MB\u001b[0m \u001b[31m69.4 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[?25hDownloading torch-2.0.0-cp310-cp310-manylinux1_x86_64.whl (619.9 MB)\n",
            "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m619.9/619.9 MB\u001b[0m \u001b[31m3.1 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[?25hDownloading torchdata-0.6.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (4.6 MB)\n",
            "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m4.6/4.6 MB\u001b[0m \u001b[31m92.6 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[?25hDownloading nvidia_cublas_cu11-11.10.3.66-py3-none-manylinux1_x86_64.whl (317.1 MB)\n",
            "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m317.1/317.1 MB\u001b[0m \u001b[31m4.7 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[?25hDownloading nvidia_cuda_cupti_cu11-11.7.101-py3-none-manylinux1_x86_64.whl (11.8 MB)\n",
            "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m11.8/11.8 MB\u001b[0m \u001b[31m49.5 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[?25hDownloading nvidia_cuda_nvrtc_cu11-11.7.99-2-py3-none-manylinux1_x86_64.whl (21.0 MB)\n",
            "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m21.0/21.0 MB\u001b[0m \u001b[31m34.7 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[?25hDownloading nvidia_cuda_runtime_cu11-11.7.99-py3-none-manylinux1_x86_64.whl (849 kB)\n",
            "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m849.3/849.3 kB\u001b[0m \u001b[31m37.1 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[?25hDownloading nvidia_cudnn_cu11-8.5.0.96-2-py3-none-manylinux1_x86_64.whl (557.1 MB)\n",
            "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m557.1/557.1 MB\u001b[0m \u001b[31m2.2 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[?25hDownloading nvidia_cufft_cu11-10.9.0.58-py3-none-manylinux2014_x86_64.whl (168.4 MB)\n",
            "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m168.4/168.4 MB\u001b[0m \u001b[31m6.4 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[?25hDownloading nvidia_curand_cu11-10.2.10.91-py3-none-manylinux1_x86_64.whl (54.6 MB)\n",
            "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m54.6/54.6 MB\u001b[0m \u001b[31m11.2 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[?25hDownloading nvidia_cusolver_cu11-11.4.0.1-2-py3-none-manylinux1_x86_64.whl (102.6 MB)\n",
            "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m102.6/102.6 MB\u001b[0m \u001b[31m8.1 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[?25hDownloading nvidia_cusparse_cu11-11.7.4.91-py3-none-manylinux1_x86_64.whl (173.2 MB)\n",
            "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m173.2/173.2 MB\u001b[0m \u001b[31m7.8 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[?25hDownloading nvidia_nccl_cu11-2.14.3-py3-none-manylinux1_x86_64.whl (177.1 MB)\n",
            "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m177.1/177.1 MB\u001b[0m \u001b[31m6.9 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[?25hDownloading nvidia_nvtx_cu11-11.7.91-py3-none-manylinux1_x86_64.whl (98 kB)\n",
            "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m98.6/98.6 kB\u001b[0m \u001b[31m9.1 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[?25hDownloading triton-2.0.0-1-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (63.3 MB)\n",
            "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m63.3/63.3 MB\u001b[0m \u001b[31m11.3 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[?25hDownloading lit-18.1.8-py3-none-any.whl (96 kB)\n",
            "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m96.4/96.4 kB\u001b[0m \u001b[31m8.4 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[?25hInstalling collected packages: lit, nvidia-nvtx-cu11, nvidia-nccl-cu11, nvidia-cusparse-cu11, nvidia-curand-cu11, nvidia-cufft-cu11, nvidia-cuda-runtime-cu11, nvidia-cuda-nvrtc-cu11, nvidia-cuda-cupti-cu11, nvidia-cublas-cu11, nvidia-cusolver-cu11, nvidia-cudnn-cu11, triton, torch, torchdata, torchtext\n",
            "  Attempting uninstall: torch\n",
            "    Found existing installation: torch 2.5.1+cu121\n",
            "    Uninstalling torch-2.5.1+cu121:\n",
            "      Successfully uninstalled torch-2.5.1+cu121\n",
            "\u001b[31mERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts.\n",
            "torchaudio 2.5.1+cu121 requires torch==2.5.1, but you have torch 2.0.0 which is incompatible.\n",
            "torchvision 0.20.1+cu121 requires torch==2.5.1, but you have torch 2.0.0 which is incompatible.\u001b[0m\u001b[31m\n",
            "\u001b[0mSuccessfully installed lit-18.1.8 nvidia-cublas-cu11-11.10.3.66 nvidia-cuda-cupti-cu11-11.7.101 nvidia-cuda-nvrtc-cu11-11.7.99 nvidia-cuda-runtime-cu11-11.7.99 nvidia-cudnn-cu11-8.5.0.96 nvidia-cufft-cu11-10.9.0.58 nvidia-curand-cu11-10.2.10.91 nvidia-cusolver-cu11-11.4.0.1 nvidia-cusparse-cu11-11.7.4.91 nvidia-nccl-cu11-2.14.3 nvidia-nvtx-cu11-11.7.91 torch-2.0.0 torchdata-0.6.0 torchtext-0.15.1 triton-2.0.0\n",
            "Requirement already satisfied: torch==2.0.0 in /usr/local/lib/python3.10/dist-packages (2.0.0)\n",
            "Requirement already satisfied: filelock in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0) (3.16.1)\n",
            "Requirement already satisfied: typing-extensions in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0) (4.12.2)\n",
            "Requirement already satisfied: sympy in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0) (1.13.1)\n",
            "Requirement already satisfied: networkx in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0) (3.4.2)\n",
            "Requirement already satisfied: jinja2 in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0) (3.1.4)\n",
            "Requirement already satisfied: nvidia-cuda-nvrtc-cu11==11.7.99 in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0) (11.7.99)\n",
            "Requirement already satisfied: nvidia-cuda-runtime-cu11==11.7.99 in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0) (11.7.99)\n",
            "Requirement already satisfied: nvidia-cuda-cupti-cu11==11.7.101 in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0) (11.7.101)\n",
            "Requirement already satisfied: nvidia-cudnn-cu11==8.5.0.96 in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0) (8.5.0.96)\n",
            "Requirement already satisfied: nvidia-cublas-cu11==11.10.3.66 in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0) (11.10.3.66)\n",
            "Requirement already satisfied: nvidia-cufft-cu11==10.9.0.58 in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0) (10.9.0.58)\n",
            "Requirement already satisfied: nvidia-curand-cu11==10.2.10.91 in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0) (10.2.10.91)\n",
            "Requirement already satisfied: nvidia-cusolver-cu11==11.4.0.1 in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0) (11.4.0.1)\n",
            "Requirement already satisfied: nvidia-cusparse-cu11==11.7.4.91 in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0) (11.7.4.91)\n",
            "Requirement already satisfied: nvidia-nccl-cu11==2.14.3 in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0) (2.14.3)\n",
            "Requirement already satisfied: nvidia-nvtx-cu11==11.7.91 in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0) (11.7.91)\n",
            "Requirement already satisfied: triton==2.0.0 in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0) (2.0.0)\n",
            "Requirement already satisfied: setuptools in /usr/local/lib/python3.10/dist-packages (from nvidia-cublas-cu11==11.10.3.66->torch==2.0.0) (75.1.0)\n",
            "Requirement already satisfied: wheel in /usr/local/lib/python3.10/dist-packages (from nvidia-cublas-cu11==11.10.3.66->torch==2.0.0) (0.45.0)\n",
            "Requirement already satisfied: cmake in /usr/local/lib/python3.10/dist-packages (from triton==2.0.0->torch==2.0.0) (3.30.5)\n",
            "Requirement already satisfied: lit in /usr/local/lib/python3.10/dist-packages (from triton==2.0.0->torch==2.0.0) (18.1.8)\n",
            "Requirement already satisfied: MarkupSafe>=2.0 in /usr/local/lib/python3.10/dist-packages (from jinja2->torch==2.0.0) (3.0.2)\n",
            "Requirement already satisfied: mpmath<1.4,>=1.1.0 in /usr/local/lib/python3.10/dist-packages (from sympy->torch==2.0.0) (1.3.0)\n",
            "Collecting spacy==3.7.2\n",
            "  Downloading spacy-3.7.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.metadata (25 kB)\n",
            "Requirement already satisfied: spacy-legacy<3.1.0,>=3.0.11 in /usr/local/lib/python3.10/dist-packages (from spacy==3.7.2) (3.0.12)\n",
            "Requirement already satisfied: spacy-loggers<2.0.0,>=1.0.0 in /usr/local/lib/python3.10/dist-packages (from spacy==3.7.2) (1.0.5)\n",
            "Requirement already satisfied: murmurhash<1.1.0,>=0.28.0 in /usr/local/lib/python3.10/dist-packages (from spacy==3.7.2) (1.0.10)\n",
            "Requirement already satisfied: cymem<2.1.0,>=2.0.2 in /usr/local/lib/python3.10/dist-packages (from spacy==3.7.2) (2.0.8)\n",
            "Requirement already satisfied: preshed<3.1.0,>=3.0.2 in /usr/local/lib/python3.10/dist-packages (from spacy==3.7.2) (3.0.9)\n",
            "Requirement already satisfied: thinc<8.3.0,>=8.1.8 in /usr/local/lib/python3.10/dist-packages (from spacy==3.7.2) (8.2.5)\n",
            "Requirement already satisfied: wasabi<1.2.0,>=0.9.1 in /usr/local/lib/python3.10/dist-packages (from spacy==3.7.2) (1.1.3)\n",
            "Requirement already satisfied: srsly<3.0.0,>=2.4.3 in /usr/local/lib/python3.10/dist-packages (from spacy==3.7.2) (2.4.8)\n",
            "Requirement already satisfied: catalogue<2.1.0,>=2.0.6 in /usr/local/lib/python3.10/dist-packages (from spacy==3.7.2) (2.0.10)\n",
            "Collecting weasel<0.4.0,>=0.1.0 (from spacy==3.7.2)\n",
            "  Downloading weasel-0.3.4-py3-none-any.whl.metadata (4.7 kB)\n",
            "Collecting typer<0.10.0,>=0.3.0 (from spacy==3.7.2)\n",
            "  Downloading typer-0.9.4-py3-none-any.whl.metadata (14 kB)\n",
            "Collecting smart-open<7.0.0,>=5.2.1 (from spacy==3.7.2)\n",
            "  Downloading smart_open-6.4.0-py3-none-any.whl.metadata (21 kB)\n",
            "Requirement already satisfied: tqdm<5.0.0,>=4.38.0 in /usr/local/lib/python3.10/dist-packages (from spacy==3.7.2) (4.66.6)\n",
            "Requirement already satisfied: requests<3.0.0,>=2.13.0 in /usr/local/lib/python3.10/dist-packages (from spacy==3.7.2) (2.32.3)\n",
            "Requirement already satisfied: pydantic!=1.8,!=1.8.1,<3.0.0,>=1.7.4 in /usr/local/lib/python3.10/dist-packages (from spacy==3.7.2) (2.9.2)\n",
            "Requirement already satisfied: jinja2 in /usr/local/lib/python3.10/dist-packages (from spacy==3.7.2) (3.1.4)\n",
            "Requirement already satisfied: setuptools in /usr/local/lib/python3.10/dist-packages (from spacy==3.7.2) (75.1.0)\n",
            "Requirement already satisfied: packaging>=20.0 in /usr/local/lib/python3.10/dist-packages (from spacy==3.7.2) (24.2)\n",
            "Requirement already satisfied: langcodes<4.0.0,>=3.2.0 in /usr/local/lib/python3.10/dist-packages (from spacy==3.7.2) (3.4.1)\n",
            "Requirement already satisfied: numpy>=1.19.0 in /usr/local/lib/python3.10/dist-packages (from spacy==3.7.2) (1.26.4)\n",
            "Requirement already satisfied: language-data>=1.2 in /usr/local/lib/python3.10/dist-packages (from langcodes<4.0.0,>=3.2.0->spacy==3.7.2) (1.2.0)\n",
            "Requirement already satisfied: annotated-types>=0.6.0 in /usr/local/lib/python3.10/dist-packages (from pydantic!=1.8,!=1.8.1,<3.0.0,>=1.7.4->spacy==3.7.2) (0.7.0)\n",
            "Requirement already satisfied: pydantic-core==2.23.4 in /usr/local/lib/python3.10/dist-packages (from pydantic!=1.8,!=1.8.1,<3.0.0,>=1.7.4->spacy==3.7.2) (2.23.4)\n",
            "Requirement already satisfied: typing-extensions>=4.6.1 in /usr/local/lib/python3.10/dist-packages (from pydantic!=1.8,!=1.8.1,<3.0.0,>=1.7.4->spacy==3.7.2) (4.12.2)\n",
            "Requirement already satisfied: charset-normalizer<4,>=2 in /usr/local/lib/python3.10/dist-packages (from requests<3.0.0,>=2.13.0->spacy==3.7.2) (3.4.0)\n",
            "Requirement already satisfied: idna<4,>=2.5 in /usr/local/lib/python3.10/dist-packages (from requests<3.0.0,>=2.13.0->spacy==3.7.2) (3.10)\n",
            "Requirement already satisfied: urllib3<3,>=1.21.1 in /usr/local/lib/python3.10/dist-packages (from requests<3.0.0,>=2.13.0->spacy==3.7.2) (2.2.3)\n",
            "Requirement already satisfied: certifi>=2017.4.17 in /usr/local/lib/python3.10/dist-packages (from requests<3.0.0,>=2.13.0->spacy==3.7.2) (2024.8.30)\n",
            "Requirement already satisfied: blis<0.8.0,>=0.7.8 in /usr/local/lib/python3.10/dist-packages (from thinc<8.3.0,>=8.1.8->spacy==3.7.2) (0.7.11)\n",
            "Requirement already satisfied: confection<1.0.0,>=0.0.1 in /usr/local/lib/python3.10/dist-packages (from thinc<8.3.0,>=8.1.8->spacy==3.7.2) (0.1.5)\n",
            "Requirement already satisfied: click<9.0.0,>=7.1.1 in /usr/local/lib/python3.10/dist-packages (from typer<0.10.0,>=0.3.0->spacy==3.7.2) (8.1.7)\n",
            "Collecting cloudpathlib<0.17.0,>=0.7.0 (from weasel<0.4.0,>=0.1.0->spacy==3.7.2)\n",
            "  Downloading cloudpathlib-0.16.0-py3-none-any.whl.metadata (14 kB)\n",
            "Requirement already satisfied: MarkupSafe>=2.0 in /usr/local/lib/python3.10/dist-packages (from jinja2->spacy==3.7.2) (3.0.2)\n",
            "Requirement already satisfied: marisa-trie>=0.7.7 in /usr/local/lib/python3.10/dist-packages (from language-data>=1.2->langcodes<4.0.0,>=3.2.0->spacy==3.7.2) (1.2.1)\n",
            "Downloading spacy-3.7.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (6.6 MB)\n",
            "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m6.6/6.6 MB\u001b[0m \u001b[31m92.2 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[?25hDownloading smart_open-6.4.0-py3-none-any.whl (57 kB)\n",
            "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m57.0/57.0 kB\u001b[0m \u001b[31m5.1 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[?25hDownloading typer-0.9.4-py3-none-any.whl (45 kB)\n",
            "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m46.0/46.0 kB\u001b[0m \u001b[31m4.2 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[?25hDownloading weasel-0.3.4-py3-none-any.whl (50 kB)\n",
            "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m50.1/50.1 kB\u001b[0m \u001b[31m4.0 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[?25hDownloading cloudpathlib-0.16.0-py3-none-any.whl (45 kB)\n",
            "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m45.0/45.0 kB\u001b[0m \u001b[31m4.2 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[?25hInstalling collected packages: typer, smart-open, cloudpathlib, weasel, spacy\n",
            "  Attempting uninstall: typer\n",
            "    Found existing installation: typer 0.13.0\n",
            "    Uninstalling typer-0.13.0:\n",
            "      Successfully uninstalled typer-0.13.0\n",
            "  Attempting uninstall: smart-open\n",
            "    Found existing installation: smart-open 7.0.5\n",
            "    Uninstalling smart-open-7.0.5:\n",
            "      Successfully uninstalled smart-open-7.0.5\n",
            "  Attempting uninstall: cloudpathlib\n",
            "    Found existing installation: cloudpathlib 0.20.0\n",
            "    Uninstalling cloudpathlib-0.20.0:\n",
            "      Successfully uninstalled cloudpathlib-0.20.0\n",
            "  Attempting uninstall: weasel\n",
            "    Found existing installation: weasel 0.4.1\n",
            "    Uninstalling weasel-0.4.1:\n",
            "      Successfully uninstalled weasel-0.4.1\n",
            "  Attempting uninstall: spacy\n",
            "    Found existing installation: spacy 3.7.5\n",
            "    Uninstalling spacy-3.7.5:\n",
            "      Successfully uninstalled spacy-3.7.5\n",
            "Successfully installed cloudpathlib-0.16.0 smart-open-6.4.0 spacy-3.7.2 typer-0.9.4 weasel-0.3.4\n",
            "Requirement already satisfied: torchdata==0.6.0 in /usr/local/lib/python3.10/dist-packages (0.6.0)\n",
            "Requirement already satisfied: urllib3>=1.25 in /usr/local/lib/python3.10/dist-packages (from torchdata==0.6.0) (2.2.3)\n",
            "Requirement already satisfied: requests in /usr/local/lib/python3.10/dist-packages (from torchdata==0.6.0) (2.32.3)\n",
            "Requirement already satisfied: torch==2.0.0 in /usr/local/lib/python3.10/dist-packages (from torchdata==0.6.0) (2.0.0)\n",
            "Requirement already satisfied: filelock in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0->torchdata==0.6.0) (3.16.1)\n",
            "Requirement already satisfied: typing-extensions in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0->torchdata==0.6.0) (4.12.2)\n",
            "Requirement already satisfied: sympy in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0->torchdata==0.6.0) (1.13.1)\n",
            "Requirement already satisfied: networkx in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0->torchdata==0.6.0) (3.4.2)\n",
            "Requirement already satisfied: jinja2 in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0->torchdata==0.6.0) (3.1.4)\n",
            "Requirement already satisfied: nvidia-cuda-nvrtc-cu11==11.7.99 in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0->torchdata==0.6.0) (11.7.99)\n",
            "Requirement already satisfied: nvidia-cuda-runtime-cu11==11.7.99 in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0->torchdata==0.6.0) (11.7.99)\n",
            "Requirement already satisfied: nvidia-cuda-cupti-cu11==11.7.101 in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0->torchdata==0.6.0) (11.7.101)\n",
            "Requirement already satisfied: nvidia-cudnn-cu11==8.5.0.96 in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0->torchdata==0.6.0) (8.5.0.96)\n",
            "Requirement already satisfied: nvidia-cublas-cu11==11.10.3.66 in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0->torchdata==0.6.0) (11.10.3.66)\n",
            "Requirement already satisfied: nvidia-cufft-cu11==10.9.0.58 in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0->torchdata==0.6.0) (10.9.0.58)\n",
            "Requirement already satisfied: nvidia-curand-cu11==10.2.10.91 in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0->torchdata==0.6.0) (10.2.10.91)\n",
            "Requirement already satisfied: nvidia-cusolver-cu11==11.4.0.1 in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0->torchdata==0.6.0) (11.4.0.1)\n",
            "Requirement already satisfied: nvidia-cusparse-cu11==11.7.4.91 in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0->torchdata==0.6.0) (11.7.4.91)\n",
            "Requirement already satisfied: nvidia-nccl-cu11==2.14.3 in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0->torchdata==0.6.0) (2.14.3)\n",
            "Requirement already satisfied: nvidia-nvtx-cu11==11.7.91 in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0->torchdata==0.6.0) (11.7.91)\n",
            "Requirement already satisfied: triton==2.0.0 in /usr/local/lib/python3.10/dist-packages (from torch==2.0.0->torchdata==0.6.0) (2.0.0)\n",
            "Requirement already satisfied: setuptools in /usr/local/lib/python3.10/dist-packages (from nvidia-cublas-cu11==11.10.3.66->torch==2.0.0->torchdata==0.6.0) (75.1.0)\n",
            "Requirement already satisfied: wheel in /usr/local/lib/python3.10/dist-packages (from nvidia-cublas-cu11==11.10.3.66->torch==2.0.0->torchdata==0.6.0) (0.45.0)\n",
            "Requirement already satisfied: cmake in /usr/local/lib/python3.10/dist-packages (from triton==2.0.0->torch==2.0.0->torchdata==0.6.0) (3.30.5)\n",
            "Requirement already satisfied: lit in /usr/local/lib/python3.10/dist-packages (from triton==2.0.0->torch==2.0.0->torchdata==0.6.0) (18.1.8)\n",
            "Requirement already satisfied: charset-normalizer<4,>=2 in /usr/local/lib/python3.10/dist-packages (from requests->torchdata==0.6.0) (3.4.0)\n",
            "Requirement already satisfied: idna<4,>=2.5 in /usr/local/lib/python3.10/dist-packages (from requests->torchdata==0.6.0) (3.10)\n",
            "Requirement already satisfied: certifi>=2017.4.17 in /usr/local/lib/python3.10/dist-packages (from requests->torchdata==0.6.0) (2024.8.30)\n",
            "Requirement already satisfied: MarkupSafe>=2.0 in /usr/local/lib/python3.10/dist-packages (from jinja2->torch==2.0.0->torchdata==0.6.0) (3.0.2)\n",
            "Requirement already satisfied: mpmath<1.4,>=1.1.0 in /usr/local/lib/python3.10/dist-packages (from sympy->torch==2.0.0->torchdata==0.6.0) (1.3.0)\n",
            "Collecting nltk==3.8.1\n",
            "  Downloading nltk-3.8.1-py3-none-any.whl.metadata (2.8 kB)\n",
            "Requirement already satisfied: click in /usr/local/lib/python3.10/dist-packages (from nltk==3.8.1) (8.1.7)\n",
            "Requirement already satisfied: joblib in /usr/local/lib/python3.10/dist-packages (from nltk==3.8.1) (1.4.2)\n",
            "Requirement already satisfied: regex>=2021.8.3 in /usr/local/lib/python3.10/dist-packages (from nltk==3.8.1) (2024.9.11)\n",
            "Requirement already satisfied: tqdm in /usr/local/lib/python3.10/dist-packages (from nltk==3.8.1) (4.66.6)\n",
            "Downloading nltk-3.8.1-py3-none-any.whl (1.5 MB)\n",
            "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m1.5/1.5 MB\u001b[0m \u001b[31m21.8 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[?25hInstalling collected packages: nltk\n",
            "  Attempting uninstall: nltk\n",
            "    Found existing installation: nltk 3.9.1\n",
            "    Uninstalling nltk-3.9.1:\n",
            "      Successfully uninstalled nltk-3.9.1\n",
            "Successfully installed nltk-3.8.1\n",
            "Requirement already satisfied: matplotlib in /usr/local/lib/python3.10/dist-packages (3.8.0)\n",
            "Collecting matplotlib\n",
            "  Downloading matplotlib-3.9.3-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.metadata (11 kB)\n",
            "Requirement already satisfied: contourpy>=1.0.1 in /usr/local/lib/python3.10/dist-packages (from matplotlib) (1.3.1)\n",
            "Requirement already satisfied: cycler>=0.10 in /usr/local/lib/python3.10/dist-packages (from matplotlib) (0.12.1)\n",
            "Requirement already satisfied: fonttools>=4.22.0 in /usr/local/lib/python3.10/dist-packages (from matplotlib) (4.55.0)\n",
            "Requirement already satisfied: kiwisolver>=1.3.1 in /usr/local/lib/python3.10/dist-packages (from matplotlib) (1.4.7)\n",
            "Requirement already satisfied: numpy>=1.23 in /usr/local/lib/python3.10/dist-packages (from matplotlib) (1.26.4)\n",
            "Requirement already satisfied: packaging>=20.0 in /usr/local/lib/python3.10/dist-packages (from matplotlib) (24.2)\n",
            "Requirement already satisfied: pillow>=8 in /usr/local/lib/python3.10/dist-packages (from matplotlib) (11.0.0)\n",
            "Requirement already satisfied: pyparsing>=2.3.1 in /usr/local/lib/python3.10/dist-packages (from matplotlib) (3.2.0)\n",
            "Requirement already satisfied: python-dateutil>=2.7 in /usr/local/lib/python3.10/dist-packages (from matplotlib) (2.8.2)\n",
            "Requirement already satisfied: six>=1.5 in /usr/local/lib/python3.10/dist-packages (from python-dateutil>=2.7->matplotlib) (1.16.0)\n",
            "Downloading matplotlib-3.9.3-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (8.3 MB)\n",
            "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m8.3/8.3 MB\u001b[0m \u001b[31m83.5 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[?25hInstalling collected packages: matplotlib\n",
            "  Attempting uninstall: matplotlib\n",
            "    Found existing installation: matplotlib 3.8.0\n",
            "    Uninstalling matplotlib-3.8.0:\n",
            "      Successfully uninstalled matplotlib-3.8.0\n",
            "Successfully installed matplotlib-3.9.3\n",
            "Collecting en-core-web-sm==3.7.1\n",
            "  Downloading https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.7.1/en_core_web_sm-3.7.1-py3-none-any.whl (12.8 MB)\n",
            "\u001b[2K     \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m12.8/12.8 MB\u001b[0m \u001b[31m89.6 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[?25hRequirement already satisfied: spacy<3.8.0,>=3.7.2 in /usr/local/lib/python3.10/dist-packages (from en-core-web-sm==3.7.1) (3.7.2)\n",
            "Requirement already satisfied: spacy-legacy<3.1.0,>=3.0.11 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.2->en-core-web-sm==3.7.1) (3.0.12)\n",
            "Requirement already satisfied: spacy-loggers<2.0.0,>=1.0.0 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.2->en-core-web-sm==3.7.1) (1.0.5)\n",
            "Requirement already satisfied: murmurhash<1.1.0,>=0.28.0 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.2->en-core-web-sm==3.7.1) (1.0.10)\n",
            "Requirement already satisfied: cymem<2.1.0,>=2.0.2 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.2->en-core-web-sm==3.7.1) (2.0.8)\n",
            "Requirement already satisfied: preshed<3.1.0,>=3.0.2 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.2->en-core-web-sm==3.7.1) (3.0.9)\n",
            "Requirement already satisfied: thinc<8.3.0,>=8.1.8 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.2->en-core-web-sm==3.7.1) (8.2.5)\n",
            "Requirement already satisfied: wasabi<1.2.0,>=0.9.1 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.2->en-core-web-sm==3.7.1) (1.1.3)\n",
            "Requirement already satisfied: srsly<3.0.0,>=2.4.3 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.2->en-core-web-sm==3.7.1) (2.4.8)\n",
            "Requirement already satisfied: catalogue<2.1.0,>=2.0.6 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.2->en-core-web-sm==3.7.1) (2.0.10)\n",
            "Requirement already satisfied: weasel<0.4.0,>=0.1.0 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.2->en-core-web-sm==3.7.1) (0.3.4)\n",
            "Requirement already satisfied: typer<0.10.0,>=0.3.0 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.2->en-core-web-sm==3.7.1) (0.9.4)\n",
            "Requirement already satisfied: smart-open<7.0.0,>=5.2.1 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.2->en-core-web-sm==3.7.1) (6.4.0)\n",
            "Requirement already satisfied: tqdm<5.0.0,>=4.38.0 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.2->en-core-web-sm==3.7.1) (4.66.6)\n",
            "Requirement already satisfied: requests<3.0.0,>=2.13.0 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.2->en-core-web-sm==3.7.1) (2.32.3)\n",
            "Requirement already satisfied: pydantic!=1.8,!=1.8.1,<3.0.0,>=1.7.4 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.2->en-core-web-sm==3.7.1) (2.9.2)\n",
            "Requirement already satisfied: jinja2 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.2->en-core-web-sm==3.7.1) (3.1.4)\n",
            "Requirement already satisfied: setuptools in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.2->en-core-web-sm==3.7.1) (75.1.0)\n",
            "Requirement already satisfied: packaging>=20.0 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.2->en-core-web-sm==3.7.1) (24.2)\n",
            "Requirement already satisfied: langcodes<4.0.0,>=3.2.0 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.2->en-core-web-sm==3.7.1) (3.4.1)\n",
            "Requirement already satisfied: numpy>=1.19.0 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.2->en-core-web-sm==3.7.1) (1.26.4)\n",
            "Requirement already satisfied: language-data>=1.2 in /usr/local/lib/python3.10/dist-packages (from langcodes<4.0.0,>=3.2.0->spacy<3.8.0,>=3.7.2->en-core-web-sm==3.7.1) (1.2.0)\n",
            "Requirement already satisfied: annotated-types>=0.6.0 in /usr/local/lib/python3.10/dist-packages (from pydantic!=1.8,!=1.8.1,<3.0.0,>=1.7.4->spacy<3.8.0,>=3.7.2->en-core-web-sm==3.7.1) (0.7.0)\n",
            "Requirement already satisfied: pydantic-core==2.23.4 in /usr/local/lib/python3.10/dist-packages (from pydantic!=1.8,!=1.8.1,<3.0.0,>=1.7.4->spacy<3.8.0,>=3.7.2->en-core-web-sm==3.7.1) (2.23.4)\n",
            "Requirement already satisfied: typing-extensions>=4.6.1 in /usr/local/lib/python3.10/dist-packages (from pydantic!=1.8,!=1.8.1,<3.0.0,>=1.7.4->spacy<3.8.0,>=3.7.2->en-core-web-sm==3.7.1) (4.12.2)\n",
            "Requirement already satisfied: charset-normalizer<4,>=2 in /usr/local/lib/python3.10/dist-packages (from requests<3.0.0,>=2.13.0->spacy<3.8.0,>=3.7.2->en-core-web-sm==3.7.1) (3.4.0)\n",
            "Requirement already satisfied: idna<4,>=2.5 in /usr/local/lib/python3.10/dist-packages (from requests<3.0.0,>=2.13.0->spacy<3.8.0,>=3.7.2->en-core-web-sm==3.7.1) (3.10)\n",
            "Requirement already satisfied: urllib3<3,>=1.21.1 in /usr/local/lib/python3.10/dist-packages (from requests<3.0.0,>=2.13.0->spacy<3.8.0,>=3.7.2->en-core-web-sm==3.7.1) (2.2.3)\n",
            "Requirement already satisfied: certifi>=2017.4.17 in /usr/local/lib/python3.10/dist-packages (from requests<3.0.0,>=2.13.0->spacy<3.8.0,>=3.7.2->en-core-web-sm==3.7.1) (2024.8.30)\n",
            "Requirement already satisfied: blis<0.8.0,>=0.7.8 in /usr/local/lib/python3.10/dist-packages (from thinc<8.3.0,>=8.1.8->spacy<3.8.0,>=3.7.2->en-core-web-sm==3.7.1) (0.7.11)\n",
            "Requirement already satisfied: confection<1.0.0,>=0.0.1 in /usr/local/lib/python3.10/dist-packages (from thinc<8.3.0,>=8.1.8->spacy<3.8.0,>=3.7.2->en-core-web-sm==3.7.1) (0.1.5)\n",
            "Requirement already satisfied: click<9.0.0,>=7.1.1 in /usr/local/lib/python3.10/dist-packages (from typer<0.10.0,>=0.3.0->spacy<3.8.0,>=3.7.2->en-core-web-sm==3.7.1) (8.1.7)\n",
            "Requirement already satisfied: cloudpathlib<0.17.0,>=0.7.0 in /usr/local/lib/python3.10/dist-packages (from weasel<0.4.0,>=0.1.0->spacy<3.8.0,>=3.7.2->en-core-web-sm==3.7.1) (0.16.0)\n",
            "Requirement already satisfied: MarkupSafe>=2.0 in /usr/local/lib/python3.10/dist-packages (from jinja2->spacy<3.8.0,>=3.7.2->en-core-web-sm==3.7.1) (3.0.2)\n",
            "Requirement already satisfied: marisa-trie>=0.7.7 in /usr/local/lib/python3.10/dist-packages (from language-data>=1.2->langcodes<4.0.0,>=3.2.0->spacy<3.8.0,>=3.7.2->en-core-web-sm==3.7.1) (1.2.1)\n",
            "\u001b[38;5;2m✔ Download and installation successful\u001b[0m\n",
            "You can now load the package via spacy.load('en_core_web_sm')\n",
            "Collecting de-core-news-sm==3.7.0\n",
            "  Downloading https://github.com/explosion/spacy-models/releases/download/de_core_news_sm-3.7.0/de_core_news_sm-3.7.0-py3-none-any.whl (14.6 MB)\n",
            "\u001b[2K     \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m14.6/14.6 MB\u001b[0m \u001b[31m27.3 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[?25hRequirement already satisfied: spacy<3.8.0,>=3.7.0 in /usr/local/lib/python3.10/dist-packages (from de-core-news-sm==3.7.0) (3.7.2)\n",
            "Requirement already satisfied: spacy-legacy<3.1.0,>=3.0.11 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.0->de-core-news-sm==3.7.0) (3.0.12)\n",
            "Requirement already satisfied: spacy-loggers<2.0.0,>=1.0.0 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.0->de-core-news-sm==3.7.0) (1.0.5)\n",
            "Requirement already satisfied: murmurhash<1.1.0,>=0.28.0 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.0->de-core-news-sm==3.7.0) (1.0.10)\n",
            "Requirement already satisfied: cymem<2.1.0,>=2.0.2 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.0->de-core-news-sm==3.7.0) (2.0.8)\n",
            "Requirement already satisfied: preshed<3.1.0,>=3.0.2 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.0->de-core-news-sm==3.7.0) (3.0.9)\n",
            "Requirement already satisfied: thinc<8.3.0,>=8.1.8 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.0->de-core-news-sm==3.7.0) (8.2.5)\n",
            "Requirement already satisfied: wasabi<1.2.0,>=0.9.1 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.0->de-core-news-sm==3.7.0) (1.1.3)\n",
            "Requirement already satisfied: srsly<3.0.0,>=2.4.3 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.0->de-core-news-sm==3.7.0) (2.4.8)\n",
            "Requirement already satisfied: catalogue<2.1.0,>=2.0.6 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.0->de-core-news-sm==3.7.0) (2.0.10)\n",
            "Requirement already satisfied: weasel<0.4.0,>=0.1.0 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.0->de-core-news-sm==3.7.0) (0.3.4)\n",
            "Requirement already satisfied: typer<0.10.0,>=0.3.0 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.0->de-core-news-sm==3.7.0) (0.9.4)\n",
            "Requirement already satisfied: smart-open<7.0.0,>=5.2.1 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.0->de-core-news-sm==3.7.0) (6.4.0)\n",
            "Requirement already satisfied: tqdm<5.0.0,>=4.38.0 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.0->de-core-news-sm==3.7.0) (4.66.6)\n",
            "Requirement already satisfied: requests<3.0.0,>=2.13.0 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.0->de-core-news-sm==3.7.0) (2.32.3)\n",
            "Requirement already satisfied: pydantic!=1.8,!=1.8.1,<3.0.0,>=1.7.4 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.0->de-core-news-sm==3.7.0) (2.9.2)\n",
            "Requirement already satisfied: jinja2 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.0->de-core-news-sm==3.7.0) (3.1.4)\n",
            "Requirement already satisfied: setuptools in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.0->de-core-news-sm==3.7.0) (75.1.0)\n",
            "Requirement already satisfied: packaging>=20.0 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.0->de-core-news-sm==3.7.0) (24.2)\n",
            "Requirement already satisfied: langcodes<4.0.0,>=3.2.0 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.0->de-core-news-sm==3.7.0) (3.4.1)\n",
            "Requirement already satisfied: numpy>=1.19.0 in /usr/local/lib/python3.10/dist-packages (from spacy<3.8.0,>=3.7.0->de-core-news-sm==3.7.0) (1.26.4)\n",
            "Requirement already satisfied: language-data>=1.2 in /usr/local/lib/python3.10/dist-packages (from langcodes<4.0.0,>=3.2.0->spacy<3.8.0,>=3.7.0->de-core-news-sm==3.7.0) (1.2.0)\n",
            "Requirement already satisfied: annotated-types>=0.6.0 in /usr/local/lib/python3.10/dist-packages (from pydantic!=1.8,!=1.8.1,<3.0.0,>=1.7.4->spacy<3.8.0,>=3.7.0->de-core-news-sm==3.7.0) (0.7.0)\n",
            "Requirement already satisfied: pydantic-core==2.23.4 in /usr/local/lib/python3.10/dist-packages (from pydantic!=1.8,!=1.8.1,<3.0.0,>=1.7.4->spacy<3.8.0,>=3.7.0->de-core-news-sm==3.7.0) (2.23.4)\n",
            "Requirement already satisfied: typing-extensions>=4.6.1 in /usr/local/lib/python3.10/dist-packages (from pydantic!=1.8,!=1.8.1,<3.0.0,>=1.7.4->spacy<3.8.0,>=3.7.0->de-core-news-sm==3.7.0) (4.12.2)\n",
            "Requirement already satisfied: charset-normalizer<4,>=2 in /usr/local/lib/python3.10/dist-packages (from requests<3.0.0,>=2.13.0->spacy<3.8.0,>=3.7.0->de-core-news-sm==3.7.0) (3.4.0)\n",
            "Requirement already satisfied: idna<4,>=2.5 in /usr/local/lib/python3.10/dist-packages (from requests<3.0.0,>=2.13.0->spacy<3.8.0,>=3.7.0->de-core-news-sm==3.7.0) (3.10)\n",
            "Requirement already satisfied: urllib3<3,>=1.21.1 in /usr/local/lib/python3.10/dist-packages (from requests<3.0.0,>=2.13.0->spacy<3.8.0,>=3.7.0->de-core-news-sm==3.7.0) (2.2.3)\n",
            "Requirement already satisfied: certifi>=2017.4.17 in /usr/local/lib/python3.10/dist-packages (from requests<3.0.0,>=2.13.0->spacy<3.8.0,>=3.7.0->de-core-news-sm==3.7.0) (2024.8.30)\n",
            "Requirement already satisfied: blis<0.8.0,>=0.7.8 in /usr/local/lib/python3.10/dist-packages (from thinc<8.3.0,>=8.1.8->spacy<3.8.0,>=3.7.0->de-core-news-sm==3.7.0) (0.7.11)\n",
            "Requirement already satisfied: confection<1.0.0,>=0.0.1 in /usr/local/lib/python3.10/dist-packages (from thinc<8.3.0,>=8.1.8->spacy<3.8.0,>=3.7.0->de-core-news-sm==3.7.0) (0.1.5)\n",
            "Requirement already satisfied: click<9.0.0,>=7.1.1 in /usr/local/lib/python3.10/dist-packages (from typer<0.10.0,>=0.3.0->spacy<3.8.0,>=3.7.0->de-core-news-sm==3.7.0) (8.1.7)\n",
            "Requirement already satisfied: cloudpathlib<0.17.0,>=0.7.0 in /usr/local/lib/python3.10/dist-packages (from weasel<0.4.0,>=0.1.0->spacy<3.8.0,>=3.7.0->de-core-news-sm==3.7.0) (0.16.0)\n",
            "Requirement already satisfied: MarkupSafe>=2.0 in /usr/local/lib/python3.10/dist-packages (from jinja2->spacy<3.8.0,>=3.7.0->de-core-news-sm==3.7.0) (3.0.2)\n",
            "Requirement already satisfied: marisa-trie>=0.7.7 in /usr/local/lib/python3.10/dist-packages (from language-data>=1.2->langcodes<4.0.0,>=3.2.0->spacy<3.8.0,>=3.7.0->de-core-news-sm==3.7.0) (1.2.1)\n",
            "Installing collected packages: de-core-news-sm\n",
            "Successfully installed de-core-news-sm-3.7.0\n",
            "\u001b[38;5;2m✔ Download and installation successful\u001b[0m\n",
            "You can now load the package via spacy.load('de_core_news_sm')\n"
          ]
        }
      ],
      "source": [
        "!pip install torchtext==0.15.1\n",
        "!pip install torch==2.0.0\n",
        "!pip install spacy==3.7.2\n",
        "!pip install torchdata==0.6.0\n",
        "!pip install portalocker>=2.0.0 #2.7.0\n",
        "!pip install nltk==3.8.1\n",
        "!pip install -U matplotlib\n",
        "\n",
        "!python -m spacy download en_core_web_sm\n",
        "!python -m spacy download de_core_news_sm"
      ],
      "execution_count": 2
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "366ef775-a916-4780-b1c1-9bf0fbdee35a"
      },
      "source": [
        "### Importing required libraries\n",
        "\n",
        "_It is recommended that you import all required libraries in one place (here):_\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "1ca16c73-7826-4379-ba4b-33978af70fef"
      },
      "outputs": [],
      "source": [
        "from torchtext.data.utils import get_tokenizer\n",
        "from torchtext.vocab import build_vocab_from_iterator\n",
        "from torchtext.datasets import multi30k, Multi30k\n",
        "from typing import Iterable, List\n",
        "from torch.nn.utils.rnn import pad_sequence\n",
        "from torch.utils.data import DataLoader\n",
        "from torchdata.datapipes.iter import IterableWrapper, Mapper\n",
        "import torchtext\n",
        "from torchtext.vocab import build_vocab_from_iterator\n",
        "from nltk.translate.bleu_score import sentence_bleu\n",
        "import torch\n",
        "import torch.nn as nn\n",
        "import torch.optim as optim\n",
        "\n",
        "\n",
        "import numpy as np\n",
        "import random\n",
        "import math\n",
        "import time\n",
        "from tqdm import tqdm\n",
        "import matplotlib.pyplot as plt\n",
        "\n",
        "\n",
        "# You can also use this section to suppress warnings generated by your code:\n",
        "def warn(*args, **kwargs):\n",
        "    pass\n",
        "import warnings\n",
        "warnings.warn = warn\n",
        "warnings.filterwarnings('ignore')"
      ],
      "execution_count": 3
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "0c7dd328-b1a3-491e-952b-f7fef2b3b5c8"
      },
      "source": [
        "## Background\n",
        "\n",
        "Sequence-to-sequence (Seq2seq) models have revolutionized various natural language processing (NLP) tasks, such as machine translation, text summarization, and chatbots. These models employ Recurrent Neural Networks (RNNs) to process variable-length input sequences and generate variable-length output sequences.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "ded3747a-cf2c-4e2d-be86-c7c43328a4ef"
      },
      "source": [
        "### History of sequence-to-sequence models\n",
        "\n",
        "Sequence-to-sequence models were introduced as an extension of traditional feedforward neural networks.\n",
        "Researchers realized the need for models that could handle variable-length input and output sequences, such as machine translation.\n",
        "The pioneering work of Sutskever et al. (2014) introduced the use of RNNs for seq2seq models.\n",
        "\n",
        "Here are some main objectives of seq2seq models:\n",
        "- Translation: Translating a sequence from one domain to another (e.g., English to French).\n",
        "- Question answering: Generating a natural language response given an input sentence (e.g., chatbots).\n",
        "- Summarization: Summarizing a long document into a shorter sequence of sentences.\n",
        "And many more applications that involve sequence generation.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "973217d2-c767-4d42-972a-ac452c00d641"
      },
      "source": [
        "### Introduction to RNNs\n",
        "\n",
        "RNNs are a class of neural networks designed to process sequential data.\n",
        "They maintain an internal memory($h_t$) to capture information from previous steps and use it for current predictions.\n",
        "RNNs have a recurrent connection that allows information to flow from one step to the next.\n",
        "Recurrent Neural Networks (RNNs) operate on sequences and utilize previous states to influence the current state. Here's the general formulation of a simple RNN:\n",
        "\n",
        "\n",
        "Given:\n",
        "\n",
        "-$ \\mathbf{x}_t $: input vector at time step $t$\n",
        "\n",
        "-$ \\mathbf{h}_{t-1} $: hidden state vector from the previous time step\n",
        "\n",
        "-$ \\mathbf{W}_x $ and $ \\mathbf{W}_h $: weight matrices for the input and hidden state, respectively\n",
        "\n",
        "-$ \\mathbf{b} $: bias vector\n",
        "\n",
        "-$\\sigma$: activation function (often a sigmoid or tanh)\n",
        "\n",
        "The update equations for the hidden state $ \\mathbf{h}_t $ and the output $ \\mathbf{y}_t $ are as follows:\n",
        "\n",
        "$$\n",
        "\\begin{align*}\n",
        "\\mathbf{h}_t &= \\sigma(\\mathbf{W}_x \\cdot \\mathbf{x}_t + \\mathbf{W}_h \\cdot \\mathbf{h}_{t-1} + \\mathbf{b})\n",
        "\\end{align*}\n",
        "$$\n",
        "\n",
        "It can be seen that the hidden state function depends on the previous hidden state as well as the input at time t, which is why it has a collective memory of previous time steps.\n",
        "\n",
        "For the output (if you're making a prediction at each time step):\n",
        "\n",
        "$$\n",
        "\\begin{align*}\n",
        "\\mathbf{y}_t &= \\text{softmax}(\\mathbf{W}_o \\cdot \\mathbf{h}_t + \\mathbf{b}_o)\n",
        "\\end{align*}\n",
        "$$\n",
        "\n",
        "Where:\n",
        "\n",
        "$ \\mathbf{W}_o $: weight matrix for the output AND $ \\mathbf{b}_o$: bias vector for the output\n",
        "\n",
        "\n",
        "\n",
        "Depending on the specific task, an RNN cell can either produce an output from $h_t$ or solely transfer it to the succeeding cell, serving as internal memory. While the architecture's ability to retain memory might seem elusive at first glance, let's elucidate this by implementing a simple RNN to handle the following data mechanism:\n",
        "\n",
        "![a title](https://cf-courses-data.s3.us.cloud-object-storage.appdomain.cloud/IBMSkillsNetwork-AI0205EN-SkillsNetwork/Screenshot%202023-10-19%20at%2011.29.23%E2%80%AFAM.png)\n",
        "\n",
        "\n",
        "The diagram showcases a state machine or transition model with three distinct states, depicted by the prominent purple circles. Each state is distinctly labeled with a value for $ h $: $ h = -1 $, $ h = 0 $, and $ h = 1 $.\n",
        "\n",
        "1. **State $ h = -1 $**:\n",
        "   - Maintains itself when $ x = 1 $ (illustrated by the yellow loop).\n",
        "   - Proceeds to the $ h = 0$ state upon receiving $ x = -1$ (highlighted by the red arrow).\n",
        "\n",
        "2. **State $ h = 0 $**:\n",
        "   - Moves to the $h = -1 $ state when $ x = 1$ (illustrated by the red arrow).\n",
        "   - Advances to the $ h = 1 $ state with $ x = -1$ (marked by the red arrow).\n",
        "\n",
        "3. **State $h = 1 $**:\n",
        "   - Sustains its position when $ x = -1 $ (indicated by the yellow loop).\n",
        "   - Transitions to the $ h = 0 $ state upon receiving $ x = 1 $ (signified by the red arrow).\n",
        "\n",
        "To encapsulate, the diagram effectively portrays transitions among three states based on the input $ x $. Contingent on the prevailing state and the input $ x $, the state machine either transitions to a different state or remains stationary.\n",
        "\n",
        "---\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "df46af95-bc66-4410-a0c3-aac7388a0dfd"
      },
      "source": [
        "\n",
        "You can represent the previously mentioned state machine using the layer detailed below. Use $tanh$ as the $h$ value should fall between [-1, 1]. Note that you have excluded the output for simplification:\n",
        "\n",
        "$$\\begin{align*}\n",
        "W_{xh} & = -10.0 \\\\\\\\\\\\\\\\\\\\\n",
        "W_{hh} & = 10.0 \\\\\n",
        "b_h & = 0.0 \\\\\n",
        "x_t & = 1 \\\\\n",
        "h_{\\text{prev}} & = 0.0 \\\\\n",
        "h_t & = \\tanh(x_t \\cdot W_{xh} + h_{\\text{prev}} \\cdot W_{hh} + b_h)\n",
        "\\end{align*}$$\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "c9cf6582-08cc-43c7-8f10-32703f6682d8"
      },
      "outputs": [],
      "source": [
        " W_xh=torch.tensor(-10.0)\n",
        " W_hh=torch.tensor(10.0)\n",
        " b_h=torch.tensor(0.0)\n",
        " x_t=1\n",
        " h_prev=torch.tensor(-1)"
      ],
      "execution_count": 4
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "753d750f-cf37-416a-a7fc-0ce80211515b"
      },
      "source": [
        "Consider the following sequence $x_t$ for  $t=0,1,..,7$,\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "ca56bf4a-c80b-4f6b-b1ca-625dd1f63e6b"
      },
      "outputs": [],
      "source": [
        "X=[1,1,-1,-1,1,1]"
      ],
      "execution_count": 5
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "1c15dafb-ccc2-4f02-9fd7-7a055da9ab5f"
      },
      "source": [
        "Assuming that you start from the intial state $h = 0$,  with the above input vector $x$, the state vector $h$ should look like this:\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "b07d18db-1cec-4937-bc83-1587fb572e79"
      },
      "outputs": [],
      "source": [
        "H=[-1,-1,0,1,0,-1]"
      ],
      "execution_count": 6
    },
    {
      "cell_type": "code",
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "a59f5699-865d-44dc-ad91-b501916b430c",
        "outputId": "5d46c9e5-c4ae-4a51-b915-92a607de8f71"
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "t= 1\n",
            "h_t-1 -1\n",
            "x_t 1\n",
            "h_t -1.0\n",
            "\n",
            "\n",
            "t= 2\n",
            "h_t-1 -1.0\n",
            "x_t 1\n",
            "h_t -1.0\n",
            "\n",
            "\n",
            "t= 3\n",
            "h_t-1 -1.0\n",
            "x_t -1\n",
            "h_t 0.0\n",
            "\n",
            "\n",
            "t= 4\n",
            "h_t-1 0.0\n",
            "x_t -1\n",
            "h_t 1.0\n",
            "\n",
            "\n",
            "t= 5\n",
            "h_t-1 1.0\n",
            "x_t 1\n",
            "h_t 0.0\n",
            "\n",
            "\n",
            "t= 6\n",
            "h_t-1 0.0\n",
            "x_t 1\n",
            "h_t -1.0\n",
            "\n",
            "\n"
          ]
        }
      ],
      "source": [
        "# Initialize an empty list to store the predicted state values\n",
        "H_hat = []\n",
        "# Loop through each data point in the input sequence X\n",
        "t=1\n",
        "for x in X:\n",
        "    # Assign the current data point to x_t\n",
        "    print(\"t=\",t)\n",
        "    x_t = x\n",
        "    # Print the value of the previous state (h at time t-1)\n",
        "    print(\"h_t-1\", h_prev.item())\n",
        "\n",
        "    # Compute the current state (h at time t) using the RNN formula with tanh activation\n",
        "    h_t = torch.tanh(x_t * W_xh + h_prev * W_hh + b_h)\n",
        "\n",
        "    # Update h_prev to the current state value for the next iteration\n",
        "    h_prev = h_t\n",
        "\n",
        "    # Print the current input value (x at time t)\n",
        "    print(\"x_t\", x_t)\n",
        "\n",
        "    # Print the computed state value (h at time t)\n",
        "    print(\"h_t\", h_t.item())\n",
        "    print(\"\\n\")\n",
        "\n",
        "    # Append the current state value to the H_hat list after converting it to integer\n",
        "    H_hat.append(int(h_t.item()))\n",
        "    t+=1\n"
      ],
      "execution_count": 7
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "3875db23-83a5-4655-ada1-dc8c1f4692dc"
      },
      "source": [
        "\n",
        "\n",
        "You can evaluate the accuracy of the predicted state ```H_hat``` by comparing it to the actual state ```H```. In RNNs, the state $ h_t $ is utilized to predict an output sequence $y_t $ based on the given input sequence $ x_t $.\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "61699165-c7a1-4ca7-8b7b-74f976680986",
        "outputId": "02161ed5-5e73-4b41-f66f-ec01a4d621eb"
      },
      "outputs": [
        {
          "output_type": "execute_result",
          "data": {
            "text/plain": [
              "[-1, -1, 0, 1, 0, -1]"
            ]
          },
          "metadata": {},
          "execution_count": 8
        }
      ],
      "source": [
        "H_hat"
      ],
      "execution_count": 8
    },
    {
      "cell_type": "code",
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "adeab630-ac5c-4d87-8d00-61de1dc72a7a",
        "outputId": "8c0d72e6-3233-456e-ab63-3bb8bfbccfae"
      },
      "outputs": [
        {
          "output_type": "execute_result",
          "data": {
            "text/plain": [
              "[-1, -1, 0, 1, 0, -1]"
            ]
          },
          "metadata": {},
          "execution_count": 9
        }
      ],
      "source": [
        "H"
      ],
      "execution_count": 9
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "0fe20815-190c-44f6-886a-9bf26e526660"
      },
      "source": [
        "While you have pre-defined the $W_{xh}$ and $W_{hh}$  and $b_h$, in practice these values need to be identified through training on data.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "a5acf032-3e86-458d-864c-3e25a4de5afa"
      },
      "source": [
        "In practice, modifications and enhancements, such as Long Short-Term Memory (LSTM) and Gated Recurrent Units (GRU), are often used to address issues like the vanishing gradient problem in basic RNNs.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "4af07ecb-b134-48dc-aa9f-4de239b726a7"
      },
      "source": [
        "An LSTM cell has three main components: an input gate, a forget gate, and an output gate.\n",
        "- The **input gate** controls how much new information should be stored in the cell's memory. It looks at the current input and the previous hidden state and decides which parts of the new input to remember.\n",
        "- The **forget gate** determines what information should be discarded or forgotten from the cell's memory. It considers the current input and the previous hidden state and decides which parts of the previous memory are no longer relevant.\n",
        "- The **output gate** determines what information should be outputted from the cell. It looks at the current input and the previous hidden state and decides which parts of the cell's memory to include in the output.\n",
        "\n",
        "The key idea behind LSTM cells is that they have a separate memory state that can selectively retain or forget information over time. This helps them handle long-range dependencies and remember important information from earlier steps in a sequence.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "b3e4e5c7-6f3b-4b26-a5c9-579622d70975"
      },
      "source": [
        "### Sequence-to-sequence architecture\n",
        "\n",
        "Seq2seq models have an Encoder-Decoder structure. The encoder encodes the input sequence into a fixed-dimensional representation, often called the context vector($h_t$). The decoder generates the output sequence based on the encoded context vector.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "303b7a32-ba19-41fb-a168-4886715f94bb"
      },
      "source": [
        "Let's look closer into the encoder and decoder boxes in the video below. Translation is a typical sequence-to-sequence task. The input is a sequence of words in the original language(\"I love to travel\"), while output is its translation in the destination language(\"J'adore voyager\"). As shown in the video, input is fed into the decoder part, one word after another. Each RNN cell receives a word($x_t$) and has an internal memory($h_t$). After processing the input and $h_t$, RNN cell passes an updated context vector($h_{t+1}$) to the next RNN cell. When the end of sentence is reached, the context vector is passed to the decoder part. Decoder cells are also RNN cells that receive context vector and generate the output word by word. Each RNN receives the generated word as well as the updated context vector from its previous cell and generates the next word($y_t$). This architecture allows for generating text without length restrictions.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "3ebf2969-ec44-4395-a676-5ced3df573e0"
      },
      "source": [
        "<video width=\"640\" height=\"480\"\n",
        "src=\"https://cf-courses-data.s3.us.cloud-object-storage.appdomain.cloud/IBMSkillsNetwork-AI0205EN-SkillsNetwork/Translation_RNN.mp4\"\n",
        "controls>\n",
        "</video>\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "b693fc3d-146b-4cec-9bad-6a1bbfe35154"
      },
      "source": [
        "## Encoder implementation in PyTorch\n",
        "\n",
        "To implement the encoder part using Pytorch, you will create the sub-class of the torch.nn.Module class and define the __init__() and __forward__() method.\n",
        "\n",
        "Let's first define the parameters that are used in __init__() function:\n",
        "- The `vocab_len` is nothing but the number of unique words present in the vocabulary. After pre-processing the data, you can count the number of unique words in your vocabulary and use that count here. This will be the dimension of the model input.\n",
        "- The embedding_dim is the output dimension of the embedding vector you need. A good practice is to use 256-512 for sample demo app like you are building here.\n",
        "- LSTM can indeed be stacked, allowing for multiple layers. In the initial implementation, you will use only one layer. However, to accommodate future flexibility, you will pass the parameter `n_layers` to specify the number of layers in the LSTM.\n",
        "- `hid_dim` is the dimensionality of the hidden and cell states.\n",
        "- `dropout` is the amount of dropout to use. This is a regularization parameter to prevent overfitting.\n",
        "\n",
        "Now, let's look into the layers:\n",
        "- The Embedding layer takes the input data and outputs the embedding vector, hence the dimension of those needs to be defined as `vocab_len` and `embedding_dim`.\n",
        "- The LSTM Layer takes the `embedding_dim` as the input data and creates total 3 outputs: `hidden`, `cell` and `output`. Here you need to define the number of neurons you need in LSTM, which is defined using the `hid_dim`.\n",
        "\n",
        "\n",
        "In the __forward__() function, the Embedding layer is defined that utilizes the `vocab_len` to internally convert the input_batch into a one-hot representation. Next, the LSTM layer receives the embedded input and outputs three vectors: Output, Hidden and cell. As for the encoder, you don't require the output vector from the LSTM as you only pass the context vector(`hidden`+`cell`) to the decoder block. Therefore, forward() only returns hidden and cell.\n",
        "\n",
        "Note: When using an LSTM, you have an additional cell state. However, if you were using a GRU, you would only have the hidden state.\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "45011fc8-9d54-49e9-ae5e-0dc5abf9b1c1"
      },
      "outputs": [],
      "source": [
        "class Encoder(nn.Module):\n",
        "    def __init__(self, vocab_len, emb_dim, hid_dim, n_layers, dropout_prob):\n",
        "        super().__init__()\n",
        "\n",
        "        self.hid_dim = hid_dim\n",
        "        self.n_layers = n_layers\n",
        "\n",
        "        self.embedding = nn.Embedding(vocab_len, emb_dim)\n",
        "\n",
        "        self.lstm = nn.LSTM(emb_dim, hid_dim, n_layers, dropout = dropout_prob)\n",
        "        self.dropout = nn.Dropout(dropout_prob)\n",
        "\n",
        "    def forward(self, input_batch):\n",
        "        #input_batch = [src len, batch size]\n",
        "        embed = self.dropout(self.embedding(input_batch))\n",
        "        embed = embed.to(device)\n",
        "        #outputs = [src len, batch size, hid dim * n directions]\n",
        "        #hidden = [n layers * n directions, batch size, hid dim]\n",
        "        #cell = [n layers * n directions, batch size, hid dim]\n",
        "        outputs, (hidden, cell) = self.lstm(embed)\n",
        "\n",
        "        return hidden, cell\n"
      ],
      "execution_count": 10
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "d93a75c2-ef97-4f1e-a07d-6192c8e71881"
      },
      "source": [
        "Now you are ready to create an encoder instance to see how it works:\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "648eac11-66bf-4e9e-ae3b-ac95ce054203"
      },
      "outputs": [],
      "source": [
        "vocab_len = 8\n",
        "emb_dim = 10\n",
        "hid_dim=8\n",
        "n_layers=1\n",
        "dropout_prob=0.5\n",
        "device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')\n",
        "\n",
        "encoder_t = Encoder(vocab_len, emb_dim, hid_dim, n_layers, dropout_prob).to(device)"
      ],
      "execution_count": 11
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "090cb2c7-db9a-4b7a-b4a1-30905e4b70b5"
      },
      "source": [
        "Let's see a simple example where the encoder forward method transforms the `src` sentence into a `hidden` and `cell` states. tensor([[0],[3],[4],[2],[1]]) is equal to `src` = 0,3,4,2,1 in which each number represents a token in the `src` vocabulary. For instance, 0:`<bos>`,3:\"Das\", 4:\"ist\",2:\"schön\", 1:`<eos>`. Note that here you have batch size of 1.\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "90d0a021-8c5b-461f-b707-9cc00b5003ce",
        "outputId": "a2abe6e0-05d7-4734-9b60-9b681b650816"
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "Shape of input(src) tensor: torch.Size([5, 1])\n",
            "Hidden tensor from encoder: tensor([[[ 0.3730, -0.0048,  0.2143,  0.0425,  0.1555,  0.0893, -0.0840,\n",
            "           0.0710]]], device='cuda:0', grad_fn=<CudnnRnnBackward0>) \n",
            "Cell tensor from encoder: tensor([[[ 0.5467, -0.0764,  0.6883,  0.0549,  0.3218,  0.1873, -0.5183,\n",
            "           0.3423]]], device='cuda:0', grad_fn=<CudnnRnnBackward0>)\n"
          ]
        }
      ],
      "source": [
        "src_batch = torch.tensor([[0,3,4,2,1]])\n",
        "# you need to transpose the input tensor as the encoder LSTM is in Sequence_first mode by default\n",
        "src_batch = src_batch.t().to(device)\n",
        "print(\"Shape of input(src) tensor:\", src_batch.shape)\n",
        "hidden_t , cell_t = encoder_t(src_batch)\n",
        "print(\"Hidden tensor from encoder:\",hidden_t ,\"\\nCell tensor from encoder:\", cell_t)"
      ],
      "execution_count": 12
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "92a62a7c-2739-4a57-90b3-4875e0a19966"
      },
      "source": [
        "The encoder takes the entire source sequence as input, which consists of a sequence of words or tokens. The encoder LSTM processes the entire input sequence and updates its hidden states at each time step. The hidden states of the LSTM network act as a form of memory and capture the contextual information of the input sequence. After processing the entire input sequence, the final hidden state of the encoder LSTM captures the summarized representation of the input sequence's context. This final hidden state is sometimes referred to as the \"context vector\".\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "1c59903e-8a1f-40f8-8b50-7a5f751a3e7b"
      },
      "source": [
        "## Decoder implementation in PyTorch\n",
        "\n",
        "To have a better understanding of the internal mechanism of the decoder part, let's take a closer look into it:\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "63334e95-9a51-4e6e-8c2b-11dba411506f"
      },
      "source": [
        "<video width=\"640\" height=\"480\"\n",
        "       src=\"https://cf-courses-data.s3.us.cloud-object-storage.appdomain.cloud/IBMSkillsNetwork-AI0205EN-SkillsNetwork/decoder_RNN.mp4\"\n",
        "       controls>\n",
        "</video>\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "ee2d469a-be4d-4036-85a9-2d9a6271aa51"
      },
      "source": [
        "The decoder class inherits from nn.Module, which is a base class for all neural network modules in PyTorch.\n",
        "The constructor (__init__ method) initializes the parameters and layers of the decoder.\n",
        "- `output_dim` is the number of possible output values(target vocab length).\n",
        "- `emb_dim` is the dimensionality of the embedding layer.\n",
        "- `hid_dim` is the dimensionality of the hidden state in the LSTM.\n",
        "- `n_layers` is the number of layers in the LSTM.\n",
        "- `dropout` is the dropout probability.\n",
        "\n",
        "The decoder contains the following layers:\n",
        "- `embedding`: An embedding layer that maps the output values to dense vectors of size emb_dim.\n",
        "- `lstm`: An LSTM layer that takes the embedded input and produces hidden states of size hid_dim.\n",
        "-  `fc_out`: A linear layer that maps the LSTM output to the output dimension output_dim.\n",
        "- `softmax`: A log-softmax activation function applied to the output to obtain a probability distribution over the output values.\n",
        "- `dropout`: A dropout layer that applies dropout to the embedded input.\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "8b99e359-f663-4e83-bfca-7b695ee4cd9c"
      },
      "outputs": [],
      "source": [
        "class Decoder(nn.Module):\n",
        "    def __init__(self, output_dim, emb_dim, hid_dim, n_layers, dropout):\n",
        "        super().__init__()\n",
        "\n",
        "        self.output_dim = output_dim\n",
        "        self.hid_dim = hid_dim\n",
        "        self.n_layers = n_layers\n",
        "\n",
        "\n",
        "        self.embedding = nn.Embedding(output_dim, emb_dim)\n",
        "        self.lstm = nn.LSTM(emb_dim, hid_dim, n_layers, dropout = dropout)\n",
        "        self.fc_out = nn.Linear(hid_dim, output_dim)\n",
        "        self.softmax = nn.LogSoftmax(dim=1)\n",
        "        self.dropout = nn.Dropout(dropout)\n",
        "\n",
        "    def forward(self, input, hidden, cell):\n",
        "\n",
        "\n",
        "        #input = [batch size]\n",
        "\n",
        "        #hidden = [n layers * n directions, batch size, hid dim]\n",
        "        #cell = [n layers * n directions, batch size, hid dim]\n",
        "\n",
        "        #n directions in the decoder will both always be 1, therefore:\n",
        "        #hidden = [n layers, batch size, hid dim]\n",
        "        #context = [n layers, batch size, hid dim]\n",
        "\n",
        "        input = input.unsqueeze(0)\n",
        "        #input = [1, batch size]\n",
        "\n",
        "        embedded = self.dropout(self.embedding(input))\n",
        "        #embedded = [1, batch size, emb dim]\n",
        "\n",
        "        output, (hidden, cell) = self.lstm(embedded, (hidden, cell))\n",
        "        #output = [seq len, batch size, hid dim * n directions]\n",
        "        #hidden = [n layers * n directions, batch size, hid dim]\n",
        "        #cell = [n layers * n directions, batch size, hid dim]\n",
        "\n",
        "        #seq len and n directions will always be 1 in the decoder, therefore:\n",
        "        #output = [1, batch size, hid dim]\n",
        "        #hidden = [n layers, batch size, hid dim]\n",
        "        #cell = [n layers, batch size, hid dim]\n",
        "        prediction_logit = self.fc_out(output.squeeze(0))\n",
        "        prediction = self.softmax(prediction_logit)\n",
        "        #prediction = [batch size, output dim]\n",
        "\n",
        "\n",
        "        return prediction, hidden, cell"
      ],
      "execution_count": 13
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "98285edd-144b-47d1-95a6-cbf6f99dc069"
      },
      "source": [
        "You can create a decoder instance. The output dimension is set as the target vocab length.\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "167fcc3a-e542-4743-a652-68c92b6eafc1"
      },
      "outputs": [],
      "source": [
        "output_dim = 6\n",
        "emb_dim=10\n",
        "hid_dim = 8\n",
        "n_layers=1\n",
        "dropout=0.5\n",
        "decoder_t = Decoder(output_dim, emb_dim, hid_dim, n_layers, dropout).to(device)"
      ],
      "execution_count": 14
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "0bc70c84-c5db-400f-b088-62273776330b"
      },
      "source": [
        "Now that you have instances of both encoder and decoder, you are ready to connect them (the red box in the diagram below). First, let's see how you can pass the Hidden and Cell (the pink cell within the red box) from encoder (the green boxes container) to decoder (the orange boxes container). Looking at the diagram, you can see that the decoder also receives an input which is the previous word that it has predicted. For the first decoder cell, this input is `<bos>` token. Each decoder cell outputs a prediction and updates the cell and state to pass to the next decoder cell. prediction is a probability distribution over possible target tokens (length of target vocab).\n",
        "\n",
        "![connection](https://cf-courses-data.s3.us.cloud-object-storage.appdomain.cloud/IBMSkillsNetwork-AI0205EN-SkillsNetwork/ED_connection.JPG)\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "d590e1db-9ba4-4311-a449-1edd64c79ff6",
        "outputId": "f78e5f87-2299-4a4f-d2b5-202123111518"
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "Prediction: tensor([[-1.7006, -1.6016, -1.8650, -1.7531, -2.1922, -1.7369]],\n",
            "       device='cuda:0', grad_fn=<LogSoftmaxBackward0>) \n",
            "Hidden: tensor([[[ 0.0358, -0.1843, -0.0659,  0.1072, -0.0617, -0.1636,  0.0276,\n",
            "           0.1047]]], device='cuda:0', grad_fn=<CudnnRnnBackward0>) \n",
            "Cell: tensor([[[ 0.0609, -0.3411, -0.6068,  0.1261, -0.1666, -0.4870,  0.0692,\n",
            "           0.2762]]], device='cuda:0', grad_fn=<CudnnRnnBackward0>)\n"
          ]
        }
      ],
      "source": [
        "input_t = torch.tensor([0]).to(device) #<bos>\n",
        "input_t.shape\n",
        "prediction, hidden, cell = decoder_t(input_t, hidden_t , cell_t)\n",
        "print(\"Prediction:\", prediction, '\\nHidden:',hidden,'\\nCell:', cell)"
      ],
      "execution_count": 15
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "6a2216ec-7db9-412b-87c4-cfef1b34f3d0"
      },
      "source": [
        "# Encoder-decoder connection\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "db8234fa-2bc6-45ce-b4b4-b554a3219c15"
      },
      "source": [
        "Alright! You learned how to create encoder and decoder modules and how to pass input to them. Now you need to create the connection so that the model can process (`src`,`trg`) pairs and generate the translation. suppose that `trg` is tensor ([[0],[2],[3],[5],[1]]) which is equal to sequence 0,2,3,5,1 in which each number represents a token in the target vocabulary. For instance, 0:`<bos>`,2:\"this\", 3:\"is\",5:\"beautiful\", 1:`<eos>`.\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "f2db7ee3-b3bd-491d-b0a9-ef5a00bca46c",
        "outputId": "7cf8cf86-2ce9-4ce3-f335-ff0ce3ed2d21"
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "tensor([[[ 0.0000,  0.0000,  0.0000,  0.0000,  0.0000,  0.0000]],\n",
            "\n",
            "        [[-1.7164, -1.5268, -1.9465, -1.6807, -2.2635, -1.7716]],\n",
            "\n",
            "        [[-1.7135, -1.5394, -1.7321, -1.7873, -2.2011, -1.8954]],\n",
            "\n",
            "        [[-1.6889, -1.5266, -1.8480, -1.6595, -2.2022, -1.9684]],\n",
            "\n",
            "        [[-1.6326, -1.5542, -1.8792, -1.6894, -2.2588, -1.8877]]],\n",
            "       device='cuda:0', grad_fn=<CopySlices>) torch.Size([5, 1, 6])\n"
          ]
        }
      ],
      "source": [
        "\n",
        "#trg = [trg len, batch size]\n",
        "#teacher_forcing_ratio is probability to use teacher forcing\n",
        "#e.g. if teacher_forcing_ratio is 0.75 you use ground-truth inputs 75% of the time\n",
        "teacher_forcing_ratio = 0.5\n",
        "trg = torch.tensor([[0],[2],[3],[5],[1]]).to(device)\n",
        "\n",
        "\n",
        "batch_size = trg.shape[1]\n",
        "trg_len = trg.shape[0]\n",
        "trg_vocab_size = decoder_t.output_dim\n",
        "\n",
        "#tensor to store decoder outputs\n",
        "outputs_t = torch.zeros(trg_len, batch_size, trg_vocab_size).to(device)\n",
        "\n",
        "#send to device\n",
        "\n",
        "hidden_t = hidden_t.to(device)\n",
        "cell_t = cell_t.to(device)\n",
        "\n",
        "\n",
        "#first input to the decoder is the <bos> tokens\n",
        "input = trg[0,:]\n",
        "\n",
        "\n",
        "for t in range(1, trg_len):\n",
        "\n",
        "    #you loop through the trg len and generate tokens\n",
        "    #decoder receives previous generated token, cell and hidden\n",
        "    # decoder outputs it prediction(probablity distribution for the next token) and updates hidden and cell\n",
        "    output_t, hidden_t, cell_t = decoder_t(input, hidden_t, cell_t)\n",
        "\n",
        "    #place predictions in a tensor holding predictions for each token\n",
        "    outputs_t[t] = output_t\n",
        "\n",
        "    #decide if you are going to use teacher forcing or not\n",
        "    teacher_force = random.random() < teacher_forcing_ratio\n",
        "\n",
        "    #get the highest predicted token from your predictions\n",
        "    top1 = output_t.argmax(1)\n",
        "\n",
        "\n",
        "    #if teacher forcing, use actual next token as next input\n",
        "    #if not, use predicted token\n",
        "    #input = trg[t] if teacher_force else top1\n",
        "    input = trg[t] if teacher_force else top1\n",
        "\n",
        "print(outputs_t,outputs_t.shape )"
      ],
      "execution_count": 16
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "ee142d10-642c-48c5-8dc3-2066304a289c"
      },
      "source": [
        "The size of output tensor is (trg_len, batch_size, trg_vocab_size). This is because for each `trg` token (length of `trg`) the model outputs a probability distribution over all possible tokens(trg vocab length). Therefore, to generate the predicted tokens or translation of the `src` sentence, you need to get the maximum probability for each token:\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "8caf88d6-6561-4cb4-a2ba-a03ac20397d6",
        "outputId": "b376470f-cf6e-4273-d3c7-644f4a7f13e0"
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "tensor([[0],\n",
            "        [1],\n",
            "        [1],\n",
            "        [1],\n",
            "        [1]], device='cuda:0')\n"
          ]
        }
      ],
      "source": [
        "# Note that you need to get the argmax from the second dimension as **outputs** is an array of **output** tensors\n",
        "pred_tokens = outputs_t.argmax(2)\n",
        "print(pred_tokens)"
      ],
      "execution_count": 17
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "53c476e4-01ab-4976-96d0-ea748c688be6"
      },
      "source": [
        "It is no surprise that the translation is not correct (trg = tensor([[0],[2],[3],[5],[1]]) as the model has not yet gone through any training.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "f2187525-773f-4c94-b014-1c0a1e4ca0cf"
      },
      "source": [
        "Let's put together all the code for connecting the encoder and decoder in a seq2seq class for better usability.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "2afd6366-9f4c-4677-81aa-3d0d54065dba"
      },
      "source": [
        "## Sequence-to-sequence model implementation in PyTorch\n",
        "Let's connect encoder and decoder components to create the seq2seq model.\n",
        "\n",
        "You define the seq2seq class that inherits from nn.Module, which is the base class for all neural network modules in PyTorch.\n",
        "Inputs are:\n",
        "- `encoder` and `decoder` are instances of the encoder and decoder networks that you have already defined.\n",
        "- `device` specifies the device (e.g., CPU or GPU) on which the computations will be performed.\n",
        "- `trg_vocab` represents the vocabulary of the target language. It is used to determine the size of the output vocabulary.\n",
        "\n",
        "**forward** method defines the forward pass of the seq2seq model. It takes three arguments: `src`, `trg`, and `teacher_forcing_ratio`.:\n",
        "\n",
        "- `src` represents the source sequences, and `trg` represents the target sequences.\n",
        "- `teacher_forcing_ratio` is a probability that determines whether teacher forcing will be used during training only. Teacher forcing is a technique where the true target sequence is fed as input to the decoder at each time step, instead of using the predicted output from the previous time step.\n",
        "\n",
        "The **forward** method initializes some variables needed for the forward pass, such as `batch_size`, `trg_len`, and `trg_vocab_size`. It also creates an empty tensor called `outputs` to store the decoder outputs for each time step.\n",
        "\n",
        "The `hidden` and `cell` states of the encoder are obtained by calling the encoder (src) method. These states are then used as the initial states for the decoder.\n",
        "\n",
        "The input to the decoder at the first time step is the <bos> token of the target sequences.\n",
        "\n",
        "The decoder is iterated over for each time step in the target sequences (`for t in range(1, trg_len)`). The input, along with the previous hidden and cell states, is passed to the decoder, and it produces an output tensor. The `output` tensor is stored in the `outputs` tensor.\n",
        "\n",
        "At each time step, there is a decision made whether to use teacher forcing or not based on the teacher_forcing_ratio probability. If teacher forcing is used, the true next token from the target sequences (`trg[t]`) is used as the input for the next time step. Otherwise, the predicted token from the previous time step (`top1 = output.argmax(1)`) is used.\n",
        "\n",
        "Finally, the `outputs` tensor containing the predicted outputs for each time step is returned.\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "2d910f77-d521-4ea7-bd7a-0d006e3bf999"
      },
      "outputs": [],
      "source": [
        "class Seq2Seq(nn.Module):\n",
        "    def __init__(self, encoder, decoder, device,trg_vocab):\n",
        "        super().__init__()\n",
        "\n",
        "        self.encoder = encoder\n",
        "        self.decoder = decoder\n",
        "        self.device = device\n",
        "        self.trg_vocab = trg_vocab\n",
        "\n",
        "        assert encoder.hid_dim == decoder.hid_dim, \\\n",
        "            \"Hidden dimensions of encoder and decoder must be equal!\"\n",
        "        assert encoder.n_layers == decoder.n_layers, \\\n",
        "            \"Encoder and decoder must have equal number of layers!\"\n",
        "\n",
        "    def forward(self, src, trg, teacher_forcing_ratio = 0.5):\n",
        "        #src = [src len, batch size]\n",
        "        #trg = [trg len, batch size]\n",
        "        #teacher_forcing_ratio is probability to use teacher forcing\n",
        "        #e.g. if teacher_forcing_ratio is 0.75 you use ground-truth inputs 75% of the time\n",
        "\n",
        "\n",
        "        batch_size = trg.shape[1]\n",
        "        trg_len = trg.shape[0]\n",
        "        trg_vocab_size = self.decoder.output_dim\n",
        "\n",
        "        #tensor to store decoder outputs\n",
        "        outputs = torch.zeros(trg_len, batch_size, trg_vocab_size).to(self.device)\n",
        "\n",
        "        #last hidden state of the encoder is used as the initial hidden state of the decoder\n",
        "        hidden, cell = self.encoder(src)\n",
        "        hidden = hidden.to(device)\n",
        "        cell = cell.to(device)\n",
        "\n",
        "\n",
        "        #first input to the decoder is the <bos> tokens\n",
        "        input = trg[0,:]\n",
        "\n",
        "        for t in range(1, trg_len):\n",
        "\n",
        "            #insert input token embedding, previous hidden and previous cell states\n",
        "            #receive output tensor (predictions) and new hidden and cell states\n",
        "            output, hidden, cell = self.decoder(input, hidden, cell)\n",
        "\n",
        "            #place predictions in a tensor holding predictions for each token\n",
        "            outputs[t] = output\n",
        "\n",
        "            #decide if you are going to use teacher forcing or not\n",
        "            teacher_force = random.random() < teacher_forcing_ratio\n",
        "\n",
        "            #get the highest predicted token from your predictions\n",
        "            top1 = output.argmax(1)\n",
        "\n",
        "\n",
        "            #if teacher forcing, use actual next token as next input\n",
        "            #if not, use predicted token\n",
        "            #input = trg[t] if teacher_force else top1\n",
        "            input = trg[t] if teacher_force else top1\n",
        "\n",
        "\n",
        "        return outputs"
      ],
      "execution_count": 18
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "e041739c-022c-409f-8520-4a0f365331a0"
      },
      "source": [
        "## Training model in PyTorch\n",
        "Now that the model is defined, you define a train function the seq2seq model. Let's go through the code and understand its components:\n",
        "\n",
        "1. `train(model, iterator, optimizer, criterion, clip)` takes five arguments:\n",
        "\n",
        "   - `model` is the model that will be trained.\n",
        "   - `iterator` is an iterable object that provides the training data in batches.\n",
        "   - `optimizer` is the optimization algorithm used to update the model's parameters.\n",
        "   - `criterion` is the loss function that measures the model's performance.\n",
        "   - `clip` is a value used to clip the gradients to prevent them from becoming too large during backpropagation.\n",
        "\n",
        "2. The function starts by setting the model to training mode with `model.train()`. This is necessary to enable certain layers (e.g., dropout) that behave differently during training and evaluation.\n",
        "\n",
        "3. It initializes a variable `epoch_loss` to keep track of the accumulated loss during the epoch.\n",
        "\n",
        "4. The function iterates over the training data provided by the `iterator`. Each iteration retrieves a batch of input sequences (`src`) and target sequences (`trg`).\n",
        "\n",
        "5. The input sequences (`src`) and target sequences (`trg`) are moved to the appropriate device (e.g., GPU) using `src = src.to(device)` and `trg = trg.to(device)`.\n",
        "\n",
        "6. The gradients of the model's parameters are cleared using `optimizer.zero_grad()` to prepare for the new batch.\n",
        "\n",
        "7. The model is then called with `output = model(src, trg)` to obtain the model's predictions for the target sequences.\n",
        "\n",
        "8. The `output` tensor has dimensions `[trg len, batch size, output dim]`. To calculate the loss, the tensor is reshaped to `[trg len - 1, batch size, output dim]` to remove the initial `<bos>` token, which is not used for calculating the loss.\n",
        "\n",
        "9. The target sequences (`trg`) are also reshaped to `[trg len - 1]` by removing the initial `<bos>` token and making it a contiguous tensor. This matches the shape of the reshaped `output` tensor.\n",
        "\n",
        "10. The loss between the reshaped `output` and `trg` tensors is calculated using the specified `criterion`.\n",
        "\n",
        "11. The gradients of the loss with respect to the model's parameters are computed using `loss.backward()`.\n",
        "\n",
        "12. The gradients are then clipped to a maximum value specified by `clip` using `torch.nn.utils.clip_grad_norm_(model.parameters(), clip)`. This prevents the gradients from becoming too large, which can cause issues during optimization.\n",
        "\n",
        "13. The optimizer's `step()` method is called to update the model's parameters using the computed gradients.\n",
        "\n",
        "14. The current batch loss (`loss.item()`) is added to the `epoch_loss` variable.\n",
        "\n",
        "15. After all the batches have been processed, the function returns the average loss per batch for the entire epoch, calculated as `epoch_loss / len(list(iterator))`.\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "20e98bc1-e508-4d1c-8e92-64626d4654c4"
      },
      "outputs": [],
      "source": [
        "def train(model, iterator, optimizer, criterion, clip):\n",
        "\n",
        "    model.train()\n",
        "\n",
        "    epoch_loss = 0\n",
        "\n",
        "    # Wrap iterator with tqdm for progress logging\n",
        "    train_iterator = tqdm(iterator, desc=\"Training\", leave=False)\n",
        "\n",
        "    for i, (src,trg) in enumerate(iterator):\n",
        "\n",
        "        src = src.to(device)\n",
        "        trg = trg.to(device)\n",
        "        optimizer.zero_grad()\n",
        "\n",
        "        output = model(src, trg)\n",
        "\n",
        "        #trg = [trg len, batch size]\n",
        "        #output = [trg len, batch size, output dim]\n",
        "\n",
        "        output_dim = output.shape[-1]\n",
        "\n",
        "        output = output[1:].view(-1, output_dim)\n",
        "\n",
        "        trg = trg[1:].contiguous().view(-1)\n",
        "\n",
        "        #trg = [(trg len - 1) * batch size]\n",
        "        #output = [(trg len - 1) * batch size, output dim]\n",
        "\n",
        "        loss = criterion(output, trg)\n",
        "\n",
        "        loss.backward()\n",
        "\n",
        "        torch.nn.utils.clip_grad_norm_(model.parameters(), clip)\n",
        "\n",
        "        optimizer.step()\n",
        "\n",
        "        # Update tqdm progress bar with the current loss\n",
        "        train_iterator.set_postfix(loss=loss.item())\n",
        "\n",
        "        epoch_loss += loss.item()\n",
        "\n",
        "\n",
        "    return epoch_loss / len(list(iterator))"
      ],
      "execution_count": 19
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "ee30ccdc-f849-4c57-9818-2f3dc6ab8107"
      },
      "source": [
        "## Evaluating model in PyTorch\n",
        "You also need to define a function to evaluate the model. Let's go through the code and understand its components:\n",
        "\n",
        "1. `evaluate(model, iterator, criterion)` takes three arguments:\n",
        "   - `model` is the neural network model that will be evaluated.\n",
        "   - `iterator` is an iterable object that provides the evaluation data in batches.\n",
        "   - `criterion` is the loss function that measures the model's performance.\n",
        "* Note that evaluate function do not perform any optimization on the model.\n",
        "\n",
        "2. The function starts by setting the model to evaluation mode with `model.eval()`.\n",
        "\n",
        "3. It initializes a variable `epoch_loss` to keep track of the accumulated loss during the evaluation.\n",
        "\n",
        "4. The function enters a `with torch.no_grad()` block, which ensures that no gradients are computed during the evaluation. This saves memory and speeds up the evaluation process since gradients are not needed for parameter updates.\n",
        "\n",
        "5. The function iterates over the evaluation data provided by the `iterator`. Each iteration retrieves a batch of input sequences (`src`) and target sequences (`trg`).\n",
        "\n",
        "6. The input sequences (`src`) and target sequences (`trg`) are moved to the appropriate device (e.g., GPU) using `src = src.to(device)` and `trg = trg.to(device)`.\n",
        "\n",
        "7. The model is then called with `output = model(src, trg, 0)` to obtain the model's predictions for the target sequences. The third argument `0` is passed to indicate that teacher forcing is turned off during evaluation.  During evaluation, teacher forcing is typically turned off to evaluate the model's ability to generate sequences based on its own predictions.\n",
        "\n",
        "8. The `output` tensor has dimensions `[trg len, batch size, output dim]`. To calculate the loss, the tensor is reshaped to `[trg len - 1, batch size, output dim]` to remove the initial `<bos>` (beginning of sequence) token, which is not used for calculating the loss.\n",
        "\n",
        "9. The target sequences (`trg`) are also reshaped to `[trg len - 1]` by removing the initial `<bos>` token and making it a contiguous tensor. This matches the shape of the reshaped `output` tensor.\n",
        "\n",
        "10. The loss between the reshaped `output` and `trg` tensors is calculated using the specified `criterion`.\n",
        "\n",
        "11. The current batch loss (`loss.item()`) is added to the `epoch_loss` variable.\n",
        "\n",
        "12. After all the batches have been processed, the function returns the average loss per batch for the entire evaluation, calculated as `epoch_loss / len(list(iterator))`.\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "d2302dad-5fc5-490c-a4ab-347e29800a4b"
      },
      "outputs": [],
      "source": [
        "def evaluate(model, iterator, criterion):\n",
        "\n",
        "    model.eval()\n",
        "\n",
        "    epoch_loss = 0\n",
        "\n",
        "    # Wrap iterator with tqdm for progress logging\n",
        "    valid_iterator = tqdm(iterator, desc=\"Training\", leave=False)\n",
        "\n",
        "    with torch.no_grad():\n",
        "\n",
        "        for i, (src,trg) in enumerate(iterator):\n",
        "\n",
        "            src = src.to(device)\n",
        "            trg = trg.to(device)\n",
        "\n",
        "            output = model(src, trg, 0) #turn off teacher forcing\n",
        "\n",
        "            #trg = [trg len, batch size]\n",
        "            #output = [trg len, batch size, output dim]\n",
        "\n",
        "            output_dim = output.shape[-1]\n",
        "\n",
        "            output = output[1:].view(-1, output_dim)\n",
        "\n",
        "            trg = trg[1:].contiguous().view(-1)\n",
        "\n",
        "\n",
        "            #trg = [(trg len - 1) * batch size]\n",
        "            #output = [(trg len - 1) * batch size, output dim]\n",
        "\n",
        "            loss = criterion(output, trg)\n",
        "            # Update tqdm progress bar with the current loss\n",
        "            valid_iterator.set_postfix(loss=loss.item())\n",
        "\n",
        "            epoch_loss += loss.item()\n",
        "\n",
        "    return epoch_loss / len(list(iterator))"
      ],
      "execution_count": 20
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "28f48608-1ade-435a-b257-5e9b0edfe47a"
      },
      "source": [
        "## Data preprocessing\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "9987a78e-7597-469d-beaa-2a401c71d63b"
      },
      "source": [
        "In this section, you will fetch a language translation dataset called Multi30k, collate it (tokenization, numericalization, and adding BOS/EOS and padding) and create iterable batches of src and trg tensors.\n",
        "\n",
        "This leverages the predefined collate_fn to efficiently curate and ready batches for training the transformer model. The primary aim is to delve deeper into the intricacies of the RNN encoder and decoder components.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "8c96ef88-3a86-4e2e-8ca9-ddb8a602f428"
      },
      "source": [
        "A \"Multi30K_de_en_dataloader.py\" file has been created that contains all the transformation processes on data. Here, you only download the file:\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "d37808c5-4bd6-4802-ba9f-ff6d16ecb112",
        "outputId": "19e34f16-2da2-4c08-a863-e1c7d02f659c"
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "--2024-12-02 19:07:20--  https://cf-courses-data.s3.us.cloud-object-storage.appdomain.cloud/IBMSkillsNetwork-AI0205EN-SkillsNetwork/Multi30K_de_en_dataloader.py\n",
            "Resolving cf-courses-data.s3.us.cloud-object-storage.appdomain.cloud (cf-courses-data.s3.us.cloud-object-storage.appdomain.cloud)... 198.23.119.245\n",
            "Connecting to cf-courses-data.s3.us.cloud-object-storage.appdomain.cloud (cf-courses-data.s3.us.cloud-object-storage.appdomain.cloud)|198.23.119.245|:443... connected.\n",
            "HTTP request sent, awaiting response... 200 OK\n",
            "Length: 4890 (4.8K) [application/x-python]\n",
            "Saving to: ‘Multi30K_de_en_dataloader.py’\n",
            "\n",
            "Multi30K_de_en_data 100%[===================>]   4.78K  --.-KB/s    in 0s      \n",
            "\n",
            "2024-12-02 19:07:21 (1.05 GB/s) - ‘Multi30K_de_en_dataloader.py’ saved [4890/4890]\n",
            "\n"
          ]
        }
      ],
      "source": [
        "!wget 'https://cf-courses-data.s3.us.cloud-object-storage.appdomain.cloud/IBMSkillsNetwork-AI0205EN-SkillsNetwork/Multi30K_de_en_dataloader.py'"
      ],
      "execution_count": 21
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "85e1e2b7-5373-4249-a9cc-1908d8f52c88"
      },
      "source": [
        "Let's run it:\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "49755a6c-563e-47a0-b8f9-455dbe545f2b"
      },
      "outputs": [],
      "source": [
        "%run Multi30K_de_en_dataloader.py"
      ],
      "execution_count": 22
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "47c9bf3c-59f8-44f0-b2c6-dd2813c08fc7"
      },
      "source": [
        "There you go! You only need to call the function `get_translation_dataloaders(batch_size = N,flip=True)` with an arbitrary batch size `N` and setting flip to True in order for the LSTM encoder receive input sequence in reversed order. This can help the training.\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "1b7b161c-515f-4ea3-aaff-c67536289773"
      },
      "outputs": [],
      "source": [
        "train_dataloader, valid_dataloader = get_translation_dataloaders(batch_size = 4)#,flip=True)"
      ],
      "execution_count": 23
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "74389308-e0f1-4f5f-bd7c-4dd3d301b08e"
      },
      "source": [
        "You can check the `src` and `trg` tensors:\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "f3ac9719-b7ff-4659-96ff-567eccb80adc",
        "outputId": "f727bf83-f1c6-41dc-ca0f-f5e3d48babdc"
      },
      "outputs": [
        {
          "output_type": "execute_result",
          "data": {
            "text/plain": [
              "(tensor([[    2,     2,     2,     2],\n",
              "         [    3,  5510,  5510, 12642],\n",
              "         [    1,     3,     3,     8],\n",
              "         [    1,     1,     1,  1701],\n",
              "         [    1,     1,     1,     3]], device='cuda:0'),\n",
              " tensor([[   2,    2,    2,    2],\n",
              "         [   3, 6650,  216,    6],\n",
              "         [   1, 4623,  110, 3398],\n",
              "         [   1,  259, 3913,  202],\n",
              "         [   1,  172, 1650,  109],\n",
              "         [   1, 9953, 3823,   37],\n",
              "         [   1,  115,   71,    3],\n",
              "         [   1,  692, 2808,    1],\n",
              "         [   1, 3428, 2187,    1],\n",
              "         [   1,    5,    5,    1],\n",
              "         [   1,    3,    3,    1]], device='cuda:0'))"
            ]
          },
          "metadata": {},
          "execution_count": 24
        }
      ],
      "source": [
        "src, trg = next(iter(train_dataloader))\n",
        "src,trg"
      ],
      "execution_count": 24
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "f0e49b6a-6c55-4b7a-aaa8-b9b90b1fb180"
      },
      "source": [
        "You can also get the english and german strings using `index_to_eng` and `index_to_german` functions provided in the .py file:\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "fc2c9a8d-f56d-4914-a702-3b492d41e637",
        "outputId": "f515a631-3fb1-4312-c5ba-32db9741752b"
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "________________\n",
            "german\n",
            "<bos> Personen mit schwarzen Hüten in der Innenstadt . <eos>\n",
            "<bos> Eine Gruppe Menschen protestiert in einer Stadt . <eos>\n",
            "<bos> Eine Gruppe teilt ihre politischen Ansichten mit . <eos>\n",
            "<bos> Mehrere Personen sitzen an einem felsigen Strand . <eos>\n",
            "________________\n",
            "english\n",
            "<bos> People in black hats gathered together downtown . <eos> <pad> <pad> <pad>\n",
            "<bos> A group of people protesting in a city . <eos> <pad> <pad>\n",
            "<bos> A group is letting their political opinion be known . <eos> <pad>\n",
            "<bos> A group of people are sitting on a rocky beach . <eos>\n",
            "________________\n",
            "german\n",
            "<bos> Zwei sitzende Personen mit Hüten und Sonnenbrillen . <eos>\n",
            "<bos> Ein kleiner Junge mit Hut beim Angeln . <eos>\n",
            "<bos> Diese zwei Frauen haben Spaß im Giorgio's . <eos>\n",
            "<bos> Zwei kleine Kinder schlafen auf dem Sofa . <eos>\n",
            "________________\n",
            "english\n",
            "<bos> Two people sitting in hats and shades . <eos> <pad> <pad> <pad>\n",
            "<bos> A young boy in a hat is fishing by himself . <eos>\n",
            "<bos> These two women is at Giorgio 's having fun . <eos> <pad>\n",
            "<bos> Two young children are asleep on a couch . <eos> <pad> <pad>\n",
            "________________\n",
            "german\n",
            "<bos> Zwei junge Mädchen marschieren in einem Umzug . <eos>\n",
            "<bos> Eine Frau läuft vor einer gestreiften Wand . <eos>\n",
            "<bos> Ein Mann fährt Jet-Ski auf dem Ozean . <eos>\n",
            "<bos> Die städtischen Straßenbahnen an einem sonnigen Tag . <eos>\n",
            "________________\n",
            "english\n",
            "<bos> Two young girls walk in a parade . <eos> <pad> <pad> <pad> <pad>\n",
            "<bos> A woman is running in front of a striped wall . <eos> <pad>\n",
            "<bos> A man rides a jet ski across the ocean . <eos> <pad> <pad>\n",
            "<bos> The urban trolly 's of a city on a sunny day . <eos>\n"
          ]
        }
      ],
      "source": [
        "data_itr = iter(train_dataloader)\n",
        "# moving forward in the dataset to reach sequences of longer length for illustration purpose. (Remember the dataset is sorted on sequence len for optimal padding)\n",
        "for n in range(1000):\n",
        "    german, english= next(data_itr)\n",
        "\n",
        "for n in range(3):\n",
        "    german, english=next(data_itr)\n",
        "    german=german.T\n",
        "    english=english.T\n",
        "    print(\"________________\")\n",
        "    print(\"german\")\n",
        "    for g in german:\n",
        "        print(index_to_german(g))\n",
        "    print(\"________________\")\n",
        "    print(\"english\")\n",
        "    for e in english:\n",
        "        print(index_to_eng(e))\n"
      ],
      "execution_count": 25
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "74f43bbc-d4af-4474-bc96-24b6668155e1"
      },
      "source": [
        "* Note: When working with PyTorch tensors that represent data, it's important to understand the conventions around representing sequences. In most cases, the rows (the first dimension) in a PyTorch tensor represent individual samples, while the columns (the second dimension) represent features or time steps in the case of sequences. When dealing with sequences in PyTorch, it's common to use functions like `pad_sequence` to ensure that all sequences have the same length. Surprisingly, the padding operation is applied along the second dimension (columns), even though sequences are typically represented in the first dimension (rows). This can be confusing at first due to the way batches of sequences are represented. In many sequence-related tasks in PyTorch, especially when working with recurrent models like RNNs, LSTMs, and GRUs, batches of sequences are usually represented with the shape [sequence_length, batch_size, feature_size], where `sequence_length` refers to the length of the longest sequence within the batch(here it is equevalent to `src_len` or `trg_len`). If you check the src tensor above, you can see that the first word of of all sentences are in the first line, the second word of all sentences are in the second line, etc. That is why the first dimension is the length of the sequence.\n",
        "\n",
        "    When you use `pad_sequence`, it adds padding to the sequences in a batch so that they all have the same length, matching the length of the longest sequence. Since sequences are represented in the first dimension, the padding is applied along that dimension. As a result, the output tensor from `pad_sequence` will have the format [sequence_length, batch_size]. (Check the output for `src` and `trg` from the above cell.) This convention is commonly used because models like LSTMs expect the data to be in this format. However, if you're accustomed to working with more traditional tabular data in PyTorch, it can initially cause confusion. It's important to be aware of this convention to avoid potential errors and understand how to properly prepare and format sequence data for your models.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "92ca6477-5c19-4fe0-a291-a432f84a1200"
      },
      "source": [
        "# Training the model\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "500b50ac-5a1c-4c2f-aef1-cfb5d3c035e0"
      },
      "source": [
        "### Initializations\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "a313f641-8f93-4fd7-855d-9803a7e88984"
      },
      "source": [
        "This code sets the random seed for various libraries and modules. This is done to make the results reproducible:\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "61cdac21-2b62-4b23-be6a-4e6a5e3bf76d"
      },
      "outputs": [],
      "source": [
        "SEED = 1234\n",
        "random.seed(SEED)\n",
        "np.random.seed(SEED)\n",
        "torch.manual_seed(SEED)\n",
        "torch.cuda.manual_seed(SEED)\n",
        "torch.backends.cudnn.deterministic = True"
      ],
      "execution_count": 26
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "a0373902-8eaa-4849-a21e-f9a45f925803"
      },
      "source": [
        "### Training\n",
        "Now, define an instance of the model:\n",
        "\n",
        "- `enc = Encoder(INPUT_DIM, ENC_EMB_DIM, HID_DIM, N_LAYERS, ENC_DROPOUT)`: This line creates an instance of the `Encoder` class, which represents the encoder component of the Seq2Seq model. The `Encoder` class takes the input dimension, embedding dimension, hidden dimension, number of layers, and dropout probability as arguments.\n",
        "\n",
        "- `dec = Decoder(OUTPUT_DIM, DEC_EMB_DIM, HID_DIM, N_LAYERS, DEC_DROPOUT)`: This line creates an instance of the `Decoder` class, which represents the decoder component of the Seq2Seq model. The `Decoder` class takes the output dimension, embedding dimension, hidden dimension, number of layers, and dropout probability as arguments.\n",
        "\n",
        "- `model = Seq2Seq(enc, dec, device,trg_vocab = vocab_transform['en']).to(device)`: This line creates an instance of the `Seq2Seq` class, which represents the entire Seq2Seq model. The `Seq2Seq` class takes the encoder, decoder, and device (e.g., CPU or GPU) as arguments. It combines the encoder and decoder to form the complete Seq2Seq architecture.\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "145a267e-282c-44b8-8337-0bc38d6cfbd0"
      },
      "outputs": [],
      "source": [
        "INPUT_DIM = len(vocab_transform['de'])\n",
        "OUTPUT_DIM = len(vocab_transform['en'])\n",
        "ENC_EMB_DIM = 128 #256\n",
        "DEC_EMB_DIM = 128 #256\n",
        "HID_DIM = 256 #512\n",
        "N_LAYERS = 1 #2\n",
        "ENC_DROPOUT = 0.3 #0.5\n",
        "DEC_DROPOUT = 0.3 #0.5\n",
        "\n",
        "enc = Encoder(INPUT_DIM, ENC_EMB_DIM, HID_DIM, N_LAYERS, ENC_DROPOUT)\n",
        "dec = Decoder(OUTPUT_DIM, DEC_EMB_DIM, HID_DIM, N_LAYERS, DEC_DROPOUT)\n",
        "\n",
        "model = Seq2Seq(enc, dec, device,trg_vocab = vocab_transform['en']).to(device)"
      ],
      "execution_count": 27
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "fe19dde8-0ca0-4212-a13e-4566ecece90c"
      },
      "source": [
        "`def init_weights(m)`defines a function named `init_weights` that takes a module `m` as input. The purpose of this function is to initialize the weights of the neural network module.\n",
        "\n",
        "The next line `for name, param in m.named_parameters():` starts a loop that iterates over the named parameters of the module `m`. Each parameter is accessed as `param` and its corresponding name is accessed as `name`.\n",
        "\n",
        "`nn.init.uniform_(param.data, -0.08, 0.08)`initializes the parameter's data with values drawn from a uniform distribution between `-0.08` and `0.08`. The `nn.init.uniform_` function is provided by the PyTorch library and is used to initialize the weights of neural network parameters.\n",
        "\n",
        "Finally, `model.apply(init_weights)` applies the `init_weights` function to the `model` instance. This ensures that the weights of all the parameters in the model are initialized using the specified uniform distribution.\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "32810a3f-d123-49e6-947c-105d5903d8a7",
        "outputId": "eb1d1a9d-f96a-4b54-8b71-48b3cbbaa3fa"
      },
      "outputs": [
        {
          "output_type": "execute_result",
          "data": {
            "text/plain": [
              "Seq2Seq(\n",
              "  (encoder): Encoder(\n",
              "    (embedding): Embedding(19214, 128)\n",
              "    (lstm): LSTM(128, 256, dropout=0.3)\n",
              "    (dropout): Dropout(p=0.3, inplace=False)\n",
              "  )\n",
              "  (decoder): Decoder(\n",
              "    (embedding): Embedding(10837, 128)\n",
              "    (lstm): LSTM(128, 256, dropout=0.3)\n",
              "    (fc_out): Linear(in_features=256, out_features=10837, bias=True)\n",
              "    (softmax): LogSoftmax(dim=1)\n",
              "    (dropout): Dropout(p=0.3, inplace=False)\n",
              "  )\n",
              "  (trg_vocab): Vocab()\n",
              ")"
            ]
          },
          "metadata": {},
          "execution_count": 28
        }
      ],
      "source": [
        "def init_weights(m):\n",
        "    for name, param in m.named_parameters():\n",
        "        nn.init.uniform_(param.data, -0.08, 0.08)\n",
        "\n",
        "model.apply(init_weights)"
      ],
      "execution_count": 28
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "6ee5c3c9-8384-4db4-b58e-bab33367cc4b"
      },
      "source": [
        "This code defines a function `count_parameters` that counts the number of trainable parameters in a given model. It then prints the count of trainable parameters in a formatted string.\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "3ea16305-b830-4eb8-938c-6d0ecd37bcf0",
        "outputId": "9caf011e-7b15-46c3-a4de-f43ee082f5ea"
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "The model has 7,422,165 trainable parameters\n"
          ]
        }
      ],
      "source": [
        "def count_parameters(model):\n",
        "    return sum(p.numel() for p in model.parameters() if p.requires_grad)\n",
        "\n",
        "print(f'The model has {count_parameters(model):,} trainable parameters')"
      ],
      "execution_count": 29
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "892e09eb-0441-46fc-8a02-d44c6833e853"
      },
      "source": [
        "The following cell sets up the optimizer and loss function for training the model.\n",
        "\n",
        "1. `optimizer = optim.Adam(model.parameters())`: This line creates an instance of the Adam optimizer and passes the model's parameters (`model.parameters()`) as the parameters to be optimized. The Adam optimizer is a popular optimization algorithm commonly used for training deep neural networks. It adjusts the model's parameters based on the gradients computed during backpropagation to minimize the loss function.\n",
        "\n",
        "2. `PAD_IDX = vocab_transform['en'].get_stoi()['<pad>']`: This line retrieves the index of the `<pad>` token in the target vocabulary.\n",
        "\n",
        "3. `criterion = nn.CrossEntropyLoss(ignore_index=PAD_IDX)`: This line creates an instance of the CrossEntropyLoss criterion. The CrossEntropyLoss is a commonly used loss function for multi-class classification tasks. In this case, it is used for training the model to predict the next word in the translated sequence. The `ignore_index` parameter is set to `PAD_IDX`, which indicates that the loss should be ignored for any predictions where the target is the padding token. This is useful to exclude padding tokens from contributing to the loss during training.\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "1afc3d29-3881-46f6-bb75-33988fcaa33a"
      },
      "outputs": [],
      "source": [
        "optimizer = optim.Adam(model.parameters())\n",
        "\n",
        "PAD_IDX = vocab_transform['en'].get_stoi()['<pad>']\n",
        "\n",
        "criterion = nn.CrossEntropyLoss(ignore_index = PAD_IDX)"
      ],
      "execution_count": 30
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "287bdd29-e22a-4991-b156-f3131a0e2a5b"
      },
      "source": [
        "The following helper function provides a convenient way to calculate the elapsed time in minutes and seconds given the start and end times. It will be used to measure the time taken for each epoch during training or any other time-related calculations.\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "9907b721-adbe-410e-8a28-f0d566a13e54"
      },
      "outputs": [],
      "source": [
        "def epoch_time(start_time, end_time):\n",
        "    elapsed_time = end_time - start_time\n",
        "    elapsed_mins = int(elapsed_time / 60)\n",
        "    elapsed_secs = int(elapsed_time - (elapsed_mins * 60))\n",
        "    return elapsed_mins, elapsed_secs"
      ],
      "execution_count": 31
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "fc457825-d178-4ac9-8ec3-19b1443e5bee"
      },
      "source": [
        "Please be aware that training the model using CPUs can be a time-consuming process. If you don't have access to GPUs, you can jump to \"loading the saved model\" and proceed with loading the pre-trained model using the provided code. The model has been trained for five epochs and saved for your convenience.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "c71efbd8-cd46-44ed-ad6a-41600a06e4eb"
      },
      "source": [
        "Let's start the training epochs:\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "f7204cc7-4273-452f-b995-186ea386fbb1",
        "outputId": "d0d6a7b6-7778-42cc-a259-d22eff001c95"
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stderr",
          "text": []
        },
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "Epoch: 01 | Time: 4m 25s\n",
            "\tTrain Loss: 4.384 | Train PPL:  80.144\n",
            "\t Val. Loss: 5.305 |  Val. PPL: 201.399\n"
          ]
        },
        {
          "output_type": "stream",
          "name": "stderr",
          "text": []
        },
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "Epoch: 02 | Time: 4m 21s\n",
            "\tTrain Loss: 3.647 | Train PPL:  38.346\n",
            "\t Val. Loss: 4.773 |  Val. PPL: 118.317\n"
          ]
        },
        {
          "output_type": "stream",
          "name": "stderr",
          "text": [
            "                                                            "
          ]
        },
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "Epoch: 03 | Time: 4m 21s\n",
            "\tTrain Loss: 3.241 | Train PPL:  25.552\n",
            "\t Val. Loss: 4.422 |  Val. PPL:  83.259\n"
          ]
        },
        {
          "output_type": "stream",
          "name": "stderr",
          "text": [
            "\r"
          ]
        }
      ],
      "source": [
        "torch.cuda.empty_cache()\n",
        "\n",
        "N_EPOCHS = 3 #run the training for at least 5 epochs\n",
        "CLIP = 1\n",
        "\n",
        "best_valid_loss = float('inf')\n",
        "best_train_loss = float('inf')\n",
        "train_losses = []\n",
        "valid_losses = []\n",
        "\n",
        "train_PPLs = []\n",
        "valid_PPLs = []\n",
        "\n",
        "for epoch in range(N_EPOCHS):\n",
        "\n",
        "    start_time = time.time()\n",
        "\n",
        "    train_loss = train(model, train_dataloader, optimizer, criterion, CLIP)\n",
        "    train_ppl = math.exp(train_loss)\n",
        "    valid_loss = evaluate(model, valid_dataloader, criterion)\n",
        "    valid_ppl = math.exp(valid_loss)\n",
        "\n",
        "\n",
        "    end_time = time.time()\n",
        "\n",
        "    epoch_mins, epoch_secs = epoch_time(start_time, end_time)\n",
        "\n",
        "\n",
        "    if valid_loss < best_valid_loss:\n",
        "\n",
        "        best_valid_loss = valid_loss\n",
        "        torch.save(model.state_dict(), 'RNN-TR-model.pt')\n",
        "\n",
        "    train_losses.append(train_loss)\n",
        "    train_PPLs.append(train_ppl)\n",
        "    valid_losses.append(valid_loss)\n",
        "    valid_PPLs.append(valid_ppl)\n",
        "\n",
        "    print(f'Epoch: {epoch+1:02} | Time: {epoch_mins}m {epoch_secs}s')\n",
        "    print(f'\\tTrain Loss: {train_loss:.3f} | Train PPL: {train_ppl:7.3f}')\n",
        "    print(f'\\t Val. Loss: {valid_loss:.3f} |  Val. PPL: {valid_ppl:7.3f}')\n"
      ],
      "execution_count": 32
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "3d14297c-76cf-4451-ab4a-64868853a31e"
      },
      "source": [
        "Let's visualize the model train and validation losses over the training epochs:\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 564
        },
        "id": "a8f09738-dd9e-40e7-86bc-18d3107d56e2",
        "outputId": "4204733c-e7d6-47de-84a8-db6fa0a7e0be"
      },
      "outputs": [
        {
          "output_type": "display_data",
          "data": {
            "text/plain": [
              "<Figure size 1000x600 with 2 Axes>"
            ],
            "image/png": "iVBORw0KGgoAAAANSUhEUgAAA4UAAAIjCAYAAAC04r7nAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjguMCwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy81sbWrAAAACXBIWXMAAA9hAAAPYQGoP6dpAADLLklEQVR4nOzdd3hURRfH8e+m9waBEFroEHoTAUVQkN5VRKSJgEp5UVBsIKCCCiqKIlaKighKVbrSBKRXKdIhEGpooaTu+8eQDUsQEgjZlN/nee5j7tzZu2eTSPbszJyxWK1WKyIiIiIiIpIjOTk6ABEREREREXEcJYUiIiIiIiI5mJJCERERERGRHExJoYiIiIiISA6mpFBERERERCQHU1IoIiIiIiKSgykpFBERERERycGUFIqIiIiIiORgSgpFRERERERyMCWFIiLprEuXLoSFhd3RY4cMGYLFYknfgDKZgwcPYrFYmDBhQoY/t8ViYciQIbbzCRMmYLFYOHjw4G0fGxYWRpcuXdI1nrv5XREREUkvSgpFJMewWCypOpYuXeroUHO8vn37YrFY2Lt373/2eeONN7BYLGzdujUDI0u7Y8eOMWTIEDZv3uzoUGySEvNRo0Y5OpQUzp49i4uLC1OnTgVMMn79/5958uThwQcfZMaMGXaPq1u3rl2/oKAgqlevznfffUdiYqKtX5cuXfDx8cnQ1yQiktm5ODoAEZGM8v3339udT5o0iUWLFqVoL1OmzF09z9dff233JjQt3nzzTV599dW7ev7soEOHDowZM4bJkyczePDgm/b56aefKF++PBUqVLjj5+nYsSNPPvkk7u7ud3yP2zl27BhDhw4lLCyMSpUq2V27m9+V7GrBggVYLBYeffRRW1ulSpXo378/YL6fX375JW3atOGLL77gueees/UrUKAAI0aMAODUqVNMmjSJbt268e+///Lee+9l7AsREclClBSKSI7x9NNP253//fffLFq0KEX7jS5fvoyXl1eqn8fV1fWO4gNwcXHBxUX/NNeoUYPixYvz008/3TQpXL16NQcOHLjrN/rOzs44Ozvf1T3uxt38rmRXc+fOpXbt2gQEBNja8ufPb/f/aadOnShevDgff/yxXVLo7+9v169nz56UKlWKzz77jLffflvfbxGR/6DpoyIi16lbty7lypVjw4YN1KlTBy8vL15//XUA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CxemSFhef/11Ll26xOTJk/n555+pUqUKv//+O6+++qpdP1dXVyZOnMhrr73Gc889R3x8POPHj79pUpj0PRs8eDA///wz48ePJywsjJEjR9K/f/80v5bbmT9//k03uw8LC6NcuXIsXbqUV199lYkTJ3LhwgVKlSrF+PHj6dKli63v008/zVdffcXYsWM5d+4cISEhtGvXjiFDhtimnfbt25fZs2ezcOFCYmJiKFy4MO+88w4vv/wyYKqOhoeHZ9j02NjYWAYNGpSivVixYkoKRSRHslgz08fcIiKS7lq1apWq7QBEHCU8PJxmzZrxwQcfODoUEZEcSWsKRUSykStXrtid79mzh7lz51K3bl3HBCRyG7GxsbRr1+6me4OKiEjG0EihiEg2ki9fPrp06ULRokU5dOgQX3zxBTExMWzatCnF3nsiIiIioDWFIiLZSqNGjfjpp584fvw47u7u1KxZk+HDhyshFBERkf+kkUIREREREZEcTGsKRUREREREcjAlhSIiIiIiIjlYjltTGB8fz6ZNm8ibN69t/yQREREREcl5EhMTOXHiBJUrV8bFJcelRjY57pVv2rSJ++67z9FhiIiIiIhIJrF27VqqV6/u6DAcJsclhXnz5gXMDz5fvnwOjkZERERERBwlMjKS++67z5Yj5FQ5LilMmjKaL18+ChQo4OBoRERERETE0XL6srKc/epFRERERERyOCWFIiIiIiIiOZiSQhERERERkRwsx60pFBEREZHMJyEhgbi4OEeHIdmMs7MzLi4uWCwWR4eSqSkpFBERERGHio6OJiIiAqvV6uhQJBvy8vIiX758uLm5OTqUTEtJoYiIiIg4TEJCAhEREXh5eREcHKwRHUk3VquV2NhYTp06xYEDByhRokSOrzL6X5QUioiIiIjDxMXFYbVaCQ4OxtPT09HhSDbj6emJq6srhw4dIjY2Fg8PD0eHlCkpVRYRERERh9MIodwrGh28PX2HREREREREcjAlhSIiIiIiIjmYkkIRERERkUwgLCyM0aNHOzoMyYGUFIqIiIiIpIHFYrnlMWTIkDu677p16+jRo8ddxVa3bl369et3V/eQnEfVR0VERERE0iAyMtL29c8//8zgwYPZvXu3rc3Hx8f2tdVqJSEhAReX27/tDg4OTt9ARVJJI4UiIiIikmlYrXDpkmMOqzV1MYaEhNgOf39/LBaL7XzXrl34+voyb948qlatiru7O3/99Rf79u2jZcuW5M2bFx8fH6pXr87ixYvt7nvj9FGLxcI333xD69at8fLyokSJEsyePfuuvr+//vorZcuWxd3dnbCwMD788EO762PHjqVEiRJ4eHiQN29eHnvsMdu1X375hfLly+Pp6UmuXLmoX78+ly5duqt4JHPQSKGIiIiIZBqXL8N1A20ZKjoavL3T516vvvoqo0aNomjRogQGBnLkyBGaNGnCu+++i7u7O5MmTaJ58+bs3r2bQoUK/ed9hg4dygcffMDIkSMZM2YMHTp04NChQwQFBaU5pg0bNvDEE08wZMgQ2rVrx6pVq3jhhRfIlSsXXbp0Yf369fTt25fvv/+eWrVqERUVxYoVKwAzOtq+fXs++OADWrduzcWLF1mxYgXW1GbSkqkpKRQRERERSWfDhg2jQYMGtvOgoCAqVqxoO3/77beZMWMGs2fPpnfv3v95ny5dutC+fXsAhg8fzqeffsratWtp1KhRmmP66KOPeOSRRxg0aBAAJUuWZMeOHYwcOZIuXbpw+PBhvL29adasGb6+vhQuXJjKlSsDJimMj4+nTZs2FC5cGIDy5cunOQbJnJQUOtLpv+HyEcjXCFx9HR2NiIiIiMN5eZkRO0c9d3qpVq2a3Xl0dDRDhgzh999/tyVYV65c4fDhw7e8T4UKFWxfe3t74+fnx8mTJ+8opp07d9KyZUu7ttq1azN69GgSEhJo0KABhQsXpmjRojRq1IhGjRrZpq5WrFiRRx55hPLly9OwYUMeffRRHnvsMQIDA+8oFslctKbQkXaPgb+egF9zw5JGsOcLuBzh6KhEREREHMZiMVM4HXFYLOn3OrxvmIc6YMAAZsyYwfDhw1mxYgWbN2+mfPnyxMbG3vI+rq6uN3x/LCQmJqZfoNfx9fVl48aN/PTTT+TLl4/BgwdTsWJFzp07h7OzM4sWLWLevHmEh4czZswYSpUqxYEDB+5JLJKxlBQ6km8p8C4BibEQuQDWvQAzC8L8arDtbTi7JfUrnkVEREQk01q5ciVdunShdevWlC9fnpCQEA4ePJihMZQpU4aVK1emiKtkyZI4OzsD4OLiQv369fnggw/YunUrBw8e5M8//wRMQlq7dm2GDh3Kpk2bcHNzY8aMGRn6GuTe0PRRR9pSBD7yhmEToNgJiJgFp1dD1AZzbBsM3mGQvwUUaAF56oCT6+3uKiIiIiKZTIkSJZg+fTrNmzfHYrEwaNCgezbid+rUKTZv3mzXli9fPvr370/16tV5++23adeuHatXr+azzz5j7NixAPz222/s37+fOnXqEBgYyNy5c0lMTKRUqVKsWbOGP/74g0cffZQ8efKwZs0aTp06RZkyZe7Ja5CMpZFCR7FaYeRI2LwZWnSBV5ZDwW+gzXGo8a1JBJ094dJB+PdT+LM+/BoMK5+CQz9D3AUHvwARERERSa2PPvqIwMBAatWqRfPmzWnYsCFVqlS5J881efJkKleubHd8/fXXVKlShalTpzJlyhTKlSvH4MGDGTZsGF26dAEgICCA6dOn8/DDD1OmTBnGjRvHTz/9RNmyZfHz82P58uU0adKEkiVL8uabb/Lhhx/SuHHje/IaMqsRI0ZQvXp1fH19yZMnD61atbLboxLg6tWr9OrVi1y5cuHj40Pbtm05ceKEXZ/Dhw/TtGlTvLy8yJMnDy+//DLx8fEZ+VLsWKw5rI5sREQEBQsW5MiRIxQoUMCxwZw+DcOGwRdfQHw8ODtD9+4wZAjkzQvxl+H4YjOCeHQOxJxKfqyTK+SpCwVamgTSu6CjXoWIiIjIHbt69SoHDhygSJEieHh4ODocyYZu9TuW1tygUaNGPPnkk1SvXp34+Hhef/11tm/fzo4dO2zrSJ9//nl+//13JkyYgL+/P71798bJyck2dTchIYFKlSoREhLCyJEjiYyMpFOnTnTv3p3hw4en/zcgFZQUZgb//guvvgpJc7J9fc15v37JZbASE+DMGjg62ySJF3bZ3yOwskkQC7SEgIrpu1JaRERE5B5RUij3WnomhTc6deoUefLkYdmyZdSpU4fz588THBzM5MmTeeyxxwDYtWsXZcqUYfXq1dx///3MmzePZs2acezYMfLmzQvAuHHjGDhwIKdOncLNze3uX3QaafpoZlCyJEyfDsuWQbVqcPEivPEGlCoFkyZBYiI4OUNwLaj0HjTbCc12Q+WREPwAWJzg7CbYNgTmVYZZYbC+jxllTLh1RSsRERERkZzu4sWLXLhwwXbExMSk6nHnz58HzD6UABs2bCAuLo769evb+pQuXZpChQqxevVqAFavXk358uVtCSFAw4YNuXDhAv/88096vaQ0UVKYmdSpA2vWwI8/QqFCEBEBnTubRHHJEvu+fiWhzABosAJaH4f7x0OBVuDsBZcPw7+fwZ8NYHoeWNkeDv4Esecc8apERERERDK18PBw/P39bceIESNu+5jExET69etH7dq1KVeuHADHjx/Hzc2NgIAAu7558+bl+PHjtj7XJ4RJ15OuOYKqj2Y2Tk7w1FPQpg188gkMHw6bNsHDD0Pz5vDBB1C6tP1jPIKhaBdzxF+BE38kr0O8egIOTTGHxQXy1k2uZupd2AEvUEREREQkc9mxYwf58+e3nbu7u9/2Mb169WL79u389ddf9zK0DKGRwszKwwMGDoS9e6FXL1OEZs4cKFfOnJ88efPHuXhC/mZQ42tofQweXQ3hr4J/OFjjzZTSDX3NFNN5lWHrWxC1UfshioiIiEiO5evri5+fn+24XVLYu3dvfvvtN5YsWWK3FjEkJITY2FjOnTtn1//EiROEhITY+txYjTTpPKlPRlNSmNkFB8Nnn8E//0DLlpCQAGPHQvHi8N57cOXKfz/W4gS574dKI6DpP9DsX6g8yux3aHGCs5th+zCYXxVmFYJ1vSByodYhioiIiIjchNVqpXfv3syYMYM///yTIkWK2F2vWrUqrq6u/PHHH7a23bt3c/jwYWrWrAlAzZo12bZtGyevG+RZtGgRfn5+hIeHZ8wLuYGqj2Y1S5fCgAGwYYM5L1TITDFt395MPU2tq6fh2Fw4OgsiF0D8peRrLr4Q2thUMg1tDG6B6foSRERERJKo+qjca+lZffSFF15g8uTJzJo1i1KlStna/f398fT0BMyWFHPnzmXChAn4+fnRp08fAFatWgUkb0kRGhrKBx98wPHjx+nYsSPPPvustqTIKFk+KQRTjXTyZHj9dThyxLRVrQoffggPPZT2+yVcheN/XNvuYjZcvW6Bq8XFjCwm7YfoE5YuL0FEREQElBTKvZeeSaHlP7Z9Gz9+PF26dLE9X//+/fnpp5+IiYmhYcOGjB071m5q6KFDh3j++edZunQp3t7edO7cmffeew8XF8eUfFFSmJVduQKjR8OIEWYbCzBTTN9/32xncSesiXBmvRlBjJgF528oixtQ4VqhmpYQVFX7IYqIiMhdUVIo99q93Kcwu9CawqzM0xNee80Uo3nhBVOMZtYsKFsWeveGU6fSfk+LE+S+Dyq+C023Q/O9UOUjyPOQuXZuK/zzDiyoDjMLwtrn4dh8SEjdXi4iIiIiYtStW5d+/frZzsPCwhg9evQtH2OxWJg5c+ZdP3d63UeyByWF2UGePPD557Btm9m2IiHBnBcvbkYNr16983v7FoPSL0L9pdDmJNScBAUfAxcfuHIU9o6DpY3h19yw4nE48APERKXbSxMRERHJbJo3b06jRo1uem3FihVYLBa2bt2a5vuuW7eOHj163G14doYMGUKlSpVStEdGRtK4ceN0fa4bTZgwIcV+fZI5KSnMTsqUgdmz4Y8/oHJluHABXn3VTCWdPNmsRbwb7rmgSEd4cBq0PQV150Lx58AzFOKj4cgvsLojTM8Di+vBrtEQfSBdXpqIiIhIZtGtWzcWLVpEREREimvjx4+nWrVqVKhQIc33DQ4OxsvLKz1CvK2QkJBU7cUnOYOSwuzo4Ydh/XqYNAkKFIDDh6FDB7j/flixIn2ew9nDVCa97wtodQQaroWyb0JAebAmwMmlsPFFmF0Ufi8PW96E02vNmkURERGR/2K1mqrojjhSWWqjWbNmBAcHM2HCBLv26Ohopk2bRrdu3Thz5gzt27cnf/78eHl5Ub58eX766adb3vfG6aN79uyhTp06eHh4EB4ezqJFi1I8ZuDAgZQsWRIvLy+KFi3KoEGDiIuLA8xI3dChQ9myZQsWiwWLxWKL+cbpo9u2bePhhx/G09OTXLly0aNHD6Kjo23Xu3TpQqtWrRg1ahT58uUjV65c9OrVy/Zcd+Lw4cO0bNkSHx8f/Pz8eOKJJ+z279uyZQv16tWz7SFYtWpV1q9fD5hCLc2bNycwMBBvb2/Kli3L3Llz7ziWnM4x5W3k3nNygo4doW3b5GI069ZBnTrQurXZ47BkyfR5LosT5KpujopvQ/R+iJhjitWcXA7nt5vjn3fBM58pVJO/BYQ8bJJLERERkSQJl2Gqj2Oe+4locPG+bTcXFxc6derEhAkTeOONN2wVKadNm0ZCQgLt27cnOjqaqlWrMnDgQPz8/Pj999/p2LEjxYoV47777rvtcyQmJtKmTRvy5s3LmjVrOH/+vN36wyS+vr5MmDCB0NBQtm3bRvfu3fH19eWVV16hXbt2bN++nfnz57N48WLAbJ1wo0uXLtGwYUNq1qzJunXrOHnyJM8++yy9e/e2S3yXLFlCvnz5WLJkCXv37qVdu3ZUqlSJ7t273/b13Oz1JSWEy5YtIz4+nl69etGuXTuWLl0KQIcOHahcuTJffPEFzs7ObN68GVdXVwB69epFbGwsy5cvx9vbmx07duDj46Dfm2xASWF25+Vltq7o1g2GDIGvvoIZM2DOHFOcZtAgyJ07fZ/TpyiU/p85Ys/C0Wv7IR6bB1ciYe+X5nDxhnyNriWJTc30VBEREZEs4JlnnmHkyJEsW7aMunXrAmbqaNu2bfH398ff358BAwbY+vfp04cFCxYwderUVCWFixcvZteuXSxYsIDQ0FAAhg8fnmId4Jtvvmn7OiwsjAEDBjBlyhReeeUVPD098fHxwcXFxW47hBtNnjyZq1evMmnSJLy9TVL82Wef0bx5c95//33y5s0LQGBgIJ999hnOzs6ULl2apk2b8scff9xRUvjHH3+wbds2Dhw4QMGCBQGYNGkSZcuWZd26dVSvXp3Dhw/z8ssvU7p0aQBKlChhe/zhw4dp27Yt5cuXB6Bo0aJpjkGSKSnMKfLmhS++gD594JVX4Pff4dNPYeJEeOMN034vykC7BUKRDuZIiIETS69tdzHbFKo58qs5LM4Q/EDydhe+xdI/FhEREcn8nL3MiJ2jnjuVSpcuTa1atfjuu++oW7cue/fuZcWKFQwbNgwwG5QPHz6cqVOncvToUWJjY4mJiUn1msGdO3dSsGBBW0IIULNmzRT9fv75Zz799FP27dtHdHQ08fHx+Pn5pfp1JD1XxYoVbQkhQO3atUlMTGT37t22pLBs2bI4Ozvb+uTLl49t27al6bmuf86CBQvaEkKA8PBwAgIC2LlzJ9WrV+ell17i2Wef5fvvv6d+/fo8/vjjFCtm3iP27duX559/noULF1K/fn3atm17R+s4xdCawpwmPBx++w0WL4aKFeH8eZMklikDU6akei79HXF2h9CGUH2sWYfYaD2UGwQBFa+tQ1wGm/rDnOLwe1nY/DqcXqN1iCIiIjmJxWJmEzniSOP+y926dePXX3/l4sWLjB8/nmLFivHQQw8BMHLkSD755BMGDhzIkiVL2Lx5Mw0bNiQ2NjbdvlWrV6+mQ4cONGnShN9++41NmzbxxhtvpOtzXC9p6mYSi8VC4t0WMryFIUOG8M8//9C0aVP+/PNPwsPDmTFjBgDPPvss+/fvp2PHjmzbto1q1aoxZsyYexZLdqekMKd65BHYsAEmTID8+eHgQWjf3hSj+euve//8FgsEVYUKw6DJZmhxAKp+AnkfAYsLnN8BO0bAwvthRn5Y0wOO/g7xV+59bCIiIiKp8MQTT+Dk5MTkyZOZNGkSzzzzjG194cqVK2nZsiVPP/00FStWpGjRovz777+pvneZMmU4cuQIkZGRtra///7brs+qVasoXLgwb7zxBtWqVaNEiRIcOnTIro+bmxsJCQm3fa4tW7Zw6dIlW9vKlStxcnKiVKlSqY45LZJe35EjR2xtO3bs4Ny5c4SHh9vaSpYsyYsvvsjChQtp06YN48ePt10rWLAgzz33HNOnT6d///58/fXX9yTWnEBJYU7m7AydO8O//8Lbb4O3N6xdCw8+aArU7N2bcbH4hEGpvvDIYmh7EmpNhkLtwNUPrh6HfV/DsmZmP8TlbWD/RLh6OuPiExEREbmBj48P7dq147XXXiMyMpIuXbrYrpUoUYJFixaxatUqdu7cSc+ePe0qa95O/fr1KVmyJJ07d2bLli2sWLGCN954w65PiRIlOHz4MFOmTGHfvn18+umntpG0JGFhYRw4cIDNmzdz+vRpYmJiUjxXhw4d8PDwoHPnzmzfvp0lS5bQp08fOnbsaJs6eqcSEhLYvHmz3bFz507q169P+fLl6dChAxs3bmTt2rV06tSJhx56iGrVqnHlyhV69+7N0qVLOXToECtXrmTdunWUKVMGgH79+rFgwQIOHDjAxo0bWbJkie2apJ2SQjHFaN580ySBPXqYyqXTp5uppv36wZkzGRuPWyCEtYcHpkCbU1BvIZToBV4FTUWyiBnwdxeYkRcW1YGdH8KFPRkbo4iIiAhmCunZs2dp2LCh3fq/N998kypVqtCwYUPq1q1LSEgIrVq1SvV9nZycmDFjBleuXOG+++7j2Wef5d1337Xr06JFC1588UV69+5NpUqVWLVqFYMGDbLr07ZtWxo1akS9evUIDg6+6bYYXl5eLFiwgKioKKpXr85jjz3GI488wmeffZa2b8ZNREdHU7lyZbujefPmWCwWZs2aRWBgIHXq1KF+/foULVqUn3/+GQBnZ2fOnDlDp06dKFmyJE888QSNGzdm6NChgEk2e/XqRZkyZWjUqBElS5Zk7Nixdx1vTmWxWu/lIrLMJyIigoIFC3LkyBEKFCjg6HAyp+3bzTrDefPMeUCASRp79wZHbnJqtcLZzRAxC47OhrOb7K/7lYECLSB/S8hdw2yVISIiIpna1atXOXDgAEWKFMHjXhS9kxzvVr9jyg0MvWuWlMqVg7lzYeFCqFABzp2DAQNMMZqpU+9tMZpbsVggqDJUGAKNN0LLQ1B1DIQ0MOsQL+yEHe/DolowIx+sedbsl6h1iCIiIiIi/0lJofy3Bg1g40b47jvIlw8OHIB27aBWLVi1ytHRgXchKNUbHl4IbU9DrZ+gcHtw9YerJ2Hft7C8BfyaC5a3gn3jTbuIiIiIiNgoKZRbc3aGrl1hzx4YOtQUo/n7b6hdGx5/HPbtc3SEhps/hD0JtSdDm5Pw8CIo2Qe8CkHCFTPldM0zMD0EFj0AO0bChd2OjlpERERExOGUFErqeHvD4MEmOXz2WVOM5pdfzJTSl16CqChHR5jM2Q1C6kO1T6HlQWi8GcoPhcAqgBVOrYTNr8Bvpc2xaaBpS7x1uWYRERERkexISaGkTb588PXXsHkzNGwIcXHw8cdQvLj5703KHDuUxQKBFaH8YGi8AVoehmqfQ8ij4ORqRgt3fmBGD2fkg7+7mVHF+MuOjlxEREREJEMoKZQ7U748zJ9vjvLl4exZM2IYHm5GEDNrUVvvglDyBXh4gVmHWPtnKPwUuAZAzCnY/51Zf/hrLljWwqxLvJL6PYVERERERLIaJYVydxo2hE2b4JtvICQE9u83aw0feMCsPczMXP2g8BNQ+0doexIe/gNK9gXvwpBwFY7OMRVMZ+SDhbVMZdPzuzJvwisiIiIicgeUFMrdc3aGbt3MesO33gIvL1OdtGZNU630wAFHR3h7Tq4Q8jBU+wRaHIDGW6DC2xBUDbDC6dWw+VX4vQz8Vgo2vQwn/9I6RBERERHJ8pQUSvrx8YEhQ0xy+MwzZj3f1KlQurTZ5/DsWUdHmDoWCwRWgHJvQqN10CoCqn8B+RqBkxtc3AM7R8HiB2FGCPzdFY7MhPhLjo5cRERERCTNlBRK+gsNhW+/NcVoGjSA2Fj48ENTjOaTT8x5VuKVH0o8B/XmmXWID0yDsKfBLRBiTsP+CbCiNfyaG5Y2h71fw5Xjjo5aREREspiwsDBGjx7t6DAkB1JSKPdOhQqwYAHMmwdly5ptK/r1M8Vofv01a67Nc/WFQo9Bre/NfoiPLIFS/cC7iFmHeOw3WNsDZoTCgprwzwg4vyNrvlYRERG5KYvFcstjyJAhd3TfdevW0aNHj7uKrW7durY4PDw8CA8PZ+zYsbbrEyZMsF13cnKiQIECdO3alZMnT9q9vpkzZ95VHJK1KCmUe8tigUaNzKjhV19B3rxmw/vHHoMHH4Q1axwd4Z1zcoG8daHqx9BiHzTZBhXegVz3AVY48zdseR1+LwtzSsLG/nByOSTGOzpyERERuQuRkZG2Y/To0fj5+dm1DRgwwNbXarUSH5+6v/3BwcF4eXnddXzdu3cnMjKSHTt28MQTT9CrVy9++ukn2/WkeCMiIvj666+ZN28eHTt2vOvnlaxLSaFkDBcX6N7drDccNAg8PWHlSrj/fmjfPmsUo7kViwUCykG5N6DhGmh1FO77EkKbgJM7RO+FXR/B4ofMOsTVneHIdIiLdnTkIiIimYrVauVS7CWHHNZUzuwJCQmxHf7+/lgsFtv5rl278PX1Zd68eVStWhV3d3f++usv9u3bR8uWLcmbNy8+Pj5Ur16dxYsX2933xumjFouFb775htatW+Pl5UWJEiWYPXv2bePz8vIiJCSEokWLMmTIkBSPS4o3NDSUxo0b07dvXxYvXsyVK1dS90OSbMfF0QFIDuPrC8OGQc+e8OabMHEiTJkC06fD//4Hr78OAQGOjvLueYVC8R7miIuGyAVwdDYc/Q1izsCBSeZwcoeQR6BAS8jfHDzzOTpyERERh7ocdxmfET4Oee7o16LxdvNOl3u9+uqrjBo1iqJFixIYGMiRI0do0qQJ7777Lu7u7kyaNInmzZuze/duChUq9J/3GTp0KB988AEjR45kzJgxdOjQgUOHDhEUFJTqWDw9PYm9RU0HT09PEhMTUz2iKdmPRgrFMfLnh/HjYeNGeOQRU3xm5EhTjGbMGIiLc3SE6cfVBwq1hZoToc0JqL8MSr8EPsUgMQaOzYW1Pa+tQ6wB/wyHc9u1DlFERCQLGzZsGA0aNKBYsWIEBQVRsWJFevbsSbly5ShRogRvv/02xYoVu+3IX5cuXWjfvj3Fixdn+PDhREdHs3bt2lTFkJCQwA8//MDWrVt5+OGHb9pnz549jBs3jmrVquHr65vm1ynZg0YKxbEqVYJFi0wxmpdfhh07oG9fkxh+8AG0bGmmZmYXTi6Qp445Ko+CCzshYpY5zqyBM2vNseUN8CkK+VuYUcTgB8xjRUREsjkvVy+iX3PM8gov17tfz5ekWrVqdufR0dEMGTKE33//ncjISOLj47ly5QqHDx++5X0qVKhg+9rb2xs/Pz+7ojA3M3bsWL755htiY2NxdnbmxRdf5Pnnn7ddP3/+PD4+PiQmJnL16lUeeOABvvnmmzt4lZJd6F2mOJ7FAk2awKOPmq0sBg82aw9bt4Y6dWDUKKhe3dFRpj+LBfzDzVH2NbONxdE5EDEbji+C6P2we7Q53AIhtKlJEPM1NFVQRUREsiGLxZJuUzgdydvb/jUMGDCARYsWMWrUKIoXL46npyePPfbYLad1Ari6utqdWywWEhMTb/mYDh068MYbb+Dp6Um+fPlwcrKfHOjr68vGjRtxcnIiX758eHp6puGVSXakpFAyDxcXs9bwqafg/ffN3obLl8N995m24cOhcGFHR3nveIZA8e7miL8EkQuvW4d4Gg7+YA4nN8j78LV1iC3M+kURERHJ1FauXEmXLl1o3bo1YEYODx48eE+ey9/fn+LFi//ndScnp1tel5xHawol8/H1hXfeMaOFnTqZEbXJk6FUKRg4EM6fd3SE956LNxRsDfePh9bHof5yKDMAfEtAYixEzod1z8PM/DC/Omx/B85t0zpEERGRTKpEiRJMnz6dzZs3s2XLFp566qnbjvg50oEDB9i8ebPdcenSJUeHJfeIkkLJvAoUMNVJ16+HevUgJsasMyxeHD77LHsVo7kVJ2fI8yBUHgnNdkPTHVDpPchdE7BA1HrYOgjmVoDZxWBDPzj+JyTmkO+PiIhIFvDRRx8RGBhIrVq1aN68OQ0bNqRKlSqODus/vfTSS1SuXNnu2LRpk6PDknvEYk3thizZREREBAULFuTIkSMUKFDA0eFIalmt8PvvphjNrl2mrWRJkyS2aJG9itGkxZUTcOw3U6jm+CJIuJp8zTUA8jc1U0xDG4Grn8PCFBER+S9Xr17lwIEDFClSBA8PD0eHI9nQrX7HlBsYGimUrMFigWbNYNs2GDsWgoPh33+hVSszirh+vaMjdAzPvFCsGzw0G9qegTozoWhXcA+GuHNw8EdY2Q5+zQ1LGsG/Y+FyhKOjFhEREZFMREmhZC0uLvD887B3r9no3sMDli0z1Uk7doTblHXO1ly8TPGZ+7+D1pHQ4C8o8zL4lTJTSSMXwPpeMLMgzKsK24bB2S1ahygiIiKSwykplKzJzw/efRd27zbJIMAPP5hiNK+/DhcuODY+R3NyhuDaUPkDaLbLHJXeN21Y4OxG2PYWzKsEs4vA+r5w/A+tQxQRERHJgZQUStZWqBBMmmSmjz70EFy9CiNGmGI0Y8fmnGI0t+NXCsJfMaOHbY5Dje/MqKKzJ1w6BP+OgT/rw6/BsPIpOPQzxOaAKq8iIiIioqRQsomqVWHJEpg1y4wWnjoFvXpBhQowZ46mSF7PIw8U62rWH7Y9DXVmm3WJHnkg7jwc+glWPgnTg+HPR+Hfz+FSDp6WKyIiIpLNKSmU7MNiMZVIt20zW1bkzm0qlbZoAY88Ahs3OjrCzMfFCwo0hxrfQKtj0GAVhA8EvzJmKunxRbC+N8wqDPOqwNYhELVJSbaIiIhINqKkULIfV1czSrh3r9ns3t3djCJWrQqdOsGRI46OMHNycobgmmYPxGY7oNm/Zm/E4AfB4gRnN8H2oTC/ikkS1/WGyEWQEOvoyEVERETkLigplOzL3x/ee88Uo+nQwbR9/73Z3/CNN+DiRcfGl9n5lYAyA6DBcmh9HO4fDwVag7MXXD4Cez6HJY+aaaZ/PQkHf4LYc46OWkRERETSSEmhZH+FC5vKpGvXQp06phjN8OGmGM24cRAf7+gIMz+PYCjaBepMN+sQH5oDxbqDR16IuwCHf4ZVT5lCNX/Uh91jTAEbEREREcn0lBRKzlG9OixdCjNnmtHCkyfNnocVKsDvv2udXGq5eEL+ZlDjK2h9DB79G8JfA/9wsMbDiT9gQ1+YFQZzK8HWtyBqg76/IiIiN6hbty79+vWznYeFhTF69OhbPsZisTBz5sy7fu70uo9kD0oKJWexWKBlS9i+HcaMgVy5YOdOaNYMGjSAzZsdHWHWYnGC3DWg0nBo+g803wOVP4Q8dcy1c1tg+zCYXw1mFYJ1veDYAkiIcXTkIiIid6x58+Y0atToptdWrFiBxWJh69atab7vunXr6NGjx92GZ2fIkCFUqlQpRXtkZCSNGzdO1+e60YQJE7BYLFgsFpycnChQoABdu3bl5MmTtj5J1y0WC/7+/tSuXZs///zTdr1Lly60atXqnsYpSgolp3J1hd69TTGaV14BNzf44w+oUgW6doWICEdHmDX5FocyL0H9ZdDmJNw/EQq2ARdvuBwBe8bC0kZmmulfT8CBHyH2rKOjFhERSZNu3bqxaNEiIm7yfmH8+PFUq1aNChUqpPm+wcHBeHl5pUeItxUSEoK7u/s9fx4/Pz8iIyOJiIjg66+/Zt68eXTs2NGuz/jx44mMjGTlypXkzp2bZs2asX///nsemyRzaFI4ZMgQu08HLBYLpUuXvuVjpk2bRunSpfHw8KB8+fLMnTs3g6KVbCkgAN5/3xSjad/eTHGcMMFMLx00SMVo7oZ7LijaCR789do6xN+heA/wzAfxF+HwNFj99LV1iA/Drk8g+qCjoxYREUezWuHSJcccqVzq0KxZM4KDg5kwYYJde3R0NNOmTaNbt26cOXOG9u3bkz9/fry8vChfvjw//fTTLe974/TRPXv2UKdOHTw8PAgPD2fRokUpHjNw4EBKliyJl5cXRYsWZdCgQcTFxQFmpG7o0KFs2bLF9l47KeYbp49u27aNhx9+GE9PT3LlykWPHj2Ijo62XU8asRs1ahT58uUjV65c9OrVy/Zc/8VisRASEkJoaCiNGzemb9++LF68mCtXrtj6BAQEEBISQrly5fjiiy+4cuXKTV+r3DsOHyksW7YskZGRtuOvv/76z76rVq2iffv2dOvWjU2bNtGqVStatWrF9u3bMzBiyZbCwmDyZPj7b3jgAbhyBd55B0qUgK++UjGau+XsAfmbwH1fQqsIeHQNlH0D/MuBNQFOLIGN/WB2EZhbAbYMgjPrwZro6MhFRCSjXb4MPj6OOS5fTlWILi4udOrUiQkTJmC9LpGcNm0aCQkJtG/fnqtXr1K1alV+//13tm/fTo8ePejYsSNr165N1XMkJibSpk0b3NzcWLNmDePGjWPgwIEp+vn6+jJhwgR27NjBJ598wtdff83HH38MQLt27ejfv7/d++127dqluMelS5do2LAhgYGBrFu3jmnTprF48WJ69+5t12/JkiXs27ePJUuWMHHiRCZMmJAiMb4dT09PEhMTif+P91aenp4AxMZqy6uM5PCk0MXFhZCQENuRO3fu/+z7ySef0KhRI15++WXKlCnD22+/TZUqVfjss88yMGLJ1mrUgOXL4ddfTXXSEyegZ0+oVAnmzVOxlPRgcYLc90HFd6DpNmixD6p8DHnqgsUZzm2Df96BBdVhZkFY+zwcm691iCIikqk888wz7Nu3j2XLltnaxo8fT9u2bfH39yd//vwMGDCASpUqUbRoUfr06UOjRo2YOnVqqu6/ePFidu3axaRJk6hYsSJ16tRh+PDhKfq9+eab1KpVi7CwMJo3b86AAQNsz+Hp6YmPj4/d++2kpOt6kydP5urVq0yaNIly5crx8MMP89lnn/H9999z4sQJW7/AwEA+++wzSpcuTbNmzWjatCl//PFHqr9ne/bsYdy4cVSrVg1fX98U1y9fvsybb76Js7MzDz30UKrvK3fP4Unhnj17CA0NpWjRonTo0IHDhw//Z9/Vq1dTv359u7aGDRuyevXq/3xMTEwMFy5csB0XNR1QbsdigTZt4J9/4JNPICjIfN2kCTz6KGzZ4ugIsxefolC6H9RfYtYh1vweCj4GLj5w5RjsHQdLG8OvuWHF43Dge4iJcnTUIiJyr3h5QXS0Y440rOcrXbo0tWrV4rvvvgNg7969rFixgm7dugGQkJDA22+/Tfny5QkKCsLHx4cFCxbc8r3u9Xbu3EnBggUJDQ21tdWsWTNFv59//pnatWsTEhKCj48Pb775Zqqf4/rnqlixIt7e3ra22rVrk5iYyO7du21tZcuWxdnZ2XaeL18+u6IxN3P+/Hl8fHzw8vKiVKlS5M2blx9//NGuT/v27fHx8cHX15dff/2Vb7/99o7WZGaE5cuX07x5c0JDQ29awfXGpXFJx8iRI219wsLCUlx/7733MviV2HNx5JPXqFGDCRMmUKpUKSIjIxk6dCgPPvgg27dvv+mnB8ePHydv3rx2bXnz5uX48eP/+RwjRoxg6NCh6R675ABubtC3L3TsaPY1/PRTWLwYKleGLl3M9NLr/qGWdOAeBEWeNkdCjJlWGjELjs42CeKRX8xhcYbgB6FACyjQ0iSWIiKSPVgscF1ykpl169aNPn368PnnnzN+/HiKFStmG+EaOXIkn3zyCaNHj6Z8+fJ4e3vTr1+/dJ0WuXr1ajp06MDQoUNp2LAh/v7+TJkyhQ8//DDdnuN6rq6uducWi4XExFsv9fD19WXjxo04OTmRL1++m45Ufvzxx9SvXx9/f3+Cg4PTNeb0dunSJSpWrMgzzzxDmzZtUlyPjIy0O583bx7dunWjbdu2du3Dhg2je/futvOb5T4ZyaFJ4fVlcCtUqECNGjUoXLgwU6dOtX3Kcrdee+01XnrpJdv50aNHCQ8PT5d7Sw4RGAgjR8ILL8Brr8HPP8P48ea/AwbAyy+bdQiSvpzdIbSROaxjzV6HSQniua1wcqk5Nr5k1iYWaAH5W0KuamaKqoiIyD32xBNP8L///Y/JkyczadIknn/+eSwWCwArV66kZcuWPP3004BZI/jvv/+m+n1omTJlOHLkCJGRkeTLlw+Av//+267PqlWrKFy4MG+88Yat7dChQ3Z93NzcSEhIuO1zTZgwgUuXLtlGC1euXImTkxOlSpVKVbz/xcnJieLFi9+yT0hIyG37ZBaNGze+5VYeISEhduezZs2iXr16FC1q/wG2r69vir6OlKneOQUEBFCyZEn27t170+shISF285oBTpw4cctvqLu7O35+frbD0Vm4ZGFFisCUKbB6NdSqZRajDxtmitF88w3c5h9cuQsWi0n2Kr4NTbZAi/1QZTTkfdiMGp7fDv8Mh4U1YGYBWNsTjs6FhKuOjlxERLIxHx8f2rVrx2uvvUZkZCRdunSxXStRogSLFi1i1apV7Ny5k549e6Z4H3sr9evXp2TJknTu3JktW7awYsUKu+Qv6TkOHz7MlClT2LdvH59++ikzZsyw6xMWFsaBAwfYvHkzp0+fJiYm5Rr9Dh064OHhQefOndm+fTtLliyhT58+dOzYMcUsPUc4f/48mzdvtjuOHDmSrs9x8eJFuyVnN/s+pdWJEyf4/fffbzrY9d5775ErVy4qV67MyJEj/7PwTkbJVElhdHQ0+/bts30acqOaNWumWMy6aNGim86vFrln7r8f/voLfvkFihWD48ehe3dTjGbBAkdHlzP4FIHS/4NH/oC2p6DWj1DoCXDxhSuRsPcrWNb02jrEtrB/EsSccXTUIiKSDXXr1o2zZ8/SsGFDu/V/b775JlWqVKFhw4bUrVuXkJCQNG3C7uTkxIwZM7hy5Qr33Xcfzz77LO+++65dnxYtWvDiiy/Su3dvKlWqxKpVqxg0aJBdn7Zt29KoUSPq1atHcHDwTbfF8PLyYsGCBURFRVG9enUee+wxHnnkkUxTzHHp0qVUrlzZ7kjv5WHh4eH4+/vbjhEjRtz1PSdOnIivr2+KaaZ9+/ZlypQpLFmyhJ49ezJ8+HBeeeWVu36+u2GxWh1XTnHAgAE0b96cwoULc+zYMd566y02b97Mjh07CA4OplOnTuTPn9/2Q1m1ahUPPfQQ7733Hk2bNmXKlCkMHz6cjRs3Uq5cuVQ9Z0REBAULFuTIkSMUKFDgXr48yQliY2HsWDNiePbaJuyPPgqjRkH58o6NLSdKiIGTy5KnmV6+blNhixMEP2CmmBZoAb5ZY5qKiEh2d/XqVQ4cOECRIkXw8PBwdDiSDd3qdywpN9ixYwf58+e3tbu7u+Pu7n7L+1osFmbMmPGfyX7p0qVp0KABY8aMueV9vvvuO3r27El0dPRtn/NecehIYUREBO3bt6dUqVI88cQT5MqVi7///tu2wPTw4cN2izVr1arF5MmT+eqrr6hYsSK//PILM2fOTHVCKJLu3NygXz/YuxdeeglcXWHhQjNq+OyzcOyYoyPMWZzdId+jUP1zaHkYGm2AcoMhoKLZ8/DkctjUH+aUgN/LwubX4PTf2g9RREQkh/P19bVbcna3ydmKFSvYvXs3zz777G371qhRg/j4eA4ePHhXz3k3HDpS6AgaKZR7at8+U4xm2jRz7uUFr7xiCtJkkUpq2dalQxAx24winlwG1uvm7nuEQP7mZgQx7yPgkrIymoiI3BsaKZR7LTUjhXeSG9xqpLBLly5s376d9evX3/Y+P/74I506deL06dMEBgamKYb0kqnWFIpkecWKwdSpsHIl1KxpitEMGWKK0Xz3nYrROJJ3YSjVBx5ZfG0d4mQo/CS4+sHV47Dva1jW3KxDXN4a9k+Aq6cdHbWIiIhkItHR0bZiN4CtiM/1e0NeuHCBadOm3XSUcPXq1YwePZotW7awf/9+fvzxR1588UWefvpphyWEoKRQ5N6oVcskhlOnmqqlkZHQrRtUqQKLFjk6OnELgLD2UPsnaHMK6i2Ekr3BqyAkXIaImfB3V5iRFxY9CDtHwYU9jo5aREREHGz9+vW2YjcAL730EpUrV2bw4MG2PlOmTMFqtdK+ffsUj3d3d2fKlCk89NBDlC1blnfffZcXX3yRr776KsNew81o+qjIvRYTA59/Dm+/DefOmbZGjczeh1oPm7lYrXB2sylSEzELzm6yv+5XGgq0hPwtIFcNcHJ2SJgiItlJ0tS+sLCwm25sLnK3rly5wsGDB9N9+mh2opFCkXvN3d0Uodm3zxSlcXWF+fOhYkXo0cNsaSGZg8UCQZWh/FvQeKMpVlPtMwhpAE6ucGEX7HgfFtWGmaGw5lmzTjH+sqMjFxHJspydzQdssbGxDo5EsqvLl83faVdXVwdHknlppFAko+3dC6++Cr/+as69vWHgQJM4qhhN5hV7HiLnmxHEY3Mh7nzyNWdPU/U0fwvI3ww88jguThGRLMZqtXL48GHi4uIIDQ3FyUljFpI+rFYrly9f5uTJkwQEBNx0L3TlBoaSQhFHWbkS+veHNWvMeWgovPsudOwIzpqWmKklxpntLZL2Q7x06LqLFgiuZRLEAi3Br5TDwhQRySpiY2M5cOAAiYnaIkjSX0BAACEhIVgslhTXlBsYSgpFHMlqNcVoXn0VkvamqVgRRo2C+vUdGpqkktUK57YmJ4hRG+yv+5Y0yWGBlpDrfq1DFBH5D4mJiZpCKunO1dXVNkX5ZpQbGEoKRTKDq1fhs8/gnXfg/LVpiU2awAcfQNmyjo1N0uZyBBydY5LEE3+aUcUk7sFmemmBlmadoouX4+IUERER5QbXKCkUyUzOnIFhw2DsWIiPBycn6N4dhg6FvHkdHZ2kVdwFiFxwbRTxd4g7l3zN2cMkhgVaQmgz8NTPV0REJKMpNzCUFIpkRnv2mCml06ebcx8fc/7ii+Cl0aUsKTEOTv1lEsSIWXDp4HUXLZD7/uTtLvxKm0qoIiIick8pNzCUFIpkZitWmGI069aZ8wIFTDGap582o4iSNVmtcH77tQRxNkSts7/uWyK5UE3uWlqHKCIico8oNzCUFIpkdomJ8PPP8NprcOhalctKleDDD+Hhhx0amqSTy0evrUOcDSf+gMTrCi245zLTSwu0NNteuGjbEhERkfSi3MBQUiiSVVy9Cp9+akYKL1wwbc2amWI0Zco4NjZJP3EXr61DnA3HfofYqORrTu4QUv/aNNNm4JlyvyURERFJPeUGhpJCkazm9GlTeGbcOFOMxtkZevSAIUMgjzZNz1YS4+HUymuFamZB9H7767lqJK9D9A/XOkQREZE0Um5gKCkUyap274aBA2HWLHPu62ummPbrB56eDg1N7gGrFc7vMMlhxCw4s9b+uk+x5AQxuDY4uTgmThERkSxEuYGhpFAkq1u2zBSj2XBt0/SCBc0U0w4dVIwmO7sSmbwf4vE/IDEm+Zp7LghtahLEfA3B1cdxcYqIiGRiyg0MJYUi2UFiIvz0E7z+Ohw+bNqqVDHFaOrWdWhokgHiouH4wmvTTH+7YR2iG+R95NooYnPwCnVcnCIiIpmMcgNDSaFIdnLliilGM3x4cjGaFi3g/fehdGnHxiYZIzEeTq8yhWoiZkH0XvvrQdVNgligJfiX1TpEERHJ0ZQbGEoKRbKjU6eSi9EkJJhiNM89B2+9BcHBjo5OMorVChd2JieIZ9YA1/2T710kOUEMfkDrEEVEJMdRbmAoKRTJznbtMsVoZs82576+Zorp//6nYjQ50ZXjZnppxCw4sRgSriZfcws06xALtLy2DtHXcXGKiIhkEOUGhpJCkZxgyRIYMAA2bjTnhQqZKabt26sYTU4VfwkiF5lqpkd/g5jTydec3CDvw1CghSlW45XfcXGKiIjcQ8oNDCWFIjlFYiL8+KMZKYyIMG3VqpliNHXqODY2cazEBDi9Onm7i4t77K8HVTPJYYGWEFBe6xBFRCTbUG5gKCkUyWmuXIGPP4YRIyA62rS1amWK0ZQs6dDQJJM4v+tagjjbJIt26xDDkhPEPA+Ck6ujohQREblryg0MJYUiOdWJE6YYzVdfmWI0Li7JxWhy53Z0dJJZXDkBx36/th/iIki4knzNNQBCm5gEMbQRuPo5LEwREZE7odzAUFIoktPt3AmvvAK//WbO/fzgjTegb1/w8HBsbJK5xF82iWHEbDg6B2JOJV9zcoU89ZL3Q/Qu6Lg4RUREUkm5gaGkUESMP/80xWg2bTLnhQubKabt2qkYjaSUmGC2uIiYZaaaXthtfz2wyrXtLlpAQEWtQxQRkUxJuYGhpFBEkiUmwg8/mGI0R4+aturVTTGaBx90bGySuV3YfW0EcRacWoXdOkSvQiY5LNAS8jykdYgiIpJpKDcwlBSKSEqXL5tiNO+9l1yMpnVrU4ymRAnHxiaZ39VTZpuLo7MhcsEN6xD9IbQx5G9p/uvm77g4RUQkx1NuYCgpFJH/dvw4DBkCX39tRhFdXOCFF2DwYMiVy9HRSVYQfwWOLzYJ4tE5cPVE8jWLC+StaxLEAi3Au5DDwhQRkZxJuYGhpFBEbu+ff0wxmrlzzbm/P7z5JvTpA+7ujo1Nsg5rIpxeYxLEiFlwYaf99cBK1xLEluZrrUMUEZF7TLmBoaRQRFJv8WLo3x+2bjXnYWFmiukTT+gNvKTdhT3JCeLplSZpTOJV8Np+iC0gT11wdnNYmCIikn0pNzCUFIpI2iQkwPffm20rjh0zbTVqmGI0tWs7NjbJuq6eTt4PMXIBJFxOvubqB/kamwQxtAm4BTgsTBERyV6UGxhKCkXkzly6BB99ZIrPXLpk2tq2NefFijk2NsnaEq7C8T+ubXcxB64eT75mcTEVTAu0MCOJPmEOC1NERLI+5QaGkkIRuTvHj5vCM99+a4rRuLpCr14waBAEBTk6OsnqrIlwZt21BHE2nP/H/npAhWv7IbY0eyNqGrOIiKSBcgNDSaGIpI/t2+Hll2H+fHMeEGASw169VIxG0s/FfckJ4qkV9usQPfNfG0FsaaqaOuv3TkREbk25gaGkUETS18KFMGAAbNtmzosWNcVoHntMoziSvmLOwLG519Yhzof4S8nXXHwhtJFJEPM3AbdAx8UpIiKZlnIDQ0mhiKS/hASYONFsWxEZadpq1jTFaGrWdGxskj0lXIUTS5JHEa9EJl+zOEOeOsn7IfoUcVycIiKSqSg3MJQUisi9Ex1tEsEPPoDL16pJPv64GTksWtSxsUn2ZU2EqA3JCeK5bfbXA8pf2+7i2jpEJ2fHxCkiIg6n3MBQUigi996xY6YYzXffgdVqitH06WNGEgM1rU/usej9EDHbJIgnl4M1Ifmai7dJDIOqQa5q5r++xcHi5Lh4RUQkwyg3MJQUikjG2brVFKNZuNCcBwaaZPGFF8BNm5NLBoiJMusQj86GY/Mh/mLKPq5+EFTVJIhJyaJ3Ea2JFRHJhpQbGEoKRSTjLVhgitFs327OixUz+xu2aaM33pJxEhPg4m44sx6irh1nN5n1iTdyC7RPEoOqglch/b6KiGRxyg0MJYUi4hgJCTB+vNm24vi1zclr1TJrEO+/37GxSc6VGA/ndyQniWfWw7ktkBibsq977hsSxWrgGapEUUQkC1FuYCgpFBHHio6GkSPNceWKaWvXDkaMgCKqEimZQEIsnN+enCRGrTfFa6zxKft6hNgniUHVwDNvxscsIiKpotzAUFIoIpnD0aNm1HDCBFOMxs0N+vaF119XMRrJfBKuwtmtySOKURvg/D/2RWySeBVIThCDrk099cid8TGLiEgKyg0MJYUikrls2WLWGy5ebM6DguCtt+C551SMRjK3+Mtwdst1ieJ6OL8TuMmfWe+wG0YUq5h1iyIikqGUGxhKCkUk87FaYf58kxzu2GHaihc3+x22aqU1W5J1xF2Es5vtp55e/PfmfX2KpUwUXf0yNFwRkZxGuYGhpFBEMq/4eLO34eDBcOKEaXvwQRg1Cu67z7Gxidyp2PNwdqN91dPo/Tfv61fqhqmnlc3eiiIiki6UGxhKCkUk87t40YwSfvhhcjGa9u1h+HAIC3NoaCLpIibKrEtMWp8YtR4uHUrZz+IEfmXsq54GVAQXz4yPWUQkG1BuYCgpFJGsIyLCFKOZONFMMXV3h//9D157DQICHB2dSPq6euq6RPHa9NMrR1P2sziDfzn7iqcB5cHZPeNjFhHJYpQbGEoKRSTr2bTJrDf8809znitXcjEaV1fHxiZyL12JNImiberpOrh6MmU/J1fwL39DoljOtIuIiI1yA0NJoYhkTVYrzJ0LL78MO3eathIlzDTTli1VjEZyBqvVjB5evz4xaj3EnEnZ18kdAivaTz31KwNOLhkft4hIJqHcwHBydAAiInfEYoGmTWHrVvjiCwgOhj17oHVrqFsX1q93dIQi957FYvZBLNgKKr4D9eZDm1PQ4gA8MA3CB0LeR8A1ABJj4Mxa2DMW1jwDcyvAND9YWBvW/w8OfG+20Ei8yV6LIiICwPLly2nevDmhoaFYLBZmzpxpd71Lly5YLBa7o1GjRnZ9oqKi6NChA35+fgQEBNCtWzeio6Mz8FWkpI8HRSRrc3Ex00afegrefx8++giWL4fq1aFDB3j3XShc2NFRimQciwV8wsxR6DHTZrWaCqfXr0+M2gDxF+H0KnMkcfEx22FcX/XUt5gpciMiksNdunSJihUr8swzz9CmTZub9mnUqBHjx4+3nbu726/x7tChA5GRkSxatIi4uDi6du1Kjx49mDx58j2N/VY0fVREspcjR+CNN+D77825uzu8+CK8+ir4+zs2NpHMxJoIF/fcMPV0IyRcTtnX1d8+UcxVDbyLaJq2iGR5d5MbWCwWZsyYQatWrWxtXbp04dy5cylGEJPs3LmT8PBw1q1bR7Vq1QCYP38+TZo0ISIigtDQ0Dt9KXdFH/uJSPZSsCBMmgQbNphppDEx8N57ULw4jB0LcXGOjlAkc7A4mX0Qi3SAqh9DgxXw+AVosh3unwAle0Ou+8HZA+LOw4klsHMkrGwHs4vBr7ngz0dh8+twZDpcOmxGJEVEsqCLFy9y4cIF2xETE3PH91q6dCl58uShVKlSPP/885w5k7zOe/Xq1QQEBNgSQoD69evj5OTEmjVr7uo13A1NHxWR7KlKFVOd9LffTDGa3buhVy/49FNTjKZ5c41yiNzIyRkCypqjaGfTlhgH53ck76F4Zj2c2wKxZ+H4InMkcQ9OHklMGlX0csyn3iIiaREeHm53/tZbbzFkyJA036dRo0a0adOGIkWKsG/fPl5//XUaN27M6tWrcXZ25vjx4+TJk8fuMS4uLgQFBXH8+PG7eQl3RUmhiGRfFotJ/ho1gm++MdtW7N5tqpPWrQujRkHVqo6OUiRzc3I1VUsDK0KxbqYtIRbOb79ufeJ6OLcNYk5B5DxzJPHMZ78+MagqeOZ1zGsREfkPO3bsIH/+/LbzG9cBptaTTz5p+7p8+fJUqFCBYsWKsXTpUh555JG7jvNeUVIoItmfqys8/7x9MZqlS6FaNXj6aRg+3Ew7FZHUcXa7tsawChTvYdoSrsLZrfZbY5z/x+yteHSOOZJ4FUxOEJP+65HbMa9FRATw9fXFz88v3e9btGhRcufOzd69e3nkkUcICQnh5En7/WXj4+OJiooiJCQk3Z8/tZQUikjO4e9vEsDnnjPFaH74wRy//JJcjOYe/EEQyRGcPSD3feZIEn8Zzm62H1G8sAsuHzFHxIzkvt5hN0w9rQpuARn8IkRE0ldERARnzpwhX758ANSsWZNz586xYcMGql6brfTnn3+SmJhIjRo1HBanqo+KSM61fj3072+2sACz1+HQodC9u9nqQkTSX9xFOLspeVuMqPVw8d+b9/Upbr8+MagyuOqDGxFJP2nNDaKjo9m7dy8AlStX5qOPPqJevXoEBQURFBTE0KFDadu2LSEhIezbt49XXnmFixcvsm3bNtuU1MaNG3PixAnGjRtn25KiWrVq2pIiIykpFBE7VivMng2vvAL/XntjWro0jBwJTZuqGI1IRog9D2c32m+PEb3/Jh0tpmLq9VtjBFYCF++MjlhEsom05gZLly6lXr16Kdo7d+7MF198QatWrdi0aRPnzp0jNDSURx99lLfffpu8eZPXUkdFRdG7d2/mzJmDk5MTbdu25dNPP8XHxyddX1taKCkUEQGzVcVXX8GQIXD6tGl7+GFTjKZyZYeGJpIjxZwx+yYmJYln1sPlwyn7WZzAL/xagljV/DegIrh4ZnzMIpLlKDcwlBSKiFzv/HkYMQJGjzZ7HFos0KkTvPMO6N8MEce6ejJ5W4ykZPHKsZT9LM7gX85+6mlAeXC+s2qCIpJ9KTcwlBSKiNzMwYOmGE3S/H5PT3jpJRg4EHx9HRqaiFznSuQNieI6kzzeyMkVAirYTz31L2vaRSTHUm5gKCkUEbmVdetMMZoVK8x5njwwbBh066ZiNCKZkdUKV47ajyZGrTfTUW/k5G7WJF5f9dSvNDjp/22RnEK5gaGkUETkdqxWmDXLFKPZs8e0hYebYjSNG6sYjUhmZ7XCpUP26xOj1kPc+ZR9nb1MldOk9YlB1cC3JDg5Z3zcInLPKTcwlBSKiKRWbCx8+aXZtuLMtVGHRx4xxWgqVXJoaCKSRlYrRO+7YURxA8RHp+zr4gNBVa7bGqMa+BYzRW5EJEtTbmAoKRQRSatz52D4cPjkE5MoWizQubMpRpM/v6OjE5E7ZU2EC/8m758Ytd5UQE24nLKvqz8EVbWfeuodppkDIlmMcgNDSaGIyJ06cABefx2mTDHnnp4wYICZZurAvYZEJB0lJsCFXfZTT89thoSrKfu6BdkniUHVwKuAEkWRTEy5gaGkUETkbq1ZY4rRrFxpzvPmhbffhmeeAWetQxLJdhLj4PwO+/WJ57aY9ht55LmWIFa9LlEMzfiYReSmlBsYSgpFRNKD1QozZpgtK/buNW3lypliNA0baqRAJLtLiIHz2+3XKJ7bDtb4lH0989mvT8xVzSSPIpLhlBsYSgpFRNJTbCx88YXZtiIqyrQ1aGCSw4oVHRubiGSs+Ctwbqv9GsXz/5i1izfyKnjD1NOq4J4r42MWyWGUGxhKCkVE7oWzZ+Hdd2HMmORiNF27mmmloZo6JpJjxV+Cs1vsp55e2AXc5O2YdxH79YlBVcAtIKMjFsnWlBsYSgpFRO6l/fvhtddg6lRz7uUFL79sCtKoGI2IAMRdhLOb7KeeXtxz876+JW5Yo1gFXH0zNl6RbES5gaGkUEQkI6xebYrRrF5tzvPlM6OGXbqoGI2IpBR7zmyHcX3V00sHbtLRAn6l7NcnBlYCF+8MDlgka1JuYCgpFBHJKFYr/PqrKUazf79pK18eRo2CRx91bGwikvnFnLm2PnFDcqJ4+XDKfhYn8Au3n3oaWBGcPTI+ZpFMTrmBoaRQRCSjxcTA2LFmpPDsWdPWsKFJDsuVc2xsIpK1XD1pksTrp55eOZayn8UFAsrZjyj6lwdnt4yPWSQTUW5gKCkUEXGUqCh45x347DOIiwMnJ7O34bBhZnqpiMiduHzMvuLpmXUQcyplPyc3CKiQvEYxVzXwLwtOrhkfs4iDKDcwlBSKiDjavn3w6qvwyy/m3NsbXnnFrEH01rogEblLVitcjrBfnxi1HmKjUvZ1cjdrEq/fHsOvDDhp7bNkT8oNDCWFIiKZxapVJhH8+29zni+fGUns3FnFaEQkfVmtcOngtUTxuumncedT9nX2gqDK122NUQ38Spq1iyJZnHIDQ0mhiEhmYrXCtGlm5PDAtUqDFSqY9YYNGjg2NhHJ3qyJEL3ffn1i1AaIj07Z18XXbIdx/RpFn2JmT1aRLES5gaGkUEQkM4qJMWsN33kHzp0zbY0bw8iRULasQ0MTkRzEmggX/r0uSVwPUZsg4XLKvq4ByWsTk/ZR9A5ToiiZmnIDQ0mhiEhmduaMqVL6+ecQH2+K0Tz7LAwdCiEhjo5ORHKixHi4sMt+feLZzZAYk7KvW5D9+sSgauBVQImiZBrKDQwlhSIiWcGePWZK6fTp5tzHx+x3+NJL4OXl2NhERBLj4PwO+0Tx3BbTfiOPPPbrE3NVA09VXBbHUG5gKCkUEclK/vrLFKNZu9ac588P774LHTuaUUQRkcwiIQbOb7dfo3huG1gTUvb1DLVPEoOqmuRR5B5TbmAoKRQRyWqsVvj5ZzNyeOiQaatUyRSjeeQRh4YmInJL8Vfg3Fb77TEu7DBrF2/kVei6aadVzeGeK+NjlmxNuYGhpFBEJKu6ehXGjDEjheevlZFv2hQ++ADCwx0bm4hIasVfMmsSrx9RvLAbuMlbVO8i9usTg6qAW0AGByzZiXIDQ0mhiEhWd/o0DBsGX3yRXIyme3dTjCZvXkdHJyKSdnEX4ewm+0Tx4p6b9/UtYT/1NLAyuPpmbLySZSk3MJQUiohkF//+a6aUzphhzn18zPmLL6oYjYhkfbHnIGqj/dTTSwdu0tECfqXtq54GVgIX/TsoKSk3MJQUiohkN8uXm2I069eb8wIFzBTTp59WMRoRyV5izkDUBvuqp5ePpOxncQL/svZVTwMrgLNHxscsmYpyA0NJoYhIdpSYCFOmwGuvweHDpq1yZfjwQ6hXz7GxiYjcS1dOJCeKSceVyJT9LC4QUM5+6ql/eXB2y/iYxWGUGxiZ5iPj9957D4vFQr9+/f6zz4QJE7BYLHaHh4c+4RERScHJCZ56CnbvhvfeAz8/2LQJHn4YWrSAXbscHaGIyL3hmRfyN4Hyg+Gh2dD6GLQ6CnVmQ7nBENoE3IPBGm8K3Oz7BtY9B/OrwTRfmF8d1j4P+76Fs/+x16JINuPi6AAA1q1bx5dffkmFChVu29fPz4/du3fbzi0Wy70MTUQka/PwMJvcP/NMcjGaOXNg7lzo2RPeegvyaC8wEcnmvELNUaC5Obda4XKE/frEqPUQG5XctvfaY509IKCSfdVTv9Lg5OyoVyOS7hyeFEZHR9OhQwe+/vpr3nnnndv2t1gshISEZEBkIiLZSHCw2b6id2+TJM6aBWPHwvffmymm/fqBp6ejoxQRyRgWC3gXNEfB1qbNaoVLB+2TxKgNEHcezvxtjiTOXmY7jOunnvqWMGsXRbIghyeFvXr1omnTptSvXz9VSWF0dDSFCxcmMTGRKlWqMHz4cMqWLfuf/WNiYoiJibGdX7x4MV3iFhHJkkqVgpkzYelSGDAANmyA1183I4jDh5sppypGIyI5kcUCPkXMUehx02ZNhIv77NcnRm2E+Gg49Zc5krj4pkwUfYqZ+4pkcg5NCqdMmcLGjRtZt25dqvqXKlWK7777jgoVKnD+/HlGjRpFrVq1+Oeff/5zYeiIESMYOnRoeoYtIpL11a0La9fC5MkmKTxyBDp2hNGjTTGahx5ydIQiIo5ncQK/EuYIa2/aEhPg4r83FLPZCPEX4eQycyRxDYCgqvZTT70LK1GUTMdh1UePHDlCtWrVWLRokW0tYd26dalUqRKjR49O1T3i4uIoU6YM7du35+23375pnxtHCo8ePUp4eHiOrzAkImJz5YpJBkeMgKTZFC1awAcfmJFFERG5tcR4uLDLfurp2c2QGJOyr3su+60xclUDz/xKFB1E1UcNhyWFM2fOpHXr1jg7Jy/STUhIwGKx4OTkRExMjN21//L444/j4uLCTz/9lKrn1Q9eROQ/nDwJQ4fCl19CQgI4O8Nzz5liNMHBjo5ORCRrSYyD8/9ctz5xPZzbevNqph557ZPEoKrgmS/jY86BlBsYDksKL168yKFDh+zaunbtSunSpRk4cCDlypW77T0SEhIoW7YsTZo04aOPPkrV8+oHLyJyGzt3mmI0c+aYcz8/M8X0f/8z1UxFROTOJMTAuW3XTTvdYM6tCSn7eobekChWAw99QJfelBsYDltT6OvrmyLx8/b2JleuXLb2Tp06kT9/fkaMGAHAsGHDuP/++ylevDjnzp1j5MiRHDp0iGeffTbD4xcRybbKlIHZs+HPP00xmk2b4NVXTbXSESPgySdVjEZE5E44u5sEL1e15Lb4K2YE8frtMS7sgCvH4OhscyTxKmS/PjGoKrgHZfzrkGzH4dVHb+Xw4cM4XffG4+zZs3Tv3p3jx48TGBhI1apVWbVqFeHh4Q6MUkQkm3r4YVi/Hn780YwUHj4MHTqY9YejRkGdOo6OUEQk63PxhNw1zJEk/pJZk3j91NMLu+HyYXMcmZ7c16eo/YhiYBVw88/wlyFZm8OmjzqKhohFRO7A5cvJxWiio01bq1bw/vtQsqQjIxMRyRniLkDUJvsRxei9N+/rW9J+2mlgZXD1ydh4swjlBoaSQhERSb0TJ2DIEPjqK0hMBBcXeP55GDwYcud2dHQiIjlL7FmzHYat6ukGuHTgJh0t4Ff6hkSxErh4ZXTEmY5yA0NJoYiIpN2OHfDKK/D77+bc3x/eeAP69FExGhERR4o5k7yHYtL008tHUvazOIF/WfvtMQIrgHPO+jdcuYGhpFBERO7cH39A//6wZYs5DwszU0zbtdOeWyIimcWVE8mJYtR6OLMOrh5P2c/iAgHl7UcU/cuBs1vGx5xBlBsYSgpFROTuJCTADz+YkcKjR03bfffBhx/CAw84NjYREbm5y8fs1ydGrYeYUyn7OblBQEX7qqf+4eCUqetVpppyA0NJoYiIpI/Ll+Gjj+C99+DSJdPWpo0pRlO8uGNjExGRW7NazTTT69cnRq2H2KiUfZ09IKCSfaLoVxqcnDM87Lul3MBQUigiIunr+HF46y345htTjMbVFV54AQYNgly5HB2diIikltUKlw7ajyZGrTeVUG/k4m2qnF6/PYZvCbN2MRNTbmAoKRQRkXvjn3/g5Zdh3jxzHhAAb74JvXuDu7tDQxMRkTtkTYSL+5ITxKj1pgJqfHTKvi6+EFTVfkTRp2imWnOu3MBQUigiIvfWokUwYABs3WrOixQxU0wffzxTvTEQEZE7lJgAF/+1H1E8uwkSrqTs6xqQnCSWfcPh+ycqNzAy93iuiIhkfQ0awMaN8N13kC8fHDhgqpPWqgWrVjk6OhERuVtOzuBfBop0hGqfwKMr4fEL0GQr1PgOSrwAuWqAkzvEnYPji2H3p1ly+4vly5fTvHlzQkNDsVgszJw503YtLi6OgQMHUr58eby9vQkNDaVTp04cO3bM7h5hYWFYLBa747333ktTHOPHj+fy5cvp8ZIAJYUiIpIRnJ2ha1fYsweGDgVvb/j7b6hd24wY7tvn6AhFRCQ9OV3b3qJYV6j+OTT8G564CI03wX1fQ/nBWbKC6aVLl6hYsSKff/55imuXL19m48aNDBo0iI0bNzJ9+nR2795NixYtUvQdNmwYkZGRtqNPnz5piuPVV18lJCSEbt26sSodPmDNej8JERHJury9YfBg6N7d/Pe77+CXX2DWLLPW8M03ISjI0VGKiMi94OQKgZXMkUU1btyYxo0b3/Sav78/ixYtsmv77LPPuO+++zh8+DCFChWytfv6+hISEnLHcRw9epQ5c+YwYcIE6tatS9GiRenatSudO3e+o/tqpFBERDJevnzw9deweTM0bAhxcfDxx2brio8/hpgYR0coIiI5yMWLF7lw4YLtiEmnv0Pnz5/HYrEQEBBg1/7ee++RK1cuKleuzMiRI4mPj0/TfV1cXGjdujWzZs3iyJEjdO/enR9//JFChQrRokULZs2aRWJiYqrvp6RQREQcp3x5mD/fHOXLw9mz8NJLEB5uRhBzVi00ERFxkPDwcPz9/W3HiBEj7vqeV69eZeDAgbRv3x4/Pz9be9++fZkyZQpLliyhZ8+eDB8+nFdeeeWOnydv3rw88MAD1KxZEycnJ7Zt20bnzp0pVqwYS5cuTdU9lBSKiIjjNWwImzaZvQ1DQmD/frPWsHZtWL3a0dGJiEg2t2PHDs6fP287Xnvttbu6X1xcHE888QRWq5UvvvjC7tpLL71E3bp1qVChAs899xwffvghY8aMSfPo5IkTJxg1ahRly5albt26XLhwgd9++40DBw5w9OhRnnjiCTp37pyqeykpdKArV8yMKRERwRSj6dbNFKN56y3w8jIJYa1aplrp/v2OjlBERLIpX19f/Pz8bIf7Xeynm5QQHjp0iEWLFtmNEt5MjRo1iI+P5+DBg6l+jubNm1OwYEEmTJhA9+7dOXr0KD/99BP169cHwNvbm/79+3PkyJFU3U9JoQN98onZruudd+DkSUdHIyKSSfj4wJAhJjl85hmzl+HUqVCmjNnv8OxZR0coIiJyU0kJ4Z49e1i8eDG5cuW67WM2b96Mk5MTefLkSfXz5MmTh2XLlrF9+3b69etH0E2KtAUHB3PgwIFU3U9JoQNNnw5Hj8KgQVCwIHTqBOvWOToqEZFMIjQUvv3WFKNp0ABiY+HDD00xmk8+MeciIiIZKDo6ms2bN7N582YADhw4wObNmzl8+DBxcXE89thjrF+/nh9//JGEhASOHz/O8ePHib32N2v16tWMHj2aLVu2sH//fn788UdefPFFnn76aQIDA1Mdx0MPPUSVKlVStMfGxjJp0iQALBYLhQsXTtX9LFZrzlrFHxERQcGCBTly5AgFChRwaCwxMTBtGowZA2vXJrfXqAF9+pjlNG5ujotPRCTTsFphwQIzUvjPP6atWDF4/31o08aMJoqIiKRRWnODpUuXUq9evRTtnTt3ZsiQIRQpUuSmj1uyZAl169Zl48aNvPDCC+zatYuYmBiKFClCx44deemll9I0ZdXZ2ZnIyMgUo4tnzpwhT548JCQkpPpeoKTQ0eHYrF1rksOff05eZ5g3L/TsCc89Z6q3i4jkePHxMH68mWJx4oRpq13bjCDWqOHY2EREJMvJrLnB7Tg5OXHixAmCg4Pt2rds2UK9evWIiopK0/2UFGYyJ07AV1/BF19AZKRpc3GBxx4zo4c1a+oDcRERLl6EkSNh1ChTtQvgySdh+HCzWFtERCQVMntucKPKlStjsVjYsmULZcuWxcXFxXYtISGBAwcO0KhRI6ZOnZqm+yopzKTi4syawzFjYOXK5PYqVUxy+OST4OHhuPhERDKFpIXZEyaYKaZubvC//8Hrr8MNGwWLiIjcKKvkBkmGDh1q+2///v3x8fGxXXNzcyMsLIy2bdvilsY1aEoKs4CNG+Gzz2DyZLMOESB3bujeHZ5/3hSpERHJ0TZvNusN//jDnOfKZba16NlTi7NFROQ/ZcXcAGDixIm0a9cOj3QaJVL10SygShX47juIiIARI0wSePq0+bpIETO1dNky8yG5iEiOVKkSLFoEv/8O4eFw5gz07QvlysGMGfoHUkREspXOnTunW0IISgqzlNy54dVXzf7Nv/4KdetCQkLy15Uqwddfw+XLDg5URMQRLBZo0gS2bIFx4yBPHrPXYZs28NBD2vNHRESytKCgIE6fPg1AYGAgQUFB/3mklaaPZnHbtpmppd9/n1xrITAQunWDF15QvQURycEuXjRbVnz4IVy9atqeesoUo0nlvk0iIpK9ZaXcYOLEiTz55JO4u7szYcIELLeoPtm5c+c03VtJYTZx9qyZYvr553DggGmzWKB5c1OY5pFHVLVURHKoiAh44w3z6ZnVCu7uycVo/P0dHZ2IiDhQds0N0krTR7OJwEDo39/MlJo9Gxo0MO99kr4uWxbGjoXoaEdHKiKSwQoUgIkTYf16qFfPVOz64AMoXtysO5w6FY4dc3SUIiIiqTZhwoSbtsfHx/Paa6+l+X53NFJ45MgRLBaLLZteu3YtkydPJjw8nB49eqQ5iIyUkz4N2LXLTC2dODE5GfTzg65doVcvKFHCsfGJiGQ4q9UUo3n5ZfOP5PWKFIEHHkg+SpcGJ312KiKSnWXV3MDPz4+GDRvy1VdfERgYCMDu3bt56qmnOHPmDAcPHkzT/e7or91TTz3FkiVLADh+/DgNGjRg7dq1vPHGGwwbNuxObin3QOnSJik8ehQ++cQkgRcumK9LljT1GObNg8RER0cqIpJBLBZo1swsyP7lFzO/vnJlk/wdOGCmmPbsaaZX5MkDLVvCyJGwenXynkAiIiIOtmnTJiIiIihfvjyLFi3i888/p0qVKpQuXZotW7ak+X53NFIYGBjI33//TalSpfj000/5+eefWblyJQsXLuS5555j//79aQ4ko2TVTwPSQ2IiLFwIY8aYZDDpJ1+ihBk57NJFy2tEJIe6cAH+/hv++gtWrIA1a5KrdyXx8ID77kseSaxZEwICHBKuiIikj6ycGyQmJtKvXz8+//xznJ2dmThxIu3bt7+je91RUujj48P27dsJCwujRYsW1K5dm4EDB3L48GFKlSrFlRv/kGYiWfkHn5727jVFab77zrwXAvD2hs6doXdvKFPGsfGJiDhUbCxs2mSSxKTjWhlwG4sFypc3CeKDD5r/5uC/KyIiWVFWzg3mzJlDt27dKFmyJP/++y8VKlRg0qRJhIaGpvledzR9tGzZsowbN44VK1awaNEiGjVqBMCxY8fIlSvXndxSMljx4vDxx2Zq6dixZq/nS5eSv27QwBSpSUhwdKQiIg7g5gY1apgKXjNmwMmTZg3iN9+YaRXFi5vpFlu3mn8427eHggUhLAyeftrsk7h9u+bni4jIPdGzZ08ef/xxBg4cyIoVK9i6dStubm6UL1+eqVOnpvl+dzRSuHTpUlq3bs2FCxfo3Lkz3333HQCvv/46u3btYvr06WkOJKNk5U8D7iWrFf7800wtnTMn+X1MkSJmv8NnnoE72AdTRCT7On7cfiRx06aUSWBAANSunTzltHp1syWGiIhkClk1NyhXrhw//vgjFStWtGv//PPPGThwINFp3HLgjvcpTEhI4MKFC7ZqNwAHDx7Ey8uLPHny3MktM0RW/cFnpIMHzQff33xj9j8E8PQ0H3736WNmS4mIyA0uXjRrEZOSxNWr4fJl+z7u7iYxTEoSa9UyewqJiIhDZNXcICYmBvf/+JBx9+7dlCpVKk33u6Ok8MqVK1itVry8vAA4dOgQM2bMoEyZMjRs2DCtt8tQWfUH7wiXL8NPP5nRw+uLGD30kEkOW7YEFxfHxScikqnFxZl/PJOSxBUrzDTUG5UrZ78VRuHCGR+riEgOlZVzg3379jF+/Hj27dvHJ598Qp48eZg3bx6FChWibNmyabrXHSWFjz76KG3atOG5557j3LlzlC5dGldXV06fPs1HH33E888/n9ZbZpis/IN3FKvVvJ8ZMwamT09eZ1iwIDz/PHTvDrlzOzZGEZFMz2o1Vb6un3L6778p+xUsaJ8kli0Lzs4ZH6+ISA6QVXODZcuW0bhxY2rXrs3y5cvZuXMnRYsW5b333mP9+vX88ssvabrfHSWFuXPnZtmyZZQtW5ZvvvmGMWPGsGnTJn799VcGDx7Mzp0703rLDJNVf/CZRUSEqZ/w1Vdw6pRpc3c3NRb69IEqVRwbn4hIlnLyJKxcmZwkbtwI8fH2ffz9zTTT69cleno6Jl4RkWwmq+YGNWvW5PHHH+ell17C19eXLVu2ULRoUdauXUubNm2IiIhI0/3uKCn08vJi165dFCpUiCeeeIKyZcvy1ltvceTIEUqVKsXlG9dQZCJZ9Qef2Vy9ClOnmtHD9euT22vVMltatG1riveJiEgaXLqUcl3ijcUCXF2hWrXkrTBq1QJV/hYRuSNZNTfw8fFh27ZtFClSxC4pPHjwIKVLl+bq1atput8dbUlRvHhxZs6cyZEjR1iwYAGPPvooACdPnsTPz+9ObilZjIcHdOoEa9ea9yxPPWXep6xaZb4OC4OhQ01xPhERSSVvb3j4YRg8GBYuNNW+NmyATz6Bxx+HkBCzVnH1ahg5Elq0MPP3y5aFnj3h++/hwAEzVVVERLKtgIAAIiMjU7Rv2rSJ/Pnzp/l+dzRS+Msvv/DUU0+RkJDAww8/zKJFiwAYMWIEy5cvZ968eWkOJKNk1U8DsoLISDOtdNy45GTQ1dW8j+nb12z5JSIid8FqNUlfUuGav/4y+yfeKDQ0ebrpgw+astFalygikkJWzQ0GDBjAmjVrmDZtGiVLlmTjxo2cOHGCTp060alTJ95666003e+Ot6Q4fvw4kZGRVKxYEScnM+C4du1a/Pz8KF269J3cMkNk1R98VhIbC7/+aqaWrl6d3F69upla2q6dtukSEUk3p06ZaRpJU07Xr0+5LtHX135d4n33wbUK4iIiOVlWzQ1iY2Pp1asXEyZMICEhARcXFxISEnjqqaeYMGECzmn8IPCOk8IkSYsYs8o3Mav+4LOqDRtMcvjTTyZZBAgOhh49TOXSOxjdFhGRW7l8GdatS04SV62CCxfs+7i4QNWqyUli7drmH2cRkRwmq+cGhw8fZvv27URHR1O5cmVKlChxR/e5o6QwMTGRd955hw8//JDoawvgfX196d+/P2+88YZt5DAzyuo/+Kzq1Cn4+mv44gtTwRTMTKY2bUzV0gceAIvFsTGKiGRLCQmwbZv9fonHjqXsV7q0/VYYRYvqH2YRyfaUGxh3lBS+9tprfPvttwwdOpTatWsD8NdffzFkyBC6d+/Ou+++m+6Bphf94B0rPh5mzjSjh8uXJ7dXqmSmlj71lCqti4jcU1YrHDpkv1/iP/+k7BcSYp8kVqxoRhhFRLKRrJQbvPTSS6nu+9FHH6Xp3neUFIaGhjJu3DhatGhh1z5r1ixeeOEFjh49mtZbZpis9IPP7rZsgc8+gx9/hCtXTFtQEDz7LLzwAhQu7Nj4RERyjKgoM800qXjNunWmyun1vL2hZs3k4jU1apg2EZEsLCvlBvXq1UtVP4vFwp9//pmme99RUujh4cHWrVspWbKkXfvu3bupVKkSV5Le4WdCWekHn1NERcG338LYsXDwoGlzcjKV1vv0gXr1NINJRCRDXbliCtYkjSSuXAnnz9v3cXaGKlXs1yXmzeuYeEVE7pByA+OOksIaNWpQo0YNPv30U7v2Pn36sHbtWtasWZNuAaY3/eAzr4QE+O03M7X0jz+S28uWNVNLO3bUh9IiIg6RmGimmF6/LvHIkZT9SpSwn3JaooQ+1RORTC075AZHrv17XLBgwTu+xx0lhcuWLaNp06YUKlSImjVrArB69WqOHDnC3LlzefDBB+84oHstO/zgc4IdO8zU0kmT4NIl0+bvD888A716QbFijo1PRCTHO3zYfl3i9u1mveL18uSxTxIrVTIb2IqIZBJZNTeIj49n6NChfPrpp7bCnz4+PvTp04e33noL1zT+W3vHW1IcO3aMzz//nF3XNs0tU6YMPXr04J133uGrr766k1tmiKz6g8+pzp2DCRPg889h717TZrFAkyZmammDBmaqqYiIONjZs2Zz2qQkce1aiImx7+PlBfffn5wk3n+/2UNRRMRBsmpu8PzzzzN9+nSGDRtmN0g3ZMgQWrVqxRdffJGm+931PoXX27JlC1WqVCEhISG9bpnusuoPPqdLTIT5883U0vnzk9tLljRTSzt3Bj8/x8UnIiI3iIlJuS7x7Fn7Pk5OZvQwqXhN7dqQL59DwhWRnCmr5gb+/v5MmTKFxo0b27XPnTuX9u3bc/7GdeC3oTEWyRKcnMzo4Lx5sHs39O1rPlz+91/zdf78ZuRw925HRyoiIgC4u5skb+BAmDMHTp82U0zHjYOnn4awMPOJ38aN8Omn8PjjEBoKxYtDly7wzTewa1fKKakiIoK7uzthYWEp2osUKYKbm1ua76eRQsmyLl40aw4/+8y8b0jy6KMmQWzSRFNLRUQytYgIM4KYtBXG1q0pk8DcuU1ymTSaWLky3MEbHhGRm8mqucGwYcPYtWsX48ePx93dHYCYmBi6detGiRIleOutt9J0PyWFkuVZrbB4sZla+ttvye8nihY1RWmeeQYCAhwaooiIpMb58/brEtesgatX7ft4epo9EpPWJdasqfUDInLHsmpu0Lp1a/744w/c3d2pWLEiYHKx2NhYHnnkEbu+06dPv+390pQUtmnT5pbXz507x7Jly5QUisPs32/2O/z2W1OkBkxdg44dzdrDcuUcGp6IiKRFbKyZXnp9ldMzZ+z7ODlBhQr2VU7z53dMvCKS5WTV3KBr166p7jt+/Pjb9klTUpjaJ0/NEztKVv3BS9pcugQ//mhGD7dvT26vV89MLW3eHFxcHBefiIjcgcREs3j8+iRx//6U/cLCzFTTpCSxdGmtJxCRm8qKuYHVauXIkSMEBwfj6emZLvdM1+mjWUFW/MHLnbNaYflykxzOmGHeTwAUKgQvvADPPgu5cjk2RhERuQvHjpl1iUlJ4ubNyf/YJwkKSl6X+MADULWqKYQjIjleVswNEhMT8fDw4J9//qFEiRLpck8lhZJjHD5sit599VXy7CMPD3jqKTN6WKmSQ8MTEZH0cPGi/brEv/+GK1fs+7i7w333JY8m1qypxeciOVRWzQ3Kli3Lt99+y/33358u91NSKDnO1aswZYoZPdy4Mbn9gQdMcti6Nbi6Oi4+ERFJR3FxsGmT/ZTTU6fs+1gsUL68/brEggUdE6+IZKismhvMmTOHDz74gC+++IJy6VA0Q0mh5FhWq/kwecwY+OUXiI837fnzw3PPQY8ekCePY2MUEZF0ZrXCnj0mOUzaCmPv3pT9ChVKThAffBDCw7UuUSQbyqq5QWBgIJcvXyY+Ph43N7cUawujoqLSdD8lhSKYJSlffmmOEydMm5sbtGtnRg+rV3dsfCIicg8dP26/LnHTJrixknpAgP26xGrVzBoEEcnSsmpuMHHixFte79y5c5rup6RQ5DoxMWbUcMwYsz1Wkho1THL4+OPaM1lEJNuLjjZ/BJKSxNWrTVnr67m5mU8Mk5LEWrVMQRsRyVKUGxhKCkX+w7p1Jjn8+WezVRZA3rzQs6c5QkMdG5+IiGSQuDjYssV+XWLStJLrlStnvy6xUCGzXlFEMq2snBvs27eP8ePHs2/fPj755BPy5MnDvHnzKFSoEGXLlk3TvZQUitzGiRPw9dfwxRdmmimYPQ7btoW+fU3ROv3NFxHJQaxW2LfPPkncvTtlvwIF7JPEcuXA2Tnj4xWR/5RVc4Nly5bRuHFjateuzfLly9m5cydFixblvffeY/369fzyyy9pup+SQpFUioszex2OGWP+/iepUsVMLX3ySS0vERHJsU6ehFWrkovXbNyYXMEsiZ+fmWaatBVG9eqQThtPi8idyaq5Qc2aNXn88cd56aWX8PX1ZcuWLRQtWpS1a9fSpk0bIiIi0nQ/JYUid2DTJvjsM5g82WxxAZA7N3TvbiqXFirk2PhERMTBLl2CtWuTRxJXrTJrFa/n6moK1iSNJNauDblyOSZekRwqq+YGPj4+bNu2jSJFitglhQcPHqR06dJcTXqDmkqqrSxyBypXhm+/hYgIeO89kwSePg0jRkCRImZq6dKlZoaRiIjkQN7eUK8eDBoECxbA2bNm9PDTT+GJJyBfPjMFZfVqGDkSWrY0ny6Gh5s9kSZNggMH9IdERG4qICCAyMjIFO2bNm0if/78ab6fRgpF0kF8PMyZY6aWLlmS3F6+PPTuDR06mPcHIiIigEn2DhywX5e4c2fKfqGh9usSK1TQukSRdJRVc4MBAwawZs0apk2bRsmSJdm4cSMnTpygU6dOdOrUibfeeitN99NIoUg6cHGB1q3hzz9h2zZTndTLK/nrAgVgwADz919ERASLBYoWhU6d4KuvYMcOOHUKZs2Cl182VcxcXU2Fs6lTTWWzKlUgMBAaNoS33zafQl6+7OhXIpKjLF++nObNmxMaGorFYmHmzJl2161WK4MHDyZfvnx4enpSv3599uzZY9cnKiqKDh064OfnR0BAAN26dSP6xunltzF8+HDKlClDoUKFiI6OJjw8nDp16lCrVi3efPPNNL8ujRSK3CNnz8L48fD557B/v2mzWKBZM1OYpn59VS0VEZFbuHIl5brECxfs+7i4QNWq9usSg4MdE69IFpTW3GDevHmsXLmSqlWr0qZNG2bMmEGrVq1s199//31GjBjBxIkTKVKkCIMGDWLbtm3s2LEDj2sVCRs3bkxkZCRffvklcXFxdO3alerVqzN58uTbPn9iYiIjR45k9uzZxMbGUqFCBdq2bUt0dDSVK1emRIkSd/R9UFIoco8lJMC8eWZq6cKFye2lS5uppZ06ga+v4+ITEZEsIiEBtm9PThJXrICjR1P2K1XKfsppsWL6FFLkP9xNbmCxWOySQqvVSmhoKP3792fAgAEAnD9/nrx58zJhwgSefPJJdu7cSXh4OOvWraNatWoAzJ8/nyZNmhAREUHobTbCfvvttxkyZAj169fH09OTBQsW0L59e7777ru0v/jraPqoyD3m7GxGBxcsgF27TCLo45P8dYEC8L//wQ0zC0REROw5O0PFitCrF/z0Exw5AgcPwg8/mLUKSZtV795tqqF17QolSpiiNo89Bp98Ahs2pNwqQ0S4ePEiFy5csB0xMTFpvseBAwc4fvw49evXt7X5+/tTo0YNVq9eDcDq1asJCAiwJYQA9evXx8nJiTVr1tz2OSZNmsTYsWNZsGABM2fOZM6cOfz4448kJiamOd7rKSkUyUClSpkRw6NHTQG6kiXNTKCkrxs3hrlz4S7/vxYRkZzAYoHChU01s3HjzCjimTOm8tnAgWYqqZsbnDgBv/4K/fqZLTACAqBBAxg6FP74I+VWGSI5UHh4OP7+/rZjxIgRab7H8ePHAcibN69de968eW3Xjh8/Tp48eeyuu7i4EBQUZOtzK4cPH6ZJkya28/r162OxWDh27Fia47WL4a4eLSJ3xM/PrCvs1QsWLTKJ4ty5MH++OYoXN9e6dgV/f0dHKyIiWUZQkJme0qyZOb96FdavT55yunIlnDsHixebA8wIZOXK9lNOb3hTK5Ld7dixw24rB3d3dwdG89/i4+NtaxOTuLq6EhcXd1f3VVIo4kBOTqaIXMOGsG+fKUrz3Xewdy+8+CK8+aZZc9i7t9m6SkREJE08PJITPTBTUf75x34rjMOHTeK4fj2MHm36lShhnySWKKF1iZKt+fr64ufnd1f3CAkJAeDEiRPky5fP1n7ixAkqVapk63Py5Em7x8XHxxMVFWV7/K1YrVa6dOlil7RevXqV5557Du/r9j+bPn16mmLX9FGRTKJYMfjoIzO1dNw4szTk0iX44gvzdf36plJ5QoKjIxURkSzLyclsovv88/Djj3DokDkmT4YXXjD7IFosZqH7+PHQrZtZ+5A3L7RpY/5QrV0LdzkqIZIdFSlShJCQEP744w9b24ULF1izZg01a9YEoGbNmpw7d44NGzbY+vz5558kJiZSo0aN2z5H586dyZMnj91U16effprQ0FC7trRS9VGRTMpqhaVLzdTSWbOS1xmGhZm/2926mVlCIiIi6ercOVi92lQ3/esvkwTeWHTDywvuvz95JPH++1VKW7KktOYG0dHR7N27F4DKlSvz0UcfUa9ePYKCgihUqBDvv/8+7733nt2WFFu3bk2xJcWJEycYN26cbUuKatWqpWpLintFSaFIFnDokBkx/PpriIoybZ6eprZAnz7mg10REZF7IibGVC29fsrp2bP2fZycoFIl+ymn102fE8ms0pobLF26lHr16qVo79y5MxMmTMBqtfLWW2/x1Vdfce7cOR544AHGjh1LyZIlbX2joqLo3bs3c+bMwcnJibZt2/Lpp5/i4+OTrq8tLZQUimQhV66YKuRjxsDmzcntdeqY5LBVK7OPsYiIyD2TmGj2Vbo+STxwIGW/okVNcvjgg+a/pUppXaJkOsoNDCWFIlmQ1WoKyI0ZY6qMJ60zLFDALBPp3h2Cgx0bo4iI5CAREeYPU1KSuGWL+WN1vVy57EcSq1QxW2aIOJByA0NJoUgWl1SY5ssv4dQp0+buDk8+aUYPq1Z1bHwiIpIDnT8Pf/+dnCT+/bfZHuN6Hh5Qo0byaGLNmmbPJpEMpNzAUFIokk3ExMDUqWb0cN265PaaNU1y2LatPpAVEREHiY2FTZuSi9f89RecOWPfx8nJLJK/fjTxun3jRO4F5QaGkkKRbGjNGpMcTp2aXDU8JASeew569jRfi4iIOIzVCrt3269L3LcvZb+wMPsksUwZkzyKpBPlBoaSQpFs7Phx+OorM700MtK0ubrC44+b0cMaNbTmX0REMonIyOR1iStWmIpqSfsxJQkKgtq1k5PEqlXNmgmRO6TcwFBSKJIDxMbC9Olm9HDVquT2atVMctiunf6miohIJnPxYsp1iZcv2/dxd4f77ktOEmvVgoAAh4QrWZNyA0NJoUgOs3GjSQ5/+il5L+LgYOjRw0wv1f8WIiKSKcXFmdHDpCRxxYrkCmtJLBYoV85+K4yCBR0SrmQNyg0MJYUiOdT/27vvsKjOvH3g99CGIkU6IiCCoqLYEbChooNxTcyb3fSsycaYGPWNyWbflCuJutldzSa/JLtZozHN7MayMVHTFOyoiJooFkSNYC+ADaS3Ob8/nswZDgMKyHCm3J/rmks45wGeORwHbp7yvXIF+OQT4MMPxU7iAODoCNx7L/C//yt+jnJqKRERWSxJAk6eVK5LPHnStF14uHJdYmws1yWSjNlAYCgksnN1dcC334rRw4wM4/H+/cXU0ocfBtzc1OsfERFRixUWKuslHjhgLOZr4OMjppkaQuLQoaI8BtklZgOBoZCIZIcPA//6F/Dll0BlpTjm6wtMmwbMmCE2gSMiIrIaZWXAvn3GUhhZWUB5ubKNi4sIhg3XJfr6qtNf6nDMBgJDIRGZuH4d+OwzYNEi4MwZcczBAZg8WYwejh3LqaVERGSF6uqAQ4eU6xILC03bxcYqp5xGRPAHn41iNhAYComoWfX1wI8/iqmlmzcbj/fpI8Lho48CnTqp1z8iIqI7IknAqVPGgLhrl6if2FjXrsqQ2LevWIhPVo/ZQLCYVbYLFy6ERqPBnDlzbtlu9erV6NWrF1xdXdGvXz+sX7++YzpIZIccHYG77wY2bQJyc4FnnwU8PMTbM2aIn5HPPw/k5andUyIiojbQaICoKGDqVLH72vHjQFERsHYt8Mc/ioK+Tk5iR7ZVq4BZs4ABA8T00okTgb/+VSzIN6y5ILJSFjFS+NNPP+H++++Hl5cXxowZg/fff7/Jdrt378aoUaOwYMEC/OY3v8GKFSvw1ltv4cCBA+jbt2+Lvhb/GkB0Z0pKgGXLxNpDQxjUaMTPxtmzgQkTuKkbERHZkIoKsS7RMOV0925RQ7EhZ2dg8GBjKYykJMDfX53+UqswGwiqh8KysjIMGjQIH374If7yl79gwIABzYbCBx54AOXl5fjhhx/kYwkJCRgwYACWLFnSoq/HbzxR+9DrgfR0MbV0wwbj8Z49gZkzgccfB7y8VOseERGRedTVAUeOKNclXr5s2q53b+WU08hIrku0QMwGgup/z585cyYmTZqElJSU27bNysoyaafT6ZCVldXsx1RXV+PmzZvyo7TxX3aIqE0cHMTo4Pr1wC+/AM89J0Kg4e3QUDHL5vhxtXtKRETUjpycgIEDxfSY//4XuHhRrEv897+B6dPFwnsAOHYM+PhjMTU1Kkr8YLz/fuCf/xSlMurq1H0eRA2oGgpXrVqFAwcOYMGCBS1qX1BQgKCgIMWxoKAgFBQUNPsxCxYsgLe3t/zoY/iPSkTtpkcP4P33xc/FRYvEH0fLyoxvT5gAfP+9aakoIiIiq6fRiFHAxx4DPvoIOHoUuHoV+O474E9/AhITxfTSy5eB1avFX04HDxbrEnU64M03gW3bTEtlEHUg1ULh+fPn8dxzz2H58uVwNWPB0FdeeQUlJSXyIzc312xfi8jedeokNqM5elRsTnPPPeJn5aZNYsOanj2B//f/gBs31O4pERGRGfn5iTpOf/+7WINYUiI2pPnrX8U0Gy8vsS5x40bgjTdErScfH7GxzR//KDa6KSpS+1mQHVFtTeG6detw7733wrHBdr719fXQaDRwcHBAdXW14hwAhIeH44UXXlDsUDp37lysW7cOhw4datHX5bxhoo515gzw4YdiUzdDGHR3F+UsZs8Wu3oTERHZlfp68RfUhusSL1wwbdezp3HzmhEjxDRUrktsV8wGgmqhsLS0FGfPnlUce+KJJ9CrVy+89NJLTe4m+sADD6CiogLff/+9fCwpKQlxcXHcaIbIwlVUACtWiI1pDh82Hk9OFuHw7rvFMg0iIiK7dPasMSTu2gXk5Ji2CQpSbl4zYAB/eN4hZgNB9d1HG0pOTlbsPvr73/8eoaGh8prD3bt3Y/To0Vi4cCEmTZqEVatW4W9/+xtLUhBZEUkSfxD94AMxO8awzjA8XNQ+nDaNu3gTERHh+nUgK8sYEvftA2pqlG08PICEBONo4rBhYi0HtRizgWDRf1o4d+4cHBoUPEtKSsKKFSvw2muv4dVXX0WPHj2wbt26FgdCIlKfRgOMGiUe588DS5YAS5cC584Br7wCzJsHPPywGD0cOFDt3hIREanE1xeYNEk8AKCqCti/X/xlddcuIDMTKC4GtmwRDwBwdBQ/PA0jicOHA8HBqj0Fsh4WNVLYEfjXACLLU1UldvX+4APx885g+HARDv/nf8TGbURERPQrvR7IzVVOOW20NAsAEB2tnHLasyfXJTbAbCAwFBKRxZAkYM8eEQ5XrzaWcOrSBXjmGVH+qVFVGiIiIjI4f16MIBo2rzlyRPxwbSggQBkSBw6067+8MhsIDIVEZJEuXxblnpYsAQoLxTEXF1H3d/ZsID5e3f4RERFZvOJi5brEvXuB6mplGzc347rEESPE215eqnRXDcwGAkMhEVm0mhrg66/F6OGePcbj8fEiHP7ud4BWq17/iIiIrEZ1NXDggHLK6fXryjYODkD//sYyGMOHiyk7NorZQGAoJCKr8fPPIhyuWmXcgC0wEHj6aTG91IZ/ZhEREbU/vR44flwZEk+fNm3XvbtyymmvXjazLpHZQGAoJCKrU1QEfPwxsHgxcPGiOObkBNx3nxg9TEqymZ9VREREHeviReO6xF27gEOHRHhsyM9PjCAaSmEMGiTWeFghZgOBoZCIrFZtLbBunRg93LnTeHzgQBEOH3xQLJUgIiKiNrp5U6zfMGxes3cvUFmpbOPqKmokGkYSExMBb291+ttKzAYCQyER2YRDh0Q4XL5clLgAxB8yn3oKmDEDCA9Xt39EREQ2oaYGyM5WTjm9elXZRqMB4uKUU04t9PduZgOBoZCIbMq1a8CnnwIffmgs1+TgAEyZIkYPR4/m1FIiIqJ2I0nAL78oQ2Jenmm7bt2UIbF3b/EDWmXMBgJDIRHZpPp64Pvvxejh1q3G4337inD4yCOAh4d6/SMiIrJZly8r1yVmZ5uuS+zcWYRHX191+vgrZgOBoZCIbN7Ro8C//gX8+99ARYU45uMDPPkk8OyzYlM1IiIiMpPSUrEW0RASs7IAf3/jlB4VMRsIDIVEZDeKi4HPPwcWLQLy88UxjQaYNEmMHo4fz6mlREREZldbC1y4AERGqt0TZoNfqT+Rl4iog/j4AM8/L5Y+/PADoNOJpRCGt3v3FoGxtFTtnhIREdkwZ2eLCIRkxFBIRHbHwUGMDqaliZq9s2cDnp7AiRPArFlAaCjwv/8rwiMRERGRrWMoJCK7FhMD/POfolbvBx+I90tLjW+npgI//mi6Pp6IiIjIVjAUEhFBjBTOmgUcOwZs3AhMnizWF6anA7/5DdCzJ/Dee2JdIhEREZEtYShU0T/3/hOTV07Gon2LkHe9iXouRNThNBqx4cx334mdsl94QaxFzM8Xb3ftCsyYAeTmqt1TIiIiovbB3UdVNOaLMdh+Zrv8flTnKKRGp0IXpcOYyDHo5NJJvc4Rkay8HFi+XEwpzckxHh87VqxHnDwZcHRUr39ERETUNpaUDdTEUKiiI4VHsCFvA9Ly0rDr3C7U6mvlc84OzhgRPgKp0alIjU5Fv8B+0HCvfCJVSRKQkSHC4bp1xnWGERGi3uG0aarX4CUiIqJWsKRsoCaGQgtRVlOGbae3IS0vDWn5aTh145TifEinEOiidUiNSkVK9xT4ufup1FMiAoBz54DFi4GPPwauXRPHXF2BRx4Ro4f9+6vbPyIiIro9S80GHY2h0ELlXc8TATEvDdvObENFbYV8TgMN4kPj5amm8aHxcHTg3DUiNVRWAqtWidHD7Gzj8ZEjRTicMkWUYyIiIiLLYy3ZwNwYCq1AdV01dp3bhfT8dKTlpeFI0RHF+c6unTE+ajx0UTroonQI9QpVqadE9kuSgN27RTj85hugrk4cDw0VG9NMnw4EBKjbRyIiIlKyxmxgDgyFVujizYvYmL8Raflp2JS/CTeqbijO9wvsB12UDqnRqRgRPgJaJ61KPSWyTxcvAh99JB5FReKYiwvw4INi9HDIEHX7R0RERIItZIP2wFBo5er19fjp0k/yVNN9F/dBgvFb6u7sjjHdxsgb1kT7RqvYWyL7Ul0NrF4tRg/37TMeT0gQ4fC3vxVhkYiIiNRha9mgrRgKbcy1imvYfGoz0vLTkJ6XjstllxXnu3fujtQoERBZ9oKo4+zbJ8Lhf/8L1P660XBwMPD00+IREqJu/4iIiOyRrWeDlmIotGGSJOFI0RGk5aUhPT8dO8/ubLbshS5Kh7igOJa9IDKzwkJg6VJgyRLg0iVxzNlZjBrOni1GEfnfkIiIqGPYUza4FYZCO2Ioe2HYsCb/Rr7ifEinEEyImoDU6FSM7z6eZS+IzKi2FlizRoweZmYajw8eLMLhAw+IEhdERERkPq3NBt26dcPZs2dNjj/77LNYtGgRkpOTkZGRoTj39NNPY8mSJe3WZ3NgKLRjedfzkJ6XjrT8NGw9vdWk7MXQ0KHyVNOhoUPh5OCkYm+JbFd2tgiHK1aIdYgA4O8vdiydMQOw85cqIiIis2ltNrhy5Qrq6+vl93NycjB+/Hhs27YNycnJSE5ORs+ePfHnP/9ZbuPu7g4vLy+z9L+9MBQSAFH2IvN8prxhTeOyFz6uPhjffbw81ZRlL4ja39WrwCefAB9+CJw/L445OgL33itGD0eO5NRSIiKi9mTIBrm5uQgNNf5+q9VqodXefgf/OXPm4IcffsDJkyeh0WiQnJyMAQMG4P333zdjr9sfQyE16XZlL/oG9kVqVCp00TqMDB/JshdE7aiuDvjuOzF6uH278XhcnAiHDz8MuLur1j0iIiKbYcgGjc2dOxfz5s275cfW1NSgS5cueOGFF/Dqq68CAJKTk3H06FFIkoTg4GBMnjwZr7/+Otwt/Ac3QyHdVsOyF+n56dh3cR/0kl4+byh7YaiNGO0bzQ1riNrJkSPAv/4FfPklUPHrDO/OnYFp04BnnwW6dVO1e0RERFbtTkYKv/rqKzz88MM4d+4cunTpAgBYunQpIiIi0KVLFxw+fBgvvfQS4uPjsWbNGrM+jzvFUEitdr3yuih78etU06bKXhgC4phuY+Cp9VSpp0S248YN4LPPgEWLgNOnxTGNBrj7bjF6OHYsp5YSERG11p1kA51OBxcXF3z//ffNttm6dSvGjRuHvLw8REVF3Wl3zYahkO6IJEnIKcoRATE/rcmyF8PDh8sb1rDsBdGdqa8H1q8XU0s3bTIe79MHmDULeOwxoBPLjxIREbVIW7PB2bNn0b17d6xZswb33HNPs+3Ky8vRqVMnpKWlQafTtUeXzYKhkNpVWU0Ztp/ZLk81zbuepzgf3CkYuigddFE6jI8aD393f5V6SmT9jh8XI4fLlgFlZeKYtzfwxBPAzJlAdLSq3SMiIrJ4bc0G8+bNw0cffYTz58/Dyan5HfozMzMxYsQIHDp0CHFxce3RZbNgKCSzMpS9SM9Px9bTW1FeWy6fM5S9MEw1jQ+NZ9kLoja4eRP44gux9vCXX4zHJ04UU0t1OsDBQb3+ERERWaq2ZAO9Xo/IyEg89NBDWLhwoXw8Pz8fK1aswF133QU/Pz8cPnwYzz//PLp27WpSu9DSMBRShzGUvTDURjxceFhx3sfVByndU+RdTbt68ftD1Bp6PbBxo5haumEDYHh179FDTC19/HHAwsskERERdai2ZIONGzdCp9PhxIkT6Nmzp3z8/PnzePTRR5GTk4Py8nKEhYXh3nvvxWuvvcY6hZaGodByXCq9JMpe5KVh06lNuF55XXE+NiAWqdFiLeKI8BFwdXJVqadE1icvT9Q7/OwzoKREHOvUCZg6VUwt7d1b3f4RERFZAmYDgaGQLEK9vh4/X/pZ3rCmcdkLNyc3jIkcI48i9vDtwQ1riFqgrEyUs/jgAyA313g8JUVMLZ00CXB0VK9/REREamI2EBgKySIZyl4YpppeKr2kOB/pE4nU6FToonQYGzmWZS+IbkOSgG3bRDj87jsx1RQAIiNFvcMnnxT1D4mIiOwJs4HAUEgWz1D2Ij0/HWl5adh5bidq6mvk804OThgRPkLesKZ/UH+OIhLdwpkzwOLFwCefANd/nbXt5gY8+qgYPezXT9XuERERdRhmA4GhkKyOoeyFYRSxcdmLII8g6KJ1SI1KZdkLoluoqABWrhSjh4cOGY+PHi3C4T33ALfYZZuIiMjqMRsIDIVk9fKv58ujiE2VvRjSZYg81XRY12Ese0HUiCQBu3aJcLhmDVBfL46HhQEzZgBPPQX4828rRERkg5gNBIZCsik19TXIPJeJtLw0pOen41DhIcV5b603xkeNhy5KB12UDmHeYSr1lMgyXbgALFkCLF0KXLkijmm1wEMPidHDQYPU7R8REVF7YjYQGArJphnKXqTnp2Nj/sYmy14Y1iKOjBjJshdEv6qqAr76Sowe/vyz8XhSkgiH990HODur1z8iIqL2wGwgMBSS3TCUvTBMNd17ca9J2YvkbslybUSWvSASU0v37hXhcPVqoLZWHA8JAZ55Bnj6aSAoSN0+EhERtRWzgcBQSHbreuV1bDm1Ra6N2LjsRTefbkiNEgGRZS+IgIIC4KOPxPTSggJxzNkZuP9+MXo4bJi6/SMiImotZgOBoZAIouzF0StH5bWIO87uMCl7MTxsuLxhTf/g/nDQOKjYYyL11NQA33wjRg+zsozHhw4V4fD++8U6RCIiIkvHbCAwFBI1obymXJS9+HWq6cnrJxXngzyCMCFqAlKjUzG++3gEeASo1FMide3fL8LhqlVAdbU4FhgITJ8uppeGhqrbPyIiolthNhAYCola4NSNU3JdxC2ntpiUvRjcZbA81ZRlL8geXbkCfPwxsHix2MEUEDUO/+d/xOjh8OEAl+gSEZGlYTYQGAqJWqmmvga7z+8WaxHz0pose5HSPUWeasqyF2RP6uqAdevE6OGOHcbjAwaIcPjQQ4Cbm1q9IyIiUmI2EBgKie7Q5dLL2Ji/EWn5adiUvwnXKq8pzvcJ6IPUqFToonUYFTGKZS/Ibhw+LMLh8uVAZaU45ucHTJsGPPssEB6ubv+IiIiYDQSGQqJ2VK+vx/7L++UNa/Zc2NNk2QtDbcSefj1Z9oJs3vXrwKefAh9+CJw5I445OAD33CNGD5OTObWUiIjUwWwgMBQSmdGNyhvYfGqzvGHNxdKLivPdfLrJAXFs5Fh4ab1U6imR+dXXAz/8APzrX8DmzcbjffsCs2YBjz4KeHio1z8iIrI/zAYCQyFRBzGUvTBsWNNU2YuksCR5wxqWvSBbduyYCIdffAGU/7pvk48P8Ic/ADNnAt27q9o9IiKyE8wGAkMhkUrKa8qRcTZD3rCmcdmLQI9AeRSRZS/IVpWUAJ9/DixaBOTliWMaDTBpkphampIippoSERGZA7OBwFBIZCEalr3YenorymrK5HMNy17oonVI6JrAshdkU/R6IC1NjB5u2GA8HhMjppZOnQp4eqrXPyIisk3MBgJDIZEFMpS9MITEgwUHFecNZS90UTroonUI9+Y2jmQ7Tp4UI4effw7cvCmOeXoCjz8uAmLPnqp2j4iIbAizgcBQSGQFCsoKRNmLvDRszN9oUvait39vpEaLtYgjw0fCzZmF4Mj6lZYC//mPKGtx/LjxuE4nppZOnMippUREdGeYDQSGQiIrU6+vx4HLB8RaxPw0k7IXrk6uSO6WLE81jfGLYdkLsmqSBGzZIsLh99+L9wEgKkpsSvPEE2KTGiIiotZiNhAYComs3I3KG9hyeotcG/HCzQuK8xHeEUiNToUuSodx3cex7AVZtdOnRb3DTz4BiovFMXd34Pe/F1NLY2NV7R4REVkZZgOBoZDIhkiShNwruXJAzDib0WTZC8OupgOCB7DsBVmligpg+XIxenjkiPH4mDFiaunddwOOjur1j4iIrAOzgcBQSGTDDGUvDBvW/HLtF8X5QI9ATIiagNSoVEyImsCyF2R1JAnYsUOEw3XrgPp6cTw8HHj2WWDaNMDPT9UuEhGRBWM2EBgKiezI6RunkZ6fjrS8NGw5vcWk7MWgkEHyVNOErglwdnRWsbdErXP+PLB4MbB0KXDt172YXF2Bhx8Wo4cDBqjaPSIiskDMBgJDIZGdqqmvQdb5LHmqaXZBtuK8l9YLKd1T5A1rWPaCrEVVFbBqlRg9PHDAeHzECBEO770XcObfO4iICMwGBgyFRATAWPYiPT8d6XnpTZa9MKxFHBUximUvyOJJEpCVJcLh118DdXXieGgo8MwzwPTpQGCgun0kIiJ1MRsIDIVEZMJQ9sIw1TTrQpZJ2YvREaPl2ogse0GW7tIl4KOPxKOwUBxzcQFGjRIjiCNGAMOGAZ06qdtPIiLqWMwGAkMhEd1WcVUxtpzaItdGbFz2Itw7HKlRIiCOjRwLb1dvlXpKdGvV1WLU8IMPgL17leccHYGBA40hcfhwIDhYnX4SEVHHYDYQGAqJqFUkScKxq8dEQMxLw46zO1BdXy2fd9Q4IiksSd6wZmDIQJa9IIt09KjYuXTXLvE4d860TXS0MSSOGAH07AlwUJyIyHYwGwgMhUR0RypqK5BxJkPesObEtROK8wHuAaLsRbQoexHowUVcZJnOnQMyM40h8cgRsS6xIX9/ZUgcOFBMQyUiIuvEbCAwFBJRuzKUvUjPT8fmU5sVZS8AiLIXv041ZdkLsmTFxWKjGkNI3LtXTD9tyM1NrEU0hMTERMDLS5XuEhFRGzAbCAyFRGQ2hrIXhg1rmip7MS5ynDzVNMInQqWeEt1edbUocWEIibt2AdevK9s4OABxccrRxNBQdfpLRES3x2wgMBQSUYcpLCvExvyNSMtPw8b8jbhacVVxvpd/L7ku4uiI0Sx7QRZNrwdOnFCGxFOnTNt166YMib17i/BIRETqYzYQGAqJSBV6SY8Dlw/IG9bsubAH9VK9fN5Q9sJQG7GXfy+WvSCLd+mScl3iwYMiPDbUubPY2dQQEocMAbRaVbpLRGT3mA0EhkIisgiGsheGqabnb55XnA/3DpcD4rjIcSx7QVahtBTYs8cYEvfsASoqlG20WmDoUGNITEoSwZGIiMyP2UBgKCQii2Moe5Gel460/DRknMkwKXuRGJYob1jDshdkLWprxehhwymnRUWm7fr2VU45jeByWyIis2A2EBgKicjiVdRWYMfZHfJUU5a9IFshSUBenjIk/vKLabuwMGVIjI0FHB07vr9ERLaG2UBgKCQiq3Om+Iw8irjl1BaU1pQqzhvKXuiidUjsmsiyF2RVioqU6xIPHADq6pRtvL3FNFNDSBw6VJTHICKi1mE2EBgKiciq1dbXIutCFtLy0pCen44Dlw8oznu6eCKlewp0UTroonXo5tNNnY4StVF5ObBvnzEk7t4NlCnLf8LZWWxY03Bdor+/Ov0lIrImzAYCQyER2RRD2Yv0/HSk56eblL2I8YtBarRYi8iyF2SN6uqAI0eMIXHnTuDyZdN2vXsrp5xGRgLcwJeISInZQGAoJCKbpZf0yL6cLdYi5qch63yWouyF1lGL0d1Gy1NNe/v3ZtkLsjqSBJw5o1yXmJtr2i4kRBkS4+IAJ6cO7y4RkUVhNhAYConIbhRXFWPr6a3yhjWNy16EeYUhNToVuigdxnUfBx9XH3U6SnSHrl0T00wNIfGnn8TOpw116gQkJhpD4rBhgIeHOv0lIlILs4HAUEhEdkmSJBy/elweRWyu7IWhNuKgkEEse0FWq7IS+PlnY0jMzARKSpRtHB2BQYOMIXH4cCAoSJ3+EhF1FGYDgaGQiAjGsheGXU2PXz2uOO/v7i/KXkSJshdBnfjbMlkvvR44elS5LvH8edN2PXoop5z26MF1iURkW5gNBIZCIqImnC0+i/T8dKTlpWHzqc0mZS8GBg+Up5omhSWx7AVZvXPnlOsSc3LEesWGAgKUIXHgQLHzKRGRtWI2EBgKiYhuo7a+Fnsu7JGnmjZV9mJc93HyhjUse0G24MYNICvLGBL37QOqq5Vt3NyAhARjSExIALy81OkvEVFbMBsIDIVERK1UWFaITac2IS0vDRvzN+JKxRXFeUPZC12UDqO7jYa7s7tKPSVqP9XVwP79ynWJ168r2zg4AP37K0cTu3RRp79ERC3R2mwwb948zJ8/X3EsJiYGx4+LZSdVVVX44x//iFWrVqG6uho6nQ4ffvghgix8kTZDIRHRHWhY9iI9Px27z+82KXsxKmKUXBuRZS/IVuj1wPHjyimnp0+btouMVIbEXr1EeCQisgRtCYVff/01Nm/eLB9zcnKCv78/AGDGjBn48ccfsWzZMnh7e2PWrFlwcHBAZmam2Z5De2AoJCJqRyVVJdhyeou8Yc25knOK8129uiI1SgRElr0gW3PxohhBNITEQ4dEeGzI11fsbGoIiYMHA1qtOv0lIjJkg9zcXISGhsrHtVottE28OM2bNw/r1q3DwYMHTc6VlJQgICAAK1aswG9/+1sAwPHjx9G7d29kZWUhISHBbM/jTjEUEhGZiaHshWHDmoyzGaiqq5LPO2ockdA1QZ5qOrjLYJa9IJty8yawZ48xJO7ZI8pjNKTVAvHxxpCYlAT4+KjSXSKyQ4Zs0NjcuXMxb948k+Pz5s3D22+/DW9vb7i6uiIxMRELFixAeHg4tm7dinHjxuHGjRvwafBCFhERgTlz5uD555834zO5MwyFREQdpLK2EjvO7pCnmh67ekxx3lD2Qhelw4SoCQjuFKxST4nMo7YWyM5WTjm9olySC40G6NtXOeU0PFyd/hKR7WvtSOGGDRtQVlaGmJgYXL58GfPnz8fFixeRk5OD77//Hk888QSqG+3KFR8fjzFjxuCtt94y+/NpK4ZCIiKVGMpepOenY/OpzbhZfVNxfkDwAHmqaWJYIlwcXVTqKZF5SBJw8qQyJJ48adouLEwZEmNjAUfHju8vEdmeO80GxcXFiIiIwLvvvgs3NzeGQmvBUEhElshQ9sIw1XT/5f2K854unhgbOVaeahrZOVKlnhKZV2Ghcl3igQNAfb2yjbe3mGZqCIlDh4ryGERErdUe2WDo0KFISUnB+PHjOX20LRYvXozFixfjzJkzAIDY2Fi88cYbmDhxYpPtly1bhieeeEJxTKvVoqqqqsn2TWEoJCJrUFRehE35m5CWn4b0vHSTshc9/XrKo4gse0G2rLwc2LvXGBKzsoCyMmUbZ2dgyBBjSBw+HPDzU6e/RGRd7jQblJWVITw8HPPmzcPUqVMREBCAlStX4r777gMAnDhxAr169eJGM7fy/fffw9HRET169IAkSfjiiy/w9ttvIzs7G7GxsSbtly1bhueeew4nTpyQj2k0mlbV/WAoJCJro5f0OFhwEGl5aUjLS2u27IUuSofU6FT0CejDshdks+rqgMOHjSFx506goMC0Xe/eyimnkZFivSIRUUOtzQYvvvgiJk+ejIiICFy6dAlz587FwYMHkZubi4CAAMyYMQPr16/HsmXL4OXlhdmzZwMAdu/ebe6nckcsbvqor68v3n77bTz55JMm55YtW4Y5c+aguLi4zZ+foZCIrF1JVQm2nt4qQmIzZS8MATGlewrLXpBNkyRRH7HhusRjx0zbhYQoQ2JcHODk1PH9JSLL0tps8OCDD2LHjh24du0aAgICMGLECPz1r39FVFQUAGPx+pUrVyqK1wcHW/bmcRYTCuvr67F69WpMnToV2dnZ6NOnj0mbZcuWYdq0aQgNDYVer8egQYPwt7/9rclRRYPq6mrFYs+LFy+iT58+DIVEZBMkScKJayfkHU23n9luUvZiWNdh8lRTlr0ge3D1KrB7tzEk/vyz2Pm0IU9PIDHRGBLj4wEPD3X6S0Tq4YCRoHooPHLkCBITE1FVVYVOnTphxYoVuOuuu5psm5WVhZMnTyIuLg4lJSV45513sGPHDhw9erTZb+K8efMwf/58k+P2/o0nIttkKHth2LCmcdkLPzc/TIiagNToVJa9ILtRWQn89JMxJGZmihqKDTk5AYMGKdclBgaq018i6jgMhYLqobCmpgbnzp1DSUkJvv76a3zyySfIyMhocqSwsdraWvTu3RsPPfQQ3nzzzSbbcKSQiOzZuZJzSM9LR1p+2i3LXuiidUgKS2LZC7IL9fXA0aPKdYkXLpi269lTOeU0OprrEolsDUOhoHoobCwlJQVRUVH46KOPWtT+d7/7HZycnLBy5coWtec3nojsVW19LfZe3CtPNf350s+K851cOmFc5Dh5PSLLXpA9OXdOuS4xJ0esV2woMFAZEgcMEDufEpH1YjYQLC4Ujh07FuHh4Vi2bNlt29bX1yM2NhZ33XUX3n333RZ9fn7jiYgEQ9mL9Px0pOeno6i8SHG+h28PpEb/WvYiYjQ8XLjgiuzHjRui/IUhJO7bBzSqRw13dyAhwRgSExLEWkUish7MBoKqofCVV17BxIkTER4ejtLSUqxYsQJvvfUW0tPTMX78ePz+979HaGgoFixYAAD485//jISEBERHR6O4uBhvv/021q1bh/3797douinAbzwRUVMMZS8MU013n9+NOn2dfN7F0QWjIkbJU01jA2JZ9oLsSnU1sH+/cjTxxg1lGwcHMXrYcF1ily6qdJeIWojZQFA1FD755JPYsmULLl++DG9vb8TFxeGll17C+PHjAQDJycno1q2bPGr4/PPPY82aNSgoKEDnzp0xePBg/OUvf8HAgQNb/DX5jSciur2b1TeNZS/y0nC25KzifKhnKFKjU6GL0iGlewo6u3VWqadE6tDrgePHlSHx9GnTdt27K6ec9urFdYlEloTZQLC46aPmxm88EVHrSJKEX679ItdFbFz2wkHjgISuCfJaxMEhg+Ho4Khij4nUcfGi2NnUEBIPHRLhsSE/PzGCaAiJgwYBWq06/SUiZgMDhkIiImqVytpK7Dy3U96wJvdKruK8n5sfxkeNR2qUKHsR4hmiUk+J1HXzJrBnjzEk7tkjymM05OoqaiQaQmJiIuDjo0p3iewSs4HAUEhERHfkfMl5uS7iplObTMpe9A/qL29Yw7IXZM9qa4HsbOWU0ytXlG00GqBfP+WU07AwdfpLZA+YDQSGQiIiajeGsheGDWv2X9oPCcYfM51cOmFs5Fh5w5runbur2FsidUkScPKkMiSePGnaLjxcGRJjY8WmNkR055gNBIZCIiIymyvlV7Dp1CZ5qmlzZS90UTokd0tm2Quye4WFYl3izp0iJGZnA/X1yjY+PkBSkjEkDh0qpqESUesxGwgMhURE1CH0kh6HCg7JATHzfKZJ2YuR4SPlqaYse0EElJUBe/caRxKzsoDycmUbFxdgyBBjSExKEhvaENHtMRsIDIVERKQKQ9kLw1TTM8VnFOdDPUPlHU1Z9oJIqKsTu5o2nHJaUGDark8f5ZTTbt1YCoOoKcwGAkMhERGpzlD2wrBhzfYz21FZZ9ym0UHjgGGhw+SppkO6DGHZCyKIdYmnTilD4vHjpu26dFGGxLg4wJH/hYiYDX7FUEhERBanqq4KO8/ulGsjNi574evmiwlRE6CL0kEXpWPZC6IGrlwBdu82hsT9+8XOpw15eoryF4aQOGwY4O6uTn+J1MRsIDAUEhGRxWtY9mLzqc0oqS5RnO8f1F+eajo8fDjLXhA1UFEB/PSTMSTu3i1qKDbk5AQMGmQMicOHA4GB6vSXqCMxGwgMhUREZFXq9HXYe2GvvGHNz5d+VpS98HD2EGUvfp1qGuUbpWJviSxPfT2Qk2MMiTt3Ahcvmrbr2VM55TQ6musSyfYwGwgMhUREZNWuVlzFpvxNSMtPQ3peOgrLCxXno32jkRoldjRl2QsiU5IEnDunXJeYk2PaLjBQGRIHDACcnTu8u0TtitlAYCgkIiKboZf0OFx4WKxFzEtrtuyFLkoHXbQOMX4x0DppVewxkWW6cUO5LnHfPqCmRtnG3R1ISBABceRIsS7R01Od/hK1FbOBwFBIREQ262b1TWw7vU3esKZx2QsA8NZ6I9AjsMlHgHuA4n1fN1/uekp2qapKbFhjCImZmSI4NuToKEYPG65LDOEeUGThmA0EhkIiIrILkiTh5PWT8lrE7We2o6K2olWfw0HjAH93f2V4dG8mUHoEwNPFExouwiIbpNcDx44pp5yeOWPaLipKOeU0JobrEsmyMBsIDIVERGSXJElCcVUxisqLmn5UiH+vlF9BUXkRrlVea/XX0Dpqmx2FbGpUklNZyZpduCBGEA0h8dAhsV6xIT8/ZUgcNAhw4WbBpCJmA4GhkIiIqAVq62txrfJa8yGy0aO8trzVX8MwlTXAI+CWo5CcykrWoKQE2LPHGBL37gUqK5VtXF3FWkRDSExMBLy91ekv2SdmA4GhkIiIyAwqaivkUcbmRiEbPhpuiNMSzU1llQNlowenspLaamqA7GzllNOrV5VtNBogLk45mshf18icmA0EhkIiIiKVNTWV9UpFM4HSTFNZG26qE+ARAFcnVzM8UyIjSQJ++UUZEvPyTNtFRChDYp8+gINDx/eXbBOzgcBQSEREZGXq9HW4WnG12dDYOFCW1ZS1+mt4ab1atKEOp7JSeyooUK5LzM4G6uuVbXx8xM6mhpA4ZIiYhkrUFswGAkMhERGRjWvNVNYr5VdQq69t1ed30DjAz82vxZvqcCortVRZmViLaAiJWVlAeaPlui4uwNChxpCYlAT4+qrTX7I+zAYCQyERERHJJElCSXVJizfUudOprLfbVIdTWamhujqxq6khJO7cCRQWmraLjVVOOY2IYCkMahqzgcBQSERERG3WcCprk6ORjUYi23Mqa1Ob6vi5+XEqqx2RJODUKeW6xOPHTduFhipDYr9+gCNvEwKzgQFDIREREXWY5qayNrexTmunsmqgMd2V9RYb63hpvTiV1cZcuQLs3m0MiT//LEYYG/L0FNNMDSExPh5wd1env6QuZgOBoZCIiIgsUkunshoC5bWKa5DQul9rXBxdTEMjp7LalIoK4KefjCFx927g5k1lGycnYPBgY0gcPhwICFCnv9SxmA0EhkIiIiKyCXX6OlyruNZ8gGynqawNy3fc6sGprJapvh7IyVGuS7x40bRdTIxyymlUFNcl2iJmA4GhkIiIiOxSZW3lLetBmmMq660CJaeyqkOSgHPnlOsSc3JM2wUFKUPigAFihJGsG7OBwFBIREREdBuNp7KarItsNAppjqmsjTfW4VRW87l+XZS/MITEffuAmhplGw8PICHBGBITEoBOndTpL7Uds4HAUEhERETUzm41lbWp0cnSmtJWfw1PF88W14bkVNY7U1UlNqwxhMTMTKC4WNnG0VGMHjYcTQwOVqO31BrMBgJDIREREZHKWjKVteH5mvqa23/SBjTQwM/dr0Ub6nAq6+3p9UBurnLK6dmzpu2iopQhMSaG6xItDbOBwFBIREREZEUkScLN6pst3lDnTqey3m5jnQD3ALg5u5np2VqP8+fFCKIhJB4+LNYrNuTvL3Y2NYTEQYMAFxd1+ksCs4HAUEhERERkw+r0dbheeb3FG+q051TWpgKln7sfnBxsf4eWkhLlusS9e8U01IZcXYFhw4whMTER8PZWp7/2itlAYCgkIiIiIlnjqayKTXUqTEOkuaayGjbW8dZ628RU1poa4MAB5ZTTa9eUbTQaIC4OGDnSWC+Rv66aF7OBwFBIRERERG1yu6msjddJXq242uqprM4Ozi3eUMeaprJKEnDihDIk5uebtuvWTTnltE8fwMGhw7trs5gNBIZCIiIiIuoQ9fp6XKtselfWpgLlzeqbrf4ani6eyvIdt9hQx9Kmsl6+rFyXmJ0tNrVpyMdHGRKHDBHTUKltmA0EhkIiIiIiskhVdVWmNSHNPJX1VhvrdPRU1tJSsRbREBKzsoCKCmUbFxdg6FBjSExKAnx9O6yLVo/ZQGAoJCIiIiKr13Aq6+3Ke5hrKmvjQNneU1lra4FDh5RTTgsLTdv17asshREezlIYzWE2EBgKiYiIiMjuNDeVVR6ZbDQS2ZaprJ1cOrW4NmRbprJKkliH2DAknjhh2q5rV2VI7NsXcHRs9dOxScwGAkMhEREREdFt3G4qa8NzheWFbZrK6uvm2+JNdZqbynrlinJd4v79QF2dso2Xl5hmagiJQ4cC7u53cnWsF7OBwFBIRERERNSOJElCaU1pi2tDXqu8Br2kv/0nbqDhVFZ5Y50mRiI9HQJxNjcQP2W5YdcuYPdusVZR8bmcgcGDjSFx+HDA378dL4gFYzYQGAqJiIiIiFRUr6/H9crrzQfHdpzKGuAeCNf6QNTcCETxxQBc/CUQNy8HAuUNHhX+6NXTSTHltHt321yXyGwgWM4evEREREREdsjRwREBHgEI8AhALGJv277hVNaWbKpTXV+NspoylNWU4dSNU8ZP5P/rownHK/xwvDwQn2wPBH4MhLsUiG4BgYjtFoihfQIxtE8AQrzEaKSPq0+H7spK7Y+hkIiIiIjIirg6uSLMOwxh3mG3bXurqaxXyq+YjEJerbgqprK6XxOPgGMAgAoAuQByK4HV+wHsN34NJ40zAjwCENTp9pvqBHgEwN3ZehcwLliwAGvWrMHx48fh5uaGpKQkvPXWW4iJiZHbJCcnIyMjQ/FxTz/9NJYsWdLR3W0xhkIiIiIiIhul0WjgpfWCl9YL0b7Rt23f1FTWiyVFOJxXhGPninD2WhGuVhahXnsF8CgCXEtQJ9XictklXC671KI+eTh7INAjEL/M/qXVO66qLSMjAzNnzsTQoUNRV1eHV199FRMmTEBubi48PDzkdk899RT+/Oc/y++7W/hOPtb1XSAiIiIiIrNpdirrcOObej2Qmyt2N83IrMbO/VdwsbhIhMQGD8/gIniFFMHJuwg1zkW4Xi2mspbXluN65XWLCoSlpaW4edO4VlOr1UKr1Zq0S0tLU7y/bNkyBAYGYv/+/Rg1apR83N3dHcHBwebrcDuznO8EERERERFZPAcHUeuwb1/gmWe0ALri/PmuilIYh7OAUglouNGpn7+ElFFl6JdQhF79S1BXBzhZSBrp06eP4v25c+di3rx5t/24kpISAICvr6/i+PLly/Hll18iODgYkydPxuuvv27Ro4XcfZSIiIiIiNpVcTGwZ48xJO7dC1RVGc9rNMCNG4C3t2pdBGDMBrm5uQgNDZWPNzdS2JBer8fdd9+N4uJi7Nq1Sz6+dOlSREREoEuXLjh8+DBeeuklxMfHY82aNWZ7HnfKQrI5ERERERHZCh8fIDVVPACgpgY4cMAYEktL1Q+EDXl6esLLy6tVHzNz5kzk5OQoAiEATJ8+XX67X79+CAkJwbhx45Cfn4+oqKh26W97YygkIiIiIiKzcnEBEhLE48UX1e7NnZs1axZ++OEH7Nix47azD4cNGwYAyMvLYygkIiIiIiKyZpIkYfbs2Vi7di22b9+OyMjI237MwYMHAQAhISFm7l3bMRQSERERERG1wMyZM7FixQp8++238PT0REFBAQDA29sbbm5uyM/Px4oVK3DXXXfBz88Phw8fxvPPP49Ro0YhLi5O5d43j6GQiIiIiIioBRYvXgxAFKhv6PPPP8fjjz8OFxcXbN68Ge+//z7Ky8sRFhaG++67D6+99poKvW05hkIiIiIiIqIWuF3hhrCwMGRkZHRQb9qPg9odICIiIiIiIvUwFBIREREREdkxhkIiIiIiIiI7xlBIRERERERkxxgKiYiIiIiI7BhDIRERERERkR1jKCQiIiIiIrJjDIVERERERER2jKGQiIiIiIjIjjEUEhERERER2TGGQiIiIiIiIjvGUEhERERERGTHGAqJiIiIiIjsGEMhERERERGRHXNSuwMdTa/XAwAuX76sck+IiIiIiEhNhkxgyAj2yu5CYWFhIQAgPj5e5Z4QEREREZElKCwsRHh4uNrdUI1GkiRJ7U50pLq6OmRnZyMoKAgODurOni0tLUWfPn2Qm5sLT09PVftii3h9zY/X2Lx4fc2L19e8eH3Ni9fXvHh9zcuSrq9er0dhYSEGDhwIJye7Gy+T2V0otCQ3b96Et7c3SkpK4OXlpXZ3bA6vr/nxGpsXr6958fqaF6+vefH6mhevr3nx+loebjRDRERERERkxxgKiYiIiIiI7BhDoYq0Wi3mzp0LrVardldsEq+v+fEamxevr3nx+poXr6958fqaF6+vefH6Wh6uKSQiIiIiIrJjHCkkIiIiIiKyYwyFREREREREdoyhkIiIiIiIyI4xFBIREREREdkxhsJ2tGPHDkyePBldunSBRqPBunXrbvsx27dvx6BBg6DVahEdHY1ly5aZtFm0aBG6desGV1dXDBs2DPv27Wv/zluB1l7fNWvWYPz48QgICICXlxcSExORnp6uaDNv3jxoNBrFo1evXmZ8Fpartdd3+/btJtdOo9GgoKBA0Y73r9Da6/v44483eX1jY2PlNrx/hQULFmDo0KHw9PREYGAgpkyZghMnTtz241avXo1evXrB1dUV/fr1w/r16xXnJUnCG2+8gZCQELi5uSElJQUnT54019OwWG25vh9//DFGjhyJzp07o3PnzkhJSTH5v9/UPZ6ammrOp2KR2nJ9ly1bZnLtXF1dFW14/xq15RonJyc3+Ro8adIkuQ3vYWHx4sWIi4uDl5eX/PvWhg0bbvkxfP21PAyF7ai8vBz9+/fHokWLWtT+9OnTmDRpEsaMGYODBw9izpw5mDZtmiK4/Pe//8ULL7yAuXPn4sCBA+jfvz90Oh2KiorM9TQsVmuv744dOzB+/HisX78e+/fvx5gxYzB58mRkZ2cr2sXGxuLy5cvyY9euXebovsVr7fU1OHHihOL6BQYGyud4/xq19vr+4x//UFzX8+fPw9fXF7/73e8U7Xj/AhkZGZg5cyb27NmDTZs2oba2FhMmTEB5eXmzH7N792489NBDePLJJ5GdnY0pU6ZgypQpyMnJkdv8/e9/xz//+U8sWbIEe/fuhYeHB3Q6HaqqqjriaVmMtlzf7du346GHHsK2bduQlZWFsLAwTJgwARcvXlS0S01NVdy/K1euNPfTsThtub4A4OXlpbh2Z8+eVZzn/WvUlmu8Zs0axfXNycmBo6OjyWsw72Gga9euWLhwIfbv34+ff/4ZY8eOxT333IOjR4822Z6vvxZKIrMAIK1du/aWbf7v//5Pio2NVRx74IEHJJ1OJ78fHx8vzZw5U36/vr5e6tKli7RgwYJ27a+1acn1bUqfPn2k+fPny+/PnTtX6t+/f/t1zEa05Ppu27ZNAiDduHGj2Ta8f5vWlvt37dq1kkajkc6cOSMf4/3btKKiIgmAlJGR0Wyb+++/X5o0aZLi2LBhw6Snn35akiRJ0uv1UnBwsPT222/L54uLiyWtViutXLnSPB23Ei25vo3V1dVJnp6e0hdffCEfmzp1qnTPPfeYoYfWrSXX9/PPP5e8vb2bPc/799bacg+/9957kqenp1RWViYf4z3cvM6dO0uffPJJk+f4+muZOFKooqysLKSkpCiO6XQ6ZGVlAQBqamqwf/9+RRsHBwekpKTIbajl9Ho9SktL4evrqzh+8uRJdOnSBd27d8cjjzyCc+fOqdRD6zRgwACEhIRg/PjxyMzMlI/z/m1fn376KVJSUhAREaE4zvvXVElJCQCY/F9v6Havv6dPn0ZBQYGijbe3N4YNG2b3929Lrm9jFRUVqK2tNfmY7du3IzAwEDExMZgxYwauXbvWrn21Ri29vmVlZYiIiEBYWJjJqAzv31tryz386aef4sEHH4SHh4fiOO9hpfr6eqxatQrl5eVITExssg1ffy0TQ6GKCgoKEBQUpDgWFBSEmzdvorKyElevXkV9fX2TbRqv26Lbe+edd1BWVob7779fPjZs2DAsW7YMaWlpWLx4MU6fPo2RI0eitLRUxZ5ah5CQECxZsgTffPMNvvnmG4SFhSE5ORkHDhwAAN6/7ejSpUvYsGEDpk2bpjjO+9eUXq/HnDlzMHz4cPTt27fZds29/hruTcO/vH+VWnp9G3vppZfQpUsXxS95qamp+Pe//40tW7bgrbfeQkZGBiZOnIj6+npzdN0qtPT6xsTE4LPPPsO3336LL7/8Enq9HklJSbhw4QIA3r+30pZ7eN++fcjJyTF5DeY9bHTkyBF06tQJWq0WzzzzDNauXYs+ffo02Zavv5bJSe0OEHWEFStWYP78+fj2228Va94mTpwovx0XF4dhw4YhIiICX331FZ588kk1umo1YmJiEBMTI7+flJSE/Px8vPfee/jPf/6jYs9szxdffAEfHx9MmTJFcZz3r6mZM2ciJyfHLtdWdoS2XN+FCxdi1apV2L59u2IzlAcffFB+u1+/foiLi0NUVBS2b9+OcePGtWu/rUVLr29iYqJiFCYpKQm9e/fGRx99hDfffNPc3bRqbbmHP/30U/Tr1w/x8fGK47yHjWJiYnDw4EGUlJTg66+/xtSpU5GRkdFsMCTLw5FCFQUHB6OwsFBxrLCwEF5eXnBzc4O/vz8cHR2bbBMcHNyRXbVqq1atwrRp0/DVV1+ZTFdozMfHBz179kReXl4H9c62xMfHy9eO92/7kCQJn332GR577DG4uLjcsq2937+zZs3CDz/8gG3btqFr1663bNvc66/h3jT8y/vXqDXX1+Cdd97BwoULsXHjRsTFxd2ybffu3eHv78/7txXX18DZ2RkDBw6Urx3v36a15RqXl5dj1apVLfpDmz3fwy4uLoiOjsbgwYOxYMEC9O/fH//4xz+abMvXX8vEUKiixMREbNmyRXFs06ZN8l//XFxcMHjwYEUbvV6PLVu2NDtPm5RWrlyJJ554AitXrlRsI92csrIy5OfnIyQkpAN6Z3sOHjwoXzvev+0jIyMDeXl5LfqFxF7vX0mSMGvWLKxduxZbt25FZGTkbT/mdq+/kZGRCA4OVrS5efMm9u7da3f3b1uuLyB2D3zzzTeRlpaGIUOG3Lb9hQsXcO3aNd6/Lby+DdXX1+PIkSPyteP9q3Qn13j16tWorq7Go48+etu29noPN0Wv16O6urrJc3z9tVCqbnNjY0pLS6Xs7GwpOztbAiC9++67UnZ2tnT27FlJkiTp5Zdflh577DG5/alTpyR3d3fpT3/6k3Ts2DFp0aJFkqOjo5SWlia3WbVqlaTVaqVly5ZJubm50vTp0yUfHx+poKCgw5+f2lp7fZcvXy45OTlJixYtki5fviw/iouL5TZ//OMfpe3bt0unT5+WMjMzpZSUFMnf318qKirq8OenttZe3/fee09at26ddPLkSenIkSPSc889Jzk4OEibN2+W2/D+NWrt9TV49NFHpWHDhjX5OXn/CjNmzJC8vb2l7du3K/6vV1RUyG0ee+wx6eWXX5bfz8zMlJycnKR33nlHOnbsmDR37lzJ2dlZOnLkiNxm4cKFko+Pj/Ttt99Khw8flu655x4pMjJSqqys7NDnp7a2XN+FCxdKLi4u0tdff634mNLSUkmSxP+HF198UcrKypJOnz4tbd68WRo0aJDUo0cPqaqqqsOfo5racn3nz58vpaenS/n5+dL+/fulBx98UHJ1dZWOHj0qt+H9a9SWa2wwYsQI6YEHHjA5znvY6OWXX5YyMjKk06dPS4cPH5ZefvllSaPRSBs3bpQkia+/1oKhsB0Ztuhv/Jg6daokSWLr4tGjR5t8zIABAyQXFxepe/fu0ueff27yeT/44AMpPDxccnFxkeLj46U9e/aY/8lYoNZe39GjR9+yvSSJEiAhISGSi4uLFBoaKj3wwANSXl5exz4xC9Ha6/vWW29JUVFRkqurq+Tr6yslJydLW7duNfm8vH+Ftrw+FBcXS25ubtLSpUub/Jy8f4WmrisAxevp6NGjFf/3JUmSvvrqK6lnz56Si4uLFBsbK/3444+K83q9Xnr99deloKAgSavVSuPGjZNOnDjRAc/IsrTl+kZERDT5MXPnzpUkSZIqKiqkCRMmSAEBAZKzs7MUEREhPfXUU3b5B6O2XN85c+bIr6tBQUHSXXfdJR04cEDxeXn/GrX1NeL48eMSADncNMR72OgPf/iDFBERIbm4uEgBAQHSuHHjFNeMr7/WQSNJktROg45ERERERERkZbimkIiIiIiIyI4xFBIREREREdkxhkIiIiIiIiI7xlBIRERERERkxxgKiYiIiIiI7BhDIRERERERkR1jKCQiIiIiIrJjDIVERERERER2jKGQiIjoFjQaDdatW6d2N4iIiMyGoZCIiCzW448/Do1GY/JITU1Vu2tEREQ2w0ntDhAREd1KamoqPv/8c8UxrVarUm+IiIhsD0cKiYjIomm1WgQHBysenTt3BiCmdi5evBgTJ06Em5sbunfvjq+//lrx8UeOHMHYsWPh5uYGPz8/TJ8+HWVlZYo2n332GWJjY6HVahESEoJZs2Ypzl+9ehX33nsv3N3d0aNHD3z33XfyuRs3buCRRx5BQEAA3Nzc0KNHD5MQS0REZMkYComIyKq9/vrruO+++3Do0CE88sgjePDBB3Hs2DEAQHl5OXQ6HTp37oyffvoJq1evxubNmxWhb/HixZg5cyamT5+OI0eO4LvvvkN0dLTia8yfPx/3338/Dh8+jLvuuguPPPIIrl+/Ln/93NxcbNiwAceOHcPixYvh7+/fcReAiIjoDmkkSZLU7gQREVFTHn/8cXz55ZdwdXVVHH/11Vfx6quvQqPR4JlnnsHixYvlcwkJCRg0aBA+/PBDfPzxx3jppZdw/vx5eHh4AADWr1+PyZMn49KlSwgKCkJoaCieeOIJ/OUvf2myDxqNBq+99hrefPNNACJodurUCRs2bEBqairuvvtu+Pv747PPPjPTVSAiIjIvrikkIiKLNmbMGEXoAwBfX1/57cTERMW5xMREHDx4EABw7Ngx9O/fXw6EADB8+HDo9XqcOHECGo0Gly5dwrhx427Zh7i4OPltDw8PeHl5oaioCAAwY8YM3HfffThw4AAmTJiAKVOmICkpqU3PlYiISA0MhUREZNE8PDxMpnO2Fzc3txa1c3Z2Vryv0Wig1+sBABMnTsTZs2exfv16bNq0CePGjcPMmTPxzjvvtHt/iYiIzIFrComIyKrt2bPH5P3evXsDAHr37o1Dhw6hvLxcPp+ZmQkHBwfExMTA09MT3bp1w5YtW+6oDwEBAZg6dSq+/PJLvP/++1i6dOkdfT4iIqKOxJFCIiKyaNXV1SgoKFAcc3JykjdzWb16NYYMGYIRI0Zg+fLl2LdvHz799FMAwCOPPIK5c+di6tSpmDdvHq5cuYLZs2fjscceQ1BQEABg3rx5eOaZZxAYGIiJEyeitLQUmZmZmD17dov698Ybb2Dw4MGIjY1FdXU1fvjhBzmUEhERWQOGQiIismhpaWkICQlRHIuJicHx48cBiJ1BV61ahWeffRYhISFYuXIl+vTpAwBwd3dHeno6nnvuOQwdOhTu7u6477778O6778qfa+rUqaiqqsJ7772HF198Ef7+/vjtb3/b4v65uLjglVdewZkzZ+Dm5oaRI0di1apV7fDMiYiIOgZ3HyUiIqul0Wiwdu1aTJkyRe2uEBERWS2uKSQiIiIiIrJjDIVERERERER2jGsKiYjIanEFBBER0Z3jSCEREREREZEdYygkIiIiIiKyYwyFREREREREdoyhkIiIiIiIyI4xFBIREREREdkxhkIiIiIiIiI7xlBIRERERERkxxgKiYiIiIiI7Nj/B+3N/mcrJNO0AAAAAElFTkSuQmCC\n"
          },
          "metadata": {}
        }
      ],
      "source": [
        "import matplotlib.pyplot as plt\n",
        "\n",
        "\n",
        "\n",
        "# Create a list of epoch numbers\n",
        "epochs = [epoch+1 for epoch in range(N_EPOCHS)]\n",
        "\n",
        "# Create the figure and axes\n",
        "fig, ax1 = plt.subplots(figsize=(10, 6))\n",
        "ax2 = ax1.twinx()\n",
        "\n",
        "# Plotting the training and validation loss\n",
        "ax1.plot(epochs, train_losses, label='Train Loss', color='blue')\n",
        "ax1.plot(epochs, valid_losses, label='Validation Loss', color='orange')\n",
        "ax1.set_xlabel('Epochs')\n",
        "ax1.set_ylabel('Loss')\n",
        "ax1.set_title('Training and Validation Loss/PPL')\n",
        "\n",
        "# Plotting the training and validation perplexity\n",
        "ax2.plot(epochs, train_PPLs, label='Train PPL', color='green')\n",
        "ax2.plot(epochs, valid_PPLs, label='Validation PPL', color='red')\n",
        "ax2.set_ylabel('Perplexity')\n",
        "\n",
        "# Adjust the y-axis scaling for PPL plot\n",
        "ax2.set_ylim(bottom=min(min(train_PPLs), min(valid_PPLs)) - 10, top=max(max(train_PPLs), max(valid_PPLs)) + 10)\n",
        "\n",
        "# Set the legend\n",
        "lines1, labels1 = ax1.get_legend_handles_labels()\n",
        "lines2, labels2 = ax2.get_legend_handles_labels()\n",
        "lines = lines1 + lines2\n",
        "labels = labels1 + labels2\n",
        "ax1.legend(lines, labels, loc='upper right')\n",
        "\n",
        "\n",
        "# Show the plot\n",
        "plt.show()\n"
      ],
      "execution_count": 33
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "7d38bd3a-1f63-4550-97ee-3f995b4fee1d"
      },
      "source": [
        "It can be seen that the loss and perplexity are decreasing as model gets trained. The validation loss starts to stabilize and then grow at Epoch 9, which suggests you do not need to continue training the model to avoid overtraining.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "070c061d-25c2-4e03-bb15-268c38dcd346"
      },
      "source": [
        "## Loading the saved model\n",
        "If you want to skip training and load the pre-trained model that is provided, go ahead and uncomment the following cell:\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "5d557e63-145f-4faf-8fb1-b0dcdaab9a6a"
      },
      "outputs": [],
      "source": [
        "# !wget 'https://cf-courses-data.s3.us.cloud-object-storage.appdomain.cloud/IBMSkillsNetwork-AI0201EN-Coursera/RNN-TR-model.pt'\n",
        "# model.load_state_dict(torch.load('RNN-TR-model.pt',map_location=torch.device('cpu')))"
      ],
      "execution_count": 34
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "f62ba587-7078-4437-a1a8-edab9cdba312"
      },
      "source": [
        "## Model inference\n",
        "\n",
        "\n",
        "Next, create a generator function that generates translations for input source sentences:\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "a44b10fd-cae5-4fbd-b8e5-7836dccec664"
      },
      "outputs": [],
      "source": [
        "import torch.nn.functional as F\n",
        "\n",
        "def generate_translation(model, src_sentence, src_vocab, trg_vocab, max_len=50):\n",
        "    model.eval()  # Set the model to evaluation mode\n",
        "\n",
        "    with torch.no_grad():\n",
        "        src_tensor = text_transform[SRC_LANGUAGE](src_sentence).view(-1, 1).to(device)\n",
        "\n",
        "        # Pass the source tensor through the encoder\n",
        "        hidden, cell = model.encoder(src_tensor)\n",
        "\n",
        "        # Create a tensor to store the generated translation\n",
        "        # get_stoi() maps tokens to indices\n",
        "        trg_indexes = [trg_vocab.get_stoi()['<bos>']]  # Start with <bos> token\n",
        "\n",
        "        # Convert the initial token to a PyTorch tensor\n",
        "        trg_tensor = torch.LongTensor(trg_indexes).unsqueeze(1)  # Add batch dimension\n",
        "\n",
        "        # Move the tensor to the same device as the model\n",
        "        trg_tensor = trg_tensor.to(model.device)\n",
        "\n",
        "\n",
        "        # Generate the translation\n",
        "        for _ in range(max_len):\n",
        "\n",
        "            # Pass the target tensor and the previous hidden and cell states through the decoder\n",
        "            output, hidden, cell = model.decoder(trg_tensor[-1], hidden, cell)\n",
        "\n",
        "            # Get the predicted next token\n",
        "            pred_token = output.argmax(1)[-1].item()\n",
        "\n",
        "            # Append the predicted token to the translation\n",
        "            trg_indexes.append(pred_token)\n",
        "\n",
        "\n",
        "            # If the predicted token is the <eos> token, stop generating\n",
        "            if pred_token == trg_vocab.get_stoi()['<eos>']:\n",
        "                break\n",
        "\n",
        "            # Convert the predicted token to a PyTorch tensor\n",
        "            trg_tensor = torch.LongTensor(trg_indexes).unsqueeze(1)  # Add batch dimension\n",
        "\n",
        "            # Move the tensor to the same device as the model\n",
        "            trg_tensor = trg_tensor.to(model.device)\n",
        "\n",
        "        # Convert the generated tokens to text\n",
        "        # get_itos() maps indices to tokens\n",
        "        trg_tokens = [trg_vocab.get_itos()[i] for i in trg_indexes]\n",
        "\n",
        "        # Remove the <sos> and <eos> from the translation\n",
        "        if trg_tokens[0] == '<bos>':\n",
        "            trg_tokens = trg_tokens[1:]\n",
        "        if trg_tokens[-1] == '<eos>':\n",
        "            trg_tokens = trg_tokens[:-1]\n",
        "\n",
        "        # Return the translation list as a string\n",
        "\n",
        "        translation = \" \".join(trg_tokens)\n",
        "\n",
        "        return translation"
      ],
      "execution_count": 35
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "82088462-f940-47a7-85e5-d0412262526e"
      },
      "source": [
        "Now, you can check the model's output for a sample sentence:\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "a7e976f2-ceee-4c37-a962-54477c156964",
        "outputId": "c9733649-d7ae-46cf-d976-5485d88804d7"
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "An Asian man is on the sidewalk of a building .\n"
          ]
        }
      ],
      "source": [
        "# model.load_state_dict(torch.load('RNN-TR-model.pt'))\n",
        "\n",
        "# Actual translation: Asian man sweeping the walkway.\n",
        "src_sentence = 'Ein asiatischer Mann kehrt den Gehweg.'\n",
        "\n",
        "\n",
        "generated_translation = generate_translation(model, src_sentence=src_sentence, src_vocab=vocab_transform['de'], trg_vocab=vocab_transform['en'], max_len=12)\n",
        "#generated_translation = \" \".join(generated_translation_list).replace(\"<bos>\", \"\").replace(\"<eos>\", \"\")\n",
        "print(generated_translation)\n"
      ],
      "execution_count": 36
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "b40f0976-e8b2-46fe-a063-b5931081f33c"
      },
      "source": [
        "Fantastic! You have created a translation model that can generate german-english translations pretty accurate, huh?\n",
        "\n",
        "You can play with the model parameters and hyperparameters to improve the model performance.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "b4028509-6063-4cc8-8290-4e4f098b7700"
      },
      "source": [
        "## BLEU score metric for evaluation\n",
        "While peplexity serves as a general metric to evaluate the performance of language model in predicting the correct next token, BLEU score is helpful in evaluating the quality of the final generated translation.\n",
        "Validating the results using BLEU score is helpful when there is more than a single valid translation for a sentence as you can include many translation versions in the reference list and compare the generated translation with different versions of translations.\n",
        "\n",
        "The BLEU (Bilingual Evaluation Understudy) score is a metric commonly used to evaluate the quality of machine-generated translations by comparing them to one or more reference translations. It measures the similarity between the generated translation and the reference translations based on n-gram matching.\n",
        "\n",
        "The BLEU score is calculated using the following formulas:\n",
        "\n",
        "1. **Precision**:\n",
        "   - Precision measures the proportion of n-grams in the generated translation that appear in the reference translations.\n",
        "   - Precision is calculated for each n-gram order (1 to N) and then combined using a geometric mean.\n",
        "   - The precision for a particular n-gram order is calculated as:\n",
        "   \n",
        "   $$\\text{Precision}_n(t) = \\frac{\\text{CountClip}_n(t)}{\\text{Count}_n(t)}$$\n",
        "   \n",
        "   where:\n",
        "     - $\\text{CountClip}_n(t)$ is the count of n-grams in the generated translation that appear in any reference translation, clipped by the maximum count of that n-gram in any single reference translation.\n",
        "     - $\\text{Count}_n(t)$ is the count of n-grams in the generated translation.\n",
        "\n",
        "2. . **Brevity penalty**:\n",
        "   - The brevity penalty accounts for the fact that shorter translations tend to have higher precision scores.\n",
        "   - It encourages translations that are closer in length to the reference translations.\n",
        "   - The brevity penalty is calculated as:\n",
        "   \n",
        "  $$\\text{BP} = \\begin{cases} 1 & \\text{if } c > r \\\\\\\\\\\\\\\\\\\\ e^{(1 - \\frac{r}{c})} & \\text{if } c \\leq r \\end{cases}$$\n",
        "   \n",
        "   where:\n",
        "     - $c$ is the total length of the generated translation.\n",
        "     - $r$ is the total length of the reference translations.\n",
        "\n",
        "3. **BLEU score**:\n",
        "   - The BLEU score is the geometric mean of the precisions, weighted by the brevity penalty.\n",
        "   - It is calculated as:\n",
        "   \n",
        "   $$\\text{BLEU} = \\text{BP} \\cdot \\exp(\\sum_{n=1}^{N}w_n \\log(\\text{Precision}_n(t)))$$\n",
        "   \n",
        "   where:\n",
        "     - $N$ is the maximum n-gram order.\n",
        "     - $w_n$ is the weight assigned to the precision at n-gram order $n$, commonly set as $\\frac{1}{N}$ for equal weights.\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "1795d5cf-90ac-41d8-97f5-f58d5bf28995"
      },
      "outputs": [],
      "source": [
        "def calculate_bleu_score(generated_translation, reference_translations):\n",
        "    # Convert the generated translations and reference translations into the expected format for sentence_bleu\n",
        "    references = [reference.split() for reference in reference_translations]\n",
        "    hypothesis = generated_translation.split()\n",
        "\n",
        "    # Calculate the BLEU score\n",
        "    bleu_score = sentence_bleu(references, hypothesis)\n",
        "\n",
        "    return bleu_score"
      ],
      "execution_count": 37
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "635e2f2f-7826-4d71-b819-5e336e35e9f5"
      },
      "source": [
        "Let's calculate the BLEU score for a sample sentence:\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "57c421b4-4014-4ca0-9dcf-fdbeed2cfab0",
        "outputId": "e4512007-6953-46fc-9ad8-8103c18edafd"
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "BLEU Score: 0.28997844147152074\n"
          ]
        }
      ],
      "source": [
        "reference_translations = [\n",
        "    \"Asian man sweeping the walkway .\",\n",
        "    \"An asian man sweeping the walkway .\",\n",
        "    \"An Asian man sweeps the sidewalk .\",\n",
        "    \"An Asian man is sweeping the sidewalk .\",\n",
        "    \"An asian man is sweeping the walkway .\",\n",
        "    \"Asian man sweeping the sidewalk .\"\n",
        "]\n",
        "\n",
        "bleu_score = calculate_bleu_score(generated_translation, reference_translations)\n",
        "print(\"BLEU Score:\", bleu_score)"
      ],
      "execution_count": 38
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "0a7e92f3-4f94-4bf9-b7d0-c87241ec2ce7"
      },
      "source": [
        "# Exercises\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "22f3e63c-250a-44c3-8aee-2cbac6d06ccc"
      },
      "source": [
        "### Exercise 1 - Translate a German sentence to English.\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "b967f961-e967-415c-8ae6-59ab43ee5602",
        "outputId": "e7b1c859-245b-4bcf-a9f5-ac596c2feef3"
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "Original German text: Menschen gehen auf der Straße\n",
            "Translated English text: People walking on the street street .\n"
          ]
        }
      ],
      "source": [
        "# Define the German text to be translated\n",
        "german_text = \"Menschen gehen auf der Straße\"\n",
        "\n",
        "# The function should be defined to accept the text, the model, source and target vocabularies, and the device as parameters.\n",
        "english_translation = generate_translation(\n",
        "    model,\n",
        "    src_sentence=german_text,\n",
        "    src_vocab=vocab_transform['de'],\n",
        "    trg_vocab=vocab_transform['en'],\n",
        "    max_len=50\n",
        ")\n",
        "\n",
        "# Display the original and translated text\n",
        "print(f\"Original German text: {german_text}\")\n",
        "print(f\"Translated English text: {english_translation}\")"
      ],
      "execution_count": 39
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "53c89046-2e3e-40a3-b806-bd7eae65a1e5"
      },
      "source": [
        "<details>\n",
        "    <summary>Click here for Solution</summary>\n",
        "\n",
        "```python\n",
        "german_text = \"Menschen gehen auf der Straße\"\n",
        "\n",
        "# The function should be defined to accept the text, the model, source and target vocabularies, and the device as parameters.\n",
        "english_translation = generate_translation(\n",
        "    model,\n",
        "    src_sentence=german_text,\n",
        "    src_vocab=vocab_transform['de'],\n",
        "    trg_vocab=vocab_transform['en'],\n",
        "    max_len=50\n",
        ")\n",
        "\n",
        "# Display the original and translated text\n",
        "print(f\"Original German text: {german_text}\")\n",
        "print(f\"Translated English text: {english_translation}\")\n",
        "```\n",
        "\n",
        "</details>\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "8b04e862-9167-4975-a7ca-af4dbb840401"
      },
      "source": [
        "## Authors\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "9012f0b6-ca67-4fe9-96de-1a7568b05eae"
      },
      "source": [
        "[Fateme Akbari](https://www.linkedin.com/in/fatemeakbari/) is a PhD candidate in Information Systems at McMaster University with demonstrated research experience in Machine Learning and NLP.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "4943a248-316b-4279-aa08-69bde232f654"
      },
      "source": [
        "```{## Change log}\n",
        "```\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "43ff8bcf-4e99-4f04-af3f-ae7e6d53c78b"
      },
      "source": [
        "```{|Date (YYYY-MM-DD)|Version|Changed By|Change Description||-|-|-|-||2020-07-17|0.1|Sam|Create Lab Template|}\n",
        "```\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "8ecb15be-f647-4ff5-9aac-c46bc18112b4"
      },
      "source": [
        "© Copyright IBM Corporation. All rights reserved.\n"
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "name": "python3"
    },
    "language_info": {
      "codemirror_mode": {
        "name": "ipython",
        "version": 3
      },
      "file_extension": ".py",
      "mimetype": "text/x-python",
      "name": "python",
      "nbconvert_exporter": "python",
      "pygments_lexer": "ipython3",
      "version": "3.11.9"
    },
    "prev_pub_hash": "50b168a2230d253ace1c41749630f15ead999c4adeff60aa79c91ff90b902a92",
    "colab": {
      "provenance": [],
      "gpuType": "T4"
    },
    "accelerator": "GPU"
  },
  "nbformat": 4,
  "nbformat_minor": 0
}