Molecule

class Molecule(atoms, bonds, position_matrix)[source]

Bases: object

An abstract base class for molecules.

Notes

You might notice that some of the methods of this abstract base class are implemented. This is purely for convenience when implementing subclasses. The implemented public methods are simply default implementations, which can be safely ignored or overridden, when implementing subclasses. Any private methods are implementation details of these default implementations.

Examples

Aligning a Molecule with a Vector

You want to rotate a molecule, such that it is aligned along with a specific direction.

import stk
import numpy as np

molecule1 = stk.BuildingBlock('CCCCC')
# Align molecule1 along x-axis.
molecule1 = molecule1.with_rotation_between_vectors(
    start=molecule1.get_direction(),
    target=np.array([1., 0., 0.]),
    origin=molecule1.get_centroid(),
)

molecule2 = stk.ConstructedMolecule(
    topology_graph=stk.polymer.Linear(
        building_blocks=(
            stk.BuildingBlock(
                smiles='BrCCCBr',
                functional_groups=(stk.BromoFactory(), ),
            ),
        ),
        repeating_unit='A',
        num_repeating_units=15,
    ),
)
# Align molecule2 along the [1, 4, -3] vector.
molecule2 = molecule2.with_rotation_between_vectors(
    start=molecule2.get_direction(),
    target=np.array([1., 4., -3.]),
    origin=molecule2.get_centroid(),
)

Aligning a Molecule along a Plane

You want to place the benzene flat along the xy plane.

import stk
import numpy as np

benzene = stk.BuildingBlock('c1ccccc1')
benzene = benzene.with_rotation_between_vectors(
    start=benzene.get_plane_normal(),
    target=np.array([0., 0., 1.]),
    origin=benzene.get_centroid(),
)

Methods

`clone`()	Return a clone.
`get_atomic_positions`([atom_ids])	Yield the positions of atoms.
`get_atoms`([atom_ids])	Yield the atoms in the molecule, ordered by id.
`get_bonds`()	Yield the bond in the molecule.
`get_canonical_atom_ids`()	Map the id of each atom to its id under canonical ordering.
`get_centroid`([atom_ids])	Return the centroid.
`get_direction`([atom_ids])	Return a vector of best fit through the atoms.
`get_maximum_diameter`([atom_ids])	Return the maximum diameter.
`get_num_atoms`()	Return the number of atoms in the molecule.
`get_num_bonds`()	Return the number of bonds in the molecule.
`get_plane_normal`([atom_ids])	Return the normal to the plane of best fit.
`get_position_matrix`()	Return a matrix holding the atomic positions.
`to_rdkit_mol`()	Return an `rdkit` representation.
`with_canonical_atom_ordering`()	Return a clone, with canonically ordered atoms.
`with_centroid`(position[, atom_ids])	Return a clone with its centroid at position.
`with_displacement`(displacement)	Return a displaced clone.
`with_position_matrix`(position_matrix)	Return a clone with atomic positions set by position_matrix.
`with_rotation_about_axis`(angle, axis, origin)	Return a rotated clone.
`with_rotation_between_vectors`(start, target, ...)	Return a rotated clone.
`with_rotation_to_minimize_angle`(start, ...)	Return a rotated clone.
`with_structure_from_file`(path[, extension])	Return a clone, with its structure taken from a file.
`write`(path[, atom_ids])	Write the structure to a file.

__init__(atoms, bonds, position_matrix)[source]

Initialize a Molecule.

Parameters

atoms (tuple[Atom, ...]) – The atoms which compose the molecule.
bonds (tuple[Bond, ...]) – The bonds of the molecule.
position_matrix (ndarray) – A (n, 3) matrix holding the position of every atom in the Molecule.

clone()[source]

Return a clone.

Return type: Molecule
Returns: The clone.

get_atomic_positions(atom_ids=None)[source]

Yield the positions of atoms.

Parameters: atom_ids (Union[int, Iterable[int], None]) – The ids of the atoms whose positions are desired. If None, then the positions of all atoms will be yielded. Can be a single int, if the position of a single atom is desired.
Yields: The x, y and z coordinates of an atom.
Return type: Iterator[ndarray]

get_atoms(atom_ids=None)[source]

Yield the atoms in the molecule, ordered by id.

Parameters: atom_ids (Union[int, Iterable[int], None]) – The ids of atoms to yield. Can be a single int if a single atom is wanted, or None if all atoms are wanted.
Yields: An atom in the molecule.
Return type: Iterator[Atom]

get_bonds()[source]

Yield the bond in the molecule.

Yields: A bond in the molecule.
Return type: Iterator[Bond]

get_canonical_atom_ids()[source]

Map the id of each atom to its id under canonical ordering.

Return type: dict[int, int]
Returns: Maps the id of each atom in the molecule to the id it would have under canonical ordering.

get_centroid(atom_ids=None)[source]

Return the centroid.

Parameters: atom_ids (Union[int, Iterable[int], None]) – The ids of atoms which are used to calculate the centroid. Can be a single int, if a single atom is to be used, or None if all atoms are to be used.
Return type: ndarray
Returns: The centroid of atoms specified by atom_ids.
Raises: ValueError – If atom_ids has a length of 0.

get_direction(atom_ids=None)[source]

Return a vector of best fit through the atoms.

Parameters: atom_ids (Union[int, Iterable[int], None]) – The ids of atoms which should be used to calculate the vector. Can be a single int, if a single atom is to be used, or None, if all atoms are to be used.
Return type: ndarray
Returns: The vector of best fit.
Raises: ValueError – If atom_ids has a length of 0.

