From c92e8381f74bd8f51bd4d4b6d139da9764c49fd5 Mon Sep 17 00:00:00 2001 From: Dynamics of Condensed Matter <30792324+DCM-Uni-Paderborn@users.noreply.github.com> Date: Sun, 26 Apr 2026 12:02:00 +0200 Subject: [PATCH] docs: add Quickstep getting-started material (#5100) Co-authored-by: Thomas D. Kuehne --- docs/getting-started/first-calculation.md | 137 +++++++++++++++++++++- docs/getting-started/h2o.inp | 47 ++++++++ docs/methods/dft/basis_sets.md | 97 ++++++++++++++- docs/methods/dft/gapw.md | 77 +++++++++++- docs/methods/dft/gapw_h2o.inp | 56 +++++++++ docs/methods/dft/gpw.md | 3 +- docs/methods/dft/hartree-fock/admm.md | 87 +++++++++++++- docs/methods/dft/index.md | 18 ++- docs/methods/dft/pseudopotentials.md | 77 +++++++++++- docs/methods/post_hartree_fock/index.md | 22 ++-- docs/methods/qm_mm/gromacs.md | 39 +++++- src/common/bibliography.F | 30 +++-- src/common/reference_manager.F | 63 ++++++---- src/input_cp2k_dft.F | 54 +++++---- src/input_cp2k_force_eval.F | 7 +- src/input_cp2k_global.F | 4 +- src/input_cp2k_hfx.F | 33 +++--- src/input_cp2k_kpoints.F | 15 +-- src/input_cp2k_mp2.F | 31 +++-- src/input_cp2k_poisson.F | 9 +- src/input_cp2k_properties_dft.F | 9 +- src/input_cp2k_qmmm.F | 9 +- src/input_cp2k_qs.F | 10 +- src/input_cp2k_resp.F | 3 +- src/input_cp2k_scf.F | 24 ++-- src/input_cp2k_subsys.F | 24 ++-- src/input_cp2k_xas.F | 15 ++- src/start/cp2k_runs.F | 8 +- 28 files changed, 830 insertions(+), 178 deletions(-) create mode 100644 docs/getting-started/h2o.inp create mode 100644 docs/methods/dft/gapw_h2o.inp diff --git a/docs/getting-started/first-calculation.md b/docs/getting-started/first-calculation.md index e6d1a5f4a9..333b06d532 100644 --- a/docs/getting-started/first-calculation.md +++ b/docs/getting-started/first-calculation.md @@ -1,10 +1,139 @@ -# Run first Calculation +# Run a First Calculation -Unfortunately no one has gotten around to writing this page yet :-( +This page walks through a small single-point energy calculation for a water molecule. It uses the +{term}`Quickstep` module, the Gaussian and plane wave ({term}`GPW`) method, a molecular Gaussian +basis set, and Goedecker-Teter-Hutter ({term}`GTH`) pseudopotentials. The example is intentionally +small enough to run in a few seconds while still showing the parts of a typical CP2K input file that +matter for larger calculations. -In the meantime, the following links might be helpful: +## Input File -- +Save the following input as `h2o.inp`. The same file is also available as [](h2o.inp). + +```text +&GLOBAL + PROJECT h2o + RUN_TYPE ENERGY +&END GLOBAL + +&FORCE_EVAL + METHOD Quickstep + &DFT + BASIS_SET_FILE_NAME BASIS_MOLOPT + POTENTIAL_FILE_NAME GTH_POTENTIALS + &MGRID + CUTOFF 400 + REL_CUTOFF 50 + &END MGRID + &POISSON + PERIODIC NONE + PSOLVER MT + &END POISSON + &SCF + EPS_SCF 1.0E-6 + MAX_SCF 50 + &END SCF + &XC + &XC_FUNCTIONAL PBE + &END XC_FUNCTIONAL + &END XC + &END DFT + &SUBSYS + &CELL + ABC 10.0 10.0 10.0 + PERIODIC NONE + &END CELL + &COORD + O 5.0000 5.0000 5.0000 + H 5.7586 5.0000 5.5043 + H 4.2414 5.0000 5.5043 + &END COORD + &KIND O + BASIS_SET DZVP-MOLOPT-GTH + POTENTIAL GTH-PBE-q6 + &END KIND + &KIND H + BASIS_SET DZVP-MOLOPT-GTH + POTENTIAL GTH-PBE-q1 + &END KIND + &END SUBSYS +&END FORCE_EVAL +``` + +## Running CP2K + +Run the calculation with one of the installed CP2K binaries: + +```bash +OMP_NUM_THREADS=1 cp2k.psmp -i h2o.inp -o h2o.out +``` + +The executable name depends on how CP2K was built: + +| executable | meaning | +| ----------- | --------------------------- | +| `cp2k.psmp` | MPI + OpenMP parallel build | +| `cp2k.pdbg` | MPI + OpenMP debug build | +| `cp2k.ssmp` | serial/OpenMP build | +| `cp2k.sdbg` | serial/OpenMP debug build | + +For MPI-parallel runs, launch CP2K through the MPI launcher used on your system, for example: + +```bash +mpirun -np 2 -x OMP_NUM_THREADS=1 cp2k.psmp -i h2o.inp -o h2o.out +``` + +`cp2k.psmp` supports both MPI and OpenMP. Setting `OMP_NUM_THREADS=1` keeps this first example in a +simple MPI-only layout. To see the output on screen while also saving it, replace `-o h2o.out` with +`| tee h2o.out`. + +## What the Input Does + +[RUN_TYPE](#CP2K_INPUT.GLOBAL.RUN_TYPE) is set to `ENERGY`, so CP2K evaluates the electronic ground +state energy without moving the atoms. + +[METHOD](#CP2K_INPUT.FORCE_EVAL.METHOD) selects `Quickstep`, CP2K's electronic-structure module for +Gaussian-based density functional theory and related methods. + +`BASIS_SET_FILE_NAME` and `POTENTIAL_FILE_NAME` tell CP2K where to find the basis-set and +pseudopotential libraries. The matching [KIND](#CP2K_INPUT.FORCE_EVAL.SUBSYS.KIND) sections then +choose one Gaussian basis set and one GTH pseudopotential for each element. + +[CUTOFF](#CP2K_INPUT.FORCE_EVAL.DFT.MGRID.CUTOFF) and +[REL_CUTOFF](#CP2K_INPUT.FORCE_EVAL.DFT.MGRID.REL_CUTOFF) control the real-space integration grids +used by the GPW method. They are not a replacement for increasing the Gaussian basis quality; for +accurate work the basis set and grid parameters should be converged together. + +The [POISSON](#CP2K_INPUT.FORCE_EVAL.DFT.POISSON) section and the +[CELL](#CP2K_INPUT.FORCE_EVAL.SUBSYS.CELL) section both use `PERIODIC NONE`, which is appropriate +for this isolated molecule in a large non-periodic box. + +## Checking the Result + +At the end of `h2o.out`, CP2K prints the total energy in Hartree: + +```text +ENERGY| Total FORCE_EVAL ( QS ) energy [hartree] +``` + +You should also see a line stating that the self-consistent field ({term}`SCF`) cycle converged. If +the SCF cycle does not converge, increase `MAX_SCF`, improve the initial guess, or use a more robust +SCF setup. + +The timing table printed at the end of every CP2K run is useful for a first performance check. For +larger calculations, compare timings between MPI/OpenMP layouts and watch whether most of the time +is spent in grid operations, sparse matrix operations, diagonalization, or communication. + +## Next Steps + +- Converge [CUTOFF](#CP2K_INPUT.FORCE_EVAL.DFT.MGRID.CUTOFF) and + [REL_CUTOFF](#CP2K_INPUT.FORCE_EVAL.DFT.MGRID.REL_CUTOFF): [](../methods/dft/cutoff) +- Learn the idea behind GPW: [](../methods/dft/gpw) +- Learn about basis sets and pseudopotentials: [](../methods/dft/basis_sets), + [](../methods/dft/pseudopotentials) +- Build or install CP2K: [](build-from-source), [](build-with-spack), [](distributions) +- Explore more complete examples: +- Read the practical CP2K overview paper: [](#Iannuzzi2026) ```{youtube} qMR-NAaUheg --- diff --git a/docs/getting-started/h2o.inp b/docs/getting-started/h2o.inp new file mode 100644 index 0000000000..c401d5ece3 --- /dev/null +++ b/docs/getting-started/h2o.inp @@ -0,0 +1,47 @@ +&GLOBAL + PROJECT h2o + RUN_TYPE ENERGY +&END GLOBAL + +&FORCE_EVAL + METHOD Quickstep + &DFT + BASIS_SET_FILE_NAME BASIS_MOLOPT + POTENTIAL_FILE_NAME GTH_POTENTIALS + &MGRID + CUTOFF 400 + REL_CUTOFF 50 + &END MGRID + &POISSON + PERIODIC NONE + PSOLVER MT + &END POISSON + &SCF + EPS_SCF 1.0E-6 + MAX_SCF 50 + &END SCF + &XC + &XC_FUNCTIONAL PBE + &END XC_FUNCTIONAL + &END XC + &END DFT + &SUBSYS + &CELL + ABC 10.0 10.0 10.0 + PERIODIC NONE + &END CELL + &COORD + O 5.0000 5.0000 5.0000 + H 5.7586 5.0000 5.5043 + H 4.2414 5.0000 5.5043 + &END COORD + &KIND O + BASIS_SET DZVP-MOLOPT-GTH + POTENTIAL GTH-PBE-q6 + &END KIND + &KIND H + BASIS_SET DZVP-MOLOPT-GTH + POTENTIAL GTH-PBE-q1 + &END KIND + &END SUBSYS +&END FORCE_EVAL diff --git a/docs/methods/dft/basis_sets.md b/docs/methods/dft/basis_sets.md index 733350aa90..f24e4a571e 100644 --- a/docs/methods/dft/basis_sets.md +++ b/docs/methods/dft/basis_sets.md @@ -1,10 +1,103 @@ # Basis Sets -Unfortunately no one has gotten around to writing this page yet :-( +In CP2K's {term}`Quickstep` module, the Kohn-Sham orbitals are expanded in atom-centered Gaussian +basis functions. This is different from pure plane-wave codes: increasing the real-space grid +[CUTOFF](#CP2K_INPUT.FORCE_EVAL.DFT.MGRID.CUTOFF) improves the auxiliary plane-wave representation +of densities and potentials, but it does not by itself reach the complete basis set limit. For +systematic convergence, the Gaussian basis quality and the grid parameters have to be considered +together. -In the meantime, the following links might be helpful: +Basis sets are selected for each atomic [KIND](#CP2K_INPUT.FORCE_EVAL.SUBSYS.KIND). The files that +contain the basis definitions are listed in +[BASIS_SET_FILE_NAME](#CP2K_INPUT.FORCE_EVAL.DFT.BASIS_SET_FILE_NAME). CP2K searches these files in +the current directory and in the configured CP2K data directory. + +```text +&FORCE_EVAL + &DFT + BASIS_SET_FILE_NAME BASIS_MOLOPT + &END DFT + &SUBSYS + &KIND O + BASIS_SET DZVP-MOLOPT-GTH + &END KIND + &KIND H + BASIS_SET DZVP-MOLOPT-GTH + &END KIND + &END SUBSYS +&END FORCE_EVAL +``` + +## Basis Set Names + +Many CP2K basis sets encode their purpose in the name: + +- `SZV`, `DZVP`, `TZVP`, `TZV2P`, and `QZVPP` indicate increasing basis quality. +- `MOLOPT` basis sets are molecularly optimized Gaussian basis sets commonly used with GPW. +- `SR` indicates short-range MOLOPT variants. They are less diffuse and often more efficient for + large condensed-phase systems when the target property does not require diffuse functions. +- `GTH` basis sets are intended for GTH pseudopotential calculations. +- `q1`, `q4`, `q6`, and similar suffixes indicate the number of valence electrons represented by the + matching pseudopotential. +- `ae` basis sets are all-electron basis sets, commonly used with the GAPW method and + `POTENTIAL ALL`. + +For production calculations, use basis sets and pseudopotentials that were designed to work +together. For example, `DZVP-MOLOPT-GTH` for oxygen is normally paired with `GTH-PBE-q6` in a PBE +calculation, while UZH protocol basis sets from `BASIS_MOLOPT_UZH` are paired with corresponding +entries from `POTENTIAL_UZH`. For new GPW production inputs, these UZH protocol pairs are the +preferred starting point where available; the older MOLOPT/GTH libraries remain useful for +compatibility and comparison with established inputs. The same `BASIS_MOLOPT_UZH` file also contains +all-electron MOLOPT basis sets for GAPW simulations, such as `SVP-MOLOPT-GGA-ae`, +`TZVPP-MOLOPT-GGA-ae`, and `QZVPP-MOLOPT-GGA-ae`, to be used with `POTENTIAL ALL`. + +## Basis Set Roles + +The keyword [BASIS_SET](#CP2K_INPUT.FORCE_EVAL.SUBSYS.KIND.BASIS_SET) can carry an optional basis +type. Without an explicit type, CP2K uses the primary orbital basis: + +```text +&KIND O + BASIS_SET ORB DZVP-MOLOPT-GTH +&END KIND +``` + +This is equivalent to the more common short form: + +```text +&KIND O + BASIS_SET DZVP-MOLOPT-GTH +&END KIND +``` + +Other basis roles are used by specific methods, for example: + +- `AUX_FIT` for the auxiliary density matrix method. +- `RI_AUX` for resolution-of-the-identity correlation methods. +- `LRI` for local resolution-of-the-identity approaches. + +The method-specific documentation usually states which auxiliary basis is required. + +## Convergence and Practical Choices + +Start with a basis set that is appropriate for the target accuracy, then converge the grid +parameters. For many routine condensed-phase GPW calculations, double-zeta or triple-zeta MOLOPT +basis sets are common starting points. For new setups, first check whether a matching UZH protocol +basis and pseudopotential pair is available. Accurate energy differences, weak interactions, +response properties, and post-Hartree-Fock methods may require larger or more specialized basis +sets. + +Diffuse basis functions can improve accuracy for molecular anions, excited states, polarizabilities, +and weak interactions, but they also increase the cost and may make the overlap matrix more +ill-conditioned. In periodic calculations, diffuse functions can also increase the number of +periodic images that have to be considered. + +For a simple tested example, see [](../../getting-started/first-calculation). + +## See Also - - - - [](#VandeVondele2007) +- [](#Iannuzzi2026) diff --git a/docs/methods/dft/gapw.md b/docs/methods/dft/gapw.md index cf3d7fb909..dcba9c1831 100644 --- a/docs/methods/dft/gapw.md +++ b/docs/methods/dft/gapw.md @@ -1,11 +1,82 @@ # Gaussian Augmented Plane Waves -Unfortunately no one has gotten around to writing this page yet :-( +The Gaussian augmented plane wave ({term}`GAPW`) method extends GPW so that all-electron +calculations and calculations with very small-core pseudopotentials become practical in CP2K. The +central idea is to keep the smooth part of the density on the regular GPW grids while treating the +rapidly varying density close to the nuclei with atom-centered contributions. -In the meantime, the following links might be helpful: +GAPW is useful when the core electron density matters, for example in all-electron calculations, +core-level spectroscopy, magnetic properties, and some small-core pseudopotential setups. For +standard valence-only pseudopotential DFT calculations, GPW is usually simpler and faster. + +## Activating GAPW + +GAPW is activated in the [QS](#CP2K_INPUT.FORCE_EVAL.DFT.QS) section: + +```text +&FORCE_EVAL + METHOD Quickstep + &DFT + &QS + METHOD GAPW + &END QS + &END DFT +&END FORCE_EVAL +``` + +All-electron GAPW calculations also require all-electron basis sets and `POTENTIAL ALL` for the +corresponding atomic kinds: + +```text +&KIND O + BASIS_SET SVP-MOLOPT-GGA-ae + POTENTIAL ALL + LEBEDEV_GRID 110 + RADIAL_GRID 80 +&END KIND +``` + +A complete tested water example is available as [](gapw_h2o.inp). It is intentionally small and is +meant as a starting point rather than as a production-quality benchmark. + +## Accuracy Parameters + +Several GAPW-specific tolerances control the split between soft grid-based and hard atom-centered +contributions: + +- [EPSFIT](#CP2K_INPUT.FORCE_EVAL.DFT.QS.EPSFIT) controls how Gaussian exponents are split into the + hard and soft parts. Lowering it includes harder functions in the soft density and usually + requires a larger [CUTOFF](#CP2K_INPUT.FORCE_EVAL.DFT.MGRID.CUTOFF). +- [EPSRHO0](#CP2K_INPUT.FORCE_EVAL.DFT.QS.EPSRHO0) controls the range used for the hard compensation + density contribution. +- [EPSSVD](#CP2K_INPUT.FORCE_EVAL.DFT.QS.EPSSVD) controls the singular value decomposition tolerance + used for projector matrices. + +The atom-centered integration grid is controlled per kind with +[LEBEDEV_GRID](#CP2K_INPUT.FORCE_EVAL.SUBSYS.KIND.LEBEDEV_GRID) and +[RADIAL_GRID](#CP2K_INPUT.FORCE_EVAL.SUBSYS.KIND.RADIAL_GRID). Increasing these values can improve +the electron count and the accuracy of properties that depend on the near-core density, but it also +increases cost. + +## Practical Guidance + +When setting up a GAPW calculation: + +- Use an all-electron basis set for `POTENTIAL ALL`, or a basis set designed for the chosen + small-core pseudopotential. +- Inspect the electron count printed by CP2K after SCF convergence. It is a useful diagnostic for + the quality of the hard/soft density split. +- Tighten `EPSFIT`, `EPSRHO0`, `EPSSVD`, and the atomic grids only as much as needed for the target + property. +- Increase the density [CUTOFF](#CP2K_INPUT.FORCE_EVAL.DFT.MGRID.CUTOFF) when harder Gaussian + exponents are included in the soft density. +- Prefer GPW when the calculation does not need all-electron or near-core accuracy. + +## See Also - [](#Lippert1999) -- [](#VandeVondele2006) +- [](#Krack2000) +- [](#Iannuzzi2026) ```{youtube} L0hKLjvjIFU --- diff --git a/docs/methods/dft/gapw_h2o.inp b/docs/methods/dft/gapw_h2o.inp new file mode 100644 index 0000000000..601100e3e5 --- /dev/null +++ b/docs/methods/dft/gapw_h2o.inp @@ -0,0 +1,56 @@ +&GLOBAL + PROJECT gapw_h2o + RUN_TYPE ENERGY +&END GLOBAL + +&FORCE_EVAL + METHOD Quickstep + &DFT + BASIS_SET_FILE_NAME BASIS_MOLOPT_UZH + &MGRID + CUTOFF 800 + REL_CUTOFF 80 + &END MGRID + &POISSON + PERIODIC NONE + PSOLVER MT + &END POISSON + &QS + EPSFIT 1.0E-6 + EPSRHO0 1.0E-8 + EPSSVD 1.0E-10 + METHOD GAPW + &END QS + &SCF + EPS_SCF 1.0E-6 + MAX_SCF 50 + &END SCF + &XC + &XC_FUNCTIONAL PBE + &END XC_FUNCTIONAL + &END XC + &END DFT + &SUBSYS + &CELL + ABC 10.0 10.0 10.0 + PERIODIC NONE + &END CELL + &COORD + O 5.0000 5.0000 5.0000 + H 5.7586 5.0000 5.5043 + H 4.2414 5.0000 5.5043 + &END COORD + &KIND O + BASIS_SET SVP-MOLOPT-GGA-ae + LEBEDEV_GRID 110 + POTENTIAL ALL + RADIAL_GRID 80 + &END KIND + &KIND H + BASIS_SET SVP-MOLOPT-GGA-ae + LEBEDEV_GRID 110 + POTENTIAL ALL + RADIAL_GRID 80 + &END KIND + &END SUBSYS +&END FORCE_EVAL diff --git a/docs/methods/dft/gpw.md b/docs/methods/dft/gpw.md index 07ef6a4283..42b658ae91 100644 --- a/docs/methods/dft/gpw.md +++ b/docs/methods/dft/gpw.md @@ -36,7 +36,8 @@ e -- "Integrate" --> f - - -- [](#VandeVondele2005) +- [](#Lippert1997) +- [](#K%C3%BChne2020) ```{youtube} v2vnZbhNEpw --- diff --git a/docs/methods/dft/hartree-fock/admm.md b/docs/methods/dft/hartree-fock/admm.md index 4b87136322..12927b384a 100644 --- a/docs/methods/dft/hartree-fock/admm.md +++ b/docs/methods/dft/hartree-fock/admm.md @@ -1,11 +1,94 @@ # HFX with ADMM -Unfortunately no one has gotten around to writing this page yet :-( +The auxiliary density matrix method ({term}`ADMM`) reduces the cost of Hartree-Fock exchange in +hybrid DFT calculations by projecting the density matrix from the primary orbital basis onto a +smaller auxiliary basis. CP2K evaluates exact exchange in the auxiliary basis and adds a correction +term for the difference between the primary and auxiliary exchange descriptions. -In the meantime, the following links might be helpful: +ADMM is most useful when exact exchange is the bottleneck, especially with larger or more diffuse +Gaussian basis sets. It is commonly used for hybrid DFT, and the ADMM2 variant is also supported by +several post-SCF methods that reuse exact-exchange machinery. + +## Basic Setup + +An ADMM calculation needs three pieces of input: + +- a hybrid functional or another setup that evaluates Hartree-Fock exchange, +- an auxiliary basis set for each atomic kind, specified with `BASIS_SET AUX_FIT`, +- an [AUXILIARY_DENSITY_MATRIX_METHOD](#CP2K_INPUT.FORCE_EVAL.DFT.AUXILIARY_DENSITY_MATRIX_METHOD) + section that selects the ADMM variant and correction functional. + +For example: + +```text +&DFT + BASIS_SET_FILE_NAME BASIS_MOLOPT_UZH + BASIS_SET_FILE_NAME BASIS_ADMM_UZH + POTENTIAL_FILE_NAME POTENTIAL_UZH + &AUXILIARY_DENSITY_MATRIX_METHOD + ADMM_TYPE ADMMS + EXCH_CORRECTION_FUNC PBEX + &END AUXILIARY_DENSITY_MATRIX_METHOD + &XC + &XC_FUNCTIONAL PBE + &END XC_FUNCTIONAL + &HF + FRACTION 0.25 + &END HF + &END XC +&END DFT + +&SUBSYS + &KIND O + BASIS_SET ccGRB-D-q6 + BASIS_SET AUX_FIT admm-dz-q6 + POTENTIAL GTH-HYB-q6 + &END KIND +&END SUBSYS +``` + +## Choosing the Auxiliary Basis + +The auxiliary basis should be chosen for the primary basis family and for the intended accuracy. For +MOLOPT-style calculations, the `BASIS_ADMM_MOLOPT` family provides compact auxiliary bases. The +newer UZH basis-set collection includes `BASIS_ADMM_UZH` and related basis files for correlation +consistent setups. All-electron calculations can use all-electron auxiliary basis sets when +available. + +The auxiliary basis is part of the approximation. A too small auxiliary basis can make the exchange +correction large and reduce accuracy; a too large one gives back less speedup. For production work, +test at least one larger auxiliary basis or compare against a smaller reference system without ADMM. + +## Choosing the ADMM Variant + +[ADMM_TYPE](#CP2K_INPUT.FORCE_EVAL.DFT.AUXILIARY_DENSITY_MATRIX_METHOD.ADMM_TYPE) is a shortcut that +sets the projection, purification, and scaling options consistently. `ADMM1` and `ADMM2` are the +original variants, while `ADMMS`, `ADMMP`, and `ADMMQ` use additional models introduced later. +`ADMM2` is often the most broadly supported variant for workflows beyond ground-state hybrid DFT. + +The +[EXCH_CORRECTION_FUNC](#CP2K_INPUT.FORCE_EVAL.DFT.AUXILIARY_DENSITY_MATRIX_METHOD.EXCH_CORRECTION_FUNC) +keyword selects the exchange functional used for the ADMM correction. It should be chosen +consistently with the exchange part of the main exchange-correlation setup; `PBEX` is a common +choice for PBE-based hybrid calculations. + +## Practical Checks + +When using ADMM: + +- keep the same primary basis and potential convergence checks that would be used without ADMM, +- check the sensitivity to the auxiliary basis size, +- compare total energies, forces, or target properties against a non-ADMM reference for a small + representative system, +- remember that ADMM accelerates the exchange calculation but does not replace convergence of the + primary Gaussian basis, real-space grid, or SCF thresholds. + +## See Also - [](#Guidon2009) - [](#Guidon2010) +- [](#Merlot2014) +- [](#Iannuzzi2026) ```{youtube} snG4fbpI0_g --- diff --git a/docs/methods/dft/index.md b/docs/methods/dft/index.md index d694f047e3..6d56340463 100644 --- a/docs/methods/dft/index.md +++ b/docs/methods/dft/index.md @@ -18,9 +18,23 @@ pseudopotentials cutoff ``` -```{youtube} kYxOWYWxYcQ +Density functional theory in CP2K is primarily provided by the Quickstep module. Most production +calculations use the Gaussian and plane waves (GPW) method with Gaussian basis sets, +pseudopotentials, and real-space grids for densities and potentials. The Gaussian augmented plane +waves (GAPW) method extends the same framework to all-electron and more core-sensitive calculations. + +For new inputs, first choose a consistent basis-set and potential pair, then converge the MGRID +cutoffs and the SCF settings for the target property. The pages in this section collect the main +Quickstep ingredients: GPW/GAPW, hybrid functionals and ADMM, local RI, constraints, k-points, basis +sets, pseudopotentials, and grid convergence. + +## References + +- [](#K%C3%BChne2020) +- [](#Iannuzzi2026) + +```{youtube} 3Cw4h3MrZ8k --- -url_parameters: ?start=216 align: center privacy_mode: --- diff --git a/docs/methods/dft/pseudopotentials.md b/docs/methods/dft/pseudopotentials.md index 22f07c90f9..77a0b22503 100644 --- a/docs/methods/dft/pseudopotentials.md +++ b/docs/methods/dft/pseudopotentials.md @@ -1,8 +1,80 @@ # Pseudopotentials -Unfortunately no one has gotten around to writing this page yet :-( +Most GPW calculations in CP2K use norm-conserving Goedecker-Teter-Hutter ({term}`GTH`) +pseudopotentials. A pseudopotential removes chemically inactive core electrons from the explicit +electronic problem and represents their effect on the valence electrons through an effective +potential. This reduces the number of electrons and avoids the very hard core density that would +otherwise require extremely fine grids. -In the meantime, the following links might be helpful: +Pseudopotential files are selected in +[POTENTIAL_FILE_NAME](#CP2K_INPUT.FORCE_EVAL.DFT.POTENTIAL_FILE_NAME), and the actual potential is +selected for each atomic [KIND](#CP2K_INPUT.FORCE_EVAL.SUBSYS.KIND) with +[POTENTIAL](#CP2K_INPUT.FORCE_EVAL.SUBSYS.KIND.POTENTIAL): + +```text +&FORCE_EVAL + &DFT + POTENTIAL_FILE_NAME GTH_POTENTIALS + &END DFT + &SUBSYS + &KIND O + POTENTIAL GTH-PBE-q6 + &END KIND + &KIND H + POTENTIAL GTH-PBE-q1 + &END KIND + &END SUBSYS +&END FORCE_EVAL +``` + +The suffix `q6` in `GTH-PBE-q6`, for example, means that six valence electrons are treated +explicitly. The chosen basis set should match this valence configuration; for oxygen, a common +matching basis is `DZVP-MOLOPT-GTH`. + +## Choosing a Pseudopotential + +Use a pseudopotential generated for the exchange-correlation functional family used in the +calculation. For example, `GTH-PBE-q6` is a natural choice for PBE calculations with oxygen. Mixing +functional families can be acceptable for exploratory work in some cases, but it is not a systematic +route to high accuracy. + +The CP2K data directory contains several pseudopotential libraries: + +- `GTH_POTENTIALS` contains widely used GTH potentials for common GPW calculations. +- `POTENTIAL_UZH` contains the UZH protocol GTH potentials designed to be used with matching UZH + basis sets. +- `NLCC_POTENTIALS` and `GTH_SOC_POTENTIALS` contain more specialized potentials. +- `ECP_POTENTIALS` contains effective core potentials for Gaussian integral based calculations. + +For new GPW production inputs, prefer a matching UZH protocol pair from `POTENTIAL_UZH` and +`BASIS_MOLOPT_UZH` when it is available for the element and functional family. The older +`GTH_POTENTIALS` library remains important for reproducing established calculations and for cases +where a matching UZH setup is not available. + +For all-electron calculations, use `POTENTIAL ALL` together with an all-electron basis set and the +GAPW method: + +```text +&KIND O + BASIS_SET SVP-MOLOPT-GGA-ae + POTENTIAL ALL +&END KIND +``` + +## Consistency Checks + +Useful checks when setting up a calculation are: + +- The basis set and pseudopotential should be available in the files named in the `DFT` section. +- The pseudopotential valence charge should match the basis set suffix where such a suffix is used. +- The exchange-correlation functional should be consistent with the pseudopotential family. +- For heavy elements, decide whether a large-core, medium-core, small-core, or all-electron + description is appropriate for the property of interest. + +For a tested minimal GPW input using GTH pseudopotentials, see +[](../../getting-started/first-calculation). + +## See Also - - @@ -10,3 +82,4 @@ In the meantime, the following links might be helpful: - [](#Goedecker1996) - [](#Hartwigsen1998) - [](#Krack2005) +- [](#Iannuzzi2026) diff --git a/docs/methods/post_hartree_fock/index.md b/docs/methods/post_hartree_fock/index.md index c373c65aca..b3726bc09a 100644 --- a/docs/methods/post_hartree_fock/index.md +++ b/docs/methods/post_hartree_fock/index.md @@ -11,17 +11,21 @@ rpa low-scaling ``` -```{youtube} paM4lPL_-aI ---- -url_parameters: ?start=115 -align: center -privacy_mode: ---- -``` +Post-Hartree-Fock methods in CP2K add wavefunction-based correlation, quasiparticle, or response +corrections on top of a converged reference calculation. The reference is usually Hartree-Fock, a +hybrid functional, or semilocal DFT, depending on the target method and property. -```{youtube} 1vUuethWhbs +Start with the [preliminaries](preliminaries) page when setting up MP2, RPA, or related methods. It +explains the common choices for primary and RI basis sets, pseudopotentials, reference orbitals, +memory layout, and GPW-based integral grids. The method-specific pages then cover canonical and +RI-MP2, RPA and SOS-MP2, and the low-scaling implementations for larger systems. + +These methods are considerably more expensive than semilocal DFT. For production work, converge the +reference calculation first, then check basis-set size, auxiliary basis or auto-generated RI basis +settings, quadrature parameters, and memory distribution. + +```{youtube} wyux20qVlck --- -url_parameters: ?start=10 align: center privacy_mode: --- diff --git a/docs/methods/qm_mm/gromacs.md b/docs/methods/qm_mm/gromacs.md index 272108d476..bf665ef2c6 100644 --- a/docs/methods/qm_mm/gromacs.md +++ b/docs/methods/qm_mm/gromacs.md @@ -1,10 +1,41 @@ -# QM/MM with Gromacs +# QM/MM with GROMACS -Unfortunately no one has gotten around to writing this page yet :-( +GROMACS can use CP2K as a quantum-mechanical engine for QM/MM simulations. In such workflows, +GROMACS handles the classical molecular mechanics model, topology, constraints, and sampling +machinery, while CP2K evaluates the electronic structure of the selected QM region and returns +energies and forces. -In the meantime, the following links might be helpful: +This setup is useful when the chemically active part of a system must be described with +electronic-structure methods, but the surrounding solvent, biomolecule, or material environment is +too large for a full QM treatment. Typical applications include reactions in enzymes, solvated +molecular complexes, and embedded active sites. -- [Installation guide](https://manual.gromacs.org/current/install-guide/index.html#building-with-cp2k-qm-mm-support) +## Setup Outline + +1. Build GROMACS with CP2K QM/MM support and make sure it can find the CP2K executable and data + directory. +1. Prepare and equilibrate the classical system with ordinary GROMACS tools. +1. Select the QM atoms and provide a CP2K input fragment for the quantum region. +1. Choose the coupling model, charge treatment, and boundary handling consistently with the target + system. +1. Start from short test trajectories and inspect both the GROMACS and CP2K output before running + production simulations. + +The CP2K part follows the same Quickstep setup principles as a standalone calculation: choose +compatible basis sets and pseudopotentials, converge the real-space grid, and use SCF settings that +are robust for the geometry changes expected during the trajectory. + +```{youtube} zSt8KQ2Hf3c +--- +align: center +privacy_mode: +--- +``` + +## External Resources + +- [Installation guide](https://manual.gromacs.org/current/install-guide/) (see the CP2K QM/MM build + instructions) - [Best practices guide](https://docs.bioexcel.eu/qmmm_bpg/en/main/index.html) - [Gromacs manual](https://manual.gromacs.org/current/reference-manual/special/qmmm.html) - [Tutorial](https://github.com/bioexcel/gromacs-2022-cp2k-tutorial) diff --git a/src/common/bibliography.F b/src/common/bibliography.F index e5957772f5..cf054da7ea 100644 --- a/src/common/bibliography.F +++ b/src/common/bibliography.F @@ -81,7 +81,7 @@ MODULE bibliography Clabaut2021, Ren2011, Ren2013, Cohen2000, Rogers2002, Filippetti2000, & Limpanuparb2011, Martin2003, Yin2017, Goerigk2017, & Wilhelm2016a, Wilhelm2016b, Wilhelm2017, Wilhelm2018, Wilhelm2021, Lass2018, & - cp2kqs2020, Behler2007, Behler2011, Schran2020a, Schran2020b, & + cp2kqs2020, Iannuzzi2026, Behler2007, Behler2011, Schran2020a, Schran2020b, & Rycroft2009, Thomas2015, Brehm2018, Brehm2020, Shigeta2001, Heinecke2016, & Brehm2021, Bussy2021a, Bussy2021b, Ditler2021, Ditler2022, Mattiat2019, & Mattiat2022, Belleflamme2023, Knizia2013, Musaelian2023, Eriksen2020, & @@ -835,7 +835,7 @@ CONTAINS title="Efficient and accurate Car-Parrinello-like approach to "// & "Born-Oppenheimer molecular dynamics", & source="Phys. Rev. Lett.", volume="98", pages="066401", & - year=2007, doi="10.1103/PhysRevLett.98.066401") + year=2007, doi="10.1103/PhysRevLett.98.066401", citation_key="Kühne2007") CALL add_reference(key=Rengaraj2020, & authors=s2a("V. Rengaraj", "M. Lass", "C. Plessl", "T. D. Kuhne"), & @@ -1520,7 +1520,7 @@ CONTAINS year=2021) CALL add_reference(key=Richters2018, & - authors=s2a("D. Richters", "M. Lass", "A. Walther", "C. Plessl", "T. D. Kuehne"), & + authors=s2a("D. Richters", "M. Lass", "A. Walther", "C. Plessl", "T. D. Kühne"), & title="A General Algorithm to Calculate the Inverse Principal p-th Root of "// & "Symmetric Positive Definite Matrices", & source="Commun. Comput. Phys.", volume="25", pages="564-585", & @@ -1623,27 +1623,39 @@ CONTAINS year=2021, doi="10.1021/acs.jctc.0c01282") CALL add_reference(key=Lass2018, & - authors=s2a("M. Lass", "S. Mohr", "H. Wiebeler", "T. D. Kuehne", "C. Plessl"), & + authors=s2a("M. Lass", "S. Mohr", "H. Wiebeler", "T. D. Kühne", "C. Plessl"), & title="A Massively Parallel Algorithm for the Approximate Calculation of "// & "Inverse P-Th Roots of Large Sparse Matrices", & source="Proceedings of the Platform for Advanced Scientific Computing (PASC) Conference", & year=2018, doi="10.1145/3218176.3218231") CALL add_reference(key=cp2kqs2020, & - authors=s2a("T. D. Kuehne", "M. Iannuzzi", "M. Del Ben", "V. V. Rybkin", & + authors=s2a("T. D. Kühne", "M. Iannuzzi", "M. Del Ben", "V. V. Rybkin", & "P. Seewald", "F. Stein", "T. Laino", "R. Z. Khaliullin", & - "O. Schuett", "F. Schiffmann", "D. Golze", "J. Wilhelm", & + "O. Schütt", "F. Schiffmann", "D. Golze", "J. Wilhelm", & "S. Chulkov", "M. H. Bani-Hashemian", "V. Weber", & "U. Borstnik", "M. Taillefumier", "A. S. Jakobovits", & - "A. Lazzaro", "H. Pabst", "T. Mueller", "R. Schade", "M. Guidon", & + "A. Lazzaro", "H. Pabst", "T. Müller", "R. Schade", "M. Guidon", & "S. Andermatt", "N. Holmberg", "G. K. Schenter", "A. Hehn", & - "A. Bussy", "F. Belleflamme", "G. Tabacchi", "A. Gloess", & + "A. Bussy", "F. Belleflamme", "G. Tabacchi", "A. Glöß", & "M. Lass", "I. Bethune", "C. J. Mundy", "C. Plessl", & "M. Watkins", "J. VandeVondele", "M. Krack", "J. Hutter"), & title="CP2K: An electronic structure and molecular dynamics software package - Quickstep: "// & "Efficient and accurate electronic structure calculations", & source="J. Chem. Phys.", volume="152", pages="194103", & - year=2020, doi="10.1063/5.0007045") + year=2020, doi="10.1063/5.0007045", citation_key="Kühne2020") + + CALL add_reference(key=Iannuzzi2026, & + authors=s2a("M. Iannuzzi", "J. Wilhelm", "F. Stein", "A. Bussy", & + "H. Elgabarty", "D. Golze", "A. Hehn", "M. Graml", & + "S. Marek", "B. Sertcan Gökmen", "C. Schran", "H. Forbert", & + "R. Z. Khaliullin", "A. Kozhevnikov", "M. Taillefumier", & + "R. Meli", "V. V. Rybkin", "M. Brehm", "R. Schade", "O. Schütt", & + "J. V. Pototschnig", "H. Mirhosseini", "A. Knüpfer", "D. Marx", & + "M. Krack", "J. Hutter", "T. D. Kühne"), & + title="The CP2K Program Package Made Simple", & + source="J. Phys. Chem. B", volume="130", pages="1237-1310", & + year=2026, doi="10.1021/acs.jpcb.5c05851") CALL add_reference(key=Rycroft2009, & authors=s2a("C. H. Rycroft"), & diff --git a/src/common/reference_manager.F b/src/common/reference_manager.F index bb7f986040..f900554659 100644 --- a/src/common/reference_manager.F +++ b/src/common/reference_manager.F @@ -121,22 +121,23 @@ CONTAINS !> \param pages ... !> \param year ... !> \param doi ... +!> \param citation_key ... !> \par History !> 08.2007 created [Joost VandeVondele] !> 07.2024 complete rewrite [Ole Schuett] !> \note !> - see bibliography.F for it use. ! ************************************************************************************************** - SUBROUTINE add_reference(key, authors, title, source, volume, pages, year, doi) + SUBROUTINE add_reference(key, authors, title, source, volume, pages, year, doi, citation_key) INTEGER, INTENT(OUT) :: key CHARACTER(LEN=*), DIMENSION(:), INTENT(IN) :: authors CHARACTER(LEN=*), INTENT(IN) :: title, source CHARACTER(LEN=*), INTENT(IN), OPTIONAL :: volume, pages INTEGER, INTENT(IN) :: year - CHARACTER(LEN=*), INTENT(IN), OPTIONAL :: doi + CHARACTER(LEN=*), INTENT(IN), OPTIONAL :: doi, citation_key CHARACTER :: tmp - CHARACTER(LEN=default_string_length) :: author, citation_key, key_a, key_b + CHARACTER(LEN=default_string_length) :: author, citation_key_, key_a, key_b INTEGER :: i, ires, match, mylen, periodloc IF (nbib + 1 > max_reference) CPABORT("increase max_reference") @@ -168,29 +169,35 @@ CONTAINS thebib(key)%ref%doi = TRIM(doi) END IF - ! construct a citation_key - author = authors(1) - periodloc = INDEX(author, '.', back=.TRUE.) - IF (periodloc > 0) author = author(periodloc + 1:) - CPASSERT(LEN_TRIM(author) > 0) - WRITE (citation_key, '(A,I4)') TRIM(author), year + IF (PRESENT(citation_key)) THEN + citation_key_ = citation_key + CPASSERT(LEN_TRIM(citation_key_) > 4) + ELSE + ! construct a citation_key + author = authors(1) + periodloc = INDEX(author, '.', back=.TRUE.) + IF (periodloc > 0) author = author(periodloc + 1:) + CPASSERT(LEN_TRIM(author) > 0) + WRITE (citation_key_, '(A,I4)') TRIM(author), year - ! avoid special characters in names, just remove them - mylen = LEN_TRIM(citation_key) - ires = 0 - DO I = 1, mylen - IF (INDEX("0123456789thequickbrownfoxjumpsoverthelazydogTHEQUICKBROWNFOXJUMPSOVERTHELAZYDOG", citation_key(i:i)) /= 0) THEN - ires = ires + 1 - tmp = citation_key(i:i) - citation_key(ires:ires) = tmp - END IF - END DO - citation_key(ires + 1:) = "" - CPASSERT(LEN_TRIM(citation_key) > 4) ! At least one character of the author should be left. + ! avoid special characters in names, just remove them + mylen = LEN_TRIM(citation_key_) + ires = 0 + DO I = 1, mylen + IF (INDEX("0123456789thequickbrownfoxjumpsoverthelazydogTHEQUICKBROWNFOXJUMPSOVERTHELAZYDOG", & + citation_key_(i:i)) /= 0) THEN + ires = ires + 1 + tmp = citation_key_(i:i) + citation_key_(ires:ires) = tmp + END IF + END DO + citation_key_(ires + 1:) = "" + CPASSERT(LEN_TRIM(citation_key_) > 4) ! At least one character of the author should be left. + END IF ! avoid duplicates, search through the list for matches (case-insensitive) - mylen = LEN_TRIM(citation_key) - key_a = citation_key(1:mylen) + mylen = LEN_TRIM(citation_key_) + key_a = citation_key_(1:mylen) CALL uppercase(key_a) match = 0 DO I = 1, nbib - 1 @@ -198,10 +205,16 @@ CONTAINS CALL uppercase(key_b) IF (key_a == key_b) match = match + 1 END DO - IF (match > 0) citation_key = citation_key(1:mylen)//CHAR(ICHAR('a') + match) + IF (match > 0) THEN + IF (PRESENT(citation_key)) THEN + CPABORT("explicit citation key already exists") + ELSE + citation_key_ = citation_key_(1:mylen)//CHAR(ICHAR('a') + match) + END IF + END IF ! finally store it - thebib(key)%ref%citation_key = citation_key + thebib(key)%ref%citation_key = citation_key_ END SUBROUTINE add_reference diff --git a/src/input_cp2k_dft.F b/src/input_cp2k_dft.F index 1933843d6f..69049c36ce 100644 --- a/src/input_cp2k_dft.F +++ b/src/input_cp2k_dft.F @@ -126,12 +126,14 @@ CONTAINS CPASSERT(.NOT. ASSOCIATED(section)) CALL section_create(section, __LOCATION__, name="DFT", & - description="Parameter needed by LCAO DFT programs", & + description="Controls electronic-structure settings for Quickstep and related "// & + "Gaussian-basis DFT methods.", & n_keywords=3, n_subsections=4, repeats=.FALSE.) NULLIFY (keyword) CALL keyword_create(keyword, __LOCATION__, name="BASIS_SET_FILE_NAME", & - description="Name of the basis set file, may include a path", & + description="Name of a basis-set library file, optionally including a path. "// & + "This keyword can be repeated to search several basis-set files.", & usage="BASIS_SET_FILE_NAME ", & type_of_var=lchar_t, repeats=.TRUE., & default_lc_val="BASIS_SET", n_var=1) @@ -139,7 +141,8 @@ CONTAINS CALL keyword_release(keyword) CALL keyword_create(keyword, __LOCATION__, name="POTENTIAL_FILE_NAME", & - description="Name of the pseudo potential file, may include a path", & + description="Name of the pseudopotential library file, optionally including a path. "// & + "The potential selected for each kind is set with KIND%POTENTIAL.", & usage="POTENTIAL_FILE_NAME ", & default_lc_val="POTENTIAL") CALL section_add_keyword(section, keyword) @@ -319,7 +322,8 @@ CONTAINS CALL keyword_create(keyword, __LOCATION__, & name="SORT_BASIS", & - description="Sort basis sets according to a certain criterion. ", & + description="Sorts basis functions according to a selected criterion. "// & + "Sorting by exponent can improve data locality for selected exact-exchange and RI workflows.", & enum_c_vals=s2a("DEFAULT", "EXP"), & enum_i_vals=[basis_sort_default, basis_sort_zet], & enum_desc=s2a("don't sort", "sort w.r.t. exponent"), & @@ -672,15 +676,16 @@ CONTAINS NULLIFY (keyword) CPASSERT(.NOT. ASSOCIATED(section)) CALL section_create(section, __LOCATION__, name="AUXILIARY_DENSITY_MATRIX_METHOD", & - description="Parameters needed for the ADMM method.", & + description="Controls the auxiliary density matrix method (ADMM), which evaluates "// & + "Hartree-Fock exchange on a smaller auxiliary basis and adds an exchange correction.", & n_keywords=1, n_subsections=1, repeats=.FALSE., & citations=[Guidon2010]) CALL keyword_create( & keyword, __LOCATION__, & name="ADMM_TYPE", & - description="Type of ADMM (sort name) as refered in literature. "// & - "This sets values for METHOD, ADMM_PURIFICATION_METHOD, and EXCH_SCALING_MODEL", & + description="Named ADMM variant from the literature. This shortcut sets METHOD, "// & + "ADMM_PURIFICATION_METHOD, and EXCH_SCALING_MODEL consistently for the selected variant.", & enum_c_vals=s2a("NONE", "ADMM1", "ADMM2", "ADMMS", "ADMMP", "ADMMQ"), & enum_desc=s2a("No short name is used, use specific definitions (default)", & "ADMM1 method from Guidon2010", & @@ -745,8 +750,8 @@ CONTAINS CALL keyword_create( & keyword, __LOCATION__, & name="EXCH_CORRECTION_FUNC", & - description="Exchange functional which is used for the ADMM correction. "// & - "LibXC implementations require linking with LibXC", & + description="Exchange functional used for the ADMM correction. It should be chosen consistently "// & + "with the exchange functional in the main XC setup. LibXC implementations require linking with LibXC.", & enum_c_vals=s2a("DEFAULT", "PBEX", "NONE", "OPTX", "BECKE88X", & "PBEX_LIBXC", "BECKE88X_LIBXC", "OPTX_LIBXC", "DEFAULT_LIBXC", "LDA_X_LIBXC"), & enum_i_vals=[do_admm_aux_exch_func_default, do_admm_aux_exch_func_pbex, & @@ -1230,26 +1235,32 @@ CONTAINS CPASSERT(.NOT. ASSOCIATED(section)) CALL section_create(section, __LOCATION__, name="mgrid", & - description="multigrid information", & + description="Controls the multigrid used by GPW/GAPW to represent densities, "// & + "potentials, and Gaussian products on real-space grids.", & n_keywords=5, n_subsections=1, repeats=.FALSE.) NULLIFY (keyword) CALL keyword_create(keyword, __LOCATION__, name="NGRIDS", & - description="The number of multigrids to use", & + description="Number of multigrid levels. Smooth Gaussian products can be mapped to "// & + "coarser levels, while sharper products require finer levels.", & usage="ngrids 1", default_i_val=4) CALL section_add_keyword(section, keyword) CALL keyword_release(keyword) CALL keyword_create(keyword, __LOCATION__, name="cutoff", & - description="The cutoff of the finest grid level. Default value for "// & - "SE or DFTB calculation is 1.0 [Ry].", & - usage="cutoff 300", default_r_val=cp_unit_to_cp2k(value=280.0_dp, & - unit_str="Ry"), n_var=1, unit_str="Ry") + description= & + "Plane-wave cutoff of the finest real-space grid level. "// & + "Increasing this value improves the grid representation, but it is "// & + "not a substitute for converging the Gaussian basis set. "// & + "Default value for SE or DFTB calculation is 1.0 [Ry].", & + usage="cutoff 300", & + default_r_val=cp_unit_to_cp2k(value=280.0_dp, unit_str="Ry"), & + n_var=1, unit_str="Ry") CALL section_add_keyword(section, keyword) CALL keyword_release(keyword) CALL keyword_create(keyword, __LOCATION__, name="progression_factor", & - description="Factor used to find the cutoff of the multigrids that"// & - " where not given explicitly", & + description="Factor used to derive the cutoff of coarser multigrid levels when "// & + "they are not given explicitly.", & usage="progression_factor ", default_r_val=3._dp) CALL section_add_keyword(section, keyword) CALL keyword_release(keyword) @@ -1271,11 +1282,10 @@ CONTAINS CALL keyword_create(keyword, __LOCATION__, name="REL_CUTOFF", & variants=["RELATIVE_CUTOFF"], & - description="Determines the grid at which a Gaussian is mapped,"// & - " giving the cutoff used for a gaussian with alpha=1."// & - " A value 50+-10Ry might be required for highly accurate results,"// & - " Or for simulations with a variable cell."// & - " Versions prior to 2.3 used a default of 30Ry.", & + description="Controls to which multigrid level a Gaussian product is mapped. "// & + "It is the reference cutoff for a Gaussian with exponent alpha=1. Larger values "// & + "keep more Gaussian products on finer grids and can be important for accurate "// & + "energies, forces, stress tensors, and variable-cell simulations.", & usage="RELATIVE_CUTOFF real", default_r_val=20.0_dp, & unit_str="Ry") CALL section_add_keyword(section, keyword) diff --git a/src/input_cp2k_force_eval.F b/src/input_cp2k_force_eval.F index 6eb51b4945..cea88f4760 100644 --- a/src/input_cp2k_force_eval.F +++ b/src/input_cp2k_force_eval.F @@ -80,7 +80,8 @@ CONTAINS NULLIFY (subsection) NULLIFY (keyword) CALL keyword_create(keyword, __LOCATION__, name="METHOD", & - description="Which method should be used to compute forces", & + description="Selects the method used by this FORCE_EVAL section to compute energies, "// & + "forces, and related properties.", & usage="METHOD ", & enum_c_vals=s2a("QS", & "SIRIUS", & @@ -97,11 +98,11 @@ CONTAINS "Molecular Mechanics", & "Hybrid quantum classical", & "Empirical Interatomic Potential", & - "Electronic structure methods (DFT, ...)", & + "Electronic structure methods in the Quickstep module, including GPW and GAPW DFT.", & "Neural Network Potentials", & "Use a combination of two of the above", & "Perform an embedded calculation", & - "Recieve forces from i–PI client"), & + "Receive forces from an i-PI client"), & enum_i_vals=[do_qs, do_sirius, do_fist, do_qmmm, do_eip, do_qs, do_nnp, do_mixed, do_embed, do_ipi], & default_i_val=do_qs) CALL section_add_keyword(section, keyword) diff --git a/src/input_cp2k_global.F b/src/input_cp2k_global.F index 16aaee7e55..6baf7c17b8 100644 --- a/src/input_cp2k_global.F +++ b/src/input_cp2k_global.F @@ -390,8 +390,8 @@ CONTAINS CALL keyword_create( & keyword, __LOCATION__, name="RUN_TYPE", & - description="Type of run that you want to perform Geometry "// & - "optimization, md, montecarlo,...", & + description="Selects the top-level task CP2K should run, such as an energy, "// & + "energy-and-force, molecular dynamics, geometry optimization, or response calculation.", & usage="RUN_TYPE MD", & default_i_val=energy_force_run, & citations=[Ceriotti2014, Schonherr2014], & diff --git a/src/input_cp2k_hfx.F b/src/input_cp2k_hfx.F index 79fdfb9297..a93a707bdc 100644 --- a/src/input_cp2k_hfx.F +++ b/src/input_cp2k_hfx.F @@ -60,14 +60,15 @@ CONTAINS CPASSERT(.NOT. ASSOCIATED(section)) CALL section_create(section, __LOCATION__, name="HF", & - description="Sets up the Hartree-Fock parameters if requested ", & + description="Controls Hartree-Fock exchange for hybrid DFT, Hartree-Fock, "// & + "and related post-Hartree-Fock workflows.", & n_keywords=5, n_subsections=2, repeats=.TRUE., & citations=[Guidon2008, Guidon2009]) NULLIFY (keyword, print_key, subsection) CALL keyword_create(keyword, __LOCATION__, name="FRACTION", & - description="The fraction of Hartree-Fock to add to the total energy. "// & + description="Fraction of Hartree-Fock exchange to add to the total energy. "// & "1.0 implies standard Hartree-Fock if used with XC_FUNCTIONAL NONE. "// & "NOTE: In a mixed potential calculation this should be set to 1.0, otherwise "// & "all parts are multiplied with this factor. ", & @@ -213,7 +214,8 @@ CONTAINS CPASSERT(.NOT. ASSOCIATED(section)) CALL section_create(section, __LOCATION__, name="INTERACTION_POTENTIAL", & - description="Sets up interaction potential if requested ", & + description="Defines the Coulomb, range-separated, mixed, or truncated interaction "// & + "operator used for Hartree-Fock exchange.", & n_keywords=1, n_subsections=0, repeats=.FALSE., & citations=[guidon2008, guidon2009]) @@ -221,8 +223,8 @@ CONTAINS CALL keyword_create( & keyword, __LOCATION__, & name="POTENTIAL_TYPE", & - description="Which interaction potential should be used "// & - "(Coulomb, longrange or shortrange).", & + description="Selects the interaction potential used for Hartree-Fock exchange. "// & + "Periodic hybrid calculations commonly use a short-range, truncated, or mixed potential.", & usage="POTENTIAL_TYPE SHORTRANGE", & enum_c_vals=s2a("COULOMB", "SHORTRANGE", "LONGRANGE", "MIX_CL", "GAUSSIAN", & "MIX_LG", "IDENTITY", "TRUNCATED", "MIX_CL_TRUNC"), & @@ -275,9 +277,10 @@ CONTAINS CALL keyword_release(keyword) CALL keyword_create(keyword, __LOCATION__, name="CUTOFF_RADIUS", & - description="Determines cutoff radius (in Angstroms) for the truncated $\frac{1}{r}$ "// & - "potential or the shortrange $\frac{\mathrm{erfc}(\omega \cdot r)}{r}$ potential. Default value "// & - "for shortrange potential when this keyword is omitted is solved from "// & + description="Cutoff radius for the truncated $\frac{1}{r}$ potential or the short-range "// & + "$\frac{\mathrm{erfc}(\omega \cdot r)}{r}$ potential. For truncated Coulomb in a "// & + "periodic cell, choose a radius compatible with the cell dimensions. The default value "// & + "for short-range potentials when this keyword is omitted is solved from "// & "$\frac{\mathrm{erfc}(\omega \cdot r)}{r} = \epsilon_{\mathrm{schwarz}}$ "// & "by Newton-Raphson method, with $\epsilon_{\mathrm{schwarz}}$ set by SCREENING/EPS_SCHWARZ", & usage="CUTOFF_RADIUS 10.0", type_of_var=real_t, & ! default_r_val=10.0_dp,& @@ -311,7 +314,7 @@ CONTAINS CPASSERT(.NOT. ASSOCIATED(section)) CALL section_create(section, __LOCATION__, name="SCREENING", & - description="Sets up screening parameters if requested ", & + description="Controls screening thresholds for Hartree-Fock exchange integrals.", & n_keywords=1, n_subsections=0, repeats=.FALSE., & citations=[guidon2008, guidon2009]) @@ -319,9 +322,8 @@ CONTAINS CALL keyword_create( & keyword, __LOCATION__, & name="EPS_SCHWARZ", & - description="Screens the near field part of the electronic repulsion "// & - "integrals using the Schwarz inequality for the given "// & - "threshold.", & + description="Schwarz inequality threshold for screening near-field electronic repulsion integrals. "// & + "Tighter values reduce screening error but increase cost.", & usage="EPS_SCHWARZ 1.0E-6", & default_r_val=1.0E-10_dp) CALL section_add_keyword(section, keyword) @@ -331,10 +333,9 @@ CONTAINS CALL keyword_create( & keyword, __LOCATION__, & name="EPS_SCHWARZ_FORCES", & - description="Screens the near field part of the electronic repulsion "// & - "integrals using the Schwarz inequality for the given "// & - "threshold. This will be approximately the accuracy of the forces, "// & - "and should normally be similar to EPS_SCF. Default value is 100*EPS_SCHWARZ.", & + description="Schwarz threshold used for force-related electronic repulsion integrals. "// & + "This is approximately the force accuracy and should normally be similar to EPS_SCF. "// & + "Default value is 100*EPS_SCHWARZ.", & usage="EPS_SCHWARZ_FORCES 1.0E-5", & default_r_val=1.0E-6_dp) CALL section_add_keyword(section, keyword) diff --git a/src/input_cp2k_kpoints.F b/src/input_cp2k_kpoints.F index 31963a9b81..589829c705 100644 --- a/src/input_cp2k_kpoints.F +++ b/src/input_cp2k_kpoints.F @@ -66,12 +66,12 @@ CONTAINS CPASSERT(.NOT. ASSOCIATED(section)) CALL section_create(section, __LOCATION__, name="KPOINTS", & - description="Sets up the kpoints.", & + description="Controls Brillouin-zone sampling with k-points.", & n_keywords=1, n_subsections=0, repeats=.FALSE.) NULLIFY (keyword) CALL keyword_create(keyword, __LOCATION__, name="SCHEME", & - description="Kpoint scheme to be used. Available options are:"//newline// & + description="K-point generation scheme. Available options are:"//newline// & "- `NONE`"//newline// & "- `GAMMA`"//newline// & "- `MONKHORST-PACK`"//newline// & @@ -96,7 +96,7 @@ CONTAINS CALL keyword_create(keyword, __LOCATION__, name="UNITS", & description="Special k-points are defined either in units"// & - " of reciprocal lattice vectors or in Cartesian coordinates in uints of 2Pi/len."// & + " of reciprocal lattice vectors or in Cartesian coordinates in units of 2Pi/len."// & " B_VECTOR: in multiples of the reciprocal lattice vectors (b)."// & " CART_ANGSTROM: In units of 2*Pi/Angstrom."// & " CART_BOHR: In units of 2*Pi/Bohr.", & @@ -112,7 +112,7 @@ CONTAINS CALL keyword_release(keyword) CALL keyword_create(keyword, __LOCATION__, name="FULL_GRID", & - description="Use full non-reduced kpoint grid.", & + description="Use the full, non-symmetry-reduced k-point grid.", & usage="FULL_GRID ", & default_l_val=.FALSE., lone_keyword_l_val=.TRUE.) CALL section_add_keyword(section, keyword) @@ -133,7 +133,7 @@ CONTAINS CALL keyword_release(keyword) CALL keyword_create(keyword, __LOCATION__, name="PARALLEL_GROUP_SIZE", & - description="Number of processors to be used for a single kpoint."// & + description="Number of MPI processes to be used for a single k-point."// & " This number must divide the total number of processes."// & " The number of groups must divide the total number of kpoints."// & " Value=-1 (smallest possible number of processes per group, satisfying the constraints)."// & @@ -145,7 +145,8 @@ CONTAINS CALL keyword_release(keyword) CALL keyword_create(keyword, __LOCATION__, name="WAVEFUNCTIONS", & - description="Use real/complex wavefunctions if possible.", & + description="Select whether real or complex wavefunctions should be used "// & + "when allowed by the k-point set.", & usage="WAVEFUNCTIONS REAL", & default_i_val=use_complex_wfn, & enum_c_vals=s2a("REAL", "COMPLEX"), & @@ -196,7 +197,7 @@ CONTAINS ! CALL keyword_create(keyword, __LOCATION__, name="UNITS", & description="Special k-points are defined either in units"// & - " of reciprocal lattice vectors or in Cartesian coordinates in uints of 2Pi/len."// & + " of reciprocal lattice vectors or in Cartesian coordinates in units of 2Pi/len."// & " B_VECTOR: in multiples of the reciprocal lattice vectors (b)."// & " CART_ANGSTROM: In units of 2*Pi/Angstrom."// & " CART_BOHR: In units of 2*Pi/Bohr.", & diff --git a/src/input_cp2k_mp2.F b/src/input_cp2k_mp2.F index 972e64297b..7f29cadb3e 100644 --- a/src/input_cp2k_mp2.F +++ b/src/input_cp2k_mp2.F @@ -82,8 +82,8 @@ CONTAINS CPASSERT(.NOT. ASSOCIATED(section)) CALL section_create(section, __LOCATION__, name="WF_CORRELATION", & - description="Sets up the wavefunction-based correlation methods as MP2, "// & - "RI-MP2, RI-SOS-MP2, RI-RPA and GW (inside RI-RPA). ", & + description="Controls wavefunction-based correlation methods such as MP2, "// & + "RI-MP2, RI-SOS-MP2, RI-RPA, and GW inside RI-RPA.", & n_keywords=4, n_subsections=7, repeats=.TRUE., & citations=[DelBen2012, DelBen2013, DelBen2015, DelBen2015b, Rybkin2016, & Wilhelm2016a, Wilhelm2016b, Wilhelm2017, Wilhelm2018, Stein2022, & @@ -94,7 +94,7 @@ CONTAINS CALL keyword_create( & keyword, __LOCATION__, & name="MEMORY", & - description="Maximum allowed total memory usage during MP2 methods [MiB].", & + description="Maximum allowed total memory usage during MP2 and related WF_CORRELATION methods [MiB].", & usage="MEMORY 1500 ", & default_r_val=1.024E+3_dp) CALL section_add_keyword(section, keyword) @@ -228,13 +228,13 @@ CONTAINS keyword, __LOCATION__, & name="METHOD", & citations=[DelBen2012, DelBen2013], & - description="Method that is used to compute the MP2 energy.", & + description="Selects the implementation used to compute the canonical MP2 energy.", & usage="METHOD MP2_GPW", & enum_c_vals=s2a("NONE", "DIRECT_CANONICAL", "MP2_GPW"), & enum_i_vals=[mp2_method_none, mp2_method_direct, mp2_method_gpw], & enum_desc=s2a("Skip MP2 calculation.", & - "Use the direct mp2 canonical approach.", & - "Use the GPW approach to MP2."), & + "Use the direct canonical MP2 approach.", & + "Use the GPW approach to MP2 integrals."), & default_i_val=mp2_method_direct) CALL section_add_keyword(section, keyword) CALL keyword_release(keyword) @@ -269,7 +269,7 @@ CONTAINS NULLIFY (keyword) CALL keyword_create(keyword, __LOCATION__, name="_SECTION_PARAMETERS_", & - description="Putting the &RI_MP2 section activates RI-MP2 calculation.", & + description="Activates an RI-MP2 calculation.", & usage="&RI_MP2 .TRUE.", & default_l_val=.FALSE., lone_keyword_l_val=.TRUE.) CALL section_add_keyword(section, keyword) @@ -512,13 +512,13 @@ CONTAINS CPASSERT(.NOT. ASSOCIATED(section)) CALL section_create(section, __LOCATION__, name="RI_RPA", & - description="Parameters influencing RI-RPA and GW.", & + description="Controls RI-RPA and GW calculations.", & n_keywords=8, n_subsections=4, repeats=.FALSE., & citations=[DelBen2013, DelBen2015]) NULLIFY (keyword, subsection) CALL keyword_create(keyword, __LOCATION__, name="_SECTION_PARAMETERS_", & - description="Putting the &RI_RPA section activates RI-RPA calculation.", & + description="Activates an RI-RPA calculation.", & usage="&RI_RPA .TRUE.", & default_l_val=.FALSE., lone_keyword_l_val=.TRUE.) CALL section_add_keyword(section, keyword) @@ -543,7 +543,7 @@ CONTAINS CALL keyword_create(keyword, __LOCATION__, name="QUADRATURE_POINTS", & variants=["RPA_NUM_QUAD_POINTS"], & - description="Number of quadrature points for the numerical integration in the RI-RPA method.", & + description="Number of quadrature points for the RI-RPA numerical integration.", & usage="QUADRATURE_POINTS 60", & default_i_val=40) CALL section_add_keyword(section, keyword) @@ -575,8 +575,8 @@ CONTAINS keyword, __LOCATION__, & name="MINIMAX_QUADRATURE", & variants=["MINIMAX"], & - description="Use the Minimax quadrature scheme for performing the numerical integration. "// & - "Maximum number of quadrature point limited to 20.", & + description="Use the Minimax quadrature scheme for the numerical integration. "// & + "It usually needs fewer quadrature points than Clenshaw-Curtis but is limited to 20 points.", & usage="MINIMAX_QUADRATURE", & default_l_val=.FALSE., & lone_keyword_l_val=.TRUE.) @@ -597,11 +597,10 @@ CONTAINS CALL keyword_create( & keyword, __LOCATION__, & name="ADMM", & - description="Decide whether to perform ADMM in the exact exchange calc. for RPA and/or GW. "// & + description="Decide whether to use ADMM in the exact-exchange calculation for RPA and/or GW. "// & "The ADMM XC correction is governed by the AUXILIARY_DENSITY_MATRIX_METHOD section in &DFT. "// & - "In most cases, the Hartree-Fock exchange is not too expensive and there is no need for ADMM, "// & - "ADMM can however provide significant speedup and memory savings in case of diffuse basis sets. "// & - "If it is a GW bandgap calculations, RI_SIGMA_X can also be used. ", & + "ADMM can provide significant speedup and memory savings, especially with diffuse basis sets. "// & + "For GW band-gap calculations, RI_SIGMA_X can also be used. ", & usage="ADMM", & default_l_val=.FALSE., & lone_keyword_l_val=.TRUE.) diff --git a/src/input_cp2k_poisson.F b/src/input_cp2k_poisson.F index 90219596c7..a8fa182c45 100644 --- a/src/input_cp2k_poisson.F +++ b/src/input_cp2k_poisson.F @@ -108,7 +108,7 @@ CONTAINS CPASSERT(.NOT. ASSOCIATED(section)) CALL section_create(section, __LOCATION__, name="poisson", & - description="Sets up the poisson resolutor.", & + description="Controls the Poisson solver and electrostatic boundary conditions used by DFT.", & n_keywords=1, n_subsections=0, repeats=.FALSE.) NULLIFY (keyword, subsection) @@ -137,10 +137,9 @@ CONTAINS CALL keyword_release(keyword) CALL keyword_create(keyword, __LOCATION__, name="PERIODIC", & - description="Specify the directions in which PBC apply. Important notice,"// & - " this only applies to the electrostatics."// & - " See the CELL section to specify the periodicity used for e.g. the pair lists."// & - " Typically the settings should be the same.", & + description="Specifies the directions in which periodic boundary conditions apply to electrostatics. "// & + "See the CELL section for the periodicity used by geometry and pair lists; "// & + "the settings are usually the same.", & usage="PERIODIC (x|y|z|xy|xz|yz|xyz|none)", & enum_c_vals=s2a("x", "y", "z", "xy", "xz", "yz", "xyz", "none"), & enum_i_vals=[use_perd_x, use_perd_y, use_perd_z, & diff --git a/src/input_cp2k_properties_dft.F b/src/input_cp2k_properties_dft.F index a107c7c91c..7e311e7959 100644 --- a/src/input_cp2k_properties_dft.F +++ b/src/input_cp2k_properties_dft.F @@ -1533,9 +1533,8 @@ CONTAINS CPASSERT(.NOT. ASSOCIATED(section)) CALL section_create(section, __LOCATION__, name="TDDFPT", & - description="Parameters needed to set up the Time-Dependent "// & - "Density Functional Perturbation Theory. "// & - "Current implementation works for hybrid functionals. ", & + description="Controls time-dependent density functional perturbation theory "// & + "(TDDFPT) calculations for electronic excitations and related properties.", & n_keywords=14, n_subsections=4, repeats=.FALSE., & citations=[Iannuzzi2005, Hanasaki2025, Hernandez2025]) @@ -1543,7 +1542,7 @@ CONTAINS CALL keyword_create(keyword, __LOCATION__, & name="_SECTION_PARAMETERS_", & - description="Controls the activation of the TDDFPT procedure", & + description="Activates the TDDFPT procedure.", & default_l_val=.FALSE., & lone_keyword_l_val=.TRUE.) CALL section_add_keyword(section, keyword) @@ -1582,7 +1581,7 @@ CONTAINS CALL keyword_create(keyword, __LOCATION__, name="NPROC_STATE", & description="Number of MPI processes to be used per excited state. "// & - "Default is to use all processors (0).", & + "Default is to use all MPI processes (0).", & n_var=1, type_of_var=integer_t, & default_i_val=0) CALL section_add_keyword(section, keyword) diff --git a/src/input_cp2k_qmmm.F b/src/input_cp2k_qmmm.F index b1701a55ed..9ce869d1fd 100644 --- a/src/input_cp2k_qmmm.F +++ b/src/input_cp2k_qmmm.F @@ -95,22 +95,23 @@ CONTAINS CPASSERT(.NOT. ASSOCIATED(section)) CALL section_create(section, __LOCATION__, name="qmmm", & - description="Input for QM/MM calculations.", & + description="Controls QM/MM calculations, including mechanical, electrostatic, "// & + "Gaussian-expanded, and periodic embedding options.", & n_keywords=6, n_subsections=3, repeats=.FALSE., & citations=[Laino2005, Laino2006]) NULLIFY (keyword, subsection) CALL keyword_create(keyword, __LOCATION__, name="E_COUPL", & variants=s2a("QMMM_COUPLING", "ECOUPL"), & - description="Specifies the type of the QM - MM electrostatic coupling.", & + description="Selects the QM-MM coupling model used for the electrostatic interaction.", & usage="E_COUPL GAUSS", & enum_c_vals=s2a("NONE", "COULOMB", "GAUSS", "S-WAVE", "POINT_CHARGE"), & enum_i_vals=[do_qmmm_none, do_qmmm_coulomb, do_qmmm_gauss, do_qmmm_swave, do_qmmm_pcharge], & enum_desc=s2a("Mechanical coupling (i.e. classical point charge based)", & "Using analytical 1/r potential (Coulomb) - not available for GPW/GAPW", & - "Using fast gaussian expansion of the electrostatic potential (Erf(r/rc)/r) "// & + "Using fast Gaussian expansion of the electrostatic potential (Erf(r/rc)/r) "// & "- not available for DFTB.", & - "Using fast gaussian expansion of the s-wave electrostatic potential", & + "Using fast Gaussian expansion of the s-wave electrostatic potential", & "Using quantum mechanics derived point charges interacting with MM charges"), & default_i_val=do_qmmm_none) CALL section_add_keyword(section, keyword) diff --git a/src/input_cp2k_qs.F b/src/input_cp2k_qs.F index e95882a649..7c981676ed 100644 --- a/src/input_cp2k_qs.F +++ b/src/input_cp2k_qs.F @@ -169,7 +169,9 @@ CONTAINS CALL keyword_create(keyword, __LOCATION__, name="EPSFIT", & variants=["EPS_FIT"], & - description="GAPW: precision to give the extension of a hard gaussian ", & + description="GAPW: tolerance controlling the split of Gaussian basis functions "// & + "into hard atom-centered and soft grid-expanded parts. Smaller values include "// & + "harder Gaussians in the soft density and can require a larger MGRID cutoff.", & usage="EPSFIT real", default_r_val=1.0E-4_dp) CALL section_add_keyword(section, keyword) CALL keyword_release(keyword) @@ -183,14 +185,16 @@ CONTAINS CALL keyword_create(keyword, __LOCATION__, name="EPSSVD", & variants=["EPS_SVD"], & - description="GAPW: tolerance used in the singular value decomposition of the projector matrix", & + description="GAPW: tolerance used in the singular value decomposition of the "// & + "projector matrix. Smaller values can improve numerical accuracy at increased cost.", & usage="EPS_SVD real", default_r_val=1.0E-8_dp) CALL section_add_keyword(section, keyword) CALL keyword_release(keyword) CALL keyword_create(keyword, __LOCATION__, name="EPSRHO0", & variants=s2a("EPSVRHO0", "EPS_VRHO0"), & - description="GAPW : precision to determine the range of V(rho0-rho0soft)", & + description="GAPW: tolerance used to determine the range of the "// & + "V(rho0-rho0_soft) compensation contribution.", & usage="EPSRHO0 real", default_r_val=1.0E-6_dp) CALL section_add_keyword(section, keyword) CALL keyword_release(keyword) diff --git a/src/input_cp2k_resp.F b/src/input_cp2k_resp.F index 3d85805f26..24baacb83f 100644 --- a/src/input_cp2k_resp.F +++ b/src/input_cp2k_resp.F @@ -61,7 +61,8 @@ CONTAINS CPASSERT(.NOT. ASSOCIATED(section)) CALL section_create(section, __LOCATION__, name="RESP", & - description="Requests a RESP fit of charges. When using a periodic "// & + description="Requests a restrained electrostatic potential (RESP) fit of atomic charges. "// & + "When using a periodic "// & "Poisson solver and a periodic cell, the periodic RESP routines are "// & "used. If the Hartree potential matches with the one of an isolated "// & "system (i.e. isolated Poisson solver and big, nonperiodic cells), "// & diff --git a/src/input_cp2k_scf.F b/src/input_cp2k_scf.F index 644ffb9f88..29b8c77b60 100644 --- a/src/input_cp2k_scf.F +++ b/src/input_cp2k_scf.F @@ -139,7 +139,7 @@ CONTAINS CALL keyword_release(keyword) CALL keyword_create(keyword, __LOCATION__, name="MAX_SCF", & - description="Maximum number of SCF iteration to be performed for one optimization", & + description="Maximum number of inner SCF iterations for one electronic optimization.", & usage="MAX_SCF 200", default_i_val=50) CALL section_add_keyword(section, keyword) CALL keyword_release(keyword) @@ -167,7 +167,7 @@ CONTAINS CALL keyword_release(keyword) CALL keyword_create(keyword, __LOCATION__, name="EPS_SCF", & - description="Target accuracy for the SCF convergence.", & + description="Target convergence threshold for the inner SCF cycle.", & usage="EPS_SCF 1.e-6", default_r_val=1.e-5_dp) CALL section_add_keyword(section, keyword) CALL keyword_release(keyword) @@ -206,7 +206,7 @@ CONTAINS CALL keyword_create( & keyword, __LOCATION__, name="SCF_GUESS", & - description="Change the initial guess for the wavefunction.", & + description="Selects how the initial wavefunction or density matrix is generated.", & usage="SCF_GUESS RESTART", default_i_val=atomic_guess, & enum_c_vals=s2a("ATOMIC", "RESTART", "RANDOM", "CORE", & "HISTORY_RESTART", "MOPAC", "EHT", "SPARSE", "NONE"), & @@ -237,8 +237,9 @@ CONTAINS CALL keyword_release(keyword) CALL keyword_create(keyword, __LOCATION__, name="ADDED_MOS", & - description="Number of additional MOS added for each spin. Use -1 to add all available. "// & - "alpha/beta spin can be specified independently (if spin-polarized calculation requested).", & + description="Number of additional molecular orbitals added for each spin channel. "// & + "This is commonly needed for smearing, excited-state, or post-Hartree-Fock calculations. "// & + "Use -1 to add all available orbitals.", & usage="ADDED_MOS", default_i_val=0, n_var=-1) CALL section_add_keyword(section, keyword) CALL keyword_release(keyword) @@ -434,13 +435,14 @@ CONTAINS CPASSERT(.NOT. ASSOCIATED(section)) CALL section_create(section, __LOCATION__, name="OUTER_SCF", & - description="parameters controlling the outer SCF loop", & + description="Controls an outer SCF loop, often used to stabilize difficult OT convergence, "// & + "constraints, or other variables wrapped around the inner SCF cycle.", & n_keywords=13, n_subsections=1, repeats=.FALSE.) NULLIFY (keyword) CALL keyword_create(keyword, __LOCATION__, name="_SECTION_PARAMETERS_", & - description="controls the activation of the outer SCF loop", & + description="Activates the outer SCF loop.", & usage="&OUTER_SCF ON", default_l_val=.FALSE., lone_keyword_l_val=.TRUE.) CALL section_add_keyword(section, keyword) CALL keyword_release(keyword) @@ -525,7 +527,7 @@ CONTAINS CALL keyword_release(keyword) CALL keyword_create(keyword, __LOCATION__, name="MAX_SCF", & - description="The maximum number of outer loops ", & + description="Maximum number of outer SCF loops.", & usage="MAX_SCF 20", default_i_val=50) CALL section_add_keyword(section, keyword) CALL keyword_release(keyword) @@ -1263,7 +1265,7 @@ CONTAINS CALL section_create(section, __LOCATION__, & name="SMEAR", & - description="Define the smearing of the MO occupation numbers", & + description="Controls smearing of MO occupation numbers for systems with small or zero gaps.", & n_keywords=6, & n_subsections=0, & repeats=.FALSE.) @@ -1281,7 +1283,7 @@ CONTAINS CALL keyword_create(keyword, __LOCATION__, & name="METHOD", & - description="Smearing method to be applied", & + description="Selects the smearing method to apply.", & usage="METHOD Fermi_Dirac", & default_i_val=smear_gaussian, & enum_c_vals=s2a("FERMI_DIRAC", "ENERGY_WINDOW", "LIST", "GAUSSIAN", & @@ -1323,7 +1325,7 @@ CONTAINS CALL keyword_create(keyword, __LOCATION__, & name="ELECTRONIC_TEMPERATURE", & variants=s2a("ELEC_TEMP", "TELEC"), & - description="Electronic temperature in the case of Fermi-Dirac smearing", & + description="Electronic temperature used for Fermi-Dirac smearing.", & repeats=.FALSE., & n_var=1, & type_of_var=real_t, & diff --git a/src/input_cp2k_subsys.F b/src/input_cp2k_subsys.F index f57d48f45b..f64857b8e5 100644 --- a/src/input_cp2k_subsys.F +++ b/src/input_cp2k_subsys.F @@ -1059,7 +1059,8 @@ CONTAINS CPASSERT(.NOT. ASSOCIATED(section)) CALL section_create(section, __LOCATION__, name="KIND", & - description="The description of the kind of the atoms (mostly for QM)", & + description="Defines settings shared by atoms of the same kind, such as basis sets, "// & + "pseudopotentials, all-electron treatment, and atom-centered grids.", & n_keywords=20, n_subsections=1, repeats=.TRUE.) NULLIFY (keyword) @@ -1071,8 +1072,8 @@ CONTAINS CALL keyword_release(keyword) CALL keyword_create(keyword, __LOCATION__, name="BASIS_SET", & - description="The primary Gaussian basis set (NONE implies no basis used, meaningful with GHOST). "// & - "Defaults are set for TYPE {ORB} and FORM {GTO}. Possible values for TYPE are "// & + description="Selects a Gaussian basis set for this kind. The default type is ORB and the default "// & + "form is GTO; NONE implies no basis and is meaningful for ghost atoms. Possible values for TYPE are "// & "{ORB, AUX, MIN, RI_AUX, LRI, ...}. Possible values for "// & "FORM are {GTO, STO}. Where STO results in a GTO expansion of a Slater type basis. "// & "If a value for FORM is given, also TYPE has to be set explicitly.", & @@ -1185,8 +1186,13 @@ CONTAINS CALL keyword_create(keyword, __LOCATION__, name="POTENTIAL", & variants=["POT"], & - description="The type (ECP, ALL, GTH, UPS) and name of the pseudopotential for the defined kind.", & - usage="POTENTIAL [type] ", type_of_var=char_t, default_c_vals=[" ", " "], & + description= & + "The type (ECP, ALL, GTH, UPS) and name of the "// & + "pseudopotential for the defined kind. Use GTH potentials "// & + "for most GPW calculations, ECP for Gaussian-integral effective core "// & + "potentials, and ALL for all-electron calculations.", & + usage="POTENTIAL [type] ", type_of_var=char_t, & + default_c_vals=[" ", " "], & citations=[Goedecker1996, Hartwigsen1998, Krack2005], n_var=-1) CALL section_add_keyword(section, keyword) CALL keyword_release(keyword) @@ -1251,15 +1257,15 @@ CONTAINS CALL keyword_release(keyword) CALL keyword_create(keyword, __LOCATION__, name="LEBEDEV_GRID", & - description="The number of points for the angular part of "// & - "the local grid (GAPW)", & + description="GAPW: size of the angular Lebedev grid used for "// & + "atom-centered integrations for this kind.", & usage="LEBEDEV_GRID 40", default_i_val=50) CALL section_add_keyword(section, keyword) CALL keyword_release(keyword) CALL keyword_create(keyword, __LOCATION__, name="RADIAL_GRID", & - description="The number of points for the radial part of "// & - "the local grid (GAPW)", & + description="GAPW: number of radial grid points used for atom-centered "// & + "integrations for this kind.", & usage="RADIAL_GRID 70", default_i_val=50) CALL section_add_keyword(section, keyword) CALL keyword_release(keyword) diff --git a/src/input_cp2k_xas.F b/src/input_cp2k_xas.F index c3e11c34db..d08a74e91a 100644 --- a/src/input_cp2k_xas.F +++ b/src/input_cp2k_xas.F @@ -71,9 +71,8 @@ CONTAINS CPASSERT(.NOT. ASSOCIATED(section)) CALL section_create(section, __LOCATION__, name="xas", & - description="Sets the method of choice to calculate core-level excitation spectra. "// & - "The occupied states from which we calculate the "// & - "excitation should be specified. "// & + description="Controls transition-potential and delta-SCF calculations of core-level excitation spectra. "// & + "The occupied states from which the excitations are calculated should be specified. "// & "Localization of the orbitals may be useful.", & n_keywords=10, n_subsections=1, repeats=.FALSE., & citations=[Iannuzzi2007]) @@ -381,7 +380,7 @@ CONTAINS CPASSERT(.NOT. ASSOCIATED(section)) CALL section_create(section, __LOCATION__, name="XAS_TDP", & description="XAS simulations using linear-response TDDFT. Excitation from "// & - "specified core orbitals are considered one at a time. In case of high "// & + "specified core orbitals is considered one at a time. In case of high "// & "symmetry structures, donor core orbitals should be localized.", & n_keywords=19, n_subsections=4, repeats=.FALSE.) @@ -423,7 +422,7 @@ CONTAINS CALL keyword_create(keyword, __LOCATION__, name="EXCITATIONS", & variants=["EXCITATION"], & description="Specify the type of excitation to consider. In case of a "// & - "resctricted closed-shell ground state calculation, "// & + "restricted closed-shell ground state calculation, "// & "RCS_SINGLET or/and RCS_TRIPLET can be chosen. In case of a "// & "open-shell ground state calculation (either UKS or ROKS), "// & "standard spin conserving excitation (OS_SPIN_CONS) or/and "// & @@ -442,7 +441,7 @@ CONTAINS CALL keyword_create(keyword, __LOCATION__, name="EPS_PGF_XAS", & variants=s2a("EPS_PGF", "EPS_PGF_XAS_TDP"), & - description="The threshold used to determine the spacial extent of all "// & + description="The threshold used to determine the spatial extent of all "// & "primitive Gaussian functions used for the construction "// & "of neighbor lists in the XAS_TDP method. "// & "By default, takes the value of QS%EPS_PGF_ORB. Useful if "// & @@ -865,7 +864,7 @@ CONTAINS description="A threshold to determine which primitive 3-center integrals "// & "are kept for contraction, as the latter operation can be "// & "expensive (especially for large basis sets ). "// & - "If |(ab|c)| < EPS_SCREENNING, it is discarded.", & + "If |(ab|c)| < EPS_SCREENING, it is discarded.", & default_r_val=1.0E-8_dp, & repeats=.FALSE.) CALL section_add_keyword(subsubsection, keyword) @@ -957,7 +956,7 @@ CONTAINS "XAS TDP calculations", repeats=.FALSE.) CALL cp_print_key_section_create(print_key, __LOCATION__, name="SPECTRUM", & - description="Controles the dumping of the XAS TDP spectrum in output files", & + description="Controls the dumping of the XAS TDP spectrum in output files", & print_level=low_print_level, filename="", common_iter_levels=3) CALL section_add_subsection(subsection, print_key) CALL section_release(print_key) diff --git a/src/start/cp2k_runs.F b/src/start/cp2k_runs.F index 5da22b45f9..a821b97a1f 100644 --- a/src/start/cp2k_runs.F +++ b/src/start/cp2k_runs.F @@ -8,8 +8,9 @@ ! ************************************************************************************************** MODULE cp2k_runs USE atom, ONLY: atom_code - USE bibliography, ONLY: Hutter2014,& - cite_reference + USE bibliography, ONLY: Iannuzzi2026,& + cite_reference,& + cp2kqs2020 USE bsse, ONLY: do_bsse_calculation USE cell_opt, ONLY: cp_cell_opt USE cp2k_debug, ONLY: cp2k_debug_energy_and_forces @@ -205,7 +206,8 @@ CONTAINS NULLIFY (globenv, force_env) - CALL cite_reference(Hutter2014) + CALL cite_reference(cp2kqs2020) + CALL cite_reference(Iannuzzi2026) ! Parse the input input_file => read_input(input_declaration, input_file_name, &