httk.atomistic.supercell
========================

.. py:module:: httk.atomistic.supercell

.. autoapi-nested-parse::

   Exact supercell construction and deterministic cell-shape search.

   Construction itself is rational/surd-exact. An integer matrix ``A`` maps the old
   row-vector basis ``B`` to ``A * B`` and multiplies the number of sites by
   ``abs(det(A))``. The corresponding finite rational translation group supplies
   every periodic image exactly; no geometric tolerance or open-ended cell search
   is involved.

   Automatic shape selection fixes that multiplier up front. A 50-digit Decimal
   approximation of the exact Gram matrix seeds a bounded set of nearby integer
   matrices, but candidates are ranked by exact, dimensionless Gram-matrix scores.
   The result is therefore the best member of the documented candidate set, not a
   claim of unrestricted global optimality.



Classes
-------

.. autoapisummary::

   httk.atomistic.supercell.SupercellResult


Functions
---------

.. autoapisummary::

   httk.atomistic.supercell.build_supercell
   httk.atomistic.supercell.orthogonal_supercell
   httk.atomistic.supercell.cubic_supercell


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

.. py:class:: SupercellResult

   A materialized supercell together with its exact construction metadata.

   ``orthogonality_score`` is the sum of the squared pairwise cosines between
   cell vectors. ``cubicity_score`` is the squared Frobenius distance between
   the trace-normalized Gram matrix and the identity. Both are exact
   :class:`~httk.core.SurdScalar` values; zero proves the ideal shape exactly.


   .. py:attribute:: structure
      :type:  httk.atomistic.structure.Structure


   .. py:attribute:: transformation
      :type:  httk.core.FracVector


   .. py:attribute:: multiplier
      :type:  int


   .. py:attribute:: orthogonality_score
      :type:  httk.core.SurdScalar


   .. py:attribute:: cubicity_score
      :type:  httk.core.SurdScalar


.. py:function:: build_supercell(structure: httk.atomistic.structure_like.StructureLike, transformation: httk.core.VectorLike, *, max_sites: int | None = DEFAULT_MAX_SITES) -> SupercellResult

   Build the exact supercell selected by an integer transformation matrix.

   Lattice vectors are rows and the returned basis is ``transformation * basis``.
   Reduced coordinates are transformed by the inverse matrix and wrapped into
   ``[0, 1)``. Any input representation is first presented as a full
   :class:`~httk.atomistic.structure.Structure`.

   Requires a fully 3D-periodic structure. Repeating a slab within its own plane is a
   perfectly sensible operation, but it is not this one: the transformation matrix here
   mixes all three rows and the coordinates are wrapped in all three directions, so applied
   to a reduced-periodicity cell it would generate images along a direction that has no
   lattice translation. Refused rather than half-supported.


.. py:function:: orthogonal_supercell(structure: httk.atomistic.structure_like.StructureLike, multiplier: int | None = None, *, tolerance: fractions.Fraction | str | float | None = None, max_multiplier: int | None = None, search_radius: int = 1, max_sites: int | None = DEFAULT_MAX_SITES) -> SupercellResult

   Build the most orthogonal supercell in the bounded candidate set.

   Exactly one of ``multiplier`` and ``tolerance`` must be provided. With
   ``multiplier``, it is the exact number of source cells in the result.
   With ``tolerance``, the multiplier is increased from one until the exact
   orthogonality score is at most the given bound, up to ``max_multiplier``.
   Candidate matrices are centered on the ideal cubic real-valued transform
   and vary each integer entry by at most ``search_radius`` (0--2); diagonal
   factorizations provide guaranteed determinant-matching fallbacks. Exact
   orthogonality is ranked first and cubicity breaks equal-shape ties.


.. py:function:: cubic_supercell(structure: httk.atomistic.structure_like.StructureLike, multiplier: int | None = None, *, tolerance: fractions.Fraction | str | float | None = None, max_multiplier: int | None = None, search_radius: int = 1, max_sites: int | None = DEFAULT_MAX_SITES) -> SupercellResult

   Build the most cubic supercell in the bounded candidate set.

   Exactly one of ``multiplier`` and ``tolerance`` must be provided. With
   ``multiplier``, it is the exact number of source cells in the result.
   With ``tolerance``, the multiplier is increased from one until the exact
   cubicity score is at most the given bound, up to ``max_multiplier``.
   Candidate matrices are centered on the ideal cubic real-valued transform
   and vary each integer entry by at most ``search_radius`` (0--2); diagonal
   factorizations provide guaranteed determinant-matching fallbacks.