geometric_kernels.spaces.spd ============================ .. py:module:: geometric_kernels.spaces.spd .. autoapi-nested-parse:: This module provides the :class:`SymmetricPositiveDefiniteMatrices` space. Module Contents --------------- .. py:class:: SymmetricPositiveDefiniteMatrices(n) Bases: :py:obj:`geometric_kernels.spaces.base.NoncompactSymmetricSpace`, :py:obj:`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 :doc:`SPD.ipynb ` notebook. :param n: Size of the matrices, the $n$ in $SPD(n)$. .. note:: As mentioned in :ref:`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 :cite:t:`azangulov2023`. .. admonition:: Citation If you use this GeometricKernels space in your research, please consider citing :cite:t:`azangulov2023`. .. py:method:: 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 :class:`~.feature_maps.RandomPhaseFeatureMapNoncompact` feature map and :class:`~.kernels.MaternFeatureMapKernel` on top of it. :param lam: A batch of frequencies, vectors of dimension equal to the rank of symmetric space. :return: $c^{-1}(\lambda)$ evaluated at every $\lambda$ in the batch `lam`. .. py:method:: power_function(lam, g, h) Implements the *power function* $p^{\lambda}(g, h)$, the integrand appearing in the definition of the zonal spherical function .. math:: \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 :ref:`here `), $\rho \in \mathbb{R}^r$ is as in :meth:`rho`, and the function $a$ is a certain space-dependent algebraic operation. This is one of the computational primitives required to (approximately) compute the :class:`~.feature_maps.RandomPhaseFeatureMapNoncompact` feature map and :class:`~.kernels.MaternFeatureMapKernel` on top of it. :param 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]. :param 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, ], where is the shape of the elements of the space. :param h: A batch of L elements of the isotropy subgroup $H$. Typically of shape [1, L, ], where is the shape of arrays representing the elements of the isotropy subgroup $H$. :return: 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:: 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. .. py:method:: random(key, number) Geomstats-based non-uniform random sampling. Always returns [N, n, n] float64 array of the `key`'s backend. :param key: Either `np.random.RandomState`, `tf.random.Generator`, `torch.Generator` or `jax.tensor` (representing random state). :param number: Number of samples to draw. :return: An array of `number` uniformly random samples on the space. .. py:method:: random_phases(key, num) Sample uniformly random points on the isotropy subgroup $H$ (defined :ref:`here `). This is one of the computational primitives required to (approximately) compute the :class:`~.feature_maps.RandomPhaseFeatureMapNoncompact` feature map and :class:`~.kernels.MaternFeatureMapKernel` on top of it. :param key: Either `np.random.RandomState`, `tf.random.Generator`, `torch.Generator` or `jax.tensor` (representing random state). :param num: Number of samples to draw. :return: 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. .. py:property:: dimension :type: int Returns n(n+1)/2 where `n` was passed down to `__init__`. .. py:property:: element_shape :return: [n, n]. .. py:property:: num_axes Number of axes in an array representing a point in the space. :return: 2. .. py: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 :class:`~.feature_maps.RandomPhaseFeatureMapNoncompact` feature map and :class:`~.kernels.MaternFeatureMapKernel` on top of it.