multipers 2.3.3b6__cp311-cp311-macosx_10_13_x86_64.whl

multipers/gudhi/gudhi/Persistence_matrix/columns/chain_column_extra_properties.h

@@ -0,0 +1,150 @@
+/*    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) 2022-24 Inria
+ *
+ *    Modification(s):
+ *      - YYYY/MM Author: Description of the modification
+ */
+
+/**
+ * @file chain_column_extra_properties.h
+ * @author Hannah Schreiber
+ * @brief Contains the @ref Gudhi::persistence_matrix::Chain_column_extra_properties class and
+ * @ref Gudhi::persistence_matrix::Dummy_chain_properties structure.
+ */
+
+#ifndef PM_CHAIN_COLUMN_PROP_H
+#define PM_CHAIN_COLUMN_PROP_H
+
+#include <utility>  //std::swap
+
+namespace Gudhi {
+namespace persistence_matrix {
+
+/**
+ * @ingroup persistence_matrix
+ *
+ * @brief Empty structure.
+ * Inherited instead of @ref Chain_column_extra_properties, when the columns are not meant for
+ * @ref chainmatrix "chain matrices".
+ */
+struct Dummy_chain_properties 
+{
+  Dummy_chain_properties([[maybe_unused]] int pivot = 0, [[maybe_unused]] int pair = 0) {}
+
+  friend void swap([[maybe_unused]] Dummy_chain_properties& col1, [[maybe_unused]] Dummy_chain_properties& col2) {}
+};
+
+/**
+ * @class Chain_column_extra_properties chain_column_extra_properties.h \
+ * gudhi/Persistence_matrix/columns/chain_column_extra_properties.h
+ * @ingroup persistence_matrix
+ *
+ * @brief Class managing the pivot and partitioning of columns in @ref Chain_matrix.
+ *
+ * The columns of a @ref chainmatrix "chain matrix" are partitioned in three sets: \f$ F \f$, \f$ G \f$ and \f$ H \f$
+ * with a bijection between \f$ G \f$ and \f$ H \f$. If a column is in \f$ F \f$, the value of
+ * `Chain_column_extra_properties::pairedColumn_` is `-1`, while the value corresponds to the @ref MatIdx index of
+ * the image of the bijection if the column is in either \f$ G \f$ or \f$ H \f$. See @cite zigzag for
+ * more details.
+ * 
+ * @tparam Master_matrix An instantiation of @ref Matrix from which all types and options are deduced.
+ */
+template <class Master_matrix>
+class Chain_column_extra_properties 
+{
+ public:
+  using Index = typename Master_matrix::Index;        /**< @ref MatIdx index type. */
+  using ID_index = typename Master_matrix::ID_index;  /**< @ref IDIdx index type. */
+
+  /**
+   * @brief Default constructor. Sets the pivot and pair to -1, which means "not existing".
+   */
+  Chain_column_extra_properties() : pivot_(-1), pairedColumn_(-1) {}
+  /**
+   * @brief Constructor setting the pivot at the given value and the pair to -1 (i.e. not paired).
+   * 
+   * @param pivot @ref rowindex "Row index" of the pivot. Corresponds to the @ref IDIdx index of the cell represented
+   * by the column.
+   */
+  Chain_column_extra_properties(ID_index pivot) : pivot_(pivot), pairedColumn_(-1) {}
+  /**
+   * @brief Constructor setting the pivot and the pair at the given values.
+   * 
+   * @param pivot @ref rowindex "Row index" of the pivot. Corresponds to the @ref IDIdx index of the cell represented
+   * by the column.
+   * @param pair @ref MatIdx index of the pair of the column.
+   */
+  Chain_column_extra_properties(ID_index pivot, Index pair) : pivot_(pivot), pairedColumn_(pair) {}
+  /**
+   * @brief Copy constructor.
+   * 
+   * @param col Column to copy.
+   */
+  Chain_column_extra_properties(const Chain_column_extra_properties& col)
+      : pivot_(col.pivot_), pairedColumn_(col.pairedColumn_) {}
+  /**
+   * @brief Move constructor.
+   * 
+   * @param col Column to move.
+   */
+  Chain_column_extra_properties(Chain_column_extra_properties&& col)
+      : pivot_(std::exchange(col.pivot_, -1)), pairedColumn_(std::exchange(col.pairedColumn_, -1)) {}
+
+  /**
+   * @brief Returns -1 if the column is not paired, the @ref MatIdx of the pair otherwise.
+   * 
+   * @return -1 if the column is not paired, the @ref MatIdx of the pair otherwise.
+   */
+  Index get_paired_chain_index() const { return pairedColumn_; }
+  /**
+   * @brief Indicates if the column is paired or not.
+   * 
+   * @return true If the column is paired.
+   * @return false Otherwise.
+   */
+  bool is_paired() const { return pairedColumn_ != static_cast<Index>(-1); }
+  /**
+   * @brief Sets the value of the pair.
+   * 
+   * @param other_col @ref MatIdx of the pair column.
+   */
+  void assign_paired_chain(Index other_col) { pairedColumn_ = other_col; }
+  /**
+   * @brief Un-pairs a column.
+   */
+  void unassign_paired_chain() { pairedColumn_ = -1; };
+
+  /**
+   * @brief Assign operator.
+   */
+  Chain_column_extra_properties& operator=(const Chain_column_extra_properties& other) {
+    pivot_ = other.pivot_;
+    pairedColumn_ = other.pairedColumn_;
+    return *this;
+  }
+  /**
+   * @brief Swap operator.
+   */
+  friend void swap(Chain_column_extra_properties& col1, Chain_column_extra_properties& col2) {
+    std::swap(col1.pivot_, col2.pivot_);
+    std::swap(col1.pairedColumn_, col2.pairedColumn_);
+  }
+
+ protected:
+  ID_index get_pivot() const { return pivot_; }
+  void swap_pivots(Chain_column_extra_properties& other) { std::swap(pivot_, other.pivot_); }
+
+ private:
+  ID_index pivot_;      /**< @ref IDIdx index associated to the chain */
+  Index pairedColumn_;  /**< Represents the (F, G x H) partition of the columns.
+                             -1 if in F, @ref MatIdx of image of bijection otherwise. 
+                             The pivot of a column in G will always be smaller than the pivot of its image in H. */
+};
+
+}  // namespace persistence_matrix
+}  // namespace Gudhi
+
+#endif  // PM_CHAIN_COLUMN_PROP_H

