hilbertbench 1.0.0__tar.gz

hilbertbench-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Md. Abdullah Al Mamun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hilbertbench-1.0.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: hilbertbench
+Version: 1.0.0
+Summary: Non-intrusive diagnostic framework for evaluating scientific claims in quantum machine learning
+Author-email: "Md. Abdullah Al Mamun" <mamun.cseian@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://mamuncseru.github.io/hilbertbench/
+Project-URL: Documentation, https://hilbertbench.readthedocs.io
+Project-URL: Repository, https://github.com/mamuncseru/hilbertbench
+Project-URL: Issues, https://github.com/mamuncseru/hilbertbench/issues
+Project-URL: Research Group, https://www.nedcdata.org/
+Keywords: quantum-machine-learning,quantum-computing,diagnostics,barren-plateau,expressibility,nisq,qiskit,observability,reproducibility
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.6.0
+Requires-Dist: qiskit>=1.0.0
+Requires-Dist: pyarrow>=14.0.0
+Provides-Extra: storage
+Requires-Dist: pyarrow>=14.0.0; extra == "storage"
+Provides-Extra: qiskit
+Requires-Dist: qiskit>=1.0.0; extra == "qiskit"
+Provides-Extra: pennylane
+Requires-Dist: pennylane>=0.38.0; extra == "pennylane"
+Provides-Extra: full
+Requires-Dist: hilbertbench[pennylane,qiskit,storage]; extra == "full"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: mypy>=1.7.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Requires-Dist: jsonschema>=4.21.0; extra == "dev"
+Requires-Dist: datamodel-code-generator; extra == "dev"
+Requires-Dist: pennylane>=0.38.0; extra == "dev"
+Requires-Dist: qiskit-ibm-runtime>=0.20.0; extra == "dev"
+Requires-Dist: qiskit-aer>=0.13.0; extra == "dev"
+Requires-Dist: pandas>=2.0.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
+Dynamic: license-file
+
+# HilbertBench
+
+> Diagnose quantum ML experiments without changing a line of algorithm code.
+
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Tests](https://github.com/mamuncseru/hilbertbench/actions/workflows/tests.yml/badge.svg)](https://github.com/mamuncseru/hilbertbench/actions/workflows/tests.yml)
+[![Docs](https://img.shields.io/badge/docs-readthedocs-blueviolet)](https://hilbertbench.readthedocs.io)
+
+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
+
+```bash
+# 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
+
+```python
+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
+
+| Function | What it answers |
+|---|---|
+| `detect_barren_plateau` | Is the cost-landscape variance exponentially suppressed? |
+| `shot_noise_ratio` | Is the optimizer chasing signal or shot noise? |
+| `optimization_convergence` | Is the parameter trajectory still moving? |
+| `circuit_structure` | How deep, how many qubits, what gate composition? |
+| `kl_expressibility` | How uniformly does the ansatz cover Hilbert space? |
+| `noise_profile` | What hardware noise levels did the run experience? |
+
+```python
+from hilbertbench.analysis import summary
+
+report = summary(trace)   # runs all analyzers, returns one dict
+```
+
+---
+
+## Integrations
+
+| Framework | Proxy class | Install extra |
+|---|---|---|
+| Qiskit V2 Estimator | `HilbertEstimatorProxy` | `hilbertbench[qiskit]` |
+| Qiskit V2 Sampler | `HilbertSamplerProxy` | `hilbertbench[qiskit]` |
+| IBM Quantum hardware | `HilbertEstimatorProxy` with `EstimatorV2(mode=backend)` | `hilbertbench[qiskit]` |
+| PennyLane | `HilbertPennyLaneDeviceProxy` | `hilbertbench[pennylane]` |
+
+---
+
+## Tutorials
+
+Four end-to-end tutorials, each diagnosing a real quantum ML failure mode:
+
+| # | Tutorial | Concepts |
+|---|---|---|
+| 01 | [Why Isn't My VQE Converging?](https://mamuncseru.github.io/hilbertbench/tutorials/vqe-barren-plateau/) | Barren plateau, cost-landscape variance |
+| 02 | [Am I Using Enough Shots?](https://mamuncseru.github.io/hilbertbench/tutorials/shot-noise/) | Shot noise floor, SNR, shot budget |
+| 03 | [Expressibility vs Trainability](https://mamuncseru.github.io/hilbertbench/tutorials/expressibility-vs-trainability/) | Active Mode, KL expressibility, Holmes 2022 |
+| 04 | [How Hardware Noise Degrades Your Results](https://mamuncseru.github.io/hilbertbench/tutorials/hardware-noise/) | Circuit fidelity, gate error, noise profile |
+
+---
+
+## Documentation
+
+| Resource | Contents |
+|---|---|
+| **[End-to-End Guide](docs/end-to-end.md)** | The whole tool in one document — top-down, layered, no quantum background assumed |
+| **[mamuncseru.github.io/hilbertbench](https://mamuncseru.github.io/hilbertbench/)** | Learning site: getting started, tutorials, concept guides |
+| **[hilbertbench.readthedocs.io](https://hilbertbench.readthedocs.io)** | Reference site: analyzer internals, trace format, architecture, and the [test catalog](docs/reference/test-catalog.md) — all 319 tests explained |
+
+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](docs/reference/invariants.md)** (rendered on
+the [reference site](https://hilbertbench.readthedocs.io)). 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)](https://nedcdata.org/)**,
+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`](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](LICENSE).

hilbertbench-1.0.0/README.md

@@ -0,0 +1,155 @@
+# HilbertBench
+
+> Diagnose quantum ML experiments without changing a line of algorithm code.
+
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Tests](https://github.com/mamuncseru/hilbertbench/actions/workflows/tests.yml/badge.svg)](https://github.com/mamuncseru/hilbertbench/actions/workflows/tests.yml)
+[![Docs](https://img.shields.io/badge/docs-readthedocs-blueviolet)](https://hilbertbench.readthedocs.io)
+
+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
+
+```bash
+# 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
+
+```python
+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
+
+| Function | What it answers |
+|---|---|
+| `detect_barren_plateau` | Is the cost-landscape variance exponentially suppressed? |
+| `shot_noise_ratio` | Is the optimizer chasing signal or shot noise? |
+| `optimization_convergence` | Is the parameter trajectory still moving? |
+| `circuit_structure` | How deep, how many qubits, what gate composition? |
+| `kl_expressibility` | How uniformly does the ansatz cover Hilbert space? |
+| `noise_profile` | What hardware noise levels did the run experience? |
+
+```python
+from hilbertbench.analysis import summary
+
+report = summary(trace)   # runs all analyzers, returns one dict
+```
+
+---
+
+## Integrations
+
+| Framework | Proxy class | Install extra |
+|---|---|---|
+| Qiskit V2 Estimator | `HilbertEstimatorProxy` | `hilbertbench[qiskit]` |
+| Qiskit V2 Sampler | `HilbertSamplerProxy` | `hilbertbench[qiskit]` |
+| IBM Quantum hardware | `HilbertEstimatorProxy` with `EstimatorV2(mode=backend)` | `hilbertbench[qiskit]` |
+| PennyLane | `HilbertPennyLaneDeviceProxy` | `hilbertbench[pennylane]` |
+
+---
+
+## Tutorials
+
+Four end-to-end tutorials, each diagnosing a real quantum ML failure mode:
+
+| # | Tutorial | Concepts |
+|---|---|---|
+| 01 | [Why Isn't My VQE Converging?](https://mamuncseru.github.io/hilbertbench/tutorials/vqe-barren-plateau/) | Barren plateau, cost-landscape variance |
+| 02 | [Am I Using Enough Shots?](https://mamuncseru.github.io/hilbertbench/tutorials/shot-noise/) | Shot noise floor, SNR, shot budget |
+| 03 | [Expressibility vs Trainability](https://mamuncseru.github.io/hilbertbench/tutorials/expressibility-vs-trainability/) | Active Mode, KL expressibility, Holmes 2022 |
+| 04 | [How Hardware Noise Degrades Your Results](https://mamuncseru.github.io/hilbertbench/tutorials/hardware-noise/) | Circuit fidelity, gate error, noise profile |
+
+---
+
+## Documentation
+
+| Resource | Contents |
+|---|---|
+| **[End-to-End Guide](docs/end-to-end.md)** | The whole tool in one document — top-down, layered, no quantum background assumed |
+| **[mamuncseru.github.io/hilbertbench](https://mamuncseru.github.io/hilbertbench/)** | Learning site: getting started, tutorials, concept guides |
+| **[hilbertbench.readthedocs.io](https://hilbertbench.readthedocs.io)** | Reference site: analyzer internals, trace format, architecture, and the [test catalog](docs/reference/test-catalog.md) — all 319 tests explained |
+
+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](docs/reference/invariants.md)** (rendered on
+the [reference site](https://hilbertbench.readthedocs.io)). 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)](https://nedcdata.org/)**,
+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`](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](LICENSE).

hilbertbench-1.0.0/hilbertbench/__init__.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python
+#
+# file: hilbertbench/__init__.py
+#
+# revision history:
+#  20260604 (am): cleaned up to project coding standards
+#
+# HilbertBench — non-intrusive diagnostic framework for quantum machine
+# learning. The recorder, reader, and models import only the standard
+# library. The analysis layer is exposed lazily so that recorder-only
+# users never pay for numpy/pandas imports.
+#
+#   from hilbertbench import HilbertTrace
+#   trace = HilbertTrace("runs/20260605_xxx")
+#
+# Source comments reference architectural invariants as INV-NNN (e.g.
+# INV-001). These are the framework's non-negotiable guarantees; the
+# canonical list lives in docs/reference/invariants.md.
+#------------------------------------------------------------------------------
+
+# import system modules
+#
+from typing import Any
+
+#------------------------------------------------------------------------------
+#
+# global variables are listed here
+#
+#------------------------------------------------------------------------------
+
+# define the public API
+#
+__all__ = ["HilbertTrace", "SpanView"]
+
+#------------------------------------------------------------------------------
+#
+# functions are listed here
+#
+#------------------------------------------------------------------------------
+
+def __getattr__(name: str) -> Any:
+    """
+    function: __getattr__
+
+    arguments:
+     name: the attribute name being accessed
+
+    return:
+     the requested attribute object
+
+    description:
+     PEP 562 lazy attribute access — keeps `import hilbertbench`
+     lightweight. The analysis layer (numpy/pandas) is only imported
+     when explicitly requested by the caller.
+    """
+
+    # resolve HilbertTrace lazily
+    #
+    if name == "HilbertTrace":
+        from hilbertbench.trace import HilbertTrace
+        return HilbertTrace
+
+    # resolve SpanView lazily
+    #
+    if name == "SpanView":
+        from hilbertbench.trace import SpanView
+        return SpanView
+
+    # exit ungracefully — unknown attribute
+    #
+    raise AttributeError(
+        f"module 'hilbertbench' has no attribute {name!r}"
+    )
+#
+# end of function
+
+#
+# end of file

hilbertbench-1.0.0/hilbertbench/active/__init__.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python
+#
+# file: hilbertbench/active/__init__.py
+#
+# revision history:
+#  20260604 (am): cleaned up to project coding standards
+#
+# hilbertbench.active — Active Mode: controlled, explicitly-authorized
+# sampling for diagnostics (e.g. expressibility) that passive observation
+# cannot provide.
+#
+#   from hilbertbench.active import active_probe_qiskit
+#------------------------------------------------------------------------------
+
+# import active mode components
+#
+from hilbertbench.active.probe import (
+    active_probe_pennylane,
+    active_probe_qiskit,
+    probe_expressibility,
+)
+
+#------------------------------------------------------------------------------
+#
+# global variables are listed here
+#
+#------------------------------------------------------------------------------
+
+# define the public API
+#
+__all__ = [
+    "probe_expressibility",
+    "active_probe_qiskit",
+    "active_probe_pennylane",
+]
+
+#
+# end of file