.. include:: ../../toolkit-substitutions

.. oe:namespace:: OEChem


.. meta::
   :keywords: OEUniMolecularRxn, UniMolecularRxn


.. _OEChem_OEUniMolecularRxn:

.. oe:class:: OEUniMolecularRxn

   .. oe:api::


      class OEUniMolecularRxn

   The :ref:`OEUniMolecularRxn <OEChem_OEUniMolecularRxn>` class is designed to apply a
   chemical transformation to a molecule. The primary purpose of the
   class is to provide an efficient means of applying normalization
   reactions, although there are few restrictions on the types of
   chemical transformations that can be applied.  The reaction used to
   initialize the class must contain only a single reactant.  The
   provided transformation is applied iteratively until no further
   reactant patterns are matched. Caution must be used in defining the
   transformation as it is possible to provide a reaction that will
   cause a :ref:`OEUniMolecularRxn <OEChem_OEUniMolecularRxn>` object to iterate until memory
   is exhausted. For example, a reaction for which the reactant
   pattern matches the transformed product molecule will reapply the
   transformation indefinitely and must be avoided.  Note, however,
   that atoms and bonds created by a transformation are excluded from
   involvement in iterative applications of the transformation.

   .. figure:: ../images/OEUniMolecularRxn.*
      :scale:  100
      :align:  center

      **OEUniMolecularRxn**

      *Example of amine nitrogen protonation using 'OEUniMolecularRxn'. Transformations are applied to the starting material recursively*

   .. seealso::

      .. oe:language:: c++

         * :ref:`chapter_reactions` chapter
         * :term:`SMIRKS`
         * :ref:`OELibraryGen <OEChem_OELibraryGen>` class
         * Example program :ref:`unimolrxn.cpp<section_example_oechem_unimolrxn>`

      .. oe:language:: python

         * :ref:`chapter_reactions` chapter
         * :term:`SMIRKS`
         * :ref:`OELibraryGen <OEChem_OELibraryGen>` class
         * Example program :ref:`unimolrxn.py<section_example_oechem_unimolrxn>`

      .. oe:language:: java

         * :ref:`chapter_reactions` chapter
         * :term:`SMIRKS`
         * :ref:`OELibraryGen <OEChem_OELibraryGen>` class
         * Example program :ref:`UniMolRxn.java<section_example_oechem_unimolrxn>`

      .. oe:language:: csharp

         * :ref:`chapter_reactions` chapter
         * :term:`SMIRKS`
         * :ref:`OELibraryGen <OEChem_OELibraryGen>` class
         * Example program :ref:`UniMolRxn.cs<section_example_oechem_unimolrxn>`


   .. oe:method:: Constructors

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

         .. oe:api::

            OEUniMolecularRxn()

      .. oe:language:: python

         .. oe:api:: python

            OEUniMolecularRxn() -> OEUniMolecularRxn

      Default constructor.

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

         .. oe:api::

            OEUniMolecularRxn(const OEUniMolecularRxn& rhs)

      .. oe:language:: python

         .. oe:api:: python

            OEUniMolecularRxn(arg2: OEUniMolecularRxn) -> OEUniMolecularRxn

      Copy constructor.

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

         .. oe:api::

            OEUniMolecularRxn(const char * smirks, bool strictSmirks)

      .. oe:language:: python

         .. oe:api:: python

            OEUniMolecularRxn(c: str, strictSmirks: bool) -> OEUniMolecularRxn

      Creates a :ref:`OEUniMolecularRxn <OEChem_OEUniMolecularRxn>` object with a (:term:`SMIRKS`) pattern.
      Attempts to initialize an :ref:`OEUniMolecularRxn <OEChem_OEUniMolecularRxn>`
      object with a reaction that has more than one reactant will
      result in an initialization failure.
      Initialization success can be tested using the operator
      :oe:meth:`OEChem::OEUniMolecularRxn::operator bool` method.
      The second argument to the constructor is used to specify the
      interpretation of the :term:`SMIRKS` semantics.
      By default, the ``smirks`` string is interpreted using strict
      semantics via a value ``true``.

      Passing a ``smirks`` value of ``false`` to the second method argument will relax
      the strict SMIRKS restrictions.
      A mapped reactant atom that does not have a corresponding mapped
      product atom is valid, and will be destroyed as part of the
      reaction.
      Unmapped reactant atoms will be used to match the reactant
      pattern, but are not destroyed when the reaction is applied.
      The resulting :term:`SMIRKS` like reactions may therefore be
      more easily readable by humans as fewer atoms may be required to
      be mapped.

      .. seealso::

         * :oe:meth:`OEChem::OEUniMolecularRxn::Init` method
         * :term:`SMIRKS` definition describing the strict SMIRKS semantics

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

         .. oe:api::

            OEUniMolecularRxn(const char * smirks,
                              const OEChem::OEUniMolecularRxnOptions& options = OEUniMolecularRxnOptions())

      .. oe:language:: python

         .. oe:api:: python

            OEUniMolecularRxn(c: str,
                              opts: OEUniMolecularRxnOptions = OEUniMolecularRxnOptions()) -> OEUniMolecularRxn

      Creates a :ref:`OEUniMolecularRxn <OEChem_OEUniMolecularRxn>` object with a
      (:term:`SMIRKS`) pattern.  The options class argument will be interrogated to determine the desired
      strict ``smirks`` interpretation requested for the (:term:`SMIRKS`) processing.

      .. seealso::

         * :oe:meth:`OEChem::OEUniMolecularRxnOptions::GetStrictSmirks` method
         * :oe:meth:`OEChem::OEUniMolecularRxn::Init` method
         * :term:`SMIRKS` definition describing the strict SMIRKS semantics

   .. oe:method:: operator=
      :language: c++

      .. oe:api::

         OEUniMolecularRxn &operator=(const OEUniMolecularRxn &rhs)

      Assignment operator.


   .. oe:method:: operator()

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

         .. oe:api::

            bool operator()(OEMolBase& mol) const

      .. oe:language:: python

         .. oe:api:: python

            __call__(mol: Union[OEGraphMol,OEMol,OEQMol]) -> bool

      Applies the transformation that the
      :ref:`OEUniMolecularRxn <OEChem_OEUniMolecularRxn>` object contains on
      the passed :ref:`OEMolBase <OEChem_OEMolBase>` object.
      Returns ``true`` if the reactant pattern matches at least one
      time in the passed molecule.

      If the :ref:`OEUniMolecularRxn <OEChem_OEUniMolecularRxn>` fails to apply any
      transformations because the reactant pattern failed to match the
      molecule, the method will return ``false``.

   .. oe:method:: operator bool

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

         .. oe:api::

            operator bool() const

      .. oe:language:: python

         .. oe:api:: python

            IsValid() -> bool

      Returns ``true``, if the :ref:`OEUniMolecularRxn <OEChem_OEUniMolecularRxn>`
      object was initialized with no failures using either the
      constructors or one of the
      :oe:meth:`OEChem::OEUniMolecularRxn::Init` methods.

      The method will return ``false`` when the
      :ref:`OEUniMolecularRxn <OEChem_OEUniMolecularRxn>` object has not been properly
      initialized as it will be unable to apply transform operations
      to molecules.


   .. oe:method:: GetClearCoordinates

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

         .. oe:api::

            bool GetClearCoordinates() const

      .. oe:language:: python

         .. oe:api:: python

            GetClearCoordinates() -> bool

      Returns whether the coordinates of a molecule are cleared
      before performing the chemical transformation.

      .. seealso::

         * :oe:meth:`OEChem::OEUniMolecularRxn::SetClearCoordinates` method


   .. oe:method:: GetOptions

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

         .. oe:api::

            OEUniMolecularRxnOptions& GetOptions()
            const OEUniMolecularRxnOptions& GetOptions() const

      .. oe:language:: python

         .. oe:api:: python

            GetOptions() -> OEUniMolecularRxnOptions

      Returns the internal options class in the :ref:`OEUniMolecularRxn <OEChem_OEUniMolecularRxn>`
      instance.  A non-const instance supports changing the option control values for
      options that are active during transformation application.  Note that the
      ``strict`` flag processing setting occurs when the :term:`SMIRKS` or :oe:cls:`OEQMolBase<OEChem::OEQMolBase>`
      transformation is processed and not during application of the transformation.

      .. seealso::

         * :ref:`OEUniMolecularRxnOptions <OEChem_OEUniMolecularRxnOptions>` class


   .. oe:method:: GetValidateKekule

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

         .. oe:api::

            bool GetValidateKekule() const

      .. oe:language:: python

         .. oe:api:: python

            GetValidateKekule() -> bool

      Returns whether the transformation validates the |Kekule|
      form of the returned products.

      .. seealso::

         * :oe:meth:`OEChem::OEUniMolecularRxn::SetValidateKekule` method
         * :ref:`subsection_reactions_libgen_kekule` section


   .. oe:method:: Init

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

         .. oe:api::

            bool Init(const char* smirks,
                      const OEUniMolecularRxnOptions& options = OEUniMolecularRxnOptions())
            bool Init(const OEQMolBase& qmol,
                      const OEUniMolecularRxnOptions& options = OEUniMolecularRxnOptions())

      .. oe:language:: python

         .. oe:api:: python

            Init(c: str,
                 opts: OEUniMolecularRxnOptions = OEUniMolecularRxnOptions()) -> bool
            Init(arg2: OEQMol,
                 opts: OEUniMolecularRxnOptions = OEUniMolecularRxnOptions()) -> bool

      The first two method overloads initialize an :ref:`OEUniMolecularRxn <OEChem_OEUniMolecularRxn>`
      object with a ``smirks`` pattern and either the explicitly provided ``strict`` flag
      setting or via the ``strict`` setting from the provided options class.

      The next two method overloads initialize an :ref:`OEUniMolecularRxn <OEChem_OEUniMolecularRxn>`
      object with a :oe:cls:`OEQMolBase<OEChem::OEQMolBase>` object and either the explicitly provided ``strict`` flag
      setting or via the ``strict`` setting from the provided options class.

      .. seealso::

         * :oe:meth:`OEChem::OEUniMolecularRxnOptions::GetStrictSmirks` method

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

         .. oe:api::

            bool Init(const char* smirks, bool strict)
            bool Init(const OEQMolBase &, bool strictSmirks = true)

      .. oe:language:: python

         .. oe:api:: python

            Init(c: str, strictSmirks: bool) -> bool
            Init(arg2: OEQMol, strictSmirks: bool) -> bool

      Initializes an :ref:`OEUniMolecularRxn <OEChem_OEUniMolecularRxn>` object with a
      query molecule (:ref:`OEQMolBase <OEChem_OEQMolBase>`).
      If query molecule is created using the
      :oe:func:`OEChem::OEParseSmirks` function, and if the reaction is
      desired to be interpreted using strict :term:`SMIRKS` semantics,
      then the default ``true`` value for the second argument to the method
      should be used.

      Passing a value of ``false`` to the second argument will relax the
      restrictions imposed by strict SMIRKS semantics.

      .. seealso::

         * :term:`SMIRKS` definition describing the strict SMIRKS semantics


   .. oe:method:: SetClearCoordinates

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

         .. oe:api::

            bool SetClearCoordinates(bool clearcoords)

      .. oe:language:: python

         .. oe:api:: python

            SetClearCoordinates(arg2: bool) -> bool

      Sets whether the coordinates of a molecule are cleared
      before performing the chemical transformation.

     .. note::

         The :ref:`OEUniMolecularRxn <OEChem_OEUniMolecularRxn>` modifies the molecular
         graph when applying the transformations.
         Generating valid 2D or 3D coordinates for the products is
         beyond the scope of the :ref:`OEUniMolecularRxn <OEChem_OEUniMolecularRxn>`
         class.

         It is recommended to either clear the coordinates by
         invoking the :oe:meth:`OEChem::OEUniMolecularRxn::SetClearCoordinates`
         method or regenerate the coordinates of the molecule afterwards.

         If no transformation is applied the molecule will not be changed.

      .. seealso::

         * :oe:meth:`OEChem::OEUniMolecularRxn::GetClearCoordinates` method


   .. oe:method:: SetValidateKekule

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

         .. oe:api::

            bool SetValidateKekule(bool validate)

      .. oe:language:: python

         .. oe:api:: python

            SetValidateKekule(arg2: bool) -> bool

      Sets whether the generated products are simply returned after a
      Kekulization attempt, or if the |Kekule| form is validated more
      rigorously. If the extra validation is enabled and an invalid
      |Kekule| form is identified, alternatives are tried by adding
      and removing implicit hydrogens from aromatic nitrogens to
      produce a valid |Kekule| form.  No further attempt is made to
      return the most reasonable or chemically sensible result.  By
      default, the extra |Kekule| validation is enabled.

      .. seealso::

         * :ref:`subsection_reactions_libgen_kekule` section
