openforcefield.topology.Molecule

class openforcefield.topology.Molecule(*args, **kwargs)[source]

Mutable chemical representation of a molecule, such as a small molecule or biopolymer.

Examples

Create a molecule from an sdf file

>>> from openforcefield.utils import get_data_file_path
>>> sdf_filepath = get_data_file_path('molecules/ethanol.sdf')
>>> molecule = Molecule(sdf_filepath)

Convert to OpenEye OEMol object

>>> oemol = molecule.to_openeye()

Create a molecule from an OpenEye molecule

>>> molecule = Molecule.from_openeye(oemol)

Convert to RDKit Mol object

>>> rdmol = molecule.to_rdkit()

Create a molecule from an RDKit molecule

>>> molecule = Molecule.from_rdkit(rdmol)

Create a molecule from IUPAC name (requires the OpenEye toolkit)

>>> molecule = Molecule.from_iupac('imatinib')

Create a molecule from SMILES

>>> molecule = Molecule.from_smiles('Cc1ccccc1')

Warning

This API is experimental and subject to change.

Attributes
angles

Get an iterator over all i-j-k angles.

atoms

Iterate over all Atom objects.

bonds

Iterate over all Bond objects.

conformers

Returns the list of conformers for this molecule.

has_unique_atom_names

True if the molecule has unique atom names, False otherwise.

hill_formula

Get the Hill formula of the molecule

impropers

Iterate over all proper torsions in the molecule

n_angles

int: number of angles in the Molecule.

n_atoms

The number of Atom objects.

n_bonds

The number of Bond objects.

n_conformers

Returns the number of conformers for this molecule.

n_impropers

int: number of improper torsions in the Molecule.

n_particles

The number of Particle objects, which corresponds to how many positions must be used.

n_propers

int: number of proper torsions in the Molecule.

n_virtual_sites

The number of VirtualSite objects.

name

The name (or title) of the molecule

partial_charges

Returns the partial charges (if present) on the molecule.

particles

Iterate over all Particle objects.

propers

Iterate over all proper torsions in the molecule

properties

The properties dictionary of the molecule

torsions

Get an iterator over all i-j-k-l torsions.

total_charge

Return the total charge on the molecule

virtual_sites

Iterate over all VirtualSite objects.

Methods

add_atom(self, atomic_number, formal_charge, …)

Add an atom

add_bond(self, atom1, atom2, bond_order, …)

Add a bond between two specified atom indices

add_bond_charge_virtual_site(self, atoms, …)

Create a bond charge-type virtual site, in which the location of the charge is specified by the position of two atoms.

add_conformer(self, coordinates)

Add a conformation of the molecule

add_divalent_lone_pair_virtual_site(self, …)

Create a divalent lone pair-type virtual site, in which the location of the charge is specified by the position of three atoms.

add_monovalent_lone_pair_virtual_site(self, …)

Create a bond charge-type virtual site, in which the location of the charge is specified by the position of three atoms.

add_trivalent_lone_pair_virtual_site(self, …)

Create a trivalent lone pair-type virtual site, in which the location of the charge is specified by the position of four atoms.

are_isomorphic(mol1, mol2[, …])

Determines whether the two molecules are isomorphic by comparing their graph representations and the chosen node/edge attributes.

canonical_order_atoms(self[, toolkit_registry])

Canonical order the atoms in a copy of the molecule using a toolkit, returns a new copy.

chemical_environment_matches(self, query[, …])

Retrieve all matches for a given chemical environment query.

compute_partial_charges(self[, toolkit_registry])

Warning! Not Implemented! Calculate partial atomic charges for this molecule using an underlying toolkit

compute_partial_charges_am1bcc(self[, …])

Calculate partial atomic charges for this molecule using AM1-BCC run by an underlying toolkit

compute_wiberg_bond_orders(self[, …])

Calculate wiberg bond orders for this molecule using an underlying toolkit

from_bson(serialized)

Instantiate an object from a BSON serialized representation.

from_dict(molecule_dict)

Create a new Molecule from a dictionary representation

from_file(file_path[, file_format, …])

Create one or more molecules from a file

from_iupac(iupac_name, \*\*kwargs)

Generate a molecule from IUPAC or common name

from_json(serialized)

Instantiate an object from a JSON serialized representation.

from_mapped_smiles(mapped_smiles[, …])

Create an openforcefield.topology.molecule.Molecule from a mapped SMILES made with cmiles.

from_messagepack(serialized)

Instantiate an object from a MessagePack serialized representation.

from_openeye(oemol[, allow_undefined_stereo])

Create a Molecule from an OpenEye molecule.

from_pdb_and_smiles(file_path, smiles[, …])

Create a Molecule from a pdb file and a SMILES string using RDKit.

from_pickle(serialized)

Instantiate an object from a pickle serialized representation.

from_qcschema(qca_record[, client, …])

Create a Molecule from a QCArchive entry based on the cmiles information.

from_rdkit(rdmol[, allow_undefined_stereo])

Create a Molecule from an RDKit molecule.

from_smiles(smiles[, …])

Construct a Molecule from a SMILES representation

from_toml(serialized)

Instantiate an object from a TOML serialized representation.

from_topology(topology)

Return a Molecule representation of an openforcefield Topology containing a single Molecule object.

from_xml(serialized)

Instantiate an object from an XML serialized representation.

from_yaml(serialized)

Instantiate from a YAML serialized representation.

generate_conformers(self[, …])

Generate conformers for this molecule using an underlying toolkit

generate_unique_atom_names(self)

Generate unique atom names using element name and number of times that element has occurred e.g.

get_bond_between(self, i, j)

Returns the bond between two atoms

get_fractional_bond_orders(self[, method, …])

Get fractional bond orders.

is_isomorphic_with(self, other, \*\*kwargs)

Check if the molecule is isomorphic with the other molecule which can be an openforcefield.topology.Molecule, or TopologyMolecule or nx.Graph().

remap(self, mapping_dict[, current_to_new])

Remap all of the indexes in the molecule to match the given mapping dict

to_bson(self)

Return a BSON serialized representation.

to_dict(self)

Return a dictionary representation of the molecule.

to_file(self, file_path, file_format[, …])

Write the current molecule to a file or file-like object

to_hill_formula(molecule)

