Homological Discrete Vector Fields

.gitignore

@@ -1173,3 +1173,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

Algebraic_foundations/doc/Algebraic_foundations/Concepts/AlgebraicStructureTraits--IsInvertible.h

@@ -0,0 +1,48 @@
+
+namespace AlgebraicStructureTraits_{
+
+/*!
+\ingroup PkgAlgebraicFoundationsAlgebraicStructuresConcepts
+\cgalConcept
+
+`AdaptableUnaryFunction`,
+returns `true` in case the argument is invertible in the ring.
+
+\cgalRefines{AdaptableUnaryFunction}
+
+\sa `AlgebraicStructureTraits`
+
+*/
+
+class IsInvertible {
+public:
+
+/// \name Types
+/// @{
+
+/*!
+Is `AlgebraicStructureTraits::Boolean`.
+*/
+typedef unspecified_type result_type;
+
+/*!
+Is `AlgebraicStructureTraits::Type`.
+*/
+typedef unspecified_type argument_type;
+
+/// @}
+
+/// \name Operations
+/// @{
+
+/*!
+
+returns true in case there exists an element \f$ y\f$ in the ring such that \f$ x * y \f$ is the one of the ring.
+*/
+result_type operator()(argument_type x);
+
+/// @}
+
+}; /* end IsInvetible */
+
+} /* end of namespace AlgebraicStructureTraits_ */

Algebraic_foundations/doc/Algebraic_foundations/Concepts/Field.h

@@ -22,7 +22,6 @@ Moreover, `CGAL::Algebraic_structure_traits< Field >` is a model of
 \sa `IntegralDomain`
 \sa `UniqueFactorizationDomain`
 \sa `EuclideanRing`
-\sa `Field`
 \sa `FieldWithSqrt`
 \sa `FieldWithKthRoot`
 \sa `FieldWithRootOf`

Algebraic_foundations/doc/Algebraic_foundations/Concepts/FieldWithKthRoot.h

@@ -18,7 +18,6 @@ Moreover, `CGAL::Algebraic_structure_traits< FieldWithKthRoot >` is a model of `
 \sa `EuclideanRing`
 \sa `Field`
 \sa `FieldWithSqrt`
-\sa `FieldWithKthRoot`
 \sa `FieldWithRootOf`
 \sa `AlgebraicStructureTraits`
 

Algebraic_foundations/doc/Algebraic_foundations/Concepts/FieldWithRootOf.h

@@ -20,7 +20,6 @@ Moreover, `CGAL::Algebraic_structure_traits< FieldWithRootOf >` is a model of `A
 \sa `Field`
 \sa `FieldWithSqrt`
 \sa `FieldWithKthRoot`
-\sa `FieldWithRootOf`
 \sa `AlgebraicStructureTraits`
 
 */

Algebraic_foundations/doc/Algebraic_foundations/Concepts/FieldWithSqrt.h

@@ -17,7 +17,6 @@ Moreover, `CGAL::Algebraic_structure_traits< FieldWithSqrt >` is a model of `Alg
 \sa `UniqueFactorizationDomain`
 \sa `EuclideanRing`
 \sa `Field`
-\sa `FieldWithSqrt`
 \sa `FieldWithKthRoot`
 \sa `FieldWithRootOf`
 \sa `AlgebraicStructureTraits`

Algebraic_foundations/doc/Algebraic_foundations/Concepts/IntegralDomain.h

@@ -19,7 +19,6 @@ Moreover, `CGAL::Algebraic_structure_traits< IntegralDomain >` is a model of
 \cgalRefines{IntegralDomainWithoutDivision}
 
 \sa `IntegralDomainWithoutDivision`
-\sa `IntegralDomain`
 \sa `UniqueFactorizationDomain`
 \sa `EuclideanRing`
 \sa `Field`

Algebraic_foundations/doc/Algebraic_foundations/Concepts/IntegralDomainWithoutDivision.h

@@ -25,13 +25,13 @@ Moreover, `CGAL::Algebraic_structure_traits< IntegralDomainWithoutDivision >` is
 - \link AlgebraicStructureTraits::Algebraic_category `CGAL::Algebraic_structure_traits< IntegralDomainWithoutDivision >::Algebraic_category` \endlink derived from `CGAL::Integral_domain_without_division_tag`
 - \link AlgebraicStructureTraits::Is_zero `CGAL::Algebraic_structure_traits< IntegralDomainWithoutDivision >::Is_zero` \endlink  which is a model of `AlgebraicStructureTraits_::IsZero`
 - \link AlgebraicStructureTraits::Is_one `CGAL::Algebraic_structure_traits< IntegralDomainWithoutDivision >::Is_one` \endlink  which is a model of `AlgebraicStructureTraits_::IsOne`
+- \link AlgebraicStructureTraits::Square `CGAL::Algebraic_structure_traits< IntegralDomainWithoutDivision >::Is_invertible` \endlink  which is a model of `AlgebraicStructureTraits_::IsInvertible`
 - \link AlgebraicStructureTraits::Square `CGAL::Algebraic_structure_traits< IntegralDomainWithoutDivision >::Square` \endlink  which is a model of `AlgebraicStructureTraits_::Square`
 - \link AlgebraicStructureTraits::Simplify `CGAL::Algebraic_structure_traits< IntegralDomainWithoutDivision >::Simplify` \endlink which is a model of `AlgebraicStructureTraits_::Simplify`
 - \link AlgebraicStructureTraits::Unit_part `CGAL::Algebraic_structure_traits< IntegralDomainWithoutDivision >::Unit_part` \endlink  which is a model of `AlgebraicStructureTraits_::UnitPart`
 
 \cgalRefines{Assignable,CopyConstructible,DefaultConstructible,EqualityComparable,FromIntConstructible}
 
-\sa `IntegralDomainWithoutDivision`
 \sa `IntegralDomain`
 \sa `UniqueFactorizationDomain`
 \sa `EuclideanRing`

Algebraic_foundations/doc/Algebraic_foundations/Concepts/UniqueFactorizationDomain.h

@@ -27,7 +27,6 @@ derived from `CGAL::Unique_factorization_domain_tag`
 
 \sa `IntegralDomainWithoutDivision`
 \sa `IntegralDomain`
-\sa `UniqueFactorizationDomain`
 \sa `EuclideanRing`
 \sa `Field`
 \sa `FieldWithSqrt`

Algebraic_foundations/doc/Algebraic_foundations/PackageDescription.txt

@@ -38,6 +38,7 @@
 - `AlgebraicStructureTraits`
 - `AlgebraicStructureTraits_::IsZero`
 - `AlgebraicStructureTraits_::IsOne`
+- `AlgebraicStructureTraits_::IsInvertible`
 - `AlgebraicStructureTraits_::Square`
 - `AlgebraicStructureTraits_::Simplify`
 - `AlgebraicStructureTraits_::UnitPart`

Algebraic_foundations/include/CGAL/Algebraic_structure_traits.h

@@ -77,6 +77,7 @@ class Algebraic_structure_traits  {
     typedef Null_functor Square;
     typedef Null_functor Is_zero;
     typedef Null_functor Is_one;
+    typedef Null_functor Is_invertible;
     typedef Null_functor Sqrt;
     typedef Null_functor Kth_root;
     typedef Null_functor Root_of;
@@ -463,6 +464,16 @@ class Algebraic_structure_traits_base< Type_, Field_tag >
       CGAL_IMPLICIT_INTEROPERABLE_BINARY_OPERATOR( Type )
     };
 
+  class Is_invertible
+    : public CGAL::cpp98::unary_function< Type, bool > {
+    public:
+      bool operator()( const Type& t) const {
+        typedef Algebraic_structure_traits<Type> AST;
+        typename AST::Is_zero is_zero;
+        return ! is_zero(t);
+      }
+  };
+
   // maps to \c 1/x by default.
   class Inverse
     : public CGAL::cpp98::unary_function< Type, Type > {

Algebraic_foundations/include/CGAL/number_utils.h

@@ -89,6 +89,14 @@ is_one( const AS& x ) {
     return is_one( x );
 }
 
+template< class AS >
+inline
+typename Algebraic_structure_traits<AS>::Is_invertible::result_type
+is_invertible( const AS& x ) {
+    typename Algebraic_structure_traits< AS >::Is_invertible is_invertible;
+    return is_invertible( x );
+}
+
 template< class AS >
 inline
 typename Algebraic_structure_traits< AS >::Sqrt::result_type

Algebraic_foundations/test/Algebraic_foundations/Algebraic_structure_traits.cpp

@@ -42,6 +42,7 @@ int main(){
     CGAL_IS_AST_NULL_FUNCTOR (  Square);
     CGAL_IS_AST_NULL_FUNCTOR (  Is_zero);
     CGAL_IS_AST_NULL_FUNCTOR (  Is_one);
+    CGAL_IS_AST_NULL_FUNCTOR (  Is_invertible);
     CGAL_IS_AST_NULL_FUNCTOR (  Sqrt);
     CGAL_IS_AST_NULL_FUNCTOR (  Kth_root);
     CGAL_IS_AST_NULL_FUNCTOR (  Root_of);

Documentation/doc/Documentation/packages.txt

@@ -127,7 +127,6 @@
 \package_listing{Surface_mesh_skeletonization}
 \package_listing{Surface_mesh_approximation}
 \package_listing{Heat_method_3}
-\package_listing{Surface_mesh_topology}
 
 \cgalPackageSection{PartPointSetProcessing,Point Set Processing}
 
@@ -140,6 +139,11 @@
 \package_listing{Stream_lines_2}
 \package_listing{Classification}
 
+\cgalPackageSection{PartTopology,Topology}
+
+\package_listing{Surface_mesh_topology}
+\package_listing{HDVF}
+
 \cgalPackageSection{PartSearchStructures,Spatial Searching and Sorting}
 
 \package_listing{Point_set_2}

HDVF/doc/HDVF/Concepts/AbstractChainComplex.h

@@ -0,0 +1,179 @@
+/*!
+ \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>`}
+ \cgalHasModelsEnd
+
+ */
+
+class AbstractChainComplex
+{
+public:
+    /// \name Types
+    /// @{
+
+    /*!
+     Type of coefficients ring used to compute homology, model of `IntegralDomainWithoutDivision`
+     */
+    typedef unspecified_type Coefficient_ring;
+
+    /**
+     Type of structure of sparse matrix used.
+
+     A model of `SparseMatrixStructure` providing a model of `SparseChain` and an associated model of `SparseMatrix`.
+
+     \warning Check if the concept `SparseMatrixStructure`and documentation are correct...
+     */
+    typedef unspecified_type Sparse_matrix_structure;
+
+    /*!
+     Type of column-major chains (returned by the boundary operator)
+     */
+    typedef Sparse_matrix_structure:: template Sparse_chain_type<Coefficient_ring, CGAL::OSM::COLUMN> Column_chain;
+
+    /*!
+     Type of row-major chains (returned by the co-boundary operator)
+     */
+    typedef Sparse_matrix_structure:: template Sparse_chain_type<Coefficient_ring, CGAL::OSM::ROW> Row_chain ;
+
+    /*!
+     Type of column-major sparse matrices (used to store the boundary operator)
+     */
+    typedef Sparse_matrix_structure:: template Sparse_matrix_type<Coefficient_ring, CGAL::OSM::COLUMN> Column_matrix;
+
+    /// @}
+
+    /// \name Verification operations
+    /// @{
+
+    /** \brief Checks if `q` belongs to the range of dimensions of cells in the complex. */
+    bool is_valid_cell_dimension(int q);
+    /** \brief Checks if the cell of index `i` and dimension `q` belongs to the range of dimensions of cells in the complex. */
+    bool is_valid_cell(size_t i, int q);
+
+    /// @}
+
+
+    /// \name Access functions
+    /// @{
+
+    /*!
+     \brief Returns the dimension of the complex.
+     *
+     * This dimension is the largest dimension of cells.
+     *
+     * \return The dimension of the complex.
+     */
+    int dimension();
+
+    /** \brief Get (unique) object Id.
+     *
+     * For comparison of constant references to the complex.
+     */
+    size_t id () const;
+
+    /*!
+     \brief Returns the number of cells in a given dimension.
+     *
+     * \param q Dimension along which the number of cells is returned.
+     *
+     * \return Number of cells in dimension `q`. If `q` is not in the interval `[0,d]` with `d` the dimension of the complex, the function returns an empty column chain.
+     */
+    size_t number_of_cells(int q);
+
+    /*!
+     \brief Returns a constant reference to the vector of boundary matrices (along each dimension).
+     *
+     * The q-th element of this vector is a column-major sparse matrix containing the boundaries of q-cells (i.e. rows encode q-1 cells and columns q cells).
+     *
+     * \return A constant reference to the vector of column-major boundary matrices along each dimension.
+     */
+    const vector<Column_matrix> & boundary_matrices() const;
+
+    /*!
+     \brief Returns a constant reference over the boundary matrix of dimension `q` (i.e.\ column-major matrix of \f$\partial_q\f$).
+     *
+     * It is a column-major sparse matrix containing the boundaries of q-cells (i.e. rows encode q-1 cells and columns q cells).
+     *
+     * \param q Dimension of the boundary matrix (i.e. columns will contain the boundary of dimension q cells).
+     *
+     * \return A constant reference over the column-major sparse matrix containing the matrix of the boundary operator of dimension q.
+     */
+    const Column_matrix & boundary_matrix(int q) const;
+
+    /*!
+     * \brief Returns the boundary of the cell `id_cell` in dimension `q`.
+     *
+     * \param id_cell %Index of the cell.
+     * \param q Dimension of the cell.
+     *
+     * \return A copy of the column-major chain containing the boundary of the cell id_cell in dimension `q`. If `q` is  not in the interval `[0,d]` with `d` the dimension of the complex, the function returns an empty column chain.
+     */
+    Column_chain d(size_t id_cell, int q);
+
+
+    /*!
+     \brief Returns the co-boundary of the cell `id_cell` in dimension `q`.
+     *
+     * This chain is actually a row of the boundary matrix in dimension `q`.
+     *
+     * \warning As the boundary matrix is stored column-major, this entails crossing the full matrix to extract the row coefficients (O(number of non empty columns))
+     *
+     * \param id_cell %Index of the cell.
+     * \param q Dimension of the cell.
+     *
+     * \return The row-major chain containing the co-boundary of the cell id_cell in dimension `q`. If `q` is not in the interval `[0,d]` with `d` the dimension of the complex, the function returns an empty row chain.
+     */
+    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;
+
+    /// @}
+
+    /// \name Input, output
+    /// @{
+    ///
+    /*!
+     \brief Inserts the chain complex in text mode in the stream.
+
+     Displays the number of cells in each dimension and the boundary matrix in each dimension.
+
+     \param out The output stream.
+     \param complex Constant reference over the complex considered.
+     */
+    friend std::ostream& operator<<(std::ostream& out, const AbstractChainComplex& complex) const;
+    /// @}
+};
+
+
+
+