Struct gchemol::Molecule

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

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

Methods

impl Molecule

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

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

impl Molecule

Chemical formula

pub fn formula(&self) -> String

Return the molecule formula represented in string Return empty string if molecule containing no atom

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

Return a hashmap for counting atom symbols.

impl Molecule

Lattice related methods

pub fn get_lattice(&self) -> Option<&Lattice>

Get a reference to Lattice struct.

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

Set periodic lattice

pub fn is_periodic(&self) -> bool

Return true if Molecule is a periodic structure.

pub fn unbuild_crystal(&mut self)

Unbuild current crystal structure leaving a nonperiodic structure

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
    P: Into<Matrix<f64, U3, U1, <DefaultAllocator as Allocator<f64, U3, U1>>::Buffer>>,
    T: IntoIterator<Item = P>, 

Set fractional coordinates relative to unit cell.

Panics if Molecule is aperiodic structure.

pub fn supercell(&self, sa: usize, sb: usize, sc: usize) -> Option<Molecule>

Create a supercell.

Arguments

• sa, sb, sc: An sequence of three scaling factors. E.g., [2, 1, 1] specifies that the supercell should have dimensions 2a x b x c

impl Molecule

Molecule constructors

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

Create a new empty molecule with specific name

pub fn from_atoms<T>(atoms: T) -> Molecule where
    T: IntoIterator,
    <T as IntoIterator>::Item: Into<Atom>, 

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

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

Build Molecule from raw graph struct.

impl Molecule

Core methods

pub fn add_atom(&mut self, sn: 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 atomic_numbers(&self) -> impl Iterator<Item = usize>

Iterate over atomic numbers.

pub fn positions(&self) -> impl Iterator<Item = [f64; 3]>

Iterate over atom positions ordered by serial numbers.

pub fn title(&self) -> String

Return the name of the molecule, which is typpically modified for safely storing in various chemical file formats.

pub fn graph(&self) -> &NxGraph<Atom, Bond>

Return a reference to internal Molecule Graph struct.

pub fn graph_mut(&mut self) -> &mut NxGraph<Atom, Bond>

Return mut access to internal Molecule Graph struct.

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_mut(&mut self, sn: usize) -> Option<&mut Atom>

Mutable access to atom by atom serial number.

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 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>(&mut self, sn: usize, position: P) where
    P: Into<Matrix<f64, U3, U1, <DefaultAllocator as Allocator<f64, U3, U1>>::Buffer>>, 

Set atom position.

Panic if atom sn does not exist.

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

Set atom symbol.

Panic if atom sn does not exist.

pub fn add_atoms_from<T, P>(&mut self, atoms: T) where
    P: Into<Atom>,
    T: IntoIterator<Item = (usize, P)>, 

Add a list of atoms into molecule.

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

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
    P: Into<Matrix<f64, U3, U1, <DefaultAllocator as Allocator<f64, U3, U1>>::Buffer>>,
    T: IntoIterator<Item = P>, 

Set positions of atoms in sequential order.

pub fn set_symbols<T, S>(&mut self, symbols: T) where
    S: Into<AtomKind>,
    T: IntoIterator<Item = S>, 

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)

impl Molecule

Extra properties for Molecule.

pub fn set_momentum<P>(&mut self, sn: usize, m: P) where
    P: Into<Matrix<f64, U3, U1, <DefaultAllocator as Allocator<f64, U3, U1>>::Buffer>>, 

Panics

• panic if there is no atom associated with sn.

impl Molecule

pub fn clean(&mut self) -> Result<(), Error>

Clean up molecule geometry using stress majorization algorithm

impl Molecule

Handling chemical bonds in Molecule.

pub fn unbound(&mut self)

Removes all existing bonds between atoms

pub fn unbond(&mut self, atom_indices1: &[usize], atom_indices2: &[usize])

Removes all bonds between two selections to respect pymol's unbond command.

Parameters

atom_indices1: the first collection of atoms

atom_indices2: the other collection of atoms

Reference

https://pymolwiki.org/index.php/Unbond

pub fn rebond(&mut self)

Recalculates all bonds in molecule based on interatomic distances and covalent radii.

impl Molecule

Geometry related methods

pub fn translate<P>(&mut self, disp: P) where
    P: Into<Matrix<f64, U3, U1, <DefaultAllocator as Allocator<f64, U3, U1>>::Buffer>>, 

Translate the whole molecule by a displacement

pub fn center_of_geometry(&self) -> [f64; 3]

Return the center of geometry of molecule (COG).

pub fn center_of_mass(&self) -> [f64; 3]

Return the center of mass of molecule (COM).

pub fn recenter(&mut self)

Center the molecule around its center of geometry

impl Molecule

pub fn distance(&self, i: usize, j: usize) -> f64

Return the distance between atom i and atom j. For periodic structure, this method will return the distance under the minimum image convention.

Panic

• if atom indices i or j out of range.

impl Molecule

Display order of Atom in Molecule

pub fn renumber(&mut self)

Renumber atoms consecutively from 1.

pub fn swap_order(&mut self, sn1: usize, sn2: usize)

Swap the display order of two Atoms sn1 and sn2.

Panic

• Panics if serial numbers sn1 or sn2 out of bounds.

pub fn reorder<O>(&mut self, keys: &[O]) where
    O: Ord, 

Reorder the atoms according to the ordering of keys. Keys define 1-to-1 mapping of atoms.

Note

• This method will cause serial numbers renumbered from 1.

Panic

• panics if the size of keys is different than the number of atoms.

impl Molecule

High level topology structure of Molecule.

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

Return the shortest distance counted in number of chemical bonds between two atoms. Return None if they are not connected.

pub fn path_between(&self, sn1: usize, sn2: usize) -> Option<Vec<usize>>

Return the shortest path between two atoms. Return None if they are not connected.

Panics

• panic if there is no atom associated with sn1 or sn2

pub fn connected(&self, a: usize) -> impl Iterator<Item = usize>

Return all directly bonded atoms with a

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<(), Error>

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<Molecule, <__D as Deserializer<'de>>::Error> where
    __D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl FromFile for Molecule

fn from_file<P>(path: P) -> Result<Molecule, Error> where
    P: AsRef<Path>, 

Construct molecule from external text file

impl Serialize for Molecule

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

Serialize this value into the given Serde serializer.

impl StringIO for Molecule

fn format_as<S>(&self, fmt: S) -> Result<String, Error> where
    S: AsRef<str>, 

Format molecule as string in specific molecular file format. Return error if cannot format molecule in fmt.

fn parse_from<R, S>(s: R, fmt: S) -> Result<Molecule, Error> where
    R: Read + Seek,
    S: AsRef<str>, 

construct molecule from string in specific molecular file format.

fn from_str<S>(s: &str, fmt: S) -> Result<Molecule, Error> where
    S: AsRef<str>, 

impl TemplateRendering for Molecule

fn render_with(&self, path: &Path) -> Result<String, Error>

Render with input template file.

impl ToFile for Molecule

fn to_file<T>(&self, path: T) -> Result<(), Error> where
    T: AsRef<Path>, 

Save molecule to an external file