8.5 Debugging, restarts and reproducibility
The inputs on this page are educational templates that have not been executed for this course. Use an authorized installation, verify version-specific options and establish your own convergence.
8.5.1 Diagnose the first meaningful failure
For parsing, check names, / terminators, plain quotes, card counts, nonempty files and working directory. Reduce to the smallest failing example rather than adding options. For missing UPF, compare filename byte-for-byte, labels, content and provenance; choose compatible functionals rather than hiding inconsistency.
For SCF oscillation first check geometry, units, contacts, electron count and spin, then occupations/mixing. A smaller mixing step may help but cannot fix wrong physics; more iterations only help healthy slow progress. For I/O failures inspect permissions, space, quota, filesystem and concurrent writers. Two independent jobs must not share prefix/outdir; preserve diagnostic/restart data before cleanup. Official troubleshooting.
8.5.2 HPC has distinct layers
Scheduler allocates resources, launcher starts ranks and QE distributes work over supported levels. Use site sample batch scripts with deliberate resource, path and time changes; neither mpirun nor srun is universally correct. Benchmark supported rank/pool layouts on representative systems without changing scientific settings, retaining actual command and core-hours. Parallelization levels.
8.5.3 New stage versus interrupted restart
Use restart_mode='from_scratch' for a new SCF, parameter test or SCF→bands/NSCF stage. Saved potential is read by the normal bands/NSCF workflow; this is not interrupted-job recovery. Use restart_mode='restart' only with valid restart data and documented conditions. The consulted reference requires same processor count/parallelization and a clean stop; check release, storage and mode before relying on portability. Scheduler kills and corrupted scratch do not guarantee recovery. Restart controls.
For planned wall time use max_seconds in CONTROL sufficiently before the allocation ends to allow output/staging; the margin depends on machine/calculation. The documented exit-file mechanism uses prefix.EXIT in outdir: this example is tmp/si.EXIT. Check names/location and remove stale requests before later continuation where appropriate. Never destroy your only saved calculation to practice recovery.
8.5.4 Reproducibility bundle
Preserve complete inputs/final geometry and units; original UPF names, source/version/hash, XC/valence and licenses; QE build/executable/compiler/MPI/library or container; full stdout/stderr and scheduler outcome; convergence values and acceptance rule; density-to-bands/DOS dependency graph; plotting scripts, reference, normalization, path basis and manual operations. State finite sampling, functional/geometry limitations and untested physics. Saved logs are more informative than a screenshot or isolated energy line.
8.5.5 Exercise and completion
In a disposable copy, intentionally use a wrong UPF filename, capture the first relevant error, correct it and preserve both logs. Draft a restart plan with saved-state location, clean-stop method and retained parallel layout. By completion you should explain model/units/UPF, distinguish electronic/basis/k/geometry convergence, reproduce choices from provenance, avoid path DOS, record energy reference and separate calculated results from templates.
Further teaching: PARADIM, CBPF SCF, Materials Cloud advanced workshop, installation troubleshooting. Workshop numbers belong to their own cells and UPFs, not these unexecuted inputs.