HARK.ConsumptionSaving.ConsGenIncProcessModel¶

Classes to solve consumption-saving models with idiosyncratic shocks to income in which shocks are not necessarily fully transitory or fully permanent. Extends ConsIndShockModel by explicitly tracking persistent income as a state variable, and allows (log) persistent income to follow an AR1 process rather than random walk.

class HARK.ConsumptionSaving.ConsGenIncProcessModel.ConsGenIncProcessSolver(solution_next, IncomeDstn, LivPrb, DiscFac, CRRA, Rfree, pLvlNextFunc, BoroCnstArt, aXtraGrid, pLvlGrid, vFuncBool, CubicBool)¶

A class for solving one period problem of a consumer who experiences persistent and transitory shocks to his income. Unlike in ConsIndShock, consumers do not necessarily have the same predicted level of p next period as this period (after controlling for growth). Instead, they have a function that translates current persistent income into expected next period persistent income (subject to shocks).

addMPCandHumanWealth(solution)¶

Take a solution and add human wealth and the bounding MPCs to it.

Parameters:	solution (ConsumerSolution) – The solution to this period’s consumption-saving problem. Returns – ---------- – solution – The solution to this period’s consumption-saving problem, but now with human wealth and the bounding MPCs.

addvPPfunc(solution)¶

Adds the marginal marginal value function to an existing solution, so that the next solver can evaluate vPP and thus use cubic interpolation.

Parameters:	solution (ConsumerSolution) – The solution to this single period problem, which must include the consumption function.
Returns:	solution – The same solution passed as input, but with the marginal marginal value function for this period added as the attribute vPPfunc.
Return type:	ConsumerSolution

assignParameters(solution_next, IncomeDstn, LivPrb, DiscFac, CRRA, Rfree, pLvlNextFunc, BoroCnstArt, aXtraGrid, pLvlGrid, vFuncBool, CubicBool)¶

Assigns inputs as attributes of self for use by other methods

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:
Return type:	none

calcEndOfPrdvP()¶

Calculates end-of-period marginal value of assets at each state space point in aLvlNow x pLvlNow. Does so by taking a weighted sum of next period marginal values across income shocks (in preconstructed grids self.mLvlNext x self.pLvlNext).

Parameters:	None –
Returns:	EndOfPrdVP – A 2D array of end-of-period marginal value of assets.
Return type:	np.array

defBoroCnst(BoroCnstArt)¶

Defines the constrained portion of the consumption function as cFuncNowCnst, an attribute of self.

Parameters:	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.
Returns:
Return type:	None

getPointsForInterpolation(EndOfPrdvP, aLvlNow)¶

Finds endogenous interpolation points (c,m) for the consumption function.

Parameters:

EndOfPrdvP (np.array) – Array of end-of-period marginal values.
aLvlNow (np.array) – Array of end-of-period asset values that yield the marginal values in EndOfPrdvP.

Returns:

c_for_interpolation (np.array) – Consumption points for interpolation.
m_for_interpolation (np.array) – Corresponding market resource points for interpolation.

makeBasicSolution(EndOfPrdvP, aLvl, pLvl, interpolator)¶

Given end of period assets and end of period marginal value, construct the basic solution for this period.

Parameters:	EndOfPrdvP (np.array) – Array of end-of-period marginal values. aLvl (np.array) – Array of end-of-period asset values that yield the marginal values in EndOfPrdvP. pLvl (np.array) – Array of persistent income levels that yield the marginal values in EndOfPrdvP (corresponding pointwise to aLvl). interpolator (function) – A function that constructs and returns a consumption function.
Returns:	solution_now – The solution to this period’s consumption-saving problem, with a consumption function, marginal value function, and minimum m.
Return type:	ConsumerSolution

makeCubiccFunc(mLvl, pLvl, cLvl)¶

Makes a quasi-cubic spline interpolation of the unconstrained consumption function for this period. Function is cubic splines with respect to mLvl, but linear in pLvl.

Parameters:	mLvl (np.array) – Market resource points for interpolation. pLvl (np.array) – Persistent income level points for interpolation. cLvl (np.array) – Consumption points for interpolation.
Returns:	cFuncUnc – The unconstrained consumption function for this period.
Return type:	CubicInterp

makeEndOfPrdvFunc(EndOfPrdvP)¶

Construct the end-of-period value function for this period, storing it as an attribute of self for use by other methods.

