spharapy.spharabasis: SPHARA Basis

SPHARA basis functions

This module provides a class for determining SPHARA basis functions. Methods are provided to determine basis functions using different discretization schemes of the Laplace-Beltrami operator, as FEM, inverse euclidean and unit.

class spharapy.spharabasis.SpharaBasis(triangsamples=None, mode='fem')

Bases: object

SPHARA basis functions class

This class can be used to determine SPHARA basis functions for spatially irregularly sampled functions whose topology is described by a triangular mesh.

Parameters:

• triangsamples (trimesh object) – A trimesh object from the package spharapy in which the triangulation of the spatial arrangement of the sampling points is stored. The SPHARA basis functions are determined for this triangulation of the sample points.

• mode ({'unit', 'inv_euclidean', 'fem'}, optional) – The discretization method used to estimate the Laplace-Beltrami operator. Using the option ‘unit’ all edges of the mesh are weighted by unit weighting function. The option ‘inv_euclidean’ results in edge weights corresponding to the inverse Euclidean distance of the edge lengths. The option ‘fem’ uses a FEM discretization. The default weighting function is ‘fem’.

triangsamples

Triangulation of the spatial arrangement of the sampling points

Type:

trimesh object

mode

Discretization used to estimate the Laplace-Beltrami operator

Type:

{‘unit’, ’inv_euclidean’, ’fem’}

basis()

Return the SPHARA basis for the triangulated sample points

This method determines a SPHARA basis for spatially distributed sampling points described by a triangular mesh. A discrete Laplace-Beltrami operator in matrix form is determined for the given triangular grid. The discretization method used to construct the Laplace-Beltrami operator is specified in the attribute mode.

In the FEM case (mode='fem'), a generalized symmetric definite eigenproblem

\(-\boldsymbol{S} \, \boldsymbol{\Phi} = \boldsymbol{\tau} \boldsymbol{B} \boldsymbol{\Phi}\)

is solved, where \(\boldsymbol{S}\) is the stiffness matrix, \(\boldsymbol{B}\) is the mass matrix, \(\boldsymbol{\Phi}\) is the matrix of eigenvectors and \(\boldsymbol{\tau}\) is a vector with the eigenvalues \(\tau_i \ge 0\). The columns of \(\boldsymbol{\Phi}\) form the SPHARA basis functions. For coordinates given in metric units (e.g., metres), the eigenvalues \(\tau_i\) act as squared spatial angular frequencies (squared wave numbers); spatial frequencies \(f_i\) and wavelengths \(\lambda_i\) follow from

\(\sqrt{\tau_i} = 2 \pi f_i = 2 \pi / \lambda_i\).

For the graph-based discretizations (mode='unit' or 'inv_euclidean'), the eigenvalues still provide a meaningful ordering from smooth (low “frequency”) to highly oscillatory basis functions, but they do not have a direct metric interpretation in terms of physical distances.

Returns:

• basis (array, shape (n_points, n_points)) – Matrix which contains the SPHARA basis functions column by column. The number of vertices of the triangular mesh is n_points.

• frequencies (array, shape (n_points,)) – Eigenvalues \(\tau_i\) of the discrete Laplace-Beltrami operator (or of the generalized FEM eigenproblem). In FEM mode they can be interpreted as squared spatial angular frequencies (squared wave numbers).

Examples

>>> from spharapy import trimesh as tm
>>> from spharapy import spharabasis as sb
>>> testtrimesh = tm.TriMesh([[0, 1, 2]], [[1., 0., 0.], [0., 2., 0.],
...                                        [0., 0., 3.]])
>>> sb_fem = sb.SpharaBasis(testtrimesh, mode='fem')
>>> sb_fem.basis()
(array([[ 0.53452248, -0.49487166,  1.42857143],
        [ 0.53452248, -0.98974332, -1.14285714],
        [ 0.53452248,  1.48461498, -0.28571429]]),
 array([  2.33627569e-16,   1.71428571e+00,   5.14285714e+00]))

eigenvalues()

Return eigenvalues of the discrete Laplace–Beltrami operator.

This is a convenience wrapper around basis() that returns only the eigenvalues associated with the SPHARA basis.

Returns:

eigenvalues – Eigenvalues \(\tau_i \ge 0\) of the discrete Laplace–Beltrami operator (or of the generalized FEM eigenproblem in mode='fem'), ordered from smallest (DC) to largest spatial variation.

Return type:

ndarray of shape (n_points,)

massmatrix()

Return the massmatrix

The method returns the mass matrix of the triangular mesh.

spatial_angular_frequencies()

Return spatial angular frequencies for FEM-based SPHARA basis.

For FEM discretization (mode='fem') and coordinates in a consistent metric unit (e.g., metres), the eigenvalues \(\tau_i\) of the Laplace–Beltrami operator behave like squared spatial angular frequencies (squared wave numbers). This method returns

\[\omega_i = \sqrt{\tau_i}.\]

For non-FEM modes the eigenvalues do not have a direct metric interpretation. In this case a RuntimeError is raised.

Returns:

omega – Spatial angular frequencies \(\omega_i = \sqrt{\tau_i}\).

Return type:

ndarray of shape (n_points,)

Raises:

RuntimeError – If mode is not 'fem'.

spatial_frequencies()

Return spatial frequencies for FEM-based SPHARA basis.

For FEM discretization (mode='fem'), the spatial frequencies \(f_i\) corresponding to the eigenvalues \(\tau_i\) are given by

\[f_i = \omega_i / (2 \pi) = \sqrt{\tau_i} / (2 \pi).\]

For non-FEM modes the eigenvalues are unitless and have no direct metric interpretation. In this case a RuntimeError is raised.

Returns:

frequencies – Spatial frequencies \(f_i\) (in inverse length units, e.g. 1/m if the coordinates are given in metres).

Return type:

ndarray of shape (n_points,)

Raises:

RuntimeError – If mode is not 'fem'.

spatial_wavelengths()

Return spatial wavelengths for FEM-based SPHARA basis.

For FEM discretization (mode='fem'), the spatial wavelengths \(\lambda_i\) corresponding to the eigenvalues \(\tau_i\) are defined by

\[\lambda_i = 2 \pi / \sqrt{\tau_i} = 1 / f_i.\]

The DC component (zero eigenvalue) is assigned an infinite wavelength.

Returns:

wavelengths – Spatial wavelengths \(\lambda_i\). The DC component receives np.inf.

Return type:

ndarray of shape (n_points,)

Raises:

RuntimeError – If mode is not 'fem'.