combinatorial-substitution

name	combinatorial-substitution
description	Use when the user asks for systematic element substitution, combinatorial materials screening, high-throughput composition search, or multi-site replacement across different element groups.

Combinatorial Substitution

Overview

Combinatorial substitution systematically replaces elements at specified sites across multiple groups, generating all combinations for materials discovery. Unlike simple doping (which replaces one element with another), this tool creates the full Cartesian product of substitutions across groups.

Common applications:

• High-entropy alloy screening: test multiple elements at different sublattices
• Perovskite composition search: vary A-site and B-site cations independently
• Catalyst optimization: systematic dopant combinations
• Battery cathode design: screen transition metals at different Wyckoff sites

MCP Tool: catgo_substitution

{"tool": "catgo_substitution", "arguments": {
  "structure": "<current structure dict>",
  "groups": [
    {
      "target_indices": [0, 4, 8],
      "replacement_elements": ["Ti", "Zr", "Hf"]
    },
    {
      "target_indices": [1, 5, 9],
      "replacement_elements": ["Mn", "Fe", "Co"]
    }
  ],
  "max_structures": 500
}}

Parameter	Description	Default
structure	Input structure dict	(required)
groups	Array of substitution groups	(required)
groups[].target_indices	Site indices to substitute in this group	(required)
groups[].replacement_elements	Elements to try at these sites	(required)
max_structures	Safety cap on total combinations	500

Total structures = product of replacement options per group. For the example above: 3 (group 1) x 3 (group 2) = 9 structures.

Router: /build/substitution (POST)

Combinatorics

The tool generates the Cartesian product across groups. Within each group, all target sites receive the same element for a given combination.

Groups	Elements per Group	Total Structures
1 group, 5 elements	5	5
2 groups, 3 each	3 x 3	9
2 groups, 5 each	5 x 5	25
3 groups, 4 each	4 x 4 x 4	64
3 groups, 6 each	6 x 6 x 6	216

The max_structures cap (default 500) prevents accidental generation of extremely large sets.

Complete Workflow: Perovskite ABO3 Screening

Step 1: Fetch a reference perovskite

{"tool": "catgo_fetch", "arguments": {
  "action": "crystal", "formula": "SrTiO3", "source": "mp"
}}

Step 2: Identify site indices

{"tool": "catgo_view", "arguments": {"action": "get_state"}}

Identify A-site (Sr) and B-site (Ti) atom indices from the structure.

Step 3: Generate all A/B combinations

{"tool": "catgo_substitution", "arguments": {
  "groups": [
    {
      "target_indices": [0],
      "replacement_elements": ["Sr", "Ba", "Ca", "La"]
    },
    {
      "target_indices": [1],
      "replacement_elements": ["Ti", "Zr", "Hf", "Mn", "Fe"]
    }
  ]
}}

This generates 4 x 5 = 20 perovskite compositions: SrTiO3, SrZrO3, BaTiO3, LaFeO3, etc.

Step 4: Screen with MLP, then refine with DFT

For 20 structures, use a two-stage workflow:

{"tool": "catgo_workflow_engine", "arguments": {
  "action": "create", "params": {"name": "Perovskite ABO3 screening"}
}}

First relax all candidates with an ML potential:

{"tool": "catgo_workflow_engine", "arguments": {
  "action": "add_task", "params": {
    "workflow_id": "<wf_id>",
    "task_type": "geo_opt",
    "params": {"software": "mlp", "mlp_model": "mace",
               "system_name": "perovskite-screen-mlp"}
  }
}}

Then run DFT on the most promising candidates.

Difference from Doping (catgo_structure action: doping)

Feature	Doping	Combinatorial Substitution
Purpose	Replace one element with another	Screen multiple compositions
Output	1 structure (or enumerated configs)	N structures (Cartesian product)
Groups	Single host/dopant pair	Multiple independent groups
MCP tool	catgo_structure(action: doping)	catgo_substitution
Use case	Targeted modification	Systematic screening

Use doping when you want to modify a single structure. Use substitution when you want to generate a library of compositions.

Common Pitfalls

1. Always check site indices with catgo_view before substituting. Atom indices depend on the specific structure and may change after supercell expansion or slab generation.
2. The Cartesian product can grow rapidly. 4 groups x 6 elements each = 1296 structures. Use max_structures to cap output.
3. All sites within a group receive the same element in each combination. If you need different elements at different sites within the same group, split them into separate groups.
4. Generated structures are unrelaxed. The substituted atoms keep the original positions. Always run geometry optimization before comparing energies.
5. For transition metal substitutions in oxides, enable spin polarization (ISPIN=2) and consider DFT+U corrections.
6. Charge neutrality is not enforced. Substituting Ca2+ for La3+ requires compensating defects or a charged cell.