Initial HamiltonZero release

.gitattributes

@@ -0,0 +1,38 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text
+datasets/train/*.jsonl filter=lfs diff=lfs merge=lfs -text
+datasets/eval/*.json filter=lfs diff=lfs merge=lfs -text
+weights/*.eqx filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+build/
+dist/
+outputs/
+weights/
+*.eqx
+*.hzc
+*.zst
+!weights/
+!weights/hamiltonzero_v1.eqx

LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

NOTICE

@@ -0,0 +1,5 @@
+HamiltonZero
+Copyright 2026 Simulacra Research Inc.
+
+This product includes third-party software. See THIRD_PARTY_NOTICES.md for
+attribution and license information.

README.md

@@ -0,0 +1,304 @@
+---
+license: apache-2.0
+---
+
+# HamiltonZero
+
+HamiltonZero is Simulacra Research's research release for compiled neural
+wavefunctions of quantum spin Hamiltonians. It exposes three workflows:
+
+- learned-router multisystem training;
+- compiled single-system fine-tuning;
+- compiled single-system evaluation, with optional router contest or large-N
+  execution.
+
+## Installation
+
+HamiltonZero requires Python 3.12 and JAX-compatible accelerator drivers.
+
+```bash
+python -m pip install .
+```
+
+The package pins the Python `jax` package to a
+[`TakeOver/jax` commit](https://github.com/TakeOver/jax/commit/79f82535b15a444516d4a5e2beb71d283665b2ff),
+also published as `hamiltonzero-jax-v0.11.0-spin.1`, and pins
+`jaxlib==0.11.0`. The fork contains the symbolic-zero JVP support used by the
+tuned Pallas attention kernel; stock Python JAX 0.11.0 is not sufficient for
+that pathway. Install the accelerator plugin appropriate for the host using
+the standard JAX instructions.
+
+Learned-router training uses eight visible accelerators and requires an MCMC
+batch size divisible by eight. Fine-tuning uses all visible accelerators and
+requires its MCMC batch size to be divisible by their count. Evaluation chooses
+a visible-device subset compatible with its walker batch.
+
+## Foundation checkpoint
+
+This Hugging Face repository stores the directly loadable HamiltonZero v1
+foundation checkpoint at `weights/hamiltonzero_v1.eqx`. To download the
+checkpoint without cloning the repository:
+
+```bash
+hf download simulacra-research/HamiltonZero \
+  weights/hamiltonzero_v1.eqx \
+  --local-dir .
+```
+
+The checkpoint contains the complete foundation wavefunction and its learned
+router. `router` is the checkpoint kind, not a router-only parameter file.
+
+To load the model directly, construct an architecture template and deserialize
+its array leaves:
+
+```python
+import jax
+
+from hamiltonzero.checkpoint import load_model
+from hamiltonzero.config import ModelConfig
+from hamiltonzero.model import build_model
+
+template = build_model(
+    ModelConfig(),
+    jax.random.PRNGKey(0),
+    n_max=64,
+)
+model = load_model("weights/hamiltonzero_v1.eqx", template)
+```
+
+The template key initializes placeholder values only; deserialization replaces
+all serialized array leaves. Set `n_max` to the padded width of the system when
+constructing a template for direct model use. The command-line evaluation path
+does this from the input system automatically.
+
+## Hamiltonians and NetworkX
+
+The public API follows the textbook convention
+
+\[
+H = \sum_{i<j} S_i^T J_{ij} S_j + \sum_i h_i^T S_i,
+\qquad S=\sigma/2.
+\]
+
+Construct and save a system from a simple undirected NetworkX graph:
+
+```python
+from pathlib import Path
+
+import networkx as nx
+
+from hamiltonzero import SpinHamiltonian
+from hamiltonzero.data import save_system
+
+graph = nx.path_graph(8)
+nx.set_edge_attributes(graph, 1.0, "J")
+nx.set_node_attributes(graph, 0.0, "h")
+
+system = SpinHamiltonian.from_networkx(graph)
+save_system(Path("outputs/systems/chain_8.json"), system)
+```
+
+The same example is runnable as `python examples/networkx_system.py`. An edge
+`J` may be an isotropic scalar, a length-three diagonal, or a 3-by-3 exchange
+matrix. A node `h` may be a scalar z-field or a length-three field vector.
+`SpinHamiltonian.from_arrays` accepts dense arrays instead.
+
+HamiltonZero converts public inputs to the model's internal `-J/2` and `-h`
+representation. The `SpinHamiltonian.J` and `SpinHamiltonian.h` properties
+return the public textbook values. If `mu` is omitted, a conservative value is
+computed from the Hamiltonian.
+
+## Standalone compiled inference
+
+The compact inference API loads the foundation checkpoint, runs the
+beam-8 router, permutes the Hamiltonian, and compiles the selected physical
+wavefunction in one call:
+
+```python
+import jax
+import networkx as nx
+
+from hamiltonzero import SpinHamiltonian, burn_in, energy, prepare, spin, step
+
+graph = nx.path_graph(8)
+nx.set_edge_attributes(graph, 1.0, "J")
+system = SpinHamiltonian.from_networkx(graph)
+
+route_key, mcmc_key = jax.random.split(jax.random.PRNGKey(0))
+compiled, order = prepare(
+    system,
+    "weights/hamiltonzero_v1.eqx",
+    route_key,
+)
+state, q = burn_in(
+    compiled,
+    mcmc_key,
+    batch_size=256,
+    replicas=8,
+    burn_in=1024,
+    walker_chunk_size=16,
+)
+local_energy = energy(compiled, q)
+local_spin = spin(compiled, q)
+state, q = step(compiled, state, steps=24, walker_chunk_size=16)
+```
+
+`state` is the complete replica-exchange MCMC state and `q` is its cold-chain
+population. `energy` returns named `total`, `exchange`, `casimir`, and `field`
+local-energy samples. `spin` returns the complex local spin estimator in the
+routed `(site, x/y/z)` order; contracting it with the routed public field
+reproduces the energy field channel. The selected padded-site permutation is
+returned as `order`. `order.leaf_to_input[leaf]` is the public input-site index
+assigned to a compiled tree leaf; `order.input_to_leaf[site]` is its inverse.
+The first mapping is also available as `compiled.route`. The public NetworkX
+path starts in exactly the supplied `system.nodes` order, applies this route
+once to the context and walkers, and then compiles an identity-routed tree.
+There is no additional bit reversal: applying one would corrupt the mapping.
+Both arrays include padded virtual leaves when the model width exceeds the
+physical site count. A complete runnable version that prints sample means and
+standard deviations is in
+[`examples/compiled_inference.py`](examples/compiled_inference.py).
+[`examples/j1j2_4x4_route.ipynb`](examples/j1j2_4x4_route.ipynb) constructs a
+periodic 4-by-4 J1-J2 model from NetworkX and visualizes the returned order as
+the successive cells of the compiled binary merge tree. Install its plotting
+dependencies with `python -m pip install '.[notebooks]'`.
+
+For a normalized pure state, the full-state `Tr(|psi><psi|)` is exactly one.
+The nontrivial purity observable is the subsystem second Renyi value
+`Tr(rho_A^2)`. It uses two independent computational-basis chains and a
+two-replica SWAP estimator:
+
+```python
+import jax
+
+from hamiltonzero import burn_in_basis, measure_renyi2
+
+x_key, y_key = jax.random.split(jax.random.PRNGKey(1))
+x_state, x = burn_in_basis(compiled, x_key, batch_size=256, burn_in=1024)
+y_state, y = burn_in_basis(compiled, y_key, batch_size=256, burn_in=1024)
+x_state, y_state, result = measure_renyi2(
+    compiled,
+    x_state,
+    y_state,
+    subsystem=range(4),
+    blocks=16,
+    steps_between=24,
+)
+print(result.purity, result.standard_error, result.renyi2_nats)
+print(result.resolved, result.failure_reasons)
+```
+
+`subsystem` accepts public site indices or a boolean mask. The result also
+retains each SWAP sample in stable log-polar form. Entropy is reported only
+when the block-count, effective-sample-size, autocorrelation,
+heavy-tail, imaginary-null, and physical-bound checks resolve the estimate;
+otherwise `renyi2_nats` is `None` and `failure_reasons` says why.
+`burn_in_basis` samples the computational basis required by this estimator.
+The SU(2)-quaternion walkers returned by `burn_in` cannot be substituted for
+those samples.
+
+## Datasets
+
+The repository includes the exact 5,000-system foundation training panel and
+the evaluation systems with at least 256 physical spins. Every file uses the
+public textbook units above.
+
+- `datasets/train/foundation_5000.jsonl` contains systems from 2 through 64
+  spins, fixed WL1/FWL2 dispatch, and available exact-diagonalization energies.
+- `datasets/eval/` contains the PPP-Ohno, RUDY, square-lattice J1-J2, and
+  triangular-Heisenberg evaluation systems from 256 through 8,100 physical
+  spins.
+
+Large-N files store physical sites only; the loader reconstructs power-of-two
+padding in memory. See [`datasets/README.md`](datasets/README.md) for the full
+inventory and sparse exchange encoding.
+
+## Train
+
+The training command starts a new learned-router multisystem run and writes one
+final full foundation-model checkpoint, including its learned router, plus a
+metadata sidecar:
+
+```bash
+hamiltonzero train examples/train.json
+```
+
+The example uses `datasets/train/foundation_5000.jsonl`, writes
+`outputs/foundation.eqx`, and exposes model, MCMC, KFAC, router, and energy
+parameters through JSON. The command writes the trained model at the end of
+the run.
+
+To skip burn-in using compatible post-burn-in sampler states:
+
+```bash
+hamiltonzero train examples/train.json --reuse-mcmc path/to/mcmc-states
+```
+
+For multisystem training, the path is a directory containing
+`<system-index>.eqx` files. For a one-system training panel it may be a single
+file.
+
+## Fine-tune
+
+Fine-tuning selects and freezes a route from a router checkpoint, compiles the
+single-system wavefunction, and optimizes that compiled model:
+
+```bash
+hamiltonzero finetune examples/finetune.json
+```
+
+The example fine-tunes on the 256-spin PPP-Ohno system and writes
+`outputs/ppp_ohno_n256.eqx`. A neighboring `.eqx.json` sidecar records the
+compiled-fine-tune kind, frozen model width, and configured ranks. A compatible
+single post-burn-in state can also be supplied:
+
+```bash
+hamiltonzero finetune examples/finetune.json --reuse-mcmc path/to/state.eqx
+```
+
+## Evaluate
+
+Compiled evaluation uses the route selected by a router checkpoint, or the
+embedded frozen route in a compiled fine-tune checkpoint:
+
+```bash
+hamiltonzero eval examples/eval.json
+```
+
+Use router contest to compare candidate routes before evaluating the winner:
+
+```bash
+hamiltonzero eval examples/eval.json --contest
+```
+
+Use the sequence-sharded large-N implementation for the large systems:
+
+```bash
+hamiltonzero eval examples/eval_large_n.json --large-n
+```
+
+Each evaluation writes `eval.json` and `eval.metrics.jsonl` inside its
+configured output directory.
+
+Training and fine-tuning metrics are written beside the final checkpoint as
+`<checkpoint>.metrics.jsonl`. Evaluation writes the same per-measurement fields
+to `eval.metrics.jsonl`. These JSONL rows contain step, energy, energy standard
+deviation, step wall time, and total wall time. Final `eval.json` additionally
+reports exchange/field channels and lag-one autocorrelation when available.
+
+## Configuration
+
+Every command accepts one JSON configuration. The files in `examples/` are
+minimal runnable configurations; omitted parameters use the defaults in
+`hamiltonzero.config`.
+
+The KFAC-JAX fork is vendored under `src/kfac_jax`.
+
+## License
+
+HamiltonZero first-party source, datasets, and released model weights are
+licensed under Apache-2.0, copyright Simulacra Research Inc. The vendored
+KFAC-JAX fork and JAX-derived large-N attention kernel remain under
+Apache-2.0. The Microsoft-Folx-derived attention forward and reverse-mode
+kernels remain under MIT. See
+[`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).

THIRD_PARTY_NOTICES.md

@@ -0,0 +1,13 @@
+# Third-party notices
+
+The KFAC-JAX fork under `src/kfac_jax`, including modifications copyright
+2026 Simulacra Research Inc., is licensed under Apache-2.0. Its license is in
+`third_party/kfac_jax/LICENSE`.
+
+The attention forward and reverse-mode kernels derived from Microsoft Folx,
+with modifications copyright 2026 Simulacra Research Inc., are licensed
+under MIT. Its license is in `third_party/folx/LICENSE`.
+
+The large-N Pallas attention kernel derived from JAX, with modifications
+copyright 2026 Simulacra Research Inc., is licensed under Apache-2.0. Its
+license is in `third_party/jax/LICENSE`.

datasets/README.md

@@ -0,0 +1,38 @@
+# Datasets
+
+All files use the public textbook convention
+
+\[
+H=\sum_{i<j}S_i^T J_{ij}S_j+\sum_i h_i^T S_i,\qquad S=\sigma/2.
+\]
+
+Sparse exchange terms are encoded as `[i, j, J]`, where `J` is a scalar,
+a length-three diagonal, or a 3-by-3 matrix. Missing fields are zero.
+HamiltonZero expands this representation when loading a system.
+
+`train/foundation_5000.jsonl` contains the 5,000 systems used by the released
+foundation checkpoint, with sizes from 2 to 64 spins. Each row includes the
+fixed WL1/FWL2 dispatch and, where available, `e_ed` in textbook energy units.
+There are 3,169 non-null exact-diagonalization references.
+
+The N≥256 evaluation systems are:
+
+| File | Physical spins | Family |
+|---|---:|---|
+| `eval/ppp_ohno_n256.json` | 256 | PPP–Ohno C128H130 |
+| `eval/ppp_ohno_n512.json` | 512 | PPP–Ohno C256H258 |
+| `eval/ppp_ohno_n1024.json` | 1,024 | PPP–Ohno C512H514 |
+| `eval/rudy_n256.json` | 256 | RUDY-12 MaxCut |
+| `eval/rudy_n512.json` | 512 | RUDY-12 MaxCut |
+| `eval/rudy_n1024.json` | 1,024 | RUDY-12 MaxCut |
+| `eval/j1j2_45x45_obc.json` | 2,025 | square-lattice J1–J2 |
+| `eval/triangular_42x42_pbc.json` | 1,764 | triangular Heisenberg |
+| `eval/j1j2_64x64_obc.json` | 4,096 | square-lattice J1–J2 |
+| `eval/j1j2_90x90_obc.json` | 8,100 | square-lattice J1–J2 |
+
+Each evaluation record stores its fixed WL1 routing dispatch.
+
+All stored couplings and reference energies use the textbook convention above.
+Padding is reconstructed in memory and is not stored as zero-valued sites.
+
+These datasets are distributed under the repository Apache-2.0 license.

datasets/eval/j1j2_45x45_obc.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:524a4ab53dea1f05fab99b827f4e8aec8d991ac160c58a59b10d07a094ec2730
+size 117093

datasets/eval/j1j2_64x64_obc.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b5177badfdd22af24182fc3a8ff358c4639457f0e6ed4bc2c332e818adb602f6
+size 247879

datasets/eval/j1j2_90x90_obc.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:33ea4692401413b9afbf8caf5a02efceae1f2a9e16d3d38df4137d0913cf9315
+size 501771

datasets/eval/ppp_ohno_n1024.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3c5934d263227de2520b7fe9843de59aa493528f4666c2bf996eb97d39743e9f
+size 21848168

datasets/eval/ppp_ohno_n256.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:07e3dc5b262c7429bfa8cc7d08d561d7aa32a6031a8b68b5944fda84a124362e
+size 1322178

datasets/eval/ppp_ohno_n512.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c346bbf5ed672d18a782f6cc2753416f10a141fbf5bb38d0977c67bca818d2e9
+size 5385846

datasets/eval/rudy_n1024.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5bff99762c67a1ffda145f96da213475ae3f8280ae89d5b2022ed86a34182918
+size 1623829

datasets/eval/rudy_n256.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6dae5999b8f02b7e513c581cec5469549606bc3cfee95dce732ab7c06d33d9a7
+size 98782

datasets/eval/rudy_n512.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0416837f2d2bcb7421b2c8f483bcf9413365cc0f0c27c6d5c11288bad656b2ad
+size 401666

datasets/eval/triangular_42x42_pbc.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:347f7dc3d215ef5c6f422aafb3bfe1dac7a5c9c01b954903ad6b7bcfecad85be
+size 78234

datasets/train/foundation_5000.jsonl

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ba07575057cc04fe69edebbf1c2083a25e6920991e6e7c606bbc994200744e48
+size 17788002

examples/compiled_inference.py

@@ -0,0 +1,71 @@
+# Copyright (c) 2026 Simulacra Research Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+from pathlib import Path
+
+import jax
+import jax.numpy as jnp
+import networkx as nx
+import numpy as np
+
+from hamiltonzero import (
+    SpinHamiltonian,
+    burn_in,
+    burn_in_basis,
+    energy,
+    measure_renyi2,
+    prepare,
+    spin,
+    step,
+    step_basis,
+)
+
+
+graph = nx.path_graph(8)
+nx.set_edge_attributes(graph, 1.0, "J")
+system = SpinHamiltonian.from_networkx(graph)
+
+route_key, mcmc_key, basis_x_key, basis_y_key = jax.random.split(
+    jax.random.PRNGKey(0), 4
+)
+compiled, order = prepare(
+    system,
+    Path("weights/hamiltonzero_v1.eqx"),
+    route_key,
+)
+state, q = burn_in(
+    compiled,
+    mcmc_key,
+    batch_size=256,
+    replicas=8,
+    burn_in=1024,
+    walker_chunk_size=16,
+)
+
+local_energy = energy(compiled, q)
+local_spin = spin(compiled, q)
+print("leaf_to_input", np.asarray(order.leaf_to_input))
+print("input_to_leaf", np.asarray(order.input_to_leaf))
+print("energy", float(jnp.mean(local_energy.total.real)))
+print("energy_std", float(jnp.std(local_energy.total.real)))
+print("spin", np.asarray(jnp.mean(local_spin.real, axis=0)))
+
+state, q = step(compiled, state, steps=24, walker_chunk_size=16)
+
+basis_x, bits_x = burn_in_basis(compiled, basis_x_key, batch_size=256, burn_in=1024)
+basis_y, bits_y = burn_in_basis(compiled, basis_y_key, batch_size=256, burn_in=1024)
+basis_x, bits_x = step_basis(compiled, basis_x, steps=24)
+basis_y, bits_y = step_basis(compiled, basis_y, steps=24)
+basis_x, basis_y, purity = measure_renyi2(
+    compiled,
+    basis_x,
+    basis_y,
+    subsystem=range(4),
+    blocks=16,
+    samples_per_block=1,
+    steps_between=24,
+)
+print("purity", purity.purity)
+print("purity_standard_error", purity.standard_error)
+print("purity_resolved", purity.resolved, purity.failure_reasons)
+print("renyi2_nats", purity.renyi2_nats)

examples/eval.json

@@ -0,0 +1,5 @@
+{
+  "system": "datasets/eval/ppp_ohno_n256.json",
+  "checkpoint": "weights/hamiltonzero_v1.eqx",
+  "output": "outputs/ppp_ohno_n256_eval"
+}

examples/eval_large_n.json

@@ -0,0 +1,5 @@
+{
+  "system": "datasets/eval/j1j2_45x45_obc.json",
+  "checkpoint": "weights/hamiltonzero_v1.eqx",
+  "output": "outputs/j1j2_45x45_eval"
+}

examples/finetune.json

@@ -0,0 +1,6 @@
+{
+  "system": "datasets/eval/ppp_ohno_n256.json",
+  "checkpoint": "weights/hamiltonzero_v1.eqx",
+  "output": "outputs/ppp_ohno_n256.eqx",
+  "steps": 1000
+}

examples/j1j2_4x4_route.ipynb

@@ -0,0 +1,205 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "license",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Copyright (c) 2026 Simulacra Research Inc.\n",
+    "# SPDX-License-Identifier: Apache-2.0"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "title",
+   "metadata": {},
+   "source": [
+    "# Learned merge-tree order for a 4×4 J1–J2 torus\n",
+    "\n",
+    "The public Hamiltonian is built in textbook units. `prepare` loads HamiltonZero v1, selects the beam-8 route, compiles the wavefunction, and returns both directions of the mapping between public input sites and binary-tree leaves."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "imports",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pathlib import Path\n",
+    "\n",
+    "import jax\n",
+    "import matplotlib.pyplot as plt\n",
+    "from matplotlib.colors import ListedColormap\n",
+    "import networkx as nx\n",
+    "import numpy as np\n",
+    "\n",
+    "from hamiltonzero import SpinHamiltonian, prepare"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "hamiltonian",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "L = 4\n",
+    "J1 = 1.0\n",
+    "J2 = 0.3\n",
+    "nodes = tuple((row, column) for row in range(L) for column in range(L))\n",
+    "graph = nx.Graph()\n",
+    "graph.add_nodes_from(nodes)\n",
+    "for row, column in nodes:\n",
+    "    graph.add_edge((row, column), (row, (column + 1) % L), J=J1)\n",
+    "    graph.add_edge((row, column), ((row + 1) % L, column), J=J1)\n",
+    "    graph.add_edge((row, column), ((row + 1) % L, (column + 1) % L), J=J2)\n",
+    "    graph.add_edge((row, column), ((row + 1) % L, (column - 1) % L), J=J2)\n",
+    "graph.graph[\"needs_fwl2\"] = False\n",
+    "system = SpinHamiltonian.from_networkx(graph, nodes=nodes)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "prepare",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "leaf  input  lattice site\n",
+      "   0      0  (0, 0)\n",
+      "   1      1  (0, 1)\n",
+      "   2      2  (0, 2)\n",
+      "   3      3  (0, 3)\n",
+      "   4      7  (1, 3)\n",
+      "   5      6  (1, 2)\n",
+      "   6      5  (1, 1)\n",
+      "   7      4  (1, 0)\n",
+      "   8      8  (2, 0)\n",
+      "   9      9  (2, 1)\n",
+      "  10     10  (2, 2)\n",
+      "  11     11  (2, 3)\n",
+      "  12     15  (3, 3)\n",
+      "  13     14  (3, 2)\n",
+      "  14     13  (3, 1)\n",
+      "  15     12  (3, 0)\n"
+     ]
+    }
+   ],
+   "source": [
+    "route_key = jax.random.PRNGKey(0)\n",
+    "compiled, order = prepare(\n",
+    "    system,\n",
+    "    Path(\"weights/hamiltonzero_v1.eqx\"),\n",
+    "    route_key,\n",
+    ")\n",
+    "leaf_to_input = np.asarray(order.leaf_to_input, dtype=np.int32)\n",
+    "input_to_leaf = np.asarray(order.input_to_leaf, dtype=np.int32)\n",
+    "print(\"leaf  input  lattice site\")\n",
+    "for leaf, site in enumerate(leaf_to_input):\n",
+    "    print(f\"{leaf:>4}  {site:>5}  {system.nodes[site]}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "permutation-convention",
+   "metadata": {},
+   "source": [
+    "## Permutation convention\n",
+    "\n",
+    "`leaf_to_input[leaf]` gives the index in `system.nodes` placed at that compiled leaf. `input_to_leaf[site]` is the inverse used below to color each public lattice site by its merge-tree cell. The NetworkX loader preserves the supplied node order. HamiltonZero applies the learned permutation once to the context and walkers, then compiles an identity-routed tree, so **no extra bit reversal is needed**. For padded systems the arrays also contain virtual leaves, which must remain when determining merge groups even though they are not drawn as physical sites."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "id": "visualize",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "image/png": "iVBORw0KGgoAAAANSUhEUgAAB0QAAAGYCAYAAADSo1HRAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjExLjEsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvctoD+AAAAAlwSFlzAAASdAAAEnQB3mYfeAAAhqxJREFUeJzs3Xd0VOX69vErnRZKgFASem8aQIqgotKlK1WpUgQsCCqi6EEEURQVRTgqKCqiHJBmpEiRDhJACAJSJZAAgQABQhJSn/cP38zPIYUJBHZm+H7Wcp3M3s/sueZhnTs7+97FzRhjBNwFzpw5oypVqig2Nlb33HOP+vTpo3Llyuny5cs6duyYfvnlFyUlJengwYN273Nzc1P9+vW1c+dOi5JnbtasWRo8eLDy5Mmjl19+Wffee69CQ0M1ZcoUXbt2Td9884369etndUwAuCWNGjVSSEiI/P39NXDgQNWqVUuSdPz4cW3YsEHr1q1TWFiYAgMDbe9p0aKF1q5dq+joaBUuXNii5BmbNWuWhg0bpvvvv19t27bVhx9+qAsXLuTKrABws8aOHatJkybJx8dHTz75pB544AH5+vrq5MmT2r17t5YuXapp06apf//+tve89957eu2117RgwQJ17drVuvAZeOCBB3TmzBl17NhRVatWVbFixXTgwAFNmzZNFy5cUJ06dRQaGio3NzerowLATVu3bp0effRRSf/sT3fp0kUlSpTQ2bNndfDgQS1evFjNmjXT999/b3vPzp071aBBAz3zzDP6/PPPrYqeocjISJUvX15t27ZVo0aNVLFiRcXGxmrt2rX64YcfZIzR3Llz9eSTT1odFQBu2qVLl1SpUiVdvHhR1apV04ABA1ShQgXFxsbq2LFjWrFihU6fPq0zZ87Yva9w4cIqVqyYjh49alFyxxw7dky1a9dWgwYNtGnTJrVu3VorV660OhaclKfVAYA7ZeHChYqNjVWjRo20ceNGeXt7261/9913FRYWZk24m/TOO+9Ikr755hv16NFDktS1a1fVqlVLvXr10sSJE2mIAnBqBw8eVEhIiHx9fRUSEqJy5crZrX/jjTcUGRmpIkWKWJQw+9q3b69u3bqpUKFCkqTp06dbnAgAct63334rSfruu+/UvXv3dOvj4uJ09erVOx3rpn3//fcqX758uuU9e/ZUvXr19Oeff2rPnj2qW7funQ8HADkkrXYPHjxYX375Zbr1n3zyicLDw+90rJvm5+eniIgIFStWzG75gAEDVL58eb3zzjv6+eefaYgCcGq//PKLLl68qNq1a2v79u3Kly+f3fqJEyc63THvf3v++edVokQJvfHGG2rdurXVceDkaIjirnH27FlJUrt27dI1Q9P8+yDHli1b9O6770qSjh49qvbt29vWPfnkk3Y7zCkpKVq8eLHWrl2rs2fPqlChQnrooYf05JNPysfHxzbu2rVrtobl5MmTtXjxYv3yyy+6cuWKatasqSFDhiggIMCh7xMaGqqwsDBVrFgx3UGmHj166PXXX9fRo0e1f/9+29VUAOBs0mp33bp10zVD05QsWdL2c2xsrHr06KHQ0FBJ/xyo9vT8Z3cnrfb+29atW7VkyRIdP35cnp6eCgoKUr9+/ey2KUkvv/yy7az4P//8U999950iIiJUunRp9e7dWw0bNnT4O12/bQBwRWfPnpWbm5s6d+6c4fp8+fLZHawZOXKk7Uzv9957T998841t3eLFi+Xl5WV7HRYWph9++EH79+9XYmKiKlasqJ49e6ZrRn7//feaN2+exo0bp8DAQM2cOVP79u1T/vz59dhjj6lr164OX9GZUTNUkqpVq6bGjRvrt99+U2RkpEPbAoDcKm3fu0uXLhmud3NzU9myZW2vv/32W82aNUuStGLFCrvjJuPGjVODBg1sr69evaoffvhB27Zt0+XLl1WyZEm1adNGHTp0sKvFf/75p1577TV16tRJffv21TfffKPNmzcrKSlJjRo10pAhQ5Q/f36Hvo+3t3e6Zmia++67T5Lk4eHh0LYAILdKq92tWrVK1wxN8+992dDQUI0dO1axsbFKSkqyq92dOnXS4MGDba+NMfr555+1evVqnTlzRgUKFFCTJk3Up0+fdJ/VqVMnBQYGavr06VqxYoUWL15su2p10KBBqlChQra/26JFi7RixQotWbIk0+8GZIsB7hJff/21kWTatGnj0PgFCxYYSRn+N27cONu48PBwExQUlOG46tWrm5MnT9rGxsTEGEmmadOmZuDAgenGFyxY0GzZssWhfLNnzzaSTP/+/TNc369fPyPJzJ0716HtAUBudPLkSSPJFC9e3Fy8ePGG46OjozOt3U2bNrWNS0xMNH369MlwnK+vr/n111/tttuoUSMjycycOdN4eHjYjXdzczMfffTRTX/HgIAAI8lER0ff9DYAILepWrWqkWTWr1/v0Pj69etnWr/j4+Nt46ZPn268vb3TjXFzczNvv/223TbHjh1rJJnJkyeb4sWLp3tPly5dTFJS0i1/13r16hlJ5siRI7e8LQCw0vDhw40k88Ybbzg0/tVXX820dgcHB9vGbdu2zZQsWTLDca1bt7ar8+vWrTOSzDPPPGPbB//3f5UrVzbh4eG39D0vX75sWrRoYSSZefPm3dK2AMBqixYtMpJMkyZNTEpKyg3Hr169OtPaPWLECNu4s2fPmiZNmmQ4rkKFCubw4cN22/Xw8DC1atUyo0aNSjc+X758ZtWqVdn6XlevXjVlypQx7du3N8YYs2nTJtvvDeBmcYUo7hpdunTR2LFjtXLlSjVu3FjdunVTw4YNFRQUJF9f33TjH3jgAQUHB6tDhw6qXLmyPv74Y9u6qlWrSvrnytCOHTtqz549atmypTp37qwSJUro/PnzmjdvntavX68+ffpo/fr1dtvetWuXtmzZov79+6t58+a6dOmSZs+erT/++EPdu3fXoUOHbnjGY0REhCRlenZN2pk/znQ7GwC4XpkyZdShQwcFBwcrKChIvXv3VpMmTVS/fv0Mr7QsUKCAgoOD9cYbbyg0NFTz5s2z1VM/Pz/buFdffVVz5sxRjRo11LdvX1WsWFHXrl3T+vXrbbd3PHbsmIoWLWq3/eeff15NmzZVr169lDdvXi1btkwLFizQyy+/rCZNmqhRo0a3d0IAwEk8++yzGjFihNq1a6ennnpKDz/8sOrXr68qVapkeFXm1KlTNWvWLH377bcaM2aMmjZtaluXdneX5cuX69lnn1XRokXVv39/BQUFydvbW6Ghofr888/1n//8Rw0aNFCbNm3stj1u3DgVL15cH3zwgQIDA7Vr1y59+umnWrx4saZMmaIxY8bc9Pf87bff9Mcff+jRRx9V5cqVb3o7AJAbDBkyRDNnztQ777yj0NBQtWvXTvfdd5/q1KmT4Z22+vfvr5IlS2rkyJFq27athg8fbluXdgeVM2fOqH379rp8+bKeeuopPfLIIypcuLBOnjypmTNn6tdff9Ubb7yhKVOm2G077fa9o0ePVt26dXXy5El98sknOnr0qPr37681a9Y4/L1SU1PVsWNHSVJ0dLRCQ0OVnJyscePG2R4/BADOqk2bNqpUqZK2bt2q+vXrq2fPnmrYsKHq1atne1TPvwUFBSk4OFg9e/ZUwYIF7W6RXrFiRdvP3bp109atW/XQQw+pa9euKl26tKKjo7Vw4UKtXLlSPXr00K5du+z27dPuVtizZ0+1adNGcXFx+v7777V161b16tVLhw4dSnecJTNvv/22zp8/r2nTpt3C7ADXsbojC9xJu3fvNvfdd5/dGSoeHh6mQYMG5osvvjDJycnp3iPJ1K9fP8PtzZ8/30gyL774Yrp1qamp5rHHHjOSzF9//WWM+b8rRCWZKVOm2I1PSEgwDRo0MJLMrFmzbvhd0s7E/PDDDzNcP2XKlGyd2QkAudWFCxdMjx49jLu7u139rlixonn99dfNhQsX0r2nefPmmV51GRkZaby9vU2DBg3szkZP8+GHHxpJZtq0abZlaWenP/bYY+nOuHzppZeMJNOzZ8+b+n5cIQrAFaWkpJjx48eb/Pnz29VuPz8/07dvX7N///5073n33XeNJLNgwYIMt1mvXj2TL18+8/fff6dbFxoaaiSZTp062ZalXSHq7++f7nfFihUrbOscOZM+IydOnDAlS5Y0vr6+XB0KwGUsWbLElC1b1q5258mTx7Rq1cruqs80O3bssF3RmZHRo0cbSeb7779Pty4mJsZUqFDBFCxY0HY8Ju0KUUlm3bp1duPPnj1r/Pz8jCSzZ88eh79TUlJSuquVOnfubEJDQx3eBgDkZgcPHjRNmza1q3Pu7u6mbt265tNPPzUJCQnp3lOoUCFTqVKlDLe3atUqI8kMGDAgw/W9evUyksy2bdtsy9LupnX9sejk5GTbMZrrj4dnZv/+/cbLy8tMnDjRtowrRJETuEIUd5WgoCDt2LFDe/bssZ3NvXnzZu3YsUM7duzQokWLFBwcbPeMoqz8+uuvkv654rNz584yxkiSjDEyxuj48eOSpH379ql69eq29/n6+uqFF16w25a3t7dGjx6tbt26aePGjRo4cGCWn532TLzk5OQM1yclJdmNAwBn5efnp3nz5mnKlClatWqVQkJCFBISoj179mjSpEmaM2eONm3alOkzRq+3bt06JSYmKiYmRj179pT0f3Vbki5duiTpn9p9vddff13u7u52y8aOHasPP/xQGzduvIVvCQCuxd3dXf/5z380atQorVq1Stu2bdMff/yhrVu36rvvvtP//vc/LViwQB06dHBoe+fPn9cff/yhokWLauTIkZLsa7cxRl5eXhnW7uHDh9vdJUD650z6+vXra9euXTp06JBq1KiRre8XGRmpVq1aKTo6WsHBwVwdCsBldOrUSe3bt9fmzZu1ceNG23GTVatWadWqVRo9erQmT57s8PbSjpuk1f3rj5tcu3ZNV65cUXh4uN0z7h544AE9/PDDdtvy9/fX4MGDNXnyZG3cuFH33nuvQxk8PDwUHBwsY4zOnj2rDRs2aN68efr111+1YsUKNWvWzOHvAwC5UbVq1bR582bt379fa9eutd2dcPfu3dq9e7f+97//afXq1cqbN69D20ur3X/99Ve6Y96SFBYWJumf4yaNGze2vc/DwyPd3VfSlq1du1YbN27USy+9dMPPf/bZZ1WhQgW98sorDuUFHEWnBHeloKAgBQUF2V5v3LhR3bt316+//qpvv/1WgwYNcmg7abet3bRpU5bjYmNj7V5XqlQpw6ZrWtP0zJkzN/zstFseXLhwIcP1Fy9elCQVLlz4htsCAGcQGBiop59+Wk8//bSkf3bA+/Tpo82bN+vVV1/VvHnzHNpOWu0+ePCgDh48mOm462u3JLuTW9IUKVJEJUqUUGRkpEOfDwB3kwIFCujxxx/X448/Lkm6evWqXnvtNX322WcaPHiwIiIiHDqBL612X7hwQUuXLs10nKO1O235rl27dObMmWw1RE+fPq1HH31Uf//9txYtWqSWLVs6/F4AcAYeHh5q1qyZrVFojNGcOXM0cOBAvf/+++rZs6fq1q3r0LbS6ndwcHCW466v31nVbsmx4yZp3Nzc1L59e9vrQYMGqU2bNurdu7deeukl7dy50+FtAUBuVqtWLdWqVcv2OiQkRN27d9eWLVs0ffp0vfzyyw5tJ612//7771mOu752lylTJsPHwGWndn///fdav369Vq9eneHt2oFbQUMUkPTQQw/plVde0csvv6w1a9Y43BBNO3gzZcoUVatWLdNx/26+SlJMTEyG49KW+/j43PCz055jun///gzXpy2vUqXKDbcFAM6ofPny+uyzzxQUFJStZwil1e4+ffqoe/fumY4LDAxMtywmJibD511cvXrV4bsLAMDdrECBAvr00081f/58nT17Vvv27Uu3r5yRtNpdp04dTZo0KdNxefLkSbcsJ/a905w8eVLNmzfXiRMnNH/+fLsD7ADgqtzc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7dry8vJSp06dNHjwYEnS1KlTNXLkSElSsWLFVLVqVXl5eSksLEzh4eFKTU1VfHy87ZEVnp6e8vf3V2JiouLj43XvvfcqLi5O+/fvV3Jyspo3b67Vq1fLzc3tpr7n5s2b9eCDD6p169ZauXLlrUwZ7mYGuEuEhoaaQYMGmRIlShhJdv95eXmZrl27mrCwsHTv27VrlyldurTd+HHjxtmN+eabb0z58uXTbbdq1armvffes42LiYkxkkzTpk3NmjVrTMmSJW1j3dzczJNPPmni4uKy9b02b95sqlSpku5zt27delPzBAC5yYULF8xrr71matSoka7GSjINGzY0v/32W7r3Xb582TRp0sRubNOmTe3GbN++3TRt2jTdNv38/Mxzzz1noqKibGMbNWpkJJlDhw6Zhg0b2o2vX7++OXz4sMPfKTw8PMPv8u//VqxYcfOTBgC5wKeffmqaNWtmPDw80tW4smXLms8++yzD9z3//PPG3d3dbnx8fLxtfWRkpHnyySeNp6en3Rhvb2/z+OOPm127dtnGjh071kgyCxcuNP3797fbbokSJczPP//s8PepVKnSDWv3zJkzb37CACAXWLlypenataspUKBAuhpXsGBB8/zzz5srV66ke9+8efNM/vz57cYHBwfb1iclJZm33nrLFClSJN12GzdubP73v//Zxq5bt85IMiNGjDDTp083+fLls6v11x+Pycr27dtNp06djJeXl91nuru7mxYtWpg9e/bc0nwBQG5w8OBBM2zYMBMQEJCuxnp4eJj27dubQ4cOpXvfX3/9le549ogRI+zGLFiwwFStWjXdditUqGDGjRtnUlJSbGM9PDxMrVq1zNatW03ZsmXtxnfu3Nlcvnz5lr7npk2bjCTTunXrW9oO7m5cIYq7jjFGERERCg8P19WrV+Xn56caNWoof/78mb4nKSlJe/fu1blz55SSkqKqVatmeM/zQ4cOKTw8XPny5VO5cuUUEBBgtz7tCtG0sx+Tk5P1xx9/6MqVK6pRo0a68dn5Tn/++afOnj2rkiVLqk6dOje1HQDIzc6fP6+TJ08qKipK+fPnV7Vq1VS8ePEs33Po0CGdOHFCiYmJ8vPzy/AqoMjISB06dEipqakqW7asypUrZ7tSM03aFaJpZz8eOHBAp06dUunSpW3P1nDUtWvXMrx11781atToht8NAJxBbGysTpw4odOnT8vDw0Nly5ZVxYoVszwz/OzZs9q/f7/i4+NljNFjjz2W7naGV69e1Z9//qmrV6+qVKlSqlChQrr9+bQrRIODg9W+fXudPn1aBw8eVL58+VS/fn15eXk5/D3WrVun2NjYLMfce++9dmfdA4CzSkpK0smTJxUREaHExESVLFlS1atXz7JuXr16VXv37tWlS5eUmpqqhg0bprsleXJysvbt26dz587ZrtosWrSo3Zi0K0RHjBihqVOnKiYmRnv27FFycrLq1q2rwoULZ/v7xMbG6ujRo4qMjJSvr69q1qx5U9sBgNzMGKPTp08rPDxcly9fVpEiRVSjRg35+vpm+p6UlBTt3btXZ8+eVXJysipWrKiaNWumG3f06FGdOHFCPj4+KleunAIDA9Ptz3t6eqp69eq2u3nt2bNHFy9eVNWqVVWuXLlb/n7R0dHasmWL/P391bBhw1veHu5ONESBO+j6higAwDlc3xAFAOR+1zdEAQC53/UNUQCAc/h3QxTIrXhqOAAAAAAAAAAAAACXRUMUAAAAAAAAAAAAgMvyvPEQADklb968Cg4Olp+fn9VRAADZ8OGHHyo6Olre3t5WRwEAOKhPnz5q3LgxzxgCACdSp04dBQcHq2LFilZHAQBkw88//6wCBQpYHQPIEs8QBQAAAAAAAAAAAOCyuGUuAAAAAAAAAAAAAJdFQxQAAAAAAAAAAACAy6IhCgAAAAAAAAAAAMBleVodIKdcunRJGzZsUJkyZeTj42N1HABwCgkJCQoPD1ezZs1UuHBhSzJQvwEge6jdAOB8qN0A4Jysrt/UbgDIvsxqt8s0RDds2KDOnTtbHQMAnNKSJUvUqVMnSz6b+g0AN4faDQDOh9oNAM7JqvpN7QaAm3d97XaZhmiZMmUkSQWfmSrP4mUtTuP8Ln0+QpJUeOgnFidxDcxnzmEuc1b0Z8NlLkXaaqgVqN/IrS59PkKpSUnSE+OsjgLYm/+GdPUCtRsAnAj73QDgnKyu39RuAMi+zGq3yzRE024Z4Fm8rDxLV7Y4jfNz8/KWJOYyhzCfOYe5zFlunl4ykqW3XaF+I7dy8/KWjJtUvJzVUQB7Hl6SqN0A4EzY7wYA52R1/aZ2A0D2ZVa73a2JAwAAAAAAAAAAAAC3Hw1RAAAAAAAAAAAAAC6LhigAAAAAAAAAAAAAl0VDFAAAAAAAAAAAAIDLoiEKAAAAAAAAAAAAwGXREAUAAAAAAAAAAADgsmiIAgAAAAAAAAAAAHBZNEQBAAAAAAAAAAAAuCwaogAAAAAAAAAAAABcFg1RAAAAAAAAAAAAAC6LhigAAAAAAAAAAAAAl0VDFAAAAAAAAAAAAIDLoiEKAAAAAAAAAAAAwGXREAUAAAAAAAAAAADgsmiIAgAAAAAAAAAAAHBZNEQBAAAAAAAAAAAAuCwaogAAAAAAAAAAAABcFg1RAAAAAAAAAAAAAC6LhigAAAAAAAAAAAAAl0VDFAAAAAAAAAAAAIDLoiEKAAAAAAAAAAAAwGXREAUAAAAAAAAAAADgsmiIAgAAAAAAAAAAAHBZNEQBAAAAAAAAAAAAuCwaogAAAAAAAAAAAABcFg1RAAAAAAAAAAAAAC6LhigAAAAAAAAAAAAAl0VDFAAAAAAAAAAAAIDLoiEKAAAAAAAAAAAAwGXREAUAAAAAAAAAAADgsmiIAgAAAAAAAAAAAHBZNEQBAAAAAAAAAAAAuCwaogAAAAAAAAAAAABclqfVATZv3qz169crOTlZ9913n9q1ayc3NzerYwEAsnDs2DEtXbpUFy9eVOXKlfXEE0/I19fX6lgAgCxcunRJCxcu1PHjx1W8eHF17txZ5cqVszoWACALKSkpCg4O1u7du+Xj46PmzZurUaNGVscCANxASEiI1qxZo4SEBAUFBaljx47y8PCwOhYA3NUsu0LUGKOBAweqTZs2On/+vJKSkjR48GC1atVK165dsyoWAOAGZs+erZo1ayokJEQ+Pj6aNm2aatWqpSNHjlgdDQCQidDQUFWvXl0zZ85Unjx5tGnTJlWvXl0//fST1dEAAJmIiYnRQw89pOeee06pqak6c+aMHnnkEb344otWRwMAZGHkyJFq1qyZTp8+LWOMRowYoQcffFAxMTFWRwOAu5plV4h+/fXX+vrrr7Vy5Uq1bt1aktSvXz/dc889Gj9+vN59912rogEAMnH06FE988wzGjFihD744ANJ0ujRo1W/fn099dRTCgkJsTghAOB6KSkp6tmzp8qWLavNmzfL0/OfPwGGDRum/v37q0mTJipdurTFKQEA1xs9erRCQ0O1f/9+2xX9Dz/8sLp27aoHH3xQTzzxhMUJAQDXW7hwoaZOnap58+apR48ekqQhQ4aoZs2aGj16tP773/9anBAA7l6WXSE6Y8YM1axZ09YMlaSqVauqXbt2+uKLL5SUlGRVNABAJmbOnKmkpCSNHDnStszHx0fPPvusduzYoe3bt1uYDgCQkd9++00HDx7U888/b2uGStKoUaMUGxur2bNnW5gOAJCR2NhYffvtt3riiSfsbm+e9vqzzz6zMB0AIDMzZsxQQECAunfvblsWGBiobt266dtvv9XVq1ctTAcAdzdLGqKxsbHavXt3hs+9uP/++xUdHa39+/dbkAwAkJVNmzapTJky6a4kuv/++23rAQC5S1ptvn7fu0qVKipatCi1GwByoV27dik+Pj7D4yaNGzfWtm3blJKSYkEyAEBmUlNTtW3bNjVs2FBubm526+6//37Fx8dr586dFqUDAFhyy9zw8HAZYzK8NVfashMnTigoKCjD9587d05RUVF2y44ePZrjOQEA9k6ePKnAwMB0y/9du7NC/QaAO+/kyZOSlOm+N7UbAHKfG9XuhIQERUZGKiAgIMP3U7sB4M47d+6c4uPjb3jMO6v3U7sB4PaxpCEaHx8v6Z/bLF4vT548dmMyMmPGDI0fP/72hAMAZCo+Pv6ma7dE/QYAK9xo3/vKlStZvp/aDQB3HsdNAMD5ULsBIHezpCGaP39+SRn/AkhbljYmI8OHD1e3bt3slh09elSdO3fOuZAAgHTy589/07Vbon4DgBX+ve/t5eVlty4+Pp7aDQC5EMdNAMD5ULsBIHezpCFatmxZubu7KyIiIt268PBwSVKFChUyfb+/v7/8/f1vWz4AQMbKly+f4e1aHKndEvUbAKxQvnx5SVJERIRq1qxpty4iIkJNmzbN8v3UbgC48/5du68XHh6ufPnyqUSJEpm+n9oNAHde8eLFlT9/fo55A0Au5W7Fh+bJk0eNGjXS1q1b063bvHmz/P39VaNGDQuSAQCy8vDDD+vMmTM6fvy43fLNmzfb1gMAcpe02rxlyxa75fv27dOlS5eo3QCQC9WrV0++vr7pandqaqq2bdumBx98UO7ulhzSAQBkws3NTQ899JC2b9+ulJQUu3WbN29WgQIFVL9+fYvSAQAs23t+4YUXdOzYMc2bN8+2bNeuXVq5cqWef/55eXh4WBUNAJCJwYMHK2/evHrnnXdsy65cuaJp06apWbNmCgoKsi4cACBDDz74oOrWraupU6cqLi7OtnzSpEkqVKiQ+vfvb104AECG8uTJoyFDhmjp0qXav3+/bfns2bN1+vRpvfjii9aFAwBk6oUXXtC5c+c0c+ZM27KDBw9q4cKFeuaZZ5Q3b14L0wHA3c2SW+ZKUs+ePbVnzx7169dPS5cuVb58+bRgwQJ169ZNY8aMsSoWACALZcqU0Q8//KA+ffro2LFjqlWrllasWKG8efNq7ty5VscDAGTAzc1N8+fPV9u2bVW3bl21bNlSoaGh2rdvnxYsWKBixYpZHREAkIGJEyfq0KFDeuCBB9S1a1ddvnxZS5cu1cSJE9WmTRur4wEAMtCmTRu98847GjFihNasWSM/Pz/99NNPat68uSZOnGh1PAC4q1nWEJWk9957TwMGDNDGjRuVnJysoUOHqkGDBlZGAgDcQOfOnXX8+HH9+uuvunjxotq1a6cWLVrIy8vL6mgAgExUrlxZ+/bt0+rVq3X8+HE1bdpUbdq0UZEiRayOBgDIRJ48eRQcHKxt27Zp9+7d8vb21rvvvqtKlSpZHQ0AkIXXX39dPXv21Lp165SQkKD+/furSZMmVscCgLuepQ1RSapWrZqqVatmdQwAQDYUK1ZMTz31lNUxAADZ4OPjo/bt21sdAwCQTffff7/uv/9+q2MAALKhYsWKqlixotUxAAD/YtkzRAEAAAAAAAAAAADgdqMhCgAAAAAAAAAAAMBl0RAFAAAAAAAAAAAA4LJoiAIAAAAAAAAAAABwWTREAQAAAAAAAAAAALgsGqIAAAAAAAAAAAAAXBYNUQAAAAAAAAAAAAAui4YoAAAAAAAAAAAAAJdFQxQAAAAAAAAAAACAy6IhCgAAAAAAAAAAAMBl0RAFAAAAAAAAAAAA4LJoiAIAAAAAAAAAAABwWTREAQAAAAAAAAAAALgsGqIAAAAAAAAAAAAAXBYNUQAAAAAAAAAAAAAui4YoAAAAAAAAAAAAAJdFQxQAAAAAAAAAAACAy6IhCgAAAAAAAAAAAMBl0RAFAAAAAAAAAAAA4LJoiAIAAAAAAAAAAABwWTREAQAAAAAAAAAAALgsGqIAAAAAAAAAAAAAXBYNUQAAAAAAAAAAAAAui4YoAAAAAAAAAAAAAJdFQxQAAAAAAAAAAACAy6IhCgAAAAAAAAAAAMBl0RAFAAAAAAAAAAAA4LJoiAIAAAAAAAAAAABwWTREAQAAAAAAAAAAALgsGqIAAAAAAAAAAAAAXBYNUQAAAAAAAAAAAAAui4YoAAAAAAAAAAAAAJdFQxQAAAAAAAAAAACAy/K0OkBOu/T5CLl5eVsdw+mlnDkmSbowoYvFSVwD85lzmMuclRp9xuoINtTvW5dy8YzcJLn7lbI6iktIqzeaNdTaIK7iSpTkJsm3uNVJnF/MeasT2FC7cwb1O+cwlzmL+cw5uWm/GwAAALgbuVxDFADgnFKTkiTjZnUM55ZqZNyklMQkq5O4FA9vL6sjuIQUd7d/Dqozn7csJReVSmp3DqF+5xzmMmcxnznHWB0AAAAAuLu5XEO08NBP5Fm6stUxnF7a1XdF31xscRLXwHzmHOYyZ53/Tzulng+3OsY/nhgnFS9ndQrg/8waKg9vL+oNch1qNwA4oc+fli5HWp0CAAAAuGvxDFEAAAAAAAAAAAAALouGKAAAAAAAAAAAAACXRUMUAAAAAAAAAAAAgMuiIQoAAAAAAAAAAADAZdEQBQAAAAAAAAAAAOCyaIgCAAAAAAAAAAAAcFk0RAEAAAAAAAAAAAC4LBqiAAAAAAAAAAAAAFwWDVEAAAAAAAAAAAAALouGKAAAAAAAAAAAAACXRUMUAAAAAAAAAAAAgMuiIQoAAAAAAAAAAADAZdEQBQAAAAAAAAAAAOCyaIgCAAAAAAAAAAAAcFk0RAEAAAAAAAAAAAC4LBqiAAAAAAAAAAAAAFwWDVEAAAAAAAAAAAAALouGKAAAAAAAAAAAAACXRUMUAAAAAAAAAAAAgMuiIQoAAAAAAAAAAADAZdEQBQAAAAAAAAAAAOCyaIgCAAAAAAAAAAAAcFk0RAEAAAAAAAAAAAC4LBqiAAAAAAAAAAAAAFwWDVEAAAAAAAAAAAAALouGKAAAAAAAAAAAAACXRUMUAAAAAAAAAAAAgMuiIQoAAAAAAAAAAADAZdEQBQAAAAAAAAAAAOCyaIgCAAAAAAAAAAAAcFk0RAEAAAAAAAAAAAC4LBqiAAAAAAAAAAAAAFwWDVEAAAAAAAAAAAAALouGKAAAAAAAAAAAAACXZWlDNCQkRC+//LKqV6+uwMBAHThwwMo4AAAHnDhxQh988IEaNWqkwMBAffHFF1ZHAgDcwOXLl/Xdd9+pffv2KlOmjPr06WN1JADADSQnJ+vXX3/VwIEDVaFCBZUvX97qSAAAB+zZs0evv/66atWqpcDAQG3bts3qSAAAWdgQ/fTTT/Xcc8+pZMmSevTRR3Xq1CklJiZaFQcA4IB9+/bp4Ycf1rlz5zRgwACdOnVKMTExVscCANxAo0aNtGbNGg0dOlQXL15UVFSU1ZEAADcwZMgQffTRR2ratKkqVaqkiIgIqyMBAG7g22+/Vf/+/eXr66t27drp1KlTSkhIsDoWAECSp1UfPHz4cL3wwguSpIkTJ1oVAwCQDTVq1NDx48clSb///rvFaQAAjtq3b588Pf/Z9Xdzc7M4DQDAEV9++aWtdv/8888WpwEAOOKpp55Sv379JEmfffaZxWkAAP9m2RWiaTv1AADn4eHhYXUEAMBNYN8bAJwPtRsAnA+1GwByL4caok2bNtVbb72lLVu2KDk5+XZnAgAAAAAAAAAAAIAc4dApKx4eHpo0aZLGjx8vX19fPfLII2rZsqVatmypatWq3e6M6Zw7dy7dc4+OHj16x3MAALKH+g0AzofaDQDOh9oNAM6H2g0At5dDDdGNGzfq6tWrWr9+vVavXq3Vq1fbnl9RpkwZtWzZUl999dVtDfpvM2bM0Pjx4+/Y5wEAcgb1GwCcD7UbAJwPtRsAnA+1GwBuL4dval6gQAG1b99e7du3lyTt2bNHY8aM0a+//qqvv/76jjZEhw8frm7dutktO3r0qDp37nzHMgAAso/6DQDOh9oNAM6H2g0AzofaDQC3l8MN0cTERG3ZskWrVq3S6tWr9ccff8jb21vNmzdXy5Ytb2fGdPz9/eXv739HPxMAcOuo3wDgfKjdAOB8qN0A4Hyo3QBweznUEH3ssce0YcMGxcXFqU6dOmrZsqXeeecdPfTQQ8qbN+/tzggAAAAAAAAAAAAAN8WhhuiKFSuUN29evfbaa+rTp49q1Khxu3MBAAAAAAAAAAAAwC1zd2TQt99+qyeeeEKzZ89WzZo1VaZMGT399NP68ccfFRUVdVMfvHv3bgUGBiowMFAffPCBJKl169YKDAzUPffcc1PbBADcftWqVVNgYKA6duwoSZo4caKtnh84cMDidACAjAwaNMhWq+Pi4rR+/Xrb6y+++MLqeACADHzzzTe2Wv3rr78qJSXF9rpPnz5WxwMAZODYsWO2Wv3mm29Kkrp166bAwECVL1/e2nAAcJdz6ArRvn37qm/fvpKkP//8U6tXr9bq1as1aNAgxcfHKygoSH/88Ue2PrhWrVr6/fffM1zn4eGRrW0BAO6cdevWKTU1NcN1JUqUuMNpAACOmDx5st56660M1xUuXPiOZgEAOKZbt25q0aJFhuvy5Mlzh9MAABxRrly5TI95u7m53eE0AIB/c6gh+m+1a9dWamqqUlJSFBcXp40bN2r37t3Z/mBvb28FBgZm+30AAGuVLl3a6ggAgGwqWrSo1REAANmUP39+5c+f3+oYAIBs8PT05Jg3AORSDjVEIyMjtXr1aq1atUqrV6/W2bNn5ebmpnvuuUcvv/xypmcsAgAAAAAAAAAAAICVHGqIli5dWsYYBQYGqm3btmrZsqVatGghf3//250PAAAAAAAAAAAAAG6aQw3RqVOnqmXLlqpRo8btzgMAAAAAAAAAAAAAOcahhugLL7xg+/ns2bM6f/68ihUrphIlSty2YAAAAAAAAAAAAABwq9wdHbhy5UrVrl1bJUuWtPvfVatW3c58AAAAAAAAAAAAAHDTHLpCdP369Wrfvr0qVKigl156SSVLltTZs2e1ZMkStWvXTr/99psefPDB250VAAAAAAAAAAAAALLFoYbo22+/rV69eumbb76Rh4eHbfl7772n/v3766233tLatWtvW0gAAAAAAAAAAAAAuBkONURDQkK0f/9+u2aoJHl4eGjChAmqU6fObQkHAAAAAAAAAAAAALfCoWeIpqSkKE+ePBmuy5s3r1JSUnI0FAAAAAAAAAAAAADkBIcaorVq1dK0adMyXDd9+nTVqlUrR0MBAAAAAAAAAAAAQE5w6Ja5I0eOVO/evbV79249/vjjKlmypM6ePavFixfrl19+0Y8//ni7cwIAAAAAAAAAAABAtjnUEH3qqad07tw5jRs3TsuXL7ct9/X11SeffKKePXvetoAAAAAAAAAAAAAAcLMcaoheunRJTz/9tIYMGaKQkBBdvHhRRYsWVYMGDZQ/f/7bnREAAAAAAAAAAAAAbopDDVE/Pz/NmzdP3bt31yOPPHK7MwEAAAAAAAAAAABAjnB3ZFCpUqXUvHnz250FAAAAAAAAAAAAAHKUQw3RAQMGaN68ebc7CwAAAAAAAAAAAADkKIdumdurVy+NHz9e+/fvV8eOHRUQECAvLy+7MdWrV78tAQEAAAAAAAAAAADgZjnUEK1du7bt5//+978ZjjHG5EwiAAAAAAAAAAAAAMghDjVEZ8+efbtzAAAAAAAAAAAAAECOc6gh2r9//9scAwAAAAAAAAAAAABynrvVAQAAAAAAAAAAAADgdqEhCgAAAAAAAAAAAMBl0RAFAAAAAAAAAAAA4LJoiAIAAAAAAAAAAABwWTREAQAAAAAAAAAAALgshxuiqamp+uWXX/TKK6/o6aefti1fu3atkpOTb0s4AAAAAAAAAAAAALgVno4Munr1qtq3b68NGzYob968io+P19dffy1J+vrrr3XhwgV17979tgYFAAAAAAAAAAAAgOxy6ArRN954Q2fOnNHmzZsVGxtrt27w4MH68ssvb0s4AAAAAAAAAAAAALgVDl0humDBAv3000+6//77062rVauWduzYkePBAAAAAAAAAAAAAOBWOXSF6Llz53TPPffYXru5udl+9vb2VkJCQs4nAwAAAAAAAAAAAIBb5FBDtGTJkgoNDbW9/ndDNCQkROXKlcv5ZAAAAAAAAAAAAABwixxqiHbs2FHPPvusTpw4Ybf89OnTevnll9W5c+fbkQ0AAAAAAAAAAAAAbolDDdFx48bp8uXLqlatmh588EEZY9S2bVtVq1ZN8fHxeu211253TgAAAAAAAAAAAADINk9HBvn7+2v79u2aMGGCgoOD5ePjo3379qlPnz4aP368ChcufJtjOu7S5yPk5uVtdQynl3LmmCTpwoQuFidxDcxnzmEuc1Zq9BmrI/yfheMlT+r3LbkSJblJ8i1udRLXcOGkUkS9ySkpF8/ITZK7Xymrozg9arcLon7nHOYyZzGfOSfmvNUJbDhukjPYt8k5zGXOYj5zVq7a9wYA3BKHGqKSVLx4cX366af69NNPb2ceAMBdyt3LS25eXlbHcGop7m7//OHrzTzmhJS0/01MsjSHy0g1Mm7MZ44wVgf4P9TunEH9zjnMZc5iPnNOipvVCf5PalKSZHJRIGfFvk3OYS5zFvOZs3LRvjcA4NY41BCNi4vTsmXL1K1bt3TrFixYoHbt2ilfvnw5Hu5mFB76iTxLV7Y6htNLuxqm6JuLLU7iGpjPnMNc5qzz/2mn1PPhVseQRP1G7nNhQpd/DiIM+tzqKIC9z5+WLkdanUIStRsAHJWb9rv1xDipeDmrUwCAc8hF+94AgFvj0DNEP/jgA/31118Zrjtw4ICmTJmSo6EAAAAAAAAAAAAAICc41BCdO3eunnzyyQzXPfnkk/rhhx9yNBQAAAAAAAAAAAAA5ASHGqInTpxQiRIlMlxXokQJhYWF5WQmAAAAAAAAAAAAAMgRDjVES5UqpZCQkAzXhYSEyN/fP0dDAQAAAAAAAAAAAEBOcKgh2qFDBz333HM6duyY3fJjx47pueeeU4cOHW5LOAAAAAAAAAAAAAC4FZ6ODHrzzTcVHBysGjVqqFGjRgoICNCpU6e0fft2lS5dWuPGjbvdOQEAAAAAAAAAAAAg2xy6QtTf31/bt2/XwIEDdfLkSS1dulQnTpzQoEGDtH37dm6ZCwAAAAAAAAAAACBXcugKUUkqUaKE/vvf/97OLAAAAAAAAAAAAACQoxy6QhQAAAAAAAAAAAAAnFGGV4ju3LlTknTffffZvc5K2lgAAAAAAAAAAAAAyC0ybIg2aNBAkmSMsXudlbSxAAAAAAAAAAAAAJBbZNgQXbx4cZavAQAAAAAAAAAAAMAZZNgQ7dy5c5avAQAAAAAAAAAAAMAZuDsyaN68ebe0HgAAAAAAAAAAAACs4FBDtFevXre0HgAAAAAAAAAAAACs4FBDNCsJCQny8PDIiSwAAAAAAAAAAAAAkKMyfIaoJO3ZsyfL19I/zdDly5crMDAwp3MBAAAAAAAAAAAAwC3LtCFat27dLF+ncXd315QpU3I2FQAAAAAAAAAAAADkgEwboj/++KPt5169etm9TpM/f37VrFlTlSpVuj3pAAAAAAAAAAAAAOAWZNoQ7dmzp+3nsLAwu9cAAAAAAAAAAAAA4AzcHRlUvnz5LNfPmzcvJ7IAAAAAAAAAAAAAQI5yqCHaq1evW1oPAAAAAAAAAAAAAFZwqCGalYSEBHl4eOREFgAAAAAAAAAAAADIUZk+Q3TPnj1Zvpb+aYYuX75cgYGBOZ0LAAAAAAAAAAAAAG5Zpg3RunXrZvk6jbu7u6ZMmZKzqQAAAAAAAAAAAAAgB2TaEP3xxx9tP/fq1cvudZr8+fOrZs2aqlSp0u1JBwAAAAAAAAAAAAC3INOGaM+ePW0/h4WF2b0GAAAAAAAAAAAAAGfg7sigMWPG3O4cAAAAAAAAAAAAAJDjHGqIStKsWbPUoEEDFSlSRAUKFEj3HwAAAAAAAAAAAADkNg41RD/77DMNHz5clStX1qVLl9SrVy81btxYCQkJeuihh9S/f//bHBMAAAAAAAAAAAAAss+hhujMmTP12Wef6ccff7S9XrNmjY4cOaK4uDj17t37toYEAAAAAAAAAAAAgJvhUEP00KFDeuKJJ2yvU1JSJEnly5fXtGnT9PLLL9+edAAAAAAAAAAAAABwCxxqiCYkJKho0aKSpHz58uns2bO2dZUqVdLu3btvTzoAAAAAAAAAAAAAuAUONUT/rWbNmvrpp59sr3/55Rf5+fnddIDIyEiFhIQoIiJCxpib3g4A4M6JiYnRrl27dOTIESUlJVkdBwDggMTERB04cEChoaG6evWq1XEAAA4wxigsLEw7duxQVFSU1XEAAA6KiopSSEiITp48qdTUVKvjAAB0Ew3RAQMGaOTIkWrVqpXat2+vp556Sr169cr2B3/00UeqUaOGqlWrpueee05BQUGqXr26li1blu1tAQDujOXLl6t58+YqVqyYhgwZolatWsnf31/vv/8+J7UAQC71119/qW/fvipcuLC6dOmiPn36qGjRoho0aJAuXrxodTwAQAYuX76s1157TaVKldL999+v4cOHq0KFCmrWrJlCQ0OtjgcAyMTnn3+ue++9VxUrVtRzzz2nBg0aqFKlSlqwYIHV0QDgrudQQ3Tbtm22n4cNG6Z33nlHERER+vvvv/Xyyy9rwoQJ2f7g0aNHq1u3bjp9+rTtCtFGjRqpY8eO2rRpU7a3BwC4/T766CMVKFBAx44d065du3T8+HG9//77evXVV2/qdwEA4PZbunSpduzYoTVr1ujQoUPau3evtm3bpp9++kmdO3e2Oh4AIANHjhzRjBkzNGnSJEVERGjHjh06fvy4EhIS9Mgjj9g9yggAkHu8/vrratGihU6dOmU75t2uXTt1796dC4EAwGIONUQbN25s+9nNzU1jxozRgQMHdODAAb377rvy8fHJ9gcvXLhQb7/9tvLnzy9JypMnjz7++GOlpqbq66+/zvb2AAC33wsvvKAlS5YoMDDQtmzw4MEKCgrSzJkzLUwGAMhM48aN9fvvv6tJkya2ZfXq1dPgwYO1adMmHTp0yMJ0AICM+Pn5afPmzXr66afl4eEhSSpevLjGjx+v6Ohou0cZAQByj9mzZ+vDDz9UwYIFJUleXl6aMmWKvLy8NGvWLIvTAcDdzdOqD+7UqVO6Zd7e3nJzc9OlS5fufCAAwA117Ngxw+U+Pj7UbgDIpR5++OEMl6ed1Ej9BoDcp2LFihkup3YDQO6W0TFvDw8PeXp6UrsBwGIZNkR37tyZ7Q3dd999txzmq6++kjFGDzzwQJbjzp07p6ioKLtlR48eveXPBwBk3969exUSEqLWrVvfcCz1GwByh2vXrmnu3LkqWLCg7rnnnizHUrsBIPdIu7qI4yYA4Dzmzp2r+Ph4ajcAWCzDhmiDBg2yvSFjzC0F2b9/v9544w1VqFBBzzzzTJZjZ8yYofHjx9/S5wEAbl1cXJz69OkjT09Ph54hSv0GgNzhxRdfVFhYmD788EPlzZs3y7HUbgDIHX766SfNnTtXbdu2VbNmzbIcS+0GgNzh+PHjGjVqlEqWLKkXX3wxy7HUbgC4vTJsiC5evPiOhjh58qQee+wxeXp6auHChSpQoECW44cPH65u3brZLTt69Kg6d+58G1MCAP4tKSlJ3bp10969e/XFF184dKcA6jcAWG/y5Mn64osv1KNHD40cOfKG46ndAGC9TZs2qW/fvqpWrZq+/fbbG46ndgOA9c6dO6c2bdooISFBP//8s4oWLZrleGo3ANxeGTZE72SRPXPmjFq0aKHo6GitWrVKdevWveF7/P395e/vfwfSAQAykpKSol69emn58uWaOnWqhgwZ4tD7qN8AYK1p06ZpzJgx6tKli77//nu5ubnd8D3UbgCwVkhIiNq1a6eAgACtXbtWxYsXv+F7qN0AYK2LFy+qZcuWOnnypH755Zcb3i5XonYDwO2WYUP0TomKilLz5s115swZ/frrr2rcuLGVcQAADkhNTVXfvn21cOFCffTRRxoxYoTVkQAADpg5c6ZGjBihTp066X//+588PS39UwAA4IDdu3erdevWKl68uNatW6eAgACrIwEAbuDy5ctq1aqVDh8+rKVLl6p58+ZWRwIASHK36oOjo6PVokULhYeHa8WKFWrSpIlVUQAADjLGaPDgwfrhhx80ZcoUh261CACw3pw5czR06FB16NBB8+fPl5eXl9WRAAA3sH//frVq1Up+fn5av369AgMDrY4EALiBq1evqm3bttq/f7+WLFmiVq1aWR0JAPD/WXJaeFJSktq0aaO9e/dqwoQJSk5O1vr1623rCxYsqHr16lkRDQCQhdGjR+vrr79Wly5dVL9+fbvaLUkPPvigPDw8rAkHAMjQsmXLNGDAAFWsWFHPPvustm7dare+du3aKlasmEXpAAAZiYiIUMuWLRUbG6uPPvpIx44d07Fjx2zrAwICVKVKFQsTAgCuZ4xRx44dtW3bNo0ZM0Y+Pj52x03y5cunhg0bWhcQAO5yljRE4+LilDdvXjVr1kxr1qzRmjVr7NbXrFlTM2bMsCIaACAL0dHRatasmS5evKi33nor3foVK1Yob968dz4YACBTJ0+etD2zaNKkSenWT5w40aFnGgEA7pzTp0+ratWqkqSvvvoq3fouXbrw6AoAyGVSU1OVmpqqZs2aadu2bdq2bZvd+rJly+q7776zKB0AwJKGaKFChdJdVQQAyP1mzZpldQQAQDYNGzZMw4YNszoGACAbGjZsyHETAHAyHh4e1G4AyMUse4YoAAAAAAAAAAAAANxuNEQBAAAAAAAAAAAAuCwaogAAAAAAAAAAAABcFg1RAAAAAAAAAAAAAC6LhigAAAAAAAAAAAAAl0VDFAAAAAAAAAAAAIDLoiEKAAAAAAAAAAAAwGXREAUAAAAAAAAAAADgsmiIAgAAAAAAAAAAAHBZNEQBAAAAAAAAAAAAuCwaogAAAAAAAAAAAABcFg1RAAAAAAAAAAAAAC6LhigAAAAAAAAAAAAAl0VDFAAAAAAAAAAAAIDLoiEKAAAAAAAAAAAAwGXREAUAAAAAAAAAAADgsmiIAgAAAAAAAAAAAHBZNEQBAAAAAAAAAAAAuCwaogAAAAAAAAAAAABcFg1RAAAAAAAAAAAAAC6LhigAAAAAAAAAAAAAl0VDFAAAAAAAAAAAAIDLoiEKAAAAAAAAAAAAwGXREAUAAAAAAAAAAADgsmiIAgAAAAAAAAAAAHBZNEQBAAAAAAAAAAAAuCwaogAAAAAAAAAAAABcFg1RAAAAAAAAAAAAAC6LhigAAAAAAAAAAAAAl0VDFAAAAAAAAAAAAIDLoiEKAAAAAAAAAAAAwGXREAUAAAAAAAAAAADgsmiIAgAAAAAAAAAAAHBZnlYHyGmXPh8hNy9vq2M4vZQzxyRJFyZ0sTiJa2A+cw5zmbNSo89YHcGG+n3rUi6ekZskd79SVkdxCWn1RrOGWhvEVVyJktwk+Ra3OonzizlvdQIbanfOoH7nHOYyZzGfOSc37XcDAAAAdyOXa4gCAJxTalKSZNysjuHcUo2Mm5SSmGR1Epfi4e1ldQSXkOLu9s9BdebzlqXkolJJ7c4h1O+cw1zmLOYz5xirAwAAAAB3N5driBYe+ok8S1e2OobTS7v6ruibiy1O4hqYz5zDXOas8/9pp9Tz4VbH+McT46Ti5axOAfyfWUPl4e1FvUGuQ+0GACf0+dPS5UirUwAAAAB3LZ4hCgAAAAAAAAAAAMBl0RAFAAAAAAAAAAAA4LJoiAIAAAAAAAAAAABwWTREAQAAAAAAAAAAALgsGqIAAAAAAAAAAAAAXBYNUQAAAAAAAAAAAAAui4YoAAAAAAAAAAAAAJdFQxQAAAAAAAAAAACAy6IhCgAAAAAAAAAAAMBl0RAFAAAAAAAAAAAA4LJoiAIAAAAAAAAAAABwWTREAQAAAAAAAAAAALgsGqIAAAAAAAAAAAAAXBYNUQAAAAAAAAAAAAAui4YoAAAAAAAAAAAAAJdFQxQAAAAAAAAAAACAy6IhCgAAAAAAAAAAAMBl0RAFAAAAAAAAAAAA4LJoiAIAAAAAAAAAAABwWTREAQAAAAAAAAAAALgsGqIAAAAAAAAAAAAAXBYNUQAAAAAAAAAAAAAui4YoAAAAAAAAAAAAAJdFQxQAAAAAAAAAAACAy6IhCgAAAAAAAAAAAMBl0RAFAAAAAAAAAAAA4LJoiAIAAAAAAAAAAABwWTREAQAAAAAAAAAAALgsGqIAAAAAAAAAAAAAXBYNUQAAAAAAAAAAAAAui4YoAAAAAAAAAAAAAJdFQxQAAAAAAAAAAACAy6IhCgAAAAAAAAAAAMBl0RAFAAAAAAAAAAAA4LI8rfzwM2fOKDg4WIcPH1aBAgVUp04dderUSZ6elsYCAGQhPj5ewcHB2rt3r5KTk1WxYkV169ZNRYoUsToaACATxhitW7dO27dvV1RUlAIDA9W+fXtVrVrV6mgAgCzs379fa9asUVhYmIoXL677779fjzzyiNWxAABZiIqK0s8//6xDhw4pT548qlmzph5//HF5e3tbHQ0A7mqWXSE6adIkPfroowoNDVVAQIDi4uI0fPhwVa1aVUeOHLEqFgAgC2vXrlXt2rUVHBwsX19f5c+fXzNmzFCZMmW0cOFCq+MBADJw4cIF1alTRx9++KGuXbumUqVKaf369apRo4Zeeuklq+MBADLRvXt3DRgwQOHh4SpbtqxOnDihdu3a6aGHHlJMTIzV8QAAGfjss8/UtGlT7dixQyVLllRycrJefvllVaxYUXv37rU6HgDc1Sy7FLNLly567bXX5ObmZls2dOhQVatWTa+++qoWLVpkVTQAQCYqV66svXv3Kn/+/LZlr776qurXr6/BgwdzlT8A5EI+Pj5avny5ypYta1v2yiuv6Nlnn9VHH32kHj16qGHDhhYmBABk5K233lLNmjXtlrVp00aPP/64pk2bptdff92iZACAzLRs2VLDhg2Th4eHbdnzzz+vKlWq6MUXX9Rvv/1mYToAuLtZdoVojRo17JqhklSxYkWVLl1aJ0+etCgVACAr5cqVs2uGSpK3t7caNmyo6OhozlQHgFyoQIECds3QNA888IAkse8NALnU9c1QidoNALldtWrV7JqhklSqVClVqlSJ2g0AFrOsIZqRnTt3KiIiQm3btrU6CgDAQZcvX9a6devUuHFjniMKAE7CGKOlS5eqQIECtoPrAIDcb8mSJZLEcRMAcCJ//fWXDh06RO0GAItZfl/D1157TRcuXNCpU6e0a9cuTZw4UaNHj87yPefOnVNUVJTdsqNHj97OmACAf/n222+1bds2RUdHa/369WrXrp3ef//9G76P+g0A1gkJCdHXX3+tuLg47dixQyVKlNCGDRtUsmTJLN9H7QYA61y5ckWjR49WcnKyDh8+rNOnT2vu3Lnq1KlTlu+jdgOAtSZMmKCIiAhFRkZq27ZtGj16tN54440s30PtBoDby/KGaK1atXT58mUVKlRIO3fu1M8//6wePXqoYsWKmb5nxowZGj9+/B1MCQD4t7Jlyyo+Pl6RkZE6dOiQVq1apW7dut3wbEfqNwBYp0iRIgoKCtKVK1d06dIlrVu3TsuWLVO9evWyfB+1GwCs4+XlpaCgICUkJMjDw0O7d+/WkiVL1L59exUsWDDT91G7AcBa1apVU9GiRVWkSBHt2rVLwcHB6tmzZ4a3Q09D7QaA28vyhmjv3r1tP7/yyiu655571L17d+3cuTPT9wwfPlzdunWzW3b06FF17tz5dsUEAPzLI488okceeUSS9J///Edt27ZV165ddeTIEZUuXTrT91G/AcA6VapUUZUqVSRJo0eP1uTJkzVmzBjVqFFDXbt2zfR91G4AsE7evHk1dOhQ2+uBAweqSZMm8vPz0+eff57p+6jdAGCt7t27235+7bXXFBQUpC5duuivv/6Su3vGT7GjdgPA7WV5Q/Tf/P399dhjj2n27Nm6ePGi/Pz8Mh3n7+9/h9MBADLi7u6ufv36adWqVdq8ebPdTv/1qN8AkHsMGDBAY8aM0apVq7JsiFK7ASD3aNiwoWrWrKlVq1ZlOY7aDQC5R6FChdSlSxd9/PHHCgsLy/TOiNRuALi9Mj4dxUIxMTHy8PCQj4+P1VEAAA6KiYmRJOXPn9/iJAAAR1G7AcA5xcTEULsBwMmk7Xvny5fP4iQAcPeypCGanJysBQsWyBhjt3zDhg0KDg5Wly5d2LkHgFxo6dKlunr1qt2yM2fOaMqUKQoICLDdRhcAkHts3rxZJ06csFuWkJCgsWPHyt3dXU8++aRFyQAAmQkLC9OWLVvSLZ8+fbrCwsLsHj8EAMg95s2bp5SUFLtlO3fu1I8//qgWLVqoZMmSFiUDAFhyy1w3NzctXbpUr7/+umrUqKEiRYro6NGj+v3339W1a1fNmjXLilgAgBs4fvy4goKCVL58eQUGBurs2bNav369atSooSVLlnCmIwDkQomJierQoYMKFCigSpUqKTY2Vtu2bVNqaqr+97//qUGDBlZHBABcx8vLS2+99ZYiIyNVvXp1eXl5ae/evTp69Khee+01vfLKK1ZHBABk4LffftMbb7yh6tWrq1ixYjp+/Lg2b96sxx57TN98843V8QDgrmZJQ9TDw0Pff/+9zp07p127dun06dPq3LmzGjZsqICAACsiAQAc8OKLL+qZZ55RSEiIjh8/rjx58uiDDz5Q7dq1rY4GAMjEo48+qtDQUO3evVsHDx5UcnKyRo0apUaNGsnLy8vqeACADAQEBGj16tX6+++/FRoaqujoaPXp00f333+/ChcubHU8AEAmvvzyS124cEE7d+5URESEOnTooO+++07lypWzOhoA3PUsaYim8ff3V9u2ba2MAADIprx586pZs2Zq1qyZ1VEAAA5yc3NTvXr1VK9ePaujAACyoWLFiqpYsaLVMQAA2VC0aFG1bt3a6hgAgOtY8gxRAAAAAAAAAAAAALgTaIgCAAAAAAAAAAAAcFk0RAEAAAAAAAAAAAC4LBqiAAAAAAAAAAAAAFwWDVEAAAAAAAAAAAAALouGKAAAAAAAAAAAAACXRUMUAAAAAAAAAAAAgMuiIQoAAAAAAAAAAADAZdEQBQAAAAAAAAAAAOCyaIgCAAAAAAAAAAAAcFk0RAEAAAAAAAAAAAC4LBqiAAAAAAAAAAAAAFwWDVEAAAAAAAAAAAAALouGKAAAAAAAAAAAAACXRUMUAAAAAAAAAAAAgMuiIQoAAAAAAAAAAADAZdEQBQAAAAAAAAAAAOCyaIgCAAAAAAAAAAAAcFk0RAEAAAAAAAAAAAC4LBqiAAAAAAAAAAAAAFwWDVEAAAAAAAAAAAAALouGKAAAAAAAAAAAAACXRUMUAAAAAAAAAAAAgMuiIQoAAAAAAAAAAADAZdEQBQAAAAAAAAAAAOCyaIgCAAAAAAAAAAAAcFk0RAEAAAAAAAAAAAC4LBqiAAAAAAAAAAAAAFwWDVEAAAAAAAAAAAAALouGKAAAAAAAAAAAAACXRUMUAAAAAAAAAAAAgMuiIQoAAAAAAAAAAADAZdEQBQAAAAAAAAAAAOCyPK0OkFMSEhIkSdGfDZebp5fFaZxfavQZSdL5/7SzOIlrYD5zDnOZs1Ivnpb0fzXUCrbPnv+G5EH9Ri4Sc14pbtQb5D7UbgBwQleiJFG7AcDpWFy/OeYNANmX2XETl2mIhoeHS5LMpUgZi7O4ktTz4VZHcCnMZ85hLnNWeHi46tWrZ9lnS5KuXrDk84Ebod4gt6J2A4DzoXYDgHOyqn5zzBsAbt71tdvNGOMStfTSpUvasGGDypQpIx8fH6vjZOro0aPq3LmzlixZosqVK1sdx+kxnzmHucxZzjKfCQkJCg8PV7NmzVS4cGFLMjhD/XaWf09nwXzmLOYz5zjLXFK7Hecs/6bOgLnMWcxnznKG+aR2O84Z/j2dCfOZc5jLnOUs82l1/aZ2352Yz5zFfOYcZ5nLzGq3y1whWrhwYXXq1MnqGA6rXLmyatWqZXUMl8F85hzmMmc5w3xadYZ6Gmeq387w7+lMmM+cxXzmHGeYS2p39jjDv6mzYC5zFvOZs3L7fFK7sye3/3s6G+Yz5zCXOcsZ5tPK+k3tvrsxnzmL+cw5zjCXGdVudwtyAAAAAAAAAAAAAMAdQUMUAAAAAAAAAAAAgMuiIQoAAAAAAAAAAADAZdEQvcOKFy+ucePGqXjx4lZHcQnMZ85hLnMW8+la+PfMWcxnzmI+cw5z6Xr4N805zGXOYj5zFvPpWvj3zFnMZ85hLnMW8+la+PfMWcxnzmI+c46zz6WbMcZYHQIAAAAAAAAAAAAAbgeuEAUAAAAAAAAAAADgsmiIAgAAAAAAAAAAAHBZNEQBAAAAAAAAAAAAuCwaogAAAAAAAAAAAABclqfVAe4WsbGx+uSTT7RhwwalpKSoYcOGGjVqlIoVK2Z1NKdjjNHvv/+u+fPna/v27apQoYLmzp1rdSynZIzR+vXrtWjRIh06dEgFChTQvffeq+eee05Fixa1Op7TSU1N1YoVK/Tzzz/r6NGjKlSokIKCgvTMM8+oRIkSVsfDTZo7d64WLlyoixcvqmrVqnr22Wd17733Wh3LKf3999+aP3++Vq5cqWvXrmn58uXy8/OzOpZTOnTokL7//nvt3btXiYmJqlKlioYMGaLatWtbHc0p7d27V3PmzNG+ffvk5uamypUra+DAgfx/3Ylt27ZNX3zxhY4fP64SJUroySefVOfOna2O5ZSio6O1ZMkSLVq0SFFRURo/frxat25tdSyndOHCBX3//ffavn27zp49q3LlyqlLly7q0KGD1dGc0tmzZ/XNN99ox44dio6OVtmyZfX444+rffv2cnNzszoebkJERIQ+/vhj7d69W3ny5FHLli317LPPytvb2+poTicpKUmrV6/W/PnzdfDgQbVr105vvvmm1bGcUmJiopYsWaJVq1bp+PHj8vf3V9OmTTV48GD5+PhYHc/pXLt2TfPmzdO6det08uRJlShRQg8++KAGDBigfPnyWR0PN+HatWuaPn261qxZo8TERNWtW1cvvfSSSpUqZXU0p7Rr1y7Nnz9fmzdvVtGiRfXzzz9bHclpbdmyRT/99JP++usv+fj4qHbt2nr++edVsmRJq6M5pTVr1mjRokU6fPiwChQooDp16uiZZ55RYGCg1dGyhStE74CYmBg1adJE33//vYYMGaJRo0Zpw4YNql+/vs6cOWN1PKfTsmVLjRo1SmXLltWpU6cUGhpqdSSn1adPH7Vq1UrGGL388svq1auXli9frkqVKikkJMTqeE6nb9++mjNnjho1aqQ33nhDnTt31oIFC1SlShXt2rXL6ni4CYMHD9awYcPUokULjRs3TsYYNWjQQKtXr7Y6mtOZNGmSWrVqpUuXLsnX11fbt29XYmKi1bGc0uzZs1W9enXt3LlT/fr10wsvvKDLly/r3nvv1bRp06yO53Rmzpyp4cOHKyAgQKNGjdIzzzyjkydPKigoSDNmzLA6Hm7Cjz/+qAceeEB+fn4aP368GjdurJ49e3Ig+CZs2bJF1atX18aNG1W9enVt375dUVFRVsdySseOHVNAQIC++OILPfLII3r99ddVoUIF9ejRQ127dpUxxuqITuXQoUNq1qyZ4uPj1bdvX7366qsq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3NysjgcHcdwEzmTSpElavHix+vfvr/bt21sdxymVKFFCU6dO1bVr17R3715NnjxZffv21fLly1WyZEmr48FB1G44k02bNumll15S9erVNXHiRKvjOK3x48crLi5OYWFhmjZtmoYOHaoSJUrowQcftDqaw2iI3maFChWSlPF98GNiYuzGAFbauHGjnnjiCVWtWlXLly/nrOpbkPZc1gceeECPP/64atSooaefflqhoaEWJ0N2FCpUiNqNXO/s2bNq0aKFLl26pJUrV6pq1apWR3Ja/567xx9/XE888YSeffZZtW3bNt1zo5B7/Xvfu2DBgnbrYmJiVLhwYQtSAfZSUlLUu3dv/frrr3r//ffVu3dvqyM5rRIlSthuWdmmTRuVK1dOzz77rFq3bq1evXpZnA6O4rgJnMV///tfjR07Vu3bt9eXX35pdRynlSdPHjVu3FiS9PDDD6tVq1aqVauWxo4dq6+++sridHAUtRvOYteuXWrfvr1Kly6tVatWZfg8TDimbt26kqSmTZvqiSee0L333qs+ffooLCzM2mDZwLXBt1n58uXl7e2tv//+O926tGXVqlW707EAO7///rvatWunsmXL6rfffuMM9Rzk6+urpk2bau/evUpISLA6DrKhWrVq1G7kaufPn1fz5s0VERGhZcuW6YEHHrA6kktp06aNEhMTOZnFyaTV5uvrd1JSkiIiIqjdsFxqaqoGDBig+fPna9KkSXrllVesjuRS0h5TsWPHDouTIDsyq91py/z9/TmhBZabPXu27WS5n376SV5eXlZHchnVq1dX+fLlqd1Opnjx4vLz8+O4CXK1vXv3qlWrVipSpIh+++03lSlTxupILiNPnjx6+OGHdeLECZ07d87qOA6jIXqbeXl5qUWLFlq/fr2Sk5Pt1q1atUq1a9fm/4iw1K5du9SmTRuVLl1a69at4/Ykt8GJEyfk5+fHVbdOpm3btrpw4YJ2795tt3zVqlVyd3dX69atLUoGSJcuXVKrVq10/Phx/fLLL2rWrJnVkVzOiRMnJEmlSpWyOAmyI60Zsnr1arvlGzZsUEJCgh577DErYgGSJGOMhg4dqjlz5mjixIk8ouI2oHY7p6CgIJUsWTJd7b569aq2bt1K7YblfvjhBw0aNEitW7fW4sWL+ds+hyUkJCgyMpLa7YTatGmjrVu3Ki4uzm75qlWrVKZM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kZQux19//WUkmdmzZ9uWLV682EgyGzduNMOGDTNFihQx7u7uplmzZiYqKsokJiaaoUOH2pYHBQWZo0eP2m03bRubN282o0aNMkWKFDGenp6mQoUKZt26dTecCwDOz8PDw7z66qt2y+677z5bzS1cuLDx9vY27du3NydOnDDGGHP8+HETEBBgJBlfX1/b2CFDhmS5LqvPvHbtmnnttddMiRIljLe3t/H19TVNmzY1v//+u92YMWPGmGLFipl8+fIZLy8vU7duXbNhw4Ybfk9Htn/hwgXTp08fky9fPuPr62s8PT1Ny5YtzV9//ZXlnGVUo9MEBASYp556yvY6JibGSDITJkwwX375pSlZsqTx8fExFSpUMNu2bTPGGPP555+bkiVLmjx58hh/f3/z888/223z39uYM2eOKV26tMmXL58pWLCg+eijj244FwCcX+vWrU39+vXtlo0cOdJWc/39/Y2Hh4epW7eu+e2332xjGjdubLy9vY23t7dtbM2aNW+4LrPPNMaY7777ztSsWdO4u7ubQoUKmYoVK5pvvvnGbsy3335rqlWrZjw9PU2BAgVMqVKlzPTp0x36rjfafkpKipk4caLx9/c3+fLlM56enqZmzZpm6dKlN5yz62t0mn79+pkSJUrYLWvUqJFp1qyZ2b59u6levbopUKCAKVCggPnvf/9rjDFm69atpmbNmsbX19fkyZPHvPnmm+m2m7aNPXv2mDp16piCBQsaT09P07t3bxMfH+/QfABwXh988IGRZKKjo23LFi1aZKu5pUuXNl5eXiYwMNBMnTrVNuaVV14xBQsWNJJM6dKlbeNDQ0OzXJfZZxpjzPbt282jjz5qPD09TaFChYyfn58ZM2aMiY2NtRvz8MMP28bkz5/fDBs2zMTFxd3wuzqy/SVLlphatWoZDw8Pky9fPuPv728mTpxoUlJSspyzjGq0Mf8cX5Jk/vzzT9uysWPHGknmzJkzpm3btqZgwYLG3d3dPP300yYpKcmcO3fOtGnTxhQsWNC4ubmZDh06mJiYGLvtpm0jKirKdOnSxRQqVMi4ubmZhg0bmmPHjt1wLgA4t927dxtJZsGCBbZl586dszvmnXaMeMiQIebq1avGGGOWLl1qihcvbiSZokWL2sZOnz49y3WZfaYxxkRGRpq+ffsaX19f22c+8cQT5vjx47YxZ8+eNb179zb5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",
+      "text/plain": [
+       "<Figure size 1860x408 with 5 Axes>"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "palette = ListedColormap([\n",
+    "    \"#1696d2\", \"#0077b6\", \"#00a676\", \"#f59f00\",\n",
+    "    \"#7b2cbf\", \"#e76f51\", \"#577590\", \"#90be6d\",\n",
+    "])\n",
+    "\n",
+    "def color_regions(labels):\n",
+    "    regions = sorted(np.unique(labels))\n",
+    "    neighbors = {region: set() for region in regions}\n",
+    "    for row in range(L):\n",
+    "        for column in range(L):\n",
+    "            here = labels[row, column]\n",
+    "            if row + 1 < L:\n",
+    "                there = labels[row + 1, column]\n",
+    "                if here != there:\n",
+    "                    neighbors[here].add(there)\n",
+    "                    neighbors[there].add(here)\n",
+    "            if column + 1 < L:\n",
+    "                there = labels[row, column + 1]\n",
+    "                if here != there:\n",
+    "                    neighbors[here].add(there)\n",
+    "                    neighbors[there].add(here)\n",
+    "    assigned = {}\n",
+    "    for region in regions:\n",
+    "        used = {assigned[value] for value in neighbors[region] if value in assigned}\n",
+    "        assigned[region] = next(color for color in range(palette.N) if color not in used)\n",
+    "    return np.vectorize(assigned.__getitem__)(labels)\n",
+    "\n",
+    "if leaf_to_input.shape != (L * L,) or not np.array_equal(np.sort(leaf_to_input), np.arange(L * L)):\n",
+    "    raise ValueError(\"the returned order is not a permutation of the 4x4 public sites\")\n",
+    "leaf_position = input_to_leaf\n",
+    "levels = int(np.log2(leaf_to_input.size)) + 1\n",
+    "fig, axes = plt.subplots(1, levels, figsize=(3.1 * levels, 3.4), constrained_layout=True)\n",
+    "for level, axis in enumerate(axes):\n",
+    "    labels = (leaf_position // (2**level)).reshape(L, L)\n",
+    "    colors = np.zeros_like(labels) if level == 0 else color_regions(labels)\n",
+    "    axis.imshow(colors, cmap=palette, vmin=0, vmax=palette.N - 1, origin=\"upper\")\n",
+    "    for boundary in range(L + 1):\n",
+    "        axis.plot([-0.5, L - 0.5], [boundary - 0.5, boundary - 0.5], color=\"black\", linewidth=1.0) if boundary in (0, L) else None\n",
+    "        axis.plot([boundary - 0.5, boundary - 0.5], [-0.5, L - 0.5], color=\"black\", linewidth=1.0) if boundary in (0, L) else None\n",
+    "    for row in range(L):\n",
+    "        for column in range(L - 1):\n",
+    "            if labels[row, column] != labels[row, column + 1]:\n",
+    "                axis.plot([column + 0.5, column + 0.5], [row - 0.5, row + 0.5], color=\"black\", linewidth=1.0)\n",
+    "    for row in range(L - 1):\n",
+    "        for column in range(L):\n",
+    "            if labels[row, column] != labels[row + 1, column]:\n",
+    "                axis.plot([column - 0.5, column + 0.5], [row + 0.5, row + 0.5], color=\"black\", linewidth=1.0)\n",
+    "    axis.set_title(f\"Step {level}\")\n",
+    "    axis.set_xticks(range(L))\n",
+    "    axis.set_yticks(range(L))\n",
+    "    axis.set_xlabel(\"lattice column\")\n",
+    "    axis.set_ylabel(\"lattice row\" if level == 0 else \"\")\n",
+    "plt.show()"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.12"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

examples/networkx_system.py

@@ -0,0 +1,16 @@
+# Copyright (c) 2026 Simulacra Research Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+from pathlib import Path
+
+import networkx as nx
+
+from hamiltonzero import SpinHamiltonian
+from hamiltonzero.data import save_system
+
+
+graph = nx.path_graph(8)
+nx.set_edge_attributes(graph, 1.0, "J")
+nx.set_node_attributes(graph, 0.0, "h")
+system = SpinHamiltonian.from_networkx(graph)
+save_system(Path("outputs/systems/chain_8.json"), system)

examples/train.json

@@ -0,0 +1,6 @@
+{
+  "systems": "datasets/train/foundation_5000.jsonl",
+  "output": "outputs/foundation.eqx",
+  "steps": 1000,
+  "n_max": 64
+}

pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hamiltonzero"
+version = "0.1.0"
+description = "Compiled neural wavefunctions for quantum spin systems"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "Apache-2.0 AND MIT"
+license-files = [
+    "LICENSE",
+    "NOTICE",
+    "THIRD_PARTY_NOTICES.md",
+    "third_party/folx/LICENSE",
+    "third_party/jax/LICENSE",
+    "third_party/kfac_jax/LICENSE",
+]
+dependencies = [
+    "absl-py>=2.5",
+    "distrax>=0.1.9",
+    "dm-tree>=0.1.10",
+    "equinox==0.13.6",
+    "immutabledict>=4.3",
+    "jax @ git+https://github.com/TakeOver/jax.git@79f82535b15a444516d4a5e2beb71d283665b2ff",
+    "jaxlib==0.11.0",
+    "jaxtyping==0.3.9",
+    "networkx>=3.5",
+    "numpy>=2.3",
+    "optax>=0.2.8",
+    "packaging>=26",
+    "typing-extensions>=4.15",
+]
+
+[project.optional-dependencies]
+notebooks = [
+    "jupyterlab>=4.4",
+    "matplotlib>=3.10",
+]
+
+[project.scripts]
+hamiltonzero = "hamiltonzero.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["hamiltonzero*", "kfac_jax*"]

src/hamiltonzero/__init__.py

@@ -0,0 +1,40 @@
+# Copyright (c) 2026 Simulacra Research Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+from .hamiltonian import SpinHamiltonian
+from .inference import (
+    CompiledOrder,
+    EnergySamples,
+    PreparedInference,
+    burn_in,
+    energy,
+    prepare,
+    spin,
+    step,
+)
+from .renyi2 import (
+    BasisSamplerState,
+    Renyi2Result,
+    burn_in_basis,
+    measure_renyi2,
+    renyi2_purity,
+    step_basis,
+)
+
+__all__ = [
+    "BasisSamplerState",
+    "CompiledOrder",
+    "EnergySamples",
+    "PreparedInference",
+    "Renyi2Result",
+    "SpinHamiltonian",
+    "burn_in",
+    "burn_in_basis",
+    "energy",
+    "measure_renyi2",
+    "prepare",
+    "renyi2_purity",
+    "spin",
+    "step",
+    "step_basis",
+]

src/hamiltonzero/checkpoint.py

@@ -0,0 +1,65 @@
+# Copyright (c) 2026 Simulacra Research Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Literal, TypeVar
+
+import equinox as eqx
+
+
+T = TypeVar("T")
+CheckpointKind = Literal["router", "compiled_finetune"]
+
+
+def _metadata_path(path: str | Path) -> Path:
+    source = Path(path)
+    return source.with_name(source.name + ".json")
+
+
+def save_model(
+    path: str | Path,
+    model: object,
+    *,
+    kind: CheckpointKind | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> None:
+    destination = Path(path)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    eqx.tree_serialise_leaves(destination, model)
+    if kind is not None:
+        payload = {"kind": kind, **(metadata or {})}
+        _metadata_path(destination).write_text(
+            json.dumps(payload, indent=2, sort_keys=True) + "\n"
+        )
+
+
+def load_model(path: str | Path, template: T) -> T:
+    return eqx.tree_deserialise_leaves(Path(path), template)
+
+
+def load_model_metadata(path: str | Path) -> dict[str, Any] | None:
+    source = _metadata_path(path)
+    return json.loads(source.read_text()) if source.exists() else None
+
+
+def save_mcmc(path: str | Path, state: object) -> None:
+    destination = Path(path)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    eqx.tree_serialise_leaves(destination, state)
+
+
+def load_mcmc(path: str | Path, template: T) -> T:
+    return eqx.tree_deserialise_leaves(Path(path), template)
+
+
+__all__ = [
+    "CheckpointKind",
+    "load_mcmc",
+    "load_model",
+    "load_model_metadata",
+    "save_mcmc",
+    "save_model",
+]

src/hamiltonzero/cli.py

@@ -0,0 +1,69 @@
+# Copyright (c) 2026 Simulacra Research Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import json
+from pathlib import Path
+
+from .config import load_config
+
+
+def _write_metric(path: Path, metric) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a", encoding="utf-8") as stream:
+        stream.write(
+            json.dumps(dataclasses.asdict(metric), separators=(",", ":")) + "\n"
+        )
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="hamiltonzero")
+    commands = parser.add_subparsers(dest="mode", required=True)
+    for mode in ("train", "finetune"):
+        command = commands.add_parser(mode)
+        command.add_argument("config", type=Path)
+        command.add_argument("--reuse-mcmc", type=Path)
+    evaluate = commands.add_parser("eval")
+    evaluate.add_argument("config", type=Path)
+    pathway = evaluate.add_mutually_exclusive_group()
+    pathway.add_argument("--contest", action="store_true")
+    pathway.add_argument("--large-n", action="store_true")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = _parser().parse_args(argv)
+    config = load_config(args.config, args.mode)
+    if args.mode == "eval":
+        from .modes.eval import run
+
+        if args.contest or args.large_n:
+            config = dataclasses.replace(
+                config,
+                contest=bool(args.contest),
+                large_n=bool(args.large_n),
+            )
+        run(config)
+        return
+    if args.reuse_mcmc is not None:
+        config = dataclasses.replace(
+            config,
+            mcmc=dataclasses.replace(config.mcmc, reuse_mcmc=args.reuse_mcmc),
+        )
+    metrics_path = config.output.with_name(config.output.name + ".metrics.jsonl")
+    sink = lambda metric: _write_metric(metrics_path, metric)
+    if args.mode == "train":
+        from .modes.train import run_train
+
+        run_train(config, metric_sink=sink)
+    else:
+        from .modes.finetune import run_finetune
+
+        run_finetune(config, metric_sink=sink)
+
+
+if __name__ == "__main__":
+    main()

src/hamiltonzero/compiled/__init__.py

@@ -0,0 +1,2 @@
+# Copyright (c) 2026 Simulacra Research Inc.
+# SPDX-License-Identifier: Apache-2.0

src/hamiltonzero/compiled/api.py

@@ -0,0 +1,34 @@
+# Copyright (c) 2026 Simulacra Research Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import jax
+import jax.numpy as jnp
+
+from .tree import compile_physical_tree_reference
+from .trunk import bind_shared_kernel, compile_shared_trunk
+from .types import CompiledWaveFunction, CompiledWaveFunctions
+
+
+def compile_wavefunction(model, context, perm) -> CompiledWaveFunction:
+    trunk = compile_shared_trunk(model, context)
+    tree = compile_physical_tree_reference(model, trunk, perm)
+    return CompiledWaveFunction(kernel=bind_shared_kernel(model), tree=tree)
+
+
+def compile_wavefunctions(model, context, perms) -> CompiledWaveFunctions:
+    trunk = compile_shared_trunk(model, context)
+    perms = jnp.asarray(perms, dtype=jnp.int32)
+    trees = jax.vmap(lambda perm: compile_physical_tree_reference(model, trunk, perm))(
+        perms
+    )
+    return CompiledWaveFunctions(kernel=bind_shared_kernel(model), trees=trees)
+
+
+def select_compiled_wavefunction(
+    candidates: CompiledWaveFunctions,
+    winner,
+) -> CompiledWaveFunction:
+    tree = jax.tree_util.tree_map(lambda value: value[winner], candidates.trees)
+    return CompiledWaveFunction(kernel=candidates.kernel, tree=tree)

src/hamiltonzero/compiled/execute.py

@@ -0,0 +1,118 @@
+# Copyright (c) 2026 Simulacra Research Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from typing import Any
+
+import jax
+import jax.numpy as jnp
+
+from hamiltonzero.model import normalize_leaf_carriers
+
+from .types import CARRY_LEFT, CARRY_RIGHT, EMPTY, MERGE
+
+
+def _single(values: tuple[Any, ...], name: str) -> Any:
+    if len(values) != 1:
+        raise ValueError(
+            f"compiled HT executor requires exactly one {name}; got {len(values)}"
+        )
+    return values[0]
+
+
+def _factorized_apply(factor: Any, h: jax.Array, x: jax.Array) -> jax.Array:
+    odd_dtype = jnp.float32
+    x_compute = x if x.dtype == odd_dtype else x.astype(odd_dtype)
+    V = factor.V if factor.V.dtype == odd_dtype else factor.V.astype(odd_dtype)
+    U = factor.U if factor.U.dtype == odd_dtype else factor.U.astype(odd_dtype)
+    mixed = (x_compute @ V) * h
+    mixed = mixed if mixed.dtype == odd_dtype else mixed.astype(odd_dtype)
+    return mixed @ U
+
+
+def _compiled_quadrilinear_merge(
+    T: jax.Array,
+    u_a: jax.Array,
+    u_b: jax.Array,
+) -> jax.Array:
+    from hamiltonzero.energy import custom_lap_active, quadrilinear_merge_p
+
+    odd_dtype = jnp.float32
+    T = T if T.dtype == odd_dtype else T.astype(odd_dtype)
+    u_a = u_a if u_a.dtype == odd_dtype else u_a.astype(odd_dtype)
+    u_b = u_b if u_b.dtype == odd_dtype else u_b.astype(odd_dtype)
+    if custom_lap_active():
+        return quadrilinear_merge_p.bind(T, u_a, u_b)
+    G, d_r, _, _ = T.shape
+    leading = u_a.shape[:-1]
+    u_a_flat = u_a.reshape((-1, G, d_r))
+    u_b_flat = u_b.reshape((-1, G, d_r))
+    out_flat = jnp.einsum("ijkl,Bik,Bil->Bij", T, u_a_flat, u_b_flat)
+    return out_flat.reshape((*leading, G * d_r))
+
+
+def _opcode_gates(opcodes: jax.Array, dtype: jnp.dtype) -> tuple[jax.Array, ...]:
+    both = (opcodes == MERGE).astype(dtype)
+    left = (opcodes == CARRY_LEFT).astype(dtype)
+    right = (opcodes == CARRY_RIGHT).astype(dtype)
+    return both, left, right
+
+
+def _gate_reference(
+    candidate: jax.Array,
+    left_value: jax.Array,
+    right_value: jax.Array,
+    opcodes: jax.Array,
+    *,
+    feature_axis: bool,
+) -> jax.Array:
+    both, left, right = _opcode_gates(opcodes, candidate.dtype)
+    if feature_axis:
+        both, left, right = both[..., None], left[..., None], right[..., None]
+    pad = candidate.ndim - both.ndim
+    shape = (1,) * pad + both.shape
+    both, left, right = both.reshape(shape), left.reshape(shape), right.reshape(shape)
+    return both * candidate + left * left_value + right * right_value
+
+
+def execute_wavefunction(kernel: Any, tree: Any, q_routed: jax.Array):
+    if len(tree.leaf_combiner_h) != 0 or len(tree.readout_combiner_h) != 0:
+        raise ValueError("single-head compiled HT executor does not accept combiners")
+    if len(tree.merge_h) != len(tree.opcodes):
+        raise ValueError("merge_h and opcodes must have one entry per tree level")
+    q_weight = kernel.q_to_odd.weight
+    leaf_factor = _single(kernel.leaf_factors, "leaf factor")
+    merge_factor = _single(kernel.merge_factors, "merge factor")
+    readout_factor = _single(kernel.readout_factors, "readout factor")
+    leaf_h = _single(tree.leaf_h, "leaf conditioner")
+    readout_h = _single(tree.readout_h, "readout conditioner")
+    odd_dtype = jnp.float32
+    q_compute = q_routed if q_routed.dtype == odd_dtype else q_routed.astype(odd_dtype)
+    q_weight = q_weight if q_weight.dtype == odd_dtype else q_weight.astype(odd_dtype)
+    z = q_compute @ q_weight
+    u_raw = _factorized_apply(leaf_factor, leaf_h, z)
+    u, log_rms = normalize_leaf_carriers(u_raw)
+    s = jnp.zeros(u.shape[:-1], dtype=odd_dtype)
+    s = s + log_rms.astype(s.dtype)
+    for h_level, opcodes in zip(tree.merge_h, tree.opcodes, strict=True):
+        if u.shape[-2] != 2 * h_level.shape[-2]:
+            raise ValueError("compiled merge level has incompatible shrinking shape")
+        u_left, u_right = u[..., 0::2, :], u[..., 1::2, :]
+        s_left, s_right = s[..., 0::2], s[..., 1::2]
+        raw = _compiled_quadrilinear_merge(kernel.merge_T, u_left, u_right)
+        out = raw + _factorized_apply(merge_factor, h_level, raw)
+        scale = jnp.sqrt(jnp.mean(out * out, axis=-1) + kernel.merge_eps)
+        candidate_u = out / scale[..., None]
+        candidate_s = s_left + s_right + jnp.log(scale)
+        u = _gate_reference(candidate_u, u_left, u_right, opcodes, feature_axis=True)
+        s = _gate_reference(candidate_s, s_left, s_right, opcodes, feature_axis=False)
+    if u.shape[-2] != 1:
+        raise ValueError("compiled tree did not reduce to one root")
+    u_root = u[..., 0, :]
+    s_root = s[..., 0]
+    psi = _factorized_apply(readout_factor, readout_h, u_root)
+    psi_re, psi_im = psi[..., 0], psi[..., 1]
+    log_abs = 0.5 * jnp.log(psi_re * psi_re + psi_im * psi_im) + s_root
+    phase = jnp.arctan2(psi_im, psi_re)
+    return log_abs, phase

src/hamiltonzero/compiled/model.py

@@ -0,0 +1,456 @@
+# Copyright (c) 2026 Simulacra Research Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from typing import Any
+
+import equinox as eqx
+import jax
+import jax.numpy as jnp
+from jaxtyping import Array
+
+from hamiltonzero.model import (
+    normalize_leaf_carriers,
+    quadrilinear_merge,
+    tagged_dense_no_bias,
+)
+from hamiltonzero.optim import register_scale_and_shift
+
+from .execute import (
+    _compiled_quadrilinear_merge,
+    _factorized_apply,
+    _gate_reference,
+    _single,
+)
+from .types import EMPTY, MERGE, OPCODE_DTYPE, CompiledTree, SharedKernel, level_widths
+
+
+def _scale_tag(y_flat, x_flat, scale_param, *, tag_id: str):
+    return register_scale_and_shift(
+        y_flat,
+        x_flat,
+        scale=scale_param,
+        tag_id=tag_id,
+    )
+
+
+class CompiledFinetuneWaveFunction(eqx.Module):
+    kernel: SharedKernel
+    leaf_h: Array
+    merge_h: Array
+    readout_h: Array
+    perm: Array
+    inv_perm: Array
+    leaf_real: Array
+    opcodes: Array
+    n_sites: int = eqx.field(static=True)
+    r_leaf: int = eqx.field(static=True)
+    r_merge: int = eqx.field(static=True)
+
+    def leaf_h_rows(self) -> Array:
+        return self.leaf_h.reshape(self.n_sites, self.r_leaf)
+
+    def merge_h_level(self, level: int, width: int) -> Array:
+        return self.merge_h[level, : width * self.r_merge].reshape(width, self.r_merge)
+
+    @classmethod
+    def from_compiled(cls, kernel: SharedKernel, tree: CompiledTree):
+        leaf_h = _single(tree.leaf_h, "leaf conditioner")
+        readout_h = _single(tree.readout_h, "readout conditioner")
+        n_sites = int(tree.perm.shape[-1])
+        widths = level_widths(n_sites)
+        w_max = widths[0]
+        r_leaf = int(leaf_h.shape[-1])
+        r_merge = int(tree.merge_h[0].shape[-1])
+        merge_rows = []
+        opcode_rows = []
+        for width, h_l, ops_l in zip(widths, tree.merge_h, tree.opcodes, strict=True):
+            if h_l.shape[-2] != width or ops_l.shape[-1] != width:
+                raise ValueError(
+                    f"level width mismatch: expected {width}, got "
+                    f"{h_l.shape[-2]}/{ops_l.shape[-1]}"
+                )
+            pad = w_max - width
+            merge_rows.append(
+                jnp.pad(h_l, ((0, pad), (0, 0))).reshape(-1) if pad else h_l.reshape(-1)
+            )
+            opcode_rows.append(
+                jnp.pad(ops_l, (0, pad), constant_values=EMPTY) if pad else ops_l
+            )
+        return cls(
+            kernel=kernel,
+            leaf_h=leaf_h.reshape(-1),
+            merge_h=jnp.stack(merge_rows),
+            readout_h=readout_h,
+            perm=tree.perm,
+            inv_perm=tree.inv_perm,
+            leaf_real=tree.leaf_real,
+            opcodes=jnp.stack(opcode_rows).astype(OPCODE_DTYPE),
+            n_sites=n_sites,
+            r_leaf=r_leaf,
+            r_merge=r_merge,
+        )
+
+    def as_compiled_tree(self) -> CompiledTree:
+        widths = level_widths(self.n_sites)
+        return CompiledTree(
+            perm=self.perm,
+            inv_perm=self.inv_perm,
+            leaf_real=self.leaf_real,
+            leaf_h=(self.leaf_h_rows(),),
+            leaf_combiner_h=(),
+            merge_h=tuple(
+                self.merge_h_level(i, width) for i, width in enumerate(widths)
+            ),
+            opcodes=tuple(self.opcodes[i, :width] for i, width in enumerate(widths)),
+            readout_h=(self.readout_h,),
+            readout_combiner_h=(),
+        )
+
+    def route_q(self, q: Array) -> Array:
+        return jnp.take(q, self.perm, axis=-2)
+
+    def param_counts(self) -> dict:
+        kernel_leaves = {
+            "q_to_odd": self.kernel.q_to_odd.weight.size,
+            "leaf_V": self.kernel.leaf_factors[0].V.size,
+            "leaf_U": self.kernel.leaf_factors[0].U.size,
+            "merge_T": self.kernel.merge_T.size,
+            "merge_V": self.kernel.merge_factors[0].V.size,
+            "merge_U": self.kernel.merge_factors[0].U.size,
+            "readout_V": self.kernel.readout_factors[0].V.size,
+            "readout_U": self.kernel.readout_factors[0].U.size,
+        }
+        tree_leaves = {
+            "leaf_h": self.leaf_h.size,
+            "merge_h": self.merge_h.size,
+            "readout_h": self.readout_h.size,
+        }
+        return {
+            "kernel": kernel_leaves,
+            "tree": tree_leaves,
+            "kernel_total": sum(kernel_leaves.values()),
+            "tree_total": sum(tree_leaves.values()),
+            "total": sum(kernel_leaves.values()) + sum(tree_leaves.values()),
+        }
+
+    def __call__(self, q: Array, ctx: Any = None, t: Any = 0.0):
+        del ctx, t
+        return self._forward_plain(q)
+
+    def _forward_plain(self, q: Array):
+        kernel = self.kernel
+        odd_dtype = jnp.float32
+        q_c = q if q.dtype == odd_dtype else q.astype(odd_dtype)
+        weight = kernel.q_to_odd.weight
+        weight = weight if weight.dtype == odd_dtype else weight.astype(odd_dtype)
+        z = q_c @ weight
+        u_raw = _factorized_apply(kernel.leaf_factors[0], self.leaf_h_rows(), z)
+        u, log_rms = normalize_leaf_carriers(u_raw)
+        s = jnp.zeros(u.shape[:-1], dtype=odd_dtype) + log_rms.astype(odd_dtype)
+        widths = level_widths(self.n_sites)
+        for level, width in enumerate(widths):
+            h_level = self.merge_h_level(level, width)
+            opcodes = self.opcodes[level, :width]
+            u_left, u_right = u[..., 0::2, :], u[..., 1::2, :]
+            s_left, s_right = s[..., 0::2], s[..., 1::2]
+            raw = _compiled_quadrilinear_merge(kernel.merge_T, u_left, u_right)
+            out = raw + _factorized_apply(kernel.merge_factors[0], h_level, raw)
+            scale = jnp.sqrt(jnp.mean(out * out, axis=-1) + kernel.merge_eps)
+            candidate_u = out / scale[..., None]
+            candidate_s = s_left + s_right + jnp.log(scale)
+            u = _gate_reference(
+                candidate_u, u_left, u_right, opcodes, feature_axis=True
+            )
+            s = _gate_reference(
+                candidate_s, s_left, s_right, opcodes, feature_axis=False
+            )
+        return self._readout(
+            _factorized_apply(kernel.readout_factors[0], self.readout_h, u[..., 0, :]),
+            s[..., 0],
+        )
+
+    def _readout(self, psi: Array, s_root: Array):
+        psi_re, psi_im = psi[..., 0], psi[..., 1]
+        log_abs = 0.5 * jnp.log(psi_re * psi_re + psi_im * psi_im) + s_root
+        return log_abs, jnp.arctan2(psi_im, psi_re)
+
+    def call_tagged(self, q: Array, ctx: Any = None, t: Any = 0.0):
+        del ctx, t
+        if q.ndim != 2:
+            raise ValueError(
+                f"call_tagged is per-walker: expected q [P, 4], got {q.shape}"
+            )
+        kernel = self.kernel
+        odd_dtype = jnp.float32
+        q_c = q if q.dtype == odd_dtype else q.astype(odd_dtype)
+        real = self.leaf_real
+        z = tagged_dense_no_bias(
+            kernel.q_to_odd.weight,
+            q_c,
+            tag_id="compiled.q_to_odd",
+            pathway="odd",
+            kfac_structural_mask=real,
+            kfac_scan_shared=False,
+            kfac_repeat_ndim=1,
+        )
+        leaf = kernel.leaf_factors[0]
+        vz = tagged_dense_no_bias(
+            leaf.V,
+            z,
+            tag_id="compiled.leaf.V",
+            pathway="odd",
+            kfac_structural_mask=real,
+            kfac_scan_shared=False,
+            kfac_repeat_ndim=1,
+        )
+        vz_flat = vz.reshape(-1)
+        mixed = _scale_tag(
+            vz_flat * self.leaf_h,
+            vz_flat,
+            self.leaf_h,
+            tag_id="compiled.leaf.h",
+        ).reshape(vz.shape)
+        u_raw = tagged_dense_no_bias(
+            leaf.U,
+            mixed,
+            tag_id="compiled.leaf.U",
+            pathway="odd",
+            kfac_structural_mask=real,
+            kfac_scan_shared=False,
+            kfac_repeat_ndim=1,
+        )
+        u, log_rms = normalize_leaf_carriers(u_raw)
+        s = jnp.zeros(u.shape[:-1], dtype=odd_dtype) + log_rms.astype(odd_dtype)
+        merge = kernel.merge_factors[0]
+        merge_T = kernel.merge_T
+        merge_eps = kernel.merge_eps
+
+        def level_body(carry, xs):
+            u_buffer, s_buffer = carry
+            h_level, opcodes = xs
+            u_left, u_right = u_buffer[0::2], u_buffer[1::2]
+            s_left, s_right = s_buffer[0::2], s_buffer[1::2]
+            merge_rows = opcodes == MERGE
+            raw = quadrilinear_merge(
+                merge_T,
+                u_left,
+                u_right,
+                tag_id="compiled.merge.T",
+                pathway="odd",
+                kfac_structural_mask=merge_rows,
+                kfac_scan_shared=True,
+                kfac_repeat_ndim=1,
+            )
+            vx = tagged_dense_no_bias(
+                merge.V,
+                raw,
+                tag_id="compiled.merge.V",
+                pathway="odd",
+                kfac_structural_mask=merge_rows,
+                kfac_scan_shared=True,
+                kfac_repeat_ndim=1,
+            )
+            vx_flat = vx.reshape(-1)
+            mixed_level = _scale_tag(
+                vx_flat * h_level,
+                vx_flat,
+                h_level,
+                tag_id="compiled.merge.h",
+            ).reshape(vx.shape)
+            correction = tagged_dense_no_bias(
+                merge.U,
+                mixed_level,
+                tag_id="compiled.merge.U",
+                pathway="odd",
+                kfac_structural_mask=merge_rows,
+                kfac_scan_shared=True,
+                kfac_repeat_ndim=1,
+            )
+            out = raw + correction
+            scale = jnp.sqrt(jnp.mean(out * out, axis=-1) + merge_eps)
+            candidate_u = out / scale[..., None]
+            candidate_s = s_left + s_right + jnp.log(scale)
+            u_next = _gate_reference(
+                candidate_u, u_left, u_right, opcodes, feature_axis=True
+            )
+            s_next = _gate_reference(
+                candidate_s, s_left, s_right, opcodes, feature_axis=False
+            )
+            return (
+                jnp.concatenate([u_next, jnp.zeros_like(u_next)], axis=0),
+                jnp.concatenate([s_next, jnp.zeros_like(s_next)], axis=0),
+            ), None
+
+        (u_buffer, s_buffer), _ = jax.lax.scan(
+            level_body,
+            (u, s),
+            (self.merge_h, self.opcodes),
+        )
+        readout = kernel.readout_factors[0]
+        vr = tagged_dense_no_bias(
+            readout.V,
+            u_buffer[0],
+            tag_id="compiled.readout.V",
+            pathway="odd",
+        )
+        mixed_readout = _scale_tag(
+            vr * self.readout_h,
+            vr,
+            self.readout_h,
+            tag_id="compiled.readout.h",
+        )
+        psi = tagged_dense_no_bias(
+            readout.U,
+            mixed_readout,
+            tag_id="compiled.readout.U",
+            pathway="odd",
+        )
+        return self._readout(psi, s_buffer[0])
+
+
+def _expand_stage(V, U, h_2d, new_rank: int, key):
+    old_rank = V.shape[-1]
+    if new_rank < old_rank:
+        raise ValueError(f"cannot shrink rank {old_rank} -> {new_rank}")
+    if new_rank == old_rank:
+        return V, U, h_2d
+    extra = new_rank - old_rank
+    key_u, key_h = jax.random.split(key)
+    v_new = jnp.zeros((*V.shape[:-1], extra), dtype=V.dtype)
+    u_new = jnp.std(U) * jax.random.normal(key_u, (extra, *U.shape[1:]), dtype=U.dtype)
+    h_new = jnp.std(h_2d) * jax.random.normal(
+        key_h, (*h_2d.shape[:-1], extra), dtype=h_2d.dtype
+    )
+    return (
+        jnp.concatenate([V, v_new], axis=-1),
+        jnp.concatenate([U, u_new], axis=0),
+        jnp.concatenate([h_2d, h_new], axis=-1),
+    )
+
+
+def expand_rank(
+    model: CompiledFinetuneWaveFunction,
+    *,
+    leaf_rank: int,
+    merge_rank: int,
+    key,
+) -> CompiledFinetuneWaveFunction:
+    key_leaf, key_merge = jax.random.split(jnp.asarray(key), 3)[:2]
+    kernel = model.kernel
+    leaf = kernel.leaf_factors[0]
+    merge = kernel.merge_factors[0]
+    n_sites = model.n_sites
+    max_width = n_sites // 2
+    n_levels = model.merge_h.shape[0]
+    leaf_h = model.leaf_h.reshape(n_sites, model.r_leaf)
+    merge_h = model.merge_h.reshape(n_levels, max_width, model.r_merge)
+    readout_h = model.readout_h
+    r_leaf, r_merge = model.r_leaf, model.r_merge
+    V, U, leaf_h = _expand_stage(leaf.V, leaf.U, leaf_h, int(leaf_rank), key_leaf)
+    leaf = eqx.tree_at(lambda factor: (factor.V, factor.U), leaf, (V, U))
+    r_leaf = int(leaf_rank)
+    V, U, merge_h = _expand_stage(merge.V, merge.U, merge_h, int(merge_rank), key_merge)
+    merge = eqx.tree_at(lambda factor: (factor.V, factor.U), merge, (V, U))
+    r_merge = int(merge_rank)
+    kernel = eqx.tree_at(
+        lambda value: (
+            value.leaf_factors,
+            value.merge_factors,
+        ),
+        kernel,
+        ((leaf,), (merge,)),
+    )
+    return CompiledFinetuneWaveFunction(
+        kernel=kernel,
+        leaf_h=leaf_h.reshape(-1),
+        merge_h=merge_h.reshape(n_levels, -1),
+        readout_h=readout_h,
+        perm=model.perm,
+        inv_perm=model.inv_perm,
+        leaf_real=model.leaf_real,
+        opcodes=model.opcodes,
+        n_sites=n_sites,
+        r_leaf=r_leaf,
+        r_merge=r_merge,
+    )
+
+
+def compile_finetune_model(
+    eager_model,
+    ctx_row,
+    *,
+    leaf_rank: int,
+    merge_rank: int,
+    physical_perm,
+    key,
+) -> CompiledFinetuneWaveFunction:
+    from .tree import compile_physical_tree_reference
+    from .trunk import bind_shared_kernel, compile_shared_trunk
+
+    shared_trunk = compile_shared_trunk(eager_model, ctx_row)
+    n_sites = int(shared_trunk.real_mask.shape[-1])
+    identity = jnp.arange(n_sites, dtype=jnp.int32)
+    tree = compile_physical_tree_reference(eager_model, shared_trunk, identity)
+    model = CompiledFinetuneWaveFunction.from_compiled(
+        bind_shared_kernel(eager_model), tree
+    )
+    model = expand_rank(
+        model,
+        leaf_rank=leaf_rank,
+        merge_rank=merge_rank,
+        key=key,
+    )
+    physical_perm = jnp.asarray(physical_perm, dtype=jnp.int32)
+    if physical_perm.shape != (n_sites,):
+        raise ValueError(
+            f"physical_perm must have shape {(n_sites,)}, got {physical_perm.shape}"
+        )
+    model = eqx.tree_at(
+        lambda value: (value.perm, value.inv_perm),
+        model,
+        (
+            physical_perm,
+            jnp.argsort(physical_perm).astype(jnp.int32),
+        ),
+    )
+    return model
+
+
+def build_finetune_template_model(
+    eager_model,
+    n_sites: int,
+    *,
+    leaf_rank: int,
+    merge_rank: int,
+) -> CompiledFinetuneWaveFunction:
+    from .trunk import bind_shared_kernel
+
+    kernel = bind_shared_kernel(eager_model)
+    widths = level_widths(int(n_sites))
+    r_leaf = int(kernel.leaf_factors[0].V.shape[-1])
+    r_merge = int(kernel.merge_factors[0].V.shape[-1])
+    r_readout = int(kernel.readout_factors[0].V.shape[-1])
+    tree = CompiledTree(
+        perm=jnp.arange(n_sites, dtype=jnp.int32),
+        inv_perm=jnp.arange(n_sites, dtype=jnp.int32),
+        leaf_real=jnp.ones((n_sites,), dtype=jnp.bool_),
+        leaf_h=(jnp.ones((n_sites, r_leaf), dtype=jnp.float32),),
+        leaf_combiner_h=(),
+        merge_h=tuple(
+            jnp.ones((width, r_merge), dtype=jnp.float32) for width in widths
+        ),
+        opcodes=tuple(
+            jnp.full((width,), MERGE, dtype=OPCODE_DTYPE) for width in widths
+        ),
+        readout_h=(jnp.ones((r_readout,), dtype=jnp.float32),),
+        readout_combiner_h=(),
+    )
+    model = CompiledFinetuneWaveFunction.from_compiled(kernel, tree)
+    return expand_rank(
+        model,
+        leaf_rank=leaf_rank,
+        merge_rank=merge_rank,
+        key=jax.random.PRNGKey(0),
+    )

src/hamiltonzero/compiled/tree.py

@@ -0,0 +1,582 @@
+# Copyright (c) 2026 Simulacra Research Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from typing import Any
+
+import equinox as eqx
+import jax
+import jax.numpy as jnp
+
+from hamiltonzero.model import (
+    edge_merge_masked,
+    tagged_dense,
+    tagged_rms_eqx_style,
+    tree_active_clock_depth,
+    tree_depth_count_features,
+    tree_sphere,
+)
+
+from .types import (
+    CARRY_LEFT,
+    CARRY_RIGHT,
+    EMPTY,
+    MERGE,
+    CompiledTree,
+    LadderProjectionKernel,
+    PhysicalCompilerKernel,
+)
+
+
+def bind_physical_compiler_kernel(model: Any) -> PhysicalCompilerKernel:
+    leaf = eqx.tree_at(lambda x: (x.P_u.V, x.P_u.U), model.leaf, (None, None))
+    merge = eqx.tree_at(
+        lambda x: (x.T, x.output_hypernet.V, x.output_hypernet.U),
+        model.merge,
+        (None, None, None),
+    )
+    readout = eqx.tree_at(
+        lambda x: (x.output_hypernet.V, x.output_hypernet.U),
+        model.readout,
+        (None, None),
+    )
+    return PhysicalCompilerKernel(
+        contextualizer=model.readout_leaf_context,
+        global_fork=model.gladder_fork_phys,
+        leaf=leaf,
+        merge=merge,
+        readout=readout,
+        leaf_projection=LadderProjectionKernel(
+            model.gladder_to_gemb_w,
+            model.gladder_to_gemb_b,
+            model.gladder_gemb_ln_s,
+        ),
+        tree_pool=model.gladder_tree_pool,
+        tree_update=model.gladder_tree_update,
+        tree_projection_weight=model.gladder_tree_proj_w,
+        tree_projection_bias=model.gladder_tree_proj_b,
+        root_projection=LadderProjectionKernel(
+            model.gladder_root_proj_w,
+            model.gladder_root_proj_b,
+            model.gladder_root_ln_s,
+        ),
+    )
+
+
+def _project_global(
+    projection: LadderProjectionKernel,
+    value,
+    *,
+    dense_tag: str,
+    norm_tag: str,
+):
+    structural_active = jnp.asarray(True)
+    out = tagged_dense(
+        projection.weight,
+        projection.bias,
+        value,
+        tag_id=dense_tag,
+        pathway="even",
+        kfac_structural_mask=structural_active,
+        kfac_scan_shared=False,
+        kfac_repeat_ndim=0,
+    )
+    return tagged_rms_eqx_style(
+        projection.norm_scale,
+        out,
+        tag_id=norm_tag,
+        pathway="even",
+        kfac_structural_mask=structural_active,
+        kfac_scan_shared=False,
+        kfac_repeat_ndim=0,
+    )
+
+
+def compile_context_only_reduction(
+    *,
+    merge,
+    c_leaf,
+    leaf_real,
+    g_emb,
+    edges,
+    structural_mask,
+    gladder,
+    n_total=None,
+    clock_depth=None,
+    initial_counts=None,
+    level_offset: int = 0,
+    feature_n_levels=None,
+):
+    c = jnp.asarray(c_leaf)
+    m = jnp.asarray(leaf_real, dtype=c.dtype)
+    if c.shape[0] != m.shape[0]:
+        raise ValueError("c_leaf and leaf_real widths differ")
+    n = c.shape[0]
+    if n == 0 or n & (n - 1):
+        raise ValueError(f"context-only width must be a power of two, got {n}")
+    k = jnp.asarray(structural_mask, dtype=c.dtype)
+    if k.shape != m.shape:
+        raise ValueError("structural_mask and leaf_real widths differ")
+    n_total = jnp.sum(m) if n_total is None else n_total
+    feature_n_levels = (
+        tree_active_clock_depth(m) if feature_n_levels is None else feature_n_levels
+    )
+    clock_depth = tree_active_clock_depth(k) if clock_depth is None else clock_depth
+    counts = m if initial_counts is None else jnp.asarray(initial_counts, dtype=m.dtype)
+    if counts.shape != m.shape:
+        raise ValueError("initial_counts and leaf_real widths differ")
+    candidates = []
+    carried = []
+    depth_levels = []
+    opcode_levels = []
+    g_curr = g_emb
+    e_curr = edges
+    e_curr = tree_sphere(e_curr)
+    level = int(level_offset)
+    while c.shape[0] > 1:
+        c_a, c_b = c[0::2], c[1::2]
+        m_a, m_b = m[0::2], m[1::2]
+        k_a, k_b = k[0::2], k[1::2]
+        pair_count = c_a.shape[0]
+        pair_idx = jnp.arange(pair_count, dtype=jnp.int32)
+        both_struct = k_a * k_b
+        pair_base = jnp.maximum(
+            jnp.sum((k_a + k_b - k_a * k_b).astype(jnp.int32)),
+            jnp.asarray(2, dtype=jnp.int32),
+        )
+        cnt_a, cnt_b = counts[0::2], counts[1::2]
+        depth = tree_depth_count_features(
+            cnt_a, cnt_b, n_total, level, feature_n_levels, c.dtype
+        )
+        counts = cnt_a + cnt_b
+        depth_levels.append(depth)
+        d_edge = e_curr.shape[-1]
+        e_pairs = e_curr.reshape(pair_count, 2, pair_count, 2, d_edge)
+        sibling_lr = e_pairs[pair_idx, 0, pair_idx, 1]
+        sibling_rl = e_pairs[pair_idx, 1, pair_idx, 0]
+        level_active = jnp.any(both_struct.astype(bool))
+        g_level = g_curr
+        g_level = tagged_dense(
+            gladder[2],
+            gladder[3],
+            g_curr,
+            tag_id="gladder.tree.proj",
+            pathway="even",
+            kfac_structural_mask=level_active,
+            kfac_scan_shared=False,
+            kfac_repeat_ndim=0,
+        )
+
+        def candidate_one(ca, cb, elr, erl, dep, pidx, struct_active):
+            return merge.context_candidate(
+                ca,
+                cb,
+                g_level,
+                sibling_edge_lr=elr,
+                sibling_edge_rl=erl,
+                level_idx=jnp.int32(level),
+                pair_idx=pidx,
+                pair_base=pair_base,
+                clock_depth=clock_depth,
+                depth_feats=dep,
+                kfac_structural_mask=struct_active,
+                kfac_g_structural_mask=level_active,
+                kfac_scan_shared=False,
+            )
+
+        candidate = jax.vmap(candidate_one)(
+            c_a,
+            c_b,
+            sibling_lr,
+            sibling_rl,
+            depth,
+            pair_idx,
+            both_struct,
+        )
+        candidates.append(candidate)
+        gate_m_a, gate_m_b = k_a, k_b
+        gate_both = gate_m_a * gate_m_b
+        gate_a = gate_m_a * (1.0 - gate_m_b)
+        gate_b = (1.0 - gate_m_a) * gate_m_b
+        c = (
+            gate_both[:, None] * candidate
+            + gate_a[:, None] * c_a
+            + gate_b[:, None] * c_b
+        )
+        m = m_a + m_b - m_a * m_b
+        k = k_a + k_b - k_a * k_b
+        opcode_levels.append(
+            jnp.where(
+                m_a.astype(jnp.bool_),
+                jnp.where(m_b.astype(jnp.bool_), MERGE, CARRY_LEFT),
+                jnp.where(m_b.astype(jnp.bool_), CARRY_RIGHT, EMPTY),
+            ).astype(jnp.uint8)
+        )
+        attn_mask = both_struct
+        d_edge = e_curr.shape[-1]
+        e_blocks = e_curr.reshape(pair_count, 2, pair_count, 2, d_edge)
+        e00, e01 = e_blocks[:, 0, :, 0], e_blocks[:, 0, :, 1]
+        e10, e11 = e_blocks[:, 1, :, 0], e_blocks[:, 1, :, 1]
+
+        def edge_row(e0, e1, e2, e3, ma, mb, ka, kb, ca, cb):
+            return jax.vmap(
+                lambda x0, x1, x2, x3, mqa, mqb, kqa, kqb, cqa, cqb: edge_merge_masked(
+                    x0,
+                    x1,
+                    x2,
+                    x3,
+                    ma,
+                    mb,
+                    mqa,
+                    mqb,
+                    ca,
+                    cb,
+                    cqa,
+                    cqb,
+                    merge.edge_merge,
+                    k_2i=ka,
+                    k_2i1=kb,
+                    k_2j=kqa,
+                    k_2j1=kqb,
+                    kfac_scan_shared=False,
+                )[0]
+            )(e0, e1, e2, e3, m_a, m_b, k_a, k_b, c_a, c_b)
+
+        e_new = jax.vmap(edge_row)(e00, e01, e10, e11, m_a, m_b, k_a, k_b, c_a, c_b)
+        e_new = merge.tree_edge_fwl.apply_residual(
+            e_new, c, attn_mask, kfac_scan_shared=False
+        )
+        edge_keep = (both_struct[:, None] * both_struct[None, :]).astype(bool)
+        e_curr = jnp.where(edge_keep[..., None], e_new, e00)
+        e_curr = jnp.where(edge_keep[..., None], tree_sphere(e_curr), e00)
+        c_skip = c
+        c = merge.level_edge_attn(
+            c,
+            e_curr,
+            attn_mask,
+            level_idx=jnp.int32(level),
+            kfac_scan_shared=False,
+        )
+        c = jnp.where(attn_mask.astype(bool)[:, None], tree_sphere(c), c_skip)
+        carried.append(c)
+        level_mask = k
+        update_active = jnp.any(attn_mask.astype(bool))
+        pool_structural_mask = level_mask.astype(c.dtype) * update_active.astype(
+            c.dtype
+        )
+        pooled = gladder[0](
+            g_curr,
+            c,
+            level_mask.astype(c.dtype),
+            kfac_structural_mask=pool_structural_mask,
+            kfac_update_mask=update_active,
+            kfac_scan_shared=False,
+            kfac_repeat_ndim=1,
+        )
+        g_curr = gladder[1](
+            g_curr,
+            pooled,
+            update_mask=update_active,
+            kfac_structural_mask=update_active,
+            kfac_scan_shared=False,
+        )
+        level += 1
+    e_root = e_curr[0, 0]
+    merge_h = tuple(
+        compile_merge_h(
+            merge,
+            candidate,
+            depth_levels[i],
+        )
+        for i, candidate in enumerate(candidates)
+    )
+    return {
+        "c_candidate": tuple(candidates),
+        "c_carried": tuple(carried),
+        "depth_features": tuple(depth_levels),
+        "merge_h": merge_h,
+        "opcodes": tuple(opcode_levels),
+        "c_root": c[0],
+        "e_root": e_root,
+        "g_final": g_curr,
+    }
+
+
+def project_conditioner(context, hypernet):
+    return jnp.matmul(context, hypernet.W_h)
+
+
+def leaf_context(leaf_builder, e_leaf, g_emb):
+    g_broadcast = jnp.broadcast_to(g_emb, e_leaf.shape[:-1] + g_emb.shape)
+    return jnp.concatenate((e_leaf, g_broadcast), axis=-1)
+
+
+def compile_target_leaf_h(leaf_builder, e_leaf, g_emb):
+    context = leaf_context(leaf_builder, e_leaf, g_emb)
+    return (project_conditioner(context, leaf_builder.P_u),)
+
+
+def merge_context(merge, c_p_candidate, depth_features):
+    return jnp.concatenate(
+        (c_p_candidate, depth_features.astype(c_p_candidate.dtype)), axis=-1
+    )
+
+
+def compile_merge_h(merge, c_p_candidate, depth_features):
+    return project_conditioner(
+        merge_context(merge, c_p_candidate, depth_features), merge.output_hypernet
+    )
+
+
+def readout_context(readout, e_root, c_root, g_emb):
+    e_norm = readout.ln_e(e_root, pathway="even")
+    return jnp.concatenate(
+        (e_norm, c_root.astype(e_norm.dtype), g_emb.astype(e_norm.dtype)), axis=-1
+    )
+
+
+def compile_target_readout_h(readout, e_root, c_root, g_emb):
+    context = readout_context(readout, e_root, c_root, g_emb)
+    return (project_conditioner(context, readout.output_hypernet),)
+
+
+def classify_merge_opcodes(leaf_real):
+    active = jnp.asarray(leaf_real, dtype=jnp.bool_)
+    n = active.shape[0]
+    if n == 0 or n & (n - 1):
+        raise ValueError(f"leaf_real width must be a nonzero power of two, got {n}")
+    levels = []
+    while active.shape[0] > 1:
+        left = active[0::2]
+        right = active[1::2]
+        opcode = jnp.where(
+            left,
+            jnp.where(right, MERGE, CARRY_LEFT),
+            jnp.where(right, CARRY_RIGHT, EMPTY),
+        ).astype(jnp.uint8)
+        levels.append(opcode)
+        active = left | right
+    return tuple(levels)
+
+
+def assemble_compiled_tree(*, perm, leaf_real, boundaries) -> CompiledTree:
+    perm = jnp.asarray(perm, dtype=jnp.int32)
+    if perm.ndim != 1:
+        raise ValueError(f"perm must be rank one, got shape {perm.shape}")
+    leaf_real = jnp.asarray(leaf_real, dtype=jnp.bool_)
+    if leaf_real.shape != perm.shape:
+        raise ValueError(
+            f"leaf_real shape {leaf_real.shape} must match perm {perm.shape}"
+        )
+    inv_perm = jnp.argsort(perm).astype(jnp.int32)
+    return CompiledTree(
+        perm=perm,
+        inv_perm=inv_perm,
+        leaf_real=leaf_real,
+        leaf_h=tuple(boundaries["leaf_h"]),
+        leaf_combiner_h=tuple(boundaries["leaf_combiner_h"]),
+        merge_h=tuple(boundaries["merge_h"]),
+        opcodes=tuple(boundaries["opcodes"]),
+        readout_h=tuple(boundaries["readout_h"]),
+        readout_combiner_h=tuple(boundaries["readout_combiner_h"]),
+    )
+
+
+def compile_physical_tree_from_reduced_state(
+    kernel: PhysicalCompilerKernel,
+    *,
+    perm,
+    leaf_real,
+    leaf_h,
+    c_reduced,
+    edge_reduced,
+    real_reduced,
+    structural_reduced,
+    counts_reduced,
+    g_reduced,
+    early_merge_h=(),
+    early_opcodes=(),
+    full_structural_mask=None,
+) -> CompiledTree:
+    perm = jnp.asarray(perm, dtype=jnp.int32)
+    leaf_real = jnp.asarray(leaf_real)
+    if perm.ndim != 1 or leaf_real.shape != perm.shape:
+        raise ValueError("perm and leaf_real must be matching rank-one arrays")
+    early_merge_h = tuple(early_merge_h)
+    early_opcodes = tuple(early_opcodes)
+    if len(early_merge_h) != len(early_opcodes):
+        raise ValueError("early merge_h/opcode level counts differ")
+    if full_structural_mask is None:
+        full_structural_mask = leaf_real
+    level_offset = len(early_merge_h)
+    reduced = compile_context_only_reduction(
+        merge=kernel.merge,
+        c_leaf=c_reduced,
+        leaf_real=real_reduced,
+        g_emb=g_reduced,
+        edges=edge_reduced,
+        structural_mask=structural_reduced,
+        n_total=jnp.sum(leaf_real),
+        clock_depth=tree_active_clock_depth(jnp.asarray(full_structural_mask)),
+        gladder=(
+            kernel.tree_pool,
+            kernel.tree_update,
+            kernel.tree_projection_weight,
+            kernel.tree_projection_bias,
+        ),
+        initial_counts=counts_reduced,
+        level_offset=level_offset,
+        feature_n_levels=tree_active_clock_depth(leaf_real),
+    )
+    readout_g_emb = _project_global(
+        kernel.root_projection,
+        reduced["g_final"],
+        dense_tag="gladder.root_proj",
+        norm_tag="gladder.root_ln",
+    )
+    boundaries = {
+        "leaf_h": tuple(leaf_h),
+        "leaf_combiner_h": (),
+        "merge_h": early_merge_h + tuple(reduced["merge_h"]),
+        "opcodes": early_opcodes + tuple(reduced["opcodes"]),
+        "readout_h": compile_target_readout_h(
+            kernel.readout,
+            reduced["e_root"],
+            reduced["c_root"],
+            readout_g_emb,
+        ),
+        "readout_combiner_h": (),
+    }
+    return assemble_compiled_tree(
+        perm=perm,
+        leaf_real=leaf_real,
+        boundaries=boundaries,
+    )
+
+
+def compile_physical_tree_from_shared_trunk(
+    kernel: PhysicalCompilerKernel,
+    shared_trunk,
+    perm,
+) -> CompiledTree:
+    perm = jnp.asarray(perm, dtype=jnp.int32)
+    if perm.ndim != 1 or perm.shape != shared_trunk.real_mask.shape:
+        raise ValueError("perm must be rank one and match the shared trunk site width")
+    node = shared_trunk.node_raw[perm]
+    edge = shared_trunk.edge_raw[perm][:, perm]
+    leaf_real = shared_trunk.real_mask[perm]
+    structural_mask = shared_trunk.balanced_mask
+    e_leaf, edge_leaf, g_stream = kernel.contextualizer.with_edge(
+        node,
+        edge,
+        leaf_real,
+        structural_mask,
+        g=shared_trunk.global_stream,
+    )
+    g_stream = kernel.global_fork(g_stream, edge_leaf, structural_mask)
+    leaf_g_emb = _project_global(
+        kernel.leaf_projection,
+        g_stream,
+        dense_tag="gladder.to_gemb",
+        norm_tag="gladder.gemb_ln",
+    )
+    c_leaf = tree_sphere(kernel.leaf.P_c(e_leaf, pathway="even"))
+    reduced = compile_context_only_reduction(
+        merge=kernel.merge,
+        c_leaf=c_leaf,
+        leaf_real=leaf_real,
+        g_emb=g_stream,
+        edges=edge_leaf,
+        structural_mask=structural_mask,
+        gladder=(
+            kernel.tree_pool,
+            kernel.tree_update,
+            kernel.tree_projection_weight,
+            kernel.tree_projection_bias,
+        ),
+    )
+    readout_g_emb = _project_global(
+        kernel.root_projection,
+        reduced["g_final"],
+        dense_tag="gladder.root_proj",
+        norm_tag="gladder.root_ln",
+    )
+    boundaries = {
+        "leaf_h": compile_target_leaf_h(
+            kernel.leaf,
+            e_leaf,
+            leaf_g_emb,
+        ),
+        "leaf_combiner_h": (),
+        "merge_h": reduced["merge_h"],
+        "opcodes": reduced["opcodes"],
+        "readout_h": compile_target_readout_h(
+            kernel.readout,
+            reduced["e_root"],
+            reduced["c_root"],
+            readout_g_emb,
+        ),
+        "readout_combiner_h": (),
+    }
+    return assemble_compiled_tree(
+        perm=perm,
+        leaf_real=leaf_real,
+        boundaries=boundaries,
+    )
+
+
+def compile_physical_tree_reference(
+    model,
+    shared_trunk,
+    perm,
+) -> CompiledTree:
+    if model.gladder_post is None or model.gladder_fork_phys is None:
+        raise ValueError(
+            "reference physical compiler requires the target global ladder"
+        )
+    perm = jnp.asarray(perm, dtype=jnp.int32)
+    if perm.ndim != 1 or perm.shape != shared_trunk.real_mask.shape:
+        raise ValueError("perm must be rank one and match the shared trunk site width")
+    node = shared_trunk.node_raw[perm]
+    edge = shared_trunk.edge_raw[perm][:, perm]
+    leaf_real = shared_trunk.real_mask[perm]
+    structural_mask = shared_trunk.balanced_mask
+    e_leaf, edge_leaf, g_stream = model._contextualize_leaf_even_with_edge_g(
+        node,
+        edge,
+        leaf_real,
+        structural_mask,
+        shared_trunk.global_stream,
+    )
+    g_stream = model.gladder_fork_phys(g_stream, edge_leaf, structural_mask)
+    leaf_g_emb = model._gladder_project(g_stream)
+    c_leaf = tree_sphere(model.leaf.P_c(e_leaf, pathway="even"))
+    reduced = compile_context_only_reduction(
+        merge=model.merge,
+        c_leaf=c_leaf,
+        leaf_real=leaf_real,
+        g_emb=g_stream,
+        edges=edge_leaf,
+        structural_mask=structural_mask,
+        gladder=model._gladder_tree_refs(),
+    )
+    readout_g_emb = model._gladder_root_project(reduced["g_final"])
+    boundaries = {
+        "leaf_h": compile_target_leaf_h(model.leaf, e_leaf, leaf_g_emb),
+        "leaf_combiner_h": (),
+        "merge_h": reduced["merge_h"],
+        "opcodes": reduced["opcodes"],
+        "readout_h": compile_target_readout_h(
+            model.readout,
+            reduced["e_root"],
+            reduced["c_root"],
+            readout_g_emb,
+        ),
+        "readout_combiner_h": (),
+    }
+    return assemble_compiled_tree(
+        perm=perm,
+        leaf_real=leaf_real,
+        boundaries=boundaries,
+    )

src/hamiltonzero/compiled/trunk.py

@@ -0,0 +1,129 @@
+# Copyright (c) 2026 Simulacra Research Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import equinox as eqx
+import jax
+import jax.numpy as jnp
+
+from hamiltonzero.model import tree_sphere
+
+from .types import (
+    CanonicalHamiltonian,
+    FactorizedQSide,
+    QSideLeafInput,
+    SharedKernel,
+    SharedTrunk,
+    TrunkCompilerKernel,
+)
+
+
+def _qside(hypernet) -> FactorizedQSide:
+    return FactorizedQSide(V=hypernet.V, U=hypernet.U)
+
+
+def bind_shared_kernel(model) -> SharedKernel:
+    return SharedKernel(
+        q_to_odd=QSideLeafInput(weight=model.q_to_odd.weight),
+        leaf_factors=(_qside(model.leaf.P_u),),
+        leaf_combiner_factors=(),
+        merge_T=model.merge.T,
+        merge_factors=(_qside(model.merge.output_hypernet),),
+        readout_factors=(_qside(model.readout.output_hypernet),),
+        merge_eps=float(model.merge.eps),
+    )
+
+
+def bind_trunk_compiler_kernel(model) -> TrunkCompilerKernel:
+    return TrunkCompilerKernel(
+        featurizer=model.featurizer,
+        trunk=model.trunk,
+        shared_global=model.gladder_post,
+    )
+
+
+class _TrunkMaskContext(eqx.Module):
+    mask: jax.Array
+
+
+def compile_canonical_shared_trunk(
+    kernel: TrunkCompilerKernel,
+    canonical: CanonicalHamiltonian,
+) -> SharedTrunk:
+    if canonical.node_mask.ndim != 2 or canonical.node_mask.shape[0] != 1:
+        raise ValueError("compiled shared trunk requires exact physical P=1")
+    if canonical.balanced_mask.shape != canonical.node_mask.shape:
+        raise ValueError("balanced_mask must match node_mask shape")
+    graph = canonical.graph_inputs
+    if graph.node.shape[:2] != canonical.node_mask.shape:
+        raise ValueError("canonical graph node width must match node_mask")
+    if graph.edge.shape[:3] != (
+        1,
+        canonical.node_mask.shape[1],
+        canonical.node_mask.shape[1],
+    ):
+        raise ValueError("canonical graph edge width must match node_mask")
+
+    def one(edge_input, node_input, real_mask, balanced_mask):
+        edge_feat, local_feat, global_feat = kernel.featurizer(
+            edge_input,
+            real_mask,
+            node_input,
+        )
+        g_seed = tree_sphere(global_feat.astype(local_feat.dtype))
+        node_raw, edge_raw, g_seed = kernel.trunk(
+            _TrunkMaskContext(real_mask),
+            edge_feat,
+            local_feat,
+            g_seed,
+        )
+        global_stream = kernel.shared_global(
+            g_seed.astype(edge_raw.dtype), edge_raw, real_mask
+        )
+        return SharedTrunk(
+            node_raw=node_raw,
+            edge_raw=edge_raw,
+            global_raw=global_feat,
+            global_stream=global_stream,
+            real_mask=real_mask,
+            balanced_mask=balanced_mask,
+        )
+
+    return jax.vmap(one)(
+        graph.edge,
+        graph.node,
+        canonical.node_mask,
+        canonical.balanced_mask,
+    )
+
+
+def select_single_physical_trunk(trunk: SharedTrunk) -> SharedTrunk:
+    leaves = jax.tree_util.tree_leaves(trunk)
+    if not leaves or any(x.ndim < 1 or x.shape[0] != 1 for x in leaves):
+        raise ValueError("production SharedTrunk must have exact leading P=1")
+    return jax.tree_util.tree_map(lambda x: x[0], trunk)
+
+
+def compile_shared_trunk(model, ctx) -> SharedTrunk:
+    edge_feat, local_feat, global_feat = model.featurizer(
+        ctx.J_double_prime,
+        ctx.mask,
+        ctx.h_prime,
+    )
+    g_seed = tree_sphere(global_feat.astype(local_feat.dtype))
+    node_raw, edge_raw, g_seed = model.trunk(
+        ctx,
+        edge_feat,
+        local_feat,
+        g_seed,
+    )
+    global_stream = model._gladder_g_stream(edge_raw, ctx.mask, g_seed)
+    return SharedTrunk(
+        node_raw=node_raw,
+        edge_raw=edge_raw,
+        global_raw=global_feat,
+        global_stream=global_stream,
+        real_mask=ctx.mask,
+        balanced_mask=ctx.bmask,
+    )

src/hamiltonzero/compiled/types.py

@@ -0,0 +1,169 @@
+# Copyright (c) 2026 Simulacra Research Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from enum import IntEnum
+from typing import Any
+
+import equinox as eqx
+import jax
+import jax.numpy as jnp
+from jaxtyping import Array
+
+
+class MergeOpcode(IntEnum):
+    MERGE = 0
+    CARRY_LEFT = 1
+    CARRY_RIGHT = 2
+    EMPTY = 3
+
+
+MERGE = int(MergeOpcode.MERGE)
+CARRY_LEFT = int(MergeOpcode.CARRY_LEFT)
+CARRY_RIGHT = int(MergeOpcode.CARRY_RIGHT)
+EMPTY = int(MergeOpcode.EMPTY)
+OPCODE_DTYPE = jnp.uint8
+
+
+class QSideLeafInput(eqx.Module):
+    weight: Array
+
+
+class FactorizedQSide(eqx.Module):
+    V: Array
+    U: Array
+
+
+class SharedKernel(eqx.Module):
+    q_to_odd: QSideLeafInput
+    leaf_factors: tuple[FactorizedQSide, ...]
+    leaf_combiner_factors: tuple[FactorizedQSide, ...]
+    merge_T: Array
+    merge_factors: tuple[FactorizedQSide, ...]
+    readout_factors: tuple[FactorizedQSide, ...]
+    merge_eps: float = eqx.field(static=True)
+
+
+class TrunkCompilerKernel(eqx.Module):
+    featurizer: Any
+    trunk: Any
+    shared_global: Any
+
+
+class LadderProjectionKernel(eqx.Module):
+    weight: Array
+    bias: Array
+    norm_scale: Array
+
+
+class PhysicalCompilerKernel(eqx.Module):
+    contextualizer: Any
+    global_fork: Any
+    leaf: Any
+    merge: Any
+    readout: Any
+    leaf_projection: LadderProjectionKernel
+    tree_pool: Any
+    tree_update: Any
+    tree_projection_weight: Array
+    tree_projection_bias: Array
+    root_projection: LadderProjectionKernel
+
+
+class ModelHamiltonianArrays(eqx.Module):
+    coupling: Array
+    full_coupling: Array
+    field: Array
+
+
+class GraphInputs(eqx.Module):
+    node: Array
+    edge: Array
+
+
+class QuotientInputs(eqx.Module):
+    node_key: Array
+    edge_key: Array
+
+
+class EnergyInputs(eqx.Module):
+    custom_lap_J_eff: Array
+    custom_lap_radial_const: Array
+    one_body_fields: tuple[Array, ...]
+
+
+class EnergyMasks(eqx.Module):
+    real: Array
+    balanced: Array
+
+
+class EnergyFrame(eqx.Module):
+    custom_lap_J_eff: Array
+    w_levels: tuple[Array, ...]
+    custom_lap_radial_const: Array
+    one_body_fields: tuple[Array, ...]
+    masks: EnergyMasks
+
+
+EnergyFrameBatch = EnergyFrame
+
+
+class CanonicalHamiltonian(eqx.Module):
+    model_coupling_fields: ModelHamiltonianArrays
+    node_mask: Array
+    balanced_mask: Array
+    graph_inputs: GraphInputs
+    quotient_inputs: QuotientInputs
+    energy_inputs: EnergyInputs
+    system_identity: Array
+
+
+class SharedTrunk(eqx.Module):
+    node_raw: Array
+    edge_raw: Array
+    global_raw: Array
+    global_stream: Array
+    real_mask: Array
+    balanced_mask: Array
+
+
+class CompiledTree(eqx.Module):
+    perm: Array
+    inv_perm: Array
+    leaf_real: Array
+    leaf_h: tuple[Array, ...]
+    leaf_combiner_h: tuple[Array, ...]
+    merge_h: tuple[Array, ...]
+    opcodes: tuple[Array, ...]
+    readout_h: tuple[Array, ...]
+    readout_combiner_h: tuple[Array, ...]
+
+
+CompiledTreeBatch = CompiledTree
+
+
+class CompiledWaveFunction(eqx.Module):
+    kernel: SharedKernel
+    tree: CompiledTree
+
+    def __call__(self, q_routed, _ctx=None, _t=0.0):
+        from .execute import execute_wavefunction
+
+        return execute_wavefunction(self.kernel, self.tree, q_routed)
+
+
+class CompiledWaveFunctions(eqx.Module):
+    kernel: SharedKernel
+    trees: CompiledTreeBatch
+
+    def __call__(self, q_routed, _ctx=None, _t=0.0):
+        from .execute import execute_wavefunction
+
+        return execute_wavefunction(self.kernel, self.trees, q_routed)
+
+
+def level_widths(n_sites: int) -> tuple[int, ...]:
+    if n_sites <= 0 or n_sites & (n_sites - 1):
+        raise ValueError(f"n_sites must be a positive power of two, got {n_sites}")
+    return tuple(n_sites >> level for level in range(1, n_sites.bit_length()))

src/hamiltonzero/config.py

@@ -0,0 +1,301 @@
+# Copyright (c) 2026 Simulacra Research Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import dataclasses
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal, TypeVar
+
+
+AttentionImplementation = Literal["tuned", "einsum"]
+
+
+@dataclass(frozen=True, slots=True)
+class ModelConfig:
+    d_e: int = 512
+    d_o: int = 32
+    d_c: int = 512
+    d_r: int = 32
+    n_heads: int = 16
+    n_layers: int = 8
+    rank: int = 32
+    edge_channels: int = 96
+    attention_qk_dim: int = 256
+    attention_v_dim: int = 256
+    merge_dim: int = 1536
+    trunk_edge_node_context_dim: int = 256
+    trunk_edge_hidden_dim: int = 128
+    trunk_attention_bias_hidden_dim: int = 64
+    trunk_ffn_hidden_dim: int = 2048
+    trunk_two_hop_hidden_dim: int = 128
+    tree_edge_node_context_dim: int = 256
+    global_dim: int = 256
+    merge_hypernet_rank: int = 256
+    featurizer_bond_dim: int = 128
+    featurizer_heads: int = 8
+    featurizer_head_dim: int = 64
+    featurizer_global_queries: int = 4
+    featurizer_edge_hidden_dim: int = 192
+    featurizer_zeeman_hidden_dim: int = 2048
+    featurizer_global_hidden_dim: int = 16384
+    featurizer_combine_hidden_dim: int = 12288
+    featurizer_token_initial_scale: float = 0.02
+    polar_group_norm_tau: float = 0.001
+    polar_bond_hidden_dim: int = 256
+    polar_bond_groups: int = 16
+    polar_bond_group_dim: int = 16
+    polar_zeeman_groups: int = 16
+    polar_zeeman_group_dim: int = 16
+    router_max_n: int = 128
+    router_model_dim: int = 512
+    router_heads: int = 16
+    router_attention_dim: int = 128
+    router_score_dim: int = 512
+    router_candidate_dim: int = 1024
+    router_summary_dim: int = 1024
+    router_ffn_dim: int = 1024
+    router_score_initial_scale: float = 0.0
+    router_rope_base: float = 10000.0
+    router_rope_scaling: float = 1.0
+    router_tree_prefix_layers: int = 4
+    router_tree_candidate_layers: int = 2
+    router_tree_merge_dim: int = 1024
+    router_tree_post_layers: int = 4
+    router_context_layers: int = 2
+    router_context_heads: int = 4
+    router_context_attention_dim: int = 256
+    router_context_edge_node_dim: int = 256
+    level_edge_heads: int = 8
+    level_edge_mlp_dim: int = 384
+    level_edge_mlp_blocks: int = 3
+    level_edge_ffn_dim: int = 1024
+    level_edge_rope_base: float = 10000.0
+    level_edge_rope_scaling: float = 1.0
+    root_readout_edge_rank: int = 128
+    ngpt_alpha_initial: float = 0.25
+    ngpt_alpha_initial_fraction: float = 0.25
+    ngpt_alpha_maximum: float = 0.8
+    global_ladder_tap_dim: int = 256
+    level_edge_bias_mlp_dim: int = 128
+    level_edge_bias_mlp_blocks: int = 1
+    merge_context_mlp_dim: int = 1024
+    readout_context_layers: int = 2
+    readout_context_heads: int = 8
+    readout_context_attention_dim: int = 128
+    readout_context_edge_node_dim: int = 256
+    readout_context_summary_dim: int = 1024
+    readout_context_mlp_dim: int = 2048
+    readout_context_bias_dim: int = 32
+    readout_context_edge_ffn_dim: int = 384
+    readout_context_rope_base: float = 10000.0
+    readout_context_rope_scaling: float = 1.0
+    two_hop_channels: int = 64
+    tree_fwl_channels: int = 128
+    attention: AttentionImplementation = "tuned"
+
+
+@dataclass(frozen=True, slots=True)
+class MCMCConfig:
+    batch_size: int = 512
+    replicas: int = 8
+    steps: int = 32
+    burn_in: int = 256
+    burn_in_replica_steps: int = 2
+    walker_chunk_size: int | None = None
+    initial_sigma: float = 0.3
+    initial_haar_sites: int = 1
+    sigma_scale: float = 1.1
+    langevin_target_acceptance: float = 0.574
+    haar_target_acceptance: float = 0.234
+    beta_history_weight: float = 0.9
+    adapt_every: int = 1
+    reuse_mcmc: Path | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class KFACConfig:
+    learning_rate_numerator: float = 0.05
+    learning_rate_offset: float = 5.0
+    learning_rate_decay_steps: float = 5000.0
+    curvature_ema: float = 0.995
+    curvature_update_period: int = 2
+    inverse_update_period: int = 2
+    damping: float = 0.001
+    minimum_damping: float = 0.0001
+    norm_constraint: float = 0.001
+    mad_clip_width: float = 5.0
+    momentum: float = 0.0
+    l2_regularization: float = 0.0
+
+
+@dataclass(frozen=True, slots=True)
+class RouterConfig:
+    temperature: float = 1.0
+    loss_weight: float = 1.0
+
+
+@dataclass(frozen=True, slots=True)
+class EnergyConfig:
+    mu: float | None = None
+    eps: float = 0.1
+    chunk_size: int = 512
+
+
+@dataclass(frozen=True, slots=True)
+class TrainConfig:
+    systems: Path
+    output: Path
+    steps: int
+    seed: int = 777
+    n_max: int = 64
+    model: ModelConfig = field(default_factory=ModelConfig)
+    router: RouterConfig = field(default_factory=RouterConfig)
+    mcmc: MCMCConfig = field(default_factory=MCMCConfig)
+    kfac: KFACConfig = field(default_factory=KFACConfig)
+    energy: EnergyConfig = field(default_factory=EnergyConfig)
+
+
+def _finetune_mcmc() -> MCMCConfig:
+    return MCMCConfig(batch_size=256, replicas=8, steps=2, burn_in=256)
+
+
+def _finetune_kfac() -> KFACConfig:
+    return KFACConfig(
+        learning_rate_numerator=0.002,
+        learning_rate_offset=1.0,
+        learning_rate_decay_steps=10000.0,
+        curvature_ema=0.99,
+        curvature_update_period=2,
+        inverse_update_period=4,
+        damping=0.001,
+    )
+
+
+def _finetune_energy() -> EnergyConfig:
+    return EnergyConfig(mu=2.86)
+
+
+@dataclass(frozen=True, slots=True)
+class FineTuneConfig:
+    system: Path
+    checkpoint: Path
+    output: Path
+    steps: int = 10000
+    seed: int = 777
+    leaf_rank: int = 1536
+    merge_rank: int = 1024
+    route_temperature: float = 1.0
+    model: ModelConfig = field(default_factory=lambda: ModelConfig(attention="einsum"))
+    mcmc: MCMCConfig = field(default_factory=_finetune_mcmc)
+    kfac: KFACConfig = field(default_factory=_finetune_kfac)
+    energy: EnergyConfig = field(default_factory=_finetune_energy)
+
+
+def _eval_mcmc() -> EvalMCMCConfig:
+    return EvalMCMCConfig(
+        batch_size=256,
+        replicas=8,
+        steps=24,
+        burn_in=1024,
+        walker_chunk_size=16,
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class EvalMCMCConfig:
+    batch_size: int = 256
+    replicas: int = 8
+    steps: int = 24
+    burn_in: int = 1024
+    burn_in_replica_steps: int = 2
+    walker_chunk_size: int = 16
+    initial_sigma: float = 0.3
+    initial_haar_sites: int = 1
+    sigma_scale: float = 1.1
+    langevin_target_acceptance: float = 0.574
+    haar_target_acceptance: float = 0.234
+    beta_history_weight: float = 0.9
+
+
+@dataclass(frozen=True, slots=True)
+class EvalConfig:
+    system: Path
+    checkpoint: Path
+    output: Path
+    seed: int = 777
+    contest: bool = False
+    large_n: bool = False
+    measurements: int = 256
+    contest_candidates: int = 8
+    contest_beam_width: int = 8
+    contest_preburn: int = 128
+    contest_measurements: int = 128
+    contest_se_multiplier: float = 2.0
+    route_temperature: float = 4.0
+    large_n_sequence_shards: int = 0
+    large_n_pair_tile_size: int = 128
+    contextualizer_attention: AttentionImplementation | None = None
+    model: ModelConfig = field(default_factory=ModelConfig)
+    mcmc: EvalMCMCConfig = field(default_factory=_eval_mcmc)
+    energy: EnergyConfig = field(default_factory=EnergyConfig)
+
+    def __post_init__(self) -> None:
+        if self.contest and self.large_n:
+            raise ValueError("contest and large_n are mutually exclusive")
+
+
+Config = TrainConfig | FineTuneConfig | EvalConfig
+T = TypeVar("T")
+
+
+def _coerce(cls: type[T], values: dict[str, Any]) -> T:
+    nested = {
+        "model": ModelConfig,
+        "router": RouterConfig,
+        "mcmc": MCMCConfig,
+        "kfac": KFACConfig,
+        "energy": EnergyConfig,
+    }
+    if cls is EvalConfig:
+        nested["mcmc"] = EvalMCMCConfig
+    data = dict(values)
+    fields_by_name = {item.name: item for item in dataclasses.fields(cls)}
+    for name, nested_cls in nested.items():
+        if name in data and isinstance(data[name], dict):
+            item = fields_by_name.get(name)
+            defaults: dict[str, Any] = {}
+            if item is not None and item.default_factory is not dataclasses.MISSING:
+                defaults = dataclasses.asdict(item.default_factory())
+            nested_values = {**defaults, **data[name]}
+            if name == "mcmc" and nested_values.get("reuse_mcmc") is not None:
+                nested_values["reuse_mcmc"] = Path(nested_values["reuse_mcmc"])
+            data[name] = nested_cls(**nested_values)
+    path_fields = {"systems", "system", "checkpoint", "output"}
+    for item in dataclasses.fields(cls):
+        if item.name in path_fields and item.name in data:
+            data[item.name] = Path(data[item.name])
+    return cls(**data)
+
+
+def load_config(path: str | Path, mode: Literal["train", "finetune", "eval"]) -> Config:
+    values = json.loads(Path(path).read_text())
+    cls = {"train": TrainConfig, "finetune": FineTuneConfig, "eval": EvalConfig}[mode]
+    return _coerce(cls, values)
+
+
+__all__ = [
+    "AttentionImplementation",
+    "EnergyConfig",
+    "EvalConfig",
+    "EvalMCMCConfig",
+    "FineTuneConfig",
+    "KFACConfig",
+    "MCMCConfig",
+    "ModelConfig",
+    "RouterConfig",
+    "TrainConfig",
+    "load_config",
+]

src/hamiltonzero/data/__init__.py

@@ -0,0 +1,22 @@
+# Copyright (c) 2026 Simulacra Research Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+from .systems import (
+    build_context,
+    build_context_and_energy,
+    build_multi_context,
+    load_system,
+    load_systems,
+    padded_model_arrays,
+    save_system,
+)
+
+__all__ = [
+    "build_context",
+    "build_context_and_energy",
+    "build_multi_context",
+    "load_system",
+    "load_systems",
+    "padded_model_arrays",
+    "save_system",
+]

src/hamiltonzero/data/systems.py

@@ -0,0 +1,264 @@
+# Copyright (c) 2026 Simulacra Research Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import json
+from dataclasses import replace
+from pathlib import Path
+from typing import Any, Iterable
+
+import numpy as np
+
+from hamiltonzero.hamiltonian import SpinHamiltonian, _exchange_matrix
+
+
+def _load_payload(path: str | Path) -> dict[str, Any]:
+    source = Path(path)
+    if source.suffix == ".jsonl":
+        records = []
+        with source.open(encoding="utf-8") as stream:
+            for line_number, line in enumerate(stream, 1):
+                if not line.strip():
+                    continue
+                record = json.loads(line)
+                if not isinstance(record, dict):
+                    raise ValueError(f"JSONL record {line_number} must be an object")
+                records.append(record)
+        return {"systems": records}
+    payload = json.loads(source.read_text())
+    if not isinstance(payload, dict):
+        raise ValueError("Hamiltonian dataset must be a JSON object")
+    return payload
+
+
+def _from_sparse(spec: dict[str, Any]) -> SpinHamiltonian:
+    n_sites = int(spec.get("n_sites", spec.get("n_spins", 0)))
+    if n_sites <= 0:
+        raise ValueError("sparse Hamiltonian requires a positive n_sites")
+    exchange = np.zeros((n_sites, n_sites, 3, 3), dtype=np.float32)
+    coupling = np.zeros((n_sites, n_sites), dtype=np.float32)
+    seen: set[tuple[int, int]] = set()
+    for offset, term in enumerate(spec["exchange"]):
+        if not isinstance(term, list) or len(term) != 3:
+            raise ValueError(f"exchange term {offset} must be [i,j,J]")
+        left, right, value = term
+        if (
+            not isinstance(left, int)
+            or isinstance(left, bool)
+            or not isinstance(right, int)
+            or isinstance(right, bool)
+            or not 0 <= left < right < n_sites
+        ):
+            raise ValueError(
+                f"exchange term {offset} must satisfy 0 <= i < j < n_sites"
+            )
+        pair = (left, right)
+        if pair in seen:
+            raise ValueError(f"duplicate exchange term for sites {pair}")
+        seen.add(pair)
+        matrix = _exchange_matrix(value)
+        exchange[left, right] = matrix
+        exchange[right, left] = matrix.T
+        coupling[left, right] = coupling[right, left] = 1.0
+    field = spec.get("field", spec.get("h", spec.get("h_field", 0.0)))
+    return SpinHamiltonian.from_arrays(
+        exchange,
+        field,
+        coupling=coupling,
+        nodes=spec.get("nodes"),
+        mu=spec.get("mu"),
+    )
+
+
+def _next_power_of_two(value: int) -> int:
+    return 1 if value <= 1 else 1 << (value - 1).bit_length()
+
+
+def _from_record(
+    record: dict[str, Any],
+    *,
+    needs_fwl2: bool | None = None,
+) -> SpinHamiltonian:
+    outer = record
+    spec = record.get("spec", record)
+    convention = spec.get("convention", "textbook")
+    if convention != "textbook":
+        raise ValueError("public Hamiltonian JSON must use convention='textbook'")
+    if "exchange" in spec:
+        system = _from_sparse(spec)
+    else:
+        system = SpinHamiltonian.from_arrays(
+            spec["J"],
+            spec.get("h", spec.get("h_field", 0.0)),
+            coupling=spec.get("coupling"),
+            nodes=spec.get("nodes"),
+            mu=spec.get("mu"),
+        )
+    if needs_fwl2 is None:
+        needs_fwl2 = outer.get("needs_fwl2", spec.get("needs_fwl2"))
+    metadata = {
+        name: outer.get(name, spec.get(name))
+        for name in ("category", "tag", "topology_class", "j_class")
+    }
+    return replace(
+        system,
+        _needs_fwl2=needs_fwl2,
+        _category=metadata["category"],
+        _tag=metadata["tag"],
+        _topology_class=metadata["topology_class"],
+        _j_class=metadata["j_class"],
+    )
+
+
+def load_system(path: str | Path) -> SpinHamiltonian:
+    payload = _load_payload(path)
+    if "systems" in payload:
+        systems = payload["systems"]
+        if len(systems) != 1:
+            raise ValueError("load_system requires exactly one system")
+        dispatch = payload.get("needs_fwl2", payload.get("dataset_needs_fwl2"))
+        if dispatch is not None:
+            if not isinstance(dispatch, list) or len(dispatch) != 1:
+                raise ValueError("needs_fwl2 sidecar must align with systems")
+            return _from_record(systems[0], needs_fwl2=bool(dispatch[0]))
+        return _from_record(systems[0])
+    return _from_record(payload)
+
+
+def load_systems(path: str | Path) -> list[SpinHamiltonian]:
+    payload = _load_payload(path)
+    records = payload.get("systems", [payload])
+    dispatch = (
+        payload.get("needs_fwl2", payload.get("dataset_needs_fwl2"))
+        if "systems" in payload
+        else None
+    )
+    if dispatch is None and isinstance(payload.get("per_system"), list):
+        derived = payload["per_system"]
+        if len(derived) == len(records) and all(
+            isinstance(value, dict) and "needs_fwl2" in value for value in derived
+        ):
+            dispatch = [value["needs_fwl2"] for value in derived]
+    if dispatch is not None:
+        if not isinstance(dispatch, list) or len(dispatch) != len(records):
+            raise ValueError("needs_fwl2 sidecar must align with systems")
+        return [
+            _from_record(record, needs_fwl2=bool(value))
+            for record, value in zip(records, dispatch, strict=True)
+        ]
+    return [_from_record(record) for record in records]
+
+
+def save_system(path: str | Path, system: SpinHamiltonian) -> None:
+    destination = Path(path)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    destination.write_text(json.dumps(system.to_dict(), indent=2) + "\n")
+
+
+def padded_model_arrays(
+    system: SpinHamiltonian,
+    n_max: int | None = None,
+) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
+    width = _next_power_of_two(system.n_spins) if n_max is None else int(n_max)
+    if width < system.n_spins:
+        raise ValueError("n_max cannot be smaller than the system")
+    if width <= 0 or width & (width - 1):
+        raise ValueError("n_max must be a positive power of two")
+    coupling, exchange, field = system.model_arrays()
+    padding = width - system.n_spins
+    coupling = np.pad(coupling, ((0, padding), (0, padding)))
+    exchange = np.pad(exchange, ((0, padding), (0, padding), (0, 0), (0, 0)))
+    field = np.pad(field, ((0, padding), (0, 0)))
+    mask = np.zeros((width,), dtype=np.int32)
+    mask[: system.n_spins] = 1
+    return coupling, exchange, field, mask
+
+
+def _context_arrays(system: SpinHamiltonian, n_max: int | None):
+    import jax.numpy as jnp
+
+    from hamiltonzero.model.route_quotient import system_needs_fwl2
+
+    _coupling, exchange, field, mask = padded_model_arrays(system, n_max)
+    needs_fwl2 = system._needs_fwl2
+    if needs_fwl2 is None:
+        _, physical_exchange, physical_field = system.model_arrays()
+        needs_fwl2 = system_needs_fwl2(
+            physical_exchange,
+            physical_field,
+            system.n_spins,
+            category=system._category,
+            tag=system._tag,
+            topology_class=system._topology_class,
+            j_class=system._j_class,
+        )
+    return (
+        jnp.asarray(exchange),
+        jnp.asarray(field),
+        jnp.asarray(mask),
+        needs_fwl2,
+    )
+
+
+def build_context(
+    system: SpinHamiltonian,
+    n_max: int | None = None,
+):
+    from hamiltonzero.model import SpinContext
+
+    exchange, field, mask, needs_fwl2 = _context_arrays(system, n_max)
+    return SpinContext(
+        J_full=exchange,
+        h=field,
+        mask=mask,
+        needs_fwl2=needs_fwl2,
+    )
+
+
+def build_context_and_energy(
+    system: SpinHamiltonian,
+    n_max: int | None = None,
+    mu: float | None = None,
+    eps: float = 0.1,
+):
+    from hamiltonzero.energy.frame import build_energy_inputs
+    from hamiltonzero.model import SpinContext
+
+    exchange, field, mask, needs_fwl2 = _context_arrays(system, n_max)
+    context = SpinContext(
+        J_full=exchange,
+        h=field,
+        mask=mask,
+        needs_fwl2=needs_fwl2,
+    )
+    energy_inputs = build_energy_inputs(
+        exchange,
+        field,
+        mask,
+        system.mu if mu is None else mu,
+        eps,
+    )
+    return context, energy_inputs
+
+
+def build_multi_context(
+    systems: Iterable[SpinHamiltonian],
+    n_max: int,
+):
+    from hamiltonzero.model import MultiSystemContext
+
+    system_list = list(systems)
+    contexts = [build_context(system, n_max=n_max) for system in system_list]
+    return MultiSystemContext.stack(contexts)
+
+
+__all__ = [
+    "build_context",
+    "build_context_and_energy",
+    "build_multi_context",
+    "load_system",
+    "load_systems",
+    "padded_model_arrays",
+    "save_system",
+]

src/hamiltonzero/energy/__init__.py

@@ -0,0 +1,22 @@
+# Copyright (c) 2026 Simulacra Research Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from hamiltonzero.model._custom_lap_primitives import (
+    custom_lap_active,
+    quadrilinear_merge_p,
+)
+
+from .compiled import (
+    vmc_energy_custom_lap_compiled,
+    vmc_energy_custom_lap_finetune,
+)
+
+
+__all__ = [
+    "custom_lap_active",
+    "quadrilinear_merge_p",
+    "vmc_energy_custom_lap_compiled",
+    "vmc_energy_custom_lap_finetune",
+]

src/hamiltonzero/energy/compiled.py

@@ -0,0 +1,57 @@
+# Copyright (c) 2026 Simulacra Research Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+
+from __future__ import annotations
+
+from typing import Any
+
+import jax
+
+from hamiltonzero.energy.kernel import (
+    _vmc_energy_custom_lap_finetune,
+    _vmc_energy_custom_lap_prebuilt,
+)
+
+
+def vmc_energy_custom_lap_compiled(
+    kernel: Any,
+    tree: Any,
+    energy_frame: Any,
+    q_routed: jax.Array,
+    *,
+    chunk_size: int | None = 512,
+) -> tuple[jax.Array, jax.Array, jax.Array, jax.Array]:
+    return _vmc_energy_custom_lap_prebuilt(
+        kernel,
+        tree,
+        energy_frame,
+        q_routed,
+        chunk_size=chunk_size,
+    )
+
+
+def vmc_energy_custom_lap_finetune(
+    model: Any,
+    energy_frame: Any,
+    q_routed: jax.Array,
+    *,
+    chunk_size: int | None = 512,
+) -> tuple[jax.Array, jax.Array, jax.Array, jax.Array]:
+    from hamiltonzero.compiled.model import CompiledFinetuneWaveFunction
+
+    if not isinstance(model, CompiledFinetuneWaveFunction):
+        raise TypeError("fine-tune energy requires CompiledFinetuneWaveFunction")
+    return _vmc_energy_custom_lap_finetune(
+        model,
+        energy_frame,
+        q_routed,
+        0.0,
+        chunk_size=chunk_size,
+    )
+
+
+__all__ = [
+    "vmc_energy_custom_lap_compiled",
+    "vmc_energy_custom_lap_finetune",
+]

src/hamiltonzero/energy/custom_lap.py

@@ -0,0 +1,1491 @@
+# Copyright (c) 2026 Simulacra Research Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+
+from __future__ import annotations
+
+from typing import Any, Callable, NamedTuple
+
+import jax
+import jax.numpy as jnp
+from jax import lax
+from jax.extend import core
+from jax.extend.core import Literal
+
+
+class JLP(NamedTuple):
+    value: Any
+    jac: Any
+    lap: Any
+    level: int
+    has_chunk_axis: bool
+    chunk_idx: int = -1
+
+
+def _is_jlp(x) -> bool:
+    return isinstance(x, JLP)
+
+
+from hamiltonzero.model._custom_lap_primitives import (
+    custom_lap_active,
+    enter_custom_lap,
+    restore_custom_lap,
+    quadrilinear_merge_p,
+)
+
+
+class use_custom_lap:
+    def __enter__(self):
+        self._cla_token = enter_custom_lap()
+        return self
+
+    def __exit__(self, *exc):
+        restore_custom_lap(self._cla_token)
+
+
+def build_W_levels(W_full, N: int) -> list:
+
+    assert W_full.shape == (3 * N, 3 * N), (
+        f"W_full must be [3N, 3N]; got {W_full.shape}"
+    )
+    assert (N & (N - 1)) == 0, f"N must be a power of 2; got {N}"
+    levels = []
+    k = 1
+    while k <= N:
+        n_chunks = N // k
+        W_reshaped = W_full.reshape(n_chunks, 3 * k, n_chunks, 3 * k)
+        idx = jnp.arange(n_chunks)
+        W_k = W_reshaped[idx, :, idx, :]
+        levels.append(W_k)
+        k *= 2
+    return levels
+
+
+def _level_idx(k: int) -> int:
+
+    assert k > 0 and (k & (k - 1)) == 0, f"k must be a power of 2; got {k}"
+    return k.bit_length() - 1
+
+
+def _W_at_level(W_levels, k: int):
+    return W_levels[_level_idx(k)]
+
+
+_RULE_REGISTRY: dict[core.Primitive, Callable] = {}
+
+
+def _params_except(params, *drop, **defaults):
+
+    out = {k: params[k] for k in params if k not in drop}
+    for k, v in defaults.items():
+        out.setdefault(k, v)
+    return out
+
+
+def _shape_bind_params(params, *drop):
+
+    out = {k: params[k] for k in params if k not in drop and k != "out_sharding"}
+    out.setdefault("sharding", params.get("out_sharding", None))
+    return out
+
+
+def _select_W_for_jlp(
+    level: int, chunk_idx: int, has_chunk_axis: bool, W_levels, M_jac: int
+):
+
+    W_k = _W_at_level(W_levels, level)
+    if has_chunk_axis:
+        assert W_k.shape[0] == M_jac, (
+            f"has_chunk_axis: W_k chunks {W_k.shape[0]} must equal jac M {M_jac}"
+        )
+        return W_k
+    if chunk_idx >= 0:
+        assert M_jac == 1
+        return W_k[chunk_idx : chunk_idx + 1]
+
+    assert W_k.shape[0] == M_jac, (
+        f"multi-chunk: W_k chunks {W_k.shape[0]} must equal jac M {M_jac}"
+    )
+    return W_k
+
+
+def _jac_self_quad_form(
+    jac, level: int, chunk_idx: int, has_chunk_axis: bool, W_levels
+):
+
+    M = jac.shape[1]
+    W_used = _select_W_for_jlp(level, chunk_idx, has_chunk_axis, W_levels, M)
+    n_trailing = jac.ndim - 2
+    if n_trailing == 0:
+        out = jnp.einsum("mc,cmn,nc->c", jac, W_used, jac)
+    elif n_trailing == 1:
+        out = jnp.einsum("mca,cmn,nca->ca", jac, W_used, jac)
+    elif n_trailing == 2:
+        out = jnp.einsum("mcab,cmn,ncab->cab", jac, W_used, jac)
+    elif n_trailing == 3:
+        out = jnp.einsum("mcabd,cmn,ncabd->cabd", jac, W_used, jac)
+    else:
+        raise NotImplementedError(
+            f"_jac_self_quad_form: trailing rank {n_trailing} not supported"
+        )
+    if not has_chunk_axis:
+        out = out.sum(axis=0)
+    return out
+
+
+def _make_unary_rule(prim, f_prime_fn, f_dprime_fn):
+
+    def rule(invals, params, W_levels):
+        [x] = invals
+        assert _is_jlp(x)
+        v_out = prim.bind(x.value, **params)
+        fp = f_prime_fn(x.value)
+        jac_out = fp * x.jac
+        fpp = f_dprime_fn(x.value)
+        cross = _jac_self_quad_form(
+            x.jac, x.level, x.chunk_idx, x.has_chunk_axis, W_levels
+        )
+        lap_out = fp * x.lap + fpp * cross
+        return JLP(
+            value=v_out,
+            jac=jac_out,
+            lap=lap_out,
+            level=x.level,
+            has_chunk_axis=x.has_chunk_axis,
+            chunk_idx=x.chunk_idx,
+        )
+
+    _RULE_REGISTRY[prim] = rule
+
+
+_make_unary_rule(lax.sin_p, jnp.cos, lambda x: -jnp.sin(x))
+_make_unary_rule(lax.cos_p, lambda x: -jnp.sin(x), lambda x: -jnp.cos(x))
+_make_unary_rule(
+    lax.tanh_p,
+    lambda x: 1.0 - jnp.tanh(x) ** 2,
+    lambda x: -2.0 * jnp.tanh(x) * (1.0 - jnp.tanh(x) ** 2),
+)
+_make_unary_rule(lax.exp_p, jnp.exp, jnp.exp)
+_make_unary_rule(lax.log_p, lambda x: 1.0 / x, lambda x: -1.0 / (x * x))
+_make_unary_rule(lax.neg_p, lambda x: -jnp.ones_like(x), lambda x: jnp.zeros_like(x))
+_make_unary_rule(lax.abs_p, lambda x: jnp.sign(x), lambda x: jnp.zeros_like(x))
+_make_unary_rule(
+    lax.sqrt_p, lambda x: 0.5 / jnp.sqrt(x), lambda x: -0.25 / (x * jnp.sqrt(x))
+)
+_make_unary_rule(
+    lax.rsqrt_p,
+    lambda x: -0.5 / (x * jnp.sqrt(x)),
+    lambda x: 0.75 / (x * x * jnp.sqrt(x)),
+)
+
+
+def _logistic_prime(x):
+    s = jax.nn.sigmoid(x)
+    return s * (1.0 - s)
+
+
+def _logistic_dprime(x):
+    s = jax.nn.sigmoid(x)
+    return s * (1.0 - s) * (1.0 - 2.0 * s)
+
+
+_logistic_p = lax.logistic_p
+_make_unary_rule(_logistic_p, _logistic_prime, _logistic_dprime)
+
+
+def _integer_pow_rule(invals, params, W_levels):
+    [x] = invals
+    y = params["y"]
+    assert _is_jlp(x)
+    v_out = lax.integer_pow_p.bind(x.value, **params)
+    if y == 0:
+        return JLP(
+            value=jnp.ones_like(x.value),
+            jac=jnp.zeros_like(x.jac),
+            lap=jnp.zeros_like(x.lap),
+            level=x.level,
+            has_chunk_axis=x.has_chunk_axis,
+            chunk_idx=x.chunk_idx,
+        )
+    if y == 1:
+        return x
+    fp = float(y) * lax.integer_pow_p.bind(x.value, y=y - 1)
+    jac_out = fp * x.jac
+    fpp = float(y * (y - 1)) * lax.integer_pow_p.bind(x.value, y=max(y - 2, 0))
+    cross = _jac_self_quad_form(x.jac, x.level, x.chunk_idx, x.has_chunk_axis, W_levels)
+    lap_out = fp * x.lap + fpp * cross
+    return JLP(
+        value=v_out,
+        jac=jac_out,
+        lap=lap_out,
+        level=x.level,
+        has_chunk_axis=x.has_chunk_axis,
+        chunk_idx=x.chunk_idx,
+    )
+
+
+_RULE_REGISTRY[lax.integer_pow_p] = _integer_pow_rule
+
+
+def _convert_rule(invals, params, W_levels):
+    [x] = invals
+    assert _is_jlp(x)
+    new_dtype = params["new_dtype"]
+    return JLP(
+        value=x.value.astype(new_dtype),
+        jac=x.jac.astype(new_dtype),
+        lap=x.lap.astype(new_dtype),
+        level=x.level,
+        has_chunk_axis=x.has_chunk_axis,
+        chunk_idx=x.chunk_idx,
+    )
+
+
+_RULE_REGISTRY[lax.convert_element_type_p] = _convert_rule
+
+
+def _broadcast_jac_lap_for_op(x, target_shape):
+
+    lap_out = jnp.broadcast_to(x.lap, target_shape)
+    jac_out = _broadcast_jac_to_value_shape(x.jac, target_shape, x.has_chunk_axis)
+    return jac_out, lap_out
+
+
+def _broadcast_jac_to_value_shape(jac, target_value_shape, has_chunk_axis: bool):
+
+    if has_chunk_axis:
+        new_shape = (jac.shape[0], target_value_shape[0]) + tuple(
+            target_value_shape[1:]
+        )
+    else:
+        new_shape = (jac.shape[0], jac.shape[1]) + tuple(target_value_shape)
+    while jac.ndim < len(new_shape):
+        jac = jnp.expand_dims(jac, axis=jac.ndim)
+    return jnp.broadcast_to(jac, new_shape)
+
+
+def _promote_jlp_one_level(x: JLP) -> JLP:
+
+    k = x.level
+    new_k = 2 * k
+    if x.has_chunk_axis:
+        assert x.chunk_idx in (0, 1), (
+            f"_promote_jlp_one_level (chunked): chunk_idx must be 0 or 1; got {x}"
+        )
+        is_left = x.chunk_idx == 0
+        zero_shape = (3 * k,) + x.jac.shape[1:]
+        zeros = jnp.zeros(zero_shape, dtype=x.jac.dtype)
+        if is_left:
+            new_jac = jnp.concatenate([x.jac, zeros], axis=0)
+        else:
+            new_jac = jnp.concatenate([zeros, x.jac], axis=0)
+        return JLP(
+            value=x.value,
+            jac=new_jac,
+            lap=x.lap,
+            level=new_k,
+            has_chunk_axis=True,
+            chunk_idx=-1,
+        )
+
+    assert x.chunk_idx >= 0, (
+        f"_promote_jlp_one_level: per-node requires chunk_idx>=0; got {x}"
+    )
+    is_left = x.chunk_idx % 2 == 0
+    new_chunk_idx = x.chunk_idx // 2
+    zero_shape = (3 * k,) + x.jac.shape[1:]
+    zeros = jnp.zeros(zero_shape, dtype=x.jac.dtype)
+    if is_left:
+        new_jac = jnp.concatenate([x.jac, zeros], axis=0)
+    else:
+        new_jac = jnp.concatenate([zeros, x.jac], axis=0)
+    return JLP(
+        value=x.value,
+        jac=new_jac,
+        lap=x.lap,
+        level=new_k,
+        has_chunk_axis=False,
+        chunk_idx=new_chunk_idx,
+    )
+
+
+def _align_jlp_levels(a: JLP, b: JLP):
+
+    while a.level < b.level:
+        a = _promote_jlp_one_level(a)
+    while b.level < a.level:
+        b = _promote_jlp_one_level(b)
+    assert a.has_chunk_axis == b.has_chunk_axis, (
+        "_align_jlp_levels: chunk-axis mismatch"
+    )
+    if a.has_chunk_axis:
+        if (
+            a.chunk_idx in (0, 1)
+            and b.chunk_idx in (0, 1)
+            and a.chunk_idx != b.chunk_idx
+        ):
+            a = _promote_jlp_one_level(a)
+            b = _promote_jlp_one_level(b)
+        return a, b
+
+    while a.chunk_idx != b.chunk_idx:
+        a = _promote_jlp_one_level(a)
+        b = _promote_jlp_one_level(b)
+    return a, b
+
+
+def _add_or_sub_rule(sign: float):
+    def rule(invals, params, W_levels):
+        a, b = invals
+        if _is_jlp(a) and _is_jlp(b):
+            need_promote = (
+                (a.level != b.level)
+                or (
+                    not a.has_chunk_axis
+                    and not b.has_chunk_axis
+                    and a.chunk_idx != b.chunk_idx
+                )
+                or (
+                    a.has_chunk_axis
+                    and b.has_chunk_axis
+                    and a.chunk_idx in (0, 1)
+                    and b.chunk_idx in (0, 1)
+                    and a.chunk_idx != b.chunk_idx
+                )
+            )
+            if need_promote:
+                a, b = _align_jlp_levels(a, b)
+            assert a.has_chunk_axis == b.has_chunk_axis, "add/sub: chunk-axis mismatch"
+            v_out = a.value + sign * b.value
+            a_jac_b = _broadcast_jac_to_value_shape(
+                a.jac, v_out.shape, a.has_chunk_axis
+            )
+            b_jac_b = _broadcast_jac_to_value_shape(
+                b.jac, v_out.shape, b.has_chunk_axis
+            )
+            jac_out = a_jac_b + sign * b_jac_b
+            a_lap_b = jnp.broadcast_to(a.lap, v_out.shape)
+            b_lap_b = jnp.broadcast_to(b.lap, v_out.shape)
+            lap_out = a_lap_b + sign * b_lap_b
+            return JLP(
+                value=v_out,
+                jac=jac_out,
+                lap=lap_out,
+                level=a.level,
+                has_chunk_axis=a.has_chunk_axis,
+                chunk_idx=a.chunk_idx,
+            )
+        if _is_jlp(a):
+            v_out = a.value + sign * b
+            jac_out, lap_out = _broadcast_jac_lap_for_op(a, v_out.shape)
+            return JLP(
+                value=v_out,
+                jac=jac_out,
+                lap=lap_out,
+                level=a.level,
+                has_chunk_axis=a.has_chunk_axis,
+                chunk_idx=a.chunk_idx,
+            )
+
+        v_out = a + sign * b.value
+        jac_out, lap_out = _broadcast_jac_lap_for_op(b, v_out.shape)
+        return JLP(
+            value=v_out,
+            jac=sign * jac_out,
+            lap=sign * lap_out,
+            level=b.level,
+            has_chunk_axis=b.has_chunk_axis,
+            chunk_idx=b.chunk_idx,
+        )
+
+    return rule
+
+
+_RULE_REGISTRY[lax.add_p] = _add_or_sub_rule(+1.0)
+_RULE_REGISTRY[lax.sub_p] = _add_or_sub_rule(-1.0)
+
+
+def _mul_rule(invals, params, W_levels):
+    a, b = invals
+    if _is_jlp(a) and _is_jlp(b):
+        need_promote = (a.level != b.level) or (
+            not a.has_chunk_axis and not b.has_chunk_axis and a.chunk_idx != b.chunk_idx
+        )
+        if need_promote:
+            a, b = _align_jlp_levels(a, b)
+        assert a.has_chunk_axis == b.has_chunk_axis
+
+        v_out = a.value * b.value
+        a_jac_b = _broadcast_jac_to_value_shape(a.jac, v_out.shape, a.has_chunk_axis)
+        b_jac_b = _broadcast_jac_to_value_shape(b.jac, v_out.shape, b.has_chunk_axis)
+        a_val_b = jnp.broadcast_to(a.value, v_out.shape)
+        b_val_b = jnp.broadcast_to(b.value, v_out.shape)
+        jac_out = a_val_b * b_jac_b + b_val_b * a_jac_b
+        a_lap_b = jnp.broadcast_to(a.lap, v_out.shape)
+        b_lap_b = jnp.broadcast_to(b.lap, v_out.shape)
+        cross = _jac_cross_quad_form(
+            a_jac_b, b_jac_b, a.level, a.chunk_idx, a.has_chunk_axis, W_levels
+        )
+        lap_out = a_val_b * b_lap_b + b_val_b * a_lap_b + 2.0 * cross
+        return JLP(
+            value=v_out,
+            jac=jac_out,
+            lap=lap_out,
+            level=a.level,
+            has_chunk_axis=a.has_chunk_axis,
+            chunk_idx=a.chunk_idx,
+        )
+    if _is_jlp(a):
+        v_out = a.value * b
+        jac_b, lap_b = _broadcast_jac_lap_for_op(a, v_out.shape)
+        return JLP(
+            value=v_out,
+            jac=b * jac_b,
+            lap=b * lap_b,
+            level=a.level,
+            has_chunk_axis=a.has_chunk_axis,
+            chunk_idx=a.chunk_idx,
+        )
+
+    v_out = a * b.value
+    jac_b, lap_b = _broadcast_jac_lap_for_op(b, v_out.shape)
+    return JLP(
+        value=v_out,
+        jac=a * jac_b,
+        lap=a * lap_b,
+        level=b.level,
+        has_chunk_axis=b.has_chunk_axis,
+        chunk_idx=b.chunk_idx,
+    )
+
+
+def _jac_cross_quad_form(
+    jac_a, jac_b, level: int, chunk_idx: int, has_chunk_axis: bool, W_levels
+):
+
+    M = jac_a.shape[1]
+    W_used = _select_W_for_jlp(level, chunk_idx, has_chunk_axis, W_levels, M)
+    n_trailing = jac_a.ndim - 2
+    if n_trailing == 0:
+        out = jnp.einsum("mc,cmn,nc->c", jac_a, W_used, jac_b)
+    elif n_trailing == 1:
+        out = jnp.einsum("mca,cmn,nca->ca", jac_a, W_used, jac_b)
+    elif n_trailing == 2:
+        out = jnp.einsum("mcab,cmn,ncab->cab", jac_a, W_used, jac_b)
+    elif n_trailing == 3:
+        out = jnp.einsum("mcabd,cmn,ncabd->cabd", jac_a, W_used, jac_b)
+    else:
+        raise NotImplementedError(
+            f"_jac_cross_quad_form: trailing rank {n_trailing} not supported"
+        )
+    if not has_chunk_axis:
+        out = out.sum(axis=0)
+    return out
+
+
+_RULE_REGISTRY[lax.mul_p] = _mul_rule
+
+
+def _div_rule(invals, params, W_levels):
+    a, b = invals
+    if _is_jlp(a) and _is_jlp(b):
+        need_promote = (a.level != b.level) or (
+            not a.has_chunk_axis and not b.has_chunk_axis and a.chunk_idx != b.chunk_idx
+        )
+        if need_promote:
+            a, b = _align_jlp_levels(a, b)
+        assert a.has_chunk_axis == b.has_chunk_axis
+        v_out = a.value / b.value
+        a_val_b = jnp.broadcast_to(a.value, v_out.shape)
+        b_val_b = jnp.broadcast_to(b.value, v_out.shape)
+        a_jac_b = _broadcast_jac_to_value_shape(a.jac, v_out.shape, a.has_chunk_axis)
+        b_jac_b = _broadcast_jac_to_value_shape(b.jac, v_out.shape, b.has_chunk_axis)
+        inv_b = 1.0 / b_val_b
+        jac_out = inv_b * a_jac_b - (a_val_b * inv_b * inv_b) * b_jac_b
+        a_lap_b = jnp.broadcast_to(a.lap, v_out.shape)
+        b_lap_b = jnp.broadcast_to(b.lap, v_out.shape)
+        lap_first = inv_b * a_lap_b - (a_val_b * inv_b * inv_b) * b_lap_b
+        cross_bb = _jac_self_quad_form(
+            b_jac_b, b.level, b.chunk_idx, b.has_chunk_axis, W_levels
+        )
+        cross_ab = _jac_cross_quad_form(
+            a_jac_b, b_jac_b, a.level, a.chunk_idx, a.has_chunk_axis, W_levels
+        )
+        lap_second = (2.0 * a_val_b * inv_b**3) * cross_bb + (
+            -2.0 * inv_b * inv_b
+        ) * cross_ab
+        lap_out = lap_first + lap_second
+        return JLP(
+            value=v_out,
+            jac=jac_out,
+            lap=lap_out,
+            level=a.level,
+            has_chunk_axis=a.has_chunk_axis,
+            chunk_idx=a.chunk_idx,
+        )
+    if _is_jlp(a):
+        inv_b = 1.0 / b
+        v_out = a.value * inv_b
+        jac_b, lap_b = _broadcast_jac_lap_for_op(a, v_out.shape)
+        return JLP(
+            value=v_out,
+            jac=inv_b * jac_b,
+            lap=inv_b * lap_b,
+            level=a.level,
+            has_chunk_axis=a.has_chunk_axis,
+            chunk_idx=a.chunk_idx,
+        )
+
+    v_out = a / b.value
+    inv_b = 1.0 / b.value
+    fp = -a * inv_b * inv_b
+    jac_out = fp * b.jac
+    fpp = 2.0 * a * inv_b**3
+    cross = _jac_self_quad_form(b.jac, b.level, b.chunk_idx, b.has_chunk_axis, W_levels)
+    lap_out = fp * b.lap + fpp * cross
+    return JLP(
+        value=v_out,
+        jac=jac_out,
+        lap=lap_out,
+        level=b.level,
+        has_chunk_axis=b.has_chunk_axis,
+        chunk_idx=b.chunk_idx,
+    )
+
+
+_RULE_REGISTRY[lax.div_p] = _div_rule
+
+
+def _atan2_rule(invals, params, W_levels):
+    a_arg, b_arg = invals
+    if _is_jlp(a_arg) and _is_jlp(b_arg):
+        need_promote = (a_arg.level != b_arg.level) or (
+            not a_arg.has_chunk_axis
+            and not b_arg.has_chunk_axis
+            and a_arg.chunk_idx != b_arg.chunk_idx
+        )
+        if need_promote:
+            a_arg, b_arg = _align_jlp_levels(a_arg, b_arg)
+        assert a_arg.has_chunk_axis == b_arg.has_chunk_axis
+        a, b = a_arg, b_arg
+    elif _is_jlp(a_arg):
+        a = a_arg
+        b = _trivial_jlp_like(b_arg, a_arg)
+    else:
+        b = b_arg
+        a = _trivial_jlp_like(a_arg, b_arg)
+    v_out = jnp.arctan2(a.value, b.value)
+    r_sq = a.value**2 + b.value**2
+    inv_r2 = 1.0 / r_sq
+    fa = b.value * inv_r2
+    fb = -a.value * inv_r2
+    aj = _broadcast_jac_to_value_shape(a.jac, v_out.shape, a.has_chunk_axis)
+    bj = _broadcast_jac_to_value_shape(b.jac, v_out.shape, b.has_chunk_axis)
+    jac_out = fa * aj + fb * bj
+    faa = -2.0 * a.value * b.value * inv_r2 * inv_r2
+    fbb = 2.0 * a.value * b.value * inv_r2 * inv_r2
+    fab = (a.value**2 - b.value**2) * inv_r2 * inv_r2
+    al = jnp.broadcast_to(a.lap, v_out.shape)
+    bl = jnp.broadcast_to(b.lap, v_out.shape)
+    cross_aa = _jac_self_quad_form(aj, a.level, a.chunk_idx, a.has_chunk_axis, W_levels)
+    cross_bb = _jac_self_quad_form(bj, b.level, b.chunk_idx, b.has_chunk_axis, W_levels)
+    cross_ab = _jac_cross_quad_form(
+        aj, bj, a.level, a.chunk_idx, a.has_chunk_axis, W_levels
+    )
+    lap_out = fa * al + fb * bl + faa * cross_aa + fbb * cross_bb + 2.0 * fab * cross_ab
+    return JLP(
+        value=v_out,
+        jac=jac_out,
+        lap=lap_out,
+        level=a.level,
+        has_chunk_axis=a.has_chunk_axis,
+        chunk_idx=a.chunk_idx,
+    )
+
+
+def _trivial_jlp_like(plain_val, template_jlp: JLP) -> JLP:
+
+    val = jnp.asarray(plain_val)
+    if template_jlp.has_chunk_axis:
+        jac_shape = (template_jlp.jac.shape[0], template_jlp.jac.shape[1]) + tuple(
+            val.shape[1:]
+        )
+    else:
+        jac_shape = (template_jlp.jac.shape[0], template_jlp.jac.shape[1]) + tuple(
+            val.shape
+        )
+    return JLP(
+        value=val,
+        jac=jnp.zeros(jac_shape, dtype=val.dtype),
+        lap=jnp.zeros_like(val),
+        level=template_jlp.level,
+        has_chunk_axis=template_jlp.has_chunk_axis,
+        chunk_idx=template_jlp.chunk_idx,
+    )
+
+
+_RULE_REGISTRY[lax.atan2_p] = _atan2_rule
+
+
+def _dot_general_rule(invals, params, W_levels):
+    lhs, rhs = invals
+    dimension_numbers = params["dimension_numbers"]
+    (lhs_contract, rhs_contract), (lhs_batch, rhs_batch) = dimension_numbers
+
+    if _is_jlp(lhs) and _is_jlp(rhs):
+        raise NotImplementedError(
+            "dot_general: JLP × JLP outside quadrilinear_merge_p is not supported. "
+            "If a model op needs same-level bilinear, route it through the merge "
+            "primitive or rewrite as elementwise mul + reduce_sum."
+        )
+    if _is_jlp(lhs):
+        return _dot_general_jlp_plain(
+            lhs, rhs, dimension_numbers, params, jlp_is_lhs=True
+        )
+    return _dot_general_jlp_plain(rhs, lhs, dimension_numbers, params, jlp_is_lhs=False)
+
+
+def _dot_general_jlp_plain(
+    jlp_arg, plain_arg, dimension_numbers, params, jlp_is_lhs: bool
+):
+
+    (lhs_contract, rhs_contract), (lhs_batch, rhs_batch) = dimension_numbers
+    dot_kw = {
+        "precision": params.get("precision", None),
+        "preferred_element_type": params.get("preferred_element_type", None),
+        "out_sharding": params.get("out_sharding", None),
+    }
+
+    if jlp_is_lhs:
+        v_out = lax.dot_general(jlp_arg.value, plain_arg, dimension_numbers, **dot_kw)
+        lap_out = lax.dot_general(jlp_arg.lap, plain_arg, dimension_numbers, **dot_kw)
+    else:
+        v_out = lax.dot_general(plain_arg, jlp_arg.value, dimension_numbers, **dot_kw)
+        lap_out = lax.dot_general(plain_arg, jlp_arg.lap, dimension_numbers, **dot_kw)
+
+    jac = jlp_arg.jac
+    leading_3k = jac.shape[0]
+
+    if jlp_arg.has_chunk_axis:
+        jac_for_dot = jac
+        shift = 1
+    else:
+        jac_for_dot = jac.reshape((leading_3k,) + tuple(jlp_arg.value.shape))
+        shift = 1
+
+    if jlp_is_lhs:
+        new_lhs_contract = tuple(a + shift for a in lhs_contract)
+        new_rhs_contract = tuple(rhs_contract)
+        new_lhs_batch = tuple(a + shift for a in lhs_batch)
+        new_rhs_batch = tuple(rhs_batch)
+        new_dim_nums = (
+            (new_lhs_contract, new_rhs_contract),
+            (new_lhs_batch, new_rhs_batch),
+        )
+        jac_out_raw = lax.dot_general(jac_for_dot, plain_arg, new_dim_nums, **dot_kw)
+
+        n_batch = len(new_lhs_batch)
+        pos_3k = n_batch
+    else:
+        new_lhs_contract = tuple(lhs_contract)
+        new_rhs_contract = tuple(a + shift for a in rhs_contract)
+        new_lhs_batch = tuple(lhs_batch)
+        new_rhs_batch = tuple(a + shift for a in rhs_batch)
+        new_dim_nums = (
+            (new_lhs_contract, new_rhs_contract),
+            (new_lhs_batch, new_rhs_batch),
+        )
+        jac_out_raw = lax.dot_general(plain_arg, jac_for_dot, new_dim_nums, **dot_kw)
+
+        n_batch = len(new_lhs_batch)
+        lhs_ndim = jnp.asarray(plain_arg).ndim
+        n_lhs_nonbatch = lhs_ndim - n_batch - len(new_lhs_contract)
+        pos_3k = n_batch + n_lhs_nonbatch
+
+    if pos_3k != 0:
+        jac_out = jnp.moveaxis(jac_out_raw, pos_3k, 0)
+    else:
+        jac_out = jac_out_raw
+
+    if jlp_arg.has_chunk_axis:
+        new_has_chunk_axis = True
+        new_chunk_idx = -1
+    else:
+        jac_out = jac_out[:, None]
+        new_has_chunk_axis = False
+        new_chunk_idx = jlp_arg.chunk_idx
+
+    return JLP(
+        value=v_out,
+        jac=jac_out,
+        lap=lap_out,
+        level=jlp_arg.level,
+        has_chunk_axis=new_has_chunk_axis,
+        chunk_idx=new_chunk_idx,
+    )
+
+
+_RULE_REGISTRY[lax.dot_general_p] = _dot_general_rule
+
+
+def _broadcast_in_dim_rule(invals, params, W_levels):
+    [x] = invals
+    assert _is_jlp(x)
+    shape = params["shape"]
+    broadcast_dimensions = params["broadcast_dimensions"]
+    extra = _shape_bind_params(params, "shape", "broadcast_dimensions")
+
+    v_out = lax.broadcast_in_dim_p.bind(
+        x.value, shape=shape, broadcast_dimensions=broadcast_dimensions, **extra
+    )
+    lap_out = lax.broadcast_in_dim_p.bind(
+        x.lap, shape=shape, broadcast_dimensions=broadcast_dimensions, **extra
+    )
+
+    if x.has_chunk_axis:
+        new_shape = (x.jac.shape[0],) + tuple(shape)
+        new_bd = (0,) + tuple(d + 1 for d in broadcast_dimensions)
+        jac_out = lax.broadcast_in_dim_p.bind(
+            x.jac.reshape((x.jac.shape[0],) + x.value.shape),
+            shape=new_shape,
+            broadcast_dimensions=new_bd,
+            **extra,
+        )
+
+        new_has_chunk_axis = True
+        new_chunk_idx = -1
+    else:
+        new_shape = (x.jac.shape[0], 1) + tuple(shape)
+        new_bd = (0, 1) + tuple(d + 2 for d in broadcast_dimensions)
+        jac_out = lax.broadcast_in_dim_p.bind(
+            x.jac,
+            shape=new_shape,
+            broadcast_dimensions=new_bd,
+            **extra,
+        )
+        new_has_chunk_axis = False
+        new_chunk_idx = x.chunk_idx
+
+    return JLP(
+        value=v_out,
+        jac=jac_out,
+        lap=lap_out,
+        level=x.level,
+        has_chunk_axis=new_has_chunk_axis,
+        chunk_idx=new_chunk_idx,
+    )
+
+
+_RULE_REGISTRY[lax.broadcast_in_dim_p] = _broadcast_in_dim_rule
+
+
+def _reduce_sum_rule(invals, params, W_levels):
+    [x] = invals
+    assert _is_jlp(x)
+    axes = tuple(params["axes"])
+    extra = _params_except(params, "axes", out_sharding=None)
+    v_out = lax.reduce_sum_p.bind(x.value, axes=axes, **extra)
+    lap_out = lax.reduce_sum_p.bind(x.lap, axes=axes, **extra)
+    if x.has_chunk_axis:
+        if 0 in axes:
+            non_chunk_axes = tuple(a for a in axes if a != 0)
+            jac_reduce_axes = tuple(a + 1 for a in non_chunk_axes)
+            if jac_reduce_axes:
+                jac_out = lax.reduce_sum_p.bind(x.jac, axes=jac_reduce_axes, **extra)
+            else:
+                jac_out = x.jac
+            new_has_chunk_axis = False
+            new_chunk_idx = -1
+        else:
+            jac_reduce_axes = tuple(a + 1 for a in axes)
+            jac_out = lax.reduce_sum_p.bind(x.jac, axes=jac_reduce_axes, **extra)
+            new_has_chunk_axis = True
+            new_chunk_idx = -1
+    else:
+        jac_reduce_axes = tuple(a + 2 for a in axes)
+        jac_out = lax.reduce_sum_p.bind(x.jac, axes=jac_reduce_axes, **extra)
+        new_has_chunk_axis = False
+        new_chunk_idx = x.chunk_idx
+    return JLP(
+        value=v_out,
+        jac=jac_out,
+        lap=lap_out,
+        level=x.level,
+        has_chunk_axis=new_has_chunk_axis,
+        chunk_idx=new_chunk_idx,
+    )
+
+
+_RULE_REGISTRY[lax.reduce_sum_p] = _reduce_sum_rule
+
+
+def _reduce_max_rule(invals, params, W_levels):
+    [x] = invals
+    assert _is_jlp(x)
+    axes = tuple(params["axes"])
+    extra = _params_except(params, "axes", out_sharding=None)
+    v_out = lax.reduce_max_p.bind(x.value, axes=axes, **extra)
+
+    keep_shape = list(x.value.shape)
+    for a in axes:
+        keep_shape[a] = 1
+    v_max_kept = lax.reduce_max_p.bind(x.value, axes=axes, **extra).reshape(
+        tuple(keep_shape)
+    )
+    mask = (x.value == v_max_kept).astype(x.value.dtype)
+
+    mask_sum_axes = lax.reduce_sum_p.bind(
+        mask,
+        axes=axes,
+        **extra,
+    ).reshape(tuple(keep_shape))
+    mask = mask / (mask_sum_axes + 1e-30)
+
+    def _gated_reduce(jac_arr, jac_axes):
+
+        n_lead = jac_arr.ndim - x.value.ndim
+        mask_b = mask.reshape((1,) * n_lead + mask.shape)
+
+        return lax.reduce_sum_p.bind(
+            jac_arr * mask_b,
+            axes=jac_axes,
+            **extra,
+        )
+
+    if x.has_chunk_axis:
+        if 0 in axes:
+            non_chunk_axes = tuple(a for a in axes if a != 0)
+            jac_reduce_axes = tuple(a + 1 for a in non_chunk_axes) + (1,)
+            jac_out = _gated_reduce(x.jac, jac_reduce_axes)
+            new_has_chunk_axis = False
+            new_chunk_idx = -1
+        else:
+            jac_reduce_axes = tuple(a + 1 for a in axes)
+            jac_out = _gated_reduce(x.jac, jac_reduce_axes)
+            new_has_chunk_axis = True
+            new_chunk_idx = -1
+    else:
+        jac_reduce_axes = tuple(a + 2 for a in axes)
+        jac_out = _gated_reduce(x.jac, jac_reduce_axes)
+        new_has_chunk_axis = False
+        new_chunk_idx = x.chunk_idx
+    lap_out = jnp.zeros_like(v_out)
+    return JLP(
+        value=v_out,
+        jac=jac_out,
+        lap=lap_out,
+        level=x.level,
+        has_chunk_axis=new_has_chunk_axis,
+        chunk_idx=new_chunk_idx,
+    )
+
+
+_RULE_REGISTRY[lax.reduce_max_p] = _reduce_max_rule
+
+
+def _make_minmax_rule(sign_for_first):
+
+    def rule(invals, params, W_levels):
+        a, b = invals
+        if _is_jlp(a) and _is_jlp(b):
+            need_promote = (
+                (a.level != b.level)
+                or (
+                    not a.has_chunk_axis
+                    and not b.has_chunk_axis
+                    and a.chunk_idx != b.chunk_idx
+                )
+                or (
+                    a.has_chunk_axis
+                    and b.has_chunk_axis
+                    and a.chunk_idx in (0, 1)
+                    and b.chunk_idx in (0, 1)
+                    and a.chunk_idx != b.chunk_idx
+                )
+            )
+            if need_promote:
+                a, b = _align_jlp_levels(a, b)
+            cmp = (a.value - b.value) * sign_for_first
+            mask_a = (cmp > 0).astype(a.value.dtype)
+            mask_b = 1.0 - mask_a
+            v_out = mask_a * a.value + mask_b * b.value
+
+            jac_a_b = _broadcast_jac_to_value_shape(
+                a.jac, v_out.shape, a.has_chunk_axis
+            )
+            jac_b_b = _broadcast_jac_to_value_shape(
+                b.jac, v_out.shape, b.has_chunk_axis
+            )
+            n_lead_a = jac_a_b.ndim - mask_a.ndim
+            n_lead_b = jac_b_b.ndim - mask_b.ndim
+            mask_a_lead = mask_a.reshape((1,) * n_lead_a + mask_a.shape)
+            mask_b_lead = mask_b.reshape((1,) * n_lead_b + mask_b.shape)
+            jac_out = mask_a_lead * jac_a_b + mask_b_lead * jac_b_b
+            lap_out = mask_a * jnp.broadcast_to(
+                a.lap, v_out.shape
+            ) + mask_b * jnp.broadcast_to(b.lap, v_out.shape)
+            return JLP(
+                value=v_out,
+                jac=jac_out,
+                lap=lap_out,
+                level=a.level,
+                has_chunk_axis=a.has_chunk_axis,
+                chunk_idx=a.chunk_idx,
+            )
+        if _is_jlp(a):
+            cmp = (a.value - b) * sign_for_first
+            mask_a = (cmp > 0).astype(a.value.dtype)
+            v_out = mask_a * a.value + (1 - mask_a) * b
+            n_lead = a.jac.ndim - mask_a.ndim
+            mask_a_lead = mask_a.reshape((1,) * n_lead + mask_a.shape)
+            jac_out = mask_a_lead * a.jac
+            lap_out = mask_a * a.lap
+            return JLP(
+                value=v_out,
+                jac=jac_out,
+                lap=lap_out,
+                level=a.level,
+                has_chunk_axis=a.has_chunk_axis,
+                chunk_idx=a.chunk_idx,
+            )
+
+        cmp = (a - b.value) * sign_for_first
+        mask_a = (cmp > 0).astype(b.value.dtype)
+        v_out = mask_a * a + (1 - mask_a) * b.value
+        mask_b = 1 - mask_a
+        n_lead = b.jac.ndim - mask_b.ndim
+        mask_b_lead = mask_b.reshape((1,) * n_lead + mask_b.shape)
+        jac_out = mask_b_lead * b.jac
+        lap_out = mask_b * b.lap
+        return JLP(
+            value=v_out,
+            jac=jac_out,
+            lap=lap_out,
+            level=b.level,
+            has_chunk_axis=b.has_chunk_axis,
+            chunk_idx=b.chunk_idx,
+        )
+
+    return rule
+
+
+_RULE_REGISTRY[lax.max_p] = _make_minmax_rule(+1.0)
+_RULE_REGISTRY[lax.min_p] = _make_minmax_rule(-1.0)
+
+
+def _reshape_jac_for_value(x: JLP, new_value_shape: tuple, new_dimensions):
+
+    leading_3k = x.jac.shape[0]
+    if x.has_chunk_axis:
+        M = x.value.shape[0]
+        old_trailing = x.value.shape[1:]
+
+        if len(new_value_shape) >= 1 and new_value_shape[0] == M:
+            jac_axes_perm = None
+            if new_dimensions is not None:
+                jac_axes_perm = (0,) + tuple(d + 1 for d in new_dimensions)
+                jac_pre = jnp.transpose(x.jac, jac_axes_perm)
+            else:
+                jac_pre = x.jac
+            new_jac_shape = (leading_3k,) + tuple(new_value_shape)
+            jac_new = jnp.reshape(jac_pre, new_jac_shape)
+
+            return jac_new, True, -1
+
+        if M == 1:
+            assert new_dimensions is None, (
+                "reshape with M=1-squeeze + transpose not yet supported"
+            )
+
+            new_jac_shape = (leading_3k, 1) + tuple(new_value_shape)
+
+            jac_new = jnp.reshape(x.jac, new_jac_shape)
+            return jac_new, False, 0
+        raise NotImplementedError(
+            f"reshape: cannot reshape JLP value {x.value.shape} (has_chunk_axis, M={M}) "
+            f"to {new_value_shape} — chunk axis would be fused/lost."
+        )
+
+    assert new_dimensions is None or all(d >= 0 for d in new_dimensions)
+    jac_pre = x.jac
+    if new_dimensions is not None:
+        jac_axes_perm = (0, 1) + tuple(d + 2 for d in new_dimensions)
+        jac_pre = jnp.transpose(jac_pre, jac_axes_perm)
+    new_jac_shape = (leading_3k, 1) + tuple(new_value_shape)
+    jac_new = jnp.reshape(jac_pre, new_jac_shape)
+    return jac_new, False, x.chunk_idx
+
+
+def _reshape_rule(invals, params, W_levels):
+    [x] = invals
+    assert _is_jlp(x)
+    new_sizes = tuple(params["new_sizes"])
+    dimensions = params.get("dimensions")
+
+    extra = _shape_bind_params(params, "new_sizes", "dimensions")
+    v_out = lax.reshape_p.bind(
+        x.value, new_sizes=new_sizes, dimensions=dimensions, **extra
+    )
+    lap_out = lax.reshape_p.bind(
+        x.lap, new_sizes=new_sizes, dimensions=dimensions, **extra
+    )
+    jac_new, new_has_chunk, new_idx = _reshape_jac_for_value(x, new_sizes, dimensions)
+    return JLP(
+        value=v_out,
+        jac=jac_new,
+        lap=lap_out,
+        level=x.level,
+        has_chunk_axis=new_has_chunk,
+        chunk_idx=new_idx,
+    )
+
+
+_RULE_REGISTRY[lax.reshape_p] = _reshape_rule
+
+
+def _transpose_rule(invals, params, W_levels):
+    [x] = invals
+    assert _is_jlp(x)
+    perm = tuple(params["permutation"])
+    extra = {k: params[k] for k in params if k != "permutation"}
+    v_out = lax.transpose_p.bind(x.value, permutation=perm, **extra)
+    lap_out = lax.transpose_p.bind(x.lap, permutation=perm, **extra)
+
+    if x.has_chunk_axis:
+        if perm[0] != 0:
+            raise NotImplementedError(
+                "transpose: chunk axis (value axis 0) must remain at position 0; "
+                f"got permutation {perm}."
+            )
+
+        jac_perm = (0, 1) + tuple(p + 1 for p in perm[1:])
+    else:
+        jac_perm = (0, 1) + tuple(p + 2 for p in perm)
+    jac_new = lax.transpose_p.bind(x.jac, permutation=jac_perm, **extra)
+    return JLP(
+        value=v_out,
+        jac=jac_new,
+        lap=lap_out,
+        level=x.level,
+        has_chunk_axis=x.has_chunk_axis,
+        chunk_idx=x.chunk_idx,
+    )
+
+
+_RULE_REGISTRY[lax.transpose_p] = _transpose_rule
+
+
+def _slice_rule(invals, params, W_levels):
+    [x] = invals
+    assert _is_jlp(x)
+    start = tuple(params["start_indices"])
+    limit = tuple(params["limit_indices"])
+    strides = params.get("strides")
+    extra = {
+        k: params[k]
+        for k in params
+        if k not in ("start_indices", "limit_indices", "strides")
+    }
+    v_out = lax.slice_p.bind(
+        x.value, start_indices=start, limit_indices=limit, strides=strides, **extra
+    )
+    lap_out = lax.slice_p.bind(
+        x.lap, start_indices=start, limit_indices=limit, strides=strides, **extra
+    )
+
+    if x.has_chunk_axis:
+        new_chunk_idx = x.chunk_idx
+        old_M = x.value.shape[0]
+        stride0 = strides[0] if strides is not None else 1
+        v_out_M = v_out.shape[0]
+        chunk_axis_touched = start[0] != 0 or limit[0] != old_M or stride0 != 1
+        if chunk_axis_touched:
+            if v_out_M == 1:
+                new_chunk_idx = start[0]
+            elif stride0 > 1 and v_out_M * stride0 == old_M and start[0] in (0, 1):
+                new_chunk_idx = start[0]
+            elif v_out_M != old_M:
+                raise NotImplementedError(
+                    f"slice on chunk axis: unsupported sub-range "
+                    f"start={start[0]}, limit={limit[0]}, stride={stride0}, "
+                    f"old_M={old_M}, v_out_M={v_out_M}"
+                )
+        jac_start = (0, start[0]) + tuple(start[1:])
+        jac_limit = (x.jac.shape[0], limit[0]) + tuple(limit[1:])
+        jac_strides = None if strides is None else (1, strides[0]) + tuple(strides[1:])
+        jac_out = lax.slice_p.bind(
+            x.jac,
+            start_indices=jac_start,
+            limit_indices=jac_limit,
+            strides=jac_strides,
+            **extra,
+        )
+        return JLP(
+            value=v_out,
+            jac=jac_out,
+            lap=lap_out,
+            level=x.level,
+            has_chunk_axis=True,
+            chunk_idx=new_chunk_idx,
+        )
+
+    jac_start = (0, 0) + tuple(start)
+    jac_limit = (x.jac.shape[0], x.jac.shape[1]) + tuple(limit)
+    jac_strides = None if strides is None else (1, 1) + tuple(strides)
+    jac_out = lax.slice_p.bind(
+        x.jac,
+        start_indices=jac_start,
+        limit_indices=jac_limit,
+        strides=jac_strides,
+        **extra,
+    )
+    return JLP(
+        value=v_out,
+        jac=jac_out,
+        lap=lap_out,
+        level=x.level,
+        has_chunk_axis=False,
+        chunk_idx=x.chunk_idx,
+    )
+
+
+_RULE_REGISTRY[lax.slice_p] = _slice_rule
+
+
+def _squeeze_rule(invals, params, W_levels):
+    [x] = invals
+    assert _is_jlp(x)
+    dims = tuple(params["dimensions"])
+    extra = {k: params[k] for k in params if k != "dimensions"}
+    v_out = lax.squeeze_p.bind(x.value, dimensions=dims, **extra)
+    lap_out = lax.squeeze_p.bind(x.lap, dimensions=dims, **extra)
+    if x.has_chunk_axis and 0 in dims:
+        non_chunk_dims = tuple(d for d in dims if d != 0)
+        jac_dims = tuple(d + 1 for d in non_chunk_dims)
+
+        if jac_dims:
+            jac_out = lax.squeeze_p.bind(x.jac, dimensions=jac_dims, **extra)
+        else:
+            jac_out = x.jac
+        return JLP(
+            value=v_out,
+            jac=jac_out,
+            lap=lap_out,
+            level=x.level,
+            has_chunk_axis=False,
+            chunk_idx=x.chunk_idx,
+        )
+    if x.has_chunk_axis:
+        jac_dims = tuple(d + 1 for d in dims)
+    else:
+        jac_dims = tuple(d + 2 for d in dims)
+    if jac_dims:
+        jac_out = lax.squeeze_p.bind(x.jac, dimensions=jac_dims, **extra)
+    else:
+        jac_out = x.jac
+    return JLP(
+        value=v_out,
+        jac=jac_out,
+        lap=lap_out,
+        level=x.level,
+        has_chunk_axis=x.has_chunk_axis,
+        chunk_idx=x.chunk_idx,
+    )
+
+
+_RULE_REGISTRY[lax.squeeze_p] = _squeeze_rule
+
+
+_stack_p = lax.stack_p
+
+
+def _stack_rule(invals, params, W_levels):
+    del W_levels
+    axis = int(params["axis"])
+    extra = {k: params[k] for k in params if k != "axis"}
+
+    jlp_inputs = [v for v in invals if _is_jlp(v)]
+    levels = {v.level for v in jlp_inputs}
+    assert len(levels) == 1, f"stack: mixed JLP levels {levels}"
+    level = next(iter(levels))
+    has_chunk = jlp_inputs[0].has_chunk_axis
+    chunk_idx = jlp_inputs[0].chunk_idx
+    for v in jlp_inputs[1:]:
+        assert v.has_chunk_axis == has_chunk and v.chunk_idx == chunk_idx, (
+            "stack: inconsistent chunk metadata"
+        )
+
+    if has_chunk and axis == 0:
+        raise NotImplementedError(
+            "stack: inserting an axis before the JLP chunk axis is not supported"
+        )
+
+    values = [v.value if _is_jlp(v) else v for v in invals]
+    value_out = _stack_p.bind(*values, axis=axis, **extra)
+
+    laps = [v.lap if _is_jlp(v) else jnp.zeros_like(v) for v in invals]
+    lap_out = _stack_p.bind(*laps, axis=axis, **extra)
+
+    jac_axis = axis + (1 if has_chunk else 2)
+    ref_jac = jlp_inputs[0].jac
+    jacs = [v.jac if _is_jlp(v) else jnp.zeros_like(ref_jac) for v in invals]
+    jac_out = _stack_p.bind(*jacs, axis=jac_axis, **extra)
+    return JLP(
+        value=value_out,
+        jac=jac_out,
+        lap=lap_out,
+        level=level,
+        has_chunk_axis=has_chunk,
+        chunk_idx=chunk_idx,
+    )
+
+
+_RULE_REGISTRY[_stack_p] = _stack_rule
+
+
+def _concatenate_rule(invals, params, W_levels):
+    dim = params["dimension"]
+    extra = {k: params[k] for k in params if k != "dimension"}
+
+    jlp_inputs = [v for v in invals if _is_jlp(v)]
+    levels = set(v.level for v in jlp_inputs)
+    assert len(levels) == 1, f"concatenate: mixed JLP levels {levels}"
+    level = next(iter(levels))
+    has_chunk = jlp_inputs[0].has_chunk_axis
+    chunk_idx = jlp_inputs[0].chunk_idx
+    for v in jlp_inputs[1:]:
+        assert v.has_chunk_axis == has_chunk and v.chunk_idx == chunk_idx, (
+            "concatenate: inconsistent chunk metadata"
+        )
+    if has_chunk and dim == 0:
+        raise NotImplementedError("concatenate on chunk axis not supported")
+
+    values = [v.value if _is_jlp(v) else v for v in invals]
+    v_out = lax.concatenate_p.bind(*values, dimension=dim, **extra)
+    laps = [v.lap if _is_jlp(v) else jnp.zeros_like(v) for v in invals]
+    lap_out = lax.concatenate_p.bind(*laps, dimension=dim, **extra)
+
+    jac_dim = dim + 2 if not has_chunk else dim + 1
+    jacs = []
+    for v in invals:
+        if _is_jlp(v):
+            jacs.append(v.jac)
+        else:
+            shape_v = v.shape if hasattr(v, "shape") else jnp.asarray(v).shape
+            if has_chunk:
+                M = jlp_inputs[0].jac.shape[1]
+                jac_shape = (jlp_inputs[0].jac.shape[0], M) + tuple(shape_v[1:])
+            else:
+                M = jlp_inputs[0].jac.shape[1]
+                jac_shape = (jlp_inputs[0].jac.shape[0], M) + tuple(shape_v)
+            jacs.append(jnp.zeros(jac_shape, dtype=jlp_inputs[0].jac.dtype))
+    jac_out = lax.concatenate_p.bind(*jacs, dimension=jac_dim, **extra)
+    return JLP(
+        value=v_out,
+        jac=jac_out,
+        lap=lap_out,
+        level=level,
+        has_chunk_axis=has_chunk,
+        chunk_idx=chunk_idx,
+    )
+
+
+_RULE_REGISTRY[lax.concatenate_p] = _concatenate_rule
+
+
+def _jit_p_rule(invals, params, W_levels):
+
+    inner_jaxpr = params["jaxpr"]
+    j = inner_jaxpr.jaxpr
+    consts = inner_jaxpr.consts
+    env: dict = {}
+    for cv, c in zip(j.constvars, consts):
+        env[cv] = c
+    for iv, x in zip(j.invars, invals):
+        env[iv] = x
+    for eqn in j.eqns:
+        outvals = _eval_eqn(eqn, env, W_levels)
+        for ov, ov_val in zip(eqn.outvars, outvals):
+            env[ov] = ov_val
+    return [env[ov] for ov in j.outvars]
+
+
+from jax._src import pjit as _pjit_module
+
+_RULE_REGISTRY[_pjit_module.jit_p] = _jit_p_rule
+
+
+def _quadrilinear_merge_rule(invals, params, W_levels):
+
+    T, u_a, u_b = invals
+    assert not _is_jlp(T), "quadrilinear_merge: T must be plain"
+    assert _is_jlp(u_a) and _is_jlp(u_b), "quadrilinear_merge: u_a, u_b must be JLPs"
+    assert u_a.level == u_b.level, (
+        f"quadrilinear_merge: leg levels differ {u_a.level} vs {u_b.level}"
+    )
+    assert u_a.has_chunk_axis and u_b.has_chunk_axis, (
+        "quadrilinear_merge requires the compiled chunk axis"
+    )
+
+    k = u_a.level
+    new_k = 2 * k
+    G, d_r, _, _ = T.shape
+    d_m_eff = G * d_r
+    M = u_a.value.shape[0]
+    assert u_b.value.shape[0] == M, "quadrilinear_merge: chunked legs must agree on M"
+    u_a_2d = u_a.value.reshape(M, G, d_r)
+    u_b_2d = u_b.value.reshape(M, G, d_r)
+    raw_value_2d = jnp.einsum("ijkl,mik,mil->mij", T, u_a_2d, u_b_2d)
+    raw_value = raw_value_2d.reshape(M, d_m_eff)
+    ua_jac_2d = u_a.jac.reshape(u_a.jac.shape[0], M, G, d_r)
+    ub_jac_2d = u_b.jac.reshape(u_b.jac.shape[0], M, G, d_r)
+    jac_upper_2d = jnp.einsum(
+        "ijkl,Amik,mil->Amij",
+        T,
+        ua_jac_2d,
+        u_b_2d,
+    )
+    jac_lower_2d = jnp.einsum(
+        "ijkl,mik,Bmil->Bmij",
+        T,
+        u_a_2d,
+        ub_jac_2d,
+    )
+    jac_upper = jac_upper_2d.reshape(jac_upper_2d.shape[0], M, d_m_eff)
+    jac_lower = jac_lower_2d.reshape(jac_lower_2d.shape[0], M, d_m_eff)
+    jac_out = jnp.concatenate([jac_upper, jac_lower], axis=0)
+    ua_lap_2d = u_a.lap.reshape(M, G, d_r)
+    ub_lap_2d = u_b.lap.reshape(M, G, d_r)
+    term1_2d = jnp.einsum(
+        "ijkl,mik,mil->mij",
+        T,
+        ua_lap_2d,
+        u_b_2d,
+    )
+    term2_2d = jnp.einsum(
+        "ijkl,mik,mil->mij",
+        T,
+        u_a_2d,
+        ub_lap_2d,
+    )
+    W_2k = _W_at_level(W_levels, new_k)
+    W_off = W_2k[:, : 3 * k, 3 * k :]
+    cross_2d = jnp.einsum(
+        "ijkl,Amik,Bmil,mAB->mij",
+        T,
+        ua_jac_2d,
+        ub_jac_2d,
+        W_off,
+    )
+    lap_out_2d = term1_2d + term2_2d + 2.0 * cross_2d
+    lap_out = lap_out_2d.reshape(M, d_m_eff)
+    return JLP(
+        value=raw_value,
+        jac=jac_out,
+        lap=lap_out,
+        level=new_k,
+        has_chunk_axis=True,
+        chunk_idx=-1,
+    )
+
+
+_RULE_REGISTRY[quadrilinear_merge_p] = _quadrilinear_merge_rule
+
+
+def _eval_eqn(eqn, env, W_levels):
+    invals = []
+    for v in eqn.invars:
+        if isinstance(v, Literal):
+            invals.append(v.val)
+        else:
+            invals.append(env[v])
+    has_jlp = any(_is_jlp(x) for x in invals)
+    if not has_jlp:
+        bind_params = eqn.primitive.get_bind_params(eqn.params)
+        outvals = eqn.primitive.bind(*invals, **bind_params)
+        if not eqn.primitive.multiple_results:
+            outvals = [outvals]
+        return outvals
+    rule = _RULE_REGISTRY.get(eqn.primitive)
+    if rule is None:
+        raise NotImplementedError(
+            f"custom_lap: no rule for primitive {eqn.primitive.name!r}. "
+            f"eqn = {eqn}. Register a rule in energy/custom_lap.py."
+        )
+    outvals = rule(invals, eqn.params, W_levels)
+    if not eqn.primitive.multiple_results:
+        outvals = [outvals]
+    return outvals
+
+
+def _trace_z(fn, z, N, W_levels):
+
+    z = jnp.asarray(z)
+    assert z.shape == (N, 3), f"z must be [N={N}, 3]; got {z.shape}"
+    eye3 = jnp.eye(3, dtype=z.dtype)
+    z_jac = jnp.broadcast_to(eye3[:, None, :], (3, N, 3))
+    z_lap = jnp.zeros((N, 3), dtype=z.dtype)
+    z_jlp = JLP(
+        value=z,
+        jac=z_jac,
+        lap=z_lap,
+        level=1,
+        has_chunk_axis=True,
+        chunk_idx=-1,
+    )
+    closed = jax.make_jaxpr(fn)(z)
+    jaxpr = closed.jaxpr
+    consts = closed.consts
+    env: dict = {}
+    for cv, c in zip(jaxpr.constvars, consts):
+        env[cv] = c
+    env[jaxpr.invars[0]] = z_jlp
+    for eqn in jaxpr.eqns:
+        outvals = _eval_eqn(eqn, env, W_levels)
+        for ov, ov_val in zip(eqn.outvars, outvals):
+            env[ov] = ov_val
+    return [env[ov] for ov in jaxpr.outvars]
+
+
+def _canonical_jac(jlp: JLP):
+
+    if jlp.jac.shape[1] != 1:
+        jac = jnp.swapaxes(jlp.jac, 0, 1)
+        return jac.reshape((jlp.jac.shape[0] * jlp.jac.shape[1],) + jlp.jac.shape[2:])
+    return jlp.jac[:, 0]
+
+
+def custom_forward_laplacian_with_jac(fn: Callable, W_levels: list, N: int) -> Callable:
+
+    def lap_jac_fn(z):
+        outs = _trace_z(fn, z, N, W_levels)
+        if len(outs) == 1:
+            out = outs[0]
+            if _is_jlp(out):
+                return out.value, _canonical_jac(out), out.lap
+            value = out
+            return (
+                value,
+                jnp.zeros((3 * N,) + value.shape, dtype=value.dtype),
+                jnp.zeros_like(value),
+            )
+        values = tuple(o.value if _is_jlp(o) else o for o in outs)
+        jacs = tuple(
+            _canonical_jac(o)
+            if _is_jlp(o)
+            else jnp.zeros((3 * N,) + o.shape, dtype=o.dtype)
+            for o in outs
+        )
+        laps = tuple(o.lap if _is_jlp(o) else jnp.zeros_like(o) for o in outs)
+        return values, jacs, laps
+
+    return lap_jac_fn
+
+
+__all__ = [
+    "JLP",
+    "build_W_levels",
+    "custom_forward_laplacian_with_jac",
+    "custom_lap_active",
+    "use_custom_lap",
+]

src/hamiltonzero/energy/frame.py

@@ -0,0 +1,152 @@
+# Copyright (c) 2026 Simulacra Research Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import jax
+import jax.numpy as jnp
+import numpy as np
+from jaxtyping import Array
+
+from hamiltonzero.compiled.types import EnergyFrame, EnergyInputs, EnergyMasks
+from hamiltonzero.energy.custom_lap import build_W_levels
+
+
+def _real_dtype(dtype):
+    return jnp.real(jnp.zeros((), dtype)).dtype
+
+
+def _host_eigvalsh(x):
+    out_dtype = _real_dtype(x.dtype)
+    out_shape = jax.ShapeDtypeStruct(x.shape[:-1], out_dtype)
+
+    def callback(a):
+        values = np.linalg.eigvalsh(np.asarray(a))
+        return values.astype(np.dtype(out_dtype))
+
+    return jax.pure_callback(
+        callback,
+        out_shape,
+        x,
+        vmap_method="sequential",
+    )
+
+
+def _compute_custom_lap_views_batched(J_full, mask, mu, eps):
+    n = J_full.shape[1]
+    n_systems = J_full.shape[0]
+    dtype = J_full.dtype
+    J_matrix = jnp.transpose(J_full, (0, 1, 3, 2, 4)).reshape(n_systems, 3 * n, 3 * n)
+    J_matrix_symmetric = 0.5 * (J_matrix + jnp.swapaxes(J_matrix, -1, -2))
+    mask_3 = jnp.repeat(mask.astype(dtype), 3, axis=-1)
+    eye_3n = jnp.eye(3 * n, dtype=dtype)
+    masked_identity = eye_3n[None] * mask_3[:, None, :]
+    J_eff = (J_matrix_symmetric - (mu + eps)[:, None, None] * masked_identity) / 4.0
+    J_eff = 0.5 * (J_eff + jnp.swapaxes(J_eff, -1, -2))
+
+    eigh_epsilon = jnp.asarray(1e-6, dtype=_real_dtype(dtype))
+    eigenvalues = _host_eigvalsh(J_eff + eigh_epsilon * eye_3n[None]) - eigh_epsilon
+    lam_max = jnp.max(eigenvalues, axis=-1)
+    delta_mu = jax.nn.relu(4.0 * (lam_max + eps))
+    shift = delta_mu / 4.0
+    J_eff = J_eff - shift[:, None, None] * eye_3n[None]
+    mu_eff = mu + delta_mu
+    casimir_per_site = (mu_eff + eps) * jnp.asarray(0.75, dtype=dtype)
+    radial_const = -casimir_per_site * mask.astype(dtype).sum(axis=-1)
+    return J_eff, radial_const
+
+
+def _compute_custom_lap_views(J_full, mask, mu, eps):
+    values = _compute_custom_lap_views_batched(
+        J_full[None],
+        mask[None],
+        jnp.asarray(mu)[None],
+        jnp.asarray(eps)[None],
+    )
+    return tuple(value[0] for value in values)
+
+
+def build_energy_inputs(J_full, h, mask, mu, eps) -> EnergyInputs:
+    dtype = J_full.dtype
+    mu_array = jnp.asarray(mu, dtype=dtype)
+    eps_array = jnp.asarray(eps, dtype=dtype)
+    J_eff, radial_const = _compute_custom_lap_views(
+        J_full,
+        mask,
+        mu_array,
+        eps_array,
+    )
+    return EnergyInputs(
+        custom_lap_J_eff=J_eff,
+        custom_lap_radial_const=radial_const,
+        one_body_fields=(h,),
+    )
+
+
+def block_permutation3(perm: Array) -> Array:
+
+    components = jnp.arange(3, dtype=perm.dtype)
+    return (perm[:, None] * 3 + components[None, :]).reshape(-1)
+
+
+def route_one_body_field(field: Array, perm: Array) -> Array:
+
+    return jnp.take(field, perm, axis=0)
+
+
+def route_one_body_fields(
+    fields: Sequence[Array],
+    perm: Array,
+) -> tuple[Array, ...]:
+
+    return tuple(route_one_body_field(field, perm) for field in fields)
+
+
+def route_J_eff(J_eff: Array, perm: Array) -> Array:
+
+    block_perm = block_permutation3(perm)
+    return jnp.take(jnp.take(J_eff, block_perm, axis=0), block_perm, axis=1)
+
+
+def route_energy_inputs(energy_inputs: EnergyInputs, perm: Array) -> EnergyInputs:
+    return EnergyInputs(
+        custom_lap_J_eff=route_J_eff(energy_inputs.custom_lap_J_eff, perm),
+        custom_lap_radial_const=energy_inputs.custom_lap_radial_const,
+        one_body_fields=route_one_body_fields(energy_inputs.one_body_fields, perm),
+    )
+
+
+def compile_energy_frame(
+    energy_inputs: EnergyInputs,
+    real_mask: Array,
+    balanced_mask: Array,
+    perm: Array,
+) -> EnergyFrame:
+
+    J_eff = route_J_eff(energy_inputs.custom_lap_J_eff, perm)
+    n_sites = int(perm.shape[0])
+    frame = EnergyFrame(
+        custom_lap_J_eff=J_eff,
+        w_levels=tuple(build_W_levels(J_eff, n_sites)),
+        custom_lap_radial_const=energy_inputs.custom_lap_radial_const,
+        one_body_fields=route_one_body_fields(energy_inputs.one_body_fields, perm),
+        masks=EnergyMasks(
+            real=route_one_body_field(real_mask, perm),
+            balanced=balanced_mask,
+        ),
+    )
+    return frame
+
+
+__all__ = [
+    "block_permutation3",
+    "build_energy_inputs",
+    "compile_energy_frame",
+    "route_energy_inputs",
+    "route_J_eff",
+    "route_one_body_field",
+    "route_one_body_fields",
+]

src/hamiltonzero/energy/kernel.py

@@ -0,0 +1,196 @@
+# Copyright (c) 2026 Simulacra Research Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+import jax
+import jax.numpy as jnp
+from jaxtyping import Array, Complex, Float
+
+from hamiltonzero.compiled.execute import execute_wavefunction
+from hamiltonzero.energy.custom_lap import (
+    custom_forward_laplacian_with_jac,
+    use_custom_lap,
+)
+
+
+def _right_su2_chart_jet(
+    q: Float[Array, "N 4"],
+    z: Float[Array, "N 3"],
+) -> Float[Array, "N 4"]:
+
+    q0, q1, q2, q3 = q[:, 0], q[:, 1], q[:, 2], q[:, 3]
+    zx, zy, zz = z[:, 0], z[:, 1], z[:, 2]
+    u0 = 1.0 - 0.5 * (zx * zx + zy * zy + zz * zz)
+    u1, u2, u3 = zz, zy, zx
+    return jnp.stack(
+        [
+            q0 * u0 - q1 * u1 - q2 * u2 - q3 * u3,
+            q0 * u1 + q1 * u0 + q2 * u3 - q3 * u2,
+            q0 * u2 - q1 * u3 + q2 * u0 + q3 * u1,
+            q0 * u3 + q1 * u2 - q2 * u1 + q3 * u0,
+        ],
+        axis=-1,
+    )
+
+
+def _custom_lap_single_finetune(
+    model: Callable,
+    q: Float[Array, "N 4"],
+    t,
+    energy_frame: Any,
+):
+    if len(energy_frame.one_body_fields) != 1:
+        raise ValueError("custom-Laplacian energy requires exactly one one-body field")
+    return _custom_lap_single_from_frame(
+        model,
+        None,
+        q,
+        t,
+        J_eff=energy_frame.custom_lap_J_eff,
+        W_levels=energy_frame.w_levels,
+        field_xyz=energy_frame.one_body_fields[0],
+        radial_const=energy_frame.custom_lap_radial_const,
+    )
+
+
+def _custom_lap_single_prebuilt(
+    model: Callable,
+    q: Float[Array, "N 4"],
+    t,
+    frame: Any,
+):
+    if len(frame.one_body_fields) != 1:
+        raise ValueError("custom-Laplacian energy requires exactly one one-body field")
+    return _custom_lap_single_from_frame(
+        model,
+        None,
+        q,
+        t,
+        J_eff=frame.custom_lap_J_eff,
+        W_levels=frame.w_levels,
+        field_xyz=frame.one_body_fields[0],
+        radial_const=frame.custom_lap_radial_const,
+    )
+
+
+def _custom_lap_single_from_frame(
+    model: Callable,
+    ctx: Any,
+    q: Float[Array, "N 4"],
+    t,
+    *,
+    J_eff,
+    W_levels,
+    field_xyz,
+    radial_const,
+):
+    N = q.shape[0]
+
+    def f_entry(z):
+        q_pert = _right_su2_chart_jet(q, z)
+        re, im = model(q_pert, ctx, t)
+        return jnp.stack([re, im])
+
+    with use_custom_lap():
+        _value, jac_pair, lap_pair = custom_forward_laplacian_with_jac(
+            f_entry,
+            W_levels,
+            N,
+        )(jnp.zeros((N, 3), dtype=q.dtype))
+
+    tr_total = lap_pair[0] + 1j * lap_pair[1]
+
+    g_lie = jac_pair[:, 0] + 1j * jac_pair[:, 1]
+    quad_total = jnp.einsum("a,ab,b->", g_lie, J_eff.astype(g_lie.dtype), g_lie)
+
+    la_xyz = 0.5 * g_lie.reshape(N, 3)
+    field = (1j * jnp.einsum("ic,ic->", field_xyz.astype(g_lie.dtype), la_xyz)).astype(
+        g_lie.dtype
+    )
+
+    total = tr_total + quad_total + radial_const.astype(g_lie.dtype) + field
+
+    zero = jnp.zeros_like(total)
+    exchange = total - field
+    return total, exchange, zero, field
+
+
+def _vmc_energy_custom_lap_finetune(
+    model: Callable,
+    energy_frame: Any,
+    q: Float[Array, "... N 4"],
+    t=0.0,
+    *,
+    chunk_size: int | None = None,
+) -> tuple[
+    Complex[Array, "..."],
+    Complex[Array, "..."],
+    Complex[Array, "..."],
+    Complex[Array, "..."],
+]:
+
+    def single(qq, tt):
+        return _custom_lap_single_finetune(model, qq, tt, energy_frame)
+
+    return _run_custom_lap_batch(single, q, t, chunk_size)
+
+
+def _vmc_energy_custom_lap_prebuilt(
+    kernel: Any,
+    tree: Any,
+    energy_frame: Any,
+    q: Float[Array, "... N 4"],
+    *,
+    chunk_size: int | None = None,
+) -> tuple[
+    Complex[Array, "..."],
+    Complex[Array, "..."],
+    Complex[Array, "..."],
+    Complex[Array, "..."],
+]:
+    def model(q_pert, _ctx, _t):
+        return execute_wavefunction(kernel, tree, q_pert)
+
+    def single(qq, tt):
+        return _custom_lap_single_prebuilt(model, qq, tt, energy_frame)
+
+    return _run_custom_lap_batch(single, q, 0.0, chunk_size)
+
+
+def _run_custom_lap_batch(single, q, t, chunk_size):
+    n_sites, n_dims = q.shape[-2], q.shape[-1]
+    assert n_dims == 4, f"expected quaternion last dim 4, got {n_dims}"
+    lead = q.shape[:-2]
+    n_items = 1
+    for d in lead:
+        n_items *= d
+
+    q_flat = q.reshape(n_items, n_sites, 4)
+    t_arr = jnp.asarray(t, dtype=q.dtype)
+    t_bcast = jnp.broadcast_to(t_arr, lead if lead else ())
+    t_flat = t_bcast.reshape(n_items) if lead else jnp.broadcast_to(t_arr, (n_items,))
+
+    with jax.default_matmul_precision("highest"):
+        if chunk_size is None or chunk_size >= n_items:
+            total, exchange, casimir, field = jax.vmap(single)(q_flat, t_flat)
+        else:
+            total, exchange, casimir, field = jax.lax.map(
+                lambda x: single(x[0], x[1]),
+                (q_flat, t_flat),
+                batch_size=chunk_size,
+            )
+
+    out_shape = lead if lead else ()
+    return (
+        total.reshape(out_shape),
+        exchange.reshape(out_shape),
+        casimir.reshape(out_shape),
+        field.reshape(out_shape),
+    )
+
+
+__all__ = []

src/hamiltonzero/evaluation/__init__.py

@@ -0,0 +1,42 @@
+# Copyright (c) 2026 Simulacra Research Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+from .backend import (
+    BeamCandidates,
+    CanonicalContext,
+    EvalBackend,
+    LargeNCompilation,
+    MCMCPopulation,
+)
+from .runner import evaluate
+from .runtime import DefaultEvalBackend, build_eval_backend
+from .statistics import (
+    ChannelMetrics,
+    EnergyWindow,
+    P01_TWO_SIDED,
+    select_winner_per_physical,
+    standard_error_from_tailstd,
+    welch_band_walkermean,
+)
+from .types import ContestCandidate, ContestResult, EvalMetric, EvalResult
+
+__all__ = [
+    "BeamCandidates",
+    "CanonicalContext",
+    "ChannelMetrics",
+    "ContestCandidate",
+    "ContestResult",
+    "DefaultEvalBackend",
+    "EnergyWindow",
+    "EvalBackend",
+    "EvalMetric",
+    "EvalResult",
+    "LargeNCompilation",
+    "MCMCPopulation",
+    "P01_TWO_SIDED",
+    "evaluate",
+    "build_eval_backend",
+    "select_winner_per_physical",
+    "standard_error_from_tailstd",
+    "welch_band_walkermean",
+]

src/hamiltonzero/evaluation/backend.py

@@ -0,0 +1,148 @@
+# Copyright (c) 2026 Simulacra Research Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Protocol
+
+from hamiltonzero.config import EnergyConfig, EvalMCMCConfig, ModelConfig
+
+
+@dataclass(frozen=True, slots=True)
+class CanonicalContext:
+    context: Any
+    old_inverse: Any
+
+
+@dataclass(frozen=True, slots=True)
+class BeamCandidates:
+    permutations: Any
+    log_probabilities: Any
+
+
+@dataclass(frozen=True, slots=True)
+class LargeNCompilation:
+    wavefunction: Any
+    permutation: Any
+    log_probability: Any
+
+
+@dataclass(frozen=True, slots=True)
+class MCMCPopulation:
+    q: Any
+    sigma: Any
+    beta: Any
+
+
+class EvalBackend(Protocol):
+    def load_system(self, path: Path, energy: EnergyConfig) -> Any: ...
+
+    def load_model(
+        self,
+        checkpoint: Path,
+        config: ModelConfig,
+        key: Any,
+        context: Any,
+        *,
+        contextualizer_attention: str | None,
+    ) -> Any: ...
+
+    def canonicalize_context(self, context: Any) -> CanonicalContext: ...
+
+    def embedded_route(self, model: Any) -> Any | None: ...
+
+    def route_context(
+        self,
+        context: Any,
+        permutation: Any,
+        *,
+        compact_custom_lap: bool,
+    ) -> Any: ...
+
+    def release_context(self, context: Any) -> None: ...
+
+    def virtual_context(self, context: Any, permutations: Any) -> Any: ...
+
+    def beam_candidates(
+        self,
+        model: Any,
+        context: Any,
+        *,
+        beam_width: int,
+        top_k: int,
+        temperature: float,
+    ) -> BeamCandidates: ...
+
+    def compile_single(self, model: Any, routed_context: Any) -> Any: ...
+
+    def compile_embedded(self, model: Any) -> Any: ...
+
+    def compile_candidates(
+        self,
+        model: Any,
+        canonical_context: Any,
+        permutations: Any,
+    ) -> Any: ...
+
+    def select_candidate(self, wavefunctions: Any, winner: int) -> Any: ...
+
+    def compile_large_n(
+        self,
+        model: Any,
+        canonical_context: Any,
+        *,
+        sequence_shards: int,
+        pair_tile_size: int,
+        temperature: float,
+    ) -> LargeNCompilation: ...
+
+    def prepare_singular(
+        self,
+        model: Any,
+        context: Any,
+        state: Any,
+    ) -> tuple[Any, Any, Any]: ...
+
+    def initialize_mcmc(
+        self,
+        key: Any,
+        model: Any,
+        context: Any,
+        config: EvalMCMCConfig,
+    ) -> Any: ...
+
+    def step_mcmc(
+        self,
+        state: Any,
+        model: Any,
+        context: Any,
+        *,
+        replica_steps: int,
+        walker_chunk_size: int,
+    ) -> Any: ...
+
+    def adapt_mcmc(self, state: Any, config: EvalMCMCConfig) -> Any: ...
+
+    def route_mcmc(self, state: Any, permutation: Any) -> Any: ...
+
+    def mcmc_population(self, state: Any) -> MCMCPopulation: ...
+
+    def replace_mcmc_population(
+        self,
+        state: Any,
+        population: MCMCPopulation,
+    ) -> Any: ...
+
+    def cold_walkers(self, state: Any) -> Any: ...
+
+    def custom_lap_energy(
+        self,
+        model: Any,
+        context: Any,
+        q: Any,
+        config: EnergyConfig,
+    ) -> tuple[Any, Any, Any, Any]: ...
+
+    def block_until_ready(self, value: Any) -> None: ...

src/hamiltonzero/evaluation/greedy_router.py

@@ -0,0 +1,125 @@
+# Copyright (c) 2026 Simulacra Research Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from functools import partial
+
+import jax
+from jax.sharding import Mesh, NamedSharding, PartitionSpec as P
+
+from hamiltonzero.model.route_pointer import TreePrefixPointerMHSEA
+
+
+def _ring_permute_rows_local(values, route_ids, *, axis_size: int):
+
+    local_rows = values.shape[0]
+    lane = jax.lax.axis_index("seq").astype(jax.numpy.int32)
+    local_ids = jax.lax.dynamic_slice_in_dim(
+        route_ids,
+        lane * local_rows,
+        local_rows,
+        axis=0,
+    )
+    owner = local_ids // local_rows
+    within_owner = local_ids % local_rows
+    output0 = jax.numpy.zeros_like(values)
+
+    def take_from(panel, origin, output):
+        selected = panel[within_owner]
+        mask = owner == origin
+        while mask.ndim < selected.ndim:
+            mask = mask[..., None]
+        return jax.numpy.where(mask, selected, output)
+
+    origin0 = lane
+    output0 = take_from(values, origin0, output0)
+    permutation = [(i, (i + 1) % axis_size) for i in range(axis_size)]
+
+    def step(carry, _):
+        panel, origin, output = carry
+        panel = jax.lax.ppermute(panel, "seq", permutation)
+        origin = (origin - jax.numpy.asarray(1, jax.numpy.int32)) % axis_size
+        output = take_from(panel, origin, output)
+        return (panel, origin, output), None
+
+    (_, _, output), _ = jax.lax.scan(
+        step,
+        (values, origin0, output0),
+        xs=None,
+        length=axis_size - 1,
+    )
+    return output
+
+
+def _make_row_permute(mesh: Mesh) -> Callable:
+    axis_size = int(mesh.shape["seq"])
+    spec = P("seq", None, None)
+    if axis_size == 1:
+        return lambda values, route_ids: values[route_ids]
+    return jax.shard_map(
+        partial(_ring_permute_rows_local, axis_size=axis_size),
+        mesh=mesh,
+        in_specs=(spec, P()),
+        out_specs=spec,
+        check_vma=False,
+    )
+
+
+def build_compact_greedy_router(
+    *,
+    mesh: Mesh,
+    decoder_template: TreePrefixPointerMHSEA,
+    pair_tile_size: int = 128,
+) -> Callable:
+
+    if tuple(mesh.axis_names) != ("seq",):
+        raise ValueError("compact greedy router requires a one-dimensional 'seq' mesh")
+    if int(mesh.shape["seq"]) < 1:
+        raise ValueError("compact greedy router requires at least one seq lane")
+    if not isinstance(decoder_template, TreePrefixPointerMHSEA):
+        raise TypeError("decoder_template must be TreePrefixPointerMHSEA")
+    if isinstance(pair_tile_size, bool) or int(pair_tile_size) < 1:
+        raise ValueError("pair_tile_size must be a positive integer")
+
+    rep = NamedSharding(mesh, P())
+    seq_vec = NamedSharding(mesh, P("seq", None))
+    seq_edge = NamedSharding(mesh, P("seq", None, None))
+    decoder_rep = jax.tree_util.tree_map(lambda _leaf: rep, decoder_template)
+    row_permute = _make_row_permute(mesh)
+
+    def decode(decoder, h, edge, mask, global_feat, tau, real_mask):
+
+        h = jax.lax.with_sharding_constraint(h, seq_vec)
+        edge = jax.lax.with_sharding_constraint(edge, seq_edge)
+        perm, logp = decoder._decode_greedy_compact(
+            h,
+            edge,
+            mask,
+            global_feat=global_feat,
+            tau=tau,
+            real_mask=real_mask,
+            sequence_mesh=mesh,
+            pair_tile_size=int(pair_tile_size),
+            row_permute_fn=row_permute,
+        )
+        return perm, logp
+
+    return jax.jit(
+        decode,
+        in_shardings=(
+            decoder_rep,
+            seq_vec,
+            seq_edge,
+            rep,
+            rep,
+            rep,
+            rep,
+        ),
+        out_shardings=(rep, rep),
+    )
+
+
+__all__ = ["build_compact_greedy_router"]

src/hamiltonzero/evaluation/large_n.py

@@ -0,0 +1,371 @@
+# Copyright (c) 2026 Simulacra Research Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+
+from __future__ import annotations
+
+import gc
+from typing import NamedTuple
+
+import jax
+import jax.numpy as jnp
+import numpy as np
+from jax.sharding import Mesh, NamedSharding, PartitionSpec as P
+
+from hamiltonzero.compiled.tree import bind_physical_compiler_kernel
+from hamiltonzero.compiled.trunk import (
+    bind_shared_kernel,
+    bind_trunk_compiler_kernel,
+)
+from hamiltonzero.compiled.types import CompiledWaveFunction
+from hamiltonzero.model.route_pointer import TreePrefixPointerMHSEA
+from .sequence_trunk import (
+    build_sequence_pair_permute,
+    build_sequence_parallel_contextualizer,
+    build_sequence_parallel_edge_global_update,
+    build_sequence_parallel_physical_leaf,
+    build_sequence_parallel_physical_reducer,
+    build_sequence_parallel_shared_trunk,
+)
+from .greedy_router import build_compact_greedy_router
+
+
+class LargeNCompiledEvalResult(NamedTuple):
+    wavefunction: CompiledWaveFunction
+    perm: jax.Array
+    logp: jax.Array
+
+
+def _sequence_mesh(n: int, requested_shards: int) -> Mesh:
+    devices = tuple(jax.devices())
+    shards = len(devices) if requested_shards == 0 else requested_shards
+    if shards < 1 or shards > len(devices):
+        raise ValueError(
+            f"compiled eval requested {shards} seq shards, but JAX exposes "
+            f"{len(devices)} devices"
+        )
+    if n % shards:
+        raise ValueError(f"N={n} must be divisible by seq_shards={shards}")
+    local_rows = n // shards
+    if n & (n - 1) or local_rows & (local_rows - 1):
+        raise ValueError(
+            "large-N physical compilation requires a power-of-two padded "
+            f"width and power-of-two rows per lane; got N={n}, "
+            f"local_rows={local_rows}"
+        )
+    return Mesh(np.asarray(devices[:shards], dtype=object), ("seq",))
+
+
+def _replicate(tree, sharding: NamedSharding):
+    return jax.device_put(tree, jax.tree_util.tree_map(lambda _leaf: sharding, tree))
+
+
+class _LargeNXlaTreePrefixPointer(TreePrefixPointerMHSEA):
+    def _resolve_heavy_attn_impl(self, n: int):
+        del n
+        return None
+
+    def _resolve_tree_attn_impl(self):
+        return None
+
+    def _route_attention(
+        self,
+        q,
+        k,
+        v,
+        edge_bias,
+        key_mask,
+        *,
+        impl,
+        key_mask_only=False,
+        attention_mask=None,
+        sequence_axis_name=None,
+        sequence_mesh=None,
+    ):
+        del impl, key_mask_only
+        dtype = q.dtype
+        valid = key_mask.astype(bool)[:, None, :]
+        if attention_mask is not None:
+            valid = valid & attention_mask.astype(bool)
+        has_key = jnp.any(valid, axis=-1)
+        q_c = q.astype(jnp.float32)
+        k_c = k.astype(jnp.float32)
+        v_c = v.astype(jnp.float32)
+        bias_c = edge_bias.astype(jnp.float32)
+        if sequence_axis_name is not None:
+
+            def sharding(*axes):
+                spec = P(*axes)
+                return (
+                    NamedSharding(sequence_mesh, spec)
+                    if sequence_mesh is not None
+                    else spec
+                )
+
+            q_c = jax.lax.with_sharding_constraint(
+                q_c, sharding(None, sequence_axis_name, None, None)
+            )
+            k_c = jax.lax.with_sharding_constraint(
+                k_c, sharding(None, None, None, None)
+            )
+            v_c = jax.lax.with_sharding_constraint(
+                v_c, sharding(None, None, None, None)
+            )
+            bias_c = jax.lax.with_sharding_constraint(
+                bias_c, sharding(None, sequence_axis_name, None, None)
+            )
+        logits = jnp.einsum("bihd,bjhd->bhij", q_c, k_c)
+        logits = logits / jnp.sqrt(jnp.asarray(self.d_head, dtype=jnp.float32))
+        logits = logits + jnp.transpose(bias_c, (0, 3, 1, 2))
+        if sequence_axis_name is not None:
+            logits = jax.lax.with_sharding_constraint(
+                logits, sharding(None, None, sequence_axis_name, None)
+            )
+        logits = jnp.where(
+            valid[:, None, :, :],
+            logits,
+            jnp.asarray(-1.0e30, dtype=jnp.float32),
+        )
+        if sequence_axis_name is not None:
+            logits = jax.lax.with_sharding_constraint(
+                logits, sharding(None, None, sequence_axis_name, None)
+            )
+        alpha = jax.nn.softmax(logits, axis=-1)
+        if sequence_axis_name is not None:
+            alpha = jax.lax.with_sharding_constraint(
+                alpha, sharding(None, None, sequence_axis_name, None)
+            )
+        out = jnp.einsum("bhij,bjhd->bihd", alpha, v_c)
+        if sequence_axis_name is not None:
+            out = jax.lax.with_sharding_constraint(
+                out, sharding(None, sequence_axis_name, None, None)
+            )
+        out = out.astype(dtype)
+        return jnp.where(has_key[..., None, None], out, jnp.zeros_like(out))
+
+
+def _large_n_xla_decoder_view(decoder: TreePrefixPointerMHSEA):
+    compiled = object.__new__(_LargeNXlaTreePrefixPointer)
+    compiled.__dict__.update(decoder.__dict__)
+    return compiled
+
+
+def _validate_large_n_model(model) -> None:
+    decoder = getattr(model, "route_decoder", None)
+    failures: list[str] = []
+    if not isinstance(decoder, TreePrefixPointerMHSEA):
+        failures.append("route decoder must be TreePrefixPointerMHSEA")
+    if getattr(model, "route_contextualizer", None) is None:
+        failures.append("route contextualizer must be enabled")
+    if getattr(model, "gladder_fork_route", None) is None:
+        failures.append("route global fork must be enabled")
+    if getattr(model, "readout_leaf_context", None) is None:
+        failures.append("physical contextualizer must be enabled")
+    if failures:
+        raise ValueError(
+            "unsupported large-N eval compiler model: " + "; ".join(failures)
+        )
+
+
+def _validate_context(ctx) -> int:
+    jdp = jnp.asarray(ctx.J_double_prime)
+    mask = jnp.asarray(ctx.mask)
+    bmask = jnp.asarray(ctx.bmask)
+    h_prime = jnp.asarray(ctx.h_prime)
+    if jdp.ndim != 3 or jdp.shape[-1] != 10:
+        raise ValueError("ctx.J_double_prime must have shape [N,N,10]")
+    n = int(jdp.shape[0])
+    if jdp.shape[1] != n:
+        raise ValueError("ctx.J_double_prime pair axes must be square")
+    if mask.shape != (n,) or bmask.shape != (n,):
+        raise ValueError("ctx.mask and ctx.bmask must both have shape [N]")
+    if h_prime.shape != (n, 3):
+        raise ValueError("ctx.h_prime must have shape [N,3]")
+    if jdp.dtype != jnp.float32 or h_prime.dtype != jnp.float32:
+        raise TypeError(
+            "large-N eval keeps streamed pair/frontier arithmetic in fp32; "
+            f"got J={jdp.dtype}, h={h_prime.dtype}"
+        )
+    return n
+
+
+def compile_large_n_eval_wavefunction(
+    model,
+    ctx,
+    *,
+    seq_shards: int = 0,
+    pair_tile_size: int = 128,
+    tau: float = 1.0,
+) -> LargeNCompiledEvalResult:
+
+    _validate_large_n_model(model)
+    n = _validate_context(ctx)
+    if pair_tile_size < 1:
+        raise ValueError("pair_tile_size must be positive")
+    mesh = _sequence_mesh(n, int(seq_shards))
+    rep = NamedSharding(mesh, P())
+    seq_edge = NamedSharding(mesh, P("seq", None, None))
+
+    trunk_kernel = _replicate(bind_trunk_compiler_kernel(model), rep)
+    route_contextualizer = _replicate(model.route_contextualizer, rep)
+    route_global_fork = _replicate(model.gladder_fork_route, rep)
+    decoder = _replicate(_large_n_xla_decoder_view(model.route_decoder), rep)
+    physical_kernel = _replicate(bind_physical_compiler_kernel(model), rep)
+
+    jdp = jax.device_put(jnp.asarray(ctx.J_double_prime), seq_edge)
+    h_prime, real_mask, structural_mask = jax.device_put(
+        (
+            jnp.asarray(ctx.h_prime),
+            jnp.asarray(ctx.mask),
+            jnp.asarray(ctx.bmask),
+        ),
+        rep,
+    )
+
+    trunk_entry = build_sequence_parallel_shared_trunk(
+        mesh=mesh,
+        kernel_template=trunk_kernel,
+        featurizer_tile_size=int(pair_tile_size),
+    )
+    trunk = trunk_entry(trunk_kernel, jdp, h_prime, real_mask, structural_mask)
+
+    route_context_entry = build_sequence_parallel_contextualizer(
+        mesh=mesh,
+        contextualizer_template=route_contextualizer,
+        g_template=trunk.global_stream,
+        tile_size=int(pair_tile_size),
+    )
+    route_node, route_edge, route_g = route_context_entry(
+        route_contextualizer,
+        trunk.node_raw,
+        trunk.edge_raw,
+        real_mask,
+        structural_mask,
+        trunk.global_stream,
+    )
+    route_global_entry = build_sequence_parallel_edge_global_update(
+        mesh=mesh,
+        module_template=route_global_fork,
+        tile_size=int(pair_tile_size),
+    )
+    route_global = route_global_entry(
+        route_global_fork, route_g, route_edge, structural_mask
+    )
+
+    route_entry = build_compact_greedy_router(
+        mesh=mesh,
+        decoder_template=decoder,
+        pair_tile_size=int(pair_tile_size),
+    )
+    perm, logp = route_entry(
+        decoder,
+        route_node,
+        route_edge,
+        structural_mask,
+        route_global,
+        jnp.asarray(tau, dtype=jnp.float32),
+        real_mask,
+    )
+
+    jax.block_until_ready((perm, logp))
+    del route_node, route_edge, route_g, route_global
+
+    pair_permute = build_sequence_pair_permute(mesh=mesh)
+    routed_node, routed_edge = pair_permute(trunk.node_raw, trunk.edge_raw, perm)
+    leaf_real = real_mask[perm]
+    global_stream = trunk.global_stream
+
+    jax.block_until_ready((routed_node, routed_edge, leaf_real, global_stream))
+    del (
+        trunk,
+        trunk_kernel,
+        route_contextualizer,
+        route_global_fork,
+        decoder,
+        jdp,
+        h_prime,
+        real_mask,
+        trunk_entry,
+        route_context_entry,
+        route_global_entry,
+        route_entry,
+        pair_permute,
+    )
+    gc.collect()
+
+    physical_context_entry = build_sequence_parallel_contextualizer(
+        mesh=mesh,
+        contextualizer_template=physical_kernel.contextualizer,
+        g_template=global_stream,
+        tile_size=int(pair_tile_size),
+    )
+    physical_node, physical_edge, physical_context_g = physical_context_entry(
+        physical_kernel.contextualizer,
+        routed_node,
+        routed_edge,
+        leaf_real,
+        structural_mask,
+        global_stream,
+    )
+    jax.block_until_ready((physical_node, physical_edge, physical_context_g))
+    del routed_node, routed_edge, global_stream, physical_context_entry
+    gc.collect()
+
+    physical_global_entry = build_sequence_parallel_edge_global_update(
+        mesh=mesh,
+        module_template=physical_kernel.global_fork,
+        tile_size=int(pair_tile_size),
+    )
+    physical_global = physical_global_entry(
+        physical_kernel.global_fork,
+        physical_context_g,
+        physical_edge,
+        structural_mask,
+    )
+    jax.block_until_ready(physical_global)
+    del physical_context_g, physical_global_entry
+    gc.collect()
+
+    physical_leaf_entry = build_sequence_parallel_physical_leaf(
+        mesh=mesh,
+        kernel_template=physical_kernel,
+    )
+    leaf_h, c_rows = physical_leaf_entry(
+        physical_kernel,
+        physical_node,
+        physical_global,
+    )
+    jax.block_until_ready((leaf_h, c_rows))
+    del physical_node, physical_leaf_entry
+    gc.collect()
+
+    physical_reducer_entry = build_sequence_parallel_physical_reducer(
+        mesh=mesh,
+        kernel_template=physical_kernel,
+        edge_template=physical_edge,
+        replicate_threshold=min(512, n),
+        contextualizer_tile_size=int(pair_tile_size),
+    )
+    tree = physical_reducer_entry(
+        physical_kernel,
+        physical_edge,
+        leaf_h,
+        c_rows,
+        leaf_real,
+        structural_mask,
+        physical_global,
+        perm,
+    )
+    jax.block_until_ready(tree)
+
+    return LargeNCompiledEvalResult(
+        wavefunction=CompiledWaveFunction(bind_shared_kernel(model), tree),
+        perm=perm,
+        logp=logp,
+    )
+
+
+__all__ = [
+    "LargeNCompiledEvalResult",
+    "compile_large_n_eval_wavefunction",
+]

src/hamiltonzero/evaluation/pallas_mha.py

@@ -0,0 +1,164 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Copyright 2023 The JAX Authors.
+# Modifications copyright (c) 2026 Simulacra Research Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+from __future__ import annotations
+
+import dataclasses
+import functools
+import math
+from typing import Any
+
+import jax
+import jax.numpy as jnp
+from jax import lax
+from jax.experimental import pallas as pl
+from jax.experimental.pallas import triton as plgpu
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class BlockSizes:
+    block_q: int
+    block_k: int
+
+    @classmethod
+    def get_default(cls):
+        return cls(block_q=128, block_k=128)
+
+
+def noncausal_bias_mha_forward_kernel(
+    q_ref,
+    k_ref,
+    v_ref,
+    bias_ref,
+    o_ref: Any,
+    *,
+    block_q: int,
+    block_k: int,
+    head_dim: int,
+):
+    seq_len = k_ref.shape[0]
+    start_q = pl.program_id(0)
+    head_dim_padded = q_ref.shape[-1]
+    m_i = jnp.zeros(block_q, dtype=jnp.float32) - float("inf")
+    l_i = jnp.zeros(block_q, dtype=jnp.float32)
+    o = jnp.zeros((block_q, head_dim_padded), dtype=jnp.float32)
+    curr_q_slice = pl.dslice(start_q * block_q, block_q)
+    head_mask = (jnp.arange(head_dim_padded) < head_dim)[None, :]
+    q = plgpu.load(q_ref, mask=head_mask, other=0.0)
+
+    def body(start_k, carry):
+        o_prev, m_prev, l_prev = carry
+        curr_k_slice = pl.dslice(start_k * block_k, block_k)
+        k = plgpu.load(k_ref.at[curr_k_slice, :], mask=head_mask, other=0.0)
+        qk = pl.dot(q, k.T)
+        bias = plgpu.load(bias_ref.at[curr_q_slice, curr_k_slice])
+        qk += bias
+        qk *= math.log2(math.e)
+        qk = qk.astype(q_ref.dtype)
+        m_curr = jnp.max(qk, axis=-1)
+        m_next = jnp.maximum(m_prev, m_curr)
+        correction = jnp.exp2(m_prev - m_next)
+        l_prev_corr = correction * l_prev
+        s_curr = jnp.exp2(qk - m_next[:, None])
+        l_curr = s_curr.sum(axis=-1)
+        l_next = l_prev_corr + l_curr
+        o_prev_corr = correction[:, None] * o_prev
+        v = plgpu.load(v_ref.at[curr_k_slice, :], mask=head_mask)
+        o_curr = pl.dot(s_curr.astype(v.dtype), v)
+        o_next = o_prev_corr + o_curr
+        return o_next, m_next, l_next
+
+    upper_bound = pl.cdiv(seq_len, block_k)
+    o, _m_i, l_i = lax.fori_loop(0, upper_bound, body, (o, m_i, l_i))
+    o /= l_i[:, None]
+    plgpu.store(o_ref.at[:, : o.shape[-1]], o.astype(o_ref.dtype), mask=head_mask)
+
+
+@functools.partial(jax.jit, static_argnames=["block_sizes"])
+def noncausal_bias_mha(
+    q,
+    k,
+    v,
+    bias,
+    *,
+    block_sizes: BlockSizes = BlockSizes.get_default(),
+):
+    batch_size, q_seq_len, num_heads, head_dim = q.shape
+    kv_seq_len = k.shape[1]
+    block_q = min(block_sizes.block_q, q_seq_len)
+    block_k = min(block_sizes.block_k, kv_seq_len)
+    head_dim_padded = pl.next_power_of_2(head_dim)
+    if (q.shape[-1] != k.shape[-1]) or (q.shape[-1] != v.shape[-1]):
+        raise ValueError(
+            "This kernel expects q, k, and v to have the same head dimension, "
+            f"but found {q.shape=}, {k.shape=}, {v.shape=}."
+        )
+    if bias.shape != (batch_size, q_seq_len, kv_seq_len, num_heads):
+        raise ValueError(
+            f"bias must have shape [batch, query, key, heads]; got {bias.shape}"
+        )
+    if q_seq_len % block_q != 0:
+        raise ValueError(f"{q_seq_len=} must be a multiple of {block_q=}")
+    if kv_seq_len % block_k != 0:
+        raise ValueError(f"{kv_seq_len=} must be a multiple of {block_k=}")
+    grid = (pl.cdiv(q_seq_len, block_q), batch_size, num_heads)
+    num_warps = 4 if head_dim <= 64 else 8
+    kernel = functools.partial(
+        noncausal_bias_mha_forward_kernel,
+        block_q=block_q,
+        block_k=block_k,
+        head_dim=head_dim,
+    )
+    in_specs = [
+        pl.BlockSpec(
+            (None, block_q, None, head_dim_padded),
+            lambda i, j, k: (j, i, k, 0),
+        ),
+        pl.BlockSpec(
+            (None, kv_seq_len, None, head_dim_padded),
+            lambda i, j, k: (j, 0, k, 0),
+        ),
+        pl.BlockSpec(
+            (None, kv_seq_len, None, head_dim_padded),
+            lambda i, j, k: (j, 0, k, 0),
+        ),
+        pl.BlockSpec(
+            (None, block_q, kv_seq_len, None),
+            lambda i, j, k: (j, i, 0, k),
+        ),
+    ]
+    out_shape = [q]
+    out_specs = [
+        pl.BlockSpec(
+            (None, block_q, None, head_dim_padded),
+            lambda i, j, k: (j, i, k, 0),
+        )
+    ]
+    out = pl.pallas_call(
+        kernel,
+        grid=grid,
+        in_specs=in_specs,
+        out_specs=out_specs,
+        compiler_params=plgpu.CompilerParams(num_warps=num_warps, num_stages=2),
+        out_shape=out_shape,
+        name="mha_forward",
+    )(q, k, v, bias)
+    return out[0]
+
+
+__all__ = ["BlockSizes", "noncausal_bias_mha"]

src/hamiltonzero/evaluation/runner.py

@@ -0,0 +1,509 @@
+# Copyright (c) 2026 Simulacra Research Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import time
+from dataclasses import replace
+from typing import Any, Callable
+
+import jax
+import jax.numpy as jnp
+import numpy as np
+
+from hamiltonzero.config import EvalConfig
+
+from .backend import EvalBackend, MCMCPopulation
+from .statistics import EnergyWindow, P01_TWO_SIDED, select_winner_per_physical
+from .types import ContestCandidate, ContestResult, EvalMetric, EvalResult
+
+
+def _permute_q_prefix(q, permutations):
+    index = jnp.broadcast_to(permutations[:, None, None, :, None], q.shape)
+    return jnp.take_along_axis(q, index, axis=3)
+
+
+def _collapse_to_winner(q_virtual, permutations, winner_idx, *, P, K):
+    winner_idx = jnp.asarray(winner_idx, dtype=jnp.int32)
+    inverse = jnp.argsort(permutations, axis=-1)
+    q_canonical = _permute_q_prefix(q_virtual, inverse)
+    batch_per_candidate = q_canonical.shape[1]
+    tail = q_canonical.shape[2:]
+    q_physical = q_canonical.reshape((P, K, batch_per_candidate) + tail).reshape(
+        (P, K * batch_per_candidate) + tail
+    )
+    permutations_pk = permutations.reshape((P, K, -1))
+    route = jnp.take_along_axis(
+        permutations_pk,
+        winner_idx[:, None, None],
+        axis=1,
+    )[:, 0]
+    return _permute_q_prefix(q_physical, route), route
+
+
+def _gather_winner_ladder(values, winner_idx, *, P, K):
+    winner_idx = jnp.asarray(winner_idx, dtype=jnp.int32)
+    values_pk = values.reshape((P, K) + values.shape[1:])
+    index = winner_idx[(slice(None), None) + (None,) * (values_pk.ndim - 2)]
+    return jnp.take_along_axis(values_pk, index, axis=1)[:, 0]
+
+
+def _as_batched_route(permutation):
+    value = jnp.asarray(permutation, dtype=jnp.int32)
+    if value.ndim == 1:
+        value = value[None, :]
+    if value.ndim != 2 or value.shape[0] != 1:
+        raise ValueError("single-system evaluation requires a route with shape [1, N]")
+    return value
+
+
+def _compose_walker_route(old_inverse, route):
+    return jnp.take_along_axis(
+        jnp.asarray(old_inverse, dtype=jnp.int32),
+        route,
+        axis=-1,
+    )
+
+
+def _adapt(backend: EvalBackend, state: Any, config: EvalConfig):
+    return backend.adapt_mcmc(state, config.mcmc)
+
+
+def _burn_in(
+    backend: EvalBackend,
+    state: Any,
+    model: Any,
+    context: Any,
+    config: EvalConfig,
+    *,
+    iterations: int,
+    replica_steps: int,
+):
+    for _ in range(int(iterations)):
+        state = backend.step_mcmc(
+            state,
+            model,
+            context,
+            replica_steps=int(replica_steps),
+            walker_chunk_size=int(config.mcmc.walker_chunk_size),
+        )
+        backend.block_until_ready(backend.cold_walkers(state))
+        state = _adapt(backend, state, config)
+    return state
+
+
+def _measure(
+    backend: EvalBackend,
+    state: Any,
+    model: Any,
+    context: Any,
+    config: EvalConfig,
+    *,
+    started: float,
+    metric_sink: Callable[[EvalMetric], None] | None,
+):
+    window = EnergyWindow(
+        config.measurements,
+        systems=1,
+        batch_size=config.mcmc.batch_size,
+    )
+    for step in range(config.measurements):
+        step_started = time.perf_counter()
+        state = backend.step_mcmc(
+            state,
+            model,
+            context,
+            replica_steps=int(config.mcmc.steps),
+            walker_chunk_size=int(config.mcmc.walker_chunk_size),
+        )
+        q_cold = backend.cold_walkers(state)
+        total, exchange, _casimir, field = backend.custom_lap_energy(
+            model,
+            context,
+            q_cold,
+            config.energy,
+        )
+        backend.block_until_ready(total)
+        window.push(total, exchange, field)
+        state = _adapt(backend, state, config)
+        if metric_sink is not None:
+            energy = np.asarray(total).real
+            metric_sink(
+                EvalMetric(
+                    step=step,
+                    energy=float(np.mean(energy)),
+                    energy_std=float(np.std(energy)),
+                    step_walltime=float(time.perf_counter() - step_started),
+                    walltime=float(time.perf_counter() - started),
+                )
+            )
+    return state, window
+
+
+def _ordinary(
+    backend: EvalBackend,
+    model: Any,
+    context: Any,
+    canonical,
+    mcmc_key,
+    config: EvalConfig,
+):
+    state = backend.initialize_mcmc(mcmc_key, model, context, config.mcmc)
+    candidates = backend.beam_candidates(
+        model,
+        canonical.context,
+        beam_width=int(config.contest_beam_width),
+        top_k=1,
+        temperature=float(config.route_temperature),
+    )
+    permutations = jnp.asarray(candidates.permutations, dtype=jnp.int32)
+    if permutations.ndim != 3 or permutations.shape[:2] != (1, 1):
+        raise ValueError("ordinary eval router must return shape [1, 1, N]")
+    route = permutations[:, 0]
+    walker_route = _compose_walker_route(canonical.old_inverse, route)
+    routed_context = backend.route_context(
+        canonical.context,
+        route,
+        compact_custom_lap=False,
+    )
+    state = backend.route_mcmc(state, walker_route)
+    wavefunction = backend.compile_single(model, routed_context)
+    backend.block_until_ready(wavefunction)
+    logp = float(np.asarray(candidates.log_probabilities)[0, 0])
+    return wavefunction, routed_context, state, route, logp, None
+
+
+def _compiled_finetune_ordinary(
+    backend: EvalBackend,
+    model: Any,
+    context: Any,
+    canonical,
+    embedded_route,
+    mcmc_key,
+    config: EvalConfig,
+):
+    state = backend.initialize_mcmc(mcmc_key, model, context, config.mcmc)
+    route = _as_batched_route(embedded_route)
+    if route.shape[-1] != canonical.context.mask.shape[-1]:
+        raise ValueError(
+            "compiled fine-tune route width does not match the evaluation system"
+        )
+    walker_route = _compose_walker_route(canonical.old_inverse, route)
+    routed_context = backend.route_context(
+        canonical.context,
+        route,
+        compact_custom_lap=False,
+    )
+    state = backend.route_mcmc(state, walker_route)
+    wavefunction = backend.compile_embedded(model)
+    backend.block_until_ready(wavefunction)
+    return wavefunction, routed_context, state, route, None, None
+
+
+def _contest(
+    backend: EvalBackend,
+    model: Any,
+    canonical,
+    root_key,
+    config: EvalConfig,
+):
+    K = int(config.contest_candidates)
+    batch_per_candidate = int(config.mcmc.batch_size) // K
+    candidates = backend.beam_candidates(
+        model,
+        canonical.context,
+        beam_width=int(config.contest_beam_width),
+        top_k=K,
+        temperature=float(config.route_temperature),
+    )
+    beam_permutations = jnp.asarray(candidates.permutations, dtype=jnp.int32)
+    if beam_permutations.ndim != 3 or beam_permutations.shape[:2] != (1, K):
+        raise ValueError(f"contest router must return shape [1, {K}, N]")
+    n_sites = int(beam_permutations.shape[-1])
+    permutations = beam_permutations.reshape((K, n_sites))
+    virtual_context = backend.virtual_context(canonical.context, permutations)
+    race_mcmc = replace(config.mcmc, batch_size=batch_per_candidate)
+    state = backend.initialize_mcmc(
+        jax.random.fold_in(root_key, 7411),
+        model,
+        virtual_context,
+        race_mcmc,
+    )
+    wavefunctions = backend.compile_candidates(
+        model,
+        canonical.context,
+        permutations,
+    )
+    backend.block_until_ready(wavefunctions)
+    for _ in range(int(config.contest_preburn)):
+        state = backend.step_mcmc(
+            state,
+            wavefunctions,
+            virtual_context,
+            replica_steps=int(config.mcmc.burn_in_replica_steps),
+            walker_chunk_size=int(config.mcmc.walker_chunk_size),
+        )
+        backend.block_until_ready(backend.cold_walkers(state))
+        state = backend.adapt_mcmc(state, race_mcmc)
+    race_window = EnergyWindow(
+        config.contest_measurements,
+        systems=K,
+        batch_size=batch_per_candidate,
+    )
+    for _ in range(int(config.contest_measurements)):
+        state = backend.step_mcmc(
+            state,
+            wavefunctions,
+            virtual_context,
+            replica_steps=int(config.mcmc.steps),
+            walker_chunk_size=int(config.mcmc.walker_chunk_size),
+        )
+        state = backend.adapt_mcmc(state, race_mcmc)
+        q_cold = backend.cold_walkers(state)
+        total, exchange, _casimir, field = backend.custom_lap_energy(
+            wavefunctions,
+            virtual_context,
+            q_cold,
+            config.energy,
+        )
+        backend.block_until_ready(total)
+        race_window.push(total, exchange, field)
+    energies = np.asarray(
+        [[race_window.tail_mean("total", candidate) for candidate in range(K)]]
+    )
+    tailstd = np.asarray(
+        [[race_window.tail_std("total", candidate) for candidate in range(K)]]
+    )
+    beam_logp = np.asarray(candidates.log_probabilities, dtype=float)
+    winners, ties, reasons, _bands, standard_errors = select_winner_per_physical(
+        energies,
+        tailstd,
+        beam_logp,
+        batch_per_candidate,
+        z=P01_TWO_SIDED,
+        ucb_z=float(config.contest_se_multiplier),
+    )
+    winner = int(winners[0])
+    wavefunction = backend.select_candidate(wavefunctions, winner)
+    population = backend.mcmc_population(state)
+    q_final, route = _collapse_to_winner(
+        population.q,
+        permutations,
+        winners,
+        P=1,
+        K=K,
+    )
+    sigma = _gather_winner_ladder(population.sigma, winners, P=1, K=K)
+    beta = _gather_winner_ladder(population.beta, winners, P=1, K=K)
+    routed_context = backend.route_context(
+        canonical.context,
+        route,
+        compact_custom_lap=False,
+    )
+    final_state = backend.initialize_mcmc(
+        jax.random.fold_in(root_key, 7919),
+        wavefunction,
+        routed_context,
+        config.mcmc,
+    )
+    final_state = backend.replace_mcmc_population(
+        final_state,
+        MCMCPopulation(q=q_final, sigma=sigma, beta=beta),
+    )
+    backend.block_until_ready(backend.cold_walkers(final_state))
+    contest_candidates = tuple(
+        ContestCandidate(
+            index=index,
+            route_log_probability=float(beam_logp[0, index]),
+            energy=float(energies[0, index]),
+            standard_error=float(standard_errors[0, index]),
+            walker_tail_std=float(tailstd[0, index]),
+            in_tie_set=bool(ties[0, index]),
+        )
+        for index in range(K)
+    )
+    contest = ContestResult(
+        winner=winner,
+        reason=reasons[0],
+        candidates=contest_candidates,
+    )
+    backend.release_context(virtual_context)
+    return (
+        wavefunction,
+        routed_context,
+        final_state,
+        route,
+        float(beam_logp[0, winner]),
+        contest,
+    )
+
+
+def _large_n(
+    backend: EvalBackend,
+    model: Any,
+    context: Any,
+    canonical,
+    mcmc_key,
+    config: EvalConfig,
+):
+    state = backend.initialize_mcmc(mcmc_key, model, context, config.mcmc)
+    compiled = backend.compile_large_n(
+        model,
+        canonical.context,
+        sequence_shards=int(config.large_n_sequence_shards),
+        pair_tile_size=int(config.large_n_pair_tile_size),
+        temperature=float(config.route_temperature),
+    )
+    route = _as_batched_route(compiled.permutation)
+    walker_route = _compose_walker_route(canonical.old_inverse, route)
+    routed_context = backend.route_context(
+        canonical.context,
+        route,
+        compact_custom_lap=True,
+    )
+    state = backend.route_mcmc(state, walker_route)
+    backend.block_until_ready(compiled.wavefunction)
+    logp = float(np.asarray(compiled.log_probability))
+    return compiled.wavefunction, routed_context, state, route, logp, None
+
+
+def _validate(config: EvalConfig) -> None:
+    if config.contest and config.large_n:
+        raise ValueError("contest and large_n are mutually exclusive")
+    if int(config.measurements) < 1:
+        raise ValueError("measurements must be positive")
+    if int(config.mcmc.batch_size) < 1:
+        raise ValueError("MCMC batch size must be positive")
+    if int(config.mcmc.replicas) < 2:
+        raise ValueError("MCMC requires at least two replicas")
+    if int(config.mcmc.steps) < 1:
+        raise ValueError("MCMC replica steps must be positive")
+    if int(config.mcmc.burn_in_replica_steps) < 1:
+        raise ValueError("burn-in replica steps must be positive")
+    if int(config.mcmc.walker_chunk_size) < 1:
+        raise ValueError("walker chunk size must be positive")
+    if config.contest:
+        K = int(config.contest_candidates)
+        W = int(config.contest_beam_width)
+        if K < 2 or W < K:
+            raise ValueError("contest requires beam_width >= candidates >= 2")
+        if int(config.mcmc.batch_size) % K:
+            raise ValueError("MCMC batch size must be divisible by candidates")
+        if int(config.mcmc.batch_size) // K < 32:
+            raise ValueError("contest requires at least 32 walkers per candidate")
+        if int(config.contest_preburn) < 0:
+            raise ValueError("contest preburn must be non-negative")
+        if int(config.contest_measurements) < 1:
+            raise ValueError("contest measurements must be positive")
+    if int(config.large_n_sequence_shards) < 0:
+        raise ValueError("large-N sequence shards must be non-negative")
+    if int(config.large_n_pair_tile_size) < 1:
+        raise ValueError("large-N pair tile size must be positive")
+
+
+def evaluate(
+    config: EvalConfig,
+    backend: EvalBackend,
+    *,
+    metric_sink: Callable[[EvalMetric], None] | None = None,
+) -> EvalResult:
+    _validate(config)
+    started = time.perf_counter()
+    root_key = jax.random.PRNGKey(int(config.seed))
+    model_key, mcmc_key = jax.random.split(root_key)
+    context = backend.load_system(config.system, config.energy)
+    model = backend.load_model(
+        config.checkpoint,
+        config.model,
+        model_key,
+        context,
+        contextualizer_attention=config.contextualizer_attention,
+    )
+    canonical = backend.canonicalize_context(context)
+    embedded_route = backend.embedded_route(model)
+    if embedded_route is not None and (config.contest or config.large_n):
+        raise ValueError(
+            "compiled fine-tune checkpoints support ordinary eval only; "
+            "contest and large_n require a router checkpoint"
+        )
+    if embedded_route is not None:
+        prepared = _compiled_finetune_ordinary(
+            backend,
+            model,
+            context,
+            canonical,
+            embedded_route,
+            mcmc_key,
+            config,
+        )
+        path = "ordinary"
+    elif config.contest:
+        prepared = _contest(
+            backend,
+            model,
+            canonical,
+            root_key,
+            config,
+        )
+        path = "contest"
+    elif config.large_n:
+        prepared = _large_n(
+            backend,
+            model,
+            context,
+            canonical,
+            mcmc_key,
+            config,
+        )
+        path = "large_n"
+    else:
+        prepared = _ordinary(
+            backend,
+            model,
+            context,
+            canonical,
+            mcmc_key,
+            config,
+        )
+        path = "ordinary"
+    wavefunction, routed_context, state, route, route_logp, contest = prepared
+    del model, context, canonical, embedded_route, prepared
+    wavefunction, routed_context, state = backend.prepare_singular(
+        wavefunction,
+        routed_context,
+        state,
+    )
+    state = _burn_in(
+        backend,
+        state,
+        wavefunction,
+        routed_context,
+        config,
+        iterations=int(config.mcmc.burn_in),
+        replica_steps=int(config.mcmc.burn_in_replica_steps),
+    )
+    _state, window = _measure(
+        backend,
+        state,
+        wavefunction,
+        routed_context,
+        config,
+        started=started,
+        metric_sink=metric_sink,
+    )
+    route_host = np.asarray(route, dtype=np.int32)
+    if route_host.shape[0] != 1:
+        raise ValueError("single-system eval produced more than one route")
+    return EvalResult(
+        path=path,
+        route=tuple(int(value) for value in route_host[0]),
+        route_log_probability=(None if route_logp is None else float(route_logp)),
+        measurements=int(window.count),
+        walltime_seconds=float(time.perf_counter() - started),
+        energy=window.metrics("total"),
+        channels={
+            "exchange": window.metrics("exchange"),
+            "field": window.metrics("field"),
+        },
+        contest=contest,
+    )