geometric_kernels.spaces.base

Abstract base classes for all spaces (input domains) in the library.

Module Contents

class geometric_kernels.spaces.base.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()[source]

Geometric dimension of the space.

Examples:

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.base.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. [2023].

abstract dimension()[source]

Geometric dimension of the space.

Examples:

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

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,\]

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.

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

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.

abstract rho()[source]

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.base.Space[source]

Bases: abc.ABC

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

abstract dimension()[source]

Geometric dimension of the space.

Examples:

Return type:

int

abstract element_shape()[source]

Shape of an element.

Examples: * hypersphere: [D + 1, ] * mesh: [1, ] * matrix Lie group: [n, n]

Return type:

beartype.typing.List[int]