archimedes.interpolant¶

archimedes.interpolant(grid: list[ndarray], data: ndarray, method: str = 'linear', arg_names: str | list[str] | None = None, ret_name: str | None = None, name: str = 'interpolant') → Callable¶

Create a callable N-dimensional interpolant function.

Constructs an efficient interpolation function from grid data that can be evaluated at arbitrary points and embedded in Archimedes computational graphs.

Parameters:

grid (list of array_like) – List of N 1D arrays defining the grid points in each dimension. Each array must be strictly monotonic (increasing or decreasing).
data (array_like) – N-D array containing the function values at all grid points.
method (str, optional) – Interpolation method to use. Options are: - “linear”: Piecewise linear interpolation (default) - “bspline”: Cubic B-spline interpolation (smoother)
arg_names (list of str, optional) – Names for the input arguments to the interpolant function. Default is ["x_0", "x_1", ...].
ret_name (str, optional) – Name for the output of the interpolant function. Default is "f".
name (str, optional) – Name for the interpolant function itself. Default is "interpolant".

Returns:

A callable function that interpolates values at specified points. The function takes N arguments corresponding to each dimension and returns the interpolated value.

Return type:

callable

Notes

When to use this function:

To create smooth approximations of complex functions from tabular data
To incorporate lookup tables into optimization or simulation workflows
To evaluate experimental or simulation data at arbitrary points
When embedding interpolation within other Archimedes functions

Data organization: For a 2D example with grid arrays xgrid and ygrid, organize the data into a 2D data array Z where Z[i,j] = f(xgrid[i], ygrid[j]). Corresponding 2D grid arrays may be created using np.meshgrid(xgrid, ygrid, indexing='ij').

This function creates a CasADi interpolant internally, which can be used with both numeric and symbolic inputs. It supports gradient computation through automatic differentiation for both interpolation methods, but only with respect to the input arguments (not the data).

Limitations:

Evaluating outside the grid boundaries will return the nearest grid value
For multi-dimensional grids with N > 1, the interpolant expects N separate args

Examples

>>> import numpy as np
>>> import archimedes as arc
>>> import matplotlib.pyplot as plt
>>>
>>> # 1D interpolation example
>>> x = np.linspace(0, 10, 11)
>>> y = np.sin(x)
>>>
>>> # Create an interpolant
>>> sin_interp = arc.interpolant([x], y, method="bspline")
>>>
>>> # Evaluate at new points
>>> x_fine = np.linspace(0, 10, 101)
>>> y_interp = np.array([sin_interp(xi) for xi in x_fine])
>>> plt.figure()
>>> plt.plot(x_fine, y_interp)
>>> plt.plot(x, y, 'k.')
>>> plt.plot(x_fine, np.sin(x_fine), 'k--')
>>> plt.show()
>>>
>>> # 2D interpolation example
>>> xgrid = np.linspace(-5, 5, 11)
>>> ygrid = np.linspace(-4, 4, 9)
>>> X, Y = np.meshgrid(xgrid, ygrid, indexing='ij')
>>>
>>> # Create a 2D function to interpolate
>>> R = np.sqrt(X**2 + Y**2) + 1
>>> Z = np.sin(R) / R
>>>
>>> # Create the interpolant
>>> f = arc.interpolant(
>>>     [xgrid, ygrid],
>>>     Z,
>>>     method="bspline",
>>>     arg_names=["x", "y"],
>>>     ret_name="z"
>>> )
>>>
>>> # Use in optimization or with automatic differentiation
>>> df_dx = arc.grad(f, argnums=0)  # Gradient with respect to x
>>> print(df_dx(0.5, 1.0))
-0.19490596565158205
>>>
>>> # Combining with other Archimedes functions
>>> @arc.compile
>>> def combined_func(x, y):
>>>     interp_value = f(x, y)
>>>     return interp_value**2 + np.sin(x * y)