Skip to content

Commit 4edf9d5

Browse files
johanneskoesterjohanneskoester
committed
docs: metadata
1 parent c9605a9 commit 4edf9d5

File tree

4 files changed

+147
-142
lines changed

4 files changed

+147
-142
lines changed

‎README.md

+1-142
Original file line numberDiff line numberDiff line change
@@ -1,144 +1,3 @@
11
# Snakemake executor plugin: slurm
22

3-
[SLURM](https://slurm.schedmd.com/documentation.html) is a widely used
4-
batch system for performance compute clusters.
5-
6-
## Specifying Account and Partition
7-
8-
Most SLURM clusters have two mandatory resource indicators for
9-
accounting and scheduling, [Account]{.title-ref} and
10-
[Partition]{.title-ref}, respectivily. These resources are usually
11-
omitted from Snakemake workflows in order to keep the workflow
12-
definition independent from the platform. However, it is also possible
13-
to specify them inside of the workflow as resources in the rule
14-
definition (see `snakefiles-resources`{.interpreted-text role="ref"}).
15-
16-
To specify them at the command line, define them as default resources:
17-
18-
``` console
19-
$ snakemake --executor slurm --default-resources slurm_account=<your SLURM account> slurm_partition=<your SLURM partition>
20-
```
21-
22-
If individual rules require e.g. a different partition, you can override
23-
the default per rule:
24-
25-
``` console
26-
$ snakemake --slurm --default-resources slurm_account=<your SLURM account> slurm_partition=<your SLURM partition> --set-resources <somerule>:slurm_partition=<some other partition>
27-
```
28-
29-
Usually, it is advisable to persist such settings via a
30-
[configuration profile](https://snakemake.readthedocs.io/en/latest/executing/cli.html#profiles), which
31-
can be provided system-wide, per user, and in addition per workflow.
32-
33-
## Ordinary SMP jobs
34-
35-
Most jobs will be carried out by programs which are either single core
36-
scripts or threaded programs, hence SMP ([shared memory
37-
programs](https://en.wikipedia.org/wiki/Shared_memory)) in nature. Any
38-
given threads and `mem_mb` requirements will be passed to SLURM:
39-
40-
``` python
41-
rule a:
42-
input: ...
43-
output: ...
44-
threads: 8
45-
resources:
46-
mem_mb=14000
47-
```
48-
49-
This will give jobs from this rule 14GB of memory and 8 CPU cores. It is
50-
advisable to use resonable default resources, such that you don\'t need
51-
to specify them for every rule. Snakemake already has reasonable
52-
defaults built in, which are automatically activated when using any non-local executor
53-
(hence also with slurm).
54-
55-
## MPI jobs {#cluster-slurm-mpi}
56-
57-
Snakemake\'s Slurm backend also supports MPI jobs, see
58-
`snakefiles-mpi`{.interpreted-text role="ref"} for details. When using
59-
MPI with slurm, it is advisable to use `srun` as MPI starter.
60-
61-
``` python
62-
rule calc_pi:
63-
output:
64-
"pi.calc",
65-
log:
66-
"logs/calc_pi.log",
67-
resources:
68-
tasks=10,
69-
mpi="srun",
70-
shell:
71-
"{resources.mpi} -n {resources.tasks} calc-pi-mpi > {output} 2> {log}"
72-
```
73-
74-
Note that the `-n {resources.tasks}` is not necessary in case of SLURM,
75-
but it should be kept in order to allow execution of the workflow on
76-
other systems, e.g. by replacing `srun` with `mpiexec`:
77-
78-
``` console
79-
$ snakemake --set-resources calc_pi:mpi="mpiexec" ...
80-
```
81-
82-
## Advanced Resource Specifications
83-
84-
A workflow rule may support a number of
85-
[resource specifications](https://snakemake.readthedocs.io/en/latest/snakefiles/rules.html#resources).
86-
For a SLURM cluster, a mapping between Snakemake and SLURM needs to be performed.
87-
88-
You can use the following specifications:
89-
90-
| SLURM | Snakemake | Description |
91-
|----------------|------------|---------------------------------------|
92-
| `--partition` | `slurm_partition` | the partition a rule/job is to use |
93-
| `--time` | `runtime` | the walltime per job in minutes |
94-
| `--constraint` | `constraint` | may hold features on some clusters |
95-
| `--mem` | `mem`, `mem_mb` | memory a cluster node must |
96-
| | | provide (`mem`: string with unit), `mem_mb`: i |
97-
| `--mem-per-cpu` | `mem_mb_per_cpu` | memory per reserved CPU |
98-
| `--ntasks` | `tasks` | number of concurrent tasks / ranks |
99-
| `--cpus-per-task` | `cpus_per_task` | number of cpus per task (in case of SMP, rather use `threads`) |
100-
| `--nodes` | `nodes` | number of nodes |
101-
102-
Each of these can be part of a rule, e.g.:
103-
104-
``` python
105-
rule:
106-
input: ...
107-
output: ...
108-
resources:
109-
partition: <partition name>
110-
runtime: <some number>
111-
```
112-
113-
Please note: as `--mem` and `--mem-per-cpu` are mutually exclusive on
114-
SLURM clusters, their corresponding resource flags `mem`/`mem_mb` and
115-
`mem_mb_per_cpu` are mutually exclusive, too. You can only reserve
116-
memory a compute node has to provide or the memory required per CPU
117-
(SLURM does not make any distintion between real CPU cores and those
118-
provided by hyperthreads). SLURM will try to sastify a combination of
119-
`mem_mb_per_cpu` and `cpus_per_task` and `nodes`, if `nodes` is not
120-
given.
121-
122-
Note that it is usually advisable to avoid specifying SLURM (and compute
123-
infrastructure) specific resources (like `constraint`) inside of your
124-
workflow because that can limit the reproducibility on other systems.
125-
Consider using the `--default-resources` and `--set-resources` flags to specify such resources
126-
at the command line or (ideally) within a [profile](https://snakemake.readthedocs.io/en/latest/executing/cli.html#profiles).
127-
128-
## Additional custom job configuration
129-
130-
SLURM installations can support custom plugins, which may add support
131-
for additional flags to `sbatch`. In addition, there are various
132-
`sbatch` options not directly supported via the resource definitions
133-
shown above. You may use the `slurm_extra` resource to specify
134-
additional flags to `sbatch`:
135-
136-
``` python
137-
rule myrule:
138-
input: ...
139-
output: ...
140-
resources:
141-
slurm_extra="--qos=long --mail-type=ALL --mail-user=<your email>"
142-
```
143-
144-
Again, rather use a [profile](https://snakemake.readthedocs.io/en/latest/executing/cli.html#profiles) to specify such resources.
3+
For documentation, see the [Snakemake plugin catalog](https://snakemake.github.io/snakemake-plugin-catalog/plugins/executor/slurm.html).

‎docs/further.md

+139
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
## Specifying Account and Partition
2+
3+
Most SLURM clusters have two mandatory resource indicators for
4+
accounting and scheduling, [Account]{.title-ref} and
5+
[Partition]{.title-ref}, respectivily. These resources are usually
6+
omitted from Snakemake workflows in order to keep the workflow
7+
definition independent from the platform. However, it is also possible
8+
to specify them inside of the workflow as resources in the rule
9+
definition (see `snakefiles-resources`{.interpreted-text role="ref"}).
10+
11+
To specify them at the command line, define them as default resources:
12+
13+
``` console
14+
$ snakemake --executor slurm --default-resources slurm_account=<your SLURM account> slurm_partition=<your SLURM partition>
15+
```
16+
17+
If individual rules require e.g. a different partition, you can override
18+
the default per rule:
19+
20+
``` console
21+
$ snakemake --executor slurm --default-resources slurm_account=<your SLURM account> slurm_partition=<your SLURM partition> --set-resources <somerule>:slurm_partition=<some other partition>
22+
```
23+
24+
Usually, it is advisable to persist such settings via a
25+
[configuration profile](https://snakemake.readthedocs.io/en/latest/executing/cli.html#profiles), which
26+
can be provided system-wide, per user, and in addition per workflow.
27+
28+
## Ordinary SMP jobs
29+
30+
Most jobs will be carried out by programs which are either single core
31+
scripts or threaded programs, hence SMP ([shared memory
32+
programs](https://en.wikipedia.org/wiki/Shared_memory)) in nature. Any
33+
given threads and `mem_mb` requirements will be passed to SLURM:
34+
35+
``` python
36+
rule a:
37+
input: ...
38+
output: ...
39+
threads: 8
40+
resources:
41+
mem_mb=14000
42+
```
43+
44+
This will give jobs from this rule 14GB of memory and 8 CPU cores. It is
45+
advisable to use resonable default resources, such that you don\'t need
46+
to specify them for every rule. Snakemake already has reasonable
47+
defaults built in, which are automatically activated when using any non-local executor
48+
(hence also with slurm).
49+
50+
## MPI jobs {#cluster-slurm-mpi}
51+
52+
Snakemake\'s Slurm backend also supports MPI jobs, see
53+
`snakefiles-mpi`{.interpreted-text role="ref"} for details. When using
54+
MPI with slurm, it is advisable to use `srun` as MPI starter.
55+
56+
``` python
57+
rule calc_pi:
58+
output:
59+
"pi.calc",
60+
log:
61+
"logs/calc_pi.log",
62+
resources:
63+
tasks=10,
64+
mpi="srun",
65+
shell:
66+
"{resources.mpi} -n {resources.tasks} calc-pi-mpi > {output} 2> {log}"
67+
```
68+
69+
Note that the `-n {resources.tasks}` is not necessary in case of SLURM,
70+
but it should be kept in order to allow execution of the workflow on
71+
other systems, e.g. by replacing `srun` with `mpiexec`:
72+
73+
``` console
74+
$ snakemake --set-resources calc_pi:mpi="mpiexec" ...
75+
```
76+
77+
## Advanced Resource Specifications
78+
79+
A workflow rule may support a number of
80+
[resource specifications](https://snakemake.readthedocs.io/en/latest/snakefiles/rules.html#resources).
81+
For a SLURM cluster, a mapping between Snakemake and SLURM needs to be performed.
82+
83+
You can use the following specifications:
84+
85+
| SLURM | Snakemake | Description |
86+
|----------------|------------|---------------------------------------|
87+
| `--partition` | `slurm_partition` | the partition a rule/job is to use |
88+
| `--time` | `runtime` | the walltime per job in minutes |
89+
| `--constraint` | `constraint` | may hold features on some clusters |
90+
| `--mem` | `mem`, `mem_mb` | memory a cluster node must |
91+
| | | provide (`mem`: string with unit), `mem_mb`: i |
92+
| `--mem-per-cpu` | `mem_mb_per_cpu` | memory per reserved CPU |
93+
| `--ntasks` | `tasks` | number of concurrent tasks / ranks |
94+
| `--cpus-per-task` | `cpus_per_task` | number of cpus per task (in case of SMP, rather use `threads`) |
95+
| `--nodes` | `nodes` | number of nodes |
96+
97+
Each of these can be part of a rule, e.g.:
98+
99+
``` python
100+
rule:
101+
input: ...
102+
output: ...
103+
resources:
104+
partition: <partition name>
105+
runtime: <some number>
106+
```
107+
108+
Please note: as `--mem` and `--mem-per-cpu` are mutually exclusive on
109+
SLURM clusters, their corresponding resource flags `mem`/`mem_mb` and
110+
`mem_mb_per_cpu` are mutually exclusive, too. You can only reserve
111+
memory a compute node has to provide or the memory required per CPU
112+
(SLURM does not make any distintion between real CPU cores and those
113+
provided by hyperthreads). SLURM will try to sastify a combination of
114+
`mem_mb_per_cpu` and `cpus_per_task` and `nodes`, if `nodes` is not
115+
given.
116+
117+
Note that it is usually advisable to avoid specifying SLURM (and compute
118+
infrastructure) specific resources (like `constraint`) inside of your
119+
workflow because that can limit the reproducibility on other systems.
120+
Consider using the `--default-resources` and `--set-resources` flags to specify such resources
121+
at the command line or (ideally) within a [profile](https://snakemake.readthedocs.io/en/latest/executing/cli.html#profiles).
122+
123+
## Additional custom job configuration
124+
125+
SLURM installations can support custom plugins, which may add support
126+
for additional flags to `sbatch`. In addition, there are various
127+
`sbatch` options not directly supported via the resource definitions
128+
shown above. You may use the `slurm_extra` resource to specify
129+
additional flags to `sbatch`:
130+
131+
``` python
132+
rule myrule:
133+
input: ...
134+
output: ...
135+
resources:
136+
slurm_extra="--qos=long --mail-type=ALL --mail-user=<your email>"
137+
```
138+
139+
Again, rather use a [profile](https://snakemake.readthedocs.io/en/latest/executing/cli.html#profiles) to specify such resources.

‎docs/intro.md

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
[SLURM](https://slurm.schedmd.com/documentation.html) is a widely used
2+
batch system for performance compute clusters.
3+
This executor plugin allows to use it in a seamless and straightforward way.

‎pyproject.toml

+4
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,10 @@ authors = [
88
"Johannes Koester <[email protected]>",
99
]
1010
readme = "README.md"
11+
license = "MIT"
12+
repository = "https://github.com/snakemake/snakemake-executor-plugin-slurm"
13+
documentation = "https://snakemake.github.io/snakemake-plugin-catalog/plugins/executor/slurm.html"
14+
keywords = ["snakemake", "plugin", "executor", "cluster", "slurm"]
1115

1216
[tool.poetry.dependencies]
1317
python = "^3.11"

0 commit comments

Comments
 (0)