update

Author: mhjensen

doc/Programs/EigenQ/pairing-eigenq/.claude/settings.json

@@ -0,0 +1,4 @@
+{
+  "permissions": { "allow": ["Skill"] },
+  "settingSources": ["user", "project"]
+}

doc/Programs/EigenQ/pairing-eigenq/.claude/skills/notebook-builder/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: notebook-builder
+description: >
+  How to assemble, execute, and validate the project Jupyter notebook
+  programmatically (with nbformat), so the notebook stays reproducible and is
+  built the same way every time. Use this skill WHENEVER the task is to create,
+  extend, rebuild, re-run, or check a notebook in this repo (e.g.
+  ResolutionRefPairing.ipynb), add a section/chapter, regenerate its figures, or
+  verify it executes without errors. Always build notebooks with the scripts
+  here rather than editing JSON by hand or pasting large code blobs.
+---
+
+# Notebook builder
+
+Notebooks are BUILD ARTIFACTS. The source of truth for physics is
+`src/pairinglib`; notebook code cells should `import pairinglib as pl` and call
+the library, not re-define it. This keeps the tested library and the narrative
+in sync.
+
+## Workflow (always in this order)
+1. **Plan the cells.** A cell is either a markdown narrative cell or a code cell.
+   Group: intro -> model -> coarse VQE -> prolongation -> refinement ->
+   four-particle analysis -> rodeo -> summary. Read the `pairing-model` and
+   `vqe-circuits` skills first for conventions and the API.
+2. **Assemble** with `scripts/build_notebook.py` (uses nbformat; never hand-edit
+   the .ipynb JSON). It takes an ordered list of (kind, source) cells.
+3. **Execute** with `scripts/execute_notebook.py` (jupyter nbconvert --execute,
+   timeout generous: the HEA k=3 optimisation alone is ~60 s).
+4. **Check** with `scripts/check_notebook.py`: asserts zero error outputs, a
+   minimum figure count, and that the benchmark anchor numbers
+   (FCI/CCD/UCCSD at k=2,3; refined overlaps; rodeo acceptance->p) appear in the
+   outputs. Treat a failing check as a build failure.
+
+## Rules
+- Keep markdown prose first-person-plural and paper-like (this notebook is the
+  source for the article). One concept per code cell; a figure-producing cell
+  ends in `plt.show()`.
+- Numbers quoted in markdown must come from a cell that actually computed them.
+- Do not use `localStorage`/browser APIs; this is a Python kernel notebook.
+- After any change, re-run execute + check before declaring done.
+
+## Common entry points
+- "add a section X to the notebook" -> append cells, execute, check.
+- "rebuild the notebook from scratch" -> run the full builder, execute, check.
+- "the notebook errors" -> execute, read the first error output, fix the cell or
+  the library, repeat.

doc/Programs/EigenQ/pairing-eigenq/.claude/skills/notebook-builder/scripts/build_notebook.py

@@ -0,0 +1,16 @@
+#!/usr/bin/env python3
+"""Assemble a notebook from an ordered cell list. Import and call build().
+Cells: list of ("md"|"code", source_string). Never hand-edit .ipynb JSON."""
+import sys, nbformat as nbf
+
+def build(cells, out_path):
+    nb = nbf.v4.new_notebook()
+    nb["cells"] = [nbf.v4.new_markdown_cell(s) if k == "md"
+                   else nbf.v4.new_code_cell(s) for k, s in cells]
+    nb["metadata"]["kernelspec"] = {"display_name": "Python 3",
+                                    "language": "python", "name": "python3"}
+    nbf.write(nb, out_path)
+    print(f"wrote {out_path} ({len(nb['cells'])} cells)")
+
+if __name__ == "__main__":
+    print("import build() from this module; pass cells=[('md'|'code', src), ...]")

doc/Programs/EigenQ/pairing-eigenq/.claude/skills/notebook-builder/scripts/check_notebook.py

@@ -0,0 +1,19 @@
+#!/usr/bin/env python3
+"""Validate an executed notebook: no errors, >= min figures, anchor numbers present.
+Usage: check_notebook.py NB [min_figs]"""
+import sys, json
+nb = json.load(open(sys.argv[1])); min_figs = int(sys.argv[2]) if len(sys.argv) > 2 else 6
+errs, figs, text = [], 0, []
+for i, c in enumerate(nb["cells"]):
+    if c["cell_type"] != "code": continue
+    for o in c.get("outputs", []):
+        if o.get("output_type") == "error": errs.append((i, o.get("ename")))
+        if o.get("output_type") == "display_data" and "image/png" in o.get("data", {}): figs += 1
+        if "text" in o: text.append("".join(o["text"]))
+blob = "\n".join(text)
+anchors = ["0.794697", "0.635548", "acceptance"]   # FCI(k=3), FCI(k=4), rodeo
+missing = [a for a in anchors if a not in blob]
+ok = not errs and figs >= min_figs and not missing
+print(f"errors={errs or 'none'}  figures={figs} (min {min_figs})  missing_anchors={missing or 'none'}")
+print("CHECK PASSED" if ok else "CHECK FAILED")
+sys.exit(0 if ok else 1)

doc/Programs/EigenQ/pairing-eigenq/.claude/skills/notebook-builder/scripts/execute_notebook.py

@@ -0,0 +1,7 @@
+#!/usr/bin/env python3
+"""Execute a notebook in place. Usage: execute_notebook.py NB [timeout_s]."""
+import sys, subprocess
+nb = sys.argv[1]; timeout = sys.argv[2] if len(sys.argv) > 2 else "1200"
+cmd = ["python3", "-m", "jupyter", "nbconvert", "--to", "notebook",
+       "--execute", "--inplace", f"--ExecutePreprocessor.timeout={timeout}", nb]
+sys.exit(subprocess.call(cmd))

doc/Programs/EigenQ/pairing-eigenq/.claude/skills/pairing-model/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: pairing-model
+description: >
+  Physics conventions and the validated Python API for the constant-pairing
+  Hamiltonian (nuclear/condensed-matter pairing model). Use this skill WHENEVER
+  the task touches the pairing model, seniority-zero spectra, the
+  delta/g Hamiltonian, Jordan-Wigner encoding of pairs, Hartree-Fock pairing
+  energies, FCI/CCD/UCCSD benchmarks for pairing, or the `pairinglib` package.
+  Consult it before writing any pairing physics so the conventions (level
+  index, qubit ordering, sign of g, benchmark numbers) stay consistent across
+  the notebook, the library, and the paper.
+---
+
+# Pairing model: conventions and API
+
+This project studies the constant-pairing Hamiltonian as a controlled testbed
+for the resolution-refinement + rodeo eigenstate-preparation pipeline. Always
+use the conventions below; they are baked into `src/pairinglib` and the paper.
+
+## Hamiltonian and conventions (do not deviate)
+- `H = delta * sum_p p * sum_sigma n_{p,sigma} - (g/2) * sum_{p,q} a+_{p up} a+_{p dn} a_{q dn} a_{q up}`
+- `delta = 1` throughout. Level `p` (0-indexed) has single-particle energy `delta*p`.
+- Qubit index `= 2*p + sigma`, with `sigma = 0` (up), `1` (down); a `k`-level
+  problem uses `2k` qubits. Big-endian: qubit `j` carries bit `(n-1-j)`.
+- The force conserves seniority, so the `N`-paired ground state lies entirely in
+  the seniority-zero subspace; the full `N`-sector FCI equals the seniority-0 result.
+- Hartree-Fock fills the lowest `N/2` levels; `E_HF(N=4, g) = 2 - g`.
+- "Basis refinement" means increasing `k` at FIXED `N` (the basis/qubit count
+  grows; the particle number does not).
+
+## Validated benchmark numbers (N=4, g=1) — use as regression anchors
+| k | qubits | FCI       | CCD       | UCCSD     |
+|---|--------|-----------|-----------|-----------|
+| 2 | 4      | 1.000000  | 1.000000  | 1.000000  |
+| 3 | 6      | 0.794697  | 0.794697  | 0.794697  |
+| 4 | 8      | 0.635548  | 0.630443  | 0.636987  |
+| 8 | 16     | 0.145559  | 0.097263  | 0.157856  |
+UCCSD is variational (>= FCI); CCD over-binds (< FCI). Singles vanish (seniority).
+
+## Library API (import from `pairinglib`)
+See `references/library-api.md` for full signatures. Do NOT redefine these in
+notebooks or scripts — import them, so there is a single tested source of truth.
+
+## Common pitfalls
+- `np.eye(2, dtype=complex)` — the 2nd positional arg of `np.eye` is the column
+  count, not the dtype.
+- Never shadow stdlib modules with file names (e.g. a file called `re.py`).
+- The dense JW pair-interaction operator `W = sum_{p,q} A+_p A_q` is already
+  Hermitian; use `H = H_kin - (g/2) W` (do not add `W + W.dag`, that double counts).

