Merge pull request #114 from reds-heig/doc_update_ripser_cpp

Doc update ripser.py

Author: sauln

.github/workflows/python-app.yml

@@ -51,7 +51,7 @@ jobs:
 
     steps:
       - uses: actions/checkout@v2
-      - uses: conda-incubator/setup-miniconda@v1
+      - uses: conda-incubator/setup-miniconda@v2
         with:
           auto-update-conda: true
           python-version: ${{ matrix.python-version }}
@@ -76,7 +76,7 @@ jobs:
 
     steps:
       - uses: actions/checkout@v2
-      - uses: conda-incubator/setup-miniconda@v1
+      - uses: conda-incubator/setup-miniconda@v2
         with:
           auto-update-conda: true
           python-version: ${{ matrix.python-version }}

README.md

@@ -55,6 +55,18 @@ pip install ripser
 
 If you are having trouble installing, please let us know!
 
+## Optional dependency
+
+Ripser.py when compiled from source can have a *steroid*<sup>1</sup> shot by replacing the standard `unordered_map` from the STL by one of the fastest implementation available: [robin_hood](https://github.com/martinus/robin-hood-hashing). Benchmarking of Ripser.py using the `robin_hood` implementation showed speed-ups up to **30%**.
+
+To be able to use `robin_hood` instead of STL, you only need to clone the repository containing the implementation:
+
+```
+# Run this command at the root of the project
+git clone https://github.com/martinus/robin-hood-hashing ripser/robinhood
+```
+
+<sup>1</sup> The Python package is already compiled with `robin_hood` by default.
 
 ## Usage
 

docs/index.rst

@@ -67,13 +67,49 @@ We also supply a Scikit-learn transformer style object if you would prefer to us
 .. image:: https://i.imgur.com/WmQPYnn.png
 
 
+Source Compilation
+---------------------
+
+In order to compile, you'll first need to do:
+
+.. code:: bash
+
+    git clone https://github.com/scikit-tda/ripser.py
+    cd ripser.py
+    pip install -e .
+
+You'll then be able to use Ripser.py as in the previous examples but compiled directly from sources.
+In order to obtain the best experience in performances when compiling from sources, you'll need an additional library, robin_hood_hashmap. To be able to use compile with this library enable, do:
+
+.. code:: bash
+
+    git clone https://github.com/martinus/robin-hood-hashing ripser/robinhood
+
+The following table shows a comparison of performances with and without robin_hood_hashmap:
+
++------------+--------+-------------+-------+---------+--------------+------------------+
+| Dataset    | size   | threshold   | dim   | coeff   | normal [s]   | robin_hood [s]   |
++============+========+=============+=======+=========+==============+==================+
+| sphere3    | 192    |             | 2     | 2       | 1.5          | 1.2              |
++------------+--------+-------------+-------+---------+--------------+------------------+
+| dragon     | 2000   |             | 1     | 2       | 2.9          | 2.5              |
++------------+--------+-------------+-------+---------+--------------+------------------+
+| o3         | 1024   | 1.8         | 3     | 2       | 2.9          | 2.2              |
++------------+--------+-------------+-------+---------+--------------+------------------+
+| random16   | 50     |             | 7     | 2       | 8.4          | 6.0              |
++------------+--------+-------------+-------+---------+--------------+------------------+
+| fractal    | 512    |             | 2     | 2       | 17.7         | 14               |
++------------+--------+-------------+-------+---------+--------------+------------------+
+| o3         | 4096   | 1.4         | 3     | 2       | 68.6         | 53.4             |
++------------+--------+-------------+-------+---------+--------------+------------------+
+
 Contributions
 ----------------
+
 We welcome contributions of all shapes and sizes. There are lots of opportunities for potential projects, so please get in touch if you would like to help out. Everything from an implementation of your favorite distance, notebooks, examples, and documentation are all equally valuable so please don’t feel you can’t contribute.
 
 To contribute please fork the project make your changes and submit a pull request. We will do our best to work through any issues with you and get your code merged into the main branch.
 
-
 Citing
 ----------