API Reference

neuromodes.eigen - Compute eigenmodes on cortical surface meshes

Module for computing geometric eigenmodes on cortical surface meshes and decomposing/reconstructing cortical maps.

EigenSolver(surf[, mask, normalize, hetero, ...])

EigenSolver class for spectral analysis and simulation on surface meshes.

class neuromodes.eigen.EigenSolver(surf: str | Path | Trimesh | TriaMesh | dict, mask: ArrayLike | None = None, normalize: bool = False, hetero: ArrayLike | None = None, alpha: float | None = None, scaling: str | None = None)

Bases: Solver

EigenSolver class for spectral analysis and simulation on surface meshes.

This class computes the Laplace-Beltrami operator (LBO) [1] on a triangular mesh via the Finite Element Method [2][3], which discretizes the eigenvalue problem according to mass and stiffness matrices. It also provides an option to incorporate spatial heterogeneity via the generalised LBO [4].

Parameters

surfstr, pathlib.Path, trimesh.Trimesh, lapy.TriaMesh, or dict

The surface mesh to be used. Can be a file path to a supported format (see io.read_surf), a supported mesh object, or a dictionary with ‘vertices’ and ‘faces’ keys.

maskarray-like, optional

A boolean mask to exclude certain points (e.g., medial wall) from the surface mesh. Vertices labelled as False in the mask will be excluded. Default is None.

normalizebool, optional

Whether to normalize the surface mesh to have unit surface area and centroid at the origin (modifies the vertices). Default is False.

heteroarray-like, optional

A heterogeneity map to scale the Laplace-Beltrami operator. Default is None.

alphafloat, optional

Scaling parameter for the heterogeneity map. If a heterogenity map is specified, the default is 1.0. Otherwise, this value is ignored (and is set to None).

scalingstr, optional

Scaling function to apply to the heterogeneity map. Must be ‘sigmoid’ or ‘exponential’. If a heterogenity map is specified, the default is ‘sigmoid’. Otherwise, this value is ignored (and is set to None).

Raises

ValueError

If hetero length does not match the number of vertices (masked or unmasked).

ValueError

If scaling is not ‘sigmoid’ or ‘exponential’ (raised by scale_hetero).

ValueError

If hetero is constant (raised by scale_hetero).

References

[1]

Pang, J. C., et al. (2023). Geometric constraints on human brain function. Nature. https://doi.org/10.1038/s41586-023-06098-1

[2]

Reuter, M., et al. (2006). Laplace-Beltrami spectra as ‘Shape-DNA’ of surfaces and solids, Computer-Aided Design. https://doi.org/10.1016/j.cad.2005.10.011

[3]

Wachinger, C., et al. (2015). BrainPrint: a discriminative characterization of brain morphology, Neuroimage. https://doi.org/10.1016/j.neuroimage.2015.01.032

[4]

Barnes, V., et al. (2026). Regional heterogeneity shapes macroscopic wave dynamics of the human and non-human primate cortex. bioRxiv. https://doi.org/10.64898/2026.01.22.701178

compute_lbo(lump: bool = False) → EigenSolver

This method computes the Laplace-Beltrami operator using finite element methods on a triangular mesh, optionally incorporating spatial heterogeneity and smoothing of the curvature. The resulting stiffness and mass matrices are stored as attributes.

Parameters

lumpbool, optional

Whether to use lumped mass matrix for the Laplace-Beltrami operator. Default is False.

Returns

EigenSolver

The EigenSolver instance.

decompose(data: ArrayLike, **kwargs) → NDArray

This is a wrapper for neuromodes.basis.decompose, see its documentation for details: https://neuromodes.readthedocs.io/en/latest/generated/nsbtools.basis.decompose.html

Note that emodes, mass, and check_ortho are passed automatically by the EigenSolver instance.

model_connectome(**kwargs) → NDArray

This is a wrapper for neuromodes.connectome.model_connectome, see its documentation for details: https://neuromodes.readthedocs.io/en/latest/generated/nsbtools.connectome.model_connectome.html

Note that emodes and evals are passed automatically by the EigenSolver instance.

reconstruct(data: ArrayLike, **kwargs) → Tuple[NDArray, NDArray, list[NDArray]]

This is a wrapper for neuromodes.basis.reconstruct, see its documentation for details: https://neuromodes.readthedocs.io/en/latest/generated/nsbtools.basis.reconstruct.html

Note that emodes, mass, and check_ortho are passed automatically by the EigenSolver instance.

reconstruct_timeseries(data: ArrayLike, **kwargs) → Tuple[NDArray, NDArray, NDArray, NDArray, list[NDArray]]

This is a wrapper for neuromodes.basis.reconstruct_timeseries, see its documentation for details: https://neuromodes.readthedocs.io/en/latest/generated/nsbtools.basis.reconstruct_timeseries.html

Note that emodes, mass, and check_ortho are passed automatically by the EigenSolver instance.

simulate_waves(**kwargs) → NDArray

This is a wrapper for neuromodes.waves.simulate_waves, see its documentation for details: https://neuromodes.readthedocs.io/en/latest/generated/nsbtools.waves.simulate_waves.html

Note that emodes, evals, mass, scaled_hetero, and check_ortho are passed automatically by the EigenSolver instance.

solve(n_modes: int, standardize: bool = True, fix_mode1: bool = True, atol: float = 0.001, rtol: float = 1e-05, sigma: float | None = -0.01, seed: int | ArrayLike | None = None, lump: bool = False) → EigenSolver

Solves the generalized eigenvalue problem for the Laplace-Beltrami operator and compute eigenvalues and eigenmodes, which are stored as attributes (emodes and evals).

Parameters

n_modesint

Number of eigenmodes to compute.

standardizebool, optional

If True, standardizes the sign of the eigenmodes so the first element is positive. Default is False.