doc/Programs/EigenQ/pairing-eigenq/.claude/skills/pairing-model/references/library-api.md

@@ -0,0 +1,39 @@
+# pairinglib API reference
+
+## hamiltonian.py
+- `build_sector(k, N) -> (nq, states, index)` — fixed-N Fock sector (bitstring list + lookup).
+- `H_pairing_sparse(k, g, N, states, index, delta=1.0) -> csr_matrix` — sparse N-sector H.
+- `fci_ground(H) -> float` — lowest eigenvalue (exact).
+- `E_HF(N, g, delta=1.0) -> float` — Hartree-Fock energy.
+- `build_H_full(k, g, delta=1.0) -> ndarray` — dense H over the full 2^(2k) space (HEA/gate-UCCSD).
+
+## ccd.py
+- `run_ccd(k, g, N, delta=1.0, ...) -> (E, iters)` — coupled-cluster doubles.
+
+## uccsd.py  (operator-level / statevector)
+- `uccsd_pool(k, N) -> (singles, doubles)`
+- `setup_uccsd(k, N, delta=1.0) -> dict(nq, states, index, ...)`
+- `uccsd_vqe(setup, H, n_trotter=1, ...) -> (E, x, energy_fn, grad_fn)`
+
+## gates.py
+- `apply_1q(psi, U, q, n)`, `apply_cnot(psi, c, t, n)`, `Ry(th)`, `Rz(th)`, `Rx(th)`
+- `pauli_exp(psi, phi, pauli, n)` — exp(-i phi/2 P) via basis change + CNOT ladder + Rz.
+
+## gate_uccsd.py  (gate-level circuits)
+- `make_single(i, a, n)`, `make_double(i, j, a, b, n)` — Pauli terms of an excitation.
+- `apply_exc_circuit(psi, theta, terms, n)`
+- `gate_uccsd_setup(k, N) -> dict(nq, terms, gens, hf, P, ncnot, nrot)`
+- `gate_uccsd_vqe(k, N, g, setup) -> (E, nit)`
+- `gate_uccsd_state(k, N, g) -> (E, statevector)`
+
+## refine.py
+- `prolong_matrix(k_low, k_high, N) -> ndarray` — gate-free basis embedding.
+- `refine_state(N, k_high, T, k_low=2, M=160, mu_buf=0.6, g=1.0) -> (psi, H_high)`
+- `refine_NK(N, k_high, Ts, ...) -> dict(ov, en, Eh, El, gap, ov0, E0)`
+
+## rodeo.py
+- `rodeo_post0(v, U, t, E) -> (state, prob)` — post-selected one-cycle filter.
+- `rodeo_cycle_ancilla(v, U, t, E)` — explicit ancilla circuit (same map).
+- `rodeo_sweep(v0, H, ts, E) -> (state, cumulative_acceptance)`
+- `rodeo_allzero_prob(v0, H, ts, E) -> float` — for energy scans.
+- `rodeo_track(v0, H, ts, E, target) -> (fidelity_array, acceptance_array)`

