ABINIT/m_kpts [ Modules ]

Copyright (C) 2008-2018 ABINIT group (XG, MG, MJV, DRH, DCA, JCC, MM)
This file is distributed under the terms of the
GNU General Public License, see ~abinit/COPYING
or http://www.gnu.org/copyleft/gpl.txt .

m_kpts/getkgrid [ Functions ]

Compute the grid of k points in the irreducible Brillouin zone.
Note that nkpt (and nkpthf) can be computed by calling this routine with nkpt=0, provided that kptopt/=0.
If downsampling is present, also compute a downsampled k grid.

INPUTS

chksymbreak= if 1, will check whether the k point grid is symmetric (for kptopt=1,2 and 4), and stop if not.
iout=unit number for echoed output . 0 if no output is wished.
iscf= ( <= 0 =>non-SCF), >0 => SCF) MG: FIXME I don't understand why we have to pass the value iscf.
kptopt=option for the generation of k points
(defines whether spatial symmetries and/or time-reversal can be used)
msym=default maximal number of symmetries
nsym=number of symmetries
rprimd(3,3)=dimensional real space primitive translations (bohr)
symafm(nsym)=(anti)ferromagnetic part of symmetry operations
symrel(3,3,nsym)=symmetry operations in real space in terms of primitive translations
vacuum(3)=for each direction, 0 if no vacuum, 1 if vacuum
[downsampling(3) = input variable that governs the downsampling]

OUTPUT

kptrlen=length of the smallest real space supercell vector associated with the lattice of k points.
nkpt_computed=number of k-points in the IBZ computed in the present routine
If nkpt/=0 the following are also output :
kpt(3,nkpt)=reduced coordinates of k points.
wtk(nkpt)=weight assigned to each k point.
[fullbz(3,nkpt_fullbz)]=k-points generated in the full Brillouin zone.
In output: allocated array with the list of k-points in the BZ.
[kpthf(3,nkpthf)]=k-points generated in the full Brillouin zone, possibly downsampled (for Fock).

NOTES

msym not needed since nsym is the last index.

SIDE EFFECTS

Input/Output
nkpt=number of k points (might be zero, see output description)
kptrlatt(3,3)=k-point lattice specification
nshiftk=actual number of k-point shifts in shiftk
shiftk(3,210)=shift vectors for k point generation
[nkpthf = number of k points in the full BZ, for the Fock operator]

m_kpts/kpts_ibz_from_kptrlatt [ Functions ]

Determines the irreducible wedge, the corresponding weights and the list
of k-points in the Brillouin Zone starting from kptrlatt and the set shifts.

INPUTS

cryst<crystal_t> = crystalline structure with info on symmetries and time-reversal.
kptopt=option for the generation of k points
(defines whether spatical symmetries and/or time-reversal can be used)
kptrlatt(3,3)=integer coordinates of the primitive vectors of the
lattice reciprocal to the k point lattice to be generated here
If diagonal, the three values are the Monkhorst-Pack usual values, in case of simple cubic.
nshiftk= number of shift vectors in the repeated cell
shiftk(3,nshiftk) = vectors that will be used to determine the shifts from (0. 0. 0.).

OUTPUT

nkibz,nkbz = Number of points in IBZ and BZ, respectively.
The following arrays are allocated and returned by the routine:
kibz(3,nkibz) = k-points in the IBZ.
wtk(nkibz) = weights of the k-points in the IBZ (normalized to one).
kbz(3,nkbz) = k-points in the BZ.
[new_kptrlatt] = New value of kptrlatt returned by getkgrid
[new_shiftk(3,new_nshiftk)] = New set of shifts returned by getkgrid

m_kpts/listkk [ Functions ]

Given a list of nkpt1 initial k points kptns1 and a list of nkpt2
final k points kptns2, associates each final k pt with a "closest"
initial k point (or symmetric thereof, also taking possible umklapp)
as determined by a metric gmet, that commutes with the symmetry operations.
The algorithm does not scale as nkpt1 times nkpt2, thanks
to the ordering of the kptns1 and kptns2 vectors according to their
lengths, and comparison first between vectors of similar lengths.
Returns indirect indexing list indkk.

INPUTS

