monoprop-bench-tools

The benchmark harness behind monoprop: the pieces that are reusable outside a single benchmark run, packaged separately so scripts, notebooks and third-party comparisons can depend on them without vendoring the repository's benches/ directory.

Install

pip install monoprop-bench-tools

GPU support

monoprop_bench_tools.memory.gpu needs CuPy, and only CuPy. Pick the extra matching your CUDA toolkit:

pip install "monoprop-bench-tools[gpu-cuda12]"   # CUDA 12.x
pip install "monoprop-bench-tools[gpu-cuda13]"   # CUDA 13.x

Pick one, not both: the two CuPy builds ship the same top-level cupy package. On a host with no system CUDA toolkit, add CuPy's bundled one with pip install "cupy-cuda12x[ctk]".

Without CuPy the module still imports, and every reading reports Method.UNAVAILABLE instead of a figure you might mistake for a real one.

Use

Measure the peak resident footprint of a block, exactly (no sampling):

from monoprop_bench_tools.memory.cpu import HighWaterMark
from monoprop_bench_tools.models import build_hubbard_problem

with HighWaterMark() as hwm:
    propagator, circuit = build_hubbard_problem()
    propagator.build_graph(circuit)

print(f"{hwm.peak_mb:.0f} MB peak, exact={hwm.exact}")

Render the artifacts of a run:

monoprop-bench-report benches/results             # writes REPORT.md
monoprop-bench-bmf benches/results ci-bare-metal-L1   # BMF JSON on stdout

Both read the two files a run leaves in the results directory: time-<label>.json (pytest-benchmark timings) and <label>.json (memory, operator sizes, configuration). The schema is documented in the repository's benches/results/README.md, and written by the suite in benches/conftest.py.

Scope

This package deliberately holds no benchmarks. monoprop's own suite lives in the repository's benches/ directory, because its benchmark names are the key Bencher's history is stored under and must not move with a library release.

bmf.benchmark_name maps a pytest node id to the name a metric is exported under, so that mapping is history-bearing for the same reason: changing it renames every series it touches.

License

Apache-2.0. See LICENSE.