{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import torch\n",
    "import numpy as np\n",
    "import matplotlib.pyplot as plt"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Differentiating Through Randomness\n",
    "\n",
    "In the previous notebook we covered the basics of automatic differentiation (AD). However, we focused on differentiating deterministic programs that always produce the same output given the same input. In contrast, ABMs are typically stochastic in nature. In this notebook we will explore how one can employ AD to differentiate through randomness.\n",
    "\n",
    "## Fixed noise distributions\n",
    "\n",
    "Consider the following stochastic model $f$ with input parameter $\\theta$:\n",
    "\n",
    "$$\n",
    "\\begin{align*}\n",
    "    z &\\sim \\mathcal N(1, 2) \\\\\n",
    "    y &= \\theta^2(z+4)\n",
    "\\end{align*}\n",
    "$$\n",
    "\n",
    "Here, $\\mathcal N(\\mu, \\sigma)$ denotes the Normal distribution with mean $\\mu$ and standard deviation $\\sigma^2$. We can implement this model via the following **stochastic program**:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "def f(theta):\n",
    "    z = np.random.normal(1, 2)\n",
    "    return theta**2 * (z + 4)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can now ask what it means to compute the derivative of $f$ with respect to $\\theta$. Recall the standard definition of the derivative for scalar univariate functions:\n",
    "\n",
    "$$\n",
    "\\frac{d f(\\theta)}{d \\theta} =  \\lim_{\\epsilon \\to 0} \\frac{f(\\theta+\\epsilon) - f(\\theta)}{\\epsilon}.\n",
    "$$\n",
    "\n",
    "Note that the difference $f(\\theta+\\epsilon) - f(\\theta)$ is now a random quantity, and as a result it is unclear how we should treat the limit on the right-hand side. Significant research effort has been dedicated to the development of **sample derivatives** which address this issue. Whilst much of what we will discuss here can be framed in terms of sample derivatives, we will take a simpler approach and circumvent this theory for the time being.\n",
    "\n",
    "In practice, we are typically interested in the **average** behaviour of a model, rather than the output associated with a single run. In the case of our example, this means we want to compute the following gradient:\n",
    "\n",
    "$$ \\nabla_{\\theta}\\mathbb{E}_{z \\sim \\mathcal{N}(1,2)}[\\theta^{2}(z+4)]$$\n",
    "\n",
    "This is a specific instance of the more general gradient estimation problem:\n",
    "\n",
    "$$\n",
    "\\nabla_{\\theta}\\mathbb E_{p(z)} [f_\\theta(z)]\n",
    "$$\n",
    "\n",
    "where $f_{\\theta}$ is any function which is deterministic with respect to $z$ and differentiable with respect to $\\theta$. Note that the noise distribution, as specified by the density $p$, does not depend on $\\theta$. We will relax this assumption later on. Let's expand and rewrite this gradient slighty.\n",
    "\n",
    "$$  \\begin{align*}\n",
    "    \\nabla_{\\theta}\\mathbb E_{p(z)} [f_\\theta(z)] &=\n",
    "    \\nabla_{\\theta}\\int p(z)f_\\theta(z)dz \\\\\n",
    "    &= \\int p(z)\\nabla_{\\theta}f_{\\theta}(z)dz \\\\\n",
    "    &= \\mathbb{E}_{z \\sim p(z)}[\\nabla_{\\theta}f_{\\theta}(z)].\n",
    "    \\end{align*}\n",
    "$$\n",
    "\n",
    "Put simply, we find that the gradient of the expectation is equal to the expectation of the gradient. In the second equality, we assumed that $f_{\\theta}(x)$ is *sufficiently regular* so that Leibniz's rule applies. That is, we are allowed to exchange the integral and derivative operators. Almost all the functions used in machine learning satisfy this criteria. If you are curious about the technical details, I recommend checking out [this paper](https://www.jstor.org/stable/2319163), which investigates when the exchange of integration and differentiation is generally permitted.\n",
    "\n",
    "We can now derive a closed-form expression for the gradient in our running example:\n",
    "\n",
    "$$\n",
    "\\nabla_\\theta \\mathbb E_{z \\sim \\mathcal N(1, 2)}\\;\\left[\\theta(z+4)\\right] = \\mathbb E_{z\\sim \\mathcal N(1,2)} \\left[\\nabla_\\theta \\theta^2(z+4)\\right] = 10\\, \\theta\n",
    "$$\n",
    "\n",
    "We can check this is correct numerically by applying finite differences (FD) directly to the expectation. In this case, FD corresponds to the following approximation scheme:\n",
    "\n",
    "$$ \\nabla_{\\theta}\\mathbb E_{p(z)} [f_\\theta(z)] \\approx \\frac{\\mathbb{E}_{z \\sim p(z)}[f_{\\theta + \\epsilon}(z)] - \\mathbb{E}_{z \\sim p(z)}[f_{\\theta}(z)]}{\\epsilon}$$\n",
    "\n",
    "Generally speaking, we can't compute the expectations within this quotient, as this requires integrating over the support of $z$. However, we can unbiasedly estimate them using a standard Monte Carlo approximation:\n",
    "\n",
    "$$ \\nabla_{\\theta}\\mathbb E_{p(z)} [f_\\theta(z)] \\approx \\frac{\\frac{1}{m}\\sum^{m}_{i=1}f_{\\theta + \\epsilon}(z_{i, 1}) - \\frac{1}{m}\\sum_{i=1}^{m}f_{\\theta}(z_{i, 2})}{\\epsilon}, $$\n",
    "\n",
    "where $z_{i, 1} \\sim p$ and $z_{i, 2} \\sim p$. Let's plot a histogram of the gradients returned by the above FD estimator for different values of $\\epsilon$!\n",
    "\n",
    "<!-- However, in many cases, we are actually interested in the derivative of an **average** model realization, not just the derivative of a single run. In other words, we want to take gradients of the form\n",
    "\n",
    "$$\n",
    "\\mathbb E_{z \\sim \\mathcal N(1, 2)}\\;\\left[\\theta^2(z+4)\\right]\n",
    "$$\n",
    "\n",
    "where $p$ is a probability density and $f$ is a (deterministic) simulator with structural parameters $\\theta$. Taking the derivative we have\n",
    "\n",
    "$$\n",
    "\\begin{align*}\n",
    "    \\nabla_\\theta \\mathbb E_{p(z)}\\;\\left[f_\\theta(z)\\right] &= \\nabla_\\theta\\left[\\int_z p(z) f_\\theta(z)\\mathrm{d}z\\right]\\\\\n",
    "                                                             &=  \\int_z p(z)\\left[\\nabla_\\theta f_\\theta(z)\\right]\\mathrm{d} z \\\\\n",
    "                                                             &= \\mathbb E_{p(z)}[\\nabla_\\theta f_\\theta(z)]\n",
    "\\end{align*}\n",
    "$$ -->\n",
    "\n",
    "<!-- so that the gradient of the expectation is the expectation of the gradient.\n",
    "\n",
    "In our considered example, this translates to\n",
    "\n",
    "$$\n",
    "\\mathbb E_{z \\sim \\mathcal N(1, 2)}\\;\\left[\\theta^2(z+4)\\right]\n",
    "$$\n",
    "\n",
    "now we can take the derivative\n",
    "\n",
    "$$\n",
    "\\nabla_\\theta \\mathbb E_{z \\sim \\mathcal N(1, 2)}\\;\\left[\\theta(z+4)\\right] = \\mathbb E_{z\\sim \\mathcal N(1,2)} \\left[\\nabla_\\theta \\theta^2(z+4)\\right] = 10\\, \\theta\n",
    "$$\n",
    "\n",
    "Let's check this result numerically. -->"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "theta = 2.0\n",
    "epsilons = [1.0, 0.5, 0.1]\n",
    "n_samples = 10_000\n",
    "samples_per_epsilon = {epsilon: [] for epsilon in epsilons}\n",
    "for epsilon in epsilons:\n",
    "    for i in range(n_samples):\n",
    "        f_deriv = (f(theta + epsilon) - f(theta)) / (epsilon)\n",
    "        samples_per_epsilon[epsilon].append(f_deriv)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<matplotlib.legend.Legend at 0x17e7b7cd0>"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "image/png": "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",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "fig, ax = plt.subplots()\n",
    "for i, (epsilon, samples) in enumerate(samples_per_epsilon.items()):\n",
    "    ax.hist(\n",
    "        samples,\n",
    "        bins=100,\n",
    "        alpha=0.6,\n",
    "        label=f\"$\\epsilon={epsilon}$\",\n",
    "        density=True,\n",
    "        color=f\"C{i}\",\n",
    "    )\n",
    "ax.axvline(\n",
    "    theta * 10,\n",
    "    color=\"black\",\n",
    "    linestyle=\"dashed\",\n",
    "    linewidth=1,\n",
    "    label=\"Expected derivative\",\n",
    ")\n",
    "ax.legend()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For all $\\epsilon$ tested, the mean of our estimator roughly corresponds to the true analytical gradient derived above, which is represented by the vertical dashed line. We also notice another striking pheneomena. As $\\epsilon \\to 0$, the variance of our estimator increases. Why is this? \n",
    "\n",
    "Recall the Monte Carlo estimate we employed to approximate FD:\n",
    "\n",
    "$$ \\sum^{m}_{i=1}f_{\\theta + \\epsilon}(z_{i, 1}) - \\sum_{i=1}^{m}f_{\\theta}(z_{i, 2}) $$\n",
    "\n",
    "This is the only random quantity and hence the source of all the variance. When we divide through by $\\epsilon$ this term is scaled up, dramatically increasing its variance. The smaller the $\\epsilon$, the worse this effect will be. As we saw in the last notebook, sometimes we need set $\\epsilon$ to a small value to get a good approximation of the gradient. As a result, we can't rely on increasing $\\epsilon$ as a strategy to reduce variance. Our only option is to reduce the initial variance of the Monte Carlo term above. \n",
    "\n",
    "The simplest way to reduce variance is increasing the number of samples $m$ used in each Monte-Carlo approximation. However, this involves more function evaluations, which in turn may be computationally expensive, especially if $f$ is an ABM. Alternatively, one can reduce variance by coupling the noise terms used in each Monte Carlo sum. That is, setting $z_{i, 1} = z_{i, 2}$. This reduces noise introduced by evaluating $f$ at different sample points when taking the difference between sums. However, syncrhonising the noise terms in practice can be difficult, and is not as simple as fixing a random seed!\n",
    "\n",
    "Next, let's consider the following approximation of the derivative:\n",
    "\n",
    "$$ \\frac{1}{m}\\sum^{m}_{i=1}\\nabla_{\\theta}f_{\\theta}(z_{i}), $$\n",
    "\n",
    "where each gradient term is computed using AD instead of FD. Note that we no longer need to take a difference of terms, nor do we need to divide by a small value. As a result, we should expect the variance of this estimator to be far lower. Let's plot its corresponding histogram and check!\n",
    "\n",
    "<!-- What is going on? The smaller $\\epsilon$ is, the variance of our estimator is going $\\to \\infty$! \n",
    "\n",
    "This is caused by the fact that the two function calls $X(p)$ and $X(p+\\epsilon)$ are uncorrelated (they have a different random seed) and so even calling the program for very similar values of $p$ can cause large differences. \n",
    "\n",
    "Nonetheless, the finite differences method gives an unbiased estimator.\n",
    "\n",
    "This issue is not present in automatic differentiation engines, since they only require one evaluation of the model. -->"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "def f_torch(theta):\n",
    "    z = torch.distributions.Normal(1.0, 2.0).sample()\n",
    "    return theta**2 * (z + 4)\n",
    "\n",
    "\n",
    "n_samples = 10_000\n",
    "samples_autograd = []\n",
    "for i in range(n_samples):\n",
    "    theta = torch.tensor(2.0, requires_grad=True)\n",
    "    f_torch(theta).backward()\n",
    "    samples_autograd.append(theta.grad)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<matplotlib.legend.Legend at 0x17ec2cac0>"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "image/png": "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mjt3rubPn6+vv/5aTz31lL744otzPjiybdu2cjgceumll/TNN9/ob3/7m5588kmfNg899JC+/vprjR07Vtu3b6+zbpiPwALAklLGfejzwqU1d+5cpaenKyYmpta6u+++Wxs2bNC3336rd955R8uXL1e3bt307rvvasqUKbXa9u/fXzfddJPi4+P17rvvymaz6YMPPlDz5s3105/+VOnp6br88su1ePFi73aDBw/W+PHjNWbMGPXs2VO7du3SsGHDzvkgvfj4eM2bN09LlixRly5dNH36dP3pT3/yadO2bVv95S9/0dKlS9W9e3fNmTNHzzzzTMM7C5eEzWgE97guKytTTEyMSktLFR0dbXY5AC6yU4Gk5thBHStcpqietys4Ks6njVWuGjp58qR27dqldu3aNfiptfjez372MzmdTr399ttml4JzONPnvj7f30y6BWAZwVFxat5vmNllwATHjx/XnDlzlJGRIbvdrnfffVeffPKJcnNzzS4NfkJgAWAZnsrjqireIUfClQoKjTC7HPiRzWbT8uXL9fTTT+vkyZPq2LGj/vKXvyg9Pd3s0uAnBBYAllF9ZJ+K350g59AZCnVeeVH2Wdf8F6ucXmpKwsPD9cknn5hdBkzEpFsAABDwCCwAACDgEVgAAEDAI7AAsAybPVj2yJay2Zl+BzQ1/K0HYBmO+BS1GTnf7DIAmKBBIyyzZ89WSkqKwsLClJqaWusZDKdbsmSJOnXqpLCwMHXr1k3Lly/3WT9s2DDZbDafV//+/RtSGgAAaITqHVgWL16s7OxsTZ48WYWFherevbsyMjJqPUzqlNWrV2vQoEEaMWKENm7cqMzMTGVmZmrLli0+7fr376/9+/d7X++++27DjghAo1V1YLe+nT1UVQd2m10Kmogbb7xRo0ePrtc2U6ZMUY8ePS74vefNm6fY2NgL3s+57N69WzabrdaDKgNNvQPL888/rwceeEDDhw9Xly5dNGfOHEVEROiNN96os/3MmTPVv39/jR07Vp07d9aTTz6pnj17atasWT7tQkND5XQ6va/mzZs37IgANFqGu0bu8kMy3DVml9Ik1TUaHogj4g0JGYEoKytL//nPfy7qPocNG6bMzEyfZcnJydq/f7+6du16Ud/rYqvXHJaqqioVFBRo/Pjx3mVBQUFKT09Xfn5+ndvk5+crOzvbZ1lGRoaWLl3qs2zlypVq1aqVmjdvrptvvllPPfWUWrZsWec+KysrVVlZ6f25rKysPocBwESn36iNm7RZS//+/fXmm2/6LAsNDTWpmsarurpa4eHhCg8Pv+TvZbfb5XQ6L/n7XKh6jbAcPHhQbrdbCQkJPssTEhLkcrnq3Mblcp2zff/+/fXWW28pLy9Pzz77rFatWqXbbrtNbre7zn1OmzZNMTEx3ldycnJ9DgNAADn9qcs8eTmwnT4a/uMR8ZUrV8rhcOif//ynt/1zzz2nVq1aqbi4WNL3ox+PPPKIHnnkEcXExCguLk5PPPGEfvwc3srKSo0ZM0atW7dWs2bNlJqaqpUrV/rU8fnnn+vGG29URESEmjdvroyMDB05ckTDhg3TqlWrNHPmTO8I0O7duyVJW7Zs0W233abIyEglJCTo/vvv18GDB737rKio0JAhQxQZGanExETl5OScV59Mnz5dCQkJioqK0ogRI3Ty5MlabV5//XV17txZYWFh6tSpk/73f//Xu+7UKZnFixerX79+CgsL04IFC3xOCf3nP/+RzWbTtm3bfPb7wgsv6IorrpAkud1ujRgxQu3atVN4eLg6duyomTNnettOmTJF8+fP1wcffODtm5UrV/qcEvJ4PGrTpo1efvlln/fZuHGjgoKCtGfPHknS0aNH9etf/1rx8fGKjo7WzTffrM2bN59XfzVUQFzWfO+99+rnP/+5unXrpszMTC1btkzr16+v9QE9Zfz48SotLfW+9u7d69+CAQC1nDoVc//996u0tFQbN27UE088oddff93nF9f58+crODhY69at08yZM/X888/r9ddf965/5JFHlJ+fr0WLFumLL77QPffco/79++vrr7+WJG3atEm33HKLunTpovz8fP3rX//SHXfcIbfbrZkzZyotLU0PPPCAd05kcnKyjh49qptvvlnXXHONNmzYoBUrVqi4uFgDBw70vu/YsWO1atUqffDBB/r444+1cuVKFRYWnvWY33vvPU2ZMkXPPPOMNmzYoMTERJ8wIkkLFizQpEmT9PTTT2vr1q165pln9MQTT2j+fN8r3saNG6dRo0Zp69atysjI8FnXoUMH9e7dWwsWLKi171/+8peS5A0bS5Ys0VdffaVJkyZpwoQJeu+99yRJY8aM0cCBA33mjPbt29dnf0FBQRo0aJAWLlxY631+8pOf6LLLLpMk3XPPPSopKdHf//53FRQUqGfPnrrlllt0+PDhs/bXhajXKaG4uDjZ7XZvUj6luLj4jMNJTqezXu0l6fLLL1dcXJx27NihW265pdb60NBQhiABk5nxDJ6Q5klKGPSMQponXdL3McupL5Efa968udq1a6eTJ0/qq6++qrVNz549JUnbt29XRUWFz7qUlBS1aNFCBw4cqPWLXVRUlNq3b1/vGpctW6bIyEifZRMmTNCECRMkSU899ZRyc3P14IMPasuWLRo6dKh+/vOf+7RPTk7WCy+8IJvNpo4dO+rLL7/UCy+8oAceeEBFRUV68803VVRUpKSk7/8/jxkzRitWrNCbb76pZ555Rs8995x69+7tEwyuuuoq758dDociIiJ8vmdmzZqla665Rs8884x32RtvvKHk5GT95z//UVJSkubOnat33nnH+70zf/58tWnT5qz9MWPGDI0YMUIjRozwHv8nn3ziM8oyefJk5eTk6K677pIktWvXTl999ZVeeeUVDR061Ntu9OjR3jZ1GTx4sGbNmqUnn3xS0vejLgUFBXrnnXckSSEhIZo6daq3fbt27ZSfn6/33ntPAwcOVGRkpMLDw1VZWXnW7+DBgwcrJydHRUVFatu2rTwejxYtWqSJEydKkv71r39p3bp1Kikp8X4X/+lPf9LSpUv15z//WQ8++OBZ+6yh6hVYHA6HevXqpby8PO+kHY/Ho7y8PD3yyCN1bpOWlqa8vDyfCVC5ublKS0s74/t8++23OnTokBITE+tTHoBGLig0QmFtr77k72PWPJtXXnnF5wtH+v7L45133tG3336rXr161drm1KmUYcOGac2aNT7r3n77bd1333167733av0bfeutt+qjjz6qd4033XRTrdMFLVq08P7Z4XBowYIFuvrqq3XZZZfphRdeqLWP6667TjabzftzWlqacnJy5Ha79eWXX8rtdqtDhw4+21RWVnrnNW7atEn33HNPverevHmzPv3001phS5J27typEydOqKqqSqmpqT7H1bFjx7Pud+vWrXrooYd8lqWlpenTTz+V9P1ppp07d2rEiBF64IEHvG1qamoUExPjs13v3r3P+l733nuvxowZozVr1ui6667TggUL1LNnT3Xq1MnbZvbs2XrjjTdUVFTkPab6XrHUo0cPde7cWQsXLtS4ceO0atUqlZSUePt88+bNKi8vrzXP9MSJE9q5c2e93qs+6n3juOzsbA0dOlS9e/dWnz59NGPGDFVUVGj48OGSpCFDhqh169aaNm2aJGnUqFHq16+fcnJyNGDAAC1atEgbNmzQq6++KkkqLy/X1KlTdffdd8vpdGrnzp16/PHHdeWVV9YaEgPQtNUcO6hjhcsU1fN2BUfFmV3ORfeb3/ym1mjEqfkhbdq0UUFBwRm3nTdvXp0jLJI0cODAWr8kRkVFNajGZs2a6corz/6k7NWrV0uSDh8+rMOHD6tZs2bnvf/y8nLZ7XYVFBTIbrf7rDsVNhoyEbW8vFx33HGHnn322VrrEhMTtWPHjnrv83zfV5Jee+01nzAkqdbxnaufnE6nbr75Zi1cuFDXXXedFi5cqIcffti7ftGiRRozZoxycnKUlpamqKgo/fGPf9TatWvrXffgwYO9gWXhwoXq37+/N6CUl5crMTGxzmkbl/Iy7HoHlqysLB04cECTJk2Sy+VSjx49tGLFCu/5yaKiIgUF/TA1pm/fvlq4cKEmTpyoCRMmqH379lq6dKn38im73a4vvvhC8+fP19GjR5WUlKRbb71VTz75JKd9APhwVxxV2Zo/K6Lj9Y0ysCQmJp5xZDksLMx7+qcuZxsJiI+PV3x8/AXXdz527typ3//+93rttde0ePFiDR06VJ988onP98LpX6Br1qxR+/btZbfbdc0118jtdqukpEQ33HBDne9x9dVXKy8vr9Zo1CkOh6PWRRs9e/bUX/7yF6WkpCg4uPZX3xVXXKGQkBCtXbtWbdu2lSQdOXJE//nPf9SvX78zHm/nzp21du1aDRkyxOd4TklISFBSUpK++eYbDR48+Iz7OV+DBw/W448/rkGDBumbb77Rvffe6133+eefq2/fvvrtb3/rXXb6iEddfVOXX/7yl5o4caIKCgr05z//WXPmzPGu69mzp1wul4KDg72h2B8adGv+UzO861JX4rrnnnvOOHwXHh7eoGFJAID/VVZW1roqNDg4WHFxcXK73brvvvuUkZGh4cOHq3///urWrZtycnI0duxYb/uioiJlZ2frN7/5jQoLC/XSSy95r8jp0KGDBg8erCFDhignJ0fXXHONDhw4oLy8PF199dUaMGCAxo8fr27duum3v/2tHnroITkcDn366ae65557FBcXp5SUFK1du1a7d+9WZGSkWrRooZEjR+q1117ToEGD9Pjjj6tFixbasWOHFi1apNdff12RkZEaMWKExo4dq5YtW6pVq1b6f//v//kErbqMGjVKw4YNU+/evfWTn/xECxYs0L///W9dfvnl3jZTp07V7373O8XExKh///6qrKzUhg0bdOTIkVq3/TiXu+66Sw8//LAefvhh3XTTTd55PpLUvn17vfXWW/roo4/Url07vf3221q/fr3atWvnbZOSkqKPPvpI27dvV8uWLWudlvpxu759+2rEiBFyu90+I3/p6elKS0tTZmamnnvuOXXo0EH79u3Thx9+qF/84hfnPLXVUAFxlRAAwBpWrFjhHQk69br++uslSU8//bT27NmjV155RdL3I0avvvqqJk6c6HPJ65AhQ3TixAn16dNHI0eO1KhRo3wmar755psaMmSIHnvsMXXs2FGZmZlav369d+SjQ4cO+vjjj7V582b16dNHaWlp+uCDD7wjJ2PGjJHdbleXLl0UHx/vncD7+eefy+1269Zbb1W3bt00evRoxcbGekPJH//4R91www264447lJ6eruuvv77OeUM/lpWVpSeeeEKPP/64evXqpT179vicppGkX//613r99df15ptvqlu3burXr5/mzZvnEyTOV1RUlO644w5t3ry51ojNb37zG911113KyspSamqqDh065DPaIkkPPPCAOnbsqN69eys+Pl6ff/75Gd9r8ODB2rx5s37xi1/4nIaz2Wxavny5fvrTn2r48OHq0KGD7r33Xu3Zs6fWbUwuJpvx44vfLaqsrEwxMTEqLS1VdHS02eUATUJDrxI6n/usnL6fU9tUunbINX+0nENnKNR55Vm3OV8NqedCnDx5Urt27VK7du0UFhZ20fZrFTfeeKN69OihGTNmmF0K/OhMn/v6fH8zwgLAMuzh0Yq8+lbZw/nFBGhqGjSHBQDMEBzTSi1v+53ZZQAwAYEFwEVzqe9f4qmuVM1Rl4JjnQoK4SpCKzrTHcyBc+GUEADLqD60V/vfGKnqQzyOA2hqCCwAACDgEVgAwASN4AJN4LxdjM87gQUA/CgkJESSdPz4cZMrAfzn1Of91Oe/IZh0C8AybDabZA/2eXCe1djtdsXGxqqkpESSFBERYenjAc7GMAwdP35cJSUlio2NrfX8pPogsACwDEfCFbpszFKzy7hgTqdTkryhBWjsYmNjvZ/7hiKwAICf2Ww2JSYmqlWrVqqu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bA0dOlS9e/dWnz59NGPGDFVUVGj48OGSpCFDhqh169aaNm2aJGnUqFHq16+fcnJyNGDAAC1atEgbNmzQq6++Kkmy2WwaPXq0nnrqKbVv3957WXNSUpIyMzMv3pECAADLqndgycrK0oEDBzRp0iS5XC716NFDK1as8E6aLSoqUlDQDwM3ffv21cKFCzVx4kRNmDBB7du319KlS733YJGkxx9/XBUVFXrwwQd19OhRXX/99VqxYkVA34MlNDRUkydPrnVqCr7op/NDP50f+un80E/nh346P4HST/W+DwsAAIC/NejW/AAAAP5EYAEAAAGPwAIAAAIegQUAAAQ8AksDPP300+rbt68iIiLOeMO6oqIiDRgwQBEREWrVqpXGjh2rmpoa/xYaAGbPnq2UlBSFhYUpNTVV69atM7skU3322We64447lJSUJJvN5n2m1imGYWjSpElKTExUeHi40tPT9fXXX5tTrImmTZuma6+9VlFRUWrVqpUyMzO1fft2nzYnT57UyJEj1bJlS0VGRuruu++udZPKxu7ll1/W1Vdf7b2hV1pamv7+979719NHtU2fPt17O41T6KfvTZkyRTabzefVqVMn73qz+4nA0gBVVVW655579PDDD9e53u12a8CAAaqqqtLq1as1f/58zZs3T5MmTfJzpeZavHixsrOzNXnyZBUWFqp79+7KyMhQSUmJ2aWZpqKiQt27d9fs2bPrXP/cc8/pxRdf1Jw5c7R27Vo1a9ZMGRkZOnnypJ8rNdeqVas0cuRIrVmzRrm5uaqurtatt96qiooKb5vf//73+r//+z8tWbJEq1at0r59+3TXXXeZWLX/tWnTRtOnT1dBQYE2bNigm2++WXfeeaf+/e9/S6KPTrd+/Xq98soruvrqq32W008/uOqqq7R//37v61//+pd3nen9ZKDB3nzzTSMmJqbW8uXLlxtBQUGGy+XyLnv55ZeN6Ohoo7Ky0o8VmqtPnz7GyJEjvT+73W4jKSnJmDZtmolVBQ5Jxvvvv+/92ePxGE6n0/jjH//oXXb06FEjNDTUePfdd02oMHCUlJQYkoxVq1YZhvF9v4SEhBhLlizxttm6dashycjPzzerzIDQvHlz4/XXX6ePTnPs2DGjffv2Rm5urtGvXz9j1KhRhmHwWfqxyZMnG927d69zXSD0EyMsl0B+fr66devm8wTqjIwMlZWVeX/zaeyqqqpUUFCg9PR077KgoCClp6crPz/fxMoC165du+RyuXz6LCYmRqmpqU2+z0pLSyVJLVq0kCQVFBSourrap686deqktm3bNtm+crvdWrRokSoqKpSWlkYfnWbkyJEaMGCAT39IfJZO9/XXXyspKUmXX365Bg8erKKiIkmB0U+WfFpzoHO5XD5hRZL3Z5fLZUZJfnfw4EG53e46+2Hbtm0mVRXYTn026uqzpvK5qYvH49Ho0aP1k5/8xHuHbJfLJYfDUWsOWVPsqy+//FJpaWk6efKkIiMj9f7776tLly7atGkTffRfixYtUmFhodavX19rHZ+lH6SmpmrevHnq2LGj9u/fr6lTp+qGG27Qli1bAqKfCCz/NW7cOD377LNnbbN161afCUgALr2RI0dqy5YtPufS8YOOHTtq06ZNKi0t1Z///GcNHTpUq1atMrusgLF3716NGjVKubm5Af24l0Bw2223ef989dVXKzU1VZdddpnee+89hYeHm1jZ9wgs//XYY49p2LBhZ21z+eWXn9e+nE5nrathTs2kdjqdDarPauLi4mS322vNIC8uLm4yfVBfp/qluLhYiYmJ3uXFxcXq0aOHSVWZ65FHHtGyZcv02WefqU2bNt7lTqdTVVVVOnr0qM9vfE3x8+VwOHTllVdKknr16qX169dr5syZysrKoo/0/amMkpIS9ezZ07vM7Xbrs88+06xZs/TRRx/RT2cQGxurDh06aMeOHfrZz35mej8xh+W/4uPj1alTp7O+HA7Hee0rLS1NX375pc/VMLm5uYqOjlaXLl0u1SEEFIfDoV69eikvL8+7zOPxKC8vT2lpaSZWFrjatWsnp9Pp02dlZWVau3Ztk+szwzD0yCOP6P3339c//vEPtWvXzmd9r169FBIS4tNX27dvV1FRUZPrq9N5PB5VVlbSR/91yy236Msvv9SmTZu8r969e2vw4MHeP9NPdSsvL9fOnTuVmJgYGJ8nv0ztbWT27NljbNy40Zg6daoRGRlpbNy40di4caNx7NgxwzAMo6amxujatatx6623Gps2bTJWrFhhxMfHG+PHjze5cv9atGiRERoaasybN8/46quvjAcffNCIjY31uXqqqTl27Jj38yLJeP75542NGzcae/bsMQzDMKZPn27ExsYaH3zwgfHFF18Yd955p9GuXTvjxIkTJlfuXw8//LARExNjrFy50ti/f7/3dfz4cW+bhx56yGjbtq3xj3/8w9iwYYORlpZmpKWlmVi1/40bN85YtWqVsWvXLuOLL74wxo0bZ9hsNuPjjz82DIM+OpMfXyVkGPTTKY899pixcuVKY9euXcbnn39upKenG3FxcUZJSYlhGOb3E4GlAYYOHWpIqvX69NNPvW12795t3HbbbUZ4eLgRFxdnPPbYY0Z1dbV5RZvkpZdeMtq2bWs4HA6jT58+xpo1a8wuyVSffvppnZ+doUOHGobx/aXNTzzxhJGQkGCEhoYat9xyi7F9+3ZzizZBXX0kyXjzzTe9bU6cOGH89re/NZo3b25EREQYv/jFL4z9+/ebV7QJfvWrXxmXXXaZ4XA4jPj4eOOWW27xhhXDoI/O5PTAQj99Lysry0hMTDQcDofRunVrIysry9ixY4d3vdn9ZDMMw/DPWA4AAEDDMIcFAAAEPAILAAAIeAQWAAAQ8AgsAAAg4BFYAABAwCOwAACAgEdgAQAAAY/AAgAAAh6BBQAABDwCCwAACHgEFgAAEPAILAAAIOD9/0J+iqG7Ue4XAAAAAElFTkSuQmCC",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "fig, ax = plt.subplots()\n",
    "ax.hist(\n",
    "    samples_autograd, bins=100, label=\"Autograd\", density=True, color=\"C0\"\n",
    ")\n",
    "ax.axvline(\n",
    "    10*theta.item(), color=\"black\", linestyle=\"dashed\", linewidth=1, label=\"Expected derivative\"\n",
    ")\n",
    "ax.legend()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As we can see, using AD leads to much lower variance compared to using FD!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Parameterizable Noise\n",
    "\n",
    "So far, we have assumed that the randomness of our model, described by $p(z)$, did not depend on the structural parameters $\\theta$ that we want to differentiate with respect to. However, in most ABMs this assumption does not hold. For instance, consider an epdiemlogical model where agents become infected with some probability. This probability may depend on structural parameters representing factors that we are interested in calibrating, such as disease contagiousness or social distancing measures.\n",
    "\n",
    "In such cases, we need to estimate the following gradient:\n",
    "\n",
    "$$\n",
    "\\nabla_\\theta\\mathbb E_{p_\\theta(z)} [f_\\theta(z)],\n",
    "$$\n",
    "\n",
    "where $p$ is parameterized by $\\theta$. Let's expand this gradient just like we did in the previous section.\n",
    "\n",
    "$$\n",
    "\\begin{align*}\n",
    "    \\nabla_\\theta\\mathbb E_{p_\\theta(z)} [f_\\theta(z)] &= \\nabla_\\theta \\left[ \\int_z p_\\theta(z) f_\\theta(z) \\mathrm{d}z\\right]\\\\\n",
    "                                                       &= \\int_z \\nabla_\\theta\\left[p_\\theta(z) f_\\theta(z)\\right] \\mathrm{d}z\\\\\n",
    "                                                       &= \\int_z f_\\theta(z)\\nabla_\\theta p_\\theta(z)\\mathrm{d} z + \\int_z p_\\theta(z) \\nabla_\\theta f_\\theta(z)\\mathrm{d}z\\\\\n",
    "                                                       &= \\int_z f_\\theta(z) \\nabla_\\theta p_\\theta(z) \\mathrm{d} z + \\mathbb E_{p_\\theta(z)} \\left[\\nabla_\\theta f_\\theta(z)\\right]\n",
    "\\end{align*}\n",
    "$$\n",
    "\n",
    "Notice that we now have an additional term, $\\int_z f_\\theta(z) \\nabla_\\theta p_\\theta(z) \\mathrm{d} z$, that prevents us from commuting the gradient and the expectation. Hence, in general, **the gradient of the expectation is not the expectation of the gradient** when our structural parameters parameterize the randomness. In the next subsection, we will introduce a trick for estimating the gradient when $p$ is continuous.\n",
    "\n",
    "\n",
    "### The Reparameterization Trick\n",
    "\n",
    " <!-- To circumvent this, we introduce the [reparameterization trick](https://arxiv.org/pdf/1312.6114.pdf).  -->\n",
    " \n",
    " <!-- For now, we assume that $p$ describes a continuous.  -->\n",
    " \n",
    " <!-- Continuous distributions have a property that allows an indirect way of sampling from them. One is direct sampling -->\n",
    "\n",
    " Roughly speaking, there are two basic ways to sample from a continuous distribution $p_{\\theta}$. We may sample directly from $p_{\\theta}$:\n",
    "\n",
    "$$ x \\sim p_\\theta(x), $$\n",
    "\n",
    "or we can sample auxillary noise $\\varepsilon$ from another distribution $q$, and apply a deterministic transform $g_{\\theta}$ so that the resulting output is distributed according to $p_{\\theta}$. This is broadly known as indirect sampling,\n",
    "\n",
    "$$  x = g_{\\theta}(\\varepsilon), \\quad \\varepsilon \\sim q(\\varepsilon) $$\n",
    "\n",
    "<!-- where $g$ is a deterministic path that maps parameter-free noise ($\\epsilon$) to $x$.  -->\n",
    "\n",
    "When $q$ is the standard uniform density, this procedure corresponds to inverse transform sampling, and $g$ corresponds to the inverse CDF function associated with $p_{\\theta}$.  However, sometimes there are better choices for $q$ that make $g_{\\theta}$ easier to compute. For instance, to sample from the normal distribution $\\mathcal N(\\mu, \\sigma^2)$, we can use the standard normal distribution $\\mathcal{N}(0, 1)$ to sample auxillary noise:\n",
    "\n",
    "$$ \\varepsilon \\sim \\mathcal N(0, 1), \\quad x  =  \\mu + \\sigma \\varepsilon $$\n",
    "\n",
    "\n",
    "So why do we care about indirect sampling? Since indirect and direct sampling produce the same distribution we clearly have:\n",
    "\n",
    "$$\n",
    "\\mathbb{E}_{p_{\\theta}(z)}[f_{\\theta}(z)] = \\mathbb{E}_{\\varepsilon \\sim q(\\varepsilon)}[f_{\\theta}(g_{\\theta}(\\varepsilon))].\n",
    "$$\n",
    "\n",
    "Thus, taking gradients we have\n",
    "$$\n",
    "\\nabla_{\\theta}\\mathbb{E}_{p_{\\theta}(z)}[f_{\\theta}(z)] = \\nabla_{\\theta}\\mathbb{E}_{\\varepsilon \\sim q(\\varepsilon)}[f_{\\theta}(g_{\\theta}(\\varepsilon))] \n",
    "$$\n",
    "\n",
    "Note that the sampling distribution $q(\\varepsilon)$ does not depend on $\\theta$. Thus, if $g_{\\theta}$ and $f_{\\theta}$ are both differentiable and sufficiently regular, we can exchange the gradient and expectation operators on the right-hand side, just as we had done in the previous section!\n",
    "\n",
    "$$\n",
    "\\nabla_{\\theta}\\mathbb{E}_{p_{\\theta}(z)}[f_{\\theta}(z)] = \\mathbb{E}_{\\varepsilon \\sim q(\\varepsilon)}[\\nabla_{\\theta}f_{\\theta}(g_{\\theta}(\\varepsilon))] \n",
    "$$\n",
    "\n",
    "Proceeding as before, we can now construct an AD-based Monte Carlo estimator for the gradient of interest:\n",
    "\n",
    "$$\n",
    "\\nabla_{\\theta}\\mathbb{E}_{p_{\\theta}(z)}[f_{\\theta}(z)] \\approx \\frac{1}{m}\\sum^{m}_{i=1}\\nabla_{\\theta}f_{\\theta}(g_{\\theta}(\\varepsilon_{i})), \\quad \\varepsilon_{i} \\sim q\n",
    "$$\n",
    "\n",
    "This method of gradient computation is known as the [reparameterization trick](https://arxiv.org/pdf/1312.6114.pdf) within the machine learning community, and was originally exploited to train VAEs. Indirect sampling effectively *reparameterizes* the noise variable $z$ so that it not longer depends on the structural parameters $\\theta$.\n",
    "\n",
    "Let's study an example. Consider the following model:\n",
    "\n",
    "$$\n",
    "\\begin{align*}\n",
    "z \\sim \\mathcal N(\\theta, 4) \\\\\n",
    "y = \\theta^2 (4 + z)\n",
    "\\end{align*}\n",
    "$$\n",
    "\n",
    "We can reparameterize the noise variable $z$ using the standard normal distribution:\n",
    "\n",
    "$$\n",
    "\\begin{align*}\n",
    "\\varepsilon \\sim \\mathcal{N}(0, 1) \\\\\n",
    "y = \\theta^2 (4 + \\theta + 2\\varepsilon)\n",
    "\\end{align*}\n",
    "$$\n",
    "\n",
    "We can now compute the gradient:\n",
    "\n",
    "$$\n",
    "\\mathbb E_{\\epsilon \\sim \\mathcal N(0,1)}\\left[ \\nabla_\\theta \\theta^2 (4 + \\theta + 2\\epsilon )\\right ] =\\mathbb E_{\\epsilon \\sim \\mathcal N(0,1)}[8\\theta + 3\\theta^2 + 4\\theta\\epsilon] = 8\\theta + 3\\theta^2\n",
    "$$\n",
    "\n",
    "<!-- What have we accomplished with this? We have untangled the \"random\" part of the distribution from the part that depends on the parameters.\n",
    "This allows us to re-formulate (1) as\n",
    "\n",
    "$$\n",
    "\\nabla_\\theta\\mathbb E_{p_\\theta(z)} [f_\\theta(z)] = \\nabla_\\theta\\mathbb E_{p(\\varepsilon)}\\left[f(g_\\theta(\\varepsilon, x))\\right],\n",
    "$$\n",
    "\n",
    "where now we can move the gradient inside,\n",
    "\n",
    "$$\n",
    "\\nabla_\\theta\\mathbb E_{p(\\epsilon)}\\left[f(g_\\theta(\\epsilon, x))\\right] = \\mathbb E_{p(\\varepsilon)}\\left[\\nabla_\\theta f(g_\\theta(\\varepsilon, x))\\right].\n",
    "$$\n",
    "\n",
    "So we have been able to transform the gradient of the expectation to the expectation of the gradient. This can be computed provided that $f$ and $g$ are differentiable. This expectation can now be estiated by Monte Carlo,\n",
    "\n",
    "$$\n",
    "\\mathbb E_{p(\\epsilon)}\\left[\\nabla_\\theta f(g_\\theta(\\epsilon, x))\\right] \\approx \\frac{1}{N} \\sum_{i=1}^N \\nabla_\\theta f(g_\\theta(\\epsilon_i, x_i)).\n",
    "$$ -->\n",
    "\n",
    "<!-- Let's see an example. Consider the program with input $\\theta$\n",
    "\n",
    "$$\n",
    "\\begin{align*}\n",
    "z \\sim \\mathcal N(\\theta, 4) \\\\\n",
    "y = \\theta^2 (4 + z)\n",
    "\\end{align*}\n",
    "$$\n",
    "\n",
    "The expected answer is\n",
    "\n",
    "$$\n",
    "\\mathbb E_{\\epsilon \\sim \\mathcal N(0,1)}\\left[ \\nabla_\\theta \\theta^2 (4 + \\theta + 2\\epsilon )\\right ] =\\mathbb E_{\\epsilon \\sim \\mathcal N(0,1)}[8\\theta + 3\\theta^2 + 4\\theta\\epsilon] = 8\\theta + 3\\theta^2\n",
    "$$\n",
    "\n",
    "Let's first check both the parameterized and unreparameterized version: -->"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's now explore how the reparameterization trick is implemented in PyTorch. Below, we define two stochatsic programs. The program `f_torch_norep` implements the previous example without performing any explicit reparameterization by sampling $z$ directly from `torch.distributions.Normal(theta, 2.0)`. The program `f_torch` explicitly reparameterizes by first sampling from `torch.distributions.Normal(0,1)` and then constructing `z`. Let's plot the density of these two estimators."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "def f_torch_norep(theta):\n",
    "    z = torch.distributions.Normal(theta, 2.0).sample()\n",
    "    return theta**2 * (z + 4)\n",
    "\n",
    "\n",
    "def f_torch(theta):\n",
    "    epsilon = torch.distributions.Normal(0, 1).sample()\n",
    "    z = theta + epsilon * 2\n",
    "    return theta**2 * (4 + z)\n",
    "\n",
    "\n",
    "rep_samples = []\n",
    "norep_samples = []\n",
    "n_samples = 2_000\n",
    "theta_value = 2.0\n",
    "analytical_result = 8 * theta_value + 3 * theta_value**2\n",
    "for i in range(n_samples):\n",
    "    theta = torch.tensor(theta_value, requires_grad=True)\n",
    "    f_torch_norep(theta).backward()\n",
    "    norep_samples.append(theta.grad.item())\n",
    "    theta = torch.tensor(theta_value, requires_grad=True)\n",
    "    f_torch(theta).backward()\n",
    "    rep_samples.append(theta.grad.item())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<matplotlib.legend.Legend at 0x17ecd80d0>"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "image/png": "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",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "fig, ax = plt.subplots()\n",
    "ax.hist(\n",
    "    norep_samples,\n",
    "    bins=100,\n",
    "    alpha=0.35,\n",
    "    label=\"No Reparametrization\",\n",
    "    density=True,\n",
    "    color=\"C0\",\n",
    ")\n",
    "ax.hist(\n",
    "    rep_samples,\n",
    "    bins=100,\n",
    "    alpha=0.35,\n",
    "    label=\"Reparametrization\",\n",
    "    density=True,\n",
    "    color=\"C1\",\n",
    ")\n",
    "ax.axvline(\n",
    "    analytical_result,\n",
    "    color=\"black\",\n",
    "    linestyle=\"dashed\",\n",
    "    linewidth=1,\n",
    "    label=\"Expected derivative\",\n",
    ")\n",
    "ax.legend()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As we can see, `f_torch` is an unbiased estimator of the analytical gradient as it explicitly employs the reparameterization trick. In contrast,`f_torch_norep` is biased. This is because `.sample()` does not implicitly perform the reparamterization trick. Instead, gradient propoagation stops at `.sample()`. Thankfully, PyTorch implements the shortcut function `.rsample` which implicitly performs the reparameterization trick for us so we do not need to implement it over and over again. Below we perform the reparameterization trick for our example implicitly via `.rsample`. Observe that an accurate estimate for the analytical gradient is returned.\n",
    "\n",
    "<!-- As we can see, we need to be careful, because PyTorch may not be applying the reparameterization trick and we may obtain the wrong results!!\n",
    "\n",
    "By calling `dist.sample()` the gradient propagation stops and so we obtain the wrong result. Thankfully, PyTorch has a shortcut to implement the reparameterization trick for us so we don't have to do it manually. This can be done by using the `.rsample()` method. -->"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "27.927927017211914 ~ 28.0\n"
     ]
    }
   ],
   "source": [
    "def f_torch(theta):\n",
    "    z = torch.distributions.Normal(theta, 2.0).rsample()\n",
    "    return theta**2 * (z + 4)\n",
    "\n",
    "\n",
    "rep = (\n",
    "    sum([torch.func.grad(f_torch)(torch.tensor(2.0)) for i in range(n_samples)])\n",
    "    / n_samples\n",
    ")\n",
    "print(f\"{rep} ~ {analytical_result}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!-- # A note on reinforcement learning\n",
    "\n",
    "Recall equation (1):\n",
    "\n",
    "$$\n",
    "\\nabla_\\theta\\mathbb E_{p_\\theta(z)} [f_\\theta(z)].\n",
    "$$\n",
    "\n",
    "There is an alternative way to re-express this gradient:\n",
    "\n",
    "$$\n",
    "\\begin{split}\n",
    "\\nabla_\\theta\\mathbb E_{p_\\theta(z)} [f_\\theta(z)] &= \\nabla_\\theta \\int p_\\theta(z) f_\\theta(z) \\mathrm{d} z \\\\\n",
    "&= \\int f(z) \\nabla_\\theta p(z) \\mathrm{d}z \\\\\n",
    "&= \\int p_\\theta(z) f_\\theta(z) \\nabla_\\theta \\log p_\\theta(z) \\mathrm{d} z \\\\\n",
    "&= \\mathbb E_{p_\\theta(z)}\\left[f(z) \\nabla_\\theta \\log p_\\theta(z)\\right]\n",
    "\\end{split}\n",
    "$$\n",
    "\n",
    "The familiar reader will recognize the last expression as the score-based estimator of the gradient, also known as REINFORCE in the RL community.\n",
    "The advantage of calculating the gradient this way, is that we only require the density $p$ to be differentiable, but we have no constraints on $f$. However, this gradient does not scale well for high dimensionality of $\\theta$, compared to the path-wise approach, since the variance scales with the dimension of $\\theta$. See [this reference](https://arxiv.org/abs/1906.10652) for an in-depth review. -->"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Discrete Randomness"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The reparameterization trick assumes that a probability density can be reparameterised effectively with a smooth transform. This assumption holds for most of the continuous distributions we encounter in machine learning. Unfortunately, this assumption does not hold for Bernoulli and categorical distributions, which are frequently used in ABM implementations, since they are discrete. To differentiate through discrete distributions, we need to seek an alternative to the reparamterization trick.\n",
    "\n",
    "<!-- This is true for continuous distributions but it does not hold for discrete ones such as Bernoulli or Categorical distributions. -->\n",
    "\n",
    "Multiple methods have been proposed aiming to address this gap. These include surrogate gradient methods, such as the straight-through gradient estimator [(Bengio et al. 2013)](https://arxiv.org/abs/1308.3432), which replace discrete sample operations with a smooth approximation when applying the chain rule. More recent approaches include the Julia package [StochasticAD.jl](https://arxiv.org/abs/2210.08572), which leverages the theory of sample derivatives to efficiently compute unbiased pathwise gradient estimators. Unfortunately, we do not have time to cover all of these methods in detail. Instead will focus on one prominent method: the **Gumbel-Softmax (GS) trick** [(Jang et al. 2016)](https://arxiv.org/abs/1611.01144).\n",
    "\n",
    "One way to circumvent differentiability issues with a discrete distribution is to replace it with a continuous distribution that can be reparameterized. Of course, we should choose a continuous distribution that approximates the original distribution well so that gradients are informative. Consider the categorical distribution of $n$ categories with parameters $\\pi =(\\pi_{1}, \\dots, \\pi_{n})$. Here, $\\pi_{i}$ indicates the probability that category $i$ is sampled. How might we construct an appropriate continuous distribution in this case?\n",
    "\n",
    "It turns out that the categorical distribution is closely related to the Gumbel distribution. By exploiting the structure of the Gumbel distribution and basic properties of order statistics one can show that:\n",
    "\n",
    "$$ \\arg\\max_{i}(g_{i} + \\log\\pi_{i}) \\sim \\text{Cat}(\\pi), \\quad g_{i} \\sim \\text{Gumbel}(0)$$\n",
    "\n",
    " That is, we can reparameterize the categorical distribution using the Gumbel distribution. See [this paper](https://arxiv.org/abs/1411.0030) for the technical details. Unsurprisingly, this is known as the Gumbel-max trick. Unfortunately, this reparameterization is not differentiable as the $\\arg\\max$ function is not differentiable. To rectify this we can replace $\\arg\\max$ with a $\\text{softmax}$ operator, obtaining the Gumbel-Softmax distribution. \n",
    "$$ y_{i} = \\frac{\\exp((\\log\\pi_{i} + g_{i})/\\tau)}{\\sum_{j=1}^{n}\\exp((\\log\\pi_{j} + g_{j})/\\tau)}  \\quad g_{i} \\sim \\text{Gumbel}(0)$$\n",
    "\n",
    "Note that, when we apply the $\\text{softmax}$ operator, we also include a temperature parameter $\\tau > 0$. As we decrease $\\tau$, the GS distribution forms a better approximation of $\\text{Cat}(\\pi)$. In fact, one can show that as $\\tau \\to 0$, the GS distribution converges to $\\text{Cat}(\\pi)$. Unfortunately, the variance of gradient estimates increase rapidly as $\\tau \\to 0$. This is reminiscent of our experience with FD, where dividing by small values caused high variance. As a result, we face a **bias-variance trade-off** when setting $\\tau$.\n",
    "\n",
    "\n",
    "<!-- Multiple methods exist to deal with this issue, the most common ones being the Straight-Through estimator [(Bengio et al. 2013)](https://arxiv.org/abs/1308.3432) or the Gumbel-Softmax trick [(Jang et al. 2016)](https://arxiv.org/abs/1611.01144). Newer methods are continuously being developed such as the [StochasticAD.jl](https://arxiv.org/abs/2210.08572) package in the Julia language. -->\n",
    "\n",
    "<!-- Here, we focus on the Gumbel-Softmax (GS) trick.  -->\n",
    "\n",
    "<!-- The GS distribution is a continuous relaxation of the categorical distribution. The GS has a temperature parameter $\\tau$ which controls the smoothness of the approximation such that the exact Categorical sampling is recovered for $\\tau\\to 0$. However, the variance of the gradient will grow as $\\tau\\to 0$ so $\\tau$ acts as a bias-variance trade-off. -->\n",
    "\n",
    "PyTorch has a standard implementation of the GS estimator built in. In particular, PyTorch implements a *hard* version of the GS trick, which uses samples from $\\text{Cat}(\\pi)$ when performing the forward pass, but uses samples from the GS distribution during the backwards pass. By doing this, PyTorch guarantees that evaluations of the stochastic program are unaltered, whilst gradients can still be computed. In other words, GS samples are used as **surrogates** for categorical samples during the backwards pass in reverse-mode AD. This is particularly useful for ABMs which often use operations defined only on discrete values. With that being said, let's experiment with the GS trick in PyTorch!\n",
    "\n",
    "<!-- In particular, it implements a \"hard\" version of GS. The idea is that we can use the samples from the categorical distribution in the forward simulated pass, and use the continuous relaxation to approximate the gradients in the backward pass. This way we guarantee that the forward simulation is exactly equivalent to the non-relaxed version. -->\n",
    "\n",
    "Consider the following program:\n",
    "\n",
    "$$\n",
    "x = 2 \\mathrm{Bern}(3\\theta) + \\mathrm{Bern}(\\theta),\n",
    "$$\n",
    "\n",
    "where $\\text{Bern}$ denotes the Bernoulli distribution. We can easily compute the gradient of the expectation in this case:\n",
    "\n",
    "$$\n",
    "\\nabla_\\theta \\mathbb E [2 \\mathrm{Bernoulli}(3\\theta) + \\mathrm{Bernoulli}(\\theta)] = \\nabla_\\theta (6\\theta + \\theta) = 7\n",
    "$$\n",
    "\n",
    "Let's implement this program using the GS trick and investigate how the distribution of the gradient changes as we change the temperature."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "def sample_bernoulli(theta, gs_tau):\n",
    "    logits = torch.cat([theta, 1 - theta]).log()\n",
    "    return torch.nn.functional.gumbel_softmax(logits=logits, tau=gs_tau, hard=True)\n",
    "\n",
    "\n",
    "def f(theta, gs_tau):\n",
    "    return 2 * sample_bernoulli(3 * theta, gs_tau) + sample_bernoulli(theta, gs_tau)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [],
   "source": [
    "n_samples = 1_000\n",
    "taus = [0.1, 0.5, 0.9]\n",
    "gradients_per_tau = {}\n",
    "for tau in taus:\n",
    "    gradients = []\n",
    "    for i in range(n_samples):\n",
    "        theta = torch.tensor([0.1], requires_grad=True)\n",
    "        f(theta, tau)[0].backward()\n",
    "        gradients.append(theta.grad.item())\n",
    "    gradients_per_tau[tau] = gradients"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<matplotlib.legend.Legend at 0x17f86ac80>"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAAiwAAAGdCAYAAAAxCSikAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjcuMSwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy/bCgiHAAAACXBIWXMAAA9hAAAPYQGoP6dpAAA4SklEQVR4nO3de3gV1b3/8c8mkJ2EXBCBXCAQUSBB5RIsISAFHigh7aFCLXI4UC4F2mpopXmkmv6Uq5pW663CwbZHwIIIeFSwLQcLUaAKKCSmCE1CiAkBIeEiuUPAZP3+SLN1kwvZYYdMkvfreeaBPWut2d8JQ/LJ7DUzNmOMEQAAgIW1a+4CAAAArofAAgAALI/AAgAALI/AAgAALI/AAgAALI/AAgAALI/AAgAALI/AAgAALK99cxfgDpWVlTp9+rT8/Pxks9mauxwAANAAxhgVFxcrJCRE7drVfw6lVQSW06dPKzQ0tLnLAAAAjXDy5En16NGj3j6tIrD4+flJqtphf3//Zq4GAAA0RFFRkUJDQx0/x+vTKgJL9cdA/v7+BBYAAFqYhkznYNItAACwPAILAACwPAILAACwvFYxhwUAWruKigpdvXq1ucsAXObh4aH27dvf8G1HCCwAYHElJSU6deqUjDHNXQrQKD4+PgoODpanp2ejt0FgAQALq6io0KlTp+Tj46OuXbtyc0y0KMYYXblyRefOnVN2drb69Olz3RvE1YXAAgAWdvXqVRlj1LVrV3l7ezd3OYDLvL291aFDB504cUJXrlyRl5dXo7bjUsxJTEzUt771Lfn5+albt26aNGmSMjIynPpcvnxZcXFxuvXWW+Xr66v7779f+fn59W7XGKPFixcrODhY3t7eGjdunDIzM13fGwBopTizgpassWdVnLbhSuc9e/YoLi5OBw4c0M6dO3X16lWNHz9epaWljj6//OUv9Ze//EVvvvmm9uzZo9OnT+sHP/hBvdt95pln9Pvf/16vvPKKPv74Y3Xs2FExMTG6fPly4/YKAAC0LuYGnD171kgye/bsMcYYU1BQYDp06GDefPNNR5+0tDQjyezfv7/WbVRWVpqgoCDz7LPPOtYVFBQYu91u3njjjQbVUVhYaCSZwsLCG9gbALCeS5cumX/961/m0qVLzV0KrmPUqFHm4Ycfbu4yHD744AMjyVy8eNEYY8zatWtNQEBAs9RS13Hsys/vGzpHU1hYKEnq3LmzJCk5OVlXr17VuHHjHH3Cw8PVs2dP7d+/v9ZtZGdnKy8vz2lMQECAoqKi6hxTXl6uoqIipwUAYB2zZ8+WzWarsUyYMKG5S3MyevRoLVy4sLnLuCmmTp2qY8eOuXWbu3fvls1mU0FBgVu3W5tGT7qtrKzUwoULNWLECN11112SpLy8PHl6eqpTp05OfQMDA5WXl1frdqrXBwYGNnhMYmKili1b1tjSAQA3wYQJE7R27VqndXa7vZmqaZmuXLlyQ5cCf5O3t3eLnrjd6DMscXFxOnLkiDZt2uTOehokISFBhYWFjuXkyZM3vQYA7lVWVqaUlJQay0cffaTXX39dH330Ua3tKSkpKisra+7yUQu73a6goCCn5ZZbbpFU9Zu5p6en/vGPfzj6P/PMM+rWrZvjQo3Ro0drwYIFWrBggQICAtSlSxc98cQTTvejKS8v1yOPPKLu3burY8eOioqK0u7du53q+OijjzR69Gj5+PjolltuUUxMjC5evKjZs2drz549eumllxxngHJyciRJR44cUWxsrHx9fRUYGKgf/ehHOn/+vGObpaWlmjlzpnx9fRUcHKznnnuuQV+TJ598Ut26dZOfn5/mzZunxx57TIMGDXK0z549W5MmTdJTTz2lkJAQ9evXT5K0fv163XPPPfLz81NQUJD+67/+S2fPnnXa9vbt29W3b195e3trzJgxjn2ptm7duhonFLZt26bIyEh5eXmpd+/eWrZsmb766itHu81m0//8z/9o8uTJ8vHxUZ8+ffTuu+9KknJycjRmzBhJ0i233CKbzabZs2c36OvQKI35LCouLs706NHDfP75507rk5KSnD4vq9azZ0/z/PPP17qtrKwsI8l8+umnTuu//e1vm1/84hcNqoc5LEDLl5ycbCQ1aklOTm7u8ptMS53DMmvWLHPffffV22fRokWmV69epqCgwKSkpBhPT0+zbds2R/uoUaOMr6+vefjhh016errZsGGD8fHxMX/84x8dfebNm2eGDx9u9u7da44fP26effZZY7fbzbFjx4wxxnz66afGbrebBx980KSmppojR46Yl19+2Zw7d84UFBSY6OhoM3/+fHPmzBlz5swZ89VXX5mLFy+arl27moSEBJOWlmZSUlLMd77zHTNmzBjH+z744IOmZ8+eZteuXebw4cPmP/7jP4yfn1+9c1g2bNhgvLy8zJo1a0xGRoZZtmyZ8ff3NwMHDnT6uvn6+pof/ehH5siRI+bIkSPGGGNeffVVs337dpOVlWX2799voqOjTWxsrGNcbm6usdvtJj4+3vG1CgwMrHcOy969e42/v79Zt26dycrKMn//+99NWFiYWbp0qaOPJNOjRw+zceNGk5mZaX7xi18YX19fc+HCBfPVV1+Zt956y0gyGRkZ5syZM6agoKDWfXfHHBaXAktlZaWJi4szISEhjoPhm6on3f7v//6vY116enqDJt3+7ne/c9oBJt0CbUtpaalJTk6usWzYsMFIMhs2bKi1PTk52ZSWljZ3+U2mrm/0p08bk5zsvFT/DnnpUs22b2a69PSabRcuVLWdPVuzrZZv99c1a9Ys4+HhYTp27Oi0PPXUU44+5eXlZtCgQeaBBx4w/fv3N/Pnz3faxqhRo0xERISprKx0rHv00UdNRESEMcaYEydOGA8PD/PFF184jRs7dqxJSEgwxhgzbdo0M2LEiDrrrG2i7IoVK8z48eOd1p08edLxg7m4uNh4enqaLVu2ONovXLhgvL296w0sUVFRJi4uzmndiBEjagSWwMBAU15eXud2jDHm4MGDRpIpLi42xhiTkJBg+vfv79Tn0UcfrTewjB071jz99NNOY9avX2+Cg4MdryWZxx9/3PG6pKTESDL/93//Z4ypObG3Lu4ILC7NYYmLi9PGjRu1bds2+fn5OeaYBAQEyNvbWwEBAZo7d67i4+PVuXNn+fv76+c//7mio6M1bNgwx3bCw8OVmJioyZMny2azaeHChXryySfVp08f3XbbbXriiScUEhKiSZMmuXa6CECL5ePjo8jIyDrbIyIi6m1va/7wB+naqXzTp0sbNkinTklDhtQcU/1JyuzZ0oEDzm3r10szZkhbtkgLFji3jR8vvfee6zWOGTNGq1evdlpXfZGGJHl6eur111/XgAED1KtXL73wwgs1tjFs2DCne9BER0frueeeU0VFhT777DNVVFSob9++TmPKy8t16623SpJSU1M1ZcoUl+r+5z//qQ8++EC+vr412rKysnTp0iVduXJFUVFRTvtV/fFNXTIyMvTQQw85rRs6dKjef/99p3V33313jXkrycnJWrp0qf75z3/q4sWLqqyslCTl5uaqf//+SktLc6pHqvpaXW8/P/roIz311FOO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",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "fig, ax = plt.subplots()\n",
    "for i, (tau, gradients) in enumerate(gradients_per_tau.items()):\n",
    "    ax.boxplot(gradients, showmeans=True, positions=[i], labels=[f\"$\\\\tau={tau}$\"], showfliers=False)\n",
    "ax.axhline(7, color=\"blue\", linestyle=\"dashed\", linewidth=1, label=\"Expected gradient\")\n",
    "ax.legend()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The mean and median of each gradient distribution is denoted by a green triangle and orange line respectively. As we would expect, using a low temperature, such as $\\tau=0.1$, leads to very low bias. However, we also see that the median is far away from the mean, indiciating that the estimator is also very erratic. In contrast, by using a higher temperature, such as $\\tau = 0.9$, we obtain a low varaince estimator, where the mean and median are closer together. Unfortunately, this estimator also has very bias. Using an intermediary temperature, such as $\\tau = 0.5$, allows us to strike a trade-off between the behaviours of the aforementioned estimators."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The Gumbel-Softmax trick is an example of a **surrogate gradient**. The fundamental idea behind surrogate gradients is as follows. Consider an operation $f$ which is not differentiable. When applying chain rule, we can replace $f$ with a differentiable operation $g$ and use its gradient instead. The original surrogate gradient was the straight-through gradient estimator, which simply replaces $f$ with the identity. That is, the gradient passes *straight through* and is left unaltered by the non-differentiable operation $f$. This works surprisingly well in many settings. However, one would intuitively expect the overall gradient to contain more useful information if we choose $g$ to be close to $f$.\n",
    "\n",
    "In the final notebook, we will encounter another surrogate used to differentiate through the indicator function. More specifically, for the indicator $\\mathbb{I}_{x \\geq a}$ we use the following surrogate:\n",
    "\n",
    "$$\n",
    "g(x)  = \\frac{1}{1+e^{-k(x - a)}}\n",
    "$$\n",
    "\n",
    "This is a essentially a Sigmoid function centered at the boundary point $a$. Note that we include the free paramter $k$ which allows us to adapt the steepness of the Sigmoid curve. Increasing $k$ ensures that $g$ is closer to the original indicator function but also increases the risk of observing exploding and vanishing gradients. Thus, similar to the temperature in the GS trick, selecting $k$ involves making a trade-off."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<matplotlib.legend.Legend at 0x17c08f940>"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "image/png": "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",
      "text/plain": [
       "<Figure size 500x500 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "def surrogate(x, a, k):\n",
    "    return torch.sigmoid( k * (x- a))\n",
    "\n",
    "n = 1000\n",
    "xvals = torch.linspace(0., 10, n)\n",
    "a = torch.tensor(5.)\n",
    "\n",
    "k1 = surrogate(xvals, a, 0.5)\n",
    "k2 = surrogate(xvals, a, 1.)\n",
    "k3 = surrogate(xvals, a, 3.)\n",
    "k4 = surrogate(xvals, a, 5.)\n",
    "\n",
    "fig, ax = plt.subplots(figsize=(5, 5))\n",
    "ax.plot(xvals, k1, label='k=0.5')\n",
    "ax.plot(xvals, k2, label='k=1')\n",
    "ax.plot(xvals, k3, label='k=3')\n",
    "ax.plot(xvals, k4, label='k=5')\n",
    "\n",
    "ax.axvline(\n",
    "    a,\n",
    "    color=\"black\",\n",
    "    linestyle=\"dashed\",\n",
    "    linewidth=1,\n",
    "    label=\"a\",\n",
    ")\n",
    "\n",
    "ax.legend()\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Other Resources\n",
    "\n",
    "To finish, we would like to highlight some relevant literature that is worth checking out if you want to learn more about applying AD in stochastic or discrete settings. \n",
    "\n",
    "- The book [\"The Elements of Differentiable Programming\"](https://arxiv.org/abs/2403.14606) is a fantastic resource detailing how a wide range of operations can be made differentiable. For instance, the book covers differentiable dictionaries and their connection to attention, as well as how to differentiate through optimisation problems.\n",
    "- The book [\"Discrete Latent Structure in Neural Networks\"](https://arxiv.org/abs/2301.07473) has a similar flavour. In particular, the book throroughly covers surrogate gradients and smooth relaxations of the $\\arg\\max$ operator.\n",
    "- The paper [\"Monte Carlo Gradient Estimation in Machine Learning\"](https://arxiv.org/abs/1906.10652) is a seminal paper that provides a broad overview of Monte Carlo gradient estimation, especially for settings with continuous densities.\n",
    "- The papers \"[A\\* star sampling](https://arxiv.org/abs/1411.0030)\" (by Maddison, Tarlow and Minka) and [\"Categorical Reparameterisation with Gumbel-Softmax\"](https://arxiv.org/abs/1611.01144) (by Jang, Gu and Poole) are fantastic resources to learn more about the GS trick.\n",
    "- The technical report [\"Stochastic Gradient Estimation\"](https://apps.dtic.mil/sti/tr/pdf/ADA438511.pdf) (by Michael Fu) provides a computational perspective on differentiation from the viewpoint of discrete event systems. In particular, the report covers FD in great detail. The report also covers smoothed perturbation analysis (SPA), which combines the theory of sample derivatives with conditonal expectations to derive gradient estimators.\n",
    "- The paper [\"Automatic Differentiation with Discrete Randomness\"](https://arxiv.org/abs/2210.08572) (by Arya, Schauer, Rakauckas) covers the theory behind StochasticAD.jl, which effectively combines ideas from SPA and AD to differentiate through discrete distributions. The authors have also written some [lecture notes](https://ocw.mit.edu/courses/18-s096-matrix-calculus-for-machine-learning-and-beyond-january-iap-2023/mit18_s096iap23_lec7.pdf) that may be more palatable to first time readers.\n",
    "\n",
    "Be sure to check out the next notebook, where we will apply what we have learned so far to build a differentiable ABM!\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "maxent",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.14"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}