torchtt.functional: continuous function bases

The subpackage includes the abstract torchtt.functional.BaseBasis class and its torchtt.functional.BSplineBasis and torchtt.functional.GaussianBasis implementations.

Evaluation, interpolation, and integration

Both concrete bases follow these conventions:

  • basis.n is the number of basis functions.

  • basis(x) returns shape (basis.n, *x.shape). The first axis indexes basis functions; basis(x, derivative=True) evaluates their first derivatives with respect to x. Evaluation also supports PyTorch autograd with respect to the input points.

  • points, matrix = basis.interpolating_points() returns shapes (n,) and (n, n). The matrix has sample points in rows and basis functions in columns: matrix = basis(points).T. Thus interpolation coefficients solve matrix @ coefficients = function_values. Gaussian interpolation can be ill-conditioned for closely spaced centers or wide basis functions.

  • basis.integration_weights() returns one integral per basis function, shape (n,). Spline weights include any decaying tails, and Gaussian weights integrate over the entire real line.

The bases are PyTorch modules. Construct and move the basis, coefficients, and input tensors to a common device and dtype, for example with basis.to(device=device, dtype=torch.float64).

Density estimation with TTDensityLayer

torchtt.nn.TTDensityLayer uses these bases to evaluate a normalized probability density from TT parameters. A neural network can supply the flat parameter vector, allowing the density to depend on conditioning data. The layer uses squared TT coefficients with the basis values and normalizes using their integration weights. Optional coordinate transformations include the Jacobian factor in the density evaluation.

Examples

The existing tutorials in examples/ demonstrate these APIs:

  • Basis functions: B-spline and Gaussian evaluation, interpolation, integration, derivatives, and spline boundary conditions.

  • Deep TT density estimation: TTDensityLayer with Gaussian bases and coordinate transformations.

  • Fokker-Planck PINN: a neural network supplies the density layer’s parameters as a function of time.

API reference

BaseBasis

class torchtt.functional.BaseBasis[source]

Bases: ABC, Module

Abstract base class for all basis functions.

All basis classes must implement the following:
  • n property: the dimension (number of basis functions)

  • __call__: evaluate the basis at given points

  • __repr__: string representation

  • interpolating_points: return points where the basis evaluation matrix is invertible

  • integration_weights: return the integral of each basis function

abstract __call__(x: Tensor, derivative: bool = False) → Tensor[source]

Evaluate the basis functions at the given points.

Each basis function is evaluated at every point in x, and the results are stacked along a new first dimension.

Parameters:
  • x (torch.Tensor) – points where the basis is evaluated. Arbitrary shape (…).

  • derivative (bool, optional) – if True, evaluate the derivative. Defaults to False.

Returns:

the basis evaluated at x. Shape (n, …) where n is the

basis dimension and … is the shape of the input.

Return type:

torch.Tensor

abstract integration_weights() → Tensor[source]

Return the integrals of each individual basis function.

Computes the integral of each basis function over its support, which is useful for various numerical methods and tensor operations.

Returns:

a vector of shape (n,) containing the integral

of each basis function.

Return type:

torch.Tensor

abstract interpolating_points() → Tuple[Tensor, Tensor][source]

Return the interpolating points and the basis evaluated at these points.

The returned matrix (from evaluating the basis at these points) is guaranteed to be invertible (non-singular). This property is essential for interpolation: given function values at these points, one can uniquely determine the coefficients of the basis expansion by solving the linear system.

Returns:

  • points: the interpolating points as a vector of shape (n,)

  • matrix: shape (n, n), with rows corresponding to points and columns to basis functions: matrix = self(points).T. Solve matrix @ coefficients = values for interpolation.

Return type:

Tuple[torch.Tensor, torch.Tensor]

abstract property n: int

The dimension of the basis (number of basis functions).

Returns:

the number of basis functions.

Return type:

int

BSplineBasis

class torchtt.functional.BSplineBasis(knots: Tensor, deg: int, bc='clamped', decay_rate=None)[source]

Bases: BaseBasis

B-spline basis functions (pure PyTorch implementation).

This class implements a univariate B-spline basis defined by a knot vector and polynomial degree using the Cox-de Boor recursion formula. The implementation is fully differentiable via PyTorch autograd.

