banquo.kernels ============== .. py:module:: banquo.kernels .. autoapi-nested-parse:: The module contains power spectral densities and kernels implementation. Functions --------- .. autoapisummary:: banquo.kernels.squared_fractional_graph_laplacian banquo.kernels.flat_index banquo.kernels.discrete_stochastic_heat_equation_corr banquo.kernels.discrete_whittle_matern_fields_corr Module Contents --------------- .. py:function:: squared_fractional_graph_laplacian(eigenvalues, kappa, alpha) Compute the squared fractional graph Laplacian. This function applies the squared fractional transformation to the graph Laplacian `eigenvalues` :math:`\lambda` with a shifting factor `kappa` and exponent `alpha`, which must both be positive. The fractional operator eigenvalues are given by, .. math:: \widetilde{\lambda} = \left(\kappa^2 \mathbf{I} + \lambda\right)^{\alpha}. :param eigenvalues: Array of eigenvalues of the graph Laplacian matrix. :type eigenvalues: array :param kappa: Shifting factor applied to the eigenvalues, must be positive. :type kappa: float :param alpha: Exponent controlling the fractional power of the transformed Laplacian, must be positive. It has a linear relation with the smoothness. :type alpha: float :returns: Transformed eigenvalues using the squared fractional Laplacian formula. :rtype: array .. rubric:: Notes - `Non-separable Spatio-temporal Graph Kernels via SPDEs `__. .. py:function:: flat_index(node_i, node_j, time_i, time_j, dim_t) Calculate flattened indices for combining node and time indices. Given node indices and time indices, this function returns the equivalent flat indices for a 2D matrix where each node spans `dim_t` time steps. :param node_i: Index of the first node. :type node_i: int :param node_j: Index of the second node. :type node_j: int :param time_i: Index of the time step for the first node. :type time_i: int :param time_j: Index of the time step for the second node. :type time_j: int :param dim_t: Number of time steps for each node. :type dim_t: int :returns: Flattened indices corresponding to the combined node-time positions. :rtype: tuple[int, int] .. py:function:: discrete_stochastic_heat_equation_corr(t, graph_eigenpair, gamma, kappa, alpha) Approximate the discrete stochastic heat equation normalized kernel. This function builds an approximation for the Gram matrix of the normalized kernel (correlation) resulted from the discrete stochastic heat equation on a graph. The following is the expression for the stochastic heat equation: .. math:: \left[\frac{\partial}{\partial t} + \gamma \left(\kappa^2 + \Delta\right)^{\alpha/2}\right] \tau \mathbf{X}(\xi) = \mathbf{W}(\xi). For the spatiotemporal Brownian motion, :math:`\mathbf{W}(\xi)` is the derivative, and :math:`\xi = (\mathbf{s}, t) \in \mathcal{D}`. Given the spatial domain :math:`\mathcal{S} \subseteq \mathbb{R}^d` and the time domain :math:`\mathcal{T} \subseteq \mathbb{R}`, the spatiotemporal domain is :math:`\mathcal{D} = \mathcal{S} \times \mathcal{T}`. With :math:`\tau > 0`, the dispersion parameter is represented as :math:`1/\tau`. The thermal diffusivity of the medium in the process :math:`\mathbf{X}(\xi)` is :math:`\gamma > 0`. Here, the graph Laplacian operator :math:`L` is used in place of the continuous one :math:`\Delta`. This correlation function is given by: .. math:: k\left(\lvert t-t'\rvert\right) = \exp\left(-\mathbf{\Gamma} \lvert t-t'\rvert\right). :func:`flat_index` can be used to provide human-friendly access to the matrix elements. :param t: Time indices. :type t: array :param graph_eigenpair: Eigenvalues and eigenvectors of the graph Laplacian. :type graph_eigenpair: tuple[array, array] :param gamma: Medium's (thermal) diffusivity, must be positive. :type gamma: float :param kappa: Shifting factor applied to the spatial eigenvalues of the graph Laplacian, must be positive. :type kappa: float :param alpha: Exponent controlling the fractional power of the transformed Laplacian, must be positive. It has a linear relation with the smoothness. :type alpha: float :returns: Non-separable spatiotemporal correlation matrix. The spatial domain is discretized as a graph. :rtype: array .. rubric:: Notes - `Non-separable Spatio-temporal Graph Kernels via SPDEs `__. .. py:function:: discrete_whittle_matern_fields_corr(graph_eigenpair, kappa, alpha) Compute the correlation matrix approximating a Whittle–Matérn field. This function constructs an approximation to the kernel corresponding to a Whittle–Matérn field defined as the solution to the SPDE .. math:: \tau \, \left(\kappa^2 - \Delta_{\mathbf{s}}\right)^{\alpha/2} \mathbf{X}(\mathbf{s}) = \mathbf{W}(\mathbf{s}), where :math:`\mathbf{W}(\mathbf{s})` is Gaussian white noise and :math:`\Delta` is the Laplacian operator on a spatial domain :math:`\Omega`. In the discrete setting, the continuous domain :math:`\Omega` is replaced by a tessellated mesh :math:`\Omega_h` with grid spacing :math:`h`, and the continuous Laplacian is approximated by the graph Laplacian :math:`\mathbf{L}`. Assuming the spectral decomposition .. math:: \mathbf{L} = \mathbf{Q} \mathbf{\Lambda} \mathbf{Q}^{\mathrm{T}}, with eigenvalues :math:`\mathbf{\Lambda}` and eigenvectors :math:`\mathbf{Q}`, the covariance matrix of the associated Gaussian Markov random field (GMRF) is given by .. math:: \mathbf{\Sigma} = \mathbf{Q} \tau^{-2}\left(\kappa^2 \mathbf{I} + \mathbf{\Lambda}\right)^{-\alpha} \mathbf{Q}^{\mathrm{T}}, Removing the precision parameter :math:`\tau` via a diagonal scaling produces the correlation matrix .. math:: \mathbf{\Omega} = \mathbf{S}^{-1} \mathbf{Q} \left(\kappa^2 \mathbf{I} + \mathbf{\Lambda}\right)^{-\alpha} \mathbf{Q}^{\mathrm{T}} \mathbf{S}^{-1} , where the diagonal entries of :math:`\mathbf{S}` are defined by .. math:: \mathbf{S}_{ii} = \sqrt{\sum_{r=1}^d \mathbf{Q}_{ir}^2 \left( \kappa^2 + \lambda_r \right)^{-\alpha}}. :param graph_eigenpair: A tuple (:math:`\mathbf{\Lambda}`, :math:`\mathbf{Q}`) where :math:`\mathbf{\Lambda}` is an array of eigenvalues and :math:`\mathbf{Q}` is the corresponding array of eigenvectors. :type graph_eigenpair: tuple[array, array] :param kappa: A positive shifting factor applied to the eigenvalues. It adjusts the spatial scale of the field. :type kappa: float :param alpha: A positive exponent controlling the fractional power of the Laplacian transformation. This parameter is directly related to the smoothness of the field. It must be greater than :math:`d/2`, where :math:`d` is the number of nodes. :type alpha: float :returns: The normalized correlation matrix approximating the Whittle–Matérn field on the discretized domain. This matrix converges to the true continuous correlation structure as the discretization is refined. :rtype: array .. rubric:: Notes - `Non-separable Spatio-temporal Graph Kernels via SPDEs `__.