ABINIT/m_bz_mesh [ Modules ]

This module provides the definition of the kmesh_t structure gathering information
on the sampling of the Brillouin zone. It also contains useful tools to operate on k-points.
and the definition of the littlegroup_t data type. The littlegroup_t structure is used
to store tables and useful info on the set of k-points belonging
to the irreducible wedge defined by the symmetry properties
of the point group that preserve the external q-point.

One has to use a fixed ordering of the loops over nsym and time-reversal
when the full zone is reconstructed by symmetry starting from the IBZ.
This is especially important in systems with both time-reversal and
spatial inversion as the effect of the two operation in reciprocal
space is very similar the only difference being the possibly non-zero
fractional translation associated to the spatial inversion.
In the present implementation, the spatial inversion has the precedence
wrt time-reversal (i.e., do itim; do isym).
Note that this particular ordering should be used in any routine used to
symmetrize k-dependent quantities in the full BZ zone to avoid possible errors.
* This module is deprecated and should be used only in the GW/BSE part.
Some of the routines will be gradually moved to m_kpts

m_bz_mesh/find_qmesh [ Functions ]

Find the q-mesh defined as all the possible differences between k-points
Find the irreducible q-points using a special treatment for the Gamma point.
Then call setup_kmesh to initialize the Qmesh datatype

m_bz_mesh/get_bz_item [ Functions ]

Given the index of a point in the full BZ, this routine returns the index of the
symmetric image in the IBZ, the index of the symmetry operation symrec needed,
whether time-reversal has to be used.
Optionally the non-symmorphic phase and the umklapp vector is returned.

INPUTS

ikbz=The index of the required point in the BZ
Kmesh<kmesh_t>=Datatype gathering information on the k point sampling.

OUTPUT

kbz(3)=The k-point in the first BZ in reduced coordinated.
isym=Index of the symrec symmetry required to rotate ik_ibz onto ik_bz.
itim=2 is time-reversal has to be used, 1 otherwise
ik_ibz=The index of the corresponding symmetric point in the IBZ.
[ph_mkbzt]=The phase factor for non-symmorphic operations e^{-i 2 \pi k_IBZ \cdot R{^-1}t}=e{-i 2\pi k_BZ cdot t}
[umklp(3)]=The umklapp G0 vector such as kbz + G0 = (IS) k_ibz, where kbz is in the BZ.
[isirred]=.TRUE. if the k-point belongs to IBZ.

m_bz_mesh/get_ng0sh [ Functions ]

Given two lists of k-points, kbz1 and kbz2, calculate any possible difference k1-k2.
For each difference, find the umklapp g0 vector and the point k3 in the array kfold
such as k1-k2 = k3 + G0.
The optimal value of G0 shells is returned, namely the smallest box around Gamma
which suffices to treat all possible umklapp processes.
The search algorithm uses bisection to process to scale in nk1*nk2*log(nkfold)

INPUTS

nk1, nk2=Number of points in the arrays kbz1, kbz2.
kbz1(3,nk1)=Reduced coordinates of the first set of points.
kbz2(3,nk2)=Reduced coordinates of the second set of points.
nkfold=Number of points in the array kfold.
kfold(3,nkfol)=Reduced coordinated of the points in the BZ.
tolq0=Tolerance below which a q-point is treated as zero.

OUTPUT

opt_ng0(3)=Minimal reduced components of the G0 vectors to account for umklapps.

m_bz_mesh/identk [ Functions ]

Identify k-points in the whole BZ starting from the IBZ.
Generate also symmetry tables relating the BZ to the IBZ.

INPUTS

kibz(3,nkibz)=Coordinates of k-points in the IBZ.
nkibz=Number of k points in IBZ.
nkbzmx=Maximum number of k points in BZ.
nsym=Number of symmetry operations.
timrev=2 if time reversal symmetry can be used; 1 otherwise.
symrec(3,3,nsym)=Symmetry operation matrices in reciprocal space.
symafm(nsym)=(anti)ferromagnetic part of symmetry operations.
[ref_bz(:,:)]= Reference set of points in the full Brillouin zone.

OUTPUT

