HARK.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 HARKobject.

class HARK.interpolation.BilinearInterp(f_values, x_list, y_list, xSearchFunc=None, ySearchFunc=None)¶: Bilinear full (or tensor) grid interpolation of a function f(x,y).

class HARK.interpolation.BilinearInterpOnInterp1D(xInterpolators, y_values, z_values)¶: A 3D interpolator that bilinearly interpolates among a list of lists of 1D interpolators.

class HARK.interpolation.BilinearInterpOnInterp2D(wxInterpolators, y_values, z_values)¶: 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.

class HARK.interpolation.ConstantFunction(value)¶

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.

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.

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.

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.

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.

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.

class HARK.interpolation.CubicInterp(x_list, y_list, dydx_list, intercept_limit=None, slope_limit=None, lower_extrap=False)¶: 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.)

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

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.

findCoords(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.

findSector(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.

updatePolarity()¶

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

class HARK.interpolation.HARKinterpolator1D¶

A wrapper class for 1D interpolation methods in HARK.

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¶

A wrapper class for 2D interpolation methods in HARK.

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¶

A wrapper class for 3D interpolation methods in HARK.

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¶

A wrapper class for 4D interpolation methods in HARK.

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)¶

A fairly trivial interpolator that simply returns one of its arguments. Useful for avoiding numeric error in extreme cases.

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

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

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.

class HARK.interpolation.LinearInterp(x_list, y_list, intercept_limit=None, slope_limit=None, lower_extrap=False)¶: A “from scratch” 1D linear interpolation class. Allows for linear or decay extrapolation (approaching a limiting linear function from below).

class HARK.interpolation.LinearInterpOnInterp1D(xInterpolators, y_values)¶: A 2D interpolator that linearly interpolates among a list of 1D interpolators.

class HARK.interpolation.LinearInterpOnInterp2D(xyInterpolators, z_values)¶: 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.

class HARK.interpolation.LowerEnvelope(*functions)¶: 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.

class HARK.interpolation.LowerEnvelope2D(*functions)¶: 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.

class HARK.interpolation.LowerEnvelope3D(*functions)¶: 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.

class HARK.interpolation.QuadlinearInterp(f_values, w_list, x_list, y_list, z_list, wSearchFunc=None, xSearchFunc=None, ySearchFunc=None, zSearchFunc=None)¶: Quadlinear full (or tensor) grid interpolation of a function f(w,x,y,z).

class HARK.interpolation.TrilinearInterp(f_values, x_list, y_list, z_list, xSearchFunc=None, ySearchFunc=None, zSearchFunc=None)¶: Trilinear full (or tensor) grid interpolation of a function f(x,y,z).

class HARK.interpolation.TrilinearInterpOnInterp1D(wInterpolators, x_values, y_values, z_values)¶: A 4D interpolator that trilinearly interpolates among a list of lists of 1D interpolators.

class HARK.interpolation.UpperEnvelope(*functions)¶: 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.

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

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.

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)¶

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.

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

HARK.interpolation.calcChoiceProbs(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.calcLogSum(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]

HARK.interpolation.calcLogSumChoiceProbs(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