Clément's remarks

git-svn-id: svn+ssh://scm.gforge.inria.fr/svnroot/gudhi/branches/relaxed-witness@1735 636b058d-ea47-450e-bf9e-a15bfbe3eedb

Former-commit-id: c3bc66a081a0bc73874246e1e12ab98c6bf2a53e

8 files changed, 43 insertions, 171 deletions

diff --git a/src/Witness_complex/doc/Witness_complex_doc.h b/src/Witness_complex/doc/Witness_complex_doc.h
index 4f3671e5..2831f107 100644
--- a/src/Witness_complex/doc/Witness_complex_doc.h
+++ b/src/Witness_complex/doc/Witness_complex_doc.h
@@ -17,7 +17,7 @@
 
    Even though often the set of landmarks \f$L\f$ is a subset of the set of witnesses \f$ W\f$, it is not a requirement for the current implementation.
 
-   The simplices are based on landmarks
+   Landmarks are the vertices of the simplicial complex
    and witnesses help to decide on which simplices are inserted via a predicate "is witnessed".
 
    De Silva and Carlsson in their paper \cite de2004topological differentiate **weak witnessing** and **strong witnessing**:
@@ -47,7 +47,13 @@
 
    The constructors take on the step 1, while the function 'create_complex' executes the steps 2 and 3.
 
-   \section witnessexamples Examples
+   \section witnessexample1 Example 1: Constructing weak relaxed witness complex from an off file
+
+   Let's start with a simple example, which reads an off point file and computes a weak witness complex.
+
+   \include Witness_complex/example_witness_complex_off.cpp
+
+   \section witnessexample2 Example2: Computing persistence using strong relaxed witness complex
 
    Here is an example of constructing a strong witness complex filtration and computing persistence on it:
 
diff --git a/src/Witness_complex/example/example_strong_witness_persistence.cpp b/src/Witness_complex/example/example_strong_witness_persistence.cpp
index f43cba52..a0563ee2 100644
--- a/src/Witness_complex/example/example_strong_witness_persistence.cpp
+++ b/src/Witness_complex/example/example_strong_witness_persistence.cpp
@@ -1,25 +1,3 @@
-/*    This file is part of the Gudhi Library. The Gudhi library 
- *    (Geometric Understanding in Higher Dimensions) is a generic C++ 
- *    library for computational topology.
- *
- *    Author(s):       Siargey Kachanovich
- *
- *    Copyright (C) 2016  INRIA (France)
- *
- *    This program is free software: you can redistribute it and/or modify
- *    it under the terms of the GNU General Public License as published by
- *    the Free Software Foundation, either version 3 of the License, or
- *    (at your option) any later version.
- *
- *    This program is distributed in the hope that it will be useful,
- *    but WITHOUT ANY WARRANTY; without even the implied warranty of
- *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- *    GNU General Public License for more details.
- *
- *    You should have received a copy of the GNU General Public License
- *    along with this program.  If not, see <http://www.gnu.org/licenses/>.
- */
-
 #include <gudhi/Simplex_tree.h>
 #include <gudhi/Strong_witness_complex.h>
 #include <gudhi/Persistent_cohomology.h>
