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, M), where N is the number of points and M is the number of columns of observed values to solve for.	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

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:

Type	Description
NDArray[float64]	Array of interpolated values with shape (N, M), where N is the number of target points and M is the number of columns of values interpolated.

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:

Type	Description
NDArray[float64]	Array of interpolated values with shape (N, M), where N is the number of source points and M is the number of columns of values interpolated.

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:

Type	Description
NDArray[float64]	Array of interpolated values with shape (N, M), where N is the number of target points and M is the number of columns of values interpolated.

build_isosurfaces(extents, resolution, isovalues)

Build 3D isosurfaces using a surface-following, non-adaptive Surface Nets method.

The sampling resolution controls grid density; choose it relative to the data scale and desired detail. Multiple isovalues may be provided; each produces a separate surface.

Seed cells are selected from samples within resolution of an isovalue. If no seeds are found for a given isovalue, the corresponding entry is empty.

Surface quality

The current isosurface extraction method does not guarantee manifold or valid meshes; surfaces may contain trifurcations or self-intersections.

Surfaces may therefore not be suitable for downstream boolean operations.

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

Returns:

Type	Description
tuple[list[NDArray[float64]], list[NDArray[uintp]]]	(points_per_iso, faces_per_iso) where: points_per_iso[i] is a (V_i, 3) array of vertex positions for the i-th isosurface. faces_per_iso[i] is an (F_i, 3) integer array of triangle vertex indices.

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.

source_points()

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()

Access the stored source values from the interpolator

Returns:

Type	Description
NDArray[float64]	Array of interpolated values with shape (N, M), where N is the number of source points and M is the number of columns of values.