Troubleshooting

Each entry names the symptom, the cause in the code, and the fix. Set CPMDC_DECK_OUT first when the symptom involves energies (see debugging a deck). The last section says how to report a problem that no entry covers.

Energies

The energy is off by about 2 eV from a hand-written deck

Cause: KLEINMAN-BYLANDER belongs on the pseudopotential file line, \*Si_MT_BLYP.psp KLEINMAN-BYLANDER. On the LMAX= line below it CPMD ignores the keyword without a warning and integrates the nonlocal projectors by Gauss-Hermite quadrature. On a 7-atom Si3N4 cluster that alone moved the energy from -1396.2695 eV to -1398.3638 eV, 2.09 eV.

Fix: set kleinmanBylander = true on each CPMDAtomsPseudopotential entry, which renders the keyword on the file line. In inputBlocks or raw text, write it on the \*file line yourself.

The system is treated as isolated

Cause: the deck that runs has SYMMETRY 0, CLUSTER, an isolated-molecule keyword, POISSON SOLVER HOCKNEY, or a zero box. A typed system section that leaves symmetry at 0 still adds the Hockney solver, including when the box has a positive volume. A message with no system section takes its symmetry from the box on the force call.

Fix: write symmetry and cell when the system is periodic, and poissonSolver when it is isolated on purpose. In eOn, pass the whole message through [RgpotPot] params_path instead of the scalar keys (see the eOn tutorial). A scalar message with a positive cell is periodic. Put poissonSolver = "HOCKNEY" or symmetry = 0 in the message when the molecule is isolated.

The energy changes when only the cell changes

Cause: a cell that differs from the previous call’s cell makes the next call cold: cpmdc clears the stored orbitals and runs CPMD’s full setup again. The energy is then that of a fresh SCF in the new cell.

Fix: none needed when the cell change is intended. Keep ForceInput.box identical between steps when the cell is fixed; a difference above 1e-8 Angstrom in any component counts as a change.

Failed calls

orbitals not converged within MAXITER, or no energy

Cause: the SCF stopped at MAXITER before reaching the orbital convergence threshold. OpenCPMD computes ionic forces only for converged orbitals, so the forces of such a call are zero, which a caller would read as a stationary point; cpmdc reports the call as failed instead, with ok == 0. Without maxIter in the message the OpenCPMD path inserts MAXITER 40.

The same message has one other cause visible before the SCF starts:

Check

Cause

an element absent from atoms.pseudopotentials and outside H, C, N, O, Si, and Ge

the message and the built-in table have no pseudopotential, so no deck is composed; the error names the atomic number

Fix: raise maxIter, or switch the optimiser (see choosing the optimiser); otherwise put that element’s pseudopotential in the message, or use an element the built-in table knows.

A missing pseudopotential directory is a different message. When neither CPMDC_PSEUDO_DIR nor CPMD_PP_LIBRARY_PATH names a directory, CPMDCResult.message and cpmdc_last_error() say so.

Atoms of one element need not be contiguous in ForceInput. CPMD keeps one species block per element. cpmdc places the step’s positions into those blocks and copies the forces back into ForceInput order. A step whose atomic numbers do not match the species counts still fails, and the message names the species blocks rather than MAXITER.

CPMD stopgm during embed SCF

Cause: CPMD called stopgm, its fatal-error routine, inside the call. With opencpmd_stopgm_return.patch in the archive, stopgm calls cpmd_stopgm_hook. While an evaluation is armed the catch records the stop code and returns 1, so stopgm returns to its caller, and cpmdc returns ok == 0 instead of ending the host. CPMD writes its reason to a LocalError-*.log file in the working directory of that moment. That is permanentDir, or scratchDir when no permanent directory is set, or the host working directory.

Fix: read the LocalError file in that directory. The wavefunction, forces, and module state of that call are undefined. cpmdc drops the stored orbitals and the warm cell, and the next call on the same session sets CPMD up again. With more than one MPI rank, cpmdc aborts the other ranks, which would otherwise stay blocked in the call stopgm returned from.

topology change requires a new session

Cause: the first successful step of a session fixes the atom count and the elemental composition. A later step with a different count or composition is refused before CPMD runs. A reordering of the same elements stays on the session.

Fix: create a new CPMDCSession for a different composition. A reordering of the same elements keeps the stored orbitals. A different elemental composition runs setup.

PotentialResult buffer too small

Cause: the output buffer is smaller than the serialized result. cpmdc writes the required size to the size argument and does not evaluate.

Fix: allocate cpmdc_potential_result_size_for_force_input() bytes.

CPMD embed not available

Cause: the library was finalized with cpmdc_finalize(), or the session could not apply its configuration.

Fix: call cpmdc_finalize() only at shutdown; check the message with CPMDC_DECK_OUT for a rendering failure.

Forces

Forces are all zero with a finite energy

Cause: the OpenCPMD archive lacks opencpmd_embed_rwfopt.patch, so fion is deallocated before cpmdc reads it.

Fix: apply the patches in tools/ and rebuild the archive (see building the archive). A symmetric cluster at a stationary geometry also gives zero forces; displace an atom to tell the two apart.

Ranks disagree about forces under mpirun

Cause: only CPMD’s parent rank holds the calculator’s forces.

Fix: broadcast the parent rank’s result (see running under mpirun).

mpirun reports an abnormal termination at exit

Cause: CPMD initialised MPI and nothing finalized it; Open MPI 5 kills the ranks still running when one exits without MPI_Finalize.

Fix: call MPI_Finalize on every rank before exit.

Report a new problem

Open an issue on the GitHub issue tracker when no entry above matches. Questions go there too.

Print the version and the build options that choose the code path. Replace build with your build directory, then run this command in the source tree.

meson introspect build --projectinfo --buildoptions | python3 -c '
import json, sys
info = json.load(sys.stdin)
print("cpmdc", info["projectinfo"]["version"])
for option in info["buildoptions"]:
    if option["name"] in ("with_cpmd", "cpmd_root", "with_readcon"):
        print(option["name"], "=", repr(option["value"]))
'

The default build prints:

cpmdc 0.4.0
with_cpmd = False
cpmd_root = ''
with_readcon = False

Put these items in the report:

  1. the output of that command;

  2. the deck that CPMDC_DECK_OUT wrote for the failing call (see debugging a deck);

  3. CPMDCResult.message or cpmdc_last_error() for a failed call, or the --print-errorlogs output for a failed test;

  4. the LocalError-*.log file, when the call stopped with CPMD stopgm during embed SCF.