httk.io.vasp
============

.. py:module:: httk.io.vasp

.. autoapi-nested-parse::

   VASP file-format readers for *httk-io*.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /reference/autoapi/httk/io/vasp/poscar_reader/index


Functions
---------

.. autoapisummary::

   httk.io.vasp.read_poscar


Package Contents
----------------

.. py:function:: read_poscar(source: Any) -> dict[str, Any]

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

   ``source`` may be a filename (``str`` or :class:`os.PathLike`, opened through
   :class:`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`` (exactly one is a string, the other
   ``None``), ``cell`` (a 3x3 list of coordinate strings), ``symbols``
   (``list[str]`` for VASP-5, ``None`` for VASP-4), ``counts`` (``list[int]``),
   ``cartesian`` (``bool``), ``coords`` (an ``N``x3 list of strings), and
   ``selective_dynamics`` (an ``N``x3 list of booleans when the file declares
   selective dynamics, else ``None``). Malformed input raises a clear
   :class:`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 —
   :func:`httk.atomistic.structure_from_poscar` — not to the reader.