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

.. _omega_opt_params:


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

.. include:: ../../common/new_mpi_execute_options.irst

.. program:: omega

File Options
^^^^^^^^^^^^^^^^^^^^^^

.. option:: -out

   This file writes conformers generated by **OMEGA**. Gzipped OEBinary is the
   recommended output format.

   Supported file formats: 
   mol2, oeb, oez, sdf, and the corresponding compressed formats (i.e., xx.gz).

.. option:: -failed

   This file writes molecules for which **OMEGA** fails to generate conformers. A failed file is only
   generated when specifically requested by users.

   Supported file formats: 
   cxsmiles, ism, mol2, oeb, oez, sdf, smi, and the corresponding compressed formats (i.e., xx.gz).

.. option:: -commentEnergy

   This flag causes the conformer energy in kcal/mol to
   be written in the comment field for each conformer.  This is
   particularly useful when writing SD or MOL2 files that will be
   passed to software that anticipates strain energies written in the
   comment field.  [Default=false]

.. option:: -includeInput

   When true, this boolean flag will include the
   input conformer in the output file. This requires that the input file
   format is in a 3D format (e.g., SDF, MOL2, OEB). [Default=false]

.. option:: -log

   The argument for this flag specifies the name of
   the log file.  The level of detail for log file information can be
   altered using the :option:`-verbose` flag.  Output can
   be directed to the terminal as well with the :option:`-progress` log option.  Generation of an
   output log may be disabled by providing ``nul`` as a argument in Windows and ``/dev/null`` as an
   argument on Linux and macOS.  [Default=``prefix`` _log.txt]

.. option:: -prefix

   The argument for this flag defines the prefix to be used
   for various information and data files generated by **OMEGA**.  Most
   important among these is the *oeomega_<mode>_parm.txt* file which includes a
   copy of all the parameters used in the **OMEGA** run.  The prefix is
   also used to generate a default log file name if it is not explicitly
   specified with the *-log* flag. [Default=oeomega_<mode>].

.. option:: -progress

   This flag shows the progress on screen.  Options are *none*, *dots*, *log*, and *percent*.
   The *dots* options will display dots on-screen to show molecules
   completed.  The *log* option will duplicate the log file on-screen.
   The *percent* option will track progress through the input file.  [Default=none]

.. option:: -rotorOffsetCompress

   This flag controls the behavior of
   writing the rotor offset compressed flavor of the OEBinary format.
   Rotor offset compressed files contain the same information as
   standard Cartesian OEBinary files but require a small fraction of
   the storage space.  Optimal compression of **OMEGA** output can be
   obtained by writing gzip compressed OEBinary files with the
   `-rotorOffsetCompress` flag turned on. [Default=true]

.. note:: **Rotor offset compression cannot be performed and is automatically
   disabled when any of the methods to fix part of the molecule geometry,
   such as -fixmol, -fixfile, -fixsmarts, or -fixmcs, are used during
   conformer generation.**

.. option:: -sdEnergy

   This flag controls the
   behavior of writing strain energies as SD tags.  This flag may be
   used with either OEBinary or MDL SD files.  [Default=false]

.. option:: -verbose

   This is a boolean flag that controls the level of
   detail written to the log file.  By default, **OMEGA** will only write
   minimal information to the log file.  Molecule titles and warning
   messages constitute the bulk of logging at the default level.
   Verbose logging will cause more information to be written to the log
   file in order to follow behavior during program execution.  In order to
   have the log shown on the screen, use `-progress log`.  [Default=false]

.. option:: -warts

   This boolean flag is used to generate unique titles for
   conformers that reflect their position in an ensemble of
   conformations produced by **OMEGA**.  The title given to each conformer
   will begin with the molecule title taken from the input file and
   appended with an underscore and the integer corresponding to the
   rank order number of the conformer in the final ensemble.  [Default=false]

3D Construction Parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. option:: -addfraglib

   [alias: -setfraglib]

   The argument that follows this flag is
   one fragment file, normally generated by MakeFraglib.
   These fragments will supplement the built-in fragment library.

   For use in a Windows platform, an enhanced fragment library, ``omega_fragment_lib_2023.oeb.gz``,
   that improves the performance of conformer
   generation is available upon request from the `database downloads page
   <https://www.eyesopen.com/database-downloads>`_. The enhanced library is the
   default on both Linux and OSX.

