structure-enumeration

name: structure-enumeration description: Generate candidate crystal structures by element substitution in prototype structures metadata:

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

Loads each prototype structure (from MP, local file, or Wyckoff construction)
Identifies the metal site (heaviest non-hydrogen element)
For each target metal, substitutes the metal site and writes a new CIF file
The original prototype is also saved (with _prototype suffix)
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"
    }
  ]
}