04_deep_learning.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "GTY-Msjal7zU"
   },
   "source": [
    "# Creative Machine Learning - Deep learning\n",
    "\n",
    "### Author: Philippe Esling (esling@ircam.fr)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "Z3M5ezRyrjA3"
   },
   "source": [
    "In this course we will cover\n",
    "1. A brief introduction to [deep learning](#learning) and problems that we face\n",
    "2. A formal presentation of [Auto-Encoders](#ae) (AEs)\n",
    "3. An explanation of how to [implement AEs](#implement) and [layer-wise pretraining](#implement)\n",
    "4. An [more modern application](#application) of AEs as generative models\n",
    "4. An practical exemple of [convolutional denoising AEs](#denoising) for image data **(exercise)**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Deep learning\n",
    "\n",
    "Deep learning is currently the most successful subfield of machine learning that deals with algorithms inspired by the structure and function of the brain through artificial neural networks. It enables computers to learn from vast amounts of data and has revolutionized various fields such as computer vision, natural language processing and speech recognition.\n",
    "\n",
    "## Why deep architectures?\n",
    "Deep architectures are essential because they allow models to learn hierarchical representations from raw input data. These hierarchical representations can capture increasingly complex and abstract features as the network depth increases. This capability enables deep learning models to achieve state-of-the-art results in many tasks, as they can automatically learn to extract relevant features from the input data without relying on hand-engineered features.\n",
    "\n",
    "**References:** \n",
    "- Goodfellow, I., Bengio, Y., & Courville, A. (2016). [Deep Learning](http://www.deeplearningbook.org). MIT Press.\n",
    "\n",
    "## Challenges in deep architectures\n",
    "\n",
    "As seen in the course, there are several impediments in learning deep architectures, namely\n",
    "1. Vanishing gradient\n",
    "2. Overfitting issues\n",
    "3. Multiple local minima\n",
    "4. Instability in the training\n",
    "Here, we briefly discuss the two major problems, namely _vanishing gradient_ and _overfitting_.\n",
    "\n",
    "#### Vanishing gradient\n",
    "One of the main challenges in training deep architectures is the vanishing gradient problem. It occurs when gradients of the loss function with respect to the model parameters become too small as they backpropagate through the layers. This issue leads to slow convergence and poor performance, as the weights in the earlier layers do not get updated significantly during training.\n",
    "\n",
    "#### Overfitting\n",
    "Another challenge in deep learning is overfitting, where the model learns to perform well on the training data but fails to generalize to unseen data. Regularization techniques, such as L1 and L2 regularization, dropout, and weight decay, are used to prevent overfitting by adding constraints to the model or by making the training process more robust.\n",
    "\n",
    "**References:**\n",
    "- Pascanu, R., Mikolov, T., & Bengio, Y. (2013). [On the difficulty of training recurrent neural networks](https://proceedings.mlr.press/v28/pascanu13.html). In International conference on machine learning (pp. 1310-1318).\n",
    "- Srivastava, N., Hinton, G., Krizhevsky, A., Sutskever, I., & Salakhutdinov, R. (2014). [Dropout: A simple way to prevent neural networks from overfitting](http://jmlr.org/papers/v15/srivastava14a.html). Journal of Machine Learning Research, 15(1), 1929-1958.\n",
    "\n",
    "### Layer-wise Pretraining\n",
    "To address the vanishing gradient problem and improve the training of deep architectures, layer-wise pretraining was proposed. In this approach, each layer of the deep architecture is pretrained independently, usually with unsupervised learning methods like autoencoders, before fine-tuning the entire network using supervised learning.\n",
    "\n",
    "**References:**\n",
    "- Hinton, G. E., Osindero, S., & Teh, Y. W. (2006). [A fast learning algorithm for deep belief nets](https://www.cs.toronto.edu/~hinton/absps/fastnc.pdf). Neural computation, 18(7), 1527-1554.\n",
    "- Vincent, P., Larochelle, H., Bengio, Y., & Manzagol, P. A. (2008). [Extracting and composing robust features with denoising autoencoders](https://dl.acm.org/doi/10.1145/1390156.1390294). In Proceedings of the 25th international conference on Machine learning (pp. 1096-1103).\n",
    "\n",
    "\n",
    "#### Autoencoders\n",
    "_Autoencoders_ are unsupervised learning models that learn to reconstruct their input data. They consist of an encoder that maps the input data to a lower-dimensional representation and a decoder that reconstructs the input data from the lower-dimensional representation. Autoencoders can be used to learn useful features from the data and initialize the weights of a deep architecture during layer-wise pretraining. As we have seen, an interesting variant of autoencoders are _denoising autoencoders_ that learn to reconstruct the input data from a corrupted version of it. By learning to recover the original data from the corrupted version, denoising autoencoders can capture more robust and meaningful features. They can be used in layer-wise pretraining to improve the training of deep architectures further."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## A brief refresher in Pytorch\n",
    "\n",
    "As we have seen previously, `Pytorch` is a Python-based scientific computing package targeted at deep learning, which provides a very large flexibility and easeness of use for GPU calculation. `Pytorch` is constructed around the concept of `Tensor`, which is very similar to `numpy.ndarray`, but can be seamlessly run on GPU. Here, we provide a more detailed refresher on concepts of `Pytorch`.\n",
    "\n",
    "Here are some examples of different `Tensor` creation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "import torch\n",
    "# Create a 5 x 3 Tensor of zeros\n",
    "x = torch.empty(5, 3)\n",
    "# Create a 64 x 3 x 32 x 32 random Tensor\n",
    "x = torch.rand(64, 3, 32, 32)\n",
    "# Create a Tensor of zeros with _long_ type\n",
    "x = torch.zeros(10, 10, dtype=torch.long)\n",
    "# Construct a Tensor from the data\n",
    "x = torch.tensor([5.5, 3])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "or create a tensor based on an existing tensor. These methods\n",
    "will reuse properties of the input tensor, e.g. dtype, unless\n",
    "new values are provided by user\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "torch.Size([8, 2])\n",
      "8\n",
      "torch.Size([8, 2])\n"
     ]
    }
   ],
   "source": [
    "x = x.new_ones(8, 2, dtype=torch.double)      # new_* methods take in sizes\n",
    "y = torch.randn_like(x, dtype=torch.float)    # override dtype!\n",
    "print(x.size())\n",
    "print(x.shape[0])\n",
    "print(y.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Arithmetic operations\n",
    "\n",
    "Tensors provide access to a transparent library of arithmetic operations"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "tensor([[0.5208, 1.3827],\n",
      "        [0.5559, 0.0124],\n",
      "        [0.6077, 0.3092],\n",
      "        [0.0675, 0.2121],\n",
      "        [0.1778, 1.3361],\n",
      "        [0.1351, 0.4214],\n",
      "        [0.0411, 0.0655],\n",
      "        [0.5816, 0.8240]])\n",
      "tensor([[1.2363, 1.4421, 2.7028, 1.4048],\n",
      "        [0.6893, 0.7793, 0.9107, 0.4320],\n",
      "        [0.8570, 0.9867, 1.5605, 0.7894],\n",
      "        [0.5596, 0.6665, 1.5543, 0.8308],\n",
      "        [0.5115, 0.6223, 1.7393, 0.9471],\n",
      "        [0.6849, 0.7914, 1.3177, 0.6725],\n",
      "        [0.7479, 0.8484, 1.0565, 0.5090],\n",
      "        [1.0384, 1.1963, 1.9100, 0.9678]])\n"
     ]
    }
   ],
   "source": [
    "x = torch.rand(8, 2)\n",
    "y = torch.rand(8, 2)\n",
    "z = torch.rand(2, 4)\n",
    "# Equivalent additions\n",
    "a = (x + y)\n",
    "b = (torch.add(x, y))\n",
    "# Add in place\n",
    "x.add_(y)\n",
    "# Put in target Tensor\n",
    "result = torch.empty(8, 2)\n",
    "torch.add(x, y, out=result)\n",
    "# Element_wise multiplication\n",
    "print(x * y)\n",
    "# Matrix product\n",
    "print(x @ z)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Slicing and resizing\n",
    "\n",
    "You can slice tensors using the usual Python operators. For resizing and reshaping tensor, you can use ``torch.view`` or ``torch.reshape``"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "torch.Size([16, 32, 32])\n",
      "torch.Size([64, 32, 32])\n",
      "torch.Size([4, 4]) torch.Size([16]) torch.Size([2, 8])\n",
      "torch.Size([2, 2, 2, 2])\n"
     ]
    }
   ],
   "source": [
    "#print(x[:, 1])\n",
    "import torch\n",
    "x = torch.zeros(16, 32, 32)\n",
    "x2 = torch.zeros(64, 32, 32)\n",
    "y = x.view(-1, 32, 32)\n",
    "y2 = x2.view(-1, 32, 32)\n",
    "print(y.size())\n",
    "print(y2.size())\n",
    "x = torch.randn(4, 4)\n",
    "y = x.view(16)\n",
    "z = x.view(-1, 8)  # the size -1 is inferred from other dimensions\n",
    "print(x.size(), y.size(), z.size())\n",
    "\n",
    "z = torch.rand(4, 4)\n",
    "z = z.view(-1, 2, 2, 2)\n",
    "print(z.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you have a one element tensor, use ``.item()`` to get the value as a\n",
    "Python number\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "tensor([0.0748])\n",
      "0.07484906911849976\n"
     ]
    }
   ],
   "source": [
    "x = torch.randn(1)\n",
    "print(x)\n",
    "print(x.item())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Tensors have more than **100 operations**, including _transposing, indexing, slicing, mathematical operations, linear algebra, random numbers_, which are all described at [https://pytorch.org/docs/torch](https://pytorch.org/docs/torch)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Numpy bridge\n",
    "\n",
    "Converting a Torch Tensor to a Numpy array and vice versa is extremely simple. Note that the Pytorch Tensor and Numpy array **will share their underlying memory locations** (if the Tensor is on CPU), and changing one will change the other."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "tensor([2., 2., 2., 2., 2.])\n",
      "[2. 2. 2. 2. 2.]\n"
     ]
    }
   ],
   "source": [
    "a = torch.ones(5)\n",
    "b = a.numpy()\n",
    "a.add_(1)\n",
    "print(a)\n",
    "print(b)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Going GPU\n",
    "\n",
    "Tensors can be moved onto any device using the ``.to`` method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "# let us run this cell only if CUDA is available\n",
    "# We will use ``torch.device`` objects to move tensors in and out of GPU\n",
    "if torch.cuda.is_available():\n",
    "    device = torch.device(\"cuda\")          # a CUDA device object\n",
    "    y = torch.ones_like(x, device=device)  # directly create a tensor on GPU\n",
    "    x = x.to(device)                       # or just use strings ``.to(\"cuda\")``\n",
    "    z = x + y\n",
    "    print(z)\n",
    "    print(z.to(\"cpu\", torch.double))       # ``.to`` can also change dtype together!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Computation Graphs\n",
    "\n",
    "The concept of a computation graph is essential to efficient deep learning programming, because it allows you to not have to write the back propagation gradients yourself. A computation graph is simply a specification of how your data is combined to give you the output (the forward pass). Since the graph totally specifies what parameters were involved with which operations, it contains enough information to compute derivatives. \n",
    "\n",
    "The fundamental flag ``requires_grad`` allows to specify which variables are going to need differentiation in all these operations. If ``requires_grad=True``, the Tensor object keeps track of how it was created."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "tensor([1., 2., 3.], requires_grad=True)\n",
      "<AddBackward0 object at 0x3083a9f70>\n",
      "tensor([0.3333, 0.3333, 0.3333])\n"
     ]
    }
   ],
   "source": [
    "# Tensor factory methods have a ``requires_grad`` flag\n",
    "x = torch.tensor([1., 2., 3], requires_grad=True)\n",
    "# With requires_grad=True, we can still do all the operations \n",
    "y = torch.tensor([4., 5., 6], requires_grad=True)\n",
    "print(x)\n",
    "z = x + y\n",
    "out = z.mean(-1)\n",
    "#print(z)\n",
    "# But z now knows something extra.\n",
    "print(z.grad_fn)\n",
    "out.backward()\n",
    "print(y.grad)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Therefore, `z` knows that it is the direct result of an addition. Furthermore, if we keep following z.grad_fn, we can even find back both `x` and `y`. But how does that help us compute a gradient?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "tensor(21., grad_fn=<SumBackward0>)\n",
      "<SumBackward0 object at 0x124f45d90>\n",
      "<AddBackward0 object at 0x1059b7b50>\n",
      "None\n"
     ]
    }
   ],
   "source": [
    "# Lets sum up all the entries in z\n",
    "s = z.sum()\n",
    "print(s)\n",
    "print(s.grad_fn)\n",
    "print(z.grad_fn)\n",
    "print(x.grad_fn)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So now, what is the derivative of this sum with respect to the first\n",
    "component of x? In math, we want\n",
    "\n",
    "\\begin{align}\\frac{\\partial s}{\\partial x_0}\\end{align}\n",
    "\n",
    "\n",
    "\n",
    "Well, s knows that it was created as a sum of the tensor z. z knows\n",
    "that it was the sum x + y. So\n",
    "\n",
    "\\begin{align}s = \\overbrace{x_0 + y_0}^\\text{$z_0$} + \\overbrace{x_1 + y_1}^\\text{$z_1$} + \\overbrace{x_2 + y_2}^\\text{$z_2$}\\end{align}\n",
    "\n",
    "And so s contains enough information to determine that the derivative we want is 1. We can have Pytorch compute the gradient, and see that we were right:\n",
    "\n",
    "**Note** : If you run this block multiple times, the gradient will increment. That is because Pytorch *accumulates* the gradient into the .grad property, since for many models this is very convenient."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "tensor([1.3333, 1.3333, 1.3333])\n"
     ]
    }
   ],
   "source": [
    "# calling .backward() on any variable will run backprop, starting from it.\n",
    "s.backward()\n",
    "print(x.grad)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Understanding what is going on in the block below is crucial for being a\n",
    "successful programmer in deep learning.\n",
    "\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "False False\n",
      "None\n",
      "<AddBackward0 object at 0x124f5c550>\n",
      "True\n",
      "None\n"
     ]
    }
   ],
   "source": [
    "x = torch.randn(2, 2)\n",
    "y = torch.randn(2, 2)\n",
    "# By default, user created Tensors have ``requires_grad=False``\n",
    "print(x.requires_grad, y.requires_grad)\n",
    "z = x + y\n",
    "# So you can't backprop through z\n",
    "print(z.grad_fn)\n",
    "# ``.requires_grad_( ... )`` changes an existing Tensor's ``requires_grad``\n",
    "x = x.requires_grad_()\n",
    "y = y.requires_grad_()\n",
    "# z contains enough information to compute gradients, as we saw above\n",
    "z = x + y\n",
    "print(z.grad_fn)\n",
    "# If any input to an operation has ``requires_grad=True``, so will the output\n",
    "print(z.requires_grad)\n",
    "# Now z has the computation history, which we can **detach**\n",
    "new_z = z.detach()\n",
    "# Which means that we have no gradient attached anymore\n",
    "print(new_z.grad_fn)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also stop autograd from tracking history on Tensors\n",
    "with ``.requires_grad=True`` by wrapping the code block in\n",
    "``with torch.no_grad():``\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "True\n",
      "True\n",
      "False\n"
     ]
    }
   ],
   "source": [
    "print(x.requires_grad)\n",
    "print((x ** 2).requires_grad)\n",
    "with torch.no_grad():\n",
    "\tprint((x ** 2).requires_grad)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Defining networks \n",
    "\n",
    "Here, we briefly recall that in `PyTorch`, the `nn` package provides higher-level abstractions over raw computational graphs that are useful for building neural networks. The `nn` package defines a set of `Modules`, which are roughly equivalent to neural network layers. A `Module` receives input `Tensors` and computes output `Tensors`, but may also hold internal state such as `Tensors` containing learnable parameters. In the following example, we use the `nn` package to show how easy it is to instantiate a three-layer network"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "import torch\n",
    "import torch.nn as nn\n",
    "# Define the input dimensions\n",
    "in_size = 1000\n",
    "# Number of neurons in a layer\n",
    "hidden_size = 100\n",
    "# Output (target) dimension\n",
    "output_size = 10\n",
    "# Use the nn package to define our model and loss function.\n",
    "model = torch.nn.Sequential(\n",
    "    nn.Linear(in_size, hidden_size),\n",
    "    nn.ReLU(),\n",
    "    nn.Linear(hidden_size, hidden_size),\n",
    "    nn.Tanh(),\n",
    "    nn.Linear(hidden_size, output_size),\n",
    "    nn.Softmax()\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As we have seen in the slides, we can as easily mix between pre-defined modules and arithmetic operations. Here, we will define our very own *residual* layer, and then combine them in a more complex network. To do so, we first define our own `ResidualLayer` (by subclassing `nn.Module`). This type of layer can now be combined inside a full network by simply using `nn.Sequential`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [],
   "source": [
    "class ResidualLayer(nn.Module):\n",
    "    def __init__(self, dim, dim_res=32):\n",
    "        super().__init__()\n",
    "        self.block = nn.Sequential(\n",
    "            nn.Conv2d(dim, dim_res, 3, 1, 1),\n",
    "            nn.ReLU(True),\n",
    "            nn.Conv2d(dim_res, dim, 1),\n",
    "            nn.ReLU(True)\n",
    "        )\n",
    "\n",
    "    def forward(self, x):\n",
    "        # Perform main residual action\n",
    "        return x + self.block(x)\n",
    "\n",
    "model = nn.Sequential(\n",
    "\tResidualLayer(64, 32),\n",
    "\tResidualLayer(64, 32),\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Autoencoders and layer-wise training\n",
    "\n",
    "Here, we discuss the implementation of a deep autoencoder using PyTorch, focusing on layer-wise training. Autoencoders are unsupervised learning models that can learn useful features from the input data. They consist of an encoder, which maps the input data to a lower-dimensional representation, and a decoder, which reconstructs the input data from the lower-dimensional representation. _Deep autoencoders_ are multi-layer autoencoders that can learn more abstract and complex features from the input data. To learn such models, _layer-wise training_ was historically used as a technique to help overcome the vanishing gradient problem and initializes the network with better weights, leading to improved performance. Hence, we aim to _pretrain each layer individually_ in an **unsupervised** manner, followed by fine-tuning the entire network with _supervised learning."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id=\"generative\"></a>\n",
    "## Types of learning\n",
    "\n",
    "### Supervised refresher\n",
    "\n",
    "Until now, we have mostly discussed models that are developed for _supervised_ and _discriminative_ tasks. To formalize this problem, we have a set of data $\\{\\mathbf{x}_{i}, \\mathbf{y}_{i}\\}_{i\\in[1,n]}$, where the $\\mathbf{x}_{i}$ and $\\mathbf{y}_{i}$ are linked. Therefore, we want to approximate this relation through\n",
    "\\begin{equation}\n",
    "    \\mathbf{\\hat{y}} = \\mathcal{F}_\\mathbf{\\theta}(\\mathbf{x})  \n",
    "\\end{equation}\n",
    "where we train the parameters $\\mathbf{\\theta}$ so that $\\mathbf{\\hat{y}}\\approx\\mathbf{y}$. The existence of a label $\\mathbf{y}$ (\"correct answer\") defines a _supervised_ problem"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Going unsupervised\n",
    "\n",
    "In some cases, we might only have a set of data $\\{\\mathbf{x}_{i}\\}_{i\\in[1,n]}$, and still be interested in learning some underlying properties or structure of this set. In that case, the problem is _unsupervised_ as we have to learn without a given answer. \n",
    "\n",
    "Here, we can turn to _generative_ models [[1](#reference1)], which allows to create new data instances based on the observation of existing examples. Although these models are more naturally defined in a _probabilistic way_ (as we will see later when we dwelve in generative models), we will assume that we have some simple _code_ $\\mathbf{z}$, which allows to control the properties of the generation, and need to learn\n",
    "\\begin{equation}\n",
    "    \\mathbf{\\hat{x}} = \\mathcal{F}_\\mathbf{\\theta}(\\mathbf{z})  \n",
    "\\end{equation}\n",
    "where we still need to learn $\\mathbf{\\theta}$, so that $\\mathbf{\\hat{x}}$ have similar properties to that of the examples in $\\{\\mathbf{x}_{i}\\}_{i\\in[1,n]}$."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "Kg83oWxMm92f"
   },
   "source": [
    "<a id=\"ae\"></a>\n",
    "\n",
    "## Auto-encoders\n",
    "\n",
    "One way to understand a set of data is to try to _compress_, or _simplify_ the corresponding dataset. So the idea is to learn simultaneously how to _encode_ our unlabeled input $\\{\\mathbf{x}_{i}\\}_{i\\in[1,n]}$ and to _decode_ the corresponding representation. This idea give rise to the notion of **auto-encoder**. \n",
    "\n",
    "### Architecture \n",
    "\n",
    "The auto-encoder is an unsupervised architecture originally proposed to perform _dimensionality reduction_ [[3](#reference3)]. As its name indicates, we will try to train this model to learn an efficient _encoding_ $\\mathbf{z}$ of unlabeled input data $\\mathbf{x}$. The only way to learn efficient parameters is to also learn a _decoding_ function to _reconstruct_ $\\mathbf{x}$ from $\\mathbf{z}$.\n",
    "\n",
    "<img src=\"images/auto_encoder.png\"/>\n",
    "\n",
    "As shown here, a first model $\\mathcal{E}_\\phi$ _encodes_ the input into a _latent code_ $\\mathbf{z}$ in order to provide a low-dimensional representation of the data. A second model $\\mathcal{D}_\\theta$ designated as the _decoder_ aims to generate outputs from $\\mathbf{z}$ that are as close to the original inputs as possible."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Formal definition\n",
    "\n",
    "The latent code $\\mathbf{z}$ can be seen as a compressed abstract representation, and may be used as an intermediate space for analysis or generation. This helps to govern the distribution of the data through a simpler and higher-level representation, while enhancing the _expressiveness_ of the generative model.\n",
    "The behaviour of an auto-encoder can be formalized as:\n",
    "\n",
    "$$\n",
    "\\begin{align}\n",
    "\\mathbf{z} &= \\mathcal{E}_\\phi(\\mathbf{x}) \\\\\n",
    "\\mathbf{\\hat{x}} &= \\mathcal{D}_\\theta(\\mathbf{z})  \n",
    "\\end{align}\n",
    "$$\n",
    "\n",
    "with the _encoder_ $\\mathcal{E}_\\phi$ and _decoder_ $\\mathcal{D}_\\theta$ functions parameterized respectively by $\\phi$ and $\\theta$. As we can see this defines the reconstruction relationship\n",
    "$$\n",
    "    \\mathbf{\\hat{x}} = \\mathcal{D}_\\theta(\\mathcal{E}_\\phi(\\mathbf{x}))  \n",
    "$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Training\n",
    "\n",
    "The training of an auto-encoder consists in finding the optimal functions of encoding $\\mathcal{E}^*$ and decoding $\\mathcal{D}^*$ by evaluating the \\textit{reconstruction error} $\\mathcal{L}$ between $\\mathbf{x}$ and $\\mathbf{\\hat{x}}$, such that\n",
    "\\begin{equation}\n",
    "    \\mathcal{E}^*, \\mathcal{D}^* = arg\\,min_{ \\phi, \\theta}{\\mathcal{L}}(\\mathbf{x}, \\mathcal{D}_\\theta(\\mathcal{E}_\\phi(\\mathbf{x})))\n",
    "\\end{equation}\n",
    "\n",
    "As the latent space usually has a smaller dimensionality than the input, it acts as an incentive for the network to find the main attributes of variations in the dataset (and also explains its use for _dimensionality reduction_)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Variants and discussion\n",
    "\n",
    "There are several variants of auto-encoders, such as denoising auto-encoders or variational auto-encoders. Each address some downside of the basic AE model. For instance, the deterministic nature of the basic auto-encoder implies a point-wise mapping of the latent space, meaning that not all the latent positions can be leveraged to produce relevant reconstructions. Because of this reason, there is no way to ensure that the latent space could allow a robust generalization and that any random $\\mathbf{z}$ would generate a meaningful output."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "cAxMjUCBUa43"
   },
   "source": [
    "<a id=\"implement\"> </a>\n",
    "\n",
    "## Implementation\n",
    "\n",
    "Here, we discuss how we can implement and train a simple auto-encoder network in Pytorch. As discussed earlier, an AE is composed of two parts, an **encoder** and a **decoder**. The goal of the encoder is to \"compress\" the dataset, representing its principal features with a very small code, while the goal of the decoder is to learn how to reproduce the initial input from this code. Hence, we will first need to use some basic imports and definition to setup our problem"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "e1_Y75QXJS6h"
   },
   "source": [
    "### Import Pytorch and other libraries"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {
    "id": "YfIk2es3hJEd"
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<style>\n",
       "        .bk-notebook-logo {\n",
       "            display: block;\n",
       "            width: 20px;\n",
       "            height: 20px;\n",
       "            background-image: url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAAUCAYAAACNiR0NAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAALEgAACxIB0t1+/AAAABx0RVh0U29mdHdhcmUAQWRvYmUgRmlyZXdvcmtzIENTNui8sowAAAOkSURBVDiNjZRtaJVlGMd/1/08zzln5zjP1LWcU9N0NkN8m2CYjpgQYQXqSs0I84OLIC0hkEKoPtiH3gmKoiJDU7QpLgoLjLIQCpEsNJ1vqUOdO7ppbuec5+V+rj4ctwzd8IIbbi6u+8f1539dt3A78eXC7QizUF7gyV1fD1Yqg4JWz84yffhm0qkFqBogB9rM8tZdtwVsPUhWhGcFJngGeWrPzHm5oaMmkfEg1usvLFyc8jLRqDOMru7AyC8saQr7GG7f5fvDeH7Ej8CM66nIF+8yngt6HWaKh7k49Soy9nXurCi1o3qUbS3zWfrYeQDTB/Qj6kX6Ybhw4B+bOYoLKCC9H3Nu/leUTZ1JdRWkkn2ldcCamzrcf47KKXdAJllSlxAOkRgyHsGC/zRday5Qld9DyoM4/q/rUoy/CXh3jzOu3bHUVZeU+DEn8FInkPBFlu3+nW3Nw0mk6vCDiWg8CeJaxEwuHS3+z5RgY+YBR6V1Z1nxSOfoaPa4LASWxxdNp+VWTk7+4vzaou8v8PN+xo+KY2xsw6une2frhw05CTYOmQvsEhjhWjn0bmXPjpE1+kplmmkP3suftwTubK9Vq22qKmrBhpY4jvd5afdRA3wGjFAgcnTK2s4hY0/GPNIb0nErGMCRxWOOX64Z8RAC4oCXdklmEvcL8o0BfkNK4lUg9HTl+oPlQxdNo3Mg4Nv175e/1LDGzZen30MEjRUtmXSfiTVu1kK8W4txyV6BMKlbgk3lMwYCiusNy9fVfvvwMxv8Ynl6vxoByANLTWplvuj/nF9m2+PDtt1eiHPBr1oIfhCChQMBw6Aw0UulqTKZdfVvfG7VcfIqLG9bcldL/+pdWTLxLUy8Qq38heUIjh4XlzZxzQm19lLFlr8vdQ97rjZVOLf8nclzckbcD4wxXMidpX30sFd37Fv/GtwwhzhxGVAprjbg0gCAEeIgwCZyTV2Z1REEW8O4py0wsjeloKoMr6iCY6dP92H6Vw/oTyICIthibxjm/DfN9lVz8IqtqKYLUXfoKVMVQVVJOElGjrnnUt9T9wbgp8AyYKaGlqingHZU/uG2NTZSVqwHQTWkx9hxjkpWDaCg6Ckj5qebgBVbT3V3NNXMSiWSDdGV3hrtzla7J+duwPOToIg42ChPQOQjspnSlp1V+Gjdged7+8UN5CRAV7a5EdFNwCjEaBR27b3W890TE7g24NAP/mMDXRWrGoFPQI9ls/MWO2dWFAar/xcOIImbbpA3zgAAAABJRU5ErkJggg==);\n",
       "        }\n",
       "    </style>\n",
       "    <div>\n",
       "        <a href=\"https://bokeh.org\" target=\"_blank\" class=\"bk-notebook-logo\"></a>\n",
       "        <span id=\"b0b2768a-c446-45cb-8fed-bb8223aaad02\">Loading BokehJS ...</span>\n",
       "    </div>\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "application/javascript": "(function(root) {\n  function now() {\n    return new Date();\n  }\n\n  const force = true;\n\n  if (typeof root._bokeh_onload_callbacks === \"undefined\" || force === true) {\n    root._bokeh_onload_callbacks = [];\n    root._bokeh_is_loading = undefined;\n  }\n\nconst JS_MIME_TYPE = 'application/javascript';\n  const HTML_MIME_TYPE = 'text/html';\n  const EXEC_MIME_TYPE = 'application/vnd.bokehjs_exec.v0+json';\n  const CLASS_NAME = 'output_bokeh rendered_html';\n\n  /**\n   * Render data to the DOM node\n   */\n  function render(props, node) {\n    const script = document.createElement(\"script\");\n    node.appendChild(script);\n  }\n\n  /**\n   * Handle when an output is cleared or removed\n   */\n  function handleClearOutput(event, handle) {\n    const cell = handle.cell;\n\n    const id = cell.output_area._bokeh_element_id;\n    const server_id = cell.output_area._bokeh_server_id;\n    // Clean up Bokeh references\n    if (id != null && id in Bokeh.index) {\n      Bokeh.index[id].model.document.clear();\n      delete Bokeh.index[id];\n    }\n\n    if (server_id !== undefined) {\n      // Clean up Bokeh references\n      const cmd_clean = \"from bokeh.io.state import curstate; print(curstate().uuid_to_server['\" + server_id + \"'].get_sessions()[0].document.roots[0]._id)\";\n      cell.notebook.kernel.execute(cmd_clean, {\n        iopub: {\n          output: function(msg) {\n            const id = msg.content.text.trim();\n            if (id in Bokeh.index) {\n              Bokeh.index[id].model.document.clear();\n              delete Bokeh.index[id];\n            }\n          }\n        }\n      });\n      // Destroy server and session\n      const cmd_destroy = \"import bokeh.io.notebook as ion; ion.destroy_server('\" + server_id + \"')\";\n      cell.notebook.kernel.execute(cmd_destroy);\n    }\n  }\n\n  /**\n   * Handle when a new output is added\n   */\n  function handleAddOutput(event, handle) {\n    const output_area = handle.output_area;\n    const output = handle.output;\n\n    // limit handleAddOutput to display_data with EXEC_MIME_TYPE content only\n    if ((output.output_type != \"display_data\") || (!Object.prototype.hasOwnProperty.call(output.data, EXEC_MIME_TYPE))) {\n      return\n    }\n\n    const toinsert = output_area.element.find(\".\" + CLASS_NAME.split(' ')[0]);\n\n    if (output.metadata[EXEC_MIME_TYPE][\"id\"] !== undefined) {\n      toinsert[toinsert.length - 1].firstChild.textContent = output.data[JS_MIME_TYPE];\n      // store reference to embed id on output_area\n      output_area._bokeh_element_id = output.metadata[EXEC_MIME_TYPE][\"id\"];\n    }\n    if (output.metadata[EXEC_MIME_TYPE][\"server_id\"] !== undefined) {\n      const bk_div = document.createElement(\"div\");\n      bk_div.innerHTML = output.data[HTML_MIME_TYPE];\n      const script_attrs = bk_div.children[0].attributes;\n      for (let i = 0; i < script_attrs.length; i++) {\n        toinsert[toinsert.length - 1].firstChild.setAttribute(script_attrs[i].name, script_attrs[i].value);\n        toinsert[toinsert.length - 1].firstChild.textContent = bk_div.children[0].textContent\n      }\n      // store reference to server id on output_area\n      output_area._bokeh_server_id = output.metadata[EXEC_MIME_TYPE][\"server_id\"];\n    }\n  }\n\n  function register_renderer(events, OutputArea) {\n\n    function append_mime(data, metadata, element) {\n      // create a DOM node to render to\n      const toinsert = this.create_output_subarea(\n        metadata,\n        CLASS_NAME,\n        EXEC_MIME_TYPE\n      );\n      this.keyboard_manager.register_events(toinsert);\n      // Render to node\n      const props = {data: data, metadata: metadata[EXEC_MIME_TYPE]};\n      render(props, toinsert[toinsert.length - 1]);\n      element.append(toinsert);\n      return toinsert\n    }\n\n    /* Handle when an output is cleared or removed */\n    events.on('clear_output.CodeCell', handleClearOutput);\n    events.on('delete.Cell', handleClearOutput);\n\n    /* Handle when a new output is added */\n    events.on('output_added.OutputArea', handleAddOutput);\n\n    /**\n     * Register the mime type and append_mime function with output_area\n     */\n    OutputArea.prototype.register_mime_type(EXEC_MIME_TYPE, append_mime, {\n      /* Is output safe? */\n      safe: true,\n      /* Index of renderer in `output_area.display_order` */\n      index: 0\n    });\n  }\n\n  // register the mime type if in Jupyter Notebook environment and previously unregistered\n  if (root.Jupyter !== undefined) {\n    const events = require('base/js/events');\n    const OutputArea = require('notebook/js/outputarea').OutputArea;\n\n    if (OutputArea.prototype.mime_types().indexOf(EXEC_MIME_TYPE) == -1) {\n      register_renderer(events, OutputArea);\n    }\n  }\n  if (typeof (root._bokeh_timeout) === \"undefined\" || force === true) {\n    root._bokeh_timeout = Date.now() + 5000;\n    root._bokeh_failed_load = false;\n  }\n\n  const NB_LOAD_WARNING = {'data': {'text/html':\n     \"<div style='background-color: #fdd'>\\n\"+\n     \"<p>\\n\"+\n     \"BokehJS does not appear to have successfully loaded. If loading BokehJS from CDN, this \\n\"+\n     \"may be due to a slow or bad network connection. Possible fixes:\\n\"+\n     \"</p>\\n\"+\n     \"<ul>\\n\"+\n     \"<li>re-rerun `output_notebook()` to attempt to load from CDN again, or</li>\\n\"+\n     \"<li>use INLINE resources instead, as so:</li>\\n\"+\n     \"</ul>\\n\"+\n     \"<code>\\n\"+\n     \"from bokeh.resources import INLINE\\n\"+\n     \"output_notebook(resources=INLINE)\\n\"+\n     \"</code>\\n\"+\n     \"</div>\"}};\n\n  function display_loaded() {\n    const el = document.getElementById(\"b0b2768a-c446-45cb-8fed-bb8223aaad02\");\n    if (el != null) {\n      el.textContent = \"BokehJS is loading...\";\n    }\n    if (root.Bokeh !== undefined) {\n      if (el != null) {\n        el.textContent = \"BokehJS \" + root.Bokeh.version + \" successfully loaded.\";\n      }\n    } else if (Date.now() < root._bokeh_timeout) {\n      setTimeout(display_loaded, 100)\n    }\n  }\n\n  function run_callbacks() {\n    try {\n      root._bokeh_onload_callbacks.forEach(function(callback) {\n        if (callback != null)\n          callback();\n      });\n    } finally {\n      delete root._bokeh_onload_callbacks\n    }\n    console.debug(\"Bokeh: all callbacks have finished\");\n  }\n\n  function load_libs(css_urls, js_urls, callback) {\n    if (css_urls == null) css_urls = [];\n    if (js_urls == null) js_urls = [];\n\n    root._bokeh_onload_callbacks.push(callback);\n    if (root._bokeh_is_loading > 0) {\n      console.debug(\"Bokeh: BokehJS is being loaded, scheduling callback at\", now());\n      return null;\n    }\n    if (js_urls == null || js_urls.length === 0) {\n      run_callbacks();\n      return null;\n    }\n    console.debug(\"Bokeh: BokehJS not loaded, scheduling load and callback at\", now());\n    root._bokeh_is_loading = css_urls.length + js_urls.length;\n\n    function on_load() {\n      root._bokeh_is_loading--;\n      if (root._bokeh_is_loading === 0) {\n        console.debug(\"Bokeh: all BokehJS libraries/stylesheets loaded\");\n        run_callbacks()\n      }\n    }\n\n    function on_error(url) {\n      console.error(\"failed to load \" + url);\n    }\n\n    for (let i = 0; i < css_urls.length; i++) {\n      const url = css_urls[i];\n      const element = document.createElement(\"link\");\n      element.onload = on_load;\n      element.onerror = on_error.bind(null, url);\n      element.rel = \"stylesheet\";\n      element.type = \"text/css\";\n      element.href = url;\n      console.debug(\"Bokeh: injecting link tag for BokehJS stylesheet: \", url);\n      document.body.appendChild(element);\n    }\n\n    for (let i = 0; i < js_urls.length; i++) {\n      const url = js_urls[i];\n      const element = document.createElement('script');\n      element.onload = on_load;\n      element.onerror = on_error.bind(null, url);\n      element.async = false;\n      element.src = url;\n      console.debug(\"Bokeh: injecting script tag for BokehJS library: \", url);\n      document.head.appendChild(element);\n    }\n  };\n\n  function inject_raw_css(css) {\n    const element = document.createElement(\"style\");\n    element.appendChild(document.createTextNode(css));\n    document.body.appendChild(element);\n  }\n\n  const js_urls = [\"https://cdnjs.cloudflare.com/ajax/libs/ace/1.4.11/ace.js\", \"https://cdnjs.cloudflare.com/ajax/libs/ace/1.4.11/ext-language_tools.js\", \"https://cdnjs.cloudflare.com/ajax/libs/ace/1.4.11/ext-modelist.js\", \"https://cdn.bokeh.org/bokeh/release/bokeh-3.2.0.min.js\", \"https://cdn.bokeh.org/bokeh/release/bokeh-gl-3.2.0.min.js\", \"https://cdn.bokeh.org/bokeh/release/bokeh-widgets-3.2.0.min.js\", \"https://cdn.bokeh.org/bokeh/release/bokeh-tables-3.2.0.min.js\", \"https://cdn.bokeh.org/bokeh/release/bokeh-mathjax-3.2.0.min.js\", \"https://unpkg.com/@holoviz/panel@1.1.0/dist/panel.min.js\"];\n  const css_urls = [];\n\n  const inline_js = [    function(Bokeh) {\n      Bokeh.set_log_level(\"info\");\n    },\nfunction(Bokeh) {\n    }\n  ];\n\n  function run_inline_js() {\n    if (root.Bokeh !== undefined || force === true) {\n          for (let i = 0; i < inline_js.length; i++) {\n      inline_js[i].call(root, root.Bokeh);\n    }\nif (force === true) {\n        display_loaded();\n      }} else if (Date.now() < root._bokeh_timeout) {\n      setTimeout(run_inline_js, 100);\n    } else if (!root._bokeh_failed_load) {\n      console.log(\"Bokeh: BokehJS failed to load within specified timeout.\");\n      root._bokeh_failed_load = true;\n    } else if (force !== true) {\n      const cell = $(document.getElementById(\"b0b2768a-c446-45cb-8fed-bb8223aaad02\")).parents('.cell').data().cell;\n      cell.output_area.append_execute_result(NB_LOAD_WARNING)\n    }\n  }\n\n  if (root._bokeh_is_loading === 0) {\n    console.debug(\"Bokeh: BokehJS loaded, going straight to plotting\");\n    run_inline_js();\n  } else {\n    load_libs(css_urls, js_urls, function() {\n      console.debug(\"Bokeh: BokehJS plotting callback run at\", now());\n      run_inline_js();\n    });\n  }\n}(window));",
      "application/vnd.bokehjs_load.v0+json": ""
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "application/javascript": "(function(root) {\n  function now() {\n    return new Date();\n  }\n\n  var force = true;\n  var py_version = '3.2.0'.replace('rc', '-rc.');\n  var is_dev = py_version.indexOf(\"+\") !== -1 || py_version.indexOf(\"-\") !== -1;\n  var reloading = false;\n  var Bokeh = root.Bokeh;\n  var bokeh_loaded = Bokeh != null && (Bokeh.version === py_version || (Bokeh.versions !== undefined && Bokeh.versions.has(py_version)));\n\n  if (typeof (root._bokeh_timeout) === \"undefined\" || force) {\n    root._bokeh_timeout = Date.now() + 5000;\n    root._bokeh_failed_load = false;\n  }\n\n  function run_callbacks() {\n    try {\n      root._bokeh_onload_callbacks.forEach(function(callback) {\n        if (callback != null)\n          callback();\n      });\n    } finally {\n      delete root._bokeh_onload_callbacks;\n    }\n    console.debug(\"Bokeh: all callbacks have finished\");\n  }\n\n  function load_libs(css_urls, js_urls, js_modules, js_exports, callback) {\n    if (css_urls == null) css_urls = [];\n    if (js_urls == null) js_urls = [];\n    if (js_modules == null) js_modules = [];\n    if (js_exports == null) js_exports = {};\n\n    root._bokeh_onload_callbacks.push(callback);\n\n    if (root._bokeh_is_loading > 0) {\n      console.debug(\"Bokeh: BokehJS is being loaded, scheduling callback at\", now());\n      return null;\n    }\n    if (js_urls.length === 0 && js_modules.length === 0 && Object.keys(js_exports).length === 0) {\n      run_callbacks();\n      return null;\n    }\n    if (!reloading) {\n      console.debug(\"Bokeh: BokehJS not loaded, scheduling load and callback at\", now());\n    }\n\n    function on_load() {\n      root._bokeh_is_loading--;\n      if (root._bokeh_is_loading === 0) {\n        console.debug(\"Bokeh: all BokehJS libraries/stylesheets loaded\");\n        run_callbacks()\n      }\n    }\n    window._bokeh_on_load = on_load\n\n    function on_error() {\n      console.error(\"failed to load \" + url);\n    }\n\n    var skip = [];\n    if (window.requirejs) {\n      window.requirejs.config({'packages': {}, 'paths': {'ace': '//cdnjs.cloudflare.com/ajax/libs/ace/1.4.7', 'jspanel': 'https://cdn.jsdelivr.net/npm/jspanel4@4.12.0/dist/jspanel', 'jspanel-modal': 'https://cdn.jsdelivr.net/npm/jspanel4@4.12.0/dist/extensions/modal/jspanel.modal', 'jspanel-tooltip': 'https://cdn.jsdelivr.net/npm/jspanel4@4.12.0/dist/extensions/tooltip/jspanel.tooltip', 'jspanel-hint': 'https://cdn.jsdelivr.net/npm/jspanel4@4.12.0/dist/extensions/hint/jspanel.hint', 'jspanel-layout': 'https://cdn.jsdelivr.net/npm/jspanel4@4.12.0/dist/extensions/layout/jspanel.layout', 'jspanel-contextmenu': 'https://cdn.jsdelivr.net/npm/jspanel4@4.12.0/dist/extensions/contextmenu/jspanel.contextmenu', 'jspanel-dock': 'https://cdn.jsdelivr.net/npm/jspanel4@4.12.0/dist/extensions/dock/jspanel.dock', 'gridstack': 'https://cdn.jsdelivr.net/npm/gridstack@7.2.3/dist/gridstack-all', 'notyf': 'https://cdn.jsdelivr.net/npm/notyf@3/notyf.min'}, 'shim': {'ace/ext-language_tools': {'deps': ['ace/ace']}, 'ace/ext-modelist': {'deps': ['ace/ace']}, 'jspanel': {'exports': 'jsPanel'}, 'gridstack': {'exports': 'GridStack'}}});\n      require([\"ace/ace\"], function(ace) {\n\twindow.ace = ace\n\ton_load()\n      })\n      require([\"ace/ext-language_tools\"], function() {\n\ton_load()\n      })\n      require([\"ace/ext-modelist\"], function() {\n\ton_load()\n      })\n      require([\"jspanel\"], function(jsPanel) {\n\twindow.jsPanel = jsPanel\n\ton_load()\n      })\n      require([\"jspanel-modal\"], function() {\n\ton_load()\n      })\n      require([\"jspanel-tooltip\"], function() {\n\ton_load()\n      })\n      require([\"jspanel-hint\"], function() {\n\ton_load()\n      })\n      require([\"jspanel-layout\"], function() {\n\ton_load()\n      })\n      require([\"jspanel-contextmenu\"], function() {\n\ton_load()\n      })\n      require([\"jspanel-dock\"], function() {\n\ton_load()\n      })\n      require([\"gridstack\"], function(GridStack) {\n\twindow.GridStack = GridStack\n\ton_load()\n      })\n      require([\"notyf\"], function() {\n\ton_load()\n      })\n      root._bokeh_is_loading = css_urls.length + 12;\n    } else {\n      root._bokeh_is_loading = css_urls.length + js_urls.length + js_modules.length + Object.keys(js_exports).length;\n    }\n\n    var existing_stylesheets = []\n    var links = document.getElementsByTagName('link')\n    for (var i = 0; i < links.length; i++) {\n      var link = links[i]\n      if (link.href != null) {\n\texisting_stylesheets.push(link.href)\n      }\n    }\n    for (var i = 0; i < css_urls.length; i++) {\n      var url = css_urls[i];\n      if (existing_stylesheets.indexOf(url) !== -1) {\n\ton_load()\n\tcontinue;\n      }\n      const element = document.createElement(\"link\");\n      element.onload = on_load;\n      element.onerror = on_error;\n      element.rel = \"stylesheet\";\n      element.type = \"text/css\";\n      element.href = url;\n      console.debug(\"Bokeh: injecting link tag for BokehJS stylesheet: \", url);\n      document.body.appendChild(element);\n    }    if (((window['ace'] !== undefined) && (!(window['ace'] instanceof HTMLElement))) || window.requirejs) {\n      var urls = ['https://cdnjs.cloudflare.com/ajax/libs/ace/1.4.11/ace.js', 'https://cdnjs.cloudflare.com/ajax/libs/ace/1.4.11/ext-language_tools.js', 'https://cdnjs.cloudflare.com/ajax/libs/ace/1.4.11/ext-modelist.js'];\n      for (var i = 0; i < urls.length; i++) {\n        skip.push(urls[i])\n      }\n    }    if (((window['jsPanel'] !== undefined) && (!(window['jsPanel'] instanceof HTMLElement))) || window.requirejs) {\n      var urls = ['https://cdn.holoviz.org/panel/1.1.0/dist/bundled/floatpanel/jspanel4@4.12.0/dist/jspanel.js', 'https://cdn.holoviz.org/panel/1.1.0/dist/bundled/floatpanel/jspanel4@4.12.0/dist/extensions/modal/jspanel.modal.js', 'https://cdn.holoviz.org/panel/1.1.0/dist/bundled/floatpanel/jspanel4@4.12.0/dist/extensions/tooltip/jspanel.tooltip.js', 'https://cdn.holoviz.org/panel/1.1.0/dist/bundled/floatpanel/jspanel4@4.12.0/dist/extensions/hint/jspanel.hint.js', 'https://cdn.holoviz.org/panel/1.1.0/dist/bundled/floatpanel/jspanel4@4.12.0/dist/extensions/layout/jspanel.layout.js', 'https://cdn.holoviz.org/panel/1.1.0/dist/bundled/floatpanel/jspanel4@4.12.0/dist/extensions/contextmenu/jspanel.contextmenu.js', 'https://cdn.holoviz.org/panel/1.1.0/dist/bundled/floatpanel/jspanel4@4.12.0/dist/extensions/dock/jspanel.dock.js'];\n      for (var i = 0; i < urls.length; i++) {\n        skip.push(urls[i])\n      }\n    }    if (((window['GridStack'] !== undefined) && (!(window['GridStack'] instanceof HTMLElement))) || window.requirejs) {\n      var urls = ['https://cdn.holoviz.org/panel/1.1.0/dist/bundled/gridstack/gridstack@7.2.3/dist/gridstack-all.js'];\n      for (var i = 0; i < urls.length; i++) {\n        skip.push(urls[i])\n      }\n    }    if (((window['Notyf'] !== undefined) && (!(window['Notyf'] instanceof HTMLElement))) || window.requirejs) {\n      var urls = ['https://cdn.holoviz.org/panel/1.1.0/dist/bundled/notificationarea/notyf@3/notyf.min.js'];\n      for (var i = 0; i < urls.length; i++) {\n        skip.push(urls[i])\n      }\n    }    var existing_scripts = []\n    var scripts = document.getElementsByTagName('script')\n    for (var i = 0; i < scripts.length; i++) {\n      var script = scripts[i]\n      if (script.src != null) {\n\texisting_scripts.push(script.src)\n      }\n    }\n    for (var i = 0; i < js_urls.length; i++) {\n      var url = js_urls[i];\n      if (skip.indexOf(url) !== -1 || existing_scripts.indexOf(url) !== -1) {\n\tif (!window.requirejs) {\n\t  on_load();\n\t}\n\tcontinue;\n      }\n      var element = document.createElement('script');\n      element.onload = on_load;\n      element.onerror = on_error;\n      element.async = false;\n      element.src = url;\n      console.debug(\"Bokeh: injecting script tag for BokehJS library: \", url);\n      document.head.appendChild(element);\n    }\n    for (var i = 0; i < js_modules.length; i++) {\n      var url = js_modules[i];\n      if (skip.indexOf(url) !== -1 || existing_scripts.indexOf(url) !== -1) {\n\tif (!window.requirejs) {\n\t  on_load();\n\t}\n\tcontinue;\n      }\n      var element = document.createElement('script');\n      element.onload = on_load;\n      element.onerror = on_error;\n      element.async = false;\n      element.src = url;\n      element.type = \"module\";\n      console.debug(\"Bokeh: injecting script tag for BokehJS library: \", url);\n      document.head.appendChild(element);\n    }\n    for (const name in js_exports) {\n      var url = js_exports[name];\n      if (skip.indexOf(url) >= 0 || root[name] != null) {\n\tif (!window.requirejs) {\n\t  on_load();\n\t}\n\tcontinue;\n      }\n      var element = document.createElement('script');\n      element.onerror = on_error;\n      element.async = false;\n      element.type = \"module\";\n      console.debug(\"Bokeh: injecting script tag for BokehJS library: \", url);\n      element.textContent = `\n      import ${name} from \"${url}\"\n      window.${name} = ${name}\n      window._bokeh_on_load()\n      `\n      document.head.appendChild(element);\n    }\n    if (!js_urls.length && !js_modules.length) {\n      on_load()\n    }\n  };\n\n  function inject_raw_css(css) {\n    const element = document.createElement(\"style\");\n    element.appendChild(document.createTextNode(css));\n    document.body.appendChild(element);\n  }\n\n  var js_urls = [\"https://cdnjs.cloudflare.com/ajax/libs/ace/1.4.11/ace.js\", \"https://cdnjs.cloudflare.com/ajax/libs/ace/1.4.11/ext-language_tools.js\", \"https://cdnjs.cloudflare.com/ajax/libs/ace/1.4.11/ext-modelist.js\", \"https://cdn.bokeh.org/bokeh/release/bokeh-3.2.0.min.js\", \"https://cdn.bokeh.org/bokeh/release/bokeh-gl-3.2.0.min.js\", \"https://cdn.bokeh.org/bokeh/release/bokeh-widgets-3.2.0.min.js\", \"https://cdn.bokeh.org/bokeh/release/bokeh-tables-3.2.0.min.js\", \"https://cdn.holoviz.org/panel/1.1.0/dist/panel.min.js\"];\n  var js_modules = [];\n  var js_exports = {};\n  var css_urls = [];\n  var inline_js = [    function(Bokeh) {\n      inject_raw_css(\"/*\\n ~ CML // Creative Machine Learning ~\\n mml.css : CSS styling information for Panel and Bokeh\\n \\n This file defines the main CSS styling information for the CML course\\n \\n Author               :  Philippe Esling\\n                        <esling@ircam.fr>\\n*/\\n\\nbody {\\n  display: flex;\\n  height: 100vh;\\n  margin: 0px;\\n  overflow-x: hidden;\\n  overflow-y: hidden;\\n}\\n\\n.bk-root .bk, .bk-root .bk:before, .bk-root .bk:after {\\n  font-family: \\\"Josefin Sans\\\";\\n}\\n\\nimg {\\n  max-width: 100%;\\n}\\n\\n#container {\\n  padding:0px;\\n  height:100vh;\\n  width: 100vw;\\n  max-width: 100vw;\\n}\\n\\n#sidebar .mdc-list {\\n  padding-left: 5px;\\n  padding-right: 5px;\\n}\\n\\n.mdc-drawer-app-content {\\n  flex: auto;\\n  position: relative;\\n  overflow: hidden;\\n}\\n\\n.mdc-drawer {\\n  background: #FAFAFA; /* GRAY 50 */\\n}\\n\\n.mdc-drawer-app-content {\\n  margin-left: 0 !important;\\n}\\n\\n.title-bar {\\n  display: contents;\\n  justify-content: center;\\n  align-content: center;\\n  width: 100%;\\n}\\n\\n.mdc-top-app-bar .bk-menu {\\n  color: black\\n}\\n\\n.app-header {\\n  display: contents;\\n  padding-left: 10px;\\n  font-size: 1.25em;\\n}\\n\\nimg.app-logo {\\n  padding-right: 10px;\\n  font-size: 28px;\\n  height: 30px;\\n  max-width: inherit;\\n  padding-top: 12px;\\n  padding-bottom: 6px;\\n}\\n\\n#app-title {\\n  padding-right: 12px;\\n  padding-left: 12px;\\n}\\n\\n.title {\\n  font-family: \\\"Josefin Sans\\\";\\n  color: #fff;\\n  text-decoration: none;\\n  text-decoration-line: none;\\n  text-decoration-style: initial;\\n  text-decoration-color: initial;\\n  font-weight: 400;\\n  font-size: 2em;\\n  line-height: 2em;\\n  white-space: nowrap;\\n}\\n\\n.main-content {\\n  overflow-y: scroll;\\n  overflow-x: auto;\\n}\\n\\n#header {\\n  position: absolute;\\n  z-index: 7;\\n}\\n\\n#header-items {\\n  width: 100%;\\n  margin-left:15px;\\n}\\n\\n.pn-busy-container {\\n  align-items: center;\\n  justify-content: center;\\n  display: flex;\\n}\\n\\n.mdc-drawer__content {\\n  overflow-x: hidden;\\n}\\n.mdc-drawer__content, .main-content {\\n  padding: 12px;\\n}\\n\\n.main-content {\\n  height: calc(100vh - 88px);\\n  max-height: calc(100vh - 88px);\\n  padding-right: 32px;\\n}\\n\\nbutton.mdc-button.mdc-card-button {\\n  color: transparent;\\n  height: 50px;\\n}\\n\\np.mdc-button {\\n  display: none;\\n}\\n\\ndiv.mdc-card {\\n  border-radius: 0px\\n}\\n\\n.mdc-card .card-header {\\n  display: flex;\\n}\\n\\n.mdc-card-title {\\n  font-family: \\\"Josefin Sans\\\";\\n  font-weight: bold;\\n  align-items: center;\\n  display: flex !important;\\n  position: relative !important;\\n}\\n\\n.mdc-card-title:nth-child(2) {\\n  margin-left: -1.4em;\\n}\\n\\n.pn-modal {\\n  overflow-y: scroll;\\n  width: 100%;\\n  display: none;\\n  position: absolute;\\n  top: 0;\\n  left: 0;\\n}\\n\\n.pn-modal-content {\\n  font-family: \\\"Josefin Sans\\\";\\n  background-color: #0e0e0e;\\n  margin: auto;\\n  margin-top: 25px;\\n  margin-bottom: 25px;\\n  padding: 15px 20px 20px 20px;\\n  border: 1px solid #888;\\n  width: 80% !important;\\n}\\n\\n.pn-modal-close {\\n  position: absolute;\\n  right: 25px;\\n  z-index: 100;\\n}\\n\\n.pn-modal-close:hover,\\n.pn-modal-close:focus {\\n  color: #000;\\n  text-decoration: none;\\n  cursor: pointer;\\n}\\n\\n.custom_button_bokeh button.bk-btn.bk-btn-default {\\n    font-size:48pt;\\n    background-color: #05b7ff;\\n    border-color: #05b7ff;\\n}\");\n    },    function(Bokeh) {\n      Bokeh.set_log_level(\"info\");\n    },\nfunction(Bokeh) {} // ensure no trailing comma for IE\n  ];\n\n  function run_inline_js() {\n    if ((root.Bokeh !== undefined) || (force === true)) {\n      for (var i = 0; i < inline_js.length; i++) {\n        inline_js[i].call(root, root.Bokeh);\n      }\n      // Cache old bokeh versions\n      if (Bokeh != undefined && !reloading) {\n\tvar NewBokeh = root.Bokeh;\n\tif (Bokeh.versions === undefined) {\n\t  Bokeh.versions = new Map();\n\t}\n\tif (NewBokeh.version !== Bokeh.version) {\n\t  Bokeh.versions.set(NewBokeh.version, NewBokeh)\n\t}\n\troot.Bokeh = Bokeh;\n      }} else if (Date.now() < root._bokeh_timeout) {\n      setTimeout(run_inline_js, 100);\n    } else if (!root._bokeh_failed_load) {\n      console.log(\"Bokeh: BokehJS failed to load within specified timeout.\");\n      root._bokeh_failed_load = true;\n    }\n    root._bokeh_is_initializing = false\n  }\n\n  function load_or_wait() {\n    // Implement a backoff loop that tries to ensure we do not load multiple\n    // versions of Bokeh and its dependencies at the same time.\n    // In recent versions we use the root._bokeh_is_initializing flag\n    // to determine whether there is an ongoing attempt to initialize\n    // bokeh, however for backward compatibility we also try to ensure\n    // that we do not start loading a newer (Panel>=1.0 and Bokeh>3) version\n    // before older versions are fully initialized.\n    if (root._bokeh_is_initializing && Date.now() > root._bokeh_timeout) {\n      root._bokeh_is_initializing = false;\n      root._bokeh_onload_callbacks = undefined;\n      console.log(\"Bokeh: BokehJS was loaded multiple times but one version failed to initialize.\");\n      load_or_wait();\n    } else if (root._bokeh_is_initializing || (typeof root._bokeh_is_initializing === \"undefined\" && root._bokeh_onload_callbacks !== undefined)) {\n      setTimeout(load_or_wait, 100);\n    } else {\n      Bokeh = root.Bokeh;\n      bokeh_loaded = Bokeh != null && (Bokeh.version === py_version || (Bokeh.versions !== undefined && Bokeh.versions.has(py_version)));\n      root._bokeh_is_initializing = true\n      root._bokeh_onload_callbacks = []\n      if (!reloading && (!bokeh_loaded || is_dev)) {\n\troot.Bokeh = undefined;\n      }\n      load_libs(css_urls, js_urls, js_modules, js_exports, function() {\n\tconsole.debug(\"Bokeh: BokehJS plotting callback run at\", now());\n\trun_inline_js();\n      });\n    }\n  }\n  // Give older versions of the autoload script a head-start to ensure\n  // they initialize before we start loading newer version.\n  setTimeout(load_or_wait, 100)\n}(window));",
      "application/vnd.holoviews_load.v0+json": ""
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "application/javascript": "\nif ((window.PyViz === undefined) || (window.PyViz instanceof HTMLElement)) {\n  window.PyViz = {comms: {}, comm_status:{}, kernels:{}, receivers: {}, plot_index: []}\n}\n\n\n    function JupyterCommManager() {\n    }\n\n    JupyterCommManager.prototype.register_target = function(plot_id, comm_id, msg_handler) {\n      if (window.comm_manager || ((window.Jupyter !== undefined) && (Jupyter.notebook.kernel != null))) {\n        var comm_manager = window.comm_manager || Jupyter.notebook.kernel.comm_manager;\n        comm_manager.register_target(comm_id, function(comm) {\n          comm.on_msg(msg_handler);\n        });\n      } else if ((plot_id in window.PyViz.kernels) && (window.PyViz.kernels[plot_id])) {\n        window.PyViz.kernels[plot_id].registerCommTarget(comm_id, function(comm) {\n          comm.onMsg = msg_handler;\n        });\n      } else if (typeof google != 'undefined' && google.colab.kernel != null) {\n        google.colab.kernel.comms.registerTarget(comm_id, (comm) => {\n          var messages = comm.messages[Symbol.asyncIterator]();\n          function processIteratorResult(result) {\n            var message = result.value;\n            console.log(message)\n            var content = {data: message.data, comm_id};\n            var buffers = []\n            for (var buffer of message.buffers || []) {\n              buffers.push(new DataView(buffer))\n            }\n            var metadata = message.metadata || {};\n            var msg = {content, buffers, metadata}\n            msg_handler(msg);\n            return messages.next().then(processIteratorResult);\n          }\n          return messages.next().then(processIteratorResult);\n        })\n      }\n    }\n\n    JupyterCommManager.prototype.get_client_comm = function(plot_id, comm_id, msg_handler) {\n      if (comm_id in window.PyViz.comms) {\n        return window.PyViz.comms[comm_id];\n      } else if (window.comm_manager || ((window.Jupyter !== undefined) && (Jupyter.notebook.kernel != null))) {\n        var comm_manager = window.comm_manager || Jupyter.notebook.kernel.comm_manager;\n        var comm = comm_manager.new_comm(comm_id, {}, {}, {}, comm_id);\n        if (msg_handler) {\n          comm.on_msg(msg_handler);\n        }\n      } else if ((plot_id in window.PyViz.kernels) && (window.PyViz.kernels[plot_id])) {\n        var comm = window.PyViz.kernels[plot_id].connectToComm(comm_id);\n        comm.open();\n        if (msg_handler) {\n          comm.onMsg = msg_handler;\n        }\n      } else if (typeof google != 'undefined' && google.colab.kernel != null) {\n        var comm_promise = google.colab.kernel.comms.open(comm_id)\n        comm_promise.then((comm) => {\n          window.PyViz.comms[comm_id] = comm;\n          if (msg_handler) {\n            var messages = comm.messages[Symbol.asyncIterator]();\n            function processIteratorResult(result) {\n              var message = result.value;\n              var content = {data: message.data};\n              var metadata = message.metadata || {comm_id};\n              var msg = {content, metadata}\n              msg_handler(msg);\n              return messages.next().then(processIteratorResult);\n            }\n            return messages.next().then(processIteratorResult);\n          }\n        }) \n        var sendClosure = (data, metadata, buffers, disposeOnDone) => {\n          return comm_promise.then((comm) => {\n            comm.send(data, metadata, buffers, disposeOnDone);\n          });\n        };\n        var comm = {\n          send: sendClosure\n        };\n      }\n      window.PyViz.comms[comm_id] = comm;\n      return comm;\n    }\n    window.PyViz.comm_manager = new JupyterCommManager();\n    \n\n\nvar JS_MIME_TYPE = 'application/javascript';\nvar HTML_MIME_TYPE = 'text/html';\nvar EXEC_MIME_TYPE = 'application/vnd.holoviews_exec.v0+json';\nvar CLASS_NAME = 'output';\n\n/**\n * Render data to the DOM node\n */\nfunction render(props, node) {\n  var div = document.createElement(\"div\");\n  var script = document.createElement(\"script\");\n  node.appendChild(div);\n  node.appendChild(script);\n}\n\n/**\n * Handle when a new output is added\n */\nfunction handle_add_output(event, handle) {\n  var output_area = handle.output_area;\n  var output = handle.output;\n  if ((output.data == undefined) || (!output.data.hasOwnProperty(EXEC_MIME_TYPE))) {\n    return\n  }\n  var id = output.metadata[EXEC_MIME_TYPE][\"id\"];\n  var toinsert = output_area.element.find(\".\" + CLASS_NAME.split(' ')[0]);\n  if (id !== undefined) {\n    var nchildren = toinsert.length;\n    var html_node = toinsert[nchildren-1].children[0];\n    html_node.innerHTML = output.data[HTML_MIME_TYPE];\n    var scripts = [];\n    var nodelist = html_node.querySelectorAll(\"script\");\n    for (var i in nodelist) {\n      if (nodelist.hasOwnProperty(i)) {\n        scripts.push(nodelist[i])\n      }\n    }\n\n    scripts.forEach( function (oldScript) {\n      var newScript = document.createElement(\"script\");\n      var attrs = [];\n      var nodemap = oldScript.attributes;\n      for (var j in nodemap) {\n        if (nodemap.hasOwnProperty(j)) {\n          attrs.push(nodemap[j])\n        }\n      }\n      attrs.forEach(function(attr) { newScript.setAttribute(attr.name, attr.value) });\n      newScript.appendChild(document.createTextNode(oldScript.innerHTML));\n      oldScript.parentNode.replaceChild(newScript, oldScript);\n    });\n    if (JS_MIME_TYPE in output.data) {\n      toinsert[nchildren-1].children[1].textContent = output.data[JS_MIME_TYPE];\n    }\n    output_area._hv_plot_id = id;\n    if ((window.Bokeh !== undefined) && (id in Bokeh.index)) {\n      window.PyViz.plot_index[id] = Bokeh.index[id];\n    } else {\n      window.PyViz.plot_index[id] = null;\n    }\n  } else if (output.metadata[EXEC_MIME_TYPE][\"server_id\"] !== undefined) {\n    var bk_div = document.createElement(\"div\");\n    bk_div.innerHTML = output.data[HTML_MIME_TYPE];\n    var script_attrs = bk_div.children[0].attributes;\n    for (var i = 0; i < script_attrs.length; i++) {\n      toinsert[toinsert.length - 1].childNodes[1].setAttribute(script_attrs[i].name, script_attrs[i].value);\n    }\n    // store reference to server id on output_area\n    output_area._bokeh_server_id = output.metadata[EXEC_MIME_TYPE][\"server_id\"];\n  }\n}\n\n/**\n * Handle when an output is cleared or removed\n */\nfunction handle_clear_output(event, handle) {\n  var id = handle.cell.output_area._hv_plot_id;\n  var server_id = handle.cell.output_area._bokeh_server_id;\n  if (((id === undefined) || !(id in PyViz.plot_index)) && (server_id !== undefined)) { return; }\n  var comm = window.PyViz.comm_manager.get_client_comm(\"hv-extension-comm\", \"hv-extension-comm\", function () {});\n  if (server_id !== null) {\n    comm.send({event_type: 'server_delete', 'id': server_id});\n    return;\n  } else if (comm !== null) {\n    comm.send({event_type: 'delete', 'id': id});\n  }\n  delete PyViz.plot_index[id];\n  if ((window.Bokeh !== undefined) & (id in window.Bokeh.index)) {\n    var doc = window.Bokeh.index[id].model.document\n    doc.clear();\n    const i = window.Bokeh.documents.indexOf(doc);\n    if (i > -1) {\n      window.Bokeh.documents.splice(i, 1);\n    }\n  }\n}\n\n/**\n * Handle kernel restart event\n */\nfunction handle_kernel_cleanup(event, handle) {\n  delete PyViz.comms[\"hv-extension-comm\"];\n  window.PyViz.plot_index = {}\n}\n\n/**\n * Handle update_display_data messages\n */\nfunction handle_update_output(event, handle) {\n  handle_clear_output(event, {cell: {output_area: handle.output_area}})\n  handle_add_output(event, handle)\n}\n\nfunction register_renderer(events, OutputArea) {\n  function append_mime(data, metadata, element) {\n    // create a DOM node to render to\n    var toinsert = this.create_output_subarea(\n    metadata,\n    CLASS_NAME,\n    EXEC_MIME_TYPE\n    );\n    this.keyboard_manager.register_events(toinsert);\n    // Render to node\n    var props = {data: data, metadata: metadata[EXEC_MIME_TYPE]};\n    render(props, toinsert[0]);\n    element.append(toinsert);\n    return toinsert\n  }\n\n  events.on('output_added.OutputArea', handle_add_output);\n  events.on('output_updated.OutputArea', handle_update_output);\n  events.on('clear_output.CodeCell', handle_clear_output);\n  events.on('delete.Cell', handle_clear_output);\n  events.on('kernel_ready.Kernel', handle_kernel_cleanup);\n\n  OutputArea.prototype.register_mime_type(EXEC_MIME_TYPE, append_mime, {\n    safe: true,\n    index: 0\n  });\n}\n\nif (window.Jupyter !== undefined) {\n  try {\n    var events = require('base/js/events');\n    var OutputArea = require('notebook/js/outputarea').OutputArea;\n    if (OutputArea.prototype.mime_types().indexOf(EXEC_MIME_TYPE) == -1) {\n      register_renderer(events, OutputArea);\n    }\n  } catch(err) {\n  }\n}\n",
      "application/vnd.holoviews_load.v0+json": ""
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/html": [
       "<style>*[data-root-id],\n",
       "*[data-root-id] > * {\n",
       "  box-sizing: border-box;\n",
       "  font-family: var(--jp-ui-font-family);\n",
       "  font-size: var(--jp-ui-font-size1);\n",
       "  color: var(--vscode-editor-foreground, var(--jp-ui-font-color1));\n",
       "}\n",
       "\n",
       "/* Override VSCode background color */\n",
       ".cell-output-ipywidget-background:has(> .cell-output-ipywidget-background\n",
       "    > .lm-Widget\n",
       "    > *[data-root-id]),\n",
       ".cell-output-ipywidget-background:has(> .lm-Widget > *[data-root-id]) {\n",
       "  background-color: transparent !important;\n",
       "}\n",
       "</style>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "application/vnd.holoviews_exec.v0+json": "",
      "text/html": [
       "<div id='c8fec78b-cc3a-4004-89be-6da21051076a'>\n",
       "  <div id=\"b9a5fb27-3944-4477-b65c-ab8828926011\" data-root-id=\"c8fec78b-cc3a-4004-89be-6da21051076a\" style=\"display: contents;\"></div>\n",
       "</div>\n",
       "<script type=\"application/javascript\">(function(root) {\n",
       "  var docs_json = {\"d32677ed-0887-4a3b-ad43-f27c56188ece\":{\"version\":\"3.2.0\",\"title\":\"Bokeh Application\",\"roots\":[{\"type\":\"object\",\"name\":\"panel.models.browser.BrowserInfo\",\"id\":\"c8fec78b-cc3a-4004-89be-6da21051076a\"},{\"type\":\"object\",\"name\":\"panel.models.comm_manager.CommManager\",\"id\":\"7a0e676c-42da-4c1d-ae8c-e1be69ff3124\",\"attributes\":{\"plot_id\":\"c8fec78b-cc3a-4004-89be-6da21051076a\",\"comm_id\":\"6bf84bd5ff644d8aaf5dd5afc924e9c8\",\"client_comm_id\":\"47e78c5ad85f4a97814128bb258960cd\"}}],\"defs\":[{\"type\":\"model\",\"name\":\"ReactiveHTML1\"},{\"type\":\"model\",\"name\":\"FlexBox1\",\"properties\":[{\"name\":\"align_content\",\"kind\":\"Any\",\"default\":\"flex-start\"},{\"name\":\"align_items\",\"kind\":\"Any\",\"default\":\"flex-start\"},{\"name\":\"flex_direction\",\"kind\":\"Any\",\"default\":\"row\"},{\"name\":\"flex_wrap\",\"kind\":\"Any\",\"default\":\"wrap\"},{\"name\":\"justify_content\",\"kind\":\"Any\",\"default\":\"flex-start\"}]},{\"type\":\"model\",\"name\":\"FloatPanel1\",\"properties\":[{\"name\":\"config\",\"kind\":\"Any\",\"default\":{\"type\":\"map\"}},{\"name\":\"contained\",\"kind\":\"Any\",\"default\":true},{\"name\":\"position\",\"kind\":\"Any\",\"default\":\"right-top\"},{\"name\":\"offsetx\",\"kind\":\"Any\",\"default\":null},{\"name\":\"offsety\",\"kind\":\"Any\",\"default\":null},{\"name\":\"theme\",\"kind\":\"Any\",\"default\":\"primary\"},{\"name\":\"status\",\"kind\":\"Any\",\"default\":\"normalized\"}]},{\"type\":\"model\",\"name\":\"GridStack1\",\"properties\":[{\"name\":\"mode\",\"kind\":\"Any\",\"default\":\"warn\"},{\"name\":\"ncols\",\"kind\":\"Any\",\"default\":null},{\"name\":\"nrows\",\"kind\":\"Any\",\"default\":null},{\"name\":\"allow_resize\",\"kind\":\"Any\",\"default\":true},{\"name\":\"allow_drag\",\"kind\":\"Any\",\"default\":true},{\"name\":\"state\",\"kind\":\"Any\",\"default\":[]}]},{\"type\":\"model\",\"name\":\"drag1\",\"properties\":[{\"name\":\"slider_width\",\"kind\":\"Any\",\"default\":5},{\"name\":\"slider_color\",\"kind\":\"Any\",\"default\":\"black\"},{\"name\":\"value\",\"kind\":\"Any\",\"default\":50}]},{\"type\":\"model\",\"name\":\"click1\",\"properties\":[{\"name\":\"terminal_output\",\"kind\":\"Any\",\"default\":\"\"},{\"name\":\"debug_name\",\"kind\":\"Any\",\"default\":\"\"},{\"name\":\"clears\",\"kind\":\"Any\",\"default\":0}]},{\"type\":\"model\",\"name\":\"FastWrapper1\",\"properties\":[{\"name\":\"object\",\"kind\":\"Any\",\"default\":null},{\"name\":\"style\",\"kind\":\"Any\",\"default\":null}]},{\"type\":\"model\",\"name\":\"NotificationAreaBase1\",\"properties\":[{\"name\":\"position\",\"kind\":\"Any\",\"default\":\"bottom-right\"},{\"name\":\"_clear\",\"kind\":\"Any\",\"default\":0}]},{\"type\":\"model\",\"name\":\"NotificationArea1\",\"properties\":[{\"name\":\"notifications\",\"kind\":\"Any\",\"default\":[]},{\"name\":\"position\",\"kind\":\"Any\",\"default\":\"bottom-right\"},{\"name\":\"_clear\",\"kind\":\"Any\",\"default\":0},{\"name\":\"types\",\"kind\":\"Any\",\"default\":[{\"type\":\"map\",\"entries\":[[\"type\",\"warning\"],[\"background\",\"#ffc107\"],[\"icon\",{\"type\":\"map\",\"entries\":[[\"className\",\"fas fa-exclamation-triangle\"],[\"tagName\",\"i\"],[\"color\",\"white\"]]}]]},{\"type\":\"map\",\"entries\":[[\"type\",\"info\"],[\"background\",\"#007bff\"],[\"icon\",{\"type\":\"map\",\"entries\":[[\"className\",\"fas fa-info-circle\"],[\"tagName\",\"i\"],[\"color\",\"white\"]]}]]}]}]},{\"type\":\"model\",\"name\":\"Notification\",\"properties\":[{\"name\":\"background\",\"kind\":\"Any\",\"default\":null},{\"name\":\"duration\",\"kind\":\"Any\",\"default\":3000},{\"name\":\"icon\",\"kind\":\"Any\",\"default\":null},{\"name\":\"message\",\"kind\":\"Any\",\"default\":\"\"},{\"name\":\"notification_type\",\"kind\":\"Any\",\"default\":null},{\"name\":\"_destroyed\",\"kind\":\"Any\",\"default\":false}]},{\"type\":\"model\",\"name\":\"TemplateActions1\",\"properties\":[{\"name\":\"open_modal\",\"kind\":\"Any\",\"default\":0},{\"name\":\"close_modal\",\"kind\":\"Any\",\"default\":0}]},{\"type\":\"model\",\"name\":\"BootstrapTemplateActions1\",\"properties\":[{\"name\":\"open_modal\",\"kind\":\"Any\",\"default\":0},{\"name\":\"close_modal\",\"kind\":\"Any\",\"default\":0}]},{\"type\":\"model\",\"name\":\"MaterialTemplateActions1\",\"properties\":[{\"name\":\"open_modal\",\"kind\":\"Any\",\"default\":0},{\"name\":\"close_modal\",\"kind\":\"Any\",\"default\":0}]}]}};\n",
       "  var render_items = [{\"docid\":\"d32677ed-0887-4a3b-ad43-f27c56188ece\",\"roots\":{\"c8fec78b-cc3a-4004-89be-6da21051076a\":\"b9a5fb27-3944-4477-b65c-ab8828926011\"},\"root_ids\":[\"c8fec78b-cc3a-4004-89be-6da21051076a\"]}];\n",
       "  var docs = Object.values(docs_json)\n",
       "  if (!docs) {\n",
       "    return\n",
       "  }\n",
       "  const py_version = docs[0].version.replace('rc', '-rc.')\n",
       "  const is_dev = py_version.indexOf(\"+\") !== -1 || py_version.indexOf(\"-\") !== -1\n",
       "  function embed_document(root) {\n",
       "    var Bokeh = get_bokeh(root)\n",
       "    Bokeh.embed.embed_items_notebook(docs_json, render_items);\n",
       "    for (const render_item of render_items) {\n",
       "      for (const root_id of render_item.root_ids) {\n",
       "\tconst id_el = document.getElementById(root_id)\n",
       "\tif (id_el.children.length && (id_el.children[0].className === 'bk-root')) {\n",
       "\t  const root_el = id_el.children[0]\n",
       "\t  root_el.id = root_el.id + '-rendered'\n",
       "\t}\n",
       "      }\n",
       "    }\n",
       "  }\n",
       "  function get_bokeh(root) {\n",
       "    if (root.Bokeh === undefined) {\n",
       "      return null\n",
       "    } else if (root.Bokeh.version !== py_version && !is_dev) {\n",
       "      if (root.Bokeh.versions === undefined || !root.Bokeh.versions.has(py_version)) {\n",
       "\treturn null\n",
       "      }\n",
       "      return root.Bokeh.versions.get(py_version);\n",
       "    } else if (root.Bokeh.version === py_version) {\n",
       "      return root.Bokeh\n",
       "    }\n",
       "    return null\n",
       "  }\n",
       "  function is_loaded(root) {\n",
       "    var Bokeh = get_bokeh(root)\n",
       "    return (Bokeh != null && Bokeh.Panel !== undefined)\n",
       "  }\n",
       "  if (is_loaded(root)) {\n",
       "    embed_document(root);\n",
       "  } else {\n",
       "    var attempts = 0;\n",
       "    var timer = setInterval(function(root) {\n",
       "      if (is_loaded(root)) {\n",
       "        clearInterval(timer);\n",
       "        embed_document(root);\n",
       "      } else if (document.readyState == \"complete\") {\n",
       "        attempts++;\n",
       "        if (attempts > 200) {\n",
       "          clearInterval(timer);\n",
       "\t  var Bokeh = get_bokeh(root)\n",
       "\t  if (Bokeh == null || Bokeh.Panel == null) {\n",
       "            console.warn(\"Panel: ERROR: Unable to run Panel code because Bokeh or Panel library is missing\");\n",
       "\t  } else {\n",
       "\t    console.warn(\"Panel: WARNING: Attempting to render but not all required libraries could be resolved.\")\n",
       "\t    embed_document(root)\n",
       "\t  }\n",
       "        }\n",
       "      }\n",
       "    }, 25, root)\n",
       "  }\n",
       "})(window);</script>"
      ]
     },
     "metadata": {
      "application/vnd.holoviews_exec.v0+json": {
       "id": "c8fec78b-cc3a-4004-89be-6da21051076a"
      }
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "import numpy as np\n",
    "import pandas as pd\n",
    "import torch\n",
    "import torch.nn as nn\n",
    "import torchvision\n",
    "from cml.plot import initialize_bokeh\n",
    "from cml.panel import initialize_panel\n",
    "from jupyterthemes.stylefx import set_nb_theme\n",
    "from bokeh.io import show\n",
    "initialize_bokeh()\n",
    "initialize_panel()\n",
    "set_nb_theme(\"onedork\")\n",
    "rng = np.random.RandomState(1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "iYn4MdZnKCey"
   },
   "source": [
    "### Load the dataset\n",
    "\n",
    "To start with a pragmatic and simple to understand example, we  will try to train the basic AE using the Fashion MNIST dataset. This dataset contains images of size 28x28 pixels, with different pieces of clothing. The following code allows to load (and eventually download) the dataset, by using the `torchvision.datasets` module. We also plot some randomly selected test examples"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {
    "id": "YZm503-I_tji"
   },
   "outputs": [],
   "source": [
    "import matplotlib\n",
    "dataset_dir = './data'\n",
    "# Going to use 80%/20% split for train/valid\n",
    "valid_ratio = 0.2\n",
    "# Load the dataset for the training/validation sets\n",
    "train_valid_dataset = torchvision.datasets.FashionMNIST(root=dataset_dir, train=True, transform=torchvision.transforms.ToTensor(), download=True)\n",
    "# Split it into training and validation sets\n",
    "nb_train = int((1.0 - valid_ratio) * len(train_valid_dataset))\n",
    "nb_valid =  int(valid_ratio * len(train_valid_dataset))\n",
    "train_dataset, valid_dataset = torch.utils.data.dataset.random_split(train_valid_dataset, [nb_train, nb_valid])\n",
    "# Load the test set\n",
    "test_dataset = torchvision.datasets.FashionMNIST(root=dataset_dir, transform=torchvision.transforms.ToTensor(),train=False)\n",
    "# Prepare \n",
    "num_threads = 4     # Loading the dataset is using 4 CPU threads\n",
    "batch_size  = 128   # Using minibatches of 128 samples\n",
    "train_loader = torch.utils.data.DataLoader(dataset=train_dataset, batch_size=batch_size, num_workers=num_threads)\n",
    "valid_loader = torch.utils.data.DataLoader(dataset=valid_dataset, batch_size=batch_size, shuffle=False, num_workers=num_threads)\n",
    "test_loader = torch.utils.data.DataLoader(dataset=test_dataset,batch_size=batch_size,shuffle=False,num_workers=num_threads)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here, we are going to check the properties of our different sets and also plot some random examples, in order to better understand what type of data we will be working with."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The train set contains 48000 images, in 375 batches\n",
      "The validation set contains 12000 images, in 94 batches\n",
      "The test set contains 10000 images, in 79 batches\n"
     ]
    },
    {
     "data": {
      "image/png": "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pUqVZPr06ZH6qY737HPLI0eOyIQJE6RFixZSrlw58wZOgXBFnIi4MD/GsGHDnIi4CRMmRGpr1651IuLOPvtsl56e7qpWreoyMjLckCFD3AMPPOCcc27lypUuLS3NiYhr0KCBGzRokDvvvPNchQoVnIi4xx57LPA88+bNc+XLl3ci4tq0aeMuueQSd9FFF7lWrVo5EXEzZsyI9J06daorVaqUi4uLc+ecc44bOXKku+CCC1zjxo2diLi1a9fmyWuEgnGysfnjjz86EXFly5Z1u3btCvzbiBEjXJkyZVz79u1dRkaGy8jIcA0aNHAi4urUqeM2bdqkHu+JJ55wIuJKlSrlevbs6UaOHOkaNmzoqlat6q644gonIu6ll16KwU+JWBgzZowTEXf//fcH6i+99JITETdy5EhXuXJl17BhQzdixAjXt29f9+GHHzrnnPvjH//oRMSVKVPG9e7d240YMcLVrVvXiYhr1qyZy8zMNJ8r59yUk4i4+vXrB2pPP/20ExFXunRp1717dzdq1CjXp0+fyPP47r77biciLj4+3nXt2tUNGzbMNW3a1ImIa9y48Qn36Ve/+pWLi4tzZ511lhs5cqQ766yz3O7du0/txUTMMdch1iZMmOBExKWlpbmtW7eG2qZ+/fpORNydd97p4uPjXd++fd3gwYNdrVq1nIi4c88912VlZQW2OdF8mP1Y11xzjStbtqw7//zz3YgRI9zgwYPdc8895/r16xeZz8aMGRP57913382jVwB5iWMsx9jCgutY5LR7925Xvnx5Fx8f73bs2OGcc65Lly5ORNzUqVPNbXJzrOvRo4d6jzIzM116eroTEXffffcF+p9oHtu6datr06aNExGXnJzs+vfv7y688EKXlJTkRMTddNNNoX/27Pl39OjRLikpyTVs2NCNHDnSde/e3cXFxbm4uDj34osvqu0mTZrkSpcu7UTEde3a1Y0cOdI1a9bMiYirXbu2W758udrmmmuucSLiypcv7/r37++GDRvmatSo4UTEde7c2R04cCDws2eP6X79+gWO8du2bQv98xVmjDvGXWGXX9cBBw8edL169XIi4qpVq+b69OnjBg4cGNnm4osvdsePHw9sc6rXs9nH7h49egTq7733nitfvryrUaOGmzt3bqSem/Ge/VpdeOGFrmLFiq5///5u+PDh7rrrrgv12sVaibkJ8fvf/96JiBs1alSklj0Asj/4/hckx44dc2eeeaYTEffoo48GBtzq1atdw4YNXenSpd33338fqWd/CfL444+rfVi+fLnbvHlzpN29e3cnIu7tt99WfefOnev27t0b9edC4WWNzX379rmvvvrKdezY0YmI+/Wvf622mz59urpgPH78uHvwwQediLgrr7wy8G9r1qxx8fHxLj4+3k2fPj1SP3r0qLvyyisj+8EXc0VHtC9Isg84x44dC/z73LlzXalSpVxiYqKbM2dOpH748GE3fPhwJyJu6NCh5nOdyhck9erVc3Fxce67774L1LOystTjvPnmm05E3BlnnOFWr14d6Hvfffc5EXEjRoww90lE3Ouvv27uFwoP5jrE2po1a1xCQoITEVepUiU3ZswY99xzz7kFCxaoeTBb9sVHcnKyW7FiRaS+bds216RJEyci7vPPPw9sE+0mRI0aNdySJUvUc82YMcOJiBszZsxp/6yIPY6xHGMLC65jkdPzzz/vRMQNGjQoUvv73//uRMQNHz7c3CY3xzr/y+C1a9e6Jk2auLi4OPfkk0+q5zjRPNa/f38nIu6WW25xhw8fjtQzMzMj538ff/xxqJ895/x7xRVXuKNHj0b+7YMPPnClS5d2FSpUcBs3bozU169f7xISElzp0qXd+++/H6kfP37c3XrrrU5EXMeOHQPP8/bbbzsRcSkpKW7VqlWR+u7du123bt2ciLjbb7891M9fXDDuGHeFXX5dB9xwww2R86acv5Sxd+/eyLh75plnAtuc6vWsdRPipZdecqVLl3ZpaWnqBlZuxnv2mG7SpElg7BYWJeYmxD/+8Q8nIu6CCy6I1HKevPkn+s459+6775oXFNmmTJmivly58MILnYi4RYsWRd2nli1bOhHht46KqeyxZf1XqVIl99RTT6m7r9Gkpqa66tWrB2r33nuvExE3btw41X/Xrl0uMTGRL+aKmGhfkNSsWTPw2xLZsi8e77nnHvVvW7dudQkJCa5UqVJu/fr16rlO5QuShIQEV7Vq1VA/S9u2bZ2IBC5ys2VlZbn09HRXunTpwG91ZO/TgAEDQj0HChZzHfLDZ599FvmN3pz/ValSxV1//fWBL8ec+9/Fx3PPPace6/HHHzfn2Gg3IfzfGs7GTYiihWMsx9jCgutY5JT9Je1bb70VqW3fvt2VLVvWlS9f3nytc3Osy/ll8JIlS1xKSoorU6aMmzx5srlf1jy2cOFCJyLurLPOUr8Z7JxzCxYscCL//c3hMLLn38TERLdz50717yNGjHAi4n73u99Fatk3WnPenMt2+PBhl5KS4kTEzZo1K1LPvnn27LPPqm0WL17s4uLiXGJiojt06NBJf/7ihHHHuCsKYn0dsHXrVle2bFmXlpbmDh48qLbZsmWLi4+Pd23atAm9z9b1rH8T4k9/+pOLi4tzzZs3d+vWrQv0ze14z35tcn6mC5MSkQkhIpG15bLXBcupTp060rFjR1X/9NNPRURkyJAh5mOee+65IiIyd+7cSK1Dhw4iInLjjTfKzJkzzXXD/L6XX365fPfdd5KVlRXmR0ERM2bMmMh/I0eOlM6dO8uBAwdkwoQJ8sknn5jb7NixQ1566SW5/fbbZdy4cTJ27FgZO3asHD16VHbs2CE7d+6M9J09e7aIiAwfPlw9TpUqVaRv376x+cFQYM4//3wzOPWrr74SEZHLLrtM/VutWrWkb9++kpWVFRkzudWhQwfZtWuXjBs37qRhwz///LMsXrxYmjZtKmeccYb697i4OOnatascP35c5s+fr/794osvPq39RP5irkMs9e7dW3744QeZMmWKXHfdddK+fXspU6aM7N69W5555hlJT0+XlStXqu2scdGsWTMREbW+eTTMSSUDx1gUNlzHFn/r16+XL7/8UqpUqSIDBw6M1KtXry79+/eXw4cPy1tvvXXC7XNzrJszZ450795ddu3aJe+++645t51I9vjKyMiQUqX0V0rZa5fnHF9h9O3bV6pWrarqo0aNEpH/zcM5/9/a73LlykXOF7P7HT16VObMmXPCbdq0aSNt2rSR/fv3y6JFi05pv4sqxt1/Me4Kv1hfB8ycOVOOHj0qF1xwgSQkJKhtkpOTpWnTpvL999/LoUOHAv92KtezOd17771y++23S7t27eSrr76SevXqBf79dMZ7XFxc4DNdmJQp6B3IL9u3bxcRkWrVqql/89/sbNmhL5dddtlJJ8fsxxYRufPOO2XWrFkyc+ZM6dWrlyQmJkrnzp1lwIABMnbs2EhAp4jIH//4R/n+++/lgw8+kA8++ECqVq0q3bp1k4svvlhGjx4t5cuXz82PikLGCklduHCh9OjRQy6++GJZsmSJNG/ePPJvr732mlxzzTUnDXTbt29fZCxnT55paWlm3xONbxRdJ3pPs8OPrJDLnPVNmzad1vP/7W9/k4yMDHnxxRflxRdflNq1a0uPHj1kyJAhMmzYMCldurSI/G8OXb16tXnhnFPOeTQbY7doYa5DrMXHx8vgwYNl8ODBIiKye/duef3112X8+PHy888/y0033STTpk0LbFO3bl31OJUqVRIRkV9++eWUnp8xVjJwjEVhw3Vs8ffqq6+Kc06GDRsm5cqVC/zb6NGj5f3335fJkyfL1VdfbW6fm2Pd5ZdfLseOHZM33nhDLrroolPa3+zxde+998q99957wn5+4G409evXN+vZ82vOoNdTnZN37NghR44ckRo1akjFihVPuM3ixYtPex4vKhh3/8W4KxpieR2QPbaee+45ee655066Hzt37pTU1FQROfXr2WyzZ8+WL774QpKTk2XGjBlSuXJltd3pjPdatWqpz3RhUWJuQixcuFBERFq1aqX+7UQnSdm/0XHBBRdI7dq1T/jYNWrUiPx/5cqVZfr06TJ79mz54IMPZObMmTJ9+nSZNm2aPPTQQ/LVV19J06ZNReS/X6TMmzdPpk+fLh9++KF88cUXkRO5Rx99VL755hupXr16rn9mFF7t2rWTa6+9Vh5//HF55pln5IknnhARkXXr1snYsWNFROSJJ56QAQMGSGpqauRubJcuXeSbb76J/EYUSqbcXthF+5LCd6LfamvTpo0sW7ZMPvnkE/noo49k5syZ8uabb8qbb74pnTt3lpkzZ0p8fHxk++TkZOnXr99Jn8s6+eMCtuhjrkMsValSRa677jpJSUmRQYMGyYwZM+TgwYOB32K3fnMot5iTSgaOsShsuI4t/iZNmiQi//1t3G7dugX+7ciRIyIi8uWXX8q6devMz3NujnWjRo2SSZMmyX333Sfdu3eX5OTk0Ntmj69u3bpJ48aNT/m588Opzsm53aYoY9zlPcZd/snL64DssZWeni5t27Y9ad/sL/dP53o2+3j+n//8R+6//375y1/+csJ9ys14L8zneCXiJsSePXvk3//+t4iI9OrVK/R22XfNrr76ahk6dGjo7eLi4qRbt26Rifznn3+WW2+9VV577TW599575c0334z0LVOmjPTt2zfyZ0Lr1q2Tq666SqZPny6PPPKIPProo6GfF0VLw4YNReS/v8GW7aOPPpIjR47IHXfcIbfccova5scff1S1OnXqyMqVK2XDhg3mxcmGDRvycK9RmKWkpMjatWtl3bp15ljIvpuefede5L+/USAi5t37k42d8uXLS0ZGhmRkZIiIyNKlS+XSSy+Vb775Rp5//nm54YYbInNojRo1zN+SR8nAXIdYO++880RE5Pjx47J7925zKR3gdHGMRUHgOrb4mz9/vixfvlxERH744Qf54YcfzH7OOXn11Vdl/PjxefK8EyZMkJSUFHnkkUfkvPPOk5kzZ0qtWrVCbZs9vjIyMuT222/Pk/0R+e8YOlk9JSUlUktJSZGVK1fKunXrpHXr1mobf06uXr26xMfHy/bt2+XAgQPmb6Vb83hxxbj7H8Zd0ZYX1wHZY6tbt27y1FNPhdomN9ez2apWrSpvvfWWnHfeefLEE09IqVKl5E9/+pO5T3k93gtaiciEuP322+XAgQNy1llnSefOnUNv16dPHxEReffdd0/r+WvVqiUPPPCAiIgsWbLkpH3r168vd999d6i+KNqyJ6XExMRIbdeuXSJi/9nYl19+KVu3blX1rl27iojIO++8o/5tz549kbXkUPxlr+/72muvqX/btm2b/Pvf/46sEZ2tTp06IiKyatUqtY3/54wn07p1a7nxxhtF5H9zV926daVFixaybNky8/FRMjDX4XRF+4uY7Avn+Pj4wG/15pfsL5pPtn46ij6OsSgIXMcWf5MnTxYRkTvuuEOcc+Z/M2fODPTNKw8//LDccccdsnz5cjnvvPNk27ZtobbLq/Hl+/TTT2X37t2q/vrrr4uIBH5b/2Rz8pEjRyJZBtn9ypYtK506dQo8Xk5LliyRxYsXS2JioqSnp0fqxfUYz7j7H8Zd4ZYf1wG9evWS0qVLy4cffihHjx4NtU1urmdzqlmzpnz++efSunVr+fOf/yx33XVX4N9jNd4LWrG+CfHjjz/KiBEj5IUXXpCKFSvKCy+8cErbDx06VFq1aiWvvvqq/O53v1Pr2jnnZPbs2YEAun/84x+ydu1a9VgfffSRiATXsv7LX/4imZmZofqieFm4cKH885//FBGR/v37R+rZITmTJ0+WAwcOROqbNm2S6667znysK6+8UuLj4+WVV16RL7/8MlI/fvy43H777bJv375Y/AgohG688UYpVaqUPPnkkzJv3rxI/ciRI3LzzTfLoUOHZMiQIYG5pUePHiIi8swzz8iOHTsi9UWLFsl9992nnuPgwYPy5JNPqhO1rKysSPhwzsf/v//7P8nKypKhQ4eaYVs7duyIuu4iii7mOuSF//u//5M777xT1qxZo/5t06ZNcu2114rIf4N2sy/a8lP2b8hZgXgoPjjGIj9xHVsyHD9+PPJlZnYIruXcc8+V1NRUWb58uRk0fzoee+wxue2222Tp0qXSu3dvM0PGd84550ifPn1k9uzZcuONN8revXtVn8WLF0fmrbD2798vt912W+CL148//ljefPNNSUhIkCuvvDJSHzdunCQkJMjrr78u//rXvyL1rKwsGT9+vGzatEk6dOgQuDF88803i4jIAw88EPgt5X379slNN90kzjm59tprA0uZFMdjPOMuiHFXuOXHdUBqaqpcddVV8tNPP8moUaPMGwg//PBD4JfhcnM966tVq5Z8/vnn0rJlS3nsscfknnvuifxbrMZ7gXNFnIg4EXFjxoxxY8aMcZdffrkbNGiQa9mypYuLi3Mi4po2beq+++47te3atWudiLgePXqc8PFXrVrlGjZs6ETE1apVy51//vnu0ksvdX379nW1atVyIuL+8pe/RPq3bdvWiYhr1aqVGzp0qBsxYkSkVr58eTdr1qxI36SkJFeqVCnXrl07d8kll7jhw4e7Zs2aORFx1apVc6tWrcrLlwr5zB+bY8aMcaNGjXJdunRxpUqVciLiBg4c6I4fPx7Z5pdffnGtW7d2IuKSk5Pd0KFD3YABA1yFChVcly5dXJcuXZyIuLVr1wae64knnnAi4kqVKuV69erlRo4c6Ro1auSqVKniRo8e7UTEvfrqq/n8CiC3xowZ40TE3X///YH6Sy+9ZNZz+sMf/uBExJUpU8adf/75buTIkS4tLS0yF2ZmZgb6Z2VluR49ekTmuMGDB7tzzz3XxcfHuzvuuMOJiKtfv36k/65du5yIuLJly7pOnTq5kSNHuiFDhkSeo0GDBm779u2B5xg/fnxkfLZv394NHz7cDRs2zLVr186VLl3aJSUlmT//jBkzcvHqIb8x1yHWbrnllsg4a9asmcvIyHAjR4503bp1c2XLlnUi4po0aeI2btwY2aZ+/fruRKe5M2bMiIzZnE4095zssbK1adPGiYg766yz3NixY924cePc+++/n6ufF7HFMZZjbGHBdSw++uijyLEtmttuu82JiLvlllsitdwc67LnJP8cK/tY26ZNm8A8c6I5Y+vWra5du3ZORFyVKlVcz5493aWXXuoGDBgQmbNy7uvJZM+/l112mUtKSnINGzZ0I0eOdD169Ih8Fp577jm13SuvvOJKlSrl4uLiXLdu3dyoUaNc8+bNnYi42rVru+XLl6ttrrnmGiciLiEhwQ0YMMANHz7c1axZ04mI69Spkztw4ECg/7x581xcXJwrX768GzRokBs3bpwbN26cmouLEsbdfzHuiob8ug44ePCg69OnjxMRV7FiRde1a1c3atQod/HFF7smTZo4EXGDBg2K9M/N9eyJjt1btmyJjKF77703Us/NePfPLQubYnMTIvu/MmXKuGrVqrkzzjjDjRkzxk2ZMsUdO3bM3DbMyZtzzu3evdv9/ve/d+3bt3eJiYmufPnyrkGDBq5fv37ub3/7m9u2bVuk79SpU91VV13lWrdu7apUqeIqVKjgmjVr5q6++mq3YsWKwOO+8sor7tJLL3XNmzd3lSpVcpUqVXKtWrVyt912W+ADhKLJH5vZF4jVqlVzPXv2dC+88ELgS7lsO3fudNdff71r0KCBK1eunGvUqJG7++673YEDB0548HbOubffftudffbZLiEhwVWtWtUNGTLErVy50l199dVORNwnn3ySDz818sLpfEHinHMffvih6927t0tKSnLx8fGuSZMm7q677nI7d+40++/evdtdd911rnbt2q5cuXKudevW7plnnnHO6YPY0aNH3d/+9jc3ZMgQ17hxY1ehQgVXpUoV16ZNG/fggw+6HTt2mM/xxRdfuOHDh7uUlBRXtmxZV716ddemTRt30003uS+++ML8+fmCpGhgrkOsbdu2zU2aNMmNHj3anXnmma569eqR872uXbu6Rx991O3fvz+wTX7fhFi9erXLyMhw1atXj9x8izZXo2BwjOUYW1hwHYtRo0aFPl589913kRtKR48edc7l7ZfBzjl38803OxFx6enpkfnmZHPGoUOH3JNPPum6dOkSmRPT0tJcjx493GOPPeY2bNgQ9edyLjj/Llu2zA0aNMhVrVrVJSQkuM6dO7sPPvjghNvOnj3bDRw40FWvXt2VLVvW1atXz11//fUnHYevvPKK69KlS+Qz0bp1a/eHP/zBHTx40Oz/6quvuvbt27uEhITI59V6/YoKxt1/Me6Khvy6DnDOuWPHjrmJEye68847z1WrVs2VLVvWpaSkuM6dO7sHH3zQrVy5MtD/VK9nT3bs3rx5c+Rm/n333Repn+p4L+w3IeKci7LAFoAi6/jx49KmTRtZvny5bN68WZKTkwt6lwAgzzHXAQAAAABQeBXrTAigpFizZo1aP/iXX36Ru+66S5YtWya9e/fmSzkARR5zHQAAAAAARU+Zgt4BAKfvrbfekvvvv186dOggaWlpsnfvXlm8eLFs2bJFatSoIU8//XRB7yIAnDbmOgAAAAAAih6WYwKKge+++07+/Oc/y5w5c2Tbtm1y7NgxSU1NlX79+sk999wjaWlpBb2LAHDamOsAAAAAACh6uAkBAAAAAAAAAABigkwIAAAAAAAAAAAQE9yEAAAAAAAAAAAAMREqmDorK0s2b94slSpVkri4uFjvEwox55zs27dPUlJSpFSp2N7DYtwhW36NO8YccmLcIb9xjEVBYK5DfmOuQ0FgrkNBYNwhv3GMRUEIO+5C3YTYvHkzYY8I2LBhg9StWzemz8G4gy/W444xBwvjDvmNYywKAnMd8htzHQoCcx0KAuMO+Y1jLApCtHEX6iZEpUqV8myHCsLll1+uapMnT1a1WGZ0lymjX+oRI0ao2vTp0wPtLVu2xGyfTkd+jImiPu6Q92I9JgrzmPN/s8Car0qXLq1qnTt3VrVZs2bl3Y55MjIyVO29996Lup31mxOxnJNPRUkedygYxeUYG2besvj7lp6ervp89dVXud6vvNKzZ09V27Vrl6otXrw4H/bm9DHX/U/58uVV7e2331a1zZs3q9q2bdsC7YSEBNWnbNmyqnbs2LFA2zouHjhwQNWOHDmiameccUagPXHiRNXnww8/VLX8Vlzmuljq2LGjqp1//vmq9vDDD+fJ83Xr1k3VevfurWoPPvhg1MeyfhMyKysrdzuWh5jrTi7sOXliYmKgfemll6o+NWvWVLWkpKRAe//+/arP7t27VS0zM1PV1q1bF2gvWrRI9fnll19UrSAw7pDfOMaiIEQbE6FuQhSlP6ux9jU+Pj5Uv1h+4RV2v2L951J5JT/GRFEad8gfsR4ThXnMhfkyz9p/6wZomO1yOx9aX6yEUZhvQpTkcYeCURSPsdbj5fYmhL9dmHmsIFj7Zd0MLiqY6/7H2teKFSuqmnWDwb+BkZc3IY4fP65q1rVDhQoVoj5fYVAU57r8Zs0z1k2ywvh8hfW1Z647ubDn5H4/67sNa+z4c6I/94mIlCtXTtWsx/fHa2F+7Rl3yG8cY1EQoo2JovGNNwAAAAAAAAAAKHIK56+WnQbrLn2zZs1U7Ve/+pWqTZkyJdC2frNo69atqub3GzVqlOpj/RbU4cOHVa2wLr8EIP/k9s/XZ8yYoWrWPPPNN98E2rn9M2V/uQcRkSuvvFLVrrjiClUbOHBgoF0Y/jwfQO5Z519+rUaNGqrP448/rmpffPFFoD169GjV58wzz1S1//f//p+qbd++Xe9sCP6+Wr8F36lTJ1Xr37+/qvm/0Tl16lTVx1q2rqgs41Qc+cuFiIg0atRI1fbs2aNq/tixxn3lypVVbf369YG29dcLO3fuVLVvv/1W1Xbs2BFoV6lSRfVB0fDII4+omrXWcvPmzQNt63rU4m/3wgsvqD7+X9aI2PPT66+/Huo5UTz488rRo0dVn6VLl6paampqoF27du2ofUTscT9gwIBA21r+6dZbb1W1JUuWBNqFdekwAChu+EsIAAAAAAAAAAAQE9yEAAAAAAAAAAAAMcFNCAAAAAAAAAAAEBPFLhPC8uabb6qavx65iMiFF14YaJcuXVr16dOnj6r56d/W2qxvv/22qlnrs7L2IABrbfUwrPmjcePGqjZo0KBA219/XcTOv6lfv37UfbDWa920aVPU7ViLFSg6rLXqrbWgL7vsskD75ptvVn2ef/55VZs/f36g3aJFC9Vn+PDhqnbHHXeomr+WuTXf/fDDD6o2b968QPsf//iH6vPWW2+pmpXt4L8OvXr1Un38c1ARkauuuirQXrZsmepTpow+lT927Jiq4dQcOHBA1fbu3atq1rl8cnJyoG3liVjvm38cbNOmjepjjdXjx4+rmn9tgqLBGivWudDll1+uarNnzw60X3nlFdXn448/VrUVK1YE2nfffbfq06BBA1Vr3bq1qvmssYni69ChQ6pm5WL6mTvWdc/BgwdD1dauXRto+xknIuEyN3N77YXYso5lYd6revXqqZo/Pq1r5Hbt2qlaSkqKqvm5iNZ3ff6cLKLPLayfJbdZZkBRwV9CAAAAAAAAAACAmOAmBAAAAAAAAAAAiAluQgAAAAAAAAAAgJjgJgQAAAAAAAAAAIiJEhFMfeaZZ6rarl27VG3JkiWBthUA2KRJE1Xzw2OsUMK2bduq2p49e1QNAKyQqnLlygXav/zyi+rz8MMPq5oV+nruuecG2n4IrEi4UM6OHTuqPrVr11a1v/zlL6rmi4+PV7XDhw9H3Q5abkPcwvDHoYg9Fq0gwp49ewbafnjr6ShfvryqTZs2TdX8UFdr3B05ciTP9qs4sELjrRBqy6WXXhpoW69tp06dVK1fv36BdpcuXUI9n7Vf/v5XrVpV9Rk0aJCq+UHR1mdo4MCBqmaFunbr1i3Q/utf/6r6WCGKd911V6A9duxY1ccKobbeMyvcFid2/vnnq5r1GlrHPD+43Qq0th7Lvy6wwlStudUaO5s2bQq0ly5dqvqg8LECoK3a119/rWr+mJ00aZLqc9FFF0Xdh0cffVTV3n33XVXjWAn/fLN06dKqj3V+5gewlymjv5KyxleFChVUzd92/fr1qs+OHTtUzUcwdfHy1FNPqZr/HteqVUv1admypaotWrRI1fzzOuuYfvz4cVX785//HGjv379f9fn8889VbeXKlar22WefBdo5x75zTvbt26e2AQoD/hICAAAAAAAAAADEBDchAAAAAAAAAABATHATAgAAAAAAAAAAxAQ3IQAAAAAAAAAAQEyUiGDq6tWrq5oVOt2sWbNA++DBg6qPFfiZmZkZaPtBNSIiCxYsUDUrENOvEfoFQCRcEOzHH3+salZ44TnnnBNoW+FdderUUTV/PrICia1AuFdeeUXvrMcK70Lu5DZczzq++az33A/wFREZPHiwqvnjYPny5aqPFewWJlDXCsy+5557VO2TTz4JtN9++23VxwpWLMnj03o9rPfECphu1KhRoG2Fm1rBeX6gtRVs6Yf4itjhlgcOHAi0k5KSVB8/JFNEpHLlylGfzzqPs+Y7f17csGGD6nP48GFVa9y48UnbIiJr1qxRNYKpT9/IkSNVzQqAXrt2rart3Lkz0PbHkog9dvzrFeuzcejQIVWzwlp79eoVaL/xxhuqz9y5c1UNBcu6PrXCyDt06KBqfpipH04uIvLyyy+r2t///veo+5WRkaFqv//976Nux1xUvPnnjdb7bZ0/+TXrPMNy7NgxVfPP/77//vtQj+WfL1iPjaLLD20W0cdYa9y98847qmbNyw0bNgy0ret06xjuB1Hv3btX9WnatGnU5xMR6d27d6D9008/Rf7/0KFDctddd6ltgMKAv4QAAAAAAAAAAAAxwU0IAAAAAAAAAAAQE9yEAAAAAAAAAAAAMcFNCAAAAAAAAAAAEBPFLpg6MTFR1RYvXqxqOYNbsvkBRS1btlR9xo8fr2pNmjQJtK+44grVZ+HChapmBV/74YsEU0dnvd7btm1TNSv4xw/4s15vK7QoTIBW2bJlVc0KLfLHgTUuchvWagXUhglYtbazArv8ALIwwbYnUqNGjUB7xYoVuX6s4ii3QX41a9ZUNX/+O+uss1QfK+jXf7+t8Ddr3IcZc9b4ssZTbkOXEZ01r/nvS4sWLVSfq6++WtWGDh2adzuWS9Z+vf7664H2V199pfps3bpV1fzXpiQFVYede6zQ5I0bNwba55xzjurTvXt3VfOPg7t371Z9rBBqa37w3zsrXNgPrxbRY98Kh7WC2n/88UdVq127dqBtjZ9//OMfqpaenh5o33zzzarPrbfeqmoEbJ4+6/jjB0qK2Mc8/1zeCqG2Hr9atWqBdtgQaqufH6RZtWpV1QeFjzWHTZkyRdXmz58f9bGqVKmiapUqVVK1MHP8U089pWpLly6Nup11XkEwdfER5no4zLWhNSas45hVq1ixYqBtfceDoiu3133Wd2/+9e4ll1yi+oQ5Novo0Ok1a9aoPsOHD1e1mTNnBtrWPG2db1rnlrNmzQq0U1NTI/9vnZ8ChQV/CQEAAAAAAAAAAGKCmxAAAAAAAAAAACAmuAkBAAAAAAAAAABiothlQljrtV577bWqZq0D7a85nJmZqfr07NlT1fzsCCuP4IwzzlA1K7/ihRdeUDWc3G9/+1tVe+2111Rt586dquavM3j48GHVx8qSqFWr1kkfR8R+f63H99cODtPnRM/pq1y5cqj98tc/tNbatvIy/IwAa11D6+examPHjg20zz333Mj/Hz9+3MwfKEn8daetfBFrrehu3bqp2qJFiwJta86yxpw/Bqw1ptPS0lStd+/eqvb555+rmo/8h+jC5rCEeS3DrCP/+9//XtWsXB6Lv68F8f7efffdgbaV83TLLbeoWknKgPCF/dlvvPFGVfPXyLXmB2sc+HOSlVETdvz4a01b6+eH+RxZnw/rWGnxMyes47CfiySij+HW6xeWf7xmXfaTs46LU6dOVbWLL75Y1Xbt2hVoW+MkOTlZ1fx+1trm1nWOlWPjryltbYei4YYbblC1OnXqqNqAAQMCbStjzhoH1mP57rjjDlULk1tonaui+PCPK1b+TZi8B+t4btWsY7W/9v3atWvtnQ2xXyg+rO9v/EycefPmqT4LFixQtS1btqhaw4YNA21rPPXr10/Vtm/fHmhb31lZ39/07dtX1fzvBubOnRv5f3JlUZjxlxAAAAAAAAAAACAmuAkBAAAAAAAAAABigpsQAAAAAAAAAAAgJrgJAQAAAAAAAAAAYqLYBVNbrPA3K2DaD89KSUlRfdq3b69qN910U9Q+ffr0UbVZs2apGqLzQ4X88D0RO4zXD8gU0YFaVojPunXrVO3nn38OtK3wIyucy3p8P8y5YsWKUffT2s5iBXBaQV/+c/qvsYhI6dKlo+6X9V5YAceWffv2BdpDhgyJ/P/hw4dLfDB1mHC/0aNHq9rmzZtVzQ+/tN43K/zNHyd79uxRfawQ20svvVTV/GBqQqhzJ7evm/V5tvih4vPnz1d9rPBLK1TNZ407K8A1TICh9fPs2LFD1davXx9oW3Nrr169VG3mzJmqFkZRHNe5DTC2Xu/69esH2tb84If4itjHzzDC7Ks1t1nb+WMqbAi81c+vWecCZ599tqrt3Lkz0F62bJnqY53jZmZmhtov/I//fvshvyIiK1asUDUrsNIfT61atVJ9Pv30U1XzP0OjRo1Sfaxrh+rVq6ua/34fPnxY9UHB898n65gxePBgVfvzn/+sav7xzQo2t+Yef7615sMXXnhB1X71q1+pGkoW/3zBOofzg6PD8s/9TuTAgQOBtnVNbimK52cIz/r+Yffu3YF2mzZtVJ/f/va3qmbNm/58+8knn6g+1nWyb+vWrapWt25dVdu2bZuqnXHGGYH2xx9/HPn/MN8bAAWFv4QAAAAAAAAAAAAxwU0IAAAAAAAAAAAQE9yEAAAAAAAAAAAAMcFNCAAAAAAAAAAAEBMlIpj6ySefVLX77rtP1fxwxJo1a6o+VuiMHxR4yy23qD5ff/21qk2fPl3vLKLyg7+tIOe0tDRVa9asmar5wc1WiI8fYiQSLuDRCmu1Ht8PC7RCvayf0Q+jtEJe9+/fr2ply5aNWrP6WD+zH2ZnhY5aj2WFjfmft8TExMj/W68JtNtvv13VrDAtfxxa4WxhAoKtMWF9Xi655BJVGzdunKr5rMcv7kFyOX9m/2e1Xg8/+FfEDqr15wJrTqlQocJJ90fEDlPt06ePqllznR8SZ4UPW++vH1pvbVepUiVVs8IJ/f169tlnVZ/GjRurWocOHQJtK9Daqlk/z9KlSwNta54uSH5ArxVSar0HDRo0ULUPPvgg0LbGa8eOHVXNf02s41vYuSDM8doKNg/zOoQJtBbR5xpWkPDixYtVzT8/uPnmm1Wfhx9+WNUsxX3uPF3p6emBtvUeWcdFK3iyVq1agbY1Jvr3769q/mdo9OjRqk/Oc6NsfjCrtV/Wdih4YT6XN9xwg6pt3LhR1bZv3x5oV6tWTfWxjvP+ufvs2bNVH+u8AvCPgWHDpP1rQ2uOtM6prH7++A1z/SISLhQeRZc1//njdcmSJarPjh07VM26tr3gggsC7WuuuUb1Wbdunar5Y3/8+PGqj38OISJy7733Rt2HLVu2RP7f+k6mJPI/59Y1gXUuX1RY86T184SZ76wwd+uxrO+WThV/CQEAAAAAAAAAAGKCmxAAAAAAAAAAACAmuAkBAAAAAAAAAABiokQstG6tbbl582ZV89fstdb09/MfRESGDRsWaGdmZqo+1tpuhW0d6MIqPT09sAZkkyZNAv9urXlnrQfpv78iem1Ja510q5aUlBRoW+tjW2u0WfsVZs0+a+01fw1g6+ez9t3aL3+ddOuxrO38MWz9fNY6xNbP478X27Zti/z/L7/8ovqXdP7nQMRey3758uWqVrVq1UDber/DrI9ovd/We+vn7YiITJgwIdC2cnpK4vqsOX/mcuXKBf7N+hy0a9dO1apUqaJqX3311QmfJ5u1trm/jq61Hq+1ncWfj8IeA/31U619D7Puv0i4cW2tEeuvk2m9DtY5g3XsP++88wLtL774IvL/zjkzyyI/hTkmWZlZTZs2VTX/2Ohna5yI//pa+2S9B2FY48eqhRkr/mdUxJ4D/ce3jqdt27ZVtRkzZgTa1ti0jgU//fRT1H1AUEpKSqBtvYZbt25VtcqVK6uan0uW83zmZKx1/n3W+7hz505V84/r1rUJigbr2FKjRg1V869N6tatq/pY2YZz5swJtIcMGXKqu3hCJTHbqyTxrwOsNcWtjDD/+Godb62sG+uz4D9n2PNBxmHx5mfkiIi0aNEi0F65cqXqs2DBAlWzvk/xXX/99apmZZH430Fa19IffvihqlnXdg0bNgy0582bF203Sxz/c346n3v/3D23WRLW94Z/+tOfVO2pp55StVWrVgXaYX+eMP38HLpY4i8hAAAAAAAAAABATHATAgAAAAAAAAAAxAQ3IQAAAAAAAAAAQExwEwIAAAAAAAAAAMREiQimbtCggarVrl1b1fwwSD+8VUSkXr16UbezApisMBkrcAlavXr1AsGkkydPDvz7c889p7bZsWOHqlkhqH4wTNhAUP/xrRAsq5aQkBB1H6ztKlSooGp+2JEVkGmFHVnhtn7wq7UPVpBmtH0SsUNurOBOX87XKmzIWHHmv5fjx49XfX7++WdVs+YZ/7GssWMFwfrvm9XHH0sidnDxjTfeGGj7QUsi+rNe0vifVeuY1L59e1X77LPPoj62FbJmvZ/+2Did45YfHlipUiXVx5ob/M+/NR9Y4bDWcWDfvn1Rt7PCu/zXxgoVswIZrde0WbNmgfbUqVNVn4IUJrysTZs2qjZt2jRV88eZFaBrnaP524UNSwsTWp6XQanWdtZxsFq1aoG29TpYx1h//PznP/9Rffr3769q1hxACOfJ+cdF6320+GHAIvqc/7rrrgv1WP5zWqGH1mfBCmv1jx/WuR+KBus4ZR0rJ02aFGiPHj1a9bGOU36IuXUeZ13HhkEwdfHmz5vWuZE1Z/ljzppvret2a070z1M7deqk+syYMUPVGIfFW/PmzVVtw4YNgbZ1HWJ912ddf/nHVCtE2Lq+9j8j1jXy6tWrVa169eqqZm2LU2cdp6zjYJjvr6zx8/zzzwfa1vWpdT1vfTfi16zvFv35VSTcfHfzzTer2rvvvqtqGzdujPpY0fCXEAAAAAAAAAAAICa4CQEAAAAAAAAAAGKCmxAAAAAAAAAAACAmuAkBAAAAAAAAAABiokQEU1uWLVumai+99FKgnZycrPoMHjxY1Z544olAu0+fPqqPFSzih+PAtnnz5kDwlR8iZIXJhA1p9lmBV1bgi88Krwnbb9euXYF2mDBVER2uboUrWaGo1s/os8JrrO3817506dKqjxVSZvXzEUwd5IdOb9q0SfXxx5KI/fofPXo00LbeW+s9CvM++I8tYo/7lStXBtoTJ05UfWbNmqVqP/30U9R9KC4uuuiiQLtly5aqz5IlS0I9Vq1atQJt6z23wqr94DUr1NJihQxWqFAh0N62bZvqYwVw+vP53r17o+7niR7Ln8+tMGAreMx/LOv1s+Zby5dffhlo5wyby8rKMj/H+SlMeJkVJm29lunp6YH2ihUrVJ9HH31U1aZMmRJoW/NdbuVlGGXYY6UfXnzHHXeoPlYoXUZGRqC9efNm1SfsZxIn55/zW/OMxZpn/OPgP//5z1ztk3/cF7EDghcsWKBq/rgIc96Fwsl676zj1DvvvBNoP/3006Eef/HixYG2Nfb947eIfRzwz9EI/y2arOO5dWxLTEyMup11buRfm1jXsHXr1lU16/reD0nt1auX6vPjjz+q2rp16wLtsD8z8ldu35crr7xS1R5++OFA2zp+WyHUVs0/PlthwGGuFazrZut7n/PPP1/V1q5dq2o4ddZxKkwI9SOPPKJq119/var5892iRYtUH+u74q+//jrqPhw8eDBqn7Cs73mWL1+uatZ8far4SwgAAAAAAAAAABAT3IQAAAAAAAAAAAAxwU0IAAAAAAAAAAAQE9yEAAAAAAAAAAAAMVHsgqmtQI0zzjhD1ayQ4u+++y7qY4UJq7ZCr2+66SZVW7hwoaqFDRktSY4dOxYIjPEDVi1WEFCY0Bkr/MgKGvJDYKyxYoW4WcGv/rYzZ85UfaxwwmrVqgXafoitiEidOnVUzQqw8UPvrNfPChcOE65ksV5TX87XynpfShp/7MydO1f1sYKLrXHojzkrRPjw4cOq5gcrWaHXVpCTFe7uB8+2a9dO9bHm25IUTP3UU08F2n//+99VHyuUzJojd+7cGWhb4X7W597/7Fl9rPfX+ozXq1cv0LbCL635yd/X7du3qz45w51Pxp+jrLnb+nn8OTJsALsVGux/bnKeexSVEM+wr7cfQG957733VM1/X6xgSyusNcyxwnrPw7Ae23q/rJB034wZM1StR48equaPfWt+PXDgQNTnQ3QpKSmBtjU/WWF8fui4iMgHH3yQJ/tkhalaAZn+/C6iA6zDhCyicLKuHaz5b86cOYG2db7kh/iKiOzfvz/QtuY161yyadOmqlaSztGKs7CBzH6wrzV2rLHqH4et43JmZqaqWeeW/jHXOofzv6sREXnyyScDbUKoC541Dqz35ZJLLgm0rfMu67sT/1rTDycXsc/l/TnSYp2nWp8H//H973NERGrUqKFq1rhesWJF1P0q7Kz5IYyw3/WFkZaWpmrjxo1Ttdtvvz3QTkxMVH02bNiganfeeWegbZ1fTp06VdWs7/ZefPHFQPuZZ55RfebNm6dqvrZt26pazZo1VW3r1q2qNnDgwEA7N+e8fLMHAAAAAAAAAABigpsQAAAAAAAAAAAgJrgJAQAAAAAAAAAAYqLYZUJYa4FZ66daa8f52RHWOq/+Gqsiem1oa93g+fPnq1rXrl1VjUwILTMzM/CatmrVKuo21tq31nvuv3fWmqfWWnX+mt7We27VrMd/5513Au1zzz1X9WnRokXU/XruuedUn+HDh6uatY6/v/6/tV68tdahnyVgrX8edm1ZX871+ax14oszKwvBZ+U/WGv57du3L+pjWWPVys0Jk/lhredpjZ0BAwYE2tb6iB07dlQ1f83j4qRJkyaBz7X/3r322mtqmz59+qia9Xnx19a1PuPWHOn3s+ZD6/21+HNBRkaG6vPZZ5+pmr/m/QUXXKD69O3bV9UeffRRVfN/nrCvgy9s/oP1+evQoUPUxy/smjVrpmrWurb++uBhc4N8hTUXKLf7ZZ2XWuv/+zkFu3btUn3OOuusXO0DTs46JlnvmzWHvPnmm1EfP8xcao2Jzp07q9ru3btVzR+bVq4ACp/rr79e1awsEisLxh+zVj6UNYb9ednKBLOyw3r37q1q06ZNC7SLSs4RgsK+b/48FjajyF/PPWzuk3We5c9t1nmXtXZ7v379Au2PP/7Y3lnEhHW9aI0769xyyJAhgfa2bdtUH2tM+evbW/lm1ndI1vd//hi2zgetcef/3NZ4tV4HK4Pnn//8p6oVNWGvIfOK9X3Z6NGjVc2aa/w54pprrlF9rNyl1NTUQNu6TreuK63rWD9f4qqrrlJ9csv6Htr6Pvzhhx8OtMmEAAAAAAAAAAAAhQY3IQAAAAAAAAAAQExwEwIAAAAAAAAAAMQENyEAAAAAAAAAAEBMFLtgakujRo1UzQoN8YO/rDCZ/fv3q1qNGjUC7e7du6s+a9asUbXBgwer2rPPPqtqJV1qamogJPfzzz8P/PuyZcvUNn6Yo4gOIxLRgURWoJYV0Fa5cuVA2xorFj+kU0SHNFuhgwsWLFC11q1bB9rnnHOO6rNo0SJV69+/v6qtW7cu0PbDlkTswCU/OClsKLEVNub7+uuvI/8fJii2OLFCdv3XdtWqVaqPFR5kBUz7rLByK0DWf7+t4CwrpNPah5UrVwbaO3fuVH26du2qak8//bSqFRctWrQIBFP5YaPWcct63az3JcxnzuLPBWEfOyEhQdX8+ciaWzt16qRq/rxpHdMnTJigalaYp7+v1pxlzXV+YFjYgGV/fhcR+fbbb0/42M65XIc35ycrQG3evHmqNnTo0ED7sccei9k+FQQrrNUa+z7rc/Svf/1L1e67775A+7333lN9rKBzK5D2559/jrpfJZkf6muFRdasWVPVrIDBqVOnRn0+a+7xWSGBVhC5dYz151crWBOFzz333KNq1vWLNX789/zQoUOqj3V+758DWuft1vzRpUsXVXvhhRcC7XHjxqk+KPzCBlP7/azrNeu6wB+/1nmXVbP4x2FrO+t8s0WLFoH2rFmzVB/rOIC8YR23rPNfK0jYDwj+7LPPVB9/LhIRSUtLC7QzMzNVH+sczrpO9se1dX5gXQP413b+dzAiIj/88IOqWfN52O+fioP69esH2tZ3JQMGDFC1nj17BtrWZzo5OVnV9uzZE3WfrHPtadOmqdr5558f9bGscOerr75a1e66665AOz09XfUZMWKEqm3ZsiXQtsardbz2v/MU0d995wZ/CQEAAAAAAAAAAGKCmxAAAAAAAAAAACAmuAkBAAAAAAAAAABigpsQAAAAAAAAAAAgJopdMHX79u1V7aKLLlI1KwDQD4+2AnyHDRuman745RVXXKH6NG7cWNWs8A8/XMQKFi5pGjZsGAjB9EM9rcCiW265RdV27NihauXLl1fP5Tty5Iiq+cFJYcNarbA3P3DOeixrXPs2bdqkalZwjBUE5fezQr2sMLuKFStG7WMFmFohZX6440MPPaT6lBRWWJAf9taqVSvVx3pvwwSKhw3C9d/fMI8tYodp+WGq1s/80Ucfhdqv4qJevXqBz4YVaObz5zARHbAqoucja34KM36s7azAP+tzX6dOnUD7xx9/VH0WL16savv37w+0ly5dqvpYoavWa+P/PNZ4tQLo/OOA9TocOHAg1D60bNky0F6+fHlgfwpbMHWTJk1Ubfv27apmjYNt27YF2ta5VxjWsSVMsG9Y1jjIy8f3WZ+POXPmqJofBmuF4M2fP1/V+vXrp2qTJk06lV0scfzzGX/eEbHnGes9sT4LvjDBr3PnzlW1MWPGqJr1+fARTF04XXbZZYG2Ne/4wbsi9nHKP4b7Y1rEHpv+tYk1Nq1jmfUZ8QM4rfN9K7wYhZ81Nv3vQCzW2PFrYYOwrX3wt7X6hPksWNdV/ncOJU2Y1ztsgLh/nLLOdVNTU1XN6ufPiWeeeabq43+/IqLPvR544IGo+ykismLFClX76quvAu2dO3eqPla4sX+NZs3l1mdm8+bNquYHFy9cuDDy/1lZWbJ+/Xq1TX669dZbA23ru1XrHKpt27a5ej7rmOQf36xzoY0bN6qa9X6mpKQE2tZ3hNZj+WPF+n5u4MCBqmaN4VmzZgXar776qupjXWv5+/XHP/5R9bHeC2sMV6tWLdAePHhw5P+PHj0qH374odrGx19CAAAAAAAAAACAmOAmBAAAAAAAAAAAiAluQgAAAAAAAAAAgJgodpkQZ599tqrNnDlT1ay11vy1Aa0MAWsdMb+ftWabtRahtdZYvXr1Am0yIf67HlrOdU799QnT0tLUNv461CIitWvXVjV/LTdrLXVrLVa/Zq2HaK2jaK2t7a8j/uyzz6o+/tprInrc+ZkKIiJ9+/ZVNWutOmst+DD87ax1FMPWrPXxSirr/d69e3fU7cLmA/jj1Vpv01qz3O9njXHrsayav62VlxJmrdnipGbNmoH38Jtvvom6TZcuXVRt+vTpquavk2m93taavP7azdb6zhZrncx9+/YF2tbarwMGDFA1fz63MkamTp0aah/8cWfN79Z86H8erH2wWPNyu3btAu2cn8ew6yLnJ2uNUCuvxFrD1R9nq1atUn2s+c4X69cl7JrGPmushMkDqFq1aqjH918v65j+/fffq5o/xkTIhIjGnxusuS4pKUnVfvrppzx5PoufVSdiH0+tMed/bv18ERQOK1euDLStcz3rOJWQkKBq/nHKGhfW+PHnV+vcy1q33NpXPy+I/IfCL8y6/yL2sbpy5cqBtjVvhskSs57PulYMc6y2vnOx1lZv2rRpoF23bl3Vp7hkQuRlxpX/WGEyiSzWdb+VgfnEE09EfaxnnnlG1V555RVV88ewdZ1lrbH//PPPq5p/PvbPf/5T9fGz8ER0/qg1Xq2MOetz5J+TJCcnR/7/2LFj+Z4JUbt27cBn9A9/+EPg361rB+v70C1btqiaP0dY17Fhskmt83br82FlVfrvi3Wdaf2M/jm/9R2LdY5mHYu7det20nZeCzN35Lwmts5XLPwlBAAAAAAAAAAAiAluQgAAAAAAAAAAgJjgJgQAAAAAAAAAAIgJbkIAAAAAAAAAAICYKHbB1CtWrFA1P3hIRKR169aq9sgjjwTaVpjWunXrVM0PO7KCm2655RZVswKzreCkku7QoUOBEBk/KMYKhbGChgYPHpyr57dCbqwwHJ8VOmOFxPlhnlYIqPXz+OPs8ssvV338MFoROzQszM9jhYH5r431WoUJ9hbJ29Csos4KUfeDcK0gKyuEOgwr7MoKxfJZ4U5WuJz1+P6Ys/qEDUEuLkqXLh14HTZv3hx1mzlz5qhavXr1VC1skLLPCrEMwzp++vORdbz77LPPVG3ZsmWBtnX8tkIzreBOf3xaYe5hxnDY0PQGDRqomh8Ul/O4UBiDqRMTE1XNOpZZc0aYeb1Xr15R+1iPk9swRGuusfjHKesYGDaAzTdmzBhV+/jjj1XNnwOsIEfrs20F/eHk/ONno0aNVB9rTvnxxx9jtk87duxQtZzBk9mswHI/MHvjxo15tl/IO/7xLDU1VfWxPuPWebt/HLSuQ6xjun+uFfa4aIWu+nOi9TmK5WcGsZOWlqZq/nWAdUy0xpx/jhg2HNs6fvvjfsOGDaqPte8XXnhhoP23v/1N9Sku8vvcskqVKqrWpEmTQNuaZ1atWqVq1ncZbdq0CbStUHFr3vTP4xYuXKj6DB06VNU++eQTVfPnv4suukj1sUKKfXv27FE1awz/8MMPquafI+YMN87tOfLp8K/rnn766UD7/PPPV9tYxwjrPMcfw2FC6sMK+1r5c02YIGwRPT6tsfnpp5+q2uzZs1Vt3rx5gbb1mbHmYf9azpqXrc/arl27VC0v5hP+EgIAAAAAAAAAAMQENyEAAAAAAAAAAEBMcBMCAAAAAAAAAADEBDchAAAAAAAAAABATBS7YOoOHTqoWseOHVXt8ccfV7U777wz0J47d67qY4XCWCEevgULFqha//79VW3btm2B9rfffhv1sYs751wg+MUPq/EDWkRE0tPTVS0lJUXVtm/fHvX5rfBdP4jGCmixQrasQK2DBw8G2lbQ2+jRo6Pup/WzWOHFVoiOv1/Wz2OF3PjbWUF51s+c27Dbksx/L/ft26f6WO+RFZDkBytZ4WDWOPFDoKwwYGsMWJ8FP5TOGidW6Hxxtm/fvsDPXL169ajbhA0o79y5c6DdsGFD1adx48aq5r8HVhCYNQ6scedvax2vx48fr2p++PZ9992n+lgheNOmTVM1PxzMGufWGPaDmK0gOSu8a/fu3armH+dzhlxnZWWZoc8F6dxzz1U163hqhY1aY8N39dVXq5p/XLRY84o1PnMbzhcmVNtizad+eOCIESNUn5EjR6qaP65nzZql+rRs2VLVkpKSou0mPP5n1XofrWNs5cqVc/V8YYL9wgYSV61aVdX8ecY/5qJw6NSpU6Dth0SL2OPOGhv+e2ydH1hzsv+c1vPlDDw92b7619zWuQbB1IVL2JBR6/rUP+Za81OY6wJrH8JeWx84cCDQ7t69u+rTrl07VfNZ53XFhf+5r127tupjnTdYn/Gc56wi9jHQmp/864lNmzapPtZxNzU1VdVWr14daFtBzr/73e9UbebMmYH2DTfcoPq8/PLLqrZo0aKoj5WRkaH6WNcAX3/9tar5du7cqWrWNUbz5s0D7Zzn5seOHZOffvop6nPF0t133x21T7Vq1VTNmmtq1aoVaFvj1ToX8gOZ/cc5EWv+8b8TtK63v//+e1Xzv88N8/1jWNb3J9a1kHUM91nX7v7rJ6Jfh5wB7FlZWbJly5aoz8VfQgAAAAAAAAAAgJjgJgQAAAAAAAAAAIgJbkIAAAAAAAAAAICY4CYEAAAAAAAAAACIiWIXTJ0zGCNb27ZtQ/XzQ6etUB0rnMMP3Vq8eLHqYwWMNmnSRNWsELGS7uDBg4HQFT8MxQplvP3221VtzZo1quaHJFmvvxVM44dsWaEwVrCbFXLtP5a1nR+6ZW1nPbYViGQJE8BpvQ7+zx02ANQKxtuxY0eobUsCawz4r601JqzX3wqj9F//sOPXDwwLG2ZnPb7PGr8lbT5cu3ZtIBTqwgsvjLqNFSLlB5KKiKxatSrQ/s9//qP6WIFw/jxjvSfW+2s9lh9mN336dNXHCqrzw3lfe+21qI8tIpKZmalqM2bMCLSt8C4rRNH/HFk/n3XOcPToUVXzt835+uU2DDmWevbsqWr79u1TNSvsLUzA9AUXXKBq1nuXW9Z77Mvt626NfeuxwrwOFv/zEOZ8RETk4osvztXzlWT+8dMK7rSOp61atYrZPlnHRWs8W9cmZ511VqA9bdq0vNsx5Bn/2GzNH9Y8k5CQoGr+tta8s3XrVlXzr6Osc0lr7rEe3x+z+/fvV31QsPz3yDrft67TatasqWr+8Se3YdJh5zUrxHb9+vWBdp8+fVQfKyzWn8+t4N/ionPnzoG29Z5Y1xPWMcj/3G/evFn18b9fsR7fCpwOKzk5OdAeNWqU6jNs2DBVGzNmTKBtfTdkXV9bY98Pw7bOxaxrLV/dunVVzbqm8a+FRPRxIOdral1/5Dd//FhB59bnzgrmXrp0ad7tWD7zr51btGih+ljvrzUv+q+pdV5q1fzHso7zVu3w4cOq5h/Xc7bDfjfEX0IAAAAAAAAAAICY4CYEAAAAAAAAAACICW5CAAAAAAAAAACAmCh2mRAWa21ha10xfz1na10sfw06Eb12XMeOHVWfZcuWRd1OROS7775TtZJu7dq1gbUL/fWjrfXlrPfXeu+qVq0aaFtrH4Zd3zIMazt/zT7r+aw14fz1OsNkNpxoH8I8n/VY/mfE2gdrTUIrk+Xrr7+Oul8lhbWWn/9aW6+hxXr9/TFgjXvr8f0xZ631a40Ta51R//GttTSt/SrOtm7dGviZ/bwhS9g1w/3X11p70nqf/PfTep/Cvuf+2qXWPG3lJzVo0CBqn0WLFqlaSkqKqvnH+TB5JSL657HWu7XW6LbWVfbX+c95LhB2Lc38tGXLllA169znxRdfzNVz+muQWvORNRbDHN+sPrk9LlpraVv7ZY0D37XXXqtqEydODLQvuugi1eenn35SNWvdd5ycn+dm5Y1Z2VW5fa3DjDlrLFlzRJi10wvj3AJ9jernE4roNe9F7LXx/XkmKSlJ9bHWH/fPE60xbZ0zWMdB/1z1xx9/VH1QsMLk9zVq1EjVrCws/1ht5YZZx05/H6zzJ2v8WnPwI488EmiPGzdO9dm4caOq+azxXFRVqFAhcIzx38+PPvpIbbN3715Vq1y5sqr577F1fmOdG/nf11g5YlbemHWe7ueqdunSRfXZs2ePqr3wwguBdu/evVWfOnXqqJqVEeWv62/lOFjfbfjbWc9nzZvWvOwf+3N+jsJe38SSPw6scWGxrm398WPNK9Z3gv71m/XYuX2trLFv7Zd//mV9N2PNUdZc7V/HWueJ1j7481uY/NET9csL/CUEAAAAAAAAAACICW5CAAAAAAAAAACAmOAmBAAAAAAAAAAAiAluQgAAAAAAAAAAgJgodqmfVrCzFXaUlpamart37w60wwTAiIi8++67gbYVoGgF0FnhYMUpFCmv+KFXfuiMH1QtIvLzzz+r2sGDB1XND3OxwlesIK4wz2cFxVhBcn7wlrWfFj88xgqTsQJzwoRVW4E2Fv+9sAJjrQBTP2hWxP5MllTWGPDfy127dqk+ViCTFcDkv99WgO+SJUtUzQ9yt96zsCGEfkiTNW+WtPlwwYIFgfemZs2aUbf59NNPVc0PPRPRYedW2FyYsEJr/rACtvx5W0TPpVZ4tTXftmvXLtC2Qjqt7az53N9XK0TR2nd/PrdeB2u7U30dwrwHseafM1mfaSvkNjU1VdUmT54caHfv3j3UPvjzlvV8Vi23YzgM65huza/WuAszl1kBic8++2yg7Z9vioi8/vrrqvbFF1+oWqdOnQLtOXPmRN2nksS/BrDO17Zt26ZqVmCvH5pphQ2HCYq2xtz+/ftVzTrXCxPiiILnHw/8Y7WIyIEDB6JuJ6LPwa1rT6vmHxet80trXrOOb36wbEk7jytswh6jfK1btw71+P48Y53XWWPAn7Os65caNWqo2q9//euo+9S0aVNVW716tapZ53/FRbNmzQLnOv5xqn///mqbDRs2qJp1vPEDrK0waWue8d9zaxxaIc3WGI62TyL6OCyix+fixYtVnxkzZqiaNYZvu+22QHvlypWqz7p166Lua2ZmpupjsY7z/jlCzjnZujYrKqyxEWbessYiCifOSAEAAAAAAAAAQExwEwIAAAAAAAAAAMQENyEAAAAAAAAAAEBMcBMCAAAAAAAAAADERLELprZCcIcPH65qhw4dUjU/iMYKmLECdTt37hxoW+FKn332maoNHDhQ1azwOgTNmzcv0F64cKHqc++996qa9b74oT1hw539IKAzzjhD9fnPf/6jalaAdUlkBZf5IVk5g3OdcyUqbGjr1q2q5geoWaFfVtBlmMBKK7yqa9euUffT2s4KerOCtv1QRSuAszCE9OYnP3xy/vz5gfb111+vtklOTla1adOmqZr/vlgBq1ZwqT9+kpKSVJ9KlSqpmhUk5x8/ExMTQ23nB8Zu2rRJ9bHChq2x74/ZsGHS/li0XquwIXD+WM8ZRBomrDbWzjnnnEDbes/9AFQRkfr166uaH7LaqlWrUPvgv5Zhw6TD9LPeO2uu8WvWY1vzlsUf19YYa9++var5c3XVqlVVHysYeePGjapmvWf4Hz+A3RonYeeZCy64INB++umnT3Pv/se6frE+o37AvDV2UPD8Od86jlg1K6zaD5S23nPr/Nufj/xjrog911nXVf5nxArQ3rNnj6ohNqwwV//6oW3btqpPzmuwbNb77R/jw54HVahQIdBOS0tTfXI7b1rB6lbge3FWpkyZwHmHfx1Wr149tY0V5Gy95/5cYJ2ThxkH1lxkBVP7xzJrH6x5xjpW7tixI+p+rl+/XtWsgOl33nkn0LaC1L/44gtVq1u3bqCdkpKi+ljnGtZnuVmzZoF2znFelIOpUfzxlxAAAAAAAAAAACAmuAkBAAAAAAAAAABigpsQAAAAAAAAAAAgJopdJoS15r61Hpu1/m/NmjWjPn7fvn2jbmetG/eb3/xG1Z577jlVIxMiOv81uvbaa0NtZ62H7K+5F3ataH8tQmv9QGsdxTDCrvWfV9sVBGudwvfff78A9qRwstbj9dcUt9bntdbEtB7LX/919OjRp7aD/7/nn39e1S688EJVs9b/9T9r1rraYdeBL67uuuuuQHvOnDmqz969e1Vt0aJFqtazZ89A21oP1lrP1M97sOYUK8fBWn/Xz2yyns8a1/4asVbejpUHZR3T/f235k1r3VV/LIbdznpt/POU/fv3qz4Fyc8LsX5Wf11dEZ1hYrHWKA+zVnPY7AXrGB6mj/UzhnnOMM8nos8jdu7cqfpY49XPfAm7VrE1Fq2sIZyYdez01zE/kZYtW0btk9vzM2ushnn8wjbP4L9SU1MDbeuYYdWs+cn/3FtjLLfjzpqnw2Sk1K5dW/VhLjp1Ya7xrGwYa419f8xZGUXff/+9qlmZb/569lbWl5Uv4e+Dle/49ddfq1oYc+fOVTUrf6A4W716dWDM+LkKVl6C9T1JrVq1VM1/La08MGu8+udBVl5g2HOXzMzMkz62iP0z+t8/WGPa2nd/vIroPK527dqpPldffbWq+XO3lTdr/Tzbt29XNf8zv2zZssj/kwmBwoy/hAAAAAAAAAAAADHBTQgAAAAAAAAAABAT3IQAAAAAAAAAAAAxwU0IAAAAAAAAAAAQE8UumNoPVBSxg3YmTJigan7AZ3p6uupjBb/6gZhW4KAf3CRiBzX5gU5WMB6CwoasWYE+ecUad7mV29C4whpCjVNnBY36768VVGgFWVnzzKZNmwLtN95441R3UURE/vrXv6pav379VM0K8/T31QpZDBtGW1z5878VcGYF47Zp00bV/OPbl19+GfX5RHSwmRV0Vq5cuajbiegQS+v9tfYhTEC5Ferrj3MRHai8b98+1cfaLz9Az/r5rHBHa162gtoLk6VLlwbaAwYMUH2efPJJVevQoUPUx7bGivX++sGH1nYW6/X25xrrMxMmDDbMmA4rbBC2/5yff/656rNq1SpVe+KJJ1Tt/vvvP4U9xJQpU1Rt2LBhqmaFXzZu3Djq41vH6zCsx7aC4v1rk8I+75RUfqirNYf5obIi9nmVX/NDokXsMFh/fg0TRitiXxNv3rw50LbOQXHqwlzjnXnmmapWrVo1VTtw4ECgbY0Tq2a9334/P6xXRKRSpUqq5vebOHGi6pNbGzduVDXr+Jrb43dR4M/3fvC3ddxKS0tTNf/aQUS/n9b8FGbOskLMrffECo/2t7XGXZj9Sk5ODrUP1vc8/piaN2+e6mOFdvvXHdZ1jzVPW8dw//3JeS5Q0q+hUbjxlxAAAAAAAAAAACAmuAkBAAAAAAAAAABigpsQAAAAAAAAAAAgJrgJAQAAAAAAAAAAYqLYBVMfO3ZM1awwQSsQ7vLLLw+0rRColStXqpofwmUF+8yaNUvVrDAcguMAbNiwQdV+/PHHQNsKwbXmv6pVq6raAw88EHUfrPBWf95csWKF6mOFF1o1a199xTk0Lgw/PNAPDBaxg8dWr16tav5rab0nVvivH+JmbWcdY48cOaJqftCvdRy2xoUfsGoFTiPv+KGk1vtrhY2G+UxbwZbW59yff6z5zmKdt/k1a9yFOU+0trPGudXPD6K2Xj+r9vPPPwfazZs3D7UPlvPOOy/Q/uyzz0JtV1J9++23qjZkyBBVCzue8sr8+fNVrWnTpqrmfx6tkE4UvBo1agTa1hxmzZFWcLAf4GqFV1vnDP5zpqamqj7WHOwf00X0OUKDBg1UH+uaGCdnfbfgf6at19o6l/dZc1iY99Z6/F9++UX1adGiharNnTs30N65c2fU/TwR//hqhSlbtTBh38WFH348Z84c1Wf58uWqlpSUpGr16tULtGvWrKn6WOH2/jWGFVge9trEn+usoO2cIc3Zdu3aFWhb85p/7SUi0qhRI1Xz9986B7b2y/8Zrc+aVbP472vOc0brcw0UFvwlBAAAAAAAAAAAiAluQgAAAAAAAAAAgJjgJgQAAAAAAAAAAIgJbkIAAAAAAAAAAICYKHbB1Jb169er2sCBA1XND3CdPXu26uMHiImIdO3aNdCeOnWq6tOjRw9VswJzSlJIEgCbFSR3xhlnBNpWKLQV3mWFxL366qtR9yG3gVb//ve/VS0jI0PV/JC4+vXrqz5LlizJ1T4UVxs3bizoXUAJ4AfXN2zYUPW58cYbVc0/h7IkJyermh8qKaID/6y5zQpYtWr+XGY9lrUP/vmY1ceaq61AQT/80AroDhPU3qVLF9WnZcuWqmYF0o4YMSLQJpj65DIzM1XNCg+33u8BAwbk6jn9MRb2msC6NvEDywmmLpz89/jss89WffwgWBGRgwcPqpo1R/n27Nmjav58Yc1PVs36PPjj7PPPP4+6T4jOCnf2w3/btm2r+lgh4/7YOXr0qOrjzx8i9vHVD02vVq2a6mOduz799NOq5gtzXLb69ezZU/XheiI6a26watb3aj4/OFpEHyutY6cV7mzxt923b5/qY43h3LLGoj/XWZ8jazvrc+Szzi2tx/JfL8KoUVTwlxAAAAAAAAAAACAmuAkBAAAAAAAAAABigpsQAAAAAAAAAAAgJkpEJsS//vUvVatdu7aqffnll4F2UlKS6vPtt9+q2rRp0wJta01Ga223L774Qu8sgBJv1apVqtauXbuo21lrxlrrQFvrVoYRZr3q3/72t6q2adMmVXv//fcDbSvjwlrzGEBsTZgwIdBeuHCh6mOtQb958+aoj33VVVep2rx581StSZMmgbaVGRMfH69qYdYyP3TokOpjzWX+2rrWY1s/s7Vesp8vYM3x1vmlz88GErH33TrHtXLOcGLWuHz55ZdV7cCBA6q2ZcuWXD1nmAyIJ598UtUWLVqkav6609OnT8/VPiG2hg4dGmj37dtX9Rk0aJCqWfk6/rWmtU56lSpVVC0xMTHQttYVtzJSPvzwQ1V78MEHVQ2nz/+uwfLxxx+rmp+vJKLHTkpKiupj5X1YNT/fzcp/yG0uSJj8BxE9Xtu3b5+r50PesY6LRZk1FmN5jRomNwIoyvhLCAAAAAAAAAAAEBPchAAAAAAAAAAAADHBTQgAAAAAAAAAABAToTIhwqxRWpgdO3ZM1aw10f3116ztrHUy/dfH2u7w4cNRn68oyY8xUdTHHfJerMdEYR5zYeYLa14rXbp0nu1DmNfHmiPDzH+F+bUvyeMOBaMgj7H+Z/jIkSOqzy+//KJqVr8wz2lt588Z1tq71rmWNU/6tdxmQliPbe2XNd/5r5c1V1tzp8/aB2vfrdcmzJhirvsf6/2wxo5Vsz4fecUaO9Y++PsfZnwVBK4ngqzPrvX+WnOPnwlhbWdl6ezfvz/qPljPF8txHmvFca4LcxwT0e+vNadYx+UwNWvs5KWi9Fm2FMdxh8KNYywKQrQxEedCjJqNGzdKWlpanu0Uir4NGzZI3bp1Y/ocjDv4Yj3uGHOwMO6Q3zjGoiAw1yG/MdehIDDXoSAw7pDfOMaiIEQbd6FuQmRlZcnmzZulUqVKEhcXl6c7iKLFOSf79u2TlJQU9Rs3eY1xh2z5Ne4Yc8iJcYf8xjEWBYG5DvmNuQ4FgbkOBYFxh/zGMRYFIey4C3UTAgAAAAAAAAAA4FQRTA0AAAAAAAAAAGKCmxAAAAAAAAAAACAmuAkBAAAAAAAAAABigpsQAAAAAAAAAAAgJrgJAQAAAAAAAAAAYoKbEAAAAAAAAAAAICa4CQEAAAAAAAAAAGLi/wPmPVhW/n87uwAAAABJRU5ErkJggg==",
      "text/plain": [
       "<Figure size 2000x500 with 10 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "print(\"The train set contains {} images, in {} batches\".format(len(train_loader.dataset), len(train_loader)))\n",
    "print(\"The validation set contains {} images, in {} batches\".format(len(valid_loader.dataset), len(valid_loader)))\n",
    "print(\"The test set contains {} images, in {} batches\".format(len(test_loader.dataset), len(test_loader)))\n",
    "nsamples = 10\n",
    "classes_names = ['T-shirt/top', 'Trouser', 'Pullover', 'Dress', 'Coat', 'Sandal','Shirt', 'Sneaker', 'Bag', 'Ankle boot']\n",
    "imgs_test, labels = next(iter(train_loader))\n",
    "fig = plt.figure(figsize=(20,5))\n",
    "for i in range(nsamples):\n",
    "    ax = plt.subplot(1,nsamples, i+1)\n",
    "    plt.imshow(imgs_test[i, 0, :, :], vmin=0, vmax=1.0, cmap=matplotlib.cm.gray)\n",
    "    ax.set_title(\"{}\".format(classes_names[labels[i]]), fontsize=15)\n",
    "    ax.get_xaxis().set_visible(False)\n",
    "    ax.get_yaxis().set_visible(False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a name=\"architecture\"></a>\n",
    "\n",
    "### Define the deep autoencoding architecture\n",
    "\n",
    "First, we will define the deep autoencoder architecture as a guideline to what we are aiming to train by creating a custom nn.Module class. The autoencoder will have multiple hidden layers in both the encoder and decoder."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [],
   "source": [
    "class DeepAutoencoder(nn.Module):\n",
    "    def __init__(self):\n",
    "        super(DeepAutoencoder, self).__init__()\n",
    "        # Encoder\n",
    "        self.encoder = nn.Sequential(\n",
    "            nn.Linear(28 * 28, 128),\n",
    "            nn.BatchNorm1d(128),\n",
    "            nn.ReLU(),\n",
    "            nn.Dropout1d(0.3),\n",
    "            nn.Linear(128, 128),\n",
    "            nn.ReLU(),\n",
    "            nn.Dropout1d(0.3),\n",
    "            nn.Linear(128, 64),\n",
    "            nn.ReLU(),\n",
    "            nn.Dropout1d(0.3),\n",
    "            nn.Linear(64, 64),\n",
    "            nn.ReLU(),\n",
    "            nn.Dropout1d(0.3),\n",
    "            nn.Linear(64, 32),\n",
    "            nn.ReLU()\n",
    "        )\n",
    "        # Decoder\n",
    "        self.decoder = nn.Sequential(\n",
    "            nn.Linear(32, 64),\n",
    "            nn.ReLU(),\n",
    "            nn.Linear(64, 64),\n",
    "            nn.ReLU(),\n",
    "            nn.Linear(64, 128),\n",
    "            nn.ReLU(),\n",
    "            nn.Linear(128, 128),\n",
    "            nn.ReLU(),\n",
    "            nn.Linear(128, 28 * 28),\n",
    "            nn.Sigmoid()\n",
    "        )\n",
    "\n",
    "    def forward(self, x):\n",
    "        x = self.encoder(x)\n",
    "        x = self.decoder(x)\n",
    "        return x"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a name=\"pretraining\"></a>\n",
    "### Layer-wise pretraining\n",
    "\n",
    "In this section, we will perform layer-wise pretraining of the deep autoencoder. We will train each layer individually as a shallow autoencoder, with its own encoder and decoder.\n",
    "\n",
    "***\n",
    "\n",
    "<div class=\"alert alert-success\" markdown=\"1\" style=\"color:white; background-color: #013220; border-color: #03C03C\">\n",
    "\n",
    "> ### Question 1.1 - Implementing the **layer-wise pretraining**\n",
    "\n",
    "> 1. Complete the `pretrain_layer` function that performs the pretraining of a given layer\n",
    ">    * Define the architecture of a single autoencoder\n",
    ">    * Create a criterion and optimizer\n",
    ">    * **Obtain the encoded features from previously trained layers**\n",
    "> 2. Update the training loop to learn the weights of both layers.\n",
    "\n",
    "</div>\n",
    "\n",
    "***"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "device = \"cpu\"\n",
    "# Function for layer-wise pretraining\n",
    "def pretrain_layer(pretrained_layers, layer_id, layer_in, layer_out, train_loader, num_epochs=50):\n",
    "    \n",
    "    ######################\n",
    "    # YOUR CODE GOES HERE\n",
    "    ######################\n",
    "    # Define the shallow autoencoder architecture\n",
    "    shallow_autoencoder = ...\n",
    "    # Our training criterion and optimizer\n",
    "    criterion = ...\n",
    "    optimizer = ...\n",
    "    \n",
    "    # Training loop\n",
    "    for epoch in range(num_epochs):\n",
    "        for batch_features, _ in train_loader:\n",
    "            \n",
    "            ######################\n",
    "            # YOUR CODE GOES HERE\n",
    "            ######################\n",
    "            # Eventually pass the batch through our previous layers\n",
    "            batch_encoded = ...\n",
    "            # Training loop for a given layer\n",
    "            ...\n",
    "        # Print the corresponding advances\n",
    "        print(f\"Epoch [{epoch+1}/{num_epochs}], Loss: {loss.item():.4f}\")\n",
    "\n",
    "    # Return the trained shallow autoencoder\n",
    "    return shallow_autoencoder\n",
    "\n",
    "# Pretrain each layer of the autoencoder\n",
    "pretrained_layers = []\n",
    "input_sizes = [28 * 28, 128, 128, 64, 64]\n",
    "output_sizes = [128, 128, 64, 64, 32]\n",
    "for i in range(len(input_sizes)):\n",
    "    print(f\"Pretraining layer {i+1}\")\n",
    "    pretrained_layer = pretrain_layer(pretrained_layers, i, input_sizes[i], output_sizes[i], train_loader)\n",
    "    pretrained_layers.append(pretrained_layer)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a name=\"finetuning\"></a>\n",
    "### Fine-tuning the Autoencoder\n",
    "\n",
    "After layer-wise pretraining, we will fine-tune the entire deep autoencoder using the pretrained layers' weights. Note that what we have right now is a set of pretrained layers contained in the `pretrained_layers` array. However, we still need to connect these layers together by **transferring their weights to our full deep autoencoder architecture**.\n",
    "\n",
    "If you check the documentation and code for the `nn.Linear` layer, you can see that the actual weights are stored inside two Tensors respectively named\n",
    "- `layer.weight.data`\n",
    "- `layer.bias.data`\n",
    "\n",
    "***\n",
    "\n",
    "<div class=\"alert alert-success\" markdown=\"1\" style=\"color:white; background-color: #013220; border-color: #03C03C\">\n",
    "\n",
    "> ### Question 1.2 - Finetuning the autoencoder\n",
    "\n",
    "> 1. Transfer the weights from the pretrained layers to the full architecture\n",
    "> 2. Fill in the training criterion and optimizer\n",
    "> 2. Finish the training loop to finetune your deep AE\n",
    "  \n",
    "</div>\n",
    "\n",
    "***"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Initialize the deep autoencoder with pretrained weights\n",
    "autoencoder = DeepAutoencoder().to(device)\n",
    "# Load pretrained weights into the deep autoencoder\n",
    "for i, layer in enumerate(autoencoder.encoder):\n",
    "    if isinstance(layer, nn.Linear):\n",
    "        ######################\n",
    "        # YOUR CODE GOES HERE\n",
    "        ######################\n",
    "        layer.weight.data = ...\n",
    "        layer.bias.data = ...\n",
    "\n",
    "for i, layer in enumerate(autoencoder.decoder):\n",
    "    if isinstance(layer, nn.Linear):\n",
    "        ######################\n",
    "        # YOUR CODE GOES HERE\n",
    "        ######################\n",
    "\n",
    "######################\n",
    "# YOUR CODE GOES HERE\n",
    "######################\n",
    "# Fine-tune the deep autoencoder\n",
    "criterion = ...\n",
    "optimizer = ...\n",
    "num_epochs = 100\n",
    "\n",
    "for epoch in range(num_epochs):\n",
    "    for batch_features, _ in train_loader:\n",
    "        ######################\n",
    "        # YOUR CODE GOES HERE\n",
    "        ######################\n",
    "        ...\n",
    "\n",
    "    print(f\"Epoch [{epoch+1}/{num_epochs}], Loss: {loss.item():.4f}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a name=\"visualization\"></a>\n",
    "### Visualizing the Results\n",
    "\n",
    "First, we can visualize the results by comparing input images and their corresponding reconstructed images produced by the deep autoencoder."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "import numpy as np\n",
    "\n",
    "# Function to display images\n",
    "def display_images(images, title):\n",
    "    fig, axes = plt.subplots(nrows=1, ncols=10, figsize=(20, 2))\n",
    "    for i, ax in enumerate(axes):\n",
    "        ax.imshow(images[i].reshape(28, 28), cmap='gray')\n",
    "        ax.axis('off')\n",
    "    plt.suptitle(title, fontsize=16)\n",
    "    plt.show()\n",
    "\n",
    "# Display the input and reconstructed images\n",
    "for batch_features, _ in test_loader:\n",
    "    batch_features = batch_features.view(-1, 28 * 28).to(device)\n",
    "    outputs = autoencoder(batch_features)\n",
    "    input_images = batch_features.cpu().detach().numpy()\n",
    "    reconstructed_images = outputs.cpu().detach().numpy()\n",
    "    display_images(input_images, 'Input Images')\n",
    "    display_images(reconstructed_images, 'Reconstructed Images')\n",
    "    break"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a name=\"finetuning\"></a>\n",
    "### Using the encoder for supervised classification\n",
    "\n",
    "The following question is entirely open, without any specific code guideline to follow. This is aimed at exercising your own problem-solving skills in order to define the code architecture by yourself. Now that we have a finetuned auto-encoder, we would like to use the _encoding_ part for _supervised classification_. As seen in class, this amounts to a form of _transfer learning_. Hence, we need to retrieve the encoder and add extra layers that we will train in a supervised manner (in order to recognize the class of different fashion items).\n",
    "\n",
    "***\n",
    "\n",
    "<div class=\"alert alert-success\" markdown=\"1\" style=\"color:white; background-color: #013220; border-color: #03C03C\">\n",
    "\n",
    "> ### Question 1.3 - Transfer learning for classification\n",
    "\n",
    "> 1. Define the architecture of your target classifier\n",
    "> 2. Transfer the weights from our finetuned encoder\n",
    "> 3. Define the complete training of this classifier\n",
    "> 4. Evaluate your solution\n",
    "  \n",
    "</div>\n",
    "\n",
    "***"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "\n",
    "######################\n",
    "# YOUR CODE GOES HERE\n",
    "######################\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Deep autoencoders using JAX\n",
    "\n",
    "The following is an **optional exercise** in which you can try to implement the same mechanisms in JAX. To speed up the implementation, we propose to rely on the Flax library, which allows an easy definition of models.\n",
    "\n",
    "### Setup and Dataset Preparation\n",
    "\n",
    "First, we need to import the necessary JAX libraries. Note that we will reuse the same dataset as previously, but you will need to _cast the batches_ into a JAX-compliant format."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Import libraries\n",
    "import jax\n",
    "import jax.numpy as jnp\n",
    "from jax import grad, jit, vmap\n",
    "import optax\n",
    "import flax"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a name=\"architecture\"></a>\n",
    "### Autoencoder training\n",
    "\n",
    "Next, we will define the deep autoencoder architecture using the Flax library in JAX.\n",
    "\n",
    "***\n",
    "\n",
    "<div class=\"alert alert-success\" markdown=\"1\" style=\"color:white; background-color: #192841; border-color: #779ecb\">\n",
    "\n",
    "> ### Exercice (optional)\n",
    ">   1. Define your architecture using Flax.\n",
    ">   2. Perform the layerwise pretraining\n",
    ">   3. Transfer the weights to a deep architecture\n",
    ">   4. Finetune and evaluate your model\n",
    "\n",
    "</div>\n",
    "\n",
    "***"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Ellipsis"
      ]
     },
     "execution_count": 25,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import flax.linen as nn\n",
    "\n",
    "# Encoder\n",
    "class Encoder(nn.Module):\n",
    "    \n",
    "    @nn.compact\n",
    "    def __call__(self, x):\n",
    "        ######################\n",
    "        # YOUR CODE GOES HERE\n",
    "        ######################\n",
    "        ...\n",
    "        \n",
    "\n",
    "# Encoder\n",
    "class Decoder(nn.Module):\n",
    "    \n",
    "    @nn.compact\n",
    "    def __call__(self, x):\n",
    "        ######################\n",
    "        # YOUR CODE GOES HERE\n",
    "        ######################\n",
    "        ...\n",
    "        \n",
    "\n",
    "# Autoencoder\n",
    "class Autoencoder(nn.Module):\n",
    "    \n",
    "    @nn.compact\n",
    "    def __call__(self, x):\n",
    "        ######################\n",
    "        # YOUR CODE GOES HERE\n",
    "        ######################\n",
    "        ...\n",
    "\n",
    "######################\n",
    "# YOUR CODE GOES HERE\n",
    "######################\n",
    "# Layerwise pretraining\n",
    "...\n",
    "\n",
    "# Model finetuning\n",
    "...\n",
    "\n",
    "# Model evaluation\n",
    "...\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "VEdCXSwCoKok"
   },
   "source": [
    "# Generative auto-encoder (modern version)\n",
    "\n",
    "As seen in the course, the previous training version of AEs was used for several years, but several advances in **model regularization** now allows to bypass the need for layer-wise training and directly train deep version of the AEs. These advances are _batch normalization_, _ReLU_ activations and _Dropout_. Furthermore, by definition, the AE can already be seen as a form of _generative model_ (although it lacks a probabilistic definition). \n",
    "\n",
    "Therefore, we will define in the following a simple AE seen as a generative model, to directly learn how to compress and reconstruct images from simple small vectors. Hence, we will need an `encoder`, which compresses the images into a small latent vector, and a `decoder`, that reconstructs the original image from this code. Here, we will start very basic and define the encoder and decoder as simple `Linear` layers. Note that we also use `BatchNorm`, `ReLU` and `Dropout` to regularize our training."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "class AE(nn.Module):\n",
    "    def __init__(self, encoding_dim):\n",
    "        super(AE, self).__init__()\n",
    "        self.latent_dim = encoding_dim\n",
    "        self.hidden_dim = 256\n",
    "        self.encoder = nn.Sequential(\n",
    "          nn.Linear(28 * 28, self.hidden_dim),\n",
    "          nn.BatchNorm1d(self.hidden_dim), nn.ReLU(),\n",
    "          nn.Dropout(0.3),\n",
    "          nn.Linear(self.hidden_dim, self.hidden_dim), \n",
    "          nn.BatchNorm1d(self.hidden_dim), nn.ReLU(),\n",
    "          nn.Dropout(0.3),\n",
    "          nn.Linear(self.hidden_dim, self.latent_dim), nn.Sigmoid()\n",
    "        )\n",
    "        self.decoder = nn.Sequential(\n",
    "          nn.Linear(self.latent_dim, self.hidden_dim), \n",
    "          nn.BatchNorm1d(self.hidden_dim), nn.ReLU(),\n",
    "          nn.Dropout(0.3),\n",
    "          nn.Linear(self.hidden_dim, self.hidden_dim), \n",
    "          nn.BatchNorm1d(self.hidden_dim), nn.ReLU(),\n",
    "          nn.Dropout(0.3),\n",
    "          nn.Linear(self.hidden_dim, 28 * 28), nn.Sigmoid()\n",
    "        )\n",
    "\n",
    "    def forward(self, x):\n",
    "        encoded = self.encoder(x.reshape(-1, 28 * 28))\n",
    "        decoded = self.decoder(encoded)\n",
    "        return decoded.reshape(-1, 1, 28, 28)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here we can see that the model depends on a given `encoding_dim` variable, which defines the size of the latent code. Therefore, we can instantiate our model arbitrarliy with `64` dimensions"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "id": "0MUxidpyChjX"
   },
   "outputs": [],
   "source": [
    "latent_dim = 64   \n",
    "model = AE(latent_dim) "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The only remaining part that we did not discuss yet is what type of _loss_ (defined as $\\mathcal{L}$) we can use to train our model. First, we will simply rely on the _Mean Squared Error_ (MSE) loss, which is defined as\n",
    "\\begin{equation}\n",
    "    \\mathcal{L}_{MSE}(\\hat{\\mathbf{x}}, \\mathbf{x}) = \\mid \\hat{\\mathbf{x}}, \\mathbf{x} \\mid^{2}\n",
    "\\end{equation}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "id": "9I1JlqEIDCI4"
   },
   "outputs": [],
   "source": [
    "# Loss function that we will use\n",
    "loss_fn = torch.nn.MSELoss(reduction='sum')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "7oJSeMTroABs"
   },
   "source": [
    "<a id=\"application\"> </a>\n",
    "\n",
    "### Training the model\n",
    "\n",
    "Train the model using `x_train` as both the input and the target. The `encoder` will learn to compress the dataset from 784 dimensions to the latent space, and the `decoder` will learn to reconstruct the original images.\n",
    "."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "id": "h1RI9OfHDBsK"
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "tensor(3343.1089, grad_fn=<MseLossBackward>)\n",
      "tensor(3005.9805, grad_fn=<MseLossBackward>)\n",
      "tensor(2812.6462, grad_fn=<MseLossBackward>)\n",
      "tensor(2727.8533, grad_fn=<MseLossBackward>)\n",
      "tensor(2595.9111, grad_fn=<MseLossBackward>)\n",
      "tensor(2553.7651, grad_fn=<MseLossBackward>)\n",
      "tensor(2544.0669, grad_fn=<MseLossBackward>)\n",
      "tensor(2468.2820, grad_fn=<MseLossBackward>)\n",
      "tensor(2400.9646, grad_fn=<MseLossBackward>)\n",
      "tensor(2364.0288, grad_fn=<MseLossBackward>)\n",
      "tensor(2379.8469, grad_fn=<MseLossBackward>)\n",
      "tensor(2298.6030, grad_fn=<MseLossBackward>)\n",
      "tensor(2324.0264, grad_fn=<MseLossBackward>)\n",
      "tensor(2216.2561, grad_fn=<MseLossBackward>)\n",
      "tensor(2306.3574, grad_fn=<MseLossBackward>)\n",
      "tensor(2223.1157, grad_fn=<MseLossBackward>)\n",
      "tensor(2159.7192, grad_fn=<MseLossBackward>)\n",
      "tensor(2185.4272, grad_fn=<MseLossBackward>)\n",
      "tensor(2213.2729, grad_fn=<MseLossBackward>)\n",
      "tensor(2150.3906, grad_fn=<MseLossBackward>)\n"
     ]
    }
   ],
   "source": [
    "# Learning rate\n",
    "learning_rate = 1e-4\n",
    "# Optimizer to fit the weights of the network\n",
    "optimizer = torch.optim.SGD(model.parameters(), lr=learning_rate)\n",
    "for t in range(20):\n",
    "    full_loss = torch.Tensor([0])\n",
    "    # Forward pass: compute predicted y by passing x to the model.\n",
    "    for i, (x, _) in enumerate(train_loader):\n",
    "        y_pred = model(x)\n",
    "        # Compute the loss.\n",
    "        loss = loss_fn(y_pred, x)\n",
    "        # Before the backward pass, zero all of the network gradients\n",
    "        optimizer.zero_grad()\n",
    "        # Backward pass: compute gradient of the loss with respect to parameters\n",
    "        loss.backward()\n",
    "        # Calling the step function to update the parameters\n",
    "        optimizer.step()\n",
    "    print(loss)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "wAM1QBhtoC-n"
   },
   "source": [
    "Now that the model is trained, we can test it by encoding and decoding images from the test set."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {
    "id": "Pbr5WCj7FQUi"
   },
   "outputs": [],
   "source": [
    "encoded_imgs = model.encoder(imgs_test.reshape(-1,28*28))\n",
    "decoded_imgs = model.decoder(encoded_imgs).reshape(-1,28,28).detach().numpy()\n",
    "\n",
    "#decoded_imgs = model(imgs_test)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "By plotting the images, we can see that the model is able to perform an adequate (yet somewhat blurry) reconstruction of the input images. The interesting point is that this reconstruction comes from a code of only `64` dimensions, whereas the original images have `784` dimensions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {
    "id": "s4LlDOS6FUA1"
   },
   "outputs": [
    {
     "data": {
      "image/png": "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J98p3nzzzVrOPl+4cKGWGf8n98DLL79cyxl/hs/Dce3FdSilPd8yjfjo/3oxqfJ9aBSjieuCaylT6jKmXMYI2mzbu2pGsbBE5G/yDOfeYTnPT8boy7Oe7y20c6P4lfzOmTaPZ1/ei/aW1+X3Fdq8fBbWLSPd/PXEvDE6r1X0xBERERERERERmQD+iCMiIiIiIiIiMgEWklOtra1V17d0EaX72SjNas8VN8l0lXQbpztbpkHl51tvvbWW00Wars/pjkxXN7oIjyRYIwkB20t3L7rR9eqW7SI2ay9d+nqp4Etp5RdM7Zdzzf/L1KSHDh2qZbo1Zppbyq7Yp3TJputiupBzbfH/Pv744+a6999/v9uPHTt21DJlDCnJIjke17rb+BSYgovl6dOnm8/ffvttLX/55ZdNHdf9SP5Cm5Spw/fu3VvLlBmljJX779y5c7Wc0gnKTEYuwPPORV7HNNsvvvhiLb/zzjvNddz3aRM2ex3kObNt27Zavummm2o55TZMFf/11183dZxXum+nLI52mbYsz62cV0IZKe1anq18zjwz2S8+f47NiFXPY76XUOZNiVApl6dQn5F95HvJ6EzotZdwv43et5J5Xc/nlZ2OruOzjOS51xu9OVhkHkWmzEjWxO933AP8XlBKG2ohv6/wnKFdGqUHZ93oPEo715Mx5/5l+5TBl9K+W43upU24nOt9TPTEERERERERERGZAP6IIyIiIiIiIiIyAfwRR0RERERERERkAiwUE2d9fb2rbR6lceNnagbPnDnTXMcUuRn/hJpBpo/bunVr917Hjx/vtke9dqaMZhvUsme8AOoVU/vfiwOxiH4vU+8ti9nzZTwE3i+1+S+99FItM25Gjv/PP/9cyxmv6Omnn77ivRLOL8sJ+5jtsY6xMUbpVzMmzoEDB2qZ8/b8888313FPjHSwIj1GcWQyDscolliPixcvNp8//fTTWmYshtxvIxtHRntgGbAfHI9MG87P88YXWSajZ2f8olJKee6552qZc8oYLKW051PaL85rL310fh7FI2D/R3HeRvPNPu7fv7+pu+WWW2r5rbfequU8n0esWgOf7Z8/f76Wc+zm7cu8sdFG6ahH89u710bTW3Pu533GPOs4p9dD3IJ5x5pztwy7eb2n2F0VjuvqGL0Xs457Jd9hHn/88Vp+8sknmzqemaO4gRcuXKhlfq/h99SE50Ep/bimGZfu1KlTtczvSaX0x8PvD/JP6IkjIiIiIiIiIjIB/BFHRERERERERGQCrC3oJvhrKeXHFfVF+txaStm+pLacw83DeZw+zuG1gfM4fZzDawPncfo4h9cGzuP0cQ6vDeaax0V/xBERERERERERkU1AOZWIiIiIiIiIyATwRxwRERERERERkQngjzgiIiIiIiIiIhPAH3FERERERERERCaAP+KIiIiIiIiIiEwAf8QREREREREREZkA/ogjIiIiIiIiIjIB/BFHRERERERERGQC+COOiIiIiIiIiMgE+D+dUxw+KUrWLwAAAABJRU5ErkJggg==",
      "text/plain": [
       "<Figure size 1440x288 with 20 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "dark"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "n = 10\n",
    "plt.figure(figsize=(20, 4))\n",
    "for i in range(n):\n",
    "    # display original\n",
    "    ax = plt.subplot(2, n, i + 1)\n",
    "    plt.imshow(imgs_test[i, 0])\n",
    "    plt.title(\"original\"); plt.gray()\n",
    "    ax.get_xaxis().set_visible(False)\n",
    "    ax.get_yaxis().set_visible(False)\n",
    "    # display reconstruction\n",
    "    ax = plt.subplot(2, n, i + 1 + n)\n",
    "    plt.imshow(decoded_imgs[i])\n",
    "    plt.title(\"reconstructed\"); plt.gray()\n",
    "    ax.get_xaxis().set_visible(False)\n",
    "    ax.get_yaxis().set_visible(False)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Improvements\n",
    "\n",
    "Even though this very basic example seems to work, several improvements can be made over the original model. First, we can see that the overall framework does not depend on the exact nature of the `encoder` and `decoder`. \n",
    "\n",
    "***\n",
    "\n",
    "<div class=\"alert alert-success\" markdown=\"1\" style=\"color:white; background-color: #192841; border-color: #779ecb\">\n",
    "\n",
    "> ### Exercise (optional)\n",
    ">   1. Rewrite the original class to accept any type of architecture for these (see code below). \n",
    ">   2. Fill the missing code to have a new AE model\n",
    "\n",
    "</div>\n",
    "\n",
    "***"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [],
   "source": [
    "class AE(nn.Module):\n",
    "    def __init__(self, encoder, decoder, encoding_dim):\n",
    "        super(AE, self).__init__()\n",
    "        self.latent_dim = encoding_dim\n",
    "        self.encoder = encoder\n",
    "        self.decoder = decoder\n",
    "\n",
    "    def forward(self, x):\n",
    "        encoded = self.encoder(x)\n",
    "        decoded = self.decoder(encoded)\n",
    "        return decoded\n",
    "\n",
    "######################\n",
    "# YOUR CODE GOES HERE\n",
    "######################\n",
    "\n",
    "encoder = ...\n",
    "decoder = ...\n",
    "model = ..."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Second, we only used the train dataset, whereas the use of a validation and test sets allows to ensure that we do not overfit our model.\n",
    "\n",
    "***\n",
    "\n",
    "<div class=\"alert alert-success\" markdown=\"1\" style=\"color:white; background-color: #192841; border-color: #779ecb\">\n",
    "\n",
    "> ### Exercise (optional)\n",
    ">   1. Write a separate train function, that can be called on different sets\n",
    ">   2. Re-write the training loop to test overfitting\n",
    "\n",
    "</div>\n",
    "\n",
    "***"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [],
   "source": [
    "######################\n",
    "# YOUR CODE GOES HERE\n",
    "######################"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "r4gv6G8PoRQE"
   },
   "source": [
    "## **Optional** exercise: Denoising AE\n",
    "\n",
    "Imagine (for the sake of argument), that we choose an encoding dimension which is of same dimensionality as the input one. Then, one huge problem is that nothing prevents the AE from simply learning the _identity_ function (try to imagine why). An autoencoder can also be trained to remove noise from images. This type of _regularization_ prevents the model from learning this degenerate situation.\n",
    "\n",
    "In this exercise, you will need to create your own denoising AE, by relying on a noisy version of the Fashion MNIST dataset (adding random Gaussian noise to each image). You will then train an autoencoder using the noisy image as input, and the original image as the target.\n",
    "\n",
    "Let's reimport the dataset to omit the modifications made earlier."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "id": "uJZ-TcaqDBr5"
   },
   "outputs": [],
   "source": [
    "class GaussianNoise(object):\n",
    "    def __init__(self, mean=0., std=0.1):\n",
    "        self.std = std\n",
    "        self.mean = mean\n",
    "        \n",
    "    def __call__(self, tensor):\n",
    "        return tensor + torch.randn(tensor.size()) * self.std + self.mean\n",
    "    \n",
    "    def __repr__(self):\n",
    "        return self.__class__.__name__ + '(mean={0}, std={1})'.format(self.mean, self.std)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "aPZl_6P65_8R"
   },
   "source": [
    "Here, we create two new train and test sets by adding random noise to the images"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "id": "axSMyxC354fc"
   },
   "outputs": [],
   "source": [
    "# Load the datasets and use our Gaussian noise transform\n",
    "train_valid_dataset = torchvision.datasets.FashionMNIST(root=dataset_dir, train=True, transform=torchvision.transforms.Compose([torchvision.transforms.ToTensor(), GaussianNoise(0., 0.1)]), download=True)\n",
    "train_dataset, valid_dataset = torch.utils.data.dataset.random_split(train_valid_dataset, [nb_train, nb_valid])\n",
    "test_dataset = torchvision.datasets.FashionMNIST(root=dataset_dir, transform=torchvision.transforms.Compose([torchvision.transforms.ToTensor(), GaussianNoise(0., 0.1)]),train=False)\n",
    "# Create loaders\n",
    "train_loader_noisy = torch.utils.data.DataLoader(dataset=train_dataset, batch_size=batch_size, num_workers=num_threads)\n",
    "valid_loader_noisy = torch.utils.data.DataLoader(dataset=valid_dataset, batch_size=batch_size, shuffle=False, num_workers=num_threads)\n",
    "test_loader_noisy = torch.utils.data.DataLoader(dataset=test_dataset,batch_size=batch_size,shuffle=False,num_workers=num_threads)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "wRxHe4XXltNd"
   },
   "source": [
    "Plot the noisy images.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "id": "thKUmbVVCQpt"
   },
   "outputs": [
    {
     "data": {
      "image/png": "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m9deey0ilmx77ItlbZbbtC2091mb91P7Pdc6ZWMg73vZ+ojtTq+Z/tY+xmOwDek5ca1fNB9HRAwdOrTTfmzay59XXnklvvjFL0ZExLrrrpttmzZtWrIHDx6cbeNCYu211072lltume3XaGQREZtvvnm27fbbb0923759k60NoU+fPsl+/fXXk62NjIusddZZJ9v21FNPJbvswX6jjRb7pbH4b7Djjjsm+8EHH0z2xhtvnO236aabJvuuu/LKdI1z/P3vfx/rrbdeNIOXX345Pve5z0XEkoMhF6j9+/df4nsNuHDT+8rzfPrpp7Nt9HdjkRYRMWTIkGw/3v+BAwcm+8UXX8z240Ci7aXxYiQi75S6QOV56P3YZJNNkv3WW28lW9s+74G2R07wM2fOnB5NYvr06bHLLrtERMSee+6ZbePC5LHHHsu2FfUdHQxfeOGFZOuDxgYbbL8n1soAACAASURBVJDsAQMGJPuv//qvs/2mTp2abPr4ySefzPZ75513ks3+G5FPeFtssUWyTz311Gy/oofbiIj33nsv2fQp23tExBtvvJFsXSA1+un555+/hP87yqxZs+L73/9+RERMnjw528Z+NGPGjGwb7+Xbb7+d7LKXkltvvXW2jb5n3xk3bly236OPPprsN998M9nDhw/P9mPf1HvHsXH27NltfkfPv70PMjruEu2LHPNvvPHGpvXFWbNmxSmnnBIR5XOJvrDs169fsukr9puIiGHDhiVb7+0222yTbN7PoUOHZvtx/N5jjz3a/HtE3id22GGHbBv7La9LX1Y9//ziyqOcIyPycZRtnH1Pv6d+bIw/55577hL3u6O88sorcdxxx0XEkot/fua8EpHPGZzzdTHM/q33hHPS9773vWSPGTMm2+/dd99N9t13311wJfn8rGM3x0aeI9chERGHHXZYm9+JyNdVhO0qIp9DeO4R+Rh2/fXXN6Uv0ofarjl36EMVr533RPsafV+23uMxdH3Ee7LbbrslW9cenGM4f0XkaxaOp2UvBDlnR+QPMU888USyOd9G5PdAH3Y49jTLhxERr776alpL6EMu2yLXDRG5XzlX6XnzXug/PPJhjHOrPqvsvffeyeb8qefEh2A+30Tk4zzbha5LuAbm2BqR+5/XpS8jeQ/0fvCab7755qb48aWXXkpjiI53Rf+oGlG8ntH1AP+h8fHHH8+2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",
      "text/plain": [
       "<Figure size 1440x288 with 20 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "dark"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "x_test, labels = next(iter(test_loader))\n",
    "x_test_noisy, labels = next(iter(test_loader_noisy))\n",
    "n = 10\n",
    "plt.figure(figsize=(20, 4))\n",
    "for i in range(n):\n",
    "    ax = plt.subplot(2, n, i + 1)\n",
    "    plt.title(\"original\")\n",
    "    plt.imshow(x_test[i].squeeze())\n",
    "    ax.get_xaxis().set_visible(False)\n",
    "    ax.get_yaxis().set_visible(False)\n",
    "    plt.gray()\n",
    "    ax = plt.subplot(2, n, i + 1 + n)\n",
    "    plt.title(\"original + noise\")\n",
    "    plt.imshow(x_test_noisy[i].squeeze())\n",
    "    ax.get_xaxis().set_visible(False)\n",
    "    ax.get_yaxis().set_visible(False)\n",
    "    plt.gray()\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "Sy9SY8jGl5aP"
   },
   "source": [
    "### Define a convolutional autoencoder"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "vT_BhZngWMwp"
   },
   "source": [
    "In this example, you will train a convolutional autoencoder using  [Conv2D](https://www.tensorflow.org/api_docs/python/tf/keras/layers/Conv2D) layers in the `encoder`, and [Conv2DTranspose](https://www.tensorflow.org/api_docs/python/tf/keras/layers/Conv2DTranspose) layers in the `decoder`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {
    "id": "R5KjoIlYCQko"
   },
   "outputs": [],
   "source": [
    "######################\n",
    "# YOUR CODE GOES HERE\n",
    "######################\n",
    "\n",
    "class DenoisingAE(AE):\n",
    "    def __init__(self):\n",
    "        super(DenoisingAE, self).__init__()\n",
    "        self.encoder = ...    \n",
    "        self.decoder = ...\n",
    "    \n",
    "    def forward(self, x):\n",
    "        encoded = ...\n",
    "        decoded = ...\n",
    "        return decoded\n",
    "\n",
    "autoencoder = ..."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Write down the full optimization loop to optimize your denoising auto-encoder"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "id": "QYKbiDFYCQfj"
   },
   "outputs": [],
   "source": [
    "######################\n",
    "# YOUR CODE GOES HERE\n",
    "######################"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "A7-VAuEy_N6M"
   },
   "source": [
    "Plot both the noisy images and the denoised images produced by the autoencoder to check that your implementation is correct"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {
    "id": "sfxr9NdBCP_x",
    "tags": []
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<Figure size 1440x288 with 0 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "######################\n",
    "# YOUR CODE GOES HERE\n",
    "######################\n",
    "encoded_imgs = ...\n",
    "decoded_imgs = ...\n",
    "plt.figure(figsize=(20, 4))\n",
    "for i in range(n):\n",
    "    ...\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Attention layers and Transformers\n",
    "\n",
    "In the following exercise, we aim to implement attention layers and Transformers in PyTorch. Transformers are a powerful deep learning architecture that has been used to achieve state-of-the-art results in various natural language processing tasks. \n",
    "\n",
    "***\n",
    "\n",
    "<div class=\"alert alert-success\" markdown=\"1\" style=\"color:white; background-color: #410819; border-color: #cb2e47\">\n",
    "\n",
    "> **Warning on the exercise difficulty and goal**\n",
    "\n",
    "> **Note that this exercise is a lot more involved, as we now move on to an almost research-level type of exercise, where we mostly provide a research paper as reference. Your goal is to try to reimplement the architecture and method proposed in that paper as closely as possible.**\n",
    "\n",
    "#### Paper reference\n",
    "\n",
    "[Vaswani, A., Shazeer, N., Parmar, N., Uszkoreit, J., Jones, L., Gomez, A. N., ... & Polosukhin, I. (2017). Attention is all you need. Advances in neural information processing systems, 30.](https://proceedings.neurips.cc/paper/2017/file/3f5ee243547dee91fbd053c1c4a845aa-Paper.pdf)\n",
    "\n",
    "**Link:** [https://proceedings.neurips.cc/paper/2017/file/3f5ee243547dee91fbd053c1c4a845aa-Paper.pdf](https://proceedings.neurips.cc/paper/2017/file/3f5ee243547dee91fbd053c1c4a845aa-Paper.pdf)\n",
    "\n",
    "</div>\n",
    "\n",
    "***\n",
    "\n",
    "<a name=\"intro\"></a>\n",
    "## Introduction to attention\n",
    "\n",
    "Attention mechanisms enable models to focus on specific parts of the input sequence while processing it. They have been proven to be highly effective in natural language processing tasks such as machine translation and sentiment analysis. Transformers are a type of deep learning model that incorporates self-attention mechanisms. They consist of an encoder and a decoder, and utilize multi-head attention layers, positional encoding, and layer normalization."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "### Defining our own attention layer\n",
    "\n",
    "In the following, we re-implement the *attention* layer, which is the basis of the infamous `Transformer` models.\n",
    "\n",
    "<div class=\"alert alert-success\" markdown=\"1\" style=\"color:white; background-color: #410819; border-color: #cb2e47\">\n",
    "\n",
    "> This is defined in Section 3.2.1 (pages 3 and 4) and depicted in Figure 2 (left) of our [paper reference.](https://proceedings.neurips.cc/paper/2017/file/3f5ee243547dee91fbd053c1c4a845aa-Paper.pdf)\n",
    "\n",
    "</div>\n",
    "\n",
    "\n",
    "***\n",
    "\n",
    "<div class=\"alert alert-success\" markdown=\"1\" style=\"color:white; background-color: #192841; border-color: #779ecb\">\n",
    "\n",
    "> ### Exercise (**course**)\n",
    ">   1. Implement the simple attention layer as defined in the slides\n",
    "\n",
    "</div>\n",
    "\n",
    "***"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [],
   "source": [
    "class AttentionLayer(nn.Module):\n",
    "    def __init__(self, n_hidden):\n",
    "        super(AttentionLayer, self).__init__()\n",
    "        ######################\n",
    "        # YOUR CODE GOES HERE \n",
    "        ######################\n",
    "        ...\n",
    "\n",
    "    def forward(self, X):\n",
    "        ######################\n",
    "        # YOUR CODE GOES HERE \n",
    "        ######################\n",
    "        ...\n",
    "    \n",
    "\n",
    "######################\n",
    "# Solution: \n",
    "class AttentionLayer(nn.Module):\n",
    "    def __init__(self, n_hidden):\n",
    "        super(AttentionLayer, self).__init__()\n",
    "        self.mlp = nn.Linear(n_hidden, n_hidden)\n",
    "        self.u_w = nn.Parameter(torch.rand(n_hidden))\n",
    "\n",
    "    def forward(self, X):\n",
    "        # get the hidden representation of the sequence\n",
    "        u_it = F.tanh(self.mlp(X))\n",
    "        # get attention weights for each timestep\n",
    "        alpha = F.softmax(torch.matmul(u_it, self.u_w), dim=1)\n",
    "        # get the weighted sum of the sequence\n",
    "        out = torch.sum(torch.matmul(alpha, X), dim=1)\n",
    "        return out, alpha\n",
    "######################"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "<a name=\"setup\"></a>\n",
    "## Setup and dataset\n",
    "\n",
    "First, let's import the necessary libraries and prepare the dataset for training. We will now rely on a text dataset, which is readily available in the `torchtext` library."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {},
   "outputs": [],
   "source": [
    "import torch\n",
    "import torch.nn as nn\n",
    "import torch.optim as optim\n",
    "import torch.nn.functional as F\n",
    "from torchtext.datasets import Multi30k\n",
    "# Translate English to German\n",
    "language_pair = (\"en\", \"\")\n",
    "# Import the text dataset\n",
    "train_iterator, valid_iterator, test_iterator = Multi30k(split=(\"train\", \"valid\", \"test\"), language_pair=language_pair)\n",
    "# Potentially use the GPU if available\n",
    "device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a name=\"mha\"></a>\n",
    "### Implementing the Multi-Head Attention layer\n",
    "\n",
    "The multi-head attention layer is a key component of the Transformer architecture. It allows the model to focus on different parts of the input sequence simultaneously.\n",
    "\n",
    "<div class=\"alert alert-success\" markdown=\"1\" style=\"color:white; background-color: #410819; border-color: #cb2e47\">\n",
    "\n",
    "> This is defined in Section 3.2.2 (pages 4 and 5) and depicted in Figure 2 (right) of our [paper reference.](https://proceedings.neurips.cc/paper/2017/file/3f5ee243547dee91fbd053c1c4a845aa-Paper.pdf)\n",
    "\n",
    "</div>\n",
    "\n",
    "***\n",
    "\n",
    "<div class=\"alert alert-success\" markdown=\"1\" style=\"color:white; background-color: #013220; border-color: #03C03C\">\n",
    "\n",
    "> ### Question 2.1 - Implementing the multi-head attention layer\n",
    "\n",
    "> 1. Following the definitions in the paper, propose your implementation of the _multi-head attention layer_.\n",
    "  \n",
    "</div>\n",
    "\n",
    "***"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [],
   "source": [
    "class MultiHeadAttentionLayer(nn.Module):\n",
    "    def __init__(self, hid_dim, n_heads, dropout, device):\n",
    "        super().__init__()\n",
    "        ######################\n",
    "        # YOUR CODE GOES HERE \n",
    "        ######################\n",
    "        ...\n",
    "\n",
    "    def forward(self, query, key, value, mask=None):\n",
    "        ######################\n",
    "        # YOUR CODE GOES HERE \n",
    "        ######################\n",
    "        ..."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a name=\"transformer\"></a>\n",
    "### Building the Transformer architecture\n",
    "\n",
    "Now that we have implemented the multi-head attention layer, we can build the Transformer architecture. We'll need to create the encoder, decoder, and the final Transformer model.\n",
    "\n",
    "<div class=\"alert alert-success\" markdown=\"1\" style=\"color:white; background-color: #410819; border-color: #cb2e47\">\n",
    "\n",
    "> The transformer architecture is defined in Section 3.1 (pages 2 and 3) and depicted in Figure 1 of our [paper reference.](https://proceedings.neurips.cc/paper/2017/file/3f5ee243547dee91fbd053c1c4a845aa-Paper.pdf). Also more details about the architecture are provided in subsequent sections 3.3 to 3.5.\n",
    "\n",
    "</div>\n",
    "\n",
    "***\n",
    "\n",
    "<div class=\"alert alert-success\" markdown=\"1\" style=\"color:white; background-color: #013220; border-color: #03C03C\">\n",
    "\n",
    "> ### Question 2.2 - Implementing the Transformer architecture\n",
    "\n",
    "> 1. Following the definitions in the paper, propose your implementation of the _transformer architecture_.\n",
    "> 2. (Optional) Implement the other parts of the architecture (sections 3.3 to 3.5).\n",
    "  \n",
    "</div>\n",
    "\n",
    "***"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Encoder Layer\n",
    "class EncoderLayer(nn.Module):\n",
    "    def __init__(self, hid_dim, n_heads, pf_dim, dropout, device):\n",
    "        ...\n",
    "\n",
    "# Decoder Layer\n",
    "class DecoderLayer(nn.Module):\n",
    "    def __init__(self, hid_dim, n_heads, pf_dim, dropout, device):\n",
    "        ...\n",
    "\n",
    "# Encoder\n",
    "class Encoder(nn.Module):\n",
    "    def __init__(self, input_dim, hid_dim, n_layers, n_heads, pf_dim, dropout, device, max_length=100):\n",
    "        ...\n",
    "\n",
    "# Decoder\n",
    "class Decoder(nn.Module):\n",
    "    def __init__(self, output_dim, hid_dim, n_layers, n_heads, pf_dim, dropout, device, max_length=100):\n",
    "        ...\n",
    "\n",
    "# Transformer\n",
    "class Transformer(nn.Module):\n",
    "    def __init__(self, encoder, decoder, device):\n",
    "        ..."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a name=\"training\"></a>\n",
    "### Training the Transformer Model\n",
    "\n",
    "After building the Transformer architecture, we can train the model using the dataset prepared in section 2. Note that this exercise is left optional, as this requires several notions not covered in the course yet (embeddings, positional encodings). However, this is of course more rewarding to see your model being trained :)\n",
    "\n",
    "***\n",
    "\n",
    "<div class=\"alert alert-success\" markdown=\"1\" style=\"color:white; background-color: #192841; border-color: #779ecb\">\n",
    "\n",
    "> ### Exercise (**optional**)\n",
    ">   1. Implement the training loop for the Transformer.\n",
    "\n",
    "</div>\n",
    "\n",
    "***"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Initialize the Transformer model\n",
    "INPUT_DIM = ...\n",
    "OUTPUT_DIM = ...\n",
    "HID_DIM = 256\n",
    "ENC_LAYERS = 3\n",
    "DEC_LAYERS = 3\n",
    "ENC_HEADS = 8\n",
    "DEC_HEADS = 8\n",
    "ENC_PF_DIM = 512\n",
    "DEC_PF_DIM = 512\n",
    "ENC_DROPOUT = 0.1\n",
    "DEC_DROPOUT = 0.1\n",
    "\n",
    "enc = Encoder(INPUT_DIM, HID_DIM, ENC_LAYERS, ENC_HEADS, ENC_PF_DIM, ENC_DROPOUT, device)\n",
    "dec = Decoder(OUTPUT_DIM, HID_DIM, DEC_LAYERS, DEC_HEADS, DEC_PF_DIM, DEC_DROPOUT, device)\n",
    "\n",
    "model = Transformer(enc, dec, device).to(device)\n",
    "\n",
    "# Train the model\n",
    "optimizer = optim.Adam(model.parameters())\n",
    "criterion = nn.CrossEntropyLoss()\n",
    "\n",
    "def train(model, iterator, optimizer, criterion, clip):\n",
    "    ...\n",
    "\n",
    "def evaluate(model, iterator, criterion):\n",
    "    ...\n",
    "\n",
    "def epoch_time(start_time, end_time):\n",
    "    ...\n",
    "\n",
    "N_EPOCHS = 10\n",
    "CLIP = 1\n",
    "\n",
    "best_valid_loss = float('inf')\n",
    "\n",
    "for epoch in range(N_EPOCHS):\n",
    "    \n",
    "    start_time = time.time()\n",
    "    \n",
    "    train_loss = train(model, train_iterator, optimizer, criterion, CLIP)\n",
    "    valid_loss = evaluate(model, valid_iterator, criterion)\n",
    "    \n",
    "    end_time = time.time()\n",
    "    \n",
    "    epoch_mins, epoch_secs = epoch_time(start_time, end_time)\n",
    "    \n",
    "    if valid_loss < best_valid_loss:\n",
    "        best_valid_loss = valid_loss\n",
    "        torch.save(model.state_dict(), 'transformer-model.pt')\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: {math.exp(train_loss):7.3f}')\n",
    "    print(f'\\t Val. Loss: {valid_loss:.3f} |  Val. PPL: {math.exp(valid_loss):7.3f}')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a name=\"evaluation\"></a>\n",
    "### Evaluating the Model\n",
    "\n",
    "After training the Transformer model, we can evaluate its performance on the test dataset."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Load the best model\n",
    "model.load_state_dict(torch.load('transformer-model.pt'))\n",
    "# Evaluate the model on the test dataset\n",
    "test_loss = evaluate(model, test_iterator, criterion)\n",
    "print(f'| Test Loss: {test_loss:.3f} | Test PPL: {math.exp(test_loss):7.3f} |')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# **Optional fun** - Style transfer \n",
    "\n",
    "Style transfer is the technique of applying the style of one image to the content of another, creating a new image with the desired content and style. The following exercise aims at replicating the results of the original [Neural style transfer paper](https://arxiv.org/abs/1508.06576) by Gatys et al. \n",
    "\n",
    "Note that the following tutorial is a plain simplification inspired by the great [tutorial available in the Pytorch documentation](https://pytorch.org/tutorials/advanced/neural_style_tutorial.html). Hence, all credits goes back to the authors of the tutorial.\n",
    "\n",
    "## Introduction to Style Transfer\n",
    "\n",
    "Style transfer is a technique in computer vision and deep learning that enables the transfer of artistic style from one image (style image) to another image (content image) while retaining the original content. This is typically achieved using a pre-trained deep neural network, such as VGG-19, and optimizing the input image to minimize the content and style losses.\n",
    "\n",
    "<a name=\"setup\"></a>\n",
    "## Import images\n",
    "\n",
    "First, let's import the necessary libraries and prepare the images for style transfer."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import torch\n",
    "import torch.nn as nn\n",
    "import torch.optim as optim\n",
    "import requests\n",
    "from io import BytesIO\n",
    "from torchvision import transforms, models\n",
    "from PIL import Image\n",
    "import matplotlib.pyplot as plt\n",
    "# Find our device\n",
    "device = torch.device(\"cuda\" if torch.cuda.is_available() else \"cpu\")\n",
    "# URL to load our content image from\n",
    "url = \"https://thumbnailer.mixcloud.com/unsafe/300x300/extaudio/6/b/a/b/d576-35c3-48a9-a01e-7dc4f0255e62.jpg\"\n",
    "response = requests.get(url)\n",
    "content_image = np.array(Image.open(BytesIO(response.content)))\n",
    "# URL to load our style image from\n",
    "url = \"https://t4.ftcdn.net/jpg/02/44/21/17/360_F_244211780_VFoZhDiuxyWpnTalr0DFilyYqNokEoVZ.jpg\"\n",
    "response = requests.get(url)\n",
    "style_image = np.array(Image.open(BytesIO(response.content)))\n",
    "# Display content and style images\n",
    "plt.imshow(content_image)\n",
    "plt.show()\n",
    "plt.imshow(style_image)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a name=\"model_loss\"></a>\n",
    "## Pre-trained Model and Loss Functions\n",
    "\n",
    "We will use the pre-trained VGG-19 model, and define the content and style loss functions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 38,
   "metadata": {},
   "outputs": [],
   "source": [
    "from torchvision.models import VGG19_Weights\n",
    "# Load pre-trained VGG-19 model\n",
    "vgg = models.vgg19(weights=VGG19_Weights.DEFAULT).features.to(device).eval()\n",
    "\n",
    "# Content and style loss functions\n",
    "class ContentLoss(nn.Module):\n",
    "    ...\n",
    "\n",
    "class StyleLoss(nn.Module):\n",
    "    ..."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a name=\"prepost\"></a>\n",
    "## Image Preprocessing and Postprocessing\n",
    "We need to define functions for preprocessing and postprocessing the images."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 39,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Image preprocessing\n",
    "def preprocess(image, max_size=512, shape=None):\n",
    "    ...\n",
    "\n",
    "# Image postprocessing\n",
    "def postprocess(tensor):\n",
    "    ..."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a name=\"implementation\"></a>\n",
    "## Style Transfer Implementation\n",
    "\n",
    "Now that we have everything set up, we can implement the style transfer algorithm."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 41,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Style transfer function\n",
    "def style_transfer(content_image, style_image, content_layers, style_layers, content_weight, style_weight, iterations=2000):\n",
    "    ...\n",
    "\n",
    "# Perform style transfer\n",
    "content_layers = ['conv_4']\n",
    "style_layers = ['conv_1', 'conv_2', 'conv_3', 'conv_4', 'conv_5']\n",
    "content_weight = 1\n",
    "style_weight = 1e6\n",
    "\n",
    "output_image = style_transfer(content_image, style_image, content_layers, style_layers, content_weight, style_weight)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a name=\"visualization\"></a>\n",
    "## Visualization\n",
    "\n",
    "We can visualize the output image and evaluate the results."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Visualize output image\n",
    "plt.imshow(output_image)\n",
    "plt.show()\n",
    "\n",
    "# Save the output image\n",
    "output_image.save(\"path/to/output/image.jpg\")"
   ]
  }
 ],
 "metadata": {
  "colab": {
   "collapsed_sections": [],
   "name": "TensorFlow_3_Autoencoder_Dimensionality_Reduction.ipynb",
   "provenance": [],
   "toc_visible": true,
   "version": "0.3.2"
  },
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.6"
  },
  "latex_envs": {
   "LaTeX_envs_menu_present": true,
   "autoclose": false,
   "autocomplete": true,
   "bibliofile": "biblio.bib",
   "cite_by": "apalike",
   "current_citInitial": 1,
   "eqLabelWithNumbers": true,
   "eqNumInitial": 1,
   "hotkeys": {
    "equation": "Ctrl-E",
    "itemize": "Ctrl-I"
   },
   "labels_anchors": false,
   "latex_user_defs": false,
   "report_style_numbering": false,
   "user_envs_cfg": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}