Rewards#

HARK.rewards.CRRAutility(c, rho)#

Evaluates constant relative risk aversion (CRRA) utility of consumption c given risk aversion parameter rho.

Parameters:

  • c (float) – Consumption value

  • rho (float) – Risk aversion

Returns:

  • (unnamed) (float) – Utility

  • Tests

  • —–

  • Test a value which should pass

  • >>> c, CRRA = 1.0, 2.0 # Set two values at once with Python syntax

  • >>> CRRAutility(c=c, rho=CRRA)

  • -1.0

HARK.rewards.CRRAutilityP(c, rho)#

Evaluates constant relative risk aversion (CRRA) marginal utility of consumption c given risk aversion parameter rho.

Parameters:

  • c (float) – Consumption value

  • rho (float) – Risk aversion

Returns:

(unnamed) – Marginal utility

Return type:

float

HARK.rewards.CRRAutilityPP(c, rho)#

Evaluates constant relative risk aversion (CRRA) marginal marginal utility of consumption c given risk aversion parameter rho.

Parameters:

  • c (float) – Consumption value

  • rho (float) – Risk aversion

Returns:

(unnamed) – Marginal marginal utility

Return type:

float

HARK.rewards.CRRAutilityPPP(c, rho)#

Evaluates constant relative risk aversion (CRRA) marginal marginal marginal utility of consumption c given risk aversion parameter rho.

Parameters:

  • c (float) – Consumption value

  • rho (float) – Risk aversion

Returns:

(unnamed) – Marginal marginal marginal utility

Return type:

float

HARK.rewards.CRRAutilityPPPP(c, rho)#

Evaluates constant relative risk aversion (CRRA) marginal marginal marginal marginal utility of consumption c given risk aversion parameter rho.

Parameters:

  • c (float) – Consumption value

  • rho (float) – Risk aversion

Returns:

(unnamed) – Marginal marginal marginal marginal utility

Return type:

float

HARK.rewards.CRRAutility_inv(u, rho)#

Evaluates the inverse of the CRRA utility function (with risk aversion para- meter rho) at a given utility level u.

Parameters:

  • u (float) – Utility value

  • rho (float) – Risk aversion

Returns:

(unnamed) – Consumption corresponding to given utility value

Return type:

float

HARK.rewards.CRRAutilityP_inv(uP, rho)#

Evaluates the inverse of the CRRA marginal utility function (with risk aversion parameter rho) at a given marginal utility level uP.

Parameters:

  • uP (float) – Marginal utility value

  • rho (float) – Risk aversion

Returns:

(unnamed) – Consumption corresponding to given marginal utility value.

Return type:

float

HARK.rewards.CRRAutility_invP(u, rho)#

Evaluates the derivative of the inverse of the CRRA utility function (with risk aversion parameter rho) at a given utility level u.

Parameters:

  • u (float) – Utility value

  • rho (float) – Risk aversion

Returns:

(unnamed) – Marginal consumption corresponding to given utility value

Return type:

float

HARK.rewards.CRRAutilityP_invP(uP, rho)#

Evaluates the derivative of the inverse of the CRRA marginal utility function (with risk aversion parameter rho) at a given marginal utility level uP.

Parameters:

  • uP (float) – Marginal utility value

  • rho (float) – Risk aversion

Returns:

(unnamed) – Consumption corresponding to given marginal utility value

Return type:

float

HARK.rewards.StoneGearyCRRAutility(c, rho, shifter, factor=1.0)#

Evaluates Stone-Geary version of a constant relative risk aversion (CRRA) utility of consumption c with given risk aversion parameter rho and Stone-Geary intercept parameter shifter

Parameters:

  • c (float) – Consumption value

  • rho (float) – Relative risk aversion

  • shifter (float) – Intercept in Stone-Geary utility

Returns:

  • (unnamed) (float) – Utility

  • Tests

  • —–

  • Test a value which should pass

  • >>> c, CRRA, stone_geary = 1.0, 2.0, 0.0

  • >>> StoneGearyCRRAutility(c=c, rho=CRRA, shifter=stone_geary)

  • -1.0

