banquo.kernels¶
The module contains power spectral densities and kernels implementation.
Functions¶
|
Compute the squared fractional graph Laplacian. |
|
Calculate flattened indices for combining node and time indices. |
Approximate the discrete stochastic heat equation normalized kernel. |
|
|
Compute the correlation matrix approximating a Whittle–Matérn field. |
Module Contents¶
- banquo.kernels.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 \(\lambda\) with a shifting factor kappa and exponent alpha, which must both be positive. The fractional operator eigenvalues are given by,
\[\widetilde{\lambda} = \left(\kappa^2 \mathbf{I} + \lambda\right)^{\alpha}.\]- Parameters:
eigenvalues (array) – Array of eigenvalues of the graph Laplacian matrix.
kappa (float) – Shifting factor applied to the eigenvalues, must be positive.
alpha (float) – Exponent controlling the fractional power of the transformed Laplacian, must be positive. It has a linear relation with the smoothness.
- Returns:
Transformed eigenvalues using the squared fractional Laplacian formula.
- Return type:
array
Notes
- banquo.kernels.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.
- Parameters:
node_i (int) – Index of the first node.
node_j (int) – Index of the second node.
time_i (int) – Index of the time step for the first node.
time_j (int) – Index of the time step for the second node.
dim_t (int) – Number of time steps for each node.
- Returns:
Flattened indices corresponding to the combined node-time positions.
- Return type:
tuple[int, int]
- banquo.kernels.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:
\[\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, \(\mathbf{W}(\xi)\) is the derivative, and \(\xi = (\mathbf{s}, t) \in \mathcal{D}\). Given the spatial domain \(\mathcal{S} \subseteq \mathbb{R}^d\) and the time domain \(\mathcal{T} \subseteq \mathbb{R}\), the spatiotemporal domain is \(\mathcal{D} = \mathcal{S} \times \mathcal{T}\). With \(\tau > 0\), the dispersion parameter is represented as \(1/\tau\). The thermal diffusivity of the medium in the process \(\mathbf{X}(\xi)\) is \(\gamma > 0\). Here, the graph Laplacian operator \(L\) is used in place of the continuous one \(\Delta\).
This correlation function is given by:
\[k\left(\lvert t-t'\rvert\right) = \exp\left(-\mathbf{\Gamma} \lvert t-t'\rvert\right).\]flat_index()can be used to provide human-friendly access to the matrix elements.- Parameters:
t (array) – Time indices.
graph_eigenpair (tuple[array, array]) – Eigenvalues and eigenvectors of the graph Laplacian.
gamma (float) – Medium’s (thermal) diffusivity, must be positive.
kappa (float) – Shifting factor applied to the spatial eigenvalues of the graph Laplacian, must be positive.
alpha (float) – Exponent controlling the fractional power of the transformed Laplacian, must be positive. It has a linear relation with the smoothness.
- Returns:
Non-separable spatiotemporal correlation matrix. The spatial domain is discretized as a graph.
- Return type:
array
Notes
- banquo.kernels.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
\[\tau \, \left(\kappa^2 - \Delta_{\mathbf{s}}\right)^{\alpha/2} \mathbf{X}(\mathbf{s}) = \mathbf{W}(\mathbf{s}),\]where \(\mathbf{W}(\mathbf{s})\) is Gaussian white noise and \(\Delta\) is the Laplacian operator on a spatial domain \(\Omega\). In the discrete setting, the continuous domain \(\Omega\) is replaced by a tessellated mesh \(\Omega_h\) with grid spacing \(h\), and the continuous Laplacian is approximated by the graph Laplacian \(\mathbf{L}\). Assuming the spectral decomposition
\[\mathbf{L} = \mathbf{Q} \mathbf{\Lambda} \mathbf{Q}^{\mathrm{T}},\]with eigenvalues \(\mathbf{\Lambda}\) and eigenvectors \(\mathbf{Q}\), the covariance matrix of the associated Gaussian Markov random field (GMRF) is given by
\[\mathbf{\Sigma} = \mathbf{Q} \tau^{-2}\left(\kappa^2 \mathbf{I} + \mathbf{\Lambda}\right)^{-\alpha} \mathbf{Q}^{\mathrm{T}},\]Removing the precision parameter \(\tau\) via a diagonal scaling produces the correlation matrix
\[\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 \(\mathbf{S}\) are defined by
\[\mathbf{S}_{ii} = \sqrt{\sum_{r=1}^d \mathbf{Q}_{ir}^2 \left( \kappa^2 + \lambda_r \right)^{-\alpha}}.\]- Parameters:
graph_eigenpair (tuple[array, array]) – A tuple (\(\mathbf{\Lambda}\), \(\mathbf{Q}\)) where \(\mathbf{\Lambda}\) is an array of eigenvalues and \(\mathbf{Q}\) is the corresponding array of eigenvectors.
kappa (float) – A positive shifting factor applied to the eigenvalues. It adjusts the spatial scale of the field.
alpha (float) – 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 \(d/2\), where \(d\) is the number of nodes.
- 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.
- Return type:
array
Notes