httk.atomistic.vasp_structures
==============================

.. py:module:: httk.atomistic.vasp_structures

.. autoapi-nested-parse::

   Build an exact :class:`~httk.atomistic.Structure` from a neutral POSCAR mapping.

   :func:`structure_from_poscar` consumes the plain, string-preserving mapping
   produced by ``httk.io.read_poscar`` (format tag ``"vasp-poscar"``) and turns it
   into an exact :class:`~httk.atomistic.Structure`. It imports nothing from
   *httk-io* — it only understands the neutral mapping shape — keeping the parsing
   capability (*httk-io*) and the domain model (*httk-atomistic*) decoupled.

   :func:`load_structure` is the convenience end-to-end entry point:
   ``httk.core.load`` picks the reader by file type, and a small adapter table maps
   the payload's ``"format"`` tag to the matching structure builder.



Functions
---------

.. autoapisummary::

   httk.atomistic.vasp_structures.structure_from_poscar
   httk.atomistic.vasp_structures.load_structure


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

.. py:function:: structure_from_poscar(data: collections.abc.Mapping[str, Any]) -> httk.atomistic.structure.Structure

   Build an exact :class:`~httk.atomistic.Structure` from a neutral POSCAR mapping.

   ``data`` is the mapping returned by ``httk.io.read_poscar`` (its ``format``
   must be ``"vasp-poscar"``). The cell basis is taken exactly from the file's
   string rows. For a positive universal scaling factor the ``scale`` string is
   used directly as the cell's exact scale; for a negative scaling factor (a
   target **volume** ``V``) the scale is the cube root of ``V / |det(basis)|`` —
   a value outside the exact surd field, so it is a deterministic rational
   approximation (the basis rows themselves stay exact).

   Direct coordinates become reduced coordinates directly (exact strings).
   Cartesian coordinates are converted exactly as ``cart * basis.inv()`` under
   the row-vector convention; because VASP scales *both* the lattice vectors and
   the Cartesian positions by the universal scaling factor, that factor cancels
   and the reduced coordinates are exact regardless of the scale/volume case.

   Species come from the VASP-5 species line (one single-element, unattached
   :class:`~httk.atomistic.Species` of concentration 1.0 per distinct symbol);
   a VASP-4 file (no species symbols) raises a :class:`ValueError`. Selective
   dynamics flags, if present, are ignored.


.. py:function:: load_structure(path: str) -> httk.atomistic.structure.Structure

   Load a file and build a :class:`~httk.atomistic.Structure` from it.

   ``httk.core.load(path)`` selects the reader by file type (transparently
   decompressing ``.bz2`` / ``.gz`` files); the payload's ``"format"`` tag then
   selects the matching structure builder. A payload without a recognized
   ``"format"`` tag (for example a CIF, which returns a different shape) raises a
   clear :class:`ValueError`.