geometric_kernels.spaces¶

Various spaces supported by the library as input domains for kernels.

Submodules¶

Package Contents¶

class geometric_kernels.spaces.Circle[source]¶

Bases: geometric_kernels.spaces.base.DiscreteSpectrumSpace

The GeometricKernels space representing the standard unit circle, denoted by \(\mathbb{S}_1\) (as the one-dimensional hypersphere) or \(\mathbb{T}\) (as the one-dimensional torus).

The elements of this space are represented by angles, scalars from \(0\) to \(2 \pi\).

Levels are the whole eigenspaces. The zeroth eigenspace is one-dimensional, all the other eigenspaces are of dimension 2.

Note

The example notebook on the torus involves this space.

Citation

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

get_eigenfunctions(num)[source]¶

Returns the SinCosEigenfunctions object with num levels.

Parameters:: num (int) – Number of levels.
Return type:: geometric_kernels.spaces.eigenfunctions.Eigenfunctions

get_eigenvalues(num)[source]¶

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)[source]¶

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)[source]¶

Sample uniformly random points in the space.

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.

property dimension: int¶

Returns:

Return type:

int

property element_dtype¶

Returns:: B.Float.

property element_shape¶

Returns:: [1].

class geometric_kernels.spaces.CompactMatrixLieGroup[source]¶

Bases: geometric_kernels.spaces.base.DiscreteSpectrumSpace

A base class for compact Lie groups of matrices, subgroups of the real or complex general linear group GL(n), n being some integer.

The group operation is the standard matrix multiplication, and the group inverse is the standard matrix inverse. Despite this, we make the subclasses implement their own inverse routine, because in special cases it can typically be implemented much more efficiently. For example, for the special orthogonal group SpecialOrthogonal, the inverse is equivalent to a simple transposition.

static inverse(X)[source]¶

Abstractmethod:
Parameters:: X (lab.Numeric)
Return type:: lab.Numeric

Inverse of a batch X of the elements of the group. A static method.

Parameters:: X (lab.Numeric) – A batch […, n, n] of elements of the group. Each element is a n x n matrix.
Returns:: A batch […, n, n] with each n x n matrix inverted.
Return type:: lab.Numeric

class geometric_kernels.spaces.DiscreteSpectrumSpace[source]¶

Bases: Space

A Space with discrete spectrum (of the Laplacian operator).

This includes, for instance, compact Riemannian manifolds, graphs & meshes.

Subclasses implement routines for computing the eigenvalues and eigenfunctions of the Laplacian operator, or certain combinations thereof. Since there is often an infinite or a prohibitively large number of those, they only compute a finite subset, consisting of the ones that are most important for approximating Matérn kernel best.

Note

See a brief introduction into the theory behind the geometric kernels on discrete spectrum spaces on the documentation pages devoted to compact Riemannian manifolds (also this), graphs and meshes.

Note

Typically used with MaternKarhunenLoeveKernel.

abstract dimension()¶

Geometric dimension of the space.

Examples:

Graph: 0-dimensional.
Circle: 1-dimensional.
Hypersphere: d-dimensional, with d >= 2.

Return type:: int

abstract get_eigenfunctions(num)[source]¶

Returns the Eigenfunctions object with num levels.

Parameters:: num (int) – Number of levels.
Return type:: geometric_kernels.spaces.eigenfunctions.Eigenfunctions

Note

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

abstract get_eigenvalues(num)[source]¶

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.

abstract get_repeated_eigenvalues(num)[source]¶

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.

abstract random(key, number)[source]¶

Sample uniformly random points in the space.

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.Graph(adjacency_matrix, normalize_laplacian=False)[source]¶

Bases: geometric_kernels.spaces.base.DiscreteSpectrumSpace

The GeometricKernels space representing the node set of any user-provided weighted undirected graph.

The elements of this space are represented by node indices, integer values from 0 to n-1, where n is the number of nodes in the user-provided graph.

Each individual eigenfunction constitutes a level.

Note

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

Parameters:

adjacency_matrix (lab.Numeric) –
An n-dimensional square, symmetric matrix, where adjacency_matrix[i, j] is non-zero if there is an edge between nodes i and j. SciPy’s sparse matrices are supported.

Warning

