httk-io¶

This site documents specifically the httk-io module. For the full documentation of httk₂ as a whole, see docs.httk.org.

httk-io is a httk₂ module providing file input/output under the namespace httk.io, plus the registry package httk.registry.io.io that registers its readers with httk-core. It currently ships a CIF/mCIF parser, reader and writer stack; string-preserving VASP POSCAR/CONTCAR readers plus the OUTCAR/XDATCAR/OSZICAR/POTCAR output readers; a numpy-backed WAVECAR reader/writer and volumetric-grid writer; and the OPTIMADE trajectory JSON Lines holding format.

Quick links

API reference: Reference
Reading POSCAR/CONTCAR files: Reading VASP POSCAR / CONTCAR files
Reading VASP output files: Reading VASP output files
Reading and writing WAVECAR files: Reading and writing VASP WAVECAR files
Trajectory JSON Lines: OPTIMADE trajectory JSON Lines
Runnable examples: Examples

Install¶

Preferably work in a Python virtual environment, then do:

git clone https://github.com/httk/httk-io
cd httk-io
python -m pip install -e .

Usage example¶

Importing httk.core discovers httk.registry.io.io and registers the .cif loader, so httk.core.load can dispatch a CIF file to httk-io. The loader returns a neutral parsed CIF payload when called with raw=True:

import httk.core  # discovery registers the ".cif" loader

payload = httk.core.load("structure.cif", raw=True)
block = payload["blocks"][0]           # one neutral asymmetric-unit mapping per structural block
print(payload["header"])               # the file's leading comment lines
print(block["symbols"])                # e.g. ["Na", "Cl"]
print(block["cell_parameters_exact"])  # ("a", "b", "c", "alpha", "beta", "gamma") as verbatim tokens

CIF loading¶

The neutral CIF payload is a mapping with format "cif" ("mcif" for magnetic CIFs), a blocks list holding one asymmetric-unit mapping per structural block, unparsed reasons for blocks that have atom sites but cannot be interpreted, and the verbatim header. Numeric values are kept as strings; where the file carries _httk_*_exact companion tags those exact tokens are preferred, so no precision is lost at the I/O layer. .cif, .mcif and their compressed forms (.cif.gz, .cif.bz2) all dispatch here.

Two conveniences smooth over real-world files:

Inferred element symbols. _atom_site_type_symbol is optional in the CIF core dictionary. When it is absent, each site’s element is inferred from the leading element run of its _atom_site_label ("MgM1" → Mg), with a RuntimeWarning. A label whose prefix names no element is not guessed at: its block cannot be interpreted, so load omits it from blocks and records the reason in unparsed (the underlying parser raises a ValueError that the loader catches per block).
Autocorrect. Passing autocorrect=True to load (or to read_cif / read_cif_asus) drops a malformed auxiliary loop — one whose column counts do not line up and whose tags are not a protected structural family — warning about each repair instead of refusing the file, and stamps autocorrect=True on the payload. Without it, such a loop is a hard ValueError.

The runnable Reading, inspecting and writing CIF files walks the lower-level read_cif, parse_cif_float / parse_cif_int and write_cif API in full.