.. include:: ../substitutions

.. oe:namespace:: OEProton

.. meta::
   :keywords: OEEnumerateTautomers

.. oe:function:: OEEnumerateTautomers

   .. oe:language:: c++ java csharp

      .. oe:api::

         OESystem::OEIterBase<OEChem::OEMolBase>* OEEnumerateTautomers(const OEChem::OEMolBase& mol,
                                                                       const OETautomerOptions& tautomerOptions)
         OESystem::OEIterBase<OEChem::OEMCMolBase>* OEEnumerateTautomers(const OEChem::OEMCMolBase& mol,
                                                                         const OETautomerOptions& tautomerOptions)

   .. oe:language:: python

      .. oe:api:: python

         OEEnumerateTautomers(mol: OEMol, tautomerOptions: OETautomerOptions) -> Iterable[OEMol]
         OEEnumerateTautomers(mol: Union[OEGraphMol,OEQMol],
                              tautomerOptions: OETautomerOptions) -> Iterable[Union[OEGraphMol, OEMol, OEQMol]]

   This function takes a const input molecule that is to be tautomerized and the tautomers are
   returned as an ``OESystem::OEIterBase<OEChem::OEMolBase> *``.  Options are set with an
   :ref:`OETautomerOptions <OEProton_OETautomerOptions>`.  See the corresponding documentation for
   descriptions of options.  Aromaticity must be perceived on the input molecule before calling
   this function.


   .. oe:language:: c++ java csharp

      .. oe:api::

         unsigned int OEEnumerateTautomers(OEChem::OEMolBase& mol,
                                           OEMolFunctionBase& mfb,
                                           unsigned int allflag = 0,
                                           bool ch3flag = false,
                                           bool saveStereo = false,
                                           float maxTime = 120)

   .. oe:language:: python

      .. oe:api:: python

         OEEnumerateTautomers(mol: Union[OEGraphMol,OEMol,OEQMol],
                              mfb: OEMolFunctionBase, allflag: int = 0,
                              ch3flag: bool = False, saveStereo: bool = False,
                              maxTime: float = 120) -> int

   .. warning::

      This version of :oe:func:`OEProton::OEEnumerateTautomers` is
      deprecated.
      Use the above :ref:`OETautomerOptions <OEProton_OETautomerOptions>` version above instead.

   This function has four arguments.  The first argument in a
   non-const molecule that will be the basis for the tautomer
   enumeration.  For details of the enumeration process, please see
   :ref:`chapter_tautomerstheory`.  The second argument is a functor
   call-back.  The functor's ``operator()`` is called with each new
   tautomer state enumerated.  The enumeration will continue until the
   functor returns false or until the enumeration is complete.  The
   third argument is an ``unsigned int`` which indicates the maximum
   acceptable energetic category of enumerated tautomers.  The
   function will return all categories of tautomers from the lowest
   available up to this cutoff.  If the only available level is higher
   than the cutoff, that single level of tautomers will be enumerated.
   This control is in addition to the call-back control.  Finally, the
   ``bool ch3flag`` argument controls whether tautomer enumeration
   should include tautomerization of methyl and methylene groups
   adjacent to a conjugated system.  This allows
   cyclohexa-2,4-dien-1-one, ``O=C1CC=CC=C1``, to be canonicalized
   as a tautomer of phenol, ``Oc1ccccc1``.  Unfortunately, the
   combinatorial explosion from tautomerizing across the alpha carbon
   of amino acids means that this option should not be used when
   enumerating the tautomers of proteins and large peptides.  This
   function returns the total number of tautomers enumerated.

   A setting of ``saveStereo=true`` will prevent associated atoms or bonds
   from taking part in tautomerization if they have stereochemistry set.
   Stereochemistry can naturally be lost with the creation and removal of double bonds.