Make sure that the type of the adjacency_matrix is of the backend (NumPy (or SciPy) / JAX / TensorFlow, PyTorch) that you wish to use for internal computations.
normalize_laplacian (bool) –
If True, the graph Laplacian will be degree normalized (symmetrically): L_sym = D^-0.5 * L * D^-0.5.

Defaults to False.

Citation

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

get_eigenfunctions(num)[source]¶

Returns the EigenfunctionsFromEigenvectors object with num levels (i.e., in this case, num eigenpairs).

Parameters:: num (int) – Number of levels.
Return type:: geometric_kernels.spaces.eigenfunctions.Eigenfunctions

get_eigensystem(num)[source]¶

Returns the first num eigenvalues and eigenvectors of the graph Laplacian. Caches the solution to prevent re-computing the same values.

Note

If the adjacency_matrix was a sparse SciPy array, requesting all eigenpairs will lead to a conversion of the sparse matrix to a dense one due to scipy.sparse.linalg.eigsh limitations.

Parameters:: num – Number of eigenpairs to return. Performs the computation at the first call. Afterwards, fetches the result from cache.
Returns:: A tuple of eigenvectors [n, num], eigenvalues [num, 1].

get_eigenvalues(num)[source]¶

Parameters:: num (int) – Number of eigenvalues to return.
Returns:: Array of eigenvalues, with shape [num, 1].
Return type:: lab.Numeric

get_eigenvectors(num)[source]¶

Parameters:: num (int) – Number of eigenvectors to return.
Returns:: Array of eigenvectors, with shape [n, num].
Return type:: lab.Numeric

get_repeated_eigenvalues(num)[source]¶

Same as get_eigenvalues().

Parameters:: num (int) – Same as get_eigenvalues().
Return type:: lab.Numeric

random(key, number)[source]¶

Sample uniformly random points in the space.

Parameters:

key – Either np.random.RandomState, tf.random.Generator, torch.Generator or jax.tensor (representing random state).
number – Number of samples to draw.

Returns:

An array of number uniformly random samples on the space.

property dimension: int¶

Returns:

Return type:

int

property element_dtype¶

Returns:: B.Int.

property element_shape¶

Returns:: [1].

property num_vertices: int¶

Number of vertices in the graph.

Return type:: int

class geometric_kernels.spaces.Hyperbolic(dim=2)[source]¶

Bases: geometric_kernels.spaces.base.NoncompactSymmetricSpace, geomstats.geometry.hyperboloid.Hyperboloid

The GeometricKernels space representing the n-dimensional hyperbolic space \(\mathbb{H}_n\). We use the hyperboloid model of the hyperbolic space.

The elements of this space are represented by (n+1)-dimensional vectors satisfying

\[x_0^2 - x_1^2 - \ldots - x_n^2 = 1,\]

i.e. lying on the hyperboloid.

The class inherits the interface of geomstats’s Hyperbolic with point_type=extrinsic.

Note

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

Parameters:: dim – Dimension of the hyperbolic space, denoted by n in docstrings.

Note

As mentioned in this note, any symmetric space is a quotient G/H. For the hyperbolic space \(\mathbb{H}_n\), the group of symmetries \(G\) is the proper Lorentz group \(SO(1, n)\), while the isotropy subgroup \(H\) is the special orthogonal group \(SO(n)\). See the mathematical details in Azangulov et al. [2024].

Citation

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

convert_to_ball(point)[source]¶

Converts the point from the hyperboloid model to the Poincare model. This corresponds to a stereographic projection onto the ball.

Param:: An […, n+1]-shaped array of points on the hyperboloid.
Returns:: An […, n]-shaped array of points in the Poincare ball.

distance(x1, x2, diag=False)[source]¶

Calls hyperbolic_distance() on the same inputs.

Parameters:

x1 (lab.Numeric)
x2 (lab.Numeric)
diag (beartype.typing.Optional[bool])

Return type:

lab.Numeric

element_shape()[source]¶

Returns:: [n+1].

inner_product(vector_a, vector_b)[source]¶: Calls minkowski_inner_product() on vector_a and vector_b.

inv_harish_chandra(lam)[source]¶

Implements \(c^{-1}(\lambda)\), where \(c\) is the Harish-Chandra’s \(c\) function.

This is one of the computational primitives required to (approximately) compute the RandomPhaseFeatureMapNoncompact feature map and MaternFeatureMapKernel on top of it.

