notebooks/Gentle-Intro-To-HARK-Buffer-Stock-Model.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# A Gentle Introduction to HARK: Buffer Stock Saving\n",
    "\n",
    "[![badge](https://img.shields.io/badge/Launch%20using%20-Econ--ARK-blue)](https://econ-ark.org/materials/gentle-intro-to-hark-buffer-stock-model#launch)\n",
    "\n",
    "This notebook explores the behavior of a consumer identical to the perfect foresight consumer described in [Gentle-Intro-To-HARK-PerfForesightCRRA](./Gentle-Intro-To-HARK-PerfForesightCRRA.ipynb) except that now the model incorporates income uncertainty and (artificial) borrowing constraints."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "# This cell has a bit of initial setup.\n",
    "# Click the \"Run\" button immediately above the notebook in order to execute the contents of any cell\n",
    "# WARNING: Each cell in the notebook relies upon results generated by previous cells\n",
    "#   The most common problem beginners have is to execute a cell before all its predecessors\n",
    "#   If you do this, you can restart the kernel (see the \"Kernel\" menu above) and start over\n",
    "from HARK.ConsumptionSaving.ConsIndShockModel import IndShockConsumerType\n",
    "from HARK.ConsumptionSaving.ConsIndShockModel import PerfForesightConsumerType\n",
    "from HARK.utilities import plot_funcs\n",
    "import matplotlib.pyplot as plt\n",
    "\n",
    "import numpy as np\n",
    "from copy import deepcopy\n",
    "\n",
    "\n",
    "def mystr(number):\n",
    "    return \"{:.4f}\".format(number)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The Consumer's Problem with Transitory and Permanent Shocks\n",
    "### Mathematical Description\n",
    "\n",
    "Our new type of consumer receives two income shocks at the beginning of each period.  Permanent income would grow by a factor $\\Gamma$ in the absence of any shock , but its growth is modified by a shock, $\\psi_{t+1}$:\n",
    "\\begin{align}\n",
    " P_{t+1} & = \\Gamma P_{t}\\psi_{t+1}\n",
    "\\end{align}\n",
    "whose expected (mean) value is $\\mathbb{E}_{t}[\\psi_{t+1}]=1$.  Actual income received $Y$ is equal to permanent income $P$ multiplied by a transitory shock $\\theta$:\n",
    "\\begin{align}\n",
    " Y_{t+1} & = \\Gamma P_{t+1}\\theta_{t+1}\n",
    "\\end{align}\n",
    "where again $\\mathbb{E}_{t}[\\theta_{t+1}] = 1$.\n",
    "\n",
    "As with the perfect foresight problem, this model can be rewritten in terms of _normalized_ variables, e.g. the ratio of 'market resources' $M_{t}$ (wealth plus current income) to permanent income is $m_t \\equiv M_t/P_t$.  (See [here](http://www.econ2.jhu.edu/people/ccarroll/papers/BufferStockTheory/) for the theory).  In addition, lenders may set a limit on borrowing: The ratio $a_{t}$ of end-of-period assets to permanent income $A_t/P_t$ must be greater than $\\underline{a} \\leq 0$. (So, if $\\underline{a}=-0.3$, the consumer cannot borrow more than 30 percent of their permanent income).\n",
    "\n",
    "The consumer's (normalized) problem turns out to be:\n",
    "\\begin{eqnarray*}\n",
    "v_t(m_t) &=& \\max_{c_t} ~~u(c_t) + \\beta  \\mathbb{E} [(\\Gamma_{t+1}\\psi_{t+1})^{1-\\rho} v_{t+1}(m_{t+1}) ], \\\\\n",
    " & \\text{s.t.} & \\\\\n",
    "a_t &=& m_t - c_t, \\\\\n",
    "a_t &\\geq& \\underline{a}, \\\\\n",
    "m_{t+1} &=& a_t  R/(\\Gamma_{t+1} \\psi_{t+1}) + \\theta_{t+1}.\n",
    "\\end{eqnarray*}\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For present purposes, we assume that the transitory and permanent shocks are independent.  The permanent shock is assumed to be (approximately) lognormal, while the transitory shock has two components: A probability $\\wp$ that the consumer is unemployed, in which case $\\theta^{u}=\\underline{\\theta}$, and a probability $(1-\\wp)$ of a shock that is a lognormal with a mean chosen so that $\\mathbb{E}_{t}[\\theta_{t+n}]=1$.\n",
    "\n",
    "\n",
    "### Representing the Income Shocks\n",
    "\n",
    "Computers are discrete devices; even if somehow we knew with certainty that the transitory and permanent shocks were, say, continuously lognormally distributed, in order to be represented on a computer those distributions would need to be approximated by a finite set of points.  A large literature in numerical computation explores ways to construct such approximations; probably the easiest discretization to understand is the equiprobable approximation, in which the continuous distribution is represented by a set of $N$ outcomes that are equally likely to occur.\n",
    "\n",
    "In the case of a single variable (say, the permanent shock $\\psi$), and when the number of equiprobable points is, say, 5, the procedure is to construct a list: $\\psi^{0}$ is the mean value of the continuous $\\psi$ given that the draw of $\\psi$ is in the bottom 20 percent of the distribution of the continuous $\\psi$.  $\\psi^{1}$ is the mean value of $\\psi$ given that the draw is between the 20th and 40th percentiles, and so on.  Having constructed these, the approximation to the expectation of some expression $g(\\psi)$ can be very quickly calculated by:\n",
    "\n",
    "$$\n",
    "\\mathbb{E}_{t}[g(\\psi)] \\equiv \\int_{0}^{\\infty} g(\\psi) dF_{\\psi} \\approx (1/N) \\sum_{i=0}^{N-1} g(\\psi^{i}).\n",
    "$$\n",
    "\n",
    "(For a graphical depiction of a particular instance of this, see [SolvingMicroDSOPs/#discreteApprox](http://www.econ2.jhu.edu/people/ccarroll/SolvingMicroDSOPs/#discreteApprox).)\n",
    "\n",
    "## The New Parameters\n",
    "\n",
    "In addition to the parameters required for the perfect foresight model (like the time preference factor $\\beta$), under the assumptions above, we need to choose values for the following extra parameters that describe the income shock distribution and the artificial borrowing constraint.\n",
    "\n",
    "| Param | Description | Code | Value |\n",
    "| :---: | ---         | ---  | :---: |\n",
    "| $\\underline{a}$ | Artificial borrowing constraint | $\\texttt{BoroCnstArt}$ | 0.0 |\n",
    "| $\\sigma_\\psi$ | Underlying stdev of permanent income shocks | $\\texttt{PermShkStd}$ | 0.1 |\n",
    "| $\\sigma_\\theta^{e}$ | Underlying stdev of transitory income shocks | $\\texttt{TranShkStd}$ | 0.1 |\n",
    "| $N_\\psi$ | Number of discrete permanent income shocks | $\\texttt{PermShkCount}$ | 7 |\n",
    "| $N_\\theta$ | Number of discrete transitory income shocks | $\\texttt{TranShkCount}$ | 7 |\n",
    "| $\\wp$ | Unemployment probability | $\\texttt{UnempPrb}$ | 0.05 |\n",
    "| $\\underline{\\theta}$ | Transitory shock when unemployed | $\\texttt{IncUnemp}$ | 0.3 |"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Representation in HARK\n",
    "\n",
    "HARK agents with this kind of problem are instances of the class $\\texttt{IndShockConsumerType}$, which is constructed by \"inheriting\" the properties of the $\\texttt{PerfForesightConsumerType}$ and then adding only the _new_ information required:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "# This cell defines a parameter dictionary for making an instance of IndShockConsumerType.\n",
    "\n",
    "\n",
    "IndShockDictionary = {\n",
    "    \"PermShkStd\": [\n",
    "        0.1\n",
    "    ],  # ... by specifying the new parameters for constructing the income process.\n",
    "    \"PermShkCount\": 7,\n",
    "    \"TranShkStd\": [0.1],\n",
    "    \"TranShkCount\": 7,\n",
    "    \"UnempPrb\": 0.05,\n",
    "    # ... and income for unemployed people (30 percent of \"permanent\" income)\n",
    "    \"IncUnemp\": 0.3,\n",
    "    # ... and specifying the location of the borrowing constraint (0 means no borrowing is allowed)\n",
    "    \"BoroCnstArt\": 0.0,\n",
    "    \"cycles\": 0,  # signifies an infinite horizon solution (see below)\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Other Attributes are Inherited from PerfForesightConsumerType\n",
    "\n",
    "You can see all the **attributes** of an object in Python by using the `dir()` command. From the output of that command below, you can see that many of the model variables are now attributes of this object, along with many other attributes that are outside the scope of this tutorial."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['AgentCount',\n",
       " 'BoroCnstArt',\n",
       " 'CRRA',\n",
       " 'DiscFac',\n",
       " 'LivPrb',\n",
       " 'MaxKinks',\n",
       " 'PerfMITShk',\n",
       " 'PermGroFac',\n",
       " 'PermGroFacAgg',\n",
       " 'RNG',\n",
       " 'Rfree',\n",
       " 'T_age',\n",
       " 'T_cycle',\n",
       " '__class__',\n",
       " '__delattr__',\n",
       " '__dict__',\n",
       " '__dir__',\n",
       " '__doc__',\n",
       " '__eq__',\n",
       " '__format__',\n",
       " '__ge__',\n",
       " '__getattribute__',\n",
       " '__gt__',\n",
       " '__hash__',\n",
       " '__init__',\n",
       " '__init_subclass__',\n",
       " '__le__',\n",
       " '__lt__',\n",
       " '__module__',\n",
       " '__ne__',\n",
       " '__new__',\n",
       " '__reduce__',\n",
       " '__reduce_ex__',\n",
       " '__repr__',\n",
       " '__setattr__',\n",
       " '__sizeof__',\n",
       " '__str__',\n",
       " '__subclasshook__',\n",
       " '__weakref__',\n",
       " 'aNrmInitMean',\n",
       " 'aNrmInitStd',\n",
       " 'add_to_time_inv',\n",
       " 'add_to_time_vary',\n",
       " 'assign_parameters',\n",
       " 'bilt',\n",
       " 'cFunc_terminal_',\n",
       " 'calc_limiting_values',\n",
       " 'check_AIC',\n",
       " 'check_FHWC',\n",
       " 'check_FVAC',\n",
       " 'check_GICRaw',\n",
       " 'check_RIC',\n",
       " 'check_conditions',\n",
       " 'check_elements_of_time_vary_are_lists',\n",
       " 'check_restrictions',\n",
       " 'clear_history',\n",
       " 'controls',\n",
       " 'cycles',\n",
       " 'del_from_time_inv',\n",
       " 'del_from_time_vary',\n",
       " 'describe_parameters',\n",
       " 'get_Rfree',\n",
       " 'get_controls',\n",
       " 'get_mortality',\n",
       " 'get_parameter',\n",
       " 'get_poststates',\n",
       " 'get_shocks',\n",
       " 'get_states',\n",
       " 'history',\n",
       " 'initialize_sim',\n",
       " 'log_condition_result',\n",
       " 'make_shock_history',\n",
       " 'newborn_init_history',\n",
       " 'pLvlInitMean',\n",
       " 'pLvlInitStd',\n",
       " 'parameters',\n",
       " 'post_solve',\n",
       " 'pre_solve',\n",
       " 'pseudo_terminal',\n",
       " 'quiet',\n",
       " 'read_shocks',\n",
       " 'read_shocks_from_history',\n",
       " 'reset_rng',\n",
       " 'seed',\n",
       " 'shock_history',\n",
       " 'shock_vars',\n",
       " 'shock_vars_',\n",
       " 'shocks',\n",
       " 'sim_birth',\n",
       " 'sim_death',\n",
       " 'sim_one_period',\n",
       " 'simulate',\n",
       " 'solution_terminal',\n",
       " 'solution_terminal_',\n",
       " 'solve',\n",
       " 'solve_one_period',\n",
       " 'state_now',\n",
       " 'state_prev',\n",
       " 'state_vars',\n",
       " 'time_inv',\n",
       " 'time_inv_',\n",
       " 'time_vary',\n",
       " 'time_vary_',\n",
       " 'tolerance',\n",
       " 'track_vars',\n",
       " 'transition',\n",
       " 'unpack',\n",
       " 'unpack_cFunc',\n",
       " 'update_Rfree',\n",
       " 'update_solution_terminal',\n",
       " 'vFunc_terminal_',\n",
       " 'verbose']"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pfc = PerfForesightConsumerType()\n",
    "dir(pfc)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In python terminology, `IndShockConsumerType` is a **superclass** of `PerfForesightConsumerType`. This means that it builds on the functionality of its parent type (including, for example, the definition of the utility function). You can find the superclasses of a type in Python using the `__bases__` attribute:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(HARK.ConsumptionSaving.ConsIndShockModel.PerfForesightConsumerType,)"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "IndShockConsumerType.__bases__"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "# So, let's create an instance of the IndShockConsumerType\n",
    "IndShockExample = IndShockConsumerType(**IndShockDictionary)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As before, we need to import the relevant subclass of $\\texttt{AgentType}$ into our workspace, then create an instance by passing the dictionary to the class as if the class were a function."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The Discretized Probability Distribution\n",
    "\n",
    "The scatterplot below shows how the discretized probability distribution is represented in HARK: The lognormal distribution is represented by a set of equiprobable point masses."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAAkkAAAGwCAYAAAC99fF4AAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjguMiwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy8g+/7EAAAACXBIWXMAAA9hAAAPYQGoP6dpAAA5QElEQVR4nO3df1RUdeL/8dcAAmqCKT/SRELbBMLkV/krErfCzFQ+7Vkxw8xsN7a2JI99kqUfG22y1ba5adDi+iMq07XUdTvux2VtU9TKQmazdKk1EdRhEVNA3aDgfv/wON+duNAMggPD83HOPYd5z/u+7/v9nlvz8j137lgMwzAEAAAAB17u7gAAAEBXREgCAAAwQUgCAAAwQUgCAAAwQUgCAAAwQUgCAAAwQUgCAAAw4ePuDnRXzc3NOnbsmPr16yeLxeLu7gAAACcYhqH6+noNHjxYXl5trxURktrp2LFjCgsLc3c3AABAO1RWVmrIkCFt1iEktVO/fv0knZvkgIAAN/cGAAA4o66uTmFhYfb38bYQktrp/EdsAQEBhCQAALoZZy6V4cJtAAAAE4QkAAAAE4QkAAAAE4QkAAAAE4QkAAAAE4QkAAAAE4QkAAAAE4QkAAAAE4QkAAAAE4QkAAAAE24PSXl5eYqIiJC/v78SEhJUXFzcal2bzaZZs2ZpxIgR8vLyUmZmZos6q1evlsViabF9/fXX7T4uAADoedwaktatW6fMzExlZ2ertLRUSUlJmjx5sioqKkzrNzQ0KDg4WNnZ2Ro1alSr7QYEBMhmszls/v7+7T4uAADoeSyGYRjuOvjo0aMVHx+v/Px8e1lUVJRSU1OVm5vb5r7JycmKjY3VkiVLHMpXr16tzMxMnTp1qlOOe15dXZ0CAwNVW1vLD9wCANBNuPL+7baVpMbGRpWUlCglJcWhPCUlRbt3776gtk+fPq3w8HANGTJEt912m0pLSy/4uA0NDaqrq3PYAACA53JbSKqpqVFTU5NCQ0MdykNDQ1VVVdXudiMjI7V69Wpt3rxZb775pvz9/TV+/Hh98cUXF3Tc3NxcBQYG2rewsLB29xEAAHR9br9w22KxODw2DKNFmSvGjBmj9PR0jRo1SklJSfrjH/+oq666SkuXLr2g42ZlZam2tta+VVZWtruPAACg6/Nx14GDgoLk7e3dYvWmurq6xSrPhfDy8tK1115rX0lq73H9/Pzk5+fXYf0CAABdm9tWknx9fZWQkKCioiKH8qKiIo0bN67DjmMYhqxWqwYNGnRRjwsAALo3t60kSdKCBQs0e/ZsJSYmauzYsSooKFBFRYUyMjIknfuI6+jRoyosLLTvY7VaJZ27OPv48eOyWq3y9fVVdHS0JOmpp57SmDFj9IMf/EB1dXV66aWXZLVa9fLLLzt9XAAAALeGpLS0NJ04cUI5OTmy2WyKiYnRli1bFB4eLunczSO/e++iuLg4+98lJSVas2aNwsPDVV5eLkk6deqUfvrTn6qqqkqBgYGKi4vTjh07dN111zl9XAAAALfeJ6k74z5JAAB0P93iPkkAAABdGSEJAADABCEJAADABCEJAADABCEJAADABCEJAADABCEJAADABCEJAADABCEJAADABCEJAADABCEJAADABCEJAADABCEJAADABCEJAADABCEJAADABCEJAADABCEJAADABCEJAADABCEJAADABCEJAADABCEJAADABCEJAADABCEJAADABCEJAADABCEJAADABCEJAADABCEJAADABCEJAADABCEJAADABCEJAADABCEJAADABCEJAADABCEJAADABCEJAADABCEJAADABCEJAADAhNtDUl5eniIiIuTv76+EhAQVFxe3Wtdms2nWrFkaMWKEvLy8lJmZ2Wbba9eulcViUWpqqkP5t99+q8cee0wRERHq3bu3hg0bppycHDU3N3fAiAAAgCdwa0hat26dMjMzlZ2drdLSUiUlJWny5MmqqKgwrd/Q0KDg4GBlZ2dr1KhRbbZ9+PBhLVy4UElJSS2ee/bZZ/XKK69o2bJlOnDggJ577jk9//zzWrp0aYeMCwAAdH8WwzAMdx189OjRio+PV35+vr0sKipKqampys3NbXPf5ORkxcbGasmSJS2ea2pq0oQJEzR37lwVFxfr1KlT2rRpk/352267TaGhoVqxYoW97Ec/+pH69Omj1157zam+19XVKTAwULW1tQoICHBqHwAA4F6uvH+7bSWpsbFRJSUlSklJcShPSUnR7t27L6jtnJwcBQcHa968eabPX3/99dq2bZs+//xzSdI//vEP7dy5U7feemurbTY0NKiurs5hAwAAnsvHXQeuqalRU1OTQkNDHcpDQ0NVVVXV7nZ37dqlFStWyGq1tlrn0UcfVW1trSIjI+Xt7a2m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nfr6eqO0tNQoLS01JBm//e1vjdLSUuPw4cOGYbScmy+//NLo06eP8fDDDxv79+83VqxYYfTq1ct466237HU85bwxjM6Zn5567hiGYa+fkJBgzJo1yygtLTU+++wz+/Oecu50xtx4wnlDSOpkL7/8shEeHm74+voa8fHxxvbt2+3PzZkzx5gwYYJD/ZdeesmIjo42evfubQwaNMi48847jSNHjtifz8zMNIYOHWr4+voawcHBRkpKirF79+6LNZwO58r87N+/34iNjTV69+5tBAQEGNOnTzf++c9/tmhz/fr1xogRI4xevXoZkZGRxttvv30xhtLhOnpuPOXc+fvf/25IarHNmTPHMAzz/67ee+89Iy4uzvD19TWuuOIKIz8/v0W7nnLedMb89ORzx6x+eHi4Qx1POHc6Y2484byxGEYrn+MAAAD0YFyTBAAAYIKQBAAAYIKQBAAAYIKQBAAAYIKQBAAAYIKQBAAAYIKQBAAAYIKQBAAAYIKQBAD/JTk5WZmZme7uBoAugJAEwGNMnTpVN910k+lz77//viwWi/bu3XuRewWguyIkAfAY8+bN07vvvqvDhw+3eG7lypWKjY1VfHy8G3oGoDsiJAHwGLfddptCQkK0evVqh/KzZ89q3bp1Sk1N1R133KEhQ4aoT58+GjlypN58880227RYLNq0aZNDWf/+/R2OcfToUaWlpenSSy/VwIEDNX36dJWXl3fMoAC4DSEJgMfw8fHRXXfdpdWrV+u/f7t7/fr1amxs1L333quEhAS98847+vTTT/XTn/5Us2fP1ocfftjuY549e1YTJ07UJZdcoh07dmjnzp265JJLdMstt6ixsbEjhgXATQhJADzKPffco/Lycr333nv2spUrV+r222/X5ZdfroULFyo2NlbDhg3Tgw8+qEmTJmn9+vXtPt7atWvl5eWlP/zhDxo5cqSioqK0atUqVVRUOPQBQPfj4+4OAEBHioyM1Lhx47Ry5UpNnDhRBw8eVHFxsf7617+qqalJv/71r7Vu3TodPXpUDQ0NamhoUN++fdt9vJKSEv3rX/9Sv379HMq//vprHTx48EKHA8CNCEkAPM68efP085//XC+//LJWrVql8PBw3XjjjXr++ef14osvasmSJRo5cqT69u2rzMzMNj8Ws1gsDh/dSdI333xj/7u5uVkJCQl64403WuwbHBzccYMCcNERkgB4nBkzZmj+/Plas2aNXn31Vf3kJz+RxWJRcXGxpk+frvT0dEnnAs4XX3yhqKioVtsKDg6WzWazP/7iiy909uxZ++P4+HitW7dOISEhCggI6LxBAbjouCYJgMe55JJLlJaWpl/84hc6duyY7r77bknSlVdeqaKiIu3evVsHDhzQfffdp6qqqjbb+uEPf6hly5Zp7969+vjjj5WRkaFevXrZn7/zzjsVFBSk6dOnq7i4WIcOHdL27ds1f/58HTlypDOHCaCTEZIAeKR58+bp5MmTuummmzR06FBJ0uOPP674+HhNmjRJycnJuuyyy5SamtpmOy+88ILCwsJ0ww03aNasWVq4cKH69Oljf75Pnz7asWOHhg4dqttvv11RUVG655579J///IeVJaCbsxjf/bAdAAAArCQBAACYISQBAACYICQBAACYICQBAACYICQBAACYICQBAACYICQBAACYICQBAACYICQBAACYICQBAACYICQBAACY+H9LhQAljFPGjgAAAABJRU5ErkJggg==",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# Plot values for equiprobable distribution of permanent shocks\n",
    "\n",
    "plt.scatter(IndShockExample.PermShkDstn[0].atoms, IndShockExample.PermShkDstn[0].pmv)\n",
    "plt.xlabel(\"Value\")\n",
    "plt.ylabel(\"Probability Mass\")\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This distribution was created, using the parameters in the dictionary above, when the `IndShockConsumerType` object was initialized."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Solution by Backwards Induction\n",
    "\n",
    "HARK solves this problem using _backwards induction_: It will derive a solution for each period ($t$) by finding a mapping between specific values of market resources $\\{m[0],m[1],...\\}$ and the corresponding optimal consumption $\\{c[0],c[1],...\\}$. The function that \"connects the dots\" will be stored in a variable named `cFunc`.\n",
    "\n",
    "Backwards induction requires a \"terminal\" (last; final) period to work backwards from.  `IndShockExample` constructed above did not specify a terminal consumption function, and consequently it uses the default terminal function in which all resources are consumed: $c_{T} = m_{t}$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<HARK.ConsumptionSaving.ConsIndShockModel.ConsumerSolution at 0x13d304a00>"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "IndShockExample.solution_terminal"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The consumption function `cFunc` is defined by _piecewise linear interpolation_.\n",
    "\n",
    "It is defined by a series of $(m,c)$ points on a grid; the value of the function for any $m$ is the $c$ determined by the line connecting the nearest defined gridpoints.\n",
    "\n",
    "You can see below that in the terminal period, $c = m$; the agent consumes all available resources."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<matplotlib.collections.PathCollection at 0x13d425720>"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "image/png": "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yMnJ4dlnnyU2NpbOnTubHU1KUbEqpo2NTaFfG4Zx27HfnDlzhgkTJvDWW29x6tQp9uzZw/nz5wkKCrrrnz99+nRSU1NvPS5cuFCcmCIiYkVOnDiBm5sbW7dupUqVKixYsIAdO3ZQu3Zts6NJKbPopmd169bFzs7utilIUlLSbdOS3wQHB9OlSxdeffVVAB599FGqV69Ot27deOedd+54pzxHR0ccHR0tiSYiIlbKMAwWLlzItGnTyM3NpXnz5kRGRtK+fXuzo0kZsWgy4uDggLu7O9HR0YWOR0dH4+Hhccfn3Lhx47Ydn52dHfDrX0AREam8rl69yoABA5g8eTK5ubm8+OKLnD59WkWkkrF4TTNlyhRWrVrFmjVrOHv2LJMnTyY+Pv7W2mX69OkMHTr01vn9+/dn27ZtLF26lHPnznH48GEmTJhAhw4daNSoUcl9JyIiYlWOHj1K27Zt2blzJw4ODixZsoSPP/6YWrVqmR1NypjFP5tm0KBBpKSkMHv2bBISEmjdujVRUVE0a9YMgISEhEL3HPH39yc9PZ0lS5YwdepUatWqxZNPPsn7779fct+FiIhYjYKCAubOncsbb7xBXl4ef/rTn9i8eTNt27Y1O5qYxMawgl1JWloaLi4upKam4uzsbHYcEREppuTkZPz8/IiKigLAy8uL5cuX67/tFVRRX7/1gW0RESkTMTExtGnThqioKJycnFi+fDkbN25UERGVERERKV0FBQW899579OjRg19++YWHH36Yr7/+mpEjR971thBSuVj8nhEREZGiSkpKYsiQIbc+henr60toaCg1atQwOZmUJyojIiJSKr766it8fHxITEykatWqhISE4O/vr2mI3EZrGhERKVH5+fnMmjWLnj17kpiYyCOPPMLJkycJCAhQEZE70mRERERKTEJCAkOGDGHfvn0ADBs2jMWLF1OtWjWTk0l5pjIiIiIlIjo6miFDhpCUlET16tVZtmwZQ4YMMTuWWAGtaURE5J7k5eXx5ptv0rt3b5KSknj00Uc5efKkiogUmSYjIiJSbBcvXsTHx4eYmBgARo0axfz586latarJycSaqIyIiEix7N69G19fX1JSUqhZsyYrVqzAy8vL7FhihbSmERERi+Tm5vLaa6/Rt29fUlJSaNu2LadPn1YRkWLTZERERIosPj4eLy8vjh49CsC4ceOYM2cO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0go9xHrFxMTQpk0bdu/ejZOTEytWrCA8PFxFREREAAvLSHJyMvn5+bi6uhY67urqSmJiYpH+jLlz55KZmcnAgQPvek5wcDAuLi63Hk2bNrUkppQTBQUFvPvuu3Tv3p1Lly7x5z//mePHjzNixAitZURE5JZivYH1v19IDMMo0ovLpk2bePvtt4mMjPzdn7g6ffp0UlNTbz0uXLhQnJhiosuXL/P000/z5ptvUlBQwNChQzlx4gR//etfzY4mIiLljEUf7a1bty52dna3TUGSkpJum5b8t8jISAIDA/n444/p2bPn757r6OiIo6OjJdGkHNm3bx+DBw8mMTGRatWqERISgr+/v9mxRESknLJoMuLg4IC7uzvR0dGFjkdHR+Ph4XHX523atAl/f382btxIv379ipdUyr38/HzefvttevbsSWJiIn/5y184ceKEioiIiPwui296NmXKFHx9fWnXrh2dO3dmxYoVxMfHExQUBPy6Yvnll19Yt24d8GsRGTp0KAsXLqRTp063pipVq1bVfSUqkISEBHx8fNi/fz8AgYGBLFq0iGrVqpkbTEREyj2Ly8igQYNISUlh9uzZJCQk0Lp1a6KiomjWrBnw64vSf95zZPny5eTl5TF27FjGjh1767ifnx9hYWH3/h2I6fbu3cuQIUO4cuUK1atXZ/ny5QwePNjsWCIiYiUsvs+IGXSfkfIpLy+PmTNnEhwcjGEYPPbYY2zevJmWLVuaHU1ERMqBor5+62fTSLFcvHgRHx+fWz8KICgoiHnz5lG1alWTk4mIiLVRGRGLRUVFMXToUFJSUqhZsyarVq363fvGiIiI/J5i3WdEKqfc3FymTZtGv379SElJwc3NjdOnT6uIiIjIPdFkRIokPj4eLy8vjh49CsD48eOZM2eO7gcjIiL3TGVE/tDOnTvx9/fn2rVruLi4sGbNGl544QWzY4mISAWhNY3cVU5ODpMnT+a5557j2rVrtG/fntjYWBUREREpUSojckfnz5+na9euLFiwAPj1ZneHDh2iefPm5gYTEZEKR2sauc3WrVsJDAwkNTWV++67j48++oj+/fubHUtERCooTUbklps3bzJu3DheeuklUlNT8fDwIC4uTkVERERKlcqIAPDDDz/g4eFBSEgIAK+99hr79+/n/vvvNzmZiIhUdFrTCBEREYwcOZL09HTq1q3LunXr6NOnj9mxRESkktBkpBLLyspi1KhReHt7k56eTrdu3YiLi1MRERGRMqUyUkl99913dOrUiRUrVmBjY8Obb77Jvn37aNy4sdnRRESkktGaphLasGEDQUFBZGZmUr9+fTZs2ECvXr3MjiUiIpWUJiOVyI0bNxg2bBi+vr5kZmbSo0cP4uLiVERERMRUKiOVxLfffkv79u1Zu3Yttra2zJo1i+joaBo2bGh2NBERqeS0pqngDMMgLCyMsWPHkpWVRcOGDdm4cSPdu3c3O5qIiAigMlKhZWRkMHr0aDZs2ACAp6cn69evp379+iYnExER+f+0pqmg/v73v9OuXTs2bNiAnZ0d7733Hrt371YRERGRckeTkQrGMAxWrlzJhAkTyM7OpnHjxkRERNC1a1ezo4mIiNyRykgFkpaWxqhRo4iIiACgb9++fPTRR9StW9fkZCIiInenNU0FERsbi7u7OxEREdjb2zNnzhx27dqlIiIiIuWeJiNWzjAMQkNDmTJlCjk5Odx///1ERETQuXNns6OJiIgUicqIFbt+/TrDhw9n69atADz77LOsXbuW2rVrm5xMRESk6LSmsVInTpzAzc2NrVu3UqVKFRYsWMCOHTtURERExOpoMmJlDMNg4cKFTJs2jdzcXJo3b05kZCTt27c3O5qIiEixqIxYkatXrxIQEMDOnTsBePHFF1m1ahW1atUyN5iIiMg90JrGShw9epS2bduyc+dOHBwcCAkJ4eOPP1YRERERq6cyUs4VFBQwZ84cHn/8ceLj4/nTn/7EsWPHGDNmDDY2NmbHExERuWda05RjycnJ+Pn5ERUVBYCXlxfLly/H2dnZ5GQiIiIlR2WknIqJicHb25tffvkFJycnFi1axPDhwzUNERGRCkdrmnKmoKCA9957jx49evDLL7/w8MMP8/XXXzNixAgVERERqZA0GSlHkpKSGDJkCNHR0QD4+voSGhpKjRo1TE4mIiJSelRGyomvvvoKHx8fEhMTqVq1KiEhIfj7+2saIiIiFZ7WNCbLz89n1qxZ9OzZk8TERB555BFOnjxJQECAioiIiFQKmoyYKCEhgSFDhrBv3z4Ahg0bxuLFi6lWrZrJyURERMqOyohJoqOjGTJkCElJSVSvXp1ly5YxZMgQs2OJiIiUOa1pylheXh5vvvkmvXv3JikpiUcffZRTp06piIiISKWlyUgZunjxIj4+PsTExAAwatQo5s+fT9WqVU1OJiIiYh6VkTKye/dufH19SUlJoWbNmqxcuZJBgwaZHUtERMR0WtOUstzcXF577TX69u1LSkoKbm5unD59WkVERETk/2gyUori4+Px8vLi6NGjAIwbN44PP/wQR0dHk5OJiIiUHyojpWTnzp34+/tz7do1XFxcWL16NS+++KLZsURERModrWlKWE5ODlOmTOG5557j2rVrtG/fntjYWBURERGRu1AZKUHnz5+nW7duzJ8/H4DJkydz6NAhmjdvbnIyERGR8ktrmhKybds2hg0bRmpqKvfddx9hYWE8++yzZscSEREp9zQZuUfZ2dmMHz+eF198kdTUVDp37kxsbKyKiIiISBGpjNyDH374AQ8PD5YsWQLAtGnTOHDgAM2aNTM5mYiIiPXQmqaYIiMjGTFiBOnp6dSpU4d169bRt29fs2OJiIhYHU1GLJSVlUVQUBBeXl6kp6fTrVs34uLiVERERESKSWXEAt999x2dOnVi+fLl2NjYMGPGDPbt20eTJk3MjiYiImK1tKYpog0bNhAUFERmZib169dnw4YN9OrVy+xYIiIiVk+TkT9w48YNAgMD8fX1JTMzkx49ehAXF6ciIiIiUkJURn7HmTNn6NChA2vWrMHGxoa3336b6OhoGjZsaHY0ERGRCkNrmrsICwtjzJgxZGVl0aBBAzZu3EiPHj3MjiUiIlLhVNoykl9gcPz8VZLSb1K/phMdmtfGztaGjIwMxo4dy7p16wDo1asX69evx9XV1eTEIiIiFVOx1jShoaE0b94cJycn3N3diYmJ+d3zDxw4gLu7O05OTrRo0YJly5YVK2xJ2fPPBLq+vw/vlceYGBGH98pjdH1/H0u3fkn79u1Zt24dtra2vPvuu+zZs0dFREREpBRZXEYiIyOZNGkSM2bMIDY2lm7dutGnTx/i4+PveP758+fp27cv3bp1IzY2ljfeeIMJEyawdevWew5fHHv+mcDoDadJSL1565hhGHx/YAdjvfryr3/9i8aNG7N//37eeOMNbG31thoREZHSZGMYhmHJEzp27IibmxtLly69daxVq1YMGDCA4ODg285/7bXX2LlzJ2fPnr11LCgoiG+++YajR48W6WumpaXh4uJCamoqzs7OlsQtJL/AoOv7+woVkYLsG6R8voQbZw8CUKtlB/4V8ymu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yd/pgoICbGxsCA8Pp0OHDvTt25d58+YRFham6cgfsOQ6nzlzhgkTJvDWW29x6tQp9uzZw/nz5wkKCiqLqJVKWb8WVtj/Vapbty52dna3NeykpKTbGt9vGjRocMfz7e3tqVOnTqlltWbFuc6/iYyMJDAwkI8//piePXuWZswKwdJrnZ6ezsmTJ4mNjWXcuHHAry+ahmFgb2/P3r17efLJJ8skuzUpzt/phg0b0rhx40I/Kr1Vq1YYhsHFixd56KGHSjWzNSrOdQ4ODqZLly68+uqrADz66KNUr16dbt268c4772h6XULMeC2ssJMRBwcH3N3diY6OLnQ8OjoaDw+POz6nc+fOt52/d+9e2rVrR5UqVUotqzUrznWGXyci/v7+bNy4UfveIrL0Wjs7O/OPf/yDuLi4W4+goCAefvhh4uLi6NixY1lFtyrF+TvdpUsXLl26REZGxq1j//73v7G1taVJkyalmtdaFec637hxA1vbwi9bdnZ2wP//P3e5d6a8FpbaW2PLgd8+NrZ69WrjzJkzxqRJk4zq1asbP/30k2EYhvH6668bvr6+t87/7eNMkydPNs6cOWOsXr1aH+0tAkuv88aNGw17e3sjJCTESEhIuPW4fv26Wd+C1bD0Wv83fZqmaCy9zunp6UaTJk2Ml156yfj222+NAwcOGA899JAxfPhws74Fq2DpdV67dq1hb29vhIaGGj/++KNx6NAho127dkaHDh3M+hasQnp6uhEbG2vExsYagDFv3jwjNjb21keoy8NrYYUuI4ZhGCEhIUazZs0MBwcHw83NzThw4MCt3/Pz8zOeeOKJQufv37/faNu2reHg4GA88MADxtKlS8s4sXWy5Do/8cQTBnDbw8/Pr+yDWyFL/07/J5WRorP0Op89e9bo2bOnUbVqVaNJkybGlClTjBs3bpRxautj6XVetGiR8cgjjxhVq1Y1GjZsaAwePNi4ePFiGae2Ll999dXv/je3PLwW2hiGZlsiIiJingr7nhERERGxDiojIiIiYiqVERERETGVyoiIiIiYSmVERERETKUyIiIiIqZSGRERERFTqYyIiIiIqVRGRERExFQqIyIiImIqlRERERExlcqIiIiImOr/AbbCb9Vgv9SVAAAAAElFTkSuQmCC",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# Plot terminal consumption function\n",
    "plt.plot(\n",
    "    IndShockExample.solution_terminal.cFunc.x_list,\n",
    "    IndShockExample.solution_terminal.cFunc.y_list,\n",
    "    color=\"k\",\n",
    ")\n",
    "plt.scatter(\n",
    "    IndShockExample.solution_terminal.cFunc.x_list,\n",
    "    IndShockExample.solution_terminal.cFunc.y_list,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The solution also has a representation of a `value function`, the value `v(m)` as a function of available market resources. Because the agent consumes all their resources in the last period, the value function for the terminal solution looks just like the CRRA utility function: $v_{T}(m) = u(m)$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[<matplotlib.lines.Line2D at 0x13d4971c0>]"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAAisAAAGdCAYAAADT1TPdAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjguMiwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy8g+/7EAAAACXBIWXMAAA9hAAAPYQGoP6dpAAAzs0lEQVR4nO3deXyU9aHv8e9Mlsk62SZ7QsKOgGwBEdCqaLEVlfZYK61aPbXecr1W2p7qhaNX8bbWtqD3VE+1PdZqbdV63LVu0IIKbsgm+xoCgZBlkpCZbJNk5rl/TBJFIGSbeWYmn/frNa9JJrN8h4cwX57f7/k9FsMwDAEAAIQoq9kBAAAAekJZAQAAIY2yAgAAQhplBQAAhDTKCgAACGmUFQAAENIoKwAAIKRRVgAAQEiLNjvAQPl8PlVUVCg5OVkWi8XsOAAAoBcMw5Db7VZeXp6s1p73nYR9WamoqFBhYaHZMQAAQD+Ul5eroKCgx/uEfVlJTk6W5H+zdrvd5DQAAKA3XC6XCgsLuz/HexL2ZaVr6Mdut1NWAAAIM72ZwsEEWwAAENIoKwAAIKRRVgAAQEijrAAAgJBGWQEAACGNsgIAAEIaZQUAAIQ0ygoAAAhplBUAABDSKCsAACCkUVYAAEBIo6wAAICQFvYnMgQAAAPT0uZVfXOb6pradLy5XfXNbf5Lk//r6cVpunxSnmn5KCsAAESQdq+vu3h0Xeqb2lTXWTzqmto+v25qU11zm1rbfT0+p6fDR1kBAACn1tbhLx/ORo9qG/0lw9no6S4itV8oJbWNHrlaO/r1OjFRFqUmxCotIUZpCbH+S6L/62nD0gb5XfUNZQUAgCAyDEOu1o7u8uG/9qim0V82ahvbVNv0+c/6Uz4sFik1PkbpibHKSLQpLdH/dXqiv4SkJ8YqrevrzlKSZIuWxWIJwDseOMoKAAADZBiGGj0dqnF7VOP2yNnYphp3q2oaPXK62/zXjR45O3/W5u152OXLoqwWpSXEypEUq4ykWKUn2pTRWT78haTzuvNnKfExirKGZvHoD8oKAACn4fUZqm30qNrtUbW7VdUufxmpdndd+wtJjdtzxnkfX5Zki1ZGUqwcSbbOEmKTI8lfQhxJts6f+ctHanyMrBFUPvqKsgIAGHK8PkO1TR5VNXhU5WpVVWcRqXa3qsrlv63a7R+e8Rm9f94kW7Qyk23KTLLJkewvHf6vbd2lxJFkU2ayTXExUYF7gxGGsgIAiChNng5VulpV2dB5cbWqqvP7KrdHVQ3+vSHeXrYQq0VyJNmUZfcXj6zkOGUm+7/PSrZ1lhP/bfGxFJBAoKwAAMKGq7Vdx4636lhDiyobWnWss5Acc7WqsqFFxxpa5e7lhNSuEpKTEqesZJuy7HHKTo5Tlt2mbLu/lGTZbcpItEXU/I9wRFkBAISE1navKhtaVXG8RRVd151fHzvuLyKNnt4VkWRbtLJT4pRjj1O2PU45KTbl2OOUZffflpMSp4zEWEVHsZB7OKCsAACCoqGlXUfqm3W0vkVHj7foaH2LKhpadPR4q47Wt8jZ6OnV86TExyg3Jc5/SY1Xbmf5yOm8Ldsep+S4mAC/GwQTZQUAMCgamttVXt+sI/UtOtJ93dJdUNy92CsSF2NVXkq88tPilZcSr9zUOOWlfv51bkqcEmL56Bpq2OIAgF5pbffqSH2LyuuadbiuWeV1zSqvb1Z5XYvK65t7NVckIzFW+Wnxyk+NV16q//qL36clxITswmQwD2UFACDJv7DZ8eZ2ldU26XBdsw7V+i9d5aTS1XrG53AkxaogLUEFaf4SUtj5dUFavPJTEzhaBv1CWQGAIcQwDDkb21RW26QyZ5P/urZZh2ubVVbbdMa9I4mxUSpMT1BheoKGpSeoMC1ewzISOksJZQSBQVkBgAjU0NyuA85GlTmbdLDz4i8ozWc8oibHHqdhGQkqSk9QUcbnxaQoI5FhGpiCsgIAYard69Oh2maV1jTqQE2TSmsaddDZpFJnk+qa2k77OItFykuJ13BHooodCSpKT1SxI1FFGf5SwsqqCDWUFQAIca7Wdh2obtT+an8p2V/dqNKaRh2qa+5xFdZsu03DHYka7kjScEdC93VheoJs0RQShA/KCgCEiOPNbdpb1ah91W7tq/KXk/3VjT1ObE2IjdKIzESNzEzScEeiRmQmaYQjUcMdiUq08U88IgN/kwEgyNyt7dpb1ai9VW7tqXRrb5Vb+6obVeM+/aJoWck2jcpK0sjMpBOus+025pAg4lFWACBA2jp8KnU2avcxt3ZXurWn0qW9VY06erzltI/JT43X6Owkjc5K0uisZI3M8peSlHhWZMXQRVkBgEFQ4/Zo5zGXdh9zaXelW7uOuXSgplHt3lPPKclNidOY7GSNzUnWqKwkjcn2XycxdAOchN8KAOgDn8/Qwdom7ahwaWeFSzuP+a9Pd16bZFu0xuYka1xussbm2DUuJ1ljspPZUwL0AWUFAE6jw+vTvupGbTvaoB1HG7SjwqVdx1xqavOedF+LRRqekaizcu06KzdZ43LsGpebrPzUeOaUAANEWQEA+YvJ/ppGbS1v0Najx7XtqH9Ix9PhO+m+cTFWjcuxa3yeXRPy7Dor17/HhBPsAYHBbxaAIccwDJXVNuuz8uP67MhxbT3SoB0VDWptP7mYJNuiNSHfrol5KZqYn6IJeXYNdyQqOspqQnJgaKKsAIh4dU1t2lJery2Hj2tzub+cNLS0n3S/JFu0JubbdXZ+is4uSNXZ+SkqSk+Q1cowDmAmygqAiNLh9Wl3pVubDtdr06F6bS4/rkO1zSfdLzbaqgl5dk0uSNXkwhRNKkjV8IxEigkQgigrAMJaQ0u7Nh2u18ayem04VKetRxrUfIoJsCMyEzW1ME1ThqVqamGqxmQnKzaaoRwgHFBWAISViuMt+rSsTusP1mlDWb32VrtlfGkpk+S4aE0pTFVJUZqmDkvTlIJUpSRwqDAQrigrAEKWYRg66GzSJwfr9ElprT4tqz/l6q/FGQkqKUrX9OI0lRSlaVRmEsM5QAShrAAIGYZhqNTZpI8O1Orj0lp9crDupPPlRFktmpBn14zidM0oTlNJUboyk20mJQYQDJQVAKYqr2vWhwec+vBArT46UKvqL5WT2CirpgxL1czh6TpneLqmDktjSXpgiOE3HkBQ1TZ69OGBWn14wKl1+50qrztxWCc22qqSYWk6d0SGZo5I15TCVMXFRJmUFkAooKwACChPh1cby+r1/j6n1u6r0Y4K1wk/j7ZaNKUwVbNHZujckRmaNiyNcgLgBKaVlbKyMv385z/X6tWrVVlZqby8PF133XW68847FRsba1YsAIPgoLNJ7+2p1nt7a/RRae1JK8OOy0nWnFEOnTfKoRnD0xnWAdAj0/6F2L17t3w+n/7whz9o1KhR2r59u26++WY1NTVpxYoVZsUC0A+t7V59dKBWazoLypcXYctMtun80Q6dP9qhOaMcykqOMykpgHBkMYwvr1BgnuXLl+vRRx9VaWlprx/jcrmUkpKihoYG2e32AKYD8EVHj7do9e5qrdldrQ8POE/YexITZdH0onRdODZTXxmTqXE5yZx5GMAJ+vL5HVL7XhsaGpSent7jfTwejzyez48WcLlcPdwbwGDx+Qxtr2jQP3ZWadWuau06duLvXm5KnC4al6ULx2Rq9igHQzsABk3I/Gty4MABPfzww3rggQd6vN/999+ve++9N0ipgKGtrcOnj0tr9c6OSv1jV5WqXJ//R8FqkaYNS9Pcs7J00dgs9p4ACJhBHwZatmzZGcvEp59+qunTp3d/X1FRoQsuuEAXXHCB/vjHP/b42FPtWSksLGQYCBgkzW0dendPjd7ZUanVu6vlbu3o/llibJS+MiZTl5yVrYvGZSk9kcnwAPqnL8NAg15WnE6nnE5nj/cpLi5WXJx/gl1FRYUuuugizZw5U08++aSs1r6dWIw5K8DAuVvbtXp3td7aVql391afMP/EkWTTV8dna96EbM0emSFbNIcVAxg4U+esOBwOORyOXt336NGjuuiii1RSUqInnniiz0UFQP81eTr0z93Vev2zCr23t0ZtHZ8XlML0eH1tQo6+NjFHUwrTFMV5dgCYyLQ5KxUVFbrwwgs1bNgwrVixQjU1Nd0/y8nJMSsWENFa2716d0+1Xv/smP65u+qEPSgjHIn6+tk5+vrEXE3IszP/BEDIMK2srFy5Uvv379f+/ftVUFBwws9C6GhqIOx5fYY+OlCrV7cc1dvbK+X2fD4HpSgjQVdMytP8SblMkAUQskJqnZX+YM4KcGo7K1x6adMRvfpZxQlnLs5LidMVk/N0+aQ8TcxnDwoAc4TtOisABqba3arXtlToxU1HT1gHJTUhRpednasFk/M0ozhdVuagAAgjlBUgzLV7fVq9u1rPbyjXmj018vr8O0tjo6y6+KwsfXNqvi4cm6XYaCawAwhPlBUgTO2vduu5T8v18uajcja2dd8+dViqrppWoMsn5So1gXVQAIQ/ygoQRlrbvXpr+zE9+0m51pfVdd/uSLLpqpJ8XV1SqFFZSSYmBIDBR1kBwsD+6kY9/ckhvbTpqBpa2iVJUVaLLhqbpWtmFOrCsZmKiWKYB0BkoqwAIarD69M/dlXrLx+X6YP9td2356fGa+GMQl09vVA5KXEmJgSA4KCsACGmrqlNz64/rKc/PqSKhlZJksUiXTwuS9fOLNJXxmSyoiyAIYWyAoSIPZVuPfHBQb28+ag8nUvfpyfG6poZhfruOcNUmJ5gckIAMAdlBTCRYRh6d2+N/ri29IShnrPzU3Tj7GLNn5SruBhOHAhgaKOsACbwdHj16pYK/XFtqfZWNUqSrBbpaxNz9P05w1VSlMbKsgDQibICBJG7tV1//fiwnvjgoKo7l8BPskVr4YxC3TinWAVpDPUAwJdRVoAgqG306MkPy/Tkh2Vyt/pPJJhtt+n7c4brOzOHyR4XY3JCAAhdlBUggCobWvWH9w/o2fWH1drunzQ7MjNRiy4YqQVT8lkCHwB6gbICBEBlQ6sefXe/nl1frjavv6ScnZ+i/3XRSM0bn8OJBAGgDygrwCA6VUmZUZymH80drfNHO5g0CwD9QFkBBkFto0ePvHtAf/n4kNo610g5pzhdP75ktGaNzKCkAMAAUFaAAXC1tuuP75fq8XUH1dTmleTfk/KTS8ZQUgBgkFBWgH5obffqqY/K9Ls1B7pPLHh2fopuv3Qswz0AMMgoK0Af+HyGXvusQsvf2aOjx1skSaOykvSzeWN06YQcSgoABABlBeilD/c79cu3dmn7UZckKccep5/OG6OrphVwYkEACCDKCnAGZc4m3ffmLq3aWSXJv+Ls/7xwpL4/Z7jiYzlvDwAEGmUFOI1GT4f+c/V+/WndQbV5fYqyWnTtzGFafPFoZSTZzI4HAEMGZQX4EsMw9NKmo/rV27tV03n+nvNHO3T35eM1OjvZ5HQAMPRQVoAv2FPp1v95ZbvWl9VJkoozEvR/Lh+vueOymDwLACahrACSmjwd+u0/9+nxdQfl9RmKj4nSbReP1vfPK5YtmnkpAGAmygqGvJU7KnXPazt0rKFVknTphGzdfcUE5afGm5wMACBRVjCEVbtbtey1HXpzW6UkaVh6gu69coIuGpdlcjIAwBdRVjDkGIah/95Qrvve2CVXa4eirBb98CsjdNvFoxUXw5APAIQaygqGlPK6Zv3vF7fqwwO1kvxL5P/6qkkan2c3ORkA4HQoKxgSDMPQc5+W6+d/36mmNq/iYqz62byxunF2saKjrGbHAwD0gLKCiFfZ0KolL23Vu3tqJEnTi9K04urJKnYkmpwMANAblBVEtNc+q9BdL2+Tq7VDsdFW3T5vrL5/3nDO5QMAYYSygojU6OnQ3a9u10ubjkqSJhWk6MFvT9aoLFagBYBwQ1lBxNl8uF6L/7ZFh+uaZbVIt140Sj+6eLRimJsCAGGJsoKI4fMZevS9A3pw1V55fYbyU+P1HwunaEZxutnRAAADQFlBRKht9OjHz23R2n1OSdIVk/P0i29MVEp8jMnJAAADRVlB2Pu0rE4/emazKl2tioux6ucLJupbJQWceBAAIgRlBWHL5zP02NpS/eadPfL6DI3MTNQj15ZobA6TaAEgklBWEJYaPR366XNbtHJnlSRpwZQ8/fKbZyvRxl9pAIg0/MuOsHPQ2aT/8dQG7atuVGyUVfdcOV7fPWcYwz4AEKEoKwgra3ZX67a/bZa7tUPZdpt+f12Jpg5LMzsWACCAKCsIC4Zh6JF3D2jFyj0yDKmkKE2PXjdNWclxZkcDAAQYZQUhz9Ph1ZIXt+nlzf7VaK+dOUz3XDFBsdEs8gYAQwFlBSGtvqlNP/zLRq0vq1OU1aL/u2CCrp1ZZHYsAEAQUVYQskprGvX9Jz9VWW2zkm3ReuS6aTp/dKbZsQAAQUZZQUj6pLRW/+MvG9XQ0q6CtHg9ceMMjc5m/RQAGIooKwg5b28/ptv+tkVtHT5NKUzVY9+brsxkm9mxAAAmoawgpDzzyWHd9co2+Qxp3vhsPfSdqYqLiTI7FgDARJQVhATDMPTw6v16cNVeSdJ3zinUzxdMVHQUR/wAwFBHWYHpfD5Dy17foac+OiRJ+tHcUfrpV8ewIi0AQBJlBSbr8Pp0xwtb9dLmo7JYpHsuH68b5ww3OxYAIIRQVmCadq9PP3lui/6+9ZiirBY9+O3JWjAl3+xYAIAQQ1mBKTwdXv3omc1aubNKMVEWPfydafraxByzYwEAQhBlBUHX2u7Vor9u1Lt7ahQbbdXvr5umueOyzY4FAAhRlBUEVWu7Vzc/tUFr9zkVF2PVY9+bzqq0AIAeUVYQNG0dPt3y9Cat3edUQmyU/nTjDJ07IsPsWACAEMciFgiKDq9Pi/+2Wat3V8sWbdXjN1BUAAC9Q1lBwHl9hv7t+c/01vZKxUZZ9V/fm65ZIykqAIDeoawgoHw+Q0tf2qpXt1Qo2mrRI9dO0wVjmKMCAOg9ygoC6pdv7tJ/bzgiq0X67cKpumQ8R/0AAPqGsoKAeez9Uv1x3UFJ0vJvTdb8SbkmJwIAhCPKCgLi5c1HdN+buyRJ/37ZOF1VUmByIgBAuKKsYNC9v7dGtz+/VZJ003nDdfP5I0xOBAAIZyFRVjwej6ZMmSKLxaItW7aYHQcDsPXIcS3660Z1+AxdOTlPd152FmdPBgAMSEiUlTvuuEN5eXlmx8AAHalv1vef/FTNbV6dN8qhFVdPltVKUQEADIzpZeWtt97SypUrtWLFCrOjYAAaPR36wZ83yNnYprNy7Xr0ummKjTb9rxcAIAKYutx+VVWVbr75Zr3yyitKSEjo1WM8Ho88Hk/39y6XK1Dx0Eten6HFz27W7kq3HEk2PX7DdCXHxZgdCwAQIUz7r69hGLrxxhu1aNEiTZ8+vdePu//++5WSktJ9KSwsDGBK9Mav396tf+6uVmy0VY99r0R5qfFmRwIARJBBLyvLli2TxWLp8bJhwwY9/PDDcrlcWrp0aZ+ef+nSpWpoaOi+lJeXD/ZbQB889+lh/df7pZKkFVdP1tRhaSYnAgBEGothGMZgPqHT6ZTT6ezxPsXFxVq4cKFef/31E44U8Xq9ioqK0rXXXqs///nPvXo9l8ullJQUNTQ0yG63Dyg7+mb9wTpd+8eP1e41tPji0frJV8eYHQkAECb68vk96GWltw4fPnzCfJOKigpdeumleuGFFzRz5kwVFPRuETHKijmqXK2a/9A6ORs9unxSrh7+zlQOUQYA9FpfPr9Nm2A7bNiwE75PSkqSJI0cObLXRQXmaPf69L+e3iRno0fjcpK1/FuTKSoAgIDh2FL02S/f3KUNh+qVbIvWo9eVKD42yuxIAIAIZuqhy19UXFwsk0ak0AevfVahJz4okyQ98O3JGu5INDcQACDisWcFvba3yq3//YL/nD+3XDhS8ybkmJwIADAUUFbQK02eDi3660a1tHs1Z1SG/m3eWLMjAQCGCMoKemXZaztUWtOkHHucHlo4VVGc8wcAECSUFZzR659V6PmNR2SxSP+xcIoykmxmRwIADCGUFfSovK5Z//7yNknSrReN0rkjMkxOBAAYaigrOK0Or08/fm6L3K0dmjYsVYsvHm12JADAEERZwWk9tHq/Nnaup/LbhVMVHcVfFwBA8PHpg1Naf7BO/7l6nyTpF9+cqML0BJMTAQCGKsoKTtLc1qF/e36LfIb0L9PytWBKvtmRAABDGGUFJ/nN23tUXteivJQ43XvlBLPjAACGOMoKTvBxaa2e/LBMkvSrqyYpOS7G3EAAgCGPsoJuzW0duqNzOf3vnFOor4zJNDkRAACUFXzBb97eo8N1zcpLidO/X3aW2XEAAJBEWUGnTxj+AQCEKMoK1NLm1R0v+od/Fs5g+AcAEFooK9B/rtmnQ7XNyk2J07/PZ/gHABBaKCtD3P5qt/7r/VJJ0rIrJ8jO8A8AIMRQVoYwwzB01yvb1e41dPG4LM0bn212JAAATkJZGcJe2XJUH5fWKS7GqmVXTpDFYjE7EgAAJ6GsDFENLe26741dkqQfzR3NuX8AACGLsjJErXhnj5yNbRqZmaibzx9hdhwAAE6LsjIEfVZ+XH/95JAk6effmKjYaP4aAABCF59SQ4zPZ+ju13bIMKRvTs3X7JEOsyMBANAjysoQ8/rWCn1WflyJsVFaetk4s+MAAHBGlJUhpLXdq1+/tVuSdMtFo5SVHGdyIgAAzoyyMoQ8vu6gKhpalZcSp5vOG252HAAAeoWyMkTUuD16ZM1+SdIdXxunuJgokxMBANA7lJUh4sFVe9XU5tXkghRdOTnP7DgAAPQaZWUI2FPp1nOfHpYk3XX5eFmtrFQLAAgflJUh4L43d8lnSF+fmKMZxelmxwEAoE8oKxFu7b4avb+3RjFRFi35OocqAwDCD2UlghmGoRUr90qSrju3SEUZiSYnAgCg7ygrEWz17mp9Vn5c8TFRuuXCUWbHAQCgXygrEcowDD24yr9X5Xuzi5SZbDM5EQAA/UNZiVDv7KjUjgqXEmOj9MOvjDQ7DgAA/UZZiUA+n6H/t2qfJOn75w1XemKsyYkAAOg/ykoE+vu2Y9pT5ZY9Llo/OH+E2XEAABgQykqE6fD69B//8M9Vufn8EUqJjzE5EQAAA0NZiTCvbKlQaU2T0hJi9K+crBAAEAEoKxHE6zP0n6v9c1V+eMFIJdmiTU4EAMDAUVYiyFvbj6mstlmpCTH63qwis+MAADAoKCsRwjAM/f69A5KkG2YVKyGWvSoAgMhAWYkQH+yv1fajLsXHROmG2cVmxwEAYNBQViLEo+/tlyRdM6OQdVUAABGFshIBth1p0Af7axVltegH53MEEAAgslBWIkDXXJUFk/NUkJZgchoAAAYXZSXMHXQ26a3txyT5D1cGACDSUFbC3H+9XyqfIc0dl6WxOclmxwEAYNBRVsJYtbtVL246IklaxF4VAECEoqyEsb9+dEhtHT5NG5aqGcVpZscBACAgKCthqq3Dp2fWl0uSbjpvhCwWi8mJAAAIDMpKmHpr+zE5Gz3Ktts0b0K22XEAAAgYykqYeuqjQ5Kka2cWKSaKzQgAiFx8yoWh7UcbtPFQvWKiLFp4TqHZcQAACCjKShh66qMySdJlZ+cqKznO3DAAAAQYZSXM1De16dUtFZKk780qNjcMAABBQFkJM/+9oVyeDp8m5Nk1bViq2XEAAAg4ykoY8foM/eVj/8TaG2YVc7gyAGBIoKyEkTW7q3WkvkWpCTG6ckqe2XEAAAgKykoY+XPnxNprphcqLibK3DAAAAQJZSVMlNc1a+0+pywW6bpzi8yOAwBA0FBWwsQLG/0nLJwz0qHC9AST0wAAEDyUlTDg8xndZeXq6QUmpwEAILgoK2Hg49JaHT3eouS4aF06IcfsOAAABJXpZeWNN97QzJkzFR8fL4fDoX/5l38xO1LIeb5zr8oVk/OYWAsAGHKizXzxF198UTfffLN++ctfau7cuTIMQ9u2bTMzUshxtbbrre3HJElXlzAEBAAYekwrKx0dHVq8eLGWL1+um266qfv2sWPHmhUpJL2x9Zha230alZWkKYWpZscBACDoTBsG2rRpk44ePSqr1aqpU6cqNzdXX//617Vjx44eH+fxeORyuU64RLLnN5RL8u9VYcVaAMBQZFpZKS0tlSQtW7ZMd911l/7+978rLS1NF1xwgerq6k77uPvvv18pKSndl8LCwmBFDrr91W5tOnxcUVaLvjkt3+w4AACYYtDLyrJly2SxWHq8bNiwQT6fT5J055136qqrrlJJSYmeeOIJWSwWPf/886d9/qVLl6qhoaH7Ul5ePthvIWR0Tay9aGymspLjTE4DAIA5Bn3Oyq233qqFCxf2eJ/i4mK53W5J0vjx47tvt9lsGjFihA4fPnzax9psNtlstsEJG8I6vD69tOmoJOlbJZG79wgAgDMZ9LLicDjkcDjOeL+SkhLZbDbt2bNH5513niSpvb1dZWVlKipiOfn399Woxu1RemKs5o7LMjsOAACmMe1oILvdrkWLFumee+5RYWGhioqKtHz5cknS1VdfbVaskPHK5gpJ0oIpeYqNNn05HAAATGPqOivLly9XdHS0rr/+erW0tGjmzJlavXq10tLSzIxlupY2r/6xq0qSdOXkPJPTAABgLlPLSkxMjFasWKEVK1aYGSPkrNlTreY2rwrS4llbBQAw5DG+EIL+vtU/BDR/Ui5rqwAAhjzKSohp8nRo9e5qSdIVkxgCAgCAshJi/rGrSq3tPhVnJGhCnt3sOAAAmI6yEmL+vtV/0sLLJ+UxBAQAgCgrIcXV2q739tRIki6fnGtyGgAAQgNlJYSs2lGlNq//DMtjs5PNjgMAQEigrISQ7qOAzuYoIAAAulBWQkRDc7vW7nNKkq5gCAgAgG6UlRDxzo5KdfgMjctJ1qgshoAAAOhCWQkRr3cOAV0+ib0qAAB8EWUlBNQ3tenDA7WS/IcsAwCAz1FWQsC7e6vl7RwCKnYkmh0HAICQQlkJAf/Y5V9e/5Kzsk1OAgBA6KGsmKytw9e9ENzFZ2WZnAYAgNBDWTHZ+oN1avR0yJFk0+SCVLPjAAAQcigrJvvHripJ0txxmbJaWQgOAIAvo6yYyDAM/XO3v6xczHwVAABOibJion3VjSqva1FstFXnj3aYHQcAgJBEWTHRqp3+vSpzRmYoITba5DQAAIQmyoqJ/rmLISAAAM6EsmISZ6NHm8uPS+KQZQAAekJZMcma3dUyDGlCnl25KfFmxwEAIGRRVkzyT1atBQCgVygrJmht9+r9ff5VaykrAAD0jLJigo9La9Xc5lW23aaJ+Xaz4wAAENIoKyZYvds/BDR3XLYsFlatBQCgJ5QVE6zb55QkXTg20+QkAACEPspKkB093qJSZ5OsFmnWyAyz4wAAEPIoK0H2wX7/XpXJhamyx8WYnAYAgNBHWQmyrrJy/ijOBQQAQG9QVoLIMIzusjKHsgIAQK9QVoJoT5VbzsY2xcdEaeqwNLPjAAAQFigrQdR1FNDMEemKjeaPHgCA3uATM4jWdQ4BnccQEAAAvUZZCZK2Dp8+Ka2TxHwVAAD6grISJJsP16ul3StHUqzGZiebHQcAgLBBWQmSLx4FZLWyxD4AAL1FWQmSdRyyDABAv1BWgsDV2q7PjjRIoqwAANBXlJUg+KS0Tl6foRGOROWnxpsdBwCAsEJZCYJ1+2oksVcFAID+oKwEAfNVAADoP8pKgFU2tOpATZOsFmnWyAyz4wAAEHYoKwG2vsy/ENyEvBSlxMeYnAYAgPBDWQmwDZ1lZXoxJy4EAKA/KCsBtqGsXpI0ozjd5CQAAIQnykoAuVrbtbvSJUmaXsSeFQAA+oOyEkCbDx+Xz5CGpScoyx5ndhwAAMISZSWANjJfBQCAAaOsBNCnnfNVphcxXwUAgP6irARIu9enzeVdk2vZswIAQH9RVgJkZ4VLre0+pSbEaGRmktlxAAAIW5SVAPm0c75KybA0Wa0Wk9MAABC+KCsBsvFQ53wV1lcBAGBAKCsBYBjG55Nrma8CAMCAUFYC4FBts5yNHsVGWXV2forZcQAACGuUlQDY0DkENKkgRXExUSanAQAgvFFWAqDr5IUlDAEBADBglJUA6DoSaAaLwQEAMGCUlUFW19SmAzVNkqQSTl4IAMCAUVYGWdchy6OykpSWGGtyGgAAwh9lZZBtONQ5BMR8FQAABgVlZZBt6tyzUsJ8FQAABgVlZRB5fYa2H3VJkqYUsr4KAACDwdSysnfvXi1YsEAOh0N2u11z5szRmjVrzIw0IAdqGtXS7lVCbJSGOzh5IQAAg8HUsjJ//nx1dHRo9erV2rhxo6ZMmaLLL79clZWVZsbqt21HGiRJE/NSFMXJCwEAGBSmlRWn06n9+/dryZIlmjRpkkaPHq1f/epXam5u1o4dO8yKNSDbjvrLytkFDAEBADBYTCsrGRkZOuuss/TUU0+pqalJHR0d+sMf/qDs7GyVlJSc9nEej0cul+uES6jYeuS4JHE+IAAABlG0WS9ssVi0atUqLViwQMnJybJarcrOztbbb7+t1NTU0z7u/vvv17333hu8oL3U4fVp5zF/cWLPCgAAg2fQ96wsW7ZMFoulx8uGDRtkGIZuueUWZWVlae3atVq/fr0WLFigyy+/XMeOHTvt8y9dulQNDQ3dl/Ly8sF+C/2yv6ZRre0+JdmiNTwj0ew4AABEDIthGMZgPqHT6ZTT6ezxPsXFxfrggw80b9481dfXy263d/9s9OjRuummm7RkyZJevZ7L5VJKSooaGhpOeJ5g++8N5brjha2aOTxdz/1wlmk5AAAIB335/B70YSCHwyGHw3HG+zU3N0uSrNYTd+5YrVb5fL7BjhVw2zsn105iCAgAgEFl2gTbWbNmKS0tTTfccIM+++wz7d27V7fffrsOHjyo+fPnmxWr37Ye6ToSKNXcIAAARBjTyorD4dDbb7+txsZGzZ07V9OnT9e6dev06quvavLkyWbF6pf2L06u5UggAAAGlWlHA0nS9OnT9c4775gZYVDsrXKrrcOn5LhoFaUnmB0HAICIwrmBBkHXfJWz81NkZeVaAAAGFWVlEHTPV2EICACAQUdZGQQssw8AQOBQVgaorcOn3cfcktizAgBAIFBWBmhvlVttXp/scdEaxuRaAAAGHWVlgLrmq0wqSJXFwuRaAAAGG2VlgLrmq0xkCAgAgICgrAzQtqPHJbHMPgAAgUJZGQBPh1d7KplcCwBAIFFWBmBPpVvtXkOpCTEqSIs3Ow4AABGJsjIAuzrPBzQhz87kWgAAAoSyMgC7O4eAxmbbTU4CAEDkoqwMwN4qf1kZl5NschIAACIXZWUA9lQ2SpLGUFYAAAgYyko/1TZ65Gz0SJJGZyWZnAYAgMhFWemnPZ1DQMPSE5RoizY5DQAAkYuy0k97OyfXjslmCAgAgECirPTTnir/fJWxOQwBAQAQSJSVftpT6V9jZWwOhy0DABBIlJV+MAxDe7v2rDAMBABAQFFW+qGioVWNng5FWy0a7kg0Ow4AABGNstIPXUNAIzITFRvNHyEAAIHEJ20/dC0Gx3wVAAACj7LSD13L7I/N5kggAAACjbLSD3tYYwUAgKChrPRRh9en/TX+YaBxDAMBABBwlJU+KqttVluHT/ExUSpIizc7DgAAEY+y0kdd81XGZCfJarWYnAYAgMhHWemj3Z3zVcbmMF8FAIBgoKz0EScwBAAguCgrfdR92DJ7VgAACArKSh+0tntVVtskiXMCAQAQLJSVPthf3SifIaUlxCgz2WZ2HAAAhgTKSh98cTE4i4UjgQAACAbKSh8wXwUAgOCjrPQBhy0DABB8lJU+2F/tX2afw5YBAAgeykovtbZ7VdHQIkka4Ug0OQ0AAEMHZaWXDtU2yzCk5LhopSfGmh0HAIAhg7LSSwed/vVVhjsSORIIAIAgoqz00hfLCgAACB7KSi+VdZaV4gzKCgAAwURZ6aWuPSsjMikrAAAEE2Wllw7WsmcFAAAzUFZ6wd3arhq3R5JUzJwVAACCirLSC4dqmyVJGYmxSomPMTkNAABDC2WlF0o5EggAANNQVnqh+0ggygoAAEFHWekF1lgBAMA8lJVeoKwAAGAeykovUFYAADAPZeUM6pva1NDSLok1VgAAMANl5Qy6FoPLTYlTfGyUyWkAABh6KCtncLCGlWsBADATZeUMyjr3rAznnEAAAJiCsnIG3QvCsWcFAABTUFbOoIwjgQAAMBVlpQeGYXQftszqtQAAmIOy0oMat0fNbV5ZLdKw9ASz4wAAMCRRVnrQNV+lIC1BsdH8UQEAYAY+gXvACQwBADAfZaUHXfNVRlBWAAAwDWWlB92TazOYrwIAgFkCWlbuu+8+zZ49WwkJCUpNTT3lfQ4fPqwrrrhCiYmJcjgcuu2229TW1hbIWL3WfQLDzCSTkwAAMHRFB/LJ29radPXVV2vWrFl6/PHHT/q51+vV/PnzlZmZqXXr1qm2tlY33HCDDMPQww8/HMhoZ+T1GTpU1yyJBeEAADBTQMvKvffeK0l68sknT/nzlStXaufOnSovL1deXp4k6YEHHtCNN96o++67T3a7PZDxelRxvEVtHT7FRFmUnxZvWg4AAIY6U+esfPTRR5o4cWJ3UZGkSy+9VB6PRxs3bjzlYzwej1wu1wmXQOg6J9Cw9ARFWS0BeQ0AAHBmppaVyspKZWdnn3BbWlqaYmNjVVlZecrH3H///UpJSem+FBYWBiRb93wVB/NVAAAwU5/LyrJly2SxWHq8bNiwodfPZ7GcvNfCMIxT3i5JS5cuVUNDQ/elvLy8r2+hVyYXpOpHc0dp/qScgDw/AADonT7PWbn11lu1cOHCHu9TXFzcq+fKycnRJ598csJt9fX1am9vP2mPSxebzSabzdar5x+IyYWpmlyYGvDXAQAAPetzWXE4HHI4HIPy4rNmzdJ9992nY8eOKTc3V5J/0q3NZlNJScmgvAYAAAhvAT0a6PDhw6qrq9Phw4fl9Xq1ZcsWSdKoUaOUlJSkefPmafz48br++uu1fPly1dXV6Wc/+5luvvlmU48EAgAAoSOgZeXuu+/Wn//85+7vp06dKklas2aNLrzwQkVFRemNN97QLbfcojlz5ig+Pl7f/e53tWLFikDGAgAAYcRiGIZhdoiBcLlcSklJUUNDA3tjAAAIE335/ObcQAAAIKRRVgAAQEijrAAAgJBGWQEAACGNsgIAAEIaZQUAAIQ0ygoAAAhplBUAABDSKCsAACCkBXS5/WDoWoDX5XKZnAQAAPRW1+d2bxbSD/uy4na7JUmFhYUmJwEAAH3ldruVkpLS433C/txAPp9PFRUVSk5OlsViMTtOSHK5XCosLFR5eTnnTwoBbI/QwvYILWyP0BOobWIYhtxut/Ly8mS19jwrJez3rFitVhUUFJgdIyzY7XZ++UMI2yO0sD1CC9sj9ARim5xpj0oXJtgCAICQRlkBAAAhjbIyBNhsNt1zzz2y2WxmR4HYHqGG7RFa2B6hJxS2SdhPsAUAAJGNPSsAACCkUVYAAEBIo6wAAICQRlkBAAAhjbISIR555BENHz5ccXFxKikp0dq1a09735deeklf/epXlZmZKbvdrlmzZumdd94JYtrI15ft8UUffPCBoqOjNWXKlMAGHGL6uj08Ho/uvPNOFRUVyWazaeTIkfrTn/4UpLSRr6/b4+mnn9bkyZOVkJCg3Nxc/eu//qtqa2uDlDayvf/++7riiiuUl5cni8WiV1555YyPee+991RSUqK4uDiNGDFCv//97wMf1EDY+9vf/mbExMQYjz32mLFz505j8eLFRmJionHo0KFT3n/x4sXGr3/9a2P9+vXG3r17jaVLlxoxMTHGpk2bgpw8MvV1e3Q5fvy4MWLECGPevHnG5MmTgxN2COjP9rjyyiuNmTNnGqtWrTIOHjxofPLJJ8YHH3wQxNSRq6/bY+3atYbVajV++9vfGqWlpcbatWuNCRMmGN/4xjeCnDwyvfnmm8add95pvPjii4Yk4+WXX+7x/qWlpUZCQoKxePFiY+fOncZjjz1mxMTEGC+88EJAc1JWIsA555xjLFq06ITbxo0bZyxZsqTXzzF+/Hjj3nvvHexoQ1J/t8c111xj3HXXXcY999xDWRlEfd0eb731lpGSkmLU1tYGI96Q09ftsXz5cmPEiBEn3PbQQw8ZBQUFAcs4VPWmrNxxxx3GuHHjTrjthz/8oXHuuecGMJlhMAwU5tra2rRx40bNmzfvhNvnzZunDz/8sFfP4fP55Ha7lZ6eHoiIQ0p/t8cTTzyhAwcO6J577gl0xCGlP9vjtdde0/Tp0/Wb3/xG+fn5GjNmjH72s5+ppaUlGJEjWn+2x+zZs3XkyBG9+eabMgxDVVVVeuGFFzR//vxgRMaXfPTRRydtv0svvVQbNmxQe3t7wF437E9kONQ5nU55vV5lZ2efcHt2drYqKyt79RwPPPCAmpqa9O1vfzsQEYeU/myPffv2acmSJVq7dq2io/mVHEz92R6lpaVat26d4uLi9PLLL8vpdOqWW25RXV0d81YGqD/bY/bs2Xr66ad1zTXXqLW1VR0dHbryyiv18MMPByMyvqSysvKU26+jo0NOp1O5ubkBeV32rEQIi8VywveGYZx026k8++yzWrZsmZ577jllZWUFKt6Q09vt4fV69d3vflf33nuvxowZE6x4Q05ffj98Pp8sFouefvppnXPOObrsssv04IMP6sknn2TvyiDpy/bYuXOnbrvtNt19993auHGj3n77bR08eFCLFi0KRlScwqm236luH0z8Ny7MORwORUVFnfS/kurq6pPa75c999xzuummm/T888/rkksuCWTMIaOv28PtdmvDhg3avHmzbr31Vkn+D0vDMBQdHa2VK1dq7ty5Qckeifrz+5Gbm6v8/PwTTl1/1llnyTAMHTlyRKNHjw5o5kjWn+1x//33a86cObr99tslSZMmTVJiYqLOP/98/eIXvwjY/+Rxajk5OafcftHR0crIyAjY67JnJczFxsaqpKREq1atOuH2VatWafbs2ad93LPPPqsbb7xRzzzzDGO/g6iv28Nut2vbtm3asmVL92XRokUaO3astmzZopkzZwYrekTqz+/HnDlzVFFRocbGxu7b9u7dK6vVqoKCgoDmjXT92R7Nzc2yWk/8qIqKipL0+f/oETyzZs06afutXLlS06dPV0xMTOBeOKDTdxEUXYcCPv7448bOnTuNH//4x0ZiYqJRVlZmGIZhLFmyxLj++uu77//MM88Y0dHRxu9+9zvj2LFj3Zfjx4+b9RYiSl+3x5dxNNDg6uv2cLvdRkFBgfGtb33L2LFjh/Hee+8Zo0ePNn7wgx+Y9RYiSl+3xxNPPGFER0cbjzzyiHHgwAFj3bp1xvTp041zzjnHrLcQUdxut7F582Zj8+bNhiTjwQcfNDZv3tx9KPmXt0fXocs/+clPjJ07dxqPP/44hy6j9373u98ZRUVFRmxsrDFt2jTjvffe6/7ZDTfcYFxwwQXd319wwQWGpJMuN9xwQ/CDR6i+bI8vo6wMvr5uj127dhmXXHKJER8fbxQUFBg//elPjebm5iCnjlx93R4PPfSQMX78eCM+Pt7Izc01rr32WuPIkSNBTh2Z1qxZ0+Pnwam2x7vvvmtMnTrViI2NNYqLi41HH3004DkthsF+NAAAELqYswIAAEIaZQUAAIQ0ygoAAAhplBUAABDSKCsAACCkUVYAAEBIo6wAAICQRlkBAAAhjbICAABCGmUFAACENMoKAAAIaZQVAAAQ0v4/h5TjieVvGuwAAAAASUVORK5CYII=",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# Final consumption function c=m\n",
    "m = np.linspace(0.1, 1, 100)\n",
    "plt.plot(m, IndShockExample.solution_terminal.vFunc(m))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Solving the problem"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This solution is generated by invoking `solve()` which is a **method** that is an **attribute** of the `IndShockExample` object. **Methods** in Python are supposed to have **documentation** that tell you what they do. You can read the documentation for methods and other attributes in HARK with the built-in Python `help()` function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on method solve in module HARK.core:\n",
      "\n",
      "solve(verbose=False) method of HARK.ConsumptionSaving.ConsIndShockModel.IndShockConsumerType instance\n",
      "    Solve the model for this instance of an agent type by backward induction.\n",
      "    Loops through the sequence of one period problems, passing the solution\n",
      "    from period t+1 to the problem for period t.\n",
      "    \n",
      "    Parameters\n",
      "    ----------\n",
      "    verbose : boolean\n",
      "        If True, solution progress is printed to screen.\n",
      "    \n",
      "    Returns\n",
      "    -------\n",
      "    none\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(IndShockExample.solve)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Finite or Infinite Horizon?\n",
    "\n",
    "$\\texttt{ConsIndShockType}$ can solve either finite-horizon (e.g., life-cycle) problems, or infinite-horizon problems (where the problem is the same in every period).  Elsewhere you can find documentation about the finite horizon solution; here we are interested in the infinite-horizon solution which is obtained (by definition) when iterating one more period yields a solution that is essentially the same.  In the dictionary above we signaled to HARK that we want the infinite horizon solution by setting the \"cycles\" paramter to zero:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "IndShockExample.cycles  # Infinite horizon solution is computed when cycles = 0"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Finished cycle #1 in 0.0013821125030517578 seconds, solution distance = 100.0\n",
      "Finished cycle #2 in 0.001065969467163086 seconds, solution distance = 10.088015890333436\n",
      "Finished cycle #3 in 0.0009438991546630859 seconds, solution distance = 3.353411473658973\n",
      "Finished cycle #4 in 0.0008041858673095703 seconds, solution distance = 1.6699529613894324\n",
      "Finished cycle #5 in 0.0008709430694580078 seconds, solution distance = 0.9967360674688521\n",
      "Finished cycle #6 in 0.0008738040924072266 seconds, solution distance = 0.6602619046109481\n",
      "Finished cycle #7 in 0.0009212493896484375 seconds, solution distance = 0.46809484231437537\n",
      "Finished cycle #8 in 0.0008640289306640625 seconds, solution distance = 0.3480770650100675\n",
      "Finished cycle #9 in 0.0008878707885742188 seconds, solution distance = 0.2681341538834978\n",
      "Finished cycle #10 in 0.000885009765625 seconds, solution distance = 0.21223248168627507\n",
      "Finished cycle #11 in 0.0009639263153076172 seconds, solution distance = 0.17162798586899441\n",
      "Finished cycle #12 in 0.0009870529174804688 seconds, solution distance = 0.14121714401876506\n",
      "Finished cycle #13 in 0.0009548664093017578 seconds, solution distance = 0.11786112023934425\n",
      "Finished cycle #14 in 0.0011670589447021484 seconds, solution distance = 0.09954374358267515\n",
      "Finished cycle #15 in 0.0010912418365478516 seconds, solution distance = 0.08492077965589928\n",
      "Finished cycle #16 in 0.0009837150573730469 seconds, solution distance = 0.07306820983636841\n",
      "Finished cycle #17 in 0.0009441375732421875 seconds, solution distance = 0.06333371450893699\n",
      "Finished cycle #18 in 0.0009338855743408203 seconds, solution distance = 0.055246317280595036\n",
      "Finished cycle #19 in 0.0009322166442871094 seconds, solution distance = 0.048458869265386006\n",
      "Finished cycle #20 in 0.0009219646453857422 seconds, solution distance = 0.04271110960013802\n",
      "Finished cycle #21 in 0.0009219646453857422 seconds, solution distance = 0.03780486582230225\n",
      "Finished cycle #22 in 0.0009200572967529297 seconds, solution distance = 0.03358704056809447\n",
      "Finished cycle #23 in 0.0009129047393798828 seconds, solution distance = 0.02993783577570497\n",
      "Finished cycle #24 in 0.001096963882446289 seconds, solution distance = 0.026762425833982917\n",
      "Finished cycle #25 in 0.0010001659393310547 seconds, solution distance = 0.023984959744489665\n",
      "Finished cycle #26 in 0.0009191036224365234 seconds, solution distance = 0.02154418103929423\n",
      "Finished cycle #27 in 0.0008988380432128906 seconds, solution distance = 0.019390181762538816\n",
      "Finished cycle #28 in 0.0009031295776367188 seconds, solution distance = 0.017481967390489128\n",
      "Finished cycle #29 in 0.0009517669677734375 seconds, solution distance = 0.015785611379662612\n",
      "Finished cycle #30 in 0.0009629726409912109 seconds, solution distance = 0.014272839895085987\n",
      "Finished cycle #31 in 0.0009331703186035156 seconds, solution distance = 0.012919936192925974\n",
      "Finished cycle #32 in 0.0010046958923339844 seconds, solution distance = 0.011706884785618321\n",
      "Finished cycle #33 in 0.0010633468627929688 seconds, solution distance = 0.010616703056517629\n",
      "Finished cycle #34 in 0.0009469985961914062 seconds, solution distance = 0.009634898474988773\n",
      "Finished cycle #35 in 0.0009288787841796875 seconds, solution distance = 0.00874904442067903\n",
      "Finished cycle #36 in 0.0009279251098632812 seconds, solution distance = 0.007948413988064118\n",
      "Finished cycle #37 in 0.0009229183197021484 seconds, solution distance = 0.00722372447082309\n",
      "Finished cycle #38 in 0.0009169578552246094 seconds, solution distance = 0.006566906564932307\n",
      "Finished cycle #39 in 0.0009112358093261719 seconds, solution distance = 0.005970916077072452\n",
      "Finished cycle #40 in 0.0009169578552246094 seconds, solution distance = 0.005429579002498741\n",
      "Finished cycle #41 in 0.0009570121765136719 seconds, solution distance = 0.004937463273915643\n",
      "Finished cycle #42 in 0.000865936279296875 seconds, solution distance = 0.004489772052598262\n",
      "Finished cycle #43 in 0.0008499622344970703 seconds, solution distance = 0.004082254546442954\n",
      "Finished cycle #44 in 0.0008449554443359375 seconds, solution distance = 0.003711131170160087\n",
      "Finished cycle #45 in 0.0008451938629150391 seconds, solution distance = 0.003373030500466001\n",
      "Finished cycle #46 in 0.0008478164672851562 seconds, solution distance = 0.0030649359736791837\n",
      "Finished cycle #47 in 0.0008420944213867188 seconds, solution distance = 0.0027841406665807256\n",
      "Finished cycle #48 in 0.0008480548858642578 seconds, solution distance = 0.0025282088157063676\n",
      "Finished cycle #49 in 0.0008378028869628906 seconds, solution distance = 0.002294942975414216\n",
      "Finished cycle #50 in 0.0008482933044433594 seconds, solution distance = 0.0020823559119378388\n",
      "Finished cycle #51 in 0.0008466243743896484 seconds, solution distance = 0.0018886464739744646\n",
      "Finished cycle #52 in 0.0009682178497314453 seconds, solution distance = 0.0017121788176552855\n",
      "Finished cycle #53 in 0.0010418891906738281 seconds, solution distance = 0.0015514644867238303\n",
      "Finished cycle #54 in 0.0010409355163574219 seconds, solution distance = 0.0014051468883895524\n",
      "Finished cycle #55 in 0.0009162425994873047 seconds, solution distance = 0.0012719878080496017\n",
      "Finished cycle #56 in 0.0008678436279296875 seconds, solution distance = 0.0011508556554602478\n",
      "Finished cycle #57 in 0.0008530616760253906 seconds, solution distance = 0.0010407151830342798\n",
      "Finished cycle #58 in 0.0008509159088134766 seconds, solution distance = 0.0009406184572169352\n",
      "Finished cycle #59 in 0.0008480548858642578 seconds, solution distance = 0.0008496968979514463\n",
      "Finished cycle #60 in 0.0008480548858642578 seconds, solution distance = 0.0007671542298588463\n",
      "Finished cycle #61 in 0.0009989738464355469 seconds, solution distance = 0.0006922602130661204\n",
      "Finished cycle #62 in 0.0009281635284423828 seconds, solution distance = 0.0006243450421976604\n",
      "Finished cycle #63 in 0.0009028911590576172 seconds, solution distance = 0.0005627943195647411\n",
      "Finished cycle #64 in 0.0011229515075683594 seconds, solution distance = 0.0005070445234878207\n",
      "Finished cycle #65 in 0.0010061264038085938 seconds, solution distance = 0.0004565789051689251\n",
      "Finished cycle #66 in 0.0009360313415527344 seconds, solution distance = 0.0004109237583840297\n",
      "Finished cycle #67 in 0.0009069442749023438 seconds, solution distance = 0.00036964501506364655\n",
      "Finished cycle #68 in 0.0009028911590576172 seconds, solution distance = 0.0003323451276209255\n",
      "Finished cycle #69 in 0.0009059906005859375 seconds, solution distance = 0.0002986602050070175\n",
      "Finished cycle #70 in 0.0009038448333740234 seconds, solution distance = 0.0002682573749837047\n",
      "Finished cycle #71 in 0.0008749961853027344 seconds, solution distance = 0.00024083234929284103\n",
      "Finished cycle #72 in 0.0008752346038818359 seconds, solution distance = 0.00021610717220754694\n",
      "Finished cycle #73 in 0.0008790493011474609 seconds, solution distance = 0.0001938281357389826\n",
      "Finished cycle #74 in 0.0009808540344238281 seconds, solution distance = 0.0001737638473713332\n",
      "Finished cycle #75 in 0.001093149185180664 seconds, solution distance = 0.00015570343805260123\n",
      "Finished cycle #76 in 0.0009617805480957031 seconds, solution distance = 0.00013945489982702952\n",
      "Finished cycle #77 in 0.0010330677032470703 seconds, solution distance = 0.00012484354371977702\n",
      "Finished cycle #78 in 0.000990152359008789 seconds, solution distance = 0.00011171056964087711\n",
      "Finished cycle #79 in 0.0008699893951416016 seconds, solution distance = 9.991174074253095e-05\n",
      "Finished cycle #80 in 0.0009009838104248047 seconds, solution distance = 8.931615549556682e-05\n",
      "Finished cycle #81 in 0.0009028911590576172 seconds, solution distance = 7.980511119853873e-05\n",
      "Finished cycle #82 in 0.0010230541229248047 seconds, solution distance = 7.127105311699466e-05\n",
      "Finished cycle #83 in 0.0009510517120361328 seconds, solution distance = 6.361660386744461e-05\n",
      "Finished cycle #84 in 0.0009169578552246094 seconds, solution distance = 5.675366786039859e-05\n",
      "Finished cycle #85 in 0.0008530616760253906 seconds, solution distance = 5.060260605693756e-05\n",
      "Finished cycle #86 in 0.0008580684661865234 seconds, solution distance = 4.509147641584832e-05\n",
      "Finished cycle #87 in 0.0008687973022460938 seconds, solution distance = 4.0155335672587e-05\n",
      "Finished cycle #88 in 0.0008859634399414062 seconds, solution distance = 3.573559836667073e-05\n",
      "Finished cycle #89 in 0.0008661746978759766 seconds, solution distance = 3.1779449082502964e-05\n",
      "Finished cycle #90 in 0.0009179115295410156 seconds, solution distance = 2.8239304256771902e-05\n",
      "Finished cycle #91 in 0.0008900165557861328 seconds, solution distance = 2.507231993220671e-05\n",
      "Finished cycle #92 in 0.00090789794921875 seconds, solution distance = 2.2239942116364375e-05\n",
      "Finished cycle #93 in 0.0008749961853027344 seconds, solution distance = 1.970749654489623e-05\n",
      "Finished cycle #94 in 0.0008749961853027344 seconds, solution distance = 1.7443814824158466e-05\n",
      "Finished cycle #95 in 0.0008730888366699219 seconds, solution distance = 1.5420894161621845e-05\n",
      "Finished cycle #96 in 0.0008759498596191406 seconds, solution distance = 1.361358793827705e-05\n",
      "Finished cycle #97 in 0.0008690357208251953 seconds, solution distance = 1.1999324726730265e-05\n",
      "Finished cycle #98 in 0.0008709430694580078 seconds, solution distance = 1.0557853297399333e-05\n",
      "Finished cycle #99 in 0.0008630752563476562 seconds, solution distance = 9.271011537137497e-06\n",
      "Finished cycle #100 in 0.0008790493011474609 seconds, solution distance = 8.122517190400913e-06\n",
      "Finished cycle #101 in 0.0008749961853027344 seconds, solution distance = 7.097778525810838e-06\n",
      "Finished cycle #102 in 0.0008761882781982422 seconds, solution distance = 6.1837232383510354e-06\n",
      "Finished cycle #103 in 0.0008666515350341797 seconds, solution distance = 5.368643900993675e-06\n",
      "Finished cycle #104 in 0.0008721351623535156 seconds, solution distance = 4.642058520687442e-06\n",
      "Finished cycle #105 in 0.0009281635284423828 seconds, solution distance = 3.994584799826839e-06\n",
      "Finished cycle #106 in 0.0009217262268066406 seconds, solution distance = 3.4178268535356437e-06\n",
      "Finished cycle #107 in 0.0008862018585205078 seconds, solution distance = 2.9042732059281207e-06\n",
      "Finished cycle #108 in 0.0008780956268310547 seconds, solution distance = 2.4472050093038433e-06\n",
      "Finished cycle #109 in 0.0008738040924072266 seconds, solution distance = 2.0406135354811283e-06\n",
      "Finished cycle #110 in 0.0008718967437744141 seconds, solution distance = 1.679126009790366e-06\n",
      "Finished cycle #111 in 0.0008721351623535156 seconds, solution distance = 1.3579390092388621e-06\n",
      "Finished cycle #112 in 0.000865936279296875 seconds, solution distance = 1.0727586685632673e-06\n",
      "Finished cycle #113 in 0.0008649826049804688 seconds, solution distance = 8.197470693360742e-07\n"
     ]
    }
   ],
   "source": [
    "# Solve It\n",
    "# Verbose prints progress as solution proceeds\n",
    "IndShockExample.solve(verbose=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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uNh0lKhVXV1t9erVyyoqKrJGjRplPfbYY6YjRaX58+dbI0aMMB1DLMu6++67rYceeqjVth/+8IfWtGnTDCWKToC1fv365jkQCFhdunSxfvOb3zRvq6+vt1JSUqw1a9Zc1muHzAqKz+dj586d3Hnnna2233nnnXz66aeGUgnYF4ACgnYBKLl8ubm53H333YwZM8Z0lKhWWFhITk4OP/nJT0hPT+emm25i3bp1pmNFpREjRvDBBx+wd+9eAL744gu2bt3KhAkTDCeLbgcOHKC8vLzVZ7nH42HUqFGX/VkeMhcLrKiowO/307lz51bbO3fuTHl5uaFUYlkWc+fOZcSIEfTr1890nKj0u9/9jl27drF9+3bTUaLe/v37Wb16NXPnzuUf/uEf+MMf/sDs2bPxeDw88MADpuNFlfnz51NVVUXv3r1xuVz4/X4WL17M/fffbzpaVDv7eX2hz/K//OUvl/VaIVNQznI4HK1my7LO2ybtZ+bMmfzxj39k69atpqNEpbKyMh577DE2b95MXFyc6ThRLxAIkJOTw5IlSwC46aab+PLLL1m9erUKSjt7/fXXefXVV3nttdfo27cvn3/+OXPmzKFr1648+OCDpuNFvWB8lodMQbnmmmtwuVznrZYcO3bsvCYm7WPWrFkUFhby0UcfkZmZaTpOVNq5cyfHjh3j5ptvbt7m9/v56KOPWLFiBQ0NDbhcLoMJo0tGRgY33nhjq219+vTh97//vaFE0evv//7veeKJJ/jbv/1bAP7mb/6Gv/zlLyxdulQFxaAuXboA9kpKRkZG8/Yr+SwPmWNQYmNjufnmmykqKmq1vaioiGHDhhlKFZ0sy2LmzJn8x3/8Bx9++CE9evQwHSlq3XHHHZSWlvL5558333JycvjZz37G559/rnLSzoYPH37eKfd79+4lOzvbUKLoVVdXh9PZ+iPM5XLpNGPDevToQZcuXVp9lvt8PoqLiy/7szxkVlAA5s6dy89//nNycnIYOnQoa9eu5eDBg0yfPt10tKiSm5vLa6+9xsaNG0lKSmpe1UpJSSE+Pt5wuuiSlJR03rE/HTp0IC0tTccEGZCXl8ewYcNYsmQJ9957L3/4wx9Yu3Yta9euNR0t6kyaNInFixfTrVs3+vbty2effcby5ct56KGHTEeLeDU1Nfz5z39ung8cOMDnn39Oamoq3bp1Y86cOSxZsoRevXrRq1cvlixZQkJCAj/96U8v742CcZpRMK1cudLKzs62YmNjrUGDBunUVgOAC95efvll09HEsnSasWGbNm2y+vXrZ3k8Hqt3797W2rVrTUeKSl6v13rsscesbt26WXFxcdZ1111nPfnkk1ZDQ4PpaBHvP//zPy/4GfHggw9almWfarxgwQKrS5culsfjsW699VartLT0st/HYVmWFYxGJSIiIhIsIXMMioiIiMhZKigiIiISclRQREREJOSooIiIiEjIUUERERGRkKOCIiIiIiFHBUVERERCjgqKiIiIhBwVFBEREQk5KigiIiISclRQREREJOSooIiIiEjI+b/cYOh53f+VSAAAAABJRU5ErkJggg==",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# plot_funcs([list],min,max) takes a [list] of functions and plots their values over a range from min to max\n",
    "plot_funcs(\n",
    "    [IndShockExample.solution[0].cFunc, IndShockExample.solution_terminal.cFunc],\n",
    "    0.0,\n",
    "    10.0,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Changing Constructed Attributes\n",
    "\n",
    "In the parameter dictionary above, we chose values for HARK to use when constructing its numerical representation of $F_t$, the joint distribution of permanent and transitory income shocks. When $\\texttt{IndShockExample}$ was created, those parameters ($\\texttt{TranShkStd}$, etc) were used by the **constructor** or **initialization** method of $\\texttt{IndShockConsumerType}$ to construct an attribute called $\\texttt{IncomeDstn}$.\n",
    "\n",
    "Suppose you were interested in changing (say) the amount of permanent income risk.  From the section above, you might think that you could simply change the attribute $\\texttt{TranShkStd}$, solve the model again, and it would work.\n",
    "\n",
    "That's _almost_ true-- there's one extra step. $\\texttt{TranShkStd}$ is a primitive input, but it's not the thing you _actually_ want to change. Changing $\\texttt{TranShkStd}$ doesn't actually update the income distribution... unless you tell it to (just like changing an agent's preferences does not change the consumption function that was stored for the old set of parameters -- until you invoke the $\\texttt{solve}$ method again).  In the cell below, we invoke the method $\\texttt{update\\_income\\_process}$ so HARK knows to reconstruct the attribute $\\texttt{IncomeDstn}$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [],
   "source": [
    "OtherExample = deepcopy(\n",
    "    IndShockExample\n",
    ")  # Make a copy so we can compare consumption functions\n",
    "OtherExample.PermShkStd = [\n",
    "    0.2\n",
    "]  # Double permanent income risk (note that it's a one element list)\n",
    "# Call the method to reconstruct the representation of F_t\n",
    "OtherExample.update_income_process()\n",
    "OtherExample.solve()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the cell below, use your blossoming HARK skills to plot the consumption function for $\\texttt{IndShockExample}$ and $\\texttt{OtherExample}$ on the same figure."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Use the remainder of this cell to plot the IndShockExample and OtherExample consumption functions against each other"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Buffer Stock Saving?\n",
    "\n",
    "There are some combinations of parameter values under which problems of the kind specified above have \"degenerate\" solutions; for example, if consumers are so patient that they always prefer deferring consumption to the future, the limiting consumption rule can be $c(m)=0$.\n",
    "\n",
    "The toolkit has built-in tests for a number of parametric conditions that can be shown to result in various characteristics in the optimal solution.\n",
    "\n",
    "Perhaps the most interesting such condition is the [\"Growth Impatience Condition\"](http://www.econ2.jhu.edu/people/ccarroll/Papers/BufferStockTheory/#GIC): If this condition is satisfied, the consumer's optimal behavior is to aim to achieve a \"target\" value of $m$, to serve as a precautionary buffer against income shocks.\n",
    "\n",
    "The tests can be invoked using the `checkConditions()` method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [],
   "source": [
    "IndShockExample.check_conditions(verbose=True)"
   ]
  }
 ],
 "metadata": {
  "jupytext": {
   "cell_metadata_json": true,
   "formats": "ipynb,py:percent",
   "notebook_metadata_filter": "all"
  },
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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": 4
}