structure-enumeration

# Structure Enumeration Skill Generate candidate crystal structures by substituting elements in a prototype structure. Supports three prototype sources: Materials Project lookup, local CIF files, or building from spacegroup + Wyckoff positions. ## Scripts ### `enumerate_structures.py` — Substitute elements in a prototype From Materials Project (for ambient-pressure phases): ```bash python3 {baseDir}/scripts/enumerate_structures.py \ --prototypes LaH3,CaH2 \ --metals Y,Ca,Sc,Ce \ --format json ``` From Wyckoff positions (for high-pressure or hypothetical phases not in MP): ```bash python3 {baseDir}/scripts/enumerate_structures.py \ --wyckoff '[{"name":"LaH10","spacegroup":225,"lattice":{"a":5.1},"species":["La","H","H"],"coords":[[0,0,0],[0.25,0.25,0.25],[0.118,0.118,0.118]]}]' \ --metals Y,Ca,Sc,Ce \ --format json ``` Multiple prototypes via Wyckoff: ```bash python3 {baseDir}/scripts/enumerate_structures.py \ --wyckoff '[{"name":"LaH10","spacegroup":225,"lattice":{"a":5.1},"species":["La","H","H"],"coords":[[0,0,0],[0.25,0.25,0.25],[0.118,0.118,0.118]]},{"name":"CaH6","spacegroup":229,"lattice":{"a":3.54},"species":["Ca","H"],"coords":[[0,0,0],[0.25,0,0.5]]}]' \ --metals Y,Sc,Ce,Ba \ --format json ``` ## Parameters | Parameter | Description | |-----------|-------------| | `--prototypes` | Comma-separated formulas to fetch from Materials Project (e.g. `LaH3,CaH2`). Only works for phases in MP. | | `--mp-ids` | Comma-separated Materials Project IDs (e.g. `mp-1234,mp-5678`) | | `--prototype-files` | Comma-separated paths to local CIF/POSCAR files | | `--wyckoff` | JSON array of prototype specs for building from spacegroup + Wyckoff positions (see format below). Use this for high-pressure phases not in MP. | | `--metals` | **Required.** Comma-separated target metals for substitution (e.g. `Y,Ca,Sc,Ce`) | | `--output-dir` | Directory for output CIF files (default: `~/.scienceclaw/enumerated_structures`) | | `--format` | `summary` \| `json` | | `--dry-run` | Show plan without generating structures | ## Wyckoff Spec Format Each prototype is a JSON object with: ```json { "name": "LaH10", "spacegroup": 225, "lattice": {"a": 5.1}, "species": ["La", "H", "H"], "coords": [[0,0,0], [0.25,0.25,0.25], [0.118,0.118,0.118]] } ``` - `name`: label for the prototype - `spacegroup`: international space group number - `lattice`: `{"a": ...}` for cubic, `{"a": ..., "c": ...}` for hexagonal - `species`: element at each Wyckoff site (first non-H element is the metal site for substitution) - `coords`: fractional coordinates for each Wyckoff site ### Common superhydride prototypes | Prototype | SG | SG# | Lattice | Species | Coordinates | |-----------|-----|-----|---------|---------|-------------| | LaH10 (clathrate) | Fm-3m | 225 | a=5.1 | La, H, H | [0,0,0], [0.25,0.25,0.25], [0.118,0.118,0.118] | | CaH6 (sodalite) | Im-3m | 229 | a=3.54 | Ca, H | [0,0,0], [0.25,0,0.5] | | H3S | Im-3m | 229 | a=3.09 | S, H | [0,0,0], [0.5,0,0.5] | | YH9 | P63/mmc | 194 | a=3.6, c=5.5 | Y, H, H | [0,0,0.25], [0.167,0.333,0.25], [0.167,0.333,0.583] | ## How It Works 1. Loads each prototype structure (from MP, local file, or Wyckoff construction) 2. Identifies the metal site (heaviest non-hydrogen element) 3. For each target metal, substitutes the metal site and writes a new CIF file 4. The original prototype is also saved (with `_prototype` suffix) 5. All CIF files are written to `--output-dir` ## Output (JSON) ```json { "status": "success", "output_dir": "/home/user/.scienceclaw/enumerated_structures", "prototypes_used": ["LaH10", "CaH6"], "metals": ["Y", "Ca", "Sc"], "total_generated": 6, "structures": [ { "label": "YH10_from_LaH10", "formula": "YH10", "prototype": "LaH10", "metal": "Y", "n_atoms": 44, "cif_path": "/home/user/.scienceclaw/enumerated_structures/YH10_from_LaH10.cif" } ] } ```