TABLE OF CONTENTS

2.1 Description of the PWTK API

DESCRIPTION

This section describes the basics of the PWTK API (application programming interface).

PWTK consists of hundreds of commands, which, for a newcomer, may easily appear overwhelming. However, once the logic of the PWTK API is understood, using PWTK gets much more straightforward.

TABLE OF CONTENTS

  1. PWTK and Tcl
  2. PWTK's namespaces
  3. PWTK's exported commands
  4. Getting info about exported commands

PWTK and Tcl

PWTK is written in Tcl. Technically, PWTK scripts are Tcl scripts. This implies that a basic knowledge of Tcl is a big plus. There are many online resorces for learning Tcl. Here are a few recommendations:

PWTK's namespaces

To prevent name clashes, all PWTK commands are implemented in the ::pwtk namespace. The commands for various purposes are then logically organized in child namespaces. For example, commands associated with the pw.x input and output data use ::pwtk::pwi and ::pwtk::pwo namespaces, and analogously for other QE executables, e.g., ::pwtk::nebi and ::pwtk::nebo for the neb.x input and output data, ::pwtk::dmi and ::pwtk::dmo for the dynmat.x input and output data, etc.

Here is the organizational structure of some namespaces: 

   ::pwtk   (PWTK parent namespace)
      |
      +-- namespaces dealing with QE input data have "i" suffix
      |     |
      |     +-- ::pwtk::pwi   (for pw.x input data)
      |     +-- ::pwtk::nebi  (for neb.x input data)
      |     +-- ....
      |
      +-- namespaces dealing with QE output files have "o" suffix
      |     |
      |     +-- ::pwtk::pwo   (for pw.x output)
      |     +-- ::pwtk::nebo  (for neb.x output)
      |     +-- ....
      |
      +-- ::pwtk::xsf  (namespace dealing with XSF files)
      |
      +-- ::pwtk::slurm   (namespace dealing with SLURM)
      +-- ::pwtk::lsf     (namespace dealing with LSF)
      +-- ....
      |
      +-- ::pwtk::difden  (namespace for the DIFDEN workflow)
      +-- ::pwtk::eos     (namespace for the EOS workflow)
      +-- ....
      |
      ....

PWTK's exported commands

As a convenience, some of the commands are exported to the global namespace and can be used without the namespace qualifiers. Here are a few examples of exported commands: 

   ::pwtk::runXX --> runXX
   ::pwtk::import --> import
   ::pwtk::pwi::load_fromPWI --> load_fromPWI
   ::pwtk::environ::environ --> environ

Some of the exported commands are shortcuts of the fully-qualified command names, using the following logic:

::pwtk::namespace::command --> namespace_command

where namespace and command stand for the namespace and command names, respectively. Here are a few examples: 

     ::pwtk::pwi::visualize   --> pwi_visualize
     ::pwtk::pwo::totene      --> pwo_totene
     ::pwtk::dmo::vibSpectrum --> dmo_vibSpectrum

To query the exported commands that matches, say, the *pwo_* pattern, enter the PWTK interactive prompt (in the terminal, type: pwtk) and type (PWTK-% stands for the PWTK prompt): 

    PWTK-% report exported pwo_

which returns the following alpabetically sorted list of exported commands: 

    * commands matching the *pwo_* pattern:
    pwo_alat pwo_conv_thr pwo_dipole pwo_ecutrho pwo_ecutwfc
    pwo_efermi pwo_etot pwo_etot_conv_thr pwo_forc_conv_thr
    pwo_ibrav pwo_mixing_beta pwo_nat pwo_nbnd pwo_nelec pwo_ntyp
    pwo_press pwo_totene pwo_totfor pwo_totmag pwo_volume pwo_xc

Getting info about exported commands

To query if a given command is exported to the global namespace, enter the PWTK interactive prompt (in the terminal, type: pwtk) and type (PWTK-% stands for the PWTK prompt): 

     PWTK-% report cmd report

which returns: 

     command report exists, its fully-qualified name is ::pwtk::report

implying that 'report' itself is an exported command. Let us now query if 'fixAtoms' is an exported command, i.e.: 

     PWTK-% report cmd fixAtoms


     command fixAtoms exists, its fully-qualified name is ::pwtk::pwi::fixAtoms

This implies that 'fixAtoms' is exported and corresponds to ::pwtk::pwi::fixAtoms. We get a similar answer for: 

     PWTK-% report cmd ::pwtk::pwi::fixAtoms


     command ::pwtk::pwi::fixAtoms is exported and can be used as fixAtoms

Now, let us try: 

     PWTK-% report cmd ::pwtk::nebi::fixAtoms


     command ::pwtk::nebi::fixAtoms exists but is not exported

implying that ::pwtk::nebi::fixAtoms is not exported. This is reasonable because ::pwtk::pwi::fixAtoms is already exported to fixAtoms, otherwise there would be a name clash.

To get the alphabetically sorted list of exported commands related to a given QE executable, e.g., type in the PWTK prompt: 

     PWTK-% report exported dynmat.x

which gives: 

     * dynmat.x run command:
       runDYNMAT   (or runXX dynmat.x)
     
     * dynmat.x rerun command:
       runDYNMAT   (or rerunXX dynmat.x)
     
     * dynmat.x input commands:
       DYNMAT dmi_clear dmi_fprint dmi_get load_fromDMI
     
     * dynmat.x output commands:
       dmo_vibSpectrum

One can also query all exported commands for a given child namespace, e.g.: 

     PWTK-% report exported environ

which gives: 

     * environ commands:
       BOUNDARY DIELECTRIC_REGIONS ELECTROSTATIC ENVIRON
       EXTERNAL_CHARGES environ environ_clear environ_fprint
       environ_get load_environ.in save_environ.in