httk.atomistic.setting_transform ================================ .. py:module:: httk.atomistic.setting_transform .. autoapi-nested-parse:: The change of basis between a space-group setting and the IT standard setting. A crystal structure can be written in any setting of its space group — a different choice of axes, a different origin, or something that appears in no table at all. httk represents such a structure by holding its Wyckoff data in the International Tables **standard** setting and carrying a :class:`SettingTransform` that says how to get from there to the setting the structure is actually in. That pairing is what lets an arbitrary, non-tabulated setting be represented losslessly. **Direction.** A :class:`SettingTransform` maps *standard* coordinates into the structure's *own* setting:: f_own = f_std * M.T() + v with the reverse ``f_std = (f_own - v) * inv(M).T()`` and cell basis rows transforming as ``B_own = inv(M).T() * B_std``. Applying it backwards produces a structurally valid but systematically wrong crystal. **Never solve for a transform.** A transform is *stored*, never re-derived by searching for one that maps one group onto another. Such a search is massively underdetermined — for SG 15 alone there are 192 valid pairs with integer entries in ``{-1,0,1}`` and translations on a 1/24 grid, and the true solution set is the full affine-normalizer coset, which is infinite. Two structures with the same group, the same Wyckoff letters and the same free parameters but different transforms are *different crystals*, so picking an arbitrary member of that family would silently produce the wrong structure. Classes ------- .. autoapisummary:: httk.atomistic.setting_transform.SettingTransform Module Contents --------------- .. py:class:: SettingTransform(matrix: Any, vector: Any = (0, 0, 0), *, hall_entry: str | None = None) An exact rational change of basis from the IT standard setting to another setting. Wraps an :class:`~httk.atomistic.AffineOperation` and gives it the standard-to-own reading described in the module docstring, plus the cell-basis and symmetry-operation transformations that follow from it. .. py:method:: identity() -> Self :classmethod: The transform of a structure already in its IT standard setting. .. py:method:: for_hall_entry(hall_entry: str) -> Self :classmethod: The tabulated transform for one of the 527 known settings. ``hall_entry`` is the normalized Hall symbol of the setting, which names it unambiguously — symbol, axes, and origin choice together. .. py:property:: operation :type: httk.atomistic.affine_operation.AffineOperation The underlying affine map, standard to own setting. .. py:property:: matrix :type: httk.core.FracVector The 3x3 rotation part ``M``. .. py:property:: vector :type: httk.core.FracVector The origin shift ``v``. .. py:property:: hall_entry :type: str | None The Hall entry this transform was looked up for, if it came from the tables. .. py:method:: determinant() -> fractions.Fraction ``det M``: the ratio of the own cell's volume to the standard cell's, inverted. ``1`` for 520 of the 527 tabulated settings. The exceptions are the seven rhombohedral-axes settings (IT numbers 146, 148, 155, 160, 161, 166, 167) where it is ``3``, because the standard hexagonal cell holds three primitive rhombohedral cells. A caller-supplied transform may have any non-zero value. .. py:method:: is_identity() -> bool Whether the structure is already in its IT standard setting. .. py:method:: to_setting(coords: Any) -> httk.core.FracVector Map standard-setting reduced coordinates into this setting. Not wrapped. .. py:method:: to_standard(coords: Any) -> httk.core.FracVector Map this setting's reduced coordinates into the standard setting. Not wrapped. .. py:method:: symop_to_setting(operation: httk.atomistic.affine_operation.AffineOperation) -> httk.atomistic.affine_operation.AffineOperation A symmetry operation written in the standard setting, rewritten in this one. .. py:method:: symop_to_standard(operation: httk.atomistic.affine_operation.AffineOperation) -> httk.atomistic.affine_operation.AffineOperation A symmetry operation written in this setting, rewritten in the standard one. .. py:method:: basis_to_setting(basis: Any) -> httk.core.SurdVector Map a standard-setting cell basis (lattice vectors as rows) into this setting. Follows from coordinate invariance: if ``f_own = f_std * M.T()`` then ``B_own = inv(M).T() * B_std``, so that ``f * B`` is the same Cartesian point either way. The transform is rational, so an exact basis stays exact — a hexagonal cell keeps its ``sqrt(3)``. .. py:method:: basis_to_standard(basis: Any) -> httk.core.SurdVector Map this setting's cell basis into the standard setting. .. py:method:: lattice_cosets() -> tuple[httk.core.FracVector, Ellipsis] Translations of this setting's cell that are standard-lattice translations. Expanding an orbit generates points from the standard setting's symmetry operations, which carry the standard lattice's periodicity. When this setting's cell is *larger* than the standard one, that is not enough: points related by a standard lattice translation are genuinely distinct sites here, and the missing ones are recovered by also applying each translation returned by this method. The result is the finite subgroup of ``(Q/Z)^3`` generated by the columns of ``M`` reduced modulo 1, always including the zero translation. It is trivial (just zero) whenever ``M`` is an integer matrix, which covers **all 527** tabulated settings — including the seven with ``det M == 3``, where this setting's cell is *smaller* and the surplus points collapse under wrapping instead. So this only ever does work for a caller-supplied transform to a supercell setting. .. py:method:: inverse() -> SettingTransform The transform in the opposite direction, from this setting to the standard one.