WallGo.interpolatableFunction

Class that can be use to evaluate and interpolate functions.

Classes

`EExtrapolationType`(value)	Enums for extrapolation.
`InterpolatableFunction`([...])	This is a totally-not-overengineered base class for defining optimized functions \(f(x)\) that, in addition to normal evaluation, support the following:

class EExtrapolationType(value)[source]: Enums for extrapolation. Default is NONE, no extrapolation at all.

class InterpolatableFunction(bUseAdaptiveInterpolation=True, initialInterpolationPointCount=1000, returnValueCount=1)[source]

This is a totally-not-overengineered base class for defining optimized functions \(f(x)\) that, in addition to normal evaluation, support the following:

Producing and using interpolation tables in favor of direct evaluation, where
applicable.
Automatic adaptive updating of the interpolation table.
Reading interpolation tables from a file.
Producing said file for some range of inputs.
Validating that what was read from a file makes sense, ie. matches the result
given by _evaluate().

WallGo uses this class for evaluating the free energy as function of the temperature. It can also be used for the thermal \(J_b, J_f\) integrals.

This also works for functions returning many numbers, ie. vector functions \(V(x) = [V1, V2, ...]\). In this case each component gets its own interpolation table.

Works with numpy array input and applying the function element-wise, but it is the user’s responsibility to ensure that the implementation of _functionImplementation() is compatible with this behavior. The logic is such that if x is an array and idx is a index-tuple for an element in x, then fx[idx] is the value of f(x) at x[idx]. Note that the shapes of fx and x will NOT match IF f(x) is vector valued.

Special care is needed if the function evaluation fails for some input x, eg. if the function is evaluated only on some interval. In this case it is the user’s responsibility to return np.nan from _functionImplementation() for these input values; this will mark these points as invalid and they will not be included in interpolations. Failure to return np.nan for bad input will likely break the interpolation.

Limitations.

If the initial interpolation is bad, then it will remain bad: no functionality to improve existing interpolations, only increase of the range is possible.
Currently makes sense only for functions of one variable. However, you CAN call this with numpy arrays of any shape (see above).
Does NOT support piecewise functions as interpolations would break for those.

Optional argument returnValueCount should be set by the user if using list-valued functions.

Parameters:

bUseAdaptiveInterpolation (bool, optional) – Whether or not to use adaptive interpolation. The default is True.
initialInterpolationPointCount (int, optional) – Initial number of points for the interpolation. The default is 1000.
returnValueCount (int, optional) – Number of outputs returned by the function. The default is 1.

derivative(x, order=1, bUseInterpolation=True, epsilon=1e-16, scale=1.0)[source]

Takes derivative of the function at points x. If bUseInterpolation=True, will compute derivatives from the interpolated function (if it exists). nth order derivative can be taken with order=n, however we only support interpolated derivative of order=1,2 for now. epsilon and scale are parameters for the helpers.derivative() routine.

Parameters:

x (list[float] or np.ndarray) – Points where the derivative will be evaluated.
order (int, optional) – Order of the derivative to take. The default is 1.
bUseInterpolation (bool, optional) – Whether or not to use interpolation to evaluate the function. The default is True.
epsilon (float, optional) – Relative accuracy at which the function is evaluated. The default is 1e-16.
scale (float, optional) – Scale at which the function changes by O(1). The default is 1.0.

Returns:

Value of the derivative at x.

Return type:

list[float | np.ndarray] or np.ndarray

disableAdaptiveInterpolation()[source]

Disables adaptive interpolation functionality.

Return type:: None

enableAdaptiveInterpolation()[source]

Enables adaptive interpolation functionality. Will clear internal work arrays.

Return type:: None

evaluate(x, bUseInterpolatedValues=True)[source]

Evaluate the function.

Parameters:

x (list[float] or np.ndarray) – Points where the function will be evaluated.
bUseInterpolatedValues (bool, optional) – Whether or not to use interpolation to evaluate the function. The default is True.

Returns:

Value of the function at x.

Return type:

list[float | np.ndarray] or np.ndarray

evaluateInterpolation(x)[source]

Evaluates our interpolated function at input x

Parameters:: x (list[float] | ndarray | float)
Return type:: ndarray

extendInterpolationTable(newMin, newMax, pointsMin, pointsMax)[source]

Extend our interpolation table. NB: This will reset internally accumulated data of adaptive interpolation.

Parameters:

newMin (float) – New minimal value at which the interpolation starts.
newMax (float) – New maximal value at which the interpolation starts.
pointsMin (int) – Minimal number of points to use.
pointsMax (int) – Maximal number of points to use.

Return type:

None

hasInterpolation()[source]

Returns true if we have an interpolation table.

Return type:: bool

interpolationRangeMax()[source]

Get upper limit of our current interpolation table.

Return type:: float

interpolationRangeMin()[source]

Get lower limit of our current interpolation table.

Return type:: float

newInterpolationTable(xMin, xMax, numberOfPoints)[source]

Creates a new interpolation table over given range. This will purge any existing interpolation information.

Parameters:

xMin (float) – Minimal interpolation point.
xMax (float) – Maximal interpolation point.
numberOfPoints (int) – Number of points to use in the interpolation.

Return type:

None

newInterpolationTableFromValues(x, fx, derivatives=None, splineDegree=3)[source]

Like initializeInterpolationTable but takes in precomputed function values ‘fx’

Parameters:

x (list[float] or np.ndarray) – Points where the function was evaluated.
fx (list[float | np.ndarray] or np.ndarray) – Value of the function at x.
derivatives (list[outputType] | None) – List containing the values of each derivative of the function at x. If None, computes the derivatives from the interpolated spline.
splineDegree (int)

Return type:

None

numPoints()[source]

How many input points in our interpolation table.

Return type:: int

readInterpolationTable(fileToRead)[source]

Reads precalculated values from a file and does cubic interpolation. Each line in the file must be of form x f(x). For vector valued functions: x f1(x) f2(x)

Parameters:: fileToRead (str) – Path of the file where the interpolation table is stored.
Return type:: None

scheduleForInterpolation(x, fx)[source]

Add x, f(x) pairs to our pending interpolation table update

Parameters:

x (list[float] or np.ndarray) – Points where the function was evaluated.
fx (list[float | np.ndarray] or np.ndarray) – Value of the function at x.

Return type:

None

setExtrapolationType(extrapolationTypeLower, extrapolationTypeUpper)[source]

Changes extrapolation behavior, default is NONE. See the enum class EExtrapolationType. NOTE: This will effectively prevent adaptive updates to the interpolation table. NOTE 2: Calling this function will force a rebuild of our interpolation table.

Parameters:

extrapolationTypeLower (EExtrapolationType) – Extrapolation type when below the interpolation range.
extrapolationTypeUpper (EExtrapolationType) – Extrapolation type when above the interpolation range.

Return type:

None

writeInterpolationTable(outputFileName)[source]

Write our interpolation table to file.

Parameters:: outputFileName (str) – Name of the file where the interpolation table will be written.
Return type:: None