Struct gchemol::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) -> Molecule

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 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) -> 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<Matrix<f64, Const<nalgebra::::base::dimension::U3::{constant#0}>, Const<1>, ArrayStorage<f64, 3, 1>>>,

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<Matrix<f64, Const<nalgebra::::base::dimension::U3::{constant#0}>, Const<1>, ArrayStorage<f64, 3, 1>>>,

Set fractional coordinates of atoms specified in serial numbers.

Panics if Molecule is aperiodic.

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

pub fn set_lattice_from_bounding_box(&mut self, padding: f64)

Create a Lattice from the minimal bounding box of the Molecule extended by a positive value of padding. NOTE: padding has to be large enough (> 0.5) to avoid self interaction with its periodic mirror.

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

Return minimal bounding box in x, y, z directions

impl Molecule

This impl block contains no items.

Methods for internal uses

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

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

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 = [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_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>(&mut self, sn: usize, position: P)where
P: Into<Matrix<f64, Const<nalgebra::::base::dimension::U3::{constant#0}>, Const<1>, ArrayStorage<f64, 3, 1>>>,

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
T: IntoIterator<Item = (usize, P)>,
P: Into<Atom>,

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
T: IntoIterator<Item = P>,
P: Into<Matrix<f64, Const<nalgebra::::base::dimension::U3::{constant#0}>, Const<1>, ArrayStorage<f64, 3, 1>>>,

Set positions of atoms in sequential order.

pub fn update_positions<T, P>(&mut self, positions: T)where
T: IntoIterator<Item = P>,
P: Into<Matrix<f64, Const<nalgebra::::base::dimension::U3::{constant#0}>, Const<1>, ArrayStorage<f64, 3, 1>>>,

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<Matrix<f64, Const<nalgebra::::base::dimension::U3::{constant#0}>, Const<1>, ArrayStorage<f64, 3, 1>>>,

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)

impl Molecule

Extra properties for Molecule.

pub fn set_velocity<P>(&mut self, sn: usize, m: P)where
P: Into<Matrix<f64, Const<nalgebra::::base::dimension::U3::{constant#0}>, Const<1>, ArrayStorage<f64, 3, 1>>>,

Set atom sn ’s velocity as m

Panics

• panic if there is no atom associated with sn.

pub fn set_velocities<T, M>(&mut self, velocities: T)where
T: IntoIterator<Item = M>,
M: Into<Matrix<f64, Const<nalgebra::::base::dimension::U3::{constant#0}>, Const<1>, ArrayStorage<f64, 3, 1>>>,

Set velocities of atoms in sequential order.

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

Return an iterator over atom velocities.

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. For periodic system, the bonds are determined by applying miniumu image convention.

impl Molecule

pub fn freezing_atoms_mask(&self) -> Mask

Create a Mask for freezing atoms in 1-D vec.

pub fn freezing_coords_mask(&self) -> Mask

Create a Mask for Cartesian coordinates (3D) of freezing atoms in flatten 1-D vec.

impl Molecule

Geometry related methods

pub fn translate<P>(&mut self, disp: P)where
P: Into<Matrix<f64, Const<nalgebra::::base::dimension::U3::{constant#0}>, Const<1>, ArrayStorage<f64, 3, 1>>>,

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 recenter(&mut self)

Center the molecule around its center of geometry

impl Molecule

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

👎Deprecated: get_distance instead

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.

pub fn get_distance(&self, i: usize, j: usize) -> Option<f64>

Return the distance of two atoms i, j. For periodic structure, this method will return the distance under the minimum image convention. Return None if any serial number is invalid.

pub fn get_angle(&self, i: usize, j: usize, k: usize) -> Option<f64>

Return the angle of three atoms i, j, k in radians, irrespective periodic images. Return None if any serial number is invalid.

pub fn get_torsion(&self, i: usize, j: usize, k: usize, l: usize) -> Option<f64>

Return the torsion angle of four atoms i, j, k, l in radians, irrespective periodic images. Return None if any serial number is invalid.

impl Molecule

pub fn superimpose_onto(
&mut self,
mol_ref: &Molecule,
selection: Option<&[usize]>
) -> f64

Superimpose structure onto mol_ref which will be held fixed during alignment. Return superposition rmsd on done.

NOTE

• The atoms must be in one-to-one mapping with atoms in mol_ref
• The structure could be mirrored for better alignment.
• Heavy atoms have more weights.

impl Molecule

Geometry related methods

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

Return molecule’s inertia matrix (3x3) in reference to molecule’s center of mass

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

Return the center of mass of molecule (COM).

impl Molecule

Display order of Atom in Molecule

pub fn renumber(&mut self)

Renumber atoms consecutively from 1.

pub fn renumber_using(&mut self, atoms: &[usize])

Renumber atoms by user provided numbers for each atom.

NOTE

• number in atoms must be unique and in one-to-one mapping to original numbering.

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

pub fn find_rings(&self, nmax: usize) -> Vec<HashSet<usize, RandomState>, Global>

Find rings up to nmax atoms in Molecule.

Arguments

• nmax: max ring size to be searched.

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, Global>>

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

pub fn get_sub_molecule(&self, atoms: &[usize]) -> Option<Molecule>

Return a sub molecule induced by atoms in parent molecule. Return None if atom serial numbers are invalid. Return an empty Molecule if atoms empty.

NOTE

• The sub molecule shares the same numbering system with its parent.

pub fn bond_graph(&self) -> NxGraph<usize, usize>

Return a shallow connectivity graph without copying atom/bond data

pub fn fragmented(&self) -> impl Iterator<Item = Molecule>

Break molecule into multiple fragments based on its bonding connectivity.

pub fn nfragments(&self) -> usize

Return the number of fragments based on bonding connectivity.

impl Molecule

pub fn selection_by_expanding_bond(
&self,
m: usize,
n: usize
) -> Vec<usize, Global>

Return selected atoms by expanding n chemical bonds away from the center atom m

Note: the center atom m is put last in returned molecule.

pub fn selection_by_distance(&self, n: usize, r: f64) -> Vec<usize, Global>

Return selected atoms by cutoff distance r nearby central atom n NOTE: For periodic structure, the selection returned could be not unique due to periodic images.

pub fn create_neighbor_probe(&self) -> Neighborhood

Return a Neighborhood struct for probing nearest neighbors in mol

N.B. The neighbor node index is defined using atom serial number

Example

let probe = mol.create_neighbor_probe();
let p = [1.0, 2.0, 3.0];
let r_cut = 3.2;
let neighbors = probe.search(p, r_cut);
let neighbors = probe.neighbors(12, r_cut);

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