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

Attributes

logger

Functions

read_poscar(source, *[, precision])

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

Module Contents

httk.atomistic.integrations.vasp.io.poscar_reader.logger

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