docs improvements

CMakeLists.txt

@@ -4,7 +4,7 @@
 cmake_minimum_required(VERSION 3.10.0)
 project(bwtzip-openmp)
 
-set(CMAKE_VERBOSE_MAKEFILE ON)
+#set(CMAKE_VERBOSE_MAKEFILE ON)
 
 # C++ Standard
 set(CMAKE_CXX_STANDARD 11)

README.md

@@ -1,8 +1,33 @@
 # Bwtzip OpenMP
-*A parallel version of the bwtzip project implemented through the OpenMP APIs*
+*A parallel version of the bwtzip project implemented by means of the OpenMP APIs*
+
+In this project the [bwtzip] lossless data compression library from Stephan T. Lavavej was extended by means of [OpenMP] APIs in order to build a faster parallel version of the library.
+Moreover, a performances analysis was conducted to show to obtained speedup.
 
 **NOTE:** This is neither an official version of the bwtzip project, nor an implementation intended to be distributed.
 
+## Speedup analysis
+
+Checkout the performed [speedup anlaysis](doc/speedup_analysis) made on the parallel versions of bwtzip
+
+- [pbwtzip speedup analysis](doc/speedup_analysis/pbwtzip_speedup_analysis.ipynb)
+- [pbwtzip2 speedup analysis](doc/speedup_analysis/pbwtzip2_speedup_analysis.ipynb)
+
+
+| pbwtzip | pbwtzip2 |  
+|:--------|:---------|
+| ![pbwtzip speedpup linechart](doc/assets/pbwtzip_speedup_linechart.png) | ![pbwtzip2 speedpup linechart](doc/assets/pbwtzip2_speedup_linechart.png) |
+| ![pbwtzip speedpup heatmap](doc/assets/pbwtzip_speedup_heatmap.png) | ![pbwtzip2 speedpup heatmap](doc/assets/pbwtzip2_speedup_heatmap.png) |
+
+
+## Documentation
+
+Checkout the [documentation](doc) to compile the project and run the speed up analysis!
+
+
+## Project presentation
+
+[Parallelization of bwtzip library - Project presentation]
 
 ## License
 
@@ -14,13 +39,17 @@ this project inherit the [GNU GPL] license.
 
 ## Source code
 
-A copy of the original, unmodified, source code archive downloaded from the bwtzip official page is located at `/bwtzip.zip` in this repository.
+A copy of the original source code archive which was downloaded from the bwtzip official page is located at `/bwtzip.zip` in this repository.
 
 ## Project context
 
 This project has been developed for the [Advanced Algorithms and Parallel Programming course]
-(A.Y. 2017/2018) at [Politecnico di Milano].
+(A.Y. 2018/2019) at [Politecnico di Milano].
+
 
+[bwtzip]: https://nuwen.net/bwtzip.html
+[OpenMP]: https://www.openmp.org/
+[Parallelization of bwtzip library - Project presentation]: https://docs.google.com/presentation/d/1_zPcOxDOrXDXwXZpeZrBO4OpaLsV2oqjUgEMrGyh-ko
 [GNU GPL]: LICENSE
 [Advanced Algorithms and Parallel Programming course]: https://www4.ceda.polimi.it/manifesti/manifesti/controller/ManifestoPublic.do?EVN_DETTAGLIO_RIGA_MANIFESTO=EVENTO&c_insegn=095946&aa=2017&k_cf=225&k_corso_la=481&ac_ins=0&k_indir=T2A&lang=EN&tipoCorso=ALL_TIPO_CORSO&semestre=2&codDescr=095946&idGruppo=3589&idRiga=216915&jaf_currentWFID=main
 [Politecnico di Milano]: https://www.polimi.it

doc/compile-project.md