Parameters:	EndOfPrdvP (np.array) – Array of end-of-period marginal value of assets corresponding to the asset values in self.aLvlNow x self.pLvlGrid.
Returns:
Return type:	none

makeLinearcFunc(mLvl, pLvl, cLvl)¶

Makes a quasi-bilinear interpolation to represent the (unconstrained) consumption function.

Parameters:	mLvl (np.array) – Market resource points for interpolation. pLvl (np.array) – Persistent income level points for interpolation. cLvl (np.array) – Consumption points for interpolation.
Returns:	cFuncUnc – The unconstrained consumption function for this period.
Return type:	LinearInterp

makevFunc(solution)¶

Creates the value function for this period, defined over market resources m and persistent income p. self must have the attribute EndOfPrdvFunc in order to execute.

Parameters:	solution (ConsumerSolution) – The solution to this single period problem, which must include the consumption function.
Returns:	vFuncNow – A representation of the value function for this period, defined over market resources m and persistent income p: v = vFuncNow(m,p).
Return type:	ValueFunc

makevPfunc(cFunc)¶

Constructs the marginal value function for this period.

Parameters:	cFunc (function) – Consumption function this period, defined over market resources and persistent income level.
Returns:	vPfunc – Marginal value (of market resources) function for this period.
Return type:	function

prepareToCalcEndOfPrdvP()¶

Prepare to calculate end-of-period marginal value by creating an array of market resources that the agent could have next period, considering the grid of end-of-period normalized assets, the grid of persistent income levels, and the distribution of shocks he might experience next period.

Parameters:	None –
Returns:	aLvlNow (np.array) – 2D array of end-of-period assets; also stored as attribute of self. pLvlNow (np.array) – 2D array of persistent income levels this period.

setAndUpdateValues(solution_next, IncomeDstn, LivPrb, DiscFac)¶

Unpacks some of the inputs (and calculates simple objects based on them), storing the results in self for use by other methods. These include: income shocks and probabilities, next period’s marginal value function (etc), the probability of getting the worst income shock next period, the patience factor, human wealth, and the bounding MPCs. Human wealth is stored as a function of persistent income.

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.
Returns:
Return type:	None

solve()¶

Solves a one period consumption saving problem with risky income, with persistent income explicitly tracked as a state variable.

Parameters:	None –
Returns:	solution – The solution to the one period problem, including a consumption function (defined over market resources and persistent income), a marginal value function, bounding MPCs, and human wealth as a func- tion of persistent income. Might also include a value function and marginal marginal value function, depending on options selected.
Return type:	ConsumerSolution

usePointsForInterpolation(cLvl, mLvl, pLvl, interpolator)¶

Constructs a basic solution for this period, including the consumption function and marginal value function.

Parameters:	cLvl (np.array) – Consumption points for interpolation. mLvl (np.array) – Corresponding market resource points for interpolation. pLvl (np.array) – Corresponding persistent income level points for interpolation. interpolator (function) – A function that constructs and returns a consumption function.
Returns:	solution_now – The solution to this period’s consumption-saving problem, with a consumption function, marginal value function, and minimum m.
Return type:	ConsumerSolution

class HARK.ConsumptionSaving.ConsGenIncProcessModel.GenIncProcessConsumerType(cycles=0, time_flow=True, **kwds)¶

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

getControls()¶

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

Parameters:	None –
Returns:
Return type:	None

getPostStates()¶

Calculates end-of-period assets for each consumer of this type. Identical to version in IndShockConsumerType but uses Lvl rather than Nrm variables.

Parameters:	None –
Returns:
Return type:	None

getStates()¶

Calculates updated values of normalized market resources and persistent income level for each agent. Uses pLvlNow, aLvlNow, PermShkNow, TranShkNow.

Parameters:	None –
Returns:
Return type:	None

installRetirementFunc()¶

Installs a special pLvlNextFunc representing retirement in the correct element of self.pLvlNextFunc. Draws on the attributes T_retire and pLvlNextFuncRet. If T_retire is zero or pLvlNextFuncRet does not exist, this method does nothing. Should only be called from within the method updatepLvlNextFunc, which ensures that time is flowing forward.

Parameters:	None –
Returns:
Return type:	None

