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

.. oe:namespace:: OEChem


.. _OEChem_OESubSearchDatabase:

.. oe:class:: OESubSearchDatabase

   .. attention::

      |TWOLANGUAGE|

   .. oe:api::

      class OESubSearchDatabase

   The :ref:`OESubSearchDatabase <OEChem_OESubSearchDatabase>` class is designed to perform
   fast multi-threaded substructure search.
   Each :ref:`OESubSearchDatabase <OEChem_OESubSearchDatabase>` is associated with one
   screen type (:ref:`OESubSearchScreenTypeBase <OEChem_OESubSearchScreenTypeBase>`) that is
   set when the database is initialized from a pre-generated binary
   substructure search file.

   .. figure:: ../images/FastSSSearch.*
      :width: 350 pt
      :align: center

      **Schematic representation of using substructure search database**

   The :ref:`OESubSearchDatabase <OEChem_OESubSearchDatabase>` class provides the following search methods:

   .. list-table::
      :widths: 100 100 200
      :header-rows: 1

      * - Method
        - Returns
        - Type

      * - :oe:meth:`NumMatches<OEChem::OESubSearchDatabase::NumMatches>`
        - number of matched molecules
        - full search

      * - :oe:meth:`GetMatchIndices<OEChem::OESubSearchDatabase::GetMatchIndices>`
        - indices of matched molecules
        - limited search

      * - :oe:meth:`GetMatchTitles<OEChem::OESubSearchDatabase::GetMatchTitles>`
        - titles of matched molecules
        - limited search

      * - :oe:meth:`Search<OEChem::OESubSearchDatabase::Search>`
        - :oe:cls:`OESubSearchResult<OEChem::OESubSearchResult>` (indices of molecules, progress of search)
        - full/limited search (cancelable)

   .. seealso::

      * :oe:func:`OEChem::OECreateSubSearchDatabaseFile` function to generate
        database files for :ref:`OESubSearchDatabase <OEChem_OESubSearchDatabase>`.


   .. admonition:: Code Example

      * :ref:`section_example_oechem_makefastss` example
      * :ref:`section_example_oechem_searchfastss` example

   .. oe:method:: Constructors

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

         .. oe:api::

            OESubSearchDatabase(const std::string& dbfile,
                                const unsigned memtype = OESubSearchDatabaseType::Default,
                                const unsigned numprocesssors = 0u)
            OESubSearchDatabase(const unsigned memtype = OESubSearchDatabaseType::Default,
                                const unsigned numprocesssors = 0u)

      .. oe:language:: python

         .. oe:api:: python

            OESubSearchDatabase(memtype: int, numprocesssors: int = 0) -> OESubSearchDatabase
            OESubSearchDatabase(dbfile: str, memtype: int,
                                numprocesssors: int = 0) -> OESubSearchDatabase

      Constructs an :ref:`OESubSearchDatabase <OEChem_OESubSearchDatabase>` object.

      dbfile
        The name of the file that contains the substructure search data
        (molecules with pre-generated screens).
        The file has to be generated with the
        :oe:func:`OEChem::OECreateSubSearchDatabaseFile` function.
        If no file name is defined, the database has to be initialized
        by calling the :oe:meth:`OEChem::OESubSearchDatabase::Open` method.

      memtype
        Defines the type of the substructure database.
        This value has to be from the
        :oe:constns:`OEChem::OESubSearchDatabaseType` namespace.

      numprocesssors
        The maximum number of threads that can be used to search the database.
        When set to ``0``, the number of processors used will be the number
        returned by the :oe:func:`OEPlatform::OEGetNumProcessors` function.
        If ``numprocesssors == 1``, all searches are executed using
        the main thread only.

   .. oe:method:: GetDatabaseType

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

         .. oe:api::

            unsigned GetDatabaseType() const

      .. oe:language:: python

         .. oe:api:: python

            GetDatabaseType() -> int

      Returns the type of the substructure search database.
      The return value is taken from the :oe:constns:`OEChem::OESubSearchDatabaseType`
      namespace.

   .. oe:method:: GetMatchIndices

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

         .. oe:api::

            OESystem::OEIterBase<size_t>* GetMatchIndices(const OESubSearchQuery &) const

      .. oe:language:: python

         .. oe:api:: python

            GetMatchIndices(arg2: OESubSearchQuery) -> Iterable[int]

      Returns the indices of molecules matched to the given query
      (:ref:`OESubSearchQuery <OEChem_OESubSearchQuery>`).
      The search terminates if the limit set for the query is reached
      (:oe:cls:`GetMaxMatches<OEChem::OESubSearchQuery::GetMaxMatches>`).
      The matched molecules  can be retried from the database by using the
      :oe:meth:`OEChem::OESubSearchDatabase::GetMolecule` method.

   .. oe:method:: GetMatchTitles

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

         .. oe:api::

            OESystem::OEIterBase<std::string>* GetMatchTitles(const OESubSearchQuery &) const

      .. oe:language:: python

         .. oe:api:: python

            GetMatchTitles(arg2: OESubSearchQuery) -> OEStringIter

      Returns the titles of the molecules matched to the given query
      (:ref:`OESubSearchQuery <OEChem_OESubSearchQuery>`).
      The search terminates if the limit set for the query is reached
      (:oe:cls:`GetMaxMatches<OEChem::OESubSearchQuery::GetMaxMatches>`).

   .. oe:method:: GetMolecule

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

         .. oe:api::

            bool GetMolecule(OEMolBase& mol, const size_t index) const

      .. oe:language:: python

         .. oe:api:: python

            GetMolecule(mol: Union[OEGraphMol,OEMol,OEQMol], arg3: int) -> bool

      Retrieves the molecule stored in the database with the specified index.

      .. seealso::

         * :oe:meth:`OEChem::OESubSearchDatabase::GetTitle` method

   .. oe:method:: GetScreenType

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

         .. oe:api::

            const OESubSearchScreenTypeBase* GetScreenType() const

      .. oe:language:: python

         .. oe:api:: python

            GetScreenType() -> OESubSearchScreenTypeBase

      Returns the screen type of the
      :ref:`OESubSearchDatabase <OEChem_OESubSearchDatabase>` object.
      An :ref:`OESubSearchDatabase <OEChem_OESubSearchDatabase>` object can only store
      screens with identical types.

   .. oe:method:: GetTitle

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

         .. oe:api::

            std::string GetTitle(const size_t index) const

      .. oe:language:: python

         .. oe:api:: python

            GetTitle(arg2: int) -> str

      Retrieves the title of the molecule stored in the database with the specified index.

      .. seealso::

         * :oe:meth:`OEChem::OESubSearchDatabase::GetMolecule` method

   .. oe:method:: IsValid

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

         .. oe:api::

            bool IsValid() const

      .. oe:language:: python

         .. oe:api:: python

            IsValid() -> bool

      Returns whether the :ref:`OESubSearchDatabase <OEChem_OESubSearchDatabase>` object is valid.

   .. oe:method:: NumMatches

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

         .. oe:api::

            size_t NumMatches(const OEQMolBase& query) const

      .. oe:language:: python

         .. oe:api:: python

            NumMatches(query: OEQMol) -> int

      Returns the number of molecules matched to the given query
      (:ref:`OESubSearchQuery <OEChem_OESubSearchQuery>`) in the entire database.

   .. oe:method:: NumMolecules

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

         .. oe:api::

            size_t NumMolecules() const

      .. oe:language:: python

         .. oe:api:: python

            NumMolecules() -> int

      Returns the number of molecules stored in the :ref:`OESubSearchDatabase <OEChem_OESubSearchDatabase>`
      object.

   .. oe:method:: NumProcessors

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

         .. oe:api::

            unsigned NumProcessors() const

      .. oe:language:: python

         .. oe:api:: python

            NumProcessors() -> int

      Returns the maximum number of threads that can be used to search the database.
      This is determined when the database is initialized.

   .. oe:method:: Open

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

         .. oe:api::

            bool Open(oemolistream& ifs,
                      OESystem::OETracerBase& tracer = OESystem::OENoTracer)
            bool Open(const std::string & filename,
                      OESystem::OETracerBase& tracer = OESystem::OENoTracer)

      .. oe:language:: python

         .. oe:api:: python

            Open(ifs: oemolistream, tracer: OETracerBase = OENoTracer) -> bool
            Open(arg2: str, tracer: OETracerBase = OENoTracer) -> bool

      Initializes the substructure search database. These methods return
      ``true`` if the database was successfully initialized.

      ifs
        The molecule stream from which the substructure search database is
        initialized.

      filename
        The name of the file from which the substructure search database is
        initialized.

      tracer
        The tracer that can be used to report the progress of the database load.

      .. seealso::

         * :ref:`OEConsoleProgressTracer <OESystem_OEConsoleProgressTracer>` class

   .. oe:method:: Search

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

         .. oe:api::

            unsigned Search(OESubSearchResult& result,
                            const OESubSearchQuery& query) const

      .. oe:language:: python

         .. oe:api:: python

            Search(arg2: OESubSearchResult, arg3: OESubSearchQuery) -> int

      This search method is designed for interactive searches.

      result
        The :ref:`OESubSearchResult <OEChem_OESubSearchResult>` object that stores the result of the
        search along with the progress of the search.
        The :ref:`OESubSearchResult <OEChem_OESubSearchResult>` is updated regularly during the search
        as more and more matches identified. It also provides a mechanism to cancel
        a long running search via :oe:meth:`OEChem::OESubSearchResult::Cancel`.

      query
        The :ref:`OESubSearchQuery <OEChem_OESubSearchQuery>` object that stores the query molecule
        with search parameters.

      The :oe:meth:`OEChem::OESubSearchDatabase::Search` method returns:

      * :oe:const:`OEChem::OESubSearchStatus::Uninitialized` if the search can not be executed
      * :oe:const:`OEChem::OESubSearchStatus::Finished`, if the search successfully finished
      * :oe:const:`OEChem::OESubSearchStatus::Canceled`, if the search was interrupted

      .. seealso::

         * :oe:constns:`OEChem::OESubSearchStatus` namespace
