Add a lattice catalog mapping StdFace models to the new three-layer lattice format - #64
Open
k-yoshimi wants to merge 34 commits into
Open
Add a lattice catalog mapping StdFace models to the new three-layer lattice format#64k-yoshimi wants to merge 34 commits into
k-yoshimi wants to merge 34 commits into
Conversation
Design for mapping all StdFace lattices and interaction types to the three-layer lattice definition format (geometry/system/model), producing a static YAML catalog (9 lattices x 3 models + wannier90 example) and a Japanese manual under lattice_catalog/. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DjgDyCehNnZT7Z4hF2RiGQ
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DjgDyCehNnZT7Z4hF2RiGQ
Address review findings: declare the catalog as an experimental dialect with schema versioning; define R and bond-reversal transformations (complex conjugate / tensor transpose); canonicalize the 9-component exchange-tensor form with parameter resolution rules; represent 2S as a parameter reference; apply magnetic fields to both Kondo subsystems; reproduce current pyrochlore Kondo behavior with a caveat; rewrite the wannier90 section as model-specific transformation rules with a Hubbard example; add ladder W=2/W=3 examples; add a semantic linter, manifest, and machine-generated keyword inventory (new Task 0). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DjgDyCehNnZT7Z4hF2RiGQ
Define value semantics as physical Hamiltonian coefficients with the
verification chain through solver sign conventions; carry all signs in
data via a {param, scale, default} reference form; keep bonds in
reference-implementation source order (dropping forced canonicalization
that would require per-bond conjugate/transpose metadata); correct the
parameter resolution order to match the implementation (local component
> global component > local scalar > global scalar); express spin S as a
scaled 2S reference; restrict the wannier90 example to the H/U channels;
extend the manifest to per-label coordination and add a counting
expander (C11) plus deeper structural checks and tool self-tests.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DjgDyCehNnZT7Z4hF2RiGQ
Pin the parameter-reference semantics (scale applies only when the parameter is given; default is a final value), include the bond type in the reversal-equivalence key so t/V coexistence on one geometric bond is legal, make the 9-component exchange check reject duplicates and wrong term counts, and add lattice/model metadata to the catalog header as the manifest cross-check anchor. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DjgDyCehNnZT7Z4hF2RiGQ
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DjgDyCehNnZT7Z4hF2RiGQ
Add the three chain lattice/model catalog YAMLs (spin, Hubbard, Kondo)
and their manifest.yaml verification entries, cross-checked against
chain_lattice.py::chain (_BONDS) and model_plugin.py
(SpinModel/HubbardModel/KondoModel).
Adjust lint_catalog.py to accept the catalog's actual couplings/onsite
shape: J-family tensor_terms nested under `operator`, and onsite terms
as a site -> {term_name: {operator, value}} mapping rather than a flat
list. Update test_tools.py fixtures to match.
Fix a keyword_inventory.py canonicalization gap: the bare Kondo
exchange keyword "j" was missing from _CANON_EXCEPTIONS (its sibling
"v" -> "V" was already present), so {param: J} references failed the
catalog's C7 keyword check.
CONVENTIONS.md still described geometry.cell / system.twist.paramN and
a flat onsite-list / bare-tensor_terms couplings shape, none of which
match the schema actually used by lattice_catalog/chain/*.yaml
(geometry.lattice_vectors, system.boundary: [{twist: {param}}], nested
onsite site->term mapping, operator.tensor_terms). Rewrite the
affected passages (geometry/system key names in §3-5, the value/coeff
semantics and sign table in §6.1-6.2, the tensor_terms location in
§6.4, and the operator vocabulary paths in §6.6) to match, and fix a
stale §4.5 cross-reference to §6.2 found along the way. Update
test_tools.py's base_doc() fixture to use the same key names.
The catalog YAML files and lint_catalog.py behavior are unchanged.
Code tracing and a pipeline run show the physical hopping coefficient is +H_mn (the reader's negation cancels against the solver convention), not a -H_mn inversion as previously stated. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DjgDyCehNnZT7Z4hF2RiGQ
…tion docs - lint_catalog.py: expand_and_count() now actually expands bonds on the min_size_for_check torus (per-cell endpoint instances with R offsets mod size) instead of ignoring the cell/size arguments. It reports two independent C11 failure modes: coordination mismatch against the manifest, and folding degeneracy (two expanded bonds collapsing onto the same endpoint-instance pair, meaning min_size_for_check is too small to distinguish them). - test_tools.py: added a direct expand_and_count() sanity test, a folding-degeneracy negative test (undersized min_size_for_check), and documented why a per-label instance-mismatch negative test is unreachable by construction. - docs/superpowers/specs/2026-08-15-lattice-catalog-design.md: corrected the retracted wannier90 Hubbard sign claim to match section 4.3 and the manual (no sign inversion; physical coefficient = +H_mn). - lattice_catalog/CONVENTIONS.md, manual.md: corrected the claim that the linter's check size equals system.size; min_size_for_check is actually derived independently from the largest bond |R| component.
- manual.md: fix a stale python/ path (input_params.py lives under stdface/lattice/, not stdface/core/), replace "byte-for-byte" with a plain-language description of the call-sequence match (fc_ortho, pyrochlore), and update a stale "will be listed as item 6" reference to point at the section that now exists (6.6). - keyword_inventory.py: canonicalise "height" to "Height" so it matches manual ch.2's keyword table row (entry count unchanged: 342). - CONVENTIONS.md: document that externally-sourced values (wannier90) may use a numeric literal directly in `value`, and that C7 only inspects dict-shaped values. - pyrochlore_spin.yaml: correct the coordination-breakdown comment (3 series x (1 intra-tetrahedron + 1 inter-tetrahedron) = 6). - triangular_hubbard.yaml: align the manifest-reference comment with the other files' specific-entry style.
- keyword_inventory.py: derive model_alias entries from the actual
MODEL_ALIASES / MODEL_ALIASES_HPHI_BOOST registry (stdface_main.py)
instead of the 3 canonical ModelType values, so GC/HPhi-Boost
variants (fermionhubbardgc, spingcboost, ...) are enumerated too
(313 keyword + 26 lattice_alias + 12 model_alias = 351 total).
Fail cleanly (non-zero exit, no partial output) if the registry
import fails or resolves to an empty result.
- lint_catalog.py:
- C11: validate that each min_size_for_check component is a
positive odd integer and exactly equals 2*max|R|+1 as computed
from the file's own bonds, instead of only checking list length.
- C2: add schema-depth checks for geometry.lattice_vectors,
per-site frac/label shape, bond field types, system.boundary
length, and site_dof spin/fermion exclusivity.
- New C12 check enforcing the CONVENTIONS.md §6.2 sign table
(hop/density-density/s_i.S_j value.scale, onsite coeff literals,
J-family coeff shape, and the wannier90 plain-value exception).
- Wrap the PyYAML import so a missing dependency exits with a clear
message instead of a traceback (dev-only dependency, not added to
python/pyproject.toml).
- Convert manifest/inventory-subprocess load failures into a single
top-level diagnostic instead of a raw traceback, and detect
orphaned manifest.yaml entries against the discovered YAML files.
- test_tools.py: cover all of the above (model-alias set equality,
min_size_for_check strict validation against all 31 real catalog
files, C12 positive/negative fixtures, and the new top-level
failure-handling paths); fix the two C9 "positive" fixtures so they
are fully valid catalog documents (consistent catalog.model, no
double sign inversion) and assert zero diagnostics.
All 31 catalog files still lint clean (31 files, 0 errors).
…ntions
- manual.md §1.1: rewrite the execution-equivalence sentence so subject
and object are unambiguous.
- manual.md §2.7: unify the lambda_u/lambda_j casing in the notes column.
- manual.md §2.10/§2.11: enumerate all 12 model aliases (including the
GC and HPhi-Boost variants) instead of the 3 canonical model names,
and update the coverage-count arithmetic to match the linter's new
output (351 = 313 keyword + 26 lattice_alias + 12 model_alias).
- manual.md §4.1: fix the incorrect claim that J-family coeff is a bare
+-1.0 sign literal (it is a {param: ...} reference), and distinguish
V/U's scale-based sign convention from the J family's direct param
binding in the closing summary.
- manual.md §4.4: D is Spin-only, so only U/mu are Kondo-_c-only; D
never appears in a Kondo onsite block at all.
- manual.md §6.1/§6.6, §5.3: fix stale/dangling section cross-references
(drop the incorrect §7.7 pointer for multi-orbital examples, fix
§6.6's many-body-term reference to §7.8, and §5.3's wannier90-scope
reference to §7.3).
- manual.md §5.2: label the wannier90 conversion rules as W2-W6 headings
to match how §5.1/§5.4 already reference them by name.
- manual.md §1.3: add a couplings/onsite sign-representation note before
the sign table, lay out the J-tensor parameter resolution order as a
numbered list, note 0-indexing for geometry.sites, and add README.md
to the directory tree.
- CONVENTIONS.md §6.3/§7: fix two dangling "§5.5" references to point at
the actual manual.md sections (5.2 and 5.5); §3: give the geometry
bullet an explicit subject.
- README.md: document PyYAML as a dev-only dependency of the linter
(matching lint_catalog.py's new ImportError guard), note it must be
run from the repository root, and refresh the C1-C12/351-entry counts.
- Small readability fixes: fc_ortho's J''/t''/V'' section now states its
conclusion before the case-by-case breakdown, the ladder transverse-
coordinate-loss note is now a blockquote, and a stray "²" was replaced
with ASCII "^2".
All §-cross-references touched above were re-checked against the final
heading numbering in manual.md.
C12 previously accepted a non-J coupling `value` dict that lacked a
`param` key (e.g. `{scale: -1.0}`), since only the scale/sign was
checked once the value was confirmed to be a dict. It also compared
onsite `tensor_terms[0].coeff` with `!=`, so a literal `coeff: true`
silently passed the hubbard_u/aniso_z check because `True == 1.0` in
Python. Both are now flagged as C12 errors.
Also hardens check_c2's duplicate-label detection against
heterogeneous-type `geometry.sites` labels: sorting a set containing
mixed str/int values previously raised TypeError, which was caught by
the top-level exception handler and replaced the specific diagnostics
with a generic "exception while checking" message.
Adds regression tests for both C12 fixes, C2 deep-check negatives
(lattice_vectors key/dim mismatches, frac dimension mismatch,
non-string label, boundary length mismatch, site_dof with both
spin and fermion), a mixed-type-labels robustness test, and
strengthens the whole-catalog test to assert exactly 31 files are
discovered and each lints with zero diagnostics.
Several cross-references in manual.md pointed at internal task numbers and an unpublished design document instead of the reader- facing spec headings: "(Task N)" verification-provenance notes, "(design §2 参照)" / "design spec §4.6", and a bare "(8 章)" chapter number meant to refer to CONVENTIONS.md. Reworded each to state the verification fact directly or point at the actual CONVENTIONS.md / manual.md section, and unified the remaining "§N.N 参照" cross-refs in §5.3/§5.5 to the manual's "N.N 節参照" style. Every touched cross-reference was checked against the actual headings in manual.md and CONVENTIONS.md.
check_c2 now filters non-string site labels and malformed bonds
(type/from/to not strings, or R not a list of ints) out of the
context it hands to C4-C12, instead of passing the raw values
through. Previously a single bad label or bond field would make a
downstream check raise TypeError (heterogeneous sorted() in C4,
unhashable bond fields in C5/C6), which collapsed the specific C2
diagnostics into one generic "exception while checking" message.
Also harden the remaining diagnostic sorted() calls in C4/C5 with
key=repr, since site_dof and couplings keys aren't guaranteed to be
strings even after the bonds/labels sanitization.
Add negative tests pinning: non-string labels and malformed bonds
now yield specific, non-crashing diagnostics; wannier90-dialect
coupling values that are neither a {param, ...} dict nor a plain
number (a dict without param, and a bare boolean) still raise C12.
C2 sanitization drops malformed bonds from ctx["bonds"], which shifted the enumeration used by C3/C4 and caused them to cite the wrong model.bonds[i] index for bonds after the dropped one. Track each sanitized bond's original source index in ctx["bond_indices"] and use it in C3/C4 instead of re-enumerating the filtered list.
Translate all user-facing content — the manual (7 chapters), the conventions document, README, manifest comments, the comments in all 31 catalog YAML files, and the tools' docstrings and diagnostic messages — from Japanese to English, keeping every parameter name, data value, check ID, and cross-reference intact. Linter and self-tests unchanged in behavior (31 files, 0 errors; all tests pass). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DjgDyCehNnZT7Z4hF2RiGQ
Five experimental samples (dimerized chain, Shastry-Sutherland, kagome with DM, two-orbital Hubbard, cylindrical boundary) probe the limits of the catalog dialect; the observed friction points are compiled into a prioritized feedback document for the next revision of the lattice definition specification. The samples intentionally fail the linter in documented ways and are excluded from its default scan. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DjgDyCehNnZT7Z4hF2RiGQ
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.
Summary
This adds
lattice_catalog/: a static YAML catalog that maps every StdFace lattice and interaction type to the new three-layer lattice-definition format (geometry / system / model) drafted for the 2026/07/27 meeting, together with a Japanese manual and machine-checkable verification tooling.{param, scale, default}references), the 9-component exchange-tensor canonical form with the parameter-resolution cascade, source-order bond convention with reversal equivalence, and the Kondo two-label representationVerification
python/stdface/lattice/*.pyand, where relevant,src/*.c), with provenance (file, function, commit) recorded in the manifest31 files, 0 errors; 56 test functions), and the repository's own unit suite is untouched (1431 passed)trans.defoutput (physical coefficient = +H_mn; the reader-side negation cancels against the solver convention)Notes for reviewers
src/Pyrochlore.c,GeneralJcall withisite + 3). The catalog reproduces this behavior faithfully and flags it as a possible upstream bug in the manual — worth a separate lookJ''/t''/V''inputs are accepted but never wired into any bond;V''is additionally missing from the not-used rejection list, unlike square/triangular — documented in the manual as a possible upstream inconsistency🤖 Generated with Claude Code
https://claude.ai/code/session_01DjgDyCehNnZT7Z4hF2RiGQ