pyextal.jaxMultipole.symmetry¶

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¶

`axis_and_order`(R[, tol])	Rotation axis and order of a Cartesian operation's proper part.
`local_frame`(stab_cart[, A, z, x])	Rows of the local frame, as Cartesian unit vectors.
`local_rotations`(stab_cart, frame)	Site operations expressed in the local frame, `F R F^T`.
`point_group_name`(stab_cart)	A short description of a site group: order, axes and inversion.
`allowed_multipoles`(stab_local, lmax[, lmin])	Allowed populations of every order up to `lmax`.
`allowed_adp_basis`(stab_frac, Gstar)	Allowed `U_ij` directions, RREF in `(U11, U22, U33, U12, U13, U23)`.
`orbit`(g, crystal)	`{member: (W, w, conj)}` of g's family, `-g` folded in for centrosymmetric groups.
`canonical`(g, crystal)	The canonical key of g's family: the largest member, as in jaxJoint.
`link_phase`(local, key, crystal)	`(c, conj)` with `U(local) = c * (U(key)* if conj else U(key))`.
`to_key`(value, local, key, crystal)	Maps a value refined under the label `local` to the canonical `key`.

Module Contents¶

pyextal.jaxMultipole.symmetry.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.
Return type:: tuple

pyextal.jaxMultipole.symmetry.local_frame(stab_cart, A=None, z=None, x=None)¶

Rows of the local frame, as Cartesian unit vectors.

Parameters:

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

Returns:

(3, 3) with rows x, y, z; a proper rotation, so that u_local = F @ u_cart.

Return type:

np.ndarray

pyextal.jaxMultipole.symmetry.local_rotations(stab_cart, frame)¶: Site operations expressed in the local frame, F R F^T.

pyextal.jaxMultipole.symmetry.point_group_name(stab_cart)¶: A short description of a site group: order, axes and inversion.

pyextal.jaxMultipole.symmetry.allowed_multipoles(stab_local, lmax, lmin=0)¶

Allowed populations of every order up to lmax.

Returns:: l -> (2l+1, nfree) RREF bases (possibly empty).
Return type:: dict[int, np.ndarray]

pyextal.jaxMultipole.symmetry.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 uij_to_beta_matrix().
Return type:: np.ndarray

pyextal.jaxMultipole.symmetry.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.

pyextal.jaxMultipole.symmetry.canonical(g, crystal)¶: The canonical key of g’s family: the largest member, as in jaxJoint.

pyextal.jaxMultipole.symmetry.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.

pyextal.jaxMultipole.symmetry.to_key(value, local, key, crystal)¶: Maps a value refined under the label local to the canonical key.