merge upstream/master into essential parts

5 files changed, 103 insertions, 71 deletions

diff --git a/src/common/doc/examples.h b/src/common/doc/examples.h
index c19b3444..474f8699 100644
--- a/src/common/doc/examples.h
+++ b/src/common/doc/examples.h
@@ -42,7 +42,7 @@
  * @example Persistence_representations/persistence_landscape.cpp
  * @example Tangential_complex/example_basic.cpp
  * @example Tangential_complex/example_with_perturb.cpp
- * @example Subsampling/example_custom_kernel.cpp
+ * @example Subsampling/example_custom_distance.cpp
  * @example Subsampling/example_choose_n_farthest_points.cpp
  * @example Subsampling/example_sparsify_point_set.cpp
  * @example Subsampling/example_pick_n_random_points.cpp
diff --git a/src/common/doc/header.html b/src/common/doc/header.html
index 99ab6bb7..9da20bbc 100644
--- a/src/common/doc/header.html
+++ b/src/common/doc/header.html
@@ -24,64 +24,65 @@ $extrastylesheet
 
 <!-- GUDHI website header BEGIN -->
 <div id="navigation" class="sticky">
-    <nav class="top-bar" role="navigation" data-topbar>
-      <ul class="title-area">
-        <li class="name">
-        <h1 class="show-for-small-only"><a href="" class="icon-tree"> GUDHI library</a></h1>
-      </li>
-         <!-- Remove the class "menu-icon" to get rid of menu icon. Take out "Menu" to just have icon alone -->
-        <li class="toggle-topbar menu-icon"><a href="#"><span>Navigation</span></a></li>
+  <nav class="top-bar" role="navigation" data-topbar>
+    <ul class="title-area">
+      <li class="name">
+      <h1 class="show-for-small-only"><a href="" class="icon-tree"> GUDHI library</a></h1>
+    </li>
+       <!-- Remove the class "menu-icon" to get rid of menu icon. Take out "Menu" to just have icon alone -->
+      <li class="toggle-topbar menu-icon"><a href="#"><span>Nav</span></a></li>
+    </ul>
+    <section class="top-bar-section">
+      <ul class="right">
+              <li class="divider"></li>
+              <li><a  href="/contact/">Contact</a></li>
       </ul>
-      <section class="top-bar-section">
-        <ul class="right">
-                <li class="divider"></li>
-                <li><a href="/contact/">Contact</a></li>
-        </ul>
-        <ul class="left">
-                <li><a href="/"> <img src="/assets/img/home.png" alt="&nbsp;&nbsp;GUDHI">&nbsp;&nbsp;GUDHI </a></li>
-                <li class="divider"></li>
-                <li class="has-dropdown">
-                  <a href="#">Project</a>
-                    <ul class="dropdown">
-                        <li><a href="/people/">People</a></li>
-                        <li><a href="/keepintouch/">Keep in touch</a></li>
-                        <li><a href="/partners/">Partners and Funding</a></li>
-                        <li><a href="/relatedprojects/">Related projects</a></li>
-                        <li><a href="/theyaretalkingaboutus/">They are talking about us</a></li>
-                        <li><a href="/inaction/">GUDHI in action</a></li>
-                    </ul>
-                </li>
-                <li class="divider"></li>
-                <li class="has-dropdown">
-                  <a href="#">Download</a>
-                    <ul class="dropdown">
-                        <li><a href="/licensing/">Licensing</a></li>
-                        <li><a href="https://github.com/GUDHI/gudhi-devel/releases/latest" target="_blank">Get the latest sources</a></li>
-                        <li><a href="/conda/">Conda package</a></li>
-                        <li><a href="/dockerfile/">Dockerfile</a></li>
-                    </ul>
-                </li>
-                <li class="divider"></li>
-                <li class="has-dropdown">
-                  <a href="#">Documentation</a>
-                    <ul class="dropdown">
-                        <li><a href="/introduction/">Introduction</a></li>
-                        <li><a href="https://gudhi.inria.fr/doc/latest/installation.html">C++ installation manual</a></li>
-                        <li><a href="https://gudhi.inria.fr/doc/latest/">C++ documentation</a></li>
-                        <li><a href="https://gudhi.inria.fr/python/latest/installation.html">Python installation manual</a></li>
-                        <li><a href="https://gudhi.inria.fr/python/latest/">Python documentation</a></li>
-                        <li><a href="/utils/">Utilities</a></li>
-                        <li><a href="/tutorials/">Tutorials</a></li>
-                    </ul>
-                </li>
-                <li class="divider"></li>
-                <li><a href="/interfaces/">Interfaces</a></li>
-                <li class="divider"></li>
-        </ul>
-      </section>
-    </nav>
-  </div><!-- /#navigation -->
-  <!-- GUDHI website header BEGIN -->
+      <ul class="left">
+              <li><a  href="/"> <img src="/assets/img/home.png" alt="  GUDHI">  GUDHI </a></li>
+              <li class="divider"></li>
+              <li class="has-dropdown">
+                <a  href="#">Project</a>
+                  <ul class="dropdown">
+                      <li><a  href="/people/">People</a></li>
+                      <li><a  href="/keepintouch/">Keep in touch</a></li>
+                      <li><a  href="/partners/">Partners and Funding</a></li>
+                      <li><a  href="/relatedprojects/">Related projects</a></li>
+                      <li><a  href="/theyaretalkingaboutus/">They are talking about us</a></li>
+                      <li><a  href="/inaction/">GUDHI in action</a></li>
+                  </ul>
+              </li>
+              <li class="divider"></li>
+              <li class="has-dropdown">
+                <a  href="#">Download</a>
+                  <ul class="dropdown">
+                      <li><a  href="/licensing/">Licensing</a></li>
+                      <li><a  href="https://github.com/GUDHI/gudhi-devel/releases/latest" target="_blank">Get the latest sources</a></li>
+                      <li><a  href="/conda/">Conda package</a></li>
+                      <li><a  href="https://pypi.org/project/gudhi/" target="_blank">Pip package</a></li>
+                      <li><a  href="/dockerfile/">Dockerfile</a></li>
+                  </ul>
+              </li>
+              <li class="divider"></li>
+              <li class="has-dropdown">
+                <a  href="#">Documentation</a>
+                  <ul class="dropdown">
+                      <li><a  href="/introduction/">Introduction</a></li>
+                      <li><a  href="/doc/latest/installation.html">C++ installation manual</a></li>
+                      <li><a  href="/doc/latest/">C++ documentation</a></li>
+                      <li><a  href="/python/latest/installation.html">Python installation manual</a></li>
+                      <li><a  href="/python/latest/">Python documentation</a></li>
+                      <li><a  href="/utils/">Utilities</a></li>
+                      <li><a  href="/tutorials/">Tutorials</a></li>
+                  </ul>
+              </li>
+              <li class="divider"></li>
+              <li><a  href="/interfaces/">Interfaces</a></li>
+              <li class="divider"></li>
+      </ul>
+    </section>
+  </nav>
+</div><!-- /#navigation -->
+<!-- GUDHI website header END -->
 
 <div id="top"><!-- do not remove this div, it is closed by doxygen! -->
 
