.. _chapter_oechem_interface_new:

********************************************************************************
Command Line Interface and Options
********************************************************************************
.. index :: command line options parsing

This chapter describes how **Options** classes that are derived from 
:ref:`OEOptions <OESystem_OEOptions>` can be configured with command line
inputs passed in through ``argv``.

The :ref:`OEConfigureOpts <OESystem_OEConfigureOpts>` function is a convenience function
that takes an :ref:`OEOptions <OESystem_OEOptions>` derivative options class and
the command line arguments ``argv``, parses the command line arguments, 
and configures the option parameters with command line inputs. A
:ref:`OEInterface <OESystem_OEInterface>` is generated internally from the
:ref:`OEOptions <OESystem_OEOptions>`, which performs the command lines parsing.

Note that this only applies to **Options** classes that are derived from the 
:ref:`OEOptions <OESystem_OEOptions>`.  There are a handful of **Options** classes
that still does not derive from :ref:`OEOptions <OESystem_OEOptions>`, and hence cannot
be configured with command line inputs directly. 
:ref:`Command Line Interface Definitions <chapter_oechem_interface>` is an
alternative way to work with command line interfaces for such cases.

In addition to the convenience function :ref:`OEConfigureOpts <OESystem_OEConfigureOpts>`,
two additional general purpose **Options** classes,  :ref:`OESimpleAppOptions <OEChem_OESimpleAppOptions>`,
and :ref:`OERefInputAppOptions <OEChem_OERefInputAppOptions>`, are provided that extends
any other options classes to include necessary input/output parameters that are
generally required to create an application. 

.. seealso::

   * :oe:func:`OESystem::OEConfigureOpts` function
   * :ref:`OEOptions <OESystem_OEOptions>` class
   * :ref:`OESimpleAppOptions <OEChem_OESimpleAppOptions>` class
   * :ref:`OERefInputAppOptions <OEChem_OERefInputAppOptions>` class


.. _section_oechem_interface_simple_app:

Application with Input, output, and Options
================================================================================

The following example shows how to use the :ref:`OESimpleAppOptions <OEChem_OESimpleAppOptions>`
class to extend an **Options** class with an additional input and output file.

The specific example is taken from **OEDocking**, and uses the
the :oe:func:`OEDocking::OEMakeReceptor` function to make a receptor in
a design unit. In this example, the :ref:`OEMakeReceptorOptions <OEDocking_OEMakeReceptorOptions>`
is extended with an input and output.

.. oe:source:: MakeReceptor.cpp
   :language: c++
   :caption:  Application with input, output, and options (Making Receptor)
   :refnum:   1

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`MakeReceptor.cpp <../../../../sublibs/tklibs/docking/examples/MakeReceptor.cpp>`


.. oe:source:: MakeReceptor.py
   :language: python
   :caption:  Application with input, output, and options (Making Receptor)
   :refnum:   1

.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`MakeReceptor.py <../../../../wrappers/python/examples/docking/MakeReceptor.py>`

.. oe:source:: MakeReceptor.java
   :language: java
   :caption:  Application with input, output, and options (Making Receptor)
   :refnum:   1

.. oe:language:: java

   .. only:: oehtml

      .. admonition:: Download code

         :download:`MakeReceptor.java <../../../../wrappers/java/examples/openeye/examples/oedocking/MakeReceptor.java>`

.. oe:source:: MakeReceptor.cs
   :language: csharp
   :caption:  Application with input, output, and options (Making Receptor)
   :refnum:   1

.. oe:language:: csharp

   .. only:: oehtml

      .. admonition:: Download code

         :download:`MakeReceptor.cs <../../../../wrappers/csharp/Csharp-Examples/OEDocking/MakeReceptor.cs>`


.. _section_oechem_interface_ref_app:

Application with Reference system, Input, output, and Options
================================================================================

Besides an input and output, some applications require an additional 
reference system input. The :ref:`OERefInputAppOptions <OEChem_OERefInputAppOptions>` class
can be used to extend an options class with three additional parameters,
an input, output, and a reference system.

The following code example is taken from **OEDocking**, and uses
the :ref:`OEDock <OEDocking_OEDock>` object to perform docking. In this example,
the :ref:`OEDockOptions <OEDocking_OEDockOptions>` is extended with an input, output,
and a **receptor** (i.e., the reference system).

.. oe:source:: DockMolecules.cpp
   :language: c++
   :caption:  Application with input, reference, output, and options (Docking Molecules)
   :refnum:   2

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`DockMolecules.cpp <../../../../sublibs/tklibs/docking/examples/DockMolecules.cpp>`

.. oe:source:: DockMolecules.py
   :language: python
   :caption:  Application with input, reference, output, and options (Docking Molecules)
   :refnum:   2

.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`DockMolecules.py <../../../../wrappers/python/examples/docking/DockMolecules.py>`

.. oe:source:: DockMolecules.java
   :language: java
   :caption:  Application with input, reference, output, and options (Docking Molecules)
   :refnum:   2

