# rmgpy.molecule.Molecule¶

class rmgpy.molecule.Molecule(atoms=None, symmetry=-1, multiplicity=-187, props=None, SMILES='')

A representation of a molecular structure using a graph data type, extending the Graph class. The atoms and bonds attributes are aliases for the vertices and edges attributes. Other attributes are:

Attribute Type Description
symmetryNumber int The (estimated) external + internal symmetry number of the molecule
multiplicity int The multiplicity of this species, multiplicity = 2*total_spin+1
props dict A list of properties describing the state of the molecule.

A new molecule object can be easily instantiated by passing the SMILES or InChI string representing the molecular structure.

InChI

InChI: str

addAtom(self, Atom atom)

Add an atom to the graph. The atom is initialized with no bonds.

addBond(self, Bond bond)

Add a bond to the graph as an edge connecting the two atoms atom1 and atom2.

addEdge(self, Edge edge) → Edge

Add an edge to the graph. The two vertices in the edge must already exist in the graph, or a ValueError is raised.

addVertex(self, Vertex vertex) → Vertex

Add a vertex to the graph. The vertex is initialized with no edges.

assignAtomIDs(self)

Assigns an index to every atom in the molecule for tracking purposes. Uses entire range of cython’s integer values to reduce chance of duplicates

atomIDValid(self) → bool

Checks to see if the atom IDs are valid in this structure

atoms

Molecule.__getAtoms(self)

calculateCp0(self) → double

Return the value of the heat capacity at zero temperature in J/mol*K.

calculateCpInf(self) → double

Return the value of the heat capacity at infinite temperature in J/mol*K.

calculateSymmetryNumber(self) → int

Return the symmetry number for the structure. The symmetry number includes both external and internal modes.

clearLabeledAtoms(self)

Remove the labels from all atoms in the molecule.

connectTheDots(self)

Delete all bonds, and set them again based on the Atoms’ coords. Does not detect bond type.

containsLabeledAtom(self, str label) → bool

Return True if the molecule contains an atom with the label label and False otherwise.

copy(self, bool deep=False) → Graph

Create a copy of the current graph. If deep is True, a deep copy is made: copies of the vertices and edges are used in the new graph. If deep is False or not specified, a shallow copy is made: the original vertices and edges are used in the new graph.

copyAndMap(self) → dict

Create a deep copy of the current graph, and return the dict ‘mapping’. Method was modified from Graph.copy() method

countInternalRotors(self) → int

Determine the number of internal rotors in the structure. Any single bond not in a cycle and between two atoms that also have other bonds are considered to be internal rotors.

deleteHydrogens(self)

Irreversibly delete all non-labeled hydrogens without updating connectivity values. If there’s nothing but hydrogens, it does nothing. It destroys information; be careful with it.

draw(self, str path)

Generate a pictorial representation of the chemical graph using the draw module. Use path to specify the file to save the generated image to; the image type is automatically determined by extension. Valid extensions are .png, .svg, .pdf, and .ps; of these, the first is a raster format and the remainder are vector formats.

findIsomorphism(self, Graph other, dict initialMap=None) → list

Returns True if other is isomorphic and False otherwise, and the matching mapping. The initialMap attribute can be used to specify a required mapping from self to other (i.e. the atoms of self are the keys, while the atoms of other are the values). The returned mapping also uses the atoms of self for the keys and the atoms of other for the values. The other parameter must be a Molecule object, or a TypeError is raised.

findSubgraphIsomorphisms(self, Graph other, dict initialMap=None) → list

Returns True if other is subgraph isomorphic and False otherwise. Also returns the lists all of valid mappings. The initialMap attribute can be used to specify a required mapping from self to other (i.e. the atoms of self are the keys, while the atoms of other are the values). The returned mappings also use the atoms of self for the keys and the atoms of other for the values. The other parameter must be a Group object, or a TypeError is raised.

fromAdjacencyList(self, str adjlist, bool saturateH=False)

Convert a string adjacency list adjlist to a molecular structure. Skips the first line (assuming it’s a label) unless withLabel is False.

fromAugmentedInChI(self, aug_inchi)

Convert an Augmented InChI string aug_inchi to a molecular structure.

fromInChI(self, str inchistr, backend='try-all')

Convert an InChI string inchistr to a molecular structure.

fromSMARTS(self, smartsstr)

Convert a SMARTS string smartsstr to a molecular structure. Uses RDKit to perform the conversion. This Kekulizes everything, removing all aromatic atom types.

fromSMILES(self, str smilesstr, backend='try-all')

Convert a SMILES string smilesstr to a molecular structure.

