.. include:: ../substitutions

.. oe:namespace:: OEChem

.. meta::
   :keywords: OEPrepareSearch

..  _oechem_oepreparesearch:

.. oe:function:: OEPrepareSearch

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

      .. oe:api::

         void OEPrepareSearch(OEMolBase& mol, const OESubSearch& subs,
                              bool adjustH = false)

   .. oe:language:: python

      .. oe:api:: python

         OEPrepareSearch(mol: Union[OEGraphMol,OEMol,OEQMol],
                         subs: OESubSearch, adjustH: bool = False) -> None

   Perceives the atom and bond properties of the given **target** molecule
   that are necessary to successfully execute the given substructure search.

   * The :oe:func:`OEChem::OEAssignAromaticFlags` function is called if
     the aromaticity of the molecule is not perceived yet.
     The aromaticity is also re-perceived if it does not match the
     aromaticity model of the query molecule stored in the given
     :ref:`OESubSearch <OEChem_OESubSearch>` object.  If the query does not
     have an aromatic model specified after processing (e.g., SMARTS, SMIRKS input),
     the target is re-perceived with the default :oe:const:`OEChem::OEAroModel::OpenEye`
     aromaticity model.

   * The :oe:func:`OEChem::OEPerceiveChiral` function is called if the
     chirality of the given molecule is not perceived yet.

   * The :oe:func:`OEChem::OEAssignHybridization` function is called if the
     hybridization perception is required by the query molecule stored
     in the :ref:`OESubSearch <OEChem_OESubSearch>` object.

   * Attempts to perceive atom stereo from other information (such as 3D,
     bond stereo or atom parity) if the atom stereo is required by the
     query molecule stored in the :ref:`OESubSearch <OEChem_OESubSearch>` object.

   * Attempts to perceive bond stereo from 2D or 3D  coordinates if
     the bond stereo is required by the query molecule stored in the
     :ref:`OESubSearch <OEChem_OESubSearch>` object.

   * If the **adjustH** parameter is ``true``, and

     * the query molecule of the substructure search has any explicit hydrogen
       expressions but no implicit ones, then
       :oe:func:`OEChem::OEAddExplicitHydrogens` is called on the
       given **target** molecule.

     * the query molecule of the substructure search has any implicit hydrogen
       expressions but no explicit ones, then
       :oe:func:`OEChem::OESuppressHydrogens` is called on the
       given **target** molecule.

   .. warning::

      If the query molecule has both explicit and implicit hydrogens then the
      hydrogens on the **target** molecule can not be adjusted accordingly,
      and the substructure search could fail. Therefore it is highly recommended
      to **not mix** explicit and implicit hydrogens in the query molecule.

   .. hint::

      It is a good practice to call the :oe:func:`OEChem::OEPrepareSearch`
      function before calling any of the following methods:

      * :oe:meth:`OEChem::OESubSearch::AtomMatch`
      * :oe:meth:`OEChem::OESubSearch::Match`
      * :oe:meth:`OEChem::OESubSearch::SingleMatch`

      If there is any atom or bond property that is not perceived but it
      is necessary to successfully execute the substructure search,
      then the above methods throw a warning.
      These warnings can be suppressed by calling the
      :oe:func:`OEChem::OEPrepareSearch` function.

   .. seealso::

      * :ref:`OESubSearch <OEChem_OESubSearch>` class
      * :oe:func:`OEChem::OEHasExplicitHydrogenExpression` function
      * :oe:func:`OEChem::OEHasImplicitHydrogenExpression` function
