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

.. _receptor_toolbox:

******************
ReceptorToolbox
******************

.. program:: receptor_toolbox

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

:ref:`receptor_toolbox` is a utility program for receptors that can do the
following

* List information about the receptor

* Set the name of the receptor and/or bound ligand

* Extract molecules from the receptor

* Setup a scoring cache for :ref:`chapter_fred`, :ref:`chapter_hybrid` or :ref:`SCOREPOSE`.

* Enable/Disable existing constraints.


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

Setup a receptor cache for *fred*
----------------------------------

This example illustrates setting up a receptor cache for :ref:`chapter_fred`.

Input files

   * **receptor.oedu** : A file containing a receptor.

Command line

      .. code-block:: bash

         prompt> receptor_toolbox -receptor receptor.oedu -prepare_score_cache fred

Output files

   * **receptor.oedu** :
     Receptor with score cache for :ref:`chapter_fred` (overwrites input file).


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

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

.. code-block:: console

   > receptor_toolbox --help

will generate the following output:

::

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


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

Receptor File to Operate On

.. option:: -receptor <receptor file>

   :ref:`RECEPTOR_TOOLBOX` reads this receptor file, and if the receptor is
   edited in any way the modified receptor will be output to this file
   (overwriting the original).

   [Aliases=**-rec**]

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

Score Caching
-------------

.. option:: -prepare_score_cache <fred, scorepose or hybrid>    [No Default]

  Caches scoring setup for the specified program on the receptor.  This is not
  required, however doing so will improve the initial speed of the program by
  not requiring it to do as much scoring setup.

  A receptor can only have a score cache for one program at a time (previous
  score caches will be erased when this flag is used).

  .. note::

     Creating a score cache will substantially increase the size of the receptor
     file, typically on the order of 100 MBytes.

   [Aliases=**-prepare**]

.. option:: -clear_score_cache [Default=false]

   If this flag is set to true any scoring cache on the receptor will be removed.

   [Aliases=**-clear_cache**]

Inner Contour
-------------

.. option:: -turn_inner_contour <on or off>   [No Default]

   If this flag is set the inner contour will be turned on or off, as specified.
   See :ref:`Receptor Theory Section<receptor_theory_negative_image>` for an
   explanation of the inner contour.

   [Aliases=**-inner_contour**,**-inner**]

Protein Constraints
-------------------

.. option:: -enable_protein_constraint <name> [<name> ...]   [No Default]

   Enables the specified protein constraints.  The name can be either the name
   of the constraint or the name of the atom that the constraint is associated with.

   [Aliases=**-enable_protein_constraints**]

.. option:: -disable_protein_constraint <name> [<name> ...]   [No Default]

   Disables the specified protein constraints.  The name can be either the name
   of the constraint or the name of the atom that the constraint is associated with.

   [Aliases=**-disable_protein_constraints**]

.. option:: -enable_all_protein_constraints [Default=false]

   Enables all protein constraints.

   [Aliases=**-enableallproteinconstraints**]

.. option:: -disable_all_protein_constraints [Default=false]

   Disables all protein constraints.

   [Aliases=**-disableallproteinconstraints**]

Custom Constraints
------------------

.. option:: -extract_custom_constraints <filename>   [No Default]

   Extracts the receptors custom constraints to this specified file.

.. option:: -set_custom_constraints <filename>   [No Default]

   Sets the receptors custom constraints to be those in the specified file.

   The format of the constraint file is a text file with lines of one of the two
   following forms

   .. code-block:: bash

      SPHERE <ID> <RAD> <X> <Y> <Z>
      SMARTS <ID> <SMARTS Pattern>

   * **SPHERE** creates a sphere associated with a given constraint

      * ID is an integer that uniquely identifies a constraint

      * RAD is the radius of the sphere

      * X, Y and Z is the sphere center

   * **SMARTS** Creates a SMARTS pattern associated with the specified sphere.

      * ID is an integer that uniquely identifies a constraint

      * SMARTS Pattern is the SMARTS pattern to associate with the constraint.

   The following example file

   .. code-block:: bash

      SPHERE 1 4.0 1.0 1.0 1.0
      SMARTS 1 F
      SPHERE 2 4.5 3.0 2.5 -1.0

   Creates two constraints.  Constraint 1 has one sphere centered at
   (1.0, 1.0, 1.0) with radius 4.0 and can only be satisfied by a fluorine atom
   on the ligand.  Constraint 2 has one sphere centered at (3.0, 2.5, -1,0)
   with radius 4.5 and can be satisfied by any heavy atom on the ligand since
   the constraint as no associated smarts patterns.

   See :ref:`Receptor Theory Section<receptor_theory_constraints>` for more
   information about constraints.

.. option:: -enable_custom_constraint <constraint> [<constraint> ...]   [No Default]

   Enables the specified custom constraints.

   [Aliases=**-enable_custom_constraint**,**-enable_custom_constraints**]

.. option:: -disable_custom_constraint <constraint> [<constraint> ...]   [No Default]

   Disables the specified custom constraints.

   [Aliases=**-disable_custom_constraints**]

.. option:: -enable_all_custom_constraints [Default=false]

   If this flag is set to true all custom constraints on the receptor are enabled.

.. option:: -disable_all_custom_constraints [Default=false]

   If this flag is set to true all custom constraints on the receptor are disabled.
