.. oe:namespace:: OEShape

.. meta::
   :keywords: OEStarts, Starts


.. _OEShape_OEStarts:

.. oe:class:: OEStarts

   .. oe:api::


      class OEStarts

   The :ref:`OEStarts <OEShape_OEStarts>` is an abstract base class. This class defines
   an interface for providing various kinds of starts for overlay optimization
   calculations.  Most methods in this interface are useful for advanced users
   who want to create their own optimization workflow using these starts. To
   specify starts for :ref:`OEOverlay <OEShape_OEOverlay>` or :ref:`OEROCS <OEShape_OEROCS>`
   calculations, a user merely needs to instantiate the appropriate
   :ref:`OEStarts <OEShape_OEStarts>`.


   .. _figure_OEStarts_Hierarchy:

   .. figure:: ../images/OEStarts.*
      :align:  center

   The :ref:`OEStarts <OEShape_OEStarts>` class defines the following public methods:
    * :oe:meth:`CreateCopy<OEShape::OEStarts::CreateCopy>`  
    * :oe:meth:`GetNumOfStarts<OEShape::OEStarts::GetNumOfStarts>` 
    * :oe:meth:`GetStarts<OEShape::OEStarts::GetStarts>`
    * :oe:meth:`Setup<OEShape::OEStarts::Setup>` 
    * :oe:meth:`SetupRef<OEShape::OEStarts::SetupFrame>`
    * :oe:meth:`SetupRef<OEShape::OEStarts::SetupRef>`

   The following classes derive from this class:
    * :ref:`OEAsIsStarts <OEShape_OEAsIsStarts>`
    * :ref:`OEAtAtomStarts <OEShape_OEAtAtomStarts>`
    * :ref:`OECartesianStarts <OEShape_OECartesianStarts>`
    * :ref:`OEInertialStarts <OEShape_OEInertialStarts>`
    * :ref:`OEQuatStarts <OEShape_OEQuatStarts>`
    * :ref:`OERandomStarts <OEShape_OERandomStarts>`
    * :ref:`OESubrocsStarts <OEShape_OESubrocsStarts>`

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

      .. oe:api::

         OEStarts & operator=(const OEStarts &)

      Assignment operator.


   .. oe:method:: CreateCopy

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

         .. oe:api::

            OEStarts* CreateCopy() const = 0

      .. oe:language:: python

         .. oe:api:: python

            CreateCopy() -> OEStarts

      Returns a new instance of an :ref:`OEStarts <OEShape_OEStarts>` with the same parameters
      as the inherent starts.

   .. oe:method:: GetNumOfStarts

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

         .. oe:api::

            unsigned int GetNumOfStarts() const

      .. oe:language:: python

         .. oe:api:: python

            GetNumOfStarts() -> int

      Returns the number of starts currently set. In most cases, the number of starts 
      depends on the reference and the fit object to be used for optimization.  Both
      :oe:meth:`SetupRef<OEShape::OEStarts::SetupRef>` and :oe:meth:`Setup<OEShape::OEStarts::Setup>` should be called to set up the reference and fit information prior to accessing
      the number of starts for any specific optimization.

   .. oe:method:: GetStarts

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

         .. oe:api::

            bool GetStarts(double* argQuats) const

      .. oe:language:: python

         .. oe:api:: python

            GetStarts(argQuats: OEDoubleArray) -> bool

      Returns the starting quaternions currently set. In most cases, the number of starts 
      depends on the reference and the fit object to be used for optimization.  Both
      :oe:meth:`SetupRef<OEShape::OEStarts::SetupRef>` and :oe:meth:`Setup<OEShape::OEStarts::Setup>` should be called to set up the reference and fit information prior to accessing
      the number of starts for any specific optimization.

      The array passed in for obtaining the starting quaternions must have a length of at least
      7*(NumStarts).


    .. _OEShape_OEStarts_Setup:
    
   .. oe:method:: Setup

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

         .. oe:api::

            unsigned int Setup(const OEChem::OEMolBase& argFitMol,
                               OEChem::OETrans& argTrans)
            bool Setup(const unsigned int argFitSymmetry)

      .. oe:language:: python

         .. oe:api:: python

            Setup(argFitMol: Union[OEGraphMol,OEMol,OEQMol], argTrans: OETrans) -> int
            Setup(argFitSymmetry: int) -> bool

      The first `Setup` defines the interface for setting up the fit system for the 
      :ref:`OEStarts <OEShape_OEStarts>` derived instance with a molecule.  The second argument
      returns the transformation required to be applied on the fit molecule prior to
      starting any optimization. The return value of the method corresponds to the
      calculated symmetry type of the fit molecule. The second `Setup` can be used for 
      setting up the fit system when the symmetry type is already known. The reference system 
      information must be set by calling :oe:meth:`SetupRef<OEShape::OEStarts::SetupRef>` prior
      to calling `Setup`.


    .. _OEShape_OEStarts_SetupFrame:
    .. oe:method:: SetupFrame

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

         .. oe:api::

            bool SetupFrame(OEChem::OEMolBase& mol)
            bool SetupFrame(OESystem::OEScalarGrid& grid)
            bool SetupFrame(OEShapeQuery& query)

      .. oe:language:: python

         .. oe:api:: python

            SetupFrame(mol: Union[OEGraphMol,OEMol,OEQMol]) -> bool
            SetupFrame(grid: OEScalarGrid) -> bool
            SetupFrame(query: OEShapeQuery) -> bool

      These methods define the interface for setting up the reference system for the :ref:`OEStarts <OEShape_OEStarts>`
      derived instance.  These methods provide simpler interface to setting up the reference system, over the 
      :oe:meth:`SetupRef<OEShape::OEStarts::SetupRef>` methods.


    .. _OEShape_OEStarts_SetupRef:
    .. oe:method:: SetupRef

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

         .. oe:api::

            bool SetupRef(const unsigned int symmetry)
            bool SetupRef(const OEChem::OEMolBase& argRefMol,
                          const unsigned int symmetry)

      .. oe:language:: python

         .. oe:api:: python

            SetupRef(argSymmetry: int) -> bool
            SetupRef(mol: Union[OEGraphMol,OEMol,OEQMol], symmetry: int) -> bool

      These methods define the interface for setting up the reference system for the :ref:`OEStarts <OEShape_OEStarts>`
      derived instance.  The knowledge of the reference molecule is required for some variants of the :ref:`OEStarts <OEShape_OEStarts>`,
      whereas the others simply require the ``symmetry`` information for the reference system.  The corresponding ``symmetry``
      values are defined in the :oe:constns:`OEShape::OEMomentSymmetry` namespace and can be calculated using the
      :oe:meth:`OEShape::OEOrientByMomentsOfInertia` method.

      .. seealso::

         * :oe:meth:`SetupFrame<OEShape::OEStarts::SetupFrame>` method
