Merge remote-tracking branch 'upstream/master' into wealth_in_utility

Documentation/CHANGELOG.md

@@ -16,6 +16,7 @@ Release Date: TBD
 
 - Adds `HARK.core.AgentPopulation` class to represent a population of agents with ex-ante heterogeneous parametrizations as distributions. [#1237](https://github.com/econ-ark/HARK/pull/1237)
 - Adds `HARK.core.Parameters` class to represent a collection of time varying and time invariant parameters in a model. [#1240](https://github.com/econ-ark/HARK/pull/1240)
+- Adds `HARK.simulation.monte_carlo` module for generic Monte Carlo simulation functions using Python model configurations. [1296](https://github.com/econ-ark/HARK/pull/1296)
 
 ### Minor Changes
 
@@ -26,6 +27,8 @@ Release Date: TBD
 - Fixes bug that prevented risky-asset consumer types from working with time-varying interest rates `Rfree`. [1343](https://github.com/econ-ark/HARK/pull/1343)
 - Overhauls and expands condition checking for the ConsIndShock model [#1294](https://github.com/econ-ark/HARK/pull/1294). Condition values and a description of their interpretation is stored in the bilt dictionary of IndShockConsumerType.
 - Creates a `models/` directory with Python model configurations for perfect foresight and Fisher 2-period models. [1347](https://github.com/econ-ark/HARK/pull/1347)
+- Fixes bug in AgentType simulations where 'who_dies' for period t was being recorded in period t-1in the history Carlo simulation functions using Python model configurations.[1296](https://github.com/econ-ark/HARK/pull/1296)
+- Removes unused `simulation.py` .[1296](https://github.com/econ-ark/HARK/pull/1296)
 
 ### 0.13.0
 

Documentation/overview/ARKitecture.md

@@ -1,8 +1,11 @@
 # ARKitecture of Econ-ARK
 
-This document guides you through the structure of econ-ark and explain the main ingredients. Note that it does not explain _how_ to use it. For this, please follow the example notebooks which you can find on the left.
+This document guides you through the structure of Econ-ARK,
+and explains the main ingredients.
+Note that it does not explain _how_ to use it---for this,
+please follow the example notebooks which you can find on the left.
 
-[Econ-ark](https://github.com/econ-ark) contains the three main repositories [HARK](https://github.com/econ-ark/HARK), [DemARK](https://github.com/econ-ark/DEMARK), and [REMARK](https://github.com/econ-ark/REMARK). On top of that, the [website](https://econ-ark.org/) combines all of them. Hence, if you want to find a notebook search them in [materials](https://econ-ark.org/materials).
+[Econ-ARK](https://github.com/econ-ark) contains the three main repositories [HARK](https://github.com/econ-ark/HARK), [DemARK](https://github.com/econ-ark/DEMARK), and [REMARK](https://github.com/econ-ark/REMARK). On top of that, the [website](https://econ-ark.org/) combines all of them. Hence, if you want to find a notebook search them in [materials](https://econ-ark.org/materials).
 
 - [HARK](https://github.com/econ-ark/HARK): Includes the source code as well as some example notebooks.
 - [DemARK](https://github.com/econ-ark/DemARK): Here you can find *Dem*onstrations of tools, AgentTypes, and ModelClasses.
@@ -12,20 +15,21 @@ Before describing each repository in detail, some preliminary remarks.
 
 HARK is written in Python, an object-oriented programming (OOP) language that has experienced increasing popularity in the scientific community in the past several years. A significant reason for the adoption of Python is the **_numpy_** and **_scipy_** packages, which offer a wide array of mathematical and statistical functions and tools; HARK makes liberal use of these libraries. Python's object-oriented nature allows models in HARK to be easily extended: more complex models can inherit functions and methods from more fundamental ''parent'' models, eliminating the need to reproduce or repurpose code.
 
-As implied in the previous section, we strongly encourage HARK users to use the Anaconda distribution of Python, which includes all commonly used mathematical and scientific packages, an interactive development environment for iPython (Spyder), and a package manager that allows users to quickly install or update packages not included in the default distribution (conda).
+We strongly encourage HARK users to use the `conda` or `mamba` package managers,
+which includes all commonly used mathematical and scientific Python packages.
 
 For users unfamiliar with OOP, we strongly encourage you to review the background material on OOP provided by the good people at [QuantEcon](https://python.quantecon.org/intro.html) (for more on them, see below) at this link: [Object Oriented Programming](https://python-programming.quantecon.org/oop_intro.html). Unlike non-OOP languages, OOP bundles together data and functions into _objects_. These can be accessed via: **_object_name.data_** and **_object_name.method_name()_**, respectively. For organizational purposes, definitions of multiple objects are stored in _modules_, which are simply files with a **_.py_** extension. Modules can be accessed in Python via:
 
-```
+```python
 import module_name as import_name
 ```
 
-This imports the module and gives it a local name of **_import_name_**. We can access a function within this module by simply typing: **_import_name.function_name()_**. The following example will illustrate the usage of these commands. **_CRRAutility_** is the function object for calculating CRRA utility supplied by **_HARK.utilities_** module. **_CRRAutility_** is called _attributes_ of the module **_HARK.utilities_**. In order to calculate CRRA utility with a consumption of 1 and a coefficient of risk aversion of 2 we run:
+This imports the module and gives it a local name of **_import_name_**. We can access a function within this module by simply typing: **_import_name.function_name()_**. The following example will illustrate the usage of these commands. **_CRRAutility_** is the function object for calculating CRRA utility supplied by the **_HARK.rewards_** module. **_CRRAutility_** is called _attributes_ of the module **_HARK.rewards_**. In order to calculate CRRA utility with a consumption of 1 and a coefficient of risk aversion of 2 we run:
 
-```
-import HARK.utilities as Hutil
+```python
+from HARK.rewards import CRRAutility
 
-Hutil.CRRAutility(1,2)
+CRRAutility(1, 2)
 ```
 
 Python modules in HARK can generally be categorized into three types: tools, models, and applications. **Tool modules** contain functions and classes with general purpose tools that have no inherent ''economic content'', but that can be used in many economic models as building blocks or utilities; they could plausibly be useful in non-economic settings. Tools might include functions for data analysis (e.g. calculating Lorenz shares from data, or constructing a non-parametric kernel regression), functions to create and manipulate discrete approximations to continuous distributions, or classes for constructing interpolated approximations to non-parametric functions. Tool modules generally reside in HARK's root directory and have names like **_HARK.simulation_** and **_HARK.interpolation_**; they do not necessarily do anything when run.

Documentation/reference/index.rst

@@ -13,6 +13,7 @@ API Reference
    tools/frame
    tools/helpers
    tools/interpolation
+   tools/model
    tools/numba_tools
    tools/parallel
    tools/rewards

Documentation/reference/tools/model.rst

@@ -0,0 +1,7 @@
+Model
+-------------
+
+.. automodule:: HARK.model
+   :members:
+   :undoc-members:
+   :show-inheritance:

Documentation/reference/tools/simulation.rst

@@ -1,7 +1,7 @@
 Simulation
 ------------
 
-.. automodule:: HARK.simulation
+.. automodule:: HARK.simulation.monte_carlo
    :members:
    :undoc-members:
    :show-inheritance:

HARK/core.py

@@ -7,6 +7,7 @@
 problem by finding a general equilibrium dynamic rule.
 """
 # Set logging and define basic functions
+# Set logging and define basic functions
 import logging
 import sys
 from collections import defaultdict, namedtuple
@@ -1061,7 +1062,14 @@ def simulate(self, sim_periods=None):
                     elif var_name in self.controls:
                         self.history[var_name][self.t_sim, :] = self.controls[var_name]
                     else:
-                        self.history[var_name][self.t_sim, :] = getattr(self, var_name)
+                        if var_name == "who_dies" and self.t_sim > 1:
+                            self.history[var_name][self.t_sim - 1, :] = getattr(
+                                self, var_name
+                            )
+                        else:
+                            self.history[var_name][self.t_sim, :] = getattr(
+                                self, var_name
+                            )
                 self.t_sim += 1
 
             return self.history

HARK/model.py

@@ -2,10 +2,28 @@
 Tools for crafting models.
 """
 
+from HARK.distribution import Distribution
+
+
+class Aggregate:
+    """
+    Used to designate a shock as an aggregate shock.
+    If so designated, draws from the shock will be scalar rather
+    than array valued.
+    """
+
+    def __init__(self, dist: Distribution):
+        self.dist = dist
+
 
 class Control:
     """
-    Should go in different model support module.
+    Used to designate a variabel that is a control variable.
+
+    Parameters
+    ----------
+    args : list of str
+        The labels of the variables that are in the information set of this control.
     """
 
     def __init__(self, args):

HARK/models/perfect_foresight.py

@@ -20,9 +20,9 @@
         "BoroCnstArt": None,
     },
     "dynamics": {
+        "y": lambda p: p,
         "m": lambda Rfree, a, y: Rfree * a + y,
         "c": Control(["m"]),
-        "y": lambda p: p,
         "p": lambda PermGroFac, p: PermGroFac * p,
         "a": lambda m, c: m - c,
     },

HARK/models/perfect_foresight_normalized.py

@@ -0,0 +1,31 @@
+from HARK.distribution import Bernoulli
+from HARK.model import Control
+
+# This way of distributing parameters across the scope is clunky
+# Can be handled better if parsed from a YAML file, probably
+# But it would be better to have a more graceful Python version as well.
+CRRA = (2.0,)
+LivPrb = 0.98
+
+model = {
+    "shocks": {
+        "live": Bernoulli(p=LivPrb),
+    },
+    "parameters": {
+        "DiscFac": 0.96,
+        "CRRA": CRRA,
+        "Rfree": 1.03,
+        "LivPrb": LivPrb,
+        "PermGroFac": 1.01,
+        "BoroCnstArt": None,
+    },
+    "dynamics": {
+        "p": lambda PermGroFac, p: PermGroFac * p,
+        "r_eff": lambda Rfree, PermGroFac: Rfree / PermGroFac,
+        "b_nrm": lambda r_eff, a_nrm: r_eff * a_nrm,
+        "m_nrm": lambda b_nrm: b_nrm + 1,
+        "c_nrm": Control(["m_nrm"]),
+        "a_nrm": lambda m_nrm, c_nrm: m_nrm - c_nrm,
+    },
+    "reward": {"u": lambda c: c ** (1 - CRRA) / (1 - CRRA)},
+}