• For users:
• For developers and maintainers:
• Large test set:

Contents

• 1   Introduction
• 2   Quick start guide
  • 2.1   Example
• 3   Installation
• 4   Validation
  • 4.1   Test set
• 5   Known issues and limitations
• 6   Release history highlights
• 7   Copyright and attributions
  • 7.1   Included third-party components
  • 7.2   License

1   Introduction

SLABCC calculates a posteriori energy correction for charged slab models under 3D periodic boundary conditions (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 Gaussian models. The model charge is assumed to be embedded in a medium with a dielectric-tensor profile ε(k) depending only on a single Cartesian space axis (k) that is orthogonal to the slab. The energy correction is calculated as:

E_corr = E_isolated - E_periodic - qΔV

where E_corr is the total energy correction for the model; E_periodic is the energy of the model charge, calculated by solving the periodic Poisson equation. E_isolated 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). The manual is accessible online.

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) are in the same directory.

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 a normal direction of (normal_direction = y) and surfaces at (interfaces = 0.25 0.75). The dielectric tensor inside 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. Afterwards, slabcc will:

• 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, the optimized parameters, and the results to the output file.

2. 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 the 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
   

3. 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
   

4. 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, the in-plane dielectric constants must be equal and the model must be surrounded by a 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
   

5. 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 (1/α < 0.2) is necessary. To avoid 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
   

3   Installation

1. Prerequisites:

1. Source: Download the latest stable release and extract the files. You can also clone the git repository and use the latest commit on the master branch to get the latest changes.
2. Compiler: You need a C++ compiler with C++14 standard support (e.g. g++ 5.0 or later)
3. 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 documentation for linking to other BLAS replacements.
4. 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.

2. Configuration: Set compilation parameters through environment variables.

1. $CC: C compiler (default: gcc)
2. $CXX: C++ compiler (default: g++)
3. $FFTW_HOME: path to FFTW library home
4. $FFTW_LIB_FLAG: FFTW library flag (default: -lfftw3)
5. $BLAS_HOME: path to BLAS library home
6. $BLAS_LIB_FLAG: BLAS library flags (default: -lblas -llapack -lpthread)
7. $EXTRA_FLAGS: extra compiler flags for CC and CXX
8. $LD_EXTRA_FLAGS: extra linker flags

3. Compilation: Run the command make in the bin/ to compile the slabcc.
4. Cleanup: You can run make clean to remove the compiled objects. make distclean additionally removes all the compiled objects of the bundled external libraries.

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. However, it is not possible to guarantee this due to the dependency on third-party components. The current version of the slabcc has been built and validated inside containers based on:

• Ubuntu Linux 16.04 (dockerfile)

• with GNU C/C++ compilers (5), OpenBLAS, FFTW

• Ubuntu Linux 22.04 (dockerfiles 1 2)

• with GNU C/C++ compilers (9,11), OpenBLAS, FFTW
• with GNU C/C++ compilers (11), MKL (2023)
• with Intel oneAPI DPC++/C++ Compiler (2023), MKL (2023)
• with LLVM Clang (14), OpenBLAS, FFTW

• AlmaLinux 8.7 (dockerfile)

• with GNU C/C++ compilers (8), BLAS, FFTW

• openSUSE Leap 15.4 (dockerfile)

• with GNU C/C++ compilers (10), BLAS, FFTW

Older versions of the code were also being tested on MS Windows 10 (latest toolchains: Intel C/C++ compilers 19.0.4 and Microsoft C/C++ compilers 19.20.27508 linked to MKL 19.0.4 and FFTW 3.3.5), support for which is currently dropped.

4.1   Test set

You can download a complete test set, including input files, input parameters, and expected output, here! You can also run regression tests and verify their results with make test. You'll need numdiff for these tests.

5   Known issues and limitations

• Only orthogonal cells are supported.
• The 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 that are not surrounded by the vacuum (diel_out > 1). The extrapolation method must be used in these cases.

6   Release history highlights

• 2023-06-05: version 1.0 - Improved build, error mitigation, and correctness checks
• 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-2023, University of Bremen, M. Farzalipour Tabriz

The source code and all documentation are available under the 2-Clause BSD License. For more information, see license.

This code uses several open-source components, each of which is located under a separate sub-directory of src/. The copyrights 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.

Attributions are also present in the binary file and can be accessed by using --copyright flag.

7.1   Included third-party components

• Armadillo C++ Linear Algebra Library licensed under the Apache License 2.0

• Copyright 2008-2023 Conrad Sanderson
• Copyright 2008-2016 National ICT Australia (NICTA)
• Copyright 2017-2023 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 Data61 / CSIRO

• inih (INI Not Invented Here) licensed under the 3-clause BSD license

• © 2009, Ben Hoyt, et al.

• 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-2023, 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.