hnep 0.4.0

Hybrid Network Evaluation Protocol — multi-method evaluation for hybrid quantum-classical models

HNEP — Hybrid Network Evaluation Protocol

Does the quantum component in your hybrid model actually contribute meaningful computation, or could a classical surrogate replace it?

Most QML benchmarks report end-task accuracy and call it a day. HNEP applies multiple independent probes to your trained hybrid model — surrogation, structural intervention, representation analysis, plus diagnostic probes (error diversity, noise, temporal) — and returns a verdict you can defend.

---

Install

pip install hnep

Optional framework extras:

pip install "hnep[jax]"          # JAX / Flax models
pip install "hnep[pytorch]"      # PyTorch models
pip install "hnep[pennylane]"    # PennyLane quantum backend
pip install "hnep[molecular]"    # RDKit-based molecular utilities
pip install "hnep[reports]"      # interactive HTML reports (jinja2, plotly)
pip install "hnep[all]"          # everything

30-second quickstart

import hnep

# Wrap your trained model in any of HNEP's adapters
adapter = hnep.FunctionalAdapter(
    name="my_model",
    predict_fn=my_predict,
    extract_quantum_fn=my_extract_quantum,
    predict_with_override_fn=my_predict_override,
    quantum_dim=4,
)

# Run the full HNEP protocol
result = hnep.evaluate(adapter, my_dataset)

print(result.qct_verdict)           # → "Regularizer"
print(result.qct_confidence)        # → 0.94
result.to_html("report.html")       # full HTML report with figures

The report opens in your browser as a self-contained HTML file with the QCT plane, the convergent-validity radar, and a manifest your run can be replayed from.

What HNEP returns

HNEP Evaluation Report
============================================================
Model:       Hybrid-V1
Dataset:     ESOL (n=1128, scaffold split)

QCT Verdict: Regularizer  (confidence: 0.94)
------------------------------------------------------------
  surrogation    score=0.077  [0.06, 0.10]   → REPLACEABLE
  intervention   score=0.29   [0.22, 0.36]   → LOAD-BEARING
------------------------------------------------------------

Notes:
  • Surrogate swap is safe at inference. Quantum's role appears
    confined to the training phase.

The QCT taxonomy

HNEP classifies your model into one of four roles plus an honest fallback:

	LOAD-BEARING	NOT LOAD-BEARING
NECESSARY	Genuine Contributor	Unique-but-Ignored
REPLACEABLE	Architectural Regularizer	Dead Weight

When the bootstrap confidence intervals straddle a threshold, HNEP returns Inconclusive rather than guessing.

Adapters

Wrap your model in one line:

Adapter	Use when
FunctionalAdapter	You can write three Python callbacks. Most users start here.
PrecomputedAdapter	You already cached the test-set extractions to disk.
JaxFlaxAdapter	Your model is a Flax module with our standard conventions.
PyTorchAdapter	Your model is a torch.nn.Module — subclass + override 2 hooks.

See hnep/examples/ for runnable examples of each.

Core probes vs Diagnostics

v0.4 tiers HNEP's probes into a verdict-driving core — the three probes QCTClassifier consumes — and a diagnostic tier for supplementary evidence. Diagnostic probes run to completion and return valid results, but they do not gate the QCT verdict.

Probe	Category	Verdict-driving	Known limitations
SurrogationProbe	Core — hnep.SurrogationProbe	Yes	—
InterventionProbe	Core — hnep.InterventionProbe	Yes	—
RepresentationProbe (CKA + MI)	Core — hnep.RepresentationProbe	Yes (under use_convergent_validity=True)	—
NoiseProbe	Diagnostic — hnep.diagnostics.NoiseProbe	No	Returned null (no verdict flip) on the thesis datasets
TemporalProbe	Diagnostic — hnep.diagnostics.TemporalProbe	No	Same as NoiseProbe — null result on thesis datasets
ErrorDiversityProbe	Diagnostic — hnep.diagnostics.ErrorDiversityProbe	No	Ridge readout fails when either branch is non-linearly informative; see low_readout_strength flag in details

The three diagnostic probes remain importable from the top-level hnep namespace via a deprecation shim (from hnep import NoiseProbe still works but emits a DeprecationWarning pointing at hnep.diagnostics). QCTClassifier's signature (surrogation, intervention, representation) excludes diagnostics by construction — you cannot accidentally gate the verdict on a diagnostic probe result.

Killer outputs

• plot_qct_plane, plot_convergent_validity_radar, plot_pareto_with_hardware_cost
• plot_disagreement_heatmap — probes × datasets verdict grid
• plot_activation_atlas — UMAP/t-SNE/PCA projection of quantum outputs
• Molecular Chemistry Gallery — RDKit-rendered top-K / bottom-K molecules by QCI, embedded in the HTML report
• HNEPCard — single-glance summary card (text / Markdown / HTML)
• Verdict explainer — result.explain() returns a deterministic plain-English paragraph naming the evidence behind the verdict
• Paper-ready exports — result.to_latex() (booktabs tables) and result.to_markdown() (README-ready)
• HTML / JSON / CSV reports + manifest files for reproducibility

CLI

hnep card result.json --format markdown
hnep compare model_a.json model_b.json model_c.json --format html -o compare.html

Adapters — Functional, Precomputed, JAX/Flax, PyTorch skeleton (heavy deps lazy-imported).

Roadmap

See docs/HNEP_LIBRARY_ROADMAP.md for the version-by-version plan.

• v0.3 — permutation-derived thresholds, atom-level QCI, Weights & Biases / Hugging Face / GitHub Action integrations
• v0.4 — hnep.dev web sandbox
• v0.5 — HNEP Doctor (AI-powered recommendations)
• v1.0 — frozen API, HNEP Arena leaderboard, governance committee

Documentation

Locally:

pip install "hnep[dev]"
cd docs_hnep && make html
open _build/html/index.html

Or skim the Sphinx source files directly.

Citing HNEP

@misc{priyanshu2026hnep,
  title  = {HNEP: Hybrid Network Evaluation Protocol for Quantum Machine Learning},
  author = {Priyanshu, Pratik},
  year   = {2026},
  url    = {https://github.com/Pratik25priyanshu20/HNEP},
}

License

MIT. See LICENSE.