Interpolation#

Custom interpolation methods for representing approximations to functions. It also includes wrapper classes to enforce standard methods across classes. Each interpolation class must have a distance() method that compares itself to another instance; this is used in HARK.core’s solve() method to check for solution convergence. The interpolator classes currently in this module inherit their distance method from MetricObject.

class HARK.interpolation.HARKinterpolator1D#

Bases: MetricObject

A wrapper class for 1D interpolation methods in HARK.

distance_criteria = []#

derivative(x)#

Evaluates the derivative of the interpolated function at the given input.

Parameters:: x (np.array or float) – Real values to be evaluated in the interpolated function.
Returns:: dydx – The interpolated function’s first derivative evaluated at x: dydx = f’(x), with the same shape as x.
Return type:: np.array or float

eval_with_derivative(x)#

Evaluates the interpolated function and its derivative at the given input.

Parameters:

x (np.array or float) – Real values to be evaluated in the interpolated function.

Returns:

y (np.array or float) – The interpolated function evaluated at x: y = f(x), with the same shape as x.
dydx (np.array or float) – The interpolated function’s first derivative evaluated at x: dydx = f’(x), with the same shape as x.

class HARK.interpolation.HARKinterpolator2D#

Bases: MetricObject

A wrapper class for 2D interpolation methods in HARK.

distance_criteria = []#

derivativeX(x, y)#

Evaluates the partial derivative of interpolated function with respect to x (the first argument) at the given input.

Parameters:

x (np.array or float) – Real values to be evaluated in the interpolated function.
y (np.array or float) – Real values to be evaluated in the interpolated function; must be the same size as x.

Returns:

dfdx – The derivative of the interpolated function with respect to x, eval- uated at x,y: dfdx = f_x(x,y), with the same shape as x and y.

Return type:

np.array or float

derivativeY(x, y)#

Evaluates the partial derivative of interpolated function with respect to y (the second argument) at the given input.

Parameters:

x (np.array or float) – Real values to be evaluated in the interpolated function.
y (np.array or float) – Real values to be evaluated in the interpolated function; must be the same size as x.

Returns:

dfdy – The derivative of the interpolated function with respect to y, eval- uated at x,y: dfdx = f_y(x,y), with the same shape as x and y.

Return type:

np.array or float

class HARK.interpolation.HARKinterpolator3D#

Bases: MetricObject

A wrapper class for 3D interpolation methods in HARK.

distance_criteria = []#

derivativeX(x, y, z)#

Evaluates the partial derivative of the interpolated function with respect to x (the first argument) at the given input.

Parameters:

x (np.array or float) – Real values to be evaluated in the interpolated function.
y (np.array or float) – Real values to be evaluated in the interpolated function; must be the same size as x.
z (np.array or float) – Real values to be evaluated in the interpolated function; must be the same size as x.

Returns:

dfdx – The derivative with respect to x of the interpolated function evaluated at x,y,z: dfdx = f_x(x,y,z), with the same shape as x, y, and z.

Return type:

np.array or float

derivativeY(x, y, z)#

Evaluates the partial derivative of the interpolated function with respect to y (the second argument) at the given input.

Parameters:

x (np.array or float) – Real values to be evaluated in the interpolated function.
y (np.array or float) – Real values to be evaluated in the interpolated function; must be the same size as x.
z (np.array or float) – Real values to be evaluated in the interpolated function; must be the same size as x.

Returns:

dfdy – The derivative with respect to y of the interpolated function evaluated at x,y,z: dfdy = f_y(x,y,z), with the same shape as x, y, and z.

Return type:

np.array or float

derivativeZ(x, y, z)#

Evaluates the partial derivative of the interpolated function with respect to z (the third argument) at the given input.

Parameters:

x (np.array or float) – Real values to be evaluated in the interpolated function.
y (np.array or float) – Real values to be evaluated in the interpolated function; must be the same size as x.
z (np.array or float) – Real values to be evaluated in the interpolated function; must be the same size as x.

Returns:

dfdz – The derivative with respect to z of the interpolated function evaluated at x,y,z: dfdz = f_z(x,y,z), with the same shape as x, y, and z.

Return type:

np.array or float

class HARK.interpolation.HARKinterpolator4D#

Bases: MetricObject

A wrapper class for 4D interpolation methods in HARK.

distance_criteria = []#

derivativeW(w, x, y, z)#

Evaluates the partial derivative with respect to w (the first argument) of the interpolated function at the given input.

Parameters:

w (np.array or float) – Real values to be evaluated in the interpolated function.
x (np.array or float) – Real values to be evaluated in the interpolated function; must be the same size as w.
y (np.array or float) – Real values to be evaluated in the interpolated function; must be the same size as w.
z (np.array or float) – Real values to be evaluated in the interpolated function; must be the same size as w.

Returns:

dfdw – The derivative with respect to w of the interpolated function eval- uated at w,x,y,z: dfdw = f_w(w,x,y,z), with the same shape as inputs.

Return type:

np.array or float

derivativeX(w, x, y, z)#

Evaluates the partial derivative with respect to x (the second argument) of the interpolated function at the given input.

Parameters:

w (np.array or float) – Real values to be evaluated in the interpolated function.
x (np.array or float) – Real values to be evaluated in the interpolated function; must be the same size as w.
y (np.array or float) – Real values to be evaluated in the interpolated function; must be the same size as w.
z (np.array or float) – Real values to be evaluated in the interpolated function; must be the same size as w.

Returns:

dfdx – The derivative with respect to x of the interpolated function eval- uated at w,x,y,z: dfdx = f_x(w,x,y,z), with the same shape as inputs.

Return type:

np.array or float

derivativeY(w, x, y, z)#

Evaluates the partial derivative with respect to y (the third argument) of the interpolated function at the given input.

Parameters:

w (np.array or float) – Real values to be evaluated in the interpolated function.
x (np.array or float) – Real values to be evaluated in the interpolated function; must be the same size as w.
y (np.array or float) – Real values to be evaluated in the interpolated function; must be the same size as w.
z (np.array or float) – Real values to be evaluated in the interpolated function; must be the same size as w.

Returns:

dfdy – The derivative with respect to y of the interpolated function eval- uated at w,x,y,z: dfdy = f_y(w,x,y,z), with the same shape as inputs.

Return type:

np.array or float

derivativeZ(w, x, y, z)#

Evaluates the partial derivative with respect to z (the fourth argument) of the interpolated function at the given input.

Parameters:

w (np.array or float) – Real values to be evaluated in the interpolated function.
x (np.array or float) – Real values to be evaluated in the interpolated function; must be the same size as w.
y (np.array or float) – Real values to be evaluated in the interpolated function; must be the same size as w.
z (np.array or float) – Real values to be evaluated in the interpolated function; must be the same size as w.

Returns:

dfdz – The derivative with respect to z of the interpolated function eval- uated at w,x,y,z: dfdz = f_z(w,x,y,z), with the same shape as inputs.

Return type:

np.array or float

class HARK.interpolation.IdentityFunction(i_dim=0, n_dims=1)#

Bases: MetricObject

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']#

derivative(*args)#: Returns the derivative of the function with respect to the first dimension.

derivativeX(*args)#: Returns the derivative of the function with respect to the X dimension. This is the first input whenever n_dims < 4 and the second input otherwise.

derivativeY(*args)#: Returns the derivative of the function with respect to the Y dimension. This is the second input whenever n_dims < 4 and the third input otherwise.

derivativeZ(*args)#: Returns the derivative of the function with respect to the Z dimension. This is the third input whenever n_dims < 4 and the fourth input otherwise.

derivativeW(*args)#: Returns the derivative of the function with respect to the W dimension. This should only exist when n_dims >= 4.

class HARK.interpolation.ConstantFunction(value)#

Bases: MetricObject

A class for representing trivial functions that return the same real output for any input. This is convenient for models where an object might be a (non-trivial) function, but in some variations that object is just a constant number. Rather than needing to make a (Bi/Tri/Quad)- LinearInterpolation with trivial state grids and the same f_value in every entry, ConstantFunction 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']#

derivative(*args)#: Evaluate the derivative of the function. The first input must exist and should be an array. Returns an array of identical shape to args[0] (if it exists). This is an array of zeros.

derivativeX(*args)#: Evaluate the derivative of the function. The first input must exist and should be an array. Returns an array of identical shape to args[0] (if it exists). This is an array of zeros.

derivativeY(*args)#: Evaluate the derivative of the function. The first input must exist and should be an array. Returns an array of identical shape to args[0] (if it exists). This is an array of zeros.

derivativeZ(*args)#: Evaluate the derivative of the function. The first input must exist and should be an array. Returns an array of identical shape to args[0] (if it exists). This is an array of zeros.

derivativeW(*args)#: Evaluate the derivative of the function. The first input must exist and should be an array. Returns an array of identical shape to args[0] (if it exists). This is an array of zeros.

derivativeXX(*args)#: Evaluate the derivative of the function. The first input must exist and should be an array. Returns an array of identical shape to args[0] (if it exists). This is an array of zeros.