fromXYZ(self, ndarray atomicNums, ndarray coordinates)

Create an RMG molecule from a list of coordinates and a corresponding list of atomic numbers. These are typically received from CCLib and the molecule is sent to ConnectTheDots so will only contain single bonds.

generateResonanceIsomers(self, bool keepIsomorphic=False) → list
getAllCycles(self, Vertex startingVertex) → list

Given a starting vertex, returns a list of all the cycles containing that vertex.

This function returns a duplicate of each cycle because [0,1,2,3] is counted as separate from [0,3,2,1]

getAllCyclesOfSize(self, int size) → list

Return a list of the all non-duplicate rings with length ‘size’. The algorithm implements was adapted from a description by Fan, Panaye, Doucet, and Barbu (doi: 10.1021/ci00015a002)

B. T. Fan, A. Panaye, J. P. Doucet, and A. Barbu. “Ring Perception: A New Algorithm for Directly Finding the Smallest Set of Smallest Rings from a Connection Table.” J. Chem. Inf. Comput. Sci. 33, p. 657-662 (1993).

getAllCyclicVertices(self) → list

Returns all vertices belonging to one or more cycles.

getAllPolycyclicVertices(self) → list

Return all vertices belonging to two or more cycles, fused or spirocyclic.

getAllSimpleCyclesOfSize(self, int size) → list

Return a list of all non-duplicate monocyclic rings with length ‘size’.

Naive approach by eliminating polycyclic rings that are returned by getAllCyclicsOfSize.

getAromaticRings(self, list rings=None) → tuple

Returns all aromatic rings as a list of atoms and a list of bonds.

Identifies rings using Graph.getSmallestSetOfSmallestRings(), then uses RDKit to perceive aromaticity. RDKit uses an atom-based pi-electron counting algorithm to check aromaticity based on Huckel’s Rule. Therefore, this method identifies “true” aromaticity, rather than simply the RMG bond type.

The method currently restricts aromaticity to six-membered carbon-only rings. This is a limitation imposed by RMG, and not by RDKit.

getBond(self, Atom atom1, Atom atom2) → Bond

Returns the bond connecting atoms atom1 and atom2.

getBonds(self, Atom atom) → dict

Return a dictionary of the bonds involving the specified atom.

getDeterministicSmallestSetOfSmallestRings(self) → list

Modified Graph method getSmallestSetOfSmallestRings by sorting calculated cycles by short lenth and then high atomic number instead of just short length (for cases where multiple cycles with same length are found, getSmallestSetOfSmallestRings outputs non-determinstically ).

For instance, molecule with this SMILES: C1CC2C3CSC(CO3)C2C1, will have non-deterministic output from getSmallestSetOfSmallestRings, which leads to non-deterministic bycyclic decomposition Using this new method can effectively prevent this situation.

getDisparateRings(self) → tuple

Return a list of distinct polycyclic and monocyclic rings within the graph. There is some code duplication in this function in order to maximize speed up so as to call self.getSmallestSetOfSmallestRings() only once.

Returns: monocyclicRingsList, polycyclicRingsList

getEdge(self, Vertex vertex1, Vertex vertex2) → Edge

Returns the edge connecting vertices vertex1 and vertex2.

getEdges(self, Vertex vertex) → dict

Return a dictionary of the edges involving the specified vertex.

getFingerprint(self) → str

Return a string containing the “fingerprint” used to accelerate graph isomorphism comparisons with other molecules. The fingerprint is a short string containing a summary of selected information about the molecule. Two fingerprint strings matching is a necessary (but not sufficient) condition for the associated molecules to be isomorphic.

getFormula(self) → str

Return the molecular formula for the molecule.

getLabeledAtom(self, str label) → Atom

Return the atoms in the molecule that are labeled.

getLabeledAtoms(self) → dict

Return the labeled atoms as a dict with the keys being the labels and the values the atoms themselves. If two or more atoms have the same label, the value is converted to a list of these atoms.

getLargestRing(self, Vertex vertex) → list

returns the largest ring containing vertex. This is typically useful for finding the longest path in a polycyclic ring, since the polycyclic rings returned from getPolycyclicRings are not necessarily in order in the ring structure.

getMolecularWeight(self) → double

Return the molecular weight of the molecule in kg/mol.

getMonocyclicRings(self) → list

Return a list of cycles that are monocyclic.

getNetCharge(self)

Iterate through the atoms in the structure and calculate the net charge on the overall molecule.

getNthNeighbor(self, startingAtoms, distanceList, ignoreList=None, n=1)

