quadsv.kernels.matrix
=====================

.. py:module:: quadsv.kernels.matrix

.. autoapi-nested-parse::

   Built-in concrete matrix kernel.

   :class:`MatrixKernel` is the standard subclass of
   :class:`~quadsv.kernels.base.MatrixKernelBase`. It carries the
   construction logic for turning a coordinate cloud or a precomputed
   matrix into the underlying ``_K`` storage; the algorithm itself
   (Kx / xtKx / trace / etc.) is inherited unchanged from
   :class:`~quadsv.kernels.base.MatrixKernelBase`.



Classes
-------

.. autoapisummary::

   quadsv.kernels.matrix.MatrixKernel


Module Contents
---------------

.. py:class:: MatrixKernel(data, mode = 'coords', method = 'matern', **kwargs)

   Bases: :py:obj:`quadsv.kernels.base.MatrixKernelBase`


   Built-in matrix kernel constructed from coordinates or a precomputed matrix.

   Carries only the **construction** logic on converting coordinates ``S`` or a
   user-supplied matrix into ``_K`` on top of :class:`MatrixKernelBase`.

   If you want a bespoke kernel builder (e.g. a custom distance decay, a
   cross-modality covariance, a learnt operator) subclass
   :class:`MatrixKernelBase` directly and implement :meth:`_build_kernel`.

   .. seealso::

      :obj:`MatrixKernel.from_coordinates`
          Recommended entry point when working from raw sample coordinates.

      :obj:`MatrixKernel.from_matrix`
          Recommended entry point when a kernel or precision matrix is already available.

      :obj:`MatrixKernelBase`
          Base class to inherit from for custom kernel constructions.


   .. py:method:: from_coordinates(coords, method = 'matern', **kwargs)
      :classmethod:


      Build kernel from spatial coordinates.

      :param coords: Array of spatial coordinates, shape (n, D).
      :type coords: np.ndarray
      :param method: Kernel method. Must be one of 'gaussian', 'matern', 'moran', 'graph_laplacian', 'car'.
      :type method: str, default 'matern'
      :param \*\*kwargs: Additional kernel parameters (bandwidth, nu, rho, k_neighbors, etc.).
      :type \*\*kwargs: dict

      :returns: Initialized kernel object.
      :rtype: MatrixKernel

      :raises ValueError: If ``method`` is not one of :attr:`_available_kernels`.

      .. rubric:: Examples

      >>> coords = np.random.randn(100, 2)
      >>> kernel = MatrixKernel.from_coordinates(coords, method='gaussian', bandwidth=1.0)



   .. py:method:: from_matrix(matrix, is_precision = False, method = 'precomputed', **kwargs)
      :classmethod:


      Build kernel from a precomputed kernel matrix or its inverse.

      :param matrix: Kernel matrix ``(n, n)`` or its inverse (precision matrix).
      :type matrix: np.ndarray or scipy.sparse matrix
      :param is_precision: If True, ``matrix`` is treated as the inverse (precision) matrix ``K^{-1}``.
      :type is_precision: bool, default False
      :param method: The logical kernel method (e.g., 'car' for precision matrices).
      :type method: str, default 'precomputed'
      :param \*\*kwargs: Additional parameters.
      :type \*\*kwargs: dict

      :returns: Initialized kernel object.
      :rtype: MatrixKernel

      .. rubric:: Examples

      >>> K = np.array([[2, -1], [-1, 2]])  # kernel matrix
      >>> kernel = MatrixKernel.from_matrix(K, is_precision=False)