TABLE OF CONTENTS
2.3 Running Quantum ESPRESSO Programs and Pluggins
DESCRIPTION
This section explains how to run programs in PWTK.
TABLE OF CONTENTS
- Commands for running and restarting Quantum ESPRESSO calculations
- List of explicitly supported QE programs
- List of explicitly supported QE plugins
- Running non-supported programs
- How to run plugin calculations
- PWTK's restart mechanism
- PWTK's error-checking mechanism
- Simple example
Commands for running and restarting Quantum ESPRESSO calculations
In PWTK scripts, the calculations of Quantum ESPRESSO (QE) programs, supported by PWTK, are run with either the runXX command (see ::pwtk::runXX) or the runCmd set of commands, where Cmd is PW for pw.x (see ::pwtk::runPW), CP for cp.x (::pwtk::runCP), PH for ph.X (::pwtk::runPH), etc. The usage of the runXX commands is:
runXX PROG ?OPTIONS? INPUT ?OUTPUT?
where:
- PROG -- canonical name of the QE executable (e.g. pw.x, cp.x, ph.x)
- OPTIONS -- (optional) various options (see ::pwtk::runXX)
- INPUT -- filename where to store the input
- OUPUT -- (optional) filename where to store the output
For example, the pw.x calculation can be run either as:
runXX pw.x ?OPTIONS? INPUT ?OUTPUT?
or, equivalently:
runPW ?OPTIONS? INPUT ?OUTPUT?
Restarting QE calculations
The pw.x calculations can be restarted as:
rerunXX pw.x ?OPTIONS? INPUT ?OUTPUT?
or, equivalently:
rerunPW ?OPTIONS? INPUT ?OUTPUT?
and analogously for the other QE programs, which have the restart mode.
The "rerunXX pw.x" or "rerunPW" activates the restart mode (for pw.x, this implies "CONTROL { restart_mode = 'restart' }") and treats the output in the append mode (i.e. the output of the restart calculation is appended to the OUTPUT file).
List of explicitly supported QE programs
To get the list of all explicitly supported QE programs and their runCmd and rerunCmd commands, type in the PWTK prompt:
PWTK-% report programs
This will output the following alphabetically sorted list:
-------------------------------------------------------------------------------
executable runCmd rerunCmd input namespace
-------------------------------------------------------------------------------
all_currents.x runALL_CURRENTS ::pwtk::all_curri
band_interpolation.x runBAND_INTERPOLATION ::pwtk::band_inti
bands.x runBANDS ::pwtk::bi
bgw2pw.x runBGW2PW ::pwtk::bgw2pwi
cp.x runCP rerunCP ::pwtk::cpi
cppp.x runCPPP ::pwtk::cpppi
d3hess.x runD3HESS ::pwtk::d3hessi
dos.x runDOS ::pwtk::di
dynmat.x runDYNMAT ::pwtk::dmi
hp.x runHP ::pwtk::hpi
kcw.x runKCW ::pwtk::kcwi
ld1.x runLD1 ::pwtk::ld1i
matdyn.x runMATDYN ::pwtk::mdi
molecularpdos.x runMOPDOS ::pwtk::mpdi
neb.x runNEB rerunNEB ::pwtk::nebi
oscdft_et.x runOSCDFT_ET ::pwtk::oscdft_eti
oscdft_pp.x runOSCDFT_PP ::pwtk::oscdft_ppi
ph.x runPH rerunPH ::pwtk::phi
postahc.x runPOSTAHC ::pwtk::postahci
pp.x runPP ::pwtk::ppi
ppacf.x runPPACF ::pwtk::ppacfi
pprism.x runPPRISM ::pwtk::pprismi
projwfc.x runPROJWFC ::pwtk::pri
pw.x runPW rerunPW ::pwtk::pwi
pw2bgw.x runPW2BGW ::pwtk::pw2bgwi
pw2gw.x runPW2GW ::pwtk::pw2gwi
pw2wannier90.x runPW2WANNIER90 ::pwtk::pw2wan90i
pwcond.x runPWCOND rerunPWCOND ::pwtk::pwcondi
q2r.x runQ2R ::pwtk::q2ri
turbo_davidson.x runDAVIDSON rerunDAVIDSON ::pwtk::davi
turbo_eels.x runEELS rerunEELS ::pwtk::eelsi
turbo_lanczos.x runLANCZOS rerunLANCZOS ::pwtk::lani
turbo_magnon.x runMAGNON rerunMAGNON ::pwtk::magi
turbo_spectrum.x runSPECTRUM ::pwtk::speci
-------------------------------------------------------------------------------
It is evident from the above list, that only some of QE programs have a restart rerunCmd command.
List of explicitly supported QE plugins
PWTK also supports several QE plugins. To get the list of supported plugins, type in the PWTK prompt:
PWTK-% report plugins
This will output:
-------------------------------------------------------------------------------
plugin plugin namespace activate / deactivate in PWTK
-------------------------------------------------------------------------------
ARTN ::pwtk::artn artn on / artn off
ENVIRON ::pwtk::environ environ on / environ off
OSCDFT ::pwtk::oscdft oscdft on / oscdft off
-------------------------------------------------------------------------------
Running non-supported programs
QE programs not explicitly supported by PWTK can be executed in PWTK scripts with the generic run or execute commands.
The generic "run" command
The usage of the run command (see ::pwtk::run) is similar to that of runXX, i.e.:
run ?OPTIONS? PROGRAM INPUT ?OUTPUT?
where PROGRAM is the name of the QE executable. The difference between runXX and run is that for the former, PWTK automatically creates the INPUT file, whereas for the latter, the INPUT file must exist before calling run. Within the PWTK script, (input) files can be created with the writeFile command. Here is an example how to run the ev.x executable:
writeFile ev.murnaghan.in "au
fcc
4
Etot-vs-alat.dat
Etot-vs-alat.out
"
run -ihandle "<" -serial ev.x ev.murnaghan.in
The generic "execute" command
Sequential executables such as sumpdos.x that do not follow the "program < input > output" logic can be run with the execute command, where an executable and its command-line arguments are treated verbatim. Here is a sumpdos.x example:
execute sumpdos.x file1 file2 file3 file4 > output
while ev.x can be run as:
execute ev.x < file.in > file.out
How to run plugin calculations
In PWTK, calculations with supported plugins are run by activating the plugin and defining the plugin input data. The rest is taken care of by PWTK. Here is an example of how to perform an ENVIRON calculation:
# define the ENVIRON data
ENVIRON {
environ_type = 'water'
env_electrostatic = .true.
}
BOUNDARY {}
ELECTROSTATIC {
pbc_correction = 'parabolic'
pbc_dim = 0
tol = 1.d-11
}
# activate ENVIRON
environ on
# perform the pw.x ENVIRON calculation
runPW example
In this case, the call to runPW will (1) create the example.in pw.x input file, (2) create the environ.in ENVIRON input file, and (3) run the pw.x calculation as:
PREFIX pw.x --environ < example.in > example.out
where PREFIX is the prefix as set by the prefix command (see ::pwtk::prefix), e.g. "mpirun -np N".
Note that when ENVIRON is turned on, the call to runPW also makes a backup copy of the environ.in file. For example, "runPW example" makes a backup copy of environ.in, named environ.example.in.
ENVIRON is turned off with the command:
environ off
As a convenience there are also "environ restart" and "environ from_scratch" commands, i.e.:
environ restart
is equivalent to:
environ on
ENVIRON { restart_mode = .true. }
whereas:
environ from_scratch
is equivalent to:
environ on
ENVIRON { restart_mode = .false. }
PWTK's restart mechanism
PWTK has a simple restart mechanism (see ::pwtk::restart), which can be activated with:
restart on
If the restart mode is ON, then the calculation will not be performed if it was already done (default = OFF). PWTK establishes if the calculation is already done by inspecting the respective output file: if the output file exists and corresponds to a normally finished job, then calculation is skipped.
PWTK's error-checking mechanism
By default PWTK will terminate the execuation of a script if it detects that a given calculation did not finish normally. The reason is that PWTK scripts may contain workflows where a given calculation depends on the preceding calculations. The error-checking mechanism can be disabled by:
stopOnError off
For more details, see ::pwtk::stopOnError.
Simple example
# load the pw.x input data from an exists pw.x input file
load_fromPWI scf.Si_bulk.in
# turn the restart mode on
restart on
# run pw.x calculation
runPW scf.Si_bulk.in
# how to run a calculation with a code that is not directly supported by PWTK writeFile ev.murnaghan.in { ... input for the ev.x program ... } # either: run -ihandle < -serial ev.x ev.murnaghan.in # or: execute ev.x < ev.murnaghan.in > ev.murnaghan.out