Doped

<a href="https://doped.readthedocs.io/en/latest/"><img align="right" width="150" src="https://raw.githubusercontent.com/SMTG-Bham/doped/main/docs/Images/doped_v2_logo.png" alt="Schematic of a doped (defect-containing) crystal, inspired by the biological analogy to (semiconductor) doping." title="Schematic of a doped (defect-containing) crystal, inspired by the biological analogy to (semiconductor) doping."></a>doped is a Python software for the generation, pre-/post-processing and analysis of defect supercell calculations, implementing the defect simulation workflow in an efficient, reproducible, user-friendly yet powerful and fully-customisable manner. doped is open-source, developed by members of the Simulation of Advanced Materials lab at Cambridge, the Scanlon group at Birmingham, the Walsh group at Imperial College and contributors from across the globe.

• doped Documentation Site
• Questions Related to doped and Instructions

Tutorials showing the code functionality and usage are provided on the docs site, and an overview of the key advances of the package is given in the JOSS paper.

Key Features

All features and functionality are fully-customisable:

• Supercell Generation: Generate an optimal supercell, maximising periodic image separation for the minimum number of atoms (computational cost).
• Defect Generation: Generate defect supercells and guess likely charge states based on chemical intuition.
• Calculation I/O: Automatically write inputs and parse calculations (VASP & other DFT/force-field codes).
• Chemical Potentials: Determine relevant competing phases for chemical potential limits, with automated calculation setup, parsing and analysis.
• Defect Analysis: Automatically parse calculation outputs to compute defect formation energies, finite-size corrections (FNV & eFNV), symmetries, degeneracies, transition levels, etc.
• Thermodynamic Analysis: Compute (non-)equilibrium Fermi levels, defect/carrier concentrations etc. as functions of annealing/cooling temperature, chemical potentials etc.
• Plotting: Generate publication-quality plots of defect formation energies, chemical potential limits, defect/carrier concentrations, Fermi levels, charge corrections, etc.
• Python Interface: Fully-customisable, modular Python API. Plug-and-play w/ShakeNBreak – defect structure-searching, easyunfold – band unfolding, CarrierCapture.jl/nonrad – non-radiative recombination etc.
• Reproducibility, tabulation, automated compatibility/sanity checking, strain/displacement analysis, shallow defect analysis, high-throughput compatibility, Wyckoff analysis...

Performance and Example Outputs

(a) Optimal supercell generation comparison. (b) Charge state estimation comparison. Example (c) Kumagai-Oba (eFNV) finite-size correction plot, (d) defect formation energy diagram, (e) chemical potential / stability region, (f) Fermi level vs. annealing temperature, (g) defect/carrier concentrations vs. annealing temperature and (h) Fermi level / carrier concentration heatmap plots from doped. Automated plots of (i,j) single-particle eigenvalues and (k) site displacements from DFT supercell calculations. See the JOSS paper for more details.

Installation

pip install doped  # install doped and dependencies

If you want to install the latest development version of doped, this can be done following the Developer Installation instructions, or with:

pip install https://github.com/SMTG-Bham/doped/archive/develop.zip

Alternatively if desired, doped can also be installed from conda with:

  conda install -c conda-forge doped
  pip install pydefect  # pydefect not available on conda, so needs to be installed with pip or otherwise, if using the eFNV correction

See the Installation docs if you encounter any issues (e.g. known issue with phonopy CMake build).

If you haven't done so already, you will need to set up your VASP POTCAR files and Materials Project API with pymatgen using the .pmgrc.yaml file, in order for doped to automatically generate VASP input files for defect calculations and determine competing phases for chemical potentials. See the docs Installation page for details on this.

Citation

If you use doped in your research, please cite:

• S. R. Kavanagh et al. doped: Python toolkit for robust and repeatable charged defect supercell calculations. Journal of Open Source Software 9 (96), 6433, 2024

Literature

The following literature contain useful discussions of various aspects of defect calculations:

• Quick-Start Guide on Defect Calculations – Kim et al.
• Guidelines for Defect Simulations – Squires et al.
• Large Review on Defect Calculations – Freysoldt et al.
• Guide to Understanding Formation Energy / Transition Level Diagrams – Gorai
• Defect Structure Searching – Mosquera-Lois et al.
• Free Energies of Defects – Mosquera-Lois et al.
• DeepWiki Code Overview & Workflow

ShakeNBreak

As shown in the doped tutorials, it is highly recommended to use the ShakeNBreak approach when calculating point defects in solids, to ensure you have identified the groundstate structures of your defects. As detailed in the theory paper, skipping this step can result in drastically incorrect formation energies, transition levels, carrier capture (basically any property associated with defects). This approach is followed in the doped defect generation tutorial, with a more in-depth explanation and tutorial given on the ShakeNBreak website.

Studies using doped, so far

• A. G. Squires, S. R. Kavanagh, A. Walsh and D. O. Scanlon Guidelines for robust and reproducible point defect simulations in crystals Nature Reviews Materials 2026
• G. Arora et al. Development of interatomic potential and effect of ordering on defect properties in CrMnV Journal of Applied Physics 2025
• A. Abudulimu et al. Radiative Defects in Chloride-Activated CdSe Thin Films ACS Energy Letters 2026 <!-- SI cite though unfortunately, likely also used SnB -->
• H. Ma, J. E. McLeod and C. Stampfl Toward tunable carrier polarity in monolayer ZrS₂: A hybrid functional study of intrinsic and extrinsic defects Physical Review B 2026
• E. I. Jaffal et al. Investigating mechanical properties through defect chemistry in hard binary phosphide material Ta₃P Solid State Communications 2026
• A. Lannerd et al. Thermodynamics of proton insertion across the perovskite-brownmillerite transition in La_0.5Sr_0.5CoO_3-δ Physical Review Materials 2026
• L. Tian et al. Optical Spectroscopic Determination of Photoexcited Small-Polaron Hopping in Transition Metal Oxide Photocatalysts Chemical Science 2026
• M. Biswas et al. Unified Graph-based Interatomic Potential for Perovskite Structure Optimization Journal of Chemical Information and Modeling 2026
• S. R. Kavanagh Identifying Split Vacancy Defects with Machine-Learned Foundation Models and Electrostatics JPhys Energy 2025
• R. Claes, A. G. Squires and D. O. Scanlon **_Establishing Doping Limits for ZnGa<s