Parameters:: lam (lab.Numeric) – A batch of frequencies, vectors of dimension equal to the rank of symmetric space.
Returns:: \(c^{-1}(\lambda)\) evaluated at every \(\lambda\) in the batch lam.
Return type:: lab.Numeric

power_function(lam, g, h)[source]¶

Implements the power function \(p^{\lambda}(g, h)\), the integrand appearing in the definition of the zonal spherical function

\[\pi^{\lambda}(g) = \int_{H} \underbrace{p^{\lambda}(g, h)}_{= e^{(i \lambda + \rho) a(h \cdot g)}} d h,\]

where \(\lambda \in i \cdot \mathbb{R}^r\), with \(r\) denoting the rank of the symmetric space and \(i\) the imaginary unit, is a sort of frequency, \(g\) is an element of the group of symmetries \(G\), \(h\) is an element of its isotropy subgroup \(H\) (\(G\) and \(H\) are defined here), \(\rho \in \mathbb{R}^r\) is as in rho(), and the function \(a\) is a certain space-dependent algebraic operation.

This is one of the computational primitives required to (approximately) compute the RandomPhaseFeatureMapNoncompact feature map and MaternFeatureMapKernel on top of it.

Parameters:

lam (lab.Numeric) –
A batch of L vectors of dimension rank, the rank of the symmetric space, representing the “sort of frequencies”.

Typically of shape [1, L, rank].
g (lab.Numeric) –
A batch of N elements of the space (these can always be thought of as elements of the group of symmetries \(G\) since the symmetric space \(G/H\) can be trivially embedded into the group \(G\)).

Typically of shape [N, 1, <axes>], where <axes> is the shape of the elements of the space.
h (lab.Numeric) –
A batch of L elements of the isotropy subgroup \(H\).

Typically of shape [1, L, <axes_p>], where <axes_p> is the shape of arrays representing the elements of the isotropy subgroup \(H\).

Returns:

An array of shape [N, L] with complex number entries, representing the value of the values of \(p^{\lambda_l}(g_n, h_l)\) for all \(1 \leq n \leq N\) and \(1 \leq l \leq L\).

Return type:

lab.Numeric

Note

Actually, \(a\) may be a more appropriate primitive than the power function \(p^{\lambda}\): everything but \(a\) in the definition of the latter is either standard or available as other primitives. Us using \(p^{\lambda}\) as a primitive is quite arbitrary.

random(key, number)[source]¶

Non-uniform random sampling, reimplements the algorithm from geomstats.

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

Parameters:

key – Either np.random.RandomState, tf.random.Generator, torch.Generator or jax.tensor (representing random state).
number – Number of samples to draw.

Returns:

An array of number random samples on the space.

random_phases(key, num)[source]¶

Sample uniformly random points on the isotropy subgroup \(H\) (defined here).

This is one of the computational primitives required to (approximately) compute the RandomPhaseFeatureMapNoncompact feature map and MaternFeatureMapKernel on top of it.

Parameters:

key – Either np.random.RandomState, tf.random.Generator, torch.Generator or jax.tensor (representing random state).
num – Number of samples to draw.

Returns:

An array of num uniformly random samples in the isotropy subgroup \(H\).

Warning

This does not sample random points on the space itself. Since the space itself is non-compact, uniform sampling on it is in principle impossible. However, the isotropy subgroup \(H\) is always compact and thus allows uniform sampling needed to approximate the zonal spherical functions \(\pi^{\lambda}(\cdot)\) via Monte Carlo.

property dimension: int¶

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

Return type:: int

property element_dtype¶

Returns:: B.Float.

property num_axes¶

Number of axes in an array representing a point in the space.

Returns:

property rho¶

rho vector of dimension equal to the rank of the symmetric space.

Algebraically, weighted sum of roots, depends only on the space.

This is one of the computational primitives required to (approximately) compute the RandomPhaseFeatureMapNoncompact feature map and MaternFeatureMapKernel on top of it.

class geometric_kernels.spaces.HypercubeGraph(dim)[source]¶

Bases: geometric_kernels.spaces.base.DiscreteSpectrumSpace

The GeometricKernels space representing the d-dimensional hypercube graph \(C^d = \{0, 1\}^d\), the combinatorial space of binary vectors of length \(d\).

The elements of this space are represented by d-dimensional boolean vectors.

