Repository files navigation

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.

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

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, modularPython 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...

(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 fromdoped. Automated plots of(i,j) single-particle eigenvalues and(k) sitedisplacements from DFT supercell calculations. See theJOSS paper for more details.

pip install doped# install doped and dependencies

Alternatively if desired,doped can also be installed fromconda 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 theInstallation docs if you encounter any issues (e.g. known issue withphonopyCMake build).

If you haven't done so already, you will need to set up your VASPPOTCAR files andMaterials Project API withpymatgen using the.pmgrc.yaml file, in order fordoped to automatically generate VASP input files for defect calculations and determine competing phases for chemical potentials.See the docsInstallation page for details on this.

If you usedoped 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

As shown in thedoped tutorials, it is highly recommended to use theShakeNBreak approach when calculating point defects in solids, to ensure you have identified the groundstate structures of your defects. As detailed in thetheory 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 thedoped defect generation tutorial, with a more in-depth explanation and tutorial given on theShakeNBreak website.

• Y. Fu & H. Lohan et al.Factors Enabling Delocalized Charge-Carriers in Pnictogen-BasedSolar Absorbers: In-depth Investigation into CuSbSe₂Nature Communications 2025
• S. R. KavanaghIdentifying Split Vacancies with Foundation Models and ElectrostaticsarXiv 2025
• S. R. Kavanagh et al.Intrinsic point defect tolerance in selenium for indoor and tandem photovoltaicsChemRxiv 2025
• J. Hu et al.Enabling ionic transport in Li₃AlP₂ the roles of defects and disorderJournal of Materials Chemistry A 2025
• X. Wang et al.Sulfur Vacancies Limit the Open-circuit Voltage of Sb₂S₃ Solar CellsACS Energy Letters 2024
• A. Zhang et al.Optimizing the n-type carrier concentration of an InVO₄ photocatalyst by codoing with donors and intrinsic defectsPhysical Review Applied 2024
• M-L. Wang et al.Impact of sulfur doping on copper-substituted lead apatitePhysical Review B 2024
• S. Quadir et al.Low-Temperature Synthesis of Stable CaZn₂P₂ Zintl Phosphide Thin Films as Candidate Top AbsorbersAdvanced Energy Materials 2024
• M. Elgaml et al.Controlling the Superconductivity of Nb₂Pd_xS₅ via Reversible Li IntercalationInorganic Chemistry 2024
• Z. Yuan & G. HautierFirst-principles study of defects and doping limits in CaOApplied 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-xM_xMn_1.5O₄ 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 LiNiO2₂ACS Energy Letters 2024
• X. Wang et al.Upper efficiency limit of Sb₂Se₃ solar cellsJoule 2024
• I. Mosquera-Lois et al.Machine-learning structural reconstructions for accelerated point defect calculationsnpj 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 ChemistryChemistry of Materials 2024
• Y. Zeng et al.Role of carbon in α-Al2O3:C crystals investigated with first-principles calculations and experimentCeramics International 2024
• X. Wang et al.Four-electron negative-U vacancy defects in antimony selenidePhysical Review B 2023
• Y. Kumagai et al.Alkali Mono-Pnictides: A New Class of Photovoltaic Materials by Element MutationPRX Energy 2023
• S. M. Liga & S. R. Kavanagh, A. Walsh, D. O. Scanlon, G. KonstantatosMixed-Cation Vacancy-Ordered Perovskites (Cs₂Ti_1–xSn_xX₆; X = I or Br): Low-Temperature Miscibility, Additivity, and Tunable StabilityJournal of Physical Chemistry C 2023
• A. T. J. Nicolson et al.Cu₂SiSe₃ as a promising solar absorber: harnessing cation dissimilarity to avoid killer antisitesJournal of Materials Chemistry A 2023
• Y. W. Woo, Z. Li, Y-K. Jung, J-S. Park, A. WalshInhomogeneous Defect Distribution in Mixed-Polytype Metal Halide PerovskitesACS 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. ScanlonOn the possibility of p-type doping in barium stannateApplied Physics Letters 2023
• J. Cen et al.Cation disorder dominates the defect chemistry of high-voltage LiMn_1.5Ni_0.5O₄ (LMNO) spinel cathodesJournal of Materials Chemistry A 2023
• J. Willis & R. Claes et al.Limits to Hole Mobility and Doping in Copper IodideChemistry of Materials 2023
• I. Mosquera-Lois & S. R. Kavanagh, A. Walsh, D. O. ScanlonIdentifying the ground state structures of point defects in solidsnpj Computational Materials 2023
• Y. T. Huang & S. R. Kavanagh et al.Strong absorption and ultrafast localisation in NaBiS₂ nanocrystals with slow charge-carrier recombinationNature Communications 2022
• S. R. Kavanagh, D. O. Scanlon, A. Walsh, C. FreysoldtImpact of metastable defect structures on carrier recombination in solar cellsFaraday 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. WalshRapid Recombination by Cadmium Vacancies in CdTeACS Energy Letters 2021
• C. J. Krajewska et al.Enhanced visible light absorption in layered Cs₃Bi₂Br₉ through mixed-valence Sn(II)/Sn(IV) dopingChemical Science 2021

doped (néeDefectsWithTheBoys) has benefitted from feedback from many users, in particularmembers of theScanlon andWalsh research groups who have used / are using it in their work. Direct contributors are listed in theContributors sidebar above; including Seán Kavanagh, Alex Squires, Adair Nicolson, Irea Mosquera-Lois, Alex Ganose, Bonan Zhu, Katarina Brlec, Sabrine Hachmioune and Savya Aggarwal.

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