# eQE 2021 User's Guide(eQE v2.0)

## Introduction

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.

### People

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):

• Oliviero Andreussi
• Davide Ceresoli
• Robert DiStasio
• Alessandro Genova
• Alisa Krishtal
• Wenhui Mi
• Michele Pavanello (PI)
• Xuecheng Shao
• All the QE contributors for providing the Quantum ESPRESSO codebase

### Contact

The 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:

### Term of Use

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

## Setup

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

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.

## Running eQE

You 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)
• The supersystem simulation cell (i.e., 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)
• the 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.

## Generating and Exporting the embedding potential

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.

### Atom centered grid

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.

## Keyword List

&system

&electrons

### fde_kin_funct

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:

Example:

 eQE_input_template/nonlocal_NAKE/


### fde_xc_funct

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/


### fde_nspin

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.

### fde_print_density

Namelist: &system

Type: logical

Default: .false.

Print the total density to a .pp file at the end of the calculation.

### fde_print_density_frag

Namelist: &system

Type: logical

Default: .false.

Print the fragment density to a .pp file at the end of the calculation.

### fde_print_embedpot

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.

### fde_split_mix

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.

### fde_cell_split(i), i=1,3

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/


### fde_overlap

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/


### fde_overlap_c

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:

• 0.000 < fde_overlap_c < 10000: Only the core density of surrounding subsystems is used.
• 10000 < fde_overlap_c < 20000: The total density of surrounding subsystems is used with $C = ($fde_overlap_c $- 10000)$

Example:

eQE_input_template/fde_overlap/


### fde_fractional

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.

### fde_nspline

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/


### fde_tvpbea

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/


### fde_rhomax

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/


### fde_mgga_kin

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/


### use_gaussians

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/


### fde_frag_charge

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

### input_dft

Namelist: &system

Type: character

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/


## What eQE cannot do that QE can
The following simulations/keywords cannot be used in eQE. This is not a comprehensive list.