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


.. program:: chomp

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

.. include:: ../../common/mpi_execute_options.irst

----------------------------
Input parameters
----------------------------

.. option:: -userFrags

   This option is similar to the :option:`-in` flag except that it is for
   passing pregenerated fragments rather than for passing whole molecules.
   Using this flag skips the initial cutting apart stage; fragments are passed
   directly into the conformer generation and database construction phase.
   Fragments passed using this flag will be added to the database in the order
   in which they are read (no resorting occurs).  It is important to note that
   the :option:`-in` and :option:`-userFrags` flags can be used together.

.. option:: -userUnique

   This flag allows you to specify a database you would like to
   use for duplicate removal.  The fragments in the specified database will be
   determined as unique; if the fragment is seen again in the current run,
   those fragments will be skipped rather than incorporated into the new
   database.

----------------------------
Output parameters
----------------------------

.. option:: -prefix

   This string flag determines the prefix of the ``info``, ``log``, ``report``, ``param``, and
   ``output`` files.  For example, if :option:`-prefix` is set to foo, then the
   output files will include ``foo.info``, ``foo.log``, ``foo.report``, and
   ``foo.param``.  [Default=chomp]

.. option:: -dots

   When this flag is set, the program will write a series of dots (.) to the
   terminal (:file:`stdout/cout`) to track the progress of the program.  The
   dots are written in two phases: first as the molecules are cut apart and
   organized and second as the conformers are generated and the database is
   written.  [Default=true]

----------------------------
Control parameters
----------------------------

.. option:: -smarts

   This flag specifies the built-in SMARTS pattern to use to identify bonds to break,
   or a file containing user-defined rules for identifying bonds to break.

   Legal values are ``rlf``, ``recap``, ``both`` (both ``rlf`` and ``recap``), ``all``, or a filename containing user-defined rules.

   Please see :ref:`CHOMP Theory<chapter_brood_theory>` for a more detailed description.


.. option:: -capAttach

   When a fragment is generated with multiple attachment points, this flag
   controls whether all the related fragments can be generated by capping
   one or more of the attachment points with a hydrogen.  This can generate
   many more fragments, but is quite efficient. [Default=true]

.. option:: -flipper

   This flag controls whether the flipper algorithm is used to generate the 2^N
   specific isomers by enumerating the stereo on unspecified stereocenters.
   The flipper flag takes an integer indicating the N in the 2^N isomers that
   can be generated from N stereocenters.  If the stereocenters in the molecule
   exceed N, then 2^N random unique isomers are sampled from the available
   isomers. By default, no more than 32 isomers will be generated from any
   molecule.  [Default=5]

.. option:: -forceFlip

   The :option:`-forceFlip` flag causes all stereocenters in a ligand to be
   enumerated, even if they had specified stereo on the input structure.  While
   this can generate fragments that are not specifically represented in the
   input molecules, it is also a means of exploring more of the chemical fragment
   space. [Default=false]

.. option:: -flipN

   This flag controls whether or not nitrogen atoms with potential
   stereochemistry are enumerated. Some nitrogens atoms have real
   stereochemistry, while most others are easily invertible in solution.  In
   fragment replacement, specific invertible static nitrogen structures are
   often being compared to carbon-based structures that are not invertible.  It
   can therefore be useful to enumerate the nitrogen structures in the database
   even though they are interconvertible in solution.  For this reason, the
   flag here controls whether or not nitrogen atoms with potential
   stereochemistry are enumerated.  [Default=true]

.. option:: -omega

   This flag controls whether the conformer generation using the **OMEGA**
   conformers is applied to the fragments.  This flag has two important
   repercussions.  First, by turning it off, the process can be stopped after
   the relatively quick fragmentation phase.  This allows users to examine the
   fragments that are automatically written to an intermediate SMILES file
   before paying the high cost of generating conformers.  Second, you can
   choose to replace the **OMEGA** algorithm with sampling conformers from known
   structures using the :option:`-readConfs` flag.

.. option:: -readConfs

   This flag allows users to specify a 3D structure file from which the
   database generation algorithm will sample conformers.  For each fragment
   generated in the cutting algorithm, all examples of the fragment's
   conformers that are present in the molecule file specified by this flag will
   be added as conformers and saved in the **BROOD** database.  Identical
   conformers are recognized and duplicates are removed.  If you have access
   to a large database of small-molecule crystal structures, this flag can be
   used to sample conformers from that database rather than using the **OMEGA**
   algorithm.

   .. note::

      The input molecules used to generate the fragments (from the
      :option:`-in` or :option:`-userFrags` flags) do not need to be the
      same as the input molecules specified with this flag.

.. option:: -primaryFrag

   This flag indicates that **CHOMP** should only process the smallest possible
   fragments with the given fragmentation pattern.  It is primarily for
   fragmentation applications unrelated to **BROOD**.

.. _fragment_selection_params:

-----------------------------
Fragment selection parameters
-----------------------------

.. option:: -filter

   This is a complex flag that specifies both whether the default filter
   should be applied to the fragments with the values (True and False).
   The :option:`-filter` flag can also be used to specify a filter
   file describing a non-default filter to be used to filter the fragments.
   For additional information on filtering, please see the documentation for the
   filter product.

.. option:: -minFrequency

   During the breaking of input molecules into fragments, the number of source
   molecules from which a fragment can be extracted is tracked.  This flag
   indicates the minimum number of source molecules that are required in order
   for the fragment to be retained.  The frequency in this case is normalized
   as a percentile where 99 indicates the most common fragments and 0 indicates
   the least common fragments.  By default, all fragments are retained. [Default=0]

.. option:: -maxDegree
.. option:: -minDegree

   The :option:`-minDegree` and :option:`-maxDegree` flags specify the range of 
   acceptable attachment points for fragments generated by **CHOMP**. The :option:`-maxDegree` can not be more than 3
   to produce a compatible fragment with the **BROOD** app. [Default=1,3]

.. option:: -maxMolWt

   This is a simple flag that allows the user to specify the maximum molecular
   weight of any fragment generated by **CHOMP**. [Default=350.0]

.. option:: -maxHvy
.. option:: -minHvy

   These flags specify the range of heavy atoms allowed in fragments generated by the **CHOMP** algorithm.
   [Default=0,15]

.. option:: -maxChiral

   This flag allows you to specify the maximum number of chiral centers (both
   atom and bond centers) in a fragment.  While there are many drugs and
   other useful molecules with a large number of stereocenters, they are often
   added for a specific purpose and should not be suggested lightly in a design
   setting.  For this reason, fragments with many chiral centers may be
   undesirable in some databases.  This flag allows the user to efficiently
   eliminate these fragments. [Default=3]