# Run DRAGEN in Bench - Interactive

## Introduction

DRAGEN can run in [Bench](/project/p-bench.md) 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**](/reference/r-pricing.md#compute) (348GiB RAM) or [**hicpu-large**](/reference/r-pricing.md#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](/project/p-flow/f-pipelines.md#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](/project/p-flow/f-pipelines.md#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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.ica.illumina.com/project/p-bench/run-dragen-in-bench-interactive.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.