.. _tutorial_basic_usage:

*******************************************************************************
Tutorial 0: Basic usage of **FastROCS TK**
*******************************************************************************

.. oe:language:: python

   **FastROCS TK** is primarily designed to be used as a server/client interface. Example 
   scripts are provided with **FastROCS TK** to help you get up and running. This
   tutorial demonstrates the use of the :ref:`section_example_fastrocs_shapedatabaseserver` and
   :ref:`section_example_fastrocs_shapedatabaseclient`. 
   example scripts, which are provided below.

   .. only:: oehtml

      .. admonition:: Download code

         :download:`ShapeDatabaseServer.py <../../../../../../wrappers/python/examples/fastrocs/ShapeDatabaseServer.py>`
         :download:`ShapeDatabaseClient.py <../../../../../../wrappers/python/examples/fastrocs/ShapeDatabaseClient.py>`

   .. only:: oepdf

      .. oe:source:: ShapeDatabaseServer.py
         :language: python
      .. oe:source:: ShapeDatabaseClient.py
         :language: python

 
   After **FastROCS TK** has been installed follow these simple steps for the most
   basic usage of **FastROCS TK**:

   #. Start the server on an OMEGA conformer database in your terminal in the virtual environment
      you used to install the **OpenEye Toolkits**::


         (fastrocs) $ ShapeDatabaseServer.py your_database.oeb

   #. Query the server from another terminal using the same virtual environment::

         (fastrocs) $ ShapeDatabaseClient.py localhost:8080 your_query.sdf output_overlays.sdf

   .. note::

      The server can be queried from the same terminal by putting the ShapeDatabaseServer process
      in the background by doing ``ctrl z && bg``. 

   .. warning::

      For best performance, do not use GNU Zipped (.gz) molecule
      databases with FastROCS. Uncompress the ``.oeb.gz`` to ``.oeb``
      first.

   For more advanced options see the ``--help`` menu::

         (fastrocs) $ ShapeDatabaseClient.py --help


      .. code-block:: bash

         usage: ShapeDatabaseClient.py [-h] [--tversky] [--shapeOnly]
                                       [--alternativeStarts {random,subrocs,inertialAtHeavyAtoms,inertialAtColorAtoms}]
                                       server:port query results [nHits]

         positional arguments:
           server:port           Server name and port number of database to search i.e.
                                 localhost:8080.
           query                 File containing the query molecule to search (format
                                 not restricted to *.oeb).
           results               Output file to store results (format not restricted to
                                 *.oeb).
           nHits                 Number of hits to return (default=100).

         optional arguments:
           -h, --help            show this help message and exit
           --tversky             Switch to Tversky similarity scoring
                                              (default=Tanimoto).
           --shapeOnly           Switch to shape-only scores (default=Combo).
           --alternativeStarts {random,subrocs,inertialAtHeavyAtoms,inertialAtColorAtoms}
                                 Optimize using alternative starts (default=inertial).
                                 To perform N random starts do "--alternativeStarts
                                 random N" (default N=10)