Levels are the whole eigenspaces.

Note

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

Note

Since the degree matrix is a constant multiple of the identity, all types of the graph Laplacian coincide on the hypercube graph up to a constant, we choose the normalized Laplacian for numerical stability.

Parameters:: dim (int) – Dimension \(d\) of the hypercube graph \(C^d\), a positive integer.

Citation

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

get_eigenfunctions(num)[source]¶

Returns the WalshFunctions object with num levels.

Parameters:: num (int) – Number of levels.
Return type:: geometric_kernels.spaces.eigenfunctions.Eigenfunctions

get_eigenvalues(num)[source]¶

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)[source]¶

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)[source]¶

Sample uniformly random points on the hypercube graph \(C^d\).

Always returns [N, D] boolean 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 N of samples to draw.

Returns:

An array of number uniformly random samples on the space.

Return type:

lab.Numeric

property dimension: int¶

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

Return type:: int

property element_dtype¶

Returns:: B.Bool.

property element_shape¶

Returns:: [d].

class geometric_kernels.spaces.Hypersphere(dim)[source]¶

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].

ehess2rhess(x, egrad, ehess, direction)[source]¶

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)[source]¶

Returns the SphericalHarmonics object with num levels.

Parameters:: num (int) – Number of levels.
Return type:: geometric_kernels.spaces.eigenfunctions.Eigenfunctions

get_eigenvalues(num)[source]¶

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)[source]¶

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)[source]¶

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 N of samples to draw.

Returns:

An array of number uniformly random samples on the space.

Return type:

lab.Numeric

property dimension: int¶

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

Return type:: int

property element_dtype¶

Returns:: B.Float.

property element_shape¶

Returns:: [d+1].

class geometric_kernels.spaces.Mesh(vertices, faces)[source]¶

Bases: geometric_kernels.spaces.base.DiscreteSpectrumSpace

The GeometricKernels space representing the node set of any user-provided mesh.

The elements of this space are represented by node indices, integer values from 0 to Nv-1, where Nv is the number of nodes in the user-provided mesh.

Each individual eigenfunction constitutes a level.

Note

We only support the commonly used 2-dimensional meshes (discrete counterparts of surfaces, 2-dimensional manifolds in a 3-dimensional ambient space).

Note

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

Note

We use potpourri3d to load meshes and mimic the interface of PyMesh.

Parameters:

vertices (numpy.ndarray) – A [Nv, 3] array of vertex coordinates, Nv is the number of vertices.
faces (numpy.ndarray) –
A [Nf, 3] array of vertex indices that represents a generalized array of faces, where Nf is the number of faces.

Citation

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

get_eigenfunctions(num)[source]¶

Returns the EigenfunctionsFromEigenvectors object with num levels (i.e., in this case, num eigenpairs).

Parameters:: num (int) – Number of levels.
Return type:: geometric_kernels.spaces.eigenfunctions.Eigenfunctions

get_eigensystem(num)[source]¶

Returns the first num eigenvalues and eigenvectors of the robust Laplacian. Caches the solution to prevent re-computing the same values.

Note

If the adjacency_matrix was a sparse SciPy array, requesting all eigenpairs will lead to a conversion of the sparse matrix to a dense one due to scipy.sparse.linalg.eigsh limitations.

Warning

Always uses SciPy (thus CPU) for internal computations. We will need to fix this in the future.

Parameters:: num (int) – Number of eigenpairs to return. Performs the computation at the first call. Afterwards, fetches the result from cache.
Returns:: A tuple of eigenvectors [nv, num], eigenvalues [num, 1].
Return type:: beartype.typing.Tuple[numpy.ndarray, numpy.ndarray]

get_eigenvalues(num)[source]¶

Parameters:: num (int) – Number of eigenvalues to return.
Returns:: Array of eigenvalues, with shape [num, 1].
Return type:: lab.Numeric

get_eigenvectors(num)[source]¶

Parameters:: num (int) – Number of eigenvectors to return.
Returns:: Array of eigenvectors, with shape [Nv, num].
Return type:: lab.Numeric

get_repeated_eigenvalues(num)[source]¶

Same as get_eigenvalues().

Parameters:: num (int) – Same as get_eigenvalues().
Return type:: lab.Numeric

classmethod load_mesh(filename)[source]¶

Construct Mesh by loading a mesh from the file at filename.

