Skip to content

Commit 19e4294

Browse files
rvhonoratorvhonorato
committed
add reference.md 
1 parent 9574fb6 commit 19e4294

1 file changed

Lines changed: 343 additions & 0 deletions

File tree

‎docs/src/reference.md‎

Lines changed: 343 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,343 @@
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 based on their common root identifier, **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 configuration file's location.
306+
- **Relative paths** in the input list file are resolved relative to the input list file's location.
307+
308+
### Filename Pattern Resolution
309+
310+
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.
311+
312+
If multiple files match the pattern, the module parameter will receive all matching filenames. If no file matches, the parameter will be omitted or cause an error depending on the HADDOCK3 module requirements.
313+
314+
---
315+
316+
## Directory Structure
317+
318+
After running a benchmark, results are organized as follows:
319+
320+
```text
321+
work_dir/
322+
├── scenario1/
323+
│ ├── target1/
324+
│ │ ├── run1/
325+
│ │ │ └── ... (HADDOCK3 output)
326+
│ │ └── job.sh (only for SLURM execution)
327+
│ └── target2/
328+
│ ├── run1/
329+
│ └── job.sh
330+
└── scenario2/
331+
├── target1/
332+
└── target2/
333+
```
334+
335+
---
336+
337+
## Tips for Configuration
338+
339+
1. **Start small**: Begin with a few targets and simple scenarios to validate your setup.
340+
2. **Use `--setup` mode**: Always run with `haddock-runner --setup configuration.yaml` first to validate the configuration before full execution.
341+
3. **Check file patterns**: Ensure your `mol_suffixes` patterns correctly match your molecule filenames.
342+
4. **Resource planning**: Calculate total CPU requirements as `max_concurrent * ncores` and ensure your system can handle it.
343+
5. **Consistent naming**: Use consistent file naming conventions across all targets for filename patterns to work correctly.

0 commit comments

Comments
 (0)