Struct qsym2::auxiliary::molecule::Molecule

pub struct Molecule {
    pub atoms: Vec<Atom>,
    pub electric_atoms: Option<Vec<Atom>>,
    pub magnetic_atoms: Option<Vec<Atom>>,
    pub threshold: f64,
}

Structure containing the atoms constituting a molecule.

Fields

atoms: Vec<Atom>

The atoms constituting this molecule.

electric_atoms: Option<Vec<Atom>>

Optional special atom to represent the electric fields applied to this molecule.

magnetic_atoms: Option<Vec<Atom>>

Optional special atoms to represent the magnetic fields applied to this molecule.

threshold: f64

A threshold for approximate equality comparisons.

Implementations

impl Molecule

pub fn from_xyz<P: AsRef<Path>>(filename: P, thresh: f64) -> Self

Parses an XYZ file to construct a molecule.

Arguments

• filename - The XYZ file to be parsed.

Returns

The parsed Molecule structure.

Panics

Panics when unable to parse the provided XYZ file.

pub fn to_xyz<P: AsRef<Path>>(&self, filename: P) -> Result<(), Error>

Writes the ordinary atoms in the molecule to an XYZ file.

Arguments

• filename - The XYZ file to be written.

pub fn from_atoms(all_atoms: &[Atom], thresh: f64) -> Self

Construct a molecule from an array of atoms.

Arguments

• all_atoms - The atoms (of all types) constituting this molecule.
• threshold - A threshold for approximate equality comparisons.

Returns

The constructed Molecule struct.

Panics

Panics when the numbers of fictitious special atoms, if any, are invalid. It is expected that, when present, there are two magnetic special atoms and/or one electric special atom.

pub fn molecule_ordinary_atoms(&self) -> Self

Constructs a new molecule containing only the ordinary atoms in this molecule.

pub fn molecule_magnetic_atoms(&self) -> Option<Self>

Constructs a new molecule containing only the fictitious magnetic atoms in this molecule, if any.

Returns

Returns None if this molecule has no fictitious magnetic atoms.

pub fn molecule_electric_atoms(&self) -> Option<Self>

Constructs a new molecule containing only the fictitious electric atoms in this molecule, if any.

Returns

Returns None if this molecule has no fictitious electric atoms.

pub fn get_all_atoms(&self) -> Vec<&Atom>

Retrieves a vector of references to all atoms in this molecule, including special ones, if any.

Returns

All atoms in this molecule.

pub fn get_all_atoms_mut(&mut self) -> Vec<&mut Atom>

Retrieves a vector of mutable references to all atoms in this molecule, including special ones, if any.

Returns

All atoms in this molecule.

pub fn calc_com(&self) -> Point3<f64>

Calculates the centre of mass of the molecule.

This does not take into account fictitious special atoms.

Returns

The centre of mass.

pub fn calc_inertia_tensor(&self, origin: &Point3<f64>) -> Matrix3<f64>

Calculates the inertia tensor of the molecule.

This does take into account fictitious special atoms.

Arguments

• origin - An origin about which the inertia tensor is evaluated.

Returns

The inertia tensor as a $3 \times 3$ matrix.

pub fn calc_moi(&self) -> ([f64; 3], [Vector3<f64>; 3])

Calculates the moments of inertia and the corresponding principal axes.

This does take into account fictitious special atoms.

Returns

• The moments of inertia in ascending order.
• The corresponding principal axes.

Panics

Panics when any of the moments of inertia cannot be compared.

pub fn calc_interatomic_distance_matrix(&self) -> (Array2<f64>, Vec<Vec<usize>>)

Determines the interatomic distance matrix and the indices of symmetry-equivalent atoms.

This does take into account fictitious special atoms.

Returns

• The interatomic distance matrix where the distances in each column are sorted in ascending order. Column $j$ contains the interatomic distances from atom $j$ to all other atoms (both ordinary and fictitious) in the molecule. Also note that all atoms (both ordinary and fictitious) are included here, so the matrix is square.
• A vector of vectors of symmetry-equivalent atom indices. Each inner vector contains indices of atoms in one SEA group.

pub fn calc_sea_groups(&self) -> Vec<Vec<Atom>>

Determines the sets of symmetry-equivalent atoms.

This does take into account fictitious special atoms.

Returns

• Copies of the atoms in the molecule, grouped into symmetry-equivalent groups.

Panics

Panics when the any of the mass-weighted interatomic distances cannot be compared.

pub fn set_magnetic_field(&mut self, magnetic_field: Option<Vector3<f64>>)

Adds two fictitious magnetic atoms to represent the magnetic field.

Arguments

• magnetic_field - The magnetic field vector. If zero or None, any magnetic field present will be removed.

Panics

Panics when the number of atoms cannot be represented as an f64 value.

pub fn set_electric_field(&mut self, electric_field: Option<Vector3<f64>>)

Adds one fictitious electric atom to represent the electric field.

Arguments

• electric_field - The electric field vector. If zero or None, any electric field present will be removed.

Panics

Panics when the number of atoms cannot be represented as an f64 value.

