Table of contents |
PWTK is written in Tcl (and uses tcllib, tclreadline, tcl-thread) but it is recommended to also install xcrysden, Gnuplot, Open Babel, Emacs, ImageMagick, and wget packages.
Depending on the GNU/Linux distribution, these packages can be installed as follows:
For Debian-based distros:
sudo apt install tcl tcllib tcl-tclreadline tcl-thread openbabel emacs gnuplot-qt imagemagick wget xcrysden
For Fedora-based distros (no xcrysden here):
sudo dnf install tcl tcllib tcl-tclreadline tcl-thread openbabel emacs gnuplot ImageMagick wget
For openSUSE-based distros (no tclreadline and xcrysden here):
sudo zypper install tcl tcllib openbabel emacs gnuplot ImageMagick wget
For other distros, install the packages analogously using the distro’s package manager.
Obviously, PWTK also needs Quantum ESPRESSO (QE). If it is not already installed, here is a quick way to install it for Debian-based distros:
sudo apt install quantum-espresso
For other GNU/Linux distros, QE can be installed analogously using the corresponding package manager.
(N.B. quantum-espresso
in Debian is version 6.7, and its
ev.x
program has a bug: it incorrectly calculates a
lattice parameter)
To make editing of PWTK scripts and Quantum ESPRESSO (QE) input files easier, let’s also install QE-emacs-modes, i.e.:
cd /tmp
wget http://pwtk.ijs.si/download/QE-modes-7.3.1.tar.gz
tar zxvf QE-modes-7.3.1.tar.gz
cd QE-modes-7.3.1
./install.sh
The install.sh
script installs QE-emacs-modes in
~/.emacs.d/qe-modes/
. To activate QE-emacs-modes in Emacs, include the
content of the qe-modes.emacs
file into the
~/.emacs
file using an editor of your choice.
Alternatively, from the terminal, this can be achieved by:
cat qe-modes.emacs >> ~/.emacs
QE-emacs-modes are now ready to use. This is what you get when opening a PWTK script with Emacs:
PWTK requires no compilation.
Once the above prerequisites are installed, download and unpack the
PWTK tarball. Let’s install PWTK in the ~/src
directory, i.e.:
mkdir -p ~/src
cd ~/src
wget http://pwtk.ijs.si/download/pwtk-3.1.tar.gz
tar zxvf pwtk-3.1.tar.gz
We need to add the location of the installed PWTK (e.g.,
$HOME/src/pwtk-3.1
) to the PATH
environmental variable, i.e., add the following line into the
~/.bashrc
file:
export PATH=$HOME/src/pwtk-3.1:$PATH
Now open a new terminal and type:
pwtk -h
which prints the usage message:
NAME
pwtk - a Tcl scripting interface for Quantum ESPRESSO
SYNOPSIS
pwtk [OPTIONS] [FILE]
DESCRIPTION
FILE is the name of the pwtk script to run (if FILE is -, pwtk
reads the script from stdin). With no OPTION and no FILE, pwtk
enters the interactive mode.
OPTIONS
-h
--help
print this usage message
-i
--interactive
run PWTK interactively
...
Let’s try to see if PWTK works as it should. Type in the terminal:
pwtk
This enters the PWTK interactive prompt. Type:
splot -xr -pi:pi -yr -pi:pi sin(x)*cos(y)
The following plot should appear:
To exit from the PWTK, close
the plot (e.g., press Enter in the terminal) and type
exit
.
It is a good idea to (at least) minimally configure PWTK to inform it of the location of
QE executables and
how to run them. The main user configuration file is
~/.pwtk/pwtk.tcl
, which can be created as follows:
mkdir -p ~/.pwtk
cd ~/.pwtk
cp ~/src/pwtk-3.1/config/pwtk_simple.tcl pwtk.tcl
Here, we used the pwtk_simple.tcl template from the
PWTK’s config/ subdirectory (remember that we installed
PWTK in
~/src/pwtk-3.1
). On a laptop or desktop computer, we
can edit the ~/.pwtk/pwtk.tcl
file to look something
like:
# how to run executables (prefix)
# (this snippet auto-detects the number of available processors)
{
try set np [exec nproc]
while { [catch {exec mpirun -n $np echo yes}] && $np > 1 } {
set np [expr { $np > 2 ? $np / 2 : 1 }]
}
if { $np > 1 } {
-n $np
prefix mpirun}
}
# directory containing the QE executables (bin_dir);
# needed only if the QE executables are not on $PATH
$env(HOME)/bin/qe-7.3.1; ## EDIT THIS
bin_dir
# directory containing pseudopotentials (pseudo_dir);
# needed only if 'pseudo_dir' != $HOME/espresso/pseudo
# and the ESPRESSO_PSEUDO environment variable is undefined
$env(HOME)/pw/pseudo; ## EDIT THIS
pseudo_dir
# scratch directory (outdir)
# (e.g. outdir == outdir_prefix/outdir_postfix)
$env(USER)/QE
outdir_prefix /tmp/[pid] outdir_postfix
With such a config, the number of available processors on the
computer is auto-detected, and the prefix
is set accordingly to mpirun -np $np
. With bin_dir
and pseudo_dir,
we instructed PWTK of the location
of QE executables
and pseudopotential files (by default, PWTK downloads requested
pseudopotentials from https://pseudopotentials.quantum-espresso.org/upf_files
if they cannot be found in pseudo_dir
). With outdir_prefix
and outdir_postfix,
we set the default location for the scratch files (aka
outdir
). Using such a setup, we can avoid defining the
pseudo_dir
and outdir
QE variables in PWTK scripts.
Remark: On HPC machines, the content of the
~/.pwtk/pwtk.tcl
is likely different because, there,
one typically uses modules or containers and submits jobs to queues,
implying that bin_dir
and prefix
can be avoided in ~/.pwtk/pwtk.tcl
.
PWTK supports the Slurm, LSF, PBS, and Load-Leveler job schedulers. The below example is for Slurm; for other job schedulers, the configuration is analogous.
To configure PWTK to use Slurm, a user should define Slurm profiles in the
~/.pwtk/slurm.tcl
configuration file; for other job
schedulers the respective files are ~/.pwtk/lsf.tcl
,
~/.pwtk/pbs.tcl
, and ~/.pwtk/ll.tcl
.
Templates for these files are available in the PWTK’s config/ subdirectory (remember we installed PWTK in ~/src/pwtk-3.1
);
hence:
cd ~/.pwtk
cp ~/src/pwtk-3.1/config/slurm.tcl .
Now, edit the slurm.tcl file with an editor of your choice. A user should define at least the default profile. Here is an example of two user-defined Slurm profiles, named default and small:
default {
slurm_profile #!/bin/sh
#SBATCH --nodes=1
#SBATCH --ntasks=16
#SBATCH --time=6:00:00
#SBATCH --partition=parallel
} {
-np 16
prefix mpirun}
{
slurm_profile small #!/bin/sh
#SBATCH --nodes=1
#SBATCH --ntasks=4
#SBATCH --time=00:30:00
#SBATCH --partition=long
} {
-np 4
prefix mpirun}
The usage of slurm_profile is:
slurm_profile profileName slurmDirectives ?pwtkDirectives?
where the last pwtkDirectives argument is optional. Its
purpose is to provide PWTK with a
default way of running executables. For example, the above
small profile requests 4 tasks, so it is reasonable to run
executables with mpirun -np 4
.
In addition to #SBATCH
directives,
module
commands can also be specified in the profile.
However, it is recommended to specify modules with the slurm_head
command because slurm_head
applies to all defined Slurm profiles, e.g.:
slurm_head {
module load QuantumESPRESSO/7.1-foss-2022a; ## EDIT THIS
}
Now, we are ready to submit our first PWTK script to Slurm. Go to some temporary
directory (e.g., ~/tmp
) and copy the scf.Si.in file from $PWTK/examples (in our case, the value of
$PWTK
is ~/src/pwtk-3.1
), i.e.:
mkdir -p ~/tmp
cd ~/tmp
cp ~/src/pwtk-3.1/examples/scf.Si.in .
Let us now create a simple PWTK
script (say ex1.pwtk
) that will load the scf.Si.in input file and perform the
pw.x calculation, e.g.:
emacs ex1.pwtk
and write the following two lines in the editor:
load_fromPWI scf.Si.in
runPW scf.Si.in
where load_fromPWI
loads the scf.Si.in input file into
PWTK and runPW
performs the pw.x calculation. After saving, we can
submit the ex1.pwtk
script as:
pwtk --slurm=small ex1.pwtk
where the --slurm=small
option requests submission
to Slurm queue using the
small
profile defined above. We get the following
printout:
========================================================================
*** PWTK-3.1 (PWscf ToolKit: a Tcl scripting environment)
========================================================================
(for more info about PWTK, see http://pwtk.ijs.si/)
Running on host: hpc-login1.arnes.si
PWTK: /d/hpc/home/src/pwtk-3.1
Date: Mon Apr 29 07:27:42 AM CEST 2024
PID: 3087480
SLURM| ======================================================================
SLURM| *** running PWTK script within the SLURM batch queuing system
SLURM| ======================================================================
batch PWTK script : ex1.slurm.1.pwtk
batch PWTK log file: ex1.slurm.1.pwtk.log
batch profile name : small
batch PWTK script profile:
prefix mpirun -np 4
SLURM batch script: ex1.slurm.1.sh
Content of the SLURM script:
#!/bin/sh
#SBATCH --nodes=1
#SBATCH --ntasks=4
#SBATCH --time=00:30:00
#SBATCH --partition=long
module load QuantumESPRESSO/7.1-foss-2022a
pwtk ex1.slurm.1.pwtk > ex1.slurm.1.pwtk.log 2>&1
Running: exec sbatch ex1.slurm.1.sh &
Job done.
--
Now, we can check if the job was submitted to the Slurm queue, i.e.:
squeue -u $USER
which returns something like:
JOBID PARTITION NAME USER ST TIME NODES NODELIST(REASON)
48961768 long ex1.slur tonek R 0:03 1 wn162
This implies we are ready to use PWTK to submit jobs to Slurm queues.
PWTK can be configured to use QE executables from a container. When using an Apptainer container, the QE executables would be run from the terminal as shown below with the annotated components:
apptainer exec /path/to/container.sif mpirun -np 16 pw.x -npool 2 -in INPUT > OUTPUT
| | | | | |
+----- container-----------------+ +--prefix--+ +postfix+
where /path/to/container.sif
stands for the pathname
of the container image (say, $HOME/bin/qe-7.3.1.sif
).
The corresponding PWTK
configuration for the above command line is:
container apptainer exec /path/to/container.sif
prefix mpirun -np 16
postfix -npool 2
IMPORTANT: when using containers, the querying of executables must be switched off, i.e.:
bin_query off
otherwise, PWTK complains that
QE executables
cannot be found and refuses to run them. The corresponding
definition in the ~/.pwtk/pwtk.tcl
configuration file
would be:
exec /path/to/container.sif
container apptainer -np 16
prefix mpirun
bin_query off
where postfix was omitted because it is case-specific. On HPC machines, the use of containers can be configured in the corresponding job-scheduler profiles. For example, let us reuse the above small Slurm profile, which in this case would be:
{
slurm_profile small #!/bin/sh
#SBATCH --nodes=1
#SBATCH --ntasks=4
#SBATCH --time=00:30:00
#SBATCH --partition=long
} {
exec /path/to/container.sif
container apptainer -np 4
prefix mpirun
bin_query off}
where /path/to/container.sif
needs to be replaced
with the pathname of the actual container image.