comp-chem/cp2k
1
0
Fork 0
mirror of https://github.com/cp2k/cp2k.git synced 2026-07-21 06:25:15 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

Docs: write build timstamp to page footer, link past releases in CP2K_INPUT, add acronyms, add notes about NaN/Inf, edit convergence.md (#5579)

Browse source
This commit is contained in:
HE Zilong 2026-07-13 16:55:09 +08:00 • committed by GitHub
parent 7de47fd987
commit d2d9c0e403
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 122 additions and 51 deletions
Download patch file Download diff file Expand all files Collapse all files

22
docs/acronyms.md
View file

@ -22,6 +22,9 @@ ASE
ASPC
Always Stable Predictor-Corrector [→ more](methods/sampling/molecular_dynamics)
BCC
Body-Centered Cubic crystal structure
BFGS
Broyden–Fletcher–Goldfarb–Shanno algorithm [→ more](methods/optimization/geometry_and_cell_opt)
@ -46,6 +49,9 @@ CG
CHARMM
Chemistry at HARvard Molecular Mechanics
CIF
Crystallographic Information File
COLVAR
COLlective VARiable [→ more](methods/sampling/metadynamics)
@ -83,7 +89,7 @@ DLA-F
Distributed Linear Algebra from the Future [→ more](technologies/eigensolvers/dlaf)
DOS
Density Of States
Density Of States [→ more](methods/electronic_structure/dos)
EAM
Embedded-Atom Method
@ -154,6 +160,9 @@ GTO
GW
GW approximation [→ more](methods/properties/optical/index)
HCP
Hexagonal Close-Packed crystal structure
HF
Hartree Fock [→ more](methods/dft/hartree-fock/index)
@ -215,7 +224,7 @@ MNDO
Modified Neglect of Diatomic Overlap
MO
Molecular Orbitals [→ more](methods/dft/index)
Molecular Orbitals [→ more](methods/electronic_structure/molecular_orbitals)
MOM
Maximum Overlap Method
@ -274,6 +283,9 @@ PBC
PBE
Perdew–Burke–Ernzerhof exchange-correlation functional [→ more](methods/dft/index)
PDB
Protein Data Bank (the database or the format specification)
PIGLET
Path Integral Generalized Langevin Equation Thermostat
@ -364,6 +376,12 @@ TRS4
UFF
Universal Force Field
UKS
Unrestricted Kohn-Sham [→ more](methods/dft/index)
VMD
Visual Molecular Dynamics
XAS
X-ray Absorption Spectra [→ more](methods/properties/x-ray/index)

2
docs/conf.py
View file

@ -46,6 +46,8 @@ html_theme = "sphinx_rtd_theme"
html_static_path = ["_static"]
html_favicon = "_static/favicon.png"
html_copy_source = False
html_last_updated_fmt = "%a, %d %b %Y %H:%M:%S +0000"
html_last_updated_use_utc = True
add_module_names = False

10
docs/generate_input_reference.py
View file

@ -7,7 +7,6 @@ import xml.etree.ElementTree as ET
from pathlib import Path
import re
import sys
from datetime import datetime
from collections import defaultdict
from functools import cache
@ -97,8 +96,6 @@ def build_input_reference(root: ET.Element, output_dir: Path) -> None:
# Build landing page.
cp2k_version = get_text(root.find("CP2K_VERSION"))
compile_revision = get_text(root.find("COMPILE_REVISION"))
# cp2k_year = get_text(root.find("CP2K_YEAR"))
# compile_date = get_text(root.find("COMPILE_DATE"))
output = []
output += ["%", "% This file was created by generate_input_reference.py", "%"]
@ -107,7 +104,12 @@ def build_input_reference(root: ET.Element, output_dir: Path) -> None:
assert compile_revision.startswith("git:")
github_url = f"https://github.com/cp2k/cp2k/tree/{compile_revision[4:]}"
output += [f"Based on {cp2k_version} ([{compile_revision}]({github_url}))", ""]
output += [
f"Based on {cp2k_version} ([{compile_revision}]({github_url})).",
"",
"For past stable releases, see [](./versions).",
"",
]
output += ["```{toctree}"]
output += [":maxdepth: 1"]

23
docs/getting-started/troubleshooting.md
View file

@ -143,19 +143,23 @@ Check everything that determines the environment variables and paths, including
[with toolchain](./build-from-source.md#toolchain-based-build), do not forget to source the
`cp2k_env` to load the dependencies as instructed.
### Asterisks or NaN in the output
### Asterisks, NaN or Inf in the output
This is a general fortran behavior about how a fixed-width field format handles a numeric value that
cannot be fitted in. For example, the edit descriptor `F12.6` specifies a real float-type field with
exactly 12 characters, including 6 for the fractional part and 1 for the decimal point (and 1 for
the minus sign if negative), thus leaving only 5 places for the integer part; if the value to be
printed is larger than 99999.999999 or smaller than -9999.999999, it would not fit in and a string
of asterisks `************` would be shown instead. If something goes haywire and the value is not
even a valid number any more, it would be represented as ` NaN`, where NaN is shorthand for
"Not a Number". Most of these field formats are designed with output layout, value precision and
possible range in mind, so the presence of asterisks and NaN in the output should invoke some doubts
on the reliability of very large or very small numeric results even if the calculation looks fine
otherwise.
of asterisks `************` would be shown instead. Most of these field formats are designed with
output layout, value precision and possible range in mind, so the presence of a string of asterisks
in the place of numeric output should invoke some doubts on the reliability of very large or very
small numeric results, even if the calculation looks fine otherwise. Note that there are some format
specifications like the PDB file and the Gaussian cube file where the entries have some restricted
fixed-width field formats for writing or reading, while others like the XYZ file are more lenient.
Beyond that, abnormal values may be represented as `NaN` for "Not a Number" or `Inf` for Infinity,
padded with whitespaces to satisfy the width of the edit descriptor. Both of these marks in the
output suggest that something numerically unstable has gone haywire and needs developer attention.
### A certain type object was expected, found something else
@ -203,9 +207,10 @@ possibilities of modelling errors, there are three frequently relevant pitfalls:
atom, and the fractional occupancy is not handled well when creating the model, as discussed in
[a FAQ](./foreword-and-faq.md#how-do-i-create-the-atomistic-model-for-cp2k-input).
### SCF run NOT converged
### SCF convergence troubles
Refer to [](../methods/dft/convergence).
`SCF run NOT converged` and `KS energy is an abnormal value (NaN/Inf)` are discussed separately on
[](../methods/dft/convergence).
### Messages mentioning LSD

116
docs/methods/dft/convergence.md
View file

@ -1,5 +1,10 @@
# How to make a SCF run converge
Since CP2K version 2024.1, a failure in SCF convergence in a Quickstep calculation will abort the
program by default. This means that after reaching [MAX_SCF](#CP2K_INPUT.FORCE_EVAL.DFT.SCF.MAX_SCF)
cycles (default 50), the value printed under the `Convergence` column does not meet
[EPS_SCF](#CP2K_INPUT.FORCE_EVAL.DFT.SCF.EPS_SCF).
```text
*******************************************************************************
* ___ *
@ -13,19 +18,25 @@
*******************************************************************************
```
Since CP2K 2024.1 version, a failure in SCF convergence in a Quickstep calculation aborts the
program by default. This means that after reaching [MAX_SCF](#CP2K_INPUT.FORCE_EVAL.DFT.SCF.MAX_SCF)
cycles (50 by default), the value printed under the `Convergence` column does not meet
[EPS_SCF](#CP2K_INPUT.FORCE_EVAL.DFT.SCF.EPS_SCF). A variety of measures are available for
converging the SCF to a reasonable result, which this page discusses, assuming that the reader has
read [](../../getting-started/foreword-and-faq) and the other documentations under [](./index)
first.
Occasionally the symptom of diverging SCF cycles manifests as another error before hitting MAX_SCF.
```{note}
At the moment, the convergence criterion does not take the absolute change in energy into account,
and the convergence of the diagonalization algorithm differs from that of the OT algorithm.
```text
*******************************************************************************
* ___ *
* / \ *
* [ABORT] *
* \___/ KS energy is an abnormal value (NaN/Inf). *
* | *
* O/| *
* /| | *
* / \ qs_ks_methods.F:1166 *
*******************************************************************************
```
This page discusses a variety of measures available for addressing these errors and converging to a
reasonable SCF solution with good precision. It is assumed that the reader has read beforehand
[](../../getting-started/foreword-and-faq) and the other documentations under [](./index).
```{danger}
**Take your own risk and responsibility for ignoring convergence failure !!**
@ -46,17 +57,28 @@ in the first place; any other tasks not preceded by it is like putting the cart
The very first ingredient of SCF convergence is a sensible input structure, applicable to every type
of computation task including geometry and cell optimization, as elaborated on
[](../../methods/optimization/geometry_and_cell_opt.md#starting-structure-and-cell).
[](../optimization/geometry_and_cell_opt.md#starting-structure-and-cell). A good initial structure
and a sufficiently small step size of structure evolution are favorable for the task types that
involve atomic motion, as the [EXTRAPOLATION](#CP2K_INPUT.FORCE_EVAL.DFT.QS.EXTRAPOLATION) of
wavefunction works best this way. Its usage is detailed elsewhere for
[optimization](../optimization/geometry_and_cell_opt.md#extrapolation) and
[molecular dynamics](../sampling/molecular_dynamics.md#extrapolation-of-the-electronic-initial-guess)
and the rest of this page will focus on a single-point calculation without such convenience.
On top of that, there is also the net charge and spin multiplicity as specified by keywords
[CHARGE](#CP2K_INPUT.FORCE_EVAL.DFT.CHARGE) and
[MULTIPLICITY](#CP2K_INPUT.FORCE_EVAL.DFT.MULTIPLICITY) respectively that should be set to represent
the realistic electronic state. Use the [UKS](#CP2K_INPUT.FORCE_EVAL.DFT.UKS) keyword (or
On top of a reasonable structure, there is also the net charge and electronic spin multiplicity as
specified by a pair of keywords [CHARGE](#CP2K_INPUT.FORCE_EVAL.DFT.CHARGE) and
[MULTIPLICITY](#CP2K_INPUT.FORCE_EVAL.DFT.MULTIPLICITY) respectively, that should represent a
realistic electronic state. Use the [UKS](#CP2K_INPUT.FORCE_EVAL.DFT.UKS) keyword (`UKS` can be
equivalently written as `LSD`) to request for an unrestricted, spin-polarized calculation of
open-shell systems.
If the geometry is reasonable, check whether the [XC](#CP2K_INPUT.FORCE_EVAL.DFT.XC) section or the
respective section of model Hamiltonian has been set up correctly.
open-shell systems. For instance, it is well-known that the dioxygen molecule $\mathrm{O_2}$ has a
[triplet](https://en.wikipedia.org/wiki/Triplet_oxygen) ground state, and even the lowest
[singlet](https://en.wikipedia.org/wiki/Singlet_oxygen) state is an excited state available from
energetic conditions like in photochemical systems; unless singlet oxygen is really intended, the
calculation of a dioxygen molecule should normally use `MULTIPLICITY 3` together with `UKS` so as to
allow for two alpha electrons that do not get paired with beta electrons. But for more complicated
cases such as multiple dioxygen molecules coexisting or a dioxygen molecule adsorbed on a surface,
simply setting `MULTIPLICITY` may not be enough; this is where a delicate preparation of SCF initial
guess would be necessary.
The default of [SCF_GUESS](#CP2K_INPUT.FORCE_EVAL.DFT.SCF.SCF_GUESS) is `ATOMIC`, meaning that the
initial wavefunction and density matrix is generated from the atomic density of each kind of atom.
@ -98,6 +120,10 @@ gamma-only calculation by using the Harris functional for energy correction unde
[DFT/ENERGY_CORRECTION](#CP2K_INPUT.FORCE_EVAL.DFT.ENERGY_CORRECTION).
```
With the structure, electronic state and initial guess cleared, the next step is to check if the
[XC](#CP2K_INPUT.FORCE_EVAL.DFT.XC) section or the respective section of model Hamiltonian has been
set up correctly. Try searching the regtest input files for a reference.
Some parameters that control the accuracy for Quickstep calculation, such as
[EPS_DEFAULT](#CP2K_INPUT.FORCE_EVAL.DFT.QS.EPS_DEFAULT),
[CUTOFF](#CP2K_INPUT.FORCE_EVAL.DFT.MGRID.CUTOFF) and
@ -107,11 +133,17 @@ the more accurate and expensive side: even if each SCF iteration takes longer, t
iterations to reach convergence may still be reduced.
Similarly, higher number or density of k-points for the Brillouin-zone sampling may be beneficial,
in particular if the cell is small and the system is not insulating. A convergence test for k-points
with respect to the target property does not need to start with what is too low to make SCF
converge.
in particular if the cell is small (corresponding to long reciprocal-space lattice vectors) and the
system is an electronic conductor or semi-conductor. A convergence test for k-points with respect to
the target property does not need to start with what is too low to make SCF converge.
## For diagonalization
## Algorithm-specific considerations
At the moment, the convergence criterion does not take the absolute change in energy into account,
and the convergence of the diagonalization algorithm differs from that of the OT algorithm. Thus,
these two algorithms are examined separately below.
### For diagonalization
The standard diagonalization algorithm for the Kohn-Sham matrix is activated by setting the
[DIAGONALIZATION](#CP2K_INPUT.FORCE_EVAL.DFT.SCF.DIAGONALIZATION) section, with full support for the
@ -123,19 +155,31 @@ default conservative `DIRECT_P_MIXING` option may be swapped with `BROYDEN_MIXIN
`KERKER_MIXING`, etc.
Fractional occupation of molecular orbitals, or smearing, is enabled by the section
[SMEAR](#CP2K_INPUT.FORCE_EVAL.DFT.SCF.SMEAR). It is very useful for systems with small to none band
gap and strong static correlation. The possibilities provided by the keyword
[METHOD](#CP2K_INPUT.FORCE_EVAL.DFT.SCF.SMEAR.METHOD) include Fermi-Dirac smearing at a certain
[ELECTRONIC_TEMPERATURE](#CP2K_INPUT.FORCE_EVAL.DFT.SCF.SMEAR.ELECTRONIC_TEMPERATURE) and several
broadening methods with width [SIGMA](#CP2K_INPUT.FORCE_EVAL.DFT.SCF.SMEAR.SIGMA); elevated
ELECTRONIC_TEMPERATURE or SIGMA can handle difficult systems, but extrapolation to 0 is required to
obtain results comparable with what without smearing.
[SMEAR](#CP2K_INPUT.FORCE_EVAL.DFT.SCF.SMEAR) which is very useful for systems with small to none
band gap and strong static correlation. The possibilities provided by the keyword
[METHOD](#CP2K_INPUT.FORCE_EVAL.DFT.SCF.SMEAR.METHOD) include Fermi-Dirac distribution and several
broadening methods like Gaussian broadening. An elevated
[ELECTRONIC_TEMPERATURE](#CP2K_INPUT.FORCE_EVAL.DFT.SCF.SMEAR.ELECTRONIC_TEMPERATURE) for the
Fermi-Dirac smearing can handle difficult systems, but extrapolation to 0 is required to obtain
results comparable with what without smearing. Likewise, the Gaussian broadening should use a width
[SIGMA](#CP2K_INPUT.FORCE_EVAL.DFT.SCF.SMEAR.SIGMA) systematically reduced to 0. Also note that some
algorithms is compatible only with the uniform occupation.
## For OT
### For OT
Alternative to the diagonalization is the orbital transformation ({term}`OT`) method, activated by
setting the [OT](#CP2K_INPUT.FORCE_EVAL.DFT.SCF.OT) section. The most important settings are
[ALGORITHM](#CP2K_INPUT.FORCE_EVAL.DFT.SCF.OT.ALGORITHM),
[LINESEARCH](#CP2K_INPUT.FORCE_EVAL.DFT.SCF.OT.LINESEARCH),
[MINIMIZER](#CP2K_INPUT.FORCE_EVAL.DFT.SCF.OT.MINIMIZER), and
Alternative to the diagonalization is the minimization-based orbital transformation ({term}`OT`)
method, activated by setting the [OT](#CP2K_INPUT.FORCE_EVAL.DFT.SCF.OT) section. The most important
settings are [ALGORITHM](#CP2K_INPUT.FORCE_EVAL.DFT.SCF.OT.ALGORITHM) for the algorithm,
[LINESEARCH](#CP2K_INPUT.FORCE_EVAL.DFT.SCF.OT.LINESEARCH) and
[MINIMIZER](#CP2K_INPUT.FORCE_EVAL.DFT.SCF.OT.MINIMIZER) for the minimization, and
[PRECONDITIONER](#CP2K_INPUT.FORCE_EVAL.DFT.SCF.OT.PRECONDITIONER).
The [OUTER_SCF](#CP2K_INPUT.FORCE_EVAL.DFT.SCF.OUTER_SCF) section controls an outer loop where the
OT preconditioner is updated. The conventional loop for updating Kohn-Sham matrix is the inner loop
now: if [SCF/MAX_SCF](#CP2K_INPUT.FORCE_EVAL.DFT.SCF.MAX_SCF) is met without satisfying
[SCF/EPS_SCF](#CP2K_INPUT.FORCE_EVAL.DFT.SCF.EPS_SCF), the program leaves the inner loop, updates
the OT preconditioner as one iteration of the outer loop, then starts another inner loop. In this
scenario, [SCF/MAX_SCF](#CP2K_INPUT.FORCE_EVAL.DFT.SCF.MAX_SCF) can be reduced to about 16 to 32 so
as to invoke the preconditioner maker with an adequate frequency balancing time cost and convergence
behavior. Setting [SCF/OUTER_SCF/MAX_SCF](#CP2K_INPUT.FORCE_EVAL.DFT.SCF.OUTER_SCF.MAX_SCF) to about
8 to 16 suffices for most situations.