From b0ef411bea5b494c0247cc5e1b5016f36701862c Mon Sep 17 00:00:00 2001 From: Morten Hjorth-Jensen Date: Mon, 20 Oct 2025 07:56:38 +0200 Subject: [PATCH] updated notes --- .../_build/.doctrees/environment.pickle | Bin 473864 -> 473882 bytes doc/LectureNotes/week43.ipynb | 5948 +++++++++++++++++ 2 files changed, 5948 insertions(+) create mode 100644 doc/LectureNotes/week43.ipynb diff --git a/doc/LectureNotes/_build/.doctrees/environment.pickle b/doc/LectureNotes/_build/.doctrees/environment.pickle index fd4f70d257c2151ce115c0a35dae74c3ad5df21c..9fcf28611fd201a8eb3dca60a22e130702ac2cc9 100644 GIT binary patch literal 473882 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[Q1pNVhh?}lu-I{X- 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

=^IK~2)iafGbhMMi8qF(yY)s_%|)U}B#__@ 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 literal 473864 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 ZM?JoJ8e-K0{SWJ_c-&GxjG@}b{|_%MG!g&+ diff --git a/doc/LectureNotes/week43.ipynb b/doc/LectureNotes/week43.ipynb new file mode 100644 index 000000000..3e86d5cdb --- /dev/null +++ b/doc/LectureNotes/week43.ipynb @@ -0,0 +1,5948 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "8c52cd3b", + "metadata": { + "editable": true + }, + "source": [ + "\n", + "" + ] + }, + { + "cell_type": "markdown", + "id": "846eee41", + "metadata": { + "editable": true + }, + "source": [ + "# Week 43: Deep Learning: Constructing a Neural Network code and solving differential equations\n", + "**Morten Hjorth-Jensen**, Department of Physics, University of Oslo, Norway\n", + "\n", + "Date: **October 20, 2025**" + ] + }, + { + "cell_type": "markdown", + "id": "ff057bd5", + "metadata": { + "editable": true + }, + "source": [ + "## Plans for week 43\n", + "\n", + "**Material for the lecture on Monday October 20, 2025.**\n", + "\n", + "1. Reminder from last week, see lalso ecture notes from week 42 at as well as those from week 41, see see . \n", + "\n", + "2. Building our own Feed-forward Neural Network.\n", + "\n", + "3. Coding examples using Tensorflow/Keras and Pytorch examples. The Pytorch examples are adapted from Rashcka's text, see chapters 11-13.. \n", + "\n", + "4. Start discussions on how to use neural networks for solving differential equations (ordinary and partial ones). This topic continues next week as well.\n", + "\n", + "" + ] + }, + { + "cell_type": "markdown", + "id": "8d1fd0b3", + "metadata": { + "editable": true + }, + "source": [ + "## Exercises and lab session week 43\n", + "**Lab sessions on Tuesday and Wednesday.**\n", + "\n", + "1. Work on writing your own neural network code and discussions of project 2. If you didn't get time to do the exercises from the two last weeks, we recommend doing so as these exercises give you the basic elements of a neural network code.\n", + "\n", + "2. The exercises this week are tailored to the optional part of project 2, and deal with studying ways to display results from classification problems" + ] + }, + { + "cell_type": "markdown", + "id": "4990faa2", + "metadata": { + "editable": true + }, + "source": [ + "## Using Automatic differentiation\n", + "\n", + "In our discussions of ordinary differential equations and neural network codes\n", + "we will also study the usage of Autograd, see for example in computing gradients for deep learning. For the documentation of Autograd and examples see the Autograd documentation at and the lecture slides from week 41, see ." + ] + }, + { + "cell_type": "markdown", + "id": "76cb0250", + "metadata": { + "editable": true + }, + "source": [ + "## Back propagation and automatic differentiation\n", + "\n", + "For more details on the back propagation algorithm and automatic differentiation see\n", + "1. \n", + "\n", + "2. \n", + "\n", + "3. Slides 12-44 at " + ] + }, + { + "cell_type": "markdown", + "id": "5bdfe8a0", + "metadata": { + "editable": true + }, + "source": [ + "## Lecture Monday October 20" + ] + }, + { + "cell_type": "markdown", + "id": "b78c27be", + "metadata": { + "editable": true + }, + "source": [ + "## Setting up the back propagation algorithm and algorithm for a feed forward NN, initalizations\n", + "This is a reminder from last week.\n", + "\n", + "**The architecture (our model).**\n", + "\n", + "1. Set up your inputs and outputs (scalars, vectors, matrices or higher-order arrays)\n", + "\n", + "2. Define the number of hidden layers and hidden nodes\n", + "\n", + "3. Define activation functions for hidden layers and output layers\n", + "\n", + "4. Define optimizer (plan learning rate, momentum, ADAgrad, RMSprop, ADAM etc) and array of initial learning rates\n", + "\n", + "5. Define cost function and possible regularization terms with hyperparameters\n", + "\n", + "6. Initialize weights and biases\n", + "\n", + "7. Fix number of iterations for the feed forward part and back propagation part" + ] + }, + { + "cell_type": "markdown", + "id": "db515eac", + "metadata": { + "editable": true + }, + "source": [ + "## Setting up the back propagation algorithm, part 1\n", + "\n", + "Let us write this out in the form of an algorithm.\n", + "\n", + "**First**, we set up the input data $\\boldsymbol{x}$ and the activations\n", + "$\\boldsymbol{z}_1$ of the input layer and compute the activation function and\n", + "the pertinent outputs $\\boldsymbol{a}^1$.\n", + "\n", + "**Secondly**, we perform then the feed forward till we reach the output\n", + "layer and compute all $\\boldsymbol{z}_l$ of the input layer and compute the\n", + "activation function and the pertinent outputs $\\boldsymbol{a}^l$ for\n", + "$l=1,2,3,\\dots,L$.\n", + "\n", + "**Notation**: The first hidden layer has $l=1$ as label and the final output layer has $l=L$." + ] + }, + { + "cell_type": "markdown", + "id": "0d9e2c6d", + "metadata": { + "editable": true + }, + "source": [ + "## Setting up the back propagation algorithm, part 2\n", + "\n", + "Thereafter we compute the ouput error $\\boldsymbol{\\delta}^L$ by computing all" + ] + }, + { + "cell_type": "markdown", + "id": "c54ddbb9", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "\\delta_j^L = \\sigma'(z_j^L)\\frac{\\partial {\\cal C}}{\\partial (a_j^L)}.\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "0a074eb8", + "metadata": { + "editable": true + }, + "source": [ + "Then we compute the back propagate error for each $l=L-1,L-2,\\dots,1$ as" + ] + }, + { + "cell_type": "markdown", + "id": "2916e7ad", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "\\delta_j^l = \\sum_k \\delta_k^{l+1}w_{kj}^{l+1}\\sigma'(z_j^l).\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "fc87090a", + "metadata": { + "editable": true + }, + "source": [ + "## Setting up the Back propagation algorithm, part 3\n", + "\n", + "Finally, we update the weights and the biases using gradient descent\n", + "for each $l=L-1,L-2,\\dots,1$ (the first hidden layer) and update the weights and biases\n", + "according to the rules" + ] + }, + { + "cell_type": "markdown", + "id": "0fab3976", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "w_{ij}^l\\leftarrow = w_{ij}^l- \\eta \\delta_j^la_i^{l-1},\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "506b036e", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "b_j^l \\leftarrow b_j^l-\\eta \\frac{\\partial {\\cal C}}{\\partial b_j^l}=b_j^l-\\eta \\delta_j^l,\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "7230ebb2", + "metadata": { + "editable": true + }, + "source": [ + "with $\\eta$ being the learning rate." + ] + }, + { + "cell_type": "markdown", + "id": "24dcabf8", + "metadata": { + "editable": true + }, + "source": [ + "## Updating the gradients\n", + "\n", + "With the back propagate error for each $l=L-1,L-2,\\dots,1$ as" + ] + }, + { + "cell_type": "markdown", + "id": "769b4b46", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "\\delta_j^l = \\sum_k \\delta_k^{l+1}w_{kj}^{l+1}\\sigma'(z_j^l),\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "0eb6e407", + "metadata": { + "editable": true + }, + "source": [ + "we update the weights and the biases using gradient descent for each $l=L-1,L-2,\\dots,1$ and update the weights and biases according to the rules" + ] + }, + { + "cell_type": "markdown", + "id": "dd2caf09", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "w_{ij}^l\\leftarrow = w_{ij}^l- \\eta \\delta_j^la_i^{l-1},\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "3ca5122d", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "b_j^l \\leftarrow b_j^l-\\eta \\frac{\\partial {\\cal C}}{\\partial b_j^l}=b_j^l-\\eta \\delta_j^l,\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "0297fbd7", + "metadata": { + "editable": true + }, + "source": [ + "## Activation functions\n", + "\n", + "A property that characterizes a neural network, other than its\n", + "connectivity, is the choice of activation function(s). The following\n", + "restrictions are imposed on an activation function for an FFNN to\n", + "fulfill the universal approximation theorem\n", + "\n", + " * Non-constant\n", + "\n", + " * Bounded\n", + "\n", + " * Monotonically-increasing\n", + "\n", + " * Continuous" + ] + }, + { + "cell_type": "markdown", + "id": "093209ef", + "metadata": { + "editable": true + }, + "source": [ + "### Activation functions, examples\n", + "\n", + "Typical examples are the logistic *Sigmoid*" + ] + }, + { + "cell_type": "markdown", + "id": "52cacfbe", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "\\sigma(x) = \\frac{1}{1 + e^{-x}},\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "3ac82bdf", + "metadata": { + "editable": true + }, + "source": [ + "and the *hyperbolic tangent* function" + ] + }, + { + "cell_type": "markdown", + "id": "e3f9be3c", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "\\sigma(x) = \\tanh(x)\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "fdb953a2", + "metadata": { + "editable": true + }, + "source": [ + "## The RELU function family\n", + "\n", + "The ReLU activation function suffers from a problem known as the dying\n", + "ReLUs: during training, some neurons effectively die, meaning they\n", + "stop outputting anything other than 0.\n", + "\n", + "In some cases, you may find that half of your network’s neurons are\n", + "dead, especially if you used a large learning rate. During training,\n", + "if a neuron’s weights get updated such that the weighted sum of the\n", + "neuron’s inputs is negative, it will start outputting 0. When this\n", + "happen, the neuron is unlikely to come back to life since the gradient\n", + "of the ReLU function is 0 when its input is negative." + ] + }, + { + "cell_type": "markdown", + "id": "0d8677dd", + "metadata": { + "editable": true + }, + "source": [ + "## ELU function\n", + "\n", + "To solve this problem, nowadays practitioners use a variant of the\n", + "ReLU function, such as the leaky ReLU discussed above or the so-called\n", + "exponential linear unit (ELU) function" + ] + }, + { + "cell_type": "markdown", + "id": "6d2d4dcc", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "ELU(z) = \\left\\{\\begin{array}{cc} \\alpha\\left( \\exp{(z)}-1\\right) & z < 0,\\\\ z & z \\ge 0.\\end{array}\\right.\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "e17fbd6e", + "metadata": { + "editable": true + }, + "source": [ + "## Which activation function should we use?\n", + "\n", + "In general it seems that the ELU activation function is better than\n", + "the leaky ReLU function (and its variants), which is better than\n", + "ReLU. ReLU performs better than $\\tanh$ which in turn performs better\n", + "than the logistic function.\n", + "\n", + "If runtime performance is an issue, then you may opt for the leaky\n", + "ReLU function over the ELU function If you don’t want to tweak yet\n", + "another hyperparameter, you may just use the default $\\alpha$ of\n", + "$0.01$ for the leaky ReLU, and $1$ for ELU. If you have spare time and\n", + "computing power, you can use cross-validation or bootstrap to evaluate\n", + "other activation functions." + ] + }, + { + "cell_type": "markdown", + "id": "4464d159", + "metadata": { + "editable": true + }, + "source": [ + "## More on activation functions, output layers\n", + "\n", + "In most cases you can use the ReLU activation function in the hidden\n", + "layers (or one of its variants).\n", + "\n", + "It is a bit faster to compute than other activation functions, and the\n", + "gradient descent optimization does in general not get stuck.\n", + "\n", + "**For the output layer:**\n", + "\n", + "* For classification the softmax activation function is generally a good choice for classification tasks (when the classes are mutually exclusive).\n", + "\n", + "* For regression tasks, you can simply use no activation function at all." + ] + }, + { + "cell_type": "markdown", + "id": "d7dacac8", + "metadata": { + "editable": true + }, + "source": [ + "## Building neural networks in Tensorflow and Keras\n", + "\n", + "Now we want to build on the experience gained from our neural network implementation in NumPy and scikit-learn\n", + "and use it to construct a neural network in Tensorflow. Once we have constructed a neural network in NumPy\n", + "and Tensorflow, building one in Keras is really quite trivial, though the performance may suffer. \n", + "\n", + "In our previous example we used only one hidden layer, and in this we will use two. From this it should be quite\n", + "clear how to build one using an arbitrary number of hidden layers, using data structures such as Python lists or\n", + "NumPy arrays." + ] + }, + { + "cell_type": "markdown", + "id": "cb79f5a6", + "metadata": { + "editable": true + }, + "source": [ + "## Tensorflow\n", + "\n", + "Tensorflow is an open source library machine learning library\n", + "developed by the Google Brain team for internal use. It was released\n", + "under the Apache 2.0 open source license in November 9, 2015.\n", + "\n", + "Tensorflow is a computational framework that allows you to construct\n", + "machine learning models at different levels of abstraction, from\n", + "high-level, object-oriented APIs like Keras, down to the C++ kernels\n", + "that Tensorflow is built upon. The higher levels of abstraction are\n", + "simpler to use, but less flexible, and our choice of implementation\n", + "should reflect the problems we are trying to solve.\n", + "\n", + "[Tensorflow uses](https://www.tensorflow.org/guide/graphs) so-called graphs to represent your computation\n", + "in terms of the dependencies between individual operations, such that you first build a Tensorflow *graph*\n", + "to represent your model, and then create a Tensorflow *session* to run the graph.\n", + "\n", + "In this guide we will analyze the same data as we did in our NumPy and\n", + "scikit-learn tutorial, gathered from the MNIST database of images. We\n", + "will give an introduction to the lower level Python Application\n", + "Program Interfaces (APIs), and see how we use them to build our graph.\n", + "Then we will build (effectively) the same graph in Keras, to see just\n", + "how simple solving a machine learning problem can be.\n", + "\n", + "To install tensorflow on Unix/Linux systems, use pip as" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "44cf829e", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "pip3 install tensorflow" + ] + }, + { + "cell_type": "markdown", + "id": "bdf6f4be", + "metadata": { + "editable": true + }, + "source": [ + "and/or if you use **anaconda**, just write (or install from the graphical user interface)\n", + "(current release of CPU-only TensorFlow)" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "784ed3b7", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "conda create -n tf tensorflow\n", + "conda activate tf" + ] + }, + { + "cell_type": "markdown", + "id": "30a63e04", + "metadata": { + "editable": true + }, + "source": [ + "To install the current release of GPU TensorFlow" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "5ecbf45a", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "conda create -n tf-gpu tensorflow-gpu\n", + "conda activate tf-gpu" + ] + }, + { + "cell_type": "markdown", + "id": "4a0568e9", + "metadata": { + "editable": true + }, + "source": [ + "## Using Keras\n", + "\n", + "Keras is a high level [neural network](https://en.wikipedia.org/wiki/Application_programming_interface)\n", + "that supports Tensorflow, CTNK and Theano as backends. \n", + "If you have Anaconda installed you may run the following command" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "9982df74", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "conda install keras" + ] + }, + { + "cell_type": "markdown", + "id": "b81f34fd", + "metadata": { + "editable": true + }, + "source": [ + "You can look up the [instructions here](https://keras.io/) for more information.\n", + "\n", + "We will to a large extent use **keras** in this course." + ] + }, + { + "cell_type": "markdown", + "id": "cf68391d", + "metadata": { + "editable": true + }, + "source": [ + "## Collect and pre-process data\n", + "\n", + "Let us look again at the MINST data set." + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "2594d47b", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "%matplotlib inline\n", + "\n", + "# import necessary packages\n", + "import numpy as np\n", + "import matplotlib.pyplot as plt\n", + "import tensorflow as tf\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", + "print(\"inputs = (n_inputs, pixel_width, pixel_height) = \" + str(inputs.shape))\n", + "print(\"labels = (n_inputs) = \" + str(labels.shape))\n", + "\n", + "\n", + "# flatten the image\n", + "# the value -1 means dimension is inferred from the remaining dimensions: 8x8 = 64\n", + "n_inputs = len(inputs)\n", + "inputs = inputs.reshape(n_inputs, -1)\n", + "print(\"X = (n_inputs, n_features) = \" + str(inputs.shape))\n", + "\n", + "\n", + "# choose some random images to display\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": 6, + "id": "060f0b22", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "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", + "\n", + "from sklearn.model_selection import train_test_split\n", + "\n", + "# one-hot representation of labels\n", + "labels = to_categorical(labels)\n", + "\n", + "# split into train and test data\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": 7, + "id": "5491ac4f", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "\n", + "epochs = 100\n", + "batch_size = 100\n", + "n_neurons_layer1 = 100\n", + "n_neurons_layer2 = 50\n", + "n_categories = 10\n", + "eta_vals = np.logspace(-5, 1, 7)\n", + "lmbd_vals = np.logspace(-5, 1, 7)\n", + "def create_neural_network_keras(n_neurons_layer1, n_neurons_layer2, n_categories, eta, lmbd):\n", + " model = Sequential()\n", + " model.add(Dense(n_neurons_layer1, activation='sigmoid', kernel_regularizer=regularizers.l2(lmbd)))\n", + " model.add(Dense(n_neurons_layer2, activation='sigmoid', kernel_regularizer=regularizers.l2(lmbd)))\n", + " model.add(Dense(n_categories, activation='softmax'))\n", + " \n", + " sgd = optimizers.SGD(learning_rate=eta)\n", + " model.compile(loss='categorical_crossentropy', optimizer=sgd, metrics=['accuracy'])\n", + " \n", + " return model" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "id": "905a1d27", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "DNN_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", + " DNN = create_neural_network_keras(n_neurons_layer1, n_neurons_layer2, n_categories,\n", + " eta=eta, lmbd=lmbd)\n", + " DNN.fit(X_train, Y_train, epochs=epochs, batch_size=batch_size, verbose=0)\n", + " scores = DNN.evaluate(X_test, Y_test)\n", + " \n", + " DNN_keras[i][j] = DNN\n", + " \n", + " print(\"Learning rate = \", eta)\n", + " print(\"Lambda = \", lmbd)\n", + " print(\"Test accuracy: %.3f\" % scores[1])\n", + " print()" + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "id": "491849b6", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "# optional\n", + "# 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", + " DNN = DNN_keras[i][j]\n", + "\n", + " train_accuracy[i][j] = DNN.evaluate(X_train, Y_train)[1]\n", + " test_accuracy[i][j] = DNN.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": "25bfc059", + "metadata": { + "editable": true + }, + "source": [ + "## Using Pytorch with the full MNIST data set" + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "id": "29c660b4", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "import torch\n", + "import torch.nn as nn\n", + "import torch.optim as optim\n", + "import torchvision\n", + "import torchvision.transforms as transforms\n", + "\n", + "# Device configuration: use GPU if available\n", + "device = torch.device(\"cuda\" if torch.cuda.is_available() else \"cpu\")\n", + "\n", + "# MNIST dataset (downloads if not already present)\n", + "transform = transforms.Compose([\n", + " transforms.ToTensor(),\n", + " transforms.Normalize((0.5,), (0.5,)) # normalize to mean=0.5, std=0.5 (approx. [-1,1] pixel range)\n", + "])\n", + "train_dataset = torchvision.datasets.MNIST(root='./data', train=True, download=True, transform=transform)\n", + "test_dataset = torchvision.datasets.MNIST(root='./data', train=False, download=True, transform=transform)\n", + "\n", + "train_loader = torch.utils.data.DataLoader(train_dataset, batch_size=64, shuffle=True)\n", + "test_loader = torch.utils.data.DataLoader(test_dataset, batch_size=64, shuffle=False)\n", + "\n", + "\n", + "class NeuralNet(nn.Module):\n", + " def __init__(self):\n", + " super(NeuralNet, self).__init__()\n", + " self.fc1 = nn.Linear(28*28, 100) # first hidden layer (784 -> 100)\n", + " self.fc2 = nn.Linear(100, 100) # second hidden layer (100 -> 100)\n", + " self.fc3 = nn.Linear(100, 10) # output layer (100 -> 10 classes)\n", + " def forward(self, x):\n", + " x = x.view(x.size(0), -1) # flatten images into vectors of size 784\n", + " x = torch.relu(self.fc1(x)) # hidden layer 1 + ReLU activation\n", + " x = torch.relu(self.fc2(x)) # hidden layer 2 + ReLU activation\n", + " x = self.fc3(x) # output layer (logits for 10 classes)\n", + " return x\n", + "\n", + "model = NeuralNet().to(device)\n", + "\n", + "\n", + "criterion = nn.CrossEntropyLoss()\n", + "optimizer = optim.SGD(model.parameters(), lr=0.01, weight_decay=1e-4)\n", + "\n", + "num_epochs = 10\n", + "for epoch in range(num_epochs):\n", + " model.train() # set model to training mode\n", + " running_loss = 0.0\n", + " for images, labels in train_loader:\n", + " # Move data to device (GPU if available, else CPU)\n", + " images, labels = images.to(device), labels.to(device)\n", + "\n", + " optimizer.zero_grad() # reset gradients to zero\n", + " outputs = model(images) # forward pass: compute predictions\n", + " loss = criterion(outputs, labels) # compute cross-entropy loss\n", + " loss.backward() # backpropagate to compute gradients\n", + " optimizer.step() # update weights using SGD step \n", + "\n", + " running_loss += loss.item()\n", + " # Compute average loss over all batches in this epoch\n", + " avg_loss = running_loss / len(train_loader)\n", + " print(f\"Epoch {epoch+1}/{num_epochs}, Loss: {avg_loss:.4f}\")\n", + "\n", + "#Evaluation on the Test Set\n", + "\n", + "\n", + "\n", + "model.eval() # set model to evaluation mode \n", + "correct = 0\n", + "total = 0\n", + "with torch.no_grad(): # disable gradient calculation for evaluation \n", + " for images, labels in test_loader:\n", + " images, labels = images.to(device), labels.to(device)\n", + " outputs = model(images)\n", + " _, predicted = torch.max(outputs, dim=1) # class with highest score\n", + " total += labels.size(0)\n", + " correct += (predicted == labels).sum().item()\n", + "\n", + "accuracy = 100 * correct / total\n", + "print(f\"Test Accuracy: {accuracy:.2f}%\")" + ] + }, + { + "cell_type": "markdown", + "id": "50468253", + "metadata": { + "editable": true + }, + "source": [ + "## And a similar example using Tensorflow with Keras" + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "id": "1e430607", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "\n", + "import tensorflow as tf\n", + "from tensorflow import keras\n", + "from tensorflow.keras import layers, regularizers\n", + "\n", + "# Check for GPU (TensorFlow will use it automatically if available)\n", + "gpus = tf.config.list_physical_devices('GPU')\n", + "print(f\"GPUs available: {gpus}\")\n", + "\n", + "# 1) Load and preprocess MNIST\n", + "(x_train, y_train), (x_test, y_test) = keras.datasets.mnist.load_data()\n", + "# Normalize to [0, 1]\n", + "x_train = (x_train.astype(\"float32\") / 255.0)\n", + "x_test = (x_test.astype(\"float32\") / 255.0)\n", + "\n", + "# 2) Build the model: 784 -> 100 -> 100 -> 10\n", + "l2_reg = 1e-4 # L2 regularization strength\n", + "\n", + "model = keras.Sequential([\n", + " layers.Input(shape=(28, 28)),\n", + " layers.Flatten(),\n", + " layers.Dense(100, activation=\"relu\",\n", + " kernel_regularizer=regularizers.l2(l2_reg)),\n", + " layers.Dense(100, activation=\"relu\",\n", + " kernel_regularizer=regularizers.l2(l2_reg)),\n", + " layers.Dense(10, activation=\"softmax\") # output probabilities for 10 classes\n", + "])\n", + "\n", + "# 3) Compile with SGD + weight decay via L2 regularizers\n", + "model.compile(\n", + " optimizer=keras.optimizers.SGD(learning_rate=0.01),\n", + " loss=\"sparse_categorical_crossentropy\",\n", + " metrics=[\"accuracy\"],\n", + ")\n", + "\n", + "model.summary()\n", + "\n", + "# 4) Train\n", + "history = model.fit(\n", + " x_train, y_train,\n", + " epochs=10,\n", + " batch_size=64,\n", + " validation_split=0.1, # optional: monitor validation during training\n", + " verbose=1\n", + ")\n", + "\n", + "# 5) Evaluate on test set\n", + "test_loss, test_acc = model.evaluate(x_test, y_test, verbose=0)\n", + "print(f\"Test accuracy: {test_acc:.4f}, Test loss: {test_loss:.4f}\")" + ] + }, + { + "cell_type": "markdown", + "id": "44c02ba1", + "metadata": { + "editable": true + }, + "source": [ + "## Building our own neural network code\n", + "\n", + "Here we present a flexible object oriented codebase\n", + "for a feed forward neural network, along with a demonstration of how\n", + "to use it. Before we get into the details of the neural network, we\n", + "will first present some implementations of various schedulers, cost\n", + "functions and activation functions that can be used together with the\n", + "neural network.\n", + "\n", + "The codes here were developed by Eric Reber and Gregor Kajda during spring 2023." + ] + }, + { + "cell_type": "markdown", + "id": "87c53214", + "metadata": { + "editable": true + }, + "source": [ + "### Learning rate methods\n", + "\n", + "The code below shows object oriented implementations of the Constant,\n", + "Momentum, Adagrad, AdagradMomentum, RMS prop and Adam schedulers. All\n", + "of the classes belong to the shared abstract Scheduler class, and\n", + "share the update_change() and reset() methods allowing for any of the\n", + "schedulers to be seamlessly used during the training stage, as will\n", + "later be shown in the fit() method of the neural\n", + "network. Update_change() only has one parameter, the gradient\n", + "($δ^l_ja^{l−1}_k$), and returns the change which will be subtracted\n", + "from the weights. The reset() function takes no parameters, and resets\n", + "the desired variables. For Constant and Momentum, reset does nothing." + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "id": "b36b4c64", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "import autograd.numpy as np\n", + "\n", + "class Scheduler:\n", + " \"\"\"\n", + " Abstract class for Schedulers\n", + " \"\"\"\n", + "\n", + " def __init__(self, eta):\n", + " self.eta = eta\n", + "\n", + " # should be overwritten\n", + " def update_change(self, gradient):\n", + " raise NotImplementedError\n", + "\n", + " # overwritten if needed\n", + " def reset(self):\n", + " pass\n", + "\n", + "\n", + "class Constant(Scheduler):\n", + " def __init__(self, eta):\n", + " super().__init__(eta)\n", + "\n", + " def update_change(self, gradient):\n", + " return self.eta * gradient\n", + " \n", + " def reset(self):\n", + " pass\n", + "\n", + "\n", + "class Momentum(Scheduler):\n", + " def __init__(self, eta: float, momentum: float):\n", + " super().__init__(eta)\n", + " self.momentum = momentum\n", + " self.change = 0\n", + "\n", + " def update_change(self, gradient):\n", + " self.change = self.momentum * self.change + self.eta * gradient\n", + " return self.change\n", + "\n", + " def reset(self):\n", + " pass\n", + "\n", + "\n", + "class Adagrad(Scheduler):\n", + " def __init__(self, eta):\n", + " super().__init__(eta)\n", + " self.G_t = None\n", + "\n", + " def update_change(self, gradient):\n", + " delta = 1e-8 # avoid division ny zero\n", + "\n", + " if self.G_t is None:\n", + " self.G_t = np.zeros((gradient.shape[0], gradient.shape[0]))\n", + "\n", + " self.G_t += gradient @ gradient.T\n", + "\n", + " G_t_inverse = 1 / (\n", + " delta + np.sqrt(np.reshape(np.diagonal(self.G_t), (self.G_t.shape[0], 1)))\n", + " )\n", + " return self.eta * gradient * G_t_inverse\n", + "\n", + " def reset(self):\n", + " self.G_t = None\n", + "\n", + "\n", + "class AdagradMomentum(Scheduler):\n", + " def __init__(self, eta, momentum):\n", + " super().__init__(eta)\n", + " self.G_t = None\n", + " self.momentum = momentum\n", + " self.change = 0\n", + "\n", + " def update_change(self, gradient):\n", + " delta = 1e-8 # avoid division ny zero\n", + "\n", + " if self.G_t is None:\n", + " self.G_t = np.zeros((gradient.shape[0], gradient.shape[0]))\n", + "\n", + " self.G_t += gradient @ gradient.T\n", + "\n", + " G_t_inverse = 1 / (\n", + " delta + np.sqrt(np.reshape(np.diagonal(self.G_t), (self.G_t.shape[0], 1)))\n", + " )\n", + " self.change = self.change * self.momentum + self.eta * gradient * G_t_inverse\n", + " return self.change\n", + "\n", + " def reset(self):\n", + " self.G_t = None\n", + "\n", + "\n", + "class RMS_prop(Scheduler):\n", + " def __init__(self, eta, rho):\n", + " super().__init__(eta)\n", + " self.rho = rho\n", + " self.second = 0.0\n", + "\n", + " def update_change(self, gradient):\n", + " delta = 1e-8 # avoid division ny zero\n", + " self.second = self.rho * self.second + (1 - self.rho) * gradient * gradient\n", + " return self.eta * gradient / (np.sqrt(self.second + delta))\n", + "\n", + " def reset(self):\n", + " self.second = 0.0\n", + "\n", + "\n", + "class Adam(Scheduler):\n", + " def __init__(self, eta, rho, rho2):\n", + " super().__init__(eta)\n", + " self.rho = rho\n", + " self.rho2 = rho2\n", + " self.moment = 0\n", + " self.second = 0\n", + " self.n_epochs = 1\n", + "\n", + " def update_change(self, gradient):\n", + " delta = 1e-8 # avoid division ny zero\n", + "\n", + " self.moment = self.rho * self.moment + (1 - self.rho) * gradient\n", + " self.second = self.rho2 * self.second + (1 - self.rho2) * gradient * gradient\n", + "\n", + " moment_corrected = self.moment / (1 - self.rho**self.n_epochs)\n", + " second_corrected = self.second / (1 - self.rho2**self.n_epochs)\n", + "\n", + " return self.eta * moment_corrected / (np.sqrt(second_corrected + delta))\n", + "\n", + " def reset(self):\n", + " self.n_epochs += 1\n", + " self.moment = 0\n", + " self.second = 0" + ] + }, + { + "cell_type": "markdown", + "id": "166220ac", + "metadata": { + "editable": true + }, + "source": [ + "### Usage of the above learning rate schedulers\n", + "\n", + "To initalize a scheduler, simply create the object and pass in the\n", + "necessary parameters such as the learning rate and the momentum as\n", + "shown below. As the Scheduler class is an abstract class it should not\n", + "called directly, and will raise an error upon usage." + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "id": "6e3221f8", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "momentum_scheduler = Momentum(eta=1e-3, momentum=0.9)\n", + "adam_scheduler = Adam(eta=1e-3, rho=0.9, rho2=0.999)" + ] + }, + { + "cell_type": "markdown", + "id": "44e094bb", + "metadata": { + "editable": true + }, + "source": [ + "Here is a small example for how a segment of code using schedulers\n", + "could look. Switching out the schedulers is simple." + ] + }, + { + "cell_type": "code", + "execution_count": 14, + "id": "e8e938bd", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "weights = np.ones((3,3))\n", + "print(f\"Before scheduler:\\n{weights=}\")\n", + "\n", + "epochs = 10\n", + "for e in range(epochs):\n", + " gradient = np.random.rand(3, 3)\n", + " change = adam_scheduler.update_change(gradient)\n", + " weights = weights - change\n", + " adam_scheduler.reset()\n", + "\n", + "print(f\"\\nAfter scheduler:\\n{weights=}\")" + ] + }, + { + "cell_type": "markdown", + "id": "7546f778", + "metadata": { + "editable": true + }, + "source": [ + "### Cost functions\n", + "\n", + "Here we discuss cost functions that can be used when creating the\n", + "neural network. Every cost function takes the target vector as its\n", + "parameter, and returns a function valued only at $x$ such that it may\n", + "easily be differentiated." + ] + }, + { + "cell_type": "code", + "execution_count": 15, + "id": "55250ea2", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "import autograd.numpy as np\n", + "\n", + "def CostOLS(target):\n", + " \n", + " def func(X):\n", + " return (1.0 / target.shape[0]) * np.sum((target - X) ** 2)\n", + "\n", + " return func\n", + "\n", + "\n", + "def CostLogReg(target):\n", + "\n", + " def func(X):\n", + " \n", + " return -(1.0 / target.shape[0]) * np.sum(\n", + " (target * np.log(X + 10e-10)) + ((1 - target) * np.log(1 - X + 10e-10))\n", + " )\n", + "\n", + " return func\n", + "\n", + "\n", + "def CostCrossEntropy(target):\n", + " \n", + " def func(X):\n", + " return -(1.0 / target.size) * np.sum(target * np.log(X + 10e-10))\n", + "\n", + " return func" + ] + }, + { + "cell_type": "markdown", + "id": "6651b1cc", + "metadata": { + "editable": true + }, + "source": [ + "Below we give a short example of how these cost function may be used\n", + "to obtain results if you wish to test them out on your own using\n", + "AutoGrad's automatics differentiation." + ] + }, + { + "cell_type": "code", + "execution_count": 16, + "id": "48d70de6", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "from autograd import grad\n", + "\n", + "target = np.array([[1, 2, 3]]).T\n", + "a = np.array([[4, 5, 6]]).T\n", + "\n", + "cost_func = CostCrossEntropy\n", + "cost_func_derivative = grad(cost_func(target))\n", + "\n", + "valued_at_a = cost_func_derivative(a)\n", + "print(f\"Derivative of cost function {cost_func.__name__} valued at a:\\n{valued_at_a}\")" + ] + }, + { + "cell_type": "markdown", + "id": "1763139f", + "metadata": { + "editable": true + }, + "source": [ + "### Activation functions\n", + "\n", + "Finally, before we look at the neural network, we will look at the\n", + "activation functions which can be specified between the hidden layers\n", + "and as the output function. Each function can be valued for any given\n", + "vector or matrix X, and can be differentiated via derivate()." + ] + }, + { + "cell_type": "code", + "execution_count": 17, + "id": "2cf6bda9", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "import autograd.numpy as np\n", + "from autograd import elementwise_grad\n", + "\n", + "def identity(X):\n", + " return X\n", + "\n", + "\n", + "def sigmoid(X):\n", + " try:\n", + " return 1.0 / (1 + np.exp(-X))\n", + " except FloatingPointError:\n", + " return np.where(X > np.zeros(X.shape), np.ones(X.shape), np.zeros(X.shape))\n", + "\n", + "\n", + "def softmax(X):\n", + " X = X - np.max(X, axis=-1, keepdims=True)\n", + " delta = 10e-10\n", + " return np.exp(X) / (np.sum(np.exp(X), axis=-1, keepdims=True) + delta)\n", + "\n", + "\n", + "def RELU(X):\n", + " return np.where(X > np.zeros(X.shape), X, np.zeros(X.shape))\n", + "\n", + "\n", + "def LRELU(X):\n", + " delta = 10e-4\n", + " return np.where(X > np.zeros(X.shape), X, delta * X)\n", + "\n", + "\n", + "def derivate(func):\n", + " if func.__name__ == \"RELU\":\n", + "\n", + " def func(X):\n", + " return np.where(X > 0, 1, 0)\n", + "\n", + " return func\n", + "\n", + " elif func.__name__ == \"LRELU\":\n", + "\n", + " def func(X):\n", + " delta = 10e-4\n", + " return np.where(X > 0, 1, delta)\n", + "\n", + " return func\n", + "\n", + " else:\n", + " return elementwise_grad(func)" + ] + }, + { + "cell_type": "markdown", + "id": "9e48a5a2", + "metadata": { + "editable": true + }, + "source": [ + "Below follows a short demonstration of how to use an activation\n", + "function. The derivative of the activation function will be important\n", + "when calculating the output delta term during backpropagation. Note\n", + "that derivate() can also be used for cost functions for a more\n", + "generalized approach." + ] + }, + { + "cell_type": "code", + "execution_count": 18, + "id": "12995853", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "z = np.array([[4, 5, 6]]).T\n", + "print(f\"Input to activation function:\\n{z}\")\n", + "\n", + "act_func = sigmoid\n", + "a = act_func(z)\n", + "print(f\"\\nOutput from {act_func.__name__} activation function:\\n{a}\")\n", + "\n", + "act_func_derivative = derivate(act_func)\n", + "valued_at_z = act_func_derivative(a)\n", + "print(f\"\\nDerivative of {act_func.__name__} activation function valued at z:\\n{valued_at_z}\")" + ] + }, + { + "cell_type": "markdown", + "id": "63d3c5bd", + "metadata": { + "editable": true + }, + "source": [ + "### The Neural Network\n", + "\n", + "Now that we have gotten a good understanding of the implementation of\n", + "some important components, we can take a look at an object oriented\n", + "implementation of a feed forward neural network. The feed forward\n", + "neural network has been implemented as a class named FFNN, which can\n", + "be initiated as a regressor or classifier dependant on the choice of\n", + "cost function. The FFNN can have any number of input nodes, hidden\n", + "layers with any amount of hidden nodes, and any amount of output nodes\n", + "meaning it can perform multiclass classification as well as binary\n", + "classification and regression problems. Although there is a lot of\n", + "code present, it makes for an easy to use and generalizeable interface\n", + "for creating many types of neural networks as will be demonstrated\n", + "below." + ] + }, + { + "cell_type": "code", + "execution_count": 19, + "id": "7e0107d8", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "import math\n", + "import autograd.numpy as np\n", + "import sys\n", + "import warnings\n", + "from autograd import grad, elementwise_grad\n", + "from random import random, seed\n", + "from copy import deepcopy, copy\n", + "from typing import Tuple, Callable\n", + "from sklearn.utils import resample\n", + "\n", + "warnings.simplefilter(\"error\")\n", + "\n", + "\n", + "class FFNN:\n", + " \"\"\"\n", + " Description:\n", + " ------------\n", + " Feed Forward Neural Network with interface enabling flexible design of a\n", + " nerual networks architecture and the specification of activation function\n", + " in the hidden layers and output layer respectively. This model can be used\n", + " for both regression and classification problems, depending on the output function.\n", + "\n", + " Attributes:\n", + " ------------\n", + " I dimensions (tuple[int]): A list of positive integers, which specifies the\n", + " number of nodes in each of the networks layers. The first integer in the array\n", + " defines the number of nodes in the input layer, the second integer defines number\n", + " of nodes in the first hidden layer and so on until the last number, which\n", + " specifies the number of nodes in the output layer.\n", + " II hidden_func (Callable): The activation function for the hidden layers\n", + " III output_func (Callable): The activation function for the output layer\n", + " IV cost_func (Callable): Our cost function\n", + " V seed (int): Sets random seed, makes results reproducible\n", + " \"\"\"\n", + "\n", + " def __init__(\n", + " self,\n", + " dimensions: tuple[int],\n", + " hidden_func: Callable = sigmoid,\n", + " output_func: Callable = lambda x: x,\n", + " cost_func: Callable = CostOLS,\n", + " seed: int = None,\n", + " ):\n", + " self.dimensions = dimensions\n", + " self.hidden_func = hidden_func\n", + " self.output_func = output_func\n", + " self.cost_func = cost_func\n", + " self.seed = seed\n", + " self.weights = list()\n", + " self.schedulers_weight = list()\n", + " self.schedulers_bias = list()\n", + " self.a_matrices = list()\n", + " self.z_matrices = list()\n", + " self.classification = None\n", + "\n", + " self.reset_weights()\n", + " self._set_classification()\n", + "\n", + " def fit(\n", + " self,\n", + " X: np.ndarray,\n", + " t: np.ndarray,\n", + " scheduler: Scheduler,\n", + " batches: int = 1,\n", + " epochs: int = 100,\n", + " lam: float = 0,\n", + " X_val: np.ndarray = None,\n", + " t_val: np.ndarray = None,\n", + " ):\n", + " \"\"\"\n", + " Description:\n", + " ------------\n", + " This function performs the training the neural network by performing the feedforward and backpropagation\n", + " algorithm to update the networks weights.\n", + "\n", + " Parameters:\n", + " ------------\n", + " I X (np.ndarray) : training data\n", + " II t (np.ndarray) : target data\n", + " III scheduler (Scheduler) : specified scheduler (algorithm for optimization of gradient descent)\n", + " IV scheduler_args (list[int]) : list of all arguments necessary for scheduler\n", + "\n", + " Optional Parameters:\n", + " ------------\n", + " V batches (int) : number of batches the datasets are split into, default equal to 1\n", + " VI epochs (int) : number of iterations used to train the network, default equal to 100\n", + " VII lam (float) : regularization hyperparameter lambda\n", + " VIII X_val (np.ndarray) : validation set\n", + " IX t_val (np.ndarray) : validation target set\n", + "\n", + " Returns:\n", + " ------------\n", + " I scores (dict) : A dictionary containing the performance metrics of the model.\n", + " The number of the metrics depends on the parameters passed to the fit-function.\n", + "\n", + " \"\"\"\n", + "\n", + " # setup \n", + " if self.seed is not None:\n", + " np.random.seed(self.seed)\n", + "\n", + " val_set = False\n", + " if X_val is not None and t_val is not None:\n", + " val_set = True\n", + "\n", + " # creating arrays for score metrics\n", + " train_errors = np.empty(epochs)\n", + " train_errors.fill(np.nan)\n", + " val_errors = np.empty(epochs)\n", + " val_errors.fill(np.nan)\n", + "\n", + " train_accs = np.empty(epochs)\n", + " train_accs.fill(np.nan)\n", + " val_accs = np.empty(epochs)\n", + " val_accs.fill(np.nan)\n", + "\n", + " self.schedulers_weight = list()\n", + " self.schedulers_bias = list()\n", + "\n", + " batch_size = X.shape[0] // batches\n", + "\n", + " X, t = resample(X, t)\n", + "\n", + " # this function returns a function valued only at X\n", + " cost_function_train = self.cost_func(t)\n", + " if val_set:\n", + " cost_function_val = self.cost_func(t_val)\n", + "\n", + " # create schedulers for each weight matrix\n", + " for i in range(len(self.weights)):\n", + " self.schedulers_weight.append(copy(scheduler))\n", + " self.schedulers_bias.append(copy(scheduler))\n", + "\n", + " print(f\"{scheduler.__class__.__name__}: Eta={scheduler.eta}, Lambda={lam}\")\n", + "\n", + " try:\n", + " for e in range(epochs):\n", + " for i in range(batches):\n", + " # allows for minibatch gradient descent\n", + " if i == batches - 1:\n", + " # If the for loop has reached the last batch, take all thats left\n", + " X_batch = X[i * batch_size :, :]\n", + " t_batch = t[i * batch_size :, :]\n", + " else:\n", + " X_batch = X[i * batch_size : (i + 1) * batch_size, :]\n", + " t_batch = t[i * batch_size : (i + 1) * batch_size, :]\n", + "\n", + " self._feedforward(X_batch)\n", + " self._backpropagate(X_batch, t_batch, lam)\n", + "\n", + " # reset schedulers for each epoch (some schedulers pass in this call)\n", + " for scheduler in self.schedulers_weight:\n", + " scheduler.reset()\n", + "\n", + " for scheduler in self.schedulers_bias:\n", + " scheduler.reset()\n", + "\n", + " # computing performance metrics\n", + " pred_train = self.predict(X)\n", + " train_error = cost_function_train(pred_train)\n", + "\n", + " train_errors[e] = train_error\n", + " if val_set:\n", + " \n", + " pred_val = self.predict(X_val)\n", + " val_error = cost_function_val(pred_val)\n", + " val_errors[e] = val_error\n", + "\n", + " if self.classification:\n", + " train_acc = self._accuracy(self.predict(X), t)\n", + " train_accs[e] = train_acc\n", + " if val_set:\n", + " val_acc = self._accuracy(pred_val, t_val)\n", + " val_accs[e] = val_acc\n", + "\n", + " # printing progress bar\n", + " progression = e / epochs\n", + " print_length = self._progress_bar(\n", + " progression,\n", + " train_error=train_errors[e],\n", + " train_acc=train_accs[e],\n", + " val_error=val_errors[e],\n", + " val_acc=val_accs[e],\n", + " )\n", + " except KeyboardInterrupt:\n", + " # allows for stopping training at any point and seeing the result\n", + " pass\n", + "\n", + " # visualization of training progression (similiar to tensorflow progression bar)\n", + " sys.stdout.write(\"\\r\" + \" \" * print_length)\n", + " sys.stdout.flush()\n", + " self._progress_bar(\n", + " 1,\n", + " train_error=train_errors[e],\n", + " train_acc=train_accs[e],\n", + " val_error=val_errors[e],\n", + " val_acc=val_accs[e],\n", + " )\n", + " sys.stdout.write(\"\")\n", + "\n", + " # return performance metrics for the entire run\n", + " scores = dict()\n", + "\n", + " scores[\"train_errors\"] = train_errors\n", + "\n", + " if val_set:\n", + " scores[\"val_errors\"] = val_errors\n", + "\n", + " if self.classification:\n", + " scores[\"train_accs\"] = train_accs\n", + "\n", + " if val_set:\n", + " scores[\"val_accs\"] = val_accs\n", + "\n", + " return scores\n", + "\n", + " def predict(self, X: np.ndarray, *, threshold=0.5):\n", + " \"\"\"\n", + " Description:\n", + " ------------\n", + " Performs prediction after training of the network has been finished.\n", + "\n", + " Parameters:\n", + " ------------\n", + " I X (np.ndarray): The design matrix, with n rows of p features each\n", + "\n", + " Optional Parameters:\n", + " ------------\n", + " II threshold (float) : sets minimal value for a prediction to be predicted as the positive class\n", + " in classification problems\n", + "\n", + " Returns:\n", + " ------------\n", + " I z (np.ndarray): A prediction vector (row) for each row in our design matrix\n", + " This vector is thresholded if regression=False, meaning that classification results\n", + " in a vector of 1s and 0s, while regressions in an array of decimal numbers\n", + "\n", + " \"\"\"\n", + "\n", + " predict = self._feedforward(X)\n", + "\n", + " if self.classification:\n", + " return np.where(predict > threshold, 1, 0)\n", + " else:\n", + " return predict\n", + "\n", + " def reset_weights(self):\n", + " \"\"\"\n", + " Description:\n", + " ------------\n", + " Resets/Reinitializes the weights in order to train the network for a new problem.\n", + "\n", + " \"\"\"\n", + " if self.seed is not None:\n", + " np.random.seed(self.seed)\n", + "\n", + " self.weights = list()\n", + " for i in range(len(self.dimensions) - 1):\n", + " weight_array = np.random.randn(\n", + " self.dimensions[i] + 1, self.dimensions[i + 1]\n", + " )\n", + " weight_array[0, :] = np.random.randn(self.dimensions[i + 1]) * 0.01\n", + "\n", + " self.weights.append(weight_array)\n", + "\n", + " def _feedforward(self, X: np.ndarray):\n", + " \"\"\"\n", + " Description:\n", + " ------------\n", + " Calculates the activation of each layer starting at the input and ending at the output.\n", + " Each following activation is calculated from a weighted sum of each of the preceeding\n", + " activations (except in the case of the input layer).\n", + "\n", + " Parameters:\n", + " ------------\n", + " I X (np.ndarray): The design matrix, with n rows of p features each\n", + "\n", + " Returns:\n", + " ------------\n", + " I z (np.ndarray): A prediction vector (row) for each row in our design matrix\n", + " \"\"\"\n", + "\n", + " # reset matrices\n", + " self.a_matrices = list()\n", + " self.z_matrices = list()\n", + "\n", + " # if X is just a vector, make it into a matrix\n", + " if len(X.shape) == 1:\n", + " X = X.reshape((1, X.shape[0]))\n", + "\n", + " # Add a coloumn of zeros as the first coloumn of the design matrix, in order\n", + " # to add bias to our data\n", + " bias = np.ones((X.shape[0], 1)) * 0.01\n", + " X = np.hstack([bias, X])\n", + "\n", + " # a^0, the nodes in the input layer (one a^0 for each row in X - where the\n", + " # exponent indicates layer number).\n", + " a = X\n", + " self.a_matrices.append(a)\n", + " self.z_matrices.append(a)\n", + "\n", + " # The feed forward algorithm\n", + " for i in range(len(self.weights)):\n", + " if i < len(self.weights) - 1:\n", + " z = a @ self.weights[i]\n", + " self.z_matrices.append(z)\n", + " a = self.hidden_func(z)\n", + " # bias column again added to the data here\n", + " bias = np.ones((a.shape[0], 1)) * 0.01\n", + " a = np.hstack([bias, a])\n", + " self.a_matrices.append(a)\n", + " else:\n", + " try:\n", + " # a^L, the nodes in our output layers\n", + " z = a @ self.weights[i]\n", + " a = self.output_func(z)\n", + " self.a_matrices.append(a)\n", + " self.z_matrices.append(z)\n", + " except Exception as OverflowError:\n", + " print(\n", + " \"OverflowError in fit() in FFNN\\nHOW TO DEBUG ERROR: Consider lowering your learning rate or scheduler specific parameters such as momentum, or check if your input values need scaling\"\n", + " )\n", + "\n", + " # this will be a^L\n", + " return a\n", + "\n", + " def _backpropagate(self, X, t, lam):\n", + " \"\"\"\n", + " Description:\n", + " ------------\n", + " Performs the backpropagation algorithm. In other words, this method\n", + " calculates the gradient of all the layers starting at the\n", + " output layer, and moving from right to left accumulates the gradient until\n", + " the input layer is reached. Each layers respective weights are updated while\n", + " the algorithm propagates backwards from the output layer (auto-differentation in reverse mode).\n", + "\n", + " Parameters:\n", + " ------------\n", + " I X (np.ndarray): The design matrix, with n rows of p features each.\n", + " II t (np.ndarray): The target vector, with n rows of p targets.\n", + " III lam (float32): regularization parameter used to punish the weights in case of overfitting\n", + "\n", + " Returns:\n", + " ------------\n", + " No return value.\n", + "\n", + " \"\"\"\n", + " out_derivative = derivate(self.output_func)\n", + " hidden_derivative = derivate(self.hidden_func)\n", + "\n", + " for i in range(len(self.weights) - 1, -1, -1):\n", + " # delta terms for output\n", + " if i == len(self.weights) - 1:\n", + " # for multi-class classification\n", + " if (\n", + " self.output_func.__name__ == \"softmax\"\n", + " ):\n", + " delta_matrix = self.a_matrices[i + 1] - t\n", + " # for single class classification\n", + " else:\n", + " cost_func_derivative = grad(self.cost_func(t))\n", + " delta_matrix = out_derivative(\n", + " self.z_matrices[i + 1]\n", + " ) * cost_func_derivative(self.a_matrices[i + 1])\n", + "\n", + " # delta terms for hidden layer\n", + " else:\n", + " delta_matrix = (\n", + " self.weights[i + 1][1:, :] @ delta_matrix.T\n", + " ).T * hidden_derivative(self.z_matrices[i + 1])\n", + "\n", + " # calculate gradient\n", + " gradient_weights = self.a_matrices[i][:, 1:].T @ delta_matrix\n", + " gradient_bias = np.sum(delta_matrix, axis=0).reshape(\n", + " 1, delta_matrix.shape[1]\n", + " )\n", + "\n", + " # regularization term\n", + " gradient_weights += self.weights[i][1:, :] * lam\n", + "\n", + " # use scheduler\n", + " update_matrix = np.vstack(\n", + " [\n", + " self.schedulers_bias[i].update_change(gradient_bias),\n", + " self.schedulers_weight[i].update_change(gradient_weights),\n", + " ]\n", + " )\n", + "\n", + " # update weights and bias\n", + " self.weights[i] -= update_matrix\n", + "\n", + " def _accuracy(self, prediction: np.ndarray, target: np.ndarray):\n", + " \"\"\"\n", + " Description:\n", + " ------------\n", + " Calculates accuracy of given prediction to target\n", + "\n", + " Parameters:\n", + " ------------\n", + " I prediction (np.ndarray): vector of predicitons output network\n", + " (1s and 0s in case of classification, and real numbers in case of regression)\n", + " II target (np.ndarray): vector of true values (What the network ideally should predict)\n", + "\n", + " Returns:\n", + " ------------\n", + " A floating point number representing the percentage of correctly classified instances.\n", + " \"\"\"\n", + " assert prediction.size == target.size\n", + " return np.average((target == prediction))\n", + " def _set_classification(self):\n", + " \"\"\"\n", + " Description:\n", + " ------------\n", + " Decides if FFNN acts as classifier (True) og regressor (False),\n", + " sets self.classification during init()\n", + " \"\"\"\n", + " self.classification = False\n", + " if (\n", + " self.cost_func.__name__ == \"CostLogReg\"\n", + " or self.cost_func.__name__ == \"CostCrossEntropy\"\n", + " ):\n", + " self.classification = True\n", + "\n", + " def _progress_bar(self, progression, **kwargs):\n", + " \"\"\"\n", + " Description:\n", + " ------------\n", + " Displays progress of training\n", + " \"\"\"\n", + " print_length = 40\n", + " num_equals = int(progression * print_length)\n", + " num_not = print_length - num_equals\n", + " arrow = \">\" if num_equals > 0 else \"\"\n", + " bar = \"[\" + \"=\" * (num_equals - 1) + arrow + \"-\" * num_not + \"]\"\n", + " perc_print = self._format(progression * 100, decimals=5)\n", + " line = f\" {bar} {perc_print}% \"\n", + "\n", + " for key in kwargs:\n", + " if not np.isnan(kwargs[key]):\n", + " value = self._format(kwargs[key], decimals=4)\n", + " line += f\"| {key}: {value} \"\n", + " sys.stdout.write(\"\\r\" + line)\n", + " sys.stdout.flush()\n", + " return len(line)\n", + "\n", + " def _format(self, value, decimals=4):\n", + " \"\"\"\n", + " Description:\n", + " ------------\n", + " Formats decimal numbers for progress bar\n", + " \"\"\"\n", + " if value > 0:\n", + " v = value\n", + " elif value < 0:\n", + " v = -10 * value\n", + " else:\n", + " v = 1\n", + " n = 1 + math.floor(math.log10(v))\n", + " if n >= decimals - 1:\n", + " return str(round(value))\n", + " return f\"{value:.{decimals-n-1}f}\"" + ] + }, + { + "cell_type": "markdown", + "id": "2bd145b9", + "metadata": { + "editable": true + }, + "source": [ + "Before we make a model, we will quickly generate a dataset we can use\n", + "for our linear regression problem as shown below" + ] + }, + { + "cell_type": "code", + "execution_count": 20, + "id": "c7f3d7ad", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "import autograd.numpy as np\n", + "from sklearn.model_selection import train_test_split\n", + "\n", + "def SkrankeFunction(x, y):\n", + " return np.ravel(0 + 1*x + 2*y + 3*x**2 + 4*x*y + 5*y**2)\n", + "\n", + "def create_X(x, y, n):\n", + " if len(x.shape) > 1:\n", + " x = np.ravel(x)\n", + " y = np.ravel(y)\n", + "\n", + " N = len(x)\n", + " l = int((n + 1) * (n + 2) / 2) # Number of elements in beta\n", + " X = np.ones((N, l))\n", + "\n", + " for i in range(1, n + 1):\n", + " q = int((i) * (i + 1) / 2)\n", + " for k in range(i + 1):\n", + " X[:, q + k] = (x ** (i - k)) * (y**k)\n", + "\n", + " return X\n", + "\n", + "step=0.5\n", + "x = np.arange(0, 1, step)\n", + "y = np.arange(0, 1, step)\n", + "x, y = np.meshgrid(x, y)\n", + "target = SkrankeFunction(x, y)\n", + "target = target.reshape(target.shape[0], 1)\n", + "\n", + "poly_degree=3\n", + "X = create_X(x, y, poly_degree)\n", + "\n", + "X_train, X_test, t_train, t_test = train_test_split(X, target)" + ] + }, + { + "cell_type": "markdown", + "id": "312deebb", + "metadata": { + "editable": true + }, + "source": [ + "Now that we have our dataset ready for the regression, we can create\n", + "our regressor. Note that with the seed parameter, we can make sure our\n", + "results stay the same every time we run the neural network. For\n", + "inititialization, we simply specify the dimensions (we wish the amount\n", + "of input nodes to be equal to the datapoints, and the output to\n", + "predict one value)." + ] + }, + { + "cell_type": "code", + "execution_count": 21, + "id": "9c4f1717", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "input_nodes = X_train.shape[1]\n", + "output_nodes = 1\n", + "\n", + "linear_regression = FFNN((input_nodes, output_nodes), output_func=identity, cost_func=CostOLS, seed=2023)" + ] + }, + { + "cell_type": "markdown", + "id": "825279d3", + "metadata": { + "editable": true + }, + "source": [ + "We then fit our model with our training data using the scheduler of our choice." + ] + }, + { + "cell_type": "code", + "execution_count": 22, + "id": "e6133768", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "linear_regression.reset_weights() # reset weights such that previous runs or reruns don't affect the weights\n", + "\n", + "scheduler = Constant(eta=1e-3)\n", + "scores = linear_regression.fit(X_train, t_train, scheduler)" + ] + }, + { + "cell_type": "markdown", + "id": "d561f849", + "metadata": { + "editable": true + }, + "source": [ + "Due to the progress bar we can see the MSE (train_error) throughout\n", + "the FFNN's training. Note that the fit() function has some optional\n", + "parameters with defualt arguments. For example, the regularization\n", + "hyperparameter can be left ignored if not needed, and equally the FFNN\n", + "will by default run for 100 epochs. These can easily be changed, such\n", + "as for example:" + ] + }, + { + "cell_type": "code", + "execution_count": 23, + "id": "22a52980", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "linear_regression.reset_weights() # reset weights such that previous runs or reruns don't affect the weights\n", + "\n", + "scores = linear_regression.fit(X_train, t_train, scheduler, lam=1e-4, epochs=1000)" + ] + }, + { + "cell_type": "markdown", + "id": "e0dba967", + "metadata": { + "editable": true + }, + "source": [ + "We see that given more epochs to train on, the regressor reaches a lower MSE.\n", + "\n", + "Let us then switch to a binary classification. We use a binary\n", + "classification dataset, and follow a similar setup to the regression\n", + "case." + ] + }, + { + "cell_type": "code", + "execution_count": 24, + "id": "d05f8035", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "from sklearn.datasets import load_breast_cancer\n", + "from sklearn.preprocessing import MinMaxScaler\n", + "\n", + "wisconsin = load_breast_cancer()\n", + "X = wisconsin.data\n", + "target = wisconsin.target\n", + "target = target.reshape(target.shape[0], 1)\n", + "\n", + "X_train, X_val, t_train, t_val = train_test_split(X, target)\n", + "\n", + "scaler = MinMaxScaler()\n", + "scaler.fit(X_train)\n", + "X_train = scaler.transform(X_train)\n", + "X_val = scaler.transform(X_val)" + ] + }, + { + "cell_type": "code", + "execution_count": 25, + "id": "dc7b7fec", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "input_nodes = X_train.shape[1]\n", + "output_nodes = 1\n", + "\n", + "logistic_regression = FFNN((input_nodes, output_nodes), output_func=sigmoid, cost_func=CostLogReg, seed=2023)" + ] + }, + { + "cell_type": "markdown", + "id": "7bfd050a", + "metadata": { + "editable": true + }, + "source": [ + "We will now make use of our validation data by passing it into our fit function as a keyword argument" + ] + }, + { + "cell_type": "code", + "execution_count": 26, + "id": "02b08ed6", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "logistic_regression.reset_weights() # reset weights such that previous runs or reruns don't affect the weights\n", + "\n", + "scheduler = Adam(eta=1e-3, rho=0.9, rho2=0.999)\n", + "scores = logistic_regression.fit(X_train, t_train, scheduler, epochs=1000, X_val=X_val, t_val=t_val)" + ] + }, + { + "cell_type": "markdown", + "id": "59b85b1b", + "metadata": { + "editable": true + }, + "source": [ + "Finally, we will create a neural network with 2 hidden layers with activation functions." + ] + }, + { + "cell_type": "code", + "execution_count": 27, + "id": "eebfa498", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "input_nodes = X_train.shape[1]\n", + "hidden_nodes1 = 100\n", + "hidden_nodes2 = 30\n", + "output_nodes = 1\n", + "\n", + "dims = (input_nodes, hidden_nodes1, hidden_nodes2, output_nodes)\n", + "\n", + "neural_network = FFNN(dims, hidden_func=RELU, output_func=sigmoid, cost_func=CostLogReg, seed=2023)" + ] + }, + { + "cell_type": "code", + "execution_count": 28, + "id": "cabc2b09", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "neural_network.reset_weights() # reset weights such that previous runs or reruns don't affect the weights\n", + "\n", + "scheduler = Adam(eta=1e-4, rho=0.9, rho2=0.999)\n", + "scores = neural_network.fit(X_train, t_train, scheduler, epochs=1000, X_val=X_val, t_val=t_val)" + ] + }, + { + "cell_type": "markdown", + "id": "37d5b7bb", + "metadata": { + "editable": true + }, + "source": [ + "### Multiclass classification\n", + "\n", + "Finally, we will demonstrate the use case of multiclass classification\n", + "using our FFNN with the famous MNIST dataset, which contain images of\n", + "digits between the range of 0 to 9." + ] + }, + { + "cell_type": "code", + "execution_count": 29, + "id": "ffc6fca1", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "from sklearn.datasets import load_digits\n", + "\n", + "def onehot(target: np.ndarray):\n", + " onehot = np.zeros((target.size, target.max() + 1))\n", + " onehot[np.arange(target.size), target] = 1\n", + " return onehot\n", + "\n", + "digits = load_digits()\n", + "\n", + "X = digits.data\n", + "target = digits.target\n", + "target = onehot(target)\n", + "\n", + "input_nodes = 64\n", + "hidden_nodes1 = 100\n", + "hidden_nodes2 = 30\n", + "output_nodes = 10\n", + "\n", + "dims = (input_nodes, hidden_nodes1, hidden_nodes2, output_nodes)\n", + "\n", + "multiclass = FFNN(dims, hidden_func=LRELU, output_func=softmax, cost_func=CostCrossEntropy)\n", + "\n", + "multiclass.reset_weights() # reset weights such that previous runs or reruns don't affect the weights\n", + "\n", + "scheduler = Adam(eta=1e-4, rho=0.9, rho2=0.999)\n", + "scores = multiclass.fit(X, target, scheduler, epochs=1000)" + ] + }, + { + "cell_type": "markdown", + "id": "cc530309", + "metadata": { + "editable": true + }, + "source": [ + "## Testing the XOR gate and other gates\n", + "\n", + "Let us now use our code to test the XOR gate." + ] + }, + { + "cell_type": "code", + "execution_count": 30, + "id": "0d61131c", + "metadata": { + "collapsed": false, + "editable": true + }, + "outputs": [], + "source": [ + "X = np.array([ [0, 0], [0, 1], [1, 0],[1, 1]],dtype=np.float64)\n", + "\n", + "# The XOR gate\n", + "yXOR = np.array( [[ 0], [1] ,[1], [0]])\n", + "\n", + "input_nodes = X.shape[1]\n", + "output_nodes = 1\n", + "\n", + "logistic_regression = FFNN((input_nodes, output_nodes), output_func=sigmoid, cost_func=CostLogReg, seed=2023)\n", + "logistic_regression.reset_weights() # reset weights such that previous runs or reruns don't affect the weights\n", + "scheduler = Adam(eta=1e-1, rho=0.9, rho2=0.999)\n", + "scores = logistic_regression.fit(X, yXOR, scheduler, epochs=1000)" + ] + }, + { + "cell_type": "markdown", + "id": "ce4ce787", + "metadata": { + "editable": true + }, + "source": [ + "Not bad, but the results depend strongly on the learning reate. Try different learning rates." + ] + }, + { + "cell_type": "markdown", + "id": "e5d7a6ab", + "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", + "**Book on solving differential equations with ML methods.**\n", + "\n", + "[An Introduction to Neural Network Methods for Differential Equations](https://www.springer.com/gp/book/9789401798150), by Yadav and Kumar.\n", + "\n", + "**Physics informed neural networks.**\n", + "\n", + "[Scientific Machine Learning Through Physics–Informed Neural Networks: Where we are and What’s Next](https://link.springer.com/article/10.1007/s10915-022-01939-z), by Cuomo et al\n", + "\n", + "**Thanks to Kristine Baluka Hein.**\n", + "\n", + "The lectures on differential equations were developed by Kristine Baluka Hein, now PhD student at IFI.\n", + "A great thanks to Kristine." + ] + }, + { + "cell_type": "markdown", + "id": "56b23083", + "metadata": { + "editable": true + }, + "source": [ + "## Ordinary Differential Equations first\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": "3f9d87d4", + "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": "ff7d3133", + "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." + ] + }, + { + "cell_type": "markdown", + "id": "f387989d", + "metadata": { + "editable": true + }, + "source": [ + "## The trial solution\n", + "\n", + "Let the trial solution $g_t(x)$ be" + ] + }, + { + "cell_type": "markdown", + "id": "d15b7ed8", + "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": "8b0ad0fb", + "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." + ] + }, + { + "cell_type": "markdown", + "id": "c33b7fca", + "metadata": { + "editable": true + }, + "source": [ + "## Minimization process\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": "d88cb1c8", + "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": "13593649", + "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": "a5e615d0", + "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": "952778b9", + "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$." + ] + }, + { + "cell_type": "markdown", + "id": "63c41a29", + "metadata": { + "editable": true + }, + "source": [ + "## Minimizing the cost function using gradient descent and automatic differentiation\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": "95ebdbc4", + "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": "48862a28", + "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": "98174490", + "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": "f3d8ced5", + "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": "0cdbddeb", + "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))." + ] + }, + { + "cell_type": "markdown", + "id": "8afed5da", + "metadata": { + "editable": true + }, + "source": [ + "## The function to solve for\n", + "\n", + "The program will use a neural network to solve" + ] + }, + { + "cell_type": "markdown", + "id": "b6cdd16d", + "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": "9423bac1", + "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$." + ] + }, + { + "cell_type": "markdown", + "id": "e3ddd331", + "metadata": { + "editable": true + }, + "source": [ + "## The trial solution\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": "41278f19", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "g_t(x, P) = h_1(x) + h_2(x, N(x, P))\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "8d0ce198", + "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." + ] + }, + { + "cell_type": "markdown", + "id": "dc70817c", + "metadata": { + "editable": true + }, + "source": [ + "## Setup of Network\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": "8c2e8dde", + "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": "5ad2bff5", + "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": "5f845ba6", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "g_t(x, P) = g_0 + x \\cdot N(x, P)\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "2604055d", + "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": "b4ba9669", + "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": "875686e8", + "metadata": { + "editable": true + }, + "source": [ + "is fulfilled as *best as possible*." + ] + }, + { + "cell_type": "markdown", + "id": "ee9f7d57", + "metadata": { + "editable": true + }, + "source": [ + "## More technicalities\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": "1e370697", + "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": "833f3b82", + "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": "35da5498", + "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": "b44a64f2", + "metadata": { + "editable": true + }, + "source": [ + "for an input value $x$." + ] + }, + { + "cell_type": "markdown", + "id": "116b1937", + "metadata": { + "editable": true + }, + "source": [ + "## More details\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": "9ef6d929", + "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": "bd901882", + "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": "31348d62", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "\\min_{P} C(\\boldsymbol{x}, P)\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "ae4a794d", + "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", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "a4ca4b65", + "metadata": { + "editable": true + }, + "source": [ + "## A possible implementation of a neural network\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} }$." + ] + }, + { + "cell_type": "markdown", + "id": "6cd19213", + "metadata": { + "editable": true + }, + "source": [ + "## Technicalities\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": "e6d9fb88", + "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": "2b7229da", + "metadata": { + "editable": true + }, + "source": [ + "## Final technicalities I\n", + "\n", + "The result after weighting the inputs at the $i$-th hidden neuron can be written as a vector:" + ] + }, + { + "cell_type": "markdown", + "id": "cd4f193b", + "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": "e475f927", + "metadata": { + "editable": true + }, + "source": [ + "## Final technicalities II\n", + "\n", + "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": "95a91bdd", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "f(z) = \\frac{1}{1 + \\exp{(-z)}}\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "56c75c71", + "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." + ] + }, + { + "cell_type": "markdown", + "id": "0cc6d1a9", + "metadata": { + "editable": true + }, + "source": [ + "## Final technicalities III\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": "0175da6a", + "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": "5fe7bc0e", + "metadata": { + "editable": true + }, + "source": [ + "## Final technicalities IV\n", + "\n", + "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": "7f0577a4", + "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": "11c8c142", + "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." + ] + }, + { + "cell_type": "markdown", + "id": "01ca4d08", + "metadata": { + "editable": true + }, + "source": [ + "## Back propagation\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": "f5133d80", + "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": "c1e40110", + "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": "89f577fa", + "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": "73db81fc", + "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": "6956b9f1", + "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": "13e5d04c", + "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": "dd560ef7", + "metadata": { + "editable": true + }, + "source": [ + "## The code for solving the ODE" + ] + }, + { + "cell_type": "code", + "execution_count": 31, + "id": "ac42510c", + "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", + "# 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": "22aed435", + "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": 32, + "id": "96179484", + "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", + " # deep_params is a list, len() should be used\n", + " N_hidden = len(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": "a0ff62a9", + "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": "e9112c77", + "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": "cf582ad1", + "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." + ] + }, + { + "cell_type": "markdown", + "id": "d945a6b3", + "metadata": { + "editable": true + }, + "source": [ + "## Setting up the problem\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": "e98cd638", + "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": "8b5c6044", + "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$." + ] + }, + { + "cell_type": "markdown", + "id": "74c055d2", + "metadata": { + "editable": true + }, + "source": [ + "## The trial solution\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", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "a65e3069", + "metadata": { + "editable": true + }, + "source": [ + "## The program using Autograd\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": 33, + "id": "b092c21e", + "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(deep_params, x):\n", + " # N_hidden is the number of hidden layers\n", + " # deep_params is a list, len() should be used\n", + " N_hidden = len(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", + "\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": "1aa71f38", + "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": "9d1de21f", + "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": "826b08a1", + "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": "c4493848", + "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": "e37b66c6", + "metadata": { + "editable": true + }, + "source": [ + "Now, if $g_i = g(t_i)$ then" + ] + }, + { + "cell_type": "markdown", + "id": "264abdcc", + "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": "afc2e4cc", + "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": 34, + "id": "63c572f6", + "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": "6381dfa2", + "metadata": { + "editable": true + }, + "source": [ + "## Example: Solving the one dimensional Poisson equation\n", + "\n", + "The Poisson equation for $g(x)$ in one dimension is" + ] + }, + { + "cell_type": "markdown", + "id": "ddcc006d", + "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": "85639943", + "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": "f17eea8d", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "\\begin{align*}\n", + " g(0) &= 0 \\\\\n", + " g(1) &= 0\n", + "\\end{align*}\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "1efed335", + "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." + ] + }, + { + "cell_type": "markdown", + "id": "23e866a2", + "metadata": { + "editable": true + }, + "source": [ + "## The specific equation to solve for\n", + "\n", + "Here, the function $g(x)$ to solve for follows the equation" + ] + }, + { + "cell_type": "markdown", + "id": "2cfcda87", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "-g''(x) = f(x),\\qquad x \\in (0,1)\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "b2a2d58c", + "metadata": { + "editable": true + }, + "source": [ + "where $f(x)$ is a given function, along with the chosen conditions" + ] + }, + { + "cell_type": "markdown", + "id": "a7c84b58", + "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": "9db2324e", + "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": "f94f8d1a", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "g_t(x) = x \\cdot (1-x) \\cdot N(P,x)\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "e8eaba06", + "metadata": { + "editable": true + }, + "source": [ + "The analytical solution for this problem is" + ] + }, + { + "cell_type": "markdown", + "id": "3c345647", + "metadata": { + "editable": true + }, + "source": [ + "$$\n", + "g(x) = x(1 - x)\\exp(x)\n", + "$$" + ] + }, + { + "cell_type": "markdown", + "id": "0d913be0", + "metadata": { + "editable": true + }, + "source": [ + "## Solving the equation using Autograd" + ] + }, + { + "cell_type": "code", + "execution_count": 35, + "id": "96194d94", + "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", + " # deep_params is a list, len() should be used\n", + " N_hidden = len(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", + "\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": "780c5c66", + "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": "b6dfbfdc", + "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": "011ba117", + "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": "cdf079bc", + "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": "bf2fc40c", + "metadata": { + "editable": true + }, + "source": [ + "Since we know from our problem that" + ] + }, + { + "cell_type": "markdown", + "id": "6662f05c", + "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": "fe9a0465", + "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": "7603ea9a", + "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": "6744dfef", + "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": "af13fca6", + "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": "bd1bd149", + "metadata": { + "editable": true + }, + "source": [ + "which makes it possible to solve for the vector $\\boldsymbol{g}$." + ] + }, + { + "cell_type": "markdown", + "id": "43e51ef4", + "metadata": { + "editable": true + }, + "source": [ + "## Setting up the code\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": 36, + "id": "49c94dd9", + "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", + " # deep_params is a list, len() should be used\n", + " N_hidden = len(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", + "\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": "6d27256f", + "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": "df08a8ac", + "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": "ec4b9fd4", + "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": "92f17705", + "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": "eec1785d", + "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": "544c3fce", + "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": "74af5618", + "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": "9a7c5864", + "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": "3f2d680d", + "metadata": { + "editable": true + }, + "source": [ + "## More details\n", + "\n", + "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": "118044b0", + "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": "e9b82be4", + "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": "d5e6b103", + "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": "c9dec199", + "metadata": { + "editable": true + }, + "source": [ + "## Example: The diffusion equation\n", + "\n", + "In one spatial dimension, the equation reads" + ] + }, + { + "cell_type": "markdown", + "id": "118d2522", + "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": "1d13aaff", + "metadata": { + "editable": true + }, + "source": [ + "where a possible choice of conditions are" + ] + }, + { + "cell_type": "markdown", + "id": "4de9c463", + "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": "65b2ba09", + "metadata": { + "editable": true + }, + "source": [ + "with $u(x)$ being some given function." + ] + }, + { + "cell_type": "markdown", + "id": "843d90aa", + "metadata": { + "editable": true + }, + "source": [ + "## Defining the problem\n", + "\n", + "For this case, we want to find $g(x,t)$ such that" + ] + }, + { + "cell_type": "markdown", + "id": "77447bcd", + "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": "c3cf90aa", + "metadata": { + "editable": true + }, + "source": [ + "and" + ] + }, + { + "cell_type": "markdown", + "id": "257d1f48", + "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": "7f4f7d6a", + "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." + ] + }, + { + "cell_type": "markdown", + "id": "1e0c143a", + "metadata": { + "editable": true + }, + "source": [ + "## Setting up the network using Autograd\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": 37, + "id": "e52c49e9", + "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 = len(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": "e6975906", + "metadata": { + "editable": true + }, + "source": [ + "## Setting up the network using Autograd; The trial solution\n", + "\n", + "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)$." + ] + }, + { + "cell_type": "markdown", + "id": "d665f51c", + "metadata": { + "editable": true + }, + "source": [ + "## Why the jacobian?\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": 38, + "id": "152c290e", + "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": "eac82d2c", + "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": 39, + "id": "df3d9605", + "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 = len(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.add_suplot(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.add_suplot(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.add_suplot(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": "fec03008", + "metadata": { + "editable": true + }, + "source": [ + "## Example: Solving the wave equation with Neural Networks\n", + "\n", + "The wave equation is" + ] + }, + { + "cell_type": "markdown", + "id": "403f7560", + "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": "dc05badf", + "metadata": { + "editable": true + }, + "source": [ + "with $c$ being the specified wave speed.\n", + "\n", + "Here, the chosen conditions are" + ] + }, + { + "cell_type": "markdown", + "id": "1daf1dd8", + "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": "4da632df", + "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." + ] + }, + { + "cell_type": "markdown", + "id": "851bb943", + "metadata": { + "editable": true + }, + "source": [ + "## The problem to solve for\n", + "\n", + "The wave equation to solve for, is" + ] + }, + { + "cell_type": "markdown", + "id": "760b72fe", + "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": "e3e22598", + "metadata": { + "editable": true + }, + "source": [ + "where $c$ is the given wave speed.\n", + "The chosen conditions for this equation are" + ] + }, + { + "cell_type": "markdown", + "id": "59f39060", + "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": "bf3a2904", + "metadata": { + "editable": true + }, + "source": [ + "In this example, let $c = 1$ and $u(x) = \\sin(\\pi x)$ and $v(x) = -\\pi\\sin(\\pi x)$." + ] + }, + { + "cell_type": "markdown", + "id": "4a633f01", + "metadata": { + "editable": true + }, + "source": [ + "## The trial solution\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." + ] + }, + { + "cell_type": "markdown", + "id": "c09dc6a7", + "metadata": { + "editable": true + }, + "source": [ + "## The analytical solution\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": "markdown", + "id": "592d4d57", + "metadata": { + "editable": true + }, + "source": [ + "## Solving the wave equation - the full program using Autograd" + ] + }, + { + "cell_type": "code", + "execution_count": 40, + "id": "1c25dc4e", + "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 = len(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.add_suplot(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.add_suplot(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.add_suplot(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": "5072a8bd", + "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 +}