Zigzag persistence part1

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

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)
 
 # For "make doxygen" - Requires GUDHI_USER_VERSION_DIR to be set
 set(GUDHI_USER_VERSION_DIR ${CMAKE_SOURCE_DIR})

src/Zigzag_persistence/concept/ZigzagComplex.h

@@ -0,0 +1,128 @@
+/*    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_COMPLEX_TYPE_H_
+#define CONCEPT_ZZ_COMPLEX_TYPE_H_
+
+/** @file ZigzagComplex.h
+ * @brief Contains @ref Gudhi::zigzag_persistence::ZigzagComplex concept.
+ */
+
+namespace Gudhi {
+namespace zigzag_persistence {
+
+/**
+ * @brief Data structure storing the simplices in the current complex.
+ */
+class ZigzagComplex {
+ public:
+  /**
+   * @brief Signed 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.
+   */
+  typename Simplex_handle;
+
+  /**
+   * @brief Handle to specify a vertex. Should be an integer type.
+   */
+  typename Vertex_handle;
+
+  /**
+   * @brief Type for filtration values. Usually 'double'.
+   */
+  typename Filtration_value;
+
+  /**
+   * @brief Range of simplex handles over the boundary of a simplex
+   */
+  typename Boundary_simplex_range;
+
+  /**
+   * @brief Constructor
+   */
+  ZigzagComplex();
+
+  /**
+   * @brief Inserts the given simplex in the complex.
+   * 
+   * @tparam VertexRange Range over the vertices of a simplex.
+   * @param simplex Simplex to insert represented by its vertices.
+   * @return A pair of a simplex handle and a boolean. 
+   * The simplex handle represents the inserted simplex and 
+   * the boolean if simplex was already contained in the complex or not.
+   */
+  template <class VertexRange>
+  std::pair<Simplex_handle, bool> insert_simplex(const VertexRange& simplex);
+
+  /**
+   * @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 Returns the dimension of the given simplex.
+   * 
+   * @param sh Simplex handle representing the simplex.
+   * @return Dimension of @a sh.
+   */
+  int dimension(Simplex_handle sh);
+
+  /**
+   * @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 @a simplex if the simplex is found, @ref null_simplex() otherwise.
+   */
+  template <class VertexRange>
+  Simplex_handle find(const VertexRange& simplex);
+
+  /**
+   * @brief Returns a range of simplex handles representing the boundary of the given simplex.
+   * 
+   * @param sh Simplex handle representing the simplex.
+   * @return Range of simplex handles.
+   */
+  Boundary_simplex_range boundary_simplex_range(Simplex_handle sh);
+
+  /**
+   * @brief Returns a simplex handle representing a non existing simplex. 
+   * 
+   * @return A simplex handle.
+   */
+  Simplex_handle null_simplex();
+};
+
+}  // namespace zigzag_persistence
+}  // namespace Gudhi
+
+#endif  // CONCEPT_ZZ_COMPLEX_TYPE_H_

src/Zigzag_persistence/concept/ZigzagPersistenceOptions.h

@@ -0,0 +1,90 @@
+/*    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_OPTIONS_TYPE_H_
+#define CONCEPT_ZZ_OPTIONS_TYPE_H_
+
+/** @file ZigzagPersistenceOptions.h
+ * @brief Contains @ref Gudhi::zigzag_persistence::ZigzagPersistenceOptions concept.
+ */
+
+namespace Gudhi {
+namespace zigzag_persistence {
+
+/**
+ * @brief List of options used for the matrix maintained for the zigzag persistence computation.
+ */
+struct ZigzagPersistenceOptions {
+  /**
+   * @brief Type for the coefficient field type. Has to support \f$Z_2\f$.
+   */
+  typename field_coeff_type;
+
+  /**
+   * @brief Has to be set to true. Indicates that the computation will be made with \f$Z_2\f$ coefficients.
+   */
+  static const bool is_z2 = true;
+  /**
+   * @brief Type of the columns in the matrix. 
+   * The available column types are given by @ref Gudhi::persistence_matrix::Column_types. 
+   * The column type has to support row access.
+   */
+  static const Column_types column_type;
+
+  /**
+   * @brief Has to be set to true. Indicates that the rows should be directly accessible in the matrix.
+   */
+  static const bool has_row_access = true;
+  /**
+   * @brief Set to true, if the rows should be intrusive lists or to false if they should be sets. True is recommended.
+   * Note that intrusive rows are not compatible with certain column types.
+   */
+  static const bool has_intrusive_rows;
+  /**
+   * @brief Has to set to true. Indicates that the rows of the matrix can be removed.
+   */
+  static const bool has_removable_rows = true;
+  /**
+   * @brief Has to be set to false. Indicates that the matrix should not store birth/death pairs of its columns.
+   */
+  static const bool has_column_pairings = false;
+  /**
+   * @brief Has to be set to true. Enables maintaining the matrix while switching columns.
+   */
+  static const bool has_vine_update = true;
+  /**
+   * @brief If set to true, the matrix can retrieve the representative cycles for the cycle classes. 
+   * This option is useless for zigzag computation and therefore it is recommended to set it to false.
+   */
+  static const bool can_retrieve_representative_cycles;
+  /**
+   * @brief This value has to be defined but will be ignored.
+   */
+  static const bool has_column_compression;
+  /**
+   * @brief Has to be set to false. 
+   * Indicates that the matrix should represent the base of the chain complex and not of the boundary group.
+   */
+  static const bool is_of_boundary_type = false;
+  /**
+   * @brief Has to be set to true. Indicates that the columns of the matrix can be removed.
+   */
+  static const bool has_removable_columns = true;
+  /**
+   * @brief Has to be set to false.
+   * Indicates that the access to the columns will be done through simplex IDs instead of column positions.
+   */
+  static const bool is_indexed_by_position = false;
+};
+
+}  // namespace zigzag_persistence
+}  // namespace Gudhi
+
+#endif  // CONCEPT_ZZ_OPTIONS_TYPE_H_

