httk.atomistic.cell
===================

.. py:module:: httk.atomistic.cell

.. autoapi-nested-parse::

   The Cell class for httk-atomistic.



Classes
-------

.. autoapisummary::

   httk.atomistic.cell.Cell


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

.. py:class:: Cell(basis: httk.core.VectorLike, scale: Any = 1)

   A crystallographic cell: its basis, the 3x3 matrix of cell vectors, held **exactly**.

   The lattice vectors are the rows of ``basis``. Internally a Cell factors that basis into a
   positive :class:`~httk.core.SurdScalar` ``scale`` times an ``unscaled_basis``
   (a :class:`~httk.core.SurdVector` of shape ``(3, 3)``), with ``basis == scale * unscaled_basis``.
   The split lets an overall length factor be carried symbolically: a hexagonal cell of lattice
   parameter ``a`` and ratio ``c/a`` is the exact ``unscaled`` rows ``(1, 0, 0)``,
   ``(-1/2, sqrt(3)/2, 0)``, ``(0, 0, c/a)`` scaled by ``a`` — so the ``sqrt(3)`` stays exact
   regardless of ``a``. A cell built from an absolute basis simply has ``scale == 1``.

   Numbers embed exactly: rationals (and rational-valued floats) stay rational, and a
   :class:`~httk.core.SurdVector` basis keeps its radicals. Derived quantities are exact whenever
   the geometry is metric-rational (the crystallographic case): ``lengths`` come from
   :meth:`~httk.core.SurdVector.sqrt_of` of the rational squared row lengths, ``angles`` (degrees)
   from the exact reverse-Niven :meth:`~httk.core.SurdScalar.acos_degrees` where possible,
   ``volume`` from the exact determinant, and ``metric`` is the exact rational Gram matrix. When a
   squared length happens to be irrational, ``lengths``/``angles`` fall back to a deterministic
   rational approximation (documented per accessor). Exact accessors return vector objects —
   render them with ``.to_floats()`` (nested plain-float lists, numpy-free), ``float(...)`` on
   scalars, :meth:`numeric` (true numpy arrays), or a view of your choice.


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


      The overall (strictly positive) length factor, as an exact ``SurdScalar``.


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


      The 3x3 cell vectors before applying ``scale``, as an exact ``SurdVector``.


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


      The 3x3 lattice vectors ``scale * unscaled_basis`` (one vector per row), exact.


   .. py:method:: numeric() -> httk.atomistic.numeric_cell.NumericCell

      A plain-numpy presentation of this cell (requires the ``httk-atomistic[numpy]`` extra).



   .. py:method:: metric() -> httk.core.SurdVector

      The exact Gram matrix ``matrix * matrix^T`` (rational for a metric-rational cell).



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


      The lengths of the three cell vectors (the scaled row norms).

      Exact via :meth:`~httk.core.SurdVector.sqrt_of` whenever the row's squared length is
      rational (the crystallographic case); otherwise a deterministic rational-approximation
      ``SurdScalar`` at ``_FALLBACK_PREC`` (the length would be a nested radical, outside the
      surd field).


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


      The cell angles ``(alpha, beta, gamma)`` in degrees, as exact ``Fraction`` values.

      Following the crystallographic convention, ``alpha`` is the angle between rows ``b`` and
      ``c``, ``beta`` between ``a`` and ``c``, and ``gamma`` between ``a`` and ``b``. Angles are
      scale-independent, so they are computed from the unscaled basis. The cosine is formed
      exactly in the surd field and reversed through the Niven table
      (:meth:`~httk.core.SurdScalar.acos_degrees`) for an exact answer; a non-Niven angle falls
      back to a deterministic :func:`~httk.core.vectors.exactmath.acos` at ``_FALLBACK_PREC``.


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


      The cell volume, the exact absolute determinant of ``basis``.