Candidate Generator

Inorganic Candidate Generation

This skill guides the systematic generation of inorganic crystal structure candidates using a suite of seven pymatgen-based tools. The methodology is: prototype → explore chemistry → resolve disorder → add defects → augment, selecting the appropriate branch(es) for the discovery goal.

The core philosophy: candidate generation is a funnel. Start broad (many chemistries, many configurations), then narrow using physical filters (charge neutrality, Ewald energy, thermodynamic stability from MP). Always track structures in the ASE database using ase_store_result so nothing is recomputed.

Tool Catalogue

1. pymatgen_prototype_builder — Seed Structure

Builds an ideal crystal from a spacegroup number/symbol, species list, and lattice parameters. This is the entry point for any workflow that starts from scratch rather than an existing structure.

Key parameters:

• spacegroup: int (1–230) or Hermann-Mauguin symbol, e.g. 225 or "Fm-3m"
• species: list of element symbols (['La', 'Mn', 'O', 'O', 'O']) or Wyckoff dict
• lattice_parameters: [a, b, c, alpha, beta, gamma] in Å and degrees; [a] works for cubic
• wyckoff_positions: optional dict mapping Wyckoff labels to species/coords
• output_format: 'dict' (default, pass to other tools), 'poscar', 'cif', 'ase'

Returns: structures[i].structure — pass directly to substitution, enumeration, or defect tools.

wyckoff_positions proximity gotcha: Passing a Wyckoff dict (e.g. {'1a': 'Ba', '1b': 'Ti', '3c': 'O'}) can raise "sites less than 0.01 Å apart" for multi-species prototypes where pymatgen auto-generates overlapping fractional coords. Preferred approach: supply explicit species and coords lists instead, and use validate_proximity=False when debugging a new prototype before finalising lattice parameters.

2. pymatgen_substitution_generator — Chemical Space Exploration

Replaces elements in existing structures. Best for isostructural analogue screening across a fixed lattice topology when charge balance is not strictly required.

Key parameters:

• substitutions: {'Li': 'Na'} (full swap), {'Li': ['Na', 'K']} (one variant per replacement), {'Li': {'replace_with': 'Na', 'fraction': 0.5}} (50 % doping)
• n_structures: variants to generate per substitution combination (default 5). For deterministic full swaps (fraction=1.0) set this to 1 — higher values only produce identical duplicates. Total output = n_structures × num_combinations, capped by max_attempts.
• max_attempts: hard cap on total output count (default 50). If you supply N substitution options with n_structures=k, set max_attempts ≥ N × k or outputs will be silently truncated. Example: 8 B-site metals with n_structures=1 needs max_attempts=8 (or higher); with n_structures=3 needs max_attempts=24.
• enforce_charge_neutrality: set True for ionic materials
• site_selector: 'all', 'wyckoff_4a', 'coordination_6', etc.

When to use over ion_exchange_generator: when you want exploratory doping without strict stoichiometry adjustment and charge neutrality is handled manually or checked post-hoc.

3. pymatgen_ion_exchange_generator — Charge-Neutral Substitution

Replaces a mobile ion (e.g. Li⁺) with one or more ions, automatically adjusting stoichiometry so that total ionic charge is conserved. Only charge-neutral structures are returned by default.

Key parameters:

• replace_ion: element to replace, e.g. 'Li'
• with_ions: ['Na', 'K'] (equal weight) or {'Na': 0.6, 'Mg': 0.4} (weighted split)
• exchange_fraction: fraction of sites to exchange (0–1), default 1.0
• allow_oxidation_state_change: False (default) = only neutral structures returned
• max_structures: cap on returned structures per input (default 10)

Prototypical use cases: Li → Na/K battery cathode analogues, Ca²⁺ → La³⁺ doping in oxides.

4. pymatgen_enumeration_generator — Exhaustive Ordering of Disordered Structures

Takes structures with fractional site occupancies and returns all symmetry-inequivalent ordered supercell approximants up to a cell-size limit, ranked by Ewald energy or cell size.

