Struct gchemol_core::Molecule

pub struct Molecule {
    pub properties: PropertyStore,
    pub lattice: Option<Lattice>,
    /* private fields */
}

Molecule is the most important data structure in gchemol, which repsents “any singular entity, irrespective of its nature, used to concisely express any type of chemical particle that can exemplify some process: for example, atoms, molecules, ions, etc. can all undergo a chemical reaction”. Molecule may have chemical bonds between atoms.

Reference

1. http://goldbook.iupac.org/M03986.html
2. https://en.wikipedia.org/wiki/Molecular_entity

Fields

properties: PropertyStore

Arbitrary property stored in key-value pair. Key is a string type, but it is the responsibility of the user to correctly interpret the value.

lattice: Option<Lattice>

Crystalline lattice for structure using periodic boundary conditions

Implementations

impl Molecule

pub fn from_database(name: &str) -> Self

Returns Molecule created from the internal database (mainly for tests).

Available names: CH4, H2O, HCN

impl Molecule

Chemical formula

pub fn formula(&self) -> String

Return the molecule formula represented in string according to the Hill system order. Return empty string if molecule containing no atom.

pub fn reduced_symbols(&self) -> HashMap<String, usize>

Return a hashmap for counting atom symbols.

impl Molecule

Lattice related methods

pub fn set_lattice(&mut self, lat: Lattice)

Set periodic lattice as lat.

pub fn set_lattice_scaled(&mut self, lat: Lattice)

Set periodic Lattice as lat, and scaled atom positions to fit new lattice. Will panic if not a periodic structure.

pub fn is_periodic(&self) -> bool

Return true if Molecule is a periodic structure.

pub fn unbuild_crystal(&mut self) -> Option<Lattice>

Unbuild current crystal structure leaving a nonperiodic structure. Return Lattice object if periodic, otherwise return None.

pub fn scaled_positions(&self) -> Option<impl Iterator<Item = [f64; 3]> + '_>

👎Deprecated: use get_scaled_positions instead

Return fractional coordinates relative to unit cell. Return None if not a periodic structure

pub fn get_scaled_positions( &self ) -> Option<impl Iterator<Item = [f64; 3]> + '_>

Return fractional coordinates relative to unit cell. Return None if not a periodic structure

pub fn set_scaled_positions<T, P>(&mut self, scaled: T)

where T: IntoIterator<Item = P>, P: Into<Vector3f>,

Set fractional coordinates of atoms in sequence order.

Panics if Molecule is aperiodic.

pub fn set_scaled_positions_from<T, P>(&mut self, scaled: T)

where T: IntoIterator<Item = (usize, P)>, P: Into<Vector3f>,

Set fractional coordinates of atoms specified in serial numbers.

Panics if Molecule is aperiodic.

impl Molecule

pub fn bounding_box(&self, padding: f64) -> [f64; 3]

Return minimal bounding box in x, y, z directions

impl Molecule

Molecule constructors

pub fn new(name: &str) -> Self

Create a new empty molecule with specific name

pub fn from_atoms<T>(atoms: T) -> Self

where T: IntoIterator, T::Item: Into<Atom>,

Build a molecule from iterator of atoms associated with serial numbers from 1.

pub fn from_graph(graph: NxGraph<Atom, Bond>) -> Self

Build Molecule from raw graph struct.

pub fn from_graph_raw( graph: NxGraph<Atom, Bond>, atoms: impl IntoIterator<Item = usize> ) -> Self

Build Molecule from raw graph struct, with atom serial numbers.

impl Molecule

Core methods

pub fn add_atom(&mut self, a: usize, atom: Atom)

Add atom a into molecule. If Atom numbered as a already exists in molecule, then the associated Atom will be updated with atom.

pub fn remove_atom(&mut self, a: usize) -> Option<Atom>

Remove Atom a from Molecule.

Return the removed Atom on success, and return None if Atom a does not exist.

pub fn natoms(&self) -> usize

Return the number of atoms in the molecule.

pub fn nbonds(&self) -> usize

Return the number of bonds in the molecule.

pub fn add_bond(&mut self, a: usize, b: usize, bond: Bond)

Add bond between Atom a and Atom b into molecule. The existing Bond will be replaced if Atom a already bonded with Atom b.

Panic if the specified atom a or b does not exist

pub fn remove_bond(&mut self, a: usize, b: usize) -> Option<Bond>

