Homological Discrete Vector Fields by umenohana13 · Pull Request #9004 · CGAL/cgal

umenohana13 · 2025-07-29T11:00:00Z

Summary of Changes

The pull request contains the first version of:

user manual (still incomplete - persistant homology and Alexander duality are not documented)
reference manual (slightly incomplete as well - the IO classes stores in tools_io are "lightly" documented as they will be revised to integrate IOs inside CGAL)
code (same: the tools_io file will be revised)

Release Management

Affected package(s): HDVF / Surface_mesh_topology
Issue(s) solved (if any):
Feature/Small Feature (if any): https://cgalwiki.geometryfactory.com/CGAL/Members/wiki/Features/Homological_Discrete_Vector_Fields
License and copyright ownership: Not yet validated by my lab but most probably LGPL / LIS laboratory

afabri · 2025-08-04T16:12:23Z

@umenohana13 I started fixing errors showing up in the CI, but there are too many to make. It is now headers compiled in isolation which do not #include all they use. And missing std:: before cout etc.

afabri · 2025-08-07T13:43:10Z

+
+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);


What does cod stand for?

It goes with d : usually we use d for the boundary operator, and d^* for the co-boundary, I wrote cod for co-d.
In our (finite dimension) context, it's just the operator which matrix is the transpose of d (but in a more general context, the definition is more complex.
Is it unclear?

afabri · 2025-08-07T13:44:19Z

+
+The concept `Filtration` describes the requirements for persistent filtrations associated to persistent homology computation.
+
+A filtration is associated to an `AbstractSimplicialComplex`. Each cells is equiped with a scalar value (called its degree) and the filtration is an enumeration of cells in any dimension by increasing degrees.


AbstractSimplicialComplex has no link.

Oups, it's "AbstractChainComplex".
DONE

afabri · 2025-08-07T13:53:34Z

+/*!
+ * \brief Gets HDVF option.
+ */
+int hdvf_opts ();


option() or options()

afabri · 2025-08-07T13:54:21Z

+ *
+ * The function returns `true` if the reduced boundary matrix is null and `false` otherwise.
+ */
+    bool is_perfect_hdvf();


is_perfect()

afabri · 2025-08-07T13:57:04Z

+/// @{
+
+/*!
+ * \brief A operation: pairs two critical cells.


I think you should systematically write A-operation to avoid confusion with the word "A".

In fact at some places you write A() operation which is also ok.

afabri · 2025-08-07T13:59:32Z

+ * \param verbose If `true`, all intermediate reductions are printed out.
+ *
+ */
+std::vector<Pair_cells> compute_perfect_hdvf(bool verbose = false);


Maybe replace Pair_cells with Cell_pair

afabri · 2025-08-07T14:00:55Z

+virtual std::vector<std::vector<int> > psc_labels () const;
+
+/*!
+ * \brief Returns a chain containing the homology generator associated to `cell` (critical cell) of dimension  `q` (in particular for vtk export).


Suggested change

* \brief Returns a chain containing the homology generator associated to `cell` (critical cell) of dimension `q` (in particular for vtk export).

* \brief Returns a chain containing the homology generator associated to `cell` (critical cell) of dimension `q`.

-> Full_lu -> Hdvf -> Couldn't understand how to call generic functions (for Zp and int)?

…th the local member function

-> Sparse matrices now receive the sparse chain type as a tparam -> Updated all classes accordingly -> All tests are OK -> Concepts updated (need checks especially for AbstractSimplicialChainComplex - how to describe the Sparse_matrix structure passed as argument...)

@todo

-> review all the code / examples / tests to comply with new structure @todo: check the documentation (related modifications are commented with warnings)

afabri · 2026-06-15T09:32:22Z

/force-build:v0

github-actions · 2026-06-15T09:35:36Z

The documentation is built. It will be available, after a few minutes, here: https://cgal.github.io/9004/v0/Manual/index.html

afabri · 2026-06-15T10:02:10Z

+Number_types
+Circulator
+Stream_support
+Surface_mesh


Suggested change

Surface_mesh

Surface_mesh

Triangulation_3

We then get a link here

afabri · 2026-06-15T10:05:20Z

+     *
+     * \brief Comparison of two COLUMN matrices.
+     */
+    template <typename _CT, template <typename, int> typename SCT>


You have to write what SCT means

afabri · 2026-06-15T10:05:44Z

