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 likely charge states from chemical intuition.

• Calculation I/O: Automatically write inputs & 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, full inclusion of metastable states 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 and modular Python API, being plug-and-play with ShakeNBreak for defect structure-searching, easyunfold for band unfolding, CarrierCapture.jl/nonrad for non-radiative recombination etc.

• Reproducibility, tabulation, automated compatibility/sanity checking, strain/displacement analysis, shallow defect / eigenvalue 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

doped can be installed via PyPI (pip install doped) or conda if preferred (conda install -c conda-forge doped; pip install pydefect), and further instructions for setting up POTCAR files with pymatgen (needed for input file generation), if not already done, are provided on the Installation page.

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

ShakeNBreak

As shown in the tutorials, it is highly recommended to use the ShakeNBreak approach when calculating point defects in solids, to ensure you have identified the ground-state 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 Tutorials, with a more in-depth explanation and tutorial given on the ShakeNBreak documentation.

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

• N. Singh et al. Data-driven discovery of high-performance quaternary chalcogenide photovoltaics Physical Review Applied 2026

• S. Meher, M. Dey and A. K. Singh Origin of Bright Quantum Emissions with a High Debye-Waller Factor in Silicon Nitride Nano Letters 2026

• B. Bakhit et al. HfO₂-based memristive synapses with asymmetrically extended p-n heterointerfaces for highly energy-efficient neuromorphic hardware Science Advances 2026

• M. Saminathan et al. Interplay between Cu Delocalization and Bonding Anisotropy on the Thermoelectric Performance of Double-Cation Chalcohalides CuBiSeX₂ (X = Cl, Br) ACS Applied Energy Materials 2026

• A. Zhang et al. Theoretical insight into the strategy for high electron carrier concentration in Bi₂WO₆ with intrinsic point defects Physical Review B 2026

• L. Zhang, M. Zhou and A. M. Ganose Dopability limits in Al-rich AlGaN alloys for far-UVC LEDs arXiv 2026

• X. Wang, I. Mosquera-Lois and A. Walsh Multi-fidelity Machine Learning Interatomic Potentials for Charged Point Defects arXiv 2026

• R. Claes, K. Li, A. G. Squires and D. O. Scanlon Screening ASb₂O₆ (A = Mg, Ca, Sr, Ba, Cd) for High Performance Transparent Conducting Oxides ChemRxiv 2026

• S. Ling et al. Investigations of Defect Physics and Quenching Effect for Optimizing n-type Carrier Concentration in CuWO ₄ Photocatalyst Inorganic Chemistry 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

• 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.5 Sr _0.5 CoO _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₂O₄ for Ultra Wide Bandgap Semiconductor Applications ACS Applied Materials & Interfaces 2025

• T. Oikawa et al. Semi-automated estimation of hydrogenic initial states for localized Wannier functions arXiv 2025

• J. Zhou et al. Breaking the 800 mV open-circuit voltage barrier in antimony sulfide photovoltaics arXiv 2025

• K. Talit et al. Structural and electronic properties of Ti- and Ca-doped hexagonal TbInO₃ Physical Review Materials 2025

• I. Mosquera-Lois and A. Walsh Dynamic Vacancy Levels in CsPbCl₃ Obey Equilibrium Defect Thermodynamics PRX Energy 2025

• B. I. J. Johnston et al. Enhanced cycling stability of LiNiO₂ cathodes through a Mg/W dual-cation modification strategy Journal of Materials Chemistry A 2025

• Z. Li and A. Walsh Thermodynamics of Sulfur Vacancy Formation in the Chalcogenide Perovskite BaZrS₃ Journal of Physical Chemistry C 2025

• P. Russell et al. Computational prediction of Y-doped Cd₂Sb₂O₇ as a competitive Sb-based n-type Transparent Conducting Oxide ChemRxiv 2025

• V. Watson et al. Enhanced Oxide Ion Diffusion by Lanthanum Substitution in the Palmierite Sr _3–3x La _2x V₂O₈ via Increased Tetrahedral Distortion and Cation Vacancies Chemistry of Materials 2025

• P. Deng et al. Temperature and Doping Dependence of Carbon Interstitial Diffusion in 4H-SiC from First Principles Advanced Electronic Materials 2025

• P. Deng et al. Carbon Interstitial Diffusion in 3C-SiC: Role of Charge-State Transitions and Entropy Advanced Theory and Simulations 2025

• P. Panagis Filippatos et al. Ab initio investigation of the Cr substitutional defect in α-quartz for quantum applications Journal of Applied Physics 2025

• P. Panagis Filippatos, A. Chroneos and N. Kelaidis A first-principles investigation of halogen doped diamond and its application to quantum technologies Journal of Applied Physics 2025