simBirth(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 persistent 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”.
Returns:
Return type:	None

update()¶

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

Parameters:	None –
Returns:
Return type:	None

updateSolutionTerminal()¶

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

Parameters:	None –
Returns:
Return type:	None

updatepLvlGrid()¶

Update the grid of persistent income levels. Currently only works for infinite horizon models (cycles=0) and lifecycle models (cycles=1). Not clear what to do about cycles>1 because the distribution of persistent income will be different within a period depending on how many cycles have elapsed. This method uses a simulation approach to generate the pLvlGrid at each period of the cycle, drawing on the initial distribution of persistent income, the pLvlNextFuncs, and the attribute pLvlPctiles.

Parameters:	None –
Returns:
Return type:	None

updatepLvlNextFunc()¶

A dummy method that creates a trivial pLvlNextFunc attribute that has no persistent income dynamics. This method should be overwritten by subclasses in order to make (e.g.) an AR1 income process.

Parameters:	None –
Returns:
Return type:	None

class HARK.ConsumptionSaving.ConsGenIncProcessModel.IndShockExplicitPermIncConsumerType(cycles=0, time_flow=True, **kwds)¶

A consumer type with idiosyncratic shocks to permanent and transitory income. The 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. This agent type is identical to an IndShockConsumerType but for explicitly tracking pLvl as a state variable during solution. There is no real economic use for it.

updatepLvlNextFunc()¶

A method that creates the pLvlNextFunc attribute as a sequence of linear functions, indicating constant expected permanent income growth across permanent income levels. Draws on the attribute PermGroFac, and installs a special retirement function when it exists.

Parameters:	None –
Returns:
Return type:	None

class HARK.ConsumptionSaving.ConsGenIncProcessModel.MargMargValueFunc2D(cFunc, CRRA)¶: A class for representing a marginal marginal value function in models where the standard envelope condition of v’(m,p) = u’(c(m,p)) holds (with CRRA utility).

class HARK.ConsumptionSaving.ConsGenIncProcessModel.MargValueFunc2D(cFunc, CRRA)¶

A class for representing a marginal value function in models where the standard envelope condition of v’(m,p) = u’(c(m,p)) holds (with CRRA utility). This is copied from ConsAggShockModel, with the second state variable re- labeled as persistent income p.

derivativeX(m, p)¶

Evaluate the first derivative with respect to market resources of the marginal value function at given levels of market resources m and per- manent income p.

Parameters:	m (float or np.array) – Market resources whose value is to be calcuated. p (float or np.array) – Persistent income levels whose value is to be calculated.
Returns:	vPP – Marginal marginal value of market resources when beginning this period with market resources m and persistent income p; has same size as inputs m and p.
Return type:	float or np.array

class HARK.ConsumptionSaving.ConsGenIncProcessModel.PersistentShockConsumerType(cycles=0, time_flow=True, **kwds)¶

Type with idiosyncratic shocks to persistent (‘Prst’) and transitory income. The problem is defined by a sequence of income distributions, survival prob- abilities, and persistent income growth rates, as well as time invariant values 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.

updatepLvlNextFunc()¶

A method that creates the pLvlNextFunc attribute as a sequence of AR1-style functions. Draws on the attributes PermGroFac and PrstIncCorr. If cycles=0, the product of PermGroFac across all periods must be 1.0, otherwise this method is invalid.

Parameters:	None –
Returns:
Return type:	None

class HARK.ConsumptionSaving.ConsGenIncProcessModel.ValueFunc2D(vFuncNvrs, CRRA)¶: A class for representing a value function in a model where persistent income is explicitly included as a state variable. The underlying interpolation is in the space of (m,p) –> u_inv(v); this class “re-curves” to the value function.

class HARK.ConsumptionSaving.ConsGenIncProcessModel.pLvlFuncAR1(pLogMean, PermGroFac, Corr)¶: A class for representing AR1-style persistent income growth functions.

HARK.ConsumptionSaving.ConsGenIncProcessModel.solveConsGenIncProcess(solution_next, IncomeDstn, LivPrb, DiscFac, CRRA, Rfree, pLvlNextFunc, BoroCnstArt, aXtraGrid, pLvlGrid, vFuncBool, CubicBool)¶

Solves the one period problem of a consumer who experiences persistent and transitory shocks to his income. Unlike in ConsIndShock, consumers do not necessarily have expected persistent income growth that is constant with respect to their current level of pLvl. Instead, they have a function that translates current pLvl into expected next period pLvl (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. Currently ignored, with BoroCnstArt=0 used implicitly. 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:	solution – The solution to the one period problem, including a consumption function (defined over market resources and persistent income), a marginal value function, bounding MPCs, and normalized human wealth.
Return type:	ConsumerSolution