+
+    /** \relates Sparse_matrix_core
+     *
+     * \brief Comparison of a COLUMN  and a ROW matrix.


Suggested change

* \brief Comparison of a COLUMN and a ROW matrix.

* \brief Comparison of a `COLUMN` and a `ROW` matrix.

Started to correct all points mentionned

-> modifications according to G. Damiand's review

-> removed ingroup (remaining from HDVF)

sloriot · 2026-10-15T17:15:29Z

@albert-github confirmed that the backtick issue in \exception is fixed in doxygen 1.18.0 and so was a bug in 1.17.0. The fix is in doxygen/doxygen#12172. We can backport it in our custom build if we haven't switch to a newer version when integrating this PR.

gdamiand · 2026-10-16T08:33:32Z

/force-build:v0

github-actions · 2026-10-16T08:36:05Z

There was an error while building the doc:

Traceback (most recent call last):
  File "/home/runner/work/cgal/cgal/Documentation/doc/scripts/html_output_post_processing.py", line 400, in <module>
    main()
  File "/home/runner/work/cgal/cgal/Documentation/doc/scripts/html_output_post_processing.py", line 325, in main
    re_replace_in_file("'src','ftv2",
  File "/home/runner/work/cgal/cgal/Documentation/doc/scripts/html_output_post_processing.py", line 89, in re_replace_in_file
    with codecs.open(fname, encoding='utf-8') as f:
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "<frozen codecs>", line 918, in open
FileNotFoundError: [Errno 2] No such file or directory: 'Manual/dynsections.js'
make[3]: *** [CMakeFiles/doc_with_postprocessing.dir/build.make:70: CMakeFiles/doc_with_postprocessing] Error 1
make[2]: *** [CMakeFiles/Makefile2:13366: CMakeFiles/doc_with_postprocessing.dir/all] Error 2
make[1]: *** [CMakeFiles/Makefile2:13373: CMakeFiles/doc_with_postprocessing.dir/rule] Error 2
make: *** [Makefile:5162: doc_with_postprocessing] Error 2

https://github.com/CGAL/cgal/actions/runs/38874500086

albert-github · 2026-10-16T08:42:46Z

The problem regarding dynsections.js might be related to #9539
(CC: @sloriot )

MaelRL added Not yet approved The feature or pull-request has not yet been approved. Feature CHANGES.md not updated labels Jul 29, 2025

MaelRL added this to the 6.2-beta milestone Jul 29, 2025

MaelRL changed the title ~~Homology new package ab~~ Homological Discrete Vector Fields Jul 29, 2025

This comment was marked as outdated.

Sign in to view

afabri requested changes Aug 7, 2025

View reviewed changes

This comment was marked as outdated.

Sign in to view

afabri reviewed Aug 12, 2025

View reviewed changes

Comment thread HDVF/doc/HDVF/Concepts/HDVF.h Outdated

afabri reviewed Aug 13, 2025

View reviewed changes

Comment thread HDVF/include/CGAL/HDVF/Hdvf_core.h

afabri reviewed Aug 14, 2025

View reviewed changes

Comment thread HDVF/include/CGAL/OSM/Sparse_chain.h Outdated

afabri and others added 8 commits May 21, 2026 07:38

trailing whitespace

afa6909

Fixes (integrating new sparse matrices)

7cf43e3

Tried using is_invertible and inverse

8f37188

-> Full_lu -> Hdvf -> Couldn't understand how to call generic functions (for Zp and int)?

Prefix some calls with CGAL:: so that the compiler does not mix up wi…

b3cdb75

…th the local member function

line is too long

ec9b774

Add #include

8b292af

Update Sparse_matrix depending on Sparse_chain

4d7249d

-> review all the code / examples / tests to comply with new structure @todo: check the documentation (related modifications are commented with warnings)

afabri reviewed Jun 15, 2026

View reviewed changes

umenohana13 added 3 commits June 16, 2026 10:26

Fix

5e302c5

Revision of G. Damiand until HDVF concept

f1d5851

Started to correct all points mentionned

Trailing whitespaces

f7c6775

MaelRL modified the milestones: 6.3-beta, 6.4-beta Sep 24, 2026

umenohana13 and others added 8 commits October 6, 2026 15:07

Review G. Damiand

9b60f99

-> modifications according to G. Damiand's review

Fix Zp.h

779aefb

-> removed ingroup (remaining from HDVF)

Fix Cub_object_io

c012d9f

Trailing whitespaces

9303664

Update dependencies

a0ed7e8

Update dependencies

0045847

option to display only documented items

b0417d9

Update Hdvf.h

547602a


		The concept `Filtration` describes the requirements for persistent filtrations associated to persistent homology computation.

		A filtration is associated to an `AbstractSimplicialComplex`. Each cells is equiped with a scalar value (called its degree) and the filtration is an enumeration of cells in any dimension by increasing degrees.

	* \brief Returns a chain containing the homology generator associated to `cell` (critical cell) of dimension `q` (in particular for vtk export).
	* \brief Returns a chain containing the homology generator associated to `cell` (critical cell) of dimension `q`.

	* \brief Comparison of a COLUMN and a ROW matrix.
	* \brief Comparison of a `COLUMN` and a `ROW` matrix.

Conversation

umenohana13 commented Jul 29, 2025 • edited by MaelRL Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary of Changes

Release Management

Uh oh!

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

afabri commented Aug 4, 2025

Uh oh!

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

Uh oh!

Uh oh!

Uh oh!

afabri commented Jun 15, 2026

Uh oh!

github-actions Bot commented Jun 15, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sloriot commented Oct 15, 2026

Uh oh!

gdamiand commented Oct 16, 2026

Uh oh!

github-actions Bot commented Oct 16, 2026

Uh oh!

albert-github commented Oct 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

umenohana13 commented Jul 29, 2025 •

edited by MaelRL

Loading