mat-ionic-substitution

Ionic Substitution

Goal

To discover new crystal structures using data-mined ionic substitution (Hautier et al. 2011). Two modes:

1. Forward (propose): Given an existing structure, propose all high-probability ion-substituted variants. E.g., input NaCoO₂ → get LiCoO₂, KCoO₂, NaNiO₂, etc.
2. Reverse (find): Given a target composition, find all known crystal structures that can be ion-substituted to create it, plus direct matches from Materials Project.

The substitution probability model is trained on the ICSD (Inorganic Crystal Structure Database) and captures empirical chemical rules about which ions commonly substitute for each other.

[!TIP] After generating candidate structures, relax them with an MLIP and compute their stability (E_hull) to prioritize the most thermodynamically viable candidates.

Instructions

Mode 1: Forward — Propose substitutions from a structure

1. Prepare a source structure (CIF or POSCAR). Ensure it is an ordered structure.

2. Run the forward proposal script:

   # Env: base-agent
   python .agents/skills/mat-ionic-substitution/scripts/propose_substitutions.py \
       --structure source.cif \
       --threshold 0.001 \
       --output_dir proposed_substitutions/
   

   The script will:

   • Auto-decorate the structure with oxidation states (if not already present)
   • Enumerate all charge-balanced ionic substitutions above the threshold
   • Handle single-ion, double-ion, and multi-ion swaps
   • Save each substituted structure as a CIF file
   • Generate a substitution_manifest.json with substitution maps and probabilities

3. Review and filter results: Higher probability → more likely to be stable. Relax top candidates with an MLIP.

Mode 2: Reverse — Find structures for a target composition

1. Run the reverse search script:

   # Env: base-agent
   python .agents/skills/mat-ionic-substitution/scripts/find_structures_for_composition.py \
       --composition LiCl \
       --threshold 0.001 \
       --output_dir structures_for_LiCl/