httk.io.vasp

VASP file-format readers for httk-io.

Submodules

• httk.io.vasp.oszicar
• httk.io.vasp.outcar
• httk.io.vasp.outputs
• httk.io.vasp.poscar_reader
• httk.io.vasp.poscar_writer
• httk.io.vasp.potcar
• httk.io.vasp.volumetric
• httk.io.vasp.wavecar
• httk.io.vasp.xdatcar

Classes

ElasticModuliBlock	Store one six-by-six elastic-moduli table.
OutcarFile	Lazy OUTCAR metadata reader whose scans reopen the source each time.
OutcarFrame	Store one complete ionic-step snapshot with VASP numeric lexemes unchanged.
VASPOutputs	Lazily resolve standard VASP files in a calculation directory.
XdatcarFile	Re-openable, forward-streaming XDATCAR source.

Functions

read_oszicar(source)	Read OSZICAR text without converting numeric lexemes.
read_outcar(source)	Return a lazy OUTCAR payload; only filesystem filenames are accepted.
read_poscar(source)	Parse a VASP POSCAR/CONTCAR into a neutral, string-preserving mapping.
read_potcar_summary(source)	Extract one metadata mapping per TITEL header without retaining POTCAR text.
read_xdatcar(source)	Read an XDATCAR path into a lazy neutral vasp-xdatcar payload.
read_wavecar(source, *[, double_precision, gamma_half])	Read a VASP WAVECAR path into a neutral payload.
write_wavecar(destination, payload)	Write a neutral WAVECAR payload to a binary path.
write_vasp_volumetric(destination, poscar_payload, grid, *)	Write POSCAR content followed by a VASP/VESTA volumetric grid.

Package Contents

httk.io.vasp.read_oszicar(source)

Read OSZICAR text without converting numeric lexemes.

Electronic iterations are attached to the following ionic summary. A trailing electronic block is retained as an incomplete final entry when no summary follows it.

Parameters:

source (Any) – OSZICAR filename, text stream, or iterable of source lines.

Returns:

A neutral payload containing ionic steps and parsing issues.

Return type:

dict[str, Any]

class httk.io.vasp.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.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.

class httk.io.vasp.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

httk.io.vasp.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]

class httk.io.vasp.VASPOutputs(directory)

Lazily resolve standard VASP files in a calculation directory.

File lookup probes each registered compression suffix after the plain filename. Payload readers are created only when their properties are first accessed. The lazy OUTCAR and XDATCAR children are owned here and closed by close(); payload mappings do not retain open handles.

Parameters:

directory (str | os.PathLike[str]) – Filesystem directory containing VASP output files.

property closed: bool

Whether this directory view has been closed.

close()

Close owned lazy file objects; repeated calls are harmless.

property poscar: dict[str, Any] | None

Return the lazily loaded POSCAR payload, or None when absent.

property contcar: dict[str, Any] | None

Return the lazily loaded CONTCAR payload, or None when absent.

property outcar: httk.io.vasp.outcar.OutcarFile | None

Return the owned lazy OUTCAR reader, or None when absent.

property xdatcar: httk.io.vasp.xdatcar.XdatcarFile | None

Return the owned lazy XDATCAR reader, or None when absent.

property oszicar: dict[str, Any] | None

Return the lazily loaded OSZICAR payload, or None when absent.

property potcar: dict[str, Any] | None

Return the lazily loaded POTCAR summary, or None when absent.

httk.io.vasp.read_poscar(source)

Parse a VASP POSCAR/CONTCAR into a neutral, string-preserving mapping.

source may be a filename, opened through httk.core.TextstreamFileView so compressed files such as CONTCAR.bz2 are decompressed transparently, or an already-open text stream / iterable of lines.

The returned mapping has the keys format (always "vasp-poscar"), comment, scale and volume (both keys are always present; exactly one is non-None), cell, symbols (which may be None for VASP-4; any species token shaped [A-Z][a-z]? followed by _, / or . is truncated to that leading symbol, so Li_sv, O_h and Lu/ read as Li, O and Lu; every other token, including vacancy, is left untouched), counts, cartesian, coords, and selective_dynamics (which may be None when selective dynamics is not declared), and raw (the original decompressed text, or None when unavailable). For filenames and binary sources, raw preserves CRLF and provides the writer’s byte-exact round-trip channel. For an open text stream, it reflects the stream’s already translated text and is not byte-exact. Malformed input raises a clear ValueError naming the offending line.

