*** FILE AUTOMATICALLY CREATED: DO NOT EDIT, CHANGES WILL BE LOST ***

------------------------------------------------------------------------
INPUT FILE DESCRIPTION

Program: band_interpolation.x / PWscf / Quantum ESPRESSO (version: 7.2)
------------------------------------------------------------------------


Purpose of band_interpolation.x:
  This contains four band energies interpolation methods,
  to be advantageously (but not necessarly) used for EXX band structure computations.

  The PP/src/band_interpolation.x post-processing subprogram reads the band energies
  stored in the pwscf.xml file after an SCF calculation on a uniform Monkhorst-Pack grid,
  and interpolates the eigenvalues to an arbitrary set of k-points provided in input.

  The workflow is just:

        (1) do an SCF on a uniform grid
        (2) call the interpolator from the folder in which the pwscf.xml
             file is present (band_interpolation.x < input)

  For large EXX calculations the first step can be splitted in two substeps:

        (1) do an SCF calculation on a uniform grid with occupied bands only
        (2) do a NSCF (or Bands) calculation on the same uniform grid adding virtual orbitals
        (3) call the interpolator from the folder in which the pwscf.xml file is present

  Four interpolation methods have been included (see "method").

  The interpolated band structure in eV units is written in a file named [method].dat
  (e.g. fourier-diff.dat for the fourier-diff method) that is plottable with Grace or Gnuplot
  (e.g. xmgrace -nxy fourier-diff.dat)

Structure of the input data:
============================

   &INTERPOLATION
     ...
   /

   [ ROUGHNESS
        RoughN
        'automatic' or RoughC(1) RoughC(2) RoughC(3) ... RoughC(RoughN) ]

   [ USER_STARS
        NUser
        vec_X vec_Y vec_Z ]

   K_POINTS { tpiba_b }
      nks
      xk_x, xk_y, xk_z,  wk