kbz(3,nkbzmx)= k-points in whole BZ
ktab(nkbzmx)= table giving for each k-point in the BZ (array kbz),
the corresponding irreducible point in the array (kibz)
k_BZ= (IS) kIBZ where S is one of the symrec operations and I is the inversion or the identity
where k_BZ = (IS) k_IBZ and S = \transpose R^{-1}
ktabi(nkbzmx)= for each k-point in the BZ defines whether inversion has to be
considered in the relation k_BZ=(IS) k_IBZ (1 => only S; -1 => -S)
ktabo(nkbzmx)= the symmetry operation S that takes k_IBZ to each k_BZ
nkbz= no. of k-points in the whole BZ
wtk(nkibz)= weight for each k-point in IBZ for symmetric quantities:
no. of distinct ks in whole BZ/(timrev*nsym)

NOTES

The logic of the routine relies on the assumption that kibz really represent an irreducible set.
If symmetrical points are present in the input list, indeed, some the output weights will turn out to be zero.
An initial check is done at the beginning of the routine to trap this possible error.

567 subroutine kmesh_free(Kmesh)
568 569 570 !This section has been created automatically by the script Abilint (TD).
571 !Do not modify the following lines by hand.
572 #undef ABI_FUNC
573 #define ABI_FUNC 'kmesh_free'
574 !End of the abilint section
575 576 implicit none
577 578 !Arguments ------------------------------------
579 !scalars
580 type(kmesh_t),intent(inout) :: Kmesh
581 582 ! *********************************************************************
583 584 !@kmesh_t585 !integer
586 if (allocated(Kmesh%rottb)) then
587 ABI_FREE(Kmesh%rottb)
588 end if
589 if (allocated(Kmesh%rottbm1)) then
590 ABI_FREE(Kmesh%rottbm1)
591 end if
592 if (allocated(Kmesh%tab)) then
593 ABI_FREE(Kmesh%tab)
594 end if
595 if (allocated(Kmesh%tabi)) then
596 ABI_FREE(Kmesh%tabi)
597 end if
598 if (allocated(Kmesh%tabo)) then
599 ABI_FREE(Kmesh%tabo)
600 end if
601 if (allocated(Kmesh%umklp)) then
602 ABI_FREE(Kmesh%umklp)
603 end if
604 605 !real
606 if (allocated(Kmesh%ibz)) then
607 ABI_FREE(Kmesh%ibz)
608 end if
609 if (allocated(Kmesh%bz)) then
610 ABI_FREE(Kmesh%bz)
611 end if
612 if (allocated(Kmesh%shift)) then
613 ABI_FREE(Kmesh%shift)
614 end if
615 if (allocated(Kmesh%wt)) then
616 ABI_FREE(Kmesh%wt)
617 end if
618 619 !complex
620 if (allocated(Kmesh%tabp)) then
621 ABI_FREE(Kmesh%tabp)
622 end if
623 624 end subroutine kmesh_free

m_bz_mesh/kmesh_init [ Functions ]

Initialize and construct a kmesh_t datatype
gathering information on the mesh in the Brilloin zone.

INPUTS

nkibz=Number of irreducible k-points.
kibz(3,nkibz)=Irreducible k-points in reduced coordinates.
Cryst<crystal_t> = Info on unit cell and its symmetries
%nsym=number of symmetry operations
%symrec(3,3,nsym)=symmetry operations in reciprocal space
%tnons(3,nsym)=fractional translations
kptopt=option for the generation of k points (see input variable description)
[wrap_1zone]=If .TRUE., the points are wrapped in in the first BZ. Defaults to .FALSE. to preserve GW implementation.
[ref_bz(:,:)]= Reference set of points in the full Brillouin zone used to prune k-points.

OUTPUT

Kmesh<kmesh_t>=Datatype gathering information on the k point sampling.

m_bz_mesh/kmesh_t [ Types ]

The kmesh_t structured datatype contains different information on the grid used to sample the BZ :
the k-points in the full Brillouin zone BZ, the irreducible wedge IBZ as well as tables describing
the symmetry relationship between the points.

SOURCE

