HilbertBench

Diagnose quantum ML experiments without changing a line of algorithm code.

HilbertBench is a non-intrusive diagnostic framework for quantum machine learning. You wrap one object — an Estimator, Sampler, or PennyLane device — and every circuit execution is silently recorded into an append-only, cryptographically sealed trace. Nothing else in your code changes.

After the run you call built-in analyzers to diagnose trainability, shot noise, optimization convergence, circuit structure, expressibility, and hardware noise — all from the evidence already in the trace.

Install

# Default: runs the Qiskit workflow out of the box
# (trace core + Qiskit integration + Parquet storage)
pip install hilbertbench

# Add the PennyLane integration
pip install hilbertbench[pennylane]

# Everything (Qiskit + PennyLane + storage)
pip install hilbertbench[full]

The default install covers the documented Qiskit path. PennyLane is the one optional integration; if you use it without installing it, the error tells you exactly which extra to add.

The one-line change

from hilbertbench.integrations.qiskit import HilbertEstimatorProxy
from hilbertbench.recorder.tape import HilbertTape
from hilbertbench.analysis import detect_barren_plateau
from hilbertbench import HilbertTrace

# Wrap the estimator — everything else stays the same
with HilbertTape("runs/my_vqe", tags={"algorithm": "vqe"}) as tape:
    estimator = HilbertEstimatorProxy(tape)   # ← the only change
    # ... your existing optimizer loop, completely unchanged ...

# Analyze the sealed trace
trace = HilbertTrace(tape.dir_path)
print(detect_barren_plateau(trace))
# {'status': 'Trainable', 'variance': 0.215, 'variance_ci': [0.098, 0.371], ...}

Built-in analyzers

from hilbertbench.analysis import summary

report = summary(trace)   # runs all analyzers, returns one dict

Integrations

Tutorials

Four end-to-end tutorials, each diagnosing a real quantum ML failure mode:

Documentation

The learning site builds from mkdocs.yml, the reference site from mkdocs-rtd.yml. After adding tests, refresh the catalog with python tools/gen_test_catalog.py.

Design guarantees

• Non-intrusive — the proxy never re-executes circuits, modifies shot counts, or alters your algorithm (INV-001)
• Immutable traces — every trace is append-only and sealed with a SHA-256 hash on close (INV-002)
• Evidence, not verdicts — raw execution data is stored; diagnostic conclusions are computed at read time and never written back (INV-006)
• No silent failures — every initiated span ends with a COMPLETED or ERROR event (INV-007)

Those INV-NNN codes appear throughout the source comments and docstrings. Each is a numbered, non-negotiable guarantee; the complete, canonical list (INV-001 … INV-008) lives in docs/reference/invariants.md (rendered on the reference site). When you see an INV-NNN tag in the code, that is where it is defined.

Acknowledgments

HilbertBench was developed by Md. Abdullah Al Mamun in the Neural Engineering Data Consortium (NEDC), lab at Temple University, under the advisorship of Prof. Joseph Picone (Department of Electrical and Computer Engineering). The author is grateful to Dr. Picone for his guidance and for the research environment in which this work was carried out.

Citing HilbertBench

If you use HilbertBench in your research, please cite it using the metadata in CITATION.cff. On the GitHub project page, that file makes a "Cite this repository" button appear automatically in the right-hand sidebar (it is a GitHub feature, not a README badge, and only shows once the repository is on GitHub). A DOI badge will be added here once the first release is archived on Zenodo.

License

MIT. See LICENSE.