structure-enumeration

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

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