@@ -81,10 +59,8 @@ int main(int argc, char * argv[]) {
   Gudhi::subsampling::pick_n_random_points(witnesses, nbL, std::back_inserter(landmarks));
 
   // Compute witness complex
-  Strong_witness_complex strong_witness_complex(landmarks.begin(),
-                                                landmarks.end(),
-                                                witnesses.begin(),
-                                                witnesses.end());
+  Strong_witness_complex strong_witness_complex(landmarks,
+                                                witnesses);
   
   strong_witness_complex.create_complex(simplex_tree, max_squared_alpha);
   
diff --git a/src/Witness_complex/example/example_witness_complex_off.cpp b/src/Witness_complex/example/example_witness_complex_off.cpp
index 94088370..2677499a 100644
--- a/src/Witness_complex/example/example_witness_complex_off.cpp
+++ b/src/Witness_complex/example/example_witness_complex_off.cpp
@@ -1,25 +1,3 @@
-/*    This file is part of the Gudhi Library. The Gudhi library
- *    (Geometric Understanding in Higher Dimensions) is a generic C++
- *    library for computational topology.
- *
- *    Author(s):       Siargey Kachanovich
- *
- *    Copyright (C) 2015  INRIA (France)
- *
- *    This program is free software: you can redistribute it and/or modify
- *    it under the terms of the GNU General Public License as published by
- *    the Free Software Foundation, either version 3 of the License, or
- *    (at your option) any later version.
- *
- *    This program is distributed in the hope that it will be useful,
- *    but WITHOUT ANY WARRANTY; without even the implied warranty of
- *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- *    GNU General Public License for more details.
- *
- *    You should have received a copy of the GNU General Public License
- *    along with this program.  If not, see <http://www.gnu.org/licenses/>.
- */
-
 #include <sys/types.h>
 #include <sys/stat.h>
 
@@ -72,10 +50,8 @@ int main(int argc, char * const argv[]) {
 
   // Compute witness complex
   start = clock();
-  Witness_complex witness_complex(landmarks.begin(),
-                                  landmarks.end(),
-                                  point_vector.begin(),
-                                  point_vector.end());
+  Witness_complex witness_complex(landmarks,
+                                  point_vector);
 
   witness_complex.create_complex(simplex_tree, alpha2, lim_dim);
   end = clock();
diff --git a/src/Witness_complex/example/example_witness_complex_persistence.cpp b/src/Witness_complex/example/example_witness_complex_persistence.cpp
index b1b415fa..00f00aae 100644
--- a/src/Witness_complex/example/example_witness_complex_persistence.cpp
+++ b/src/Witness_complex/example/example_witness_complex_persistence.cpp
@@ -1,25 +1,3 @@
-/*    This file is part of the Gudhi Library. The Gudhi library 
- *    (Geometric Understanding in Higher Dimensions) is a generic C++ 
- *    library for computational topology.
- *
- *    Author(s):       Siargey Kachanovich
- *
- *    Copyright (C) 2016  INRIA (France)
- *
- *    This program is free software: you can redistribute it and/or modify
- *    it under the terms of the GNU General Public License as published by
- *    the Free Software Foundation, either version 3 of the License, or
- *    (at your option) any later version.
- *
- *    This program is distributed in the hope that it will be useful,
- *    but WITHOUT ANY WARRANTY; without even the implied warranty of
- *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- *    GNU General Public License for more details.
- *
- *    You should have received a copy of the GNU General Public License
- *    along with this program.  If not, see <http://www.gnu.org/licenses/>.
- */
-
 #include <gudhi/Simplex_tree.h>
 #include <gudhi/Witness_complex.h>
 #include <gudhi/Persistent_cohomology.h>
@@ -81,10 +59,8 @@ int main(int argc, char * argv[]) {
   Gudhi::subsampling::pick_n_random_points(witnesses, nbL, std::back_inserter(landmarks));
 
   // Compute witness complex
-  Witness_complex witness_complex(landmarks.begin(),
-                                  landmarks.end(),
-                                  witnesses.begin(),
-                                  witnesses.end());
+  Witness_complex witness_complex(landmarks,
+                                  witnesses);
   
   witness_complex.create_complex(simplex_tree, max_squared_alpha);
   
diff --git a/src/Witness_complex/example/example_witness_complex_sphere.cpp b/src/Witness_complex/example/example_witness_complex_sphere.cpp
index d21195fa..42fb9f8d 100644
--- a/src/Witness_complex/example/example_witness_complex_sphere.cpp
+++ b/src/Witness_complex/example/example_witness_complex_sphere.cpp
@@ -1,24 +1,3 @@
-/*    This file is part of the Gudhi Library. The Gudhi library
- *    (Geometric Understanding in Higher Dimensions) is a generic C++
- *    library for computational topology.
- *
- *    Author(s):       Siargey Kachanovich
- *
- *    Copyright (C) 2015  INRIA (France)
- *
- *    This program is free software: you can redistribute it and/or modify
- *    it under the terms of the GNU General Public License as published by
- *    the Free Software Foundation, either version 3 of the License, or
- *    (at your option) any later version.
- *
- *    This program is distributed in the hope that it will be useful,
- *    but WITHOUT ANY WARRANTY; without even the implied warranty of
- *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- *    GNU General Public License for more details.
- *
- *    You should have received a copy of the GNU General Public License
- *    along with this program.  If not, see <http://www.gnu.org/licenses/>.
- */
 #define BOOST_PARAMETER_MAX_ARITY 12
 
 
@@ -80,10 +59,8 @@ int main(int argc, char * const argv[]) {
     Gudhi::subsampling::pick_n_random_points(point_vector, number_of_landmarks, std::back_inserter(landmarks));
 
     // Compute witness complex
-    Witness_complex witness_complex(landmarks.begin(),
-                                    landmarks.end(),
-                                    point_vector.begin(),
-                                    point_vector.end());
+    Witness_complex witness_complex(landmarks,
+                                    point_vector);
     witness_complex.create_complex(simplex_tree, 0);
     end = clock();
     double time = static_cast<double>(end - start) / CLOCKS_PER_SEC;
diff --git a/src/Witness_complex/include/gudhi/Strong_witness_complex.h b/src/Witness_complex/include/gudhi/Strong_witness_complex.h
index 7ef8d3e5..c7b8c27b 100644
--- a/src/Witness_complex/include/gudhi/Strong_witness_complex.h
+++ b/src/Witness_complex/include/gudhi/Strong_witness_complex.h
@@ -94,22 +94,18 @@ private:
 
   /**
    *  \brief Initializes member variables before constructing simplicial complex.
-   *  \details Records landmarks from the range [landmarks_first, landmarks_last) into a 
-   *           table internally, as well as witnesses from the range [witnesses_first, witnesses_last).
-   *           All iterator parameters should satisfy <a target="_blank"
-   *           href="http://en.cppreference.com/w/cpp/concept/InputIterator">InputIterator</a>
-   *           C++ concept.
+   *  \details Records landmarks from the range 'landmarks' into a 
+   *           table internally, as well as witnesses from the range 'witnesses'.
    */
-  template< typename InputIteratorLandmarks,
-            typename InputIteratorWitnesses >
-  Strong_witness_complex(InputIteratorLandmarks landmarks_first,
-                  InputIteratorLandmarks landmarks_last,
-                  InputIteratorWitnesses witnesses_first,
-                  InputIteratorWitnesses witnesses_last)
-    : witnesses_(witnesses_first, witnesses_last), landmarks_(landmarks_first, landmarks_last), landmark_tree_(landmarks_)
+  template< typename LandmarkRange,
+            typename WitnessRange >
+  Strong_witness_complex(const LandmarkRange & landmarks,
+                         const WitnessRange &  witnesses)
+    : witnesses_(witnesses), landmarks_(landmarks), landmark_tree_(landmarks_)
   {    
   }
 
+  
   /** \brief Returns the point corresponding to the given vertex.
    */
   template <typename Vertex_handle> 
@@ -118,9 +114,10 @@ private:
     return landmarks_[vertex];
   }
   
-  /** \brief Outputs the strong witness complex in a simplicial complex data structure.
-   *  @param[out] complex Simplicial complex data structure compatible with 'find' and 'insert' operations.
-   *              (Cf SimplicialComplexForWitness)
+  /** \brief Outputs the strong witness complex of relaxation 'max_alpha_square' 
+   *         in a simplicial complex data structure.
+   *  @param[out] complex Simplicial complex data structure, which is a model of
+   *              SimplicialComplexForWitness concept.
    *  @param[in] max_alpha_square Maximal squared relaxation parameter.
    *  @param[in] limit_dimension Represents the maximal dimension of the simplicial complex
    *         (default value = no limit).
diff --git a/src/Witness_complex/include/gudhi/Witness_complex.h b/src/Witness_complex/include/gudhi/Witness_complex.h
index ac0e8f66..c1d402c6 100644
--- a/src/Witness_complex/include/gudhi/Witness_complex.h
+++ b/src/Witness_complex/include/gudhi/Witness_complex.h
@@ -46,12 +46,6 @@ namespace witness_complex {
  * \tparam Kernel_ requires a <a target="_blank"
  * href="http://doc.cgal.org/latest/Kernel_d/classCGAL_1_1Epick__d.html">CGAL::Epick_d</a> class, which
  * can be static if you know the ambiant dimension at compile-time, or dynamic if you don't.
- * \tparam DimensionTag can be either <a target="_blank"
- * href="http://doc.cgal.org/latest/Kernel_23/classCGAL_1_1Dimension__tag.html">Dimension_tag<d></a>
- * if you know the intrinsic dimension at compile-time,
- * or <a target="_blank"
- * href="http://doc.cgal.org/latest/Kernel_23/classCGAL_1_1Dynamic__dimension__tag.html">CGAL::Dynamic_dimension_tag</a>
- * if you don't.
 */
 template< class Kernel_ >
 class Witness_complex {
@@ -94,19 +88,14 @@ private:
 
   /**
    *  \brief Initializes member variables before constructing simplicial complex.
-   *  \details Records landmarks from the range [landmarks_first, landmarks_last) into a 
-   *           table internally, as well as witnesses from the range [witnesses_first, witnesses_last).
-   *           All iterator parameters should satisfy <a target="_blank"
-   *           href="http://en.cppreference.com/w/cpp/concept/InputIterator">InputIterator</a>
-   *           C++ concept.
+   *  \details Records landmarks from the range 'landmarks' into a 
+   *           table internally, as well as witnesses from the range 'witnesses'.
    */
-  template< typename InputIteratorLandmarks,
-            typename InputIteratorWitnesses >
-  Witness_complex(InputIteratorLandmarks landmarks_first,
-                  InputIteratorLandmarks landmarks_last,
-                  InputIteratorWitnesses witnesses_first,
-                  InputIteratorWitnesses witnesses_last)
-    : witnesses_(witnesses_first, witnesses_last), landmarks_(landmarks_first, landmarks_last), landmark_tree_(landmarks_)
+  template< typename LandmarkRange,
+            typename WitnessRange >
+  Witness_complex(const LandmarkRange & landmarks,
+                  const WitnessRange &  witnesses)
+    : witnesses_(witnesses), landmarks_(landmarks), landmark_tree_(landmarks_)
   {    
   }
 
@@ -118,9 +107,10 @@ private:
     return landmarks_[vertex];
   }
   
-  /** \brief Outputs the (weak) witness complex in a simplicial complex data structure.
-   *  @param[out] complex Simplicial complex data structure compatible with 'find' and 'insert' operations.
-   *              (Cf SimplicialComplexForWitness)
+  /** \brief Outputs the (weak) witness complex of relaxation 'max_alpha_square'
+   *         in a simplicial complex data structure.
+   *  @param[out] complex Simplicial complex data structure compatible which is a model of
+   *              SimplicialComplexForWitness concept.
    *  @param[in] max_alpha_square Maximal squared relaxation parameter.
    *  @param[in] limit_dimension Represents the maximal dimension of the simplicial complex
    *         (default value = no limit).
diff --git a/src/Witness_complex/test/test_simple_witness_complex.cpp b/src/Witness_complex/test/test_simple_witness_complex.cpp
index 90b6cfa2..a0a1b36c 100644
--- a/src/Witness_complex/test/test_simple_witness_complex.cpp
+++ b/src/Witness_complex/test/test_simple_witness_complex.cpp
@@ -1,25 +1,3 @@
-/*    This file is part of the Gudhi Library. The Gudhi library
- *    (Geometric Understanding in Higher Dimensions) is a generic C++
- *    library for computational topology.
- *
- *    Author(s):       Siargey Kachanovich
- *
- *    Copyright (C) 2016  INRIA (France)
- *
- *    This program is free software: you can redistribute it and/or modify
- *    it under the terms of the GNU General Public License as published by
- *    the Free Software Foundation, either version 3 of the License, or
- *    (at your option) any later version.
- *
- *    This program is distributed in the hope that it will be useful,
- *    but WITHOUT ANY WARRANTY; without even the implied warranty of
- *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- *    GNU General Public License for more details.
- *
- *    You should have received a copy of the GNU General Public License
- *    along with this program.  If not, see <http://www.gnu.org/licenses/>.
- */
-
 #define BOOST_TEST_DYN_LINK
 #define BOOST_TEST_MODULE "simple_witness_complex"
 #include <boost/test/unit_test.hpp>
@@ -79,10 +57,8 @@ BOOST_AUTO_TEST_CASE(simple_witness_complex) {
   witnesses.push_back(Point_d(std::vector<FT>{ 2,-1}));
   witnesses.push_back(Point_d(std::vector<FT>{ 2, 1}));
   
-  WitnessComplex witness_complex(landmarks.begin(),
-                                 landmarks.end(),
-                                 witnesses.begin(),
-                                 witnesses.end());
+  WitnessComplex witness_complex(landmarks,
+                                 witnesses);
   witness_complex.create_complex(complex, 0);
 
   std::cout << "complex.num_simplices() = " << complex.num_simplices() << std::endl; 
@@ -93,10 +69,8 @@ BOOST_AUTO_TEST_CASE(simple_witness_complex) {
   std::cout << "relaxed_complex.num_simplices() = " << relaxed_complex.num_simplices() << std::endl; 
   BOOST_CHECK(relaxed_complex.num_simplices() == 239);
   
-  StrongWitnessComplex strong_witness_complex(landmarks.begin(),
-                                              landmarks.end(),
-                                              witnesses.begin(),
-                                              witnesses.end());
+  StrongWitnessComplex strong_witness_complex(landmarks,
+                                              witnesses);
 
   strong_witness_complex.create_complex(strong_relaxed_complex, 9.1);