pysiglib.branched_sig

pysiglib.branched_sig#

branched_sig(path, degree, *, time_aug=False, lead_lag=False, end_time=1.0, planar=False, scalar_term=False, correction=None, n_jobs=1)[source]#

Computes the truncated branched signature of a path or batch of paths.

The branched signature extends the standard path signature to iterated integrals indexed by decorated rooted trees, following Gubinelli (2010). For planar=True, the output is instead indexed by the MKW ordered forest basis.

Must call prepare_branched_sig(dimension, degree, planar=planar) before first use, where dimension is the augmented dimension (accounting for time_aug and lead_lag).

Parameters:

  • path (numpy.ndarray | torch.tensor) – Path of shape (length, dimension) or (..., length, dimension).

  • degree (int) – Maximum order (number of nodes).

  • time_aug (bool) – If True, prepend a time channel to the path.

  • lead_lag (bool) – If True, apply the lead-lag transformation.

  • end_time (float) – End time for the time augmentation channel.

  • planar (bool) – If True, compute the planar MKW branched signature.

  • scalar_term (bool) – If True, the output includes the leading constant 1 at index 0 (the empty-word term). If False (default), this leading element is stripped from the output.

  • correction (numpy.ndarray | torch.tensor | None) –

    Optional per-segment correction of level \(\geq 2\) added to the path increment on each path segment. The level-1 part of the local lift is the segment’s path increment \(\Delta x\), the higher levels come from the matching correction row, and the local branched signature on each segment is

    \[\exp_* \left( \sum_i \Delta x_i\, e_i + \sum_{k=2}^{m} \sum_{i_1, \ldots, i_k} c^{(k)}_{i_1 \ldots i_k}\, e_{i_1 \cdots i_k} \right),\]

    where \(e_w\) is the chain (root-to-leaf path) tree with labels \(w\) and \(\exp_*\) is the Hopf-algebra exponential under the Butcher product. A non-empty correction may have shape (C,) for one constant correction shared by every segment and batch item, (path.shape[-2] - 1, C) for one correction row per segment shared by the batch, or path.shape[:-2] + (path.shape[-2] - 1, C) for batch-specific segment corrections. Here C is the correction width, with C = d^2 + d^3 + ... + d^m, where \(d\) is the underlying path dimension and \(2 \leq m \leq N\) is the highest correction level supplied (missing higher levels are zero). Levels are concatenated in order, and within level \(k\) the entry for chain \((i_1, \ldots, i_k)\) lives at flat index \(i_1 d^{k-1} + i_2 d^{k-2} + \cdots + i_k\). Passing None (default) or an empty array is equivalent to all-zero correction. Indices are over the original path channels; with time_aug=True, the appended time channel contributes no correction. Cannot be combined with lead_lag=True.

  • n_jobs (int) – Number of parallel threads for batch processing.

Returns:

Branched signature array of shape (bsig_len,) or (..., bsig_len).

Example usage:#

Ito-lifted branched signature of a sampled Brownian path. For Brownian motion with instantaneous covariance \(\Sigma\), setting the level-2 correction to \(c^{(2)}_{ij} = \Sigma_{ij}\,\Delta t\) per segment gives the Ito correction.

import numpy as np
import pysiglib

d, N, T = 2, 3, 1.0
n_steps = 100
dt = T / n_steps
rng = np.random.default_rng(42)

# 2D standard Brownian motion sample (Sigma = I)
path = np.zeros((n_steps + 1, d))
path[1:] = np.cumsum(rng.normal(0, np.sqrt(dt), (n_steps, d)), axis=0)

# Ito level-2 correction: one dt * Sigma row per path segment.
correction = np.broadcast_to(
    (np.eye(d) * dt).reshape(1, -1), (n_steps, d * d)).copy()

pysiglib.prepare_branched_sig(d, N)
ito_bsig = pysiglib.branched_sig(
    path, N, correction=correction, end_time=T)
print(ito_bsig)

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