Skip to content

RBFInterpolator

ferreus_rbf.RBFInterpolator(points, values, interpolant_settings, params=None, global_trend=None, progress_callback=None)

Radial basis function (RBF) interpolator.

An RBFInterpolator represents a fitted RBF model built from input data points, their associated values, and a chosen kernel. Once constructed, it can be used to evaluate interpolated values at new locations, or serialized for later reuse.

The interpolator stores:

  • The original input points and values.
  • The solved RBF and polynomial coefficients.
  • Kernel settings and solver parameters used during fitting.
  • Optional global trend transforms (e.g. anisotropy/scaling/rotation).
  • An optional Fast Multipole Method (FMM) tree evaluator for efficient queries.

Parameters:

Name Type Description Default
points NDArray[float64]

Coordinates of the input data points with shape (N, D), where N is the number of points and D is the dimensionality.

 required
values NDArray[float64]

Observed values at the input source point locations with shape (N,) for scalar values or (N, K) for one or more value columns.

 required
interpolant_settings InterpolantSettings

Settings used to configure the interpolator.

 required
params Optional[Params]

Solver and algorithm parameters, by default None

 None
global_trend Optional[GlobalTrend]

Optional global trend transform (anisotropy / rotation), by default None

 None
progress_callback Optional[Progress]

Optional callback for reporting solver progress, by default None

 None

source_points property

Access the stored source points from the interpolator

Returns:

Type Description
NDArray[float64]

Array of the source points with shape (N, D), where N is the number of source points and D is the dimenstionality.

source_values property

Access the stored source values from the interpolator

Returns:

Type Description
NDArray[float64]

Array of interpolated values with shape (N,) for scalar values or (N, M) for multiple value columns.

coefficients property

Access solved RBF coefficients.

Returns:

Type Description
Coefficients

The solved RBF coefficients.

evaluate(targets)

Evaluate the interpolant at target_points using a one-shot FMM evaluator.

This is the most convenient way to evaluate a single batch: it builds a temporary FMM tree, evaluates, and discards the evaluator. If a global_trend is present, the target points are transformed for evaluation.

Extents are computed as the union of the source and target point bounding boxes to ensure all targets can be assigned to tree boxes.

Parameters:

Name Type Description Default
targets NDArray[float64]

Coordinates of the target data points with shape (N, D), where N is the number of points and D is the dimensionality.

 required

Returns:

Name Type Description
values NDArray[float64]

Array of interpolated values with shape (N,) for scalar values or (N, M) for multiple value columns.

evaluate_with_gradients(targets)

Evaluate the interpolant and its gradient at target_points using a one-shot FMM evaluator.

This is the most convenient way to evaluate a single batch: it builds a temporary FMM tree, evaluates, and discards the evaluator. If a global_trend is present, the target points are transformed for evaluation.

Extents are computed as the union of the source and target point bounding boxes to ensure all targets can be assigned to tree boxes.

Parameters:

Name Type Description Default
targets NDArray[float64]

Coordinates of the target data points with shape (N, D), where N is the number of points and D is the dimensionality.

 required

Returns:

Name Type Description
values NDArray[float64]

Array of interpolated values with shape (N,) for scalar values or (N, M) for multiple value columns.
gradient NDArray[float64]

Array of interpolated gradients with shape (N, D x M), where N is the number of target points, D is the dimensionality and M is the number of columns of values interpolated.
The gradient values are stored in batches of D columns, so the first D columns are for each dimension of the first column of values evaluated, the second D columns are for each dimension of the second column of values evaluated etc.

evaluate_at_source(add_nugget=False)

Evaluate the interpolant at the original source points.

Useful for convergence checks and diagnostics.

Parameters:

Name Type Description Default
add_nugget Optional[bool]

Whether to add the nugget effect back to the result, by default False

When add_nugget = True, the diagonal “nugget” term is added back so the evaluated values should match the input samples to within the solver's tolerance (undoing any smoothing from the nugget).

When add_nugget = False, you observe the smoothed/regularised fit.

 False

Returns:

Name Type Description
values NDArray[float64]

Array of interpolated values with shape (N,) for scalar values or (N, M) for multiple value columns.
Notes