Three further keys report how precisely the file wrote its numbers, each the coarsest claim among the tokens it covers, or None when none of them claim anything: cell_precision, scale_precision, and coordinate_precision. They are the precisions of the tokens as written, deliberately not converted: the cell vectors are still to be multiplied by the scaling factor, and the coordinates may be Cartesian or fractional depending on cartesian. Doing that conversion needs the assembled cell, so it belongs to whoever builds the structure — httk.core.load() — not to the reader.

Parameters:

source (Any) – POSCAR/CONTCAR filename, text stream, or iterable of source lines.

Returns:

The neutral mapping, including the original text in raw when available.

Raises:

ValueError – If the input is malformed.

Return type:

dict[str, Any]

httk.io.vasp.read_potcar_summary(source)

Extract one metadata mapping per TITEL header without retaining POTCAR text.

Only header metadata is returned; the potential body is never retained or exposed because it can contain licensed data. Concatenated POTCAR.summary headers are accepted.

Parameters:

source (Any) – POTCAR or POTCAR.summary filename, text stream, or iterable of source lines.

Returns:

A neutral payload containing one metadata mapping per potential.

Return type:

dict[str, Any]

class httk.io.vasp.XdatcarFile(filename)

Re-openable, forward-streaming XDATCAR source.

Construction checks only that filename exists. Compressed paths are accepted by deliberate forward-streaming divergence from WavecarFile; repeated scans re-stream the file. Header properties scan the header; frames opens a fresh stream and never caches frames. Variable-cell files are identified by a repeated POSCAR-like header and expose that header’s cell on the following frame. An incomplete final coordinate block is dropped and reported in issues during the full pass. The public path property returns the source filename.

Parameters:

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

property path: str

Return the source filename used to construct this lazy reader.

property closed: bool

Whether this lazy reader has been closed.

close()

Close the object; scans use short-lived streams and own no handle.

property comment: str

Return the source comment line.

property scale: str

Return the source scaling-factor lexeme.

property cell: tuple[tuple[str, str, str], Ellipsis]

Return the initial cell-vector lexemes.

property symbols: tuple[str, Ellipsis] | None

Return initial species symbols, or None for the older header form.

property counts: tuple[int, Ellipsis]

Return the number of sites for each initial species entry.

property cartesian: bool

Whether the first configuration uses Cartesian coordinates.

property issues: tuple[str, Ellipsis]

Return issues collected while scanning all frames.

frames()

Yield complete frames in file order without retaining them.

Yield:

One complete frame mapping at a time.

property nframes: int

Return the number of complete frames after a full scan.

httk.io.vasp.read_xdatcar(source)

Read an XDATCAR path into a lazy neutral vasp-xdatcar payload.

Parameters:

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

Returns:

A neutral payload containing the lazy XDATCAR reader.

Raises:

• TypeError – If source is not a filesystem path.

• FileNotFoundError – If the path does not exist.

Return type:

dict[str, Any]

httk.io.vasp.read_wavecar(source, *, double_precision=None, gamma_half=None)

Read a VASP WAVECAR path into a neutral payload.

Parameters:

• source (str | os.PathLike[str]) – Filesystem path to an uncompressed WAVECAR.

• double_precision (bool | None) – Override the coefficient precision declared by the file.

• gamma_half (str | None) – Consumer hint for the gamma-half orientation, or None when unspecified.

Returns:

A payload containing the lazy WAVECAR source and the gamma-half hint.

Raises:

ValueError – If an option is invalid or the file is malformed.

Return type:

dict[str, Any]

httk.io.vasp.write_wavecar(destination, payload)

Write a neutral WAVECAR payload to a binary path.

Parameters:

• destination (str | os.PathLike[str]) – Filesystem path for the uncompressed binary output.

• payload (collections.abc.Mapping[str, Any]) – Neutral payload containing a WAVECAR source.

Raises:

• ValueError – If the destination or payload cannot represent a WAVECAR.

• TypeError – If the payload is not a mapping.

• KeyError – If the payload mapping does not contain "wavecar".

httk.io.vasp.write_vasp_volumetric(destination, poscar_payload, grid, *, cols=10)

Write POSCAR content followed by a VASP/VESTA volumetric grid.

Parameters:

• destination (str | os.PathLike[str] | io.TextIOBase) – Filesystem path or open text stream for the output.

• poscar_payload (collections.abc.Mapping[str, Any]) – Neutral POSCAR payload supplying the structure header.

• grid (Any) – Three-dimensional real-valued grid in the order written by the format.

• cols (int) – Maximum number of values written on each grid line.

Raises:

ValueError – If the grid or column count is not writable as volumetric data.