pysiglib.sig_kernel_gram

pysiglib.sig_kernel_gram#

Added in version v0.2.1.

sig_kernel_gram(path1, path2, dyadic_order, *, static_kernel=None, time_aug=False, lead_lag=False, end_time=1.0, n_jobs=1, max_batch=-1, return_grid=False, normalize=False)[source]#

Given batches of paths \(\{x_i\}_{i=1}^{B_1}\) and \(\{y_j\}_{j=1}^{B_2}\), computes the gram matrix of signature kernels

\[G = (k_{x_i, y_j})_{i = 1, j = 1}^{B_1, B_2}.\]

The signature kernel of two \(d\)-dimensional paths \(x,y\) is defined as

\[k_{x,y}(s,t) := \left< S(x)_{[0,s]}, S(y)_{[0, t]} \right>_{T((\mathbb{R}^d))}\]

where the inner product is defined as

\[\left< A, B \right> := \sum_{k=0}^{\infty} \left< A_k, B_k \right>_{\left(\mathbb{R}^d\right)^{\otimes k}}\]
\[\left< u, v \right>_{\left(\mathbb{R}^d\right)^{\otimes k}} := \prod_{i=1}^k \left< u_i, v_i \right>_{\mathbb{R}^d}.\]

Optionally, a static kernel can be specified. For details, see the documentation on static kernels.

Parameters:

  • path1 (numpy.ndarray | torch.tensor) – A path or batch of paths, of shape (*batch_shape_1, length_1, dimension).

  • path2 (numpy.ndarray | torch.tensor) – A path or batch of paths, of shape (*batch_shape_2, length_2, dimension). Independent of path1’s batch shape.

  • dyadic_order (int | tuple) – If set to a positive integer \(\lambda\), will refine the paths by a factor of \(2^\lambda\). If set to a tuple of positive integers \((\lambda_1, \lambda_2)\), will refine the first path by \(2^{\lambda_1}\) and the second path by \(2^{\lambda_2}\).

  • static_kernel (None | pysiglib.StaticKernel) – Static kernel. If None (default), the linear kernel will be used. For details, see the documentation on static kernels.

  • time_aug (bool) – If set to True, will compute the signature of the time-augmented path, \(\hat{x}_t := (t, x_t)\), defined as the original path with an extra channel set to time, \(t\). This channel spans \([0, t_L]\), where \(t_L\) is given by the parameter end_time.

  • lead_lag (bool) – If set to True, will compute the signature of the path after applying the lead-lag transformation.

  • end_time (float) – End time for time-augmentation, \(t_L\).

  • n_jobs (int) – (Only applicable to CPU computation) Number of threads to run in parallel. If n_jobs = 1, the computation is run serially. If set to -1, all available threads are used. For n_jobs below -1, (max_threads + 1 + n_jobs) threads are used. For example if n_jobs = -2, all threads but one are used.

  • max_batch (int) – Maximum batch size to run in parallel. If the computation is failing due to insufficient memory, this parameter should be decreased. If set to -1, the entire batch is computed in parallel.

  • return_grid (bool) – If True, returns the entire PDE grid.

  • normalize (bool) – If True, normalizes the gram matrix so that \(K(x, x) = 1\) by dividing each entry by \(\sqrt{K(x_i, x_i) \cdot K(y_j, y_j)}\). Cannot be used with return_grid=True.

Returns:

Gram matrix of signature kernels, of shape (*batch_shape_1, *batch_shape_2) (or (*batch_shape_1, *batch_shape_2, dyadic_length_1, dyadic_length_2) if return_grid=True).

Return type:

numpy.ndarray | torch.tensor

Note

When called via pysiglib.torch_api, the default behaviour is to reconstruct the PDE grids during backpropagation. This is done to avoid memory allocation issues for large batch sizes.

Example:#

import torch
import pysiglib

path1 = torch.rand((10, 100, 5))
path2 = torch.rand((8, 100, 5))
gram = pysiglib.sig_kernel_gram(path1, path2, dyadic_order=2)
print(gram.shape) # gram has shape (10, 8)
print(gram)

# Gram matrix with a static kernel
import torch
import pysiglib

path1 = torch.rand((10, 100, 5))
path2 = torch.rand((8, 100, 5))
rbf = pysiglib.RBFKernel(sigma=0.5)
gram = pysiglib.sig_kernel_gram(
    path1, path2,
    dyadic_order=2,
    static_kernel=rbf,
    time_aug=True,
    lead_lag=True,
    max_batch=4,
)
print(gram.shape)

# Multi-dim batches: leading dims are flattened and the result has shape
# (*batch_shape_1, *batch_shape_2)
import torch
import pysiglib

path1 = torch.rand((4, 10, 100, 5))  # batch_shape_1 = (4, 10)
path2 = torch.rand((8, 100, 5))      # batch_shape_2 = (8,)
gram = pysiglib.sig_kernel_gram(path1, path2, dyadic_order=2)
print(gram.shape)  # gram has shape (4, 10, 8)

Citation#

If you found this library useful in your research, please consider citing the paper:

@article{shmelev2025pysiglib,
  title={pySigLib-Fast Signature-Based Computations on CPU and GPU},
  author={Shmelev, Daniil and Salvi, Cristopher},
  journal={arXiv preprint arXiv:2509.10613},
  year={2025}
}
Contents