diff --git a/src/common/doc/installation.h b/src/common/doc/installation.h
index ce2c5448..c2e63a24 100644
--- a/src/common/doc/installation.h
+++ b/src/common/doc/installation.h
@@ -6,7 +6,7 @@
  * 
  * \section compiling Compiling
  * The library uses c++14 and requires <a target="_blank" href="http://www.boost.org/">Boost</a>  &ge; 1.56.0
- * and <a target="_blank" href="https://www.cmake.org/">CMake</a> &ge; 3.1.
+ * and <a target="_blank" href="https://www.cmake.org/">CMake</a> &ge; 3.5.
  * It is a multi-platform library and compiles on Linux, Mac OSX and Visual Studio 2015.
  * 
  * \subsection utilities Utilities and examples
@@ -14,13 +14,13 @@
 \verbatim  cd /path-to-gudhi/
 mkdir build
 cd build/
-cmake ..
+cmake -DCMAKE_BUILD_TYPE=Release ..
 make \endverbatim
  * By default, examples are disabled. You can activate their compilation with
- * <a href="https://cmake.org/cmake/help/v3.0/manual/ccmake.1.html">ccmake</a> (on Linux and Mac OSX),
- * <a href="https://cmake.org/cmake/help/v3.0/manual/cmake-gui.1.html">cmake-gui</a> (on Windows) or by modifying the
+ * <a href="https://cmake.org/cmake/help/latest/manual/ccmake.1.html">ccmake</a> (on Linux and Mac OSX),
+ * <a href="https://cmake.org/cmake/help/latest/manual/cmake-gui.1.html">cmake-gui</a> (on Windows) or by modifying the
  * cmake command as follows :
-\verbatim  cmake -DWITH_GUDHI_EXAMPLE=ON ..
+\verbatim  cmake -DCMAKE_BUILD_TYPE=Release -DWITH_GUDHI_EXAMPLE=ON ..
 make \endverbatim
  * A list of utilities and examples is available <a href="examples.html">here</a>.
  * 
@@ -28,7 +28,7 @@ make \endverbatim
  * To install the library (headers and activated utilities), run the following command in a terminal:
  * \verbatim  make install \endverbatim
  * This action may require to be in the sudoer or administrator of the machine in function of the operating system and
- * of <a href="https://cmake.org/cmake/help/v3.0/variable/CMAKE_INSTALL_PREFIX.html">CMAKE_INSTALL_PREFIX</a>.
+ * of <a href="https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html">CMAKE_INSTALL_PREFIX</a>.
  *
  * \subsection testsuites Test suites
  * To test your build, run the following command in a terminal:
@@ -66,9 +66,9 @@ make doxygen
  * Some GUDHI modules (cf. \ref main_page "modules list"), and few examples require CGAL, a C++ library that provides
  * easy access to efficient and reliable geometric algorithms.
  *