Parameters:: filename (str) – Path to read the file from. Supported formats: obj, ply, off, and stl. Format inferred automatically from the file extension.
Returns:: And object of class Mesh representing the loaded mesh.
Return type:: Mesh

random(key, number)[source]¶

Sample uniformly random points in the space.

Parameters:

key – Either np.random.RandomState, tf.random.Generator, torch.Generator or jax.tensor (representing random state).
number – Number of samples to draw.

Returns:

An array of number uniformly random samples on the space.

property dimension: int¶

Returns:

Return type:

int

property element_dtype¶

Returns:: B.Int.

property element_shape¶

Returns:: [1].

property faces: numpy.ndarray¶

A [Nf, 3] array of vertex indices that represents a generalized array of faces, where Nf is the number of faces.

Return type:: numpy.ndarray

property num_faces: int¶

Number of faces in the mesh, Nf.

Return type:: int

property num_vertices: int¶

Number of vertices in the mesh, Nv.

Return type:: int

property vertices: numpy.ndarray¶

A [Nv, 3] array of vertex coordinates, Nv is the number of vertices.

Return type:: numpy.ndarray

class geometric_kernels.spaces.NoncompactSymmetricSpace[source]¶

Bases: Space

Non-compact symmetric space.

This includes, for instance, hyperbolic spaces and manifolds of symmetric positive definite matrices (endowed with the affine-invariant metric).

Note

See a brief introduction into the theory behind the geometric kernels on non-compact symmetric spaces on the respective documentation page.

Note

Typically used with MaternFeatureMapKernel that builds on a space-specific feature map like the RejectionSamplingFeatureMapHyperbolic and the RejectionSamplingFeatureMapSPD, or, in the absence of a space-specific feature map, on the general (typically less effective) map RandomPhaseFeatureMapNoncompact.

Note

Mathematically, any non-compact symmetric space can be represented as a quotient \(G/H\) of a Lie group of symmetries \(G\) and its compact isotropy subgroup \(H\). We sometimes refer to these \(G\) and \(H\) in the documentation. See mathematical details in Azangulov et al. [2024].

abstract dimension()¶

Geometric dimension of the space.

Examples:

Hyperbolic: d-dimensional, with d >= 2.
SymmetricPositiveDefiniteMatrices: \(n(n+1)/2\)-dimensional,
with n >= 2.

Return type:: int

abstract inv_harish_chandra(lam)[source]¶

Implements \(c^{-1}(\lambda)\), where \(c\) is the Harish-Chandra’s \(c\) function.

This is one of the computational primitives required to (approximately) compute the RandomPhaseFeatureMapNoncompact feature map and MaternFeatureMapKernel on top of it.

Parameters:: lam (lab.Numeric) – A batch of frequencies, vectors of dimension equal to the rank of symmetric space.
Returns:: \(c^{-1}(\lambda)\) evaluated at every \(\lambda\) in the batch lam.
Return type:: lab.Numeric

abstract num_axes()¶

Number of axes in an array representing a point in the space.

Usually 1 for vectors or 2 for matrices.

abstract power_function(lam, g, h)[source]¶

Implements the power function \(p^{\lambda}(g, h)\), the integrand appearing in the definition of the zonal spherical function

\[\pi^{\lambda}(g) = \int_{H} \underbrace{p^{\lambda}(g, h)}_{= e^{(i \lambda + \rho) a(h \cdot g)}} d h,\]

This is one of the computational primitives required to (approximately) compute the RandomPhaseFeatureMapNoncompact feature map and MaternFeatureMapKernel on top of it.

Parameters:

lam (lab.Numeric) –
A batch of L vectors of dimension rank, the rank of the symmetric space, representing the “sort of frequencies”.

Typically of shape [1, L, rank].
g (lab.Numeric) –
A batch of N elements of the space (these can always be thought of as elements of the group of symmetries \(G\) since the symmetric space \(G/H\) can be trivially embedded into the group \(G\)).

Typically of shape [N, 1, <axes>], where <axes> is the shape of the elements of the space.
h (lab.Numeric) –
A batch of L elements of the isotropy subgroup \(H\).

Typically of shape [1, L, <axes_p>], where <axes_p> is the shape of arrays representing the elements of the isotropy subgroup \(H\).

Returns:

An array of shape [N, L] with complex number entries, representing the value of the values of \(p^{\lambda_l}(g_n, h_l)\) for all \(1 \leq n \leq N\) and \(1 \leq l \leq L\).

Return type:

lab.Numeric

Note

abstract random_phases(key, num)[source]¶

Sample uniformly random points on the isotropy subgroup \(H\) (defined here).

This is one of the computational primitives required to (approximately) compute the RandomPhaseFeatureMapNoncompact feature map and MaternFeatureMapKernel on top of it.

Parameters:

key (lab.RandomState) – Either np.random.RandomState, tf.random.Generator, torch.Generator or jax.tensor (representing random state).
num (int) – Number of samples to draw.

Returns:

An array of num uniformly random samples in the isotropy subgroup \(H\).

Return type:

lab.Numeric

Warning

abstract rho()¶

rho vector of dimension equal to the rank of the symmetric space.

Algebraically, weighted sum of roots, depends only on the space.

This is one of the computational primitives required to (approximately) compute the RandomPhaseFeatureMapNoncompact feature map and MaternFeatureMapKernel on top of it.

class geometric_kernels.spaces.ProductDiscreteSpectrumSpace(*spaces, num_levels=25, num_levels_per_space=None)[source]¶

Bases: geometric_kernels.spaces.base.DiscreteSpectrumSpace

The GeometricKernels space representing a product

\[\mathcal{S} = \mathcal{S}_1 \times \ldots \mathcal{S}_S\]

of DiscreteSpectrumSpace-s \(\mathcal{S}_i\).

Levels are indexed by tuples of levels of the factors.

Precomputing optimal levels

The eigenvalue corresponding to a level of the product space represented by a tuple \((j_1, .., j_S)\) is the sum

\[\lambda^{(1)}_{j_1} + \ldots + \lambda^{(S)}_{j_S}\]

of the eigenvalues \(\lambda^{(s)}_{j_s}\) of the factors.

Computing top num_levels smallest eigenvalues is thus a combinatorial problem, the solution to which we precompute. To make this precomputation possible you need to provide the num_levels parameter when constructing the ProductDiscreteSpectrumSpace, unlike for other spaces. What is more, the num parameter of the get_eigenfunctions() cannot be larger than the num_levels value.

Note

See this page for a brief account on theory behind product spaces and the Torus.ipynb notebook for a tutorial on how to use them.

An alternative to using ProductDiscreteSpectrumSpace is to use the ProductGeometricKernel kernel. The latter is more flexible, allowing more general spaces as factors and automatic relevance determination -like behavior.

Parameters:

spaces (geometric_kernels.spaces.base.DiscreteSpectrumSpace) – The factors, subclasses of DiscreteSpectrumSpace.
num_levels (int) – The number of levels to pre-compute for this product space.
num_levels_per_space (beartype.typing.Optional[int]) –
Number of levels to fetch for each of the factor spaces, to compute the product-space levels. This is a single number rather than a list, because we currently only support fetching the same number of levels for all the factor spaces.

If not given, num_levels levels will be fetched for each factor.

Citation

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

get_eigenfunctions(num)[source]¶

Returns the ProductEigenfunctions object with num levels.

Parameters:: num (int) – Number of levels. Cannot be larger than the num_levels parameter of the constructor.
Return type:: geometric_kernels.spaces.eigenfunctions.Eigenfunctions

get_eigenvalues(num)[source]¶

Eigenvalues of the Laplacian corresponding to the first num levels.

Parameters:: num (int) – Number of levels. Cannot be larger than the num_levels parameter of the constructor.
Returns:: (num, 1)-shaped array containing the eigenvalues.
Return type:: lab.Numeric

get_repeated_eigenvalues(num)[source]¶

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

