feat: add vaspcheck-outcar — per-step SCF and ionic convergence checker

[patrickmelix]

Description:

Adds a new standalone module tools4vasp.outcar_convergence and the CLI command vaspcheck-outcar for inspecting VASP OUTCAR files without requiring a full VASP directory or an ASE calculator object. Accepts plain OUTCAR and gzip-compressed OUTCAR.gz files, or a directory containing either.

Checks performed

POTCAR/POSCAR alignment Reads the POTCAR title lines and POSCAR element line echoed in the OUTCAR header and verifies that the element order matches. A mismatch means VASP applied the wrong pseudopotential to each species, silently corrupting all energies and forces. PAW potential suffixes (_pv, _d, _sv, …) are stripped before comparison. Returns None (rather than raising) when the header is absent, e.g. for a truncated file.

Per-step SCF convergence Reports whether each ionic step's SCF cycle reached the required accuracy (reached required accuracy - stopping SCF-cycle) or hit NELM without converging. Returns one bool per ionic step, so unconverged frames can be identified and excluded from training data individually.

Ionic/geometry convergence Checks for reached required accuracy - stopping structural energy minimisation anywhere in the file. Works for geometry optimisations, dimer TS searches, and NEB image relaxations.

Public API

from tools4vasp.outcar_convergence import (
    check_potcar_poscar_alignment,   # alignment only
    check_scf_convergence_per_step,  # List[bool], one per ionic step
    check_ionic_convergence,         # bool
    check_outcar,                    # all checks in one dict
    run,                             # check_outcar + human-readable stdout
)

check_outcar(path) returns:

key | type | meaning -- | -- | -- outcar_path | str | resolved file path used potcar_aligned | bool\|None | True=OK, False=mismatch, None=header absent potcar_message | str | "OK" or mismatch/error detail poscar_elements | List[str] | elements from POSCAR line potcar_elements | List[str] | elements from POTCAR lines n_steps | int | number of ionic steps found scf_converged | List[bool] | per-step SCF flags n_scf_failed | int | count of SCF-failed steps ionic_converged | bool | geometry/TS/NEB convergence

CLI

vaspcheck-outcar                      # OUTCAR in current directory
vaspcheck-outcar path/to/dir          # OUTCAR in given directory
vaspcheck-outcar path/to/OUTCAR       # direct file path
vaspcheck-outcar path/to/OUTCAR.gz    # gzip-compressed OUTCAR

Example output:

OUTCAR      : /path/to/OUTCAR
POTCAR/POSCAR alignment : OK
Ionic steps : 47
SCF         : all steps converged
Ionic       : CONVERGED

Relation to existing vaspcheck

vaspcheck requires a full VASP directory and reads the last step only via ASE. vaspcheck-outcar operates on the raw OUTCAR text and reports every ionic step independently — useful for filtering training data for ML force-field fitting and for checking bare OUTCAR/OUTCAR.gz archives where no other input files are present.

Tests

49 tests across 6 classes, all passing. ruff clean.