bands.tcl

::pwtk::bands_run

::pwtk::bands_run

SYNOPSIS

proc ::pwtk::bands_run {args} {

PURPOSE

A configurable workflow for calculating and plotting spaghetti BANDS, and if requested, total DOS alongside spaghetti.

USAGE

   ::pwtk::bands_run ?SPECIFIC-OPTIONS?  ?PLOTTING-OPTIONS?  HEAD  UNIT  NKTOT  KPATH_SPECS  ?KPATH_SPECS?  ...

   where SPECIFIC-OPTIONS are:

       -scf
       -nscf KGRID
       -preserve
       -gap
       -dos
       -intdos
       -dd  DOS_SIZE
       -e   EFERMI
       -emin EMIN
       -emax EMAX
    
  PLOTTING-OPTIONS:

       -out   ROOTNAME
       -w     WITH
       -w_dw  WITH
       -dw    DOS_WITH
       -dw_dw DOS_WITH
       -fc    DOS_FILL_COLOR
       -fc_dw DOS_FILL_COLOR
       -iw    WITH
       -itc   INTDOS_TEXTCOLOR

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

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

DESCRIPTION

A workflow for calculating and plotting the spaghetti band structure plot, and optionally total DOS alongside spaghetti. The sequence of calculations is:

      pw.x SCF (optional, requested by -scf)
       |
       +--> for -gap if needed: pw.x fixed-occupations SCF
      (|)                        |
       +<---------------------- pw.x fixed-occupations NSCF
       |
      pw.x NSCF (optional, requested by -nscf KGRID)
       |
      dos.x (optional, requested by -dos or -intdos)
       |
      pw.x BANDS
       |
      bands.x
       |
      PLOTTING

SPECIFIC OPTIONS

-scf --- perform an SCF pw.x calculation (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 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)
-gap --- report the band gap using the combination of fixed-occupations (N)SCF and 'bands' pw.x calculations; if the input-data correpond to smearing occupations, PWTK additionally performs the fixed-occupations SCF and for -nscf also fixed-occupations NSCF pw.x calculations, ensuring that pw.x prints the line: "highest occupied, lowest unoccupied level (ev): ...."; BEWARE: do not apply this option for metals
-preserve --- preserve the 'outdir'; pw.x 'bands' calculation "corrupts" the outdir, and this options requests the 'outdir' to be preserved by using the copy of 'outdir' for 'bands' calculations
-dos --- calculate and plot also total DOS using dos.x
-intdos --- for -dos, plot also integrated DOS; implies -dos
-dd DOS_SIZE --- relative size of the DOS plot (default = 0.25)
-e EFERMI --- Fermi energy (either a floating-point number or a pw.x output file from where the Fermi energy is taken)
-emin EMIN --- (used only for -dos) the minimum-energy with respect to Fermi energy (in eV) to be used for dos.x, i.e., Emin of dos.x is set to: Emin = EMIN + Efermi
-emax EMAX --- (used only for -dos) the maximum-energy with respect to Fermi energy (in eV) to be used for dos.x, i.e., Emax of dos.x is set to: Emax = EMAX + Efermi

PLOTTING OPTIONS:

-out ROOTNAME --- rootname for the Gnuplot-script and, for file terminals, the output image file (default = the value of the HEAD argument)
-w WITH --- Gnuplot's "with" plot specs for the DOS

* -w_dw WITH --- Gnuplot's "with" plot specs for spin-down bands (the -w option is used for the spin-up analogue) * -dw DOS_WITH --- Gnuplot's "with" plot specification for DOS * -dw_dw DOS_WITH --- Gnuplot's "with" plot specification for spin-down DOS * -fc DOS_FILL_COLOR --- fill color for the DOS filledcurve (e.g. -fc {lt 1} or -fc {fc "cyan"}) * -fc_dw DOS_FILL_COLOR --- fill color for the spin-down DOS filledcurve * -iw WITH --- Gnuplot's "with" plot specs for the Integrated DOS * -itc TEXTCOLOR --- textcolor of Integrated DOS label and y2tics

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

ARGUMENTS

HEAD --- the rootname for files, which will be named as prefix.HEAD.postfix
UNIT --- units in which the k-points are specified (tbipa* or crystal*, i.e., tpiba_b is here synonymous with tpiba and likewise for crystal_b)
NKTOT --- total number of k-points uniformly distributed along the k-path
KPATH_SPECS --- one or more spaghetti continuous k-path specs. More than one KPATH_SPECS arguments are used when the k-path is discontinuous. Each KPATH_SPECS is specified as:

          kx(1) ky(1) kz(1) ?label(1)?  ... coordinates and label of the 1st special k-point (label is optional)
          kx(2) ky(2) kz(2) ?label(2)?  ... coordinates and label of the 2nd special k-point (label is optional)
          ...
          kx(n) ky(n) kz(n) ?label(n)?  ... coordinates and label of the Nth special k-point (label is optional)

BEWARE

This workflow performs BANDS pw.x calculation, implying that an SCF (or *relax) pw.x calculation must be performed prior to using this workflow, unless the -scf option is specified, which performs such an SCF calculation.

EXAMPLE

   # plot a spaghetti band-structure for Si-bulk

   load_fromPWI scf.Si-bulk.in

   bands_run -scf -t png  Si-bulk  crystal 100 {
      0.00     0.500     0.000     L
      0.00     0.000     0.000     Γ
      0.50     0.500     0.000     X
      0.25     0.500    -0.250     W
      0.00     0.375    -0.375     K
      0.00     0.500     0.000     L
   } {
      0.00     0.000     0.000     Γ
      0.625    0.375     0.000     U
   }

   # plot DOS alongside BANDS spaghetti plot with the -dos option

   DOS { DeltaE = 0.03  bz_sum = 'tetrahedra' }
   
   bands_run -scf -nscf {8 8 8} -dos -t png  Si-bulk  crystal 100 {
      0.00     0.500     0.000     L
      0.00     0.000     0.000     Γ
      0.50     0.500     0.000     X
      0.25     0.500    -0.250     W
      0.00     0.375    -0.375     K
      0.00     0.500     0.000     L
   }

RETURN VALUE

Filename of the created spaghetti plot (for file terminals) or the empty string (for window terminals).

SOURCE

    set mode run

    printTitle BANDS_RUN "Running the BANDS workflow"
    print "Workflow options & arguments :  $args\n"
    
    # parse & check

    bandsParseOpts_
    bandsCheckUnit_
    bandsParseKSpecs_
    set n_kpath_specs [llength $args]
    
    if { ! [::pwtk::type::number posint -strict $nktot] } {
        ::pwtk::error "expected positive integer for the total number of k-points (NKTOT), but got \"$nktot\"" 1
    }
    
    # printout
    
    print "Rootname for I/O files:  $head

Requested total number of k-points     :   $nktot
Number of special k-points             :   $nk
Special k-points specified in units    :   $unit
Number of discontinuities in the k-path:   [expr $n_kpath_specs - 1]\n"

    if { $opt(dos) } {
        print "In addition to BANDS, DOS plot was also requested\n"
    }

    # no 'tetrahedra*' & 'from_input' for BANDS
    #
    # N.B. this is very restrictive, but it is safer (if the user wants
    # to plot DOS with tetrahedra, bz_sum = 'tetrahedra' can be used)
    
    set occ [::pwtk::input::namelistGetVarValue SYSTEM -nocase occupations trim]
    if { [regexp {tetrahedra|from_input} $occ] } {
        ::pwtk::error "occupations = '$occ' not compatible with calculation = 'bands'" 1
    }
    
    # calculate
    
    input_pushpop {
        input_clear IONS CELL

        # perform SCF + NSCF calcs & fetch Efermi
        SCF_NSCF_
        Efermi_

        # dos.x

        if { $opt(dos) } {
            dosCalc_
        }
        
        # spin-polarized ?

        set nspin [::pwtk::input::namelistGetVarValue SYSTEM -nocase nspin]
        set spin  [expr { [string is integer $nspin] && $nspin > 1 ? 1 : 0 }]

        # distribute k-points uniformly

        bandsDistributeK_

        # pw.x BANDS

        if { $opt(preserve) } {
            set outdir [outdir_backup bands]
            CONTROL [subst {
                calculation = 'bands'
                outdir = '$outdir'
            }]
        }

        ## N.B. this was moved up
        ## no 'tetrahedra' & 'from_input' for BANDS
        #set occ [::pwtk::input::namelistGetVarValue SYSTEM -nocase occupations trim]
        #if { $occ ne {} && $occ ne "smearing" } {
        #    infoMsg "occupations = '$occ' not compatible with calculation = 'bands';\ndisabling occupations"
        #    SYSTEM " occupations = "
        #    ifexist nbnd { SYSTEM " nbnd = $nbnd " }
        #}

        for {set ip 1} {$ip <= $npath} {incr ip} {
            if { $npath > 1 } {
                set name($ip) $head.$ip
                set part " (part-$ip/$npath)"
            } else {
                set name($ip) $head
                set part {}
            }
            print BANDS "Performing BANDS pw.x calculation$part\n"
            print "K-path specs:\n[join $kpath($ip) \n]\n"

            K_POINTS $unit $kpointCard($ip)
        
            runPW pw.$name($ip).bands

            # bands.x

            print BANDS "Performing bands.x calculation$part\n"
            if { ! $spin } {
                BANDS " filband = '$name($ip).dat' "; # N.B.: gnuplot file will be written to $name($ip).dat.gnu
                set bo($ip) [runBANDS bands.$name($ip)]
            } else {
                BANDS " filband = '$name($ip).up.dat'  spin_component = 1"
                set bo($ip.up) [runBANDS bands.$name($ip).up]
                
                BANDS " filband = '$name($ip).dw.dat'  spin_component = 2"
                set bo($ip.dw) [runBANDS bands.$name($ip).dw]
            }
        }
    }

    # report BANDS refined band gap
    bandsBandGap_
    
    # plot

    return [bandsPlot_]
}

TABLE OF CONTENTS

::pwtk::bands_run