Guideline for users

Minimal compilation instructions

Preparation

Before compiling the code, the libraries specific for each GPU/architecture need to be installed, depending on the available hardware. Note that for NVIDIA or AMD GPUs, system drivers for the need to be already installed.

NVIDIA (Cuda)

On Debian/Ubuntu distributions it is possible to install libraries and dependencies can be installed using apt:

    sudo apt install nvidia-opencl-dev  nvidia-opencl-icd nvidia-cuda-dev
    export GPU_INCLUDE_PATH=/usr/include
    export GPU_LIBRARY_PATH=/usr/lib/x86_64-linux-gnu

For other distributions, drivers and development libraries can be installed either from the official distribution repositories or from the NVIDIA website, then environment libraries need to be set accordingly. For example, when using the NVIDIA official installer, environment paths should be as following:

    export GPU_INCLUDE_PATH=/usr/local/cuda/include
    export GPU_LIBRARY_PATH=/usr/local/cuda/lib64

however their location might vary. To find the path to be specified for the GPU_INCLUDE_PATH variable, find where the cuda.h file is located, while for the GPU_LIBRARY_PATH path, locate the file libcuda.so.

AMD (OpenCL)

On Debian/Ubuntu distributions it is possible to install libraries and dependencies using apt:

    sudo apt-get install opencl-headers

When using the official repositories, the paths should be:

    export GPU_INCLUDE_PATH=/usr/include
    export GPU_LIBRARY_PATH=/usr/lib/x86_64-linux-gnu

If another installation method is used (e.g. Intel OpenCL SDK), environment variables GPU_INCLUDE_PATH and GPU_LIBRARY_PATH have to point to the locations of CL/CL.h and libopencl.so files, respectively.

CPU (OpenCL)

On Debian/Ubuntu distributions it is possible to install libraries and dependencies using apt:

    sudo apt-get install opencl-headers

When using the official repositories, the paths should be:

    export CPU_INCLUDE_PATH=/usr/include
    export CPU_LIBRARY_PATH=/usr/lib/x86_64-linux-gnu

If another installation method is used, environment variables CPU_INCLUDE_PATH and CPU_LIBRARY_PATH have to point to the locations of CL/CL.h and libopencl.so files, respectively.

Compilation

Once libraries are installed, the code can be compiled.

• NVIDIA (CUDA)

        make DEVICE=GPU && make DEVICE=CUDA

• AMD (OpenCL)

        make DEVICE=OCLGPU && make DEVICE=OPENCL

• CPU (multiprocessor, requires CPU OpenCL installation)

        make DEVICE=CPU

• Apple macOS

On both Intel and AMD Macs make should be sufficient.

• Windows

A Visual Studio project file is provided for compilation using OpenCL. Alternatively, we strive to provide binaries for Windows for every major release as well.

Executables

When the compilation is completed, the AutoDock-GPU executables will be found in the bin/ directory. The docking executable is:

    bin/autodock_gpu_128wi   # GPU-accelerated (Nvidia, AMD, Intel)
    bin/autodock_cpu_1i   # CPU multi-processor

A standalone CPU-only analysis tool with the same analysis features as the AutoDock-GPU binary is also compiled. This may come in handy for situations with CPU-only data processing nodes (or laptops etc.) where the GPU-docking functionality is not needed. For example, xml result files can be batch processed into dlg files and interactions can be assigned (and for example their cutoffs changed).

    bin/adgpu_analysis    # CPU-only analysis tool

Execution example

./bin/autodock_gpu_64wi \
--ffile ./input/1stp/derived/1stp_protein.maps.fld \
--lfile ./input/1stp/derived/1stp_ligand.pdbqt

By default the output log file is written in the current working folder. Examples of output logs can be found under examples/output.

Extra compilation options

DEVICE and NUMWI

When compiling, it is possible to adjust the work-group size depending on the GPU and workload, which adjusts the work-group/thread block size:

    make DEVICE=<TYPE> NUMWI=<NWI>

where DEVICE can be any of the target architectures (CPU, GPU, CUDA, OCLGPU, OPENCL) and NUMWI can be 1, 2, 4, 8, 16, 32, 64, 128 or 256. With modern GPU cards,NUMWI=128 (default) or NUMWI=64 are reasonable options. On MacOS, use NUMWI=1 when compiling for CPUs.

OVERLAP

By default we compile with the option OVERLAP set to ON. This provides a parallelized path for virtual screenings (batch dockings) to overlap ligand reading, setup, docking, and output processing. This option also enables multiple GPUs to be used concurrently for virtual screenings.

