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.

Literature

• 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)

Installation

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 https://github.com/SMTG-Bham/ShakeNBreak

2. Navigate to root directory:

  cd ShakeNBreak

3. Install the code, using the command:

  pip install -e .

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

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.

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.

Contributing

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.

Tests

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.

Acknowledgements

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

• Z. Yuan & G. Hautier First-principles study of defects and doping limits in CaO Applied 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
• Y. Fu & H. Lohan et al. Factors Enabling Delocalized Charge-Carriers in Pnictogen-Based Solar Absorbers: In-depth Investigation into CuSbSe₂ arXiv 2024
• S. Hachmioune et al. Exploring the Thermoelectric Potential of MgB4: Electronic Band Structure, Transport Properties, and Defect Chemistry Chemistry of Materials 2024
• J. Hu et al. Enabling ionic transport in Li3AlP2 the roles of defects and disorder ChemRxiv 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 cells Joule 2024
• I. Mosquera-Lois et al. Machine-learning structural reconstructions for accelerated point defect calculations npj Computational Materials 2024
• S. R. Kavanagh et al. doped: Python toolkit for robust and repeatable charged defect supercell calculations Journal 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
• X. Wang et al. Four-electron negative-U vacancy defects in antimony selenide Physical Review B 2023
• Y. Kumagai et al. Alkali Mono-Pnictides: A New Class of Photovoltaic Materials by Element Mutation PRX Energy 2023
• A. T. J. Nicolson et al. Cu₂SiSe₃ as a promising solar absorber: harnessing cation dissimilarity to avoid killer antisites Journal of Materials Chemistry A 2023
• J. Willis, K. B. Spooner, D. O. Scanlon On the possibility of p-type doping in barium stannate Applied Physics Letters 2023
• J. Cen et al. Cation disorder dominates the defect chemistry of high-voltage LiMn_1.5Ni_0.5O₄ (LMNO) spinel cathodes Journal of Materials Chemistry A 2023
• J. Willis & R. Claes et al. Limits to Hole Mobility and Doping in Copper Iodide Chemistry of Materials 2023
• I. Mosquera-Lois & S. R. Kavanagh, A. Walsh, D. O. Scanlon Identifying the ground state structures of point defects in solids npj 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 recombination Nature Communications 2022
• S. R. Kavanagh, D. O. Scanlon, A. Walsh, C. Freysoldt Impact of metastable defect structures on carrier recombination in solar cells Faraday 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. Walsh Rapid Recombination by Cadmium Vacancies in CdTe ACS Energy Letters 2021
• C. J. Krajewska et al. Enhanced visible light absorption in layered Cs₃Bi₂Br₉ through mixed-valence Sn(II)/Sn(IV) doping Chemical Science 2021 (Early version)
• (News & Views): A. Mannodi-Kanakkithodi The devil is in the defects Nature Physics 2023 (Free-to-read link)

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 CITATIONS.md file.

Requirements

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

• Pymatgen
• Ase
• Hiphive
• Numpy
• Matplotlib
• Pandas
• Seaborn
• Monty
• Click