openforcefield.typing.chemistry.ChemicalEnvironment¶

class openforcefield.typing.chemistry.ChemicalEnvironment(smirks=None, label=None, replacements=None, toolkit=None)[source]¶

Chemical environment abstract base class that matches an atom, bond, angle, etc.

Warning

This class is largely redundant with the same one in the Chemper package, and will likely be removed.

Methods

Atom([ORtypes, ANDtypes, index, ring])	Atom representation, which may have some ORtypes and ANDtypes properties.
Bond([ORtypes, ANDtypes])	Bond representation, which may have ORtype and ANDtype descriptors.
addAtom(self, bondToAtom[, bondORtypes, …])	Add an atom to the specified target atom.
asSMIRKS(self[, smarts])	Returns a SMIRKS representation of the chemical environment
getAlphaAtoms(self)	Returns a list of atoms alpha to any indexed atom
getAlphaBonds(self)	Returns a list of Bond objects that connect
getAtoms(self)	Returns
getBetaAtoms(self)	Returns a list of atoms beta to any indexed atom
getBetaBonds(self)	Returns a list of Bond objects that connect
getBond(self, atom1, atom2)	Get bond betwen two atoms
getBondOrder(self, atom)	Returns minimum bond order around a given atom 0 if atom has no neighbors aromatic bonds count as 1.5 any bond counts as 1.0
getBonds(self[, atom])	Parameters
getComponentList(self, component_type[, …])	Returns a list of atoms or bonds matching the descriptor
getIndexedAtoms(self)	returns the list of Atom objects with an index
getIndexedBonds(self)	Returns a list of Bond objects that connect two indexed atoms
getNeighbors(self, atom)	Returns atoms that are bound to the given atom in the form of a list of Atom objects
getType(self)	Uses number of indexed atoms and bond connectivity to determine the type of chemical environment
getUnindexedAtoms(self)	returns a list of Atom objects that are not indexed
getUnindexedBonds(self)	Returns a list of Bond objects that connect
getValence(self, atom)	Returns the valence (number of neighboring atoms) around the given atom
isAlpha(self, component)	Takes an atom or bond are returns True if it is alpha to an indexed atom
isBeta(self, component)	Takes an atom or bond are returns True if it is beta to an indexed atom
isIndexed(self, component)	returns True if the atom or bond is indexed
isUnindexed(self, component)	returns True if the atom or bond is not indexed
isValid(self[, smirks])	Returns if the environment is valid, that is if it creates a parseable SMIRKS string.
removeAtom(self, atom[, onlyEmpty])	Remove the specified atom from the chemical environment.
selectAtom(self[, descriptor])	Select a random atom fitting the descriptor.
selectBond(self[, descriptor])	Select a random bond fitting the descriptor.
validate(smirks[, ensure_valence_type, toolkit])	Validate the provided SMIRKS string is valid, and if requested, tags atoms appropriate to the specified valence type.

__init__(self, smirks=None, label=None, replacements=None, toolkit=None)[source]¶

Initialize a chemical environment abstract base class.

smirks = string, optional

if smirks is not None, a chemical environment is built from the provided SMIRKS string

label = anything, optional

intended to be used to label this chemical environment could be a string, int, or float, or anything

replacements = list of lists, optional,

[substitution, smarts] form for parsing SMIRKS

toolkit = string. Default = None

Either ‘openeye’ or ‘rdkit’, indicating the backend to use for chemical perception. If None, this function will use OpenEye if possible, otherwise will use RDKit.

Methods

