Goal
====

Pick the CPMD wavefunction optimiser for a session that evaluates many
nearby geometries, such as a minimisation, a saddle search, or a nudged
elastic band. Every call after the first starts from the orbitals of the
previous call, so the optimiser that suits a cold start from atomic
orbitals is not always the cheapest for the warm calls that follow.

Measured on the Si3N4 cluster
=============================

One minimisation of a 7-atom Si3N4 cluster, BLYP at 70 Ry in a 14
Angstrom cube with Kleinman-Bylander pseudopotentials, library route on
16 MPI ranks, orbital convergence 1e-5. The two runs differ only in the
optimiser line of the ``&CPMD`` section.

+------------------+----------+----------+----------+----------+--------------+
| Optimiser        | Wall     | Force    | SCF      | Seconds  | Minimum (eV) |
|                  | time     | calls    | steps    | per SCF  |              |
|                  |          |          |          | step     |              |
+==================+==========+==========+==========+==========+==============+
| ``PCG MINIMIZE`` | 734 s    | 33       | 515      | 1.26     | -1396.271181 |
| (the deck's      |          |          |          |          |              |
| choice)          |          |          |          |          |              |
+------------------+----------+----------+----------+----------+--------------+
| ``ODIIS`` with   | 255 s    | 23       | 296      | 0.64     | -1396.271246 |
| 10 vectors       |          |          |          |          |              |
+------------------+----------+----------+----------+----------+--------------+

Both reach the same minimum: the two energies differ by 0.065 meV,
inside the orbital convergence tolerance. ODIIS (orbital direct
inversion in the iterative subspace) needed fewer and cheaper SCF steps.
PCG (preconditioned conjugate gradient) with ``MINIMIZE`` runs a line
minimisation that costs about two energy evaluations per step.

Set ODIIS in the message
========================

.. code:: capnp

   ( cpmd = ( optimizeWavefunction = true,
              convergenceOrbitals = 1.0e-5,
              maxIter = 400,
              odiisVectors = 10 ) )

``odiisVectors = 10`` renders ``ODIIS`` followed by ``10`` on the next
line. With no optimiser keyword at all, OpenCPMD 4.3 also uses
preconditioned DIIS with 10 vectors; its output then reads
``WAVEFUNCTION OPTIMIZATION BY PRECONDITIONED DIIS`` and
``MAXIMUM NUMBER OF VECTORS RETAINED FOR DIIS: 10``. Writing
``odiisVectors`` keeps the choice visible in the message.
``odiis = true`` renders a bare ``ODIIS`` with CPMD's default vector
count, and ``odiisOptions`` adds inline options such as ``NOPREC``. To
keep the deck's PCG line instead, use a directive:

.. code:: capnp

   ( cpmd = ( optimizeWavefunction = true,
              convergenceOrbitals = 1.0e-5,
              maxIter = 400,
              directives = [ ( keyword = "PCG MINIMIZE", args = [] ) ] ) )

Set only one optimiser in a message. Check the rendered ``&CPMD``
section with ``CPMDC_DECK_OUT`` (see
:doc:`debugging a deck <debug-deck>`).

When to keep PCG
================

``cpmdc`` applies one deck to every call of a session, so the optimiser
chosen for the warm calls also runs the cold first call from atomic
orbitals. Keep ``PCG MINIMIZE`` for a system whose ODIIS calls stop at
``MAXITER``: each such call is reported as a failure (see
:doc:`troubleshooting <troubleshooting>`), and the optimiser choice does
not change the converged state, only the path to it.

Always set MAXITER
==================

Without ``maxIter``, the OpenCPMD path inserts ``MAXITER 40`` into the
first deck. A warm call on a geometry that moved far from the previous
one can need more steps than that, and an SCF that stops at the limit
fails the call.