From ba091954fad1fd357a6ea4d023d95908958b1a2b Mon Sep 17 00:00:00 2001 From: "Rodrigo V. Honorato" Date: Thu, 23 Jul 2026 15:32:30 +0200 Subject: [PATCH 1/3] update `usage.md` --- docs/src/usage.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/docs/src/usage.md b/docs/src/usage.md index f2c51c8..04ef044 100644 --- a/docs/src/usage.md +++ b/docs/src/usage.md @@ -104,6 +104,45 @@ scenarios: See [Configuration Reference](./reference.md) for complete configuration options. +### Step 3.1: Using SLURM + +Set `execution: slurm` in `general` to submit jobs via `sbatch` instead of running them locally. `sbatch` and `sacct` must be available in `PATH`. + +> IMPORTANT: `haddock-runner` expects to be executed in the LOGIN node. It will take care of the SLURM submission itself. Do not submit a job with `haddock-runner` to the queue. + +**Customizing the `#SBATCH` header**: use `slurm_header` to pass any `sbatch` long option as a YAML mapping: + +```yaml +general: + execution: slurm + ncores: 96 + slurm_header: + partition: small + nodes: 1 + account: project_XXXXXX + mem-per-cpu: 1500 + time: "24:00:00" + qos: standard + exclusive: true # renders as a bare `#SBATCH --exclusive` flag +``` + +- Keys must be recognized `sbatch` long-option names (e.g. `partition`, `nodes`, `account`, `time`, `qos`, `mem-per-cpu`); an unknown key fails validation. +- `cpus-per-task` is always derived from `ncores` and cannot be overridden here. +- `true` renders a bare flag (no value); `false`, `null`, or an empty string drops the entry and lets SLURM's own default apply. +- If `slurm_header` is omitted entirely, SLURM's cluster defaults are used — these vary by system. + +**Running setup commands before the job**: use `slurm_prologue` for shell commands (e.g. loading environment modules) that must run before haddock3 executes: + +```yaml +general: + slurm_prologue: | + module load some-module + module load another-module +``` + +- Do **not** add `cd ` or the `haddock3 ...` invocation yourself, those lines are always generated automatically and appended after your prologue. +- Because `slurm_prologue` can change the shell environment it might swap the version of `haddock3` you are using. There is an extra (automatic) check directly in the produced job script to double-check the version and avoid any surprises. + ### Step 4: Run the Benchmark Execute `haddock-runner` with your configuration: From b3ef373cefda726e23f93dbd38a9a97c6e5adc24 Mon Sep 17 00:00:00 2001 From: "Rodrigo V. Honorato" Date: Thu, 23 Jul 2026 15:35:17 +0200 Subject: [PATCH 2/3] update reference.md --- docs/src/reference.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/src/reference.md b/docs/src/reference.md index eb94798..ad98665 100644 --- a/docs/src/reference.md +++ b/docs/src/reference.md @@ -30,6 +30,8 @@ The `general` section contains global settings that apply to all scenarios and t | `ncores` | integer | Yes | Number of CPU cores to allocate per job. | | `execution` | string | Yes | Execution backend. Valid values: `local`, `slurm`. | | `partition` | string | No | SLURM partition to submit jobs to when `execution: slurm`. If omitted, the cluster default partition is used. | +| `slurm_header` | mapping | No | Arbitrary `#SBATCH` directives for `execution: slurm`, as `key: value` pairs using canonical `sbatch` long-option names (e.g. `partition`, `nodes`, `account`, `time`, `qos`, `mem-per-cpu`). `true` renders a bare flag (e.g. `exclusive: true` → `#SBATCH --exclusive`); `false`, `null`, or an empty string drops the entry. `cpus-per-task` is always derived from `ncores` and cannot be overridden. Unknown keys fail validation. | +| `slurm_prologue` | string | No | Shell commands (e.g. `module load ...`) run before the haddock3 execution line when `execution: slurm`. Do not include `cd ` or the `haddock3 ...` invocation — those are always generated automatically. When set, a version-check step is automatically added to the job script after the prologue to detect if it altered the haddock3 version in use. | | `mol_suffixes` | array of strings | Yes | File suffixes used to identify molecule files. Must contain at least 2 suffixes (typically receptor and ligand). | | `input_list` | string | Yes | Path to the input list file containing file paths for all targets. | | `work_dir` | string | Yes | Directory where benchmark results will be stored. Created automatically if it doesn't exist. | @@ -49,6 +51,29 @@ general: work_dir: ./results ``` +**SLURM example**, using `slurm_header` and `slurm_prologue`: + +```yaml +general: + max_concurrent: 4 + ncores: 96 + execution: slurm + slurm_header: + partition: small + nodes: 1 + account: project_XXXXXX + mem-per-cpu: 1500 + time: "24:00:00" + qos: standard + exclusive: true + slurm_prologue: | + module load some-module + module load another-module + mol_suffixes: [_r_u, _l_u, _x_u] + input_list: docking/input_list.txt + work_dir: ./results +``` + ### Notes - **Local execution**: When using `execution: local`, the total number of CPU cores required is `max_concurrent * ncores`. Ensure your system has enough cores. @@ -339,6 +364,7 @@ When `execution: local`: When `execution: slurm`: - The `sbatch` and `sacct` commands must be available in the system PATH. +- **`slurm_header`**: Keys must be recognized `sbatch` long-option names; an unknown key fails validation. `cpus-per-task` is always derived from `ncores` and cannot be overridden. --- From 1f46dd579ec35ff8b831d4ba8a2d92348495785b Mon Sep 17 00:00:00 2001 From: "Rodrigo V. Honorato" Date: Thu, 23 Jul 2026 15:35:25 +0200 Subject: [PATCH 3/3] update `setting-up-bm5.md` --- docs/src/setting-up-bm5.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/src/setting-up-bm5.md b/docs/src/setting-up-bm5.md index 214fe9d..8cd293c 100644 --- a/docs/src/setting-up-bm5.md +++ b/docs/src/setting-up-bm5.md @@ -165,9 +165,13 @@ For SLURM clusters, modify your config: general: execution: slurm ncores: 4 - partition: long + slurm_header: + partition: long + account: project_XXXXXX ``` +See [Step 3.1: Using SLURM](./usage.md#step-31-using-slurm) for the full `slurm_header`/`slurm_prologue` reference. + ## Step 6: Monitor and Manage the Benchmark ### Monitoring Progress