__init__(self[, smirks, label, …])	Initialize a chemical environment abstract base class.
addAtom(self, bondToAtom[, bondORtypes, …])	Add an atom to the specified target atom.
asSMIRKS(self[, smarts])	Returns a SMIRKS representation of the chemical environment
getAlphaAtoms(self)	Returns a list of atoms alpha to any indexed atom
getAlphaBonds(self)	Returns a list of Bond objects that connect
getAtoms(self)	Returns
getBetaAtoms(self)	Returns a list of atoms beta to any indexed atom
getBetaBonds(self)	Returns a list of Bond objects that connect
getBond(self, atom1, atom2)	Get bond betwen two atoms
getBondOrder(self, atom)	Returns minimum bond order around a given atom 0 if atom has no neighbors aromatic bonds count as 1.5 any bond counts as 1.0
getBonds(self[, atom])	Parameters
getComponentList(self, component_type[, …])	Returns a list of atoms or bonds matching the descriptor
getIndexedAtoms(self)	returns the list of Atom objects with an index
getIndexedBonds(self)	Returns a list of Bond objects that connect two indexed atoms
getNeighbors(self, atom)	Returns atoms that are bound to the given atom in the form of a list of Atom objects
getType(self)	Uses number of indexed atoms and bond connectivity to determine the type of chemical environment
getUnindexedAtoms(self)	returns a list of Atom objects that are not indexed
getUnindexedBonds(self)	Returns a list of Bond objects that connect
getValence(self, atom)	Returns the valence (number of neighboring atoms) around the given atom
isAlpha(self, component)	Takes an atom or bond are returns True if it is alpha to an indexed atom
isBeta(self, component)	Takes an atom or bond are returns True if it is beta to an indexed atom
isIndexed(self, component)	returns True if the atom or bond is indexed
isUnindexed(self, component)	returns True if the atom or bond is not indexed
isValid(self[, smirks])	Returns if the environment is valid, that is if it creates a parseable SMIRKS string.
removeAtom(self, atom[, onlyEmpty])	Remove the specified atom from the chemical environment.
selectAtom(self[, descriptor])	Select a random atom fitting the descriptor.
selectBond(self[, descriptor])	Select a random bond fitting the descriptor.
validate(smirks[, ensure_valence_type, toolkit])	Validate the provided SMIRKS string is valid, and if requested, tags atoms appropriate to the specified valence type.

class Atom(ORtypes=None, ANDtypes=None, index=None, ring=None)[source]¶

Atom representation, which may have some ORtypes and ANDtypes properties.

Attributes

ORtypeslist of tuples in the form (base, [list of decorators])

where bases and decorators are both strings The descriptor types that will be combined with logical OR

ANDtypeslist of string

The descriptor types that will be combined with logical AND

Methods

addANDtype(self, ANDtype)	Adds ANDtype to the set for this atom.
addORtype(self, ORbase, ORdecorators)	Adds ORtype to the set for this atom.
asSMARTS(self)	Return the atom representation as SMARTS.
asSMIRKS(self)	Return the atom representation as SMIRKS.
getANDtypes(self)	returns a copy of the list of ANDtypes for this atom
getORtypes(self)	returns a copy of the dictionary of ORtypes for this atom
setANDtypes(self, newANDtypes)	sets new ANDtypes for this atom
setORtypes(self, newORtypes)	sets new ORtypes for this atom

asSMARTS(self)[source]¶

Return the atom representation as SMARTS.

Returns

smartsstr

The SMARTS string for this atom

asSMIRKS(self)[source]¶

Return the atom representation as SMIRKS.

Returns

smirksstr

The SMIRKS string for this atom

addORtype(self, ORbase, ORdecorators)[source]¶

Adds ORtype to the set for this atom.

Parameters

ORbase: string, such as ‘#6’

ORdecorators: list of strings, such as [‘X4’,’+0’]

addANDtype(self, ANDtype)[source]¶

Adds ANDtype to the set for this atom.

Parameters

ANDtype: string

added to the list of ANDtypes for this atom

getORtypes(self)[source]¶

returns a copy of the dictionary of ORtypes for this atom

setORtypes(self, newORtypes)[source]¶

sets new ORtypes for this atom

Parameters

newORtypes: list of tuples in the form (base, [ORdecorators])

