https://kylebystrom.github.io/pawpyseed/
PAWpySeed is a parallelized Python and C tool for reading and analyzing the optimized band structure and wave functions of VASP DFT calculations. The code is written for the PAW formalism developed by P.E. Blochl and implemented in VASP.
TO compile the C code, pawpyseed needs to link with the Intel Math Kernel Library (MKL). You can customize how this is done via the config file (see "The customizable way"). However, for most users, the easy way described below is adequate.
First, install mkl-devel
in your local installation:
pip install mkl-devel --user
Next, find your Python installation directory (call it INST_DIR
) and add the include
and lib
to your
C compiler paths to link with MKL:
export C_INCLUDE_PATH=$INST_DIR/include:$C_INCLUDE_PATH
export LIBRARY_PATH=$INST_DIR/lib:$LIBRARY_PATH
export LD_LIBRARY_PATH=$INST_DIR/lib:$LD_LIBRARY_PATH
Then run
python setup.py build
python setup.py install
OR with pip
.
pip install pawpyseed
This has been tested on Scientific Linux 7 and Linux Mint 18, but should work for systems that have the appropriate packages and environment variables defined as described below.
After installing MKL locally with pip
,
copy site.cfg.default
from the pawpyseed repository to ~/.pawpyseed-site.cfg
.
Open it and set root=<your home directory>/.local
under the [mkl]
heading
and uncomment it by removing the #
.
IF you get linking issues at runtime using this method, try setting
sdl=True
in the config file and then setting the environment
variable MKL_THREADING_LAYER=sequential
.
If you have icc
and prefer to use it to compile pawpyseed's C libraries,
set compiler=icc
in ~/.pawpyseed-site.cfg
and then
set root
to your MKL installation directory. Set sdl=True
. You MKL distribution must have also
been compiled with the Intel compiler. Run the setup.py
script or pip install pawpyseed
.
To make your own config file,
make a file in your home directory ~
named .pawpyseed-site.cfg
. This file allows you
to customize configuration settings for pawpyseed. It is read using the Python
configparser module https://docs.python.org/3/library/configparser.html. If you don't
want to learn about the configuration file options, skip to "The Easy Way" to get this done with quickly.
The options (with their defaults) are as follows:
[compiler]
# Name of the compiler to be used. By default, let's the setup script choose this.
compiler_name = <no default> # Examples: icc or gcc
# Name of the linker to be used. By default, let's the setup script choose this.
# NOTE: Don't forget the -shared tag for icc or gcc!
# NOTE: If compiler_name is set and linker_name is not,
# linker_name is set to compiler_name with the -shared tag appended.
linker_name = <no default> # Examples: icc -shared or gcc -shared
[mkl]
# MKL installation directory. <root>/lib or <root>/lib/intel64 must contain
# the MKL shared object libraries, while <root>/include must containn the MKL headers.
# Many systems have the environment variable
# MKLROOT set for this, so you can set this to the output of:
# echo $MKLROOT
# If you pip install mkl-devel, this goes to /usr or /usr/local.
# If you pip install mkl-devel --user, this goes to ~/.local
# (or the equivalents for your system).
root = <no default>
# Don't change this. Might be used in the future but currently has no effect.
interface32 = True
# Whether to compile with the single dynamic library libmkl_rt.so.
# If you are having installation/performance problems, try setting sdl=True,
# pip installing mkl-devel with the --user option, set root=~/.local,
# and set the environment variable MKL_THREADING_LAYER=sequential
# when using pawpyseed.
sdl = False
[threading]
# Whether to use omp_loops. If False, pawpyseed doesn't do any parallelization
# on its own, though its calls to MKL, BLAS, LAPACK, etc might be
# threaded by MKL.
omp_loops = True
# Whether to use threading for MKL. OVERRIDDEN if sdl=True, in which case
# MKL is threaded by default and you can run sequentially by
# setting the environment variable MKL_THREADING_LAYER=sequential
# when using pawpyseed.
# NOTE: ONLY SET THIS TRUE IF COMPILING WITH icc (OR gcc with omp_loops=False),
# and only if you are very concerned about speed. This is because gcc
# cannot do nested parallelism with MKL
threaded_mkl = False
# NOTE: Do not link to icc-compiled MKL libraries when compiling the C
# extension with gcc or vice versa. Use like type compilers.
All dependencies indicate the minimum version tested. PAWpySeed might work fine with earlier versions, but use of older versions will not be officially supported.
Python requirements:
Python>=3.5
numpy>=1.14
scipy>=1.0
pymatgen>=2018.2.13
sympy>=1.1.1
matplotlib>=0.2.5
C requirements:
icc >= 16.0.4 OR gcc >= 4.8.5
Intel Math Kernel Library >= 11.3.4
If you don't want to pip install
Intel MKL,
it is available for free installation on a variety of platforms.
Most computing clusters will have Intel MKL, and you can install it
on your desktop (or any system to which you have root access) by following
the relevant instructions at the following URL:
https://software.intel.com/en-us/articles/free-ipsxe-tools-and-libraries.
The projector augmented wave (PAW) method is a technique used in plane wave density functional theory to simplify the description of the wavefunctions near the nuclei of a system. The strong Coulombic forces near an atomic nucleus creates quickly oscillating wavefunctions that are not well described by plane waves without prohibitively large basis sets, so a "pseudopotential" is introduced near the atomic nuclei which results in smooth "pseudo wavefunctions" well described by plane waves. The full wavefunctions can be recovered by a linear transform of the pseudowavefunctions. The PAW method requires three sets of functions: projector functions, onto which pseudowavefunctions are projected to probe their character; full partial waves, which describe atomic valence states derived from the true potential; and pseudo partial waves, which are derived from the full partial waves and pseudopotential.
The projector functions and partial waves are unique to each element and stored in the POTCAR file used in a VASP calculation. The pseudowavefunction is the part of the wavefunction optimized during a DFT calculation and is stored in the WAVECAR output file in VASP. PAWpySeed parses both files to retrieve all parts of the full Kohn Sham wavefunctions.
The main purpose of PAWpySeed is to evaluate overlap operators between Kohn-Sham wavefunctions from different structures, which is not done by standard plane-wave DFT codes. Such functionality can be useful for analyzing the composition of defect levels in solids, which is main application for which the code is currently focused.
The code in PAWpySeed is based on a several algorithms and codes, which are enumerated here.
If you find pawpyseed useful, please encourage its development by citing the following paper in your research:
@ARTICLE{2019arXiv190411572B,
author = { {Bystrom}, Kyle and {Broberg}, Danny and {Dwaraknath}, Shyam and
{Persson}, Kristin A. and {Asta}, Mark},
title = "{Pawpyseed: Perturbation-extrapolation band shifting corrections for point defect calculations}",
journal = {arXiv e-prints},
keywords = {Condensed Matter - Materials Science},
year = "2019",
month = "Apr",
eid = {arXiv:1904.11572},
pages = {arXiv:1904.11572},
archivePrefix = {arXiv},
eprint = {1904.11572},
primaryClass = {cond-mat.mtrl-sci},
adsurl = {https://ui.adsabs.harvard.edu/abs/2019arXiv190411572B},
adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}
You can view the paper here: https://arxiv.org/abs/1904.11572
Find a bug? Areas of code unclearly documented? Other questions? Feel free to contact Kyle Bystrom at kylebystrom@gmail.com with the subject "pawpyseed: (Your Topic)" AND/OR create an issue on the Github page at https://github.com/kylebystrom/pawpyseed.