Recursively get the Nth nonHydrogen neighbors of the startingAtoms, and return them in a list. startingAtoms is a list of :class:Atom for which we will get the nth neighbor. distanceList is a list of intergers, corresponding to the desired neighbor distances. ignoreList is a list of :class:Atom that have been counted in (n-1)th neighbor, and will not be returned. n is an interger, corresponding to the distance to be calculated in the current iteration.

getNumAtoms(self, str element=None) → int

Return the number of atoms in molecule. If element is given, ie. “H” or “C”, the number of atoms of that element is returned.

getPolycyclicRings(self) → list

Return a list of cycles that are polycyclic. In other words, merge the cycles which are fused or spirocyclic into a single polycyclic cycle, and return only those cycles. Cycles which are not polycyclic are not returned.

getRadicalAtoms(self)

Return the atoms in the molecule that have unpaired electrons.

getRadicalCount(self) → short

Return the total number of radical electrons on all atoms in the molecule. In this function, monoradical atoms count as one, biradicals count as two, etc.

getSmallestSetOfSmallestRings(self) → list

Return a list of the smallest set of smallest rings in the graph. The algorithm implements was adapted from a description by Fan, Panaye, Doucet, and Barbu (doi: 10.1021/ci00015a002)

B. T. Fan, A. Panaye, J. P. Doucet, and A. Barbu. “Ring Perception: A New Algorithm for Directly Finding the Smallest Set of Smallest Rings from a Connection Table.” J. Chem. Inf. Comput. Sci. 33, p. 657-662 (1993).

getSymmetryNumber(self)

Returns the symmetry number of Molecule. First checks whether the value is stored as an attribute of Molecule. If not, it calls the calculateSymmetryNumber method.

getURL(self)

Get a URL to the molecule’s info page on the RMG website.

hasAtom(self, Atom atom) → bool

Returns True if atom is an atom in the graph, or False if not.

hasBond(self, Atom atom1, Atom atom2) → bool

Returns True if atoms atom1 and atom2 are connected by an bond, or False if not.

hasEdge(self, Vertex vertex1, Vertex vertex2) → bool

Returns True if vertices vertex1 and vertex2 are connected by an edge, or False if not.

hasVertex(self, Vertex vertex) → bool

Returns True if vertex is a vertex in the graph, or False if not.

implicitHydrogens

implicitHydrogens: ‘bool’

isAromatic(self)

Returns True if the molecule is aromatic, or False if not. Iterates over the SSSR’s and searches for rings that consist solely of Cb atoms. Assumes that aromatic rings always consist of 6 atoms. In cases of naphthalene, where a 6 + 4 aromatic system exists, there will be at least one 6 membered aromatic ring so this algorithm will not fail for fused aromatic rings.

isArylRadical(self, list aromaticRings=None) → bool

Return True if the molecule only contains aryl radicals, ie. radical on an aromatic ring, or False otherwise.

isAtomInCycle(self, Atom atom) → bool

Return True if atom is in one or more cycles in the structure, and False if not.

isBondInCycle(self, Bond bond) → bool

Return True if the bond between atoms atom1 and atom2 is in one or more cycles in the graph, or False if not.

isCyclic(self) → bool

Return True if one or more cycles are present in the graph or False otherwise.

isEdgeInCycle(self, Edge edge) → bool

Return True if the edge between vertices vertex1 and vertex2 is in one or more cycles in the graph, or False if not.

isIdentical(self, Molecule other) → bool

Performs isomorphism checking, with the added constraint that atom IDs must match.

Primary use case is tracking atoms in reactions for reaction degeneracy determination.

Returns True if two graphs are identical and False otherwise.

isIsomorphic(self, Graph other, dict initialMap=None) → bool

Returns True if two graphs are isomorphic and False otherwise. The initialMap attribute can be used to specify a required mapping from self to other (i.e. the atoms of self are the keys, while the atoms of other are the values). The other parameter must be a Molecule object, or a TypeError is raised. Also ensures multiplicities are also equal.

isLinear(self) → bool

Return True if the structure is linear and False otherwise.

isMappingValid(self, Graph other, dict mapping) → bool

Check that a proposed mapping of vertices from self to other is valid by checking that the vertices and edges involved in the mapping are mutually equivalent.

isRadical(self) → bool

Return True if the molecule contains at least one radical electron, or False otherwise.

isSubgraphIsomorphic(self, Graph other, dict initialMap=None) → bool

Returns True if other is subgraph isomorphic and False otherwise. The initialMap attribute can be used to specify a required mapping from self to other (i.e. the atoms of self are the keys, while the atoms of other are the values). The other parameter must be a Group object, or a TypeError is raised.

