.. include:: ../../toolkit-substitutions
.. include:: ../../common/cookbook/cookbook-hyperlinks

.. oe:namespace:: OEGraphSim


.. _OEGraphSim_OEFastFPDatabase:

.. oe:class:: OEFastFPDatabase

   .. oe:api::

      class OEFastFPDatabase

   The :ref:`OEFastFPDatabase <OEGraphSim_OEFastFPDatabase>` class is designed to perform
   rapid CUDA-accelerated, in-memory or memory-mapped fingerprint searches
   using the :term:`popcount` method.
   Each :ref:`OEFastFPDatabase <OEGraphSim_OEFastFPDatabase>` object is associated with a
   fingerprint type (:ref:`OEFPTypeBase <OEGraphSim_OEFPTypeBase>`) that is
   set when the database is initialized from a pre-generated binary
   fingerprint file.

   For CUDA-accelerated fingerprint searching please see the :ref:`prerequisites for OpenEye's GPU-accelerated software <graphsim_prereq_for_gpu>`.

   .. note::

      **GraphSim TK** currently only supports the :term:`popcount` search
      method for fingerprints with the size of multiple of ``256``.
      This means that the :ref:`OEFastFPDatabase <OEGraphSim_OEFastFPDatabase>` class
      currently does not support:

      * :oe:const:`OEGraphSim::OEFPType::MACCS166` fingerprint type
      * :oe:const:`OEGraphSim::OEFPType::Lingo` fingerprint type
      * other custom fingerprint types (see :ref:`chapter_user_defined` section)
        with size that is not a multiple of ``256``

      For the fingerprint types listed above, the original
      :ref:`OEFPDatabase <OEGraphSim_OEFPDatabase>` class can be utilized.

   .. note::

      :ref:`OEFastFPDatabase <OEGraphSim_OEFastFPDatabase>` gives identical results
      to :ref:`OEFPDatabase <OEGraphSim_OEFPDatabase>`.
      However, :ref:`OEFPDatabase <OEGraphSim_OEFPDatabase>` calculates similarity
      scores in single precision (float) while
      :ref:`OEFastFPDatabase <OEGraphSim_OEFastFPDatabase>` uses double precision.
      As a result, small similarity score differences can be observed.

   .. seealso::

      * :ref:`OEFPDatabase <OEGraphSim_OEFPDatabase>` class

   .. admonition:: Code Example

      * Example code in the :ref:`section_examples_summary_makefastfp` section
      * Example code in the :ref:`section_examples_summary_searchfastfp` section

      * `Rapid Similarity Searching of Large Molecule File`_ **OpenEye Python Cookbook** recipe
      * `Depicting Molecule Similarity Based on Fingerprints`_ **OpenEye Python Cookbook** recipe

   .. figure:: ../images/searchfastfp.*
      :align:  center
      :width:  400pt

      **Schematic representation of fast fingerprint search process**


   .. ################################################################
      #
      ################################################################

   .. oe:method:: Constructors

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

         .. oe:api::

            OEFastFPDatabase(const std::string& dbfile,
                             unsigned int memtype = OEFastFPDatabaseMemoryType::Default)

      .. oe:language:: python

         .. oe:api:: python

            OEFastFPDatabase(dbfile: str, memtype: int) -> OEFastFPDatabase

      Constructs an :ref:`OEFastFPDatabase <OEGraphSim_OEFastFPDatabase>` object.

      dbfile
        The name of the file which contains the fingerprint data.
        The file has to be generated with the
        :oe:func:`OEGraphSim::OECreateFastFPDatabaseFile` function.

      memtype
        Defines whether the fingerprints are pre-loaded into GPU-memory,
        CPU-memory, or memory-mapped during the search process.
        This value has to be from the
        :oe:constns:`OEGraphSim::OEFastFPDatabaseMemoryType` namespace.

      .. note::

         If the :ref:`OEFastFPDatabase <OEGraphSim_OEFastFPDatabase>` object can not be initialized
         with the :oe:const:`OEGraphSim::OEFastFPDatabaseMemoryType::CUDA` option,
         the following warning message will be throw:

         ::

            Warning: OEFastFPDatabase::OEFastFPDatabase() : no CUDA-enabled
            device available falling back to memory-mapped type!

         As a rule of thumb, 1 million finger prints requires 0.6GB of GPU memory.
         GPU memory can be queried using the ``nvidia-smi`` command from terminal.

      .. seealso::

         * :oe:constns:`OEGraphSim::OEFastFPDatabaseMemoryType` namespace.


   .. ################################################################
      #
      ################################################################

   .. oe:method:: GetAllScores

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

         .. oe:api::

            OESystem::OEIterBase<float>* GetAllScores(const OEFPDatabaseOptions& opts) const

      .. oe:language:: python

         .. oe:api:: python

            GetAllScores(opts: OEFPDatabaseOptions) -> Iterable[float]

      Performs :math:`NxN` similarity calculations between all pairs of fingerprints
      stored in the :ref:`OEFastFPDatabase <OEGraphSim_OEFastFPDatabase>` object.
      It returns an iterator over the calculated similarity scores.
      The scores are not sorted, but returned as a flattened square matrix.

      For all similarity measures other than :ref:`section_measure_tversky`,
      the returned 'matrix' will be symmetrical.

      opts
        The :ref:`OEFPDatabaseOptions <OEGraphSim_OEFPDatabaseOptions>` object controls all the parameters
        that determine the search (i.e. similarity measure parameters).
        Cutoff and order parameters are ignored as the results are not filtered or sorted.

      .. note::

         This operation scales with :math:`n^2` in memory and can easily overwhelm
         the system memory for larger databases.
         Therefore, the :oe:meth:`OEGraphSim::OEFastFPDatabase::GetRawScores` method
         returns a single row of the similarity matrix and is the recommended usage
         for querying large databases.

      .. seealso::

         * :ref:`OEFPDatabaseOptions <OEGraphSim_OEFPDatabaseOptions>` class


   .. ################################################################
      #
      ################################################################

   .. oe:method:: GetFingerPrint

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

         .. oe:api::

            bool GetFingerPrint(OEFingerPrint& fp, size_t idx) const

      .. oe:language:: python

         .. oe:api:: python

            GetFingerPrint(fp: OEFingerPrint, fpidx: int) -> bool

      Returns the :math:`idx^{th}` fingerprint of the database.

      .. warning::

         This function returns ``false`` if the fingerprint index is
         not identical to the corresponding molecule index.
         This can occur if the fingerprint binary file is generated in
         multi-thread process.
         If direct access to the fingerprint is required when using
         the :oe:meth:`OEGraphSim::OEFastFPDatabase::GetFingerPrint`
         method, the fingerprint file should be generated in a
         single-threaded mode.
         This can be done by setting
         :oe:meth:`SetNumProcessors(1) <OEGraphSim::OECreateFastFPDatabaseOptions::GetNumProcessors>`
         for the option class used for creating the binary file.

      .. seealso::

         * :ref:`OEFingerPrint <OEGraphSim_OEFingerPrint>` class
         * :oe:meth:`OEGraphSim::OECreateFastFPDatabaseOptions::GetNumProcessors` method
         * :oe:meth:`OEGraphSim::OECreateFastFPDatabaseOptions::SetNumProcessors` method

   .. ################################################################
      #
      ################################################################

   .. oe:method:: GetFPTypeBase

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

         .. oe:api::

            const OEFPTypeBase* GetFPTypeBase() const

      .. oe:language:: python

         .. oe:api:: python

            GetFPTypeBase() -> OEFPTypeBase

      Returns the fingerprint type of the
      :ref:`OEFastFPDatabase <OEGraphSim_OEFastFPDatabase>` object.
      An :ref:`OEFastFPDatabase <OEGraphSim_OEFastFPDatabase>` object can only store
      fingerprints with identical types.


   .. ################################################################
      #
      ################################################################

   .. oe:method:: GetHistogram

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

         .. oe:api::

            OEFPHistogram GetHistogram(const OEFPDatabaseOptions& opts,
                                       const size_t nrbins = 200u) const

      .. oe:language:: python

         .. oe:api:: python

            GetHistogram(opts: OEFPDatabaseOptions, nrbins: int = 200) -> OEFPHistogram

      Performs similarity calculations between all pairs of fingerprints
      stored in the :ref:`OEFastFPDatabase <OEGraphSim_OEFastFPDatabase>` object.
      It returns the histogram over the calculated similarity scores in a
      :ref:`OEFPHistogram <OEGraphSim_OEFPHistogram>` object.

      opts
        The :ref:`OEFPDatabaseOptions <OEGraphSim_OEFPDatabaseOptions>` object contains the
        settings available to control the search (i.e. similarity measure,
        :math:`\alpha` and :math:`\beta` parameters for :ref:`section_measure_tversky`
        similarity).
        Cutoff and order parameters are ignored as the results are not filtered or sorted.

      nrbins
        Number of bins in the returned :ref:`OEFPHistogram <OEGraphSim_OEFPHistogram>` object.

      .. note::

         For all similarity measures other than :ref:`section_measure_tversky`,
         the histogram only contains the upper-triangular similarity scores
         (excluding the diagonal).
         In case of the asymmetric :ref:`section_measure_tversky` similarity measure,
         the histogram of the whole :math:`NxN` matrix is returned.

      .. note::

         When the :ref:`OEFastFPDatabase <OEGraphSim_OEFastFPDatabase>` object is initialized
         with :oe:constns:`OEGraphSim::OEFastFPDatabaseMemoryType::CUDA`,
         ``nrbins`` is limited to at most 1024.

      .. hint::

         This method calculates similarities identically to
         :oe:meth:`OEGraphSim::OEFastFPDatabase::GetAllScores`
         but is not bound by the system memory. It can be used to quickly obtain
         statistics on larger databases.

      .. seealso::

         * :ref:`OEFPDatabaseOptions <OEGraphSim_OEFPDatabaseOptions>` class
         * :ref:`OEFPHistogram <OEGraphSim_OEFPHistogram>` class


   .. ################################################################
      #
      ################################################################

   .. oe:method:: GetMemoryType

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

         .. oe:api::

            unsigned int GetMemoryType() const

      .. oe:language:: python

         .. oe:api:: python

            GetMemoryType() -> int

      Returns the memory type of the fingerprint database.
      The return value is taken from the :oe:constns:`OEGraphSim::OEFastFPDatabaseMemoryType`
      namespace.

      .. seealso::

         * :oe:meth:`OEGraphSim::OEFastFPDatabase::GetMemoryTypeString` method


   .. ################################################################
      #
      ################################################################

   .. oe:method:: GetMemoryTypeString

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

         .. oe:api::

            std::string GetMemoryTypeString() const

      .. oe:language:: python

         .. oe:api:: python

            GetMemoryTypeString() -> str

      Returns the string representation if memory type of the fingerprint database.

      .. seealso::

         * :oe:meth:`OEGraphSim::OEFastFPDatabase::GetMemoryType` method

   .. oe:method:: GetMoleculeIndex

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

         .. oe:api::

            size_t GetMoleculeIndex(const size_t fpidx) const

      .. oe:language:: python

         .. oe:api:: python

            GetMoleculeIndex(fpidx: int) -> int

      Returns the molecule index that corresponds to the fingerprint index.

      .. note::

         When building fingerprint databases using
         :ref:`OECreateFastFPDatabaseOptions <OEGraphSim_OECreateFastFPDatabaseOptions>`, the molecule
         index is always the same as the fingerprint index. However, there
         are private database building APIs that allow to specify the molecule
         index associated with each fingerprint.
         This :oe:meth:`OEGraphSim::OEFastFPDatabase::GetMoleculeIndex`
         method allows to handle these private databases.

   .. ################################################################
      #
      ################################################################

   .. oe:method:: GetRawScores

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

         .. oe:api::

            OESystem::OEIterBase<double>* GetRawScores(const size_t fpidx,
                                                       const OEFPDatabaseOptions& opts) const
            OESystem::OEIterBase<double>* GetRawScores(const OEFingerPrint& fp,
                                                       const OEFPDatabaseOptions& opts) const
            OESystem::OEIterBase<double>* GetRawScores(const OEChem::OEMolBase& mol,
                                                       const OEFPDatabaseOptions& opts) const

      .. oe:language:: python

         .. oe:api:: python

            GetRawScores(fpidx: int, opts: OEFPDatabaseOptions) -> Iterable[float]
            GetRawScores(fp: OEFingerPrint, opts: OEFPDatabaseOptions) -> Iterable[double]
            GetRawScores(mol: Union[OEGraphMol,OEMol,OEQMol],
                         opts: OEFPDatabaseOptions) -> Iterable[double]


      Performs similarity calculations between a molecule or a fingerprint and the
      fingerprints stored in the :ref:`OEFastFPDatabase <OEGraphSim_OEFastFPDatabase>` object.
      It returns an iterator over the calculated similarity scores.
      The scores are not sorted, but returned in the same order as the database.
      The number of elements in the returned iterator is equal to the number
      of fingerprints in the database.

      fpidx
        If the method is called with an integer index, the query fingerprint is
        taken from the :ref:`OEFastFPDatabase <OEGraphSim_OEFastFPDatabase>` object with the given index.

      mol
        If the method is called with an :ref:`OEMolBase <OEChem_OEMolBase>` object, a fingerprint
        is generated from this molecule before looping over the fingerprints of the
        database and calculating similarities.

      fp
        If the method is called with an :ref:`OEFingerPrint <OEGraphSim_OEFingerPrint>` object,
        its type has to match the type of the :ref:`OEFastFPDatabase <OEGraphSim_OEFastFPDatabase>`.

      opts
        The :ref:`OEFPDatabaseOptions <OEGraphSim_OEFPDatabaseOptions>` object contains the settings
        available to control the search (i.e. similarity measure parameters).
        Cutoff and order parameters are ignored as the results are not filtered or sorted.

      .. seealso::

         * :ref:`OEFPDatabaseOptions <OEGraphSim_OEFPDatabaseOptions>` class
         * :oe:meth:`OEGraphSim::OEFastFPDatabase::GetAllScores` method


   .. ################################################################
      #
      ################################################################

   .. oe:method:: GetScores

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

         .. oe:api::

            OESystem::OEIterBase<OESimScore>* GetScores(const size_t idx,
                                                        const OEFPDatabaseOptions& opts) const
            OESystem::OEIterBase<OESimScore>* GetScores(const OEFingerPrint& fp,
                                                        const OEFPDatabaseOptions& opts) const
            OESystem::OEIterBase<OESimScore>* GetScores(const OEChem::OEMolBase& mol,
                                                        const OEFPDatabaseOptions& opts) const

      .. oe:language:: python

         .. oe:api:: python

            GetScores(idx: int, opts: OEFPDatabaseOptions) -> Iterable[OESimScore]
            GetScores(fp: OEFingerPrint, opts: OEFPDatabaseOptions) -> Iterable[OESimScore]
            GetScores(mol: Union[OEGraphMol,OEMol,OEQMol],
                      opts: OEFPDatabaseOptions) -> Iterable[OESimScore]

      Performs similarity calculations between a molecule or fingerprint and the
      fingerprints stored in the :ref:`OEFastFPDatabase <OEGraphSim_OEFastFPDatabase>` object.
      It returns an iterator over the calculated similarity scores
      (:ref:`OESimScore <OEGraphSim_OESimScore>`).
      The results are filtered according to the cutoff and order parameters
      specified in ``opts``, but are not sorted.

      fpidx
        If the method is called with an integer index, the query fingerprint is
        taken from the :ref:`OEFastFPDatabase <OEGraphSim_OEFastFPDatabase>` object with the given index.

      mol
        If the method is called with an :ref:`OEMolBase <OEChem_OEMolBase>` object, a fingerprint
        is generated from this molecule before looping over the fingerprints of the
        database and calculating similarities.

      fp
        If the method is called with an :ref:`OEFingerPrint <OEGraphSim_OEFingerPrint>` object,
        its type has to match the type of the :ref:`OEFastFPDatabase <OEGraphSim_OEFastFPDatabase>`.

      opts
        The :ref:`OEFPDatabaseOptions <OEGraphSim_OEFPDatabaseOptions>` object controls all the
        parameters that determine the search (i.e. similarity measure parameters,
        score cutoff and order).

      .. seealso::

         * :ref:`OEFPDatabaseOptions <OEGraphSim_OEFPDatabaseOptions>` class


   .. ################################################################
      #
      ################################################################

   .. oe:method:: GetSortedScores

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

         .. oe:api::

            OESystem::OEIterBase<OESimScore>* GetSortedScores(const size_t idx,
                                                              const OEFPDatabaseOptions& opts) const
            OESystem::OEIterBase<OESimScore>* GetSortedScores(const OEFingerPrint& fp,
                                                              const OEFPDatabaseOptions& opts) const
            OESystem::OEIterBase<OESimScore>* GetSortedScores(const OEChem::OEMolBase& mol,
                                                              const OEFPDatabaseOptions& opts) const

      .. oe:language:: python

         .. oe:api:: python

            GetSortedScores(idx: int, opts: OEFPDatabaseOptions) -> Iterable[OESimScore]
            GetSortedScores(fp: OEFingerPrint, opts: OEFPDatabaseOptions) -> Iterable[OESimScore]
            GetSortedScores(mol: Union[OEGraphMol,OEMol,OEQMol],
                            opts: OEFPDatabaseOptions) -> Iterable[OESimScore]

      Performs similarity calculations between a molecule or fingerprint and the
      fingerprints stored in the :ref:`OEFastFPDatabase <OEGraphSim_OEFastFPDatabase>` object.
      It returns an iterator over the calculated similarity scores
      (:ref:`OESimScore <OEGraphSim_OESimScore>`) in sorted order.
      Each :ref:`OESimScore <OEGraphSim_OESimScore>` holds a similarity score and
      index of the corresponding fingerprint of the database.

      fpidx
        If the method is called with an integer index, the query fingerprint is
        taken from the :ref:`OEFastFPDatabase <OEGraphSim_OEFastFPDatabase>` object with the given index.

      mol
        If the method is called with an :ref:`OEMolBase <OEChem_OEMolBase>` object, a fingerprint
        is generated from this molecule before looping over the fingerprints of the
        database and calculating similarities.

      fp
        If the method is called with an :ref:`OEFingerPrint <OEGraphSim_OEFingerPrint>` object,
        its type has to match the type of the :ref:`OEFastFPDatabase <OEGraphSim_OEFastFPDatabase>`.

      opts
        The :ref:`OEFPDatabaseOptions <OEGraphSim_OEFPDatabaseOptions>` object controls all the
        parameters that determine the search (i.e. similarity measure parameters,
        score cutoff, order and limit).

      .. seealso::

         * :ref:`OEFPDatabaseOptions <OEGraphSim_OEFPDatabaseOptions>` class

   .. ################################################################
      #
      ################################################################

   .. oe:method:: GetSparseMatrix

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

         .. oe:api::

            OESystem::OEIterBase<OESimScorePair>* GetSparseMatrix(const OEFPDatabaseOptions& opts) const

      .. oe:language:: python

         .. oe:api:: python

            GetSparseMatrix(opts: OEFPDatabaseOptions) -> Iterable[OESimScorePair]


      Performs :math:`NxN` similarity calculations between all pairs of fingerprints
      stored in the :ref:`OEFastFPDatabase <OEGraphSim_OEFastFPDatabase>` object and returns either the top ``K``
      scores for each fingerprint or all scores above a cutoff for each fingerprint. The sparse
      matrix is returned as an iterator over :ref:`OESimScorePair <OEGraphSim_OESimScorePair>` objects. The
      limit of scores to return can be set using :oe:meth:`OEGraphSim::OEFPDatabaseOptions::SetLimit`
      and the cutoff of scores to return can be set using :oe:meth:`OEGraphSim::OEFPDatabaseOptions::SetCutoff`.
      If no limit is set, all scores will be returned above the cutoff value. If a limit is set, only
      :oe:meth:`OEGraphSim::OEFPDatabaseOptions::GetLimit` scores will be returned regardless of whether
      more scores fall within the cutoff range. A ``limit`` should be set for best performance.

      opts
        The :ref:`OEFPDatabaseOptions <OEGraphSim_OEFPDatabaseOptions>` object controls all the parameters
        that determine the search (i.e. similarity measure parameters).

      .. hint::

         This operation scales with :math:`n^2` in memory when
         ``limit = 0`` (or when ``limit`` is not set), so it can easily overwhelm
         the system memory for larger databases. The best practice is to set a
         reasonable ``limit`` that will capture the scores of interest.

      .. seealso::

         * :ref:`OEFPDatabaseOptions <OEGraphSim_OEFPDatabaseOptions>` class
         * :ref:`OESimScorePair <OEGraphSim_OESimScorePair>` class

   .. ################################################################
      #
      ################################################################

   .. oe:method:: GetVariogram

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

         .. oe:api::

            OEFPVariogram GetVariogram(const std::vector<float>& obsdata,
                                       const OEFPDatabaseOptions& opts,
                                       const size_t nrbins = 200u) const

      .. oe:language:: python

         .. oe:api:: python

            GetVariogram(obsdata: OEFloatVector, opts: OEFPDatabaseOptions,
                         nrbins: int = 200) -> OEFPVariogram

      Performs similarity calculations between all pairs of fingerprints
      stored in the :ref:`OEFastFPDatabase <OEGraphSim_OEFastFPDatabase>` object.
      It returns the empirical variogram over the calculated similarity scores
      with respect to the measurements provided in the ``obsdata`` parameter in a
      :ref:`OEFPVariogram <OEGraphSim_OEFPVariogram>` object.

      obsdata
        User-provided empirical measurements for each fingerprint in the database.

      opts
        The :ref:`OEFPDatabaseOptions <OEGraphSim_OEFPDatabaseOptions>` object controls all the
        parameters that determine the scoring (i.e. similarity measure parameters).
        Cutoff and order parameters are ignored as the results are not filtered or sorted.

      nrbins
        Number of bins in the returned :ref:`OEFPVariogram <OEGraphSim_OEFPVariogram>` object.

      .. note::

         The empirical variogram is defined over **distances rather than similarities**.
         It is therefore not possible to calculate a variogram using
         :ref:`section_measure_tversky` similarity.
         For all other similarity measures, empirical variogram is calculated
         using :math:`distance = 1-similarity`.

      .. hint::

         This method calculates similarities identically to
         :oe:meth:`OEGraphSim::OEFastFPDatabase::GetAllScores`
         but is not bound by the system memory. It can be used to quickly obtain
         statistics on larger databases.

      .. note::

         When the :ref:`OEFastFPDatabase <OEGraphSim_OEFastFPDatabase>` object is initialized
         with :oe:constns:`OEGraphSim::OEFastFPDatabaseMemoryType::CUDA`,
         ``nrbins`` is limited to at most 1024.

      .. hint::

         The returned :ref:`OEFPVariogram <OEGraphSim_OEFPVariogram>` object
         also contains a histogram, but note that this histogram is over
         **distances** rather than similarities.

      .. seealso::

         * :ref:`OEFPDatabaseOptions <OEGraphSim_OEFPDatabaseOptions>` class
         * :ref:`OEFPVariogram <OEGraphSim_OEFPVariogram>` class


   .. ################################################################
      #
      ################################################################

   .. oe:method:: IsValid

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

         .. oe:api::

            bool IsValid() const

      .. oe:language:: python

         .. oe:api:: python

            IsValid() -> bool

      Returns whether the database was initialized correctly.


   .. ################################################################
      #
      ################################################################

   .. oe:method:: NumFingerPrints

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

         .. oe:api::

            size_t NumFingerPrints() const

      .. oe:language:: python

         .. oe:api:: python

            NumFingerPrints() -> int

      Returns the number of :ref:`OEFingerPrint <OEGraphSim_OEFingerPrint>` objects
      stored in the database.

   .. ################################################################
      #
      ################################################################

   .. oe:method:: SortedSearch

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

         .. oe:api::

            unsigned SortedSearch(OESimSearchResult& result,
                                  const OEChem::OEMolBase& mol,
                                  const OEFPDatabaseOptions& opts) const

      .. oe:language:: python

         .. oe:api:: python

            SortedSearch(result: OESimSearchResult,
                         mol: Union[OEGraphMol,OEMol,OEQMol],
                         opts: OEFPDatabaseOptions) -> int

      Performs **multi-threaded** similarity calculations between a molecule and the
      fingerprints stored in the :ref:`OEFastFPDatabase <OEGraphSim_OEFastFPDatabase>` object.
      The method combines the functionality of the
      :oe:meth:`OEGraphSim::OEFastFPDatabase::GetSortedScores` and the
      :oe:meth:`OEGraphSim::OEFastFPDatabase::GetHistogram` methods.

      result
        The :ref:`OESimSearchResult <OEGraphSim_OESimSearchResult>` object that stores the result of the
        search along with the progress of the search and the histogram of all scores.

      mol
        If the method is called with an :ref:`OEMolBase <OEChem_OEMolBase>` object, a fingerprint
        is generated from this molecule before looping over the fingerprints of the
        database and calculating similarities.

      opts
        The :ref:`OEFPDatabaseOptions <OEGraphSim_OEFPDatabaseOptions>` object controls all the parameters
        that determine the search (i.e. similarity measure parameters).
        The :oe:meth:`OEGraphSim::OEFastFPDatabase::SortedSearch` method can use
        multiple threads to accelerate the search process. The number of processors used
        can be controlled by the :oe:meth:`OEGraphSim::OEFPDatabaseOptions::SetNumProcessors`
        method.

      The :oe:meth:`OEGraphSim::OEFastFPDatabase::SortedSearch` method returns:

      * :oe:const:`OEGraphSim::OESimSearchStatus::Uninitialized` if the similarity
        search can not be executed
      * :oe:const:`OEGraphSim::OESimSearchStatus::Finished`, if the similarity
        search successfully finished

      .. note::

         This method is currently only available in
         :oe:const:`OEGraphSim::OEFastFPDatabaseMemoryType::MemoryMapped` and
         :oe:const:`OEGraphSim::OEFastFPDatabaseMemoryType::InMemory` modes.

      **Example:**

      .. oe:source:: SortedSearch.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET

      .. oe:source:: SortedSearch.py
         :language: python
         :noindent:
         :frag:     SNIPPET

      ..  oe:language:: python

            :ref:`Full listing. <listing-SortedSearch.py>`


      .. oe:source:: SortedSearch.java
         :language: java
         :noindent:
         :frag:     SNIPPET

      .. oe:source:: SortedSearch.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET

      The output of the code snippet above might look like this:

      .. code-block:: console

         Search status = Finished
         Number of searched = 1000
         0.950
         0.912
         0.901
         0.886
         0.859
         [0.000-0.200] = 428
         [0.200-0.400] = 312
         [0.400-0.600] = 225
         [0.600-0.800] = 25
         [0.800-1.000] = 10

      .. seealso::

         * :oe:meth:`OEGraphSim::OEFastFPDatabase::GetSortedScores` method
         * :oe:meth:`OEGraphSim::OEFastFPDatabase::GetHistogram` method
         * :oe:constns:`OEGraphSim::OESimSearchStatus` namespace
