.. _chapter_oeff_examples:

.. _oeff_part_examples:

********************************************************************************
OEFF Examples
********************************************************************************

Simple Functions and Optimization
==================================

.. _section_Func2Opt_example:

Solving a simple equation
-------------------------

The following example illustrates how to define a simple objective function. By
deriving the objective function from :ref:`OEFunc2 <OEOpt_OEFunc2>`, we can find the
roots of the simple quadratic equation using :ref:`OENewtonOpt <OEOpt_OENewtonOpt>` optimizer.
A class derived from :ref:`OEFunc2 <OEOpt_OEFunc2>` must contain analytical gradients
and Hessians. This example expects a number as input for the initial guess to solve
the simple function.

.. oe:source:: Func2Opt.cpp
   :language: c++
   :caption:  Define a simple objective function
   :refnum:   1

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`Func2Opt.cpp <../../../../sublibs/tklibs/ff/examples/Func2Opt.cpp>`

.. oe:source:: Func2Opt.py
   :language: python
   :caption:  Define a simple objective function
   :refnum:   1

.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`Func2Opt.py <../../../../wrappers/python/examples/ff/Func2Opt.py>`

.. _section_Func1Chk_example:

Using checkpoints for optimization monitoring
---------------------------------------------
The following example illustrates how to define checkpoints and use then along with
optimizers to monitor progress during optimization. For simplicity, a simple quadratic
equation is defined as objective function and derived from :ref:`OEFunc1 <OEOpt_OEFunc1>`.
The quadratic equation is solved using the :ref:`OEBFGSOpt <OEOpt_OEBFGSOpt>` optimizer.
A class derived from :ref:`OEFunc1 <OEOpt_OEFunc1>` must contain analytical gradients. This
examples expects a number as input for the initial guess to solve the simple function.

.. oe:source:: Func1Chk.cpp
   :language: c++
   :caption:  Define and use checkpoints
   :refnum:   2

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`Func1Chk.cpp <../../../../sublibs/tklibs/ff/examples/Func1Chk.cpp>`


.. oe:source:: Func1Chk.py
   :language: python
   :caption:  Define and use checkpoints
   :refnum:   2

.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`Func1Chk.py <../../../../wrappers/python/examples/ff/Func1Chk.py>`


Molecule Functions
===================

.. _section_Molfunc1Opt_example:

User defined molecule function
------------------------------
The following example illustrates how to define an objective function within the context
of a molecule. Generally speaking, a molecule function (:ref:`OEMolFunc <OEMolPotential_OEMolFunc>`) defines
some sort of interaction involving a part or all of a molecule. For simplicity, a simple
energy function is defined that consists sum of square of distance of all the atoms in the molecule.
The molecule function is optimized using the :ref:`OEBFGSOpt <OEOpt_OEBFGSOpt>` optimizer.
A class derived from :ref:`OEMolFunc1 <OEMolPotential_OEMolFunc1>` must contain analytical gradients.

.. oe:source:: Molfunc1Opt.cpp
   :language: c++
   :caption:  Define an objective function within the context of a molecule
   :refnum:   3

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`Molfunc1Opt.cpp <../../../../sublibs/tklibs/ff/examples/Molfunc1Opt.cpp>`


.. oe:source:: Molfunc1Opt.py
   :language: python
   :caption:  Define an objective function within the context of a molecule
   :refnum:   3

.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`Molfunc1Opt.py <../../../../wrappers/python/examples/ff/Molfunc1Opt.py>`

Small Molecule Force fields
============================

.. _section_FFOptimize_example:

Single ligand in vacuum
------------------------
The following example illustrates how to calculate energy and optimize a single
ligand in vacuum. The molecule needs to be prepared (:oe:meth:`OEMolPotential::OEForceField::PrepMol`),
followed by a call to :oe:meth:`OEMolPotential::OEMolFunc::Setup` to create the interactions. Optimization is carried out using the :ref:`OEBFGSOpt <OEOpt_OEBFGSOpt>` optimizer.

.. oe:source:: FFOptimize.cpp
   :language: c++
   :caption:  Calculate energy and optimize a single ligand in vacuum
   :refnum:   4

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`FFOptimize.cpp <../../../../sublibs/tklibs/ff/examples/FFOptimize.cpp>`


.. oe:source:: FFOptimize.py
   :language: python
   :caption:  Calculate energy and optimize a single ligand in vacuum
   :refnum:   4

.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`FFOptimize.py <../../../../wrappers/python/examples/ff/FFOptimize.py>`

.. _section_FFEnergy_example:

Energy components of a single ligand in vacuum
-----------------------------------------------

The following example illustrates how to obtain various intermolecular energy
components of a single ligand in vacuum.

.. oe:source:: FFEnergy.cpp
   :language: c++
   :caption:  Obtain intermolecular energy components of a single ligand in vacuum
   :refnum:   5

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`FFEnergy.cpp <../../../../sublibs/tklibs/ff/examples/FFEnergy.cpp>`


.. oe:source:: FFEnergy.py
   :language: python
   :caption:  Obtain intermolecular energy components of a single ligand in vacuum
   :refnum:   5

.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`FFEnergy.py <../../../../wrappers/python/examples/ff/FFEnergy.py>`


