feat: StochasticWfn trial wavefunction

[beevus77]

Summary

Adds a first-class StochasticWfn trial to the overhaul tree: a NOMSD-based trial whose overlap and local energy are estimated from an auxiliary-field inner ensemble, with a closed inner_* input surface (illegal sampler combinations are unrepresentable; unknown keys abort).

This is the production surface that worked in the N₂ / Fe study work — not a grab-bag of experimental knobs.

Rough size vs current overhaul: ~57 files, +8.5k / −0.1k (mostly StochasticWfn.*, full_g_estimators.hpp, CUDA reduction kernels, and tests/test_stochastic_wfn.cpp).

What it adds

Trial + driver wiring

• StochasticWfn variant alternative, factory / HDF5 type detection (stochasticwfn / Wavefunction/StochasticWfn)
• Inner ensemble allocation; begin_inner_step; pop-control realignment via SLOT_LINEAGE + permute_inner_blocks_after_pop
• Persistent field chains in walker TRIAL_FIELDS; Propagate_conditioned / Propagate_free / Propagate_given_fields
• Estimators call measure_energy (replica-averaged when inner_n_measure_samples > 1)
• Full-G energy / vbias path (full_g_estimators.hpp) for CLOSED and COLLINEAR; device reduction kernels for GPU
• Optional separate variational Hamiltonian (inner_hamiltonian) for the inner propagator

Closed input surface (10 keys)

Schema-owned in WavefunctionParameters (unknown inner_* abort via the JSON schema):

key	role
inner_n_samples	ensemble size P
inner_nsteps	inner propagation length; 0 ⇒ static anchor
inner_sampling_target	static | gaussian | walker_overlap
inner_sample_update_steps	sweeps between measurements
inner_burn_in	chain burn-in (default 100)
inner_n_measure_samples	measurement replicas
inner_sampler / inner_sampler_step	field-space proposal (pcn / gaussian)
inner_seed	inner RNG
inner_propagator / inner_hamiltonian	optional blocks; timestep from HDF5 stamp when using inner_hamiltonian

inner_sampling_target: walker_overlap turns on conditioning, leapfrog reweight, and persistent chains together. Combinations that used to be expressible and wrong (e.g. leapfrog without persistence) are no longer representable.

inner_timestep travels with the variational operator: export stamps Hamiltonian/inner_timestep on ham_var.h5; the factory reads it; a missing stamp aborts; setting inner_propagator.timestep alongside inner_hamiltonian aborts (no silent 0.01 default).

Docs + tests

• Short features.rst entry (type, Dense Cholesky × CLOSED/COLLINEAR, unsupported list)
• CONTRIBUTING-style Doxygen on the stochastic public surface
• Full Catch suite in tests/test_stochastic_wfn.cpp (~20 cases): delegate-limit NOMSD parity, mean-field / BP, persistent pool + pop-control, measurement replicas, closed input surface — green on allocation (CPU + CUDA as validated on the fork)

Design choices worth calling out in review

1. inner_burn_in default 0 → 100 is not energy-neutral. N₂-equilibrium A/B (production settings → shipped defaults), 48 pairs: +4.327 ± 1.390 mHa (3.11 σ). Bundles burn-in with “measure always advances the pool”; both are deliberate. inner_burn_in: 0 remains legal.
2. Walker bookkeeping (SLOT_LINEAGE, TRIAL_FIELDS) lives in walker_buffer so branch / load-balance copy fields for free; both sit outside the walkerSizeIO() checkpoint window.
3. Polarized COLLINEAR (ndown == 0) — after upstream Replace FULLYPOLARIZED by COLLINEAR[ndown=0] #123, fully polarized systems are ordinary COLLINEAR with an empty beta block. Zero-extent beta ops trap on GPU (nda host→device assign / cuTENSOR) while host/tblis accepts them. This PR gates those paths (has_beta(), NOMSD::accumulate_estimators, walker resize, StochasticWfn overlap). The accumulate_estimators guard is an upstream hole too (their polarized consistency test covers Energy/MixedDM, not 1-body estimators); happy to peel it to a standalone overhaul PR if preferred.
4. Compile-time surface — hot StochasticWfn methods use concrete WalkerSet / array_view signatures and live in .cpp, matching overhaul Compile time optimization #126’s direction.
5. AFQMCInfo leftovers in five orphaned observable headers (atomcentered / generalizedFock / n2r / realspace / sk) take int NMO — finishes upstream The extrication of AFQMCInfo #118 for headers that are still commented out of the live Observable variant. Not required for StochasticWfn; included as hygiene.
6. afqmctools cmax: default 4 → 20 and hard-error if Cholesky exits on the vector cap before tol (silent truncation on large active spaces, e.g. Fe₂S₂). Python-only; orthogonal — happy to peel to a follow-up if preferred.

Known limits (intentional for this PR)

• Dense Cholesky + CLOSED / COLLINEAR only; NONCOLLINEAR full-G is a follow-up
• Multi-rank (-np > 1) consistency for the dynamic ensemble is deferred (including a known deno_real defect under multi-rank reduction)
• Full unit suite ships in one PR; happy to iterate on staging if review prefers parity-first

Out of scope / follow-ups

• NONCOLLINEAR full-G for dynamic StochasticWfn
• Multi-rank dynamic-ensemble gate (deno_real)
• Optional peel of mol.py cmax, orphaned-observable NMO ctors, and/or the NOMSD::accumulate_estimators empty-spin guard into standalone PRs
• Study-side export stamp backfill / decks still emitting pre-cleanup key names (abort by design on this binary)