phlite_grpph¶

Classes¶

`Algorithm`	A reduction algorithm and its options.
`Barcode`	A persistence barcode, split by dimension.

Functions¶

grpph(…)

Module Contents¶

class phlite_grpph.Algorithm¶

A reduction algorithm and its options.

Start from a preset, Algorithm.serial() or Algorithm.parallel(), which are the recommended configurations, or from one of the algorithms themselves, Algorithm.standard(), Algorithm.clearing() or Algorithm.parallel_clearing(), then adjust it with the with_* methods (each returns a new Algorithm):

Algorithm.parallel(threads=8)
Algorithm.clearing().with_columns("heap").with_skip_zero_apparent_pairs(False)

Pass the result as the algorithm argument. Every algorithm gives the same barcode; only the time and memory differ.

static clearing() → Algorithm¶: The standard algorithm with the clearing optimisation. Skips zero-length apparent pairs by default.

static parallel(threads: int | None = None) → Algorithm¶: The recommended parallel algorithm: clearing with each dimension reduced in parallel, skipping zero-length apparent pairs, on threads threads (default: all cores). The same as parallel_clearing().with_threads(threads) (and shown as that).

static parallel_clearing() → Algorithm¶: Clearing, with the columns of each dimension reduced in parallel. Skips zero-length apparent pairs by default, and uses all cores and locking storage.

static serial() → Algorithm¶: The recommended serial algorithm: clearing, skipping zero-length apparent pairs. The same as clearing() (and shown as that).

static standard() → Algorithm¶: The standard algorithm, with no optimisations.

with_cache(cache: bool = True) → Algorithm¶

Whether to cache the columns of the boundary matrix as they are added during the reduction. The presets cache in phlite_grpph, but not in phlite_rips, whose columns are cheap to recompute, nor in phlite, whose columns are stored sorted.

Caching saves recomputing (and re-sorting) a column every time it is added, which pays off when columns are expensive to compute (about 3× faster for GrPPH), but keeps every column needed in a dimension in memory until that dimension is done (most of the memory for Vietoris–Rips). For phlite.ChainComplex, whose columns are stored sorted, it only saves copying them, and with the default pivot columns and stored R it is slower: about 20% on cell complexes and nearly 2× on cubical complexes.

with_columns(columns: Literal['merged', 'heap', 'sorted', 'pivot']) → Algorithm¶

How the column being reduced is represented: 'merged', 'heap', 'sorted' or 'pivot'. The presets use 'merged' in phlite_grpph, 'heap' in phlite_rips and 'pivot' in phlite. Every choice gives the same barcode; only time and memory differ.

Reducing a column means repeatedly finding its pivot (largest entry) and adding other columns to cancel it.

'merged' never builds the column: it merges the columns added lazily, with one heap slot per column added, so it never reads anything below the pivot. The safe choice, fast on every kind of matrix tried.
'heap' pushes every entry of every column added onto one heap. No sorting, so it is good when the columns added are short and few (e.g. Vietoris–Rips cohomology), but slows down when many entries are added.
'sorted' keeps the column as one sorted vector and merges each batch of added columns into it. The fastest when the columns added stay near the pivot (typically homology of simplicial or cell complexes, about 1.5× faster than 'merged'), but very slow when they reach far below it (15–35× slower on GrPPH or the cohomology of cubical complexes). Measure before using it.
'pivot' keeps the column as a dense array over all rows, with a tree of bitsets marking which are present (as PHAT does): adding an entry flips a bit, and the pivot is found with a few bit-scans. The fastest when many columns are added to each, as for dense or cubical complexes, especially with with_store_r(). Needs a matrix that knows the rank of every row in filtration order (phlite’s explicit complexes do, Vietoris–Rips and GrPPH don’t), and only serial clearing uses it: otherwise asking for it is an error.

with_dimension_order(dimension_order: Sequence[int] | None) → Algorithm¶

The order in which to reduce dimensions (clearing algorithms only), or None to detect it from the matrix.

Clearing saves work when dimensions are reduced in the direction the matrix maps them (ascending for cohomology, descending for homology), which is what is detected. Only the dimensions listed are reduced, so list every dimension the barcode needs.

with_skip_zero_apparent_pairs(skip: bool = True) → Algorithm¶

Whether to leave zero-length apparent pairs out of the diagram (clearing algorithms only).

Such pairs give zero-length bars, which the barcode omits anyway, but in many filtrations nearly every pair is one, so recording them dominates the time and memory of the reduction.

with_storage(storage: Literal['locking', 'lock-free']) → Algorithm¶: The concurrent data structures for the parallel algorithm: 'locking' (the default) or 'lock-free'.

with_store_r(store: bool = True) → Algorithm¶

Whether to keep each reduced column of R = D V and add it directly when cancelling a pivot, rather than recompute it from V (serial clearing only). The presets store R in phlite, but not in phlite_rips or phlite_grpph, where almost every column is an apparent pair and needs no reduction.

Only V is stored by default, so cancelling a pivot with an earlier column j adds one column of the boundary matrix for every term of V_j. Storing R (as PHAT does) adds R_j as one column instead, which pays off when V_j gets long, as in dense or cubical complexes, at the cost of memory for the stored columns. Vietoris–Rips cohomology, where almost every pair needs no reduction, gains little.

with_threads(threads: int | None) → Algorithm¶: The number of threads for the parallel algorithm, or None for all cores.

property cache: bool¶: Whether columns of the boundary matrix are cached.

property columns: str¶: 'merged', 'heap', 'sorted' or 'pivot'.

property dimension_order: list[int] | None¶: The order dimensions are reduced in, or None if detected.

property name: str¶: 'standard', 'clearing' or 'parallel-clearing'.

property skip_zero_apparent_pairs: bool¶: Whether zero-length apparent pairs are skipped.

property storage: str | None¶: 'locking' or 'lock-free' for the parallel algorithm, else None.

property store_r: bool¶: Whether reduced columns of R are stored (serial clearing only).

property threads: int | None¶

all cores).

Type:: The number of threads for the parallel algorithm (None

class phlite_grpph.Barcode¶

A persistence barcode, split by dimension.

Bars of length zero are omitted. Within each dimension, bars are sorted by birth (and then death).

property essential: list[list[float]]¶: essential[k] lists the birth times of the infinite bars in dimension k.

property essential_representatives: list[list[list[tuple[int, ...]]]] | None¶

essential_representatives[k][i] is a cycle representing the bar essential[k][i], or None if representatives were not requested.

A cycle is a list of cells, each given as a tuple of vertices (indices, or node labels for a networkx graph).

property pairing_representatives: list[list[list[tuple[int, ...]]]] | None¶

pairing_representatives[k][i] is a cycle representing the bar pairings[k][i], or None if representatives were not requested.

A cycle is a list of cells, each given as a tuple of vertices (indices, or node labels for a networkx graph).

property pairings: list[list[tuple[float, float]]]¶: pairings[k] lists the (birth, death) times of the finite bars in dimension k.

phlite_grpph.grpph(graph: networkx.DiGraph, /, *, weight: str = 'weight', method: Literal['cohomology', 'homology'] = 'cohomology', algorithm: Algorithm | None = None, representatives: bool = False) → Barcode¶
phlite_grpph.grpph(n_vertices: int, edges: Sequence[tuple[int, int, float]], /, *, method: Literal['cohomology', 'homology'] = 'cohomology', algorithm: Algorithm | None = None, representatives: bool = False) → Barcode