.. include:: substitutions
.. include:: ../apps-substitutions

.. _OptimizeDU:

******************
OptimizeDU
******************

.. program:: OptimizeDU

Overview
===================

:ref:`OptimizeDU` is an application to optimize a protein-ligand complex
inside a design unit. This is suitable for lead optimization, where a complete 
optimization which includes solvent forces and possibly partial relaxation of 
the protein residues in the direct proximity to the ligand desired.


Example Commands
===================

Protein-Ligand Optimization in a Design Unit
------------------------------------------------------

This optimizes the protein-ligand complex in the design unit using the FF14SB-Parsley force field.
Complete protein residues within 2 angstroms from the ligand are considered flexible
by default.

Input files

   * **1H1Q_AB_receptor.oedu**: OEDU file to optimize protein-ligand complex

Command line

      .. code-block:: bash

         prompt> optimizedu 1H1Q_AB_receptor.oedu 1H1Q_AB_opt.oedu

Output files

   * **1H1Q_AB_opt.oedu**: OEDU file containing optimized protein-ligand complex
   * **OptimizeDU_rpt.csv**: CSV file containing optimization report


Report File
==============

The CSV report file contains the following fields. 

   * **Molecule**: SMILES representation of the ligand molecule.
   * **Title**: Title of the ligand molecule.
   * **Inter Ene**: Final intermolecular energy between the protein target and the ligand (kcal/mol).
   * **Ligand Ene**: Final intramolecular energy of the ligand (kcal/mol).
   * **Protein Ene**: Final intramolecular energy of the flexible part of the protein target (kcal/mol).
   * **Ligand RMSD**: Root mean square deviation of the ligand between initial and final structures (Å).
   * **Protein RMSD**: Root mean square deviation of the protein target between initial and final structures (Å).
   * **ElapsedTime(s)**: Elapsed time for the optimization process (seconds).
   * **Status**: Status of the optimization. (Reported only when the optimization fails. Otherwise, this field is empty.)

Optimize a Ligand Pose in a Partially Flexible Protein
-------------------------------------------------------

This performs a constrained optimization of the ligand in the partially flexible protein
active site, using the FF14SB-Parsley force field. Complete protein residues within 2 angstroms
from the ligand are considered flexible by default.

Input files

   * **1H1Q_AB_receptor.oedu**: OEDU file to optimize protein-ligand complex

Command line

      .. code-block:: bash

         prompt> optimizedu -in 1H1Q_AB_receptor.oedu -out 1H1Q_AB_opt.oedu -optimize poseCartesian

Output files

   * **1H1Q_AB_opt.oedu**: OEDU file containing optimized protein-ligand complex

Command Line Help
===================

A description of the command line interface can be obtained by executing **OptimizeDU**
with the `--help` option.

.. code-block:: console

   > optimizedu --help

will generate the following output:

::

   Help functions:
     optimizedu --help simple      : Get a list of simple parameters
     optimizedu --help all         : Get a complete list of parameters
     optimizedu --help defaults    : List the defaults for all parameters
     optimizedu --help <parameter> : Get detailed help on a parameter
     optimizedu --help html        : Create an html help file for this program
     optimizedu --help versions    : List the toolkits and versions used in the application


Required Parameters
===================

.. option:: -in <filename>

   An OEDU file containing one or more design units, containing protein and ligand.

   [keyless parameter 1]


Optional Parameters
===================

.. include:: ../common/file_options.irst
.. include:: ../common/progress_options.irst

Input Options
---------------------------

.. option:: -proteinMask

   Design unit components mask defining the subset of design unit components to
   be used as ``protein`` during optimization. Multiple components can also be combined as
   a comma-separated string to create the input.

   Possible values include cofactors, counter_ions, excipients, lipids, metals, nucleic, other_cofactors,
   other_ligands, other_nucleics, other_proteins, packing_residues, polymers,
   post_translational, protein, solvent, and sugars.

   Predefined multi-component values:

   * **targetComplex** =
     protein,nucleic,cofactors,solvent,metals,counter_ions,lipids,other_proteins,
     other_nucleics,other_ligands,other_cofactors.
   * **targetComplexNoSolvent** = protein,nucleic,cofactors,metals,lipids,other_proteins,
     other_nucleics,other_ligands,other_cofactors.
   * **macroMolComponents** = protein,nucleic,other_proteins,other_nucleics.

     [Default=targetComplex]

.. option:: -receptorMask    [Default=True]

   Flag indicating if the ``Design unit components mask`` defining the subset of design 
   unit components to be used as ``protein`` during optimization should be picked up based
   on the mask defined in the receptor. If the input ``Design Unit`` does not contain
   a receptor, the optimizer automatically falls back to using the ``-proteinMask``.

.. option:: -ignoreAroBent    [Default=False]

   Flag indicating if optimization should not fail due to excess deviation from
   planarity for aromatic rings in optimized ligands.  By default, optimization would fail
   if aromatic rings deviate from planarity in an optimized ligand by more than five degrees
   on average, or if certain torsion exceeds a maximum of 10 degrees.

Output Options
---------------------------

.. option:: -out <filename>

   An OEDesignUnit file containing the optimized protein-ligand complexes.

   [keyless parameter 2]


Optimization Options
---------------------------

.. option:: -optimize    [Default=poseCartesian]

   Optimization type.
   Choices: [0] cartesian: performs a full cartesian optimization, or [1] poseCartesian: performs
   a constrained cartesian optimization, ensuring to hold the ligand pose.

.. option:: -ff    [Default=ff14sb_sage]

   The force field to use for optimization.  A predefined force field can be used by
   choosing one from the list of choices.  A different SMIRNOFF/OpenFF formatted
   small molecule force field can be used with ff14SB by passing in the
   small molecule force field OFFXML file as the argument.
   Choices: ``mmff94``, ``mmff94s``, ``mmff_amber``, ``mmffs_amber``, ``ff14sb_parsley``, and ``ff14sb_sage``.

.. option:: -ligandCharge    [Default=current]

   Charges to be assigned for the ligand. The default value of ``current`` refers to
   using the existing charges on the ligand.
   Choices: [0] current, [1] am1bcc, [2] am1bccelf10, and [3] MMFF.

.. option:: -gradTol    [Default=1.0e-6]

   Root mean squared (RMS) gradient tolerance for convergence and termination of optimization.

.. option:: -maxIter    [Default=1000]

   Maximum number of iterations for termination of optimization.  Optimization is terminated
   if either the gradient tolerance ``gradTol`` or the maximum iterations limit, whichever
   occurs first, is reached.

.. option:: -solventModel    [Default=vacuum]

   Solvent model to be used during optimization.
   Choices: [0] vacuum, [1] sheffield, or [2] pb.

Protein Flexibility Options
------------------------------

.. option:: -flexRange    [Default=2.0]

   Distance at which protein residues should be considered flexible. The distance is measured between
   all ligand atoms and the protein residues.  The protein is completely rigid when a value of
   ``0.0`` is used.

.. option:: -residueID    [Default=None]

   Regular expression (Regex) strings describing residues that should be considered flexible.
   When a value for ``residueID`` is provided, it overrides the ``-flexRange`` (i.e., the flexRange
   is ignored).