.. option:: -buildff

   This flag sets the force field used for
   constructing fragments that are assembled to build an initial model
   of the input structure.  Consult the description of force fields
   (see :ref:`section_ForceFields`) for an explanation of appropriate
   arguments for this flag.  [Default=mmff94smod_NoEstat]

.. option:: -canonOrder

   This flag can be used to disable the
   automatic reordering of input molecules to a canonical atom and bond
   order.  In order to obtain consistent results from different file
   formats and different connection table orders, **OMEGA** reorders the
   input connection table.  This behavior can be turned off using the
   `-canonOrder` flag; however, the resultant ensembles will
   likely be inconsistent in their composition. [Default=true]

.. option:: -deleteFixHydrogens

   When a fixfile fragment is
   specified, all possible mappings (matches) of the fragment and the
   input molecule are considered for positioning the input molecule.
   This process begins with a substructure search of the fragment in
   the input molecule.  If hydrogens are included on the fixfile
   fragment, the number of possible matches will grow exponentially
   with the number of equivalences.  Each geminal hydrogen pair on the
   fixfile produces a nonproductive match multiplied by all other
   nonproductive matches.  This flag can be used to prevent the
   explosion of nonproductive matches by deleting hydrogens from the
   fixfile fragment prior to the substructure search.  [Default=true]

.. option:: -fixfile

   The argument that follows this flag is a molecule file
   used to specify the coordinates for a substructure of the input
   molecules.  An initial structure is generated for every input
   molecule, then a substructure search is performed using the
   molecule or fragment provided in the fixfile as a query molecule.
   Every instance of the fixed substructure found in the input molecule
   up to a predetermined limit (see `maxmatch` and `umatch`)
   is used to replace the coordinates of the atoms that match the
   substructure.  The input molecule coordinates are aligned relative
   to the substructure prior to fragment replacement, then the
   coordinates are taken from the fixed fragment and assigned to the
   corresponding atoms of the input molecule.  A separate alignment,
   replacement, and conformer search is carried out for every
   matching substructure in the input molecule.  Molecules that do not
   match the fixfile will fail and will be reported as such in the log file.

.. option:: -fixmcs

   This flag fixes a portion of a molecule based on the maximum common subgraph against the
   `-fixfile` molecule.   Molecules that do not have any common subgraph will fail
   and be reported as such in the log file.
   [default = false]

.. option:: -fixrms

   Fixfile fragments taken from crystallographic
   sources may differ in their geometry relative to optimal MMFF94
   geometries.  **OMEGA** attempts to superimpose built structures onto
   fixfile fragments, and if the geometry differs too greatly, **OMEGA**
   considers the superposition a poor match and will fail to build a
   structure using the fixfile.  This flag can be used to loosen the
   default RMS superposition criteria to allow suboptimal
   superpositions to succeed in spite of the poor geometric
   complementarity.  [Default=0.15]

.. option:: -fixsmarts

   This is another way to specify a fixed portion of a molecule.  The SMARTS pattern is used to fix a portion of the `-fixfile` primarily, or to fix a portion
   of the input molecule if `-fromCT` is set to *false* secondarily.   Molecules that do not
   match will fail and be reported as such in the log file.

.. option:: -fixmcs

   This flag fixes a portion of a molecule based on the maximum common subgraph against the
   `-fixfile` molecule.   Molecules that do not have any common subgraph will fail
   and be reported as such in the log file.
   [Default=false]

.. option:: -fromCT

   This boolean flag determines whether **OMEGA** should
   generate an initial set of 3D coordinates using only the connection
   table of the input molecule.  Initial model generation is always
   necessary for molecule file formats devoid of coordinates (i.e.,
   SMILES).  Bond lengths and angles taken from molecule files
   containing coordinates may be retained by setting this flag to
   false.  `-enumNitrogen off` must also be set for identical stereochemistry
   to be guaranteed in the output.  [Default=true]

