Improve Symmray MPS sampling strategy

.github/skills/pepsy-fermion-operators/SKILL.md

@@ -50,13 +50,20 @@ Keep one model-facing object responsible for:
 - matching `SymHamiltonian` construction for spinful Hubbard or spinless t-V;
 - occupation/charge helpers and model metadata.
 
-Prefer an explicit constructor such as:
+Prefer an explicit local-space constructor, with physical couplings supplied
+at the term, Hamiltonian, or gate-stream call site:
 
 ```python
-Fermion(spinful=False, symmetry="U1", t=1.0, V=0.5)
-Fermion(spinful=True, symmetry="U1U1", t=1.0, U=8.0)
+spinless = Fermion(spinful=False, symmetry="U1")
+spinful = Fermion(spinful=True, symmetry="U1U1")
+
+spinless.hamiltonian(edges, t=1.0, V=0.5)
+spinful.strang_gate_stream(edges, dt=0.01, t=1.0, U=8.0)
 ```
 
+`Fermion` must not store `t`, `U`, `V`, or `mu`. Reject a Hubbard `U` on a
+spinless object instead of silently dropping it.
+
 Do not hide the spinless/spinful choice behind a model-name string when a
 boolean or explicit local-space descriptor can make it clear. Model-name
 strings may remain accepted for compatibility and Hamiltonian dispatch.

.github/skills/pepsy-fermion-operators/references/design.md

@@ -6,24 +6,20 @@ Symmray implementation.
 
 ## Current Pepsy state
 
-Pepsy currently exposes `SpinfulFermion` from `pepsy` and `pepsy.tensors`. The
-implementation lives in `src/pepsy/tensors/symmetric.py`, is re-exported by
-`src/pepsy/tensors/symm_fermions.py`, and currently provides:
+Pepsy exposes the canonical `Fermion` helper from `pepsy` and `pepsy.tensors`.
+The implementation lives in `src/pepsy/tensors/symmetric.py`, is re-exported
+by `src/pepsy/tensors/symm_fermions.py`, and provides:
 
-- spinful `U1` and `U1U1` local spaces;
+- spinless `U1`/`Z2` and spinful `U1`/`Z2`/`U1U1`/`Z2Z2` local spaces;
 - dense local operators and aliases;
 - native Symmray one-site observables;
-- onsite interaction and two-site hopping gates;
-- deterministic second-order edge-colored gate streams;
-- `SymHamiltonian` construction for `fermi_hubbard` and
-  `fermi_hubbard_u1u1`;
-- `SpinfulFermionHubbard = SpinfulFermion` compatibility alias.
-
-Pepsy already supports spinless model metadata and Hamiltonian paths through
-`fermi_hubbard_spinless`, but the model-facing helper does not yet unify that
-space with the spinful helper. The intended evolution is a canonical
-`Fermion(spinful=...)` helper, retaining the existing spinful names as
-compatibility aliases.
+- onsite, hopping, density, field, and parity-preserving pairing gates;
+- deterministic first- and second-order edge-colored gate streams;
+- `SymHamiltonian` construction for spinful Hubbard and spinless t-V models.
+
+`SpinfulFermion` and `SpinfulFermionHubbard` are compatibility constructors:
+they deliberately fix `spinful=True`, while `SymmFermions.spinful(...)` and
+`SymmFermions.spinless(...)` provide corresponding factories.
 
 ## Symmray local conventions
 
