Interpolation

Differentiable interpolation (ungridding) and adjoint interpolation (gridding) functions.

torchlinops.functional.interpolate

interpolate(
    vals: Inexact[Tensor, ...],
    locs: Float[Tensor, "... D"],
    width: float | tuple[float, ...],
    kernel="kaiser_bessel",
    norm: int = 1,
    pad_mode: str = "circular",
    kernel_params: dict = None,
)

Interpolate from a regular grid to scattered locations (ungridding).

Evaluates values on a uniform grid at arbitrary non-uniform locations using kernel-based interpolation. This is the forward NUFFT interpolation step. Gradients are computed via the adjoint (gridding) operation.

PARAMETER	DESCRIPTION
vals	Values on a regular grid. The last D dimensions are spatial, where D = locs.shape[-1]. TYPE: Inexact[Tensor, ...]
locs	Non-uniform target locations, with coordinates in the range [0, N-1] for each spatial dimension of size N. TYPE: Float[Tensor, '... D']
width	Interpolation kernel width (in grid units) for each spatial dimension. A scalar applies the same width to all dimensions. TYPE: float or tuple of float
kernel	Interpolation kernel type. Default is 'kaiser_bessel'. TYPE: str DEFAULT: 'kaiser_bessel'
norm	Kernel normalization order. Default is 1. TYPE: int DEFAULT: 1
pad_mode	Padding mode for out-of-bounds access. Default is 'circular'. TYPE: str DEFAULT: 'circular'
kernel_params	Additional parameters passed to the interpolation kernel (e.g., {'beta': ...} for Kaiser-Bessel). TYPE: dict DEFAULT: None

RETURNS	DESCRIPTION
Tensor	Interpolated values at the non-uniform locations.

Source code in src/torchlinops/functional/_interp/interp.py

def interpolate(
    vals: Inexact[Tensor, "..."],
    locs: Float[Tensor, "... D"],
    width: float | tuple[float, ...],
    kernel="kaiser_bessel",
    norm: int = 1,
    pad_mode: str = "circular",
    kernel_params: dict = None,
):
    """Interpolate from a regular grid to scattered locations (ungridding).

    Evaluates values on a uniform grid at arbitrary non-uniform locations
    using kernel-based interpolation. This is the forward NUFFT interpolation
    step. Gradients are computed via the adjoint (gridding) operation.

    Parameters
    ----------
    vals : Inexact[Tensor, "..."]
        Values on a regular grid. The last ``D`` dimensions are spatial,
        where ``D = locs.shape[-1]``.
    locs : Float[Tensor, "... D"]
        Non-uniform target locations, with coordinates in the range
        ``[0, N-1]`` for each spatial dimension of size ``N``.
    width : float or tuple of float
        Interpolation kernel width (in grid units) for each spatial
        dimension. A scalar applies the same width to all dimensions.
    kernel : str, optional
        Interpolation kernel type. Default is ``'kaiser_bessel'``.
    norm : int, optional
        Kernel normalization order. Default is 1.
    pad_mode : str, optional
        Padding mode for out-of-bounds access. Default is ``'circular'``.
    kernel_params : dict, optional
        Additional parameters passed to the interpolation kernel
        (e.g., ``{'beta': ...}`` for Kaiser-Bessel).

    Returns
    -------
    Tensor
        Interpolated values at the non-uniform locations.
    """
    return InterpolateFn.apply(vals, locs, width, kernel, norm, pad_mode, kernel_params)

torchlinops.functional.interpolate_adjoint

interpolate_adjoint(
    vals: Inexact[Tensor, ...],
    locs: Float[Tensor, "... D"],
    grid_size: tuple[int, ...],
    width: float | tuple[float, ...],
    kernel: str = "kaiser_bessel",
    norm: int = 1,
    pad_mode: str = "circular",
    kernel_params: dict = None,
)

Adjoint of interpolation (gridding) from scattered locations to a regular grid.

Scatters values from non-uniform locations back onto a regular grid using kernel-based gridding. This is the adjoint of the interpolate operation and corresponds to the gridding step in an adjoint NUFFT.

PARAMETER	DESCRIPTION
vals	Values at non-uniform locations to be gridded. TYPE: Inexact[Tensor, ...]
locs	Non-uniform source locations, with coordinates in the range [0, N-1] for each spatial dimension of size N. TYPE: Float[Tensor, '... D']
grid_size	Output grid size for each spatial dimension. TYPE: tuple of int
width	Interpolation kernel width (in grid units) for each spatial dimension. A scalar applies the same width to all dimensions. TYPE: float or tuple of float
kernel	Interpolation kernel type. Default is 'kaiser_bessel'. TYPE: str DEFAULT: 'kaiser_bessel'
norm	Kernel normalization order. Default is 1. TYPE: int DEFAULT: 1
pad_mode	Padding mode for out-of-bounds access. Default is 'circular'. TYPE: str DEFAULT: 'circular'
kernel_params	Additional parameters passed to the interpolation kernel (e.g., {'beta': ...} for Kaiser-Bessel). TYPE: dict DEFAULT: None

RETURNS	DESCRIPTION
Tensor	Gridded values on a regular grid of shape (..., *grid_size).

Source code in src/torchlinops/functional/_interp/interp.py

def interpolate_adjoint(
    vals: Inexact[Tensor, "..."],
    locs: Float[Tensor, "... D"],
    grid_size: tuple[int, ...],
    width: float | tuple[float, ...],
    kernel: str = "kaiser_bessel",
    norm: int = 1,
    pad_mode: str = "circular",
    kernel_params: dict = None,
):
    """Adjoint of interpolation (gridding) from scattered locations to a regular grid.

    Scatters values from non-uniform locations back onto a regular grid
    using kernel-based gridding. This is the adjoint of the ``interpolate``
    operation and corresponds to the gridding step in an adjoint NUFFT.

    Parameters
    ----------
    vals : Inexact[Tensor, "..."]
        Values at non-uniform locations to be gridded.
    locs : Float[Tensor, "... D"]
        Non-uniform source locations, with coordinates in the range
        ``[0, N-1]`` for each spatial dimension of size ``N``.
    grid_size : tuple of int
        Output grid size for each spatial dimension.
    width : float or tuple of float
        Interpolation kernel width (in grid units) for each spatial
        dimension. A scalar applies the same width to all dimensions.
    kernel : str, optional
        Interpolation kernel type. Default is ``'kaiser_bessel'``.
    norm : int, optional
        Kernel normalization order. Default is 1.
    pad_mode : str, optional
        Padding mode for out-of-bounds access. Default is ``'circular'``.
    kernel_params : dict, optional
        Additional parameters passed to the interpolation kernel
        (e.g., ``{'beta': ...}`` for Kaiser-Bessel).

    Returns
    -------
    Tensor
        Gridded values on a regular grid of shape ``(..., *grid_size)``.
    """
    return InterpolateAdjointFn.apply(
        vals,
        locs,
        grid_size,
        width,
        kernel,
        norm,
        pad_mode,
        kernel_params,
    )