pytc.vmc.sampling.adaptive_burn_in

pytc.vmc.sampling.adaptive_burn_in(ref_det, full_ansatz, walkers, params, step_size=0.01, key=None, move_type='one', max_vmap_batch_size=0, mesh=None, chunk_size=500, max_steps=50000, acceptance_target=0.5, acceptance_tol=0.02, stability_window=3, energy_stability_atol=0.05, variance_stability_rtol=0.02)[source]

Burn in until the ensemble’s E_L/Var estimates stabilize, instead of a fixed step count (a count tuned for one system size under-provisions a larger one, since equilibration time grows with system size).

Runs in chunks of chunk_size sweeps; after each chunk:

  1. PRE-GATE on acceptance within acceptance_tol of acceptance_target. Acceptance reflects only step-size adaptation, not global |Psi|^2 mixing – a cheap pre-check, not the stopping decision.

  2. Once the pre-gate passes, compute batch-mean E_L and Var via full_ansatz (the physical trial wavefunction – NOT ref_det, which only defines the sampling distribution) over a sliding window of the last stability_window chunks. Terminate once E is within energy_stability_atol (absolute: E crosses zero during equilibration) and Var within variance_stability_rtol (relative: Var is strictly positive) across the window.

  3. Hard-capped at max_steps total sweeps.

If walkers came from mcmc_utils.resample_walkers, this function’s sweep counter is “sweeps since resample” by construction, so the stability window can’t read “stable” off still-correlated bootstrap duplicates.

Parameters:

  • ref_det – The determinant (or other) ansatz that defines the MCMC proposal/target distribution – same role as ansatz in burn_in.

  • full_ansatz – The physical trial wavefunction (e.g. SlaterJastrow) whose local_energy is the actual quantity of interest for the stability check.

  • walkers – Initial walker configurations.

  • params – Full [jastrow_params, linear_coeffs] for full_ansatz.

  • step_size – Initial MCMC proposal step size.

  • key – PRNG key.

  • move_type – forwarded to burn_in.

  • max_vmap_batch_size – forwarded to burn_in.

  • mesh – forwarded to burn_in.

  • chunk_size – Sweeps per chunk (one stability check per chunk, and one step-size adaptation per chunk using the chunk-MEAN acceptance – burn_in’s internal per-interval adaptation is disabled here so the two controllers don’t fight).

  • max_steps – Hard cap on total sweeps; the stability criterion, not the cap, should normally terminate.

  • acceptance_target – Pre-gate center, matching burn_in’s step-size adaptation target.

  • acceptance_tol – Pre-gate band around the target.

  • stability_window – Number of consecutive chunks required stable.

  • energy_stability_atol – Absolute energy tolerance (Ha) for the window range; scale with system size (equilibrium fluctuations grow with it).

  • variance_stability_rtol – Relative tolerance for Var’s window range, above the plateau noise floor and below the pre-plateau transition.

Returns:

Tuple of (equilibrated_walkers, chunk_history, new_key, step_size, total_steps_run). chunk_history is a list of per-chunk dicts with keys: steps_so_far, acceptance, mean_energy, variance (the latter two are None for chunks skipped by the acceptance pre-gate).