@@ -68,15 +64,15 @@ Use one object with an explicit local-space switch. The exact name can change
 only with user direction; `Fermion` is the recommended canonical name.
 
 ```python
-spinless = Fermion(spinful=False, symmetry="U1", t=1.0, V=0.5, mu=0.0)
-spinful = Fermion(spinful=True, symmetry="U1U1", t=1.0, U=8.0, mu=0.0)
+spinless = Fermion(spinful=False, symmetry="U1")
+spinful = Fermion(spinful=True, symmetry="U1U1")
 
 spinless.dense_operator("number")
 spinful.observable("number_up")
-spinful.hopping_gate(dt=0.01)
-spinful.interaction_gate(dt=0.01, site=3)
-spinful.strang_gate_stream(edges, dt=0.01, sites=range(L))
-spinful.hamiltonian(edges)
+spinful.hopping_gate(dt=0.01, t=1.0)
+spinful.interaction_gate(dt=0.01, site=3, U=8.0)
+spinful.strang_gate_stream(edges, dt=0.01, sites=range(L), t=1.0, U=8.0)
+spinful.hamiltonian(edges, t=1.0, U=8.0, mu=0.0)
 ```
 
 Recommended metadata and methods:
@@ -96,7 +92,10 @@ Recommended metadata and methods:
 | `strang_gate_stream(...)` | create deterministic canonical bundled entries |
 
 The spinless parameter should use `V` for nearest-neighbor density interaction;
-do not silently interpret a spinless `U` as a doublon interaction. Spinless
+do not silently interpret a spinless `U` as a doublon interaction: the public
+methods reject it. `Fermion` stores only local-space and backend metadata;
+pass `t`, `U`, `V`, and `mu` to a term, Hamiltonian, or gate-stream call.
+Spinless
 pairing or superconducting terms should be added only with explicit symmetry
 and charge semantics, since they break particle-number conservation.
 
@@ -170,14 +169,16 @@ once. This is correct for native local-term measurements, but the one-site
 interaction is not a separate dictionary entry.
 
 For examples that prioritize visible bookkeeping, build hopping-only edge
-terms with `U=0` and `mu=0`, then add one-site native observables:
+terms with `U=0` and `mu=0`, then add one-site native observables. Keep the
+couplings as ordinary local variables rather than Fermion attributes:
 
 ```python
-hop = fermion.hamiltonian(edges, U=0.0, mu=0.0)
+U, mu = 8.0, 0.0
+hop = fermion.hamiltonian(edges, t=1.0, U=0.0, mu=0.0)
 energy_terms = dict(hop.terms)
 onsite = (
-    fermion.U * fermion.observable("double")
-    - fermion.mu * fermion.observable("number")
+    U * fermion.observable("double")
+    - mu * fermion.observable("number")
 )
 energy_terms.update({(site,): onsite for site in range(L)})
 ```

.github/skills/pepsy-vmc/SKILL.md

@@ -196,9 +196,13 @@ For sampled configurations `x`, evaluate
 
 `O_loc(x) = sum_{x'} O[x, x'] * psi(x') / psi(x)`.
 
-Average local estimators over the Markov-chain samples. The canonical sampled
-driver method is `estimate_observable(...)`; `estimate_energy(...)` remains a
-compatibility wrapper. Return complex means
+Average local estimators over the Markov-chain samples. The canonical native
+Torch workflow is `samples = vmc.sample(sampling=...)`, followed by
+`vmc.measure(samples, observables={...})`. One `measure` call shares stored
+parent amplitudes and connected-target contractions across every named
+observable. `run(observables=..., sampling=...)` is the convenience form that
+warms up, samples, and measures once; `estimate_observables(...)` and
+`estimate_energy(...)` remain compatibility wrappers. Return complex means
 when appropriate but report Hermitian observables using their real part only
 after checking the imaginary residual. Keep energy, diagonal observables,
 hopping, correlations, and arbitrary supported Fermion observables on the

.github/skills/qmera-energy-optimizer/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: qmera-energy-optimizer
-description: "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."
+description: "Design, implement, review, or extend Pepsy qMERA energy optimization in src/pepsy/optimizers/qmera, including QMeraGeometry, QMeraBuilder schedules, qMERA RG-layout search and scoring, parameterized gate registries, reverse-lightcone energy chunks, compiled JAX/Torch losses, Symmray-native fermion gates/terms, schematics, and QMeraEnergyOptimizer APIs."
 ---
 
 # qMERA Energy Optimizer in Pepsy
 
