Struct qsym2::symmetry::symmetry_element::SymmetryElement

pub struct SymmetryElement { /* private fields */ }

Structure for storing and managing symmetry elements.

Each symmetry element is a geometrical object in $\mathbb{R}^3$ that encodes the following pieces of information:

• the axis of rotation $\hat{\mathbf{n}}$,
• the angle of rotation $\phi$,
• the associated improper operation, if any, and
• the associated antiunitary operation, if any.

These pieces of information can be stored in the following representation of a symmetry element $\hat{g}$:

\hat{g} = \hat{\alpha} \hat{\gamma} \hat{C}_n^k,

where

• $n \in \mathbb{N}_{+}$, $k \in \mathbb{Z}/n\mathbb{Z}$ such that $\lfloor -n/2 \rfloor < k \le \lfloor n/2 \rfloor$,
• $\hat{\gamma}$ is either the identity $\hat{e}$, the inversion operation $\hat{i}$, or a reflection operation $\hat{\sigma}$ perpendicular to the axis of rotation,
• $\hat{\alpha}$ is either the identity $\hat{e}$, the complex conjugation $\hat{K}$, or the time reversal $\hat{\theta}$.

With this definition, the above pieces of information required to specify a geometrical symmetry element are given as follows:

• the axis of rotation $\hat{\mathbf{n}}$ is given by the axis of $\hat{C}_n^k$,
• the angle of rotation $\phi = 2\pi k/n \in (-\pi, \pi]$,
• the improper contribution $\hat{\gamma}$,
• the antiunitary contribution $\hat{\alpha}$.

This definition also allows the unitary part of $\hat{g}$ to be interpreted as an element of either $\mathsf{O}(3)$ or $\mathsf{SU}'(2)$, which means that the unitary part of $\hat{g}$ is also a symmetry operation in the corresponding group, and a rather special one that can be used to generate other symmetry operations of the group. $\hat{g}$ thus serves as a bridge between molecular symmetry and abstract group theory.

There is one small caveat: for infinite-order elements, $n$ and $k$ can no longer be used to give the angle of rotation. There must thus be a mechanism to allow for infinite-order elements to be interpreted as an arbitrary finite-order one. An explicit specification of the angle of rotation $\phi$ seems to be the best way to do this. In other words, the angle of rotation of each element is specified by either a tuple of integers $(k, n)$ or a floating-point number $\phi$.

Implementations

impl SymmetryElement

pub fn builder() -> SymmetryElementBuilder

Returns a builder to construct a new symmetry element.

Returns

A builder to construct a new symmetry element.

pub fn raw_proper_order(&self) -> &ElementOrder

Returns the raw order of the proper rotation. This might not be equal to the value of $n$ if the fraction $k/n$ has been reduced.

pub fn raw_proper_power(&self) -> Option<&i32>

Returns the raw power of the proper rotation. This might not be equal to the value of $k$ if the fraction $k/n$ has been reduced.

pub fn raw_axis(&self) -> &Vector3<f64>

Returns the raw axis of the proper rotation.

pub fn standard_positive_axis(&self) -> Vector3<f64>

Returns the axis of the proper rotation in the standard positive hemisphere.

pub fn signed_axis(&self) -> Vector3<f64>

Returns the axis of the proper rotation multiplied by the sign of the rotation angle. If the proper rotation is a binary rotation, then the positive axis is always returned.

pub fn proper_rotation_pole(&self) -> Vector3<f64>

Returns the pole of the proper rotation part of the element while leaving any improper and antiunitary contributions intact.

If the proper rotation part if a binary rotation, the pole is always in the standard positive hemisphere.

Returns

The position vector of the proper rotation pole.

pub fn proper_fraction(&self) -> Option<&GenericFraction<u32>>

Returns the proper fraction for this element, if any.

The element lacks a proper fraction if it is infinite-order.

pub fn proper_angle(&self) -> Option<f64>

Returns the proper angle for this element, if any.

The element lacks a proper angle if it is infinite-order and the rotation angle has not been set.

pub fn kind(&self) -> &SymmetryElementKind

Returns the spatial and antiunitary kind of this element.

pub fn rotation_group(&self) -> &RotationGroup

Returns the rotation group and possibly the identity-connected homotopy class in which the proper rotation part of this element is to be interpreted.

pub fn is_generator(&self) -> bool