isVertexInCycle(self, Vertex vertex) → bool

Return True if the given vertex is contained in one or more cycles in the graph, or False if not.

is_equal(self, other)

Method to test equality of two Molecule objects.

kekulize(self)

Kekulizes an aromatic molecule.

merge(self, Graph other) → Graph

Merge two molecules so as to store them in a single Molecule object. The merged Molecule object is returned.

multiplicity

multiplicity: ‘int’

props

props: dict

rdMol

rdMol: object

rdMolConfId

rdMolConfId: ‘int’

removeAtom(self, Atom atom)

Remove atom and all bonds associated with it from the graph. Does not remove atoms that no longer have any bonds as a result of this removal.

removeBond(self, Bond bond)

Remove the bond between atoms atom1 and atom2 from the graph. Does not remove atoms that no longer have any bonds as a result of this removal.

removeEdge(self, Edge edge)

Remove the specified edge from the graph. Does not remove vertices that no longer have any edges as a result of this removal.

removeVertex(self, Vertex vertex)

Remove vertex and all edges associated with it from the graph. Does not remove vertices that no longer have any edges as a result of this removal.

resetConnectivityValues(self)

Reset any cached connectivity information. Call this method when you have modified the graph.

saturate(self)

Saturate the molecule by replacing all radicals with bonds to hydrogen atoms. Changes self molecule object.

sortAtoms(self)

Sort the atoms in the graph. This can make certain operations, e.g. the isomorphism functions, much more efficient.

sortVertices(self)

Sort the vertices in the graph. This can make certain operations, e.g. the isomorphism functions, much more efficient.

split(self) → list

Convert a single Molecule object containing two or more unconnected molecules into separate class:Molecule objects.

symmetryNumber

symmetryNumber: ‘int’

toAdjacencyList(self, str label='', bool removeH=False, bool removeLonePairs=False, bool oldStyle=False)

Convert the molecular structure to a string adjacency list.

toAugmentedInChI(self) → str

Adds an extra layer to the InChI denoting the multiplicity of the molecule.

Separate layer with a forward slash character.

toAugmentedInChIKey(self) → str

Adds an extra layer to the InChIKey denoting the multiplicity of the molecule.

Simply append the multiplicity string, do not separate by a character like forward slash.

toGroup(self)

This method converts a list of atoms in a Molecule to a Group object.

toInChI(self) → str

Convert a molecular structure to an InChI string. Uses RDKit to perform the conversion. Perceives aromaticity.

or

Convert a molecular structure to an InChI string. Uses OpenBabel to perform the conversion.

toInChIKey(self) → str

Convert a molecular structure to an InChI Key string. Uses OpenBabel to perform the conversion.

or

Convert a molecular structure to an InChI Key string. Uses RDKit to perform the conversion.

Removes check-sum dash (-) and character so that only the 14 + 9 characters remain.

toRDKitMol(self, *args, **kwargs)

Convert a molecular structure to a RDKit rdmol object.

toSMARTS(self)

Convert a molecular structure to an SMARTS string. Uses RDKit to perform the conversion. Perceives aromaticity and removes Hydrogen atoms.

toSMILES(self) → str

Convert a molecular structure to an SMILES string.

If there is a Nitrogen atom present it uses OpenBabel to perform the conversion, and the SMILES may or may not be canonical.

Otherwise, it uses RDKit to perform the conversion, so it will be canonical SMILES. While converting to an RDMolecule it will perceive aromaticity and removes Hydrogen atoms.

toSingleBonds(self)

Returns a copy of the current molecule, consisting of only single bonds.

This is useful for isomorphism comparison against something that was made via fromXYZ, which does not attempt to perceive bond orders

update(self)

Update connectivity values, atom types of atoms. Update multiplicity, and sort atoms using the new connectivity values.

updateAtomTypes(self, bool logSpecies=True, bool raiseException=True)

Iterate through the atoms in the structure, checking their atom types to ensure they are correct (i.e. accurately describe their local bond environment) and complete (i.e. are as detailed as possible).

If raiseException is False, then the generic atomType ‘R’ will be prescribed to any atom when getAtomType fails. Currently used for resonance hybrid atom types.

updateConnectivityValues(self)

Update the connectivity values for each vertex in the graph. These are used to accelerate the isomorphism checking.

updateLonePairs(self)

Iterate through the atoms in the structure and calculate the number of lone electron pairs, assuming a neutral molecule.

updateMultiplicity(self)

Update the multiplicity of a newly formed molecule.

vertices

vertices: list