{"cells": [{"cell_type": "markdown", "id": "5533b572", "metadata": {"papermill": {"duration": 0.024317, "end_time": "2023-10-11T15:25:54.475662", "exception": false, "start_time": "2023-10-11T15:25:54.451345", "status": "completed"}, "tags": []}, "source": ["\n", "# Tutorial 1: Introduction to PyTorch\n", "\n", "* **Author:** Phillip Lippe\n", "* **License:** CC BY-SA\n", "* **Generated:** 2023-10-11T15:25:36.178524\n", "\n", "This tutorial will give a short introduction to PyTorch basics, and get you setup for writing your own neural networks.\n", "This notebook is part of a lecture series on Deep Learning at the University of Amsterdam.\n", "The full list of tutorials can be found at https://uvadlc-notebooks.rtfd.io.\n", "\n", "\n", "---\n", "Open in [![Open In Colab](data:image/png;base64,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){height=\"20px\" width=\"117px\"}](https://colab.research.google.com/github/PytorchLightning/lightning-tutorials/blob/publication/.notebooks/course_UvA-DL/01-introduction-to-pytorch.ipynb)\n", "\n", "Give us a \u2b50 [on Github](https://www.github.com/Lightning-AI/lightning/)\n", "| Check out [the documentation](https://pytorch-lightning.readthedocs.io/en/stable/)\n", "| Join us [on Slack](https://www.pytorchlightning.ai/community)"]}, {"cell_type": "markdown", "id": "63bea807", "metadata": {"papermill": {"duration": 0.017252, "end_time": "2023-10-11T15:25:54.512416", "exception": false, "start_time": "2023-10-11T15:25:54.495164", "status": "completed"}, "tags": []}, "source": ["## Setup\n", "This notebook requires some packages besides pytorch-lightning."]}, {"cell_type": "code", "execution_count": 1, "id": "9c70b0ff", "metadata": {"colab": {}, "colab_type": "code", "execution": {"iopub.execute_input": "2023-10-11T15:25:54.539154Z", "iopub.status.busy": "2023-10-11T15:25:54.538982Z", "iopub.status.idle": "2023-10-11T15:25:57.992201Z", "shell.execute_reply": "2023-10-11T15:25:57.990719Z"}, "id": "LfrJLKPFyhsK", "lines_to_next_cell": 0, "papermill": {"duration": 3.470121, "end_time": "2023-10-11T15:25:57.995418", "exception": false, "start_time": "2023-10-11T15:25:54.525297", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["\u001b[33mWARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv\u001b[0m\u001b[33m\r\n", "\u001b[0m"]}], "source": ["! pip install --quiet \"pytorch-lightning>=1.4, <2.1.0\" \"urllib3\" \"ipython[notebook]>=8.0.0, <8.17.0\" \"torchmetrics>=0.7, <1.3\" \"torch>=1.8.1, <2.1.0\" \"matplotlib>=3.0.0, <3.9.0\" \"matplotlib\" \"lightning>=2.0.0\" \"setuptools>=68.0.0, <68.3.0\""]}, {"cell_type": "markdown", "id": "2c11ae7b", "metadata": {"papermill": {"duration": 0.017999, "end_time": "2023-10-11T15:25:58.064174", "exception": false, "start_time": "2023-10-11T15:25:58.046175", "status": "completed"}, "tags": []}, "source": ["
\n", "Welcome to our PyTorch tutorial for the Deep Learning course 2020 at the University of Amsterdam!\n", "The following notebook is meant to give a short introduction to PyTorch basics, and get you setup for writing your own neural networks.\n", "PyTorch is an open source machine learning framework that allows you to write your own neural networks and optimize them efficiently.\n", "However, PyTorch is not the only framework of its kind.\n", "Alternatives to PyTorch include [TensorFlow](https://www.tensorflow.org/), [JAX](https://github.com/google/jax) and [Caffe](http://caffe.berkeleyvision.org/).\n", "We choose to teach PyTorch at the University of Amsterdam because it is well established, has a huge developer community (originally developed by Facebook), is very flexible and especially used in research.\n", "Many current papers publish their code in PyTorch, and thus it is good to be familiar with PyTorch as well.\n", "Meanwhile, TensorFlow (developed by Google) is usually known for being a production-grade deep learning library.\n", "Still, if you know one machine learning framework in depth, it is very easy to learn another one because many of them use the same concepts and ideas.\n", "For instance, TensorFlow's version 2 was heavily inspired by the most popular features of PyTorch, making the frameworks even more similar.\n", "If you are already familiar with PyTorch and have created your own neural network projects, feel free to just skim this notebook.\n", "\n", "We are of course not the first ones to create a PyTorch tutorial.\n", "There are many great tutorials online, including the [\"60-min blitz\"](https://pytorch.org/tutorials/beginner/deep_learning_60min_blitz.html) on the official [PyTorch website](https://pytorch.org/tutorials/).\n", "Yet, we choose to create our own tutorial which is designed to give you the basics particularly necessary for the practicals, but still understand how PyTorch works under the hood.\n", "Over the next few weeks, we will also keep exploring new PyTorch features in the series of Jupyter notebook tutorials about deep learning.\n", "\n", "We will use a set of standard libraries that are often used in machine learning projects.\n", "If you are running this notebook on Google Colab, all libraries should be pre-installed.\n", "If you are running this notebook locally, make sure you have installed our `dl2020` environment ([link](https://github.com/uvadlc/uvadlc_practicals_2020/blob/master/environment.yml)) and have activated it."]}, {"cell_type": "code", "execution_count": 2, "id": "4aa322b3", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:25:58.091840Z", "iopub.status.busy": "2023-10-11T15:25:58.091451Z", "iopub.status.idle": "2023-10-11T15:25:59.943517Z", "shell.execute_reply": "2023-10-11T15:25:59.942885Z"}, "papermill": {"duration": 1.868601, "end_time": "2023-10-11T15:25:59.945602", "exception": false, "start_time": "2023-10-11T15:25:58.077001", "status": "completed"}, "tags": []}, "outputs": [], "source": ["import time\n", "\n", "import matplotlib.pyplot as plt\n", "\n", "%matplotlib inline\n", "import matplotlib_inline.backend_inline\n", "import numpy as np\n", "import torch\n", "import torch.nn as nn\n", "import torch.utils.data as data\n", "from matplotlib.colors import to_rgba\n", "from torch import Tensor\n", "from tqdm.notebook import tqdm # Progress bar\n", "\n", "matplotlib_inline.backend_inline.set_matplotlib_formats(\"svg\", \"pdf\") # For export"]}, {"cell_type": "markdown", "id": "6f999f37", "metadata": {"papermill": {"duration": 0.018147, "end_time": "2023-10-11T15:25:59.984037", "exception": false, "start_time": "2023-10-11T15:25:59.965890", "status": "completed"}, "tags": []}, "source": ["## The Basics of PyTorch\n", "\n", "We will start with reviewing the very basic concepts of PyTorch.\n", "As a prerequisite, we recommend to be familiar with the `numpy` package as most machine learning frameworks are based on very similar concepts.\n", "If you are not familiar with numpy yet, don't worry: here is a [tutorial](https://numpy.org/devdocs/user/quickstart.html) to go through.\n", "\n", "So, let's start with importing PyTorch.\n", "The package is called `torch`, based on its original framework [Torch](http://torch.ch/).\n", "As a first step, we can check its version:"]}, {"cell_type": "code", "execution_count": 3, "id": "eb430c1b", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:00.011560Z", "iopub.status.busy": "2023-10-11T15:26:00.011270Z", "iopub.status.idle": "2023-10-11T15:26:00.015475Z", "shell.execute_reply": "2023-10-11T15:26:00.014828Z"}, "papermill": {"duration": 0.019437, "end_time": "2023-10-11T15:26:00.016626", "exception": false, "start_time": "2023-10-11T15:25:59.997189", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["Using torch 2.0.1+cu118\n"]}], "source": ["print(\"Using torch\", torch.__version__)"]}, {"cell_type": "markdown", "id": "00afd05f", "metadata": {"papermill": {"duration": 0.013195, "end_time": "2023-10-11T15:26:00.044040", "exception": false, "start_time": "2023-10-11T15:26:00.030845", "status": "completed"}, "tags": []}, "source": ["At the time of writing this tutorial (mid of August 2021), the current stable version is 1.9.\n", "You should therefore see the output `Using torch 1.9.0`, eventually with some extension for the CUDA version on Colab.\n", "In case you use the `dl2020` environment, you should see `Using torch 1.6.0` since the environment was provided in October 2020.\n", "It is recommended to update the PyTorch version to the newest one.\n", "If you see a lower version number than 1.6, make sure you have installed the correct the environment, or ask one of your TAs.\n", "In case PyTorch 1.10 or newer will be published during the time of the course, don't worry.\n", "The interface between PyTorch versions doesn't change too much, and hence all code should also be runnable with newer versions.\n", "\n", "As in every machine learning framework, PyTorch provides functions that are stochastic like generating random numbers.\n", "However, a very good practice is to setup your code to be reproducible with the exact same random numbers.\n", "This is why we set a seed below."]}, {"cell_type": "code", "execution_count": 4, "id": "0a4c434d", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:00.071975Z", "iopub.status.busy": "2023-10-11T15:26:00.071746Z", "iopub.status.idle": "2023-10-11T15:26:00.078986Z", "shell.execute_reply": "2023-10-11T15:26:00.078374Z"}, "papermill": {"duration": 0.023123, "end_time": "2023-10-11T15:26:00.080085", "exception": false, "start_time": "2023-10-11T15:26:00.056962", "status": "completed"}, "tags": []}, "outputs": [{"data": {"text/plain": [""]}, "execution_count": 4, "metadata": {}, "output_type": "execute_result"}], "source": ["torch.manual_seed(42) # Setting the seed"]}, {"cell_type": "markdown", "id": "642b8596", "metadata": {"papermill": {"duration": 0.013625, "end_time": "2023-10-11T15:26:00.106974", "exception": false, "start_time": "2023-10-11T15:26:00.093349", "status": "completed"}, "tags": []}, "source": ["### Tensors\n", "\n", "Tensors are the PyTorch equivalent to Numpy arrays, with the addition to also have support for GPU acceleration (more on that later).\n", "The name \"tensor\" is a generalization of concepts you already know.\n", "For instance, a vector is a 1-D tensor, and a matrix a 2-D tensor.\n", "When working with neural networks, we will use tensors of various shapes and number of dimensions.\n", "\n", "Most common functions you know from numpy can be used on tensors as well.\n", "Actually, since numpy arrays are so similar to tensors, we can convert most tensors to numpy arrays (and back) but we don't need it too often.\n", "\n", "#### Initialization\n", "\n", "Let's first start by looking at different ways of creating a tensor.\n", "There are many possible options, the most simple one is to call\n", "`Tensor` passing the desired shape as input argument:"]}, {"cell_type": "code", "execution_count": 5, "id": "65bea0fa", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:00.135217Z", "iopub.status.busy": "2023-10-11T15:26:00.134301Z", "iopub.status.idle": "2023-10-11T15:26:00.163604Z", "shell.execute_reply": "2023-10-11T15:26:00.162967Z"}, "papermill": {"duration": 0.0444, "end_time": "2023-10-11T15:26:00.164616", "exception": false, "start_time": "2023-10-11T15:26:00.120216", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["tensor([[[-1.6339e-32, 4.5768e-41, 2.6395e-26, 3.0780e-41],\n", " [ 3.7616e-37, 2.7105e-20, 1.0141e+31, 7.5670e-44],\n", " [ 7.9935e-37, 4.9961e-38, 5.5106e-39, 4.2981e-38]],\n", "\n", " [[ 4.9962e-38, 2.2967e-39, 1.2512e-23, 1.2031e-38],\n", " [ 1.6751e-37, 4.9959e-38, 2.2967e-39, 4.2981e-38],\n", " [ 7.1708e-37, 4.9665e-37, 1.5104e-39, -9.6800e+02]]])\n"]}], "source": ["x = Tensor(2, 3, 4)\n", "print(x)"]}, {"cell_type": "markdown", "id": "aa71ef10", "metadata": {"papermill": {"duration": 0.013042, "end_time": "2023-10-11T15:26:00.190796", "exception": false, "start_time": "2023-10-11T15:26:00.177754", "status": "completed"}, "tags": []}, "source": ["The function `torch.Tensor` allocates memory for the desired tensor, but reuses any values that have already been in the memory.\n", "To directly assign values to the tensor during initialization, there are many alternatives including:\n", "\n", "* `torch.zeros`: Creates a tensor filled with zeros\n", "* `torch.ones`: Creates a tensor filled with ones\n", "* `torch.rand`: Creates a tensor with random values uniformly sampled between 0 and 1\n", "* `torch.randn`: Creates a tensor with random values sampled from a normal distribution with mean 0 and variance 1\n", "* `torch.arange`: Creates a tensor containing the values $N,N+1,N+2,...,M$\n", "* `torch.Tensor` (input list): Creates a tensor from the list elements you provide"]}, {"cell_type": "code", "execution_count": 6, "id": "09b0eeba", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:00.221414Z", "iopub.status.busy": "2023-10-11T15:26:00.220488Z", "iopub.status.idle": "2023-10-11T15:26:00.227180Z", "shell.execute_reply": "2023-10-11T15:26:00.226132Z"}, "papermill": {"duration": 0.022951, "end_time": "2023-10-11T15:26:00.228583", "exception": false, "start_time": "2023-10-11T15:26:00.205632", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["tensor([[1., 2.],\n", " [3., 4.]])\n"]}], "source": ["# Create a tensor from a (nested) list\n", "x = Tensor([[1, 2], [3, 4]])\n", "print(x)"]}, {"cell_type": "code", "execution_count": 7, "id": "26210c86", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:00.256689Z", "iopub.status.busy": "2023-10-11T15:26:00.255894Z", "iopub.status.idle": "2023-10-11T15:26:00.262326Z", "shell.execute_reply": "2023-10-11T15:26:00.261651Z"}, "papermill": {"duration": 0.021731, "end_time": "2023-10-11T15:26:00.263530", "exception": false, "start_time": "2023-10-11T15:26:00.241799", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["tensor([[[0.8823, 0.9150, 0.3829, 0.9593],\n", " [0.3904, 0.6009, 0.2566, 0.7936],\n", " [0.9408, 0.1332, 0.9346, 0.5936]],\n", "\n", " [[0.8694, 0.5677, 0.7411, 0.4294],\n", " [0.8854, 0.5739, 0.2666, 0.6274],\n", " [0.2696, 0.4414, 0.2969, 0.8317]]])\n"]}], "source": ["# Create a tensor with random values between 0 and 1 with the shape [2, 3, 4]\n", "x = torch.rand(2, 3, 4)\n", "print(x)"]}, {"cell_type": "markdown", "id": "3463b5d4", "metadata": {"papermill": {"duration": 0.013175, "end_time": "2023-10-11T15:26:00.290064", "exception": false, "start_time": "2023-10-11T15:26:00.276889", "status": "completed"}, "tags": []}, "source": ["You can obtain the shape of a tensor in the same way as in numpy (`x.shape`), or using the `.size` method:"]}, {"cell_type": "code", "execution_count": 8, "id": "d82494b7", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:00.317490Z", "iopub.status.busy": "2023-10-11T15:26:00.317250Z", "iopub.status.idle": "2023-10-11T15:26:00.324101Z", "shell.execute_reply": "2023-10-11T15:26:00.323057Z"}, "papermill": {"duration": 0.02231, "end_time": "2023-10-11T15:26:00.325654", "exception": false, "start_time": "2023-10-11T15:26:00.303344", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["Shape: torch.Size([2, 3, 4])\n", "Size: torch.Size([2, 3, 4])\n", "Size: 2 3 4\n"]}], "source": ["shape = x.shape\n", "print(\"Shape:\", x.shape)\n", "\n", "size = x.size()\n", "print(\"Size:\", size)\n", "\n", "dim1, dim2, dim3 = x.size()\n", "print(\"Size:\", dim1, dim2, dim3)"]}, {"cell_type": "markdown", "id": "bd49194f", "metadata": {"papermill": {"duration": 0.013645, "end_time": "2023-10-11T15:26:00.353033", "exception": false, "start_time": "2023-10-11T15:26:00.339388", "status": "completed"}, "tags": []}, "source": ["#### Tensor to Numpy, and Numpy to Tensor\n", "\n", "Tensors can be converted to numpy arrays, and numpy arrays back to tensors.\n", "To transform a numpy array into a tensor, we can use the function `torch.from_numpy`:"]}, {"cell_type": "code", "execution_count": 9, "id": "2a22f204", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:00.381476Z", "iopub.status.busy": "2023-10-11T15:26:00.380956Z", "iopub.status.idle": "2023-10-11T15:26:00.388357Z", "shell.execute_reply": "2023-10-11T15:26:00.387280Z"}, "papermill": {"duration": 0.023544, "end_time": "2023-10-11T15:26:00.390168", "exception": false, "start_time": "2023-10-11T15:26:00.366624", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["Numpy array: [[1 2]\n", " [3 4]]\n", "PyTorch tensor: tensor([[1, 2],\n", " [3, 4]])\n"]}], "source": ["np_arr = np.array([[1, 2], [3, 4]])\n", "tensor = torch.from_numpy(np_arr)\n", "\n", "print(\"Numpy array:\", np_arr)\n", "print(\"PyTorch tensor:\", tensor)"]}, {"cell_type": "markdown", "id": "5ab9ba1a", "metadata": {"papermill": {"duration": 0.013381, "end_time": "2023-10-11T15:26:00.417008", "exception": false, "start_time": "2023-10-11T15:26:00.403627", "status": "completed"}, "tags": []}, "source": ["To transform a PyTorch tensor back to a numpy array, we can use the function `.numpy()` on tensors:"]}, {"cell_type": "code", "execution_count": 10, "id": "8febaee0", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:00.445854Z", "iopub.status.busy": "2023-10-11T15:26:00.444913Z", "iopub.status.idle": "2023-10-11T15:26:00.453686Z", "shell.execute_reply": "2023-10-11T15:26:00.452584Z"}, "papermill": {"duration": 0.024671, "end_time": "2023-10-11T15:26:00.455086", "exception": false, "start_time": "2023-10-11T15:26:00.430415", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["PyTorch tensor: tensor([0, 1, 2, 3])\n", "Numpy array: [0 1 2 3]\n"]}], "source": ["tensor = torch.arange(4)\n", "np_arr = tensor.numpy()\n", "\n", "print(\"PyTorch tensor:\", tensor)\n", "print(\"Numpy array:\", np_arr)"]}, {"cell_type": "markdown", "id": "f24a0cd6", "metadata": {"papermill": {"duration": 0.013751, "end_time": "2023-10-11T15:26:00.482506", "exception": false, "start_time": "2023-10-11T15:26:00.468755", "status": "completed"}, "tags": []}, "source": ["The conversion of tensors to numpy require the tensor to be on the CPU, and not the GPU (more on GPU support in a later section).\n", "In case you have a tensor on GPU, you need to call `.cpu()` on the tensor beforehand.\n", "Hence, you get a line like `np_arr = tensor.cpu().numpy()`."]}, {"cell_type": "markdown", "id": "7bae6b5b", "metadata": {"papermill": {"duration": 0.013661, "end_time": "2023-10-11T15:26:00.510025", "exception": false, "start_time": "2023-10-11T15:26:00.496364", "status": "completed"}, "tags": []}, "source": ["#### Operations\n", "\n", "Most operations that exist in numpy, also exist in PyTorch.\n", "A full list of operations can be found in the [PyTorch documentation](https://pytorch.org/docs/stable/tensors.html#), but we will review the most important ones here.\n", "\n", "The simplest operation is to add two tensors:"]}, {"cell_type": "code", "execution_count": 11, "id": "bc529a63", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:00.539154Z", "iopub.status.busy": "2023-10-11T15:26:00.538554Z", "iopub.status.idle": "2023-10-11T15:26:00.548270Z", "shell.execute_reply": "2023-10-11T15:26:00.547181Z"}, "papermill": {"duration": 0.025878, "end_time": "2023-10-11T15:26:00.549639", "exception": false, "start_time": "2023-10-11T15:26:00.523761", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["X1 tensor([[0.1053, 0.2695, 0.3588],\n", " [0.1994, 0.5472, 0.0062]])\n", "X2 tensor([[0.9516, 0.0753, 0.8860],\n", " [0.5832, 0.3376, 0.8090]])\n", "Y tensor([[1.0569, 0.3448, 1.2448],\n", " [0.7826, 0.8848, 0.8151]])\n"]}], "source": ["x1 = torch.rand(2, 3)\n", "x2 = torch.rand(2, 3)\n", "y = x1 + x2\n", "\n", "print(\"X1\", x1)\n", "print(\"X2\", x2)\n", "print(\"Y\", y)"]}, {"cell_type": "markdown", "id": "0d1ab9d1", "metadata": {"papermill": {"duration": 0.01391, "end_time": "2023-10-11T15:26:00.577518", "exception": false, "start_time": "2023-10-11T15:26:00.563608", "status": "completed"}, "tags": []}, "source": ["Calling `x1 + x2` creates a new tensor containing the sum of the two inputs.\n", "However, we can also use in-place operations that are applied directly on the memory of a tensor.\n", "We therefore change the values of `x2` without the chance to re-accessing the values of `x2` before the operation.\n", "An example is shown below:"]}, {"cell_type": "code", "execution_count": 12, "id": "35a58fd6", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:00.606881Z", "iopub.status.busy": "2023-10-11T15:26:00.606337Z", "iopub.status.idle": "2023-10-11T15:26:00.615983Z", "shell.execute_reply": "2023-10-11T15:26:00.614907Z"}, "papermill": {"duration": 0.02634, "end_time": "2023-10-11T15:26:00.617848", "exception": false, "start_time": "2023-10-11T15:26:00.591508", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["X1 (before) tensor([[0.5779, 0.9040, 0.5547],\n", " [0.3423, 0.6343, 0.3644]])\n", "X2 (before) tensor([[0.7104, 0.9464, 0.7890],\n", " [0.2814, 0.7886, 0.5895]])\n", "X1 (after) tensor([[0.5779, 0.9040, 0.5547],\n", " [0.3423, 0.6343, 0.3644]])\n", "X2 (after) tensor([[1.2884, 1.8504, 1.3437],\n", " [0.6237, 1.4230, 0.9539]])\n"]}], "source": ["x1 = torch.rand(2, 3)\n", "x2 = torch.rand(2, 3)\n", "print(\"X1 (before)\", x1)\n", "print(\"X2 (before)\", x2)\n", "\n", "x2.add_(x1)\n", "print(\"X1 (after)\", x1)\n", "print(\"X2 (after)\", x2)"]}, {"cell_type": "markdown", "id": "4279cfca", "metadata": {"papermill": {"duration": 0.013975, "end_time": "2023-10-11T15:26:00.645805", "exception": false, "start_time": "2023-10-11T15:26:00.631830", "status": "completed"}, "tags": []}, "source": ["In-place operations are usually marked with a underscore postfix (for example `torch.add_` instead of `torch.add`).\n", "\n", "Another common operation aims at changing the shape of a tensor.\n", "A tensor of size (2,3) can be re-organized to any other shape with the same number of elements (e.g. a tensor of size (6), or (3,2), ...).\n", "In PyTorch, this operation is called `view`:"]}, {"cell_type": "code", "execution_count": 13, "id": "90746f0a", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:00.675262Z", "iopub.status.busy": "2023-10-11T15:26:00.674683Z", "iopub.status.idle": "2023-10-11T15:26:00.680694Z", "shell.execute_reply": "2023-10-11T15:26:00.680019Z"}, "papermill": {"duration": 0.022133, "end_time": "2023-10-11T15:26:00.681908", "exception": false, "start_time": "2023-10-11T15:26:00.659775", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["X tensor([0, 1, 2, 3, 4, 5])\n"]}], "source": ["x = torch.arange(6)\n", "print(\"X\", x)"]}, {"cell_type": "code", "execution_count": 14, "id": "cc584fda", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:00.711125Z", "iopub.status.busy": "2023-10-11T15:26:00.710638Z", "iopub.status.idle": "2023-10-11T15:26:00.715342Z", "shell.execute_reply": "2023-10-11T15:26:00.714719Z"}, "papermill": {"duration": 0.020683, "end_time": "2023-10-11T15:26:00.716560", "exception": false, "start_time": "2023-10-11T15:26:00.695877", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["X tensor([[0, 1, 2],\n", " [3, 4, 5]])\n"]}], "source": ["x = x.view(2, 3)\n", "print(\"X\", x)"]}, {"cell_type": "code", "execution_count": 15, "id": "9270a34d", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:00.745904Z", "iopub.status.busy": "2023-10-11T15:26:00.745542Z", "iopub.status.idle": "2023-10-11T15:26:00.751053Z", "shell.execute_reply": "2023-10-11T15:26:00.750381Z"}, "papermill": {"duration": 0.021693, "end_time": "2023-10-11T15:26:00.752247", "exception": false, "start_time": "2023-10-11T15:26:00.730554", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["X tensor([[0, 3],\n", " [1, 4],\n", " [2, 5]])\n"]}], "source": ["x = x.permute(1, 0) # Swapping dimension 0 and 1\n", "print(\"X\", x)"]}, {"cell_type": "markdown", "id": "60db2618", "metadata": {"papermill": {"duration": 0.014181, "end_time": "2023-10-11T15:26:00.780521", "exception": false, "start_time": "2023-10-11T15:26:00.766340", "status": "completed"}, "tags": []}, "source": ["Other commonly used operations include matrix multiplications, which are essential for neural networks.\n", "Quite often, we have an input vector $\\mathbf{x}$, which is transformed using a learned weight matrix $\\mathbf{W}$.\n", "There are multiple ways and functions to perform matrix multiplication, some of which we list below:\n", "\n", "* `torch.matmul`: Performs the matrix product over two tensors, where the specific behavior depends on the dimensions.\n", "If both inputs are matrices (2-dimensional tensors), it performs the standard matrix product.\n", "For higher dimensional inputs, the function supports broadcasting (for details see the [documentation](https://pytorch.org/docs/stable/generated/torch.matmul.html?highlight=matmul#torch.matmul)).\n", "Can also be written as `a @ b`, similar to numpy.\n", "* `torch.mm`: Performs the matrix product over two matrices, but doesn't support broadcasting (see [documentation](https://pytorch.org/docs/stable/generated/torch.mm.html?highlight=torch%20mm#torch.mm))\n", "* `torch.bmm`: Performs the matrix product with a support batch dimension.\n", "If the first tensor $T$ is of shape ($b\\times n\\times m$), and the second tensor $R$ ($b\\times m\\times p$), the output $O$ is of shape ($b\\times n\\times p$), and has been calculated by performing $b$ matrix multiplications of the submatrices of $T$ and $R$: $O_i = T_i @ R_i$\n", "* `torch.einsum`: Performs matrix multiplications and more (i.e. sums of products) using the Einstein summation convention.\n", "Explanation of the Einstein sum can be found in assignment 1.\n", "\n", "Usually, we use `torch.matmul` or `torch.bmm`. We can try a matrix multiplication with `torch.matmul` below."]}, {"cell_type": "code", "execution_count": 16, "id": "515ee753", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:00.810369Z", "iopub.status.busy": "2023-10-11T15:26:00.810002Z", "iopub.status.idle": "2023-10-11T15:26:00.816966Z", "shell.execute_reply": "2023-10-11T15:26:00.816064Z"}, "papermill": {"duration": 0.023439, "end_time": "2023-10-11T15:26:00.818264", "exception": false, "start_time": "2023-10-11T15:26:00.794825", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["X "]}, {"name": "stdout", "output_type": "stream", "text": ["tensor([[0, 1, 2],\n", " [3, 4, 5]])\n"]}], "source": ["x = torch.arange(6)\n", "x = x.view(2, 3)\n", "print(\"X\", x)"]}, {"cell_type": "code", "execution_count": 17, "id": "5fe6974c", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:00.849138Z", "iopub.status.busy": "2023-10-11T15:26:00.848615Z", "iopub.status.idle": "2023-10-11T15:26:00.854964Z", "shell.execute_reply": "2023-10-11T15:26:00.853988Z"}, "papermill": {"duration": 0.022772, "end_time": "2023-10-11T15:26:00.856247", "exception": false, "start_time": "2023-10-11T15:26:00.833475", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["W tensor([[0, 1, 2],\n", " [3, 4, 5],\n", " [6, 7, 8]])\n"]}], "source": ["W = torch.arange(9).view(3, 3) # We can also stack multiple operations in a single line\n", "print(\"W\", W)"]}, {"cell_type": "code", "execution_count": 18, "id": "2ed609e8", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:00.885964Z", "iopub.status.busy": "2023-10-11T15:26:00.885617Z", "iopub.status.idle": "2023-10-11T15:26:00.891855Z", "shell.execute_reply": "2023-10-11T15:26:00.890973Z"}, "papermill": {"duration": 0.022612, "end_time": "2023-10-11T15:26:00.893129", "exception": false, "start_time": "2023-10-11T15:26:00.870517", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["h tensor([[15, 18, 21],\n", " [42, 54, 66]])\n"]}], "source": ["h = torch.matmul(x, W) # Verify the result by calculating it by hand too!\n", "print(\"h\", h)"]}, {"cell_type": "markdown", "id": "517bc447", "metadata": {"papermill": {"duration": 0.014228, "end_time": "2023-10-11T15:26:00.921779", "exception": false, "start_time": "2023-10-11T15:26:00.907551", "status": "completed"}, "tags": []}, "source": ["#### Indexing\n", "\n", "We often have the situation where we need to select a part of a tensor.\n", "Indexing works just like in numpy, so let's try it:"]}, {"cell_type": "code", "execution_count": 19, "id": "7cfa27cc", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:00.952021Z", "iopub.status.busy": "2023-10-11T15:26:00.951467Z", "iopub.status.idle": "2023-10-11T15:26:00.957740Z", "shell.execute_reply": "2023-10-11T15:26:00.956742Z"}, "papermill": {"duration": 0.02282, "end_time": "2023-10-11T15:26:00.958997", "exception": false, "start_time": "2023-10-11T15:26:00.936177", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["X tensor([[ 0, 1, 2, 3],\n", " [ 4, 5, 6, 7],\n", " [ 8, 9, 10, 11]])\n"]}], "source": ["x = torch.arange(12).view(3, 4)\n", "print(\"X\", x)"]}, {"cell_type": "code", "execution_count": 20, "id": "b09430d5", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:00.989211Z", "iopub.status.busy": "2023-10-11T15:26:00.988677Z", "iopub.status.idle": "2023-10-11T15:26:00.995154Z", "shell.execute_reply": "2023-10-11T15:26:00.994267Z"}, "papermill": {"duration": 0.023042, "end_time": "2023-10-11T15:26:00.996420", "exception": false, "start_time": "2023-10-11T15:26:00.973378", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["tensor([1, 5, 9])\n"]}], "source": ["print(x[:, 1]) # Second column"]}, {"cell_type": "code", "execution_count": 21, "id": "7bdcad71", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:01.026905Z", "iopub.status.busy": "2023-10-11T15:26:01.026434Z", "iopub.status.idle": "2023-10-11T15:26:01.031988Z", "shell.execute_reply": "2023-10-11T15:26:01.031103Z"}, "papermill": {"duration": 0.022193, "end_time": "2023-10-11T15:26:01.033276", "exception": false, "start_time": "2023-10-11T15:26:01.011083", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["tensor([0, 1, 2, 3])\n"]}], "source": ["print(x[0]) # First row"]}, {"cell_type": "code", "execution_count": 22, "id": "34b20708", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:01.064207Z", "iopub.status.busy": "2023-10-11T15:26:01.063698Z", "iopub.status.idle": "2023-10-11T15:26:01.069656Z", "shell.execute_reply": "2023-10-11T15:26:01.068665Z"}, "papermill": {"duration": 0.022999, "end_time": "2023-10-11T15:26:01.070904", "exception": false, "start_time": "2023-10-11T15:26:01.047905", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["tensor([3, 7])\n"]}], "source": ["print(x[:2, -1]) # First two rows, last column"]}, {"cell_type": "code", "execution_count": 23, "id": "63eac740", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:01.102505Z", "iopub.status.busy": "2023-10-11T15:26:01.101714Z", "iopub.status.idle": "2023-10-11T15:26:01.107458Z", "shell.execute_reply": "2023-10-11T15:26:01.106583Z"}, "papermill": {"duration": 0.022838, "end_time": "2023-10-11T15:26:01.108725", "exception": false, "start_time": "2023-10-11T15:26:01.085887", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["tensor([[ 4, 5, 6, 7],\n", " [ 8, 9, 10, 11]])\n"]}], "source": ["print(x[1:3, :]) # Middle two rows"]}, {"cell_type": "markdown", "id": "7b1fdd9c", "metadata": {"papermill": {"duration": 0.014666, "end_time": "2023-10-11T15:26:01.138401", "exception": false, "start_time": "2023-10-11T15:26:01.123735", "status": "completed"}, "tags": []}, "source": ["### Dynamic Computation Graph and Backpropagation\n", "\n", "One of the main reasons for using PyTorch in Deep Learning projects is that we can automatically get **gradients/derivatives** of functions that we define.\n", "We will mainly use PyTorch for implementing neural networks, and they are just fancy functions.\n", "If we use weight matrices in our function that we want to learn, then those are called the **parameters** or simply the **weights**.\n", "\n", "If our neural network would output a single scalar value, we would talk about taking the **derivative**, but you will see that quite often we will have **multiple** output variables (\"values\"); in that case we talk about **gradients**.\n", "It's a more general term.\n", "\n", "Given an input $\\mathbf{x}$, we define our function by **manipulating** that input, usually by matrix-multiplications with weight matrices and additions with so-called bias vectors.\n", "As we manipulate our input, we are automatically creating a **computational graph**.\n", "This graph shows how to arrive at our output from our input.\n", "PyTorch is a **define-by-run** framework; this means that we can just do our manipulations, and PyTorch will keep track of that graph for us.\n", "Thus, we create a dynamic computation graph along the way.\n", "\n", "So, to recap: the only thing we have to do is to compute the **output**, and then we can ask PyTorch to automatically get the **gradients**.\n", "\n", "> **Note: Why do we want gradients?\n", "** Consider that we have defined a function, a neural net, that is supposed to compute a certain output $y$ for an input vector $\\mathbf{x}$.\n", "We then define an **error measure** that tells us how wrong our network is; how bad it is in predicting output $y$ from input $\\mathbf{x}$.\n", "Based on this error measure, we can use the gradients to **update** the weights $\\mathbf{W}$ that were responsible for the output, so that the next time we present input $\\mathbf{x}$ to our network, the output will be closer to what we want.\n", "\n", "The first thing we have to do is to specify which tensors require gradients.\n", "By default, when we create a tensor, it does not require gradients."]}, {"cell_type": "code", "execution_count": 24, "id": "d58c46aa", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:01.169281Z", "iopub.status.busy": "2023-10-11T15:26:01.168784Z", "iopub.status.idle": "2023-10-11T15:26:01.174474Z", "shell.execute_reply": "2023-10-11T15:26:01.173505Z"}, "papermill": {"duration": 0.022536, "end_time": "2023-10-11T15:26:01.175702", "exception": false, "start_time": "2023-10-11T15:26:01.153166", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["False\n"]}], "source": ["x = torch.ones((3,))\n", "print(x.requires_grad)"]}, {"cell_type": "markdown", "id": "dbe9569e", "metadata": {"papermill": {"duration": 0.015475, "end_time": "2023-10-11T15:26:01.206055", "exception": false, "start_time": "2023-10-11T15:26:01.190580", "status": "completed"}, "tags": []}, "source": ["We can change this for an existing tensor using the function `requires_grad_()` (underscore indicating that this is a in-place operation).\n", "Alternatively, when creating a tensor, you can pass the argument\n", "`requires_grad=True` to most initializers we have seen above."]}, {"cell_type": "code", "execution_count": 25, "id": "3b836804", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:01.237277Z", "iopub.status.busy": "2023-10-11T15:26:01.236670Z", "iopub.status.idle": "2023-10-11T15:26:01.242169Z", "shell.execute_reply": "2023-10-11T15:26:01.241288Z"}, "papermill": {"duration": 0.023081, "end_time": "2023-10-11T15:26:01.243925", "exception": false, "start_time": "2023-10-11T15:26:01.220844", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["True\n"]}], "source": ["x.requires_grad_(True)\n", "print(x.requires_grad)"]}, {"cell_type": "markdown", "id": "4859b856", "metadata": {"papermill": {"duration": 0.014826, "end_time": "2023-10-11T15:26:01.273716", "exception": false, "start_time": "2023-10-11T15:26:01.258890", "status": "completed"}, "tags": []}, "source": ["In order to get familiar with the concept of a computation graph, we will create one for the following function:\n", "\n", "$$y = \\frac{1}{|x|}\\sum_i \\left[(x_i + 2)^2 + 3\\right]$$\n", "\n", "You could imagine that $x$ are our parameters, and we want to optimize (either maximize or minimize) the output $y$.\n", "For this, we want to obtain the gradients $\\partial y / \\partial \\mathbf{x}$.\n", "For our example, we'll use $\\mathbf{x}=[0,1,2]$ as our input."]}, {"cell_type": "code", "execution_count": 26, "id": "0cf91b9e", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:01.305024Z", "iopub.status.busy": "2023-10-11T15:26:01.304423Z", "iopub.status.idle": "2023-10-11T15:26:01.311548Z", "shell.execute_reply": "2023-10-11T15:26:01.310651Z"}, "papermill": {"duration": 0.024265, "end_time": "2023-10-11T15:26:01.312819", "exception": false, "start_time": "2023-10-11T15:26:01.288554", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["X "]}, {"name": "stdout", "output_type": "stream", "text": ["tensor([0., 1., 2.], requires_grad=True)\n"]}], "source": ["x = torch.arange(3, dtype=torch.float32, requires_grad=True) # Only float tensors can have gradients\n", "print(\"X\", x)"]}, {"cell_type": "markdown", "id": "cd57fffd", "metadata": {"papermill": {"duration": 0.015001, "end_time": "2023-10-11T15:26:01.342813", "exception": false, "start_time": "2023-10-11T15:26:01.327812", "status": "completed"}, "tags": []}, "source": ["Now let's build the computation graph step by step.\n", "You can combine multiple operations in a single line, but we will\n", "separate them here to get a better understanding of how each operation\n", "is added to the computation graph."]}, {"cell_type": "code", "execution_count": 27, "id": "cb19b057", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:01.374395Z", "iopub.status.busy": "2023-10-11T15:26:01.373776Z", "iopub.status.idle": "2023-10-11T15:26:01.381540Z", "shell.execute_reply": "2023-10-11T15:26:01.380532Z"}, "papermill": {"duration": 0.025096, "end_time": "2023-10-11T15:26:01.382892", "exception": false, "start_time": "2023-10-11T15:26:01.357796", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["Y tensor(12.6667, grad_fn=)\n"]}], "source": ["a = x + 2\n", "b = a**2\n", "c = b + 3\n", "y = c.mean()\n", "print(\"Y\", y)"]}, {"cell_type": "markdown", "id": "6e931011", "metadata": {"papermill": {"duration": 0.015298, "end_time": "2023-10-11T15:26:01.413466", "exception": false, "start_time": "2023-10-11T15:26:01.398168", "status": "completed"}, "tags": []}, "source": ["Using the statements above, we have created a computation graph that looks similar to the figure below:\n", "\n", "
\n", "\n", "We calculate $a$ based on the inputs $x$ and the constant $2$, $b$ is $a$ squared, and so on.\n", "The visualization is an abstraction of the dependencies between inputs and outputs of the operations we have applied.\n", "Each node of the computation graph has automatically defined a function for calculating the gradients with respect to its inputs, `grad_fn`.\n", "You can see this when we printed the output tensor $y$.\n", "This is why the computation graph is usually visualized in the reverse direction (arrows point from the result to the inputs).\n", "We can perform backpropagation on the computation graph by calling the\n", "function `backward()` on the last output, which effectively calculates\n", "the gradients for each tensor that has the property\n", "`requires_grad=True`:"]}, {"cell_type": "code", "execution_count": 28, "id": "bd987584", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:01.445636Z", "iopub.status.busy": "2023-10-11T15:26:01.445268Z", "iopub.status.idle": "2023-10-11T15:26:01.542743Z", "shell.execute_reply": "2023-10-11T15:26:01.541854Z"}, "papermill": {"duration": 0.115441, "end_time": "2023-10-11T15:26:01.544347", "exception": false, "start_time": "2023-10-11T15:26:01.428906", "status": "completed"}, "tags": []}, "outputs": [], "source": ["y.backward()"]}, {"cell_type": "markdown", "id": "303c8c9c", "metadata": {"papermill": {"duration": 0.01503, "end_time": "2023-10-11T15:26:01.574513", "exception": false, "start_time": "2023-10-11T15:26:01.559483", "status": "completed"}, "tags": []}, "source": ["`x.grad` will now contain the gradient $\\partial y/ \\partial \\mathcal{x}$, and this gradient indicates how a change in $\\mathbf{x}$ will affect output $y$ given the current input $\\mathbf{x}=[0,1,2]$:"]}, {"cell_type": "code", "execution_count": 29, "id": "d3e89cdc", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:01.605535Z", "iopub.status.busy": "2023-10-11T15:26:01.605365Z", "iopub.status.idle": "2023-10-11T15:26:01.611266Z", "shell.execute_reply": "2023-10-11T15:26:01.610373Z"}, "papermill": {"duration": 0.022884, "end_time": "2023-10-11T15:26:01.612523", "exception": false, "start_time": "2023-10-11T15:26:01.589639", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["tensor([1.3333, 2.0000, 2.6667])\n"]}], "source": ["print(x.grad)"]}, {"cell_type": "markdown", "id": "1e421f85", "metadata": {"papermill": {"duration": 0.015571, "end_time": "2023-10-11T15:26:01.643358", "exception": false, "start_time": "2023-10-11T15:26:01.627787", "status": "completed"}, "tags": []}, "source": ["We can also verify these gradients by hand.\n", "We will calculate the gradients using the chain rule, in the same way as PyTorch did it:\n", "\n", "$$\\frac{\\partial y}{\\partial x_i} = \\frac{\\partial y}{\\partial c_i}\\frac{\\partial c_i}{\\partial b_i}\\frac{\\partial b_i}{\\partial a_i}\\frac{\\partial a_i}{\\partial x_i}$$\n", "\n", "Note that we have simplified this equation to index notation, and by using the fact that all operation besides the mean do not combine the elements in the tensor.\n", "The partial derivatives are:\n", "\n", "$$\n", "\\frac{\\partial a_i}{\\partial x_i} = 1,\\hspace{1cm}\n", "\\frac{\\partial b_i}{\\partial a_i} = 2\\cdot a_i\\hspace{1cm}\n", "\\frac{\\partial c_i}{\\partial b_i} = 1\\hspace{1cm}\n", "\\frac{\\partial y}{\\partial c_i} = \\frac{1}{3}\n", "$$\n", "\n", "Hence, with the input being $\\mathbf{x}=[0,1,2]$, our gradients are $\\partial y/\\partial \\mathbf{x}=[4/3,2,8/3]$.\n", "The previous code cell should have printed the same result."]}, {"cell_type": "markdown", "id": "6943f1a8", "metadata": {"papermill": {"duration": 0.015467, "end_time": "2023-10-11T15:26:01.674289", "exception": false, "start_time": "2023-10-11T15:26:01.658822", "status": "completed"}, "tags": []}, "source": ["### GPU support\n", "\n", "A crucial feature of PyTorch is the support of GPUs, short for Graphics Processing Unit.\n", "A GPU can perform many thousands of small operations in parallel, making it very well suitable for performing large matrix operations in neural networks.\n", "When comparing GPUs to CPUs, we can list the following main differences (credit: [Kevin Krewell, 2009](https://blogs.nvidia.com/blog/2009/12/16/whats-the-difference-between-a-cpu-and-a-gpu/))\n", "\n", "
\n", "\n", "CPUs and GPUs have both different advantages and disadvantages, which is why many computers contain both components and use them for different tasks.\n", "In case you are not familiar with GPUs, you can read up more details in this [NVIDIA blog post](https://blogs.nvidia.com/blog/2009/12/16/whats-the-difference-between-a-cpu-and-a-gpu/) or [here](https://www.intel.com/content/www/us/en/products/docs/processors/what-is-a-gpu.html).\n", "\n", "GPUs can accelerate the training of your network up to a factor of $100$ which is essential for large neural networks.\n", "PyTorch implements a lot of functionality for supporting GPUs (mostly those of NVIDIA due to the libraries [CUDA](https://developer.nvidia.com/cuda-zone) and [cuDNN](https://developer.nvidia.com/cudnn)).\n", "First, let's check whether you have a GPU available:"]}, {"cell_type": "code", "execution_count": 30, "id": "772045e0", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:01.706783Z", "iopub.status.busy": "2023-10-11T15:26:01.706215Z", "iopub.status.idle": "2023-10-11T15:26:01.710815Z", "shell.execute_reply": "2023-10-11T15:26:01.710168Z"}, "papermill": {"duration": 0.022125, "end_time": "2023-10-11T15:26:01.711968", "exception": false, "start_time": "2023-10-11T15:26:01.689843", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["Is the GPU available? True\n"]}], "source": ["gpu_avail = torch.cuda.is_available()\n", "print(f\"Is the GPU available? {gpu_avail}\")"]}, {"cell_type": "markdown", "id": "eaea6906", "metadata": {"papermill": {"duration": 0.015252, "end_time": "2023-10-11T15:26:01.742625", "exception": false, "start_time": "2023-10-11T15:26:01.727373", "status": "completed"}, "tags": []}, "source": ["If you have a GPU on your computer but the command above returns False, make sure you have the correct CUDA-version installed.\n", "The `dl2020` environment comes with the CUDA-toolkit 10.1, which is selected for the Lisa supercomputer.\n", "Please change it if necessary (CUDA 10.2 is currently common).\n", "On Google Colab, make sure that you have selected a GPU in your runtime setup (in the menu, check under `Runtime -> Change runtime type`).\n", "\n", "By default, all tensors you create are stored on the CPU.\n", "We can push a tensor to the GPU by using the function `.to(...)`, or `.cuda()`.\n", "However, it is often a good practice to define a `device` object in your code which points to the GPU if you have one, and otherwise to the CPU.\n", "Then, you can write your code with respect to this device object, and it allows you to run the same code on both a CPU-only system, and one with a GPU.\n", "Let's try it below.\n", "We can specify the device as follows:"]}, {"cell_type": "code", "execution_count": 31, "id": "e9027be6", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:01.774681Z", "iopub.status.busy": "2023-10-11T15:26:01.774143Z", "iopub.status.idle": "2023-10-11T15:26:01.779247Z", "shell.execute_reply": "2023-10-11T15:26:01.778315Z"}, "papermill": {"duration": 0.022549, "end_time": "2023-10-11T15:26:01.780534", "exception": false, "start_time": "2023-10-11T15:26:01.757985", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["Device cuda\n"]}], "source": ["device = torch.device(\"cuda\") if torch.cuda.is_available() else torch.device(\"cpu\")\n", "print(\"Device\", device)"]}, {"cell_type": "markdown", "id": "93cb3af0", "metadata": {"papermill": {"duration": 0.015338, "end_time": "2023-10-11T15:26:01.811341", "exception": false, "start_time": "2023-10-11T15:26:01.796003", "status": "completed"}, "tags": []}, "source": ["Now let's create a tensor and push it to the device:"]}, {"cell_type": "code", "execution_count": 32, "id": "c47c2018", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:01.844561Z", "iopub.status.busy": "2023-10-11T15:26:01.843561Z", "iopub.status.idle": "2023-10-11T15:26:02.089559Z", "shell.execute_reply": "2023-10-11T15:26:02.089056Z"}, "papermill": {"duration": 0.263848, "end_time": "2023-10-11T15:26:02.090604", "exception": false, "start_time": "2023-10-11T15:26:01.826756", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["X tensor([[0., 0., 0.],\n", " [0., 0., 0.]], device='cuda:0')\n"]}], "source": ["x = torch.zeros(2, 3)\n", "x = x.to(device)\n", "print(\"X\", x)"]}, {"cell_type": "markdown", "id": "452898ef", "metadata": {"papermill": {"duration": 0.015382, "end_time": "2023-10-11T15:26:02.121525", "exception": false, "start_time": "2023-10-11T15:26:02.106143", "status": "completed"}, "tags": []}, "source": ["In case you have a GPU, you should now see the attribute `device='cuda:0'` being printed next to your tensor.\n", "The zero next to cuda indicates that this is the zero-th GPU device on your computer.\n", "PyTorch also supports multi-GPU systems, but this you will only need once you have very big networks to train (if interested, see the [PyTorch documentation](https://pytorch.org/docs/stable/distributed.html#distributed-basics)).\n", "We can also compare the runtime of a large matrix multiplication on the CPU with a operation on the GPU:"]}, {"cell_type": "code", "execution_count": 33, "id": "1a83efe1", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:02.154073Z", "iopub.status.busy": "2023-10-11T15:26:02.153518Z", "iopub.status.idle": "2023-10-11T15:26:02.683637Z", "shell.execute_reply": "2023-10-11T15:26:02.683136Z"}, "papermill": {"duration": 0.547926, "end_time": "2023-10-11T15:26:02.684945", "exception": false, "start_time": "2023-10-11T15:26:02.137019", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["CPU time: 0.24235s\n", "GPU time: 0.07721s\n"]}], "source": ["x = torch.randn(5000, 5000)\n", "\n", "# CPU version\n", "start_time = time.time()\n", "_ = torch.matmul(x, x)\n", "end_time = time.time()\n", "print(f\"CPU time: {(end_time - start_time):6.5f}s\")\n", "\n", "# GPU version\n", "if torch.cuda.is_available():\n", " x = x.to(device)\n", " # CUDA is asynchronous, so we need to use different timing functions\n", " start = torch.cuda.Event(enable_timing=True)\n", " end = torch.cuda.Event(enable_timing=True)\n", " start.record()\n", " _ = torch.matmul(x, x)\n", " end.record()\n", " torch.cuda.synchronize() # Waits for everything to finish running on the GPU\n", " print(f\"GPU time: {0.001 * start.elapsed_time(end):6.5f}s\") # Milliseconds to seconds"]}, {"cell_type": "markdown", "id": "74d8ced5", "metadata": {"papermill": {"duration": 0.015697, "end_time": "2023-10-11T15:26:02.717519", "exception": false, "start_time": "2023-10-11T15:26:02.701822", "status": "completed"}, "tags": []}, "source": ["Depending on the size of the operation and the CPU/GPU in your system, the speedup of this operation can be >50x.\n", "As `matmul` operations are very common in neural networks, we can already see the great benefit of training a NN on a GPU.\n", "The time estimate can be relatively noisy here because we haven't run it for multiple times.\n", "Feel free to extend this, but it also takes longer to run.\n", "\n", "When generating random numbers, the seed between CPU and GPU is not synchronized.\n", "Hence, we need to set the seed on the GPU separately to ensure a reproducible code.\n", "Note that due to different GPU architectures, running the same code on different GPUs does not guarantee the same random numbers.\n", "Still, we don't want that our code gives us a different output every time we run it on the exact same hardware.\n", "Hence, we also set the seed on the GPU:"]}, {"cell_type": "code", "execution_count": 34, "id": "7e7af7f2", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:02.749490Z", "iopub.status.busy": "2023-10-11T15:26:02.749319Z", "iopub.status.idle": "2023-10-11T15:26:02.753637Z", "shell.execute_reply": "2023-10-11T15:26:02.752915Z"}, "papermill": {"duration": 0.021752, "end_time": "2023-10-11T15:26:02.754817", "exception": false, "start_time": "2023-10-11T15:26:02.733065", "status": "completed"}, "tags": []}, "outputs": [], "source": ["# GPU operations have a separate seed we also want to set\n", "if torch.cuda.is_available():\n", " torch.cuda.manual_seed(42)\n", " torch.cuda.manual_seed_all(42)\n", "\n", "# Additionally, some operations on a GPU are implemented stochastic for efficiency\n", "# We want to ensure that all operations are deterministic on GPU (if used) for reproducibility\n", "torch.backends.cudnn.deterministic = True\n", "torch.backends.cudnn.benchmark = False"]}, {"cell_type": "markdown", "id": "deb0594a", "metadata": {"papermill": {"duration": 0.015882, "end_time": "2023-10-11T15:26:02.786801", "exception": false, "start_time": "2023-10-11T15:26:02.770919", "status": "completed"}, "tags": []}, "source": ["## Learning by example: Continuous XOR\n", "
\n", "\n", "If we want to build a neural network in PyTorch, we could specify all our parameters (weight matrices, bias vectors) using `Tensors` (with `requires_grad=True`), ask PyTorch to calculate the gradients and then adjust the parameters.\n", "But things can quickly get cumbersome if we have a lot of parameters.\n", "In PyTorch, there is a package called `torch.nn` that makes building neural networks more convenient.\n", "\n", "We will introduce the libraries and all additional parts you might need to train a neural network in PyTorch, using a simple example classifier on a simple yet well known example: XOR.\n", "Given two binary inputs $x_1$ and $x_2$, the label to predict is $1$ if either $x_1$ or $x_2$ is $1$ while the other is $0$, or the label is $0$ in all other cases.\n", "The example became famous by the fact that a single neuron, i.e. a linear classifier, cannot learn this simple function.\n", "Hence, we will learn how to build a small neural network that can learn this function.\n", "To make it a little bit more interesting, we move the XOR into continuous space and introduce some gaussian noise on the binary inputs.\n", "Our desired separation of an XOR dataset could look as follows:\n", "\n", "
"]}, {"cell_type": "markdown", "id": "8b0362f2", "metadata": {"papermill": {"duration": 0.015906, "end_time": "2023-10-11T15:26:02.818849", "exception": false, "start_time": "2023-10-11T15:26:02.802943", "status": "completed"}, "tags": []}, "source": ["### The model\n", "\n", "The package `torch.nn` defines a series of useful classes like linear networks layers, activation functions, loss functions etc.\n", "A full list can be found [here](https://pytorch.org/docs/stable/nn.html).\n", "In case you need a certain network layer, check the documentation of the package first before writing the layer yourself as the package likely contains the code for it already.\n", "We import it below:"]}, {"cell_type": "code", "execution_count": null, "id": "7eae0eeb", "metadata": {"lines_to_next_cell": 0, "papermill": {"duration": 0.016318, "end_time": "2023-10-11T15:26:02.851036", "exception": false, "start_time": "2023-10-11T15:26:02.834718", "status": "completed"}, "tags": []}, "outputs": [], "source": []}, {"cell_type": "code", "execution_count": null, "id": "30e45e10", "metadata": {"papermill": {"duration": 0.016441, "end_time": "2023-10-11T15:26:02.884451", "exception": false, "start_time": "2023-10-11T15:26:02.868010", "status": "completed"}, "tags": []}, "outputs": [], "source": []}, {"cell_type": "markdown", "id": "bc2a5b36", "metadata": {"papermill": {"duration": 0.016523, "end_time": "2023-10-11T15:26:02.917564", "exception": false, "start_time": "2023-10-11T15:26:02.901041", "status": "completed"}, "tags": []}, "source": ["Additionally to `torch.nn`, there is also `torch.nn.functional`.\n", "It contains functions that are used in network layers.\n", "This is in contrast to `torch.nn` which defines them as `nn.Modules` (more on it below), and `torch.nn` actually uses a lot of functionalities from `torch.nn.functional`.\n", "Hence, the functional package is useful in many situations, and so we import it as well here."]}, {"cell_type": "markdown", "id": "27f2fb1e", "metadata": {"lines_to_next_cell": 2, "papermill": {"duration": 0.016472, "end_time": "2023-10-11T15:26:02.950475", "exception": false, "start_time": "2023-10-11T15:26:02.934003", "status": "completed"}, "tags": []}, "source": ["#### nn.Module\n", "\n", "In PyTorch, a neural network is built up out of modules.\n", "Modules can contain other modules, and a neural network is considered to be a module itself as well.\n", "The basic template of a module is as follows:"]}, {"cell_type": "code", "execution_count": 35, "id": "32aef1e9", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:02.985128Z", "iopub.status.busy": "2023-10-11T15:26:02.984885Z", "iopub.status.idle": "2023-10-11T15:26:02.989780Z", "shell.execute_reply": "2023-10-11T15:26:02.988838Z"}, "lines_to_next_cell": 2, "papermill": {"duration": 0.024132, "end_time": "2023-10-11T15:26:02.991091", "exception": false, "start_time": "2023-10-11T15:26:02.966959", "status": "completed"}, "tags": []}, "outputs": [], "source": ["class MyModule(nn.Module):\n", " def __init__(self):\n", " super().__init__()\n", " # Some init for my module\n", "\n", " def forward(self, x):\n", " # Function for performing the calculation of the module.\n", " pass"]}, {"cell_type": "markdown", "id": "1389b592", "metadata": {"lines_to_next_cell": 2, "papermill": {"duration": 0.015915, "end_time": "2023-10-11T15:26:03.023134", "exception": false, "start_time": "2023-10-11T15:26:03.007219", "status": "completed"}, "tags": []}, "source": ["The forward function is where the computation of the module is taken place, and is executed when you call the module (`nn = MyModule(); nn(x)`).\n", "In the init function, we usually create the parameters of the module, using `nn.Parameter`, or defining other modules that are used in the forward function.\n", "The backward calculation is done automatically, but could be overwritten as well if wanted.\n", "\n", "#### Simple classifier\n", "We can now make use of the pre-defined modules in the `torch.nn` package, and define our own small neural network.\n", "We will use a minimal network with a input layer, one hidden layer with tanh as activation function, and a output layer.\n", "In other words, our networks should look something like this:\n", "\n", "
\n", "\n", "The input neurons are shown in blue, which represent the coordinates $x_1$ and $x_2$ of a data point.\n", "The hidden neurons including a tanh activation are shown in white, and the output neuron in red.\n", "In PyTorch, we can define this as follows:"]}, {"cell_type": "code", "execution_count": 36, "id": "1eda04b6", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:03.057592Z", "iopub.status.busy": "2023-10-11T15:26:03.057224Z", "iopub.status.idle": "2023-10-11T15:26:03.064741Z", "shell.execute_reply": "2023-10-11T15:26:03.063730Z"}, "papermill": {"duration": 0.02686, "end_time": "2023-10-11T15:26:03.066006", "exception": false, "start_time": "2023-10-11T15:26:03.039146", "status": "completed"}, "tags": []}, "outputs": [], "source": ["class SimpleClassifier(nn.Module):\n", " def __init__(self, num_inputs, num_hidden, num_outputs):\n", " super().__init__()\n", " # Initialize the modules we need to build the network\n", " self.linear1 = nn.Linear(num_inputs, num_hidden)\n", " self.act_fn = nn.Tanh()\n", " self.linear2 = nn.Linear(num_hidden, num_outputs)\n", "\n", " def forward(self, x):\n", " # Perform the calculation of the model to determine the prediction\n", " x = self.linear1(x)\n", " x = self.act_fn(x)\n", " x = self.linear2(x)\n", " return x"]}, {"cell_type": "markdown", "id": "3eafa4b9", "metadata": {"papermill": {"duration": 0.015952, "end_time": "2023-10-11T15:26:03.097939", "exception": false, "start_time": "2023-10-11T15:26:03.081987", "status": "completed"}, "tags": []}, "source": ["For the examples in this notebook, we will use a tiny neural network with two input neurons and four hidden neurons.\n", "As we perform binary classification, we will use a single output neuron.\n", "Note that we do not apply a sigmoid on the output yet.\n", "This is because other functions, especially the loss, are more efficient and precise to calculate on the original outputs instead of the sigmoid output.\n", "We will discuss the detailed reason later."]}, {"cell_type": "code", "execution_count": 37, "id": "fd94d5e2", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:03.132054Z", "iopub.status.busy": "2023-10-11T15:26:03.131385Z", "iopub.status.idle": "2023-10-11T15:26:03.138071Z", "shell.execute_reply": "2023-10-11T15:26:03.137060Z"}, "papermill": {"duration": 0.025313, "end_time": "2023-10-11T15:26:03.139404", "exception": false, "start_time": "2023-10-11T15:26:03.114091", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["SimpleClassifier(\n", " (linear1): Linear(in_features=2, out_features=4, bias=True)\n", " (act_fn): Tanh()\n", " (linear2): Linear(in_features=4, out_features=1, bias=True)\n", ")\n"]}], "source": ["model = SimpleClassifier(num_inputs=2, num_hidden=4, num_outputs=1)\n", "# Printing a module shows all its submodules\n", "print(model)"]}, {"cell_type": "markdown", "id": "9ac4cf5a", "metadata": {"papermill": {"duration": 0.015718, "end_time": "2023-10-11T15:26:03.171182", "exception": false, "start_time": "2023-10-11T15:26:03.155464", "status": "completed"}, "tags": []}, "source": ["Printing the model lists all submodules it contains.\n", "The parameters of a module can be obtained by using its `parameters()` functions, or `named_parameters()` to get a name to each parameter object.\n", "For our small neural network, we have the following parameters:"]}, {"cell_type": "code", "execution_count": 38, "id": "91875cde", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:03.204312Z", "iopub.status.busy": "2023-10-11T15:26:03.203942Z", "iopub.status.idle": "2023-10-11T15:26:03.209744Z", "shell.execute_reply": "2023-10-11T15:26:03.208826Z"}, "papermill": {"duration": 0.024088, "end_time": "2023-10-11T15:26:03.211017", "exception": false, "start_time": "2023-10-11T15:26:03.186929", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["Parameter linear1.weight, shape torch.Size([4, 2])\n", "Parameter linear1.bias, shape torch.Size([4])\n", "Parameter linear2.weight, shape torch.Size([1, 4])\n", "Parameter linear2.bias, shape torch.Size([1])\n"]}], "source": ["for name, param in model.named_parameters():\n", " print(f\"Parameter {name}, shape {param.shape}\")"]}, {"cell_type": "markdown", "id": "70ae6a44", "metadata": {"papermill": {"duration": 0.015763, "end_time": "2023-10-11T15:26:03.242875", "exception": false, "start_time": "2023-10-11T15:26:03.227112", "status": "completed"}, "tags": []}, "source": ["Each linear layer has a weight matrix of the shape `[output, input]`, and a bias of the shape `[output]`.\n", "The tanh activation function does not have any parameters.\n", "Note that parameters are only registered for `nn.Module` objects that are direct object attributes, i.e. `self.a = ...`.\n", "If you define a list of modules, the parameters of those are not registered for the outer module and can cause some issues when you try to optimize your module.\n", "There are alternatives, like `nn.ModuleList`, `nn.ModuleDict` and `nn.Sequential`, that allow you to have different data structures of modules.\n", "We will use them in a few later tutorials and explain them there."]}, {"cell_type": "markdown", "id": "97273afb", "metadata": {"papermill": {"duration": 0.01727, "end_time": "2023-10-11T15:26:03.276339", "exception": false, "start_time": "2023-10-11T15:26:03.259069", "status": "completed"}, "tags": []}, "source": ["### The data\n", "\n", "PyTorch also provides a few functionalities to load the training and\n", "test data efficiently, summarized in the package `torch.utils.data`."]}, {"cell_type": "code", "execution_count": null, "id": "60e89260", "metadata": {"papermill": {"duration": 0.016163, "end_time": "2023-10-11T15:26:03.308919", "exception": false, "start_time": "2023-10-11T15:26:03.292756", "status": "completed"}, "tags": []}, "outputs": [], "source": []}, {"cell_type": "markdown", "id": "2c2bb918", "metadata": {"papermill": {"duration": 0.016295, "end_time": "2023-10-11T15:26:03.341469", "exception": false, "start_time": "2023-10-11T15:26:03.325174", "status": "completed"}, "tags": []}, "source": ["The data package defines two classes which are the standard interface for handling data in PyTorch: `data.Dataset`, and `data.DataLoader`.\n", "The dataset class provides an uniform interface to access the\n", "training/test data, while the data loader makes sure to efficiently load\n", "and stack the data points from the dataset into batches during training."]}, {"cell_type": "markdown", "id": "74ca5dc7", "metadata": {"papermill": {"duration": 0.016146, "end_time": "2023-10-11T15:26:03.373869", "exception": false, "start_time": "2023-10-11T15:26:03.357723", "status": "completed"}, "tags": []}, "source": ["#### The dataset class\n", "\n", "The dataset class summarizes the basic functionality of a dataset in a natural way.\n", "To define a dataset in PyTorch, we simply specify two functions: `__getitem__`, and `__len__`.\n", "The get-item function has to return the $i$-th data point in the dataset, while the len function returns the size of the dataset.\n", "For the XOR dataset, we can define the dataset class as follows:"]}, {"cell_type": "code", "execution_count": 39, "id": "1ebd1dcc", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:03.407891Z", "iopub.status.busy": "2023-10-11T15:26:03.406850Z", "iopub.status.idle": "2023-10-11T15:26:03.417892Z", "shell.execute_reply": "2023-10-11T15:26:03.416876Z"}, "papermill": {"duration": 0.029403, "end_time": "2023-10-11T15:26:03.419134", "exception": false, "start_time": "2023-10-11T15:26:03.389731", "status": "completed"}, "tags": []}, "outputs": [], "source": ["\n", "\n", "class XORDataset(data.Dataset):\n", " def __init__(self, size, std=0.1):\n", " \"\"\"XORDataset.\n", "\n", " Args:\n", " size: Number of data points we want to generate\n", " std: Standard deviation of the noise (see generate_continuous_xor function)\n", " \"\"\"\n", " super().__init__()\n", " self.size = size\n", " self.std = std\n", " self.generate_continuous_xor()\n", "\n", " def generate_continuous_xor(self):\n", " # Each data point in the XOR dataset has two variables, x and y, that can be either 0 or 1\n", " # The label is their XOR combination, i.e. 1 if only x or only y is 1 while the other is 0.\n", " # If x=y, the label is 0.\n", " data = torch.randint(low=0, high=2, size=(self.size, 2), dtype=torch.float32)\n", " label = (data.sum(dim=1) == 1).to(torch.long)\n", " # To make it slightly more challenging, we add a bit of gaussian noise to the data points.\n", " data += self.std * torch.randn(data.shape)\n", "\n", " self.data = data\n", " self.label = label\n", "\n", " def __len__(self):\n", " # Number of data point we have. Alternatively self.data.shape[0], or self.label.shape[0]\n", " return self.size\n", "\n", " def __getitem__(self, idx):\n", " # Return the idx-th data point of the dataset\n", " # If we have multiple things to return (data point and label), we can return them as tuple\n", " data_point = self.data[idx]\n", " data_label = self.label[idx]\n", " return data_point, data_label"]}, {"cell_type": "markdown", "id": "a9ff54ba", "metadata": {"papermill": {"duration": 0.01588, "end_time": "2023-10-11T15:26:03.450931", "exception": false, "start_time": "2023-10-11T15:26:03.435051", "status": "completed"}, "tags": []}, "source": ["Let's try to create such a dataset and inspect it:"]}, {"cell_type": "code", "execution_count": 40, "id": "0f02bd3f", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:03.484185Z", "iopub.status.busy": "2023-10-11T15:26:03.483820Z", "iopub.status.idle": "2023-10-11T15:26:03.491022Z", "shell.execute_reply": "2023-10-11T15:26:03.490039Z"}, "papermill": {"duration": 0.025491, "end_time": "2023-10-11T15:26:03.492367", "exception": false, "start_time": "2023-10-11T15:26:03.466876", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["Size of dataset: 200\n", "Data point 0: (tensor([0.9632, 0.1117]), tensor(1))\n"]}], "source": ["dataset = XORDataset(size=200)\n", "print(\"Size of dataset:\", len(dataset))\n", "print(\"Data point 0:\", dataset[0])"]}, {"cell_type": "markdown", "id": "5be8c92d", "metadata": {"lines_to_next_cell": 2, "papermill": {"duration": 0.015956, "end_time": "2023-10-11T15:26:03.524381", "exception": false, "start_time": "2023-10-11T15:26:03.508425", "status": "completed"}, "tags": []}, "source": ["To better relate to the dataset, we visualize the samples below."]}, {"cell_type": "code", "execution_count": 41, "id": "67a6d5d1", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:03.557635Z", "iopub.status.busy": "2023-10-11T15:26:03.557329Z", "iopub.status.idle": "2023-10-11T15:26:03.562931Z", "shell.execute_reply": "2023-10-11T15:26:03.562077Z"}, "papermill": {"duration": 0.02377, "end_time": "2023-10-11T15:26:03.564168", "exception": false, "start_time": "2023-10-11T15:26:03.540398", "status": "completed"}, "tags": []}, "outputs": [], "source": ["def visualize_samples(data, label):\n", " if isinstance(data, Tensor):\n", " data = data.cpu().numpy()\n", " if isinstance(label, Tensor):\n", " label = label.cpu().numpy()\n", " data_0 = data[label == 0]\n", " data_1 = data[label == 1]\n", "\n", " plt.figure(figsize=(4, 4))\n", " plt.scatter(data_0[:, 0], data_0[:, 1], edgecolor=\"#333\", label=\"Class 0\")\n", " plt.scatter(data_1[:, 0], data_1[:, 1], edgecolor=\"#333\", label=\"Class 1\")\n", " plt.title(\"Dataset samples\")\n", " plt.ylabel(r\"$x_2$\")\n", " plt.xlabel(r\"$x_1$\")\n", " plt.legend()"]}, {"cell_type": "code", "execution_count": 42, "id": "219e30d2", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:03.598210Z", "iopub.status.busy": "2023-10-11T15:26:03.597571Z", "iopub.status.idle": "2023-10-11T15:26:04.152946Z", "shell.execute_reply": "2023-10-11T15:26:04.152119Z"}, "papermill": {"duration": 0.573674, "end_time": "2023-10-11T15:26:04.154264", "exception": false, "start_time": "2023-10-11T15:26:03.580590", "status": "completed"}, "tags": []}, "outputs": [{"data": {"application/pdf": "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K5xVFcUbziQfPpK9w1rHkKKZR0Oc3dwWDkuNFKtYFhaeYRGktDXM+Lwoa2BKKeppZ/W/u+V6Af+fHCwKZW5kc3RyZWFtCmVuZG9iagoxNyAwIG9iago8PCAvVHlwZSAvRm9udCAvQmFzZUZvbnQgL0dDV1hEVitEZWphVnVTYW5zLU9ibGlxdWUgL0ZpcnN0Q2hhciAwCi9MYXN0Q2hhciAyNTUgL0ZvbnREZXNjcmlwdG9yIDE2IDAgUiAvU3VidHlwZSAvVHlwZTMKL05hbWUgL0dDV1hEVitEZWphVnVTYW5zLU9ibGlxdWUgL0ZvbnRCQm94IFsgLTEwMTYgLTM1MSAxNjYwIDEwNjggXQovRm9udE1hdHJpeCBbIDAuMDAxIDAgMCAwLjAwMSAwIDAgXSAvQ2hhclByb2NzIDE4IDAgUgovRW5jb2RpbmcgPDwgL1R5cGUgL0VuY29kaW5nIC9EaWZmZXJlbmNlcyBbIDEyMCAveCBdID4+IC9XaWR0aHMgMTUgMCBSID4+CmVuZG9iagoxNiAwIG9iago8PCAvVHlwZSAvRm9udERlc2NyaXB0b3IgL0ZvbnROYW1lIC9HQ1dYRFYrRGVqYVZ1U2Fucy1PYmxpcXVlIC9GbGFncyA5NgovRm9udEJCb3ggWyAtMTAxNiAtMzUxIDE2NjAgMTA2OCBdIC9Bc2NlbnQgOTI5IC9EZXNjZW50IC0yMzYgL0NhcEhlaWdodCAwCi9YSGVpZ2h0IDAgL0l0YWxpY0FuZ2xlIDAgL1N0ZW1WIDAgL01heFdpZHRoIDEzNTAgPj4KZW5kb2JqCjE1IDAgb2JqClsgNjAwIDYwMCA2MDAgNjAwIDYwMCA2MDAgNjAwIDYwMCA2MDAgNjAwIDYwMCA2MDAgNjAwIDYwMCA2MDAgNjAwIDYwMCA2MDAKNjAwIDYwMCA2MDAgNjAwIDYwMCA2MDAgNjAwIDYwMCA2MDAgNjAwIDYwMCA2MDAgNjAwIDYwMCAzMTggNDAxIDQ2MCA4MzggNjM2Cjk1MCA3ODAgMjc1IDM5MCAzOTAgNTAwIDgzOCAzMTggMzYxIDMxOCAzMzcgNjM2IDYzNiA2MzYgNjM2IDYzNiA2MzYgNjM2IDYzNgo2MzYgNjM2IDMzNyAzMzcgODM4IDgzOCA4MzggNTMxIDEwMDAgNjg0IDY4NiA2OTggNzcwIDYzMiA1NzUgNzc1IDc1MiAyOTUKMjk1IDY1NiA1NTcgODYzIDc0OCA3ODcgNjAzIDc4NyA2OTUgNjM1IDYxMSA3MzIgNjg0IDk4OSA2ODUgNjExIDY4NSAzOTAgMzM3CjM5MCA4MzggNTAwIDUwMCA2MTMgNjM1IDU1MCA2MzUgNjE1IDM1MiA2MzUgNjM0IDI3OCAyNzggNTc5IDI3OCA5NzQgNjM0IDYxMgo2MzUgNjM1IDQxMSA1MjEgMzkyIDYzNCA1OTIgODE4IDU5MiA1OTIgNTI1IDYzNiAzMzcgNjM2IDgzOCA2MDAgNjM2IDYwMCAzMTgKMzUyIDUxOCAxMDAwIDUwMCA1MDAgNTAwIDEzNTAgNjM1IDQwMCAxMDcwIDYwMCA2ODUgNjAwIDYwMCAzMTggMzE4IDUxOCA1MTgKNTkwIDUwMCAxMDAwIDUwMCAxMDAwIDUyMSA0MDAgMTAyOCA2MDAgNTI1IDYxMSAzMTggNDAxIDYzNiA2MzYgNjM2IDYzNiAzMzcKNTAwIDUwMCAxMDAwIDQ3MSA2MTcgODM4IDM2MSAxMDAwIDUwMCA1MDAgODM4IDQwMSA0MDEgNTAwIDYzNiA2MzYgMzE4IDUwMAo0MDEgNDcxIDYxNyA5NjkgOTY5IDk2OSA1MzEgNjg0IDY4NCA2ODQgNjg0IDY4NCA2ODQgOTc0IDY5OCA2MzIgNjMyIDYzMiA2MzIKMjk1IDI5NSAyOTUgMjk1IDc3NSA3NDggNzg3IDc4NyA3ODcgNzg3IDc4NyA4MzggNzg3IDczMiA3MzIgNzMyIDczMiA2MTEgNjA4CjYzMCA2MTMgNjEzIDYxMyA2MTMgNjEzIDYxMyA5OTUgNTUwIDYxNSA2MTUgNjE1IDYxNSAyNzggMjc4IDI3OCAyNzggNjEyIDYzNAo2MTIgNjEyIDYxMiA2MTIgNjEyIDgzOCA2MTIgNjM0IDYzNCA2MzQgNjM0IDU5MiA2MzUgNTkyIF0KZW5kb2JqCjE4IDAgb2JqCjw8IC94IDE5IDAgUiA+PgplbmRvYmoKMjQgMCBvYmoKPDwgL0xlbmd0aCAyMzUgL0ZpbHRlciAvRmxhdGVEZWNvZGUgPj4Kc3RyZWFtCnicNVFJbgAxCLvnFf5ApbAn75mq6qH9/7WGUS8DA9jYJO/BRiQ+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IDAgUgovRW5jb2RpbmcgPDwgL1R5cGUgL0VuY29kaW5nCi9EaWZmZXJlbmNlcyBbIDMyIC9zcGFjZSA0NiAvcGVyaW9kIDQ4IC96ZXJvIC9vbmUgL3R3byA1MiAvZm91ciAvZml2ZSAvc2l4IC9zZXZlbgovZWlnaHQgNjcgL0MgL0QgOTcgL2EgMTAxIC9lIDEwOCAvbCAvbSAxMTIgL3AgMTE1IC9zIC90IF0KPj4KL1dpZHRocyAyMCAwIFIgPj4KZW5kb2JqCjIxIDAgb2JqCjw8IC9UeXBlIC9Gb250RGVzY3JpcHRvciAvRm9udE5hbWUgL0JNUVFEVitEZWphVnVTYW5zIC9GbGFncyAzMgovRm9udEJCb3ggWyAtMTAyMSAtNDYzIDE3OTQgMTIzMyBdIC9Bc2NlbnQgOTI5IC9EZXNjZW50IC0yMzYgL0NhcEhlaWdodCAwCi9YSGVpZ2h0IDAgL0l0YWxpY0FuZ2xlIDAgL1N0ZW1WIDAgL01heFdpZHRoIDEzNDIgPj4KZW5kb2JqCjIwIDAgb2JqClsgNjAwIDYwMCA2MDAgNjAwIDYwMCA2MDAgNjAwIDYwMCA2MDAgNjAwIDYwMCA2MDAgNjAwIDYwMCA2MDAgNjAwIDYwMCA2MDAKNjAwIDYwMCA2MDAgNjAwIDYwMCA2MDAgNjAwIDYwMCA2MDAgNjAwIDYwMCA2MDAgNjAwIDYwMCAzMTggNDAxIDQ2MCA4MzggNjM2Cjk1MCA3ODAgMjc1IDM5MCAzOTAgNTAwIDgzOCAzMTggMzYxIDMxOCAzMzcgNjM2IDYzNiA2MzYgNjM2IDYzNiA2MzYgNjM2IDYzNgo2MzYgNjM2IDMzNyAzMzcgODM4IDgzOCA4MzggNTMxIDEwMDAgNjg0IDY4NiA2OTggNzcwIDYzMiA1NzUgNzc1IDc1MiAyOTUKMjk1IDY1NiA1NTcgODYzIDc0OCA3ODcgNjAzIDc4NyA2OTUgNjM1IDYxMSA3MzIgNjg0IDk4OSA2ODUgNjExIDY4NSAzOTAgMzM3CjM5MCA4MzggNTAwIDUwMCA2MTMgNjM1IDU1MCA2MzUgNjE1IDM1MiA2MzUgNjM0IDI3OCAyNzggNTc5IDI3OCA5NzQgNjM0IDYxMgo2MzUgNjM1IDQxMSA1MjEgMzkyIDYzNCA1OTIgODE4IDU5MiA1OTIgNTI1IDYzNiAzMzcgNjM2IDgzOCA2MDAgNjM2IDYwMCAzMTgKMzUyIDUxOCAxMDAwIDUwMCA1MDAgNTAwIDEzNDIgNjM1IDQwMCAxMDcwIDYwMCA2ODUgNjAwIDYwMCAzMTggMzE4IDUxOCA1MTgKNTkwIDUwMCAxMDAwIDUwMCAxMDAwIDUyMSA0MDAgMTAyMyA2MDAgNTI1IDYxMSAzMTggNDAxIDYzNiA2MzYgNjM2IDYzNiAzMzcKNTAwIDUwMCAxMDAwIDQ3MSA2MTIgODM4IDM2MSAxMDAwIDUwMCA1MDAgODM4IDQwMSA0MDEgNTAwIDYzNiA2MzYgMzE4IDUwMAo0MDEgNDcxIDYxMiA5NjkgOTY5IDk2OSA1MzEgNjg0IDY4NCA2ODQgNjg0IDY4NCA2ODQgOTc0IDY5OCA2MzIgNjMyIDYzMiA2MzIKMjk1IDI5NSAyOTUgMjk1IDc3NSA3NDggNzg3IDc4NyA3ODcgNzg3IDc4NyA4MzggNzg3IDczMiA3MzIgNzMyIDczMiA2MTEgNjA1CjYzMCA2MTMgNjEzIDYxMyA2MTMgNjEzIDYxMyA5ODIgNTUwIDYxNSA2MTUgNjE1IDYxNSAyNzggMjc4IDI3OCAyNzggNjEyIDYzNAo2MTIgNjEyIDYxMiA2MTIgNjEyIDgzOCA2MTIgNjM0IDYzNCA2MzQgNjM0IDU5MiA2MzUgNTkyIF0KZW5kb2JqCjIzIDAgb2JqCjw8IC9DIDI0IDAgUiAvRCAyNSAwIFIgL2EgMjYgMCBSIC9lIDI3IDAgUiAvZWlnaHQgMjggMCBSIC9maXZlIDI5IDAgUgovZm91ciAzMCAwIFIgL2wgMzEgMCBSIC9tIDMyIDAgUiAvb25lIDM0IDAgUiAvcCAzNSAwIFIgL3BlcmlvZCAzNiAwIFIKL3MgMzcgMCBSIC9zZXZlbiAzOCAwIFIgL3NpeCAzOSAwIFIgL3NwYWNlIDQwIDAgUiAvdCA0MSAwIFIgL3R3byA0MiAwIFIKL3plcm8gNDMgMCBSID4+CmVuZG9iagozIDAgb2JqCjw8IC9GMiAxNyAwIFIgL0YxIDIyIDAgUiA+PgplbmRvYmoKNCAwIG9iago8PCAvQTEgPDwgL1R5cGUgL0V4dEdTdGF0ZSAvQ0EgMCAvY2EgMSA+PgovQTIgPDwgL1R5cGUgL0V4dEdTdGF0ZSAvQ0EgMSAvY2EgMSA+PgovQTMgPDwgL1R5cGUgL0V4dEdTdGF0ZSAvQ0EgMC44IC9jYSAwLjggPj4gPj4KZW5kb2JqCjUgMCBvYmoKPDwgPj4KZW5kb2JqCjYgMCBvYmoKPDwgPj4KZW5kb2JqCjcgMCBvYmoKPDwgL00wIDEzIDAgUiAvTTEgMTQgMCBSIC9GMS1EZWphVnVTYW5zLW1pbnVzIDMzIDAgUiA+PgplbmRvYmoKMTMgMCBvYmoKPDwgL1R5cGUgL1hPYmplY3QgL1N1YnR5cGUgL0Zvcm0gL0JCb3ggWyAtOCAtOCA4IDggXSAvTGVuZ3RoIDEzMQovRmlsdGVyIC9GbGF0ZURlY29kZSA+PgpzdHJlYW0KeJxtkEEOhCAMRfc9RS/wSUtFZevSa7iZTOL9twNxQEzdNNC+PH5R/pLwTqXA+CQJS06z5HrTkNK6TIwY5tWyKMegUS3WznU4qM/QcGN0i7EUptTW6Hijm+k23pM/+rBZIUY/HA6vhHsWQyZcKTEGh98LL9vD/xGeXtTAH6KNfmNaQ/0KZW5kc3RyZWFtCmVuZG9iagoxNCAwIG9iago8PCAvVHlwZSAvWE9iamVjdCAvU3VidHlwZSAvRm9ybSAvQkJveCBbIC04IC04IDggOCBdIC9MZW5ndGggMTMxCi9GaWx0ZXIgL0ZsYXRlRGVjb2RlID4+CnN0cmVhbQp4nG2QQQ6EIAxF9z1FL/BJS0Vl69JruJlM4v23A3FATN000L48flH+kvBOpcD4JAlLTrPketOQ0rpMjBjm1bIox6BRLdbOdTioz9BwY3SLsRSm1NboeKOb6Tbekz/6sFkhRj8cDq+EexZDJlwpMQaH3wsv28P/EZ5e1MAfoo1+Y1pD/QplbmRzdHJlYW0KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9LaWRzIFsgMTEgMCBSIF0gL0NvdW50IDEgPj4KZW5kb2JqCjQ0IDAgb2JqCjw8IC9DcmVhdG9yIChNYXRwbG90bGliIHYzLjguMCwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZykKL1Byb2R1Y2VyIChNYXRwbG90bGliIHBkZiBiYWNrZW5kIHYzLjguMCkgL0NyZWF0aW9uRGF0ZSAoRDoyMDIzMTAxMTE1MjYwNFopCj4+CmVuZG9iagp4cmVmCjAgNDUKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDE2IDAwMDAwIG4gCjAwMDAwMTUxMTIgMDAwMDAgbiAKMDAwMDAxNDMwNiAwMDAwMCBuIAowMDAwMDE0MzQ5IDAwMDAwIG4gCjAwMDAwMTQ0OTEgMDAwMDAgbiAKMDAwMDAxNDUxMiAwMDAwMCBuIAowMDAwMDE0NTMzIDAwMDAwIG4gCjAwMDAwMDAwNjUgMDAwMDAgbiAKMDAwMDAwMDM0NyAwMDAwMCBuIAowMDAwMDA1MjkwIDAwMDAwIG4gCjAwMDAwMDAyMDggMDAwMDAgbiAKMDAwMDAwNTI2OSAwMDAwMCBuIAowMDAwMDE0NjA0IDAwMDAwIG4gCjAwMDAwMTQ4NTggMDAwMDAgbiAKMDAwMDAwNjAyMiAwMDAwMCBuIAowMDAwMDA1ODA3IDAwMDAwIG4gCjAwMDAwMDU0NzcgMDAwMDAgbiAKMDAwMDAwNzA3NSAwMDAwMCBuIAowMDAwMDA1MzEwIDAwMDAwIG4gCjAwMDAwMTMwMDkgMDAwMDAgbiAKMDAwMDAxMjgwMiAwMDAwMCBuIAowMDAwMDEyMzcyIDAwMDAwIG4gCjAwMDAwMTQwNjIgMDAwMDAgbiAKMDAwMDAwNzEwNyAwMDAwMCBuIAowMDAwMDA3NDE1IDAwMDAwIG4gCjAwMDAwMDc2NTIgMDAwMDAgbiAKMDAwMDAwODAzMiAwMDAwMCBuIAowMDAwMDA4MzU0IDAwMDAwIG4gCjAwMDAwMDg4MjIgMDAwMDAgbiAKMDAwMDAwOTE0NCAwMDAwMCBuIAowMDAwMDA5MzEwIDAwMDAwIG4gCjAwMDAwMDk0MjkgMDAwMDAgbiAKMDAwMDAwOTc2MCAwMDAwMCBuIAowMDAwMDA5OTMyIDAwMDAwIG4gCjAwMDAwMTAwODcgMDAwMDAgbiAKMDAwMDAxMDM5OSAwMDAwMCBuIAowMDAwMDEwNTIyIDAwMDAwIG4gCjAwMDAwMTA5MjkgMDAwMDAgbiAKMDAwMDAxMTA3MSAwMDAwMCBuIAowMDAwMDExNDY0IDAwMDAwIG4gCjAwMDAwMTE1NTQgMDAwMDAgbiAKMDAwMDAxMTc2MCAwMDAwMCBuIAowMDAwMDEyMDg0IDAwMDAwIG4gCjAwMDAwMTUxNzIgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA0NSAvUm9vdCAxIDAgUiAvSW5mbyA0NCAwIFIgPj4Kc3RhcnR4cmVmCjE1MzIzCiUlRU9GCg==", "image/svg+xml": ["\n", "\n", "\n", " \n", " \n", " \n", " \n", " 2023-10-11T15:26:03.780352\n", " image/svg+xml\n", " \n", " \n", " Matplotlib v3.8.0, https://matplotlib.org/\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "\n"], "text/plain": ["
"]}, "metadata": {}, "output_type": "display_data"}], "source": ["visualize_samples(dataset.data, dataset.label)\n", "plt.show()"]}, {"cell_type": "markdown", "id": "25e1d86c", "metadata": {"papermill": {"duration": 0.017421, "end_time": "2023-10-11T15:26:04.190054", "exception": false, "start_time": "2023-10-11T15:26:04.172633", "status": "completed"}, "tags": []}, "source": ["#### The data loader class\n", "\n", "The class `torch.utils.data.DataLoader` represents a Python iterable over a dataset with support for automatic batching, multi-process data loading and many more features.\n", "The data loader communicates with the dataset using the function `__getitem__`, and stacks its outputs as tensors over the first dimension to form a batch.\n", "In contrast to the dataset class, we usually don't have to define our own data loader class, but can just create an object of it with the dataset as input.\n", "Additionally, we can configure our data loader with the following input arguments (only a selection, see full list [here](https://pytorch.org/docs/stable/data.html#torch.utils.data.DataLoader)):\n", "\n", "* `batch_size`: Number of samples to stack per batch\n", "* `shuffle`: If True, the data is returned in a random order.\n", "This is important during training for introducing stochasticity.\n", "* `num_workers`: Number of subprocesses to use for data loading.\n", "The default, 0, means that the data will be loaded in the main process which can slow down training for datasets where loading a data point takes a considerable amount of time (e.g. large images).\n", "More workers are recommended for those, but can cause issues on Windows computers.\n", "For tiny datasets as ours, 0 workers are usually faster.\n", "* `pin_memory`: If True, the data loader will copy Tensors into CUDA pinned memory before returning them.\n", "This can save some time for large data points on GPUs.\n", "Usually a good practice to use for a training set, but not necessarily for validation and test to save memory on the GPU.\n", "* `drop_last`: If True, the last batch is dropped in case it is smaller than the specified batch size.\n", "This occurs when the dataset size is not a multiple of the batch size.\n", "Only potentially helpful during training to keep a consistent batch size.\n", "\n", "Let's create a simple data loader below:"]}, {"cell_type": "code", "execution_count": 43, "id": "0c8ca394", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:04.226130Z", "iopub.status.busy": "2023-10-11T15:26:04.225944Z", "iopub.status.idle": "2023-10-11T15:26:04.230660Z", "shell.execute_reply": "2023-10-11T15:26:04.229568Z"}, "papermill": {"duration": 0.024534, "end_time": "2023-10-11T15:26:04.231964", "exception": false, "start_time": "2023-10-11T15:26:04.207430", "status": "completed"}, "tags": []}, "outputs": [], "source": ["data_loader = data.DataLoader(dataset, batch_size=8, shuffle=True)"]}, {"cell_type": "code", "execution_count": 44, "id": "26aea44e", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:04.272321Z", "iopub.status.busy": "2023-10-11T15:26:04.272092Z", "iopub.status.idle": "2023-10-11T15:26:04.280968Z", "shell.execute_reply": "2023-10-11T15:26:04.279877Z"}, "papermill": {"duration": 0.029329, "end_time": "2023-10-11T15:26:04.282343", "exception": false, "start_time": "2023-10-11T15:26:04.253014", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["Data inputs torch.Size([8, 2]) \n", " tensor([[-0.0890, 0.8608],\n", " [ 1.0905, -0.0128],\n", " [ 0.7967, 0.2268],\n", " [-0.0688, 0.0371],\n", " [ 0.8732, -0.2240],\n", " [-0.0559, -0.0282],\n", " [ 0.9277, 0.0978],\n", " [ 1.0150, 0.9689]])\n", "Data labels torch.Size([8]) \n", " tensor([1, 1, 1, 0, 1, 0, 1, 0])\n"]}], "source": ["# next(iter(...)) catches the first batch of the data loader\n", "# If shuffle is True, this will return a different batch every time we run this cell\n", "# For iterating over the whole dataset, we can simple use \"for batch in data_loader: ...\"\n", "data_inputs, data_labels = next(iter(data_loader))\n", "\n", "# The shape of the outputs are [batch_size, d_1,...,d_N] where d_1,...,d_N are the\n", "# dimensions of the data point returned from the dataset class\n", "print(\"Data inputs\", data_inputs.shape, \"\\n\", data_inputs)\n", "print(\"Data labels\", data_labels.shape, \"\\n\", data_labels)"]}, {"cell_type": "markdown", "id": "1154f48a", "metadata": {"papermill": {"duration": 0.017425, "end_time": "2023-10-11T15:26:04.317449", "exception": false, "start_time": "2023-10-11T15:26:04.300024", "status": "completed"}, "tags": []}, "source": ["### Optimization\n", "\n", "After defining the model and the dataset, it is time to prepare the optimization of the model.\n", "During training, we will perform the following steps:\n", "\n", "1. Get a batch from the data loader\n", "2. Obtain the predictions from the model for the batch\n", "3. Calculate the loss based on the difference between predictions and labels\n", "4. Backpropagation: calculate the gradients for every parameter with respect to the loss\n", "5. Update the parameters of the model in the direction of the gradients\n", "\n", "We have seen how we can do step 1, 2 and 4 in PyTorch. Now, we will look at step 3 and 5."]}, {"cell_type": "markdown", "id": "6f706ea4", "metadata": {"papermill": {"duration": 0.017582, "end_time": "2023-10-11T15:26:04.352623", "exception": false, "start_time": "2023-10-11T15:26:04.335041", "status": "completed"}, "tags": []}, "source": ["#### Loss modules\n", "\n", "We can calculate the loss for a batch by simply performing a few tensor operations as those are automatically added to the computation graph.\n", "For instance, for binary classification, we can use Binary Cross Entropy (BCE) which is defined as follows:\n", "\n", "$$\\mathcal{L}_{BCE} = -\\sum_i \\left[ y_i \\log x_i + (1 - y_i) \\log (1 - x_i) \\right]$$\n", "\n", "where $y$ are our labels, and $x$ our predictions, both in the range of $[0,1]$.\n", "However, PyTorch already provides a list of predefined loss functions which we can use (see [here](https://pytorch.org/docs/stable/nn.html#loss-functions) for a full list).\n", "For instance, for BCE, PyTorch has two modules: `nn.BCELoss()`, `nn.BCEWithLogitsLoss()`.\n", "While `nn.BCELoss` expects the inputs $x$ to be in the range $[0,1]$, i.e. the output of a sigmoid, `nn.BCEWithLogitsLoss` combines a sigmoid layer and the BCE loss in a single class.\n", "This version is numerically more stable than using a plain Sigmoid followed by a BCE loss because of the logarithms applied in the loss function.\n", "Hence, it is advised to use loss functions applied on \"logits\" where possible (remember to not apply a sigmoid on the output of the model in this case!).\n", "For our model defined above, we therefore use the module `nn.BCEWithLogitsLoss`."]}, {"cell_type": "code", "execution_count": 45, "id": "ce3af0bc", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:04.389464Z", "iopub.status.busy": "2023-10-11T15:26:04.388677Z", "iopub.status.idle": "2023-10-11T15:26:04.393588Z", "shell.execute_reply": "2023-10-11T15:26:04.392606Z"}, "papermill": {"duration": 0.024747, "end_time": "2023-10-11T15:26:04.394928", "exception": false, "start_time": "2023-10-11T15:26:04.370181", "status": "completed"}, "tags": []}, "outputs": [], "source": ["loss_module = nn.BCEWithLogitsLoss()"]}, {"cell_type": "markdown", "id": "76acd303", "metadata": {"papermill": {"duration": 0.017458, "end_time": "2023-10-11T15:26:04.429862", "exception": false, "start_time": "2023-10-11T15:26:04.412404", "status": "completed"}, "tags": []}, "source": ["#### Stochastic Gradient Descent\n", "\n", "For updating the parameters, PyTorch provides the package `torch.optim` that has most popular optimizers implemented.\n", "We will discuss the specific optimizers and their differences later in the course, but will for now use the simplest of them: `torch.optim.SGD`.\n", "Stochastic Gradient Descent updates parameters by multiplying the gradients with a small constant, called learning rate, and subtracting those from the parameters (hence minimizing the loss).\n", "Therefore, we slowly move towards the direction of minimizing the loss.\n", "A good default value of the learning rate for a small network as ours is 0.1."]}, {"cell_type": "code", "execution_count": 46, "id": "a632c9d9", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:04.466908Z", "iopub.status.busy": "2023-10-11T15:26:04.465945Z", "iopub.status.idle": "2023-10-11T15:26:04.471148Z", "shell.execute_reply": "2023-10-11T15:26:04.470181Z"}, "papermill": {"duration": 0.025379, "end_time": "2023-10-11T15:26:04.472716", "exception": false, "start_time": "2023-10-11T15:26:04.447337", "status": "completed"}, "tags": []}, "outputs": [], "source": ["# Input to the optimizer are the parameters of the model: model.parameters()\n", "optimizer = torch.optim.SGD(model.parameters(), lr=0.1)"]}, {"cell_type": "markdown", "id": "56e856e2", "metadata": {"papermill": {"duration": 0.017563, "end_time": "2023-10-11T15:26:04.507968", "exception": false, "start_time": "2023-10-11T15:26:04.490405", "status": "completed"}, "tags": []}, "source": ["The optimizer provides two useful functions: `optimizer.step()`, and `optimizer.zero_grad()`.\n", "The step function updates the parameters based on the gradients as explained above.\n", "The function `optimizer.zero_grad()` sets the gradients of all parameters to zero.\n", "While this function seems less relevant at first, it is a crucial pre-step before performing backpropagation.\n", "If we would call the `backward` function on the loss while the parameter gradients are non-zero from the previous batch, the new gradients would actually be added to the previous ones instead of overwriting them.\n", "This is done because a parameter might occur multiple times in a computation graph, and we need to sum the gradients in this case instead of replacing them.\n", "Hence, remember to call `optimizer.zero_grad()` before calculating the gradients of a batch."]}, {"cell_type": "markdown", "id": "0ae55fa3", "metadata": {"papermill": {"duration": 0.01752, "end_time": "2023-10-11T15:26:04.542937", "exception": false, "start_time": "2023-10-11T15:26:04.525417", "status": "completed"}, "tags": []}, "source": ["### Training\n", "\n", "Finally, we are ready to train our model.\n", "As a first step, we create a slightly larger dataset and specify a data loader with a larger batch size."]}, {"cell_type": "code", "execution_count": 47, "id": "25a8b557", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:04.579375Z", "iopub.status.busy": "2023-10-11T15:26:04.579010Z", "iopub.status.idle": "2023-10-11T15:26:04.584942Z", "shell.execute_reply": "2023-10-11T15:26:04.583841Z"}, "papermill": {"duration": 0.025954, "end_time": "2023-10-11T15:26:04.586376", "exception": false, "start_time": "2023-10-11T15:26:04.560422", "status": "completed"}, "tags": []}, "outputs": [], "source": ["train_dataset = XORDataset(size=1000)\n", "train_data_loader = data.DataLoader(train_dataset, batch_size=128, shuffle=True)"]}, {"cell_type": "markdown", "id": "cc710fed", "metadata": {"papermill": {"duration": 0.017481, "end_time": "2023-10-11T15:26:04.621648", "exception": false, "start_time": "2023-10-11T15:26:04.604167", "status": "completed"}, "tags": []}, "source": ["Now, we can write a small training function.\n", "Remember our five steps: load a batch, obtain the predictions, calculate the loss, backpropagate, and update.\n", "Additionally, we have to push all data and model parameters to the device of our choice (GPU if available).\n", "For the tiny neural network we have, communicating the data to the GPU actually takes much more time than we could save from running the operation on GPU.\n", "For large networks, the communication time is significantly smaller than the actual runtime making a GPU crucial in these cases.\n", "Still, to practice, we will push the data to GPU here."]}, {"cell_type": "code", "execution_count": 48, "id": "ad7fa7bf", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:04.658213Z", "iopub.status.busy": "2023-10-11T15:26:04.657842Z", "iopub.status.idle": "2023-10-11T15:26:04.665627Z", "shell.execute_reply": "2023-10-11T15:26:04.664540Z"}, "papermill": {"duration": 0.027892, "end_time": "2023-10-11T15:26:04.667060", "exception": false, "start_time": "2023-10-11T15:26:04.639168", "status": "completed"}, "tags": []}, "outputs": [{"data": {"text/plain": ["SimpleClassifier(\n", " (linear1): Linear(in_features=2, out_features=4, bias=True)\n", " (act_fn): Tanh()\n", " (linear2): Linear(in_features=4, out_features=1, bias=True)\n", ")"]}, "execution_count": 48, "metadata": {}, "output_type": "execute_result"}], "source": ["# Push model to device. Has to be only done once\n", "model.to(device)"]}, {"cell_type": "markdown", "id": "597dd535", "metadata": {"lines_to_next_cell": 2, "papermill": {"duration": 0.017619, "end_time": "2023-10-11T15:26:04.702362", "exception": false, "start_time": "2023-10-11T15:26:04.684743", "status": "completed"}, "tags": []}, "source": ["In addition, we set our model to training mode.\n", "This is done by calling `model.train()`.\n", "There exist certain modules that need to perform a different forward\n", "step during training than during testing (e.g. BatchNorm and Dropout),\n", "and we can switch between them using `model.train()` and `model.eval()`."]}, {"cell_type": "code", "execution_count": 49, "id": "2b4efcd8", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:04.739071Z", "iopub.status.busy": "2023-10-11T15:26:04.738806Z", "iopub.status.idle": "2023-10-11T15:26:04.745432Z", "shell.execute_reply": "2023-10-11T15:26:04.744510Z"}, "papermill": {"duration": 0.026641, "end_time": "2023-10-11T15:26:04.746782", "exception": false, "start_time": "2023-10-11T15:26:04.720141", "status": "completed"}, "tags": []}, "outputs": [], "source": ["def train_model(model, optimizer, data_loader, loss_module, num_epochs=100):\n", " # Set model to train mode\n", " model.train()\n", "\n", " # Training loop\n", " for epoch in tqdm(range(num_epochs)):\n", " for data_inputs, data_labels in data_loader:\n", " # Step 1: Move input data to device (only strictly necessary if we use GPU)\n", " data_inputs = data_inputs.to(device)\n", " data_labels = data_labels.to(device)\n", "\n", " # Step 2: Run the model on the input data\n", " preds = model(data_inputs)\n", " preds = preds.squeeze(dim=1) # Output is [Batch size, 1], but we want [Batch size]\n", "\n", " # Step 3: Calculate the loss\n", " loss = loss_module(preds, data_labels.float())\n", "\n", " # Step 4: Perform backpropagation\n", " # Before calculating the gradients, we need to ensure that they are all zero.\n", " # The gradients would not be overwritten, but actually added to the existing ones.\n", " optimizer.zero_grad()\n", " # Perform backpropagation\n", " loss.backward()\n", "\n", " # Step 5: Update the parameters\n", " optimizer.step()"]}, {"cell_type": "code", "execution_count": 50, "id": "d171eee0", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:04.783796Z", "iopub.status.busy": "2023-10-11T15:26:04.783485Z", "iopub.status.idle": "2023-10-11T15:26:06.048467Z", "shell.execute_reply": "2023-10-11T15:26:06.047443Z"}, "papermill": {"duration": 1.286464, "end_time": "2023-10-11T15:26:06.050930", "exception": false, "start_time": "2023-10-11T15:26:04.764466", "status": "completed"}, "tags": []}, "outputs": [{"data": {"application/vnd.jupyter.widget-view+json": {"model_id": "d4200f8838e34c138fbface6291caaed", "version_major": 2, "version_minor": 0}, "text/plain": [" 0%| | 0/100 [00:00 Don't drop the last batch although it is smaller than 128\n", "test_data_loader = data.DataLoader(test_dataset, batch_size=128, shuffle=False, drop_last=False)"]}, {"cell_type": "markdown", "id": "4019755c", "metadata": {"lines_to_next_cell": 2, "papermill": {"duration": 0.018058, "end_time": "2023-10-11T15:26:06.548547", "exception": false, "start_time": "2023-10-11T15:26:06.530489", "status": "completed"}, "tags": []}, "source": ["As metric, we will use accuracy which is calculated as follows:\n", "\n", "$$acc = \\frac{\\#\\text{correct predictions}}{\\#\\text{all predictions}} = \\frac{TP+TN}{TP+TN+FP+FN}$$\n", "\n", "where TP are the true positives, TN true negatives, FP false positives, and FN the fale negatives.\n", "\n", "When evaluating the model, we don't need to keep track of the computation graph as we don't intend to calculate the gradients.\n", "This reduces the required memory and speed up the model.\n", "In PyTorch, we can deactivate the computation graph using `with torch.no_grad(): ...`.\n", "Remember to additionally set the model to eval mode."]}, {"cell_type": "code", "execution_count": 55, "id": "9569fd43", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:06.586456Z", "iopub.status.busy": "2023-10-11T15:26:06.586070Z", "iopub.status.idle": "2023-10-11T15:26:06.595155Z", "shell.execute_reply": "2023-10-11T15:26:06.594039Z"}, "papermill": {"duration": 0.030427, "end_time": "2023-10-11T15:26:06.597093", "exception": false, "start_time": "2023-10-11T15:26:06.566666", "status": "completed"}, "tags": []}, "outputs": [], "source": ["def eval_model(model, data_loader):\n", " model.eval() # Set model to eval mode\n", " true_preds, num_preds = 0.0, 0.0\n", "\n", " with torch.no_grad(): # Deactivate gradients for the following code\n", " for data_inputs, data_labels in data_loader:\n", " # Determine prediction of model on dev set\n", " data_inputs, data_labels = data_inputs.to(device), data_labels.to(device)\n", " preds = model(data_inputs)\n", " preds = preds.squeeze(dim=1)\n", " preds = torch.sigmoid(preds) # Sigmoid to map predictions between 0 and 1\n", " pred_labels = (preds >= 0.5).long() # Binarize predictions to 0 and 1\n", "\n", " # Keep records of predictions for the accuracy metric (true_preds=TP+TN, num_preds=TP+TN+FP+FN)\n", " true_preds += (pred_labels == data_labels).sum()\n", " num_preds += data_labels.shape[0]\n", "\n", " acc = true_preds / num_preds\n", " print(f\"Accuracy of the model: {100.0*acc:4.2f}%\")"]}, {"cell_type": "code", "execution_count": 56, "id": "32cc570e", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:06.634882Z", "iopub.status.busy": "2023-10-11T15:26:06.634519Z", "iopub.status.idle": "2023-10-11T15:26:06.649886Z", "shell.execute_reply": "2023-10-11T15:26:06.648709Z"}, "papermill": {"duration": 0.036095, "end_time": "2023-10-11T15:26:06.651331", "exception": false, "start_time": "2023-10-11T15:26:06.615236", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["Accuracy of the model: 100.00%\n"]}], "source": ["eval_model(model, test_data_loader)"]}, {"cell_type": "markdown", "id": "595036dc", "metadata": {"papermill": {"duration": 0.018177, "end_time": "2023-10-11T15:26:06.687812", "exception": false, "start_time": "2023-10-11T15:26:06.669635", "status": "completed"}, "tags": []}, "source": ["If we trained our model correctly, we should see a score close to 100% accuracy.\n", "However, this is only possible because of our simple task, and\n", "unfortunately, we usually don't get such high scores on test sets of\n", "more complex tasks."]}, {"cell_type": "markdown", "id": "83b19efb", "metadata": {"lines_to_next_cell": 2, "papermill": {"duration": 0.018164, "end_time": "2023-10-11T15:26:06.724215", "exception": false, "start_time": "2023-10-11T15:26:06.706051", "status": "completed"}, "tags": []}, "source": ["#### Visualizing classification boundaries\n", "\n", "To visualize what our model has learned, we can perform a prediction for every data point in a range of $[-0.5, 1.5]$, and visualize the predicted class as in the sample figure at the beginning of this section.\n", "This shows where the model has created decision boundaries, and which points would be classified as $0$, and which as $1$.\n", "We therefore get a background image out of blue (class 0) and orange (class 1).\n", "The spots where the model is uncertain we will see a blurry overlap.\n", "The specific code is less relevant compared to the output figure which\n", "should hopefully show us a clear separation of classes:"]}, {"cell_type": "code", "execution_count": 57, "id": "3c8306aa", "metadata": {"execution": {"iopub.execute_input": "2023-10-11T15:26:06.762689Z", "iopub.status.busy": "2023-10-11T15:26:06.761844Z", "iopub.status.idle": "2023-10-11T15:26:07.235253Z", "shell.execute_reply": "2023-10-11T15:26:07.234131Z"}, "papermill": {"duration": 0.494205, "end_time": "2023-10-11T15:26:07.236614", "exception": false, "start_time": "2023-10-11T15:26:06.742409", "status": "completed"}, "tags": []}, "outputs": [{"name": "stderr", "output_type": "stream", "text": ["/usr/local/lib/python3.10/dist-packages/torch/functional.py:504: UserWarning: torch.meshgrid: in an upcoming release, it will be required to pass the indexing argument. (Triggered internally at ../aten/src/ATen/native/TensorShape.cpp:3483.)\n", " return _VF.meshgrid(tensors, **kwargs) # type: ignore[attr-defined]\n"]}, {"data": {"application/pdf": "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IDAgUiAvU3VidHlwZSAvVHlwZTMKL05hbWUgL0dDV1hEVitEZWphVnVTYW5zLU9ibGlxdWUgL0ZvbnRCQm94IFsgLTEwMTYgLTM1MSAxNjYwIDEwNjggXQovRm9udE1hdHJpeCBbIDAuMDAxIDAgMCAwLjAwMSAwIDAgXSAvQ2hhclByb2NzIDE5IDAgUgovRW5jb2RpbmcgPDwgL1R5cGUgL0VuY29kaW5nIC9EaWZmZXJlbmNlcyBbIDEyMCAveCBdID4+IC9XaWR0aHMgMTYgMCBSID4+CmVuZG9iagoxNyAwIG9iago8PCAvVHlwZSAvRm9udERlc2NyaXB0b3IgL0ZvbnROYW1lIC9HQ1dYRFYrRGVqYVZ1U2Fucy1PYmxpcXVlIC9GbGFncyA5NgovRm9udEJCb3ggWyAtMTAxNiAtMzUxIDE2NjAgMTA2OCBdIC9Bc2NlbnQgOTI5IC9EZXNjZW50IC0yMzYgL0NhcEhlaWdodCAwCi9YSGVpZ2h0IDAgL0l0YWxpY0FuZ2xlIDAgL1N0ZW1WIDAgL01heFdpZHRoIDEzNTAgPj4KZW5kb2JqCjE2IDAgb2JqClsgNjAwIDYwMCA2MDAgNjAwIDYwMCA2MDAgNjAwIDYwMCA2MDAgNjAwIDYwMCA2MDAgNjAwIDYwMCA2MDAgNjAwIDYwMCA2MDAKNjAwIDYwMCA2MDAgNjAwIDYwMCA2MDAgNjAwIDYwMCA2MDAgNjAwIDYwMCA2MDAgNjAwIDYwMCAzMTggNDAxIDQ2MCA4MzggNjM2Cjk1MCA3ODAgMjc1IDM5MCAzOTAgNTAwIDgzOCAzMTggMzYxIDMxOCAzMzcgNjM2IDYzNiA2MzYgNjM2IDYzNiA2MzYgNjM2IDYzNgo2MzYgNjM2IDMzNyAzMzcgODM4IDgzOCA4MzggNTMxIDEwMDAgNjg0IDY4NiA2OTggNzcwIDYzMiA1NzUgNzc1IDc1MiAyOTUKMjk1IDY1NiA1NTcgODYzIDc0OCA3ODcgNjAzIDc4NyA2OTUgNjM1IDYxMSA3MzIgNjg0IDk4OSA2ODUgNjExIDY4NSAzOTAgMzM3CjM5MCA4MzggNTAwIDUwMCA2MTMgNjM1IDU1MCA2MzUgNjE1IDM1MiA2MzUgNjM0IDI3OCAyNzggNTc5IDI3OCA5NzQgNjM0IDYxMgo2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c2NlbnQgLTIzNiAvQ2FwSGVpZ2h0IDAKL1hIZWlnaHQgMCAvSXRhbGljQW5nbGUgMCAvU3RlbVYgMCAvTWF4V2lkdGggMTM0MiA+PgplbmRvYmoKMjEgMCBvYmoKWyA2MDAgNjAwIDYwMCA2MDAgNjAwIDYwMCA2MDAgNjAwIDYwMCA2MDAgNjAwIDYwMCA2MDAgNjAwIDYwMCA2MDAgNjAwIDYwMAo2MDAgNjAwIDYwMCA2MDAgNjAwIDYwMCA2MDAgNjAwIDYwMCA2MDAgNjAwIDYwMCA2MDAgNjAwIDMxOCA0MDEgNDYwIDgzOCA2MzYKOTUwIDc4MCAyNzUgMzkwIDM5MCA1MDAgODM4IDMxOCAzNjEgMzE4IDMzNyA2MzYgNjM2IDYzNiA2MzYgNjM2IDYzNiA2MzYgNjM2CjYzNiA2MzYgMzM3IDMzNyA4MzggODM4IDgzOCA1MzEgMTAwMCA2ODQgNjg2IDY5OCA3NzAgNjMyIDU3NSA3NzUgNzUyIDI5NQoyOTUgNjU2IDU1NyA4NjMgNzQ4IDc4NyA2MDMgNzg3IDY5NSA2MzUgNjExIDczMiA2ODQgOTg5IDY4NSA2MTEgNjg1IDM5MCAzMzcKMzkwIDgzOCA1MDAgNTAwIDYxMyA2MzUgNTUwIDYzNSA2MTUgMzUyIDYzNSA2MzQgMjc4IDI3OCA1NzkgMjc4IDk3NCA2MzQgNjEyCjYzNSA2MzUgNDExIDUyMSAzOTIgNjM0IDU5MiA4MTggNTkyIDU5MiA1MjUgNjM2IDMzNyA2MzYgODM4IDYwMCA2MzYgNjAwIDMxOAozNTIgNTE4IDEwMDAgNTAwIDUwMCA1MDAgMTM0MiA2MzUgNDAwIDEwNzAgNjAwIDY4NSA2MDAgNjAwIDMxOCAzMTggNTE4IDUxOAo1OTAgNTAwIDEwMDAgNTAwIDEwMDAgNTIxIDQwMCAxMDIzIDYwMCA1MjUgNjExIDMxOCA0MDEgNjM2IDYzNiA2MzYgNjM2IDMzNwo1MDAgNTAwIDEwMDAgNDcxIDYxMiA4MzggMzYxIDEwMDAgNTAwIDUwMCA4MzggNDAxIDQwMSA1MDAgNjM2IDYzNiAzMTggNTAwCjQwMSA0NzEgNjEyIDk2OSA5NjkgOTY5IDUzMSA2ODQgNjg0IDY4NCA2ODQgNjg0IDY4NCA5NzQgNjk4IDYzMiA2MzIgNjMyIDYzMgoyOTUgMjk1IDI5NSAyOTUgNzc1IDc0OCA3ODcgNzg3IDc4NyA3ODcgNzg3IDgzOCA3ODcgNzMyIDczMiA3MzIgNzMyIDYxMSA2MDUKNjMwIDYxMyA2MTMgNjEzIDYxMyA2MTMgNjEzIDk4MiA1NTAgNjE1IDYxNSA2MTUgNjE1IDI3OCAyNzggMjc4IDI3OCA2MTIgNjM0CjYxMiA2MTIgNjEyIDYxMiA2MTIgODM4IDYxMiA2MzQgNjM0IDYzNCA2MzQgNTkyIDYzNSA1OTIgXQplbmRvYmoKMjQgMCBvYmoKPDwgL0MgMjUgMCBSIC9EIDI2IDAgUiAvYSAyNyAwIFIgL2UgMjggMCBSIC9maXZlIDI5IDAgUiAvbCAzMCAwIFIKL20gMzEgMCBSIC9vbmUgMzMgMCBSIC9wIDM0IDAgUiAvcGVyaW9kIDM1IDAgUiAvcyAzNiAwIFIgL3NldmVuIDM3IDAgUgovc3BhY2UgMzggMCBSIC90IDM5IDAgUiAvdHdvIDQwIDAgUiAvemVybyA0MSAwIFIgPj4KZW5kb2JqCjMgMCBvYmoKPDwgL0YyIDE4IDAgUiAvRjEgMjMgMCBSID4+CmVuZG9iago0IDAgb2JqCjw8IC9BMSA8PCAvVHlwZSAvRXh0R1N0YXRlIC9DQSAwIC9jYSAxID4+Ci9BMiA8PCAvVHlwZSAvRXh0R1N0YXRlIC9DQSAxIC9jYSAxID4+Ci9BMyA8PCAvVHlwZSAvRXh0R1N0YXRlIC9DQSAwLjggL2NhIDAuOCA+PiA+PgplbmRvYmoKNSAwIG9iago8PCA+PgplbmRvYmoKNiAwIG9iago8PCA+PgplbmRvYmoKNyAwIG9iago8PCAvSTEgMTMgMCBSIC9NMCAxNCAwIFIgL00xIDE1IDAgUiAvRjEtRGVqYVZ1U2Fucy1taW51cyAzMiAwIFIgPj4KZW5kb2JqCjEzIDAgb2JqCjw8IC9UeXBlIC9YT2JqZWN0IC9TdWJ0eXBlIC9JbWFnZSAvV2lkdGggMzA5IC9IZWlnaHQgMzA4Ci9Db2xvclNwYWNlIC9EZXZpY2VSR0IgL0JpdHNQZXJDb21wb25lbnQgOCAvRmlsdGVyIC9GbGF0ZURlY29kZQovRGVjb2RlUGFybXMgPDwgL1By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OTIgMDAwMDAgbiAKMDAwMDAwNTEyNyAwMDAwMCBuIAowMDAwMDExNzg0IDAwMDAwIG4gCjAwMDAwMTE1NzcgMDAwMDAgbiAKMDAwMDAxMTE2MiAwMDAwMCBuIAowMDAwMDEyODM3IDAwMDAwIG4gCjAwMDAwMDY5MjQgMDAwMDAgbiAKMDAwMDAwNzIzMiAwMDAwMCBuIAowMDAwMDA3NDY5IDAwMDAwIG4gCjAwMDAwMDc4NDkgMDAwMDAgbiAKMDAwMDAwODE3MSAwMDAwMCBuIAowMDAwMDA4NDkzIDAwMDAwIG4gCjAwMDAwMDg2MTIgMDAwMDAgbiAKMDAwMDAwODk0MyAwMDAwMCBuIAowMDAwMDA5MTE1IDAwMDAwIG4gCjAwMDAwMDkyNzAgMDAwMDAgbiAKMDAwMDAwOTU4MiAwMDAwMCBuIAowMDAwMDA5NzA1IDAwMDAwIG4gCjAwMDAwMTAxMTIgMDAwMDAgbiAKMDAwMDAxMDI1NCAwMDAwMCBuIAowMDAwMDEwMzQ0IDAwMDAwIG4gCjAwMDAwMTA1NTAgMDAwMDAgbiAKMDAwMDAxMDg3NCAwMDAwMCBuIAowMDAwMDQ5MjYxIDAwMDAwIG4gCjAwMDAwNDk4NTEgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA0NCAvUm9vdCAxIDAgUiAvSW5mbyA0MyAwIFIgPj4Kc3RhcnR4cmVmCjUwMDAyCiUlRU9GCg==", "image/svg+xml": ["\n", "\n", "\n", " \n", " \n", " \n", " \n", " 2023-10-11T15:26:06.965444\n", " image/svg+xml\n", " \n", " \n", " Matplotlib v3.8.0, https://matplotlib.org/\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "\n"], "text/plain": ["
"]}, "metadata": {}, "output_type": "display_data"}], "source": ["@torch.no_grad() # Decorator, same effect as \"with torch.no_grad(): ...\" over the whole function.\n", "def visualize_classification(model, data, label):\n", " if isinstance(data, Tensor):\n", " data = data.cpu().numpy()\n", " if isinstance(label, Tensor):\n", " label = label.cpu().numpy()\n", " data_0 = data[label == 0]\n", " data_1 = data[label == 1]\n", "\n", " plt.figure(figsize=(4, 4))\n", " plt.scatter(data_0[:, 0], data_0[:, 1], edgecolor=\"#333\", label=\"Class 0\")\n", " plt.scatter(data_1[:, 0], data_1[:, 1], edgecolor=\"#333\", label=\"Class 1\")\n", " plt.title(\"Dataset samples\")\n", " plt.ylabel(r\"$x_2$\")\n", " plt.xlabel(r\"$x_1$\")\n", " plt.legend()\n", "\n", " # Let's make use of a lot of operations we have learned above\n", " model.to(device)\n", " c0 = Tensor(to_rgba(\"C0\")).to(device)\n", " c1 = Tensor(to_rgba(\"C1\")).to(device)\n", " x1 = torch.arange(-0.5, 1.5, step=0.01, device=device)\n", " x2 = torch.arange(-0.5, 1.5, step=0.01, device=device)\n", " xx1, xx2 = torch.meshgrid(x1, x2) # Meshgrid function as in numpy\n", " model_inputs = torch.stack([xx1, xx2], dim=-1)\n", " preds = model(model_inputs)\n", " preds = torch.sigmoid(preds)\n", " # Specifying \"None\" in a dimension creates a new one\n", " output_image = (1 - preds) * c0[None, None] + preds * c1[None, None]\n", " output_image = (\n", " output_image.cpu().numpy()\n", " ) # Convert to numpy array. This only works for tensors on CPU, hence first push to CPU\n", " plt.imshow(output_image, origin=\"lower\", extent=(-0.5, 1.5, -0.5, 1.5))\n", " plt.grid(False)\n", "\n", "\n", "visualize_classification(model, dataset.data, dataset.label)\n", "plt.show()"]}, {"cell_type": "markdown", "id": "c8a8a0db", "metadata": {"papermill": {"duration": 0.020894, "end_time": "2023-10-11T15:26:07.280671", "exception": false, "start_time": "2023-10-11T15:26:07.259777", "status": "completed"}, "tags": []}, "source": ["The decision boundaries might not look exactly as in the figure in the preamble of this section which can be caused by running it on CPU or a different GPU architecture.\n", "Nevertheless, the result on the accuracy metric should be the approximately the same."]}, {"cell_type": "markdown", "id": "34a88bc1", "metadata": {"papermill": {"duration": 0.020741, "end_time": "2023-10-11T15:26:07.322197", "exception": false, "start_time": "2023-10-11T15:26:07.301456", "status": "completed"}, "tags": []}, "source": ["## Additional features we didn't get to discuss yet\n", "\n", "Finally, you are all set to start with your own PyTorch project!\n", "In summary, we have looked at how we can build neural networks in PyTorch, and train and test them on data.\n", "However, there is still much more to PyTorch we haven't discussed yet.\n", "In the coming series of Jupyter notebooks, we will discover more and more functionalities of PyTorch, so that you also get familiar to PyTorch concepts beyond the basics.\n", "If you are already interested in learning more of PyTorch, we recommend the official [tutorial website](https://pytorch.org/tutorials/) that contains many tutorials on various topics.\n", "Especially logging with Tensorboard ([tutorial\n", "here](https://pytorch.org/tutorials/intermediate/tensorboard_tutorial.html))\n", "is a good practice that we will explore from Tutorial 5 on."]}, {"cell_type": "markdown", "id": "3400ceac", "metadata": {"papermill": {"duration": 0.020656, "end_time": "2023-10-11T15:26:07.363590", "exception": false, "start_time": "2023-10-11T15:26:07.342934", "status": "completed"}, "tags": []}, "source": ["## Congratulations - Time to Join the Community!\n", "\n", "Congratulations on completing this notebook tutorial! If you enjoyed this and would like to join the Lightning\n", "movement, you can do so in the following ways!\n", "\n", "### Star [Lightning](https://github.com/Lightning-AI/lightning) on GitHub\n", "The easiest way to help our community is just by starring the GitHub repos! This helps raise awareness of the cool\n", "tools we're building.\n", "\n", "### Join our [Slack](https://www.pytorchlightning.ai/community)!\n", "The best way to keep up to date on the latest advancements is to join our community! Make sure to introduce yourself\n", "and share your interests in `#general` channel\n", "\n", "\n", "### Contributions !\n", "The best way to contribute to our community is to become a code contributor! At any time you can go to\n", "[Lightning](https://github.com/Lightning-AI/lightning) or [Bolt](https://github.com/Lightning-AI/lightning-bolts)\n", "GitHub Issues page and filter for \"good first issue\".\n", "\n", "* [Lightning good first issue](https://github.com/Lightning-AI/lightning/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)\n", "* [Bolt good first issue](https://github.com/Lightning-AI/lightning-bolts/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)\n", "* You can also contribute your own notebooks with useful examples !\n", "\n", "### Great thanks from the entire Pytorch Lightning Team for your interest !\n", "\n", "[![Pytorch Lightning](data:image/png;base64,NDA0OiBOb3QgRm91bmQ=){height=\"60px\" width=\"240px\"}](https://pytorchlightning.ai)"]}, {"cell_type": "raw", "metadata": {"raw_mimetype": "text/restructuredtext"}, "source": [".. customcarditem::\n", " :header: Tutorial 1: Introduction to PyTorch\n", " :card_description: This tutorial will give a short introduction to PyTorch basics, and get you setup for writing your own neural networks. This notebook is part of a lecture series on Deep...\n", " :tags: GPU/TPU,UvA-DL-Course\n", " :image: _static/images/course_UvA-DL/01-introduction-to-pytorch.jpg"]}], "metadata": {"jupytext": {"cell_metadata_filter": "colab,colab_type,id,-all", "formats": "ipynb,py:percent", "main_language": "python"}, "language_info": {"codemirror_mode": {"name": "ipython", "version": 3}, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.10.12"}, "papermill": {"default_parameters": {}, "duration": 15.029135, "end_time": "2023-10-11T15:26:08.605852", "environment_variables": {}, "exception": null, "input_path": "course_UvA-DL/01-introduction-to-pytorch/Introduction_to_PyTorch.ipynb", "output_path": ".notebooks/course_UvA-DL/01-introduction-to-pytorch.ipynb", "parameters": {}, "start_time": "2023-10-11T15:25:53.576717", "version": "2.4.0"}, "widgets": {"application/vnd.jupyter.widget-state+json": {"state": {"1c136f2f153949f182894d63f39e10ab": {"model_module": "@jupyter-widgets/controls", "model_module_version": "2.0.0", "model_name": "HTMLStyleModel", "state": {"_model_module": "@jupyter-widgets/controls", "_model_module_version": "2.0.0", "_model_name": "HTMLStyleModel", "_view_count": null, "_view_module": "@jupyter-widgets/base", "_view_module_version": "2.0.0", "_view_name": "StyleView", "background": null, "description_width": "", "font_size": null, "text_color": null}}, "1df83b443c89404fa9f16c956d568cef": {"model_module": "@jupyter-widgets/controls", "model_module_version": "2.0.0", "model_name": "HTMLModel", "state": {"_dom_classes": [], "_model_module": "@jupyter-widgets/controls", "_model_module_version": "2.0.0", "_model_name": "HTMLModel", "_view_count": null, "_view_module": "@jupyter-widgets/controls", "_view_module_version": "2.0.0", "_view_name": "HTMLView", "description": "", "description_allow_html": false, "layout": "IPY_MODEL_9281b4a440eb426eabc18ddb8624d3e5", "placeholder": "\u200b", "style": "IPY_MODEL_1c136f2f153949f182894d63f39e10ab", "tabbable": null, "tooltip": null, "value": "100%"}}, "3d18b5e789a447b18bdbe8c792d9b40a": {"model_module": "@jupyter-widgets/base", "model_module_version": "2.0.0", "model_name": "LayoutModel", "state": {"_model_module": "@jupyter-widgets/base", "_model_module_version": "2.0.0", "_model_name": "LayoutModel", "_view_count": null, "_view_module": "@jupyter-widgets/base", "_view_module_version": "2.0.0", "_view_name": "LayoutView", "align_content": null, "align_items": null, "align_self": null, "border_bottom": null, "border_left": null, "border_right": null, "border_top": null, "bottom": null, "display": null, "flex": null, "flex_flow": null, "grid_area": null, "grid_auto_columns": null, "grid_auto_flow": null, "grid_auto_rows": null, "grid_column": null, "grid_gap": null, "grid_row": null, "grid_template_areas": null, "grid_template_columns": null, "grid_template_rows": null, "height": null, "justify_content": null, "justify_items": null, "left": null, "margin": null, "max_height": null, "max_width": null, "min_height": null, "min_width": null, "object_fit": null, "object_position": null, "order": null, "overflow": null, "padding": null, "right": null, "top": null, "visibility": null, "width": null}}, "469ced458f2149bf87eb29694a0dca3c": {"model_module": "@jupyter-widgets/controls", "model_module_version": "2.0.0", "model_name": "FloatProgressModel", "state": {"_dom_classes": [], "_model_module": "@jupyter-widgets/controls", "_model_module_version": "2.0.0", "_model_name": "FloatProgressModel", "_view_count": null, "_view_module": "@jupyter-widgets/controls", "_view_module_version": "2.0.0", "_view_name": "ProgressView", "bar_style": "success", "description": "", "description_allow_html": false, "layout": "IPY_MODEL_fef432417d884171b400cbb593f78fae", "max": 100.0, "min": 0.0, "orientation": "horizontal", "style": "IPY_MODEL_911695dde12144d69a0b94d4a8234c54", "tabbable": null, "tooltip": null, "value": 100.0}}, "6c5f9790a00540a398a791c87cf65450": {"model_module": "@jupyter-widgets/controls", "model_module_version": "2.0.0", "model_name": "HTMLModel", "state": {"_dom_classes": [], "_model_module": "@jupyter-widgets/controls", "_model_module_version": "2.0.0", "_model_name": "HTMLModel", "_view_count": null, "_view_module": "@jupyter-widgets/controls", "_view_module_version": "2.0.0", "_view_name": "HTMLView", "description": "", "description_allow_html": false, "layout": "IPY_MODEL_3d18b5e789a447b18bdbe8c792d9b40a", "placeholder": "\u200b", "style": "IPY_MODEL_f0eea5ffe6c94f3f95550522108bcda8", "tabbable": null, "tooltip": null, "value": " 100/100 [00:01<00:00, 82.83it/s]"}}, "911695dde12144d69a0b94d4a8234c54": {"model_module": "@jupyter-widgets/controls", "model_module_version": "2.0.0", "model_name": "ProgressStyleModel", "state": {"_model_module": "@jupyter-widgets/controls", "_model_module_version": "2.0.0", "_model_name": "ProgressStyleModel", "_view_count": null, "_view_module": "@jupyter-widgets/base", "_view_module_version": "2.0.0", "_view_name": "StyleView", "bar_color": null, "description_width": ""}}, "9281b4a440eb426eabc18ddb8624d3e5": {"model_module": "@jupyter-widgets/base", "model_module_version": "2.0.0", "model_name": "LayoutModel", "state": {"_model_module": "@jupyter-widgets/base", "_model_module_version": "2.0.0", "_model_name": "LayoutModel", "_view_count": null, "_view_module": "@jupyter-widgets/base", "_view_module_version": "2.0.0", "_view_name": "LayoutView", "align_content": null, "align_items": null, "align_self": null, "border_bottom": null, "border_left": null, "border_right": null, "border_top": null, "bottom": null, "display": null, "flex": null, "flex_flow": null, "grid_area": null, "grid_auto_columns": null, "grid_auto_flow": null, "grid_auto_rows": null, "grid_column": null, "grid_gap": null, "grid_row": null, "grid_template_areas": null, "grid_template_columns": null, "grid_template_rows": null, "height": null, "justify_content": null, "justify_items": null, "left": null, "margin": null, "max_height": null, "max_width": null, "min_height": null, "min_width": null, "object_fit": null, "object_position": null, "order": null, "overflow": null, "padding": null, "right": null, "top": null, "visibility": null, "width": null}}, "a26ecdc9e4ab4562bb1ecdcaeaad6150": {"model_module": "@jupyter-widgets/base", "model_module_version": "2.0.0", "model_name": "LayoutModel", "state": {"_model_module": "@jupyter-widgets/base", "_model_module_version": "2.0.0", "_model_name": "LayoutModel", "_view_count": null, "_view_module": "@jupyter-widgets/base", "_view_module_version": "2.0.0", "_view_name": "LayoutView", "align_content": null, "align_items": null, "align_self": null, "border_bottom": null, "border_left": null, "border_right": null, "border_top": null, "bottom": null, "display": null, "flex": null, "flex_flow": null, "grid_area": null, "grid_auto_columns": null, "grid_auto_flow": null, "grid_auto_rows": null, "grid_column": null, "grid_gap": null, "grid_row": null, "grid_template_areas": null, "grid_template_columns": null, "grid_template_rows": null, "height": null, "justify_content": null, "justify_items": null, "left": null, "margin": null, "max_height": null, "max_width": null, "min_height": null, "min_width": null, "object_fit": null, "object_position": null, "order": null, "overflow": null, "padding": null, "right": null, "top": null, "visibility": null, "width": null}}, "d4200f8838e34c138fbface6291caaed": {"model_module": "@jupyter-widgets/controls", "model_module_version": "2.0.0", "model_name": "HBoxModel", "state": {"_dom_classes": [], "_model_module": "@jupyter-widgets/controls", "_model_module_version": "2.0.0", "_model_name": "HBoxModel", "_view_count": null, "_view_module": "@jupyter-widgets/controls", "_view_module_version": "2.0.0", "_view_name": "HBoxView", "box_style": "", "children": ["IPY_MODEL_1df83b443c89404fa9f16c956d568cef", "IPY_MODEL_469ced458f2149bf87eb29694a0dca3c", "IPY_MODEL_6c5f9790a00540a398a791c87cf65450"], "layout": "IPY_MODEL_a26ecdc9e4ab4562bb1ecdcaeaad6150", "tabbable": null, "tooltip": null}}, "f0eea5ffe6c94f3f95550522108bcda8": {"model_module": "@jupyter-widgets/controls", "model_module_version": "2.0.0", "model_name": "HTMLStyleModel", "state": {"_model_module": "@jupyter-widgets/controls", "_model_module_version": "2.0.0", "_model_name": "HTMLStyleModel", "_view_count": null, "_view_module": "@jupyter-widgets/base", "_view_module_version": "2.0.0", "_view_name": "StyleView", "background": null, "description_width": "", "font_size": null, "text_color": null}}, "fef432417d884171b400cbb593f78fae": {"model_module": "@jupyter-widgets/base", "model_module_version": "2.0.0", "model_name": "LayoutModel", "state": {"_model_module": "@jupyter-widgets/base", "_model_module_version": "2.0.0", "_model_name": "LayoutModel", "_view_count": null, "_view_module": "@jupyter-widgets/base", "_view_module_version": "2.0.0", "_view_name": "LayoutView", "align_content": null, "align_items": null, "align_self": null, "border_bottom": null, "border_left": null, "border_right": null, "border_top": null, "bottom": null, "display": null, "flex": null, "flex_flow": null, "grid_area": null, "grid_auto_columns": null, "grid_auto_flow": null, "grid_auto_rows": null, "grid_column": null, "grid_gap": null, "grid_row": null, "grid_template_areas": null, "grid_template_columns": null, "grid_template_rows": null, "height": null, "justify_content": null, "justify_items": null, "left": null, "margin": null, "max_height": null, "max_width": null, "min_height": null, "min_width": null, "object_fit": null, "object_position": null, "order": null, "overflow": null, "padding": null, "right": null, "top": null, "visibility": null, "width": null}}}, "version_major": 2, "version_minor": 0}}}, "nbformat": 4, "nbformat_minor": 5}