An Introduction to RbowtieCuda
Franck RICHARD
2026-11-09
Source:vignettes/RbowtieCuda-Introduction.Rmd
RbowtieCuda-Introduction.RmdIntroduction
NVBIO is a library of reusable components developed by NVIDIA Corporation to accelerate bioinformatics applications using CUDA technology. Although specifically designed to harness the computational power of NVIDIA GPUs, many of its components are fully cross-platform and can be used in both host C++ and device CUDA code.
The purpose of NVBIO is twofold. It serves as a robust foundation for developing modern GPU-focused applications, ensuring that core computations delegated to the library automatically benefit from advances in GPU technology. At the same time, it provides valuable resources for designing novel bioinformatics algorithms tailored to massively parallel architectures.
In addition to its core components, NVBIO includes a suite of applications built on top of the library. Among these is nvBowtie, a re-engineered implementation of the widely recognized Bowtie2 short-read aligner 1. Unlike many prototypes, nvBowtie is built as an industrial-grade aligner, replicating most of Bowtie2’s original features while adding enhancements such as efficient support for direct BAM output, with future plans for CRAM support.
Performances
nvBowtie is designed to fully exploit the massive parallelism of modern GPUs, delivering significantly higher alignment throughput without compromising accuracy, or achieving even greater accuracy in the same amount of time. For example, its performance was compared to Bowtie2 using an Illumina HiSeq 2000 dataset (the first 10 million reads of ERR161544) and an IonProton dataset, applying both end-to-end and local alignment methods. The results demonstrate an impressive 99.98% agreement at high MAPQ scores. For comparison, Bowtie2 tests were performed using 20 CPU threads with default alignment settings.
knitr::include_graphics("benchmark-nvbowtie-speedup.png")
benchmark
RBowtieCuda
This package provides an R wrapper for nvBio/nvBowtie, offering user-friendly interfaces specifically designed for R users. To maximize efficiency, the indexing and alignment functions (nvBWT and nvBowtie) are implemented in C++ and seamlessly integrated into R using the system2 function. This integration is fully transparent to the user, ensuring that the package is easy to use while providing high-performance features optimized to take full advantage of your machine’s capabilities.
Additionally, an experimental implementation of the
Wavefront Alignment (WFA) method 2 is included and can be
accessed by using the --wfa parameter during execution.
Please note that this package requires an NVIDIA graphics card for proper functionality.
Additional Installation Instructions
For detailed installation steps, please refer to the INSTALL file included with the package.
RbowtieCuda is compatible with all Cuda versions greater than or equal to 10. A minimum of 16 GB of RAM is recommended for compiling the package.
An Example Workflow Using RbowtieCuda
Installation
To install the latest version of RbowtieCuda, ensure that you are running the most up-to-date version of R. As RbowtieCuda is part of the Bioconductor project, you can easily install it along with its dependencies by following these steps:
library(BiocManager)
BiocManager::install("RbowtieCuda")As with any other R package, you need to load RbowtieCuda each time before using it, like this:
## RbowtieCuda is distributed under the BSD 3-Clause License.
## Please read the LICENSE file carefully before use.
##
## Note:
## - Redistribution and use (source/binary, with/without modification) are permitted
## under certain conditions.
## - The name of NVIDIA CORPORATION and its contributors may not be used to endorse
## or promote derived products without written permission.
## - This software is provided "AS IS", without warranty of any kind.nvBWT : Building BWT Indices for Reference FASTA Files
nvBWT is an application developed as part of the NVBIO library, designed to perform BWT-based reference indexing for nvBowtie and potentially other FM-index-based applications. When provided with one or more FASTA files, nvBWT generates both the forward and reverse Burrows-Wheeler Transform (BWT), along with a 2-bit packed representation of the sequences. In addition, it produces several auxiliary indices to support efficient alignment and querying.
Example:
td <- tempdir()
fa_file <- system.file(package="RbowtieCuda", "extdata", "bt2", "refs", "lambda_virus.fa")
nvBWT(myinput=fa_file, output=file.path(td, "index"), options="")will generate the following files:
index.pac
index.rpac
index.bwt
index.rbwt
index.sa
index.rsa
index.ann
index.ambWarning: if you run the command in a directory that already contains these files, they will be deleted and new files will be generated.
nvBWT supports the following command options:
-v | --verbosity int (0-6) [5] // select the verbosity level
-m | --max-length int [inf] // clamp input length
-b | --byte-packing // output a byte-encoded .pac file
-w | --word-packing // output a word-encoded .wpac file (more efficient)
-c | --crc // compute CRCs
-d | --device // select a cuda devicenvBowtie Alignments:
nvBowtie is a GPU-accelerated re-engineering of Bowtie2, one of the most widely used short-read aligners. Completely rewritten from scratch, nvBowtie retains many of the key features of Bowtie2, though not all functionalities are replicated.
Designed to fully exploit the massive parallelism of modern GPUs, nvBowtie achieves significantly higher alignment throughput without sacrificing accuracy—or offers even greater accuracy within the same time frame. Despite its focus on performance, nvBowtie is carefully designed to align closely with Bowtie2 in terms of specificity and sensitivity, maintaining the same level of reliability for users.
To harness the computational power of modern processor architectures, nvBowtie re-implements the algorithms underlying Bowtie2 but adopts a fundamentally different approach. While Bowtie2 is optimized to process one read at a time—using multiple CPU threads to handle different reads simultaneously—nvBowtie operates on large batches of reads, treating their alignment as a pipeline. This pipeline consists of many relatively simple but highly parallel stages, each optimized for execution on GPUs. In several stages, the parallelism extends far beyond the read level, processing multiple candidate hits for each read simultaneously, enabling a much finer granularity of parallel computation.
New features :
We’ve introduced several new functions to nvBowtie. You can now
perform alignments using the WFA method by including the
--wfa (or --scoring wfa) parameter. The WFA method
requires a large amount of RAM on the graphics card. We therefore
recommend using an Nvidia card with 8GB or more. Please note that this
feature is still experimental; it currently supports only end-to-end
alignments and does not yet allow customization of scoring parameters.
By default, it uses the following scoring: match:0, mismatch:1,
gap_open:1 and gap_ext:1.
Additionally, the --cache-writes parameter activates the
asynchronous SAM writer for single-end alignments: output records are
formatted and written by a background thread while the GPU aligns the
next batches, giving a large speedup on sizeable outputs (about 100 MB
of extra host RAM are used by the queue). It is not recommended for
paired-end alignments and is ignored for BAM output. Pair it with
--batch-size 64: --batch-size caps the number
of reads per batch, in thousands of reads (minimum 16, default 1024);
smaller batches overlap the alignment and the writing much better than
the default.
Example :
Reads_1 and Reads_2 represent raw paired-end read files in FASTQ format. Using a nvBWT index, these reads are mapped to the reference genome by invoking nvBowtie. The resulting alignments are stored in a BAM file, with its file path specified by the output parameter.
read_1 <- system.file(package="RbowtieCuda", "extdata", "bt2", "reads", "reads_1.fastq")
read_2 <- system.file(package="RbowtieCuda", "extdata", "bt2", "reads", "reads_2.fastq")
nvBowtie(file.path(td, "index"), file.path(td, "my_result.bam"), options="", seq1=read_1, seq2=read_2)Indexing of bam files produced by nvBowtie
nvBowtie does not automatically generate the .bai index files that are typically associated with .bam files.
These index files are essential for visualizing .bam files in tools such as the Integrative Genomics Viewer (IGV).
Fortunately, this issue can be easily resolved using the Rsamtools package, which includes the required functionality. For example, if you have generated a file named results.bam, you can create the corresponding index file with a simple command.
You only need to run the following in R:
library(Rsamtools)
sortBam("results.bam", "results")
indexBam("results.bam")Options and Version of the nvBowtie Aligner
You can customize the alignment process by adjusting the available options, enabling you to optimize performance and accuracy according to your specific needs:
## [1] "options:"
## [1] "General:"
## [1] " --verbosity int [5] verbosity level"
## [1] " --upto | -u int [-1] maximum number of reads to process"
## [1] " --trim3 | -3 int [0] trim the first N bases of 3'"
## [1] " --trim5 | -5 int [0] trim the first N bases of 5'"
## [1] " --nofw [false] do not align the forward strand"
## [1] " --norc [false] do not align the reverse-complemented strand"
## [1] " --device int [0] select the given cuda device(s) (e.g. --device 0 --device 1 ...)"
## [1] " --file-ref [false] load reference from file"
## [1] " --server-ref [false] load reference from server"
## [1] " --phred33 [true] qualities are ASCII characters equal to Phred quality + 33"
## [1] " --phred64 [false] qualities are ASCII characters equal to Phred quality + 64"
## [1] " --solexa-quals [false] qualities are in the Solexa format"
## [1] " --rg-id string add the RG-ID field of the SAM output header"
## [1] " --rg string,val add an RG-TAG field of the SAM output header"
## [1] " --cache-writes bool [false] asynchronous SAM writer, single-end SAM output only (not recommended for paired-end, ignored for BAM)"
## [1] " --batch-size int [1024] maximum reads per batch, in thousands of reads (minimum 16)"
## [1] "Paired-End:"
## [1] " --ff [false] paired mates are forward-forward"
## [1] " --fr [true] paired mates are forward-reverse"
## [1] " --rf [false] paired mates are reverse-forwardd"
## [1] " --rr [false] paired mates are reverse-reverse"
## [1] " --minins | -I int [0] minimum insert length"
## [1] " --maxins | -X int [500] maximum insert length"
## [1] " --overlap [true] allow overlapping mates"
## [1] " --no-mixed [false] only report paired alignments"
## [1] " --ungapped-mates | -ug perform ungapped mate alignment"
## [1] " --opposite-myers [true] score opposite mates with the Myers bit-vector core (exact, faster)"
## [1] "Seeding:"
## [1] " --seed-len | -L int [22] seed lengths"
## [1] " --seed-freq | -i {G|L|S},x,y seed interval, as x + y*func(read-len) (G=log,L=linear,S=sqrt)"
## [1] " --max-hits int [100] maximum amount of seed hits"
## [1] " --max-reseed | -R int [2] number of reseeding rounds"
## [1] " --top bool [false] explore top seed entirely"
## [1] " --N bool [false] allow substitution in seed"
## [1] "Extension:"
## [1] " --mode {best,best-exact,all} [best] alignment mode\n"
## [1] " --all | -a [false] perform all-mapping (i.e. find and report all alignments)"
## [1] " --local [false] perform local alignment"
## [1] " --rand [true] randomized seed hit selection"
## [1] " --no-rand [false] do not randomize seed hit selection"
## [1] " --max-dist int [15] maximum edit distance"
## [1] " --max-effort-init int [15] initial maximum number of consecutive extension failures"
## [1] " --max-effort | -D int [15] maximum number of consecutive extension failures"
## [1] " --min-ext int [30] minimum number of extensions per read"
## [1] " --max-ext int [400] maximum number of extensions per read"
## [1] " --very-fast apply the very-fast presets"
## [1] " --fast apply the fast presets"
## [1] " --sensitive apply the sensitive presets"
## [1] " --very-sensitive apply the very-sensitive presets"
## [1] " --very-fast-local apply the very-fast presets"
## [1] " --fast-local apply the fast presets"
## [1] " --sensitive-local apply the sensitive presets"
## [1] " --very-sensitive-local apply the very-sensitive presets"
## [1] "Scoring:"
## [1] " --scoring {sw|ed|wfa} [ed] Smith-Waterman / Edit-Distance / Wfa scoring"
## [1] " --score-min {G|L|S},x,y minimum score function, as x + y*func(read-len)"
## [1] " --ma int match bonus"
## [1] " --mp int,int mismatch min/max penalties"
## [1] " --np int N penalty"
## [1] " --rdg int,int read open/extension gap penalties"
## [1] " --rfg int,int reference open/extension gap penalties"
## [1] "Alternative:"
## [1] " --wfa Activate wavefront algorithm"
## [1] "Reporting:"
## [1] " --mapQ-filter | -Q int [0] minimum mapQ threshold"
## [1] ""
## [1] ""
## [1] "Default values are indicated in brackets []."
## [1] ""
## [1] "The '--scoring-scheme filename' option allows to provide a custom Smith-Waterman scoring"
## [1] "scheme through a text file, where each line must contain a token value pair."
## [1] " The tokens and default values are reported below:"
## [1] "* match 0 // local alignment: 2"
## [1] "* mm-penalty-min 2"
## [1] "* mm-penalty-max 6"
## [1] "* N-penalty-min 1"
## [1] "* N-penalty-max 1"
## [1] "* score-min-const -0.6 // local alignment: 0"
## [1] "* score-min-coeff -0.6 // local alignment: 10"
## [1] "* score-min-type linear // local alignment: log"
## [1] "* N-ceil-const 0"
## [1] "* N-ceil-coeff 0.15"
## [1] "* read-gap-const 5"
## [1] "* read-gap-coeff 3"
## [1] "* ref-gap-const 5"
## [1] "* ref-gap-coeff 3"
## [1] "* gap-free 5"You can execute unit tests for the program using the following commands or tools, ensuring its functionality and correctness:
## [1] "nvbio test passed."And you can obtain version information by executing the following command:
Session Information
## R version 4.6.1 (2026-06-24)
## Platform: x86_64-pc-linux-gnu
## Running under: Ubuntu 26.10
##
## Matrix products: default
## BLAS: /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3
## LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.33.so; LAPACK version 3.12.0
##
## locale:
## [1] LC_CTYPE=fr_FR.UTF-8 LC_NUMERIC=C
## [3] LC_TIME=es_ES.UTF-8 LC_COLLATE=fr_FR.UTF-8
## [5] LC_MONETARY=es_ES.UTF-8 LC_MESSAGES=fr_FR.UTF-8
## [7] LC_PAPER=es_ES.UTF-8 LC_NAME=C
## [9] LC_ADDRESS=C LC_TELEPHONE=C
## [11] LC_MEASUREMENT=es_ES.UTF-8 LC_IDENTIFICATION=C
##
## time zone: Europe/Madrid
## tzcode source: system (glibc)
##
## attached base packages:
## [1] stats graphics grDevices utils datasets methods base
##
## other attached packages:
## [1] RbowtieCuda_1.4.6
##
## loaded via a namespace (and not attached):
## [1] digest_0.6.39 desc_1.4.3 R6_2.6.1 fastmap_1.2.0
## [5] xfun_0.62 cachem_1.1.0 knitr_1.52 htmltools_0.5.9
## [9] rmarkdown_2.32 lifecycle_1.0.5 cli_3.6.6 sass_0.4.10
## [13] pkgdown_2.2.1 textshaping_1.0.5 jquerylib_0.1.4 systemfonts_1.3.2
## [17] compiler_4.6.1 rstudioapi_0.19.0 tools_4.6.1 ragg_1.5.2
## [21] bslib_0.12.0 evaluate_1.0.5 yaml_2.3.12 otel_0.2.0
## [25] jsonlite_2.0.0 htmlwidgets_1.6.4 rlang_1.3.0 fs_2.1.0Acknowledgement
We would like to thank Ismael Galve Roperh for his assistance.
Dedicated to the memory of Lilit Tabirian.
News
-
2026-11-03 RbowtieCuda version 1.4.6
- nvbio (host banded affine alignment): the score reported for a banded wavefront window is now the cost of the alignment that is actually emitted. The banded engines credit a cell with the wavefront it was reached on, and where the rows run out the traceback completes a tail up to that credit – a tail the wavefront never proved. Base by base, the emitted path then costs one gap-open (or one mismatch) more than the number advertised. Measured on the 20 real windows of nvbio-test: the 13 whose longest gap run is a single symbol were exact, and all 7 with a run of two symbols or more costed more than they advertised, always in that direction. On the host the window is now answered by the affine banded DP under the aligner’s own penalties, and both the score call and the traceback report the cost of the path the traceback emits, so a report that no alignment earns cannot pass. Device code is untouched, and keeps the per-window budgets the GPU needs.
- Known, still open upstream: the same defect sits in the direction encoding of the shared banded Gotoh traceback (a direction-continuation bit is stored on the cell next to the one it describes), so the device traceback and nvBowtie in banded Gotoh mode keep the one-event under-credit; only the host path is repaired here.
- Affine gap convention made explicit: a WFA engine charges a gap of L symbols as gap_open + L * gap_extension, where the nvbio DP family charges gap_open + (L-1) * gap_extension. The WfahScoreScheme adaptor bridges the two (gap_open_dp = gap_open + gap_extension); without it the banded DP and the wavefront disagreed by one extension per gap.
- nvbio-test: the banded WFA cases are self-checking. Each site now carries the expected score as well as the expected CIGAR, and the test compares the score, the CIGAR and the cost of the emitted path. 12 of the 15 banded sites moved to the score the banded semantics really produces – a start free along the text, anchored at the end of the pattern, the end of the text swept over the last row of the pattern – where the window anchored at both of its ends is kept by the corresponding full-length WFA case.
- Banded kernels: a prefetch no longer reads past the bound of its row in the banded Smith-Waterman and WFA kernels, and a window is no longer accepted when the text is shorter than the pattern.
-
2026-11-02 RbowtieCuda version 1.4.5
- nvBowtie: single-end SAM output is now produced by a dedicated background writer thread fed by a small ring buffer, so record formatting and disk writes overlap the GPU alignment of the next batches. Selected with –cache-writes (single-end SAM output). Combined with –batch-size 64 it divided the wall time of a 1M-read benchmark by about 3.7 (4.96 s -> 1.34 s on 1M x 10 bp reads against a 46 Mbp chromosome); –batch-size caps the reads per batch in thousands (min 16, default 1024) and is now documented in nvBowtie_usage().
- nvBowtie: much faster SAM record emission: the writer is buffered and hands a whole block of records to the disk with a single fwrite, instead of ~30 stdio calls per record.
- nvBowtie: WFA alignment (–wfa / –scoring wfa) is faster thanks to improved wavefront kernels, and its admissible-score cutoff now follows –max-dist: raising –max-dist in WFA mode now maps more reads, as it already did in edit-distance mode.
- nvBowtie: fixed a paired-end crash (cudaErrorInvalidValue during a host-to-device copy)introduced by the page-locked host buffers of version 1.4.4: page-lock registrations are now size-aware, so host buffers that grow are re-registered over their full span.
- The –cache-writes option is not recommended for paired-end alignments (the legacy path is kept) and is ignored for BAM output, with a warning; it costs a small ring buffer (~100 MB). The nvBowtie() wrapper now strips the flag itself in those two cases: a warning is issued for paired-end, a message for BAM output; single-end SAM output keeps the flag and its queue mode.
-
2026-10-07 RbowtieCuda version 1.4.4
- nvBowtie: faster paired-end opposite-mate scoring using a Myers bit-vector core, enabled by default; use –opposite-myers 0 to restore the previous algorithm. Alignment output is unchanged (bit-identical SAM records); the scoring stage is ~1.7x faster on GPU.
- CUDA architectures are auto-detected at build time (native code for the installed GPUs, with a PTX fallback), replacing the previously hard-coded target.
- Faster host/GPU transfers through page-locked buffers and stream-scoped synchronisation.
- Faster BWT occurrence-table construction on CPU.
-
2026-05-08 RbowtieCuda version 1.4.3
- Fix for an issue with the Thrust library
-
2026-04-10 RbowtieCuda version 1.0.11
- Installation modifications
-
2025-10-12 RbowtieCuda version 1.0.10
- Installation modifications
-
2025-09-25 RbowtieCuda version 1.0.9
- nvBowtie, nvBWT and nvbio_test propagate their error messages to the R interface
- Improved diagnostic messages during package installation
- Improved program stability
- Faster startup
- Compatible with CUDA 13.0
- The program needs 16 GB of RAM to be compiled (with Sys.setenv(MAKEFLAGS=“-j8”))
-
2025-04-17 RbowtieCuda version 1.0.1
- The package is available on Bioconductor
Credits
The main contributors of the original NVBIO are:
Jacopo Pantaleoni - jpantaleoni@nvidia.com
Nuno Subtil - nsubtil@nvidia.comRbowtieCuda developers:
Samuel Simon Sanchez - samsimon@ucm.es
Franck RICHARD - franck.richard@winstars.netThe maintainer of the RbowtieCuda package is Franck RICHARD