geometric_kernels.spaces.eigenfunctions

This module provides base classes for storing or evaluating eigenfunctions of the Laplacian, or certain combinations thereof (see the note below).

Note

Sometimes, when relations analogous to the addition theorem on the sphere are available, it is much more efficient to use certain sums of outer products of eigenfunctions instead of the eigenfunctions themselves. For this, we offer EigenfunctionsWithAdditionTheorem. Importantly, it is permitted to _only_ provide the computational routines for these “certain sums”, lacking the actual capability to compute the eigenfunctions themselves. This is important because for compact Lie groups, for example, computing eigenfunctions is more involved and less efficient than computing the “certain sums”, called characters in this case. This is also relevant for hyperspheres of higher dimension: in this case, the eigenfunctions (spherical harmonics) are much more cumbersome than the “certain sums” (zonal spherical harmonics).

Module Contents

class geometric_kernels.spaces.eigenfunctions.Eigenfunctions[source]

Bases: abc.ABC

Abstract base class providing an interface for working with eigenfunctions.

We denote the basis of eigenfunctions represented by an instance of this class by \([f_j]_{j=0}^{J-1}\). We assume it to be partitioned into levels (see MaternKarhunenLoeveKernel on how they are used). Specifically, we call the sets \([f_{l s}]_{s=1}^{d_l}\) levels if

\[[f_j]_{j=0}^{J-1} = \bigcup_{l=0}^{L-1}[f_{l s}]_{s=1}^{d_l}\]

such that all the eigenfunctions \(f_{l s}\) with the same index \(l\) correspond to the same eigenvalue \(\lambda_l\). Note, however, that \(\lambda_l\) are not required to be unique: it is possible that for some \(l,l'\), \(\lambda_l = \lambda_{l'}\).

Note

There is often more than one way to choose a partition into levels. Trivially, you can always correspond a level to each individual eigenfunction. Alternatively, you can partition \([f_j]_{j=0}^{J-1}\) into the maximal subsets corresponding to the same eigenvalue (into the full eigenspaces). There are also often plenty of possibilities in between these two extremes.

Importantly, subclasses of this class do not necessarily have to allow computing the individual eigenfunctions (i.e. implement the method __call__()). The only methods that subclasses have to implement are phi_product() and its close relative phi_product_diag(). These output the sums of outer products of eigenfunctions for all levels:

\[\sum_{s=1}^{d_l} f_{l s}(x_1) f_{l s}(x_2)\]

for all \(0 \leq l < L\), and all pairs \(x_1\), \(x_2\) provided as inputs.

property num_eigenfunctions: int[source]

The number J of eigenfunctions.

Return type:

int

property num_levels: int[source]

The number L of levels.

Return type:

int

abstract __call__(X, **kwargs)[source]

Evaluate the individual eigenfunctions at a batch of input locations.

Parameters:

  • X (lab.Numeric) – Points to evaluate the eigenfunctions at, an array of shape [N, <axis>], where N is the number of points and <axis> is the shape of the arrays that represent the points in a given space.

  • **kwargs – Any additional parameters.

Returns:

An [N, J]-shaped array, where J is the number of eigenfunctions.

Return type:

lab.Numeric

abstract num_eigenfunctions_per_level()[source]

The number of eigenfunctions per level: list of \(d_l\), \(0 \leq l < L\).

Return type:

beartype.typing.List[int]

abstract phi_product(X, X2=None, **kwargs)[source]

Computes the

\[\sum_{s=1}^{d_l} f_{l s}(x_1) f_{l s}(x_2)\]

for all \(x_1\) in X, all \(x_2\) in X2, and \(0 \leq l < L\).

Parameters:

  • X (lab.Numeric) – The first of the two batches of points to evaluate the phi product at. An array of shape [N, <axis>], where N is the number of points and <axis> is the shape of the arrays that represent the points in a given space.

  • X2 (beartype.typing.Optional[lab.Numeric]) –

    The second of the two batches of points to evaluate the phi product at. An array of shape [N2, <axis>], where N2 is the number of points and <axis> is the shape of the arrays that represent the points in a given space.

    Defaults to None, in which case X is used for X2.

  • **kwargs – Any additional parameters.

Returns:

An array of shape [N, N2, L].

Return type:

lab.Numeric

abstract phi_product_diag(X, **kwargs)[source]

Computes the diagonals of the matrices phi_product(X, X, **kwargs)[:, :, l], \(0 \leq l < L\).

Parameters:
Returns:

An array of shape [N, L].

weighted_outerproduct(weights, X, X2=None, **kwargs)[source]

Computes

\[\sum_{l=0}^{L-1} w_l \sum_{s=1}^{d_l} f_{l s}(x_1) f_{l s}(x_2).\]

for all \(x_1\) in X and all \(x_2\) in X2, where \(w_l\) are weights.

Parameters:

  • weights (lab.Numeric) – An array of shape [L, 1] where L is the number of levels.

  • X (lab.Numeric) – The first of the two batches of points to evaluate the weighted outer product at. An array of shape [N, <axis>], where N is the number of points and <axis> is the shape of the arrays that represent the points in a given space.

  • X2 (beartype.typing.Optional[lab.Numeric]) –

    The second of the two batches of points to evaluate the weighted outer product at. An array of shape [N2, <axis>], where N2 is the number of points and <axis> is the shape of the arrays that represent the points in a given space.

    Defaults to None, in which case X is used for X2.

  • **kwargs – Any additional parameters.