This path uses a sparse/leaf-only evaluation strategy optimized for source-point queries.

build_evaluator(extents=None)

Build and store an FMM evaluator for repeated evaluations.

Use this when you'll call evaluate_targets many times (e.g. during isosurfacing or interactive probing). The evaluator is constructed once and saved inside the interpolator.

Parameters:

Name Type Description Default
extents Optional[NDArray[float64]]

AABB extents to build the evaluator [min_0.., max_0..], by default None. If None, extents are derived from the (transformed, if applicable) source points.

 None

evaluate_targets(targets)

Evaluate using the stored evaluator built by build_evaluator.

This is the fast path for repeated calls. If a global_trend is present, target points are transformed consistently with the stored evaluator.

Panics
  • If called before build_evaluator.
  • If any target_points lie outside the extents used to build the evaluator.

Parameters:

Name Type Description Default
targets NDArray[float64]

Coordinates of the target data points with shape (N, D), where N is the number of points and D is the dimensionality.

 required

Returns:

Name Type Description
values NDArray[float64]

Array of interpolated values with shape (N,) for scalar values or (N, M) for multiple value columns.

evaluate_targets_with_gradients(targets)

Evaluate the interpolant and gradient using the stored evaluator built by build_evaluator.

This is the fast path for repeated calls. If a global_trend is present, target points are transformed consistently with the stored evaluator.

Panics
  • If called before build_evaluator.
  • If any target_points lie outside the extents used to build the evaluator.

Parameters:

Name Type Description Default
targets NDArray[float64]

Coordinates of the target data points with shape (N, D), where N is the number of points and D is the dimensionality.

 required

Returns:

Name Type Description
values NDArray[float64]

Array of interpolated values with shape (N,) for scalar values or (N, M) for multiple value columns.
gradients NDArray[float64]

Array of interpolated gradients with shape (N, D x M), where N is the number of target points, D is the dimensionality and M is the number of columns of values interpolated.
The gradient values are stored in batches of D columns, so the first D columns are for each dimension of the first column of values evaluated, the second D columns are for each dimension of the second column of values evaluated etc.

build_isosurface(extents, resolution, isovalue, boundary_closure=None)

Extract an isosurface using regularised marching tetrahedra.

Parameters:

Name Type Description Default
extents NDArray[float64]

Evaluation domain [minx, miny, minz, maxx, maxy, maxz].

 required
resolution float

Sampling lattice step in world units.

 required
isovalue float

Scalar level to extract.

 required
boundary_closure BoundaryClosure | None

Boundary closure method to use. If None, leaves clipped boundaries open.

 None

Returns:

Type Description
Mesh

Extracted triangle mesh.

build_isosurfaces(extents, resolution, isovalues, boundary_closure=None)

Convenience wrapper for build_isosurface that can extract multiple meshes from a list of isovalues at once.

Parameters:

Name Type Description Default
extents NDArray[float64]

evaluation domain [minx, miny, minz, maxx, maxy, maxz]

 required
resolution float

grid step in world units.

 required
isovalues list[float]

list of scalar levels to extract.

 required
boundary_closure BoundaryClosure | None

Boundary closure method to use. If None, leaves clipped boundaries open.

 None

Returns:

Type Description
list[Mesh]

One mesh per requested isovalue.

save_model(path)

Save this interpolator to a JSON envelope { format, version, model }.

The on-disk format is versioned via JSON_FORMAT_NAME and JSON_VERSION. Files produced here are intended to be read back with load_model.

Parameters:

Name Type Description Default
path str

file path to save the model to.

 required

load_model(path, progress_callback=None) staticmethod

Load an interpolator from a versioned JSON envelope, validating format & version, saved using save_model.

If progress is Some, installs the sink into self.params.progress_callback on the returned model so subsequent long-running operations (evaluation, surface extraction, etc.) can report progress.

Parameters:

Name Type Description Default
path str

file path to load the model from.

 required
progress_callback Optional[Progress]

Progress callback operator, by default None

 None

Returns:

Type Description
RBFInterpolator

A solved RBFInterpolator that can be used for evaluations and surfacing.