README.md 5.55 KB
Newer Older
Leonardo Solis's avatar
Leonardo Solis committed
1 2
# Legacy Repository. Rebranded to AutoDock-GPU: https://github.com/ccsb-scripps/AutoDock-GPU

Leonardo Solis's avatar
Leonardo Solis committed
3
OCLADock - OpenCL Accelerated Molecular Docking
4
===============================================
Leonardo Solis's avatar
Leonardo Solis committed
5

Leonardo Solis's avatar
Leonardo Solis committed
6 7
An OpenCL implementation of AutoDock4 running a Lamarckian Genetic Algorithm.

Leonardo Solis's avatar
Leonardo Solis committed
8
<img src="logo.png" width="200">
9 10 11

# Features

Leonardo Solis's avatar
Leonardo Solis committed
12
* OpenCL-accelerated version of AutoDock 4.2 running a Lamarckian Genetic Algorithm (LGA)
Andreas Koch's avatar
Andreas Koch committed
13
* It leverages the LGA paralelism, as entities of multiple docking runs are computed simultaneously
Leonardo Solis's avatar
Leonardo Solis committed
14
* It targets platforms based on multi-core CPU and GPU accelerators
Leonardo Solis's avatar
Leonardo Solis committed
15
* Observed speedups of up to 4x (quad-core CPU) and 56x (GPU) over the original serial AutoDock 4.2 on CPU
16

Andreas Koch's avatar
Andreas Koch committed
17 18
# Easy Download

Leonardo Solis's avatar
Leonardo Solis committed
19
If you are not familiar with GitLab, the easiest way to download all of OCLADock (source code, prebuilt-binaries for Linux and Windows, sample input data) is to
Andreas Koch's avatar
Andreas Koch committed
20
use the Download icon (close to the top right of this webpage, just above the list of files) and use a familiar archive format (e.g., .zip) to fetch everything at once.
Andreas Koch's avatar
Andreas Koch committed
21

22 23 24
# Setup
## Requirements

Leonardo Solis's avatar
Leonardo Solis committed
25 26 27 28
| Architecture | Operating system                        |
|:------------:|:---------------------------------------:|
| Intel x86_64 | CentOS 6.7 & 6.8 / Ubuntu 14.04 & 16.04 |
| Intel x86_64 | Windows 7                               |
Leonardo Solis's avatar
Leonardo Solis committed
29

30
## Prerequisites
Leonardo Solis's avatar
Leonardo Solis committed
31

32 33 34 35
| Operating system | CPU                          | GPU                           |
|:----------------:|:----------------------------:|:-----------------------------:|
| Linux            | Intel SDK for OpenCL v1.2    | AMD APP SDK v3.0 / CUDA v8.0  |
| Windows          | Intel SDK for OpenCL 2016 R3 | AMD APP SDK v3.0              |
Leonardo Solis's avatar
Leonardo Solis committed
36

Leonardo Solis's avatar
Leonardo Solis committed
37
Other environments/configurations likely work as well, but are untested.
38

Andreas Koch's avatar
Andreas Koch committed
39 40
# Ready-to-run Executables

Andreas Koch's avatar
Andreas Koch committed
41
We provide ready-to-run executables for [Linux](prebuilt/linux) and [Windows](prebuilt/windows). 
Leonardo Solis's avatar
Leonardo Solis committed
42
These executables have been compiled with a fixed number of work-items (**_wi_**, basically the degree of parallel processing done). If you are not sure, 
Andreas Koch's avatar
Andreas Koch committed
43 44
you should start with the versions using 16 work-items on a quad-core CPU and 64 work-items for a GPU. These values gave the 
best performance on our target platforms. The best values for your CPU or GPU might be different.
Andreas Koch's avatar
Andreas Koch committed
45

46 47
# Compilation

Leonardo Solis's avatar
Leonardo Solis committed
48
You only need to do this if you want to target our sources to a different system or modify the code. This can be configured in the [Makefile](Makefile).
Andreas Koch's avatar
Andreas Koch committed
49

50 51
## Compilation on Linux
```zsh
Leonardo Solis's avatar
Leonardo Solis committed
52
make DEVICE=<TYPE> NUMWI=<NWI>
53
```
Leonardo Solis's avatar
Leonardo Solis committed
54

Leonardo Solis's avatar
Leonardo Solis committed
55 56 57 58
| Parameters | Description            | Values                         |
|:----------:|:----------------------:|:------------------------------:|
| `<TYPE>`   | Accelerator chosen     | `CPU`, `GPU`                   |
| `<NWI>`    | OpenCL work-group size | `16`, `32`, `64`, `128`, `256` |
Leonardo Solis's avatar
Leonardo Solis committed
59

