eQE 2017 User’s Guide
(eQE v0.2.0)

Table of Content

Introduction

This is the manual for embedded Quantum ESPRESSO 2017 (eQE 2017). 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 are promoted, developed and maintained by the Pavanello Research group (PRG) at the Chemistry Department of Rutgers - Newark, NJ and collaborators.

Contributors to eQE, include:

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:

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

Download

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-X.Y.Z.tar.gz

where X.Y.Z stands for the version number.

The directory eqe-X.Y.Z 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-X.Y.Z
./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.

NOTA BENE: Pseudopotentials and the ntyp keyword has to be the same across all the fragments. i.e. all the fragments need to be aware of the atom types present in the entire system.

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:

The following keywords can differ among the subsystems:

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

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

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

&electrons

use_gaussians | fde_frag_charge

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:

^ Back to top

fde_xc_funct

Namelist: &system

Type: character

Default: ‘SAME’

The xc density functional to be used to evaluate the non-additive kinetic energy and potential.

By default the same functional is used within and across the fragments.

^ Back to top

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.

^ Back to top

fde_print_density

Namelist: &system

Type: logical

Default: .false.

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

^ Back to top

fde_print_density_frag

Namelist: &system

Type: logical

Default: .false.

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

^ Back to top

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.

^ Back to top

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.

^ Back to top

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.

^ Back to top

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.

^ Back to top

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:

^ Back to top

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.

^ Back to top

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.

^ Back to top

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

^ Back to top

What eQE cannot do that QE can

The following simulations/keywords cannot be used in eQE. This is not a comprehensive list.

^ Back to top