httk.atomistic.structure_comparison
===================================

.. py:module:: httk.atomistic.structure_comparison

.. autoapi-nested-parse::

   Comparing structures as crystals rather than as lists of atoms.

   ``Structure.__eq__`` compares the site list element by element, which is the right default
   for a data object but is stricter than crystallographic identity: the same crystal written
   with its atoms in a different order, or with a site represented by a different lattice
   translate, is a different ``Structure`` and the same crystal.

   That distinction matters for the asymmetric-unit round trip.
   ``Structure -> ASUStructure -> Structure`` reproduces the crystal exactly — the coordinates
   are exact rationals throughout, with no numerical drift — but site ordering and the choice
   of lattice representative follow the canonical expansion order rather than the original
   input. :func:`same_crystal` is the predicate that guarantee is stated in.



Functions
---------

.. autoapisummary::

   httk.atomistic.structure_comparison.same_crystal


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

.. py:function:: same_crystal(first: httk.atomistic.structure_like.StructureLike, second: httk.atomistic.structure_like.StructureLike) -> bool

   Whether two structures describe the same crystal.

   True when they have the same cell and the same *multiset* of occupied sites, comparing
   each site by its species and its reduced coordinate wrapped into ``[0, 1)``. Site order
   is ignored, and so is which lattice translate of a site was written down.

   The comparison is exact, not approximate: reduced coordinates are exact rationals and
   cell bases are exact, so two structures that differ by any amount at all compare
   unequal. There is deliberately no tolerance parameter — a tolerant comparison belongs
   with the recognition step that snaps a measured structure onto an idealised one, not
   here.

   Periodicity takes part in two ways. Cells must agree on it, so a slab is never the same
   crystal as the bulk with the same lattice vectors. And only the periodic directions are
   wrapped, since along the others there is no lattice translate to be indifferent about —
   an atom at ``1.05`` really is somewhere else than one at ``0.05``. The comparison stays
   exact in the frame as written: two descriptions of the same slab that differ in their
   non-periodic frame vector compare unequal, because reconciling them would need an origin
   convention this function deliberately does not have.

   Accepts anything structure-like on either side, so a
   :class:`~httk.atomistic.Structure` may be compared directly against an
   :class:`~httk.atomistic.ASUStructure` without expanding it by hand.