.. option:: -maxmatch

   This flag is used to limit the number
   of fixfile substructure matches in the input molecule.  Each match
   will result in replacement of the matching substructure with
   coordinates taken from the fixfile fragment.  The number of matches
   may need to be limited using this parameter for a substructure
   where many matches are possible.  [Default=1]

.. option:: -mcsMinAtoms

   This parameter is used to define the limit of MCS-based fixes using `-fixmcs`.
   This is the minimum number of atoms that is required for a MCS-based fix.
   [Default=1]

.. option:: -strictfrags

   This flag sets how **OMEGA** generates fragments that are not in the fragment library.  The default is
   a faster and less rigorous fragment generation than the **MakeFragLib** program, whereas
   a *true* value will require **OMEGA** to be identical to the **MakeFragLib** program.  The most noticeable
   difference is the time limit for fragment generation, which is increased from 30 seconds to 300 seconds with
   `-strictfrags` set to ``true``.  [Default=false]

.. option:: -strictatomtyping

   This flag uses strict atom typing for MMFF94 or allows "close enough" atom typing.  A *true* setting will fail any molecule
   that contains an atom type that does not have specified parameters.  A *false* setting will allow parameters
   from a similar atom type to be used.  [Default=true]

.. option:: -umatch

   The *-umatch* boolean flag determines whether only
   the unique substructure matches of the fixfile are used for
   coordinate replacement.  A unique substructure match is defined as a
   match that does not cover the identical set of target atoms as any
   other substructure match in a set.  For example, a benzene
   substructure will match a benzene ring 12 times.  Only one
   substructure match constitutes a unique match, while the other 11
   matches are duplicates.  If the flag is set to *false*, then all
   possible substructure matches may be used for coordinate
   replacement.  This behavior is usually unnecessary as nonunique
   matches will frequently lead to duplication. [Default=true]


Structure Enumeration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. option:: -enumNitrogen

   The `-enumNitrogen` string flag controls
   the behavior of **OMEGA** with respect to enumeration of nonterminal
   nitrogens.  Any nitrogen with pyramidal geometry in the initial
   model of the input molecule and having no more than two ring bonds
   is considered by OMEGA to be *invertible*.  OMEGA will enumerate all
   possible puckers if the `-enumNitrogen` flag is set to ``all``.  OMEGA 
   will only enumerate unspecified invertible nitrogens if the flag is set to ``unspecified``.
   Nitrogen enumeration can be turned off by setting the flag to ``off``.
   [Default=unspecified]

.. option:: -enumRing

   The `-enumRing` boolean flag controls the
   behavior of **OMEGA** with respect to ring conformations.  If this flag
   is set to *true*, **OMEGA** will generate all possible combinations of all
   ring conformations in a molecule.  Ring systems with only a single
   conformation will be replaced with a conformation taken from a
   fragment file or generated on the fly by **OMEGA**. If this flag is set
   to *false*, then no ring conformer enumeration or replacement will
   occur.  Initial geometries provided by an input file (see
   `-fromCT`) may therefore be preserved by setting
   `-enumRing` to *false* as well.  [Default=true]

.. option:: -sampleHydrogens

   This flag sets whether hydrogens will be sampled.  This option enables sampling of hydrogen
   locations for -OH, -SH, and amines.  [Default=false]


Torsion Driving Parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. option:: -addtorlib

   This flag takes a filename as a parameter.  Torsion rules in the file are placed above any previous torsion rules and therefore are matched first
   (see :ref:`section_TorsionLibraryFormat`).

.. option:: -erange

   The `-erange` flag sets the energy cutoff
   used as an accept or reject criteria for conformers depending on the
   number of rotatable bonds in the structure.  Any conformer that has
   a calculated strain energy less than the sum of the energy window
   and the energy of the global minimum conformer will be accepted.
   Conformers with strain energies above this threshold are rejected.
   The energy range is given as a list of values that
   correspond to the `-rangeIncrement` parameter.  For example,
   `-erange 5.0 10.0 15.0 20.0` used with
   `-rangeIncrement 3` sets the energy window to 5.0 kcal/mol for
   structures with zero to two rotatable bonds, 10.0 kcal/mol for
   structures with three to five rotatable bonds, and so on.  The
   energy window for structures with more rotors than the highest
   `-erange` value specified will be taken as the highest specified
   value. [default = 10.0 15.0 15.0 20.0 (classic) ]

