substitutional-doping

name	substitutional-doping
description	Use when the user asks to dope a material, substitute one element for another, create alloy surfaces, or introduce heteroatoms into a structure.

Substitutional Doping

Overview

Substitutional doping replaces one or more host atoms with dopant atoms. Common applications:

• Catalyst tuning: Fe-doped NiOOH for OER, N-doped graphene for ORR
• Alloy surfaces: PtRu, PtNi, CuZn for selectivity control
• Band engineering: Al-doped ZnO, Nb-doped TiO2
• Single-atom catalysts: isolated Pt in CeO2, Fe in N-doped carbon

MCP Tool: catgo_structure(action: replace_atom)

Replace a single atom

{"tool": "catgo_structure", "arguments": {
  "action": "replace_atom",
  "atom_index": 5,
  "new_element": "Co"
}}

This replaces atom #5 (0-based index) with Co, keeping the same position.

Identify which atom to replace

First, inspect the structure to find the target atom:

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

The response lists all atoms with indices, elements, and positions. Select the atom index based on:

• Element type (replace Ni with Co)
• Position (surface vs bulk, specific layer)

Replace multiple atoms (alloy)

For a Pt3Ni(111) alloy slab, replace every 4th Pt with Ni:

{"tool": "catgo_structure", "arguments": {
  "action": "replace_atom", "atom_index": 3, "new_element": "Ni"
}}

{"tool": "catgo_structure", "arguments": {
  "action": "replace_atom", "atom_index": 7, "new_element": "Ni"
}}

{"tool": "catgo_structure", "arguments": {
  "action": "replace_atom", "atom_index": 11, "new_element": "Ni"
}}

Verify after doping

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

Check: correct composition, dopant in expected position, no structural distortion (will be resolved by geo_opt).

Complete Doping Workflow: Fe-doped NiOOH for OER

Step 1: Fetch and build host structure

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

{"tool": "catgo_structure", "arguments": {
  "action": "slab", "miller_index": [0, 0, 1],
  "min_slab_size": 12.0, "min_vacuum_size": 15.0
}}

{"tool": "catgo_structure", "arguments": {
  "action": "supercell", "scaling": [2, 2, 1]
}}

Step 2: Replace one Ni with Fe

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

Identify a surface Ni atom (e.g., atom_index=8):

{"tool": "catgo_structure", "arguments": {
  "action": "replace_atom", "atom_index": 8, "new_element": "Fe"
}}

Step 3: Relax doped structure

{"tool": "catgo_workflow_engine", "arguments": {
  "action": "create", "name": "Fe-doped NiOOH OER"
}}

{"tool": "catgo_workflow_engine", "arguments": {
  "action": "add_task", "workflow_id": "wf_doped",
  "task_type": "geo_opt",
  "params": {"software": "vasp", "ENCUT": 520,
             "system_name": "Fe-NiOOH relaxation"}
}}

Python API

from catgo.workflow import Workflow
import json

# Load and modify structure
with open("niooh_slab.json") as f:
    structure = json.load(f)

# Replace atom in structure dict before workflow
# (Index 8 is a surface Ni atom)
structure["sites"][8]["species"][0]["element"] = "Fe"

wf = Workflow("Fe-doped NiOOH")

inp = wf.add_task("structure_input", structure=json.dumps(structure))
opt = wf.add_task("geo_opt",
    structure=inp.output.structure,
    software="vasp", ENCUT=520, ISPIN=2)

wf.submit()

Doping Strategies

Surface Doping

Replace atoms in the top 1-2 layers. These directly interact with adsorbates and affect catalytic properties.

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

Surface atoms have the highest z-coordinates. Replace those.

Subsurface Doping

Replace atoms in the 2nd or 3rd layer. This modifies the electronic structure of surface atoms (ligand effect) without directly participating in bonding.

Random Alloy

For a random A_x B_(1-x) alloy, replace atoms randomly to match the desired composition. For a 2x2x1 slab with 16 metal atoms:

Composition	Atoms to Replace
Pt3Ni (25% Ni)	4 of 16
PtNi (50% Ni)	8 of 16
PtNi3 (75% Ni)	12 of 16

Ordered Alloy

For L1_0 or L1_2 ordered alloys, replace atoms in a specific pattern. Use catgo_view to identify the sublattice positions.

Magnetic Considerations

Many dopants (Fe, Co, Ni, Mn, Cr) are magnetic. Enable spin polarization:

{"tool": "catgo_workflow_engine", "arguments": {
  "action": "add_task", "workflow_id": "wf_doped",
  "task_type": "geo_opt",
  "params": {
    "software": "vasp", "ENCUT": 520,
    "ISPIN": 2,
    "MAGMOM": "16*0.6 1*5.0 24*0.6",
    "system_name": "spin-polarized Fe-NiOOH"
  }
}}

Set initial MAGMOM high for the dopant atom (e.g., 5.0 for Fe) and low for the host (e.g., 0.6 for Ni in NiOOH).

DFT+U for Transition Metal Dopants

Localized d-electrons in dopants often require Hubbard U correction:

Dopant	Typical U (eV)	Host Systems
Fe (3d)	4.0-5.3	Oxides, oxyhydroxides
Co (3d)	3.3-3.5	Oxides
Ni (3d)	6.0-6.4	NiO, NiOOH
Mn (3d)	3.9-4.0	MnO2, perovskites
Ti (3d)	3.0-4.0	TiO2

Add U parameters via LDAU settings in VASP task params.

Common Pitfalls

1. Always relax (geo_opt) after doping. The dopant has a different atomic radius, so the local structure will distort.
2. For charged dopants (e.g., Al3+ replacing Si4+), the system may need charge compensation. Consider adding/removing atoms or using a charged cell (not recommended for slabs).
3. Doping changes atom indices. If you plan to place adsorbates after doping, re-check atom positions with catgo_view.
4. For transition metal dopants in oxides, always use ISPIN=2 and consider DFT+U. Non-magnetic calculations may converge to wrong electronic ground states.
5. When comparing doped vs undoped systems, use the same supercell size, k-points, and ENCUT. The doped cell should only differ by the substituted atom.
6. For single-atom catalysts (SAC), use a large supercell (3x3 or 4x4) to minimize dopant-dopant periodic interactions.