lamm-mit/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):

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):

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:

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:

{
  "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)

{
  "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"
    }
  ]
}