class HARK.interpolation.LinearInterp(x_list, y_list, intercept_limit=None, slope_limit=None, lower_extrap=False)#

Bases: 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']#

class HARK.interpolation.CubicInterp(x_list, y_list, dydx_list, intercept_limit=None, slope_limit=None, lower_extrap=False)#

Bases: HARKinterpolator1D

An interpolating function using piecewise cubic splines. Matches level and 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']#

class HARK.interpolation.CubicHermiteInterp(x_list, y_list, dydx_list, intercept_limit=None, slope_limit=None, lower_extrap=False)#

Bases: HARKinterpolator1D

An interpolating function using piecewise cubic splines. Matches level and 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']#

out_of_bounds(x)#

class HARK.interpolation.BilinearInterp(f_values, x_list, y_list, xSearchFunc=None, ySearchFunc=None)#

Bases: 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']#

class HARK.interpolation.TrilinearInterp(f_values, x_list, y_list, z_list, xSearchFunc=None, ySearchFunc=None, zSearchFunc=None)#

Bases: 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']#

class HARK.interpolation.QuadlinearInterp(f_values, w_list, x_list, y_list, z_list, wSearchFunc=None, xSearchFunc=None, ySearchFunc=None, zSearchFunc=None)#

Bases: 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']#

class HARK.interpolation.LowerEnvelope(*functions, nan_bool=True)#

Bases: 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']#

class HARK.interpolation.UpperEnvelope(*functions, nan_bool=True)#

Bases: 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']#

class HARK.interpolation.LowerEnvelope2D(*functions, nan_bool=True)#

Bases: 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']#

class HARK.interpolation.LowerEnvelope3D(*functions, nan_bool=True)#

Bases: 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']#

class HARK.interpolation.VariableLowerBoundFunc2D(func, lowerBound)#

Bases: MetricObject

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']#

derivativeX(x, y)#

Evaluate the first derivative with respect to x of the function at given state space points.

Parameters:

x (np.array) – First input values.
y (np.array) – Second input values; should be of same shape as x.

Returns:

dfdx_out – First derivative of function with respect to the first input, evaluated at (x,y), of same shape as inputs.

Return type:

np.array

derivativeY(x, y)#

Evaluate the first derivative with respect to y of the function at given state space points.

Parameters:

x (np.array) – First input values.
y (np.array) – Second input values; should be of same shape as x.

Returns:

dfdy_out – First derivative of function with respect to the second input, evaluated at (x,y), of same shape as inputs.

Return type:

np.array

class HARK.interpolation.VariableLowerBoundFunc3D(func, lowerBound)#

Bases: MetricObject

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']#

derivativeX(x, y, z)#

Evaluate the first derivative with respect to x of the function at given state space points.

Parameters:

x (np.array) – First input values.
y (np.array) – Second input values; should be of same shape as x.
z (np.array) – Third input values; should be of same shape as x.

Returns:

dfdx_out – First derivative of function with respect to the first input, evaluated at (x,y,z), of same shape as inputs.

Return type:

np.array

derivativeY(x, y, z)#

Evaluate the first derivative with respect to y of the function at given state space points.

Parameters:

x (np.array) – First input values.
y (np.array) – Second input values; should be of same shape as x.
z (np.array) – Third input values; should be of same shape as x.

Returns:

dfdy_out – First derivative of function with respect to the second input, evaluated at (x,y,z), of same shape as inputs.

Return type:

np.array

derivativeZ(x, y, z)#

Evaluate the first derivative with respect to z of the function at given state space points.

Parameters:

x (np.array) – First input values.
y (np.array) – Second input values; should be of same shape as x.
z (np.array) – Third input values; should be of same shape as x.

Returns:

dfdz_out – First derivative of function with respect to the third input, evaluated at (x,y,z), of same shape as inputs.

Return type:

np.array

class HARK.interpolation.LinearInterpOnInterp1D(xInterpolators, y_values)#

Bases: 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']#

class HARK.interpolation.BilinearInterpOnInterp1D(xInterpolators, y_values, z_values)#

Bases: 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']#

class HARK.interpolation.TrilinearInterpOnInterp1D(wInterpolators, x_values, y_values, z_values)#

Bases: 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']#

class HARK.interpolation.LinearInterpOnInterp2D(xyInterpolators, z_values)#

Bases: HARKinterpolator3D

A 3D interpolation method that linearly interpolates between “layers” of arbitrary 2D interpolations. Useful for models with two endogenous state 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']#

