Clarify doc of witness complex

3 files changed, 15 insertions, 18 deletions

diff --git a/src/Witness_complex/example/example_nearest_landmark_table.cpp b/src/Witness_complex/example/example_nearest_landmark_table.cpp
index acaf7c54..441900c1 100644
--- a/src/Witness_complex/example/example_nearest_landmark_table.cpp
+++ b/src/Witness_complex/example/example_nearest_landmark_table.cpp
@@ -19,22 +19,19 @@ int main(int argc, char * const argv[]) {
   using Persistent_cohomology = Gudhi::persistent_cohomology::Persistent_cohomology<Simplex_tree, Field_Zp>;
 
   Simplex_tree simplex_tree;
-  Nearest_landmark_table nlt;
 
   // Example contains 5 witnesses and 5 landmarks
-  Nearest_landmark_range w0 = {std::make_pair(0, 0), std::make_pair(1, 1), std::make_pair(2, 2),
-                               std::make_pair(3, 3), std::make_pair(4, 4)}; nlt.push_back(w0);
-  Nearest_landmark_range w1 = {std::make_pair(1, 0), std::make_pair(2, 1), std::make_pair(3, 2),
-                               std::make_pair(4, 3), std::make_pair(0, 4)}; nlt.push_back(w1);
-  Nearest_landmark_range w2 = {std::make_pair(2, 0), std::make_pair(3, 1), std::make_pair(4, 2),
-                               std::make_pair(0, 3), std::make_pair(1, 4)}; nlt.push_back(w2);
-  Nearest_landmark_range w3 = {std::make_pair(3, 0), std::make_pair(4, 1), std::make_pair(0, 2),
-                               std::make_pair(1, 3), std::make_pair(2, 4)}; nlt.push_back(w3);
-  Nearest_landmark_range w4 = {std::make_pair(4, 0), std::make_pair(0, 1), std::make_pair(1, 2),
-                               std::make_pair(2, 3), std::make_pair(3, 4)}; nlt.push_back(w4);
+  Nearest_landmark_table nlt = {
+    {{0, 0.0}, {1, 0.1}, {2, 0.2}, {3, 0.3}, {4, 0.4}}, // witness 0
+    {{1, 0.0}, {2, 0.1}, {3, 0.2}, {4, 0.3}, {0, 0.4}}, // witness 1
+    {{2, 0.0}, {3, 0.1}, {4, 0.2}, {0, 0.3}, {1, 0.4}}, // witness 2
+    {{3, 0.0}, {4, 0.1}, {0, 0.2}, {1, 0.3}, {2, 0.4}}, // witness 3
+    {{4, 0.0}, {0, 0.1}, {1, 0.2}, {2, 0.3}, {3, 0.4}}  // witness 4
+  };
+  /* distance(witness3, landmark3) is 0, distance(witness3, landmark4) is 0.1, etc.  */
 
   Witness_complex witness_complex(nlt);
-  witness_complex.create_complex(simplex_tree, 4.1);
+  witness_complex.create_complex(simplex_tree, .41);
 
   std::cout << "Number of simplices: " << simplex_tree.num_simplices() << std::endl;
 
diff --git a/src/Witness_complex/include/gudhi/Strong_witness_complex.h b/src/Witness_complex/include/gudhi/Strong_witness_complex.h
index fd6b3f38..5fd116b9 100644
--- a/src/Witness_complex/include/gudhi/Strong_witness_complex.h
+++ b/src/Witness_complex/include/gudhi/Strong_witness_complex.h
@@ -40,10 +40,10 @@ namespace witness_complex {
  * \brief Constructs strong witness complex for a given table of nearest landmarks with respect to witnesses.
  * \ingroup witness_complex
  *
- * \tparam Nearest_landmark_table_ needs to be a range of a range of pairs of nearest landmarks and distances.
+ * \tparam Nearest_landmark_table_ needs to be a range (one entry per witness) of sorted ranges of pairs of nearest landmarks and distances.
  *         The class Nearest_landmark_table_::value_type must be a copiable range.
  *         The range of pairs must admit a member type 'iterator'. The dereference type 
- *         of the pair range iterator needs to be 'std::pair<std::size_t, double>'.
+ *         of the pair range iterator needs to be 'std::pair<std::size_t, double>' where the first element is the index of the landmark, and the second its (squared) distance to the witness.
  */
 template< class Nearest_landmark_table_ >
 class Strong_witness_complex {
diff --git a/src/Witness_complex/include/gudhi/Witness_complex.h b/src/Witness_complex/include/gudhi/Witness_complex.h
index 67885258..4063e040 100644
--- a/src/Witness_complex/include/gudhi/Witness_complex.h
+++ b/src/Witness_complex/include/gudhi/Witness_complex.h
@@ -75,10 +75,10 @@ class Witness_complex {
   /**
    *  \brief Initializes member variables before constructing simplicial complex.
    *  \details Records nearest landmark table.
-   *  @param[in] nearest_landmark_table needs to be a range of a range of pairs of nearest landmarks and distances.
+   *  @param[in] nearest_landmark_table needs to be a range (one entry per witness) of sorted ranges of pairs of nearest landmarks and distances.
    *         The class Nearest_landmark_table_::value_type must be a copiable range.
    *         The range of pairs must admit a member type 'iterator'. The dereference type 
-   *         of the pair range iterator needs to be 'std::pair<std::size_t, double>'.
+   *         of the pair range iterator needs to be 'std::pair<std::size_t, double>' where the first element is the index of the landmark, and the second its (squared) distance to the witness.
    */
 
   Witness_complex(Nearest_landmark_table_ const & nearest_landmark_table)
@@ -108,8 +108,8 @@ class Witness_complex {
     }
     ActiveWitnessList active_witnesses;
     Landmark_id k = 0; /* current dimension in iterative construction */
-    for (auto w : nearest_landmark_table_)
-      active_witnesses.push_back(ActiveWitness(w));
+    for (auto&& w : nearest_landmark_table_)
+      active_witnesses.emplace_back(w);
     while (!active_witnesses.empty() && k <= limit_dimension) {
       typename ActiveWitnessList::iterator aw_it = active_witnesses.begin();
       std::vector<Landmark_id> simplex;