Shape TK 2.0.0
================================================================================

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

* The **Shape TK** has been completely redesigned to make the library
  thread-safe, to make the library more flexible to use, and to allow the API
  to be easily extended with additional functionality.

* Three new classes, :ref:`OEExactShapeFunc <OEShape_OEExactShapeFunc>`,
  :ref:`OEGridShapeFunc <OEShape_OEGridShapeFunc>`, and
  :ref:`OEAnalyticShapeFunc <OEShape_OEAnalyticShapeFunc>`, have been added to provide
  static shape overlap calculation based on Exact, Grid, and Analytic
  methods.

* Three new classes, :ref:`OEExactColorFunc <OEShape_OEExactColorFunc>`,
  :ref:`OEGridColorFunc <OEShape_OEGridColorFunc>`, and
  :ref:`OEAnalyticColorFunc <OEShape_OEAnalyticColorFunc>`, have been added to provide
  static color score calculation based on Exact, Grid, and Analytic
  methods.

* A new class, :ref:`OEShapeOptions <OEShape_OEShapeOptions>`, has been added to define
  options related to all :ref:`OEShapeFunc <OEShape_OEShapeFunc>` evaluations.

* A new class, :ref:`OEColorOptions <OEShape_OEColorOptions>`, has been added to define
  options related to all :ref:`OEColorFunc <OEShape_OEColorFunc>` evaluations.

* A new class, :ref:`OEShapeGridOptions <OEShape_OEShapeGridOptions>`, has been added to define
  options related to grid-based method evaluations.

* A new class, :ref:`OEAnalyticOptions <OEShape_OEAnalyticOptions>`, has been added to define
  options related to analytic method evaluations.

* A new class, :ref:`OEOverlapPrep <OEShape_OEOverlapPrep>`, has been added that
  can be used to prepare molecules for shape and/or color calculations.

* A new class, :ref:`OEOverlay <OEShape_OEOverlay>`, has been added that
  can be used to overlay conformers of an :ref:`OEMol <OEChem_OEMol>` on
  a reference system that can be a molecule, grid, or shape query.

* A new class, :ref:`OEOverlayOptions <OEShape_OEOverlayOptions>`, has been added that
  sets all options for overlay optimization using :ref:`OEOverlay <OEShape_OEOverlay>`.
  :ref:`OEOverlayOptions <OEShape_OEOverlayOptions>` provides flexibility to optimize
  based on shape or color or both, to choose any method for shape or
  color calculation, and to optimize overlap or Tanimoto individually for shape
  and color.

* A new class, :ref:`OEROCS <OEShape_OEROCS>`, has been added that
  can be used to generate hits from a database on
  a reference system that can be a molecule, grid, or shape query.
  :ref:`OEROCS <OEShape_OEROCS>` provides top hits based on flexible
  scoring criterion.

* A new class, :ref:`OEROCSOptions <OEShape_OEROCSOptions>`, has been added to define
  options for generating hits using :ref:`OEROCS <OEShape_OEROCS>`.

* A new class, :ref:`OEROCSResult <OEShape_OEROCSResult>`, has been added that
  extends the :ref:`OEBestOverlayScore <OEShape_OEBestOverlayScore>` with overlaid
  conformer structures.

* Three overloads of a new function, :oe:meth:`OEShape::OEROCSOverlay`,
  have been added to provide the best hit between a pair of molecules.

* New unary predicates have been added to terminate a hit search
  calculation using :ref:`OEROCS <OEShape_OEROCS>`:

  * :ref:`OEColorTanimotoCutoff <OEShape_OEColorTanimotoCutoff>`
  * :ref:`OEFitColorTverskyCutoff <OEShape_OEFitColorTverskyCutoff>`
  * :ref:`OEFitTverskyComboCutoff <OEShape_OEFitTverskyComboCutoff>`
  * :ref:`OEFitTverskyCutoff <OEShape_OEFitTverskyCutoff>`
  * :ref:`OEOverlapCutoff <OEShape_OEOverlapCutoff>`
  * :ref:`OERefColorTverskyCutoff <OEShape_OERefColorTverskyCutoff>`
  * :ref:`OERefTverskyComboCutoff <OEShape_OERefTverskyComboCutoff>`
  * :ref:`OERefTverskyCutoff <OEShape_OERefTverskyCutoff>`

* The :ref:`OEShapeQueryPublic <OEShape_OEShapeQueryPublic>` class has been replaced by
  :ref:`OEShapeQuery <OEShape_OEShapeQuery>` and is complete with functionality to
  create and edit a shape query with combinations of molecules, grids,
  and Gaussians.

* With the introduction of the new API classes in **Shape TK**, several
  previously existing classes have been deprecated.  The following table
  shows the deprecated classes and their replacements:

  ===============================   ======================================
  Deprecated Class                  New Class
  -------------------------------   --------------------------------------
  ``OEShape::OEOverlap``            :ref:`OEExactShapeFunc <OEShape_OEExactShapeFunc>`
                                    :ref:`OEGridShapeFunc <OEShape_OEGridShapeFunc>`
                                    :ref:`OEAnalyticShapeFunc <OEShape_OEAnalyticShapeFunc>`

  ``OEShape::OEColorOverlap``       :ref:`OEExactColorFunc <OEShape_OEExactColorFunc>`
                                    :ref:`OEGridColorFunc <OEShape_OEGridColorFunc>`
                                    :ref:`OEAnalyticColorFunc <OEShape_OEAnalyticColorFunc>`

  ``OEShape::OEBestOverlay``        :ref:`OEOverlay <OEShape_OEOverlay>`
                                    :ref:`OEROCS <OEShape_OEROCS>`

  ``OEShape::OEColorResults``       :ref:`OEOverlapResults <OEShape_OEOverlapResults>`

  ``OEShape::OEShapeQueryPublic``   :ref:`OEShapeQuery <OEShape_OEShapeQuery>`
  ===============================   ======================================

* With the introduction of the new API, several obsolete functionalities
  have been removed.  These functionalities were added in
  the early development days of **Shape TK** and are no longer deemed useful.
  Methods related to such functionality, contained within the deprecated
  classes, are now ignored. The list of methods that fall into this category,
  with their current behavior, is as follows:

  * ``OEShape::OEOverlap::Overlap(const OESystem::OEScalarGrid&, OEOverlapResults&)``: The method does nothing and returns ``false``.
  * ``OEShape::OEOverlap::SetFitGrid(const OESystem::OEScalarGrid&)``: The method does nothing and returns ``false``.
  * ``OEShape::OEOverlap::SetRepresentationLevel(unsigned int)``: The method does nothing and returns ``false``.  The default representation level is ``OEShape::OEOverlapRepresentation::Atomic``.
  * ``OEShape::OEColorOverlap::SetAllColor(bool)``: The method does nothing and returns ``false``. The default ``AllColor`` state is ``true``.
  * ``OEShape::OEBestOverlay::SetAllColor(bool)``: The method does nothing and returns ``false``. The default ``AllColor`` state is ``true``.
  * ``OEShape::OEBestOverlay::SetInertialAxialDivisions(unsigned int)``: The method does nothing and returns ``false``.
  * ``OEShape::OEBestOverlay::SetRepresentationLevel(unsigned int)``: The method does nothing and returns ``false``.  The default representation level is ``OEShape::OEOverlapRepresentation::Atomic``.
  * ``OEShape::OEBestOverlay::Overlay(const OESystem::OEScalarGrid&)``: The method does nothing and returns an empty iterator.

Minor Bug Fixes
--------------------------------------------------------------------------------

* The Hermite grid generated by :ref:`OEHermite <OEShape_OEHermite>` was previously
  offset from the original frame of the molecule being expanded.  This has
  been corrected.

* Previously, using a molecule without 3D coordinates as a reference for an
  overlay had caused a crash.  This has been fixed.

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

* The **ShapeTK** examples have been rewritten to illustrate the use of
  the new API.  The various ``bestOverlay`` examples now have
  more descriptive names.