for example: (‘#6’, [‘X4’,’H0’,’+0’]) –> ‘#6X4H0+0’

getANDtypes(self)[source]¶

returns a copy of the list of ANDtypes for this atom

setANDtypes(self, newANDtypes)[source]¶

sets new ANDtypes for this atom

Parameters

newANDtypes: list of strings

strings that will be AND’d together in a SMARTS

class Bond(ORtypes=None, ANDtypes=None)[source]¶

Bond representation, which may have ORtype and ANDtype descriptors.

Attributes

ORtypeslist of tuples of ORbases and ORdecorators

in form (base: [list of decorators]) The ORtype types that will be combined with logical OR

ANDtypeslist of string

The ANDtypes that will be combined with logical AND

Methods

addANDtype(self, ANDtype)	Adds ANDtype to the set for this atom.
addORtype(self, ORbase, ORdecorators)	Adds ORtype to the set for this atom.
asSMARTS(self)	Return the atom representation as SMARTS.
asSMIRKS(self)	Returns
getANDtypes(self)	returns a copy of the list of ANDtypes for this atom
getORtypes(self)	returns a copy of the dictionary of ORtypes for this atom
getOrder(self)	Returns a float for the order of this bond for multiple ORtypes or ~ it returns the minimum possible order the intended application is for checking valence around a given atom
setANDtypes(self, newANDtypes)	sets new ANDtypes for this atom
setORtypes(self, newORtypes)	sets new ORtypes for this atom

asSMARTS(self)[source]¶

Return the atom representation as SMARTS.

Returns

smartsstr

The SMARTS string for just this atom

asSMIRKS(self)[source]¶

Returns

smartsstr

The SMIRKS string for just this bond

getOrder(self)[source]¶

Returns a float for the order of this bond for multiple ORtypes or ~ it returns the minimum possible order the intended application is for checking valence around a given atom

addANDtype(self, ANDtype)¶

Adds ANDtype to the set for this atom.

Parameters

ANDtype: string

added to the list of ANDtypes for this atom

addORtype(self, ORbase, ORdecorators)¶

Adds ORtype to the set for this atom.

Parameters

ORbase: string, such as ‘#6’

ORdecorators: list of strings, such as [‘X4’,’+0’]

getANDtypes(self)¶

returns a copy of the list of ANDtypes for this atom

getORtypes(self)¶

returns a copy of the dictionary of ORtypes for this atom

setANDtypes(self, newANDtypes)¶

sets new ANDtypes for this atom

Parameters

newANDtypes: list of strings

strings that will be AND’d together in a SMARTS

setORtypes(self, newORtypes)¶

sets new ORtypes for this atom

Parameters

newORtypes: list of tuples in the form (base, [ORdecorators])

for example: (‘#6’, [‘X4’,’H0’,’+0’]) –> ‘#6X4H0+0’

static validate(smirks, ensure_valence_type=None, toolkit='openeye')[source]¶

Validate the provided SMIRKS string is valid, and if requested, tags atoms appropriate to the specified valence type.

Parameters

smirksstr

The SMIRKS expression to validate

ensure_valence_typestr, optional, default=None

If specified, ensure the tagged atoms are appropriate to the specified valence type

This method will raise a :class:`SMIRKSParsingError` if the provided SMIRKS string is not valid.

isValid(self, smirks=None)[source]¶

Returns if the environment is valid, that is if it creates a parseable SMIRKS string.

asSMIRKS(self, smarts=False)[source]¶

Returns a SMIRKS representation of the chemical environment

Parameters

smarts: optional, boolean

if True, returns a SMARTS instead of SMIRKS without index labels

selectAtom(self, descriptor=None)[source]¶

Select a random atom fitting the descriptor.

Parameters

descriptor: optional, None

None - returns any atom with equal probability int - will return an atom with that index ‘Indexed’ - returns a random indexed atom ‘Unindexed’ - returns a random unindexed atom ‘Alpha’ - returns a random alpha atom ‘Beta’ - returns a random beta atom

Returns

a single Atom object fitting the description

or None if no such atom exists

getComponentList(self, component_type, descriptor=None)[source]¶

Returns a list of atoms or bonds matching the descriptor

Parameters

component_type: string: ‘atom’ or ‘bond’

descriptor: string, optional

‘all’, ‘Indexed’, ‘Unindexed’, ‘Alpha’, ‘Beta’

selectBond(self, descriptor=None)[source]¶

Select a random bond fitting the descriptor.

Parameters

descriptor: optional, None

None - returns any bond with equal probability int - will return an bond with that index ‘Indexed’ - returns a random indexed bond ‘Unindexed’ - returns a random unindexed bond ‘Alpha’ - returns a random alpha bond ‘Beta’ - returns a random beta bond

Returns

a single Bond object fitting the description

or None if no such atom exists

addAtom(self, bondToAtom, bondORtypes=None, bondANDtypes=None, newORtypes=None, newANDtypes=None, newAtomIndex=None, newAtomRing=None, beyondBeta=False)[source]¶

Add an atom to the specified target atom.

Parameters

bondToAtom: atom object, required

atom the new atom will be bound to

bondORtypes: list of tuples, optional

strings that will be used for the ORtypes for the new bond

bondANDtypes: list of strings, optional

strings that will be used for the ANDtypes for the new bond

newORtypes: list of strings, optional

strings that will be used for the ORtypes for the new atom

newANDtypes: list of strings, optional

strings that will be used for the ANDtypes for the new atom

newAtomIndex: int, optional

integer label that could be used to index the atom in a SMIRKS string

beyondBeta: boolean, optional

if True, allows bonding beyond beta position

Returns

newAtom: atom object for the newly created atom

removeAtom(self, atom, onlyEmpty=False)[source]¶

Remove the specified atom from the chemical environment. if the atom is not indexed for the SMIRKS string or used to connect two other atoms.

Parameters

atom: atom object, required

atom to be removed if it meets the conditions.

onlyEmpty: boolean, optional

True only an atom with no ANDtypes and 1 ORtype can be removed

Returns

Boolean True: atom was removed, False: atom was not removed

getAtoms(self)[source]¶

Returns

list of atoms in the environment

getBonds(self, atom=None)[source]¶

Parameters

atom: Atom object, optional, returns bonds connected to atom

returns all bonds in fragment if atom is None

Returns

a complete list of bonds in the fragment

getBond(self, atom1, atom2)[source]¶

Get bond betwen two atoms

Parameters

atom1 and atom2: atom objects

Returns

bond object between the atoms or None if no bond there

getIndexedAtoms(self)[source]¶

returns the list of Atom objects with an index

getUnindexedAtoms(self)[source]¶

returns a list of Atom objects that are not indexed

getAlphaAtoms(self)[source]¶

Returns a list of atoms alpha to any indexed atom

that are not also indexed

getBetaAtoms(self)[source]¶

Returns a list of atoms beta to any indexed atom

that are not alpha or indexed atoms

getIndexedBonds(self)[source]¶

Returns a list of Bond objects that connect two indexed atoms

getUnindexedBonds(self)[source]¶

Returns a list of Bond objects that connect

an indexed atom to an unindexed atom two unindexed atoms

getAlphaBonds(self)[source]¶

Returns a list of Bond objects that connect

an indexed atom to alpha atoms

getBetaBonds(self)[source]¶

Returns a list of Bond objects that connect

alpha atoms to beta atoms

isAlpha(self, component)[source]¶

Takes an atom or bond are returns True if it is alpha to an indexed atom

isUnindexed(self, component)[source]¶

returns True if the atom or bond is not indexed

isIndexed(self, component)[source]¶

returns True if the atom or bond is indexed

isBeta(self, component)[source]¶

Takes an atom or bond are returns True if it is beta to an indexed atom

getType(self)[source]¶

Uses number of indexed atoms and bond connectivity to determine the type of chemical environment

Returns

chemical environemnt type:

‘Atom’, ‘Bond’, ‘Angle’, ‘ProperTorsion’, ‘ImproperTorsion’ None if number of indexed atoms is 0 or > 4

getNeighbors(self, atom)[source]¶

Returns atoms that are bound to the given atom in the form of a list of Atom objects

getValence(self, atom)[source]¶

Returns the valence (number of neighboring atoms) around the given atom

getBondOrder(self, atom)[source]¶

Returns minimum bond order around a given atom 0 if atom has no neighbors aromatic bonds count as 1.5 any bond counts as 1.0