Key parameters:

• min_cell_size / max_cell_size: supercell multiplier range (1–8); keep max_cell_size ≤ 4 for binaries, ≤ 2 for ternaries to avoid combinatorial explosion
• n_structures: max ordered structures returned per input (default 20, max 500)
• sort_by: 'ewald' (default, lowest energy first), 'num_sites', 'random'
• add_oxidation_states: auto-assign oxidation states for Ewald ranking (default True)
• refine_structure: re-symmetrize before enumeration (recommended, default True)

Requires: enumlib on PATH — install with pip install enumlib or conda install -c conda-forge enumlib.

When to use over sqs_generator: when you need the complete ordered-configuration pool, want to identify the ground-state ordering, or are building a cluster expansion training set.

5. pymatgen_sqs_generator — Special Quasirandom Structures

Finds a small ordered supercell whose Warren-Cowley pair correlations best mimic a perfectly random alloy. Returns the single best quasirandom approximant per input, not the full ordered-configuration space.

Key parameters:

• supercell_size: target formula units in SQS cell (default 8; use 8–16 for binary, 12–24 for ternary)
• supercell_matrix: explicit [nx, ny, nz] or 3×3 matrix (overrides supercell_size)
• n_structures: independent SQS candidates per input (default 3); ranked by sqs_error
• n_mc_steps: Monte Carlo steps per candidate (default 50 000; increase for multicomponent)
• n_shells: correlation shells in objective function (default 4)
• seed: set for reproducibility
• use_mcsqs: use ATAT mcsqs binary if available (better quality for large systems)

When to use over enumeration_generator: target system is a solid solution / high-entropy material where disorder is the physical state being modelled, not a defect to be minimised.

6. pymatgen_defect_generator — Point Defect Supercells

Takes a perfect bulk host structure and generates one supercell per symmetry-inequivalent defect site. Supports vacancies, substitutional dopants, and interstitials.

Key parameters:

• vacancy_species: ['Li', 'O'] — generate V_Li, V_O defects
• substitution_species: {'Fe': ['Mn', 'Co']} — Mn_Fe and Co_Fe substitutionals
• interstitial_species: ['Li'] — find void sites and insert Li
• charge_states: {'V_Li': [-1, 0, 1]} — metadata only; structures are always neutral geometry
• supercell_min_atoms: target atoms in defect supercell (default 64; 64–128 for plane-wave DFT)
• inequivalent_only: True (default) — generate only symmetry-distinct defects

Downstream: feed outputs to pymatgen_perturbation_generator to rattle defect geometries, or save directly to the ASE database via ase_store_result.

7. pymatgen_perturbation_generator — Structural Ensemble / Augmentation

Applies random atomic displacements ("rattling") and/or lattice strain to create ensembles of perturbed structures. Does not change composition.

Key parameters:

• displacement_max: max displacement per atom in Å (default 0.1; typical range 0.05–0.2)
• strain_percent: None (off), scalar (uniform), [min, max] (random range), or 6-element Voigt tensor [e_xx, e_yy, e_zz, e_xy, e_xz, e_yz]
• n_structures: perturbed copies per input (default 10, max 200)
• seed: for reproducibility

Primary uses:

• Provide DFT starting geometries that are not stuck at a symmetry saddle point
• Augment ML training datasets with off-equilibrium configurations
• Generate strained cells for elastic property screening

Workflow Phases

Phase 1: Seed Structure

Start here if no structure exists yet.

pymatgen_prototype_builder(
    spacegroup=225,           # Fm-3m (rock-salt)
    species=['Li', 'O'],
    lattice_parameters=[4.33] # cubic: [a]
)

If a known structure already exists (from mp_get_material_properties, a CIF file, or the ASE database), skip this step and pass that structure directly.

Common prototypes:

Phase 2: Chemical Space Exploration

Choose the branch based on whether charge-neutrality must be enforced:

Branch A — Exploratory (charge balance not enforced):

