update documentation about SLURM usage and customization (#207)

* update `usage.md`

* update reference.md

* update `setting-up-bm5.md`

Author: rvhonorato

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 <path>` 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.
 
 ---
 

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

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 <path>` 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: