Quickstart

Docs | Repo | Rust Library (github) | Rust Docs (docs.rs)

This library provides serializable N-dimensional interpolators backed by compute-heavy code written in Rust.

These methods perform zero allocation when evaluated (except, optionally, for the output). Because of this, they have minimal per-call overhead, and are particularly effective when examining small numbers of observation points. See the performance page for detailed benchmarks.

Features

Feature → ↓ Interpolant Method	Regular Grid	Rectilinear Grid	Json Serialization
Linear	✅	✅	✅
Cubic	✅	✅	✅

The methods provided here, while more limited in scope than scipy's, are * significantly faster for higher dimensions (1-3 orders of magnitude under most conditions) * use almost no RAM (and perform no heap allocations at all) * produce significantly improved floating-point error (by 1-2 orders of magnitude) * are json-serializable using Pydantic * can also be used easily in web and embedded applications via the Rust library * are permissively licensed

ND throughput 1 obs

See here for more info about quality-of-fit, throughput, and memory usage.

Installation

pip install interpn

Example: Available Methods

import interpn
import numpy as np

# Build grid
x = np.linspace(0.0, 10.0, 5)
y = np.linspace(20.0, 30.0, 4)
grids = [x, y]

xgrid, ygrid = np.meshgrid(x, y, indexing="ij")
zgrid = (xgrid + 2.0 * ygrid)  # Values at grid points

# Grid inputs for true regular grid
dims = [x.size, y.size]
starts = np.array([x[0], y[0]])
steps = np.array([x[1] - x[0], y[1] - y[0]])

# Initialize different interpolators
# Call like `linear_regular.eval([xs, ys])`
linear_regular = interpn.MultilinearRegular.new(dims, starts, steps, zgrid)
cubic_regular = interpn.MulticubicRegular.new(dims, starts, steps, zgrid)
linear_rectilinear = interpn.MultilinearRectilinear.new(grids, zgrid)
cubic_rectilinear = interpn.MulticubicRectilinear.new(grids, zgrid)

Example: Multilinear Interpolation on a Regular Grid

import interpn
import numpy as np

# Build grid
x = np.linspace(0.0, 10.0, 5)
y = np.linspace(20.0, 30.0, 4)

xgrid, ygrid = np.meshgrid(x, y, indexing="ij")
zgrid = (xgrid + 2.0 * ygrid)  # Values at grid points

# Grid inputs for true regular grid
dims = [x.size, y.size]
starts = np.array([x[0], y[0]])
steps = np.array([x[1] - x[0], y[1] - y[0]])

# Observation points pointed back at the grid
obs = [xgrid.flatten(), ygrid.flatten()]

# Initialize
interpolator = interpn.MultilinearRegular.new(dims, starts, steps, zgrid)

# Interpolate
out = interpolator.eval(obs)

# Check result
assert np.allclose(out, zgrid.flatten(), rtol=1e-13)

# Serialize and deserialize
roundtrip_interpolator = interpn.MultilinearRegular.model_validate_json(
    interpolator.model_dump_json()
)
out2 = roundtrip_interpolator.eval(obs)

# Check result from roundtrip serialized/deserialized interpolator
assert np.all(out == out2)