fix_mode1bool, optional

If True, sets the first eigenmode to a constant value and the first eigenvalue to zero, as is expected analytically. Default is True. See the is_orthonormal_basis function for details.

atolfloat, optional

Absolute tolerance for mass-orthonormality validation. Default is 1e-3.

rtolfloat, optional

Relative tolerance for mass-orthonormality validation. Default is 1e-5.

sigmafloat, optional

Shift-invert parameter to speed up the computation of eigenvalues close to this value. Default is -0.01.

seedint or array-like, optional

Random seed for reproducibile generation of eigenvectors (which otherwise use an iterative algorithm that starts with a random vector, meaning that repeated generation of eigenmodes on the same surface can have different orientations). Specify as an int (to set the seed) or a vector with n_verts elements (to directly set the initialisation vector). Default is None (not reproducible).

lump: bool = False

Whether to use lumped mass matrix for the Laplace-Beltrami operator. Default is False.

Returns

EigenSolver

The EigenSolver instance.

Raises

ValueError

If n_modes is not a positive integer.

ValueError

If seed is an array but does not have shape (n_verts,).

AssertionError

If computed eigenvalues or eigenmodes contain NaNs.

neuromodes.eigen.EigenSolver.compute_lbo([lump])	This method computes the Laplace-Beltrami operator using finite element methods on a triangular mesh, optionally incorporating spatial heterogeneity and smoothing of the curvature.
neuromodes.eigen.EigenSolver.solve(n_modes)	Solves the generalized eigenvalue problem for the Laplace-Beltrami operator and compute eigenvalues and eigenmodes, which are stored as attributes (emodes and evals).
neuromodes.eigen.EigenSolver.decompose(data, ...)	This is a wrapper for neuromodes.basis.decompose, see its documentation for details: https://neuromodes.readthedocs.io/en/latest/generated/nsbtools.basis.decompose.html
neuromodes.eigen.EigenSolver.reconstruct(...)	This is a wrapper for neuromodes.basis.reconstruct, see its documentation for details: https://neuromodes.readthedocs.io/en/latest/generated/nsbtools.basis.reconstruct.html
neuromodes.eigen.EigenSolver.reconstruct_timeseries(...)	This is a wrapper for neuromodes.basis.reconstruct_timeseries, see its documentation for details: https://neuromodes.readthedocs.io/en/latest/generated/nsbtools.basis.reconstruct_timeseries.html
neuromodes.eigen.EigenSolver.simulate_waves(...)	This is a wrapper for neuromodes.waves.simulate_waves, see its documentation for details: https://neuromodes.readthedocs.io/en/latest/generated/nsbtools.waves.simulate_waves.html
neuromodes.eigen.EigenSolver.model_connectome(...)	This is a wrapper for neuromodes.connectome.model_connectome, see its documentation for details: https://neuromodes.readthedocs.io/en/latest/generated/nsbtools.connectome.model_connectome.html

neuromodes.eigen.scale_hetero(hetero[, ...])	Scales a heterogeneity map using specified normalization and scaling functions.
neuromodes.eigen.standardize_modes(emodes)	Flips the modes' signs such that the first element of each eigenmode has positive amplitude.
neuromodes.eigen.is_orthonormal_basis(emodes)	Check if a set of vectors is orthonormal in Euclidean space (i.e., emodes.T @ emodes == I) or with respect to a mass matrix (i.e., emodes.T @ mass @ emodes == I), where I is the identity matrix.

neuromodes.basis - Decompose and reconstruct cortical maps

Module for expressing brain maps as linear combinations of orthogonal basis vectors.

neuromodes.basis.decompose(data, emodes[, ...])	Calculate the decomposition of the given data onto a basis set.
neuromodes.basis.reconstruct(data, emodes[, ...])	Calculate and score the reconstruction of the given independent data using the provided orthogonal vectors (e.g., geometric eigenmodes).
neuromodes.basis.reconstruct_timeseries(...)	Calculate and score the reconstruction of the given time-series data using the provided orthogonal vectors (e.g., geometric eigenmodes).
neuromodes.basis.calc_norm_power(beta)	Transform beta coefficients from a decomposition into normalised power.
neuromodes.basis.calc_vec_fc(timeseries)	Compute Fisher-z-transformed vectorized functional connectivity from timeseries data.

neuromodes.waves - Simulate activity via wave propagation

Module for using neural field theory to simulate neural activity and BOLD signals on cortical surfaces.

neuromodes.waves.simulate_waves(emodes, evals)	Simulate neural activity or BOLD signals on the surface mesh using the NFT wave equation [1][2] using homogeneous or heterogeneous modes [3].
neuromodes.waves.calc_wave_speed(r, gamma[, ...])	Calculate wave speed based on the two parameters of the wave model.
neuromodes.waves.get_balloon_params(**overrides)	Return balloon model parameters with optional overrides.

neuromodes.connectome - Generative modelling of the structural connectome

Module for generating models of cortical structural connectomes.

neuromodes.connectome.model_connectome(...)

Generate a vertex-wise structural connectivity matrix using the Geometric Eigenmode Model [1].

neuromodes.io - IO functions for cortical surface meshes and maps

Module for reading, validating, and manipulating surface meshes.

neuromodes.io.read_surf(surf)	Load and validate a surface mesh.
neuromodes.io.mask_surf(surf, mask)	Remove specified vertices and corresponding faces from the surface mesh.
neuromodes.io.check_surf(surf)	Check if the surface mesh is contiguous with no unreferenced vertices.
neuromodes.io.fetch_surf([species, density, ...])	Load a cortical triangular surface mesh and medial wall mask from neuromodes data directory.
neuromodes.io.fetch_map(data[, species, ...])	Load cortical surface data from neuromodes data directory.