# Run DRAGEN in Bench - Interactive

## Introduction

DRAGEN can run in [Bench](https://help.ica.illumina.com/project/p-bench) workspaces

* In either **FPGA mode** (hardware-accelerated) or **software mode** when using **FPGA** instances. This can be useful when comparing performance gains by hardware acceleration or to distribute concurrent processes between the FPGA and cpu.
* In **software mode** when using **non-FPGA** instances.

{% hint style="info" %}
To run DRAGEN in software mode, you need to use the DRAGEN `--sw-mode` parameter.
{% endhint %}

The DRAGEN command line parameters to specify the location of the licence file are different.

* **FPGA** mode uses `LICENSE_PARAMS=``"--lic-instance-id-location /opt/dragen-licence/instance-identity.protected --lic-credentials /opt/dragen-licence/instance-identity.protected/dragen-creds.lic"`
* **Software** mode uses `LICENSE_PARAMS="--sw-mode --lic-credentials /opt/dragen-licence/instance-identity.protected/dragen-creds-sw-mode.lic"`

## DRAGEN Bench Images

DRAGEN software is provided in specific Bench images with names starting with `Dragen`. For example (available versions may vary):

* `Dragen 4.4.1 - Minimal` provides DRAGEN 4.4.1 and SSH access
* `Dragen 4.4.6` provides DRAGEN 4.4.6, SSH and JupyterLab.

### Prerequisites

#### Memory

The instance type is selected during workspace creation (**Projects > your\_project > Bench > Workspaces**). The amount of RAM available on the instance is critical. **256GiB RAM** is a safe choice to run DRAGEN in production. **All FPGA2 instances offer 256GiB or more of RAM**.

When running in **Software mode**, use[ **himem-large**](https://help.ica.illumina.com/reference/r-pricing#compute) (348GiB RAM) or [**hicpu-large**](https://help.ica.illumina.com/reference/r-pricing#compute) (144 GiB RAM) to ensure enough RAM is available for your runs.

{% hint style="info" %}
During pipeline development, when typically using small amounts of data, you can try to scale down in instance types to save costs. You can start at hicpu-large and progressively use smaller instances, though you will need at least **standard-xlarge**.\
**If DRAGEN runs out of available memory, the system is rebooted**, losing your currently running commands and interface.

**DRAGEN version 4.4.6** and later verify if the system has at least **128GB** of memory available. If not enough memory is available, you will encounter an error stating that the *Available memory is less than the minimum system memory required 128GB.*\
This can be overridden with the command line parameter `dragen --min-memory 0`
{% endhint %}

## FPGA-mode

Using an fpga2-medium [instance type](https://help.ica.illumina.com/p-flow/f-pipelines#compute-types).

#### Example

{% code overflow="wrap" %}

```sh
mkdir /data/demo 
cd /data/demo 

# download ref 
wget --progress=dot:giga https://s3.amazonaws.com/stratus-documentation-us-east-1-public/dragen/reference/Homo_sapiens/hg38.fa -O hg38.fa 
# => 0.5min 

# Build ht-ref 
mkdir ref 
dragen --build-hash-table true --ht-reference hg38.fa --output-directory ref 
# => 6.5min 

# run DRAGEN mapper 
FASTQ=/opt/edico/self_test/reads/midsize_chrM.fastq.gz

# Next line is needed to resolve "run the requested pipeline with a pangenome reference, but a linear reference was provided" in DRAGEN (4.4.1 and others). Comment out when encountering unrecognised option '--validate-pangenome-reference=false'.
DRAGEN_VERSION_SPECIFIC_PARAMS="--validate-pangenome-reference=false" 

# License Parameters
LICENSE_PARAMS="--lic-instance-id-location /opt/dragen-licence/instance-identity.protected --lic-credentials /opt/dragen-licence/instance-identity.protected/dragen-creds.lic"

mkdir out
dragen -r ref --output-directory out --output-file-prefix out -1 $FASTQ --enable-variant-caller false --RGID x --RGSM y ${LICENSE_PARAMS} ${DRAGEN_VERSION_SPECIFIC_PARAMS} 
# => 1.5min (10 sec if fpga already programmed)
```

{% endcode %}

## Software-mode

Using a standard-xlarge [instance type](https://help.ica.illumina.com/p-flow/f-pipelines#compute-types).

Software mode is activated with the DRAGEN `--sw-mode` parameter.

#### Example

{% code overflow="wrap" %}

```sh
mkdir /data/demo 
cd /data/demo 

# download ref 
wget --progress=dot:giga https://s3.amazonaws.com/stratus-documentation-us-east-1-public/dragen/reference/Homo_sapiens/hg38.fa -O hg38.fa 
# => 0.5min 

# Build ht-ref 
mkdir ref 
dragen --build-hash-table true --ht-reference hg38.fa --output-directory ref 
# => 6.5min 

# run DRAGEN mapper 
FASTQ=/opt/edico/self_test/reads/midsize_chrM.fastq.gz

# Next line is needed to resolve "run the requested pipeline with a pangenome reference, but a linear reference was provided" in DRAGEN (4.4.1 and others). Comment out when encountering ERROR: unrecognised option '--validate-pangenome-reference=false'.
DRAGEN_VERSION_SPECIFIC_PARAMS="--validate-pangenome-reference=false"

# When using DRAGEN 4.4.6 and later, the line above should be extended with --min-memory 0 to skip the memory check.
DRAGEN_VERSION_SPECIFIC_PARAMS="--validate-pangenome-reference=false --min-memory 0" 

# License Parameters
LICENSE_PARAMS="--sw-mode --lic-credentials /opt/dragen-licence/instance-identity.protected/dragen-creds-sw-mode.lic" 

mkdir out 
dragen -r ref --output-directory out --output-file-prefix out -1 $FASTQ --enable-variant-caller false --RGID x --RGSM y ${LICENSE_PARAMS} ${DRAGEN_VERSION_SPECIFIC_PARAMS} 
# => 2min
```

{% endcode %}