Ensemble¶

This is the pydoc code for the ensemble module.

# molli.chem.ensemble

This submodule defines the ConformerEnsemble class.

class molli.chem.ensemble.ConformerEnsemble(other: ConformerEnsemble = None, /, n_conformers: int = 0, n_atoms: int = 0, *, name: str = None, charge: int = None, mult: int = None, coords: ArrayLike = None, weights: ArrayLike = None, atomic_charges: ArrayLike = None, copy_atoms: bool = False, **kwds)¶

Bases: Connectivity

This is a fundamental class of Molli that employs methods that work on a collection of conformers. This is built to treat all conformers as having a single Connectivity and various coordinates associated with the atoms of each Conformer. The ensemble supports iteration and collective transformations.

Examples

ConformerEnsemble can be initialized from a multi-mol2 file

>>> ml.ConformerEnsemble.load_mol2(ml.files.pentane_confs_mol2)
ConformerEnsemble(name='pentane', formula='C5 H12', n_conformers=7)

It can also be initialized from a list of molecules

>>> mol_list = ml.Molecule.load_all_mol2(ml.files.pentane_confs_mol2)
>>> ml.ConformerEnsemble(mol_list)
ConformerEnsemble(name='pentane', formula='C5 H12', n_conformers=7)

property coords: ndarray¶

Set of atomic positions in shape (n_confs, n_atoms, 3)

Returns:: Returns array of coordinates
Return type:: np.ndarray

Examples

