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 once on the whole latent when it is a joint basis) 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. Ignored when anchors is given.	64
null_space	NullSpaceBasis | None	Optional :class:NullSpaceBasis — its evaluate(z) output is concatenated to the design matrix. Required to reach the null modes the kernel excludes.	None
epsilon	float	Floor applied to the retained 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 (pre-map space).	0.25
anchors	Tensor | None	Optional explicit initial anchor positions [R, d]. Mandatory (as integer node ids) for an index basis.	None
learnable_anchors	bool	When False the anchors are a fixed buffer.	True
domain_map	DomainMapLike	"auto" squashes each coordinate into its basis's domain before evaluation; "none" feeds the raw latent.	AUTO

Raises:

Type	Description
IGLConfigError	On shape mismatches, invalid hyperparameters, a joint basis inside a per-dimension sequence, or an index basis without fixed integer anchors.

is_joint property

Whether the kernel expands one joint basis on the whole latent.

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). A joint basis sees the mask only through the masked z.	None

Returns:

Type	Description
Tensor	[N, output_dim] design matrix.

map_to_domain(z)

Squash [N, d] latents into the per-dimension basis domains (identity for "none").

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 and to extend the eigenfunctions.	10
epsilon	float	Floor applied to the zero eigenvalue (λ₀) in :attr:eigenvalues, and to μ_n = 1 − λ_n in the Nyström denominator.	0.0001

Raises:

Type	Description
IGLConfigError	For invalid hyperparameters.

Attributes:

Name	Type	Description
is_joint	bool	Always True — the basis takes the whole latent vector.
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 (a [N] tensor is read as d = 1).	required

Returns:

Type	Description
Tensor	[N, n_modes] eigenfunction values.

Raises:

Type	Description
IGLConfigError	If :meth:refresh has not been called, or z does not have the refresh latents' width.

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] or [N, 1] tensor of node indices. A float tensor is accepted when every value is an integer in range.	required

Returns:

Type	Description
Tensor	[N, n_modes] eigenfunction values.

Raises:

Type	Description
IGLConfigError	For non-integer values or indices outside [0, n_nodes).

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.