httk.io.vasp.outcar

Lazy, streaming access to the bounded metadata and final results of OUTCAR.

Attributes

vasp_xc_tags

Classes

FinalEnergies	Store energy lexemes from the last complete or partial energy block.
OutcarFrame	Store one complete ionic-step snapshot with VASP numeric lexemes unchanged.
ElasticModuliBlock	Store one six-by-six elastic-moduli table.
OutcarFile	Lazy OUTCAR metadata reader whose scans reopen the source each time.

Functions

read_outcar(source)

Return a lazy OUTCAR payload; only filesystem filenames are accepted.

Module Contents

httk.io.vasp.outcar.vasp_xc_tags

class httk.io.vasp.outcar.FinalEnergies

Store energy lexemes from the last complete or partial energy block.

Parameters:

• free_energy – Free-energy lexeme from the block, when present.

• energy_without_entropy – Energy-without-entropy lexeme, when present.

• energy_sigma0 – Sigma-zero energy lexeme, when present.

• final – Whether the block was complete when parsing ended.

free_energy: str | None

energy_without_entropy: str | None

energy_sigma0: str | None

final: bool

class httk.io.vasp.outcar.OutcarFrame

Store one complete ionic-step snapshot with VASP numeric lexemes unchanged.

Parameters:

• index – Zero-based ionic-step index.

• cell – Lattice-vector lexemes, when the step contains a cell.

• positions – Position lexemes, when the step contains positions.

• forces – Force lexemes, when the step contains forces.

• stress_kbar – Six stress lexemes in VASP order, when present.

• free_energy – Free-energy lexeme, when present.

• energy_without_entropy – Energy-without-entropy lexeme, when present.

• energy_sigma0 – Sigma-zero energy lexeme, when present.

• temperature – Temperature lexeme, when present.

index: int

cell: tuple[tuple[str, str, str], Ellipsis] | None

positions: tuple[tuple[str, str, str], Ellipsis] | None

forces: tuple[tuple[str, str, str], Ellipsis] | None

stress_kbar: tuple[str, Ellipsis] | None

free_energy: str | None

energy_without_entropy: str | None

energy_sigma0: str | None

temperature: str | None

cell_floats()

Convert the cell lexemes to floating-point values when present.

Returns:

Converted cell values, or None when the frame has no cell.

Return type:

tuple[tuple[float, float, float], Ellipsis] | None

positions_floats()

Convert the position lexemes to floating-point values when present.

Returns:

Converted position values, or None when the frame has no positions.

Return type:

tuple[tuple[float, float, float], Ellipsis] | None

forces_floats()

Convert the force lexemes to floating-point values when present.

Returns:

Converted force values, or None when the frame has no forces.

Return type:

tuple[tuple[float, float, float], Ellipsis] | None

stress_gpa_voigt()

Convert stress to tensile-positive GPa Voigt order xx, yy, zz, yz, xz, xy.

The conversion multiplies kbar by 0.1, reverses VASP’s compressive-positive sign, and reorders the shear components.

Returns:

Stress in tensile-positive GPa Voigt order, or None when absent.

Return type:

tuple[float, Ellipsis] | None

class httk.io.vasp.outcar.ElasticModuliBlock

Store one six-by-six elastic-moduli table.

Parameters:

• heading – Heading identifying the table in the source.

• rows – Table rows with their source numeric lexemes.

heading: str

rows: tuple[tuple[str, Ellipsis], Ellipsis]

class httk.io.vasp.outcar.OutcarFile(filename)

Lazy OUTCAR metadata reader whose scans reopen the source each time.

OUTCAR paths, including compressed paths, are accepted by deliberate forward-streaming divergence from WavecarFile; random frame access re-streams the file. Construction validates only that the path exists. Prologue and full scans are lazy: the first prologue access scans to the ionic marker and can traverse the whole file when no marker exists. The full pass streams the source once and caches summary fields, all stress rows, and all elastic-moduli blocks. No source handle is retained, so close() only marks this lazy object closed. The public path property returns the source filename.

Parameters:

filename (str | os.PathLike[str]) – Filesystem path to an OUTCAR, optionally compressed.

property closed: bool

Whether this lazy reader has been closed.

close()

Mark this lazy object closed; it owns no persistent stream.

property path: str

Return the source filename used to construct this lazy reader.

property version_string: str

Return the VASP version string found during the prologue scan.

property version_numbers: tuple[int, Ellipsis]

Return the numeric components of the VASP version string.

property parameters: collections.abc.Mapping[str, str]

Return the first recognized VASP parameter lexeme for each parameter.

property ions_per_type: tuple[int, Ellipsis] | None

Return the number of ions for each potential type, when reported.

property xc: str | None

Return the recognized exchange-correlation description, when available.

property potcar_titles: tuple[str, Ellipsis]

Return distinct POTCAR titles in first-seen order.

frames()

Stream complete ionic frames without retaining the sequence.

Returns:

An iterator yielding one OutcarFrame at a time.

Return type:

collections.abc.Iterator[OutcarFrame]

frame(index)

Return one frame by rescanning from the start of the file.

Parameters:

index (int) – Zero-based frame index.

Returns:

The requested frame, or None when it is beyond the file.

Raises:

ValueError – If index is negative or not an integer.

Return type:

OutcarFrame | None

property final_energies: FinalEnergies

Return energies from the last complete or partial energy block.

property nframes: int

Return the number of complete ionic frames after the full pass.

property last_frame: OutcarFrame | None

Return the last complete ionic frame, when one exists.

stresses()

Return all six-token in kB rows in file order.

Returns:

Stress rows retaining their source numeric lexemes.

Return type:

tuple[tuple[str, Ellipsis], Ellipsis]

property elastic_moduli: tuple[ElasticModuliBlock, Ellipsis]

Return parsed elastic-moduli tables in source order.

property magnetization: tuple[float, Ellipsis] | None

Return per-ion total magnetic moments from the final magnetization (x) block.

The values are the last (tot) column of each ion row in the last magnetization (x) block in the file, in Bohr magnetons. The per-orbital columns and the magnetization (y) / (z) blocks themselves are out of scope, so for a noncollinear run these values are only the x projection of each moment. A caller treating them as a collinear axis projection must check noncollinear_magnetization first. A malformed or truncated final block never raises: it yields None and records an entry in issues, so an OUTCAR from a killed job is ordinary input.

Returns:

The per-ion total moments, or None for a non-spin-polarized run or an unusable final block.

Return type:

tuple[float, Ellipsis] | None

property noncollinear_magnetization: bool

Whether a magnetization (y) or (z) block follows the final (x) block.

When True the magnetization values are only the x projection of a noncollinear moment and must not be treated as a collinear axis magnitude.

Returns:

True for a noncollinear final block, False otherwise, including when the file has no magnetization block.

Return type:

bool

property completed: bool

Whether the source contains completion-footer evidence.

property completion_evidence: tuple[str, Ellipsis]

Return completion-footer lines found during the full pass.

property issues: tuple[str, Ellipsis]

Return parsing issues collected during the available scans.

httk.io.vasp.outcar.read_outcar(source)

Return a lazy OUTCAR payload; only filesystem filenames are accepted.

Parameters:

source (Any) – Filesystem path to an OUTCAR, optionally compressed.

Returns:

A neutral payload containing the lazy OUTCAR reader.

Raises:

• TypeError – If source is not a filesystem path.

• FileNotFoundError – If the path does not exist.

Return type:

dict[str, Any]