doc/Programs/EigenQ/pairing-eigenq/.claude/skills/physics-paper/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: physics-paper
+description: >
+  How to build the LaTeX scientific article from the notebook: extract the
+  notebook figures, write/maintain the paper in the project's article style, and
+  compile to PDF. Use this skill WHENEVER the task is to create, edit, or compile
+  the paper (eigenq_pairing.tex), pull figures out of the notebook into
+  paper/figs, update the author list or bibliography, or turn notebook results
+  into article prose. Follow `references/article-conventions.md` for the house
+  style (article class, authblk author block, figure/caption rules).
+---
+
+# Physics paper builder
+
+The article is generated FROM the executed notebook: figures are extracted, and
+every quantitative claim must trace back to a notebook output. Do not invent
+numbers.
+
+## Workflow
+1. **Extract figures** from the executed notebook into `paper/figs/`:
+   `python scripts/extract_figures.py notebooks/ResolutionRefPairing.ipynb paper/figs`
+   It writes `fig1.png ...` in cell order and prints a cell->figure map; choose
+   which to include and reference them with `\includegraphics{figs/figN.png}`.
+2. **Write / update** `paper/eigenq_pairing.tex` following
+   `references/article-conventions.md` (and reuse `assets/article-template.tex`
+   as the starting skeleton for a new paper).
+3. **Compile**: `bash scripts/build_paper.sh paper/eigenq_pairing.tex` (runs
+   pdflatex twice to resolve references; fails loudly on LaTeX errors or
+   undefined citations/references).
+
+## House rules
+- Author list in ALPHABETICAL order by surname, with `authblk` affiliation
+  superscripts. The canonical list lives in the README / application; keep it in sync.
+- Standard `article` class (RevTeX is not assumed installed). Packages known to
+  be available: amsmath, amssymb, graphicx, booktabs, authblk, physics, braket,
+  hyperref, lmodern, geometry.
+- Wide notebook figures (~13:5) go full `\linewidth`, one per `figure`.
+- Equations and quoted results must match the notebook and the rodeo reference
+  (see the vqe-circuits skill); cite Choi 2021 / Qian 2024 for the rodeo and
+  Bogner 2026 (PLB 875) for resolution refinement.
+- Keep Sections within the journal page budget if one is specified.

doc/Programs/EigenQ/pairing-eigenq/.claude/skills/physics-paper/assets/article-template.tex

@@ -0,0 +1,16 @@
+\documentclass[11pt]{article}
+\usepackage[utf8]{inputenc}\usepackage[T1]{fontenc}\usepackage{lmodern}
+\usepackage[a4paper,margin=1in]{geometry}
+\usepackage{amsmath,amssymb,physics,graphicx,booktabs,authblk}
+\usepackage[colorlinks=true]{hyperref}
+\title{\bfseries TITLE}
+\author[1]{Author One}\author[2]{Author Two}
+\affil[1]{Affiliation 1}\affil[2]{Affiliation 2}
+\date{\today}
+\begin{document}\maketitle
+\begin{abstract}\noindent ABSTRACT\end{abstract}
+\section{Introduction}
+\bibliographystyle{plain}
+\begin{thebibliography}{99}
+\end{thebibliography}
+\end{document}

doc/Programs/EigenQ/pairing-eigenq/.claude/skills/physics-paper/references/article-conventions.md

@@ -0,0 +1,25 @@
+# Article conventions
+
+## Class & preamble
+- `\documentclass[11pt]{article}` + `geometry` (a4, 1in margins).
+- Author block via `authblk`: `\author[n]{First Last}` + `\affil[n]{...}`.
+- Math: `amsmath, amssymb, physics` (\ket,\bra,\expval,\abs) and/or `braket`.
+- `booktabs` for tables, `hyperref` (colorlinks) for links, `lmodern` font.
+
+## Structure (this paper)
+1. Introduction (eigenstate-prep bottleneck; VQE/adiabatic/QPE+rodeo limits; the
+   hybrid idea; pairing model as testbed).
+2. The pairing model and its qubit encoding.
+3. The hybrid pipeline (coarse UCCSD-VQE; prolongation; resolution refinement;
+   rodeo algorithm with Eqs. 1-2 and the convergence criterion).
+4. Results (UCCSD vs FCI/CCD + scaling; refinement overlap & energy; rodeo scan
+   + convergence).
+5. Discussion & outlook (hardware/Trotter/Magne; applications).
+
+## Authors (alphabetical by surname) — keep in sync with the application
+Bogner (FRIB/MSU), Glittum (Oslo), Hergert (FRIB/MSU), Hjorth-Jensen (Oslo),
+Lange (Oslo), LaRose (MSU), Lee (FRIB/MSU), Massel (USN/Oslo).
+
+## Figure captions
+Self-contained, describe axes and the takeaway. Reference exact numbers
+(e.g. peak at E=0.6352 vs exact 0.635548) only if a notebook cell printed them.