HADDOCK3 benchmark tutorial
Developing HADDOCK3 requires handling thousands of parameters, either at the CNS level or the Python level. Therefore, unit-testing is sometimes not enough. To assess the correct functioning of HADDOCK3 we have assembled a benchmarking workflow where we dock well known and studied complexes and ensure the outcome matches expectations.
To run HADDOCK3 as a user, you don’t need to run this benchmark. But if you are an advanced user who has configured HADDOCK3 in your systems, you may wish to run the benchmark to make sure HADDOCK3 behaves as expected.
HADDOCK3 has two command-line clients that set up the benchmark workflow automatically. Let’s go through them step-by-step.
Obtaining the initial models
The Bonvin lab has manually curated a list of systems ideal for this benchmark. The repository is available here. Clone it to your machine with:
git clone https://github.com/haddocking/BM5-clean
If you inspect the new BM5-clean
folder, you will see the
HADDOCK-ready
folder has more than 200 sub-folders with “ready-to-use”
systems for HADDOCK.
Setting up the runs
Having HADDOCK3 installed, you can set up the runs with the following command:
# first, make a new folder where you want the runs to be stored
mkdir <folder-where-the-BM-jobs-will-be-created>
haddock3-bm BM5-clean/HADDOCK-ready <folder-where-the-BM-jobs-will-be-created> [OPTIONS]
[OPTIONS]
are optional :relaxed:. Look at the haddock3-bm -h
help
menu and select which ones better adapt to your system.
Running with the daemon
Running more than 200 HADDOCK jobs is time-consuming. Inspecting the queue system manually over several days is a pain. Therefore, we created a daemon that will handle the queue and submit the jobs for you. Use the command:
haddock3-dmn <folder-where-the-BM-jobs-were-created> [OPTIONS]
Use haddock3-dmn -h
to read all possible options.
From this point on, the daemon will manage the queue for you. You can also run the daemon as a job; please read further.
Initially, all jobs have a file named AVAILABLE
pointing that the jobs
are ready to run. Jobs that are sent to the queue get the file flag
RUNNING
. Completed jobs get the file flag DONE
, and failed jobs get
the file flag FAIL
.You can inspect which jobs are at which state with
the find
command:
find <folder-where-the-BM-jobs-were-created> -name DONE
You can count the number of folders with:
find <folder-where-the-BM-jobs-were-created> -name DONE | wc -l
Stopping the daemon
If you want to stop the daemon, press Ctrl+c
in the window where you
launch it. And manually cancel the remaining jobs. You can try the
following command:
qstat -a | awk '{print $4}' | grep BM5 | xargs scancel
BM5
comes because all jobs prepared for the benchmark have the BM5
tag in their job name (unless you defined otherwise in the [OPTIONS]
)
Further notes
As with any command-line tool, the haddock3-daemon will run as long as
the terminal window is open. However, we don’t recommend using the &
terminal detacher suffix command unless you know what you do.
Alternatively, you could use tmux
to
maintain the session running even when you disconnect from your login
node.
A better way can be to send the daemon job to some queue. You can easily
do that by using the daemon job created by the haddock3-bm
command.
What happens if you halt the daemon?
If you halt the daemon, you can restart the operations from where they left. Two scenarios are possible:
you also canceled running jobs
you let the running jobs finish properly
In the first scenario, you want the previously running jobs to restart. For that, run the command:
haddock3-dmn <new-folder-of-my-preference> --restart [OPTIONS]
Or you can update the hd3-daemon.job
file with the --restart
option.
In the second scenario, run the daemon as you would from scratch. Only
the jobs with the file flag AVAILABLE
will be executed.
Thanks for using HADDOCK3. Any feedback is very welcomed.
The HADDOCK team.