readme: condense to an overview - #9
Merged
Merged
Conversation
562 → ~310 lines. The README had accumulated design-log-level detail (FiLM option tables and symmetry derivations, MP envelope measurements, LES init/DDP internals, batching alignment mechanics). Feature sections now state what each option does and how to invoke it, and point to the class/trainer docstrings — where all of that detail already lives — for the reasoning. Kept intact: layout, install, quickstart (now includes the SPICE/torchrun and calculator examples that were buried in the batching section), the LES install + IP/licensing note, the calculator refusal semantics, the force-training safety split between the two fused kernels, and the test index. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The FiLM gate becomes part of the default architecture: element_film=True in ECENet and all four trainers. Old checkpoints are unaffected — from_checkpoint rebuilds from stored hparams, which have always recorded element_film. The gate is identity at init (zero-init MLP), so a default-built model's initial energies are unchanged; parameter counts and state-dict keys grow by the gate. Test fallout, both assumption fixes rather than breaks: - test_ignored_flags_warn now passes element_film=False explicitly (with the gate on by default, the flags it sets are genuinely used — no warning is correct behavior). - test_les's cell=None vs explicit-zero-cell check asserted bitwise equality between two independent implementations; they only agreed exactly by luck of the old seeded values (the gate's parameters shift the RNG stream). Now asserts < 1e-14 with the reason documented. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The Layout block already points at tests/ (runnable scripts, repo root); the file-by-file list belongs in the files' own docstrings. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…detail 'sum' — the raw signed score times the cutoff envelope, extensive in coordination and an exact no-op at init — becomes the default aggregation in ECENet and all four trainers. Old checkpoints are unaffected (mp_type is in hparams). Consequence of the default pairing: a default model's msg_envelope flag is now False, since 'sum' is enveloped structurally and never sets it. Tests updated to the new default: test_default_is_softmax becomes test_default_is_sum, and test_msg_envelope_defaults_and_flag pins mp_type='softmax' explicitly where it exercises the softmax-only flag. README: the mp_type comparison table and the nonlinearity paragraph go; message passing is now one short paragraph deferring to the docstring. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The 'not vendored' jargon goes; the IP note below still carries the load-bearing statement that none of the les package's code is included. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
LR schedules, size-aware batching, precompute_topology, and tf32 are all documented in the trainer docstrings the Quickstart already points at. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…dout table The trainers' les_readout now defaults to None, resolved at run start to 'edge_basis' when use_les=True and 'sum' otherwise. LES runs get the per-edge charge head (the readout behind the dipole/BEC results) by default, while short-range runs keep the parameter-free 'sum' read-out — a bare-model or SR run must not carry an unused charge head, which under DDP's find_unused_parameters=False would hang the gradient reduction (the existing spice/mptrj guards for explicit misconfigurations stay). The bare-model default stays 'sum' for the same reason, documented in the readout comment block. Explicit les_readout settings and old checkpoints are unaffected (the resolved value is what lands in hparams). Tests: the xyz/rmd17 LES smokes pin les_readout='sum' — they specifically exercise upstream's lazy atomwise head and resume against 'sum' checkpoints, and a resume must match the checkpoint's readout like any other architecture hparam (the strict load rejects the mismatch loudly). README: the les_readout table and the knobs paragraph collapse to two sentences deferring to the model docstring. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Trims the README from 562 to ~310 lines. It had grown design-log-level detail (FiLM option tables + symmetry derivations, MP envelope measurements, LES initialization/DDP internals, DDP batching mechanics); feature sections now say what each option does and how to use it, deferring the reasoning to the docstrings where it already lives.
Preserved: layout, install, quickstart (SPICE/torchrun + calculator usage promoted out of the batching section), LES install + IP/licensing note verbatim, calculator refusal semantics, the double-backward-safety distinction between the fused kernels, and the full test index.
Second commit:
element_filmis now on by default (model + all four trainers), and the README's FiLM section shrinks to a one-liner accordingly. Old checkpoints are unaffected (hparams have always recorded the flag;from_checkpointrebuilds from them). The gate is identity at init, so default-built models start numerically unchanged. Two test-assumption fixes ride along: the ignored-flags warning test now setselement_film=Falseexplicitly, and a bitwise LES path-equality assertion is relaxed to 1e-14 (two independent implementations; exact agreement was luck of the old RNG stream).🤖 Generated with Claude Code