Installing DOCK 6: Difference between revisions

From DISI
Jump to navigation Jump to search
(Created page with " 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...")
 
m (asdf)
 
(6 intermediate revisions by 2 users not shown)
Line 6: Line 6:
The simple configuration scheme of DOCK is based on plain text files.
The simple configuration scheme of DOCK is based on plain text files.
Building and testing employ the
Building and testing employ the
[[make]]
make
command.
command.
DOCK installation is so simple and transparent that users
DOCK installation is so simple and transparent that users
Line 18: Line 18:
for parallel, pbsa, etc; see step 6.
for parallel, pbsa, etc; see step 6.
(Here is a quick start for an example gnu serial and parallel installation:
(Here is a quick start for an example gnu serial and parallel installation:
cd install; ./configure gnu; make install;
  cd install; ./configure gnu; make install;
make dockclean; ./configure gnu parallel;
  make dockclean; ./configure gnu parallel;
setenv MPICH_HOME /bla; make dock; make test;).
  setenv MPICH_HOME /bla; make dock; make test;).


If problems occur then read the diagnostics carefully and apply the
If problems occur then read the diagnostics carefully and apply the
[[scientific method]].
[[scientific method]].
Line 28: Line 27:
file (install/config.h) that is created by configure,
file (install/config.h) that is created by configure,
and execute make -n for a dry run.
and execute make -n for a dry run.
Consult the [[FAQ]].
Consult the [[DOCK6 FAQ | FAQ]].
Search the [[DOCK-Fans]] mailing list archive.
Search the [[DOCK-Fans]] mailing list archive.


Line 35: Line 34:
USERS: DOCK and its accessories must be run using a Unix-like
USERS: DOCK and its accessories must be run using a Unix-like
environment such as Cygwin
environment such as Cygwin
( [[http://www.cygwin.com/]] ).
( [[https://www.cygwin.com/]] ).
We recommend a full Unix installation.
We recommend a full Unix installation.
In particular, when you install your emulator,
In particular, when you install your emulator,
Line 41: Line 40:
All steps below should be performed
All steps below should be performed
using Cygwin or another Unix emulator for Windows.
using Cygwin or another Unix emulator for Windows.
See also the [[DOCK wiki entry for Cygwin]].
See also the [[DOCK on cygwin | DOCK wiki entry for Cygwin]].


   
   
Line 47: Line 46:
using the following command:
using the following command:


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


</blockquote>
(2) Enter the installation directory:
(2) Enter the installation directory:


<blockquote>
  [user@dock ~] cd dock6/install
[user@dock ~] cd dock6/install


</blockquote>
(3) Configure the Makefile for the
(3) Configure the Makefile for the
appropriate operating system:
appropriate operating system:


<blockquote>
  [user@dock ~] ./configure [configuration file]
[user@dock ~] ./configure
[configuration file]


   
   
AUTHOR: Scott Brozell
AUTHOR: Scott Brozell
   
   
USAGE: configure [-help]
USAGE: configure [-help]
[configuration file]
[configuration file]


OPTIONS: Notable ones are listed below;
OPTIONS: Notable ones are listed below;
for a complete list see the configure -help output.<br> '''-help''' #emit the usage statement<br> '''configuration file''' #input file
for a complete list see the configure -help output.<br> '''-help''' #emit the usage statement<br> '''configuration file''' #input file
Line 78: Line 68:


                                                  
                                                  
{| border="1"
{| class="wikitable"
|-
|-
|'''Configuration Files '''
|'''Configuration Files '''
Line 87: Line 77:
|-
|-
|gnu.acml
|gnu.acml
|recent GNU compilers and
|recent GNU compilers and [[ACML]]
            [[ACML]]
|-
|-
|gnu.parallel
|gnu.parallel
Line 106: Line 95:
|-
|-
|intel.mkl
|intel.mkl
|Intel compilers and
|Intel compilers and [[MKL]]
            [[MKL]]
|-
|-
|pgi  
|pgi  
Line 115: Line 103:
|SGI native compilers
|SGI native compilers
|}  
|}  
DESCRIPTION:<br>
 
= Description =


Create the DOCK configuration file, config.h, by copying an existing
Create the DOCK configuration file, config.h, by copying an existing
Line 128: Line 117:
to use alternatives.
to use alternatives.


</blockquote>
Build the desired DOCK executable(s) via
(4) Build the desired DOCK executable(s) via
one of the following commands:
one of the following commands:


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


[user@dock ~] make dock # builds only the dock program<br>


[user@dock ~] make utils # builds only the accessory programs
</blockquote>
(5)
Test the built executable(s) via these commands:
Test the built executable(s) via these commands:


<blockquote>
  [user@dock ~] cd test; make test; make check
[user@dock ~] cd test; make test; make check


   
   
Line 188: Line 170:
[[here.]]
[[here.]]


</blockquote>
(6) OPTIONAL: Alternate executables.
(6) OPTIONAL: Alternate executables.


<blockquote>
(i) DOCK with parallel processing functionality
(i) DOCK with parallel processing functionality
requires a Message Passing Interface (MPI) library.
requires a Message Passing Interface (MPI) library.
Line 198: Line 178:
The MPI library must be installed and running on the system if the
The MPI library must be installed and running on the system if the
parallel features of DOCK are to be used.
parallel features of DOCK are to be used.
<br>


Currently, the DOCK installation mechanism only directly supports
Currently, the DOCK installation mechanism only directly supports
Line 205: Line 184:
with the only extra effort of editing the config.h file.)
with the only extra effort of editing the config.h file.)
The MPICH2 library is freely available from Argonne National Labs
The MPICH2 library is freely available from Argonne National Labs
([[http://www.mcs.anl.gov/research/projects/mpi/]]).
([[https://www.mcs.anl.gov/research/projects/mpi/]]).
Once MPI is installed, define the environment variable MPICH_HOME
Once MPI is installed, define the environment variable MPICH_HOME
to the top level MPICH2 directory.  
to the top level MPICH2 directory.  
Line 214: Line 193:
for execution information.
for execution information.


WARNING: The parallel configuration files have been
WARNING: The parallel configuration files have been
tailored to a typical MPICH2 build.
tailored to a typical MPICH2 build.
Line 225: Line 203:
in general, the LIBS should contain those link flags in the same order.
in general, the LIBS should contain those link flags in the same order.


(ii) DOCK with PB/SA scoring requires OpenEye Toolkits.
(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.  
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
These can be obtained from OpenEye
([[http://www.eyesopen.com/]]).
([[https://www.eyesopen.com/]]).
Once they are installed, define the environment variable ZAP_HOME to the
Once they are installed, define the environment variable ZAP_HOME to the
directory that contains the ZAP library. ZAP_HOME is used during
directory that contains the ZAP library. ZAP_HOME is used during
Line 236: Line 213:
(Here is a quick start for an example gnu pbsa installation after
(Here is a quick start for an example gnu pbsa installation after
already building and testing a serial gnu installation:
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;).


</blockquote>
  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;).
 
[[Category:DOCK]]
[[Category:DOCK 6]]
[[Category:Software]]
[[Category:Freecom]]

Latest revision as of 01:22, 24 May 2024

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;).