.. oe:namespace:: OEFastROCS

.. oe:constnamespace:: OEFastROCSOrientation 

   The **FastROCS TK** search algorithm performs an optimization to maximize
   the overlap between the query and the database molecule. This namespace
   defines a set of initial orientations for the optimization that are also
   referred to as alternative starts.  The default orientation is
   :oe:const:`OEFastROCS::OEFastROCSOrientation::Inertial`, which can also
   be accessed via :oe:const:`OEFastROCS::OEFastROCSOrientation::Default`. 
   As the optimization has a limited number of iterations, it may be
   beneficial to use alternative starting coordinates for some molecular
   systems.  To set an alternative initial orientation
   use :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::SetInitialOrientation`.

   At present there are 7 initial orientations available: 

      - :oe:const:`OEFastROCS::OEFastROCSOrientation::Inertial` 
      - :oe:const:`OEFastROCS::OEFastROCSOrientation::UserInertialStarts`
      - :oe:const:`OEFastROCS::OEFastROCSOrientation::InertialAtHeavyAtoms`
      - :oe:const:`OEFastROCS::OEFastROCSOrientation::InertialAtColorAtoms`
      - :oe:const:`OEFastROCS::OEFastROCSOrientation::AsIs`
      - :oe:const:`OEFastROCS::OEFastROCSOrientation::Random`
      - :oe:const:`OEFastROCS::OEFastROCSOrientation::Subrocs`

   .. seealso::

      - :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::SetInitialOrientation`
      - :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::GetInitialOrientation`
      - :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::SetUserStarts`
      - :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::GetUserStarts`
      - :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::GetNumStarts`
      - :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::GetNumUserStarts`
      - :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::GetNumHeavyAtomStarts`
      - :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::GetNumColorAtomStarts`

   .. oe:constant:: Default
   
      The default orientation is
      :oe:const:`OEFastROCS::OEFastROCSOrientation::Inertial`.

   .. oe:constant:: Inertial
  
      The query and the database molecule are aligned to the inertial frame
      and optimizations are performed for 4 inertial orientations of the
      database molecule, by rotating about its 2 major moments of inertia. 

   .. oe:constant:: UserInertialStarts
 
      The database molecule is translated to each user-defined starting
      position and optimizations are performed for 4 inertial starts for
      each translation.  See
      :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::SetInitialOrientation` and 
      :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::SetUserStarts` for
      more details on setting the starting coordinates. 

   .. warning::
      
      Currently, error checking is not performed for user-defined starting
      coordinates that fall out of scope of the molecule's coordinate range
      therefore, bad starting coordinates will yield zero shape/color overlap.
      
   .. oe:constant:: InertialAtHeavyAtoms
 
      The database molecule is translated to each heavy atom of the query
      molecule and optimizations are performed for 4 inertial starts
      for each translation.   
      See
      :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::SetInitialOrientation` and 
      :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::GetInitialOrientation`

   .. oe:constant:: InertialAtColorAtoms
 
      The database molecule is translated to each color atom of the
      query molecule and 
      optimizations are performed for 4 inertial starts for each translation.   
      This method works for combo and shape-only searches. The only
      requirement is that the query molecule has color atoms. If the query
      molecule does not have color atoms the search will default to
      :oe:constns:`OEFastROCS::OEFastROCSOrientation::Inertial`.
      See :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::SetInitialOrientation`, 
      :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::GetInitialOrientation` and
      :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::GetNumColorAtomStarts`.

   .. oe:constant:: AsIs
 
      The query and database molecules are left ``AsIs``. It is presumed
      that the conformers are already positioned in space (perhaps through
      docking) therefore they are not centered or set to the inertial frame
      of reference. This method carries out a single
      optimization at the query and database molecule's original coordinates.
      No inertial orientations are optimized. 

      .. warning::
 
        In order to use this method on a database the entire database is
        required to be reloaded with the
        :oe:meth:`OEFastROCS::OEShapeDatabase::Open` or
        :oe:meth:`OEFastROCS::OEShapeDatabase::AddMol` routine using
        ``unsigned int orient=OEFastROCSOrientation::AsIs`` as the
        last argument. 

      .. warning::

        In order to use the
        :oe:meth:`OEFastROCS::OEShapeDatabaseScore::Constructors` with 
        this method it is required that the final argument to the constructor
        be ``unsigned int orient=OEFastROCSOrientation::AsIs``.

      See :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::SetInitialOrientation`, 
      :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::GetInitialOrientation`,
      :oe:meth:`OEFastROCS::OEShapeDatabase::Open` and
      :oe:meth:`OEFastROCS::OEShapeDatabaseScore::Constructors`.
      
   .. oe:constant:: Random 

      N random starts are generated by randomly orientating the database molecule
      N times. This method includes the ability to set the maximum random 
      translation via the :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::SetMaxRandomTranslation`,
      option. The default maximum is ``2`` angstroms. 
      The number of random starts can be set using the 
      :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::SetNumRandomStarts` option. The default number 
      of random starts is ``10``. 
      The random seed can be set using the :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::SetRandomSeed`. 
      The default random seed is based on the time.   

      .. warning::

       The random API point is only deterministic when using the same seed if only 
       one thread  is set to open the database using :oe:meth:`OEFastROCS::OEShapeDatabase::SetNumOpenThreads` 
       between calls to GetScores or GetScores is called on the same opened database object.

      See :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::SetInitialOrientation` 
      :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::GetInitialOrientation`
      :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::SetMaxRandomTranslation`
      :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::GetMaxRandomTranslation`
      :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::SetNumRandomStarts`
      :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::GetNumRandomStarts`
      :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::SetRandomSeed`
      :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::GetRandomSeed`

   .. oe:constant:: Subrocs 

      Optimizations are carried for each inertial orientation at each heavy atom of the molecule with the
      most heavy atoms regardless of whether it is the query or the database molecule. This method is synonymous
      with :oe:const:`OEFastROCS::OEFastROCSOrientation::InertialAtHeavyAtoms`.

      See :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::SetInitialOrientation` 
      :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::GetInitialOrientation`

   See the :ref:`starts_for_optimization` section in the **Shape TK**
   theory documentation for a description of alternative starts. 
