8.2 Restart safely and archive provenance
8.2.1 Three different meanings of restart
An electronic density guess, an exact-exchange electronic checkpoint and a molecular-dynamics checkpoint are different objects. Reading yesterday's density can reduce iterations without continuing yesterday's ionic trajectory. Continuing an MD step requires the correct geometry, velocities and integrator state. A successful file read proves neither physical compatibility nor exact numerical continuity.
This unexecuted case uses ABACUS 3.9.0 documented interfaces. Begin with first LCAO silicon, or the independently verified MD parent from NVE energy drift. Keep the original teaching Hamiltonian unchanged for the first experiment. Do not restart into a different functional, species valence, orbital basis, spin representation or cell while calling it a continuation of the same calculation.
Work in copied, identifiable directories. Preserve the original output before making a restart attempt; never let a new suffix and an assumed default path accidentally select unrelated stale files. Output naming is not identity. A folder called “converged” can still contain a failed run or density from another structure.
8.2.2 Physical identity and a continuity test
A reproducible record links files and method to an observable:
For MD, add velocities, masses, timestep, thermostat/barostat variables, step number and random-state policy. A new temperature draw is not the same trajectory even if it begins at the same geometry. Exact bitwise identity can depend on processor decomposition and arithmetic order; scientific reproducibility instead requires an explicit observable tolerance and a documented state.
The trace is an illustrative continuity test, not an executed ABACUS trajectory. Its purpose is to show what to inspect at the join.
8.2.3 Worked electronic-density restart
For a parent that completed SCF, request documented density output before creating the checkpoint:
Preserve that output directory and use a new task with explicit source path:
# ABACUS 3.9.0 electronic guess, not an MD continuation
suffix Si_density_restart
init_chg file
read_file_dir ../parent/OUT.Si_density_parent/
The relative directory assumes the new folder is a sibling of parent; adjust it to your actual layout. init_chg file can prefer the documented binary density if present, otherwise the corresponding cube files. Thus a stale binary file can override a cube you thought you were using. Inventory the selected source directory and confirm the read messages. For the spin-unpolarized parent, the documented cube route uses SPIN1_CHG.cube; a collinear two-channel state needs its second channel too. A spinor state requires the documented complete representation.
This is a new SCF initialized from density. It is not an NSCF fixed-density band task; retain calculation scf from the parent and let the charge relax to the same accepted convergence target. Compare with a fresh atomic-density start. Both should reach the same chosen solution within your tolerance, although metastable magnetic or correlated occupations may require additional branch checks.
8.2.4 Electronic checkpoints and MD checkpoints
For a separate LCAO electronic-checkpoint experiment, 3.9.0 documents restart_save and restart_load, with restart data stored under the configured directory's restart area. Exact-exchange states can involve processor-specific exchange files. Follow the release example and preserve the entire checkpoint rather than selectively copying one density file. Do not assume checkpoint portability across executable versions, solvers or rank counts. A portable density guess and a full internal restart are not interchangeable.
For MD, the conditional delta is applied only to an otherwise unchanged, verified MD parent:
# ABACUS 3.9.0 MD continuation; complete matching checkpoint required
md_restart 1
read_file_dir ./OUT.<existing-suffix>/
<existing-suffix> is an explicit placeholder, not a literal production filename. The documented route reads Restart_md.dat for the step and corresponding STRU_MD_<step> from the expected output structure directory. Preserve the existing suffix and full output tree unless the release example specifies a different supported layout. Check that velocities and thermostat state were emitted and are restored for your integrator; do not invent missing state from a structure snapshot. The manual contains inconsistent spellings in one directory description, so confirm the actual files written by your binary rather than creating a guessed directory to silence an error.
8.2.5 Archive, outputs and validation record
Save INPUT, STRU, KPT, every species file or its immutable acquisition record, model files if present, executable/build identifiers, launcher layout, full logs and selected checkpoint. Compute SHA-256 hashes after the parent finishes. Record a mapping from each hash to its role; a long list without species order or units is insufficient. Keep the original checkpoint read-only and create a separate attempt folder.
| Test | Source checkpoint hash | Version / layout | Read state confirmed? | SCF residual / termination | Final energy (eV) | MD boundary continuity | Decision |
|---|---|---|---|---|---|---|---|
| fresh SCF | none | not applicable | |||||
| density-start SCF | same | not applicable | |||||
| uninterrupted short MD | none | same | reference | ||||
| segmented short MD | same | compare join |
For MD, compare coordinates, velocities, total energy and temperature at the restart boundary and subsequent short segment. A first-step jump may indicate reinitialization or missing integrator state; a long-time chaotic trajectory divergence does not alone imply a faulty restart. Validate continuity locally before interpreting trajectory statistics. For density restarts, inspect iteration histories and the selected final branch rather than demanding identical iteration counts.
8.2.6 Pitfalls, exercises and answers
Pitfalls. Renaming a suffix changes default lookup paths. Copying only a cube ignores binary-file precedence and correlated occupations. Reusing a checkpoint after changing atom order can assign state to the wrong sites. Recreating velocities turns continuation into a fresh ensemble draw. Deleting old files before validation destroys the evidence needed to diagnose a failed restart. A git commit alone does not capture external pseudopotentials, executable libraries or neural models.
Exercise 1. A density-start run reaches the same energy in fewer iterations. Has the MD trajectory continued? Answer: no; only electronic initialization was demonstrated. MD continuation requires its additional dynamical checkpoint.
Exercise 2. A segmented MD run has a temperature jump exactly at the join. What should you check first? Answer: the restored velocities, masses, step/timestep and thermostat state, plus the actual checkpoint read messages. Do not immediately attribute the jump to a physical transition.
8.2.7 Sources
- ABACUS 3.9.0 initialization and restart keywords.
- ABACUS 3.9.0 MD guide.
- Versioned ABACUS source archive.
Next: DeePKS inference.