@@ -638,10 +638,10 @@ The estimate result retains the legacy `energy_mean`, `energy_variance`, and
638638` energy_stderr ` field names; they contain statistics for the configured
639639observable. ` estimate_energy(...) ` remains as a compatibility alias.
640640
641- For a coordinate-labelled PEPS, use ` TorchFermionVMC ` to derive the lattice,
642- physical charge ordering, initial sector, and sampler rule in one place. Pass
643- ` fermion ` to generate the default Hamiltonian, or omit it when supplying
644- explicit ` terms ` :
641+ For compatibility with an existing lower-level sweep loop, coordinate-labelled
642+ PEPS can still initialize ` TorchFermionVMC ` in the constructor. New code
643+ should prefer the first-run recipe below instead. Pass ` fermion ` to generate
644+ the default Hamiltonian, or omit it when supplying explicit ` terms ` :
645645
646646``` python
647647from pepsy import Fermion
@@ -663,6 +663,109 @@ result = vmc.estimate_observable(
663663)
664664```
665665
666+ For a native fermionic PEPS measurement, construct ` TorchFermionVMC ` from the
667+ state and native Fermion terms only. The first ` sample ` (or ` warmup ` ) owns both
668+ the chain recipe and PEPS contraction recipe:
669+
670+ 1 . ` SamplingConfig ` owns the number of chains, retained samples, burn-in,
671+ thinning, and RNG seeds. In the native Torch sampler, ` burn_in ` counts
672+ discarded thinning intervals, so the ` Metropolis ` total is
673+ ` (burn_in + n_samples_per_chain) * thin ` batched sweeps; every batched
674+ sweep advances all chains once.
675+ 2 . ` contraction_opts ` is a single mapping with ` method ` , ` chi ` , ` cutoff ` , and
676+ any backend options such as ` mode ` . It is consumed when the first operation builds
677+ the amplitude model, then remains fixed with the Markov state.
678+ 3 . ` observables ` is a name-to-term mapping. ` measure(samples, observables=...) `
679+ uses one retained batch for every entry. Include ` "energy": terms `
680+ explicitly when the Hamiltonian should be visible in the measurement recipe.
681+
682+ ``` python
683+ sampling = pvmc.SamplingConfig(
684+ n_samples_per_chain = 256 ,
685+ n_chains = 32 ,
686+ burn_in = 64 ,
687+ thin = 2 ,
688+ seed = 7 ,
689+ )
690+ contraction_opts = {
691+ " method" " boundary"
692+ " chi" 32 ,
693+ " cutoff" 1e-10 ,
694+ " mode" " mps"
695+ }
696+
697+ vmc = pvmc.TorchFermionVMC(
698+ peps,
699+ fermion = fermion,
700+ terms = terms, # native Fermi-Hubbard terms; no JW conversion
701+ )
702+
703+ # Optional, non-MCMC warm-up: inspect one valid PEPS amplitude.
704+ warmup = vmc.warmup(
705+ sampling = sampling,
706+ contraction_opts = contraction_opts,
707+ )
708+
709+ # Phase 1: exactly one Metropolis pass. `samples` retains psi(x) for every x.
710+ samples = vmc.sample(sampling = sampling, progress = True )
711+
712+ # Phase 2: no new Metropolis work. Reuse this batch for energy, eta, density, ...
713+ estimates = vmc.measure(
714+ samples,
715+ observables = {" energy" " eta"
716+ progress = True ,
717+ )
718+ print (warmup.amplitude)
719+ print (estimates[" energy" " eta"
720+ ```
721+
722+ ` estimate_observables({...}, sampling=..., contraction_opts=...) ` provides the
723+ same one-batch behavior without retaining a separately named sample batch.
724+ ` run(...) ` is the one-command convenience form: warm up, sample once, then
725+ measure. ` measure_samples(...) ` remains the lower-level spelling of
726+ ` measure(samples, ...) ` . Native sample batches carry the PEPS parameter
727+ versions and contraction signature used to draw them, so ` measure ` rejects a
728+ batch after either changes; draw fresh samples after an optimization update.
729+ ` progress=True ` reports optional burn-in sweeps, MCMC
730+ sampling, then the shared connection-building, amplitude-contraction, and
731+ statistics phases. The ` Metropolis ` bar reports walkers (chains), retained
732+ samples per walker, burn-in/thinning, proposal, contraction method/` chi ` ,
733+ acceptance, and live boundary-environment cache reuse/build activity. Its
734+ ` phase ` is ` equilibrate ` while discarded intervals run, then ` retain i/n ` as
735+ each retained configuration per walker is recorded. The
736+ ` Evaluation ` bar reports the shared sample shape, observables, whether parent
737+ amplitudes were stored, connection count, and the diagonal/environment/direct
738+ target-amplitude split. The warm-up amplitude is a representative PEPS
739+ amplitude, not an energy estimate. The legacy constructor-level ` n_walkers ` ,
740+ ` contraction ` , ` chi ` , and ` cutoff ` options remain supported for existing
741+ scripts, but new measurement code should keep them in ` SamplingConfig ` and
742+ ` contraction_opts ` as above.
743+
744+ External MPS/BP/tree proposal sampling uses the same explicit two-stage
745+ shape, but has no Metropolis burn-in or thinning. Pass its independent count
746+ as ` n_samples ` , rather than a ` SamplingConfig ` :
747+
748+ ``` python
749+ importance_samples = vmc.sample(
750+ proposal = mps_sampler,
751+ n_samples = 512 ,
752+ fermion = proposal_fermion,
753+ one_d_to_two_d = mps_site_to_peps_coordinate,
754+ )
755+ importance_estimates = vmc.measure(
756+ importance_samples,
757+ observables = {" energy" " eta"
758+ )
759+ ```
760+
761+ ` importance_samples ` stores PEPS-code configurations, ` log q(x) ` , and target
762+ parent amplitudes. The later ` measure ` call automatically forms the
763+ self-normalized weights ` |psi(x)|**2 / q(x) ` once and shares the resulting
764+ target-amplitude work across every observable. Unlike a target-Metropolis
765+ batch, an external-proposal batch remains valid after a PEPS update: ` measure `
766+ refreshes its target amplitudes while retaining the fixed proposal density.
767+ ` measure_from_proposal(...) ` remains the one-call compatibility shortcut.
768+
666769By default, ` pbc=None ` reads the PEPS cyclic axes through Quimb's
667770` is_cyclic_x() ` and ` is_cyclic_y() ` metadata; pass ` pbc= ` or ` edges= ` to
668771override that inference. When explicit two-site ` terms ` are supplied, their
0 commit comments