Repository files navigation

ShakeNBreak is a defect structure-searching method employing chemically-guided bond distortions tolocate ground-state and metastable structures of point defects in solid materials.Docs here!

Main features include:

1. Defect structure generation:
   • Automatic generation of distorted structures for input defects
   • Optionally, input file generation for geometry optimisation with several codes (VASP,CP2K,Quantum-Espresso,CASTEP &FHI-aims)
2. Analysis:
   • Parsing of geometry relaxation results
   • Plotting of final energies versus distortion to demonstrate what energy-lowering reconstructions have been identified
   • Coordination & bonding analysis to investigate the physico-chemical factors driving an energy-lowering distortion
   • Magnetisation analysis (currently only supported forVASP)

The code currently supportsVASP,CP2K,Quantum-Espresso,CASTEP &FHI-aims. Code contributions to support additional solid-state packages are welcome.

• Preview: Mosquera-Lois, I.; Kavanagh, S. R.In Search of Hidden Defects,Matter 4 (8), 2602-2605,2021
• Code: Mosquera-Lois, I. & Kavanagh, S. R.; Walsh, A.; Scanlon, D. O.ShakeNBreak: Navigating the defect configurational landscape,Journal of Open Source Software 7 (80), 4817,2022
• Theory/Method: Mosquera-Lois, I. & Kavanagh, S. R.; Walsh, A.; Scanlon, D. O.Identifying the Ground State Structures of Defects in Solids,npj Comput Mater 9, 252023
• News & Views: Mannodi-Kanakkithodi, A.The Devil is in the Defects,Nature Physics2023 (Free-to-read link)
• YouTube Overview (10 mins):ShakeNBreak: Symmetry-Breaking and Reconstruction at Defects in Solids
• YouTube Seminar (35 mins):Seminar: Predicting the Atomic Structures of Defects

ShakeNBreak can be installed usingconda:

conda install -c conda-forge shakenbreak

orpip:

pip install shakenbreak

See theInstallation docs if you encounter any issues (e.g. known issue withphonopyCMake build).

If usingVASP, in order forShakeNBreak to automatically generate the pseudopotential input files (POTCARs), your localVASP pseudopotential directory must be set in thepymatgen configuration file$HOME/.pmgrc.yaml as follows:

PMG_VASP_PSP_DIR:<Path to VASP pseudopotential top directory>

Within yourVASP pseudopotential top directory, you should have a folder namedPOT_GGA_PAW_PBEwhich contains thePOTCAR.X(.gz) files (in this case for PBEPOTCARs). Please refer to thedoped Installation docs if you havedifficulty with this.

The font Montserrat (Open Font License) will be installed with the package, and will be used by default for plotting.

ShakeNBreak can be used through a Python API, as exemplified in theSnB Python API tutorial, with more info available on thedocs.

Alternatively, the code can be used via the command line:

The functions provided include:

• snb-generate: Generate distorted structures for a given defect
• snb-generate_all: Generate distorted structures for all defects present in the specified/current directory
• snb-run: Submit geometry relaxations to the HPC scheduler
• snb-parse: Parse the results of the geometry relaxations and write them to ayaml file
• snb-analyse: Generatecsv files with energies and structural differences between the final configurations
• snb-plot: Generate plots of energy vs distortion, with the option to include a colorbar to quantify structural differences
• snb-regenerate: Identify defect species undergoing energy-lowering distortions and test these distortions for the other charge states of the defect
• snb-groundstate: Save the ground state structures to aGroundstate directory for continuation runs

More information about each function and its inputs/outputs are available from theCLI section of the docs or using-h help option (e.g.snb -h).

We recommend at least looking through thetutorials when first starting to useShakeNBreak, to familiarise yourself with the full functionality and workflow.You may also find theYouTube Overview (10 mins),YouTube Seminar (35 mins)and/or papers listed in theLiterature section above useful.

• Y. Fu & H. Lohan et al.Factors Enabling Delocalized Charge-Carriers in Pnictogen-BasedSolar Absorbers: In-depth Investigation into CuSbSe₂Nature Communications 2025
• Y. LiuSmall hole polarons in yellow phase δ-CsPbI₃arXiv 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. Zhao et al.Trace Yb doping-induced cationic vacancy clusters enhance thermoelectrics in p-type PbTeApplied Physics Letters 2025
• Z. Cai & C. MaOrigin of oxygen partial pressure-dependent conductivity in SrTiO₃Applied Physics Letters 2025
• W. D. Neilson et al.Oxygen Potential, Uranium Diffusion, and Defect Chemistry in UO_2±x: A Density Functional Theory StudyJournal of Physical Chemistry C 2024
• X. Wang et al.Sulfur Vacancies Limit the Open-circuit Voltage of Sb₂S₃ Solar CellsACS Energy Letters 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
• S. R. Kavanagh et al.doped: Python toolkit for robust and repeatable charged defect supercell calculationsJournal of Open Source Software 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 MgB4: Electronic Band Structure, Transport Properties, and Defect ChemistryChemistry of Materials 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
• 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
• 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
• B. Peng et al.Advancing understanding of structural, electronic, and magnetic properties in 3d-transition-metal TM-doped α-Ga₂O₃ (TM = V, Cr, Mn, and Fe)Journal of Applied Physics 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 (Early version)
• 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 (Early version)
• (News & Views): A. Mannodi-KanakkithodiThe devil is in the defectsNature Physics 2023 (Free-to-read link)

ShakeNBreak is made available under the MIT License.

If you use it in your research, please cite:

• Code: Mosquera-Lois, I. & Kavanagh, S. R.; Walsh, A.; Scanlon, D. O.ShakeNBreak: Navigating the defect configurational landscape.Journal of Open Source Software 7 (80), 4817,2022
• Theory/Method: Mosquera-Lois, I. & Kavanagh, S. R.; Walsh, A.; Scanlon, D. O.Identifying the Ground State Structures of Defects in Solidsnpj Comput Mater 9, 252023

You may also find this Preview paper useful, which discusses the general problem of defect structure prediction:

• Mosquera-Lois, I.; Kavanagh, S. R.In Search of Hidden Defects.Matter 4 (8), 2602-2605,2021

BibTeX entries for these papers are provided in theCITATIONS.md file.

ShakeNBreak is built to natively function usingdoped /pymatgenDefect objects and be compatible with the most recent version ofpymatgen.If you are receivingpymatgen-related errors when usingShakeNBreak, you may need to updatepymatgen and/orShakeNBreak, which can be done with:

pip install -U pymatgen shakenbreak

ShakeNBreak is compatible with a variety of inputs (to then generate the trial distorted structures), includingdoped /pymatgenDefect objects,pymatgenStructure objects or structure files(e.g.POSCARs forVASP). As such, it should be compatible with any defect code(such asdoped,pydefect,PyCDT,PyLada,DASP,Spinney,DefAP,PyDEF...) or manual defect supercell generation.Please let us know if you have any issues with compatibility, or if you would like to see any additional features added toShakeNBreak to make it more compatible with your code.

ShakeNBreak has benefitted from feedback from many members of the Walsh and Scanlon research groups who have used / are using it in their work, including Adair Nicolson, Xinwei Wang, Katarina Brlec, Joe Willis, Zhenzhu Li, Jiayi Cen, Lavan Ganeshkumar, Daniel Sykes, Luisa Herring-Rodriguez, Alex Squires, Sabrine Hachmioune and Chris Savory.

Please use theIssue Tracker to report bugs or request new features.

Contributions to extend this package are very welcome! Please use the"Fork and Pull"workflow to do so and follow thePEP8 style guidelines.

See theContributing Documentation for detailed instructions.