.. oe:language:: java

   .. only:: oehtml

      .. admonition:: Download code

         :download:`DockMolecules.java <../../../../wrappers/java/examples/openeye/examples/oedocking/DockMolecules.java>`

.. oe:source:: DockMolecules.cs
   :language: csharp
   :caption:  Application with input, reference, output, and options (Docking Molecules)
   :refnum:   2

.. oe:language:: csharp

   .. only:: oehtml

      .. admonition:: Download code

         :download:`DockMolecules.cs <../../../../wrappers/csharp/Csharp-Examples/OEDocking/DockMolecules.cs>`

.. _section_oechem_interface_no_options:

Application with Input and output only
================================================================================

Some applications do not have any additional options or parameters, and only require
an input and output. The :ref:`OESimpleAppOptions <OEChem_OESimpleAppOptions>` class
has an overload that does not require an :ref:`OEOptions <OESystem_OEOptions>` input argument.

The following code example is taken from **OEQuacpac**, and uses
the :oe:func:`OEProton::OEAssignCharges` method to assign charges in
an :ref:`OEDesignUnit <OEBio_OEDesignUnit>`. This example only configures an
input and output, and does not have any additional parameters to configure.

.. oe:source:: applycharges_oedu.cpp
   :language: c++
   :caption:  Application with input and output only (DesignUnit Charges)
   :refnum:   3

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`applycharges_oedu.cpp <../../../../sublibs/tklibs/quacpac/examples/applycharges_oedu.cpp>`

.. oe:source:: applycharges_oedu.py
   :language: python
   :caption:  Application with input and output only (DesignUnit Charges)
   :refnum:   3

.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`applycharges_oedu.py <../../../../wrappers/python/examples/quacpac/applycharges_oedu.py>`

.. _section_oechem_interface_add_param:

Adding custom parameters
================================================================================

Custom parameters can also be added to an application API when a built-in **Options**
class does not contain all required parameters for the application.

The following code example is taken from **OEDocking**, and uses
the :ref:`OEPosit <OEDocking_OEPosit>` object to generate pose structures. In this example,
the :ref:`OEPositOptions <OEDocking_OEPositOptions>` is extended with an input, output,
and **receptor** (i.e., the reference system). However, the number of 
poses to generate is not a built-in parameter into the :ref:`OEPositOptions <OEDocking_OEPositOptions>`.
This example shows how to add an additional parameter, for the number of poses,
to be configured through the command line.

.. oe:source:: GenerateMultiplePose.cpp
   :language: c++
   :caption:  Adding custom parameters (POSIT with Multiple Receptors)
   :refnum:   4

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

         :download:`GenerateMultiplePose.cpp <../../../../sublibs/tklibs/docking/examples/GenerateMultiplePose.cpp>`


.. oe:source:: GenerateMultiplePose.py
   :language: python
   :caption:  Adding custom parameters (POSIT with Multiple Receptors)
   :refnum:   4

.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

         :download:`GenerateMultiplePose.py <../../../../wrappers/python/examples/docking/GenerateMultiplePose.py>`

.. oe:source:: GenerateMultiplePose.java
   :language: java
   :caption:  Adding custom parameters (POSIT with Multiple Receptors)
   :refnum:   4

.. oe:language:: java

   .. only:: oehtml

      .. admonition:: Download code

         :download:`GenerateMultiplePose.java <../../../../wrappers/java/examples/openeye/examples/oedocking/GenerateMultiplePose.java>`

.. oe:source:: GenerateMultiplePose.cs
   :language: csharp
   :caption:  Adding custom parameters (POSIT with Multiple Receptors)
   :refnum:   4

.. oe:language:: csharp

   .. only:: oehtml

      .. admonition:: Download code

         :download:`GenerateMultiplePose.cs <../../../../wrappers/csharp/Csharp-Examples/OEDocking/GenerateMultiplePose.cs>`

.. _section_oechem_interface_custom_options:

Defining new options class
================================================================================

Options classes, derived from :ref:`OEOptions <OESystem_OEOptions>`, can also be defined
at the script level, and wrapped with the :ref:`OESimpleAppOptions <OEChem_OESimpleAppOptions>`
or :ref:`OERefInputAppOptions <OEChem_OERefInputAppOptions>`, to build applications.

The following code example is taken from **OEFF**, and optimizes molecule
conformations using a force field. In this example, a new **Options** class
is defined to accept command line input for the force field.

.. oe:source:: FFOptimize.cpp
   :language: c++
   :caption:  Defining Options class (Optimize molecule)
   :refnum:   5

.. oe:language:: c++

   .. only:: oehtml

      .. admonition:: Download code

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


.. oe:source:: FFOptimize.py
   :language: python
   :caption:  Defining Options class (Optimize molecule)
   :refnum:   5

.. oe:language:: python

   .. only:: oehtml

      .. admonition:: Download code

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