Parameters:: num (int) – Number of levels. Cannot be larger than the num_levels parameter of the constructor.
Returns:: (J, 1)-shaped array containing the repeated eigenvalues,`J is the resulting number of the repeated eigenvalues.
Return type:: lab.Numeric

random(key, number)[source]¶

Sample random points on the product space by concatenating random points on the factor spaces via make_product().

Parameters:

key – Either np.random.RandomState, tf.random.Generator, torch.Generator or jax.tensor (representing random state).
number – Number of samples to draw.

Returns:

An array of number uniformly random samples on the space.

property dimension: int¶

Returns the dimension of the product space, equal to the sum of dimensions of the factors.

Return type:: int

property element_dtype¶

Returns:: B.Numeric.

property element_shape¶

Returns:: Sum of the products of the element shapes of the factor spaces.

class geometric_kernels.spaces.Space[source]¶

Bases: abc.ABC

A space (input domain) on which a geometric kernel can be defined.

abstract dimension()¶

Geometric dimension of the space.

Examples:

Graph: 0-dimensional.
Circle: 1-dimensional.
Hypersphere: d-dimensional, with d >= 2.
Hyperbolic: d-dimensional, with d >= 2.

Return type:: int

abstract element_dtype()¶

Abstract DType of an element.

Examples: * Hypersphere: B.Float * Mesh: B.Int * SpecialUnitary: B.Complex

Return type:: lab.DType

abstract element_shape()¶

Shape of an element.

Examples: * Hypersphere: [D + 1, ] * Mesh: [1, ] * CompactMatrixLieGroup: [n, n]

Return type:: beartype.typing.List[int]

class geometric_kernels.spaces.SpecialOrthogonal(n)[source]¶

Bases: geometric_kernels.spaces.lie_groups.CompactMatrixLieGroup

The GeometricKernels space representing the special orthogonal group SO(n) consisting of n by n orthogonal matrices with unit determinant.

The elements of this space are represented as n x n orthogonal matrices with real entries and unit determinant.

Note

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

Parameters:: n (int) – The order n of the group SO(n).

Note

We only support n >= 3. Mathematically, SO(2) is equivalent to the unit circle, which is available as the Circle space.

For larger values of n, you might need to run the utils/compute_characters.py script to precompute the necessary mathematical quantities beyond the ones provided by default. Same can be required for larger numbers of levels.

Citation

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

get_eigenfunctions(num)[source]¶

Returns the SOEigenfunctions object with num levels and order n.

Parameters:: num (int) – Number of levels.
Return type:: geometric_kernels.spaces.eigenfunctions.Eigenfunctions

get_eigenvalues(num)[source]¶

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)[source]¶

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.

static inverse(X)[source]¶

Inverse of a batch X of the elements of the group. A static method.

Parameters:: X (lab.Numeric) – A batch […, n, n] of elements of the group. Each element is a n x n matrix.
Returns:: A batch […, n, n] with each n x n matrix inverted.
Return type:: lab.Numeric

random(key, number)[source]¶

Sample uniformly random points in the space.

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.

property dimension: int¶

The dimension of the space, as that of a Riemannian manifold.

Returns:: floor(n(n-1)/2) where n is the order of the group SO(n).
Return type:: int

property element_dtype¶

Returns:: B.Float.

property element_shape¶

Returns:: [n, n].

class geometric_kernels.spaces.SpecialUnitary(n)[source]¶

Bases: geometric_kernels.spaces.lie_groups.CompactMatrixLieGroup

The GeometricKernels space representing the special unitary group SU(n) consisting of n by n complex unitary matrices with unit determinant.

The elements of this space are represented as n x n unitary matrices with complex entries and unit determinant.

Note

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

Parameters:: n (int) – The order n of the group SU(n).

Note

We only support n >= 2. Mathematically, SU(1) is trivial, consisting of a single element (the identity), chances are you do not need it. For large values of n, you might need to run the compute_characters.py script to precompute the necessary mathematical quantities beyond the ones provided by default.

Citation

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

get_eigenfunctions(num)[source]¶

Returns the SUEigenfunctions object with num levels and order n.

Parameters:: num (int) – Number of levels.
Return type:: geometric_kernels.spaces.eigenfunctions.Eigenfunctions

get_eigenvalues(num)[source]¶

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)[source]¶

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.

static inverse(X)[source]¶

Inverse of a batch X of the elements of the group. A static method.

Parameters:: X (lab.Numeric) – A batch […, n, n] of elements of the group. Each element is a n x n matrix.
Returns:: A batch […, n, n] with each n x n matrix inverted.
Return type:: lab.Numeric

random(key, number)[source]¶

Sample uniformly random points in the space.

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.

property dimension: int¶

The dimension of the space, as that of a Riemannian manifold.

Returns:: floor(n^2-1) where n is the order of the group SU(n).
Return type:: int

property element_dtype¶

Returns:: B.Complex.

property element_shape¶

Returns:: [n, n].

class geometric_kernels.spaces.SymmetricPositiveDefiniteMatrices(n)[source]¶

Bases: geometric_kernels.spaces.base.NoncompactSymmetricSpace, geomstats.geometry.spd_matrices.SPDMatrices

The GeometricKernels space representing the manifold of symmetric positive definite matrices \(SPD(n)\) with the affine-invariant Riemannian metric.

The elements of this space are represented by positive definite matrices of size n x n. Positive definite means _strictly_ positive definite here, not positive semi-definite.

The class inherits the interface of geomstats’s SPDMatrices.

Note

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

Parameters:: n – Size of the matrices, the \(n\) in \(SPD(n)\).

Note

As mentioned in this note, any symmetric space is a quotient G/H. For the manifold of symmetric positive definite matrices \(SPD(n)\), the group of symmetries \(G\) is the identity component \(GL(n)_+\) of the general linear group \(GL(n)\), while the isotropy subgroup \(H\) is the special orthogonal group \(SO(n)\). See the mathematical details in Azangulov et al. [2024].

Citation

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

inv_harish_chandra(lam)[source]¶

Implements \(c^{-1}(\lambda)\), where \(c\) is the Harish-Chandra’s \(c\) function.

This is one of the computational primitives required to (approximately) compute the RandomPhaseFeatureMapNoncompact feature map and MaternFeatureMapKernel on top of it.

Parameters:: lam – A batch of frequencies, vectors of dimension equal to the rank of symmetric space.
Returns:: \(c^{-1}(\lambda)\) evaluated at every \(\lambda\) in the batch lam.

power_function(lam, g, h)[source]¶

Implements the power function \(p^{\lambda}(g, h)\), the integrand appearing in the definition of the zonal spherical function

\[\pi^{\lambda}(g) = \int_{H} \underbrace{p^{\lambda}(g, h)}_{= e^{(i \lambda + \rho) a(h \cdot g)}} d h,\]

This is one of the computational primitives required to (approximately) compute the RandomPhaseFeatureMapNoncompact feature map and MaternFeatureMapKernel on top of it.

Parameters:

lam –
A batch of L vectors of dimension rank, the rank of the symmetric space, representing the “sort of frequencies”.

Typically of shape [1, L, rank].
g –
A batch of N elements of the space (these can always be thought of as elements of the group of symmetries \(G\) since the symmetric space \(G/H\) can be trivially embedded into the group \(G\)).

Typically of shape [N, 1, <axes>], where <axes> is the shape of the elements of the space.
h –
A batch of L elements of the isotropy subgroup \(H\).

Typically of shape [1, L, <axes_p>], where <axes_p> is the shape of arrays representing the elements of the isotropy subgroup \(H\).

Returns:

An array of shape [N, L] with complex number entries, representing the value of the values of \(p^{\lambda_l}(g_n, h_l)\) for all \(1 \leq n \leq N\) and \(1 \leq l \leq L\).

Note

random(key, number)[source]¶

Non-uniform random sampling, reimplements the algorithm from geomstats.

Always returns [N, n, n] float64 array of the key’s backend.

Parameters:

key – Either np.random.RandomState, tf.random.Generator, torch.Generator or jax.tensor (representing random state).
number – Number of samples to draw.

Returns:

An array of number random samples on the space.

random_phases(key, num)[source]¶

Sample uniformly random points on the isotropy subgroup \(H\) (defined here).

This is one of the computational primitives required to (approximately) compute the RandomPhaseFeatureMapNoncompact feature map and MaternFeatureMapKernel on top of it.

Parameters:

key – Either np.random.RandomState, tf.random.Generator, torch.Generator or jax.tensor (representing random state).
num – Number of samples to draw.

Returns:

An array of num uniformly random samples in the isotropy subgroup \(H\).

Warning

property dimension: int¶

Returns n(n+1)/2 where n was passed down to __init__.

Return type:: int

property element_dtype¶

Returns:: B.Float.

property element_shape¶

Returns:: [n, n].

property num_axes¶

Number of axes in an array representing a point in the space.

Returns:

property rho¶

rho vector of dimension equal to the rank of the symmetric space.

Algebraically, weighted sum of roots, depends only on the space.

This is one of the computational primitives required to (approximately) compute the RandomPhaseFeatureMapNoncompact feature map and MaternFeatureMapKernel on top of it.