httk.io

Public file readers for httk-io.

Submodules

Functions

read_cif(source[, pragmatic, allow_cif2, autocorrect, ...])

Read CIF text as (data_blocks, header).

read_poscar(source)

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

Package Contents

httk.io.read_cif(source, pragmatic=True, allow_cif2=False, *, autocorrect=False, structural_only=False)[source]

Read CIF text as (data_blocks, header).

Paths are opened through httk.core.TextstreamFileView, including compressed CIF files. Open streams and iterables are consumed but left open.

Parameters:

  • source (str | os.PathLike[str] | collections.abc.Iterable[str]) – A filename, open text stream, or iterable of CIF lines.

  • pragmatic (bool) – Accept selected common deviations from strict CIF tokenization.

  • allow_cif2 (bool) – Parse CIF2 list values in addition to CIF1 data.

  • autocorrect (bool) – Drop malformed auxiliary loops and warn about each repair.

  • structural_only (bool) – Retain only tags consumed by httk’s structural adapters and skip auxiliary CIF1 loops.

Returns:

The data blocks and the leading comment header.

Raises:

ValueError – If a loop contains mismatched column value counts.

Return type:

tuple[list[tuple[str, dict[str, Any]]], str]

httk.io.read_poscar(source)[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]