PWTK: A Short Tutorial


1 Introduction

1.1 The purpose of PWTK

The PWTK stands for PWSCF TOOL KIT.

Technically, PWTK is a Tcl scripting interface for QUANTUM ESPRESSO. The aim of the PWTK package is to make the use of QUANTUM ESPRESSO easier and to provide a more productive framework. (The name of the PWTK originates from the fact that in its early versions, PWTK supported only a subset of PWSCF programs contained in the QUANTUM ESPRESSO distribution.)

Why PWTK? Imagine that you want to perform a set of calculations where only a few of parameters are varied. Such set of calculations requires a set of input files, one input per each run. Hence we have two choices: (i) to make a new input for each calculation, or (ii) to generate the files in some automate way. For simple cases automation can be achieved by shell scripts, but such scripts get quickly too elaborate. With the PWTK this is easily achieved, because the PWTK package provides a powerful and flexible scripting interface.

1.2 PWTK features

1.3 Simple example

Here is a simple example--a comparison between the pw.x input file for Si bulk and the corresponding PWTK script.

pw.x input file: si.scf.in PWTK script file: si.pwtk 
 &CONTROL
        title = 'Si bulk'
  calculation = 'scf' ,
 restart_mode = 'from_scratch' ,
       outdir = 'Si_example/' ,
   pseudo_dir = '/home/tone/pw/pseudo/' ,
 /

 &SYSTEM
        ibrav = 2,
    celldm(1) = 10.2,
          nat = 2,
         ntyp = 1,
      ecutwfc = 18.0,
      ecutrho = 72.0,
 /

 &ELECTRONS
     conv_thr = 1d-7,
 /

ATOMIC_SPECIES
   Si  1.00  Si.vbc 

ATOMIC_POSITIONS alat 
   Si    0.00  0.00  0.00    
   Si    0.25  0.25  0.25    

K_POINTS automatic 
   4 4 4   1 1 1

CONTROL {
        title = 'Si bulk'
  calculation = 'scf' ,
 restart_mode = 'from_scratch' ,
       outdir = 'Si_example/' ,
   pseudo_dir = '/home/tone/pw/pseudo/' ,
} 
 
SYSTEM {
        ibrav = 2,
    celldm(1) = 10.2,
          nat = 2,
         ntyp = 1,
      ecutwfc = 18.0 ,
      ecutrho = 4*18.0 ,
}

ELECTRONS {
      conv_thr = 1d-7,
}

ATOMIC_SPECIES {
   Si  1.00  Si.vbc 
}
ATOMIC_POSITIONS alat {
   Si    0.0   0.0   0.0
   Si    1/4   1/4   1/4
}
K_POINTS automatic {
  4 4 4   1 1 1 
}

runPW si.scf.in
This calculation is run as: This calculation is run as: 
pw.x < si.scf.in > si.scf.out &

pwtk si.pwtk

The syntax of the input data in PWTK's scripts is similar to that of PWSCF's input file, but notice that both Fortran namelists (e.g. &CONTROL .... /) and cards (e.g. ATOMIC_SPECIES) are enclosed with curly braces (e.g. CONTROL { ... }). The curly braces are due to the fact that the PWTK package is written in TCL scripting language.

The last line of the above PWTK script (i.e. runPW si.scf) requests the pw.x calculation. Upon execution the PWTK will:

1.4 Syntax of the PWTK scripts

Here are the main syntactic attributes of the PWTK scripts:

1.5 Example: running multiple calculations

One of the strengths of PWTK is the possibility to (re)assign the value of namelist's variable or the content of a given card at will. This comes handy when performing multiple calculations, where only a few parameters change per run, while the majority of the input data is common to all runs.

Let us perform a few tests on Si bulk example. We will first construct a common script that will be used by all calculations. Let us call it Si_common.pwtk: 

CONTROL {
         title = 'Si bulk'
   calculation = 'scf' ,
  restart_mode = 'from_scratch' ,
        outdir = 'Si_example/' ,
    pseudo_dir = '/home/tone/pw/pseudo/' ,
} 
 
SYSTEM {
         ibrav = 2,
     celldm(1) = 10.2,
           nat = 2,
          ntyp = 1,
       ecutwfc = 18.0 ,
       ecutrho = 4*18.0 ,
}

ELECTRONS {
      conv_thr = 1d-7,
}

ATOMIC_SPECIES {
   Si  1.00  Si.vbc 
}

ATOMIC_POSITIONS alat {
   Si    0.0   0.0   0.0
   Si    1/4   1/4   1/4
}

K_POINTS automatic {
  4 4 4   1 1 1 
}

