pysiglib.sig_kernel_gram_backprop

pysiglib.sig_kernel_gram_backprop#

Added in version v0.2.1.

Warning

Where possible, pysiglib.torch_api should be used rather than explicitly calling backpropagation functions. Explicit backpropagation can introduce subtle errors if called incorrectly. In addition, some pysiglib functions can only be backpropagated through using their pysiglib.torch_api variants and do not expose explicit backpropagation functions.

sig_kernel_gram_backprop(derivs, path1, path2, dyadic_order, *, static_kernel=None, time_aug=False, lead_lag=False, end_time=1.0, left_deriv=True, right_deriv=False, k_grid=None, n_jobs=1, return_grid=False, max_batch=-1)[source]#

This function is required to backpropagate through pysiglib.sig_kernel_gram. Given the derivatives of a scalar function \(F\) with respect to a gram matrix of signature kernels, \(\partial F / G\), returns the derivatives of \(F\) with respect to one or both of the underlying paths, \(\{\partial F / x_{t_i}\}_{i=0}^{L_1}\) and \(\{\partial F / y_{t_i}\}_{i=0}^{L_2}\).

Parameters:

  • derivs (numpy.ndarray | torch.tensor) – Derivatives with respect to a gram matrix of signature kernels, \(\partial F / G\). Should have the same shape as the output of pysiglib.sig_kernel_gram for the same inputs: (*batch_shape_1, *batch_shape_2) if return_grid=False, or (*batch_shape_1, *batch_shape_2, dyadic_length_1, dyadic_length_2) if return_grid=True.

  • 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) – The dyadic order(s) used to compute the signature kernels.

  • 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 True, assumes the paths were time augmented.

  • lead_lag (bool) – If True, assumes the lead-lag transform was applied.

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

  • left_deriv (bool) – If True, returns \(\{\partial F / x_{t_i}\}_{i=0}^{L_1}\). At least one of left_deriv and right_deriv must be True. If both are True, returns both derivatives as a tuple.

  • right_deriv (bool) – If True, returns \(\{\partial F / y_{t_i}\}_{i=0}^{L_2}\). At least one of left_deriv and right_deriv must be True. If both are True, returns both derivatives as a tuple.

  • k_grid (numpy.ndarray | torch.tensor) – Signature kernel PDE grid. If None, the grid will be recomputed.

  • 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.

  • return_grid (bool) – If True, backpropagates derivatives with respect to the entire PDE grid.

  • 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.

Returns:

Tuple of derivatives of \(F\) with respect to one or both of the underlying paths. If left_deriv is True, the first element of this tuple is \(\{\partial F / x_{t_i}\}_{i=0}^{L_1}\) with shape matching path1, otherwise it is None. Similarly for right_deriv and \(\{\partial F / y_{t_i}\}_{i=0}^{L_2}\) with shape matching path2.

Return type:

numpy.ndarray | torch.tensor | Tuple[numpy.ndarray | numpy.ndarray] | Tuple[torch.tensor | torch.tensor]

Note

When called via pysiglib.torch_api, the default behaviour is to pass k_grid = None and reconstruct the PDE grids. 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)
derivs = torch.ones_like(gram)
dpath1, _ = pysiglib.sig_kernel_gram_backprop(derivs, path1, path2, dyadic_order=2)
print(dpath1)

# Gram backprop 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,
)
derivs = torch.ones_like(gram)
dpath1, dpath2 = pysiglib.sig_kernel_gram_backprop(
    derivs, path1, path2,
    dyadic_order=2,
    static_kernel=rbf,
    time_aug=True,
    left_deriv=True,
    right_deriv=True,
    max_batch=4,
)
print(dpath1)
print(dpath2)

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