Installing DOCK 6

DOCK is Unix based scientific software and follows a common installation recipe: download, unpack, configure, build, and test. The simple configuration scheme of DOCK is based on plain text files. Building and testing employ the make command. DOCK installation is so simple and transparent that users have a reasonable chance of correcting problems themselves.

Start with a plain serial installation. Follow the detailed steps (1. through 5.) enumerated below. The appropriate configuration option is likely gnu; see step 3. Subsequently, additional executables can be installed for parallel, pbsa, etc; see step 6. (Here is a quick start for an example gnu serial and parallel installation: cd install; ./configure gnu; make install; make dockclean; ./configure gnu parallel; setenv MPICH_HOME /bla; make dock; make test;).

If problems occur then read the diagnostics carefully and apply the scientific method. To observe what's under the hood, view the configuration file (install/config.h) that is created by configure, and execute make -n for a dry run. Consult the FAQ. Search the DOCK-Fans mailing list archive.

NOTE FOR WINDOWS USERS: DOCK and its accessories must be run using a Unix-like environment such as Cygwin ( [[1]] ). We recommend a full Unix installation. In particular, when you install your emulator, make sure to also install compilers, Unix shells, and perl ( Devel for Cygwin ). All steps below should be performed using Cygwin or another Unix emulator for Windows. See also the DOCK wiki entry for Cygwin.

(1) Unpack the distribution using the following command:

[user@dock ~] tar -zxvf dock.6.7.tar.gz

(2) Enter the installation directory:

[user@dock ~] cd dock6/install

(3) Configure the Makefile for the appropriate operating system:

[user@dock ~] ./configure [configuration file]

AUTHOR: Scott Brozell

USAGE: configure [-help] [configuration file]

OPTIONS: Notable ones are listed below; for a complete list see the configure -help output.
-help #emit the usage statement
configuration file #input file containing operating system appropriate variables

Configuration Files	Target
gnu	GNU compilers
gnu.acml	recent GNU compilers and ACML
gnu.parallel	GNU compilers with parallel processing capability
gnu.pbsa	GNU compilers with PB/SA (ZAP library) capability
gnu.parallel.pbsa	GNU compilers with parallel processing and PB/SA (ZAP library) capabilities
ibmaix	IBM AIX and native compilers
intel	Intel compilers
intel.mkl	Intel compilers and MKL
pgi	PGI compilers
sgi	SGI native compilers

Description

Create the DOCK configuration file, config.h, by copying an existing configuration file that is selected using the arguments. When invoked without arguments, print this usage statement and if the configuration file exists then print its creation stamp. Some configuration files require that environment variables be defined; these requirements are listed in the files and emitted by configure. Note that as of version 6.6 gfortran is the default Fortran compiler in the gnu config files (replacing g77). But other Fortran compilers may be used; simply hand edit install/config.h to use alternatives.

Build the desired DOCK executable(s) via one of the following commands:

[user@dock ~] make all # builds all the DOCK programs [user@dock ~] make dock # builds only the dock program
[user@dock ~] make utils # builds only the accessory programs

Test the built executable(s) via these commands:

[user@dock ~] cd test; make test; make check

The test directory contains the DOCK quality control (QC) suite. It produces pass/fail results via fast regression tests. The suite should complete in less than ten minutes; five minutes is typical. Un-passed tests should be examined to determine their significance. The make check command executed from the test directory emits all the differences uncovered during testing. The make clean command executed from the test directory removes all files produced during testing; this command is automatically executed by the main make test command above; however, to run tests from a subdirectory of the test directory, one should explicitly execute make clean.

NOTE: Some failures are not significant. For example, differences in the tails of floating point numbers may not be significant. The sources of such differences are frequently platform dependencies from computer hardware, operating systems, and compilers that impact arithmetic precision and random number generators. In addition, the reference outputs as of version 6.4 are from a 64 bit platform and as of version 6.6 use gfortran gcc version 4.4.5, and this can cause false positives on 32 bit platforms or with other compilers; in particular, differing numbers of Orientations or Conformations and different Contact or Grid scores. We are working on increasing the QC suite's resilience to these issues. For now, apply common sense and good judgment to determine the significance of a possible failure. Note that some number of failures is rarely an indication of real problems, but if almost every test fails then something is amiss.

Some features of DOCK (DOCK3.5 Score aka ChemGrid Score) require an electrostatic potential map which is usually generated by DelPhi. Testing of these features requires that the environment variable DELPHI_PATH be defined to the full path of the DelPhi executable. DelPhi is not distributed with DOCK; see also here.

(6) OPTIONAL: Alternate executables.

(i) DOCK with parallel processing functionality requires a Message Passing Interface (MPI) library. Because of the vagaries of MPI libraries, building parallel DOCK has more pitfalls than installing the serial version. The MPI library must be installed and running on the system if the parallel features of DOCK are to be used.

Currently, the DOCK installation mechanism only directly supports the MPICH2 and MPICH implementations. (But other MPI implementations can be accommodated probably with the only extra effort of editing the config.h file.) The MPICH2 library is freely available from Argonne National Labs ([[2]]). Once MPI is installed, define the environment variable MPICH_HOME to the top level MPICH2 directory. MPICH_HOME will be referenced by all stages of the build procedure - from configuration through testing. See the Parallel DOCK section for execution information.

WARNING: The parallel configuration files have been tailored to a typical MPICH2 build. Linking problems, such as undefined references and cannot find libbla_bla, can occur due to idiosyncrasies in the MPI installation. One corrective approach is to use manual linking; add to the LIBS definition in config.h the link flags (-L and -l) from the command: $MPICH_HOME/mpicc -show; in general, the LIBS should contain those link flags in the same order.

(ii) DOCK with PB/SA scoring requires OpenEye Toolkits. In particular, DOCK uses the APIs as in OEChem TK 1.7.0 and Zap TK 2.1.1. These can be obtained from OpenEye ([[3]]). Once they are installed, define the environment variable ZAP_HOME to the directory that contains the ZAP library. ZAP_HOME is used during installation and testing. For execution the environment variable OE_LICENSE must also be defined to the full path of the license file. (Here is a quick start for an example gnu pbsa installation after already building and testing a serial gnu installation:

cd install; ./configure gnu.pbsa; setenv ZAP_HOME /openeye/toolkits/1.7.0-3/redhat-RHEL5-g++4.1-x64/; setenv OE_LICENSE /openeye/oe_license.txt; make dockclean; make dock; make testpbsa;).