Merge branch 'master' into master

Documentation/CHANGELOG.md

@@ -18,6 +18,7 @@ Release Date: TBD
 - Allows structural equations in model files to be provided in string form [#1427](https://github.com/econ-ark/HARK/pull/1427)
 - Introduces `HARK.parser' module for parsing configuration files into models [#1427](https://github.com/econ-ark/HARK/pull/1427)
 - Allows construction of shocks with arguments based on mathematical expressions [#1464](https://github.com/econ-ark/HARK/pull/1464)
+- YAML configuration file for the normalized consumption and portolio choice [#1465](https://github.com/econ-ark/HARK/pull/1465)
 
 #### Minor Changes
 
@@ -26,6 +27,7 @@ Release Date: TBD
 - Removes a specific way of accounting for ``employment'' in the idiosyncratic-shocks income process. [1473](https://github.com/econ-ark/HARK/pull/1473)
 - Changes the behavior of make_lognormal_RiskyDstn so that the standard deviation represents the standard deviation of log(returns)
 - Adds detailed parameter and latex documentation to most models.
+- Add PermGroFac constructor that explicitly combines idiosyncratic and aggregate sources of growth. [1489](https://github.com/econ-ark/HARK/pull/1489)
 
 ### 0.15.1
 

Documentation/overview/ARKitecture.md

@@ -53,11 +53,11 @@ Macroeconomic models in HARK use the **_Market_** class to represent a market (o
 #### HARK.metric
 
 **_HARK.metric_** defines a superclass called **_MetricObject_** that is used throughout HARK's tools and models. When solving a dynamic microeconomic model with an infinite horizon (or searching for a dynamic general equilibrium), it is often required to consider whether two solutions are sufficiently close to each other to warrant stopping the process (i.e. approximate convergence). It is thus necessary to calculate the ''distance'' between two solutions, so HARK specifies that classes should have a **_distance_** method that takes a single input and returns a non-negative value representing the (generally unitless) distance between the object in question and the input to the method. As a convenient default, **_MetricObject_** provides a ''universal distance metric'' that should be useful in many contexts. (Roughly speaking, the universal distance metric is a recursive supnorm, returning the largest distance between two instances, among attributes named in **_distance_criteria_**. Those attributes might be complex objects themselves rather than real numbers, generating a recursive call to the universal distance metric.
-) When defining a new subclass of **_MetricObject_**, the user simply defines the attribute **_distance_criteria_** as a list of strings naming the attributes of the class that should be compared when calculating the distance between two instances of that class. For example, the class **_ConsumerSolution_** has **_distance_criteria = ['cFunc']_**, indicating that only the consumption function attribute of the solution matters when comparing the distance between two instances of **_ConsumerSolution_**. See [here](https://docs.econ-ark.org/reference/tools/metric.html) for further documentation.
+) When defining a new subclass of **_MetricObject_**, the user simply defines the attribute **_distance_criteria_** as a list of strings naming the attributes of the class that should be compared when calculating the distance between two instances of that class. For example, the class **_ConsumerSolution_** has **_distance_criteria = ['cFunc']_**, indicating that only the consumption function attribute of the solution matters when comparing the distance between two instances of **_ConsumerSolution_**. See [here](https://docs.econ-ark.org/Documentation/reference/tools/metric.html) for further documentation.
 
 #### HARK.utilities
 
-The **_HARK.utilities_** module contains a variety of general purpose tools, including some data manipulation tools (e.g. for calculating an average of data conditional on being within a percentile range of different data), basic kernel regression tools, convenience functions for retrieving information about functions, and basic plotting tools using **_matplotlib.pyplot_**. See [here](https://docs.econ-ark.org/reference/tools/utilities.html) for further documentation.
+The **_HARK.utilities_** module contains a variety of general purpose tools, including some data manipulation tools (e.g. for calculating an average of data conditional on being within a percentile range of different data), basic kernel regression tools, convenience functions for retrieving information about functions, and basic plotting tools using **_matplotlib.pyplot_**. See [here](https://docs.econ-ark.org/Documentation/reference/tools/utilities.html) for further documentation.
 
 #### HARK.distribution
 

HARK/Calibration/Income/IncomeProcesses.py

@@ -749,6 +749,41 @@ def __call__(self, pLvlNow):
         return pLvlNext
 
 
+def make_PermGroFac_from_ind_and_agg(PermGroFacInd, PermGroFacAgg):
+    """
+    A very simple function that constructs *overall* permanent income growth over
+    the lifecycle as the sum of idiosyncratic productivity growth PermGroFacInd and
+    aggregate productivity growth PermGroFacAgg. In most HARK models, PermGroFac
+    is treated as the overall permanent income growth factor, regardless of source.
+    In applications in which the user has estimated permanent income growth from
+    *cross sectional* data, or wants to investigate how a change in aggregate
+    productivity growth affects behavior or outcomes, this function can be used
+    as the constructor for PermGroFac.
+
+    To use this function, specify idiosyncratic productivity growth in the attribute
+    PermGroFacInd (or construct it), and put this function as the entry for PermGroFac
+    in the constructors dictionary of your AgentType subclass instances.
+
+    Parameters
+    ----------
+    PermGroFacInd : [float] or np.array
+        Lifecycle sequence of idiosyncratic permanent productivity growth factors.
+        These represent individual-based productivity factors, like experience.
+    PermGroFacAgg : float
+        Constant aggregate permanent growth factor, representing (e.g.) TFP.
+
+    Returns
+    -------
+    PermGroFac : [float] or np.array
+        Lifecycle sequence of overall permanent productivity growth factors.
+        Returns same type as PermGroFacInd.
+    """
+    PermGroFac = [PermGroFacAgg * G for G in PermGroFacInd]
+    if type(PermGroFacInd) is np.array:
+        PermGroFac = np.array(PermGroFac)
+    return PermGroFac
+
+
 ###############################################################################
 
 # Define income processes that can be used in the ConsGenIncProcess model