HARK.rewards.StoneGearyCRRAutilityP(c, rho, shifter, factor=1.0)#

Marginal utility of Stone-Geary version of a constant relative risk aversion (CRRA) utility of consumption c with a given risk aversion parameter rho and Stone-Geary intercept parameter shifter

Parameters:

  • c (float) – Consumption value

  • rho (float) – Relative risk aversion

  • shifter (float) – Intercept in Stone-Geary utility

Returns:

(unnamed) – marginal utility

Return type:

float

HARK.rewards.StoneGearyCRRAutilityPP(c, rho, shifter, factor=1.0)#

Marginal marginal utility of Stone-Geary version of a CRRA utilty function with risk aversion parameter rho and Stone-Geary intercept parameter shifter

Parameters:

  • c (float) – Consumption value

  • rho (float) – Relative risk aversion

  • shifter (float) – Intercept in Stone-Geary utility

Returns:

(unnamed) – marginal utility

Return type:

float

HARK.rewards.StoneGearyCRRAutility_inv(u, rho, shifter, factor=1.0)#
HARK.rewards.StoneGearyCRRAutilityP_inv(uP, rho, shifter, factor=1.0)#
HARK.rewards.StoneGearyCRRAutility_invP(u, rho, shifter, factor=1.0)#
HARK.rewards.StoneGearyCRRAutilityP_invP(uP, rho, shifter, factor=1.0)#
HARK.rewards.CARAutility(c, alpha)#

Evaluates constant absolute risk aversion (CARA) utility of consumption c given risk aversion parameter alpha.

Parameters:

  • c (float) – Consumption value

  • alpha (float) – Risk aversion

Returns:

(unnamed) – Utility

Return type:

float

HARK.rewards.CARAutilityP(c, alpha)#

Evaluates constant absolute risk aversion (CARA) marginal utility of consumption c given risk aversion parameter alpha.

Parameters:

  • c (float) – Consumption value

  • alpha (float) – Risk aversion

Returns:

(unnamed) – Marginal utility

Return type:

float

HARK.rewards.CARAutilityPP(c, alpha)#

Evaluates constant absolute risk aversion (CARA) marginal marginal utility of consumption c given risk aversion parameter alpha.

Parameters:

  • c (float) – Consumption value

  • alpha (float) – Risk aversion

Returns:

(unnamed) – Marginal marginal utility

Return type:

float

HARK.rewards.CARAutilityPPP(c, alpha)#

Evaluates constant absolute risk aversion (CARA) marginal marginal marginal utility of consumption c given risk aversion parameter alpha.

Parameters:

  • c (float) – Consumption value

  • alpha (float) – Risk aversion

Returns:

(unnamed) – Marginal marginal marginal utility

Return type:

float

HARK.rewards.CARAutility_inv(u, alpha)#

Evaluates inverse of constant absolute risk aversion (CARA) utility function at utility level u given risk aversion parameter alpha.

Parameters:

  • u (float) – Utility value

  • alpha (float) – Risk aversion

Returns:

(unnamed) – Consumption value corresponding to u

Return type:

float

HARK.rewards.CARAutilityP_inv(u, alpha)#

Evaluates the inverse of constant absolute risk aversion (CARA) marginal utility function at marginal utility uP given risk aversion parameter alpha.

Parameters:

  • u (float) – Utility value

  • alpha (float) – Risk aversion

Returns:

(unnamed) – Consumption value corresponding to uP

Return type:

float

HARK.rewards.CARAutility_invP(u, alpha)#

Evaluates the derivative of inverse of constant absolute risk aversion (CARA) utility function at utility level u given risk aversion parameter alpha.

Parameters:

  • u (float) – Utility value

  • alpha (float) – Risk aversion

Returns:

(unnamed) – Marginal onsumption value corresponding to u

Return type:

float

HARK.rewards.cobb_douglas(x, zeta, factor)#

Evaluates Cobb Douglas utility at quantities of goods consumed x given elasticity parameters zeta and efficiency parameter factor.

