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

.. _OptLigandInDU:

******************
OptLigandInDU
******************

.. program:: OptLigandInDU

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

:ref:`OptLigandInDU` is an application to optimize a ligand or a series of
ligands in a rigid protein active site. This is suitable for screening a
large amount of docked ligands into a protein receptor.


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

Ligand Optimization in a Protein Active Site
------------------------------------------------------

This optimizes the ligands in a protein active site using the FF14SB-Parsley force field.

Input files

   * **1H1Q_AB_receptor.oedu**: OEDU file containing the protein active site
   * **1H1Q_AB_fred_docked.oeb**: OEB file containing the ligand to optimize

Command line

      .. code-block:: bash

         prompt> optligandindu 1H1Q_AB_receptor.oedu 1H1Q_AB_fred_docked.oeb 1H1Q_AB_fred_docked_opt.oeb

Output files

   * **1H1Q_AB_fred_docked_opt.oeb**: OEB file containing optimized ligands
   * **OptLigandInDU_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.
   * **ConfID**: Ligand conformer index.
   * **Inter Ene**: Final intermolecular energy between the protein target and the ligand (kcal/mol).
   * **Ligand Ene**: Final intramolecular energy of the ligand (kcal/mol).
   * **Ligand RMSD**: Root mean square deviation of the ligand 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 Rigid Protein
-------------------------------------------------------

This performs a constrained optimization of the ligand in the rigid protein
active site, using the FF14SB-Parsley force field.

Input files

   * **1H1Q_AB_receptor.oedu**: OEDU file containing the protein active site
   * **1H1Q_AB_fred_docked.oeb**: OEB file containing the ligand to optimize

Command line

      .. code-block:: bash

         prompt> optligandindu -du 2IKO.oedu -in 1H1Q_AB_fred_docked.oeb -out 1H1Q_AB_fred_docked_opt.oeb -optimize poseCartesian

Output files

   * **1H1Q_AB_fred_docked_opt.oeb**: OEB file containing optimized ligand

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

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

.. code-block:: console

   > optligandindu --help

will generate the following output:

::

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


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

.. option:: -du <filename>

   An OEDU file with a design unit, containing the protein active site.  If the file contains multiple
   design units, only the first one is used.

   [keyless parameter 1]

.. option:: -in <filename>

   Molecular input file name containing 3D coordinates in any format
   supported by **OEChem**.

   [keyless parameter 1]

Acceptable molecule file formats are listed below.

.. list-table:: *SZYBKI File Format Support*
   :widths: 20 25
   :header-rows: 1

   * - File extension
     - Description
   * - mol
     - MDL Mol File
   * - mmd, mmod
     - Macromodel
   * - mol2
     - Tripos Sybyl mol2 file
   * - oeb
     - New Style OEBinary
   * - sd, sdf
     - MDL SD File
   * - xyz
     - XMol XYZ format


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 multicomponent 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 the ``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>

   Output file name, in any format supported by OEChem, for an
   optimized ligand.

   [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, or [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.