.. _section_FFInteractions_example:

MMFF interactions of a single ligand
--------------------------------------

The following example illustrates how to obtain various interactions of a single ligand
in the context of a force field.

.. oe:source:: FFInteractions.cpp
   :language: c++
   :caption:  Obtain interactions of a single ligand in the context of a force field
   :refnum:   6

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`FFInteractions.cpp <../../../../sublibs/tklibs/ff/examples/FFInteractions.cpp>`


.. oe:source:: FFInteractions.py
   :language: python
   :caption:  Obtain interactions of a single ligand in the context of a force field
   :refnum:   6

.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`FFInteractions.py <../../../../wrappers/python/examples/ff/FFInteractions.py>`


Protein-Ligand Complexes
========================

.. _section_FFComplexOpt_example:

Protein-ligand optimization
----------------------------

The following example illustrates how to set up a ligand optimization within the
context of a protein contained in a design unit.

.. oe:source:: FFComplexOpt.cpp
   :language: c++
   :caption:  Set up a ligand optimization
   :refnum:   7

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`FFComplexOpt.cpp <../../../../sublibs/tklibs/ff/examples/FFComplexOpt.cpp>`


.. oe:source:: FFComplexOpt.py
   :language: python
   :caption:  Set up a ligand optimization
   :refnum:   7

.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`FFComplexOpt.py <../../../../wrappers/python/examples/ff/FFComplexOpt.py>`


Using adaptors
==============

.. _section_FFSubset_example:

Optimizing a single ligand with fixed atoms
--------------------------------------------

The following example illustrates how to fix a subset of atoms using the :ref:`OESubsetAdaptor <OEMolPotential_OESubsetAdaptor>` during a single ligand optimization in vacuum. The adaptor is initialized with
the force field interactions of the ligand, and passed as the objective function to be optimized.
Methods of the adaptor are used to convert between the Cartesian coordinates of the ligand and the
adaptor variables.

.. oe:source:: FFSubset.cpp
   :language: c++
   :caption:  Fix a subset of atoms
   :refnum:   8

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`FFSubset.cpp <../../../../sublibs/tklibs/ff/examples/FFSubset.cpp>`


.. oe:source:: FFSubset.py
   :language: python
   :caption:  Fix a subset of atoms
   :refnum:   8

.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`FFSubset.py <../../../../wrappers/python/examples/ff/FFSubset.py>`


.. _section_FFTorAdaptor_example:

Optimizing a single ligand torsions
---------------------------------------------

The following example illustrates how to optimize a set of torsion angles using the :ref:`OETorAdaptor <OEMolPotential_OETorAdaptor>`
for a single ligand in vacuum. The adaptor is initialized with
the force field interactions of the ligand, and passed as the objective function to be optimized.
Methods of the adaptor are used to convert between the Cartesian coordinates of the ligand and the
adaptor variables.

.. oe:source:: FFTorAdaptor.cpp
   :language: c++
   :caption:  Optimize a set of torsion angles
   :refnum:   9

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`FFTorAdaptor.cpp <../../../../sublibs/tklibs/ff/examples/FFTorAdaptor.cpp>`


.. oe:source:: FFTorAdaptor.py
   :language: python
   :caption:  Optimize a set of torsion angles
   :refnum:   9

.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`FFTorAdaptor.py <../../../../wrappers/python/examples/ff/FFTorAdaptor.py>`


.. _section_FFComplexQuat_example:

Optimizing rigid ligand in protein
-----------------------------------

The following example illustrates how to perform rigid optimization of a ligand in the context of a protein using the :ref:`OEQuatAdaptor <OEMolPotential_OEQuatAdaptor>`. The adaptor is initialized with
the protein-ligand interactions, and passed as the objective function to be optimized.
Methods of the adaptor are used to convert between the Cartesian coordinates of the ligand and the
adaptor variables.

.. oe:source:: FFComplexQuat.cpp
   :language: c++
   :caption:  Perform rigid optimization of a ligand
   :refnum:   10

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`FFComplexQuat.cpp <../../../../sublibs/tklibs/ff/examples/FFComplexQuat.cpp>`


.. oe:source:: FFComplexQuat.py
   :language: python
   :caption:  Perform rigid optimization of a ligand
   :refnum:   10

.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`FFComplexQuat.py <../../../../wrappers/python/examples/ff/FFComplexQuat.py>`


Custom Force Fields
==========================

.. _section_FFCustomSmirnoff_example:

Custom Smirnoff
------------------------
The following example illustrates how to load custom SMIRNOFF force field parameters from
an OFFXML file and use that to calculate energy and optimize a single ligand
in vacuum.

.. oe:source:: FFCustomSmirnoff.cpp
   :language: c++
   :caption:  Load custom SMIRNOFF force field parameters
   :refnum:   11

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`FFCustomSmirnoff.cpp <../../../../sublibs/tklibs/ff/examples/FFCustomSmirnoff.cpp>`


.. oe:source:: FFCustomSmirnoff.py
   :language: python
   :caption:  Load custom SMIRNOFF force field parameters
   :refnum:   11

.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`FFCustomSmirnoff.py <../../../../wrappers/python/examples/ff/FFCustomSmirnoff.py>`

