ShakeNBreak (SnB)

<a href="https://shakenbreak.readthedocs.io/en/latest/"><img align="right" width="400" src="docs/Images/SnB_logo.png"></a> ShakeNBreak is a defect structure-searching method employing chemically-guided bond distortions to locate ground-state and metastable structures of point defects in solid materials.

• ShakeNBreak Documentation Site
• Questions Related to ShakeNBreak and Instructions

ShakeNBreak 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.

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 for VASP)

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

Literature

We kindly ask that you cite the code and theory/method papers if you use ShakeNBreak in your work.

• 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, 25 2023
• News & Views: Mannodi-Kanakkithodi, A. The Devil is in the Defects, Nature Physics 2023 (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
• DeepWiki Code Overview & Workflow

See the doped Literature section for recommended articles on defect modelling in general.

Installation

ShakeNBreak can be installed using conda:

conda install -c conda-forge shakenbreak

or pip:

pip install shakenbreak

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

If using VASP, in order for ShakeNBreak to automatically generate the pseudopotential input files (POTCARs), your local VASP pseudopotential directory must be set in the pymatgen configuration file $HOME/.pmgrc.yaml as follows:

PMG_VASP_PSP_DIR: <Path to VASP pseudopotential top directory>

Within your VASP pseudopotential top directory, you should have a folder named POT_GGA_PAW_PBE which contains the POTCAR.X(.gz) files (in this case for PBE POTCARs). Please refer to the doped Installation docs if you have difficulty with this.

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

Usage

Python API

ShakeNBreak can be used through a Python API, as exemplified in the SnB Python API tutorial, with more info available on the docs.

Command line interface

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 a yaml file
• snb-analyse: Generate csv 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 a Groundstate directory for continuation runs

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

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

Studies using ShakeNBreak

• 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
• X. Wang et al. Making atomistic materials calculations accessible with the AiiDAlab Quantum ESPRESSO app npj Computational Materials 2026
• D. J. Keeble Detection and identification of vacancy defects in antimony selenide Nature Communications 2026
• E. I. Jaffal et al. Investigating mechanical properties through defect chemistry in hard binary phosphide material Ta₃P Solid State Communications 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 Ultrawide-Band-Gap Semiconductor Applications ACS Applied Materials & Interfaces 2025
• Y. Liu, S. Chae and E. Kioupakis Origin of shallow n-type doping in AlN and Al-rich AlGaN arXiv 2025