>>> ens = ml.ConformerEnsemble.load_mol2(ml.files.pentane_confs_mol2)
>>> ens.coords
array([[[-2.8045e+00,  3.9964e+00, -1.4128e+00],...

property weights: ndarray¶

The weights of conformers in the ensemble in shape (n_confs,)

Returns:: Returns array of weights
Return type:: np.ndarray

Examples

>>> ens = ml.ConformerEnsemble.load_mol2(ml.files.pentane_confs_mol2)
>>> ens.weights
array([1., 1., 1., 1., 1., 1., 1.])

property atomic_charges: ndarray¶

The atomic charges of the ensemble in shape (n_confs,n_atoms)

Returns:: Returns the atomic charges of the ensemble
Return type:: np.ndarray

Examples

>>> ens = ml.ConformerEnsemble.load_mol2(ml.files.pentane_confs_mol2)
>>> ens.atomic_charges
array([[-0.0653, -0.0559, ...], [-0.0653, -0.0559, ...], ...

classmethod load_mol2(input: str | Path | IO, *, name: str = None, source_units: str = 'Angstrom') → ConformerEnsemble¶

Loads mol2 from a file path, string, or stream

Parameters:

cls (type[ConformerEnsemble]) – Class to be loaded into
input (str | Path | IO) – File path, string, or stream
name (str, optional) – Name for ConformerEnsemble, by default None
source_units (str, optional) – Units to be used in loading, by default “Angstrom”

Returns:

Returns ConformerEnsemble

Return type:

ConformerEnsemble

Examples

>>> ml.ConformerEnsemble.load_mol2(ml.files.pentane_confs_mol2)
ConformerEnsemble(name='pentane', formula='C5 H12', n_conformers=7)

classmethod loads_mol2(input: str, *, name: str = None, source_units: str = 'Angstrom') → ConformerEnsemble¶

Loads mol2 from a string

Parameters:

cls (type[ConformerEnsemble]) – Class to be loaded into
input (str) – Mol2 block as string
name (str, optional) – Name for ConformerEnsemble, by default None
source_units (str, optional) – Units to be used in loading, by default “Angstrom”

Returns:

Returns ConformerEnsemble

Return type:

ConformerEnsemble

Examples

>>> with open(ml.files.pentane_confs_mol2, 'r') as f:
>>>     ml.ConformerEnsemble.loads_mol2(f.read())
ConformerEnsemble(name='pentane', formula='C5 H12', n_conformers=7)

classmethod load_xyz(input: str | Path | IO, *, name: str = None, source_units: str = 'Angstrom') → ConformerEnsemble¶

Loads xyz from a file path, string, or stream

Parameters:

cls (type[ConformerEnsemble]) – Class to be loaded into
input (str | Path | IO) – File path, string, or stream
name (str, optional) – Name for ConformerEnsemble, by default None
source_units (str, optional) – Units to be used in loading, by default “Angstrom”

Returns:

Returns ConformerEnsemble

Return type:

ConformerEnsemble

Examples

>>> ml.ConformerEnsemble.load_xyz(ml.files.pentane_confs_xyz)
ConformerEnsemble(name='pentane', formula='C5 H12', n_conformers=7)

classmethod loads_xyz(input: str, *, name: str = None, source_units: str = 'Angstrom') → ConformerEnsemble¶

Loads xyz from a string

Parameters:

cls (type[ConformerEnsemble]) – Class to be loaded into
input (str) – xyz block as string
name (str, optional) – Name for ConformerEnsemble, by default None
source_units (str, optional) – Units to be used in loading, by default “Angstrom”

Returns:

Returns ConformerEnsemble

Return type:

ConformerEnsemble

Examples

>>> with open(ml.files.pentane_confs_xyz, 'r') as f:
>>>     ml.ConformerEnsemble.loads_xyz(f.read())
ConformerEnsemble(name='pentane', formula='C5 H12', n_conformers=7)

dump_mol2(stream: StringIO) → None¶

Dumps the multi-mol2 block into the output stream

Parameters:: stream (StringIO, optional) – Output stream, by default None

Examples

>>> ens = ml.ConformerEnsemble.load_mol2(ml.files.pentane_confs_mol2)
>>> with open('test.mol2', 'w') as f:
>>>     ens.dump_mol2(f)
# Produced with molli package
@<TRIPOS>MOLECULE
pentane
...

dumps_mol2() → str¶

Dumps the multi-mol2 block as a string

Returns:: The multi-mol2 block
Return type:: str

Examples

>>> ens = ml.ConformerEnsemble.load_mol2(ml.files.pentane_confs_mol2)
>>> ens.dumps_mol2()
# Produced with molli package
@<TRIPOS>MOLECULE
pentane
...

dump_xyz(stream: StringIO)¶

Dumps the .xyz file into the stream

Parameters:: stream (StringIO, optional) – Stream into which the xyz values are written.

dumps_xyz()¶

Returns the string of the .xyz file

Returns:: String containing .xyz file of multi-conformer molecule.
Return type:: str

property n_conformers: int¶

returns: Returns number of conformers in the ensemble :rtype: int

Examples

>>> ens = ml.ConformerEnsemble.load_mol2(ml.files.pentane_confs_mol2)
>>> ens.n_conformers
7

extend(others: ConformerEnsemble | Iterable[CartesianGeometry]) → None¶

Extends ConformerEnsemble

Parameters:: others (ConformerEnsemble | Iterable[CartesianGeometry]) – Iterable object with a coords property

Examples

>>> ens1 = ml.ConformerEnsemble.load_mol2(ml.files.pentane_confs_mol2)
>>> ens2 = ml.ConformerEnsemble.load_mol2(ml.files.pentane_confs_mol2)
>>> ens1.extend(ens2)
>>> ens1
ConformerEnsemble(name='pentane', formula='C5 H12', n_conformers=14)

append(other: CartesianGeometry) → None¶

_summary_

Parameters:: other (CartesianGeometry) – Object with a coords property

Examples

>>> ens = ml.ConformerEnsemble.load_mol2(ml.files.pentane_confs_mol2)
>>> mol = ens[0]
>>> ens.append(mol)
>>> ens
ConformerEnsemble(name='pentane', formula='C5 H12', n_conformers=8)

scale(factor: float, allow_inversion=False) → None¶

Scale the coordinates by a factor. This also scales the atomic charges

Parameters:

factor (float) – Factor to scale by
allow_inversion (bool, optional) – Allows inversion of coordinates, by default False

Examples

>>> ens = ml.ConformerEnsemble.load_mol2(ml.files.pentane_confs_mol2)
>>> ens.coords
array([[[-2.8045e+00,  3.9964e+00, -1.4128e+00],...
>>> ens.scale(0.5)
>>> ens.coords
array([[[-1.40225e+00,  1.99820e+00, -7.06400e-01],...

invert() → None¶

Coordinates are inverted wrt the origin. This also inverts inverts the absolute stereochemistry

Examples

>>> ens = ml.ConformerEnsemble.load_mol2(ml.files.pentane_confs_mol2)
>>> ens.coords
array([[[-2.8045e+00,  3.9964e+00, -1.4128e+00],...
>>> ens.invert
>>> ens.coords
array([[[ 2.8045e+00, -3.9964e+00,  1.4128e+00],...

get_substr_indices(pattern: Connectivity) → Generator[list[int], None, None]¶

Yields all possible combinations of substructure indices that matched with the given pattern.

Parameters:¶

pattern: Connectivity

Returns:¶

Generator over list of all possible mappings to pattern

If only one variation of substructure indices is needed, use next(ens.get_substr_indices(pattern))

Examples

>>> for ens in tqdm(library):
>>>    for mapping in ens.get_substr_indices(pattern):
>>>        ...

translate(vector: ArrayLike)¶

Translates coordinates by a set amount

Parameters:: vector (ArrayLike) – Array for translation

Examples

>>> ens = ml.ConformerEnsemble.load_mol2(ml.files.pentane_confs_mol2)
>>> ens.coords
array([[[-2.8045e+00,  3.9964e+00, -1.4128e+00],...
>>> ens.translate([1,1,1])
>>> ens.coords
array([[[-1.8045,  4.9964, -0.4128],

rotate(rotation_matrix: ndarray) → ndarray¶

Rotates coordinates by a set rotation matrix

Parameters:: rotation_matrix (np.ndarray) – Rotation matrix for ConformerEnsemble

Examples

>>> ens = ml.ConformerEnsemble.load_mol2(ml.files.pentane_confs_mol2)
>>> ens.coords
array([[[-2.8045e+00,  3.9964e+00, -1.4128e+00],...
>>> ens.rotate(np.array([[1,0,0],[0,0,-1],[0,1,0]])) #90 deg Rot X-axis
>>> ens.coords
array([[[-2.8045e+00, -1.4128e+00, -3.9964e+00],

center_at_atom(_a: Atom)¶

Translates coordinates of ensemble placing an atom at the origin

Parameters:: _a (Atom) – Atom to center coordinates around

Examples

>>> ens = ml.ConformerEnsemble.load_mol2(ml.files.pentane_confs_mol2)
>>> a = ens.get_atom(0)
>>> ens.center_at_atom(a)
array([[[0,0,0],...

center_at_core(substructure_indices: list[int])¶: Centers ensemble at its substructure so that the coordinates of centroid of the this substructure are at the origin.

optimal_rotation_to_ref_coords(func: Callable[[ndarray, ndarray], Tuple[ndarray, float]], substr_indices: list[list[int]], reference_subgeometry: Substructure) → Tuple[list[float], ndarray]¶

This is the inner part of the main function for Conformer alignment. For each conformer in the ConformerEnsemble, it does the following: 1. Finds optimal rotation using symmetry corrected rmsd. It calculates rmsd (root mean squared deviation) for every possible mapping with reference coordinates, then picks the lowest rmsd and corresponding rotation matrix. 2. Rotates conformer with the resulting rotation matrix. 3. Returns list with the lowest rmsd values for each conformer.

Parameters:¶

func: callable: function that calculates rmsd value and rotation matrix. It accepts two ndarrays of coordinates and returns optimal rotation matrix as ndarray and minimal rmsd value as float.
substr_indices: list: list of all possible mappings to the alignment core
reference_subgeometry: ml.chem.Substructure: Referentce coordinates for the alignment

Returns:¶

rmsds: list: List of rmsd values for each conformer in the given ConformerEnsemble

Notes:¶

If core_indices list has only one element, the algorithm will perform the usual (non symmetry corrected) alignment

align_to_ref_coords(func: Callable[[ndarray, ndarray], Tuple[ndarray, float]], substructure_indices: list[list[int]], reference_subgeometry: Substructure, vec: list = None) → list¶

This is the outer part of the main function for the ConformerEnsemble alignment.

Parameters:¶

func: Callable: function that calculates rmsd value and rotation matrix. It accepts two ndarrays of coordinates and returns optimal rotation matrix as ndarray and minimal rmsd value as float.
substr_indices: list: list of all possible mappings to the alignment core
reference_subgeometry: Substructure: Referential coordinates for the alignment
vec: list = None: translation vector. If vec is not None, the whole ConformerEnsemble will be translated on that vector.

Returns:¶

rmsds: list: List of rmsd values for each conformer in the ConformerEnsemble

Notes:¶

Reference_subgeometry should be centered at the origin before calling this function.

class molli.chem.ensemble.Conformer(parent: ConformerEnsemble, conf_id: int)¶

Bases: Molecule

Conformer class behaves like a molecule, yet is completely virtual. More documentation about the use of this class can be found in the Molecule documentation

Examples

>>> ens = ml.ConformerEnsemble.load_mol2(ml.files.pentane_confs_mol2)
>>> ens[0]
Conformer(name='pentane', conf_id=0)

property name: str¶

Name of the Conformer

Returns:: The name
Return type:: str

Examples

>>> ens = ml.ConformerEnsemble.load_mol2(ml.files.pentane_confs_mol2)
>>> ens[0].name
pentane