httk.io.vasp.poscar_reader

A string-preserving reader for VASP POSCAR/CONTCAR files.

read_poscar() parses a POSCAR/CONTCAR file into a neutral, JSON-able mapping whose numeric fields are kept as the verbatim strings found in the file. It performs no numeric conversion and imports nothing from httk-atomistic; turning the mapping into a UnitcellStructure is the job of httk.core.load.

Functions

read_poscar(source)

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

Module Contents

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