Skip to content

Commit 4a7e0d3

Browse files
rvhonoratorvhonorato
authored
add configuration reference to documentation (#183)
* add `reference.md` * update links * updates
1 parent 9574fb6 commit 4a7e0d3

3 files changed

Lines changed: 344 additions & 1 deletion

File tree

‎docs/src/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,5 @@
55
- [Usage](./usage.md)
66
- [Examples](./examples.md)
77
- [Setting up BM5](./setting-up-bm5.md)
8+
- [Configuration Reference](./reference.md)
89
- [Development](./development.md)

‎docs/src/reference.md‎

Lines changed: 342 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,342 @@
1+
# Configuration Reference
2+
3+
This document provides a comprehensive reference for the `haddock-runner` configuration YAML file format. It describes all available options, their purpose, valid values, and examples.
4+
5+
> Keep in mind that YAML format is indentation-sensitive!
6+
7+
## Configuration File Structure
8+
9+
The configuration file is a YAML document with two main sections:
10+
11+
```yaml
12+
general:
13+
# Global configuration options
14+
15+
scenarios:
16+
# Benchmark scenarios to execute
17+
```
18+
19+
---
20+
21+
## General Configuration
22+
23+
The `general` section contains global settings that apply to all scenarios and targets.
24+
25+
### Options
26+
27+
| Option | Type | Required | Description |
28+
|--------|------|----------|-------------|
29+
| `max_concurrent` | integer | Yes | Maximum number of jobs to run simultaneously. Controls how many target-scenario combinations execute in parallel. |
30+
| `ncores` | integer | Yes | Number of CPU cores to allocate per job. |
31+
| `execution` | string | Yes | Execution backend. Valid values: `local`, `slurm`. |
32+
| `mol_suffixes` | array of strings | Yes | File suffixes used to identify molecule files. Must contain at least 2 suffixes (typically receptor and ligand). |
33+
| `input_list` | string | Yes | Path to the input list file containing file paths for all targets. |
34+
| `work_dir` | string | Yes | Directory where benchmark results will be stored. Created automatically if it doesn't exist. |
35+
36+
### Example
37+
38+
```yaml
39+
general:
40+
max_concurrent: 4
41+
ncores: 2
42+
execution: local
43+
mol_suffixes: [_r_u, _l_u, _x_u]
44+
input_list: docking/input_list.txt
45+
work_dir: ./results
46+
```
47+
48+
### Notes
49+
50+
- **Local execution**: When using `execution: local`, the total number of CPU cores required is `max_concurrent * ncores`. Ensure your system has enough cores.
51+
- **SLURM execution**: When using `execution: slurm`, ensure SLURM is installed and configured. The `sbatch` and `sacct` commands must be available in your PATH.
52+
- **File suffixes**: The `mol_suffixes` array defines patterns used to identify molecule files in the input list. Files matching these patterns are grouped together as molecules for each target.
53+
54+
---
55+
56+
## Scenarios Configuration
57+
58+
The `scenarios` section defines the different docking workflows to test. Each scenario is executed for every target specified in the input list.
59+
60+
### Scenario Options
61+
62+
| Option | Type | Required | Description |
63+
|--------|------|----------|-------------|
64+
| `name` | string | Yes | Unique identifier for this scenario. Used as directory name in the results. |
65+
| `workflow` | mapping | Yes | HADDOCK3 workflow configuration defining modules and their parameters. |
66+
67+
### Example
68+
69+
```yaml
70+
scenarios:
71+
- name: true-interface
72+
workflow:
73+
topoaa:
74+
autohis: true
75+
rigidbody:
76+
sampling: 1000
77+
ambig_fname: _ti.tbl
78+
flexref:
79+
ambig_fname: _ti.tbl
80+
caprieval:
81+
reference_fname: _ref.pdb
82+
83+
- name: center-of-mass
84+
workflow:
85+
topoaa:
86+
autohis: true
87+
rigidbody:
88+
sampling: 500
89+
cmrest: true
90+
```
91+
92+
---
93+
94+
## Input List File Format
95+
96+
The input list file (specified by `general.input_list`) contains paths to all files required for each docking target. Files are automatically grouped into targets by a shared identifier derived from the filename: for molecule files, the identifier is the part of the filename before the configured `mol_suffixes` match; for restraints, topology/parameter, shape, and miscellaneous files, grouping typically uses the part before the first underscore.
97+
98+
### File Classification
99+
100+
Files in the input list are automatically categorized based on their extensions and patterns:
101+
102+
| File Type | Pattern | Description |
103+
|-----------|---------|-------------|
104+
| Molecules | Matches `mol_suffixes` patterns | Structure files (PDB format) |
105+
| Restraints | `_*.tbl` | Distance restraint files |
106+
| Topology/Parameters | `.top`, `.param` | Topology and parameter files for ligands |
107+
| Shape | `_shape*` or configured pattern | Shape files for shape-based docking |
108+
| Miscellaneous | All other files | Any additional files (reference structures, etc.) |
109+
110+
### Example Input List
111+
112+
```text
113+
# Target 1A2K - Protein-protein complex
114+
structures/1A2K/1A2K_r_u.pdb
115+
structures/1A2K/1A2K_l_u.pdb
116+
structures/1A2K/1A2K_ti.tbl
117+
structures/1A2K/1A2K_unambig.tbl
118+
structures/1A2K/1A2K_ref.pdb
119+
120+
# Target 1GGR - Another complex
121+
structures/1GGR/1GGR_r_u.pdb
122+
structures/1GGR/1GGR_l_u.pdb
123+
structures/1GGR/1GGR_ti.tbl
124+
```
125+
126+
### Notes
127+
128+
- Lines starting with `#` are treated as comments and ignored.
129+
- Empty lines are ignored.
130+
- Paths can be relative to the configuration file location or absolute.
131+
- Files are grouped by their root identifier which is extracted by splitting on underscore, taking the first part.
132+
133+
---
134+
135+
## HADDOCK3 Workflow Modules
136+
137+
The `workflow` section within each scenario defines the HADDOCK3 modules to execute and their parameters. Each module is specified as a YAML key, with its parameters as nested key-value pairs.
138+
139+
> IMPORTANT! You should not set any of haddock's "General Default Parameters" - these are handled by `haddock-runner` internally!
140+
141+
### Haddock Module Patterns
142+
143+
Look in the [haddock repository](https://github.com/haddocking/haddock3) for information about modules/parameters for each module.
144+
145+
### Module Parameter Patterns
146+
147+
Many parameters accept **filename patterns** instead of explicit paths. These patterns are matched against the files available for each target. The pattern matching uses regular expressions.
148+
149+
Common filename patterns:
150+
151+
| Pattern | Matches |
152+
|---------|---------|
153+
| `_ti.tbl` | Files ending with `_ti.tbl` |
154+
| `_unambig.tbl` | Files ending with `_unambig.tbl` |
155+
| `_ref.pdb` | Files ending with `_ref.pdb` |
156+
| `_ligand.top` | Files ending with `_ligand.top` |
157+
| `_ligand.param` | Files ending with `_ligand.param` |
158+
159+
**Note:** When using filename patterns, ensure the corresponding files are listed in the input list and have consistent naming conventions across all targets.
160+
161+
---
162+
163+
## Complete Configuration Examples
164+
165+
### Basic Benchmark
166+
167+
```yaml
168+
general:
169+
max_concurrent: 2
170+
ncores: 2
171+
execution: local
172+
mol_suffixes: [_r_u, _l_u]
173+
input_list: input_list.txt
174+
work_dir: ./results
175+
176+
scenarios:
177+
- name: standard
178+
workflow:
179+
topoaa:
180+
autohis: true
181+
rigidbody:
182+
sampling: 500
183+
flexref:
184+
emref:
185+
```
186+
187+
### Parameter Optimization with Shape Docking
188+
189+
```yaml
190+
general:
191+
max_concurrent: 4
192+
ncores: 4
193+
execution: slurm
194+
mol_suffixes: [_r_u, _l_u, _shape]
195+
input_list: shape/input.txt
196+
work_dir: shape-results
197+
198+
scenarios:
199+
- name: sampling-500
200+
workflow:
201+
topoaa:
202+
autohis: true
203+
rigidbody:
204+
sampling: 500
205+
mol_shape_3: true
206+
207+
- name: sampling-1000
208+
workflow:
209+
topoaa:
210+
autohis: true
211+
rigidbody:
212+
sampling: 1000
213+
mol_shape_3: true
214+
215+
- name: sampling-2000
216+
workflow:
217+
topoaa:
218+
autohis: true
219+
rigidbody:
220+
sampling: 2000
221+
mol_shape_3: true
222+
```
223+
224+
### Restraint Strategy Comparison
225+
226+
```yaml
227+
general:
228+
max_concurrent: 2
229+
ncores: 2
230+
execution: local
231+
mol_suffixes: [_r_u, _l_u]
232+
input_list: input_list.txt
233+
work_dir: restraint-comparison
234+
235+
scenarios:
236+
- name: true-interface
237+
workflow:
238+
topoaa:
239+
autohis: true
240+
rigidbody:
241+
sampling: 1000
242+
ambig_fname: _ti.tbl
243+
unambig_fname: _unambig.tbl
244+
flexref:
245+
ambig_fname: _ti.tbl
246+
caprieval:
247+
reference_fname: _ref.pdb
248+
249+
- name: center-of-mass
250+
workflow:
251+
topoaa:
252+
autohis: true
253+
rigidbody:
254+
sampling: 1000
255+
cmrest: true
256+
flexref:
257+
caprieval:
258+
reference_fname: _ref.pdb
259+
260+
- name: random-restart
261+
workflow:
262+
topoaa:
263+
autohis: true
264+
rigidbody:
265+
sampling: 1000
266+
ranair: true
267+
flexref:
268+
caprieval:
269+
reference_fname: _ref.pdb
270+
```
271+
272+
---
273+
274+
## Validation Rules
275+
276+
The configuration file is validated before execution. The following rules apply:
277+
278+
### General Section
279+
280+
1. **`mol_suffixes`**: Must be a non-empty array with at least 2 entries.
281+
2. **`mol_suffixes`**: Must contain unique values (no duplicates).
282+
3. **`work_dir`**: Must not be an empty string.
283+
4. **`input_list`**: Must not be an empty string, and the file must exist.
284+
5. **`max_concurrent`**: Must be greater than 0.
285+
6. **`ncores`**: Must be greater than 0.
286+
287+
### Local Execution
288+
289+
When `execution: local`:
290+
291+
- `max_concurrent * ncores` must not exceed the available CPU cores on the system.
292+
293+
### SLURM Execution
294+
295+
When `execution: slurm`:
296+
297+
- The `sbatch` and `sacct` commands must be available in the system PATH.
298+
299+
---
300+
301+
## File Resolution
302+
303+
### Path Resolution
304+
305+
- **Relative paths** in the configuration file (for `input_list` and `work_dir`) are resolved relative to the current working directory.
306+
307+
### Filename Pattern Resolution
308+
309+
When a module parameter ends with `_fname` and contains a pattern (e.g., `_ti.tbl`), the pattern is matched against all files available for the target. The matching is done using regular expressions.
310+
311+
**IMPORTANT: If multiple files match the pattern, the match is treated as ambiguous and the resolver returns `None`, so the parameter is omitted from the generated run TOML.**
312+
313+
---
314+
315+
## Directory Structure
316+
317+
After running a benchmark, results are organized as follows:
318+
319+
```text
320+
work_dir/
321+
├── scenario1/
322+
│ ├── target1/
323+
│ │ ├── run1/
324+
│ │ │ └── ... (HADDOCK3 output)
325+
│ │ └── job.sh (only for SLURM execution)
326+
│ └── target2/
327+
│ ├── run1/
328+
│ └── job.sh
329+
└── scenario2/
330+
├── target1/
331+
└── target2/
332+
```
333+
334+
---
335+
336+
## Tips for Configuration
337+
338+
1. **Start small**: Begin with a few targets and simple scenarios to validate your setup.
339+
2. **Use `--setup` mode**: Always run with `haddock-runner --setup configuration.yaml` first to validate the configuration before full execution.
340+
3. **Check file patterns**: Ensure your `mol_suffixes` patterns correctly match your molecule filenames.
341+
4. **Resource planning**: Calculate total CPU requirements as `max_concurrent * ncores` and ensure your system can handle it.
342+
5. **Consistent naming**: Use consistent file naming conventions across all targets for filename patterns to work correctly.

‎docs/src/usage.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,7 @@ scenarios:
102102
cmrest: true
103103
```
104104
105-
See [Writing a Benchmark YAML File](#step-3-write-the-benchmark-configuration) for complete configuration options.
105+
See [Configuration Reference](./reference.md) for complete configuration options.
106106
107107
### Step 4: Run the Benchmark
108108

0 commit comments

Comments
 (0)