UHFk to mVMC PairProduct bridge (SOC + APBC + SubShape > 1)

[k-ido]

Summary

Adds tools/uhfk_to_mvmc.py, a bridge that converts an H-wave UHFk
self-consistent solution into the initial PairProduct wave function of mVMC
(InOrbital / InOrbitalAntiParallel / InOrbitalGeneral). The mVMC
PairProduct state can then be initialized from an H-wave UHF Slater matrix.

The bridge covers, deterministically:

• Boundary conditions: periodic and antiperiodic (APBC), including
  multi-direction APBC.
• Spin-orbit coupling: general complex spin-mixing hopping (Zeeman,
  Rashba, Dresselhaus, general sigma_x / sigma_y one-body coupling),
  emitting the Sz-non-conserving F components.
• Sublattice folding: any SubShape dividing CellShape, including
  the SOC + APBC + SubShape > [1, 1, 1] combination.
• Dispatch: three paths (AntiParallel / General / General-SOC) chosen
  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, the
trans = -conj(v) Transfer rule) are documented in
docs/{en,ja}/source/algorithm/uhfk_to_mvmc.rst; usage in
docs/{en,ja}/source/uhfk/tools/uhfk_to_mvmc.rst.

Validation

• pytest on this branch (on top of develop @ 5504b56):
  1457 passed / 124 skipped / 0 failed. The skips are optional-dependency
  (sparse-ir, cupy) and intentional non-active-axis mutation no-ops. The
  tracked tree stays clean after the test run.
• End-to-end seven-gate harness cross-checks the emitted wave function and
  trans.def against mVMC ComplexUHF (density, energy, topology gates):
  v3.7 four-fixture suite 28/28 PASS, v3.6 fixture PASS. Gate values match
  every previously recorded digit, re-run on this branch.

Notes for reviewers

• The branch is built directly on the current develop tip (5504b56),
  so the diff is the bridge alone: no upstream file is modified beyond the
  17 files listed below, and nothing is deleted.
• ~90% of the insertions are numerical validation fixtures under
  tests/validation/ (e.g. OneBodyG.dat) plus unit tests; the tool
  itself is tools/uhfk_to_mvmc.py + tools/_uhfk_to_mvmc/.
• Modified upstream files (17): .gitignore (adds bridge work-dir
  ignores), src/hwave/solver/uhfk.py (APBC phase handling via the new
  _apbc_phase helper, plus occupation / boundary-condition output and
  SOC-aware greenone export), 12 docs .rst pages (index wiring and
  cross-references), 2 UHFk tests extended for the new export/folding
  behavior, and 1 whitespace-only cleanup
  (tests/test_uhfk_green_deflate_subshape.py).

🤖 Generated with Claude Code and Codex (gpt-5.6-sol)