Skip to content

Latest commit

 

History

History
249 lines (183 loc) · 15.4 KB

readme.rst

File metadata and controls

249 lines (183 loc) · 15.4 KB

Version 0.8.4 Last update 15 July 2019 Build Status Codacy Badge Test Set

Contents

1   Introduction

SLABCC calculates an a posteriori energy correction for charged slab models under 3D periodic boundary condition (PBC) based on the method proposed in:

Hannu-Pekka Komsa and Alfredo Pasquarello, Finite-Size Supercell Correction for Charged Defects at Surfaces and Interfaces, Physical Review Letters 110, 095505 (2013) DOI: 10.1103/PhysRevLett.110.095505 (Supplements)

This method estimates the error in the total energy of the charged models under 3D PBC, due to the excess charge in the real system using a simple Gaussian model. The model charge is assumed to be embedded in a medium with dielectric-tensor profile depending only on one Cartesian space axis orthogonal to the slab. The energy correction is calculated as:

Ecorr = Eisolated - Eperiodic - qΔV

where, Ecorr is the total energy correction for the model, Eperiodic is the energy of the model charge, calculated by solving the periodic Poisson equation. Eisolated is the energy of the model charge embedded in the dielectric medium and can be determined by extrapolation. q is the total extra charge and ΔV is the difference between the potential of the Gaussian model charge system and the DFT calculations.

The code can also calculate the charge correction for the 2D models under PBC. The isolated energies for the 2D models are calculated by extrapolation based on the method proposed in:

Hannu-Pekka Komsa, Natalia Berseneva, Arkady V. Krasheninnikov, and Risto M. Nieminen, Charged Point Defects in the Flatland: Accurate Formation Energy Calculations in Two-Dimensional Materials, Physical Review X 4, 031044 (2014) DOI: 10.1103/PhysRevX.4.031044 (Erratum)

And by the cylindrical Bessel expansion of the Poisson equation as proposed in:

Ravishankar Sundararaman, and Yuan Ping, First-principles electrostatic potentials for reliable alignment at interfaces and defects, The Journal of Chemical Physics 146, 104109 (2017) DOI: 10.1063/1.4978238
SLABCC have been initially developed for the Bremen Center for Computational Materials Science (BCCMS)

Please read the manual.html for more information on the algorithm, input and outputs.

2   Quick start guide

To calculate the charge correction slabcc needs the following files:

  • Input parameters file (default: slabcc.in)
  • CHGCAR of the neutral system from the VASP calculation (default: CHGCAR.N)
  • CHGCAR of the charged system from the VASP calculation (default: CHGCAR.C)
  • LOCPOT of the neutral system from the VASP calculation (default: LOCPOT.N)
  • LOCPOT of the charged system from the VASP calculation (default: LOCPOT.C)

Input parameters file for a slab should minimally include (all in relative scale [0 1]):

  • charge_position: position of the localized charge
  • diel_in: dielectric tensor of the slab
  • normal_direction: direction normal to the surface
  • interfaces: position of the surfaces of the slab (in the normal direction)

2.1   Example

The following examples list the input parameters to be defined in slabcc.in file, assuming the VASP outputs (LOCPOT and CHGCAR files) to be in the same directory. Please read the manual.html for complete list of the input parameters.

  1. Minimum input: The program models the extra charge with a Gaussian charge distribution localized around the position (charge_position= 0.24 0.56 0.65) in a slab model with normal direction of (normal_direction = y) and surfaces at (interfaces = 0.25 0.75). The dielectric tensor inside of the slab is assumed to be isotropic (diel_in = 4.8):

    charge_position = 0.24  0.56  0.65
diel_in = 4.8
normal_direction = y
interfaces = 0.25 0.75

