LCOV - code coverage report
Current view: top level - src - input_cp2k_kpoints.F (source / functions) Coverage Total Hit
Test: CP2K Regtests (git:744416f) Lines: 100.0 % 67 67
Test Date: 2026-09-20 02:09:09 Functions: 100.0 % 2 2

            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
        

Generated by: LCOV version 2.0-1