doc multi_critical_filtration

src/Multi_filtration/include/gudhi/One_critical_filtration.h

@@ -5,7 +5,7 @@
  *    Copyright (C) 2023 Inria
  *
  *    Modification(s):
- *      - 2024/08 Hannah Schreiber: Generalization to all signed arithmetic types for T
+ *      - 2024/08 Hannah Schreiber: Generalization to all signed arithmetic types for T + doc
  *      - YYYY/MM Author: Description of the modification
  */
 
@@ -78,7 +78,6 @@ class One_critical_filtration : public std::vector<T>
    * @brief Default constructor. Constructs an empty vector with 0 parameters.
    */
   One_critical_filtration() : Base() {};
-  //TODO: Accept {-inf, -inf, ...} / {inf, inf, ...} / {NaN, NaN, ...} as resp. -inf / inf / NaN to avoid the warnings.
   /**
    * @brief Constructs a vector of the size of the given number of parameters with -inf as value for each entry.
    *
@@ -93,7 +92,7 @@ class One_critical_filtration : public std::vector<T>
    * @brief Constructs a vector of the size of the given number of parameters and the given value for each entry.
    *
    * @warning If @p value is `inf`, `-inf`, or `NaN`, the vector `{value, value, ...}` with \f$ n > 1 \f$ entries
-   * are not wrong but will not be considered as respectively "infinity", "minus infinity" or "NaN" (the corresponding
+   * is not wrong but will not be considered as respectively "infinity", "minus infinity" or "NaN" (the corresponding
    * methods @ref is_inf(), @ref is_minus_inf() and @ref is_nan() will return false). For this purpose, please use
    * the static methods @ref inf(), @ref minus_inf() and @ref nan() instead.
    * 
@@ -219,6 +218,8 @@ class One_critical_filtration : public std::vector<T>
 
   // DESCRIPTORS
 
+  //TODO: Accept {-inf, -inf, ...} / {inf, inf, ...} / {NaN, NaN, ...} as resp. -inf / inf / NaN.
+
   /**
    * @brief Returns `true` if and only if the filtration value is considered as infinity.
    */
@@ -1010,7 +1011,7 @@ class One_critical_filtration : public std::vector<T>
    * 
    * @param x The target filtration value towards which to push.
    */