• P. Panagis Filippatos, T. J. P. Irons and K. Inzani Revisiting intrinsic spin defects in hexagonal boron nitride with r2SCAN arXiv 2025

• M. A. Fadla et al. Tailoring the Electronic Properties of Monoclinic (In _x Al _1-x )₂O₃ Alloys via Substitutional Donors and Acceptors Physical Review Materials 2025

• M. E. Turiansky et al. Machine Learning Phonon Spectra for Fast and Accurate Optical Lineshapes of Defects arXiv 2025

• C. López et al. Chalcogen Vacancies Rule Charge Recombination in Pnictogen Chalcohalide Solar-Cell Absorbers ACS Energy Letters 2025

• K. Ogawa et al. Defect Tolerance via External Passivation in the Photocatalyst SrTiO₃:Al Journal of the American Chemical Society 2025

• M. S. Islam et al. Diffusion Characteristics of Ru and Oxygen Vacancies in Ta₂O₅ for Resistive Random Access Memory Devices: A Density Functional Theory Investigation Advanced Electronic Materials 2025

• J. Tu et al. Giant switchable ferroelectric photovoltage in double-perovskite epitaxial films through chemical negative strain Science Advances 2025

• Y. Fu & H. Lohan et al. Factors Enabling Delocalized Charge-Carriers in Pnictogen-Based Solar Absorbers: In-depth Investigation into CuSbSe₂ Nature Communications 2025

• S. R. Kavanagh et al. Intrinsic point defect tolerance in selenium for indoor and tandem photovoltaics Energy & Environmental Science 2025

• N. T. Taylor et al. Instability of oxide perovskite surfaces induced by vacancy formation Physical Review B 2025

• J. Hu et al. Enabling ionic transport in Li₃AlP₂ the roles of defects and disorder Journal of Materials Chemistry A 2025

• X. Jiang et al. Carrier lifetime killer in 4H-SiC: carrier capture path via carbon vacancies Journal of Materials Chemistry C 2025

• G. Kalemai et al. Flexible Inorganic/Organic Memristor Based on W-Doped MoOx/Poly(methyl methacrylate) Heterostructure Nanomaterials 2025

• M. R. Khan et al. Interplay between intrinsic defects and optoelectronic properties of semi-Heusler gapped metals Physical Chemistry Chemical Physics 2025

• F. Wang et al. Investigation of hydrogen diffusion in zirconia under extreme conditions Physical Chemistry Chemical Physics 2025

• R. Chinnappan First-principles study of defect energetics and magnetic properties of Cr, Ru and Rh doped AlN Physica Scripta 2025

• R. Desai et al. Exploring the Defect Landscape and Dopability of Chalcogenide Perovskite BaZrS₃ Journal of Physical Chemistry C 2025

• C. Kaewmeechai, J. Strand & A. Shluger Structure and Migration Mechanisms of Oxygen Interstitial Defects in β-Ga₂O₃ Physica Status Solidi B 2025

• Y. Gong Wang et al. Influence of Vanadium and Chromium Doping on the Thermoelectric Performance of AgSbTe₂ Physica Scripta 2025

• W. Gierlotka et al. Thermodynamics of point defects in the AlSb phase and its influence on phase equilibrium Computational Materials Science 2025

• X. Wang et al. Sulfur vacancies limit the open-circuit voltage of Sb₂S₃ solar cells ACS Energy Letters 2024

• A. Zhang et al. Optimizing the n-type carrier concentration of an InVO₄ photocatalyst by codoping with donors and intrinsic defects Physical Review Applied 2024

• M-L. Wang et al. Impact of sulfur doping on copper-substituted lead apatite Physical Review B 2024

• S. Quadir et al. Low-Temperature Synthesis of Stable CaZn₂P₂ Zintl Phosphide Thin Films as Candidate Top Absorbers Advanced Energy Materials 2024

• M. Elgaml et al. Controlling the Superconductivity of Nb₂Pd _x S₅ via Reversible Li Intercalation Inorganic Chemistry 2024

• Z. Yuan & G. Hautier First-principles study of defects and doping limits in CaO Applied Physics Letters 2024

• B. E. Murdock et al. Li-Site Defects Induce Formation of Li-Rich Impurity Phases: Implications for Charge Distribution and Performance of LiNi _0.5-x M _x Mn _1.5 O₄ Cathodes (M = Fe and Mg; x = 0.05–0.2) Advanced Materials 2024

• A. G. Squires et al. Oxygen dimerization as a defect-driven process in bulk LiNiO₂ ACS Energy Letters 2024

• X. Wang et al. Upper efficiency limit of Sb₂Se₃ solar cells Joule 2024

• I. Mosquera-Lois et al. Machine-learning structural reconstructions for accelerated point defect calculations npj Computational Materials 2024

• W. Dou et al. Band Degeneracy and Anisotropy Enhances Thermoelectric Performance from Sb₂Si₂Te₆ to Sc₂Si₂Te₆ Journal of the American Chemical Society 2024