Returns:

An array of shape [N, N2].

Return type:

lab.Numeric

weighted_outerproduct_diag(weights, X, **kwargs)[source]

Computes the diagonal of the matrix weighted_outerproduct(weights, X, X, **kwargs).

Parameters:
Returns:

An array of shape [N,].

Return type:

lab.Numeric

class geometric_kernels.spaces.eigenfunctions.EigenfunctionsFromEigenvectors(eigenvectors)[source]

Bases: Eigenfunctions

Turns an array of eigenvectors into an Eigenfunctions instance. The resulting eigenfunctions’ inputs are given by the indices.

Each individual eigenfunction corresponds to a separate level.

Parameters:

eigenvectors (lab.Numeric) – Array of shape [D, J] containing J eigenvectors of dimension D.

property num_eigenfunctions: int[source]

The number J of eigenfunctions.

Return type:

int

property num_eigenfunctions_per_level: beartype.typing.List[int][source]

Number of eigenfunctions per level.

Returns a list of J ones.

Return type:

beartype.typing.List[int]

property num_levels: int[source]

Number of levels.

Returns J, same as num_eigenfunctions().

Return type:

int

__call__(X, **kwargs)[source]

Takes the values of the J stored eigenvectors self.eigenvectors that correspond to the indices in X.

Parameters:

  • X (lab.Numeric) – Indices, an array of shape [N, 1].

  • **kwargs – Ignored.

Returns:

An array of shape [N, J], whose element with index (n, j) corresponds to the X[n]-th element of the j-th eigenvector.

Return type:

lab.Numeric

phi_product(X, X2=None, **kwargs)[source]

Computes the

\[\sum_{s=1}^{d_l} f_{l s}(x_1) f_{l s}(x_2)\]

for all \(x_1\) in X, all \(x_2\) in X2, and \(0 \leq l < L\).

Parameters:

  • X (lab.Numeric) – The first of the two batches of points to evaluate the phi product at. An array of shape [N, <axis>], where N is the number of points and <axis> is the shape of the arrays that represent the points in a given space.

  • X2 (beartype.typing.Optional[lab.Numeric]) –

    The second of the two batches of points to evaluate the phi product at. An array of shape [N2, <axis>], where N2 is the number of points and <axis> is the shape of the arrays that represent the points in a given space.

    Defaults to None, in which case X is used for X2.

  • **kwargs – Any additional parameters.

Returns:

An array of shape [N, N2, L].

Return type:

lab.Numeric

phi_product_diag(X, **kwargs)[source]

Computes the diagonals of the matrices phi_product(X, X, **kwargs)[:, :, l], \(0 \leq l < L\).

Parameters:
Returns:

An array of shape [N, L].

weighted_outerproduct(weights, X, X2=None, **kwargs)[source]

Computes

\[\sum_{l=0}^{L-1} w_l \sum_{s=1}^{d_l} f_{l s}(x_1) f_{l s}(x_2).\]

for all \(x_1\) in X and all \(x_2\) in X2, where \(w_l\) are weights.

Parameters:

  • weights (lab.Numeric) – An array of shape [L, 1] where L is the number of levels.

  • X (lab.Numeric) – The first of the two batches of points to evaluate the weighted outer product at. An array of shape [N, <axis>], where N is the number of points and <axis> is the shape of the arrays that represent the points in a given space.

  • X2 (beartype.typing.Optional[lab.Numeric]) –

    The second of the two batches of points to evaluate the weighted outer product at. An array of shape [N2, <axis>], where N2 is the number of points and <axis> is the shape of the arrays that represent the points in a given space.

    Defaults to None, in which case X is used for X2.

  • **kwargs – Any additional parameters.

Returns:

An array of shape [N, N2].

Return type:

lab.Numeric

weighted_outerproduct_diag(weights, X, **kwargs)[source]

Computes the diagonal of the matrix weighted_outerproduct(weights, X, X, **kwargs).

Parameters:
Returns:

An array of shape [N,].

Return type:

lab.Numeric

class geometric_kernels.spaces.eigenfunctions.EigenfunctionsWithAdditionTheorem[source]

Bases: Eigenfunctions

Eigenfunctions for which the sum of outer products over a level has a simpler expression.

Note

See a brief introduction into the notion of addition theorems in the respective documentation page.

phi_product(X, X2=None, **kwargs)[source]

Computes the

\[\sum_{s=1}^{d_l} f_{l s}(x_1) f_{l s}(x_2)\]

for all \(x_1\) in X, all \(x_2\) in X2, and \(0 \leq l < L\).

Parameters:

  • X (lab.Numeric) – The first of the two batches of points to evaluate the phi product at. An array of shape [N, <axis>], where N is the number of points and <axis> is the shape of the arrays that represent the points in a given space.

  • X2 (beartype.typing.Optional[lab.Numeric]) –

    The second of the two batches of points to evaluate the phi product at. An array of shape [N2, <axis>], where N2 is the number of points and <axis> is the shape of the arrays that represent the points in a given space.

    Defaults to None, in which case X is used for X2.

  • **kwargs – Any additional parameters.

Returns:

An array of shape [N, N2, L].

Return type:

lab.Numeric

phi_product_diag(X, **kwargs)[source]

Computes the diagonals of the matrices phi_product(X, X, **kwargs)[:, :, l], \(0 \leq l < L\).

Parameters:
Returns:

An array of shape [N, L].

Return type:

lab.Numeric