The program will use the default values for the other parameters to:

  • Load the CHGCAR of charged and neutralized systems.
  • Load the LOCPOT of charged and neutralized systems.
  • Calculate the total extra charge from the difference between the charged and neutralized CHGCARs.
  • Optimize the charge_position, interfaces and charge_sigma.
  • Calculate the total energy correction for the charged system.
  • Write all the input parameters used for calculation, optimized parameters and the results to output file.

  1. Correction with multiple localized Gaussian charges: If a single charge cannot represent your localized charge properly, you can use multiple Gaussian charges in your model. You have to define the positions of each Gaussian charge as shown in example below:

    LOCPOT_charged = CHARGED_LOCPOT
LOCPOT_neutral = UNCHARGED_LOCPOT
CHGCAR_charged = CHARGED_CHGCAR
CHGCAR_neutral = UNCHARGED_CHGCAR
charge_position = 0.24  0.56  0.65; 0.20  0.50  0.65
diel_in = 4.8
normal_direction = a
interfaces = 0.25 0.75

  2. Correction for the uniform dielectric medium e.g. bulk models: You must have the same dielectric tensor inside and outside:

    LOCPOT_charged = CHARGED_LOCPOT
LOCPOT_neutral = UNCHARGED_LOCPOT
CHGCAR_charged = CHARGED_CHGCAR
CHGCAR_neutral = UNCHARGED_CHGCAR
charge_position = 0.24  0.56  0.65
diel_in = 4.8
diel_out = 4.8

  3. Correction for the monolayers i.e. 2D models (without extrapolation): To use the Bessel expansion of the Poisson equation for calculating the isolated energy of the 2D models, in-plane dielectric constants must be equal and the model must be surrounded by the vacuum. Use the extrapolation method (extrapolate=yes) for more general cases:

    LOCPOT_charged = CHARGED_LOCPOT
LOCPOT_neutral = UNCHARGED_LOCPOT
CHGCAR_charged = CHARGED_CHGCAR
CHGCAR_neutral = UNCHARGED_CHGCAR
2D_model = yes
charge_position = 0.5 0.4 0.56
interfaces = 0.66 0.46
normal_direction = z
diel_in = 6.28 6.28 1.83
diel_out = 1

  4. Correction for the monolayers i.e. 2D models (with extrapolation): To calculate the isolated energy by fitting the extrapolation results with the non-linear formula, extrapolation to relatively large cell sizes (α < 0.2) is necessary. To avoid the large discretization errors, the size of the extrapolation grid will be automatically increased:

    LOCPOT_charged = CHARGED_LOCPOT
LOCPOT_neutral = UNCHARGED_LOCPOT
CHGCAR_charged = CHARGED_CHGCAR
CHGCAR_neutral = UNCHARGED_CHGCAR
2D_model = yes
extrapolate = yes
charge_position = 0.5 0.4 0.56
interfaces = 0.66 0.46
normal_direction = z
diel_in = 6.28 6.28 1.83

2.2   Test set

You can download a complete test set including input files, input parameters and expected output here. Bitwise reproducibility of the results is not guaranteed across the different versions.

3   Installation

  1. Prerequisites:
  1. Compiler: You need a C++ compiler with C++14 standard support (e.g. g++ 5.0 or later, icpc 15.0 or later, etc.)
  2. BLAS/OpenBLAS/MKL: You can use BLAS+LAPACK for the matrix operations inside the slabcc but it is highly recommended to use one of the high performance replacements e.g. the OpenBLAS/MKL instead. If you don't have OpenBLAS installed on your system, follow the guide on the OpenBLAS website. Please refer to the Armadillo documentations for linking to the other BLAS replacements.
  3. FFTW: If you don't have FFTW installed on your system follow the guide on the FFTW website. Alternatively, you can use the FFTW interface of the MKL.
  1. Configuration: You must edit the src/makefile to choose your compiler and add the paths to FFTW and BLAS libraries.
  2. Compilation: Run the command make in the src/ to compile the slabcc.
  3. Cleanup: You can run make clean to remove the compiled objects, and static library files. make distclean additionally removes all the compiled objects in the external libraries.

Note: By default, the code will be compiled for the specific microarchitecture of your compilation machine. If you are compiling and running the slabcc on different machines, you must edit the makefile and change the -march flag.

4   Validation

We are trying to keep the slabcc compatible with as many compilers as possible by using only the standard features of the C++ language. But it is not possible to guarantee this due to the dependency on the third-party components. The current version of the slabcc has been built/validated on:

  • CentOS Linux release 7.6.1810
  • with Intel C/C++ compilers 18.0.3, MKL 18.0.3, FFTW (from MKL)
  • Ubuntu Linux release 16.04.6 (Travis)
  • with GNU C/C++ compilers (5.5.0/6.5.0/8.1.0/9.1.0), OpenBLAS 0.2.18, FFTW 3.3.4
  • Microsoft Windows version 10.0.17134
  • with Intel C/C++ compilers 19.0.4, MKL 19.0.4, FFTW 3.3.5
  • with Microsoft C/C++ compilers 19.20.27508, MKL 19.0.4, FFTW 3.3.5

5   Known issues and limitations

  • Shape of the VASP files cell is limited to orthogonal cells.
  • Maximum line length of the input file (slabcc.in) is 4000 bytes.
  • Bessel expansion of the Poisson equation cannot be used for the calculation of isolated energies for the 2D models with anisotropic in-plane screening, trivariate Gaussian model change, or the models which are not surrounded by the vacuum (diel_out > 1). Extrapolation method must be used in these cases.

6   Release history highlights

  • 2019-06-13: version 0.8 - OO redesign
  • 2019-05-14: version 0.7 - Added discretization error mitigation
  • 2019-04-04: version 0.6 - Added trivariate Gaussian model charge and selective charge optimization support
  • 2019-03-18: version 0.5 - Added 2D model support
  • 2018-10-10: version 0.4 - Added spdlog and several user interface and performance improvements
  • 2018-07-29: version 0.3 - First public release

7   Copyright and attributions

Copyright (c) 2018-2019, University of Bremen, M. Farzalipour Tabriz

The source codes and all the documentations are available under The 2-Clause BSD License. For more information see license.

This code uses several open source components each of which are located under a separate sub-directory in the src/. The copyright of these libraries belong to their respective owners. Any modification made to those codes is also published under the same license. We acknowledge and are grateful to these developers and maintainers for their valuable contributions to this software and more importantly to the free software society.
The attributions are also present in the binary file and can be accessed using the command-line parameters.

7.1   Included third-party components

  • Copyright 2008-2018, Conrad Sanderson
  • Copyright 2008-2016, National ICT Australia (NICTA)
  • Copyright 2017-2018, Arroyo Consortium
  • Copyright 2017-2018, Data61, CSIRO
  • This product includes software developed by Conrad Sanderson
  • This product includes software developed at National ICT Australia (NICTA)
  • This product includes software developed at Arroyo Consortium
  • This product includes software developed at Data61, CSIRO
  • inih (INI Not Invented Here) licensed under the 3-clause BSD license
  • clara licensed under the Boost Software License 1.0
  • © 2014, Phil Nash, Martin Hořeňovský, et al.
  • spline (Cubic Spline Interpolation) licensed under the Beer-Ware License 42
  • © 2011, Devin Lane
  • NLOPT licensed under the GNU LGPL
  • © 2007-2014, Massachusetts Institute of Technology
  • © 2007-2014, Steven G. Johnson et al.
  • spdlog licensed under the MIT License
  • © 2016, Gabi Melman, et al.
  • Boost.Predef licensed under the Boost Software License 1.0
  • © 2005-2018 Rene Rivera
  • © 2015 Charly Chevalier
  • © 2015 Joel Falcou, et al.

7.2   License

Copyright (c) 2018-2019, University of Bremen, M. Farzalipour Tabriz

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.