========================================================================
NAMELIST: &INTERPOLATION

   +--------------------------------------------------------------------
   Variable:       method
   
   Type:           CHARACTER
   Default:        'fourier-diff'
   Description:    The interpolation method to be used
   Description:   
                   Available options are:
    
                   'fourier-diff' :
                        band energies, as functions of k, are expanded in reciprocal space using a Star function basis set
                        (algorithm from Pickett W. E., Krakauer H., Allen P. B., Phys. Rev. B, vol. 38, issue 4, page 2721, 1988,
                         https://link.aps.org/doi/10.1103/PhysRevB.38.2721 ).
                        WARNING: The pwscf.xml file must be generated with "nosym" == .false. .
    
                   'fourier' :
                        band energies, as functions of k, are expanded in reciprocal space using a Star function basis set
                        (algorithm from D. D. Koelling, J. H. Wood, J. Comput. Phys., 67, 253-262 (1986).
                         https://ui.adsabs.harvard.edu/abs/1986JCoPh..67..253K ).
                        WARNING: The pwscf.xml file must be generated with "nosym" == .false. .
    
                   'idw' :
                        inverse distance weighting interpolation with Shepard metric
                        (ACM 68: Proceedings of the 1968 23rd ACM national conference, January 1968, Pages 517–524,
                         https://doi.org/10.1145/800186.810616 ).
                        WARNING: The pwscf.xml file must be generated with "nosym" == .true. .
                        WARNING: This method is REALLY simple and provides only a very rough estimate of the band structure.
    
                   'idw-sphere' :
                        inverse distance weighting interpolation inside a sphere of given radius.
                        WARNING: The pwscf.xml file must be generated with "nosym" == .true. .
                        WARNING: This method is REALLY simple and provides only a very rough estimate of the band structure.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       miller_max
   
   Type:           INTEGER
   Default:        6
   Description:    The maximum Miller index used to automatically generate the set of symmetry inequivalent Star vectors
                                     (only for "method" == 'fourier-diff' or 'fourier')
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       check_periodicity
   
   Type:           LOGICAL
   Default:        .FALSE.
   Description:    If .TRUE. a (time consuming) step is performed, to check whether all the Star functions have
                                     the correct lattice periodicity (only for "method" == 'fourier-diff' or 'fourier') .
                   
                                     For automatically generated Star functions this should never occur by construction, and the program
                                     will stop and exit in case one Star function with wrong periodicity is found (useful for
                                     debugging and program sanity check).
                   
                                     If additional user-defined Star vectors are specified (see optional card "USER_STARS"),
                                     the program will print a WARNING in case one Star function with wrong periodicity is found.
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       p_metric
   
   Type:           INTEGER
   Default:        2
   Description:    The exponent of the distance in the IDW method ( only for "method" == 'idw' or 'idw-sphere')
   +--------------------------------------------------------------------
   
   +--------------------------------------------------------------------
   Variable:       scale_sphere
   
   Type:           INTEGER
   Default:        4.0d0
   Description:    The search radius for "method" == 'idw-sphere', is Rmin * scale_sphere, where Rmin is the
                                     minimum distance found between the uniform grid of k-points.
                   
                                     If scale_sphere is too small, some k-points of the path might not see enough uniform grid points
                                     to average energies, whereas for large values the method becomes equal to "method" == 'idw'.
   +--------------------------------------------------------------------
   
===END OF NAMELIST======================================================


========================================================================
CARD: ROUGHNESS 

   OPTIONAL CARD, USED ONLY IF "METHOD" == 'FOURIER-DIFF', OR 'FOURIER', IGNORED OTHERWISE!
   
   This card can be used to change the roughness functional that is minimized
                    in the "method" == 'fourier-diff' and 'fourier'.
                    In case "method" == 'fourier-diff', or 'fourier' and card ROUGHNESS is not specified the default
                    roughness will be used with "RoughN" == 1 and "RoughC"(1) == 1.0d0.
   
   /////////////////////////////////////////
   // Syntax:                             //
   /////////////////////////////////////////
   
      ROUGHNESS 
         RoughN
         RoughC(1)  RoughC(2)  . . .  RoughC(RoughN)  
   
   /////////////////////////////////////////
   
   DESCRIPTION OF ITEMS:
   
      +--------------------------------------------------------------------
      Variable:       RoughN
      
      Type:           INTEGER
      Default:        1
      Description:    Number of terms included in the roughness functional
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variables:      RoughC
      
      Type:           REAL
      Default:        1.0d0
      Description:    Coefficients for the terms included in the roughness functional.
                                                      They can be explicitely given or 'automatic' can be specified instead of numbers
                                                      to use default coefficients.
      +--------------------------------------------------------------------
      
===END OF CARD==========================================================


========================================================================
CARD: USER_STARS 

   OPTIONAL CARD, USED ONLY IF "METHOD" == 'FOURIER-DIFF', OR 'FOURIER', IGNORED OTHERWISE !
   
   /////////////////////////////////////////
   // Syntax:                             //
   /////////////////////////////////////////
   
      USER_STARS 
         NUser
         vec_x(1)      vec_y(1)      vec_z(1)      
         vec_x(2)      vec_y(2)      vec_z(2)      
         . . . 
         vec_x(NUser)  vec_y(NUser)  vec_z(NUser)  
   
   /////////////////////////////////////////
   
   DESCRIPTION OF ITEMS:
   
      +--------------------------------------------------------------------
      Variable:       NUser
      
      Type:           INTEGER
      Default:        0
      Description:    Number of supplied additional Star vectors.
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variables:      vec_x, vec_y, vec_z
      
      Type:           REAL
      Description:    Additional user-defined Star vectors that are added to the
                      automatically generated ones to augment the Star functions
                      basis set.
                      You might also want to check "check_periodicity" when providing
                      user-defined Star vectors.
      +--------------------------------------------------------------------
      
===END OF CARD==========================================================


========================================================================
CARD: K_POINTS { tpiba_b }

   ________________________________________________________________________
   * IF tpiba_b : 
   
      /////////////////////////////////////////
      // Syntax:                             //
      /////////////////////////////////////////
      
         K_POINTS  tpiba_b 
            nks
            xk_x(1)    xk_y(1)    xk_z(1)    wk(1)    
            xk_x(2)    xk_y(2)    xk_z(2)    wk(2)    
            . . . 
            xk_x(nks)  xk_y(nks)  xk_z(nks)  wk(nks)  
      
      /////////////////////////////////////////
      
       
   ENDIF
   ________________________________________________________________________
   
   DESCRIPTION OF ITEMS:
   
      +--------------------------------------------------------------------
      Card's flags:   { tpiba_b }
      
      Default:        none
      Description:   
                      All K_POINTS options other than tpiba_b have been disabled in the interpolation.
       
                      tpiba_b :
                           Used for band-structure plots.
                           See Doc/brillouin_zones.pdf for usage of BZ labels;
                           otherwise, k-points are in units of  2 pi/a.
                           nks points specify nks-1 lines in reciprocal space.
                           Every couple of points identifies the initial and
                           final point of a line. pw.x generates N intermediate
                           points of the line where N is the weight of the first point.
      +--------------------------------------------------------------------


      +--------------------------------------------------------------------
      Variable:       nks
      
      Type:           INTEGER
      Description:    Number of supplied special k-points.
      +--------------------------------------------------------------------
      
      +--------------------------------------------------------------------
      Variables:      xk_x, xk_y, xk_z, wk
      
      Type:           REAL
      Description:    Special k-points (xk_x/y/z) in the irreducible Brillouin Zone
                      (IBZ) of the lattice (with all symmetries) and weights (wk)
                      See the literature for lists of special points and
                      the corresponding weights.
                      
                      If the symmetry is lower than the full symmetry
                      of the lattice, additional points with appropriate
                      weights are generated. Notice that such procedure
                      assumes that ONLY k-points in the IBZ are provided in input
      +--------------------------------------------------------------------
      
===END OF CARD==========================================================


This file has been created by helpdoc utility on Sat Mar 18 15:50:15 CET 2023