Generate the Hill formula from either a FrozenMolecule, TopologyMolecule or nx.Graph() of the molecule

to_iupac(self)

Generate IUPAC name from Molecule

to_json(self[, indent])

Return a JSON serialized representation.

to_messagepack(self)

Return a MessagePack representation.

to_networkx(self)

Generate a NetworkX undirected graph from the Molecule.

to_openeye(self[, aromaticity_model])

Create an OpenEye molecule

to_pickle(self)

Return a pickle serialized representation.

to_qcschema(self[, multiplicity, conformer])

Generate the qschema input format used to submit jobs to archive or run qcengine calculations locally, the molecule is placed in canonical order first.

to_rdkit(self[, aromaticity_model])

Create an RDKit molecule

to_smiles(self[, toolkit_registry])

Return a canonical isomeric SMILES representation of the current molecule

to_toml(self)

Return a TOML serialized representation.

to_topology(self)

Return an openforcefield Topology representation containing one copy of this molecule

to_xml(self[, indent])

Return an XML representation.

to_yaml(self)

Return a YAML serialized representation.

__init__(self, *args, **kwargs)[source]

Create a new Molecule object

Parameters
otheroptional, default=None

If specified, attempt to construct a copy of the Molecule from the specified object. This can be any one of the following:

  • a Molecule object

  • a file that can be used to construct a Molecule object

  • an openeye.oechem.OEMol

  • an rdkit.Chem.rdchem.Mol

  • a serialized Molecule object

Examples

Create an empty molecule:

>>> empty_molecule = Molecule()

Create a molecule from a file that can be used to construct a molecule, using either a filename or file-like object:

>>> from openforcefield.utils import get_data_file_path
>>> sdf_filepath = get_data_file_path('molecules/ethanol.sdf')
>>> molecule = Molecule(sdf_filepath)
>>> molecule = Molecule(open(sdf_filepath, 'r'), file_format='sdf')
>>> import gzip
>>> mol2_gz_filepath = get_data_file_path('molecules/toluene.mol2.gz')
>>> molecule = Molecule(gzip.GzipFile(mol2_gz_filepath, 'r'), file_format='mol2')

Create a molecule from another molecule:

>>> molecule_copy = Molecule(molecule)

Convert to OpenEye OEMol object

>>> oemol = molecule.to_openeye()

Create a molecule from an OpenEye molecule:

>>> molecule = Molecule(oemol)

Convert to RDKit Mol object

>>> rdmol = molecule.to_rdkit()

Create a molecule from an RDKit molecule:

>>> molecule = Molecule(rdmol)

Create a molecule from a serialized molecule object:

>>> serialized_molecule = molecule.__getstate__()
>>> molecule_copy = Molecule(serialized_molecule)

Methods

__init__(self, \*args, \*\*kwargs)

Create a new Molecule object

add_atom(self, atomic_number, formal_charge, …)

Add an atom

add_bond(self, atom1, atom2, bond_order, …)

Add a bond between two specified atom indices

add_bond_charge_virtual_site(self, atoms, …)

Create a bond charge-type virtual site, in which the location of the charge is specified by the position of two atoms.

add_conformer(self, coordinates)

Add a conformation of the molecule

add_divalent_lone_pair_virtual_site(self, …)

Create a divalent lone pair-type virtual site, in which the location of the charge is specified by the position of three atoms.

add_monovalent_lone_pair_virtual_site(self, …)

Create a bond charge-type virtual site, in which the location of the charge is specified by the position of three atoms.

add_trivalent_lone_pair_virtual_site(self, …)

Create a trivalent lone pair-type virtual site, in which the location of the charge is specified by the position of four atoms.

are_isomorphic(mol1, mol2[, …])

Determines whether the two molecules are isomorphic by comparing their graph representations and the chosen node/edge attributes.

canonical_order_atoms(self[, toolkit_registry])

Canonical order the atoms in a copy of the molecule using a toolkit, returns a new copy.

chemical_environment_matches(self, query[, …])

Retrieve all matches for a given chemical environment query.

compute_partial_charges(self[, toolkit_registry])

Warning! Not Implemented! Calculate partial atomic charges for this molecule using an underlying toolkit

compute_partial_charges_am1bcc(self[, …])

Calculate partial atomic charges for this molecule using AM1-BCC run by an underlying toolkit

compute_wiberg_bond_orders(self[, …])

Calculate wiberg bond orders for this molecule using an underlying toolkit

from_bson(serialized)

Instantiate an object from a BSON serialized representation.

from_dict(molecule_dict)

Create a new Molecule from a dictionary representation

from_file(file_path[, file_format, …])

Create one or more molecules from a file

from_iupac(iupac_name, \*\*kwargs)

Generate a molecule from IUPAC or common name

from_json(serialized)

Instantiate an object from a JSON serialized representation.

from_mapped_smiles(mapped_smiles[, …])

Create an openforcefield.topology.molecule.Molecule from a mapped SMILES made with cmiles.

from_messagepack(serialized)

Instantiate an object from a MessagePack serialized representation.

from_openeye(oemol[, allow_undefined_stereo])

Create a Molecule from an OpenEye molecule.

from_pdb_and_smiles(file_path, smiles[, …])

Create a Molecule from a pdb file and a SMILES string using RDKit.

from_pickle(serialized)

Instantiate an object from a pickle serialized representation.

from_qcschema(qca_record[, client, …])

Create a Molecule from a QCArchive entry based on the cmiles information.

from_rdkit(rdmol[, allow_undefined_stereo])

Create a Molecule from an RDKit molecule.

from_smiles(smiles[, …])

Construct a Molecule from a SMILES representation

from_toml(serialized)

Instantiate an object from a TOML serialized representation.

from_topology(topology)

Return a Molecule representation of an openforcefield Topology containing a single Molecule object.

from_xml(serialized)

Instantiate an object from an XML serialized representation.

from_yaml(serialized)

Instantiate from a YAML serialized representation.

generate_conformers(self[, …])

Generate conformers for this molecule using an underlying toolkit

generate_unique_atom_names(self)

Generate unique atom names using element name and number of times that element has occurred e.g.

get_bond_between(self, i, j)

Returns the bond between two atoms

get_fractional_bond_orders(self[, method, …])