@@ -19,12 +19,10 @@ $ chmod +x ./script/*
 $ ./script/build_debug.sh
 ```
 
-Manually:
+or, manually:
 
 ```bash
-$ mkdir cmake-build-debug
-
-$ cd cmake-build-debug
+$ mkdir cmake-build-debug && cd cmake-build-debug
 
 $ cmake -DCMAKE_BUILD_TYPE=Debug ..
 
@@ -41,15 +39,60 @@ $ chmod +x ./script/*
 $ ./script/build_release.sh
 ```
 
-Manually:
+or, manually:
 
 ```bash
-$ mkdir cmake-build-release
-
-$ cd cmake-build-release
+$ mkdir cmake-build-release && cd cmake-build-release
 
 $ cmake -DCMAKE_BUILD_TYPE=Release ..
 
 $ make -j4
 ```
 
+# Run tests
+
+```bash
+$ cd cmake-build-release
+
+$ ctest --verbose
+```
+
+## Test passing
+
+```
+ctest --verbose
+UpdateCTestConfiguration  from :/bwtzip-openmp/cmake-build-debug/DartConfiguration.tcl
+Parse Config file:/bwtzip-openmp/cmake-build-debug/DartConfiguration.tcl
+UpdateCTestConfiguration  from :/bwtzip-openmp/cmake-build-debug/DartConfiguration.tcl
+Parse Config file://bwtzip-openmp/cmake-build-debug/DartConfiguration.tcl
+Test project /bwtzip-openmp/cmake-build-debug
+Constructing a list of tests
+Done constructing a list of tests
+Updating test list for fixtures
+Added 0 tests to meet fixture requirements
+Checking test dependency graph...
+Checking test dependency graph end
+test 1
+    Start 1: tests
+
+1: Test command: /bwtzip-openmp/cmake-build-debug/tests
+1: Test timeout computed to be: 1500
+1: [TEST][pbwtzip]-------- Compressed file matches original file ---------
+1: [TEST][pbwtzip] Compressing ../test/data_sample.txt to ./pbwtzip_data_sample_compressed.bwtzip
+1: ./pbwtzip_data_sample_compressed.bwtzip,4.1.1,409600,11,1,6,1,1,2,0.0547315,0.533713,0.273296,0.137589,0.0073339,6.47994
+1: [TEST][pbwtzip] Decompressing ./pbwtzip_data_sample_compressed.bwtzip to ./pbwtzip_data_sample_decompressed.txt
+1: [TEST][pbwtzip] Testing match of original and decompressed file
+1: [TEST][pbwtzip2]-------- Compressed file matches original file ---------
+1: [TEST][pbwtzip2] Compressing ../test/data_sample.txt to ./pbwtzip2_data_sample_compressed.bwtzip
+1: ./pbwtzip2_data_sample_compressed.bwtzip,4.2,409600,10,1,6,2,1,0.0941392,0.683185,0.328479,0.01135,7.18643
+1: [TEST][pbwtzip2] Decompressing ./pbwtzip2_data_sample_compressed.bwtzip to ./pbwtzip2_data_sample_decompressed.txt
+1: [TEST][pbwtzip2] Testing match of original and decompressed file
+1: ===============================================================================
+1: All tests passed (2 assertions in 2 test cases)
+1: 
+1/1 Test #1: tests ............................   Passed   21.11 sec
+
+100% tests passed, 0 tests failed out of 1
+
+Total Test time (real) =  21.11 sec
+```

doc/speedup_analysis/pbwtzip2_speedup_analysis.ipynb

@@ -20,7 +20,7 @@
     "\n",
     "```python\n",
     "bwtCompress(data_chunk) {\n",
-    "    bwtfxn(data_chunk)      # F1: SuffixTree\n",
+    "    bwtfxn(data_chunk)      # F1: Burrows–Wheeler transform\n",
     "    mtf2(data_chunk)        # F2: Move-To-Front (MTF)\n",
     "    zleWheeler(data_chunk)  # F3: Wheeler Zero Length Encoder\n",
     "    arith(data_chunk)       # F4: Arithmetic Coding\n",