Structure

This is the pydoc code for the structure module.

# molli.chem.molecule This submodule defines the cornerstone of the diamond inheritance in molli: the Structure and Substructure classes

class molli.chem.structure.Structure(other: Structure = None, /, *, n_atoms: int = 0, name: str = None, coords: ArrayLike = None, copy_atoms: bool = False, charge: int = None, mult: int = None, **kwds)

Bases: CartesianGeometry, Connectivity

Combines the functionality of CartesianGeometry andd Connectivity ‘CartesianGeometry’ gives the molecular data structure features of a 3d coordinate matrix ‘Connectivity’ gives the molecular data structure features of an undirected graph

classmethod yield_from_mol2(input: str | StringIO, name: str = None, source_units: str = 'Angstrom') → Generator[Structure, None, None]

Yields generator of Structure from stream

Parameters:

  • cls (type[Structure]) – The class to load the mol2 file into

  • input (str | StringIO) – Stream to read from

  • name (str, optional) – Name of the Structure, by default None

  • source_units (str, optional) – Units to use when reading, by default “Angstrom”

Yields:

Generator[Structure, None, None] – Yields generator of Structure

Examples

The Molecule class inherits yield_from_mol2()
>>> with open(ml.files.dendrobine_mol2) as f:
>>>     ml.Molecule.yield_from_mol2(f, name='dendrobine')
<generator object Structure.yield_from_mol2 at ...>
If desired, one can work directly with Structure class instead
>>> with open(ml.files.dendrobine_mol2) as f:
>>>     ml.Structure.yield_from_mol2(f, name='dendrobine')
<generator object Structure.yield_from_mol2 at ...>
dump_mol2(stream: StringIO) → None

Dumps the mol2 block into the output stream

Parameters:

_stream (StringIO, optional) – Output stream, by default None

Examples

The Molecule class inherits dump_mol2()
>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> with open('dendrobine.mol2', 'w') as f:
>>>     dendrobine.dump_mol2(f)
# Produced with molli package
@<TRIPOS>MOLECULE
dendrobine
...
If desired, one can work directly with Structure class instead
>>> dendrobine = ml.Structure.load_mol2(ml.files.dendrobine_mol2)
>>> with open('dendrobine.mol2', 'w') as f:
>>>     dendrobine.dump_mol2(f)
# Produced with molli package
@<TRIPOS>MOLECULE
dendrobine
...
classmethod load_mol2(input: str | Path | IO, *, name: str = None, source_units: str = 'Angstrom') → Structure

_summary_

Parameters:

  • cls (type[Structure]) – Class to be loaded into

  • input (str | Path | IO) – File path, string, or stream

  • name (str, optional) – Name for Structure, by default None

  • source_units (str, optional) – Units to be used in loading, by default “Angstrom”

Returns:

Returns Structure

Return type:

Structure

Examples

The Molecule class inherits load_mol2()
>>> ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
Molecule(name='dendrobine', formula='C16 H25 N1 O2')
If desired, one can work directly with Structure class instead
>>> ml.Structure.load_mol2(ml.files.dendrobine_mol2)
Structure(name='dendrobine', formula='C16 H25 N1 O2')
classmethod loads_mol2(input: str, *, name: str = None, source_units: str = 'Angstrom') → Structure

Loads mol2 from a string

Parameters:

  • cls (type[Structure]) – Class to be loaded into

  • input (str) – Mol2 block as string

  • name (str, optional) – Name for Structure, by default None

  • source_units (str, optional) – Units to be used in loading, by default “Angstrom”

Returns:

Returns Structure

Return type:

Structure

Examples

The Molecule class inherits loads_mol2()
>>> with open(ml.files.dendrobine_mol2, 'r') as f:
>>>     ml.Molecule.loads_mol2(f.read())
Molecule(name='dendrobine', formula='C16 H25 N1 O2')
If desired, one can work directly with Structure class instead
>>> with open(ml.files.dendrobine_mol2, 'r') as f:
>>>     ml.Structure.loads_mol2(f.read())
Structure(name='dendrobine', formula='C16 H25 N1 O2')
classmethod load_all_mol2(input: str | Path | IO, *, name: str = None, source_units: str = 'Angstrom') → List[Structure]