- * \note There is no need to install CGAL, you can just <CODE>cmake . && make</CODE> CGAL (or even
- * <CODE>cmake -DCGAL_HEADER_ONLY=ON .</CODE>), thereafter you will be able to compile
- * GUDHI by calling <CODE>cmake -DCGAL_DIR=/your/path/to/CGAL-X.Y .. && make</CODE>
+ * \note There is no need to install CGAL, you can just <CODE>cmake -DCMAKE_BUILD_TYPE=Release . && make</CODE> CGAL
+ * (or even <CODE>cmake -DCMAKE_BUILD_TYPE=Release -DCGAL_HEADER_ONLY=ON .</CODE>), thereafter you will be able to
+ * compile GUDHI by calling <CODE>cmake -DCMAKE_BUILD_TYPE=Release -DCGAL_DIR=/your/path/to/CGAL-X.Y .. && make</CODE>
  * 
  * The procedure to install this library according to
  * your operating system is detailed here http://doc.cgal.org/latest/Manual/installation.html
@@ -113,8 +113,6 @@ make doxygen
  * Spatial_searching/example_spatial_searching.cpp</a>
  * \li <a href="_subsampling_2example_choose_n_farthest_points_8cpp-example.html">
  * Subsampling/example_choose_n_farthest_points.cpp</a>
- * \li <a href="_subsampling_2example_custom_kernel_8cpp-example.html">
- * Subsampling/example_custom_kernel.cpp</a>
  * \li <a href="_subsampling_2example_pick_n_random_points_8cpp-example.html">
  * Subsampling/example_pick_n_random_points.cpp</a>
  * \li <a href="_subsampling_2example_sparsify_point_set_8cpp-example.html">
@@ -153,8 +151,6 @@ make doxygen
  * Spatial_searching/example_spatial_searching.cpp</a>
  * \li <a href="_subsampling_2example_choose_n_farthest_points_8cpp-example.html">
  * Subsampling/example_choose_n_farthest_points.cpp</a>
- * \li <a href="_subsampling_2example_custom_kernel_8cpp-example.html">
- * Subsampling/example_custom_kernel.cpp</a>
  * \li <a href="_subsampling_2example_pick_n_random_points_8cpp-example.html">
  * Subsampling/example_pick_n_random_points.cpp</a>
  * \li <a href="_subsampling_2example_sparsify_point_set_8cpp-example.html">
diff --git a/src/common/doc/main_page.md b/src/common/doc/main_page.md
index a33d98cd..e19af537 100644
--- a/src/common/doc/main_page.md
+++ b/src/common/doc/main_page.md
@@ -217,6 +217,36 @@
  </tr>
 </table>
 
+### Edge collapse
+
+<table>
+  <tr>
+    <td width="35%" rowspan=2>
+      \image html "dominated_edge.png"
+    </td>
+    <td width="50%">
+    Edge collapse is able to reduce any flag filtration to a smaller flag filtration with the same persistence, using
+    only the 1-skeletons of a simplicial complex.
+    The reduction is exact and the persistence homology of the reduced sequence is identical to the persistence
+    homology of the input sequence. The resulting method is simple and extremely efficient.
+
+    Computation of edge collapse and persistent homology of a filtered flag complex via edge collapse as described in
+    \cite edgecollapsesocg2020.
+    </td>
+    <td width="15%">
+      <b>Author:</b> Siddharth Pritam<br>
+      <b>Introduced in:</b> GUDHI 3.3.0<br>
+      <b>Copyright:</b> MIT<br>
+      <b>Requires:</b> \ref eigen
+    </td>
+ </tr>
+ <tr>
+    <td colspan=2 height="25">
+    <b>User manual:</b> \ref edge_collapse
+    </td>
+ </tr>
+</table>
+
 ### Witness complex
 
 <table>
diff --git a/src/common/include/gudhi/graph_simplicial_complex.h b/src/common/include/gudhi/graph_simplicial_complex.h
index b8508697..da9dee7d 100644
--- a/src/common/include/gudhi/graph_simplicial_complex.h
+++ b/src/common/include/gudhi/graph_simplicial_complex.h
@@ -19,6 +19,9 @@
 #include <tuple>  // for std::tie
 
 namespace Gudhi {
+/** @file
+ * @brief Graph simplicial complex methods
+ */
 
 /* Edge tag for Boost PropertyGraph. */
 struct edge_filtration_t {
@@ -46,6 +49,8 @@ using Proximity_graph = typename boost::adjacency_list < boost::vecS, boost::vec
  * If points contains n elements, the proximity graph is the graph with n vertices, and an edge [u,v] iff the
  * distance function between points u and v is smaller than threshold.
  *
+ * \tparam SimplicialComplexForProximityGraph furnishes `Filtration_value` and `Vertex_handle` type definitions.
+ *
  * \tparam ForwardPointRange furnishes `.begin()` and `.end()` methods.
  *
  * \tparam Distance furnishes `operator()(const Point& p1, const Point& p2)`, where