• K. Li et al. Computational Prediction of an Antimony-based n-type Transparent Conducting Oxide: F-doped Sb₂O₅ Chemistry of Materials 2024

• S. Hachmioune et al. Exploring the Thermoelectric Potential of MgB₄: Electronic Band Structure, Transport Properties, and Defect Chemistry Chemistry of Materials 2024

• Y. Zeng et al. Role of carbon in α-Al2O3:C crystals investigated with first-principles calculations and experiment Ceramics International 2024

• X. Wang et al. Four-electron negative-U vacancy defects in antimony selenide Physical Review B 2023

• Y. Kumagai et al. Alkali Mono-Pnictides: A New Class of Photovoltaic Materials by Element Mutation PRX Energy 2023

• S. M. Liga & S. R. Kavanagh, A. Walsh, D. O. Scanlon, G. Konstantatos Mixed-Cation Vacancy-Ordered Perovskites (Cs₂Ti _1–x Sn _x X₆; X = I or Br): Low-Temperature Miscibility, Additivity, and Tunable Stability Journal of Physical Chemistry C 2023

• A. T. J. Nicolson et al. Cu₂SiSe₃ as a promising solar absorber: harnessing cation dissimilarity to avoid killer antisites Journal of Materials Chemistry A 2023

• Y. W. Woo, Z. Li, Y-K. Jung, J-S. Park, A. Walsh Inhomogeneous Defect Distribution in Mixed-Polytype Metal Halide Perovskites ACS Energy Letters 2023

• P. A. Hyde et al. Lithium Intercalation into the Excitonic Insulator Candidate Ta₂NiSe₅ Inorganic Chemistry 2023

• J. Willis, K. B. Spooner, D. O. Scanlon. On the possibility of p-type doping in barium stannate Applied Physics Letters 2023

• J. Cen et al. Cation disorder dominates the defect chemistry of high-voltage LiMn _1.5 Ni _0.5 O₄ (LMNO) spinel cathodes Journal of Materials Chemistry A 2023

• J. Willis & R. Claes et al. Limits to Hole Mobility and Doping in Copper Iodide Chemistry of Materials 2023

• I. Mosquera-Lois & S. R. Kavanagh, A. Walsh, D. O. Scanlon Identifying the ground state structures of point defects in solids npj Computational Materials 2023

• Y. T. Huang & S. R. Kavanagh et al. Strong absorption and ultrafast localisation in NaBiS₂ nanocrystals with slow charge-carrier recombination Nature Communications 2022

• S. R. Kavanagh, D. O. Scanlon, A. Walsh, C. Freysoldt Impact of metastable defect structures on carrier recombination in solar cells Faraday Discussions 2022

• Y-S. Choi et al. Intrinsic Defects and Their Role in the Phase Transition of Na-Ion Anode Na₂Ti₃O₇ ACS Applied Energy Materials 2022

• S. R. Kavanagh, D. O. Scanlon, A. Walsh Rapid Recombination by Cadmium Vacancies in CdTe ACS Energy Letters 2021

• C. J. Krajewska et al. Enhanced visible light absorption in layered Cs₃Bi₂Br₉ through mixed-valence Sn(II)/Sn(IV) doping Chemical Science 2021

Open Science and Reproducibility

Robust, open and reproducible science greatly strengthens the impact of research. This is especially true for computational defect modelling, given the many steps and complexities involved – see Guidelines for robust and reproducible point defect simulations in crystals for discussion.

doped has been built to aid robustness and reproducibility for computational defect studies. We highly recommend that the doped/ShakeNBreak class objects, which store key metadata and can be directly output to lightweight json(.gz) files be shared in open-access repositories upon publication, along with relevant raw computational data. It is also helpful to use the doped summary functions to tabulate key quantities in Supplementary Information files. See the Open Science section of the docs Tips page for details.

Acknowledgements

doped (née DefectsWithTheBoys) has benefitted from feedback from many users, in particular members of the Scanlon and Walsh research groups who have / are using it in their work. Direct contributors are listed in the GitHub Contributors sidebar; including Seán Kavanagh, Alex Squires, Irea Mosquera-Lois, Sefer Bora Lisesivdin, Sheharyar Pervez, Atharva Anturkar, Adair Nicolson, Alex Ganose, Bonan Zhu, Katarina Brlec, Sabrine Hachmioune and Savya Aggarwal.

doped was originally based on the excellent PyCDT (no longer maintained), but transformed and morphed over time as more and more functionality was added. After breaking changes in pymatgen, the package was entirely refactored and rewritten, to work with the new pymatgen-analysis-defects package.

Thanks to Chaoqun Zhang for uploading the YouTube tutorials with Chinese subtitles to Bilibili!