pymatgen_substitution_generator(
    input_structures=seed_structure,
    substitutions={'Li': ['Na', 'K', 'Rb'], 'Fe': ['Mn', 'Co', 'Ni']},
    n_structures=10,
    enforce_charge_neutrality=False
)

Use when: screening isostructural analogues, building diverse training sets.

Branch B — Charge-neutral (ionic materials):

pymatgen_ion_exchange_generator(
    input_structures=seed_structure,
    replace_ion='Li',
    with_ions={'Na': 0.5, 'Mg': 0.5},
    exchange_fraction=1.0,
    max_structures=20
)

Use when: battery cathode analogues, any case where the oxidation-state bookkeeping must be exact.

Both branches accept lists of input structures — pipe multiple seeds through in one call.

Phase 3: Resolve Disorder (if structures have partial occupancies)

If Phase 2 produced or if you started from a disordered structure:

Ground-state search (small cells, complete enumeration):

pymatgen_enumeration_generator(
    input_structures=disordered_structs,
    max_cell_size=4,
    n_structures=50,
    sort_by='ewald'
)

Solid-solution modelling (large / high-entropy systems):

pymatgen_sqs_generator(
    input_structures=disordered_struct,
    supercell_size=16,
    n_structures=5,
    n_mc_steps=200000,
    seed=42
)

Decision rule:

• Enumeration when you need all low-energy orderings or a CE training set.
• SQS when disorder is the target state (e.g. (Li,Na)₀.₅CoO₂ solid solution).
• For high-entropy systems (≥ 4 mixing species), prefer SQS; enumeration becomes intractable above max_cell_size=2.

Phase 4: Defect Generation (optional branch)

Fork off from any ordered structure to study point defects:

pymatgen_defect_generator(
    input_structure=ordered_structure,
    vacancy_species=['Li'],
    substitution_species={'Fe': ['Mn', 'Co']},
    interstitial_species=['Li'],
    charge_states={'V_Li': [-1, 0, 1]},
    supercell_min_atoms=128
)

Important: Pass only a single, ordered, defect-free host structure. The tool generates one supercell per inequivalent defect site automatically — do not pre-expand the cell.

Phase 5: Perturbation / Augmentation

Apply to any structure from Phases 1–4 to:

• Break symmetry before DFT relaxation (avoid false saddle-point convergence)
• Augment ML training datasets
• Probe elastic and thermal response

pymatgen_perturbation_generator(
    input_structures=ordered_or_defect_structures,
    displacement_max=0.1,
    strain_percent=[-2.0, 2.0],
    n_structures=20,
    seed=0
)

For defect geometries, use displacement_max=0.05–0.1 Å (subtle rattling). For ML data augmentation, 0.1–0.2 Å with random strain is typical.

Connecting to the Rest of the Workflow

Saving to the ASE Database

Always store generated structures so they can be queried later without regeneration:

ase_store_result(
    db_path='candidates.db',
    atoms_dict=structure['structure'],   # MUST use output_format='ase' — see note below
    key_value_pairs={
        'generator': 'substitution',
        'compound': structure['formula'],   # NOT 'formula' — see reserved keys below
        'campaign': 'cathode_screen_2026',
        'source_structure': 'LiCoO2_mp-24850'
    }
)

output_format must be 'ase' when feeding into ase_store_result: ase_store_result requires ASE-native keys (numbers, positions, cell, pbc), which are only produced when the upstream pymatgen tool is called with output_format='ase'. Using the default output_format='dict' produces a pymatgen Structure.as_dict() object (with @module, @class, sites, lattice, etc.) that will be rejected with: "atoms_dict missing required keys: ['numbers']". Always set output_format='ase' on any pymatgen tool whose result goes directly to ase_store_result.

ASE reserved key names — never use these in key_value_pairs: ASE's db.write() will raise ValueError: Bad key for any of the following built-in column names: id, unique_id, ctime, mtime, user, calculator, energy, forces, stress, magmoms, charges, cell, pbc, natoms, formula, mass, volume, spacegroup. Use unambiguous alternatives e.g. compound instead of formula, sg_num instead of spacegroup, uid instead of unique_id.

