# Input File Description

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

> ### TABLE OF CONTENTS

> > INTRODUCTION

> > &INTERPOLATION

> > > method | miller_max | check_periodicity | p_metric | scale_sphere

> > ROUGHNESS

> > > RoughN | RoughC

> > USER_STARS

> > > NUser | vec_x | vec_y | vec_z

> > K_POINTS

> > > nks | xk_x | xk_y | xk_z | wk

> ### INTRODUCTION

> >     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

method | CHARACTER
Default: | 'fourier-diff'

>      The interpolation method to be used

>      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.

[Back to Top]

miller_max | INTEGER
Default: | 6

>     The maximum Miller index used to automatically generate the set of symmetry inequivalent Star vectors
>                       (only for method == 'fourier-diff' or 'fourier')

[Back to Top]

check_periodicity | LOGICAL
Default: | .FALSE.

>     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.

[Back to Top]

p_metric | INTEGER
Default: | 2

>      The exponent of the distance in the IDW method ( only for method == 'idw' or 'idw-sphere')

[Back to Top]

scale_sphere | INTEGER
Default: | 4.0d0

>     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'.

[Back to Top]

## 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:

> RoughN | INTEGER
> Default: | 1

> >      Number of terms included in the roughness functional

> [Back to Top]

> RoughC | REAL
> Default: | 1.0d0

> >     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.

> [Back to Top]

## 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:

> NUser | INTEGER
> Default: | 0

> >      Number of supplied additional Star vectors.

> [Back to Top]

> vec_x, vec_y, vec_z | REAL

> >     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.

> [Back to Top]

## 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)

### Description of items:

> Card's options: | tpiba_b
> --- | ---
> Default: | none

> >     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.

> [Back to Top]

> nks | INTEGER

> >      Number of supplied special k-points.

> [Back to Top]

> xk_x, xk_y, xk_z, wk | REAL

> >     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

> [Back to Top]

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