This is the manual for embedded Quantum ESPRESSO v2.0 (eQE 2017-2021). eQE is a generalization of Quantum ESPRESSO tailored to perform large-scale subsystem DFT simulations.
This distribution contains the core packages for PWscf (Plane-Wave Self-Consistent Field). These allow for the calculation of electronic structure properties employing Subsystem Density-Functional Theory (DFT), using a Plane Wave (PW) basis set and pseudopotentials.
All trademarks mentioned in this manual belong to their respective owners.
The eQE distribution is promoted, developed and maintained by the Pavanello Research group (PRG) at the Chemistry Department of Rutgers - Newark, NJ and collaborators.
Contributors to eQE, include (Alphabetize by Last Name):
QE contributors for providing the Quantum ESPRESSO codebaseThe homepage of eQE is eqe.rutgers.edu.
Bleeding edge source code can be downloaded from the GIT repository at gitlab.com/Pavanello/eqe (registration required).
eQE developers are always happy to answer questions about the code and to help setting up and running eQE simulations. Please, contact us at:
eQE is free software, released under the GNU General Public License.
Acknowledgement of our work is appreciated when scientific work is carried out using eQE. Please, cite the following reference:
W. Mi, X. Shao, A. Genova, D. Ceresoli, M. Pavanello, "eQE version 2: Subsystem DFT beyond GGA functionals", To be published (2021).
A. Genova, D. Ceresoli, A. Krishtal, O. Andreussi, R. A. DiStasio, M. Pavanello, Int. J. Quantum Chem. 117, e25401 (2017) 10.1002/qua.25401
Presently, eQE is distributed in source form.
A snapshot of the code can be found at eqe.rutgers.edu.
Uncompress and unpack the base distribution using the command:
tar -zxvf eqe-XYZ.tar.gz
where XYZ stands for the version number.
The directory eqe-XYZ will be created.
Alternatively, for the ones who dare access the bleeding edge of the code, it can be found on our GIT repository. Request access to m.pavanello@rutgers.edu, and then clone the repo:
git clone git@gitlab.com:Pavanello/eqe.git eqe
Compilation is identical to the regular Quantum ESPRESSO distribution, refer to their user manual for the fine tuning needed to obtain an efficient executable for your machine.
For the impatient:
cd eqe-XYZ
./configure
make pw
NOTA BENE: this will more often than not produce a slow executable. Make sure that high performance compilers and libraries are properly selected by manually modifying make.sys after running configure.
eQE NEEDS a parallel environment to properly run and communicate information across the subsystems. Make sure all the needed parallel compilers are present in your machine.
eQEYou will need a separate input file for each subsystem (fragment that may be an atom, a molecule, or a surface) composing your system.
The input files need to share the same prefix and be numbered starting from 0.
Each input file is essentially a regular QE input file with only the atoms belonging to that specific fragment.
eQE introduces a series of new keywords, whose complete list can be found at the end of this manual.
In this example we will simulate a water trimer, so we have the following input files:
trimer.scf_0.in
trimer.scf_1.in
trimer.scf_2.in
Several example input files for eQE can be found in the eQE_input_template folder included with the distribution.
Specifically, the water trimer input files are in eQE_input_template/beginner.
Although most of the original QE keywords can be defined independently in each of the subsystem input files, some need to be consistent and explicitly specified for all the subsystems. These keywords are:
prefix (the name of files in the scratch folders)ibrav and CELL_PARAMETERS).ecutwfc and ecutrho (the cutoff for wavefunction and charge density)conv_thr (this sets the SCF convergence)The following keywords can differ among the subsystems:
occupations (whether to use smearing or not)degauss (smearing parameter)nspin (1=spin restricted, 2=open-shell)K_POINT card (subsystems can have different intrinsic periodicity)fde_cell_split(i) (defines the electronic simulation cell of each fragment in the direction of the $i$-th lattice vector).To run an eQE simulation, the following command is needed (please, adapt it based on your needs and available resources):
mpirun -np 6 fdepw.x -ni 3 -in trimer.scf
where -np defines the total number of processors used, -ni defines the number of fragments in your system, and -in defines the prefix of the input and output files (i.e. the filename of the input files up to and excluding _N.in)
The calculation will run on 6 processors, assigning two processors to each of the fragment.
By default the code will try to split the number of processors evenly. But it may be the case where the size of the fragments is heterogenous, and an even split of the available processors would be inefficient.
eQE allows the user to assign an arbitrary number of processors to each fragment by creating an additional file named fragments_procs.in. This file contains as many lines as subsystems, each line containing the number of processors to assign to each subsystem. For example, if fragments_procs.in contains:
2
4
2
it will assign 2 processors to the first and third fragment, and 4 processors to the second. The -np parameter will have to be set accordingly.
In order for eQE to compute the embedding potential of a single fragment explicitly, the keyword
fde_print_embedpot = .true.
must be included in the &system namelist of the fragment input file.
NOTA BENE: Because of parallelization complexity, currently the embedding potential can be printed only for a single fragment.
If the user specifies the keyword for more than one fragment, the code will only print the embedding potential of the fragment with the lowest id.
The embedding potential will be represented in the small electronic cell of the fragment and stored in a .pp file at the end of the calculation.
Afterwards, it is possible to export the embedding potential to several other formats using the standard pp.x program provided with the eQE distribution.
The embedding potential can be interpolated on an arbitrarily defined grid. This can be useful when codes based on atom-centered basis functions are employed. We have noticed that integrals of the kind
$$ v_\mathrm{emb}^{\mu\nu}=\langle \chi_\mu | v_\mathrm{emb} | \chi_\nu \rangle, $$
will not be evaluated correctly when $v_\mathrm{emb}$ is expressed on a regular, evenly-spaced grid. Atom-centered grid generated from a molecular code (such as the Becke grid) provide the correct real-space representation in this case.
To achieve this, the pp.x program provided with the eQE distribution needs to be used. Be sure to include a file containing the arbitrary grid named grid.dat in the same directory as the embedding potential .pp file.
The format of grid.txt should be as follows:
npoints
x1 y1 z1 w1
x2 y2 z2 w2
...
xn yn zn wn
where
npoints is the total number of points in the custom grid;x,y,z are the cartesian coordinates in Bohr of the gridpoints;w is the weight or volume element associated to the grid point.Create a pp.x input file based on this template and name it interpolatepp.in:
&inputpp
/
&plot
nfile = 1
filepp(1) = 'filename_embedpot_0_alpha.pp'
iflag = 3 ! 3D plot
output_format = 6 ! cube file
interpolation = 'bspline_custom' ! interpolate on the points specified in 'grid.dat'.
fileout = 'filename_embedpot_0_alpha.customgrid' ! interpolated potential output file
/
Finally, execute:
/path/to/eQE/bin/pp.x < interpolatepp.in
This will generate filename_embedpot_0_alpha.customgrid in Gaussian cube file format containing the embedding potential splined onto the custom grid.
&system
fde_kin_funct | fde_xc_funct | fde_nspin | fde_print_density | fde_print_density_frag | fde_print_embedpot | fde_split_mix | fde_cell_split | fde_overlap | fde_overlap_c | fde_fractional | fde_nspline | fde_tvpbea | fde_rhomax | fde_mgga_kin | input_dft
&electrons
use_gaussians | fde_frag_charge
Namelist: &system
Type: character
Default: 'LC94'
The kinetic energy density functional to be used to evaluate the non-additive kinetic energy and potential.
Selected GGA functionals are implemented:
- 'TF' : Thomas-Fermi LDA
- 'VW' : Von Weizsacker (unstable)
- 'DGE2'
- 'LLP'
- 'PW86'
- 'LC94' : Default
- 'APBEK'
- 'revAPBEK' : Recommended
Example:
eQE_input_template/beginner/
Selected Nonlocal functionals are implemented:
- 'LMGPA' : Recommended
- 'LMGPG'
- 'LMGP0'
- 'LMGP'
- 'LWT'
NOTE : An additional kernel table file named Kernel_'fde_kin_funct'.TABLE (e.g. Kernel_LMGPA.TABLE for LMGPA functional) is needed when using Nonlocal non-additive kinetic energy functional. All the kernel table files are in PW/Kernel/.
Keywords ONLY related to nonlocal kinetic energy functionals are:
fde_nspline | fde_tvpbea | fde_rhomax
Example:
eQE_input_template/nonlocal_NAKE/
Namelist: &system
Type: character
Default: 'SAME'
The xc density functional to be used to evaluate the non-additive xc energy and potential.
By default the same functional is used within and across the fragments.
Example:
eQE_input_template/beginner/
Namelist: &system
Type: integer
Default: 1
Determines wheter the supersystem density will be spin polarized:
1 : Spin unpolarized
2 : Spin polarized
If the nspin variable of at least one of fragment is equal to 2, then fde_nspin NEEDS to be eqaual to 2 for all the fragments.
This allows to have one or more fragments treated openshell while the others are close shell.
Namelist: &system
Type: logical
Default: .false.
Print the total density to a .pp file at the end of the calculation.
Namelist: &system
Type: logical
Default: .false.
Print the fragment density to a .pp file at the end of the calculation.
Namelist: &system
Type: logical
Default: .false.
Explicitly calculate the embedding potential of the fragment and print it to a .pp file at the end of the calculation.
Make sure this keyword is .true. only for a single fragment, or eQE will arbitrarely print it only for the fragment with the lowest index.
The embedding potential is represented into the smaller electronic cell.
Namelist: &system
Type: logical
Default: .true.
Dynamically adjust the mixing_beta parameter of the fragment along the scf cycle.
Helps speeding up convergence and stability.
Namelist: &system
Type: integer
Default: 1.d0
Flag to define the dimension of each fragment electronic cell.
By default the electronic cell and the supersystem cell are the same, but a huge increase in efficiency can be achieved if the fragment is small enough compared to the total system so that its electronic structure can be confined within a cell which is a fraction of the supersystem cell using this variable.
Each direction can be scaled independently.
Although any value between 0. and 1. can be set, the code will round it to be one of the following allowed fractions:
1/5
1/4
1/3
2/5
1/2
3/5
2/3
3/4
4/5
1/1
And it might be further changed so that the grid points match across all the subsystems.
Example:
eQE_input_template/thiophene-dimer/
Namelist: &system
Type: logical
Default: .false.
Adds a potential proportional to the electron density of the surrounding fragments, $v_\text{overlap}^I(\mathbf{r}) = C \cdot \sum_{J \neq I} \rho_J(\mathbf{r})$.
It can be useful to confine (localize) the electronic structure of subsystems. In the examples, the excess electron in a thiophene radical anion is localized onto the thiophene.
See also fde_overlap_c. Nota Bene: This is a last resort solution. Consider using use_gaussians first.
Example:
eQE_input_template/fde_overlap/
Namelist: &system
Type: real
Default: 0.0e0
The proportionality constant, $C$, to be applied to the density of surrounding fragments for fde_overlap.
Mind of the following specifications:
fde_overlap_c < 10000: Only the core density of surrounding subsystems is used.fde_overlap_c < 20000: The total density of surrounding subsystems is used with $C = ($fde_overlap_c $- 10000)$Example:
eQE_input_template/fde_overlap/
Namelist: &system
Type: logical
Default: .false.
WARNING: fde_fractional is relatively untested. Use with a grain of salt and at your own risk!
fde_fractional Allows the subsystem electron occupations to be determined self-consistently. Subsystems will exchange electrons through the alpha channel (fde_fractional_onlyalpha=.true.), or the beta channel (fde_fractional_onlybeta=.true.), or both (setting both alpha and beta channels to true).
The transfer rate of electrons in/out of a subsystem is set by fde_fractional_mixing ((0 < ) fde_fractional_mixing ( < 1 )) and the total amount of trasferred electrons is capped by fde_fractional_maxEtransfer (typically set to 0.5 electrons).
Transfer goes in the direction of Fermi energy equalization for all subsystems. Set fde_fractional_cycle=N to start electron transfer at the N-th SCF cycle.
Namelist: &system
Type: integer
Default: 80
The number of $\rho_0$ to be used to spline the kernel and potential of nonlocal non-additive kinetic energy functional.
Example:
eQE_input_template/beginner/nonlocal_NAKE/
Namelist: &system
Type: real
Default: 0.01
The parameter to be used in evaluation of the TF+vW functional with PBE-like formalism. It is only used in Nonlocal NAKEs (LMGP(X) and LWT).
The benchmarks of fde_tvpbea=0.01 and 0.1 for LMGP(X) and LWT functionals can be found in the paper: JPCL 11 (1), 272–279 (2020).
Example:
eQE_input_template/nonlocal_NAKE/
Namelist: &system
Type: real
Default: Evaluated from the pseudo-atom density of pseudopotentials
The maximum value of electron density, $\rho_\text{max}$ for the considered system. There is no needed to be exact number (can be little larger than the real $\rho_{max}$). It is only used in Nonlocal NAKEs
DO NOT USE this keyword unless you know what you are doing
Example:
eQE_input_template/nonlocal_NAKE/
Namelist: &system
Type: character
Default: 'TFL'
The kinetic energy density functional to be used to evaluate the kinetic energy density in deorbitalized meta-GGA xc functional.
Selected functionals are implemented:
- 'TFL' : Default
- 'TFLopt'
- 'GEA2L'
- 'PC'
- 'PCopt'
- 'L04' : Recommended
Example:
eQE_input_template/mGGA-L_x/
Namelist: &electrons
Type: logical
Default: .false.
If .true., it replaces the core densities of the surrounding fragments to a gaussian. This is to avoid problems of electrons leaking in the core region of surrounding fragments when hard pseudopotentials (such as hgh NC-PPs) are employed.
Use use_gaussians only if you encounter convergence problems.
Example:
eQE_input_template/use_gaussians/
Namelist: &electrons
Type: real
Default: 0.d0
Change the number of electrons assigned to a fragment. Default = 0.0 neutral fragment.
The sum of the charges across all fragments needs to be 0.0
Namelist: &system
Type: character
Default: 'read from pseudopotential files'
Exchange-correlation functional: eg 'PBE', 'revPBE' etc
See Modules/funct.f90 for allowed values.
Selected deorbitalized meta-GGA xc functionals are implemented:
- 'SCAL' : Deorbitalized meta-GGA SCAN functional (SCAN-L)
- 'r2SL' : Deorbitalized meta-GGA r2SCAN functional (To be released).
Example:
eQE_input_template/mGGA-L_x/
Selected nonlocal xc functionals are implemented:
- 'rVV10'
NOTE : The kernel table (rVV10_kernel_table) is the additional inputfile when using rVV10 xc functional and it is in PW/Kernel/.
Example:
eQE_input_template/nonlocal_xc/
eQE cannot do that QE canThe following simulations/keywords cannot be used in eQE. This is not a comprehensive list.