Now let's make a script that will scan the energy-cutoff (ecutwfc), k-point mesh (K_POINTS), and lattice parameter (celldm(1)). Let's call this file scan.pwtk. 

# load the common definitions
source Si_common.pwtk

#------------------------
# scan the energy-cuttofs
#------------------------
foreach e {10.0 14.0 18.0 22.0} {
   # load the new energy-cuttofs
   SYSTEM "ecutwfc = $e, ecutrho = 4*$e"

   # perform the calculation (io files: Si_e$e.scf.in|out)
   runPW Si_e$e.scf
}

#-----------------
# scan the kpoints
#-----------------
# say that we want to perform this at 18.0 Ry 
SYSTEM "ecutwfc = 18.0, ecutrho = 4*18.0"

foreach k {2 4 6} {
   # load new k-points
   K_POINTS automatic "$k $k $k   1 1 1"

   # perform the calculation (io files: Si_k$k.scf.in|out)
   runPW Si_k$k.scf
}

#---------------------------
# scan the lattice-parameter
#---------------------------
# say that we want to perform this at the following k-mesh
K_POINTS automatic "4 4 4   1 1 1"

# here we use the "seq" command, which behaves just like the Unix seq
foreach a [seq 9.2 0.2 10.8] {
   # load new celldm(1)
   SYSTEM " celldm(1) = $a "

   # perform the calculation (io files: Si_a$a.scf.in|out)
   runPW Si_a$a.scf
}

We run this script by executing: pwtk scan.pwtk. Notice from this example that the namelist variables and cards can be reassigned at will.

1.6 List of supported QUANTUM ESPRESSO programs

The following QUANTUM ESPRESSO programs are explicitly supported by PWTK. The below list lists the supported programs and the corresponding PWTK routines for running them in the form: program -> runCommand.

Note that it is possible to run also other QUANTUM ESPRESSO programs that are not directly supported by PWTK, using the run command or even the generic Tcl exec command. As an example, see the end of the file Si.pwtk.

2 Input data stacking

PWTK allows for input data stacking, which is useful when performing multiple calculations. For example, we want a set of default parameters for all calculations, but each individual calculation require some modification of input data. We don't want that a change of input data for a given calculation affects the input data for other calculations. This can be done by organizing input data into a stack, and for this purpose PWTK provide input_push and input_pop commands. The concept is illustrated below: 

... define default set of parameters (#0)

# 1st calculation 
input_push
   # input data has been pushed on the stack;
   # at this point the input data is the same as in (#0)
 
   ... modify input data for this calculation (#1)
   ... perform 1st calculation
input_pop

# the "input_pop" has removed the input data modification (#1),
# i.e. input data (#1) has been popped from the stack;
# at this point the input data is the same as in (#0)

# 2nd calculation
input_push
   # input data still the same as in (#0)
 
   ... modify input data for this calculation (#2)
   ... perform 2nd calculation
input_pop

# at this point the input data is again the same as in (#0)

As a convenience, there is also the input_pushpop { ... } command, which behaves as the input_push ... input_pop pair, i.e.: 

# example of input_push/input_pop pair
input_push
   ... modify input data
   ... perform calculation
input_pop

# the same example using the input_pushpop { ... } command
input_pushpop {
   ... modify input data
   ... perform calculation
}

3 Customizing the PWTK

PWTK customization (configuration) files are stored in $HOME/.pwtk/  directory and the main customization file therein is pwtk.tcl. In this file the following items are defined (actually default values for those items):

The system configuration files are stored in $PWTK/config/ directory and the PWTK first reads the system configuration files and then the user configuration files, which implies that user definitions have precedence/priority over the system configuration (i.e. user can overwrite system configuration).

3.1 Main configuration file: $HOME/.pwtk/pwtk.tcl

Here is an example of the $HOME/.pwtk/pwtk.tcl file: 

# ------------------------------------------------------------------------
# 
# File: pwtk.tcl -- PWTK main configuration file
#
# This is a main configuration file for PWTK. It contains some custom
# definitions, such as Quantum ESPRESSO executables and alike.
#
# (by default almost everything is commented)
# ------------------------------------------------------------------------

#
# HOW TO RUN QUANTUM ESPRESSO EXECUTABLES ...
# 
# They are run as: prefix bin_dir/program postfix

#prefix  ""
#postfix ""
#bin_dir $env(HOME)/bin/espresso

# For Singularity containers use:

#prefix "singularity exec /path/to/container.simg mpirun -np 32"
#serial_prefix "singularity exec /path/to/container.simg"
#bin_query false

# if you wish to define some individual executables explicitly,
# uncomment appropriate lines below, and set the full-path name
# accordingly.

# pw  /full/path/to/pw.x
# neb /full/path/to/neb.x
# ph  /full/path/to/ph.x
# cp  /full/path/to/cp.x

#
# DEFAULT DIRECTORIES ...
#
# top (root) directory where the scatch files will be written
# (i.e. outdir == outdir_prefix/outdir_postfix)

# either:
#outdir_prefix /scratch/$env(USER)/pw
#wfcdir_prefix /scratch/$env(USER)/pw

# or:
#outdir        /scratch/$env(USER)/pw/[pid]
#wfcdir        /scratch/$env(USER)/pw/[pid]

# default pseudo_dir
#pseudo_dir    $env(HOME)/pw/pseudo

In this file, the following data are specified:

3.2 (Incomplete) list of configuration files

Among the configuration files that are usually copied by a user from $PWTK/config/ to $HOME/.pwtk/ directory and edited therein are:

The following configuration files typically do not need any user editing and relying on system configurations in $PWTK/config/directory is just fine.

3.3 PWTK's batch queuing support

When running calculations via batch queuing system one needs to provide some batch queuing system specific instructions within the shell script files, such as the name of the queue, number of processors, and some other resources. Instead of putting this instructions inside each shell script (or PWTK script, if one is using PWTK instead), the specific queuing system instructions can be stored in the corresponding PWTK's configuration file (e.q. $HOME/.pwtk/slurm.tcl, $HOME/.pwtk/lsf.tcl, or $HOME/.pwtk/ll.tcl).

Once such configuration file is properly set, we need to tell to PWTK that the script is to be submitted to the batch queuing system. For example, for SLURM this can be achieved by encapsulating the whole script with the SLURM { ... } command, i.e.: 

SLURM {
    ... here comes the whole script ...
}

Alternatively, a plain PWTK script can be imported with the import command, i.e: 

SLURM {
    import job.pwtk
}

Note that SLURM command is fully configurable; its usage is the following:

where script stands for the plain PWTK script to be submitted to SLURM and profile is the name of the profile as defined in the user $HOME/.pwtk/slurm.tcl file and contains SLURM specific directives. If the profile is omitted the default profile is used, which is guaranteed to exist, because it is defined in the $PWTK/config/slurm.tcl file.

One can define different profiles in the configuration file. Here is an example where two different SLURM profiles, named as parallel and longpar are defined in user configuration file $HOME/.pwtk/slurm.tcl: 

# ------------------------------------------------------------------------
# 
# SLURM
#
# This is a configuration file for PWTK's SLURM utility
#
# ------------------------------------------------------------------------

set profile(parallel) {
    #!/bin/sh
    #SBATCH --nodes=1
    #SBATCH --ntasks=64
    #SBATCH --time=6:00:00
    #SBATCH --partition=parallel
}

set profile(longpar) {
    #!/bin/sh
    #SBATCH --nodes=1
    #SBATCH --ntasks=64
    #SBATCH --time=24:00:00
    #SBATCH --partition=longpar
}

For example, the longpar profile can then be utilized in PWTK script via: 

SLURM longpar {
    import job.pwtk
}

4 Math parser

As specified above floating-point numbers can be specified as mathematical expressions, for example: 1/4*exp(2*log(0.23)). Here is an example of how mathematical expressions can be used in specifying the input data: 

SYSTEM { celldm(1) = 7.5*sqrt(2)*$angs2bohr }
ATOMIC_POSITIONS alat {
   Si    0.0   0.0   0.0
   Si    1/4   1/4   1/4
}

Notice the use of $angs2bohr in the example above. This a predefined constant (a conversion factor from Å to Bohr units).

IMPORTANT: mathematical expression should be written without any whitespace or else it should be double-quoted. For example, the 1/4 * sqrt(2) expression contains two whitespaces and it will be treated as three separate input-fields and the parser will return .25000000000000000000 * 1.41421356237309504880, whereas "1/4 * sqrt(2)" is evaluated to .35355339059327376220.

4.1 List of predefined constants

Here is a list of predefined constant that can be used in mathematical expressions, and their values (corresponding to CODATA Internationally recommended 2018 values):

4.2 List of mathematical functions

Here is a list of supported mathematical functions (actually these are functions supported by the Tcl):

About this document ...

PWTK: A Short Tutorial

This document was generated using the LaTeX2HTML translator Version 2019 (Released January 1, 2019)

The command line arguments were:
latex2html -split 1 -t 'PWTK: A Short Tutorial' -no_navigation -toc_stars -show_section_numbers -link 4 -toc_depth 4 tutorial.tex

The translation was initiated on 2021-05-18