.. option:: -ewindow

   The `-ewindow` flag sets the energy window in kcal/mol used
   as an accept or reject criteria for conformers.  Any conformer that
   has a calculated strain energy less than the sum of the energy
   window and the energy of the global minimum conformer will be
   accepted.  Conformers with strain energies above this threshold are
   rejected. [Default=10.0 (classic) or 20.0 (macrocycle)]

.. option:: -maxConfRange

   The `-maxConfRange` flag allows the user to specify the maximum number of
   conformers to be output for a structure based on the number of rotatable
   bonds in the structure.  The maximum conformer range is given as a list of 
   values that correspond to the `-rangeIncrement` parameter.
   For example, `-maxConfRange 100 150 200 250` used with
   `-rangeIncrement 3` sets the maximum number of conformers to 100 for
   structures with zero to two rotatable bonds, 150 for
   structures with three to five rotatable bonds, and so on.  The
   number of conformers for structures with more rotors than the highest
   `-maxConfRange` value specified will be taken as the highest specified
   value.

.. option:: -maxconfs

   The `-maxconfs` flag sets the maximum number of conformations to be included in the output ensemble for each
   molecule. For molecules with few conformational degrees of freedom, the number of output conformers might be lower than
   the value set for this flag but will never exceed it. Out of all the generated conformers that satisfy the
   other ensemble slicing criteria (like `-ewindow` , `-rms`, etc.), the output
   includes only up to the `-maxconfs` number conformers that are the lowest in energy according force field
   set in `-searchff` flag.
   As a special case, setting `-maxconfs 0` along with `-rms 0` will result in **OMEGA** skipping the duplicate
   removal step and will write all generated conformers that satisfy all other criteria to the output file.
   [Default=200]


.. option:: -maxrot

   The `-maxrot` flag sets the cutoff for the maximum number
   of rotatable bonds.  Molecules that have rotors less than or equal to the `-maxrot`
   cutoff will be processed by **OMEGA**.
   **OMEGA** will not search for conformers of molecules that have more
   rotors than the `-maxrot` cutoff.  By default, **OMEGA** does not
   apply a cutoff for the number of rotatable bonds.  Instead, a desired cutoff
   must be supplied by the user.  [Default=9999]

.. option:: -maxtime

   This flag limits the amount of time (in seconds) spent for the torsion driving search during
   conformer generation for each molecule. The total time used for each molecule may
   exceed this limit due to all other steps of conformer generation.
   [Default=120.0]

.. option:: -rangeIncrement

   The `-rangeIncrement` is used to
   control the range for the number of rotatable bonds used with the
   `-maxConfRange`, `-rmsrange`, and `-erange` flags.
   The preceding flags are used to control the maximum number of
   conformers, RMS cutoff, and energy windows that are dependent
   on the number of rotors in a given structure. [Default=5]

.. option:: -rms

   The `-rms` flag sets the minimum Root Mean Square
   (RMS) Cartesian distance below which two conformers are duplicates.
   The RMS calculation is performed after superposition such that the
   true minimum distance between conformers is calculated.  Lowering
   the `-rms` value may cause **OMEGA** to generate ensembles that
   contain more representative conformers of a similar shape.  Higher
   `-rms` values may result in smaller, yet possibly more, shape-
   diverse ensembles.  [Default=0.5]

.. option:: -rmsrange

   The `-rmsrange` flag allows the user to specify the RMS cutoff used
   for duplicate conformer removal based on the number of rotatable bonds
   in the structure.  The RMS range is given as a list of values that
   correspond to the `-rangeIncrement` parameter.
   For example, `-rmsrange 0.8 1.0 1.2 1.4` used with
   `-rangeIncrement 3` sets the RMS cutoff value to 0.8 for
   structures with zero to two rotatable bonds, 1.0 for
   structures with three to five rotatable bonds, and so on.  The
   RMS cutoff value for structures with more rotors than the highest
   `-rmsrange` value specified will be taken as the highest specified
   value.

