lapy.heat

Functions for computing heat kernel and diffusion.

Inputs are eigenvalues and eigenvectors (for heat kernel) and the mesh geometries (tet or tria mesh) for heat diffusion.

lapy.heat.diagonal(t, x, evecs, evals, n)[source]

Compute heat kernel diagonal K(t,x,x).

For a given time t (can be a vector) using only the first n smallest eigenvalues and eigenvectors.

Parameters:
tfloat or np.ndarray

Time or array of time values, shape (n_times,).

xnp.ndarray

Vertex indices for the positions of K(t,x,x), shape (n_vertices,).

evecsnp.ndarray

Eigenvectors matrix, shape (n_vertices, n_eigenvectors).

evalsnp.ndarray

Vector of eigenvalues, shape (n_eigenvalues,).

nint

Number of eigenvectors and eigenvalues to use (smaller or equal to length).

Returns:
np.ndarray

Heat kernel diagonal values. Shape (n_vertices, n_times) if t is array, or (n_vertices, 1) if t is scalar. Rows correspond to vertices selected in x, columns to times in t.

Raises:
ValueError

If n exceeds the number of available eigenpairs.

Parameters:
Return type:

ndarray

lapy.heat.diffusion(geometry, vids, m=1.0, aniso=None, use_cholmod=False)[source]

Compute the heat diffusion from initial vertices in vids.

Uses the backward Euler solution with time \(t = m l^2\), where l describes the average edge length.

Parameters:
geometryTriaMesh or TetMesh

Geometric object on which to run diffusion.

vidsint or array_like

Vertex index or indices where initial heat is applied.

The nesting level determines whether one or multiple seed sets are computed:

  • Single seed set — an int, a 1-D np.ndarray, or a plain list[int]: heat is seeded at those vertices and a 1-D result array of shape (n_vertices,) is returned.

  • Multiple seed sets — a list[list[int]] or a list[np.ndarray]: each inner sequence defines one independent seed set. The heat matrix is factorised only once and reused for all sets. A 2-D array of shape (n_vertices, n_cases) is returned, where column k corresponds to vids[k].

Note

The direct output of boundary_loops() is a list[list[int]] and therefore treated as multiple seed sets (one diffusion per boundary loop). To compute the distance from all boundary vertices at once, concatenate the loops first:

loops = tria.boundary_loops()
all_bnd = np.concatenate(loops)
vfunc = diffusion(tria, all_bnd)
mfloat, default=1.0

Factor to compute time of heat evolution.

anisoint, default=None

Number of smoothing iterations for curvature computation on vertices.

use_cholmodbool, default=False

Which solver to use. If True, use Cholesky decomposition from scikit-sparse cholmod. If False, use spsolve (LU decomposition).

Returns:
np.ndarray

Heat diffusion values at vertices. Shape (n_vertices,) for a single seed set, or (n_vertices, n_cases) for multiple seed sets.

Raises:
ValueError

If vids contains out-of-range vertex indices.

ImportError

If use_cholmod is True but scikit-sparse is not installed.

Parameters:
Return type:

ndarray

lapy.heat.kernel(t, vfix, evecs, evals, n)[source]

Compute heat kernel from all points to a fixed point.

For a given time t, computes K_t(p,q) using only the first n smallest eigenvalues and eigenvectors:

\[K_t (p,q) = \sum_j \exp(-\lambda_j t) \phi_j(p) \phi_j(q)\]

where \(\lambda_j\) are eigenvalues and \(\phi_j\) are eigenvectors.

Parameters:
tfloat or np.ndarray

Time (can also be array, if passing multiple times), shape (n_times,).

vfixint

Fixed vertex index.

evecsnp.ndarray

Matrix of eigenvectors, shape (n_vertices, n_eigenvectors).

evalsnp.ndarray

Column vector of eigenvalues, shape (n_eigenvalues,).

nint

Number of eigenvalues/vectors used in heat kernel (n <= n_eigenvectors).

Returns:
np.ndarray

Heat kernel values. Shape (n_vertices, n_times) if t is array, or (n_vertices, 1) if t is scalar. Rows correspond to all vertices, columns to times in t.

Raises:
ValueError

If n exceeds the number of available eigenpairs.

Parameters:
Return type:

ndarray