httk.atomistic.models.cell.api
==============================

.. py:module:: httk.atomistic.models.cell.api

.. autoapi-nested-parse::

   The minimal canonical cell interface for httk-atomistic.



Classes
-------

.. autoapisummary::

   httk.atomistic.models.cell.api.CellAPI


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

.. py:class:: CellAPI

   Bases: :py:obj:`abc.ABC`


   Abstract base class for the canonical cell interface.

   It declares the exact accessors that every cell backend produces from its own native
   representation and every cell view builds its presentation from: the ``basis`` of 3x3 lattice
   vectors (``scale * unscaled_basis``), the positive ``scale``, and the ``unscaled_basis``. All
   three are exact httk-core vectors; this is the single interchange format, with no pairwise
   conversion between backends.


   .. py:property:: basis
      :type: httk.core.SurdVector

      :abstractmethod:


      Return the scaled lattice vectors.


   .. py:property:: scale
      :type: httk.core.SurdScalar

      :abstractmethod:


      Return the positive factor applied to ``unscaled_basis``.


   .. py:property:: unscaled_basis
      :type: httk.core.SurdVector

      :abstractmethod:


      Return the lattice vectors before applying ``scale``.


   .. py:property:: precision
      :type: fractions.Fraction | None


      How precisely the basis was stated, as an absolute length, or ``None`` if unknown.

      A backend that knows its source's precision overrides this; one that does not — a
      bare matrix of numbers with no provenance — inherits ``None``.

      :return: The absolute basis precision, or ``None`` when it is unknown.


   .. py:property:: periodicity
      :type: tuple[bool, bool, bool]


      Which of the three basis rows is a genuine lattice translation.

      A backend that knows its periodicity overrides this; one that does not inherit
      ``(True, True, True)``. A cell described only by six lattice parameters or a bare
      matrix is interpreted as a fully periodic crystal.

      :return: Flags identifying the periodic basis rows.


   .. py:method:: metric()

      Return the exact Gram matrix of the scaled basis.

      :return: The Gram matrix of the cell vectors.



   .. py:property:: lengths
      :type: tuple[httk.core.SurdScalar, Ellipsis]


      Return exact lengths where representable, with a deterministic rational fallback otherwise.

      :return: The three cell-vector lengths.


   .. py:property:: angles
      :type: tuple[fractions.Fraction, Ellipsis]


      Return ``(alpha, beta, gamma)`` exactly where representable, with a deterministic rational fallback otherwise.

      :return: The crystallographic angles in degrees.


   .. py:property:: volume
      :type: httk.core.SurdScalar


      Return the exact absolute determinant of the basis.

      :return: The cell volume.
      :raises ValueError: If the cell is not periodic in all three directions.