Get fractional bond orders.

is_isomorphic_with(self, other, \*\*kwargs)

Check if the molecule is isomorphic with the other molecule which can be an openforcefield.topology.Molecule, or TopologyMolecule or nx.Graph().

remap(self, mapping_dict[, current_to_new])

Remap all of the indexes in the molecule to match the given mapping dict

to_bson(self)

Return a BSON serialized representation.

to_dict(self)

Return a dictionary representation of the molecule.

to_file(self, file_path, file_format[, …])

Write the current molecule to a file or file-like object

to_hill_formula(molecule)

Generate the Hill formula from either a FrozenMolecule, TopologyMolecule or nx.Graph() of the molecule

to_iupac(self)

Generate IUPAC name from Molecule

to_json(self[, indent])

Return a JSON serialized representation.

to_messagepack(self)

Return a MessagePack representation.

to_networkx(self)

Generate a NetworkX undirected graph from the Molecule.

to_openeye(self[, aromaticity_model])

Create an OpenEye molecule

to_pickle(self)

Return a pickle serialized representation.

to_qcschema(self[, multiplicity, conformer])

Generate the qschema input format used to submit jobs to archive or run qcengine calculations locally, the molecule is placed in canonical order first.

to_rdkit(self[, aromaticity_model])

Create an RDKit molecule

to_smiles(self[, toolkit_registry])

Return a canonical isomeric SMILES representation of the current molecule

to_toml(self)

Return a TOML serialized representation.

to_topology(self)

Return an openforcefield Topology representation containing one copy of this molecule

to_xml(self[, indent])

Return an XML representation.

to_yaml(self)

Return a YAML serialized representation.

Attributes

angles

Get an iterator over all i-j-k angles.

atoms

Iterate over all Atom objects.

bonds

Iterate over all Bond objects.

conformers

Returns the list of conformers for this molecule.

has_unique_atom_names

True if the molecule has unique atom names, False otherwise.

hill_formula

Get the Hill formula of the molecule

impropers

Iterate over all proper torsions in the molecule

n_angles

int: number of angles in the Molecule.

n_atoms

The number of Atom objects.

n_bonds

The number of Bond objects.

n_conformers

Returns the number of conformers for this molecule.

n_impropers

int: number of improper torsions in the Molecule.

n_particles

The number of Particle objects, which corresponds to how many positions must be used.

n_propers

int: number of proper torsions in the Molecule.

n_virtual_sites

The number of VirtualSite objects.

name

The name (or title) of the molecule

partial_charges

Returns the partial charges (if present) on the molecule.

particles

Iterate over all Particle objects.

propers

Iterate over all proper torsions in the molecule

properties

The properties dictionary of the molecule

torsions

Get an iterator over all i-j-k-l torsions.

total_charge

Return the total charge on the molecule

virtual_sites

Iterate over all VirtualSite objects.

property angles

Get an iterator over all i-j-k angles.

static are_isomorphic(mol1, mol2, return_atom_map=False, aromatic_matching=True, formal_charge_matching=True, bond_order_matching=True, atom_stereochemistry_matching=True, bond_stereochemistry_matching=True)

Determines whether the two molecules are isomorphic by comparing their graph representations and the chosen node/edge attributes. Minimally connections and atomic_number are checked.

If nx.Graphs() are given they must at least have atomic_number attributes on nodes. other optional attributes for nodes are: is_aromatic, formal_charge and stereochemistry. optional attributes for edges are: is_aromatic, bond_order and stereochemistry.

Warning

This API is experimental and subject to change.

Parameters
mol1an openforcefield.topology.molecule.FrozenMolecule or TopologyMolecule or nx.Graph()
mol2an openforcefield.topology.molecule.FrozenMolecule or TopologyMolecule or nx.Graph()

The molecule to test for isomorphism.

return_atom_map: bool, default=False, optional

will return an optional dict containing the atomic mapping.

aromatic_matching: bool, default=True, optional

compare the aromatic attributes of bonds and atoms.

formal_charge_matching: bool, default=True, optional

compare the formal charges attributes of the atoms.

bond_order_matching: bool, deafult=True, optional

compare the bond order on attributes of the bonds.

atom_stereochemistry_matchingbool, default=True, optional

If False, atoms’ stereochemistry is ignored for the purpose of determining equality.

bond_stereochemistry_matchingbool, default=True, optional

If False, bonds’ stereochemistry is ignored for the purpose of determining equality.

Returns
molecules_are_isomorphicbool
atom_mapdefault=None, Optional,

[Dict[int,int]] ordered by mol1 indexing {mol1_index: mol2_index} If molecules are not isomorphic given input arguments, will return None instead of dict.

property atoms

Iterate over all Atom objects.

property bonds

Iterate over all Bond objects.

canonical_order_atoms(self, toolkit_registry=<openforcefield.utils.toolkits.ToolkitRegistry object at 0x7ff387cfa690>)

Canonical order the atoms in a copy of the molecule using a toolkit, returns a new copy.

Warning

This API is experimental and subject to change.

Parameters
hydrogens_last: bool, default True

If the canonical ordering should rank the hydrogens last.

toolkit_registryopenforcefield.utils.toolkits.ToolRegistry or openforcefield.utils.toolkits.ToolkitWrapper, optional, default=None

ToolkitRegistry or ToolkitWrapper to use for SMILES-to-molecule conversion

Returns
moleculeopenforcefield.topology.Molecule

An new openforcefield-style molecule with atoms in the canonical order.

chemical_environment_matches(self, query, toolkit_registry=<openforcefield.utils.toolkits.ToolkitRegistry object at 0x7ff387cfa690>)

Retrieve all matches for a given chemical environment query.

Parameters
querystr or ChemicalEnvironment

SMARTS string (with one or more tagged atoms) or ChemicalEnvironment query Query will internally be resolved to SMIRKS using query.asSMIRKS() if it has an .asSMIRKS method.

toolkit_registryopenforcefield.utils.toolkits.ToolRegistry or openforcefield.utils.toolkits.ToolkitWrapper, optional, default=GLOBAL_TOOLKIT_REGISTRY

ToolkitRegistry or ToolkitWrapper to use for chemical environment matches

Returns
matcheslist of atom index tuples

A list of tuples, containing the indices of the matching atoms.

Examples

Retrieve all the carbon-carbon bond matches in a molecule

>>> molecule = Molecule.from_iupac('imatinib')
>>> matches = molecule.chemical_environment_matches('[#6X3:1]~[#6X3:2]')
compute_partial_charges(self, toolkit_registry=<openforcefield.utils.toolkits.ToolkitRegistry object at 0x7ff387cfa690>)

Warning! Not Implemented! Calculate partial atomic charges for this molecule using an underlying toolkit

Parameters
quantum_chemical_methodstring, default=’AM1-BCC’

The quantum chemical method to use for partial charge calculation.

partial_charge_methodstring, default=’None’

The partial charge calculation method to use for partial charge calculation.

toolkit_registryopenforcefield.utils.toolkits.ToolRegistry or openforcefield.utils.toolkits.ToolkitWrapper, optional, default=None

ToolkitRegistry or ToolkitWrapper to use for SMILES-to-molecule conversion

Raises
InvalidToolkitError

If an invalid object is passed as the toolkit_registry parameter

Examples

>>> molecule = Molecule.from_smiles('CCCCCC')
>>> molecule.generate_conformers()
compute_partial_charges_am1bcc(self, toolkit_registry=<openforcefield.utils.toolkits.ToolkitRegistry object at 0x7ff387cfa690>)

Calculate partial atomic charges for this molecule using AM1-BCC run by an underlying toolkit

Parameters
toolkit_registryopenforcefield.utils.toolkits.ToolRegistry or openforcefield.utils.toolkits.ToolkitWrapper, optional, default=None

ToolkitRegistry or ToolkitWrapper to use for the calculation

Raises
InvalidToolkitError

If an invalid object is passed as the toolkit_registry parameter

Examples

>>> molecule = Molecule.from_smiles('CCCCCC')
>>> molecule.generate_conformers()
>>> molecule.compute_partial_charges_am1bcc()
compute_wiberg_bond_orders(self, charge_model=None, toolkit_registry=<openforcefield.utils.toolkits.ToolkitRegistry object at 0x7ff387cfa690>)

Calculate wiberg bond orders for this molecule using an underlying toolkit

Parameters
toolkit_registryopenforcefield.utils.toolkits.ToolRegistry or openforcefield.utils.toolkits.ToolkitWrapper, optional, default=None

ToolkitRegistry or ToolkitWrapper to use for SMILES-to-molecule conversion

charge_modelstring, optional

The charge model to use for partial charge calculation

Raises
InvalidToolkitError

If an invalid object is passed as the toolkit_registry parameter

Examples

>>> molecule = Molecule.from_smiles('CCCCCC')
>>> molecule.generate_conformers()
>>> molecule.compute_wiberg_bond_orders()
property conformers

Returns the list of conformers for this molecule. This returns a list of simtk.unit.Quantity-wrapped numpy arrays, of shape (3 x n_atoms) and with dimensions of distance. The return value is the actual list of conformers, and changes to the contents affect the original FrozenMolecule.

classmethod from_bson(serialized)

Instantiate an object from a BSON serialized representation.

Specification: http://bsonspec.org/

Parameters
serializedbytes

A BSON serialized representation of the object

Returns
instancecls

An instantiated object

classmethod from_dict(molecule_dict)

Create a new Molecule from a dictionary representation

Parameters
molecule_dictOrderedDict

A dictionary representation of the molecule.

Returns
moleculeMolecule

A Molecule created from the dictionary representation

static from_file(file_path, file_format=None, toolkit_registry=<openforcefield.utils.toolkits.ToolkitRegistry object at 0x7ff387cfa690>, allow_undefined_stereo=False)

Create one or more molecules from a file

Parameters
file_pathstr or file-like object

The path to the file or file-like object to stream one or more molecules from.

file_formatstr, optional, default=None

Format specifier, usually file suffix (eg. ‘MOL2’, ‘SMI’) Note that not all toolkits support all formats. Check ToolkitWrapper.toolkit_file_read_formats for your loaded toolkits for details.

toolkit_registryopenforcefield.utils.toolkits.ToolRegistry or openforcefield.utils.toolkits.ToolkitWrapper,
optional, default=GLOBAL_TOOLKIT_REGISTRY

ToolkitRegistry or ToolkitWrapper to use for file loading. If a Toolkit is passed, only the highest-precedence toolkit is used

allow_undefined_stereobool, default=False

If false, raises an exception if oemol contains undefined stereochemistry.

Returns
moleculesMolecule or list of Molecules

If there is a single molecule in the file, a Molecule is returned; otherwise, a list of Molecule objects is returned.

Examples

>>> from openforcefield.tests.utils import get_monomer_mol2_file_path
>>> mol2_file_path = get_monomer_mol2_file_path('cyclohexane')
>>> molecule = Molecule.from_file(mol2_file_path)
classmethod from_iupac(iupac_name, **kwargs)

Generate a molecule from IUPAC or common name

Parameters
iupac_namestr

IUPAC name of molecule to be generated

allow_undefined_stereobool, default=False

If false, raises an exception if molecule contains undefined stereochemistry.

Returns
moleculeMolecule

The resulting molecule with position

Note

This method requires the OpenEye toolkit to be installed. ..

Examples

Create a molecule from a common name

>>> molecule = Molecule.from_iupac('4-[(4-methylpiperazin-1-yl)methyl]-N-(4-methyl-3-{[4-(pyridin-3-yl)pyrimidin-2-yl]amino}phenyl)benzamide')

Create a molecule from a common name

>>> molecule = Molecule.from_iupac('imatinib')
classmethod from_json(serialized)

Instantiate an object from a JSON serialized representation.

Specification: https://www.json.org/

Parameters
serializedstr

A JSON serialized representation of the object

Returns
instancecls

An instantiated object

classmethod from_mapped_smiles(mapped_smiles, toolkit_registry=<openforcefield.utils.toolkits.ToolkitRegistry object at 0x7ff387cfa690>, allow_undefined_stereo=False)

Create an openforcefield.topology.molecule.Molecule from a mapped SMILES made with cmiles. The molecule will be in the order of the indexing in the mapped smiles string.

Warning

This API is experimental and subject to change.

Parameters
mapped_smiles: str,

A CMILES-style mapped smiles string with explicit hydrogens.

toolkit_registryopenforcefield.utils.toolkits.ToolkitRegistry or openforcefield.utils.toolkits.ToolkitWrapper, optional, default=None

ToolkitRegistry or ToolkitWrapper to use for SMILES-to-molecule conversion

allow_undefined_stereobool, default=False

If false, raises an exception if oemol contains undefined stereochemistry.

Returns
offmolopenforcefield.topology.molecule.Molecule

An openforcefiled molecule instance.

Raises
SmilesParsingErrorif the given SMILES had no indexing picked up by the toolkits.
classmethod from_messagepack(serialized)

Instantiate an object from a MessagePack serialized representation.

Specification: https://msgpack.org/index.html

Parameters
serializedbytes

A MessagePack-encoded bytes serialized representation

Returns
instancecls

Instantiated object.

static from_openeye(oemol, allow_undefined_stereo=False)

Create a Molecule from an OpenEye molecule.

Requires the OpenEye toolkit to be installed.

Parameters
oemolopeneye.oechem.OEMol

An OpenEye molecule

allow_undefined_stereobool, default=False

If false, raises an exception if oemol contains undefined stereochemistry.

Returns
moleculeopenforcefield.topology.Molecule

An openforcefield molecule

Examples

Create a Molecule from an OpenEye OEMol

>>> from openeye import oechem
>>> from openforcefield.tests.utils import get_data_file_path
>>> ifs = oechem.oemolistream(get_data_file_path('systems/monomers/ethanol.mol2'))
>>> oemols = list(ifs.GetOEGraphMols())
>>> molecule = Molecule.from_openeye(oemols[0])
classmethod from_pdb_and_smiles(file_path, smiles, allow_undefined_stereo=False)

Create a Molecule from a pdb file and a SMILES string using RDKit.

Requires RDKit to be installed.

Warning

This API is experimental and subject to change.

The molecule is created and sanitised based on the SMILES string, we then find a mapping between this molecule and one from the PDB based only on atomic number and connections. The SMILES molecule is then reindex to match the PDB, the conformer is attached and the molecule returned.

Parameters
file_path: str

PDB file path

smilesstr

a valid smiles string for the pdb, used for seterochemistry and bond order

allow_undefined_stereobool, default=False

If false, raises an exception if oemol contains undefined stereochemistry.

Returns
moleculeopenforcefield.Molecule

An OFFMol instance with ordering the same as used in the PDB file.

Raises
InvalidConformerErrorif the SMILES and PDB molecules are not isomorphic.
classmethod from_pickle(serialized)

Instantiate an object from a pickle serialized representation.

Warning

This is not recommended for safe, stable storage since the pickle specification may change between Python versions.

Parameters
serializedstr

A pickled representation of the object

Returns
instancecls

An instantiated object

classmethod from_qcschema(qca_record, client=None, toolkit_registry=<openforcefield.utils.toolkits.ToolkitRegistry object at 0x7ff387cfa690>, allow_undefined_stereo=False)

Create a Molecule from a QCArchive entry based on the cmiles information.

If we also have a client instance/address we can go and attach the starting geometry.

Parameters
qca_recorddict,

A QCArchive dict with json encoding or record instance

clientoptional, default=None,

A qcportal.FractalClient instance so we can pull the initial molecule geometry.

toolkit_registryopenforcefield.utils.toolkits.ToolRegistry or openforcefield.utils.toolkits.ToolkitWrapper, optional, default=None

ToolkitRegistry or ToolkitWrapper to use for SMILES-to-molecule conversion

allow_undefined_stereobool, default=False

If false, raises an exception if oemol contains undefined stereochemistry.

Returns
moleculeopenforcefield.topology.Molecule

An openforcefield molecule instance.

Raises
AttributeErrorif the record dict can not be made from a record instance.

if a client is passed, because the client could not retrive the initial molecule.

KeyErrorif the dict does not contain the canonical_isomeric_explicit_hydrogen_mapped_smiles.
InvalidConformerErrorsilent error, if the conformer could not be attached.
static from_rdkit(rdmol, allow_undefined_stereo=False)

Create a Molecule from an RDKit molecule.

Requires the RDKit to be installed.

Parameters
rdmolrkit.RDMol

An RDKit molecule

allow_undefined_stereobool, default=False

If false, raises an exception if oemol contains undefined stereochemistry.

Returns
moleculeopenforcefield.Molecule

An openforcefield molecule

Examples

Create a molecule from an RDKit molecule

>>> from rdkit import Chem
>>> from openforcefield.tests.utils import get_data_file_path
>>> rdmol = Chem.MolFromMolFile(get_data_file_path('systems/monomers/ethanol.sdf'))
>>> molecule = Molecule.from_rdkit(rdmol)
static from_smiles(smiles, hydrogens_are_explicit=False, toolkit_registry=<openforcefield.utils.toolkits.ToolkitRegistry object at 0x7ff387cfa690>, allow_undefined_stereo=False)

Construct a Molecule from a SMILES representation

Parameters
smilesstr

The SMILES representation of the molecule.

hydrogens_are_explicitbool, default = False

If False, the cheminformatics toolkit will perform hydrogen addition

toolkit_registryopenforcefield.utils.toolkits.ToolRegistry or openforcefield.utils.toolkits.ToolkitWrapper, optional, default=None

ToolkitRegistry or ToolkitWrapper to use for SMILES-to-molecule conversion

allow_undefined_stereobool, default=False

Whether to accept SMILES with undefined stereochemistry. If False, an exception will be raised if a SMILES with undefined stereochemistry is passed into this function.

Returns
moleculeopenforcefield.topology.Molecule

Examples

>>> molecule = Molecule.from_smiles('Cc1ccccc1')
classmethod from_toml(serialized)

Instantiate an object from a TOML serialized representation.

Specification: https://github.com/toml-lang/toml

Parameters
serlializedstr

A TOML serialized representation of the object

Returns
instancecls

An instantiated object

static from_topology(topology)

Return a Molecule representation of an openforcefield Topology containing a single Molecule object.

Parameters
topologyopenforcefield.topology.Topology

The Topology object containing a single Molecule object. Note that OpenMM and MDTraj Topology objects are not supported.

Returns
moleculeopenforcefield.topology.Molecule

The Molecule object in the topology

Raises
ValueError

If the topology does not contain exactly one molecule.

Examples

Create a molecule from a Topology object that contains exactly one molecule

>>> molecule = Molecule.from_topology(topology)  
classmethod from_xml(serialized)

Instantiate an object from an XML serialized representation.

Specification: https://www.w3.org/XML/

Parameters
serializedbytes

An XML serialized representation

Returns
instancecls

Instantiated object.

classmethod from_yaml(serialized)

Instantiate from a YAML serialized representation.

Specification: http://yaml.org/

Parameters
serializedstr

A YAML serialized representation of the object

Returns
instancecls

Instantiated object

generate_conformers(self, toolkit_registry=<openforcefield.utils.toolkits.ToolkitRegistry object at 0x7ff387cfa690>, n_conformers=10, clear_existing=True)

Generate conformers for this molecule using an underlying toolkit

Parameters
toolkit_registryopenforcefield.utils.toolkits.ToolRegistry or openforcefield.utils.toolkits.ToolkitWrapper, optional, default=None

ToolkitRegistry or ToolkitWrapper to use for SMILES-to-molecule conversion

n_conformersint, default=1

The maximum number of conformers to produce

clear_existingbool, default=True

Whether to overwrite existing conformers for the molecule

Raises
InvalidToolkitError

If an invalid object is passed as the toolkit_registry parameter

Examples

>>> molecule = Molecule.from_smiles('CCCCCC')
>>> molecule.generate_conformers()
generate_unique_atom_names(self)

Generate unique atom names using element name and number of times that element has occurred e.g. ‘C1’, ‘H1’, ‘O1’, ‘C2’, …

get_bond_between(self, i, j)

Returns the bond between two atoms

Parameters
i, jint or Atom

Atoms or atom indices to check

Returns
bondBond

The bond between i and j.

get_fractional_bond_orders(self, method='Wiberg', toolkit_registry=<openforcefield.utils.toolkits.ToolkitRegistry object at 0x7ff387cfa690>)

Get fractional bond orders.

methodstr, optional, default=’Wiberg’

The name of the charge method to use. Options are: * ‘Wiberg’ : Wiberg bond order

toolkit_registryopenforcefield.utils.toolkits ToolkitRegistry

The toolkit registry to use for molecule operations

Examples

Get fractional Wiberg bond orders

>>> molecule = Molecule.from_iupac('imatinib')
>>> molecule.generate_conformers()
>>> fractional_bond_orders = molecule.get_fractional_bond_orders(method='Wiberg')
property has_unique_atom_names

True if the molecule has unique atom names, False otherwise.

property hill_formula

Get the Hill formula of the molecule

property impropers

Iterate over all proper torsions in the molecule

is_isomorphic_with(self, other, **kwargs)

Check if the molecule is isomorphic with the other molecule which can be an openforcefield.topology.Molecule, or TopologyMolecule or nx.Graph(). Full matching is done using the options described bellow.

Warning

This API is experimental and subject to change.

Parameters
other: openforcefield.topology.Molecule or TopologyMolecule or nx.Graph()
return_atom_map: bool, default=False, optional

will return an optional dict containing the atomic mapping.

aromatic_matching: bool, default=True, optional
compare the aromatic attributes of bonds and atoms.
formal_charge_matching: bool, default=True, optional
compare the formal charges attributes of the atoms.
bond_order_matching: bool, deafult=True, optional
compare the bond order on attributes of the bonds.
atom_stereochemistry_matchingbool, default=True, optional

If False, atoms’ stereochemistry is ignored for the purpose of determining equality.

bond_stereochemistry_matchingbool, default=True, optional

If False, bonds’ stereochemistry is ignored for the purpose of determining equality.

Returns
isomorphicbool
property n_angles

int: number of angles in the Molecule.

property n_atoms

The number of Atom objects.

property n_bonds

The number of Bond objects.

property n_conformers

Returns the number of conformers for this molecule.

property n_impropers

int: number of improper torsions in the Molecule.

property n_particles

The number of Particle objects, which corresponds to how many positions must be used.

property n_propers

int: number of proper torsions in the Molecule.

property n_virtual_sites

The number of VirtualSite objects.

property name

The name (or title) of the molecule

property partial_charges

Returns the partial charges (if present) on the molecule.

Returns
partial_chargesa simtk.unit.Quantity - wrapped numpy array [1 x n_atoms] or None

The partial charges on this Molecule’s atoms. Returns None if no charges have been specified.

property particles

Iterate over all Particle objects.

property propers

Iterate over all proper torsions in the molecule

property properties

The properties dictionary of the molecule

remap(self, mapping_dict, current_to_new=True)

Remap all of the indexes in the molecule to match the given mapping dict

Warning

This API is experimental and subject to change.

Parameters
mapping_dictdict,

A dictionary of the mapping between in the indexes, this should start from 0.

current_to_newbool, default=True

The dict is {current_index: new_index} if True else {new_index: current_index}

Returns
new_moleculeopenforcefield.topology.molecule.Molecule

An openforcefield.Molecule instance with all attributes transferred, in the PDB order.

to_bson(self)

Return a BSON serialized representation.

Specification: http://bsonspec.org/

Returns
serializedbytes

A BSON serialized representation of the objecft

to_dict(self)

Return a dictionary representation of the molecule.

Returns
molecule_dictOrderedDict

A dictionary representation of the molecule.

to_file(self, file_path, file_format, toolkit_registry=<openforcefield.utils.toolkits.ToolkitRegistry object at 0x7ff387cfa690>)

Write the current molecule to a file or file-like object

Parameters
file_pathstr or file-like object

A file-like object or the path to the file to be written.

file_formatstr

Format specifier, one of [‘MOL2’, ‘MOL2H’, ‘SDF’, ‘PDB’, ‘SMI’, ‘CAN’, ‘TDT’] Note that not all toolkits support all formats

toolkit_registryopenforcefield.utils.toolkits.ToolRegistry or openforcefield.utils.toolkits.ToolkitWrapper,
optional, default=GLOBAL_TOOLKIT_REGISTRY

ToolkitRegistry or ToolkitWrapper to use for file writing. If a Toolkit is passed, only the highest-precedence toolkit is used

Raises
ValueError

If the requested file_format is not supported by one of the installed cheminformatics toolkits

Examples

>>> molecule = Molecule.from_iupac('imatinib')
>>> molecule.to_file('imatinib.mol2', file_format='mol2')  
>>> molecule.to_file('imatinib.sdf', file_format='sdf')  
>>> molecule.to_file('imatinib.pdb', file_format='pdb')  
static to_hill_formula(molecule)

Generate the Hill formula from either a FrozenMolecule, TopologyMolecule or nx.Graph() of the molecule

Parameters
moleculeFrozenMolecule, TopologyMolecule or nx.Graph()
Returns
formulathe Hill formula of the molecule
Raises
NotImplementedErrorif the molecule is not of one of the specified types.
to_iupac(self)

Generate IUPAC name from Molecule

Returns
iupac_namestr

IUPAC name of the molecule

Note

This method requires the OpenEye toolkit to be installed. ..

Examples

>>> from openforcefield.utils import get_data_file_path
>>> sdf_filepath = get_data_file_path('molecules/ethanol.sdf')
>>> molecule = Molecule(sdf_filepath)
>>> iupac_name = molecule.to_iupac()
to_json(self, indent=None)

Return a JSON serialized representation.

Specification: https://www.json.org/

Parameters
indentint, optional, default=None

If not None, will pretty-print with specified number of spaces for indentation

Returns
serializedstr

A JSON serialized representation of the object

to_messagepack(self)

Return a MessagePack representation.

Specification: https://msgpack.org/index.html

Returns
serializedbytes

A MessagePack-encoded bytes serialized representation of the object

to_networkx(self)

Generate a NetworkX undirected graph from the Molecule.

Nodes are Atoms labeled with particle indices and atomic elements (via the element node atrribute). Edges denote chemical bonds between Atoms. Virtual sites are not included, since they lack a concept of chemical connectivity.

Returns
graphnetworkx.Graph

The resulting graph, with nodes (atoms) labeled with atom indices, elements, stereochemistry and aromaticity flags and bonds with two atom indices, bond order, stereochemistry, and aromaticity flags

Examples

Retrieve the bond graph for imatinib (OpenEye toolkit required)

>>> molecule = Molecule.from_iupac('imatinib')
>>> nxgraph = molecule.to_networkx()
to_openeye(self, aromaticity_model='OEAroModel_MDL')

Create an OpenEye molecule

Requires the OpenEye toolkit to be installed.

Parameters
aromaticity_modelstr, optional, default=DEFAULT_AROMATICITY_MODEL

The aromaticity model to use

Returns
oemolopeneye.oechem.OEMol

An OpenEye molecule

Examples

Create an OpenEye molecule from a Molecule

>>> molecule = Molecule.from_smiles('CC')
>>> oemol = molecule.to_openeye()
to_pickle(self)

Return a pickle serialized representation.

Warning

This is not recommended for safe, stable storage since the pickle specification may change between Python versions.

Returns
serializedstr

A pickled representation of the object

to_qcschema(self, multiplicity=1, conformer=0)

Generate the qschema input format used to submit jobs to archive or run qcengine calculations locally, the molecule is placed in canonical order first. spec can be found here <https://molssi-qc-schema.readthedocs.io/en/latest/index.html>

Warning

This API is experimental and subject to change.

Parameters
multiplicityint, default=1,

The multiplicity of the molecule required for qcschema

conformerint, default=0,

The index of the conformer that should be used for qcschema

Returns
qcelemental.models.Molecule :

A validated qcschema

Raises
ImportErrorif qcelemental is not installed; the qcschema can not be validated.
InvalidConformerErrorif there is no conformer found at the given index.
to_rdkit(self, aromaticity_model='OEAroModel_MDL')

Create an RDKit molecule

Requires the RDKit to be installed.

Parameters
aromaticity_modelstr, optional, default=DEFAULT_AROMATICITY_MODEL

The aromaticity model to use

Returns
rdmolrkit.RDMol

An RDKit molecule

Examples

Convert a molecule to RDKit

>>> from openforcefield.utils import get_data_file_path
>>> sdf_filepath = get_data_file_path('molecules/ethanol.sdf')
>>> molecule = Molecule(sdf_filepath)
>>> rdmol = molecule.to_rdkit()
to_smiles(self, toolkit_registry=<openforcefield.utils.toolkits.ToolkitRegistry object at 0x7ff387cfa690>)

Return a canonical isomeric SMILES representation of the current molecule

Note

RDKit and OpenEye versions will not necessarily return the same representation.

Parameters
toolkit_registryopenforcefield.utils.toolkits.ToolRegistry or openforcefield.utils.toolkits.ToolkitWrapper, optional, default=None

ToolkitRegistry or ToolkitWrapper to use for SMILES conversion

Returns
smilesstr

Canonical isomeric explicit-hydrogen SMILES

Examples

>>> from openforcefield.utils import get_data_file_path
>>> sdf_filepath = get_data_file_path('molecules/ethanol.sdf')
>>> molecule = Molecule(sdf_filepath)
>>> smiles = molecule.to_smiles()
to_toml(self)

Return a TOML serialized representation.

Specification: https://github.com/toml-lang/toml

Returns
serializedstr

A TOML serialized representation of the object

to_topology(self)

Return an openforcefield Topology representation containing one copy of this molecule

Returns
topologyopenforcefield.topology.Topology

A Topology representation of this molecule

Examples

>>> molecule = Molecule.from_iupac('imatinib')
>>> topology = molecule.to_topology()
to_xml(self, indent=2)

Return an XML representation.

Specification: https://www.w3.org/XML/

Parameters
indentint, optional, default=2

If not None, will pretty-print with specified number of spaces for indentation

Returns
serializedbytes

A MessagePack-encoded bytes serialized representation.

to_yaml(self)

Return a YAML serialized representation.

Specification: http://yaml.org/

Returns
serializedstr

A YAML serialized representation of the object

property torsions

Get an iterator over all i-j-k-l torsions. Note that i-j-k-i torsions (cycles) are excluded.

Returns
torsionsiterable of 4-Atom tuples
property total_charge

Return the total charge on the molecule

property virtual_sites

Iterate over all VirtualSite objects.

add_atom(self, atomic_number, formal_charge, is_aromatic, stereochemistry=None, name=None)[source]

Add an atom

Parameters
atomic_numberint

Atomic number of the atom

formal_chargeint

Formal charge of the atom

is_aromaticbool

If True, atom is aromatic; if False, not aromatic

stereochemistrystr, optional, default=None

Either ‘R’ or ‘S’ for specified stereochemistry, or None if stereochemistry is irrelevant

namestr, optional, default=None

An optional name for the atom

Returns
indexint

The index of the atom in the molecule

Examples

Define a methane molecule

>>> molecule = Molecule()
>>> molecule.name = 'methane'
>>> C = molecule.add_atom(6, 0, False)
>>> H1 = molecule.add_atom(1, 0, False)
>>> H2 = molecule.add_atom(1, 0, False)
>>> H3 = molecule.add_atom(1, 0, False)
>>> H4 = molecule.add_atom(1, 0, False)
>>> bond_idx = molecule.add_bond(C, H1, False, 1)
>>> bond_idx = molecule.add_bond(C, H2, False, 1)
>>> bond_idx = molecule.add_bond(C, H3, False, 1)
>>> bond_idx = molecule.add_bond(C, H4, False, 1)
add_bond_charge_virtual_site(self, atoms, distance, charge_increments=None, weights=None, epsilon=None, sigma=None, rmin_half=None, name='')[source]

Create a bond charge-type virtual site, in which the location of the charge is specified by the position of two atoms. This supports placement of a virtual site S along a vector between two specified atoms, e.g. to allow for a sigma hole for halogens or similar contexts. With positive values of the distance, the virtual site lies outside the first indexed atom. Parameters ———- atoms : list of openforcefield.topology.molecule.Atom objects or ints of shape [N

The atoms defining the virtual site’s position or their indices

distance : float

weightslist of floats of shape [N] or None, optional, default=None

weights[index] is the weight of particles[index] contributing to the position of the virtual site. Default is None

charge_incrementslist of floats of shape [N], optional, default=None

The amount of charge to remove from the VirtualSite’s atoms and put in the VirtualSite. Indexing in this list should match the ordering in the atoms list. Default is None.

epsilonfloat

Epsilon term for VdW properties of virtual site. Default is None.

sigmafloat, default=None

Sigma term for VdW properties of virtual site. Default is None.

rmin_halffloat

Rmin_half term for VdW properties of virtual site. Default is None.

namestring or None, default=’’

The name of this virtual site. Default is ‘’.

Returns
indexint

The index of the newly-added virtual site in the molecule

add_monovalent_lone_pair_virtual_site(self, atoms, distance, out_of_plane_angle, in_plane_angle, **kwargs)[source]

Create a bond charge-type virtual site, in which the location of the charge is specified by the position of three atoms.

TODO : Do “weights” have any meaning here?

Parameters
atomslist of three openforcefield.topology.molecule.Atom objects or ints

The three atoms defining the virtual site’s position or their molecule atom indices

distancefloat
out_of_plane_anglefloat
in_plane_anglefloat
epsilonfloat

Epsilon term for VdW properties of virtual site. Default is None.

sigmafloat, default=None

Sigma term for VdW properties of virtual site. Default is None.

rmin_halffloat

Rmin_half term for VdW properties of virtual site. Default is None.

namestring or None, default=’’

The name of this virtual site. Default is ‘’.

Returns
indexint

The index of the newly-added virtual site in the molecule

add_divalent_lone_pair_virtual_site(self, atoms, distance, out_of_plane_angle, in_plane_angle, **kwargs)[source]

Create a divalent lone pair-type virtual site, in which the location of the charge is specified by the position of three atoms.

TODO : Do “weights” have any meaning here?

Parameters
atomslist of 3 openforcefield.topology.molecule.Atom objects or ints

The three atoms defining the virtual site’s position or their molecule atom indices

distancefloat
out_of_plane_anglefloat
in_plane_anglefloat
epsilonfloat

Epsilon term for VdW properties of virtual site. Default is None.

sigmafloat, default=None

Sigma term for VdW properties of virtual site. Default is None.

rmin_halffloat

Rmin_half term for VdW properties of virtual site. Default is None.

namestring or None, default=’’

The name of this virtual site. Default is ‘’.

Returns
indexint

The index of the newly-added virtual site in the molecule

add_trivalent_lone_pair_virtual_site(self, atoms, distance, out_of_plane_angle, in_plane_angle, **kwargs)[source]

Create a trivalent lone pair-type virtual site, in which the location of the charge is specified by the position of four atoms.

TODO : Do “weights” have any meaning here?

Parameters
atomslist of 4 openforcefield.topology.molecule.Atom objects or ints

The three atoms defining the virtual site’s position or their molecule atom indices

distancefloat
out_of_plane_anglefloat
in_plane_anglefloat
epsilonfloat

Epsilon term for VdW properties of virtual site. Default is None.

sigmafloat, default=None

Sigma term for VdW properties of virtual site. Default is None.

rmin_halffloat

Rmin_half term for VdW properties of virtual site. Default is None.

namestring or None, default=’’

The name of this virtual site. Default is ‘’.

Returns
indexint

The index of the newly-added virtual site in the molecule

add_bond(self, atom1, atom2, bond_order, is_aromatic, stereochemistry=None, fractional_bond_order=None)[source]

Add a bond between two specified atom indices

Parameters
atom1int or openforcefield.topology.molecule.Atom

Index of first atom

atom2int or openforcefield.topology.molecule.Atom

Index of second atom

bond_orderint

Integral bond order of Kekulized form

is_aromaticbool

True if this bond is aromatic, False otherwise

stereochemistrystr, optional, default=None

Either ‘E’ or ‘Z’ for specified stereochemistry, or None if stereochemistry is irrelevant

fractional_bond_orderfloat, optional, default=None

The fractional (eg. Wiberg) bond order

Returns
index: int

Index of the bond in this molecule

add_conformer(self, coordinates)[source]

Add a conformation of the molecule

Parameters
coordinates: simtk.unit.Quantity(np.array) with shape (n_atoms, 3) and dimension of distance

Coordinates of the new conformer, with the first dimension of the array corresponding to the atom index in the Molecule’s indexing system.

Returns
index: int

The index of this conformer