pysiglib.LogSigStream

Added in version v3.0.0.

class LogSigStream(dimension, degree, *, method=2, n_jobs=1, _log_sig_join=None, _log_sig_combine=None, _log_sig=None)

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

Cumulative log-signatures are stored for each point. Any interval log-signature is computed via BCH: L(a, b) = BCH(-L(0, a), L(0, b)), since the inverse of a log-signature is its negation.

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.

Note

You must call pysiglib.prepare_log_sig(dimension, degree) before creating a LogSigStream. This precomputes the Lyndon basis and BCH coefficients.

Parameters:

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

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

• method (int) – Method to use for internal log-signature computation (2 or 3). Method 2 uses the Lyndon bracket basis via the signature-to-log-signature projection; method 3 computes log-sigs directly from the path via BCH.

• n_jobs (int) – Number of threads to run in parallel in internal log_sig, log_sig_join and log_sig_combine calls. -1 uses all available threads; for n_jobs < -1, max_threads + 1 + n_jobs threads are used.

Example:

import pysiglib
import numpy as np

pysiglib.prepare_log_sig(3, 4, method=2)

# Single path
stream = pysiglib.LogSigStream(dimension=3, degree=4)
path = np.random.randn(50, 3)
stream.push_batch(path)
ls = stream.sig(10, 30)  # shape (log_sig_length,)

# Batch of 8 independent paths
stream = pysiglib.LogSigStream(dimension=3, degree=4)
paths = np.random.randn(8, 50, 3)
stream.push_batch(paths)
ls = stream.sig(10, 30)  # shape (8, log_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 log-signature from the stream.

push(point)

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

Parameters:

point (numpy.ndarray | torch.Tensor) – Shape (..., dimension).

push_batch(points)

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

Parameters:

points (numpy.ndarray | torch.Tensor) – Shape (..., n_points, dimension).

sig(start, end)

Query the log-signature over an interval via BCH.

Parameters:

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

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

Returns:

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

Return type:

numpy.ndarray | torch.Tensor

sig_all()

Return the expanding (cumulative) log-signatures.

Returns:

Stacked log-signatures of shape (n, ..., log_sig_length).

Return type:

numpy.ndarray | torch.Tensor

sig_batch(intervals)

Query log-signatures over multiple intervals at once.

Parameters:

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

Returns:

Stacked log-signatures of shape (K, ..., log_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}
}