multipers/gudhi/gudhi/Persistence_matrix/columns/column_dimension_holder.h

@@ -0,0 +1,106 @@
+/*    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) 2022-24 Inria
+ *
+ *    Modification(s):
+ *      - YYYY/MM Author: Description of the modification
+ */
+
+/**
+ * @file column_dimension_holder.h
+ * @author Hannah Schreiber
+ * @brief Contains the @ref Gudhi::persistence_matrix::Column_dimension_holder class and
+ * @ref Gudhi::persistence_matrix::Dummy_dimension_holder structure.
+ */
+
+#ifndef PM_COLUMN_DIM_HOLDER_H
+#define PM_COLUMN_DIM_HOLDER_H
+
+#include <utility>  //std::swap
+
+namespace Gudhi {
+namespace persistence_matrix {
+
+/**
+ * @ingroup persistence_matrix
+ *
+ * @brief Empty structure.
+ * Inherited instead of @ref Column_dimension_holder, when the columns are not storing a dimension.
+ */
+struct Dummy_dimension_holder 
+{
+  Dummy_dimension_holder() {}
+  template <typename Dimension>
+  Dummy_dimension_holder([[maybe_unused]] Dimension dim) {}
+
+  friend void swap([[maybe_unused]] Dummy_dimension_holder& col1, [[maybe_unused]] Dummy_dimension_holder& col2) {}
+};
+
+/**
+ * @class Column_dimension_holder column_dimension_holder.h gudhi/Persistence_matrix/columns/column_dimension_holder.h
+ * @ingroup persistence_matrix
+ *
+ * @brief Class managing the dimension access of a column.
+ * 
+ * @tparam Master_matrix An instantiation of @ref Matrix from which all types and options are deduced.
+ */
+template <class Master_matrix>
+struct Column_dimension_holder 
+{
+  using Dimension = typename Master_matrix::Dimension;  /**< Dimension value type. */
+
+  /**
+   * @brief Default constructor. Sets the dimension to 0 for @ref boundarymatrix "boundary matrices" and to -1 for @ref chainmatrix "chain matrices".
+   */
+  Column_dimension_holder() : dim_(Master_matrix::Option_list::is_of_boundary_type ? 0 : -1) {}
+  /**
+   * @brief Constructor setting the dimension to the given value.
+   * 
+   * @param dim Dimension of the column.
+   */
+  Column_dimension_holder(Dimension dim) : dim_(dim) {}
+  /**
+   * @brief Copy constructor.
+   * 
+   * @param col Column to copy.
+   */
+  Column_dimension_holder(const Column_dimension_holder& col) : dim_(col.dim_) {}
+  /**
+   * @brief Move constructor.
+   * 
+   * @param col Column to move.
+   */
+  Column_dimension_holder(Column_dimension_holder&& col) : dim_(std::exchange(col.dim_, -1)) {}
+
+  /**
+   * @brief Returns the dimension of the column.
+   * 
+   * @return The dimension of the column.
+   */
+  Dimension get_dimension() const { return dim_; }
+
+  /**
+   * @brief Assign operator.
+   */
+  Column_dimension_holder& operator=(const Column_dimension_holder& other) {
+    dim_ = other.dim_;
+    return *this;
+  }
+  /**
+   * @brief Swap operator.
+   */
+  friend void swap(Column_dimension_holder& col1, Column_dimension_holder& col2) { std::swap(col1.dim_, col2.dim_); }
+
+ protected:
+  void swap_dimension(Column_dimension_holder& other) { std::swap(dim_, other.dim_); }
+
+ private:
+  Dimension dim_;  /**< Dimension of the column. */
+};
+
+}  // namespace persistence_matrix
+}  // namespace Gudhi
+
+#endif  // PM_COLUMN_DIM_HOLDER_H

