Metadata-Version: 2.3
Name: log-signatures-pytorch
Version: 0.1.10
Summary: Simple pytorch implementation of log-signatures.
Author: Erlend Aune
Author-email: Erlend Aune <erlend.aune@pm.me>
License: MIT License
         
         Copyright (c) 2025
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
Requires-Dist: torch>=2.9.1
Requires-Python: >=3.13
Project-URL: Homepage, https://github.com/froskekongen/log_signatures_pytorch
Project-URL: Repository, https://github.com/froskekongen/log_signatures_pytorch
Project-URL: Documentation, https://froskekongen.github.io/log_signatures_pytorch/
Description-Content-Type: text/markdown

# log_signatures_pytorch

Differentiable log-signature and signature kernels implemented in PyTorch with both CPU-friendly and GPU-parallel execution paths.

## What you'll find

- Batched signature and log-signature computation for tensors shaped ``(batch, length, dim)`` with optional streaming outputs at every step. For a single path, add a leading dimension via ``unsqueeze(0)``.
- Sliding-window signatures and log-signatures that reuse streamed prefixes (Chen identity) instead of re-computing each window independently.
- Hall-basis utilities (`hall_basis`, `logsigdim`, `logsigkeys`) plus Lyndon “words” helpers (`lyndon_words`, `logsigdim_words`, `logsigkeys_words`) for inspecting dimensions and basis labels.
- Two log-signature coordinate systems: Signatory-style “words” (Lyndon, default) and Hall.
- Two log-signature backends: the default signature→log path, and an incremental sparse BCH implementation for depths up to 4 (falls back otherwise).
- The implementation of signatures is structured after keras_sig, but only focuses on pytorch.
- Dependencies are kept minimal.


## Installation

Requires Python 3.13+ and PyTorch ≥ 2.9 (CPU or CUDA builds work).  To install from pypi using pip:

```bash
pip install log-signatures-pytorch
```


From the repository root:

```bash
uv venv
source .venv/bin/activate
uv sync                    # installs runtime deps + project in editable mode
```

Verify PyTorch is available:

```bash
python - <<'PY'
import torch
print("torch version:", torch.__version__)
print("cuda available:", torch.cuda.is_available())
PY
```

## Quick start

### Signature and log-signature of a single path

```python
import torch
from log_signatures_pytorch import signature, log_signature, logsigdim_words

path = torch.tensor([[0.0, 0.0], [1.0, 1.0], [2.0, 0.0]]).unsqueeze(0)

sig = signature(path, depth=2)
print(sig.shape)           # torch.Size([1, 6]) = sum(width**k for k in 1..depth)

log_sig = log_signature(path, depth=2)
print(log_sig.shape)       # torch.Size([1, 3]) = logsigdim_words(2, 2)
print("logsigdim_words:", logsigdim_words(2, 2))  # 3

# Lyndon words coordinates (Signatory-style)
log_sig_words = log_signature(path, depth=2, mode="words")
print(log_sig_words.shape)  # torch.Size([1, 3])
```

### Batched computation and streaming outputs

```python
batch_paths = torch.tensor([
    [[0.0, 0.0], [1.0, 1.0]],
    [[0.0, 0.0], [2.0, 2.0]],
])

sig = signature(batch_paths, depth=2)
print(sig.shape)                 # torch.Size([2, 6])

log_sig_stream = log_signature(batch_paths, depth=2, stream=True)
print(log_sig_stream.shape)      # torch.Size([2, 1, 3]) -> (batch, steps, logsigdim)

# Streaming for a single path returns one row per increment (batch=1)
sig_stream = signature(path, depth=2, stream=True)
print(sig_stream.shape)          # torch.Size([1, 2, 6])
```

### Sliding-window signatures and log-signatures

