From f557d7fbd98513ad2a2d2143ff8a34d0af439ffb Mon Sep 17 00:00:00 2001 From: Saurabh Date: Tue, 3 Aug 2021 21:17:14 -0700 Subject: [PATCH] Updated README --- README.md | 64 ++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 44 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index b98a992..21459d7 100644 --- a/README.md +++ b/README.md @@ -2,42 +2,66 @@ ### Introduction mm2-fast is an accelerated implementation of minimap2 on modern CPUs. mm2-fast accelerates all three major modules of minimap2: Seeding, Chaining, and Alignment, achieving up to 3.5x speedup over minimap2. mm2-fast is a drop-in replacement of minimap2, providing the same functionality with the exact same output. -In the current version, all the modules are optimized using **AVX-512** vectorization. For **AVX2** systems, mm2-fast can be run with optimized seeding and AVX2 based vectorized alignment. The chaining module is not optimized for AVX2. The following table shows AVX2/AVX512 compatibility for three modules along with their default settings. +In the current version, all the modules are optimized using **AVX-512** vectorization. - +------------+------------+-----------------------------------+ - | AVX512 | AVX2 | Default settings | - +-----------+------------+------------+-----------------------------------+ - | Seeding | Yes | Yes | AVX512/AVX2: Disabled | - +-----------+------------+------------+-----------------------------------+ - | Chaining | Yes | No | AVX512: Enabled, AVX2: NA | - +-----------+------------+------------+-----------------------------------+ - | Alignment | Yes | Yes | AVX512: Enabled, AVX2: Disabled | - +-------------------------------------+-----------------------------------+ +### System requirement +Operating System: Linux +Compiler: G++/ICPC -- version +Architecture: AVX512 +Memory requirement: ~30GB for human genome -### Usage -```sh +### Installation +clone the fast-contrib branch from minimap2 github page. The source code can be compiled by simple using make command. +``` git clone --recursive https://github.com/lh3/minimap2.git -b fast-contrib mm2-fast cd mm2-fast +make +``` -# Compile and run mm2-fast (without seeding module optimizations). -make clean && make -./minimap2 -ax map-ont ref.fa ont.fq.gz > aln.sam +### Usage/Demo +The usage of mm2-fast is same as minimap2. Here is an example of mapping ONT reads with test data. +```sh +./minimap2 -ax map-ont test/MT-human.fa test/MT-orang.fa > mm2-fast_output +``` -# Compile and run mm2-fast (with all three optimized modules) +### Accuracy evaluation +As mm2-fast is an accelerated version of minimap2-v2.18, the output of mm2-fast can be verified against minimap2-v2.18. Note that, AVX512-based chaining in mm2-fast by default runs with a chaining parameter max-skip=infinity for higher chaining precision. Therefore, for correctness verification, minimap2 should run with a larger value of max\_skip parameter. Follow the below steps to verify the accuracy of mm2-fast. +```sh +git clone https://github.com/lh3/minimap2.git -b v2.18 +cd minimap2 && make +./minimap2 -ax test/MT-human.fa test/MT-orang.fa --max-chain-skip=1000000 > minimap2_output +``` +The output generated by minimap2 and mm2-fast should match. +```sh +diff minimap2_output mm2-fast_output > diff_result +``` +The file diff\_result should show a clean-diff with the difference of 2 lines, i.e., the lines containing the command-line parameters for minimap2 and mm2-fast. + +### Advanced options +The default compilation using make applies two optimizations: AVX512 vectorized chaining and alignment, and learned-indexes based seeding is disables by default as it requires aditional installations. Learned hash-table uses an external training library that runs on Rust. Following are the steps to enable learned hash table optimization in mm2-fast: +```sh +# Compile and run mm2-fast optimized seeding (all three optimized modules) 1. Build learned hash table index for optimized seeding module Pre-requisite: Install "Rust" and add path to .bashrc file. For Rust installation, visit https://rustup.rs/ - ./build_rmi.sh ref.fa map-ont ##takes two arguments: 1. path-to-reference-seq-file 2. preset + ./build_rmi.sh test/MT-human.fa map-ont ##takes two arguments: 1. path-to-reference-seq-file 2. preset 2. Compile and run make clean && make lhash=1 -./minimap2 -ax map-ont ref.fa ont.fq.gz > aln.sam - +./minimap2 -ax map-ont test/MT-human.fa test/MT-orang.fa > mm2-fast-lhash_output + # Compile with all optimizations disabled (runs as minimap2) make clean && make no_opt=1 -# Enable optimized seeding and AVX2 based alignment for AVX2 systems (By default, all optimizations are disabled for AVX2 systems) +# Enable optimized seeding and AVX2 based alignment for AVX2 systems (By default, all optimizations are disabled for AVX2 systems). Chaining step is not optimized for AVX2. make clean && make lhash=1 use_avx2=1 ``` + +### Future Plans +The current version of mm2-fast is based-on minimap2-v2.18. We are planning to apply our optimizations to minimap2 master branch. +### Citations +"Accelerating long-read analysis on modern CPs"; Saurabh Kalikar, Chirag Jain, Vasimuddin Md, Sanchit Misra; uploaded to bioRxiv - https://www.biorxiv.org/content/10.1101/2021.07.21.453294v1 + + The original README content of minimap2 follows. [![GitHub Downloads](https://img.shields.io/github/downloads/lh3/minimap2/total.svg?style=social&logo=github&label=Download)](https://github.com/lh3/minimap2/releases)