Skip to content

FmmTree

ferreus_bbfmm.FmmTree(source_points, interpolation_order, kernel_params, adaptive_tree, sparse, extents, params)

A Fast Multipole Method (FMM) tree that organises source points into a hierarchical spatial structure to accelerate kernel summation tasks.

The tree supports both adaptive and uniform refinement, with optional sparse leaf pruning. It efficiently precomputes all operators (M2M and M2L) required for far-field approximation.

Parameters:

Name Type Description Default
source_points NDArray[float64]

Source point locations used to build the tree. Expected to be a numpy array with shape (N, D), where N is the number of points and D is the dimensionality.

 required
interpolation_order int

Number of Chebyshev interpolation nodes per dimension.

 required
kernel_params FmmParams

KernelParams that define the kernel function used for interaction computations.

 required
adaptive_tree bool

Whether the tree uses adaptive or uniform subdivision.

 required
sparse bool

If True, constructs a sparse tree that omits empty leaves.

 required
extents Optional[NDArray[float64]]

Optional bounding box [xmin, xmax, ymin, ymax, ...]; if None, computed from data.

 required
params Optional[FmmParams]

Optional parameters for tuning the FMM performance.

 required

set_weights(weights)

Performs an upward pass of the tree to set the multipole coefficients.

Parameters:

Name Type Description Default
weights NDArray[float64]

Numpy array of shape (N, K), where N is the number of source points and K is the number of right-hand sides to evaluate, containing source point weights (values)

 required

evaluate(weights, target_points)

Performs a downward pass of the tree to set the local coefficients and then performs a leaf evaluation pass to evaluate the values at the target locations.

Parameters:

Name Type Description Default
weights NDArray[float64]

Numpy array of shape (N, K), where N is the number of source points and K is the number of right-hand sides to evaluate, containing source point weights (values)

 required
target_points NDArray[float64]

Numpy array of shape (N, D), where N is the number of target points and D is the dimensionality.

 required

Returns:

Name Type Description
values NDArray[float64]

Array of evaluated values with shape (N, K), where N is the number of target points and K is the number of right-hand-sides evaluated.

evaluate_with_gradients(weights, target_points)

Performs a downward pass of the tree to set the local coefficients and then performs a leaf evaluation pass to evaluate the values and gradients at the target locations.

Parameters:

Name Type Description Default
weights NDArray[float64]

Numpy array of shape (N, K), where N is the number of source points and K is the number of right-hand sides to evaluate, containing source point weights (values)

 required
target_points NDArray[float64]

Numpy array of shape (N, D), where N is the number of target points and D is the dimensionality.

 required

Returns:

Name Type Description
values NDArray[float64]

Array of evaluated values with shape (N, K), where N is the number of target points and K is the number of right-hand-sides evaluated.
gradients NDArray[float64]

Array of evaluated 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.

set_local_coefficients(weights)

Performs a downward pass of the tree to set the local coefficients. Intended to be used before calling evaluate_leaves.

Parameters:

Name Type Description Default
weights NDArray[float64]

Numpy array of shape (N, K), where N is the number of source points and K is the number of right-hand sides to evaluate, containing source point weights (values)

 required

evaluate_leaves(weights, target_points)

Performs a leaf evaluation pass to calculate the values at the target locations. Intended to be used after set_local_coefficients, for when repeated calls to this function are desired, such as when using 'surface following' isosurface generation algorithms.

Parameters:

Name Type Description Default
weights NDArray[float64]

Numpy array of shape (N, K), where N is the number of source points and K is the number of right-hand sides to evaluate, containing source point weights (values)

 required
target_points NDArray[float64]

Numpy array of shape (N, D), where N is the number of target points and D is the dimensionality.

 required

Returns:

Name Type Description
values NDArray[float64]

Array of evaluated values with shape (N, K), where N is the number of target points and K is the number of right-hand-sides evaluated.

evaluate_leaves_with_gradients(weights, target_points)

Performs a leaf evaluation pass to calculate the values and gradients at the target locations. Intended to be used after set_local_coefficients, for when repeated calls to this function are desired, such as when using 'surface following' isosurface generation algorithms.

Parameters:

Name Type Description Default
weights NDArray[float64]

Numpy array of shape (N, K), where N is the number of source points and K is the number of right-hand sides to evaluate, containing source point weights (values)

 required
target_points NDArray[float64]

Numpy array of shape (N, D), where N is the number of target points and D is the dimensionality.

 required

Returns:

Name Type Description
values NDArray[float64]

Array of evaluated values with shape (N, K), where N is the number of target points and K is the number of right-hand-sides evaluated.
gradients NDArray[float64]

Array of evaluated 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.

source_points()

Source point locations used to build the tree.

Returns:

Name Type Description
source_points NDArray[float64]

Numpy array of shape (N, D), where N is the number of source points and D is the dimensionality.