84 type,public :: kmesh_t 85 86 !scalars
87 integer :: nshift=0
88 89 integer :: nbz=0
90 ! Number of points in the BZ.
91 92 integer :: nibz=0
93 ! Number of points in the IBZ.
94 95 integer :: nsym
96 ! Number of symmetry operations.
97 98 integer :: kptopt
99 ! kptopt=option for the generation of k points (see input variable description)
100 !
101 ! 1 if both time-reversal and point group symmetries are used.
102 ! 2 if only time-reversal symmetry is used.
103 ! 3 do not take into account any symmetry (except the identity).
104 ! 4 if time-reversal is not used (spin-orbit coupling).
105 ! <0 number of segments used to construct the k-path for NSCF calculation.
106 107 integer :: timrev
108 ! 2 if time reversal symmetry can be used, 1 otherwise.
109 110 !arrays
111 integer :: kptrlatt(3,3) = NONE_KPTRLATT
112 ! Coordinates of three vectors in real space, expressed in reduced coordinates.
113 ! They define a super-lattice in real space. The k point lattice is the reciprocal of
114 ! this super-lattice, eventually shifted by shift.
115 ! Not available if the structure is initialized from the points in the IBZ.
116 117 integer,allocatable :: rottb(:,:,:)
118 ! rottb(nbz,timrev,nsym),
119 ! Index of (IS)k in the BZ array where S is a sym operation in reciprocal space,
120 ! I is the identity or the inversion operator (1,2 resp)
121 122 integer,allocatable :: rottbm1(:,:,:)
123 ! rottbm1(nbz,timrev,nsym)
124 ! Index of IS^{-1} k in the BZ array.
125 126 integer,allocatable :: tab(:)
127 ! tab(nbz)
128 ! For each point in the BZ, it gives the index of the symmetric irreducible point in the array ibz.
129 130 integer,allocatable :: tabi(:)
131 ! tabi(nbz)
132 ! For each point in the BZ, tabi tells whether time-reversal has to be
133 ! used to obtain k_BZ starting from the corresponding point in the IBZ (1=>no, -1=>yes)
134 135 integer,allocatable :: tabo(:)
136 ! tabo(nbz)
137 ! For each point in the BZ, it gives the index in the array symrec of the
138 ! symmetry operation in reciprocal space which rotates k_IBZ onto \pm k_BZ (depending on tabi)
139 140 integer,allocatable :: umklp(:,:)
141 ! umklp(3,nbz)
142 ! The Umklapp G0-vector such as kbz + G0 = (IS) k_ibz, where kbz is in the first BZ.
143 144 real(dp) :: gmet(3,3)
145 ! Reciprocal spacemetric ($\textrm{bohr}^{-2}$).
146 147 real(dp) :: gprimd(3,3)
148 ! Dimensional primitive translations for reciprocal space ($\textrm{bohr}^{-1}$)
149 150 real(dp),allocatable :: bz(:,:)
151 ! bz(3,nbz)
152 ! Points in the BZ in reduced coordinates.
153 ! TODO should packed in shells.
154 155 real(dp),allocatable :: ibz(:,:)
156 ! ibz(3,nibz)
157 ! Points in the IBZ in reduced coordinates.
158 159 real(dp),allocatable :: shift(:,:)
160 ! shift(3,nshift)
161 ! Shift for k-points, not available is nshift=0. Usually nshift=1
162 163 real(dp),allocatable :: wt(:)
164 ! wt(nibz)
165 ! Weights for each point in the IBZ.
166 167 !%real(dp),allocatable :: vbox(:)
168 ! vbox(nkbz)
169 ! Volume of the small box centered on the k-point in the full BZ.
170 ! Mainly used for inhomogeneous meshes.
171 172 complex(dpc),allocatable :: tabp(:)
173 ! tabp(nkbz)
174 ! For each point in the BZ, this table gives the phase factors associated
175 ! to non-symmorphic operations, i.e., e^{-i2\pi k_IBZ.R{^-1}t}=e^{-i2\pi k_BZ cdot t}
176 ! where \transpose R{-1}=S and (S k_IBZ)=\pm k_BZ (depending on tabi)
177 178 end type kmesh_t179 180 public :: kmesh_init ! Main creation method.
181 public :: kmesh_free ! Free memory182 public :: kmesh_print ! Printout of basic info on the object.
183 public :: get_bz_item ! Get point in the BZ as well as useful quantities.
184 public :: get_IBZ_item ! Get point in the IBZ as well as useful quantities.
185 public :: get_BZ_diff ! Get the difference k1-k2 in the BZ (if any).
186 public :: isamek ! Check whether two points are equal within an umklapp G0.
187 public :: isequalk ! Check whether two points are equal within an umklapp G0 (does not report G0)
188 public :: has_BZ_item ! Check if a point belongs to the BZ mesh.
189 public :: has_IBZ_item ! Check if a point is in the IBZ
190 public :: bz_mesh_isirred ! TRUE. if ikbz is in the IBZ (a non-zero umklapp is not allowed)
191 public :: make_mesh ! Initialize the mesh starting from kptrlatt and shift.
192 public :: identk ! Find the BZ starting from the irreducible k-points.
193 public :: get_ng0sh ! Calculate the smallest box in RSpace able to treat all possible umklapp processes.
194 public :: find_qmesh ! Find the Q-mesh defined as the set of all possible k1-k2 differences.
195 public :: findnq ! Helper routine returning the number of q-points.
196 public :: findq ! Helper routine returning the list of q-points.
197 public :: findqg0 ! Identify q + G0 = k1-k2.
198 public :: box_len ! Return the length of the vector connecting the origin with one the faces of the unit cell.

2947 subroutine littlegroup_free_0D(Ltg)
2948 2949 2950 !This section has been created automatically by the script Abilint (TD).
2951 !Do not modify the following lines by hand.
2952 #undef ABI_FUNC
2953 #define ABI_FUNC 'littlegroup_free_0D'
2954 !End of the abilint section
2955 2956 implicit none
2957 2958 !Arguments ------------------------------------
2959 !scalars
2960 type(littlegroup_t),intent(inout) :: Ltg
2961 2962 ! *********************************************************************
2963 2964 !@littlegroup_t2965 if (allocated(Ltg%g0)) then
2966 ABI_FREE(Ltg%g0)
2967 end if
2968 if (allocated(Ltg%ibzq)) then
2969 ABI_FREE(Ltg%ibzq)
2970 end if
2971 if (allocated(Ltg%bz2ibz)) then
2972 ABI_FREE(Ltg%bz2ibz)
2973 end if
2974 if (allocated(Ltg%ibz2bz)) then
2975 ABI_FREE(Ltg%ibz2bz)
2976 end if
2977 if (allocated(Ltg%igmG0)) then
2978 ABI_FREE(Ltg%igmG0)
2979 end if
2980 if (allocated(Ltg%flag_umklp)) then
2981 ABI_FREE(Ltg%flag_umklp)
2982 end if
2983 if (allocated(Ltg%preserve)) then
2984 ABI_FREE(Ltg%preserve)
2985 end if
2986 if (allocated(Ltg%tab)) then
2987 ABI_FREE(Ltg%tab)
2988 end if
2989 if (allocated(Ltg%tabo)) then
2990 ABI_FREE(Ltg%tabo)
2991 end if
2992 if (allocated(Ltg%tabi)) then
2993 ABI_FREE(Ltg%tabi)
2994 end if
2995 if (allocated(Ltg%wtksym)) then
2996 ABI_FREE(Ltg%wtksym)
2997 end if
2998 2999 end subroutine littlegroup_free_0D

m_bz_mesh/littlegroup_init [ Functions ]

Finds symmetry operations belonging to the little group associated to an external
point ext_pt and fills symmetry tables.

INPUTS

