ListInterpolation

Status: Stable

documented, exercised by the test suite and/or worked examples, with no known limitations recorded.

Description

ListInterpolation[array]

constructs an InterpolatingFunction interpolating the values in array, taken to lie on a regular grid at integer positions 1, 2, ... in each direction. array may be nested to any depth; the nesting depth is the number of dimensions.

ListInterpolation[array, {{xmin, xmax}, {ymin, ymax}, ...}]

places the grid lines equally spaced across the given interval in each direction (one {min, max} pair per dimension).

ListInterpolation[array, {{x1, x2, ...}, ...}]

uses explicit lists of grid-line positions in each direction.

ListInterpolation[array, ..., InterpolationOrder -> n]

sets the piecewise-polynomial degree (default 3; 0 constant, 1 linear); Method -> "Spline" | "Hermite" selects the method and PeriodicInterpolation -> True builds a periodic interpolant.

Notes

A fast path for List, packed, and NDArray value tensors; works at machine or arbitrary (MPFR) precision, matching the data.

Examples (9)

Every input below was run against the current Mathilda build and its output recorded.

Basic examples (4)

In[1]:= f = ListInterpolation[{1, 2, 3, 5, 8, 5}]
Out[1]= InterpolatingFunction[{{1, 6}}, <>]

In[2]:= f[2.5]
Out[2]= 2.4375

In[3]:= ListInterpolation[{1, 2, 3, 5, 8, 5}, {{0, 1}}][0.5]
Out[3]= 3.875

In[4]:= ListInterpolation[{{1, 2}, {3, 4}}][1.5, 1.5]
Out[4]= 2.5

Applications (5)

Values on the integer grid 1, 2, 3, 4

In[5]:= ListInterpolation[{1, 4, 9, 16}]
Out[5]= InterpolatingFunction[{{1, 4}}, <>]

Evaluate the interpolant between grid points

In[6]:= ListInterpolation[{1, 4, 9, 16}][2.5]
Out[6]= 6.25

Place the grid equally spaced on [0, 3]

In[7]:= ListInterpolation[{1, 4, 9, 16}, {{0, 3}}]
Out[7]= InterpolatingFunction[{{0, 3}}, <>]

Piecewise-linear: halfway between 4 and 9

In[8]:= ListInterpolation[{1, 4, 9, 16}, InterpolationOrder -> 1][2.5]
Out[8]= 6.5

A 2-D array interpolates in both directions

In[9]:= ListInterpolation[{{1, 2}, {3, 4}}][1.5, 1.5]
Out[9]= 2.5

Algorithm

interp.c

InterpolatingFunction --- piecewise-polynomial interpolation of tabulated data on a regular (tensor-product) grid, plus the Interpolation[] builder. Modelled on Mathematica's InterpolatingFunction object.

  InterpolatingFunction[domain, table]
  InterpolatingFunction[domain, table, ders]
  InterpolatingFunction[domain, table, ders, orders]
  InterpolatingFunction[domain, table, ders, orders, method]

    domain = {{x1min, x1max}, ...}   -- one interval per dimension; the
             number of intervals m is the dimensionality.
    table  = {{coord, val}, ...}                     -- value-only data, or
             {{coord, val, grad, hess, ...}, ...}     -- derivative-supplied.
             coord is a scalar (1-D value-only) or an {x1,...,xm} list.
             grad = D[f,{vars,1}] (length-m vector), hess = D[f,{vars,2}]
             (m x m matrix), etc.
    ders   = {d1, ..., dm}   -- (optional) derivative-of-interpolant orders.
    orders = {o1, ..., om}   -- (optional) interpolation order per dimension.
    method = "Spline" | "Hermite"   -- (optional) interpolation method.

Methods (all evaluate the ders-th mixed derivative so D[ifun[..],..] composes):

  default  : sliding-window Newton divided-difference (order min(3,n-1) or the
             requested InterpolationOrder), per dimension, tensor product.
  "Spline" : natural cubic spline (C2; second derivative 0 at the ends),
             tensor product over the full grid.
  "Hermite": tensor-product piecewise cubic Hermite with node slopes estimated
             by 3-point finite differences.
  supplied : derivative-annotated data is interpolated by tensor-product
             Hermite of per-dimension order k = max(K,1) where K is the highest
             supplied derivative order.  Mixed partials that are not supplied
             are filled by central finite differences across the grid.

Precision: machine (double) by default; if the data/argument carry MPFR arbitrary precision the MPFR kernels (interp_mpfr.c) are used instead and an EXPR_MPFR is returned.

Builtin ownership: interp_apply / the Interpolation builtin return a fresh Expr* (or NULL to stay unevaluated); inputs are borrowed.

Performance

Against other systems, from the benchmark suite (same input, results cross-checked for agreement):

case	Mathilda	Wolfram	Python
Interpolation evaluate, 20000 points	18.9 s	18.1 s	0.073 s
Interpolation over 10^5 array	1.26 s	4.57 s	4.44 s
Interpolation build, 2000 knots	0.013 s	0.761 s	0.092 s
Interpolation order 1 (linear) build	--	0.764 s	0.014 s
ListInterpolation 2-D 60x60	--	0.823 s	1.02 s

Implementation notes

Algorithm. builtin_listinterpolation is the value-only companion to Interpolation: it interpolates a rectangular array of values laid out on a regular grid and returns an InterpolatingFunction. It reads the array's rectangular shape along a representative spine (listinterp_shape, nesting depth = dimensionality), synthesises the abscissae for each axis (listinterp_axis — plain integer positions 1..n by default, n equally-spaced points from a {xmin, xmax} interval, or an explicit list of positions), stitches the coordinates and values into the {{coord, val}, ...} table that Interpolation consumes, and hands it to the shared builtin_interpolation_impl. All numerics, MPFR handling, options, and the vectorised InterpolatingFunction[...] object are therefore shared verbatim — this is purely a front-end turning "values on a grid" into "value at abscissa".

Options pass straight through: InterpolationOrder -> n sets the piecewise-polynomial degree (default 3; 0 constant, 1 linear), Method -> "Spline" | "Hermite" picks the scheme, and PeriodicInterpolation -> True builds a periodic interpolant. List, packed, and NDArray value tensors all feed the same path, at machine or arbitrary (MPFR) precision matching the data.

Data structures. A shape[] vector (capped at LISTINTERP_MAXDIM = 16 dimensions) and per-axis abscissa Expr arrays — exact endpoint Exprs copied so the object's domain prints exactly, interior nodes machine reals — feeding the InterpolatingFunction representation the shared engine builds.

Complexity / limits. Dominated by the underlying Interpolation build (per axis, piecewise fits across the grid). The array must be rectangular (enforced node-by-node by listinterp_emit), non-empty on every axis, and at most 16 dimensions; a domain spec must give one {min, max} pair (or position list) per dimension.

Attributes: Protected.

References

See also: InterpolatingFunction, Interpolation, NDArray, List, Rational

• C. de Boor, A Practical Guide to Splines, rev. ed. (Springer, 2001) — piecewise-polynomial interpolation on a grid.
• Source: src/interp.c
• Specification: docs/spec/builtins/functional-programming.md
• Tests: tests/test_interp.c

Notes & additional examples

Notes

ListInterpolation[array] builds an InterpolatingFunction from an array of values taken to lie on a regular grid at integer positions 1, 2, ... in each direction — the value-only companion to Interpolation, which takes {abscissa, value} pairs. The nesting depth of array is the number of dimensions. Call the returned object like a function to sample it.

A second argument places the grid: {{xmin, xmax}, ...} spaces it equally over an interval per dimension, or explicit position lists give the grid lines directly. InterpolationOrder -> n sets the degree (default 3, so a longer run of points is a cubic fit; 1 is piecewise-linear), and Method and PeriodicInterpolation select the scheme.