Benchmark Client

Prepare HADDOCK3 benchmark configuration files and job scripts.

Creates HADDOCK3 configuration files and job files. Details on each parameter are explained in the -h menu.

There’s also a test flag that generates jobs only with topology creation. This feature helps testing the haddock3-dmn client.

The state of the jobs is identified by a file tag:

  • AVAILABLE

  • RUNNING

  • DONE

  • FAIL

At start, all jobs have the AVAILABLE tag, and this tag is upgraded as the job completes. To know which jobs are in each state, navigate to the <output dir> and search for the tags, for example:

find . -name AVAILABLE
find . -name RUNNING
find . -name DONE
find . -name FAIL

Jobs are identified as FAIL if there are messages in the stderr file.

Finally, a daemon job file is created to facilitate the usage of the daemon without directly using the haddock3-dmn client.

Usage:

haddock3-bm -h
haddock3-bm <BM dir> <output dir> [OPTIONS]
haddock3-bm <BM dir> <output dir> --workload-manager <option>
haddock3-bm <BM dir> <output dir> --workload-manager <option> -n <num cores>
haddock3-bm <BM dir> <output dir> --workload-manager <option> -n <num cores> -td
A BM folder is a folder with the characteristics of:

https://github.com/haddocking/BM5-clean

For more information read our benchmark tutorial at docs/benchmark.tut in HADDOCK3 repository site: https://github.com/haddocking/haddock3

haddock.clis.cli_bm.cli(ap: ArgumentParser, main: Callable[[...], None]) → None[source]

Command-line interface entry point.

haddock.clis.cli_bm.create_cfg_test_daemon(run_dir: str | Path, receptor_f: str | Path, ligand_f: str | Path, *ignore: Any, **everythinelse: Any) → str[source]

Create HADDOCK3 configuration file that only generates the topology.

This function is usefull to use test the benchmark daemon.

haddock.clis.cli_bm.create_cfg_ti(run_dir: str | Path, receptor_f: str | Path, ligand_f: str | Path, ambig_f: str | Path, target_f: str | Path) → str[source]

Create HADDOCK3 configuration file for the first scenario.

Parameters:

  • run_dir (path or str) – Path to the run directory; where run results will be saved.

  • receptor_f (Path or str) – Absolute path pointing to the receptor PDB file.

  • ligand_f (Path or str) – Absolute path pointing to the ligand PDB file.

  • ambig_f (Path or str) – Absolute path pointing to the ambig.tbl file.

Returns:

str – The HADDOCK3 configuration file for benchmarking.

haddock.clis.cli_bm.create_job(create_job_header: Callable[[...], str], create_job_body: Callable[[str | Path, str | Path, str | Path], str], create_job_tail: Callable[[str | Path, str | Path, str | Path], str], job_name_prefix: str, scenario_name: str, job_name_suffix: str, queue_name: str, ncores: int, work_dir: Path, run_dir: Path, config_file: str | Path) → str[source]

Create the job file.

The jobs is created by assembling three parts: the job header, the body, and the final tail (post execution process).

The different parameters will be injected in the respective job creation functions.

Parameters:

  • create_job_header (callable) – The function that will create the header.

  • create_job_body (callable) – The function that will create the job body.

  • create_job_tail (callable) – The function that will create the job tail.

  • job_name_prefix (str) – A prefix for the job name. Normally this is the name of the job test case, for example the PDB ID. Injected in create_job_header.

  • scenario_name (str) – The name of the benchmark scenario. Injected in create_job_header.

  • job_name_suffix (str) – An additional suffix for the job name. Normally, BM5. Injected in create_job_header.

  • queue_name (str) – The name of the queue. Injected in create_job_header.

  • ncores (int) – The number of cpu cores to use in the jobs. Injected in create_job_header.

  • work_dir (pathlib.Path) – The working dir of the example. That is, the directory where input, jobs, and logs reside. Injected in create_job_header.

  • run_dir (pathlib.Path) – The running directory of the scenario.

  • config_file (pathlib.Path) – Path to the scenario configuration file. Injected in create_job_body.

Returns:

str – The job file in the form of string.

haddock.clis.cli_bm.get_conda_path() → Path[source]

Get conda source path.

haddock.clis.cli_bm.load_args(ap: ArgumentParser) → Namespace[source]

Load argument parser args.

haddock.clis.cli_bm.main(benchmark_path: Path, output_path: str | Path, workload_manager: str = 'slurm', ncores: int = 48, queue_name: str = 'medium', test_daemon: bool = False, suffix: str = 'BM5') → None[source]

Create configuration and job scripts for HADDOCK3 benchmarking.

Developed for https://github.com/haddocking/BM5-clean

The parameters defined here are the same as defined in the client arguments.

This is the main function of the client. If you want to run the benchmark creation routine withOUT using the command line and instead importing its functionalities and setting it up from another pythong script, you should import this function.

>>> from haddock.clis.cli_bm import main
Parameters:

  • benchmark_path (Path) – The path to the benchmark models folder. In BM5-clean would be the ‘HADDOCK-ready’ folder.

  • output_path (Path) – Where the results will be saved. A subfolder for each model in benchmark_path will be created.

  • workload_manager (str) – A key for create_job_header_funcs dictionary. These relate to the queue managing software installed in your system. Examples are ‘slurm’ and ‘torque’.

  • ncores (int) – The number of CPUs to use in the created jobs.

  • queue_name (str) – The name of the queue where the jobs will be sent. This depends on your system configurations.

  • test_daemon (bool) – If True, generates short jobs where only the topology will be created. This facilitates testing the haddoc3 benchmark daemon.

  • suffix (str) – A common suffix for all jobs. Avoid using more than three chars.

haddock.clis.cli_bm.maincli() → None[source]

Execute main client.

haddock.clis.cli_bm.make_daemon_job(create_job_func: Callable[[...], str], workdir: str | Path, target_dir: str | Path, job_name: str = 'HD3-dmn', stdout_path: str | Path = 'daemon.out', stderr_path: str | Path = 'daemon.err', queue: str = 'short') → str[source]

Make a daemon-ready job.

haddock.clis.cli_bm.process_job_execution_status(stderr: str | Path, done_tag: str | Path, fail_tag: str | Path) → str[source]

Add execution status tail to job.

If job completes properly adds DONE, else adds FAIL.

Parameters:

  • done_tag (pathlib.Path) – Path where to generate the DONE file tag. Relative to the job header workdir.

  • fail_flag (pathlib.Path) – Path where to generate the FAIL file tag. Relative to the job header workdir.

haddock.clis.cli_bm.process_target(source_path: Path, result_path: str | Path, create_job_func: Callable[[...], str], scenarios: dict[str, Callable[..., str]]) → None[source]

Process each model example for benchmarking.

Parameters:

  • source_path (Path) – The folder path to the target.

  • result_path (Path) – The path where the results for the different scenarios will be saved.

  • create_job_func (callable) – A function to create the job script. This is an argument because there are several queue systems available. See create_job_header_funcs.

haddock.clis.cli_bm.setup_haddock3_job(available_flag: str | Path, running_flag: str | Path, conf_f: str | Path) → str[source]

Write body for the job script.

Parameters:

  • available_flag (pathlib.Path) – Path where to generate the AVAILABLE file tag. Relative to the job header workdir.

  • running_flag (pathlib.Path) – Path where to generate the RUNNING file tag. Relative to the job header workdir.

  • conf_f (Path or str) – Path to the configuration file. Relative to the job header workdir.

Returns:

str – The body of the job file.