A force call on a geometry close to the previous one should not start
its SCF from scratch. The converged orbitals of the last call, c0 in
OpenCPMD, are a far better starting point than atomic orbitals, and
keeping them in memory is the main reason to run CPMD inside the host.
This page follows c0 from call to call.
Cold and warm calls¶
Each session keeps a counter of successful warm-capable calls and the cell of the call that started them.
Call |
Condition |
What runs |
|---|---|---|
cold |
first call of a session, a changed cell, cutoff, or state count, or the session was re-configured |
the full CPMD setup on the
composed deck, then the SCF
from CPMD’s initial guess, or
from |
warm |
the previous call of this session succeeded and the cell, cutoff, and state count are unchanged |
new positions into |
A cell counts as unchanged when every component of ForceInput.box
matches the stored cell within 1e-8 Angstrom, and when both calls agree
on having a box at all. The cutoff matches within 1e-8 Rydberg. The
state count follows the number of atoms, their atomic numbers, the
charge, and the multiplicity. A failed warm call leaves the counter
where it was, so the next call is warm again; a failed cold call clears
the stored results. An SCF that does not converge does not replace the
stored orbitals. When ODIIS exhausts MAXITER, the same call
continues once with PCG MINIMIZE. That pass restores the previous
converged c0 when a converged copy is already stored, and it still
counts as warm. A stopgm during the call is not that failure: the
wavefunction, forces, and module state of the call are undefined,
cpmdc drops the stored orbitals and the warm cell, and the next call
runs setup again. With more than one MPI rank, cpmdc aborts the
other ranks.
Where the orbitals are kept¶
opencpmd_embed_rwfopt.patch adds a module-level copy of c0 to
rwfopt_utils. At the end of rwfopt, every rank saves its own
slice of c0 when embed_warm_orbitals is true and
ropt_mod%convwf is true. A call that does not converge leaves the
previous copy in place. A failed store allocation calls stopgm.
cpmdc sets embed_warm_orbitals on every SCF, including the
first. Restore does nothing until a converged copy exists, so the first
call still starts from CPMD’s guess and stores c0 only if that SCF
converges. On a later call, rwfopt first runs initrun, which
sets up the iteration state and scratch arrays as for any SCF, and then
overwrites the generated starting orbitals with the saved copy when its
shape still matches. A different shape calls stopgm and names
embed_reset_warm_orbitals. cpmdc makes that call when the
cutoff, the cell, or the state count changes, before rwfopt runs.
The SCF then runs to the orbital convergence threshold with the full
MAXITER budget of the deck; a warm call is a complete SCF from a
better start, not a shortened one.
opencpmd_converged_state.patch makes the saved copy trustworthy. In
stock OpenCPMD, updwf applies an optimiser step to c0 before it
checks convergence, so the orbitals left behind after the last iteration
have moved one step past the ones that produced the reported energy and
forces. The patch checks convergence first and updates only unconverged
orbitals, so the saved c0 is the state that forcedr used.
Steepest descent with iproj <= 1 sets gemax above the threshold
before that check: those steps do not converge on gemax.
What clears the orbitals¶
Event |
Why |
|---|---|
a cell change |
the plane-wave basis depends on the cell, so the stored coefficients no longer fit |
a cutoff change |
the plane-wave basis changes, so the stored coefficients no longer fit |
a change of atom count, atomic numbers, charge, or multiplicity |
those inputs set the number of
states, and a restored |
|
a new method invalidates the orbitals |
evaluating a different session in the same process |
the stored copy is process-wide; the other session re-applies its configuration and starts cold |
any global call
( |
each applies its message afresh |
|
the call continued past a failed check, so the stored orbitals are not a result |
A topology change is refused outright rather than treated as cold: the atom count and the ordered atomic numbers belong to the session.
The RESTART file¶
The warm path never reads or writes RESTART on the host’s behalf.
CPMD still writes RESTART.1 at the end of each SCF, in
permanentDir if that field is set, otherwise in scratchDir,
otherwise in the host working directory, and reads one on a cold call
when the deck asks for RESTART WAVEFUNCTION. cpmdc turns off
CPMD’s restart of coordinates, velocities, and the stored geometry
before every SCF: the host owns the geometry, and a
RESTART COORDINATES in the deck would otherwise overwrite the step’s
positions.
To seed a cold start from an earlier run with a new geometry, patch the
positions of a RESTART.1 with cpmdc-restart patch-positions. It
rewrites only the coordinate records and copies the wavefunction records
unchanged; the deck then needs RESTART WAVEFUNCTION.
The optimiser on a warm start¶
A warm start changes how far the SCF has to go, not how it gets there.
CPMD’s optimiser choice then decides the cost: ODIIS reuses its history
of residuals, while PCG MINIMIZE runs a line minimisation per step.
On the Si3N4 cluster of the route comparison, the same
minimisation took 515 SCF steps at 1.26 s with PCG MINIMIZE and 296
steps at 0.64 s with ODIIS, to the same minimum.