geometric_kernels.spaces.product

This module provides the ProductDiscreteSpectrumSpace space and the respective Eigenfunctions subclass ProductEigenfunctions.

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.

Module Contents

class geometric_kernels.spaces.product.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.product.ProductEigenfunctions(element_shapes, element_dtypes, eigenindicies, *eigenfunctions, dimension_indices=None)[source]

Bases: geometric_kernels.spaces.eigenfunctions.Eigenfunctions

Eigenfunctions of the Laplacian on the product space are outer products of the eigenfunctions on factors.

Levels correspond to tuples of levels of the factors.

Parameters:

  • element_shapes (beartype.typing.List[beartype.typing.List[int]]) – Shapes of the elements in each factor. Can be obtained as properties space.element_shape of any given factor space.

  • element_dtypes (beartype.typing.List[lab.DType]) – Abstract lab data types of the elements in each factor. Can be obtained as properties space.element_dtype of any given factor space.

  • eigenindicies (lab.Numeric) –

    A [L, S]-shaped array, where S is the number of factor spaces and L is the number of levels, such that eigenindicies[i, :] are the indices of the levels of the factor spaces that correspond to the i’th level of the product space.

    This parameter implicitly determines the number of levels.

  • *eigenfunctions (geometric_kernels.spaces.eigenfunctions.Eigenfunctions) – The Eigenfunctions subclasses corresponding to each of the factor spaces.

  • dimension_indices (lab.Numeric) –

    Determines how a vector x representing a product space element is to be mapped into the arrays xi that represent elements of the factor spaces. xi are assumed to be equal to x[dimension_indices[i]], possibly up to a reshape. Such a reshape might be necessary to accommodate the spaces whose elements are matrices rather than vectors, as determined by element_shapes. The transformation of x into the list of xis is performed by project_product().

    If None, assumes the each input is layed-out flattened and concatenated, in the same order as the factor spaces. In this case, the inverse to project_product() is make_product().

    Defaults to None.

__call__(X, **kwargs)[source]

Evaluate the individual eigenfunctions at a batch of input locations.

Warning

Will raise NotImplementedError if some of the factors do not implement their __call__.

Parameters:

  • X (lab.Numeric) –

    Points to evaluate the eigenfunctions at, an array of shape [N, D], where N is the number of points and D is the dimension of the vectors that represent points in the product space.

    Each point x in the product space is a D-dimensional vector such that x[dimension_indices[i]] is the vector that represents the flattened element of the i-th factor space.

    Note

    If the instance was created with dimension_indices=None, then you can use the make_product() function to convert a list of (batches of) points in factor spaces into a (batch of) points in the product space.

  • **kwargs – Any additional parameters.

Returns:

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

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

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