pyharmx.interpolator module

class PolyHarmInterpolator(c: Tensor | ndarray, f: Tensor | ndarray, order: int = 3, smoothing: float = 0.0, device: str = 'cpu', dtype: dtype = torch.float32, *args, **kwargs)

Interpolate batched data using polyharmonic interpolation.

The interpolant has the form:

\({f(x) = \sum_{i = 1}^n w_i \phi(||x - c_i||) + v^\text{T}x + b}\).

This is a sum of two terms: (1) A weighted sum of radial basis function (RBF) terms with centers \({\left(c_1, \ldots, c_n\right)}\). (2) A linear term with a bias. The \({c_i}\) vectors are ‘training’ points. The coefficients \({w}\) and \({v}\) are estimated such that the interpolant exactly fits the value of the function at the \({c_i}\) points, and the vector \({w}\) is orthogonal to each \({c_i}\), and the vector \({w}\) sums to 0. With these constraints, the coefficients can be obtained by solving a linear system.

The function \({\phi}\) is an RBF, parametrized by an interpolation order. Using order=2 produces the well-known thin-plate spline.

We also provide the option to perform regularized interpolation. Here, the interpolant is selected to trade off between the squared loss on the training data and a certain measure of its curvature [details]. Using a regularization weight greater than zero has the effect that the interpolant will no longer exactly fit the training data. However, it may be less vulnerable to overfitting, particularly for high-order interpolation.

Parameters:

• c (torch.Tensor or np.ndarray) – 3D tensor with shape [batch_size, n, d] of n d-dimensional locations. These do not need to be regularly-spaced.

• f (torch.Tensor or np.ndarray) – 3D tensor with shape [batch_size, n, k] of n c-dimensional values evaluated at train_points.

• order (int) – (optional) Order of the interpolation. Common values are 1 for \({\phi(r)=r}\), 2 for \({\phi(r)=r^2 \log(r)}\) (thin-plate spline), or 3 for \({\phi(r)=r^3}\).

• smoothing (float) – (optional) Weight placed on the regularization term. This will depend substantially on the problem, and it should always be tuned. For many problems, it is reasonable to use no regularization. If using a non-zero value, we recommend a small value like 0.001.

• device (str) – (optional) Specifies the default device to store tensors and perform interpolation.

• dtype (torch.dtype) – (optional) Specifies the default precision.

build() → None

Solve for interpolation coefficients.

Computes the coefficients \({w}\) and \({v}\) of the polyharmonic interpolant for the training data defined by \({\left(c, f\right)}\) using the kernel \({\phi}\).

forward(x: Tensor | ndarray) → Tensor

Apply polyharmonic interpolation model to new input data.

Given coefficients \({w}\) and \({v}\) for the interpolation model, the interpolated function is evaluated at query points \({x}\).

Note that the interpolation procedure is differentiable with respect to \({x}\).

Parameters:

x (torch.Tensor) – 3D tensor with shape [batch_size, m, d] to evaluate the interpolation at.

Returns:

Polyharmonic interpolation evaluated at query points x.

Return type:

torch.Tensor

Raises:

ValueError – If the input tensor x is not 3-dimensional.

pyharmx.functions module

cross_squared_distance_matrix(x: Tensor, y: Tensor) → Tensor

Pairwise squared distance between two (batch) matrices’ rows (2nd dimension). Computes the pairwise distances between rows of x and rows of y.

Parameters:

• x (torch.Tensor) – 3D tensor with shape [batch_size, n, d].

• y (torch.Tensor) – 3D tensor with shape [batch_size, m, d].

Returns:

3D tensor with shape [batch_size, n, m]. Each element represents the squared Euclidean distance between vectors x[b, i, :] and y[b, j, :].

Return type:

torch.Tensor

get_phi(order: int) → callable

Coordinate-wise nonlinear function used to define the order of the interpolation. See here for the definition.

Parameters:

order (int) – Interpolation order.

Returns:

Coordinate-wise nonlinear kernel \({\phi}\).

Return type:

callable

pairwise_squared_distance_matrix(x: Tensor) → Tensor

Compute pairwise squared distance among a (batch) matrix’s rows (2nd dimension). It is faster than cross_squared_distance_matrix.

Parameters:

x (torch.Tensor) – 3D tensor with shape [batch_size, n, d].

Returns:

3D tensor with shape [batch_size, n, n]. Each element represents the squared Euclidean distance between vectors x[b, i, :] and x[b, j, :].

Return type:

torch.Tensor