`igl.spectral`

Spectral formulation of IGL: eigendecomposition-based Green's kernels + null-space augmentation.

Not flattened into the top-level igl namespace. Import explicitly::

from igl.spectral import SpectralKernel, FourierSineBasis, ConstantNullSpace

Mathematical setup

For an operator \(L\) with eigendecomposition \(L \phi_n = \lambda_n \phi_n\), the Green's function is

\[ G(z, s) = \sum_n \frac{\phi_n(z)\, \phi_n(s)}{\max(\lambda_n, \varepsilon)}. \]

Zero-\(\lambda\) modes ARE the null space — modes the Green's function cannot reach. The kernel-agnostic NullSpaceBasis adds them back as extra design-matrix columns whose coefficients are fitted by lstsq without Tikhonov shrinkage.

SpectralKernel

`igl.spectral.kernel.SpectralKernel`

Bases: Module

Spectral Green's-function kernel.

Parameters:

Name	Type	Description	Default
`latent_dim`	`int`	Latent dimensionality `d`.	required
`bases`	`SpectralBasis \| Sequence[SpectralBasis]`	One :class:`SpectralBasis` (used uniformly across all `latent_dim` dimensions) or a sequence of length `latent_dim`. Sub-bases may have different mode counts.	required
`n_anchors`	`int`	Number of anchor positions `R` in latent space.	`64`
`null_space`	`NullSpaceBasis \| None`	Optional :class:`NullSpaceBasis` — its `evaluate(z)` output is concatenated to the design matrix.	`None`
`epsilon`	`float`	Floor applied to eigenvalues (additional safety on top of the basis's own clamping).	`0.0001`
`anchor_init_std`	`float`	Std-dev of the Gaussian initialiser for the learnable anchor positions.	`0.25`

Raises:

Type	Description
`IGLConfigError`	On shape mismatches or invalid hyperparameters.

`compute_design_matrix(z, *, gate_mask=None)`

Build the design matrix.

Parameters:

Name	Type	Description	Default
`z`	`Tensor`	`[N, d]` latent coordinates.	required
`gate_mask`	`Tensor \| None`	Optional `[d]` binary mask; latent dims with `mask = 0` contribute a factor of `1` (neutral).	`None`

Returns:

Type	Description
`Tensor`	`[N, output_dim]` design matrix.

Closed-form 1-D bases

`igl.spectral.bases.fourier_sine.FourierSineBasis`

Bases: Module

1-D Fourier sine spectral basis (Dirichlet BCs).

Parameters:

Name	Type	Description	Default
`n_modes`	`int`	Number of modes `K` (default `16`).	`16`

Raises:

Type	Description
`IGLConfigError`	For `n_modes < 1`.

`igl.spectral.bases.fourier_cosine.FourierCosineBasis`

Bases: Module

1-D Fourier cosine spectral basis (Neumann BCs).

Parameters:

Name	Type	Description	Default
`n_modes`	`int`	Number of modes `K` (default `16`); index `0` is the constant.	`16`
`epsilon`	`float`	Floor applied to the zero eigenvalue so the kernel's `1/λ` weighting stays finite. Default `1e-4`.	`0.0001`

Raises:

Type	Description
`IGLConfigError`	For `n_modes < 1` or `epsilon <= 0`.

`igl.spectral.bases.chebyshev.ChebyshevBasis`

Bases: Module

1-D Chebyshev (first-kind) spectral basis.

Inputs are mapped from [0, 1] to [-1, 1] via x = 2 z − 1 before evaluation.

Parameters:

Name	Type	Description	Default
`n_modes`	`int`	Number of modes `K` (default `16`); index `0` is the constant `T₀`.	`16`
`epsilon`	`float`	Floor applied to the zero eigenvalue (`λ₀`).	`0.0001`

Raises:

Type	Description
`IGLConfigError`	For `n_modes < 1` or `epsilon <= 0`.

`igl.spectral.bases.legendre.LegendreBasis`

Bases: Module

1-D Legendre spectral basis.

Inputs mapped from [0, 1] to [-1, 1] via x = 2 z − 1.

Parameters:

Name	Type	Description	Default
`n_modes`	`int`	Number of modes `K` (default `16`); index `0` is the constant `P₀`.	`16`
`epsilon`	`float`	Floor applied to `λ₀`.	`0.0001`

Raises:

Type	Description
`IGLConfigError`	For `n_modes < 1` or `epsilon <= 0`.

`igl.spectral.bases.hermite.HermiteBasis`

Bases: Module

1-D Hermite-function spectral basis (Gaussian-weighted domain).

Parameters:

Name	Type	Description	Default
`n_modes`	`int`	Number of modes `K`.	`16`

Raises:

Type	Description
`IGLConfigError`	For `n_modes < 1`.

`igl.spectral.bases.laguerre.LaguerreBasis`

Bases: Module

1-D Laguerre-function spectral basis (exponentially-weighted domain).

Parameters:

Name	Type	Description	Default
`n_modes`	`int`	Number of modes `K`.	`16`

Raises:

Type	Description
`IGLConfigError`	For `n_modes < 1`.

Data-driven bases

`igl.spectral.bases.learned_lb.LearnedLaplacianBasis`

Bases: Module

Numerically-estimated Laplace–Beltrami spectrum on a learned manifold.

Parameters:

Name	Type	Description	Default
`n_modes`	`int`	Number of eigenmodes `K` to retain (smallest eigenvalues).	`16`
`k_nn`	`int`	Number of nearest neighbours used to build the graph.	`10`
`epsilon`	`float`	Floor applied to the zero eigenvalue (`λ₀`) when evaluating the Nyström extension.	`0.0001`

Raises:

Type	Description
`IGLConfigError`	For invalid hyperparameters.

Attributes:

Name	Type	Description
`is_refreshed`	`bool`	`True` once :meth:`refresh` has run. Calling :meth:`evaluate` before refresh raises.

`evaluate(z)`

Nyström-extend the eigenfunctions to z.

Parameters:

Name	Type	Description	Default
`z`	`Tensor`	`[N, d]` query latents.	required

Returns:

Type	Description
`Tensor`	`[N, n_modes]` eigenfunction values.

Raises:

Type	Description
`IGLConfigError`	If :meth:`refresh` has not been called.

`refresh(z)`

Recompute the LB spectrum from a fresh set of encoded latents.

Parameters:

Name	Type	Description	Default
`z`	`Tensor`	`[M, d]` encoded latents (`M` should be ≥ a few hundred for the spectrum to be informative).	required

`igl.spectral.bases.graph_laplacian.GraphLaplacianBasis`

Bases: Module

Graph-Laplacian spectral basis.

Parameters:

Name	Type	Description	Default
`adjacency`	`Tensor \| ndarray \| spmatrix`	`[n, n]` adjacency matrix. Accepts a dense PyTorch tensor, a dense numpy array, or any scipy sparse matrix.	required
`n_modes`	`int`	Number of eigenmodes `K`.	`16`
`normalization`	`GraphLaplacianNormLike`	One of :class:`GraphLaplacianNorm`. Default `SYMMETRIC`.	`SYMMETRIC`
`epsilon`	`float`	Floor applied to `λ₀` (which is always 0 for a connected graph in the symmetric / unnormalized cases).	`0.0001`

Raises:

Type	Description
`IGLConfigError`	For invalid shapes or hyperparameters.

`evaluate(z)`

Return eigenfunction values at the given node indices.

Parameters:

Name	Type	Description	Default
`z`	`Tensor`	`[N]` long-tensor of node indices, or `[N, 1]` with integer dtype.	required

Returns:

Type	Description
`Tensor`	`[N, n_modes]` eigenfunction values.

Mixtures

`igl.spectral.multi.MultiSpectralBasis`

Bases: Module

A weighted concatenation of several :class:SpectralBasis instances.

Implements the :class:SpectralBasis Protocol: n_modes is the sum of the sub-bases' mode counts, eigenvalues is the concatenated vector, and null_indices is the union of the sub-bases' null indices (re-numbered to account for offsets).

The mixing weights are softmax-normalised mode-block weights — every basis is multiplied by a learned (or fixed) coefficient so the optimiser can up- or down-weight a contribution.

Parameters:

Name	Type	Description	Default
`bases`	`Sequence[SpectralBasis]`	Sequence of two or more :class:`SpectralBasis` instances.	required
`learnable`	`bool`	When `True` (default), the mixing weights are `nn.Parameter`; otherwise they are equal and fixed.	`True`

Raises:

Type	Description
`IGLConfigError`	For empty or singleton sequences.

`evaluate(z)`

Evaluate every sub-basis and weight by the softmax-mixed coefficients.

Null-space augmentation

`igl.spectral.null_space.ConstantNullSpace`

One column of ones — the DC mode.

Standard null space for the Neumann Laplacian (constants are harmonic with the Neumann boundary condition). Useful in general as a cheap way to give a local :class:igl.GreenKernel a DC mode it otherwise lacks.

`igl.spectral.null_space.PolynomialNullSpace`

Constants + per-dimension monomials up to degree.

For degree = 1: one column of ones plus d columns z_j. For degree = 2: also includes z_j^2. Up to degree = k: the constant plus all univariate monomials per dimension — contains the harmonics of the Euclidean Laplacian up to that degree (mixed monomials like z_j z_k are not included; users needing those can subclass :class:CustomNullSpace).

Parameters:

Name	Type	Description	Default
`latent_dim`	`int`	Number of input dimensions `d`.	required
`degree`	`int`	Maximum monomial degree (inclusive). Default `1`.	`1`

Raises:

Type	Description
`IGLConfigError`	For `degree < 0` or `latent_dim < 1`.

`igl.spectral.null_space.CustomNullSpace`

Wraps a user-supplied callable as a :class:NullSpaceBasis.

Parameters:

Name	Type	Description	Default
`fn`	`Callable[[Tensor], Tensor]`	Callable `z -> [N, n_columns]`.	required
`n_columns`	`int`	Number of columns the callable returns.	required

Raises:

Type	Description
`IGLConfigError`	When `n_columns < 1`.

`igl.spectral.null_space.build_null_space(kind, *, latent_dim, degree=1)`

Build a built-in null space from a :class:NullSpaceKind.

Parameters:

Name	Type	Description	Default
`kind`	`NullSpaceKindLike`	One of :data:`NullSpaceKind`. `NONE` returns `None`.	required
`latent_dim`	`int`	Required for `POLYNOMIAL`.	required
`degree`	`int`	Forwarded to :class:`PolynomialNullSpace`.	`1`

Returns:

Type	Description
`ConstantNullSpace \| PolynomialNullSpace \| None`	An instance of :class:`ConstantNullSpace` /
`ConstantNullSpace \| PolynomialNullSpace \| None`

Refresh hook

`igl.spectral.refresh.LearnedLBRefresh`

Refresh a :class:LearnedLaplacianBasis every every batches.

Implements :class:igl.types.ExtraLoss purely for its scheduling semantics — it returns None (no loss contribution) and uses the callback to invoke :meth:LearnedLaplacianBasis.refresh with the current batch's encoded latents. The first refresh happens on the very first call.

Parameters:

Name	Type	Description	Default
`basis`	`LearnedLaplacianBasis`	The learned-LB basis to keep up to date.	required
`every`	`int`	Refresh frequency in batches.	`200`
`weight`	`float`	Ignored (kept for protocol compatibility); defaults to 0.	`0.0`

Raises:

Type	Description
`IGLConfigError`	When `every < 1`.