mopdos.tcl

::pwtk::mopdos_run

::pwtk::mopdos_run

SYNOPSIS

proc ::pwtk::mopdos_run {args} {

PURPOSE

A very configurable workflow for calculating and plotting DOS projected to molecular orbitals (aka MOPDOS).

The workflow requires minimal input data specs for moleculardos.x (see the example below). In particular, all i_atmwfc_* and i_bnd_* variables are automatically assigned by the workflow itself.

USAGE

   ::pwtk::mopdos_run  ?SPECIFIC-OPTIONS?  ?PLOTTING-OPTIONS?  HEAD  MOLECULE  MOLATOMS

   where SPECIFIC-OPTIONS are:

       -scf
       -nscf KGRID
       -e    EFERMI
       -emin EMIN
       -emax EMAX

       -homo HOMO_INDEX 
       -mo   MO_INDICES 
       -molatoms   MOL_ATOMS 
       -otheratoms OTHER_ATOMS 
       -mollab     MOL_LABEL 
       -otherlab   OTHER_LABEL

  PLOTTING-OPTIONS:

       -top 
       -descend 
       -yrel  YREL 
       -rymax RYMAX 
       -ylp   Y_LABEL_PDOS 
       -lx    LABEL_X_POS 
       -ly    LABEL_Y_POS

       -out   ROOTNAME
       -w_dw  WITH 
       -w_mol WITH 
       -w_mol_dw WITH 
       -fc    FILLCOLOR 
       -fc_dw FILLCOLOR 
       -fc_mol FILLCOLOR 
       -fc_mol_dw FILLCOLOR


   For other PLOTTING-OPTIONS, see: ::pwtk::plot.
   Ignored PLOTTING-OPTIONS: -u

ARGUMENTS

HEAD --- the name of the whole structure; the corresponding files will be named as prefix.$HEAD.postfix
MOLECULE --- the name of the molecule; the corresponding files will be named as prefix.fragment_$MOLECULE.postfix
MOLATOMS --- indices of molecular atoms in the whole structure

SPECIFIC OPTIONS

-scf --- perform an SCF pw.x calculation of the whole structure (the Fermi energy is taken from this SCF calculation unless the -nscf or -e option is specified)
-nscf {K1 K2 K3 ?SK1 SK2 SK3?} --- perform NSCF pw.x calculation of the whole structure using the provided automatic k-point grid; if SK1,SK2,SK3 shifts are omitted, a non-shifted k-mesh is used; (the Fermi energy is taken from this NSCF calculation unless the -e option is specified)
-e EFERMI --- Fermi energy (either a floating-point number or a pw.x output file from where the Fermi energy is taken)
-emin EMIN --- the minimum-energy with respect to Fermi energy (in eV) to be used for projwfc.x & molecularpdos.x, i.e., Emin is set to: Emin = EMIN + Efermi
-emax EMAX --- the maximum-energy with respect to Fermi energy (in eV) to be used for projwfc.x & molecularpdos.x, i.e., Emax x is set to: Emax = EMAX + Efermi
-homo HOMO_INDEX --- index of the molecular HOMO orbital (if specified, MOs are labeled as ...HOMO-2 HOMO-1, HOMO, LUMO, LUMO+1...; otherwise, MOs are labeled as MO-1, MO-2...
-mo MO_INDICES --- indices of MOs used for DOS projections (default = all molecular MOs)
-molatoms MOL_ATOMS --- a subset of molecular atoms used for PDOS plot (default = MOLATOMS)
-otheratoms OTHER_ATOMS --- a subset of atoms of the rest of the structure used for PDOS plot (default = all atoms - MOLATOMS)
-mollab MOL_LABEL --- a molecular label in PDOS plot (default = mol)
-otherlab OTHER_LABEL --- a label for the rest of the structure in PDOS plot (default = other)

PLOTTING OPTIONS

-top --- plot MOPDOS above PDOS (default = bottom, i.e., PDOS above MOPDOS)
-descend --- plot MO projections in descending order from top to bottom (default = ascend)
-yrel YREL --- relative Y-size of PDOS plot wrt single MOPDOS plot
-rymax RYMAX --- relative YMAX (i.e. upper bound of Y-range) wrt maximum-MOPDOS for MOPDOS
-ylp Y_LABEL_PDOS --- Y-label for PDOS (default = PDOS; N.B. -yl is used for MOPDOS)
-lx LABEL_X_POS --- relative X position of MO labels in the MOPDOS plot
-ly LABEL_Y_POS --- relative Y position of MO labels in the MOPDOS plot
-out ROOTNAME --- rootname for the Gnuplot-script and, for file terminals, the output image file (default = the value of the HEAD argument)
-w_dw WITH --- Gnuplot's "with" plot specification for the 'other' spin-down PDOS
-w_mol WITH --- Gnuplot's "with" plot specification for the 'molecular' PDOS
-w_mol_dw WITH --- Gnuplot's "with" plot specification for the 'molecular' spin-down PDOS
-fc FILLCOLOR --- fill color for the 'other' *DOS filledcurve (e.g. -fc {lt 1} or -fc {fc "cyan"})
-fc_dw FILLCOLOR --- fill color for the 'other' spin-down *DOS filledcurve
-fc_mol FILLCOLOR --- fill color for the 'molecular' *DOS filledcurve
-fc_mol_dw FILLCOLOR --- fill color for the 'molecular' spin-down *DOS filledcurve

For other PLOTTING OPTIONS, see ::pwtk::plot

DESCRIPTION

The workflow's sequence of jobs is:

      pw.x SCF (optional, requested by -scf)
       |
      pw.x NSCF (optional, requested by -nscf)
       |
      projwfc.x
       |
       +-- pw.x SCF (molecule only)
       |
       +-- projwfc.x (molecule only)
       |
      moleculardos.x
       |
      PLOTTING

This workflow makes two plots:

PDOS plot with projections to 'molecule' and to the rest of the structure (nicknamed as 'other')
MOPDOS plot with projections to molecular orbitals

DEFAULTS

PDOS is plotted above MOPDOS (to revert the order, use the -top option).
MO projections to all molecular MOs are plotted; to project to a subset of MOs, use the -mo option
MOs are labeled as MO-1, MO-2...; to label MOs wrt HOMO, use the -homo option (in this case, MOs will be labeled as ...HOMO-1, HOMO, LUMO, LUMO+1...).
MO projections are plotted in ascending order from top to bottom, i.e., low MOs at the top, high MOs at the bottom (use the -descend option to revert the order).
For 'molecular' PDOS, all atoms specified by MOLATOMS are used, and for 'other' "all - MOLATOMS" atoms are used. To use a subset of the corresponding atoms, use the -molatoms and -otheratoms options.

EXAMPLE

   load_fromPWI scf.CO-Pt111.in

   set inp { ngauss = 0, degauss = 0.01, DeltaE  = 0.05 }
   PROJWFC $inp
   MOPDOS  $inp

   mopdos_run -scf -nscf {8 8 8} -t png  $head

RETURN VALUE

Filename of the created MOPDOS plots (for file terminals) or the empty string (for window terminals).

SOURCE

    printTitle MOPDOS_RUN "Running the MOPDOS workflow"
    print "Workflow options & arguments :  $args\n" 

    # parse command-line options & arguments
    
    mopdosParseOpts_

    print "Calculating projections onto selected molecular orbitals\nusing pw.x, projwfc.x, and molecularpdos.x codes"
    print $molInfo
    
    # calculate

    input_pushpop {        
        input_clear IONS CELL
        printTitle "Performing calculations of the whole structure"
        
        # SCF + NSCF & fetch Efermi
        SCF_NSCF_
        Efermi_

        # projwfc.x
        print PROJWFC "Performing projwfc.x calculation\n"
        set full_xml [PROJWFC_xml_ $head $opt(emin) $opt(emax) $Efermi]
        
        # calculate a molecule
        input_pushpop {
            printTitle "Performing calculations of the '$mol' fragment (aka molecule)"
            print SCF "Performing SCF pw.x calculation of the '$mol' fragment\n"
            
            CONTROL " calculation = 'scf', prefix = '$fragment' "
            ::pwtk::pwi::deleteAtoms $other_atoms
            runPW pw.$fragment.scf.in

            print PROJWFC "Performing projwfc.x calculation of the '$mol' fragment\n"
            # N.B. set prefix explicitly
            #      (otherwise the prefix of the whole structure would be used)
            PROJWFC " prefix = '$fragment' "
            set mol_xml [PROJWFC_xml_ $fragment]
        }
        
        # molecularpdos.x
        
        printTitle "Performing molecularpdos.x calculation"

        MOPDOS [subst {
            xmlfile_full = '$full_xml'
            xmlfile_part = '$mol_xml'
            fileout      = '$head.proj_to_$mol'
        }]
        if { $opt(emin) ne {} } { MOPDOS " Emin = $opt(emin)+$Efermi " }
        if { $opt(emax) ne {} } { MOPDOS " Emax = $opt(emax)+$Efermi " }
        
        # i_atmwfc_beg_full & i_atmwfc_end_full
        
        lassign [infoFromPRO_ $mol_atoms projwfc.$head.out] i_beg i_end
        
        print "Finding the first and last molecular states from projwfc.$head.out:
   * i_atmwfc_beg_full = $i_beg
   * i_atmwfc_end_full = $i_end\n"
        
        MOPDOS [subst {
            i_atmwfc_beg_full = $i_beg
            i_atmwfc_end_full = $i_end
        }]
        
        runMOLECULARPDOS molecularpdos.$head.in
    }
    printTitle "Projecting DOS"
    
    return [mopdosPlot_]
}

TABLE OF CONTENTS

::pwtk::mopdos_run