DefectCorrectionsNotebook

Introduction

This project contains a workflow which aims to allow for convenient and explanatory post-processing of charged defect supercells from electronic structure calculations with the all-electron electronic structure software package FHI-aims.

Usage

The notebook in this repository (DefectCorrectionsNotebook.ipynb) can be used to peform the Lany-Zunger (LZ) finite-size correction scheme (doi: 10.1088/0965-0393/17/8/084002) or the Freysoldt, Neugebauer and Van de Walle (FNV) finite-size correction scheme (doi: 10.1103/PhysRevLett.102.016402) with the option for the potential alignment step to use either planar averages or atom centres with the sampling region proposed by Kumagai and Oba (doi: 10.1103/PhysRevB.89.195205). However, if the defect supercell has been relaxed, the use of atom centres is highly recommended. To view a demo of the notebook see here.

This notebook can also be run as a script for a set of data generated by FHI-aims for charged defect calculation using 'DefectCorrectionsDataset.py'.

Known issues and limitations

This project is currently under development. Tests are currently being run to determine sensible default parameters (although there will later always be the option for manual override by the user). Please see the 'Assumptions' section of the notebook for assumptions made about the defects data during the processing performed by the notebook.

Installation instructions

First download a copy of the repository. All analysis should be performed from the directory containing the notebook file (DefectCorrectionsNotebook.ipynb).

This workflow uses python3. The most convenient way to setup the python environment for this workflow is to use Anaconda. The notebook should be run within this conda environment.

Option 1: Create your conda env directly from the .yml file

All dependencies present when testing this workflow are listed in DefectCorrectionsCondaEnv.yml. This environment can be re-created using conda with

conda env create -n YourChosenEnvName --file DefectCorrectionsCondaEnv.yml

To use this workflow you must then activate this conda environment with

conda activate YourChosenEnvName

Option 2: Create your conda env manually

Alternatively, a conda environment can be created for this workflow and the necessary packages installed one at a time, as outlined below

conda create -n YourChosenEnvName python=3.6

conda activate YourChosenEnvName

conda install -c conda-forge -c suzannekwallace -c breathe coffee_poisson_solver_ko pylada notebookscripter jupyter pytest pytest-cov coveralls

Project components

• DefectCorrectionsNotebook.ipynb: contains all of the processing steps (and explanations) for performing finite-size correction schemes to obtain the defect formation energy for charged defect supercells, for one defect at a time. More information on the correction schemes and processing steps is contained in the notebook.
• DefectCorrectionsDataset.py: allows for running the notebook from the command line for a set of defect supercells data. Further instructions are contained in comments at the top of the script.
• DefectSupercellAnalyses.py: This contains functions used in the notebook workflow that were written for reading in structural information of defect supercells in the geometry file format of FHI-aims ('geometry.in').
• CoffeeConvenienceFunctions.py: This contains functions used in the notebook workflow to automatically generate input files for the CoFFEE software package for performing processing steps for applying corrections to charged defect supercells.
• AtomPotentialAlignment.py: This file contains functions used for performing the potential alignment method with atom-centres and the Kumagai-Oba sampling region (doi: 10.1103/PhysRevB.89.195205) with outputs from FHI-aims, as an alternative to the default in CoFFEE to use planar averages.
• PyladaDefectsImageCharge.py: This file contains functions used for calculating the image-interaction correction from the LZ correction scheme using functions adapted with permission from pylada-defects.
• LogFileSetup.py: This file contains the default format of the log file used to store intermediate processing results from the notebook.
• PlottingFunctions.py: This contains functions called in the notebook to generate various plots.
• DefectCorrectionsCondaEnv.yml: This file stored the conda environment used to run this workflow (see installation instructions below).
• coffee.py: This is the main executable for the CoFFEE package (from version 1.1) that is used in this workflow.
• tests: This directory contains tests for functions written for this workflow and sample data to use with the tests.
• sample_data contains some sample defect data for running the notebook.
• conftest.py is a configuration file for pytest to define the root directory for the testsuite.
• .travis.yml and .coveragerc are files required for Travis-CI and test coverage respectively.

License

This software has been made available under a 3-Clause BSD License.

Code contributions

Contributions to extend the functionality of this workflow are very much welcomed! For this, we welcome contributors to fork their own copy of this repository for local developments before submitting a pull request to merge with this repository. See here for more details on this procedure.

Relevant citations

Methods used in this workflow are taken from a number of publications and so these should be cited when making use of this workflow. For using the LZ correction scheme, please cite doi: 10.1088/0965-0393/17/8/084002 and pylada-defects for the implementation in this workflow with doi: 10.1016/j.commatsci.2016.12.040. For using the FNV correction scheme, please cite doi: 10.1103/PhysRevLett.102.016402 and the CoFFEE package for the implementation in this workflow with doi: 10.1016/j.cpc.2018.01.011. When using atom centres for the potential alignment with the sampling region proposed by Kumagai and Oba, please cite doi: 10.1103/PhysRevB.89.195205.

Authors

• Tong Zhu
• Suzanne K. Wallace

Contact

For any queries or bugs to report, please contact suzywallace501@gmail.com

Acknowledgements

• Volker Blum (Duke University)
• Nathaniel Cohen for support in the development of this workflow and for the NotebookScripter library
• Many useful discussions on defect correction techniques were provided by Stephan Lany, Anuj Goyal, Prashun Gorai and Vladan Stevanovic (NREL and Colorado School of Mines)
• Software packages: CoFFEE and pylada-defects are used for implementing finite-size corrections to defect supercells with different correction schemes