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

.. oe:namespace:: OEShape

.. meta::
   :keywords: OEBestOverlay, BestOverlay


.. _OEShape_OEBestOverlay:

.. oe:class:: OEBestOverlay

   .. oe:api::

      class OEBestOverlay

   .. note::

      This deprecated class will not be developed further. It is being replaced by
      :ref:`OEOverlay <OEShape_OEOverlay>` and :ref:`OEROCS <OEShape_OEROCS>` which provides
      more control and greater expandability.

   This class is used to optimize the overlap between 2
   molecules. Both molecules can contain one or more conformers. The
   reference molecule is held rigid and the fit molecule orientation
   is calculated to maximize overlap.  Each conformer of the fit
   molecule is optimized against each conformer of the reference
   molecule, resulting in a large number of results that can be
   returned. The :ref:`OEBestOverlayResults <OEShape_OEBestOverlayResults>` and
   :ref:`OEBestOverlayScore <OEShape_OEBestOverlayScore>` classes are used to make handling this
   large amount of results easier.

   Additionally, the reference or fit shape can be a grid instead of a molecule.

   Since an OEBestOverlay optimization can result in numerous final
   results, one for each starting position, the
   :ref:`OEBestOverlayResults <OEShape_OEBestOverlayResults>` class is a container to hold
   all the results for a fit conformer against a reference
   conformer. This class is essentially a container for one or more
   :ref:`OEBestOverlayScore <OEShape_OEBestOverlayScore>` instances.  The actual number
   of scores depends on the :oe:constns:`OEShape::OEBOOrientation` used
   in the OEBestOverlay.

   For :oe:const:`OEShape::OEBOOrientation::Inertial`, there will be 4,
   8 or 20 scores per ref-fit conformer pair, depending on the
   symmetry of each conformer.  For
   :oe:const:`OEShape::OEBOOrientation::AsIs`, there will be just 1
   :ref:`OEBestOverlayScore <OEShape_OEBestOverlayScore>` inside each
   :ref:`OEBestOverlayResults <OEShape_OEBestOverlayResults>` instance. And for
   :oe:const:`OEShape::OEBOOrientation::Random`, then there will be 1 OEBestOverlayScore for
   each of the **N** random starts. 

   When dealing with the results from OEBestOverlay, the user can
   either use a double loop, *i.e.* loop over all the
   OEBestOverlayResults instances for each ref-fit conformer pair then
   loop over each OEBestOverlayScore inside each OEBestOverlayResults
   instance. In this case, the results also come out in conformer
   order.

   .. oe:language:: c++

      .. code-block:: c++

         OEIter<OEBestOverlayResults> resiter = best.Overlay(fitmol);
         for (;resiter;++resiter)
         {
             OEIter<OEBestOverlayScore> scoreiter = resiter->GetScores();
             for (;scoreiter;++scoreiter)
             {
                 // do something with score
             }
         }

   .. oe:language:: python

      .. code-block:: python

         for res in best.Overlay(fitmol):
             for score in res.GetScores():
                 # do something with score 

   .. oe:language:: java

      .. code-block:: java

         OEBestOverlayResultsIter resiter = best.Overlay(fitmol);
         for (OEBestOverlayResults res : best.Overlay(fitmol)) {
             for (OEBestOverlayScore score : res.GetScores()) {
                 // do something with score
             }
         }


   Or, there is a free function
   :oe:func:`OEShape::OESortOverlayScores`, that takes an iterator of
   OEBestOverlayResults and returns a single, sorted iterator of
   OEBestOverlayScores that can be used in a single loop.

   .. oe:language:: c++

      .. code-block:: c++

         OEIter<OEBestOverlayResults> resiter = best.Overlay(fitmol);
         OEIter<OEBestOverlayScore> scoreiter;
         OESortOverlayScores(scoreiter, resiter, OEHighestTanimotoCombo());
         for (;scoreiter;++scoreiter)
         {
             // do something with score
         }

   .. oe:language:: python

      .. code-block:: python

         scoreiter = OEBestOverlayScoreIter()
         OESortOverlayScores(scoreiter, best.Overlay(fitmol), OEHighestTanimotoCombo())
         for score in scoreiter:
              # do something with score 

   .. oe:language:: java

      .. code-block:: java

         OEBestOverlayResultsIter resiter = best.Overlay(fitmol);
         OEBestOverlayScoreIter scoreiter = new OEBestOverlayScoreIter();
         oeshape.OESortOverlayScores(scoreiter, resiter, new OEHighestTanimotoCombo());
         for (OEBestOverlayScore score : scoreiter) {
             // do something with score
         }


   
   .. oe:method:: Constructors

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

         .. oe:api::

            OEBestOverlay()
            OEBestOverlay(const OEBestOverlay &)
            OEBestOverlay(const OEChem::OEMCMolBase& refmol)
            OEBestOverlay(const OESystem::OEScalarGrid& refgrid,
                          float interpolate = 0.5f)

      .. oe:language:: python

         .. oe:api:: python

            OEBestOverlay() -> OEBestOverlay
            OEBestOverlay(refmol: OEMol) -> OEBestOverlay
            OEBestOverlay(refgrid: OEScalarGrid, interpolate: float = 0.5) -> OEBestOverlay
            OEBestOverlay(arg2: OEBestOverlay) -> OEBestOverlay

      An empty OEBestOverlay class instance can be created, or a new
      instance can take the reference molecule or grid as an
      argument. Note that by default, grids that have a resolution
      larger that 0.5 |A| will be interpolated to that resolution.

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

      .. oe:api::

         OEBestOverlay &operator=(const OEBestOverlay &)

      The assignment operator.

      Assignment operator.

      
   .. oe:method:: ClearColorForceField

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

         .. oe:api::

            void ClearColorForceField()

      .. oe:language:: python

         .. oe:api:: python

            ClearColorForceField() -> None

      Clear out any color force field. No color scores will be calculated.

   .. oe:method:: ClearUserStarts

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

         .. oe:api::

            void ClearUserStarts()

      .. oe:language:: python

         .. oe:api:: python

            ClearUserStarts() -> None

      Set the number of User Starts back to zero. 

   .. oe:method:: GetCarbonRadius

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

         .. oe:api::

            float GetCarbonRadius() const

      .. oe:language:: python

         .. oe:api:: python

            GetCarbonRadius() -> float

      Return the current value for the carbon radius approximation.

   .. oe:method:: GetInitialOrientation

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

         .. oe:api::

            unsigned int GetInitialOrientation() const

      .. oe:language:: python

         .. oe:api:: python

            GetInitialOrientation() -> int

      Get the current value for initial orientation. Possible values are from the
      :oe:constns:`OEShape::OEBOOrientation` namespace.

   .. oe:method:: GetMaxRandomTranslation

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

         .. oe:api::

            float GetMaxRandomTranslation() const

      .. oe:language:: python

         .. oe:api:: python

            GetMaxRandomTranslation() -> float

      Get the value in |A| of maximum random translation. 


   .. oe:method:: GetMethod

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

         .. oe:api::

            unsigned int GetMethod() const

      .. oe:language:: python

         .. oe:api:: python

            GetMethod() -> int

      Return the current value of overlap method.


   .. oe:method:: GetMinimizeType

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

         .. oe:api::

            unsigned int GetMinimizeType() const

      .. oe:language:: python

         .. oe:api:: python

            GetMinimizeType() -> int

      Get the current value for minimize type. Possible values are from the
      :oe:constns:`OEShape::OEBOMinType` namespace.


   .. oe:method:: GetNumRandomStarts

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

         .. oe:api::

            unsigned int GetNumRandomStarts() const

      .. oe:language:: python

         .. oe:api:: python

            GetNumRandomStarts() -> int

      Get the current number of random starts. 
     
   .. oe:method:: GetNumUserStarts

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

         .. oe:api::

            unsigned int GetNumUserStarts() const

      .. oe:language:: python

         .. oe:api:: python

            GetNumUserStarts() -> int

      Get the number of user starts currently set. Note that these are not actually
      used unless :oe:const:`OEShape::OEBOOrientation::UserInertialStarts` is also set.

   .. oe:method:: GetRadiiApproximation

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

         .. oe:api::

            unsigned int GetRadiiApproximation() const

      .. oe:language:: python

         .. oe:api:: python

            GetRadiiApproximation() -> int

      Return the current value of the radii approximation.

   .. oe:method:: GetRandomSeed

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

         .. oe:api::

            unsigned int GetRandomSeed() const

      .. oe:language:: python

         .. oe:api:: python

            GetRandomSeed() -> int

      Get the current value of the random seed.

   .. oe:method:: GetRefGrid

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

         .. oe:api::

            const OESystem::OEScalarGrid* GetRefGrid() const

      .. oe:language:: python

         .. oe:api:: python

            GetRefGrid() -> OEScalarGrid

   .. oe:method:: GetRefMol

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

         .. oe:api::

            const OEChem::OEMCMolBase* GetRefMol() const

      .. oe:language:: python

         .. oe:api:: python

            GetRefMol() -> OEMol

   .. oe:method:: GetRefSelfColor

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

         .. oe:api::

            float GetRefSelfColor()

      .. oe:language:: python

         .. oe:api:: python

            GetRefSelfColor() -> float

      Return the self color score of the reference molecule.

   .. oe:method:: GetRefSymmetry

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

         .. oe:api::

            unsigned int GetRefSymmetry(unsigned int confIdx) const

      .. oe:language:: python

         .. oe:api:: python

            GetRefSymmetry(confIdx: int) -> int

      Return the current representation level.

   .. oe:method:: GetSymmetryThreshold

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

         .. oe:api::

            float GetSymmetryThreshold() const

      .. oe:language:: python

         .. oe:api:: python

            GetSymmetryThreshold() -> float

   .. oe:method:: GetUseHydrogens

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

         .. oe:api::

            bool GetUseHydrogens() const

      .. oe:language:: python

         .. oe:api:: python

            GetUseHydrogens() -> bool

      Return the status of hydrogen use in OEBestOverlay.
      
   .. oe:method:: GetUserStarts

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

         .. oe:api::

            bool GetUserStarts(float* xyz) const

      .. oe:language:: python

         .. oe:api:: python

            GetUserStarts(xyz: OEFloatArray) -> bool

      Extract the coordinates of the user starts. ``xyz`` should be sized to
      3 * GetNumUserStarts().

   .. oe:method:: Overlay

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

         .. oe:api::

            OESystem::OEIterBase<OEBestOverlayResults>* Overlay(const OEChem::OEMCMolBase& fitmol)

      .. oe:language:: python

         .. oe:api:: python

            Overlay(fitmol: OEMol) -> Iterable[OEBestOverlayResults]

      Perform the calculation and return the an iterator of the results. 

   .. oe:method:: SetCarbonRadius

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

         .. oe:api::

            void SetCarbonRadius(float cradius)

      .. oe:language:: python

         .. oe:api:: python

            SetCarbonRadius(cradius: float) -> None

      Set the radius to use when using
      :oe:const:`OEShape::OEOverlapRadii::Carbon`. By default this is
      set to 1.7 |A|.


   .. oe:method:: SetColorForceField

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

         .. oe:api::

            bool SetColorForceField(unsigned int type)
            bool SetColorForceField(OEPlatform::oeistream& is)
            bool SetColorForceField(const std::string& filename)
            bool SetColorForceField(const OEColorForceField& cff)

      .. oe:language:: python

         .. oe:api:: python

            SetColorForceField(type: int) -> bool
            SetColorForceField(ifs: oeistream) -> bool
            SetColorForceField(filename: str) -> bool
            SetColorForceField(cff: OEColorForceField) -> bool

      Set the color force field to be used. Once set, color scores
      will be calculated and included in the results. Color gradients
      will not be included in the optimization unless specifically set
      using SetColorOptimize(true).

   .. oe:method:: SetColorOptimize

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

         .. oe:api::

            void SetColorOptimize(bool state)

      .. oe:language:: python

         .. oe:api:: python

            SetColorOptimize(state: bool) -> None

      Add color gradients to shape gradients in the optimization. Has no effect unless
      a color force field is also set via :oe:meth:`OEShape::OEBestOverlay::SetColorForceField`.

   .. oe:method:: SetInitialOrientation

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

         .. oe:api::

            void SetInitialOrientation(unsigned int orient)

      .. oe:language:: python

         .. oe:api:: python

            SetInitialOrientation(orient: int) -> None

      Determines the initial orientation (starting position) for each
      optimization.  The default is
      :oe:const:`OEShape::OEBOOrientation::Inertial`. Alternatives are defined
      in the :oe:constns:`OEShape::OEBOOrientation` namespace.

   .. oe:method:: SetMaxRandomTranslation

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

         .. oe:api::

            void SetMaxRandomTranslation(float trans)

      .. oe:language:: python

         .. oe:api:: python

            SetMaxRandomTranslation(trans: float) -> None

      If using random starts, this set the maximum distance (in |A|)
      that the center of mass of the fit molecule will be moved away
      from the center calculated for inertial frame alignment.

   .. oe:method:: SetMethod

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

         .. oe:api::

            void SetMethod(unsigned int method)

      .. oe:language:: python

         .. oe:api:: python

            SetMethod(method: int) -> None

      Set the method used to calculate overlap. The default for
      OEBestOverlay is :oe:const:`OEShape::OEOverlapMethod::Grid`. Alternatives are defined
      in the :oe:constns:`OEShape::OEOverlapMethod` namespace.


   .. oe:method:: SetMinimizeType

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

         .. oe:api::

            void SetMinimizeType(unsigned int type)

      .. oe:language:: python

         .. oe:api:: python

            SetMinimizeType(type: int) -> None

      Set the score to use in the optimization. Options are in the
      :oe:constns:`OEShape::OEBOMinType` namespace.

   .. oe:method:: SetNumRandomStarts

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

         .. oe:api::

            void SetNumRandomStarts(unsigned int n)

      .. oe:language:: python

         .. oe:api:: python

            SetNumRandomStarts(n: int) -> None

      If SetInitialOrientation is set to
      :oe:const:`OEShape::OEBOOrientation::Random`, this method sets
      the number of random starting positions that will be used.

   .. oe:method:: SetRadiiApproximation

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

         .. oe:api::

            void SetRadiiApproximation(unsigned int type)

      .. oe:language:: python

         .. oe:api:: python

            SetRadiiApproximation(type: int) -> None

      Set the radius approximation used to calculate overlap. The
      default for OEBestOverlay is
      :oe:const:`OEShape::OEOverlapRadii::Carbon`. Alternatives are
      defined in the :oe:constns:`OEShape::OEOverlapRadii` namespace.


   .. oe:method:: SetRandomSeed

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

         .. oe:api::

            void SetRandomSeed(unsigned int seed)

      .. oe:language:: python

         .. oe:api:: python

            SetRandomSeed(seed: int) -> None

      Set a random seed value to allow reproducible random searches.

   .. oe:method:: SetRefGrid

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

         .. oe:api::

            bool SetRefGrid(const OESystem::OEScalarGrid& refgrid,
                            float interpolate = 0.5f)

      .. oe:language:: python

         .. oe:api:: python

            SetRefGrid(refgrid: OEScalarGrid, interpolate: float = 0.5) -> bool

      Set a reference grid for the calculation. OEBestOverlay makes an
      internal copy. Pre-existing reference molecules or grids are replaced.

   .. oe:method:: SetRefMol

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

         .. oe:api::

            bool SetRefMol(const OEChem::OEMCMolBase& refmol)

      .. oe:language:: python

         .. oe:api:: python

            SetRefMol(refmol: OEMol) -> bool

      Set a reference molecule for the calculation. OEBestOverlay makes an
      internal copy. Pre-existing reference molecules or grids are replaced.

   .. oe:method:: SetSymmetryThreshold

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

         .. oe:api::

            void SetSymmetryThreshold(float threshold)

      .. oe:language:: python

         .. oe:api:: python

            SetSymmetryThreshold(threshold: float) -> None

   .. oe:method:: SetUseHydrogens

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

         .. oe:api::

            void SetUseHydrogens(bool state)

      .. oe:language:: python

         .. oe:api:: python

            SetUseHydrogens(state: bool) -> None

      Boolean to determine whether hydrogens are included in the shape calculation.
      By default this is false and hydrogens are ignored.

   .. oe:method:: SetUserStarts

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

         .. oe:api::

            void SetUserStarts(const float* xyz, unsigned int nstarts)

      .. oe:language:: python

         .. oe:api:: python

            SetUserStarts(xyz: OEFloatArray, nstarts: int) -> None

      Set a set of 3D coordinates for doing separate inertial
      starts. ``xyz`` should be 3 * nstarts. These are not used unless
      :oe:const:`OEShape::OEBOOrientation::UserInertialStarts` is also set.