get_maximum_diameter(atom_ids=None)[source]

Return the maximum diameter.

This method does not account for the van der Waals radius of atoms.

Parameters: atom_ids (Union[int, Iterable[int], None]) – The ids of atoms which are considered when looking for the maximum diameter. Can be a single int, if a single atom is to be used, or None, if all atoms are to be used.
Return type: float
Returns: The maximum diameter in the molecule.
Raises: ValueError – If atom_ids has a length of 0.

get_num_atoms()[source]

Return the number of atoms in the molecule.

Return type: int
Returns: The number of atoms in the molecule.

get_num_bonds()[source]

Return the number of bonds in the molecule.

Return type: int
Returns: The number of bonds in the molecule.

get_plane_normal(atom_ids=None)[source]

Return the normal to the plane of best fit.

Parameters: atom_ids (Union[int, Iterable[int], None]) – The ids of atoms which should be used to calculate the plane. Can be a single int, if a single atom is to be used, or None, if all atoms are to be used.
Return type: ndarray
Returns: Vector orthonormal to the plane of the molecule.
Raises: ValueError – If atom_ids has a length of 0.

get_position_matrix()[source]

Return a matrix holding the atomic positions.

Return type: ndarray
Returns: The array has the shape (n, 3). Each row holds the x, y and z coordinates of an atom.

to_rdkit_mol()[source]

Return an rdkit representation.

Return type: Mol
Returns: The molecule in rdkit format.

with_canonical_atom_ordering()[source]

Return a clone, with canonically ordered atoms.

Return type: Molecule
Returns: The clone.

with_centroid(position, atom_ids=None)[source]

Return a clone with its centroid at position.

Parameters

position (ndarray) – This array holds the position on which the centroid of the clone is going to be placed.
atom_ids (Union[int, Iterable[int], None]) – The ids of atoms which should have their centroid set to position. Can be a single int, if a single atom is to be used, or None, if all atoms are to be used.

Return type

Molecule

Returns

A clone with its centroid at position.

with_displacement(displacement)[source]

Return a displaced clone.

Parameters: displacement (ndarray) – The displacement vector to be applied.
Return type: Molecule
Returns: A displaced clone.

with_position_matrix(position_matrix)[source]

Return a clone with atomic positions set by position_matrix.

Parameters: position_matrix (ndarray) – The position matrix of the clone. The shape of the matrix is (n, 3).
Return type: Molecule
Returns: The clone.

with_rotation_about_axis(angle, axis, origin)[source]

Return a rotated clone.

The clone is rotated by angle about axis on the origin.

Parameters

angle (float) – The size of the rotation in radians.
axis (ndarray) – The axis about which the rotation happens. Must have unit magnitude.
origin (ndarray) – The origin about which the rotation happens.

Return type

Molecule

Returns

A rotated clone.

with_rotation_between_vectors(start, target, origin)[source]

Return a rotated clone.

The rotation is equal to a rotation from start to target.

Given two direction vectors, start and target, this method applies the rotation required transform start to target onto the clone. The rotation occurs about the origin.

For example, if the start and target vectors are 45 degrees apart, a 45 degree rotation will be applied to the clone. The rotation will be along the appropriate direction.

The great thing about this method is that you as long as you can associate a geometric feature of the molecule with a vector, then the clone can be rotated so that this vector is aligned with target. The defined vector can be virtually anything. This means that any geometric feature of the molecule can be easily aligned with any arbitrary direction.

Parameters

start (ndarray) – A vector which is to be rotated so that it transforms into the target vector.
target (ndarray) – The vector onto which start is rotated.
origin (ndarray) – The point about which the rotation occurs.

Return type

Molecule

Returns

A rotated clone.

with_rotation_to_minimize_angle(start, target, axis, origin)[source]

Return a rotated clone.

The clone is rotated by the rotation required to minimize the angle between start and target.

Note that this function will not necessarily overlay the start and target vectors. This is because the possible rotation is restricted to the axis.

Parameters

start (ndarray) – The vector which is rotated.
target (ndarray) – The vector which is stationary.
axis (ndarray) – The vector about which the rotation happens. Must have unit magnitude.
origin (ndarray) – The origin about which the rotation happens.

Return type

Molecule

Returns

A rotated clone.

Raises

ValueError – If target has a magnitude of 0. In this case it is not possible to calculate an angle between start and target.

with_structure_from_file(path, extension=None)[source]

Return a clone, with its structure taken from a file.

Multiple file types are supported, namely:

.mol, .sdf - MDL V2000 and V3000 files
.xyz - XYZ files
.mae - Schrodinger Maestro files
.coord - Turbomole files
.pdb - PDB files

Parameters

path (str) – The path to a molecular structure file holding updated coordinates for the Molecule.
extension (Optional[str]) – If you want to treat the file as though it has a particular extension, put it here. Include the dot.

Return type

Molecule

Returns

A clone with atomic positions found in path.

write(path, atom_ids=None)[source]

Write the structure to a file.

This function will write the format based on the extension of path.

.mol, .sdf - MDL V3000 MOL file
.xyz - XYZ file
.pdb - PDB file

Parameters

path (str) – The path to which the molecule should be written.
atom_ids (Union[int, Iterable[int], None]) – The atom ids of atoms to write. Can be a single int, if a single atom is to be used, or None, if all atoms are to be used. If you use this parameter, the atom ids in the file may not correspond to the atom ids in the molecule.

Return type

Molecule

Returns

The molecule.