Homological Discrete Vector Fields

.gitignore

@@ -1172,3 +1172,5 @@ patches_after_merge.ply
 CMakeUserPresets.json
 /.cache
 compile_commands.json
+/HDVF/test/HDVF/tmp
+/HDVF/examples/HDVF/tmp

Algebraic_foundations/doc/Algebraic_foundations/CGAL/number_utils.h

@@ -22,7 +22,7 @@ namespace CGAL {
 \ingroup PkgAlgebraicFoundationsRef
 
 The template function `compare()` compares the first argument with respect to
-the second, i.e.\ it returns `CGAL::LARGER` if \f$ x\f$ is larger than \f$ y\f$.
+the second.
 
 In case the argument types `NT1` and `NT2` differ,
 `compare` is performed with the semantic of the type determined via

Constrained_triangulation_3/include/CGAL/Conforming_constrained_Delaunay_triangulation_3.h

@@ -934,7 +934,7 @@ class Conforming_constrained_Delaunay_triangulation_3
    */
   CDT_3_signed_index face_constraint_index(typename Triangulation::Cell_handle ch, int i) const
   {
-    return ch->face_id[static_cast<unsigned>(i)];
+    return ch->ccdt_3_data().face_constraint_index(i);
   }
 
   /*!

Documentation/doc/Documentation/packages.txt

@@ -131,7 +131,11 @@
 \package_listing{Stream_lines_2}
 \package_listing{Classification}
 \package_listing{Heat_method_3}
+
+\cgalPackageSection{PartTopology,Topology}
+
 \package_listing{Surface_mesh_topology}
+\package_listing{HDVF}
 
 \cgalPackageSection{PartSearchStructures,Spatial Searching and Sorting}
 

HDVF/doc/HDVF/Concepts/AbstractChainComplex.h

@@ -0,0 +1,136 @@
+/*!
+\ingroup PkgHDVFConcepts
+\cgalConcept
+
+The concept `AbstractChainComplex` describes the requirements for (topological) chain complexes associated to abstract complexes used in the concept `HDVF`.
+
+It provides methods to:
+
+ - get the dimension of the complex, the number of cells in each dimension
+ - get the boundary and co-boundary of cell(s)
+ - get the vertices of a given cell
+ - output the complex in text format
+
+ Cells are indexed along each dimension and thus identified by their index together with their dimension.
+
+
+\cgalHasModelsBegin
+\cgalHasModelsBare{`CGAL::Homological_discrete_vector_field::Abstract_simplicial_chain_complex<IntegralDomainWithoutDivision>`}
+\cgalHasModelsBare{`CGAL::Homological_discrete_vector_field::Sub_chain_complex_mask<IntegralDomainWithoutDivision, AbstractChainComplex>`}
+\cgalHasModelsEnd
+
+*/
+
+class AbstractChainComplex
+{
+public:
+/// \name Types
+/// @{
+
+/*!
+Type of coefficients ring used to compute homology, model of `IntegralDomainWithoutDivision`
+ */
+typedef CoefficientRing Coefficient_ring;
+
+/*!
+ Type of column-major chains (returned by the boundary operator)
+ */
+typedef CGAL::OSM::Sparse_chain<CoefficientRing, CGAL::OSM::COLUMN> Column_chain;
+
+/*!
+ Type of row-major chains (returned by the co-boundary operator)
+ */
+typedef CGAL::OSM::Sparse_chain<CoefficientRing, CGAL::OSM::ROW> Row_chain ;
+
+/*!
+ Type of column-major sparse matrices (used to store the boundary operator)
+ */
+typedef CGAL::OSM::Sparse_matrix<CoefficientRing, CGAL::OSM::COLUMN> Column_matrix;
+
+/// @}
+
+/// \name Operators
+/// @{
+
+/*!
+Assignment operator.
+
+The operator creates a copy of `complex`.
+ */
+    AbstractChainComplex& operator= (const AbstractChainComplex& complex);
+
+/// @}
+
+/// \name Access functions
+/// @{
+
+/*!
+Returns the dimension of the complex, that is, the largest dimension of cells.
+ */
+int dimension();
+
+/*!
+Returns the number of cells of dimension `q`.
+If `q` is negative of larger than the dimension of the complex, returns 0.
+ */
+size_t number_of_cells(int q);
+
+/*!
+\brief Returns all boundary matrices.
+
+The function returns constant reference to a vector of column-major sparse matrices. The `q`-th element of this vector is the matrix of \f$\partial_q\f$, which gives the boundary of cells of dimension `q`(as a linear combination of `q`-1 cells).
+
+ */
+const vector<Column_matrix> & boundary_matrices() const;
+
+/*!
+ \brief Returns the boundary matrix of dimension `q` (ie.\ the matrix of \f$\partial_q\f$).
+
+The function returns a column-major sparse matrices.
+ */
+const Column_matrix & boundary_matrix(int q) const;
+
+/*!
+ \brief Returns the boundary of the cell of index `id_cell` in dimension `q`.
+
+This boundary is a finite linear combination of cells of dimension `q`-1. It is encoded as a column-major chain (which maps each cell with a non-zero coefficient to this coefficient). This boundary  is thus the `id_cell`-th column of the boundary matrix in dimension `q`.
+
+*/
+Column_chain d(size_t id_cell, int q);
+
+
+/*!
+ \brief Returns the co-boundary of the cell of index `id_cell` in dimension `q`.
+
+This boundary is a finite linear combination of cells of dimension `q`+1. It is encoded as a row-major chain (which maps each cell with a non-zero coefficient to this coefficient). This co-boundary  is thus the `id_cell`-th row of the boundary matrix in dimension `q`+1.
+*/
+Row_chain cod(size_t id_cell, int q);
+
+/*!
+ \brief Returns the vertices of a given cell (that is, the indices of its faces of dimension 0).
+
+*/
+std::vector<size_t> bottom_faces(size_t id_cell, int q) const;
+
+/*!
+ * \brief Returns the cofaces of a given chain in dimension `q`.
+ *
+ * The resulting chain, whatever the storage format of the input, is column-major, lies in dimension `q`+1 and is null if this dimension exceeds the dimension of the complex.
+ *
+ * \tparam CoefficientR `CoefficientRing` of the chain.
+ * \tparam StorageF `StorageFormat` of the chain.
+*/
+template <typename CoefficientR, int StorageF>
+Column_chain cofaces_chain (SparseChain<CoefficientR, StorageF> chain, int q) const;
+
+/// @}
+
+};
+
+
+/*!
+\relates AbstractChainComplex
+Inserts the chain complex in text mode in the stream.
+*/
+std::ostream& operator<<(std::ostream& out, const AbstractChainComplex& complex) const;
+

HDVF/doc/HDVF/Concepts/Filtration.h

@@ -0,0 +1,181 @@
+/*!
+\ingroup PkgHDVFConcepts
+\cgalConcept
+
+The concept `Filtration` describes the requirements for persistent filtrations associated to persistent homology computation.
+
+A filtration is associated to an `AbstractChainComplex`. Each cell is equiped with a scalar value (called its degree) and the filtration is an enumeration of cells in any dimension by increasing degrees.
+
+A filtration class provides:
+
+ - an iterator to visit all cells by increasing degrees.
+ - getters to get the degree of a cell, and the cell of a given index along the filtration.
+ - an overload of `operator<<()` to output filtrations.
+
+Cells are indexed along each dimension and thus identified by their index together with their dimension.
+
+\cgalHasModelsBegin
+\cgalHasModelsBare{`CGAL::Homological_discrete_vector_field::Filtration_core<ChainComplex,Degree>`}
+\cgalHasModelsBare{`CGAL::Homological_discrete_vector_field::Filtration_lower_star<ChainComplex,Degree>`}
+\cgalHasModelsEnd
+
+*/
+
+class Filtration
+{
+public:
+    /*! \brief Type of the underlying complex. */
+    typedef unspecified_type Complex;
+
+    /*! \brief (Scalar) type of degrees (model of `RealEmbeddable`).
+     */
+    typedef unspecified_type Degree ;
+
+    /*! \brief Type of coefficients used to compute homology. */
+    typedef Complex::Coefficient_ring Coefficient_ring;
+
+    /*! \brief Type for indexing uniquely a cell.
+     *
+     * As stated in `AbstractChainComplex`, cells are identified by their dimension, together with their index along this dimension. The type `Cell` stores this pair:
+     *
+     * - First element of the pair: index of the cell.
+     * - Second element of the pair: dimension of the cell.
+     */
+    typedef std::pair<size_t, int> Cell ;
+
+    /*! \brief Value type of the filtration iterator.
+     * Contains a cell (identified by its index and dimension in a `Cell`) and its associated degree.
+     */
+    typedef struct {
+        Cell cell_dim ;
+        Degree degree ;
+    } Filtration_iter_value ;
+
+protected:
+    /*!
+     Type of column-major sparse matrices.
+     */
+    typedef SparseMatrix<Coefficient_ring,CGAL::OSM::COLUMN> Column_matrix ;
+
+    /*!
+     Type of row-major sparse matrices.
+     */
+    typedef SparseMatrix<Coefficient_ring,CGAL::OSM::ROW> Row_matrix ;
+
+    /*!
+     Type of column-major chains.
+     */
+    typedef SparseChain<Coefficient_ring,CGAL::OSM::COLUMN> Column_chain ;
+
+    /*!
+     Type of row-major chains.
+     */
+    typedef SparseChain<Coefficient_ring,CGAL::OSM::ROW> Row_chain ;
+
+public:
+    /**
+     * \brief The iterator over filtration.
+     *
+     * Iterate the filtration by increasing degrees.
+     */
+    struct iterator
+    {
+        // Iterator tags
+        using iterator_category = std::forward_iterator_tag;
+        using difference_type   = std::ptrdiff_t;
+        using value_type        = Filtration_iter_value;
+
+        /*! Iterator constructor
+         */
+        iterator(const Filtration& f, size_t i=0);
+
+        /*! Dereference operator.
+         */
+        value_type operator*() const;
+
+        /*! Gets the index (time) associated to the iterator.
+         */
+        size_t time () const ;
+
+        /*! Gets the `Cell` (cell and its dimension) associated to the iterator.
+         */
+        Cell cell_dim () const ;
+
+        /*! Gets the degree associated to the iterator.
+         */
+        Degree degree () const ;
+
+        /*!
+         * \brief Prefix incrementation.
+         * Move to next index in the filtration.
+         */
+        iterator& operator++();
+
+        /*! \brief Postfix incrementation.
+         */
+        iterator operator++(int);
+
+        /*!
+         * \brief Equality check.
+         * \returns True if the indices are equal.
+         */
+        friend bool operator== (const iterator& a, const iterator& b);
+
+        /*!
+         * \brief Inequality check.
+         * \returns True if the indices are different.
+         */
+        friend bool operator!= (const iterator& a, const iterator& b);
+    };
+
+    /*!
+     * \brief Iterator to the beginning of the filtration.
+     */
+    iterator begin();
+
+    /*!
+     * \brief Returns a past-the-end iterator.
+     */
+    iterator end();
+
+    // getters
+    /*! \brief Gets the filtration size.
+     */
+    size_t size () const;
+
+    /*! \brief Gets the cell (that is cell index and dimension) at the index `i` of the filtration.
+     */
+    Cell cell_index_dimension (size_t i) const;
+
+    /*! \brief Gets the degree of the `i`th element of the filtration.
+     */
+    Degree degree (size_t i) const;
+
+    // Filtration verification
+    /*! \brief Checks that a filtration is valid.
+     * Checks that cells are ordered in increasing degrees and all cells have indices larger than their faces.
+     */
+    bool is_valid() const;
+
+    // Input/output filtration
+
+
+    /**
+     * \brief Exports the filtration time indices.
+     *
+     * The method exports the time index of every cell in each dimension.
+     */
+    vector<vector<size_t> > export_filtration () const
+};
+
+    /*!
+    \relates Filtration
+    \brief extracts a filtration from a stream.
+     */
+    istream & operator>>(istream & in, Filtration &f);
+
+    /*!
+    \relates Filtration
+    \brief Inserts a filtration into a stream.
+     */
+    ostream & operator<<(ostream & out, const Filtration &f);