.. oe:namespace:: OEChem

.. meta::
   :keywords: OESubSearch, SubSearch


.. _OEChem_OESubSearch:

.. oe:class:: OESubSearch

   .. oe:api::

      class OESubSearch

   This class represents `OESubSearch`.

   The :ref:`OESubSearch <OEChem_OESubSearch>` class performs substructure searches,
   also known as subgraph isomorphism determination, on molecular graphs.
   In a molecular graph, atoms are considered nodes and bonds are edges.
   The :ref:`OESubSearch <OEChem_OESubSearch>` class is capable of performing both
   colored and uncolored graph comparison.  The 'color' properties of a
   query graph are stored as expression trees associated with atoms and
   bonds of a query molecule.

   .. seealso::

      * :ref:`section_patternmatch_sss` section
      * :ref:`chapter_mdlqueries` chapter

   .. admonition:: Code Example

      * :ref:`section_example_oechem_molgrep` example

   .. 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.

   .. oe:method:: Constructors

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

         .. oe:api::

            OESubSearch()

      .. oe:language:: python

         .. oe:api:: python

            OESubSearch() -> OESubSearch

      Default constructor.

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

         .. oe:api::

            OESubSearch(const OESubSearch& rhs)

      .. oe:language:: python

         .. oe:api:: python

            OESubSearch(arg2: OESubSearch) -> OESubSearch

      Copy constructor.

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

         .. oe:api::

            OESubSearch(const OEQMolBase& qmol)

      .. oe:language:: python

         .. oe:api:: python

            OESubSearch(arg2: OEQMol) -> OESubSearch

      Constructs an :ref:`OESubSearch <OEChem_OESubSearch>` object using
      a query molecule (:ref:`OEQMolBase <OEChem_OEQMolBase>`). Query molecules must
      have atom and bond expressions (see
      :oe:meth:`OEChem::OEQMolBase::BuildExpressions`) built for the entire
      molecule before being passed to this constructor.  Failure to do so
      will result in the :ref:`OESubSearch <OEChem_OESubSearch>` object being
      constructed as uninitialized.

      .. note::

        The :ref:`OESubSearch <OEChem_OESubSearch>` object will store its own copy of the
        given query molecule, and the :oe:meth:`OEChem::OESubSearch::Match`
        method will return matches between copied query and the target.

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

         .. oe:api::

            OESubSearch(const OEMolBase& mol, unsigned int aexpr,
                        unsigned int bexpr)

      .. oe:language:: python

         .. oe:api:: python

            OESubSearch(mol: Union[OEGraphMol,OEMol,OEQMol], aexpr: int,
                        bexpr: int) -> OESubSearch

      Constructs an :ref:`OESubSearch <OEChem_OESubSearch>` object using
      a molecule and expression options.  The atom and bond expression
      options passed as the second and third arguments to the method are
      defined in the :oe:constns:`OEChem::OEExprOpts` namespace.  The
      expression options are used to convert the atom and bond data into
      expression trees which are used during the subgraph search.

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

         .. oe:api::

            OESubSearch(const char* smarts, bool allowReorderAtoms = true)

      .. oe:language:: python

         .. oe:api:: python

            OESubSearch(smarts: str, allowReorderAtoms: bool = False) -> OESubSearch

      Constructs an :ref:`OESubSearch <OEChem_OESubSearch>` object using
      a :term:`SMARTS` pattern that is passed as the first argument to the
      constructor.
      The second argument of the method determines the traversal order used
      in subgraph isomorphism detection. This argument is currently not
      used, therefore the traversal order always reflects the atom and bond
      ordering of the passed :term:`SMARTS` pattern.

      ..  The Boolean reorder flag determines the match order of the query atoms
          and bonds.  If reorder is set to ``true`` then the atoms and bonds will be
          matched in an arbitrary order.  If ``false``, atoms and bonds will be
          matched in the order that they appear in the query molecule.

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

      .. oe:api::

         OESubSearch &operator=(const OESubSearch &rhs)

      Assignment operator that copies the data of the 'rhs' :ref:`OESubSearch <OEChem_OESubSearch>` object
      into the right-hand side :ref:`OESubSearch <OEChem_OESubSearch>` object.

      Assignment operator.


   .. oe:method:: operator bool

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

         .. oe:api::

            operator bool() const

      .. oe:language:: python

         .. oe:api:: python

            IsValid() -> bool

      Tests whether initialization of an :ref:`OESubSearch <OEChem_OESubSearch>` object
      is successful .  If initialization was attempted with an invalid
      :term:`SMARTS` pattern or query molecule then this method will return ``false``.
      If initialization was completed successfully this method will return
      ``true``.  An :ref:`OESubSearch <OEChem_OESubSearch>` object is considered to be
      uninitialized when constructed with the default constructor.

   .. oe:method:: AddConstraint

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

         .. oe:api::

            bool AddConstraint(const OEMatchPair<OEAtomBase> &)
            bool AddConstraint(const OEMatchPair<OEBondBase> &)

      .. oe:language:: python

         .. oe:api:: python

            AddConstraint(arg2: OEMatchPairAtom) -> bool
            AddConstraint(arg2: OEMatchPairBond) -> bool

      The search space of a subgraph isomorphism determination can be
      restricted by constraining pairs of nodes or edges (atoms or bonds) to
      be mapped onto one another in all valid subgraph solutions.  Failure
      to satisfy atom or bond pairwise constraints will prevent any subgraph
      solutions from being identified by any of the match methods in
      :ref:`OESubSearch <OEChem_OESubSearch>`.  Both
      :oe:meth:`OEChem::OESubSearch::AddConstraint` methods return ``true`` if a
      constraint is added successfully.  If the pattern atom or bond in the
      :ref:`OEMatchPair <OEChem_OEMatchPair>` does not exist as part of the query
      molecule created in the initialization of the
      :ref:`OESubSearch <OEChem_OESubSearch>` object then
      :oe:meth:`OEChem::OESubSearch::AddConstraint` will return ``false``.
      Multiple calls :oe:meth:`OEChem::OESubSearch::AddConstraint` using the same
      pattern atom or bond will cause previously stored constraints to be
      overwritten as constraints are mutually exclusive.  It is impossible to
      satisfy multiple simultaneous constraints for a single pattern atom or bond,
      hence the exclusivity.

   .. oe:method:: AtomMatch

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

         .. oe:api::

            bool AtomMatch(const OEAtomBase *) const

      .. oe:language:: python

         .. oe:api:: python

            AtomMatch(arg2: OEAtomBase) -> bool

      Searches for a single valid subgraph isomorphism starting with the
      passed target atom mapped to the first pattern atom with which the
      :ref:`OESubSearch <OEChem_OESubSearch>` was initialized. If a valid subgraph is
      identified the method will return ``true``. This method is the effective
      combination of sequential calls to
      :oe:meth:`OEChem::OESubSearch::AddConstraint` followed by
      :oe:meth:`OEChem::OESubSearch::SingleMatch`.

      .. oe:api: IGNORED - NOT IMPLEMENTED YET

         bool AtomMatch(const OEQAtomBase *) const


   .. oe:method:: ClearConstraints

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

         .. oe:api::

            void ClearConstraints()

      .. oe:language:: python

         .. oe:api:: python

            ClearConstraints() -> None

      Eliminates all prior match constraints set with the
      :oe:meth:`OEChem::OESubSearch::AddConstraint` method.

   .. oe:method:: GetMaxMatches

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

         .. oe:api::

            unsigned int GetMaxMatches() const

      .. oe:language:: python

         .. oe:api:: python

            GetMaxMatches() -> int

      Returns the maximum number of subgraph isomorphism solutions that the
      :ref:`OESubSearch <OEChem_OESubSearch>` object will identify before
      terminating the search.  A value of zero indicates that no arbitrary
      limit has been set on the total number of subgraph isomorphism
      solutions to be identified.
      By default, the maximum number of matches is set to ``1024``.

      .. seealso::

         * :oe:meth:`OEChem::OESubSearch::SetMaxMatches`

   .. oe:method:: GetPattern

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

         .. oe:api::

            const OEQMolBase& GetPattern() const

      .. oe:language:: python

         .. oe:api:: python

            GetPattern() -> OEQMol

      Returns the read-only reference to the query molecule contained in an
      :ref:`OESubSearch <OEChem_OESubSearch>` object.
      Const :ref:`OEQMolBase <OEChem_OEQMolBase>` methods can be used to interrogate
      the returned :ref:`OEQMolBase <OEChem_OEQMolBase>` reference.  If the
      :ref:`OESubSearch <OEChem_OESubSearch>` object has not been initialized, a reference
      to an empty molecule will be returned.

   .. oe:method:: Init

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

         .. oe:api::

            bool Init(const OEQMolBase &)

      .. oe:language:: python

         .. oe:api:: python

            Init(arg2: OEQMol) -> bool

      (Re)initializes an :ref:`OESubSearch <OEChem_OESubSearch>` object with a query
      molecule (:ref:`OEQMolBase <OEChem_OEQMolBase>`) reference. The method will
      return ``true`` if initialization completes successfully, and ``false`` upon
      failure.  Prior state information is cleared before initialization,
      and is lost even if the method fails to initialize properly.

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

         .. oe:api::

            bool Init(const char* smarts, bool allowReorderAtoms = false)

      .. oe:language:: python

         .. oe:api:: python

            Init(smarts: str, allowReorderAtoms: bool = False) -> bool

      (Re)initializes an :ref:`OESubSearch <OEChem_OESubSearch>` object
      with a :term:`SMARTS` pattern, which is parsed to create a query molecule
      available for substructure search.  The method will return ``true`` if
      initialization completes successfully, and ``false`` upon failure.  Prior
      state information is cleared before initialization, and is lost even
      if the method fails to initialize properly.  The second argument of
      the method determines the traversal order used in subgraph isomorphism
      detection. This argument is currently not used, therefore the
      traversal order always reflects the atom and bond ordering of the
      passed :term:`SMARTS` pattern.

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

         .. oe:api::

            bool Init(const OEMolBase& mol, unsigned int atomexpr,
                      unsigned int bondexpr)

      .. oe:language:: python

         .. oe:api:: python

            Init(mol: Union[OEGraphMol,OEMol,OEQMol], aexpr: int, bexpr: int) -> bool

      (Re)initializes an :ref:`OESubSearch <OEChem_OESubSearch>` object using a
      molecule and expression options that are used to convert the given
      molecule into a :ref:`OEQMolBase <OEChem_OEQMolBase>` query object.

      *mol*
        The *query* molecule of the maximum common substructure search.

      *atomexpr*
        This value has to be any combination of atom expressions of the
        :oe:constns:`OEChem::OEExprOpts` namespace.

      *bondexpr*
        This value has to be any combination of bond expressions of the
        :oe:constns:`OEChem::OEExprOpts` namespace.

      Expression options are used to convert the atom and bond data into
      expression trees which are  used during the substructure search
      to map atoms and bonds.
      The method will return ``true`` if initialization completes successfully,
      and ``false`` upon failure.

      .. note::

         Prior state information is cleared before initialization, and
         is lost even if the method fails to initialize properly.

      .. seealso::

         * :oe:constns:`OEChem::OEExprOpts` namespace

   .. oe:method:: Match

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

         .. oe:api::

            OESystem::OEIterBase<OEMatchBase>* Match(const OEMolBase& mol,
                                                     bool uniquematch = false) const

      .. oe:language:: python

         .. oe:api:: python

            Match(arg2: Union[OEGraphMol,OEMol], uniquematch: bool = False) -> Iterable[OEMatchBase]

      Performs search in order to identify subgraphs of :ref:`OEMolBase <OEChem_OEMolBase>`
      which are isomorphic to the graph with which an
      :ref:`OESubSearch <OEChem_OESubSearch>` object was initialized.
      It returns an iterator pointer (:ref:`OEIterBase <OESystem_OEIterBase>`)
      over graph matches (:ref:`OEMatchBase <OEChem_OEMatchBase>`), and should be
      assigned to an :ref:`OEIter <OESystem_OEIter>` < :ref:`OEMatchBase <OEChem_OEMatchBase>` >
      in order to prevent memory leaks.

      *mol*
         The target molecule in which the substructure is identified.

      *uniquematch*
         By default all possible subgraphs up to and including
         the maximum number of matches are returned by these methods.
         If this parameters is ``true`` then only the unique
         matches will be included in the iterator over the matches.  A match or
         subgraph is considered unique if it differs from all other subgraphs
         found previously by at least one atom.  Two subgraph matches
         which cover the same atoms, albeit in different orders, will
         be called duplicates and the subgraph found later in the search will
         be discarded.

      .. oe:api: IGNORED - NOT IMPLEMENTED YET

         OESystem::OEIterBase<OEMatchBase> *Match(const OEQMolBase &,
                                                  bool uniquematch=false) const


   .. oe:method:: SetMaxMatches

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

         .. oe:api::

            bool SetMaxMatches(unsigned int m)

      .. oe:language:: python

         .. oe:api:: python

            SetMaxMatches(m: int) -> bool

      Sets the maximum number of subgraphs to be determined by the
      :oe:meth:`OEChem::OESubSearch::Match` method.  Once the maximum number of
      subgraphs have been found the search for additional subgraphs is
      terminated.  By default, maximum number of matches is set to ``1024``. The
      constraint on the maximum number of matches can be removed by calling
      this method with a value of zero.

      .. seealso::

         * :oe:meth:`OEChem::OESubSearch::GetMaxMatches`


   .. oe:method:: SingleMatch

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

         .. oe:api::

            bool SingleMatch(const OEMolBase &) const

      .. oe:language:: python

         .. oe:api:: python

            SingleMatch(arg2: Union[OEGraphMol,OEMol]) -> bool

      Returns ``true``, if a single subgraph isomorphism is detected in the
      molecule passed as the function argument. If no subgraph isomorphism
      is detected the method will return ``false``.

      .. oe:api: IGNORED - NOT IMPLEMENTED YET

         bool SingleMatch(const OEQMolBase &) const

   .. seealso::

      .. oe:language:: c++

         * Example program :ref:`molgrep.cpp<section_example_oechem_molgrep>`

      .. oe:language:: python

         * Example program :ref:`molgrep.py<section_example_oechem_molgrep>`

      .. oe:language:: java

         * Example program :ref:`MolGrep.java<section_example_oechem_molgrep>`

      .. oe:language:: csharp

         * Example program :ref:`MolGrep.cs<section_example_oechem_molgrep>`