Returns a boolean indicating if the element is a generator of a group.

pub fn threshold(&self) -> f64

Returns the threshold for approximate comparisons.

pub fn contains_time_reversal(&self) -> bool

Checks if the symmetry element contains a time-reversal operator as the antiunitary part.

Returns

A boolean indicating if the symmetry element contains a time-reversal operator as the antiunitary part.

pub fn contains_antiunitary(&self) -> Option<AntiunitaryKind>

Checks if the symmetry element contains an antiunitary part.

Returns

Returns None if the symmetry element has no antiunitary parts, or Some wrapping around the antiunitary kind if the symmetry element contains an antiunitary part.

pub fn is_su2(&self) -> bool

Checks if the proper rotation part of the element is in $\mathsf{SU}(2)$.

pub fn is_su2_class_1(&self) -> bool

Checks if the proper rotation part of the element is in $\mathsf{SU}(2)$ and connected to the identity via a homotopy path of class 1.

See S.L. Altmann, Rotations, Quaternions, and Double Groups (Dover Publications, Inc., New York, 2005) for further information.

pub fn is_o3_proper(&self, au: Option<AntiunitaryKind>) -> bool

Checks if the spatial part of the symmetry element is proper and has the specified antiunitary attribute.

Arguments

• au - An Option for the desired antiunitary kind.

Returns

A boolean indicating if the symmetry element is proper and has the specified antiunitary attribute.

pub fn is_o3_identity(&self, au: Option<AntiunitaryKind>) -> bool

Checks if the symmetry element is spatially an identity element and has the specified antiunitary attribute.

Arguments

• au - An Option for the desired antiunitary kind.

Returns

A boolean indicating if this symmetry element is spatially an identity element and has the specified antiunitary attribute.

pub fn is_o3_inversion_centre(&self, au: Option<AntiunitaryKind>) -> bool

Checks if the symmetry element is spatially an inversion centre and has the specified antiunitary attribute.

Arguments

• au - An Option for the desired antiunitary kind.

Returns

A boolean indicating if this symmetry element is an inversion centre and has the specified antiunitary attribute.

pub fn is_o3_binary_rotation_axis(&self, au: Option<AntiunitaryKind>) -> bool

Checks if the symmetry element is spatially a binary rotation axis and has the specified antiunitary attribute.

Arguments

• au - An Option for the desired antiunitary kind.

Returns

A boolean indicating if this symmetry element is spatially a binary rotation axis and has the specified antiunitary attribute.

pub fn is_o3_mirror_plane(&self, au: Option<AntiunitaryKind>) -> bool

Checks if the symmetry element is spatially a mirror plane and has the specified antiunitary attribute.

Arguments

• au - An Option for the desired antiunitary kind.

Returns

A boolean indicating if this symmetry element is spatially a mirror plane and has the specified antiunitary attribute.

pub fn get_full_symbol(&self) -> String

Returns the full symbol for this symmetry element, which does not classify certain improper rotation axes into inversion centres or mirror planes, but which does simplify the power/order ratio, and which displays only the absolute value of the power since symmetry elements do not distinguish senses of rotations since rotations of oposite directions are inverses of each other, both of which must exist in the group.

Some additional symbols that can be unconventional include:

• θ: time reversal,
• (Σ): the spatial part is in homotopy class 0 of $\mathsf{SU}'(2)$,
• (QΣ): the spatial part is in homotopy class 1 of $\mathsf{SU}'(2)$.

See RotationGroup for further information.

Returns

The full symbol for this symmetry element.

pub fn get_simplified_symbol(&self) -> String

Returns the simplified symbol for this symmetry element, which classifies special symmetry elements (identity, inversion centre, time reversal, mirror planes), and which simplifies the power/order ratio and displays only the absolute value of the power since symmetry elements do not distinguish senses of rotations, as rotations of oposite directions are inverses of each other, both of which must exist in the group.

Returns

The simplified symbol for this symmetry element.

pub fn get_simplified_symbol_signed_power(&self) -> String

Returns the simplified symbol for this symmetry element, which classifies special symmetry elements (identity, inversion centre, mirror planes), and which simplifies the power/order ratio and displays only the absolute value of the power since symmetry elements do not distinguish senses of rotations. Rotations of oposite directions are inverses of each other, both of which must exist in the group.

Returns

The simplified symbol for this symmetry element.

