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

.. oe:namespace:: OEMolPotential



.. meta::
   :keywords: OESubsetAdaptor, SubsetAdaptor


.. _OEMolPotential_OESubsetAdaptor:

.. oe:class:: OESubsetAdaptor

   .. attention::

      |TWOLANGUAGE|

   .. oe:api::


      class OESubsetAdaptor : public OEMolAdaptor2

   The :ref:`OESubsetAdaptor <OEMolPotential_OESubsetAdaptor>` class allows optimization of Cartesian coordinates
   for a subset of atoms in a molecule, while the remaining atoms are fixed. This is accomplished
   by subsetting the coordinates and gradients into the subsets which correspond to atoms being
   optimized. Additional facilities are provided for excluding invariant molecule function interactions, 
   and controlling which subset of atoms are held fixed during an optimization.

   .. _figure_OESubsetAdaptor_Hierarchy:

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

   The following methods are publicly inherited from :ref:`OEAdaptor <OEOpt_OEAdaptor>`:
    * :oe:meth:`AdaptVar<OEOpt::OEAdaptor::AdaptVar>` 
    * :oe:meth:`GetVar<OEOpt::OEAdaptor::GetVar>`

   The following methods are publicly inherited from :ref:`OEFunc0 <OEOpt_OEFunc0>`:
    * :oe:meth:`operator()<OEOpt::OEFunc0::operator()>`         
    * :oe:meth:`GetFComponents<OEOpt::OEFunc0::GetFComponents>` 
    * :oe:meth:`NumVar<OEOpt::OEFunc0::NumVar>`

   The following methods are publicly inherited from :ref:`OEFunc1 <OEOpt_OEFunc1>`:
    * :oe:meth:`operator()<OEOpt::OEFunc2::operator()>`

   The following methods are publicly inherited from :ref:`OEFunc2 <OEOpt_OEFunc2>`:
    * :oe:meth:`operator()<OEOpt::OEFunc1::operator()>`
   
   The following methods are publicly inherited from :ref:`OEMolFunc <OEMolPotential_OEMolFunc>`:
    * :oe:meth:`Clear<OEMolPotential::OEMolFunc::Clear>`   
    * :oe:meth:`ClearPredicates<OEMolPotential::OEMolFunc::ClearPredicates>`
    * :oe:meth:`GetInteractions<OEMolPotential::OEMolFunc::GetInteractions>`
    * :oe:meth:`Setup<OEMolPotential::OEMolFunc::Setup>`

   The following methods are publicly inherited from :ref:`OEMolAdaptor <OEMolPotential_OEMolAdaptor>`:
    * :oe:meth:`SetMolFunc<OEMolPotential::OEMolAdaptor::SetMolFunc>`

   The following methods are publicly inherited from :ref:`OEMolAdaptor2 <OEMolPotential_OEMolAdaptor2>`:
    * :oe:meth:`SetMolFunc<OEMolPotential::OEMolAdaptor2::SetMolFunc2>`

   The :ref:`OESubsetAdaptor <OEMolPotential_OESubsetAdaptor>` class defines the following public methods:
    * :oe:meth:`AdaptGrad<OEMolPotential::OESubsetAdaptor::AdaptGrad>`
    * :oe:meth:`AdaptHessian<OEMolPotential::OESubsetAdaptor::AdaptHessian>`
    * :oe:meth:`Set<OEMolPotential::OESubsetAdaptor::Set>`

   .. oe:method:: Constructors

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

         .. oe:api::

            OESubsetAdaptor(OEMolFunc1 &, bool own = false,
                            bool excludeInteract = true)
            OESubsetAdaptor(OEMolFunc2 &, bool own = false,
                            bool excludeInteract = true)

      .. oe:language:: python

         .. oe:api:: python

            OESubsetAdaptor(arg2: OEMolFunc1, own: bool = False,
                            excludeInteract: bool = True) -> OESubsetAdaptor
            OESubsetAdaptor(arg2: OEMolFunc2, own: bool = False,
                            excludeInteract: bool = True) -> OESubsetAdaptor

      Default and copy constructors.

      The molecule function used for function evaluation must be provided as the first argument to
      the constructor. The second argument specifies whether the 
      :ref:`OESubsetAdaptor <OEMolPotential_OESubsetAdaptor>` object takes ownership of the memory of the molecule
      function instance. By default that does not happen, so the :ref:`OESubsetAdaptor <OEMolPotential_OESubsetAdaptor>`
      destructor does not delete the molecule function instance. If ownership of the molecule function 
      is transferred to the :ref:`OESubsetAdaptor <OEMolPotential_OESubsetAdaptor>` instance, the molecule function's
      delete operator will be called in the :ref:`OESubsetAdaptor <OEMolPotential_OESubsetAdaptor>` destructor.
      The third argument controls the inclusion of invariant molecule function interactions. By default, 
      interactions which remain constant during the optimization are excluded from calculation.  
      Interactions composed entirely of atoms held fixed during the optimization will not change during 
      the optimization. Excluding invariant interactions does not affect the optimization, however, 
      the total energy calculated for a set of coordinates will be altered by the exclusion.  If the 
      third calling argument is ``false`` then all interactions will be computed during every function 
      evaluation.

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

      .. oe:api::

         OESubsetAdaptor & operator=(const OESubsetAdaptor &)

      Assignment operator.

   

   .. oe:method:: AdaptGrad

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

         .. oe:api::

            bool AdaptGrad(double* ga, const double* g) const

      .. oe:language:: python

         .. oe:api:: python

            AdaptGrad(ga: OEDoubleArray, g: OEDoubleArray) -> bool

      Takes a set of gradients from a molecule function evaluation as the second argument, and subsets 
      the gradients into the array passed as the first argument.

   .. oe:method:: AdaptHessian

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

         .. oe:api::

            bool AdaptHessian(double* ha, const double* h) const

      .. oe:language:: python

         .. oe:api:: python

            AdaptHessian(he: OEDoubleArray, h: OEDoubleArray) -> bool

      Takes a set of hessians from a molecule function evaluation as the second argument, and subsets 
      the hessians into the array passed as the first argument.

   .. oe:method:: Set

      .. oe:api::

         bool Set(const OESystem::OEUnaryPredicate<OEChem::OEAtomBase>&,
                  unsigned int functype = OEFuncType::SubsetAdapt);)

      This method assigns an atom predicate which is used to specify atoms which are to be held fixed in their starting positions during an optimization. The :oe:meth:`Set<OEMolPotential::OESubsetAdaptor::Set>` method must be called before the :oe:meth:`Setup<OEMolPotential::OEMolFunc::Setup>` for it to be effective.

