[QCS] 🌠 Wander/漫步者: Issue #128 Certify a 4.050498× Tighter Trotter Resource Bound

docs/plans/2026-07-30-issue-128-delivery-design.md

@@ -0,0 +1,143 @@
+# Issue 128 Final Delivery Design
+
+**Date:** 2026-07-30
+
+**Status:** Approved by the user (option A)
+
+**Target:** Existing pull request `QuantumBFS/quantum.harness#248`
+
+## Objective
+
+Finish Issue 128 as a reviewer-ready, reproducible package. Preserve the
+proved `11791/2911 = 4.050498110614909...x` resource improvement as the
+official result, add a polished technical report and machine-readable
+summaries, and report the strict fivefold investigation as an honest
+feasibility appendix rather than a completed certificate.
+
+## Frozen Scientific Claim
+
+The benchmark is the periodic `12 x 12` spin-1/2 isotropic Heisenberg model
+
+```text
+H = sum_<i,j> (X_i X_j + Y_i Y_j + Z_i Z_j) / 4,
+T = 1, operator-norm tolerance = 1e-6.
+```
+
+The pinned published rigorous baseline uses 393 Trotter steps and 11,791
+merged group exponentials. The submitted certificate uses 97 steps and 2,911
+merged group exponentials. The 97-step exact-rational error bound is below
+`1e-6`; the 96-step bound is above it. The proof, circuit, normalization,
+tolerance, resource model, main certificate, and D4 sidecar are immutable.
+
+## Chosen Approach
+
+Extend the existing proof branch with four reviewer-facing layers:
+
+1. a standard LaTeX article of approximately 6--8 pages;
+2. compact JSON and plain-text result summaries;
+3. a verifier transcript and SHA-256 manifest; and
+4. a precise update to the existing PR description.
+
+The exact D5 artifact is follow-up evidence only. No `5x` result may be stated
+or implied. The unresolved translation-coupled D4 and explicit D8/tail proof
+gates, and the absence of an accepted 78-step global certificate, must be
+visible wherever the conditional fivefold arithmetic appears.
+
+## Deliverables
+
+All final files live under
+`tracks/qcs/solutions/WangTheoPhys/issue128`:
+
+```text
+docs/report/issue128-technical-report.tex
+docs/report/references.bib
+docs/report/output/issue128-technical-report.pdf
+artifacts/issue128-summary.json
+artifacts/issue128-summary.txt
+artifacts/verification-transcript.txt
+artifacts/SHA256SUMS
+```
+
+The PDF is versioned because it is a competition deliverable. Auxiliary LaTeX
+files and rendered page images are temporary and are not committed.
+
+## Report Structure
+
+No challenge template exists, so the report uses the standard `article` class.
+It contains:
+
+1. abstract and contribution summary;
+2. benchmark and resource accounting;
+3. reconstruction of the published rigorous baseline;
+4. local logarithm, Lie projection, concrete Pauli representation, and exact
+   anticommuting-group method;
+5. finite-step right-generator error ledger;
+6. verifier architecture and small-size dense cross-check;
+7. certified result and exact integer boundary;
+8. strict fivefold feasibility evidence and unresolved gates; and
+9. limitations and copy-paste reproduction commands.
+
+External citations are restricted to verified primary sources.
+
+## Trust Boundary and Data Flow
+
+The certificate and sidecars remain the source of truth. A packaging script
+checks their frozen hashes, projects exact fields into JSON and text, runs the
+fast main verifier and exact D5 verifier, and records their complete output.
+The final manifest binds the PDF, summaries, transcript, certificates, and
+report sources.
+
+- integers, `Fraction`, rational intervals, and symplectic Pauli algebra are
+  trusted;
+- heuristic grouping is untrusted discovery and is rechecked exactly;
+- floating point is presentation-only or part of the dense sanity check;
+- PDF and summaries explain the certificate but never replace it.
+
+## Fivefold Reporting Policy
+
+At 78 steps the unchanged compilation rule gives 2,341 groups and the
+conditional ratio `11791/2341 = 5.036736...`. This arithmetic does not prove a
+78-step error bound. The D5 sidecar has 605,832 exact terms, 123,106
+same-support pairwise-anticommuting groups, and site-density upper bound
+`11.23706750025696`; it narrows the gap without closing D4 or D8/tail.
+
+Every conditional fivefold statement must be accompanied by:
+
+```text
+No 78-step global error certificate is claimed or supplied.
+```
+
+## Validation
+
+Release requires all of the following:
+
+- the full default Issue 128 test suite;
+- the main fast verifier and exact D5 verifier;
+- the 97-accept/96-reject boundary checks;
+- frozen main-certificate and D4 hashes;
+- deterministic JSON/text regeneration;
+- SHA-256 verification of every manifest entry;
+- LaTeX compilation without fatal errors, undefined references, or missing
+  citations;
+- PDF text/page checks and visual inspection of every rendered page;
+- an unsupported-fivefold-language scan;
+- an explicit Git allowlist and remote-head drift check.
+
+If a follow-up check fails, remove its affirmative claim; never weaken the
+official 4.050x proof or substitute a numerical estimate.
+
+## Git and PR Strategy
+
+Work only in the isolated Issue 128 clone. Explicitly stage approved files;
+never use `git add -A`. Push to the existing fork head branch
+`JunkaiWang-TheoPhy:codex/issue-128-trotter-certificate` only if its remote head
+is still an ancestor of the audited local head. Do not force-push and do not
+open a competing PR. Update PR #248 with artifact links, exact results,
+validation commands, and the fivefold non-claim.
+
+## Definition of Done
+
+The report and data package are committed, every validation gate passes, the
+audited history is fast-forward pushed to the existing PR branch, the remote
+SHA equals the local SHA, and PR #248 exposes accurate reproduction steps and
+limitations. Maintainer review and merge are external outcomes.

hpc/issue128_d8_array.sbatch

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+#SBATCH --job-name=issue128-d8
+#SBATCH --partition=xhacnormalb
+#SBATCH --account=giggleliu
+#SBATCH --qos=user_acamtw70yu
+#SBATCH --nodes=1
+#SBATCH --ntasks=1
+#SBATCH --cpus-per-task=17
+#SBATCH --mem=64G
+#SBATCH --time=04:30:00
+#SBATCH --array=0-30%16
+#SBATCH --output=results/slurm-%x-%A_%a.out
+#SBATCH --error=results/slurm-%x-%A_%a.err
+
+set -euo pipefail
+
+: "${ISSUE128_RUN_ID:?ISSUE128_RUN_ID must name the result run}"
+ISSUE128_ORDER="${ISSUE128_ORDER:-8}"
+
+export PYTHONHASHSEED=0
+export OMP_NUM_THREADS=1
+export OPENBLAS_NUM_THREADS=1
+export MKL_NUM_THREADS=1
+export NUMEXPR_NUM_THREADS=1
+
+REPOSITORY_ROOT="${SLURM_SUBMIT_DIR:?}"
+ISSUE_ROOT="$REPOSITORY_ROOT/tracks/qcs/solutions/WangTheoPhys/issue128"
+export PYTHONPATH="$ISSUE_ROOT/src${PYTHONPATH:+:$PYTHONPATH}"
+CELL_ID=$(printf "stage-%02d" "$SLURM_ARRAY_TASK_ID")
+CELL_DIR="$REPOSITORY_ROOT/results/$ISSUE128_RUN_ID/cells/$CELL_ID"
+mkdir -p "$CELL_DIR"
+
+cd "$ISSUE_ROOT"
+"$REPOSITORY_ROOT/.venv/bin/python" -u scripts/build_d8_shard.py \
+  --stage-index "$SLURM_ARRAY_TASK_ID" \
+  --order "$ISSUE128_ORDER" \
+  --output "$CELL_DIR/shard.json.gz" \
+  --manifest "$CELL_DIR/manifest.json"

hpc/issue128_d8_reduce.sbatch

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+#SBATCH --job-name=issue128-d8-reduce
+#SBATCH --partition=xhacnormalb
+#SBATCH --account=giggleliu
+#SBATCH --qos=user_acamtw70yu
+#SBATCH --nodes=1
+#SBATCH --ntasks=1
+#SBATCH --cpus-per-task=26
+#SBATCH --mem=96G
+#SBATCH --time=01:15:00
+#SBATCH --output=results/slurm-%x-%j.out
+#SBATCH --error=results/slurm-%x-%j.err
+
+set -euo pipefail
+: "${ISSUE128_RUN_ID:?ISSUE128_RUN_ID must name the result run}"
+ISSUE128_ORDER="${ISSUE128_ORDER:-8}"
+
+export PYTHONHASHSEED=0
+export OMP_NUM_THREADS=1
+export OPENBLAS_NUM_THREADS=1
+export MKL_NUM_THREADS=1
+
+REPOSITORY_ROOT="${SLURM_SUBMIT_DIR:?}"
+ISSUE_ROOT="$REPOSITORY_ROOT/tracks/qcs/solutions/WangTheoPhys/issue128"
+export PYTHONPATH="$ISSUE_ROOT/src${PYTHONPATH:+:$PYTHONPATH}"
+RUN_ROOT="$REPOSITORY_ROOT/results/$ISSUE128_RUN_ID"
+mkdir -p "$RUN_ROOT/reduced"
+cd "$ISSUE_ROOT"
+"$REPOSITORY_ROOT/.venv/bin/python" -u scripts/reduce_d8_shards.py \
+  --input-root "$RUN_ROOT/cells" \
+  --expected-stages 31 \
+  --order "$ISSUE128_ORDER" \
+  --output "$RUN_ROOT/reduced/degree-${ISSUE128_ORDER}.json.gz" \
+  --summary "$RUN_ROOT/reduced/summary.json"

hpc/issue128_screen_array.sbatch

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+#SBATCH --job-name=issue128-screen
+#SBATCH --partition=xhacnormalb
+#SBATCH --account=giggleliu
+#SBATCH --qos=user_acamtw70yu
+#SBATCH --nodes=1
+#SBATCH --ntasks=1
+#SBATCH --cpus-per-task=5
+#SBATCH --mem=16G
+#SBATCH --time=02:00:00
+#SBATCH --array=0-23%24
+#SBATCH --output=results/slurm-%x-%A_%a.out
+#SBATCH --error=results/slurm-%x-%A_%a.err
+
+set -euo pipefail
+: "${ISSUE128_RUN_ID:?ISSUE128_RUN_ID must name the result run}"
+ISSUE128_SCREEN_ORDER="${ISSUE128_SCREEN_ORDER:-6}"
+
+export PYTHONHASHSEED=0
+export OMP_NUM_THREADS=1
+export OPENBLAS_NUM_THREADS=1
+export MKL_NUM_THREADS=1
+
+REPOSITORY_ROOT="${SLURM_SUBMIT_DIR:?}"
+ISSUE_ROOT="$REPOSITORY_ROOT/tracks/qcs/solutions/WangTheoPhys/issue128"
+export PYTHONPATH="$ISSUE_ROOT/src${PYTHONPATH:+:$PYTHONPATH}"
+CELL_ID=$(printf "permutation-%02d" "$SLURM_ARRAY_TASK_ID")
+CELL_DIR="$REPOSITORY_ROOT/results/$ISSUE128_RUN_ID/screen/$CELL_ID"
+mkdir -p "$CELL_DIR"
+cd "$ISSUE_ROOT"
+"$REPOSITORY_ROOT/.venv/bin/python" -u scripts/screen_matching_order.py \
+  --permutation-index "$SLURM_ARRAY_TASK_ID" \
+  --order "$ISSUE128_SCREEN_ORDER" \
+  --output "$CELL_DIR/result.json" \
+  --manifest "$CELL_DIR/manifest.json"

hpc/issue128_verify.sbatch

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+#SBATCH --job-name=issue128-verify
+#SBATCH --partition=xhacnormalb
+#SBATCH --account=giggleliu
+#SBATCH --qos=user_acamtw70yu
+#SBATCH --nodes=1
+#SBATCH --ntasks=1
+#SBATCH --cpus-per-task=9
+#SBATCH --mem=32G
+#SBATCH --time=04:30:00
+#SBATCH --output=results/slurm-%x-%j.out
+#SBATCH --error=results/slurm-%x-%j.err
+
+set -euo pipefail
+: "${ISSUE128_RUN_ID:?ISSUE128_RUN_ID must name the result run}"
+
+export PYTHONHASHSEED=0
+export OMP_NUM_THREADS=1
+export OPENBLAS_NUM_THREADS=1
+export MKL_NUM_THREADS=1
+
+REPOSITORY_ROOT="${SLURM_SUBMIT_DIR:?}"
+ISSUE_ROOT="$REPOSITORY_ROOT/tracks/qcs/solutions/WangTheoPhys/issue128"
+export PYTHONPATH="$ISSUE_ROOT/src${PYTHONPATH:+:$PYTHONPATH}"
+OUT="$REPOSITORY_ROOT/results/$ISSUE128_RUN_ID/verification"
+mkdir -p "$OUT"
+cd "$ISSUE_ROOT"
+
+set +e
+"$REPOSITORY_ROOT/.venv/bin/python" -u scripts/verify.py \
+  certificates/issue128-certificate.json --deep \
+  >"$OUT/deep-verifier.stdout" 2>"$OUT/deep-verifier.stderr"
+VERIFY_RC=$?
+"$REPOSITORY_ROOT/.venv/bin/python" -m pytest -q -o addopts='' \
+  >"$OUT/pytest.stdout" 2>"$OUT/pytest.stderr"
+PYTEST_RC=$?
+set -e
+
+"$REPOSITORY_ROOT/.venv/bin/python" - "$OUT" "$VERIFY_RC" "$PYTEST_RC" <<'PY'
+import datetime
+import hashlib
+import json
+import pathlib
+import sys
+
+root = pathlib.Path(sys.argv[1])
+verify_rc = int(sys.argv[2])
+pytest_rc = int(sys.argv[3])
+files = {}
+for path in sorted(root.glob("*.std*")):
+    files[path.name] = hashlib.sha256(path.read_bytes()).hexdigest()
+payload = {
+    "schema_version": 1,
+    "kind": "issue128_hpc_verification",
+    "status": "complete" if verify_rc == 0 and pytest_rc == 0 else "failed",
+    "deep_verifier_exit_code": verify_rc,
+    "pytest_exit_code": pytest_rc,
+    "completed_at": datetime.datetime.now(datetime.timezone.utc).isoformat(),
+    "sha256": files,
+}
+(root / "manifest.json.tmp").write_text(json.dumps(payload, sort_keys=True, indent=2) + "\n")
+(root / "manifest.json.tmp").replace(root / "manifest.json")
+PY
+
+test "$VERIFY_RC" -eq 0
+test "$PYTEST_RC" -eq 0

scripts/harness_slurm.sh

@@ -21,6 +21,7 @@
 #   precheck                 resolve profile, test ssh, capture git dirty status
 #   probe-partitions         ssh sinfo and print a parsed candidate table
 #   submit ...               build+run sbatch, or validate with --test-only
+#                            (repeat --env KEY=VALUE for explicit job metadata)
 #   status <jobid>           squeue the job, parse state + pending-reason category
 #   fetch <run>              rsync results/<run>/ back from the cluster
 #   classify <run> <jobid>   sacct + per-cell manifests -> cell outcome table
@@ -208,6 +209,7 @@ cmd_probe_partitions() {
 cmd_submit() {
   local array="" run_spec="" command="" entrypoint="" partition="" walltime="" cpus="" \
         script="scripts/harness_array_sbatch.sh" extra="" test_only="false"
+  local -a job_env=()
   while [[ $# -gt 0 ]]; do
     case "$1" in
       --array) array="$2"; shift 2 ;;
@@ -218,6 +220,7 @@ cmd_submit() {
       --time) walltime="$2"; shift 2 ;;
       --cpus) cpus="$2"; shift 2 ;;
       --script) script="$2"; shift 2 ;;
+      --env) job_env+=("$2"); shift 2 ;;
       --extra) extra="$2"; shift 2 ;;
       --test-only) test_only="true"; shift ;;
       *) die "submit: unknown flag $1" ;;
@@ -237,6 +240,12 @@ cmd_submit() {
   elif [[ -n "$array" ]]; then
     die "submit: --array requires --run-spec; use a plain --script for single jobs"
   fi
+  local assignment
+  for assignment in "${job_env[@]}"; do
+    [[ "$assignment" =~ ^[A-Za-z_][A-Za-z0-9_]*=[^,[:space:]]+$ ]] || \
+      die "submit: --env must be KEY=VALUE without commas or whitespace"
+    exports="${exports},${assignment}"
+  done
 
   local extra_partition="" extra_gres="" extra_status=0 \
         extra_partition_set="false" extra_gres_set="false"