Restarting CP2K Calculations
Restarting CP2K calculations is useful for continuing interrupted tasks, extending the trajectory of molecular dynamics simulations, or using converged wavefunctions or geometry as starting points for new calculations. This guide explains how to produce and utilize two major types of restart files:
Motion restart file for tasks involving atomic motion (such as optimization and molecular dynamics) with any force method;
Wavefunction restart for tasks using the Quickstep module for the force method (such as DFT, post-HF and SE) with or without atomic motion.
Other specialized functionalities may also define their custom restart files, which are not covered by this guide. Refer to the dedicated documentation and input section for those cases.
Prerequisites
File forms
In Fortran terminology, there are two forms of file input/output:
One is formatted, which is for ASCII plain-text, human-readable files;
The other is unformatted, which is for binary machine-readable (but not human readable) files.
The formatted files are open to manual text editing and are portable between machines, while the unformatted files are generally only intended to be consumed internally by the same program on the same machine that has produced it. The data storage pattern in unformatted files may be subject to changes during program development; there is no guarantee for backwards or forwards compatibility of unformatted files across versions even with identical machine and compiler environments. Contact developers if there is some advanced need to read and modify unformatted files.
The form of a file can be readily checked with the file command: returning ASCII text means
formatted, and returning something else like SIMH tape data means unformatted.
$ file ./project-1.restart
/path/to/project-1.restart: ASCII text
$ file ./project-RESTART.wfn
/path/to/project-RESTART.wfn: SIMH tape data
Iteration levels in CP2K
Many methods use an iterative procedure to obtain the results, which may be nested into layers; for example, when using Quickstep KS-DFT for a geometry optimization task, the optimizer refreshes the geometry with the energy and gradient (force) information in a step-by-step manner, and each step of evaluating energy and gradient with KS-DFT requires several SCF cycles of updating the wavefunction.
In CP2K, iteration levels are used to manage layers of iterative procedures and control the
frequency of printing output files. The names and descriptions of iteration levels can be found in
the input reference under any section named EACH, such as QS_SCF for the SCF cycles in Quickstep
module, GEO_OPT for the steps of fixed-cell geometry optimization, CELL_OPT for those of cell
optimization, MD for timesteps of molecular dynamics, etc. So for GEO_OPT, a value of 1 set in
the EACH section means printing once every 1 step of geometry optimization, 5 means once every 5
steps, and a non-positive integer means no printing at all. Different EACH sections can have
different default values for each iteration level, as can be checked in the input reference.
The presence of iteration levels depends primarily, but not solely, on the type of current task as
specified by GLOBAL/RUN_TYPE; for instance, a GEO_OPT task may
target a local minimum or a saddle point, the latter of which has the ROT_OPT iteration level as
defined by the dimer method in addition to the GEO_OPT level. To understand what iteration levels
are involved, adjust ITER_LEVEL_VERBOSITY. The EACH
sections will ignore iteration levels not present in the current task even if specified. Also, while
the control of output files uses input sections with the EACH section, non-default settings of
EACH are only meaningful when the output is actually available during iterations; some like the
FINAL_STRUCTURE are only meant for a finished iteration.
Motion restart
A motion restart file stores information of a snapshot, including atomic positions, velocities, cell parameters, thermostat/barostat states, elastic band states, random number generator states, etc. It is produced with the MOTION/PRINT/RESTART and MOTION/PRINT/RESTART_HISTORY sections from a task with particle motion. Take the following snippet of the input sections for a molecular dynamics (MD) task as an example.
&GLOBAL
PRINT_LEVEL LOW
PROJECT_NAME md_project
RUN_TYPE MD
&END GLOBAL
&MOTION
&MD
! Other important settings omitted for clarity
STEPS 600
STEP_START_VAL 0
&END MD
&PRINT
&RESTART ON
BACKUP_COPIES 0
&EACH
MD 1
&END EACH
&END RESTART
&RESTART_HISTORY ON
&EACH
MD 200
&END EACH
&END RESTART_HISTORY
&END PRINT
&END MOTION
The MD task will run for 600 steps, also called iterations, as specified by keyword STEP. The
STEP_START_VAL specifies that the counter of the steps starts at 0; even though 0 is just the
default value (if omitted from input), this keyword is written explicitly for later discussion. The
STEP value of 600 does not limit STEP_START_VAL to under 600.
After normal termination of such a task, check the presence of files using a .restart suffix with
the find command:
$ find . -type f -name "*.restart"
./md_project-1.restart
./md_project-1_200.restart
./md_project-1_400.restart
./md_project-1_600.restart
These are motion restart files that record information on some selected iterations. By default, they
are formatted as a regular CP2K input file and can be read and edited with common command-line tools
like less, more, vim, nano, etc. They contain not only the explicit settings provided in the
original input but also other implicit definitions of default values; moreover, the numerical values
are written in a scientific notation with many significant digits. Thus, it is expected that motion
restart file is generally longer than the original input.
The STEP_START_VAL value shows which iteration each restart file is at.
The first one,
md_project-1.restart, is produced due to settingMOTION/PRINT/RESTARTto ON. Its record is from the most recent iteration; givenEACH/MDset to 1, it is updated every 1 iteration. IfEACH/MDis set to 5, the record will be updated every 5 iterations instead.The other three,
md_project-1_{200,400,600}.restart, are produced due to settingMOTION/PRINT/RESTART_HISTORYto ON. Their records are from the respective historically visited iterations; givenSTEPset to 600,STEP_START_VALset to 0 andEACH/MDset to 200, they correspond to the iterations above 0 but not above (0+600) that is a multiple of 200, namely the 200-th, 400-th, and 600-th iterations in this case.
The record in md_project-1.restart is most recent in a chronological sense, which depending on
the value of EACH/MD and how program is terminated may or may not be the exact latest iteration.
If the task has been run to completion as a normal termination, md_project-1.restart is the latest
record as can be verified with the STEP_START_VAL value, regardless of whether iterations counter
finishes at a multiple of the EACH/MD value. In case an out-of-memory, job scheduler interruption
or other disturbance triggers externally an erroneous termination, chances are that the unfortunate
timing does not permit rescuing the status by printing one more restart file; a smaller EACH/MD
value would leave a restart file more recent than a larger one would.
In practice, it is not always ideal to set the frequency to 1: a very long input file with a massive atomistic model and complicated definition of the force method can lead to reduced performance and significant burden on disk I/O, especially if the formatted motion restart file needs to be dumped frequently. In such rare cases, see the hint at the end of this section.
Unlike RESTART_HISTORY that uses a filename containing the unique iteration counter, the RESTART
uses one single filename for printing on different iterations and overwrites in updates accordingly;
the filename is determined by the FILENAME keyword. The
BACKUP_COPIES keyword accompanies the overwriting
behavior by creating backup files. In the snippet above it is explicitly set to 0 to disable backup.
If set to a positive number N instead, old files will be moved gradually out of the way and renamed
to add a suffix; in the end, apart from the most recent md_project-1.restart, a series of N backup
files ranging from the newer md_project-1.restart.bak-1 to the older md_project-1.restart.bak-N
will also exist. While restart backup files do preserve several snapshots, they are not intended for
reconstruction of the entire trajectory from the very beginning.
A motion restart file can be utilized by directly passed to CP2K as an input file.
cp2k.psmp -i md_project-1.restart -o md_project-1.restart.out
A motion restart files can also be parsed in the EXT_RESTART section in another freshly created input, where RESTART_FILE_NAME should point to the existing restart file.
The EXT_RESTART section offers fine-grained control over which components to restart. The default
is to restart all of them if available and meaningful for the current task; this can be inverted by
setting the keyword RESTART_DEFAULT to .FALSE. and then
selectively setting a few other items back to .TRUE.. In addition, there is the keyword
CUSTOM_PATH that enables copying entire input sections from
the restart to the current input.
Hint
For situations where it is expected that formatted motion restart files will have extreme size, it is possible to use an unformatted version produced by RESTART/SPLIT_RESTART_FILE and parsed by EXT_RESTART/BINARY_RESTART_FILE_NAME.
Generally, the best practices for using a motion restart is to check parameter consistency and keep backup copies for long simulations. Values such as potential energies, temperatures, and conserved quantities that vary continuously with steps should not show sudden jumps (discontinuity) before and after the usage of a restart file. Motion restart file alone may not guarantee that the potential energy is evaluated consistently if the force method is dependent on history and sensitive to the initial guess; other restart files specific to the method are also needed, with the wavefunction restart introduced in the next section for Quickstep DFT a primary example.
If a restarted run keeps the original PROJECT_NAME and is under the same directory with all of the
original output files in place, be careful that new outputs may either be appended to the end of the
existing files, or overwriting the files from the start; manual backups in other directories can
prevent accidental data loss or unintentional concatenation.
Wavefunction restart
A wavefunction restart file is used by tasks with the Quickstep module for the force method, which stores electronic structure information obtained from the SCF cycles. It is most commonly produced with the FORCE_EVAL/DFT/SCF/PRINT/RESTART and FORCE_EVAL/DFT/SCF/PRINT/RESTART_HISTORY sections. Unlike formatted motion restart files, wavefunction restart files are unformatted and are not intended for human reading, plaintext editing, porting to other binaries, or downstream electronic-structure analyses. Other well-defined Molecular orbitals output is available as the interface to post-processing programs for that last purpose.
The following snippet turns off the RESTART_HISTORY and keeps only the RESTART with no backups
for a task of single-point energy evaluation.
&GLOBAL
PRINT_LEVEL LOW
PROJECT project_name
RUN_TYPE ENERGY
&END GLOBAL
&FORCE_EVAL
METHOD QS
&DFT
! Other important settings omitted for clarity
&SCF
SCF_GUESS ATOMIC
&PRINT
&RESTART ON
BACKUP_COPIES 0
&END RESTART
&RESTART_HISTORY OFF
&END RESTART_HISTORY
&END PRINT
&END SCF
&END DFT
&END FORCE_EVAL
The wavefunction restart file, say project_name-RESTART.wfn, can then be utilized by setting the
FORCE_EVAL/DFT/WFN_RESTART_FILE_NAME to it and
switching FORCE_EVAL/DFT/SCF/SCF_GUESS to RESTART.
&FORCE_EVAL
&DFT
WFN_RESTART_FILE_NAME project_name-RESTART.wfn
&SCF
SCF_GUESS RESTART
&END SCF
&END DFT
&END FORCE_EVAL
If WFN_RESTART_FILE_NAME is not explicitly given, the filename of the wavefunction restart will be
deduced from the FORCE_EVAL/DFT/SCF/PRINT/RESTART/FILENAME (regardless of whether the section is
explicitly given or not) and the GLOBAL/PROJECT_NAME. Using SCF_GUESS RESTART without a properly
named restart file will result in a warning and fallback to another method of initial guess.
*** WARNING in qs_initial_guess.F:312 :: User requested to restart the ***
*** wavefunction from the file named: project_name-RESTART.wfn. This file ***
*** does not exist. Please check the existence of the file or change ***
*** properly the value of the keyword WFN_RESTART_FILE_NAME. Calculation ***
*** continues using ATOMIC GUESS. ***
SCF_GUESS RESTART takes a single wavefunction restart file. Meanwhile, SCF_GUESS HISTORY_RESTART
takes a series of these files, starting with project_name-RESTART.wfn and continuing to backups
project_name-RESTART.wfn.bak-1, …, project_name-RESTART.wfn.bak-N, as a positive number of
BACKUP_COPIES in FORCE_EVAL/DFT/SCF/PRINT/RESTART would generate. The number of files required
for such a history restart depends on the Quickstep extrapolation method and order, as specified by
EXTRAPOLATION and
EXTRAPOLATION_ORDER keywords under the
FORCE_EVAL/DFT/QS section.
Notes about k-point sampling
The usage of k-point sampling in Brillouin zone, which is enabled with the section FORCE_EVAL/DFT/KPOINTS, makes a significant difference in the file type of unformatted wavefunction restart files:
If the section is not explicitly set, referred to as an “implicit gamma” formalism below, the
.wfnsuffix will be used (which is not to be confused with the plaintext AIM wavefunction file also with the.wfnsuffix that several other quantum chemistry programs can output) and the contents include atomic basis sets and per-spin eigenvalues and occupation numbers;If the section is explicitly set, referred to as an “explicit k-point” formalism below, regardless of the actual number of k-points sampled in the scheme, the
.kpsuffix will be used and the content include density matrix for each spin and cell image.
The entire workflow of writing and reading wavefunction restart files are handled with separate machinery, and thus it is not possible to swap them for restarting purposes. Also compare the treatment of mismatching system configurations between the restart file and the input file:
Number of atoms (
natom) - both implicit gamma and explicit k-point will reject a mismatch and fallback to another method of initial guess;Number of spins (
nspin) - explicit k-point will reject a mismatch, whereas implicit gamma may allow one but only under the restriction that (1) the number of spins in the restart is fewer than requested in the input, and (2) the input requests a multiplicity of 1;Number of basis functions in atomic orbitals (
nao) - explicit k-point will reject a mismatch, implicit gamma can allow one;Number of molecular orbitals (
nmo) - specific to implicit gamma, some truncation or padding with zeroes will be carried out in case of a MO mismatch, but if the number of occupied orbitals in the restart as indicated by the index of HOMO is higher than total number of available MOs from input due to more electrons of a spin in the restart than input, then restarting is rejected.Number of cell images (
nimages) - specific to explicit k-point, a mismatch is allowed.
For explicit k-point sampling, the FULL_GRID keyword
in the KPOINTS section controls whether all k-points (including symmetry-equivalent ones) or only
irreducible k-points should be used and written to the restart. FULL_GRID ON uses all, which has
maximum restart flexibility; the default FULL_GRID OFF is faster but restricted to the same
symmetry settings. K-point restart files generated with FULL_GRID ON can be used with
FULL_GRID OFF in the restart calculation (or vice versa). Both converge to the same energy,
typically in 1 SCF step.
A complete example of k-point samping and restart files is demonstrated below. Despite distinctions described above, the relevant input keywords are otherwise identical with the implicit gamma case.
&GLOBAL
PROJECT H_SYM
RUN_TYPE ENERGY
&END GLOBAL
&FORCE_EVAL
&DFT
BASIS_SET_FILE_NAME GTH_BASIS_SETS
POTENTIAL_FILE_NAME POTENTIAL
&KPOINTS
FULL_GRID ON
SCHEME MONKHORST-PACK 2 2 2
SYMMETRY ON
&END KPOINTS
&SCF
SCF_GUESS ATOMIC
&PRINT
&RESTART ON
&END RESTART
&END PRINT
&END SCF
&XC
&XC_FUNCTIONAL PADE
&END XC_FUNCTIONAL
&END XC
&END DFT
&SUBSYS
&CELL
ABC 3.56683 3.56683 3.56683
&END CELL
&COORD
SCALED
H 0.100000 0.000000 0.000000
H 0.500000 0.500000 0.000000
...
&END COORD
&KIND H
BASIS_SET SZV-GTH
POTENTIAL GTH-PADE-q1
&END KIND
&END SUBSYS
&END FORCE_EVAL
This generates H_SYM-RESTART.kp. Restarting with a different FULL_GRID setting:
&DFT
WFN_RESTART_FILE_NAME H_SYM-RESTART.kp
&KPOINTS
FULL_GRID OFF ! Different from initial calculation
SCHEME MONKHORST-PACK 2 2 2
SYMMETRY ON
&END KPOINTS
&SCF
SCF_GUESS RESTART
MAX_SCF 3
&PRINT
&RESTART OFF
&END RESTART
&END PRINT
&END SCF
&XC
&XC_FUNCTIONAL PADE
&END XC_FUNCTIONAL
&END XC
&END DFT
The CP2K test suite includes k-point restart tests in tests/QS/regtest-kp-1/.
Harris Chain
The Harris functional converts a k-point wavefunction into a gamma-point wavefunction, enabling
k-point-converged densities to seed gamma-point calculations. The three-step chain is: k-point SCF
→ k-point Harris functional → gamma-point DFT.
Step 1: K-point SCF — generates {PROJECT}-1_0.kp:
&GLOBAL
PROJECT Carbon
RUN_TYPE ENERGY
&END GLOBAL
&FORCE_EVAL
&DFT
BASIS_SET_FILE_NAME BASIS_SET
POTENTIAL_FILE_NAME GTH_POTENTIALS
&KPOINTS
FULL_GRID ON
SCHEME MONKHORST-PACK 2 2 2
SYMMETRY ON
&END KPOINTS
&SCF
SCF_GUESS ATOMIC
&PRINT
&RESTART ON
&END RESTART
&END PRINT
&END SCF
&XC
&XC_FUNCTIONAL PADE
&END XC_FUNCTIONAL
&END XC
&END DFT
&SUBSYS
&CELL
ABC 3.56683 3.56683 3.56683
&END CELL
&COORD ...
&KIND C
BASIS_SET ORB DZVP-GTH-PADE
POTENTIAL GTH-PADE-q4
&END KIND
&END SUBSYS
&END FORCE_EVAL
This generates Carbon-1_0.kp.
Step 2: Harris functional with k-points — reads the .kp file and writes a gamma-point
wavefunction to {PROJECT}-Harris-1_0.kp via HARRIS_OUTPUT_WFN:
&GLOBAL
PROJECT Carbon
RUN_TYPE ENERGY
&END GLOBAL
&FORCE_EVAL
&DFT
BASIS_SET_FILE_NAME BASIS_SET
POTENTIAL_FILE_NAME GTH_POTENTIALS
WFN_RESTART_FILE_NAME ./Carbon-1_0.kp
&ENERGY_CORRECTION
ENERGY_FUNCTIONAL HARRIS
HARRIS_BASIS HARRIS
&KPOINTS
FULL_GRID ON
SCHEME MONKHORST-PACK 2 2 2
SYMMETRY ON
&END KPOINTS
&PRINT
&HARRIS_OUTPUT_WFN
&END HARRIS_OUTPUT_WFN
&END PRINT
&XC
&XC_FUNCTIONAL PBE
&END XC_FUNCTIONAL
&END XC
&END ENERGY_CORRECTION
&SCF
SCF_GUESS RESTART
&PRINT
&RESTART OFF
&END RESTART
&END PRINT
&XC
&XC_FUNCTIONAL PADE
&END XC_FUNCTIONAL
&END XC
&END DFT
&SUBSYS
&KIND C
BASIS_SET ORB DZVP-GTH-PADE
BASIS_SET HARRIS SZV-GTH-PADE
POTENTIAL GTH-PADE-q4
&END KIND
&END SUBSYS
&END FORCE_EVAL
Key points:
ENERGY_CORRECTION+ENERGY_FUNCTIONAL HARRISenables the Harris functionalHARRIS_BASIS HARRISuses the smaller Harris basis setKPOINTSinENERGY_CORRECTIONmust match the step 1 gridHARRIS_OUTPUT_WFNwrites{PROJECT}-Harris-1_0.kpThe
KINDsection needs both the orbital and theHARRISbasis set
This generates Carbon-Harris-1_0.kp.
Step 3: Gamma-point DFT — reads the Harris wavefunction and optionally writes a .wfn file:
&GLOBAL
PROJECT Carbon_gamma
RUN_TYPE ENERGY
&END GLOBAL
&FORCE_EVAL
&DFT
BASIS_SET_FILE_NAME BASIS_SET
POTENTIAL_FILE_NAME GTH_POTENTIALS
WFN_RESTART_FILE_NAME ./Carbon-Harris-1_0.kp
&SCF
SCF_GUESS RESTART
&PRINT
&RESTART ON
&END RESTART
&END PRINT
&XC
&XC_FUNCTIONAL PADE
&END XC_FUNCTIONAL
&END XC
&END DFT
&SUBSYS
&KIND C
BASIS_SET ORB DZVP-GTH-PADE
POTENTIAL GTH-PADE-q4
&END KIND
&END SUBSYS
&END FORCE_EVAL
No
KPOINTSsection — this is a gamma-point calculation&RESTART ONwritesCarbon_gamma-RESTART.wfn
The CP2K test suite includes these Harris chain tests in tests/QS/regtest-harris-kp/
(cc_kp_01.inp, cc_kp_02.inp, cc_kp_03.inp) which demonstrate the three-step k-point restart
process.
Band and NEB Calculations
A band calculation writes a separate wavefunction restart for every replica. CP2K derives the
replica project names from the project in GLOBAL, for example:
neb-BAND1-RESTART.wfn
neb-BAND2-RESTART.wfn
neb-BAND3-RESTART.wfn
With k-point sampling, the corresponding files have the .kp extension. To reuse these files, set
SCF_GUESS RESTART but normally omit WFN_RESTART_FILE_NAME:
&GLOBAL
PROJECT neb
RUN_TYPE BAND
&END GLOBAL
&EXT_RESTART
RESTART_FILE_NAME neb-1.restart
&END EXT_RESTART
&FORCE_EVAL
&DFT
# Do not set WFN_RESTART_FILE_NAME here.
&SCF
SCF_GUESS RESTART
&END SCF
&END DFT
...
&END FORCE_EVAL
CP2K then selects neb-BAND<N>-RESTART.wfn or neb-BAND<N>-RESTART.kp after assigning the current
replica project name. In contrast, an explicitly specified WFN_RESTART_FILE_NAME is interpreted
literally and is shared by all replicas; CP2K does not insert the -BAND<N> part. An explicit name
is therefore useful when all replicas should deliberately start from the same wavefunction, but a
name such as neb-RESTART.kp will not select the per-replica files shown above.
The EXT_RESTART file restores the band coordinates and optimizer state. This is independent of the
per-replica wavefunction restarts, so use both EXT_RESTART and SCF_GUESS RESTART when both parts
of an interrupted band calculation should be continued. Keep the original PROJECT name and run
from the directory containing the restart files, or preserve their relative paths.
CDFT
For mixed CDFT calculations, each constrained state requires its own wavefunction restart file.
Specify SCF_GUESS RESTART and WFN_RESTART_FILE_NAME per FORCE_EVAL subblock:
&FORCE_EVAL
METHOD MIXED
&MIXED
MIXING_TYPE MIXED_CDFT
&MIXED_CDFT
WFN_OVERLAP TRUE
WFN_RESTART_FILE_NAME reference_wavefunction.wfn
&END MIXED_CDFT
&END MIXED
&END FORCE_EVAL
Mixed CDFT calculations require separate wavefunction restart files for each constrained state. The
CP2K test suite includes examples in tests/QS/regtest-cdft-3/: single-state CDFT calculations
generate wavefunction files that are then used as restarts for mixed CDFT calculations.