pysiglib.tree_to_idx

pysiglib.tree_to_idx#

tree_to_idx(tree, dimension, degree, *, planar=False, scalar_term=False)[source]#

Given a basis element, returns its flat index in the branched-signature coefficient vector.

Trees use the native pySigLib tuple convention:

  • Empty tree: None - index 0 when scalar_term=True; invalid otherwise

  • Leaf: (label,) where label is in [0, dimension)

  • Internal node: (child_1, child_2, ..., root_label)

  • Planar ordered forest: (tree_1, tree_2, ...) when planar=True

With scalar_term=True the empty tree sits at index 0. With scalar_term=False (default) there is no empty-tree entry, so all indices shift down by 1 and None is invalid.

In the planar case, the branched-signature basis is indexed by ordered forests. Passing a single tree is accepted as shorthand for the one-tree forest.

Parameters:

  • tree (tuple | None) – Decorated rooted tree, ordered forest, or None for empty when scalar_term=True.

  • dimension (int) – Path dimension (alphabet size).

  • degree (int) – Maximum number of nodes (same as degree in branched_sig()).

  • planar (bool) – If True, use the planar ordered-forest enumeration matching branched_sig(..., planar=True).

  • scalar_term (bool) – Whether the target branched signature includes the leading scalar 1 at index 0. Must match the format of the bsig you intend to index. Default False.

Returns:

Flat index in the branched signature vector.

Return type:

int

Example:#

import torch
import pysiglib

path = torch.rand(size=(100, 2))
pysiglib.prepare_branched_sig(2, 3)
bsig = pysiglib.branched_sig(path, 3)  # scalar_term=False

tree = ((1,), 0)
idx = pysiglib.tree_to_idx(tree, dimension=2, degree=3)
print(f"Index: {idx}, Coefficient: {bsig[idx]}")

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