geometric_kernels.spaces.hyperbolic

This module provides the Hyperbolic space.

Module Contents

class geometric_kernels.spaces.hyperbolic.Hyperbolic(dim=2)

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

Citation

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

convert_to_ball(point)

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)

Compute the hyperbolic distance between x1 and x2.

The code is a reimplementation of geomstats.geometry.hyperboloid.HyperbolicMetric for lab.

Parameters:

• x1 (lab.Numeric) – An [N, n+1]-shaped array of points in the hyperbolic space.

• x2 (lab.Numeric) – An [M, n+1]-shaped array of points in the hyperbolic space.

• diag (beartype.typing.Optional[bool]) –

  If True, compute elementwise distance. Requires N = M.

  Default False.

Returns:

An [N, M]-shaped array if diag=False or [N,]-shaped array if diag=True.

Return type:

lab.Numeric

element_shape()

Returns:

[n+1].

inner_product(vector_a, vector_b)

Computes the Minkowski inner product of vectors.

\[\langle a, b \rangle = a_0 b_0 - a_1 b_1 - \ldots - a_n b_n.\]

Parameters:

• vector_a – An […, n+1]-shaped array of points in the hyperbolic space.

• vector_b – An […, n+1]-shaped array of points in the hyperbolic space.

Returns:

An […,]-shaped array of inner products.

inv_harish_chandra(lam)

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)

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)

Geomstats-based non-uniform random sampling.

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 uniformly random samples on the space.

random_phases(key, num)

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