Parameters:

  • x (np.ndarray) – Quantities of goods consumed. First axis must index goods.

  • zeta (np.ndarray) – Elasticity parameters for each good. Must be consistent with x.

  • factor (float) – Multiplicative efficiency parameter. (e.g. TFP in production function)

Returns:

(unnamed) – Utility

Return type:

np.ndarray

HARK.rewards.cobb_douglas_p(x, zeta, factor, arg=0)#

Evaluates the marginal utility of consumption indexed by arg good at quantities of goods consumed x given elasticity parameters zeta and efficiency parameter factor.

Parameters:

  • x (np.ndarray) – Quantities of goods consumed. First axis must index goods.

  • zeta (np.ndarray) – Elasticity parameters for each good. Must be consistent with x.

  • factor (float) – Multiplicative efficiency parameter.

  • arg (int) – Index of good to evaluate marginal utility.

Returns:

(unnamed) – Utility

Return type:

np.ndarray

HARK.rewards.cobb_douglas_pp(x, zeta, factor, args=(0, 1))#

Evaluates the marginal marginal utility of consumption indexed by args at quantities of goods consumed x given elasticity parameters zeta and efficiency parameter factor.

Parameters:

  • x (np.ndarray) – Quantities of goods consumed. First axis must index goods.

  • zeta (np.ndarray) – Elasticity parameters for each good. Must be consistent with x.

  • factor (float) – Multiplicative efficiency parameter.

  • args (tuple(int)) – Indexes of goods to evaluate marginal utility. args[0] is the index of the first derivative taken, and args[1] is the index of the second derivative taken.

Returns:

(unnamed) – Utility

Return type:

np.ndarray

HARK.rewards.cobb_douglas_pn(x, zeta, factor, args=())#

Evaluates the nth marginal utility of consumption indexed by args at quantities of goods consumed x given elasticity parameters zeta and efficiency parameter factor.

Parameters:

  • x (np.ndarray) – Quantities of goods consumed. First axis must index goods.

  • zeta (np.ndarray) – Elasticity parameters for each good. Must be consistent with x.

  • factor (float) – Multiplicative efficiency parameter.

  • args (tuple(int)) – Indexes of goods to evaluate marginal utility. args[0] is the index of the first derivative taken, and args[1] is the index of the second derivative taken. This function works by recursively taking derivatives, so args can be of any length.

Returns:

(unnamed) – Utility

Return type:

np.ndarray

HARK.rewards.const_elast_subs(x, zeta, subs, factor, power)#

Evaluates Constant Elasticity of Substitution utility at quantities of goods consumed x given parameters alpha, ‘subs’, ‘factor’, and ‘power’.

Parameters:

  • x (np.ndarray) – Quantities of goods consumed. First axis must index goods.

  • zeta (Sequence[float]) – Share parameter for each good. Must be consistent with x.

  • subs (float) – Substitution parameter.

  • factor (float) – Factor productivity parameter. (e.g. TFP in production function)

  • power (float) – degree of homogeneity of the utility function

Returns:

CES utility.

Return type:

np.ndarray

HARK.rewards.const_elast_subs_p(x, zeta, subs, factor, power, arg=0)#

Evaluates the marginal utility of consumption indexed by arg good at quantities of goods consumed x given parameters alpha, ‘subs’, ‘factor’, and ‘power’.

Parameters:

  • x (np.ndarray) – Quantities of goods consumed. First axis must index goods.

  • zeta (Sequence[float]) – Share parameter for each good. Must be consistent with x.

  • subs (float) – Substitution parameter.

  • factor (float) – Factor productivity parameter. (e.g. TFP in production function)

  • power (float) – degree of homogeneity of the utility function

Returns:

CES marginal utility.

Return type:

np.ndarray

class HARK.rewards.UtilityFunction(eval_func, der_func=None, inv_func=None)#

Bases: MetricObject

distance_criteria = ['eval_func']#
derivative(*args, **kwargs)#
inverse(*args, **kwargs)#
der(*args, **kwargs)#
inv(*args, **kwargs)#
class HARK.rewards.UtilityFuncCRRA(CRRA)#

Bases: UtilityFunction

A class for representing a CRRA utility function.

Parameters:

CRRA (float) – The coefficient of constant relative risk aversion.

