Skip to content
proffitteoyPublic

Repository files navigation

Topp mark

Topp

Exact Bottleneck and Wasserstein distances for persistence diagrams.

CI status PyPI version Python versions

中文 · 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.x compatibility contract. The C++ headers and ABI remain kernel-maintenance interfaces and are not covered by that stability promise.

When Topp fits

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∞, or W2-L2 semantics 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.

Provided capabilities

  • exact Bottleneck distance with the internal L∞ metric;
  • exact W1-L∞ and W2-L2 Wasserstein distances;
  • immutable PreparedDiagram objects and native one-to-many operations;
  • reusable output arrays and exact bottleneck_within threshold 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.

Installation

py -m pip install topp

Prebuilt 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.

Quick start

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.

Batch comparisons with reusable memory

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
)

Supported metrics

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

Input contract

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.

Kernel maintenance boundary

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.

Development

py -m pip install -v .
py -m pytest tests/python
cmd.exe /d /c scripts\build-kernel.cmd

The existing include/bottleneck/* C++ interface supports community maintenance and kernel experiments; it does not promise a stable ABI. See the development guide.

Project links

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

Citing

For research use, cite the repository version and release tag. Machine-readable metadata is available in CITATION.cff.

License

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.

Releases

Packages

Contributors

Languages