diff --git a/README.md b/README.md index f259728..370081d 100644 --- a/README.md +++ b/README.md @@ -2,16 +2,16 @@ ### Introduction mm2-fast is an accelerated implementation of minimap2 on modern CPUs. mm2-fast accelerates all the three major modules of minimap2: (a) seeding, (b) chaining, and (c) pairwise alignment, achieving up to 1.9x speedup and 1.4x speed using AVX512 and AVX2 respectively 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. Detailed benchmark results are available in our [preprint](https://doi.org/10.1101/2021.07.21.453294). +In the current version, all the modules are optimized using **AVX-512** and **AVX2** vectorization. Detailed benchmark results are available in our [preprint](https://doi.org/10.1101/2021.07.21.453294). ### System requirement Operating System: Linux mm2-fast was tested using g++ (GCC) 9.2.0 and icpc version 19.1.3.304 -Architecture: x86\_64 CPUs with [AVX512](https://en.wikipedia.org/wiki/AVX-512) +Architecture: x86\_64 CPUs with [AVX512][AVX2](https://en.wikipedia.org/wiki/Advanced_Vector_Extensions) Memory requirement: ~30GB for human genome ### Installation -Clone the *fast-contrib-v2.22* branch from minimap2 github page. The source code can be compiled by simple using *make* command. It only takes a few seconds. +Clone the *fast-contrib-v2.22* branch from minimap2 github page. The source code can be compiled by using *make* command. It only takes a few seconds. ``` git clone --recursive https://github.com/lh3/minimap2.git -b fast-contrib-v2.22 mm2-fast cd mm2-fast @@ -25,7 +25,12 @@ The usage of mm2-fast is same as minimap2. Here is an example of mapping ONT rea ``` ### Accuracy evaluation -As mm2-fast is an accelerated version of minimap2-v2.22, the output of mm2-fast can be verified against minimap2-v2.22. Note that AVX512-based chaining in mm2-fast by default runs with a chaining parameter *max-chain-skip=infinity* for higher chaining precision. Therefore, for correctness verification, minimap2 should run with a larger value of *max-chain-skip* parameter. Follow the below steps to verify the accuracy of mm2-fast. +As mm2-fast is an accelerated version of minimap2-v2.22, the output of mm2-fast can be verified against minimap2-v2.22. Note that the optimized chaining in mm2-fast is strictly required to be run with a chaining parameter *max-chain-skip=infinity*. Note that having parameter *max-chain-skip=infinity* leads to higher chaining precision. Therefore, for correctness verification, minimap2 should run with a larger value of *max-chain-skip* parameter. Follow the below steps to verify the accuracy of mm2-fast. +```sh +git clone --recursive https://github.com/lh3/minimap2.git -b fast-contrib-v2.22 mm2-fast +cd mm2-fast && make +./minimap2 -ax map-ont test/MT-human.fa test/MT-orang.fa --max-chain-skip=1000000 > mm2-fast_output +``` ```sh git clone https://github.com/lh3/minimap2.git -b v2.22 cd minimap2 && make @@ -35,14 +40,14 @@ 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. +The file diff\_result should show a clean-diff with the difference of 0 lines. ### Advanced options -The default compilation using make applies two optimizations: AVX512 vectorized chaining and alignment, and learned-indexes based seeding is disabled by default as it requires availability of [Rust](https://en.wikipedia.org/wiki/Rust_(programming_language)). This is because the learned hash-table uses an external training library that runs on Rust. Rust is trivial to install, see https://rustup.rs/ and add its path to .bashrc file. Rust installation only takes a few seconds. Following are the steps to enable learned hash table optimization in mm2-fast: +The default compilation using make applies two optimizations: vectorized chaining and alignment. The learned-indexes based seeding is disabled by default as it requires availability of [Rust](https://en.wikipedia.org/wiki/Rust_(programming_language)). This is because the learned hash-table uses an external training library that runs on Rust. Rust is trivial to install, see https://rustup.rs/ and add its path to .bashrc file. Rust installation only takes a few seconds. Following are the steps to enable learned hash table optimization in mm2-fast: ```sh # Start by building learned hash table index for optimized seeding module ./build_rmi.sh test/MT-human.fa map-ont ##Takes two arguments: 1. path-to-reference-seq-file 2. preset. - ##For human genome, this step should take around 20-30 minutes to finish. + ##For human genome, this step should take around 2-3 minutes to finish. # Next, compile and run the mapping phase make clean && make lhash=1 diff --git a/build_rmi.sh b/build_rmi.sh index 396dbd4..e6a5734 100755 --- a/build_rmi.sh +++ b/build_rmi.sh @@ -9,7 +9,7 @@ kv_file=$1"_"$2"_minimizers_key_value_sorted" full_path=`readlink -f $kv_file` -cd ./ext/TAL_offline +cd ./ext/TAL make lisa_hash ./build-lisa-hash-index $full_path