# openforcefield.typing.chemistry.ChemicalEnvironment

class `openforcefield.typing.chemistry.``ChemicalEnvironment`(smirks=None, label=None, replacements=None, toolkit=None)

  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)

    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)

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

    Attributes
      ORtypes list 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

      ANDtypes list 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)

      Return the atom representation as SMARTS.

      Returns
        smarts str
        The SMARTS string for this atom
    `asSMIRKS`(self)

      Return the atom representation as SMIRKS.

      Returns
        smirks str
        The SMIRKS string 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’]
    `addANDtype`(self, ANDtype)

      Adds ANDtype to the set for this atom.

      Parameters
        ANDtype: string

          added to the list of ANDtypes for this atom

    `getORtypes`(self)

      returns a copy of the dictionary of ORtypes for this atom

    `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’

    `getANDtypes`(self)

      returns a copy of the list of ANDtypes 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

  class `Bond`(ORtypes=None, ANDtypes=None)

    Bond representation, which may have ORtype and ANDtype descriptors.

    Attributes
      ORtypes list of tuples of ORbases and ORdecorators

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

      ANDtypes list 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)

      Return the atom representation as SMARTS.

      Returns
        smarts str

          The SMARTS string for just this atom

    `asSMIRKS`(self)
      Returns
        smarts str

          The SMIRKS string for just this bond

    `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

    `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')

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

    Parameters
      smirks str

        The SMIRKS expression to validate

      ensure_valence_type str, 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)

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

  `asSMIRKS`(self, smarts=False)

    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)

    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)

    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)

    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)

    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)

    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)
    Returns
      list of atoms in the environment
  `getBonds`(self, atom=None)
    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)

    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)

    returns the list of Atom objects with an index

  `getUnindexedAtoms`(self)

    returns a list of Atom objects that are not indexed

  `getAlphaAtoms`(self)
    Returns a list of atoms alpha to any indexed atom

      that are not also indexed

  `getBetaAtoms`(self)
    Returns a list of atoms beta to any indexed atom

      that are not alpha or indexed atoms

  `getIndexedBonds`(self)

    Returns a list of Bond objects that connect two indexed atoms

  `getUnindexedBonds`(self)
    Returns a list of Bond objects that connect

      an indexed atom to an unindexed atom two unindexed atoms

  `getAlphaBonds`(self)
    Returns a list of Bond objects that connect

      an indexed atom to alpha atoms

  `getBetaBonds`(self)
    Returns a list of Bond objects that connect

      alpha atoms to beta atoms

  `isAlpha`(self, component)

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

  `isUnindexed`(self, component)

    returns True if the atom or bond is not indexed

  `isIndexed`(self, component)

    returns True if the atom or bond is indexed

  `isBeta`(self, component)

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

  `getType`(self)

    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)

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

  `getValence`(self, atom)

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

  `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