magnon.symmetry =============== .. py:module:: magnon.symmetry Classes ------- .. autoapisummary:: magnon.symmetry.SymOp Functions --------- .. autoapisummary:: magnon.symmetry.symop_product_modulo_lattice magnon.symmetry.spgcell magnon.symmetry.get_space_group_symops magnon.symmetry.is_group magnon.symmetry.is_point_group magnon.symmetry.k_star magnon.symmetry.get_point_group_name magnon.symmetry.factor_out_translations magnon.symmetry.remove_translations magnon.symmetry.rotation_axes magnon.symmetry.site_symmetry_group Module Contents --------------- .. py:class:: SymOp(rotation, translation, symmetry_tol = magnon.default_numerical_tol) Represents a symmetry operation in three-dimensional space, consisting of a rotation and a translation. :param rotation: Rotation matrix. :type rotation: array_like, shape (3, 3) :param translation: Translation vector. :type translation: array_like, shape (3,) .. rubric:: Notes A symmetry operation is defined as a pair :math:`(R, \mathbf{t})` where: * :math:`R` is a 3x3 rotation matrix * :math:`\mathbf{t}` is a 3-element translation vector This class supports standard operations such as composition (multiplication), inversion, application to coordinates, and introspection of geometric properties such as rotation axes and fixed points. .. py:attribute:: rotation .. py:attribute:: translation .. py:attribute:: symmetry_tol :value: 1e-08 .. py:method:: __mul__(other) Compose two symmetry operations via multiplication. :param other: The symmetry operation to compose on the right. :type other: SymOp :returns: The composed symmetry operation. :rtype: SymOp .. rubric:: Notes For two symmetry operations, .. math:: S_1 x = R_1 x + T_1 .. math:: S_2 x = R_2 x + T_2 the action of the product .. math:: S_1 S_2 x = S_1 (R_2 x + T_2) .. math:: = R_1 (R_2 x + T_2) + T_1 .. math:: = R_1 R_2 x + R_1 T_2 + T_1 so that the composite symmetry operations consists of rotation :math:`R_1 R_2` and translation :math:`R_1 T_2 + T_1`. .. py:method:: __matmul__(pos) Apply this symmetry operation to a coordinate vector. :param pos: The position vector to transform. :type pos: array_like, shape (3,) :returns: The transformed coordinate. :rtype: np.ndarray .. py:method:: __add__(translation) Return a copy of the symmetry operation with the translation vector incremented. :param translation: Translation vector to add. :type translation: array_like, shape (3,) :returns: The symmetry operation with updated translation. :rtype: SymOp .. py:method:: __sub__(translation) Return a copy of the symmetry operation with the translation vector decremented. :param translation: Translation vector to subtract. :type translation: array_like, shape (3,) :returns: The symmetry operation with updated translation. :rtype: SymOp .. py:method:: __pow__(exponent) Return the symmetry operation raised to the given non-negative integer power. :param exponent: The exponent (must be non-negative). :type exponent: int :returns: The composed operation applied `exponent` times. :rtype: SymOp .. py:method:: __eq__(other) Check equality of two symmetry operations with numerical tolerance. :param other: The object to compare with. :type other: Any :returns: True if the operations are equal within tolerance. :rtype: bool .. py:method:: __hash__() Compute a hash value based on the rounded rotation and translation components. :returns: Hash value. :rtype: int .. py:method:: __repr__() Return an unambiguous string representation. :returns: String representation of the symmetry operation. :rtype: str .. py:method:: __str__() Return a formatted string showing the rotation matrix and translation vector. :returns: Human-readable representation of the symmetry operation. :rtype: str .. py:method:: identity() :classmethod: Return the identity symmetry operation. :returns: The identity operation (rotation = I, translation = 0). :rtype: SymOp .. py:method:: inverse() Compute the inverse of this symmetry operation. :returns: The inverse operation :math:`(R^{-1}, -R^{-1}t)`. :rtype: SymOp .. py:method:: rotation_order() Return the order of the rotational part of this symmetry operation. The order is the smallest positive integer n such that :math:`R^n = I`. :returns: The order of the rotation. :rtype: int .. rubric:: Notes If a rotation is combined with inversion (i.e. an improper rotation), it will have a determinant of -1. In this case, the order of the rotational part (excluding the inversion) is returned as a negative integer. If this order is odd, it must be doubled to ensure that the inversion part when raised to the exponent gives the identity. .. py:method:: intrinsic_translation() Compute the intrinsic translation vector of this symmetry operation. This represents the translational component that remains after applying the operation repeatedly. :returns: The intrinsic translation vector. :rtype: np.ndarray .. py:method:: fixed_point() Return a point that is invariant under this symmetry operation. :returns: A fixed point in space under the operation. :rtype: np.ndarray .. py:method:: rotation_axis(tol = magnon.default_numerical_tol) Return the axis of rotation as a unit vector, if defined. :param tol: Tolerance for identifying unit eigenvalues. :type tol: float :returns: A unit vector along the rotation axis, or None if not well-defined. :rtype: np.ndarray or None .. py:method:: is_translation_only(tol = magnon.default_numerical_tol) Check whether the symmetry operation is a pure translation. :param tol: Tolerance for determining if the rotational part is close to the identity. :type tol: float :returns: True if the rotation is the identity and the translation is non-zero modulo lattice. :rtype: bool .. py:method:: is_identity(tol = magnon.default_numerical_tol) Check whether the symmetry operation is the identity. :param tol: Tolerance for determining if the operation is close to the identity. :type tol: float :returns: True if the operation is (I, 0). :rtype: bool .. py:method:: as_homogeneous_matrix() Return the 4x4 homogeneous transformation matrix for this symmetry operation. :returns: A 4x4 matrix combining rotation and translation. :rtype: np.ndarray .. py:function:: symop_product_modulo_lattice(a, b) Multiply two symmetry operations with translation wrapped modulo lattice. This function performs composition of two symmetry operations of the form :math:`(R_a, \mathbf{t}_a)` and :math:`(R_b, \mathbf{t}_b)`, and reduces the resulting translation vector modulo 1. The operation is defined as: .. math:: R = R_a R_b .. math:: \mathbf{t} = (\mathbf{t}_a + R_a \mathbf{t}_b) \; \text{mod} \; 1 This is useful when working with symmetry operations in scaled coordinates where translations differing by a lattice vector are equivalent. :param a: The first symmetry operation. :type a: SymOp :param b: The second symmetry operation. :type b: SymOp :returns: The resulting symmetry operation after composition, with translation modulo 1. :rtype: SymOp .. py:function:: spgcell(ase_atoms, magnetic=False) Convert an ASE Atoms object into a spglib-compatible tuple representation. This function returns the standard input format required by spglib: (lattice, positions, atomic numbers [, magnetic moments]), depending on whether magnetic symmetry detection is requested. :param ase_atoms: An ASE Atoms object representing the crystal structure. :type ase_atoms: ase.Atoms :param magnetic: If True, include initial magnetic moments in the output tuple for magnetic symmetry analysis. Default is False. :type magnetic: bool, optional :returns: A tuple containing: * lattice : np.ndarray, shape (3, 3) - Lattice vectors as rows of a matrix. * positions : np.ndarray, shape (N, 3) - Scaled atomic positions. * numbers : np.ndarray, shape (N,) - Atomic numbers. * moments : np.ndarray, shape (N,), optional - Magnetic moments, only returned if `magnetic=True`. :rtype: tuple .. rubric:: Notes This function is useful for preparing input for `spglib.get_symmetry`, `get_spacegroup`, etc. .. py:function:: get_space_group_symops(atoms, use_magnetic_symmetry=False) Return the set of symmetry operations that form the space group of a crystal. This function uses spglib to extract the space group symmetry operations from an ASE Atoms object, and returns them as a collection of `SymOp` objects containing both rotation and translation components. :param atoms: An ASE Atoms object representing the crystal structure. :type atoms: ase.Atoms :returns: A collection of symmetry operations representing the space group of the structure. :rtype: Collection[SymOp] .. py:function:: is_group(symops, mod_lattice = False) Check whether a set of symmetry operations forms a group under composition. This function verifies the group axioms: * Contains the identity * Every element has a (left) inverse in the set * Closed under composition When `mod_lattice` is True, composition is performed modulo lattice translations. This is useful when working with periodic symmetry groups in scaled coordinates. :param symops: A set or list of symmetry operations to test for group structure. :type symops: Collection[SymOp] :param mod_lattice: If True, symmetry operations are composed modulo lattice translations. Default is False. :type mod_lattice: bool, optional :returns: True if the set satisfies the group axioms under the specified multiplication rule, False otherwise. :rtype: bool .. rubric:: Notes Associativity is assumed due to matrix multiplication being associative. .. py:function:: is_point_group(symops, tol = magnon.default_numerical_tol) Check whether a set of symmetry operations forms a point group under composition. This function verifies: * All symmetry operations are pure rotations (zero translation part). * Contains the identity operation. * Every element has a (left) inverse in the set. * Closed under composition. :param symops: Set or list of symmetry operations to test. :type symops: Collection[SymOp] :param tol: Tolerance for checking zero translation. Default is 1e-8. :type tol: float, optional :returns: True if the set forms a point group, False otherwise. :rtype: bool .. rubric:: Notes * Point groups must have only rotational parts (no translations). * Associativity is assumed due to matrix multiplication being associative. .. py:function:: k_star(k, symops, tol = magnon.default_numerical_tol) Generate the star of vector k by applying a set of symmetry operations. The star of k is defined as: .. math:: \mathrm{star}(\mathbf{k}) = \{ g \cdot \mathbf{k} \mid g \in G \} where each symmetry operation g acts on k as a linear transformation, potentially followed by a translation. :param k: A 3-element array representing the input wave vector in scaled coordinates. :type k: array_like :param symops: A collection of symmetry operations forming a group. :type symops: Collection[SymOp] :param tol: Tolerance for identifying duplicate vectors in the star. Default is 1e-8. :type tol: float, optional :returns: List of unique wave vectors forming the star of `k`, each as a NumPy array of shape (3,). :rtype: list[np.ndarray] .. py:function:: get_point_group_name(symops) Return the crystallographic point group name associated with a set of symmetry operations. The function extracts the rotational components from the given symmetry operations and uses spglib to identify the crystallographic point group to which they belong. :param symops: A list or set of symmetry operations, typically forming a point group (i.e., all translations removed). :type symops: Collection[SymOp] :returns: The international symbol of the crystallographic point group (e.g., "m-3m", "4mm"). :rtype: str .. rubric:: Notes This function assumes the input operations contain only rotation components. If translations are present, use `factor_out_translations` or `remove_translations` beforehand. .. py:function:: factor_out_translations(symops) Factor out translations from symmetry operations to obtain the associated point group. This function takes a list of symmetry operations of the form :math:`(R, \mathbf{t})` and removes the translational components, yielding only the rotational parts :math:`(R, \mathbf{0})`. Duplicate operations (i.e., those with the same rotation matrix) are removed to produce a valid point group. :param symops: A list or set of symmetry operations (rotation + translation) forming a group. :type symops: Collection[SymOp] :returns: The list of unique symmetry operations with zero translations, representing the point group associated with the input space group. :rtype: list[SymOp] .. rubric:: Notes This corresponds to the mathematical quotient of the space group by its translation subgroup: :math:`G / T`, where :math:`T` is the group of pure translations. .. py:function:: remove_translations(symops) Remove the translational part from one or more symmetry operations. This operation replaces each symmetry operation :math:`(R, \mathbf{t})` with :math:`(R, \mathbf{0})`, effectively projecting the operation into pure rotational space. It is commonly used to convert space group operations to their corresponding point group operations. :param symops: A single symmetry operation or a collection of symmetry operations from which to remove translations. :type symops: SymOp or Collection[SymOp] :returns: The symmetry operation(s) with translation components set to zero. Returns a single SymOp if input is a single object, or a list of SymOps otherwise. :rtype: SymOp | list[SymOp] .. rubric:: Notes This function is equivalent to projecting out translations: :math:`(R, \mathbf{t}) \rightarrow (R, \mathbf{0})`. If you want to deduplicate the resulting rotations, use `factor_out_translations` instead. .. py:function:: rotation_axes(symops, tol=magnon.default_numerical_tol) Identify distinct rotation axes from a collection of symmetry operations. Each axis is returned as a unit vector along with its associated rotation order. The function excludes improper rotations (e.g., mirror planes or inversion) and the identity operation. Axes that are equivalent up to sign (i.e., parallel but oppositely directed) are treated as duplicates. :param symops: A list or set of symmetry operations to analyze. :type symops: Collection[SymOp] :param tol: Numerical tolerance used to identify equivalent axes (default is 1e-8). :type tol: float, optional :returns: A list of unique (axis, order) pairs. Each axis is a unit vector (as a NumPy array) and the order is the smallest positive integer n such that the rotation raised to the power n equals the identity. :rtype: list[tuple[np.ndarray, int]] .. py:function:: site_symmetry_group(space_group, x, cell, delta_equiv_min = 1e-05) Compute the site symmetry group for a given scaled position `x` in the unit cell. :param space_group: A list or set of symmetry operations (rotation + translation) forming a space group. :type space_group: Collection[SymOp] :param x: Scaled coordinates of the point for which the site symmetry group is to be determined. :type x: array_like, shape (3,) :param cell: Lattice vectors as rows of a 3×3 matrix defining the unit cell. :type cell: array_like, shape (3, 3) :param delta_equiv_min: Minimum distance (in Cartesian units) under which two points are considered equivalent. Used to identify when a symmetry operation maps the point onto itself modulo lattice translations. Default is 1e-5. :type delta_equiv_min: float, optional :returns: The symmetry operations from the space group that leave `x` fixed (modulo lattice translations). These operations may include translations, but they form a point group under multiplication. :rtype: list[SymOp]