doc

src/Zigzag_persistence/concept/EdgeModifier.h

@@ -22,7 +22,7 @@ namespace zigzag_persistence {
  * @brief Methods whose purposes are to modify the filtration value of a given edge following a rule.
  * The concept is for example realized by @ref Square_root_edge_modifier.
  */
- template <typename Filtration_value>
+template <typename Filtration_value>
 class EdgeModifier {
  public:
   /**

src/Zigzag_persistence/concept/PointRange.h

@@ -25,8 +25,8 @@ namespace zigzag_persistence {
 class Point{};
 
 /**
- * @brief Range of @ref Point. Used with @ref Oscillating_rips_edge_range::Order_policy::FARTHEST_POINT_ORDERING order policy, 
- * it has to be a random access range.
+ * @brief Range of @ref Point. If used with @ref Oscillating_rips_edge_order_policy::FARTHEST_POINT_ORDERING
+ * order policy, it has to be a random access range.
  */
 class PointRange {
  public:
@@ -52,8 +52,8 @@ class PointRange {
   std::size_t size();
 
   /**
-   * @brief Necessary only if used with @ref Oscillating_rips_edge_range::Order_policy::FARTHEST_POINT_ORDERING. Returns the element
-   * at the given index.
+   * @brief Necessary only if used with @ref Oscillating_rips_edge_order_policy::FARTHEST_POINT_ORDERING.
+   * Returns the element at the given index.
    * 
    * @param index Index of the element to return.
    * @return Point at index @p index.

src/Zigzag_persistence/concept/StableFilteredComplex.h

@@ -20,13 +20,8 @@ namespace zigzag_persistence {
 
 /**
  * @brief Data structure storing the simplices and their filtration values in the current complex. 
- * The concept is realized for example by @ref Gudhi::Simplex_tree < Gudhi::Simplex_tree_options_oscillating_rips >.
- *
- * This concept is not incompatible with the @ref ZigzagComplex concept, so it is possible to use the same complex
- * for the @ref Oscillating_rips_iterator class and the @ref ZigzagPersistence class, as long as it realizes the two 
- * concepts (which is the case for @ref Gudhi::Simplex_tree < Gudhi::Simplex_tree_options_oscillating_rips >). 
- * This avoids having two complexes in memory and give the possibility to directly use the simplex handle instead
- * of the vector of vertices to communicate between the two classes.
+ * The concept is realized for example by
+ * @ref Gudhi::Simplex_tree < Gudhi::zigzag_persistence::Simplex_tree_options_oscillating_rips >.
  */
 class StableFilteredComplex {
  public:
@@ -36,9 +31,8 @@ class StableFilteredComplex {
   typename Simplex_key;
 
   /**
-   * @brief Handle to specify a simplex. Different from the @ref ZigzagComplex concept,
-   * the simplex handles have to be stable, that is, they do not invalidate when a simplex is 
-   * added or removed from the complex (except for the removed simplices them selves of course).
+   * @brief Handle to specify a simplex. The simplex handles have to be stable, that is, they do not invalidate when
+   * a simplex is added or removed from the complex (except for the removed simplices them selves of course).
    */
   typename Simplex_handle;
 
@@ -74,17 +68,11 @@ class StableFilteredComplex {
 
   /**
    * @brief Returns the key associated to the given simplex.
-   * 
-   * @param sh Simplex handle representing the simplex.
-   * @return The key.
    */
   Simplex_key key(Simplex_handle sh);
 
   /**
    * @brief Assignes the given value to the given simplex as a key.
-   * 
-   * @param sh Simplex handle representing the simplex.
-   * @param key Values to associate as key.
    */
   void assign_key(Simplex_handle sh, Simplex_key key);
 
@@ -93,16 +81,13 @@ class StableFilteredComplex {
    * 
    * @tparam VertexRange Range over the vertices of a simplex.
    * @param simplex Simplex to find represented by its vertices.
-   * @return The simplex handle associated to @p simplex if the simplex is found, @ref null_simplex() otherwise.
+   * @return The simplex handle associated to @p simplex if the simplex is found.
    */
   template <class VertexRange>
   Simplex_handle find(const VertexRange& simplex);
 
   /**
    * @brief Returns the filtration value of the given simplex.
-   * 
-   * @param sh 
-   * @return Filtration_value 
    */
   Filtration_value filtration(Simplex_handle sh);
 

src/Zigzag_persistence/concept/ZigzagOptions.h

@@ -22,24 +22,35 @@ namespace zigzag_persistence {
 /**
  * @ingroup zigzag_persistence
  *
- * @brief List of options used for the filtered zigzag persistence computation.
+ * @brief List of options used for the filtered zigzag persistence computation. An implementation of this concept is
+ * @ref Default_filtered_zigzag_options "", which inherits from @ref Default_zigzag_options for the common types.
  */
 struct FilteredZigzagOptions {
   /**
-   * @brief Numerical type for the cell IDs used internally and other indexations. It must be signed.
+   * @brief Type for filtration values.
    */
-  using Internal_key = unspecified;
+  using Filtration_value = unspecified;
 
   /**
    * @brief Type for the cell IDs used at insertion and in the boundaries given as argument.
-   * Has to be usable as key in a hashtable, so "hashable" and comparable.
    */
   using Cell_key = unspecified;
 
   /**
-   * @brief Type for filtration values.
+   * @brief Hash method for @ref Cell_key type. Could simply be 'std::hash<Cell_key>' if the specialization exists;
    */
-  using Filtration_value = unspecified;
+  using Cell_key_hash = unspecified;
+
+  /**
+   * @brief Equality comparator for @ref Cell_key type. Could simply be 'std::equal_to<Cell_key>' if the specialization
+   * exists;
+   */
+  using Cell_key_equal = unspecified;
+
+  /**
+   * @brief Numerical type for the cell IDs used internally and other indexations. It must be signed.
+   */
+  using Internal_key = unspecified;
 
   /**
    * @brief Type for the dimension values.
@@ -55,7 +66,8 @@ struct FilteredZigzagOptions {
 /**
  * @ingroup zigzag_persistence
  *
- * @brief List of options used for the zigzag persistence computation.
+ * @brief List of options used for the zigzag persistence computation. An implementation of this concept is
+ * @ref Default_zigzag_options "".
  */
 struct ZigzagOptions {
   /**

src/Zigzag_persistence/doc/Intro_zigzag_persistence.h

@@ -55,9 +55,38 @@ namespace zigzag_persistence {
  *
  * \subsection zigzagrips Oscillating Rips
  * 
- * A typical example of zigzag filtrations are oscillating rips filtrations. Similar to standard Rips filtrations, they 
- * completely depend on their edges. But here we look at neighborhoods "oscillating" in size around the points, so 
- * edges are added but also removed. We refer for example to \cite osc_zz.
+ * A typical example of zigzag filtrations are oscillating Rips filtrations. Similar to standard
+ * @ref ripsdefinition "Rips filtrations", they completely depend on their edges. But here we look at neighborhoods
+ * "oscillating" in size around the points, so edges are added but also removed. We refer for example to \cite osc_zz
+ * for more theoretical details.
+ * 
+ * This module implements the construction of such an oscillating Rips filtration as follows:
+ * \image html "osc_rips.svg" width=70%
+ *
+ * If \f$ P \f$ is the set of points generating the rips filtration, \f$ P_i \f$ corresponds to the subset containing
+ * the \f$ i \f$ first points. So, at each forward inclusion, one vertex is added.
+ *
+ * The superscript of \f$ \mathcal{R} \f$ corresponds to the filtration values which will be associated to the cycles.
+ * The sequence of \f$ \varepsilon \f$ should be decreasing and end with \f$ 0 \f$. The sequence can either be specified
+ * by the user or automatically generated by choosing the distance of the added point from the other already added
+ * points from the set. In the second case, the user has to specify how the order of the points should be decided.
+ *
+ * The subscript of \f$ \mathcal{R} \f$ corresponds like usual to the radius of the Rips complex. It is generated from
+ * the current epsilon / filtration value by multiplying it alternatively by two coefficients: \f$ \nu \leqslant \mu \f$.
+ * Both multipliers have to be specified by the user.
+ *
+ * The construction is based on two classes:
+ * - @ref Oscillating_rips_edge_range computes the range of inserted and removed vertices and edges in the filtration
+ * based on the elements descipted above.
+ * - @ref Oscillating_rips_simplex_range infers from @ref Oscillating_rips_edge_range all simplices from higher
+ * dimensions (i.e. > 1) of the filtration if necessary. For this purpose, a data structure able to represent a flag
+ * complex is additionally needed (such as @ref Gudhi::Simplex_tree). Note that @ref Oscillating_rips_edge_range is
+ * passed by template, so the user can potentially pass any other type of edge range as long as the dereferenced format
+ * corresponds and the sequence makes sense as a zigzag filtration.
+ *
+ * If only the barcode of the filtration is of interest and not the filtration it-self, the helper method
+ * @ref compute_oscillating_rips_persistence can be used. It will directly feed to the filtration constructed by the
+ * two classes above into @ref Zigzag_persistence "".
  * 
  * \section zigzagexamples Examples
  *