FastROCS TK 1.8.2
================================================================================

New features
--------------------------------------------------------------------------------

* Alternative starting points in **FastROCS TK** have been extended to now
  include :oe:constns:`OEFastROCS::OEFastROCSOrientation::AsIs` and
  :oe:constns:`OEFastROCS::OEFastROCSOrientation::InertialAtColorAtoms`.

  * :oe:constns:`OEFastROCS::OEFastROCSOrientation::AsIs` presumes that the
    query and the database molecules are already correctly aligned in space
    (perhaps through docking), so a single optimization per query-database
    molecule pair is carried out.

  * :oe:constns:`OEFastROCS::OEFastROCSOrientation::InertialAtColorAtoms`
    translates each database molecule to each color atom of the query molecule
    and optimizes for 4 inertial poses at each translation. This method can
    be used with both shape-only searches and combo searches. The only
    requirement is that the query molecule must have color atoms; otherwise,
    the search will throw a warning and default to inertial starts.

  See :oe:constns:`OEFastROCS::OEFastROCSOrientation`
  and :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::SetInitialOrientation` for
  more information.

* The following new getter methods have been added to
  :ref:`OEShapeDatabaseOptions <OEFastROCS_OEShapeDatabaseOptions>` for retrieving the number
  of starts for the relevant method:

   * :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::GetNumUserStarts`
   * :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::GetNumColorAtomStarts`
   * :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::GetNumHeavyAtomStarts`
   * :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::GetNumStarts`

  :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::GetNumStarts`
  has also been overloaded for each alternative start option.

* A new argument has been added to
  :oe:meth:`OEFastROCS::OEShapeDatabase::Open` to ensure that
  conformers are correctly handled when using
  :oe:constns:`OEFastROCS::OEFastROCSOrientation::AsIs`.

  When using the new :oe:constns:`OEFastROCS::OEFastROCSOrientation::AsIs`
  feature, the shape database must be opened with the additional argument set
  to :oe:constns:`OEFastROCS::OEFastROCSOrientation::AsIs`.

  There is no need to alter existing scripts if the
  :oe:constns:`OEFastROCS::OEFastROCSOrientation::AsIs` alternative
  starts feature is not being used since the default argument
  results in the correct execution path for all other use cases.

  See :oe:meth:`OEFastROCS::OEShapeDatabase::Open` and
  :oe:constns:`OEFastROCS::OEFastROCSOrientation::AsIs` for more information.

* A new argument has been added to
  :oe:meth:`OEFastROCS::OEShapeDatabaseScore::Constructors` to
  correctly transform conformers to their resultant position when using
  :oe:constns:`OEFastROCS::OEFastROCSOrientation::AsIs`.

  Generally, the constructor is not used in most scripts as the
  :ref:`OEShapeDatabaseScore <OEFastROCS_OEShapeDatabaseScore>` object is constructed
  internally when calling
  :oe:meth:`OEFastROCS::OEShapeDatabase::GetScores` or
  :oe:meth:`OEFastROCS::OEShapeDatabase::GetSortedScores`.
  Therefore, most users will not be affected by this change.

  If the :ref:`OEShapeDatabaseScore <OEFastROCS_OEShapeDatabaseScore>` constructor is used and
  :oe:constns:`OEFastROCS::OEFastROCSOrientation::AsIs` is set,
  the constructor can be modified with the additional argument set to
  :oe:constns:`OEFastROCS::OEFastROCSOrientation::AsIs`.

  The default value for the additional argument satisfies all other use
  cases, so no action is required.

  See :oe:meth:`OEFastROCS::OEShapeDatabaseScore::Constructors` for more
  information.

Major bug fixes
--------------------------------------------------------------------------------

* Previously, GPU memory limits were being reached for routine searches when
  using :oe:constns:`OEFastROCS::OEFastROCSOrientation::InertialAtHeavyAtoms`,
  causing searches to default to
  :oe:constns:`OEFastROCS::OEFastROCSOrientation::Inertial`.
  The improved alternative starts algorithm handles any number
  of starts without reaching GPU memory limits.

  .. warning::

     Performance will be affected by using large numbers of alternative
     starts.

* :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::SetMaxOverlays` now sets
  the number of overlay results to return per conformer.  Previously, this
  was broken and was restricting the number of overlays to 1 per conformer
  regardless of its setting.
  :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::SetMaxOverlays` is now fixed
  and works correctly with
  :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::SetMaxConfs`,
  :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::SetNumInertialStarts`
  and alternative starts for both
  :oe:meth:`OEFastROCS::OEShapeDatabase::GetScores` and
  :oe:meth:`OEFastROCS::OEShapeDatabase::GetSortedScores`.

* Tversky calculations no longer overestimate the score of caged systems or
  conformer pairs where one conformer is much larger than the other.

Minor bug fixes
--------------------------------------------------------------------------------

* A warning is now thrown if
  :oe:constns:`OEFastROCS::OEFastROCSOrientation::UserInertialStarts`
  is set with
  :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::SetInitialOrientation` and
  :oe:meth:`OEFastROCS::OEShapeDatabase::GetScores` or if
  :oe:meth:`OEFastROCS::OEShapeDatabase::GetSortedScores` is called before
  :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::SetUserStarts`.

Documentation changes
--------------------------------------------------------------------------------

* A tutorials page has been created that walks through features of
  **FastROCS TK** and gives detailed examples.  The first tutorial gives
  step-by-step instructions on how to use alternative starts.

  If you have a specific feature that you would like
  in a tutorial, please contact support at support@eyesopen.com
  with the subject header **FastROCS TK Tutorial Request**.
