httk.atomistic.integrations.vasp.io¶

VASP file-format readers for httk-atomistic.

Submodules¶

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, *[, precision])	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.atomistic.integrations.vasp.io.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.atomistic.integrations.vasp.io.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.atomistic.integrations.vasp.io.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.atomistic.integrations.vasp.io.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.atomistic.integrations.vasp.io.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.atomistic.integrations.vasp.io.VASPOutputs(directory, *, precision=None)¶

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.
precision (float | None) – Cartesian coordinate precision in Å propagated to the POSCAR/CONTCAR reads (see read_poscar()). None (the default) keeps the digit-derived precision and, on first poscar/contcar access, emits the same recommendation warning read_poscar does — relaxed CONTCAR coordinates are written to full double precision, so without a value the symmetry tolerance comes out unrealistically tight. Validated lazily by the reader.

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.

The read uses this object’s precision (warning when it was not supplied).

property contcar: dict[str, Any] | None¶

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

The read uses this object’s precision (warning when it was not supplied).

property outcar: httk.atomistic.integrations.vasp.io.outcar.OutcarFile | None¶

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

property xdatcar: httk.atomistic.integrations.vasp.io.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.atomistic.integrations.vasp.io.read_poscar(source, *, precision=None)¶

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. In Direct mode, conventional special fractions written exactly as 0.0, 0.5, or 1.0 make no precision claim; signed forms follow the same rule. The cell vectors are still to be multiplied by the scaling factor, and Cartesian coordinates are still to be transformed into the fractional frame. Doing those conversions needs the assembled cell, so it belongs to whoever builds the structure — httk.core.load() — not to the reader.

A further key, precision_override, carries the caller’s precision value (or None). When given, it is the Cartesian coordinate precision as a length in Å — the same units as cartesian_precision() and the symprec used by symmetry recognition — and whoever builds the structure uses it in place of the digit-derived precision. Relaxed VASP CONTCAR coordinates are written to full double precision, so the digit-derived precision is unrealistically tight (~machine epsilon) and yields a symmetry tolerance that makes spglib reject nearly every candidate; pass a realistic value (e.g. 5e-4) for such files. When precision is None a recommendation warning is emitted.

Parameters:

source (Any) – POSCAR/CONTCAR filename, text stream, or iterable of source lines.
precision (float | None) – Cartesian coordinate precision as a length in Å, or None to keep the digit-derived behavior (and emit a recommendation warning). Must be a finite number greater than zero when given.

Returns:

The neutral mapping, including the original text in raw when available, and precision_override (the passed value or None).

Raises:

ValueError – If the input is malformed, or precision is not a finite number greater than zero.

Return type:

dict[str, Any]

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