Launching an experiment

Overview

We show how to launch an “experiment”, i.e., a nextflow script.

We cover two ways to launch an experiment:

  1. Local: where all processes (nodes in the workflow graph) run in the same machine.
  2. Cluster where each node in the graph can run in different machines in a cluster.

Method 1 is useful to run experiments on a laptop and for prototyping.

Surprisingly, thanks to nextflow, method 2 only involves adding the command line option -profile cluster. This is because nextflow takes care of generating submission scripts, transferring files and orchestring everything.

Example nextflow script

The nf-nest repo contains a small example nextflow script, which we will use to demonstrate the two ways to launch an experiment. Here is the script for reference:

workflow  {
    hello()
}

process hello {
    debug true 
    """
    echo Hello world!
    """
}

Local execution

Use the following command to run the nextflow script locally:

cd experiment_repo
./nextflow run nf-nest/examples/hello.nf
N E X T F L O W  ~  version 24.10.0
WARN: It appears you have never run this project before -- Option `-resume` is ignored
Launching `nf-nest/examples/hello.nf` [angry_northcutt] DSL2 - revision: 9d1a692a7e
[d4/dbd00f] Submitted process > hello
Hello world!

Cluster execution

To run on a cluster, add the argument -profile cluster which instructs nextflow to use the configs in section cluster { ... } of the file nextflow.config created in the setup instructions.1

Here is a minimal example:

./nextflow run nf-nest/examples/hello.nf -profile cluster 
N E X T F L O W  ~  version 24.10.0
Launching `nf-nest/examples/hello.nf` [wise_goldberg] DSL2 - revision: 9d1a692a7e
[d4/dbd00f] Cached process > hello
Hello world!

Managing long executions

When starting a job, the launching nextflow process needs to stay alive until the end of the last job. However, when the SSH connection is lost (e.g., you close your laptop), the nextflow process and hence child jobs will be killed. To avoid this, use screen or tmux which allows you to preserve a SSH session even if the SSH connection is closed.

Basic instructions to start a long job

  • Take note of which of the login nodes you are starting the job (e.g. in Sockeye, login01, login02 or login03).
  • List existing tmux sessions with tmux ls
  • Create one with tmux or join last one with tmux a
  • Start the nextflow.
  • To detach the tmux session ctrl-b followed by d

Look at the status after being disconnected

  • SSH in.
  • If you are in the wrong login node, use e.g., ssh login02 (follow 2FA instruction)
  • Reattach with tmux a

For more information on tmux, use this cheat sheet.

Cancelling a nextflow workflow

Press ctrl-c only once. This will instruct nextflow to clean up children jobs: killing running jobs, as well as cancelling queued jobs.

Footnotes

  1. In the previous section (“local execution”), where we did not specify a -profile, the default profile named standard is used.↩︎