pub fn adjust_threshold(&self, thresh: f64) -> Self

Clones this molecule and adjusts all comparison thresholds to that specified by thresh.

Arguments

• thresh - The new threshold to be assigned to the cloned molecule.

Returns

A cloned copy of the molecule wit the adjusted threshold.

pub fn reorientate_mut(&mut self, moi_thresh: f64)

Reorientates the molecule in-place into a canonical alignment with the space-fixed axes of the coordinate system.

Fictitious special atoms are also moved during the reorientation.

If the molecule has a unique principal axis, then this axis becomes aligned with the $z$-axis and the other two degenerate axes become aligned with the $x$- and $y$-axes of the coordinate system. If the molecule has no unique principal axes, then the axes are aligned with $x$-, $y$-, and $z$-axes in ascending order of moments of inertia.

Arguments

• moi_thresh - Threshold for comparing moments of inertia.

pub fn reorientate(&self, moi_thresh: f64) -> Self

Clones and reorientates the molecule into a canonical alignment with the space-fixed axes of the coordinate system.

Fictitious special atoms are also moved during the reorientation.

If the molecule has a unique principal axis, then this axis becomes aligned with the $z$-axis and the other two degenerate axes become aligned with the $x$- and $y$-axes of the coordinate system. If the molecule has no unique principal axes, then the axes are aligned with $x$-, $y$-, and $z$-axes in ascending order of moments of inertia.

Arguments

• moi_thresh - Threshold for comparing moments of inertia.

Returns

A reoriented copy of the molecule.

Trait Implementations

impl Clone for Molecule

fn clone(&self) -> Molecule

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Molecule

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Molecule

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Molecule

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

Formats the value using the given formatter.

impl From<PyMolecule> for Molecule

fn from(pymol: PyMolecule) -> Self

Converts to this type from the input type.

impl PartialEq for Molecule

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

This method tests for self and other values to be equal, and is used by ==.

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 PermutableCollection for Molecule

fn get_perm_of(&self, other: &Self) -> Option<Permutation<Self::Rank>>

Determines the permutation of all atoms to map self to other. Special fictitious atoms are included after ordinary atoms, with magnetic atoms before electric atoms.

Arguments

• other - Another molecule to be compared with self.

Returns

Returns a permutation that permutes all atoms of self to give other, or None if no such permutation exists.

fn permute(&self, perm: &Permutation<Self::Rank>) -> Result<Self, Error>

Permutes all atoms in this molecule (including special fictitious atoms) and places them in a new molecule to be returned.

Arguments

• perm - A permutation for the atoms. Special fictitious atoms are included after ordinary atoms, with magnetic atoms before electric atoms.

Returns

A new molecule with the permuted atoms.

Panics

Panics if the rank of perm does not match the number of atoms in this molecule, or if the permutation results in atoms of different kind (e.g. ordinary and magnetic) are permuted into each other.

fn permute_mut(&mut self, perm: &Permutation<Self::Rank>) -> Result<(), Error>

Permutes in-place all atoms in this molecule (including special fictitious atoms).

The in-place rearrangement implementation is taken from here.

Arguments

• perm - A permutation for the atoms. Special fictitious atoms are included after ordinary atoms, with magnetic atoms before electric atoms.

Panics

Panics if the rank of perm does not match the number of atoms in this molecule, or if the permutation results in atoms of different kind (e.g. ordinary and magnetic) are permuted into each other.

type Rank = usize

The type of the rank of the permutation.

impl Serialize for Molecule

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

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Transform for Molecule

fn transform_mut(&mut self, mat: &Matrix3<f64>)

Transforms in-place the coordinates about the origin by a given transformation.

fn rotate_mut(&mut self, angle: f64, axis: &Vector3<f64>)

Rotates in-place the coordinates through angle about axis.

fn improper_rotate_mut( &mut self, angle: f64, axis: &Vector3<f64>, kind: &ImproperRotationKind, )

Improper-rotates in-place the coordinates through angle about axis.

fn translate_mut(&mut self, tvec: &Vector3<f64>)

Translates in-place the coordinates by a specified translation vector in three dimensions.

fn recentre_mut(&mut self)

Recentres in-place to put the centre of mass at the origin.

fn reverse_time_mut(&mut self)

Reverses time by reversing in-place the polarity of any magnetic special atoms.

fn transform(&self, mat: &Matrix3<f64>) -> Self

Clones and transforms the coordinates about the origin by a given transformation.

fn rotate(&self, angle: f64, axis: &Vector3<f64>) -> Self

Clones and rotates the coordinates through angle about axis.

fn improper_rotate( &self, angle: f64, axis: &Vector3<f64>, kind: &ImproperRotationKind, ) -> Self

Clones and improper-rotates the coordinates through angle about axis.

fn translate(&self, tvec: &Vector3<f64>) -> Self

Clones and translates in-place the coordinates by a specified translation in three dimensions.

fn recentre(&self) -> Self

Clones and recentres to put the centre of mass at the origin.

fn reverse_time(&self) -> Self

Clones the molecule and reverses time by reversing the polarity of any magnetic special atoms.