(git:47b47fb)
Loading...
Searching...
No Matches
input_cp2k_kpoints.F
Go to the documentation of this file.
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! **************************************************************************************************
14MODULE 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
54CONTAINS
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 SUBROUTINE create_kpoints_section(section)
79 TYPE(section_type), POINTER :: section
80
81 TYPE(keyword_type), POINTER :: keyword
82
83 cpassert(.NOT. ASSOCIATED(section))
84 CALL section_create(section, __location__, name="KPOINTS", &
85 description="Controls Brillouin-zone sampling with k-points.", &
86 n_keywords=1, n_subsections=0, repeats=.false.)
87
88 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 n_var=-1, type_of_var=char_t)
105 CALL section_add_keyword(section, keyword)
106 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 default_l_val=.false., lone_keyword_l_val=.true.)
116 CALL section_add_keyword(section, keyword)
117 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 n_var=4, type_of_var=real_t)
123 CALL section_add_keyword(section, keyword)
124 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 usage="UNITS <value>", type_of_var=char_t, default_c_val="B_VECTOR")
133 CALL section_add_keyword(section, keyword)
134 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 default_l_val=.false., lone_keyword_l_val=.true.)
140 CALL section_add_keyword(section, keyword)
141 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 default_l_val=.false., lone_keyword_l_val=.true.)
147 CALL section_add_keyword(section, keyword)
148 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 default_i_val=lattice_fft_auto)
166 CALL section_add_keyword(section, keyword)
167 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 default_l_val=.false., lone_keyword_l_val=.true.)
174 CALL section_add_keyword(section, keyword)
175 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 default_l_val=.true., lone_keyword_l_val=.true.)
184 CALL section_add_keyword(section, keyword)
185 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 default_i_val=use_k290_kpoint_backend)
200 CALL section_add_keyword(section, keyword)
201 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 default_i_val=use_k290_kpoint_symmetry)
217 CALL section_add_keyword(section, keyword)
218 CALL keyword_release(keyword)
219
220 CALL keyword_create(keyword, __location__, name="VERBOSE", &
221 description="Verbose output information.", &
222 usage="VERBOSE <LOGICAL>", &
223 default_l_val=.false., lone_keyword_l_val=.true.)
224 CALL section_add_keyword(section, keyword)
225 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 default_r_val=1.0e-6_dp)
235 CALL section_add_keyword(section, keyword)
236 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 default_i_val=-1)
248 CALL section_add_keyword(section, keyword)
249 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 enum_i_vals=[use_real_wfn, use_complex_wfn])
262 CALL section_add_keyword(section, keyword)
263 CALL keyword_release(keyword)
264
265 END SUBROUTINE create_kpoints_section
266
267! **************************************************************************************************
268!> \brief ...
269!> \param section ...
270!> \param section_name ...
271!> \author JGH
272! **************************************************************************************************
273 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 IF (PRESENT(section_name)) THEN
281 my_section_name = section_name
282 ELSE
283 my_section_name = "KPOINT_SET"
284 END IF
285
286 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 n_keywords=0, n_subsections=0, repeats=.true.)
290 ! keywords
291 NULLIFY (keyword)
292 CALL keyword_create(keyword, __location__, name="SPECIAL_POINT", &
293 description="Name and coordinates of a special k-point", &
294 usage="SPECIAL_POINT GAMMA 0.0 0.0 0.0", n_var=-1, type_of_var=char_t, repeats=.true.)
295 CALL section_add_keyword(section, keyword)
296 CALL keyword_release(keyword)
297 !
298 CALL keyword_create(keyword, __location__, name="NPOINTS", &
299 description="Number of k-points along the line.", &
300 default_i_val=0)
301 CALL section_add_keyword(section, keyword)
302 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 usage="UNITS <value>", type_of_var=char_t, default_c_val="B_VECTOR")
311 CALL section_add_keyword(section, keyword)
312 CALL keyword_release(keyword)
313
314 END SUBROUTINE create_kpoint_set_section
315
316END MODULE input_cp2k_kpoints
string_utilities::s2a
Definition string_utilities.F:49
bibliography
collects all references to literature in CP2K as new algorithms / method are included from literature...
Definition bibliography.F:21
bibliography::monkhorst1976
integer, save, public monkhorst1976
Definition bibliography.F:36
bibliography::macdonald1978
integer, save, public macdonald1978
Definition bibliography.F:36
input_cp2k_kpoints
function that build the kpoints section of the input
Definition input_cp2k_kpoints.F:14
input_cp2k_kpoints::use_spglib_kpoint_symmetry
integer, parameter, public use_spglib_kpoint_symmetry
Definition input_cp2k_kpoints.F:37
input_cp2k_kpoints::lattice_fft_auto
integer, parameter, public lattice_fft_auto
Definition input_cp2k_kpoints.F:37
input_cp2k_kpoints::use_k290_kpoint_symmetry
integer, parameter, public use_k290_kpoint_symmetry
Definition input_cp2k_kpoints.F:37
input_cp2k_kpoints::create_kpoints_section
subroutine, public create_kpoints_section(section)
Creates the Kpoints section SECTION: &kpoint... &end SCHEME [None, Gamma, Monkhorst-Pack,...
Definition input_cp2k_kpoints.F:79
input_cp2k_kpoints::lattice_fft_off
integer, parameter, public lattice_fft_off
Definition input_cp2k_kpoints.F:37
input_cp2k_kpoints::use_real_wfn
integer, parameter, public use_real_wfn
Definition input_cp2k_kpoints.F:37
input_cp2k_kpoints::create_kpoint_set_section
subroutine, public create_kpoint_set_section(section, section_name)
...
Definition input_cp2k_kpoints.F:274
input_cp2k_kpoints::lattice_fft_on
integer, parameter, public lattice_fft_on
Definition input_cp2k_kpoints.F:37
input_cp2k_kpoints::use_spglib_kpoint_backend
integer, parameter, public use_spglib_kpoint_backend
Definition input_cp2k_kpoints.F:37
input_cp2k_kpoints::use_k290_kpoint_backend
integer, parameter, public use_k290_kpoint_backend
Definition input_cp2k_kpoints.F:37
input_cp2k_kpoints::use_complex_wfn
integer, parameter, public use_complex_wfn
Definition input_cp2k_kpoints.F:37
input_keyword_types
represents keywords in an input
Definition input_keyword_types.F:14
input_keyword_types::keyword_release
subroutine, public keyword_release(keyword)
releases the given keyword (see doc/ReferenceCounting.html)
Definition input_keyword_types.F:448
input_keyword_types::keyword_create
subroutine, public keyword_create(keyword, location, name, description, usage, type_of_var, n_var, repeats, variants, default_val, default_l_val, default_r_val, default_lc_val, default_c_val, default_i_val, default_l_vals, default_r_vals, default_c_vals, default_i_vals, lone_keyword_val, lone_keyword_l_val, lone_keyword_r_val, lone_keyword_c_val, lone_keyword_i_val, lone_keyword_l_vals, lone_keyword_r_vals, lone_keyword_c_vals, lone_keyword_i_vals, enum_c_vals, enum_i_vals, enum, enum_strict, enum_desc, unit_str, citations, deprecation_notice, removed)
creates a keyword object
Definition input_keyword_types.F:156
input_section_types
objects that represent the structure of input sections and the data contained in an input section
Definition input_section_types.F:15
input_section_types::section_create
subroutine, public section_create(section, location, name, description, n_keywords, n_subsections, repeats, citations, deprecation_notice)
creates a list of keywords
Definition input_section_types.F:158
input_section_types::section_add_keyword
subroutine, public section_add_keyword(section, keyword)
adds a keyword to the given section
Definition input_section_types.F:514
input_val_types
a wrapper for basic fortran types.
Definition input_val_types.F:14
input_val_types::real_t
integer, parameter, public real_t
Definition input_val_types.F:41
input_val_types::char_t
integer, parameter, public char_t
Definition input_val_types.F:41
input_val_types::enum_t
integer, parameter, public enum_t
Definition input_val_types.F:41
kinds
Defines the basic variable types.
Definition kinds.F:23
kinds::dp
integer, parameter, public dp
Definition kinds.F:34
kinds::default_path_length
integer, parameter, public default_path_length
Definition kinds.F:58
string_utilities
Utilities for string manipulations.
Definition string_utilities.F:16
string_utilities::newline
character(len=1), parameter, public newline
Definition string_utilities.F:29
input_keyword_types::keyword_type
represent a keyword in the input
Definition input_keyword_types.F:89
input_section_types::section_type
represent a section of the input file
Definition input_section_types.F:102