-Use this skill for qMERA/QMERA-B, dense MERA, and `MeraEnergyOptimizer` work in
-Pepsy. The current implementation is Pepsy-owned and schedule-first: Pepsy
+Use this skill for qMERA/QMERA-B work in Pepsy. The current implementation is
+Pepsy-owned and schedule-first: Pepsy
 defines geometry, RG blocking, gate placement, parameter dictionaries, local
 lightcone chunks, and optimizer shells; quimb/cotengra provide tensor-network
 storage and contraction.
@@ -15,8 +15,8 @@ storage and contraction.
 
 - Repository rules: `AGENTS.md`.
 - Design reference: [references/design.md](references/design.md).
-- Current source: `src/pepsy/optimizers/mera/`.
-- Focused tests: `tests/test_optimize_mera.py`.
+- Current source: `src/pepsy/optimizers/qmera/`.
+- Focused tests: `tests/test_optimize_qmera.py`.
 - Public exports: `src/pepsy/optimizers/__init__.py`,
   `src/pepsy/__init__.py`, `tests/test_public_api.py`, and
   `tests/test_package_layout.py`.
@@ -34,9 +34,6 @@ copied prototype scripts.
 
 ## Implementation Map
 
-- `optimizer.py`: dense/isometric `MeraEnergyOptimizer` over existing MERA-like
-  tensor networks, with local lightcone energy chunks and quimb `TNOptimizer`
-  integration.
 - `terms.py`: `LocalTerm` normalization and backend conversion for local
   Hamiltonian inputs.
 - `geometry.py`: `QMeraGeometry` with explicit lattice labels, boundary,
@@ -58,12 +55,19 @@ copied prototype scripts.
   `qmera_parametric_lightcone_tn(...)`, and
   `contract_qmera_lightcone_tn(...)` to rebuild and contract only the scheduled
   local cone for each Hamiltonian term.
-- `compiled.py`: `cotengra.array_contract_expression` wrappers for dense
-  qMERA local cones. These freeze contraction topology so Torch/JAX see a pure
-  array loss over parameter dictionaries.
-- `parametric.py`: `QMeraParametricEnergyOptimizer`, a
-  `GradientOptimizer`-based shell for parameter dictionaries, including
-  compiled-loss runs.
+- `compiled.py`: `cotengra.array_contract_expression` wrappers for dense and
+  native graded qMERA local cones. Native Symmray expressions keep their
+  product-state/operator constants as Symmray arrays and freeze only the
+  contraction topology, so Torch/JAX parameter dictionaries remain
+  differentiable without dropping charge or fermionic-order metadata.
+- `parametric.py`: `QMeraEnergyOptimizer`, a `GradientOptimizer`-based shell
+  for parameter dictionaries, including compiled-loss runs. The old
+  `QMeraParametricEnergyOptimizer` name remains only as a compatibility alias.
+- `layout.py`: `QMeraLayoutFinder` and immutable candidate/score/report objects
+  for structural pre-ranking of RG architectures.
+- `prototype.py`: a loader and stream-level scorer for serialized
+  `~/mera/U_q3_l*` placement streams; prototype streams remain diagnostics,
+  not Pepsy schedules.
 - `fermions.py`: Symmray-native fermion helpers, including
   `QMeraSymmrayFermionBackend`, `qmera_symmray_fermi_hubbard_terms(...)`, and
   `symmray_fermion_gate_registry(...)`.
@@ -94,9 +98,9 @@ copied prototype scripts.
   only backend-native arrays in the parameter dictionary.
 - Use Pepsy backend helpers and autoray-compatible arrays. Do not introduce a
   qMERA-specific backend abstraction.
-- Keep dense MERA projection and explicit qMERA circuit unitarity separate.
-  Dense MERA uses isometric tensor projection; qMERA uses unitary or
-  symmetry-preserving gate families.
+- Keep qMERA gate unitarity and symmetry in the gate families. Do not add a
+  separate dense tensor projection or normalization path to the qMERA
+  optimizer.
 - Keep optional dependencies optional. Symmray-specific tests must use
   `pytest.importorskip("symmray")`.
 
