04_launch.qmd

---
title: "Launching an experiment"
engine: knitr
---

## 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:

```{groovy}
#| eval: false
#| file: experiment_repo/nf-nest/examples/hello.nf
```



## Local execution

Use the following command to run the nextflow script locally:

```{bash}
cd experiment_repo
./nextflow run nf-nest/examples/hello.nf
```


## 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](03_create-exp-repo.qmd#instructions).[^2] 

[^2]: In the previous section ("local execution"), where we did not 
      specify a `-profile`, the default profile named `standard` is 
      used.

Here is a minimal example:

```{bash echo = -1}
cd experiment_repo
./nextflow run nf-nest/examples/hello.nf -profile cluster 
```


## 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](https://tmuxcheatsheet.com/).


### 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.