ConsIndShockModel#

Classes to solve canonical consumption-saving models with idiosyncratic shocks to income. All models here assume CRRA utility with geometric discounting, no bequest motive, and income shocks that are fully transitory or fully permanent.

It currently solves three types of models:

A very basic “perfect foresight” consumption-savings model with no uncertainty.
A consumption-savings model with risk over transitory and permanent income shocks.
The model described in (2), with an interest rate for debt that differs from the interest rate for savings.

See NARK econ-ark/HARK for information on variable naming conventions. See HARK documentation for mathematical descriptions of the models being solved.

class HARK.ConsumptionSaving.ConsIndShockModel.ConsumerSolution(cFunc=None, vFunc=None, vPfunc=None, vPPfunc=None, mNrmMin=None, hNrm=None, MPCmin=None, MPCmax=None)#

Bases: MetricObject

A class representing the solution of a single period of a consumption-saving problem. The solution must include a consumption function and marginal value function.

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.

append_solution(new_solution)#

Appends one solution to another to create a ConsumerSolution whose attributes are lists. Used in ConsMarkovModel, where we append solutions conditional on a particular value of a Markov state to each other in order to get the entire solution.

Parameters:: new_solution (ConsumerSolution) – The solution to a consumption-saving problem; each attribute is a list representing state-conditional values or functions.
Return type:: None

distance_criteria = ['vPfunc']#

class HARK.ConsumptionSaving.ConsIndShockModel.IndShockConsumerType(verbose=1, quiet=False, **kwds)#

Bases: PerfForesightConsumerType

A consumer type with idiosyncratic shocks to permanent and transitory income. His problem is defined by a sequence of income distributions, survival prob- 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.

calc_ergodic_dist(transition_matrix=None)#

Calculates the ergodic distribution across normalized market resources and permanent income as the eigenvector associated with the eigenvalue 1. The distribution is stored as attributes of self both as a vector and as a reshaped array with the ij’th element representing the probability of being at the i’th point on the mGrid and the j’th point on the pGrid.

Parameters:: transition_matrix (List) – list with one transition matrix whose ergordic distribution is to be solved
Return type:: None

calc_jacobian(shk_param, T)#

Calculates the Jacobians of aggregate consumption and aggregate assets. Parameters that can be shocked are LivPrb, PermShkStd,TranShkStd, DiscFac, UnempPrb, Rfree, IncUnemp, DiscFac .

Parameters:#

shk_param: string: name of variable to be shocked
T: int: dimension of Jacobian Matrix. Jacobian Matrix is a TxT square Matrix

returns:

CJAC (numpy.array) – TxT Jacobian Matrix of Aggregate Consumption with respect to shk_param
AJAC (numpy.array) – TxT Jacobian Matrix of Aggregate Assets with respect to shk_param

calc_limiting_values()#

Compute various scalar values that are relevant to characterizing the solution to an infinite horizon problem. This method should only be called when T_cycle=1 and cycles=0, otherwise the values generated are meaningless. This method adds the following values to this instance in the dictionary attribute called bilt.

APFac : Absolute Patience Factor GPFacRaw : Growth Patience Factor GPFacMod : Risk-Modified Growth Patience Factor GPFacLiv : Mortality-Adjusted Growth Patience Factor GPFacLivMod : Modigliani Mortality-Adjusted Growth Patience Factor GPFacSdl : Szeidl Growth Patience Factor FHWFac : Finite Human Wealth Factor RPFac : Return Patience Factor WRPFac : Weak Return Patience Factor PFVAFac : Perfect Foresight Value of Autarky Factor VAFac : Value of Autarky Factor cNrmPDV : Present Discounted Value of Autarky Consumption MPCmin : Limiting minimum MPC as market resources go to infinity MPCmax : Limiting maximum MPC as market resources approach minimum level hNrm : Human wealth divided by permanent income. ELogPermShk : Expected log permanent income shock WorstPrb : Probability of worst income shock realization Delta_mNrm_ZeroFunc : Linear locus where expected change in market resource ratio is zero BalGroFunc : Linear consumption function where the level of market resources grows at the same rate as permanent income

