Developing Topp¶
Regular users consume only the Python API. include/bottleneck/*, experimental strategies, and benchmarks support community maintenance and do not promise a stable C++ ABI.
Python build and tests¶
Requirements: Python 3.10+, CMake 3.24+, and a C++20 compiler. Visual Studio 2022 Build Tools are recommended on Windows; Linux uses GCC/Clang and Ninja.
py -m pip install -v .
py -m pip install pytest
py -m pytest tests/python
Linux:
python3 -m venv .venv
.venv/bin/python -m pip install -v ".[test]"
.venv/bin/python -m pytest tests/python -m "not oracle"
.venv/bin/python -m mypy --strict tests/python/typecheck_api.py
.venv/bin/python -m mypy.stubtest topp
The oracle suite requires pinned GUDHI 3.13.0:
$env:TOPP_RUN_ORACLE_TESTS='1'
py -m pytest tests/python/test_oracles.py
C++ kernel¶
cmd.exe /d /c scripts\build-kernel.cmd
build\manual\bottleneck_core_tests.exe
build\manual\wasserstein_core_tests.exe
Linux:
cmake -S . -B build/linux -G Ninja -DCMAKE_BUILD_TYPE=Release -DBOTTLENECK_BUILD_BENCHMARKS=OFF
cmake --build build/linux
ctest --test-dir build/linux --output-on-failure
Disable AVX2 translation units to validate the scalar build:
cmake -S . -B build\scalar -G Ninja -DCMAKE_BUILD_TYPE=Release -DBOTTLENECK_ENABLE_AVX2=OFF
cmake --build build\scalar
ctest --test-dir build\scalar --output-on-failure
Benchmarks¶
See benchmarks/README.md for commands and fair-comparison rules. Raw output belongs in ignored benchmarks/results/; commit only reproducible commands, fixed inputs/seeds, and bounded conclusions.
Experimental strategies must pass reference/oracle differentials before randomized-order median/p95 comparisons. Keep conclusions for failed routes and do not add them to the default dispatcher.
Layout¶
python/topp/: public Python layer and type information;python/bindings.cpp: private pybind11 extension;include/,src/: exact C++20 kernel;tests/python/,tests/*.cpp: Python/C++ correctness;benchmarks/: reproducible kernel benchmarks;docs/research/: the 1.0 final state, experimental conclusions, and historical patches.