This function loads all mol2 files from the input

Parameters:

  • cls (type[Structure]) – Class to be loaded into

  • input (str | Path | IO) – File path, string, or stream

  • name (str, optional) – Name for Structure, by default None

  • source_units (str, optional) – Units to be used in loading, by default “Angstrom”

Returns:

Returns list of Structures

Return type:

List[Structure]

Examples

The Molecule class inherits load_all_mol2()
>>> ml.Molecule.load_all_mol2(ml.files.pentane_confs_mol2)
[Molecule(name='pentane', formula='C5 H12'),...
If desired, one can work directly with Structure class instead
>>> ml.Structure.load_all_mol2(ml.files.pentane_confs_mol2)
[Structure(name='pentane', formula='C5 H12'),...
classmethod loads_all_mol2(input: str, *, name: str = None, source_units: str = 'Angstrom') → List[Structure]

This loads all mol2 files from the input string

Parameters:

  • cls (type[CartesianGeometry]) – Class to be loaded into

  • input (str) – Mol2 Block as a string

  • name (str, optional) – Name for Structure, by default None

  • source_units (str, optional) – Units to be used in loading, by default “Angstrom”

Returns:

Returns a list of Structures

Return type:

List[Structure]

Examples

The Molecule class inherits loads_all_mol2()
>>> with open(ml.files.pentane_confs_mol2, 'r') as f:
>>>     ml.Molecule.loads_all_mol2(f.read())
[Molecule(name='pentane', formula='C5 H12'),...
If desired, one can work directly with Structure class instead
>>> with open(ml.files.pentane_confs_mol2, 'r') as f:
>>>     ml.Structure.loads_all_mol2(f.read())
[Structure(name='pentane', formula='C5 H12'),...
dumps_mol2() → str

Dumps the mol2 block as a string

Returns:

The mol2 block

Return type:

str

Examples

The Molecule class inherits dumps_mol2()
>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.dumps_mol2()
# Produced with molli package
@<TRIPOS>MOLECULE
dendrobine
...
If desired, one can work directly with Structure class instead
>>> dendrobine = ml.Structure.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.dumps_mol2()
# Produced with molli package
@<TRIPOS>MOLECULE
dendrobine
...
classmethod join(struct1: Structure, struct2: Structure, _a1: Atom | int | str | Element, _a2: Atom | int | str | Element, *, dist: float = None, optimize_rotation: bool | int = False, name: str = None, charge: float = None, mult: float = None, btype: BondType = BondType.Single, bstereo: BondStereo = BondStereo.Unknown, bforder: float = 1.0) → Structure

This can be used to join two structures together at individual atoms

Parameters:

  • struct1 (Structure) – First structure

  • struct2 (Structure) – Second structure

  • _a1 (AtomLike) – First atom

  • _a2 (AtomLike) – Second atom

  • dist (float, optional) – Distance for two structures to be joined at, by default None

  • optimize_rotation (bool | int, optional) – Rotates structures if there is expected to be overlapping van der Waals radii, by default False

  • name (str, optional) – Name of the new structure, by default None

  • charge (float, optional) – Charge of the new structure, by default None

  • mult (float, optional) – Multiplicity of the new structure, by default None

  • btype (BondType, optional) – Type of bond formed, by default BondType.Single

  • bstereo (BondStereo, optional) – Geometry of bond formed, by default BondStereo.Unknown

  • bforder (float, optional) – Fractional order of bond formed, by default 1.0

Returns:

Returns a structure joined at the the atoms of interest

Return type:

Structure

Examples

The Molecule class inherits join()
>>> mol1 = ml.Molecule.load_mol2('mol1_w_attachment_point.mol2')
>>> ap1, = mol1.get_attachment_points()
>>> mol2 = ml.Molecule.load_mol2('mol1_w_attachment_point.mol2')
>>> ap2, = mol2.get_attachment_points()
>>> res = ml.Molecule.join(mol1, mol2, ap1, ap2, optimize_rotation=True)
If desired, one can work directly with Structure class instead
>>> mol1 = ml.Structure.load_mol2('mol1_w_attachment_point.mol2')
>>> ap1, = mol1.get_attachment_points()
>>> mol2 = ml.Structure.load_mol2('mol1_w_attachment_point.mol2')
>>> ap2, = mol2.get_attachment_points()
>>> res = ml.Structure.join(mol1, mol2, ap1, ap2, optimize_rotation=True)
classmethod concatenate(*structs: Structure) → Structure

Concatenates atom and bond tables of structures

Returns:

Returns concatenated structure

Return type:

Structure

Examples

The Molecule class inherits concatenate()
>>> mol1 = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> mol2 = ml.Molecule.load_mol2(ml.files.benzene_mol2)
>>> ml.Molecule.concatenate(mol1, mol2)
Molecule(name='unknown', formula='C22 H31 N1 O2')
If desired, one can work directly with Structure class instead
>>> mol1 = ml.Structure.load_mol2(ml.files.dendrobine_mol2)
>>> mol2 = ml.Structure.load_mol2(ml.files.benzene_mol2)
>>> ml.Structure.concatenate(mol1, mol2)
Structure(name='unknown', formula='C22 H31 N1 O2')
extend(other: Structure) → None

Currently Not Implemented

This extends current structure with the copied atoms, bonds and coordinates from another

Parameters:

other (Structure) – Structure to extend with

Raises:

NotImplementedError – _description_

substructure(atoms: Iterable[Atom | int | str | Element]) → Substructure

Creates a substructure from a subset of atoms

Parameters:

atoms (Iterable[AtomLike]) – Subset of atoms to create Substructure from

Returns:

Returns a Substructure from a parent Structure

Return type:

Substructure

Examples

The Molecule class inherits substructure()
>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.substructure([0,1,2])
Substructure(parent=Molecule(name='dendrobine', ...), atoms=[0,1,2])
If desired, one can work directly with Structure class instead
>>> dendrobine = ml.Structure.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.substructure([0,1,2])
Substructure(parent=Structure(name='dendrobine', ...), atoms=[0,1,2])
property heavy: Substructure

Returns a substructure containing only heavy atoms.

Returns:

The substructure containing only heavy atoms.

Return type:

Substructure

Examples

The Molecule class inherits heavy
>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.heavy
Substructure(parent=Molecule(name='dendrobine', ...), atoms=[0,1,...])
If desired, one can work directly with Structure class instead
>>> dendrobine = ml.Structure.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.heavy
Substructure(parent=Structure(name='dendrobine', ...), atoms=[0,1,...])
bond_length(b: Bond) → float

Returns the length of a bond.

Parameters:

b (Bond) – The bond to measure.

Returns:

The length of the bond.

Return type:

float

Examples

The Molecule class inherits bond_length()
>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> bond = dendrobine.get_bond(0)
>>> dendrobine.bond_length(bond)
1.0956031261364676
If desired, one can work directly with Structure class instead
>>> dendrobine = ml.Structure.load_mol2(ml.files.dendrobine_mol2)
>>> bond = dendrobine.get_bond(0)
>>> dendrobine.bond_length(bond)
1.0956031261364676
bond_vector(b: Bond) → ndarray

Returns the vector between the two atoms in a bond.

Parameters:

b (Bond) – The bond to measure.

Returns:

The vector between the two atoms in the bond.

Return type:

np.ndarray

Examples

The Molecule class inherits bond_vector()
>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> bond = dendrobine.get_bond(0)
>>> dendrobine.bond_vector(bond)
array([-0.6747, -0.6486,  0.5696])
If desired, one can work directly with Structure class instead
>>> dendrobine = ml.Structure.load_mol2(ml.files.dendrobine_mol2)
>>> bond = dendrobine.get_bond(0)
>>> dendrobine.bond_vector(bond)
array([-0.6747, -0.6486,  0.5696])
bond_coords(b: Bond) → tuple[ndarray]

Returns the coordinates of the two atoms in a bond.

Parameters:

b (Bond) – The bond to measure.

Returns:

The coordinates of the two atoms in the bond.

Return type:

tuple[np.ndarray]

Examples

The Molecule class inherits bond_coords()
>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> bond = dendrobine.get_bond(0)
>>> dendrobine.bond_coords(bond)
array([[ 1.0232, -0.452 , -5.421 ], [ 0.3485, -1.1006, -4.8514]])
If desired, one can work directly with Structure class instead
>>> dendrobine = ml.Structure.load_mol2(ml.files.dendrobine_mol2)
>>> bond = dendrobine.get_bond(0)
>>> dendrobine.bond_coords(bond)
array([[ 1.0232, -0.452 , -5.421 ], [ 0.3485, -1.1006, -4.8514]])
perceive_atom_properties(_a: Atom | int | str | Element) → None

Currently Not Implemented

This function analyzes atomic properties

Parameters:

_a (AtomLike) – This is the atom for analysis

perceive_bond_properties() → None

Currently Not Implemented

This function analyzes bond properties

rotate_dihedral(atoms: tuple[Atom | int | str | Element], target_angle: float)

This procedure rotates the substructure

remove_substituent(a1: Atom | int | str | Element, a2: Atom | int | str | Element, *, ap_label: str = None)

This removes the substituent from the

split(a1: Atom | int | str | Element, a2: Atom | int | str | Element, *, ap1_label: str = None, ap2_label: str = None)

This is a stub of the function that splits

del_atom(_a: Atom | int | str | Element)

Deletes an atom from the Structure

Parameters:

_a (AtomLike) – An atom, index, label, or Element. This will only delete the first instance of the label or Element found

Examples

The Molecule class inherits del_atom()
>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.get_atom(0)
Atom(element=N, isotope=None, label='N', formal_charge=0, formal_spin=0)
>>> dendrobine.del_atom(0)
>>> dendrobine.get_atom(0)
Atom(element=C, isotope=None, label='C', formal_charge=0, formal_spin=0)
If desired, one can work directly with Structure class instead
>>> Structure = ml.Structure(dendrobine)
>>> Structure.del_atom(0)
>>> Structure.get_atom(0)
Atom(element=C, isotope=None, label='C', formal_charge=0, formal_spin=0)
add_implicit_hydrogens(*atoms: Atom | int | str | Element) → None

This function adds implicit hydrogens to all specified atoms. By default, it will add implicit hydrogens to all atoms if necessary.

Examples

The Molecule class inherits add_implicit_hydrogens()
>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.n_atoms
44
>>> dendrobine.add_implicit_hydrogens()
>>> dendrobine.n_atoms
44
If desired, one can work directly with Structure class instead
>>> dendrobine = ml.Structure.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.n_atoms
44
>>> dendrobine.add_implicit_hydrogens()
>>> dendrobine.n_atoms
44
class molli.chem.structure.Substructure(parent: Structure, atoms: Iterable[Atom | int | str | Element])

Bases: Structure

This class represents a substructure of a structure. It pulls the atoms and bonds from the parent structure, and allows for manipulation of the a subset of atoms within the initial structure.

yield_parent_atom_indices(atoms: Iterable[Atom | int | str | Element]) → Generator[int, None, None]

This function yields the indices of the atoms in the parent structure.

Parameters:

atoms (Iterable[AtomLike]) – The atoms to yield the indices of.

Yields:

Generator[int, None, None] – The indices of the atoms in the parent structure.

Examples

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.heavy
Substructure(parent=Molecule(name='dendrobine', ...), atoms=[0,1,...])
>>> substruc.yield_parent_atom_indices(struc.yield_atoms_by_element("H"))
<generator object Substructure.yield_parent_atom_indices at ...>
property parent_atom_indices: list[int]

Returns the indices of the atoms in the parent structure.

Returns:

The indices of the atoms in the parent structure.

Return type:

list[int]

Examples

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.heavy
Substructure(parent=Molecule(name='dendrobine', ...), atoms=[0,1,...])
>>> substruc.parent_atom_indices
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 20, 21, 22]
property coords: ndarray

Returns the coordinates of the atoms in the substructure.

Returns:

The coordinates of the atoms in the substructure.

Return type:

np.ndarray

Examples

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.coords
(44,3)
>>> dendrobine.heavy.coords
array([[ 1.2960e+00, -2.3190e-01,  1.2670e+00],...
>>> dendrobine.heavy.coords.shape
(19,3)