multipers/gudhi/gudhi/Persistence_matrix/columns/column_utilities.h

@@ -0,0 +1,219 @@
+/*    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) 2024 Inria
+ *
+ *    Modification(s):
+ *      - YYYY/MM Author: Description of the modification
+ */
+
+/**
+ * @file column_utilities.h
+ * @author Hannah Schreiber
+ * @brief Contains helper methods for column addition and column hasher.
+ */
+
+#ifndef PM_COLUMN_UTILITIES_H
+#define PM_COLUMN_UTILITIES_H
+
+#include <cstddef>
+#include <stdexcept>
+
+#include <gudhi/persistence_matrix_options.h>
+
+namespace Gudhi {
+namespace persistence_matrix {
+
+template <class Entry, typename Entry_iterator>
+Entry* _get_entry(const Entry_iterator& itTarget)
+{
+  if constexpr (Entry::Master::Option_list::column_type == Column_types::INTRUSIVE_LIST ||
+                Entry::Master::Option_list::column_type == Column_types::INTRUSIVE_SET) {
+    return &*itTarget;
+  } else {
+    return *itTarget;
+  }
+}
+
+// works only for ordered columns
+template <class Column, class Entry_iterator, typename F1, typename F2, typename F3, typename F4>
+void _generic_merge_entry_to_column(Column& targetColumn,
+                                    Entry_iterator& itSource,
+                                    typename Column::Column_support::iterator& itTarget,
+                                    F1&& process_target,
+                                    F2&& process_source,
+                                    F3&& update_target1,
+                                    F4&& update_target2,
+                                    bool& pivotIsZeroed)
+{
+  typename Column::Entry* targetEntry = _get_entry<typename Column::Entry>(itTarget);
+
+  if (targetEntry->get_row_index() < itSource->get_row_index()) {
+    process_target(targetEntry);
+    ++itTarget;
+  } else if (targetEntry->get_row_index() > itSource->get_row_index()) {
+    process_source(itSource, itTarget);
+    ++itSource;
+  } else {
+    if constexpr (Column::Master::Option_list::is_z2) {
+      //_multiply_*_and_add never enters here so not treated
+      if constexpr (Column::Master::isNonBasic && !Column::Master::Option_list::is_of_boundary_type) {
+        if (targetEntry->get_row_index() == targetColumn.get_pivot()) pivotIsZeroed = true;
+      }
+      targetColumn._delete_entry(itTarget);
+    } else {
+      update_target1(targetEntry->get_element(), itSource);
+      if (targetEntry->get_element() == Column::Field_operators::get_additive_identity()) {
+        if constexpr (Column::Master::isNonBasic && !Column::Master::Option_list::is_of_boundary_type) {
+          if (targetEntry->get_row_index() == targetColumn.get_pivot()) pivotIsZeroed = true;
+        }
+        targetColumn._delete_entry(itTarget);
+      } else {
+        update_target2(targetEntry);
+        if constexpr (Column::Master::Option_list::has_row_access) targetColumn.update_entry(*targetEntry);
+        ++itTarget;
+      }
+    }
+    ++itSource;
+  }
+}
+
+// works only for ordered columns
+template <class Column, class Entry_range, typename F1, typename F2, typename F3, typename F4, typename F5>
+bool _generic_add_to_column(const Entry_range& source,
+                            Column& targetColumn,
+                            F1&& process_target,
+                            F2&& process_source,
+                            F3&& update_target1,
+                            F4&& update_target2,
+                            F5&& finish_target)
+{
+  bool pivotIsZeroed = false;
+
+  auto& target = targetColumn.column_;
+  auto itTarget = target.begin();
+  auto itSource = source.begin();
+  while (itTarget != target.end() && itSource != source.end()) {
+    _generic_merge_entry_to_column(targetColumn, itSource, itTarget,
+                                   process_target, process_source, update_target1, update_target2,
+                                   pivotIsZeroed);
+  }
+
+  finish_target(itTarget);
+
+  while (itSource != source.end()) {
+    process_source(itSource, target.end());
+    ++itSource;
+  }
+
+  return pivotIsZeroed;
+}
+
+template <class Column, class Entry_range>
+bool _add_to_column(const Entry_range& source, Column& targetColumn)
+{
+  return _generic_add_to_column(
+      source,
+      targetColumn,
+      [&]([[maybe_unused]] typename Column::Entry* entryTarget) {},
+      [&](typename Entry_range::const_iterator& itSource, const typename Column::Column_support::iterator& itTarget) {
+        if constexpr (Column::Master::Option_list::is_z2) {
+          targetColumn._insert_entry(itSource->get_row_index(), itTarget);
+        } else {
+          targetColumn._insert_entry(itSource->get_element(), itSource->get_row_index(), itTarget);
+        }
+      },
+      [&](typename Column::Field_element& targetElement, typename Entry_range::const_iterator& itSource) {
+        if constexpr (!Column::Master::Option_list::is_z2)
+          targetColumn.operators_->add_inplace(targetElement, itSource->get_element());
+      },
+      [&]([[maybe_unused]] typename Column::Entry* entryTarget) {},
+      [&]([[maybe_unused]] typename Column::Column_support::iterator& itTarget) {}
+    );
+}
+
+template <class Column, class Entry_range>
+bool _multiply_target_and_add_to_column(const typename Column::Field_element& val,
+                                        const Entry_range& source,
+                                        Column& targetColumn)
+{
+  if (val == 0u) {
+    if constexpr (Column::Master::isNonBasic && !Column::Master::Option_list::is_of_boundary_type) {
+      throw std::invalid_argument("A chain column should not be multiplied by 0.");
+      // this would not only mess up the base, but also the pivots stored.
+    } else {
+      targetColumn.clear();
+    }
+  }
+
+  return _generic_add_to_column(
+      source,
+      targetColumn,
+      [&](typename Column::Entry* entryTarget) {
+        targetColumn.operators_->multiply_inplace(entryTarget->get_element(), val);
+        // targetColumn.RA_opt::update_entry(*itTarget) produces an internal compiler error
+        // even though it works in _generic_add_to_column... Probably because of the lambda.
+        if constexpr (Column::Master::Option_list::has_row_access) targetColumn.update_entry(*entryTarget);
+      },
+      [&](typename Entry_range::const_iterator& itSource, const typename Column::Column_support::iterator& itTarget) {
+        targetColumn._insert_entry(itSource->get_element(), itSource->get_row_index(), itTarget);
+      },
+      [&](typename Column::Field_element& targetElement, typename Entry_range::const_iterator& itSource) {
+        targetColumn.operators_->multiply_and_add_inplace_front(targetElement, val, itSource->get_element());
+      },
+      [&]([[maybe_unused]] typename Column::Entry* entryTarget) {},
+      [&](typename Column::Column_support::iterator& itTarget) {
+        while (itTarget != targetColumn.column_.end()) {
+          typename Column::Entry* targetEntry = _get_entry<typename Column::Entry>(itTarget);
+          targetColumn.operators_->multiply_inplace(targetEntry->get_element(), val);
+          if constexpr (Column::Master::Option_list::has_row_access) targetColumn.update_entry(*targetEntry);
+          itTarget++;
+        }
+      }
+    );
+}
+
+template <class Column, class Entry_range>
+bool _multiply_source_and_add_to_column(const typename Column::Field_element& val,
+                                        const Entry_range& source,
+                                        Column& targetColumn)
+{
+  if (val == 0u) {
+    return false;
+  }
+
+  return _generic_add_to_column(
+      source,
+      targetColumn,
+      []([[maybe_unused]] typename Column::Entry* entryTarget) {},
+      [&](typename Entry_range::const_iterator& itSource, const typename Column::Column_support::iterator& itTarget) {
+        typename Column::Entry* entry =
+            targetColumn._insert_entry(itSource->get_element(), itSource->get_row_index(), itTarget);
+        targetColumn.operators_->multiply_inplace(entry->get_element(), val);
+        if constexpr (Column::Master::Option_list::has_row_access) targetColumn.update_entry(*entry);
+      },
+      [&](typename Column::Field_element& targetElement, typename Entry_range::const_iterator& itSource) {
+        targetColumn.operators_->multiply_and_add_inplace_back(itSource->get_element(), val, targetElement);
+      },
+      [&]([[maybe_unused]] typename Column::Entry* entryTarget) {},
+      []([[maybe_unused]] typename Column::Column_support::iterator& itTarget) {});
+}
+
+// column has to be ordered (ie. not suited for unordered_map and heap) and contain the exact values
+// (ie. not suited for vector and heap). A same column but ordered differently will have another hash value.
+template <class Column>
+std::size_t hash_column(const Column& column)
+{
+  std::size_t seed = 0;
+  for (auto& entry : column) {
+    seed ^= std::hash<unsigned int>()(entry.get_row_index() * static_cast<unsigned int>(entry.get_element())) +
+            0x9e3779b9 + (seed << 6) + (seed >> 2);
+  }
+  return seed;
+}
+
+}  // namespace persistence_matrix
+}  // namespace Gudhi
+
+#endif  // PM_COLUMN_UTILITIES_H