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 postprocessing subprogram reads the band energies
stored in the pwscf.xml file after an SCF calculation on a uniform MonkhorstPack grid,
and interpolates the eigenvalues to an arbitrary set of kpoints 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. fourierdiff.dat for the fourierdiff method) that is plottable with Grace or Gnuplot
(e.g. xmgrace nxy fourierdiff.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: 
'fourierdiff'

The interpolation method to be used

Available options are:
 'fourierdiff' :
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, 253262 (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.
 'idwsphere' :
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.

miller_max 
INTEGER 
Default: 
6

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

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 == 'fourierdiff' 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 userdefined 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.

p_metric 
INTEGER 
Default: 
2

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

scale_sphere 
INTEGER 
Default: 
4.0d0

The search radius for method == 'idwsphere', is Rmin * scale_sphere, where Rmin is the
minimum distance found between the uniform grid of kpoints.
If scale_sphere is too small, some kpoints of the path might not see enough uniform grid points
to average energies, whereas for large values the method becomes equal to method == 'idw'.



Card: ROUGHNESS 
Optional card, used only if method == 'fourierdiff', or 'fourier', ignored otherwise!
This card can be used to change the roughness functional that is minimized
in the method == 'fourierdiff' and 'fourier'.
In case method == 'fourierdiff', or 'fourier' and card ROUGHNESS is not specified the default
roughness will be used with RoughN == 1 and RoughC(1) == 1.0d0.
Syntax:
ROUGHNESS

Description of items:
RoughN 
INTEGER 
Default: 
1

Number of terms included in the roughness functional

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.



Card: USER_STARS 
Optional card, used only if method == 'fourierdiff', or 'fourier', ignored otherwise !
Syntax:
USER_STARS

Description of items:
NUser 
INTEGER 
Default: 
0

Number of supplied additional Star vectors.

vec_x, vec_y, vec_z

REAL 
Additional userdefined 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
userdefined Star vectors.



Card: K_POINTS { tpiba_b } 

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 bandstructure plots.
See Doc/brillouin_zones.pdf for usage of BZ labels;
otherwise, kpoints are in units of 2 pi/a.
nks points specify nks1 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.

nks 
INTEGER 
Number of supplied special kpoints.

xk_x, xk_y, xk_z, wk

REAL 
Special kpoints (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 kpoints in the IBZ are provided in input



