Developers Manual:Exchange and Correlation

From OctopusWiki
Revision as of 22:38, 20 March 2015 by Dstrubbe (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Octopus uses libxc, which holds the parametrizations of the LDA, GGA, etc. functionals.

WARNING: This page is out of date.

xc module

Introduction

This module takes care of most of the problem of calculating the exchange-correlation potential and energy functionals. Unfortunately, it cannot handle the whole problem, as would be desirable, because the OEP functionals have to be handled within the hamiltonian module (to obtain an OEP functional one needs to apply the Hamiltonian). Since Fortran 90 is unable to handle circular dependencies, obtaining OEP functionals (or obtaining the SIC through the OEP method) is done in the xc_oep subroutine in the hamiltonian module. We can consider xc_oep to be within the xc module in spirit.

Types

xc_type

type(xc_functl_type) :: functl(2)
integer              :: sic_correction
type(xc_functl_type) :: sic_aux(2)
integer              :: mGGA_implementation
integer              :: oep_level
FLOAT                :: oep_mixing
logical              :: nlcc

This data type holds all the necessary information to fully characterize the exchange and correlation functional used in an octopus calculation. Its components are the following:

  • functl(2): The first element of this two-element array is the xc_functl_type structure that holds the information about the exchange functional; the second element holds the correlation functional.
  • sic_correction determines wether self-interaction corrections (SIC) are to be applied or not. It only holds if any of the functl components is holding a functional of the XC_FAMILY_LDA or XC_FAMILY_GGA families. The possible values are: 0 (do not apply SIC corrections), or anything else

(do apply SIC corrections).

  • sic_aux(2): These are two xc_functl_type structures, which hold auxiliary exchange and correlation functionals, necessary to builid the SIC. [WARNING: I believe that this could be avoided]
  • mGGA_implementation: The mGGA functional is in fact an orbital-dependent functional. It may then also use the OEP formalism. The precise way in which the mGGA functional is implemented is then decided by this variable, which may take two values:
    • mGGA_implementation = 1: GEA-like implementation (not working).
    • mGGA_implementation = 2: OEP-like implementation (not yet implemented).
  • oep_level: The optimized effective potential method is applied in three cases: (i) in case a SIC is applied to a LDA or GGA functional; (ii) in case the exact exchange functional is requested; and (iii) in case the mGGA is to be implemented through the OEP (mGGA_implementation = 2). However, several possible choices are then possible to approximate (or calculate exactly) the OEP.
  • oep_mixing
  • nlcc

Constants

OEP levels

  • XC_OEP_NONE = 0
  • XC_OEP_SLATER = 1
  • XC_OEP_KLI = 2
  • XC_OEP_CEDA = 3
  • XC_OEP_FULL = 4


Subroutines

xc_init

type(xc_type), intent(out) :: xcs
logical,       intent(in)  :: nlcc
integer,       intent(in)  :: spin_channels

This subroutine initializes a xc_type variable, the xcs argument, maiinly by reading in variables from the input file. Two input arguments need, however, to be passed in:

  • nlcc, used to fill in xc_type%nlcc (see type xc_type).
  • spin_channels, which is needed to call xc_functl_init_exchange and xc_functl_init_correlation (see xc_functl). It should be equal to one if the calculations are unpolarized, and equal to two if the calculations are spin-polarized, or based in two-spinors.

This routine is in charge of calling exc_functl_init_exchange and xc_functl_init_correlation.

It also reads some extra variables from the input file:

  • MGGAimplementation: it is used to fill xcs%mGGA_implementation.
  • SICCorrection: used to fill xcs%sic_correction.
  • OEP_level: used to fill xcs%oep_level.
  • OEP_mixing: used to fill xcs%oep_mixing.

xc_write_info

type(xc_type), intent(in) :: xcs
integer,       intent(in) :: iunit

xc_end

type(xc_type), intent(inout) :: xcs

subroutine xc_get_vxc

type(xc_type),        intent(in)    :: xcs
type(mesh_type),      intent(in)    :: m
type(f_der_type),     intent(inout) :: f_der
type(states_type),    intent(in)    :: st
FLOAT,                intent(inout) :: vxc(:,:), ex, ec
FLOAT,                intent(in)    :: ip, qtot
logical, optional,    intent(in)    :: aux

This routine fills the exchange and correlation potential vxc (as well as the exchange and correlation energies, ex and ec. It takes care of the "simple" functionals, i.e. LDA, GGA and mGGA; The SIC corrections to these functionals or the exact exchange OEP is handled in the h_xc_OEP subroutine, which should be called after xc_get_vxc.

The input variables are:

  • xcs: This is the xc_type variable that holds all the information about the exchange and correlation functional. It should have been initialized previously by the xc_init subroutine.
  • m: The mesh where all the system functions live.
  • f_der: This is the f_der_type structure: the structure that knows how to do the derivatives. It is defined inout for technical reasons, but it should not change.
  • st: The states_type structure that holds the density and the Kohn-Sham states.
  • ip: The ionization potential of the system, or some reasonable estimation for it, necessary only in case the van Leeuween & Baerends potential is to be used.
  • qtot: The total electron number of the system, also only necessary in case the van Leeuween & Baerends potential is to be used.
  • aux: This is an optional flag:
    • If it is passed, and it is set to .true., the exchange and correlation functional used will be those held in xcs%sic_aux. This is done in order to calculate the self-interaction corrections.
    • Otherwise, they will be those held in xcs%functl.
  • vxc, ex, ec: the values of these three variables on entry is added to the calculated values.

The output variables are:

  • ex: The exchange energy.
  • ec: The correlation energy.
  • vxc(:, :): The dimension of this array are (m%np, st%d%nspin). On output,

it holds the exchange and correlation potential - added to whatever it held before.


xc_functl module

Introduction

This the is lower level module used by Developers_Manual:Exchange and Correlation#xc module.

Types

xc_functl_type

integer :: family
integer :: id
integer :: spin_channels
integer(POINTER_SIZE) :: conf
integer(POINTER_SIZE) :: info

The integer family may take one of the four following families:

  • XC_FAMILY_LDA = 1 - For LDA functionals.
  • XC_FAMILY_GGA = 2 - For GGA functionals.
  • XC_FAMILY_MGGA = 3 - For MGGA functionals.
  • XC_FAMILY_OEP = 4 - For OEP functionals (i.e. orbital dependent functionals).

This value is set in either the xc_functl_init_exchange and xc_functl_init_correlation, depending on the functional requested, read from the input file, and which in turns sets the id integer identifier.

The integer id is the identifier for the functional. Note that it does not fully identify the exchange and correlation functional - SIC corrections can be added to, for example, one LDA functional. This possibility is handled in the xc module. The values that this variable can take are defined in libxc.

The spin_channels integer may be one, in case the calculation is of spin-unpolarized type (i.e. restricted to paired electrons in closed shells), or two, in case the calculation is spin-polarized, or it is a two-spinors like calculation.

The integer(POINTER_SIZE), conf, and info are the pointers needed to use the subroutines in the libxc module.


Subroutines

xc_functl_init_exchange

type(xc_functl_type), intent(out) :: functl
integer,              intent(in)  :: spin_channels

This subroutine initializes one xc_functl_type structure (argument functl), so that it holds information about one exchange functional. Its only input is spin_channels - which is used to fill in functl%spin_channels, whereas the rest of the needed information is obtained through the input file.

The input file variable XFunctional is read, and used to fill in functl%id. According to its value functl%family is then set by the code. The values given in the input file for XFunctional must then be any of the accepted values for functl%id - in the exchange case. Some mnemonic variables are provided in the SHARE/octopus/variables directory.

Besides filling the xc_functl_type structure functl, the main task of this subroutine is to call either xc_lda_init, xc_gga_init or xc_mgga_init in module libxc.

xc_functl_init_correlation

type(xc_functl_type), intent(out) :: functl
integer,              intent(in)  :: spin_channels

This subroutine initializes one xc_functl_type structure (argument functl), so that it holds information about one correlation functional. Its only input is spin_channels - which is used to fill in functl%spin_channels, whereas the rest of the needed information is obtained through the input file.

The input file variable CFunctional is read, and used to fill in functl%id. According to its value functl%family is then set by the code. The values given in the input file for CFunctional must then be any of the accepted values for functl%id - in the correlation case. Some mnemonic variables are provided in the SHARE/octopus/variables directory.

Besides filling the xc_functl_type structure functl, the main task of this subroutine is to call either xc_lda_init, xc_gga_init, or xc_mgga_init in libxc.

xc_functl_write_info

type(xc_functl_type), intent(in) :: functl
integer,              intent(in) :: iunit

It outputs to the file opened in unit iunit information about the functional initialized in functl.

xc_functl_end

type(xc_functl_type), intent(inout) :: functl

This subroutine does the necessary cleaning of a xc_fucntl_type variable that is not going to be used any more.