The behavior at each boundary can be selected via the bc argument:

  • "clamped" (default): the boundary knot is repeated, the basis is clamped and the first/last basis function reaches 1 at the boundary.

  • "zero": like "clamped", but the basis function that is nonzero at the boundary is omitted. Every function in the span (and hence any expansion) vanishes at that boundary. Reduces n by one per side.

  • "decay": the domain becomes unbounded on that side. The knot vector is extended with deg uniformly spaced phantom knots and the basis functions whose support crosses the boundary knot are continued beyond it by tails of the form sum_{j=1..deg} a_j * exp(-j * rate * |x - boundary|), with the deg coefficients matched in value and the first deg-1 derivatives. The basis is therefore C^(deg-1) on the whole unbounded domain and all integrals remain finite. The crossing functions whose Greville center would fall outside [a, b] are dropped, so the outermost retained function peaks at the boundary and decays monotonically past it (no redundant bump in the tail). As a result the partition of unity is only approximate within roughly deg knot spans of a decay boundary.

The number of basis functions is n = len(knots) + deg - 1, reduced by the dropped boundary functions: one per "zero" side and the number of out-of-domain crossing functions per "decay" side (roughly deg/2).

Example

>>> knots = torch.linspace(0, 1, 5)
>>> basis = BSplineBasis(knots, deg=3)
>>> x = torch.linspace(0, 1, 100, requires_grad=True)
>>> B = basis(x)  # shape: (n, 100), supports autograd
>>> B.sum().backward()  # gradients flow through
>>>
>>> # Supports arbitrary input shapes
>>> x_batch = torch.rand(32, 10, requires_grad=True)
>>> B_batch = basis(x_batch)  # shape: (n, 32, 10)
>>>
>>> # Sparse evaluation: only the deg+1 functions that are nonzero at
>>> # each point, plus their indices -- never forms the (n, ...) matrix
>>> values, indices = basis.eval_sparse(x)  # both shape: (deg+1, 100)
>>>
>>> # Density-friendly variant: vanishes at 0, unbounded to the right
>>> basis_pdf = BSplineBasis(knots, deg=3, bc=("zero", "decay"))

Note

Evaluation is local: the knot span of each point is found by a binary search and only the deg + 1 B-splines that are nonzero there are computed, by a vectorised de Boor recursion. The cost is O(deg^2) per point and is independent of the number of knots, and the whole recursion is a handful of elementwise tensor operations, which keeps it fast on both CPU and GPU and differentiable through autograd. eval_sparse returns that compressed result directly; __call__ scatters it into the dense (n, …) matrix. The mass, stiffness and advection matrices are assembled from the same local blocks, so they too scale linearly in n.

Note

For "decay" sides the exponential tails are matched to the spline jet at the boundary. The tails are the general polynomial in the mapped variable t = 1 - exp(-rate * |x - boundary|), which sends the unbounded side onto [0, 1), constrained to vanish at t = 1 so that they stay integrable; in x this is a sum of deg geometrically spaced decaying exponentials with no growing factor. With the default rate deg / h the tails are non-negative and monotone to machine precision. Rates much smaller than deg / h can still produce a small negative undershoot; prefer increasing the spacing of the boundary knots over lowering the rate if heavier tails are needed.

Initialize a B-spline basis.

Parameters:
  • knots (torch.Tensor) – the interior knot vector (at least 2 entries). For “clamped”/”zero” sides the boundary knot is automatically repeated deg times; for “decay” sides deg phantom knots with the spacing of the adjacent knot interval are appended instead.

  • deg (int) – the polynomial degree of the B-splines (e.g., 3 for cubic).

  • bc (str or tuple[str, str], optional) – boundary mode for the (left, right) side, each one of “clamped”, “zero” or “decay”. A single string applies to both sides. Modes other than “clamped” require deg >= 1. Defaults to “clamped”.

  • decay_rate (float or tuple[float, float], optional) – exponential decay rate(s) for “decay” sides; the slowest term of a tail behaves like exp(-decay_rate * |x - boundary|), setting the far-field rate. A None entry uses the default deg / h, where h is the adjacent knot spacing. Defaults to None.

__call__(x: Tensor, derivative: bool = False) → Tensor[source]

Evaluate the B-spline basis functions at the given points.

Each basis function is evaluated at every point in x, and the results are stacked along a new first dimension. This method is fully differentiable via PyTorch autograd.

Only deg + 1 basis functions are nonzero at any point: they are computed by eval_sparse in O(deg^2) per point, independently of the number of knots, and scattered into the dense output. Use eval_sparse directly to skip the dense (n, …) result altogether.

