Geometry¶

This is the pydoc code for the geometry module.

# molli.chem.geometry

This submodule defines classes CartesianGeometry.

class molli.chem.geometry.DistanceUnit(value)¶

Bases: Enum

This is an Enumeration class for assigning commonly used distance units

Parameters:: Enum – Accepts integer enumerations for different distance units

Examples

>>> ml.DistanceUnit(1.0) == ml.DistanceUnit.A
True

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

Bases: Promolecule

Stores molecular geometry in ANGSTROM floating points. This version is generalizable to arbitrary coordinates and data types. This is a parent class that employs methods that work on a Promolecule

add_atom(a: Atom, coord: ArrayLike) → None¶

Adds atom to CartesianGeometry

Parameters:

a (Atom) – Atom to add
coord (ArrayLike) – Coordinates to add

Examples

The Molecule class inherits add_atom()

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.n_atoms
44
>>> new_atom = ml.Atom("C")
>>> dendrobine.add_atom(new_atom, [0,0,0])
>>> dendrobine.n_atoms
45

If desired, one can work directly with CartesianGeometry class instead

>>> cartgeom = ml.CartesianGeometry(dendrobine)
>>> cartgeom.add_atom(new_atom, [0,0,0])
>>> cargeom.n_atoms

new_atom(element: Element = Ellipsis, isotope: int = None, coord: ArrayLike = [0, 0, 0], **kwargs) → Atom¶

Adds a new atom and returns it

Parameters:

element (Element, optional) – Element of the atom, by default …
isotope (int, optional) – Isotope of the atom, by default None
coord (ArrayLike, optional) – Coordinates of the atom, by default [0, 0, 0]

Returns:

Returns Atom instance

Return type:

Atom

Examples

The Molecule class inherits new_atom()

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.n_atoms
44
>>> dendrobine.new_atom(element="C", isotope=None, coord=[0,0,0])
Atom(element=C, isotope=None, ...)
>>> dendrobine.n_atoms
45

If desired, one can work directly with CartesianGeometry class instead

>>> cartgeom = ml.CartesianGeometry(dendrobine)
>>> cartgeom.new_atom(element="C", isotope=None, coord=[0,0,0])
44
>>> cartgeom.new_atom(element="C", isotope=None, coord=[0,0,0])
Atom(element=C, isotope=None, ...)
>>> cartgeom.n_atoms
45

property coords: ndarray¶

returns: Coordinates of Geometry :rtype: np.ndarray

Examples

>>> geom = ml.CartesianGeometry()
>>> geom.add_atom(ml.Atom("C"), [0,0,0])
>>> geom.coords
array([[0., 0., 0.]])

property coords_as_list: List[float]¶

returns: Returns flattened coordinates of CartesianGeometry as a list :rtype: List[float]

Examples

>>> geom = ml.CartesianGeometry()
>>> geom.add_atom(ml.Atom("C"), [0,0,0])
>>> geom.coords_as_list
[0.0, 0.0, 0.0]

extend(other: Iterable[CartesianGeometry])¶

Currently Not Implemented

Parameters:: other (Iterable[CartesianGeometry]) – iterable to extend cartesiangeometry from other cartesian geometries

dump_xyz(output: StringIO, write_header: bool = True, *, fmt: str = '12.6f') → None¶

Dumps the xyz file into the output stream

Parameters:

output (StringIO) – Output stream
write_header (bool, optional) – Whether to write the header, by default True
fmt (str, optional) – Format of the string, by default “12.6f”

Examples

>>> geom = ml.CartesianGeometry()
>>> geom.add_atom(ml.Atom("C"), [0,0,0])
>>> with open('test.xyz', 'w') as f:
>>>     geom.dump_xyz(f)
1
unknown
C         0.000000     0.000000     0.000000

dumps_xyz(write_header: bool = True) → str¶

Dumps the xyz file into the output stream

Parameters:: write_header (bool, optional) – Whether to write the header, by default True
Returns:: The xyz block
Return type:: str

Examples

>>> geom = ml.CartesianGeometry()
>>> geom.add_atom(ml.Atom("C"), [0,0,0])
>>> geom.dumps_xyz()
1
unknown
C         0.000000     0.000000     0.000000

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

This function loads a single xyz file into the current instance. This can be a stream, filepath, or string.

Parameters:

cls (type[CartesianGeometry]) – The class to load the xyz file into
input (str | Path | IO) – XYZ file to be loaded
name (str, optional) – Name of the geometry, by default None
source_units (str, optional) – Units to use when reading, by default “Angstrom”

Returns:

Returns CartesianGeometry

Return type:

CartesianGeometry

Examples

The Molecule class inherits load_xyz()

>>> ml.Molecule.load_xyz(ml.files.dendrobine_xyz, name='dendrobine')
Molecule(name='dendrobine', formula='C16 H25 N1 O2')

If desired, one can work directly with CartesianGeometry class instead

>>> ml.CartesianGeometry.load_xyz(ml.files.dendrobine_xyz,
name='dendrobine')
CartesianGeometry(name='dendrobine', formula='C16 H25 N1 O2')

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

This function loads a single xyz file into the current instance. This can only be a string

Parameters:

cls (type[CartesianGeometry]) – The class to load the xyz file into
input (str) – XYZ block as a string
name (str, optional) – Name of the geometry, by default None
source_units (str, optional) – Units to use when reading, by default “Angstrom”

Returns:

Returns CartesianGeometry

Return type:

CartesianGeometry

Examples

The Molecule class inherits loads_xyz()

>>> with open(ml.files.dendrobine_xyz) as f:
>>>     ml.Molecule.loads_xyz(f.read(), name='dendrobine')
Molecule(name='dendrobine', formula='C16 H25 N1 O2')

If desired, one can work directly with CartesianGeometry class instead

>>> with open(ml.files.dendrobine_xyz) as f:
>>>     ml.CartesianGeometry.loads_xyz(f.read(), name='dendrobine')
CartesianGeometry(name='dendrobine', formula='C16 H25 N1 O2')

classmethod load_all_xyz(input: str | Path | IO, *, name: str = None, source_units: str = 'Angstrom') → List[CartesianGeometry]¶

This function loads all xyz files from the input

Parameters:

cls (type[CartesianGeometry]) – The class to load the xyz file into
input (str | Path | IO) – XYZ file to be loaded
name (str, optional) – Name of the geometry, by default None
source_units (str, optional) – Units to use when reading, by default “Angstrom”

Returns:

Returns list of cartesian geometries

Return type:

List[CartesianGeometry]

Examples

The Molecule class inherits load_all_xyz()

>>> ml.Molecule.load_all_xyz(ml.files.pentane_confs_xyz)
[Molecule(name='unnamed', formula='C5 H12'), ...]

If desired, one can work directly with CartesianGeometry class instead

>>> ml.CartesianGeometry.load_all_xyz(ml.files.pentane_confs_xyz)
[CartesianGeometry(name='unnamed', formula='C5 H12'), ...]

classmethod loads_all_xyz(input: str, *, name: str = None, source_units: str = 'Angstrom') → List[CartesianGeometry]¶

This function loads all xyz files from the input string

Parameters:

cls (type[CartesianGeometry]) – The class to load the xyz file into
input (str) – XYZ block as a string
name (str, optional) – Name of the geometry, by default None
source_units (str, optional) – Units to use when reading, by default “Angstrom”

Returns:

Returns list of cartesian geometries

Return type:

List[CartesianGeometry]

Examples

The Molecule class inherits loads_all_xyz()

>>> with open(ml.files.pentane_confs_xyz) as f:
>>>     ml.Molecule.loads_all_xyz(f.read())
[Molecule(name='dendrobine', formula='C16 H25 N1 O2'),...]

If desired, one can work directly with CartesianGeometry class instead

>>> with open(ml.files.pentane_confs_xyz) as f:
>>>     ml.CartesianGeometry.loads_all_xyz(f.read())
[CartesianGeometry(name='dendrobine', formula='C16 H25 N1 O2'),...]

classmethod yield_from_xyz(stream: StringIO, *, name: str = None, source_units: str = 'Angstrom') → Generator[CartesianGeometry, None, None]¶

Yields generator of CartesianGeometry from stream

Parameters:

cls (type[CartesianGeometry]) – The class to load the xyz file into
stream (StringIO) – Stream to read from
name (str, optional) – Name of the geometry, by default None
source_units (str, optional) – Units to use when reading, by default “Angstrom”

Yields:

Generator[CartesianGeometry, None, None] – Yields Generator of CartesianGeometry

Examples

The Molecule class inherits yield_from_xyz()

>>> with open(ml.files.dendrobine_xyz) as f:
>>>     ml.Molecule.yield_from_xyz(f, name='dendrobine')
<generator object CartesianGeometry.yield_from_xyz at ...>

If desired, one can work directly with CartesianGeometry class instead

>>> with open(ml.files.dendrobine_xyz) as f:
>>>     ml.CartesianGeometry.yield_from_xyz(f, name='dendrobine')
<generator object CartesianGeometry.yield_from_xyz at ...>

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

Multiplies all coordinates by a factor

Parameters:

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

Examples

The Molecule class inherits scale()

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.coords
array([[ 1.2960e+00 -2.3190e-01  1.2670e+00],...
>>> dendrobine.scale(0.5)
>>> dendrobine.coords
array([[ 6.48000e-01, -1.15950e-01,  6.33500e-01],...

If desired, one can work directly with CartesianGeometry class instead

>>> cartgeom = ml.CartesianGeometry(dendrobine)
>>> cartgeom.scale(0.5)
>>> cartgeom.coords
array([[ 6.48000e-01, -1.15950e-01,  6.33500e-01],...

invert() → None¶

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

Examples

The Molecule class inherits invert()

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

If desired, one can work directly with CartesianGeometry class instead

>>> cartgeom = ml.CartesianGeometry(dendrobine)
>>> cartgeom.invert()
>>> cartgeom.coords
array([[-1.2960e+00,  2.3190e-01, -1.2670e+00],

distance(a1: Atom | int | str | Element, a2: Atom | int | str | Element) → float¶

Calculates the distance between two atoms

Parameters:

a1 (AtomLike) – First atom
a2 (AtomLike) – Second atom

Returns:

Distance between the two atoms

Return type:

float

Examples

The Molecule class inherits distance()

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.distance(0,1)
1.520002194077364

If desired, one can work directly with CartesianGeometry class instead

>>> cartgeom = ml.CartesianGeometry(dendrobine)
>>> cartgeom.distance(0,1)
1.520002194077364

get_atom_coord(_a: Atom | int | str | Element) → ndarray¶

Returns the coordinates of the atom

Parameters:: _a (AtomLike) – Atom of interest
Returns:: Coordinates of the atom
Return type:: np.ndarray

Examples

The Molecule class inherits get_atom_coord()

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.get_atom_coord(0)
array([ 1.296 , -0.2319,  1.267 ])

If desired, one can work directly with CartesianGeometry class instead

>>> cartgeom = ml.CartesianGeometry(dendrobine)
>>> cartgeom.get_atom_coord(0,1)
array([ 1.296 , -0.2319,  1.267 ])

vector(a1: Atom | int | str | Element, a2: Atom | int | str | Element | ndarray) → ndarray¶

Returns the vector between two atoms or one atom and array

Parameters:

a1 (AtomLike) – First atom
a2 (AtomLike | np.ndarray) – Second atom or array

Returns:

Vector between the two atoms

Return type:

np.ndarray

Examples

The Molecule class inherits vector()

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.vector(0,1)
array([-1.2387,  0.2093,  0.8557])

If desired, one can work directly with CartesianGeometry class instead

>>> cartgeom = ml.CartesianGeometry(dendrobine)
>>> cartgeom.vector(0,1)
array([-1.2387,  0.2093,  0.8557])

distance_to_point(a: Atom | int | str | Element, p: ArrayLike) → float¶

Compute the distance between an atom and a point

Parameters:

a (AtomLike) – Atom of interest
p (ArrayLike) – Point of interest

Returns:

Distance between the atom and the point

Return type:

float

Examples

The Molecule class inherits distance_to_point()

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.distance_to_point(0,[0,0,0])
1.827206230834385

If desired, one can work directly with CartesianGeometry class instead

>>> cartgeom = ml.CartesianGeometry(dendrobine)
>>> cartgeom.distance_to_point(0,[0,0,0])
1.827206230834385

angle(a1: Atom | int | str | Element, a2: Atom | int | str | Element, a3: Atom | int | str | Element) → float¶

Compute an angle between three atoms in radians

Parameters:

a1 (AtomLike) – First atom
a2 (AtomLike) – Second atom
a3 (AtomLike) – Third atom

Returns:

Angle between the three atoms in radians

Return type:

float

Examples

The Molecule class inherits angle()

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.angle(0,1,2)
1.8082869758837117

If desired, one can work directly with CartesianGeometry class instead

>>> cartgeom = ml.CartesianGeometry(dendrobine)
>>> cartgeom.angle(0,1,2)
1.8082869758837117

coord_subset(atoms: Iterable[Atom | int | str | Element]) → ndarray¶

Returns the coordinates of a subset of atoms

Parameters:: atoms (Iterable[AtomLike]) – Subset of atoms
Returns:: Coordinates of the subset of atoms
Return type:: np.ndarray

Examples

The Molecule class inherits coord_subset()

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.coord_subset([0,1,2])
array([[ 1.296 , -0.2319,  1.267 ],
[ 0.0573, -0.0226,  2.1227],
[-1.0974, -0.4738,  1.2059]])

If desired, one can work directly with CartesianGeometry class instead

>>> cartgeom = ml.CartesianGeometry(dendrobine)
>>> cartgeom.coord_subset([0,1,2])
array([[ 1.296 , -0.2319,  1.267 ],
[ 0.0573, -0.0226,  2.1227],
[-1.0974, -0.4738,  1.2059]])

dihedral(a1: Atom | int | str | Element, a2: Atom | int | str | Element, a3: Atom | int | str | Element, a4: Atom | int | str | Element) → float¶

Compute the dihedral angle between four atoms in radians

Parameters:

a1 (AtomLike) – First atom
a2 (AtomLike) – Second atom
a3 (AtomLike) – Third atom
a4 (AtomLike) – Fourth atom

Returns:

Dihedral angle between the four atoms in radians

Return type:

float

Examples

The Molecule class inherits dihedral()

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.dihedral(0,1,2,3)
-0.3286236550063439

If desired, one can work directly with CartesianGeometry class instead

>>> cartgeom = ml.CartesianGeometry(dendrobine)
>>> cartgeom.dihedral(0,1,2,3)
-0.3286236550063439

translate(vector: ArrayLike) → None¶

Translates coordinates inplace

Parameters:: vector (ArrayLike) – Translation vector

Examples

The Molecule class inherits translate()

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.coords
array([[ 1.2960e+00, -2.3190e-01,  1.2670e+00],...
>>> dendrobine.translate([1,1,1])
>>> dendrobine.coords
array([[ 2.296 ,  0.7681,  2.267 ],...

If desired, one can work directly with CartesianGeometry class instead

>>> cartgeom = ml.CartesianGeometry(dendrobine)
>>> cartgeom.translate([1,1,1])
>>> cartgeom.coords
array([[ 2.296 ,  0.7681,  2.267 ],...

centroid() → ndarray¶

Centroid of the molecule

Returns:: Centroid of the molecule
Return type:: np.ndarray

Examples

The Molecule class inherits centroid()

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.centroid()
array([ 0.16483864, -0.16130455, -1.00852727])

If desired, one can work directly with CartesianGeometry class instead

>>> cartgeom = ml.CartesianGeometry(dendrobine)
>>> cartgeom.centroid()
array([ 0.16483864, -0.16130455, -1.00852727])

rmsd(other: CartesianGeometry, validate_elements=True)¶

Currently Not Implemented

Parameters:

other (CartesianGeometry) – Other CartesianGeometry for comparison
validate_elements (bool, optional) – Validates the elements between the two geometries are equal, by default True

transform(_t_matrix: ArrayLike, /, validate=False) → None¶

Transform the coordinates of the molecule

Parameters:

_t_matrix (ArrayLike) – Transformation matrix
validate (bool, optional) – Whether to validate the transformation matrix, by default False Currently Not Implemented

Examples

The Molecule class inherits transform()

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.coords
array([[ 1.2960e+00, -2.3190e-01,  1.2670e+00],...
>>> t_matrix = ml.math.rotation_matrix_from_axis([0,0,1],90)
>>> dendrobine.transform(t_matrix)
array([[-7.88021233e-01, -1.05471140e+00,  1.26700000e+00],...

If desired, one can work directly with CartesianGeometry class instead

>>> cartgeom = ml.CartesianGeometry(dendrobine)
>>> cartgeom.transform(t_matrix)
array([[-7.88021233e-01, -1.05471140e+00,  1.26700000e+00],...

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

Deletes an atom from the CartesianGeometry

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 CartesianGeometry class instead

>>> cartgeom = ml.CartesianGeometry(dendrobine)
>>> cartgeom.del_atom(0)
>>> cartgeom.get_atom(0)
Atom(element=C, isotope=None, label='C', formal_charge=0, formal_spin=0)