distance_criteria = ['CRRA']#
derivative(c, order=1)#

The derivative of the utility function at a given level of consumption c.

Parameters:

  • c (float or np.ndarray) – Consumption level(s).

  • order (int, optional) – Order of derivative. For example, order == 1 returns the first derivative of utility of consumption, and so on. By default 1.

Returns:

Derivative of CRRA utility evaluated at given consumption level(s).

Return type:

float or np.ndarray

Raises:

ValueError – Derivative of order higher than 4 is not supported.

inverse(u, order=(0, 0))#

The inverse of the utility function at a given level of utility u.

Parameters:

  • u (float or np.ndarray) – Utility level(s).

  • order (tuple, optional) – Order of derivatives. For example, order == (1,1) represents the first derivative of utility, inverted, and then differentiated once. For a simple mnemonic, order refers to the number of P`s in the function `CRRAutility[#1]_inv[#2]. By default (0, 0), which is just the inverse of utility.

Returns:

Inverse of CRRA utility evaluated at given utility level(s).

Return type:

float or np.ndarray

Raises:

ValueError – Higher order derivatives are not supported.

derinv(u, order=(1, 0))#

Short alias for inverse with default order = (1,0). See self.inverse.

class HARK.rewards.UtilityFuncStoneGeary(CRRA, factor=1.0, shifter=0.0)#

Bases: UtilityFuncCRRA

derivative(c, order=1)#

The derivative of the utility function at a given level of consumption c.

Parameters:

  • c (float or np.ndarray) – Consumption level(s).

  • order (int, optional) – Order of derivative. For example, order == 1 returns the first derivative of utility of consumption, and so on. By default 1.

Returns:

Derivative of CRRA utility evaluated at given consumption level(s).

Return type:

float or np.ndarray

Raises:

ValueError – Derivative of order higher than 4 is not supported.

inverse(u, order=(0, 0))#

The inverse of the utility function at a given level of utility u.

Parameters:

  • u (float or np.ndarray) – Utility level(s).

  • order (tuple, optional) – Order of derivatives. For example, order == (1,1) represents the first derivative of utility, inverted, and then differentiated once. For a simple mnemonic, order refers to the number of P`s in the function `CRRAutility[#1]_inv[#2]. By default (0, 0), which is just the inverse of utility.

Returns:

Inverse of CRRA utility evaluated at given utility level(s).

Return type:

float or np.ndarray

Raises:

ValueError – Higher order derivatives are not supported.

class HARK.rewards.UtilityFuncCobbDouglas(EOS, factor=1.0)#

Bases: UtilityFunction

A class for representing a Cobb-Douglas utility function.

TODO: Add inverse methods.

Parameters:

  • EOS (float) – The coefficient for elasticity of substitution.

  • factor (float) – Factor productivity parameter. (e.g. TFP in production function)

distance_criteria = ['EOS', 'factor']#
derivative(x, args=())#
class HARK.rewards.UtilityFuncCobbDouglasCRRA(EOS, factor, CRRA)#

Bases: UtilityFuncCobbDouglas

A class for representing a Cobb-Douglas aggregated CRRA utility function.

TODO: Add derivative and inverse methods.

Parameters:

  • EOS (float) – The coefficient for elasticity of substitution.

  • factor (float) – Factor productivity parameter. (e.g. TFP in production function)

  • CRRA (float) – Coefficient of relative risk aversion.

distance_criteria = ['EOS', 'factor', 'CRRA']#
class HARK.rewards.UtilityFuncConstElastSubs(shares, subs, homogeneity=1.0, factor=1.0)#

Bases: UtilityFunction

A class for representing a constant elasticity of substitution utility function.

TODO: Add derivative and inverse methods.

Parameters:

  • shares (Sequence[float]) – Share parameter for each good. Must be consistent with x.

  • subs (float) – Substitution parameter.

  • factor (float) – Factor productivity parameter. (e.g. TFP in production function)

  • homogeneity (float) – degree of homogeneity of the utility function

distance_criteria = ['shares', 'subs', 'factor', 'homogeneity']#
derivative(x, arg=0)#