spectralbrain.SpectralDecomposition#

class spectralbrain.SpectralDecomposition(eigenvalues, eigenvectors, *, stiffness=None, mass=None, surface_area=None, metadata=None)[source]#

Bases: object

Eigenvalues and eigenvectors of a Laplace–Beltrami operator.

This is the central object of SpectralBrain. It is produced by core.meshes.BrainMesh.decompose() or core.pointclouds.BrainPointCloud.decompose() and consumed by every function in spectral/.

Parameters:

eigenvalues (ndarray, shape (k,)) – Non-negative LBO eigenvalues, sorted ascending.
eigenvectors (ndarray, shape (N, k)) – Corresponding eigenvectors, M-orthonormal.
stiffness (SparseMatrix, optional) – The Laplacian matrix L.
mass (MassMatrix, optional) – The mass matrix M.
surface_area (float, optional) – Total surface area (for eigenvalue normalisation).
metadata (dict, optional) – Provenance info (subject, hemisphere, structure, backend, …).

eigenvalues#

Type:: ndarray

eigenvectors#

Type:: ndarray

stiffness#

Type:: SparseMatrix or None

mass#

Type:: MassMatrix or None

surface_area#

Type:: float or None

metadata#

Type:: dict

Examples

>>> mesh = sb.core.BrainMesh(vertices, faces)
>>> decomp = mesh.decompose(k=100)
>>> decomp.n_eigenvalues
100
>>> decomp.fiedler_value
0.0023
>>> decomp.truncate(50).n_eigenvalues
50

>>> # Pass to spectral descriptors:
>>> hks = sb.spectral.compute_hks(decomp, t_values)

__init__(eigenvalues, eigenvectors, *, stiffness=None, mass=None, surface_area=None, metadata=None)[source]#

Initialise from eigenvalues, eigenvectors, and optional matrices.

Parameters:

eigenvalues (ndarray[tuple[Any, ...], dtype[floating]])
eigenvectors (ndarray[tuple[Any, ...], dtype[floating]])
stiffness (spmatrix | None)
mass (spmatrix | None)
surface_area (float | None)
metadata (dict[str, Any] | None)

Return type:

None

Methods

`__init__`(eigenvalues, eigenvectors, *[, ...])	Initialise from eigenvalues, eigenvectors, and optional matrices.
`load`(path)	Load from an HDF5 cache file.
`normalize_eigenvalues`([method, area, volume])	Return a copy with normalised eigenvalues.
`save`(path, **kwargs)	Save to HDF5 via `spectralbrain.io.export.save_hdf5()`.
`truncate`(k)	Return a copy with only the first k eigenpairs.

Attributes

`fiedler_value`	First non-trivial eigenvalue λ₁ (the Fiedler value).
`k`	Alias for `n_eigenvalues`.
`n_eigenvalues`	Number of stored eigenpairs.
`n_vertices`	Number of vertices/points.
`shape_dna`	ShapeDNA — the raw eigenvalue sequence (excluding λ₀ ≈ 0).
`shape_dna_normalized`	Area-normalised ShapeDNA.
`spectral_gap`	Gap between λ₁ and λ₂.

classmethod load(path)[source]#

Load from an HDF5 cache file.

Parameters:: path (PathLike)
Returns:: SpectralDecomposition
Return type:: SpectralDecomposition

normalize_eigenvalues(method='area', area=None, volume=None)[source]#

Return a copy with normalised eigenvalues.

Parameters:

method (str) – "area" — multiply by surface area (Reuter convention). "volume" — multiply by volume^{2/3}. "fiedler" — divide by λ₁.
area (float, optional) – Override surface area.
volume (float, optional) – Override volume.

Returns:

SpectralDecomposition

Return type:

SpectralDecomposition

save(path, **kwargs)[source]#

Save to HDF5 via spectralbrain.io.export.save_hdf5().

Parameters:

path (PathLike) – Output .h5 file.
kwargs (Any)

Returns:

Path

Return type:

Path

truncate(k)[source]#

Return a copy with only the first k eigenpairs.

Parameters:: k (int) – Number of eigenpairs to keep (must be ≤ current k).
Returns:: SpectralDecomposition
Return type:: SpectralDecomposition

property fiedler_value: float#

First non-trivial eigenvalue λ₁ (the Fiedler value).

Encodes global connectivity of the shape. Larger values indicate tighter geometry.

property k: int#: Alias for n_eigenvalues.

property n_eigenvalues: int#: Number of stored eigenpairs.

property n_vertices: int#: Number of vertices/points.

property shape_dna: ndarray[tuple[Any, ...], dtype[floating]]#

ShapeDNA — the raw eigenvalue sequence (excluding λ₀ ≈ 0).

Returns:: ndarray, shape (k-1,)

property shape_dna_normalized: ndarray[tuple[Any, ...], dtype[floating]]#

Area-normalised ShapeDNA.

Eigenvalues scaled by surface area so that shapes of different sizes are comparable.

Returns:: ndarray, shape (k-1,)
Raises:: ValueError – If surface_area is not set.

property spectral_gap: float#: Gap between λ₁ and λ₂.