httk.atomistic.integrations.vasp.io.poscar_reader
=================================================

.. py:module:: httk.atomistic.integrations.vasp.io.poscar_reader

.. autoapi-nested-parse::

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

   :func:`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
----------

.. autoapisummary::

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


Functions
---------

.. autoapisummary::

   httk.atomistic.integrations.vasp.io.poscar_reader.read_poscar


Module Contents
---------------

.. py:data:: logger

.. py:function:: read_poscar(source, *, precision = None)

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

   ``source`` may be a filename, 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`` (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
   :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. 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 —
   :func:`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 :meth:`~httk.atomistic.UnitcellStructure.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.

   :param source: POSCAR/CONTCAR filename, text stream, or iterable of source lines.
   :param precision: 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.
   :return: 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.