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 : lattice_fft_auto = 400, &
44 : lattice_fft_on = 401, &
45 : lattice_fft_off = 402
46 :
47 : PUBLIC :: create_kpoints_section
48 : PUBLIC :: create_kpoint_set_section
49 : PUBLIC :: use_real_wfn, use_complex_wfn
50 : PUBLIC :: use_k290_kpoint_symmetry, use_spglib_kpoint_symmetry
51 : PUBLIC :: use_k290_kpoint_backend, use_spglib_kpoint_backend
52 : PUBLIC :: lattice_fft_auto, lattice_fft_on, lattice_fft_off
53 :
54 : CONTAINS
55 :
56 : ! **************************************************************************************************
57 : !> \brief Creates the Kpoints section
58 : !> SECTION: &kpoint... &end
59 : !> SCHEME [None, Gamma, Monkhorst-Pack, MacDonald, General]
60 : !> { nx ny nz }
61 : !> { nx ny nz sx sy sz }
62 : !> KPOINT x1 y1 z1 w1
63 : !> SYMMETRY [on, off]
64 : !> WAVEFUNCTION [real, complex]
65 : !> FULL_GRID [on, off]
66 : !> LATTICE_FFT [auto, on, off]
67 : !> INVERSION_SYMMETRY_ONLY [on, off]
68 : !> DEBUG_FULL_KPOINT_SYMMETRY [on, off]
69 : !> SYMMETRY_BACKEND [K290, SPGLIB]
70 : !> SYMMETRY_REDUCTION_METHOD [K290, SPGLIB]
71 : !> VERBOSE [on, off]
72 : !> EPS_SYMMETRY value
73 : !> PARALLEL_GROUP_SIZE [-1,0,n]
74 : !>
75 : !> \param section the section to create
76 : !> \author JGH
77 : ! **************************************************************************************************
78 4197 : SUBROUTINE create_kpoints_section(section)
79 : TYPE(section_type), POINTER :: section
80 :
81 : TYPE(keyword_type), POINTER :: keyword
82 :
83 4197 : CPASSERT(.NOT. ASSOCIATED(section))
84 : CALL section_create(section, __LOCATION__, name="KPOINTS", &
85 : description="Controls Brillouin-zone sampling with k-points.", &
86 4197 : n_keywords=1, n_subsections=0, repeats=.FALSE.)
87 :
88 4197 : NULLIFY (keyword)
89 : CALL keyword_create(keyword, __LOCATION__, name="SCHEME", &
90 : description="K-point generation scheme. Available options are:"//newline// &
91 : "- `NONE`"//newline// &
92 : "- `GAMMA`"//newline// &
93 : "- `MONKHORST-PACK`"//newline// &
94 : "- `MACDONALD`"//newline// &
95 : "- `GENERAL`"//newline// &
96 : newline// &
97 : "For `MONKHORST-PACK` the number of k points in all 3 dimensions has to"// &
98 : " be supplied along with the keyword. For `MACDONALD` also the list of shifts."// &
99 : " E.g. `MONKHORST-PACK 12 12 8`, `MACDONALD 4 4 4 0.25 0.25 0.25`."// &
100 : " `GENERAL` uses explicitly listed k-points. If symmetry reduction is requested,"// &
101 : " the explicit set must be equally weighted and closed under the selected operations.", &
102 : usage="SCHEME {KPMETHOD} {integer} {integer} ..", &
103 : citations=[Monkhorst1976, MacDonald1978], &
104 12591 : n_var=-1, type_of_var=char_t)
105 4197 : CALL section_add_keyword(section, keyword)
106 4197 : CALL keyword_release(keyword)
107 :
108 : CALL keyword_create(keyword, __LOCATION__, name="GAMMA_CENTERED", &
109 : description="Generate a gamma-centered variant of the "// &
110 : "Monkhorst-Pack or MacDonald mesh. This shifts the original mesh so "// &
111 : "it can include the Gamma point, and makes sense only when an "// &
112 : "even number of subdivisions is used. For MacDonald meshes, the "// &
113 : "explicit shift is applied after the gamma-centering shift.", &
114 : usage="GAMMA_CENTERED <LOGICAL>", &
115 4197 : default_l_val=.FALSE., lone_keyword_l_val=.TRUE.)
116 4197 : CALL section_add_keyword(section, keyword)
117 4197 : CALL keyword_release(keyword)
118 :
119 : CALL keyword_create(keyword, __LOCATION__, name="KPOINT", &
120 : description="Specify kpoint coordinates and weight. ", &
121 : usage="KPOINT x y z w", repeats=.TRUE., &
122 4197 : n_var=4, type_of_var=real_t)
123 4197 : CALL section_add_keyword(section, keyword)
124 4197 : CALL keyword_release(keyword)
125 :
126 : CALL keyword_create(keyword, __LOCATION__, name="UNITS", &
127 : description="Special k-points are defined either in units"// &
128 : " of reciprocal lattice vectors or in Cartesian coordinates in units of 2Pi/len."// &
129 : " B_VECTOR: in multiples of the reciprocal lattice vectors (b)."// &
130 : " CART_ANGSTROM: In units of 2*Pi/Angstrom."// &
131 : " CART_BOHR: In units of 2*Pi/Bohr.", &
132 4197 : usage="UNITS <value>", type_of_var=char_t, default_c_val="B_VECTOR")
133 4197 : CALL section_add_keyword(section, keyword)
134 4197 : CALL keyword_release(keyword)
135 :
136 : CALL keyword_create(keyword, __LOCATION__, name="SYMMETRY", &
137 : description="Use symmetry to reduce the number of kpoints.", &
138 : usage="SYMMETRY <LOGICAL>", &
139 4197 : default_l_val=.FALSE., lone_keyword_l_val=.TRUE.)
140 4197 : CALL section_add_keyword(section, keyword)
141 4197 : CALL keyword_release(keyword)
142 :
143 : CALL keyword_create(keyword, __LOCATION__, name="FULL_GRID", &
144 : description="Use the full, non-symmetry-reduced k-point grid.", &
145 : usage="FULL_GRID <LOGICAL>", &
146 4197 : default_l_val=.FALSE., lone_keyword_l_val=.TRUE.)
147 4197 : CALL section_add_keyword(section, keyword)
148 4197 : CALL keyword_release(keyword)
149 :
150 : CALL keyword_create(keyword, __LOCATION__, name="LATTICE_FFT", &
151 : description="Control lattice FFTs for real-space operators and grouped k-point densities. "// &
152 : "The density path also accepts regular-grid subsets with their original weights. "// &
153 : "AUTO uses the lattice FFT for at least "// &
154 : "27 k points when the grid, memory, and communication-granularity requirements "// &
155 : "are satisfied. ON bypasses these performance thresholds. OFF always uses the "// &
156 : "established direct phase sum. "// &
157 : "Unsupported or oversized grids retain the direct fallback; the forward operator "// &
158 : "FFT still requires a complete grid.", &
159 : usage="LATTICE_FFT AUTO", type_of_var=enum_t, &
160 : enum_c_vals=s2a("AUTO", "ON", "OFF"), &
161 : enum_i_vals=[lattice_fft_auto, lattice_fft_on, lattice_fft_off], &
162 : enum_desc=s2a("Select the FFT from a conservative cost threshold.", &
163 : "Prefer the FFT whenever the grid and memory checks allow it.", &
164 : "Use direct phase sums instead of lattice FFTs."), &
165 4197 : default_i_val=lattice_fft_auto)
166 4197 : CALL section_add_keyword(section, keyword)
167 4197 : CALL keyword_release(keyword)
168 :
169 : CALL keyword_create(keyword, __LOCATION__, name="INVERSION_SYMMETRY_ONLY", &
170 : description="Restrict k-point reduction to k-space inversion "// &
171 : "(time-reversal) symmetry.", &
172 : usage="INVERSION_SYMMETRY_ONLY <LOGICAL>", &
173 4197 : default_l_val=.FALSE., lone_keyword_l_val=.TRUE.)
174 4197 : CALL section_add_keyword(section, keyword)
175 4197 : CALL keyword_release(keyword)
176 :
177 : CALL keyword_create(keyword, __LOCATION__, name="DEBUG_FULL_KPOINT_SYMMETRY", &
178 : description="Use full atomic k-point symmetry also for DEBUG finite-difference "// &
179 : "points. This is enabled by default so analytical and finite-difference "// &
180 : "evaluations use the symmetry of their current geometry. Disable it to restrict "// &
181 : "DEBUG finite-difference energies to inversion/time-reversal symmetry.", &
182 : usage="DEBUG_FULL_KPOINT_SYMMETRY <LOGICAL>", &
183 4197 : default_l_val=.TRUE., lone_keyword_l_val=.TRUE.)
184 4197 : CALL section_add_keyword(section, keyword)
185 4197 : CALL keyword_release(keyword)
186 :
187 : CALL keyword_create(keyword, __LOCATION__, name="SYMMETRY_BACKEND", &
188 : description="Select the backend used to provide and apply atomic "// &
189 : "k-point symmetry operations. K290 is the established default. "// &
190 : "SPGLIB uses the symmetry operations returned by SPGLIB, including "// &
191 : "their fractional translations. This applies to Monkhorst-Pack, MacDonald, and "// &
192 : "closed GENERAL k-point sets. If "// &
193 : "SYMMETRY_REDUCTION_METHOD is not specified, it follows the selected backend.", &
194 : usage="SYMMETRY_BACKEND K290", type_of_var=enum_t, &
195 : enum_c_vals=s2a("K290", "SPGLIB"), &
196 : enum_i_vals=[use_k290_kpoint_backend, use_spglib_kpoint_backend], &
197 : enum_desc=s2a("Use the existing K290 k-point symmetry backend.", &
198 : "Use SPGLIB symmetry operations as k-point symmetry backend."), &
199 4197 : default_i_val=use_k290_kpoint_backend)
200 4197 : CALL section_add_keyword(section, keyword)
201 4197 : CALL keyword_release(keyword)
202 :
203 : CALL keyword_create(keyword, __LOCATION__, name="SYMMETRY_REDUCTION_METHOD", &
204 : description="Select the method used to reduce Monkhorst-Pack and MacDonald "// &
205 : "k-point meshes when atomic symmetry is enabled. K290 is the established "// &
206 : "default. SPGLIB uses the symmetry operations returned by SPGLIB for the "// &
207 : "k-point reduction. GENERAL k-point lists can be reduced when the explicit set is "// &
208 : "equally weighted and closed under the selected operations. With "// &
209 : "SYMMETRY_BACKEND K290 this can be used as a comparison mode using K290 "// &
210 : "operations for SPGLIB-generated mappings.", &
211 : usage="SYMMETRY_REDUCTION_METHOD K290", type_of_var=enum_t, &
212 : enum_c_vals=s2a("K290", "SPGLIB"), &
213 : enum_i_vals=[use_k290_kpoint_symmetry, use_spglib_kpoint_symmetry], &
214 : enum_desc=s2a("Use the existing K290 k-point symmetry reduction method.", &
215 : "Use SPGLIB symmetry operations for k-point reduction."), &
216 4197 : default_i_val=use_k290_kpoint_symmetry)
217 4197 : CALL section_add_keyword(section, keyword)
218 4197 : CALL keyword_release(keyword)
219 :
220 : CALL keyword_create(keyword, __LOCATION__, name="VERBOSE", &
221 : description="Verbose output information.", &
222 : usage="VERBOSE <LOGICAL>", &
223 4197 : default_l_val=.FALSE., lone_keyword_l_val=.TRUE.)
224 4197 : CALL section_add_keyword(section, keyword)
225 4197 : CALL keyword_release(keyword)
226 :
227 : CALL keyword_create(keyword, __LOCATION__, name="EPS_SYMMETRY", variants=["EPS_GEO"], &
228 : description="Accuracy in k-point symmetry determination."//newline// &
229 : "K290 applies this value in lattice and fractional-coordinate checks. "// &
230 : "SPGLIB uses a Cartesian distance tolerance in bohr. The same numerical "// &
231 : "value is therefore not an equivalent geometric tolerance for both backends."//newline// &
232 : "EPS_GEO is accepted as an alias.", &
233 : usage="EPS_SYMMETRY <real>", &
234 8394 : default_r_val=1.0e-6_dp)
235 4197 : CALL section_add_keyword(section, keyword)
236 4197 : CALL keyword_release(keyword)
237 :
238 : CALL keyword_create(keyword, __LOCATION__, name="PARALLEL_GROUP_SIZE", &
239 : description="Number of MPI processes to be used for a single k-point."// &
240 : " This number must divide the total number of processes."// &
241 : " The number of groups must not exceed the number of kpoints."// &
242 : " Kpoints are distributed as evenly as possible among the groups."// &
243 : " Value=-1 (smallest possible number of processes per group, satisfying the constraints)."// &
244 : " Value=0 (all processes)."// &
245 : " Value=n (exactly n processes).", &
246 : usage="PARALLEL_GROUP_SIZE <integer>", &
247 4197 : default_i_val=-1)
248 4197 : CALL section_add_keyword(section, keyword)
249 4197 : CALL keyword_release(keyword)
250 :
251 : CALL keyword_create(keyword, __LOCATION__, name="WAVEFUNCTIONS", &
252 : description="Select whether real or complex wavefunctions should be used "// &
253 : "when allowed by the k-point set. REAL wavefunctions can only represent "// &
254 : "Gamma or special k-points and symmetry operations with real Bloch phases. "// &
255 : "Use COMPLEX for general atomic k-point symmetries with nontrivial phases.", &
256 : usage="WAVEFUNCTIONS REAL", &
257 : default_i_val=use_complex_wfn, &
258 : enum_c_vals=s2a("REAL", "COMPLEX"), &
259 : enum_desc=s2a("Use real wavefunctions (if possible by kpoints specified).", &
260 : "Use complex wavefunctions (default)."), &
261 4197 : enum_i_vals=[use_real_wfn, use_complex_wfn])
262 4197 : CALL section_add_keyword(section, keyword)
263 4197 : CALL keyword_release(keyword)
264 :
265 4197 : END SUBROUTINE create_kpoints_section
266 :
267 : ! **************************************************************************************************
268 : !> \brief ...
269 : !> \param section ...
270 : !> \param section_name ...
271 : !> \author JGH
272 : ! **************************************************************************************************
273 16693 : SUBROUTINE create_kpoint_set_section(section, section_name)
274 : TYPE(section_type), POINTER :: section
275 : CHARACTER(LEN=*), OPTIONAL :: section_name
276 :
277 : CHARACTER(len=default_path_length) :: my_section_name
278 : TYPE(keyword_type), POINTER :: keyword
279 :
280 16693 : IF (PRESENT(section_name)) THEN
281 1380 : my_section_name = section_name
282 : ELSE
283 15313 : my_section_name = "KPOINT_SET"
284 : END IF
285 :
286 16693 : CPASSERT(.NOT. ASSOCIATED(section))
287 : CALL section_create(section, __LOCATION__, name=my_section_name, &
288 : description="Specifies a k-point line to be calculated.", &
289 16693 : n_keywords=0, n_subsections=0, repeats=.TRUE.)
290 : ! keywords
291 16693 : NULLIFY (keyword)
292 : CALL keyword_create(keyword, __LOCATION__, name="SPECIAL_POINT", &
293 : description="Name and coordinates of a special k-point", &
294 16693 : usage="SPECIAL_POINT GAMMA 0.0 0.0 0.0", n_var=-1, type_of_var=char_t, repeats=.TRUE.)
295 16693 : CALL section_add_keyword(section, keyword)
296 16693 : CALL keyword_release(keyword)
297 : !
298 : CALL keyword_create(keyword, __LOCATION__, name="NPOINTS", &
299 : description="Number of k-points along the line.", &
300 16693 : default_i_val=0)
301 16693 : CALL section_add_keyword(section, keyword)
302 16693 : CALL keyword_release(keyword)
303 : !
304 : CALL keyword_create(keyword, __LOCATION__, name="UNITS", &
305 : description="Special k-points are defined either in units"// &
306 : " of reciprocal lattice vectors or in Cartesian coordinates in units of 2Pi/len."// &
307 : " B_VECTOR: in multiples of the reciprocal lattice vectors (b)."// &
308 : " CART_ANGSTROM: In units of 2*Pi/Angstrom."// &
309 : " CART_BOHR: In units of 2*Pi/Bohr.", &
310 16693 : usage="UNITS <value>", type_of_var=char_t, default_c_val="B_VECTOR")
311 16693 : CALL section_add_keyword(section, keyword)
312 16693 : CALL keyword_release(keyword)
313 :
314 16693 : END SUBROUTINE create_kpoint_set_section
315 :
316 : END MODULE input_cp2k_kpoints
|