-  void push_to(const One_critical_filtration &x)
+  void push_to_least_common_upper_bound(const One_critical_filtration &x)
   {
     if (this->is_inf() || this->is_nan() || x.is_nan() || x.is_minus_inf()) return;
     if (x.is_inf() || this->is_minus_inf()) {
@@ -1034,7 +1035,7 @@ class One_critical_filtration : public std::vector<T>
    * 
    * @param x The target filtration value towards which to pull.
    */
-  void pull_to(const One_critical_filtration &x)
+  void pull_to_greatest_common_lower_bound(const One_critical_filtration &x)
   {
     if (x.is_inf() || this->is_nan() || x.is_nan() || this->is_minus_inf()) return;
     if (this->is_inf() || x.is_minus_inf()) {
@@ -1049,10 +1050,6 @@ class One_critical_filtration : public std::vector<T>
       Base::operator[](i) = Base::operator[](i) > x[i] ? x[i] : Base::operator[](i);
   }
 
-  /*
-   * Same as `compute_coordinates_in_grid` but does the operation in-place
-   */
-
   /**
    * @brief Projects the filtration value into the given grid. If @p coordinate is false, the entries are set to
    * the nearest upper bound value with the same parameter in the grid. Otherwise, the entries are set to the indices
@@ -1092,7 +1089,7 @@ class One_critical_filtration : public std::vector<T>
    * @tparam U Arithmetic type of the result. Default value: `T`.
    * @param f Filtration value.
    * @param x Vector of coefficients.
-   * @return U Scalar product of @p f with @p x.
+   * @return Scalar product of @p f with @p x.
    */
   template <typename U = T>
   friend U compute_linear_projection(const One_critical_filtration &f, const std::vector<U> &x)
@@ -1132,12 +1129,6 @@ class One_critical_filtration : public std::vector<T>
     return std::sqrt(out);
   }
 
-  /**
-   * Given a grid in an array of shape (num_parameters, filtration_values of this parameter),
-   * projects itself into this grid, and returns the coordinates of this projected points
-   * in the given grid
-   */
-
   /**
    * @brief Computes the coordinates in the given grid, corresponding to the nearest upper bounds of the entries
    * in the given filtration value.
@@ -1149,7 +1140,7 @@ class One_critical_filtration : public std::vector<T>
    * @tparam out_type Signed arithmetic type. Default value: std::int32_t.
    * @tparam U Type which is convertible into `out_type`.
    * @param f Filtration value to project.
-   * @param grid Vector of vector to project into.
+   * @param grid Vector of vectors to project into.
    * @return Filtration value \f$ out \f$ whose entry correspond to the indices of the projected values. That is,
    * the projection of \f$ f[i] \f$ is \f$ grid[i][out[i]] \f$.
    */
@@ -1161,12 +1152,6 @@ class One_critical_filtration : public std::vector<T>
     coords.project_onto_grid(grid);
     return coords;
   }
-
-  /**
-   * Given a grid in an array of shape (num_parameters, filtration_values of this parameter),
-   * and assuming that `this` correspond to the coordinates in this grid,
-   * returns the points evaluated in this grid
-   */
 
   /**
    * @brief Computes the values in the given grid corresponding to the coordinates given by the given filtration 
@@ -1236,9 +1221,8 @@ class One_critical_filtration : public std::vector<T>
   constexpr static const T T_inf =
       std::numeric_limits<T>::has_infinity ? std::numeric_limits<T>::infinity() : std::numeric_limits<T>::max();
 
-  // for compiler
   /**
-   * @brief Indicates if the class manage multi-critical filtration values.
+   * @brief Indicates if the class manages multi-critical filtration values.
    */
   constexpr static bool is_multi_critical = false;
 

src/Multi_filtration/test/multifiltration_multicritical_unit_test.cpp

@@ -235,66 +235,66 @@ BOOST_AUTO_TEST_CASE_TEMPLATE(multi_critical_filtration_modifiers, T, list_of_te
   BOOST_CHECK_EQUAL(f[1][1], 1);
   BOOST_CHECK_EQUAL(f[1][2], 7);
 
-  f.push_to({-1, 5, 6});
+  f.push_to_least_common_upper_bound({-1, 5, 6});
   BOOST_CHECK_EQUAL(f[0][0], 0);
   BOOST_CHECK_EQUAL(f[0][1], 5);
   BOOST_CHECK_EQUAL(f[0][2], 6);
   BOOST_CHECK_EQUAL(f[1][0], -1);
   BOOST_CHECK_EQUAL(f[1][1], 5);
   BOOST_CHECK_EQUAL(f[1][2], 7);
 
-  f.push_to({-1, -5, -6});
+  f.push_to_least_common_upper_bound({-1, -5, -6});
   BOOST_CHECK_EQUAL(f[0][0], 0);
   BOOST_CHECK_EQUAL(f[0][1], 5);
   BOOST_CHECK_EQUAL(f[0][2], 6);
   BOOST_CHECK_EQUAL(f[1][0], -1);
   BOOST_CHECK_EQUAL(f[1][1], 5);
   BOOST_CHECK_EQUAL(f[1][2], 7);
 
-  f.push_to(Multi_critical_filtration<T>::Single_point::minus_inf());
+  f.push_to_least_common_upper_bound(Multi_critical_filtration<T>::Single_point::minus_inf());
   BOOST_CHECK_EQUAL(f[0][0], 0);
   BOOST_CHECK_EQUAL(f[0][1], 5);
   BOOST_CHECK_EQUAL(f[0][2], 6);
   BOOST_CHECK_EQUAL(f[1][0], -1);
   BOOST_CHECK_EQUAL(f[1][1], 5);
   BOOST_CHECK_EQUAL(f[1][2], 7);
 
-  f.push_to(Multi_critical_filtration<T>::Single_point::inf());
+  f.push_to_least_common_upper_bound(Multi_critical_filtration<T>::Single_point::inf());
   BOOST_CHECK(f.is_inf());
 
-  f.push_to(Multi_critical_filtration<T>::Single_point::nan());
+  f.push_to_least_common_upper_bound(Multi_critical_filtration<T>::Single_point::nan());
   BOOST_CHECK(f.is_inf());
 
-  f.pull_to({-1, 5, 6});
+  f.pull_to_greatest_common_lower_bound({-1, 5, 6});
   BOOST_CHECK_EQUAL(f[0][0], -1);
   BOOST_CHECK_EQUAL(f[0][1], 5);
   BOOST_CHECK_EQUAL(f[0][2], 6);
 
-  f.pull_to({1, 8, 9});
+  f.pull_to_greatest_common_lower_bound({1, 8, 9});
   BOOST_CHECK_EQUAL(f[0][0], -1);
   BOOST_CHECK_EQUAL(f[0][1], 5);
   BOOST_CHECK_EQUAL(f[0][2], 6);
 
-  f.pull_to(Multi_critical_filtration<T>::Single_point::inf());
+  f.pull_to_greatest_common_lower_bound(Multi_critical_filtration<T>::Single_point::inf());
   BOOST_CHECK_EQUAL(f[0][0], -1);
   BOOST_CHECK_EQUAL(f[0][1], 5);
   BOOST_CHECK_EQUAL(f[0][2], 6);
 
-  f.pull_to(Multi_critical_filtration<T>::Single_point::minus_inf());
+  f.pull_to_greatest_common_lower_bound(Multi_critical_filtration<T>::Single_point::minus_inf());
   BOOST_CHECK(f.is_minus_inf());
 
-  f.pull_to(Multi_critical_filtration<T>::Single_point::nan());
+  f.pull_to_greatest_common_lower_bound(Multi_critical_filtration<T>::Single_point::nan());
   BOOST_CHECK(f.is_minus_inf());
 
   std::vector<std::vector<int> > grid = {{0, 2, 4, 8}, {0, 3, 6, 9}, {0, 4, 8, 16}};
 
-  f.push_to({1, 7, 5});
+  f.push_to_least_common_upper_bound({1, 7, 5});
   f.project_onto_grid(grid, true);
   BOOST_CHECK_EQUAL(f[0][0], 1);
   BOOST_CHECK_EQUAL(f[0][1], 3);
   BOOST_CHECK_EQUAL(f[0][2], 2);
 
-  f.push_to({1, 7, 5});
+  f.push_to_least_common_upper_bound({1, 7, 5});
   f.project_onto_grid(grid, false);
   BOOST_CHECK_EQUAL(f[0][0], 2);
   BOOST_CHECK_EQUAL(f[0][1], 9);

src/Multi_filtration/test/multifiltration_onecritical_unit_test.cpp

@@ -416,57 +416,57 @@ BOOST_AUTO_TEST_CASE_TEMPLATE(one_critical_filtration_modifiers, T, list_of_test
   BOOST_CHECK_EQUAL(f[1], 1);
   BOOST_CHECK_EQUAL(f[2], 2);
 
-  f.push_to({-1, 5, 6});
+  f.push_to_least_common_upper_bound({-1, 5, 6});
   BOOST_CHECK_EQUAL(f[0], 0);
   BOOST_CHECK_EQUAL(f[1], 5);
   BOOST_CHECK_EQUAL(f[2], 6);
 
-  f.push_to({-1, -5, -6});
+  f.push_to_least_common_upper_bound({-1, -5, -6});
   BOOST_CHECK_EQUAL(f[0], 0);
   BOOST_CHECK_EQUAL(f[1], 5);
   BOOST_CHECK_EQUAL(f[2], 6);
 
-  f.push_to(One_critical_filtration<T>::minus_inf());
+  f.push_to_least_common_upper_bound(One_critical_filtration<T>::minus_inf());
   BOOST_CHECK_EQUAL(f[0], 0);
   BOOST_CHECK_EQUAL(f[1], 5);
   BOOST_CHECK_EQUAL(f[2], 6);
 
-  f.push_to(One_critical_filtration<T>::inf());
+  f.push_to_least_common_upper_bound(One_critical_filtration<T>::inf());
   BOOST_CHECK(f.is_inf());
 
-  f.push_to(One_critical_filtration<T>::nan());
+  f.push_to_least_common_upper_bound(One_critical_filtration<T>::nan());
   BOOST_CHECK(f.is_inf());
 
-  f.pull_to({-1, 5, 6});
+  f.pull_to_greatest_common_lower_bound({-1, 5, 6});
   BOOST_CHECK_EQUAL(f[0], -1);
   BOOST_CHECK_EQUAL(f[1], 5);
   BOOST_CHECK_EQUAL(f[2], 6);
 
-  f.pull_to({1, 8, 9});
+  f.pull_to_greatest_common_lower_bound({1, 8, 9});
   BOOST_CHECK_EQUAL(f[0], -1);
   BOOST_CHECK_EQUAL(f[1], 5);
   BOOST_CHECK_EQUAL(f[2], 6);
 
-  f.pull_to(One_critical_filtration<T>::inf());
+  f.pull_to_greatest_common_lower_bound(One_critical_filtration<T>::inf());
   BOOST_CHECK_EQUAL(f[0], -1);
   BOOST_CHECK_EQUAL(f[1], 5);
   BOOST_CHECK_EQUAL(f[2], 6);
 
-  f.pull_to(One_critical_filtration<T>::minus_inf());
+  f.pull_to_greatest_common_lower_bound(One_critical_filtration<T>::minus_inf());
   BOOST_CHECK(f.is_minus_inf());
 
-  f.pull_to(One_critical_filtration<T>::nan());
+  f.pull_to_greatest_common_lower_bound(One_critical_filtration<T>::nan());
   BOOST_CHECK(f.is_minus_inf());
 
   std::vector<std::vector<int> > grid = {{0, 2, 4, 8}, {0, 3, 6, 9}, {0, 4, 8, 16}};
 
-  f.push_to({1, 7, 5});
+  f.push_to_least_common_upper_bound({1, 7, 5});
   f.project_onto_grid(grid, true);
   BOOST_CHECK_EQUAL(f[0], 1);
   BOOST_CHECK_EQUAL(f[1], 3);
   BOOST_CHECK_EQUAL(f[2], 2);
 
-  f.push_to({1, 7, 5});
+  f.push_to_least_common_upper_bound({1, 7, 5});
   f.project_onto_grid(grid, false);
   BOOST_CHECK_EQUAL(f[0], 2);
   BOOST_CHECK_EQUAL(f[1], 9);

src/Simplex_tree/concept/FiltrationValue.h

@@ -30,6 +30,6 @@ struct FiltrationValue {
    * This function is called when using, e.g. `make_filtration_non_decreasing`, as the filtration of a simplex
    * has to be greater than the filtration of any of its faces.
    * */ 
-  void push_to(const FiltrationValue f);
+  void push_to_least_common_upper_bound(const FiltrationValue f);
 
 };

src/Simplex_tree/concept/SimplexTreeOptions.h

@@ -41,7 +41,7 @@ struct SimplexTreeOptions {
   static const bool stable_simplex_handles;
   /// If true, assumes that SimplexTreeOptions::Filtration_value is vector-like instead of float-like. 
   /// In that case only, this also assumes that SimplexTreeOptions::Filtration_value is a class, 
-  /// which has a `push_to` method that allows to push the filtration value `this` onto the set of points 
+  /// which has a `push_to_least_common_upper_bound` method that allows to push the filtration value `this` onto the set of points 
   /// \f$ \{ y\in \mathrm{Filtration_value} : y\geq x\}\f$ 
   /// that are greater than another filtration value \f$ x \f$.
   /// An example of such a class is Gudhi::multi_persistence::Finitely_critical_multi_filtration .

src/Simplex_tree/include/gudhi/Simplex_tree.h

@@ -1927,10 +1927,10 @@ class Simplex_tree {
       Boundary_simplex_range&& boundary = boundary_simplex_range(sh);
       Filtration_value max_filt_border_value;
       if constexpr (SimplexTreeOptions::is_multi_parameter) {
-        // in that case, we assume that Filtration_value has a `push_to` member to handle this.
+        // in that case, we assume that Filtration_value has a `push_to_least_common_upper_bound` member to handle this.
         max_filt_border_value = Filtration_value(number_of_parameters_); 
         for (auto& face_sh : boundary) {
-          max_filt_border_value.push_to(
+          max_filt_border_value.push_to_least_common_upper_bound(
               filtration(face_sh));  // pushes the value of max_filt_border_value to reach simplex' filtration
         }
       } else {
@@ -1947,7 +1947,7 @@ class Simplex_tree {
         modified = true;
         if constexpr (Options::is_multi_parameter){
           auto& to_increase_filtration = filtration_mutable(sh);
-          to_increase_filtration.push_to(max_filt_border_value);
+          to_increase_filtration.push_to_least_common_upper_bound(max_filt_border_value);
         }
         else{
          sh->second.assign_filtration(max_filt_border_value);

src/common/doc/main_page.md

@@ -298,7 +298,7 @@
 <table>
   <tr>
     <td width="35%" rowspan=2>
-      \image html "gicvisu.jpg"
+      \image html "radius_density_complex_without_interval.png"
     </td>
     <td width="50%">
     Data structures representing one (1-critical) or multiple (k-critical) filtration values of a same simplex with