class HARK.interpolation.BilinearInterpOnInterp2D(wxInterpolators, y_values, z_values)#

Bases: HARKinterpolator4D

A 4D interpolation method that bilinearly interpolates among “layers” of arbitrary 2D interpolations. Useful for models with two endogenous state 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']#

class HARK.interpolation.Curvilinear2DInterp(f_values, x_values, y_values)#

Bases: 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']#

update_polarity()#

Fills in the polarity attribute of the interpolation, determining whether the “plus” (True) or “minus” (False) solution of the system of equations should be used for each sector. Needs to be called in __init__.

Parameters:: none
Return type:: none

find_sector(x, y)#

Finds the quadrilateral “sector” for each (x,y) point in the input. Only called as a subroutine of _evaluate().

Parameters:

x (np.array) – Values whose sector should be found.
y (np.array) – Values whose sector should be found. Should be same size as x.

Returns:

x_pos (np.array) – Sector x-coordinates for each point of the input, of the same size.
y_pos (np.array) – Sector y-coordinates for each point of the input, of the same size.

find_coords(x, y, x_pos, y_pos)#

Calculates the relative coordinates (alpha,beta) for each point (x,y), given the sectors (x_pos,y_pos) in which they reside. Only called as a subroutine of __call__().

Parameters:

x (np.array) – Values whose sector should be found.
y (np.array) – Values whose sector should be found. Should be same size as x.
x_pos (np.array) – Sector x-coordinates for each point in (x,y), of the same size.
y_pos (np.array) – Sector y-coordinates for each point in (x,y), of the same size.

Returns:

alpha (np.array) – Relative “horizontal” position of the input in their respective sectors.
beta (np.array) – Relative “vertical” position of the input in their respective sectors.

class HARK.interpolation.DiscreteInterp(index_interp, discrete_vals)#

Bases: MetricObject

An interpolator for variables that can only take a discrete set of values.

If the function we wish to interpolate, f(args) can take on the list of values discrete_vals, this class expects an interpolator for the index of f’s value in discrete_vals. E.g., if f(a,b,c) = discrete_vals[5], then index_interp(a,b,c) = 5.

Parameters:

index_interp (HARKInterpolator) – An interpolator giving an approximation to the index of the value in discrete_vals that corresponds to a given set of arguments.
discrete_vals (numpy.array) – A 1D array containing the values in the range of the discrete function to be interpolated.

distance_criteria = ['index_interp']#

HARK.interpolation.calc_log_sum_choice_probs(Vals, sigma)#

Returns the final optimal value and choice probabilities given the choice specific value functions Vals. Probabilities are degenerate if sigma == 0.0. :param Vals: A numpy.array that holds choice specific values at common grid points. :type Vals: [numpy.array] :param sigma: A number that controls the variance of the taste shocks :type sigma: float

Returns:

V ([numpy.array]) – A numpy.array that holds the integrated value function.
P ([numpy.array]) – A numpy.array that holds the discrete choice probabilities

HARK.interpolation.calc_choice_probs(Vals, sigma)#

Returns the choice probabilities given the choice specific value functions Vals. Probabilities are degenerate if sigma == 0.0. :param Vals: A numpy.array that holds choice specific values at common grid points. :type Vals: [numpy.array] :param sigma: A number that controls the variance of the taste shocks :type sigma: float

Returns:: Probs – A numpy.array that holds the discrete choice probabilities
Return type:: [numpy.array]

HARK.interpolation.calc_log_sum(Vals, sigma)#

Returns the optimal value given the choice specific value functions Vals. :param Vals: A numpy.array that holds choice specific values at common grid points. :type Vals: [numpy.array] :param sigma: A number that controls the variance of the taste shocks :type sigma: float

Returns:: V – A numpy.array that holds the integrated value function.
Return type:: [numpy.array]

class HARK.interpolation.ValueFuncCRRA(vFuncNvrs, CRRA)#

Bases: MetricObject

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']#

gradient(*args)#

class HARK.interpolation.MargValueFuncCRRA(cFunc, CRRA)#

Bases: MetricObject

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']#

derivativeX(*cFuncArgs)#

Evaluate the derivative of the marginal value function with respect to market resources at given state; this is the marginal marginal value function.

Parameters:: cFuncArgs (floats or np.arrays) – State variables.
Returns:: vPP – Marginal marginal lifetime value of beginning this period with state cFuncArgs; has same size as inputs.
Return type:: float or np.array

class HARK.interpolation.MargMargValueFuncCRRA(cFunc, CRRA)#

Bases: MetricObject

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']#

HARK.interpolation.main()#