The scripts and files mentioned in this document can be obtained from the accompanying git repository, see http://anonscm.debian.org/gitweb/?p=pkg-boinc/scripts.git and follow the server-examples folder.

Update: We have now automated the preparation of BOINC servers for AutoDock Vina BOINC/Server/Projects/AutoDock. Those scripts are educational in their own right, we suggest following those instructions for first project.

1. BOINCed variant of the tutorial for running AutoDock on Debian and Ubuntu

We took a nice publicly available walk through for AutoDock and the MGLTools and modified that. There original is here which you may decide to walk through to increase your familiarity with the technology (biochemist or not). As you will see, that script was split in three sections. The first and last are left almost untouched. The middle one, i.e. the invocation of the tool, this is now modified for BOINC.

The idea is to provide help for a smaller group of researchers to obtain computing resources from the masses. Also it will help to bridge some amount of gap that exists between general public and the research group.

1.1. BOINC Application

The BOINCed application is designed by splitting the docker into three parts,

  1. Pre Docking preparation.
  2. Docking of each ligand.
  3. Post Docking Summarization

Corresponding scripts to each steps is in the git repository. Here, the Pre and Post steps need access to the full data, so computed in server. Whereas the docking part consists of isolated slots for each ligand. This, obviously is a perfect candidate to compute distributed.

The BOINC app by design should contain following files,

  1. Receptor Map files
  2. Ligand molecule description
  3. Docking parameter file.
  4. Autodock binary
  5. BOINC wrapper and job description file.

The application is designed using the BOINC/ServerGuide/WrapperApp framework. The static binary of autodock is used in the app.

Here, we present the steps to create such an application with boinc-server-maker and boinc-app-examples packages provided by Debian. The steps illustrated should work with any regular installtion of a BOINC server.

The following illustration assumes that reader have a working BOINC server project readily installed at his fingertips. How to get there is described at BOINC/ServerGuide.

1.1.1. Prepare the Biology

This step was not changed with respect to the original docker script. A few file locations have been modified. This just slightly adapted version of its "upper half" is kept here (download).

1.1.1.1. dock-pre.sh

The dock-pre expects all files needed in the working directory.

user@host: $ tree
.
|-- dock-pre.sh 
|-- ligands.mol2
|-- receptor.gpf
`-- receptor.pdbqt

0 directories, 4 files

On running,

  1. Perfomrs intial grid calcuation using autogrid
  2. Splits the ligand files
  3. Generates the parameter files.

user@host: $ tree
.
|-- dock-pre.sh 
|-- ligands
|   |-- receptor.A.map
|   |-- receptor.C.map
|   |-- receptor.d.map
|   |-- receptor.e.map
|   |-- receptor.HD.map
|   |-- receptor.maps.fld
|   |-- receptor.maps.xyz
|   |-- receptor.NA.map
|   |-- receptor.N.map
|   |-- receptor.OA.map
|   |-- receptor.pdbqt
|   |-- receptor.SA.map
|   |-- ZINC00034176.mol2
|   |-- ZINC00034176.pdbqt
|   |-- and MORE...
|   `-- ZINC01818227.pdbqt
|-- ligands.mol2
|-- receptor.A.map
|-- receptor.C.map
|-- receptor.d.map
|-- receptor.e.map
|-- receptor.glg
|-- receptor.gpf
|-- receptor.HD.map
|-- receptor.maps.fld
|-- receptor.maps.xyz
|-- receptor.NA.map
|-- receptor.N.map
|-- receptor.OA.map
|-- receptor.pdbqt
`-- receptor.SA.map

1.1.2. App Deployment

As the autodock binary is non native to BOINC, i.e. it does not know how to open files that BOINC provides at a central place or how to return results in a way that the BOINC client would understand it. We use a wrapper, as explained ?here to help bridging BOINC with AutoDock. The wrapper is responsible for invocation, running, and reporting of the actual task. The deployment of a generic wrapper is described at BOINC/ServerGuide/WrapperApp.

1.1.2.1. AutoDock

One can retrieve dynamically linked binaries of autodock again with the fetch-script that we have used before to retrieve the wrapper. It is however technically favorable to have static binaries. This way, one is less dependent on the version of the libc run at different sites. But those must be compiled manually for all platforms that shall not run in a virtualised environment. For the static version do

   apt-get source autodocktools
   cd autodocktools-*/autodock
   ./configure LDFLAGS=-static && make

1.1.2.2. Wrapper

The job description file is used to pass information on the work to the wrapper, it contains details about the binary to call, the arguments to apps, the outputs etc.

?AutoDockApp preforms docking, the corresponding command from docker.sh which the wrapper should be calling

autodock4 -p ligand_receptor.dpf -l result.dlg

The wrapper's job description file is named job.xml. It should be created and moved to the same directory as of wrapper binary.

cat <<EOFJOB > job.xml 
<job_desc>
  <task>
    <application>autodock</application>
     <append_cmdline_args/>
  </task>
</job_desc>
EOFJOB

Summarizing, ?AutoDockApp needs following files, Stage and sign them them inside the $projectroot/apps directory.

apps
|      
`-- wrapper
    `-- wrapper_6.12_i686-pc-linux-gnu
        |-- job.xml
        |-- autodock
        `-- wrapper_6.12_i686-pc-linux-gnu

and input files,
|-- receptor.A.map
|-- receptor.C.map
|-- receptor.d.map
|-- receptor.e.map
|-- receptor.HD.map
|-- receptor.maps.fld
|-- receptor.maps.xyz
|-- receptor.NA.map
|-- receptor.N.map
|-- receptor.OA.map
|-- receptor.SA.map
|-- ZINC00034176.pdbqt
`-- ZINC00034176_receptor.dpf

Also sign the binaries:

for f in apps/wrapper/*/; do
    name = $(basename $f)
    /path/to/sigh_executable $f /path/to/code_sign_private >> $name.sig
done

Do move all signature files same directory of the corresponding generating file, also note that input files dont need a signature.

Then add the information on applications to the project.xml file, update the database with new application included, add start the project.

bin/xadd && bin/update_versions
bin/start

1.1.3. Work Generation

The BOINC app should be fed with the work to perform, or in BOINC terminology a workunit. The workunit consists of input files and work and result definitions. These definitions are specified in an XML document called template. There are separate templates for the workunit (input) and the result (output). Even though the design of docking permits multiple ligands in a single workunit, Here we restrict each workunit to contain only one ligand. This reduces the complexity and also allows for considering less performant clients.

1.1.3.1. Workunit Templates

The workunit has to define the input files, which is specified in workunit template,

Please adjust that workunit template for your project. The majority of those files will be available after the invocation of autogrid.

The <sticky/> attribute specifies that the files are same among all workunits, so some bandwidth can be saved.

The result is obtained as a dlg file, which should be transported back. It is also specified using a template, called result template

1.1.3.2. dock-genwu.sh

The script used to generate work, dock-genwu.sh is assumed to be run inside the same directory as dock-pre.sh, The BOINC project variables should be edited insed the script to suite your setup.

Call it in

user@host : $ ./dock-genwu.sh <no-of-wu>

1.1.4. Step 4: Start BOINC clients

1.1.5. Step 5: Analyze results

Again, this step was not conceptionally changed, except for a few file locations have been modified. This just slightly adapted version of docker 's "lower half" is kept here.