Remove the bond between atom a and atom b.

Returns the removed Bond on success

Panic if the specified atom a or b does not exist

pub fn clear(&mut self)

Remove all atoms and bonds. To remove bonds only, see unbound method.

pub fn atoms(&self) -> impl Iterator<Item = (usize, &Atom)>

Iterate over atoms ordered by serial numbers.

pub fn bonds(&self) -> impl Iterator<Item = (usize, usize, &Bond)>

Iterate over bonds in arbitrary order.

pub fn serial_numbers(&self) -> impl Iterator<Item = usize>

Iterate over atom serial numbers in ascending order. Serial number is an unsigned integer (1-based, traditionally) for accessing Atom in Molecule

pub fn numbers(&self) -> impl Iterator<Item = usize> + '_

A shorter alias to serial_numbers method.

pub fn symbols(&self) -> impl Iterator<Item = &str>

Iterate over atom symbols ordered by serial numbers.

pub fn masses(&self) -> impl Iterator<Item = f64> + '_

Iterate over atom’s mass ordered by atom’s serial numbers. Dummy atom has mass of zero.

pub fn atomic_numbers(&self) -> impl Iterator<Item = usize> + '_

Iterate over atomic numbers.

pub fn positions(&self) -> impl Iterator<Item = Point3> + '_

Iterate over atom positions ordered by serial numbers.

pub fn title(&self) -> String

A short description of the molecule.

NOTE: for long title, only the first line will be return for safely storing in various chemical file formats such as xyz.

impl Molecule

Edit Molecule

pub fn get_atom(&self, sn: usize) -> Option<&Atom>

Read access to atom by atom serial number.

pub fn get_atom_unchecked(&self, sn: usize) -> &Atom

Read access to atom by atom serial number. Panic if no this atom.

pub fn has_atom(&self, sn: usize) -> bool

Returns true if the molecule contains atom with the given sn

pub fn get_atom_mut(&mut self, sn: usize) -> Option<&mut Atom>

Mutable access to atom by atom serial number.

pub fn get_atom_unchecked_mut(&mut self, sn: usize) -> &mut Atom

Mutable access to atom by atom serial number. Panic if no this atom.

pub fn get_bond(&self, sn1: usize, sn2: usize) -> Option<&Bond>

Read access to bond by a pair of atoms. Return None if there is no bond between Atom sn1 and Atom sn2.

pub fn has_bond(&self, sn1: usize, sn2: usize) -> bool

Returns true if the molcule contains bond between atom sn1 and sn2

pub fn get_bond_mut(&mut self, sn1: usize, sn2: usize) -> Option<&mut Bond>

Mutable access to bond by a pair of atoms.

pub fn set_position<P: Into<Vector3f>>(&mut self, sn: usize, position: P)

Set atom position.

Panic if atom sn does not exist.

pub fn set_symbol<S: Into<AtomKind>>(&mut self, sn: usize, sym: S)

Set atom symbol.

Panic if atom sn does not exist.

pub fn add_atoms_from<T, P>(&mut self, atoms: T)

where T: IntoIterator<Item = (usize, P)>, P: Into<Atom>,

Add a list of atoms into molecule.

pub fn set_title<S: AsRef<str>>(&mut self, title: S)

Set molecular title.

pub fn add_bonds_from<T>(&mut self, bonds: T)

where T: IntoIterator<Item = (usize, usize, Bond)>,

Add a list of bonds into molecule.

pub fn set_positions<T, P>(&mut self, positions: T)

where T: IntoIterator<Item = P>, P: Into<Vector3f>,

Set positions of atoms in sequential order.

pub fn update_positions<T, P>(&mut self, positions: T)

where T: IntoIterator<Item = P>, P: Into<Vector3f>,

Update positions of atoms in sequential order, with freezing coordinates ignored.

pub fn set_positions_from<T, P>(&mut self, selected_positions: T)

where T: IntoIterator<Item = (usize, P)>, P: Into<Vector3f>,

Set positions of specified atoms

pub fn set_symbols<T, S>(&mut self, symbols: T)

where T: IntoIterator<Item = S>, S: Into<AtomKind>,

Set element symbols

pub fn remove_atoms_from(&mut self)

Remove atoms from .. (unimplemented)

pub fn remove_bonds_from(&mut self)

Remove bonds from .. (unimplemented)

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

fn default() -> Molecule

Returns the “default value” for a type.

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 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.