shardes 0.1.1__tar.gz

shardes-0.1.1/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.ipynb_checkpoints/
+.venv/

shardes-0.1.1/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+The supported surface is `shardes.__all__`. Before 1.0 a minor version may change it, and
+says so here. Everything else is importable and may move without notice.
+
+## 0.1.1
+
+Packaging only; the code is 0.1.0's.
+
+- First release on PyPI: `pip install shardes`.
+- Index metadata (classifiers, keywords, links), and an explicit list of what the sdist
+  contains.
+- A release workflow: it builds from the tag, checks that the tag names the declared
+  version, checks the artifacts, installs the wheel into a clean environment, and only
+  then publishes, through PyPI's trusted publishing rather than a token.
+
+## 0.1.0
+
+The first version with a repository of its own. Until the tag `monorepo-final` the library
+shared one with the paper it was built for, which is now
+[shardes-paper](https://github.com/andreshernandez-spec/shardes-paper).
+
+- `ShardedES`: `init`, `ask`, `apply`, `tell`, over the one-axis device mesh `make_mesh`
+  builds.
+- Strategies: `IIDGaussian`, `SeedRegenerated(chunk)`, `LowRank(r)`, and `Mirrored(inner)`
+  for antithetic pairs around any of them.
+- Two placements of the update contraction, `how="A"` and `how="B"`.
+- Shaping: `centered_ranks` (the default), `centered`, `group_relative`, `none`.
+- The seams a model routes its weights through, `shardes.nn.dense` and `shardes.nn.embed`,
+  and `shardes.check.check_model` to find the weights that miss them.
+- Problems: `quadratic`, `mlp`, `transformer_block`, and a Qwen2.5 port that needs
+  `shardes[models]`.
+- Python 3.12 or newer, JAX 0.11 or newer.

shardes-0.1.1/CITATION.cff

@@ -0,0 +1,18 @@
+# How to cite the library. GitHub reads this file and shows a "Cite this repository"
+# button. `version` and `date-released` name the latest release, not main, so they move
+# when a tag is cut, and a test holds `version` to the changelog's latest released heading.
+cff-version: 1.2.0
+message: "If you use shardes, please cite it."
+type: software
+title: "shardes: sharded evolution strategies for JAX"
+authors:
+  - family-names: Hernandez
+    given-names: Andres
+version: 0.1.1
+date-released: "2026-09-22"
+repository-code: "https://github.com/andreshernandez-spec/shardes"
+license: Apache-2.0
+keywords:
+  - evolution strategies
+  - JAX
+  - distributed training

shardes-0.1.1/CLAUDE.md

@@ -0,0 +1,149 @@
+# CLAUDE.md
+
+Instructions for Claude Code working in this repository. Keep this file short — it
+loads into every session. Detail lives in `docs/`.
+
+---
+
+## What this project is
+
+`shardes` is a JAX library for **sharded evolution strategies**: an `ask`/`eval`/`tell`
+core that shards the population and the rollouts across devices, with the perturbation
+scheme as a pluggable, shape-aware strategy rather than a hardcoded `randn(num_dims)`.
+
+The distribution state is replicated, not sharded (decided in `docs/02` C1.4 and corrected
+here on 2026-07-31). Sharding it is theatre for isotropic ES and, for the CMA family, would
+cost a per-generation gather to save memory the design already spends on replicating the
+model.
+
+It exists because the two 2025 papers that made ES work at LLM scale
+([Qiu et al.](https://arxiv.org/abs/2509.24372), full-rank + seed regeneration;
+[Sarkar et al. / EGGROLL](https://arxiv.org/abs/2511.16652), rank-`r` factored) have no
+common library, and the incumbent (`evosax`) forecloses both by flattening every solution
+to one dense vector via `ravel_pytree`. Background: `docs/00-context.md`.
+
+**The deliverable is the library.** Everything else is instrumentation for it.
+
+---
+
+## Ground rules
+
+### 1. Andres writes and understands the load-bearing code
+
+This is a hard constraint, not a preference. The project's value is what he can explain
+in a technical interview, and the ecosystem this targets is explicit about it — JAX's
+`docs/contributing.md` states that *"the use of an AI agent that autonomously writes code
+and submits pull requests is not permitted"* and *"do not use AI to speak for you"* on
+issue trackers. This repo is standalone, so the letter of that policy doesn't bind it,
+but the spirit is the whole point.
+
+Concretely:
+
+- **Claude Code may**: scaffold, write tests, write benchmark harnesses, write plotting
+  and infra code, port reference implementations for comparison, research, review, explain,
+  find bugs, refactor.
+- **Claude Code should hand back**: the perturbation strategies, the sharding logic, the
+  gradient-estimator math, and anything that ends up in a README or a talk. Draft it,
+  explain the reasoning, then let Andres write the version that ships.
+- **Claude Code must never**: draft GitHub issues, PR descriptions, or review comments for
+  upstream projects. Andres writes those in his own voice.
+
+If asked to do something in the second or third bucket, say so and offer the first-bucket
+version instead.
+
+### 2. Every number in a doc has a script behind it
+
+No claim of the form "X is Y× faster" or "error is 1e-15" enters any markdown file without
+a committed, re-runnable script and a recorded environment (GPU model, JAX version, commit
+SHA). Scripts that check the library are in `tools/`; the experiments and the paper are in
+the [shardes-paper](https://github.com/andreshernandez-spec/shardes-paper) repository, and a
+number that comes from there is cited as `shardes-paper:<path>`. If a number can't be
+reproduced from a clean checkout, delete it.
+
+### 3. Don't build what a measurement already ruled out
+
+Phase 3, coupled sampling at scale, was conditional on a Phase 0 result and that result
+came back no (`docs/04-phase3-coupling.md`, `docs/01`). Do not build it speculatively
+because it seems interesting. The research program's phases and gates are in
+`shardes-paper:PLAN.md`.
+
+---
+
+## Repository layout
+
+```
+shardes/
+├── README.md              for a user: install, quickstart, guarantees
+├── CLAUDE.md              this file
+├── pyproject.toml         must stay pip-installable from a git SHA; shardes-paper pins one
+├── src/shardes/           the library
+├── tests/                 pytest; CPU-only, no network; tests/gpu needs real accelerators
+├── examples/              what the README shows; the suite runs them
+├── tools/                 scripts that check the library, not experiments
+├── validation/            the real-hardware invariance check (gate G1)
+└── docs/                  design (02), context (00), the estimator study (01), conventions,
+                           diagnoses, proposals, and the record of the split (14)
+```
+
+The experiments, the results, the paper and the campaign docs are in
+[shardes-paper](https://github.com/andreshernandez-spec/shardes-paper), which installs this
+library at a pinned commit. Until the tag `monorepo-final` they were here, and that history
+is kept on purpose: records from that period cite commits of this repository. Never rewrite
+it, and never delete a `provenance/*` tag: each one keeps a cited commit reachable. It was
+rewritten once, on 2026-09-22, to remove a personal account from three files; every commit
+after 2026-08-01 changed hash and `docs/provenance/` maps old to new. That is the exception,
+and the map is what it cost.
+
+`tests/` runs on CPU, no GPU, no network, in **two tiers**: `pytest --fast` is the inner
+loop while editing, `pytest` is everything and is the default. Budgets and the reasoning
+are in `docs/conventions.md`. This line said "under two minutes" until 2026-08-01; that
+number predated the code and was about to cost `R` in the unbiasedness tests.
+
+---
+
+## Environment
+
+- Python ≥ 3.12 (jax 0.11 requires it; this said 3.11 until CI tried it), JAX ≥ 0.11. **Do not pin below 0.11** — `from jax import shard_map` needs
+  0.8 and `AxisType` needs 0.11, and those are what the library is built on. This used to
+  say "evosax is stuck at `<0.7`"; that stopped being true at evosax 0.2.0 (`jax>=0.5.0`,
+  no upper bound). The floor is justified by what we use, not by what they pin.
+- `from jax import shard_map`. `jax.experimental.shard_map` is deprecated (JAX 0.8.0).
+- Multi-device logic is developed and tested **on CPU** with
+  `XLA_FLAGS=--xla_force_host_platform_device_count=8`. See `docs/compute.md`. Do not
+  reach for a GPU to debug a `PartitionSpec`.
+- Dependencies stay minimal: `jax`, `numpy`, `pytest`. Adding anything else needs a
+  one-line justification in the PR description. `optax`, `flax`, `chex` are acceptable if
+  actually used; `evosax` is a comparison target, not a dependency.
+
+---
+
+## Invariants — breaking these is a bug, not a tradeoff
+
+1. **No global flattening.** Nothing in `src/` calls `ravel_pytree` on a solution. Leaves
+   keep their `(m, n)` shape all the way through sample → apply → contract. This is the
+   architectural difference from evosax and the reason low-rank perturbation is expressible
+   at all.
+2. **Device-count invariance.** For a fixed seed, the update produced on 1 device and on
+   8 devices must agree to within float tolerance (`rtol=1e-5` bf16, `1e-12` f32). Seeds
+   are derived from the *member index*, never from the device index. There is a test for
+   this; it is the most important test in the repo.
+3. **The perturbation is never materialized by the low-rank path.** If a profile shows an
+   `(n_members, m, n)` array being allocated under `LowRank`, the implementation is wrong.
+4. **Communication is measured, not assumed.** Every `psum`/`all_gather` in the update path
+   is accounted for in `shardes-paper:docs/03-phase2-benchmarks.md`. See the note there about the two
+   contraction strategies — the "ES only all-reduces scalars" claim is true only for one
+   of them.
+
+---
+
+## Working style
+
+- Small commits, each with its test. Prefer a failing test first.
+- When a design decision has two defensible answers, write both down in the relevant
+  `docs/` file with the tradeoff, and flag it for Andres rather than picking silently.
+- Numerical code: assert against an exact oracle where one exists (see
+  `docs/conventions.md` for the list — e.g. the FWHT has one that ships in JAX).
+- The names in `shardes.__all__` are the supported surface and `tests/test_public_api.py`
+  pins them. Changing one is a version bump and a line in the release notes. Everything
+  else stays importable from its module, and shardes-paper uses those deep paths, so a
+  rename there breaks the paper's pin when it next moves.

shardes-0.1.1/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 2026 Andres Hernandez
+
+   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.

shardes-0.1.1/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.5
+Name: shardes
+Version: 0.1.1
+Summary: Sharded evolution strategies for JAX
+Project-URL: Repository, https://github.com/andreshernandez-spec/shardes
+Project-URL: Changelog, https://github.com/andreshernandez-spec/shardes/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/andreshernandez-spec/shardes/issues
+Project-URL: Paper, https://github.com/andreshernandez-spec/shardes-paper
+Author: Andres Hernandez
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: distributed,evolution strategies,jax,low-rank,sharding
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: jax>=0.11
+Requires-Dist: numpy
+Requires-Dist: scipy
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Provides-Extra: models
+Requires-Dist: safetensors; extra == 'models'
+Provides-Extra: tasks
+Requires-Dist: playground; extra == 'tasks'
+Description-Content-Type: text/markdown
+
+# shardes
+
+Sharded evolution strategies for JAX.
+
+Evolution strategies train a model without gradients: perturb the weights, score each
+perturbed copy, move toward the copies that scored well. `shardes` is an `ask` / `apply` /
+`tell` core that splits that population across devices, with the perturbation scheme as a
+pluggable strategy. The two 2025 results that made ES work at language-model scale,
+full-rank noise regenerated from seeds ([Qiu et al.](https://arxiv.org/abs/2509.24372))
+and rank-`r` factored noise ([EGGROLL](https://arxiv.org/abs/2511.16652)), are one
+constructor argument apart here, on the same mesh, shaping and update.
+
+> **Status: 0.1, pre-alpha.** The API can still change. What is here is tested, on CPU with
+> eight simulated devices, and device-count invariance has been checked on real hardware
+> too: the GPU suite on two T4s, and one device against eight A100s on a 0.5B-parameter
+> model.
+
+## Install
+
+```sh
+pip install shardes                                                          # the release
+pip install "shardes @ git+https://github.com/andreshernandez-spec/shardes"  # main
+```
+
+Python 3.12 or newer, JAX 0.11 or newer. On an accelerator, install JAX for it first
+(`pip install -U "jax[cuda12]"` or `"jax[tpu]"`). The core needs only jax, numpy and scipy.
+Extras: `shardes[models]` for loading Qwen2.5 checkpoints, `shardes[tasks]` for the MuJoCo
+Playground adapter.
+
+## Quickstart
+
+This is `examples/quickstart.py`, and the test suite runs it. It needs no accelerator:
+eight simulated CPU devices stand in, and the sharding is the same program either way.
+
+```python
+import os
+os.environ["XLA_FLAGS"] = "--xla_force_host_platform_device_count=8"   # 8 devices on a CPU
+
+import jax
+import shardes
+from shardes.problems import transformer_block       # a small model that uses the seams
+
+key = jax.random.key(0)
+params = transformer_block.init(key, d_model=64)
+batch = transformer_block.make_batch(jax.random.fold_in(key, 1), d_model=64, batch=8, seq=32)
+
+mesh = shardes.make_mesh()                           # every visible device, one "pop" axis
+es = shardes.ShardedES(shardes.Mirrored(shardes.LowRank(r=1)),
+                       n=256, sigma=1e-2, lr=1e-2, mesh=mesh)
+state = es.init(key, params)
+
+@jax.jit
+def generation(state):
+    pert, state = es.ask(state)                      # a Perturbation, never a batch of params
+    fitness = es.apply(transformer_block.loss, state, pert)(batch)   # one loss per member
+    return es.tell(state, pert, fitness), fitness
+
+for step in range(30):
+    state, fitness = generation(state)
+    if step % 10 == 0 or step == 29:
+        print(f"step {step:2d}  mean loss {float(fitness.mean()):.4f}")
+```
+
+Jit the whole generation rather than stepping it eagerly; that is what lets JAX settle
+device placement at trace time. `tell` descends, so hand it a loss, or the negative of a
+reward.
+
+## Both published algorithms, one argument apart
+
+```python
+# Qiu et al. 2025: full-rank noise, regenerated from seeds, small population
+shardes.ShardedES(shardes.Mirrored(shardes.SeedRegenerated()), n=30, ...)
+
+# EGGROLL (Sarkar et al. 2025): rank-1 factors, never materialized, huge population
+shardes.ShardedES(shardes.Mirrored(shardes.LowRank(r=1)), n=262_144, ...)
+```
+
+| strategy | the perturbation | what it costs |
+|---|---|---|
+| `IIDGaussian()` | full rank, materialized | memory: `n` copies of the noise |
+| `SeedRegenerated(chunk=1)` | full rank, regenerated from each member's seed | compute: every perturbation is drawn twice. `chunk` trades memory for speed |
+| `LowRank(r)` | rank `r`, two thin factors per matrix, product never formed | the noise is not full rank |
+| `Mirrored(inner)` | antithetic pairs around any of the above | halves the distinct directions |
+
+`ask` returns a `Perturbation`, not a batch of parameter trees, and the rest follows from
+that: under `LowRank` it is a pair of factors, under `SeedRegenerated` a key and member
+ids. Shaping is `centered_ranks` by default (`shardes.shaping` has `centered`,
+`group_relative` and `none`).
+
+## Where the update is assembled: `how="A"` or `how="B"`
+
+After evaluation each device holds the fitnesses of its own members, and the update
+`sum_i w_i eps_i` has to be put together. There are two placements, and which is faster
+depends on the perturbation and on the interconnect.
+
+- **`how="B"`, the default.** Each device contracts its own members, then the partial
+  updates are all-reduced. That moves a buffer the size of the model.
+- **`how="A"`.** Every device gathers the scalar fitnesses and contracts the whole
+  population itself. Only scalars cross the wire, and the contraction is repeated on
+  every device.
+
+Measured on an 8x A100 node, a TPU v5e-8 and two A100 nodes over sockets: on one host
+with a fast interconnect, **B wins for full-rank and seed-regenerated perturbations, and A
+wins for low-rank perturbations on large models**, by more on the TPU. Across a slow host
+boundary A wins more widely. The measurements, and the paper they belong to, are in
+[shardes-paper](https://github.com/andreshernandez-spec/shardes-paper).
+
+## Your own model
+
+A low-rank perturbation is never materialized, so a perturbed weight is not an array: it
+is a base matrix plus two factors. A model therefore routes its parameterized matrix
+multiplies and embedding lookups through two seams, `shardes.nn.dense(x, w)` and
+`shardes.nn.embed(table, ids)`, which do the right thing for a plain array and for a
+structured weight alike. Direct arithmetic on a structured weight raises rather than
+silently densifying. `shardes.problems.transformer_block` is the small worked example and
+`shardes.problems.qwen2` is Qwen2.5 ported this way.
+`shardes.check.check_model(model, params, batch)` finds, in a second on CPU, every weight a
+model reaches without a seam, instead of the strategy raising minutes into a run.
+
+## What it guarantees
+
+- **Device count cannot change the result.** Member `i`'s noise derives from `i` alone,
+  so the update contracted on one device and on eight agrees to floating-point
+  tolerance. This is tested on simulated devices and checked on real ones: `tests/gpu`
+  on two T4s (`validation/`), and on A100s the update for Qwen2.5-0.5B computed on one
+  device and on eight agrees to 6.3e-6 relative error
+  (`shardes-paper:experiments/countdown/results/c6d-a100x8-2026-08-18`).
+- **The low-rank path never forms an `(n, m, n)` array.** A test inspects the traced
+  program to make sure.
+- **Fitness is float32 or wider.** In bfloat16 a population's losses collapse to a
+  handful of ties and rank shaping of ties is noise, so `tell` refuses rather than casts.
+- **No global flattening.** Parameters keep their shapes from sampling to update, which
+  is what makes per-matrix structure expressible at all.
+
+## Development
+
+```sh
+pip install -e ".[dev]"
+pytest --fast        # the inner loop
+pytest               # everything, including the statistical tier
+```
+
+The suite pins JAX to the CPU and simulates eight devices, so it needs no accelerator and
+no network. `tools/` holds scripts that check the library itself (mutation testing,
+compile-cost diagnostics, two probes behind design decisions), `validation/` the
+real-hardware invariance check, and `docs/` the design, conventions and diagnoses.
+CI runs the suite on Python 3.12 and 3.13 and installs the built wheel into a clean
+environment.
+
+## The paper and the experiments
+
+This library is the instrument of *Update-contraction placement in sharded evolution
+strategies on GPUs and TPUs*. The manuscript, every experiment and every result live in
+[shardes-paper](https://github.com/andreshernandez-spec/shardes-paper), which installs
+this library at a pinned commit.
+
+Until the tag `monorepo-final` the two were one repository, and that history is kept here
+on purpose: result records from that period cite commits of this repository, and
+checking one out gives the driver, its config and the library together, as run.
+
+## Non-goals
+
+- Sharded *parameters*. Every device holds the model and evaluates independently;
+  sharding parameters would bring back the communication ES avoids.
+- A general replacement for evosax. This targets the sharded, large-population,
+  structured-perturbation regime.
+- Reimplementing either paper's full experimental setup. The papers stand; this is
+  infrastructure.
+
+## License
+
+Apache 2.0.