Return type:: None

calc_transition_matrix(shk_dstn=None)#

Calculates how the distribution of agents across market resources transitions from one period to the next. If finite horizon problem, then calculates a list of transition matrices, consumption and asset policy grids for each period of the problem. The transition matrix/matrices and consumption and asset policy grid(s) are stored as attributes of self.

Parameters:: shk_dstn (list) – list of income shock distributions. Each Income Shock Distribution should be a DiscreteDistribution Object (see Distribution.py)
Return type:: None

check_FVAC(verbose=None)#: Evaluate and report on the Finite Value of Autarky condition in the presence of income risk.

check_GICHrm(verbose=None)#: Evaluate and report on the Harmenberg variation of the Growth Impatience Condition.

check_GICLiv(verbose=None)#: Evaluate and report on the Mortality-Adjusted Growth Impatience Condition.

check_GICMod(verbose=None)#: Evaluate and report on the Risk-Modified Growth Impatience Condition.

check_GICSdl(verbose=None)#: Evaluate and report on the Szeidl variation of the Growth Impatience Condition.

check_WRIC(verbose=None)#: Evaluate and report on the Weak Return Impatience Condition.

check_conditions(verbose=None)#

This method checks whether the instance’s type satisfies various conditions. When combinations of these conditions are satisfied, the solution to the problem exhibits different characteristics. (For an exposition of the conditions, see https://econ-ark.github.io/BufferStockTheory/)

Parameters:: verbose (boolean) – Specifies different levels of verbosity of feedback. When False, it only reports whether the instance’s type fails to satisfy a particular condition. When True, it reports all results, i.e. the factor values for all conditions.
Return type:: None

compute_steady_state()#

construct_lognormal_income_process_unemployment()#

Generates a list of discrete approximations to the income process for each life period, from end of life to beginning of life. Permanent shocks are mean one lognormally distributed with standard deviation PermShkStd[t] during the working life, and degenerate at 1 in the retirement period. Transitory shocks are mean one lognormally distributed with a point mass at IncUnemp with probability UnempPrb while working; they are mean one with a point mass at IncUnempRet with probability UnempPrbRet. Retirement occurs after t=T_retire periods of working.

Note 1: All time in this function runs forward, from t=0 to t=T

Note 2: All parameters are passed as attributes of the input parameters.

Parameters (passed as attributes of the input parameters)#

PermShkStd[float]: List of standard deviations in log permanent income uncertainty during the agent’s life.
PermShkCountint: The number of approximation points to be used in the discrete approxima- tion to the permanent income shock distribution.
TranShkStd[float]: List of standard deviations in log transitory income uncertainty during the agent’s life.
TranShkCountint: The number of approximation points to be used in the discrete approxima- tion to the permanent income shock distribution.
UnempPrbfloat or [float]: The probability of becoming unemployed during the working period.
UnempPrbRetfloat or None: The probability of not receiving typical retirement income when retired.
T_retireint: The index value for the final working period in the agent’s life. If T_retire <= 0 then there is no retirement.
IncUnempfloat or [float]: Transitory income received when unemployed.
IncUnempRetfloat or None: Transitory income received while “unemployed” when retired.
T_cycleint: Total number of non-terminal periods in the consumer’s sequence of periods.

returns:

IncShkDstn ([distribution.Distribution]) – A list with T_cycle elements, each of which is a discrete approximation to the income process in a period.
PermShkDstn ([[distribution.Distributiony]]) – A list with T_cycle elements, each of which a discrete approximation to the permanent income shocks.
TranShkDstn ([[distribution.Distribution]]) – A list with T_cycle elements, each of which a discrete approximation to the transitory income shocks.

define_distribution_grid(dist_mGrid=None, dist_pGrid=None, m_density=0, num_pointsM=None, timestonest=None, num_pointsP=55, max_p_fac=30.0)#

Defines the grid on which the distribution is defined. Stores the grid of market resources and permanent income as attributes of self. Grid for normalized market resources and permanent income may be prespecified as dist_mGrid and dist_pGrid, respectively. If not then default grid is computed based off given parameters.

Parameters:

dist_mGrid (np.array) – Prespecified grid for distribution over normalized market resources
dist_pGrid (np.array) – Prespecified grid for distribution over permanent income.
m_density (float) – Density of normalized market resources grid. Default value is mdensity = 0. Only affects grid of market resources if dist_mGrid=None.
num_pointsM (float) – Number of gridpoints for market resources grid.
num_pointsP (float) – Number of gridpoints for permanent income. This grid will be exponentiated by the function make_grid_exp_mult.
max_p_fac (float) – Factor that scales the maximum value of permanent income grid. Larger values increases the maximum value of permanent income grid.

Return type:

None

describe_parameters()#

Generate a string describing the primitive model parameters that will be used to calculating limiting values and factors.

Parameters:: None
Returns:: param_desc – Description of primitive parameters.
Return type:: str

get_shocks()#

Gets permanent and transitory income shocks for this period. Samples from IncShkDstn for each period in the cycle.

Parameters:: NewbornTransShk (boolean, optional) – Whether Newborns have transitory shock. The default is False.
Return type:: None

make_euler_error_func(mMax=100, approx_inc_dstn=True)#

Creates a “normalized Euler error” function for this instance, mapping from market resources to “consumption error per dollar of consumption.” Stores result in attribute eulerErrorFunc as an interpolated function. Has option to use approximate income distribution stored in self.IncShkDstn or to use a (temporary) very dense approximation.

Only works on (one period) infinite horizon models at this time, will be generalized later.

Parameters:

mMax (float) – Maximum normalized market resources for the Euler error function.
approx_inc_dstn (Boolean) – Indicator for whether to use the approximate discrete income distri- bution stored in self.IncShkDstn[0], or to use a very accurate discrete approximation instead. When True, uses approximation in IncShkDstn; when False, makes and uses a very dense approximation.

Return type:

None

Notes

This method is not used by any other code in the library. Rather, it is here for expository and benchmarking purposes.

pre_solve()#: Method that is run automatically just before solution by backward iteration. Solves the (trivial) terminal period and does a quick check on the borrowing constraint and MaxKinks attribute (only relevant in constrained, infinite horizon problems).

reset_rng()#

Reset the RNG behavior of this type. This method is called automatically by initialize_sim(), ensuring that each simulation run uses the same sequence of random shocks; this is necessary for structural estimation to work. This method extends AgentType.reset_rng() to also reset elements of IncShkDstn.

Parameters:: None
Return type:: None

shock_vars_ = ['PermShk', 'TranShk']#

time_inv_ = ['CRRA', 'DiscFac', 'BoroCnstArt', 'BoroCnstArt', 'vFuncBool', 'CubicBool']#

update()#

Update the income process, the assets grid, and the terminal solution.

Parameters:: None
Return type:: None

update_assets_grid()#

Updates this agent’s end-of-period assets grid by constructing a multi- exponentially spaced grid of aXtra values.

Parameters:: none
Return type:: none

update_income_process()#

Updates this agent’s income process based on his own attributes.

Parameters:

none
Returns
-----------
none

class HARK.ConsumptionSaving.ConsIndShockModel.KinkedRconsumerType(**kwds)#

Bases: IndShockConsumerType

A consumer type that faces idiosyncratic shocks to income and has a different interest factor on saving vs borrowing. Extends IndShockConsumerType, with very small changes. Solver for this class is currently only compatible with linear spline interpolation.

Same parameters as AgentType.

calc_bounding_values()#

Calculate human wealth plus minimum and maximum MPC in an infinite horizon model with only one period repeated indefinitely. Store results as attributes of self. Human wealth is the present discounted value of expected future income after receiving income this period, ignoring mort- ality. The maximum MPC is the limit of the MPC as m –> mNrmMin. The minimum MPC is the limit of the MPC as m –> infty. This version deals with the different interest rates on borrowing vs saving.

Parameters:: None
Return type:: None

check_conditions(verbose)#

This empty method overwrites the version inherited from its parent class, IndShockConsumerType. The condition checks are not appropriate when Rfree has multiple values.

Parameters:: None
Return type:: None

get_Rfree()#

Returns an array of size self.AgentCount with self.Rboro or self.Rsave in each entry, based on whether self.aNrmNow >< 0.

Parameters:: None
Returns:: RfreeNow – Array of size self.AgentCount with risk free interest rate for each agent.
Return type:: np.array

make_euler_error_func(mMax=100, approx_inc_dstn=True)#

SHOULD BE INHERITED FROM ConsIndShockModel

Parameters:

mMax (float) – Maximum normalized market resources for the Euler error function.
approx_inc_dstn (Boolean) – Indicator for whether to use the approximate discrete income distri- bution stored in self.IncShkDstn[0], or to use a very accurate discrete approximation instead. When True, uses approximation in IncShkDstn; when False, makes and uses a very dense approximation.

Return type:

None

Notes

This method is not used by any other code in the library. Rather, it is here for expository and benchmarking purposes.

time_inv_ = ['CRRA', 'DiscFac', 'BoroCnstArt', 'BoroCnstArt', 'vFuncBool', 'CubicBool', 'Rboro', 'Rsave']#

class HARK.ConsumptionSaving.ConsIndShockModel.PerfForesightConsumerType(verbose=1, quiet=False, **kwds)#

Bases: AgentType

A perfect foresight consumer type who has no uncertainty other than mortality. 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.

cFunc_terminal_ = <HARK.interpolation.LinearInterp object>#

calc_limiting_values()#

Compute various scalar values that are relevant to characterizing the solution to an infinite horizon problem. This method should only be called when T_cycle=1 and cycles=0, otherwise the values generated are meaningless. This method adds the following values to the instance in the dictionary attribute called bilt.

APFac : Absolute Patience Factor GPFacRaw : Growth Patience Factor FHWFac : Finite Human Wealth Factor RPFac : Return Patience Factor PFVAFac : Perfect Foresight Value of Autarky Factor cNrmPDV : Present Discounted Value of Autarky Consumption MPCmin : Limiting minimum MPC as market resources go to infinity MPCmax : Limiting maximum MPC as market resources approach minimum level. hNrm : Human wealth divided by permanent income. Delta_mNrm_ZeroFunc : Linear consumption function where expected change in market resource ratio is zero BalGroFunc : Linear consumption function where the level of market resources grows at the same rate as permanent income

Return type:: None

calc_stable_points()#

If the problem is one that satisfies the conditions required for target ratios of different variables to permanent income to exist, and has been solved to within the self-defined tolerance, this method calculates the target values of market resources.

Parameters:: None
Return type:: None

check_AIC(verbose=None)#: Evaluate and report on the Absolute Impatience Condition.

check_FHWC(verbose=None)#: Evaluate and report on the Finite Human Wealth Condition.

check_FVAC(verbose=None)#: Evaluate and report on the Finite Value of Autarky Condition under perfect foresight.

check_GICRaw(verbose=None)#: Evaluate and report on the Growth Impatience Condition for the Perfect Foresight model.

check_RIC(verbose=None)#: Evaluate and report on the Return Impatience Condition.

check_conditions(verbose=None)#

This method checks whether the instance’s type satisfies the Absolute Impatience Condition (AIC), the Return Impatience Condition (RIC), the Finite Human Wealth Condition (FHWC), the perfect foresight model’s Growth Impatience Condition (GICRaw) and Perfect Foresight Finite Value of Autarky Condition (FVACPF). Depending on the configuration of parameter values, somecombination of these conditions must be satisfied in order for the problem to have a nondegenerate solution. To check which conditions are required, in the verbose mode a reference to the relevant theoretical literature is made.

Parameters:: verbose (boolean) – Specifies different levels of verbosity of feedback. When False, it only reports whether the instance’s type fails to satisfy a particular condition. When True, it reports all results, i.e. the factor values for all conditions.
Return type:: None

check_restrictions()#: A method to check that various restrictions are met for the model class.

describe_parameters()#

Make a string describing this instance’s parameter values, including their representation in code and symbolically.

Returns:: param_desc – Description of parameters as a unicode string.
Return type:: str

get_Rfree()#

Returns an array of size self.AgentCount with self.Rfree in every entry.

Parameters:: None
Returns:: RfreeNow – Array of size self.AgentCount with risk free interest rate for each agent.
Return type:: np.array

get_controls()#

Calculates consumption for each consumer of this type using the consumption functions.

Parameters:: None
Return type:: None

get_poststates()#

Calculates end-of-period assets for each consumer of this type.

Parameters:: None
Return type:: None

get_shocks()#

Finds permanent and transitory income “shocks” for each agent this period. As this is a perfect foresight model, there are no stochastic shocks: PermShkNow = PermGroFac for each agent (according to their t_cycle) and TranShkNow = 1.0 for all agents.

Parameters:: None
Return type:: None

initialize_sim()#

Prepares this AgentType for a new simulation. Resets the internal random number generator, makes initial states for all agents (using sim_birth), clears histories of tracked variables.

Parameters:: None
Return type:: None

log_condition_result(name, result, message, verbose)#

Records the result of one condition check in the attribute condition_report of the bilt dictionary, and in the message log.

Parameters:

name (string or None) – Name for the condition; if None, no test result is added to conditions.
result (bool) – An indicator for whether the condition was passed.
message (str) – The messages to record about the condition check.
verbose (bool) – Indicator for whether verbose messages should be included in the report.

post_solve()#

Method that is run automatically at the end of a call to solve. Here, it simply calls calc_stable_points() if appropriate: an infinite horizon problem with a single repeated period in its cycle.

Parameters:: None
Return type:: None

pre_solve()#: Method that is run automatically just before solution by backward iteration. Solves the (trivial) terminal period and does a quick check on the borrowing constraint and MaxKinks attribute (only relevant in constrained, infinite horizon problems).

shock_vars_ = []#

sim_birth(which_agents)#

Makes new consumers for the given indices. Initialized variables include aNrm and pLvl, as well as time variables t_age and t_cycle. Normalized assets and permanent income levels are drawn from lognormal distributions given by aNrmInitMean and aNrmInitStd (etc).

Parameters:: which_agents (np.array(Bool)) – Boolean array of size self.AgentCount indicating which agents should be “born”.
Return type:: None

sim_death()#

Determines which agents die this period and must be replaced. Uses the sequence in LivPrb to determine survival probabilities for each agent.

Parameters:: None
Returns:: which_agents – Boolean array of size AgentCount indicating which agents die.
Return type:: np.array(bool)

solution_terminal_ = <HARK.ConsumptionSaving.ConsIndShockModel.ConsumerSolution object>#

state_vars = ['pLvl', 'PlvlAgg', 'bNrm', 'mNrm', 'aNrm', 'aLvl']#

time_inv_ = ['CRRA', 'DiscFac', 'MaxKinks', 'BoroCnstArt']#

time_vary_ = ['LivPrb', 'PermGroFac']#

transition()#

Parameters:

None
[Eventually
spec (to match dolo)
exogenous_prev
endogenous_prev
controls
exogenous
parameters]

Returns:

endogenous_state – Tuple with new values of the endogenous states

Return type:

()

unpack_cFunc()#

DEPRECATED: Use solution.unpack(‘cFunc’) instead. “Unpacks” the consumption functions into their own field for easier access. After the model has been solved, the consumption functions reside in the attribute cFunc of each element of ConsumerType.solution. This method creates a (time varying) attribute cFunc that contains a list of consumption functions. :param none:

Return type:: none

update_Rfree()#

Determines whether Rfree is time-varying or fixed.

Parameters:: None
Return type:: None

update_solution_terminal()#

Update the terminal period solution. This method should be run when a new AgentType is created or when CRRA changes.

Parameters:: none
Return type:: none

vFunc_terminal_ = <HARK.interpolation.LinearInterp object>#