Add exact-logical QBP validation

PAPER1_NUMERICS.md

@@ -0,0 +1,225 @@
+# Paper I numerical material
+
+This page documents the repository material for
+**[A Compass on the Quantum State Sphere: The Hopf Ansatz for Arbitrary Pure-State Optimization](https://arxiv.org/abs/2607.14231)**.
+
+The first paper studies the Hopf ansatz as an optimization chart. The repository contains
+real- and complex-Hopf stress tests, adaptive baselines, diagnostics, plotting scripts,
+finite-shot estimator checks, CNOT-ledger checks, and a small Qibo VQE circuit demo.
+The generated CSV archives are derived artifacts and are intentionally not tracked.
+
+## Main files
+
+| File | Role |
+|---|---|
+| `hopf_utils.py` | Real and complex Hopf maps, inverse maps, Jacobians, diagonal metrics, tangent-state assignments, gate schedules, and optional Qibo checks. |
+| `hopf_data.py` | Generates the multi-size real-Hopf synthetic stress-test datasets. |
+| `adam_data.py` | Generates the adaptive Adam baseline datasets. |
+| `diagnose_hopf.py` | Checks completeness and numerical quality of the Hopf datasets. |
+| `diagnose_adam.py` | Checks completeness and numerical quality of the Adam datasets. |
+| `plot_hopf.py` | Generates the real-Hopf and Adam summary figures. |
+| `hopf_complex.py` | Focused complex-Hopf stress test at `n=6`. |
+| `finite_shot_sanity_check.py` | Fixed-state finite-shot check of the symmetric signed-branch gradient identity. |
+| `hopf_gate_count.py` | Checks generated real and complex gate schedules against the closed-form CNOT ledger. |
+| `VQE_qibo.py` | Local `n=4` real/complex Qibo and statevector layerwise-gradient demonstration. |
+
+Included small release figures are regenerated by their corresponding scripts:
+
+```text
+hopf_complex.png
+finite_shot_sanity.png
+VQE_qibo.png
+```
+
+## Scope
+
+The synthetic tasks comprise three VQE families and three metrology-inspired families:
+
+- parent-Hamiltonian recovery;
+- hidden Hamming-spectrum minimization;
+- small-gap spectrum minimization;
+- single-target Fisher proxy;
+- normalized pure-state QFI;
+- balanced two-target Fisher proxy.
+
+These experiments test optimization behavior. They are separate from the second
+manuscript's deterministic theorem-validation suite in `qbp_validation/`.
+
+## Requirements
+
+Use Python 3.10 or newer.
+
+```bash
+python -m pip install -r requirements.txt
+```
+
+Explicit Qibo circuit paths additionally use:
+
+```bash
+python -m pip install -r requirements-optional.txt
+```
+
+## Minimal safeguards
+
+```bash
+python hopf_utils.py
+
+mkdir -p figures_safeguards
+python hopf_gate_count.py \
+    --nmin 2 \
+    --nmax 6 \
+    --out figures_safeguards/hopf_gate_count_smoke.pdf
+
+MPLBACKEND=Agg python VQE_qibo.py \
+    --steps 2 \
+    --shots 20 \
+    --sampler statevector \
+    --output figures_safeguards/VQE_qibo_smoke.png \
+    --log-every 0
+
+python hopf_complex.py \
+    --quick \
+    --outdir figures_safeguards \
+    --csv-name complex_hopf_smoke.csv \
+    --plot-name hopf_complex_smoke.png
+
+python finite_shot_sanity_check.py \
+    --shots 100 1000 \
+    --trials 3 \
+    --output-dir figures_safeguards
+```
+
+Use `--sampler qibo-explicit` in `VQE_qibo.py` to require the explicit Qibo path.
+The default `auto` mode uses Qibo when available and otherwise falls back to the
+statevector implementation.
+
+## Full real-Hopf datasets
+
+```bash
+mkdir -p data
+
+for n in 6 7 8 9 10; do
+    python hopf_data.py --n "$n" --steps 200 --num-seeds 10 --outdir data
+    python adam_data.py --n "$n" --steps 200 --num-seeds 10 --outdir data
+done
+```
+
+The geometry-native tracks are:
+
+```text
+Hopf-EGT-CG
+Hopf-Riemannian-LBFGS
+Hopf-Riemannian-BB
+```
+
+The adaptive baselines are:
+
+```text
+Hopf-Adam
+Mottonen-ideal-PS-Adam
+```
+
+## Diagnostics
+
+```bash
+repo_root="$(pwd)"
+mkdir -p diagnostics
+
+python diagnose_hopf.py \
+    --indir data \
+    --ns 6-10 \
+    --steps 200 \
+    --num-seeds 10 \
+    --out "$repo_root/diagnostics/hopf_data_diagnostics.txt"
+
+python diagnose_adam.py \
+    --indir data \
+    --ns 6-10 \
+    --steps 200 \
+    --num-seeds 10 \
+    --out "$repo_root/diagnostics/adam_data_diagnostics.txt"
+```
+
+The reports check expected files and rows, task/mode/seed/step coverage, parse errors,
+vector lengths, nonfinite values, state normalization, convergence summaries, and final
+rankings. The diagnostic scripts stream the large vector columns rather than loading the
+full archive into pandas.
+
+## Figures
+
+```bash
+mkdir -p figures
+python plot_hopf.py \
+    --indir data \
+    --adam-dir data \
+    --outdir figures \
+    --ns 6-10 \
+    --detail-n 10 \
+    --formats pdf png
+```
+
+## Focused complex-Hopf run
+
+```bash
+python hopf_complex.py
+```
+
+This generates:
+
+```text
+complex_hopf_stress_data.csv
+hopf_complex.png
+```
+
+For a smaller run:
+
+```bash
+python hopf_complex.py --quick
+```
+
+For plotting only from an existing CSV:
+
+```bash
+python hopf_complex.py --plot-only
+```
+
+## Standalone safeguards
+
+### CNOT ledger
+
+```bash
+python hopf_gate_count.py
+```
+
+This compares generated schedules with the closed-form real and complex CNOT-count
+formulas. The resulting plot is a local safeguard, not a hardware compilation benchmark.
+
+### Finite-shot signed-branch identity
+
+```bash
+python finite_shot_sanity_check.py
+```
+
+The script fixes one `n=6` real Hopf state, verifies the exact branch identity against an
+independent tree-gradient reference, and then samples the two branch energies at several
+shot counts. This is an estimator sanity check, not a total full-gradient sampling study.
+
+### Local Qibo VQE demonstration
+
+```bash
+MPLBACKEND=Agg python VQE_qibo.py
+```
+
+The script runs local `n=4` real and complex VQE toys and compares exact Hopf-gradient
+Adam with sampled layerwise-circuit Adam. It is a local circuit-realizability demonstration,
+not the global-frame implementation of the second manuscript and not an asymptotic gate-count
+benchmark.
+
+## Determinism and complete commands
+
+The scripts use deterministic seeds by default. Exact regeneration commands, seed rules,
+chart tolerances, and output conventions are listed in
+[`REPRODUCIBILITY.md`](REPRODUCIBILITY.md).
+
+The repository landing page before the two-paper reorganization is preserved in Git history
+at commit `1188e8a1af5326d62d8c788499c1d59a06fe450c`.