.. option:: -searchff

   This flag sets the force field used to calculate
   strain energies of conformers generated during a torsion search.
   Consult the description of force fields (see :ref:`section_ForceFields`)
   for an explanation of appropriate arguments for this flag.  [Default=mmff94smod_NoEstat]

.. option:: -settorlib

   The `-settorlib` flag is used to specify the file
   name of the file containing rules used in resolution control of the
   torsion driving part of conformer generation.  Refer to the :ref:`section_TorsionLibraryFormat` section
   describing the format of the torsion library.

.. option:: -thompson

   The `-thompson` flag sets whether to use Thompson sampling for exploring the conformer space.
   **OMEGA** will use this by default. If switched off, exhaustive sampling will be used. [default = true]

.. option:: -torlibtype

   The `-torlibtype` flag is used to specify the type of built-in torsion library.
   There are two types: `original`, and `guba`. The `original` is
   the default OMEGA torsion library and the `guba` [Guba-2016]_ is available in 
   OMEGA 3.0 and above. [Default=original]

.. option:: -useGPU

   The `-useGPU` flag is used to engage GPU-Omega to accelerate torsion driving on a
   GPU if one is available on the system. See :ref:`omega_gpuomega` for details. [Default=true]

.. option:: -thompson

   The `-thompson` flag sets whether to use Thompson sampling for exploring the conformer space.
   OMEGA will use exhaustive sampling by default. If switched Thompson sampling is used, the parameters
   can be controlled by the Thompson Sampling Options class. [Default=false]

..  _thompson-sampling-parameters:

Thompson Sampling Parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. option:: -maxTrials

    This parameter sets a limit on the number of Thompson sampling trials.
    OMEGA will stop exploration of the conformer space once this limit is reached,
    irrespective of how many conformers have been found so far. The default (and recommended) way of controlling
    this quantity, however, is through the `-maxTrialsRange` parameter. [Default=0]

.. option:: -maxTrialsRange

    This flag sets the maximum number of trials in Thompson sampling depending on the number of rotatable
    bonds in a given molecule. The range is determined by the `-trialsRangeIncrement` parameter.
    For example, `-maxTrialsRange 1000 2000 3000 5000` used with `-trialsRangeIncrement 3` sets the maximum
    number of trials  to 1000 for molecules with 0–2 rotors, 2000 for 3–5 rotors, 3000 for 6–8 rotors, and 5000 for all
    molecules with 9 or more rotors.

.. option:: -trialsRangeIncrement

    This parameter is used to control the dependence of maximum number of Thompson sampling trials on the
    number of rotors in the molecule along with the
    :ref:`SetMaxTrialsRange<OEConfGen_OEThompsonOptions_SetMaxTrialsRange>` parameter. [Default=1].


.. option:: -batchMaxRotors

    This parameter controls the maximum allowed number of rotors for which batching is done; that is, two
    samples are drawn from the current distributions to form all these rotors.
    The resulting :math:`2^{BatchMaxRotors}` conformers are processed in a batch and the distributions
    associated with the rotors are then updated. Higher `-batchMaxRotors` values result in a lower runtime, but for large
    enough batches, accuracy can be compromised as the learning is not reinforced frequently enough to
    influence many samples. [Default=2]

.. option:: -priorTemperature

    This parameter is used to set the initial probabilities (prior distributions) associated with
    each angle in the torsion rule according to values of respective strain associated with the angles.
    If a rule does not provide these strain values, all angles are assumed to be at zero strain and
    equally likely.
    For nonzero strains, this parameter acts as a Boltzmann temperature and gives the
    probability as :math:`= exp(-1 \times \frac{strain}{PriorTemperature})`.
    The lower the parameter, the stronger the initial preference for the angles with low strain.

    For instance, a torsion angle with strain of 5 kcal/mol will be initialized to a probability of 0.7% for
    `-priorTemperature` of 1, 60.6% for `-priorTemperature`  = 10 and 95% for `-priorTemperature`  = 100.
    [Default=100.0]


..  _omega-stereo-parameters:

Stereo Parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. option:: -flipper

   This parameter creates an ensemble of stereoisomers before passing the molecules for
   conformer generation.  A value of *true* will flip all unspecified stereo centers and
   a value of *force* will flip all stereo centers.  [Default=false]

