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

.. oe:namespace:: OEMolPotential



.. meta::
   :keywords: OEMolFunc, MolFunc


.. _OEMolPotential_OEMolFunc:

.. oe:class:: OEMolFunc

   .. attention::

      |TWOLANGUAGE|

   .. oe:api::


      class OEMolFunc

   The :ref:`OEMolFunc <OEMolPotential_OEMolFunc>` is an abstract base class. This class defines the
   interface for functions that require a molecule to compute the function value,
   and is often associated with a force field. When associated with a force field,
   this represents a forcefield component or a collection of components with each
   component being a collection of interactions (:ref:`OEInteraction <OEMolPotential_OEInteraction>`).
   Thus, classes derived from :ref:`OEMolFunc <OEMolPotential_OEMolFunc>` can represent
   a part of or a complete force field. The force field components need to be done
   concomitant with one or more :ref:`OEFFParams <OEMolPotential_OEFFParams>` derived classes.

   .. _figure_OEMolFunc_Hierarchy:

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

   The :ref:`OEMolFunc <OEMolPotential_OEMolFunc>` class defines the following public methods:
    * :oe:meth:`Clear<OEMolPotential::OEMolFunc::Clear>`
    * :oe:meth:`ClearPredicates<OEMolPotential::OEMolFunc::ClearPredicates>`
    * :oe:meth:`GetInteractions<OEMolPotential::OEMolFunc::GetInteractions>`
    * :oe:meth:`Set<OEMolPotential::OEMolFunc::Set>`
    * :oe:meth:`Setup<OEMolPotential::OEMolFunc::Setup>`
    * :oe:meth:`SetupConf<OEMolPotential::OEMolFunc::SetupConf>`

   The following classes derive from this class:
    * :ref:`OEMolFunc0 <OEMolPotential_OEMolFunc0>`
    * :ref:`OEMolFunc1 <OEMolPotential_OEMolFunc1>`
    * :ref:`OEMolFunc2 <OEMolPotential_OEMolFunc2>`
    * :ref:`OEForceField <OEMolPotential_OEForceField>`
    * :ref:`OEGenericFF <OEMolPotential_OEGenericFF>`
    * :ref:`OEGenericFF2 <OEMolPotential_OEGenericFF2>`
    * :ref:`OEInterAdaptor <OEMolPotential_OEInterAdaptor>`
    * :ref:`OEMolAdaptor <OEMolPotential_OEMolAdaptor>`
    * :ref:`OEQuatAdaptor <OEMolPotential_OEQuatAdaptor>`
    * :ref:`OESubsetAdaptor <OEMolPotential_OESubsetAdaptor>`
    * :ref:`OETorAdaptor <OEMolPotential_OETorAdaptor>`
    * :ref:`OETorQuatAdaptor <OEMolPotential_OETorQuatAdaptor>`
    * :ref:`OENumericMolFunc2 <OEMolPotential_OENumericMolFunc2>`
    * :ref:`OEScaledMolFunc <OEMolPotential_OEScaledMolFunc>`
    * :ref:`OEFFPotential <OEMolPotential_OEFFPotential>`
    * :ref:`OEStretchPotential <OEMolPotential_OEStretchPotential>`
    * :ref:`OEBendPotential <OEMolPotential_OEBendPotential>`
    * :ref:`OETorsionPotential <OEMolPotential_OETorsionPotential>`
    * :ref:`OEOutOfPlanePotential <OEMolPotential_OEOutOfPlanePotential>`
    * :ref:`OENonBondPotBase <OEMolPotential_OENonBondPotBase>`
    * :ref:`OEVdwPotential <OEMolPotential_OEVdwPotential>`
    * :ref:`OECoulombPotential <OEMolPotential_OECoulombPotential>`
    * :ref:`OEInterMolFunc1 <OEMolPotential_OEInterMolFunc1>`
    * :ref:`OEInterMolFunc2 <OEMolPotential_OEInterMolFunc2>`
    * :ref:`OEInterNonBondPotBase <OEMolPotential_OEInterNonBondPotBase>`
    * :ref:`OEInterNonBondPotential <OEMolPotential_OEInterNonBondPotential>`
    * :ref:`OEInterVdwPotential <OEMolPotential_OEInterVdwPotential>`
    * :ref:`OEInterCoulombPotential <OEMolPotential_OEInterCoulombPotential>`
    * :ref:`OEHarmonicPotential <OEConstr_OEHarmonicPotential>`
    * :ref:`OEMMFF <OEMolMMFF_OEMMFF>`
    * :ref:`OEMMFFStretchBend <OEMolMMFF_OEMMFFStretchBend>`
    * :ref:`OEMMFFIEFF <OEFF_OEMMFFIEFF>`
    * :ref:`OESheffield <OESheff_OESheffield>`
    * :ref:`OEOverlapFuncBase <OEShape_OEOverlapFuncBase>`
    * :ref:`OEOverlapFunc <OEShape_OEOverlapFunc>`
    * :ref:`OEShapeFunc <OEShape_OEShapeFunc>`
    * :ref:`OEExactShapeFunc <OEShape_OEExactShapeFunc>`
    * :ref:`OEAnalyticShapeFunc <OEShape_OEAnalyticShapeFunc>`
    * :ref:`OEHermiteShapeFunc <OEShape_OEHermiteShapeFunc>`
    * :ref:`OEGridShapeFunc <OEShape_OEGridShapeFunc>`
    * :ref:`OEColorFunc <OEShape_OEColorFunc>`
    * :ref:`OEExactColorFunc <OEShape_OEExactColorFunc>`
    * :ref:`OEAnalyticColorFunc <OEShape_OEAnalyticColorFunc>`
    * :ref:`OEGridColorFunc <OEShape_OEGridColorFunc>`


   .. oe:method:: Clear

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

         .. oe:api::

            void Clear()

      .. oe:language:: python

         .. oe:api:: python

            Clear() -> None

      Deletes all interactions contained in the :ref:`OEMolFunc <OEMolPotential_OEMolFunc>` derived instance.
      The interactions are created during setup (:oe:meth:`OEMolPotential::OEMolFunc::Setup`).

   .. oe:method:: ClearPredicates

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

         .. oe:api::

            void ClearPredicates()

      .. oe:language:: python

         .. oe:api:: python

            ClearPredicates() -> None

      Deletes all stored predicates set, previously created by using one of the overloaded
      :oe:meth:`OEMolPotential::OEMolFunc::Set` methods. Predicates control function behavior
      during setup (:oe:meth:`OEMolPotential::OEMolFunc::Setup`).

   .. oe:method:: GetInteractions

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

         .. oe:api::

            OESystem::OEIterBase<OEInteraction>* GetInteractions(const OEChem::OEMolBase &,
                                                                 const double *,
                                                                 unsigned functype = 0) const

      .. oe:language:: python

         .. oe:api:: python

            GetInteractions(arg0: Union[OEGraphMol,OEMol,OEQMol], arg1: float,
                            functype: int = 0) -> Iterable[OEInteraction]

      This method defines the interface for retrieving interaction level information computed
      by the :ref:`OEMolFunc <OEMolPotential_OEMolFunc>` instance, given a molecule (first argument) and a
      set of coordinates (second argument). The method returns an iterator over the :ref:`OEInteraction <OEMolPotential_OEInteraction>`
      objects. See the section on :ref:`OEInteraction <OEMolPotential_OEInteraction>` for the details regarding
      interaction interrogation and reporting.

      If :ref:`OEMolFunc <OEMolPotential_OEMolFunc>` is a composition of multiple components,
      the last argument may be used to request the interactions of only a single component by passing a value from the :oe:const:`OEMolPotential::OEFuncType` namespace.

      Due to the unique construct of the return value from this method, it
      is not possible to implement this in a user derived class. Default implementation of this method
      return an iterator over an empty vector.

   .. oe:method:: Set

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

         .. oe:api::

            bool Set(const OESystem::OEUnaryPredicate<OEChem::OEBondBase>& pred,
                     unsigned int functype)
            bool Set(const OESystem::OEUnaryPredicate<OEChem::OEAtomBase>& pred,
                     unsigned int functype)
            bool Set(const OESystem::OEBinaryPredicate<OEChem::OEAtomBase, OEChem::OEAtomBase>& pred,
                     unsigned int functype)
            bool Set(const OESystem::OEBinaryPredicate<OEChem::OEBondBase, OEChem::OEBondBase>& pred,
                     unsigned int functype)

      .. oe:language:: python

         .. oe:api:: python

            Set(arg0: OEUnaryBondPred, arg1: int) -> bool
            Set(arg0: OEUnaryAtomPred, arg1: int) -> bool
            Set(arg0: OEBinaryAtomPred, arg1: int) -> bool
            Set(arg0: OEBinaryBondPred, arg1: int) -> bool

      These methods assigns interaction-control predicates to the :ref:`OEMolFunc <OEMolPotential_OEMolFunc>`
      derived instance. The first argument is the predicate type to be passed to the interaction component.
      The second argument is a value or a set of binary OR'ed values taken from the :oe:const:`OEMolPotential::OEFuncType`
      namespace which specifies the intended target for the predicate assignment.

      Most derived classes can only use a handful of the four different kinds of predicates
      allowed in these overloads, thus only the specific overloads are overwritten by various derived class.
      The default implementation for all the overloads has trivial implementation and returns a ``false``.

   .. oe:method:: Setup

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

         .. oe:api::

            bool Setup(const OEChem::OEMolBase&)

      .. oe:language:: python

         .. oe:api:: python

            Setup(mol: Union[OEGraphMol,OEMol,OEQMol]) -> bool

      This method defines the interface for initializing a :ref:`OEMolFunc <OEMolPotential_OEMolFunc>` derived instance with a molecule. All classes derived from :ref:`OEMolFunc <OEMolPotential_OEMolFunc>` implements this method.
      Typically the implementation of this method requires perception of the passed molecule for efficient energy evaluation.


      .. seealso::

         * :ref:`section_FFEnergy_example` example

   .. _OEMolPotential_OEMolFunc_SetupConf:

   .. oe:method:: SetupConf

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

         .. oe:api::

            bool SetupConf(const double *)

      .. oe:language:: python

         .. oe:api:: python

            SetupConf(arg0: OEDoubleArray) -> bool

      This method defines the interface for initializing a :ref:`OEMolFunc <OEMolPotential_OEMolFunc>` derived 
      instance with coordinates of a new conformer, after it has already been initialized with the molecule by 
      calling :oe:meth:`Setup<OEMolPotential::OEMolFunc::Setup>`. Not all classes derived from 
      :ref:`OEMolFunc <OEMolPotential_OEMolFunc>` implements this method, but calling this should never
      cause any additional performance issue or failures.

