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 | the full CPMD setup on the | | | changed cell, cutoff, or | composed deck, then the SCF | | | state count, or the session | from CPMD's initial guess, or | | | was re-configured | from ``RESTART`` when the | | | | deck has | | | | ``RESTART WAVEFUNCTION`` | +------+-------------------------------+-------------------------------+ | warm | the previous call of this | new positions into ``tau0``, | | | session succeeded and the | ``phfac``, then the SCF from | | | cell, cutoff, and state count | the stored ``c0`` | | | are unchanged | | +------+-------------------------------+-------------------------------+ 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 | those inputs set the number of | | numbers, charge, or multiplicity | states, and a restored ``c0`` of | | | another shape calls ``stopgm`` | +----------------------------------+----------------------------------+ | ``cpmdc_session_set_params()`` | a new method invalidates the | | or ``cpmdc_session_configure()`` | orbitals | +----------------------------------+----------------------------------+ | evaluating a different session | the stored copy is process-wide; | | in the same process | the other session re-applies its | | | configuration and starts cold | +----------------------------------+----------------------------------+ | any global call | each applies its message afresh | | (``cpmdc_set_params()``, | | | ``cpmdc_energy*()``) or a | | | one-shot call | | | (``cpmdc_calculate_result()``) | | +----------------------------------+----------------------------------+ | ``stopgm`` returns through | the call continued past a failed | | ``cpmd_stopgm_hook`` | 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 :doc:`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.