geometric_kernels.spaces.hamming_graph ====================================== .. py:module:: geometric_kernels.spaces.hamming_graph .. autoapi-nested-parse:: This module provides the :class:`HammingGraph` space and the respective :class:`~.eigenfunctions.Eigenfunctions` subclass :class:`VilenkinFunctions`. Module Contents --------------- .. py:class:: HammingGraph(dim, n_cat) Bases: :py:obj:`geometric_kernels.spaces.base.DiscreteSpectrumSpace` The GeometricKernels space representing the q-ary Hamming graph $H(d,q) = \{0, 1, ..., q-1\}^d$, the combinatorial space of categorical vectors (with $q$ categories) of length $d$. The elements of this space are represented by d-dimensional categorical vectors (with $q$ categories) taking integer values in $\{0, 1, ..., q-1\}$. Levels are the whole eigenspaces. .. note:: If you need a kernel operating on categorical vectors where $q$ varies between dimensions, you can use `HammingGraph` in conjunction with :class:`ProductGeometricKernel` or :class:`ProductDiscreteSpectrumSpace`. .. note:: For the special case $q = 2$, this reduces to the binary hypercube graph, also available as :class:`HypercubeGraph`. .. note:: A tutorial on how to use this space is available in the :doc:`HammingGraph.ipynb ` notebook. .. note:: Since the degree matrix is a constant multiple of the identity, all types of the graph Laplacian coincide on the Hamming graph up to a constant, we choose the normalized Laplacian for numerical stability. :param dim: Dimension $d$ of the Hamming graph $H(d,q)$, a positive integer. :param n_cat: Number of categories $q$ of the Hamming graph $H(d,q)$, a positive integer $q \geq 2$. .. admonition:: Citation If you use this GeometricKernels space in your research, please consider citing :cite:t:`borovitskiy2023` and :cite:t:`doumont2025`. .. py:method:: get_eigenfunctions(num) Returns the :class:`~.VilenkinFunctions` object with `num` levels. :param num: Number of levels. .. py:method:: get_eigenvalues(num) Eigenvalues of the Laplacian corresponding to the first `num` levels. :param num: Number of levels. :return: (num, 1)-shaped array containing the eigenvalues. .. note:: The notion of *levels* is discussed in the documentation of the :class:`~.kernels.MaternKarhunenLoeveKernel`. .. py:method:: get_repeated_eigenvalues(num) Eigenvalues of the Laplacian corresponding to the first `num` levels, repeated according to their multiplicity within levels. :param num: Number of levels. :return: (J, 1)-shaped array containing the repeated eigenvalues, J is the resulting number of the repeated eigenvalues. .. note:: The notion of *levels* is discussed in the documentation of the :class:`~.kernels.MaternKarhunenLoeveKernel`. .. py:method:: random(key, number) Sample uniformly random points on the Hamming graph $H(d,q)$. Always returns [N, D] integer array of the `key`'s backend with values in $\{0, 1, ..., q-1\}$. :param key: Either `np.random.RandomState`, `tf.random.Generator`, `torch.Generator` or `jax.tensor` (representing random state). :param number: Number N of samples to draw. :return: An array of `number` uniformly random samples on the space. .. py:property:: dimension :type: int Returns d, the `dim` parameter that was passed down to `__init__`. .. note: Although this is a graph, and graphs are generally treated as 0-dimensional throughout GeometricKernels, we make an exception for HammingGraph. This is because it helps maintain good behavior of Matérn kernels with the usual values of the smoothness parameter nu, i.e. nu = 1/2, nu = 3/2, nu = 5/2. .. py:property:: element_dtype :return: B.Int. .. py:property:: element_shape :return: [d]. .. py:class:: VilenkinFunctions(dim, n_cat, num_levels) Bases: :py:obj:`geometric_kernels.spaces.eigenfunctions.EigenfunctionsWithAdditionTheorem` Eigenfunctions of the graph Laplacian on the q-ary Hamming graph $H(d,q)$, whose nodes are indexed by categorical vectors in $\{0, 1, ..., q-1\}^d$. These eigenfunctions are the Vilenkin functions (also called Vilenkin-Chrestenson functions), which generalize the binary Walsh functions to q-ary alphabets. They map vertices to complex values via products of characters on cyclic groups. For the special case $q = 2$, the Vilenkin functions reduce to the Walsh functions on the binary hypercube $\{0, 1\}^d$. .. note:: The Vilenkin functions can be indexed by "character patterns" - choices of coordinates and non-identity characters at those coordinates. Each eigenspace (level) $j$ has dimension $\binom{d}{j}(q-1)^j$, corresponding to choosing $j$ coordinates and assigning $(q-1)$ possible non-identity characters to each. Levels are the whole eigenspaces, comprising all Vilenkin functions with the same number of coordinates having non-identity characters. The addition theorem for these is based on generalized Kravchuk polynomials, i.e. discrete orthogonal polynomials on the q-ary Hamming scheme. :param dim: Dimension $d$ of the q-ary Hamming graph $H(d,q)$. :param n_cat: Number of categories $q \geq 2$ in the q-ary alphabet $\{0, 1, ..., q-1\}$. :param num_levels: Specifies the number of levels (eigenspaces) of the Vilenkin functions to use. .. py:method:: __call__(X, **kwargs) :abstractmethod: Evaluate the individual eigenfunctions at a batch of input locations. :param X: Points to evaluate the eigenfunctions at, an array of shape [N, ], where N is the number of points and is the shape of the arrays that represent the points in a given space. :param ``**kwargs``: Any additional parameters. :return: An [N, J]-shaped array, where `J` is the number of eigenfunctions. .. py:method:: weighted_outerproduct(weights, X, X2 = None, **kwargs) Computes .. math:: \sum_{l=0}^{L-1} w_l \sum_{s=1}^{d_l} f_{l s}(x_1) f_{l s}(x_2). for all $x_1$ in `X` and all $x_2$ in `X2`, where $w_l$ are `weights`. :param weights: An array of shape [L, 1] where L is the number of levels. :param X: The first of the two batches of points to evaluate the weighted outer product at. An array of shape [N, ], where N is the number of points and is the shape of the arrays that represent the points in a given space. :param X2: The second of the two batches of points to evaluate the weighted outer product at. An array of shape [N2, ], where N2 is the number of points and 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. :param ``**kwargs``: Any additional parameters. :return: An array of shape [N, N2]. .. py:method:: weighted_outerproduct_diag(weights, X, **kwargs) Computes the diagonal of the matrix ``weighted_outerproduct(weights, X, X, **kwargs)``. :param weights: As in :meth:`weighted_outerproduct`. :param X: As in :meth:`weighted_outerproduct`. :param ``**kwargs``: As in :meth:`weighted_outerproduct`. :return: An array of shape [N,]. .. py:property:: num_eigenfunctions :type: int The number J of eigenfunctions. .. py:property:: num_eigenfunctions_per_level :type: beartype.typing.List[int] The number of eigenfunctions per level: list of $d_l$, $0 \leq l < L$. .. py:property:: num_levels :type: int The number L of levels.