From d760cdfa85c095a500907f2ae1ab8b8d79409c39 Mon Sep 17 00:00:00 2001 From: Morten Hjorth-Jensen Date: Wed, 8 Dec 2021 06:54:30 +0100 Subject: [PATCH] update --- doc/BookChapters/chapter11.ipynb | 3375 ------------------- doc/BookChapters/chapter12.do.txt | 593 +++- doc/BookChapters/chapter13.do.txt | 1246 +++++++ doc/BookChapters/chapteroptimization.do.txt | 291 +- doc/BookChapters/ipynb-chapter12-src.tar.gz | Bin 87846 -> 88086 bytes doc/LectureNotes/_toc.yml | 3 + doc/LectureNotes/chapter11.ipynb | 704 +++- doc/LectureNotes/chapter12.ipynb | 1577 +++++++++ doc/LectureNotes/chapter13.ipynb | 1873 ++++++++++ doc/LectureNotes/chapteroptimization.ipynb | 1501 +++++++-- 10 files changed, 7133 insertions(+), 4030 deletions(-) delete mode 100644 doc/BookChapters/chapter11.ipynb create mode 100644 doc/BookChapters/chapter13.do.txt create mode 100644 doc/LectureNotes/chapter12.ipynb create mode 100644 doc/LectureNotes/chapter13.ipynb diff --git a/doc/BookChapters/chapter11.ipynb b/doc/BookChapters/chapter11.ipynb deleted file mode 100644 index 00bf35796..000000000 --- a/doc/BookChapters/chapter11.ipynb +++ /dev/null @@ -1,3375 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "7660a7d5", - "metadata": { - "editable": true - }, - "source": [ - "" - ] - }, - { - "cell_type": "markdown", - "id": "7174820b", - "metadata": { - "editable": true - }, - "source": [ - "# Solving Differential Equations with Deep Learning\n", - "\n", - "The Universal Approximation Theorem states that a neural network can\n", - "approximate any function at a single hidden layer along with one input\n", - "and output layer to any given precision. \n", - "\n", - "An ordinary differential equation (ODE) is an equation involving functions having one variable.\n", - "\n", - "In general, an ordinary differential equation looks like" - ] - }, - { - "cell_type": "markdown", - "id": "ac838a12", - "metadata": { - "editable": true - }, - "source": [ - "\n", - "
\n", - "\n", - "$$\n", - "\\begin{equation} \\label{ode} \\tag{1}\n", - "f\\left(x, \\, g(x), \\, g'(x), \\, g''(x), \\, \\dots \\, , \\, g^{(n)}(x)\\right) = 0\n", - "\\end{equation}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "ccee4286", - "metadata": { - "editable": true - }, - "source": [ - "where $g(x)$ is the function to find, and $g^{(n)}(x)$ is the $n$-th derivative of $g(x)$.\n", - "\n", - "The $f\\left(x, g(x), g'(x), g''(x), \\, \\dots \\, , g^{(n)}(x)\\right)$ is just a way to write that there is an expression involving $x$ and $g(x), \\ g'(x), \\ g''(x), \\, \\dots \\, , \\text{ and } g^{(n)}(x)$ on the left side of the equality sign in ([1](#ode)).\n", - "The highest order of derivative, that is the value of $n$, determines to the order of the equation.\n", - "The equation is referred to as a $n$-th order ODE.\n", - "Along with ([1](#ode)), some additional conditions of the function $g(x)$ are typically given\n", - "for the solution to be unique.\n", - "\n", - "Let the trial solution $g_t(x)$ be" - ] - }, - { - "cell_type": "markdown", - "id": "39d7dabd", - "metadata": { - "editable": true - }, - "source": [ - "\n", - "
\n", - "\n", - "$$\n", - "\\begin{equation}\n", - "\tg_t(x) = h_1(x) + h_2(x,N(x,P))\n", - "\\label{_auto1} \\tag{2}\n", - "\\end{equation}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "74f33170", - "metadata": { - "editable": true - }, - "source": [ - "where $h_1(x)$ is a function that makes $g_t(x)$ satisfy a given set\n", - "of conditions, $N(x,P)$ a neural network with weights and biases\n", - "described by $P$ and $h_2(x, N(x,P))$ some expression involving the\n", - "neural network. The role of the function $h_2(x, N(x,P))$, is to\n", - "ensure that the output from $N(x,P)$ is zero when $g_t(x)$ is\n", - "evaluated at the values of $x$ where the given conditions must be\n", - "satisfied. The function $h_1(x)$ should alone make $g_t(x)$ satisfy\n", - "the conditions.\n", - "\n", - "But what about the network $N(x,P)$?\n", - "\n", - "As described previously, an optimization method could be used to minimize the parameters of a neural network, that being its weights and biases, through backward propagation.\n", - "\n", - "For the minimization to be defined, we need to have a cost function at hand to minimize.\n", - "\n", - "It is given that $f\\left(x, \\, g(x), \\, g'(x), \\, g''(x), \\, \\dots \\, , \\, g^{(n)}(x)\\right)$ should be equal to zero in ([1](#ode)).\n", - "We can choose to consider the mean squared error as the cost function for an input $x$.\n", - "Since we are looking at one input, the cost function is just $f$ squared.\n", - "The cost function $c\\left(x, P \\right)$ can therefore be expressed as" - ] - }, - { - "cell_type": "markdown", - "id": "2565ab16", - "metadata": { - "editable": true - }, - "source": [ - "$$\n", - "C\\left(x, P\\right) = \\big(f\\left(x, \\, g(x), \\, g'(x), \\, g''(x), \\, \\dots \\, , \\, g^{(n)}(x)\\right)\\big)^2\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "83d4ee25", - "metadata": { - "editable": true - }, - "source": [ - "If $N$ inputs are given as a vector $\\boldsymbol{x}$ with elements $x_i$ for $i = 1,\\dots,N$,\n", - "the cost function becomes" - ] - }, - { - "cell_type": "markdown", - "id": "a7a3a709", - "metadata": { - "editable": true - }, - "source": [ - "\n", - "
\n", - "\n", - "$$\n", - "\\begin{equation} \\label{cost} \\tag{3}\n", - "\tC\\left(\\boldsymbol{x}, P\\right) = \\frac{1}{N} \\sum_{i=1}^N \\big(f\\left(x_i, \\, g(x_i), \\, g'(x_i), \\, g''(x_i), \\, \\dots \\, , \\, g^{(n)}(x_i)\\right)\\big)^2\n", - "\\end{equation}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "d3ca8026", - "metadata": { - "editable": true - }, - "source": [ - "The neural net should then find the parameters $P$ that minimizes the cost function in\n", - "([3](#cost)) for a set of $N$ training samples $x_i$.\n", - "\n", - "To perform the minimization using gradient descent, the gradient of $C\\left(\\boldsymbol{x}, P\\right)$ is needed.\n", - "It might happen so that finding an analytical expression of the gradient of $C(\\boldsymbol{x}, P)$ from ([3](#cost)) gets too messy, depending on which cost function one desires to use.\n", - "\n", - "Luckily, there exists libraries that makes the job for us through automatic differentiation.\n", - "Automatic differentiation is a method of finding the derivatives numerically with very high precision." - ] - }, - { - "cell_type": "markdown", - "id": "9bde4bd4", - "metadata": { - "editable": true - }, - "source": [ - "### Example: Exponential decay\n", - "\n", - "An exponential decay of a quantity $g(x)$ is described by the equation" - ] - }, - { - "cell_type": "markdown", - "id": "e74337c3", - "metadata": { - "editable": true - }, - "source": [ - "\n", - "
\n", - "\n", - "$$\n", - "\\begin{equation} \\label{solve_expdec} \\tag{4}\n", - " g'(x) = -\\gamma g(x)\n", - "\\end{equation}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "273549a4", - "metadata": { - "editable": true - }, - "source": [ - "with $g(0) = g_0$ for some chosen initial value $g_0$.\n", - "\n", - "The analytical solution of ([4](#solve_expdec)) is" - ] - }, - { - "cell_type": "markdown", - "id": "db3c6623", - "metadata": { - "editable": true - }, - "source": [ - "\n", - "
\n", - "\n", - "$$\n", - "\\begin{equation}\n", - " g(x) = g_0 \\exp\\left(-\\gamma x\\right)\n", - "\\label{_auto2} \\tag{5}\n", - "\\end{equation}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "8547e3c8", - "metadata": { - "editable": true - }, - "source": [ - "Having an analytical solution at hand, it is possible to use it to compare how well a neural network finds a solution of ([4](#solve_expdec)).\n", - "\n", - "The program will use a neural network to solve" - ] - }, - { - "cell_type": "markdown", - "id": "48341fc6", - "metadata": { - "editable": true - }, - "source": [ - "\n", - "
\n", - "\n", - "$$\n", - "\\begin{equation} \\label{solveode} \\tag{6}\n", - "g'(x) = -\\gamma g(x)\n", - "\\end{equation}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "d25b1e02", - "metadata": { - "editable": true - }, - "source": [ - "where $g(0) = g_0$ with $\\gamma$ and $g_0$ being some chosen values.\n", - "\n", - "In this example, $\\gamma = 2$ and $g_0 = 10$.\n", - "\n", - "To begin with, a trial solution $g_t(t)$ must be chosen. A general trial solution for ordinary differential equations could be" - ] - }, - { - "cell_type": "markdown", - "id": "7c5dd91e", - "metadata": { - "editable": true - }, - "source": [ - "$$\n", - "g_t(x, P) = h_1(x) + h_2(x, N(x, P))\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "24223062", - "metadata": { - "editable": true - }, - "source": [ - "with $h_1(x)$ ensuring that $g_t(x)$ satisfies some conditions and $h_2(x,N(x, P))$ an expression involving $x$ and the output from the neural network $N(x,P)$ with $P $ being the collection of the weights and biases for each layer. For now, it is assumed that the network consists of one input layer, one hidden layer, and one output layer.\n", - "\n", - "In this network, there are no weights and bias at the input layer, so $P = \\{ P_{\\text{hidden}}, P_{\\text{output}} \\}$.\n", - "If there are $N_{\\text{hidden} }$ neurons in the hidden layer, then $P_{\\text{hidden}}$ is a $N_{\\text{hidden} } \\times (1 + N_{\\text{input}})$ matrix, given that there are $N_{\\text{input}}$ neurons in the input layer.\n", - "\n", - "The first column in $P_{\\text{hidden} }$ represents the bias for each neuron in the hidden layer and the second column represents the weights for each neuron in the hidden layer from the input layer.\n", - "If there are $N_{\\text{output} }$ neurons in the output layer, then $P_{\\text{output}} $ is a $N_{\\text{output} } \\times (1 + N_{\\text{hidden} })$ matrix.\n", - "\n", - "Its first column represents the bias of each neuron and the remaining columns represents the weights to each neuron.\n", - "\n", - "It is given that $g(0) = g_0$. The trial solution must fulfill this condition to be a proper solution of ([6](#solveode)). A possible way to ensure that $g_t(0, P) = g_0$, is to let $F(N(x,P)) = x \\cdot N(x,P)$ and $A(x) = g_0$. This gives the following trial solution:" - ] - }, - { - "cell_type": "markdown", - "id": "ebf04383", - "metadata": { - "editable": true - }, - "source": [ - "\n", - "
\n", - "\n", - "$$\n", - "\\begin{equation} \\label{trial} \\tag{7}\n", - "g_t(x, P) = g_0 + x \\cdot N(x, P)\n", - "\\end{equation}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "ea4a0013", - "metadata": { - "editable": true - }, - "source": [ - "### Reformulating the problem\n", - "\n", - "We wish that our neural network manages to minimize a given cost function.\n", - "\n", - "A reformulation of out equation, ([6](#solveode)), must therefore be done,\n", - "such that it describes the problem a neural network can solve for.\n", - "\n", - "The neural network must find the set of weights and biases $P$ such that the trial solution in ([7](#trial)) satisfies ([6](#solveode)).\n", - "\n", - "The trial solution" - ] - }, - { - "cell_type": "markdown", - "id": "2351b84f", - "metadata": { - "editable": true - }, - "source": [ - "$$\n", - "g_t(x, P) = g_0 + x \\cdot N(x, P)\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "f6cc00e4", - "metadata": { - "editable": true - }, - "source": [ - "has been chosen such that it already solves the condition $g(0) = g_0$. What remains, is to find $P$ such that" - ] - }, - { - "cell_type": "markdown", - "id": "84e066a1", - "metadata": { - "editable": true - }, - "source": [ - "\n", - "
\n", - "\n", - "$$\n", - "\\begin{equation} \\label{nnmin} \\tag{8}\n", - "g_t'(x, P) = - \\gamma g_t(x, P)\n", - "\\end{equation}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "feff9ab3", - "metadata": { - "editable": true - }, - "source": [ - "is fulfilled as *best as possible*.\n", - "\n", - "The left hand side and right hand side of ([8](#nnmin)) must be computed separately, and then the neural network must choose weights and biases, contained in $P$, such that the sides are equal as best as possible.\n", - "This means that the absolute or squared difference between the sides must be as close to zero, ideally equal to zero.\n", - "In this case, the difference squared shows to be an appropriate measurement of how erroneous the trial solution is with respect to $P$ of the neural network.\n", - "\n", - "This gives the following cost function our neural network must solve for:" - ] - }, - { - "cell_type": "markdown", - "id": "0c6f0e79", - "metadata": { - "editable": true - }, - "source": [ - "$$\n", - "\\min_{P}\\Big\\{ \\big(g_t'(x, P) - ( -\\gamma g_t(x, P) \\big)^2 \\Big\\}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "9302a1dd", - "metadata": { - "editable": true - }, - "source": [ - "(the notation $\\min_{P}\\{ f(x, P) \\}$ means that we desire to find $P$ that yields the minimum of $f(x, P)$)\n", - "\n", - "or, in terms of weights and biases for the hidden and output layer in our network:" - ] - }, - { - "cell_type": "markdown", - "id": "f7f204bb", - "metadata": { - "editable": true - }, - "source": [ - "$$\n", - "\\min_{P_{\\text{hidden} }, \\ P_{\\text{output} }}\\Big\\{ \\big(g_t'(x, \\{ P_{\\text{hidden} }, P_{\\text{output} }\\}) - ( -\\gamma g_t(x, \\{ P_{\\text{hidden} }, P_{\\text{output} }\\}) \\big)^2 \\Big\\}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "8d61d75f", - "metadata": { - "editable": true - }, - "source": [ - "for an input value $x$.\n", - "\n", - "If the neural network evaluates $g_t(x, P)$ at more values for $x$, say $N$ values $x_i$ for $i = 1, \\dots, N$, then the *total* error to minimize becomes" - ] - }, - { - "cell_type": "markdown", - "id": "10d3aec9", - "metadata": { - "editable": true - }, - "source": [ - "\n", - "
\n", - "\n", - "$$\n", - "\\begin{equation} \\label{min} \\tag{9}\n", - "\\min_{P}\\Big\\{\\frac{1}{N} \\sum_{i=1}^N \\big(g_t'(x_i, P) - ( -\\gamma g_t(x_i, P) \\big)^2 \\Big\\}\n", - "\\end{equation}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "5e296388", - "metadata": { - "editable": true - }, - "source": [ - "Letting $\\boldsymbol{x}$ be a vector with elements $x_i$ and $C(\\boldsymbol{x}, P) = \\frac{1}{N} \\sum_i \\big(g_t'(x_i, P) - ( -\\gamma g_t(x_i, P) \\big)^2$ denote the cost function, the minimization problem that our network must solve, becomes" - ] - }, - { - "cell_type": "markdown", - "id": "fe010d79", - "metadata": { - "editable": true - }, - "source": [ - "$$\n", - "\\min_{P} C(\\boldsymbol{x}, P)\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "add715f9", - "metadata": { - "editable": true - }, - "source": [ - "In terms of $P_{\\text{hidden} }$ and $P_{\\text{output} }$, this could also be expressed as\n", - "\n", - "$$\n", - "\\min_{P_{\\text{hidden} }, \\ P_{\\text{output} }} C(\\boldsymbol{x}, \\{P_{\\text{hidden} }, P_{\\text{output} }\\})\n", - "$$\n", - "\n", - "For simplicity, it is assumed that the input is an array $\\boldsymbol{x} = (x_1, \\dots, x_N)$ with $N$ elements. It is at these points the neural network should find $P$ such that it fulfills ([9](#min)).\n", - "\n", - "First, the neural network must feed forward the inputs.\n", - "This means that $\\boldsymbol{x}s$ must be passed through an input layer, a hidden layer and a output layer. The input layer in this case, does not need to process the data any further.\n", - "The input layer will consist of $N_{\\text{input} }$ neurons, passing its element to each neuron in the hidden layer. The number of neurons in the hidden layer will be $N_{\\text{hidden} }$.\n", - "\n", - "For the $i$-th in the hidden layer with weight $w_i^{\\text{hidden} }$ and bias $b_i^{\\text{hidden} }$, the weighting from the $j$-th neuron at the input layer is:" - ] - }, - { - "cell_type": "markdown", - "id": "cb9b22eb", - "metadata": { - "editable": true - }, - "source": [ - "$$\n", - "\\begin{aligned}\n", - "z_{i,j}^{\\text{hidden}} &= b_i^{\\text{hidden}} + w_i^{\\text{hidden}}x_j \\\\\n", - "&=\n", - "\\begin{pmatrix}\n", - "b_i^{\\text{hidden}} & w_i^{\\text{hidden}}\n", - "\\end{pmatrix}\n", - "\\begin{pmatrix}\n", - "1 \\\\\n", - "x_j\n", - "\\end{pmatrix}\n", - "\\end{aligned}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "49f3c493", - "metadata": { - "editable": true - }, - "source": [ - "The result after weighting the inputs at the $i$-th hidden neuron can be written as a vector:" - ] - }, - { - "cell_type": "markdown", - "id": "a352bd61", - "metadata": { - "editable": true - }, - "source": [ - "$$\n", - "\\begin{aligned}\n", - "\\boldsymbol{z}_{i}^{\\text{hidden}} &= \\Big( b_i^{\\text{hidden}} + w_i^{\\text{hidden}}x_1 , \\ b_i^{\\text{hidden}} + w_i^{\\text{hidden}} x_2, \\ \\dots \\, , \\ b_i^{\\text{hidden}} + w_i^{\\text{hidden}} x_N\\Big) \\\\\n", - "&=\n", - "\\begin{pmatrix}\n", - " b_i^{\\text{hidden}} & w_i^{\\text{hidden}}\n", - "\\end{pmatrix}\n", - "\\begin{pmatrix}\n", - "1 & 1 & \\dots & 1 \\\\\n", - "x_1 & x_2 & \\dots & x_N\n", - "\\end{pmatrix} \\\\\n", - "&= \\boldsymbol{p}_{i, \\text{hidden}}^T X\n", - "\\end{aligned}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "e5636ad7", - "metadata": { - "editable": true - }, - "source": [ - "The vector $\\boldsymbol{p}_{i, \\text{hidden}}^T$ constitutes each row in $P_{\\text{hidden} }$, which contains the weights for the neural network to minimize according to ([9](#min)).\n", - "\n", - "After having found $\\boldsymbol{z}_{i}^{\\text{hidden}} $ for every $i$-th neuron within the hidden layer, the vector will be sent to an activation function $a_i(\\boldsymbol{z})$.\n", - "\n", - "In this example, the sigmoid function has been chosen to be the activation function for each hidden neuron:" - ] - }, - { - "cell_type": "markdown", - "id": "68bb8b9c", - "metadata": { - "editable": true - }, - "source": [ - "$$\n", - "f(z) = \\frac{1}{1 + \\exp{(-z)}}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "ff6e6536", - "metadata": { - "editable": true - }, - "source": [ - "It is possible to use other activations functions for the hidden layer also.\n", - "\n", - "The output $\\boldsymbol{x}_i^{\\text{hidden}}$ from each $i$-th hidden neuron is:\n", - "\n", - "$$\n", - "\\boldsymbol{x}_i^{\\text{hidden} } = f\\big( \\boldsymbol{z}_{i}^{\\text{hidden}} \\big)\n", - "$$\n", - "\n", - "The outputs $\\boldsymbol{x}_i^{\\text{hidden} } $ are then sent to the output layer.\n", - "\n", - "The output layer consists of one neuron in this case, and combines the\n", - "output from each of the neurons in the hidden layers. The output layer\n", - "combines the results from the hidden layer using some weights $w_i^{\\text{output}}$\n", - "and biases $b_i^{\\text{output}}$. In this case,\n", - "it is assumes that the number of neurons in the output layer is one.\n", - "\n", - "The procedure of weighting the output neuron $j$ in the hidden layer to the $i$-th neuron in the output layer is similar as for the hidden layer described previously." - ] - }, - { - "cell_type": "markdown", - "id": "6fb4c55b", - "metadata": { - "editable": true - }, - "source": [ - "$$\n", - "\\begin{aligned}\n", - "z_{1,j}^{\\text{output}} & =\n", - "\\begin{pmatrix}\n", - "b_1^{\\text{output}} & \\boldsymbol{w}_1^{\\text{output}}\n", - "\\end{pmatrix}\n", - "\\begin{pmatrix}\n", - "1 \\\\\n", - "\\boldsymbol{x}_j^{\\text{hidden}}\n", - "\\end{pmatrix}\n", - "\\end{aligned}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "09c31d8d", - "metadata": { - "editable": true - }, - "source": [ - "Expressing $z_{1,j}^{\\text{output}}$ as a vector gives the following way of weighting the inputs from the hidden layer:" - ] - }, - { - "cell_type": "markdown", - "id": "f81fe361", - "metadata": { - "editable": true - }, - "source": [ - "$$\n", - "\\boldsymbol{z}_{1}^{\\text{output}} =\n", - "\\begin{pmatrix}\n", - "b_1^{\\text{output}} & \\boldsymbol{w}_1^{\\text{output}}\n", - "\\end{pmatrix}\n", - "\\begin{pmatrix}\n", - "1 & 1 & \\dots & 1 \\\\\n", - "\\boldsymbol{x}_1^{\\text{hidden}} & \\boldsymbol{x}_2^{\\text{hidden}} & \\dots & \\boldsymbol{x}_N^{\\text{hidden}}\n", - "\\end{pmatrix}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "c309a4ce", - "metadata": { - "editable": true - }, - "source": [ - "In this case we seek a continuous range of values since we are approximating a function. This means that after computing $\\boldsymbol{z}_{1}^{\\text{output}}$ the neural network has finished its feed forward step, and $\\boldsymbol{z}_{1}^{\\text{output}}$ is the final output of the network.\n", - "\n", - "The next step is to decide how the parameters should be changed such that they minimize the cost function.\n", - "\n", - "The chosen cost function for this problem is" - ] - }, - { - "cell_type": "markdown", - "id": "ea47ae29", - "metadata": { - "editable": true - }, - "source": [ - "$$\n", - "C(\\boldsymbol{x}, P) = \\frac{1}{N} \\sum_i \\big(g_t'(x_i, P) - ( -\\gamma g_t(x_i, P) \\big)^2\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "9dd83767", - "metadata": { - "editable": true - }, - "source": [ - "In order to minimize the cost function, an optimization method must be chosen.\n", - "\n", - "Here, gradient descent with a constant step size has been chosen." - ] - }, - { - "cell_type": "markdown", - "id": "531a7b4f", - "metadata": { - "editable": true - }, - "source": [ - "### Gradient descent\n", - "\n", - "The idea of the gradient descent algorithm is to update parameters in\n", - "a direction where the cost function decreases goes to a minimum.\n", - "\n", - "In general, the update of some parameters $\\boldsymbol{\\omega}$ given a cost\n", - "function defined by some weights $\\boldsymbol{\\omega}$, $C(\\boldsymbol{x},\n", - "\\boldsymbol{\\omega})$, goes as follows:" - ] - }, - { - "cell_type": "markdown", - "id": "e10c204a", - "metadata": { - "editable": true - }, - "source": [ - "$$\n", - "\\boldsymbol{\\omega}_{\\text{new} } = \\boldsymbol{\\omega} - \\lambda \\nabla_{\\boldsymbol{\\omega}} C(\\boldsymbol{x}, \\boldsymbol{\\omega})\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "9f4fa48e", - "metadata": { - "editable": true - }, - "source": [ - "for a number of iterations or until $ \\big|\\big| \\boldsymbol{\\omega}_{\\text{new} } - \\boldsymbol{\\omega} \\big|\\big|$ becomes smaller than some given tolerance.\n", - "\n", - "The value of $\\lambda$ decides how large steps the algorithm must take\n", - "in the direction of $ \\nabla_{\\boldsymbol{\\omega}} C(\\boldsymbol{x}, \\boldsymbol{\\omega})$.\n", - "The notation $\\nabla_{\\boldsymbol{\\omega}}$ express the gradient with respect\n", - "to the elements in $\\boldsymbol{\\omega}$.\n", - "\n", - "In our case, we have to minimize the cost function $C(\\boldsymbol{x}, P)$ with\n", - "respect to the two sets of weights and biases, that is for the hidden\n", - "layer $P_{\\text{hidden} }$ and for the output layer $P_{\\text{output}\n", - "}$ .\n", - "\n", - "This means that $P_{\\text{hidden} }$ and $P_{\\text{output} }$ is updated by" - ] - }, - { - "cell_type": "markdown", - "id": "4652fc79", - "metadata": { - "editable": true - }, - "source": [ - "$$\n", - "\\begin{aligned}\n", - "P_{\\text{hidden},\\text{new}} &= P_{\\text{hidden}} - \\lambda \\nabla_{P_{\\text{hidden}}} C(\\boldsymbol{x}, P) \\\\\n", - "P_{\\text{output},\\text{new}} &= P_{\\text{output}} - \\lambda \\nabla_{P_{\\text{output}}} C(\\boldsymbol{x}, P)\n", - "\\end{aligned}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "41ae0626", - "metadata": { - "editable": true - }, - "source": [ - "### The code for solving the ODE" - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "id": "af7c165f", - "metadata": { - "collapsed": false, - "editable": true - }, - "outputs": [], - "source": [ - "%matplotlib inline\n", - "\n", - "import autograd.numpy as np\n", - "from autograd import grad, elementwise_grad\n", - "import autograd.numpy.random as npr\n", - "from matplotlib import pyplot as plt\n", - "\n", - "def sigmoid(z):\n", - " return 1/(1 + np.exp(-z))\n", - "\n", - "# Assuming one input, hidden, and output layer\n", - "def neural_network(params, x):\n", - "\n", - " # Find the weights (including and biases) for the hidden and output layer.\n", - " # Assume that params is a list of parameters for each layer.\n", - " # The biases are the first element for each array in params,\n", - " # and the weights are the remaning elements in each array in params.\n", - "\n", - " w_hidden = params[0]\n", - " w_output = params[1]\n", - "\n", - " # Assumes input x being an one-dimensional array\n", - " num_values = np.size(x)\n", - " x = x.reshape(-1, num_values)\n", - "\n", - " # Assume that the input layer does nothing to the input x\n", - " x_input = x\n", - "\n", - " ## Hidden layer:\n", - "\n", - " # Add a row of ones to include bias\n", - " x_input = np.concatenate((np.ones((1,num_values)), x_input ), axis = 0)\n", - "\n", - " z_hidden = np.matmul(w_hidden, x_input)\n", - " x_hidden = sigmoid(z_hidden)\n", - "\n", - " ## Output layer:\n", - "\n", - " # Include bias:\n", - " x_hidden = np.concatenate((np.ones((1,num_values)), x_hidden ), axis = 0)\n", - "\n", - " z_output = np.matmul(w_output, x_hidden)\n", - " x_output = z_output\n", - "\n", - " return x_output\n", - "\n", - "# The trial solution using the deep neural network:\n", - "def g_trial(x,params, g0 = 10):\n", - " return g0 + x*neural_network(params,x)\n", - "\n", - "# The right side of the ODE:\n", - "def g(x, g_trial, gamma = 2):\n", - " return -gamma*g_trial\n", - "\n", - "# The cost function:\n", - "def cost_function(P, x):\n", - "\n", - " # Evaluate the trial function with the current parameters P\n", - " g_t = g_trial(x,P)\n", - "\n", - " # Find the derivative w.r.t x of the neural network\n", - " d_net_out = elementwise_grad(neural_network,1)(P,x)\n", - "\n", - " # Find the derivative w.r.t x of the trial function\n", - " d_g_t = elementwise_grad(g_trial,0)(x,P)\n", - "\n", - " # The right side of the ODE\n", - " func = g(x, g_t)\n", - "\n", - " err_sqr = (d_g_t - func)**2\n", - " cost_sum = np.sum(err_sqr)\n", - "\n", - " return cost_sum / np.size(err_sqr)\n", - "\n", - "# Solve the exponential decay ODE using neural network with one input, hidden, and output layer\n", - "def solve_ode_neural_network(x, num_neurons_hidden, num_iter, lmb):\n", - " ## Set up initial weights and biases\n", - "\n", - " # For the hidden layer\n", - " p0 = npr.randn(num_neurons_hidden, 2 )\n", - "\n", - " # For the output layer\n", - " p1 = npr.randn(1, num_neurons_hidden + 1 ) # +1 since bias is included\n", - "\n", - " P = [p0, p1]\n", - "\n", - " print('Initial cost: %g'%cost_function(P, x))\n", - "\n", - " ## Start finding the optimal weights using gradient descent\n", - "\n", - " # Find the Python function that represents the gradient of the cost function\n", - " # w.r.t the 0-th input argument -- that is the weights and biases in the hidden and output layer\n", - " cost_function_grad = grad(cost_function,0)\n", - "\n", - " # Let the update be done num_iter times\n", - " for i in range(num_iter):\n", - " # Evaluate the gradient at the current weights and biases in P.\n", - " # The cost_grad consist now of two arrays;\n", - " # one for the gradient w.r.t P_hidden and\n", - " # one for the gradient w.r.t P_output\n", - " cost_grad = cost_function_grad(P, x)\n", - "\n", - " P[0] = P[0] - lmb * cost_grad[0]\n", - " P[1] = P[1] - lmb * cost_grad[1]\n", - "\n", - " print('Final cost: %g'%cost_function(P, x))\n", - "\n", - " return P\n", - "\n", - "def g_analytic(x, gamma = 2, g0 = 10):\n", - " return g0*np.exp(-gamma*x)\n", - "\n", - "# Solve the given problem\n", - "if __name__ == '__main__':\n", - " # Set seed such that the weight are initialized\n", - " # with same weights and biases for every run.\n", - " npr.seed(15)\n", - "\n", - " ## Decide the vales of arguments to the function to solve\n", - " N = 10\n", - " x = np.linspace(0, 1, N)\n", - "\n", - " ## Set up the initial parameters\n", - " num_hidden_neurons = 10\n", - " num_iter = 10000\n", - " lmb = 0.001\n", - "\n", - " # Use the network\n", - " P = solve_ode_neural_network(x, num_hidden_neurons, num_iter, lmb)\n", - "\n", - " # Print the deviation from the trial solution and true solution\n", - " res = g_trial(x,P)\n", - " res_analytical = g_analytic(x)\n", - "\n", - " print('Max absolute difference: %g'%np.max(np.abs(res - res_analytical)))\n", - "\n", - " # Plot the results\n", - " plt.figure(figsize=(10,10))\n", - "\n", - " plt.title('Performance of neural network solving an ODE compared to the analytical solution')\n", - " plt.plot(x, res_analytical)\n", - " plt.plot(x, res[0,:])\n", - " plt.legend(['analytical','nn'])\n", - " plt.xlabel('x')\n", - " plt.ylabel('g(x)')\n", - " plt.show()" - ] - }, - { - "cell_type": "markdown", - "id": "875a0c0b", - "metadata": { - "editable": true - }, - "source": [ - "## The network with one input layer, specified number of hidden layers, and one output layer\n", - "\n", - "It is also possible to extend the construction of our network into a more general one, allowing the network to contain more than one hidden layers.\n", - "\n", - "The number of neurons within each hidden layer are given as a list of integers in the program below." - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "id": "00684827", - "metadata": { - "collapsed": false, - "editable": true - }, - "outputs": [], - "source": [ - "import autograd.numpy as np\n", - "from autograd import grad, elementwise_grad\n", - "import autograd.numpy.random as npr\n", - "from matplotlib import pyplot as plt\n", - "\n", - "def sigmoid(z):\n", - " return 1/(1 + np.exp(-z))\n", - "\n", - "# The neural network with one input layer and one output layer,\n", - "# but with number of hidden layers specified by the user.\n", - "def deep_neural_network(deep_params, x):\n", - " # N_hidden is the number of hidden layers\n", - "\n", - " N_hidden = np.size(deep_params) - 1 # -1 since params consists of\n", - " # parameters to all the hidden\n", - " # layers AND the output layer.\n", - "\n", - " # Assumes input x being an one-dimensional array\n", - " num_values = np.size(x)\n", - " x = x.reshape(-1, num_values)\n", - "\n", - " # Assume that the input layer does nothing to the input x\n", - " x_input = x\n", - "\n", - " # Due to multiple hidden layers, define a variable referencing to the\n", - " # output of the previous layer:\n", - " x_prev = x_input\n", - "\n", - " ## Hidden layers:\n", - "\n", - " for l in range(N_hidden):\n", - " # From the list of parameters P; find the correct weigths and bias for this layer\n", - " w_hidden = deep_params[l]\n", - "\n", - " # Add a row of ones to include bias\n", - " x_prev = np.concatenate((np.ones((1,num_values)), x_prev ), axis = 0)\n", - "\n", - " z_hidden = np.matmul(w_hidden, x_prev)\n", - " x_hidden = sigmoid(z_hidden)\n", - "\n", - " # Update x_prev such that next layer can use the output from this layer\n", - " x_prev = x_hidden\n", - "\n", - " ## Output layer:\n", - "\n", - " # Get the weights and bias for this layer\n", - " w_output = deep_params[-1]\n", - "\n", - " # Include bias:\n", - " x_prev = np.concatenate((np.ones((1,num_values)), x_prev), axis = 0)\n", - "\n", - " z_output = np.matmul(w_output, x_prev)\n", - " x_output = z_output\n", - "\n", - " return x_output\n", - "\n", - "# The trial solution using the deep neural network:\n", - "def g_trial_deep(x,params, g0 = 10):\n", - " return g0 + x*deep_neural_network(params, x)\n", - "\n", - "# The right side of the ODE:\n", - "def g(x, g_trial, gamma = 2):\n", - " return -gamma*g_trial\n", - "\n", - "# The same cost function as before, but calls deep_neural_network instead.\n", - "def cost_function_deep(P, x):\n", - "\n", - " # Evaluate the trial function with the current parameters P\n", - " g_t = g_trial_deep(x,P)\n", - "\n", - " # Find the derivative w.r.t x of the neural network\n", - " d_net_out = elementwise_grad(deep_neural_network,1)(P,x)\n", - "\n", - " # Find the derivative w.r.t x of the trial function\n", - " d_g_t = elementwise_grad(g_trial_deep,0)(x,P)\n", - "\n", - " # The right side of the ODE\n", - " func = g(x, g_t)\n", - "\n", - " err_sqr = (d_g_t - func)**2\n", - " cost_sum = np.sum(err_sqr)\n", - "\n", - " return cost_sum / np.size(err_sqr)\n", - "\n", - "# Solve the exponential decay ODE using neural network with one input and one output layer,\n", - "# but with specified number of hidden layers from the user.\n", - "def solve_ode_deep_neural_network(x, num_neurons, num_iter, lmb):\n", - " # num_hidden_neurons is now a list of number of neurons within each hidden layer\n", - "\n", - " # The number of elements in the list num_hidden_neurons thus represents\n", - " # the number of hidden layers.\n", - "\n", - " # Find the number of hidden layers:\n", - " N_hidden = np.size(num_neurons)\n", - "\n", - " ## Set up initial weights and biases\n", - "\n", - " # Initialize the list of parameters:\n", - " P = [None]*(N_hidden + 1) # + 1 to include the output layer\n", - "\n", - " P[0] = npr.randn(num_neurons[0], 2 )\n", - " for l in range(1,N_hidden):\n", - " P[l] = npr.randn(num_neurons[l], num_neurons[l-1] + 1) # +1 to include bias\n", - "\n", - " # For the output layer\n", - " P[-1] = npr.randn(1, num_neurons[-1] + 1 ) # +1 since bias is included\n", - "\n", - " print('Initial cost: %g'%cost_function_deep(P, x))\n", - "\n", - " ## Start finding the optimal weights using gradient descent\n", - "\n", - " # Find the Python function that represents the gradient of the cost function\n", - " # w.r.t the 0-th input argument -- that is the weights and biases in the hidden and output layer\n", - " cost_function_deep_grad = grad(cost_function_deep,0)\n", - "\n", - " # Let the update be done num_iter times\n", - " for i in range(num_iter):\n", - " # Evaluate the gradient at the current weights and biases in P.\n", - " # The cost_grad consist now of N_hidden + 1 arrays; the gradient w.r.t the weights and biases\n", - " # in the hidden layers and output layers evaluated at x.\n", - " cost_deep_grad = cost_function_deep_grad(P, x)\n", - "\n", - " for l in range(N_hidden+1):\n", - " P[l] = P[l] - lmb * cost_deep_grad[l]\n", - "\n", - " print('Final cost: %g'%cost_function_deep(P, x))\n", - "\n", - " return P\n", - "\n", - "def g_analytic(x, gamma = 2, g0 = 10):\n", - " return g0*np.exp(-gamma*x)\n", - "\n", - "# Solve the given problem\n", - "if __name__ == '__main__':\n", - " npr.seed(15)\n", - "\n", - " ## Decide the vales of arguments to the function to solve\n", - " N = 10\n", - " x = np.linspace(0, 1, N)\n", - "\n", - " ## Set up the initial parameters\n", - " num_hidden_neurons = np.array([10,10])\n", - " num_iter = 10000\n", - " lmb = 0.001\n", - "\n", - " P = solve_ode_deep_neural_network(x, num_hidden_neurons, num_iter, lmb)\n", - "\n", - " res = g_trial_deep(x,P)\n", - " res_analytical = g_analytic(x)\n", - "\n", - " plt.figure(figsize=(10,10))\n", - "\n", - " plt.title('Performance of a deep neural network solving an ODE compared to the analytical solution')\n", - " plt.plot(x, res_analytical)\n", - " plt.plot(x, res[0,:])\n", - " plt.legend(['analytical','dnn'])\n", - " plt.ylabel('g(x)')\n", - " plt.show()" - ] - }, - { - "cell_type": "markdown", - "id": "5420c490", - "metadata": { - "editable": true - }, - "source": [ - "### Example: Population growth\n", - "\n", - "A logistic model of population growth assumes that a population converges toward an equilibrium.\n", - "The population growth can be modeled by" - ] - }, - { - "cell_type": "markdown", - "id": "1436ed3c", - "metadata": { - "editable": true - }, - "source": [ - "\n", - "
\n", - "\n", - "$$\n", - "\\begin{equation} \\label{log} \\tag{10}\n", - "\tg'(t) = \\alpha g(t)(A - g(t))\n", - "\\end{equation}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "a590bdb6", - "metadata": { - "editable": true - }, - "source": [ - "where $g(t)$ is the population density at time $t$, $\\alpha > 0$ the growth rate and $A > 0$ is the maximum population number in the environment.\n", - "Also, at $t = 0$ the population has the size $g(0) = g_0$, where $g_0$ is some chosen constant.\n", - "\n", - "In this example, similar network as for the exponential decay using Autograd has been used to solve the equation. However, as the implementation might suffer from e.g numerical instability\n", - "and high execution time (this might be more apparent in the examples solving PDEs),\n", - "using a library like TensorFlow is recommended.\n", - "Here, we stay with a more simple approach and implement for comparison, the simple forward Euler method.\n", - "\n", - "Here, we will model a population $g(t)$ in an environment having carrying capacity $A$.\n", - "The population follows the model" - ] - }, - { - "cell_type": "markdown", - "id": "48d788d6", - "metadata": { - "editable": true - }, - "source": [ - "\n", - "
\n", - "\n", - "$$\n", - "\\begin{equation} \\label{solveode_population} \\tag{11}\n", - "g'(t) = \\alpha g(t)(A - g(t))\n", - "\\end{equation}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "169c6c25", - "metadata": { - "editable": true - }, - "source": [ - "where $g(0) = g_0$.\n", - "\n", - "In this example, we let $\\alpha = 2$, $A = 1$, and $g_0 = 1.2$.\n", - "\n", - "We will get a slightly different trial solution, as the boundary conditions are different\n", - "compared to the case for exponential decay.\n", - "\n", - "A possible trial solution satisfying the condition $g(0) = g_0$ could be\n", - "\n", - "$$\n", - "h_1(t) = g_0 + t \\cdot N(t,P)\n", - "$$\n", - "\n", - "with $N(t,P)$ being the output from the neural network with weights and biases for each layer collected in the set $P$.\n", - "\n", - "The analytical solution is\n", - "\n", - "$$\n", - "g(t) = \\frac{Ag_0}{g_0 + (A - g_0)\\exp(-\\alpha A t)}\n", - "$$\n", - "\n", - "The network will be the similar as for the exponential decay example, but with some small modifications for our problem." - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "id": "6d2e33bf", - "metadata": { - "collapsed": false, - "editable": true - }, - "outputs": [], - "source": [ - "import autograd.numpy as np\n", - "from autograd import grad, elementwise_grad\n", - "import autograd.numpy.random as npr\n", - "from matplotlib import pyplot as plt\n", - "\n", - "def sigmoid(z):\n", - " return 1/(1 + np.exp(-z))\n", - "\n", - "# Function to get the parameters.\n", - "# Done such that one can easily change the paramaters after one's liking.\n", - "def get_parameters():\n", - " alpha = 2\n", - " A = 1\n", - " g0 = 1.2\n", - " return alpha, A, g0\n", - "\n", - "def deep_neural_network(P, x):\n", - " # N_hidden is the number of hidden layers\n", - " N_hidden = np.size(P) - 1 # -1 since params consist of parameters to all the hidden layers AND the output layer\n", - "\n", - " # Assumes input x being an one-dimensional array\n", - " num_values = np.size(x)\n", - " x = x.reshape(-1, num_values)\n", - "\n", - " # Assume that the input layer does nothing to the input x\n", - " x_input = x\n", - "\n", - " # Due to multiple hidden layers, define a variable referencing to the\n", - " # output of the previous layer:\n", - " x_prev = x_input\n", - "\n", - " ## Hidden layers:\n", - "\n", - " for l in range(N_hidden):\n", - " # From the list of parameters P; find the correct weigths and bias for this layer\n", - " w_hidden = P[l]\n", - "\n", - " # Add a row of ones to include bias\n", - " x_prev = np.concatenate((np.ones((1,num_values)), x_prev ), axis = 0)\n", - "\n", - " z_hidden = np.matmul(w_hidden, x_prev)\n", - " x_hidden = sigmoid(z_hidden)\n", - "\n", - " # Update x_prev such that next layer can use the output from this layer\n", - " x_prev = x_hidden\n", - "\n", - " ## Output layer:\n", - "\n", - " # Get the weights and bias for this layer\n", - " w_output = P[-1]\n", - "\n", - " # Include bias:\n", - " x_prev = np.concatenate((np.ones((1,num_values)), x_prev), axis = 0)\n", - "\n", - " z_output = np.matmul(w_output, x_prev)\n", - " x_output = z_output\n", - "\n", - " return x_output\n", - "\n", - "\n", - "def cost_function_deep(P, x):\n", - "\n", - " # Evaluate the trial function with the current parameters P\n", - " g_t = g_trial_deep(x,P)\n", - "\n", - " # Find the derivative w.r.t x of the trial function\n", - " d_g_t = elementwise_grad(g_trial_deep,0)(x,P)\n", - "\n", - " # The right side of the ODE\n", - " func = f(x, g_t)\n", - "\n", - " err_sqr = (d_g_t - func)**2\n", - " cost_sum = np.sum(err_sqr)\n", - "\n", - " return cost_sum / np.size(err_sqr)\n", - "\n", - "# The right side of the ODE:\n", - "def f(x, g_trial):\n", - " alpha,A, g0 = get_parameters()\n", - " return alpha*g_trial*(A - g_trial)\n", - "\n", - "# The trial solution using the deep neural network:\n", - "def g_trial_deep(x, params):\n", - " alpha,A, g0 = get_parameters()\n", - " return g0 + x*deep_neural_network(params,x)\n", - "\n", - "# The analytical solution:\n", - "def g_analytic(t):\n", - " alpha,A, g0 = get_parameters()\n", - " return A*g0/(g0 + (A - g0)*np.exp(-alpha*A*t))\n", - "\n", - "def solve_ode_deep_neural_network(x, num_neurons, num_iter, lmb):\n", - " # num_hidden_neurons is now a list of number of neurons within each hidden layer\n", - "\n", - " # Find the number of hidden layers:\n", - " N_hidden = np.size(num_neurons)\n", - "\n", - " ## Set up initial weigths and biases\n", - "\n", - " # Initialize the list of parameters:\n", - " P = [None]*(N_hidden + 1) # + 1 to include the output layer\n", - "\n", - " P[0] = npr.randn(num_neurons[0], 2 )\n", - " for l in range(1,N_hidden):\n", - " P[l] = npr.randn(num_neurons[l], num_neurons[l-1] + 1) # +1 to include bias\n", - "\n", - " # For the output layer\n", - " P[-1] = npr.randn(1, num_neurons[-1] + 1 ) # +1 since bias is included\n", - "\n", - " print('Initial cost: %g'%cost_function_deep(P, x))\n", - "\n", - " ## Start finding the optimal weigths using gradient descent\n", - "\n", - " # Find the Python function that represents the gradient of the cost function\n", - " # w.r.t the 0-th input argument -- that is the weights and biases in the hidden and output layer\n", - " cost_function_deep_grad = grad(cost_function_deep,0)\n", - "\n", - " # Let the update be done num_iter times\n", - " for i in range(num_iter):\n", - " # Evaluate the gradient at the current weights and biases in P.\n", - " # The cost_grad consist now of N_hidden + 1 arrays; the gradient w.r.t the weights and biases\n", - " # in the hidden layers and output layers evaluated at x.\n", - " cost_deep_grad = cost_function_deep_grad(P, x)\n", - "\n", - " for l in range(N_hidden+1):\n", - " P[l] = P[l] - lmb * cost_deep_grad[l]\n", - "\n", - " print('Final cost: %g'%cost_function_deep(P, x))\n", - "\n", - " return P\n", - "\n", - "if __name__ == '__main__':\n", - " npr.seed(4155)\n", - "\n", - " ## Decide the vales of arguments to the function to solve\n", - " Nt = 10\n", - " T = 1\n", - " t = np.linspace(0,T, Nt)\n", - "\n", - " ## Set up the initial parameters\n", - " num_hidden_neurons = [100, 50, 25]\n", - " num_iter = 1000\n", - " lmb = 1e-3\n", - "\n", - " P = solve_ode_deep_neural_network(t, num_hidden_neurons, num_iter, lmb)\n", - "\n", - " g_dnn_ag = g_trial_deep(t,P)\n", - " g_analytical = g_analytic(t)\n", - "\n", - " # Find the maximum absolute difference between the solutons:\n", - " diff_ag = np.max(np.abs(g_dnn_ag - g_analytical))\n", - " print(\"The max absolute difference between the solutions is: %g\"%diff_ag)\n", - "\n", - " plt.figure(figsize=(10,10))\n", - "\n", - " plt.title('Performance of neural network solving an ODE compared to the analytical solution')\n", - " plt.plot(t, g_analytical)\n", - " plt.plot(t, g_dnn_ag[0,:])\n", - " plt.legend(['analytical','nn'])\n", - " plt.xlabel('t')\n", - " plt.ylabel('g(t)')\n", - "\n", - " plt.show()" - ] - }, - { - "cell_type": "markdown", - "id": "e31ec549", - "metadata": { - "editable": true - }, - "source": [ - "## Using forward Euler to solve the ODE\n", - "\n", - "A straightforward way of solving an ODE numerically, is to use Euler's method.\n", - "\n", - "Euler's method uses Taylor series to approximate the value at a function $f$ at a step $\\Delta x$ from $x$:\n", - "\n", - "$$\n", - "f(x + \\Delta x) \\approx f(x) + \\Delta x f'(x)\n", - "$$\n", - "\n", - "In our case, using Euler's method to approximate the value of $g$ at a step $\\Delta t$ from $t$ yields" - ] - }, - { - "cell_type": "markdown", - "id": "2e9ee105", - "metadata": { - "editable": true - }, - "source": [ - "$$\n", - "\\begin{aligned}\n", - " g(t + \\Delta t) &\\approx g(t) + \\Delta t g'(t) \\\\\n", - " &= g(t) + \\Delta t \\big(\\alpha g(t)(A - g(t))\\big)\n", - "\\end{aligned}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "e876da16", - "metadata": { - "editable": true - }, - "source": [ - "along with the condition that $g(0) = g_0$.\n", - "\n", - "Let $t_i = i \\cdot \\Delta t$ where $\\Delta t = \\frac{T}{N_t-1}$ where $T$ is the final time our solver must solve for and $N_t$ the number of values for $t \\in [0, T]$ for $i = 0, \\dots, N_t-1$.\n", - "\n", - "For $i \\geq 1$, we have that" - ] - }, - { - "cell_type": "markdown", - "id": "b79a3def", - "metadata": { - "editable": true - }, - "source": [ - "$$\n", - "\\begin{aligned}\n", - "t_i &= i\\Delta t \\\\\n", - "&= (i - 1)\\Delta t + \\Delta t \\\\\n", - "&= t_{i-1} + \\Delta t\n", - "\\end{aligned}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "9d99cb4e", - "metadata": { - "editable": true - }, - "source": [ - "Now, if $g_i = g(t_i)$ then" - ] - }, - { - "cell_type": "markdown", - "id": "3b9dcc24", - "metadata": { - "editable": true - }, - "source": [ - "\n", - "
\n", - "\n", - "$$\n", - "\\begin{equation}\n", - " \\begin{aligned}\n", - " g_i &= g(t_i) \\\\\n", - " &= g(t_{i-1} + \\Delta t) \\\\\n", - " &\\approx g(t_{i-1}) + \\Delta t \\big(\\alpha g(t_{i-1})(A - g(t_{i-1}))\\big) \\\\\n", - " &= g_{i-1} + \\Delta t \\big(\\alpha g_{i-1}(A - g_{i-1})\\big)\n", - " \\end{aligned}\n", - "\\end{equation} \\label{odenum} \\tag{12}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "65ce688e", - "metadata": { - "editable": true - }, - "source": [ - "for $i \\geq 1$ and $g_0 = g(t_0) = g(0) = g_0$.\n", - "\n", - "Equation ([12](#odenum)) could be implemented in the following way,\n", - "extending the program that uses the network using Autograd:" - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "id": "d5497948", - "metadata": { - "collapsed": false, - "editable": true - }, - "outputs": [], - "source": [ - "# Assume that all function definitions from the example program using Autograd\n", - "# are located here.\n", - "\n", - "if __name__ == '__main__':\n", - " npr.seed(4155)\n", - "\n", - " ## Decide the vales of arguments to the function to solve\n", - " Nt = 10\n", - " T = 1\n", - " t = np.linspace(0,T, Nt)\n", - "\n", - " ## Set up the initial parameters\n", - " num_hidden_neurons = [100,50,25]\n", - " num_iter = 1000\n", - " lmb = 1e-3\n", - "\n", - " P = solve_ode_deep_neural_network(t, num_hidden_neurons, num_iter, lmb)\n", - "\n", - " g_dnn_ag = g_trial_deep(t,P)\n", - " g_analytical = g_analytic(t)\n", - "\n", - " # Find the maximum absolute difference between the solutons:\n", - " diff_ag = np.max(np.abs(g_dnn_ag - g_analytical))\n", - " print(\"The max absolute difference between the solutions is: %g\"%diff_ag)\n", - "\n", - " plt.figure(figsize=(10,10))\n", - "\n", - " plt.title('Performance of neural network solving an ODE compared to the analytical solution')\n", - " plt.plot(t, g_analytical)\n", - " plt.plot(t, g_dnn_ag[0,:])\n", - " plt.legend(['analytical','nn'])\n", - " plt.xlabel('t')\n", - " plt.ylabel('g(t)')\n", - "\n", - " ## Find an approximation to the funtion using forward Euler\n", - "\n", - " alpha, A, g0 = get_parameters()\n", - " dt = T/(Nt - 1)\n", - "\n", - " # Perform forward Euler to solve the ODE\n", - " g_euler = np.zeros(Nt)\n", - " g_euler[0] = g0\n", - "\n", - " for i in range(1,Nt):\n", - " g_euler[i] = g_euler[i-1] + dt*(alpha*g_euler[i-1]*(A - g_euler[i-1]))\n", - "\n", - " # Print the errors done by each method\n", - " diff1 = np.max(np.abs(g_euler - g_analytical))\n", - " diff2 = np.max(np.abs(g_dnn_ag[0,:] - g_analytical))\n", - "\n", - " print('Max absolute difference between Euler method and analytical: %g'%diff1)\n", - " print('Max absolute difference between deep neural network and analytical: %g'%diff2)\n", - "\n", - " # Plot results\n", - " plt.figure(figsize=(10,10))\n", - "\n", - " plt.plot(t,g_euler)\n", - " plt.plot(t,g_analytical)\n", - " plt.plot(t,g_dnn_ag[0,:])\n", - "\n", - " plt.legend(['euler','analytical','dnn'])\n", - " plt.xlabel('Time t')\n", - " plt.ylabel('g(t)')\n", - "\n", - " plt.show()" - ] - }, - { - "cell_type": "markdown", - "id": "fa8f0bb4", - "metadata": { - "editable": true - }, - "source": [ - "## Solving the one dimensional Poisson equation\n", - "\n", - "The Poisson equation for $g(x)$ in one dimension is" - ] - }, - { - "cell_type": "markdown", - "id": "f765b0ba", - "metadata": { - "editable": true - }, - "source": [ - "\n", - "
\n", - "\n", - "$$\n", - "\\begin{equation} \\label{poisson} \\tag{13}\n", - " -g''(x) = f(x)\n", - "\\end{equation}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "bd63b92e", - "metadata": { - "editable": true - }, - "source": [ - "where $f(x)$ is a given function for $x \\in (0,1)$.\n", - "\n", - "The conditions that $g(x)$ is chosen to fulfill, are" - ] - }, - { - "cell_type": "markdown", - "id": "c0a7face", - "metadata": { - "editable": true - }, - "source": [ - "$$\n", - "\\begin{align*}\n", - " g(0) &= 0 \\\\\n", - " g(1) &= 0\n", - "\\end{align*}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "f71c3cb9", - "metadata": { - "editable": true - }, - "source": [ - "This equation can be solved numerically using programs where e.g Autograd and TensorFlow are used.\n", - "The results from the networks can then be compared to the analytical solution.\n", - "In addition, it could be interesting to see how a typical method for numerically solving second order ODEs compares to the neural networks.\n", - "\n", - "Here, the function $g(x)$ to solve for follows the equation" - ] - }, - { - "cell_type": "markdown", - "id": "35aa6a37", - "metadata": { - "editable": true - }, - "source": [ - "$$\n", - "-g''(x) = f(x),\\qquad x \\in (0,1)\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "f8b35111", - "metadata": { - "editable": true - }, - "source": [ - "where $f(x)$ is a given function, along with the chosen conditions" - ] - }, - { - "cell_type": "markdown", - "id": "33813514", - "metadata": { - "editable": true - }, - "source": [ - "\n", - "
\n", - "\n", - "$$\n", - "\\begin{aligned}\n", - "g(0) = g(1) = 0\n", - "\\end{aligned}\\label{cond} \\tag{14}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "c70aadd4", - "metadata": { - "editable": true - }, - "source": [ - "In this example, we consider the case when $f(x) = (3x + x^2)\\exp(x)$.\n", - "\n", - "For this case, a possible trial solution satisfying the conditions could be" - ] - }, - { - "cell_type": "markdown", - "id": "d5719dee", - "metadata": { - "editable": true - }, - "source": [ - "$$\n", - "g_t(x) = x \\cdot (1-x) \\cdot N(P,x)\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "a683041b", - "metadata": { - "editable": true - }, - "source": [ - "The analytical solution for this problem is" - ] - }, - { - "cell_type": "markdown", - "id": "672cdaff", - "metadata": { - "editable": true - }, - "source": [ - "$$\n", - "g(x) = x(1 - x)\\exp(x)\n", - "$$" - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "id": "66e6bebb", - "metadata": { - "collapsed": false, - "editable": true - }, - "outputs": [], - "source": [ - "import autograd.numpy as np\n", - "from autograd import grad, elementwise_grad\n", - "import autograd.numpy.random as npr\n", - "from matplotlib import pyplot as plt\n", - "\n", - "def sigmoid(z):\n", - " return 1/(1 + np.exp(-z))\n", - "\n", - "def deep_neural_network(deep_params, x):\n", - " # N_hidden is the number of hidden layers\n", - " N_hidden = np.size(deep_params) - 1 # -1 since params consist of parameters to all the hidden layers AND the output layer\n", - "\n", - " # Assumes input x being an one-dimensional array\n", - " num_values = np.size(x)\n", - " x = x.reshape(-1, num_values)\n", - "\n", - " # Assume that the input layer does nothing to the input x\n", - " x_input = x\n", - "\n", - " # Due to multiple hidden layers, define a variable referencing to the\n", - " # output of the previous layer:\n", - " x_prev = x_input\n", - "\n", - " ## Hidden layers:\n", - "\n", - " for l in range(N_hidden):\n", - " # From the list of parameters P; find the correct weigths and bias for this layer\n", - " w_hidden = deep_params[l]\n", - "\n", - " # Add a row of ones to include bias\n", - " x_prev = np.concatenate((np.ones((1,num_values)), x_prev ), axis = 0)\n", - "\n", - " z_hidden = np.matmul(w_hidden, x_prev)\n", - " x_hidden = sigmoid(z_hidden)\n", - "\n", - " # Update x_prev such that next layer can use the output from this layer\n", - " x_prev = x_hidden\n", - "\n", - " ## Output layer:\n", - "\n", - " # Get the weights and bias for this layer\n", - " w_output = deep_params[-1]\n", - "\n", - " # Include bias:\n", - " x_prev = np.concatenate((np.ones((1,num_values)), x_prev), axis = 0)\n", - "\n", - " z_output = np.matmul(w_output, x_prev)\n", - " x_output = z_output\n", - "\n", - " return x_output\n", - "\n", - "def solve_ode_deep_neural_network(x, num_neurons, num_iter, lmb):\n", - " # num_hidden_neurons is now a list of number of neurons within each hidden layer\n", - "\n", - " # Find the number of hidden layers:\n", - " N_hidden = np.size(num_neurons)\n", - "\n", - " ## Set up initial weigths and biases\n", - "\n", - " # Initialize the list of parameters:\n", - " P = [None]*(N_hidden + 1) # + 1 to include the output layer\n", - "\n", - " P[0] = npr.randn(num_neurons[0], 2 )\n", - " for l in range(1,N_hidden):\n", - " P[l] = npr.randn(num_neurons[l], num_neurons[l-1] + 1) # +1 to include bias\n", - "\n", - " # For the output layer\n", - " P[-1] = npr.randn(1, num_neurons[-1] + 1 ) # +1 since bias is included\n", - "\n", - " print('Initial cost: %g'%cost_function_deep(P, x))\n", - "\n", - " ## Start finding the optimal weigths using gradient descent\n", - "\n", - " # Find the Python function that represents the gradient of the cost function\n", - " # w.r.t the 0-th input argument -- that is the weights and biases in the hidden and output layer\n", - " cost_function_deep_grad = grad(cost_function_deep,0)\n", - "\n", - " # Let the update be done num_iter times\n", - " for i in range(num_iter):\n", - " # Evaluate the gradient at the current weights and biases in P.\n", - " # The cost_grad consist now of N_hidden + 1 arrays; the gradient w.r.t the weights and biases\n", - " # in the hidden layers and output layers evaluated at x.\n", - " cost_deep_grad = cost_function_deep_grad(P, x)\n", - "\n", - " for l in range(N_hidden+1):\n", - " P[l] = P[l] - lmb * cost_deep_grad[l]\n", - "\n", - " print('Final cost: %g'%cost_function_deep(P, x))\n", - "\n", - " return P\n", - "\n", - "## Set up the cost function specified for this Poisson equation:\n", - "\n", - "# The right side of the ODE\n", - "def f(x):\n", - " return (3*x + x**2)*np.exp(x)\n", - "\n", - "def cost_function_deep(P, x):\n", - "\n", - " # Evaluate the trial function with the current parameters P\n", - " g_t = g_trial_deep(x,P)\n", - "\n", - " # Find the derivative w.r.t x of the trial function\n", - " d2_g_t = elementwise_grad(elementwise_grad(g_trial_deep,0))(x,P)\n", - "\n", - " right_side = f(x)\n", - "\n", - " err_sqr = (-d2_g_t - right_side)**2\n", - " cost_sum = np.sum(err_sqr)\n", - "\n", - " return cost_sum/np.size(err_sqr)\n", - "\n", - "# The trial solution:\n", - "def g_trial_deep(x,P):\n", - " return x*(1-x)*deep_neural_network(P,x)\n", - "\n", - "# The analytic solution;\n", - "def g_analytic(x):\n", - " return x*(1-x)*np.exp(x)\n", - "\n", - "if __name__ == '__main__':\n", - " npr.seed(4155)\n", - "\n", - " ## Decide the vales of arguments to the function to solve\n", - " Nx = 10\n", - " x = np.linspace(0,1, Nx)\n", - "\n", - " ## Set up the initial parameters\n", - " num_hidden_neurons = [200,100]\n", - " num_iter = 1000\n", - " lmb = 1e-3\n", - "\n", - " P = solve_ode_deep_neural_network(x, num_hidden_neurons, num_iter, lmb)\n", - "\n", - " g_dnn_ag = g_trial_deep(x,P)\n", - " g_analytical = g_analytic(x)\n", - "\n", - " # Find the maximum absolute difference between the solutons:\n", - " max_diff = np.max(np.abs(g_dnn_ag - g_analytical))\n", - " print(\"The max absolute difference between the solutions is: %g\"%max_diff)\n", - "\n", - " plt.figure(figsize=(10,10))\n", - "\n", - " plt.title('Performance of neural network solving an ODE compared to the analytical solution')\n", - " plt.plot(x, g_analytical)\n", - " plt.plot(x, g_dnn_ag[0,:])\n", - " plt.legend(['analytical','nn'])\n", - " plt.xlabel('x')\n", - " plt.ylabel('g(x)')\n", - " plt.show()" - ] - }, - { - "cell_type": "markdown", - "id": "d425cba5", - "metadata": { - "editable": true - }, - "source": [ - "### Comparing with a numerical scheme\n", - "\n", - "The Poisson equation is possible to solve using Taylor series to approximate the second derivative.\n", - "\n", - "Using Taylor series, the second derivative can be expressed as\n", - "\n", - "$$\n", - "g''(x) = \\frac{g(x + \\Delta x) - 2g(x) + g(x-\\Delta x)}{\\Delta x^2} + E_{\\Delta x}(x)\n", - "$$\n", - "\n", - "where $\\Delta x$ is a small step size and $E_{\\Delta x}(x)$ being the error term.\n", - "\n", - "Looking away from the error terms gives an approximation to the second derivative:" - ] - }, - { - "cell_type": "markdown", - "id": "a2efa110", - "metadata": { - "editable": true - }, - "source": [ - "\n", - "
\n", - "\n", - "$$\n", - "\\begin{equation} \\label{approx} \\tag{15}\n", - "g''(x) \\approx \\frac{g(x + \\Delta x) - 2g(x) + g(x-\\Delta x)}{\\Delta x^2}\n", - "\\end{equation}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "5011ee25", - "metadata": { - "editable": true - }, - "source": [ - "If $x_i = i \\Delta x = x_{i-1} + \\Delta x$ and $g_i = g(x_i)$ for $i = 1,\\dots N_x - 2$ with $N_x$ being the number of values for $x$, ([15](#approx)) becomes" - ] - }, - { - "cell_type": "markdown", - "id": "705ee300", - "metadata": { - "editable": true - }, - "source": [ - "$$\n", - "\\begin{aligned}\n", - "g''(x_i) &\\approx \\frac{g(x_i + \\Delta x) - 2g(x_i) + g(x_i -\\Delta x)}{\\Delta x^2} \\\\\n", - "&= \\frac{g_{i+1} - 2g_i + g_{i-1}}{\\Delta x^2}\n", - "\\end{aligned}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "b390796d", - "metadata": { - "editable": true - }, - "source": [ - "Since we know from our problem that" - ] - }, - { - "cell_type": "markdown", - "id": "19c9ece4", - "metadata": { - "editable": true - }, - "source": [ - "$$\n", - "\\begin{aligned}\n", - "-g''(x) &= f(x) \\\\\n", - "&= (3x + x^2)\\exp(x)\n", - "\\end{aligned}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "6ade1a7a", - "metadata": { - "editable": true - }, - "source": [ - "along with the conditions $g(0) = g(1) = 0$,\n", - "the following scheme can be used to find an approximate solution for $g(x)$ numerically:" - ] - }, - { - "cell_type": "markdown", - "id": "78b16d02", - "metadata": { - "editable": true - }, - "source": [ - "\n", - "
\n", - "\n", - "$$\n", - "\\begin{equation}\n", - " \\begin{aligned}\n", - " -\\Big( \\frac{g_{i+1} - 2g_i + g_{i-1}}{\\Delta x^2} \\Big) &= f(x_i) \\\\\n", - " -g_{i+1} + 2g_i - g_{i-1} &= \\Delta x^2 f(x_i)\n", - " \\end{aligned}\n", - "\\end{equation} \\label{odesys} \\tag{16}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "f2bfcca4", - "metadata": { - "editable": true - }, - "source": [ - "for $i = 1, \\dots, N_x - 2$ where $g_0 = g_{N_x - 1} = 0$ and $f(x_i) = (3x_i + x_i^2)\\exp(x_i)$, which is given for our specific problem.\n", - "\n", - "The equation can be rewritten into a matrix equation:" - ] - }, - { - "cell_type": "markdown", - "id": "a6191528", - "metadata": { - "editable": true - }, - "source": [ - "$$\n", - "\\begin{aligned}\n", - "\\begin{pmatrix}\n", - "2 & -1 & 0 & \\dots & 0 \\\\\n", - "-1 & 2 & -1 & \\dots & 0 \\\\\n", - "\\vdots & & \\ddots & & \\vdots \\\\\n", - "0 & \\dots & -1 & 2 & -1 \\\\\n", - "0 & \\dots & 0 & -1 & 2\\\\\n", - "\\end{pmatrix}\n", - "\\begin{pmatrix}\n", - "g_1 \\\\\n", - "g_2 \\\\\n", - "\\vdots \\\\\n", - "g_{N_x - 3} \\\\\n", - "g_{N_x - 2}\n", - "\\end{pmatrix}\n", - "&=\n", - "\\Delta x^2\n", - "\\begin{pmatrix}\n", - "f(x_1) \\\\\n", - "f(x_2) \\\\\n", - "\\vdots \\\\\n", - "f(x_{N_x - 3}) \\\\\n", - "f(x_{N_x - 2})\n", - "\\end{pmatrix} \\\\\n", - "\\boldsymbol{A}\\boldsymbol{g} &= \\boldsymbol{f},\n", - "\\end{aligned}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "aefef707", - "metadata": { - "editable": true - }, - "source": [ - "which makes it possible to solve for the vector $\\boldsymbol{g}$.\n", - "\n", - "We can then compare the result from this numerical scheme with the output from our network using Autograd:" - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "id": "471664cd", - "metadata": { - "collapsed": false, - "editable": true - }, - "outputs": [], - "source": [ - "import autograd.numpy as np\n", - "from autograd import grad, elementwise_grad\n", - "import autograd.numpy.random as npr\n", - "from matplotlib import pyplot as plt\n", - "\n", - "def sigmoid(z):\n", - " return 1/(1 + np.exp(-z))\n", - "\n", - "def deep_neural_network(deep_params, x):\n", - " # N_hidden is the number of hidden layers\n", - " N_hidden = np.size(deep_params) - 1 # -1 since params consist of parameters to all the hidden layers AND the output layer\n", - "\n", - " # Assumes input x being an one-dimensional array\n", - " num_values = np.size(x)\n", - " x = x.reshape(-1, num_values)\n", - "\n", - " # Assume that the input layer does nothing to the input x\n", - " x_input = x\n", - "\n", - " # Due to multiple hidden layers, define a variable referencing to the\n", - " # output of the previous layer:\n", - " x_prev = x_input\n", - "\n", - " ## Hidden layers:\n", - "\n", - " for l in range(N_hidden):\n", - " # From the list of parameters P; find the correct weigths and bias for this layer\n", - " w_hidden = deep_params[l]\n", - "\n", - " # Add a row of ones to include bias\n", - " x_prev = np.concatenate((np.ones((1,num_values)), x_prev ), axis = 0)\n", - "\n", - " z_hidden = np.matmul(w_hidden, x_prev)\n", - " x_hidden = sigmoid(z_hidden)\n", - "\n", - " # Update x_prev such that next layer can use the output from this layer\n", - " x_prev = x_hidden\n", - "\n", - " ## Output layer:\n", - "\n", - " # Get the weights and bias for this layer\n", - " w_output = deep_params[-1]\n", - "\n", - " # Include bias:\n", - " x_prev = np.concatenate((np.ones((1,num_values)), x_prev), axis = 0)\n", - "\n", - " z_output = np.matmul(w_output, x_prev)\n", - " x_output = z_output\n", - "\n", - " return x_output\n", - "\n", - "def solve_ode_deep_neural_network(x, num_neurons, num_iter, lmb):\n", - " # num_hidden_neurons is now a list of number of neurons within each hidden layer\n", - "\n", - " # Find the number of hidden layers:\n", - " N_hidden = np.size(num_neurons)\n", - "\n", - " ## Set up initial weigths and biases\n", - "\n", - " # Initialize the list of parameters:\n", - " P = [None]*(N_hidden + 1) # + 1 to include the output layer\n", - "\n", - " P[0] = npr.randn(num_neurons[0], 2 )\n", - " for l in range(1,N_hidden):\n", - " P[l] = npr.randn(num_neurons[l], num_neurons[l-1] + 1) # +1 to include bias\n", - "\n", - " # For the output layer\n", - " P[-1] = npr.randn(1, num_neurons[-1] + 1 ) # +1 since bias is included\n", - "\n", - " print('Initial cost: %g'%cost_function_deep(P, x))\n", - "\n", - " ## Start finding the optimal weigths using gradient descent\n", - "\n", - " # Find the Python function that represents the gradient of the cost function\n", - " # w.r.t the 0-th input argument -- that is the weights and biases in the hidden and output layer\n", - " cost_function_deep_grad = grad(cost_function_deep,0)\n", - "\n", - " # Let the update be done num_iter times\n", - " for i in range(num_iter):\n", - " # Evaluate the gradient at the current weights and biases in P.\n", - " # The cost_grad consist now of N_hidden + 1 arrays; the gradient w.r.t the weights and biases\n", - " # in the hidden layers and output layers evaluated at x.\n", - " cost_deep_grad = cost_function_deep_grad(P, x)\n", - "\n", - " for l in range(N_hidden+1):\n", - " P[l] = P[l] - lmb * cost_deep_grad[l]\n", - "\n", - " print('Final cost: %g'%cost_function_deep(P, x))\n", - "\n", - " return P\n", - "\n", - "## Set up the cost function specified for this Poisson equation:\n", - "\n", - "# The right side of the ODE\n", - "def f(x):\n", - " return (3*x + x**2)*np.exp(x)\n", - "\n", - "def cost_function_deep(P, x):\n", - "\n", - " # Evaluate the trial function with the current parameters P\n", - " g_t = g_trial_deep(x,P)\n", - "\n", - " # Find the derivative w.r.t x of the trial function\n", - " d2_g_t = elementwise_grad(elementwise_grad(g_trial_deep,0))(x,P)\n", - "\n", - " right_side = f(x)\n", - "\n", - " err_sqr = (-d2_g_t - right_side)**2\n", - " cost_sum = np.sum(err_sqr)\n", - "\n", - " return cost_sum/np.size(err_sqr)\n", - "\n", - "# The trial solution:\n", - "def g_trial_deep(x,P):\n", - " return x*(1-x)*deep_neural_network(P,x)\n", - "\n", - "# The analytic solution;\n", - "def g_analytic(x):\n", - " return x*(1-x)*np.exp(x)\n", - "\n", - "if __name__ == '__main__':\n", - " npr.seed(4155)\n", - "\n", - " ## Decide the vales of arguments to the function to solve\n", - " Nx = 10\n", - " x = np.linspace(0,1, Nx)\n", - "\n", - " ## Set up the initial parameters\n", - " num_hidden_neurons = [200,100]\n", - " num_iter = 1000\n", - " lmb = 1e-3\n", - "\n", - " P = solve_ode_deep_neural_network(x, num_hidden_neurons, num_iter, lmb)\n", - "\n", - " g_dnn_ag = g_trial_deep(x,P)\n", - " g_analytical = g_analytic(x)\n", - "\n", - " # Find the maximum absolute difference between the solutons:\n", - "\n", - " plt.figure(figsize=(10,10))\n", - "\n", - " plt.title('Performance of neural network solving an ODE compared to the analytical solution')\n", - " plt.plot(x, g_analytical)\n", - " plt.plot(x, g_dnn_ag[0,:])\n", - " plt.legend(['analytical','nn'])\n", - " plt.xlabel('x')\n", - " plt.ylabel('g(x)')\n", - "\n", - " ## Perform the computation using the numerical scheme\n", - "\n", - " dx = 1/(Nx - 1)\n", - "\n", - " # Set up the matrix A\n", - " A = np.zeros((Nx-2,Nx-2))\n", - "\n", - " A[0,0] = 2\n", - " A[0,1] = -1\n", - "\n", - " for i in range(1,Nx-3):\n", - " A[i,i-1] = -1\n", - " A[i,i] = 2\n", - " A[i,i+1] = -1\n", - "\n", - " A[Nx - 3, Nx - 4] = -1\n", - " A[Nx - 3, Nx - 3] = 2\n", - "\n", - " # Set up the vector f\n", - " f_vec = dx**2 * f(x[1:-1])\n", - "\n", - " # Solve the equation\n", - " g_res = np.linalg.solve(A,f_vec)\n", - "\n", - " g_vec = np.zeros(Nx)\n", - " g_vec[1:-1] = g_res\n", - "\n", - " # Print the differences between each method\n", - " max_diff1 = np.max(np.abs(g_dnn_ag - g_analytical))\n", - " max_diff2 = np.max(np.abs(g_vec - g_analytical))\n", - " print(\"The max absolute difference between the analytical solution and DNN Autograd: %g\"%max_diff1)\n", - " print(\"The max absolute difference between the analytical solution and numerical scheme: %g\"%max_diff2)\n", - "\n", - " # Plot the results\n", - " plt.figure(figsize=(10,10))\n", - "\n", - " plt.plot(x,g_vec)\n", - " plt.plot(x,g_analytical)\n", - " plt.plot(x,g_dnn_ag[0,:])\n", - "\n", - " plt.legend(['numerical scheme','analytical','dnn'])\n", - " plt.show()" - ] - }, - { - "cell_type": "markdown", - "id": "6f02e86d", - "metadata": { - "editable": true - }, - "source": [ - "## Partial Differential Equations\n", - "\n", - "A partial differential equation (PDE) has a solution here the function\n", - "is defined by multiple variables. The equation may involve all kinds\n", - "of combinations of which variables the function is differentiated with\n", - "respect to.\n", - "\n", - "In general, a partial differential equation for a function $g(x_1,\\dots,x_N)$ with $N$ variables may be expressed as" - ] - }, - { - "cell_type": "markdown", - "id": "ad5c63e8", - "metadata": { - "editable": true - }, - "source": [ - "\n", - "
\n", - "\n", - "$$\n", - "\\begin{equation} \\label{PDE} \\tag{17}\n", - " f\\left(x_1, \\, \\dots \\, , x_N, \\frac{\\partial g(x_1,\\dots,x_N) }{\\partial x_1}, \\dots , \\frac{\\partial g(x_1,\\dots,x_N) }{\\partial x_N}, \\frac{\\partial g(x_1,\\dots,x_N) }{\\partial x_1\\partial x_2}, \\, \\dots \\, , \\frac{\\partial^n g(x_1,\\dots,x_N) }{\\partial x_N^n} \\right) = 0\n", - "\\end{equation}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "c7b98797", - "metadata": { - "editable": true - }, - "source": [ - "where $f$ is an expression involving all kinds of possible mixed derivatives of $g(x_1,\\dots,x_N)$ up to an order $n$. In order for the solution to be unique, some additional conditions must also be given." - ] - }, - { - "cell_type": "markdown", - "id": "52f9394e", - "metadata": { - "editable": true - }, - "source": [ - "### Type of problem\n", - "\n", - "The problem our network must solve for, is similar to the ODE case.\n", - "We must have a trial solution $g_t$ at hand.\n", - "\n", - "For instance, the trial solution could be expressed as" - ] - }, - { - "cell_type": "markdown", - "id": "4d489854", - "metadata": { - "editable": true - }, - "source": [ - "$$\n", - "\\begin{align*}\n", - " g_t(x_1,\\dots,x_N) = h_1(x_1,\\dots,x_N) + h_2(x_1,\\dots,x_N,N(x_1,\\dots,x_N,P))\n", - "\\end{align*}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "82311538", - "metadata": { - "editable": true - }, - "source": [ - "where $h_1(x_1,\\dots,x_N)$ is a function that ensures $g_t(x_1,\\dots,x_N)$ satisfies some given conditions.\n", - "The neural network $N(x_1,\\dots,x_N,P)$ has weights and biases described by $P$ and $h_2(x_1,\\dots,x_N,N(x_1,\\dots,x_N,P))$ is an expression using the output from the neural network in some way.\n", - "\n", - "The role of the function $h_2(x_1,\\dots,x_N,N(x_1,\\dots,x_N,P))$, is to ensure that the output of $N(x_1,\\dots,x_N,P)$ is zero when $g_t(x_1,\\dots,x_N)$ is evaluated at the values of $x_1,\\dots,x_N$ where the given conditions must be satisfied. The function $h_1(x_1,\\dots,x_N)$ should alone make $g_t(x_1,\\dots,x_N)$ satisfy the conditions." - ] - }, - { - "cell_type": "markdown", - "id": "9d134db4", - "metadata": { - "editable": true - }, - "source": [ - "### Network requirements\n", - "\n", - "The network tries then the minimize the cost function following the\n", - "same ideas as described for the ODE case, but now with more than one\n", - "variables to consider. The concept still remains the same; find a set\n", - "of parameters $P$ such that the expression $f$ in ([17](#PDE)) is as\n", - "close to zero as possible.\n", - "\n", - "As for the ODE case, the cost function is the mean squared error that\n", - "the network must try to minimize. The cost function for the network to\n", - "minimize is" - ] - }, - { - "cell_type": "markdown", - "id": "5a463498", - "metadata": { - "editable": true - }, - "source": [ - "$$\n", - "C\\left(x_1, \\dots, x_N, P\\right) = \\left( f\\left(x_1, \\, \\dots \\, , x_N, \\frac{\\partial g(x_1,\\dots,x_N) }{\\partial x_1}, \\dots , \\frac{\\partial g(x_1,\\dots,x_N) }{\\partial x_N}, \\frac{\\partial g(x_1,\\dots,x_N) }{\\partial x_1\\partial x_2}, \\, \\dots \\, , \\frac{\\partial^n g(x_1,\\dots,x_N) }{\\partial x_N^n} \\right) \\right)^2\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "c40d8997", - "metadata": { - "editable": true - }, - "source": [ - "If we let $\\boldsymbol{x} = \\big( x_1, \\dots, x_N \\big)$ be an array containing the values for $x_1, \\dots, x_N$ respectively, the cost function can be reformulated into the following:" - ] - }, - { - "cell_type": "markdown", - "id": "cc033de6", - "metadata": { - "editable": true - }, - "source": [ - "$$\n", - "C\\left(\\boldsymbol{x}, P\\right) = f\\left( \\left( \\boldsymbol{x}, \\frac{\\partial g(\\boldsymbol{x}) }{\\partial x_1}, \\dots , \\frac{\\partial g(\\boldsymbol{x}) }{\\partial x_N}, \\frac{\\partial g(\\boldsymbol{x}) }{\\partial x_1\\partial x_2}, \\, \\dots \\, , \\frac{\\partial^n g(\\boldsymbol{x}) }{\\partial x_N^n} \\right) \\right)^2\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "ae18b4f4", - "metadata": { - "editable": true - }, - "source": [ - "If we also have $M$ different sets of values for $x_1, \\dots, x_N$, that is $\\boldsymbol{x}_i = \\big(x_1^{(i)}, \\dots, x_N^{(i)}\\big)$ for $i = 1,\\dots,M$ being the rows in matrix $X$, the cost function can be generalized into" - ] - }, - { - "cell_type": "markdown", - "id": "44ca21bd", - "metadata": { - "editable": true - }, - "source": [ - "$$\n", - "C\\left(X, P \\right) = \\sum_{i=1}^M f\\left( \\left( \\boldsymbol{x}_i, \\frac{\\partial g(\\boldsymbol{x}_i) }{\\partial x_1}, \\dots , \\frac{\\partial g(\\boldsymbol{x}_i) }{\\partial x_N}, \\frac{\\partial g(\\boldsymbol{x}_i) }{\\partial x_1\\partial x_2}, \\, \\dots \\, , \\frac{\\partial^n g(\\boldsymbol{x}_i) }{\\partial x_N^n} \\right) \\right)^2.\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "fe94451e", - "metadata": { - "editable": true - }, - "source": [ - "## Example: The diffusion equation\n", - "\n", - "In one spatial dimension, the equation reads" - ] - }, - { - "cell_type": "markdown", - "id": "30a42273", - "metadata": { - "editable": true - }, - "source": [ - "$$\n", - "\\frac{\\partial g(x,t)}{\\partial t} = \\frac{\\partial^2 g(x,t)}{\\partial x^2}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "fd4077e7", - "metadata": { - "editable": true - }, - "source": [ - "where a possible choice of conditions are" - ] - }, - { - "cell_type": "markdown", - "id": "dbbf2e4b", - "metadata": { - "editable": true - }, - "source": [ - "$$\n", - "\\begin{align*}\n", - "g(0,t) &= 0 ,\\qquad t \\geq 0 \\\\\n", - "g(1,t) &= 0, \\qquad t \\geq 0 \\\\\n", - "g(x,0) &= u(x),\\qquad x\\in [0,1]\n", - "\\end{align*}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "83653db9", - "metadata": { - "editable": true - }, - "source": [ - "with $u(x)$ being some given function.\n", - "\n", - "For this case, we want to find $g(x,t)$ such that" - ] - }, - { - "cell_type": "markdown", - "id": "d2c2ef4f", - "metadata": { - "editable": true - }, - "source": [ - "\n", - "
\n", - "\n", - "$$\n", - "\\begin{equation}\n", - " \\frac{\\partial g(x,t)}{\\partial t} = \\frac{\\partial^2 g(x,t)}{\\partial x^2}\n", - "\\end{equation} \\label{diffonedim} \\tag{18}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "8fb27bdb", - "metadata": { - "editable": true - }, - "source": [ - "and" - ] - }, - { - "cell_type": "markdown", - "id": "dc9297ab", - "metadata": { - "editable": true - }, - "source": [ - "$$\n", - "\\begin{align*}\n", - "g(0,t) &= 0 ,\\qquad t \\geq 0 \\\\\n", - "g(1,t) &= 0, \\qquad t \\geq 0 \\\\\n", - "g(x,0) &= u(x),\\qquad x\\in [0,1]\n", - "\\end{align*}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "ab90784f", - "metadata": { - "editable": true - }, - "source": [ - "with $u(x) = \\sin(\\pi x)$.\n", - "\n", - "First, let us set up the deep neural network.\n", - "The deep neural network will follow the same structure as discussed in the examples solving the ODEs.\n", - "First, we will look into how Autograd could be used in a network tailored to solve for bivariate functions.\n", - "\n", - "The only change to do here, is to extend our network such that\n", - "functions of multiple parameters are correctly handled. In this case\n", - "we have two variables in our function to solve for, that is time $t$\n", - "and position $x$. The variables will be represented by a\n", - "one-dimensional array in the program. The program will evaluate the\n", - "network at each possible pair $(x,t)$, given an array for the desired\n", - "$x$-values and $t$-values to approximate the solution at." - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "id": "b07e858c", - "metadata": { - "collapsed": false, - "editable": true - }, - "outputs": [], - "source": [ - "def sigmoid(z):\n", - " return 1/(1 + np.exp(-z))\n", - "\n", - "def deep_neural_network(deep_params, x):\n", - " # x is now a point and a 1D numpy array; make it a column vector\n", - " num_coordinates = np.size(x,0)\n", - " x = x.reshape(num_coordinates,-1)\n", - "\n", - " num_points = np.size(x,1)\n", - "\n", - " # N_hidden is the number of hidden layers\n", - " N_hidden = np.size(deep_params) - 1 # -1 since params consist of parameters to all the hidden layers AND the output layer\n", - "\n", - " # Assume that the input layer does nothing to the input x\n", - " x_input = x\n", - " x_prev = x_input\n", - "\n", - " ## Hidden layers:\n", - "\n", - " for l in range(N_hidden):\n", - " # From the list of parameters P; find the correct weigths and bias for this layer\n", - " w_hidden = deep_params[l]\n", - "\n", - " # Add a row of ones to include bias\n", - " x_prev = np.concatenate((np.ones((1,num_points)), x_prev ), axis = 0)\n", - "\n", - " z_hidden = np.matmul(w_hidden, x_prev)\n", - " x_hidden = sigmoid(z_hidden)\n", - "\n", - " # Update x_prev such that next layer can use the output from this layer\n", - " x_prev = x_hidden\n", - "\n", - " ## Output layer:\n", - "\n", - " # Get the weights and bias for this layer\n", - " w_output = deep_params[-1]\n", - "\n", - " # Include bias:\n", - " x_prev = np.concatenate((np.ones((1,num_points)), x_prev), axis = 0)\n", - "\n", - " z_output = np.matmul(w_output, x_prev)\n", - " x_output = z_output\n", - "\n", - " return x_output[0][0]" - ] - }, - { - "cell_type": "markdown", - "id": "9a167ec1", - "metadata": { - "editable": true - }, - "source": [ - "The cost function must then iterate through the given arrays\n", - "containing values for $x$ and $t$, defines a point $(x,t)$ the deep\n", - "neural network and the trial solution is evaluated at, and then finds\n", - "the Jacobian of the trial solution.\n", - "\n", - "A possible trial solution for this PDE is\n", - "\n", - "$$\n", - "g_t(x,t) = h_1(x,t) + x(1-x)tN(x,t,P)\n", - "$$\n", - "\n", - "with $A(x,t)$ being a function ensuring that $g_t(x,t)$ satisfies our given conditions, and $N(x,t,P)$ being the output from the deep neural network using weights and biases for each layer from $P$.\n", - "\n", - "To fulfill the conditions, $A(x,t)$ could be:\n", - "\n", - "$$\n", - "h_1(x,t) = (1-t)\\Big(u(x) - \\big((1-x)u(0) + x u(1)\\big)\\Big) = (1-t)u(x) = (1-t)\\sin(\\pi x)\n", - "$$\n", - "since $(0) = u(1) = 0$ and $u(x) = \\sin(\\pi x)$.\n", - "\n", - "The Jacobian is used because the program must find the derivative of\n", - "the trial solution with respect to $x$ and $t$.\n", - "\n", - "This gives the necessity of computing the Jacobian matrix, as we want\n", - "to evaluate the gradient with respect to $x$ and $t$ (note that the\n", - "Jacobian of a scalar-valued multivariate function is simply its\n", - "gradient).\n", - "\n", - "In Autograd, the differentiation is by default done with respect to\n", - "the first input argument of your Python function. Since the points is\n", - "an array representing $x$ and $t$, the Jacobian is calculated using\n", - "the values of $x$ and $t$.\n", - "\n", - "To find the second derivative with respect to $x$ and $t$, the\n", - "Jacobian can be found for the second time. The result is a Hessian\n", - "matrix, which is the matrix containing all the possible second order\n", - "mixed derivatives of $g(x,t)$." - ] - }, - { - "cell_type": "code", - "execution_count": 8, - "id": "921e5969", - "metadata": { - "collapsed": false, - "editable": true - }, - "outputs": [], - "source": [ - "# Set up the trial function:\n", - "def u(x):\n", - " return np.sin(np.pi*x)\n", - "\n", - "def g_trial(point,P):\n", - " x,t = point\n", - " return (1-t)*u(x) + x*(1-x)*t*deep_neural_network(P,point)\n", - "\n", - "# The right side of the ODE:\n", - "def f(point):\n", - " return 0.\n", - "\n", - "# The cost function:\n", - "def cost_function(P, x, t):\n", - " cost_sum = 0\n", - "\n", - " g_t_jacobian_func = jacobian(g_trial)\n", - " g_t_hessian_func = hessian(g_trial)\n", - "\n", - " for x_ in x:\n", - " for t_ in t:\n", - " point = np.array([x_,t_])\n", - "\n", - " g_t = g_trial(point,P)\n", - " g_t_jacobian = g_t_jacobian_func(point,P)\n", - " g_t_hessian = g_t_hessian_func(point,P)\n", - "\n", - " g_t_dt = g_t_jacobian[1]\n", - " g_t_d2x = g_t_hessian[0][0]\n", - "\n", - " func = f(point)\n", - "\n", - " err_sqr = ( (g_t_dt - g_t_d2x) - func)**2\n", - " cost_sum += err_sqr\n", - "\n", - " return cost_sum" - ] - }, - { - "cell_type": "markdown", - "id": "0bc00b69", - "metadata": { - "editable": true - }, - "source": [ - "### Setting up the network using Autograd; The full program\n", - "\n", - "Having set up the network, along with the trial solution and cost function, we can now see how the deep neural network performs by comparing the results to the analytical solution.\n", - "\n", - "The analytical solution of our problem is\n", - "\n", - "$$\n", - "g(x,t) = \\exp(-\\pi^2 t)\\sin(\\pi x)\n", - "$$\n", - "\n", - "A possible way to implement a neural network solving the PDE, is given below.\n", - "Be aware, though, that it is fairly slow for the parameters used.\n", - "A better result is possible, but requires more iterations, and thus longer time to complete.\n", - "\n", - "Indeed, the program below is not optimal in its implementation, but rather serves as an example on how to implement and use a neural network to solve a PDE.\n", - "Using TensorFlow results in a much better execution time. Try it!" - ] - }, - { - "cell_type": "code", - "execution_count": 9, - "id": "20734418", - "metadata": { - "collapsed": false, - "editable": true - }, - "outputs": [], - "source": [ - "import autograd.numpy as np\n", - "from autograd import jacobian,hessian,grad\n", - "import autograd.numpy.random as npr\n", - "from matplotlib import cm\n", - "from matplotlib import pyplot as plt\n", - "from mpl_toolkits.mplot3d import axes3d\n", - "\n", - "## Set up the network\n", - "\n", - "def sigmoid(z):\n", - " return 1/(1 + np.exp(-z))\n", - "\n", - "def deep_neural_network(deep_params, x):\n", - " # x is now a point and a 1D numpy array; make it a column vector\n", - " num_coordinates = np.size(x,0)\n", - " x = x.reshape(num_coordinates,-1)\n", - "\n", - " num_points = np.size(x,1)\n", - "\n", - " # N_hidden is the number of hidden layers\n", - " N_hidden = np.size(deep_params) - 1 # -1 since params consist of parameters to all the hidden layers AND the output layer\n", - "\n", - " # Assume that the input layer does nothing to the input x\n", - " x_input = x\n", - " x_prev = x_input\n", - "\n", - " ## Hidden layers:\n", - "\n", - " for l in range(N_hidden):\n", - " # From the list of parameters P; find the correct weigths and bias for this layer\n", - " w_hidden = deep_params[l]\n", - "\n", - " # Add a row of ones to include bias\n", - " x_prev = np.concatenate((np.ones((1,num_points)), x_prev ), axis = 0)\n", - "\n", - " z_hidden = np.matmul(w_hidden, x_prev)\n", - " x_hidden = sigmoid(z_hidden)\n", - "\n", - " # Update x_prev such that next layer can use the output from this layer\n", - " x_prev = x_hidden\n", - "\n", - " ## Output layer:\n", - "\n", - " # Get the weights and bias for this layer\n", - " w_output = deep_params[-1]\n", - "\n", - " # Include bias:\n", - " x_prev = np.concatenate((np.ones((1,num_points)), x_prev), axis = 0)\n", - "\n", - " z_output = np.matmul(w_output, x_prev)\n", - " x_output = z_output\n", - "\n", - " return x_output[0][0]\n", - "\n", - "## Define the trial solution and cost function\n", - "def u(x):\n", - " return np.sin(np.pi*x)\n", - "\n", - "def g_trial(point,P):\n", - " x,t = point\n", - " return (1-t)*u(x) + x*(1-x)*t*deep_neural_network(P,point)\n", - "\n", - "# The right side of the ODE:\n", - "def f(point):\n", - " return 0.\n", - "\n", - "# The cost function:\n", - "def cost_function(P, x, t):\n", - " cost_sum = 0\n", - "\n", - " g_t_jacobian_func = jacobian(g_trial)\n", - " g_t_hessian_func = hessian(g_trial)\n", - "\n", - " for x_ in x:\n", - " for t_ in t:\n", - " point = np.array([x_,t_])\n", - "\n", - " g_t = g_trial(point,P)\n", - " g_t_jacobian = g_t_jacobian_func(point,P)\n", - " g_t_hessian = g_t_hessian_func(point,P)\n", - "\n", - " g_t_dt = g_t_jacobian[1]\n", - " g_t_d2x = g_t_hessian[0][0]\n", - "\n", - " func = f(point)\n", - "\n", - " err_sqr = ( (g_t_dt - g_t_d2x) - func)**2\n", - " cost_sum += err_sqr\n", - "\n", - " return cost_sum /( np.size(x)*np.size(t) )\n", - "\n", - "## For comparison, define the analytical solution\n", - "def g_analytic(point):\n", - " x,t = point\n", - " return np.exp(-np.pi**2*t)*np.sin(np.pi*x)\n", - "\n", - "## Set up a function for training the network to solve for the equation\n", - "def solve_pde_deep_neural_network(x,t, num_neurons, num_iter, lmb):\n", - " ## Set up initial weigths and biases\n", - " N_hidden = np.size(num_neurons)\n", - "\n", - " ## Set up initial weigths and biases\n", - "\n", - " # Initialize the list of parameters:\n", - " P = [None]*(N_hidden + 1) # + 1 to include the output layer\n", - "\n", - " P[0] = npr.randn(num_neurons[0], 2 + 1 ) # 2 since we have two points, +1 to include bias\n", - " for l in range(1,N_hidden):\n", - " P[l] = npr.randn(num_neurons[l], num_neurons[l-1] + 1) # +1 to include bias\n", - "\n", - " # For the output layer\n", - " P[-1] = npr.randn(1, num_neurons[-1] + 1 ) # +1 since bias is included\n", - "\n", - " print('Initial cost: ',cost_function(P, x, t))\n", - "\n", - " cost_function_grad = grad(cost_function,0)\n", - "\n", - " # Let the update be done num_iter times\n", - " for i in range(num_iter):\n", - " cost_grad = cost_function_grad(P, x , t)\n", - "\n", - " for l in range(N_hidden+1):\n", - " P[l] = P[l] - lmb * cost_grad[l]\n", - "\n", - " print('Final cost: ',cost_function(P, x, t))\n", - "\n", - " return P\n", - "\n", - "if __name__ == '__main__':\n", - " ### Use the neural network:\n", - " npr.seed(15)\n", - "\n", - " ## Decide the vales of arguments to the function to solve\n", - " Nx = 10; Nt = 10\n", - " x = np.linspace(0, 1, Nx)\n", - " t = np.linspace(0,1,Nt)\n", - "\n", - " ## Set up the parameters for the network\n", - " num_hidden_neurons = [100, 25]\n", - " num_iter = 250\n", - " lmb = 0.01\n", - "\n", - " P = solve_pde_deep_neural_network(x,t, num_hidden_neurons, num_iter, lmb)\n", - "\n", - " ## Store the results\n", - " g_dnn_ag = np.zeros((Nx, Nt))\n", - " G_analytical = np.zeros((Nx, Nt))\n", - " for i,x_ in enumerate(x):\n", - " for j, t_ in enumerate(t):\n", - " point = np.array([x_, t_])\n", - " g_dnn_ag[i,j] = g_trial(point,P)\n", - "\n", - " G_analytical[i,j] = g_analytic(point)\n", - "\n", - " # Find the map difference between the analytical and the computed solution\n", - " diff_ag = np.abs(g_dnn_ag - G_analytical)\n", - " print('Max absolute difference between the analytical solution and the network: %g'%np.max(diff_ag))\n", - "\n", - " ## Plot the solutions in two dimensions, that being in position and time\n", - "\n", - " T,X = np.meshgrid(t,x)\n", - "\n", - " fig = plt.figure(figsize=(10,10))\n", - " ax = fig.gca(projection='3d')\n", - " ax.set_title('Solution from the deep neural network w/ %d layer'%len(num_hidden_neurons))\n", - " s = ax.plot_surface(T,X,g_dnn_ag,linewidth=0,antialiased=False,cmap=cm.viridis)\n", - " ax.set_xlabel('Time $t$')\n", - " ax.set_ylabel('Position $x$');\n", - "\n", - "\n", - " fig = plt.figure(figsize=(10,10))\n", - " ax = fig.gca(projection='3d')\n", - " ax.set_title('Analytical solution')\n", - " s = ax.plot_surface(T,X,G_analytical,linewidth=0,antialiased=False,cmap=cm.viridis)\n", - " ax.set_xlabel('Time $t$')\n", - " ax.set_ylabel('Position $x$');\n", - "\n", - " fig = plt.figure(figsize=(10,10))\n", - " ax = fig.gca(projection='3d')\n", - " ax.set_title('Difference')\n", - " s = ax.plot_surface(T,X,diff_ag,linewidth=0,antialiased=False,cmap=cm.viridis)\n", - " ax.set_xlabel('Time $t$')\n", - " ax.set_ylabel('Position $x$');\n", - "\n", - " ## Take some slices of the 3D plots just to see the solutions at particular times\n", - " indx1 = 0\n", - " indx2 = int(Nt/2)\n", - " indx3 = Nt-1\n", - "\n", - " t1 = t[indx1]\n", - " t2 = t[indx2]\n", - " t3 = t[indx3]\n", - "\n", - " # Slice the results from the DNN\n", - " res1 = g_dnn_ag[:,indx1]\n", - " res2 = g_dnn_ag[:,indx2]\n", - " res3 = g_dnn_ag[:,indx3]\n", - "\n", - " # Slice the analytical results\n", - " res_analytical1 = G_analytical[:,indx1]\n", - " res_analytical2 = G_analytical[:,indx2]\n", - " res_analytical3 = G_analytical[:,indx3]\n", - "\n", - " # Plot the slices\n", - " plt.figure(figsize=(10,10))\n", - " plt.title(\"Computed solutions at time = %g\"%t1)\n", - " plt.plot(x, res1)\n", - " plt.plot(x,res_analytical1)\n", - " plt.legend(['dnn','analytical'])\n", - "\n", - " plt.figure(figsize=(10,10))\n", - " plt.title(\"Computed solutions at time = %g\"%t2)\n", - " plt.plot(x, res2)\n", - " plt.plot(x,res_analytical2)\n", - " plt.legend(['dnn','analytical'])\n", - "\n", - " plt.figure(figsize=(10,10))\n", - " plt.title(\"Computed solutions at time = %g\"%t3)\n", - " plt.plot(x, res3)\n", - " plt.plot(x,res_analytical3)\n", - " plt.legend(['dnn','analytical'])\n", - "\n", - " plt.show()" - ] - }, - { - "cell_type": "markdown", - "id": "143f1c80", - "metadata": { - "editable": true - }, - "source": [ - "## Solving the wave equation with Neural Networks\n", - "\n", - "The wave equation is" - ] - }, - { - "cell_type": "markdown", - "id": "190bd4f2", - "metadata": { - "editable": true - }, - "source": [ - "$$\n", - "\\frac{\\partial^2 g(x,t)}{\\partial t^2} = c^2\\frac{\\partial^2 g(x,t)}{\\partial x^2}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "9719cfc5", - "metadata": { - "editable": true - }, - "source": [ - "with $c$ being the specified wave speed.\n", - "\n", - "Here, the chosen conditions are" - ] - }, - { - "cell_type": "markdown", - "id": "f69ec7fd", - "metadata": { - "editable": true - }, - "source": [ - "$$\n", - "\\begin{align*}\n", - "\tg(0,t) &= 0 \\\\\n", - "\tg(1,t) &= 0 \\\\\n", - "\tg(x,0) &= u(x) \\\\\n", - "\t\\frac{\\partial g(x,t)}{\\partial t} \\Big |_{t = 0} &= v(x)\n", - "\\end{align*}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "6ce8c5a8", - "metadata": { - "editable": true - }, - "source": [ - "where $\\frac{\\partial g(x,t)}{\\partial t} \\Big |_{t = 0}$ means the derivative of $g(x,t)$ with respect to $t$ is evaluated at $t = 0$, and $u(x)$ and $v(x)$ being given functions.\n", - "\n", - "The wave equation to solve for, is" - ] - }, - { - "cell_type": "markdown", - "id": "4be700d7", - "metadata": { - "editable": true - }, - "source": [ - "\n", - "
\n", - "\n", - "$$\n", - "\\begin{equation} \\label{wave} \\tag{19}\n", - "\\frac{\\partial^2 g(x,t)}{\\partial t^2} = c^2 \\frac{\\partial^2 g(x,t)}{\\partial x^2}\n", - "\\end{equation}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "993f93ba", - "metadata": { - "editable": true - }, - "source": [ - "where $c$ is the given wave speed.\n", - "The chosen conditions for this equation are" - ] - }, - { - "cell_type": "markdown", - "id": "2cb2a80f", - "metadata": { - "editable": true - }, - "source": [ - "\n", - "
\n", - "\n", - "$$\n", - "\\begin{aligned}\n", - "g(0,t) &= 0, &t \\geq 0 \\\\\n", - "g(1,t) &= 0, &t \\geq 0 \\\\\n", - "g(x,0) &= u(x), &x\\in[0,1] \\\\\n", - "\\frac{\\partial g(x,t)}{\\partial t}\\Big |_{t = 0} &= v(x), &x \\in [0,1]\n", - "\\end{aligned} \\label{condwave} \\tag{20}\n", - "$$" - ] - }, - { - "cell_type": "markdown", - "id": "3f1dcfd4", - "metadata": { - "editable": true - }, - "source": [ - "In this example, let $c = 1$ and $u(x) = \\sin(\\pi x)$ and $v(x) = -\\pi\\sin(\\pi x)$.\n", - "\n", - "Setting up the network is done in similar matter as for the example of solving the diffusion equation.\n", - "The only things we have to change, is the trial solution such that it satisfies the conditions from ([20](#condwave)) and the cost function.\n", - "\n", - "The trial solution becomes slightly different since we have other conditions than in the example of solving the diffusion equation. Here, a possible trial solution $g_t(x,t)$ is\n", - "\n", - "$$\n", - "g_t(x,t) = h_1(x,t) + x(1-x)t^2N(x,t,P)\n", - "$$\n", - "\n", - "where\n", - "\n", - "$$\n", - "h_1(x,t) = (1-t^2)u(x) + tv(x)\n", - "$$\n", - "\n", - "Note that this trial solution satisfies the conditions only if $u(0) = v(0) = u(1) = v(1) = 0$, which is the case in this example.\n", - "\n", - "The analytical solution for our specific problem, is\n", - "\n", - "$$\n", - "g(x,t) = \\sin(\\pi x)\\cos(\\pi t) - \\sin(\\pi x)\\sin(\\pi t)\n", - "$$" - ] - }, - { - "cell_type": "code", - "execution_count": 10, - "id": "230a9aef", - "metadata": { - "collapsed": false, - "editable": true - }, - "outputs": [], - "source": [ - "import autograd.numpy as np\n", - "from autograd import hessian,grad\n", - "import autograd.numpy.random as npr\n", - "from matplotlib import cm\n", - "from matplotlib import pyplot as plt\n", - "from mpl_toolkits.mplot3d import axes3d\n", - "\n", - "## Set up the trial function:\n", - "def u(x):\n", - " return np.sin(np.pi*x)\n", - "\n", - "def v(x):\n", - " return -np.pi*np.sin(np.pi*x)\n", - "\n", - "def h1(point):\n", - " x,t = point\n", - " return (1 - t**2)*u(x) + t*v(x)\n", - "\n", - "def g_trial(point,P):\n", - " x,t = point\n", - " return h1(point) + x*(1-x)*t**2*deep_neural_network(P,point)\n", - "\n", - "## Define the cost function\n", - "def cost_function(P, x, t):\n", - " cost_sum = 0\n", - "\n", - " g_t_hessian_func = hessian(g_trial)\n", - "\n", - " for x_ in x:\n", - " for t_ in t:\n", - " point = np.array([x_,t_])\n", - "\n", - " g_t_hessian = g_t_hessian_func(point,P)\n", - "\n", - " g_t_d2x = g_t_hessian[0][0]\n", - " g_t_d2t = g_t_hessian[1][1]\n", - "\n", - " err_sqr = ( (g_t_d2t - g_t_d2x) )**2\n", - " cost_sum += err_sqr\n", - "\n", - " return cost_sum / (np.size(t) * np.size(x))\n", - "\n", - "## The neural network\n", - "def sigmoid(z):\n", - " return 1/(1 + np.exp(-z))\n", - "\n", - "def deep_neural_network(deep_params, x):\n", - " # x is now a point and a 1D numpy array; make it a column vector\n", - " num_coordinates = np.size(x,0)\n", - " x = x.reshape(num_coordinates,-1)\n", - "\n", - " num_points = np.size(x,1)\n", - "\n", - " # N_hidden is the number of hidden layers\n", - " N_hidden = np.size(deep_params) - 1 # -1 since params consist of parameters to all the hidden layers AND the output layer\n", - "\n", - " # Assume that the input layer does nothing to the input x\n", - " x_input = x\n", - " x_prev = x_input\n", - "\n", - " ## Hidden layers:\n", - "\n", - " for l in range(N_hidden):\n", - " # From the list of parameters P; find the correct weigths and bias for this layer\n", - " w_hidden = deep_params[l]\n", - "\n", - " # Add a row of ones to include bias\n", - " x_prev = np.concatenate((np.ones((1,num_points)), x_prev ), axis = 0)\n", - "\n", - " z_hidden = np.matmul(w_hidden, x_prev)\n", - " x_hidden = sigmoid(z_hidden)\n", - "\n", - " # Update x_prev such that next layer can use the output from this layer\n", - " x_prev = x_hidden\n", - "\n", - " ## Output layer:\n", - "\n", - " # Get the weights and bias for this layer\n", - " w_output = deep_params[-1]\n", - "\n", - " # Include bias:\n", - " x_prev = np.concatenate((np.ones((1,num_points)), x_prev), axis = 0)\n", - "\n", - " z_output = np.matmul(w_output, x_prev)\n", - " x_output = z_output\n", - "\n", - " return x_output[0][0]\n", - "\n", - "## The analytical solution\n", - "def g_analytic(point):\n", - " x,t = point\n", - " return np.sin(np.pi*x)*np.cos(np.pi*t) - np.sin(np.pi*x)*np.sin(np.pi*t)\n", - "\n", - "def solve_pde_deep_neural_network(x,t, num_neurons, num_iter, lmb):\n", - " ## Set up initial weigths and biases\n", - " N_hidden = np.size(num_neurons)\n", - "\n", - " ## Set up initial weigths and biases\n", - "\n", - " # Initialize the list of parameters:\n", - " P = [None]*(N_hidden + 1) # + 1 to include the output layer\n", - "\n", - " P[0] = npr.randn(num_neurons[0], 2 + 1 ) # 2 since we have two points, +1 to include bias\n", - " for l in range(1,N_hidden):\n", - " P[l] = npr.randn(num_neurons[l], num_neurons[l-1] + 1) # +1 to include bias\n", - "\n", - " # For the output layer\n", - " P[-1] = npr.randn(1, num_neurons[-1] + 1 ) # +1 since bias is included\n", - "\n", - " print('Initial cost: ',cost_function(P, x, t))\n", - "\n", - " cost_function_grad = grad(cost_function,0)\n", - "\n", - " # Let the update be done num_iter times\n", - " for i in range(num_iter):\n", - " cost_grad = cost_function_grad(P, x , t)\n", - "\n", - " for l in range(N_hidden+1):\n", - " P[l] = P[l] - lmb * cost_grad[l]\n", - "\n", - "\n", - " print('Final cost: ',cost_function(P, x, t))\n", - "\n", - " return P\n", - "\n", - "if __name__ == '__main__':\n", - " ### Use the neural network:\n", - " npr.seed(15)\n", - "\n", - " ## Decide the vales of arguments to the function to solve\n", - " Nx = 10; Nt = 10\n", - " x = np.linspace(0, 1, Nx)\n", - " t = np.linspace(0,1,Nt)\n", - "\n", - " ## Set up the parameters for the network\n", - " num_hidden_neurons = [50,20]\n", - " num_iter = 1000\n", - " lmb = 0.01\n", - "\n", - " P = solve_pde_deep_neural_network(x,t, num_hidden_neurons, num_iter, lmb)\n", - "\n", - " ## Store the results\n", - " res = np.zeros((Nx, Nt))\n", - " res_analytical = np.zeros((Nx, Nt))\n", - " for i,x_ in enumerate(x):\n", - " for j, t_ in enumerate(t):\n", - " point = np.array([x_, t_])\n", - " res[i,j] = g_trial(point,P)\n", - "\n", - " res_analytical[i,j] = g_analytic(point)\n", - "\n", - " diff = np.abs(res - res_analytical)\n", - " print(\"Max difference between analytical and solution from nn: %g\"%np.max(diff))\n", - "\n", - " ## Plot the solutions in two dimensions, that being in position and time\n", - "\n", - " T,X = np.meshgrid(t,x)\n", - "\n", - " fig = plt.figure(figsize=(10,10))\n", - " ax = fig.gca(projection='3d')\n", - " ax.set_title('Solution from the deep neural network w/ %d layer'%len(num_hidden_neurons))\n", - " s = ax.plot_surface(T,X,res,linewidth=0,antialiased=False,cmap=cm.viridis)\n", - " ax.set_xlabel('Time $t$')\n", - " ax.set_ylabel('Position $x$');\n", - "\n", - "\n", - " fig = plt.figure(figsize=(10,10))\n", - " ax = fig.gca(projection='3d')\n", - " ax.set_title('Analytical solution')\n", - " s = ax.plot_surface(T,X,res_analytical,linewidth=0,antialiased=False,cmap=cm.viridis)\n", - " ax.set_xlabel('Time $t$')\n", - " ax.set_ylabel('Position $x$');\n", - "\n", - "\n", - " fig = plt.figure(figsize=(10,10))\n", - " ax = fig.gca(projection='3d')\n", - " ax.set_title('Difference')\n", - " s = ax.plot_surface(T,X,diff,linewidth=0,antialiased=False,cmap=cm.viridis)\n", - " ax.set_xlabel('Time $t$')\n", - " ax.set_ylabel('Position $x$');\n", - "\n", - " ## Take some slices of the 3D plots just to see the solutions at particular times\n", - " indx1 = 0\n", - " indx2 = int(Nt/2)\n", - " indx3 = Nt-1\n", - "\n", - " t1 = t[indx1]\n", - " t2 = t[indx2]\n", - " t3 = t[indx3]\n", - "\n", - " # Slice the results from the DNN\n", - " res1 = res[:,indx1]\n", - " res2 = res[:,indx2]\n", - " res3 = res[:,indx3]\n", - "\n", - " # Slice the analytical results\n", - " res_analytical1 = res_analytical[:,indx1]\n", - " res_analytical2 = res_analytical[:,indx2]\n", - " res_analytical3 = res_analytical[:,indx3]\n", - "\n", - " # Plot the slices\n", - " plt.figure(figsize=(10,10))\n", - " plt.title(\"Computed solutions at time = %g\"%t1)\n", - " plt.plot(x, res1)\n", - " plt.plot(x,res_analytical1)\n", - " plt.legend(['dnn','analytical'])\n", - "\n", - " plt.figure(figsize=(10,10))\n", - " plt.title(\"Computed solutions at time = %g\"%t2)\n", - " plt.plot(x, res2)\n", - " plt.plot(x,res_analytical2)\n", - " plt.legend(['dnn','analytical'])\n", - "\n", - " plt.figure(figsize=(10,10))\n", - " plt.title(\"Computed solutions at time = %g\"%t3)\n", - " plt.plot(x, res3)\n", - " plt.plot(x,res_analytical3)\n", - " plt.legend(['dnn','analytical'])\n", - "\n", - " plt.show()" - ] - }, - { - "cell_type": "markdown", - "id": "a23bd19a", - "metadata": { - "editable": true - }, - "source": [ - "## Resources on differential equations and deep learning\n", - "\n", - "1. [Artificial neural networks for solving ordinary and partial differential equations by I.E. Lagaris et al](https://pdfs.semanticscholar.org/d061/df393e0e8fbfd0ea24976458b7d42419040d.pdf)\n", - "\n", - "2. [Neural networks for solving differential equations by A. Honchar](https://becominghuman.ai/neural-networks-for-solving-differential-equations-fa230ac5e04c)\n", - "\n", - "3. [Solving differential equations using neural networks by M.M Chiaramonte and M. Kiener](http://cs229.stanford.edu/proj2013/ChiaramonteKiener-SolvingDifferentialEquationsUsingNeuralNetworks.pdf)\n", - "\n", - "4. [Introduction to Partial Differential Equations by A. Tveito, R. Winther](https://www.springer.com/us/book/9783540225515)" - ] - } - ], - "metadata": {}, - "nbformat": 4, - "nbformat_minor": 5 -} diff --git a/doc/BookChapters/chapter12.do.txt b/doc/BookChapters/chapter12.do.txt index 6371c0102..851715e74 100644 --- a/doc/BookChapters/chapter12.do.txt +++ b/doc/BookChapters/chapter12.do.txt @@ -1,6 +1,7 @@ ======= Convolutional Neural Networks ======= + Convolutional neural networks (CNNs) were developed during the last decade of the previous century, with a focus on character recognition tasks. Nowadays, CNNs are a central element in the spectacular success @@ -18,12 +19,53 @@ loss function (for example Softmax) on the last (fully-connected) layer and all the tips/tricks we developed for learning regular Neural Networks still apply (back propagation, gradient descent etc etc). -What is the difference? _CNN architectures make the explicit assumption that + + +_CNN architectures make the explicit assumption that the inputs are images, which allows us to encode certain properties into the architecture. These then make the forward function more efficient to implement and vastly reduce the amount of parameters in the network._ +Here we provide only a superficial overview, for the more interested, we recommend highly the course +"IN5400 – Machine Learning for Image Analysis":"https://www.uio.no/studier/emner/matnat/ifi/IN5400/index-eng.html" +and the slides of "CS231":"http://cs231n.github.io/convolutional-networks/". + +Another good read is the article here URL:"https://arxiv.org/pdf/1603.07285.pdf". + + + +===== Neural Networks vs CNNs ===== + +Neural networks are defined as _affine transformations_, that is +a vector is received as input and is multiplied with a matrix of so-called weights (our unknown paramters) to produce an +output (to which a bias vector is usually added before passing the result +through a nonlinear activation function). This is applicable to any type of input, be it an +image, a sound clip or an unordered collection of features: whatever their +dimensionality, their representation can always be flattened into a vector +before the transformation. + + + +However, when we consider images, sound clips and many other similar kinds of data, these data have an intrinsic +structure. More formally, they share these important properties: +* They are stored as multi-dimensional arrays (think of the pixels of a figure) . +* They feature one or more axes for which ordering matters (e.g., width and height axes for an image, time axis for a sound clip). +* One axis, called the channel axis, is used to access different views of the data (e.g., the red, green and blue channels of a color image, or the left and right channels of a stereo audio track). + +These properties are not exploited when an affine transformation is applied; in +fact, all the axes are treated in the same way and the topological information +is not taken into account. Still, taking advantage of the implicit structure of +the data may prove very handy in solving some tasks, like computer vision and +speech recognition, and in these cases it would be best to preserve it. This is +where discrete convolutions come into play. + +A discrete convolution is a linear transformation that preserves this notion of +ordering. It is sparse (only a few input units contribute to a given output +unit) and reuses parameters (the same weights are applied to multiple locations +in the input). + + As an example, consider an image of size $32\times 32\times 3$ (32 wide, 32 high, 3 color channels), so a @@ -42,7 +84,6 @@ would quickly lead to possible overfitting. FIGURE: [figslides/nn.jpeg, width=500 frac=0.6] A regular 3-layer Neural Network. - Convolutional Neural Networks take advantage of the fact that the input consists of images and they constrain the architecture in a more sensible way. @@ -67,11 +108,14 @@ end of the CNN architecture we will reduce the full image into a single vector of class scores, arranged along the depth dimension. -FIGURE: [figslides/cnn.jpeg, width=500 frac=0.6] A CNN arranges its neurons in three dimensions (width, heigh#t, depth), as visualized in one of the layers. Every layer of a CNN transforms the 3D input volume to a 3D out#put volume of neuron activations. In this example, the red input layer holds the image, so its width and heigh#t would be the dimensions of the image, and the depth would be 3 (Red, Green, Blue channels). +FIGURE: [figslides/cnn.jpeg, width=500 frac=0.6] A CNN arranges its neurons in three dimensions (width, height, depth), as visualized in one of the layers. Every layer of a CNN transforms the 3D input volume to a 3D output volume of neuron activations. In this example, the red input layer holds the image, so its width and height would be the dimensions of the image, and the depth would be 3 (Red, Green, Blue channels). +===== Layers used to build CNNs ===== + + A simple CNN is a sequence of layers, and every layer of a CNN transforms one volume of activations to another through a differentiable function. We use three main types of layers to build @@ -89,6 +133,7 @@ A simple CNN for image classification could have the architecture: + CNNs transform the original image layer by layer from the original pixel values to the final class scores. @@ -103,8 +148,6 @@ are consistent with the labels in the training set for each image. -=== CNNs in brief === - In summary: * A CNN architecture is in the simplest case a list of Layers that transform the image volume into an output volume (e.g. holding the class scores) @@ -114,6 +157,438 @@ In summary: * Each Layer may or may not have additional hyperparameters (e.g. CONV/FC/POOL do, RELU doesn’t) +A dense neural network is representd by an affine operation (like matrix-matrix multiplication) where all parameters are included. + +The key idea in CNNs for say imaging is that in images neighbor pixels tend to be related! So we connect +only neighboring neurons in the input instead of connecting all with the first hidden layer. + +We say we perform a filtering (convolution is the mathematical operation). + + + +===== Mathematics of CNNs ===== + +The mathematics of CNNs is based on the mathematical operation of +_convolution_. In mathematics (in particular in functional analysis), +convolution is represented by matheematical operation (integration, +summation etc) on two function in order to produce a third function +that expresses how the shape of one gets modified by the other. +Convolution has a plethora of applications in a variety of disciplines, spanning from statistics to signal processing, computer vision, solutions of differential equations,linear algebra, engineering, and yes, machine learning. + +Mathematically, convolution is defined as follows (one-dimensional example): +Let us define a continuous function $y(t)$ given by +!bt +\[ +y(t) = \int x(a) w(t-a) da, +\] +!et +where $x(a)$ represents a so-called input and $w(t-a)$ is normally called the weight function or kernel. + +The above integral is written in a more compact form as +!bt +\[ +y(t) = \left(x * w\right)(t). +\] +!et + +The discretized version reads +!bt +\[ +y(t) = \sum_{a=-\infty}^{a=\infty}x(a)w(t-a). +\] +!et +Computing the inverse of the above convolution operations is known as deconvolution. + +How can we use this? And what does it mean? Let us study some familiar examples first. + + + +=== Convolution Examples: Polynomial multiplication === + +We have already met such an example in project 1 when we tried to set +up the design matrix for a two-dimensional function. This was an +example of polynomial multiplication. Let us recast such a problem in terms of the convolution operation. +Let us look a the following polynomials to second and third order, respectively: +!bt +\[ +p(t) = \alpha_0+\alpha_1 t+\alpha_2 t^2, +\] +!et +and +!bt +\[ +s(t) = \beta_0+\beta_1 t+\beta_2 t^2+\beta_3 t^3. +\] +!et + +The polynomial multiplication gives us a new polynomial of degree $5$ +!bt +\[ +z(t) = \delta_0+\delta_1 t+\delta_2 t^2+\delta_3 t^3+\delta_4 t^4+\delta_5 t^5. +\] +!et + + +Computing polynomial products can be implemented efficiently if we rewrite the more brute force multiplications using convolution. +We note first that the new coefficients are given as + +!bt +\begin{split} +\delta_0=&\alpha_0\beta_0\\ +\delta_1=&\alpha_1\beta_0+\alpha_1\beta_0\\ +\delta_2=&\alpha_0\beta_2+\alpha_1\beta_1+\alpha_2\beta_0\\ +\delta_3=&\alpha_1\beta_2+\alpha_2\beta_1+\alpha_0\beta_3\\ +\delta_4=&\alpha_2\beta_2+\alpha_1\beta_3\\ +\delta_5=&\alpha_2\beta_3.\\ +\end{split} +!et + + +We note that $\alpha_i=0$ except for $i\in \left\{0,1,2\right\}$ and $\beta_i=0$ except for $i\in\left\{0,1,2,3\right\}$. + +We can then rewrite the coefficients $\delta_j$ using a discrete convolution as +!bt +\[ +\delta_j = \sum_{i=-\infty}^{i=\infty}\alpha_i\beta_{j-i}=(\alpha * \beta)_j, +\] +!et +or as a double sum with restriction $l=i+j$ +!bt +\[ +\delta_l = \sum_{ij}\alpha_i\beta_{j}. +\] +!et + +Do you see a potential drawback with these equations? + + +Since we only have a finite number of $\alpha$ and $\beta$ values +which are non-zero, we can rewrite the above convolution expressions +as a matrix-vector multiplication + +!bt +\[ +\bm{\delta}=\begin{bmatrix}\alpha_0 & 0 & 0 & 0 \\ + \alpha_1 & \alpha_0 & 0 & 0 \\ + \alpha_2 & \alpha_1 & \alpha_0 & 0 \\ + 0 & \alpha_2 & \alpha_1 & \alpha_0 \\ + 0 & 0 & \alpha_2 & \alpha_1 \\ + 0 & 0 & 0 & \alpha_2 + \end{bmatrix}\begin{bmatrix} \beta_0 \\ \beta_1 \\ \beta_2 \\ \beta_3\end{bmatrix}. +\] +!et + +The process is commutative and we can easily see that we can rewrite the multiplication in terms of a matrix holding $\beta$ and a vector holding $\alpha$. +In this case we have +!bt +\[ +\bm{\delta}=\begin{bmatrix}\beta_0 & 0 & 0 \\ + \beta_1 & \beta_0 & 0 \\ + \beta_2 & \beta_1 & \beta_0 \\ + \beta_3 & \beta_2 & \beta_1 \\ + 0 & \beta_3 & \beta_2 \\ + 0 & 0 & \beta_3 + \end{bmatrix}\begin{bmatrix} \alpha_0 \\ \alpha_1 \\ \alpha_2\end{bmatrix}. +\] +!et + +Note that the use of these matrices is for mathematical purposes only and not implementation purposes. +When implementing the above equation we do not encode (and allocate memory) the matrices explicitely. +We rather code the convolutions in the minimal memory footprint that they require. + +Does the number of floating point operations change here when we use the commutative property? + +=== Convolution Examples: Principle of Superposition and Periodic Forces (Fourier Transforms) === + +For problems with so-called harmonic oscillations, given by for example the following differential equation +!bt +\[ +m\frac{d^2x}{dt^2}+\eta\frac{dx}{dt}+x(t)=F(t), +\] +!et +where $F(t)$ is an applied external force acting on the system (often called a driving force), one can use the theory of Fourier transformations to find the solutions of this type of equations. + +If one has several driving forces, $F(t)=\sum_n F_n(t)$, one can find +the particular solution to each $F_n$, $x_{pn}(t)$, and the particular +solution for the entire driving force is then given by a series like + +!bt +\begin{equation} +x_p(t)=\sum_nx_{pn}(t). +\end{equation} +!et + + + +This is known as the principle of superposition. It only applies when +the homogenous equation is linear. If there were an anharmonic term +such as $x^3$ in the homogenous equation, then when one summed various +solutions, $x=(\sum_n x_n)^2$, one would get cross +terms. Superposition is especially useful when $F(t)$ can be written +as a sum of sinusoidal terms, because the solutions for each +sinusoidal (sine or cosine) term is analytic. + +Driving forces are often periodic, even when they are not +sinusoidal. Periodicity implies that for some time $\tau$ + +!bt +\begin{eqnarray} +F(t+\tau)=F(t). +\end{eqnarray} +!et + +One example of a non-sinusoidal periodic force is a square wave. Many +components in electric circuits are non-linear, e.g. diodes, which +makes many wave forms non-sinusoidal even when the circuits are being +driven by purely sinusoidal sources. + + +The code here shows a typical example of such a square wave generated using the functionality included in the _scipy_ Python package. We have used a period of $\tau=0.2$. + +!bc pycod +import numpy as np +import math +from scipy import signal +import matplotlib.pyplot as plt + +# number of points +n = 500 +# start and final times +t0 = 0.0 +tn = 1.0 +# Period +t = np.linspace(t0, tn, n, endpoint=False) +SqrSignal = np.zeros(n) +SqrSignal = 1.0+signal.square(2*np.pi*5*t) +plt.plot(t, SqrSignal) +plt.ylim(-0.5, 2.5) +plt.show() +!ec + + +For the sinusoidal example the +period is $\tau=2\pi/\omega$. However, higher harmonics can also +satisfy the periodicity requirement. In general, any force that +satisfies the periodicity requirement can be expressed as a sum over +harmonics, + +!bt +\begin{equation} +F(t)=\frac{f_0}{2}+\sum_{n>0} f_n\cos(2n\pi t/\tau)+g_n\sin(2n\pi t/\tau). +\end{equation} +!et + + +We can write down the answer for +$x_{pn}(t)$, by substituting $f_n/m$ or $g_n/m$ for $F_0/m$. By +writing each factor $2n\pi t/\tau$ as $n\omega t$, with $\omega\equiv +2\pi/\tau$, + +!bt +\begin{equation} +label{eq:fourierdef1} +F(t)=\frac{f_0}{2}+\sum_{n>0}f_n\cos(n\omega t)+g_n\sin(n\omega t). +\end{equation} +!et + +The solutions for $x(t)$ then come from replacing $\omega$ with +$n\omega$ for each term in the particular solution, + +!bt +\begin{eqnarray} +x_p(t)&=&\frac{f_0}{2k}+\sum_{n>0} \alpha_n\cos(n\omega t-\delta_n)+\beta_n\sin(n\omega t-\delta_n),\\ +\nonumber +\alpha_n&=&\frac{f_n/m}{\sqrt{((n\omega)^2-\omega_0^2)+4\beta^2n^2\omega^2}},\\ +\nonumber +\beta_n&=&\frac{g_n/m}{\sqrt{((n\omega)^2-\omega_0^2)+4\beta^2n^2\omega^2}},\\ +\nonumber +\delta_n&=&\tan^{-1}\left(\frac{2\beta n\omega}{\omega_0^2-n^2\omega^2}\right). +\end{eqnarray} +!et + + + +Because the forces have been applied for a long time, any non-zero +damping eliminates the homogenous parts of the solution, so one need +only consider the particular solution for each $n$. + +The problem is considered solved if one can find expressions for the +coefficients $f_n$ and $g_n$, even though the solutions are expressed +as an infinite sum. The coefficients can be extracted from the +function $F(t)$ by + +!bt +\begin{eqnarray} +label{eq:fourierdef2} +f_n&=&\frac{2}{\tau}\int_{-\tau/2}^{\tau/2} dt~F(t)\cos(2n\pi t/\tau),\\ +\nonumber +g_n&=&\frac{2}{\tau}\int_{-\tau/2}^{\tau/2} dt~F(t)\sin(2n\pi t/\tau). +\end{eqnarray} +!et + +To check the consistency of these expressions and to verify +Eq. (ref{eq:fourierdef2}), one can insert the expansion of $F(t)$ in +Eq. (ref{eq:fourierdef1}) into the expression for the coefficients in +Eq. (ref{eq:fourierdef2}) and see whether + +!bt +\begin{eqnarray} +f_n&=?&\frac{2}{\tau}\int_{-\tau/2}^{\tau/2} dt~\left\{ +\frac{f_0}{2}+\sum_{m>0}f_m\cos(m\omega t)+g_m\sin(m\omega t) +\right\}\cos(n\omega t). +\end{eqnarray} +!et + +Immediately, one can throw away all the terms with $g_m$ because they +convolute an even and an odd function. The term with $f_0/2$ +disappears because $\cos(n\omega t)$ is equally positive and negative +over the interval and will integrate to zero. For all the terms +$f_m\cos(m\omega t)$ appearing in the sum, one can use angle addition +formulas to see that $\cos(m\omega t)\cos(n\omega +t)=(1/2)(\cos[(m+n)\omega t]+\cos[(m-n)\omega t]$. This will integrate +to zero unless $m=n$. In that case the $m=n$ term gives + +!bt +\begin{equation} +\int_{-\tau/2}^{\tau/2}dt~\cos^2(m\omega t)=\frac{\tau}{2}, +\end{equation} +!et + +and + +!bt +\begin{eqnarray} +f_n&=?&\frac{2}{\tau}\int_{-\tau/2}^{\tau/2} dt~f_n/2\\ +\nonumber +&=&f_n~\checkmark. +\end{eqnarray} +!et + +The same method can be used to check for the consistency of $g_n$. + + + + +The code here uses the Fourier series applied to a +square wave signal. The code here +visualizes the various approximations given by Fourier series compared +with a square wave with period $T=0.2$ (dimensionless time), width $0.1$ and max value of the force $F=2$. We +see that when we increase the number of components in the Fourier +series, the Fourier series approximation gets closer and closer to the +square wave signal. + +!bc pycod +import numpy as np +import math +from scipy import signal +import matplotlib.pyplot as plt + +# number of points +n = 500 +# start and final times +t0 = 0.0 +tn = 1.0 +# Period +T =0.2 +# Max value of square signal +Fmax= 2.0 +# Width of signal +Width = 0.1 +t = np.linspace(t0, tn, n, endpoint=False) +SqrSignal = np.zeros(n) +FourierSeriesSignal = np.zeros(n) +SqrSignal = 1.0+signal.square(2*np.pi*5*t+np.pi*Width/T) +a0 = Fmax*Width/T +FourierSeriesSignal = a0 +Factor = 2.0*Fmax/np.pi +for i in range(1,500): + FourierSeriesSignal += Factor/(i)*np.sin(np.pi*i*Width/T)*np.cos(i*t*2*np.pi/T) +plt.plot(t, SqrSignal) +plt.plot(t, FourierSeriesSignal) +plt.ylim(-0.5, 2.5) +plt.show() +!ec + + + +===== Two-dimensional Objects ===== + +We often use convolutions over more than one dimension at a time. If +we have a two-dimensional image $I$ as input, we can have a _filter_ +defined by a two-dimensional _kernel_ $K$. This leads to an output $S$ + +!bt +\[ +S_(i,j)=(I * K)(i,j) = \sum_m\sum_n I(m,n)K(i-m,j-n). +\] +!et + +Convolution is a commutatitave process, which means we can rewrite this equation as +!bt +\[ +S_(i,j)=(I * K)(i,j) = \sum_m\sum_n I(i-m,j-n)K(m,n). +\] +!et + +Normally the latter is more straightforward to implement in a machine elarning library since there is less variation in the range of values of $m$ and $n$. + + +Many deep learning libraries implement cross-correlation instead of convolution +!bt +\[ +S_(i,j)=(I * K)(i,j) = \sum_m\sum_n I(i+m,j-+)K(m,n). +\] +!et + + +===== More on Dimensionalities ===== + +In fields like signal processing (and imaging as well), one designs +so-called filters. These filters are defined by the convolutions and +are often hand-crafted. One may specify filters for smoothing, edge +detection, frequency reshaping, and similar operations. However with +neural networks the idea is to automatically learn the filters and use +many of them in conjunction with non-linear operations (activation +functions). + +As an example consider a neural network operating on sound sequence +data. Assume that we an input vector $\bm{x}$ of length $d=10^6$. We +construct then a neural network with onle hidden layer only with +$10^4$ nodes. This means that we will have a weight matrix with +$10^4\times 10^6=10^{10}$ weights to be determined, together with $10^4$ biases. + +Assume furthermore that we have an output layer which is meant to train whether the sound sequence represents a human voice (true) or something else (false). +It means that we have only one output node. But since this output node connects to $10^4$ nodes in the hidden layer, there are in total $10^4$ weights to be determined for the output layer, plus one bias. In total we have + +!bt +\[ +\mathrm{NumberParameters}=10^{10}+10^4+10^4+1 \approx 10^{10}, +\] +!et +that is ten billion parameters to determine. + + +===== Further Dimensionality Remarks ===== + +In today’s architecture one can train such neural networks, however +this is a huge number of parameters for the task at hand. In general, +it is a very wasteful and inefficient use of dense matrices as +parameters. Just as importantly, such trained network parameters are +very specific for the type of input data on which they were trained +and the network is not likely to generalize easily to variations in +the input. + + +The main principles that justify convolutions is locality of +information and repetion of patterns within the signal. Sound samples +of the input in adjacent spots are much more likely to affect each +other than those that are very far away. Similarly, sounds are +repeated in multiple times in the signal. While slightly simplistic, +reasoning about such a sound example demonstrates this. The same +principles then apply to images and other similar data. + + + ===== CNNs in more detail, building convolutional neural networks in Tensorflow and Keras ===== @@ -138,6 +613,7 @@ dataset of images, we require a 4D matrix or _tensor_. This tensor has the dimen !et +=== The MNIST dataset again === The MNIST dataset consists of grayscale images with a pixel size of $28\times 28$, meaning we require $28 \times 28 = 724$ weights to each @@ -183,6 +659,7 @@ small regions, and this serves as input to the next convolutional layer. +=== Systematic reduction === By systematically reducing the size of the input volume, through convolution and pooling, the network should create representations of @@ -194,7 +671,6 @@ then serves as input to the output layer, e.g. a softmax output for classification. - === Prerequisites: Collect and pre-process data === !bc pycod # import necessary packages @@ -240,7 +716,7 @@ plt.show() !ec -=== Importing Keras and Tensorflow === + !bc pycod from tensorflow.keras import datasets, layers, models from tensorflow.keras.layers import Input @@ -297,6 +773,7 @@ lmbd_vals = np.logspace(-5, 1, 7) !ec + !bc pycod CNN_keras = np.zeros((len(eta_vals), len(lmbd_vals)), dtype=object) @@ -316,8 +793,8 @@ for i, eta in enumerate(eta_vals): print() !ec +!split -=== Final visualization === !bc pycod # visual representation of grid search @@ -378,7 +855,6 @@ train_images, test_images = train_images / 255.0, test_images / 255.0 - To verify that the dataset looks correct, let's plot the first 25 images from the training set and display the class name below each image. !bc pycod @@ -399,7 +875,7 @@ plt.show() !ec -The 6 lines of code below define the convolutional base using a common pattern: a stack of Conv2D and MaxPooling2D layers. +The six lines of code below define the convolutional base using a common pattern: a stack of Conv2D and MaxPooling2D layers. As input, a CNN takes tensors of shape (image_height, image_width, color_channels), ignoring the batch size. If you are new to these dimensions, color_channels refers to (R,G,B). In this example, you will configure our CNN to process inputs of shape (32, 32, 3), which is the format of CIFAR images. You can do this by passing the argument input_shape to our first layer. @@ -420,6 +896,8 @@ You can see that the output of every Conv2D and MaxPooling2D layer is a 3D tenso + + To complete our model, you will feed the last output tensor from the convolutional base (of shape (4, 4, 64)) into one or more Dense layers to perform classification. Dense layers take vectors as input (which @@ -438,7 +916,6 @@ model.summary() !ec As you can see, our (4, 4, 64) outputs were flattened into vectors of shape (1024) before going through two Dense layers. -Compile and train the model. !bc pycod model.compile(optimizer='adam', @@ -450,7 +927,7 @@ history = model.fit(train_images, train_labels, epochs=10, !ec -Finally, we evaluate the model. + !bc pycod plt.plot(history.history['accuracy'], label='accuracy') @@ -468,99 +945,7 @@ print(test_acc) -===== Recurrent neural networks: Overarching view ===== - -Till now our focus has been, including convolutional neural networks -as well, on feedforward neural networks. The output or the activations -flow only in one direction, from the input layer to the output layer. - -A recurrent neural network (RNN) looks very much like a feedforward -neural network, except that it also has connections pointing -backward. - -RNNs are used to analyze time series data such as stock prices, and -tell you when to buy or sell. In autonomous driving systems, they can -anticipate car trajectories and help avoid accidents. More generally, -they can work on sequences of arbitrary lengths, rather than on -fixed-sized inputs like all the nets we have discussed so far. For -example, they can take sentences, documents, or audio samples as -input, making them extremely useful for natural language processing -systems such as automatic translation and speech-to-text. -=== A simple example === - -!bc pycod -# Start importing packages -import pandas as pd -import numpy as np -import matplotlib.pyplot as plt -import tensorflow as tf -from tensorflow.keras import datasets, layers, models -from tensorflow.keras.layers import Input -from tensorflow.keras.models import Model, Sequential -from tensorflow.keras.layers import Dense, SimpleRNN, LSTM, GRU -from tensorflow.keras import optimizers -from tensorflow.keras import regularizers -from tensorflow.keras.utils import to_categorical - - - -# convert into dataset matrix -def convertToMatrix(data, step): - X, Y =[], [] - for i in range(len(data)-step): - d=i+step - X.append(data[i:d,]) - Y.append(data[d,]) - return np.array(X), np.array(Y) - -step = 4 -N = 1000 -Tp = 800 - -t=np.arange(0,N) -x=np.sin(0.02*t)+2*np.random.rand(N) -df = pd.DataFrame(x) -df.head() - -plt.plot(df) -plt.show() - -values=df.values -train,test = values[0:Tp,:], values[Tp:N,:] - -# add step elements into train and test -test = np.append(test,np.repeat(test[-1,],step)) -train = np.append(train,np.repeat(train[-1,],step)) - -trainX,trainY =convertToMatrix(train,step) -testX,testY =convertToMatrix(test,step) -trainX = np.reshape(trainX, (trainX.shape[0], 1, trainX.shape[1])) -testX = np.reshape(testX, (testX.shape[0], 1, testX.shape[1])) - -model = Sequential() -model.add(SimpleRNN(units=32, input_shape=(1,step), activation="relu")) -model.add(Dense(8, activation="relu")) -model.add(Dense(1)) -model.compile(loss='mean_squared_error', optimizer='rmsprop') -model.summary() - -model.fit(trainX,trainY, epochs=100, batch_size=16, verbose=2) -trainPredict = model.predict(trainX) -testPredict= model.predict(testX) -predicted=np.concatenate((trainPredict,testPredict),axis=0) - -trainScore = model.evaluate(trainX, trainY, verbose=0) -print(trainScore) - -index = df.index.values -plt.plot(index,df) -plt.plot(index,predicted) -plt.axvline(df.index[Tp], c="r") -plt.show() -!ec - - diff --git a/doc/BookChapters/chapter13.do.txt b/doc/BookChapters/chapter13.do.txt new file mode 100644 index 000000000..42755dbf7 --- /dev/null +++ b/doc/BookChapters/chapter13.do.txt @@ -0,0 +1,1246 @@ +======= Recurrent neural networks: Overarching view ======= + +Till now our focus has been, including convolutional neural networks +as well, on feedforward neural networks. The output or the activations +flow only in one direction, from the input layer to the output layer. + +A recurrent neural network (RNN) looks very much like a feedforward +neural network, except that it also has connections pointing +backward. + +RNNs are used to analyze time series data such as stock prices, and +tell you when to buy or sell. In autonomous driving systems, they can +anticipate car trajectories and help avoid accidents. More generally, +they can work on sequences of arbitrary lengths, rather than on +fixed-sized inputs like all the nets we have discussed so far. For +example, they can take sentences, documents, or audio samples as +input, making them extremely useful for natural language processing +systems such as automatic translation and speech-to-text. + + + + +More to text to be added + + +===== A simple example ===== + +!bc pycod +# Start importing packages +import pandas as pd +import numpy as np +import matplotlib.pyplot as plt +import tensorflow as tf +from tensorflow.keras import datasets, layers, models +from tensorflow.keras.layers import Input +from tensorflow.keras.models import Model, Sequential +from tensorflow.keras.layers import Dense, SimpleRNN, LSTM, GRU +from tensorflow.keras import optimizers +from tensorflow.keras import regularizers +from tensorflow.keras.utils import to_categorical + + + +# convert into dataset matrix +def convertToMatrix(data, step): + X, Y =[], [] + for i in range(len(data)-step): + d=i+step + X.append(data[i:d,]) + Y.append(data[d,]) + return np.array(X), np.array(Y) + +step = 4 +N = 1000 +Tp = 800 + +t=np.arange(0,N) +x=np.sin(0.02*t)+2*np.random.rand(N) +df = pd.DataFrame(x) +df.head() + +plt.plot(df) +plt.show() + +values=df.values +train,test = values[0:Tp,:], values[Tp:N,:] + +# add step elements into train and test +test = np.append(test,np.repeat(test[-1,],step)) +train = np.append(train,np.repeat(train[-1,],step)) + +trainX,trainY =convertToMatrix(train,step) +testX,testY =convertToMatrix(test,step) +trainX = np.reshape(trainX, (trainX.shape[0], 1, trainX.shape[1])) +testX = np.reshape(testX, (testX.shape[0], 1, testX.shape[1])) + +model = Sequential() +model.add(SimpleRNN(units=32, input_shape=(1,step), activation="relu")) +model.add(Dense(8, activation="relu")) +model.add(Dense(1)) +model.compile(loss='mean_squared_error', optimizer='rmsprop') +model.summary() + +model.fit(trainX,trainY, epochs=100, batch_size=16, verbose=2) +trainPredict = model.predict(trainX) +testPredict= model.predict(testX) +predicted=np.concatenate((trainPredict,testPredict),axis=0) + +trainScore = model.evaluate(trainX, trainY, verbose=0) +print(trainScore) + +index = df.index.values +plt.plot(index,df) +plt.plot(index,predicted) +plt.axvline(df.index[Tp], c="r") +plt.show() +!ec + + + +===== An extrapolation example ===== + +The following code provides an example of how recurrent neural +networks can be used to extrapolate to unknown values of physics data +sets. Specifically, the data sets used in this program come from +a quantum mechanical many-body calculation of energies as functions of the number of particles. + + +!bc pycod + +# For matrices and calculations +import numpy as np +# For machine learning (backend for keras) +import tensorflow as tf +# User-friendly machine learning library +# Front end for TensorFlow +import tensorflow.keras +# Different methods from Keras needed to create an RNN +# This is not necessary but it shortened function calls +# that need to be used in the code. +from tensorflow.keras import datasets, layers, models +from tensorflow.keras.layers import Input +from tensorflow.keras import regularizers +from tensorflow.keras.models import Model, Sequential +from tensorflow.keras.layers import Dense, SimpleRNN, LSTM, GRU +# For timing the code +from timeit import default_timer as timer +# For plotting +import matplotlib.pyplot as plt + + +# The data set +datatype='VaryDimension' +X_tot = np.arange(2, 42, 2) +y_tot = np.array([-0.03077640549, -0.08336233266, -0.1446729567, -0.2116753732, -0.2830637392, -0.3581341341, -0.436462435, -0.5177783846, + -0.6019067271, -0.6887363571, -0.7782028952, -0.8702784034, -0.9649652536, -1.062292565, -1.16231451, + -1.265109911, -1.370782966, -1.479465113, -1.591317992, -1.70653767]) + +!ec + + +The way the recurrent neural networks are trained in this program +differs from how machine learning algorithms are usually trained. +Typically a machine learning algorithm is trained by learning the +relationship between the x data and the y data. In this program, the +recurrent neural network will be trained to recognize the relationship +in a sequence of y values. This is type of data formatting is +typically used time series forcasting, but it can also be used in any +extrapolation (time series forecasting is just a specific type of +extrapolation along the time axis). This method of data formatting +does not use the x data and assumes that the y data are evenly spaced. + +For a standard machine learning algorithm, the training data has the +form of (x,y) so the machine learning algorithm learns to assiciate a +y value with a given x value. This is useful when the test data has x +values within the same range as the training data. However, for this +application, the x values of the test data are outside of the x values +of the training data and the traditional method of training a machine +learning algorithm does not work as well. For this reason, the +recurrent neural network is trained on sequences of y values of the +form ((y1, y2), y3), so that the network is concerned with learning +the pattern of the y data and not the relation between the x and y +data. As long as the pattern of y data outside of the training region +stays relatively stable compared to what was inside the training +region, this method of training can produce accurate extrapolations to +y values far removed from the training data set. + + + +!bc pycod +# FORMAT_DATA +def format_data(data, length_of_sequence = 2): + """ + Inputs: + data(a numpy array): the data that will be the inputs to the recurrent neural + network + length_of_sequence (an int): the number of elements in one iteration of the + sequence patter. For a function approximator use length_of_sequence = 2. + Returns: + rnn_input (a 3D numpy array): the input data for the recurrent neural network. Its + dimensions are length of data - length of sequence, length of sequence, + dimnsion of data + rnn_output (a numpy array): the training data for the neural network + Formats data to be used in a recurrent neural network. + """ + + X, Y = [], [] + for i in range(len(data)-length_of_sequence): + # Get the next length_of_sequence elements + a = data[i:i+length_of_sequence] + # Get the element that immediately follows that + b = data[i+length_of_sequence] + # Reshape so that each data point is contained in its own array + a = np.reshape (a, (len(a), 1)) + X.append(a) + Y.append(b) + rnn_input = np.array(X) + rnn_output = np.array(Y) + + return rnn_input, rnn_output + + +# ## Defining the Recurrent Neural Network Using Keras +# +# The following method defines a simple recurrent neural network in keras consisting of one input layer, one hidden layer, and one output layer. + +def rnn(length_of_sequences, batch_size = None, stateful = False): + """ + Inputs: + length_of_sequences (an int): the number of y values in "x data". This is determined + when the data is formatted + batch_size (an int): Default value is None. See Keras documentation of SimpleRNN. + stateful (a boolean): Default value is False. See Keras documentation of SimpleRNN. + Returns: + model (a Keras model): The recurrent neural network that is built and compiled by this + method + Builds and compiles a recurrent neural network with one hidden layer and returns the model. + """ + # Number of neurons in the input and output layers + in_out_neurons = 1 + # Number of neurons in the hidden layer + hidden_neurons = 200 + # Define the input layer + inp = Input(batch_shape=(batch_size, + length_of_sequences, + in_out_neurons)) + # Define the hidden layer as a simple RNN layer with a set number of neurons and add it to + # the network immediately after the input layer + rnn = SimpleRNN(hidden_neurons, + return_sequences=False, + stateful = stateful, + name="RNN")(inp) + # Define the output layer as a dense neural network layer (standard neural network layer) + #and add it to the network immediately after the hidden layer. + dens = Dense(in_out_neurons,name="dense")(rnn) + # Create the machine learning model starting with the input layer and ending with the + # output layer + model = Model(inputs=[inp],outputs=[dens]) + # Compile the machine learning model using the mean squared error function as the loss + # function and an Adams optimizer. + model.compile(loss="mean_squared_error", optimizer="adam") + return model + +!ec + +!split +===== Predicting New Points With A Trained Recurrent Neural Network ===== + +!bc pycod +def test_rnn (x1, y_test, plot_min, plot_max): + """ + Inputs: + x1 (a list or numpy array): The complete x component of the data set + y_test (a list or numpy array): The complete y component of the data set + plot_min (an int or float): the smallest x value used in the training data + plot_max (an int or float): the largest x valye used in the training data + Returns: + None. + Uses a trained recurrent neural network model to predict future points in the + series. Computes the MSE of the predicted data set from the true data set, saves + the predicted data set to a csv file, and plots the predicted and true data sets w + while also displaying the data range used for training. + """ + # Add the training data as the first dim points in the predicted data array as these + # are known values. + y_pred = y_test[:dim].tolist() + # Generate the first input to the trained recurrent neural network using the last two + # points of the training data. Based on how the network was trained this means that it + # will predict the first point in the data set after the training data. All of the + # brackets are necessary for Tensorflow. + next_input = np.array([[[y_test[dim-2]], [y_test[dim-1]]]]) + # Save the very last point in the training data set. This will be used later. + last = [y_test[dim-1]] + + # Iterate until the complete data set is created. + for i in range (dim, len(y_test)): + # Predict the next point in the data set using the previous two points. + next = model.predict(next_input) + # Append just the number of the predicted data set + y_pred.append(next[0][0]) + # Create the input that will be used to predict the next data point in the data set. + next_input = np.array([[last, next[0]]], dtype=np.float64) + last = next + + # Print the mean squared error between the known data set and the predicted data set. + print('MSE: ', np.square(np.subtract(y_test, y_pred)).mean()) + # Save the predicted data set as a csv file for later use + name = datatype + 'Predicted'+str(dim)+'.csv' + np.savetxt(name, y_pred, delimiter=',') + # Plot the known data set and the predicted data set. The red box represents the region that was used + # for the training data. + fig, ax = plt.subplots() + ax.plot(x1, y_test, label="true", linewidth=3) + ax.plot(x1, y_pred, 'g-.',label="predicted", linewidth=4) + ax.legend() + # Created a red region to represent the points used in the training data. + ax.axvspan(plot_min, plot_max, alpha=0.25, color='red') + plt.show() + +# Check to make sure the data set is complete +assert len(X_tot) == len(y_tot) + +# This is the number of points that will be used in as the training data +dim=12 + +# Separate the training data from the whole data set +X_train = X_tot[:dim] +y_train = y_tot[:dim] + + +# Generate the training data for the RNN, using a sequence of 2 +rnn_input, rnn_training = format_data(y_train, 2) + + +# Create a recurrent neural network in Keras and produce a summary of the +# machine learning model +model = rnn(length_of_sequences = rnn_input.shape[1]) +model.summary() + +# Start the timer. Want to time training+testing +start = timer() +# Fit the model using the training data genenerated above using 150 training iterations and a 5% +# validation split. Setting verbose to True prints information about each training iteration. +hist = model.fit(rnn_input, rnn_training, batch_size=None, epochs=150, + verbose=True,validation_split=0.05) + +for label in ["loss","val_loss"]: + plt.plot(hist.history[label],label=label) + +plt.ylabel("loss") +plt.xlabel("epoch") +plt.title("The final validation loss: {}".format(hist.history["val_loss"][-1])) +plt.legend() +plt.show() + +# Use the trained neural network to predict more points of the data set +test_rnn(X_tot, y_tot, X_tot[0], X_tot[dim-1]) +# Stop the timer and calculate the total time needed. +end = timer() +print('Time: ', end-start) +!ec + + +Changing the size of the recurrent neural network and its parameters +can drastically change the results you get from the model. The below +code takes the simple recurrent neural network from above and adds a +second hidden layer, changes the number of neurons in the hidden +layer, and explicitly declares the activation function of the hidden +layers to be a sigmoid function. The loss function and optimizer can +also be changed but are kept the same as the above network. These +parameters can be tuned to provide the optimal result from the +network. For some ideas on how to improve the performance of a +"recurrent neural network":"https://danijar.com/tips-for-training-recurrent-neural-networks". + +!bc pycod +def rnn_2layers(length_of_sequences, batch_size = None, stateful = False): + """ + Inputs: + length_of_sequences (an int): the number of y values in "x data". This is determined + when the data is formatted + batch_size (an int): Default value is None. See Keras documentation of SimpleRNN. + stateful (a boolean): Default value is False. See Keras documentation of SimpleRNN. + Returns: + model (a Keras model): The recurrent neural network that is built and compiled by this + method + Builds and compiles a recurrent neural network with two hidden layers and returns the model. + """ + # Number of neurons in the input and output layers + in_out_neurons = 1 + # Number of neurons in the hidden layer, increased from the first network + hidden_neurons = 500 + # Define the input layer + inp = Input(batch_shape=(batch_size, + length_of_sequences, + in_out_neurons)) + # Create two hidden layers instead of one hidden layer. Explicitly set the activation + # function to be the sigmoid function (the default value is hyperbolic tangent) + rnn1 = SimpleRNN(hidden_neurons, + return_sequences=True, # This needs to be True if another hidden layer is to follow + stateful = stateful, activation = 'sigmoid', + name="RNN1")(inp) + rnn2 = SimpleRNN(hidden_neurons, + return_sequences=False, activation = 'sigmoid', + stateful = stateful, + name="RNN2")(rnn1) + # Define the output layer as a dense neural network layer (standard neural network layer) + #and add it to the network immediately after the hidden layer. + dens = Dense(in_out_neurons,name="dense")(rnn2) + # Create the machine learning model starting with the input layer and ending with the + # output layer + model = Model(inputs=[inp],outputs=[dens]) + # Compile the machine learning model using the mean squared error function as the loss + # function and an Adams optimizer. + model.compile(loss="mean_squared_error", optimizer="adam") + return model + +# Check to make sure the data set is complete +assert len(X_tot) == len(y_tot) + +# This is the number of points that will be used in as the training data +dim=12 + +# Separate the training data from the whole data set +X_train = X_tot[:dim] +y_train = y_tot[:dim] + + +# Generate the training data for the RNN, using a sequence of 2 +rnn_input, rnn_training = format_data(y_train, 2) + + +# Create a recurrent neural network in Keras and produce a summary of the +# machine learning model +model = rnn_2layers(length_of_sequences = 2) +model.summary() + +# Start the timer. Want to time training+testing +start = timer() +# Fit the model using the training data genenerated above using 150 training iterations and a 5% +# validation split. Setting verbose to True prints information about each training iteration. +hist = model.fit(rnn_input, rnn_training, batch_size=None, epochs=150, + verbose=True,validation_split=0.05) + + +# This section plots the training loss and the validation loss as a function of training iteration. +# This is not required for analyzing the couple cluster data but can help determine if the network is +# being overtrained. +for label in ["loss","val_loss"]: + plt.plot(hist.history[label],label=label) + +plt.ylabel("loss") +plt.xlabel("epoch") +plt.title("The final validation loss: {}".format(hist.history["val_loss"][-1])) +plt.legend() +plt.show() + +# Use the trained neural network to predict more points of the data set +test_rnn(X_tot, y_tot, X_tot[0], X_tot[dim-1]) +# Stop the timer and calculate the total time needed. +end = timer() +print('Time: ', end-start) +!ec + + +===== Other Types of Recurrent Neural Networks ===== + +Besides a simple recurrent neural network layer, there are two other +commonly used types of recurrent neural network layers: Long Short +Term Memory (LSTM) and Gated Recurrent Unit (GRU). For a short +introduction to these layers see URL:"https://medium.com/mindboard/lstm-vs-gru-experimental-comparison-955820c21e8b" +and URL:"https://medium.com/mindboard/lstm-vs-gru-experimental-comparison-955820c21e8b". + +The first network created below is similar to the previous network, +but it replaces the SimpleRNN layers with LSTM layers. The second +network below has two hidden layers made up of GRUs, which are +preceeded by two dense (feeddorward) neural network layers. These +dense layers "preprocess" the data before it reaches the recurrent +layers. This architecture has been shown to improve the performance +of recurrent neural networks (see the link above and also +URL:"https://arxiv.org/pdf/1807.02857.pdf". + +!bc pycod +def lstm_2layers(length_of_sequences, batch_size = None, stateful = False): + """ + Inputs: + length_of_sequences (an int): the number of y values in "x data". This is determined + when the data is formatted + batch_size (an int): Default value is None. See Keras documentation of SimpleRNN. + stateful (a boolean): Default value is False. See Keras documentation of SimpleRNN. + Returns: + model (a Keras model): The recurrent neural network that is built and compiled by this + method + Builds and compiles a recurrent neural network with two LSTM hidden layers and returns the model. + """ + # Number of neurons on the input/output layer and the number of neurons in the hidden layer + in_out_neurons = 1 + hidden_neurons = 250 + # Input Layer + inp = Input(batch_shape=(batch_size, + length_of_sequences, + in_out_neurons)) + # Hidden layers (in this case they are LSTM layers instead if SimpleRNN layers) + rnn= LSTM(hidden_neurons, + return_sequences=True, + stateful = stateful, + name="RNN", use_bias=True, activation='tanh')(inp) + rnn1 = LSTM(hidden_neurons, + return_sequences=False, + stateful = stateful, + name="RNN1", use_bias=True, activation='tanh')(rnn) + # Output layer + dens = Dense(in_out_neurons,name="dense")(rnn1) + # Define the midel + model = Model(inputs=[inp],outputs=[dens]) + # Compile the model + model.compile(loss='mean_squared_error', optimizer='adam') + # Return the model + return model + +def dnn2_gru2(length_of_sequences, batch_size = None, stateful = False): + """ + Inputs: + length_of_sequences (an int): the number of y values in "x data". This is determined + when the data is formatted + batch_size (an int): Default value is None. See Keras documentation of SimpleRNN. + stateful (a boolean): Default value is False. See Keras documentation of SimpleRNN. + Returns: + model (a Keras model): The recurrent neural network that is built and compiled by this + method + Builds and compiles a recurrent neural network with four hidden layers (two dense followed by + two GRU layers) and returns the model. + """ + # Number of neurons on the input/output layers and hidden layers + in_out_neurons = 1 + hidden_neurons = 250 + # Input layer + inp = Input(batch_shape=(batch_size, + length_of_sequences, + in_out_neurons)) + # Hidden Dense (feedforward) layers + dnn = Dense(hidden_neurons/2, activation='relu', name='dnn')(inp) + dnn1 = Dense(hidden_neurons/2, activation='relu', name='dnn1')(dnn) + # Hidden GRU layers + rnn1 = GRU(hidden_neurons, + return_sequences=True, + stateful = stateful, + name="RNN1", use_bias=True)(dnn1) + rnn = GRU(hidden_neurons, + return_sequences=False, + stateful = stateful, + name="RNN", use_bias=True)(rnn1) + # Output layer + dens = Dense(in_out_neurons,name="dense")(rnn) + # Define the model + model = Model(inputs=[inp],outputs=[dens]) + # Compile the mdoel + model.compile(loss='mean_squared_error', optimizer='adam') + # Return the model + return model + +# Check to make sure the data set is complete +assert len(X_tot) == len(y_tot) + +# This is the number of points that will be used in as the training data +dim=12 + +# Separate the training data from the whole data set +X_train = X_tot[:dim] +y_train = y_tot[:dim] + + +# Generate the training data for the RNN, using a sequence of 2 +rnn_input, rnn_training = format_data(y_train, 2) + + +# Create a recurrent neural network in Keras and produce a summary of the +# machine learning model +# Change the method name to reflect which network you want to use +model = dnn2_gru2(length_of_sequences = 2) +model.summary() + +# Start the timer. Want to time training+testing +start = timer() +# Fit the model using the training data genenerated above using 150 training iterations and a 5% +# validation split. Setting verbose to True prints information about each training iteration. +hist = model.fit(rnn_input, rnn_training, batch_size=None, epochs=150, + verbose=True,validation_split=0.05) + + +# This section plots the training loss and the validation loss as a function of training iteration. +# This is not required for analyzing the couple cluster data but can help determine if the network is +# being overtrained. +for label in ["loss","val_loss"]: + plt.plot(hist.history[label],label=label) + +plt.ylabel("loss") +plt.xlabel("epoch") +plt.title("The final validation loss: {}".format(hist.history["val_loss"][-1])) +plt.legend() +plt.show() + +# Use the trained neural network to predict more points of the data set +test_rnn(X_tot, y_tot, X_tot[0], X_tot[dim-1]) +# Stop the timer and calculate the total time needed. +end = timer() +print('Time: ', end-start) + + +# ### Training Recurrent Neural Networks in the Standard Way (i.e. learning the relationship between the X and Y data) +# +# Finally, comparing the performace of a recurrent neural network using the standard data formatting to the performance of the network with time sequence data formatting shows the benefit of this type of data formatting with extrapolation. + +# Check to make sure the data set is complete +assert len(X_tot) == len(y_tot) + +# This is the number of points that will be used in as the training data +dim=12 + +# Separate the training data from the whole data set +X_train = X_tot[:dim] +y_train = y_tot[:dim] + +# Reshape the data for Keras specifications +X_train = X_train.reshape((dim, 1)) +y_train = y_train.reshape((dim, 1)) + + +# Create a recurrent neural network in Keras and produce a summary of the +# machine learning model +# Set the sequence length to 1 for regular data formatting +model = rnn(length_of_sequences = 1) +model.summary() + +# Start the timer. Want to time training+testing +start = timer() +# Fit the model using the training data genenerated above using 150 training iterations and a 5% +# validation split. Setting verbose to True prints information about each training iteration. +hist = model.fit(X_train, y_train, batch_size=None, epochs=150, + verbose=True,validation_split=0.05) + + +# This section plots the training loss and the validation loss as a function of training iteration. +# This is not required for analyzing the couple cluster data but can help determine if the network is +# being overtrained. +for label in ["loss","val_loss"]: + plt.plot(hist.history[label],label=label) + +plt.ylabel("loss") +plt.xlabel("epoch") +plt.title("The final validation loss: {}".format(hist.history["val_loss"][-1])) +plt.legend() +plt.show() + +# Use the trained neural network to predict the remaining data points +X_pred = X_tot[dim:] +X_pred = X_pred.reshape((len(X_pred), 1)) +y_model = model.predict(X_pred) +y_pred = np.concatenate((y_tot[:dim], y_model.flatten())) + +# Plot the known data set and the predicted data set. The red box represents the region that was used +# for the training data. +fig, ax = plt.subplots() +ax.plot(X_tot, y_tot, label="true", linewidth=3) +ax.plot(X_tot, y_pred, 'g-.',label="predicted", linewidth=4) +ax.legend() +# Created a red region to represent the points used in the training data. +ax.axvspan(X_tot[0], X_tot[dim], alpha=0.25, color='red') +plt.show() + +# Stop the timer and calculate the total time needed. +end = timer() +print('Time: ', end-start) + +!ec + + + + + + +======= Generative Models ======= + +_Generative models_ describe a class of statistical models that are a contrast +to _discriminative models_. Informally we say that generative models can +generate new data instances while discriminative models discriminate between +different kinds of data instances. A generative model could generate new photos +of animals that look like 'real' animals while a discriminative model could tell +a dog from a cat. More formally, given a data set $x$ and a set of labels / +targets $y$. Generative models capture the joint probability $p(x, y)$, or +just $p(x)$ if there are no labels, while discriminative models capture the +conditional probability $p(y | x)$. Discriminative models generally try to draw +boundaries in the data space (often high dimensional), while generative models +try to model how data is placed throughout the space. + +_Note_: this material is thanks to Linus Ekstrøm. + +===== Generative Adversarial Networks ===== + +_Generative Adversarial Networks_ are a type of unsupervised machine learning +algorithm proposed by "Goodfellow et. al": "https://arxiv.org/pdf/1406.2661.pdf" +in 2014 (short and good article). + +The simplest formulation of +the model is based on a game theoretic approach, *zero sum game*, where we pit +two neural networks against one another. We define two rival networks, one +generator $g$, and one discriminator $d$. The generator directly produces +samples +!bt +\begin{equation} + x = g(z; \theta^{(g)}) +\end{equation} +!et + + +The discriminator attempts to distinguish between samples drawn from the +training data and samples drawn from the generator. In other words, it tries to +tell the difference between the fake data produced by $g$ and the actual data +samples we want to do prediction on. The discriminator outputs a probability +value given by + +!bt +\begin{equation} + d(x; \theta^{(d)}) +\end{equation} +!et + +indicating the probability that $x$ is a real training example rather than a +fake sample the generator has generated. The simplest way to formulate the +learning process in a generative adversarial network is a zero-sum game, in +which a function + +!bt +\begin{equation} + v(\theta^{(g)}, \theta^{(d)}) +\end{equation} +!et + +determines the reward for the discriminator, while the generator gets the +conjugate reward + +!bt +\begin{equation} + -v(\theta^{(g)}, \theta^{(d)}) +\end{equation} +!et + + + +During learning both of the networks maximize their own reward function, so that +the generator gets better and better at tricking the discriminator, while the +discriminator gets better and better at telling the difference between the fake +and real data. The generator and discriminator alternate on which one trains at +one time (i.e. for one epoch). In other words, we keep the generator constant +and train the discriminator, then we keep the discriminator constant to train +the generator and repeat. It is this back and forth dynamic which lets GANs +tackle otherwise intractable generative problems. As the generator improves with + training, the discriminator's performance gets worse because it cannot easily + tell the difference between real and fake. If the generator ends up succeeding + perfectly, the the discriminator will do no better than random guessing i.e. + 50\%. This progression in the training poses a problem for the convergence + criteria for GANs. The discriminator feedback gets less meaningful over time, + if we continue training after this point then the generator is effectively + training on junk data which can undo the learning up to that point. Therefore, + we stop training when the discriminator starts outputting $1/2$ everywhere. + + + +At convergence we have + +!bt +\begin{equation} + g^* = \underset{g}{\mathrm{argmin}}\hspace{2pt} + \underset{d}{\mathrm{max}}v(\theta^{(g)}, \theta^{(d)}) +\end{equation} +!et +The default choice for $v$ is +!bt +\begin{equation} + v(\theta^{(g)}, \theta^{(d)}) = \mathbb{E}_{x\sim p_\mathrm{data}}\log d(x) + + \mathbb{E}_{x\sim p_\mathrm{model}} + \log (1 - d(x)) +\end{equation} +!et +The main motivation for the design of GANs is that the learning process requires +neither approximate inference (variational autoencoders for example) nor +approximation of a partition function. In the case where +!bt +\begin{equation} + \underset{d}{\mathrm{max}}v(\theta^{(g)}, \theta^{(d)}) +\end{equation} +!et +is convex in $\theta^{(g)} then the procedure is guaranteed to converge and is +asymptotically consistent +( "Seth Lloyd on QuGANs": "https://arxiv.org/pdf/1804.09139.pdf" ). + + +This is in +general not the case and it is possible to get situations where the training +process never converges because the generator and discriminator chase one +another around in the parameter space indefinitely. A much deeper discussion on +the currently open research problem of GAN convergence is available +"here": "https://www.deeplearningbook.org/contents/generative_models.html". To +anyone interested in learning more about GANs it is a highly recommended read. +Direct quote: "In this best-performing formulation, the generator aims to +increase the log probability that the discriminator makes a mistake, rather than +aiming to decrease the log probability that the discriminator makes the correct +prediction." "Another interesting read": "https://arxiv.org/abs/1701.00160" + + + +===== Writing Our First Generative Adversarial Network ===== +Let us now move on to actually implementing a GAN in tensorflow. We will study +the performance of our GAN on the MNIST dataset. This code is based on and +adapted from the +"google tutorial": "https://www.tensorflow.org/tutorials/generative/dcgan" + +First we import our libraries + +!bc pycod +import os +import time +import numpy as np +import tensorflow as tf +import matplotlib.pyplot as plt +from tensorflow.keras import layers +from tensorflow.keras.utils import plot_model +!ec + +Next we define our hyperparameters and import our data the usual way + +!bc pycod +BUFFER_SIZE = 60000 +BATCH_SIZE = 256 +EPOCHS = 30 + +data = tf.keras.datasets.mnist.load_data() +(train_images, train_labels), (test_images, test_labels) = data +train_images = np.reshape(train_images, (train_images.shape[0], + 28, + 28, + 1)).astype('float32') + +# we normalize between -1 and 1 +train_images = (train_images - 127.5) / 127.5 +training_dataset = tf.data.Dataset.from_tensor_slices( + train_images).shuffle(BUFFER_SIZE).batch(BATCH_SIZE) +!ec + + +=== MNIST and GANs === + +Let's have a quick look + +!bc pycod +plt.imshow(train_images[0], cmap='Greys') +plt.show() +!ec + +Now we define our two models. This is where the 'magic' happens. There are a +huge amount of possible formulations for both models. A lot of engineering and +trial and error can be done here to try to produce better performing models. For +more advanced GANs this is by far the step where you can 'make or break' a +model. + +We start with the generator. As stated in the introductory text the generator +$g$ upsamples from a random sample to the shape of what we want to predict. In +our case we are trying to predict MNIST images ($28\times 28$ pixels). + +!bc pycod +def generator_model(): + """ + The generator uses upsampling layers tf.keras.layers.Conv2DTranspose() to + produce an image from a random seed. We start with a Dense layer taking this + random sample as an input and subsequently upsample through multiple + convolutional layers. + """ + + # we define our model + model = tf.keras.Sequential() + + + # adding our input layer. Dense means that every neuron is connected and + # the input shape is the shape of our random noise. The units need to match + # in some sense the upsampling strides to reach our desired output shape. + # we are using 100 random numbers as our seed + model.add(layers.Dense(units=7*7*BATCH_SIZE, + use_bias=False, + input_shape=(100, ))) + # we normalize the output form the Dense layer + model.add(layers.BatchNormalization()) + # and add an activation function to our 'layer'. LeakyReLU avoids vanishing + # gradient problem + model.add(layers.LeakyReLU()) + model.add(layers.Reshape((7, 7, BATCH_SIZE))) + assert model.output_shape == (None, 7, 7, BATCH_SIZE) + # even though we just added four keras layers we think of everything above + # as 'one' layer + + # next we add our upscaling convolutional layers + model.add(layers.Conv2DTranspose(filters=128, + kernel_size=(5, 5), + strides=(1, 1), + padding='same', + use_bias=False)) + model.add(layers.BatchNormalization()) + model.add(layers.LeakyReLU()) + assert model.output_shape == (None, 7, 7, 128) + + model.add(layers.Conv2DTranspose(filters=64, + kernel_size=(5, 5), + strides=(2, 2), + padding='same', + use_bias=False)) + model.add(layers.BatchNormalization()) + model.add(layers.LeakyReLU()) + assert model.output_shape == (None, 14, 14, 64) + + model.add(layers.Conv2DTranspose(filters=1, + kernel_size=(5, 5), + strides=(2, 2), + padding='same', + use_bias=False, + activation='tanh')) + assert model.output_shape == (None, 28, 28, 1) + + return model + +!ec + +And there we have our 'simple' generator model. Now we move on to defining our +discriminator model $d$, which is a convolutional neural network based image +classifier. + +!bc pycod +def discriminator_model(): + """ + The discriminator is a convolutional neural network based image classifier + """ + + # we define our model + model = tf.keras.Sequential() + model.add(layers.Conv2D(filters=64, + kernel_size=(5, 5), + strides=(2, 2), + padding='same', + input_shape=[28, 28, 1])) + model.add(layers.LeakyReLU()) + # adding a dropout layer as you do in conv-nets + model.add(layers.Dropout(0.3)) + + + model.add(layers.Conv2D(filters=128, + kernel_size=(5, 5), + strides=(2, 2), + padding='same')) + model.add(layers.LeakyReLU()) + # adding a dropout layer as you do in conv-nets + model.add(layers.Dropout(0.3)) + + model.add(layers.Flatten()) + model.add(layers.Dense(1)) + + return model +!ec + + + +Let us take a look at our models. + +!bc pycod +generator = generator_model() +plot_model(generator, show_shapes=True, rankdir='LR') +!ec + +!bc pycod +discriminator = discriminator_model() +plot_model(discriminator, show_shapes=True, rankdir='LR') +!ec + +Next we need a few helper objects we will use in training + +!bc pycod +cross_entropy = tf.keras.losses.BinaryCrossentropy(from_logits=True) +generator_optimizer = tf.keras.optimizers.Adam(1e-4) +discriminator_optimizer = tf.keras.optimizers.Adam(1e-4) +!ec + +The first object, *cross_entropy* is our loss function and the two others are +our optimizers. Notice we use the same learning rate for both $g$ and $d$. This +is because they need to improve their accuracy at approximately equal speeds to +get convergence (not necessarily exactly equal). Now we define our loss +functions + +!bc pycod +def generator_loss(fake_output): + loss = cross_entropy(tf.ones_like(fake_output), fake_output) + + return loss +!ec + +!bc pycod +def discriminator_loss(real_output, fake_output): + real_loss = cross_entropy(tf.ones_like(real_output), real_output) + fake_loss = cross_entropy(tf.zeros_liks(fake_output), fake_output) + total_loss = real_loss + fake_loss + + return total_loss +!ec + +Next we define a kind of seed to help us compare the learning process over +multiple training epochs. + +!bc pycod +noise_dimension = 100 +n_examples_to_generate = 16 +seed_images = tf.random.normal([n_examples_to_generate, noise_dimension]) +!ec + + +Now we have everything we need to define our training step, which we will apply +for every step in our training loop. Notice the @tf.function flag signifying +that the function is tensorflow 'compiled'. Removing this flag doubles the +computation time. + +!bc pycod +@tf.function +def train_step(images): + noise = tf.random.normal([BATCH_SIZE, noise_dimension]) + + with tf.GradientTape() as gen_tape, tf.GradientTape() as disc_tape: + generated_images = generator(noise, training=True) + + real_output = discriminator(images, training=True) + fake_output = discriminator(generated_images, training=True) + + gen_loss = generator_loss(fake_output) + disc_loss = discriminator_loss(real_output, fake_output) + + gradients_of_generator = gen_tape.gradient(gen_loss, + generator.trainable_variables) + gradients_of_discriminator = disc_tape.gradient(disc_loss, + discriminator.trainable_variables) + generator_optimizer.apply_gradients(zip(gradients_of_generator, + generator.trainable_variables)) + discriminator_optimizer.apply_gradients(zip(gradients_of_discriminator, + discriminator.trainable_variables)) + + return gen_loss, disc_loss +!ec + + +Next we define a helper function to produce an output over our training epochs +to see the predictive progression of our generator model. _Note_: I am including +this code here, but comment it out in the training loop. +!bc pycod +def generate_and_save_images(model, epoch, test_input): + # we're making inferences here + predictions = model(test_input, training=False) + + fig = plt.figure(figsize=(4, 4)) + + for i in range(predictions.shape[0]): + plt.subplot(4, 4, i+1) + plt.imshow(predictions[i, :, :, 0] * 127.5 + 127.5, cmap='gray') + plt.axis('off') + + plt.savefig(f'./images_from_seed_images/image_at_epoch_{str(epoch).zfill(3)}.png') + plt.close() + #plt.show() +!ec + + + +Setting up checkpoints to periodically save our model during training so that +everything is not lost even if the program were to somehow terminate while +training. + +!bc pycod +# Setting up checkpoints to save model during training +checkpoint_dir = './training_checkpoints' +checkpoint_prefix = os.path.join(checkpoint_dir, 'ckpt') +checkpoint = tf.train.Checkpoint(generator_optimizer=generator_optimizer, + discriminator_optimizer=discriminator_optimizer, + generator=generator, + discriminator=discriminator) +!ec + +Now we define our training loop + +!bc pycod +def train(dataset, epochs): + generator_loss_list = [] + discriminator_loss_list = [] + + for epoch in range(epochs): + start = time.time() + + for image_batch in dataset: + gen_loss, disc_loss = train_step(image_batch) + generator_loss_list.append(gen_loss.numpy()) + discriminator_loss_list.append(disc_loss.numpy()) + + #generate_and_save_images(generator, epoch + 1, seed_images) + + if (epoch + 1) % 15 == 0: + checkpoint.save(file_prefix=checkpoint_prefix) + + print(f'Time for epoch {epoch} is {time.time() - start}') + + #generate_and_save_images(generator, epochs, seed_images) + + loss_file = './data/lossfile.txt' + with open(loss_file, 'w') as outfile: + outfile.write(str(generator_loss_list)) + outfile.write('\n') + outfile.write('\n') + outfile.write(str(discriminator_loss_list)) + outfile.write('\n') + outfile.write('\n') +!ec + + +To train simply call this function. _Warning_: this might take a long time so +there is a folder of a pretrained network already included in the repository. + +!bc pycod +train(train_dataset, EPOCHS) +!ec + + +Now to avoid having to train and everything, which will take a while depending +on your computer setup we now load in the model which produced the above gif. + +!bc pycod +checkpoint.restore(tf.train.latest_checkpoint(checkpoint_dir)) +restored_generator = checkpoint.generator +restored_discriminator = checkpoint.discriminator + +print(restored_generator) +print(restored_discriminator) +!ec + + + +We have successfully loaded in our latest model. Let us now play around a bit +and see what kind of things we can learn about this model. Our generator takes +an array of 100 numbers. One idea can be to try to systematically change our +input. Let us try and see what we get + +!bc pycod +def generate_latent_points(number=100, scale_means=1, scale_stds=1): + latent_dim = 100 + means = scale_means * tf.linspace(-1, 1, num=latent_dim) + stds = scale_stds * tf.linspace(-1, 1, num=latent_dim) + latent_space_value_range = tf.random.normal([number, latent_dim], + means, + stds, + dtype=tf.float64) + + return latent_space_value_range + +def generate_images(latent_points): + # notice we set training to false because we are making inferences + generated_images = restored_generator.predict(latent_points) + + return generated_images +!ec + +!bc pycod +def plot_result(generated_images, number=100): + # obviously this assumes sqrt number is an int + fig, axs = plt.subplots(int(np.sqrt(number)), int(np.sqrt(number)), + figsize=(10, 10)) + + for i in range(int(np.sqrt(number))): + for j in range(int(np.sqrt(number))): + axs[i, j].imshow(generated_images[i*j], cmap='Greys') + axs[i, j].axis('off') + + plt.show() +!ec + +!bc pycod +generated_images = generate_images(generate_latent_points()) +plot_result(generated_images) +!ec + + +We see that the generator generates images that look like MNIST +numbers: $1, 4, 7, 9$. Let's try to tweak it a bit more to see if we are able +to generate a similar plot where we generate every MNIST number. Let us now try +to 'move' a bit around in the latent space. _Note_: decrease the plot number if +these following cells take too long to run on your computer. + +!bc pycod +plot_number = 225 + +generated_images = generate_images(generate_latent_points(number=plot_number, + scale_means=5, + scale_stds=1)) +plot_result(generated_images, number=plot_number) + +generated_images = generate_images(generate_latent_points(number=plot_number, + scale_means=-5, + scale_stds=1)) +plot_result(generated_images, number=plot_number) + +generated_images = generate_images(generate_latent_points(number=plot_number, + scale_means=1, + scale_stds=5)) +plot_result(generated_images, number=plot_number) +!ec + +Again, we have found something interesting. *Moving* around using our means +takes us from digit to digit, while *moving* around using our standard +deviations seem to increase the number of different digits! In the last image +above, we can barely make out every MNIST digit. Let us make on last plot using +this information by upping the standard deviation of our Gaussian noises. + +!bc pycod +plot_number = 400 +generated_images = generate_images(generate_latent_points(number=plot_number, + scale_means=1, + scale_stds=10)) +plot_result(generated_images, number=plot_number) +!ec +A pretty cool result! We see that our generator indeed has learned a +distribution which qualitatively looks a whole lot like the MNIST dataset. + + +Another interesting way to explore the latent space of our generator model is by +interpolating between the MNIST digits. This section is largely based on +"this excellent blogpost": "https://machinelearningmastery.com/how-to-interpolate-and-perform-vector-arithmetic-with-faces-using-a-generative-adversarial-network/" +by Jason Brownlee. + +So let us start by defining a function to interpolate between two points in the +latent space. + +!bc pycod +def interpolation(point_1, point_2, n_steps=10): + ratios = np.linspace(0, 1, num=n_steps) + vectors = [] + for i, ratio in enumerate(ratios): + vectors.append(((1.0 - ratio) * point_1 + ratio * point_2)) + + return tf.stack(vectors) +!ec + +Now we have all we need to do our interpolation analysis. + +!bc pycod +plot_number = 100 +latent_points = generate_latent_points(number=plot_number) +results = None +for i in range(0, 2*np.sqrt(plot_number), 2): + interpolated = interpolation(latent_points[i], latent_points[i+1]) + generated_images = generate_images(interpolated) + + if results is None: + results = generated_images + else: + results = tf.stack((results, generated_images)) + +plot_results(results, plot_number) +!ec + diff --git a/doc/BookChapters/chapteroptimization.do.txt b/doc/BookChapters/chapteroptimization.do.txt index 121e59113..d22d9ead4 100644 --- a/doc/BookChapters/chapteroptimization.do.txt +++ b/doc/BookChapters/chapteroptimization.do.txt @@ -922,7 +922,31 @@ plt.show() -===== Stochastic Gradient Descent ===== +===== Stochastic Gradient Descent (SGD) ===== + +In stochastic gradient descent, the extreme case is the case where we +have only one batch, that is we include the whole data set. + +This process is called Stochastic Gradient +Descent (SGD) (or also sometimes on-line gradient descent). This is +relatively less common to see because in practice due to vectorized +code optimizations it can be computationally much more efficient to +evaluate the gradient for 100 examples, than the gradient for one +example 100 times. Even though SGD technically refers to using a +single example at a time to evaluate the gradient, you will hear +people use the term SGD even when referring to mini-batch gradient +descent (i.e. mentions of MGD for “Minibatch Gradient Descent”, or BGD +for “Batch gradient descent” are rare to see), where it is usually +assumed that mini-batches are used. The size of the mini-batch is a +hyperparameter but it is not very common to cross-validate or bootstrap it. It is +usually based on memory constraints (if any), or set to some value, +e.g. 32, 64 or 128. We use powers of 2 in practice because many +vectorized operation implementations work faster when their inputs are +sized in powers of 2. + +In our notes with SGD we mean stochastic gradient descent with mini-batches. + + Stochastic gradient descent (SGD) and variants thereof address some of the shortcomings of the Gradient descent method discussed above. @@ -954,7 +978,6 @@ minibatches. We denote these minibatches by $B_k$ where $k=1,\cdots,n/M$. - As an example, suppose we have $10$ data points $(\mathbf{x}_1,\cdots, \mathbf{x}_{10})$ and we choose to have $M=5$ minibathces, then each minibatch contains two data points. In particular we have @@ -991,11 +1014,12 @@ minibathces (n/M) is commonly referred to as an epoch. Thus it is typical to choose a number of epochs and for each epoch iterate over the number of minibatches, as exemplified in the code below. + !bc pycod import numpy as np n = 100 #100 datapoints -M = 5 #size of each minibatch +M = 5 #size of each mini-batche m = int(n/M) #number of minibatches n_epochs = 10 #number of epochs @@ -1017,7 +1041,6 @@ cheaper since we sum over the datapoints in the $k-th$ minibatch and not all $n$ datapoints. - A natural question is when do we stop the search for a new minimum? One possibility is to compute the full gradient after a given number of epochs and check if the norm of the gradient is smaller than some @@ -1030,7 +1053,6 @@ compare the values of the cost function and keep the $\beta$ that gave the lowest value. - Another approach is to let the step length $\gamma_j$ depend on the number of epochs in such a way that it becomes very small after a reasonable time such that we do not move at all. @@ -1071,37 +1093,41 @@ print("gamma_j after %d epochs: %g" % (n_epochs,gamma_j)) !ec +We note that we have defined several hyperparameters. These are now the number of epochs, the number of mini-batches and the parameters $t_0$ and $t_1$. + + + === Program for stochastic gradient === !bc pycod # Importing various packages +# Importing various packages from math import exp, sqrt from random import random, seed import numpy as np import matplotlib.pyplot as plt -from sklearn.linear_model import SGDRegressor -m = 100 -x = 2*np.random.rand(m,1) -y = 4+3*x+np.random.randn(m,1) +n = 100 +x = 2*np.random.rand(n,1) +y = 4+3*x+np.random.randn(n,1) -X = np.c_[np.ones((m,1)), x] +X = np.c_[np.ones((n,1)), x] +XT_X = X.T @ X theta_linreg = np.linalg.inv(X.T @ X) @ (X.T @ y) print("Own inversion") print(theta_linreg) -sgdreg = SGDRegressor(max_iter = 50, penalty=None, eta0=0.1) -sgdreg.fit(x,y.ravel()) -print("sgdreg from scikit") -print(sgdreg.intercept_, sgdreg.coef_) - +# Hessian matrix +H = (2.0/n)* XT_X +EigValues, EigVectors = np.linalg.eig(H) +print(f"Eigenvalues of Hessian Matrix:{EigValues}") theta = np.random.randn(2,1) -eta = 0.1 +eta = 1.0/np.max(EigValues) Niterations = 1000 for iter in range(Niterations): - gradients = 2.0/m*X.T @ ((X @ theta)-y) + gradients = 2.0/n*X.T @ ((X @ theta)-y) theta -= eta*gradients print("theta from own gd") print(theta) @@ -1111,8 +1137,9 @@ Xnew = np.c_[np.ones((2,1)), xnew] ypredict = Xnew.dot(theta) ypredict2 = Xnew.dot(theta_linreg) - n_epochs = 50 +M = 5 #size of each minibatch +m = int(n/M) #number of minibatches t0, t1 = 5, 50 def learning_schedule(t): return t0/(t+t1) @@ -1120,16 +1147,20 @@ def learning_schedule(t): theta = np.random.randn(2,1) for epoch in range(n_epochs): +# Can you figure out a better way of setting up the contributions to each batch? for i in range(m): - random_index = np.random.randint(m) - xi = X[random_index:random_index+1] - yi = y[random_index:random_index+1] - gradients = 2 * xi.T @ ((xi @ theta)-yi) + random_index = M*np.random.randint(m) + xi = X[random_index:random_index+M] + yi = y[random_index:random_index+M] + gradients = (2.0/M)* xi.T @ ((xi @ theta)-yi) eta = learning_schedule(epoch*m+i) theta = theta - eta*gradients print("theta from own sdg") print(theta) + + + plt.plot(xnew, ypredict, "r-") plt.plot(xnew, ypredict2, "b-") plt.plot(x, y ,'ro') @@ -1142,6 +1173,13 @@ plt.show() !ec +In the above code, we have use replacement in setting up the +mini-batches. The discussion +"here":"https://sebastianraschka.com/faq/docs/sgd-methods.html" may be +useful. More material will be added later. + + + ===== Momentum based GD ===== The stochastic gradient descent (SGD) is almost always used with a @@ -1175,7 +1213,6 @@ earlier. An equivalent way of writing the updates is where we have defined $\Delta \boldsymbol{\theta}_{t}= \boldsymbol{\theta}_t-\boldsymbol{\theta}_{t-1}$. - Let us try to get more intuition from these equations. It is helpful to consider a simple physical analogy with a particle of mass $m$ moving in a viscous medium with drag coefficient $\mu$ and potential @@ -1205,7 +1242,6 @@ Rearranging this equation, we can rewrite this as !et - Notice that this equation is identical to previous one if we identify the position of the particle, $\mathbf{w}$, with the parameters $\boldsymbol{\theta}$. This allows us to identify the momentum @@ -1254,6 +1290,7 @@ One of the major advantages of NAG is that it allows for the use of a larger lea + In stochastic gradient descent, with and without momentum, we still have to specify a schedule for tuning the learning rates $\eta_t$ as a function of time. As discussed in the context of Newton's @@ -1272,10 +1309,9 @@ Hessians. Recently, a number of methods have been introduced that accomplish this by tracking not only the gradient, but also the second moment of -the gradient. These methods include AdaGrad, AdaDelta, RMS-Prop, and +the gradient. These methods include AdaGrad, AdaDelta, Root Mean Squared Propagation (RMS-Prop), and ADAM. - === RMS prop === In RMS prop, in addition to keeping a running average of the first @@ -1301,6 +1337,8 @@ directions where the norm of the gradient is consistently large. This greatly speeds up the convergence by allowing us to use a larger learning rate for flat directions. + + === ADAM optimizer === A related algorithm is the ADAM optimizer. In ADAM, we keep a running @@ -1359,6 +1397,7 @@ update rule for this parameter is given by * _Adaptive optimization methods don't always have good generalization._ Recent studies have shown that adaptive methods such as ADAM, RMSPorp, and AdaGrad tend to have poor generalization compared to SGD or SGD with momentum, particularly in the high-dimensional limit (i.e. the number of parameters exceeds the number of data points). Although it is not clear at this stage why these methods perform so well in training deep neural networks, simpler procedures like properly-tuned SGD may work as well or better in these applications. + ===== Automatic differentiation ===== "Automatic differentiation (AD)":"https://en.wikipedia.org/wiki/Automatic_differentiation", @@ -1540,7 +1579,6 @@ might be easier to work with, as the output is closer to what one could expect form a gradient-evaluting function. - !bc pycod import autograd.numpy as np from autograd import grad @@ -1581,7 +1619,6 @@ print("The computed derivative of f5 at x = %g is: %g"%(x,f5_grad(x))) !ec - !bc pycod import autograd.numpy as np from autograd import grad @@ -1654,21 +1691,21 @@ print("The analytical derivative of f7 at n = %d is: %g"%(n,f7_grad_analytical)) Note that if n is equal to zero or one, Autograd will give an error message. This message appears when the output is independent on input. -Autograd supports many features. However, there are some functions that are not supported (yet) by Autograd. +Autograd supports many features. However, there are some functions that is not supported (yet) by Autograd. -Assigning a value to the variable being differentiated with respect to is an example thereof. +Assigning a value to the variable being differentiated with respect to !bc pycod -#import autograd.numpy as np -#from autograd import grad -#def f8(x): # Assume x is an array -# x[2] = 3 -# return x*2 +import autograd.numpy as np +from autograd import grad +def f8(x): # Assume x is an array + x[2] = 3 + return x*2 -#f8_grad = grad(f8) +f8_grad = grad(f8) -#x = 8.4 +x = 8.4 -#print("The derivative of f8 is:",f8_grad(x)) +print("The derivative of f8 is:",f8_grad(x)) !ec Here, Autograd tells us that an 'ArrayBox' does not support item assignment. The item assignment is done when the program tries to assign x[2] to the value 3. However, Autograd has implemented the computation of the derivative such that this assignment is not possible. @@ -1718,10 +1755,186 @@ a /=b !ec -More examples will be added, in particular how to compare autograd with own codes for the gradients. + +===== Using Autograd with OLS ===== + +We conclude the part on optmization by showing how we can make codes +for linear regression and logistic regression using _autograd_. The +first example shows results with ordinary leats squares. + +!bc pycod +# Using Autograd to calculate gradients for OLS +from random import random, seed +import numpy as np +import autograd.numpy as np +import matplotlib.pyplot as plt +from autograd import grad + +def CostOLS(beta): + return (1.0/n)*np.sum((y-X @ beta)**2) + +n = 100 +x = 2*np.random.rand(n,1) +y = 4+3*x+np.random.randn(n,1) + +X = np.c_[np.ones((n,1)), x] +XT_X = X.T @ X +theta_linreg = np.linalg.pinv(XT_X) @ (X.T @ y) +print("Own inversion") +print(theta_linreg) +# Hessian matrix +H = (2.0/n)* XT_X +EigValues, EigVectors = np.linalg.eig(H) +print(f"Eigenvalues of Hessian Matrix:{EigValues}") + +theta = np.random.randn(2,1) +eta = 1.0/np.max(EigValues) +Niterations = 1000 +# define the gradient +training_gradient = grad(CostOLS) + +for iter in range(Niterations): + gradients = training_gradient(theta) + theta -= eta*gradients +print("theta from own gd") +print(theta) + +xnew = np.array([[0],[2]]) +Xnew = np.c_[np.ones((2,1)), xnew] +ypredict = Xnew.dot(theta) +ypredict2 = Xnew.dot(theta_linreg) + +plt.plot(xnew, ypredict, "r-") +plt.plot(xnew, ypredict2, "b-") +plt.plot(x, y ,'ro') +plt.axis([0,2.0,0, 15.0]) +plt.xlabel(r'$x$') +plt.ylabel(r'$y$') +plt.title(r'Random numbers ') +plt.show() + +!ec +=== Including Stochastic Gradient Descent with Autograd === +In this code we include the stochastic gradient descent approach discussed above. Note here that we specify which argument we are taking the derivative with respect to when using _autograd_. + +!bc pycod +# Using Autograd to calculate gradients using SGD +# OLS example +from random import random, seed +import numpy as np +import autograd.numpy as np +import matplotlib.pyplot as plt +from autograd import grad + +# Note change from previous example +def CostOLS(y,X,theta): + return np.sum((y-X @ theta)**2) + +n = 100 +x = 2*np.random.rand(n,1) +y = 4+3*x+np.random.randn(n,1) + +X = np.c_[np.ones((n,1)), x] +XT_X = X.T @ X +theta_linreg = np.linalg.pinv(XT_X) @ (X.T @ y) +print("Own inversion") +print(theta_linreg) +# Hessian matrix +H = (2.0/n)* XT_X +EigValues, EigVectors = np.linalg.eig(H) +print(f"Eigenvalues of Hessian Matrix:{EigValues}") + +theta = np.random.randn(2,1) +eta = 1.0/np.max(EigValues) +Niterations = 1000 + +# Note that we request the derivative wrt third argument (theta, 2 here) +training_gradient = grad(CostOLS,2) + +for iter in range(Niterations): + gradients = (1.0/n)*training_gradient(y, X, theta) + theta -= eta*gradients +print("theta from own gd") +print(theta) + +xnew = np.array([[0],[2]]) +Xnew = np.c_[np.ones((2,1)), xnew] +ypredict = Xnew.dot(theta) +ypredict2 = Xnew.dot(theta_linreg) + +plt.plot(xnew, ypredict, "r-") +plt.plot(xnew, ypredict2, "b-") +plt.plot(x, y ,'ro') +plt.axis([0,2.0,0, 15.0]) +plt.xlabel(r'$x$') +plt.ylabel(r'$y$') +plt.title(r'Random numbers ') +plt.show() + +n_epochs = 50 +M = 5 #size of each minibatch +m = int(n/M) #number of minibatches +t0, t1 = 5, 50 +def learning_schedule(t): + return t0/(t+t1) + +theta = np.random.randn(2,1) + +for epoch in range(n_epochs): +# Can you figure out a better way of setting up the contributions to each batch? + for i in range(m): + random_index = M*np.random.randint(m) + xi = X[random_index:random_index+M] + yi = y[random_index:random_index+M] + gradients = (1.0/M)*training_gradient(yi, xi, theta) + eta = learning_schedule(epoch*m+i) + theta = theta - eta*gradients +print("theta from own sdg") +print(theta) +!ec + + +=== And Logistic Regression === + +!bc pycod +import autograd.numpy as np +from autograd import grad + +def sigmoid(x): + return 0.5 * (np.tanh(x / 2.) + 1) + +def logistic_predictions(weights, inputs): + # Outputs probability of a label being true according to logistic model. + return sigmoid(np.dot(inputs, weights)) + +def training_loss(weights): + # Training loss is the negative log-likelihood of the training labels. + preds = logistic_predictions(weights, inputs) + label_probabilities = preds * targets + (1 - preds) * (1 - targets) + return -np.sum(np.log(label_probabilities)) + +# Build a toy dataset. +inputs = np.array([[0.52, 1.12, 0.77], + [0.88, -1.08, 0.15], + [0.52, 0.06, -1.30], + [0.74, -2.49, 1.39]]) +targets = np.array([True, True, False, True]) + +# Define a function that returns gradients of training loss using Autograd. +training_gradient_fun = grad(training_loss) + +# Optimize weights using gradient descent. +weights = np.array([0.0, 0.0, 0.0]) +print("Initial loss:", training_loss(weights)) +for i in range(100): + weights -= training_gradient_fun(weights) * 0.01 + +print("Trained loss:", training_loss(weights)) +!ec + diff --git a/doc/BookChapters/ipynb-chapter12-src.tar.gz b/doc/BookChapters/ipynb-chapter12-src.tar.gz index 4e69853b78e9fdcecaeab5899ee3a9ef4350aa4e..f43147c7ca2b70212ecda91e1e9f293d6610ebe9 100644 GIT binary patch literal 88086 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 literal 87846 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�RRz9;qn{7|{ z!ECY9-Ps!QUys=*;d`5j5CNa|s1W8Hnn5YSF-v<2AFI+;DVxq-#)4(?Hy%!ElgnEd__hSa`&IFGLnbK^fa z1^s7y`m<7p!RH>b#L^xf<-C}v8=*eXW<0S)_}m59IzLvvbxJ!U1JI|_&m`_I=T}Ku zrKDzZ`f7`iZySjN$zI&4GxxWquznoKUj_#mGVezQbr#y5AC(|Hi)fFUjsejQ_)wrF z72A_+w3`{2iqo_(x~ab*`A?CatEiE@x;gsqrsqPon2e zkwI%2ghrYf!H^3m=J<8GkK^EP{=P!(*K?OJqNGAZQ^#PmNcu)WB~5^s$4(HBxtd#vQg^}v2$Bl2{09pV!R;|_gXmmA)m=JfD)h_bqpZ(66sA1TNNwp#{eq1@fc9$ zO8Zwy{D-_ETh!J_>iRd~RhT+-cmbh6T~?W+BGIYnO7ZO9na2S87M5xU8!5?p(jSy+ zEafKk6RtlW+X1V^ChY`kn7z6#-0RDvyTdg2vHi)-gUK&6>!S~C!ZZ%UwyR|8{JcQ3 zK&R@LK@BYLw`@;`>AVfoS?ygr2Do!Vd*4e_eMuk!B@*p6Geu!M9LAaNzGr z^yVKCynEzsHOeK$8OBZ1d#dGZqtJZ#Tz>U0?mT5q5NXlfbo90DJQcA|mpXb&ms$>V zd^Fp(yMgUa!zMOHto!)`Y+ogz!P0THkKQw!3lD|G;aOx2UV~?8go_6 z0~2}=Fmgj$QCAI_`h}z(Dcxi#N9p|6LHNI_s@_-EXA%}1*VhS;w(iTFzVlGoKqd^Z zX~PVme)_rd1$^$Yexzx9N~&)^#dp;rH=7 zqs!vV;j~Iv&y{Gyexi@kj&}0Ye=1PlWiNJYa)F!(0PeO6Ln5L0I zoS(Y7WaNJMpV_&aWzz=UzS@4j$w?zue(-Pyrom5zX$!!P($;G8j11lJWpTbhz^Y6- zUrUmFNh{?mZwl*rTJd2W5hm^ya?#w8!V6zS!^oOHKL`lJk`e04`{{S30{RECbW}P97gO|INsDMKf8FL8r#VqlNII~qfaO-B>uqE4mt{Ui?1N^2 z4cn1fBX!O&xgUt2!wah*cDj(`oYI%pZ#gz606ywlex(HSQ}3=;;q(5h$%5OnjeyBA zIEVo3*<_8)2JEvNX3u z3d5t{YG-FQ)BRxMdS0!K@{LFfik)seAJ44|iI>Ye7=N0*L1-M6A=t@heX9+1YjxbU zK=*zN^uK}J`UoBD(+MB>f-)}z@=}LL%)#0whxo2l<;@TnaVp z=GNyp(`oZ)j51XF3!xZbPY6Cm86l{?dHr%uJc0iha4$DeuJ~E>tst)e5&wDKX@oQN z5ENEbNa~Aug^Wi8mm@N>pEO=M->;r#<-=Gt6LDkUGT0d>ag?G8v6+Qn7npgh3XcHTm3f!>to@+eDo_m7IYc5XS-`MJC)N+HIZ zCjW0o%qX`Q;$200v*mkJQOl-*Ke9Zo4><&%8sW_Nze{00k9 z$9k}=ss>*y={)O?pf&leCSSbA$qNiWuEHKVXIEy%mW_m#&si>0loa;e+&(-dBn6wl z4P$9SWz)=$0jIgBmLFCPi{Pd@-UPjdyiZPeYn>`aki(1ju{w`Essaa-+JkH@+{*r3 z22E{J-qdiqIvhT6-ZKC4WLv?<-YE>UF7$M9d_!pSNmcuELl}Xnn9kqVrznQFUBlV9 z-0pPUFWEa+@bw_z7~t=;+}~p!OKG6i1PNfSoY;zcT$)9L>=;_g2tD~c@%P%^ zH1GZrFbTEE4RGC9^ZbT=Sd?%%>i;9YzWq;pMg6b%`oB(1xSWZqT%H5fxU@c^Pa4+3 zT6JcI&e^Vfzfs6uYZePHrl3j8N!}EBVarW{l~;Zrs$RbuWp+acJ>#Kotn{4l@*;7v zJIxF|2OOg@lxYz5VCml*8R<=_DM7g2kXnYFJ7fCpyhC!IjSFXfEHdaMyfgE9 zB$0lp@&2meEmpUo+p2Hk$op^+vrD}<0OI>B8rqXnO7ww-Hl~z~?#U*MWEA9CME?yD-1&5PvF>+l>`wf4C_6^mB1q6Mp&vL(KA#uohlGv&O16ISGar&ssXxGqG9fe8kp zJ5PA3Ww!XpGBn^6}B5)vm9j*#{Qr3aNcd9pWl_FHC&+Y#w> zt;y@>4=V&s1E21E{6EGsV`}Qq|3f^}qIU|wNUeLy)1rp{9a1NQZb$yoRisG@^dsa6o6-hT?&rThRuawS7Fl(R{A9LN zmoYD#lq=v@qwndW?Q-SuozAp7&ok`*HM(;8cg|fZxD*#zW@>CVZmetm{Xfm7+l#bw zjJ*%3A{2FMMewy!N#7E1miSoA%VzrqK;SW;QiH-$7t8_!gv^Schho%-#{e{TYVxkP zcd1jB6Tw}`KydK(DTU_^FEshhw0*w+%%8cqR%P;HQJU|Y5>4z-e#n~y?FdYIGmUtf zEnU(;!Ne=_jSsWcd^+p(nN=>Ix)xB;B7z$^?b6&wQFzZ^N!sl7$SZJ&AZKdi{Jx&< zxma$sof#yyjrfw5;3%WyqW~^MTuRbg^u!KpA8R_ir z$d9&tBVprfQG$-YG4-!QnLm_SDJ*TsW4#KD*Ys}zB}gtsd24WLn~hJJi{U$bD*X?} zFQyA3Ocm)7=gv{bdO9uKg5dO@ga16v-q6-Ke1K3Q>vcL2#lWm0RK=;vGvI<&HkBQk z+?bSZhLG6p;!{FT?Rb`4{sJ-jw@I5xi07p=Rg!yjt&_F`V(9w&k3BCFFs|)PS-yY` z$^5`mO3JGixhF=%yTVKV4LXrIJm09BScnij@cG5c@*97w^*lnJrpC_MD4ijSC+$5$HWtsA)ZZDbj95>D!IIp)dv;;>;=S4bY$TE@AsxVA1N_g`d86 z2_`P9>_21l7&GmsXSSmy&xLm7Q77?NLc7$+PO9Zu^r!HIF+ctHDe+H_^kf-fIF_E- zM|Ao&9-G`*OI}D|b5B51mu*gv>E1(XRv2z1;1*-xkk=*U z%zR%(93WoWCU{g-1-|UW?MRm*`^6SHWw)hz6hq0^;{&Vj(H4iU)?}vmsK#+qX%s*}Y><%~BkuE1rq(a{O?tOkoTdbwLehz@DK$!6D%o;ACjA zhz4;Ay8=7O8nKVbKK=cp$;$xTmX=4Kq%;f6k!nstq6^MwgRixo8nXopFHo$m?HNJh zr`r(>VaguNhTbqBT?28!^}^VF(qg=it3vN-9<;;NLvGl!uh9cC?HVT^ z--BeA-~THTR`C+B9h)4q7h@T!E`IeB5}>8*y3(@?GmDa(wEG2kZQov?>bxKJT#Ngm z&R`peTENkEp41YCwk5LPaj@_2s_a>ZhJtU>_x>v zY74r9Hc!~UW~hgWUuK9b(|w7-#qiqMo5?JI2$~XyvH{D>Q}3Af)^o@z-Pb8#A*w!( z#hv;zlt-bxrqVts?z-u_Qvm~_D5j)8_&bRj_YTk$Zz=;GHC2YUNyim%bhJJB8n39B za5|GdAHD#+sF^7N(7?Pm@hEEf{8GB-P#y6Db1r>vJ^$Y+Eg_id5kW2It_Y2)_3)Tk( zu_h@WMR%@l0eZPp!!AfMAE3MFvZDxB{5r(?XWbc9!wdBDI(2`)xfyWpf%+r+B_bo_ zX8u#b7pOx?|2WlI?v(XYr*7iIAWMQ{-o0kce72Ok5(kru`sk#Ko0LmO6>fC4Ijj4M zXhmUGRT#6CRg?QyXqtWPOmL@_m%$d&oHOw4gZqY$bAA$02CBontAnziA%fH~1Cn^W z!l%#H>_I+w6R)iXJ6-xk$dPv#E6TNw&o5vAcE?xPEUp&IIs>l!Y|~S=Twkp9A48fhp3cgLK4Uwm^;%6P5f2o|v&B`t5SZM3UZAqNltL?@LZLx1{&J)!8_@^hI zC0Xpy49TUHL7$h?8}e{n1<&s)d8QSYulYqk^GqLs*iJp2cB)Ucz*zRUxSWkj7UaHg zAvsJI2mBBq(7PG-6OMt?%<T1id;Fi#|ve5^yOYdK3X~3yP?84&nujCK~l3WL^ts~mR$D{@< zjt}5pR)E_;Z17lxUIX? zsgQ?l;`r6exZi=#MX}wRpKE1bvt^K2lwXn>Io?DB*(_r+N>TQFf0M@5>eCgL78_Cw zM34_VQuIg5sRdn{GD+9^#&%~FCQZM(@7w!wdjQKvE(iB=!rk5<$~)&Xw`Q484T$U` zY%^EqFgn|{6y9c(zraoXVN&hy#${{GpN+wbJtouKDv*BX=2 zgvE#rpT@5|h?~Wzf|o~tD-7zp>MsHgBU&~8(iji#z!eAs3Tp_1k_Qa#(tSB@)O|}( zpp4K4!x~)bArqE+)-J8{O^m6YL}ZFSU%y$(3I-Y9{xaACjh?&IlmnxNN}e07D`LO@ zvJBLm!ZpYOH8Oi|jKR_jNecy^mo#lxjPLtaKEnj)dwosutClQ$aSHh;I2jzv`Uu=} zk#Y=B8A1vCm`yHi89M>kz7fulA9DoV@l!mjmzbZ&RXkTX_9NK#0+&SjJSvczp zf4zBI92Q&bbUHC;3ECoR!?d=0lA<)`XDA#pYO!{oG)B=OFRlmq+7mZ1%Jgkr(&t14 zpU@Z!yAik4?hvB&7c`4x8q21}-{Ql_4I}`eOv>u2o>?_KV{TvhSG+$9h}5l+f$dvB|`mWf%BPP-)VD}g&X`L^Pnxv%>0Jn`8cMC66H**^~3tMhevIYmzM1b zbk168EbiGsXwL{Ea-CC{@{>V+=B|HhaVUbPu~1|GYpc|&-G`{l%3D_}3`}esihtR- z9%|BFR#Oj2p=i2FjY)({f6KS&C$En3m${~FcYE;}Bhu#3z@6-ayLD38+L_sY&;Kto zpYr}Q^XY%|2sgrnXUpB`UH#%@%3VZ&63n1c2A_bXW106Q3{b&mV~{(g447)S$^zl+iwN0(RUG@lpTh09DB<20vRVoq4NxglS6y;yN%zyRI zhrdI!->ZF`M1;WTJ6Ddp{sp#X3yf#)cL4DC7wkQK=auRXMzqJHJY;2$GX z`{x<9z<-x(8%BLelj}T(SDfkR$se*#6jyVUDnr6Av7wK^hk$I%oK7O5%9}_szYW2oHZSnbYJ^aGxj|u94*5&by@(qOxH4T{ofA31f z-ygV=$Y*?GKq?==*czbUi^R0!^*h)_;t@_nLp5k?yg%nf)~LNL@lMw<#Q~z!X|aA( zGU722`Wj0zzGP-FTDz`~2XzQpiF{lAe(@9Gj2BqfIIkT26#N5D<0i3)Kt984&Mrzuetj7UA$EFe40U3LJKB+(O=y`!NKGI)c1asntJvBci(&U z2=y4yk*(N`Wp<|XlR1m9j+heWIRbBI=e%I=381Qk)o5vLTc{Pu`hu-8uJS4SZV-ZhEEL|*g zes*V0%B28bKGHB1dv{l|y7D|&&+CQ95cjuh!K_aHr;k3XnbzogyDDEvHDr%5;7*Kr zq%IM0=0YjzhmH&m(g&Fe#FtQ6iB#W_GoNbPNfFdBQJ zmB|-BZvtZ=FOl)Wbsdb3tqm@BJ0%M8x*stK2@V_sR?W03sX3I^qhhl)HDyO^&506T zRL|Ji51INjAhag-bRBY=^4b2uWVgq=|7ayk_VDK2?zZ@z)LQZ` z-u;qgbHz&y`bDW73^S?&I_1)F5)5ZQZ!P)NID^l(478EC%IUuAL%f+o#J`UMFpVRR z(}x3(yv8eri~j6+G(v4RM?(8$ixN6^l7PUIROC#uw7w}eTsxh1_vMYH6_W@-@iX9< zM)$J_R`b%ODj75QRV|@V&*IOU5vstX*|#``%^%E$e#TU2!S~R(R^XWvyM48;?0#yd zDz9V~gSexjPymYAcyBA^FP|c!F7k#Oj;{&3@x!IY})@Z+G~NRZWRBDK#0(!s;R*>rfMyVu5-r#Gf6IX zJBDNvqI~X`zQ=fM@(I1Fe42*Ch`q>6fTyXDz$=d5BL&yB2gFjRORgLwQe&X{IoMl&eCbio&#^UE-Wn-NRed z>(kvz@cRb7jr(qo1WnoFE(*?yv{+ht^e<{h0B@VC6;y{tU#YTK?P@*-#L+;$6GnL< z_kiEsPrz`Mmmm{c2b{|3`%2RzRTj@s6-`nfcL&NhlNn^kV`PXO$1U@1RIKk}5P;V5*7 zG%0${V<_~+J;vRBcbeZf**0~WJT<9k?x{W@N%(;Mt-0{X!{@ATc*cg_UUDy$8*_7g z-x7{*jF*Y-75;Y;#~w>%z~qTfI<&`%%hWcd9d=?YhN_V{PQa<$TnFhQjKRT}Wqd(? zDF4P9LW_{+j?U*BSJ02KFmZC_$F(p&V>lmtD_>(oZX9R!F=PnFPx(q!c~TIWIcA@- zqhkSDFe8gcv;~soQ^yduD=dyuKO=J9aa)4dx*0_khesGEv$fSqSF)>`>|Kk{+6V7b zEl$^uycHCUVX42GOX+nf<@>wO*9^*Yb< zeZ9`>Jiy{oNhm6B-+e<}oyR6xeWiB@jmTP|Q_~KP@^4t@eh$y=oj|XCdui13`tGn? z+QpM+%&kBC>!mjtMddeWQ+A;DTjID?`o04xcuJK^*`LRWO<$iIem1DJSBLEWw3@J( zcc>k;^oIX(;2)?LbHxigoN;SxnYYH9Tx74XSw0EF?D@HT zrS>Ilb7C-Ws&1!udkC%~ z&rlr%+HfcP@4L39bl4QY%0AbLD>Gyv^dQA;RyA*t{ucq=4?a8v+(l(L*n%}%FuJRA;(no?h)t(>Oh7rbj&iy z$3>;IpRWB9e5UCpiE>Ei+hhRlkLcHlKgEgNlCRx*%fZ8&((?Tt=SG=^nqhnt+lw-#54ZTfOhs3OW-X(=uZt;lKqg`_lXVy^9k%w`p_Oas zn66EOmZ&7jX?D?HGP7De<+fkW86M_XCa&+26C9##IL1@UyD3~EFFYuAHeJ{GKYbu> z-#Fma?A9N6TEB$AU!~=>tRR8omBaW?!T?H+JR3=_yF;#aI5W}~V4wKa)pwcLeYes2 zEajwV^wVutm~3}%KWHN-n5*UmDxJzjt|K5i5S(r0(7-mdK+8yxe4bvw!&1hOZ$*v| z6K`mR4#wb)A!>jUa|Fsm;E_}=Ff|}pXKQIvWXfOSxFm+$zC_C7%F^zP*u;RlP~)gG|cNqmMul2$D8}ybAe$KSK_e zB7m76h{mzKJv#!Ibe%Ma-?>N#bPKw##*_Y3*Zh(rUmW9}-l|_pAI$H}mY%#<*Lt%4 zO{t4*_c`^z@j>c`Hqg-dv{HQES+E$?&t!0i{MP2|Nbxr8*9lSP{VCD2-FLUK{M#I^ z7uE6_xsw}R>fj?d@DiF9y<2vpN8gNlO@S+7!SILf+XB|>j8*N@QnYnnR3n-ZrdS2Y zkzCr)ES2$6iMK}1)xIyfB0c4;5-B!&V=sLIyf91&> zz47o@Tfg!xGtE{V!#?=rc~sHX+-kPEEX4Ej8e~{uV9+?9U~#2_)D(*E&oktRKAD{)4=W>fss- zfAIn$jJ^cL8r9a21TZeuRhX0GFaw!XAt8uzk(CC;Wx0;I9B{&;!l}Y%Ru0Y=7JR)d zGl6zE1SUMjn{n+9TZ$8i2E>k(HNnF4*3vlbG-hjCmG4*u;{E6#GLV;}k&^`jUvTe>X@hd3FHoYJ!ci4p zEEp{GL5!f&KL4#>tnFpU`l)k$oSTovQF$ZPQx-Udj&4u@!*ntfV@~Tos}_ITN}|cD;Ee&J|%fCsgpPSp?NEa6C|Fh0ODW% z=LS^TG2OQl*~jK%v;J?s|2|+7Ul$ISS?Mc;)?p_7qN=yEZho=-mdm>O)38VV&{%J; zJUNCLmi`sdc9nj%^UE&;Ud*ZU2*maJQG_|3=$v{c@nE(5xcrj7$Q*$}d>*;6C#@lc z;TPA`ZfcbkWA)g%%(tc91d<)>hHL_j_LQ>i2ABY=LpJJJ;HEeKQp((v`<;hT8zwhx zodPdqci#GRORB}=x6LZ>pP<;v; z6)ZmJ)uH|ds0AQi z*c&hhAc7*lP}i0r956Q8KWSq-c2?cGvMF;)?_TQz+M2m1COd}2LtK^1gf6}DJ!gqMb6H#4aB)k{$4T?NqBU9=p5CmzTYj^Jji;{>`IJp*lV8# zk4_Y$o4O>STp2V7uTpD4E#Y{A>bU%Sg)_2*?>MZ+PX z{}N*EI`*TR1IY{=1!jJ7EpmOI9Q)`yH%BiXB50_%F2e}$x6kWpfE#6!w#%>H%%4aR z?R3CJ?*#F0TeX8HmzI{h?~pJAa6|#%Le^6&@WrywSnf-|FPglYwC(h+K2)6l4@o!m zo3N*^OQ~tW%kB*JW4)Jh^A5(3$HvWadqDCgyY1(Nf8O2RH_F6vjnaik@%2M=k#1SL zn;q)4`+@D>PCc?{@M36f`}+emqxKfb05nqaN6TuCAxEAr0w6@9t2fy@7N0kQG1A>3 z3}S%BVXodZJazbOrUIKu?a0pBqgSuo-y3i=o#K%)9|T>q?9PB41J-F|7oxI{I9^9u z`%OlK6;B>yhx)Qib`AYbs{As2z5lZE)t*{qohrOpS0X#?=`hD^xPR=A4e_tEDF^k?CT|91gD;cLPk(qAeefB$(fTaJk6H8{ zOZAWg1Yn~iHV^u&P=&}ZTcHjep$nl8rOv7oa^4()d{}o6>j!2a3V~Kp+SYkc(_Ui0 zILfJD%1P38DlFP;utJC`dxEx`iY|1~DV*k+p6ri5^SviGX)umoVwcJ4_cixE+d z(9=7wQp`$l-w_IXm){sNdW$j!Lt?)#p@RW$Qq>K>xhM#Erw->M`A%miN2o}5x$;1k zuDpfh>fR*mc-tS}o#*QlwRalNoPKOKf%X@`-z$@m&KC z8s->rdkR?oy&5=_KA|f{X2IaN0Xa$-$)u!_ED-E0^|118Xi%Z1?#nAeTK7~w|FE`e z3AUPsoQBH+fdm803||-gY_lzq&$5oMohHPkAKy)CxO@py!Q3QoqHbDhH((rBKbKG& zBU}E!@n3gszCRWqC2%cWL0U?U2bXoIVm(3Z#)#hcI{l91tH#oASl-;f;BfcHz+-TE zLDISSf}~U)z30z0K%4~`)VY*S2x%HotI!g?e&;dl9PmKuX5loVSK)z$G@tUp*HnEb z-q3V!&G1**AHFcx%)n$rU(<^3z(COQ}MQ;!@ zeV#U`^}Vwx0SCx;s=WiOt4s^63D0U%CO&K@I{gT=`aa}fcIjSnmBIUB*>!*Q2(&7+ z1+Q4aNWDqwsB3s;ZHZM;-R3@VrG6w>Q-^YR5mg8~Nw#fA@O?v%;G17#@3&5q6a8@AfdZE9?A-LZXhH|DNjQe z2O5alyC^mx0pYaQ2jcN8(An-v>=m-q{Ml4eW7{5Ga$I`K?PZI!G2DLv;;VYBdXT-z zQ0Ar^1Uq1gBtC0Y6Qux`g_@4B{R(8*^2mwTzoW7GM%j$_?P9p6xF`^t3m*fE$QP2& z=6mD=cWypRze}RzUMt85@AZ4~xh#b9Az$k~W}&_}pJj^R14u3(4?ed&gn+iE0QI3w z!x5;X{8yV?u?^2wI7{xOH(EsLY`fAG;p-p}L$H=rCe;NX?da&LgvrLS(P#(~W@e}5(DAw~Y=mV#@f4Y7e)SlWs zBUK?NRRjC$S^{KJu8%o=AItv7KL6Tz!X3_h7%yF+q0jhrVP_?vobw^g#G*#*8urom z9~J1jn2r8qNhER2DVIZ$}XRu6q#9LLQGM zi(t|wXWzln$N3VQnpE6p!~#k==Z-*--`GO&Bc^O(?nQ3Q{Oc3~}2Yx6_7_yu~%t|(qs5(F| zxm1au#NACg0%0l>-kO}+s87<7e$N+|Q2!M2hyO2*gU$d2<82Bu#AA6z&v=*E!w(h{ zy_;y$2NLGQ>tJ=NBO)479g*qI2IzxXpsz2et3_J+9@=5PNQgS}GpYM9BAeVWbapD+ zsIKH{SCIb2Zz>|zrw8ONTBW{gi@%DKVxk<79dZ%>))+1%YINE?o?k$kX#OtQ3t>Zf z@#M*Uo~(q^sfDZ>`HQHjHGE~uIx_GGbZYTSbxOOsZ^Kx@J&6lf_&)dv4O~k8xsYu- zlC^|h2CNBdN-+qICM5!g=FoagpBnC7+_|3)%9lIMa_<|z_h;gE`@P#NJkSxKN>BOH zT4xhPYf7uT44FxmxnExVC&Yl@pha)R@hGA})LUe(^)`ZAv61}7`B5q#!s|^#cvyJB zi-$YYr~F#!O4=?9LIYyPeJ1V|k6dRosx~KO^P2Lj|I1m4_Mz1sfn0%>=bK@}N1$gs zL1exT6WS;I=L_ezFJvtKbWnF(_!ju?Z%8K}@P%<188#ULv!%7bwW)g59Sv%s?jCp% z&F)JZncB4C+>W&0URs9eCYrgu*71_#0)ybESLkB(l6C=ewfWzsnWvqbKQPMlQEjh3 zYTMuz-(9!Z0RrGX8L`vk)!uCPoc}l~PPh63+@ar|Qra`4hq;+<_39m`e9xpb0?h(Q={9f-X)hJU)7!h%@L45%i;CMt~T?4 z2%h+nER*=UGF%FCv-qH?cwQwXN+9+&3x{m7R8 zZY$>hX$Q5TxP5x|;Ow{;Mqw46iXF1fSepy`f_|3BmKCcVp=X5WL;zGl8dADxm_C(+os`=>=2%QL6x!e|S zXZX**F4;K(vD@1^=*fMgNJVHIkGjz3!-I#8pWE)oj2YpFV(N z^Fau%ft%0vNLE*IL^RgF+V@l%4KZ5(+Fj!fsc=|Feibu;Yr$O1h{%}9`Lceb>)Ya9 z60P*&)_lU%_Fpyigo~eB0{uO7$>Jf%Y8>?pW4k>=Q|CY^T-cS+(NL4`ExK2J4hE_N*LD3_uaD!ZSs%LPx*Hw>TttLR1D^h*WlGFo+0Supfv*^+(tXIqh7p;kg@T7y z1-of5^_(wR{;3JybX@dZcUFT~?On*3^E%iF_cCn=eplUIVVo<~l^yo+A<0?yx~l%m=i6QD&6?&L*9($aUtI;Kdarr~B26)! zxS9cs!|9%J(i+#i+&afqio#e(K!Y1v_Iu5byBjqLX4l>X5fZ(*I;=h#9X@)gd)YS>--2oO?vyvO zXlXF3vbnfB^Rv6^jOr9{mGTU5pL0xf#>d+BrY;k0J{~^&v@5dp6)|(7S&!%G?OXSv z@=t%g4B9!vu(cPB=72o`_FVYu5>*|zpbq-H{;|b>tjk8p-!}x8UAu*>{g)-1a2?31 zCL{yQL?B9AFGszTi?LJqTV?4lvA$q%$57;C4|BkxSy1Yp-MN2-D12dz1`Nuf;11n0 zG25-K#WxGp7~7tlXn%^>_!)enYHX>roQ*PZXkHvDoNB1+x>FHe z(IRGiW+m((XqvEr%&4KCp%0&h%Z*L7XDd~But1lXd43h!EglQQM~`*~?iDPAsHKSx zve=Q+@#5*^l(vx|xQ|(ggSrDkx@R zE1`~lf4{V{@aEDlbg}L-sqa;6_$)xGS=#*3lCG41BT(c8`fu`V1dOJ9p!Vlk+d%U2 zAZ6f2kWeMV+Sth>5EVL&z^c(LmT(O8s~EBiX5@CzsS$1KLiLH7AcZ!on0vnIr~OYG zY9m;g#6Rh#AdVkd9lYDulKRl^MxeOPF+5DOvDh|0| zSApDbbx{i6HmCygeM=Tt*cHgcg>4ABhq*n-mLb8c@9{L41@RKaAZZI|QBvHWcRu0) z$G-iz;XIYJRXr@ffqNXfgE|YnR1qMT9p=d$xB`!~(jlOt?1ca){8W5kXTxq})QH9%VB}H+*Iy6MaJbJfiAl3wTG2vn|~X9i7uYytlx2`ZC0TUm)@b zBc+%w9i0?j;GF)!AP$K7Y%L%sRo7 zeBF?`rCh%`t}t!~=!3Zt%~~wgFOVU|&Qvk+WaVY1i$W*iWG0ra(NvEDT|t;KX|L@F z#N?XIM{0gwF)Yvb@}gF@zKnuY9a)RlNSEs9Xr))=>T7cW>G7o4M(>H!>ktih_ot8M zqYZ9b+ygNVT70F*J|XD&xtugE&)+&No7eE$m369DNQPBVn>jza{oR-bA9?rbtWqok_Wmmc&@Mw8{C~b zNry8pNn4U}JoJR(BJWYZSDYuB1C*j5&ry-O(xjQRSRZ`j3w&j;?UbD@e052cF?2~u z-g}_$y^(Z+$zuRais+r&43!*ldg4?1ILWhQl_jk{Ygbd7C?vsEvTE|?2*gjmk<%-vgb#-VYB0;)Q zB$Nv!n5YTUQ(Q|YMd!7?gc4;MvcCp(ae!R^;A~&|CfQj}-}ZC6w2=T6y{56tt|3{B z`mBU-Cc5Ei(;4aQ5FvZ$Yke);?a{31M?FEBObJ?*^~+xhs%b^k+oYu>1<3qn$i|LB z_tUk8`=8bebPG;+u5DF`!&h>+@?}wqScvODgw5G^;^lOOilzvQ-FgkB&JZ;t0+c4(Xja|cU1uMc&HK+b!1n_m~-o^Lt3V$U)B3{7S( zb}jq^(o5dDp8Ml4NBq$tdx`^JUEJ&H#OQ$Hs1}z#uvPQ0uuPCm-@4#mFAb(8)t^$K z?_1>=3bzphEG#+E}5ty+L^R2JWbLMgVlo8gHv5^piQE$cCRavZu?#AEVY_8qw6*g+7Ly~bm zj1l)(yK&OOyPHwqD)lg!0cpvBbLE-^G7_aQFsX7l^@#F|zdbSaGku$JFxjYE=lVB~ zScem;T1q_X9ZC^=Mezg;uRTkt6H^cEzm+$u*R?Rsk#MR$;FEA|SL9ju;_vnEsv!cd z`z8iA8}^;!-(i#)dljMD&SoqX5<Qu=>YY1MD&4G zC+?&*G}72H&%APJwAOyok$Gk6Z&v6uci=w$8P7J9wP6 zFHphq=TFyyj(M|?q0~6qtCkk&(-NUxX$Rv6`sN2B2Cw=f|7;n0d{cLUtbY0cE{)U) za_cC4mu2^NHSvbv$ClWeJI`aNKqRK6wmFX1_BOe<-Ku0*E3^4D{|9!4A$QMid++T1 zuj;refo`Q3*9GbWT7l|e*_AGtVd}+K8LzwxMhXkd`VgOk(ia4(LtH_o& z6OsP18|-C0q3=>nO1q7BZFWe2s>!yQrI$tdQkhstj4aA<;q-rcbbSI6!&(;XDvv;K zkL$L6({BU`TY~*BEyr(WH7;Mxp}1x~TAo+=y(X?#wPT%M%6v4%p6Bn`&*Q4{9hbiR zE23Q!*d!=L=_*2FmRlW8{SiYpj=`*tK#G*;!Klneaee$RI(Rd#%&cSf60J;CD_)?z z@-g6o593v_Iv`v$+LeFf6o+_w5FpxeFLej}u8Ad=szD;6qw$BQ*5%JFgbVqLG&cG? z*H{e#t$=daxxyePcep|uq-_2sWtJHemeFJ7%&!%ZCDN3~JLau>(kZy1|8Y7E)jqG-FG7aA+s`v17euF8<=;kym~mGyB-3y$`wl@?{r^3)g zVjcbw)#XqcWqH?j9jYmofI8CjBf1R5I;hCoz4d)t$b^%D=CcDFZ>7Fsar>S;TXd`B?vmJ3s2 zQzx7(%KpaF!3en84(5AsGuC8qeJ2s*%FZanDj?vs417YrsyG4#&%N!`nsaCcv#%l< zv>A>-tcven*Zg{`WwfzTkUBiqD{Z_k_93L>Y`5m$*}BB_3AY00rYrL^ftYgB8{MAh zD@Py(5hJRJSC40a)O2xVsX+g3i;K%Xyr?)F@?1ftLtLT?A-vYm61(_ZD|sHD7Zt}B z%plJ)6drUD501#@Cy73RLGUz)(JOc5sn$G8FcC8A(UGyAd4n|2HNde-S-wrykDtF0 zw*O|emj2*M+v-D?;!^CZ7E!no^e)3ZDs&r{bBNUytKW_s)ki<+9t(FfbMF_mF@8Bz z``Ii{7R5Mx1adcv9G<47+ay|(Y6cI7R%L;8 zdu+9l8LjH6$WEClU*-SAN|p1?*R>(oVNZrn7B#xW{&;t&Sm+U6Ukh2U^IR>KIB;QZ zY>;JK(gH_iU!#56zz?I(70~5LSDx?}$GCGhjbk({vV3$Jk`WC9aaKe2;$-pk`95)+ z#SkiIw0bRkhQG5h!gBY3XE5}q&dV8Md~KntYS~Pam1WgMBgfB-`6a7DW=!Cl4%dLl zIhPn+4mSZ^SwQQpNkROQ15}sTYdg)kBx%Mn_>8At1grphK@9+$zd-{#xT%jwOo7^F zMJVdsbv`X0t$WOK4}+FYU-LPq2Uac*Qo>_9X2A2fU@03+9`-Ijz`zK@w<{EMxPq0Nr zW%Jb}6WS(Awx|Yqt;~P!@ahf;u4rmfq~nN))Uv@()8-GW?Vk5`T(c-IEbgyUvyzpL zdAQPg1d{rb&{dAb76+N*!_QdtI-EHIy}$`ljet~0+rY$D7l%hz(g{^0@3iCJ17R08 z-suP*nXC|o{Tq#oR+mzpjJ1aqxxIZ28mRg}%N#1q<|Pi=-7)DGIrrwSoBw6rI|=B= zPKwJDdMG3cGFQ;Tv8gB%+MX>+E>5tyny7wjC_47b+S0Y}Yc!nk?hz>D2t+bLMZ(#d z%y_8=$%r^z-OS~NF{?+4ae%VR9uK|Mb0_u8x(|EV>N^0&s_?slou6X?RVS zyJlE*{5%1>bMmbE(65Q!oD=sUfAfA6iu&B5EqXSoh<7#flPRV14l%gz;3#<&RLr&b zfevKIUKN`gSj2!&m6Fy$t(Z|XlJFj_kZ=}!?*z74Ip|D`QYketyW1FX1Tt-kcByNq zeM9aQVK0^AJSDM87~bUHc>4Y8{M*{yt&$U|+|)zRUl!+AtPi$6iZN4q1z zyxMiVfTQ9ovcdRWHvT%x=ZUSvh>A9H=KMA2cIQcX7;BCY*rcx6G0E_!vP+7#BR|t& zxF}I`P1S=J$fVSaZKx=n{^gCwg;Tct10sI>yzhQT%qfbem9nD=&*kcWx;*gUle^Qu ztdA`Ok68FQ06(vVWT47q{`?-bKCb;3GIl-kYkTXK=_w|!X=1C$8Ww#9CP_L*2pp$k zYVH)BOu||X2fH*NHnjrSvy}9*uO<6x^UVbb;Bk=(Z*@*|%BviDwkyf62Q*eJe%!lI z?Gx`|Mxr1U=p{iO#n!j3p6?tj6@95Q5yju}R=`y#q~y5-NZE+!06A7xHJ^(rO77&r zu9B8=2{X^03FXA+RmFap?$pbK<}~G5spBU#cjImjn|yRJ7(pve?BDM9UK{WN~L}yEQ%&vKOed07S}KYSAzxC zC5xF8;R1m1qH%Mc(r1Kcb@4vb?!+qmO}CQjucTWVl$jN{dRYmSt+czfx< zZ|lQ!+c?H$Ncl-DGgjtTMALt|mza#Q@*zt3!^U(>g_)#~>gP5d{hQaDjv*146* zEXbKARRPG8QLgka`q?oHi;WE15L51ZEW;MZGb4;a-*&5gq1mXB-gE)}9mE?9b_MEsXe#UM3>+&b3lSTy;~|SJp1c z<+JDuSw47g@Fj;!08k}U9C%i@0J-k7PXFBE)1y-z`pT*m(Q9aS_x;sszNDT77Y_jf zO?i{@1o(*Keyinwfh691sdJt~nW6Jr0ktY;UD-%{F+F}Q(F*7z-MkHS7U^v#)fIcALf!mBUElx`89@A< zF3#8Dhs0#WEpNPj(!i{9HH+O>TJ#C9+i;*Qnv$2i;%_lxA#z%_T#5khGGm9al2maq zRO{kC1!U$ymwVe9*+W{t$0;u)U%YMf@d zZvvx{`6xTbig;=F+XeE|wS$b>feI-6Y_t1Bmv$#@*1Jo6dGf~*h><=3;cs~j5UJ*5 zmxnEYD=Ce@=bFtr4DM|j&6Scn|2ynWfxDDfvc7MDKPP+yFgetKDFZ@JI8g7X`~@ot z!r|&kwvmk~aj-qEPhdJzS5wRnn!AbEAjT(CSKa}TeV!S}H{;sEqATn0_vcrlZ-X!q zw4-f^VW}8UEyQmEvde8mv-@_C$C>sd9kR5)`1#>%UQMYKp7*kITZa4x{Eu{%Nn8x{DR(Y5L*%Hs}F(Yk<=% ztvl9SUZumS0Y>1_zU9q`PWxKOiYJXVnT#Z9lFtOQNDAJ5)f zWDe)X#(Vgz^c#P8tZI`#^CB;1L$kfv;D7t}?CosCRRC-bRfHrK-e1t?|MhXHLPE-G zZ=I114Ul(@cd)IfOMR>Ea|qxzx`u&y3=)sgjmCvXMJlQea66n&jnih|+Cp>k2$WuF zYXv_DWJAy8xCzDycBD;8D)PU4`QE+Z|=I{IFJD)umsQg&^ zB_NqgoN8w-U9#;8Kl5J!U&mX92f-MI1Ac$^|x=?^A`XWGRYx#qFas&!< zCYaUIN`D`kt{;Jz+o}ZV+xKC20qhaz^xC{qFjbBgPs=@K-X^_MG!)U^YQndYef`fA z{RngyW&8tMtkLcnU{cUD-|D4Q7zu;V*VLLv#}Xm0xL9Uvp`3SmiE3<7D!u1Qx{56#Ut#(=t$5x% zBECYV&o;--rxR~;wGnOGC~#@g=<$rX|IwKl3|YCOko7fZ|Ma^nasubnUz_&_Se=&- z(!BAYWTV`LKY#x%&Hz3svz&<%94!%gk?ZcW<}vnn#;s!GgH`_n_;^E0_-mCzlo(ZU zya|lY{LAF&#`~BpQNC_w+v!x1uBJrtv?ycD23n2k9gAm<#FyRYxab3@Hs6pF?6KRw z^mX--p@`FlpqNH~0M@u;*wYK$r|@~iT{>gNo^a47XKXbj*DO9m#pbU1a4asOKf9`q zjgqHqZ-g&oxSWd0PkxjQ5-+Nxy3Q*Bx3t0KZY?f{4ix7PSfmTC>i5=Q?aUvI{wrCc z0apD-ptEpgH!x4jv&=-^zu8j&Hq7$@hf(&9{QNbjPyg_(gRt zrP%abX|CC>>shlJdby+K9cL4}hG@r9hjz+i%N_xV#6 z6B0B=T8CZOX+~`m>COX80PYqLi!Zf9V6ZKd!ncP!Il4cPUr%=0F8WvsI!h%@*10Vs zCT?~LdxW$+D-*FBSG--6>6o4}a7Cy+_EP}o!Vbts`g92w(T>0oXyWdMft>WAxnQ0N zM9^(3*i$6v=cDu&BM%Ek?+6%YBx;Qn?3hf_(<^r`7e?PNWF4Kg<39o^Snqu1C(H`d z^5tPZBo|vUF5<20=0*-#Q9PU z-Jj`0Dd$U4eqT2HW-;Q+{6=q?QHq6sNcekJz2wF^^4EGF!6s|p-+r&I7tvVpXUN`q z4xI2F*zUI18a_8XJfcU+-@ocsIYX^7zS`s;2)fq@R%jwIbZfuCP^!nM4}1dEF}Uza zT>M)RBVn1bjw6tBf~7tB{>MKpd z3-kx;o7)GHya~@E$wJw%XDwL#Z|2(&s4r7eR9&Xda>bINo?+&^b7~yhMJk-Iu8rl z1(~R#oUaZB#RC<)I{c}4yQc_lz{Pk>@s;#&xstonk3gYJB?f1XiUbxZ4Q+F~GV6&< zePhr2wpT4;=sP7{h<_HJIuz{etjQ!ECcIxakHRQ$5d?x&k*A;$xPjqajk~X{MCLtv48wMu z9Ro$ytLQ+g1}MQ zHWcD9d#vR-abI03*U>syW4|eJGlqhk+@|~_f)>xGeP_A`4qxy7EN4tL zkY6oO?raofT=H%|0`Vy&(|f=mA7sS%v$=_jrdNIyo8CAwd3q1XGn6tU+)hwousGu=D+W4qAY0D3YU1(ldBg#!{vKgR zpoJ%u$J73=!xQ61S*pyy5~RaET;aj(k=c*ap!Bl;+RBQ@EPZZ;Naql)f0js8QcmRom)**Bi7so3-?y^1H<&k@Fu;36 z*HxqW>%ONp7#01bOu=Kql;~QI)2YfjxQN!{fy>MzVzkx1dVM!hpFDT)>VaT4R)t~5 zgnzqru;s-7bDEnOH`J~BY;Suff@NY!ihhC{{@N9S&(oCx9-bs4+WH)r6mX{toCz|EKC&3)57yHn;eqR9J6|pkT z(xo+xq#C(+^Kd*@bV`cu24C=#WBjSXB+6s*`U0$^ z=p_pUM%Ff`<;+r5vCp;@UMI!HI?1sU-t<3A{LP-AH&6t%nqQ7QhA!fr>%)q0tilJ$ z2VPuQ9t$F>jaG$FYaa+6n5nO|@st{ArcC zN^5j>Qdi`h14I4*S*AN3F(Itn-m24(#p*IZBC>-#@CuE9Ns!2)JpDIal$J(6I{|gL zeYm!%K-QyUQ^X#HETpQ8IFcyI z-!4lvWI-|rqj7d6lqBy#E8JLb%-7Y2K}j`&UV8rFXUrcz#~*KgW=JemDj#}?5k^MB zZWgs2L*oYycRy#Z#{4w3Rj%SMQtz)zgq(y2!uaaO5YMdgiwS&BDv3L89 zW}8UMHK<1*)LI3`_;b3} zzIZ3;u+0xwtzTATGc#p^M~2rvwsC#`IT`nrQ=L2DnGdzn3$yCL4aFYss*~DUZXRD& zg%Ob|Q_$Ke>kEwhV)@ZteE{Qt%{~TmEwU3Clkwr~tawc%9-XlAv#u^0z1G_XmUNQq zHWd)UmyS1a9LfOd78Zk8qHxOmFvA zI@AL;=X-1F+7nOqWCZdScVtV5KV%zq7SPb>E(Jd<4S=lY%*u>D8P~l8d_4kn3ny>Y z%1P-t^XT08I!B<*gpLXyaQsJe$LgZm)oLzIS9|_{LSllhVeeEVZcP18NX+4Q{J&HG zGxu1O2&f40vp~8N#esJvts(DS&G{tXUcn>K)7u!Ox!cetWYuOOobT#msw}yn(zWN# zG3=?MkZO$6VXqurR*DmB(C_ntbp!sn1Z5i^e?tL0UmWg1=#@vKibZ&O>q`o}BY`)uuFze^RuWq<1;{)};t?iNxU}-@wCs%ex;9sT_g0|8D(x znWlCS{~@2(cIH;4K4#_-kG%j2{wu9PE&oClskb8|GPuV3SBQ|Xt!APId)NYd_TmR$ z8xT1$M%cFoFDI)jO1<~PjRs2jCs#A>MA~JZcKKoy$T7r=K|2*AkLIQ2Dp0{WGcV|x z{svJhdFL$OvA4W7sW;+p@Vc_i%P?JB-+2UzJ044uKOV`^mrH#_3QwqTlUKg!_U&)q z#|s}qzc-Mp7hI&AK*}d!f%01>Rlk!KPUQ-C^VJw!*D0;#|14N6fZC-=Wj`F9sy~py zL-;45RqZzL7EXzphC06QzJjrbt=Y(nOngKKW%vM`8C>T_WG$guleNKa!0oxft`V4A z!Q-44J|Z=3$%~_;9$kY4?~hodLfbY%6y||!16TMZ?lijgyxh7Yp6XP$`Kn3l85{20 z*}0HwymC8!l-Ix=HsJ8##dY33Qf^Vh|ldpWjSz_Y1Ybk%Yh?$sMt?0lY? z7xrElFv^RO>$~>Pt?nn#8nl*{=W9nG9#>1G2wJq{J5V+Eh(00u{v2d7&3vKPLoyM4 zL*UZ2@A6q2BJl14iOUkfdUK&BT3R{N`+jqNoy}JX>Fs@tT^aYb@S{1uYZoiWw@c*Y z4QN>QtJ98qI+DDa6KT5}sEvjko3322b5^=3bzta<# zul*}@v&0fqA}F!<&Fz7Yt8s>JgWIMe?_zSg)3V1OwecSC1ijzQv1nKb z{Rq^0!cwVAmQYEnhVwpl1?-IH#~*D_d|q6C&w+cFvPCH+!w10J^fS;{iw5B4eDkGl zy|D}Gd@t-Jq9+BVbqLQabur;{AU{Xpzq-8efri?5gkDsXt}dAuTG~~GS-3HHdvVHI zU;lL1<*Qx#Z+@KoA)R9X*2xkzHaACDpSGQxT>w2m!oRIa52V{>Un;z>;TOI*ez;So zy1BMEy>Ltgw-YCkgn(?;G{(e^5s0h*8Tt_Jgw(Wp{0&Pv9JApY#7$dqT^f?=Q4F&| z1L35Wj!ECdlGP-6n*`)H{jS-^Am!7gyOYHtdQ7|`S(ZYyk7x-u2wxK)p@k2M#@LNl zPc3HNOXOhUw#_{$S$jKiNmJ3t{nO7qnbX{*f=|9^KxX>Xc4|IkHtcKB@b>(oSI&&u zF1weHyF*&;AX??A4~{@7Q-H}4$gvkmJ29V0Uh3(+M=PbD#=yUjp5ohEZc0**OBw<1 zRs_&UTAj1%Y^`{1uxvungOZhaRW>&WD$UqG@-ER3 z7$b?802L%Ou3fDvp6gIEFa2(|%5*JJ_`^LbiPTBs-5s6MfaYCo5c1XC&$46$c9*A$1;ZwWPABx2KpDdx{jYviq8+!N% z^gIo4DRZz@*r~NrOSYRhn=GxYRr!7TOx9~5CeFw;^B?%f(bAGSZ{UCng{qyWX$mu8)sekMtDZIq;h>ia~)TBIvXwW?TlHM@LQX% zm?FH0Y1;YskAJ>i*cxOeXnpsd5+d5p3XnazQD;QdQDx>5xqkgW?7as(T;I1S zKB7el5uGrJ5<&D{LP!u1MDIk4-aBI^O7s#0(Gw+Fn2162P7p+oZcLP@GwNWI}vYp>(#q zk6h0y?7dzuTc6{?)szx>?cKGnWvm{oVPCgXgQ^)>7WM?>y!#gF)n{G4osR9Ut$R+q zGFEcm}D6|(FWY=&Csz(&5$w%}j2V?1~mAm%bs+rl4HY*Q?vgB|w?`(?i0UBH$+ zn+KK%6x{9Ve;++9{^<2(IAP*n>{3wKiOzspVzU(po!bdEP>G4XyCt~TGRvyI9F8Z$ z-q+ok-qIOdODynB$vuMdW6QzpP6f1zPTJ9?#BW~J$!%VpwoO3R>kO>(x(3|RNH`a& z^BGAr)fYyU7B7V6{AyapEjlSa>M4?C@^GAKC6mlJZOLxPo4D9fnCQ&J1E|_BW6|pi zV5Cd%+WX1O<1n+V+aB?wxnN(Bwq zq_lJGb#7;$ml}N+#|9`hk9oMIx`}QrR@pajl8=4f<=^cEA>epG7?2r!z1yb{B#Y{c z^?@6u{H$+4(Ftvsy35=qS6w+jCfCv$OS6!0lr>m*S28ffRBhBCuv3tpk3C%&gRg1o zIq#>7@3t=H;oO`}(agx^zI;~n@hX%KU1^2Po7yXV&e1jjQuMibTo^;M0MfbWEky>FKcGe8`+k_C{uBaocw@pzbtsfg=K~B|e7g)_S z=dj!}ujHr4@(vU)0awyae9`wmVmPAvct4u|Fwb)^PJ7mHL78-6>mGK>0dLDDPS~N_QCu^t2b#~m;nhheihm`bN1MbloPM|})zU2D zwJ4Vl)!Ify`R;UESYf?E_QD~b{n5{TM%&J6JYb~?NVOLm(cMmk;|ffE#{VXKUL{dA zlM69duEsT!Vve}aSjsRLTHT?dywmvW`Vl5>^PYoa^^+HO2(F;Mp~3qceF;g z=rBfmvx)3tyb%r|fY>Edf*2;Nf-ZGiz^uzYgG-WqW6Ia=ppf{W=SMu;F)KAU zjhb{+p3l4Q9Ko+nnAaF8snF@(n?@F35+tqmfmouMa-$5iHcpjQ=rkD@?lM{VIk^jj zv&E=v(&?zU2Pvuiy}wTKq5+-=?D=#i+m>cq(VGwyP(L7wn4r8CWEBswgT87yuIpJw zCf>>Mq<^bXs?EiO_)J)f2e3gM%7p$%-u$6K*

O6gh7(DX(7M{oYZw6<5GESu;N} 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᫿ z?HiDE^K-`FtD;K^!`-YIqW015kk0hF+DaG`W zt#9_7^Fd93nHn;1iblrp=!4+k;~J~l=G9(R_`Nq" + ] + }, + { + "cell_type": "markdown", + "id": "7174820b", + "metadata": { + "editable": true + }, "source": [ "# Solving Differential Equations with Deep Learning\n", "\n", @@ -10,7 +24,6 @@ "approximate any function at a single hidden layer along with one input\n", "and output layer to any given precision. \n", "\n", - "\n", "An ordinary differential equation (ODE) is an equation involving functions having one variable.\n", "\n", "In general, an ordinary differential equation looks like" @@ -18,7 +31,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "ac838a12", + "metadata": { + "editable": true + }, "source": [ "\n", "

\n", @@ -32,7 +48,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "ccee4286", + "metadata": { + "editable": true + }, "source": [ "where $g(x)$ is the function to find, and $g^{(n)}(x)$ is the $n$-th derivative of $g(x)$.\n", "\n", @@ -42,14 +61,15 @@ "Along with ([1](#ode)), some additional conditions of the function $g(x)$ are typically given\n", "for the solution to be unique.\n", "\n", - "\n", - "\n", "Let the trial solution $g_t(x)$ be" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "39d7dabd", + "metadata": { + "editable": true + }, "source": [ "\n", "
\n", @@ -64,7 +84,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "74f33170", + "metadata": { + "editable": true + }, "source": [ "where $h_1(x)$ is a function that makes $g_t(x)$ satisfy a given set\n", "of conditions, $N(x,P)$ a neural network with weights and biases\n", @@ -77,11 +100,8 @@ "\n", "But what about the network $N(x,P)$?\n", "\n", - "\n", "As described previously, an optimization method could be used to minimize the parameters of a neural network, that being its weights and biases, through backward propagation.\n", "\n", - "\n", - "\n", "For the minimization to be defined, we need to have a cost function at hand to minimize.\n", "\n", "It is given that $f\\left(x, \\, g(x), \\, g'(x), \\, g''(x), \\, \\dots \\, , \\, g^{(n)}(x)\\right)$ should be equal to zero in ([1](#ode)).\n", @@ -92,7 +112,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "2565ab16", + "metadata": { + "editable": true + }, "source": [ "$$\n", "C\\left(x, P\\right) = \\big(f\\left(x, \\, g(x), \\, g'(x), \\, g''(x), \\, \\dots \\, , \\, g^{(n)}(x)\\right)\\big)^2\n", @@ -101,7 +124,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "83d4ee25", + "metadata": { + "editable": true + }, "source": [ "If $N$ inputs are given as a vector $\\boldsymbol{x}$ with elements $x_i$ for $i = 1,\\dots,N$,\n", "the cost function becomes" @@ -109,7 +135,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "a7a3a709", + "metadata": { + "editable": true + }, "source": [ "\n", "
\n", @@ -123,20 +152,28 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "d3ca8026", + "metadata": { + "editable": true + }, "source": [ "The neural net should then find the parameters $P$ that minimizes the cost function in\n", "([3](#cost)) for a set of $N$ training samples $x_i$.\n", "\n", - "\n", - "\n", "To perform the minimization using gradient descent, the gradient of $C\\left(\\boldsymbol{x}, P\\right)$ is needed.\n", "It might happen so that finding an analytical expression of the gradient of $C(\\boldsymbol{x}, P)$ from ([3](#cost)) gets too messy, depending on which cost function one desires to use.\n", "\n", "Luckily, there exists libraries that makes the job for us through automatic differentiation.\n", - "Automatic differentiation is a method of finding the derivatives numerically with very high precision.\n", - "\n", - "\n", + "Automatic differentiation is a method of finding the derivatives numerically with very high precision." + ] + }, + { + "cell_type": "markdown", + "id": "9bde4bd4", + "metadata": { + "editable": true + }, + "source": [ "### Example: Exponential decay\n", "\n", "An exponential decay of a quantity $g(x)$ is described by the equation" @@ -144,7 +181,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "e74337c3", + "metadata": { + "editable": true + }, "source": [ "\n", "
\n", @@ -158,7 +198,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "273549a4", + "metadata": { + "editable": true + }, "source": [ "with $g(0) = g_0$ for some chosen initial value $g_0$.\n", "\n", @@ -167,7 +210,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "db3c6623", + "metadata": { + "editable": true + }, "source": [ "\n", "
\n", @@ -182,18 +228,22 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "8547e3c8", + "metadata": { + "editable": true + }, "source": [ "Having an analytical solution at hand, it is possible to use it to compare how well a neural network finds a solution of ([4](#solve_expdec)).\n", "\n", - "\n", - "\n", "The program will use a neural network to solve" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "48341fc6", + "metadata": { + "editable": true + }, "source": [ "\n", "
\n", @@ -207,19 +257,24 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "d25b1e02", + "metadata": { + "editable": true + }, "source": [ "where $g(0) = g_0$ with $\\gamma$ and $g_0$ being some chosen values.\n", "\n", "In this example, $\\gamma = 2$ and $g_0 = 10$.\n", "\n", - "\n", "To begin with, a trial solution $g_t(t)$ must be chosen. A general trial solution for ordinary differential equations could be" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "7c5dd91e", + "metadata": { + "editable": true + }, "source": [ "$$\n", "g_t(x, P) = h_1(x) + h_2(x, N(x, P))\n", @@ -228,12 +283,13 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "24223062", + "metadata": { + "editable": true + }, "source": [ "with $h_1(x)$ ensuring that $g_t(x)$ satisfies some conditions and $h_2(x,N(x, P))$ an expression involving $x$ and the output from the neural network $N(x,P)$ with $P $ being the collection of the weights and biases for each layer. For now, it is assumed that the network consists of one input layer, one hidden layer, and one output layer.\n", "\n", - "\n", - "\n", "In this network, there are no weights and bias at the input layer, so $P = \\{ P_{\\text{hidden}}, P_{\\text{output}} \\}$.\n", "If there are $N_{\\text{hidden} }$ neurons in the hidden layer, then $P_{\\text{hidden}}$ is a $N_{\\text{hidden} } \\times (1 + N_{\\text{input}})$ matrix, given that there are $N_{\\text{input}}$ neurons in the input layer.\n", "\n", @@ -247,7 +303,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "ebf04383", + "metadata": { + "editable": true + }, "source": [ "\n", "
\n", @@ -261,7 +320,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "ea4a0013", + "metadata": { + "editable": true + }, "source": [ "### Reformulating the problem\n", "\n", @@ -277,7 +339,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "2351b84f", + "metadata": { + "editable": true + }, "source": [ "$$\n", "g_t(x, P) = g_0 + x \\cdot N(x, P)\n", @@ -286,14 +351,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "f6cc00e4", + "metadata": { + "editable": true + }, "source": [ "has been chosen such that it already solves the condition $g(0) = g_0$. What remains, is to find $P$ such that" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "84e066a1", + "metadata": { + "editable": true + }, "source": [ "\n", "
\n", @@ -307,11 +378,13 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "feff9ab3", + "metadata": { + "editable": true + }, "source": [ "is fulfilled as *best as possible*.\n", "\n", - "\n", "The left hand side and right hand side of ([8](#nnmin)) must be computed separately, and then the neural network must choose weights and biases, contained in $P$, such that the sides are equal as best as possible.\n", "This means that the absolute or squared difference between the sides must be as close to zero, ideally equal to zero.\n", "In this case, the difference squared shows to be an appropriate measurement of how erroneous the trial solution is with respect to $P$ of the neural network.\n", @@ -321,7 +394,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "0c6f0e79", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\min_{P}\\Big\\{ \\big(g_t'(x, P) - ( -\\gamma g_t(x, P) \\big)^2 \\Big\\}\n", @@ -330,7 +406,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "9302a1dd", + "metadata": { + "editable": true + }, "source": [ "(the notation $\\min_{P}\\{ f(x, P) \\}$ means that we desire to find $P$ that yields the minimum of $f(x, P)$)\n", "\n", @@ -339,7 +418,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "f7f204bb", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\min_{P_{\\text{hidden} }, \\ P_{\\text{output} }}\\Big\\{ \\big(g_t'(x, \\{ P_{\\text{hidden} }, P_{\\text{output} }\\}) - ( -\\gamma g_t(x, \\{ P_{\\text{hidden} }, P_{\\text{output} }\\}) \\big)^2 \\Big\\}\n", @@ -348,18 +430,22 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "8d61d75f", + "metadata": { + "editable": true + }, "source": [ "for an input value $x$.\n", "\n", - "\n", - "\n", "If the neural network evaluates $g_t(x, P)$ at more values for $x$, say $N$ values $x_i$ for $i = 1, \\dots, N$, then the *total* error to minimize becomes" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "10d3aec9", + "metadata": { + "editable": true + }, "source": [ "\n", "
\n", @@ -373,14 +459,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "5e296388", + "metadata": { + "editable": true + }, "source": [ "Letting $\\boldsymbol{x}$ be a vector with elements $x_i$ and $C(\\boldsymbol{x}, P) = \\frac{1}{N} \\sum_i \\big(g_t'(x_i, P) - ( -\\gamma g_t(x_i, P) \\big)^2$ denote the cost function, the minimization problem that our network must solve, becomes" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "fe010d79", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\min_{P} C(\\boldsymbol{x}, P)\n", @@ -389,7 +481,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "add715f9", + "metadata": { + "editable": true + }, "source": [ "In terms of $P_{\\text{hidden} }$ and $P_{\\text{output} }$, this could also be expressed as\n", "\n", @@ -397,20 +492,21 @@ "\\min_{P_{\\text{hidden} }, \\ P_{\\text{output} }} C(\\boldsymbol{x}, \\{P_{\\text{hidden} }, P_{\\text{output} }\\})\n", "$$\n", "\n", - "\n", "For simplicity, it is assumed that the input is an array $\\boldsymbol{x} = (x_1, \\dots, x_N)$ with $N$ elements. It is at these points the neural network should find $P$ such that it fulfills ([9](#min)).\n", "\n", "First, the neural network must feed forward the inputs.\n", "This means that $\\boldsymbol{x}s$ must be passed through an input layer, a hidden layer and a output layer. The input layer in this case, does not need to process the data any further.\n", "The input layer will consist of $N_{\\text{input} }$ neurons, passing its element to each neuron in the hidden layer. The number of neurons in the hidden layer will be $N_{\\text{hidden} }$.\n", "\n", - "\n", "For the $i$-th in the hidden layer with weight $w_i^{\\text{hidden} }$ and bias $b_i^{\\text{hidden} }$, the weighting from the $j$-th neuron at the input layer is:" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "cb9b22eb", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\begin{aligned}\n", @@ -429,14 +525,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "49f3c493", + "metadata": { + "editable": true + }, "source": [ "The result after weighting the inputs at the $i$-th hidden neuron can be written as a vector:" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "a352bd61", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\begin{aligned}\n", @@ -456,7 +558,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "e5636ad7", + "metadata": { + "editable": true + }, "source": [ "The vector $\\boldsymbol{p}_{i, \\text{hidden}}^T$ constitutes each row in $P_{\\text{hidden} }$, which contains the weights for the neural network to minimize according to ([9](#min)).\n", "\n", @@ -467,7 +572,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "68bb8b9c", + "metadata": { + "editable": true + }, "source": [ "$$\n", "f(z) = \\frac{1}{1 + \\exp{(-z)}}\n", @@ -476,7 +584,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "ff6e6536", + "metadata": { + "editable": true + }, "source": [ "It is possible to use other activations functions for the hidden layer also.\n", "\n", @@ -494,14 +605,15 @@ "and biases $b_i^{\\text{output}}$. In this case,\n", "it is assumes that the number of neurons in the output layer is one.\n", "\n", - "\n", - "\n", "The procedure of weighting the output neuron $j$ in the hidden layer to the $i$-th neuron in the output layer is similar as for the hidden layer described previously." ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "6fb4c55b", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\begin{aligned}\n", @@ -519,14 +631,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "09c31d8d", + "metadata": { + "editable": true + }, "source": [ "Expressing $z_{1,j}^{\\text{output}}$ as a vector gives the following way of weighting the inputs from the hidden layer:" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "f81fe361", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\boldsymbol{z}_{1}^{\\text{output}} =\n", @@ -542,11 +660,13 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "c309a4ce", + "metadata": { + "editable": true + }, "source": [ "In this case we seek a continuous range of values since we are approximating a function. This means that after computing $\\boldsymbol{z}_{1}^{\\text{output}}$ the neural network has finished its feed forward step, and $\\boldsymbol{z}_{1}^{\\text{output}}$ is the final output of the network.\n", "\n", - "\n", "The next step is to decide how the parameters should be changed such that they minimize the cost function.\n", "\n", "The chosen cost function for this problem is" @@ -554,7 +674,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "ea47ae29", + "metadata": { + "editable": true + }, "source": [ "$$\n", "C(\\boldsymbol{x}, P) = \\frac{1}{N} \\sum_i \\big(g_t'(x_i, P) - ( -\\gamma g_t(x_i, P) \\big)^2\n", @@ -563,12 +686,23 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "9dd83767", + "metadata": { + "editable": true + }, "source": [ "In order to minimize the cost function, an optimization method must be chosen.\n", "\n", - "Here, gradient descent with a constant step size has been chosen.\n", - "\n", + "Here, gradient descent with a constant step size has been chosen." + ] + }, + { + "cell_type": "markdown", + "id": "531a7b4f", + "metadata": { + "editable": true + }, + "source": [ "### Gradient descent\n", "\n", "The idea of the gradient descent algorithm is to update parameters in\n", @@ -581,7 +715,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "e10c204a", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\boldsymbol{\\omega}_{\\text{new} } = \\boldsymbol{\\omega} - \\lambda \\nabla_{\\boldsymbol{\\omega}} C(\\boldsymbol{x}, \\boldsymbol{\\omega})\n", @@ -590,7 +727,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "9f4fa48e", + "metadata": { + "editable": true + }, "source": [ "for a number of iterations or until $ \\big|\\big| \\boldsymbol{\\omega}_{\\text{new} } - \\boldsymbol{\\omega} \\big|\\big|$ becomes smaller than some given tolerance.\n", "\n", @@ -609,7 +749,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "4652fc79", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\begin{aligned}\n", @@ -621,14 +764,18 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "41ae0626", + "metadata": { + "editable": true + }, "source": [ "### The code for solving the ODE" ] }, { "cell_type": "code", - "execution_count": null, + "execution_count": 1, + "id": "af7c165f", "metadata": { "collapsed": false, "editable": true @@ -785,7 +932,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "875a0c0b", + "metadata": { + "editable": true + }, "source": [ "## The network with one input layer, specified number of hidden layers, and one output layer\n", "\n", @@ -796,7 +946,8 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 2, + "id": "00684827", "metadata": { "collapsed": false, "editable": true @@ -965,7 +1116,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "5420c490", + "metadata": { + "editable": true + }, "source": [ "### Example: Population growth\n", "\n", @@ -975,7 +1129,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "1436ed3c", + "metadata": { + "editable": true + }, "source": [ "\n", "
\n", @@ -989,7 +1146,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "a590bdb6", + "metadata": { + "editable": true + }, "source": [ "where $g(t)$ is the population density at time $t$, $\\alpha > 0$ the growth rate and $A > 0$ is the maximum population number in the environment.\n", "Also, at $t = 0$ the population has the size $g(0) = g_0$, where $g_0$ is some chosen constant.\n", @@ -999,15 +1159,16 @@ "using a library like TensorFlow is recommended.\n", "Here, we stay with a more simple approach and implement for comparison, the simple forward Euler method.\n", "\n", - "\n", - "\n", "Here, we will model a population $g(t)$ in an environment having carrying capacity $A$.\n", "The population follows the model" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "48d788d6", + "metadata": { + "editable": true + }, "source": [ "\n", "
\n", @@ -1021,13 +1182,15 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "169c6c25", + "metadata": { + "editable": true + }, "source": [ "where $g(0) = g_0$.\n", "\n", "In this example, we let $\\alpha = 2$, $A = 1$, and $g_0 = 1.2$.\n", "\n", - "\n", "We will get a slightly different trial solution, as the boundary conditions are different\n", "compared to the case for exponential decay.\n", "\n", @@ -1045,14 +1208,13 @@ "g(t) = \\frac{Ag_0}{g_0 + (A - g_0)\\exp(-\\alpha A t)}\n", "$$\n", "\n", - "\n", - "\n", "The network will be the similar as for the exponential decay example, but with some small modifications for our problem." ] }, { "cell_type": "code", - "execution_count": null, + "execution_count": 3, + "id": "6d2e33bf", "metadata": { "collapsed": false, "editable": true @@ -1226,7 +1388,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "e31ec549", + "metadata": { + "editable": true + }, "source": [ "## Using forward Euler to solve the ODE\n", "\n", @@ -1243,7 +1408,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "2e9ee105", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\begin{aligned}\n", @@ -1255,7 +1423,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "e876da16", + "metadata": { + "editable": true + }, "source": [ "along with the condition that $g(0) = g_0$.\n", "\n", @@ -1266,7 +1437,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "b79a3def", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\begin{aligned}\n", @@ -1279,14 +1453,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "9d99cb4e", + "metadata": { + "editable": true + }, "source": [ "Now, if $g_i = g(t_i)$ then" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "3b9dcc24", + "metadata": { + "editable": true + }, "source": [ "\n", "
\n", @@ -1305,7 +1485,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "65ce688e", + "metadata": { + "editable": true + }, "source": [ "for $i \\geq 1$ and $g_0 = g(t_0) = g(0) = g_0$.\n", "\n", @@ -1315,7 +1498,8 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 4, + "id": "d5497948", "metadata": { "collapsed": false, "editable": true @@ -1391,7 +1575,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "fa8f0bb4", + "metadata": { + "editable": true + }, "source": [ "## Solving the one dimensional Poisson equation\n", "\n", @@ -1400,7 +1587,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "f765b0ba", + "metadata": { + "editable": true + }, "source": [ "\n", "
\n", @@ -1414,7 +1604,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "bd63b92e", + "metadata": { + "editable": true + }, "source": [ "where $f(x)$ is a given function for $x \\in (0,1)$.\n", "\n", @@ -1423,7 +1616,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "c0a7face", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\begin{align*}\n", @@ -1435,19 +1631,24 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "f71c3cb9", + "metadata": { + "editable": true + }, "source": [ "This equation can be solved numerically using programs where e.g Autograd and TensorFlow are used.\n", "The results from the networks can then be compared to the analytical solution.\n", "In addition, it could be interesting to see how a typical method for numerically solving second order ODEs compares to the neural networks.\n", "\n", - "\n", "Here, the function $g(x)$ to solve for follows the equation" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "35aa6a37", + "metadata": { + "editable": true + }, "source": [ "$$\n", "-g''(x) = f(x),\\qquad x \\in (0,1)\n", @@ -1456,14 +1657,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "f8b35111", + "metadata": { + "editable": true + }, "source": [ "where $f(x)$ is a given function, along with the chosen conditions" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "33813514", + "metadata": { + "editable": true + }, "source": [ "\n", "
\n", @@ -1477,7 +1684,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "c70aadd4", + "metadata": { + "editable": true + }, "source": [ "In this example, we consider the case when $f(x) = (3x + x^2)\\exp(x)$.\n", "\n", @@ -1486,7 +1696,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "d5719dee", + "metadata": { + "editable": true + }, "source": [ "$$\n", "g_t(x) = x \\cdot (1-x) \\cdot N(P,x)\n", @@ -1495,14 +1708,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "a683041b", + "metadata": { + "editable": true + }, "source": [ "The analytical solution for this problem is" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "672cdaff", + "metadata": { + "editable": true + }, "source": [ "$$\n", "g(x) = x(1 - x)\\exp(x)\n", @@ -1511,7 +1730,8 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 5, + "id": "66e6bebb", "metadata": { "collapsed": false, "editable": true @@ -1672,7 +1892,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "d425cba5", + "metadata": { + "editable": true + }, "source": [ "### Comparing with a numerical scheme\n", "\n", @@ -1691,7 +1914,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "a2efa110", + "metadata": { + "editable": true + }, "source": [ "\n", "
\n", @@ -1705,14 +1931,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "5011ee25", + "metadata": { + "editable": true + }, "source": [ "If $x_i = i \\Delta x = x_{i-1} + \\Delta x$ and $g_i = g(x_i)$ for $i = 1,\\dots N_x - 2$ with $N_x$ being the number of values for $x$, ([15](#approx)) becomes" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "705ee300", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\begin{aligned}\n", @@ -1724,14 +1956,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "b390796d", + "metadata": { + "editable": true + }, "source": [ "Since we know from our problem that" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "19c9ece4", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\begin{aligned}\n", @@ -1743,7 +1981,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "6ade1a7a", + "metadata": { + "editable": true + }, "source": [ "along with the conditions $g(0) = g(1) = 0$,\n", "the following scheme can be used to find an approximate solution for $g(x)$ numerically:" @@ -1751,7 +1992,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "78b16d02", + "metadata": { + "editable": true + }, "source": [ "\n", "
\n", @@ -1768,7 +2012,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "f2bfcca4", + "metadata": { + "editable": true + }, "source": [ "for $i = 1, \\dots, N_x - 2$ where $g_0 = g_{N_x - 1} = 0$ and $f(x_i) = (3x_i + x_i^2)\\exp(x_i)$, which is given for our specific problem.\n", "\n", @@ -1777,7 +2024,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "a6191528", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\begin{aligned}\n", @@ -1811,17 +2061,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "aefef707", + "metadata": { + "editable": true + }, "source": [ "which makes it possible to solve for the vector $\\boldsymbol{g}$.\n", "\n", - "\n", "We can then compare the result from this numerical scheme with the output from our network using Autograd:" ] }, { "cell_type": "code", - "execution_count": null, + "execution_count": 6, + "id": "471664cd", "metadata": { "collapsed": false, "editable": true @@ -2022,7 +2275,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "6f02e86d", + "metadata": { + "editable": true + }, "source": [ "## Partial Differential Equations\n", "\n", @@ -2036,7 +2292,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "ad5c63e8", + "metadata": { + "editable": true + }, "source": [ "\n", "
\n", @@ -2050,10 +2309,21 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "c7b98797", + "metadata": { + "editable": true + }, + "source": [ + "where $f$ is an expression involving all kinds of possible mixed derivatives of $g(x_1,\\dots,x_N)$ up to an order $n$. In order for the solution to be unique, some additional conditions must also be given." + ] + }, + { + "cell_type": "markdown", + "id": "52f9394e", + "metadata": { + "editable": true + }, "source": [ - "where $f$ is an expression involving all kinds of possible mixed derivatives of $g(x_1,\\dots,x_N)$ up to an order $n$. In order for the solution to be unique, some additional conditions must also be given.\n", - "\n", "### Type of problem\n", "\n", "The problem our network must solve for, is similar to the ODE case.\n", @@ -2064,7 +2334,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "4d489854", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\begin{align*}\n", @@ -2075,15 +2348,24 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "82311538", + "metadata": { + "editable": true + }, "source": [ "where $h_1(x_1,\\dots,x_N)$ is a function that ensures $g_t(x_1,\\dots,x_N)$ satisfies some given conditions.\n", "The neural network $N(x_1,\\dots,x_N,P)$ has weights and biases described by $P$ and $h_2(x_1,\\dots,x_N,N(x_1,\\dots,x_N,P))$ is an expression using the output from the neural network in some way.\n", "\n", - "The role of the function $h_2(x_1,\\dots,x_N,N(x_1,\\dots,x_N,P))$, is to ensure that the output of $N(x_1,\\dots,x_N,P)$ is zero when $g_t(x_1,\\dots,x_N)$ is evaluated at the values of $x_1,\\dots,x_N$ where the given conditions must be satisfied. The function $h_1(x_1,\\dots,x_N)$ should alone make $g_t(x_1,\\dots,x_N)$ satisfy the conditions.\n", - "\n", - "\n", - "\n", + "The role of the function $h_2(x_1,\\dots,x_N,N(x_1,\\dots,x_N,P))$, is to ensure that the output of $N(x_1,\\dots,x_N,P)$ is zero when $g_t(x_1,\\dots,x_N)$ is evaluated at the values of $x_1,\\dots,x_N$ where the given conditions must be satisfied. The function $h_1(x_1,\\dots,x_N)$ should alone make $g_t(x_1,\\dots,x_N)$ satisfy the conditions." + ] + }, + { + "cell_type": "markdown", + "id": "9d134db4", + "metadata": { + "editable": true + }, + "source": [ "### Network requirements\n", "\n", "The network tries then the minimize the cost function following the\n", @@ -2099,7 +2381,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "5a463498", + "metadata": { + "editable": true + }, "source": [ "$$\n", "C\\left(x_1, \\dots, x_N, P\\right) = \\left( f\\left(x_1, \\, \\dots \\, , x_N, \\frac{\\partial g(x_1,\\dots,x_N) }{\\partial x_1}, \\dots , \\frac{\\partial g(x_1,\\dots,x_N) }{\\partial x_N}, \\frac{\\partial g(x_1,\\dots,x_N) }{\\partial x_1\\partial x_2}, \\, \\dots \\, , \\frac{\\partial^n g(x_1,\\dots,x_N) }{\\partial x_N^n} \\right) \\right)^2\n", @@ -2108,14 +2393,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "c40d8997", + "metadata": { + "editable": true + }, "source": [ "If we let $\\boldsymbol{x} = \\big( x_1, \\dots, x_N \\big)$ be an array containing the values for $x_1, \\dots, x_N$ respectively, the cost function can be reformulated into the following:" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "cc033de6", + "metadata": { + "editable": true + }, "source": [ "$$\n", "C\\left(\\boldsymbol{x}, P\\right) = f\\left( \\left( \\boldsymbol{x}, \\frac{\\partial g(\\boldsymbol{x}) }{\\partial x_1}, \\dots , \\frac{\\partial g(\\boldsymbol{x}) }{\\partial x_N}, \\frac{\\partial g(\\boldsymbol{x}) }{\\partial x_1\\partial x_2}, \\, \\dots \\, , \\frac{\\partial^n g(\\boldsymbol{x}) }{\\partial x_N^n} \\right) \\right)^2\n", @@ -2124,14 +2415,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "ae18b4f4", + "metadata": { + "editable": true + }, "source": [ "If we also have $M$ different sets of values for $x_1, \\dots, x_N$, that is $\\boldsymbol{x}_i = \\big(x_1^{(i)}, \\dots, x_N^{(i)}\\big)$ for $i = 1,\\dots,M$ being the rows in matrix $X$, the cost function can be generalized into" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "44ca21bd", + "metadata": { + "editable": true + }, "source": [ "$$\n", "C\\left(X, P \\right) = \\sum_{i=1}^M f\\left( \\left( \\boldsymbol{x}_i, \\frac{\\partial g(\\boldsymbol{x}_i) }{\\partial x_1}, \\dots , \\frac{\\partial g(\\boldsymbol{x}_i) }{\\partial x_N}, \\frac{\\partial g(\\boldsymbol{x}_i) }{\\partial x_1\\partial x_2}, \\, \\dots \\, , \\frac{\\partial^n g(\\boldsymbol{x}_i) }{\\partial x_N^n} \\right) \\right)^2.\n", @@ -2140,7 +2437,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "fe94451e", + "metadata": { + "editable": true + }, "source": [ "## Example: The diffusion equation\n", "\n", @@ -2149,7 +2449,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "30a42273", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\frac{\\partial g(x,t)}{\\partial t} = \\frac{\\partial^2 g(x,t)}{\\partial x^2}\n", @@ -2158,14 +2461,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "fd4077e7", + "metadata": { + "editable": true + }, "source": [ "where a possible choice of conditions are" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "dbbf2e4b", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\begin{align*}\n", @@ -2178,18 +2487,22 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "83653db9", + "metadata": { + "editable": true + }, "source": [ "with $u(x)$ being some given function.\n", "\n", - "\n", - "\n", "For this case, we want to find $g(x,t)$ such that" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "d2c2ef4f", + "metadata": { + "editable": true + }, "source": [ "\n", "
\n", @@ -2203,14 +2516,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "8fb27bdb", + "metadata": { + "editable": true + }, "source": [ "and" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "dc9297ab", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\begin{align*}\n", @@ -2223,7 +2542,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "ab90784f", + "metadata": { + "editable": true + }, "source": [ "with $u(x) = \\sin(\\pi x)$.\n", "\n", @@ -2231,9 +2553,6 @@ "The deep neural network will follow the same structure as discussed in the examples solving the ODEs.\n", "First, we will look into how Autograd could be used in a network tailored to solve for bivariate functions.\n", "\n", - "\n", - "\n", - "\n", "The only change to do here, is to extend our network such that\n", "functions of multiple parameters are correctly handled. In this case\n", "we have two variables in our function to solve for, that is time $t$\n", @@ -2245,7 +2564,8 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 7, + "id": "b07e858c", "metadata": { "collapsed": false, "editable": true @@ -2300,7 +2620,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "9a167ec1", + "metadata": { + "editable": true + }, "source": [ "The cost function must then iterate through the given arrays\n", "containing values for $x$ and $t$, defines a point $(x,t)$ the deep\n", @@ -2322,8 +2645,6 @@ "$$\n", "since $(0) = u(1) = 0$ and $u(x) = \\sin(\\pi x)$.\n", "\n", - "\n", - "\n", "The Jacobian is used because the program must find the derivative of\n", "the trial solution with respect to $x$ and $t$.\n", "\n", @@ -2345,7 +2666,8 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 8, + "id": "921e5969", "metadata": { "collapsed": false, "editable": true @@ -2392,7 +2714,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "0bc00b69", + "metadata": { + "editable": true + }, "source": [ "### Setting up the network using Autograd; The full program\n", "\n", @@ -2408,14 +2733,14 @@ "Be aware, though, that it is fairly slow for the parameters used.\n", "A better result is possible, but requires more iterations, and thus longer time to complete.\n", "\n", - "\n", "Indeed, the program below is not optimal in its implementation, but rather serves as an example on how to implement and use a neural network to solve a PDE.\n", "Using TensorFlow results in a much better execution time. Try it!" ] }, { "cell_type": "code", - "execution_count": null, + "execution_count": 9, + "id": "20734418", "metadata": { "collapsed": false, "editable": true @@ -2649,7 +2974,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "143f1c80", + "metadata": { + "editable": true + }, "source": [ "## Solving the wave equation with Neural Networks\n", "\n", @@ -2658,7 +2986,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "190bd4f2", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\frac{\\partial^2 g(x,t)}{\\partial t^2} = c^2\\frac{\\partial^2 g(x,t)}{\\partial x^2}\n", @@ -2667,7 +2998,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "9719cfc5", + "metadata": { + "editable": true + }, "source": [ "with $c$ being the specified wave speed.\n", "\n", @@ -2676,7 +3010,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "f69ec7fd", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\begin{align*}\n", @@ -2690,17 +3027,22 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "6ce8c5a8", + "metadata": { + "editable": true + }, "source": [ "where $\\frac{\\partial g(x,t)}{\\partial t} \\Big |_{t = 0}$ means the derivative of $g(x,t)$ with respect to $t$ is evaluated at $t = 0$, and $u(x)$ and $v(x)$ being given functions.\n", "\n", - "\n", "The wave equation to solve for, is" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "4be700d7", + "metadata": { + "editable": true + }, "source": [ "\n", "
\n", @@ -2714,7 +3056,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "993f93ba", + "metadata": { + "editable": true + }, "source": [ "where $c$ is the given wave speed.\n", "The chosen conditions for this equation are" @@ -2722,7 +3067,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "2cb2a80f", + "metadata": { + "editable": true + }, "source": [ "\n", "
\n", @@ -2739,12 +3087,13 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "3f1dcfd4", + "metadata": { + "editable": true + }, "source": [ "In this example, let $c = 1$ and $u(x) = \\sin(\\pi x)$ and $v(x) = -\\pi\\sin(\\pi x)$.\n", "\n", - "\n", - "\n", "Setting up the network is done in similar matter as for the example of solving the diffusion equation.\n", "The only things we have to change, is the trial solution such that it satisfies the conditions from ([20](#condwave)) and the cost function.\n", "\n", @@ -2762,7 +3111,6 @@ "\n", "Note that this trial solution satisfies the conditions only if $u(0) = v(0) = u(1) = v(1) = 0$, which is the case in this example.\n", "\n", - "\n", "The analytical solution for our specific problem, is\n", "\n", "$$\n", @@ -2772,7 +3120,8 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 10, + "id": "230a9aef", "metadata": { "collapsed": false, "editable": true @@ -3003,7 +3352,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "a23bd19a", + "metadata": { + "editable": true + }, "source": [ "## Resources on differential equations and deep learning\n", "\n", @@ -3019,5 +3371,5 @@ ], "metadata": {}, "nbformat": 4, - "nbformat_minor": 4 + "nbformat_minor": 5 } diff --git a/doc/LectureNotes/chapter12.ipynb b/doc/LectureNotes/chapter12.ipynb new file mode 100644 index 000000000..c0569826b --- /dev/null +++ b/doc/LectureNotes/chapter12.ipynb @@ -0,0 +1,1577 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "b1ad0b52", + "metadata": { + "editable": true + }, + "source": [ + "" + ] + }, + { + "cell_type": "markdown", + "id": "9548423d", + "metadata": { + "editable": true + }, + "source": [ + "# Convolutional Neural Networks\n", + "\n", + "Convolutional neural networks (CNNs) were developed during the last\n", + "decade of the previous century, with a focus on character recognition\n", + "tasks. Nowadays, CNNs are a central element in the spectacular success\n", + "of deep learning methods. The success in for example image\n", + "classifications have made them a central tool for most machine\n", + "learning practitioners.\n", + "\n", + "CNNs are very similar to ordinary Neural Networks.\n", + "They are made up of neurons that have learnable weights and\n", + "biases. Each neuron receives some inputs, performs a dot product and\n", + "optionally follows it with a non-linearity. The whole network still\n", + "expresses a single differentiable score function: from the raw image\n", + "pixels on one end to class scores at the other. And they still have a\n", + "loss function (for example Softmax) on the last (fully-connected) layer\n", + "and all the tips/tricks we developed for learning regular Neural\n", + "Networks still apply (back propagation, gradient descent etc etc).\n", + "\n", + "**CNN architectures make the explicit assumption that\n", + "the inputs are images, which allows us to encode certain properties\n", + "into the architecture. These then make the forward function more\n", + "efficient to implement and vastly reduce the amount of parameters in\n", + "the network.**\n", + "\n", + "Here we provide only a superficial overview, for the more interested, we recommend highly the course\n", + "[IN5400 – Machine Learning for Image Analysis](https://www.uio.no/studier/emner/matnat/ifi/IN5400/index-eng.html)\n", + "and the slides of [CS231](http://cs231n.github.io/convolutional-networks/).\n", + "\n", + "Another good read is the article here ." + ] + }, + { + "cell_type": "markdown", + "id": "315b8308", + "metadata": { + "editable": true + }, + "source": [ + "## Neural Networks vs CNNs\n", + "\n", + "Neural networks are defined as **affine transformations**, that is \n", + "a vector is received as input and is multiplied with a matrix of so-called weights (our unknown paramters) to produce an\n", + "output (to which a bias vector is usually added before passing the result\n", + "through a nonlinear activation function). This is applicable to any type of input, be it an\n", + "image, a sound clip or an unordered collection of features: whatever their\n", + "dimensionality, their representation can always be flattened into a vector\n", + "before the transformation.\n", + "\n", + "However, when we consider images, sound clips and many other similar kinds of data, these data have an intrinsic\n", + "structure. More formally, they share these important properties:\n", + "* They are stored as multi-dimensional arrays (think of the pixels of a figure) .\n", + "\n", + "* They feature one or more axes for which ordering matters (e.g., width and height axes for an image, time axis for a sound clip).\n", + "\n", + "* One axis, called the channel axis, is used to access different views of the data (e.g., the red, green and blue channels of a color image, or the left and right channels of a stereo audio track).\n", + "\n", + "These properties are not exploited when an affine transformation is applied; in\n", + "fact, all the axes are treated in the same way and the topological information\n", + "is not taken into account. Still, taking advantage of the implicit structure of\n", + "the data may prove very handy in solving some tasks, like computer vision and\n", + "speech recognition, and in these cases it would be best to preserve it. This is\n", + "where discrete convolutions come into play.\n", + "\n", + "A discrete convolution is a linear transformation that preserves this notion of\n", + "ordering. It is sparse (only a few input units contribute to a given output\n", + "unit) and reuses parameters (the same weights are applied to multiple locations\n", + "in the input).\n", + "\n", + "As an example, consider\n", + "an image of size $32\\times 32\\times 3$ (32 wide, 32 high, 3 color channels), so a\n", + "single fully-connected neuron in a first hidden layer of a regular\n", + "Neural Network would have $32\\times 32\\times 3 = 3072$ weights. This amount still\n", + "seems manageable, but clearly this fully-connected structure does not\n", + "scale to larger images. For example, an image of more respectable\n", + "size, say $200\\times 200\\times 3$, would lead to neurons that have \n", + "$200\\times 200\\times 3 = 120,000$ weights. \n", + "\n", + "We could have\n", + "several such neurons, and the parameters would add up quickly! Clearly,\n", + "this full connectivity is wasteful and the huge number of parameters\n", + "would quickly lead to possible overfitting.\n", + "\n", + "\n", + "\n", + "\n", + "

Figure 1: A regular 3-layer Neural Network.

\n", + "\n", + "\n", + "Convolutional Neural Networks take advantage of the fact that the\n", + "input consists of images and they constrain the architecture in a more\n", + "sensible way. \n", + "\n", + "In particular, unlike a regular Neural Network, the\n", + "layers of a CNN have neurons arranged in 3 dimensions: width,\n", + "height, depth. (Note that the word depth here refers to the third\n", + "dimension of an activation volume, not to the depth of a full Neural\n", + "Network, which can refer to the total number of layers in a network.)\n", + "\n", + "To understand it better, the above example of an image \n", + "with an input volume of\n", + "activations has dimensions $32\\times 32\\times 3$ (width, height,\n", + "depth respectively). \n", + "\n", + "The neurons in a layer will\n", + "only be connected to a small region of the layer before it, instead of\n", + "all of the neurons in a fully-connected manner. Moreover, the final\n", + "output layer could for this specific image have dimensions $1\\times 1 \\times 10$, \n", + "because by the\n", + "end of the CNN architecture we will reduce the full image into a\n", + "single vector of class scores, arranged along the depth\n", + "dimension. \n", + "\n", + "\n", + "\n", + "\n", + "

Figure 1: A CNN arranges its neurons in three dimensions (width, height, depth), as visualized in one of the layers. Every layer of a CNN transforms the 3D input volume to a 3D output volume of neuron activations. In this example, the red input layer holds the image, so its width and height would be the dimensions of the image, and the depth would be 3 (Red, Green, Blue channels).

\n", + "" + ] + }, + { + "cell_type": "markdown", + "id": "a142cd5d", + "metadata": { + "editable": true + }, + "source": [ + "## Layers used to build CNNs\n", + "\n", + "A simple CNN is a sequence of layers, and every layer of a CNN\n", + "transforms one volume of activations to another through a\n", + "differentiable function. We use three main types of layers to build\n", + "CNN architectures: Convolutional Layer, Pooling Layer, and\n", + "Fully-Connected Layer (exactly as seen in regular Neural Networks). We\n", + "will stack these layers to form a full CNN architecture.\n", + "\n", + "A simple CNN for image classification could have the architecture:\n", + "\n", + "* **INPUT** ($32\\times 32 \\times 3$) will hold the raw pixel values of the image, in this case an image of width 32, height 32, and with three color channels R,G,B.\n", + "\n", + "* **CONV** (convolutional )layer will compute the output of neurons that are connected to local regions in the input, each computing a dot product between their weights and a small region they are connected to in the input volume. This may result in volume such as $[32\\times 32\\times 12]$ if we decided to use 12 filters.\n", + "\n", + "* **RELU** layer will apply an elementwise activation function, such as the $max(0,x)$ thresholding at zero. This leaves the size of the volume unchanged ($[32\\times 32\\times 12]$).\n", + "\n", + "* **POOL** (pooling) layer will perform a downsampling operation along the spatial dimensions (width, height), resulting in volume such as $[16\\times 16\\times 12]$.\n", + "\n", + "* **FC** (i.e. fully-connected) layer will compute the class scores, resulting in volume of size $[1\\times 1\\times 10]$, where each of the 10 numbers correspond to a class score, such as among the 10 categories of the MNIST images we considered above . As with ordinary Neural Networks and as the name implies, each neuron in this layer will be connected to all the numbers in the previous volume.\n", + "\n", + "CNNs transform the original image layer by layer from the original\n", + "pixel values to the final class scores. \n", + "\n", + "Observe that some layers contain\n", + "parameters and other don’t. In particular, the CNN layers perform\n", + "transformations that are a function of not only the activations in the\n", + "input volume, but also of the parameters (the weights and biases of\n", + "the neurons). On the other hand, the RELU/POOL layers will implement a\n", + "fixed function. The parameters in the CONV/FC layers will be trained\n", + "with gradient descent so that the class scores that the CNN computes\n", + "are consistent with the labels in the training set for each image.\n", + "\n", + "In summary:\n", + "\n", + "* A CNN architecture is in the simplest case a list of Layers that transform the image volume into an output volume (e.g. holding the class scores)\n", + "\n", + "* There are a few distinct types of Layers (e.g. CONV/FC/RELU/POOL are by far the most popular)\n", + "\n", + "* Each Layer accepts an input 3D volume and transforms it to an output 3D volume through a differentiable function\n", + "\n", + "* Each Layer may or may not have parameters (e.g. CONV/FC do, RELU/POOL don’t)\n", + "\n", + "* Each Layer may or may not have additional hyperparameters (e.g. CONV/FC/POOL do, RELU doesn’t)\n", + "\n", + "A dense neural network is representd by an affine operation (like matrix-matrix multiplication) where all parameters are included.\n", + "\n", + "The key idea in CNNs for say imaging is that in images neighbor pixels tend to be related! So we connect\n", + "only neighboring neurons in the input instead of connecting all with the first hidden layer.\n", + "\n", + "We say we perform a filtering (convolution is the mathematical operation)." + ] + }, + { + "cell_type": "markdown", + "id": "bb1e3617", + "metadata": { + "editable": true + }, + "source": [ + "## Mathematics of CNNs\n", + "\n", + "The mathematics of CNNs is based on the mathematical operation of\n", + "**convolution**. In mathematics (in particular in functional analysis),\n", + "convolution is represented by matheematical operation (integration,\n", + "summation etc) on two function in order to produce a third function\n", + "that expresses how the shape of one gets modified by the other.\n", + "Convolution has a plethora of applications in a variety of disciplines, spanning from statistics to signal processing, computer vision, solutions of differential equations,linear algebra, engineering, and yes, machine learning.\n", + "\n", + "Mathematically, convolution is defined as follows (one-dimensional example):\n", + "Let us define a continuous function $y(t)$ given by" + ] + }, + { + "cell_type": "markdown", + "id": "051485e5", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "y(t) = \\int x(a) w(t-a) da,\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "799b8e5f", + "metadata": { + "editable": true + }, + "source": [ + "where $x(a)$ represents a so-called input and $w(t-a)$ is normally called the weight function or kernel.\n", + "\n", + "The above integral is written in a more compact form as" + ] + }, + { + "cell_type": "markdown", + "id": "3353345f", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "y(t) = \\left(x * w\\right)(t).\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "ef341ee6", + "metadata": { + "editable": true + }, + "source": [ + "The discretized version reads" + ] + }, + { + "cell_type": "markdown", + "id": "ca8f7582", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "y(t) = \\sum_{a=-\\infty}^{a=\\infty}x(a)w(t-a).\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "216e011f", + "metadata": { + "editable": true + }, + "source": [ + "Computing the inverse of the above convolution operations is known as deconvolution.\n", + "\n", + "How can we use this? And what does it mean? Let us study some familiar examples first." + ] + }, + { + "cell_type": "markdown", + "id": "5545738c", + "metadata": { + "editable": true + }, + "source": [ + "### Convolution Examples: Polynomial multiplication\n", + "\n", + "We have already met such an example in project 1 when we tried to set\n", + "up the design matrix for a two-dimensional function. This was an\n", + "example of polynomial multiplication. Let us recast such a problem in terms of the convolution operation.\n", + "Let us look a the following polynomials to second and third order, respectively:" + ] + }, + { + "cell_type": "markdown", + "id": "9f317908", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "p(t) = \\alpha_0+\\alpha_1 t+\\alpha_2 t^2,\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "eb6f1070", + "metadata": { + "editable": true + }, + "source": [ + "and" + ] + }, + { + "cell_type": "markdown", + "id": "9fe61b3c", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "s(t) = \\beta_0+\\beta_1 t+\\beta_2 t^2+\\beta_3 t^3.\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "38c68ea7", + "metadata": { + "editable": true + }, + "source": [ + "The polynomial multiplication gives us a new polynomial of degree $5$" + ] + }, + { + "cell_type": "markdown", + "id": "3e91a9f1", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "z(t) = \\delta_0+\\delta_1 t+\\delta_2 t^2+\\delta_3 t^3+\\delta_4 t^4+\\delta_5 t^5.\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "5e24ac44", + "metadata": { + "editable": true + }, + "source": [ + "Computing polynomial products can be implemented efficiently if we rewrite the more brute force multiplications using convolution.\n", + "We note first that the new coefficients are given as" + ] + }, + { + "cell_type": "markdown", + "id": "ac215eb9", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "\\begin{split}\n", + "\\delta_0=&\\alpha_0\\beta_0\\\\\n", + "\\delta_1=&\\alpha_1\\beta_0+\\alpha_1\\beta_0\\\\\n", + "\\delta_2=&\\alpha_0\\beta_2+\\alpha_1\\beta_1+\\alpha_2\\beta_0\\\\\n", + "\\delta_3=&\\alpha_1\\beta_2+\\alpha_2\\beta_1+\\alpha_0\\beta_3\\\\\n", + "\\delta_4=&\\alpha_2\\beta_2+\\alpha_1\\beta_3\\\\\n", + "\\delta_5=&\\alpha_2\\beta_3.\\\\\n", + "\\end{split}\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "eca51025", + "metadata": { + "editable": true + }, + "source": [ + "We note that $\\alpha_i=0$ except for $i\\in \\left\\{0,1,2\\right\\}$ and $\\beta_i=0$ except for $i\\in\\left\\{0,1,2,3\\right\\}$.\n", + "\n", + "We can then rewrite the coefficients $\\delta_j$ using a discrete convolution as" + ] + }, + { + "cell_type": "markdown", + "id": "0d517816", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "\\delta_j = \\sum_{i=-\\infty}^{i=\\infty}\\alpha_i\\beta_{j-i}=(\\alpha * \\beta)_j,\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "8cf1037e", + "metadata": { + "editable": true + }, + "source": [ + "or as a double sum with restriction $l=i+j$" + ] + }, + { + "cell_type": "markdown", + "id": "efe18d99", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "\\delta_l = \\sum_{ij}\\alpha_i\\beta_{j}.\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "14ae41db", + "metadata": { + "editable": true + }, + "source": [ + "Do you see a potential drawback with these equations?\n", + "\n", + "Since we only have a finite number of $\\alpha$ and $\\beta$ values\n", + "which are non-zero, we can rewrite the above convolution expressions\n", + "as a matrix-vector multiplication" + ] + }, + { + "cell_type": "markdown", + "id": "046e108b", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "\\boldsymbol{\\delta}=\\begin{bmatrix}\\alpha_0 & 0 & 0 & 0 \\\\\n", + " \\alpha_1 & \\alpha_0 & 0 & 0 \\\\\n", + "\t\t\t \\alpha_2 & \\alpha_1 & \\alpha_0 & 0 \\\\\n", + "\t\t\t 0 & \\alpha_2 & \\alpha_1 & \\alpha_0 \\\\\n", + "\t\t\t 0 & 0 & \\alpha_2 & \\alpha_1 \\\\\n", + "\t\t\t 0 & 0 & 0 & \\alpha_2\n", + "\t\t\t \\end{bmatrix}\\begin{bmatrix} \\beta_0 \\\\ \\beta_1 \\\\ \\beta_2 \\\\ \\beta_3\\end{bmatrix}.\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "0c73a726", + "metadata": { + "editable": true + }, + "source": [ + "The process is commutative and we can easily see that we can rewrite the multiplication in terms of a matrix holding $\\beta$ and a vector holding $\\alpha$.\n", + "In this case we have" + ] + }, + { + "cell_type": "markdown", + "id": "81bc84d0", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "\\boldsymbol{\\delta}=\\begin{bmatrix}\\beta_0 & 0 & 0 \\\\\n", + " \\beta_1 & \\beta_0 & 0 \\\\\n", + "\t\t\t \\beta_2 & \\beta_1 & \\beta_0 \\\\\n", + "\t\t\t \\beta_3 & \\beta_2 & \\beta_1 \\\\\n", + "\t\t\t 0 & \\beta_3 & \\beta_2 \\\\\n", + "\t\t\t 0 & 0 & \\beta_3\n", + "\t\t\t \\end{bmatrix}\\begin{bmatrix} \\alpha_0 \\\\ \\alpha_1 \\\\ \\alpha_2\\end{bmatrix}.\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "6f314582", + "metadata": { + "editable": true + }, + "source": [ + "Note that the use of these matrices is for mathematical purposes only and not implementation purposes.\n", + "When implementing the above equation we do not encode (and allocate memory) the matrices explicitely.\n", + "We rather code the convolutions in the minimal memory footprint that they require.\n", + "\n", + "Does the number of floating point operations change here when we use the commutative property?" + ] + }, + { + "cell_type": "markdown", + "id": "e01eb276", + "metadata": { + "editable": true + }, + "source": [ + "### Convolution Examples: Principle of Superposition and Periodic Forces (Fourier Transforms)\n", + "\n", + "For problems with so-called harmonic oscillations, given by for example the following differential equation" + ] + }, + { + "cell_type": "markdown", + "id": "1016b422", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "m\\frac{d^2x}{dt^2}+\\eta\\frac{dx}{dt}+x(t)=F(t),\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "c237cb74", + "metadata": { + "editable": true + }, + "source": [ + "where $F(t)$ is an applied external force acting on the system (often called a driving force), one can use the theory of Fourier transformations to find the solutions of this type of equations.\n", + "\n", + "If one has several driving forces, $F(t)=\\sum_n F_n(t)$, one can find\n", + "the particular solution to each $F_n$, $x_{pn}(t)$, and the particular\n", + "solution for the entire driving force is then given by a series like" + ] + }, + { + "cell_type": "markdown", + "id": "4f2f2089", + "metadata": { + "editable": true + }, + "source": [ + "\n", + "
\n", + "\n", + "$$\n", + "\\begin{equation}\n", + "x_p(t)=\\sum_nx_{pn}(t).\n", + "\\label{_auto1} \\tag{1}\n", + "\\end{equation}\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "a32fa928", + "metadata": { + "editable": true + }, + "source": [ + "This is known as the principle of superposition. It only applies when\n", + "the homogenous equation is linear. If there were an anharmonic term\n", + "such as $x^3$ in the homogenous equation, then when one summed various\n", + "solutions, $x=(\\sum_n x_n)^2$, one would get cross\n", + "terms. Superposition is especially useful when $F(t)$ can be written\n", + "as a sum of sinusoidal terms, because the solutions for each\n", + "sinusoidal (sine or cosine) term is analytic. \n", + "\n", + "Driving forces are often periodic, even when they are not\n", + "sinusoidal. Periodicity implies that for some time $\\tau$" + ] + }, + { + "cell_type": "markdown", + "id": "0b6ca2c5", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "\\begin{eqnarray}\n", + "F(t+\\tau)=F(t). \n", + "\\end{eqnarray}\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "789cd636", + "metadata": { + "editable": true + }, + "source": [ + "One example of a non-sinusoidal periodic force is a square wave. Many\n", + "components in electric circuits are non-linear, e.g. diodes, which\n", + "makes many wave forms non-sinusoidal even when the circuits are being\n", + "driven by purely sinusoidal sources.\n", + "\n", + "The code here shows a typical example of such a square wave generated using the functionality included in the **scipy** Python package. We have used a period of $\\tau=0.2$." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "2c90eb89", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "%matplotlib inline\n", + "\n", + "import numpy as np\n", + "import math\n", + "from scipy import signal\n", + "import matplotlib.pyplot as plt\n", + "\n", + "# number of points \n", + "n = 500\n", + "# start and final times \n", + "t0 = 0.0\n", + "tn = 1.0\n", + "# Period \n", + "t = np.linspace(t0, tn, n, endpoint=False)\n", + "SqrSignal = np.zeros(n)\n", + "SqrSignal = 1.0+signal.square(2*np.pi*5*t)\n", + "plt.plot(t, SqrSignal)\n", + "plt.ylim(-0.5, 2.5)\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "8e7b8f5c", + "metadata": { + "editable": true + }, + "source": [ + "For the sinusoidal example the\n", + "period is $\\tau=2\\pi/\\omega$. However, higher harmonics can also\n", + "satisfy the periodicity requirement. In general, any force that\n", + "satisfies the periodicity requirement can be expressed as a sum over\n", + "harmonics," + ] + }, + { + "cell_type": "markdown", + "id": "4453c025", + "metadata": { + "editable": true + }, + "source": [ + "\n", + "
\n", + "\n", + "$$\n", + "\\begin{equation}\n", + "F(t)=\\frac{f_0}{2}+\\sum_{n>0} f_n\\cos(2n\\pi t/\\tau)+g_n\\sin(2n\\pi t/\\tau).\n", + "\\label{_auto2} \\tag{2}\n", + "\\end{equation}\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "32d5f410", + "metadata": { + "editable": true + }, + "source": [ + "We can write down the answer for\n", + "$x_{pn}(t)$, by substituting $f_n/m$ or $g_n/m$ for $F_0/m$. By\n", + "writing each factor $2n\\pi t/\\tau$ as $n\\omega t$, with $\\omega\\equiv\n", + "2\\pi/\\tau$," + ] + }, + { + "cell_type": "markdown", + "id": "4a58698d", + "metadata": { + "editable": true + }, + "source": [ + "\n", + "
\n", + "\n", + "$$\n", + "\\begin{equation}\n", + "\\label{eq:fourierdef1} \\tag{3}\n", + "F(t)=\\frac{f_0}{2}+\\sum_{n>0}f_n\\cos(n\\omega t)+g_n\\sin(n\\omega t).\n", + "\\end{equation}\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "5664f63d", + "metadata": { + "editable": true + }, + "source": [ + "The solutions for $x(t)$ then come from replacing $\\omega$ with\n", + "$n\\omega$ for each term in the particular solution," + ] + }, + { + "cell_type": "markdown", + "id": "0d9a2811", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "\\begin{eqnarray}\n", + "x_p(t)&=&\\frac{f_0}{2k}+\\sum_{n>0} \\alpha_n\\cos(n\\omega t-\\delta_n)+\\beta_n\\sin(n\\omega t-\\delta_n),\\\\\n", + "\\nonumber\n", + "\\alpha_n&=&\\frac{f_n/m}{\\sqrt{((n\\omega)^2-\\omega_0^2)+4\\beta^2n^2\\omega^2}},\\\\\n", + "\\nonumber\n", + "\\beta_n&=&\\frac{g_n/m}{\\sqrt{((n\\omega)^2-\\omega_0^2)+4\\beta^2n^2\\omega^2}},\\\\\n", + "\\nonumber\n", + "\\delta_n&=&\\tan^{-1}\\left(\\frac{2\\beta n\\omega}{\\omega_0^2-n^2\\omega^2}\\right).\n", + "\\end{eqnarray}\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "ac8b5fff", + "metadata": { + "editable": true + }, + "source": [ + "Because the forces have been applied for a long time, any non-zero\n", + "damping eliminates the homogenous parts of the solution, so one need\n", + "only consider the particular solution for each $n$.\n", + "\n", + "The problem is considered solved if one can find expressions for the\n", + "coefficients $f_n$ and $g_n$, even though the solutions are expressed\n", + "as an infinite sum. The coefficients can be extracted from the\n", + "function $F(t)$ by" + ] + }, + { + "cell_type": "markdown", + "id": "5bb70ae9", + "metadata": { + "editable": true + }, + "source": [ + "\n", + "
\n", + "\n", + "$$\n", + "\\begin{eqnarray}\n", + "\\label{eq:fourierdef2} \\tag{4}\n", + "f_n&=&\\frac{2}{\\tau}\\int_{-\\tau/2}^{\\tau/2} dt~F(t)\\cos(2n\\pi t/\\tau),\\\\\n", + "\\nonumber\n", + "g_n&=&\\frac{2}{\\tau}\\int_{-\\tau/2}^{\\tau/2} dt~F(t)\\sin(2n\\pi t/\\tau).\n", + "\\end{eqnarray}\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "4f64082e", + "metadata": { + "editable": true + }, + "source": [ + "To check the consistency of these expressions and to verify\n", + "Eq. ([4](#eq:fourierdef2)), one can insert the expansion of $F(t)$ in\n", + "Eq. ([3](#eq:fourierdef1)) into the expression for the coefficients in\n", + "Eq. ([4](#eq:fourierdef2)) and see whether" + ] + }, + { + "cell_type": "markdown", + "id": "bdd9e4e8", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "\\begin{eqnarray}\n", + "f_n&=?&\\frac{2}{\\tau}\\int_{-\\tau/2}^{\\tau/2} dt~\\left\\{\n", + "\\frac{f_0}{2}+\\sum_{m>0}f_m\\cos(m\\omega t)+g_m\\sin(m\\omega t)\n", + "\\right\\}\\cos(n\\omega t).\n", + "\\end{eqnarray}\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "e64a4a4c", + "metadata": { + "editable": true + }, + "source": [ + "Immediately, one can throw away all the terms with $g_m$ because they\n", + "convolute an even and an odd function. The term with $f_0/2$\n", + "disappears because $\\cos(n\\omega t)$ is equally positive and negative\n", + "over the interval and will integrate to zero. For all the terms\n", + "$f_m\\cos(m\\omega t)$ appearing in the sum, one can use angle addition\n", + "formulas to see that $\\cos(m\\omega t)\\cos(n\\omega\n", + "t)=(1/2)(\\cos[(m+n)\\omega t]+\\cos[(m-n)\\omega t]$. This will integrate\n", + "to zero unless $m=n$. In that case the $m=n$ term gives" + ] + }, + { + "cell_type": "markdown", + "id": "d51a4f59", + "metadata": { + "editable": true + }, + "source": [ + "\n", + "
\n", + "\n", + "$$\n", + "\\begin{equation}\n", + "\\int_{-\\tau/2}^{\\tau/2}dt~\\cos^2(m\\omega t)=\\frac{\\tau}{2},\n", + "\\label{_auto3} \\tag{5}\n", + "\\end{equation}\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "44804e35", + "metadata": { + "editable": true + }, + "source": [ + "and" + ] + }, + { + "cell_type": "markdown", + "id": "7de0dbe5", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "\\begin{eqnarray}\n", + "f_n&=?&\\frac{2}{\\tau}\\int_{-\\tau/2}^{\\tau/2} dt~f_n/2\\\\\n", + "\\nonumber\n", + "&=&f_n~\\checkmark.\n", + "\\end{eqnarray}\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "4d1a02e0", + "metadata": { + "editable": true + }, + "source": [ + "The same method can be used to check for the consistency of $g_n$.\n", + "\n", + "The code here uses the Fourier series applied to a \n", + "square wave signal. The code here\n", + "visualizes the various approximations given by Fourier series compared\n", + "with a square wave with period $T=0.2$ (dimensionless time), width $0.1$ and max value of the force $F=2$. We\n", + "see that when we increase the number of components in the Fourier\n", + "series, the Fourier series approximation gets closer and closer to the\n", + "square wave signal." + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "4ae0ec42", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "import numpy as np\n", + "import math\n", + "from scipy import signal\n", + "import matplotlib.pyplot as plt\n", + "\n", + "# number of points \n", + "n = 500\n", + "# start and final times \n", + "t0 = 0.0\n", + "tn = 1.0\n", + "# Period \n", + "T =0.2\n", + "# Max value of square signal \n", + "Fmax= 2.0\n", + "# Width of signal \n", + "Width = 0.1\n", + "t = np.linspace(t0, tn, n, endpoint=False)\n", + "SqrSignal = np.zeros(n)\n", + "FourierSeriesSignal = np.zeros(n)\n", + "SqrSignal = 1.0+signal.square(2*np.pi*5*t+np.pi*Width/T)\n", + "a0 = Fmax*Width/T\n", + "FourierSeriesSignal = a0\n", + "Factor = 2.0*Fmax/np.pi\n", + "for i in range(1,500):\n", + " FourierSeriesSignal += Factor/(i)*np.sin(np.pi*i*Width/T)*np.cos(i*t*2*np.pi/T)\n", + "plt.plot(t, SqrSignal)\n", + "plt.plot(t, FourierSeriesSignal)\n", + "plt.ylim(-0.5, 2.5)\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "acd75ab0", + "metadata": { + "editable": true + }, + "source": [ + "## Two-dimensional Objects\n", + "\n", + "We often use convolutions over more than one dimension at a time. If\n", + "we have a two-dimensional image $I$ as input, we can have a **filter**\n", + "defined by a two-dimensional **kernel** $K$. This leads to an output $S$" + ] + }, + { + "cell_type": "markdown", + "id": "0cdf3af8", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "S_(i,j)=(I * K)(i,j) = \\sum_m\\sum_n I(m,n)K(i-m,j-n).\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "1640aae2", + "metadata": { + "editable": true + }, + "source": [ + "Convolution is a commutatitave process, which means we can rewrite this equation as" + ] + }, + { + "cell_type": "markdown", + "id": "11491f4c", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "S_(i,j)=(I * K)(i,j) = \\sum_m\\sum_n I(i-m,j-n)K(m,n).\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "a1e3ef9d", + "metadata": { + "editable": true + }, + "source": [ + "Normally the latter is more straightforward to implement in a machine elarning library since there is less variation in the range of values of $m$ and $n$.\n", + "\n", + "Many deep learning libraries implement cross-correlation instead of convolution" + ] + }, + { + "cell_type": "markdown", + "id": "919fb5e9", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "S_(i,j)=(I * K)(i,j) = \\sum_m\\sum_n I(i+m,j-+)K(m,n).\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "c42d55ac", + "metadata": { + "editable": true + }, + "source": [ + "## More on Dimensionalities\n", + "\n", + "In fields like signal processing (and imaging as well), one designs\n", + "so-called filters. These filters are defined by the convolutions and\n", + "are often hand-crafted. One may specify filters for smoothing, edge\n", + "detection, frequency reshaping, and similar operations. However with\n", + "neural networks the idea is to automatically learn the filters and use\n", + "many of them in conjunction with non-linear operations (activation\n", + "functions).\n", + "\n", + "As an example consider a neural network operating on sound sequence\n", + "data. Assume that we an input vector $\\boldsymbol{x}$ of length $d=10^6$. We\n", + "construct then a neural network with onle hidden layer only with\n", + "$10^4$ nodes. This means that we will have a weight matrix with\n", + "$10^4\\times 10^6=10^{10}$ weights to be determined, together with $10^4$ biases.\n", + "\n", + "Assume furthermore that we have an output layer which is meant to train whether the sound sequence represents a human voice (true) or something else (false).\n", + "It means that we have only one output node. But since this output node connects to $10^4$ nodes in the hidden layer, there are in total $10^4$ weights to be determined for the output layer, plus one bias. In total we have" + ] + }, + { + "cell_type": "markdown", + "id": "4ebd8c85", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "\\mathrm{NumberParameters}=10^{10}+10^4+10^4+1 \\approx 10^{10},\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "6d886fa7", + "metadata": { + "editable": true + }, + "source": [ + "that is ten billion parameters to determine." + ] + }, + { + "cell_type": "markdown", + "id": "cd3b731e", + "metadata": { + "editable": true + }, + "source": [ + "## Further Dimensionality Remarks\n", + "\n", + "In today’s architecture one can train such neural networks, however\n", + "this is a huge number of parameters for the task at hand. In general,\n", + "it is a very wasteful and inefficient use of dense matrices as\n", + "parameters. Just as importantly, such trained network parameters are\n", + "very specific for the type of input data on which they were trained\n", + "and the network is not likely to generalize easily to variations in\n", + "the input.\n", + "\n", + "The main principles that justify convolutions is locality of\n", + "information and repetion of patterns within the signal. Sound samples\n", + "of the input in adjacent spots are much more likely to affect each\n", + "other than those that are very far away. Similarly, sounds are\n", + "repeated in multiple times in the signal. While slightly simplistic,\n", + "reasoning about such a sound example demonstrates this. The same\n", + "principles then apply to images and other similar data." + ] + }, + { + "cell_type": "markdown", + "id": "fc38055c", + "metadata": { + "editable": true + }, + "source": [ + "## CNNs in more detail, building convolutional neural networks in Tensorflow and Keras\n", + "\n", + "As discussed above, CNNs are neural networks built from the assumption that the inputs\n", + "to the network are 2D images. This is important because the number of features or pixels in images\n", + "grows very fast with the image size, and an enormous number of weights and biases are needed in order to build an accurate network. \n", + "\n", + "As before, we still have our input, a hidden layer and an output. What's novel about convolutional networks\n", + "are the **convolutional** and **pooling** layers stacked in pairs between the input and the hidden layer.\n", + "In addition, the data is no longer represented as a 2D feature matrix, instead each input is a number of 2D\n", + "matrices, typically 1 for each color dimension (Red, Green, Blue). \n", + "\n", + "It means that to represent the entire\n", + "dataset of images, we require a 4D matrix or **tensor**. This tensor has the dimensions:" + ] + }, + { + "cell_type": "markdown", + "id": "c153f6eb", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "(n_{inputs},\\, n_{pixels, width},\\, n_{pixels, height},\\, depth) .\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "f45ab21d", + "metadata": { + "editable": true + }, + "source": [ + "### The MNIST dataset again\n", + "\n", + "The MNIST dataset consists of grayscale images with a pixel size of\n", + "$28\\times 28$, meaning we require $28 \\times 28 = 724$ weights to each\n", + "neuron in the first hidden layer.\n", + "\n", + "If we were to analyze images of size $128\\times 128$ we would require\n", + "$128 \\times 128 = 16384$ weights to each neuron. Even worse if we were\n", + "dealing with color images, as most images are, we have an image matrix\n", + "of size $128\\times 128$ for each color dimension (Red, Green, Blue),\n", + "meaning 3 times the number of weights $= 49152$ are required for every\n", + "single neuron in the first hidden layer.\n", + "\n", + "Images typically have strong local correlations, meaning that a small\n", + "part of the image varies little from its neighboring regions. If for\n", + "example we have an image of a blue car, we can roughly assume that a\n", + "small blue part of the image is surrounded by other blue regions.\n", + "\n", + "Therefore, instead of connecting every single pixel to a neuron in the\n", + "first hidden layer, as we have previously done with deep neural\n", + "networks, we can instead connect each neuron to a small part of the\n", + "image (in all 3 RGB depth dimensions). The size of each small area is\n", + "fixed, and known as a [receptive](https://en.wikipedia.org/wiki/Receptive_field).\n", + "\n", + "The layers of a convolutional neural network arrange neurons in 3D: width, height and depth. \n", + "The input image is typically a square matrix of depth 3. \n", + "\n", + "A **convolution** is performed on the image which outputs\n", + "a 3D volume of neurons. The weights to the input are arranged in a number of 2D matrices, known as **filters**.\n", + "\n", + "Each filter slides along the input image, taking the dot product\n", + "between each small part of the image and the filter, in all depth\n", + "dimensions. This is then passed through a non-linear function,\n", + "typically the **Rectified Linear (ReLu)** function, which serves as the\n", + "activation of the neurons in the first convolutional layer. This is\n", + "further passed through a **pooling layer**, which reduces the size of the\n", + "convolutional layer, e.g. by taking the maximum or average across some\n", + "small regions, and this serves as input to the next convolutional\n", + "layer." + ] + }, + { + "cell_type": "markdown", + "id": "4af74ca7", + "metadata": { + "editable": true + }, + "source": [ + "### Systematic reduction\n", + "\n", + "By systematically reducing the size of the input volume, through\n", + "convolution and pooling, the network should create representations of\n", + "small parts of the input, and then from them assemble representations\n", + "of larger areas. The final pooling layer is flattened to serve as\n", + "input to a hidden layer, such that each neuron in the final pooling\n", + "layer is connected to every single neuron in the hidden layer. This\n", + "then serves as input to the output layer, e.g. a softmax output for\n", + "classification." + ] + }, + { + "cell_type": "markdown", + "id": "2b435dc0", + "metadata": { + "editable": true + }, + "source": [ + "### Prerequisites: Collect and pre-process data" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "ffb4904f", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "# import necessary packages\n", + "import numpy as np\n", + "import matplotlib.pyplot as plt\n", + "from sklearn import datasets\n", + "\n", + "\n", + "# ensure the same random numbers appear every time\n", + "np.random.seed(0)\n", + "\n", + "# display images in notebook\n", + "%matplotlib inline\n", + "plt.rcParams['figure.figsize'] = (12,12)\n", + "\n", + "\n", + "# download MNIST dataset\n", + "digits = datasets.load_digits()\n", + "\n", + "# define inputs and labels\n", + "inputs = digits.images\n", + "labels = digits.target\n", + "\n", + "# RGB images have a depth of 3\n", + "# our images are grayscale so they should have a depth of 1\n", + "inputs = inputs[:,:,:,np.newaxis]\n", + "\n", + "print(\"inputs = (n_inputs, pixel_width, pixel_height, depth) = \" + str(inputs.shape))\n", + "print(\"labels = (n_inputs) = \" + str(labels.shape))\n", + "\n", + "\n", + "# choose some random images to display\n", + "n_inputs = len(inputs)\n", + "indices = np.arange(n_inputs)\n", + "random_indices = np.random.choice(indices, size=5)\n", + "\n", + "for i, image in enumerate(digits.images[random_indices]):\n", + " plt.subplot(1, 5, i+1)\n", + " plt.axis('off')\n", + " plt.imshow(image, cmap=plt.cm.gray_r, interpolation='nearest')\n", + " plt.title(\"Label: %d\" % digits.target[random_indices[i]])\n", + "plt.show()" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "bb2db46c", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "from tensorflow.keras import datasets, layers, models\n", + "from tensorflow.keras.layers import Input\n", + "from tensorflow.keras.models import Sequential #This allows appending layers to existing models\n", + "from tensorflow.keras.layers import Dense #This allows defining the characteristics of a particular layer\n", + "from tensorflow.keras import optimizers #This allows using whichever optimiser we want (sgd,adam,RMSprop)\n", + "from tensorflow.keras import regularizers #This allows using whichever regularizer we want (l1,l2,l1_l2)\n", + "from tensorflow.keras.utils import to_categorical #This allows using categorical cross entropy as the cost function\n", + "#from tensorflow.keras import Conv2D\n", + "#from tensorflow.keras import MaxPooling2D\n", + "#from tensorflow.keras import Flatten\n", + "\n", + "from sklearn.model_selection import train_test_split\n", + "\n", + "# representation of labels\n", + "labels = to_categorical(labels)\n", + "\n", + "# split into train and test data\n", + "# one-liner from scikit-learn library\n", + "train_size = 0.8\n", + "test_size = 1 - train_size\n", + "X_train, X_test, Y_train, Y_test = train_test_split(inputs, labels, train_size=train_size,\n", + " test_size=test_size)" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "100a8d6d", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "def create_convolutional_neural_network_keras(input_shape, receptive_field,\n", + " n_filters, n_neurons_connected, n_categories,\n", + " eta, lmbd):\n", + " model = Sequential()\n", + " model.add(layers.Conv2D(n_filters, (receptive_field, receptive_field), input_shape=input_shape, padding='same',\n", + " activation='relu', kernel_regularizer=regularizers.l2(lmbd)))\n", + " model.add(layers.MaxPooling2D(pool_size=(2, 2)))\n", + " model.add(layers.Flatten())\n", + " model.add(layers.Dense(n_neurons_connected, activation='relu', kernel_regularizer=regularizers.l2(lmbd)))\n", + " model.add(layers.Dense(n_categories, activation='softmax', kernel_regularizer=regularizers.l2(lmbd)))\n", + " \n", + " sgd = optimizers.SGD(lr=eta)\n", + " model.compile(loss='categorical_crossentropy', optimizer=sgd, metrics=['accuracy'])\n", + " \n", + " return model\n", + "\n", + "epochs = 100\n", + "batch_size = 100\n", + "input_shape = X_train.shape[1:4]\n", + "receptive_field = 3\n", + "n_filters = 10\n", + "n_neurons_connected = 50\n", + "n_categories = 10\n", + "\n", + "eta_vals = np.logspace(-5, 1, 7)\n", + "lmbd_vals = np.logspace(-5, 1, 7)" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "635da5a7", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "CNN_keras = np.zeros((len(eta_vals), len(lmbd_vals)), dtype=object)\n", + " \n", + "for i, eta in enumerate(eta_vals):\n", + " for j, lmbd in enumerate(lmbd_vals):\n", + " CNN = create_convolutional_neural_network_keras(input_shape, receptive_field,\n", + " n_filters, n_neurons_connected, n_categories,\n", + " eta, lmbd)\n", + " CNN.fit(X_train, Y_train, epochs=epochs, batch_size=batch_size, verbose=0)\n", + " scores = CNN.evaluate(X_test, Y_test)\n", + " \n", + " CNN_keras[i][j] = CNN\n", + " \n", + " print(\"Learning rate = \", eta)\n", + " print(\"Lambda = \", lmbd)\n", + " print(\"Test accuracy: %.3f\" % scores[1])\n", + " print()" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "df145244", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "# visual representation of grid search\n", + "# uses seaborn heatmap, could probably do this in matplotlib\n", + "import seaborn as sns\n", + "\n", + "sns.set()\n", + "\n", + "train_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))\n", + "test_accuracy = np.zeros((len(eta_vals), len(lmbd_vals)))\n", + "\n", + "for i in range(len(eta_vals)):\n", + " for j in range(len(lmbd_vals)):\n", + " CNN = CNN_keras[i][j]\n", + "\n", + " train_accuracy[i][j] = CNN.evaluate(X_train, Y_train)[1]\n", + " test_accuracy[i][j] = CNN.evaluate(X_test, Y_test)[1]\n", + "\n", + " \n", + "fig, ax = plt.subplots(figsize = (10, 10))\n", + "sns.heatmap(train_accuracy, annot=True, ax=ax, cmap=\"viridis\")\n", + "ax.set_title(\"Training Accuracy\")\n", + "ax.set_ylabel(\"$\\eta$\")\n", + "ax.set_xlabel(\"$\\lambda$\")\n", + "plt.show()\n", + "\n", + "fig, ax = plt.subplots(figsize = (10, 10))\n", + "sns.heatmap(test_accuracy, annot=True, ax=ax, cmap=\"viridis\")\n", + "ax.set_title(\"Test Accuracy\")\n", + "ax.set_ylabel(\"$\\eta$\")\n", + "ax.set_xlabel(\"$\\lambda$\")\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "a6724f1c", + "metadata": { + "editable": true + }, + "source": [ + "## The CIFAR01 data set\n", + "\n", + "The CIFAR10 dataset contains 60,000 color images in 10 classes, with\n", + "6,000 images in each class. The dataset is divided into 50,000\n", + "training images and 10,000 testing images. The classes are mutually\n", + "exclusive and there is no overlap between them." + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "id": "90c28005", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "import tensorflow as tf\n", + "\n", + "from tensorflow.keras import datasets, layers, models\n", + "import matplotlib.pyplot as plt\n", + "\n", + "# We import the data set\n", + "(train_images, train_labels), (test_images, test_labels) = datasets.cifar10.load_data()\n", + "\n", + "# Normalize pixel values to be between 0 and 1 by dividing by 255. \n", + "train_images, test_images = train_images / 255.0, test_images / 255.0" + ] + }, + { + "cell_type": "markdown", + "id": "759ea77a", + "metadata": { + "editable": true + }, + "source": [ + "To verify that the dataset looks correct, let's plot the first 25 images from the training set and display the class name below each image." + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "id": "494edadd", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "class_names = ['airplane', 'automobile', 'bird', 'cat', 'deer',\n", + " 'dog', 'frog', 'horse', 'ship', 'truck']\n", + "​\n", + "plt.figure(figsize=(10,10))\n", + "for i in range(25):\n", + " plt.subplot(5,5,i+1)\n", + " plt.xticks([])\n", + " plt.yticks([])\n", + " plt.grid(False)\n", + " plt.imshow(train_images[i], cmap=plt.cm.binary)\n", + " # The CIFAR labels happen to be arrays, \n", + " # which is why you need the extra index\n", + " plt.xlabel(class_names[train_labels[i][0]])\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "46d2ea5d", + "metadata": { + "editable": true + }, + "source": [ + "The six lines of code below define the convolutional base using a common pattern: a stack of Conv2D and MaxPooling2D layers.\n", + "\n", + "As input, a CNN takes tensors of shape (image_height, image_width, color_channels), ignoring the batch size. If you are new to these dimensions, color_channels refers to (R,G,B). In this example, you will configure our CNN to process inputs of shape (32, 32, 3), which is the format of CIFAR images. You can do this by passing the argument input_shape to our first layer." + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "id": "044310ec", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "model = models.Sequential()\n", + "model.add(layers.Conv2D(32, (3, 3), activation='relu', input_shape=(32, 32, 3)))\n", + "model.add(layers.MaxPooling2D((2, 2)))\n", + "model.add(layers.Conv2D(64, (3, 3), activation='relu'))\n", + "model.add(layers.MaxPooling2D((2, 2)))\n", + "model.add(layers.Conv2D(64, (3, 3), activation='relu'))\n", + "\n", + "# Let's display the architecture of our model so far.\n", + "\n", + "model.summary()" + ] + }, + { + "cell_type": "markdown", + "id": "738f34a7", + "metadata": { + "editable": true + }, + "source": [ + "You can see that the output of every Conv2D and MaxPooling2D layer is a 3D tensor of shape (height, width, channels). The width and height dimensions tend to shrink as you go deeper in the network. The number of output channels for each Conv2D layer is controlled by the first argument (e.g., 32 or 64). Typically, as the width and height shrink, you can afford (computationally) to add more output channels in each Conv2D layer.\n", + "\n", + "To complete our model, you will feed the last output tensor from the\n", + "convolutional base (of shape (4, 4, 64)) into one or more Dense layers\n", + "to perform classification. Dense layers take vectors as input (which\n", + "are 1D), while the current output is a 3D tensor. First, you will\n", + "flatten (or unroll) the 3D output to 1D, then add one or more Dense\n", + "layers on top. CIFAR has 10 output classes, so you use a final Dense\n", + "layer with 10 outputs and a softmax activation." + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "id": "e0fea435", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "model.add(layers.Flatten())\n", + "model.add(layers.Dense(64, activation='relu'))\n", + "model.add(layers.Dense(10))\n", + "Here's the complete architecture of our model.\n", + "\n", + "model.summary()" + ] + }, + { + "cell_type": "markdown", + "id": "62f1e50d", + "metadata": { + "editable": true + }, + "source": [ + "As you can see, our (4, 4, 64) outputs were flattened into vectors of shape (1024) before going through two Dense layers." + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "id": "e2d8f4f2", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "model.compile(optimizer='adam',\n", + " loss=tf.keras.losses.SparseCategoricalCrossentropy(from_logits=True),\n", + " metrics=['accuracy'])\n", + "​\n", + "history = model.fit(train_images, train_labels, epochs=10, \n", + " validation_data=(test_images, test_labels))" + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "id": "d2965f40", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "plt.plot(history.history['accuracy'], label='accuracy')\n", + "plt.plot(history.history['val_accuracy'], label = 'val_accuracy')\n", + "plt.xlabel('Epoch')\n", + "plt.ylabel('Accuracy')\n", + "plt.ylim([0.5, 1])\n", + "plt.legend(loc='lower right')\n", + "\n", + "test_loss, test_acc = model.evaluate(test_images, test_labels, verbose=2)\n", + "\n", + "print(test_acc)" + ] + } + ], + "metadata": {}, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/doc/LectureNotes/chapter13.ipynb b/doc/LectureNotes/chapter13.ipynb new file mode 100644 index 000000000..7d78135c1 --- /dev/null +++ b/doc/LectureNotes/chapter13.ipynb @@ -0,0 +1,1873 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "6d2db899", + "metadata": { + "editable": true + }, + "source": [ + "" + ] + }, + { + "cell_type": "markdown", + "id": "f4908a97", + "metadata": { + "editable": true + }, + "source": [ + "# Recurrent neural networks: Overarching view\n", + "\n", + "Till now our focus has been, including convolutional neural networks\n", + "as well, on feedforward neural networks. The output or the activations\n", + "flow only in one direction, from the input layer to the output layer.\n", + "\n", + "A recurrent neural network (RNN) looks very much like a feedforward\n", + "neural network, except that it also has connections pointing\n", + "backward. \n", + "\n", + "RNNs are used to analyze time series data such as stock prices, and\n", + "tell you when to buy or sell. In autonomous driving systems, they can\n", + "anticipate car trajectories and help avoid accidents. More generally,\n", + "they can work on sequences of arbitrary lengths, rather than on\n", + "fixed-sized inputs like all the nets we have discussed so far. For\n", + "example, they can take sentences, documents, or audio samples as\n", + "input, making them extremely useful for natural language processing\n", + "systems such as automatic translation and speech-to-text.\n", + "\n", + "More to text to be added" + ] + }, + { + "cell_type": "markdown", + "id": "43cb4913", + "metadata": { + "editable": true + }, + "source": [ + "## A simple example" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "cf6b9dab", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "%matplotlib inline\n", + "\n", + "# Start importing packages\n", + "import pandas as pd\n", + "import numpy as np\n", + "import matplotlib.pyplot as plt\n", + "import tensorflow as tf\n", + "from tensorflow.keras import datasets, layers, models\n", + "from tensorflow.keras.layers import Input\n", + "from tensorflow.keras.models import Model, Sequential \n", + "from tensorflow.keras.layers import Dense, SimpleRNN, LSTM, GRU\n", + "from tensorflow.keras import optimizers \n", + "from tensorflow.keras import regularizers \n", + "from tensorflow.keras.utils import to_categorical \n", + "\n", + "\n", + "\n", + "# convert into dataset matrix\n", + "def convertToMatrix(data, step):\n", + " X, Y =[], []\n", + " for i in range(len(data)-step):\n", + " d=i+step \n", + " X.append(data[i:d,])\n", + " Y.append(data[d,])\n", + " return np.array(X), np.array(Y)\n", + "\n", + "step = 4\n", + "N = 1000 \n", + "Tp = 800 \n", + "\n", + "t=np.arange(0,N)\n", + "x=np.sin(0.02*t)+2*np.random.rand(N)\n", + "df = pd.DataFrame(x)\n", + "df.head()\n", + "\n", + "plt.plot(df)\n", + "plt.show()\n", + "\n", + "values=df.values\n", + "train,test = values[0:Tp,:], values[Tp:N,:]\n", + "\n", + "# add step elements into train and test\n", + "test = np.append(test,np.repeat(test[-1,],step))\n", + "train = np.append(train,np.repeat(train[-1,],step))\n", + " \n", + "trainX,trainY =convertToMatrix(train,step)\n", + "testX,testY =convertToMatrix(test,step)\n", + "trainX = np.reshape(trainX, (trainX.shape[0], 1, trainX.shape[1]))\n", + "testX = np.reshape(testX, (testX.shape[0], 1, testX.shape[1]))\n", + "\n", + "model = Sequential()\n", + "model.add(SimpleRNN(units=32, input_shape=(1,step), activation=\"relu\"))\n", + "model.add(Dense(8, activation=\"relu\")) \n", + "model.add(Dense(1))\n", + "model.compile(loss='mean_squared_error', optimizer='rmsprop')\n", + "model.summary()\n", + "\n", + "model.fit(trainX,trainY, epochs=100, batch_size=16, verbose=2)\n", + "trainPredict = model.predict(trainX)\n", + "testPredict= model.predict(testX)\n", + "predicted=np.concatenate((trainPredict,testPredict),axis=0)\n", + "\n", + "trainScore = model.evaluate(trainX, trainY, verbose=0)\n", + "print(trainScore)\n", + "\n", + "index = df.index.values\n", + "plt.plot(index,df)\n", + "plt.plot(index,predicted)\n", + "plt.axvline(df.index[Tp], c=\"r\")\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "897a47c7", + "metadata": { + "editable": true + }, + "source": [ + "## An extrapolation example\n", + "\n", + "The following code provides an example of how recurrent neural\n", + "networks can be used to extrapolate to unknown values of physics data\n", + "sets. Specifically, the data sets used in this program come from\n", + "a quantum mechanical many-body calculation of energies as functions of the number of particles." + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "6776ae2a", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "\n", + "# For matrices and calculations\n", + "import numpy as np\n", + "# For machine learning (backend for keras)\n", + "import tensorflow as tf\n", + "# User-friendly machine learning library\n", + "# Front end for TensorFlow\n", + "import tensorflow.keras\n", + "# Different methods from Keras needed to create an RNN\n", + "# This is not necessary but it shortened function calls \n", + "# that need to be used in the code.\n", + "from tensorflow.keras import datasets, layers, models\n", + "from tensorflow.keras.layers import Input\n", + "from tensorflow.keras import regularizers\n", + "from tensorflow.keras.models import Model, Sequential\n", + "from tensorflow.keras.layers import Dense, SimpleRNN, LSTM, GRU\n", + "# For timing the code\n", + "from timeit import default_timer as timer\n", + "# For plotting\n", + "import matplotlib.pyplot as plt\n", + "\n", + "\n", + "# The data set\n", + "datatype='VaryDimension'\n", + "X_tot = np.arange(2, 42, 2)\n", + "y_tot = np.array([-0.03077640549, -0.08336233266, -0.1446729567, -0.2116753732, -0.2830637392, -0.3581341341, -0.436462435, -0.5177783846,\n", + "\t-0.6019067271, -0.6887363571, -0.7782028952, -0.8702784034, -0.9649652536, -1.062292565, -1.16231451, \n", + "\t-1.265109911, -1.370782966, -1.479465113, -1.591317992, -1.70653767])" + ] + }, + { + "cell_type": "markdown", + "id": "35227d36", + "metadata": { + "editable": true + }, + "source": [ + "The way the recurrent neural networks are trained in this program\n", + "differs from how machine learning algorithms are usually trained.\n", + "Typically a machine learning algorithm is trained by learning the\n", + "relationship between the x data and the y data. In this program, the\n", + "recurrent neural network will be trained to recognize the relationship\n", + "in a sequence of y values. This is type of data formatting is\n", + "typically used time series forcasting, but it can also be used in any\n", + "extrapolation (time series forecasting is just a specific type of\n", + "extrapolation along the time axis). This method of data formatting\n", + "does not use the x data and assumes that the y data are evenly spaced.\n", + "\n", + "For a standard machine learning algorithm, the training data has the\n", + "form of (x,y) so the machine learning algorithm learns to assiciate a\n", + "y value with a given x value. This is useful when the test data has x\n", + "values within the same range as the training data. However, for this\n", + "application, the x values of the test data are outside of the x values\n", + "of the training data and the traditional method of training a machine\n", + "learning algorithm does not work as well. For this reason, the\n", + "recurrent neural network is trained on sequences of y values of the\n", + "form ((y1, y2), y3), so that the network is concerned with learning\n", + "the pattern of the y data and not the relation between the x and y\n", + "data. As long as the pattern of y data outside of the training region\n", + "stays relatively stable compared to what was inside the training\n", + "region, this method of training can produce accurate extrapolations to\n", + "y values far removed from the training data set." + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "7dc577d1", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "# FORMAT_DATA\n", + "def format_data(data, length_of_sequence = 2): \n", + " \"\"\"\n", + " Inputs:\n", + " data(a numpy array): the data that will be the inputs to the recurrent neural\n", + " network\n", + " length_of_sequence (an int): the number of elements in one iteration of the\n", + " sequence patter. For a function approximator use length_of_sequence = 2.\n", + " Returns:\n", + " rnn_input (a 3D numpy array): the input data for the recurrent neural network. Its\n", + " dimensions are length of data - length of sequence, length of sequence, \n", + " dimnsion of data\n", + " rnn_output (a numpy array): the training data for the neural network\n", + " Formats data to be used in a recurrent neural network.\n", + " \"\"\"\n", + "\n", + " X, Y = [], []\n", + " for i in range(len(data)-length_of_sequence):\n", + " # Get the next length_of_sequence elements\n", + " a = data[i:i+length_of_sequence]\n", + " # Get the element that immediately follows that\n", + " b = data[i+length_of_sequence]\n", + " # Reshape so that each data point is contained in its own array\n", + " a = np.reshape (a, (len(a), 1))\n", + " X.append(a)\n", + " Y.append(b)\n", + " rnn_input = np.array(X)\n", + " rnn_output = np.array(Y)\n", + "\n", + " return rnn_input, rnn_output\n", + "\n", + "\n", + "# ## Defining the Recurrent Neural Network Using Keras\n", + "# \n", + "# The following method defines a simple recurrent neural network in keras consisting of one input layer, one hidden layer, and one output layer.\n", + "\n", + "def rnn(length_of_sequences, batch_size = None, stateful = False):\n", + " \"\"\"\n", + " Inputs:\n", + " length_of_sequences (an int): the number of y values in \"x data\". This is determined\n", + " when the data is formatted\n", + " batch_size (an int): Default value is None. See Keras documentation of SimpleRNN.\n", + " stateful (a boolean): Default value is False. See Keras documentation of SimpleRNN.\n", + " Returns:\n", + " model (a Keras model): The recurrent neural network that is built and compiled by this\n", + " method\n", + " Builds and compiles a recurrent neural network with one hidden layer and returns the model.\n", + " \"\"\"\n", + " # Number of neurons in the input and output layers\n", + " in_out_neurons = 1\n", + " # Number of neurons in the hidden layer\n", + " hidden_neurons = 200\n", + " # Define the input layer\n", + " inp = Input(batch_shape=(batch_size, \n", + " length_of_sequences, \n", + " in_out_neurons)) \n", + " # Define the hidden layer as a simple RNN layer with a set number of neurons and add it to \n", + " # the network immediately after the input layer\n", + " rnn = SimpleRNN(hidden_neurons, \n", + " return_sequences=False,\n", + " stateful = stateful,\n", + " name=\"RNN\")(inp)\n", + " # Define the output layer as a dense neural network layer (standard neural network layer)\n", + " #and add it to the network immediately after the hidden layer.\n", + " dens = Dense(in_out_neurons,name=\"dense\")(rnn)\n", + " # Create the machine learning model starting with the input layer and ending with the \n", + " # output layer\n", + " model = Model(inputs=[inp],outputs=[dens])\n", + " # Compile the machine learning model using the mean squared error function as the loss \n", + " # function and an Adams optimizer.\n", + " model.compile(loss=\"mean_squared_error\", optimizer=\"adam\") \n", + " return model" + ] + }, + { + "cell_type": "markdown", + "id": "1978b6a1", + "metadata": { + "editable": true + }, + "source": [ + "## Predicting New Points With A Trained Recurrent Neural Network" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "d4ad417a", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "def test_rnn (x1, y_test, plot_min, plot_max):\n", + " \"\"\"\n", + " Inputs:\n", + " x1 (a list or numpy array): The complete x component of the data set\n", + " y_test (a list or numpy array): The complete y component of the data set\n", + " plot_min (an int or float): the smallest x value used in the training data\n", + " plot_max (an int or float): the largest x valye used in the training data\n", + " Returns:\n", + " None.\n", + " Uses a trained recurrent neural network model to predict future points in the \n", + " series. Computes the MSE of the predicted data set from the true data set, saves\n", + " the predicted data set to a csv file, and plots the predicted and true data sets w\n", + " while also displaying the data range used for training.\n", + " \"\"\"\n", + " # Add the training data as the first dim points in the predicted data array as these\n", + " # are known values.\n", + " y_pred = y_test[:dim].tolist()\n", + " # Generate the first input to the trained recurrent neural network using the last two \n", + " # points of the training data. Based on how the network was trained this means that it\n", + " # will predict the first point in the data set after the training data. All of the \n", + " # brackets are necessary for Tensorflow.\n", + " next_input = np.array([[[y_test[dim-2]], [y_test[dim-1]]]])\n", + " # Save the very last point in the training data set. This will be used later.\n", + " last = [y_test[dim-1]]\n", + "\n", + " # Iterate until the complete data set is created.\n", + " for i in range (dim, len(y_test)):\n", + " # Predict the next point in the data set using the previous two points.\n", + " next = model.predict(next_input)\n", + " # Append just the number of the predicted data set\n", + " y_pred.append(next[0][0])\n", + " # Create the input that will be used to predict the next data point in the data set.\n", + " next_input = np.array([[last, next[0]]], dtype=np.float64)\n", + " last = next\n", + "\n", + " # Print the mean squared error between the known data set and the predicted data set.\n", + " print('MSE: ', np.square(np.subtract(y_test, y_pred)).mean())\n", + " # Save the predicted data set as a csv file for later use\n", + " name = datatype + 'Predicted'+str(dim)+'.csv'\n", + " np.savetxt(name, y_pred, delimiter=',')\n", + " # Plot the known data set and the predicted data set. The red box represents the region that was used\n", + " # for the training data.\n", + " fig, ax = plt.subplots()\n", + " ax.plot(x1, y_test, label=\"true\", linewidth=3)\n", + " ax.plot(x1, y_pred, 'g-.',label=\"predicted\", linewidth=4)\n", + " ax.legend()\n", + " # Created a red region to represent the points used in the training data.\n", + " ax.axvspan(plot_min, plot_max, alpha=0.25, color='red')\n", + " plt.show()\n", + "\n", + "# Check to make sure the data set is complete\n", + "assert len(X_tot) == len(y_tot)\n", + "\n", + "# This is the number of points that will be used in as the training data\n", + "dim=12\n", + "\n", + "# Separate the training data from the whole data set\n", + "X_train = X_tot[:dim]\n", + "y_train = y_tot[:dim]\n", + "\n", + "\n", + "# Generate the training data for the RNN, using a sequence of 2\n", + "rnn_input, rnn_training = format_data(y_train, 2)\n", + "\n", + "\n", + "# Create a recurrent neural network in Keras and produce a summary of the \n", + "# machine learning model\n", + "model = rnn(length_of_sequences = rnn_input.shape[1])\n", + "model.summary()\n", + "\n", + "# Start the timer. Want to time training+testing\n", + "start = timer()\n", + "# Fit the model using the training data genenerated above using 150 training iterations and a 5%\n", + "# validation split. Setting verbose to True prints information about each training iteration.\n", + "hist = model.fit(rnn_input, rnn_training, batch_size=None, epochs=150, \n", + " verbose=True,validation_split=0.05)\n", + "\n", + "for label in [\"loss\",\"val_loss\"]:\n", + " plt.plot(hist.history[label],label=label)\n", + "\n", + "plt.ylabel(\"loss\")\n", + "plt.xlabel(\"epoch\")\n", + "plt.title(\"The final validation loss: {}\".format(hist.history[\"val_loss\"][-1]))\n", + "plt.legend()\n", + "plt.show()\n", + "\n", + "# Use the trained neural network to predict more points of the data set\n", + "test_rnn(X_tot, y_tot, X_tot[0], X_tot[dim-1])\n", + "# Stop the timer and calculate the total time needed.\n", + "end = timer()\n", + "print('Time: ', end-start)" + ] + }, + { + "cell_type": "markdown", + "id": "e2cad4fc", + "metadata": { + "editable": true + }, + "source": [ + "Changing the size of the recurrent neural network and its parameters\n", + "can drastically change the results you get from the model. The below\n", + "code takes the simple recurrent neural network from above and adds a\n", + "second hidden layer, changes the number of neurons in the hidden\n", + "layer, and explicitly declares the activation function of the hidden\n", + "layers to be a sigmoid function. The loss function and optimizer can\n", + "also be changed but are kept the same as the above network. These\n", + "parameters can be tuned to provide the optimal result from the\n", + "network. For some ideas on how to improve the performance of a\n", + "[recurrent neural network](https://danijar.com/tips-for-training-recurrent-neural-networks)." + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "c39f1516", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "def rnn_2layers(length_of_sequences, batch_size = None, stateful = False):\n", + " \"\"\"\n", + " Inputs:\n", + " length_of_sequences (an int): the number of y values in \"x data\". This is determined\n", + " when the data is formatted\n", + " batch_size (an int): Default value is None. See Keras documentation of SimpleRNN.\n", + " stateful (a boolean): Default value is False. See Keras documentation of SimpleRNN.\n", + " Returns:\n", + " model (a Keras model): The recurrent neural network that is built and compiled by this\n", + " method\n", + " Builds and compiles a recurrent neural network with two hidden layers and returns the model.\n", + " \"\"\"\n", + " # Number of neurons in the input and output layers\n", + " in_out_neurons = 1\n", + " # Number of neurons in the hidden layer, increased from the first network\n", + " hidden_neurons = 500\n", + " # Define the input layer\n", + " inp = Input(batch_shape=(batch_size, \n", + " length_of_sequences, \n", + " in_out_neurons)) \n", + " # Create two hidden layers instead of one hidden layer. Explicitly set the activation\n", + " # function to be the sigmoid function (the default value is hyperbolic tangent)\n", + " rnn1 = SimpleRNN(hidden_neurons, \n", + " return_sequences=True, # This needs to be True if another hidden layer is to follow\n", + " stateful = stateful, activation = 'sigmoid',\n", + " name=\"RNN1\")(inp)\n", + " rnn2 = SimpleRNN(hidden_neurons, \n", + " return_sequences=False, activation = 'sigmoid',\n", + " stateful = stateful,\n", + " name=\"RNN2\")(rnn1)\n", + " # Define the output layer as a dense neural network layer (standard neural network layer)\n", + " #and add it to the network immediately after the hidden layer.\n", + " dens = Dense(in_out_neurons,name=\"dense\")(rnn2)\n", + " # Create the machine learning model starting with the input layer and ending with the \n", + " # output layer\n", + " model = Model(inputs=[inp],outputs=[dens])\n", + " # Compile the machine learning model using the mean squared error function as the loss \n", + " # function and an Adams optimizer.\n", + " model.compile(loss=\"mean_squared_error\", optimizer=\"adam\") \n", + " return model\n", + "\n", + "# Check to make sure the data set is complete\n", + "assert len(X_tot) == len(y_tot)\n", + "\n", + "# This is the number of points that will be used in as the training data\n", + "dim=12\n", + "\n", + "# Separate the training data from the whole data set\n", + "X_train = X_tot[:dim]\n", + "y_train = y_tot[:dim]\n", + "\n", + "\n", + "# Generate the training data for the RNN, using a sequence of 2\n", + "rnn_input, rnn_training = format_data(y_train, 2)\n", + "\n", + "\n", + "# Create a recurrent neural network in Keras and produce a summary of the \n", + "# machine learning model\n", + "model = rnn_2layers(length_of_sequences = 2)\n", + "model.summary()\n", + "\n", + "# Start the timer. Want to time training+testing\n", + "start = timer()\n", + "# Fit the model using the training data genenerated above using 150 training iterations and a 5%\n", + "# validation split. Setting verbose to True prints information about each training iteration.\n", + "hist = model.fit(rnn_input, rnn_training, batch_size=None, epochs=150, \n", + " verbose=True,validation_split=0.05)\n", + "\n", + "\n", + "# This section plots the training loss and the validation loss as a function of training iteration.\n", + "# This is not required for analyzing the couple cluster data but can help determine if the network is\n", + "# being overtrained.\n", + "for label in [\"loss\",\"val_loss\"]:\n", + " plt.plot(hist.history[label],label=label)\n", + "\n", + "plt.ylabel(\"loss\")\n", + "plt.xlabel(\"epoch\")\n", + "plt.title(\"The final validation loss: {}\".format(hist.history[\"val_loss\"][-1]))\n", + "plt.legend()\n", + "plt.show()\n", + "\n", + "# Use the trained neural network to predict more points of the data set\n", + "test_rnn(X_tot, y_tot, X_tot[0], X_tot[dim-1])\n", + "# Stop the timer and calculate the total time needed.\n", + "end = timer()\n", + "print('Time: ', end-start)" + ] + }, + { + "cell_type": "markdown", + "id": "842c7602", + "metadata": { + "editable": true + }, + "source": [ + "## Other Types of Recurrent Neural Networks\n", + "\n", + "Besides a simple recurrent neural network layer, there are two other\n", + "commonly used types of recurrent neural network layers: Long Short\n", + "Term Memory (LSTM) and Gated Recurrent Unit (GRU). For a short\n", + "introduction to these layers see \n", + "and .\n", + "\n", + "The first network created below is similar to the previous network,\n", + "but it replaces the SimpleRNN layers with LSTM layers. The second\n", + "network below has two hidden layers made up of GRUs, which are\n", + "preceeded by two dense (feeddorward) neural network layers. These\n", + "dense layers \"preprocess\" the data before it reaches the recurrent\n", + "layers. This architecture has been shown to improve the performance\n", + "of recurrent neural networks (see the link above and also\n", + "." + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "6f0e9b62", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "def lstm_2layers(length_of_sequences, batch_size = None, stateful = False):\n", + " \"\"\"\n", + " Inputs:\n", + " length_of_sequences (an int): the number of y values in \"x data\". This is determined\n", + " when the data is formatted\n", + " batch_size (an int): Default value is None. See Keras documentation of SimpleRNN.\n", + " stateful (a boolean): Default value is False. See Keras documentation of SimpleRNN.\n", + " Returns:\n", + " model (a Keras model): The recurrent neural network that is built and compiled by this\n", + " method\n", + " Builds and compiles a recurrent neural network with two LSTM hidden layers and returns the model.\n", + " \"\"\"\n", + " # Number of neurons on the input/output layer and the number of neurons in the hidden layer\n", + " in_out_neurons = 1\n", + " hidden_neurons = 250\n", + " # Input Layer\n", + " inp = Input(batch_shape=(batch_size, \n", + " length_of_sequences, \n", + " in_out_neurons)) \n", + " # Hidden layers (in this case they are LSTM layers instead if SimpleRNN layers)\n", + " rnn= LSTM(hidden_neurons, \n", + " return_sequences=True,\n", + " stateful = stateful,\n", + " name=\"RNN\", use_bias=True, activation='tanh')(inp)\n", + " rnn1 = LSTM(hidden_neurons, \n", + " return_sequences=False,\n", + " stateful = stateful,\n", + " name=\"RNN1\", use_bias=True, activation='tanh')(rnn)\n", + " # Output layer\n", + " dens = Dense(in_out_neurons,name=\"dense\")(rnn1)\n", + " # Define the midel\n", + " model = Model(inputs=[inp],outputs=[dens])\n", + " # Compile the model\n", + " model.compile(loss='mean_squared_error', optimizer='adam') \n", + " # Return the model\n", + " return model\n", + "\n", + "def dnn2_gru2(length_of_sequences, batch_size = None, stateful = False):\n", + " \"\"\"\n", + " Inputs:\n", + " length_of_sequences (an int): the number of y values in \"x data\". This is determined\n", + " when the data is formatted\n", + " batch_size (an int): Default value is None. See Keras documentation of SimpleRNN.\n", + " stateful (a boolean): Default value is False. See Keras documentation of SimpleRNN.\n", + " Returns:\n", + " model (a Keras model): The recurrent neural network that is built and compiled by this\n", + " method\n", + " Builds and compiles a recurrent neural network with four hidden layers (two dense followed by\n", + " two GRU layers) and returns the model.\n", + " \"\"\" \n", + " # Number of neurons on the input/output layers and hidden layers\n", + " in_out_neurons = 1\n", + " hidden_neurons = 250\n", + " # Input layer\n", + " inp = Input(batch_shape=(batch_size, \n", + " length_of_sequences, \n", + " in_out_neurons)) \n", + " # Hidden Dense (feedforward) layers\n", + " dnn = Dense(hidden_neurons/2, activation='relu', name='dnn')(inp)\n", + " dnn1 = Dense(hidden_neurons/2, activation='relu', name='dnn1')(dnn)\n", + " # Hidden GRU layers\n", + " rnn1 = GRU(hidden_neurons, \n", + " return_sequences=True,\n", + " stateful = stateful,\n", + " name=\"RNN1\", use_bias=True)(dnn1)\n", + " rnn = GRU(hidden_neurons, \n", + " return_sequences=False,\n", + " stateful = stateful,\n", + " name=\"RNN\", use_bias=True)(rnn1)\n", + " # Output layer\n", + " dens = Dense(in_out_neurons,name=\"dense\")(rnn)\n", + " # Define the model\n", + " model = Model(inputs=[inp],outputs=[dens])\n", + " # Compile the mdoel\n", + " model.compile(loss='mean_squared_error', optimizer='adam') \n", + " # Return the model\n", + " return model\n", + "\n", + "# Check to make sure the data set is complete\n", + "assert len(X_tot) == len(y_tot)\n", + "\n", + "# This is the number of points that will be used in as the training data\n", + "dim=12\n", + "\n", + "# Separate the training data from the whole data set\n", + "X_train = X_tot[:dim]\n", + "y_train = y_tot[:dim]\n", + "\n", + "\n", + "# Generate the training data for the RNN, using a sequence of 2\n", + "rnn_input, rnn_training = format_data(y_train, 2)\n", + "\n", + "\n", + "# Create a recurrent neural network in Keras and produce a summary of the \n", + "# machine learning model\n", + "# Change the method name to reflect which network you want to use\n", + "model = dnn2_gru2(length_of_sequences = 2)\n", + "model.summary()\n", + "\n", + "# Start the timer. Want to time training+testing\n", + "start = timer()\n", + "# Fit the model using the training data genenerated above using 150 training iterations and a 5%\n", + "# validation split. Setting verbose to True prints information about each training iteration.\n", + "hist = model.fit(rnn_input, rnn_training, batch_size=None, epochs=150, \n", + " verbose=True,validation_split=0.05)\n", + "\n", + "\n", + "# This section plots the training loss and the validation loss as a function of training iteration.\n", + "# This is not required for analyzing the couple cluster data but can help determine if the network is\n", + "# being overtrained.\n", + "for label in [\"loss\",\"val_loss\"]:\n", + " plt.plot(hist.history[label],label=label)\n", + "\n", + "plt.ylabel(\"loss\")\n", + "plt.xlabel(\"epoch\")\n", + "plt.title(\"The final validation loss: {}\".format(hist.history[\"val_loss\"][-1]))\n", + "plt.legend()\n", + "plt.show()\n", + "\n", + "# Use the trained neural network to predict more points of the data set\n", + "test_rnn(X_tot, y_tot, X_tot[0], X_tot[dim-1])\n", + "# Stop the timer and calculate the total time needed.\n", + "end = timer()\n", + "print('Time: ', end-start)\n", + "\n", + "\n", + "# ### Training Recurrent Neural Networks in the Standard Way (i.e. learning the relationship between the X and Y data)\n", + "# \n", + "# Finally, comparing the performace of a recurrent neural network using the standard data formatting to the performance of the network with time sequence data formatting shows the benefit of this type of data formatting with extrapolation.\n", + "\n", + "# Check to make sure the data set is complete\n", + "assert len(X_tot) == len(y_tot)\n", + "\n", + "# This is the number of points that will be used in as the training data\n", + "dim=12\n", + "\n", + "# Separate the training data from the whole data set\n", + "X_train = X_tot[:dim]\n", + "y_train = y_tot[:dim]\n", + "\n", + "# Reshape the data for Keras specifications\n", + "X_train = X_train.reshape((dim, 1))\n", + "y_train = y_train.reshape((dim, 1))\n", + "\n", + "\n", + "# Create a recurrent neural network in Keras and produce a summary of the \n", + "# machine learning model\n", + "# Set the sequence length to 1 for regular data formatting \n", + "model = rnn(length_of_sequences = 1)\n", + "model.summary()\n", + "\n", + "# Start the timer. Want to time training+testing\n", + "start = timer()\n", + "# Fit the model using the training data genenerated above using 150 training iterations and a 5%\n", + "# validation split. Setting verbose to True prints information about each training iteration.\n", + "hist = model.fit(X_train, y_train, batch_size=None, epochs=150, \n", + " verbose=True,validation_split=0.05)\n", + "\n", + "\n", + "# This section plots the training loss and the validation loss as a function of training iteration.\n", + "# This is not required for analyzing the couple cluster data but can help determine if the network is\n", + "# being overtrained.\n", + "for label in [\"loss\",\"val_loss\"]:\n", + " plt.plot(hist.history[label],label=label)\n", + "\n", + "plt.ylabel(\"loss\")\n", + "plt.xlabel(\"epoch\")\n", + "plt.title(\"The final validation loss: {}\".format(hist.history[\"val_loss\"][-1]))\n", + "plt.legend()\n", + "plt.show()\n", + "\n", + "# Use the trained neural network to predict the remaining data points\n", + "X_pred = X_tot[dim:]\n", + "X_pred = X_pred.reshape((len(X_pred), 1))\n", + "y_model = model.predict(X_pred)\n", + "y_pred = np.concatenate((y_tot[:dim], y_model.flatten()))\n", + "\n", + "# Plot the known data set and the predicted data set. The red box represents the region that was used\n", + "# for the training data.\n", + "fig, ax = plt.subplots()\n", + "ax.plot(X_tot, y_tot, label=\"true\", linewidth=3)\n", + "ax.plot(X_tot, y_pred, 'g-.',label=\"predicted\", linewidth=4)\n", + "ax.legend()\n", + "# Created a red region to represent the points used in the training data.\n", + "ax.axvspan(X_tot[0], X_tot[dim], alpha=0.25, color='red')\n", + "plt.show()\n", + "\n", + "# Stop the timer and calculate the total time needed.\n", + "end = timer()\n", + "print('Time: ', end-start)" + ] + }, + { + "cell_type": "markdown", + "id": "0752ba7f", + "metadata": { + "editable": true + }, + "source": [ + "# Generative Models\n", + "\n", + "**Generative models** describe a class of statistical models that are a contrast\n", + "to **discriminative models**. Informally we say that generative models can\n", + "generate new data instances while discriminative models discriminate between\n", + "different kinds of data instances. A generative model could generate new photos\n", + "of animals that look like 'real' animals while a discriminative model could tell\n", + "a dog from a cat. More formally, given a data set $x$ and a set of labels /\n", + "targets $y$. Generative models capture the joint probability $p(x, y)$, or\n", + "just $p(x)$ if there are no labels, while discriminative models capture the\n", + "conditional probability $p(y | x)$. Discriminative models generally try to draw\n", + "boundaries in the data space (often high dimensional), while generative models\n", + "try to model how data is placed throughout the space.\n", + "\n", + "**Note**: this material is thanks to Linus Ekstrøm." + ] + }, + { + "cell_type": "markdown", + "id": "784138f8", + "metadata": { + "editable": true + }, + "source": [ + "## Generative Adversarial Networks\n", + "\n", + "**Generative Adversarial Networks** are a type of unsupervised machine learning\n", + "algorithm proposed by [Goodfellow et. al](https://arxiv.org/pdf/1406.2661.pdf)\n", + "in 2014 (short and good article).\n", + "\n", + "The simplest formulation of\n", + "the model is based on a game theoretic approach, *zero sum game*, where we pit\n", + "two neural networks against one another. We define two rival networks, one\n", + "generator $g$, and one discriminator $d$. The generator directly produces\n", + "samples" + ] + }, + { + "cell_type": "markdown", + "id": "a42f89ee", + "metadata": { + "editable": true + }, + "source": [ + "\n", + "
\n", + "\n", + "$$\n", + "\\begin{equation}\n", + " x = g(z; \\theta^{(g)})\n", + "\\label{_auto1} \\tag{1}\n", + "\\end{equation}\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "abe7212f", + "metadata": { + "editable": true + }, + "source": [ + "The discriminator attempts to distinguish between samples drawn from the\n", + "training data and samples drawn from the generator. In other words, it tries to\n", + "tell the difference between the fake data produced by $g$ and the actual data\n", + "samples we want to do prediction on. The discriminator outputs a probability\n", + "value given by" + ] + }, + { + "cell_type": "markdown", + "id": "0821eaee", + "metadata": { + "editable": true + }, + "source": [ + "\n", + "
\n", + "\n", + "$$\n", + "\\begin{equation}\n", + " d(x; \\theta^{(d)})\n", + "\\label{_auto2} \\tag{2}\n", + "\\end{equation}\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "55e0ccf6", + "metadata": { + "editable": true + }, + "source": [ + "indicating the probability that $x$ is a real training example rather than a\n", + "fake sample the generator has generated. The simplest way to formulate the\n", + "learning process in a generative adversarial network is a zero-sum game, in\n", + "which a function" + ] + }, + { + "cell_type": "markdown", + "id": "f37ece14", + "metadata": { + "editable": true + }, + "source": [ + "\n", + "
\n", + "\n", + "$$\n", + "\\begin{equation}\n", + " v(\\theta^{(g)}, \\theta^{(d)})\n", + "\\label{_auto3} \\tag{3}\n", + "\\end{equation}\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "d6d6d5fa", + "metadata": { + "editable": true + }, + "source": [ + "determines the reward for the discriminator, while the generator gets the\n", + "conjugate reward" + ] + }, + { + "cell_type": "markdown", + "id": "3c74b45c", + "metadata": { + "editable": true + }, + "source": [ + "\n", + "
\n", + "\n", + "$$\n", + "\\begin{equation}\n", + " -v(\\theta^{(g)}, \\theta^{(d)})\n", + "\\label{_auto4} \\tag{4}\n", + "\\end{equation}\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "605ac8c9", + "metadata": { + "editable": true + }, + "source": [ + "During learning both of the networks maximize their own reward function, so that\n", + "the generator gets better and better at tricking the discriminator, while the\n", + "discriminator gets better and better at telling the difference between the fake\n", + "and real data. The generator and discriminator alternate on which one trains at\n", + "one time (i.e. for one epoch). In other words, we keep the generator constant\n", + "and train the discriminator, then we keep the discriminator constant to train\n", + "the generator and repeat. It is this back and forth dynamic which lets GANs\n", + "tackle otherwise intractable generative problems. As the generator improves with\n", + " training, the discriminator's performance gets worse because it cannot easily\n", + " tell the difference between real and fake. If the generator ends up succeeding\n", + " perfectly, the the discriminator will do no better than random guessing i.e.\n", + " 50\\%. This progression in the training poses a problem for the convergence\n", + " criteria for GANs. The discriminator feedback gets less meaningful over time,\n", + " if we continue training after this point then the generator is effectively\n", + " training on junk data which can undo the learning up to that point. Therefore,\n", + " we stop training when the discriminator starts outputting $1/2$ everywhere.\n", + "\n", + "At convergence we have" + ] + }, + { + "cell_type": "markdown", + "id": "cfec7462", + "metadata": { + "editable": true + }, + "source": [ + "\n", + "
\n", + "\n", + "$$\n", + "\\begin{equation}\n", + " g^* = \\underset{g}{\\mathrm{argmin}}\\hspace{2pt}\n", + " \\underset{d}{\\mathrm{max}}v(\\theta^{(g)}, \\theta^{(d)})\n", + "\\label{_auto5} \\tag{5}\n", + "\\end{equation}\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "37c65d4c", + "metadata": { + "editable": true + }, + "source": [ + "The default choice for $v$ is" + ] + }, + { + "cell_type": "markdown", + "id": "c868a092", + "metadata": { + "editable": true + }, + "source": [ + "\n", + "
\n", + "\n", + "$$\n", + "\\begin{equation}\n", + " v(\\theta^{(g)}, \\theta^{(d)}) = \\mathbb{E}_{x\\sim p_\\mathrm{data}}\\log d(x)\n", + " + \\mathbb{E}_{x\\sim p_\\mathrm{model}}\n", + " \\log (1 - d(x))\n", + "\\label{_auto6} \\tag{6}\n", + "\\end{equation}\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "ad465af3", + "metadata": { + "editable": true + }, + "source": [ + "The main motivation for the design of GANs is that the learning process requires\n", + "neither approximate inference (variational autoencoders for example) nor\n", + "approximation of a partition function. In the case where" + ] + }, + { + "cell_type": "markdown", + "id": "27858a4e", + "metadata": { + "editable": true + }, + "source": [ + "\n", + "
\n", + "\n", + "$$\n", + "\\begin{equation}\n", + " \\underset{d}{\\mathrm{max}}v(\\theta^{(g)}, \\theta^{(d)})\n", + "\\label{_auto7} \\tag{7}\n", + "\\end{equation}\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "86006023", + "metadata": { + "editable": true + }, + "source": [ + "is convex in $\\theta^{(g)} then the procedure is guaranteed to converge and is\n", + "asymptotically consistent\n", + "( [Seth Lloyd on QuGANs](https://arxiv.org/pdf/1804.09139.pdf) ).\n", + "\n", + "This is in\n", + "general not the case and it is possible to get situations where the training\n", + "process never converges because the generator and discriminator chase one\n", + "another around in the parameter space indefinitely. A much deeper discussion on\n", + "the currently open research problem of GAN convergence is available\n", + "[here](https://www.deeplearningbook.org/contents/generative_models.html). To\n", + "anyone interested in learning more about GANs it is a highly recommended read.\n", + "Direct quote: \"In this best-performing formulation, the generator aims to\n", + "increase the log probability that the discriminator makes a mistake, rather than\n", + "aiming to decrease the log probability that the discriminator makes the correct\n", + "prediction.\" [Another interesting read](https://arxiv.org/abs/1701.00160)" + ] + }, + { + "cell_type": "markdown", + "id": "2fee38bd", + "metadata": { + "editable": true + }, + "source": [ + "## Writing Our First Generative Adversarial Network\n", + "Let us now move on to actually implementing a GAN in tensorflow. We will study\n", + "the performance of our GAN on the MNIST dataset. This code is based on and\n", + "adapted from the\n", + "[google tutorial](https://www.tensorflow.org/tutorials/generative/dcgan)\n", + "\n", + "First we import our libraries" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "004a0b53", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "import os\n", + "import time\n", + "import numpy as np\n", + "import tensorflow as tf\n", + "import matplotlib.pyplot as plt\n", + "from tensorflow.keras import layers\n", + "from tensorflow.keras.utils import plot_model" + ] + }, + { + "cell_type": "markdown", + "id": "353af161", + "metadata": { + "editable": true + }, + "source": [ + "Next we define our hyperparameters and import our data the usual way" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "id": "8cbaf16a", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "BUFFER_SIZE = 60000\n", + "BATCH_SIZE = 256\n", + "EPOCHS = 30\n", + "\n", + "data = tf.keras.datasets.mnist.load_data()\n", + "(train_images, train_labels), (test_images, test_labels) = data\n", + "train_images = np.reshape(train_images, (train_images.shape[0],\n", + " 28,\n", + " 28,\n", + " 1)).astype('float32')\n", + "\n", + "# we normalize between -1 and 1\n", + "train_images = (train_images - 127.5) / 127.5\n", + "training_dataset = tf.data.Dataset.from_tensor_slices(\n", + " train_images).shuffle(BUFFER_SIZE).batch(BATCH_SIZE)" + ] + }, + { + "cell_type": "markdown", + "id": "822b8cc7", + "metadata": { + "editable": true + }, + "source": [ + "### MNIST and GANs\n", + "\n", + "Let's have a quick look" + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "id": "52b5965c", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "plt.imshow(train_images[0], cmap='Greys')\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "21c5199c", + "metadata": { + "editable": true + }, + "source": [ + "Now we define our two models. This is where the 'magic' happens. There are a\n", + "huge amount of possible formulations for both models. A lot of engineering and\n", + "trial and error can be done here to try to produce better performing models. For\n", + "more advanced GANs this is by far the step where you can 'make or break' a\n", + "model.\n", + "\n", + "We start with the generator. As stated in the introductory text the generator\n", + "$g$ upsamples from a random sample to the shape of what we want to predict. In\n", + "our case we are trying to predict MNIST images ($28\\times 28$ pixels)." + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "id": "356759c7", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "def generator_model():\n", + " \"\"\"\n", + " The generator uses upsampling layers tf.keras.layers.Conv2DTranspose() to\n", + " produce an image from a random seed. We start with a Dense layer taking this\n", + " random sample as an input and subsequently upsample through multiple\n", + " convolutional layers.\n", + " \"\"\"\n", + "\n", + " # we define our model\n", + " model = tf.keras.Sequential()\n", + "\n", + "\n", + " # adding our input layer. Dense means that every neuron is connected and\n", + " # the input shape is the shape of our random noise. The units need to match\n", + " # in some sense the upsampling strides to reach our desired output shape.\n", + " # we are using 100 random numbers as our seed\n", + " model.add(layers.Dense(units=7*7*BATCH_SIZE,\n", + " use_bias=False,\n", + " input_shape=(100, )))\n", + " # we normalize the output form the Dense layer\n", + " model.add(layers.BatchNormalization())\n", + " # and add an activation function to our 'layer'. LeakyReLU avoids vanishing\n", + " # gradient problem\n", + " model.add(layers.LeakyReLU())\n", + " model.add(layers.Reshape((7, 7, BATCH_SIZE)))\n", + " assert model.output_shape == (None, 7, 7, BATCH_SIZE)\n", + " # even though we just added four keras layers we think of everything above\n", + " # as 'one' layer\n", + "\n", + " # next we add our upscaling convolutional layers\n", + " model.add(layers.Conv2DTranspose(filters=128,\n", + " kernel_size=(5, 5),\n", + " strides=(1, 1),\n", + " padding='same',\n", + " use_bias=False))\n", + " model.add(layers.BatchNormalization())\n", + " model.add(layers.LeakyReLU())\n", + " assert model.output_shape == (None, 7, 7, 128)\n", + "\n", + " model.add(layers.Conv2DTranspose(filters=64,\n", + " kernel_size=(5, 5),\n", + " strides=(2, 2),\n", + " padding='same',\n", + " use_bias=False))\n", + " model.add(layers.BatchNormalization())\n", + " model.add(layers.LeakyReLU())\n", + " assert model.output_shape == (None, 14, 14, 64)\n", + "\n", + " model.add(layers.Conv2DTranspose(filters=1,\n", + " kernel_size=(5, 5),\n", + " strides=(2, 2),\n", + " padding='same',\n", + " use_bias=False,\n", + " activation='tanh'))\n", + " assert model.output_shape == (None, 28, 28, 1)\n", + "\n", + " return model" + ] + }, + { + "cell_type": "markdown", + "id": "854bcd6b", + "metadata": { + "editable": true + }, + "source": [ + "And there we have our 'simple' generator model. Now we move on to defining our\n", + "discriminator model $d$, which is a convolutional neural network based image\n", + "classifier." + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "id": "41473304", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "def discriminator_model():\n", + " \"\"\"\n", + " The discriminator is a convolutional neural network based image classifier\n", + " \"\"\"\n", + "\n", + " # we define our model\n", + " model = tf.keras.Sequential()\n", + " model.add(layers.Conv2D(filters=64,\n", + " kernel_size=(5, 5),\n", + " strides=(2, 2),\n", + " padding='same',\n", + " input_shape=[28, 28, 1]))\n", + " model.add(layers.LeakyReLU())\n", + " # adding a dropout layer as you do in conv-nets\n", + " model.add(layers.Dropout(0.3))\n", + "\n", + "\n", + " model.add(layers.Conv2D(filters=128,\n", + " kernel_size=(5, 5),\n", + " strides=(2, 2),\n", + " padding='same'))\n", + " model.add(layers.LeakyReLU())\n", + " # adding a dropout layer as you do in conv-nets\n", + " model.add(layers.Dropout(0.3))\n", + "\n", + " model.add(layers.Flatten())\n", + " model.add(layers.Dense(1))\n", + "\n", + " return model" + ] + }, + { + "cell_type": "markdown", + "id": "353af567", + "metadata": { + "editable": true + }, + "source": [ + "Let us take a look at our models." + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "id": "f899d4e3", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "generator = generator_model()\n", + "plot_model(generator, show_shapes=True, rankdir='LR')" + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "id": "87ef384b", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "discriminator = discriminator_model()\n", + "plot_model(discriminator, show_shapes=True, rankdir='LR')" + ] + }, + { + "cell_type": "markdown", + "id": "b2bef82d", + "metadata": { + "editable": true + }, + "source": [ + "Next we need a few helper objects we will use in training" + ] + }, + { + "cell_type": "code", + "execution_count": 14, + "id": "e397847a", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "cross_entropy = tf.keras.losses.BinaryCrossentropy(from_logits=True)\n", + "generator_optimizer = tf.keras.optimizers.Adam(1e-4)\n", + "discriminator_optimizer = tf.keras.optimizers.Adam(1e-4)" + ] + }, + { + "cell_type": "markdown", + "id": "db3396cc", + "metadata": { + "editable": true + }, + "source": [ + "The first object, *cross_entropy* is our loss function and the two others are\n", + "our optimizers. Notice we use the same learning rate for both $g$ and $d$. This\n", + "is because they need to improve their accuracy at approximately equal speeds to\n", + "get convergence (not necessarily exactly equal). Now we define our loss\n", + "functions" + ] + }, + { + "cell_type": "code", + "execution_count": 15, + "id": "931eaced", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "def generator_loss(fake_output):\n", + " loss = cross_entropy(tf.ones_like(fake_output), fake_output)\n", + "\n", + " return loss" + ] + }, + { + "cell_type": "code", + "execution_count": 16, + "id": "0c4a44bb", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "def discriminator_loss(real_output, fake_output):\n", + " real_loss = cross_entropy(tf.ones_like(real_output), real_output)\n", + " fake_loss = cross_entropy(tf.zeros_liks(fake_output), fake_output)\n", + " total_loss = real_loss + fake_loss\n", + "\n", + " return total_loss" + ] + }, + { + "cell_type": "markdown", + "id": "fcf8f066", + "metadata": { + "editable": true + }, + "source": [ + "Next we define a kind of seed to help us compare the learning process over\n", + "multiple training epochs." + ] + }, + { + "cell_type": "code", + "execution_count": 17, + "id": "eea2bbee", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "noise_dimension = 100\n", + "n_examples_to_generate = 16\n", + "seed_images = tf.random.normal([n_examples_to_generate, noise_dimension])" + ] + }, + { + "cell_type": "markdown", + "id": "94a6e341", + "metadata": { + "editable": true + }, + "source": [ + "Now we have everything we need to define our training step, which we will apply\n", + "for every step in our training loop. Notice the @tf.function flag signifying\n", + "that the function is tensorflow 'compiled'. Removing this flag doubles the\n", + "computation time." + ] + }, + { + "cell_type": "code", + "execution_count": 18, + "id": "8d48470b", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "@tf.function\n", + "def train_step(images):\n", + " noise = tf.random.normal([BATCH_SIZE, noise_dimension])\n", + "\n", + " with tf.GradientTape() as gen_tape, tf.GradientTape() as disc_tape:\n", + " generated_images = generator(noise, training=True)\n", + "\n", + " real_output = discriminator(images, training=True)\n", + " fake_output = discriminator(generated_images, training=True)\n", + "\n", + " gen_loss = generator_loss(fake_output)\n", + " disc_loss = discriminator_loss(real_output, fake_output)\n", + "\n", + " gradients_of_generator = gen_tape.gradient(gen_loss,\n", + " generator.trainable_variables)\n", + " gradients_of_discriminator = disc_tape.gradient(disc_loss,\n", + " discriminator.trainable_variables)\n", + " generator_optimizer.apply_gradients(zip(gradients_of_generator,\n", + " generator.trainable_variables))\n", + " discriminator_optimizer.apply_gradients(zip(gradients_of_discriminator,\n", + " discriminator.trainable_variables))\n", + "\n", + " return gen_loss, disc_loss" + ] + }, + { + "cell_type": "markdown", + "id": "62015b88", + "metadata": { + "editable": true + }, + "source": [ + "Next we define a helper function to produce an output over our training epochs\n", + "to see the predictive progression of our generator model. **Note**: I am including\n", + "this code here, but comment it out in the training loop." + ] + }, + { + "cell_type": "code", + "execution_count": 19, + "id": "b189ed96", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "def generate_and_save_images(model, epoch, test_input):\n", + " # we're making inferences here\n", + " predictions = model(test_input, training=False)\n", + "\n", + " fig = plt.figure(figsize=(4, 4))\n", + "\n", + " for i in range(predictions.shape[0]):\n", + " plt.subplot(4, 4, i+1)\n", + " plt.imshow(predictions[i, :, :, 0] * 127.5 + 127.5, cmap='gray')\n", + " plt.axis('off')\n", + "\n", + " plt.savefig(f'./images_from_seed_images/image_at_epoch_{str(epoch).zfill(3)}.png')\n", + " plt.close()\n", + " #plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "ba2c82d5", + "metadata": { + "editable": true + }, + "source": [ + "Setting up checkpoints to periodically save our model during training so that\n", + "everything is not lost even if the program were to somehow terminate while\n", + "training." + ] + }, + { + "cell_type": "code", + "execution_count": 20, + "id": "a0e2fc8a", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "# Setting up checkpoints to save model during training\n", + "checkpoint_dir = './training_checkpoints'\n", + "checkpoint_prefix = os.path.join(checkpoint_dir, 'ckpt')\n", + "checkpoint = tf.train.Checkpoint(generator_optimizer=generator_optimizer,\n", + " discriminator_optimizer=discriminator_optimizer,\n", + " generator=generator,\n", + " discriminator=discriminator)" + ] + }, + { + "cell_type": "markdown", + "id": "4d93a0f7", + "metadata": { + "editable": true + }, + "source": [ + "Now we define our training loop" + ] + }, + { + "cell_type": "code", + "execution_count": 21, + "id": "a1275556", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "def train(dataset, epochs):\n", + " generator_loss_list = []\n", + " discriminator_loss_list = []\n", + "\n", + " for epoch in range(epochs):\n", + " start = time.time()\n", + "\n", + " for image_batch in dataset:\n", + " gen_loss, disc_loss = train_step(image_batch)\n", + " generator_loss_list.append(gen_loss.numpy())\n", + " discriminator_loss_list.append(disc_loss.numpy())\n", + "\n", + " #generate_and_save_images(generator, epoch + 1, seed_images)\n", + "\n", + " if (epoch + 1) % 15 == 0:\n", + " checkpoint.save(file_prefix=checkpoint_prefix)\n", + "\n", + " print(f'Time for epoch {epoch} is {time.time() - start}')\n", + "\n", + " #generate_and_save_images(generator, epochs, seed_images)\n", + "\n", + " loss_file = './data/lossfile.txt'\n", + " with open(loss_file, 'w') as outfile:\n", + " outfile.write(str(generator_loss_list))\n", + " outfile.write('\\n')\n", + " outfile.write('\\n')\n", + " outfile.write(str(discriminator_loss_list))\n", + " outfile.write('\\n')\n", + " outfile.write('\\n')" + ] + }, + { + "cell_type": "markdown", + "id": "6ff3a75a", + "metadata": { + "editable": true + }, + "source": [ + "To train simply call this function. **Warning**: this might take a long time so\n", + "there is a folder of a pretrained network already included in the repository." + ] + }, + { + "cell_type": "code", + "execution_count": 22, + "id": "371ed41a", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "train(train_dataset, EPOCHS)" + ] + }, + { + "cell_type": "markdown", + "id": "654399f1", + "metadata": { + "editable": true + }, + "source": [ + "Now to avoid having to train and everything, which will take a while depending\n", + "on your computer setup we now load in the model which produced the above gif." + ] + }, + { + "cell_type": "code", + "execution_count": 23, + "id": "dec4b560", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "checkpoint.restore(tf.train.latest_checkpoint(checkpoint_dir))\n", + "restored_generator = checkpoint.generator\n", + "restored_discriminator = checkpoint.discriminator\n", + "\n", + "print(restored_generator)\n", + "print(restored_discriminator)" + ] + }, + { + "cell_type": "markdown", + "id": "296bfa5c", + "metadata": { + "editable": true + }, + "source": [ + "We have successfully loaded in our latest model. Let us now play around a bit\n", + "and see what kind of things we can learn about this model. Our generator takes\n", + "an array of 100 numbers. One idea can be to try to systematically change our\n", + "input. Let us try and see what we get" + ] + }, + { + "cell_type": "code", + "execution_count": 24, + "id": "eecfbb1f", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "def generate_latent_points(number=100, scale_means=1, scale_stds=1):\n", + " latent_dim = 100\n", + " means = scale_means * tf.linspace(-1, 1, num=latent_dim)\n", + " stds = scale_stds * tf.linspace(-1, 1, num=latent_dim)\n", + " latent_space_value_range = tf.random.normal([number, latent_dim],\n", + " means,\n", + " stds,\n", + " dtype=tf.float64)\n", + "\n", + " return latent_space_value_range\n", + "\n", + "def generate_images(latent_points):\n", + " # notice we set training to false because we are making inferences\n", + " generated_images = restored_generator.predict(latent_points)\n", + "\n", + " return generated_images" + ] + }, + { + "cell_type": "code", + "execution_count": 25, + "id": "333a593d", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "def plot_result(generated_images, number=100):\n", + " # obviously this assumes sqrt number is an int\n", + " fig, axs = plt.subplots(int(np.sqrt(number)), int(np.sqrt(number)),\n", + " figsize=(10, 10))\n", + "\n", + " for i in range(int(np.sqrt(number))):\n", + " for j in range(int(np.sqrt(number))):\n", + " axs[i, j].imshow(generated_images[i*j], cmap='Greys')\n", + " axs[i, j].axis('off')\n", + "\n", + " plt.show()" + ] + }, + { + "cell_type": "code", + "execution_count": 26, + "id": "2f5f0154", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "generated_images = generate_images(generate_latent_points())\n", + "plot_result(generated_images)" + ] + }, + { + "cell_type": "markdown", + "id": "ff581bf2", + "metadata": { + "editable": true + }, + "source": [ + "We see that the generator generates images that look like MNIST\n", + "numbers: $1, 4, 7, 9$. Let's try to tweak it a bit more to see if we are able\n", + "to generate a similar plot where we generate every MNIST number. Let us now try\n", + "to 'move' a bit around in the latent space. **Note**: decrease the plot number if\n", + "these following cells take too long to run on your computer." + ] + }, + { + "cell_type": "code", + "execution_count": 27, + "id": "d3617ad8", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "plot_number = 225\n", + "\n", + "generated_images = generate_images(generate_latent_points(number=plot_number,\n", + " scale_means=5,\n", + " scale_stds=1))\n", + "plot_result(generated_images, number=plot_number)\n", + "\n", + "generated_images = generate_images(generate_latent_points(number=plot_number,\n", + " scale_means=-5,\n", + " scale_stds=1))\n", + "plot_result(generated_images, number=plot_number)\n", + "\n", + "generated_images = generate_images(generate_latent_points(number=plot_number,\n", + " scale_means=1,\n", + " scale_stds=5))\n", + "plot_result(generated_images, number=plot_number)" + ] + }, + { + "cell_type": "markdown", + "id": "1a074f93", + "metadata": { + "editable": true + }, + "source": [ + "Again, we have found something interesting. *Moving* around using our means\n", + "takes us from digit to digit, while *moving* around using our standard\n", + "deviations seem to increase the number of different digits! In the last image\n", + "above, we can barely make out every MNIST digit. Let us make on last plot using\n", + "this information by upping the standard deviation of our Gaussian noises." + ] + }, + { + "cell_type": "code", + "execution_count": 28, + "id": "4ef8937d", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "plot_number = 400\n", + "generated_images = generate_images(generate_latent_points(number=plot_number,\n", + " scale_means=1,\n", + " scale_stds=10))\n", + "plot_result(generated_images, number=plot_number)" + ] + }, + { + "cell_type": "markdown", + "id": "385a2d0a", + "metadata": { + "editable": true + }, + "source": [ + "A pretty cool result! We see that our generator indeed has learned a\n", + "distribution which qualitatively looks a whole lot like the MNIST dataset.\n", + "\n", + "Another interesting way to explore the latent space of our generator model is by\n", + "interpolating between the MNIST digits. This section is largely based on\n", + "[this excellent blogpost](https://machinelearningmastery.com/how-to-interpolate-and-perform-vector-arithmetic-with-faces-using-a-generative-adversarial-network/)\n", + "by Jason Brownlee.\n", + "\n", + "So let us start by defining a function to interpolate between two points in the\n", + "latent space." + ] + }, + { + "cell_type": "code", + "execution_count": 29, + "id": "57de87b8", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "def interpolation(point_1, point_2, n_steps=10):\n", + " ratios = np.linspace(0, 1, num=n_steps)\n", + " vectors = []\n", + " for i, ratio in enumerate(ratios):\n", + " vectors.append(((1.0 - ratio) * point_1 + ratio * point_2))\n", + "\n", + " return tf.stack(vectors)" + ] + }, + { + "cell_type": "markdown", + "id": "cfb76bb6", + "metadata": { + "editable": true + }, + "source": [ + "Now we have all we need to do our interpolation analysis." + ] + }, + { + "cell_type": "code", + "execution_count": 30, + "id": "e25decef", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "plot_number = 100\n", + "latent_points = generate_latent_points(number=plot_number)\n", + "results = None\n", + "for i in range(0, 2*np.sqrt(plot_number), 2):\n", + " interpolated = interpolation(latent_points[i], latent_points[i+1])\n", + " generated_images = generate_images(interpolated)\n", + "\n", + " if results is None:\n", + " results = generated_images\n", + " else:\n", + " results = tf.stack((results, generated_images))\n", + "\n", + "plot_results(results, plot_number)" + ] + } + ], + "metadata": {}, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/doc/LectureNotes/chapteroptimization.ipynb b/doc/LectureNotes/chapteroptimization.ipynb index e8dc9fc17..5d83c5b50 100644 --- a/doc/LectureNotes/chapteroptimization.ipynb +++ b/doc/LectureNotes/chapteroptimization.ipynb @@ -2,7 +2,21 @@ "cells": [ { "cell_type": "markdown", - "metadata": {}, + "id": "4d72e1df", + "metadata": { + "editable": true + }, + "source": [ + "" + ] + }, + { + "cell_type": "markdown", + "id": "fb6e8fcd", + "metadata": { + "editable": true + }, "source": [ "# Optimization, the central part of any Machine Learning algortithm\n", "\n", @@ -15,9 +29,6 @@ "analytically, however this is not possible in general and we must use\n", "some approximative/numerical method to compute the minimum.\n", "\n", - "\n", - "\n", - "\n", "In our discussion on Logistic Regression we studied the \n", "case of\n", "two classes, with $y_i$ either\n", @@ -28,7 +39,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "a507b82a", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\begin{align*}\n", @@ -40,12 +54,13 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "4071429e", + "metadata": { + "editable": true + }, "source": [ "where $\\boldsymbol{\\beta}$ are the weights we wish to extract from data, in our case $\\beta_0$ and $\\beta_1$. \n", "\n", - "\n", - "\n", "Our compact equations used a definition of a vector $\\boldsymbol{y}$ with $n$\n", "elements $y_i$, an $n\\times p$ matrix $\\boldsymbol{X}$ which contains the\n", "$x_i$ values and a vector $\\boldsymbol{p}$ of fitted probabilities\n", @@ -55,7 +70,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "a3cca0b2", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\frac{\\partial \\mathcal{C}(\\boldsymbol{\\beta})}{\\partial \\boldsymbol{\\beta}} = -\\boldsymbol{X}^T\\left(\\boldsymbol{y}-\\boldsymbol{p}\\right).\n", @@ -64,7 +82,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "12a4ad28", + "metadata": { + "editable": true + }, "source": [ "If we in addition define a diagonal matrix $\\boldsymbol{W}$ with elements \n", "$p(y_i\\vert x_i,\\boldsymbol{\\beta})(1-p(y_i\\vert x_i,\\boldsymbol{\\beta})$, we can obtain a compact expression of the second derivative as" @@ -72,7 +93,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "5d6e7796", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\frac{\\partial^2 \\mathcal{C}(\\boldsymbol{\\beta})}{\\partial \\boldsymbol{\\beta}\\partial \\boldsymbol{\\beta}^T} = \\boldsymbol{X}^T\\boldsymbol{W}\\boldsymbol{X}.\n", @@ -81,12 +105,13 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "b324ae78", + "metadata": { + "editable": true + }, "source": [ "This defines what is called the Hessian matrix.\n", "\n", - "\n", - "\n", "If we can set up these equations, Newton-Raphson's iterative method is normally the method of choice. It requires however that we can compute in an efficient way the matrices that define the first and second derivatives. \n", "\n", "Our iterative scheme is then given by" @@ -94,7 +119,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "7c39cc3f", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\boldsymbol{\\beta}^{\\mathrm{new}} = \\boldsymbol{\\beta}^{\\mathrm{old}}-\\left(\\frac{\\partial^2 \\mathcal{C}(\\boldsymbol{\\beta})}{\\partial \\boldsymbol{\\beta}\\partial \\boldsymbol{\\beta}^T}\\right)^{-1}_{\\boldsymbol{\\beta}^{\\mathrm{old}}}\\times \\left(\\frac{\\partial \\mathcal{C}(\\boldsymbol{\\beta})}{\\partial \\boldsymbol{\\beta}}\\right)_{\\boldsymbol{\\beta}^{\\mathrm{old}}},\n", @@ -103,14 +131,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "10749f5d", + "metadata": { + "editable": true + }, "source": [ "or in matrix form as" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "3ec50136", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\boldsymbol{\\beta}^{\\mathrm{new}} = \\boldsymbol{\\beta}^{\\mathrm{old}}-\\left(\\boldsymbol{X}^T\\boldsymbol{W}\\boldsymbol{X} \\right)^{-1}\\times \\left(-\\boldsymbol{X}^T(\\boldsymbol{y}-\\boldsymbol{p}) \\right)_{\\boldsymbol{\\beta}^{\\mathrm{old}}}.\n", @@ -119,13 +153,15 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "0145d9eb", + "metadata": { + "editable": true + }, "source": [ "The right-hand side is computed with the old values of $\\beta$. \n", "\n", "If we can compute these matrices, in particular the Hessian, the above is often the easiest method to implement. \n", "\n", - "\n", "Let us quickly remind ourselves how we derive the above method.\n", "\n", "Perhaps the most celebrated of all one-dimensional root-finding\n", @@ -136,8 +172,6 @@ "numerically and/or your function is not of the smooth type, we\n", "normally discourage the use of this method.\n", "\n", - "\n", - "\n", "The Newton-Raphson formula consists geometrically of extending the\n", "tangent line at a current point until it crosses zero, then setting\n", "the next guess to the abscissa of that zero-crossing. The mathematics\n", @@ -147,7 +181,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "43c17534", + "metadata": { + "editable": true + }, "source": [ "\n", "
\n", @@ -160,7 +197,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "32ef04f0", + "metadata": { + "editable": true + }, "source": [ "For small enough values of the function and for well-behaved\n", "functions, the terms beyond linear are unimportant, hence we obtain" @@ -168,7 +208,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "6700017c", + "metadata": { + "editable": true + }, "source": [ "$$\n", "f(x)+(s-x)f'(x)\\approx 0,\n", @@ -177,14 +220,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "8791dec4", + "metadata": { + "editable": true + }, "source": [ "yielding" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "69008872", + "metadata": { + "editable": true + }, "source": [ "$$\n", "s\\approx x-\\frac{f(x)}{f'(x)}.\n", @@ -193,14 +242,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "fce4ef1f", + "metadata": { + "editable": true + }, "source": [ "Having in mind an iterative procedure, it is natural to start iterating with" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "e64aef7e", + "metadata": { + "editable": true + }, "source": [ "$$\n", "x_{n+1}=x_n-\\frac{f(x_n)}{f'(x_n)}.\n", @@ -209,7 +264,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "9acecc44", + "metadata": { + "editable": true + }, "source": [ "The above is Newton-Raphson's method. It has a simple geometric\n", "interpretation, namely $x_{n+1}$ is the point where the tangent from\n", @@ -223,16 +281,16 @@ "guess near such a local extremum, so that the first derivative nearly\n", "vanishes, then Newton-Raphson may fail totally\n", "\n", - "\n", - "\n", - "\n", "Newton's method can be generalized to systems of several non-linear equations\n", "and variables. Consider the case with two equations" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "18bc9fd6", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\begin{array}{cc} f_1(x_1,x_2) &=0\\\\\n", @@ -242,14 +300,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "7dcad370", + "metadata": { + "editable": true + }, "source": [ "which we Taylor expand to obtain" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "f1724121", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\begin{array}{cc} 0=f_1(x_1+h_1,x_2+h_2)=&f_1(x_1,x_2)+h_1\n", @@ -264,14 +328,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "d04bfa9f", + "metadata": { + "editable": true + }, "source": [ "Defining the Jacobian matrix $\\boldsymbol{J}$ we have" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "a4d3a9e3", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\boldsymbol{J}=\\left( \\begin{array}{cc}\n", @@ -283,14 +353,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "d9d6ff69", + "metadata": { + "editable": true + }, "source": [ "we can rephrase Newton's method as" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "362a86a3", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\left(\\begin{array}{c} x_1^{n+1} \\\\ x_2^{n+1} \\end{array} \\right)=\n", @@ -301,14 +377,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "4b8c2937", + "metadata": { + "editable": true + }, "source": [ "where we have defined" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "7580aa9a", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\left(\\begin{array}{c} h_1^{n} \\\\ h_2^{n} \\end{array} \\right)=\n", @@ -319,18 +401,26 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "a2e3adc3", + "metadata": { + "editable": true + }, "source": [ "We need thus to compute the inverse of the Jacobian matrix and it\n", "is to understand that difficulties may\n", "arise in case $\\boldsymbol{J}$ is nearly singular.\n", "\n", "It is rather straightforward to extend the above scheme to systems of\n", - "more than two non-linear equations. In our case, the Jacobian matrix is given by the Hessian that represents the second derivative of cost function. \n", - "\n", - "\n", - "\n", - "\n", + "more than two non-linear equations. In our case, the Jacobian matrix is given by the Hessian that represents the second derivative of cost function." + ] + }, + { + "cell_type": "markdown", + "id": "83a585c9", + "metadata": { + "editable": true + }, + "source": [ "## Steepest descent\n", "\n", "The basic idea of gradient descent is\n", @@ -343,7 +433,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "e127ea11", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\mathbf{x}_{k+1} = \\mathbf{x}_k - \\gamma_k \\nabla F(\\mathbf{x}_k),\n", @@ -352,7 +445,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "bce435bc", + "metadata": { + "editable": true + }, "source": [ "with $\\gamma_k > 0$.\n", "\n", @@ -360,7 +456,6 @@ "F(\\mathbf{x}_k)$. This means that for a sufficiently small $\\gamma_k$\n", "we are always moving towards smaller function values, i.e a minimum.\n", "\n", - "\n", "The previous observation is the basis of the method of steepest\n", "descent, which is also referred to as just gradient descent (GD). One\n", "starts with an initial guess $\\mathbf{x}_0$ for a minimum of $F$ and\n", @@ -369,7 +464,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "2691da5f", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\mathbf{x}_{k+1} = \\mathbf{x}_k - \\gamma_k \\nabla F(\\mathbf{x}_k), \\ \\ k \\geq 0.\n", @@ -378,12 +476,14 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "e7ae7322", + "metadata": { + "editable": true + }, "source": [ "The parameter $\\gamma_k$ is often referred to as the step length or\n", "the learning rate within the context of Machine Learning.\n", "\n", - "\n", "Ideally the sequence $\\{\\mathbf{x}_k \\}_{k=0}$ converges to a global\n", "minimum of the function $F$. In general we do not know if we are in a\n", "global or local minimum. In the special case when $F$ is a convex\n", @@ -402,9 +502,6 @@ "Note that the gradient is a function of $\\mathbf{x} =\n", "(x_1,\\cdots,x_n)$ which makes it expensive to compute numerically.\n", "\n", - "\n", - "\n", - "\n", "The gradient descent method \n", "is sensitive to the choice of learning rate $\\gamma_k$. This is due\n", "to the fact that we are only guaranteed that $F(\\mathbf{x}_{k+1}) \\leq\n", @@ -415,10 +512,16 @@ "\n", "Many of these shortcomings can be alleviated by introducing\n", "randomness. One such method is that of Stochastic Gradient Descent\n", - "(SGD), see below.\n", - "\n", - "\n", - "\n", + "(SGD), see below." + ] + }, + { + "cell_type": "markdown", + "id": "a6a44ea7", + "metadata": { + "editable": true + }, + "source": [ "## Convex functions\n", "\n", "Ideally we want our cost/loss function to be convex(concave).\n", @@ -433,11 +536,8 @@ "$\\mathbb{R}$. Examples of convex sets of $\\mathbb{R}^2$ are the\n", "regular polygons (triangles, rectangles, pentagons, etc...).\n", "\n", - "\n", - "\n", "**Convex function**: Let $X \\subset \\mathbb{R}^n$ be a convex set. Assume that the function $f: X \\rightarrow \\mathbb{R}$ is continuous, then $f$ is said to be convex if $$f(tx_1 + (1-t)x_2) \\leq tf(x_1) + (1-t)f(x_2) $$ for all $x_1, x_2 \\in X$ and for all $t \\in [0,1]$. If $\\leq$ is replaced with a strict inequaltiy in the definition, we demand $x_1 \\neq x_2$ and $t\\in(0,1)$ then $f$ is said to be strictly convex. For a single variable function, convexity means that if you draw a straight line connecting $f(x_1)$ and $f(x_2)$, the value of the function on the interval $[x_1,x_2]$ is always below the line as illustrated below.\n", "\n", - "\n", "In the following we state first and second-order conditions which\n", "ensures convexity of a function $f$. We write $D_f$ to denote the\n", "domain of $f$, i.e the subset of $R^n$ where $f$ is defined. For more\n", @@ -454,8 +554,6 @@ "make a drawing of $f(x) = x^2+1$ and draw the tangent line to $f(x)$ and\n", "note that it is always below the graph.\n", "\n", - "\n", - "\n", "**Second order condition.**\n", "\n", "Assume that $f$ is twice\n", @@ -465,12 +563,8 @@ "single-variable function this reduces to $f''(x) \\geq 0$. Geometrically this means that $f$ has nonnegative curvature\n", "everywhere.\n", "\n", - "\n", - "\n", "This condition is particularly useful since it gives us an procedure for determining if the function under consideration is convex, apart from using the definition.\n", "\n", - "\n", - "\n", "The next result is of great importance to us and the reason why we are\n", "going on about convex functions. In machine learning we frequently\n", "have to minimize a loss/cost function in order to find the best\n", @@ -487,11 +581,16 @@ "is minimal, where $f$ is convex and differentiable. Then, any point\n", "$x^*$ that satisfies $\\nabla f(x^*) = 0$ is a global minimum.\n", "\n", - "\n", - "\n", - "This result means that if we know that the cost/loss function is convex and we are able to find a minimum, we are guaranteed that it is a global minimum.\n", - "\n", - "\n", + "This result means that if we know that the cost/loss function is convex and we are able to find a minimum, we are guaranteed that it is a global minimum." + ] + }, + { + "cell_type": "markdown", + "id": "809f8f01", + "metadata": { + "editable": true + }, + "source": [ "### Some simple problems\n", "\n", "1. Show that $f(x)=x^2$ is convex for $x \\in \\mathbb{R}$ using the definition of convexity. Hint: If you re-write the definition, $f$ is convex if the following holds for all $x,y \\in D_f$ and any $\\lambda \\in [0,1]$ $\\lambda f(x)+(1-\\lambda)f(y)-f(\\lambda x + (1-\\lambda) y ) \\geq 0$.\n", @@ -502,7 +601,6 @@ "\n", " * $g(x) = -\\ln(x)$ is convex for $x \\in (0,\\infty)$.\n", "\n", - "\n", "3. Let $f(x) = x^2$ and $g(x) = e^x$. Show that $f(g(x))$ and $g(f(x))$ is convex for $x \\in \\mathbb{R}$. Also show that if $f(x)$ is any convex function than $h(x) = e^{f(x)}$ is convex.\n", "\n", "4. A norm is any function that satisfy the following properties\n", @@ -513,13 +611,18 @@ "\n", " * $f(x) \\leq 0$ for all $x \\in \\mathbb{R}^n$ with equality if and only if $x = 0$\n", "\n", - "\n", - "Using the definition of convexity, try to show that a function satisfying the properties above is convex (the third condition is not needed to show this).\n", - "\n", - "\n", + "Using the definition of convexity, try to show that a function satisfying the properties above is convex (the third condition is not needed to show this)." + ] + }, + { + "cell_type": "markdown", + "id": "f3b91277", + "metadata": { + "editable": true + }, + "source": [ "## Standard steepest descent\n", "\n", - "\n", "Before we proceed, we would like to discuss the approach called the\n", "**standard Steepest descent** (different from the above steepest descent discussion), which again leads to us having to be able\n", "to compute a matrix. It belongs to the class of Conjugate Gradient methods (CG).\n", @@ -533,7 +636,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "ec752109", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\boldsymbol{A}\\boldsymbol{x} = \\boldsymbol{b}.\n", @@ -542,14 +648,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "eb64c8e7", + "metadata": { + "editable": true + }, "source": [ "In the iterative process we end up with a problem like" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "7e99eb7f", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\boldsymbol{r}= \\boldsymbol{b}-\\boldsymbol{A}\\boldsymbol{x},\n", @@ -558,20 +670,24 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "3a3f6414", + "metadata": { + "editable": true + }, "source": [ "where $\\boldsymbol{r}$ is the so-called residual or error in the iterative process.\n", "\n", "When we have found the exact solution, $\\boldsymbol{r}=0$.\n", "\n", - "\n", - "\n", "The residual is zero when we reach the minimum of the quadratic equation" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "a88175a4", + "metadata": { + "editable": true + }, "source": [ "$$\n", "P(\\boldsymbol{x})=\\frac{1}{2}\\boldsymbol{x}^T\\boldsymbol{A}\\boldsymbol{x} - \\boldsymbol{x}^T\\boldsymbol{b},\n", @@ -580,19 +696,24 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "6992cc4f", + "metadata": { + "editable": true + }, "source": [ "with the constraint that the matrix $\\boldsymbol{A}$ is positive definite and\n", "symmetric. This defines also the Hessian and we want it to be positive definite. \n", "\n", - "\n", "We denote the initial guess for $\\boldsymbol{x}$ as $\\boldsymbol{x}_0$. \n", "We can assume without loss of generality that" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "00e22e2b", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\boldsymbol{x}_0=0,\n", @@ -601,14 +722,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "faab896d", + "metadata": { + "editable": true + }, "source": [ "or consider the system" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "02cb8061", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\boldsymbol{A}\\boldsymbol{z} = \\boldsymbol{b}-\\boldsymbol{A}\\boldsymbol{x}_0,\n", @@ -617,17 +744,22 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "fe52c448", + "metadata": { + "editable": true + }, "source": [ "instead.\n", "\n", - "\n", "One can show that the solution $\\boldsymbol{x}$ is also the unique minimizer of the quadratic form" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "f698b7fe", + "metadata": { + "editable": true + }, "source": [ "$$\n", "f(\\boldsymbol{x}) = \\frac{1}{2}\\boldsymbol{x}^T\\boldsymbol{A}\\boldsymbol{x} - \\boldsymbol{x}^T \\boldsymbol{x} , \\quad \\boldsymbol{x}\\in\\mathbf{R}^n.\n", @@ -636,7 +768,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "022bda7f", + "metadata": { + "editable": true + }, "source": [ "This suggests taking the first basis vector $\\boldsymbol{r}_1$ (see below for definition) \n", "to be the gradient of $f$ at $\\boldsymbol{x}=\\boldsymbol{x}_0$, \n", @@ -645,7 +780,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "b64077bc", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\boldsymbol{A}\\boldsymbol{x}_0-\\boldsymbol{b},\n", @@ -654,18 +792,23 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "dec06904", + "metadata": { + "editable": true + }, "source": [ "and \n", "$\\boldsymbol{x}_0=0$ it is equal $-\\boldsymbol{b}$.\n", "\n", - "\n", "We can compute the residual iteratively as" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "b566de75", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\boldsymbol{r}_{k+1}=\\boldsymbol{b}-\\boldsymbol{A}\\boldsymbol{x}_{k+1},\n", @@ -674,14 +817,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "2c2d16e7", + "metadata": { + "editable": true + }, "source": [ "which equals" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "6c97f03d", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\boldsymbol{b}-\\boldsymbol{A}(\\boldsymbol{x}_k+\\alpha_k\\boldsymbol{r}_k),\n", @@ -690,14 +839,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "2b40818b", + "metadata": { + "editable": true + }, "source": [ "or" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "6619d064", + "metadata": { + "editable": true + }, "source": [ "$$\n", "(\\boldsymbol{b}-\\boldsymbol{A}\\boldsymbol{x}_k)-\\alpha_k\\boldsymbol{A}\\boldsymbol{r}_k,\n", @@ -706,14 +861,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "467c71be", + "metadata": { + "editable": true + }, "source": [ "which gives" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "d58fd1af", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\alpha_k = \\frac{\\boldsymbol{r}_k^T\\boldsymbol{r}_k}{\\boldsymbol{r}_k^T\\boldsymbol{A}\\boldsymbol{r}_k}\n", @@ -722,14 +883,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "38e32957", + "metadata": { + "editable": true + }, "source": [ "leading to the iterative scheme" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "98043fd6", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\boldsymbol{x}_{k+1}=\\boldsymbol{x}_k-\\alpha_k\\boldsymbol{r}_{k},\n", @@ -738,7 +905,8 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 1, + "id": "8c7efe84", "metadata": { "collapsed": false, "editable": true @@ -771,14 +939,18 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "3bdeb3c1", + "metadata": { + "editable": true + }, "source": [ "And then as countor plot" ] }, { "cell_type": "code", - "execution_count": null, + "execution_count": 2, + "id": "e6e460db", "metadata": { "collapsed": false, "editable": true @@ -792,14 +964,18 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "d165add7", + "metadata": { + "editable": true + }, "source": [ "Find guesses" ] }, { "cell_type": "code", - "execution_count": null, + "execution_count": 3, + "id": "236615ae", "metadata": { "collapsed": false, "editable": true @@ -812,14 +988,18 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "4b90442c", + "metadata": { + "editable": true + }, "source": [ "Run it!" ] }, { "cell_type": "code", - "execution_count": null, + "execution_count": 4, + "id": "0346fd1d", "metadata": { "collapsed": false, "editable": true @@ -837,14 +1017,18 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "ecff8b5b", + "metadata": { + "editable": true + }, "source": [ "What happened?" ] }, { "cell_type": "code", - "execution_count": null, + "execution_count": 5, + "id": "0d9b7732", "metadata": { "collapsed": false, "editable": true @@ -859,7 +1043,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "b0f8920b", + "metadata": { + "editable": true + }, "source": [ "## Conjugate gradient method\n", "In the CG method we define so-called conjugate directions and two vectors \n", @@ -870,7 +1057,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "67b215c6", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\boldsymbol{s}^T\\boldsymbol{A}\\boldsymbol{t}= 0.\n", @@ -879,7 +1069,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "efc1c192", + "metadata": { + "editable": true + }, "source": [ "The philosophy of the CG method is to perform searches in various conjugate directions\n", "of our vectors $\\boldsymbol{x}_i$ obeying the above criterion, namely" @@ -887,7 +1080,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "eb4e1832", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\boldsymbol{x}_i^T\\boldsymbol{A}\\boldsymbol{x}_j= 0.\n", @@ -896,7 +1092,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "775cf999", + "metadata": { + "editable": true + }, "source": [ "Two vectors are conjugate if they are orthogonal with respect to \n", "this inner product. Being conjugate is a symmetric relation: if $\\boldsymbol{s}$ is conjugate to $\\boldsymbol{t}$, then $\\boldsymbol{t}$ is conjugate to $\\boldsymbol{s}$.\n", @@ -906,7 +1105,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "95893950", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\boldsymbol{v}_i^T\\boldsymbol{A}\\boldsymbol{v}_j= \\lambda\\boldsymbol{v}_i^T\\boldsymbol{v}_j,\n", @@ -915,7 +1117,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "16bfad5c", + "metadata": { + "editable": true + }, "source": [ "which is zero unless $i=j$. \n", "\n", @@ -925,7 +1130,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "e2577f1c", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\boldsymbol{x}_{i+1}=\\boldsymbol{x}_{i}+\\alpha_i\\boldsymbol{p}_{i}.\n", @@ -934,7 +1142,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "e4defaaf", + "metadata": { + "editable": true + }, "source": [ "We assume that $\\boldsymbol{p}_{i}$ is a sequence of $n$ mutually conjugate directions. \n", "Then the $\\boldsymbol{p}_{i}$ form a basis of $R^n$ and we can expand the solution \n", @@ -943,7 +1154,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "b4632612", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\boldsymbol{x} = \\sum^{n}_{i=1} \\alpha_i \\boldsymbol{p}_i.\n", @@ -952,14 +1166,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "a0a06bf2", + "metadata": { + "editable": true + }, "source": [ "The coefficients are given by" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "1db7cc6a", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\mathbf{A}\\mathbf{x} = \\sum^{n}_{i=1} \\alpha_i \\mathbf{A} \\mathbf{p}_i = \\mathbf{b}.\n", @@ -968,14 +1188,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "e7aa5384", + "metadata": { + "editable": true + }, "source": [ "Multiplying with $\\boldsymbol{p}_k^T$ from the left gives" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "884580b0", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\boldsymbol{p}_k^T \\boldsymbol{A}\\boldsymbol{x} = \\sum^{n}_{i=1} \\alpha_i\\boldsymbol{p}_k^T \\boldsymbol{A}\\boldsymbol{p}_i= \\boldsymbol{p}_k^T \\boldsymbol{b},\n", @@ -984,14 +1210,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "934990e4", + "metadata": { + "editable": true + }, "source": [ "and we can define the coefficients $\\alpha_k$ as" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "8be96384", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\alpha_k = \\frac{\\boldsymbol{p}_k^T \\boldsymbol{b}}{\\boldsymbol{p}_k^T \\boldsymbol{A} \\boldsymbol{p}_k}\n", @@ -1000,7 +1232,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "44f4d8d5", + "metadata": { + "editable": true + }, "source": [ "If we choose the conjugate vectors $\\boldsymbol{p}_k$ carefully, \n", "then we may not need all of them to obtain a good approximation to the solution \n", @@ -1015,7 +1250,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "a8739d7d", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\boldsymbol{x}_0=0,\n", @@ -1024,14 +1262,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "d871e171", + "metadata": { + "editable": true + }, "source": [ "or consider the system" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "7ed84e84", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\boldsymbol{A}\\boldsymbol{z} = \\boldsymbol{b}-\\boldsymbol{A}\\boldsymbol{x}_0,\n", @@ -1040,7 +1284,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "b690f75b", + "metadata": { + "editable": true + }, "source": [ "instead.\n", "\n", @@ -1049,7 +1296,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "86ce9e8a", + "metadata": { + "editable": true + }, "source": [ "$$\n", "f(\\boldsymbol{x}) = \\frac{1}{2}\\boldsymbol{x}^T\\boldsymbol{A}\\boldsymbol{x} - \\boldsymbol{x}^T \\boldsymbol{x} , \\quad \\boldsymbol{x}\\in\\mathbf{R}^n.\n", @@ -1058,7 +1308,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "7968787f", + "metadata": { + "editable": true + }, "source": [ "This suggests taking the first basis vector $\\boldsymbol{p}_1$ \n", "to be the gradient of $f$ at $\\boldsymbol{x}=\\boldsymbol{x}_0$, \n", @@ -1067,7 +1320,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "0d510b11", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\boldsymbol{A}\\boldsymbol{x}_0-\\boldsymbol{b},\n", @@ -1076,7 +1332,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "c7c47a8e", + "metadata": { + "editable": true + }, "source": [ "and \n", "$\\boldsymbol{x}_0=0$ it is equal $-\\boldsymbol{b}$.\n", @@ -1088,7 +1347,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "5dc0e4ac", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\boldsymbol{r}_k=\\boldsymbol{b}-\\boldsymbol{A}\\boldsymbol{x}_k.\n", @@ -1097,7 +1359,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "0aecb4b3", + "metadata": { + "editable": true + }, "source": [ "Note that $\\boldsymbol{r}_k$ is the negative gradient of $f$ at \n", "$\\boldsymbol{x}=\\boldsymbol{x}_k$, \n", @@ -1110,7 +1375,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "f3dfc701", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\boldsymbol{p}_{k+1}=\\boldsymbol{r}_k-\\frac{\\boldsymbol{p}_k^T \\boldsymbol{A}\\boldsymbol{r}_k}{\\boldsymbol{p}_k^T\\boldsymbol{A}\\boldsymbol{p}_k} \\boldsymbol{p}_k.\n", @@ -1119,14 +1387,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "12e92892", + "metadata": { + "editable": true + }, "source": [ "We can also compute the residual iteratively as" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "1514b03f", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\boldsymbol{r}_{k+1}=\\boldsymbol{b}-\\boldsymbol{A}\\boldsymbol{x}_{k+1},\n", @@ -1135,14 +1409,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "7b09db3d", + "metadata": { + "editable": true + }, "source": [ "which equals" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "4a0638f8", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\boldsymbol{b}-\\boldsymbol{A}(\\boldsymbol{x}_k+\\alpha_k\\boldsymbol{p}_k),\n", @@ -1151,14 +1431,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "298f5e46", + "metadata": { + "editable": true + }, "source": [ "or" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "acd35abb", + "metadata": { + "editable": true + }, "source": [ "$$\n", "(\\boldsymbol{b}-\\boldsymbol{A}\\boldsymbol{x}_k)-\\alpha_k\\boldsymbol{A}\\boldsymbol{p}_k,\n", @@ -1167,14 +1453,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "79625f01", + "metadata": { + "editable": true + }, "source": [ "which gives" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "dc5888e2", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\boldsymbol{r}_{k+1}=\\boldsymbol{r}_k-\\boldsymbol{A}\\boldsymbol{p}_{k},\n", @@ -1183,7 +1475,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "d11b96a9", + "metadata": { + "editable": true + }, "source": [ "## Revisiting our Linear Regression Solvers\n", "\n", @@ -1203,7 +1498,8 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 6, + "id": "cf7c349e", "metadata": { "collapsed": false, "editable": true @@ -1217,7 +1513,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "adf34219", + "metadata": { + "editable": true + }, "source": [ "with $x_i \\in [0,1] $ is chosen randomly using a uniform distribution. Additionally we have a stochastic noise chosen according to a normal distribution $\\cal {N}(0,1)$. \n", "The linear regression model is given by" @@ -1225,7 +1524,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "d28eb4e0", + "metadata": { + "editable": true + }, "source": [ "$$\n", "h_\\beta(x) = \\boldsymbol{y} = \\beta_0 + \\beta_1 x,\n", @@ -1234,14 +1536,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "60060fcb", + "metadata": { + "editable": true + }, "source": [ "such that" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "82983f16", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\boldsymbol{y}_i = \\beta_0 + \\beta_1 x_i.\n", @@ -1250,7 +1558,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "60fc4bc0", + "metadata": { + "editable": true + }, "source": [ "Let $\\mathbf{y} = (y_1,\\cdots,y_n)^T$, $\\mathbf{\\boldsymbol{y}} = (\\boldsymbol{y}_1,\\cdots,\\boldsymbol{y}_n)^T$ and $\\beta = (\\beta_0, \\beta_1)^T$\n", "\n", @@ -1259,7 +1570,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "0c5dac72", + "metadata": { + "editable": true + }, "source": [ "$$\n", "X \\equiv \\begin{bmatrix}\n", @@ -1272,14 +1586,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "002d8c9b", + "metadata": { + "editable": true + }, "source": [ "The cost/loss/risk function is given by (" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "b91d8b5a", + "metadata": { + "editable": true + }, "source": [ "$$\n", "C(\\beta) = \\frac{1}{n}||X\\beta-\\mathbf{y}||_{2}^{2} = \\frac{1}{n}\\sum_{i=1}^{100}\\left[ (\\beta_0 + \\beta_1 x_i)^2 - 2 y_i (\\beta_0 + \\beta_1 x_i) + y_i^2\\right]\n", @@ -1288,17 +1608,22 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "d0fc6c20", + "metadata": { + "editable": true + }, "source": [ "and we want to find $\\beta$ such that $C(\\beta)$ is minimized.\n", "\n", - "\n", "Computing $\\partial C(\\beta) / \\partial \\beta_0$ and $\\partial C(\\beta) / \\partial \\beta_1$ we can show that the gradient can be written as" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "3f99dab5", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\nabla_{\\beta} C(\\beta) = \\frac{2}{n}\\begin{bmatrix} \\sum_{i=1}^{100} \\left(\\beta_0+\\beta_1x_i-y_i\\right) \\\\\n", @@ -1309,17 +1634,22 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "e1305a22", + "metadata": { + "editable": true + }, "source": [ "where $X$ is the design matrix defined above.\n", "\n", - "\n", "The Hessian matrix of $C(\\beta)$ is given by" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "ef62073f", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\boldsymbol{H} \\equiv \\begin{bmatrix}\n", @@ -1331,18 +1661,22 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "dfb78235", + "metadata": { + "editable": true + }, "source": [ "This result implies that $C(\\beta)$ is a convex function since the matrix $X^T X$ always is positive semi-definite.\n", "\n", - "\n", - "\n", "We can now write a program that minimizes $C(\\beta)$ using the gradient descent method with a constant learning rate $\\gamma$ according to" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "56cee86c", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\beta_{k+1} = \\beta_k - \\gamma \\nabla_\\beta C(\\beta_k), \\ k=0,1,\\cdots\n", @@ -1351,7 +1685,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "6cc71454", + "metadata": { + "editable": true + }, "source": [ "We can use the expression we computed for the gradient and let use a\n", "$\\beta_0$ be chosen randomly and let $\\gamma = 0.001$. Stop iterating\n", @@ -1360,14 +1697,13 @@ "And finally we can compare our solution for $\\beta$ with the analytic result given by \n", "$\\beta= (X^TX)^{-1} X^T \\mathbf{y}$.\n", "\n", - "\n", - "\n", "Here is our simple example" ] }, { "cell_type": "code", - "execution_count": null, + "execution_count": 7, + "id": "90fab6b7", "metadata": { "collapsed": false, "editable": true @@ -1424,14 +1760,18 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "48ba87fe", + "metadata": { + "editable": true + }, "source": [ "Alternatively, we can use **Scikit-Learn** as done here" ] }, { "cell_type": "code", - "execution_count": null, + "execution_count": 8, + "id": "7522775d", "metadata": { "collapsed": false, "editable": true @@ -1458,14 +1798,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "90552e2f", + "metadata": { + "editable": true + }, "source": [ "We have also discussed Ridge regression where the loss function contains a regularized term given by the $L_2$ norm of $\\beta$," ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "5d7c032c", + "metadata": { + "editable": true + }, "source": [ "$$\n", "C_{\\text{ridge}}(\\beta) = \\frac{1}{n}||X\\beta -\\mathbf{y}||^2 + \\lambda ||\\beta||^2, \\ \\lambda \\geq 0.\n", @@ -1474,14 +1820,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "ed86f1ba", + "metadata": { + "editable": true + }, "source": [ "In order to minimize $C_{\\text{ridge}}(\\beta)$ using GD we only have adjust the gradient as follows" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "0386e23c", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\nabla_\\beta C_{\\text{ridge}}(\\beta) = \\frac{2}{n}\\begin{bmatrix} \\sum_{i=1}^{100} \\left(\\beta_0+\\beta_1x_i-y_i\\right) \\\\\n", @@ -1492,14 +1844,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "b65523fc", + "metadata": { + "editable": true + }, "source": [ "We can easily extend our program to minimize $C_{\\text{ridge}}(\\beta)$ using gradient descent and compare with the analytical solution given by" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "c62584ee", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\beta_{\\text{ridge}} = \\left(X^T X + \\lambda I_{2 \\times 2} \\right)^{-1} X^T \\mathbf{y}.\n", @@ -1508,7 +1866,8 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 9, + "id": "e8d43667", "metadata": { "collapsed": false, "editable": true @@ -1562,7 +1921,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "1ca83847", + "metadata": { + "editable": true + }, "source": [ "## Using gradient descent methods, limitations\n", "\n", @@ -1576,9 +1938,39 @@ "\n", "* **GD treats all directions in parameter space uniformly.** Another major drawback of GD is that unlike Newton's method, the learning rate for GD is the same in all directions in parameter space. For this reason, the maximum learning rate is set by the behavior of the steepest direction and this can significantly slow down training. Ideally, we would like to take large steps in flat directions and small steps in steep directions. Since we are exploring rugged landscapes where curvatures change, this requires us to keep track of not only the gradient but second derivatives. The ideal scenario would be to calculate the Hessian but this proves to be too computationally expensive. \n", "\n", - "* GD can take exponential time to escape saddle points, even with random initialization. As we mentioned, GD is extremely sensitive to initial condition since it determines the particular local minimum GD would eventually reach. However, even with a good initialization scheme, through the introduction of randomness, GD can still take exponential time to escape saddle points.\n", + "* GD can take exponential time to escape saddle points, even with random initialization. As we mentioned, GD is extremely sensitive to initial condition since it determines the particular local minimum GD would eventually reach. However, even with a good initialization scheme, through the introduction of randomness, GD can still take exponential time to escape saddle points." + ] + }, + { + "cell_type": "markdown", + "id": "dcf3e808", + "metadata": { + "editable": true + }, + "source": [ + "## Stochastic Gradient Descent (SGD)\n", "\n", - "## Stochastic Gradient Descent\n", + "In stochastic gradient descent, the extreme case is the case where we\n", + "have only one batch, that is we include the whole data set.\n", + "\n", + "This process is called Stochastic Gradient\n", + "Descent (SGD) (or also sometimes on-line gradient descent). This is\n", + "relatively less common to see because in practice due to vectorized\n", + "code optimizations it can be computationally much more efficient to\n", + "evaluate the gradient for 100 examples, than the gradient for one\n", + "example 100 times. Even though SGD technically refers to using a\n", + "single example at a time to evaluate the gradient, you will hear\n", + "people use the term SGD even when referring to mini-batch gradient\n", + "descent (i.e. mentions of MGD for “Minibatch Gradient Descent”, or BGD\n", + "for “Batch gradient descent” are rare to see), where it is usually\n", + "assumed that mini-batches are used. The size of the mini-batch is a\n", + "hyperparameter but it is not very common to cross-validate or bootstrap it. It is\n", + "usually based on memory constraints (if any), or set to some value,\n", + "e.g. 32, 64 or 128. We use powers of 2 in practice because many\n", + "vectorized operation implementations work faster when their inputs are\n", + "sized in powers of 2.\n", + "\n", + "In our notes with SGD we mean stochastic gradient descent with mini-batches.\n", "\n", "Stochastic gradient descent (SGD) and variants thereof address some of\n", "the shortcomings of the Gradient descent method discussed above.\n", @@ -1590,7 +1982,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "473b1af6", + "metadata": { + "editable": true + }, "source": [ "$$\n", "C(\\mathbf{\\beta}) = \\sum_{i=1}^n c_i(\\mathbf{x}_i,\n", @@ -1600,7 +1995,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "3353fe2a", + "metadata": { + "editable": true + }, "source": [ "This in turn means that the gradient can be\n", "computed as a sum over $i$-gradients" @@ -1608,7 +2006,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "6e8e47c3", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\nabla_\\beta C(\\mathbf{\\beta}) = \\sum_i^n \\nabla_\\beta c_i(\\mathbf{x}_i,\n", @@ -1618,7 +2019,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "a2eeb6ad", + "metadata": { + "editable": true + }, "source": [ "Stochasticity/randomness is introduced by only taking the\n", "gradient on a subset of the data called minibatches. If there are $n$\n", @@ -1626,8 +2030,6 @@ "minibatches. We denote these minibatches by $B_k$ where\n", "$k=1,\\cdots,n/M$.\n", "\n", - "\n", - "\n", "As an example, suppose we have $10$ data points $(\\mathbf{x}_1,\\cdots, \\mathbf{x}_{10})$ \n", "and we choose to have $M=5$ minibathces,\n", "then each minibatch contains two data points. In particular we have\n", @@ -1644,7 +2046,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "5a7a0f8b", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\nabla_{\\beta}\n", @@ -1656,14 +2061,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "b7b5884f", + "metadata": { + "editable": true + }, "source": [ "Thus a gradient descent step now looks like" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "6492d660", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\beta_{j+1} = \\beta_j - \\gamma_j \\sum_{i \\in B_k}^n \\nabla_\\beta c_i(\\mathbf{x}_i,\n", @@ -1673,7 +2084,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "584164f4", + "metadata": { + "editable": true + }, "source": [ "where $k$ is picked at random with equal\n", "probability from $[1,n/M]$. An iteration over the number of\n", @@ -1684,7 +2098,8 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 10, + "id": "42d97cf8", "metadata": { "collapsed": false, "editable": true @@ -1694,7 +2109,7 @@ "import numpy as np \n", "\n", "n = 100 #100 datapoints \n", - "M = 5 #size of each minibatch\n", + "M = 5 #size of each mini-batche\n", "m = int(n/M) #number of minibatches\n", "n_epochs = 10 #number of epochs\n", "\n", @@ -1709,7 +2124,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "ca9c6c58", + "metadata": { + "editable": true + }, "source": [ "Taking the gradient only on a subset of the data has two important\n", "benefits. First, it introduces randomness which decreases the chance\n", @@ -1719,8 +2137,6 @@ "cheaper since we sum over the datapoints in the $k-th$ minibatch and not\n", "all $n$ datapoints.\n", "\n", - "\n", - "\n", "A natural question is when do we stop the search for a new minimum?\n", "One possibility is to compute the full gradient after a given number\n", "of epochs and check if the norm of the gradient is smaller than some\n", @@ -1732,8 +2148,6 @@ "compare the values of the cost function and keep the $\\beta$ that\n", "gave the lowest value.\n", "\n", - "\n", - "\n", "Another approach is to let the step length $\\gamma_j$ depend on the\n", "number of epochs in such a way that it becomes very small after a\n", "reasonable time such that we do not move at all.\n", @@ -1749,7 +2163,8 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 11, + "id": "d2921658", "metadata": { "collapsed": false, "editable": true @@ -1784,48 +2199,62 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "84469eb8", + "metadata": { + "editable": true + }, + "source": [ + "We note that we have defined several hyperparameters. These are now the number of epochs, the number of mini-batches and the parameters $t_0$ and $t_1$." + ] + }, + { + "cell_type": "markdown", + "id": "b4b94e7a", + "metadata": { + "editable": true + }, "source": [ "### Program for stochastic gradient" ] }, { "cell_type": "code", - "execution_count": null, + "execution_count": 12, + "id": "71dcdb35", "metadata": { "collapsed": false, "editable": true }, "outputs": [], "source": [ + "# Importing various packages\n", "# Importing various packages\n", "from math import exp, sqrt\n", "from random import random, seed\n", "import numpy as np\n", "import matplotlib.pyplot as plt\n", - "from sklearn.linear_model import SGDRegressor\n", "\n", - "m = 100\n", - "x = 2*np.random.rand(m,1)\n", - "y = 4+3*x+np.random.randn(m,1)\n", + "n = 100\n", + "x = 2*np.random.rand(n,1)\n", + "y = 4+3*x+np.random.randn(n,1)\n", "\n", - "X = np.c_[np.ones((m,1)), x]\n", + "X = np.c_[np.ones((n,1)), x]\n", + "XT_X = X.T @ X\n", "theta_linreg = np.linalg.inv(X.T @ X) @ (X.T @ y)\n", "print(\"Own inversion\")\n", "print(theta_linreg)\n", - "sgdreg = SGDRegressor(max_iter = 50, penalty=None, eta0=0.1)\n", - "sgdreg.fit(x,y.ravel())\n", - "print(\"sgdreg from scikit\")\n", - "print(sgdreg.intercept_, sgdreg.coef_)\n", - "\n", + "# Hessian matrix\n", + "H = (2.0/n)* XT_X\n", + "EigValues, EigVectors = np.linalg.eig(H)\n", + "print(f\"Eigenvalues of Hessian Matrix:{EigValues}\")\n", "\n", "theta = np.random.randn(2,1)\n", - "eta = 0.1\n", + "eta = 1.0/np.max(EigValues)\n", "Niterations = 1000\n", "\n", "\n", "for iter in range(Niterations):\n", - " gradients = 2.0/m*X.T @ ((X @ theta)-y)\n", + " gradients = 2.0/n*X.T @ ((X @ theta)-y)\n", " theta -= eta*gradients\n", "print(\"theta from own gd\")\n", "print(theta)\n", @@ -1835,8 +2264,9 @@ "ypredict = Xnew.dot(theta)\n", "ypredict2 = Xnew.dot(theta_linreg)\n", "\n", - "\n", "n_epochs = 50\n", + "M = 5 #size of each minibatch\n", + "m = int(n/M) #number of minibatches\n", "t0, t1 = 5, 50\n", "def learning_schedule(t):\n", " return t0/(t+t1)\n", @@ -1844,16 +2274,20 @@ "theta = np.random.randn(2,1)\n", "\n", "for epoch in range(n_epochs):\n", + "# Can you figure out a better way of setting up the contributions to each batch?\n", " for i in range(m):\n", - " random_index = np.random.randint(m)\n", - " xi = X[random_index:random_index+1]\n", - " yi = y[random_index:random_index+1]\n", - " gradients = 2 * xi.T @ ((xi @ theta)-yi)\n", + " random_index = M*np.random.randint(m)\n", + " xi = X[random_index:random_index+M]\n", + " yi = y[random_index:random_index+M]\n", + " gradients = (2.0/M)* xi.T @ ((xi @ theta)-yi)\n", " eta = learning_schedule(epoch*m+i)\n", " theta = theta - eta*gradients\n", "print(\"theta from own sdg\")\n", "print(theta)\n", "\n", + "\n", + "\n", + "\n", "plt.plot(xnew, ypredict, \"r-\")\n", "plt.plot(xnew, ypredict2, \"b-\")\n", "plt.plot(x, y ,'ro')\n", @@ -1866,7 +2300,23 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "6231b86f", + "metadata": { + "editable": true + }, + "source": [ + "In the above code, we have use replacement in setting up the\n", + "mini-batches. The discussion\n", + "[here](https://sebastianraschka.com/faq/docs/sgd-methods.html) may be\n", + "useful. More material will be added later." + ] + }, + { + "cell_type": "markdown", + "id": "8d50214c", + "metadata": { + "editable": true + }, "source": [ "## Momentum based GD\n", "\n", @@ -1878,7 +2328,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "45d43ca3", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\mathbf{v}_{t}=\\gamma \\mathbf{v}_{t-1}+\\eta_{t}\\nabla_\\theta E(\\boldsymbol{\\theta}_t) \\nonumber\n", @@ -1887,7 +2340,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "dcdd91bf", + "metadata": { + "editable": true + }, "source": [ "\n", "
\n", @@ -1902,7 +2358,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "c7519d1e", + "metadata": { + "editable": true + }, "source": [ "where we have introduced a momentum parameter $\\gamma$, with\n", "$0\\le\\gamma\\le 1$, and for brevity we dropped the explicit notation to\n", @@ -1918,7 +2377,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "f4d4340d", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\Delta \\boldsymbol{\\theta}_{t+1} = \\gamma \\Delta \\boldsymbol{\\theta}_t -\\ \\eta_{t}\\nabla_\\theta E(\\boldsymbol{\\theta}_t),\n", @@ -1927,12 +2389,13 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "41ad532a", + "metadata": { + "editable": true + }, "source": [ "where we have defined $\\Delta \\boldsymbol{\\theta}_{t}= \\boldsymbol{\\theta}_t-\\boldsymbol{\\theta}_{t-1}$.\n", "\n", - "\n", - "\n", "Let us try to get more intuition from these equations. It is helpful\n", "to consider a simple physical analogy with a particle of mass $m$\n", "moving in a viscous medium with drag coefficient $\\mu$ and potential\n", @@ -1942,7 +2405,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "eef8ae92", + "metadata": { + "editable": true + }, "source": [ "$$\n", "m {d^2 \\mathbf{w} \\over dt^2} + \\mu {d \\mathbf{w} \\over dt }= -\\nabla_w E(\\mathbf{w}).\n", @@ -1951,14 +2417,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "80481a6d", + "metadata": { + "editable": true + }, "source": [ "We can discretize this equation in the usual way to get" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "6aab8db7", + "metadata": { + "editable": true + }, "source": [ "$$\n", "m { \\mathbf{w}_{t+\\Delta t}-2 \\mathbf{w}_{t} +\\mathbf{w}_{t-\\Delta t} \\over (\\Delta t)^2}+\\mu {\\mathbf{w}_{t+\\Delta t}- \\mathbf{w}_{t} \\over \\Delta t} = -\\nabla_w E(\\mathbf{w}).\n", @@ -1967,14 +2439,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "dd6414d2", + "metadata": { + "editable": true + }, "source": [ "Rearranging this equation, we can rewrite this as" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "b76a8372", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\Delta \\mathbf{w}_{t +\\Delta t}= - { (\\Delta t)^2 \\over m +\\mu \\Delta t} \\nabla_w E(\\mathbf{w})+ {m \\over m +\\mu \\Delta t} \\Delta \\mathbf{w}_t.\n", @@ -1983,7 +2461,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "07bbe6db", + "metadata": { + "editable": true + }, "source": [ "Notice that this equation is identical to previous one if we identify\n", "the position of the particle, $\\mathbf{w}$, with the parameters\n", @@ -1994,7 +2475,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "7a9a2ecf", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\gamma= {m \\over m +\\mu \\Delta t }, \\qquad \\eta = {(\\Delta t)^2 \\over m +\\mu \\Delta t}.\n", @@ -2003,7 +2487,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "fe5a2bbc", + "metadata": { + "editable": true + }, "source": [ "Thus, as the name suggests, the momentum parameter is proportional to\n", "the mass of the particle and effectively provides inertia.\n", @@ -2033,7 +2520,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "04540023", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\mathbf{v}_{t}=\\gamma \\mathbf{v}_{t-1}+\\eta_{t}\\nabla_\\theta E(\\boldsymbol{\\theta}_t +\\gamma \\mathbf{v}_{t-1}) \\nonumber\n", @@ -2042,7 +2532,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "dfbf53a5", + "metadata": { + "editable": true + }, "source": [ "\n", "
\n", @@ -2057,12 +2550,13 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "32ac3869", + "metadata": { + "editable": true + }, "source": [ "One of the major advantages of NAG is that it allows for the use of a larger learning rate than GDM for the same choice of $\\gamma$.\n", "\n", - "\n", - "\n", "In stochastic gradient descent, with and without momentum, we still\n", "have to specify a schedule for tuning the learning rates $\\eta_t$\n", "as a function of time. As discussed in the context of Newton's\n", @@ -2081,10 +2575,17 @@ "\n", "Recently, a number of methods have been introduced that accomplish\n", "this by tracking not only the gradient, but also the second moment of\n", - "the gradient. These methods include AdaGrad, AdaDelta, RMS-Prop, and\n", - "ADAM.\n", - "\n", - "\n", + "the gradient. These methods include AdaGrad, AdaDelta, Root Mean Squared Propagation (RMS-Prop), and\n", + "ADAM." + ] + }, + { + "cell_type": "markdown", + "id": "6f575b16", + "metadata": { + "editable": true + }, + "source": [ "### RMS prop\n", "\n", "In RMS prop, in addition to keeping a running average of the first\n", @@ -2095,7 +2596,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "274604c4", + "metadata": { + "editable": true + }, "source": [ "\n", "
\n", @@ -2110,7 +2614,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "cd679323", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\mathbf{s}_t =\\beta \\mathbf{s}_{t-1} +(1-\\beta)\\mathbf{g}_t^2 \\nonumber\n", @@ -2119,7 +2626,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "0a7f8e9d", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\boldsymbol{\\theta}_{t+1}=\\boldsymbol{\\theta}_t - \\eta_t { \\mathbf{g}_t \\over \\sqrt{\\mathbf{s}_t +\\epsilon}}, \\nonumber\n", @@ -2128,7 +2638,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "48ba8fff", + "metadata": { + "editable": true + }, "source": [ "where $\\beta$ controls the averaging time of the second moment and is\n", "typically taken to be about $\\beta=0.9$, $\\eta_t$ is a learning rate\n", @@ -2138,8 +2651,16 @@ "is clear from this formula that the learning rate is reduced in\n", "directions where the norm of the gradient is consistently large. This\n", "greatly speeds up the convergence by allowing us to use a larger\n", - "learning rate for flat directions.\n", - "\n", + "learning rate for flat directions." + ] + }, + { + "cell_type": "markdown", + "id": "83140ab2", + "metadata": { + "editable": true + }, + "source": [ "### ADAM optimizer\n", "\n", "A related algorithm is the ADAM optimizer. In ADAM, we keep a running\n", @@ -2158,7 +2679,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "61874dc3", + "metadata": { + "editable": true + }, "source": [ "\n", "
\n", @@ -2173,7 +2697,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "24e19d86", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\mathbf{m}_t = \\beta_1 \\mathbf{m}_{t-1} + (1-\\beta_1) \\mathbf{g}_t \\nonumber\n", @@ -2182,7 +2709,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "506f78ea", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\mathbf{s}_t =\\beta_2 \\mathbf{s}_{t-1} +(1-\\beta_2)\\mathbf{g}_t^2 \\nonumber\n", @@ -2191,7 +2721,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "cb4b8585", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\boldsymbol{\\mathbf{m}}_t={\\mathbf{m}_t \\over 1-\\beta_1^t} \\nonumber\n", @@ -2200,7 +2733,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "9b5b11b1", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\boldsymbol{\\mathbf{s}}_t ={\\mathbf{s}_t \\over1-\\beta_2^t} \\nonumber\n", @@ -2209,7 +2745,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "92292a73", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\boldsymbol{\\theta}_{t+1}=\\boldsymbol{\\theta}_t - \\eta_t { \\boldsymbol{\\mathbf{m}}_t \\over \\sqrt{\\boldsymbol{\\mathbf{s}}_t} +\\epsilon}, \\nonumber\n", @@ -2218,7 +2757,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "1a264832", + "metadata": { + "editable": true + }, "source": [ "\n", "
\n", @@ -2232,7 +2774,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "6a307202", + "metadata": { + "editable": true + }, "source": [ "where $\\beta_1$ and $\\beta_2$ set the memory lifetime of the first and\n", "second moment and are typically taken to be $0.9$ and $0.99$\n", @@ -2248,7 +2793,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "3285f010", + "metadata": { + "editable": true + }, "source": [ "$$\n", "\\Delta \\theta_{t+1}= -\\eta_t { \\boldsymbol{m}_t \\over \\sqrt{\\sigma_t^2 + m_t^2 }+\\epsilon}.\n", @@ -2257,7 +2805,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "657349da", + "metadata": { + "editable": true + }, "source": [ "## Practical tips\n", "\n", @@ -2267,8 +2818,16 @@ "\n", "* **Monitor the out-of-sample performance.** Always monitor the performance of your model on a validation set (a small portion of the training data that is held out of the training process to serve as a proxy for the test set. If the validation error starts increasing, then the model is beginning to overfit. Terminate the learning process. This *early stopping* significantly improves performance in many settings.\n", "\n", - "* **Adaptive optimization methods don't always have good generalization.** Recent studies have shown that adaptive methods such as ADAM, RMSPorp, and AdaGrad tend to have poor generalization compared to SGD or SGD with momentum, particularly in the high-dimensional limit (i.e. the number of parameters exceeds the number of data points). Although it is not clear at this stage why these methods perform so well in training deep neural networks, simpler procedures like properly-tuned SGD may work as well or better in these applications.\n", - "\n", + "* **Adaptive optimization methods don't always have good generalization.** Recent studies have shown that adaptive methods such as ADAM, RMSPorp, and AdaGrad tend to have poor generalization compared to SGD or SGD with momentum, particularly in the high-dimensional limit (i.e. the number of parameters exceeds the number of data points). Although it is not clear at this stage why these methods perform so well in training deep neural networks, simpler procedures like properly-tuned SGD may work as well or better in these applications." + ] + }, + { + "cell_type": "markdown", + "id": "65044ac7", + "metadata": { + "editable": true + }, + "source": [ "## Automatic differentiation\n", "\n", "[Automatic differentiation (AD)](https://en.wikipedia.org/wiki/Automatic_differentiation), \n", @@ -2296,15 +2855,16 @@ "while numerical differentiation can introduce round-off errors in the\n", "discretization process and cancellation\n", "\n", - "\n", - "\n", "Python has tools for so-called **automatic differentiation**.\n", "Consider the following example" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "dacf05cf", + "metadata": { + "editable": true + }, "source": [ "$$\n", "f(x) = \\sin\\left(2\\pi x + x^2\\right)\n", @@ -2313,14 +2873,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "da4ad36e", + "metadata": { + "editable": true + }, "source": [ "which has the following derivative" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "f4c3e6c4", + "metadata": { + "editable": true + }, "source": [ "$$\n", "f'(x) = \\cos\\left(2\\pi x + x^2\\right)\\left(2\\pi + 2x\\right)\n", @@ -2329,14 +2895,18 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "1c8bfd4a", + "metadata": { + "editable": true + }, "source": [ "Using **autograd** we have" ] }, { "cell_type": "code", - "execution_count": null, + "execution_count": 13, + "id": "e1d91b8b", "metadata": { "collapsed": false, "editable": true @@ -2381,7 +2951,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "cd1158a5", + "metadata": { + "editable": true + }, "source": [ "Here we\n", "experiment with what kind of functions Autograd is capable\n", @@ -2392,7 +2965,8 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 14, + "id": "e2e9faff", "metadata": { "collapsed": false, "editable": true @@ -2420,7 +2994,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "e4a83059", + "metadata": { + "editable": true + }, "source": [ "To differentiate with respect to two (or more) arguments of a Python\n", "function, Autograd need to know at which variable the function if\n", @@ -2429,7 +3006,8 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 15, + "id": "f65983d8", "metadata": { "collapsed": false, "editable": true @@ -2473,14 +3051,18 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "1d369f97", + "metadata": { + "editable": true + }, "source": [ "Note that the grad function will not produce the true gradient of the function. The true gradient of a function with two or more variables will produce a vector, where each element is the function differentiated w.r.t a variable." ] }, { "cell_type": "code", - "execution_count": null, + "execution_count": 16, + "id": "46ea0652", "metadata": { "collapsed": false, "editable": true @@ -2508,7 +3090,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "9cc6674a", + "metadata": { + "editable": true + }, "source": [ "Note that in this case, when sending an array as input argument, the\n", "output from Autograd is another array. This is the true gradient of\n", @@ -2520,7 +3105,8 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 17, + "id": "17813055", "metadata": { "collapsed": false, "editable": true @@ -2548,7 +3134,8 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 18, + "id": "6da49540", "metadata": { "collapsed": false, "editable": true @@ -2572,39 +3159,45 @@ ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "code", + "execution_count": 19, + "id": "a8ff2c17", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], "source": [ - "1\n", - "8\n", - " \n", - "<\n", - "<\n", - "<\n", - "!\n", - "!\n", - "C\n", - "O\n", - "D\n", - "E\n", - "_\n", - "B\n", - "L\n", - "O\n", - "C\n", - "K\n", - " \n", - " \n", - "p\n", - "y\n", - "c\n", - "o\n", - "d" + "import autograd.numpy as np\n", + "from autograd import grad\n", + "def f6_for(x):\n", + " val = 0\n", + " for i in range(10):\n", + " val = val + x**i\n", + " return val\n", + "\n", + "def f6_while(x):\n", + " val = 0\n", + " i = 0\n", + " while i < 10:\n", + " val = val + x**i\n", + " i = i + 1\n", + " return val\n", + "\n", + "f6_for_grad = grad(f6_for)\n", + "f6_while_grad = grad(f6_while)\n", + "\n", + "x = 0.5\n", + "\n", + "# Print the computed derivaties of f6_for and f6_while\n", + "print(\"The computed derivative of f6_for at x = %g is: %g\"%(x,f6_for_grad(x)))\n", + "print(\"The computed derivative of f6_while at x = %g is: %g\"%(x,f6_while_grad(x)))" ] }, { "cell_type": "code", - "execution_count": null, + "execution_count": 20, + "id": "ec67d4a3", "metadata": { "collapsed": false, "editable": true @@ -2624,7 +3217,8 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 21, + "id": "742a2d68", "metadata": { "collapsed": false, "editable": true @@ -2662,48 +3256,55 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "e7be6348", + "metadata": { + "editable": true + }, "source": [ "Note that if n is equal to zero or one, Autograd will give an error message. This message appears when the output is independent on input.\n", "\n", + "Autograd supports many features. However, there are some functions that is not supported (yet) by Autograd.\n", "\n", - "Autograd supports many features. However, there are some functions that are not supported (yet) by Autograd.\n", - "\n", - "Assigning a value to the variable being differentiated with respect to is an example thereof." + "Assigning a value to the variable being differentiated with respect to" ] }, { "cell_type": "code", - "execution_count": null, + "execution_count": 22, + "id": "c551058c", "metadata": { "collapsed": false, "editable": true }, "outputs": [], "source": [ - "#import autograd.numpy as np\n", - "#from autograd import grad\n", - "#def f8(x): # Assume x is an array\n", - "# x[2] = 3\n", - "# return x*2\n", + "import autograd.numpy as np\n", + "from autograd import grad\n", + "def f8(x): # Assume x is an array\n", + " x[2] = 3\n", + " return x*2\n", "\n", - "#f8_grad = grad(f8)\n", + "f8_grad = grad(f8)\n", "\n", - "#x = 8.4\n", + "x = 8.4\n", "\n", - "#print(\"The derivative of f8 is:\",f8_grad(x))" + "print(\"The derivative of f8 is:\",f8_grad(x))" ] }, { "cell_type": "markdown", - "metadata": {}, + "id": "7a13b21d", + "metadata": { + "editable": true + }, "source": [ "Here, Autograd tells us that an 'ArrayBox' does not support item assignment. The item assignment is done when the program tries to assign x[2] to the value 3. However, Autograd has implemented the computation of the derivative such that this assignment is not possible." ] }, { "cell_type": "code", - "execution_count": null, + "execution_count": 23, + "id": "19c7502b", "metadata": { "collapsed": false, "editable": true @@ -2725,7 +3326,10 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "4450885d", + "metadata": { + "editable": true + }, "source": [ "Here we are told that the 'dot' function does not belong to Autograd's\n", "version of a Numpy array. To overcome this, an alternative syntax\n", @@ -2734,7 +3338,8 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 24, + "id": "013fc7f8", "metadata": { "collapsed": false, "editable": true @@ -2759,14 +3364,18 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "8d360f7d", + "metadata": { + "editable": true + }, "source": [ "The documentation recommends to avoid inplace operations such as" ] }, { "cell_type": "code", - "execution_count": null, + "execution_count": 25, + "id": "e29a24eb", "metadata": { "collapsed": false, "editable": true @@ -2781,13 +3390,233 @@ }, { "cell_type": "markdown", - "metadata": {}, + "id": "ad8fbbb7", + "metadata": { + "editable": true + }, "source": [ - "More examples will be added, in particular how to compare autograd with own codes for the gradients." + "## Using Autograd with OLS\n", + "\n", + "We conclude the part on optmization by showing how we can make codes\n", + "for linear regression and logistic regression using **autograd**. The\n", + "first example shows results with ordinary leats squares." + ] + }, + { + "cell_type": "code", + "execution_count": 26, + "id": "904f65dc", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "# Using Autograd to calculate gradients for OLS\n", + "from random import random, seed\n", + "import numpy as np\n", + "import autograd.numpy as np\n", + "import matplotlib.pyplot as plt\n", + "from autograd import grad\n", + "\n", + "def CostOLS(beta):\n", + " return (1.0/n)*np.sum((y-X @ beta)**2)\n", + "\n", + "n = 100\n", + "x = 2*np.random.rand(n,1)\n", + "y = 4+3*x+np.random.randn(n,1)\n", + "\n", + "X = np.c_[np.ones((n,1)), x]\n", + "XT_X = X.T @ X\n", + "theta_linreg = np.linalg.pinv(XT_X) @ (X.T @ y)\n", + "print(\"Own inversion\")\n", + "print(theta_linreg)\n", + "# Hessian matrix\n", + "H = (2.0/n)* XT_X\n", + "EigValues, EigVectors = np.linalg.eig(H)\n", + "print(f\"Eigenvalues of Hessian Matrix:{EigValues}\")\n", + "\n", + "theta = np.random.randn(2,1)\n", + "eta = 1.0/np.max(EigValues)\n", + "Niterations = 1000\n", + "# define the gradient\n", + "training_gradient = grad(CostOLS)\n", + "\n", + "for iter in range(Niterations):\n", + " gradients = training_gradient(theta)\n", + " theta -= eta*gradients\n", + "print(\"theta from own gd\")\n", + "print(theta)\n", + "\n", + "xnew = np.array([[0],[2]])\n", + "Xnew = np.c_[np.ones((2,1)), xnew]\n", + "ypredict = Xnew.dot(theta)\n", + "ypredict2 = Xnew.dot(theta_linreg)\n", + "\n", + "plt.plot(xnew, ypredict, \"r-\")\n", + "plt.plot(xnew, ypredict2, \"b-\")\n", + "plt.plot(x, y ,'ro')\n", + "plt.axis([0,2.0,0, 15.0])\n", + "plt.xlabel(r'$x$')\n", + "plt.ylabel(r'$y$')\n", + "plt.title(r'Random numbers ')\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "ce338980", + "metadata": { + "editable": true + }, + "source": [ + "### Including Stochastic Gradient Descent with Autograd\n", + "\n", + "In this code we include the stochastic gradient descent approach discussed above. Note here that we specify which argument we are taking the derivative with respect to when using **autograd**." + ] + }, + { + "cell_type": "code", + "execution_count": 27, + "id": "de261f10", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "# Using Autograd to calculate gradients using SGD\n", + "# OLS example\n", + "from random import random, seed\n", + "import numpy as np\n", + "import autograd.numpy as np\n", + "import matplotlib.pyplot as plt\n", + "from autograd import grad\n", + "\n", + "# Note change from previous example\n", + "def CostOLS(y,X,theta):\n", + " return np.sum((y-X @ theta)**2)\n", + "\n", + "n = 100\n", + "x = 2*np.random.rand(n,1)\n", + "y = 4+3*x+np.random.randn(n,1)\n", + "\n", + "X = np.c_[np.ones((n,1)), x]\n", + "XT_X = X.T @ X\n", + "theta_linreg = np.linalg.pinv(XT_X) @ (X.T @ y)\n", + "print(\"Own inversion\")\n", + "print(theta_linreg)\n", + "# Hessian matrix\n", + "H = (2.0/n)* XT_X\n", + "EigValues, EigVectors = np.linalg.eig(H)\n", + "print(f\"Eigenvalues of Hessian Matrix:{EigValues}\")\n", + "\n", + "theta = np.random.randn(2,1)\n", + "eta = 1.0/np.max(EigValues)\n", + "Niterations = 1000\n", + "\n", + "# Note that we request the derivative wrt third argument (theta, 2 here)\n", + "training_gradient = grad(CostOLS,2)\n", + "\n", + "for iter in range(Niterations):\n", + " gradients = (1.0/n)*training_gradient(y, X, theta)\n", + " theta -= eta*gradients\n", + "print(\"theta from own gd\")\n", + "print(theta)\n", + "\n", + "xnew = np.array([[0],[2]])\n", + "Xnew = np.c_[np.ones((2,1)), xnew]\n", + "ypredict = Xnew.dot(theta)\n", + "ypredict2 = Xnew.dot(theta_linreg)\n", + "\n", + "plt.plot(xnew, ypredict, \"r-\")\n", + "plt.plot(xnew, ypredict2, \"b-\")\n", + "plt.plot(x, y ,'ro')\n", + "plt.axis([0,2.0,0, 15.0])\n", + "plt.xlabel(r'$x$')\n", + "plt.ylabel(r'$y$')\n", + "plt.title(r'Random numbers ')\n", + "plt.show()\n", + "\n", + "n_epochs = 50\n", + "M = 5 #size of each minibatch\n", + "m = int(n/M) #number of minibatches\n", + "t0, t1 = 5, 50\n", + "def learning_schedule(t):\n", + " return t0/(t+t1)\n", + "\n", + "theta = np.random.randn(2,1)\n", + "\n", + "for epoch in range(n_epochs):\n", + "# Can you figure out a better way of setting up the contributions to each batch?\n", + " for i in range(m):\n", + " random_index = M*np.random.randint(m)\n", + " xi = X[random_index:random_index+M]\n", + " yi = y[random_index:random_index+M]\n", + " gradients = (1.0/M)*training_gradient(yi, xi, theta)\n", + " eta = learning_schedule(epoch*m+i)\n", + " theta = theta - eta*gradients\n", + "print(\"theta from own sdg\")\n", + "print(theta)" + ] + }, + { + "cell_type": "markdown", + "id": "ccd8829e", + "metadata": { + "editable": true + }, + "source": [ + "### And Logistic Regression" + ] + }, + { + "cell_type": "code", + "execution_count": 28, + "id": "cc5811d1", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "import autograd.numpy as np\n", + "from autograd import grad\n", + "\n", + "def sigmoid(x):\n", + " return 0.5 * (np.tanh(x / 2.) + 1)\n", + "\n", + "def logistic_predictions(weights, inputs):\n", + " # Outputs probability of a label being true according to logistic model.\n", + " return sigmoid(np.dot(inputs, weights))\n", + "\n", + "def training_loss(weights):\n", + " # Training loss is the negative log-likelihood of the training labels.\n", + " preds = logistic_predictions(weights, inputs)\n", + " label_probabilities = preds * targets + (1 - preds) * (1 - targets)\n", + " return -np.sum(np.log(label_probabilities))\n", + "\n", + "# Build a toy dataset.\n", + "inputs = np.array([[0.52, 1.12, 0.77],\n", + " [0.88, -1.08, 0.15],\n", + " [0.52, 0.06, -1.30],\n", + " [0.74, -2.49, 1.39]])\n", + "targets = np.array([True, True, False, True])\n", + "\n", + "# Define a function that returns gradients of training loss using Autograd.\n", + "training_gradient_fun = grad(training_loss)\n", + "\n", + "# Optimize weights using gradient descent.\n", + "weights = np.array([0.0, 0.0, 0.0])\n", + "print(\"Initial loss:\", training_loss(weights))\n", + "for i in range(100):\n", + " weights -= training_gradient_fun(weights) * 0.01\n", + "\n", + "print(\"Trained loss:\", training_loss(weights))" ] } ], "metadata": {}, "nbformat": 4, - "nbformat_minor": 4 + "nbformat_minor": 5 }