TENSOR (Cuda-only)

A recent feature for certain Nvidia GPUs is the use of tensor cores to speed up certain parts of docking with Cuda when TENSOR=ON.

TARGETS (Cuda-only)

By default, make DEVICE=CUDA tests which targets the given Cuda installation supports and compiles for them. On head nodes, this might not always be the desired behavior and thus TARGETS can be specified directly. For example, TARGETS=80 would compile only for compute architecture 80 (Ampere GPUs) while TARGETS="80 86" compiles for both Ampere (80) and Ada GPUs (86).

HPC and other systems

In order to run on certain systems, especially HPC settings, the following variables need to be defined:

• CPU accelerator : $(CPU_INCLUDE_PATH) and $(CPU_LIBRARY_PATH)
• GPU accelerator : $(GPU_INCLUDE_PATH) and $(GPU_LIBRARY_PATH)
• Both platforms: $(LD_LIBRARY_PATH)

Explanation

• $(CPU_INCLUDE_PATH) / $(GPU_INCLUDE_PATH): paths containing the Cuda or OpenCL header files, i.e., cuda.h, CL/cl.h, CL/cl.hpp, and opencl.h.
• $(CPU_LIBRARY_PATH) / $(GPU_LIBRARY_PATH): paths containing the Cuda or OpenCL shared libraries, i.e., libcudart.so and libOpenCL.so.

The following environment variables are usually set by the corresponding driver installer or module systems: $INTELOCLSDKROOT, $AMDAPPSDKROOT, and $CUDAROOT (or $CUDAPATH).

If they are defined, they can be used to set the required include and library paths, for example:

% echo $INTELOCLSDKROOT
/opt/intel/opencl-1.2-sdk-6.0.0.1049

% export CPU_INCLUDE_PATH=$INTELOCLSDKROOT/include
% export CPU_LIBRARY_PATH=$INTELOCLSDKROOT/lib/x64

% echo $AMDAPPSDKROOT
/opt/AMDAPPSDK-3.0

% export GPU_INCLUDE_PATH=$AMDAPPSDKROOT/include
% export GPU_LIBRARY_PATH=$AMDAPPSDKROOT/lib/x64_86

% echo $CUDAROOT
/usr/local/cuda-10.0

% export GPU_INCLUDE_PATH=$CUDAROOT/include
% export GPU_LIBRARY_PATH=$CUDAROOT/lib64

Usage

Basic command

./bin/autodock_<type>_<N>wi \
--ffile <protein>.maps.fld \
--lfile <ligand>.pdbqt \
--nrun <nruns>

Mandatory options		Description	Value
--ffile	-M	Protein file	<protein>.maps.fld
--lfile	-L	Ligand file	<ligand>.pdbqt

Both options can alternatively be provided in the contents of the files specified with --filelist (-B) (see below for format) and --import_dpf (-I) (AD4 dpf file format).

Supported arguments