60

Leonardo Solis's avatar
Leonardo Solis committed
61
After successful compilation, the host binary **ocladock_&lt;type&gt;_&lt;N&gt;wi** is placed under [bin](./bin).
62

Leonardo Solis's avatar
Leonardo Solis committed
63 64 65 66
| Binary-name portion | Description            | Values                         |
|:-------------------:|:----------------------:|:------------------------------:|
| **&lt;type&gt;**    | Accelerator chosen     | `cpu`, `gpu`                   |
| **&lt;N&gt;**       | OpenCL work-group size | `16`, `32`, `64`, `128`, `256` |
Leonardo Solis's avatar
Leonardo Solis committed
67

68 69 70

## Compilation on Windows

Leonardo Solis's avatar
Leonardo Solis committed
71
A Microsoft Visual Studio 2013 solution for two configurations **_ocladock-cpu-deb_** and **_ocladock-gpu-deb_** can be found in the [win](win/) folder.
72

73
# Usage
Leonardo Solis's avatar
Leonardo Solis committed
74

75
## Basic command
76
```zsh
77
./bin/ocladock_<type>_<N>wi -ffile <protein>.maps.fld -lfile <ligand>.pdbqt -nrun <nruns>
78
```
Leonardo Solis's avatar
Leonardo Solis committed
79

Leonardo Solis's avatar
Leonardo Solis committed
80 81
| Mandatory options | Description   | Value                     |
|:-----------------:|:-------------:|:-------------------------:|
Leonardo Solis's avatar
Leonardo Solis committed
82 83
| -ffile            |Protein file   |&lt;protein&gt;.maps.fld   |
| -lfile            |Ligand file    |&lt;ligand&gt;.pdbqt       |
Leonardo Solis's avatar
Leonardo Solis committed
84

85
## Example
86
```zsh
Leonardo Solis's avatar
Leonardo Solis committed
87
./bin/ocladock_gpu_64wi -ffile ./input/1stp/derived/1stp_protein.maps.fld -lfile ./input/1stp/derived/1stp_ligand.pdbqt -nrun 10
88
```
Leonardo Solis's avatar
Leonardo Solis committed
89
By default the output log file is written in the current working folder. Examples of output logs can be found under [examples/output](examples/output/).
Leonardo Solis's avatar
Leonardo Solis committed
90

91
## Supported arguments
Leonardo Solis's avatar
Leonardo Solis committed
92

Leonardo Solis's avatar
Leonardo Solis committed
93 94 95 96 97 98 99 100 101 102 103
| Argument | Description                      | Default value |
|:---------|:---------------------------------|--------------:|
| -nrun    | # Docking runs                   | 1             |
| -nev     | # Energy evaluations             | 2500000       |
| -ngen    | # Generations                    | 27000         |
| -lsit    | # Local-search iterations (max.) | 300           |
| -psize   | Population size                  | 150           |
| -mrat    | Mutation rate                    | 2 (%)         |
| -crat    | Crossover rate                   | 80 (%)        |
| -lsrat   | Local-search rate                | 6 (%)         |
| -trat    | Tournament rate                  | 60 (%)        |
Leonardo Solis's avatar
Leonardo Solis committed
104
| -resnam  | Name for docking output log      | _"docking"_   |
105
| -hsym    | Handle symmetry in RMSD calc.    | 1             |
106

Leonardo Solis's avatar
Leonardo Solis committed
107
For a complete list of available arguments and their default values, check: [getparameters.cpp](host/src/getparameters.cpp).
Leonardo Solis's avatar
Leonardo Solis committed
108

Leonardo Solis's avatar
Leonardo Solis committed
109 110 111
## Images
Prebuilt images are provided for [Linux](prebuilt/linux) and [Windows](prebuilt/windows).

112
# Documentation
113

Leonardo Solis's avatar
Leonardo Solis committed
114
For more details, go to the [Documentation](doc/readme/home.md).
115

Andreas Koch's avatar
Andreas Koch committed
116
# Bibliographic information for citing OCLADock
117 118

Leonardo Solis-Vasquez and Andreas Koch. 2017. A Performance and Energy Evaluation of OpenCL-accelerated Molecular Docking. In Proceedings of the 5th International Workshop on OpenCL (IWOCL 2017). ACM, New York, NY, USA, Article 3, 11 pages. DOI: https://doi.org/10.1145/3078155.3078167
119 120 121

# License

Leonardo Solis's avatar
Leonardo Solis committed
122
This project is licensed under the GNU GPLv2 - see the [LICENSE](LICENSE) file for details.