Topp

English · 使用说明 · API · 开发指南

Topp 是一个精简的 persistence diagram 距离包。它只专注于 exact Bottleneck 和两种 exact Wasserstein 距离，并由自适应 C++20 内核完成计算。

v0.1.0 内测版： PyPI 会把 0.1.0 视为正式版本号，但本项目仍处于公开内测阶段；Python API 已冻结，Wasserstein 内核仍会继续优化。

特性

  • exact Bottleneck Distance（点间使用 L∞）；
  • exact W1-L∞ 与 W2-L2 Wasserstein Distance；
  • 不可变的 PreparedDiagram；
  • 原生 one-to-many 批量计算与可复用输出数组；
  • exact threshold decision：bottleneck_within；
  • Windows x64 的 CPython 3.10–3.14 wheels；
  • 运行时仅依赖 NumPy；AVX2 路径在运行时检测，不要求所有机器支持 AVX2。

安装

py -m pip install topp

首发 wheel 面向 Windows x64。其他平台可以从 sdist 构建，但需要 CMake 3.24+ 和 C++20 编译器。

快速开始

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))

完整示例见 examples/basic.py。

支持的度量

函数 语义 状态
bottleneck_distance exact Bottleneck，内部 L∞ 支持
wasserstein_distance(..., order=1, internal_p=np.inf) exact W1-L∞ 支持
wasserstein_distance(..., order=2, internal_p=2) exact W2-L2 支持
其他 Wasserstein 参数 数学上可能合法 NotImplementedError

输入契约

输入必须可转换为 (n, 2) 的 float64 数组。空图、对角点、重复点和规范 essential points 合法。NaN、birth > death、birth=+inf、death=-inf 及其他非法无穷组合会抛出 ValueError，不会被静默修正。

详见 API 文档。

实验功能

C++ 源码保留候选生成、图表示、matching、component 和 incremental pricing 等实验策略，供维护者复现与比较。它们不会暴露到普通 Python API，也不代表默认性能承诺。研究证据和历史方案见 docs/research。

开发

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

现有 include/bottleneck/* C++ 接口用于社区维护和内核实验，不承诺稳定 ABI。构建、测试和 benchmark 约定见 开发指南。

引用

研究中使用 Topp 时，请引用仓库版本与发布标签。机器可读元数据见 CITATION.cff。

许可

Topp 使用 MIT License。GUDHI 仅作为测试 oracle、语义参考及历史补丁来源，不是运行时依赖；详情见 第三方声明。

Project links

Data verified by PyPI on Aug 12, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for proffitteoy from gravatar.com proffitteoy

Credits

Author: Topp contributors

GitHub Statistics

Data verified by PyPI on Aug 12, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.10

Provides Extra

test

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

topp-0.1.0.tar.gz (173.3 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

topp-0.1.0-cp314-cp314-win_amd64.whl (426.6 kB view details)

Uploaded CPython 3.14Windows x86-64

topp-0.1.0-cp313-cp313-win_amd64.whl (413.7 kB view details)

Uploaded CPython 3.13Windows x86-64

topp-0.1.0-cp312-cp312-win_amd64.whl (413.7 kB view details)

Uploaded CPython 3.12Windows x86-64

topp-0.1.0-cp311-cp311-win_amd64.whl (412.1 kB view details)

Uploaded CPython 3.11Windows x86-64

topp-0.1.0-cp310-cp310-win_amd64.whl (411.3 kB view details)

Uploaded CPython 3.10Windows x86-64

File details

Details for the file topp-0.1.0.tar.gz.

File metadata

  • Download URL: topp-0.1.0.tar.gz
  • Upload date:
  • Size: 173.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for topp-0.1.0.tar.gz
Algorithm Hash digest
SHA256 fe85ffd1cad8419feba024c10039b40dd1e24e04ac61766b402fd568a76646f4
MD5 8a9eadadeb647ef7fe0f42413d64026e
BLAKE2b-256 ccb8676b8e01019d32324311fac8891cc5540f365d872e681e49153e56fe268c

See more details on using hashes here.

File details

Details for the file topp-0.1.0-cp314-cp314-win_amd64.whl.

File metadata

  • Download URL: topp-0.1.0-cp314-cp314-win_amd64.whl
  • Upload date:
  • Size: 426.6 kB
  • Tags: CPython 3.14, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for topp-0.1.0-cp314-cp314-win_amd64.whl
Algorithm Hash digest
SHA256 3a476a38e1a7c843f070a7a95066ec1b82b7a05eb035f1d6c85858ad4fcf5994
MD5 5ada5a121d61237aac6ce5b702cdc3dc
BLAKE2b-256 0e8e59bc198bb17eb8cb017d994306e31c219998ecf1f41eb67d4641806f045d

See more details on using hashes here.

File details

Details for the file topp-0.1.0-cp313-cp313-win_amd64.whl.

File metadata

  • Download URL: topp-0.1.0-cp313-cp313-win_amd64.whl
  • Upload date:
  • Size: 413.7 kB
  • Tags: CPython 3.13, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for topp-0.1.0-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 86ee1f9d2604d3ccfd5fdae3af57c1d46e20794af88897bfa7d11f9845c142e7
MD5 1aa764ae668e21920c729e91b49d68cc
BLAKE2b-256 489a887dc284d8617a4c822d238241fc1ba1ab1472a45916f36367c1d4934f71

See more details on using hashes here.

File details

Details for the file topp-0.1.0-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: topp-0.1.0-cp312-cp312-win_amd64.whl
  • Upload date:
  • Size: 413.7 kB
  • Tags: CPython 3.12, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for topp-0.1.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 e2a08d1c67ddec598c7f3af53ead6b90b8addb0ada50c6d1025424a2ad40dac2
MD5 ad0a25521b72584f678c59d3d3269ebf
BLAKE2b-256 94699d9a52fe0ef84d37fc1acfe07ef9665d8475b446793ec22b170e9942a4fe

See more details on using hashes here.

File details

Details for the file topp-0.1.0-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: topp-0.1.0-cp311-cp311-win_amd64.whl
  • Upload date:
  • Size: 412.1 kB
  • Tags: CPython 3.11, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for topp-0.1.0-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 272121ad829ea1180201c1894bad78d58ffc243b8c4e6e85b200989e1875050d
MD5 35ccfa663e201c4dbd2416fa756ea5d3
BLAKE2b-256 092703fa72ee370cf67886887381beea5231bf0df11707c3e225bb6459ca8bb6

See more details on using hashes here.

File details

Details for the file topp-0.1.0-cp310-cp310-win_amd64.whl.

File metadata

  • Download URL: topp-0.1.0-cp310-cp310-win_amd64.whl
  • Upload date:
  • Size: 411.3 kB
  • Tags: CPython 3.10, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for topp-0.1.0-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 2cd346a878082ff65313ed1b9de32fd129a3b856b87903293e07022960812276
MD5 2946919be89e2e8b51adc265e14df860
BLAKE2b-256 d3a24c7029203cfa8ddd129559fc35e410a286c2b4ae57869b89c9e22d8e489f

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page