Argument		Description	Default value
INPUT
--lfile	-L	Ligand pdbqt file	no default
--ffile	-M	Grid map files descriptor fld file	no default
--flexres	-F	Flexible residue pdbqt file	no default
--filelist	-B	Batch file	no default
--import_dpf	-I	Import AD4-type dpf input file (only partial support)	no default
--xraylfile	-R	reference ligand file for RMSD analysis	ligand file
CONVERSION
--xml2dlg	-X	One (or many) AD-GPU xml file(s) to convert to dlg(s)	no default
OUTPUT
--resnam	-N	Name for docking output log	ligand basename
--contact_analysis	-C	Perform distance-based analysis (description below)	0 (no)
--xmloutput	-x	Specify if xml output format is wanted	1 (yes)
--dlgoutput	-d	Control if dlg output is created	1 (yes)
--dlg2stdout	-2	Write dlg file output to stdout (if not OVERLAP=ON)	0 (no)
--rlige		Print reference ligand energies	0 (no)
--gfpop		Output all poses from all populations of each LGA run	0 (no)
--npdb		# pose pdbqt files from populations of each LGA run	0
--gbest		Output single best pose as pdbqt file	0 (no)
--clustering		Output clustering analysis in dlg and/or xml file	1 (yes)
--hsym		Handle symmetry in RMSD calc.	1 (yes)
--rmstol		RMSD clustering tolerance	2 (Å)
SETUP
--devnum	-D	OpenCL/Cuda device number (counting starts at 1)	1
--loadxml	-c	Load initial population from xml results file	no default
--seed	-s	Random number seeds (up to three comma-sep. integers)	time, process id
SEARCH
--heuristics	-H	Ligand-based automatic search method and # evals	1 (yes)
--heurmax	-E	Asymptotic heuristics # evals limit (smooth limit)	12000000
--autostop	-A	Automatic stopping criterion based on convergence	1 (yes)
--asfreq	-a	AutoStop testing frequency (in # of generations)	5
--nrun	-n	# LGA runs	20
--nev	-e	# Score evaluations (max.) per LGA run	2500000
--ngen	-g	# Generations (max.) per LGA run	42000
--lsmet	-l	Local-search method	ad (ADADELTA)
--lsit	-i	# Local-search iterations (max.)	300
--psize	-p	Population size	150
--mrat		Mutation rate	2 (%)
--crat		Crossover rate	80 (%)
--lsrat		Local-search rate	100 (%)
--trat		Tournament (selection) rate	60 (%)
--dmov		Maximum LGA movement delta	6 (Å)
--dang		Maximum LGA angle delta	90 (°)
--rholb		Solis-Wets lower bound of rho parameter	0.01
--lsmov		Solis-Wets movement delta	2 (Å)
--lsang		Solis-Wets angle delta	75 (°)
--cslim		Solis-Wets cons. success/failure limit to adjust rho	4
--stopstd		AutoStop energy standard deviation tolerance	0.15 (kcal/mol)
--initswgens		Initial # generations of Solis-Wets instead of -lsmet	0 (no)
SCORING
--derivtype	-T	Derivative atom types (e.g. C1,C2,C3=C/S4=S/H5=HD)	no default
--modpair	-P	Modify vdW pair params (e.g. C1:S4,1.60,1.200,13,7)	no default
--ubmod	-u	Unbound model: 0 (bound), 1 (extended), 2 (compact)	0 (same as bound)
--smooth		Smoothing parameter for vdW interactions	0.5 (Å)
--elecmindist		Min. electrostatic potential distance (w/ dpf: 0.5 Å)	0.01 (Å)
--modqp		Use modified QASP from VirtualDrug or AD4 original	0 (no, use AD4)

Autostop is enabled by default since v1.4. The collective distribution of scores among all LGA populations is tested for convergence every <asfreq> generations, and docking is stopped if the top-scored poses exhibit a small variance. This avoids wasting computation after the best docking solutions have been found. The heuristics set the number of evaluations at a generously large number. They are a function of the number of rotatable bonds. It prevents unreasonably long dockings in cases where autostop fails to detect convergence. In our experience --heuristics 1 and --autostop 1 allow sufficient score evaluations for searching the energy landscape accurately. For molecules with many rotatable bonds (e.g. about 15 or more) it may be advisable to increase --heurmax.

When the heuristics is used and --nev <max evals> is provided as a command line argument it provides the (hard) upper # of evals limit to the value the heuristics suggests. Conversely, --heurmax is the rolling-off type asymptotic limit to the heuristic's # of evals formula and should only be changed with caution. The batch file is a text file containing the parameters to --ffile, --lfile, and --resnam each on an individual line. It is possible to only use one line to specify the Protein grid map file which means it will be used for all ligands. Here is an example:

./receptor1.maps.fld
./ligand1.pdbqt
Ligand 1
./receptor2.maps.fld
./ligand2.pdbqt
Ligand 2
./receptor3.maps.fld
./ligand3.pdbqt
Ligand 3

When the distance-based analysis is used (--contact_analysis 1 or --contact_analysis <R_cutoff>,<H_cutoff>,<V_cutoff>), the ligand poses of a given run (either after a docking run or even when --xml2dlg <xml file(s)> is used) are analyzed in terms of their individual atom distances to the target protein with individual cutoffs for:

• Reactive (default: 2.1 Å): These are interactions between modified atom types numbered 1, 4, or 7 (i.e. between C1 and S4)
• Hydrogen bonds (default: 3.7 Å): Interactions between Hydrogen-bond donor (closest N,O,S to an HD, or HD otherwise) and acceptor atom types (NA,NS,OA,OS,SA atom types).
• Van der Waals (default: 4.0 Å): All other interactions not fulfilling the above criteria.

The contact analysis results for each pose are output in dlg lines starting with ANALYSIS: and/or in <contact_analysis> blocks in xml file output.

Further reading

Go to Wiki home.