Skip to main content

Package to generate and analyse distorted defect structures, in order to identify ground-state and metastable defect configurations.

Project description

Build status Documentation Status JOSS PyPI Conda Downloads npj

ShakeNBreak (SnB)

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

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

ShakeNBreak Summary



ShakeNBreak can be installed using pip:

  pip install shakenbreak

Alternatively if needed, it can also be installed from conda with:

  conda install -c conda-forge shakenbreak

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.

Developer installation

For development work, ShakeNBreak can also be installed from a copy of the source directory:

  1. Download ShakeNBreak source code using the command:
  git clone
  1. Navigate to root directory:
  cd ShakeNBreak
  1. Install the code, using the command:
  pip install -e .

This command tries to obtain the required packages and their dependencies and install them automatically.


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: ShakeNBreak CLI

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.

Code Compatibility

ShakeNBreak is built to natively function using pymatgen 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 pymatgen and/or ShakeNBreak, which can be done with:

pip install --upgrade pymatgen shakenbreak

ShakeNBreak can take pymatgen Defect objects as input (to then generate the trial distorted structures), but also can take in pymatgen Structure objects, doped defects or structure files (e.g. POSCARs for VASP) as inputs. As such, it should be compatible with any defect code (such as doped, pydefect, PyCDT, PyLada, DASP, Spinney, 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.


Bugs reports, feature requests and questions

Please use the Issue 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 the PEP8 style guidelines.

See the Contributing Documentation for detailed instructions.


Unit tests are in the tests directory and can be run from the top directory using unittest. 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.


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.

Studies using ShakeNBreak

License and Citation

ShakeNBreak is made available under the MIT License.

If you use it in your research, please cite:

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

BibTeX entries for these papers are provided in the file.


ShakeNBreak is compatible with Python 3.9 - 3.12 and requires the following open-source python packages:

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

shakenbreak-3.3.1.tar.gz (371.2 kB view hashes)

Uploaded Source

Built Distribution

shakenbreak-3.3.1-py3-none-any.whl (304.2 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page