.. oe:namespace:: OEChem

.. meta::
   :keywords: OEMCSSearch, MCSSearch


.. _OEChem_OEMCSSearch:

.. oe:class:: OEMCSSearch

   .. oe:api::

      class OEMCSSearch

   This class represents `OEMCSSearch`.

   This :ref:`OEMCSSearch <OEChem_OEMCSSearch>` class identifies a set of
   maximum substructures common to two molecules.

   .. seealso::

      .. oe:language:: c++

         * :ref:`section_patternmatch_mcss` section
         * Example program :ref:`mcs3dalign.cpp<section_example_oechem_mcs3dalign>`

      .. oe:language:: python

         * :ref:`section_patternmatch_mcss` section
         * Example program :ref:`mcs3dalign.py<section_example_oechem_mcs3dalign>`

      .. oe:language:: java

         * :ref:`section_patternmatch_mcss` section
         * Example program :ref:`MCS3DAlign.java<section_example_oechem_mcs3dalign>`

      .. oe:language:: csharp

         * :ref:`section_patternmatch_mcss` section
         * Example program :ref:`MCS3DAlign.cs<section_example_oechem_mcs3dalign>`

   .. oe:method:: Constructors

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

         .. oe:api::

            OEMCSSearch(unsigned int type = OEMCSType::Default)

      .. oe:language:: python

         .. oe:api:: python

            OEMCSSearch(type: int) -> OEMCSSearch

      Default constructor.

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

         .. oe:api::

            OEMCSSearch(const OEMCSSearch& rhs)

      .. oe:language:: python

         .. oe:api:: python

            OEMCSSearch(arg2: OEMCSSearch) -> OEMCSSearch

      Copy constructor.

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

         .. oe:api::

            OEMCSSearch(const char* smarts,
                        unsigned int type = OEMCSType::Default)

      .. oe:language:: python

         .. oe:api:: python

            OEMCSSearch(arg2: str, type: int) -> OEMCSSearch

      Constructs an :ref:`OEMCSSearch <OEChem_OEMCSSearch>` object using a 'smarts' pattern.
      The :term:`SMARTS` pattern is parsed into a query molecule
      (:ref:`OEQMolBase <OEChem_OEQMolBase>`).
      The valid types of the :ref:`OEMCSSearch <OEChem_OEMCSSearch>` are defined
      in the :oe:constns:`OEChem::OEMCSType` namespace.

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

         .. oe:api::

            OEMCSSearch(const OEQMolBase& qmol, bool perception = true,
                        unsigned int type = OEMCSType::Default)

      .. oe:language:: python

         .. oe:api:: python

            OEMCSSearch(arg2: OEQMol, makeCopy: bool = True, type: int) -> OEMCSSearch

      Constructs an :ref:`OEMCSSearch <OEChem_OEMCSSearch>` object using a query molecule
      (:ref:`OEQMolBase <OEChem_OEQMolBase>`).

      *qmol*
        The query molecule of the MCS search.

      *type*
        The type of the :ref:`OEMCSSearch <OEChem_OEMCSSearch>` from the
        :oe:constns:`OEChem::OEMCSType` namespace.

      *perception*
         If ``true``, then ring perception is performed on the query molecule.

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

         .. oe:api::

            OEMCSSearch(const OEMolBase &, unsigned int atomexpr,
                        unsigned int bondexpr,
                        unsigned int type = OEMCSType::Default)

      .. oe:language:: python

         .. oe:api:: python

            OEMCSSearch(arg2: Union[OEGraphMol,OEMol,OEQMol], arg3: int,
                        arg4: int, type: int) -> OEMCSSearch


      Constructs an :ref:`OEMCSSearch <OEChem_OEMCSSearch>` 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 common
      subgraph search.

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

      .. oe:api::

         OEMCSSearch &operator=(const OEMCSSearch &rhs)

      Assignment operator that copies the data of the 'rhs' :ref:`OEMCSSearch <OEChem_OEMCSSearch>` object
      into the right-hand side :ref:`OEMCSSearch <OEChem_OEMCSSearch>` 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

      Test for successful initialization of an
      :ref:`OEMCSSearch <OEChem_OEMCSSearch>` object.
      If initialization was attempted with an invalid :term:`SMARTS`
      pattern or query molecule (:ref:`OEQMolBase <OEChem_OEQMolBase>`) then
      this method will return ``false``.
      If initialization was completed successfully this method will
      return ``true``.
      An :ref:`OEMCSSearch <OEChem_OEMCSSearch>` 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<OEBondBase> &)
            bool AddConstraint(const OEMatchPair<OEAtomBase> &)

      .. oe:language:: python

         .. oe:api:: python

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

      The search space of a maximum common subgraph determination can
      be restricted by constraining pairs of nodes or edges (atoms or
      bonds) to be mapped onto one another in all subgraph solutions.
      All subgraph solutions will contain all constraints specified by
      this method.

      Both :oe:meth:`OEChem::OEMCSSearch::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:`OEMCSSearch <OEChem_OEMCSSearch>` object then
      :oe:meth:`OEChem::OEMCSSearch::AddConstraint` will return
      ``false``.

      Multiple calls to :oe:meth:`OEChem::OEMCSSearch::AddConstraint`
      using the same pattern atom or bond will return ``false`` as
      it is impossible to satisfy multiple simultaneous constraints
      for a single pattern atom or bond, hence the exclusivity.

   .. oe:method:: ClearConstraints

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

         .. oe:api::

            void ClearConstraints()

      .. oe:language:: python

         .. oe:api:: python

            ClearConstraints() -> None

      Clears all prior match constraints set with the
      :oe:meth:`OEChem::OEMCSSearch::AddConstraint` methods.

   .. 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 common subgraphs
      that the :ref:`OEMCSSearch <OEChem_OEMCSSearch>` will identify
      before terminating the search.
      A value of zero indicates that no arbitrary limit has been set
      on the total number of subgraphs to be identified.
      By default, the maximum number of matches is set to ``1024``
      This value can be set using the
      :oe:meth:`OEChem::OEMCSSearch::SetMaxMatches` method.

   .. oe:method:: GetMinAtoms

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

         .. oe:api::

            unsigned int GetMinAtoms() const

      .. oe:language:: python

         .. oe:api:: python

            GetMinAtoms() -> int

      Returns the minimum number of atoms of a subgraph that
      can be returned as a maximum common subgraph.
      This value can be set using the
      :oe:meth:`OEChem::OEMCSSearch::SetMinAtoms` method.

   .. oe:method:: GetPattern

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

         .. oe:api::

            const OEQMolBase& GetPattern() const

      .. oe:language:: python

         .. oe:api:: python

            GetPattern() -> OEQMol

      Returns a read-only reference to the query molecule
      (:ref:`OEQMolBase <OEChem_OEQMolBase>`) of :ref:`OEMCSSearch <OEChem_OEMCSSearch>`.
      Const :ref:`OEQMolBase <OEChem_OEQMolBase>` methods can be used on the
      returned :ref:`OEQMolBase <OEChem_OEQMolBase>` reference.
      If the :ref:`OEMCSSearch <OEChem_OEMCSSearch>` object has not been
      initialized, a reference to an empty molecule will be returned.

   .. oe:method: GetSaveRange  IGNORE - OBSOLETE

      .. oe:api:

         unsigned int GetSaveRange() const

   .. oe:method:: Init

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

         .. oe:api::

            bool Init(const char* smarts)

      .. oe:language:: python

         .. oe:api:: python

            Init(arg2: str) -> bool

      (Re)initializes an :ref:`OEMCSSearch <OEChem_OEMCSSearch>` object using a
      'smarts' pattern.
      The :term:`SMARTS` pattern is parsed to create a query molecule
      available for maximum common subgraph matching.
      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.

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

         .. oe:api::

            bool Init(const OEQMolBase& qmol, bool perception = true)

      .. oe:language:: python

         .. oe:api:: python

            Init(arg2: OEQMol, makeCopy: bool = True) -> bool

      (Re)initializes an :ref:`OEMCSSearch <OEChem_OEMCSSearch>` object using a
      query molecule (:ref:`OEQMolBase <OEChem_OEQMolBase>`) reference.
      The method will return ``true`` if initialization completes
      successfully, and ``false`` upon failure.

      *qmol*
        The query molecule of the MCS search.

      *perception*
         If ``true``, then ring perception is performed on the query molecule.

      .. note::

         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 OEMolBase& mol, unsigned int atomexpr,
                      unsigned int bondexpr)

      .. oe:language:: python

         .. oe:api:: python

            Init(arg2: Union[OEGraphMol,OEMol,OEQMol], arg3: int, arg4: int) -> bool

      (Re)initializes an :ref:`OEMCSSearch <OEChem_OEMCSSearch>` 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 common subgraph
      search.
      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 &,
                                                     bool uniquematch = false) const

      .. oe:language:: python

         .. oe:api:: python

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


      Performs search in order to identify maximum common subgraphs
      shared between the passed :ref:`OEMolBase <OEChem_OEMolBase>` and the
      query molecule which the :ref:`OEMCSSearch <OEChem_OEMCSSearch>` 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.

      If the 'uniquematch'  argument passed to the methods is ``true`` then
      only the unique matches will be returned  in the iterator over the matches.
      By definition, a match or subgraph is considered unique if it differs
      from all other subgraphs found previously by at least one atom or
      bond.
      Additionally, it is also considered unique if the query subgraph
      is mapped to a different part of the target
      (See example in the :ref:`section_patternmatch_mcss` section)

      .. oe:api: IGNORED - NOT IMPLEMENTED YET

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

   .. oe:method:: SetMCSFunc

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

         .. oe:api::

            bool SetMCSFunc(const OEChem::OEMCSFunc &)

      .. oe:language:: python

         .. oe:api:: python

            SetMCSFunc(arg2: OEMCSFunc) -> bool

      Stores a copy of the passed :ref:`OEMCSFunc <OEChem_OEMCSFunc>` functor
      in the :ref:`OEMCSSearch <OEChem_OEMCSSearch>` object.
      The functor is then used to evaluate and order subgraphs found
      during a maximum common subgraph search.

      .. seealso::

         * :ref:`OEMCSFunc <OEChem_OEMCSFunc>`
         * :ref:`OEMCSMaxAtoms <OEChem_OEMCSMaxAtoms>`
         * :ref:`OEMCSMaxBonds <OEChem_OEMCSMaxBonds>`
         * :ref:`OEMCSMaxAtomsCompleteCycles <OEChem_OEMCSMaxAtomsCompleteCycles>`
         * :ref:`OEMCSMaxBondsCompleteCycles <OEChem_OEMCSMaxBondsCompleteCycles>`

   .. oe:method:: SetMaxMatches

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

         .. oe:api::

            bool SetMaxMatches(unsigned int)

      .. oe:language:: python

         .. oe:api:: python

            SetMaxMatches(arg2: int) -> bool

      Sets the maximum number of maximum common subgraph matches that
      will be returned by the :oe:meth:`OEChem::OEMCSSearch::Match`
      method.

      .. note::

         The search for maximum common substructures will not terminate
         immediately upon reaching this limit.
         The maximum common subgraph cannot be known unless the MCS is
         composed of all atoms and bonds of at least one of the graphs
         being compared.
         The limit of subgraphs to be returned may be reached with a
         smaller subgraph than the maximum.
         In such a case the search continues for larger subgraphs until
         the search is exhausted.
         :oe:meth:`OEChem::OEMCSSearch::Match` will return the first
         :math:`N` maximum common subgraphs where :math:`N` is less than
         or equal to the maximum match limit.


      The default limit set upon construction of an
      :ref:`OEMCSSearch <OEChem_OEMCSSearch>` object is ``1024`` matches.
      This value can be retrieved
      using the :oe:meth:`OEChem::OEMCSSearch::GetMaxMatches` method.

   .. oe:method:: SetMinAtoms

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

         .. oe:api::

            bool SetMinAtoms(unsigned int)

      .. oe:language:: python

         .. oe:api:: python

            SetMinAtoms(arg2: int) -> bool

      Sets the minimum number of atoms required of a subgraph match to
      be returned a solution by a MCS search.
      A single atom can be a perfectly valid maximum common subgraph,
      however, for many applications such a small subgraph may not be
      considered useful.
      Setting the minimum number of atoms to an appropriate size
      prevents unproductive subgraph matches from being returned by
      the :oe:meth:`OEChem::OEMCSSearch::Match` method.
      The default value for the minimum number of atoms in a subgraph
      match is set to ``1`` upon construction of an
      :ref:`OEMCSSearch <OEChem_OEMCSSearch>` object.
      This value can be retrieved using the
      :oe:meth:`OEChem::OEMCSSearch::GetMinAtoms` method.

   .. oe:method: SetSaveRange IGNORE - OBSOLETE

      .. oe:api::

         bool SetSaveRange(unsigned int)

   .. oe:method: SingleMatch IGNORED - NOT IMPLEMENTED YET

      .. oe:api::

         bool SingleMatch(const OEMolBase &) const
         bool SingleMatch(const OEQMolBase &) const

