Design, implement, review, or document Pepsy's native Symmray fermion model-facing API, including a unified spinless/spinful helper, local operators, observables, Hamiltonian terms, native gates, gate streams, charge handling, and compatibility aliases. Use when changing src/pepsy/tensors/symmetric.py or symm_fermions.py, fermionic SymmMPS/SymPEPS workflows, Fermi-Hubbard or spinless t-V examples, or tests/docs for these APIs.
Run, review, debug, benchmark, or extend pepsy.TreeOptimizer -- the rooted tree-tensor-network (TTN) gate-stream circuit simulator of Seitz et al. (Quantum 7, 964, 2023; arXiv:2206.01000). Use when the user asks to replay a circuit on a tree tensor network; build or score a TreeLayoutFinder / TreePlan (entanglement-adapted recursive spectral bisection); tune the exact 2q-gate threading + single canonical compression sweep; work on the sibling-leaf fast path, canonical single-/multi-site local_expectation (Steiner subtree), measure/reset, the BLAS thread cap, the canonical-centre tracker, the tid cache, convergence_sweep / bond_report diagnostics, or copy(); or asks why TTN truncation is more accurate than per-hop truncation, how the tree geodesic threading works, or how to add sampling / stream-wired control events. Not for MPS (pepsy.MpsOptimizer -> mps-optimizer skill), MERA (qmera-energy-optimizer), stabilizer TN (stabilizer-tensor-networks), or BP.
Learn and implement the Stabilizer Tensor Network (STN) universal quantum simulator from Masot-Llima & Garcia-Saez (PRL 133, 230601, 2024 / arXiv:2403.08724) inside pepsy. Use when the user asks to implement, prototype, port, study, or extend stabilizer tensor networks, the generalized tableau formalism, a stabilizer-basis MPS, nu/coefficient-state simulation, Clifford plus non-Clifford circuit simulation with an amplitude MPS, or stim-tableau plus quimb/pepsy-MPS hybrid simulation. Also use for questions about STN cooling, magic-state injection including deferred MAST projection, the STN update rules (Clifford, non-Clifford rotation, measurement), the stabilizer basis B(S,D), pseudo-stabilizer rank, or bond-dimension growth bounds from that paper.
Belief-propagation tensor-network contraction and its loop / cluster / partitioned corrections inside pepsy (the `pepsy.bp` subpackage). Use when the user asks to run, build, extend, wrap, or debug: 1-norm BP (`one_norm_bp`) or 2-norm BP for a quimb tensor network; the loop cluster expansion (`loop_cluster_expand`); the edge-resolved loop series (`loop_series_expand`); partitioned network expansion / PNE (`partitioned_expand`, explicit or higher-rank projectors, recursive schedules, open outputs); Appendix-C weight passing (`weight_pass`); disordered-memory / relay-BP convergence robustness (`relay_bp`, `RelayBPResult`); generalized belief propagation (GBP / region graphs, `RegionGraph`, `gen_region_counts`); message reuse / warm-starting; or questions about whether a loop correction needs BP to converge, the cluster-vs-series-vs-PNE distinction, the Midha–Zhang free-energy cluster expansion + Kotecký–Preiss error bound, stochastic (MCMC) loop corrections, or how pepsy BP feeds the tensy DEM decoder. Not for
Design, implement, review, or extend Pepsy MERA/qMERA energy optimization in src/pepsy/optimizers/mera, including QMeraGeometry, QMeraBuilder schedules, parameterized two-qubit gate registries, reverse-lightcone energy chunks, compiled JAX/Torch losses, Symmray-native fermion gates/terms, schematics, and MeraEnergyOptimizer APIs.
Run, review, debug, or extend pepsy.MpsOptimizer for MPS gate-stream replay, MPO/SVD/DMRG/swap compression, persistent graph layouts, canonical-center diagnostics, normalization, control events, and exact-mode transitions.
Run, debug, tune, extend, or validate SymDMRG2 — pepsy's symmetric (symmray block-sparse) two-site DMRG ground-state solver for MPS. Use when the user asks to find a ground state / run DMRG with a conserved symmetry (U1, U1U1, Z2) in pepsy; build a symmetric MPO via SymHamiltonian.to_mpo; pick or debug the initial state (product ramp vs random), bond-dimension schedule/ramp, or the mixer (density_matrix vs subspace); compare pepsy DMRG against TeNPy or exact diagonalization; run Fermi-Hubbard (U1U1), spinless Fermi-Hubbard / t-V (U1), Heisenberg (U1), or transverse-field Ising (Z2); diagnose non-monotonic energy vs chi, a stuck/locked DMRG, or a plateau above the reference; or add a new symmetric model. Also use for questions about SymDMRG2 conventions, snake 2D->1D mapping, fermionic MPO Jordan-Wigner signs, or the tenpy_vs_pepsy_dmrg benchmark workspace.