Welcome to ShakeNBreak!#
SnB) is a defect structure-searching method employing
chemically-guided bond distortions to locate ground-state and metastable
structures of point defects in solid materials.
Main features include:
Defect structure generation:
Automatic generation of distorted structures for input defects
Optionally, input file generation for geometry optimisation with several codes (
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
The code currently supports
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, 25, 2023
ShakeNBreak can be installed using
pip install shakenbreak
Alternatively if needed, it can also be installed from
conda install -c conda-forge shakenbreak
VASP, in order for
ShakeNBreak to automatically generate the pseudopotential
input files (
POTCARs), your local
VASP pseudopotential directory must be set in the
$HOME/.pmgrc.yaml as follows:
PMG_VASP_PSP_DIR: <Path to VASP pseudopotential top directory>
VASP pseudopotential top directory, you should have a folder named
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.
For development work,
ShakeNBreak can also be installed from a copy of the source directory:
ShakeNBreaksource code using the command:
git clone https://github.com/SMTG-Bham/ShakeNBreak
Navigate to root directory:
Install the code, using the command:
pip install -e .
This command tries to obtain the required packages and their dependencies and install them automatically.
ShakeNBreak can be used through a Python API, as exemplified in the SnB Python API Tutorial.
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 int 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
csvfiles 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
Groundstatedirectory 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.
We recommend at least looking through the Tutorials when first starting to use
familiarise yourself with the full functionality and workflow.
ShakeNBreak is built to natively function using
Defect objects (docs available here) and be compatible with the most recent version of
pymatgen. If you are receiving
pymatgen-related errors when using
ShakeNBreak, you may need to update
ShakeNBreak, which can be done with:
pip install --upgrade pymatgen shakenbreak
ShakeNBreak can take
Defect objects as input (to then generate the trial distorted
structures), but also can take in
doped defect dictionaries or
structure files (e.g.
VASP) as inputs. As such, it should be compatible with any defect code
(such as doped, pydefect,
DefAP, PyDEF…) that generates these files.
Please let us know if you have any issues with compatibility, or if you would like to see any additional features added to
ShakeNBreak 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
Bugs reports, feature requests and questions#
Please use the Issue Tracker to report bugs or request new features.
See the Contributing Documentation for detailed instructions.
Unit tests are in the
tests directory and can be run from the top directory using
Automatic testing is run on the master and develop branches using Github Actions. Please
run tests and add new tests for any new features whenever submitting pull requests.
We’ll add papers that use ShakeNBreak to this list as they come out!
X. Wang et al. Physical Review B 2023
Y. Kumagai, S. R. Kavanagh et al. PRX Energy 2023
J. Willis, K. B. Spooner, D. O. Scanlon. Applied Physics Letters 2023
A. T. J. Nicolson et al. Journal of Materials Chemistry A 2023
J. Cen et al. Journal of Materials Chemistry A 2023
J. Willis & R. Claes et al. Chem Mater 2023
I. Mosquera-Lois & S. R. Kavanagh, A. Walsh, D. O. Scanlon npj Computational Materials 2023
Y. T. Huang & S. R. Kavanagh et al. Nature Communications 2022
S. R. Kavanagh, D. O. Scanlon, A. Walsh, C. Freysoldt Faraday Discussions 2022
S. R. Kavanagh, D. O. Scanlon, A. Walsh ACS Energy Letters 2021
C. J. Krajewska et al. Chemical Science 2021 (early version)
License and Citation#
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 Solids. npj Comput Mater 9, 25, 2023
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 the repository CITATIONS.md file.
ShakeNBreak is compatible with Python 3.9 - 3.12 and requires the following open-source python packages: