Atom¶

This is the pydoc code for the atom module.

# molli.chem.atom

This submodule defines classes Element, Atom, Promolecule.

class molli.chem.atom.Element(value)¶

Bases: IntEnum

The Element class is an Enumeration class used for calling elements in the periodic table

Parameters:: IntEnum – A parameter that accepts an integer enumeration from 0-118, with 0 being defined as an “Unknown” element

classmethod get(elt: Element | str | int) → Element¶

Class method that used to instantiate Molli Elements

Parameters:

elt (ElementLike | int | str) –

‘int’ will be interpreted as atomic number (used as callable)
’str’ will be interpreted as element name (retrieved with indexing)

Return type:

Element

Examples

>>> o = ml.Element(8) # Oxygen
>>> f = ml.Element["F"] # Fluorine
>>> f == ml.Element.F # True

property symbol: str¶

returns: A string representing the symbol of the element :rtype: str

Examples

>>> ml.Element.C.symbol
'C'

property z: int¶

returns: An integer representing the atomic number of the element :rtype: int

Examples

>>> ml.Element.C.z
6

get_property_value(property_name: str) → int | str | float¶

Retrieves desired property value from dictionary key

Parameters:: str – Name of the property to be retrieved
Returns:: property_value – Value of the Property
Return type:: int | str | float

property atomic_weight: float¶

returns: Atomic weight of the element :rtype: float

Examples

>>> ml.Element["C"].atomic_weight
12.011

property cov_radius_1: float¶

returns: Represents the covalent radius of a single bond (based on DOI: 10.1021/jp5065819) :rtype: float

Examples

>>> ml.Element["Pb"].cov_radius_1
1.44

property cov_radius_2: float¶

Currently Not Implemented

Returns:: A float representing the covalent radius of a double bond
Return type:: float

property cov_radius_3: float¶

Currently Not Implemented

Returns:: A float representing the covalent radius of a triple bond
Return type:: float

property cov_radius_grimme: float¶

This is the same definition of covalent radii; however, any metal element has been scaled down by 10% to allow for use with grimme’s implementation of dftd-coordination number. (See DOI: 10.1063/1.3382344)

Returns:: Represents the covalent radius of a single bond by the Grimme Definition
Return type:: float

Examples

>>> ml.Element["Pb"].cov_radius_grimme
1.3

property vdw_radius: float¶

returns: The Bondi Van der Waals radius in Angstroms (based on DOIs: 10.1021/jp8111556 , 10.1021/j100785a001 :rtype: float

Examples

>>> ml.Element["Pb"].vdw_radius
2.02

property en_pauling: float¶

Currently Not Implemented

Returns:: Represents the element’s Pauling electronegativity
Return type:: float

property color_cpk: str¶

returns: Hex color code based on the CPK color scheme :rtype: str

Examples

>>> ml.Element["F"].color_cpk
'#daa520'

property group: int¶

returns: Group number from the periodic table :rtype: int

Examples

>>> ml.Element["He"].group
18

molli.chem.atom.ElementLike = molli.chem.atom.Element | str | int¶

A type alias for anything that can be resolved as an element

str is interpreted as element symbol

int is interpreted as atomic number

molli.chem.atom.IMPLICIT_VALENCE = {1: 1, 2: 2, 3: 0, 4: 0, 5: 0, 6: 0, 7: 0, 8: 0, 9: 0, 10: 0, 11: 0, 12: 0, 13: 3, 14: 4, 15: 3, 16: 2, 17: 1, 18: 0}¶: This is the expected number of bonds for main group elements

class molli.chem.atom.AtomType(value)¶

Bases: IntEnum

The AtomType class is an Enumeration class for assigning atom types

Parameters:: IntEnum – Accepts integer enumerations for different atom types

Examples

>>> ml.AtomType(2) == ml.AtomType.Aromatic
True

class molli.chem.atom.AtomStereo(value)¶

Bases: IntEnum

The AtomStereo class is an Enumeration class used for stereogenic atom assignment

Parameters:: IntEnum – Accepts integer enumerations for different stereogenic assignments

Examples

>>> ml.AtomStereo(10) == ml.AtomStereo.R
True

class molli.chem.atom.AtomGeom(value)¶

Bases: IntEnum

The AtomGeom class is an Enumeration class for assigning atom geometries

Parameters:: IntEnum – Accepts integer enumerations for different atom geometries

Examples

>>> ml.AtomGeom(21) == ml.AtomGeom.R2_Linear
True

class molli.chem.atom.Atom(element: Element | str | int = Unknown, isotope: int = None, label: str = None, atype: AtomType = AtomType.Regular, stereo: AtomStereo = AtomStereo.Unknown, geom: AtomGeom = AtomGeom.Unknown, formal_charge: int = 0, formal_spin: int = 0, attrib: dict = NOTHING, parent=None)¶

Bases: object

The Atom class is the most fundamental class a molecule can have

evolve(**changes) → Atom¶

Evolves the atom into a new atom with the changes specified

Atom
A new Atom instance with the changes specified

Examples

>>> my_atom = ml.Atom(element = 'C', atype = ml.AtomType.Regular)
>>> new_atom = my_atom.evolve(atype = ml.AtomType.Aromatic)
>>> new_atom.atype
<AtomType.Aromatic: 2>

as_dict(schema: List[str] = None) → dict¶

Returns the atom as a dictionary

Parameters:: schema (List[str], optional) – Can be used to specify if only certain properties are desired, by default None
Returns:: This dictionary contains properties of the associated atom
Return type:: dict

Examples

>>> ml.Atom(element='C').as_dict()
{'element': C, 'isotope': None, ...}
>>> ml.Atom(element='C').as_dict(['element','label','attrib'])
{'element': C, 'label': None, 'attrib': {}}

as_tuple(schema: List[str] = None) → tuple¶

Returns the atom as a tuple

Parameters:: schema (List[str], optional) – Can be used to specify if only certain properties are desired, by default None
Returns:: This tuple contains properties of the associated atom
Return type:: tuple

Examples

>>> ml.Atom(element='C').as_tuple()
{C, None, ...}
>>> ml.Atom(element='C').as_tuple(['element','label','attrib'])
{C, None, {}}

property is_dummy: bool¶

Checks if the atom type is Unknown or a Dummy

Returns:: Returns True if a Dummy atom
Return type:: bool

Examples

>>> a = ml.Atom(element='Unknown', atype=ml.AtomType.Dummy)
>>> a.is_dummy
True

property is_attachment_point: bool¶

Checks if the atom is an attachment point

Returns:: Returns True if an attachment point
Return type:: bool

Examples

>>> a = ml.Atom(element='Unknown', atype=ml.AtomType.AttachmentPoint)
>>> a.is_attachment_point
True

property idx: int | None¶

Returns the index of the atom if associated with a Molecule

Returns:: Represents the index of the atom
Return type:: int | None

Examples

The index is undefined with no parent molecule

>>> a = ml.Atom(element='C')
>>> a.idx
None

The index is defined with dendrobine as the parent molecule

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.add_atom(a, coord=[0,0,0])
>>> a.idx
44 #

property implicit_valence: int¶

returns: Integer based on the implicit valence :rtype: int

Examples

>>> ml.Atom(element='C').implicit_valence
4

property Z: int¶

returns: Returns an integer representing the atomic number of the element :rtype: int

Examples

>>> ml.Atom(element='C').Z
6

property atomic_weight: float¶

returns: Atomic weight of the element :rtype: float

Examples

>>> ml.Atom(element='C').atomic_weight
12.011

property vdw_radius: float¶

returns: The Bondi Van der Waals radius in Angstroms (based on DOIs: 10.1021/jp8111556 , 10.1021/j100785a001 :rtype: float

Examples

>>> ml.Atom(element='Pb').vdw_radius
2.02

property cov_radius_1: float¶

returns: Represents the covalent radius of a single bond (based on DOI: 10.1021/jp5065819) :rtype: float

Examples

>>> ml.Element["Pb"].cov_radius_1
1.44

property cov_radius_2: float¶

Currently Not Implemented

Returns:: A float representing the covalent radius of a double bond
Return type:: float

property cov_radius_3: float¶

Currently Not Implemented

Returns:: A float representing the covalent radius of a triple bond
Return type:: float

property cov_radius_grimme: float¶

Returns:: Represents the covalent radius of a single bond by the Grimme Definition
Return type:: float

Examples

>>> ml.Atom(element='Pb').cov_radius_grimme
1.3

property color_cpk: str¶

returns: Hex color code based on the CPK color scheme :rtype: str

Examples

>>> ml.Atom(element='F').color_cpk
'#daa520'

property valence_electrons: int¶: Returns the number of valence electrons

get_mol2_type() → str¶

Used to return the Sybyl Mol2 Type of an atom

Returns:: Returns the Sybyl Mol2 type of an atom
Return type:: str

Examples

>>> unknown_molli_atom.get_mol2_type()
>>> 'C.1' # Indicates it was ml.AtomType.MainGroup_sp

molli.chem.atom.AtomLike = molli.chem.atom.Atom | int | str | molli.chem.atom.Element¶: AtomLike can be an atom, its index, string, or element

class molli.chem.atom.Promolecule(other: Promolecule | Iterable[Atom] | Iterable[Element | str | int] = None, /, *, n_atoms: int = 0, name: str = None, copy_atoms: bool = False, charge: int = None, mult: int = None, attrib: dict = None, **kwds)¶

Bases: object

This is a parent class that only employs methods that work on a list of disconnected atoms with no structure or geometry assigned to them. Any class that adds functionality on top of atom list should inherit this class for API compatibility reasons.

property attachment_points: List[Atom]¶

returns: Returns a list of atoms whose AtomType is an AttachmentPoint :rtype: List[Atom]

Examples

The Molecule class inherits attachment_points

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.attachment_points
[] #There are no attachment points in the dendrobine file

If desired, one can work directly with Promolecule class instead

>>> promol = ml.Promolecule(dendrobine)
>>> promol.attachment_points
[] #There are no attachment points in the dendrobine file

property n_attachment_points: int¶

returns: Returns the number of atoms whose AtomType is an AttachmentPoint :rtype: int

Examples

The Molecule class inherits n_attachment_points

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.n_attachment_points
0 #There are no attachment points in the dendrobine file

If desired, one can work directly with Promolecule class instead

>>> promol = ml.Promolecule(dendrobine)
>>> promol.n_attachment_points
0 #There are no attachment points in the dendrobine file

property name: str¶

returns: Returns the name of the Promolecule :rtype: str

Examples

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> promol = ml.Promolecule(dendrobine)
>>> promol.name
dendrobine

property atoms: List[Atom]¶

returns: Returns an ordered list of the atoms in the Promolecule instance :rtype: List[Atom]

Examples

The Molecule class inherits atoms

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.atoms
[Atom(element=N, ...),Atom(element=C, ...), ...]

If desired, one can work directly with Promolecule class instead

>>> promol = ml.Promolecule(dendrobine)
>>> promol.atoms
[Atom(element=N, ...),Atom(element=C, ...), ...]

property elements: List[Element]¶

returns: Returns an ordered list of the elements in the Promolecule instance :rtype: List[Element]

Examples

The Molecule class inherits elements

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.elements
[N, C, C, C, C, ...]

If desired, one can work directly with Promolecule class instead

>>> promol = ml.Promolecule(dendrobine)
>>> promol.elements
[N, C, C, C, C, ...]

property n_atoms: int¶

returns: Returns the total number of atoms in the Promolecule instance :rtype: int

Examples

The Molecule class inherits n_atoms

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.n_atoms
44

If desired, one can work directly with Promolecule class instead

>>> promol = ml.Promolecule(dendrobine)
>>> promol.n_atoms
44

get_atom(_a: Atom | int | str | Element) → Atom¶

Fetches an atom from the Promolecule instance

Parameters:: _a (AtomLike) – An Atom, index, label, or Element. This will only return the first instance of the label or Element found.
Returns:: Returns the Atom instance
Return type:: Atom

Examples

The Molecule class inherits get_atom()

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.get_atom(10)
Atom(element=O, isotope=None, label='O', formal_charge=0, formal_spin=0)

If desired, one can work directly with Promolecule class instead

>>> promol = ml.Promolecule(dendrobine)
>>> promol.get_atom(10)
Atom(element=O, isotope=None, label='O', formal_charge=0, formal_spin=0)

get_atoms(*_atoms: Atom | int | str | Element) → tuple[Atom]¶

Fetches a tuple of Atoms from the Promolecule instance

Returns:: Returns a Tuple of Atoms
Return type:: tuple[Atom]

Examples

The Molecule class inherits get_atoms()

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.get_atoms(0,1,2)
(Atom(element=N,...),Atom(element=C,...),Atom(element=C,...))

Here is an example of getting atoms by element

>>> dendrobine.get_atoms(*dendrobine.yield_atoms_by_element("H"))
(Atom(element=H,...),Atom(element=H,...),Atom(element=H,...), ...)

If desired, one can work directly with Promolecule class instead

>>> promol = ml.Promolecule(dendrobine)
>>> promol.get_atoms(0,1,2)
(Atom(element=N,...),Atom(element=C,...),Atom(element=C,...))

Here is an example of getting atoms by element

>>> promol.get_atoms(*promol.yield_atoms_by_element("H"))
(Atom(element=H,...),Atom(element=H,...),Atom(element=H,...), ...)

get_atom_index(_a: Atom | int | str | Element) → int¶

Fetches the atom index from the promolecule

Parameters:: _a (AtomLike) – An atom, index, label, or Element. This will only return the first instance of the label or Element found.
Returns:: Returns the index of the atom
Return type:: int

Examples

The Molecule class inherits get_atom_index()

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.get_atom_index("N")
0

If desired, one can work directly with Promolecule class instead

>>> promol = ml.Promolecule(dendrobine)
>>> promol.get_atom_index("N")
0

get_atom_indices(*_atoms: Atom | int | str | Element) → tuple[int]¶

Fetches a tuple of indices from the Promolecule

Returns:: Returns a tuple of indices
Return type:: tuple[int]

Examples

The Molecule class inherits get_atom_indices()

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.get_atom_indices(*dendrobine.yield_atoms_by_element("H"))
(16, 17, 18, 19, 23, 24, 25, ...)

If desired, one can work directly with Promolecule class instead

>>> promol = ml.Promolecule(dendrobine)
>>> promol.get_atom_indices(*promol.yield_atoms_by_element("H"))
(16, 17, 18, 19, 23, 24, 25, ...)

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

Deletes an atom from the promolecule

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

>>> promol = ml.Promolecule(dendrobine)
>>> promol.del_atom(0)
Atom(element=C, isotope=None, label='C', formal_charge=0, formal_spin=0)

append_atom(a: Atom) → None¶

Appends an atom to the Promolecule instance

Parameters:: a (Atom) – An atom instance to be added

Examples

The Molecule class inherits append_atom()

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> new_atom = ml.Atom(element='H')
>>> dendrobine.append_atom(new_atom)
>>> dendrobine.get_atom(new_atom)
Atom(element=H, isotope=None, label=None, formal_charge=0, formal_spin=0)

If desired, one can work directly with Promolecule class instead

>>> promol = ml.Promolecule(dendrobine)
>>> promol.append_atom(new_atom)
Atom(element=H, isotope=None, label=None, formal_charge=0, formal_spin=0)

index_atom(_a: Atom) → int¶

Fetches the atom index from the Promolecule Instance

Parameters:: _a (Atom) – Must be an atom in the Promolecule instance list rather than AtomLike
Returns:: Returns the index of the atom
Return type:: int

Examples

The Molecule class inherits index_atom()

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> atom = dendrobine.get_atom("N")
>>> dendrobine.index_atom(atom)
0

If desired, one can work directly with Promolecule class instead

>>> promol = ml.Promolecule(dendrobine)
>>> promol.index_atom(atom)
0

yield_atoms_by_element(elt: Element | str | int) → Generator[Atom, None, None]¶

Yields atoms based on their element

Parameters:: elt (ElementLike) – An element, integer, or float
Yields:: Generator[Atom, None, None] – Yields generator of Atom instances

Examples

The Molecule class inherits yield_atoms_by_element()

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> generator = dendrobine.yield_atoms_by_element("H")
<generator object Promolecule.yield_atoms_by_element at ...>

If desired, one can work directly with Promolecule class instead

>>> promol = ml.Promolecule(dendrobine)
>>> generator = promol.yield_atoms_by_element("H")
<generator object Promolecule.yield_atoms_by_element at ...>

yield_attachment_points() → Generator[Atom, None, None]¶

Yields atoms that are attachment points

Yields:: Generator[Atom, None, None] – Yields generator of Atom instances that are attachment points

Examples

The Molecule class inherits yield_attachment_points()

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> generator = dendrobine.yield_attachment_points()
<generator object Promolecule.yield_attachment_points at ...>

If desired, one can work directly with Promolecule class instead

>>> promol = ml.Promolecule(dendrobine)
>>> generator = promol.yield_attachment_points()
<generator object Promolecule.yield_attachment_points at ...>

get_attachment_points() → tuple[Atom]¶

Gets tuple of atoms that are attachment points

Returns:: Returns tuple of atoms that are attachment points
Return type:: tuple[Atom]

Examples

The Molecule class inherits get_attachment_points()

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> generator = dendrobine.get_attachment_points()
() #Dendrobine does not have attachment points

If desired, one can work directly with Promolecule class instead

>>> promol = ml.Promolecule(dendrobine)
>>> generator = promol.get_attachment_points()
() #Dendrobine does not have attachment points

yield_atoms_by_label(lbl: str) → Generator[Atom, None, None]¶

Yields atoms based on their labels

Parameters:: lbl (str) – A string representing a label
Yields:: Generator[Atom, None, None] – Yields a generator of Atom instances

Examples

The Molecule class inherits yield_atoms_by_element()

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> generator = dendrobine.yield_atoms_by_label("H")
<generator object Promolecule.yield_atoms_by_label at ...>

If desired, one can work directly with Promolecule class instead

>>> promol = ml.Promolecule(dendrobine)
>>> generator = promol.yield_atoms_by_label("H")
<generator object Promolecule.yield_atoms_by_label at ...>

property formula: str¶

returns: A String representing the molecular formula of the Promolecule :rtype: str

Examples

The Molecule class inherits formula

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.formula
C16 H25 N1 O2

If desired, one can work directly with Promolecule class instead

>>> promol = ml.Promolecule(dendrobine)
>>> promol.formula
C16 H25 N1 O2

property molecular_weight: float¶

Molecular weight of the molecule

Warning: currently there is no support for isotopic masses.

Returns:: Returns float representing the molecular weight
Return type:: float

Examples

The Molecule class inherits molecular_weight

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.molecular_weight
263.381

If desired, one can work directly with Promolecule class instead

>>> promol = ml.Promolecule(dendrobine)
>>> promol.molecular_weight
263.381

label_atoms(template: str = '{e}{n0}')¶

Allows for unique labeling scheme of atoms in the Promolecule instance

Parameters:

template (str, optional) –

String template for labeling scheme, by default “{e}{n0}”:

’e’ = element, ‘n0’ = atom number (begin with 0),

Examples

The Molecule class inherits label_atoms()

>>> dendrobine = ml.Molecule.load_mol2(ml.files.dendrobine_mol2)
>>> dendrobine.label_atoms('{e}{n1}')
>>> dendrobine.atoms
[Atom(...,label='N1'), Atom(...,label='C2'), Atom(...,label='C3')]

If desired, one can work directly with Promolecule class instead

>>> promol = ml.Promolecule(dendrobine)
>>> promol.label_atoms('{e}{n1}')
>>> promol.atoms
[Atom(...,label='N1'), Atom(...,label='C2'), Atom(...,label='C3')]

molli.chem.atom.PromoleculeLike¶

PromoleculeLike can be a Promolecule, or an iterable of atoms or elements.

alias of Promolecule | Iterable[Atom | Element | str | int]