httk.atomistic.standardization
==============================

.. py:module:: httk.atomistic.standardization

.. autoapi-nested-parse::

   Express an asymmetric-unit structure in its IT standard-setting cell.

   The operation is exact after any optional recognition step. An ASU already carries the
   standard-setting Wyckoff data and the stored transform from that setting to its own cell,
   so the conventional cell is obtained by transforming the cell basis back and expanding a
   new identity-transform ASU.



Classes
-------

.. autoapisummary::

   httk.atomistic.standardization.ConventionalCellResult


Functions
---------

.. autoapisummary::

   httk.atomistic.standardization.conventional_cell


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

.. py:class:: ConventionalCellResult

   A structure in its space group's IT standard-setting conventional cell.

   ``asu`` is the new standard-setting ASU that was expanded to make ``structure``.
   ``transform`` is the standard-to-own transform from the ASU that was supplied to, or
   recognized from, the operation; its orientation is :math:`f_own = f_std M^T + v`, so
   this operation undoes it for the cell basis. ``multiplier`` is the exact ratio of
   conventional-cell site count to input-cell site count. For the 527 vendored settings
   it is at least one; an untabulated, caller-supplied supercell transform may still
   produce a ratio below one.


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


   .. py:attribute:: asu
      :type:  httk.atomistic.asu_structure.ASUStructure


   .. py:attribute:: spacegroup
      :type:  httk.atomistic.spacegroup.Spacegroup


   .. py:attribute:: transform
      :type:  httk.atomistic.setting_transform.SettingTransform


   .. py:attribute:: multiplier
      :type:  fractions.Fraction


.. py:function:: conventional_cell(structure: httk.atomistic.structure_like.StructureLike | httk.atomistic.asu_structure.ASUStructure, *, tolerance: float | None = None, limit_denominator: int | None = None) -> ConventionalCellResult

   Return ``structure`` in its space group's IT standard-setting conventional cell.

   An existing :class:`~httk.atomistic.ASUStructure` (including an
   :class:`~httk.atomistic.ASUStructureView`, an ASU backend, or a full-cell view backed
   by one) is used exactly as stored. Supplying ``tolerance`` or ``limit_denominator`` for
   that path raises :class:`ValueError`, because those arguments belong to recognition.
   Any other :class:`~httk.atomistic.StructureLike` is first passed to
   :func:`~httk.atomistic.recognize_asu`. That tolerant step may snap measured coordinates
   onto symmetry positions and chooses the transform recorded in the result; it does not
   preserve an unstated input transform or promise a :func:`~httk.atomistic.same_crystal`
   match to noisy input coordinates. The optional tolerance is a Cartesian matching
   distance and the optional denominator limit idealises free parameters.

   The returned ``transform`` is the existing ASU's transform, or the transform chosen by
   recognition for a plain input; the returned ``asu`` has an identity transform.
   Construction and expansion are exact, including the rhombohedral case where the
   standard hexagonal cell contains three primitive cells. Basis precision is multiplied by
   ``M.T()`` and coordinate precision by the maximum absolute column sum of
   ``inv(M.T())``; unknown precision remains unknown. Requires a fully 3D-periodic
   structure.