geometric_kernels.spaces.hypersphere

This module provides the Hypersphere space and the respective Eigenfunctions subclass SphericalHarmonics.

Module Contents

class geometric_kernels.spaces.hypersphere.Hypersphere(dim)

Bases: geometric_kernels.spaces.base.DiscreteSpectrumSpace, geomstats.geometry.hypersphere.Hypersphere

The GeometricKernels space representing the d-dimensional hypersphere \(\mathbb{S}_d\) embedded in the (d+1)-dimensional Euclidean space.

The elements of this space are represented by (d+1)-dimensional vectors of unit norm.

Levels are the whole eigenspaces.

Note

We only support d >= 2. For d = 1, use Circle.

Note

A tutorial on how to use this space is available in the Hypersphere.ipynb notebook.

Parameters:

dim (int) – Dimension of the hypersphere \(\mathbb{S}_d\). Should satisfy dim >= 2. For dim = 1, use Circle.

Citation

If you use this GeometricKernels space in your research, please consider citing Borovitskiy et al. [2020].

property dimension: int

Returns d, the dim parameter that was passed down to __init__.

Return type:

int

property element_shape

Returns:

[d+1].

ehess2rhess(x, egrad, ehess, direction)

Riemannian Hessian along a given direction from the Euclidean Hessian.

Used to test that the heat kernel does indeed solve the heat equation.

Parameters:

• x (lab.NPNumeric) – A point on the d-dimensional hypersphere.

• egrad (lab.NPNumeric) – Euclidean gradient of a function defined in a neighborhood of the hypersphere, evaluated at the point x.

• ehess (lab.NPNumeric) – Euclidean Hessian of a function defined in a neighborhood of the hypersphere, evaluated at the point x.

• direction (lab.NPNumeric) – Direction to evaluate the Riemannian Hessian at. A tangent vector at x.

Returns:

A [dim]-shaped array that contains Hess_f(x)[direction], the value of the Riemannian Hessian of the function evaluated at x along the direction.

Return type:

lab.NPNumeric

See Absil et al. [2008] for mathematical details.

get_eigenfunctions(num)

Returns the SphericalHarmonics object with num levels.

Parameters:

num (int) – Number of levels.

Return type:

geometric_kernels.spaces.eigenfunctions.Eigenfunctions

get_eigenvalues(num)

Eigenvalues of the Laplacian corresponding to the first num levels.

Parameters:

num (int) – Number of levels.

Returns:

(num, 1)-shaped array containing the eigenvalues.

Return type:

lab.Numeric

Note

The notion of levels is discussed in the documentation of the MaternKarhunenLoeveKernel.

get_repeated_eigenvalues(num)

Eigenvalues of the Laplacian corresponding to the first num levels, repeated according to their multiplicity within levels.

Parameters:

num (int) – Number of levels.

Returns:

(J, 1)-shaped array containing the repeated eigenvalues, J is the resulting number of the repeated eigenvalues.

Return type:

lab.Numeric

Note

The notion of levels is discussed in the documentation of the MaternKarhunenLoeveKernel.

random(key, number)

Sample uniformly random points on the hypersphere.

Always returns [N, D+1] float64 array of the key’s backend.

Parameters:

• key (lab.RandomState) – Either np.random.RandomState, tf.random.Generator, torch.Generator or jax.tensor (representing random state).

• number (int) – Number of samples to draw.

Returns:

An array of number uniformly random samples on the space.

Return type:

lab.Numeric

class geometric_kernels.spaces.hypersphere.SphericalHarmonics(dim, num_levels)

Bases: geometric_kernels.spaces.eigenfunctions.EigenfunctionsWithAdditionTheorem

Eigenfunctions Laplace-Beltrami operator on the hypersphere correspond to the spherical harmonics.

Levels are the whole eigenspaces.

Parameters:

• dim (int) –

  Dimension of the hypersphere.

  E.g. dim = 2 means the standard 2-dimensional sphere in \(\mathbb{R}^3\). We only support dim >= 2. For dim = 1, use Circle.

• num_levels (int) – Specifies the number of levels of the spherical harmonics.

property num_eigenfunctions: int

The number J of eigenfunctions.

Return type:

int

property num_eigenfunctions_per_level: beartype.typing.List[int]

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

Return type:

beartype.typing.List[int]

property num_levels: int

The number L of levels.

Return type:

int

__call__(X, **parameters)

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