elfes.io.vasp

Read and write the supported VASP charge-data formats.

ELFES reads the uniform real-space density and PAW occupancies from one VASP calculation directory. These are charge-density quantities, not a localized-basis Hamiltonian or wave-function representation. Both reader paths return the same four physical objects:

Geometry
UniformVolumetric          real-space charge and magnetization density
OrbVector                  PAW occupancy
BasisSet                   PAW coupled basis describing the occupancy axis

The PAW coupled basis describes projector-channel pairs after angular-momentum coupling. It is not the underlying PAW projector basis, and the returned PAW occupancy is represented in this coupled basis.

CHGCAR input

read_chgcar(input_dir) treats these files as one source:

input_dir/
├── CHGCAR       final geometry, regular-grid values, and PAW occupancy
├── POTCAR       species and PAW projector channels
└── INCAR        MAGMOM, spin mode, SAXIS, and LSORBIT settings

The CHGCAR may contain one, two, or four components for nonmagnetic, collinear, or noncollinear calculations. ELFES returns these as positive charge density and Cartesian magnetization with 0, 0z, or 0xyz Pauli labels. Noncollinear components are rotated from the VASP SAXIS frame. SOC data are unsupported; no-SOC noncollinear CHGCAR input is accepted only when its VASP-specific imaginary PAW occupancy blocks are negligible.

When MAGMOM is explicit, both readers attach it to Geometry.magmoms in μB. Collinear moments are signed scalars; noncollinear moments are rotated from the SAXIS frame to global Cartesian vectors. ISPIN=1 or absent MAGMOM leaves magmoms unset.

VASP HDF5 input

read_hdf5_charge(input_dir) jointly reads:

input_dir/
├── vaspwave.h5    final structure, charge grid, and real PAW occupancy
└── vaspout.h5     embedded POTCAR and INCAR settings

This path reads the charge structure produced by LCHARGH5=True. It accepts the same one-, two-, and four-component no-SOC cases as the CHGCAR path. The HDF5 output contains only real PAW occupancy arrays, so the reader cannot perform the CHGCAR imaginary-occupancy check.

Both readers divide VASP's raw grid values by the cell volume to obtain values in electron Å\(^{-3}\), reorder grid and coupled-shell axes into ELFES conventions, infer the stored PAW occupancy shell content from POTCAR channels and per-atom value counts, and return real UniformVolumetric and OrbVector objects.

Calculation status

read_run_status(input_dir) reads OUTCAR independently of the charge-data Readers. It reports whether VASP wrote its normal termination section and whether the final electronic loop explicitly reached EDIFF. It does not decide whether a workflow should accept the calculation and does not treat ionic relaxation convergence as electronic convergence.

CHGCAR output

write_chgcar(output_dir, density=density, paw_occupancy=paw_occupancy) writes or replaces output_dir/CHGCAR. It does not use an existing CHGCAR as a template: POSCAR supplies the target geometry, POTCAR supplies species and projector channels, and INCAR supplies LMAXMIX, SAXIS, and LSORBIT. Density and PAW occupancy must describe one matching nonmagnetic, collinear, or no-SOC noncollinear sample. There is no VASP-source HDF5 writer because VASP does not consume this charge HDF5 structure as its restart input.

CHG, PARCHG, LOCPOT, SOC PAW occupancy data, wave functions, and trajectories are outside the current module scope.

VaspRunStatus(normal_termination: bool, final_electronic_converged: bool | None)

read_chgcar(
    input_dir: StrPath,
) -> tuple[Geometry, UniformVolumetric, OrbVector, BasisSet]

write_chgcar(
    output_dir: StrPath, *, density: UniformVolumetric, paw_occupancy: OrbVector
) -> None

read_hdf5_charge(
    input_dir: StrPath,
) -> tuple[Geometry, UniformVolumetric, OrbVector, BasisSet]

read_run_status(calculation: StrPath) -> VaspRunStatus