pyextal.jaxJoint.link
=====================

.. py:module:: pyextal.jaxJoint.link

.. autoapi-nested-parse::

   Which structure factor is which, across datasets.

   The engine names each refined structure factor by a representative it picks
   from the dataset's own beam list: under ``SpaceGroup`` the first member of the
   symmetry group it meets (`GroupSymmetry.uniqueBeams`), under ``Friedel``
   whichever of g and -g comes first. Two datasets -- another zone axis, or just a
   different beam list -- can therefore name the same U_g differently, and the
   values under the two names are not equal: a glide or screw translation t makes

       U(R g) = U(g) exp(-2 pi i t.g)

   -- a sign change for a phase of pi, which on La4Ni3O10 (P2_1/a) is a third of
   all equivalent pairs -- and U(-g) = U(g)* for the Friedel mate.

   So every U_g has a **canonical key**, the largest (h, k, l) of its whole orbit,
   which no beam list influences; the shared parameter is U at the canonical key.
   Each dataset's own label ``r`` reaches it through a fixed **link map** ``M``,
   4 x 4 on ``(xfre, xfim, afre, afim)``: ``U_local = M @ U_shared`` -- a rotation
   by the translation phase, preceded by a conjugation when ``r`` lies in the orbit
   of -g. ``M`` is orthogonal, so ``U_shared = M.T @ U_local``.

   `check_links` verifies every map against the engine's own structure factors
   (``defaultsf``) before anything is refined.



Attributes
----------

.. autoapisummary::

   pyextal.jaxJoint.link.CONJ


Functions
---------

.. autoapisummary::

   pyextal.jaxJoint.link.as_hkl
   pyextal.jaxJoint.link.neg
   pyextal.jaxJoint.link.rotation
   pyextal.jaxJoint.link._symmetry_members
   pyextal.jaxJoint.link.is_centro
   pyextal.jaxJoint.link.orbit
   pyextal.jaxJoint.link.canonical
   pyextal.jaxJoint.link.link_map
   pyextal.jaxJoint.link.tabulated
   pyextal.jaxJoint.link.check_links
   pyextal.jaxJoint.link.beam_differences
   pyextal.jaxJoint.link.sort_keys


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

.. py:data:: CONJ

.. py:function:: as_hkl(g)

   Any triple (ints, floats, numpy scalars) -> a tuple of ints.


.. py:function:: neg(g)

.. py:function:: rotation(phi)

   ``M`` multiplying U and U' by ``exp(i phi)``.


.. py:function:: _symmetry_members(g)

   ``[(member, translation)]`` of g's orbit under the engine's operations.


.. py:function:: is_centro()

.. py:function:: orbit(g, symmetry, centro)

   Every reflection sharing g's refined structure factor.

   :param g: A reflection.
   :type g: tuple
   :param symmetry: ``'Friedel'`` -- g and -g only -- or ``'SpaceGroup'`` --
                    the orbit under the space group, with that of -g when the group is
                    centrosymmetric (the engine keeps ops without the inversion and adds
                    it itself, as `GroupSymmetry` does).
   :type symmetry: str
   :param centro: The group is centrosymmetric.
   :type centro: bool

   :returns: set[tuple]


.. py:function:: canonical(g, symmetry, centro)

   The canonical key of g's structure factor: the largest member of its orbit.


.. py:function:: link_map(local, key, symmetry, centro)

   ``M`` with ``U(local) = M @ U(key)``.

   :param local: The dataset's label.
   :type local: tuple
   :param key: The canonical key, in ``local``'s orbit.
   :type key: tuple
   :param symmetry: ``'Friedel'`` or ``'SpaceGroup'``.
   :type symmetry: str
   :param centro: The group is centrosymmetric.
   :type centro: bool

   :returns: (4, 4).
   :rtype: np.ndarray

   :raises SetupError: If ``local`` is not in ``key``'s orbit.


.. py:function:: tabulated(g)

   The engine's ``(xfre, xfim, afre, afim)`` for g, from the crystal structure.


.. py:function:: check_links(links, rtol=0.001, floor=1e-07)

   Verifies each link map against the engine's structure factors.

   For every ``(local, key, M)``, ``M @ U(key)`` must equal ``U(local)`` as
   ``defaultsf`` computes them from the atom positions. This catches a wrong
   sign convention, which would otherwise quietly refine a sum of U_g that
   should be a difference.

   :param links: ``(local, key, M)`` triples; the engine must hold the
                 dataset they belong to.
   :type links: list
   :param rtol: Tolerance, relative to the larger of the two values.
   :type rtol: float
   :param floor: Pairs where both are below this are not tested (the
                 sign of a zero cannot be checked).
   :type floor: float

   :raises SetupError: Naming the pairs that disagree.


.. py:function:: beam_differences(hkl)

   Every g = h_i - h_j of a beam list, (000) excluded: the U_g its matrix holds.


.. py:function:: sort_keys(keys)

   Shortest index first, as the engine orders its reflections.