@@ -113,34 +117,110 @@ copied prototype scripts.
   neighbors should be adjacent in the active register.
 - Use `QMeraSymmrayFermionBackend.product_state(...)` through the builder's
   `product_state_factory` when contracting native Symmray lightcones.
-- The compiled dense path in `compiled.py` is not automatically a Symmray
-  compiled path. Keep native Symmray contractions explicit until a tested
-  compiled graded-array route exists.
-- Two-dimensional multi-mode schedules are intentionally guarded until the RG
-  design is explicit; do not silently flatten this case as if it were a normal
-  spin schedule.
-
-## Next Useful Work
-
-- Add user-facing docs/examples for `QMeraBuilder`, schematics, parametric
-  lightcone losses, compiled JAX/Torch loss usage, and Symmray-native
-  Fermi-Hubbard terms.
-- Add local-cone grouping or reusable path-cache helpers around cotengra once
-  one-term-per-chunk correctness remains stable.
-- Extend tests that compare direct full-qMERA TN energy to schedule-only
-  lightcone energy for more schedules and boundary conditions.
-- Design the explicit 2D multi-mode/Fermi-Hubbard RG blocking before enabling
-  it in `build_qmera_schedule(...)`.
-- Decide whether any qMERA symbols should become top-level `pepsy.*` exports;
-  if yes, update docs and public API tests in the same patch.
+- Native Symmray compilation is supported when the builder receives a graded
+  `product_state_factory`, normally
+  `QMeraSymmrayFermionBackend.product_state`. The compiler must use Symmray's
+  autoray dispatch for pairwise contractions; never densify the frozen
+  constants or runtime gate blocks. `QMeraCompiledLightconeChunk.is_graded`,
+  `.symmetry`, and `.contraction_backend` expose this choice.
+- Two-dimensional multi-mode schedules are supported when geometry and block
+  shapes are explicit. Preserve mode labels and same-flavor pairing; true
+  rectangular isometries remain unsupported and must not be mislabeled as
+  unitary completions.
+
+## Remaining Work
+
+- Add optional actual cotengra FLOP/peak-memory estimates to layout search
+  after its cheap structural pre-ranking, reusing the path cache.
+- Extend compiled graded-array coverage to larger later-scale schedules and
+  optional device-specific benchmarks while retaining direct native cones as
+  the correctness oracle.
+- Extend the prototype adapter with level-to-scale inference only when the
+  serialized stream format is formally specified; do not infer RG semantics
+  from a flat placement list by guesswork.
+- Add broader later-scale direct-versus-lightcone comparisons and validate any
+  future true-isometry implementation separately from unitary completion.
+
+## qMERA RG Layout Finder
+
+The layout finder searches immutable RG architecture candidates and
+return a reproducible `scales` plan that can be passed directly to
+`QMeraBuilder`. It should not replace the schedule-first energy path or mutate
+the builder while searching.
+
+The public objects are `QMeraLayoutCandidate`, `QMeraLayoutScore`,
+`QMeraLayoutReport`, and `QMeraLayoutFinder`. A candidate records, for
+every RG scale:
+
+- isometry block shape and orientation;
+- disentangler placement (`boundary-faces`, `boundary-square`, or
+  `within-block`), corner policy, periodic wrapping, and executable rounds;
+- internal circuit depths, gate families, and parameter-sharing policy;
+- the resulting `QMeraScaleSpec` values and a stable candidate id.
+
+Candidate generation must validate the existing qMERA invariants before
+scoring:
+
+- isometry blocks form a non-overlapping covering partition;
+- concurrent disentangler supports are disjoint, while sequential circuit
+  rounds may reuse a block support;
+- boundary disentanglers connect neighboring isometry regions and cover the
+  relevant interaction boundaries;
+- reverse lightcones are finite, reproducible, and compatible with periodic
+  geometry, explicit modes, and the selected fermion symmetry;
+- native Symmray candidates preserve mode labels, charge maps, and graded
+  contraction semantics without adding Jordan-Wigner strings.
+
+The score must expose components rather than hiding all decisions in one
+opaque number. The initial components should include:
+
+- structural cost: gate count, circuit depth, number of placements, and
+  maximum/mean local-cone width;
+- contraction cost: cotengra estimated FLOPs, peak intermediate size, and
+  path-search cost for representative local-cone topologies;
+- interaction coverage: weighted coverage of Hamiltonian supports and
+  important interaction boundaries by the candidate's blocks and
+  disentanglers;
+- optional entanglement coverage: weighted coverage of a user-supplied
+  mutual-information, entropy, correlation, or covariance map.
+
+Without state-derived data, report interaction coverage as a Hamiltonian proxy;
+do not call it measured physical entanglement. For expensive searches, use a
+cheap structural pre-ranking followed by actual cotengra path estimates for
+the top candidates, reusing `QMeraContractionPathCache`. Return both a scalar
+weighted score and a Pareto front so users can inspect cost-versus-coverage
+tradeoffs.
+
+The intended workflow is:
+
+1. generate and structurally validate candidate scale plans;
+2. pre-rank candidates using cone width, gate count, depth, and interaction
+   coverage;
+3. evaluate cached contraction estimates for the top candidates;
+4. optionally run a short pilot optimization and rescore with measured
+   entanglement coverage;
+5. return the best plan, Pareto candidates, component scores, and schematic
+metadata without silently changing mode order or fermion conventions.
+
+For comparison with the research prototype, call
+`load_qmera_prototype_layout(...)` and
+`finder.score_prototype_layout(...)`. That path reports flat-stream gate
+count/depth and support coverage separately; it never converts `U_q3_l*`
+into a `QMeraScaleSpec` without an explicit RG mapping.
+
+The finder should integrate with `QMeraBuilder`, `QMeraSchedule`, and
+`draw_schematic` so a selected architecture can be inspected at every
+`rg_step`. Add focused tests for candidate validity, deterministic ranking,
+bounded lightcones, contraction-cost reporting, OBC/PBC layouts, and native
+Fermi-Hubbard mode/symmetry preservation before exposing top-level exports.
 
 ## Validation
 
 Run focused validation after qMERA edits:
 
 ```bash
 env NUMBA_CACHE_DIR=/tmp/numba_cache MPLCONFIGDIR=/tmp/mplconfig PYTHONPYCACHEPREFIX=/tmp \
-  /home/reza.haghshenas@quantinuum.com/envs/py312/bin/python -m pytest -q tests/test_optimize_mera.py
+  /home/reza.haghshenas@quantinuum.com/envs/py312/bin/python -m pytest -q tests/test_optimize_qmera.py
 ```
 
 For API/export changes, also run:
@@ -153,5 +233,11 @@ env NUMBA_CACHE_DIR=/tmp/numba_cache MPLCONFIGDIR=/tmp/mplconfig PYTHONPYCACHEPR
 For syntax-only checks:
 
 ```bash
-/home/reza.haghshenas@quantinuum.com/envs/py312/bin/python -m pyflakes src/pepsy/optimizers/mera tests/test_optimize_mera.py
+/home/reza.haghshenas@quantinuum.com/envs/py312/bin/python -m pyflakes src/pepsy/optimizers/qmera tests/test_optimize_qmera.py
 ```
+
+The focused suite also covers independent 2D PBC Jordan-Wigner Fock-space
+checks for every native Hubbard term, compiled native Symmray Hubbard
+lightcones and Torch gradients, prototype-stream loading/scoring,
+and canonical `pepsy.optimizers.qmera` imports with the temporary `mera`
+compatibility alias.

.github/skills/qmera-energy-optimizer/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "qMERA Energy Optimizer"
-  short_description: "Design and extend Pepsy qMERA/MERA optimization."
+  short_description: "Design and extend Pepsy qMERA optimization."
   default_prompt: "Use $qmera-energy-optimizer to design or extend Pepsy qMERA energy optimization from the current schedule-first implementation."