pub fn convert_to_improper_kind( &self, improper_kind: &SymmetryElementKind, preserves_power: bool, ) -> Self

Returns a copy of the current improper symmetry element that has been converted to the required improper kind. For $\mathsf{SU}'(2)$ elements, the conversion will be carried out in the same homotopy class.

To convert between the two improper kinds, we essentially seek integers $n, n' \in \mathbb{N}_{+}$ and $k \in \mathbb{Z}/n\mathbb{Z}$, $k' \in \mathbb{Z}/n'\mathbb{Z}$, such that

\sigma C_n^k = i C_{n'}^{k'},

where the axes of all involved elements are parallel. By noting that $\sigma = i C_2$ and that $k$ and $k'$ must have opposite signs, we can easily show that, for $k \ge 0, k' < 0$,

\begin{aligned}
    n' &= \frac{2n}{\operatorname{gcd}(2n, n - 2k)},\\
    k' &= -\frac{n - 2k}{\operatorname{gcd}(2n, n - 2k)},
\end{aligned}

whereas for $k < 0, k' \ge 0$,

\begin{aligned}
    n' &= \frac{2n}{\operatorname{gcd}(2n, n + 2k)},\\
    k' &= \frac{n + 2k}{\operatorname{gcd}(2n, n + 2k)}.
\end{aligned}

The above relations are self-inverse. It can be further shown that $\operatorname{gcd}(n', k') = 1$. Hence, for symmetry element conversions, we can simply take $k' = 1$. This is because a symmetry element plays the role of a generator, and the coprimality of $n'$ and $k'$ means that $i C_{n'}^{1}$ is as valid a generator as $i C_{n'}^{k'}$.

Arguments

• improper_kind - The improper kind to which self is to be converted. There is no need to make sure the time reversal specification in improper_kind matches that of self as the conversion will take care of this.
• preserves_power - Boolean indicating if the proper rotation power $k'$ should be preserved or should be set to $1$.

Returns

A copy of the current improper symmetry element that has been converted.

Panics

Panics when self is not an improper element, or when improper_kind is not one of the improper variants.

pub fn to_tr(&self, tr: bool) -> Self

Converts the symmetry element to one with the desired time-reversal property.

Arguments

• tr - A boolean indicating if time reversal is to be included.

Returns

A new symmetry element with or without time reversal as indicated by tr.

pub fn to_su2(&self, normal: bool) -> Option<Self>

Convert the proper rotation of the current element to one in $\mathsf{SU}(2)$.

Arguments

• normal - A boolean indicating whether the resultant $\mathsf{SU}(2)$ proper rotation is of homotopy class 0 (true) or 1 (false) when connected to the identity.

Returns

A symmetry element in $\mathsf{SU}(2)$, or None if the current symmetry element is already in $\mathsf{SU}(2)$.

pub fn closeness_to_cartesian_axes(&self) -> (f64, usize)

The closeness of the symmetry element’s axis to one of the three space-fixed Cartesian axes.

Returns

A tuple of two values:

• A value $\gamma \in [0, 1-1/\sqrt{3}]$ indicating how close the axis is to one of the three Cartesian axes. The closer $\gamma$ is to $0$, the closer the alignment.
• An index for the closest axis: 0 for $z$, 1 for $y$, 2 for $x$.

Panics

Panics when $\gamma$ is outside the required closed interval $[0, 1-1/\sqrt{3}]$ by more than the threshold value in self.

Trait Implementations

impl Clone for SymmetryElement

fn clone(&self) -> SymmetryElement

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SymmetryElement

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for SymmetryElement

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for SymmetryElement

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Hash for SymmetryElement

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for SymmetryElement

fn eq(&self, other: &Self) -> bool

Two symmetry elements are equal if and only if the following conditions are all satisfied:

• they are both in the same rotation group and belong to the same homotopy class;
• they are both proper or improper;
• they both have the same antiunitary properties;
• their axes are either parallel or anti-parallel;
• their proper rotation angles have equal absolute values.

For improper elements, proper rotation angles are taken in the inversion centre convention.

Thus, symmetry element equality is less strict than symmetry operation equality. This is so that parallel or anti-parallel symmetry elements with the same spatial and time-reversal parities and angle of rotation are deemed identical, thus facilitating symmetry detection where one does not yet care much about directions of rotations.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for SymmetryElement

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for SymmetryElement