notebooks/Gradient-Descent.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In supervised learning algorithms, we generally have some model (such as a neural network) with a set of parameters (the weights), a data set, and an error function which measures how well our parameters and model fit the data. With many models, the way to train the model and fit the parameters is through an iterative minimization procedure which uses the gradient of the error to find the local minimum in parameter space. This notebook will not go into the details of neural networks or how to compute the derivatives of error functions, but instead focuses on some of the simple minimization methods one can employ. The goal of this notebook is to develop a simple yet flexible framework in Haskell in which we can develop gradient descent methods.\n",
    "\n",
    "Although you should keep in mind that the goal of these algorithms (for our purposes) is to train neural networks, for now we will just discuss some abstract function $f(\\vec x)$ for which we can compute all partial derivatives.\n",
    "$\\newcommand\\vector[1]{\\langle #1 \\rangle}\\newcommand\\p[2]{\\frac{\\partial #1}{\\partial #2}}$\n",
    "\n",
    "Gradient Descent\n",
    "---\n",
    "The simplest algorithm for iterative minimization of differentiable functions is known as just **gradient descent**.\n",
    "Recall that the gradient of a function is defined as the vector of partial derivatives:\n",
    "\n",
    "$$\\nabla f(x) = \\vector{\\p{f}{x_1}, \\p{f}{x_2}, \\ldots, \\p{f}{x_n}}$$\n",
    "\n",
    "and that the gradient of a function always points towards the direction of maximal increase at that point.\n",
    "\n",
    "Equivalently, it points *away* from the direction of maximum decrease - thus, if we start at any point, and keep moving in the direction of the negative gradient, we will eventually reach a local minimum.\n",
    "\n",
    "This simple insight leads to the Gradient Descent algorithm. Outlined algorithmically, it looks like this:\n",
    "\n",
    "1. Pick a point $x_0$ as your initial guess.\n",
    "2. Compute the gradient at your current guess:\n",
    "$v_i = \\nabla f(x_i)$\n",
    "3. Move by $\\alpha$ (your step size) in the direction of that gradient:\n",
    "$x_{i+1} = x_i + \\alpha v_i$\n",
    "4. Repeat steps 1-3 until your function is close enough to zero (until $f(x_i) < \\varepsilon$ for some small tolerance $\\varepsilon$)\n",
    "\n",
    "Note that the step size, $\\alpha$, is simply a parameter of the algorithm and has to be fixed in advance. \n",
    "\n",
    "Though this algorithm is simple, it will be a bit of a challenge to formalize it into executable Haskell code that we can later extend to other algorithms. First, note that gradient descent requires two things:\n",
    "\n",
    "- Something to optimize (a function)\n",
    "- What to optimize over (the parameters)\n",
    "- A way to compute partials of the function\n",
    "\n",
    "Note that we don't actually need to *call* the function itself - only the partial derivatives are necessary.\n",
    "\n",
    "We're going to define a single class for things on which we can run gradient descent. Although later we may want to modify this class, this serves as a beginning:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    ":set -XTypeFamilies\n",
    "class GradientDescent a where\n",
    "  -- Type to represent the parameter space.\n",
    "  data Params a :: *\n",
    "  \n",
    "  -- Compute the gradient at a location in parameter space.\n",
    "  grad :: a -> Params a -> Params a\n",
    "  \n",
    "  -- Move in parameter space.\n",
    "  paramMove :: Double    -- Scaling factor.\n",
    "            -> Params a  -- Direction vector.\n",
    "            -> Params a  -- Original location.\n",
    "            -> Params a  -- New location."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In order to use some type `a` with our gradient descent, we require that it is an instance of `GradientDescent`. This class requires a few things.\n",
    "\n",
    "First off, we use type families in order to define a representation for the parameter space. We want to be able to operate on points in the parameter space of our function; however, while something like a list of values might be nice and simple in one case, it is inappropriate and inefficient when storing the weights of a neural network. Thus, we let each class instance decide how to store its parameters by defining an associated type instance. (We will see an instance of this later!)\n",
    "\n",
    "Next, `GradientDescent` requires a single function called `grad`, which takes the thing of type `a` and the current point in parameter space (via a `Param a`) and outputs a set of partial derivatives. The partial derivatives have the same form and dimension as the point in parameter space, so they are also a `Param a`. \n",
    "\n",
    "Finally, we must be able to move around in parameter space, so `GradientDescent` defines a function `paramMove` which does exactly that - it takes a parameter vector and an amount by which to move and uses these to generate a new position from an old one.\n",
    "\n",
    "Let's go ahead and create the simplest instantiation of this class and type family: a single-argument function. Note that this is just for demo purposes, and we're going to use numerical differentiation to compute the derivative."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "-- We need flexible instances for declarations like these.\n",
    ":set -XFlexibleInstances\n",
    "\n",
    "instance Floating a => GradientDescent (a -> a) where\n",
    "  -- The parameter for a function is just its argument.\n",
    "  data Params (a -> a) = Arg { unArg :: a }\n",
    "\n",
    "  -- Use numeric differentiation for taking the gradient.\n",
    "  grad f (Arg value) = Arg $ (f value - f (value - epsilon)) / epsilon\n",
    "    where epsilon = 0.0001\n",
    "    \n",
    "  paramMove scale (Arg vec) (Arg old) = Arg $ old + fromRational (toRational scale) * vec"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We're getting closer to implementing the actual algorithm. However, we have yet to define when the algorithm *stops* - and, in order to give maximum flexibility to the user, we'll let the stopping condition be an argument. This lets the user specify an error tolerance, as well as how they want to derive this error:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "-- Define a way to decide when to stop.\n",
    "-- This lets the user specify an error tolerance easily.\n",
    "-- The function takes the previous two sets of parameters and returns\n",
    "-- `True` to continue the descent and `False` to stop.\n",
    "newtype StopCondition a = StopWhen (Params a -> Params a -> Bool)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "With a single instance of our class, we can now implement our gradient descent algorithm:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "gradientDescent :: GradientDescent a => a  -- What to optimize.\n",
    "                -> StopCondition a        -- When to stop.\n",
    "                -> Double                 -- Step size (alpha).\n",
    "                -> Params a               -- Initial point (x0).\n",
    "                -> Params a               -- Return: Location of minimum.\n",
    "gradientDescent function (StopWhen stop) alpha x0 =\n",
    "  let iterations = iterate takeStep x0\n",
    "      iterationPairs = zip iterations $ tail iterations\n",
    "    in\n",
    "      -- Drop all elements where the resulting parameters (and previous parameters)\n",
    "      -- do not meet the stop condition. Then, return just the last parameter set.\n",
    "      snd . head $ dropWhile (not . uncurry stop) iterationPairs\n",
    "  where\n",
    "    -- For each step...\n",
    "    takeStep params = \n",
    "      -- Compute the gradient.\n",
    "      let gradients = grad function params in\n",
    "        -- And move against the gradient with a step size alpha.\n",
    "        paramMove (-alpha) gradients params"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's go ahead and try this for some simple functions. First, we need to create a stopping condition. In this case, we're going to stop when successive updates to the parameters do not affect the outcome very much - namely, when the difference between the function value at successive parameters is below some $\\varepsilon$-tolerance. In other scenarios, we may want to use a more complicated stopping criterion."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "-- Create a stop condition that respects a given error tolerance.\n",
    "stopCondition :: (Double -> Double) -> Double -> StopCondition (Double -> Double)\n",
    "stopCondition f tolerance = StopWhen stop\n",
    "  where stop (Arg prev) (Arg cur) =\n",
    "          abs (f prev - f cur) < tolerance  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's finally try to minimize something, such as the relatively trivial function $f(x) = x^2 + 3x$. It's graph looks like this:\n",
    "\n",
    "<center>\n",
    "<img src=\"data:image/png;base64,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ICA8L3JkZjpSREY+CjwveDp4bXBtZXRhPgoauLcRAABAAElEQVR4AezdB7wU1dkHYLqgIoJgARv2hmLBkoiKJRr9gjUWYoXYUFRMNEoEa6xRRI0FC8TeYjeWxBqNhRALsUQlxgIWVFRUEC7e7z2sGuRe4Ja9u7O7z/zw797ZmTnnPGcpu+/OTPPq6upmTb+ccML90UivXstE7rjjmk3foBYIECBAgAABAgQIEKi3QPPmzWOfwrxHqHvnWtR9U1sSIECAAAECBAgQIECg8ALNC/Mu6sUX34uxnX32o5HXXLNnZO49XDywECBAgAABAgQIECCQEQGVloxMhG4QIECAAAECBAgQIFBKAq0K09m1114qGlpooTaRTz31VuSPfrR8pIUAAQIECBAgQIAAAQLzFnBOy7x9PEuAAAECBAgQIECAQJEFClRpyY1yjz3WiQc33/xCpEpLkWde8wQIECBAgAABAqUuMG1KjGDyjHaRHdvP/x/206ak7Vu1b58y/iudRaWldOZKTwkQIECAAAECBAhUpEBB32JtvvkKgXzJJU9FvvbapMhVVulSkewGTYAAAQIECBAgQKDhAlPGjY6d97no88jd13wpckznwZHD+60W+cNlYvx42T4/jTzk2hdnPbV35OMfjors3aWgbwdmtd6QUGlpiJp9CBAgQIAAAQIECBAomECB7tMy+3huvTW9w3v55Q8ihw3bZvanPCZAgAABAgQIECBAYF4CVa/Gs/u0Xj3y5x9WR/btkmopg5t3i+wzYUZa0/V/9ZO37jo71jyy9IGR+6+Xzma5f3DryN90Hxv5whHrRc6+uE/L7BoeEyBAgAABAgQIECBAoE4C/3sTVqfN87HRDjuk94XXXJPe202cmL6H17XrIvk4sGMQIECAAAECBAgQKHeBqenM8AnNTonc5NvTw1P9ZLW108BfeCddH6xv147ph1nLEn2OiP/v377ttz83a9ate594vHbnDt+vyf4D57Rkf470kAABAgQIECBAgEBFCxSh0tKuXfoWXd++a0bedNPzkYMHb1bRk2DwBAgQIECAAAECBOomMOX1dCXeR5qlOsl31ZNUaem5W6qfPBj//XBpO1uNJb7nFE/eccfKkYPvXPGHG2b6J5WWTE+PzhEgQIAAAQIECBAgUIRKSw59l116xIN99rkhsn//XpEdOrTLPSUJECBAgAABAgQIEKhVoH33DWJ9n2ZPRk6btUX7Zuk8lmdufST99JNZq2qJqlh3/5DfRK54+eWRsy4kVst2uVW5a4jVfLq6Ol2vrPCLSkvhzbVIgAABAgQIECBAgEA9BIpWaenYMdVVttxypcg//WlcZP/+G9aj4zYlQIAAAQIECBAgUIECHdO5KOs02yryqUlDI/t2SVWUz15Mlw/rtUI6vyVXg5k4cWo86jrrSmLjRh8Tj8dsdlrk0BXTuTDjH74rckavvpGr5XaKR98txaqofNf+nP9XaZlTxM8ECBAgQIAAAQIECGRKoHlx30VNmPBZcAwceFvkTTftHdm2bbq2mIUAAQIECBAgQIAAgbkJTP7n6HjqgOEfRu7eY3zkmKUHRw7vt1pk1VvXR7Ze/ubIJ5/YMvLHmx4Z+YPloFvix6mX7Rb53VXI0vO5s1mK+x4h9eOHi0rLDz38RIAAAQIECBAgQIBAxgSKXGnJaZx44gPxYO21u0buumu6qpiFAAECBAgQIECAAIH5CFSl64ZNnpK+qdSx4+z1kvnsN4+nVVrmgeMpAgQIECBAgAABAgQI1C6QiUrLK698EL076aS/RF5/fb/Ili19b632CbOWAAECBAgQIECAQNMJqLQ0na0jEyBAgAABAgQIECBQtgJFu0/L7KKrr75E/LjUUukC0Y88kq5+sPXWK8++gccECBAgQIAAAQIECFSsgG9hVezUGzgBAgQIECBAgACB0hDIRKUlR7Xnnj3jwRVXPBup0lIaLx+9JECAAAECBAgQIND0AiotTW+sBQIECBAgQIAAAQIEGiGQoTctG2+8XPyaOfOb+DVmzDvxqxHjsisBAgQIECBAgAABAmUikKE3LWUiahgECBAgQIAAAQIECORVIEPntOTGtdde68aDG254LrJXr2XyOlgHI0CAAAECBAgQIECg9ARUWkpvzvSYAAECBAgQIECAQEUJZK7SstVWK8UEXH75M5GvvTYpcpVVulTUlBgsAQIECBAgQIAAAQKzC6i0zK7hMQECBAgQIECAAAECmRNoXl1dnblONWt2yy0vRK9efvnDyBNP3CaDPdQlAgQIECBAgAABAuUn0Lx58xhU1t4jqLSU3yvNiAgQIECAAAECBAiUlUDmzmnJ6f7f/60RD6655p+R7733eeRSSy2Se0oSIECAAAECBAgQIFBRAiotFTXdBkuAAAECBAgQIECg9AQyek5LDvKKK9I1xL74YnrkUUf1Lj1dPSZAgAABAgQIECBQUgLOaSmp6dJZAgQIECBAgAABAgSyIZDpSssnn3wVSvvue2PkddftFdmhQ7tsuOkFAQIECBAgQIAAgTIUyFVaag6suNcTc05LzRmxhgABAgQIECBAgACBDAlkutKSczr33MfiQadOC0YecECvDOHpCgECBAgQIECAAIHyEnBOS3nNp9EQIECAAAECBAgQIFAQgRKotEyY8FlQDBx4W+RNN+0d2bZt64LgaIQAAQIECBAgQIBAZQmotFTWfBstAQIECBAgQIAAAQJ5EWiVl6M06UG6desQx+/Zs2vkvfe+Grnrrj2atEUHJ0CAAAECBAgQIEAgOwKuHpadudATAgQIECBAgAABAgRqESiBc1pyvX7llQ/iwUkn/SXy+uv7RbZs6R1XzkYSIECAAAECBAgQyI+Ac1ry4+goBAgQIECAAAECBAhUlEAJnNOSm4/VV18iHiy1VPvIRx4ZH7n11ivnnpIECBAgQIAAAQIECJSxgG9YlfHkGhoBAgQIECBAgACBchAomUpLDnvPPXvGgyuueDZSpaUcXoDGQIAAAQIECBAgQGB+Aiot8xPyPAECBAgQIECAAAECRRUosTctG2+8XPyqqvomfv3jH+/Er6LqaZwAAQIECBAgQIAAgSYXKLE3LU3uoQECBAgQIECAAAECBDImUGLntOT09torndlyww3PR26wwTIZI9UdAgQIECBAgAABAgTyKaDSkk9NxyJAgAABAgQIECBAIO8CJVlpyV037KqrxgTH669/FLnyyp3zTuOABAgQIECAAAECBAhkQUClJQuzoA8ECBAgQIAAAQIECMxVoHl1dfVcn8z2E7ffPi46OHbshMjTTtsu253VOwIECBAgQIAAAQIlINC8efPoZdbeI6i0lMBLRxcJECBAgAABAgQIVLJASZ7TkpuwHXZYPR5cffXYyDff/CSye/dOuackAQIECBAgQIAAAQJlI6DSUjZTaSAECBAgQIAAAQIEylOghM9pyU3IDTc8Fw/eeOPjyKFDty7PWTIqAgQIECBAgAABAgURcE5LQZg1QoAAAQIECBAgQIBAeQmU8DktuYnYaae14sEee1wbOWHCZ5HdunXIPSUJECBAgAABAgQIECgDAee0lMEkGgIBAgQIECBAgACBchYo+XNacpMzevSYeDBp0peRxxyzRW6lJECAAAECBAgQIECgXgK5c1pq7lLcO7eotNScEWsIECBAgAABAgQIEMiQQJlUWqZM+TpQ99rrushRo3aP7NJl4Qwx6woBAgQIECBAgACBUhBw9bBSmCV9JECAAAECBAgQIEAgYwJlUmnJqV566VPxYPr0mZFHHLFpxqh1hwABAgQIECBAgEDWBVRasj5D+keAAAECBAgQIECAQAYFyqrS8sknXwXxvvveGHnNNXtFduzYLoPoukSAAAECBAgQIEAgmwIqLdmcF70iQIAAAQIECBAgQCDTAmVVaclJjxjxt3jQrl3ryIMO2jjT/DpHgAABAgQIECBAIEsCKi1Zmg19IUCAAAECBAgQIECgRATKsNLywQdTAv+Xv7wl8oYbfhG58MILlMh06CYBAgQIECBAgACBYgqotBRTX9sECBAgQIAAAQIECJSoQBlWWnIzcdZZj8SDJZdsH7nffhuU6PToNgECBAgQIECAAIFCCqi0FFJbWwQIECBAgAABAgQIlIlA2VZa3n3305iiww67PfLGG/eOzF1PrEzmzTAIECBAgAABAgQINIGASksToDokAQIECBAgQIAAAQLlLtCqXAe49NKLxtDWX3/pyLvueilyjz16lutgjYsAAQIECBAgQIBAGQu0KOOxGRoBAgQIECBAgAABAmUgULbntOTm5j//+Tge/PrX90TeeGO6Z0ubNmVbXMoNWRIgQIAAAQIECBBosIBzWhpMZ0cCBAgQIECAAAECBCpXoMzLDiussFjM7eqrLx55772vRu6881qVO9tGToAAAQIECBAgQKAEBZzTUoKTpssECBAgQIAAAQIEKkmgzM9pyU3lq69+GA+GDn0gMndmS8uW3q1V0svcWAkQIECAAAECBOom4JyWujnZigABAgQIECBAgAABArMJlPk5LbmRrrZaOqdl2WXTnVsefPC1yJ/+dLXcU5IAAQIECBAgQIAAgYwL+JZUxidI9wgQIECAAAECBAhUukBFnNOSm+Tnn58QD37/+8cjr756z8gWLZrnnpIECBAgQIAAAQIECISAc1q8DAgQIECAAAECBAgQIFBvgYo4pyWn0rNnt3jQoUPbyMceGx/Zp89KuackAQIECBAgQIAAAQLfC+TqLd//GA+qq6tn/7HAj53TUmBwzREgQIAAAQIECBAgUD+B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nJaCTvLtt4+L9p555p3IM8/cvqBta4wAAQIECBAgQIDA/ARy57TU3Kq6urrmyoKtUWkpGLWGCBAgQIAAAQIECBBoiIBzWhqi1uB9/u//1oh9b7zxhch//ev9yLXWWrLBR7MjAQIECBAgQIAAgaYQKG5dpeaIVFpqmlhDgAABAgQIECBAgECGBJzTUoTJuP/+V6PV++77d+SIETsWoQeaJECAAAECBAgQIFCbgPu01KZiHQECBAgQIECAAAECBOYp4JyWefI0zZPbbLNKHPj665+LHDMmXUmsV69lmqYpRyVAgAABAgQIECBQ8gLOaSn5KTQAAgQIECBAgAABAuUtoNJShPlt2TK9VxwwYMPIyy9/JlKlpQjToEkCBAgQIECAAIESEVBpKZGJ0k0CBAgQIECAAAEClSrgTUvRZn6zzVaIX3EN7Fgef/w/8atoXdEwAQIECBAgQIAAgQwLeNOS4cnRNQIECBAgQIAAAQIEmjVzn5YivwrGjn03enDeeY9HXn31npG5M16K3C3NEyBAgAABAgQIVKSA+7RU5LQbNAECBAgQIECAAAECjRNw9bDG+TV67/XXXzqO0bXrIpF33fVy5M47r9XoozoAAQIECBAgQIAAgfIRcE5L+cylkRAgQIAAAQIECBAoSwHntGRiWseP/zj68etf3x153XX9IhdcsE0meqYTBAgQIECAAAEClSTgnJZKmm1jJUCAAAECBAgQIEAgTwIqLXmCzMdhzjzz4ThMly4LRw4YsGE+DukYBAgQIECAAAECBOohoNJSDyybEiBAgAABAgQIECBAICeg0pKhV8KkSV9Eb/r3vzly1Kg9Ijt3XihD/dMVAgQIECBAgACBchdQaSn3GTY+AgQIECBAgAABAgSaQEClpQlQG3fIkSOfjgN8+unUyGOP7dO4g9mbAAECBAgQIECAQD0EVFrqgWVTAgQIECBAgAABAgQI5ARagciawC9+sV50qV+/6yPffPOTyO7dO2Wtk/pDgAABAgQIECBAoGACLQrWkoYIECBAgAABAgQIECDQAAHntDQArRC7/OlP46KZZ599O/Kss3YoRJPaIECAAAECBAgQqHgB57RU/EsAAAECBAgQIECAAAEC9RdwTkv9zQqyx447rhHt3Hrri5HPPTchct11uxWkZY0QIECAAAECBAhUukCu3jK7QnV19ew/Fuxxrl3ntBQMXEMECBAgQIAAAQIECDREwDktDVEr2D6PPjo+2rruun9Gjhy5W2TNd70F64yGCBAgQIAAAQIEyl4ga+e0/PWvr4e5SkvZv/AMkAABAgQIECBAgEBpC6i0lMD8HXrobdHLXXZZK3KbbVYpgR7rIgECBAgQIECAQGkKZKfSMmPGzCDce+8bIlVaSvPVpNcECBAgQIAAAQIEKkbA1cNKYKoHDtwkennaaQ9Fbr75ipFt2rQsgX7rIgECBAgQIECAAIGGCtx++79i15VWWixSpaWhivYjQIAAAQIECBAgQKAgAiotBWFuXCM9eiwVB1h55c6Rt902LnLPPXs27pD2JkCAAAECBAgQIJBRgS+++Dp6dt11z0VeeOGOkSotGZ0q3SJAgAABAgQIECBAICeg0lIyr4SDDto4+jpo0O2RO+ywemT79guUTO91lAABAgQIECBAgEDdBHI1lt69u8fmyy7bMVKlpW5ytiJAgAABAgQIECBAoEgC7tNSJPiGNjt8+OOxa5s2qUR22GE/auhh7EeAAAECBAgQIECgFoHi3qflww+/iD4NGHBz5B//uGdkp04LRqq0BIKFAAECBAgQIECAAIHsCqi0ZHduau3Z5MlTY/2++6Y7g15++W6RSy65SK1bWkmAAAECBAgQIECgvgLFrbScccbD0eElllg4sn//Db/vvErL9xQeECBAgAABAgQIECCQRQFXD8virMyjTx07totnf/7zdSJHjnwmctiwbeaxvacIECBAgAABAgQIZF9g/PiPo5PPPvt25PXX/2KODqu0zAHiRwIECBAgQIAAAQIEsiWg0pKt+ahjb3bffe3Y8he/SGe2/PvfH0auuuriddzXZgQIECBAgAABAgSyJnDppU9Fl/bbb4PIdu1az9E9lZY5QPxIgAABAgQIECBAgEC2BFRasjUfdexN27bp3Wf//r0iL7kkvSs9//wd67ivzQgQIECAAAECBAhkR+DJJ/8bncndoeVnP1uj1o6ptNTKYiUBAgQIECBAgAABAlkRUGnJykw0oB8//elqsdett74Y+fTTb0VuvPFyDTiOXQgQIECAAAECBAgUXmDGjJnR6MUX/z1y8ODekS1b1l5TqX1t4XusRQIECBAgQIAAAQIECNQqoNJSK0tprGzRonl09NBDfxQ5YsTfIjfYYOnIVq1aRloIECBAgAABAgQIZFng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SVVVupLYoYfeFrnzzj0it99+tbIftQESIECAAAEClSMwdeqMGOwBB6Qrhg0e3Dtyo42WLfDwVVoKDK45AgQIECBAgAABAgTKQUClpRxmsaLG8Oabn8R4jzrqrsiRI3eNXGKJ9hUlYLAECBAgQIBAuQqcd97jMbTct0uOPbZPUYap0lIUdo0SIECAAAECBAgQIFDaAiotpT1/Fdv7669/Lsb+j3+8E3nuuT+LzH0qULEgBk6AAAECBAiUtMDYse9G/88665HIUaP2iFxooTZFGZFKS1HYNUqAAAECBAgQIECAQGkLqLSU9vxVbO+/+aY6xn744bdHbrPNypG564lVLIiBEyBAgAABAiUq8NVX06Pn++13U+Rxx6XzWNZff+kijkWlpYj4miZAgAABAgQIECBAoFQFVFpKdeb0OwTefffTyMMOS/WWiy/eJbJbtw6RFgIECBAgQIBAqQicc86j0dUWLZpH/upXmxe92yotRZ8CHSBAgAABAgQIECBAoPQEVFpKb870eA6B224bF2seeuiNyAsv3Cky91nFHJv5kQABAgQIECCQKYFnn307+pO7N0vuimHt2rUueg9VWoo+BTpAgAABAgQIECBAgEDpCai0lN6c6fEcAtXV6UpiRx99d+SGGy4Tudde686xjR8JECBAgAABAtkR+PzzadGZAQNuifztb7eM7NmzW0a6p9KSkYnQDQIECBAgQIAAAQIESklApaWUZktf5yHwwQdT4tmDDro18vzzd4zs3r3TPLb3FAECBAgQIECgWAJDhtwXTS+/fMfIgw7auFjdqLVdlZZaWawkQIAAAQIECBAgQIDAvARUWual47mSE/jzn1+NPueuJ3bZZbvG45YtW5TcKHSYAAECBAgQKFeBu+56KYZ2zz2vRF588c6RrVq1zNRgc5WWml3KnUVcc31h1vj3XGGctUKAAAECBAgQIECAQAMFVFoaCGe3LAscf/yfo3srr9w5sn//DbPcVX0jQIAAAQIEKkTg7bcnx0gHDboj8qKLUo1lmWUWzeDYndOSwUnRJQIECBAgQIAAAQIEsi6g0pL1GdK/Bgh8+unU2Kt//5sjhw3bOjI71z5vwHDsQoAAAQIECJS0wIwZM6P/hx56W+TOO68VucMOq2d2RCotmZ0aHSNAgAABAgQIECBAILsCKi3ZnRs9a6TAP/7xThzhrLMejbziip9HdujQNtJCgAABAgQIECikwMUX/z2ae//9dE+5U07ZtpBNN6AtlZYGoNmFAAECBAgQIECAAIFKF1BpqfRXQNmP/9JLn4oxvv32p5Gnn/7Tsh+vARIgQIAAAQLZEZj9ex9XXpm+97HIIln/3odKS3ZeP3pCgAABAgQIECBAgEDJCKi0lMxU6WjDBKqq0vU6Bg68PXL77VeL3GmndNUOCwECBAgQIECg6QQ++2xaHDx3LdMTTtgqHq+7bremay6PR1ZpySOmQxEgQIAAAQIECBAgUCkCKi2VMtMVPs4JqInrzQAAMaBJREFUEz4LgYED0/XRzz9/x8ju3TtVuInhEyBAgAABAk0nMGTIfXHw5ZfvGHnQQRs3XUN5P7JKS95JHZAAAQIECBAgQIAAgfIXUGkp/zk2wu8F7r//3/H4xhufjxw5ctfINm1aff+sBwQIECBAgACBxgvcdddLcZB77nkl8uKLd45s1apl4w9bsCOotBSMWkMECBAgQIAAAQIECJSPgEpL+cylkdRR4JRT/hJb5q6SftRRveu4l80IECBAgAABAvMWePvtybHBoEF3RF50UaqxLLPMovPeJYPPqrRkcFJ0iQABAgQIECBAgACBrAuotGR9hvQv7wJffjk9jjlgwM2RgwZtGvnjHy8faSFAgAABAgQINExgxox0X7hDD03XKd1553RHuB12WL1hhyr6XiotRZ8CHSBAgAABAgQIECBAoPQEVFpKb870OC8CL7/8QRzn+OPTNdSvvPLnkZ07L5SXIzsIAQIECBAgUGkCl1zy9xjyxIlTIk89dduSHr5KS0lPn84TIECAAAECBAgQIFAcAZWW4rhrNSMC11wzNnoyduyEyPPO+1lkixbNM9I33SBAgAABAgSyLzB27LvRyTPPfCQy992N3BVKs9/zufVQpWVuMtYTIECAAAECBAgQIEBgrgIqLXOl8UQlCHzzTXUM8+ij74rcYINlIvfee71KGLgxEiBAgAABAo0U+OyzaXGE/v3T9UhPOGGryHXX7dbIY2Zhd5WWLMyCPhAgQIAAAQIECBAgUGICKi0lNmG62xQCH330ZRx2wIBbIs8446eRa6yxRFM05JgECBAgQIBA2Qgcf/yfYyzdu3eKPOigjctmXLlKS83hVFen76cUa2lRrIa1S4AAAQIECBAgQIAAgboIqLTURck2FSHw5JP/jXFeeOETkVdeuXvkQgu1ibQQIECAAAECBGYXuPbaf8aPzzzzduT55/eNbNmyfCoBzmmZfa49JkCAAAECBAgQIECAQJ0EVFrqxGSjyhEYPvzxGOwXX0yPHDp068oZuJESIECAAAEC8xV4/vl0b7dTTvlr5MiRu0V27rzQfPcqrQ1UWkprvvSWAAECBAgQIECAAIFMCKi0ZGIadCI7AtOnV0VnDjroT5F77rlO5HbbrZad7ukJAQIECBAgUBSBTz75Kto98MBbI4cM2TJy/fWXLkpPmrpRlZamFnZ8AgQIECBAgAABAgTKUEClpQwn1ZAaL/DOO5/GQQ4//PbI3//+Z5Err9y58Yd1BAIECBAgQKDkBGbO/Cb6/Ktf3R2Zu+f9fvttUHKjqHuHVVrqbmVLAgQIECBAgAABAgQIfCug0uKlQGCuAo89Nj6eu+SSpyOvuCJdIWThhReY69aeIECAAAECBMpR4PLLn4lhvfbapMizztohskWL5uU40G/HpNJSxpNraAQIECBAgAABAgQINJWASktTyTpu2QhcdNGTMZaJEz+P/N3vtovMfQJRNgM0EAIECBAgQKBWgaeffivWn3tuuodb7jsXHTq0q3XLclqp0lJOs2ksBAgQIECAAAECBAgUSEClpUDQmildgaqqmdH5I464M3LTTbtH9uu3bukOR88JECBAgACB+Qp8+OEXsc1BB6W7spx2WvqexVprLTnfvcpjA5WW8phHoyBAgAABAgQIECBAoKACKi0F5dZY6QpMmpQ+cTn44D9FDhu2dWTPnt1Kdzh6ToAAAQIECNQqkPuGxaBB6RsWW2yxYuQee6xT65blulKlpVxn1rgIECBAgAABAgQIEGhCAZWWJsR16PITGDv23RjU7373UOTll6c7tyy22ELlN0wjIkCAAAECFStw4YVPxNg/+CB9wyJ3NkumKaZNie5NnpGuadaxfau8dFWlJS+MDkKAAAECBAgQIECAQGUJqLRU1nwbbV4ErrlmbBzn2WffiTz//L6RLVu2yMuRHYQAAQIECBAolsBjj42Ppi+77OnIkSPT9ykWXniBYnVmvu1OGTc6ttnnonQfud3XfClyTOfBkcP7rRZZc5n06sOx8vSBaZvuZzwaecRGHSNrLiotNU2sIUCAAAECBAgQIECAwHwE8vPVt/k04mkC5SWw997rxYDGjXs/cuTIZyIPPXST8hqi0RAgQIAAgQoSmDDhsxjteef9LfKcc3aIzHKNpVnVq9HDgWsfENn/w+rIvl0mRo5pnq5retcWM9KarnP+I7/9EqkC02vliGbvpiixxXdaSmzCdJcAAQIECBAgQIBApQnM+Sas0sZvvAQaIJD7rufQoVvHvr/85S2Ra621RGTv3is04Gh2IUCAAAECBIolMH16VTQ9dOgDkQMG9IpcZZUuxepMXdudOim2nNDslMhNvu1s+3i82trpAC+8k64n1rfrnOertO3YNW2zYvfIdO5OqS0qLaU2Y/pLgAABAgQIECBAoMIEVFoqbMINN38C7dunK4qccsq2kccee0/kCissFtmtW4dICwECBAgQIJB9gREjnohOrrBCp8i+fdfMSIenTU61lE+mprNTai5fv5bOvXmkWfr3Rttvn06Vlp679Yl88Ns15fY/lZZym1HjIUCAAAECBAgQIFBmAiotZTahhlNogVVXTV8mHTBgw8jcN2IvuWSXeLzAAn5zFXoutEeAAAECBOou8MAD/46Nx417L/Kyy9JdWbKzTHjmhujM2Q+k65Qulm52/90y9eN4tGiv3pF9mr0ZOW3WM+2bpfNYnrn1kfTTT2atanTkzuCteZjq6nS9ssIvKi2FN9ciAQIECBAgQIAAAQL1EPBhcD2wbEpgbgK5b8Hm7twyfHj6pulxx6XvlVoIECBAgACBrAm8+eYn0aVLL30q8rzz+ka2a9c6U51ccbsjoj+XbTe3Tr0VT7z3i30in5o0NLJvl3QNtM9eTJcP67VCOr8lV4OZOHFqPOo6+5XEvv481izQevbyTdq65lKsikrNnuTWqLTMTcZ6AgQIECBAgAABAgQyIdA8a++iMqGiEwQaJDBtWrrKxyGH3Bb585+nTzt22GH1Bh3JTgQIECBAgED+BSZPTpWHQw75U+TAgT+K3HzzFfLfTEGOOPmfo6OdA4Z/GLl7j3TnlTFLD44c3m+1yKq3ro9svfzNka/MuCOy2xv3Rw5c/aeRzc66JeK0Q3eKXK79nF+8yp3NkrX3CCotaeIsBAgQIECAAAECBAhkVkClJbNTo2OlKvD2259G1488Mn2qceaZ20euuuripToY/SZAgAABAmUhUFU1M8Zx1FF3RW6wwdKR++/fqxxGVpWuGzZ5Sjonp2PH7+7aUuvAqtJ5L1WtZtVVqmZddaxV2n7OOkuzZiottfpZSYAAAQIECBAgQIAAgXkJqLTMS8dzBBos8PTT6coev//9Y5G5O7d06bJwg49mRwIECBAgQKAxAuec82js/vnnX0eeckq6lcnc7kMST1X4otJS4S8AwydAgAABAgQIECBAoCECKi0NUbMPgToK3Hjj87Hlww+/EXnhhekaHQssUPO7o3U8mM0IECBAgACBegvcfvu42Ofuu1+J/MMfdo7M2l1Z6j2kJt5BpaWJgR2eAAECBAgQIECAAIFyFFBpKcdZNaaMCZx++kPRoxkzvok88cRtMtY73SFAgAABAuUp8NxzE2Jgp57618hcjWWppRYpz6HmdVQqLXnldDACBAgQIECAAAECBCpDQKWlMubZKIsqMH167trwd0YvNtlkuch99lm/qD3SOAECBAgQKGeB9977PIZ32GG3Rw4dunXkuut2K+cB53VsKi155XQwAgQIECBAgAABAgQqQ0ClpTLm2SgzIPDJJ19FLw455E+Rgwb9OLJ37xUy0C9dIECAAAEC5SMwdeqMGMzAgbdF7rjjmpE77bRW+QyvICNRaSkIs0YIECBAgAABAgQIECgvAbeMKK/5NJoMC3TqtGD07rTTtos85ph7I7t27RC54oqLRVoIECBAgACBxghUV1fH7r/7Xbpi51prLRmpxtIYz6zt2yJrHdIfAgQIECBAgAABAgQIzC7gnJbZNTwmUCCBRx55I1q67LKnIy+9dNfIRRdtV6C2NUOAAAECBMpR4Kqrno1hPffcxMjhw38W2apVy3IcaJOPyTktTU6sAQIECBAgQIAAAQIEyk9ApaX85tSISkbgyivTZ0LPP+8zoZKZMh0lQIAAgQwKPPbYf6JXF1/898jc9xc6dvT9hYZPlEpLw+3sSYAAAQIECBAgQIBAxQqotFTs1Bt48QVy1zkZOvSB6EqHDm0jjzlmi+J3Sw8IECBAgECJCIwf/3H09Oij74o899x0HstKK3Uukb5nt5sqLdmdGz0jQIAAAQIECBAgQCCzAiotmZ0aHasUgdy9ew877PYY8A47rB656649KmXwxkmAAAECBBok8NlnU2O/gw/+06zcOLJPn5UadCQ7zSmg0jKniJ8JECBAgAABAgQIECAwXwGVlvkS2YBAIQTef39KNDNw4G2RQ4ZsGbnBBssUomFtECBAgACBkhKoqpoZ/T366Lsj11mn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W5kURk2AAIESFZg2LZ278tvf3h+5yCJtI084YavIXL0lHlgqUEClpQIn3ZAJECBAgAABAgQIEGisgEpLYwXtT6DCBV5++YMQGDLkvsijj94scrPNVqhwE8MnQIBA9gW++mp6dPK44/4c2bXrIpHHHtsnskWL5pGWShZQaank2Td2AgQIECBAgAABAgQaKKDS0kA4uxEgMLvA+PEfx4/HHHNP5MEHbxy57barzr6BxwQIECCQEYEvvvg6enLssfdGrrRS58jBg3tH5j5fjweWChdQaanwF4DhEyBAgAABAgQIECDQEAGVloao2YcAgVoF3n7701j/61/fHdmv37qRO+20Vq1bWkmAAAEChRfI1ViOPPLOaHq99ZaOPOywHxW+G1rMuIBKS8YnSPcIECBAgAABAgQIEMiigEpLFmdFnwiUtMD7738e/T/66FRv+dnP1ojca69UdbEQIECAQLEEJk36IprOncfSu3f3eNy//4bF6ox2My6g0pLxCdI9AgQIECBAgAABAgSyKKDSksVZ0ScCZSDw8cdfxigGD071ls03T3duGTDAp3plMLGGQIBAiQn85z/p6o6/+U26H8uuu/aI3HPPniU2Bt0trIBKS2G9tUaAAAECBAgQIECAQFkIqLSUxTQaBIGsCnz22bToWu56Yj17dovHhx66SaQ7Lmd1xvSLAIHyERg79t0YzCmn/DXyqKM2jezTZ6XyGZ6RNJmASkuT0TowAQIECBAgQIAAAQLlK6DSUr5za2QEMiPw5ZfToy8nnHB/5EILtZn1eKvItm1bR1oIECBAIL8CDz74Whzw4ov/HnnqqdtG9uixVH6bcLQyFlBpKePJNTQCBAgQIECAAAECBJpKQKWlqWQdlwCBOQSqqmbGmnPOeSzyv//9JPKMM7aP7NRpwUgLAQIECDRe4JprxsZB7r33lcizz/6/yGWXXbTxh3WEihJQaamo6TZYAgQIECBAgAABAgTyI6DSkh9HRyFAoF4Cuc8C77775djrrLN2iOzevVO9jmBjAgQIEMgJzJz5TTw477zHI19//aPIM89Ux87ZyIYIqLQ0RM0+BAgQIECAAAECBAhUuIBKS4W/AAyfQDEFHn74jWh+xIgnIocN2zpy/fWXLmaHtE2AAIGSEpg6dUb096STHvy+1yed9JN43K6dazN+T+JBvQVylZaau1VXV9dcWbA1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\" width=400/>\n",
    "</center>\n",
    "\n",
    "This function has a minimum at $x = -\\frac{3}{2}$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "-- A demo function with minimum at -3/2\n",
    "function x = x^2 + 3 * x"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, let's take the minimum. We're going to use a step size of $\\alpha = 0.1$, start at $x_0 = 12$, and stop with a tolerance of $1\\times 10^{-4}$:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "-1.4892542376755242"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "let alpha = 1e-1\n",
    "let tolerance = 1e-4\n",
    "let initValue = 12.0\n",
    "unArg $ gradientDescent function (stopCondition function tolerance) alpha (Arg initValue)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Monadic Gradient Descent\n",
    "---\n",
    "\n",
    "Although the above implementation of gradient descent works, we're going to run into problems when our functions are more complicated. For instance, suppose that computing the gradient required a lot of computation, and the computation required communicating with a distributed network of processing nodes. Or suppose that there were some regimes in which the function was non-differentiable, and we wanted to use the `Maybe` type to represent this. In order to support this, we can try to rewrite our class with *monadic* variants of its operations."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    ":set -XMultiParamTypeClasses\n",
    "class Monad m => GradientDescent m a where\n",
    "  -- Type to represent the parameter space.\n",
    "  data Params a :: *\n",
    "  \n",
    "  -- Compute the gradient at a location in parameter space.\n",
    "  grad :: a -> Params a -> m (Params a)\n",
    "  \n",
    "  -- Move in parameter space.\n",
    "  paramMove :: Double        -- Scaling factor.\n",
    "            -> Params a      -- Direction vector.\n",
    "            -> Params a      -- Original location.\n",
    "            -> m (Params a)  -- New location.\n",
    "            \n",
    "            \n",
    "-- Since we've redefined GradientDescent, we need to redefine StopCondition.\n",
    "newtype StopCondition a = StopWhen (Params a -> Params a -> Bool)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In order to utilize this, we're going to have to rewrite our instance to run all computations in a monad. The implementation will look quite familiar, but we won't be able to use as many built-in functions, as they do not have monadic variants in the base packages."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "gradientDescent :: (GradientDescent m a) => \n",
    "                   a                 -- What to optimize.\n",
    "                -> StopCondition a   -- When to stop.\n",
    "                -> Double            -- Step size (alpha).\n",
    "                -> Params a          -- Initial point (x0).\n",
    "                -> m (Params a)      -- Return: Location of minimum.\n",
    "gradientDescent function (StopWhen stop) alpha x0 = do\n",
    "  -- Take the next step.\n",
    "  next <- takeStep x0\n",
    "  \n",
    "  -- If we stop, do so, otherwise recurse.\n",
    "  if stop x0 next\n",
    "     then return next\n",
    "     else gradientDescent function (StopWhen stop) alpha next\n",
    "  where\n",
    "    takeStep params = do\n",
    "      gradients <- grad function params\n",
    "      paramMove (-alpha) gradients params"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's try this for something simple. Suppose we're using our old $f(x) = x^2 + 3x$, but for some reason, we are incapable of differentiating if the function value is below zero. We'll use the `Maybe` monad to represent this - if the parameter to a function is negative, we return `Nothing`, otherwise, we return `Just` the derivative."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "instance (Ord a, Floating a) => GradientDescent Maybe (a -> a) where\n",
    "  -- The parameter for a function is just its argument.\n",
    "  data Params (a -> a) = Arg { unArg :: a }\n",
    "\n",
    "  -- Use numeric differentiation for taking the gradient.\n",
    "  grad f (Arg value) = \n",
    "    if value > 0\n",
    "    then Just $ Arg $ (f value - f (value - epsilon)) / epsilon\n",
    "    else Nothing\n",
    "    where epsilon = 0.0001\n",
    "    \n",
    "  paramMove scale (Arg vec) (Arg old) = Just $ Arg $ old + fromRational (toRational scale) * vec"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's go ahead and try this with the same example as before."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Nothing!"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "stopCondition f tolerance = StopWhen stop\n",
    "  where stop (Arg prev) (Arg cur) =\n",
    "          abs (f prev - f cur) < tolerance  \n",
    "          \n",
    "let x0 = Arg initValue\n",
    "let stopper = stopCondition function tolerance\n",
    "case gradientDescent function stopper alpha x0 of\n",
    "  Just x -> print $ unArg x\n",
    "  Nothing -> putStrLn \"Nothing!\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We saw in the original example that the minimum is at $-\\frac{3}{2}$, so this gradient descent tries to go into the $x < 0$ region - at which point the differentiation returns `Nothing`, and the gradient descent implicitly stops! This monadic gradient descent can be used to implement things such as bounded optimization, optimization that keeps track of the states it went through, optimization that uses networked IO to do its computation, and so on.\n",
    "\n",
    "That's it for now. In the next notebook, I'm going to try implementing conjugate gradient in this same framework."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Haskell",
   "language": "haskell",
   "name": "haskell"
  },
  "language_info": {
   "codemirror_mode": "ihaskell",
   "file_extension": ".hs",
   "mimetype": "text/x-haskell",
   "name": "haskell",
   "pygments_lexer": "Haskell",
   "version": "8.10.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}