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

.. program:: chomp

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

This section gives a series of examples of **CHOMP** command-line executions.  Unlike
**BROOD**, **CHOMP** does not have a GUI and must be accessed from the command line.
Each of these examples is followed by a brief description of its behavior.


.. code-block:: bash

   prompt> chomp -in mymolecules.smi -out myfragDB
   prompt> chomp -i mymolecules.smi -o myfragDB
   prompt> chomp mymolecules.smi myfragDB


All three of these command lines specify exactly the same thing.  In each case,
**CHOMP** will read the molecules in :file:`mymolecules.smi` and write the **BROOD**
database in the directory :file:`myfragDB`.  This is the most basic and most
common **CHOMP** execution.  Since the :option:`-dots` flag defaults to ``True``,
dots will be written to ``std:cout`` to indicate the progress of the molecular
fragmentation as the job progresses.  The :file:`myfragDB` directory will be
filled with just over 40 files that contain all the information critical for
efficient 3D **BROOD** searches.

.. code-block:: bash

   prompt> chomp -param oldrun.param

This execution of **CHOMP** will read the command-line parameters from the
file :file:`oldrun.param`.  Every time **Chomp** is executed, a file called
:file:`chomp.param` is written that records the command-line parameters used.
This is useful for recalling what was used in a specific execution or for
repeating a previous calculation.

.. code-block:: bash

   prompt> chomp -userFrags myFrags.sdf -out newDB

This reads the molecular fragments from the :file:`myFrags.sdf` and, bypassing
the fragmentation phase, generates 3D conformers and relates precalculated
parameters, and writes the database into multiple files in the :file:`newDB`
directory.

.. code-block:: bash

   prompt> chomp -in myMolecules.sdf -userUnique oldDB -out newDB

This execution of **CHOMP** behaves the same as the prior execution, except that
every fragment generated by the fragmentation of :file:`myFrags.sdf` will be
compared to the fragments in the **BROOD** database :file:`oldDB` (generated
earlier). Fragments that exist in the old database will not be included
in the :file:`newDB`.

.. code-block:: bash

   prompt> chomp -in myMolecules.sdf -omega false -out newDB

This reads and fragments the molecules from
:file:`myMolecules.sdf`, then writes all of the fragments (including source
information) to the SMILES file :file:`newDB.ism`.  It will not generate
conformers nor will it write a **BROOD** database.  The newly generated SMILES file
is available for examination and editing.  After this partial run, the database
preparation can be completed by passing the SMILES :file:`newDB.ism` into **CHOMP**
using the :option:`-userFrags` parameter.

.. code-block:: bash

   prompt> chomp -in myMolecules.sdf -readConfs xtals.sdf -out newDB

This execution of **CHOMP** reads and fragments the molecules from
:file:`myMolecules.sdf`.  Then, rather than using OMEGA to generate conformers
for the database, **CHOMP** uses the conformers read from the structures in
:file:`xtals.sdf` to generate conformers for the fragments.  These conformers
will be written into the new **BROOD** database :file:`newDB`.

.. code-block:: bash

   prompt> chomp -smarts bondids mymolecules.smi myfrags.oeb.gz
   prompt> chomp mymolecules.smi myfrags.oeb.gz -smarts bondids

This example demonstrates two important principles. The first is that the first of these two
command lines will work, but the second will result in an error.  When
specifying a command line with keyless arguments for the :option:`-in` and
:option:`-out` files, these files must be the final two arguments on the
command line.  

The second principle involves use of non-default fragmentation patterns.  In this
example, **CHOMP** uses the SMARTS patterns in the file :file:`bondids` to
generate fragments rather than the default fragmentation scheme.

.. code-block:: bash

   prompt> chomp -mpi_np 16 -in mymolecules.sdf -out newDB

In this execution, the :file:`mymolecules.sdf` is read, the molecules are
fragmented, 3D conformers are generated and the database is written to the
directory :file:`newDB`.  The fragmentation and the more expensive conformer
generation will be carried out on 16 local processors.  On modern multicore
workstations, this parameter is often a highly efficient means to execute
**CHOMP**.
