magnon.symmetry¶
Classes¶
Represents a symmetry operation in three-dimensional space, consisting of a rotation and a translation. |
Functions¶
Multiply two symmetry operations with translation wrapped modulo lattice. |
|
|
Convert an ASE Atoms object into a spglib-compatible tuple representation. |
|
Return the set of symmetry operations that form the space group of a crystal. |
|
Check whether a set of symmetry operations forms a group under composition. |
|
Check whether a set of symmetry operations forms a point group under composition. |
|
Generate the star of vector k by applying a set of symmetry operations. |
|
Return the crystallographic point group name associated with a set of symmetry operations. |
|
Factor out translations from symmetry operations to obtain the associated point group. |
|
Remove the translational part from one or more symmetry operations. |
|
Identify distinct rotation axes from a collection of symmetry operations. |
|
Compute the site symmetry group for a given scaled position x in the unit cell. |
Module Contents¶
- class magnon.symmetry.SymOp(rotation, translation, symmetry_tol=magnon.default_numerical_tol)¶
Represents a symmetry operation in three-dimensional space, consisting of a rotation and a translation.
- Parameters:
rotation (array_like, shape (3, 3)) – Rotation matrix.
translation (array_like, shape (3,)) – Translation vector.
symmetry_tol (float) –
Notes
A symmetry operation is defined as a pair \((R, \mathbf{t})\) where:
\(R\) is a 3x3 rotation matrix
\(\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.
- rotation¶
- translation¶
- symmetry_tol = 1e-08¶
- __mul__(other)¶
Compose two symmetry operations via multiplication.
- Parameters:
other (SymOp) – The symmetry operation to compose on the right.
- Returns:
The composed symmetry operation.
- Return type:
Notes
For two symmetry operations,
\[S_1 x = R_1 x + T_1\]\[S_2 x = R_2 x + T_2\]the action of the product
\[S_1 S_2 x = S_1 (R_2 x + T_2)\]\[= R_1 (R_2 x + T_2) + T_1\]\[= R_1 R_2 x + R_1 T_2 + T_1\]so that the composite symmetry operations consists of rotation \(R_1 R_2\) and translation \(R_1 T_2 + T_1\).
- __matmul__(pos)¶
Apply this symmetry operation to a coordinate vector.
- Parameters:
pos (array_like, shape (3,)) – The position vector to transform.
- Returns:
The transformed coordinate.
- Return type:
np.ndarray
- __add__(translation)¶
Return a copy of the symmetry operation with the translation vector incremented.
- Parameters:
translation (array_like, shape (3,)) – Translation vector to add.
- Returns:
The symmetry operation with updated translation.
- Return type:
- __sub__(translation)¶
Return a copy of the symmetry operation with the translation vector decremented.
- Parameters:
translation (array_like, shape (3,)) – Translation vector to subtract.
- Returns:
The symmetry operation with updated translation.
- Return type:
- __pow__(exponent)¶
Return the symmetry operation raised to the given non-negative integer power.
- __eq__(other)¶
Check equality of two symmetry operations with numerical tolerance.
- Parameters:
other (Any) – The object to compare with.
- Returns:
True if the operations are equal within tolerance.
- Return type:
- __hash__()¶
Compute a hash value based on the rounded rotation and translation components.
- Returns:
Hash value.
- Return type:
- __repr__()¶
Return an unambiguous string representation.
- Returns:
String representation of the symmetry operation.
- Return type:
- __str__()¶
Return a formatted string showing the rotation matrix and translation vector.
- Returns:
Human-readable representation of the symmetry operation.
- Return type:
- classmethod identity()¶
Return the identity symmetry operation.
- Returns:
The identity operation (rotation = I, translation = 0).
- Return type:
- inverse()¶
Compute the inverse of this symmetry operation.
- Returns:
The inverse operation \((R^{-1}, -R^{-1}t)\).
- Return type:
- rotation_order()¶
Return the order of the rotational part of this symmetry operation.
The order is the smallest positive integer n such that \(R^n = I\).
- Returns:
The order of the rotation.
- Return type:
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.
- 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.
- Return type:
np.ndarray
- fixed_point()¶
Return a point that is invariant under this symmetry operation.
- Returns:
A fixed point in space under the operation.
- Return type:
np.ndarray
- rotation_axis(tol=magnon.default_numerical_tol)¶
Return the axis of rotation as a unit vector, if defined.
- Parameters:
tol (float) – Tolerance for identifying unit eigenvalues.
- Returns:
A unit vector along the rotation axis, or None if not well-defined.
- Return type:
np.ndarray or None
- is_translation_only(tol=magnon.default_numerical_tol)¶
Check whether the symmetry operation is a pure translation.
- is_identity(tol=magnon.default_numerical_tol)¶
Check whether the symmetry operation is the identity.
- as_homogeneous_matrix()¶
Return the 4x4 homogeneous transformation matrix for this symmetry operation.
- Returns:
A 4x4 matrix combining rotation and translation.
- Return type:
np.ndarray
- magnon.symmetry.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 \((R_a, \mathbf{t}_a)\) and \((R_b, \mathbf{t}_b)\), and reduces the resulting translation vector modulo 1. The operation is defined as:
\[R = R_a R_b\]\[\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.
- magnon.symmetry.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.
- Parameters:
ase_atoms (ase.Atoms) – An ASE Atoms object representing the crystal structure.
magnetic (bool, optional) – If True, include initial magnetic moments in the output tuple for magnetic symmetry analysis. Default is False.
- 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.
- Return type:
Notes
This function is useful for preparing input for spglib.get_symmetry, get_spacegroup, etc.
- magnon.symmetry.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.
- Parameters:
atoms (ase.Atoms) – An ASE Atoms object representing the crystal structure.
- Returns:
A collection of symmetry operations representing the space group of the structure.
- Return type:
Collection[SymOp]
- magnon.symmetry.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.
- Parameters:
- Returns:
True if the set satisfies the group axioms under the specified multiplication rule, False otherwise.
- Return type:
Notes
Associativity is assumed due to matrix multiplication being associative.
- magnon.symmetry.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.
- Parameters:
- Returns:
True if the set forms a point group, False otherwise.
- Return type:
Notes
Point groups must have only rotational parts (no translations).
Associativity is assumed due to matrix multiplication being associative.
- magnon.symmetry.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:
\[\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.
- Parameters:
- Returns:
List of unique wave vectors forming the star of k, each as a NumPy array of shape (3,).
- Return type:
list[np.ndarray]
- magnon.symmetry.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.
- Parameters:
symops (Collection[SymOp]) – A list or set of symmetry operations, typically forming a point group (i.e., all translations removed).
- Returns:
The international symbol of the crystallographic point group (e.g., “m-3m”, “4mm”).
- Return type:
Notes
This function assumes the input operations contain only rotation components. If translations are present, use factor_out_translations or remove_translations beforehand.
- magnon.symmetry.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 \((R, \mathbf{t})\) and removes the translational components, yielding only the rotational parts \((R, \mathbf{0})\). Duplicate operations (i.e., those with the same rotation matrix) are removed to produce a valid point group.
- Parameters:
symops (Collection[SymOp]) – A list or set of symmetry operations (rotation + translation) forming a group.
- Returns:
The list of unique symmetry operations with zero translations, representing the point group associated with the input space group.
- Return type:
Notes
This corresponds to the mathematical quotient of the space group by its translation subgroup: \(G / T\), where \(T\) is the group of pure translations.
- magnon.symmetry.remove_translations(symops)¶
Remove the translational part from one or more symmetry operations.
This operation replaces each symmetry operation \((R, \mathbf{t})\) with \((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.
- Parameters:
symops (SymOp or Collection[SymOp]) – A single symmetry operation or a collection of symmetry operations from which to remove translations.
- 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.
- Return type:
Notes
This function is equivalent to projecting out translations: \((R, \mathbf{t}) \rightarrow (R, \mathbf{0})\). If you want to deduplicate the resulting rotations, use factor_out_translations instead.
- magnon.symmetry.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.
- Parameters:
- 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.
- Return type:
- magnon.symmetry.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.
- Parameters:
space_group (Collection[SymOp]) – A list or set of symmetry operations (rotation + translation) forming a space group.
x (array_like, shape (3,)) – Scaled coordinates of the point for which the site symmetry group is to be determined.
cell (array_like, shape (3, 3)) – Lattice vectors as rows of a 3×3 matrix defining the unit cell.
delta_equiv_min (float, optional) – 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.
- 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.
- Return type: