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(atomic_number, formal_charge, …)

Add an atom

add_bond(atom1, atom2, bond_order, is_aromatic)

Add a bond between two specified atom indices

add_bond_charge_virtual_site(atoms, distance)

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.

add_conformer(coordinates)

Add a conformation of the molecule

add_divalent_lone_pair_virtual_site(atoms, …)

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(atoms, …)

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(atoms, …)

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.

assign_fractional_bond_orders([…])

Update and store list of bond orders this molecule.

assign_partial_charges(partial_charge_method)

Calculate partial atomic charges for this molecule using an underlying toolkit, and assign the new values to the partial_charges attribute.

canonical_order_atoms([toolkit_registry])

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

chemical_environment_matches(query[, …])

Retrieve all matches for a given chemical environment query.

compute_partial_charges_am1bcc([…])

Calculate partial atomic charges for this molecule using AM1-BCC run by an underlying toolkit and assign them to this molecule’s partial_charges attribute.

enumerate_protomers([max_states])

Enumerate the formal charges of a molecule to generate different protomoers.

enumerate_stereoisomers([undefined_only, …])

Enumerate the stereocenters and bonds of the current molecule.

enumerate_tautomers([max_states, …])

Enumerate the possible tautomers of the current molecule

find_rotatable_bonds([…])

Find all bonds classed as rotatable ignoring any matched to the ignore_functional_groups list.

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_inchi(inchi[, allow_undefined_stereo, …])

Construct a Molecule from a InChI representation

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(*args, **kwargs)

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(*args, **kwargs)

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([toolkit_registry, …])

Generate conformers for this molecule using an underlying toolkit.

generate_unique_atom_names()

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

get_bond_between(i, j)

Returns the bond between two atoms

is_isomorphic_with(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(mapping_dict[, current_to_new])

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

strip_atom_stereochemistry(smarts[, …])

Delete stereochemistry information for certain atoms, if it is present.

to_bson()

Return a BSON serialized representation.

to_dict()

Return a dictionary representation of the molecule.

to_file(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_inchi([fixed_hydrogens, toolkit_registry])

Create an InChI string for the molecule using the requested toolkit backend.

to_inchikey([fixed_hydrogens, toolkit_registry])

Create an InChIKey for the molecule using the requested toolkit backend.

to_iupac()

Generate IUPAC name from Molecule

to_json([indent])

Return a JSON serialized representation.

to_messagepack()

Return a MessagePack representation.

to_networkx()

Generate a NetworkX undirected graph from the Molecule.

to_openeye([aromaticity_model])

Create an OpenEye molecule

to_pickle()

Return a pickle serialized representation.

to_qcschema([multiplicity, conformer, extras])

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

to_rdkit([aromaticity_model])

Create an RDKit molecule

to_smiles([isomeric, explicit_hydrogens, …])

Return a canonical isomeric SMILES representation of the current molecule.

to_toml()

Return a TOML serialized representation.

to_topology()

Return an openforcefield Topology representation containing one copy of this molecule

to_xml([indent])

Return an XML representation.

to_yaml()

Return a YAML serialized representation.

visualize([backend, width, height])

Render a visualization of the molecule in Jupyter

__init__(*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__(*args, **kwargs)

Create a new Molecule object

add_atom(atomic_number, formal_charge, …)

Add an atom

add_bond(atom1, atom2, bond_order, is_aromatic)

Add a bond between two specified atom indices

add_bond_charge_virtual_site(atoms, distance)

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.

add_conformer(coordinates)

Add a conformation of the molecule

add_divalent_lone_pair_virtual_site(atoms, …)

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(atoms, …)

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(atoms, …)

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.

assign_fractional_bond_orders([…])

Update and store list of bond orders this molecule.

assign_partial_charges(partial_charge_method)

Calculate partial atomic charges for this molecule using an underlying toolkit, and assign the new values to the partial_charges attribute.

canonical_order_atoms([toolkit_registry])

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

chemical_environment_matches(query[, …])

Retrieve all matches for a given chemical environment query.

compute_partial_charges_am1bcc([…])

Calculate partial atomic charges for this molecule using AM1-BCC run by an underlying toolkit and assign them to this molecule’s partial_charges attribute.

enumerate_protomers([max_states])

Enumerate the formal charges of a molecule to generate different protomoers.

enumerate_stereoisomers([undefined_only, …])

Enumerate the stereocenters and bonds of the current molecule.

enumerate_tautomers([max_states, …])

Enumerate the possible tautomers of the current molecule

find_rotatable_bonds([…])

Find all bonds classed as rotatable ignoring any matched to the ignore_functional_groups list.

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_inchi(inchi[, allow_undefined_stereo, …])

Construct a Molecule from a InChI representation

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(*args, **kwargs)

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(*args, **kwargs)

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([toolkit_registry, …])

Generate conformers for this molecule using an underlying toolkit.

generate_unique_atom_names()

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

get_bond_between(i, j)

Returns the bond between two atoms

is_isomorphic_with(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(mapping_dict[, current_to_new])

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

strip_atom_stereochemistry(smarts[, …])

Delete stereochemistry information for certain atoms, if it is present.

to_bson()

Return a BSON serialized representation.

to_dict()

Return a dictionary representation of the molecule.

to_file(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_inchi([fixed_hydrogens, toolkit_registry])

Create an InChI string for the molecule using the requested toolkit backend.

to_inchikey([fixed_hydrogens, toolkit_registry])

Create an InChIKey for the molecule using the requested toolkit backend.

to_iupac()

Generate IUPAC name from Molecule

to_json([indent])

Return a JSON serialized representation.

to_messagepack()

Return a MessagePack representation.

to_networkx()

Generate a NetworkX undirected graph from the Molecule.

to_openeye([aromaticity_model])

Create an OpenEye molecule

to_pickle()

Return a pickle serialized representation.

to_qcschema([multiplicity, conformer, extras])

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

to_rdkit([aromaticity_model])

Create an RDKit molecule

to_smiles([isomeric, explicit_hydrogens, …])

Return a canonical isomeric SMILES representation of the current molecule.

to_toml()

Return a TOML serialized representation.

to_topology()

Return an openforcefield Topology representation containing one copy of this molecule

to_xml([indent])

Return an XML representation.

to_yaml()

Return a YAML serialized representation.

visualize([backend, width, height])

Render a visualization of the molecule in Jupyter

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.