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

.. program:: makefraglib

.. _chapter_makefraglib:

******************
MakeFragLib
******************

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

:ref:`MakeFragLib <chapter_makefraglib>` identifies, extracts, and generates conformers of
molecular fragments.  The model builder in **OMEGA** fragments input
molecules, retrieves corresponding fragment conformers, and assembles
them into a three dimensional structure.  Pregenerating fragment
conformers using **MakeFragLib** accelerates the model building
process.

The model builder in **OMEGA** attempts to capture all of the relevant
bond lengths, bond angles, and ring conformations for an input molecule.
Fragment assembly allows for a "divide and conquer" approach to model
building.  Much of the relevant information for building a molecular
model is contained in carefully chosen fragments.  :ref:`MakeFragLib <chapter_makefraglib>`
uses distance constraints and geometry optimization to generate
fragment conformations.  Only a single conformation is stored for
acyclic fragments, while all possible unique ring conformers are
retained within user defined limits.  Libraries created with
**MakeFragLib** can then be provided to **OMEGA** using the
`-setfraglib` or `-addfraglib` flags.

**MakeFragLib** can be used from the command line to generate ring
templates for use with **OMEGA** starting from only a collection of
molecules.  The output file from **MakeFragLib** can then be passed
directly into **OMEGA** using the `-setfraglib` or `-addfraglib`
flag.  Although fragment libraries may be concatenated using the Unix
'cat' command, this is not strictly necessary as multiple fragment
libraries may be specified as one argument to the flag.

.. _section_makefraglib_usage:

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

The following section shows several common command line executions of
:ref:`MakeFragLib <chapter_makefraglib>`.  Each example is followed by an explanation of what the
program will do.
Sample data files can be found in the data directory.

.. code-block:: bash

   prompt> makefraglib -in drugs.smi -out drugs_fraglib.oeb

All of the molecules in *drugs.smi* will be processed.  The set of all
unique fragments (according to **OMEGA** fragmentation rules) from all molecules in *drugs.smi* will be collected.

.. code-block:: bash

   prompt> makefraglib -in vendor.smi -out new_drugs_fraglib.oeb -ewindow 5.0

Conformers will be generated for all of the unique fragments found in
the user-supplied file *vendor.smi*.  An energy
window of 5 kcal above the global minimum conformer will be used to
accept or reject conformations of flexible ring systems.

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

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

.. code-block:: console
   
   > makefraglib --help

will generate the following output:

::

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


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

.. option:: -in

   File containing one or more molecules from which fragments will be generated.

.. option:: -out

   File to write fragments generated by **MakeFragLib**.  OEBinary format is required and gzipped OEBinary is recommended.


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

.. include:: ../common/mpi_execute_options.irst
.. include:: ../common/file_options.irst
.. include:: ../common/progress_options.irst


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

.. 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]
   [Aliases=**-bldff**,**-bldFF**]

.. option:: -fromCT


   This boolean flag determines whether *makefraglib* 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.  [Default=true]
   [Aliases=**-fromct**]

.. option:: -ewindow
.. option:: -ewindowRing

   These flags set the energy window in accepting or rejecting
   fragment conformers.  Any fragment conformer that
   has a calculated strain energy less than the sum of the energy
   window and the energy of the global minimum fragment conformer will be
   accepted.  Conformers with strain energies above this threshold are
   rejected. [Default=4.0]

.. option:: -rms
.. option:: -rmsRing

   These flags set the minimum Root Mean Square
   (RMS) Cartesian distance below which two fragment conformers are duplicates.
   The RMS calculation is performed after superposition such that the
   true minimum distance between fragment conformers is calculated.  Lowering
   the value may cause **MakeFragLib** to generate ensembles that
   contain more fragment conformers of a similar shape.  Higher
   values may result in smaller, yet possibly more shape
   diverse ensembles.  [Default=0.1]

.. option:: -startfact
.. option:: -startfactRing

   Factor for determining number of random starting geometries when 
   generating fragments. Legal values are from 1 to 100. [Default=2, 20]

.. option:: -fragGen
.. option:: -fragGenRing

   Maximum Number of conformers to be generated with distance geometry 
   for each fragment. [Default=40, 50000]

.. option:: -fragKeep
.. option:: -fragKeepRing

   Maximum Number of conformers to be kept for each fragment. 
   [Default=1, 1024]

.. option:: -timeLimit
.. option:: -timeLimitRing

   Maximum time in sec allowed for each fragment generation. 
   [Default=300]

.. option:: -maxtime


   Maximum time (s) allowed for fragment conformer search.
   [Default=300.0]
   [Aliases=**-maxsearchtime**]
