pysiglib.branched_log_sig

pysiglib.branched_log_sig#

branched_log_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 branched log signature of a path.

Parameters:

  • path (numpy.ndarray | torch.tensor) – The underlying path or batch of paths, given as a numpy.ndarray or torch.tensor. For a single path, this must be of shape (length, dimension). For a batch of paths, this must be of shape (batch_size, length, dimension).

  • degree (int) – Truncation degree of the branched (log) signature(s).

  • time_aug (bool) – If set to True, will compute the branched log 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 branched log signature of the path after applying the lead-lag transformation.

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

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

  • scalar_term (bool) – If True, include the leading scalar coefficient, which is zero.

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

    Optional per-segment correction of level \(\geq 2\) added to the path increment on each path segment, before the branched log signature is taken. 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 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.

Returns:

The branched log signature or batch of branched log signatures.

Return type:

numpy.ndarray | torch.tensor

Example usage:#

import torch
import pysiglib

path = torch.rand((10, 100, 5))
blogsig = pysiglib.branched_log_sig(path, 3)
print(blogsig)

Ito-lifted branched log 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_blogsig = pysiglib.branched_log_sig(
    path, N, correction=correction, end_time=T)
print(ito_blogsig)

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