pdos.tcl

::pwtk::pdos_multiplot

::pwtk::pdos_multiplot

SYNOPSIS

proc ::pwtk::pdos_multiplot {args} {

USAGE

   ::pwtk::pdos_multiplot  ?SPECIFIC-OPTIONS?  ?PLOTTING-OPTIONS?  PDOSFILE_ORBITAL_LLIST  ?HEAD?

   where SPECIFIC-OPTIONS are:

       -e  E_FERMI|PWO_FILE
       -o  ORIENT
       -nx NX
       -np NP

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

   A more detailed description of SPECIFIC-OPTIONS and ARGUMENTS is provided below.

DESCRIPTION

Visualize specified PDOS components as a "multiplot" with aid of Gnuplot.

SPECIFIC OPTIONS

-e EFERMI --- Fermi energy (either a floating-point number or a pw.x output file from where to grep the Fermi energy)
-o ORIENT --- page orientation for EPS (default = portrait); if -s is specified, this option is ignored
-nx NUMBER --- number of plots per row
-np NUMBER --- number of plots per page

PLOTTING OPTIONS

See ::pwtk::plot

ARGUMENTS

PDOSFILE_ORBITAL_LLIST -- list of lists of projwfc.x PDOS files and the corresponding orbital-expressions (see below)
HEAD -- (optional, default = multiplot-X, X = integer) rootname for the generated plot files: $HEAD.gp and, for file terminals, $HEAD.EXT, where EXT = image type

The structure of the PDOSFILE_ORBITAL_LLIST list-of-lists is the following:

    set PDOSFILE_ORBITAL_LLIST {
          { pdosFile1 orbitalExpression1
            pdosFile2 orbitalExpression2
            ...       ...
          }
          {
            pdosFileX orbitalExpressionX
            ...       ...
          }
          ...
    }

EXAMPLE

    set PDOSFILE_ORBITAL_LLIST {
        {
            pdosFile1 {pz + px - 2*pz}
            pdosFile2 {dxy + dxz + dyz - dx2-y2 - dz2}
        }
        {
            pdosFileX px
            pdosFileX py
            pdosFileX pz
         }
         {
            pdosFileW {px + py + pz}
         }
    }
    ::pwtk::pdos_multiplot $PDOSFILE_ORBITAL_LLIST pdos-example

For each list element in $PDOSFILE_ORBITAL_LLIST, a plot is generated. Hence, the number of generated plots is [llength $PDOSFILE_ORBITAL_LLIST]. For the above example, three PDOS plots are created. The 1st plot displays the PDOSes for pdosFile1 and pdosFile2, the 2nd plot displays the PDOSes for pdosFileX, pdosFileY, and pdosFileZ, etc.

THE SYNTAX OF ORBITAL EXPRESSIONS

Orbital expressions are simple mathematical expressions involving orbital labels, defined in the ::pwtk::obitalIndex array (i.e. ldos, s, px,py,pz, dxy,dxz,dxy,dx2y2,dz2), where ldos stands for the sum of all components present in the PDOS file. Here is an example of the orbital expression:

    s + 0.5*(px + py)

In addition to orbital labels, also group-orbitals can be used as defined in the ::pwtk::obitalGroup array. New group-orbitals can be defined with the ::pwtk::orbitalGroup command.

Note that options are optional and any number of them can be specified.

RETURN VALUE

Filename(s) of the created image(s) (for file terminals) or the empty string (for window terminals).

SOURCE

    set xdos PDOS
    set mode multi
    printTitle $xdos "Multiplot $xdos plotting"
    print "Options & arguments :  $args\n"

    # parse command-line options & initialize plotting
    set arguments "PDOSFILE_ORBITAL_LLIST  ?HEAD?"
    xdosParseOpts_initPlot_

    #
    # make a PDOS plot for each list element in $pdosLL
    #
    
    set ith 0
    set ipage 1
    foreach pdosL $pdosLL {
        set plot {}

        #
        # filledcurves
        #
        if { $dos_fill } {
            set lt 1
            foreach {pdos orbExpr} $pdosL {
                set kres [pdos_kresolved $pdos]
                set spin [pdos_spin $pdos]
                set Ei   [expr 1 + $kres]
                set using [gp_using_ $kres $spin $orbExpr up_i_]

                append plot "     '$pdos' u (\$$Ei-Efermi):(\$$Ei-Efermi <= 0.0 ? $using : 0/0) not w filledcurve y1=0.0 lt $lt, \\\n"
            
                if { $spin } {
                    set using [gp_using_ $kres $spin $orbExpr dw_i_]
                    append plot "     '$pdos' u (\$$Ei-Efermi):(\$$Ei-Efermi <= 0.0 ? -1*($using) : 0/0) not w filledcurve y1=0.0 lt $lt, \\\n"
                } 
                incr lt
            }
            append plot "    \\\n"
        }

        #
        # lines
        #   
        set lt 1
        foreach {pdos orbExpr} $pdosL {
            set kres [pdos_kresolved $pdos]
            set spin [pdos_spin $pdos]
            set Ei   [expr 1 + $kres]
            set using [gp_using_ $kres $spin $orbExpr up_i_]
            set orb   [regsub -all { +} $orbExpr {}]; # condensed orbital expression
            if { $lt > 1 } {
                append plot ", \\\n"
            }
            set title "$orb ($pdos)"
            append plot "     '$pdos' u (\$$Ei-Efermi):($using) t '$title' w l lt $lt lw 2"
            
            if { $spin } {
                set using [gp_using_ $kres $spin $orbExpr dw_i_]
                append plot ", \\
     '$pdos' u (\$$Ei-Efermi):(-1*($using)) not w l lt $lt lw 2"
            }
            incr lt
        }
        $gp plot $plot
    }

    return [::pwtk::gp::execDisplay_ $gp opt]
}

TABLE OF CONTENTS

::pwtk::pdos_multiplot