---
title: "Interstitial Doping Documentation"
description: "Interstitial Doping is a tool that helps place extra atoms inside crystal structures. It uses a physics-informed approach to find likely interstitial sites with Voronoi tessellation, and then ranks these sites by how well they fit the dopant atom and how favorable the surrounding chemistry is. The m"
url: "https://ouro.foundation/posts/mmoderwell/interstitial-doping-documentation"
id: "019b84d9-17ae-74e7-aca5-7138c19a4696"
type: "post"
---

# Interstitial Doping Documentation

Post by @mmoderwell in #materials-science (all) · 2026-01-03

- Asset id: `019b84d9-17ae-74e7-aca5-7138c19a4696`
- Page: https://ouro.foundation/posts/mmoderwell/interstitial-doping-documentation

# Interstitial Doping Documentation

A physics-informed approach to interstitial site identification and dopant placement in crystalline materials.

> Embedded route: [Create an interstitially doped structure](https://ouro.foundation/routes/mmoderwell/create-an-interstitially-doped-structure)

## **Overview**

This module provides tools for computationally doping crystal structures with interstitial atoms. It uses **Voronoi tessellation** to identify void spaces in the crystal lattice, then ranks potential interstitial sites based on geometric, chemical, and energetic criteria.

The implementation is designed for high-throughput screening of doped materials where approximate placement is sufficient, rather than for precise defect formation energy calculations (which would require DFT relaxation).

---

## **Algorithm**

### **1. Voronoi Tessellation for Void Detection**

The core idea is that **Voronoi vertices** in a crystal structure represent points equidistant from multiple atoms—natural candidates for interstitial sites.

```code-line
┌────────────────────────┐
│                                      │
│    ●           ○           ●        │
│         Voronoi vertex (○)           │
│    ●           ○           ●        │
│                                      │
│    ●           ○           ●        │
│                                      │
└────────────────────────┘
     ● = host atoms    ○ = interstitial sites

```

**Periodic Boundary Conditions (PBC):**
To correctly handle periodicity, we replicate the unit cell into a 3×3×3 supercell before computing the Voronoi tessellation, then filter vertices back to the original cell.

### **2. Site Characterization**

Each Voronoi vertex is characterized by:

| Property | Description |
| -------- | ----------- |
| **Void radius** | Distance to nearest atom minus that atom's effective radius |
| **Coordination number** | Number of atoms within 1.3× the nearest-neighbor distance |
| **Site geometry** | Tetrahedral, octahedral, or general (based on coordination analysis) |
| **Nearest neighbors** | Species and distances of surrounding atoms |

### **3. Site Quality Ranking**

Sites are scored and ranked using a multi-factor quality function:

\[Q = Q_{size} + Q_{geometry} + Q_{coordination} + Q_{chemistry} + Q_{uniformity} + Q_{order}\] 

Where:

- **Q_size**: Preference for void/dopant radius ratio in [1.0, 1.5] (ideal fit)
- **Q_geometry**: Bonus for well-defined tetrahedral (+4) or octahedral (+3.5) sites
- **Q_coordination**: Preference for 4-fold or 6-fold coordination
- **Q_chemistry**: Electronegativity-based compatibility scoring
- **Q_uniformity**: Bonus for uniform neighbor distances (low coefficient of variation)
- **Q_order**: Bonus for high order parameter scores

### **4. Dopant Placement**

Dopants are placed iteratively, selecting the best available site at each step while enforcing:

- **Minimum host-dopant separation**: Based on sum of ionic/atomic radii
- **Minimum dopant-dopant separation**: Configurable (default 3.0 Å) to ensure uniform distribution

---

## **Physical Assumptions**

### **Ionic/Atomic Radii**

The module uses a hierarchy of radius sources:

1. **Ionic radius** (preferred for interstitial chemistry)
2. **Atomic radius** (fallback)
3. **Default 1.0 Å** (if neither available)

```code-line python
# Priority order for effective radius
if ionic_radii available:
    use ionic_radii
elif atomic_radius available:
    use atomic_radius
else:
    use 1.0 Å
```

### **Void Radius Calculation**

The **true void radius** accounts for the size of surrounding atoms:

\[ r_{void} = d_{nearest} - r_{host}\] Where:

- `d_nearest` = distance to nearest host atom
- `r_host` = effective radius of nearest host atom

This ensures we're measuring the actual available space, not just the geometric distance.

### **Coordination Shell Definition**

The coordination shell is defined as all atoms within **1.3× the nearest-neighbor distance**. This tolerance accounts for:

- Thermal vibrations
- Minor structural distortions
- Non-ideal geometries in real materials

### **Chemical Compatibility**

We use **Pauling electronegativity differences** (ΔX) as a proxy for bonding compatibility:

| ΔX Range | Interpretation | Score |
| -------- | -------------- | ----- |
| 0.4 – 1.8 | Favorable ionic/covalent bonding | +1.0 |
| < 0.4 | Metallic-like (acceptable) | +0.5 |
| > 2.5 | Highly ionic (may cause strain) | −0.5 |

**Limitation:** This is a simplified heuristic. True chemical compatibility depends on oxidation states, coordination preferences, and local electronic structure.

---

## **Site Geometry Classification**

### **Tetrahedral Sites**

Identified when:

- Coordination number = 4
- Normalized distance variance < 0.02 (i.e., 4 equidistant neighbors)

In FCC metals, tetrahedral sites are located at (¼, ¼, ¼) and equivalent positions.

### **Octahedral Sites**

Identified when:

- Coordination number = 6
- Normalized distance variance < 0.02 (i.e., 6 equidistant neighbors)

In FCC metals, octahedral sites are at (½, 0, 0) and equivalent positions.
In BCC metals, octahedral sites are smaller and located at edge midpoints.

### **General Sites**

All other coordination environments. These may still be valid interstitial positions but lack the symmetry of tetrahedral/octahedral sites.

---

## **Minimum Separation Constraints**

### **Host-Dopant Separation**

The minimum distance between a dopant and any host atom is:

\[ d_{min} = α × (r_{dopant} + r_{host})\] Where **α** is the `min_separation_factor` (default 0.8).

- α = 1.0: No overlap of atomic spheres
- α = 0.8: Allows ~20% "overlap" (accounts for bonding, lattice relaxation)
- α < 0.8: Increasingly compressed; may require DFT relaxation

### **Dopant-Dopant Separation**

A configurable minimum distance (default **3.0 Å**) between dopant atoms ensures:

- Dopants don't cluster
- More uniform distribution in the structure
- Avoids dopant-dopant interactions that might destabilize the structure

---

## **Spatial Distribution Optimization**

When placing multiple dopants, we optimize for **spatial uniformity** by combining:

1. **Site quality score** (geometric/chemical preference)
2. **Spatial score** (minimum distance to already-placed dopants)

\[ combined score = quality score - 0.2 × spatial score \] The factor 0.2 balances site quality against uniform distribution.

---

## **Limitations & Caveats**

### **What This Module Does Well**

✅ **High-throughput screening**: Quickly generates candidate doped structures
✅ **Physics-informed placement**: Uses geometric and chemical heuristics
✅ **Handles periodicity**: Proper PBC treatment via supercell replication
✅ **Reproducible**: Deterministic with fixed random seed

### **What This Module Does NOT Do**

❌ **Calculate formation energies**: Requires DFT (use VASP, Quantum ESPRESSO, etc.)
❌ **Structural relaxation**: Positions are unrelaxed; always relax with DFT
❌ **Charge state analysis**: Assumes neutral dopants
❌ **Defect interactions**: No treatment of defect-defect coupling beyond separation distance
❌ **Finite-size corrections**: For dilute defects, use appropriate supercell sizes

### **Recommendations for Production Use**

1. **Always relax structures** with DFT before calculating properties
2. **Validate site types** against known interstitial positions for your crystal structure
3. **Use appropriate supercell sizes** (typically 3×3×3 or larger for dilute defects)
4. **Check convergence** of properties with respect to supercell size
5. **Consider symmetry-inequivalent sites** separately for defect formation energy calculations

---

## **Implementation Details**

### **Dependencies**

- **pymatgen**: Crystal structure handling, atomic data
- **scipy**: Voronoi tessellation, KDTree for spatial queries
- **numpy**: Numerical operations

### **Key Classes**

| Class | Purpose |
| ----- | ------- |
| `InterstitialFinder` | Voronoi-based void detection and characterization |
| `InterstitialSite` | Data container for site properties |
| `SpacingChecker` | Validates separation constraints with PBC |

### **Performance Considerations**

- **KDTree** used for O(log n) nearest-neighbor queries
- **Spatial hashing** for O(1) duplicate site detection
- **max_voronoi_sites** parameter limits analysis for large cells
- Unit cell analysis → supercell replication (more efficient than analyzing full supercell)

---

## **Changelog**

### **v2.0 (Current)**

- Corrected void radius calculation (subtracts host atom radius)
- Added chemical compatibility scoring via electronegativity
- Improved geometry classification with coordination shell analysis
- Made random seed configurable for reproducibility

### **v1.0**

- Initial implementation with basic Voronoi analysis
- Simple distance-based site filtering

#

## Assets in this post

- [Create an interstitially doped structure](https://ouro.foundation/routes/mmoderwell/create-an-interstitially-doped-structure) (route, id `be1c9062-9c73-4c56-a91f-6fbbbcad6d4f`)