Package: shakenbreak
ShakeNBreak(SnB)ShakeNBreakis 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:Defect structure generation:Automatic generation of distorted structures for input defectsOptionally, input file generation for geometry optimisation with several codes (VASP,CP2K,Quantum-Espresso,CASTEP&FHI-aims)Analysis:Parsing of geometry relaxation resultsPlotting of final energies versus distortion to demonstrate what energy-lowering reconstructions have been identifiedCoordination & bonding analysis to investigate the physico-chemical factors driving an energy-lowering distortionMagnetisation 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.LiteraturePreview: Mosquera-Lois, I.; Kavanagh, S. R.In Search of Hidden Defects,Matter4 (8), 2602-2605,2021Code: Mosquera-Lois, I. & Kavanagh, S. R.; Walsh, A.; Scanlon, D. O.ShakeNBreak: Navigating the defect configurational landscape,Journal of Open Source Software7 (80), 4817,2022Theory/Method: Mosquera-Lois, I. & Kavanagh, S. R.; Walsh, A.; Scanlon, D. O.Identifying the Ground State Structures of Defects in Solids,npj Comput Mater9, 252023News & Views: Mannodi-Kanakkithodi, A.The Devil is in the Defects,Nature Physics2023(Free-to-read link)InstallationShakeNBreakcan be installed usingpip:pipinstallshakenbreakAlternatively if needed, it can also be installed fromcondawith:condainstall-cconda-forgeshakenbreakIf usingVASP, in order forShakeNBreakto automatically generate the pseudopotential input files (POTCARs), your localVASPpseudopotential directory must be set in thepymatgenconfiguration file$HOME/.pmgrc.yamlas follows:PMG_VASP_PSP_DIR:<PathtoVASPpseudopotentialtopdirectory>Within yourVASPpseudopotential top directory, you should have a folder namedPOT_GGA_PAW_PBEwhich contains thePOTCAR.X(.gz)files (in this case for PBEPOTCARs). Please refer to thedopedInstallation docsif 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 installationFor development work, ShakeNBreak can also be installed from a copy of the source directory:DownloadShakeNBreaksource code using the command:gitclonehttps://github.com/SMTG-Bham/ShakeNBreakNavigate to root directory:cdShakeNBreakInstall the code, using the command:pipinstall-e.This command tries to obtain the required packages and their dependencies and install them automatically.UsagePython APIShakeNBreakcan be used through a Python API, as exemplified in theSnB Python API tutorial, with more info available on thedocs.Command line interfaceAlternatively, the code can be used via the command line:The functions provided include:snb-generate: Generate distorted structures for a given defectsnb-generate_all: Generate distorted structures for all defects present in the specified/current directorysnb-run: Submit geometry relaxations to the HPC schedulersnb-parse: Parse the results of the geometry relaxations and write them to ayamlfilesnb-analyse: Generatecsvfiles with energies and structural differences between the final configurationssnb-plot: Generate plots of energy vs distortion, with the option to include a colorbar to quantify structural differencessnb-regenerate: Identify defect species undergoing energy-lowering distortions and test these distortions for the other charge states of the defectsnb-groundstate: Save the ground state structures to aGroundstatedirectory for continuation runsMore information about each function and its inputs/outputs are available from theCLI section of the docsor using-hhelp option (e.g.snb -h).We recommend at least looking through thetutorialswhen first starting to useShakeNBreak, to familiarise yourself with the full functionality and workflow.Code CompatibilityShakeNBreakis built to natively function usingpymatgenDefectobjects (docs available here) and be compatible with the most recent version ofpymatgen.
If you are receivingpymatgen-related errors when usingShakeNBreak, you may need to updatepymatgenand/orShakeNBreak, which can be done with:pipinstall--upgradepymatgenshakenbreakShakeNBreakcan takepymatgenDefectobjects as input (to then generate the trial distorted structures),but alsocan take inpymatgenStructureobjects,dopeddefects or structure files
(e.g.POSCARs forVASP) as inputs. As such, it should be compatible with any defect code
(such asdoped,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 toShakeNBreakto make it more compatible with your code.ContributingBugs reports, feature requests and questionsPlease use theIssue Trackerto 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 thePEP8style guidelines.See theContributing Documentationfor detailed instructions.TestsUnit tests are in thetestsdirectory and can be run from the top directory usingunittest.
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.AcknowledgementsShakeNBreakhas 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 usingShakeNBreakX. Wang et al.arXiv2024I. Mosquera-Lois et al.arXiv2024K. Li et al.ChemRxiv2023X. Wang et al.Physical Review B2023Y. Kumagai, S. R. Kavanagh et alPRX Energy2023J. Willis, K. B. Spooner, D. O. Scanlon.Applied Physics Letters2023A. T. J. Nicolson et al.Journal of Materials Chemistry A2023J. Cen et al.Journal of Materials Chemistry A2023J. Willis & R. Claes et al.Chem Mater2023I. Mosquera-Lois & S. R. Kavanagh, A. Walsh, D. O. Scanlonnpj Computational Materials2023Y. T. Huang & S. R. Kavanagh et al.Nature Communications2022S. R. Kavanagh, D. O. Scanlon, A. Walsh, C. FreysoldtFaraday Discussions2022Y-S. Choi et al.ACS Appl. Energy Mater.2022 (early version)S. R. Kavanagh, D. O. Scanlon, A. WalshACS Energy Letters2021C. J. Krajewska et al.Chemical Science2021  (early version)(News & Views): A. Mannodi-KanakkithodiNature Physics2023 (Free-to-read link)License and CitationShakeNBreak 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 Software7 (80), 4817,2022Theory/Method: Mosquera-Lois, I. & Kavanagh, S. R.; Walsh, A.; Scanlon, D. O.Identifying the Ground State Structures of Defects in Solidsnpj Comput Mater9, 252023You 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.Matter4 (8), 2602-2605,2021BibTeXentries for these papers are provided in theCITATIONS.mdfile.RequirementsShakeNBreakis compatible with Python 3.9 - 3.12 and requires the following open-source python packages:PymatgenAseHiphiveNumpyMatplotlibPandasSeabornMontyClick