Parameters:
  • x (torch.Tensor) – points where the basis is evaluated. Arbitrary shape (…).

  • derivative (bool, optional) – if True, evaluate the first derivative of the basis functions. Defaults to False.

Returns:

the B-splines evaluated at x. Shape (n, …) where n

is the number of basis functions and … is the shape of the input.

Return type:

torch.Tensor

advection_matrix(degree: int = None) → Tensor[source]

Compute the advection matrix C_ij = int B_i(x) B’_j(x) dx.

For “decay” sides the integral extends over the unbounded tail; the tail contribution is added analytically.

Parameters:

degree (int, optional) – The number of quadrature points per interval. If not provided, defaults to deg + 1.

Returns:

The advection matrix of shape (n, n).

Return type:

torch.Tensor

property bc: Tuple[str, str]

The boundary modes for the (left, right) side.

Returns:

each one of “clamped”, “zero” or “decay”.

Return type:

Tuple[str, str]

property decay_rate: Tuple[float, float]

The exponential decay rates per side (None for non-“decay” sides).

Returns:

the (left, right) decay rates.

Return type:

Tuple[float, float]

property deg: int

The polynomial degree of the B-splines.

Returns:

the degree.

Return type:

int

eval_sparse(x: Tensor, derivative: bool = False) → Tuple[Tensor, Tensor][source]

Sparse (compressed) evaluation of the basis.

At most deg + 1 basis functions are nonzero at any point, so instead of the dense (n, …) matrix returned by __call__ this returns only those values together with the index of the basis function each one belongs to. Both the work and the memory are O(deg^2) per point and do not grow with the number of knots (or basis functions), which is what makes the evaluation cheap for fine knot vectors. It is fully differentiable in x and runs as a handful of elementwise kernels, so it is fast on CPU and GPU alike.

Parameters:
  • x (torch.Tensor) – points where the basis is evaluated. Arbitrary shape (…).

  • derivative (bool, optional) – if True, evaluate the first derivative of the basis functions. Defaults to False.

Returns:

  • values: shape (deg+1, …), the nonzero basis values.
    • indices: shape (deg+1, …), integer indices into [0, n) of the corresponding basis functions.

Slots that carry no basis function (points outside the domain, or functions dropped by a “zero”/”decay” boundary) have value exactly 0 and an in-range but otherwise meaningless index, so the pair can be gathered or scattered without any further masking.

Return type:

Tuple[torch.Tensor, torch.Tensor]

Example

>>> basis = BSplineBasis(torch.linspace(0, 1, 1000), deg=3)
>>> x = torch.rand(10000, requires_grad=True)
>>> v, i = basis.eval_sparse(x)     # (4, 10000) instead of (1001, 10000)
>>> f = (c[i] * v).sum(0)           # == c @ basis(x), for coefficients c
>>> f.sum().backward()              # gradients flow through
integration_weights() → Tensor[source]

Return the integrals of each individual B-spline basis function.

For B-splines supported inside the interval, the integral of basis function B_{i,p}(x) over its entire support is given by the analytical formula:

∫ B_{i,p}(x) dx = (t_{i+p+1} - t_i) / (p+1)

where t_i are the knots in the extended knot vector and p is the degree. For “decay” sides, the bounded part is integrated exactly with Gauss-Legendre quadrature and the analytic integral of the exponential tails is added, so the weights are the integrals over the whole (unbounded) domain.

Returns:

a vector of shape (n,) containing the integral of

each B-spline basis function.

Return type:

torch.Tensor

interpolating_points() → Tuple[Tensor, Tensor][source]

Return the interpolating points (Greville abscissae) and the basis matrix.

The interpolating points are the Greville abscissae, defined as the averages of deg consecutive knots. When the basis is evaluated at these points, the resulting matrix is guaranteed to be invertible (non-singular).

This property is fundamental for B-spline interpolation: given function values f_i at the interpolating points x_i, the coefficients c_j of the B-spline expansion can be uniquely determined by solving:

B(x_i) @ c = f

where B(x_i) is the invertible matrix returned by this method.

For “zero” sides the boundary point is dropped together with the omitted basis function. For “decay” sides the dropped out-of-domain crossing functions take their (past-boundary) Greville points with them, so all retained interpolating points lie within [a, b], the outermost sitting exactly at the boundary.

Returns:

  • points: the Greville abscissae as a vector of shape (n,)

  • matrix: shape (n, n), with rows corresponding to points and columns to basis functions: matrix = self(points).T

Return type:

Tuple[torch.Tensor, torch.Tensor]

property interval: Tuple[float, float]

The interval on which the basis is defined.

Returns:

(start, end) of the interval.

Return type:

Tuple[float, float]

property knots: Tensor

The extended knot vector (including boundary repetitions for “clamped”/”zero” sides and phantom knots for “decay” sides).

Returns:

the knot vector.

Return type:

torch.Tensor

mass_matrix(degree: int = None) → Tensor[source]

Compute the mass matrix M_ij = int B_i(x) B_j(x) dx.

For “decay” sides the integral extends over the unbounded tail; the tail contribution is added analytically.

Parameters:

degree (int, optional) – The number of quadrature points per interval. If not provided, defaults to deg + 1 to ensure exact integration of polynomials of degree up to 2*deg.

Returns:

The mass matrix of shape (n, n).

Return type:

torch.Tensor

property n: int

The dimension of the basis (number of basis functions).

Returns:

the number of basis functions.

Return type:

int

quadrature(degree: int) → Tuple[Tensor, Tensor][source]

Compute quadrature points and weights for integrating functions in the B-spline basis.

It computes Gauss-Legendre quadrature points and weights for each non-zero length interval between the knots. For “decay” sides, points mapped through the tail variable t = 1 - exp(-rate * |x - boundary|) are appended on the unbounded tail. In t the tails are polynomials vanishing at t = 1, so with degree >= deg the rule is exact both for the basis tails themselves and for their pairwise products (e.g. mass matrix entries).

Parameters:

degree (int) – the number of quadrature points per interval (and per tail).

Returns:

  • points: 1D tensor of quadrature points (ascending).

  • weights: 1D tensor of corresponding quadrature weights.

Return type:

Tuple[torch.Tensor, torch.Tensor]

stiffness_matrix(degree: int = None) → Tensor[source]

Compute the stiffness matrix S_ij = int B’_i(x) B’_j(x) dx.

For “decay” sides the integral extends over the unbounded tail; the tail contribution is added analytically.

Parameters:

degree (int, optional) – The number of quadrature points per interval. If not provided, defaults to deg + 1.

Returns:

The stiffness matrix of shape (n, n).

Return type:

torch.Tensor

GaussianBasis

class torchtt.functional.GaussianBasis(knots: Tensor, delta_overlap: int)[source]

Bases: BaseBasis

Gaussian basis functions.

The basis functions are Gaussians centered at the knots. phi_i(x) = exp(-(x - mu_i)^2 / (2 * sigma_i^2))

The centers mu_i are the knots themselves. The widths sigma_i are determined by the ‘delta_overlap’ parameter, which specifies the distance to the neighboring knot that defines the scale. Specifically, sigma_i is set to the distance between the i-th knot and the (i + delta_overlap)-th knot. For indices where this neighbor doesn’t exist (near the end), the distance to the (i - delta_overlap)-th knot is used.

Initialize a Gaussian basis.

Parameters:
  • knots (torch.Tensor) – the centers of the Gaussian functions.

  • delta_overlap (int) – the knot stride used to determine the width (sigma) of the Gaussians. Must be >= 1.

__call__(x: Tensor, derivative: bool = False) → Tensor[source]

Evaluate the Gaussian basis or its first derivative at each input point.

Parameters:
  • x (torch.Tensor) – Input points of arbitrary shape (...). Move the basis and input to the same device and dtype before calling.

  • derivative (bool, optional) – Evaluate the first derivative with respect to x if True. Defaults to False.

Returns:

Values of shape (n, ...). Evaluation supports PyTorch autograd with respect to the input points.

Return type:

torch.Tensor

integration_weights() → Tensor[source]

Integrate each Gaussian over the entire real line.

Returns:

Integrals of shape (n,), equal to sigma * sqrt(2 * pi). The Gaussians are not normalized individually.

Return type:

torch.Tensor

interpolating_points() → Tuple[Tensor, Tensor][source]

Return the Gaussian centers and their interpolation matrix.

Returns:

Points of shape (n,) and matrix of shape (n, n). Rows correspond to points and columns to basis functions: matrix = self(points).T. Solve matrix @ coefficients = values for interpolation. Wide or closely spaced Gaussians can make this matrix ill-conditioned.

Return type:

Tuple[torch.Tensor, torch.Tensor]

property n: int

The number of Gaussian basis functions.