.. option:: -flipper_enhstereo

   This flag considers enhanced stereo information during stereo-enumeration.
   [default = false]

.. option:: -flipper_maxcenters

   This flag sets the maximum number of stereocenters that can be flipped exhaustively.
   The number of molecules generated by
   enumerating the stereocenters is :math:`2^N`, where `N` is the number of
   stereocenters.  In some instances, this may be larger than is desired.  The
   `-flipper_maxcenters` parameter indicates the maximum number of stereocenters
   which will be fully enumerated.  If a molecule has more than
   `-flipper_maxcenters` stereocenters, **OMEGA** will randomly enumerate
   `2^(flipper_maxcenters)` instances from the full set of potential isomers.
   [Default=12]

.. option:: -flipper_warts

   This flag adds a wart to the title of each stereoisomer.
   [Default=false]

.. option:: -flipper_enhstereo

   This flag considers enhanced stereo information during stereo-enumeration.
   [Default=false]

.. option:: -strictstereo

   This parameter requires all stereo centers to be specified.  Molecules sent to conformer
   generation with unspecified stereo will fail. [Default=true]

General
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. option:: -strict

   This is a convenience flag for setting *-strictstereo*, *-strictatomtyping*,
   and *-strictfrags* all at once.  This setting will override any individual
   settings for these flags.


.. _omega_macrocycle_opt_params:

.. program:: macrocycle

Options Specific to the Macrocycle Mode
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Execute Options**

.. option:: -mpi_hostfile

   This is the path to the host file to be used for launching MPI processes.

.. option:: -mpi_np

   This is the number of MPI processors to launch. If this is not used, the job will run on a single processor.

.. note:: **The number of processors should be set to a reasonable number,
   preferably the maximum number of CPU cores available.**

.. option:: -param

   This is a parameter file name.

**File Options**

.. option:: -in

   This is the input molecular file name. Contrary to oeomega classic, pipe streaming cannot be used.

.. option:: -molnames

   This parameter specifies a text file containing a list of molecule names (one name
   per line in the file).  If this parameter is set, then only molecules in the
   input file(s) (parameter :option:`-in`) with names that match those
   in the text files will be read.

   The general purpose of this flag is to provide an easy mechanism for reading
   a few specific molecules that are contained in a large database, without
   having to extract those molecules by hand from the database.

.. option:: -out

   This is the output molecular file name. The following SD tags will be attached to the output:
   "Macrocycle Energy," "Relative Energy," "Macrocycle Iteration," "Macrocycle Duplicate Minima Count,"
   and "RMSD from Input Structure."
   Important note: the macrocycle mode does *not* support the `-rotorOffsetCompress` option.

.. option:: -prefix

   This is the prefix used to name output files.

.. option:: -progress

   This shows progress on the screen.  Options are *none*, *dots*, *log*, and *percent*.
   The *dots* options will display dots on the screen to show molecules that are
   completed.  The *log* option will duplicate the log file on screen.
   The *percent* option will track progress through the input file.  [Default=none]

**Calculation Options**

.. option:: -ewindow

   This is the energy window for output conformers. All conformations with energy higher than the energy window
   will be skipped from the molecular output file.

..  option:: -iteration_cycle_size

    This is the number of iterations to run before checking if a new minimum was found (the run will
    finish if no new minimum is found). [Default=100]
    [Aliases=-cycle_size]

..  option:: -max_iterations

    This is the maximum number of iterations (the calculation may converge before reaching this number).
    Each iteration is a single conformation generation which originates from a unique
    random atom (or fragment) placement. [Default=2000]
    [Aliases=-max_iter]

.. option:: -ref_tolerance

    This is the RMS gradient tolerance for force field refinement. [Default=0.001]

.. option:: -rms

   This is the deduplication threshold. [Default=0.5 |A|].

.. option:: -maxconfs

   The `-maxconfs` flag sets the maximum number of conformations to be included in the output ensemble for each
   molecule. For molecules with few conformational degrees of freedom, the number of output conformers might be lower than
   the value set for this flag but will never exceed it. [Default=400]
