Zigzag persistence part2

CMakeLists.txt

@@ -46,6 +46,7 @@ add_gudhi_module(Toplex_map)
 add_gudhi_module(Witness_complex)
 add_gudhi_module(Nerve_GIC)
 add_gudhi_module(Persistence_matrix)
+add_gudhi_module(Zigzag_persistence)
 
 # Include module CMake subdirectories
 # GUDHI_SUB_DIRECTORIES is managed in CMAKE_MODULE_PATH/GUDHI_modules.cmake

biblio/bibliography.bib

@@ -267,6 +267,18 @@ @book{Munkres-elementsalgtop1984
   bibsource = {DBLP, http://dblp.uni-trier.de}
 }
 
+@inproceedings{osc_zz,
+author = {Oudot, Steve and Sheehy, Donald},
+year = {2013},
+month = {06},
+pages = {387-396},
+title = {{Zigzag Zoology: Rips Zigzags for Homology Inference}},
+volume = {15},
+ booktitle = {Foundations of Computational Mathematics},
+url = {https://doi.org/10.1145/2462356.2462371},
+doi = {10.1145/2462356.2462371}
+}
+
 @article{Cohen-Steiner2009,
   author    = {Cohen-Steiner, David and Edelsbrunner, Herbert and Harer, John},
   journal   = {Foundations of Computational Mathematics},

src/CMakeLists.txt

@@ -45,6 +45,7 @@ add_gudhi_module(Toplex_map)
 add_gudhi_module(Witness_complex)
 add_gudhi_module(Nerve_GIC)
 add_gudhi_module(Persistence_matrix)
+add_gudhi_module(Zigzag_persistence)
 
 set(GUDHI_BIBLIO_DIR ${CMAKE_SOURCE_DIR})
 # For "make doxygen" - Requires GUDHI_USER_VERSION_DIR to be set

src/Zigzag_persistence/concept/DistanceFunction.h

@@ -0,0 +1,31 @@
+/*    This file is part of the Gudhi Library - https://gudhi.inria.fr/ - which is released under MIT.
+ *    See file LICENSE or go to https://gudhi.inria.fr/licensing/ for full license details.
+ *    Author(s):       Hannah Schreiber
+ *
+ *    Copyright (C) 2023 Inria
+ *
+ *    Modification(s):
+ *      - YYYY/MM Author: Description of the modification
+ */
+
+#ifndef CONCEPT_ZZ_DISTANCE_FUNCTION_H_
+#define CONCEPT_ZZ_DISTANCE_FUNCTION_H_
+
+/** @file DistanceFunction.h
+ * @brief Contains @ref Gudhi::zigzag_persistence::DistanceFunction concept.
+ */
+
+#include "PointRange.h"
+
+namespace Gudhi {
+namespace zigzag_persistence {
+
+/**
+ * @brief Distance function taking two points as input and returning the distance between them.
+ */
+using DistanceFunction = double (*)(const Point&, const Point&);
+
+}  // namespace zigzag_persistence
+}  // namespace Gudhi
+
+#endif  // CONCEPT_ZZ_DISTANCE_FUNCTION_H_

src/Zigzag_persistence/concept/EdgeModifier.h

@@ -0,0 +1,54 @@
+/*    This file is part of the Gudhi Library - https://gudhi.inria.fr/ - which is released under MIT.
+ *    See file LICENSE or go to https://gudhi.inria.fr/licensing/ for full license details.
+ *    Author(s):       Hannah Schreiber
+ *
+ *    Copyright (C) 2023 Inria
+ *
+ *    Modification(s):
+ *      - YYYY/MM Author: Description of the modification
+ */
+
+#ifndef CONCEPT_ZZ_EDGE_MODIFIER_H_
+#define CONCEPT_ZZ_EDGE_MODIFIER_H_
+
+/** @file EdgeModifier.h
+ * @brief Contains @ref Gudhi::zigzag_persistence::EdgeModifier concept.
+ */
+
+namespace Gudhi {
+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>
+class EdgeModifier {
+ public:
+  /**
+   * @brief Indicates that the modifier should not be ignored.
+   */
+  static constexpr bool isActive_ = true;
+
+  /**
+   * @brief Applies the modifier to the given value and returns it.
+   * 
+   * @param f Value to modify.
+   * @return The modified value of @p f.
+   */
+  static Filtration_value apply_modifier(Filtration_value f);
+
+  /**
+   * @brief Applies the inverse modifier to the given value and returns it.
+   * So, apply_inverse_modifier(apply_modifier(f)) == f (modulo some possible precision errors.).
+   * 
+   * @param f Value to modify.
+   * @return The modified value of @p f.
+   */
+  static Filtration_value apply_inverse_modifier(Filtration_value f);
+};
+
+}  // namespace zigzag_persistence
+}  // namespace Gudhi
+
+#endif  // CONCEPT_ZZ_EDGE_MODIFIER_H_

src/Zigzag_persistence/concept/OscillatingRipsSimplexRange.h

@@ -0,0 +1,69 @@
+/*    This file is part of the Gudhi Library - https://gudhi.inria.fr/ - which is released under MIT.
+ *    See file LICENSE or go to https://gudhi.inria.fr/licensing/ for full license details.
+ *    Author(s):       Hannah Schreiber
+ *
+ *    Copyright (C) 2023 Inria
+ *
+ *    Modification(s):
+ *      - YYYY/MM Author: Description of the modification
+ */
+
+#ifndef CONCEPT_ZZ_OSCI_RIPS_RANGE_H_
+#define CONCEPT_ZZ_OSCI_RIPS_RANGE_H_
+
+/** @file OscillatingRipsSimplexRange.h
+ * @brief Contains @ref Gudhi::zigzag_persistence::OscillatingRipsSimplexRange concept.
+ */
+
+#include <gudhi/Zigzag_persistence/oscillating_rips_iterators.h>
+#include <gudhi/Simplex_tree.h>
+
+namespace Gudhi {
+namespace zigzag_persistence {
+
+/**
+ * @brief Class giving access to a range over the simplices in an oscillating Rips filtration 
+ * in order of the filtration.
+ *
+ * A simplex has to be represented by a tuple of three elements:
+ * the first is the simplex handle of the simplex in the given complex,
+ * the second is the filtration value of the corresponding arrow,
+ * the third is the direction of the arrow, i.e., indicates if the simplex is inserted or removed.
+ */
+class OscillatingRipsSimplexRange {
+ public:
+  /**
+   * @brief Returns a range over the simplices in an oscillating Rips filtration 
+   * in order of the filtration.
+   * 
+   * @param edgeStartIterator Begin iterator of the edge range.
+   * @param edgeEndIterator End iterator of the edge range.
+   * @param complex Structure storing the complex at each step.
+   * @param maxDimension Maximal dimension of the expansion.
+   * @return A range with begin() and end() methods.
+   */
+  static auto get_iterator_range(Oscillating_rips_edge_range<double>::Oscillating_rips_edge_iterator& edgeStartIterator,
+                                 Oscillating_rips_edge_range<double>::Oscillating_rips_edge_iterator& edgeEndIterator,
+                                 StableFilteredComplex& complex,
+                                 int maxDimension);
+
+  /**
+   * @brief Returns a range over the simplices in an oscillating Rips filtration 
+   * in order of the filtration.
+   * 
+   * @param edgeStartIterator Begin iterator of the edge range.
+   * @param edgeEndIterator End iterator of the edge range.
+   * @param complex Structure storing the complex at each step.
+   * @param maxDimension Maximal dimension of the expansion.
+   * @return A range with begin() and end() methods.
+   */
+  static auto get_iterator_range(std::vector<Zigzag_edge<double> >::iterator& edgeStartIterator,
+                                 std::vector<Zigzag_edge<double> >::iterator& edgeEndIterator,
+                                 StableFilteredComplex& complex,
+                                 int maxDimension);
+};
+
+}  // namespace zigzag_persistence
+}  // namespace Gudhi
+
+#endif  // CONCEPT_ZZ_OSCI_RIPS_RANGE_H_

src/Zigzag_persistence/concept/PointRange.h

@@ -0,0 +1,67 @@
+/*    This file is part of the Gudhi Library - https://gudhi.inria.fr/ - which is released under MIT.
+ *    See file LICENSE or go to https://gudhi.inria.fr/licensing/ for full license details.
+ *    Author(s):       Hannah Schreiber
+ *
+ *    Copyright (C) 2023 Inria
+ *
+ *    Modification(s):
+ *      - YYYY/MM Author: Description of the modification
+ */
+
+#ifndef CONCEPT_ZZ_POINT_RANGE_H_
+#define CONCEPT_ZZ_POINT_RANGE_H_
+
+/** @file PointRange.h
+ * @brief Contains @ref Gudhi::zigzag_persistence::Point and @ref Gudhi::zigzag_persistence::PointRange concept.
+ */
+
+namespace Gudhi {
+namespace zigzag_persistence {
+
+/**
+ * @brief Data structure representing a point of fixed dimension. The structure of the point does not matter
+ * it-self as long as it corresponds to the input type of the @ref DistanceFunction concept.
+ */
+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.
+ */
+class PointRange {
+ public:
+  /**
+   * @brief Returns begin iterator.
+   * 
+   * @return Begin iterator.
+   */
+  auto begin();
+
+  /**
+   * @brief Returns end iterator.
+   * 
+   * @return End iterator.
+   */
+  auto end();
+
+  /**
+   * @brief Returns size of the range.
+   * 
+   * @return Size of the range.
+   */
+  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.
+   * 
+   * @param index Index of the element to return.
+   * @return Point at index @p index.
+   */
+  Point operator[](std::size_t index);
+};
+
+}  // namespace zigzag_persistence
+}  // namespace Gudhi
+
+#endif  // CONCEPT_ZZ_POINT_RANGE_H_

src/Zigzag_persistence/concept/StableFilteredComplex.h

@@ -0,0 +1,121 @@
+/*    This file is part of the Gudhi Library - https://gudhi.inria.fr/ - which is released under MIT.
+ *    See file LICENSE or go to https://gudhi.inria.fr/licensing/ for full license details.
+ *    Author(s):       Hannah Schreiber
+ *
+ *    Copyright (C) 2023 Inria
+ *
+ *    Modification(s):
+ *      - YYYY/MM Author: Description of the modification
+ */
+
+#ifndef CONCEPT_ZZ_STABLE_COMPLEX_TYPE_H_
+#define CONCEPT_ZZ_STABLE_COMPLEX_TYPE_H_
+
+/** @file StableFilteredComplex.h
+ * @brief Contains @ref Gudhi::zigzag_persistence::StableFilteredComplex concept.
+ */
+
+namespace Gudhi {
+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.
+ */
+class StableFilteredComplex {
+ public:
+  /**
+   * @brief Integer type that needs to be long enough to store the numbers of arrows in the zigzag filtration.
+   */
+  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).
+   */
+  typename Simplex_handle;
+
+  /**
+   * @brief Type for filtration values. Usually 'double'.
+   */
+  typename Filtration_value;
+
+  /**
+   * @brief Removes the given simplex. Assumes that the simplex is maximal and can be safely removed.
+   * 
+   * @param sh Simplex handle representing the simplex to remove.
+   */
+  void remove_maximal_simplex(Simplex_handle sh);
+
+  /**
+   * @brief Adds a vertex or an edge in a flag complex, as well as all
+   * simplices of its star, defined to maintain the property
+   * of the complex to be a flag complex, truncated at dimension dim_max.
+   *
+   * @param u ID of one end of the edge.
+   * @param v ID of the other end of the edge. If @p u == @p v, then the input is considered as a vertex.
+   * @param fil Filtration value of the edge.
+   * @param dim_max Maximal dimension of the expansion. If set to -1, the expansion goes as far as possible.
+   * @param added_simplices Container for all new simplices induced by the insertion of the edge. 
+   * If not empty at start, the content of the container should @b not be erased by the method.
+   */
+  void insert_edge_as_flag(int u,
+                           int v,
+                           Filtration_value fil,
+                           int dim_max,
+                           std::vector<Simplex_handle>& added_simplices);
+
+  /**
+   * @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);
+
+  /**
+   * @brief Finds the given simplex in the complex and returns the associated simplex handle.
+   * 
+   * @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.
+   */
+  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);
+
+  /**
+   * @brief Returns a range (with begin() and end() methods) over the star of the given simplex, including the simplex.
+   * 
+   * @param simplex Simplex to compute the star from.
+   * @return A iterable range over the star of @p simplex.
+   */
+  auto star_simplex_range(const Simplex_handle simplex);
+};
+
+}  // namespace zigzag_persistence
+}  // namespace Gudhi
+
+#endif  // CONCEPT_ZZ_STABLE_COMPLEX_TYPE_H_