pyextal.jaxMultipole.symmetry
=============================

.. py:module:: pyextal.jaxMultipole.symmetry

.. autoapi-nested-parse::

   Site symmetry, local frames, allowed parameters and reflection families.

   Local frames
   ------------

   Multipole populations are only comparable between programs -- and only come out
   as single named ``P_lm`` rather than mixtures -- when each atom's frame is chosen
   the way Kurki-Suonio's index-picking rules choose it:

   * cubic site groups (four 3-fold axes): z and x along two of the cube axes (the
     4-fold axes, or the 2-fold ones in 23 / m-3);
   * otherwise z along the highest-order rotation axis (proper or improper), or
     along the mirror normal when a mirror is all there is, and x along a 2-fold
     axis or mirror normal perpendicular to z when one exists;
   * failing that, the crystal's Cartesian axes.

   Ties are broken towards the Cartesian axes, x before y before z, so the choice
   is deterministic. A frame can always be given explicitly instead, as direct
   lattice directions ``z=[u, v, w]``, ``x=[u, v, w]``.

   For the oxygen of SrTiO3 at ``(0, 1/2, 1/2)`` this puts z along ``[100]`` -- the
   Ti-O bond and the 4-fold axis -- and x along ``[010]``.

   Reflection families
   -------------------

   ``U(W^T h) = U(h) exp(-2 pi i h.w)`` for every operation ``(W, w)``, which is
   what maps a dataset's own reflection label onto the canonical key of its family.
   The key is chosen as `jaxJoint.link.canonical` chooses it -- the largest member
   of the orbit, ``-h`` included for centrosymmetric groups -- so keys from a joint
   refinement can be used as they are.



Functions
---------

.. autoapisummary::

   pyextal.jaxMultipole.symmetry.axis_and_order
   pyextal.jaxMultipole.symmetry.local_frame
   pyextal.jaxMultipole.symmetry.local_rotations
   pyextal.jaxMultipole.symmetry.point_group_name
   pyextal.jaxMultipole.symmetry.allowed_multipoles
   pyextal.jaxMultipole.symmetry.allowed_adp_basis
   pyextal.jaxMultipole.symmetry.orbit
   pyextal.jaxMultipole.symmetry.canonical
   pyextal.jaxMultipole.symmetry.link_phase
   pyextal.jaxMultipole.symmetry.to_key


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

.. py:function:: axis_and_order(R, tol=1e-06)

   Rotation axis and order of a Cartesian operation's proper part.

   :returns: ``(axis, n, proper)``. ``axis`` is ``None`` for the identity and
             the inversion; ``n`` is the order of the proper rotation ``+-R``.
   :rtype: tuple


.. py:function:: local_frame(stab_cart, A=None, z=None, x=None)

   Rows of the local frame, as Cartesian unit vectors.

   :param stab_cart: ``(m, 3, 3)`` Cartesian site-symmetry operations.
   :type stab_cart: np.ndarray
   :param A: Lattice matrix, needed only for user axes.
   :type A: np.ndarray, optional
   :param z: Direct-lattice directions ``[u, v, w]``
             overriding the automatic choice. ``x`` is orthogonalised to ``z``.
   :type z: array-like, optional
   :param x: Direct-lattice directions ``[u, v, w]``
             overriding the automatic choice. ``x`` is orthogonalised to ``z``.
   :type x: array-like, optional

   :returns: (3, 3) with rows ``x, y, z``; a proper rotation, so that
             ``u_local = F @ u_cart``.
   :rtype: np.ndarray


.. py:function:: local_rotations(stab_cart, frame)

   Site operations expressed in the local frame, ``F R F^T``.


.. py:function:: point_group_name(stab_cart)

   A short description of a site group: order, axes and inversion.


.. py:function:: allowed_multipoles(stab_local, lmax, lmin=0)

   Allowed populations of every order up to ``lmax``.

   :returns: ``l -> (2l+1, nfree)`` RREF bases (possibly empty).
   :rtype: dict[int, np.ndarray]


.. py:function:: allowed_adp_basis(stab_frac, Gstar)

   Allowed ``U_ij`` directions, RREF in ``(U11, U22, U33, U12, U13, U23)``.

   ``pyextal.adp.allowed_beta_basis`` works on the engine's beta; with
   ``beta_ij = 2 pi^2 a*_i a*_j U_ij`` diagonal in the 6-vector, the same
   subspace in ``U_ij`` coordinates is its rescaling, which RREF then turns
   into named components (``U11`` and ``U22 = U33`` for a 4-fold axis along a).

   :returns: ``(6, nfree)``; ``beta = D @ basis @ coeffs`` with ``D`` from
             :func:`uij_to_beta_matrix`.
   :rtype: np.ndarray


.. py:function:: orbit(g, crystal)

   ``{member: (W, w, conj)}`` of g's family, ``-g`` folded in for centrosymmetric groups.

   Each member is listed with one operation producing it, preferring the
   engine's coset representatives; ``conj`` marks members reached only through
   the inversion-related half, i.e. through ``-g``.


.. py:function:: canonical(g, crystal)

   The canonical key of g's family: the largest member, as in `jaxJoint`.


.. py:function:: link_phase(local, key, crystal)

   ``(c, conj)`` with ``U(local) = c * (U(key)* if conj else U(key))``.

   The same relation `jaxJoint.link.link_map` encodes as a 4 x 4 matrix:
   ``U(W^T g) = U(g) exp(-2 pi i g.w)`` for a coset representative, and for a
   member reached through ``-g`` the Friedel relation ``U(-g) = U(g)*`` first.

   :raises ValueError: If ``local`` is not in ``key``'s family.


.. py:function:: to_key(value, local, key, crystal)

   Maps a value refined under the label ``local`` to the canonical ``key``.