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.
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,
- Pre Docking preparation.
- Docking of each ligand.
- 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,
- Receptor Map files
- Ligand molecule description
- Docking parameter file.
- Autodock binary
- 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
- install Debian packages: autodocktools autodock autogrid
follow the docker web tutorial for
follow the "upper half" of the docker script for preparing the receptor and the ligands for docking. It is suggested to really go through the script line by line and not to just execute it:
- split .mol2 ligand collection into many files
- name each correctly
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
- Perfomrs intial grid calcuation using autogrid
- Splits the ligand files
- 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.
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
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.
22.214.171.124. 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
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
- Start your own and address them to your project
- When this works, try persuading your peers to also run some work units
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.
- it is basically a single script to execute - but from the right location