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

.. program:: omega

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

This section has a series of example **OMEGA** command line executions.  Each
example is followed by a brief description of its behavior.
Sample data files can be found in the data directory.

Basic Commands
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: bash

   prompt> oeomega classic drugs.smi drugs.oeb.gz
   prompt> oeomega classic -in drugs.smi -out drugs.oeb.gz

These two commands will yield identical results.  These execute **OMEGA** ``classic`` with the
default parameters.  The file `drugs.smi` is opened in SMILES format for
input, and the output is written to the file `drugs.oeb.gz` in gzipped
OEBinary format.

.. code-block:: bash

   prompt> oeomega macrocycle -in drugs.smi
   prompt> oeomega macrocycle -in pdb_10_examples.oeb -prefix pdbexamples -mpi_np 8

The first command executes **OMEGA** ``macrocycle`` mode with the default parameters. By default, the conformers
are written to the file `oeomega_macrocycle_conformers.oeb.gz`. The macrocycle mode execution will
take a longer time than the classic mode and usually result in fewer conformers for the same input
molecule. The second command executes ``macrocycle`` mode using an input file with macrocyclic
molecules. The conformers are written to the file `pdbexamples_conformers.oeb.gz` and the
execution time will be even longer because of the macrocyclic molecules. It is preferable to run
the ``macrocycle`` mode under Open MPI using the maximum number of CPU cores available.


Using Parameters and Param Files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: bash

   prompt> oeomega classic -in drugs.smi -out drugs.oeb.gz -maxconfs 1

The parameter `-maxconfs` can be used to specify the maximum number of conformers for each output molecule.
This command will generate a single low energy conformer for every molecule in drugs.smi.

.. code-block:: bash

   prompt> oeomega classic -in drugs.smi -out drugs.oeb.gz -param myparameters

This command is the same as the basic commands above except for the `-param` flag.
It executes **OMEGA** ``classic`` with the parameters found in the `myparameters`
file.  The file `drugs.smi` is opened in SMILES format for input, and
the output is written to the file `drugs.oeb.gz` in gzipped OEBinary
format.

.. code-block:: bash

   prompt> oeomega classic -param myparameters drugs.smi drugs.oeb.gz
   prompt> oeomega classic drugs.smi drugs.oeb.gz -param myparameters

The first of these two commands will yield exactly the same results as the
example above.  `drugs.smi` will be mapped to the `-in` flag and
`drugs.oeb.gz` will be mapped to the `-out` flag to begin the second to
last and last command line arguments, respectively.  Unfortunately, the second
of these two commands will fail to parse because the implicit input and output
arguments are not the final two arguments in the list.

.. code-block:: bash

   prompt> oeomega classic -in drugs.smi -out drugs_maxconfs600.oeb.gz
                  -param myparameters -maxconfs 600

Again, this is a very similar command.  It executes **OMEGA** `classic` using the
parameters in the `myparameters` file, except the `-maxconfs`
parameter is overridden with the 600 from the command line.  The
command line `-maxconfs` parameter would take precedence over the
value in the parameter file independent of the order of flags on the
command line.

Advanced Commands
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: bash

   prompt> oeomega classic -in drugs.mol2 -out drugs.oeb.gz -fromCT true

The `-fromCT` true flag will cause **OMEGA** `classic` to ignore the input
conformations in the `drugs.mol2` file.  An initial conformation will
be generated by a distance-bounds algorithm from the connection table of
the molecules in the input file.  Be aware that the default value of
`-fromCT` is true, however it is listed explicitly here for emphasis.

.. code-block:: bash

   prompt> oeomega classic -in drugs.smi -out drugs.oeb.gz -log null

The `-log` flag normally allows specification of the log file's name.
However, `nul` and `null` are reserved names which indicate that
no log file will be written (this includes failure modes).


CSV Report File for ``macrocycle`` Mode
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

For each molecule in the input file, a row of data with the following columns is recorded:

* `Molecule`
   Title of the molecule.

* `SMILES`
   SMILES string corresponding to the molecule.

* `Conformers`
   Number of conformers in the output file. Its maximum number is always smaller than
   or equal to the value of the :option:`-maxconfs`.

* `LargestRing`
   Size of the largest ring system in the molecule.

   .. note:: **All fused rings are considered to be a part of the macrocycle ring. Within this
      convention, decalin is assumed to be a 10-membered ring system.**

* `Iterations`
   This number is equal to the parameter :option:`macrocycle -max_iterations`.

* `Elapsed Time`
   Time used to generate conformers (in seconds).

* `Status`
   Failure reason in case conformers are not generated.

   .. note:: **Message: "No conformer left after post processing" is usually caused by a chirality mismatch
      between the chirality of the input molecule and the chirality of each generated conformation.
      It means that the force field refinement was not able to reproduce input chirality. It is recommended
      therefore to check the correctness of chirality input molecule. This situation is common when the input
      is taken from the 3D PDB file. A good example is the PDB structure of the rifampicin antibiotic extracted
      from the 1SKX entry. This molecule has nine atomic chiral centers and two chiral bonds. Its chirality
      assignment based on the 3D PDB structure differs from the actual chirality of this antibiotic.**