src/Zigzag_persistence/doc/COPYRIGHT

@@ -0,0 +1,12 @@
+The files of this directory are 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):       Vincent Rouvreau
+
+Copyright (C) 2015 Inria
+
+This gives everyone the freedoms to use openFrameworks in any context:
+commercial or non-commercial, public or private, open or closed source.
+
+You should have received a copy of the MIT License along with this program.
+If not, see https://opensource.org/licenses/MIT.

src/Zigzag_persistence/doc/Intro_zigzag_persistence.h

@@ -0,0 +1,52 @@
+/*    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 DOC_ZIGZAG_PERSISTENCE_INTRO_ZIGZAG_PERSISTENCE_H_
+#define DOC_ZIGZAG_PERSISTENCE_INTRO_ZIGZAG_PERSISTENCE_H_
+
+// needs namespace for Doxygen to link on classes
+namespace Gudhi {
+namespace zigzag_persistence {
+
+/** \defgroup zigzag_persistence Zigzag Persistence
+ * @{
+ * \author    Clément Maria, Hannah Schreiber
+ *
+ * We refer to the introduction page \ref persistent_cohomology for persistent (co)homology for an introduction
+ * to the topic.
+ * Zigzag persistence is a generalization of the latter. While standard persistence only allows to grow the filtered
+ * complex by adding simplices, zigzag persistence also allows removals. Hence the name "zigzag", as the module
+ * diagram will have arrows alterning between forward and backward.
+ *
+ * The implementation is based on the algorithm introduced in \cite zigzag.
+ *
+ * \subsection zigzaginterface Stream-like interface
+ * 
+ * As removals are possible in zigzag filtration, the maximal size of the complex does not depend on the length of the 
+ * filtration anymore. This makes it possible to build very long fine tuned filtrations with relatively small complexes
+ * which can be processed without overreaching memory space. For this purpose, it is possible to feed the module with
+ * information about the filtration "on the fly" to avoid loading the whole filtration at once. Information about the
+ * current complex and current barcode can be retrieved between any steps.
+ * 
+ * \subsection zigzagexamples Examples
+ * 
+ * Here is a list of zigzag persistence examples :
+ * \li \gudhi_example_link{Zigzag_persistence,example_simple_zigzag_filtration.cpp} - A simple example to showcase how
+ * to use the \ref Zigzag_persistence class.
+ *
+ * \li \gudhi_example_link{Zigzag_persistence,example_zzfiltration_from_file.cpp} - An example of a "stream-like" usage
+ * by reading of the filtration from a file.
+ * 
+ * @}
+ */
+}  // namespace zigzag_persistence
+}  // namespace Gudhi
+
+#endif  // DOC_ZIGZAG_PERSISTENCE_INTRO_ZIGZAG_PERSISTENCE_H_

src/Zigzag_persistence/example/CMakeLists.txt

@@ -0,0 +1,18 @@
+project(Zigzag_persistence_examples)
+
+add_executable ( Zigzag_persistence_example_simple_zigzag_filtration example_simple_zigzag_filtration.cpp )
+if(TARGET TBB::tbb)
+  target_link_libraries(Zigzag_persistence_example_simple_zigzag_filtration TBB::tbb)
+endif()
+add_test(NAME Zigzag_persistence_example_simple_zigzag_filtration COMMAND $<TARGET_FILE:Zigzag_persistence_example_simple_zigzag_filtration>)
+
+add_executable ( Zigzag_persistence_example_zzfiltration_from_file example_zzfiltration_from_file.cpp )
+if(TARGET TBB::tbb)
+  target_link_libraries(Zigzag_persistence_example_zzfiltration_from_file TBB::tbb)
+endif()
+file(COPY "zigzag_filtration_example.txt" DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/)
+add_test(NAME Zigzag_persistence_example_zzfiltration_from_file COMMAND $<TARGET_FILE:Zigzag_persistence_example_zzfiltration_from_file> "${CMAKE_CURRENT_BINARY_DIR}/zigzag_filtration_example.txt")
+
+
+
+