.. oe:namespace:: OEFastROCS

.. meta::
   :keywords: OEShapeDatabase, ShapeDatabase


.. _OEFastROCS_OEShapeDatabase:

.. oe:class:: OEShapeDatabase

   .. oe:api::


       class OEShapeDatabase

   This is the primary class for performing **FastROCS TK**
   calculations. It is a very heavy-weight object: 

   - consuming many gigabytes of memory
   - managing many host threads
   - managing all GPU interaction 

   The goal is to allow abstracting away the complexities as much as
   possible to allow writing to a single API, allowing for the
   improvement of the underlying compute engine over time.

   Ideally, this class is initialized once per dataset. There is a
   fair amount of pre-calculation done on each molecule and conformer
   while being loaded into memory. Some of this can be alleviated by
   pre-calculating and caching, but not all of it, as there is a
   balance between caching and recalculation that is always being
   tuned.

   .. oe:method:: Constructors

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

         .. oe:api::

            OEShapeDatabase(const OEShape::OEColorForceField& cff,
                            unsigned int dbtype = OEShapeDatabaseType::Default)
            OEShapeDatabase(unsigned int dbtype = OEShapeDatabaseType::Default,
                            unsigned int cfftype = OEShape::OEColorFFType::OEDefault)

      .. oe:language:: python

         .. oe:api:: python

            OEShapeDatabase(dbtype: int, cfftype: int = OEColorFFType_OEDefault) -> OEShapeDatabase
            OEShapeDatabase(cff: OEColorForceField, dbtype: int) -> OEShapeDatabase

      Create a new :ref:`OEShapeDatabase <OEFastROCS_OEShapeDatabase>` for managing
      conformers and performing **FastROCS TK** calculations. 

      Whether the :ref:`OEShapeDatabase <OEFastROCS_OEShapeDatabase>` can perform
      color calculations must be chosen at construction. If "shape
      only" is chosen by passing
      :oe:const:`OEFastROCS::OEShapeDatabaseType::Shape`, then there
      can be significant memory and load-time performance
      improvements. Color atom assignment can be a significant cost
      during load and increase memory usage by roughly 2x.

      A custom :ref:`OEColorForceField <OEShape_OEColorForceField>` can be passed to
      this constructor as well to allow color scoring to be completely
      customized. Note, in the case of a custom color force field,
      :oe:const:`OEFastROCS::OEShapeDatabaseType::Default` is
      assumed. It is currently not possible to perform a "color only"
      scoring.

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

      .. oe:api::

         OEShapeDatabase & operator=(const OEShapeDatabase &)

      Assignment operator.



   .. oe:method:: AddMol

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

         .. oe:api::

            unsigned int AddMol(const OEChem::OEMCMolBase& mol,
                                const unsigned orient = OEFastROCSOrientation::Inertial)

      .. oe:language:: python

         .. oe:api:: python

            AddMol(mol: OEMol, orient: int) -> int

      Add a new collection of conformers to this database and return
      the index used to identify this molecule. This index will start
      at ``0`` and monotonically increase by ``1`` for every
      multi-conformer molecule
      added. :oe:meth:`OEFastROCS::OEShapeDatabaseScore::GetMolIdx`
      will return this index to be able to map **FastROCS** scores to
      molecules added through this mechanism.

      If using alternative start method
      :oe:constns:`OEFastROCS::OEFastROCSOrientation::AsIs`, this
      constant needs to be passed as the final argument to the AddMol routine
      so the database can be loaded without pre-processing conformer coordinates.
      The final argument is ignored for all other use cases and does not need
      to be changed from the default argument as all molecules are identically
      pre-processed for all other starting points.

      .. warning::

         Databases must be re-added if using :oe:constns:`OEFastROCS::OEFastROCSOrientation::AsIs`

      .. note::

         Even though this method is not ``const``, it has been made
         thread-safe so that it can be called from multiple
         threads. Furthermore, it has been optimized as much as
         possible to parallelize the pre-calculation this method
         performs. This makes it very efficient to use multiple
         threads to load a database file into memory.

   .. oe:method:: GetColorForceFieldType

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

         .. oe:api::

            unsigned int GetColorForceFieldType() const

      .. oe:language:: python

         .. oe:api:: python

            GetColorForceFieldType() -> int

      Return a constant from the :oe:constns:`OEShape::OEColorFFType`
      namespace to indicate the color force field used to construct
      this database. Returns
      :oe:const:`OEShape::OEColorFFType::Custom` if a custom
      :ref:`OEColorForceField <OEShape_OEColorForceField>` object was passed to the
      constructor.

   .. oe:method:: GetColorGridSpacing

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

         .. oe:api::

            float GetColorGridSpacing() const

      .. oe:language:: python

         .. oe:api:: python

            GetColorGridSpacing() -> float

      Return the grid spacing used to calculate color scores. This
      defaults to ``0.5`` for good performance. Lower values will
      yield answers that agree more closely with the ``Exact``
      analytical calculation, at the expense of performance. Higher
      values can yield better performance. The default was chosen as a
      good balance of virtual screening statistical analysis (AUCs) versus
      raw throughput performance.

   .. oe:method:: GetDatabaseType

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

         .. oe:api::

            unsigned int GetDatabaseType() const

      .. oe:language:: python

         .. oe:api:: python

            GetDatabaseType() -> int

      Returns a constant from the
      :oe:constns:`OEFastROCS::OEShapeDatabaseType` namespace
      indicating what type of calculations this database can perform. 

   .. oe:method:: GetDeviceToHostStrategy

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

         .. oe:api::

            unsigned int GetDeviceToHostStrategy() const

      .. oe:language:: python

         .. oe:api:: python

            GetDeviceToHostStrategy() -> int


   .. oe:method:: GetHostToDeviceStrategy

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

         .. oe:api::

            unsigned int GetHostToDeviceStrategy() const

      .. oe:language:: python

         .. oe:api:: python

            GetHostToDeviceStrategy() -> int

   .. oe:method:: GetMaxNumDevices

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

         .. oe:api::

            unsigned int GetMaxNumDevices() const

      .. oe:language:: python

         .. oe:api:: python

            GetMaxNumDevices() -> int

      Returns the maximum number of GPU devices this database will use
      for calculations. The only way to restrict the GPUs seen by the
      database is to use the ``CUDA_VISIBLE_DEVICES`` environment
      variable before starting the process.
      
      .. seealso::

         - :oe:meth:`OEFastROCS::OEShapeDatabase::SetNumDevices`

   .. oe:method:: GetMaxOptIterations

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

         .. oe:api::

            unsigned int GetMaxOptIterations() const

      .. oe:language:: python

         .. oe:api:: python

            GetMaxOptIterations() -> int

      Return the number of optimizer iterations the **FastROCS**
      algorithm should use when optimizing the alignment of the
      database conformer and the query conformer. This currently
      defaults to ``10`` based upon analysis of producing good virtual
      screening statistics (AUCs) without excessive iterations that
      would cost performance.

   .. oe:method:: GetNumDevices

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

         .. oe:api::

            unsigned int GetNumDevices() const

      .. oe:language:: python

         .. oe:api:: python

            GetNumDevices() -> int

      Returns the number of GPU devices this database will use for
      calculation. This will default to all the GPUs that are visible,
      i.e., the value returned from
      :oe:meth:`OEFastROCS::OEShapeDatabase::GetMaxNumDevices`.

   .. oe:method:: GetNumThreadsPerDevice

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

         .. oe:api::

            unsigned int GetNumThreadsPerDevice() const

      .. oe:language:: python

         .. oe:api:: python

            GetNumThreadsPerDevice() -> int

   .. oe:method:: GetNumOpenThreads

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

         .. oe:api::

            unsigned int GetNumOpenThreads() const

      .. oe:language:: python

         .. oe:api:: python

            GetNumOpenThreads() -> int

      Return how many CPU threads will be used to read a
      :ref:`OEMolDatabase <OEChem_OEMolDatabase>` from disk into memory using the
      :oe:meth:`OEFastROCS::OEShapeDatabase::Open` method. The
      default, a value of ``0``, is to use as many CPUs as can be
      found on the system with
      :oe:func:`OEPlatform::OEGetNumProcessors`.

   .. oe:method:: GetScores

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

         .. oe:api::

            OESystem::OEIterBase<OEShapeDatabaseScore> * GetScores(const OEChem::OEMolBase& query,
                                                                   const OEShapeDatabaseOptions& options = OEShapeDatabaseOptions()) const
            OESystem::OEIterBase<OEShapeDatabaseScore> * GetScores(const OEShape::OEShapeQueryPublic& shapeQry,
                                                                   const OEShapeDatabaseOptions& options = OEShapeDatabaseOptions()) const
            OESystem::OEIterBase<OEShapeDatabaseScore> * GetScores(const OEShape::OEShapeQuery& shapeQry,
                                                                   const OEShapeDatabaseOptions& options = OEShapeDatabaseOptions()) const

      .. oe:language:: python

         .. oe:api:: python

            GetScores(arg1: OEShapeQueryPublic,
                      options: OEShapeDatabaseOptions = OEFastROCS_OEShapeDatabaseOptions()) -> Iterable[OEFastROCS_OEShapeDatabaseScore]
            GetScores(arg1: OEShapeQuery,
                      options: OEShapeDatabaseOptions = OEFastROCS_OEShapeDatabaseOptions()) -> Iterable[OEFastROCS_OEShapeDatabaseScore]
            GetScores(query: Union[OEGraphMol,OEMol,OEQMol],
                      options: OEShapeDatabaseOptions = OEFastROCS_OEShapeDatabaseOptions()) -> Iterable[OEFastROCS_OEShapeDatabaseScore]

      Return **ALL** scores of the query against the entire database
      subject to the options specified in the
      :ref:`OEShapeDatabaseOptions <OEFastROCS_OEShapeDatabaseOptions>` passed to this
      method. This is useful for performing larger scale ``NxN``
      clustering type of calculations where all pairs of scores need
      to be processed.

      The query can be either a single conformer
      :ref:`OEMolBase <OEChem_OEMolBase>`, a :ref:`OEShapeQuery <OEShape_OEShapeQuery>` or a
      :ref:`OEShapeQueryPublic <OEShape_OEShapeQueryPublic>` object read from a ``.sq``
      file. :ref:`OEShapeQuery <OEShape_OEShapeQuery>` or :ref:`OEShapeQueryPublic <OEShape_OEShapeQueryPublic>`
      objects must contain a molecule. To determine if your OEShapeQuery object
      is **FastROCS**-friendly see :oe:func:`OEShape::OEIsFastROCSShapeQuery` in the
      **Shape TK**.

      When passing an :ref:`OEMolBase <OEChem_OEMolBase>` query, the molecule must
      have 3D coordinates assigned and must have been preprocessed with
      :oe:func:`OEFastROCS::OEPrepareFastROCSMol` before calling this method.

      .. warning:: 

         The order of the :ref:`OEShapeDatabaseScore <OEFastROCS_OEShapeDatabaseScore>`
         returned by the iterator is non-deterministic and will
         certainly change for each execution due to the multi-threaded
         nature of this method. However, the values calculated in each
         :ref:`OEShapeDatabaseScore <OEFastROCS_OEShapeDatabaseScore>` will be the
         same. Therefore, users should rely on the return value of
         :oe:meth:`OEFastROCS::OEShapeDatabaseScore::GetMolIdx` and
         :oe:meth:`OEFastROCS::OEShapeDatabaseScore::GetConfIdx` to do further
         processing, not the location within the iterator.

      .. seealso:: 

         The :ref:`OEShapeDatabaseOptions <OEFastROCS_OEShapeDatabaseOptions>` class is
         used to control many of the parameters to this method. For
         example, how many conformers per molecule to return.

   .. oe:method:: GetShapeGridSpacing

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

         .. oe:api::

            float GetShapeGridSpacing() const

      .. oe:language:: python

         .. oe:api:: python

            GetShapeGridSpacing() -> float

      Return the grid spacing used to calculate shape scores and drive
      the alignment. This defaults to ``0.5`` for good
      performance. Lower values will yield answers that agree more
      closely with the ``Exact`` analytical calculation, at the
      expense of performance. Higher values can yield better
      performance. The default was chosen as a good balance of virtual
      screening statistical analysis (AUCs) versus raw throughput
      performance.


   .. oe:method:: GetSortedScores

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

         .. oe:api::

            OESystem::OEIterBase<OEShapeDatabaseScore> * GetSortedScores(const OEChem::OEMolBase& query,
                                                                         unsigned int limit = 0) const
            OESystem::OEIterBase<OEShapeDatabaseScore> * GetSortedScores(const OEChem::OEMolBase& query,
                                                                         const OEShapeDatabaseOptions& options) const
            OESystem::OEIterBase<OEShapeDatabaseScore> * GetSortedScores(const OEShape::OEShapeQueryPublic& shapeQry,
                                                                         const OEShapeDatabaseOptions& options = OEShapeDatabaseOptions()) const
            OESystem::OEIterBase<OEShapeDatabaseScore> * GetSortedScores(const OEShape::OEShapeQuery& shapeQry,
                                                                         const OEShapeDatabaseOptions& options = OEShapeDatabaseOptions()) const

      .. oe:language:: python

         .. oe:api:: python

            GetSortedScores(arg1: OEShapeQueryPublic,
                            options: OEShapeDatabaseOptions = OEFastROCS_OEShapeDatabaseOptions()) -> Iterable[OEFastROCS_OEShapeDatabaseScore]
            GetSortedScores(arg1: OEShapeQuery,
                            options: OEShapeDatabaseOptions = OEFastROCS_OEShapeDatabaseOptions()) -> Iterable[OEFastROCS_OEShapeDatabaseScore]
            GetSortedScores(query: Union[OEGraphMol,OEMol,OEQMol],
                            limit: int = 0) -> Iterable[OEFastROCS_OEShapeDatabaseScore]
            GetSortedScores(query: Union[OEGraphMol,OEMol,OEQMol],
                            options: OEShapeDatabaseOptions) -> Iterable[OEFastROCS_OEShapeDatabaseScore]

      Return a hitlist of the ``query`` against the database based
      upon the scoring options of the database and the
      :ref:`OEShapeDatabaseOptions <OEFastROCS_OEShapeDatabaseOptions>` passed to this
      method. The :ref:`OEShapeDatabaseScore <OEFastROCS_OEShapeDatabaseScore>` will be
      returned in descending order, i.e., the better 'hits' will come
      first in the iterator.

      The query can be either a single conformer
      :ref:`OEMolBase <OEChem_OEMolBase>`, a :ref:`OEShapeQuery <OEShape_OEShapeQuery>` or a
      :ref:`OEShapeQueryPublic <OEShape_OEShapeQueryPublic>` object read from a ``.sq``
      file. :ref:`OEShapeQuery <OEShape_OEShapeQuery>` or :ref:`OEShapeQueryPublic <OEShape_OEShapeQueryPublic>`
      objects must contain a molecule. To determine if your OEShapeQuery object
      is **FastROCS**-friendly see :oe:func:`OEShape::OEIsFastROCSShapeQuery` in the
      **Shape TK**.

      When passing an :ref:`OEMolBase <OEChem_OEMolBase>` query, the molecule must
      have 3D coordinates assigned and must have been preprocessed with
      :oe:func:`OEFastROCS::OEPrepareFastROCSMol` before calling this method.

      .. note:: 

         This method is typically used to select only a subset of the
         results based upon ``limit`` or
         :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::SetLimit`. It
         is optimized for rapidly constructing relatively small
         hitlists. If the entire set of scores for the database is
         desired, it can be faster to use the
         :oe:meth:`OEFastROCS::OEShapeDatabase::GetScores` to avoid
         the sorting operation.

      .. seealso:: 

         The :ref:`OEShapeDatabaseOptions <OEFastROCS_OEShapeDatabaseOptions>` class is
         used to control many of the parameters to this method. For
         example, how many conformers per molecule to return.

   .. oe:method:: NumConfs

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

         .. oe:api::

            unsigned int NumConfs() const

      .. oe:language:: python

         .. oe:api:: python

            NumConfs() -> int

      Return the number of conformers the database is currently
      managing. Useful for getting a ballpark idea of the underlying
      memory usage.

      .. note::

         This value has no relation to the indexes returned by
         :oe:meth:`OEFastROCS::OEShapeDatabase::AddMol`, except that
         this value will always be larger than the last index
         returned.

   .. oe:method:: Open

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

         .. oe:api::

            bool Open(const OEChem::OEMolDatabase& moldb,
                      const unsigned int orient = OEFastROCSOrientation::Inertial)
            bool Open(const OEChem::OEMolDatabase& moldb,
                      OESystem::OEThreadedDots& dots,
                      const unsigned int orient = OEFastROCSOrientation::Inertial)

      .. oe:language:: python

         .. oe:api:: python

            Open(moldb: OEMolDatabase, orient: int) -> bool
            Open(moldb: OEMolDatabase, dots: OEThreadedDots, orient: int) -> bool

      Initialize the database using a
      :ref:`OEMolDatabase <OEChem_OEMolDatabase>`. This is the most efficient way
      to initialize a :ref:`OEShapeDatabase <OEFastROCS_OEShapeDatabase>` as this
      method will launch an operating thread for each CPU core
      available and parallelize all the parsing and
      pre-calculation. The progress of the loading operation can be
      tracked through a thread-safe :ref:`OEThreadedDots <OESystem_OEThreadedDots>`
      object. 
      
      If using alternative start method
      :oe:constns:`OEFastROCS::OEFastROCSOrientation::AsIs`, this
      constant needs to be passed as the final argument to the Open routine 
      so the database can be loaded without adjusting conformer coordinates. 
      The final argument can be left blank for all other use cases.

      .. warning::

         Databases must be re-opened if using :oe:constns:`OEFastROCS::OEFastROCSOrientation::AsIs`

      This method will block and return ``true`` when the
      database has been successfully loaded into memory. 

      .. note::

         The indices returned by
         :oe:meth:`OEFastROCS::OEShapeDatabaseScore::GetMolIdx` are
         guaranteed to map directly into the
         :ref:`OEMolDatabase <OEChem_OEMolDatabase>` index space.
         :oe:meth:`OEChem::OEMolDatabase::GetMolecule` can fail and
         return no molecule for good reason, i.e., an empty molecule
         from an SD file. Therefore, the index space used by
         :ref:`OEShapeDatabase <OEFastROCS_OEShapeDatabase>` can have "holes" when
         initialized from a :ref:`OEMolDatabase <OEChem_OEMolDatabase>`.


   .. oe:method:: PrintMemoryUsage

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

         .. oe:api::

            void PrintMemoryUsage(OEPlatform::oeostream& os) const
            void PrintMemoryUsage() const

      .. oe:language:: python

         .. oe:api:: python

            PrintMemoryUsage(os: oeostream) -> None
            PrintMemoryUsage() -> None

      Print out memory usage statistics for this object. This will
      break down how much memory is being used to pre-cache various
      parts of the calculation. By default, the output will be written to
      :oe:const:`OEPlatform::OEPlatform::oeerr`. The output stream can also
      be passed as an argument. The diagnostic output is meant for human
      consumption and may change format in future releases. 


   .. oe:method:: SetColorGridSpacing

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

         .. oe:api::

            bool SetColorGridSpacing(float gridSpacing)

      .. oe:language:: python

         .. oe:api:: python

            SetColorGridSpacing(gridSpacing: float) -> bool

      Set the grid spacing to use for static color scoring. 

      .. seealso:: 

         - :oe:meth:`OEFastROCS::OEShapeDatabase::GetColorGridSpacing`

   .. oe:method:: SetDeviceToHostStrategy

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

         .. oe:api::

            void SetDeviceToHostStrategy(unsigned int strat)

      .. oe:language:: python

         .. oe:api:: python

            SetDeviceToHostStrategy(strat: int) -> None

   .. oe:method:: SetHostToDeviceStrategy

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

         .. oe:api::

            void SetHostToDeviceStrategy(unsigned int strat)

      .. oe:language:: python

         .. oe:api:: python

            SetHostToDeviceStrategy(strat: int) -> None

   .. oe:method:: SetMaxOptIterations

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

         .. oe:api::

            void SetMaxOptIterations(unsigned int maxIter)

      .. oe:language:: python

         .. oe:api:: python

            SetMaxOptIterations(maxIter: int) -> None

      Set the number of optimizer iterations to use when optimizing
      the alignment by shape.

      .. seealso:: 

         - :oe:meth:`OEFastROCS::OEShapeDatabase::GetMaxOptIterations`

   .. oe:method:: SetNumDevices

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

         .. oe:api::

            void SetNumDevices(unsigned int ndevices)

      .. oe:language:: python

         .. oe:api:: python

            SetNumDevices(ndevices: int) -> None

      Set the number of GPU devices this calculation should use. This
      number should be between ``1`` and
      :oe:meth:`OEFastROCS::OEShapeDatabase::GetMaxNumDevices`
      inclusively. This method is really only useful to efficiently
      collecting **FastROCS** scalability data across multiple
      GPUs. To restrict :ref:`OEShapeDatabase <OEFastROCS_OEShapeDatabase>` to only
      run on a subset of GPUs on the machine, use the
      ``CUDA_VISIBLE_DEVICES`` environment variable instead before the
      process is launched.

   .. oe:method:: SetNumThreadsPerDevice

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

         .. oe:api::

            void SetNumThreadsPerDevice(unsigned int numThrds)

      .. oe:language:: python

         .. oe:api:: python

            SetNumThreadsPerDevice(numThrds: int) -> None

   .. oe:method:: SetNumOpenThreads

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

         .. oe:api::

            void SetNumOpenThreads(unsigned int numThrds)

      .. oe:language:: python

         .. oe:api:: python

            SetNumOpenThreads(numThrds: int) -> None

      Set how many CPU threads should be created to read a
      :ref:`OEMolDatabase <OEChem_OEMolDatabase>` from disk into memory using the
      :oe:meth:`OEFastROCS::OEShapeDatabase::Open` method. A value of
      ``0`` specifies that all CPUs in the system will be used. The
      value passed to this method should not exceed the value returned
      by :oe:func:`OEPlatform::OEGetNumProcessors`.

   .. oe:method:: SetShapeGridSpacing

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

         .. oe:api::

            bool SetShapeGridSpacing(float gridSpacing)

      .. oe:language:: python

         .. oe:api:: python

            SetShapeGridSpacing(gridSpacing: float) -> bool

      Set the grid spacing to use for shape scoring and alignment. 

      .. seealso:: 

         - :oe:meth:`OEFastROCS::OEShapeDatabase::GetShapeGridSpacing`
