Exact Bottleneck and Wasserstein distances for persistence diagrams.
中文 · Website · Usage · API · Mathematics · Development · Changelog
Topp is for users who already have persistence diagrams and need strict, repeated distance comparisons in Python. It provides a small Python API backed by an adaptive C++20 kernel. Prepare a diagram once and use native batch operations when comparing it with many candidates.
v1.0.1 stable release: The documented Python API now follows the
1.xcompatibility contract. The C++ headers and ABI remain kernel-maintenance interfaces and are not covered by that stability promise.
Choose Topp when you:
- already obtain persistence diagrams from GUDHI, Ripser, or another pipeline and only need distances between them;
- need exact Bottleneck,
W1-L∞, orW2-L2semantics without an approximation parameter changing threshold decisions; - repeatedly compare one query with many candidates and want to reuse preprocessing, workspace, or output memory;
- want a typed Python API with NumPy as its only runtime dependency.
Topp does not compute persistence diagrams and does not provide arbitrary (order, internal_p) pairs, approximate/GPU distances, or a complete TDA workflow. Use a broader TDA library when those capabilities are required. The public documentation includes a Python batch-distance comparison with GUDHI and Hera; the results apply only to the stated environment and call pattern.
- exact Bottleneck distance with the internal
L∞metric; - exact
W1-L∞andW2-L2Wasserstein distances; - immutable
PreparedDiagramobjects and native one-to-many operations; - reusable output arrays and exact
bottleneck_withinthreshold decisions; - GIL release during native computation;
- Windows x64 and Linux x86_64 wheels for CPython 3.10–3.14;
- NumPy as the only runtime dependency; AVX2 is selected at runtime and is not required.
py -m pip install toppPrebuilt wheels target Windows x64 and Linux x86_64. macOS source builds may work with CMake 3.24+ and a C++20 compiler, but macOS is not yet covered by CI and is not a validated platform.
import numpy as np
import topp
x = np.array([[0.0, 1.0], [0.3, 0.8]])
y = np.array([[0.0, 1.1], [0.4, 0.9]])
print(topp.bottleneck_distance(x, y))
print(topp.wasserstein_distance(x, y, order=2, internal_p=2))
query = topp.prepare_diagram(x)
print(topp.bottleneck_distances(query, [y, np.empty((0, 2))]))
print(topp.bottleneck_within(query, y, 0.1))See examples/basic.py for a complete runnable example.
targets = [y, np.empty((0, 2))]
out = np.empty(len(targets), dtype=np.float64)
query = topp.prepare_diagram(x)
topp.wasserstein_distances(
query, targets, order=2, internal_p=2, out=out
)| Function | Meaning | Status |
|---|---|---|
bottleneck_distance |
exact Bottleneck, internal L∞ |
supported |
wasserstein_distance(..., order=1, internal_p=np.inf) |
exact W1-L∞ |
supported |
wasserstein_distance(..., order=2, internal_p=2) |
exact W2-L2 |
supported |
| other Wasserstein parameters | potentially valid mathematically | NotImplementedError |
Inputs must contain Python/NumPy real numbers, Decimal, or Fraction values and convert to a float64 array of shape (n, 2). Complex values, masked arrays, booleans, numeric strings, and finite values outside the float64 range are rejected. Empty diagrams, diagonal points, duplicates, and canonical essential points are valid. NaN, birth > death, birth=+inf, death=-inf, and other invalid infinity forms raise ValueError and are never silently repaired.
See Mathematical conventions for distance definitions, diagonal costs, duplicates, and essential points. See the API reference for the call contract.
The C++ source retains explicit candidate, graph, matching, component, and incremental-pricing strategies for regression testing, ablation, and maintenance. They are not exposed through the public Python API and are not default performance claims. See the 1.0 kernel final state for the default paths, retained benchmarks, and rejected routes.
py -m pip install -v .
py -m pytest tests/python
cmd.exe /d /c scripts\build-kernel.cmdThe existing include/bottleneck/* C++ interface supports community maintenance and kernel experiments; it does not promise a stable ABI. See the development guide.
| Entry | Contents |
|---|---|
| Project website | Use cases, installation, API, and mathematical overview |
| Usage guide | Installation, scalar and batch calls, output arrays, and errors |
| API reference | Complete public API and input contract |
| Mathematical conventions | Distances, diagonal costs, duplicates, and essential points |
| Development guide | Local builds, tests, and benchmarks |
| Contributing | Requirements for correctness and performance changes |
| Research notes | 1.0 final state, kernel experiments, and differential evidence |
| Changelog | Released capabilities and known limitations |
For research use, cite the repository version and release tag. Machine-readable metadata is available in CITATION.cff.
Topp is licensed under the MIT License. GUDHI is used only as a test oracle, semantic reference, and source of a historical patch; it is not a runtime dependency. See third-party notices.