adding AgentPopulation design document

design/AgentPopulationDesignDocument.ipynb

@@ -0,0 +1,75 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "19defa18",
+   "metadata": {},
+   "source": [
+    "# AgentPopulation Design Document\n",
+    "\n",
+    "This document aims to motivate and lay out the the design for a new software class for heterogeneous agent modeling (HAM).\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "70510e8d",
+   "metadata": {},
+   "source": [
+    "## AgentPopulation\n",
+    "\n",
+    "This proposal for `AgentPopulation` takes into consideration many desiderata for HAM modeling that have arisen in previous iterations of implementation of HARK, Econ-ARK's pioneering HAM toolkit. It also is explicitly driven by the use case of the _Understanding Financial Markets_ project, originally funded by the Sloan Foundation and pending further finanical support. This latter use case involves the integration of HAM agents with a separate ABM representing financial markets, which greatly complicates the ability of the HAM model to represent agents with rational expectations.\n",
+    "\n",
+    "This proposal envisions the `AgentPopulation` class to be developed in several stages, initially with a \"lightweight\" version that supports integration with external ABMs with relaxed rational expectations conditions, and ultimately building to a more fully-powered macroeconomic modeling tool.\n",
+    "\n",
+    "### True distribution of population parameters\n",
+    "\n",
+    "This software class, provisionally named `AgentPopulation`, represents a population of macroeconomic e.g. consumer agents who individually vary over a distribution of parameters. For example, the agents within the population may vary with respect to their impatience, risk aversion, income shocks, and expectations of a risky asset's return values.\n",
+    "\n",
+    "### Optional/separate approximation parameters\n",
+    "\n",
+    "The discretization parameters of the distributions and the size/shape of the grids for value interpretation should be defined separately from the \"true\" distributions in order to enable comparison of different approximations.\n",
+    "\n",
+    "### Fitting population parameters to empirical distributions\n",
+    "\n",
+    "Extend CSTWMPC methods to enable fitting of population parameters so that outcome dependent variables (such as distribution of wealth) resemble empirical values.\n",
+    "\n",
+    "\n",
+    "## Population Solution\n",
+    "\n",
+    "Beyond the grounding `AgentPopulation` class, there will also need to be a more general `PopulationSolution` class that represents a solution or policy that is parameterized over the variety within the population. \n",
+    "\n",
+    "### Hierarchical interpolation grids\n",
+    "\n",
+    "This solution object will range over additional \"grids\" of inputs.\n",
+    "\n",
+    "These will be hierarchical: inputs that vary with respect to the agent's population parameters will be treated differently than those that vary with endogenous population state.\n",
+    "\n",
+    "\n",
+    "## Economy Aggregator\n",
+    "\n",
+    "There will also ultimately be a new class to support the derivation of rational expectations of an `AgentPopulation` as they interact in the aggregate with \"economy\"-level phenomena. This would be a variation of what is currently called (somewhat confusingly) a `Market` in HARK."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "hark-env",
+   "language": "python",
+   "name": "hark-env"
+  },
+  "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.9.5"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}