pysiglib.SigStream

Added in version v3.0.0.

class SigStream(dimension, degree, *, scalar_term=False, n_jobs=1, _sig_join=None, _sig_combine=None, _sig=None)

A stateful stream that maintains precomputed cumulative signatures over a growing path, supporting efficient push/pop operations and O(1) arbitrary interval queries.

Cumulative signatures S(0, t) and their inverses S(0, t)^{-1} are stored for each point. Any interval signature is computed via Chen’s identity: S(a, b) = S(0, a)^{-1} * S(0, b).

Supports numpy arrays, torch tensors (with autograd via pysiglib.torch_api), and JAX arrays (via pysiglib.jax_api). Accepts a single path or a batch of independent paths - the batch shape is inferred from the first push / push_batch call and locked in for the rest of the stream’s lifetime. A single SigStream instance can therefore track many independent paths in parallel.

Parameters:

• dimension (int) – Dimension of the underlying space, \(d\).

• degree (int) – Truncation level of the signature, \(N\).

• scalar_term (bool) – If True, stored signatures include the leading constant 1 at index 0. If False (default), the leading element is stripped.

• n_jobs (int) – Number of threads to run in parallel in the internal sig, sig_join and sig_combine calls. If n_jobs = 1 the computation is serial. If -1, all available threads are used. For n_jobs < -1, max_threads + 1 + n_jobs threads are used.

Example:

import pysiglib
import numpy as np

# Single path
stream = pysiglib.SigStream(dimension=3, degree=4)
path = np.random.randn(50, 3)
stream.push_batch(path)
s = stream.sig(10, 30)  # shape (sig_length,)

# Batch of 8 independent paths tracked in parallel
stream = pysiglib.SigStream(dimension=3, degree=4)
paths = np.random.randn(8, 50, 3)
stream.push_batch(paths)
s = stream.sig(10, 30)  # shape (8, sig_length)

property batch_shape

Batch shape locked in by the first push, or None if nothing has been pushed.

property end_index

Absolute index of the last point in the stream.

pop_front()

Remove the oldest cumulative signature from the stream.

push(point)

Append a single point (or batch of points, one per tracked path) and update the cumulative signature.

Parameters:

point (numpy.ndarray | torch.Tensor) – Shape (..., dimension). The leading batch dimensions are either empty (single-path stream) or match the batch shape locked in by the first push.

push_batch(points)

Append multiple points to the stream. Computes the batch signature in a single batched call rather than per-point sequential joins.

Parameters:

points (numpy.ndarray | torch.Tensor) – Shape (..., n_points, dimension). The leading batch dimensions are either empty (single-path stream) or match the batch shape locked in by the first push.

sig(start, end)

Query the signature over an interval via Chen’s identity.

Parameters:

• start (int) – Start index (absolute, inclusive).

• end (int) – End index (absolute, inclusive).

Returns:

The signature of shape (..., sig_length) for the interval path[start:end+1].

Return type:

numpy.ndarray | torch.Tensor

sig_all()

Return the expanding (cumulative) signatures S(0, 0), S(0, 1), ..., S(0, t).

Returns:

Stacked signatures of shape (n, ..., sig_length).

Return type:

numpy.ndarray | torch.Tensor

sig_batch(intervals)

Query signatures over multiple intervals at once.

Parameters:

intervals (list[tuple[int, int]]) – List of (start, end) pairs.

Returns:

Stacked signatures of shape (K, ..., sig_length).

Return type:

numpy.ndarray | torch.Tensor

property size

Number of time-steps currently in the stream.

property start_index

Absolute index of the first point in the stream.

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}
}