Conversation
Squashed feature/uhfk-antiperiodic-bc (13 commits, 26 files,
+1477 lines) into dev-boundary. APBC = twist angle pi is implemented
by injecting a gauge phase exp(i sum_d theta_d R_d / L_d) onto the
real-space transfer T(R) in _make_ham_trans, so the rest of the FFT
+ SCF pipeline runs unchanged on the standard k-grid. Per-site
one-body Green output (_save_greenone) applies the inverse gauge
phase exp(i sum_d theta_d (r_i_d - r_j_d) / L_d) to off-diagonal
entries so that _UHF_cisajs.dat is in the physical c basis,
directly comparable with ComplexUHF and usable as initial-Green
input for mVMC's APBC convention.
User-visible interface
* New [mode.param] key BoundaryCondition: length-3 list of
'periodic' / 'antiperiodic' (case-insensitive aliases 'P' / 'AP').
Default ['periodic'] * 3 (full PBC, backward compatible).
* New eigen.npz field twist_offset: shape-(3,) float64, values
in {0, 1/2}. Consumers reconstruct physical k as
(wavevector_index[n] + twist_offset) @ wavevector_unit.
Existing keys unchanged.
* _export_hamiltonian also emits <prefix>BoundaryCondition.dat
so that a consumer of the exported Transfer can reconstruct the
boundary independently. Transfer is exported unmodified.
* en/ja documentation for both BoundaryCondition and twist_offset.
v1 scope guards (fail-fast)
* APBC requires explicit SubShape = [1, 1, 1] (omitted SubShape
defaults to CellShape, which is rejected when combined with any
antiperiodic direction).
* APBC combined with PairHop or PairLift is rejected (non-density
interactions are not gauge-invariant under the site-dependent
gauge; deferred to v2). CoulombIntra, CoulombInter, Coulomb,
Hund, Ising, Exchange are accepted.
Tests (37 new + 0 regressions, 572 passed total)
* Unit: phase helper (13), BoundaryCondition normalization (10),
v1 guards (16).
* Physical correctness: 1D / 2D / 3D APBC eigenvalue spectrum
matches the analytic closed form; L-site APBC equals the odd-k
subset of a 2L-site PBC spectrum; H(k) stays Hermitian under
APBC; inverse-gauge round-trip on _save_greenone.
* End-to-end gauge convention check: independent analytic
physical-basis Green for closed-shell 1D APBC vs production
output, exercises FFT direction + gauge phase + inverse-gauge
sign together (caught a self-referential gap from an earlier
Codex review).
Non-CI validation
* tests/validation/apbc_complexuhf/ Docker harness cross-validates
against mVMC ComplexUHF. case_1d_hubbard (L=8, t=1, U=2, quarter
filling): energy rel diff 5.81e-10, greenone max delta 1.187e-9
(both within the 1e-6 spec tolerance).
* README documents the workflow + caveat that APBC in ComplexUHF
is actually enabled via stan.in phase0=180.0 (StdFace bakes a
-1 on the wrap-around bond), NOT via the documented
NMPTrans < 0 (which is read into APFlag but not consumed
elsewhere in the ComplexUHF tree of mVMC-1.4.0).
mVMC-1.4.0/ is read-only and untouched throughout.
Extends the APBC support introduced in db6d877 with follow-up hwave-side work developed on feature/uhfk-mvmc-pairproduct-bridge. Highlights * APBC + SubShape > [1, 1, 1] support: sublattice_offset, full_lattice_displacement helpers; new src/hwave/solver/_apbc_phase.py * Green output: apply the inverse gauge phase per-site so the resulting _UHF_cisajs.dat is in the physical c basis and directly comparable with ComplexUHF * eigen.npz records twist_offset; green.npz records boundary_theta with a restart-mismatch warning * _export_hamiltonian emits BoundaryCondition.dat and exports the raw Transfer.dat so downstream consumers do not double-apply the twist * Occupation output: save converged occupation, mu and T to occupation.npz (documented in en/ja rst) Tests * Analytic APBC / PBC-subset match * Multi-orbital + complex-hopping APBC spectrum pin * 2-orbital APBC spectrum pin * APBC output shape / consistency / guards * Sublattice APBC analytic match and SubShape independence * Green deflate SubShape coverage * occupation.npz save / load round trip Validation * Adds a ComplexUHF docker validation harness at tests/validation/apbc_complexuhf/ with case_1d_hubbard_sublattice. Chore * Untracks internal planning/spec docs under docs/superpowers/ that slipped into the tree before .gitignore was applied. User-visible interface is identical to db6d877 (BoundaryCondition + twist_offset); no breaking change.
…PBC)
Introduces tools/uhfk_to_mvmc.py, a converter from an H-wave UHFk SCF
result to an mVMC PairProduct InOrbitalAntiParallel input. This is the
initial bridge version (v1) and covers the AntiParallel path under both
periodic and antiperiodic boundary conditions.
Design
* CLI in tools/uhfk_to_mvmc.py; helpers under tools/_uhfk_to_mvmc/
- input_loader.py : read eigen.npz + green.npz + orbitalidx.def
- partner_index.py : (k, -k) partner table with signed wv-index
- occupation_step.py : T = 0 occupation with fractional / degeneracy
fail-fast guards
- fij_builder.py : (k, -k) pair F_ij builder; APBC add-add phase
- orbitalidx_reader.py : orbitalidx.def (PBC 3-col / APBC 4-col)
- output_writer.py : atomic write of zqp_orbital_uhfk.dat, sign-
aware averaging, rank-lift epsilon = 1e-8
- density_check.py : consistency of ship-side F vs source G
Correctness
* Bloch sign + pair closure under APBC (empirically fixed against the
1D Hubbard PBC/APBC reference)
* Rank-lift noise lowered from 1e-6 to 1e-8 to remove residual mVMC
<H> bias on APBC Ne = 4
* Class-consistency and format guards, fail-fast on odd Ncond /
mixed-block inputs
Validation harness
* tests/validation/uhfk_mvmc_pairproduct/{case_pbc, case_apbc,
case_apbc_halffill}
* run.sh drives H-wave -> bridge -> StdFace -> ComplexUHF -> mVMC
* compare.py evaluates <H>_mVMC vs <H>_ComplexUHF
* README.md documents the harness
Tests
* Unit + fail-fast + phase / partner / output-format / occupation
coverage (11 test files); density check + density invariance;
Pfaffian-mimic F round trip; naive vs k-mink partner equivalence;
end-to-end PBC + APBC (xfail-then-pass across the APBC fix)
Docs
* en / ja uhfk/tools/uhfk_to_mvmc.rst plus index_tools inclusion
Extends the v1 AntiParallel bridge to SubShape > [1, 1, 1] (folded Brillouin zone), and fixes a sign discrepancy in the sublattice pair closure that was not visible on SubShape = [1, 1, 1] (v2.1). Design (v2.0) * tools/_uhfk_to_mvmc/sublattice_unfold.py: helpers that expand a folded-BZ eigenvector across the sublattice, expose cell_shape and sub_offset for each row * fij_builder accepts (cell_shape, subshape) so pair-closure keys are (k_row, local_band) tuples, matching the mVMC per-band pair index * CLI validates SubShape divisibility and shape consistency Correctness fix (v2.1) * Positive-Bloch sign flip: sub-lattice folded convention wants exp(+i k . r) rather than exp(-i k . r) in the pair-closure phase. Non-sublattice SubShape = [1, 1, 1] paths are unaffected; sublattice paths now match the analytic density on case_apbc_sublattice. Validation harness * case_apbc_sublattice (L = 8, SubShape = [2, 1, 1]) * case_2d_hubbard_sublattice (4 x 4, SubShape = [2, 2, 1]) * README + activation of the mVMC E2E after v2.1 fix Tests * sublattice_unfold coverage (row -> cell_shape / sub_offset, invariance under folding) * fij_builder sublattice pair-closure regression * partner / phase / e2e / fail-fast / Pfaffian-mimic density updates under SubShape > 1 Docs * en / ja rst reflect SubShape > 1 scope and positive-Bloch convention * Fix stale 1e-6 rank-lift default note in output_writer / E2E README
Adds the mVMC General path (InOrbitalGeneral orbitalidx_general.def)
alongside the existing AntiParallel path. General accepts Sz-fixed
2 Sz != 0 states and Sz-free non-mixed states that AntiParallel cannot
express with a single (k, -k) closure.
Design
* Format-first CLI dispatch: (is_antiparallel_metadata,
orbitalidx_format) selects the emitter. StdFace with HubbardGC and
friends emits orbitalidxgen.def; the bridge routes to General when
it detects that format.
* Class-consistency fail-fast: General inputs are checked against the
hwave block structure at load time (odd Ncond + mixed block are
rejected up front)
* New helpers under tools/_uhfk_to_mvmc/:
- general_fij_builder.py : canonical rep + spin-cross pair-closure;
same-spin excess pair emission for
2 Sz > 0; Slater orbital extraction +
antisymmetric F construction
- general_output_writer.py: atomic write of zqp_orbital_uhfk.dat
with class-consistency fail-fast
- orbitalidx_general_reader.py: arity-based format detection with
header-only rejection
* density_check.py grows a 2 Ns x 2 Ns G branch that compares against
greenone (used by General)
Validation harness
* case_pbc_sz2 (v3 A: Sz-fixed 2 Sz = 2)
* case_zeeman_sz_free (v3 B: Sz-free non-mixed)
* run.sh routes v3 fixtures through StdFace orbitalidxgen.def
* scripts/assert_occupation.py shared occupation gate
Tests
* Dispatch matrix, general fij_builder, general orbitalidx reader,
general output writer, per-case occupation regressions, fail-fast
guards (odd Ncond, mixed block)
Docs
* en / ja rst document InOrbitalGeneral dispatch and the class-
consistency contract
Adds spin-orbit coupling support (v3.1) to the General path and extends it to the antiperiodic boundary condition (v3.2). SOC + SubShape > [1,1,1] is intentionally deferred to a later spec; the CLI rejects that combination up front. v3.1 SOC * CLI carries an is_soc_mode dispatch flag; expands the routing matrix to six cases. Reject rules are stated explicitly. * validate_general_prerequisites and occupation_step accept column_spin = -1 under is_soc_mode * general_fij_builder SOC branch: mVMC spin-block A permutation with SOC self-pair parity and n_occ balance guards * density_check accepts s != t entries under is_soc_mode; asymmetric greenone golden data * trans_emit.py: emit mVMC trans.def directly from H-wave Transfer.dat under SOC. Wannier90 mode of StdFace turned out not to be enough on its own. Divides coefficients by Wannier90 ndegen; rejects duplicate Transfer.dat entries; atomic write with same-path / directory-target preflight * Sign convention on the diagonal / off-diagonal split of trans_emit is empirically pinned via ComplexUHF cross-check (case_soc_rashba_2d_nosub, matches within 4.4e-8 %) * boundary_input.py canonicalizes BoundaryCondition and enforces eigen twist consistency * _reshape_orbit_ in hwave-side stride is corrected for enable_spin_orbital = true; _save_greenone extended to emit packed spin-orbital indices v3.2 SOC + APBC (A1) * trans_emit applies the boundary gauge phase to Transfer entries under APBC so the emitted trans.def is boundary-consistent * SOC plane-wave twist gauge matched to the negative-Bloch convention * Lifts the SOC + APBC reject; case_soc_rashba_2d_nosub_apbc validates end-to-end within 0.03 % delta Deferred (SOC + SubShape > [1, 1, 1]) * CLI rejects the SOC + SubShape combination pre-dispatch until the bridge grows a subshape-aware gauge check * case_soc_rashba_2d_sub fixture data is present but not activated Validation * case_soc_rashba_2d_nosub (SOC only) * case_soc_rashba_2d_nosub_apbc (SOC + APBC) * case_soc_rashba_2d_sub (fixture data only; deferred) * Helper scripts: emit_onebodyg_full_soc.py, emit_rashba_transfer.py, soc_pilot_gap.py; assert_occupation.py extended for SOC Tests * trans_emit (unit + sign-convention regression), general_fij_builder SOC additions, occupation SOC coverage, dispatch matrix 6-case * apbc_phase_normalize, hwave uhfk export / folding regressions Docs * en / ja rst document v3.1 six-case dispatch, SOC + APBC scope, and the SOC + SubShape defer
Lifts the SOC + SubShape > [1, 1, 1] defer from v3.2. Delivered in two
steps that ended up in the same final tree; v3.3 was a blocked attempt
whose signal was folded into the v3.4 root-cause and is not carried in
this squash.
v3.4 sub_offset in the SOC plane-wave phase
* general_fij_builder SOC branch computes the plane-wave phase as
exp(-i k_folded . (folded_cell + sub_offset))
* SubShape = [1, 1, 1] paths keep sub_offset = 0 and are bit-identical
to the pre-v3.4 SOC path
* case_soc_rashba_2d_sub cleared 0.22 % delta on mVMC <H> with this
single change
v3.5 gauge-lifted density check + dual-A scaffold removal
* tools/_uhfk_to_mvmc/density_check.py::gauge_lift reconstructs
k-resolved G_k from H-wave green_sublattice via ifftn (SOC block
extraction + 3-D spatial reshape), then applies the twist gauge
phase exp(-i k . (r_j - r_i)) with r_phys = folded_cell + sub_offset
and 1 / N_folded normalization
* compare_against_green_sublattice grows an is_soc_sublattice_mode
branch that iterates all (site, spin) pairs and compares
G_ship = np.conj(A) @ A.T against the reconstructed G_ref at 1e-10
* Deleted the v3.4 dual-A scaffold (reference-A + _soc_reference_convention)
because it validated the reference construction, not the shipping A
* CLI drops the SOC + SubShape reject; the SOC + APBC + SubShape triple
combination remains rejected pre-dispatch (still deferred to a
future spec)
Emitters
* tools/_uhfk_to_mvmc/orbitalidx_general_emitter.py provides an
all-unique-classes fallback so SOC + SubShape can emit
orbitalidxgen.def when StdFace does not
Validation
* case_soc_rashba_2d_sub (SubShape = [3, 2, 1]) shipping at 0.22 % delta
* Test-data snapshots pinned under tests/data/ so density-check unit
tests do not require a live H-wave run
Harness security (v3.4 / v3.5 side-effects)
* run.sh rejects path-traversing CASE arguments (leading '.' / '..' /
'/'); rejects symlink CASE_DIR; realpath check pins
CASE_DIR_REAL == HERE_REAL / CASE before rm -rf ${WORK}
Tests
* Extensive density_check gauge-lift tests (round trip, scale, spin
swap, orientation, gauge invariance)
* orbitalidx_general_emitter unit tests (all-unique-classes fallback)
* Expanded dispatch matrix; trans_emit sign-convention note aligned
Docs
* en / ja rst mark v3.5 GA with the gauge-lift density-check scope,
and note SOC + APBC + SubShape still deferred
…round Codex hardening
Extends the H-wave UHFk -> mVMC PairProduct bridge to support the
triple combination of Rashba spin-orbit coupling, single-direction
antiperiodic boundary condition, and sublattice folding
(SubShape > [1, 1, 1]). Validated end-to-end by the new shipping
fixture case_soc_rashba_2d_sub_apbc (CellShape [6, 4, 1],
SubShape [2, 2, 1], BoundaryCondition [antiperiodic, periodic,
periodic], Rashba alpha = 0.5, Ncond = 8).
Squashes 21 commits from feature/uhfk-mvmc-pairproduct-general-v36:
14 Phase 1-7 commits landing the v3.6 GA (documented in
docs/superpowers/2026-07-12-session-handoff-v36-ga.md) plus 5
Codex-adversarial-review-driven hardening rounds documented below.
Ships:
* tools/_uhfk_to_mvmc/pair_product_density.py
parse_emitted_F + pair_product_density_from_F (spec §5.4 skew-
SVD projector from the emitted F to a physical density).
* tools/_uhfk_to_mvmc/energy_compare.py
energy_relative_delta + _resolve_g3_paths (spec §5.6 canonical
G3 comparison via /hwave/energy.dat + /
mvmc/zvo_out_selected.dat).
* tools/_uhfk_to_mvmc/density_check.py
gauge_lift gains a boundary_theta parameter that composes the
APBC twist gauge with the sub_offset gauge. Downstream
compare_against_green_sublattice plumbs it end-to-end.
* tools/_uhfk_to_mvmc/general_fij_builder.py
build_slater_orbitals SOC branch composes both gauges on the
shipping A matrix.
* tools/uhfk_to_mvmc.py
Narrowed CLI reject: SOC + multi-direction APBC + SubShape > 1
remains deferred to v3.7; single-direction APBC + SOC +
SubShape > 1 is now supported and ships against case_soc_
rashba_2d_sub_apbc. --debug-writer flag dumps F_pre_noise +
F_post_aggregate npz snapshots for the G0-writer-check gate.
* tests/validation/uhfk_mvmc_pairproduct/
run.sh gains a seven-gate branch for
case_soc_rashba_2d_sub_apbc:
G0-writer-check (parse_emitted_F, bridge_zeronoise)
G1 (build_slater_orbitals+gauge_lift)
G2a-emitted-F (parse_emitted_F + pair_product_density,
bridge+complexuhf)
G2a-in-memory-A (build_slater_orbitals, hwave+complexuhf)
G2b (gauge_lift, hwave+complexuhf)
G3 (energy_relative_delta, hwave+mvmc)
G4 (soc_apbc_topology_guard, hwave+bridge+
composite-manifest)
Anchored PASS record verification via awk index() per spec
§5.3b, with normalize_mvmc_output bash helper per §5.6.
* compare.py --workspace/--mode dispatcher with a deep-frozen
EXPECTED_MODE_DISPATCH registry that maps every §5.3b gate row
to its canonical helper (importlib + getattr resolution;
hostile module-substitution rejected).
* scripts/soc_apbc_topology_guard.py --mode g4 semantic guard:
verifies the composite element (i_c, s_c, j_c, t_c) from
composite_element.json against the current SCF workspace,
reruns the M-gauge-1..5 + M-ship-1..5 mutation matrix, and
emits the anchored G4 PASS record.
* scripts/phase2_produce_manifest.py: Phase 2 producer that
selects the composite element via a strong-mutation gate
(every real mutation delta >= 10% |G_base|) and writes
composite_element.json.
* case_soc_rashba_2d_sub_apbc/ fixture with input.toml
(BoundaryCondition = AP-P-P), stan.in (phase0 = 180.0 for
ComplexUHF), Transfer.dat / CoulombIntra.dat / Geometry.dat /
geometry_uhf.dat / OneBodyG.dat, composite_element.json
(committed manifest for G4).
Codex adversarial-review hardening (5 rounds, 2026-07-12):
1. G1/G2a/G2b dispatchers replaced from PASS-emitting stubs to
real numeric comparisons. Shipping A density + gauge_lift-
lifted green_sublattice + strict-parsed ComplexUHF cross-
checks.
2. Snapshot-workspace rejection guard anchored at the guard
module's own location (parents[3]) so invocation from outside
the repo can no longer bypass tests/data rejection.
3. G4 shadow-copy _build_A_ship_mutated asserts baseline
equality with canonical build_slater_orbitals at 1e-10 before
running mutations; drift in the shipping kernel becomes
visible.
4. MVMC_LD_LIBRARY_PATH validated (absolute, owned by current
user, non-world-writable, single directory only); caller
LD_LIBRARY_PATH REPLACED (not appended) with the accepted
path or unset entirely.
5. LD_PRELOAD / LD_AUDIT / BASH_ENV / ENV unset at top of
run.sh; inherited traps cleared via 'trap - DEBUG ERR RETURN
EXIT'; run_native() shell function wraps every native solver
invocation with '/usr/bin/env -u LD_PRELOAD -u LD_AUDIT [-u
LD_LIBRARY_PATH|LD_LIBRARY_PATH=...] ...' for per-command
scrubbing. Absolute /usr/bin/env path resists shell-function
shadowing and PATH poisoning.
6. Cross-solver ComplexUHF seeding
(scripts/seed_complexuhf_from_hwave.py): H-wave shipping A
density is written into ComplexUHF's initial.def with a small
Hermitian perturb-scale (1e-6 for this fixture) so
ComplexUHF actually iterates (>= 1 SCF step, enforced by
awk-parse of uhf.log) but stays inside H-wave's basin. Post-
seeding ComplexUHF runs 9 SCF steps and matches H-wave at
Energy_Total = -25.3717166 (10 digits).
Regression tests (all in tests/):
* test_uhfk_to_mvmc_density_check.py (Phase 3b + 3c + Phase 4
parametrized 10-mutation matrix on the Phase 3 snapshot).
* test_uhfk_to_mvmc_pair_product_density.py (Phase 3d zero-noise
pin on v3.5 case_soc_rashba_2d_sub).
* test_uhfk_mvmc_pairproduct_compare_wiring.py (18 dispatch
wiring tests + 6 strict ComplexUHF parser negatives).
* test_soc_apbc_topology_guard_semantic.py (7 tests: 6 negative
contract pins + 1 positive baseline).
* test_snapshot_rejection_guard_v36.py (12 tests: literal /
subdir / symlink / artifact-symlink rejections + non-repo-
CWD + real-fixture positive baseline).
* test_apbc_complexuhf_soc_smoke.py (5 smoke tests for the
apbc_complexuhf/ SOC fixture parity).
* test_run_sh_loader_env_sanitize.py (6 tests: LD_PRELOAD /
LD_AUDIT / LD_LIBRARY_PATH sanitization + structural precedence
+ BASH_FUNC_env%% shadow resistance).
Fresh E2E on empty for case_soc_rashba_2d_sub_apbc
emits all seven anchored PASS records with deltas well under spec
tolerance:
G0-writer-check: 2.78e-17 vs 1e-10
G1: 1.41e-13 vs 1e-10
G2a-emitted-F: 2.92e-08 vs 1e-6
G2a-in-memory-A: 2.83e-08 vs 1e-6
G2b: 2.83e-08 vs 1e-6
G3: 2.05e-04 vs 1e-2
G4: 0.00e+00 vs 0.2
Full pytest sweep: 892 passed, 6 skipped, 16 warnings (baseline
pre-v3.6 802 passed; +90 v3.6 tests across Phase 1-7 + 5-round
hardening).
Deferred to v3.7: SOC + multi-direction APBC (n_apbc_dirs >= 2) +
SubShape > 1. Rejected pre-dispatch with a documented message
(quoted verbatim in docs/en + docs/ja source/uhfk/tools/
uhfk_to_mvmc.rst).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
… 5-round review hardening
Extends the H-wave UHFk -> mVMC PairProduct bridge from v3.6's single
antiperiodic direction to arbitrary combinations of them, on a 3D
lattice with sublattice folding. Validated end-to-end by four shipping
fixtures covering every active-axis mask (CellShape [4, 4, 4],
SubShape [2, 2, 2], xy-plane Rashba alpha = 0.5, general complex
z-direction spin-mixing hopping, U = 2):
case_soc_rashba_3d_sub_apbc_xy AP AP P Ncond = 20
case_soc_rashba_3d_sub_apbc_xz AP P AP Ncond = 20
case_soc_rashba_3d_sub_apbc_yz P AP AP Ncond = 24
case_soc_rashba_3d_sub_apbc_xyz AP AP AP Ncond = 12
Ncond is not uniform: each fixture is pinned to the filling that clears
both a >= 5e-2 HOMO-LUMO gap and the build_pair_list partner-balance
invariant n_occ(k) == n_occ(partner(k)).
Squashes 58 commits from feature/uhfk-mvmc-pairproduct-general-v37:
Tasks 1a-7c landing the v3.7 GA, three Codex adversarial-review rounds
during development, then a final branch review plus two more review
rounds documented below. Full history in
docs/superpowers/2026-07-19-session-handoff-v37-ga.md and
docs/superpowers/2026-07-20-session-handoff-v37-post-review.md.
Two physics defects were found and fixed while bringing up the fixtures:
* trans.def spin-off-diagonal rule generalized. The emitter had an
empirically fixed trans = +v, replaced by the general rule
K[i, t; i+R, s] = conj(v)
trans[i, t; i+R, s] = -conj(v)
which swaps the spin endpoints and conjugates, leaving the site
endpoints alone. v3.6's Rashba matrices satisfy v[t,s] = -conj(v[s,t])
at fixed R, exactly the condition under which both rules agree, so
v3.6 is matrix-identical (though not byte-identical: off-diagonal rows
swap their spin labels and some -0.0 become 0.0). The v3.7 z block
does not satisfy it, which is what exposed the bug: reconstructing the
bare K from 128 eigenpairs gives max_abs_delta 6.000e-01 under the old
rule and 1.138e-12 under the new one.
* flag_fock unified to true across the shipping fixtures. ComplexUHF
fixes the exchange term at compile time (#define Fock 1), so
flag_fock = false meant minimizing a different functional than the
cross-solver reference. The setting was inherited from pre-SOC v2
fixtures where the on-site Fock term was identically zero and the
choice was physically meaningless. Under v3.7's z-SOC the transverse
spin density reaches 2.7e-2 and the mismatch became visible. No Ncond
pin moved.
Ships:
* tools/_uhfk_to_mvmc/allowlist_predicate.py + allowlist_coverage.py
The v3.6 pre-dispatch reject for multi-direction APBC is replaced by
an allowlist predicate, with a coverage checker over the mask space.
* tools/_uhfk_to_mvmc/phase5_gate.py
Static and live gates for the ComplexUHF bundle: reads the SCF
artifacts, checks Nsite line by line against stan.in, cross-checks
the phase mask against fixture, workspace and geometry, verifies
bundle line counts, NTransfer, per-row trans.def Hermiticity, byte
equality with the mVMC-side copy, and recomputes every provenance
field.
* tools/_uhfk_to_mvmc/transfer_hermiticity.py
Hermitian-pair checker over post-ndegen coefficients, wired into
run.sh, the manifest producer and the product CLI.
* tools/_uhfk_to_mvmc/trans_emit.py
General spin-off-diagonal rule (above); emit_trans_def_from_entries
so callers can validate parsed entries and emit them without parsing
twice; validate_trans_def_entries shared with the emitter.
* tools/uhfk_to_mvmc.py
Parses and fully validates Transfer.dat before any producer runs,
and refuses output destinations that alias each other or any input.
* tests/validation/uhfk_mvmc_pairproduct/
run.sh runs the seven-gate branch for all four v3.7 fixtures via
--all-v37, with a Phase 5 gated ComplexUHF launch. An unknown
v3.7 case name is now a hard error rather than a silent fallback.
* scripts/soc_apbc_topology_guard.py + phase2_produce_manifest.py
v3.7 mutation matrix over active axes, with the producer failing
closed on non-positive thresholds.
Review hardening. Three rounds ran during development (18 findings, 11
fixed, 7 WONTFIX with recorded rationale and re-examination conditions).
A final branch review and two further rounds ran afterwards, fixing 14
more findings:
Final branch review (Critical 0 / Important 3 / Minor 4)
* Several test modules read green/eigen/occupation.npz and
greenone.dat from fixture output/ directories, which .gitignore
excludes. Locally surviving E2E artifacts hid the dependency, so a
clean checkout failed during setup and those tests never ran in
CI. They now stage workspaces from tracked tests/data snapshots.
* The Hermiticity checker reached run.sh and the manifest producer
but not the product CLI, which parsed Transfer.dat and emitted
straight away. The bridge mapping only reproduces the input
Hamiltonian when H is Hermitian, and H-wave passes non-Hermitian
transfers with a warning when strict_hermite = false.
* The four fixtures were described as "3D Rashba". The z-direction
rows give H_z(k_z) = (0.6 cos k_z - 0.8 sin k_z) sigma_x, whose
even component breaks spin-1/2 time reversal, so the block is a
general complex spin-mixing hopping. It stays Hermitian, so the
fixtures and every gate result remain valid; only the wording was
wrong. A time-reversal-symmetric 3D SOC fixture is a v3.8
follow-up.
Round 4 (high 3 / medium 1)
* G0 and G1 compared with `if max_abs_delta > gtol`, and nan > gtol
is false, so a NaN in either operand or in the tolerance produced
an anchored PASS carrying max_abs_delta=nan. The same fail-open
had been fixed in G2 and G3 in an earlier round but never applied
to G0 and G1. The threshold check now goes through one
_validated_max_abs_delta helper so a gate cannot acquire the hole
by being written without the check.
* G3's zvo_out parser read only column 0 of each row, so a file
truncated right after a matching energy passed. Every non-comment
row now needs exactly six finite numeric columns; mVMC 1.4.0
writes that row unconditionally (vmcmain.c:649).
* The CLI Hermiticity check ran after --emit-orbitalidx and
--debug-writer had already written. Validation now precedes every
producer.
Round 5 (medium 1 / low 2)
* Moving the parse ahead of the producers made --emit-orbitalidx
pointed at the --transfer path succeed while destroying the input,
since trans.def was then built from the cached entries. The
destination preflight now enumerates every active destination and
rejects aliases of other destinations or of any input.
* Splitting the entry loop into validate-then-emit meant a generator
argument was consumed by validation and the emitter wrote
NTransfer 0 while exiting zero. Entries are materialized once.
* The atomic-cleanup test's input started failing in the
pre-validator, so its "no stray tmp" assertion only showed that no
temp was ever created. A separate test now injects an os.replace
failure and checks the temps are removed.
Fresh E2E via run.sh --all-v37 emits 28 anchored PASS records:
gate xy xz yz xyz tol
G0-writer-check 2.776e-17 2.776e-17 4.163e-17 2.776e-17 1e-10
G1 3.199e-13 3.085e-13 2.987e-13 3.411e-13 1e-10
G2a-emitted-F 3.105e-08 2.180e-08 3.736e-08 1.589e-07 1e-06
G2a-in-memory-A 2.706e-08 2.180e-08 3.703e-08 1.550e-07 1e-06
G2b 2.706e-08 2.180e-08 3.703e-08 1.550e-07 1e-06
G3 1.097e-04 3.755e-04 4.490e-04 1.116e-04 1e-02
G4 0.000e+00 0.000e+00 0.000e+00 0.000e+00 2e-01
The residual ~1e-8 in G2 is ComplexUHF's own SCF stopping condition, not
a physics disagreement: its energy approaches H-wave's monotonically and
the gap shrinks by exactly 0.50 per step (Mix = 0.5 linear mixing) until
the internal residue drops below 1e-10. A functional mismatch would
plateau instead, as it did at 3.1e-3 while Fock was disabled.
v3.6 case_soc_rashba_2d_sub_apbc still passes its seven gates after the
flag_fock change, with G2 upgraded from a stationarity check to a real
cross-solver convergence test (initial_delta 3.888e-04 -> final_delta
2.437e-08, contraction ratio 6.27e-05).
Full pytest sweep in a clean worktree: 1199 passed, 36 skipped
(pre-v3.7 baseline 892 passed). The 36 skips are all accounted for: 30
inactive-axis mutations that are no-ops by construction, 2 requiring
libtetrabz, 2 v1 snapshots Phase 3 will regenerate, 2 covered by
sibling tests.
Deferred to v3.8: a time-reversal-symmetric 3D SOC fixture, CellShape
beyond [4, 4, 4], non-orthogonal Bravais lattices, and the H-wave
_deflate_green aa/bb slot bug. General twist boundaries (theta outside
{0, pi}) remain out of scope and are documented as unverified.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Squash-integrate origin/develop into the v3.7 bridge line. Content only: no merge parent is recorded, so dev-boundary and origin/develop histories stay independent (merge-base remains b7a24c9). A later sync will therefore re-present this same diff and re-conflict the same files. Conflicts (3 files, 5 hunks). Both sides were almost entirely additive: - uhfk.py imports: kept both (_apbc_phase from HEAD, fold + wan90 from develop) - uhfk.py _reshape_interaction: took develop's fold.reshape_interaction(). Verified it already carries both HEAD-side fixes -- the norb_phys_orig physical stride (fold.py:84) and the wrap-around accumulation (fold.py:128) -- and that the SO-mode even-norb validation moved into _init_orbit, still reached from __init__ (uhfk.py:42, uhfk.py:318). HEAD's own regression test for the stride fix (TestReshapeInteractionStrideSO, absent upstream) passes against develop's implementation, which confirms the choice empirically. - uhfk.py save_green savez: kept all four keys, HEAD's boundary_theta alongside develop's green_convention marker from PR issp-center-dev#35. - green_uhfk.rst (ja): kept both paragraphs, mirroring the en file's order. - test_uhfk_green_deflate_subshape.py: kept both sides' tests, no name collisions. Two test stubs build UHFk via object.__new__ and so skip _init_orbit; they now set norb_phys_orig to mirror it, since develop's _reshape_interaction reads that attribute (test_uhfk_folding.py, test_uhfk_apbc_sublattice.py). Production is unaffected -- _init_orbit always runs from __init__. The two RPA stub files need no change because rpa.py computes norb_phys_orig itself. Verification: - pytest 1450 passed / 100 skipped / 0 failed (baseline 1199 / 36 / 0). The 64 added skips are all optional-dependency skips from develop's new FLEX/IR/Eliashberg/GPU tests (sparse-ir 52, cupy 12). All 36 original skips are intact with unchanged reasons; no bridge test was disabled. - E2E v3.7 run.sh --all-v37: SEVEN-GATE PASS x 4 fixtures (28/28). - E2E v3.6 case_soc_rashba_2d_sub_apbc: SEVEN-GATE PASS. - All 35 gate values match the v3.7 GA record to the 4 significant figures in which that record was kept. No stronger agreement is established. On PR issp-center-dev#35 and the Green fold convention. An earlier draft of this message claimed the gate agreement was empirical proof that PR issp-center-dev#35's changed _deflate_green slot convention does not disturb the bridge. That claim was wrong on its premise and has been removed. dev-boundary already carried the first-slot default via a7e2242, so this integration does not change _deflate_green or _reshape_green semantics at all -- git diff dev-boundary HEAD shows no change to them. There was no semantic transition here for the gate values to test. What they do establish is that the integration itself is regression-free. Relatedly, the bridge does not read green_sublattice exclusively: the SOC+sublattice route does, but other density-check routes parse greenone.dat, which _save_greenone generates via _deflate_green's default convention (uhfk.py:2488, tools/uhfk_to_mvmc.py:713,763,977). Those routes are unaffected here for the same reason -- the convention did not change -- but they are not covered by the SOC+sublattice fixtures cited above.
…docs The mVMC bridge under tools/ and its tests carried comments, messages and docstrings that cited development version numbers (v3.1 .. v3.7) and sections of design specs kept in the gitignored docs/superpowers/. That directory ships in no release, so anyone holding only the repository could resolve none of them. The user-facing rejection messages were the worst case, explaining a refused run in terms a reader cannot look up. This squashes the five-commit cleanup done on feature/doc-comment-cleanup: - docs: the bridge documentation had one scope section per version, so a reader had to merge five sections and infer which statements later ones superseded. Two sections still claimed the SOC+APBC+SubShape>1 case is rejected, which the later sections contradict. Split into a new algorithm/uhfk_to_mvmc.rst (conventions and construction) and a rewritten usage page (ja 571->332, en 597->348), both free of version numbers. - tools: 21 files. Algorithm-level pointers now reference the docs by stable path; local constraints kept their substance and lost the pointer; pure history was deleted. The allowlist rejection now names the supported lattice shapes and directions instead of "the v3.7 allowlist". - tests: 50+ files, same treatment. Three files that assert on changed messages moved with them, and run.sh's two echo lines were updated in step with the byte-for-byte provenance test that pins them. - manifest: the schema tag "v3.6-10entry"/"v3.7-30entry" is renamed to "whole-vector-10entry"/"per-direction-30entry", after confirming nothing reads it back (the guard infers the shape from key count). - dispatch tests: six assertions guarding against retired rejection strings were the last version strings in test code and could never fire (the strings are not emitted by the CLI). Three dead lines removed, one empty test deleted, and one test with a real subject given live assertions whose detection power was verified by fault injection. No behaviour changed. This was checked independently of the subagent reports: comparing the AST of every changed tools/ and tests/ file with string constants normalised and docstrings dropped shows no structural difference, and because that is blind to a string used as an assertion operand, the literals inside assert statements were diffed separately. Verification: pytest 1449 passed / 100 skipped / 0 failed. E2E v3.7 28/28 SEVEN-GATE PASS and v3.6 SEVEN-GATE PASS, all 35 gate values reproducing the pre-cleanup run to every digit.
test_uhfk_apbc_input.py is named for "the normal input path" but imports
only normalize_boundary_condition and calls it directly in every test; it
never goes through the loader or UHFk. Its five properties are each already
checked, with equal-or-stronger assertions, by two other bridge test files:
- accepted forms + all-periodic default
-> test_apbc_phase_normalize.py::test_accepts_periodic_variants,
test_accepts_antiperiodic_variants, test_accepts_mixed_pbc_apbc
-> test_uhfk_apbc_phase.py::test_normalize_lowercase_full_words,
test_normalize_short_and_case
- wrong length raises (with match="length")
-> test_apbc_phase_normalize.py::test_rejects_wrong_length
-> test_uhfk_apbc_phase.py::test_normalize_rejects_wrong_length
- unknown value raises (with match="unknown")
-> test_apbc_phase_normalize.py::test_rejects_open_and_ambiguous
-> test_uhfk_apbc_phase.py::test_normalize_rejects_unknown_value
- non-string entry raises TypeError
-> test_uhfk_apbc_phase.py::test_normalize_rejects_non_string
The retained files keep the match= diagnostics, so no fault-detection is
lost. Each property was mapped and confirmed by hand; the two covering
files pass on their own (35 passed).
This is the only file-level removal that a test-volume audit (controller +
Codex) found safe: the bridge's high test-to-core ratio (~2.5, repo-normal)
is inherent cross-code validation against mVMC ComplexUHF, not redundancy.
pytest 1439 passed / 100 skipped / 0 failed (was 1449; the 10 collected
cases of the removed file are the whole delta). No source changed, so the
seven-gate E2E path is unaffected.
Owner
Author
|
Superseded by the upstream PR issp-center-dev#76, which carries the same bridge rebased onto the current upstream develop tip (5504b56) so the diff is bridge-only. Closing this fork-internal draft; the branch pr/APboundary-uhfk2mvmc is kept. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
tools/uhfk_to_mvmc.py, a bridge that converts an H-wave UHFkself-consistent solution into the initial PairProduct wave function of mVMC
(
InOrbital/InOrbitalAntiParallel/InOrbitalGeneral). The mVMCPairProduct state can then be initialized from an H-wave UHF Slater matrix.
The bridge covers, deterministically:
multi-direction APBC.
Rashba, Dresselhaus, general sigma_x / sigma_y one-body coupling),
emitting the Sz-non-conserving
Fcomponents.SubShapedividingCellShape, includingthe SOC + APBC +
SubShape > [1, 1, 1]combination.automatically from the orbitalidx metadata, its column form, and
enable_spin_orbital.The mapping conventions (positive-Bloch amplitude, sub_offset gauge composed
with the APBC twist, canonical-pair
F, partner balance, thetrans = -conj(v)Transfer rule) are documented indocs/{en,ja}/source/algorithm/uhfk_to_mvmc.rst; usage indocs/{en,ja}/source/uhfk/tools/uhfk_to_mvmc.rst.Validation
pytest: 1439 passed / 100 skipped / 0 failed. The 100 skips areoptional-dependency (sparse-ir, cupy) and intentional non-active-axis
mutation no-ops.
trans.defagainst mVMC ComplexUHF (density, energy, topology gates):v3.7 four-fixture suite 28/28 PASS, v3.6 fixture PASS. Gate values are
stable to every recorded digit across the changes in this branch.
Notes for reviewers
itself — dominated by numerical validation fixtures under
tests/validation/(e.g.OneBodyG.dat) plus the unit tests and tools.branch integrated
origin/develop(144 commits) as a squash commit,by design, so histories stay independent. A side effect is that upstream
modules already on
develop—src/hwave/solver/{eliashberg_dynamic, ir_axis,matsubara,fold}.py,src/hwave/tsweep.py, their tests, and someFLEX docs (~15.6k insertions, ~40 files) — re-appear in the diff because
the squash shares no history with
develop's commits. They are not partof this feature.
Status
Draft. Opened on the fork (
k-ido/H-wave-dev) againstdevelop, not theupstream repository.