diff --git a/Documentation/CHANGELOG.md b/Documentation/CHANGELOG.md index 88d6cad34..6923e86f7 100644 --- a/Documentation/CHANGELOG.md +++ b/Documentation/CHANGELOG.md @@ -20,6 +20,7 @@ Release Data: TBD * Centralizes the definition of value, marginal value, and marginal marginal value functions that use inverse-space interpolation for problems with CRRA utility. See [#888](https://github.com/econ-ark/HARK/pull/888). * MarkovProcess class (#902)[https://github.com/econ-ark/HARK/pull/902] +* Corrects location of constructor documentation to class string for Sphinx rendering (#908)[https://github.com/econ-ark/HARK/pull/908] #### Minor Changes diff --git a/HARK/ConsumptionSaving/ConsAggShockModel.py b/HARK/ConsumptionSaving/ConsAggShockModel.py index 52904d1ac..b483ad8d8 100644 --- a/HARK/ConsumptionSaving/ConsAggShockModel.py +++ b/HARK/ConsumptionSaving/ConsAggShockModel.py @@ -1791,28 +1791,20 @@ class CobbDouglasEconomy(Market): Note: The current implementation assumes a constant labor supply, but this will be generalized in the future. + + Parameters + ---------- + agents : [ConsumerType] + List of types of consumers that live in this economy. + tolerance: float + Minimum acceptable distance between "dynamic rules" to consider the + solution process converged. Distance depends on intercept and slope + of the log-linear "next capital ratio" function. + act_T : int + Number of periods to simulate when making a history of of the market. """ def __init__(self, agents=None, tolerance=0.0001, act_T=1200, **kwds): - """ - Make a new instance of CobbDouglasEconomy by filling in attributes - specific to this kind of market. - - Parameters - ---------- - agents : [ConsumerType] - List of types of consumers that live in this economy. - tolerance: float - Minimum acceptable distance between "dynamic rules" to consider the - solution process converged. Distance depends on intercept and slope - of the log-linear "next capital ratio" function. - act_T : int - Number of periods to simulate when making a history of of the market. - - Returns - ------- - None - """ agents = agents if agents is not None else list() params = init_cobb_douglas.copy() params["sow_vars"] = [ @@ -2120,27 +2112,20 @@ class SmallOpenEconomy(Market): A class for representing a small open economy, where the wage rate and interest rate are exogenously determined by some "global" rate. However, the economy is still subject to aggregate productivity shocks. + + Parameters + ---------- + agents : [ConsumerType] + List of types of consumers that live in this economy. + tolerance: float + Minimum acceptable distance between "dynamic rules" to consider the + solution process converged. Distance depends on intercept and slope + of the log-linear "next capital ratio" function. + act_T : int + Number of periods to simulate when making a history of of the market. """ def __init__(self, agents=None, tolerance=0.0001, act_T=1000, **kwds): - """ - Make a new instance of SmallOpenEconomy by filling in attributes specific to this kind of market. - - Parameters - ---------- - agents : [ConsumerType] - List of types of consumers that live in this economy. - tolerance: float - Minimum acceptable distance between "dynamic rules" to consider the - solution process converged. Distance depends on intercept and slope - of the log-linear "next capital ratio" function. - act_T : int - Number of periods to simulate when making a history of of the market. - - Returns - ------- - None - """ agents = agents if agents is not None else list() Market.__init__( self, @@ -2343,6 +2328,16 @@ class CobbDouglasMarkovEconomy(CobbDouglasEconomy): state for the "macroeconomy", so that the shock distribution and aggregate productivity growth factor can vary over time. + Parameters + ---------- + agents : [ConsumerType] + List of types of consumers that live in this economy. + tolerance: float + Minimum acceptable distance between "dynamic rules" to consider the + solution process converged. Distance depends on intercept and slope + of the log-linear "next capital ratio" function. + act_T : int + Number of periods to simulate when making a history of of the market. """ def __init__( @@ -2362,25 +2357,6 @@ def __init__( ], **kwds ): - """ - Make a new instance of CobbDouglasMarkovEconomy by filling in attributes - specific to this kind of market. - - Parameters - ---------- - agents : [ConsumerType] - List of types of consumers that live in this economy. - tolerance: float - Minimum acceptable distance between "dynamic rules" to consider the - solution process converged. Distance depends on intercept and slope - of the log-linear "next capital ratio" function. - act_T : int - Number of periods to simulate when making a history of of the market. - - Returns - ------- - None - """ agents = agents if agents is not None else list() params = init_mrkv_cobb_douglas.copy() params.update(kwds) @@ -2789,28 +2765,20 @@ class KrusellSmithEconomy(Market): This model replicates the one presented in the JPE article "Income and Wealth Heterogeneity in the Macroeconomy", with its default parameters set to match those in the paper. + + Parameters + ---------- + agents : [ConsumerType] + List of types of consumers that live in this economy. + tolerance: float + Minimum acceptable distance between "dynamic rules" to consider the + solution process converged. Distance depends on intercept and slope + of the log-linear "next capital ratio" function. + act_T : int + Number of periods to simulate when making a history of of the market. """ def __init__(self, agents=None, tolerance=0.0001, **kwds): - """ - Make a new instance of KrusellSmithEconomy by filling in attributes - specific to this kind of market. - - Parameters - ---------- - agents : [ConsumerType] - List of types of consumers that live in this economy. - tolerance: float - Minimum acceptable distance between "dynamic rules" to consider the - solution process converged. Distance depends on intercept and slope - of the log-linear "next capital ratio" function. - act_T : int - Number of periods to simulate when making a history of of the market. - - Returns - ------- - None - """ agents = agents if agents is not None else list() params = deepcopy(init_KS_economy) params.update(kwds) @@ -3106,23 +3074,16 @@ class AggregateSavingRule(HARKobject): """ A class to represent agent beliefs about aggregate saving at the end of this period (AaggNow) as a function of (normalized) aggregate market resources at the beginning of the period (MaggNow). + + Parameters + ---------- + intercept : float + Intercept of the log-linear capital evolution rule. + slope : float + Slope of the log-linear capital evolution rule. """ def __init__(self, intercept, slope): - """ - Make a new instance of CapitalEvoRule. - - Parameters - ---------- - intercept : float - Intercept of the log-linear capital evolution rule. - slope : float - Slope of the log-linear capital evolution rule. - - Returns - ------- - new instance of CapitalEvoRule - """ self.intercept = intercept self.slope = slope self.distance_criteria = ["slope", "intercept"] @@ -3147,20 +3108,13 @@ def __call__(self, Mnow): class AggShocksDynamicRule(HARKobject): """ Just a container class for passing the dynamic rule in the aggregate shocks model to agents. + + Parameters + ---------- + AFunc : CapitalEvoRule + Aggregate savings as a function of aggregate market resources. """ def __init__(self, AFunc): - """ - Make a new instance of CapDynamicRule. - - Parameters - ---------- - AFunc : CapitalEvoRule - Aggregate savings as a function of aggregate market resources. - - Returns - ------- - None - """ self.AFunc = AFunc self.distance_criteria = ["AFunc"] diff --git a/HARK/ConsumptionSaving/ConsGenIncProcessModel.py b/HARK/ConsumptionSaving/ConsGenIncProcessModel.py index 9188fccf8..03c9c208b 100644 --- a/HARK/ConsumptionSaving/ConsGenIncProcessModel.py +++ b/HARK/ConsumptionSaving/ConsGenIncProcessModel.py @@ -64,25 +64,18 @@ class pLvlFuncAR1(HARKobject): """ A class for representing AR1-style persistent income growth functions. + + Parameters + ---------- + pLogMean : float + Log persistent income level toward which we are drawn. + PermGroFac : float + Autonomous (e.g. life cycle) pLvl growth (does not AR1 decay). + Corr : float + Correlation coefficient on log income. """ def __init__(self, pLogMean, PermGroFac, Corr): - """ - Make a new pLvlFuncAR1 instance. - - Parameters - ---------- - pLogMean : float - Log persistent income level toward which we are drawn. - PermGroFac : float - Autonomous (e.g. life cycle) pLvl growth (does not AR1 decay). - Corr : float - Correlation coefficient on log income. - - Returns - ------- - None - """ self.pLogMean = pLogMean self.LogGroFac = np.log(PermGroFac) self.Corr = Corr @@ -121,6 +114,40 @@ class ConsGenIncProcessSolver(ConsIndShockSetup): (after controlling for growth). Instead, they have a function that translates current persistent income into expected next period persistent income (subject to shocks). + + Parameters + ---------- + solution_next : ConsumerSolution + The solution to next period's one period problem. + IncomeDstn : [np.array] + A list containing three arrays of floats, representing a discrete + approximation to the income process between the period being solved + and the one immediately following (in solution_next). Order: event + probabilities, persistent shocks, transitory shocks. + LivPrb : float + Survival probability; likelihood of being alive at the beginning of + the succeeding period. + DiscFac : float + Intertemporal discount factor for future utility. + CRRA : float + Coefficient of relative risk aversion. + Rfree : float + Risk free interest factor on end-of-period assets. + pLvlNextFunc : float + Expected persistent income next period as a function of current pLvl. + BoroCnstArt: float or None + Borrowing constraint for the minimum allowable assets to end the + period with. + aXtraGrid: np.array + Array of "extra" end-of-period (normalized) asset values-- assets + above the absolute minimum acceptable level. + pLvlGrid: np.array + Array of persistent income levels at which to solve the problem. + vFuncBool: boolean + An indicator for whether the value function should be computed and + included in the reported solution. + CubicBool: boolean + An indicator for whether the solver should use cubic or linear interpolation. """ def __init__( @@ -138,49 +165,6 @@ def __init__( vFuncBool, CubicBool, ): - """ - Constructor for a new solver for a one period problem with idiosyncratic - shocks to persistent and transitory income, with persistent income tracked - as a state variable rather than normalized out. - - Parameters - ---------- - solution_next : ConsumerSolution - The solution to next period's one period problem. - IncomeDstn : [np.array] - A list containing three arrays of floats, representing a discrete - approximation to the income process between the period being solved - and the one immediately following (in solution_next). Order: event - probabilities, persistent shocks, transitory shocks. - LivPrb : float - Survival probability; likelihood of being alive at the beginning of - the succeeding period. - DiscFac : float - Intertemporal discount factor for future utility. - CRRA : float - Coefficient of relative risk aversion. - Rfree : float - Risk free interest factor on end-of-period assets. - pLvlNextFunc : float - Expected persistent income next period as a function of current pLvl. - BoroCnstArt: float or None - Borrowing constraint for the minimum allowable assets to end the - period with. - aXtraGrid: np.array - Array of "extra" end-of-period (normalized) asset values-- assets - above the absolute minimum acceptable level. - pLvlGrid: np.array - Array of persistent income levels at which to solve the problem. - vFuncBool: boolean - An indicator for whether the value function should be computed and - included in the reported solution. - CubicBool: boolean - An indicator for whether the solver should use cubic or linear interpolation. - - Returns - ------- - None - """ self.assignParameters( solution_next=solution_next, IncomeDstn=IncomeDstn, @@ -899,6 +883,14 @@ class GenIncProcessConsumerType(IndShockConsumerType): abilities, and persistent income growth functions, as well as time invariant values for risk aversion, discount factor, the interest rate, the grid of end-of-period assets, and an artificial borrowing constraint. + + See init_explicit_perm_inc for a dictionary of the + keywords that should be passed to the constructor. + + Parameters + ---------- + cycles : int + Number of times the sequence of periods should be solved. """ cFunc_terminal_ = BilinearInterp( @@ -911,20 +903,6 @@ class GenIncProcessConsumerType(IndShockConsumerType): state_vars = ["pLvlNow","mLvlNow","aLvlNow"] def __init__(self, cycles=0, **kwds): - """ - Instantiate a new ConsumerType with given data. - See ConsumerParameters.init_explicit_perm_inc for a dictionary of the - keywords that should be passed to the constructor. - - Parameters - ---------- - cycles : int - Number of times the sequence of periods should be solved. - - Returns - ------- - None - """ params = init_explicit_perm_inc.copy() params.update(kwds) @@ -1267,21 +1245,14 @@ class PersistentShockConsumerType(GenIncProcessConsumerType): for risk aversion, discount factor, the interest rate, the grid of end-of- period assets, an artificial borrowing constraint, and the AR1 correlation coefficient for (log) persistent income. + + Parameters + ---------- + cycles : int + Number of times the sequence of periods should be solved. """ def __init__(self, cycles=0, **kwds): - """ - Instantiate a new ConsumerType with given data. - - Parameters - ---------- - cycles : int - Number of times the sequence of periods should be solved. - - Returns - ------- - None - """ params = init_persistent_shocks.copy() params.update(kwds) diff --git a/HARK/ConsumptionSaving/ConsIndShockModel.py b/HARK/ConsumptionSaving/ConsIndShockModel.py index bf831cfee..b3a8cd0b1 100644 --- a/HARK/ConsumptionSaving/ConsIndShockModel.py +++ b/HARK/ConsumptionSaving/ConsIndShockModel.py @@ -88,6 +88,34 @@ class ConsumerSolution(HARKobject): Here and elsewhere in the code, Nrm indicates that variables are normalized by permanent income. + + Parameters + ---------- + cFunc : function + The consumption function for this period, defined over market + resources: c = cFunc(m). + vFunc : function + The beginning-of-period value function for this period, defined over + market resources: v = vFunc(m). + vPfunc : function + The beginning-of-period marginal value function for this period, + defined over market resources: vP = vPfunc(m). + vPPfunc : function + The beginning-of-period marginal marginal value function for this + period, defined over market resources: vPP = vPPfunc(m). + mNrmMin : float + The minimum allowable market resources for this period; the consump- + tion function (etc) are undefined for m < mNrmMin. + hNrm : float + Human wealth after receiving income this period: PDV of all future + income, ignoring mortality. + MPCmin : float + Infimum of the marginal propensity to consume this period. + MPC --> MPCmin as m --> infinity. + MPCmax : float + Supremum of the marginal propensity to consume this period. + MPC --> MPCmax as m --> mNrmMin. + """ distance_criteria = ["vPfunc"] @@ -103,40 +131,6 @@ def __init__( MPCmin=None, MPCmax=None, ): - """ - The constructor for a new ConsumerSolution object. - - Parameters - ---------- - cFunc : function - The consumption function for this period, defined over market - resources: c = cFunc(m). - vFunc : function - The beginning-of-period value function for this period, defined over - market resources: v = vFunc(m). - vPfunc : function - The beginning-of-period marginal value function for this period, - defined over market resources: vP = vPfunc(m). - vPPfunc : function - The beginning-of-period marginal marginal value function for this - period, defined over market resources: vPP = vPPfunc(m). - mNrmMin : float - The minimum allowable market resources for this period; the consump- - tion function (etc) are undefined for m < mNrmMin. - hNrm : float - Human wealth after receiving income this period: PDV of all future - income, ignoring mortality. - MPCmin : float - Infimum of the marginal propensity to consume this period. - MPC --> MPCmin as m --> infinity. - MPCmax : float - Supremum of the marginal propensity to consume this period. - MPC --> MPCmax as m --> mNrmMin. - - Returns - ------- - None - """ # Change any missing function inputs to NullFunc self.cFunc = cFunc if cFunc is not None else NullFunc() self.vFunc = vFunc if vFunc is not None else NullFunc() @@ -195,6 +189,29 @@ class ConsPerfForesightSolver(HARKobject): """ A class for solving a one period perfect foresight consumption-saving problem. An instance of this class is created by the function solvePerfForesight in each period. + + Parameters + ---------- + solution_next : ConsumerSolution + The solution to next period's one-period problem. + DiscFac : float + Intertemporal discount factor for future utility. + LivPrb : float + Survival probability; likelihood of being alive at the beginning of + the next period. + CRRA : float + Coefficient of relative risk aversion. + Rfree : float + Risk free interest factor on end-of-period assets. + PermGroFac : float + Expected permanent income growth factor at the end of this period. + BoroCnstArt : float or None + Artificial borrowing constraint, as a multiple of permanent income. + Can be None, indicating no artificial constraint. + MaxKinks : int + Maximum number of kink points to allow in the consumption function; + additional points will be thrown out. Only relevant in infinite + horizon model with artificial borrowing constraint. """ def __init__( @@ -208,36 +225,6 @@ def __init__( BoroCnstArt, MaxKinks, ): - """ - Constructor for a new ConsPerfForesightSolver. - - Parameters - ---------- - solution_next : ConsumerSolution - The solution to next period's one-period problem. - DiscFac : float - Intertemporal discount factor for future utility. - LivPrb : float - Survival probability; likelihood of being alive at the beginning of - the next period. - CRRA : float - Coefficient of relative risk aversion. - Rfree : float - Risk free interest factor on end-of-period assets. - PermGroFac : float - Expected permanent income growth factor at the end of this period. - BoroCnstArt : float or None - Artificial borrowing constraint, as a multiple of permanent income. - Can be None, indicating no artificial constraint. - MaxKinks : int - Maximum number of kink points to allow in the consumption function; - additional points will be thrown out. Only relevant in infinite - horizon model with artificial borrowing constraint. - - Returns: - ---------- - None - """ # We ask that HARK users define single-letter variables they use in a dictionary # attribute called notation. Do that first. @@ -476,6 +463,41 @@ class ConsIndShockSetup(ConsPerfForesightSolver): A superclass for solvers of one period consumption-saving problems with constant relative risk aversion utility and permanent and transitory shocks to income. Has methods to set up but not solve the one period problem. + + Parameters + ---------- + solution_next : ConsumerSolution + The solution to next period's one period problem. + IncomeDstn : [np.array] + A list containing three arrays of floats, representing a discrete + approximation to the income process between the period being solved + and the one immediately following (in solution_next). Order: event + probabilities, permanent shocks, transitory shocks. + LivPrb : float + Survival probability; likelihood of being alive at the beginning of + the succeeding period. + DiscFac : float + Intertemporal discount factor for future utility. + CRRA : float + Coefficient of relative risk aversion. + Rfree : float + Risk free interest factor on end-of-period assets. + PermGroFac : float + Expected permanent income growth factor at the end of this period. + BoroCnstArt: float or None + Borrowing constraint for the minimum allowable assets to end the + period with. If it is less than the natural borrowing constraint, + then it is irrelevant; BoroCnstArt=None indicates no artificial bor- + rowing constraint. + aXtraGrid: np.array + Array of "extra" end-of-period asset values-- assets above the + absolute minimum acceptable level. + vFuncBool: boolean + An indicator for whether the value function should be computed and + included in the reported solution. + CubicBool: boolean + An indicator for whether the solver should use cubic or linear inter- + polation. """ def __init__( @@ -492,49 +514,6 @@ def __init__( vFuncBool, CubicBool, ): - """ - Constructor for a new solver-setup for problems with income subject to - permanent and transitory shocks. - - Parameters - ---------- - solution_next : ConsumerSolution - The solution to next period's one period problem. - IncomeDstn : [np.array] - A list containing three arrays of floats, representing a discrete - approximation to the income process between the period being solved - and the one immediately following (in solution_next). Order: event - probabilities, permanent shocks, transitory shocks. - LivPrb : float - Survival probability; likelihood of being alive at the beginning of - the succeeding period. - DiscFac : float - Intertemporal discount factor for future utility. - CRRA : float - Coefficient of relative risk aversion. - Rfree : float - Risk free interest factor on end-of-period assets. - PermGroFac : float - Expected permanent income growth factor at the end of this period. - BoroCnstArt: float or None - Borrowing constraint for the minimum allowable assets to end the - period with. If it is less than the natural borrowing constraint, - then it is irrelevant; BoroCnstArt=None indicates no artificial bor- - rowing constraint. - aXtraGrid: np.array - Array of "extra" end-of-period asset values-- assets above the - absolute minimum acceptable level. - vFuncBool: boolean - An indicator for whether the value function should be computed and - included in the reported solution. - CubicBool: boolean - An indicator for whether the solver should use cubic or linear inter- - polation. - - Returns - ------- - None - """ self.assignParameters( solution_next=solution_next, IncomeDstn=IncomeDstn, @@ -1162,6 +1141,45 @@ class ConsKinkedRsolver(ConsIndShockSolver): erence is that Rfree is replaced by Rsave (a>0) and Rboro (a<0). The solver can handle Rboro == Rsave, which makes it identical to ConsIndShocksolver, but it terminates immediately if Rboro < Rsave, as this has a different solution. + + Parameters + ---------- + solution_next : ConsumerSolution + The solution to next period's one period problem. + IncomeDstn : [np.array] + A list containing three arrays of floats, representing a discrete + approximation to the income process between the period being solved + and the one immediately following (in solution_next). Order: event + probabilities, permanent shocks, transitory shocks. + LivPrb : float + Survival probability; likelihood of being alive at the beginning of + the succeeding period. + DiscFac : float + Intertemporal discount factor for future utility. + CRRA : float + Coefficient of relative risk aversion. + Rboro: float + Interest factor on assets between this period and the succeeding + period when assets are negative. + Rsave: float + Interest factor on assets between this period and the succeeding + period when assets are positive. + PermGroFac : float + Expected permanent income growth factor at the end of this period. + BoroCnstArt: float or None + Borrowing constraint for the minimum allowable assets to end the + period with. If it is less than the natural borrowing constraint, + then it is irrelevant; BoroCnstArt=None indicates no artificial bor- + rowing constraint. + aXtraGrid: np.array + Array of "extra" end-of-period asset values-- assets above the + absolute minimum acceptable level. + vFuncBool: boolean + An indicator for whether the value function should be computed and + included in the reported solution. + CubicBool: boolean + An indicator for whether the solver should use cubic or linear inter- + polation. """ def __init__( @@ -1179,53 +1197,6 @@ def __init__( vFuncBool, CubicBool, ): - """ - Constructor for a new solver for problems with risky income and a different - interest rate on borrowing and saving. - - Parameters - ---------- - solution_next : ConsumerSolution - The solution to next period's one period problem. - IncomeDstn : [np.array] - A list containing three arrays of floats, representing a discrete - approximation to the income process between the period being solved - and the one immediately following (in solution_next). Order: event - probabilities, permanent shocks, transitory shocks. - LivPrb : float - Survival probability; likelihood of being alive at the beginning of - the succeeding period. - DiscFac : float - Intertemporal discount factor for future utility. - CRRA : float - Coefficient of relative risk aversion. - Rboro: float - Interest factor on assets between this period and the succeeding - period when assets are negative. - Rsave: float - Interest factor on assets between this period and the succeeding - period when assets are positive. - PermGroFac : float - Expected permanent income growth factor at the end of this period. - BoroCnstArt: float or None - Borrowing constraint for the minimum allowable assets to end the - period with. If it is less than the natural borrowing constraint, - then it is irrelevant; BoroCnstArt=None indicates no artificial bor- - rowing constraint. - aXtraGrid: np.array - Array of "extra" end-of-period asset values-- assets above the - absolute minimum acceptable level. - vFuncBool: boolean - An indicator for whether the value function should be computed and - included in the reported solution. - CubicBool: boolean - An indicator for whether the solver should use cubic or linear inter- - polation. - - Returns - ------- - None - """ assert ( Rboro >= Rsave ), "Interest factor on debt less than interest factor on savings!" @@ -1395,6 +1366,11 @@ class PerfForesightConsumerType(AgentType): His problem is defined by a coefficient of relative risk aversion, intertemporal discount factor, interest factor, an artificial borrowing constraint (maybe) and time sequences of the permanent income growth rate and survival probability. + + Parameters + ---------- + cycles : int + Number of times the sequence of periods should be solved. """ # Define some universal values for all consumer types @@ -1414,21 +1390,6 @@ class PerfForesightConsumerType(AgentType): shock_vars_ = [] def __init__(self, cycles=1, verbose=1, quiet=False, **kwds): - """ - Instantiate a new consumer type with given data. - See init_perfect_foresight for a dictionary of - the keywords that should be passed to the constructor. - - Parameters - ---------- - cycles : int - Number of times the sequence of periods should be solved. - - Returns - ------- - None - """ - params = init_perfect_foresight.copy() params.update(kwds) kwds = params @@ -1883,6 +1844,11 @@ class IndShockConsumerType(PerfForesightConsumerType): abilities, and permanent income growth rates, as well as time invariant values for risk aversion, discount factor, the interest rate, the grid of end-of- period assets, and an artificial borrowing constraint. + + Parameters + ---------- + cycles : int + Number of times the sequence of periods should be solved. """ time_inv_ = PerfForesightConsumerType.time_inv_ + [ @@ -1896,21 +1862,6 @@ class IndShockConsumerType(PerfForesightConsumerType): shock_vars_ = ["PermShkNow", "TranShkNow"] def __init__(self, cycles=1, verbose=1, quiet=False, **kwds): - """ - Instantiate a new ConsumerType with given data. - See ConsumerParameters.init_idiosyncratic_shocks for a dictionary of - the keywords that should be passed to the constructor. - - Parameters - ---------- - cycles : int - Number of times the sequence of periods should be solved. - - Returns - ------- - None - """ - params = init_idiosyncratic_shocks.copy() params.update(kwds) @@ -2608,6 +2559,11 @@ class KinkedRconsumerType(IndShockConsumerType): interest factor on saving vs borrowing. Extends IndShockConsumerType, with very small changes. Solver for this class is currently only compatible with linear spline interpolation. + + Parameters + ---------- + cycles : int + Number of times the sequence of periods should be solved. """ time_inv_ = copy(IndShockConsumerType.time_inv_) @@ -2615,20 +2571,6 @@ class KinkedRconsumerType(IndShockConsumerType): time_inv_ += ["Rboro", "Rsave"] def __init__(self, cycles=1, **kwds): - """ - Instantiate a new ConsumerType with given data. - See ConsumerParameters.init_kinked_R for a dictionary of - the keywords that should be passed to the constructor. - - Parameters - ---------- - cycles : int - Number of times the sequence of periods should be solved. - - Returns - ------- - None - """ params = init_kinked_R.copy() params.update(kwds) diff --git a/HARK/ConsumptionSaving/ConsIndShockModelFast.py b/HARK/ConsumptionSaving/ConsIndShockModelFast.py index db8d171ec..2fab53b73 100644 --- a/HARK/ConsumptionSaving/ConsIndShockModelFast.py +++ b/HARK/ConsumptionSaving/ConsIndShockModelFast.py @@ -78,6 +78,27 @@ class PerfForesightSolution(HARKobject): Here and elsewhere in the code, Nrm indicates that variables are normalized by permanent income. + + Parameters + ---------- + mNrm: np.array + (Normalized) corresponding market resource points for interpolation. + cNrm : np.array + (Normalized) consumption points for interpolation. + vFuncNvrsSlope: float + Constant slope of inverse value vFuncNvrs + mNrmMin : float + The minimum allowable market resources for this period; the consump- + tion function (etc) are undefined for m < mNrmMin. + hNrm : float + Human wealth after receiving income this period: PDV of all future + income, ignoring mortality. + MPCmin : float + Infimum of the marginal propensity to consume this period. + MPC --> MPCmin as m --> infinity. + MPCmax : float + Supremum of the marginal propensity to consume this period. + MPC --> MPCmax as m --> mNrmMin. """ distance_criteria = ["cNrm", "mNrm"] @@ -92,34 +113,6 @@ def __init__( MPCmin=1.0, MPCmax=1.0, ): - """ - The constructor for a new PerfForesightSolution object. - - Parameters - ---------- - mNrm: np.array - (Normalized) corresponding market resource points for interpolation. - cNrm : np.array - (Normalized) consumption points for interpolation. - vFuncNvrsSlope: float - Constant slope of inverse value vFuncNvrs - mNrmMin : float - The minimum allowable market resources for this period; the consump- - tion function (etc) are undefined for m < mNrmMin. - hNrm : float - Human wealth after receiving income this period: PDV of all future - income, ignoring mortality. - MPCmin : float - Infimum of the marginal propensity to consume this period. - MPC --> MPCmin as m --> infinity. - MPCmax : float - Supremum of the marginal propensity to consume this period. - MPC --> MPCmax as m --> mNrmMin. - - Returns - ------- - None - """ self.mNrm = mNrm self.cNrm = cNrm self.vFuncNvrsSlope = vFuncNvrsSlope @@ -133,6 +126,27 @@ class IndShockSolution(HARKobject): """ A class representing the solution of a single period of a consumption-saving idiosyncratic shocks to permanent and transitory income problem. + + Parameters + ---------- + mNrm: np.array + (Normalized) corresponding market resource points for interpolation. + cNrm : np.array + (Normalized) consumption points for interpolation. + vFuncNvrsSlope: float + Constant slope of inverse value vFuncNvrs + mNrmMin : float + The minimum allowable market resources for this period; the consump- + tion function (etc) are undefined for m < mNrmMin. + hNrm : float + Human wealth after receiving income this period: PDV of all future + income, ignoring mortality. + MPCmin : float + Infimum of the marginal propensity to consume this period. + MPC --> MPCmin as m --> infinity. + MPCmax : float + Supremum of the marginal propensity to consume this period. + MPC --> MPCmax as m --> mNrmMin. """ distance_criteria = ["cNrm", "mNrm", "mNrmMin"] @@ -154,34 +168,6 @@ def __init__( vNvrsP=None, MPCminNvrs=None, ): - """ - The constructor for a new ConsumerSolution object. - - Parameters - ---------- - mNrm: np.array - (Normalized) corresponding market resource points for interpolation. - cNrm : np.array - (Normalized) consumption points for interpolation. - vFuncNvrsSlope: float - Constant slope of inverse value vFuncNvrs - mNrmMin : float - The minimum allowable market resources for this period; the consump- - tion function (etc) are undefined for m < mNrmMin. - hNrm : float - Human wealth after receiving income this period: PDV of all future - income, ignoring mortality. - MPCmin : float - Infimum of the marginal propensity to consume this period. - MPC --> MPCmin as m --> infinity. - MPCmax : float - Supremum of the marginal propensity to consume this period. - MPC --> MPCmax as m --> mNrmMin. - - Returns - ------- - None - """ self.mNrm = mNrm self.cNrm = cNrm self.cFuncLimitIntercept = cFuncLimitIntercept diff --git a/HARK/ConsumptionSaving/ConsLaborModel.py b/HARK/ConsumptionSaving/ConsLaborModel.py index c9e922fed..f84213915 100644 --- a/HARK/ConsumptionSaving/ConsLaborModel.py +++ b/HARK/ConsumptionSaving/ConsLaborModel.py @@ -33,36 +33,29 @@ class ConsumerLaborSolution(HARKobject): """ A class for representing one period of the solution to a Consumer Labor problem. + + Parameters + ---------- + cFunc : function + The consumption function for this period, defined over normalized + bank balances and the transitory productivity shock: cNrm = cFunc(bNrm,TranShk). + LbrFunc : function + The labor supply function for this period, defined over normalized + bank balances 0.751784276198: Lbr = LbrFunc(bNrm,TranShk). + vFunc : function + The beginning-of-period value function for this period, defined over + normalized bank balances 0.751784276198: v = vFunc(bNrm,TranShk). + vPfunc : function + The beginning-of-period marginal value (of bank balances) function for + this period, defined over normalized bank balances 0.751784276198: vP = vPfunc(bNrm,TranShk). + bNrmMin: float + The minimum allowable bank balances for this period, as a function of + the transitory shock. cFunc, LbrFunc, etc are undefined for bNrm < bNrmMin(TranShk). """ distance_criteria = ["cFunc", "LbrFunc"] def __init__(self, cFunc=None, LbrFunc=None, vFunc=None, vPfunc=None, bNrmMin=None): - """ - The constructor for a new ConsumerSolution object. - - Parameters - ---------- - cFunc : function - The consumption function for this period, defined over normalized - bank balances and the transitory productivity shock: cNrm = cFunc(bNrm,TranShk). - LbrFunc : function - The labor supply function for this period, defined over normalized - bank balances 0.751784276198: Lbr = LbrFunc(bNrm,TranShk). - vFunc : function - The beginning-of-period value function for this period, defined over - normalized bank balances 0.751784276198: v = vFunc(bNrm,TranShk). - vPfunc : function - The beginning-of-period marginal value (of bank balances) function for - this period, defined over normalized bank balances 0.751784276198: vP = vPfunc(bNrm,TranShk). - bNrmMin: float - The minimum allowable bank balances for this period, as a function of - the transitory shock. cFunc, LbrFunc, etc are undefined for bNrm < bNrmMin(TranShk). - - Returns - ------- - None - """ if cFunc is not None: self.cFunc = cFunc if LbrFunc is not None: @@ -353,6 +346,14 @@ class LaborIntMargConsumerType(IndShockConsumerType): to consume vs save and how much labor to supply (as a fraction of their time). They get CRRA utility from a composite good x_t = c_t*z_t^alpha, and discount future utility flows at a constant factor. + + See init_labor_intensive for a dictionary of + the keywords that should be passed to the constructor. + + Parameters + ---------- + cycles : int + Number of times the sequence of periods should be solved. """ time_vary_ = copy(IndShockConsumerType.time_vary_) @@ -360,20 +361,6 @@ class LaborIntMargConsumerType(IndShockConsumerType): time_inv_ = copy(IndShockConsumerType.time_inv_) def __init__(self, cycles=1, **kwds): - """ - Instantiate a new consumer type with given data. - See init_labor_intensive for a dictionary of - the keywords that should be passed to the constructor. - - Parameters - ---------- - cycles : int - Number of times the sequence of periods should be solved. - - Returns - ------- - None - """ params = init_labor_intensive.copy() params.update(kwds) diff --git a/HARK/ConsumptionSaving/ConsMedModel.py b/HARK/ConsumptionSaving/ConsMedModel.py index 23d632e34..bd4c2c645 100644 --- a/HARK/ConsumptionSaving/ConsMedModel.py +++ b/HARK/ConsumptionSaving/ConsMedModel.py @@ -61,6 +61,28 @@ class MedShockPolicyFunc(HARKobject): Class for representing the policy function in the medical shocks model: opt- imal consumption and medical care for given market resources, permanent income, and medical need shock. Always obeys Con + MedPrice*Med = optimal spending. + + Parameters + ---------- + xFunc : function + Optimal total spending as a function of market resources, permanent + income, and the medical need shock. + xLvlGrid : np.array + 1D array of total expenditure levels. + MedShkGrid : np.array + 1D array of medical shocks. + MedPrice : float + Relative price of a unit of medical care. + CRRAcon : float + Coefficient of relative risk aversion for consumption. + CRRAmed : float + Coefficient of relative risk aversion for medical care. + xLvlCubicBool : boolean + Indicator for whether cubic spline interpolation (rather than linear) + should be used in the xLvl dimension. + MedShkCubicBool : boolean + Indicator for whether bicubic interpolation should be used; only + operative when xLvlCubicBool=True. """ distance_criteria = ["xFunc", "cFunc", "MedPrice"] @@ -76,35 +98,6 @@ def __init__( xLvlCubicBool=False, MedShkCubicBool=False, ): - """ - Make a new MedShockPolicyFunc. - - Parameters - ---------- - xFunc : function - Optimal total spending as a function of market resources, permanent - income, and the medical need shock. - xLvlGrid : np.array - 1D array of total expenditure levels. - MedShkGrid : np.array - 1D array of medical shocks. - MedPrice : float - Relative price of a unit of medical care. - CRRAcon : float - Coefficient of relative risk aversion for consumption. - CRRAmed : float - Coefficient of relative risk aversion for medical care. - xLvlCubicBool : boolean - Indicator for whether cubic spline interpolation (rather than linear) - should be used in the xLvl dimension. - MedShkCubicBool : boolean - Indicator for whether bicubic interpolation should be used; only - operative when xLvlCubicBool=True. - - Returns - ------- - None - """ # Store some of the inputs in self self.MedPrice = MedPrice self.xFunc = xFunc @@ -284,27 +277,20 @@ class cThruXfunc(HARKobject): """ Class for representing consumption function derived from total expenditure and consumption. + + Parameters + ---------- + xFunc : function + Optimal total spending as a function of market resources, permanent + income, and the medical need shock. + cFunc : function + Optimal consumption as a function of total spending and the medical + need shock. """ distance_criteria = ["xFunc", "cFunc"] def __init__(self, xFunc, cFunc): - """ - Make a new instance of MedFromXfunc. - - Parameters - ---------- - xFunc : function - Optimal total spending as a function of market resources, permanent - income, and the medical need shock. - cFunc : function - Optimal consumption as a function of total spending and the medical - need shock. - - Returns - ------- - None - """ self.xFunc = xFunc self.cFunc = cFunc @@ -417,29 +403,22 @@ class MedThruXfunc(HARKobject): """ Class for representing medical care function derived from total expenditure and consumption. + + Parameters + ---------- + xFunc : function + Optimal total spending as a function of market resources, permanent + income, and the medical need shock. + cFunc : function + Optimal consumption as a function of total spending and the medical + need shock. + MedPrice : float + Relative price of a unit of medical care. """ distance_criteria = ["xFunc", "cFunc", "MedPrice"] def __init__(self, xFunc, cFunc, MedPrice): - """ - Make a new instance of MedFromXfunc. - - Parameters - ---------- - xFunc : function - Optimal total spending as a function of market resources, permanent - income, and the medical need shock. - cFunc : function - Optimal consumption as a function of total spending and the medical - need shock. - MedPrice : float - Relative price of a unit of medical care. - - Returns - ------- - None - """ self.xFunc = xFunc self.cFunc = cFunc self.MedPrice = MedPrice @@ -583,27 +562,20 @@ class MedShockConsumerType(PersistentShockConsumerType): and medical care; both goods yield CRRAutility, and the coefficients on the goods might be different. Agents expect to receive shocks to permanent and transitory income as well as multiplicative shocks to utility from medical care. + + See init_med_shock for a dictionary of the keywords + that should be passed to the constructor. + + Parameters + ---------- + cycles : int + Number of times the sequence of periods should be solved. """ shock_vars_ = PersistentShockConsumerType.shock_vars_ + ["MedShkNow"] state_vars = PersistentShockConsumerType.state_vars + ['mLvlNow'] def __init__(self, cycles=0, **kwds): - """ - Instantiate a new ConsumerType with given data, and construct objects - to be used during solution (income distribution, assets grid, etc). - See ConsumerParameters.init_med_shock for a dictionary of the keywords - that should be passed to the constructor. - - Parameters - ---------- - cycles : int - Number of times the sequence of periods should be solved. - - Returns - ------- - None - """ params = init_medical_shocks.copy() params.update(kwds) @@ -908,6 +880,48 @@ class ConsMedShockSolver(ConsGenIncProcessSolver): Class for solving the one period problem for the "medical shocks" model, in which consumers receive shocks to permanent and transitory income as well as shocks to "medical need"-- multiplicative utility shocks for a second good. + + Parameters + ---------- + solution_next : ConsumerSolution + The solution to next period's one period problem. + IncomeDstn : [np.array] + A list containing three arrays of floats, representing a discrete + approximation to the income process between the period being solved + and the one immediately following (in solution_next). Order: event + probabilities, permanent shocks, transitory shocks. + MedShkDstn : [np.array] + Discrete distribution of the multiplicative utility shifter for med- + ical care. Order: probabilities, preference shocks. + LivPrb : float + Survival probability; likelihood of being alive at the beginning of + the succeeding period. + DiscFac : float + Intertemporal discount factor for future utility. + CRRA : float + Coefficient of relative risk aversion for composite consumption. + CRRAmed : float + Coefficient of relative risk aversion for medical care. + Rfree : float + Risk free interest factor on end-of-period assets. + MedPrice : float + Price of unit of medical care relative to unit of consumption. + pLvlNextFunc : float + Expected permanent income next period as a function of current pLvl. + BoroCnstArt: float or None + Borrowing constraint for the minimum allowable assets to end the + period with. + aXtraGrid: np.array + Array of "extra" end-of-period (normalized) asset values-- assets + above the absolute minimum acceptable level. + pLvlGrid: np.array + Array of permanent income levels at which to solve the problem. + vFuncBool: boolean + An indicator for whether the value function should be computed and + included in the reported solution. + CubicBool: boolean + An indicator for whether the solver should use cubic or linear inter- + polation. """ def __init__( @@ -928,56 +942,6 @@ def __init__( vFuncBool, CubicBool, ): - """ - Constructor for a new solver for a one period problem with idiosyncratic - shocks to permanent and transitory income and shocks to medical need. - - Parameters - ---------- - solution_next : ConsumerSolution - The solution to next period's one period problem. - IncomeDstn : [np.array] - A list containing three arrays of floats, representing a discrete - approximation to the income process between the period being solved - and the one immediately following (in solution_next). Order: event - probabilities, permanent shocks, transitory shocks. - MedShkDstn : [np.array] - Discrete distribution of the multiplicative utility shifter for med- - ical care. Order: probabilities, preference shocks. - LivPrb : float - Survival probability; likelihood of being alive at the beginning of - the succeeding period. - DiscFac : float - Intertemporal discount factor for future utility. - CRRA : float - Coefficient of relative risk aversion for composite consumption. - CRRAmed : float - Coefficient of relative risk aversion for medical care. - Rfree : float - Risk free interest factor on end-of-period assets. - MedPrice : float - Price of unit of medical care relative to unit of consumption. - pLvlNextFunc : float - Expected permanent income next period as a function of current pLvl. - BoroCnstArt: float or None - Borrowing constraint for the minimum allowable assets to end the - period with. - aXtraGrid: np.array - Array of "extra" end-of-period (normalized) asset values-- assets - above the absolute minimum acceptable level. - pLvlGrid: np.array - Array of permanent income levels at which to solve the problem. - vFuncBool: boolean - An indicator for whether the value function should be computed and - included in the reported solution. - CubicBool: boolean - An indicator for whether the solver should use cubic or linear inter- - polation. - - Returns - ------- - None - """ self.assignParameters( solution_next=solution_next, IncomeDstn=IncomeDstn, diff --git a/HARK/ConsumptionSaving/ConsPrefShockModel.py b/HARK/ConsumptionSaving/ConsPrefShockModel.py index 9d0f169bc..8fdf6f8d8 100644 --- a/HARK/ConsumptionSaving/ConsPrefShockModel.py +++ b/HARK/ConsumptionSaving/ConsPrefShockModel.py @@ -69,26 +69,19 @@ class PrefShockConsumerType(IndShockConsumerType): """ A class for representing consumers who experience multiplicative shocks to utility each period, specified as iid lognormal. + + See ConsumerParameters.init_pref_shock for a dictionary of + the keywords that should be passed to the constructor. + + Parameters + ---------- + cycles : int + Number of times the sequence of periods should be solved. """ shock_vars_ = IndShockConsumerType.shock_vars_ + ["PrefShkNow"] def __init__(self, cycles=1, **kwds): - """ - Instantiate a new ConsumerType with given data, and construct objects - to be used during solution (income distribution, assets grid, etc). - See ConsumerParameters.init_pref_shock for a dictionary of - the keywords that should be passed to the constructor. - - Parameters - ---------- - cycles : int - Number of times the sequence of periods should be solved. - - Returns - ------- - None>>>>>>> master - """ params = init_preference_shocks.copy() params.update(kwds) @@ -263,24 +256,17 @@ class KinkyPrefConsumerType(PrefShockConsumerType, KinkedRconsumerType): A class for representing consumers who experience multiplicative shocks to utility each period, specified as iid lognormal and different interest rates on borrowing vs saving. - """ - def __init__(self, cycles=1, **kwds): - """ - Instantiate a new ConsumerType with given data, and construct objects - to be used during solution (income distribution, assets grid, etc). - See init_kinky_pref for a dictionary of the keywords - that should be passed to the constructor. + See init_kinky_pref for a dictionary of the keywords + that should be passed to the constructor. - Parameters - ---------- - cycles : int - Number of times the sequence of periods should be solved. + Parameters + ---------- + cycles : int + Number of times the sequence of periods should be solved. + """ - Returns - ------- - None - """ + def __init__(self, cycles=1, **kwds): params = init_kinky_pref.copy() params.update(kwds) kwds = params @@ -304,6 +290,45 @@ class ConsPrefShockSolver(ConsIndShockSolver): A class for solving the one period consumption-saving problem with risky income (permanent and transitory shocks) and multiplicative shocks to utility each period. + + + Parameters + ---------- + solution_next : ConsumerSolution + The solution to the succeeding one period problem. + IncomeDstn : [np.array] + A list containing three arrays of floats, representing a discrete + approximation to the income process between the period being solved + and the one immediately following (in solution_next). Order: event + probabilities, permanent shocks, transitory shocks. + PrefShkDstn : [np.array] + Discrete distribution of the multiplicative utility shifter. Order: + probabilities, preference shocks. + LivPrb : float + Survival probability; likelihood of being alive at the beginning of + the succeeding period. + DiscFac : float + Intertemporal discount factor for future utility. + CRRA : float + Coefficient of relative risk aversion. + Rfree : float + Risk free interest factor on end-of-period assets. + PermGroGac : float + Expected permanent income growth factor at the end of this period. + BoroCnstArt: float or None + Borrowing constraint for the minimum allowable assets to end the + period with. If it is less than the natural borrowing constraint, + then it is irrelevant; BoroCnstArt=None indicates no artificial bor- + rowing constraint. + aXtraGrid: np.array + Array of "extra" end-of-period asset values-- assets above the + absolute minimum acceptable level. + vFuncBool: boolean + An indicator for whether the value function should be computed and + included in the reported solution. + CubicBool: boolean + An indicator for whether the solver should use cubic or linear inter- + polation. """ def __init__( @@ -325,43 +350,6 @@ def __init__( Constructor for a new solver for problems with risky income, a different interest rate on borrowing and saving, and multiplicative shocks to utility. - Parameters - ---------- - solution_next : ConsumerSolution - The solution to the succeeding one period problem. - IncomeDstn : [np.array] - A list containing three arrays of floats, representing a discrete - approximation to the income process between the period being solved - and the one immediately following (in solution_next). Order: event - probabilities, permanent shocks, transitory shocks. - PrefShkDstn : [np.array] - Discrete distribution of the multiplicative utility shifter. Order: - probabilities, preference shocks. - LivPrb : float - Survival probability; likelihood of being alive at the beginning of - the succeeding period. - DiscFac : float - Intertemporal discount factor for future utility. - CRRA : float - Coefficient of relative risk aversion. - Rfree : float - Risk free interest factor on end-of-period assets. - PermGroGac : float - Expected permanent income growth factor at the end of this period. - BoroCnstArt: float or None - Borrowing constraint for the minimum allowable assets to end the - period with. If it is less than the natural borrowing constraint, - then it is irrelevant; BoroCnstArt=None indicates no artificial bor- - rowing constraint. - aXtraGrid: np.array - Array of "extra" end-of-period asset values-- assets above the - absolute minimum acceptable level. - vFuncBool: boolean - An indicator for whether the value function should be computed and - included in the reported solution. - CubicBool: boolean - An indicator for whether the solver should use cubic or linear inter- - polation. Returns ------- @@ -622,6 +610,48 @@ class ConsKinkyPrefSolver(ConsPrefShockSolver, ConsKinkedRsolver): A class for solving the one period consumption-saving problem with risky income (permanent and transitory shocks), multiplicative shocks to utility each period, and a different interest rate on saving vs borrowing. + + Parameters + ---------- + solution_next : ConsumerSolution + The solution to the succeeding one period problem. + IncomeDstn : [np.array] + A list containing three arrays of floats, representing a discrete + approximation to the income process between the period being solved + and the one immediately following (in solution_next). Order: event + probabilities, permanent shocks, transitory shocks. + PrefShkDstn : [np.array] + Discrete distribution of the multiplicative utility shifter. Order: + probabilities, preference shocks. + LivPrb : float + Survival probability; likelihood of being alive at the beginning of + the succeeding period. + DiscFac : float + Intertemporal discount factor for future utility. + CRRA : float + Coefficient of relative risk aversion. + Rboro: float + Interest factor on assets between this period and the succeeding + period when assets are negative. + Rsave: float + Interest factor on assets between this period and the succeeding + period when assets are positive. + PermGroGac : float + Expected permanent income growth factor at the end of this period. + BoroCnstArt: float or None + Borrowing constraint for the minimum allowable assets to end the + period with. If it is less than the natural borrowing constraint, + then it is irrelevant; BoroCnstArt=None indicates no artificial bor- + rowing constraint. + aXtraGrid: np.array + Array of "extra" end-of-period asset values-- assets above the + absolute minimum acceptable level. + vFuncBool: boolean + An indicator for whether the value function should be computed and + included in the reported solution. + CubicBool: boolean + An indicator for whether the solver should use cubic or linear inter- + polation. """ def __init__( @@ -640,56 +670,6 @@ def __init__( vFuncBool, CubicBool, ): - """ - Constructor for a new solver for problems with risky income, a different - interest rate on borrowing and saving, and multiplicative shocks to utility. - - Parameters - ---------- - solution_next : ConsumerSolution - The solution to the succeeding one period problem. - IncomeDstn : [np.array] - A list containing three arrays of floats, representing a discrete - approximation to the income process between the period being solved - and the one immediately following (in solution_next). Order: event - probabilities, permanent shocks, transitory shocks. - PrefShkDstn : [np.array] - Discrete distribution of the multiplicative utility shifter. Order: - probabilities, preference shocks. - LivPrb : float - Survival probability; likelihood of being alive at the beginning of - the succeeding period. - DiscFac : float - Intertemporal discount factor for future utility. - CRRA : float - Coefficient of relative risk aversion. - Rboro: float - Interest factor on assets between this period and the succeeding - period when assets are negative. - Rsave: float - Interest factor on assets between this period and the succeeding - period when assets are positive. - PermGroGac : float - Expected permanent income growth factor at the end of this period. - BoroCnstArt: float or None - Borrowing constraint for the minimum allowable assets to end the - period with. If it is less than the natural borrowing constraint, - then it is irrelevant; BoroCnstArt=None indicates no artificial bor- - rowing constraint. - aXtraGrid: np.array - Array of "extra" end-of-period asset values-- assets above the - absolute minimum acceptable level. - vFuncBool: boolean - An indicator for whether the value function should be computed and - included in the reported solution. - CubicBool: boolean - An indicator for whether the solver should use cubic or linear inter- - polation. - - Returns - ------- - None - """ ConsKinkedRsolver.__init__( self, solution_next, diff --git a/HARK/ConsumptionSaving/ConsRepAgentModel.py b/HARK/ConsumptionSaving/ConsRepAgentModel.py index 499c96630..ba491dbc6 100644 --- a/HARK/ConsumptionSaving/ConsRepAgentModel.py +++ b/HARK/ConsumptionSaving/ConsRepAgentModel.py @@ -229,21 +229,17 @@ def solveConsRepAgentMarkov( class RepAgentConsumerType(IndShockConsumerType): """ A class for representing representative agents with inelastic labor supply. + + Parameters + ---------- + cycles : int + Number of times the sequence of periods should be solved. + """ time_inv_ = IndShockConsumerType.time_inv_ + ["CapShare", "DeprFac"] def __init__(self, **kwds): - """ - Make a new instance of a representative agent. - - Parameters - ---------- - - Returns - ------- - None - """ params = init_rep_agent.copy() params.update(kwds) @@ -300,21 +296,14 @@ class RepAgentMarkovConsumerType(RepAgentConsumerType): """ A class for representing representative agents with inelastic labor supply and a discrete MarkovState + + Parameters + ---------- """ time_inv_ = RepAgentConsumerType.time_inv_ + ["MrkvArray"] def __init__(self, **kwds): - """ - Make a new instance of a representative agent with Markov state. - - Parameters - ---------- - - Returns - ------- - None - """ params = init_markov_rep_agent.copy() params.update(kwds) diff --git a/HARK/ConsumptionSaving/TractableBufferStockModel.py b/HARK/ConsumptionSaving/TractableBufferStockModel.py index 54a9926c8..733f68157 100644 --- a/HARK/ConsumptionSaving/TractableBufferStockModel.py +++ b/HARK/ConsumptionSaving/TractableBufferStockModel.py @@ -66,6 +66,20 @@ class TractableConsumerSolution(HARKobject): cNrm_list, a list of MPCs MPC_list, a perfect foresight consumption function while employed, and a perfect foresight consumption function while unemployed. The solution includes a consumption function constructed from the lists. + + Parameters + ---------- + mNrm_list : [float] + List of normalized market resources points on the stable arm. + cNrm_list : [float] + List of normalized consumption points on the stable arm. + MPC_list : [float] + List of marginal propensities to consume on the stable arm, corres- + ponding to the (mNrm,cNrm) points. + cFunc_U : function + The (linear) consumption function when permanently unemployed. + cFunc : function + The consumption function when employed. """ def __init__( @@ -76,27 +90,6 @@ def __init__( cFunc_U=NullFunc, cFunc=NullFunc, ): - """ - The constructor for a new TractableConsumerSolution object. - - Parameters - ---------- - mNrm_list : [float] - List of normalized market resources points on the stable arm. - cNrm_list : [float] - List of normalized consumption points on the stable arm. - MPC_list : [float] - List of marginal propensities to consume on the stable arm, corres- - ponding to the (mNrm,cNrm) points. - cFunc_U : function - The (linear) consumption function when permanently unemployed. - cFunc : function - The consumption function when employed. - - Returns - ------- - new instance of TractableConsumerSolution - """ self.mNrm_list = mNrm_list if mNrm_list is not None else list() self.cNrm_list = cNrm_list if cNrm_list is not None else list() self.MPC_list = MPC_list if MPC_list is not None else list() @@ -304,22 +297,16 @@ def addToStableArmPoints( class TractableConsumerType(AgentType): + """ + Parameters + ---------- + cycles : int + Number of times the sequence of periods should be solved. + """ state_vars = ['bLvlNow', 'mLvlNow', "aLvlNow"] def __init__(self, cycles=0, **kwds): - """ - Instantiate a new TractableConsumerType with given data. - - Parameters - ---------- - cycles : int - Number of times the sequence of periods should be solved. - - Returns: - ----------- - New instance of TractableConsumerType. - """ params = init_tractable.copy() params.update(kwds) # Initialize a basic AgentType diff --git a/HARK/core.py b/HARK/core.py index 9035a0da2..41e3caa26 100644 --- a/HARK/core.py +++ b/HARK/core.py @@ -235,7 +235,6 @@ class AgentType(HARKobject): Attributes ---------- - AgentCount : int The number of agents of this type to use in simulation. @@ -1050,6 +1049,42 @@ class Market(HARKobject): A superclass to represent a central clearinghouse of information. Used for dynamic general equilibrium models to solve the "macroeconomic" model as a layer on top of the "microeconomic" models of one or more AgentTypes. + + Parameters + ---------- + agents : [AgentType] + A list of all the AgentTypes in this market. + sow_vars : [string] + Names of variables generated by the "aggregate market process" that should + be "sown" to the agents in the market. Aggregate state, etc. + reap_vars : [string] + Names of variables to be collected ("reaped") from agents in the market + to be used in the "aggregate market process". + const_vars : [string] + Names of attributes of the Market instance that are used in the "aggregate + market process" but do not come from agents-- they are constant or simply + parameters inherent to the process. + track_vars : [string] + Names of variables generated by the "aggregate market process" that should + be tracked as a "history" so that a new dynamic rule can be calculated. + This is often a subset of sow_vars. + dyn_vars : [string] + Names of variables that constitute a "dynamic rule". + millRule : function + A function that takes inputs named in reap_vars and returns a tuple the same size and order as sow_vars. The "aggregate market process" that + transforms individual agent actions/states/data into aggregate data to + be sent back to agents. + calcDynamics : function + A function that takes inputs named in track_vars and returns an object + with attributes named in dyn_vars. Looks at histories of aggregate + variables and generates a new "dynamic rule" for agents to believe and + act on. + act_T : int + The number of times that the "aggregate market process" should be run + in order to generate a history of aggregate variables. + tolerance: float + Minimum acceptable distance between "dynamic rules" to consider the + Market solution process converged. Distance is a user-defined metric. """ def __init__( @@ -1066,49 +1101,6 @@ def __init__( tolerance=0.000001, **kwds ): - """ - Make a new instance of the Market class. - - Parameters - ---------- - agents : [AgentType] - A list of all the AgentTypes in this market. - sow_vars : [string] - Names of variables generated by the "aggregate market process" that should - be "sown" to the agents in the market. Aggregate state, etc. - reap_vars : [string] - Names of variables to be collected ("reaped") from agents in the market - to be used in the "aggregate market process". - const_vars : [string] - Names of attributes of the Market instance that are used in the "aggregate - market process" but do not come from agents-- they are constant or simply - parameters inherent to the process. - track_vars : [string] - Names of variables generated by the "aggregate market process" that should - be tracked as a "history" so that a new dynamic rule can be calculated. - This is often a subset of sow_vars. - dyn_vars : [string] - Names of variables that constitute a "dynamic rule". - millRule : function - A function that takes inputs named in reap_vars and returns a tuple the same size and order as sow_vars. The "aggregate market process" that - transforms individual agent actions/states/data into aggregate data to - be sent back to agents. - calcDynamics : function - A function that takes inputs named in track_vars and returns an object - with attributes named in dyn_vars. Looks at histories of aggregate - variables and generates a new "dynamic rule" for agents to believe and - act on. - act_T : int - The number of times that the "aggregate market process" should be run - in order to generate a history of aggregate variables. - tolerance: float - Minimum acceptable distance between "dynamic rules" to consider the - Market solution process converged. Distance is a user-defined metric. - - Returns - ------- - None - """ self.agents = agents if agents is not None else list() # NOQA reap_vars = reap_vars if reap_vars is not None else list() # NOQA diff --git a/HARK/distribution.py b/HARK/distribution.py index 6a4d2bb1b..c4cb93eec 100644 --- a/HARK/distribution.py +++ b/HARK/distribution.py @@ -6,15 +6,14 @@ class Distribution: + """ + Parameters + ---------- + seed : int + Seed for random number generator. + """ def __init__(self, seed=0): - """ - Initialize the distribution. - - Parameters - ---------- - seed : int - Seed for random number generator. - """ + self.RNG = np.random.RandomState(seed) self.seed = seed @@ -34,26 +33,23 @@ def reset(self): class Lognormal(Distribution): """ A Lognormal distribution + + Parameters + ---------- + mu : float or [float] + One or more means. Number of elements T in mu determines number + of rows of output. + sigma : float or [float] + One or more standard deviations. Number of elements T in sigma + determines number of rows of output. + seed : int + Seed for random number generator. """ mu = None sigma = None def __init__(self, mu=0.0, sigma=1.0, seed=0): - """ - Initialize the distribution. - - Parameters - ---------- - mu : float or [float] - One or more means. Number of elements T in mu determines number - of rows of output. - sigma : float or [float] - One or more standard deviations. Number of elements T in sigma - determines number of rows of output. - seed : int - Seed for random number generator. - """ self.mu = mu self.sigma = sigma # Set up the RNG @@ -255,26 +251,23 @@ def __init__(self, sigma=1.0, seed=0): class Normal(Distribution): """ A Normal distribution. + + Parameters + ---------- + mu : float or [float] + One or more means. Number of elements T in mu determines number + of rows of output. + sigma : float or [float] + One or more standard deviations. Number of elements T in sigma + determines number of rows of output. + seed : int + Seed for random number generator. """ mu = None sigma = None def __init__(self, mu=0.0, sigma=1.0, seed=0): - """ - Initialize the distribution. - - Parameters - ---------- - mu : float or [float] - One or more means. Number of elements T in mu determines number - of rows of output. - sigma : float or [float] - One or more standard deviations. Number of elements T in sigma - determines number of rows of output. - seed : int - Seed for random number generator. - """ self.mu = mu self.sigma = sigma super().__init__(seed) @@ -323,28 +316,25 @@ def approx(self, N): class Weibull(Distribution): """ - A Weibull distribution + A Weibull distribution. + + Parameters + ---------- + scale : float or [float] + One or more scales. Number of elements T in scale + determines number of + rows of output. + shape : float or [float] + One or more shape parameters. Number of elements T in scale + determines number of rows of output. + seed : int + Seed for random number generator. """ scale = None shape = None def __init__(self, scale=1.0, shape=1.0, seed=0): - """ - Initialize the distribution. - - Parameters - ---------- - scale : float or [float] - One or more scales. Number of elements T in scale - determines number of - rows of output. - shape : float or [float] - One or more shape parameters. Number of elements T in scale - determines number of rows of output. - seed : int - Seed for random number generator. - """ self.scale = scale self.shape = shape # Set up the RNG @@ -390,28 +380,25 @@ def draw(self, N): class Uniform(Distribution): """ A Uniform distribution. + + Parameters + ---------- + bot : float or [float] + One or more bottom values. + Number of elements T in mu determines number + of rows of output. + top : float or [float] + One or more top values. + Number of elements T in top determines number of + rows of output. + seed : int + Seed for random number generator. """ bot = None top = None def __init__(self, bot=0.0, top=1.0, seed=0): - """ - Initialize the distribution. - - Parameters - ---------- - bot : float or [float] - One or more bottom values. - Number of elements T in mu determines number - of rows of output. - top : float or [float] - One or more top values. - Number of elements T in top determines number of - rows of output. - seed : int - Seed for random number generator. - """ self.bot = bot self.top = top # Set up the RNG @@ -479,22 +466,19 @@ def approx(self, N): class Bernoulli(Distribution): """ A Bernoulli distribution. + + Parameters + ---------- + p : float or [float] + Probability or probabilities of the event occurring (True). + + seed : int + Seed for random number generator. """ p = None def __init__(self, p=0.5, seed=0): - """ - Initialize the distribution. - - Parameters - ---------- - p : float or [float] - Probability or probabilities of the event occurring (True). - - seed : int - Seed for random number generator. - """ self.p = p # Set up the RNG super().__init__(seed) @@ -530,25 +514,21 @@ class DiscreteDistribution(Distribution): """ A representation of a discrete probability distribution. + Parameters + ---------- + pmf : np.array + An array of floats representing a probability mass function. + X : np.array or [np.array] + Discrete point values for each probability mass. + May be multivariate (list of arrays). + seed : int + Seed for random number generator. """ pmf = None X = None def __init__(self, pmf, X, seed=0): - """ - Initialize a discrete distribution. - - Parameters - ---------- - pmf : np.array - An array of floats representing a probability mass function. - X : np.array or [np.array] - Discrete point values for each probability mass. - May be multivariate (list of arrays). - seed : int - Seed for random number generator. - """ self.pmf = pmf self.X = X # Set up the RNG diff --git a/HARK/interpolation.py b/HARK/interpolation.py index 77de86f6a..d2215abdf 100644 --- a/HARK/interpolation.py +++ b/HARK/interpolation.py @@ -584,25 +584,18 @@ class IdentityFunction(HARKobject): """ A fairly trivial interpolator that simply returns one of its arguments. Useful for avoiding numeric error in extreme cases. + + Parameters + ---------- + i_dim : int + Index of the dimension on which the identity is defined. f(*x) = x[i] + n_dims : int + Total number of input dimensions for this function. """ distance_criteria = ["i_dim"] def __init__(self, i_dim=0, n_dims=1): - """ - Constructor for a new IdentityFunction. - - Parameters - ---------- - i_dim : int - Index of the dimension on which the identity is defined. f(*x) = x[i] - n_dims : int - Total number of input dimensions for this function. - - Returns - ------- - None - """ self.i_dim = i_dim self.n_dims = n_dims @@ -689,23 +682,16 @@ class ConstantFunction(HARKobject): allows the user to quickly make a constant/trivial function. This comes up, e.g., in models with endogenous pricing of insurance contracts; a contract's premium might depend on some state variables of the individual, but in some variations the premium of a contract is just a number. + + Parameters + ---------- + value : float + The constant value that the function returns. """ convergence_criteria = ["value"] def __init__(self, value): - """ - Make a new ConstantFunction object. - - Parameters - ---------- - value : float - The constant value that the function returns. - - Returns - ------- - None - """ self.value = float(value) def __call__(self, *args): @@ -751,6 +737,23 @@ class LinearInterp(HARKinterpolator1D): """ A "from scratch" 1D linear interpolation class. Allows for linear or decay extrapolation (approaching a limiting linear function from below). + + NOTE: When no input is given for the limiting linear function, linear + extrapolation is used above the highest gridpoint. + + Parameters + ---------- + x_list : np.array + List of x values composing the grid. + y_list : np.array + List of y values, representing f(x) at the points in x_list. + intercept_limit : float + Intercept of limiting linear function. + slope_limit : float + Slope of limiting linear function. + lower_extrap : boolean + Indicator for whether lower extrapolation is allowed. False means + f(x) = NaN for x < min(x_list); True means linear extrapolation. """ distance_criteria = ["x_list", "y_list"] @@ -758,30 +761,6 @@ class LinearInterp(HARKinterpolator1D): def __init__( self, x_list, y_list, intercept_limit=None, slope_limit=None, lower_extrap=False ): - """ - The interpolation constructor to make a new linear spline interpolation. - - Parameters - ---------- - x_list : np.array - List of x values composing the grid. - y_list : np.array - List of y values, representing f(x) at the points in x_list. - intercept_limit : float - Intercept of limiting linear function. - slope_limit : float - Slope of limiting linear function. - lower_extrap : boolean - Indicator for whether lower extrapolation is allowed. False means - f(x) = NaN for x < min(x_list); True means linear extrapolation. - - Returns - ------- - new instance of LinearInterp - - NOTE: When no input is given for the limiting linear function, linear - extrapolation is used above the highest gridpoint. - """ # Make the basic linear spline interpolation self.x_list = ( np.array(x_list) @@ -909,6 +888,25 @@ class CubicInterp(HARKinterpolator1D): slope of 1D function at gridpoints, smoothly interpolating in between. Extrapolation above highest gridpoint approaches a limiting linear function if desired (linear extrapolation also enabled.) + + NOTE: When no input is given for the limiting linear function, linear + extrapolation is used above the highest gridpoint. + + Parameters + ---------- + x_list : np.array + List of x values composing the grid. + y_list : np.array + List of y values, representing f(x) at the points in x_list. + dydx_list : np.array + List of dydx values, representing f'(x) at the points in x_list + intercept_limit : float + Intercept of limiting linear function. + slope_limit : float + Slope of limiting linear function. + lower_extrap : boolean + Indicator for whether lower extrapolation is allowed. False means + f(x) = NaN for x < min(x_list); True means linear extrapolation. """ distance_criteria = ["x_list", "y_list", "dydx_list"] @@ -922,32 +920,6 @@ def __init__( slope_limit=None, lower_extrap=False, ): - """ - The interpolation constructor to make a new cubic spline interpolation. - - Parameters - ---------- - x_list : np.array - List of x values composing the grid. - y_list : np.array - List of y values, representing f(x) at the points in x_list. - dydx_list : np.array - List of dydx values, representing f'(x) at the points in x_list - intercept_limit : float - Intercept of limiting linear function. - slope_limit : float - Slope of limiting linear function. - lower_extrap : boolean - Indicator for whether lower extrapolation is allowed. False means - f(x) = NaN for x < min(x_list); True means linear extrapolation. - - Returns - ------- - new instance of CubicInterp - - NOTE: When no input is given for the limiting linear function, linear - extrapolation is used above the highest gridpoint. - """ self.x_list = ( np.asarray(x_list) if _check_flatten(1, x_list) @@ -1197,33 +1169,26 @@ def _evalAndDer(self, x): class BilinearInterp(HARKinterpolator2D): """ Bilinear full (or tensor) grid interpolation of a function f(x,y). + + Parameters + ---------- + f_values : numpy.array + An array of size (x_n,y_n) such that f_values[i,j] = f(x_list[i],y_list[j]) + x_list : numpy.array + An array of x values, with length designated x_n. + y_list : numpy.array + An array of y values, with length designated y_n. + xSearchFunc : function + An optional function that returns the reference location for x values: + indices = xSearchFunc(x_list,x). Default is np.searchsorted + ySearchFunc : function + An optional function that returns the reference location for y values: + indices = ySearchFunc(y_list,y). Default is np.searchsorted """ distance_criteria = ["x_list", "y_list", "f_values"] def __init__(self, f_values, x_list, y_list, xSearchFunc=None, ySearchFunc=None): - """ - Constructor to make a new bilinear interpolation. - - Parameters - ---------- - f_values : numpy.array - An array of size (x_n,y_n) such that f_values[i,j] = f(x_list[i],y_list[j]) - x_list : numpy.array - An array of x values, with length designated x_n. - y_list : numpy.array - An array of y values, with length designated y_n. - xSearchFunc : function - An optional function that returns the reference location for x values: - indices = xSearchFunc(x_list,x). Default is np.searchsorted - ySearchFunc : function - An optional function that returns the reference location for y values: - indices = ySearchFunc(y_list,y). Default is np.searchsorted - - Returns - ------- - new instance of BilinearInterp - """ self.f_values = f_values self.x_list = ( np.array(x_list) @@ -1338,6 +1303,27 @@ def _derY(self, x, y): class TrilinearInterp(HARKinterpolator3D): """ Trilinear full (or tensor) grid interpolation of a function f(x,y,z). + + Parameters + ---------- + f_values : numpy.array + An array of size (x_n,y_n,z_n) such that f_values[i,j,k] = + f(x_list[i],y_list[j],z_list[k]) + x_list : numpy.array + An array of x values, with length designated x_n. + y_list : numpy.array + An array of y values, with length designated y_n. + z_list : numpy.array + An array of z values, with length designated z_n. + xSearchFunc : function + An optional function that returns the reference location for x values: + indices = xSearchFunc(x_list,x). Default is np.searchsorted + ySearchFunc : function + An optional function that returns the reference location for y values: + indices = ySearchFunc(y_list,y). Default is np.searchsorted + zSearchFunc : function + An optional function that returns the reference location for z values: + indices = zSearchFunc(z_list,z). Default is np.searchsorted """ distance_criteria = ["f_values", "x_list", "y_list", "z_list"] @@ -1352,34 +1338,6 @@ def __init__( ySearchFunc=None, zSearchFunc=None, ): - """ - Constructor to make a new trilinear interpolation. - - Parameters - ---------- - f_values : numpy.array - An array of size (x_n,y_n,z_n) such that f_values[i,j,k] = - f(x_list[i],y_list[j],z_list[k]) - x_list : numpy.array - An array of x values, with length designated x_n. - y_list : numpy.array - An array of y values, with length designated y_n. - z_list : numpy.array - An array of z values, with length designated z_n. - xSearchFunc : function - An optional function that returns the reference location for x values: - indices = xSearchFunc(x_list,x). Default is np.searchsorted - ySearchFunc : function - An optional function that returns the reference location for y values: - indices = ySearchFunc(y_list,y). Default is np.searchsorted - zSearchFunc : function - An optional function that returns the reference location for z values: - indices = zSearchFunc(z_list,z). Default is np.searchsorted - - Returns - ------- - new instance of TrilinearInterp - """ self.f_values = f_values self.x_list = ( np.array(x_list) @@ -1595,6 +1553,32 @@ def _derZ(self, x, y, z): class QuadlinearInterp(HARKinterpolator4D): """ Quadlinear full (or tensor) grid interpolation of a function f(w,x,y,z). + + Parameters + ---------- + f_values : numpy.array + An array of size (w_n,x_n,y_n,z_n) such that f_values[i,j,k,l] = + f(w_list[i],x_list[j],y_list[k],z_list[l]) + w_list : numpy.array + An array of x values, with length designated w_n. + x_list : numpy.array + An array of x values, with length designated x_n. + y_list : numpy.array + An array of y values, with length designated y_n. + z_list : numpy.array + An array of z values, with length designated z_n. + wSearchFunc : function + An optional function that returns the reference location for w values: + indices = wSearchFunc(w_list,w). Default is np.searchsorted + xSearchFunc : function + An optional function that returns the reference location for x values: + indices = xSearchFunc(x_list,x). Default is np.searchsorted + ySearchFunc : function + An optional function that returns the reference location for y values: + indices = ySearchFunc(y_list,y). Default is np.searchsorted + zSearchFunc : function + An optional function that returns the reference location for z values: + indices = zSearchFunc(z_list,z). Default is np.searchsorted """ distance_criteria = ["f_values", "w_list", "x_list", "y_list", "z_list"] @@ -1611,39 +1595,6 @@ def __init__( ySearchFunc=None, zSearchFunc=None, ): - """ - Constructor to make a new quadlinear interpolation. - - Parameters - ---------- - f_values : numpy.array - An array of size (w_n,x_n,y_n,z_n) such that f_values[i,j,k,l] = - f(w_list[i],x_list[j],y_list[k],z_list[l]) - w_list : numpy.array - An array of x values, with length designated w_n. - x_list : numpy.array - An array of x values, with length designated x_n. - y_list : numpy.array - An array of y values, with length designated y_n. - z_list : numpy.array - An array of z values, with length designated z_n. - wSearchFunc : function - An optional function that returns the reference location for w values: - indices = wSearchFunc(w_list,w). Default is np.searchsorted - xSearchFunc : function - An optional function that returns the reference location for x values: - indices = xSearchFunc(x_list,x). Default is np.searchsorted - ySearchFunc : function - An optional function that returns the reference location for y values: - indices = ySearchFunc(y_list,y). Default is np.searchsorted - zSearchFunc : function - An optional function that returns the reference location for z values: - indices = zSearchFunc(z_list,z). Default is np.searchsorted - - Returns - ------- - new instance of QuadlinearInterp - """ self.f_values = f_values self.w_list = ( np.array(w_list) @@ -2031,25 +1982,19 @@ class LowerEnvelope(HARKinterpolator1D): The lower envelope of a finite set of 1D functions, each of which can be of any class that has the methods __call__, derivative, and eval_with_derivative. Generally: it combines HARKinterpolator1Ds. + + Parameters + ---------- + *functions : function + Any number of real functions; often instances of HARKinterpolator1D + nan_bool : boolean + An indicator for whether the solver should exclude NA's when + forming the lower envelope """ distance_criteria = ["functions"] def __init__(self, *functions, nan_bool=True): - """ - Constructor to make a new lower envelope iterpolation. - - Parameters - ---------- - *functions : function - Any number of real functions; often instances of HARKinterpolator1D - nan_bool : boolean - An indicator for whether the solver should exclude NA's when - forming the lower envelope - Returns - ------- - new instance of LowerEnvelope - """ if nan_bool: self.compare = np.nanmin @@ -2110,25 +2055,19 @@ class UpperEnvelope(HARKinterpolator1D): The upper envelope of a finite set of 1D functions, each of which can be of any class that has the methods __call__, derivative, and eval_with_derivative. Generally: it combines HARKinterpolator1Ds. + + Parameters + ---------- + *functions : function + Any number of real functions; often instances of HARKinterpolator1D + nan_bool : boolean + An indicator for whether the solver should exclude NA's when forming + the lower envelope. """ distance_criteria = ["functions"] def __init__(self, *functions, nan_bool=True): - """ - Constructor to make a new upper envelope iterpolation. - - Parameters - ---------- - *functions : function - Any number of real functions; often instances of HARKinterpolator1D - nan_bool : boolean - An indicator for whether the solver should exclude NA's when forming - the lower envelope. - Returns - ------- - new instance of UpperEnvelope - """ if nan_bool: self.compare = np.nanmax self.argcompare = np.nanargmax @@ -2186,25 +2125,19 @@ class LowerEnvelope2D(HARKinterpolator2D): The lower envelope of a finite set of 2D functions, each of which can be of any class that has the methods __call__, derivativeX, and derivativeY. Generally: it combines HARKinterpolator2Ds. + + Parameters + ---------- + *functions : function + Any number of real functions; often instances of HARKinterpolator2D + nan_bool : boolean + An indicator for whether the solver should exclude NA's when forming + the lower envelope. """ distance_criteria = ["functions"] def __init__(self, *functions, nan_bool=True): - """ - Constructor to make a new lower envelope iterpolation. - - Parameters - ---------- - *functions : function - Any number of real functions; often instances of HARKinterpolator2D - nan_bool : boolean - An indicator for whether the solver should exclude NA's when forming - the lower envelope. - Returns - ------- - new instance of LowerEnvelope2D - """ if nan_bool: self.compare = np.nanmin self.argcompare = np.nanargmin @@ -2271,25 +2204,19 @@ class LowerEnvelope3D(HARKinterpolator3D): The lower envelope of a finite set of 3D functions, each of which can be of any class that has the methods __call__, derivativeX, derivativeY, and derivativeZ. Generally: it combines HARKinterpolator2Ds. + + Parameters + ---------- + *functions : function + Any number of real functions; often instances of HARKinterpolator3D + nan_bool : boolean + An indicator for whether the solver should exclude NA's when forming + the lower envelope. """ distance_criteria = ["functions"] def __init__(self, *functions, nan_bool=True): - """ - Constructor to make a new lower envelope iterpolation. - - Parameters - ---------- - *functions : function - Any number of real functions; often instances of HARKinterpolator3D - nan_bool : boolean - An indicator for whether the solver should exclude NA's when forming - the lower envelope. - Returns - ------- - None - """ if nan_bool: self.compare = np.nanmin self.argcompare = np.nanargmin @@ -2373,27 +2300,20 @@ class VariableLowerBoundFunc2D(HARKobject): A class for representing a function with two real inputs whose lower bound in the first input depends on the second input. Useful for managing curved natural borrowing constraints, as occurs in the persistent shocks model. + + Parameters + ---------- + func : function + A function f: (R_+ x R) --> R representing the function of interest + shifted by its lower bound in the first input. + lowerBound : function + The lower bound in the first input of the function of interest, as + a function of the second input. """ distance_criteria = ["func", "lowerBound"] def __init__(self, func, lowerBound): - """ - Make a new instance of VariableLowerBoundFunc2D. - - Parameters - ---------- - func : function - A function f: (R_+ x R) --> R representing the function of interest - shifted by its lower bound in the first input. - lowerBound : function - The lower bound in the first input of the function of interest, as - a function of the second input. - - Returns - ------- - None - """ self.func = func self.lowerBound = lowerBound @@ -2469,27 +2389,20 @@ class VariableLowerBoundFunc3D(HARKobject): A class for representing a function with three real inputs whose lower bound in the first input depends on the second input. Useful for managing curved natural borrowing constraints. + + Parameters + ---------- + func : function + A function f: (R_+ x R^2) --> R representing the function of interest + shifted by its lower bound in the first input. + lowerBound : function + The lower bound in the first input of the function of interest, as + a function of the second input. """ distance_criteria = ["func", "lowerBound"] def __init__(self, func, lowerBound): - """ - Make a new instance of VariableLowerBoundFunc3D. - - Parameters - ---------- - func : function - A function f: (R_+ x R^2) --> R representing the function of interest - shifted by its lower bound in the first input. - lowerBound : function - The lower bound in the first input of the function of interest, as - a function of the second input. - - Returns - ------- - None - """ self.func = func self.lowerBound = lowerBound @@ -2593,28 +2506,19 @@ def derivativeZ(self, x, y, z): class LinearInterpOnInterp1D(HARKinterpolator2D): """ A 2D interpolator that linearly interpolates among a list of 1D interpolators. + + Parameters + ---------- + xInterpolators : [HARKinterpolator1D] + A list of 1D interpolations over the x variable. The nth element of + xInterpolators represents f(x,y_values[n]). + y_values: numpy.array + An array of y values equal in length to xInterpolators. """ distance_criteria = ["xInterpolators", "y_list"] def __init__(self, xInterpolators, y_values): - """ - Constructor for the class, generating an approximation to a function of - the form f(x,y) using interpolations over f(x,y_0) for a fixed grid of - y_0 values. - - Parameters - ---------- - xInterpolators : [HARKinterpolator1D] - A list of 1D interpolations over the x variable. The nth element of - xInterpolators represents f(x,y_values[n]). - y_values: numpy.array - An array of y values equal in length to xInterpolators. - - Returns - ------- - new instance of LinearInterpOnInterp1D - """ self.xInterpolators = xInterpolators self.y_list = y_values self.y_n = y_values.size @@ -2712,30 +2616,25 @@ class BilinearInterpOnInterp1D(HARKinterpolator3D): """ A 3D interpolator that bilinearly interpolates among a list of lists of 1D interpolators. + + Constructor for the class, generating an approximation to a function of + the form f(x,y,z) using interpolations over f(x,y_0,z_0) for a fixed grid + of y_0 and z_0 values. + + Parameters + ---------- + xInterpolators : [[HARKinterpolator1D]] + A list of lists of 1D interpolations over the x variable. The i,j-th + element of xInterpolators represents f(x,y_values[i],z_values[j]). + y_values: numpy.array + An array of y values equal in length to xInterpolators. + z_values: numpy.array + An array of z values equal in length to xInterpolators[0]. """ distance_criteria = ["xInterpolators", "y_list", "z_list"] def __init__(self, xInterpolators, y_values, z_values): - """ - Constructor for the class, generating an approximation to a function of - the form f(x,y,z) using interpolations over f(x,y_0,z_0) for a fixed grid - of y_0 and z_0 values. - - Parameters - ---------- - xInterpolators : [[HARKinterpolator1D]] - A list of lists of 1D interpolations over the x variable. The i,j-th - element of xInterpolators represents f(x,y_values[i],z_values[j]). - y_values: numpy.array - An array of y values equal in length to xInterpolators. - z_values: numpy.array - An array of z values equal in length to xInterpolators[0]. - - Returns - ------- - new instance of BilinearInterpOnInterp1D - """ self.xInterpolators = xInterpolators self.y_list = y_values self.y_n = y_values.size @@ -2948,32 +2847,27 @@ def _derZ(self, x, y, z): class TrilinearInterpOnInterp1D(HARKinterpolator4D): """ A 4D interpolator that trilinearly interpolates among a list of lists of 1D interpolators. + + Constructor for the class, generating an approximation to a function of + the form f(w,x,y,z) using interpolations over f(w,x_0,y_0,z_0) for a fixed + grid of y_0 and z_0 values. + + Parameters + ---------- + wInterpolators : [[[HARKinterpolator1D]]] + A list of lists of lists of 1D interpolations over the x variable. + The i,j,k-th element of wInterpolators represents f(w,x_values[i],y_values[j],z_values[k]). + x_values: numpy.array + An array of x values equal in length to wInterpolators. + y_values: numpy.array + An array of y values equal in length to wInterpolators[0]. + z_values: numpy.array + An array of z values equal in length to wInterpolators[0][0] """ distance_criteria = ["wInterpolators", "x_list", "y_list", "z_list"] def __init__(self, wInterpolators, x_values, y_values, z_values): - """ - Constructor for the class, generating an approximation to a function of - the form f(w,x,y,z) using interpolations over f(w,x_0,y_0,z_0) for a fixed - grid of y_0 and z_0 values. - - Parameters - ---------- - wInterpolators : [[[HARKinterpolator1D]]] - A list of lists of lists of 1D interpolations over the x variable. - The i,j,k-th element of wInterpolators represents f(w,x_values[i],y_values[j],z_values[k]). - x_values: numpy.array - An array of x values equal in length to wInterpolators. - y_values: numpy.array - An array of y values equal in length to wInterpolators[0]. - z_values: numpy.array - An array of z values equal in length to wInterpolators[0][0] - - Returns - ------- - new instance of TrilinearInterpOnInterp1D - """ self.wInterpolators = wInterpolators self.x_list = x_values self.x_n = x_values.size @@ -3502,28 +3396,23 @@ class LinearInterpOnInterp2D(HARKinterpolator3D): variables and one exogenous state variable when solving with the endogenous grid method. NOTE: should not be used if an exogenous 3D grid is used, will be significantly slower than TrilinearInterp. + + Constructor for the class, generating an approximation to a function of + the form f(x,y,z) using interpolations over f(x,y,z_0) for a fixed grid + of z_0 values. + + Parameters + ---------- + xyInterpolators : [HARKinterpolator2D] + A list of 2D interpolations over the x and y variables. The nth + element of xyInterpolators represents f(x,y,z_values[n]). + z_values: numpy.array + An array of z values equal in length to xyInterpolators. """ distance_criteria = ["xyInterpolators", "z_list"] def __init__(self, xyInterpolators, z_values): - """ - Constructor for the class, generating an approximation to a function of - the form f(x,y,z) using interpolations over f(x,y,z_0) for a fixed grid - of z_0 values. - - Parameters - ---------- - xyInterpolators : [HARKinterpolator2D] - A list of 2D interpolations over the x and y variables. The nth - element of xyInterpolators represents f(x,y,z_values[n]). - z_values: numpy.array - An array of z values equal in length to xyInterpolators. - - Returns - ------- - new instance of LinearInterpOnInterp2D - """ self.xyInterpolators = xyInterpolators self.z_list = z_values self.z_n = z_values.size @@ -3656,31 +3545,26 @@ class BilinearInterpOnInterp2D(HARKinterpolator4D): variables and two exogenous state variables when solving with the endogenous grid method. NOTE: should not be used if an exogenous 4D grid is used, will be significantly slower than QuadlinearInterp. + + Constructor for the class, generating an approximation to a function of + the form f(w,x,y,z) using interpolations over f(w,x,y_0,z_0) for a fixed + grid of y_0 and z_0 values. + + Parameters + ---------- + wxInterpolators : [[HARKinterpolator2D]] + A list of lists of 2D interpolations over the w and x variables. + The i,j-th element of wxInterpolators represents + f(w,x,y_values[i],z_values[j]). + y_values: numpy.array + An array of y values equal in length to wxInterpolators. + z_values: numpy.array + An array of z values equal in length to wxInterpolators[0]. """ distance_criteria = ["wxInterpolators", "y_list", "z_list"] def __init__(self, wxInterpolators, y_values, z_values): - """ - Constructor for the class, generating an approximation to a function of - the form f(w,x,y,z) using interpolations over f(w,x,y_0,z_0) for a fixed - grid of y_0 and z_0 values. - - Parameters - ---------- - wxInterpolators : [[HARKinterpolator2D]] - A list of lists of 2D interpolations over the w and x variables. - The i,j-th element of wxInterpolators represents - f(w,x,y_values[i],z_values[j]). - y_values: numpy.array - An array of y values equal in length to wxInterpolators. - z_values: numpy.array - An array of z values equal in length to wxInterpolators[0]. - - Returns - ------- - new instance of BilinearInterpOnInterp2D - """ self.wxInterpolators = wxInterpolators self.y_list = y_values self.y_n = y_values.size @@ -3978,28 +3862,21 @@ class Curvilinear2DInterp(HARKinterpolator2D): A 2D interpolation method for curvilinear or "warped grid" interpolation, as in White (2015). Used for models with two endogenous states that are solved with the endogenous grid method. + + Parameters + ---------- + f_values: numpy.array + A 2D array of function values such that f_values[i,j] = + f(x_values[i,j],y_values[i,j]). + x_values: numpy.array + A 2D array of x values of the same size as f_values. + y_values: numpy.array + A 2D array of y values of the same size as f_values. """ distance_criteria = ["f_values", "x_values", "y_values"] def __init__(self, f_values, x_values, y_values): - """ - Constructor for 2D curvilinear interpolation for a function f(x,y) - - Parameters - ---------- - f_values: numpy.array - A 2D array of function values such that f_values[i,j] = - f(x_values[i,j],y_values[i,j]). - x_values: numpy.array - A 2D array of x values of the same size as f_values. - y_values: numpy.array - A 2D array of y values of the same size as f_values. - - Returns - ------- - new instance of Curvilinear2DInterp - """ self.f_values = f_values self.x_values = x_values self.y_values = y_values @@ -4448,26 +4325,19 @@ class ValueFuncCRRA(HARKobject): """ A class for representing a value function. The underlying interpolation is in the space of (state,u_inv(v)); this class "re-curves" to the value function. + + Parameters + ---------- + vFuncNvrs : function + A real function representing the value function composed with the + inverse utility function, defined on the state: u_inv(vFunc(state)) + CRRA : float + Coefficient of relative risk aversion. """ distance_criteria = ["func", "CRRA"] def __init__(self, vFuncNvrs, CRRA): - """ - Constructor for a new value function object. - - Parameters - ---------- - vFuncNvrs : function - A real function representing the value function composed with the - inverse utility function, defined on the state: u_inv(vFunc(state)) - CRRA : float - Coefficient of relative risk aversion. - - Returns - ------- - None - """ self.func = deepcopy(vFuncNvrs) self.CRRA = CRRA @@ -4494,29 +4364,22 @@ class MargValueFuncCRRA(HARKobject): """ A class for representing a marginal value function in models where the standard envelope condition of dvdm(state) = u'(c(state)) holds (with CRRA utility). + + Parameters + ---------- + cFunc : function. + Its first argument must be normalized market resources m. + A real function representing the marginal value function composed + with the inverse marginal utility function, defined on the state + variables: uP_inv(dvdmFunc(state)). Called cFunc because when standard + envelope condition applies, uP_inv(dvdm(state)) = cFunc(state). + CRRA : float + Coefficient of relative risk aversion. """ distance_criteria = ["cFunc", "CRRA"] def __init__(self, cFunc, CRRA): - """ - Constructor for a new marginal value function object. - - Parameters - ---------- - cFunc : function. - Its first argument must be normalized market resources m. - A real function representing the marginal value function composed - with the inverse marginal utility function, defined on the state - variables: uP_inv(dvdmFunc(state)). Called cFunc because when standard - envelope condition applies, uP_inv(dvdm(state)) = cFunc(state). - CRRA : float - Coefficient of relative risk aversion. - - Returns - ------- - None - """ self.cFunc = deepcopy(cFunc) self.CRRA = CRRA @@ -4578,29 +4441,22 @@ class MargMargValueFuncCRRA(HARKobject): """ A class for representing a marginal marginal value function in models where the standard envelope condition of dvdm = u'(c(state)) holds (with CRRA utility). + + Parameters + ---------- + cFunc : function. + Its first argument must be normalized market resources m. + A real function representing the marginal value function composed + with the inverse marginal utility function, defined on the state + variables: uP_inv(dvdmFunc(state)). Called cFunc because when standard + envelope condition applies, uP_inv(dvdm(state)) = cFunc(state). + CRRA : float + Coefficient of relative risk aversion. """ distance_criteria = ["cFunc", "CRRA"] def __init__(self, cFunc, CRRA): - """ - Constructor for a new marginal marginal value function object. - - Parameters - ---------- - cFunc : function. - Its first argument must be normalized market resources m. - A real function representing the marginal value function composed - with the inverse marginal utility function, defined on the state - variables: uP_inv(dvdmFunc(state)). Called cFunc because when standard - envelope condition applies, uP_inv(dvdm(state)) = cFunc(state). - CRRA : float - Coefficient of relative risk aversion. - - Returns - ------- - None - """ self.cFunc = deepcopy(cFunc) self.CRRA = CRRA