ext_pt(3)= External point in the Brillouin zone in reduce coordinated
Kmesh<kmesh_t>
%nbz=number of points in the full BZ
%kbz(3,nbz)=points in the full Brillouin Zon
Cryst<crystal_t>= Info on symmetries and unit cell
%symrec(3,3,nsym)=symmetry operations in reciprocal space
%nsym=number of symmetry operations in the space group
%timrev=if 2 time-reversal can be used; 1 otherwise
%gmet(3,3)=reciprocal spacemetric (bohr**-2).
npwvec=number of G vectors
gvec(3,npwvec) coordinates of G vectors
npwe=If greater than 0, the index of G-Go in the gvec(:,1:npwvec) array will be calculated
and stored in %igmG0 for each symmetry preserving the external q. Note that G is one of the npwe vectors.
use_umklp=flag to include umklapp G0 vectors in the definition of the little group (0:n0,1:yes)

OUTPUT

Ltg% <littlegroup_t_datatype>.
%ibzq(nbz)= 1 if the kpoint belongs to the IBZ defined by ext_pt, 0 otherwise
%bz2ibz(nbz)= sequential index of the point in the IBZ defined by ext_pt
%ibz2bz(nibz_Ltg) For each nibz_Ltg the correspondind index in the BZ array
%igmG0(npwepstimrev,nsym)= index of the uklapp vector G_o in the FFT array
%flag_umklp(timrev,nsym)= flag for umklapp processes
1 if operation (IS) requires a G_o to preserve ext_pt, 0 otherwise
%tab(nbz)=table giving, for each k-point in the BZ (kBZ), the corresponding
irreducible point (kIBZ) in the irreducible zone defined by the little group of ext_pt,
i.e kBZ= (IS) kIBZ where I is either the inversion or the identity and S is an
operation in the little group defined by ext_pt
%tabo(nbz)=the symmetry operation S in the little group that takes kIBZ to each kBZ
%tabi(nbz)= defines whether inversion has to be considered in the
relation kBZ=(IS) kIBZ (1 => only S; -1 => -S)
%preserve(2,nsym)= 1 if ISq=q, 0 otherwise, the first index is for the identity or the time reversal symmetry,
%wtksym(2,nsym,nbz)= for each kpoint is equal to 1 if the symmetry operation (with or without time reversal)
must be considered in the calculation of \chi_o, 0 otherwise

m_bz_mesh/littlegroup_t [ Types ]

For the GW part of ABINIT. The littlegroup_t structured datatype gather information on
the little group associated to an external vector q. The little group associated to q
is defined as the subset of the space group that preserves q, modulo a G0 vector
(also called umklapp vector). Namely
Sq = q +G0, where S is an operation in reciprocal space.
If time reversal symmetry holds true, it is possible to enlarge the little group by
including the operations such as
-Sq = q+ G0.
The operations belongin to the little group define an irriducible wedge in the Brillouin zone
that is, usually, larger than the irredubile zone defined by the space group.
The two zone coincide when q=0

TODO

Rationalize most of the arrays, in particular the tables
This structure shoud be rewritten almost from scratch, thus avoid using it
for your developments.

m_bz_mesh/make_mesh [ Functions ]

Cryst<crystal_t>=Info on the crystalline structure.
nshiftk=Number of shifts for the mesh.
kptrlatt(3,3)= Coordinates of three vectors in real space, expressed in reduced coordinates.
They define a super-lattice in real space. The k point lattice is the reciprocal of
this super-lattice, eventually shifted by shift.
shiftk(3,nshiftk)=Shifts for the k-mesh.
[vacuum(3)]=For each direction, 0 if no vacuum, 1 if vacuum

OUTPUT

Kmesh<kmesh_t>=Object gathering info on the sampling of the Brillouin zone.

m_bz_mesh/make_path [ Functions ]

Generate a normalized path given the extrema.
See also kpath_t and kpath_new (recommended API).

INPUTS

nbounds=Number of extrema defining the path.
bounds(3,nbounds)=The points defining the path in reduced coordinates.
met(3,3)=Metric matrix.
space='R' for real space, G for reciprocal space.
ndivsm=Number of divisions to be used for the smallest segment.
[unit]=Fortran unit for formatted output. Default: dev_null

OUTPUT

npts=Total number of points in the normalized circuit.
ndivs(nbounds-1)=Number of division for each segment
path: allocated inside the routine. When the subroutine returns, path(3,npts) will
contain the path in reduced coordinates.