README
BerkeleyGW is a GW / Bethe-Salpeter equation computer package.
Documentation
-------------
The user documentation is gathered in the directory
~BerkeleyGW/documentation/users/
Compilation
-----------
We have tested the code extensively with various configurations, and support the following compilers and libraries:
* Operating systems: Linux, AIX, MacOS
* Fortran compilers (required): pgf90, ifort, gfortran, g95, openf90, sunf90, pathf90, crayftn, af90 (Absoft), nagfor, xlf90 (experimental)
* C compilers (required): pgcc, icc, gcc, opencc, pathcc, craycc, clang
* C++ compilers (required): pgCC, icpc, g++, openCC, pathCC, crayCC, clang++
* MPI implementation (optional): OpenMPI, MPICH1, MPICH2, MVAPICH2, Intel MPI
* LAPACK/BLAS implementation (required): NetLib, ATLAS, Intel MKL, ACML, Cray LibSci
* ScaLAPACK/BLACS implementation (required if MPI is used): NetLib, Cray LibSci, Intel MKL, AMD
* FFTW (required): versions 3.3.x
1. Architecture-specific Makefile-include files appropriate for various supercomputers as well as
for using standard Ubuntu or Macports packages are provided in the config directory. Copy or
link one to the top directory. Example:
cp config/stampede.tacc.utexas.edu_threaded_hdf5.mk arch.mk
2. Edit it to fit your needs. Refer to config/README for details.
3. Copy flavor_real.mk or flavor_cplx.mk to flavor.mk to set flavor.
Complex may always be used. Real may be used for systems that
have both inversion (about the origin) and time-reversal symmetry, and will be
faster and use less memory.
4. Stay in the root directory and run the following commands
to compile the various codes:
MAIN:
make epsilon
make sigma
make bse
MISC:
make plotxct
make nonlinearoptics
make meanfield
make visual
EVERYTHING:
make all All codes/packages (for selected flavor)
make -j all parallel build (for selected flavor)
make all-flavors everything, for both flavors
make -j all-flavors parallel build of everything, for both flavors
make install INSTDIR= install binaries, library, examples, testsuite into specified prefix
These commands will generate executables with extension .x in
the source directory and symbolic links with the same name in
the bin directory.
5. Test your build. See testsuite/README for more info.
License
-------
BerkeleyGW is distributed under the Berkeley Software Distribution (BSD) license.
For license information see "license.txt" as well as "Copyright.txt"
Contributors
------------
See the file CONTRIBUTORS for a complete list of authors.
license.txt
Unless otherwise stated, all files distributed in this package
are licensed under the following terms.
BerkeleyGW, Copyright (c) 2011, The Regents of the University of
California, through Lawrence Berkeley National Laboratory (subject to
receipt of any required approvals from the U.S. Dept. of Energy).
All rights reserved.
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.
(3) Neither the name of the University of California, Lawrence
Berkeley National Laboratory, U.S. Dept. of Energy nor the names of
its contributors may be used to endorse or promote products derived
from this software without specific prior written permission.
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.
You are under no obligation whatsoever to provide any bug fixes,
patches, or upgrades to the features, functionality or performance of
the source code ("Enhancements") to anyone; however, if you choose to
make your Enhancements available either publicly, or directly to
Lawrence Berkeley National Laboratory, without imposing a separate
written license agreement for such Enhancements, then you hereby grant
the following license: a non-exclusive, royalty-free perpetual
license to install, use, modify, prepare derivative works, incorporate
into other computer software, distribute, and sublicense such
enhancements or derivative works thereof, in binary and source code
form.
CONTRIBUTORS
Chronological list of contributors
----------------------------------
BerkeleyGW - The Berkeley GW (And More) Package
http://www.berkeleygw.org
Version 1.2 (Aug, 2016)
F. H. da Jornada, J. Deslippe, D. Vigil-Fowler, J. I. Mustafa, T. Rangel,
F. Bruneval, F. Liu, D. Y. Qiu, D. A. Strubbe, G. Samsonidze, J. Lischner.
Version 1.1 (June, 2014) -
Version 1.0 (Aug, 2011)
J. Deslippe, G. Samsonidze, D. A. Strubbe, M. Jain
Version 0.5 (July, 2008)
J. Deslippe, G. Samsonidze, L. Yang, F. Ribeiro
Version 0.2 M. L. Tiago (2001) Original BSE Code, PlotXct
S. Ismail-Beigi (2002) FFT, Documentation, General Improvements
C. Spataru (2005) Cylindrical Coulomb Truncation, Transform (obsolete)
Version 0.1 X. Blase (1998) Implemented F90, Preprocessing, Dynamical Memory Allocation
G. M. Rignanese " "
E. Chang " "
Version 0.0 M. Hybertsen (1985) Original GW Code
Report current bugs or problems and ask questions at the BerkeleyGW Forum,
at http://www.berkeleygw.org.
Alphabetical list of contributors
---------------------------------
Gabriel K. Antonius (GKA)
Brad A. Barker (BAB)
Xavier Blase (XAV)
Andrew Canning (AC)
Andrea Cepellotti (ACE)
Eric K. Chang (EKC)
Sangkook Choi (SKC)
Mauro Del Ben (MDB)
Jack R. Deslippe (JRD)
Peter W. Doak (PWD)
Mark S. Hybertsen (MSH)
Sohrab Ismail-Beigi (SIB)
Manish Jain (MJ)
Felipe H. da Jornada (FHJ)
Je-Luen Li (JLL)
Zhenglu Li (ZL)
Steven G. Louie (SGL)
Andrei S. Malashevich (ASM)
Brad D. Malone (BDM)
Jamal I. Mustafa (JIM)
Jeffrey B. Neaton (JBN)
Cheol-Hwan Park (CHP)
David G. Prendergast (DGP)
Diana Y. Qiu (DYQ)
Tonatiuh Rangel (TR)
Filipe J. Ribeiro (FJR)
Gian-Marco Rignanese (GMR)
Georgy Samsonidze (GSM)
Sahar Sharifzadeh (SS)
Catalin D. Spataru (CDS)
David A. Strubbe (DAS)
Murilo L. Tiago (MLT)
Derek Vigil-Fowler (DVF)
Li Yang (LY)
Oleg V. Yazyev (OVY)
Peihong Zhang (PZ)
config/README
# Information about how to set the various options here.
# Ideally you can use a file already created for your platform in this directory.
# Otherwise, you can work from the one most similar that is here.
# Select the Fortran compiler you are using.
# if you have a different one than these, modifications in Common/compiler.h
# and Common/common-rules.mk will be necessary.
COMPFLAG = -D{INTEL, PGI, GNU, PATH, XLF, G95, ABSOFT, NAG, OPEN64, SUN, CRAY}
# Use -DMPI to compile Fortran in parallel with MPI. Otherwise is serial.
# Add -DOMP to compile with OpenMP support. Also add appropriate compiler-dependent flag to F90free:
# ifort, sunf90, absoft, pathscale, Open64: -openmp. PGI: -mp=nonuma. gfortran: -fopenmp. XLF: -qsmp=omp.
# crayftn: on by default (to turn off use -h noomp). g95 and NAG do not support OpenMP.
PARAFLAG = -DMPI
# -DUSESCALAPACK enables usage of ScaLAPACK (required in parallel for BSE).
# -DUSEESSL uses ESSL instead of LAPACK in some parts of the code.
# -DUNPACKED uses unpacked rather than packed representation of the Hamiltonian
# in EPM. Packed LAPACK operations give bad results eventually in Si-EPM kernel 'max x'
# test for ACML, Cray LibSci, and MKL sometimes.
# -DUSEFFTW3 uses fftw3 instead of fftw2, which is recommended for better performance, and enables threading.
# -DHDF5 enables usage of HDF5 for writing epsmat and bsemat files. The produced files will be
# eps0mat.h5, epsmat.h5 and bsemat.h5 and are used in place of eps0mat, epsmat, bsedmat, bsexmat
# (the latter two are combined in one .h5 file).
# Using -DHDF5 gives you substantially better IO performance in many cases by taking advantage
# of HDF5's parallel IO options and other options. However, you must have the HDF5 libraries
# installed on your system and define HDF5LIB and HDF5INCLUDE below.
MATHFLAG = -DUSESCALAPACK -DUSEESSL -DUNPACKED -DHDF5
# For Fortran and C++. -DDEBUG enables extra checking. -DVERBOSE is an internal
# flag, and is equivalent to running all codes with the maximum verbosity level.
# Don't use the -DVERBOSE option, unless a developer told you to. The -DDEBUG
# option makes extra memory checks, and slows down the code by up to ~20%.
# Only use these flags if you need to develop or debug BerkeleyGW.
# The output will be much more verbose, and the code will slow down by ~20%.
DEBUGFLAG = -DDEBUG -DVERBOSE
# Same, but for C and C++.
C_DEBUGFLAG = -DDEBUG -DVERBOSE
# Command for the preprocessor. -C (and not -ansi) should generally be used.
# add -P if the Fortran compiler will not accept indication of line numbers.
# Use gcc's (often in /lib/cpp) or a C compiler (even mpicc) with "-E". Some need "-x c" as well.
FCPP = cpp -C
# Fortran compiler and its flags for F90 and f90 files (free source form)
# see above at PARAFLAG regarding flags for OpenMP.
# With -DOMP and openmp flags here, you will get threaded BerkeleyGW.
# Without -DOMP, but with openmp flags here, is appropriate for just using threaded libraries.
# Sometimes, flags such as -fno-second-underscore or -assume 2underscores may be necessary
# to make linking succeed against C libraries such as FFTW, depending on what compiler built them.
F90free = {mpif90, mpiifort, ftn, ifort, pgf90, gfortran, ...}
# Fortran compiler and any flag(s) required for linking
LINK = {mpif90, mpiifort, ftn, ifort, pgf90, gfortran, ...}
# Fortran optimization flags. The levels below will generally work.
FOPTS = {-fast, -O3}
# Fortran optimization flags for epsilon_main and sigma_main which can have
# trouble in high optimization due to their long length. If below does not
# work, try -O2.
FNOOPTS = $(FOPTS)
# Fortran compiler flag to specify location where module should be created.
# different for each compiler, refer to examples.
MOD_OPT =
# Fortran compiler flag to specify where to look for modules.
INCFLAG = -I
# Use this to compile C++ in parallel with MPI. Leave blank for serial.
# MPICH, MVAPICH, Intel MPI require also -DMPICH_IGNORE_CXX_SEEK, or an error may occur such as:
# "SEEK_SET is #defined but must not be for the C++ binding of MPI. Include mpi.h before stdio.h"
C_PARAFLAG = -DPARA
# C++ compiling command and any needed flags
CC_COMP = {mpiCC, mpicxx, mpiicpc, CC, icpc, pgCC, g++, ...}
# C compiling command and any needed flags
C_COMP = {mpicc, mpiicc, cc, icc, pgcc, gcc, ...}
# C/C++ link command and any needed flags
C_LINK = {mpiCC, mpicxx, mpiicpc, CC, icpc, pgCC, g++, ...}
# C/C++ optimization flags
# Note: for Intel compilers, it is equivalent to use icc or icpc on C++ files.
C_OPTS = -fast
# command to remove, for make clean
REMOVE = /bin/rm -f
# command for making archives (.a). Default is /usr/bin/ar.
# Usually that is fine and AR does not need to be specified, but
# to do interprocedural optimizations (IPO) with ifort, you need xiar instead.
#AR = /usr/bin/env xiar
# Math Libraries
# path for FFTW library, used in lines below
FFTWPATH =
# link line for FFTW2 library. Sometimes needs to be -ldfftw
FFTWLIB = -L$(FFTWPATH)/lib -lfftw
# link line for FFTW3 library, if -DUSEFFTW3 is used. Including fftw_omp allows threaded run.
# Note: To use FFTW3 from MKL, do not link the fftw3xf interfaces.
FFTWLIB = -L$(FFTWPATH)/lib {-lfftw3_omp} -lfftw3
# FFTW2 requires include file fftw_f77.i;
# Sometimes supercomputer installations will not have it.
# If not, find it online and copy it: e.g. http://www.fifi.org/doc/fftw-dev/fortran/fftw_f77.i
# FFTW3 requires include file fftw3.f03 instead.
FFTWINCLUDE = $(FFTWPATH)/include
# Different styles will apply depending on the package used.
# Must provide BLAS as well as LAPACK: some packages will do this in one library file,
# others will not. See examples in this directory for how to link with MKL, ACML,
# ATLAS, Ubuntu packages, etc. For MKL, if you will use ScaLAPACK, it is most
# convenient to include BLACS here too. For further info on linking with MKL, see
# the link-line advisor at http://software.intel.com/sites/products/mkl/
LAPACKLIB =
# Specify below if you have -DUSESCALAPACK in MATHFLAG.
# BLACS must be provided here too, if it is not provided in LAPACKLIB above. See
# examples in this directory for different packages, as with LAPACKLIB. Note that
# you may have problems if ScaLAPACK was not built with the same LAPACK used above.
SCALAPACKLIB =
# Specify below if you have -DHDF5 in MATHFLAG.
# If compiling in parallel, you must have HDF5 compiled with parallel support or linking will fail.
# Path as below should generally work. Sometimes -lsz too, or static linkage, might be required.
# Note that "-lz" is not from HDF5, but its dependency zlib.
# libdl may be required on your system even when linking static HDF5 due to plugin support in 1.8.11 and higher
HDF5PATH =
HDF5INCLUDE = $(HDF5PATH)/include
HDF5LIB = -L$(HDF5PATH)/lib -lhdf5hl_fortran -lhdf5_hl -lhdf5_fortran -lhdf5 -lz
# Flags for performance profiling with an external tool such as IPM on NERSC
PERFORMANCE =
# Command to submit testsuite job script from testsuite directory.
# qsub is for PBS. If no scheduler, put make check-parallel here.
# In serial, delete this line.
TESTSCRIPT = qsub {architecture}.scr
testsuite/README
BerkeleyGW testsuite
David Strubbe 2009-2011
== Running tests ==
* To run the testsuite in serial, type "make check" in this directory or the main directory. "make check-save" will do the same, but retain the working directories for debugging.
* To run in parallel without a scheduler, you can just use "make check-parallel" if you do not have a scheduler (e.g. PBS). Set environment variable SAVETESTDIRS=yes to save working directories. The tests use 4 cores, so be sure that at least that many are available, or use BGW_TEST_MPI_NPROCS (see below).
* To run in parallel with a scheduler, type "make check-jobscript" or "make check-jobscript-save", which will execute the job script for the machine you are using, as specified in arch.mk by the line TESTSCRIPT. See example job scripts for various machines in this directory called *.scr. The tests use 4 cores, so be sure to request at least that many in the job script, or use BGW_TEST_MPI_NPROCS (see below).
* Environment variables:
- TEMPDIRPATH: sets the scratch directory where temporary working directories will be created. Default is /tmp, but on some machines you may not have permission to write there.
- MPIEXEC: sets the command for parallel runs. Default is `which mpiexec`. Note that mpiexec and mpirun are generally equivalent (except for Intel MPI, in which case mpirun is recommended). Set this if you are using a different command such as 'ibrun' (SGE parallel environment), 'runjob' (BlueGene), or 'aprun' (Cray), if you need to use a different mpiexec than the one in your path, or if some options need to be appended to the command. Depending on the value of this variable, three styles of command line are used: ibrun, runjob, and mpirun/aprun.
- BGW_TEST_MPI_NPROCS: set to overrule the number of processors listed in the test files. Useful for testing correctness of parallelization, if you don't have 4 cores, or to run the testsuite faster with more cores.
[- BGW_TEST_NPROCS: deprecated, same as BGW_TEST_MPI_NPROCS, provided for compatibility with versions 1.0.x.]
- MACHINELIST: if set, will be added to command line for MPI runs. This is needed in some MPI implementations.
- EXEC: if set, will be added before name of executable. Used to run code through valgrind.
* To run just one test, in its directory, run "../run_regression_test.pl [-s] [-p] -D ../../bin -f [testname].test". Include the -s flag to run in serial; otherwise it will be in parallel. Include the -p flag to preserve the working directory.
Contents:
(1) run_testsuite.sh -- this script runs tests from filenames ending in *.test in this directory.
(2) run_regression_test.pl -- called from run_testsuite.sh for each individual test.
(3) *.scr -- job scripts for running the testsuite on various parallel machines.
(4) interactive*.sh -- scripts to run in parallel, in interactive mode. You have to follow the instructions in the script, not just run it.
(5) queue_monitor.pl -- a Perl script for parallel tests with a SLURM or PBS scheduler, which submits a job and monitors the queue to see what happens. Used by the BuildBot.
(6) test directories.
(7) fix_testsuite.py -- (for developers) can be used to create or update match reference values in test files.
(8) no_hires.sh -- Some clusters will not have the Perl package Time::HiRes installed which is needed for timing in run_regression_test.pl. You can just deactivate the usage with this script.
(9) buildbot_query.pl -- (for developers) can be used to find the range of values obtained on the buildslaves for a particular match, to set values in the test files.
== Writing tests ==
The test files consist of lines beginning with one of a set of tags, parsed by the Perl script. Comment lines beginning with '#' will be ignored.
Test : title
Write a title to output to identify the test. Should be the first tag in the file.
Banner : text
Write a heading in a box to identify a specific part of a test. Helpful when input files are generated by sed and do not have a distinct name.
Enabled : Yes/No
If Yes, will be run; if No, will not be run. Use to turn off a test without deleting it from the repository. Should be the second tag in the file.
TestGroups : group-name [group-name2 [...]]
The run_testsuite.sh script can be run with argument "-g" and a list of groups. Then tests will only be run if there is a match between the argument list and the list in TestGroups. Examples of groups that could be used: parallel, serial, long. [This tag is actually read by run_testsuite.sh rather than run_regression_test.pl.]
Executable : program.x
Name of executable to be run (path is bin directory). Persists for multiple runs, until next Executable tag.
Processors : integer
Number of processors to use. Ignored if mpiexec is not available. May not exceed the number in the reservation in the job scripts.
Set to special value "serial" to run without mpiexec.
Command : shell-command
Specify a shell command, which will be executed in the working directory. Useful for renaming log files that would be overwritten by a subsequent run, or preprocessing input files by sed or other utilities (after putting in working directory with Copy).
Copy : file.in [file_newname.in]
Copy a file from test directory to run directory. If new name is not supplied, original name will be used. Useful if you want to sed a file before it is run.
Unpack : data.tar.gz
The file data.tar.gz in the test directory will have "tar xzf" run on it, with resulting files going to the working directory.
Output : file.out
Output will be piped into the file named here, in the working directory.
Arguments : arg1 arg2
The current Executable will be executed (in serial) with the text given here as command-line argument(s). No files will be copied to working directory. Use redirection with ">" to capture the output if necessary.
Input : file.in [file_newname.in/PIPE/CMDLINE/NONE/NOCOPY]
The file named here will be copied from the test directory to the working directory, for use as input (unless NOCOPY is specified). If it is followed by "PIPE", the file will be piped into the executable. If it is followed by "CMDLINE", the file will be given as a command-line argument to the executable. If it is followed by "NONE", no file will be copied (useful if an input file was already generated by sed in the working directory). If it is followed by another name, the file's name in the working directory will be the new name. This tag causes actual execution of the run that has been set up by previous tags.
Precision : 1e-5
A floating point number, the tolerance for testing whether a match has passed or failed. Persists until next Precision tag. Default is 1e-4.
match ; name ; COMMAND(..); reference-value
Extracts a calculated number from a run and tests it against the reference value. The name is an identifier printed to output. The number is extracted as the standard output from the listed COMMAND, which is one of this set:
. GREP(filename, 'search-text', field, offset)
Finds the first line in file containing 'search-text' (which MAY NOT contain a comma), and returns the specified field of that line. "Field" is meant in the sense used by 'awk', i.e. the line is parsed into white-space separated groups, indexed starting with 1. The optional 'offset' directs the use of the Mth line after the line containing 'search-text'. No offset is equivalent to offset = 0. This is the most robust of the commands and should be used when possible in preference to the others.
. SIZE(filename)
Returns the size of the specified file via 'ls -lt'. Useful for binary files whose contents cannot easily be checked.
. LINE(filename, line, field)
Returns the specified field of the specified line number from the file. Use GREP instead if possible.
. SHELL(shell-command)
The result is the standard output of the listed command. Deprecated; use GREP or LINE unless absolutely necessary.
STOP TEST
For debugging purposes, to halt test after the part you are studying has run.
library/README
================================================================================
BerkeleyGW library
================================================================================
Version 2.0 (May, 2018)
To be announced.
Version 1.2 (Aug, 2016)
F. H. da Jornada, J. Deslippe, D. Vigil-Fowler, J. I. Mustafa, T. Rangel,
F. Bruneval, F. Liu, D. Y. Qiu, D. A. Strubbe, G. Samsonidze, J. Lischner.
Version 1.1 (June, 2014)
Version 1.0 (July, 2011) J. Deslippe, M. Jain, D. A. Strubbe, G. Samsonidze
Version 0.5 J. Deslippe, D. Prendergast, L. Yang, F. Ribeiro, G. Samsonidze (2008)
Version 0.2 M. L. Tiago, C. Spataru, S. Ismail-Beigi (2004)
--------------------------------------------------------------------------------
To build other codes with BerkeleyGW output support, type 'make library'
to create libBGW_wfn.a and wfn_rho_vxc_io_m.mod (and dependent modules),
and then compile with -I library/ and link library/libBGW_wfn.a with
the other code.
An m4 macro for configure scripts is provided in this directory, for
use in linking to this library. Codes linking the library should 'use'
the module 'wfn_rho_vxc_io_m'.
To generate real wavefunctions, a Gram-Schmidt process should be used.
The appropriate parallelization scheme etc. will be dependent on the code,
and cannot be easily handled in a general manner here, but examples can
be found in MeanField/SIESTA/real.f90 and MeanField/ESPRESSO/pw2bgw.f90
(routine real_wfng).
examples/README
================================================================================
BerkeleyGW Examples
================================================================================
Version 2.0 (May, 2018)
To be announced.
Version 1.2 (Aug, 2016)
F. H. da Jornada, J. Deslippe, D. Vigil-Fowler, J. I. Mustafa, T. Rangel,
F. Bruneval, F. Liu, D. Y. Qiu, D. A. Strubbe, G. Samsonidze, J. Lischner.
--------------------------------------------------------------------------------
This folder contains a set of example calculations for BerkeleyGW 1.2.
The mean-field portion of the examples may be done with the Empirical
Pseudopotential Method (EPM), or ab intio DFT, using the Quantum ESPRESSO,
PARATEC, or ABINIT codes. Other mean-field codes, such as Octopus and PARSEC,
are also supported, but we don't have examples for them at this point.
The examples contained here are organized according to the mean-field starting
point:
1. Example under the "DFT" folder, use ab initio DFT as the starting mean-field
picture for our GW and Bethe-Salpeter equation (BSE) calculations. You must
have either PARATEC, Quantum ESPRESSO, or ABINIT for run these examples.
Required pseudopotentials are stored in DFT/pseudos.
2. Examples under the "EPM" folder use the Empirical Pseudopotential Method
(EPM), and you won't need any external mean-field code to run these examples.
Calculations in these folders are much shorter to run, but are probably of
less
Each of these directories contain a number of subdirectories, each of them
containing a different example and a README file with the instructions how to
run each examples and suggestion on the number of processors to use.
Before you run anything, note that YOU MUST MODIFY ALL SCRIPTS in this folder
to set the appropriate path to BerkeleyGW (eg: $HOME/GW), your parallel job
launching command (eg: mpirun), and parallel submission flags (eg: "#SLURM ...").
Tutorial
--------
The idea behind these examples is to provide a working set of input files
and reference output files for several calculations that span a range of
relevant materials. However, for a more pedagogical introduction to BerkeleyGW,
we suggest you first try to run our tutorials that are designed for our yearly
BerkeleyGW workshops, available at:
https://sites.google.com/site/berkeleygw2015/home
Note for ABINIT
---------------
Our ABINIT wrapper is still experimental, and not all examples have been ported
to use ABINIT.
Note for Quantum ESPRESSO
-------------------------
Quantum ESPRESSO examples are compatible with
Quantum ESPRESSO 5.0 and later versions. If you want to run them with Quantum
ESPRESSO 4.3.2 or earlier version, you should modify the input files for pw.x, and
change "calculation = 'bands'" to "calculation = 'nscf'" and "CELL_PARAMETERS" to
"CELL_PARAMETERS cubic".
Basic examples
--------------
- silicon: a bulk semiconductor. You should start here!
- Includes PREBUILT tarball of DFT inputs from PARATEC.
- Includes ref directories containing sample output from ESPRESSO and BerkeleyGW steps.
- Available for EPM as well as DFT.
- Shows how to use Wannier90 and sig2wan.x to obtain a GW bandstructure by
interpolation (optional step).
- Shows how to use inteqp to obtain a GW bandstructure by interpolation.
- GaAs: similar to silicon example. Runs slightly faster.
- sodium: a bulk metal
- swcnt_5-5: (5,5) single-walled carbon nanotube, a metallic 1D system
- swcnt_8-0: (8,0) single-walled carbon nanotube, a semiconducting 1D system
- Has runs of plotxct with visualization by volume.py and surface.x.
- CO: a small molecule
- benzene: a slightly larger molecule
- Includes run of gsphere.py and SIESTA.
Advanced examples
-----------------
These examples demonstrate how to use advanced features of the code, and they
are not as tidy as the other examples. You are expected to modify submission
- Si2_sapo: another silicon example
- Shows how to perform iterative Davidson diagonalization in SAPO,
- requires pw2bgw with write_vscg capability as in espresso-5.0.2.
- Zn2O2: a bulk semiconductor
- Includes ref directories containing sample output from ESPRESSO and BerkeleyGW steps.
- Shows how to use inteqp to obtain a GW bandstructure by interpolation.
- Shows how to perform iterative Davidson diagonalization in SAPO,
requires pw2bgw with write_vscg capability as in espresso-5.0.2.
- Shows how to use valence only charge density in the Generalized Plasmon Pole model,
requires pw2bgw with calc_rhog capability as in espresso-5.0.2.
Other examples
---------------
- Make sure you visit the tutorials presented during the BerkeleyGW workshops:
https://sites.google.com/site/berkeleygw2015/home
- The testsuite runs may also be consulted, although they are not realistic calculations.
- There are also examples in the Visual directory for the scripts there.
MeanField/README
================================================================================
BerkeleyGW: MeanField wrappers and utilities
================================================================================
Version 2.0 (May, 2018)
To be announced.
Version 1.2 (Aug, 2016)
F. H. da Jornada, J. Deslippe, D. Vigil-Fowler, J. I. Mustafa, T. Rangel,
F. Bruneval, F. Liu, D. Y. Qiu, D. A. Strubbe, G. Samsonidze, J. Lischner.
--------------------------------------------------------------------------------
Description:
BerkeleyGW uses a mean-field starting point, typically from DFT.
Currently, BerkeleyGW supports two plane-wave DFT codes,
PARATEC and Quantum ESPRESSO; one localized-orbital DFT code, SIESTA;
and two real-space codes, Octopus and PARSEC.
You can find details on how to use BerkeleyGW with these codes in
their respective directories.
For testing purposes and for crude calculations of large systems,
BerkeleyGW can be executed on top of the empirical pseudopotential
plane-wave code. See MeanField/EPM for details.
There is a tool for generating large numbers of unoccupied orbitals
(approximate from plane waves or exact by iterative diagonalization).
It is located in MeanField/SAPO.
You can find a simple code for computing the Coulomb integral within
an image-charge model in MeanField/ICM.
--------------------------------------------------------------------------------
Tricks and hints:
1. Vxc0
Vxc0 is the G=0 component of the exchange-correlation potential Vxc.
Vxc0 is added to the eigenvalues in the wavefunction files produced
by PARATEC and ESPRESSO. Vxc0 is also included in the VXC and vxc.dat
files produced by PARATEC and ESPRESSO (the VXC file contains Vxc(G)
and the vxc.dat file contains matrix elements of Vxc). The two Vxc0
terms cancel out when calculating the quasiparticle corrections
in the Sigma code.
2. Vacuum level
To correct the DFT eigenvalues for the vacuum level take the average
of the electrostatic potential on the faces of the unit cell in the
non-periodic directions and subtract it from the DFT eigenvalues.
The electrostatic potential is defined as Velec = Vbare + Vhartree,
while the total potential is Vtot = Vbare + Vhartree + Vxc, hence
Vtot contains Vxc0 and Velec does not. The average of Velec is
fed into the Sigma code using keywords avgpot and avgpot_outer.
The potentials can be generated with PARATEC and ESPRESSO.
In PARATEC, use elecplot for Velec or potplot for Vtot, then
convert from a3dr to cube using the Visual/volume.py script.
In ESPRESSO, use iflag=3, output_format=6, and plot_num=11
for Velec or plot_num=1 for Vtot. The averaging is done with
the Visual/average.py script.
3. Unit cell size
If you truncate the Coulomb interaction, make sure that the size
of the unit cell in non-periodic directions is at least two times
larger than the size of the charge distribution. This is needed
to avoid spurious interactions between periodic replicas but at
the same time not to alter interactions within the same unit cell.
Run Visual/surface.x to plot an isosurface that contains 99% of the
charge density (see Visual/README for instructions on how to do this).
The code will print the size of the box that contains the isosurface
to stdout. Multiply the box dimensions in non-periodic directions
by two to get the minimum size of the unit cell.
4. Inversion symmetry
When using the real flavor of the code, make sure the inversion
symmetry has no associated fractional translation (if it does,
shift the coordinate origin). Otherwise WFN, VXC, RHO (and VSC
in SAPO) have non-vanishing imaginary parts which are simply
dropped in the real flavor of the code. This won't do any
good to your calculation...
MeanField/ESPRESSO/README
Quantum ESPRESSO is available for download at http://www.quantum-espresso.org/
The interface between Quantum ESPRESSO and BerkeleyGW consists of three programs,
kgrid.x, pw2bgw.x and bgw2pw.x. kgrid.x is compiled with BerkeleyGW package and
pw2bgw.x and bgw2pw.x are compiled with Quantum ESPRESSO.
Files for versions 4.3.2, 5.0.x, and 5.1.x are supplied here.
Starting with version 5.0, compatible files of pw2bgw.f90 and bgw2pw.f90 are
distributed with Quantum ESPRESSO.
If you are using espresso-5.1, apply a patch following the
instructions in BerkeleyGW/MeanField/ESPRESSO/version-5.1/README_patch.
Alternatively, you can use BerkeleyGW/MeanField/ESPRESSO/version-5.1/pw2bgw.f90
(rather than espresso-5.1/PP/src/pw2bgw.f90), which includes a bugfix to
the problem of an immediate segmentation fault or error
saying 'MPI_Comm_rank: Invalid communicator'. To use:
cp BerkeleyGW/MeanField/ESPRESSO/version-5.1/pw2bgw.f90 espresso-5.1/PP/src/
Then 'make pp' in espresso. This seems to happen for MPICH and MVAPICH (and
probably the related IntelMPI) but not OpenMPI, but the updated version should work
in all cases. This is fixed in espresso-5.1.1 and later versions.
The development versions of pw2bgw.f90 and bgw2pw.f90 are available from
Quantum ESPRESSO trunk. Quantum ESPRESSO allows anonymous checkouts of its
source code. Use the command below and use 'anonymous' as the username and
a blank password to checkout the code:
svn checkout http://qeforge.qe-forge.org/svn/q-e/trunk/espresso
You can find more details about Quantum ESPRESSO svn on this website:
http://www.qe-forge.org/gf/project/q-e/scmsvn/
--------------------------------------------------------------------------------
kgrid.x
pw.x can automatically generate a uniform grid of k-points, either unshifted
or shifted by half a grid step (Monkhorst-Pack grid), and reduce it to the
irreducible wedge of the Brillouin Zone with the symmetries of the point group
of the Bravais lattice and optionally with time-reversal symmetry. The same
functionality (and more) is provided by kgrid.x in this directory. Additionally,
kgrid.x can use the symmetries of the space group of the crystal instead of the
symmetries of the point group of Bravais lattice, which is needed for BerkeleyGW.
kgrid.x is not limited to the unshifted/half-step shifted Monkhorst-Pack grids.
It can generate an asymmetrically shifted fine grid used to improve the
convergence in absorption calculations. Also, kgrid.x can generate a grid
of k-points with a small q-shift used in Epsilon calculation to avoid the
divergence of the Coulomb interaction. The list of k-points generated by
kgrid.x must be manually added to the input file of pw.x. Note that time-reversal
symmetry should NOT be used for BerkeleyGW (noinv = .false. if generating the
k-grid in pw.x), unless the utility wfn_time_reversal.x is run afterward.
The format of the input file for kgrid.x (along with an example for Si) is found
in kgrid.inp. See also more information in the header of kgrid.f90. You can find
the input files for kgrid.x in examples/DFT in the ESPRESSO subdirectories of
each example.
--------------------------------------------------------------------------------
data-file2kgrid.py
Parses the atomic positions and FFT grid from a Quantum Espresso data-file.xml
file and creates the input file kgrid.inp for the kgrid.x utility.
All options to kgrid.x -- such as number of k-points, k-shift, and k-grid --
are read as optional command-line arguments to data-file2kgrid.py. Type
data-file2kgrid.py --help for a list of possible options.
--------------------------------------------------------------------------------
pw2bgw.x
Converts the output files produced by pw.x to the input files for BerkeleyGW.
You cannot use USPP, PAW, or spinors in a pw.x run for BerkeleyGW.
You cannot use "K_POINTS gamma" in a pw.x run for BerkeleyGW.
Use "K_POINTS { tpiba | automatic | crystal }" even for the
Gamma-point calculation.
The format of the input file for pw2bgw.x is described
in files MeanField/ESPRESSO/version-4.3.2/pw2bgw.inp,
MeanField/ESPRESSO/version-5.1/INPUT_pw2bgw.html (copy of espresso-5.1/PP/Doc/INPUT_pw2bgw.html),
which is generated from MeanField/ESPRESSO/version-5.1/INPUT_pw2bgw.def, and
MeanField/ESPRESSO/version-5.0/INPUT_pw2bgw.html (copy of espresso-5.0.3/PP/Doc/INPUT_pw2bgw.html),
which is generated from MeanField/ESPRESSO/version-5.0/INPUT_pw2bgw.def.
You can find the input files for pw2bgw.x in examples/DFT
in the ESPRESSO subdirectories of each example.
Version 4.3.2 and earlier:
It is recommended to run a pw.x "nscf" calculation with "K_POINTS crystal"
and a list of k-points produced by kgrid.x.
Sometimes pw.x generates additional k-points in a "nscf" run with an explicit
list of k-points. If this is the case for your calculation, there are several
ways to go around this problem:
* Apply the patch provided with BerkeleyGW. It will prevent pw.x from
generating additional k-points if they are provided explicitly, and
take care of the normalization of the weights of k-points in a "bands"
calculation.
* Do not specify the atomic positions in the input file of kgrid.x (set
number of atoms = 0). Then pw.x will generate additional k-points which
are the correct ones. Also set noinv = .true. in the input file of pw.x
if time-reversal symmetry was not used in kgrid.x.
* Run a pw.x "bands" calculation instead of "nscf". In this case you have
to explicitly specify the occupations in the input file of pw2bgw.x (note
that this only works for insulators) and to normalize the weights of
k-points to one in the input file of pw.x.
Version 5.0 and later:
It is recommended to run a pw.x "bands" calculation with "K_POINTS crystal"
and a list of k-points produced by kgrid.x.
You can also run a pw.x "nscf" calculation instead of "bands", but in this
case pw.x may generate more k-points than provided in the input file of pw.x.
If this is the case for your calculation you will get errors in BerkeleyGW.
--------------------------------------------------------------------------------
bgw2pw.x
Converts BerkeleyGW WFN and RHO files to the format of pw.x.
This can be useful, for example, if you generate the plane waves
on top of the valence bands and want to diagonalize them in pw.x.
Look at the documentation for SAPO code in BerkeleyGW for more information.
Another possible use is to convert between different versions of pw.x.
bgw2pw.x reads common parameters from file prefix.save/data-file.xml and
writes files prefix.save/charge-density.dat (charge density in R-space),
prefix.save/gvectors.dat (G-vectors for charge density and potential),
prefix.save/K$n/eigenval.xml (eigenvalues and occupations for nth k-point),
prefix.save/K$n/evc.dat (wavefunctions in G-space for nth k-point), and
prefix.save/K$n/gkvectors.dat (G-vectors for nth k-point).
You must have prefix.save/K$n/eigenval.xml files present, or an error will occur,
even though their contents will not be used and will be overwritten.
The best is to run a pw.x calculation and use its prefix.save, e.g. from scf
and then get unoccupied bands from bgw2pw.x.
bgw2pw.x doesn't create restart files, so you cannot use restart_mode = 'restart'
for a subsequent pw.x run. Instead, use startingwfc = 'file'. Make sure
wf_collect = .true. and there are no prefix.wfc* files present. Also, the pw.x run
that generated the prefix.save directory originally must have wf_collect = .true.
also, for the appropriate links to the K$n files to be present.
bgw2pw.x doesn't modify file prefix.save/data-file.xml so make changes to this
file manually. For example, you will need to change the NUMBER_OF_BANDS and
NUMBER_OF_PROCESSORS tags (as well as per pool and per image) to make sure these
match the number of bands from the WFN file, as well as the number of processors
you will use in a subsequent run.
The format of the input file for bgw2pw.x is described
in files MeanField/ESPRESSO/version-4.3.2/bgw2pw.inp,
MeanField/ESPRESSO/version-5.1/INPUT_bgw2pw.html (copy of espresso-5.1/PP/Doc/INPUT_bgw2pw.html),
which is generated from MeanField/ESPRESSO/version-5.1/INPUT_bgw2pw.def, and
MeanField/ESPRESSO/version-5.0/INPUT_bgw2pw.html (copy of espresso-5.0.3/PP/Doc/INPUT_bgw2pw.html),
which is generated from MeanField/ESPRESSO/version-5.0/INPUT_bgw2pw.def.
--------------------------------------------------------------------------------
Notes on running pw.x
Sometimes pw.x crashes when trying to generate a LARGE number of unoccupied
states needed for GW calculations. The error messages may refer to "Cholesky
decomposition" or "diagonalization". If you run into this problem try one of
the following workarounds, or a combination of them:
1) Increase ecutwfc. Iterative diagonalization becomes inefficient and
unstable with increasing the ratio of the number of states to the size
of the Hamiltonian. Increasing ecutwfc will decrease this ratio
at the cost of computation time.
2) Split the calculation over k-points. If one k-point fails, it won't
affect the other k-points. You can merge the final wavefunction file
using MeanField/Utilities/wfnmerge.x after running pw2bgw.x for each
k-point.
3) Start with random instead of randomized atomic wavefunctions. For
this use the following parameter in the input file of pw.x:
startingwfc = 'random'
4) Split the diagonalization into several steps alternating between
different diagonalization schemes. For example, use the following
parameters in the input files for consequent runs of pw.x:
1st run:
conv_thr = 1.0d-2
diagonalization = 'david'
2nd run:
conv_thr = 1.0d-4
diagonalization = 'cg'
startingwfc = 'file'
3rd run:
conv_thr = 1.0d-6
diagonalization = 'david'
startingwfc = 'file'
etc.
5) Run pw.x with "-ndiag 1". Often serial diagonalization is more
stable than the parallel one, and the time and memory overhead
is bearable in most cases.
6) Compile pw.x without "-D__SCALAPACK" in DFLAGS in make.sys
for using a custom distributed-memory diagonalization instead
of ScaLAPACK. This is useful to check if the problem
is caused by improper installation of ScaLAPACK.
Note that you will have to explicitly specify ndiag,
e.g. "mpirun -np 24 pw.x -ndiag 16 -in prefix.in > prefix.out",
because pw.x only sets ndiag automatically in case of ScaLAPACK.
7) Last but not least, perform iterative diagonalization
in SAPO instead of using pw.x, see examples/DFT/Si2_sapo
for details.
Finally, it is recommended to always use the following parameters
in the input files for pw.x:
wf_collect = .true.
diago_full_acc = .true.
See documentation on Quantum ESPRESSO for information on these
parameters.
BEWARE: Sometimes wavefunctions may lose orthogonality during
iterative diagonalization. Neither Quantum ESPRESSO nor BerkeleyGW
checks for orthogonality of wavefunctions. This may cause erroneous
behavior like diverging head of eps0mat and possibly many other things.
This problem could be avoided by using SAPO [see 7) above] which keeps
wavefunctions orthogonal during iterative diagonalization.
MeanField/ESPRESSO/kgrid.inp
5 5 5 ! numbers of k-points along b1,b2,b3
0.5 0.5 0.5 ! k-grid offset (0.0 unshifted, 0.5 shifted by half a grid step)
! These first two lines are the usual Monkhorst-Pack parameters.
0.0 0.0 0.001 ! a small q-shift (0.0 unshifted, 0.001 shifted by one 1000th of b3)
! This is for WFNq in Epsilon.
0.0 0.5 0.5 ! lattice vectors in Cartesian coordinates (x,y,z)
0.5 0.0 0.5 ! in units of the lattice parameter
0.5 0.5 0.0 !
2 ! number of atoms in the unit cell
1 -0.125 -0.125 -0.125 ! atomic species and positions in Cartesian coordinates (x,y,z)
1 0.125 0.125 0.125 ! in units of the lattice parameter
0 0 0 ! size of FFT grid
.false. ! use time-reversal symmetry. Set to false for BerkeleyGW
.false. ! OPTIONAL: k-points in the log file are in Cartesian coordinates
.false. ! OPTIONAL: output is in Octopus format
# Above: typical values for Si. Below: general description.
# nk1 nk2 nk3 ! numbers of k-points in crystal coordinates (b1,b2,b3)
# dk1 dk2 dk3 ! k-grid offset (0.0 unshifted, 1.0 shifted by bj/nkj)
# dq1 dq2 dq3 ! a small q-shift (0.0 unshifted, 1.0 shifted by bj)
# a1x a1y a1z ! lattice vectors in Cartesian coordinates (x,y,z)
# a2x a2y a2z ! in arbitrary units (bohr, angstrom, lattice parameter)
# a3x a3y a3z !
# n ! number of atoms in the unit cell
# s1 x1 y1 z1 ! atomic species and positions in Cartesian coordinates (x,y,z)
# ........... ! in the same units as the lattice vectors
# sn xn yn zn !
# nr1 nr2 nr3 ! size of FFT grid
# trs ! if set to .true., use time-reversal symmetry (do not use this for BerkeleyGW)
# Cartesian ! OPTIONAL: set to .true. for k-points in Cartesian coordinates (only in the log file)
# octopus ! OPTIONAL: set to .true. to write output file in format suitable for Octopus