fork/minimap2
1
0
Fork 0
mirror of https://github.com/lh3/minimap2.git synced 2026-09-15 21:17:54 +08:00
Code Issues Packages Projects Releases Wiki Activity

Updated README

Browse Source
This commit is contained in:
Saurabh
2021-08-03 21:17:14 -07:00
committed by Heng Li
parent 4bc645c31d
commit f557d7fbd9
1 changed files with 44 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
README.md
View File

@@ -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)