Query existing candidates before generating new ones to avoid duplication:

ase_query_db(db_path='candidates.db', property_filters={'campaign': 'cathode_screen_2026'})

Filtering with Materials Project

After chemical space exploration, cross-check compositions against the MP convex hull before running expensive DFT:

mp_search_materials(
    formula='NaCoO2',
    is_stable=True
)

Discard compositions that are far above the hull (energy_above_hull > 0.1 eV/atom) unless the target is metastable phases.

Output Format Routing

Common Patterns

Isostructural Analogue Screen

# 1. Build rock-salt seed
seed = pymatgen_prototype_builder(spacegroup=225, species=['Li','O'], lattice_parameters=[4.33])

# 2. Swap Li site: Li → Na, K, Rb; O site: O → S, Se
variants = pymatgen_substitution_generator(
    input_structures=seed['structures'][0]['structure'],
    substitutions={'Li': ['Na', 'K', 'Rb'], 'O': ['S', 'Se', 'O']},
    n_structures=15
)

# 3. Filter by MP stability and store survivors
for s in variants['structures']:
    mp_results = mp_search_materials(formula=s['formula'])
    if mp_results['count'] > 0:
        ase_store_result(db_path='screen.db', atoms_dict=s['structure'],
                         key_value_pairs={'formula': s['formula'], 'campaign': 'rocksalt_screen'})

Li → Na Battery Analogue

licoo2 = mp_get_material_properties('mp-24850')  # LiCoO2
struct_dict = licoo2['properties'][0]['structure']

exchanged = pymatgen_ion_exchange_generator(
    input_structures=struct_dict,
    replace_ion='Li',
    with_ions=['Na'],
    exchange_fraction=1.0,
    max_structures=5
)

High-Entropy Oxide SQS

# Build a rocksalt with 5-component mixing on the cation sublattice
# Input: disordered structure with occupancies {Mg:0.2, Co:0.2, Ni:0.2, Cu:0.2, Zn:0.2}
sqs = pymatgen_sqs_generator(
    input_structures=disordered_cif,
    supercell_size=20,
    n_structures=5,
    n_mc_steps=500000,
    seed=7
)
# Best SQS is sqs['structures'][0] (sorted by sqs_error)

Ground-State Ordering Search

# Li₀.₅CoO₂ starting from partially delithiated structure with site occupancies
ordered_candidates = pymatgen_enumeration_generator(
    input_structures=disordered_struct,
    max_cell_size=4,
    n_structures=100,
    sort_by='ewald'
)
# Top 10 by Ewald energy are the most plausible ground-state orderings
top10 = ordered_candidates['structures'][:10]

Defect-Engineered Cathode

# Start from a relaxed ordered LiMnO2 structure
defect_cells = pymatgen_defect_generator(
    input_structure=limno2_dict,
    vacancy_species=['Li'],
    substitution_species={'Mn': ['Fe', 'Ni', 'Co']},
    supercell_min_atoms=96
)

# Rattle each defect cell before DFT relaxation
for dc in defect_cells['structures']:
    perturbed = pymatgen_perturbation_generator(
        input_structures=dc,
        displacement_max=0.08,
        n_structures=3,
        seed=1
    )
    for p in perturbed['structures']:
        ase_store_result(db_path='defects.db', atoms_dict=p,
                         key_value_pairs={'defect_label': dc['metadata']['defect_label']})

Decision Guide

Need a new structure from scratch?
  └─► pymatgen_prototype_builder

Have an existing structure, want new chemistries?
  ├─ Charge balance is critical (ionic material)?
  │     └─► pymatgen_ion_exchange_generator
  └─ Exploratory / charge balance not enforced?
        └─► pymatgen_substitution_generator

Structure has partial occupancies / is disordered?
  ├─ Want ALL orderings / ground-state search / CE training?
  │     └─► pymatgen_enumeration_generator  (max_cell_size ≤ 4 for binaries)
  └─ Modelling disorder itself (solid solution / high-entropy)?
        └─► pymatgen_sqs_generator

Need point defect supercells?
  └─► pymatgen_defect_generator

Need an ensemble / perturbed copies of any structure?
  └─► pymatgen_perturbation_generator

Pitfalls and Gotchas

enumeration_generator hangs or never returns Cause: max_cell_size too large for the number of mixing species. Combinatorial explosion. Fix: reduce max_cell_size to 2–3, or switch to sqs_generator for multicomponent systems.

enumeration_generator fails on Windows Cause: The tool requires the enum.x (enumlib) binary on PATH. enumlib is not available natively on Windows — it can only be installed inside WSL. Fix: On Windows, fall back to sqs_generator (no binary dependency; uses a built-in MC backend). If ground-state enumeration is essential, run via WSL: wsl conda install -c conda-forge enumlib then add the WSL binary path to the Windows PATH.

Never bypass MCP tools by calling pymatgen directly in scripts Cause: Writing script code that calls pymatgen transformation classes (e.g. EnumerateStructureTransformation) directly risks passing incorrect kwargs as the internal API evolves (e.g. check_ordered_structures vs check_ordered_symmetry), and it loses the error handling and platform abstraction that the MCP tools provide. Fix: Always use the designated MCP tool (pymatgen_enumeration_generator, pymatgen_substitution_generator, etc.). Only drop to direct pymatgen code when an MCP tool explicitly cannot accomplish the task (e.g. manual supercell construction).

substitution_generator silently truncates output when many options are given Cause: max_attempts (default 50) is a hard cap on total output. With a list of N substitution options and n_structures=k, the tool attempts N×k structures but stops at max_attempts, silently dropping the remainder with no error. Symptom: count in the result is less than N×k; some substitution options are missing. Fix: Always set max_attempts = n_structures × len(substitution_options) explicitly. Also set n_structures=1 for deterministic full swaps (fraction=1.0) — higher values just add identical duplicates and inflate the attempt count unnecessarily.

substitution_generator fractional doping silently becomes a full swap on single-site cells Cause: fraction=0.5 on a sublattice with only one site cannot produce a partial occupancy (you cannot remove half an atom). The tool falls back to replacing the whole site, returning the same result as fraction=1.0 with no warning. Symptom: The output formula shows a complete element swap even though fraction < 1.0 was requested; the output is an ordered structure, not a disordered one. Fix: Ensure the input cell has ≥ 2 sites of the target species before using fractional substitution. For a single-site primitive cell (e.g. a 5-atom perovskite with one B-site), either (a) build a supercell first so multiple target sites exist, or (b) manually construct the disordered structure dict with explicit partial occupancies ({"element": "Fe", "occu": 0.5}, {"element": "Co", "occu": 0.5} on the same site) and pass it directly to sqs_generator or enumeration_generator.

ion_exchange_generator returns zero structures Cause: No charge-neutral solution exists at the requested stoichiometry. Fix: Try different exchange_fraction values, use allow_oxidation_state_change=True to debug, or verify oxidation state assumptions with mp_get_material_properties.

defect_generator creates excessively large supercells Cause: supercell_min_atoms is high (default 64) relative to a primitive cell with few atoms. Fix: Lower supercell_min_atoms (e.g. 32 for quick tests), or supply an explicit supercell_matrix.

prototype_builder raises proximity error Cause: The chosen lattice parameters place atoms too close together. Fix: Check against experimental / MP values. Temporarily set validate_proximity=False to retrieve the structure and inspect it before adjusting parameters.

Duplicate structures in candidate pool Cause: Multiple generation paths converge on the same composition and topology. Fix: Query ase_query_db and use unique_key in ase_store_result to deduplicate on formula + source_structure hash before running DFT.

sqs_generator produces poor SQS quality (high sqs_error) Cause: Too few MC steps or too small a supercell for the target composition. Fix: Increase n_mc_steps (try 200 000–500 000) and supercell_size (16–24), or install ATAT and set use_mcsqs=True.

Quick Reference