gmet(3,3)=reciprocal spacemetric (bohr^-2)
kptns1(3,nkpt1)=list of initial k points (reduced coordinates)
kptns2(3,nkpt2)=list of final k points
nkpt1=number of initial k points
nkpt2=number of final k points
nsym=number of symmetry elements in space group
sppoldbl=if 1, no spin-polarisation doubling
if 2, spin-polarisation doubling using symafm
symafm(nsym)=(anti)ferromagnetic part of symmetry operations
symmat(3,3,nsym)=symmetry operations (symrel or symrec, depending on
value of use_symrec
timrev=1 if the use of time-reversal is allowed; 0 otherwise
use_symrec: if present and true, symmat assumed to be symrec, otherwise assumed to be symrel (default)

OUTPUT

dksqmax=maximal value of the norm**2 of the difference between
a kpt2 vector and the closest k-point found from the kptns1 set, using symmetries.
indkk(nkpt2*sppoldbl,6)=describe k point number of kpt1 that allows to
generate wavefunctions closest to given kpt2
if sppoldbl=2, use symafm to generate spin down wfs from spin up wfs
indkk(:,1)=k point number of kptns1
indkk(:,2)=symmetry operation to be applied to kpt1, to give kpt1a
(if 0, means no symmetry operation, equivalent to identity )
indkk(:,3:5)=shift in reciprocal space to be given to kpt1a,
to give kpt1b, that is the closest to kpt2.
indkk(:,6)=1 if time-reversal was used to generate kpt1a from kpt1, 0 otherwise

NOTES

The tolerances tol12 and tol8 aims at giving a machine-independent ordering.
(this trick is used in bonds.f, listkk.f, prtrhomxmn.f and rsiaf9.f)
The tolerance tol12 is used for each component of the k vectors,
and for the length of the vectors
while the tolerance tol8 is used for the comparison of the squared lengths
of the separate vectors.

m_kpts/mknormpath [ Functions ]

Please do not use this routine, use make_normpath instead.
mknormpath should be removed
This simple routine generates a normalized path that can be used to plot a band
structures in an easy way. For normalized path we mean a path where the number
of division on each segment is proportional to the length of the segment itself.
To generate the above mentioned path, the subroutine must be called twice.
The first call reports the total number of divisions in the normalized path, dimension
that is required to correctly allocate the array.
The second call calculates the reduced coordinates of the circuit.

nbounds=number of points defining the path
ndiv_small=number of points to be used to sample the smallest
segment defined by bounds(:,1:nbounds)
bounds(3,nbounds)=points defining the path
gmet(3,3)=metric

OUTPUT

ndiv(nbounds-1)= number of divisions for each segment
npt_tot=total number of points sampled along the circuit
path(3,npt_tot)= normalized path in reciprocal space

m_kpts/smpbz [ Functions ]

Generate a set of special k (or q) points which samples in a homogeneous way
the entire Brillouin zone of a simple lattice, face-centered cubic,
body-centered lattice and hexagonal lattice.
If kptrlatt is diagonal, the algorithm used here reduces to the usual
Monkhorst-Pack set of k points.

INPUTS

brav = 1 or -1 -> simple lattice; 2 -> face-centered cubic;
3 -> body-centered lattice; 4 -> hexagonal lattice (D6h)
downsampling(3) [optional, for brav=1 only]
Three integer numbers, describing the downsampling of the k grid
If present, in any case, only the first shiftk is taken into account
The absolute value of one number gives, for the corresponding k-coordinate, the factor of decrease of the sampling
If zero, only one point is used to sample along this direction
The sign has also a meaning :
- if three numbers are negative, perform a face-centered sampling
- if two numbers are negative, perform a body-centered sampling
- if one number is negative, perform a face-centered sampling for the two-dimensional lattice of the other directions
- if one number is zero and at least one number is negative, perform face-centered sampling for the non-zero directions.
iout = unit number for output
kptrlatt(3,3)=integer coordinates of the primitive vectors of the
lattice reciprocal to the k point lattice to be generated here
If diagonal, the three values are the Monkhorst-Pack usual values, in case of simple cubic.
mkpt = maximum number of k points
nshiftk= number of shift vectors in the repeated cell
option= Flag defining what will be printed of iout: 0 for k points, anything else for q points.
Also, for q points, if the Gamma point is present, place it first in the list.
shiftk(3,nshiftk) = vectors that will be used to determine the shifts from (0. 0. 0.).

OUTPUT

nkpt = number of k points
spkpt(3,mkpt) = the nkpt first values contain the special k points
obtained by the Monkhorst & Pack method, in reduced coordinates.
These vectors have to be multiplied by the reciprocal basis vectors
gprimd(3,3) (in cartesian coordinates) to obtain the special k points
set in cartesian coordinates.

m_kpts/symkchk [ Functions ]

Checks that the set of k points chosen for a response function
calculation has the full space group symmetry, modulo time reversal if appropriate.
Returns ierr/=0 with error message if not satisfied
Currently used only when strain perturbation is treated. Based on symkpt.

INPUTS

kptns(3,nkpt)= k vectors in reciprocal space
nkpt = number of k-points whose weights are wtk
nsym=number of space group symmetries
symrec(3,3,nsym)=3x3 matrices of the group symmetries (reciprocal space)
timrev: if 1, the time reversal operation has to be taken into account
if 0, no time reversal symmetry.

OUTPUT

msg=Error message if ierr /= 0

TODO

This version should scale badly with the number of k-points. Replace loops with listkk

m_kpts/testkgrid [ Functions ]

Test different grids of k points. The algorithm used is based on the idea of testing different
one-dimensional sets of possible k point grids. It is not exhaustive (other families could be included),
but should do a respectable job in all cases. The Monkhorst-Pack set of grids (defined with respect to
symmetry axes, and not primitive axes) is always tested.

INPUTS

bravais(11): bravais(1)=iholohedry
bravais(2)=center
bravais(3:11)=coordinates of rprim in the axes of the conventional bravais lattice (*2 if center/=0)
iout=unit number for echoed output
msym=default maximal number of symmetries
nsym=number of symetries
prtkpt=if non-zero, will write the characteristics of k grids, then stop
rprimd(3,3)=dimensional real space primitive translations (bohr)
symafm(nsym)=(anti)ferromagnetic part of symmetry operations
symrel(3,3,nsym)=symmetry operations in real space in terms of primitive translations
vacuum(3)=for each direction, 0 if no vacuum, 1 if vacuum

OUTPUT

kptrlatt(3,3)=k-point lattice specification
nshiftk=number of k-point shifts in shiftk (always 1 from this routine)
shiftk(3,210)=shift vectors for k point generation

SIDE EFFECTS

kptrlen=length of the smallest real space supercell vector associated with the lattice of k points.

NOTES

Note that nkpt can be computed by calling this routine with input value nkpt=0
Note that kptopt is always =1 in this routine.

m_kpts/tetra_from_kptrlatt [ Functions ]

cryst<cryst_t>=Crystalline structure.
kptopt=Option for the k-point generation.
kptrlatt(3,3)=k-point lattice specification
nshiftk= number of shift vectors.
shiftk(3,nshiftk)=shift vectors for k point generation
nkibz=Number of points in the IBZ
kibz(3,nkibz)=Reduced coordinates of the k-points in the IBZ.