```python
import torch
from log_signatures_pytorch import windowed_signature, windowed_log_signature

path = torch.tensor([[0.0, 0.0], [1.0, 1.0], [2.0, 0.0], [3.0, -1.0]]).unsqueeze(0)
width = path.shape[-1]
window_size = 4
hop_size = 2

win_sig = windowed_signature(path, depth=2, window_size=window_size, hop_size=hop_size)
print(win_sig.shape)   # torch.Size([batch, num_windows, 6])

win_logsig = windowed_log_signature(
    path, depth=2, window_size=window_size, hop_size=hop_size, mode="words"
)
print(win_logsig.shape)  # torch.Size([batch, num_windows, logsigdim_words(width, 2)])
```

### Hall basis helpers

```python
from log_signatures_pytorch import hall_basis, logsigkeys

basis = hall_basis(width=2, depth=2)
print(basis)          # [1, 2, (1, 2)]

keys = logsigkeys(width=2, depth=2)
print(keys)           # ['1', '2', '[1,2]'] (matches esig format)

# Lyndon words helpers
from log_signatures_pytorch import lyndon_words, logsigkeys_words
words = lyndon_words(width=2, depth=3)
print(words)          # [(1,), (2,), (1, 2), (1, 1, 2), (1, 2, 2)]
print(logsigkeys_words(width=2, depth=3))
```

### Choosing computation mode

- `method`: `log_signature(..., method="bch_sparse")` uses the incremental BCH routine for depths supported by `HallBCH` (depth ≤ 4); otherwise it falls back to the default path.
- `mode`: `log_signature(..., mode="words"|"hall")` chooses the coordinate basis. Default is `"words"`. BCH currently requires `mode="hall"`; the default path supports both.

Signature outputs exclude the empty word (dimension is `sum(width**k for k=1..depth)`); use `logsigdim(width, depth)` to size log-signature outputs.

### GPU compile recommendations

- For fixed shapes with many repeated calls, `torch.compile` with mode `reduce-overhead` gives the fastest runtime for `signature` (~0.08–0.12 ms in our sweeps) and for `log_signature` (similarly sized speedups). First-call compile time can be large—especially for log-signatures—so cache per shape if you need to reuse compiled artifacts.
- For workloads with many varying shapes or when compile latency matters more than per-call speed, prefer `none` (no compile) or the lighter `default` mode. `default` is slower than `reduce-overhead` at runtime but compiles much faster; this tradeoff is more pronounced for log-signatures.
- The benchmark helper `benchmarks/benchmark_batch_signature.py` supports `--target signature|log_signature`, `--compile-modes none reduce-overhead default`, `--measure-compile-time`, and per-shape compile caching. CSVs land under `benchmarks/results/` by default.

## Testing and verification

- Run the suite: `pytest tests -q`
- Mathematical property checks are documented in `tests/mathematical_verification_guide.md`.

## Documentation

Documentation is built using MkDocs with mkdocstrings and Material theme. To build and serve the documentation:

```bash
# Build static site
uv run mkdocs build

# Serve locally (with auto-reload on changes)
uv run mkdocs serve
```

The documentation will be available at `http://127.0.0.1:8000` when serving locally.

## References

- esig: https://github.com/datasig-ac-uk/esig

Kidger, Patrick and Lyons, Terry, Signatory: differentiable computations of the signature and logsignature transforms, on both CPU and GPU, ICLR 2021.  Repository: https://github.com/patrick-kidger/signatory

Genet, R., & Inzirillo, H. (2025). Keras sig: Efficient path signature computation on gpu in keras 3. arXiv preprint arXiv:2501.08455. Repository: https://github.com/remigenet/keras_sig

## License

MIT


## Citation

If you use this software in your research or in your project, please cite it as follows:

### BibTeX

```bibtex
@software{log_signatures_pytorch,
  author = {Aune, Erlend},
  title = {log-signatures-pytorch: Differentiable log-signature and signature kernels in PyTorch},
  version = {0.1.x},
  url = {https://github.com/froskekongen/log_signatures_pytorch},
  year = {2025},
  license = {MIT}
}
```

### Plain text

Aune, Erlend. (2025). log-signatures-pytorch: Differentiable log-signature and signature kernels in PyTorch (Version 0.1.x). [Computer software]: https://github.com/froskekongen/log_signatures_pytorch
