Line data Source code
1 : !--------------------------------------------------------------------------------------------------!
2 : ! CP2K: A general program to perform molecular dynamics simulations !
3 : ! Copyright 2000-2026 CP2K developers group <https://cp2k.org> !
4 : ! !
5 : ! SPDX-License-Identifier: GPL-2.0-or-later !
6 : !--------------------------------------------------------------------------------------------------!
7 :
8 : ! **************************************************************************************************
9 : !> \brief function that build the kpoints section of the input
10 : !> \par History
11 : !> init [07.2014]
12 : !> \author JGH
13 : ! **************************************************************************************************
14 : MODULE input_cp2k_kpoints
15 : USE bibliography, ONLY: MacDonald1978,&
16 : Monkhorst1976
17 : USE input_keyword_types, ONLY: keyword_create,&
18 : keyword_release,&
19 : keyword_type
20 : USE input_section_types, ONLY: section_add_keyword,&
21 : section_create,&
22 : section_type
23 : USE input_val_types, ONLY: char_t,&
24 : enum_t,&
25 : real_t
26 : USE kinds, ONLY: default_path_length,&
27 : dp
28 : USE string_utilities, ONLY: newline,&
29 : s2a
30 : #include "./base/base_uses.f90"
31 :
32 : IMPLICIT NONE
33 : PRIVATE
34 :
35 : CHARACTER(len=*), PARAMETER, PRIVATE :: moduleN = 'input_cp2k_kpoints'
36 :
37 : INTEGER, PARAMETER :: use_real_wfn = 101, &
38 : use_complex_wfn = 100, &
39 : use_k290_kpoint_symmetry = 200, &
40 : use_spglib_kpoint_symmetry = 201, &
41 : use_k290_kpoint_backend = 300, &
42 : use_spglib_kpoint_backend = 301
43 :
44 : PUBLIC :: create_kpoints_section
45 : PUBLIC :: create_kpoint_set_section
46 : PUBLIC :: use_real_wfn, use_complex_wfn
47 : PUBLIC :: use_k290_kpoint_symmetry, use_spglib_kpoint_symmetry
48 : PUBLIC :: use_k290_kpoint_backend, use_spglib_kpoint_backend
49 :
50 : CONTAINS
51 :
52 : ! **************************************************************************************************
53 : !> \brief Creates the Kpoints section
54 : !> SECTION: &kpoint... &end
55 : !> SCHEME [None, Gamma, Monkhorst-Pack, MacDonald, General]
56 : !> { nx ny nz }
57 : !> { nx ny nz sx sy sz }
58 : !> KPOINT x1 y1 z1 w1
59 : !> SYMMETRY [on, off]
60 : !> WAVEFUNCTION [real, complex]
61 : !> FULL_GRID [on, off]
62 : !> INVERSION_SYMMETRY_ONLY [on, off]
63 : !> SYMMETRY_BACKEND [K290, SPGLIB]
64 : !> SYMMETRY_REDUCTION_METHOD [K290, SPGLIB]
65 : !> VERBOSE [on, off]
66 : !> EPS_SYMMETRY value
67 : !> PARALLEL_GROUP_SIZE [-1,0,n]
68 : !>
69 : !> \param section the section to create
70 : !> \author JGH
71 : ! **************************************************************************************************
72 29517 : SUBROUTINE create_kpoints_section(section)
73 : TYPE(section_type), POINTER :: section
74 :
75 : TYPE(keyword_type), POINTER :: keyword
76 :
77 29517 : CPASSERT(.NOT. ASSOCIATED(section))
78 : CALL section_create(section, __LOCATION__, name="KPOINTS", &
79 : description="Controls Brillouin-zone sampling with k-points.", &
80 29517 : n_keywords=1, n_subsections=0, repeats=.FALSE.)
81 :
82 29517 : NULLIFY (keyword)
83 : CALL keyword_create(keyword, __LOCATION__, name="SCHEME", &
84 : description="K-point generation scheme. Available options are:"//newline// &
85 : "- `NONE`"//newline// &
86 : "- `GAMMA`"//newline// &
87 : "- `MONKHORST-PACK`"//newline// &
88 : "- `MACDONALD`"//newline// &
89 : "- `GENERAL`"//newline// &
90 : newline// &
91 : "For `MONKHORST-PACK` the number of k points in all 3 dimensions has to"// &
92 : " be supplied along with the keyword. For `MACDONALD` also the list of shifts."// &
93 : " E.g. `MONKHORST-PACK 12 12 8`, `MACDONALD 4 4 4 0.25 0.25 0.25`."// &
94 : " `GENERAL` uses the explicitly listed k-points as supplied and does not apply"// &
95 : " SYMMETRY_BACKEND or SYMMETRY_REDUCTION_METHOD.", &
96 : usage="SCHEME {KPMETHOD} {integer} {integer} ..", &
97 : citations=[Monkhorst1976, MacDonald1978], &
98 88551 : n_var=-1, type_of_var=char_t)
99 29517 : CALL section_add_keyword(section, keyword)
100 29517 : CALL keyword_release(keyword)
101 :
102 : CALL keyword_create(keyword, __LOCATION__, name="KPOINT", &
103 : description="Specify kpoint coordinates and weight. ", &
104 : usage="KPOINT x y z w", repeats=.TRUE., &
105 29517 : n_var=4, type_of_var=real_t)
106 29517 : CALL section_add_keyword(section, keyword)
107 29517 : CALL keyword_release(keyword)
108 :
109 : CALL keyword_create(keyword, __LOCATION__, name="UNITS", &
110 : description="Special k-points are defined either in units"// &
111 : " of reciprocal lattice vectors or in Cartesian coordinates in units of 2Pi/len."// &
112 : " B_VECTOR: in multiples of the reciprocal lattice vectors (b)."// &
113 : " CART_ANGSTROM: In units of 2*Pi/Angstrom."// &
114 : " CART_BOHR: In units of 2*Pi/Bohr.", &
115 29517 : usage="UNITS <value>", type_of_var=char_t, default_c_val="B_VECTOR")
116 29517 : CALL section_add_keyword(section, keyword)
117 29517 : CALL keyword_release(keyword)
118 :
119 : CALL keyword_create(keyword, __LOCATION__, name="SYMMETRY", &
120 : description="Use symmetry to reduce the number of kpoints.", &
121 : usage="SYMMETRY <LOGICAL>", &
122 29517 : default_l_val=.FALSE., lone_keyword_l_val=.TRUE.)
123 29517 : CALL section_add_keyword(section, keyword)
124 29517 : CALL keyword_release(keyword)
125 :
126 : CALL keyword_create(keyword, __LOCATION__, name="FULL_GRID", &
127 : description="Use the full, non-symmetry-reduced k-point grid.", &
128 : usage="FULL_GRID <LOGICAL>", &
129 29517 : default_l_val=.FALSE., lone_keyword_l_val=.TRUE.)
130 29517 : CALL section_add_keyword(section, keyword)
131 29517 : CALL keyword_release(keyword)
132 :
133 : CALL keyword_create(keyword, __LOCATION__, name="INVERSION_SYMMETRY_ONLY", &
134 : description="Restrict k-point reduction to k-space inversion "// &
135 : "(time-reversal) symmetry.", &
136 : usage="INVERSION_SYMMETRY_ONLY <LOGICAL>", &
137 29517 : default_l_val=.FALSE., lone_keyword_l_val=.TRUE.)
138 29517 : CALL section_add_keyword(section, keyword)
139 29517 : CALL keyword_release(keyword)
140 :
141 : CALL keyword_create(keyword, __LOCATION__, name="SYMMETRY_BACKEND", &
142 : description="Select the backend used to provide and apply atomic "// &
143 : "k-point symmetry operations. K290 is the established default. "// &
144 : "SPGLIB uses the symmetry operations returned by SPGLIB, including "// &
145 : "their fractional translations. This applies to Monkhorst-Pack and MacDonald "// &
146 : "meshes. For GENERAL, the explicit k-point list is used as supplied. If "// &
147 : "SYMMETRY_REDUCTION_METHOD is not specified, it follows the selected backend.", &
148 : usage="SYMMETRY_BACKEND K290", type_of_var=enum_t, &
149 : enum_c_vals=s2a("K290", "SPGLIB"), &
150 : enum_i_vals=[use_k290_kpoint_backend, use_spglib_kpoint_backend], &
151 : enum_desc=s2a("Use the existing K290 k-point symmetry backend.", &
152 : "Use SPGLIB symmetry operations as k-point symmetry backend."), &
153 29517 : default_i_val=use_k290_kpoint_backend)
154 29517 : CALL section_add_keyword(section, keyword)
155 29517 : CALL keyword_release(keyword)
156 :
157 : CALL keyword_create(keyword, __LOCATION__, name="SYMMETRY_REDUCTION_METHOD", &
158 : description="Select the method used to reduce Monkhorst-Pack and MacDonald "// &
159 : "k-point meshes when atomic symmetry is enabled. K290 is the established "// &
160 : "default. SPGLIB uses the symmetry operations returned by SPGLIB for the "// &
161 : "k-point reduction. GENERAL k-point lists are not reduced. With "// &
162 : "SYMMETRY_BACKEND K290 this can be used as a comparison mode using K290 "// &
163 : "operations for SPGLIB-generated mappings.", &
164 : usage="SYMMETRY_REDUCTION_METHOD K290", type_of_var=enum_t, &
165 : enum_c_vals=s2a("K290", "SPGLIB"), &
166 : enum_i_vals=[use_k290_kpoint_symmetry, use_spglib_kpoint_symmetry], &
167 : enum_desc=s2a("Use the existing K290 k-point symmetry reduction method.", &
168 : "Use SPGLIB symmetry operations for k-point reduction."), &
169 29517 : default_i_val=use_k290_kpoint_symmetry)
170 29517 : CALL section_add_keyword(section, keyword)
171 29517 : CALL keyword_release(keyword)
172 :
173 : CALL keyword_create(keyword, __LOCATION__, name="VERBOSE", &
174 : description="Verbose output information.", &
175 : usage="VERBOSE <LOGICAL>", &
176 29517 : default_l_val=.FALSE., lone_keyword_l_val=.TRUE.)
177 29517 : CALL section_add_keyword(section, keyword)
178 29517 : CALL keyword_release(keyword)
179 :
180 : CALL keyword_create(keyword, __LOCATION__, name="EPS_SYMMETRY", variants=["EPS_GEO"], &
181 : description="Accuracy in k-point symmetry determination."//newline// &
182 : "EPS_GEO is accepted as an alias.", &
183 : usage="EPS_SYMMETRY <real>", &
184 59034 : default_r_val=1.0e-6_dp)
185 29517 : CALL section_add_keyword(section, keyword)
186 29517 : CALL keyword_release(keyword)
187 :
188 : CALL keyword_create(keyword, __LOCATION__, name="PARALLEL_GROUP_SIZE", &
189 : description="Number of MPI processes to be used for a single k-point."// &
190 : " This number must divide the total number of processes."// &
191 : " The number of groups must divide the total number of kpoints."// &
192 : " Value=-1 (smallest possible number of processes per group, satisfying the constraints)."// &
193 : " Value=0 (all processes)."// &
194 : " Value=n (exactly n processes).", &
195 : usage="PARALLEL_GROUP_SIZE <integer>", &
196 29517 : default_i_val=-1)
197 29517 : CALL section_add_keyword(section, keyword)
198 29517 : CALL keyword_release(keyword)
199 :
200 : CALL keyword_create(keyword, __LOCATION__, name="WAVEFUNCTIONS", &
201 : description="Select whether real or complex wavefunctions should be used "// &
202 : "when allowed by the k-point set. REAL wavefunctions can only represent "// &
203 : "Gamma or special k-points and symmetry operations with real Bloch phases. "// &
204 : "Use COMPLEX for general atomic k-point symmetries with nontrivial phases.", &
205 : usage="WAVEFUNCTIONS REAL", &
206 : default_i_val=use_complex_wfn, &
207 : enum_c_vals=s2a("REAL", "COMPLEX"), &
208 : enum_desc=s2a("Use real wavefunctions (if possible by kpoints specified).", &
209 : "Use complex wavefunctions (default)."), &
210 29517 : enum_i_vals=[use_real_wfn, use_complex_wfn])
211 29517 : CALL section_add_keyword(section, keyword)
212 29517 : CALL keyword_release(keyword)
213 :
214 29517 : END SUBROUTINE create_kpoints_section
215 :
216 : ! **************************************************************************************************
217 : !> \brief ...
218 : !> \param section ...
219 : !> \param section_name ...
220 : !> \author JGH
221 : ! **************************************************************************************************
222 117988 : SUBROUTINE create_kpoint_set_section(section, section_name)
223 : TYPE(section_type), POINTER :: section
224 : CHARACTER(LEN=*), OPTIONAL :: section_name
225 :
226 : CHARACTER(len=default_path_length) :: my_section_name
227 : TYPE(keyword_type), POINTER :: keyword
228 :
229 117988 : IF (PRESENT(section_name)) THEN
230 9823 : my_section_name = section_name
231 : ELSE
232 108165 : my_section_name = "KPOINT_SET"
233 : END IF
234 :
235 117988 : CPASSERT(.NOT. ASSOCIATED(section))
236 : CALL section_create(section, __LOCATION__, name=my_section_name, &
237 : description="Specifies a k-point line to be calculated.", &
238 117988 : n_keywords=0, n_subsections=0, repeats=.TRUE.)
239 : ! keywords
240 117988 : NULLIFY (keyword)
241 : CALL keyword_create(keyword, __LOCATION__, name="SPECIAL_POINT", &
242 : description="Name and coordinates of a special k-point", &
243 117988 : usage="SPECIAL_POINT GAMMA 0.0 0.0 0.0", n_var=-1, type_of_var=char_t, repeats=.TRUE.)
244 117988 : CALL section_add_keyword(section, keyword)
245 117988 : CALL keyword_release(keyword)
246 : !
247 : CALL keyword_create(keyword, __LOCATION__, name="NPOINTS", &
248 : description="Number of k-points along the line.", &
249 117988 : default_i_val=0)
250 117988 : CALL section_add_keyword(section, keyword)
251 117988 : CALL keyword_release(keyword)
252 : !
253 : CALL keyword_create(keyword, __LOCATION__, name="UNITS", &
254 : description="Special k-points are defined either in units"// &
255 : " of reciprocal lattice vectors or in Cartesian coordinates in units of 2Pi/len."// &
256 : " B_VECTOR: in multiples of the reciprocal lattice vectors (b)."// &
257 : " CART_ANGSTROM: In units of 2*Pi/Angstrom."// &
258 : " CART_BOHR: In units of 2*Pi/Bohr.", &
259 117988 : usage="UNITS <value>", type_of_var=char_t, default_c_val="B_VECTOR")
260 117988 : CALL section_add_keyword(section, keyword)
261 117988 : CALL keyword_release(keyword)
262 :
263 117988 : END SUBROUTINE create_kpoint_set_section
264 :
265 : END MODULE input_cp2k_kpoints
|
