diff --git a/biblio/bibliography.bib b/biblio/bibliography.bib index 35ddf880b1..32727c079f 100644 --- a/biblio/bibliography.bib +++ b/biblio/bibliography.bib @@ -38,10 +38,32 @@ @article{Carriere16 year = {2017} } -@inproceedings{zigzag_reflection, - author = {Jean-Daniel Boissonnat and Cl\'ement Maria and Steve Oudot}, - title = {Zigzag Persistent Homology Algorithm via Reflections}, - year = {2014 $\ \ \ \ \ \ \ \ \ \ \ $ \emph{In Preparation}}, +@inproceedings{zigzag, + author = {Cl{\'{e}}ment Maria and + Steve Y. Oudot}, + title = {Zigzag Persistence via Reflections and Transpositions}, + booktitle = {Proceedings of the Twenty-Sixth Annual {ACM-SIAM} Symposium on Discrete + Algorithms, {SODA} 2015, San Diego, CA, USA, January 4-6, 2015}, + pages = {181--199}, + publisher = {{SIAM}}, + year = {2015}, + url = {https://doi.org/10.1137/1.9781611973730.14}, + doi = {10.1137/1.9781611973730.14} +} + +@inproceedings{zigzag_morse, + author = {Cl{\'{e}}ment Maria and + Hannah Schreiber}, + title = {Discrete Morse Theory for Computing Zigzag Persistence}, + booktitle = {Algorithms and Data Structures - 16th International Symposium, {WADS} + 2019, Edmonton, AB, Canada, August 5-7, 2019, Proceedings}, + series = {Lecture Notes in Computer Science}, + volume = {11646}, + pages = {538--552}, + publisher = {Springer}, + year = {2019}, + url = {https://doi.org/10.1007/978-3-030-24766-9\_39}, + doi = {10.1007/978-3-030-24766-9\_39} } @article{Cohen-Steiner2009, @@ -186,7 +208,7 @@ @inproceedings{DBLP:conf/compgeom/CarlssonSM09 ee = {http://doi.acm.org/10.1145/1542362.1542408}, bibsource = {DBLP, http://dblp.uni-trier.de} } -@inproceedings{DBLP:conf/compgeom/Cohen-SteinerEM06, +@inproceedings{vineyards, author = {David Cohen-Steiner and Herbert Edelsbrunner and Dmitriy Morozov}, @@ -195,7 +217,8 @@ @inproceedings{DBLP:conf/compgeom/Cohen-SteinerEM06 year = {2006}, pages = {119-126}, ee = {http://doi.acm.org/10.1145/1137856.1137877}, - bibsource = {DBLP, http://dblp.uni-trier.de} + bibsource = {DBLP, http://dblp.uni-trier.de}, + url = {https://doi.org/10.1145/1137856.1137877} } @article{quiverrepresentations_derksenweyman, diff --git a/src/Persistence_matrix/concept/FieldOperators.h b/src/Persistence_matrix/concept/FieldOperators.h index 1f5173e51d..86ea036349 100644 --- a/src/Persistence_matrix/concept/FieldOperators.h +++ b/src/Persistence_matrix/concept/FieldOperators.h @@ -17,10 +17,13 @@ namespace Gudhi { namespace persistence_matrix { -/** @brief Concept of the field operator classes needed for the class @ref Matrix. +/** + * @ingroup persistence_matrix * - * Implementations of this concept are @ref Zp_field_operators, @ref Z2_field_operators, - * @ref Multi_field_operators and @ref Multi_field_small_operators. + * @brief Concept of the field operator classes needed for the class @ref Matrix. + * + * Implementations of this concept are @ref Gudhi::persistence_fields::Zp_field_operators, @ref Gudhi::persistence_fields::Z2_field_operators, + * @ref Gudhi::persistence_fields::Multi_field_operators and @ref Gudhi::persistence_fields::Multi_field_operators_with_small_characteristics. */ class FieldOperators { diff --git a/src/Persistence_matrix/concept/PersistenceMatrixColumn.h b/src/Persistence_matrix/concept/PersistenceMatrixColumn.h index 5a0bb99cd5..60dd9feb1a 100644 --- a/src/Persistence_matrix/concept/PersistenceMatrixColumn.h +++ b/src/Persistence_matrix/concept/PersistenceMatrixColumn.h @@ -17,7 +17,10 @@ namespace Gudhi { namespace persistence_matrix { -/** @brief Concept of the column classes used by the @ref Matrix class. +/** + * @ingroup persistence_matrix + * + * @brief Concept of the column classes used by the @ref Matrix class. * * Implementations of this concept are @ref Heap_column, @ref List_column, @ref Vector_column, @ref Naive_vector_column * @ref Set_column, @ref Unordered_set_column, @ref PersistenceMatrixColumn and @ref Intrusive_set_column. @@ -52,8 +55,8 @@ class PersistenceMatrixColumn : using Cell_constructor = unspecified; /**< @ref Cell factory. */ using Field_operators = unspecified; /**< Follows the @ref FieldOperators concept. */ using Field_element_type = unspecified; /**< Type of a field element. */ - using index = unspecified; /**< Type of MatIdx index. */ - using id_index = unspecified; /**< Type of IDIdx index. */ + using index = unspecified; /**< Type of @ref MatIdx index. */ + using id_index = unspecified; /**< Type of @ref IDIdx index. */ using dimension_type = unspecified; /**< Type for dimension value. */ using Cell = unspecified; /**< @ref Cell. */ using Column_type = unspecified; /**< Type of cell container. */ @@ -94,7 +97,7 @@ class PersistenceMatrixColumn : * @tparam Container_type Range of @ref Matrix::cell_rep_type. Assumed to have a begin(), end() and size() method. * @tparam Row_container_type Either std::map if @ref PersistenceMatrixOptions::has_removable_rows is true or * std::vector. - * @param columnIndex MatIdx column index that should be specified to the cells. + * @param columnIndex @ref MatIdx column index that should be specified to the cells. * @param nonZeroRowIndices Range of @ref Matrix::cell_rep_type representing all rows with non zero values. * @param rowContainer Pointer to the row container that will be forwarded to @ref Row_access at construction. * @param operators Pointer to the field operators. @@ -129,7 +132,7 @@ class PersistenceMatrixColumn : * @tparam Container_type Range of @ref Matrix::cell_rep_type. Assumed to have a begin(), end() and size() method. * @tparam Row_container_type Either std::map if @ref PersistenceMatrixOptions::has_removable_rows is true or * std::vector. - * @param columnIndex MatIdx column index that should be specified to the cells. + * @param columnIndex @ref MatIdx column index that should be specified to the cells. * @param nonZeroRowIndices Range of @ref Matrix::cell_rep_type representing all rows with non zero values. * @param dimension Dimension of the column. Is ignored if the dimension is not stored. * @param rowContainer Pointer to the row container that will be forwarded to @ref Row_access at construction. @@ -164,7 +167,7 @@ class PersistenceMatrixColumn : * @tparam Row_container_type Either std::map if @ref PersistenceMatrixOptions::has_removable_rows is true or * std::vector. * @param column Column to copy. - * @param columnIndex MatIdx column index of the new column once copied. + * @param columnIndex @ref MatIdx column index of the new column once copied. * @param rowContainer Pointer to the row container that will be forwarded to @ref Row_access. * @param operators Pointer to the field operators. * If null pointer, the pointer in @p column is choosen instead. @@ -227,12 +230,12 @@ class PersistenceMatrixColumn : * @brief Reorders the column with the given map of row indices. Also changes the column index stored in the * cells if row access is enabled and @p columnIndex is not -1. * - * Only useful for base and boundary matrices using lazy swaps. + * Only useful for base and @ref boundarymatrix "boundary matrices" using lazy swaps. * * @tparam Map_type Map with an `at` method. * @param valueMap Map such that `valueMap.at(i)` indicates the new row index of the cell * at current row index `i`. - * @param columnIndex New MatIdx column index of the column. If -1, the index does not change. Ignored if + * @param columnIndex New @ref MatIdx column index of the column. If -1, the index does not change. Ignored if * the row access is not enabled. Default value: -1. */ template @@ -240,14 +243,14 @@ class PersistenceMatrixColumn : /** * @brief Zeros/empties the column. * - * Only useful for base and boundary matrices. Used in `zero_column` and in the reduction algorithm + * Only useful for base and @ref boundarymatrix "boundary matrices". Used in `zero_column` and in the reduction algorithm * for the persistence barcode. */ void clear(); /** * @brief Zeros the cell at given row index. * - * Only useful for base and boundary matrices. Used in `zero_cell` and during vine swaps. + * Only useful for base and @ref boundarymatrix "boundary matrices". Used in `zero_cell` and during vine swaps. * * @warning For @ref Vector_column, do not clear a cell that was already at zero or the results of @ref size and * @ref is_empty will be wrong. @@ -259,7 +262,7 @@ class PersistenceMatrixColumn : /** * @brief Returns the row index of the pivot. If the column does not have a pivot, returns -1. * - * Only useful for boundary and chain matrices. + * Only useful for boundary and @ref chainmatrix "chain matrices". * * @return Row index of the pivot or -1. */ @@ -269,7 +272,7 @@ class PersistenceMatrixColumn : * * Has to have value 1 if \f$ Z_2 \f$ coefficients are used. * - * Only useful for boundary and chain matrices. + * Only useful for boundary and @ref chainmatrix "chain matrices". * * @return The value of the pivot or 0. */ diff --git a/src/Persistence_matrix/concept/PersistenceMatrixOptions.h b/src/Persistence_matrix/concept/PersistenceMatrixOptions.h index 97e540e52f..f84c5eb3f5 100644 --- a/src/Persistence_matrix/concept/PersistenceMatrixOptions.h +++ b/src/Persistence_matrix/concept/PersistenceMatrixOptions.h @@ -14,10 +14,15 @@ * @brief Contains the concept for the matrix options. */ +/// Gudhi namespace. namespace Gudhi { +/// Persistence matrix namespace. namespace persistence_matrix { -/** @brief Concept of the template parameter for the class @ref Matrix. +/** + * @ingroup persistence_matrix + * + * @brief Concept of the template parameter for the class @ref Matrix. * * An implementation of this concept is @ref Default_options. * If you want to provide your own, it is recommended that you derive from it and override some parts instead of @@ -61,25 +66,25 @@ struct PersistenceMatrixOptions static const Column_indexation_types column_indexation_type; /** - * @brief Only enabled for base matrices (i.e., none of the following is true: @ref has_column_pairings, + * @brief Only enabled for @ref basematrix "base matrices" (i.e., none of the following is true: @ref has_column_pairings, * @ref has_vine_update, @ref can_retrieve_representative_cycles), is ignored otherwise. * If set to true, two identical columns in the matrix are not explicitely stored separately but are represented * by a same column. * - * Note that some methods of the base matrix are not available when true: - * - @ref insert_column(const Container_type& column, index columnIndex), - * - @ref zero_column(index columnIndex), - * - @ref zero_cell(index columnIndex, id_index rowIndex), - * - @ref swap_columns(index columnIndex1, index columnIndex2), - * - @ref swap_rows(index rowIndex1, index rowIndex2), - * - @ref remove_column(index columnIndex), - * - @ref remove_last(). + * Note that some methods of the @ref basematrix "base matrix" are not available when true: + * - @ref Matrix::insert_column ( const Container_type& column, index columnIndex ), + * - @ref Matrix::zero_column ( index columnIndex ), + * - @ref Matrix::zero_cell ( index columnIndex, id_index rowIndex ), + * - @ref Matrix::swap_columns ( index columnIndex1, index columnIndex2 ), + * - @ref Matrix::swap_rows ( index rowIndex1, index rowIndex2 ), + * - @ref Matrix::remove_column ( index columnIndex ), + * - @ref Matrix::remove_last ( ). */ static const bool has_column_compression; /** - * @brief Only enabled for base matrices or simple boundary matrices, i.e., when both + * @brief Only enabled for @ref basematrix "base matrices" or simple @ref boundarymatrix "boundary matrices", i.e., when both * @ref has_vine_update and @ref can_retrieve_representative_cycles are false. - * If set to true, the methods @ref swap_columns and @ref swap_rows are enabled. + * If set to true, the methods @ref Matrix::swap_columns and @ref Matrix::swap_rows are enabled. */ static const bool has_column_and_row_swaps; @@ -87,15 +92,16 @@ struct PersistenceMatrixOptions * @brief If set to true, the underlying container containing the matrix columns is an std::unordered_map. * If set to false, the container is a std::vector. By default, it is recommended to set it to false, but some * methods require it to be true to be enabled: - * - @ref remove_column(index columnIndex) for base matrices, - * - @ref remove_maximal_face(index columnIndex) for chain matrices, - * - @ref remove_maximal_face(id_index faceIndex, const std::vector& columnsToSwap) for chain matrices, - * - @ref remove_last() for chain matrices if @ref has_vine_update is true. + * - @ref Matrix::remove_column ( index columnIndex ) for @ref basematrix "base matrices", + * - @ref Matrix::remove_maximal_face ( index columnIndex ) for @ref chainmatrix "chain matrices", + * - @ref Matrix::remove_maximal_face ( id_index faceIndex, const std::vector& columnsToSwap ) + * for @ref chainmatrix "chain matrices", + * - @ref Matrix::remove_last ( ) for @ref chainmatrix "chain matrices" if @ref has_vine_update is true. */ static const bool has_map_column_container; /** - * @brief If set to true, enables the methods @ref remove_maximal_face and @ref remove_last, except for base matrices - * when @ref has_column_compression is true. + * @brief If set to true, enables the methods @ref Matrix::remove_maximal_face and @ref Matrix::remove_last, + * except for @ref basematrix "base matrices" when @ref has_column_compression is true. */ static const bool has_removable_columns; @@ -111,49 +117,50 @@ struct PersistenceMatrixOptions static const bool has_intrusive_rows; /** * @brief Only enabled if @ref has_row_access is true, ignored otherwise. - * If set to true, the underlying container containing the rows is an std::map and for chain matrices, - * enables the method @ref erase_row (always enabled for other matrix types). + * If set to true, the underlying container containing the rows is an std::map and for @ref chainmatrix "chain matrices", + * enables the method @ref Matrix::erase_row (always enabled for other matrix types). * If set to false, the container is a std::vector. */ static const bool has_removable_rows; /** - * @brief Only enabled for boundary and chain matrices, i.e., when at least one of the following is true: + * @brief Only enabled for boundary and @ref chainmatrix "chain matrices", i.e., when at least one of the following is true: * @ref has_column_pairings, @ref has_vine_update or @ref can_retrieve_representative_cycles. Is ignored otherwise. - * If set to true, the matrix is a boundary matrix. If set to false, the matrix is a chain matrix. + * If set to true, the matrix is a @ref boundarymatrix "boundary matrix". If set to false, the matrix is a @ref chainmatrix "chain matrix". */ static const bool is_of_boundary_type; /** - * @brief Only enabled for boundary and chain matrices, i.e., when at least one of the following is true: + * @brief Only enabled for boundary and @ref chainmatrix "chain matrices", i.e., when at least one of the following is true: * @ref has_column_pairings, @ref has_vine_update or @ref can_retrieve_representative_cycles. Is ignored otherwise * (the notion of dimension makes generally no sense then). - * If set to true, enables the method @ref get_max_dimension. If set to false, the method is disabled except when - * @ref has_column_pairings is true and @ref has_vine_update and @ref can_retrieve_representative_cycles are both + * If set to true, enables the method @ref Matrix::get_max_dimension. If set to false, the method is disabled except + * when @ref has_column_pairings is true and @ref has_vine_update and @ref can_retrieve_representative_cycles are both * false. In this case, the method is always available. */ static const bool has_matrix_maximal_dimension_access; /** - * @brief If set to true, enables the method @ref get_current_barcode. The matrix will then either be a boundary - * matrix (if @ref is_of_boundary_type is true), or a chain matrix (if @ref is_of_boundary_type is false). + * @brief If set to true, enables the method @ref Matrix::get_current_barcode. The matrix will then either be a + * @ref boundarymatrix "boundary matrix" (if @ref is_of_boundary_type is true), or a @ref chainmatrix "chain matrix" (if @ref is_of_boundary_type is false). */ static const bool has_column_pairings; /** - * @brief If set to true, enables the methods @ref vine_swap and @ref vine_swap_with_z_eq_1_case. - * The matrix will then either be a boundary matrix (if @ref is_of_boundary_type is true), - * or a chain matrix (if @ref is_of_boundary_type is false). + * @brief If set to true, enables the methods @ref Matrix::vine_swap and @ref Matrix::vine_swap_with_z_eq_1_case. + * The matrix will then either be a @ref boundarymatrix "boundary matrix" (if @ref is_of_boundary_type is true), + * or a @ref chainmatrix "chain matrix" (if @ref is_of_boundary_type is false). */ static const bool has_vine_update; /** - * @brief If set to true, enables the methods @ref update_representative_cycles and @ref get_representative_cycles. - * The matrix will then either be a boundary matrix (if @ref is_of_boundary_type is true), - * or a chain matrix (if @ref is_of_boundary_type is false). + * @brief If set to true, enables the methods @ref Matrix::update_representative_cycles and + * @ref Matrix::get_representative_cycles. + * The matrix will then either be a @ref boundarymatrix "boundary matrix" (if @ref is_of_boundary_type is true), + * or a @ref chainmatrix "chain matrix" (if @ref is_of_boundary_type is false). */ static const bool can_retrieve_representative_cycles; // not implemented yet // /** - // * @brief Only enabled for boundary and chain matrices, i.e., when at least one of the following is true: + // * @brief Only enabled for boundary and @ref chainmatrix "chain matrices", i.e., when at least one of the following is true: // * @ref has_column_pairings, @ref has_vine_update or @ref can_retrieve_representative_cycles. // * Is ignored otherwise // * If set to true, the matrix is decomposed in several submatrices containing each all the diff --git a/src/Persistence_matrix/doc/COPYRIGHT b/src/Persistence_matrix/doc/COPYRIGHT new file mode 100644 index 0000000000..236bfc6351 --- /dev/null +++ b/src/Persistence_matrix/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): Hannah Schreiber + +Copyright (C) 2024 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. diff --git a/src/Persistence_matrix/doc/Intro_field_elements_and_operators.h b/src/Persistence_matrix/doc/Intro_field_elements_and_operators.h new file mode 100644 index 0000000000..17d0fd3267 --- /dev/null +++ b/src/Persistence_matrix/doc/Intro_field_elements_and_operators.h @@ -0,0 +1,54 @@ +/* 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 + */ + +#ifndef DOC_PERSISTENCE_MATRIX_INTRO_FIELDS_H_ +#define DOC_PERSISTENCE_MATRIX_INTRO_FIELDS_H_ + +// needs namespace for Doxygen to link on classes +namespace Gudhi { +namespace persistence_fields { + +/** \defgroup persistence_fields Persistence Fields + * @{ + * \author Hannah Schreiber + * + * The module provides a data structure for matrices, in particular thought for matrices representing filtered complexes + * and used as backend for persistence algorithms, such at persistent homology, \ref persistent_cohomology, + * or zigzag. TODO: refs. + * + * The structure provides several functionnalities which can be enabled or disabled through a structure following + * the @ref PersistenceMatrixOptions concept which is then used as template parameter. + * The main functionnalities are: + * @li column and row access, + * @li column addition and scalar multiplication, + * @li removal of maximal faces while maintaining a valid reduced @ref boundarymatrix "boundary matrix" or compatible chain complex base + * and a valid barcode with respect to the new filtration, + * @li computation of persistent homology (but note that if the barcode is your only necessity, using the + * \ref persistent_cohomology module is often more performant), + * @li computation of representative cycles for the cycle classes, + * @li swapping of two consecutive faces in a filtration (cf. vineyards) while maintaining a valid reduced boundary + * matrix or compatible chain complex base and a valid barcode with respect to the new filtration, + * + * + * \subsection fieldsexamples Examples + * + * Here is a list of examples using the module: TODO: + * \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 persistence_fields +} // namespace Gudhi + +#endif // DOC_PERSISTENCE_MATRIX_INTRO_FIELDS_H_ diff --git a/src/Persistence_matrix/doc/Intro_persistence_matrix.h b/src/Persistence_matrix/doc/Intro_persistence_matrix.h new file mode 100644 index 0000000000..19c5d0c508 --- /dev/null +++ b/src/Persistence_matrix/doc/Intro_persistence_matrix.h @@ -0,0 +1,54 @@ +/* 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 + */ + +#ifndef DOC_PERSISTENCE_MATRIX_INTRO_PERSISTENCE_MATRIX_H_ +#define DOC_PERSISTENCE_MATRIX_INTRO_PERSISTENCE_MATRIX_H_ + +// needs namespace for Doxygen to link on classes +namespace Gudhi { +namespace persistence_matrix { + +/** \defgroup persistence_matrix Persistence Matrix + * @{ + * \author Hannah Schreiber + * + * The module provides a data structure for matrices, in particular thought for matrices representing filtered complexes + * and used as backend for persistence algorithms, such at persistent homology, \ref persistent_cohomology, + * or zigzag. TODO: refs. + * + * The structure is entirely accessed via the class @ref Matrix and it provides several functionnalities which can + * be enabled or disabled through a template argument following the @ref PersistenceMatrixOptions concept. + * The main functionnalities are: + * @li column and row access, + * @li column addition and scalar multiplication, + * @li removal of maximal faces while maintaining a valid reduced @ref boundarymatrix "boundary matrix" or compatible chain complex base + * and a valid barcode with respect to the new filtration, + * @li computation of persistent homology (but note that if the barcode is your only necessity, using the + * \ref persistent_cohomology module is often more performant), + * @li computation of representative cycles for the cycle classes, + * @li swapping of two consecutive faces in a filtration (cf. vineyards @cite vineyards) while maintaining a valid reduced boundary + * matrix or compatible chain complex base and a valid barcode with respect to the new filtration, + * + * + * \subsection matrixexamples Examples + * + * Here is a list of examples using the module: TODO: + * \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 persistence_matrix +} // namespace Gudhi + +#endif // DOC_PERSISTENCE_MATRIX_INTRO_PERSISTENCE_MATRIX_H_ diff --git a/src/Persistence_matrix/include/gudhi/Fields/Multi_field.h b/src/Persistence_matrix/include/gudhi/Fields/Multi_field.h index 6fcfbf5b06..ce69f46480 100644 --- a/src/Persistence_matrix/include/gudhi/Fields/Multi_field.h +++ b/src/Persistence_matrix/include/gudhi/Fields/Multi_field.h @@ -17,8 +17,14 @@ #include namespace Gudhi { -namespace persistence_matrix { +namespace persistence_fields { +/** + * @ingroup persistence_fields + * + * @brief TODO: + * + */ template class Multi_field_element { public: @@ -416,7 +422,7 @@ inline constexpr bool Multi_field_element::_is_prime(const int return true; } -} //namespace persistence_matrix +} //namespace persistence_fields } //namespace Gudhi #endif // MATRIX_FIELD_MULTI_H_ diff --git a/src/Persistence_matrix/include/gudhi/Fields/Multi_field_operators.h b/src/Persistence_matrix/include/gudhi/Fields/Multi_field_operators.h index 66bf20a463..5747684356 100644 --- a/src/Persistence_matrix/include/gudhi/Fields/Multi_field_operators.h +++ b/src/Persistence_matrix/include/gudhi/Fields/Multi_field_operators.h @@ -17,8 +17,14 @@ #include namespace Gudhi { -namespace persistence_matrix { +namespace persistence_fields { +/** + * @ingroup persistence_fields + * + * @brief TODO: + * + */ class Multi_field_operators { public: using element_type = mpz_class; @@ -227,7 +233,7 @@ class Multi_field_operators { } }; -} //namespace persistence_matrix +} //namespace persistence_fields } //namespace Gudhi #endif // MATRIX_FIELD_MULTI_OPERATORS_H_ diff --git a/src/Persistence_matrix/include/gudhi/Fields/Multi_field_shared.h b/src/Persistence_matrix/include/gudhi/Fields/Multi_field_shared.h index 6d99634dc9..7071a419fd 100644 --- a/src/Persistence_matrix/include/gudhi/Fields/Multi_field_shared.h +++ b/src/Persistence_matrix/include/gudhi/Fields/Multi_field_shared.h @@ -17,8 +17,14 @@ #include namespace Gudhi { -namespace persistence_matrix { +namespace persistence_fields { +/** + * @ingroup persistence_fields + * + * @brief TODO: + * + */ class Shared_multi_field_element { public: using element_type = mpz_class; @@ -381,7 +387,7 @@ inline constexpr bool Shared_multi_field_element::_is_prime(const int p) return true; } -} //namespace persistence_matrix +} //namespace persistence_fields } //namespace Gudhi #endif // MATRIX_FIELD_MULTI_SHARED_H_ diff --git a/src/Persistence_matrix/include/gudhi/Fields/Multi_field_small.h b/src/Persistence_matrix/include/gudhi/Fields/Multi_field_small.h index 883eb7d5e8..1cfa3a0089 100644 --- a/src/Persistence_matrix/include/gudhi/Fields/Multi_field_small.h +++ b/src/Persistence_matrix/include/gudhi/Fields/Multi_field_small.h @@ -18,9 +18,15 @@ #include namespace Gudhi { -namespace persistence_matrix { +namespace persistence_fields { //productOfAllCharacteristics_ has to fit in an unsigned int, ie, productOfAllCharacteristics_ < 4294967295 +/** + * @ingroup persistence_fields + * + * @brief TODO: + * + */ template class Multi_field_element_with_small_characteristics { public: @@ -490,7 +496,7 @@ inline constexpr bool Multi_field_element_with_small_characteristics namespace Gudhi { -namespace persistence_matrix { +namespace persistence_fields { //productOfAllCharacteristics_ ^ 2 has to fit in an unsigned int +/** + * @ingroup persistence_fields + * + * @brief TODO: + * + */ class Multi_field_operators_with_small_characteristics { public: using element_type = unsigned int; @@ -281,7 +287,7 @@ inline constexpr bool Multi_field_operators_with_small_characteristics::_is_prim return true; } -} //namespace persistence_matrix +} //namespace persistence_fields } //namespace Gudhi #endif // MATRIX_FIELD_MULTI_SMALL_OPERATORS_H_ diff --git a/src/Persistence_matrix/include/gudhi/Fields/Multi_field_small_shared.h b/src/Persistence_matrix/include/gudhi/Fields/Multi_field_small_shared.h index 40d69bfb3e..4a8da63449 100644 --- a/src/Persistence_matrix/include/gudhi/Fields/Multi_field_small_shared.h +++ b/src/Persistence_matrix/include/gudhi/Fields/Multi_field_small_shared.h @@ -18,9 +18,15 @@ #include namespace Gudhi { -namespace persistence_matrix { +namespace persistence_fields { //productOfAllCharacteristics_ ^ 2 has to fit in an unsigned int +/** + * @ingroup persistence_fields + * + * @brief TODO: + * + */ class Shared_multi_field_element_with_small_characteristics { public: using element_type = unsigned int; @@ -448,7 +454,7 @@ inline constexpr bool Shared_multi_field_element_with_small_characteristics::_is return true; } -} //namespace persistence_matrix +} //namespace persistence_fields } //namespace Gudhi #endif // MATRIX_FIELD_MULTI_SMALL_SHARED_H_ diff --git a/src/Persistence_matrix/include/gudhi/Fields/Z2_field.h b/src/Persistence_matrix/include/gudhi/Fields/Z2_field.h index a4b6a1e89a..b65d7f0364 100644 --- a/src/Persistence_matrix/include/gudhi/Fields/Z2_field.h +++ b/src/Persistence_matrix/include/gudhi/Fields/Z2_field.h @@ -14,8 +14,14 @@ #include namespace Gudhi { -namespace persistence_matrix { +namespace persistence_fields { +/** + * @ingroup persistence_fields + * + * @brief TODO: + * + */ class Z2_field_element { public: using element_type = unsigned int; @@ -212,7 +218,7 @@ inline unsigned int Z2_field_element::get_value() const return element_; } -} //namespace persistence_matrix +} //namespace persistence_fields } //namespace Gudhi #endif // MATRIX_FIELD_Z2_H_ diff --git a/src/Persistence_matrix/include/gudhi/Fields/Z2_field_operators.h b/src/Persistence_matrix/include/gudhi/Fields/Z2_field_operators.h index 2a829439d6..c47b86f6ad 100644 --- a/src/Persistence_matrix/include/gudhi/Fields/Z2_field_operators.h +++ b/src/Persistence_matrix/include/gudhi/Fields/Z2_field_operators.h @@ -14,8 +14,14 @@ #include namespace Gudhi { -namespace persistence_matrix { +namespace persistence_fields { +/** + * @ingroup persistence_fields + * + * @brief TODO: + * + */ class Z2_field_operators { public: using element_type = bool; @@ -121,7 +127,7 @@ class Z2_field_operators { } }; -} //namespace persistence_matrix +} //namespace persistence_fields } //namespace Gudhi #endif // MATRIX_FIELD_Z2_OPERATORS_H_ diff --git a/src/Persistence_matrix/include/gudhi/Fields/Zp_field.h b/src/Persistence_matrix/include/gudhi/Fields/Zp_field.h index bef956615f..1fa6385b01 100644 --- a/src/Persistence_matrix/include/gudhi/Fields/Zp_field.h +++ b/src/Persistence_matrix/include/gudhi/Fields/Zp_field.h @@ -16,8 +16,14 @@ #include namespace Gudhi { -namespace persistence_matrix { +namespace persistence_fields { +/** + * @ingroup persistence_fields + * + * @brief TODO: + * + */ template class Zp_field_element { public: @@ -372,7 +378,7 @@ inline constexpr bool Zp_field_element::_is_prime() return true; } -} //namespace persistence_matrix +} //namespace persistence_fields } //namespace Gudhi #endif // MATRIX_FIELD_ZP_H_ diff --git a/src/Persistence_matrix/include/gudhi/Fields/Zp_field_operators.h b/src/Persistence_matrix/include/gudhi/Fields/Zp_field_operators.h index c4db0a8c7e..ed92da0631 100644 --- a/src/Persistence_matrix/include/gudhi/Fields/Zp_field_operators.h +++ b/src/Persistence_matrix/include/gudhi/Fields/Zp_field_operators.h @@ -17,8 +17,14 @@ #include namespace Gudhi { -namespace persistence_matrix { +namespace persistence_fields { +/** + * @ingroup persistence_fields + * + * @brief TODO: + * + */ template > > class Zp_field_operators { public: @@ -176,7 +182,7 @@ class Zp_field_operators { } }; -} //namespace persistence_matrix +} //namespace persistence_fields } //namespace Gudhi #endif // MATRIX_FIELD_ZP_OPERATOR_H_ diff --git a/src/Persistence_matrix/include/gudhi/Fields/Zp_field_shared.h b/src/Persistence_matrix/include/gudhi/Fields/Zp_field_shared.h index 36d05c01ab..63d8ad9d9e 100644 --- a/src/Persistence_matrix/include/gudhi/Fields/Zp_field_shared.h +++ b/src/Persistence_matrix/include/gudhi/Fields/Zp_field_shared.h @@ -17,8 +17,14 @@ #include namespace Gudhi { -namespace persistence_matrix { +namespace persistence_fields { +/** + * @ingroup persistence_fields + * + * @brief TODO: + * + */ class Shared_Zp_field_element { public: using element_type = unsigned int; @@ -329,7 +335,7 @@ inline unsigned int Shared_Zp_field_element::_multiply(unsigned int element, uns return element; } -} //namespace persistence_matrix +} //namespace persistence_fields } //namespace Gudhi #endif // MATRIX_FIELD_ZP_VAR_H_ diff --git a/src/Persistence_matrix/include/gudhi/Persistence_matrix/base_matrix.h b/src/Persistence_matrix/include/gudhi/Persistence_matrix/base_matrix.h index fb4915b257..9039f38301 100644 --- a/src/Persistence_matrix/include/gudhi/Persistence_matrix/base_matrix.h +++ b/src/Persistence_matrix/include/gudhi/Persistence_matrix/base_matrix.h @@ -25,7 +25,10 @@ namespace Gudhi { namespace persistence_matrix { /** - * @brief A basic matrix structure allowing to easily manipulate and access entire columns and rows, + * @class Base_matrix base_matrix.h gudhi/Persistence_matrix/base_matrix.h + * @ingroup persistence_matrix + * + * @brief A @ref basematrix "basic matrix" structure allowing to easily manipulate and access entire columns and rows, * but not individual cells. * * @tparam Master_matrix An instanciation of @ref Matrix from which all types and options are deduced. @@ -116,7 +119,7 @@ class Base_matrix : public Master_matrix::template Base_swap_option void insert_column(const Container_type& column, index columnIndex); @@ -131,14 +134,14 @@ class Base_matrix : public Master_matrix::template Base_swap_option void insert_boundary(const Boundary_type& boundary, dimension_type dim = -1); /** - * @brief Returns the column at the given MatIdx index. + * @brief Returns the column at the given @ref MatIdx index. * The type of the column depends on the choosen options, see @ref PersistenceMatrixOptions::column_type. * * Note that before returning the column, all column cells can eventually be reordered, if lazy swaps occurred. * It is therefore recommended to avoid calling `get_column` between column or row swaps, otherwise the benefits * of the the lazyness is lost. * - * @param columnIndex MatIdx index of the column to return. + * @param columnIndex @ref MatIdx index of the column to return. * @return Reference to the column. */ Column_type& get_column(index columnIndex); @@ -165,7 +168,7 @@ class Base_matrix : public Master_matrix::template Base_swap_option void add_to(const Cell_range_or_column_index& sourceColumn, index targetColumnIndex); @@ -219,9 +222,9 @@ class Base_matrix : public Master_matrix::template Base_swap_option void multiply_target_and_add_to(const Cell_range_or_column_index& sourceColumn, @@ -237,8 +240,8 @@ class Base_matrix : public Master_matrix::template Base_swap_option void multiply_source_and_add_to(const Field_element_type& coefficient, @@ -248,20 +251,20 @@ class Base_matrix : public Master_matrix::template Base_swap_option - // Column_type(const Container_type& nonZeroRowIndices, Field_operators* operators, - // Cell_constructor* cellConstructor) - // : Base(nonZeroRowIndices, operators, cellConstructor) {} - // template - // Column_type(index columnIndex, const Container_type& nonZeroRowIndices, Row_container_type& rowContainer, - // Field_operators* operators, Cell_constructor* cellConstructor) - // : Base(columnIndex, nonZeroRowIndices, rowContainer, operators, cellConstructor) {} - // template - // Column_type(const Container_type& nonZeroRowIndices, dimension_type dimension, Field_operators* operators, - // Cell_constructor* cellConstructor) - // : Base(nonZeroRowIndices, dimension, operators, cellConstructor) {} - // template - // Column_type(index columnIndex, const Container_type& nonZeroRowIndices, dimension_type dimension, - // Row_container_type& rowContainer, Field_operators* operators, Cell_constructor* cellConstructor) - // : Base(columnIndex, nonZeroRowIndices, dimension, rowContainer, operators, cellConstructor) {} - // Column_type(const Column_type& column, Field_operators* operators = nullptr, - // Cell_constructor* cellConstructor = nullptr) - // : Base(static_cast(column), operators, cellConstructor) {} - // template - // Column_type(const Column_type& column, index columnIndex, Row_container_type& rowContainer, - // Field_operators* operators = nullptr, Cell_constructor* cellConstructor = nullptr) - // : Base(static_cast(column), columnIndex, rowContainer, operators, cellConstructor) {} - // Column_type(Column_type&& column) noexcept : Base(std::move(static_cast(column))) {} - - template - Column_type(U&&... u) : Base(std::forward(u)...) {} + Column_type(Field_operators* operators = nullptr, Cell_constructor* cellConstructor = nullptr) + : Base(operators, cellConstructor) {} + template + Column_type(const Container_type& nonZeroRowIndices, Field_operators* operators, + Cell_constructor* cellConstructor) + : Base(nonZeroRowIndices, operators, cellConstructor) {} + template + Column_type(index columnIndex, const Container_type& nonZeroRowIndices, Row_container_type& rowContainer, + Field_operators* operators, Cell_constructor* cellConstructor) + : Base(columnIndex, nonZeroRowIndices, rowContainer, operators, cellConstructor) {} + template + Column_type(const Container_type& nonZeroRowIndices, dimension_type dimension, Field_operators* operators, + Cell_constructor* cellConstructor) + : Base(nonZeroRowIndices, dimension, operators, cellConstructor) {} + template + Column_type(index columnIndex, const Container_type& nonZeroRowIndices, dimension_type dimension, + Row_container_type& rowContainer, Field_operators* operators, Cell_constructor* cellConstructor) + : Base(columnIndex, nonZeroRowIndices, dimension, rowContainer, operators, cellConstructor) {} + Column_type(const Column_type& column, Field_operators* operators = nullptr, + Cell_constructor* cellConstructor = nullptr) + : Base(static_cast(column), operators, cellConstructor) {} + template + Column_type(const Column_type& column, index columnIndex, Row_container_type& rowContainer, + Field_operators* operators = nullptr, Cell_constructor* cellConstructor = nullptr) + : Base(static_cast(column), columnIndex, rowContainer, operators, cellConstructor) {} + Column_type(Column_type&& column) noexcept : Base(std::move(static_cast(column))) {} + + // template + // Column_type(U&&... u) : Base(std::forward(u)...) {} index get_rep() const { return rep_; } void set_rep(const index& rep) { rep_ = rep; } @@ -182,13 +185,13 @@ class Base_matrix_with_column_compression : protected Master_matrix::Matrix_row_ template void insert_boundary(const Boundary_type& boundary, dimension_type dim = -1); /** - * @brief Returns the column at the given MatIdx index. + * @brief Returns the column at the given @ref MatIdx index. * The type of the column depends on the choosen options, see @ref PersistenceMatrixOptions::column_type. * * Remark: the method it-self is not const, because of the path compression optimization of the union-find structure, * when a column is looked up. * - * @param columnIndex MatIdx index of the column to return. + * @param columnIndex @ref MatIdx index of the column to return. * @return Const reference to the column. */ const Column_type& get_column(index columnIndex); @@ -198,7 +201,7 @@ class Base_matrix_with_column_compression : protected Master_matrix::Matrix_row_ * The type of the row depends on the choosen options, see @ref PersistenceMatrixOptions::has_intrusive_rows. * Note that the row will be from the compressed matrix, that is, the one with only unique columns. * - * @param rowIndex IDIdx row index of the row to return, see [TODO: description]. + * @param rowIndex @ref IDIdx row index of the row to return, see [TODO: description]. * @return Const reference to the row. */ const Row_type& get_row(index rowIndex) const; @@ -212,7 +215,7 @@ class Base_matrix_with_column_compression : protected Master_matrix::Matrix_row_ * `erase_row` method just as a way to specify that a row is empty and can therefore be removed from dictionnaries. * This allows to avoid testing the emptiness of a row at each column cell removal, what can be quite frequent. * - * @param rowIndex IDIdx row index of the empty row, see [TODO: description]. + * @param rowIndex @ref IDIdx row index of the empty row, see [TODO: description]. */ void erase_row(index rowIndex); @@ -231,8 +234,8 @@ class Base_matrix_with_column_compression : protected Master_matrix::Matrix_row_ * * @tparam Cell_range_or_column_index Either a range of @ref Cell with a begin() and end() method, * or any integer type. - * @param sourceColumn Either a cell range or the MatIdx index of the column to add. - * @param targetColumnIndex MatIdx index of the target column. + * @param sourceColumn Either a cell range or the @ref MatIdx index of the column to add. + * @param targetColumnIndex @ref MatIdx index of the target column. */ template void add_to(const Cell_range_or_column_index& sourceColumn, index targetColumnIndex); @@ -245,9 +248,9 @@ class Base_matrix_with_column_compression : protected Master_matrix::Matrix_row_ * * @tparam Cell_range_or_column_index Either a range of @ref Cell with a begin() and end() method, * or any integer type. - * @param sourceColumn Either a cell range or the MatIdx index of the column to add. + * @param sourceColumn Either a cell range or the @ref MatIdx index of the column to add. * @param coefficient Value to multiply. - * @param targetColumnIndex MatIdx index of the target column. + * @param targetColumnIndex @ref MatIdx index of the target column. */ template void multiply_target_and_add_to(const Cell_range_or_column_index& sourceColumn, @@ -263,8 +266,8 @@ class Base_matrix_with_column_compression : protected Master_matrix::Matrix_row_ * @tparam Cell_range_or_column_index Either a range of @ref Cell with a begin() and end() method, * or any integer type. * @param coefficient Value to multiply. - * @param sourceColumn Either a cell range or the MatIdx index of the column to add. - * @param targetColumnIndex MatIdx index of the target column. + * @param sourceColumn Either a cell range or the @ref MatIdx index of the column to add. + * @param targetColumnIndex @ref MatIdx index of the target column. */ template void multiply_source_and_add_to(const Field_element_type& coefficient, @@ -274,7 +277,7 @@ class Base_matrix_with_column_compression : protected Master_matrix::Matrix_row_ /** * @brief Indicates if the cell at given coordinates has value zero. * - * @param columnIndex MatIdx index of the column of the cell. + * @param columnIndex @ref MatIdx index of the column of the cell. * @param rowIndex Row index of the row of the cell. * @return true If the cell has value zero. * @return false Otherwise. @@ -283,7 +286,7 @@ class Base_matrix_with_column_compression : protected Master_matrix::Matrix_row_ /** * @brief Indicates if the column at given index has value zero. * - * @param columnIndex MatIdx index of the column. + * @param columnIndex @ref MatIdx index of the column. * @return true If the column has value zero. * @return false Otherwise. */ diff --git a/src/Persistence_matrix/include/gudhi/Persistence_matrix/base_pairing.h b/src/Persistence_matrix/include/gudhi/Persistence_matrix/base_pairing.h index 2293e78723..b83d7059f0 100644 --- a/src/Persistence_matrix/include/gudhi/Persistence_matrix/base_pairing.h +++ b/src/Persistence_matrix/include/gudhi/Persistence_matrix/base_pairing.h @@ -26,6 +26,8 @@ namespace Gudhi { namespace persistence_matrix { /** + * @ingroup persistence_matrix + * * @brief Empty structure. * Inheritated instead of @ref Base_pairing, when the computation of the barcode was not enabled or if the pairing * is already managed by the vine update classes. @@ -40,6 +42,9 @@ struct Dummy_base_pairing { }; /** + * @class Base_pairing base_pairing.h gudhi/Persistence_matrix/base_pairing.h + * @ingroup persistence_matrix + * * @brief Class managing the barcode for @ref Boundary_matrix if the option was enabled. * * @tparam Master_matrix An instanciation of @ref Matrix from which all types and options are deduced. diff --git a/src/Persistence_matrix/include/gudhi/Persistence_matrix/base_swap.h b/src/Persistence_matrix/include/gudhi/Persistence_matrix/base_swap.h index 13a7d1742f..4984ea5989 100644 --- a/src/Persistence_matrix/include/gudhi/Persistence_matrix/base_swap.h +++ b/src/Persistence_matrix/include/gudhi/Persistence_matrix/base_swap.h @@ -24,6 +24,8 @@ namespace Gudhi { namespace persistence_matrix { /** + * @ingroup persistence_matrix + * * @brief Empty structure. * Inheritated instead of @ref Base_swap, when the column and row swaps are not enabled. */ @@ -38,6 +40,9 @@ struct Dummy_base_swap { }; /** + * @class Base_swap base_swap.h gudhi/Persistence_matrix/base_swap.h + * @ingroup persistence_matrix + * * @brief Class managing the column and row swaps in @ref Base_matrix and @ref Boundary_matrix. * * @tparam Master_matrix An instanciation of @ref Matrix from which all types and options are deduced. @@ -48,7 +53,7 @@ class Base_swap { public: using matrix_type = typename Master_matrix::column_container_type; /**< Column container type. */ using index = typename Master_matrix::index; /**< Container index type. */ - using id_index = typename Master_matrix::id_index; /**< IDIdx index type. */ + using id_index = typename Master_matrix::id_index; /**< @ref IDIdx index type. */ /** * @brief Default constructor. @@ -77,8 +82,8 @@ class Base_swap { * @brief Swaps the two columns at given indices in the column container. Does not updates the column index value, * potentially stored in the cells. This will be done when calling `_orderRows()`. * - * @param columnIndex1 First MatIdx column index. - * @param columnIndex2 Second MatIdx column index. + * @param columnIndex1 First @ref MatIdx column index. + * @param columnIndex2 Second @ref MatIdx column index. */ void swap_columns(index columnIndex1, index columnIndex2); /** diff --git a/src/Persistence_matrix/include/gudhi/Persistence_matrix/boundary_matrix.h b/src/Persistence_matrix/include/gudhi/Persistence_matrix/boundary_matrix.h index 8f141a568b..02a20062aa 100644 --- a/src/Persistence_matrix/include/gudhi/Persistence_matrix/boundary_matrix.h +++ b/src/Persistence_matrix/include/gudhi/Persistence_matrix/boundary_matrix.h @@ -25,9 +25,12 @@ namespace Gudhi { namespace persistence_matrix { -// TODO: factorize/inheritate/compose with base matrix? +// TODO: factorize/inheritate/compose with @ref basematrix "base matrix"? /** - * @brief Matrix structure to store the ordered boundary matrix \f$ R \f$ of a filtered complex in order to compute its + * @class Boundary_matrix boundary_matrix.h gudhi/Persistence_matrix/boundary_matrix.h + * @ingroup persistence_matrix + * + * @brief Matrix structure to store the ordered @ref boundarymatrix "boundary matrix" \f$ R \f$ of a filtered complex in order to compute its * persistent homology. Provides an access to its columns and rows as well as the possibility to remove the last * faces of the filtration while maintaining a valid barcode. * @@ -41,7 +44,7 @@ class Boundary_matrix : public Master_matrix::Matrix_dimension_option, { public: using index = typename Master_matrix::index; /**< Container index type. */ - using id_index = typename Master_matrix::id_index; /**< IDIdx index type. */ + using id_index = typename Master_matrix::id_index; /**< @ref IDIdx index type. */ using dimension_type = typename Master_matrix::dimension_type; /**< Dimension value type. */ /** * @brief Field operators class. Necessary only if @ref PersistenceMatrixOptions::is_z2 is false. @@ -68,7 +71,7 @@ class Boundary_matrix : public Master_matrix::Matrix_dimension_option, * * @tparam Boundary_type Range type for @ref Matrix::cell_rep_type ranges. * Assumed to have a begin(), end() and size() method. - * @param orderedBoundaries Range of boundaries: @p orderedBoundaries is interpreted as a boundary matrix of a + * @param orderedBoundaries Range of boundaries: @p orderedBoundaries is interpreted as a @ref boundarymatrix "boundary matrix" of a * filtered **simplicial** complex, whose boundaries are ordered by filtration order. * Therefore, `orderedBoundaries[i]` should store the boundary of the \f$ i^th \f$ simplex in the filtration, * as an ordered list of indices of its facets (again those indices correspond to their respective position @@ -130,7 +133,7 @@ class Boundary_matrix : public Master_matrix::Matrix_dimension_option, * @param boundary Boundary generating the new column. The content should be ordered by ID. * @param dim Dimension of the face whose boundary is given. If the complex is simplicial, * this parameter can be omitted as it can be deduced from the size of the boundary. - * @return The MatIdx index of the inserted boundary. + * @return The @ref MatIdx index of the inserted boundary. */ template index insert_boundary(const Boundary_type& boundary, dimension_type dim = -1); @@ -143,25 +146,25 @@ class Boundary_matrix : public Master_matrix::Matrix_dimension_option, * the faces are inserted by order of filtration), it is sufficient to indicate the ID of the face being inserted. * * @tparam Boundary_type Range of @ref Matrix::cell_rep_type. Assumed to have a begin(), end() and size() method. - * @param faceIndex IDIdx index to use to indentify the new face. + * @param faceIndex @ref IDIdx index to use to indentify the new face. * @param boundary Boundary generating the new column. The indices of the boundary have to correspond to the * @p faceIndex values of precedent calls of the method for the corresponding faces and should be ordered in * increasing order. * @param dim Dimension of the face whose boundary is given. If the complex is simplicial, * this parameter can be omitted as it can be deduced from the size of the boundary. - * @return The MatIdx index of the inserted boundary. + * @return The @ref MatIdx index of the inserted boundary. */ template index insert_boundary(id_index faceIndex, const Boundary_type& boundary, dimension_type dim = -1); /** - * @brief Returns the column at the given MatIdx index. + * @brief Returns the column at the given @ref MatIdx index. * The type of the column depends on the choosen options, see @ref PersistenceMatrixOptions::column_type. * * Note that before returning the column, all column cells can eventually be reordered, if lazy swaps occurred. * It is therefore recommended to avoid calling `get_column` between column or row swaps, otherwise the benefits * of the the lazyness is lost. * - * @param columnIndex MatIdx index of the column to return. + * @param columnIndex @ref MatIdx index of the column to return. * @return Reference to the column. */ Column_type& get_column(index columnIndex); @@ -211,7 +214,7 @@ class Boundary_matrix : public Master_matrix::Matrix_dimension_option, /** * @brief Returns the dimension of the given column. * - * @param columnIndex MatIdx index of the column representing the face. + * @param columnIndex @ref MatIdx index of the column representing the face. * @return Dimension of the face. */ dimension_type get_column_dimension(index columnIndex) const; @@ -220,11 +223,11 @@ class Boundary_matrix : public Master_matrix::Matrix_dimension_option, * @brief Adds column at @p sourceColumnIndex onto the column at @p targetColumnIndex in the matrix. * * @warning They will be no verification to ensure that the addition makes sense for the validity of a - * boundary matrix of a filtered complex. For example, a right-to-left addition could corrupt the computation + * @ref boundarymatrix "boundary matrix" of a filtered complex. For example, a right-to-left addition could corrupt the computation * of the barcode if done blindly. So should be used with care. * - * @param sourceColumnIndex MatIdx index of the source column. - * @param targetColumnIndex MatIdx index of the target column. + * @param sourceColumnIndex @ref MatIdx index of the source column. + * @param targetColumnIndex @ref MatIdx index of the target column. */ void add_to(index sourceColumnIndex, index targetColumnIndex); /** @@ -232,12 +235,12 @@ class Boundary_matrix : public Master_matrix::Matrix_dimension_option, * That is: targetColumn = (targetColumn * coefficient) + sourceColumn. * * @warning They will be no verification to ensure that the addition makes sense for the validity of a - * boundary matrix of a filtered complex. For example, a right-to-left addition could corrupt the computation + * @ref boundarymatrix "boundary matrix" of a filtered complex. For example, a right-to-left addition could corrupt the computation * of the barcode if done blindly. So should be used with care. * - * @param sourceColumnIndex MatIdx index of the source column. + * @param sourceColumnIndex @ref MatIdx index of the source column. * @param coefficient Value to multiply. - * @param targetColumnIndex MatIdx index of the target column. + * @param targetColumnIndex @ref MatIdx index of the target column. */ void multiply_target_and_add_to(index sourceColumnIndex, const Field_element_type& coefficient, @@ -247,12 +250,12 @@ class Boundary_matrix : public Master_matrix::Matrix_dimension_option, * That is: targetColumn += (coefficient * sourceColumn). The source column will **not** be modified. * * @warning They will be no verification to ensure that the addition makes sense for the validity of a - * boundary matrix of a filtered complex. For example, a right-to-left addition could corrupt the computation + * @ref boundarymatrix "boundary matrix" of a filtered complex. For example, a right-to-left addition could corrupt the computation * of the barcode if done blindly. So should be used with care. * * @param coefficient Value to multiply. - * @param sourceColumnIndex MatIdx index of the source column. - * @param targetColumnIndex MatIdx index of the target column. + * @param sourceColumnIndex @ref MatIdx index of the source column. + * @param targetColumnIndex @ref MatIdx index of the target column. */ void multiply_source_and_add_to(const Field_element_type& coefficient, index sourceColumnIndex, @@ -262,9 +265,9 @@ class Boundary_matrix : public Master_matrix::Matrix_dimension_option, * @brief Zeroes the cell at the given coordinates. * * @warning They will be no verification to ensure that the zeroing makes sense for the validity of a - * boundary matrix of a filtered complex. So should be used while knowing what one is doing. + * @ref boundarymatrix "boundary matrix" of a filtered complex. So should be used while knowing what one is doing. * - * @param columnIndex MatIdx index of the column of the cell. + * @param columnIndex @ref MatIdx index of the column of the cell. * @param rowIndex Row index of the row of the cell, see [TODO: description]. */ void zero_cell(index columnIndex, index rowIndex); @@ -272,15 +275,15 @@ class Boundary_matrix : public Master_matrix::Matrix_dimension_option, * @brief Zeroes the column at the given index. * * @warning They will be no verification to ensure that the zeroing makes sense for the validity of a - * boundary matrix of a filtered complex. So should be used while knowing what one is doing. + * @ref boundarymatrix "boundary matrix" of a filtered complex. So should be used while knowing what one is doing. * - * @param columnIndex MatIdx index of the column to zero. + * @param columnIndex @ref MatIdx index of the column to zero. */ void zero_column(index columnIndex); /** * @brief Indicates if the cell at given coordinates has value zero. * - * @param columnIndex MatIdx index of the column of the cell. + * @param columnIndex @ref MatIdx index of the column of the cell. * @param rowIndex Row index of the row of the cell, see [TODO: description]. * @return true If the cell has value zero. * @return false Otherwise. @@ -289,7 +292,7 @@ class Boundary_matrix : public Master_matrix::Matrix_dimension_option, /** * @brief Indicates if the column at given index has value zero. * - * @param columnIndex MatIdx index of the column. + * @param columnIndex @ref MatIdx index of the column. * @return true If the column has value zero. * @return false Otherwise. */ @@ -298,7 +301,7 @@ class Boundary_matrix : public Master_matrix::Matrix_dimension_option, /** * @brief Returns the pivot of the given column. * - * @param columnIndex MatIdx index of the column. + * @param columnIndex @ref MatIdx index of the column. * @return Pivot of the coluimn at @p columnIndex. */ index get_pivot(index columnIndex); diff --git a/src/Persistence_matrix/include/gudhi/Persistence_matrix/chain_matrix.h b/src/Persistence_matrix/include/gudhi/Persistence_matrix/chain_matrix.h index f5f69372ef..7cf3b62070 100644 --- a/src/Persistence_matrix/include/gudhi/Persistence_matrix/chain_matrix.h +++ b/src/Persistence_matrix/include/gudhi/Persistence_matrix/chain_matrix.h @@ -29,6 +29,9 @@ namespace Gudhi { namespace persistence_matrix { /** + * @class Chain_matrix chain_matrix.h gudhi/Persistence_matrix/chain_matrix.h + * @ingroup persistence_matrix + * * @brief Matrix structure storing a compatible base of a filtered chain complex. See [TODO: cite zigzag paper]. * The base is constructed from the boundaries of the faces in the complex. Allows the persistent homology to be * computed, as well as representative cycles. Supports vineyards (see [TODO: cite vineyard paper]) and the removal @@ -56,9 +59,9 @@ class Chain_matrix : public Master_matrix::Matrix_dimension_option, using Cell_constructor = typename Master_matrix::Cell_constructor; /**< Factory of @ref Cell classes. */ using boundary_type = typename Master_matrix::boundary_type; /**< Type of an input column. */ using cell_rep_type = typename Master_matrix::cell_rep_type; /**< Cell content representative. */ - using index = typename Master_matrix::index; /**< MatIdx index type. */ - using id_index = typename Master_matrix::id_index; /**< IDIdx index type. */ - using pos_index = typename Master_matrix::pos_index; /**< PosIdx index type. */ + using index = typename Master_matrix::index; /**< @ref MatIdx index type. */ + using id_index = typename Master_matrix::id_index; /**< @ref IDIdx index type. */ + using pos_index = typename Master_matrix::pos_index; /**< @ref PosIdx index type. */ using dimension_type = typename Master_matrix::dimension_type; /**< Dimension value type. */ /** @@ -80,7 +83,7 @@ class Chain_matrix : public Master_matrix::Matrix_dimension_option, * * @tparam Boundary_type Range type for @ref Matrix::cell_rep_type ranges. * Assumed to have a begin(), end() and size() method. - * @param orderedBoundaries Range of boundaries: @p orderedBoundaries is interpreted as a boundary matrix of a + * @param orderedBoundaries Range of boundaries: @p orderedBoundaries is interpreted as a @ref boundarymatrix "boundary matrix" of a * filtered **simplicial** complex, whose boundaries are ordered by filtration order. * Therefore, `orderedBoundaries[i]` should store the boundary of the \f$ i^th \f$ simplex in the filtration, * as an ordered list of indices of its facets (again those indices correspond to their respective position @@ -117,11 +120,11 @@ class Chain_matrix : public Master_matrix::Matrix_dimension_option, * @tparam EventComparatorFunction Method of the form: ( @ref pos_index, @ref pos_index ) -> bool. * @param operators Pointer to the field operators. * @param cellConstructor Pointer to the cell factory. - * @param birthComparator Method taking two PosIdx indices as input and returning true if and only if + * @param birthComparator Method taking two @ref PosIdx indices as input and returning true if and only if * the birth associated to the first position is strictly less than birth associated to * the second one with respect to some self defined order. It is used while swapping two unpaired or * two negative columns. - * @param deathComparator Method taking two PosIdx indices as input and returning true if and only if + * @param deathComparator Method taking two @ref PosIdx indices as input and returning true if and only if * the death associated to the first position is strictly less than death associated to * the second one with respect to some self defined order. It is used while swapping two positive but paired * columns. @@ -144,7 +147,7 @@ class Chain_matrix : public Master_matrix::Matrix_dimension_option, * @tparam EventComparatorFunction Method of the form: ( @ref pos_index, @ref pos_index ) -> bool. * @tparam Boundary_type Range type for @ref Matrix::cell_rep_type ranges. * Assumed to have a begin(), end() and size() method. - * @param orderedBoundaries Range of boundaries: @p orderedBoundaries is interpreted as a boundary matrix of a + * @param orderedBoundaries Range of boundaries: @p orderedBoundaries is interpreted as a @ref boundarymatrix "boundary matrix" of a * filtered **simplicial** complex, whose boundaries are ordered by filtration order. * Therefore, `orderedBoundaries[i]` should store the boundary of the \f$ i^th \f$ simplex in the filtration, * as an ordered list of indices of its facets (again those indices correspond to their respective position @@ -155,11 +158,11 @@ class Chain_matrix : public Master_matrix::Matrix_dimension_option, * the matrix with the `Matrix(int numberOfColumns)` constructor preferably). * @param operators Pointer to the field operators. * @param cellConstructor Pointer to the cell factory. - * @param birthComparator Method taking two PosIdx indices as input and returning true if and only if + * @param birthComparator Method taking two @ref PosIdx indices as input and returning true if and only if * the birth associated to the first position is strictly less than birth associated to * the second one with respect to some self defined order. It is used while swapping two unpaired or * two negative columns. - * @param deathComparator Method taking two PosIdx indices as input and returning true if and only if + * @param deathComparator Method taking two @ref PosIdx indices as input and returning true if and only if * the death associated to the first position is strictly less than death associated to * the second one with respect to some self defined order. It is used while swapping two positive but paired * columns. @@ -182,11 +185,11 @@ class Chain_matrix : public Master_matrix::Matrix_dimension_option, * @param numberOfColumns Number of columns to reserve space for. * @param operators Pointer to the field operators. * @param cellConstructor Pointer to the cell factory. - * @param birthComparator Method taking two PosIdx indices as input and returning true if and only if + * @param birthComparator Method taking two @ref PosIdx indices as input and returning true if and only if * the birth associated to the first position is strictly less than birth associated to * the second one with respect to some self defined order. It is used while swapping two unpaired or * two negative columns. - * @param deathComparator Method taking two PosIdx indices as input and returning true if and only if + * @param deathComparator Method taking two @ref PosIdx indices as input and returning true if and only if * the death associated to the first position is strictly less than death associated to * the second one with respect to some self defined order. It is used while swapping two positive but paired * columns. @@ -228,13 +231,13 @@ class Chain_matrix : public Master_matrix::Matrix_dimension_option, * a more general cell complex. This includes cubical complexes or Morse complexes for example. * * When inserted, the given boundary is reduced and from the reduction process, the column is deduced in the form of: - * `IDIdx + linear combination of older column IDIdxs`. If the barcode is stored, it will be updated. + * `@ref IDIdx + linear combination of older column @ref IDIdxs`. If the barcode is stored, it will be updated. * * @tparam Boundary_type Range of @ref Matrix::cell_rep_type. Assumed to have a begin(), end() and size() method. * @param boundary Boundary generating the new column. The content should be ordered by ID. * @param dim Dimension of the face whose boundary is given. If the complex is simplicial, * this parameter can be omitted as it can be deduced from the size of the boundary. - * @return The MatIdx indices of the unpaired chains used to reduce the boundary. + * @return The @ref MatIdx indices of the unpaired chains used to reduce the boundary. */ template std::vector insert_boundary(const Boundary_type& boundary, dimension_type dim = -1); @@ -247,29 +250,29 @@ class Chain_matrix : public Master_matrix::Matrix_dimension_option, * the faces are inserted by order of filtration), it is sufficient to indicate the ID of the face being inserted. * * @tparam Boundary_type Range of @ref Matrix::cell_rep_type. Assumed to have a begin(), end() and size() method. - * @param faceID IDIdx index to use to indentify the new face. + * @param faceID @ref IDIdx index to use to indentify the new face. * @param boundary Boundary generating the new column. The indices of the boundary have to correspond to the * @p faceID values of precedent calls of the method for the corresponding faces and should be ordered in * increasing order. * @param dim Dimension of the face whose boundary is given. If the complex is simplicial, * this parameter can be omitted as it can be deduced from the size of the boundary. - * @return The MatIdx index of the inserted boundary. + * @return The @ref MatIdx index of the inserted boundary. */ template std::vector insert_boundary(id_index faceID, const Boundary_type& boundary, dimension_type dim = -1); /** - * @brief Returns the column at the given MatIdx index. + * @brief Returns the column at the given @ref MatIdx index. * The type of the column depends on the choosen options, see @ref PersistenceMatrixOptions::column_type. * - * @param columnIndex MatIdx index of the column to return. + * @param columnIndex @ref MatIdx index of the column to return. * @return Reference to the column. */ Column_type& get_column(index columnIndex); /** - * @brief Returns the column at the given MatIdx index. + * @brief Returns the column at the given @ref MatIdx index. * The type of the column depends on the choosen options, see @ref PersistenceMatrixOptions::column_type. * - * @param columnIndex MatIdx index of the column to return. + * @param columnIndex @ref MatIdx index of the column to return. * @return Const reference to the column. */ const Column_type& get_column(index columnIndex) const; @@ -287,7 +290,7 @@ class Chain_matrix : public Master_matrix::Matrix_dimension_option, * * See also @ref remove_last. * - * @param faceID IDIdx index of the face to remove + * @param faceID @ref IDIdx index of the face to remove */ void remove_maximal_face(id_index faceID); /** @@ -300,17 +303,17 @@ class Chain_matrix : public Master_matrix::Matrix_dimension_option, * Also updates the barcode if it is stored. * * To maintain the compatibility, vine swaps are done to move the face up to the end of the filtration. Once at - * the end, the removal is trivial. But for chain matrices, swaps do not actually swap the position of the column + * the end, the removal is trivial. But for @ref chainmatrix "chain matrices", swaps do not actually swap the position of the column * every time, so the faces appearing after @p faceID in the filtration have to be searched first within the matrix. - * If the user has an easy access to the IDIdx of the faces in the order of filtration, passing them by argument with + * If the user has an easy access to the @ref IDIdx of the faces in the order of filtration, passing them by argument with * @p columnsToSwap allows to skip a linear search process. Typically, if the user knows that the face he wants to * remove is already the last face of the filtration, calling `remove_maximal_face(faceIndex, {})` will be faster * than `remove_last()`. * * See also @ref remove_last. * - * @param faceID IDIdx index of the face to remove - * @param columnsToSwap Vector of IDIdx indices of the faces coming after @p faceID in the filtration. + * @param faceID @ref IDIdx index of the face to remove + * @param columnsToSwap Vector of @ref IDIdx indices of the faces coming after @p faceID in the filtration. */ void remove_maximal_face(id_index faceID, const std::vector& columnsToSwap); /** @@ -323,7 +326,7 @@ class Chain_matrix : public Master_matrix::Matrix_dimension_option, * * @warning If @ref PersistenceMatrixOptions::has_vine_update is true, the last face does not have to * be at the end of the matrix container and therefore has to be searched first. In this case, if the user - * already knows the IDIdx of the last face, calling `remove_maximal_face(faceID, {})` instead allows + * already knows the @ref IDIdx of the last face, calling `remove_maximal_face(faceID, {})` instead allows * to skip the search. */ void remove_last(); @@ -338,7 +341,7 @@ class Chain_matrix : public Master_matrix::Matrix_dimension_option, /** * @brief Returns the dimension of the given column. * - * @param columnIndex MatIdx index of the column representing the face. + * @param columnIndex @ref MatIdx index of the column representing the face. * @return Dimension of the face. */ dimension_type get_column_dimension(index columnIndex) const; @@ -347,11 +350,11 @@ class Chain_matrix : public Master_matrix::Matrix_dimension_option, * @brief Adds column at @p sourceColumnIndex onto the column at @p targetColumnIndex in the matrix. * * @warning They will be no verification to ensure that the addition makes sense for the validity of a - * chain matrix. For example, a right-to-left addition could corrupt the computation + * @ref chainmatrix "chain matrix". For example, a right-to-left addition could corrupt the computation * of the barcode if done blindly. So should be used with care. * - * @param sourceColumnIndex MatIdx index of the source column. - * @param targetColumnIndex MatIdx index of the target column. + * @param sourceColumnIndex @ref MatIdx index of the source column. + * @param targetColumnIndex @ref MatIdx index of the target column. */ void add_to(index sourceColumnIndex, index targetColumnIndex); /** @@ -359,12 +362,12 @@ class Chain_matrix : public Master_matrix::Matrix_dimension_option, * That is: targetColumn = (targetColumn * coefficient) + sourceColumn. * * @warning They will be no verification to ensure that the addition makes sense for the validity of a - * chain matrix. For example, a right-to-left addition could corrupt the computation + * @ref chainmatrix "chain matrix". For example, a right-to-left addition could corrupt the computation * of the barcode if done blindly. So should be used with care. * - * @param sourceColumnIndex MatIdx index of the source column. + * @param sourceColumnIndex @ref MatIdx index of the source column. * @param coefficient Value to multiply. - * @param targetColumnIndex MatIdx index of the target column. + * @param targetColumnIndex @ref MatIdx index of the target column. */ void multiply_target_and_add_to(index sourceColumnIndex, const Field_element_type& coefficient, @@ -374,12 +377,12 @@ class Chain_matrix : public Master_matrix::Matrix_dimension_option, * That is: targetColumn += (coefficient * sourceColumn). The source column will **not** be modified. * * @warning They will be no verification to ensure that the addition makes sense for the validity of a - * chain matrix. For example, a right-to-left addition could corrupt the computation + * @ref chainmatrix "chain matrix". For example, a right-to-left addition could corrupt the computation * of the barcode if done blindly. So should be used with care. * * @param coefficient Value to multiply. - * @param sourceColumnIndex MatIdx index of the source column. - * @param targetColumnIndex MatIdx index of the target column. + * @param sourceColumnIndex @ref MatIdx index of the source column. + * @param targetColumnIndex @ref MatIdx index of the target column. */ void multiply_source_and_add_to(const Field_element_type& coefficient, index sourceColumnIndex, @@ -388,8 +391,8 @@ class Chain_matrix : public Master_matrix::Matrix_dimension_option, /** * @brief Indicates if the cell at given coordinates has value zero. * - * @param columnIndex MatIdx index of the column of the cell. - * @param rowIndex IDIdx row index of the row of the cell. + * @param columnIndex @ref MatIdx index of the column of the cell. + * @param rowIndex @ref IDIdx row index of the row of the cell. * @return true If the cell has value zero. * @return false Otherwise. */ @@ -398,7 +401,7 @@ class Chain_matrix : public Master_matrix::Matrix_dimension_option, * @brief Indicates if the column at given index has value zero. Note that if the matrix is valid, this method * should always return false. * - * @param columnIndex MatIdx index of the column. + * @param columnIndex @ref MatIdx index of the column. * @return true If the column has value zero. * @return false Otherwise. */ @@ -407,15 +410,15 @@ class Chain_matrix : public Master_matrix::Matrix_dimension_option, /** * @brief Returns the column with given row index as pivot. Assumes that the pivot exists. * - * @param faceID IDIdx row index of the pivot. - * @return MatIdx index of the column with the given pivot. + * @param faceID @ref IDIdx row index of the pivot. + * @return @ref MatIdx index of the column with the given pivot. */ index get_column_with_pivot(id_index faceID) const; /** * @brief Returns the row index of the pivot of the given column. * - * @param columnIndex MatIdx index of the column - * @return The IDIdx row index of the pivot. + * @param columnIndex @ref MatIdx index of the column + * @return The @ref IDIdx row index of the pivot. */ id_index get_pivot(index columnIndex); @@ -510,7 +513,7 @@ class Chain_matrix : public Master_matrix::Matrix_dimension_option, >::type; matrix_type matrix_; /**< Column container. */ - dictionnary_type pivotToColumnIndex_; /**< Map from IDIdx to MatIdx index. */ + dictionnary_type pivotToColumnIndex_; /**< Map from @ref IDIdx to @ref MatIdx index. */ index nextIndex_; /**< Next unused column index. */ Field_operators* operators_; /**< Field operators, can be nullptr if @ref PersistenceMatrixOptions::is_z2 is true. */ @@ -856,8 +859,8 @@ inline void Chain_matrix::remove_last() if (nextIndex_ == 0 || matrix_.empty()) return; // empty matrix if constexpr (Master_matrix::Option_list::has_vine_update) { - // carefull: linear because of the search of the last index. It is better to keep track of the IDIdx index - // of the last column while performing swaps (or the MatIdx with the return values of `vine_swap` + get_pivot) + // carefull: linear because of the search of the last index. It is better to keep track of the @ref IDIdx index + // of the last column while performing swaps (or the @ref MatIdx with the return values of `vine_swap` + get_pivot) // and then call `remove_maximal_face` with it and an empty `columnsToSwap`. id_index pivot = 0; @@ -1244,7 +1247,7 @@ inline void Chain_matrix::_insert_chain(const tmp_column_type& co index pair) { // true when no vine updates and if nextIndex_ is updated in remove_last for special case of no vines - // because then PosIdx == MatIdx + // because then @ref PosIdx == @ref MatIdx pos_index pairPos = pair; id_index pivot; diff --git a/src/Persistence_matrix/include/gudhi/Persistence_matrix/chain_pairing.h b/src/Persistence_matrix/include/gudhi/Persistence_matrix/chain_pairing.h index b721471d66..057ed91b7c 100644 --- a/src/Persistence_matrix/include/gudhi/Persistence_matrix/chain_pairing.h +++ b/src/Persistence_matrix/include/gudhi/Persistence_matrix/chain_pairing.h @@ -23,6 +23,8 @@ namespace Gudhi { namespace persistence_matrix { /** + * @ingroup persistence_matrix + * * @brief Empty structure. * Inheritated instead of @ref Chain_pairing, when the computation of the barcode was not enabled or if the pairing * is already managed by the vine update classes. @@ -34,6 +36,9 @@ struct Dummy_chain_pairing { }; /** + * @class Chain_pairing chain_pairing.h gudhi/Persistence_matrix/chain_pairing.h + * @ingroup persistence_matrix + * * @brief Class managing the barcode for @ref Chain_matrix if the option was enabled. * * @tparam Master_matrix An instanciation of @ref Matrix from which all types and options are deduced. @@ -87,7 +92,7 @@ class Chain_pairing using pos_index = typename Master_matrix::pos_index; barcode_type barcode_; /**< Bar container. */ - dictionnary_type indexToBar_; /**< Map from MatIdx index to bar index. */ + dictionnary_type indexToBar_; /**< Map from @ref MatIdx index to bar index. */ pos_index nextPosition_; /**< Next relative position in the filtration. */ }; diff --git a/src/Persistence_matrix/include/gudhi/Persistence_matrix/chain_rep_cycles.h b/src/Persistence_matrix/include/gudhi/Persistence_matrix/chain_rep_cycles.h index 85a1e3b1b7..7a0d99d9fc 100644 --- a/src/Persistence_matrix/include/gudhi/Persistence_matrix/chain_rep_cycles.h +++ b/src/Persistence_matrix/include/gudhi/Persistence_matrix/chain_rep_cycles.h @@ -25,6 +25,8 @@ namespace Gudhi { namespace persistence_matrix { /** + * @ingroup persistence_matrix + * * @brief Empty structure. * Inheritated instead of @ref Chain_representative_cycles, when the computation of the representative cycles * were not enabled. @@ -40,6 +42,9 @@ struct Dummy_chain_representative_cycles { // TODO: add coefficients ? Only Z2 token into account for now. /** + * @class Chain_representative_cycles chain_rep_cycles.h gudhi/Persistence_matrix/chain_rep_cycles.h + * @ingroup persistence_matrix + * * @brief Class managing the representative cycles for @ref Chain_matrix if the option was enabled. * * @tparam Master_matrix An instanciation of @ref Matrix from which all types and options are deduced. @@ -137,8 +142,8 @@ inline void Chain_representative_cycles::update_representative_cy birthToCycle_.resize(_matrix()->get_number_of_columns(), -1); representativeCycles_.clear(); - // for birthToCycle_, assumes that PosIdx == IDIdx, ie pivot == birth index... which is not true with vineyards - // TODO: with vineyard, there is a IDIdx --> PosIdx map stored. somehow get access to it here + // for birthToCycle_, assumes that @ref PosIdx == @ref IDIdx, ie pivot == birth index... which is not true with vineyards + // TODO: with vineyard, there is a @ref IDIdx --> @ref PosIdx map stored. somehow get access to it here for (typename Master_matrix::id_index i = 0; i < _matrix()->get_number_of_columns(); i++) { auto& col = _matrix()->get_column(_matrix()->get_column_with_pivot(i)); if (!col.is_paired() || i < col.get_paired_chain_index()) { diff --git a/src/Persistence_matrix/include/gudhi/Persistence_matrix/chain_vine_swap.h b/src/Persistence_matrix/include/gudhi/Persistence_matrix/chain_vine_swap.h index e99697751e..a9ca2d75aa 100644 --- a/src/Persistence_matrix/include/gudhi/Persistence_matrix/chain_vine_swap.h +++ b/src/Persistence_matrix/include/gudhi/Persistence_matrix/chain_vine_swap.h @@ -27,6 +27,8 @@ namespace Gudhi { namespace persistence_matrix { /** + * @ingroup persistence_matrix + * * @brief Default death comparator. Simply assumes that two positive paired columns are never swapped. Which is true * for the use case in zigzag persistence for example. * @@ -34,13 +36,15 @@ namespace persistence_matrix { * @param columnIndex2 Second column index. * @return false */ -static constexpr bool _no_G_death_comparator([[maybe_unused]] unsigned int columnIndex1, - [[maybe_unused]] unsigned int columnIndex2) +constexpr bool _no_G_death_comparator([[maybe_unused]] unsigned int columnIndex1, + [[maybe_unused]] unsigned int columnIndex2) { return false; } /** + * @ingroup persistence_matrix + * * @brief Empty structure. * Inheritated instead of @ref Chain_vine_swap, when vine swappes are not enabled. */ @@ -56,6 +60,8 @@ struct Dummy_chain_vine_swap { }; /** + * @ingroup persistence_matrix + * * @brief Empty structure. * Inheritated instead of @ref Chain_barcode_swap, when the barcode is not stored. */ @@ -66,6 +72,8 @@ struct Dummy_chain_vine_pairing { }; /** + * @ingroup persistence_matrix + * * @brief Class managing the barcode for @ref Chain_vine_swap. * * @tparam Master_matrix An instanciation of @ref Matrix from which all types and options are deduced. @@ -74,8 +82,8 @@ template class Chain_barcode_swap : public Chain_pairing { public: - using id_index = typename Master_matrix::id_index; /**< IDIdx index type. */ - using pos_index = typename Master_matrix::pos_index; /**< PosIdx index type. */ + using id_index = typename Master_matrix::id_index; /**< @ref IDIdx index type. */ + using pos_index = typename Master_matrix::pos_index; /**< @ref PosIdx index type. */ using CP = Chain_pairing; /** @@ -214,6 +222,9 @@ class Chain_barcode_swap : public Chain_pairing }; /** + * @class Chain_vine_swap chain_vine_swap.h gudhi/Persistence_matrix/chain_vine_swap.h + * @ingroup persistence_matrix + * * @brief Class managing the vine swaps for @ref Chain_matrix. * * @tparam Master_matrix An instanciation of @ref Matrix from which all types and options are deduced. @@ -225,9 +236,9 @@ class Chain_vine_swap : public std::conditional::type { public: - using index = typename Master_matrix::index; /**< MatIdx index type. */ - using id_index = typename Master_matrix::id_index; /**< IDIdx index type. */ - using pos_index = typename Master_matrix::pos_index; /**< PosIdx index type. */ + using index = typename Master_matrix::index; /**< @ref MatIdx index type. */ + using id_index = typename Master_matrix::id_index; /**< @ref IDIdx index type. */ + using pos_index = typename Master_matrix::pos_index; /**< @ref PosIdx index type. */ using matrix_type = typename Master_matrix::column_container_type; /**< Column container type. */ using Column_type = typename Master_matrix::Column_type; /**< Column type. */ typedef bool (*EventCompFuncPointer)(pos_index, pos_index); /**< Pointer type for birth/death comparators. */ @@ -240,11 +251,11 @@ class Chain_vine_swap : public std::conditional bool. - * @param birthComparator Method taking two PosIdx indices as input and returning true if and only if + * @param birthComparator Method taking two @ref PosIdx indices as input and returning true if and only if * the birth associated to the first position is strictly less than birth associated to * the second one with respect to some self defined order. It is used while swapping two unpaired or * two negative columns. - * @param deathComparator Method taking two PosIdx indices as input and returning true if and only if + * @param deathComparator Method taking two @ref PosIdx indices as input and returning true if and only if * the death associated to the first position is strictly less than death associated to * the second one with respect to some self defined order. It is used while swapping two positive but paired * columns. Default value: @ref _no_G_death_comparator. @@ -269,10 +280,10 @@ class Chain_vine_swap : public std::conditional class Cell_column_index @@ -92,7 +98,7 @@ class Cell_column_index Cell_column_index(Cell_column_index&& cell) noexcept : columnIndex_(std::exchange(cell.columnIndex_, 0)){}; /** - * @brief Returns the MatIdx column index stored in the cell. + * @brief Returns the @ref MatIdx column index stored in the cell. * * @return Column index of the cell. */ @@ -117,6 +123,8 @@ class Cell_column_index }; /** + * @ingroup persistence_matrix + * * @brief Class managing the value access of a cell. * * @tparam Field_element_type Type of a cell value. @@ -180,6 +188,9 @@ class Cell_field_element }; /** + * @class Cell cell_types.h gudhi/Persistence_matrix/columns/cell_types.h + * @ingroup persistence_matrix + * * @brief Matrix cell class. Stores by default only the row index it belongs to, but can also store its * column index when the row access is enabled, as well as its value when they are different from only 0 and 1. * Zero-valued cells are never explicited in the matrix. @@ -306,6 +317,8 @@ class Cell : public Master_matrix::Cell_column_index_option, } // namespace Gudhi /** + * @ingroup persistence_matrix + * * @brief Hash method for @ref Gudhi::persistence_matrix::Cell. * * The cells are differentiated by their row indices only. For exemple, two cells with the same row index diff --git a/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/chain_column_extra_properties.h b/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/chain_column_extra_properties.h index f0901dfc67..ea7e55d5ee 100644 --- a/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/chain_column_extra_properties.h +++ b/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/chain_column_extra_properties.h @@ -23,8 +23,10 @@ namespace Gudhi { namespace persistence_matrix { /** + * @ingroup persistence_matrix + * * @brief Empty structure. - * Inheritated instead of @ref Chain_column_extra_properties, when the columns are not meant for chain matrices. + * Inheritated instead of @ref Chain_column_extra_properties, when the columns are not meant for @ref chainmatrix "chain matrices". */ struct Dummy_chain_properties { @@ -40,11 +42,14 @@ struct Dummy_chain_properties }; /** + * @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 chain matrix are partitioned in three sets: \f$ F \f$, \f$ G \f$ and \f$ H \f$ with a + * 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 - * @ref Chain_column_extra_properties::pairedColumn_ is -1, while the value corresponds to the MatIdx index of + * @ref 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 [TODO: zigzag paper] for * more details. * @@ -54,8 +59,8 @@ template class Chain_column_extra_properties { public: - using index = typename Master_matrix::index; /**< MatIdx index type. */ - using id_index = typename Master_matrix::id_index; /**< IDIdx index type. */ + 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". @@ -64,14 +69,14 @@ class Chain_column_extra_properties /** * @brief Constructor setting the pivot at the given value and the pair to -1 (i.e. not paired). * - * @param pivot Row index of the pivot. Corresponds to the IDIdx index of the face represented by the column. + * @param pivot Row index of the pivot. Corresponds to the @ref IDIdx index of the face 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 Row index of the pivot. Corresponds to the IDIdx index of the face represented by the column. - * @param pair MatIdx index of the pair of the column. + * @param pivot Row index of the pivot. Corresponds to the @ref IDIdx index of the face 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) {} /** @@ -90,9 +95,9 @@ class Chain_column_extra_properties : pivot_(std::exchange(col.pivot_, -1)), pairedColumn_(std::exchange(col.pairedColumn_, -1)) {} /** - * @brief Returns -1 if the column is not paired, the matIdx of the pair otherwise. + * @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 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_; } /** @@ -105,7 +110,7 @@ class Chain_column_extra_properties /** * @brief Sets the value of the pair. * - * @param other_col MatIdx of the pair column. + * @param other_col @ref MatIdx of the pair column. */ void assign_paired_chain(index other_col) { pairedColumn_ = other_col; } /** @@ -134,9 +139,9 @@ class Chain_column_extra_properties void swap_pivots(Chain_column_extra_properties& other) { std::swap(pivot_, other.pivot_); } private: - id_index pivot_; /**< IDIdx index associated to the chain */ + 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, MatIdx of image of bijection otherwise. + -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. */ }; diff --git a/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/column_dimension_holder.h b/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/column_dimension_holder.h index 2aa7febef7..3bf9fb70e1 100644 --- a/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/column_dimension_holder.h +++ b/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/column_dimension_holder.h @@ -23,6 +23,8 @@ namespace Gudhi { namespace persistence_matrix { /** + * @ingroup persistence_matrix + * * @brief Empty structure. * Inheritated instead of @ref Column_dimension_holder, when the columns are not storing a dimension. */ @@ -40,6 +42,9 @@ struct Dummy_dimension_holder }; /** + * @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 instanciation of @ref Matrix from which all types and options are deduced. @@ -50,7 +55,7 @@ struct Column_dimension_holder using dimension_type = typename Master_matrix::dimension_type; /**< Dimension value type. */ /** - * @brief Default constructor. Sets the dimension to 0 for boundary matrices and to -1 for chain matrices. + * @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) {} /** diff --git a/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/heap_column.h b/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/heap_column.h index 1f401dc2d0..db1ffb90d1 100644 --- a/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/heap_column.h +++ b/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/heap_column.h @@ -31,6 +31,9 @@ namespace Gudhi { namespace persistence_matrix { /** + * @class Heap_column heap_column.h gudhi/Persistence_matrix/columns/heap_column.h + * @ingroup persistence_matrix + * * @brief Column class following the @ref PersistenceMatrixColumn concept. Not compatible with row access. * * Column based on a heap structure. The heap is represented as a vector sorted as a heap. The top of the heap is @@ -1055,6 +1058,8 @@ inline bool Heap_column::_multiply_and_add(cons } // namespace Gudhi /** + * @ingroup persistence_matrix + * * @brief Hash method for @ref Gudhi::persistence_matrix::Heap_column. * * @tparam Master_matrix Template parameter of @ref Gudhi::persistence_matrix::Heap_column. diff --git a/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/intrusive_list_column.h b/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/intrusive_list_column.h index a8691a2055..a35746cc7d 100644 --- a/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/intrusive_list_column.h +++ b/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/intrusive_list_column.h @@ -31,6 +31,9 @@ namespace Gudhi { namespace persistence_matrix { /** + * @class Intrusive_list_column intrusive_list_column.h gudhi/Persistence_matrix/columns/intrusive_list_column.h + * @ingroup persistence_matrix + * * @brief Column class following the @ref PersistenceMatrixColumn concept. * * Column based on a intrusive list structure. The cells are always ordered by row index and only non-zero values @@ -1019,6 +1022,8 @@ inline bool Intrusive_list_column::_multiply_an } // namespace Gudhi /** + * @ingroup persistence_matrix + * * @brief Hash method for @ref Gudhi::persistence_matrix::Intrusive_list_column. * * @tparam Master_matrix Template parameter of @ref Gudhi::persistence_matrix::Intrusive_list_column. diff --git a/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/intrusive_set_column.h b/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/intrusive_set_column.h index 3fecff3456..bf7471fcc3 100644 --- a/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/intrusive_set_column.h +++ b/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/intrusive_set_column.h @@ -32,6 +32,9 @@ namespace Gudhi { namespace persistence_matrix { /** + * @class Intrusive_set_column intrusive_set_column.h gudhi/Persistence_matrix/columns/intrusive_set_column.h + * @ingroup persistence_matrix + * * @brief Column class following the @ref PersistenceMatrixColumn concept. * * Column based on a intrusive set structure. The cells are ordered by row index and only non-zero values @@ -1000,6 +1003,8 @@ inline bool Intrusive_set_column::_multiply_and /** + * @ingroup persistence_matrix + * * @brief Hash method for @ref Gudhi::persistence_matrix::Intrusive_set_column. * * @tparam Master_matrix Template parameter of @ref Gudhi::persistence_matrix::Intrusive_set_column. diff --git a/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/list_column.h b/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/list_column.h index 36783750e1..8b2ed2d1a1 100644 --- a/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/list_column.h +++ b/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/list_column.h @@ -32,6 +32,9 @@ namespace Gudhi { namespace persistence_matrix { /** + * @class List_column list_column.h gudhi/Persistence_matrix/columns/list_column.h + * @ingroup persistence_matrix + * * @brief Column class following the @ref PersistenceMatrixColumn concept. * * Column based on a list structure. The cells are always ordered by row index and only non-zero values @@ -1082,6 +1085,8 @@ inline bool List_column::_multiply_and_add(cons } // namespace Gudhi /** + * @ingroup persistence_matrix + * * @brief Hash method for @ref Gudhi::persistence_matrix::List_column. * * @tparam Master_matrix Template parameter of @ref Gudhi::persistence_matrix::List_column. diff --git a/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/naive_vector_column.h b/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/naive_vector_column.h index d97ff2bc43..7e86f9c434 100644 --- a/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/naive_vector_column.h +++ b/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/naive_vector_column.h @@ -32,6 +32,9 @@ namespace Gudhi { namespace persistence_matrix { /** + * @class Naive_vector_column naive_vector_column.h gudhi/Persistence_matrix/columns/naive_vector_column.h + * @ingroup persistence_matrix + * * @brief Column class following the @ref PersistenceMatrixColumn concept. * * Column based on a vector structure. The cells are always ordered by row index and only non-zero values @@ -1123,6 +1126,8 @@ inline bool Naive_vector_column::_multiply_and_ } // namespace Gudhi /** + * @ingroup persistence_matrix + * * @brief Hash method for @ref Gudhi::persistence_matrix::Naive_vector_column. * * @tparam Master_matrix Template parameter of @ref Gudhi::persistence_matrix::Naive_vector_column. diff --git a/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/row_access.h b/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/row_access.h index 94879fbd47..762c3fb7a1 100644 --- a/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/row_access.h +++ b/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/row_access.h @@ -23,6 +23,8 @@ namespace Gudhi { namespace persistence_matrix { /** + * @ingroup persistence_matrix + * * @brief Empty structure. * Inheritated instead of @ref Row_access, if the row access is not enabled. */ @@ -37,6 +39,9 @@ struct Dummy_row_access }; /** + * @class Row_access row_access.h gudhi/Persistence_matrix/columns/row_access.h + * @ingroup persistence_matrix + * * @brief Class managing the row access for the columns. * * @tparam Master_matrix An instanciation of @ref Matrix from which all types and options are deduced. @@ -45,8 +50,8 @@ template class Row_access { public: - using index = typename Master_matrix::index; /**< MatIdx index type. */ - using id_index = typename Master_matrix::id_index; /**< IDIdx index type. */ + using index = typename Master_matrix::index; /**< @ref MatIdx index type. */ + using id_index = typename Master_matrix::id_index; /**< @ref IDIdx index type. */ using Cell_type = typename Master_matrix::Cell_type; /**< @ref Cell. */ using Row_container_type = typename Master_matrix::row_container_type; /**< Type of the row container. */ @@ -93,9 +98,9 @@ class Row_access */ void update_cell(const Cell_type& cell); /** - * @brief Returns the MatIdx column index. + * @brief Returns the @ref MatIdx column index. * - * @return The MatIdx column index. + * @return The @ref MatIdx column index. */ index get_column_index() const; diff --git a/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/set_column.h b/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/set_column.h index 3fda9d8489..87b13280e1 100644 --- a/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/set_column.h +++ b/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/set_column.h @@ -32,6 +32,9 @@ namespace Gudhi { namespace persistence_matrix { /** + * @class Set_column set_column.h gudhi/Persistence_matrix/columns/set_column.h + * @ingroup persistence_matrix + * * @brief Column class following the @ref PersistenceMatrixColumn concept. * * Column based on a set structure. The cells are always ordered by row index and only non-zero values @@ -994,6 +997,8 @@ inline bool Set_column::_multiply_and_add(const } // namespace Gudhi /** + * @ingroup persistence_matrix + * * @brief Hash method for @ref Gudhi::persistence_matrix::Set_column. * * @tparam Master_matrix Template parameter of @ref Gudhi::persistence_matrix::Set_column. diff --git a/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/unordered_set_column.h b/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/unordered_set_column.h index ce7d4d49a7..79009b4901 100644 --- a/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/unordered_set_column.h +++ b/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/unordered_set_column.h @@ -33,6 +33,9 @@ namespace Gudhi { namespace persistence_matrix { /** + * @class Unordered_set_column unordered_set_column.h gudhi/Persistence_matrix/columns/unordered_set_column.h + * @ingroup persistence_matrix + * * @brief Column class following the @ref PersistenceMatrixColumn concept. * * Column based on an unordered set structure. The cells are not ordered, but only non-zero values @@ -981,6 +984,8 @@ inline bool Unordered_set_column::_multiply_and } // namespace Gudhi /** + * @ingroup persistence_matrix + * * @brief Hash method for @ref Gudhi::persistence_matrix::Unordered_set_column. * * @tparam Master_matrix Template parameter of @ref Gudhi::persistence_matrix::Unordered_set_column. diff --git a/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/vector_column.h b/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/vector_column.h index ca5fac0360..01892f9b86 100644 --- a/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/vector_column.h +++ b/src/Persistence_matrix/include/gudhi/Persistence_matrix/columns/vector_column.h @@ -33,6 +33,9 @@ namespace Gudhi { namespace persistence_matrix { /** + * @class Vector_column vector_column.h gudhi/Persistence_matrix/columns/vector_column.h + * @ingroup persistence_matrix + * * @brief Column class following the @ref PersistenceMatrixColumn concept. * * Column based on a vector structure. The cells are always ordered by row index, but cells are removed by @@ -1326,6 +1329,8 @@ inline bool Vector_column::_multiply_and_add(co } // namespace Gudhi /** + * @ingroup persistence_matrix + * * @brief Hash method for @ref Gudhi::persistence_matrix::Vector_column. * * @tparam Master_matrix Template parameter of @ref Gudhi::persistence_matrix::Vector_column. diff --git a/src/Persistence_matrix/include/gudhi/Persistence_matrix/matrix_dimension_holders.h b/src/Persistence_matrix/include/gudhi/Persistence_matrix/matrix_dimension_holders.h index 6d69f99b49..113c7cc755 100644 --- a/src/Persistence_matrix/include/gudhi/Persistence_matrix/matrix_dimension_holders.h +++ b/src/Persistence_matrix/include/gudhi/Persistence_matrix/matrix_dimension_holders.h @@ -25,6 +25,8 @@ namespace Gudhi { namespace persistence_matrix { /** + * @ingroup persistence_matrix + * * @brief Empty structure. * Inheritated instead of @ref Matrix_max_dimension_holder or @ref Matrix_all_dimension_holder, when the maximal * dimension of a matrix is not stored. @@ -38,6 +40,8 @@ struct Dummy_matrix_dimension_holder { }; /** + * @ingroup persistence_matrix + * * @brief Class managing the maximal dimension of a face represented in the inheritating matrix, when the option of * face removal is not enabled. * @@ -98,6 +102,8 @@ class Matrix_max_dimension_holder }; /** + * @ingroup persistence_matrix + * * @brief Class managing the maximal dimension of a face represented in the inheritating matrix, when the option of * face removal is enabled. * diff --git a/src/Persistence_matrix/include/gudhi/Persistence_matrix/matrix_row_access.h b/src/Persistence_matrix/include/gudhi/Persistence_matrix/matrix_row_access.h index 02eb4f6138..98c1a77209 100644 --- a/src/Persistence_matrix/include/gudhi/Persistence_matrix/matrix_row_access.h +++ b/src/Persistence_matrix/include/gudhi/Persistence_matrix/matrix_row_access.h @@ -23,6 +23,8 @@ namespace Gudhi { namespace persistence_matrix { /** + * @ingroup persistence_matrix + * * @brief Empty structure. * Inheritated instead of @ref Matrix_row_access, when the the row access is not enabled. */ @@ -34,6 +36,9 @@ struct Dummy_matrix_row_access { }; /** + * @class Matrix_row_access matrix_row_access.h gudhi/Persistence_matrix/matrix_row_access.h + * @ingroup persistence_matrix + * * @brief Class managing the row access for the inheritating matrix. * * @tparam Row_type Either boost::intrusive::list if @ref PersistenceMatrixOptions::has_intrusive_rows @@ -41,7 +46,7 @@ struct Dummy_matrix_row_access { * @tparam Row_container_type Either std::map if @ref PersistenceMatrixOptions::has_removable_rows is * true, or std::vector otherwise. * @tparam has_removable_rows Value of @ref PersistenceMatrixOptions::has_removable_rows. - * @tparam id_index IDIdx index type. + * @tparam id_index @ref IDIdx index type. */ template class Matrix_row_access @@ -90,10 +95,10 @@ class Matrix_row_access * @brief Returns the row at the given row index, see [TODO: description]. * The type of the row depends on the choosen options, see @ref PersistenceMatrixOptions::has_intrusive_rows. * - * @warning The @ref get_column_index method of the row cells returns the original PosIdx indices (before any swaps) - * for boundary matrices and MatIdx indices for chain matrices. + * @warning The @ref get_column_index method of the row cells returns the original @ref PosIdx indices (before any swaps) + * for @ref boundarymatrix "boundary matrices" and @ref MatIdx indices for @ref chainmatrix "chain matrices". * - * @param rowIndex Row index of the row to return: IDIdx for chain matrices or updated IDIdx for boundary matrices + * @param rowIndex Row index of the row to return: @ref IDIdx for @ref chainmatrix "chain matrices" or updated @ref IDIdx for @ref boundarymatrix "boundary matrices" * if swaps occured, see [TODO: description]. * @return Reference to the row. */ @@ -108,10 +113,10 @@ class Matrix_row_access * @brief Returns the row at the given row index, see [TODO: description]. * The type of the row depends on the choosen options, see @ref PersistenceMatrixOptions::has_intrusive_rows. * - * @warning The @ref get_column_index method of the row cells returns the original PosIdx indices (before any swaps) - * for boundary matrices and MatIdx indices for chain matrices. + * @warning The @ref get_column_index method of the row cells returns the original @ref PosIdx indices (before any swaps) + * for @ref boundarymatrix "boundary matrices" and @ref MatIdx indices for @ref chainmatrix "chain matrices". * - * @param rowIndex Row index of the row to return: IDIdx for chain matrices or updated IDIdx for boundary matrices + * @param rowIndex Row index of the row to return: @ref IDIdx for @ref chainmatrix "chain matrices" or updated @ref IDIdx for @ref boundarymatrix "boundary matrices" * if swaps occured, see [TODO: description]. * @return Const reference to the row. */ diff --git a/src/Persistence_matrix/include/gudhi/Persistence_matrix/overlay_ididx_to_matidx.h b/src/Persistence_matrix/include/gudhi/Persistence_matrix/overlay_ididx_to_matidx.h index 1ec5ef4479..740225f4f5 100644 --- a/src/Persistence_matrix/include/gudhi/Persistence_matrix/overlay_ididx_to_matidx.h +++ b/src/Persistence_matrix/include/gudhi/Persistence_matrix/overlay_ididx_to_matidx.h @@ -9,7 +9,7 @@ */ /** - * @file overlay_ididx_to_matidx.h + * @file overlay_@ref IDIdx_to_@ref MatIdx.h * @author Hannah Schreiber * @brief Contains the @ref Id_to_index_overlay class. */ @@ -26,8 +26,11 @@ namespace Gudhi { namespace persistence_matrix { /** - * @brief Overlay for non basic matrices replacing all input and output MatIdx indices of the original methods - * with IDIdx indices. + * @class Id_to_index_overlay overlay_ididx_to_matidx.h gudhi/Persistence_matrix/overlay_ididx_to_matidx.h + * @ingroup persistence_matrix + * + * @brief Overlay for non @ref basematrix "basic matrices" replacing all input and output @ref MatIdx indices of the original methods + * with @ref IDIdx indices. * * @tparam Matrix_type Matrix type taking the overlay. * @tparam Master_matrix_type An instanciation of @ref Matrix from which all types and options are deduced. @@ -36,8 +39,8 @@ template class Id_to_index_overlay { public: - using index = typename Master_matrix_type::index; /**< MatIdx index type. */ - using id_index = typename Master_matrix_type::id_index; /**< IDIdx index type. */ + using index = typename Master_matrix_type::index; /**< @ref MatIdx index type. */ + using id_index = typename Master_matrix_type::id_index; /**< @ref IDIdx index type. */ using dimension_type = typename Master_matrix_type::dimension_type; /**< Dimension value type. */ /** * @brief Field operators class. Necessary only if @ref PersistenceMatrixOptions::is_z2 is false. @@ -67,7 +70,7 @@ class Id_to_index_overlay * * @tparam Boundary_type Range type for @ref Matrix::cell_rep_type ranges. * Assumed to have a begin(), end() and size() method. - * @param orderedBoundaries Range of boundaries: @p orderedBoundaries is interpreted as a boundary matrix of a + * @param orderedBoundaries Range of boundaries: @p orderedBoundaries is interpreted as a @ref boundarymatrix "boundary matrix" of a * filtered **simplicial** complex, whose boundaries are ordered by filtration order. * Therefore, `orderedBoundaries[i]` should store the boundary of the \f$ i^th \f$ simplex in the filtration, * as an ordered list of indices of its facets (again those indices correspond to their respective position @@ -92,7 +95,7 @@ class Id_to_index_overlay */ Id_to_index_overlay(unsigned int numberOfColumns, Field_operators* operators, Cell_constructor* cellConstructor); /** - * @brief Only available for chain matrices. Constructs an empty matrix and stores the given comparators. + * @brief Only available for @ref chainmatrix "chain matrices". Constructs an empty matrix and stores the given comparators. * * @warning If @ref PersistenceMatrixOptions::has_vine_update is false, the comparators are not used. * And if @ref PersistenceMatrixOptions::has_vine_update is true, but @@ -102,11 +105,11 @@ class Id_to_index_overlay * @tparam EventComparatorFunction Method of the form: ( @ref pos_index, @ref pos_index ) -> bool. * @param operators Pointer to the field operators. * @param cellConstructor Pointer to the cell factory. - * @param birthComparator Method taking two PosIdx indices as input and returning true if and only if + * @param birthComparator Method taking two @ref PosIdx indices as input and returning true if and only if * the birth associated to the first position is strictly less than birth associated to * the second one with respect to some self defined order. It is used while swapping two unpaired or * two negative columns. - * @param deathComparator Method taking two PosIdx indices as input and returning true if and only if + * @param deathComparator Method taking two @ref PosIdx indices as input and returning true if and only if * the death associated to the first position is strictly less than death associated to * the second one with respect to some self defined order. It is used while swapping two positive but paired * columns. @@ -117,7 +120,7 @@ class Id_to_index_overlay EventComparatorFunction&& birthComparator, EventComparatorFunction&& deathComparator); /** - * @brief Only available for chain matrices. + * @brief Only available for @ref chainmatrix "chain matrices". * Constructs a new matrix from the given ranges of @ref cell_rep_type. Each range corresponds to a column * (the order of the ranges are preserved). The content of the ranges is assumed to be sorted by increasing IDs. * The IDs of the simplices are also assumed to be consecutifs, ordered by filtration value, starting with 0. @@ -130,7 +133,7 @@ class Id_to_index_overlay * @tparam EventComparatorFunction Method of the form: ( @ref pos_index, @ref pos_index ) -> bool. * @tparam Boundary_type Range type for @ref Matrix::cell_rep_type ranges. * Assumed to have a begin(), end() and size() method. - * @param orderedBoundaries Range of boundaries: @p orderedBoundaries is interpreted as a boundary matrix of a + * @param orderedBoundaries Range of boundaries: @p orderedBoundaries is interpreted as a @ref boundarymatrix "boundary matrix" of a * filtered **simplicial** complex, whose boundaries are ordered by filtration order. * Therefore, `orderedBoundaries[i]` should store the boundary of the \f$ i^th \f$ simplex in the filtration, * as an ordered list of indices of its facets (again those indices correspond to their respective position @@ -141,11 +144,11 @@ class Id_to_index_overlay * the matrix with the `Matrix(int numberOfColumns)` constructor preferably). * @param operators Pointer to the field operators. * @param cellConstructor Pointer to the cell factory. - * @param birthComparator Method taking two PosIdx indices as input and returning true if and only if + * @param birthComparator Method taking two @ref PosIdx indices as input and returning true if and only if * the birth associated to the first position is strictly less than birth associated to * the second one with respect to some self defined order. It is used while swapping two unpaired or * two negative columns. - * @param deathComparator Method taking two PosIdx indices as input and returning true if and only if + * @param deathComparator Method taking two @ref PosIdx indices as input and returning true if and only if * the death associated to the first position is strictly less than death associated to * the second one with respect to some self defined order. It is used while swapping two positive but paired * columns. @@ -157,7 +160,7 @@ class Id_to_index_overlay EventComparatorFunction&& birthComparator, EventComparatorFunction&& deathComparator); /** - * @brief Only available for chain matrices. + * @brief Only available for @ref chainmatrix "chain matrices". * Constructs a new empty matrix and reserves space for the given number of columns. * * @warning If @ref PersistenceMatrixOptions::has_vine_update is false, the comparators are not used. @@ -169,11 +172,11 @@ class Id_to_index_overlay * @param numberOfColumns Number of columns to reserve space for. * @param operators Pointer to the field operators. * @param cellConstructor Pointer to the cell factory. - * @param birthComparator Method taking two PosIdx indices as input and returning true if and only if + * @param birthComparator Method taking two @ref PosIdx indices as input and returning true if and only if * the birth associated to the first position is strictly less than birth associated to * the second one with respect to some self defined order. It is used while swapping two unpaired or * two negative columns. - * @param deathComparator Method taking two PosIdx indices as input and returning true if and only if + * @param deathComparator Method taking two @ref PosIdx indices as input and returning true if and only if * the death associated to the first position is strictly less than death associated to * the second one with respect to some self defined order. It is used while swapping two positive but paired * columns. @@ -225,7 +228,7 @@ class Id_to_index_overlay * - If it is a boundary type matrix and both \f$ R \f$ and \f$ U \f$ are stored, the new boundary is stored in its * reduced form and the barcode, if active, is also updated. * - If it is a chain type matrix, the new column is of the form - * `IDIdx + linear combination of older column IDIdxs`, where the combination is deduced while reducing the + * `@ref IDIdx + linear combination of older column @ref IDIdxs`, where the combination is deduced while reducing the * given boundary. If the barcode is stored, it will also be updated. * * @tparam Boundary_type Range of @ref Matrix::cell_rep_type. Assumed to have a begin(), end() and size() method. @@ -244,7 +247,7 @@ class Id_to_index_overlay * the faces are inserted by order of filtration), it is sufficient to indicate the ID of the face being inserted. * * @tparam Boundary_type Range of @ref Matrix::cell_rep_type. Assumed to have a begin(), end() and size() method. - * @param faceIndex IDIdx index to use to indentify the new face. + * @param faceIndex @ref IDIdx index to use to indentify the new face. * @param boundary Boundary generating the new column. The indices of the boundary have to correspond to the * @p faceIndex values of precedent calls of the method for the corresponding faces and should be ordered in * increasing order. @@ -254,11 +257,11 @@ class Id_to_index_overlay template void insert_boundary(id_index faceIndex, const Boundary_type& boundary, dimension_type dim = -1); /** - * @brief Returns the column at the given IDIdx index. + * @brief Returns the column at the given @ref IDIdx index. * For RU matrices, the returned column is from \f$ R \f$. * The type of the column depends on the choosen options, see @ref PersistenceMatrixOptions::column_type. * - * @param faceID IDIdx index of the column to return. + * @param faceID @ref IDIdx index of the column to return. * @return Reference to the column. */ Column_type& get_column(id_index faceID); @@ -267,26 +270,26 @@ class Id_to_index_overlay * For RU matrices, the returned row is from \f$ R \f$. * The type of the row depends on the choosen options, see @ref PersistenceMatrixOptions::has_intrusive_rows. * - * @warning The @ref get_column_index method of the row cells returns the original PosIdx indices (before any swaps) - * for boundary matrices and MatIdx indices for chain matrices. + * @warning The @ref get_column_index method of the row cells returns the original @ref PosIdx indices (before any swaps) + * for @ref boundarymatrix "boundary matrices" and @ref MatIdx indices for @ref chainmatrix "chain matrices". * - * @param rowIndex Row index of the row to return: IDIdx for chain matrices or updated IDIdx for boundary matrices + * @param rowIndex Row index of the row to return: @ref IDIdx for @ref chainmatrix "chain matrices" or updated @ref IDIdx for @ref boundarymatrix "boundary matrices" * if swaps occured, see [TODO: description]. * @return Reference to the row. */ Row_type& get_row(id_index rowIndex); /** * @brief The effect varies depending on the matrices and the options: - * - Boundary matrix with only \f$ R \f$ stored: + * - @ref boundarymatrix "boundary matrix" with only \f$ R \f$ stored: * - @ref PersistenceMatrixOptions::has_map_column_container and * @ref PersistenceMatrixOptions::has_column_and_row_swaps are true: * cleans up maps used for the lazy row swaps. * - @ref PersistenceMatrixOptions::has_row_access and @ref PersistenceMatrixOptions::has_removable_rows are true: * assumes that the row is empty and removes it. * - Otherwise, does nothing. - * - Boundary matrix with \f$ U \f$ stored: only \f$ R \f$ is affected by the above. + * - @ref boundarymatrix "boundary matrix" with \f$ U \f$ stored: only \f$ R \f$ is affected by the above. * If properly used, \f$ U \f$ will never have empty rows. - * - Chain matrix: only available if @ref PersistenceMatrixOptions::has_row_access and + * - @ref chainmatrix "chain matrix": only available if @ref PersistenceMatrixOptions::has_row_access and * @ref PersistenceMatrixOptions::has_removable_rows are true. * Assumes that the row is empty and removes it. * @@ -300,26 +303,26 @@ class Id_to_index_overlay */ void erase_row(id_index rowIndex); /** - * @brief Only available for RU and chain matrices and if @ref PersistenceMatrixOptions::has_removable_columns and + * @brief Only available for RU and @ref chainmatrix "chain matrices" and if @ref PersistenceMatrixOptions::has_removable_columns and * @ref PersistenceMatrixOptions::has_vine_update are true. - * For chain matrices, @ref PersistenceMatrixOptions::has_map_column_container and + * For @ref chainmatrix "chain matrices", @ref PersistenceMatrixOptions::has_map_column_container and * @ref PersistenceMatrixOptions::has_column_pairings also need to be true. * Assumes that the face is maximal in the current complex and removes it such that the matrix remains consistent - * (i.e., RU is still an upper triangular decomposition of the boundary matrix and chain is still a compatible + * (i.e., RU is still an upper triangular decomposition of the @ref boundarymatrix "boundary matrix" and chain is still a compatible * bases of the chain complex in the sense of @cite [TODO: zigzag paper]). * The maximality of the face is not verified. * Also updates the barcode if it was computed. * - * For chain matrices, using the other version of the method could perform better depending on how the data is + * For @ref chainmatrix "chain matrices", using the other version of the method could perform better depending on how the data is * maintained on the side of the user. Then, @ref has_column_pairings also do not need to be true. * * See also @ref remove_last. * - * @param faceID IDIdx index of the face to remove. + * @param faceID @ref IDIdx index of the face to remove. */ void remove_maximal_face(id_index faceID); /** - * @brief Only available for chain matrices and if @ref has_removable_columns, @ref has_vine_update + * @brief Only available for @ref chainmatrix "chain matrices" and if @ref has_removable_columns, @ref has_vine_update * and @ref has_map_column_container are true. * Assumes that the face is maximal in the current complex and removes it such that the matrix remains consistent * (i.e., it is still a compatible bases of the chain complex in the sense of @cite [TODO: zigzag paper]). @@ -327,29 +330,29 @@ class Id_to_index_overlay * Also updates the barcode if it was computed. * * To maintain the compatibility, vine swaps are done to move the face up to the end of the filtration. Once at - * the end, the removal is trivial. But for chain matrices, swaps do not actually swap the position of the column + * the end, the removal is trivial. But for @ref chainmatrix "chain matrices", swaps do not actually swap the position of the column * every time, so the faces appearing after @p faceIndex in the filtration have to be searched first within the - * matrix. If the user has an easy access to the IDIdx of the faces in the order of filtration, passing them by + * matrix. If the user has an easy access to the @ref IDIdx of the faces in the order of filtration, passing them by * argument with @p columnsToSwap allows to skip a linear search process. Typically, if the user knows that the * face he wants to remove is already the last face of the filtration, calling `remove_maximal_face(faceIndex, {})` * will be faster than `remove_last()`. * * See also @ref remove_last. * - * @param faceID IDIdx index of the face to remove. - * @param columnsToSwap Vector of IDIdx indices of the faces coming after @p faceID in the filtration. + * @param faceID @ref IDIdx index of the face to remove. + * @param columnsToSwap Vector of @ref IDIdx indices of the faces coming after @p faceID in the filtration. */ void remove_maximal_face(id_index faceID, const std::vector& columnsToSwap); /** * @brief Only available if @ref PersistenceMatrixOptions::has_removable_columns is true. Additionnaly, if the - * matrix is a chain matrix, either @ref PersistenceMatrixOptions::has_map_column_container has to be true or + * matrix is a @ref chainmatrix "chain matrix", either @ref PersistenceMatrixOptions::has_map_column_container has to be true or * @ref PersistenceMatrixOptions::has_vine_update has to be false. * Removes the last face in the filtration from the matrix and updates the barcode if it is stored. * * See also @ref remove_maximal_face. * - * For chain matrices, if @ref has_vine_update is true, the last face does not have to be at the end of the matrix - * and therefore has to be searched first. In this case, if the user already knows the IDIdx of the last face, + * For @ref chainmatrix "chain matrices", if @ref has_vine_update is true, the last face does not have to be at the end of the matrix + * and therefore has to be searched first. In this case, if the user already knows the @ref IDIdx of the last face, * calling `remove_maximal_face(faceID, {})` instead allows to skip the search. */ void remove_last(); @@ -368,9 +371,9 @@ class Id_to_index_overlay */ index get_number_of_columns() const; /** - * @brief Returns the dimension of the given face. Only available for non basic matrices. + * @brief Returns the dimension of the given face. Only available for non @ref basematrix "basic matrices". * - * @param faceID IDIdx index of the face. + * @param faceID @ref IDIdx index of the face. * @return Dimension of the face. */ dimension_type get_column_dimension(id_index faceID) const; @@ -379,11 +382,11 @@ class Id_to_index_overlay * @brief Adds column corresponding to @p sourceFaceID onto the column corresponding to @p targetFaceID. * * @warning They will be no verification to ensure that the addition makes sense for the validity of a - * chain matrix. For example, a right-to-left addition could corrupt the computation + * @ref chainmatrix "chain matrix". For example, a right-to-left addition could corrupt the computation * of the barcode if done blindly. So should be used with care. * - * @param sourceFaceID IDIdx index of the source column. - * @param targetFaceID IDIdx index of the target column. + * @param sourceFaceID @ref IDIdx index of the source column. + * @param targetFaceID @ref IDIdx index of the target column. */ void add_to(id_index sourceFaceID, id_index targetFaceID); /** @@ -391,12 +394,12 @@ class Id_to_index_overlay * That is: targetColumn = (targetColumn * coefficient) + sourceColumn. * * @warning They will be no verification to ensure that the addition makes sense for the validity of a - * chain matrix. For example, a right-to-left addition could corrupt the computation + * @ref chainmatrix "chain matrix". For example, a right-to-left addition could corrupt the computation * of the barcode if done blindly. So should be used with care. * - * @param sourceFaceID IDIdx index of the source column. + * @param sourceFaceID @ref IDIdx index of the source column. * @param coefficient Value to multiply. - * @param targetFaceID IDIdx index of the target column. + * @param targetFaceID @ref IDIdx index of the target column. */ void multiply_target_and_add_to(id_index sourceFaceID, const Field_element_type& coefficient, id_index targetFaceID); /** @@ -404,34 +407,34 @@ class Id_to_index_overlay * That is: targetColumn += (coefficient * sourceColumn). The source column will **not** be modified. * * @warning They will be no verification to ensure that the addition makes sense for the validity of a - * chain matrix. For example, a right-to-left addition could corrupt the computation + * @ref chainmatrix "chain matrix". For example, a right-to-left addition could corrupt the computation * of the barcode if done blindly. So should be used with care. * * @param coefficient Value to multiply. - * @param sourceFaceID IDIdx index of the source column. - * @param targetFaceID IDIdx index of the target column. + * @param sourceFaceID @ref IDIdx index of the source column. + * @param targetFaceID @ref IDIdx index of the target column. */ void multiply_source_and_add_to(const Field_element_type& coefficient, id_index sourceFaceID, id_index targetFaceID); /** - * @brief Zeroes the cell at the given coordinates. Not available for chain matrices. + * @brief Zeroes the cell at the given coordinates. Not available for @ref chainmatrix "chain matrices". * In general, should be used with care to not destroy the validity * of the persistence related properties of the matrix. * * For RU matrices, zeros only the cell in \f$ R \f$. * - * @param faceID IDIdx index of the face corresponding to the column of the cell. + * @param faceID @ref IDIdx index of the face corresponding to the column of the cell. * @param rowIndex Row index of the row of the cell. */ void zero_cell(id_index faceID, id_index rowIndex); /** - * @brief Zeroes the column at the given index. Not available for chain matrices. + * @brief Zeroes the column at the given index. Not available for @ref chainmatrix "chain matrices". * In general, should be used with care to not destroy the validity * of the persistence related properties of the matrix. * * For RU matrices, zeros only the column in \f$ R \f$. * - * @param faceID IDIdx index of the face corresponding to the column. + * @param faceID @ref IDIdx index of the face corresponding to the column. */ void zero_column(id_index faceID); /** @@ -439,7 +442,7 @@ class Id_to_index_overlay * * For RU matrices, looks into \f$ R \f$. * - * @param faceID IDIdx index of the face corresponding to the column of the cell. + * @param faceID @ref IDIdx index of the face corresponding to the column of the cell. * @param rowIndex Row index of the row of the cell. * @return true If the cell has value zero. * @return false Otherwise. @@ -450,30 +453,30 @@ class Id_to_index_overlay * * For RU matrices, looks into \f$ R \f$. * - * Note that for chain matrices, this method should always return false, as a valid chain matrix never has + * Note that for @ref chainmatrix "chain matrices", this method should always return false, as a valid @ref chainmatrix "chain matrix" never has * empty columns. * - * @param faceID IDIdx index of the face corresponding to the column. + * @param faceID @ref IDIdx index of the face corresponding to the column. * @return true If the column has value zero. * @return false Otherwise. */ bool is_zero_column(id_index faceID); /** - * @brief Returns the IDIdx index of the column which has the given row index as pivot. + * @brief Returns the @ref IDIdx index of the column which has the given row index as pivot. * Assumes that the pivot exists. For RU matrices, the column is returned from \f$ R \f$. * - * Recall that the row indices for chain matrices correspond to the IDIdx indices and that the row indices - * for a RU matrix correspond to the updated IDIdx indices which got potentially swapped by a vine swap. + * Recall that the row indices for @ref chainmatrix "chain matrices" correspond to the @ref IDIdx indices and that the row indices + * for a RU matrix correspond to the updated @ref IDIdx indices which got potentially swapped by a vine swap. * * @param faceIndex Row index of the pivot. - * @return IDIdx index of the column with the given pivot. + * @return @ref IDIdx index of the column with the given pivot. */ id_index get_column_with_pivot(id_index faceIndex) const; /** * @brief Returns the row index of the pivot of the given column. * - * @param faceID IDIdx index of the face corresponding to the column. + * @param faceID @ref IDIdx index of the face corresponding to the column. * @return The row index of the pivot. */ id_index get_pivot(id_index faceID); @@ -514,26 +517,26 @@ class Id_to_index_overlay * * Recall that we assume that the boundaries were inserted in the order of filtration for the barcode to be valid. * - * @warning For simple boundary matrices (only storing \f$ R \f$), we assume that `get_current_barcode` is only + * @warning For simple @ref boundarymatrix "boundary matrices" (only storing \f$ R \f$), we assume that `get_current_barcode` is only * called once, when the matrix is completed. * * @return A reference to the barcode. The barcode is a vector of @ref Bar. A bar stores three informations: - * the PosIdx birth index, the PosIdx death index and the dimension of the bar. + * the @ref PosIdx birth index, the @ref PosIdx death index and the dimension of the bar. */ const barcode_type& get_current_barcode(); /** - * @brief Only available for simple boundary matrices (only storing \f$ R \f$) and if + * @brief Only available for simple @ref boundarymatrix "boundary matrices" (only storing \f$ R \f$) and if * @ref PersistenceMatrixOptions::has_column_and_row_swaps is true. * Swaps the two given columns. Note that it really just swaps two columns and do not updates * anything else, nor performs additions to maintain some properties on the matrix. * - * @param faceID1 First column IDIdx index to swap. - * @param faceID2 Second column IDIdx index to swap. + * @param faceID1 First column @ref IDIdx index to swap. + * @param faceID2 Second column @ref IDIdx index to swap. */ void swap_columns(id_index faceID1, id_index faceID2); /** - * @brief Only available for simple boundary matrices (only storing R) + * @brief Only available for simple @ref boundarymatrix "boundary matrices" (only storing R) * and if @ref PersistenceMatrixOptions::has_column_and_row_swaps is true. * Swaps the two given rows. Note that it really just swaps two rows and do not updates * anything else, nor performs additions to maintain some properties on the matrix. @@ -547,10 +550,10 @@ class Id_to_index_overlay * Does the same than @ref vine_swap, but assumes that the swap is non trivial and * therefore skips a part of the case study. * - * @param faceID1 IDIdx index of the first face. - * @param faceID2 IDIdx index of the second face. It is assumed that the PosIdx of both only differs by one. - * @return Let pos1 be the PosIdx index of @p faceID1 and pos2 be the PosIdx index of @p faceID2. - * The method returns the IDIdx of the column which has now, after the swap, the PosIdx max(pos1, pos2). + * @param faceID1 @ref IDIdx index of the first face. + * @param faceID2 @ref IDIdx index of the second face. It is assumed that the @ref PosIdx of both only differs by one. + * @return Let pos1 be the @ref PosIdx index of @p faceID1 and pos2 be the @ref PosIdx index of @p faceID2. + * The method returns the @ref IDIdx of the column which has now, after the swap, the @ref PosIdx max(pos1, pos2). */ id_index vine_swap_with_z_eq_1_case(id_index faceID1, id_index faceID2); /** @@ -562,10 +565,10 @@ class Id_to_index_overlay * \f$ F' \f$ has to be a valid filtration. * See @cite [TODO: vineyard paper] for more information about vine and vineyards. * - * @param faceID1 IDIdx index of the first face. - * @param faceID2 IDIdx index of the second face. It is assumed that the PosIdx of both only differs by one. - * @return Let pos1 be the PosIdx index of @p faceID1 and pos2 be the PosIdx index of @p faceID2. - * The method returns the IDIdx of the column which has now, after the swap, the PosIdx max(pos1, pos2). + * @param faceID1 @ref IDIdx index of the first face. + * @param faceID2 @ref IDIdx index of the second face. It is assumed that the @ref PosIdx of both only differs by one. + * @return Let pos1 be the @ref PosIdx index of @p faceID1 and pos2 be the @ref PosIdx index of @p faceID2. + * The method returns the @ref IDIdx of the column which has now, after the swap, the @ref PosIdx max(pos1, pos2). */ id_index vine_swap(id_index faceID1, id_index faceID2); @@ -597,7 +600,7 @@ class Id_to_index_overlay using dictionnary_type = typename Master_matrix_type::template dictionnary_type; Matrix_type matrix_; /**< Interfaced matrix. */ - dictionnary_type* idToIndex_; /**< Map from IDIdx index to MatIdx index. */ + dictionnary_type* idToIndex_; /**< Map from @ref IDIdx index to @ref MatIdx index. */ index nextIndex_; /**< Next unused index. */ void _initialize_map(unsigned int size); diff --git a/src/Persistence_matrix/include/gudhi/Persistence_matrix/overlay_posidx_to_matidx.h b/src/Persistence_matrix/include/gudhi/Persistence_matrix/overlay_posidx_to_matidx.h index 7328817fd8..cb4c0f238a 100644 --- a/src/Persistence_matrix/include/gudhi/Persistence_matrix/overlay_posidx_to_matidx.h +++ b/src/Persistence_matrix/include/gudhi/Persistence_matrix/overlay_posidx_to_matidx.h @@ -9,7 +9,7 @@ */ /** - * @file overlay_posidx_to_matidx.h + * @file overlay_@ref PosIdx_to_@ref MatIdx.h * @author Hannah Schreiber * @brief Contains the @ref Position_to_index_overlay class. */ @@ -25,8 +25,11 @@ namespace Gudhi { namespace persistence_matrix { /** - * @brief Overlay for chain matrices replacing all input and output MatIdx indices of the original methods - * with PosIdx indices. The overlay is useless for boundary matrices as MatIdx == PosIdx for them. + * @class Position_to_index_overlay overlay_posidx_to_matidx.h gudhi/Persistence_matrix/overlay_posidx_to_matidx.h + * @ingroup persistence_matrix + * + * @brief Overlay for @ref chainmatrix "chain matrices" replacing all input and output @ref MatIdx indices of the original methods + * with @ref PosIdx indices. The overlay is useless for @ref boundarymatrix "boundary matrices" as @ref MatIdx == @ref PosIdx for them. * * @tparam Matrix_type Matrix type taking the overlay. * @tparam Master_matrix_type An instanciation of @ref Matrix from which all types and options are deduced. @@ -35,9 +38,9 @@ template class Position_to_index_overlay { public: - using index = typename Master_matrix_type::index; /**< MatIdx index type. */ - using id_index = typename Master_matrix_type::id_index; /**< IDIdx index type. */ - using pos_index = typename Master_matrix_type::pos_index; /**< PosIdx index type. */ + using index = typename Master_matrix_type::index; /**< @ref MatIdx index type. */ + using id_index = typename Master_matrix_type::id_index; /**< @ref IDIdx index type. */ + using pos_index = typename Master_matrix_type::pos_index; /**< @ref PosIdx index type. */ using dimension_type = typename Master_matrix_type::dimension_type; /**< Dimension value type. */ /** * @brief Field operators class. Necessary only if @ref PersistenceMatrixOptions::is_z2 is false. @@ -68,7 +71,7 @@ class Position_to_index_overlay * * @tparam Boundary_type Range type for @ref Matrix::cell_rep_type ranges. * Assumed to have a begin(), end() and size() method. - * @param orderedBoundaries Range of boundaries: @p orderedBoundaries is interpreted as a boundary matrix of a + * @param orderedBoundaries Range of boundaries: @p orderedBoundaries is interpreted as a @ref boundarymatrix "boundary matrix" of a * filtered **simplicial** complex, whose boundaries are ordered by filtration order. * Therefore, `orderedBoundaries[i]` should store the boundary of the \f$ i^th \f$ simplex in the filtration, * as an ordered list of indices of its facets (again those indices correspond to their respective position @@ -95,7 +98,7 @@ class Position_to_index_overlay Field_operators* operators, Cell_constructor* cellConstructor); /** - * @brief Only available for chain matrices. Constructs an empty matrix and stores the given comparators. + * @brief Only available for @ref chainmatrix "chain matrices". Constructs an empty matrix and stores the given comparators. * * @warning If @ref PersistenceMatrixOptions::has_vine_update is false, the comparators are not used. * And if @ref PersistenceMatrixOptions::has_vine_update is true, but @@ -105,11 +108,11 @@ class Position_to_index_overlay * @tparam EventComparatorFunction Method of the form: ( @ref pos_index, @ref pos_index ) -> bool. * @param operators Pointer to the field operators. * @param cellConstructor Pointer to the cell factory. - * @param birthComparator Method taking two PosIdx indices as input and returning true if and only if + * @param birthComparator Method taking two @ref PosIdx indices as input and returning true if and only if * the birth associated to the first position is strictly less than birth associated to * the second one with respect to some self defined order. It is used while swapping two unpaired or * two negative columns. - * @param deathComparator Method taking two PosIdx indices as input and returning true if and only if + * @param deathComparator Method taking two @ref PosIdx indices as input and returning true if and only if * the death associated to the first position is strictly less than death associated to * the second one with respect to some self defined order. It is used while swapping two positive but paired * columns. @@ -120,7 +123,7 @@ class Position_to_index_overlay EventComparatorFunction&& birthComparator, EventComparatorFunction&& deathComparator); /** - * @brief Only available for chain matrices. + * @brief Only available for @ref chainmatrix "chain matrices". * Constructs a new matrix from the given ranges of @ref cell_rep_type. Each range corresponds to a column * (the order of the ranges are preserved). The content of the ranges is assumed to be sorted by increasing IDs. * The IDs of the simplices are also assumed to be consecutifs, ordered by filtration value, starting with 0. @@ -133,7 +136,7 @@ class Position_to_index_overlay * @tparam EventComparatorFunction Method of the form: ( @ref pos_index, @ref pos_index ) -> bool. * @tparam Boundary_type Range type for @ref Matrix::cell_rep_type ranges. * Assumed to have a begin(), end() and size() method. - * @param orderedBoundaries Range of boundaries: @p orderedBoundaries is interpreted as a boundary matrix of a + * @param orderedBoundaries Range of boundaries: @p orderedBoundaries is interpreted as a @ref boundarymatrix "boundary matrix" of a * filtered **simplicial** complex, whose boundaries are ordered by filtration order. * Therefore, `orderedBoundaries[i]` should store the boundary of the \f$ i^th \f$ simplex in the filtration, * as an ordered list of indices of its facets (again those indices correspond to their respective position @@ -144,11 +147,11 @@ class Position_to_index_overlay * the matrix with the `Matrix(int numberOfColumns)` constructor preferably). * @param operators Pointer to the field operators. * @param cellConstructor Pointer to the cell factory. - * @param birthComparator Method taking two PosIdx indices as input and returning true if and only if + * @param birthComparator Method taking two @ref PosIdx indices as input and returning true if and only if * the birth associated to the first position is strictly less than birth associated to * the second one with respect to some self defined order. It is used while swapping two unpaired or * two negative columns. - * @param deathComparator Method taking two PosIdx indices as input and returning true if and only if + * @param deathComparator Method taking two @ref PosIdx indices as input and returning true if and only if * the death associated to the first position is strictly less than death associated to * the second one with respect to some self defined order. It is used while swapping two positive but paired * columns. @@ -160,7 +163,7 @@ class Position_to_index_overlay EventComparatorFunction&& birthComparator, EventComparatorFunction&& deathComparator); /** - * @brief Only available for chain matrices. + * @brief Only available for @ref chainmatrix "chain matrices". * Constructs a new empty matrix and reserves space for the given number of columns. * * @warning If @ref PersistenceMatrixOptions::has_vine_update is false, the comparators are not used. @@ -172,11 +175,11 @@ class Position_to_index_overlay * @param numberOfColumns Number of columns to reserve space for. * @param operators Pointer to the field operators. * @param cellConstructor Pointer to the cell factory. - * @param birthComparator Method taking two PosIdx indices as input and returning true if and only if + * @param birthComparator Method taking two @ref PosIdx indices as input and returning true if and only if * the birth associated to the first position is strictly less than birth associated to * the second one with respect to some self defined order. It is used while swapping two unpaired or * two negative columns. - * @param deathComparator Method taking two PosIdx indices as input and returning true if and only if + * @param deathComparator Method taking two @ref PosIdx indices as input and returning true if and only if * the death associated to the first position is strictly less than death associated to * the second one with respect to some self defined order. It is used while swapping two positive but paired * columns. @@ -218,7 +221,7 @@ class Position_to_index_overlay * a more general cell complex. This includes cubical complexes or Morse complexes for example. * * When inserted, the given boundary is reduced and from the reduction process, the column is deduced in the form of: - * `IDIdx + linear combination of older column IDIdxs`. If the barcode is stored, it will be updated. + * `@ref IDIdx + linear combination of older column @ref IDIdxs`. If the barcode is stored, it will be updated. * * @tparam Boundary_type Range of @ref Matrix::cell_rep_type. Assumed to have a begin(), end() and size() method. * @param boundary Boundary generating the new column. The content should be ordered by ID. @@ -236,7 +239,7 @@ class Position_to_index_overlay * the faces are inserted by order of filtration), it is sufficient to indicate the ID of the face being inserted. * * @tparam Boundary_type Range of @ref Matrix::cell_rep_type. Assumed to have a begin(), end() and size() method. - * @param faceID IDIdx index to use to indentify the new face. + * @param faceID @ref IDIdx index to use to indentify the new face. * @param boundary Boundary generating the new column. The indices of the boundary have to correspond to the * @p faceID values of precedent calls of the method for the corresponding faces and should be ordered in * increasing order. @@ -246,18 +249,18 @@ class Position_to_index_overlay template void insert_boundary(id_index faceIndex, const Boundary_type& boundary, dimension_type dim = -1); /** - * @brief Returns the column at the given PosIdx index. + * @brief Returns the column at the given @ref PosIdx index. * The type of the column depends on the choosen options, see @ref PersistenceMatrixOptions::column_type. * - * @param position PosIdx index of the column to return. + * @param position @ref PosIdx index of the column to return. * @return Reference to the column. */ Column_type& get_column(pos_index position); /** - * @brief Returns the column at the given PosIdx index. + * @brief Returns the column at the given @ref PosIdx index. * The type of the column depends on the choosen options, see @ref PersistenceMatrixOptions::column_type. * - * @param position PosIdx index of the column to return. + * @param position @ref PosIdx index of the column to return. * @return Const reference to the column. */ const Column_type& get_column(pos_index position) const; @@ -266,7 +269,7 @@ class Position_to_index_overlay * Returns the row at the given row index, see [TODO: description]. * The type of the row depends on the choosen options, see @ref PersistenceMatrixOptions::has_intrusive_rows. * - * @warning The @ref get_column_index method of the row cells returns the MatIdx indices for chain matrices. + * @warning The @ref get_column_index method of the row cells returns the @ref MatIdx indices for @ref chainmatrix "chain matrices". * * @param rowIndex Row index of the row to return, see [TODO: description]. * @return Reference to the row. @@ -277,7 +280,7 @@ class Position_to_index_overlay * Returns the row at the given row index, see [TODO: description]. * The type of the row depends on the choosen options, see @ref PersistenceMatrixOptions::has_intrusive_rows. * - * @warning The @ref get_column_index method of the row cells returns the MatIdx indices for chain matrices. + * @warning The @ref get_column_index method of the row cells returns the @ref MatIdx indices for @ref chainmatrix "chain matrices". * * @param rowIndex Row index of the row to return, see [TODO: description]. * @return Const reference to the row. @@ -308,7 +311,7 @@ class Position_to_index_overlay * * See also @ref remove_last. * - * @param position PosIdx index of the face to remove. + * @param position @ref PosIdx index of the face to remove. */ void remove_maximal_face(pos_index position); /** @@ -337,7 +340,7 @@ class Position_to_index_overlay /** * @brief Returns the dimension of the given face. * - * @param position PosIdx index of the face. + * @param position @ref PosIdx index of the face. * @return Dimension of the face. */ dimension_type get_column_dimension(pos_index position) const; @@ -346,11 +349,11 @@ class Position_to_index_overlay * @brief Adds column corresponding to @p sourcePosition onto the column corresponding to @p targetPosition. * * @warning They will be no verification to ensure that the addition makes sense for the validity of a - * chain matrix. For example, a right-to-left addition could corrupt the computation + * @ref chainmatrix "chain matrix". For example, a right-to-left addition could corrupt the computation * of the barcode if done blindly. So should be used with care. * - * @param sourcePosition PosIdx index of the source column. - * @param targetPosition PosIdx index of the target column. + * @param sourcePosition @ref PosIdx index of the source column. + * @param targetPosition @ref PosIdx index of the target column. */ void add_to(pos_index sourcePosition, pos_index targetPosition); /** @@ -358,12 +361,12 @@ class Position_to_index_overlay * That is: targetColumn = (targetColumn * coefficient) + sourceColumn. * * @warning They will be no verification to ensure that the addition makes sense for the validity of a - * chain matrix. For example, a right-to-left addition could corrupt the computation + * @ref chainmatrix "chain matrix". For example, a right-to-left addition could corrupt the computation * of the barcode if done blindly. So should be used with care. * - * @param sourcePosition PosIdx index of the source column. + * @param sourcePosition @ref PosIdx index of the source column. * @param coefficient Value to multiply. - * @param targetPosition PosIdx index of the target column. + * @param targetPosition @ref PosIdx index of the target column. */ void multiply_target_and_add_to(pos_index sourcePosition, const Field_element_type& coefficient, @@ -373,12 +376,12 @@ class Position_to_index_overlay * That is: targetColumn += (coefficient * sourceColumn). The source column will **not** be modified. * * @warning They will be no verification to ensure that the addition makes sense for the validity of a - * chain matrix. For example, a right-to-left addition could corrupt the computation + * @ref chainmatrix "chain matrix". For example, a right-to-left addition could corrupt the computation * of the barcode if done blindly. So should be used with care. * * @param coefficient Value to multiply. - * @param sourcePosition PosIdx index of the source column. - * @param targetPosition PosIdx index of the target column. + * @param sourcePosition @ref PosIdx index of the source column. + * @param targetPosition @ref PosIdx index of the target column. */ void multiply_source_and_add_to(const Field_element_type& coefficient, pos_index sourcePosition, @@ -387,7 +390,7 @@ class Position_to_index_overlay /** * @brief Indicates if the cell at given coordinates has value zero. * - * @param position PosIdx index of the face corresponding to the column of the cell. + * @param position @ref PosIdx index of the face corresponding to the column of the cell. * @param rowIndex Row index of the row of the cell. * @return true If the cell has value zero. * @return false Otherwise. @@ -396,27 +399,27 @@ class Position_to_index_overlay /** * @brief Indicates if the column at given index has value zero. * - * Note that this method should always return false, as a valid chain matrix never has + * Note that this method should always return false, as a valid @ref chainmatrix "chain matrix" never has * empty columns. * - * @param position PosIdx index of the face corresponding to the column. + * @param position @ref PosIdx index of the face corresponding to the column. * @return true If the column has value zero. * @return false Otherwise. */ bool is_zero_column(pos_index position); /** - * @brief Returns the PosIdx index of the column which has the given row index as pivot. + * @brief Returns the @ref PosIdx index of the column which has the given row index as pivot. * Assumes that the pivot exists. * * @param faceIndex Row index of the pivot. - * @return PosIdx index of the column with the given pivot. + * @return @ref PosIdx index of the column with the given pivot. */ pos_index get_column_with_pivot(id_index faceIndex) const; // assumes that pivot exists /** * @brief Returns the row index of the pivot of the given column. * - * @param position PosIdx index of the face corresponding to the column. + * @param position @ref PosIdx index of the face corresponding to the column. * @return The row index of the pivot. */ id_index get_pivot(pos_index position); @@ -461,7 +464,7 @@ class Position_to_index_overlay * Recall that we assume that the boundaries were inserted in the order of filtration for the barcode to be valid. * * @return A reference to the barcode. The barcode is a vector of @ref Bar. A bar stores three informations: - * the PosIdx birth index, the PosIdx death index and the dimension of the bar. + * the @ref PosIdx birth index, the @ref PosIdx death index and the dimension of the bar. */ const barcode_type& get_current_barcode() const; @@ -494,7 +497,7 @@ class Position_to_index_overlay * Does the same than @ref vine_swap, but assumes that the swap is non trivial and * therefore skips a part of the case study. * - * @param position PosIdx index of the first face to swap. The second one has to be at (@p position + 1). + * @param position @ref PosIdx index of the first face to swap. The second one has to be at (@p position + 1). * @return true If the barcode changed from the swap. * @return false Otherwise. */ @@ -508,7 +511,7 @@ class Position_to_index_overlay * \f$ F' \f$ has to be a valid filtration. * See @cite [TODO: vineyard paper] for more information about vine and vineyards. * - * @param position PosIdx index of the first face to swap. The second one has to be at (@p position + 1). + * @param position @ref PosIdx index of the first face to swap. The second one has to be at (@p position + 1). * @return true If the barcode changed from the swap. * @return false Otherwise. */ @@ -516,7 +519,7 @@ class Position_to_index_overlay private: Matrix_type matrix_; /**< Interfaced matrix. */ - std::vector positionToIndex_; /**< Map from PosIdx index to MatIdx index. */ + std::vector positionToIndex_; /**< Map from @ref PosIdx index to @ref MatIdx index. */ pos_index nextPosition_; /**< Next unused position. */ index nextIndex_; /**< Next unused index. */ }; diff --git a/src/Persistence_matrix/include/gudhi/Persistence_matrix/ru_matrix.h b/src/Persistence_matrix/include/gudhi/Persistence_matrix/ru_matrix.h index 316811aed4..a17cf1d4cd 100644 --- a/src/Persistence_matrix/include/gudhi/Persistence_matrix/ru_matrix.h +++ b/src/Persistence_matrix/include/gudhi/Persistence_matrix/ru_matrix.h @@ -25,7 +25,10 @@ namespace Gudhi { namespace persistence_matrix { /** - * @brief Matrix structure to store the ordered boundary matrix \f$ R \cdot U \f$ of a filtered complex + * @class RU_matrix ru_matrix.h gudhi/Persistence_matrix/ru_matrix.h + * @ingroup persistence_matrix + * + * @brief Matrix structure to store the ordered @ref boundarymatrix "boundary matrix" \f$ R \cdot U \f$ of a filtered complex * in order to compute its persistent homology, as well as representative cycles. * Supports vineyards (see [TODO: cite vineyard paper]) and the removal of maximal faces while maintaining * a valid barcode. Provides an access to its columns and rows. @@ -48,9 +51,9 @@ class RU_matrix : public Master_matrix::RU_pairing_option, only necessary with row access option. */ using Cell_constructor = typename Master_matrix::Cell_constructor; /**< Factory of @ref Cell classes. */ using boundary_type = typename Master_matrix::boundary_type; /**< Type of an input column. */ - using index = typename Master_matrix::index; /**< MatIdx index type. */ - using id_index = typename Master_matrix::id_index; /**< IDIdx index type. */ - using pos_index = typename Master_matrix::pos_index; /**< PosIdx index type. */ + using index = typename Master_matrix::index; /**< @ref MatIdx index type. */ + using id_index = typename Master_matrix::id_index; /**< @ref IDIdx index type. */ + using pos_index = typename Master_matrix::pos_index; /**< @ref PosIdx index type. */ using dimension_type = typename Master_matrix::dimension_type; /**< Dimension value type. */ /** @@ -67,7 +70,7 @@ class RU_matrix : public Master_matrix::RU_pairing_option, * * @tparam Boundary_type Range type for @ref Matrix::cell_rep_type ranges. * Assumed to have a begin(), end() and size() method. - * @param orderedBoundaries Range of boundaries: @p orderedBoundaries is interpreted as a boundary matrix of a + * @param orderedBoundaries Range of boundaries: @p orderedBoundaries is interpreted as a @ref boundarymatrix "boundary matrix" of a * filtered **simplicial** complex, whose boundaries are ordered by filtration order. * Therefore, `orderedBoundaries[i]` should store the boundary of the \f$ i^th \f$ simplex in the filtration, * as an ordered list of indices of its facets (again those indices correspond to their respective position @@ -139,7 +142,7 @@ class RU_matrix : public Master_matrix::RU_pairing_option, * the faces are inserted by order of filtration), it is sufficient to indicate the ID of the face being inserted. * * @tparam Boundary_type Range of @ref Matrix::cell_rep_type. Assumed to have a begin(), end() and size() method. - * @param faceIndex IDIdx index to use to indentify the new face. + * @param faceIndex @ref IDIdx index to use to indentify the new face. * @param boundary Boundary generating the new column. The indices of the boundary have to correspond to the * @p faceIndex values of precedent calls of the method for the corresponding faces and should be ordered in * increasing order. @@ -149,7 +152,7 @@ class RU_matrix : public Master_matrix::RU_pairing_option, template void insert_boundary(id_index faceIndex, const Boundary_type& boundary, dimension_type dim = -1); /** - * @brief Returns the column at the given MatIdx index in \f$ R \f$ if @p inR is true and + * @brief Returns the column at the given @ref MatIdx index in \f$ R \f$ if @p inR is true and * in \f$ U \f$ if @p inR is false. * The type of the column depends on the choosen options, see @ref PersistenceMatrixOptions::column_type. * @@ -157,7 +160,7 @@ class RU_matrix : public Master_matrix::RU_pairing_option, * It is therefore recommended to avoid calling `get_column` between vine swaps, otherwise the benefits * of the the lazyness is lost. * - * @param columnIndex MatIdx index of the column to return. + * @param columnIndex @ref MatIdx index of the column to return. * @param inR If true, returns the column in \f$ R \f$, if false, returns the column in \f$ U \f$. * Default value: true. * @return Reference to the column. @@ -200,13 +203,13 @@ class RU_matrix : public Master_matrix::RU_pairing_option, * @brief Only available if @ref PersistenceMatrixOptions::has_removable_columns and * @ref PersistenceMatrixOptions::has_vine_update are true. * Assumes that the face is maximal in the current complex and removes it such that the matrix remains consistent - * (i.e., RU is still an upper triangular decomposition of the boundary matrix). + * (i.e., RU is still an upper triangular decomposition of the @ref boundarymatrix "boundary matrix"). * The maximality of the face is not verified. * Also updates the barcode if it is stored. * * See also @ref remove_last. * - * @param columnIndex MatIdx index of the face to remove. + * @param columnIndex @ref MatIdx index of the face to remove. */ void remove_maximal_face(index columnIndex); /** @@ -233,7 +236,7 @@ class RU_matrix : public Master_matrix::RU_pairing_option, /** * @brief Returns the dimension of the given column. * - * @param columnIndex MatIdx index of the column representing the face. + * @param columnIndex @ref MatIdx index of the column representing the face. * @return Dimension of the face. */ dimension_type get_column_dimension(index columnIndex) const; @@ -242,11 +245,11 @@ class RU_matrix : public Master_matrix::RU_pairing_option, * @brief Adds column at @p sourceColumnIndex onto the column at @p targetColumnIndex in the matrix. * * @warning They will be no verification to ensure that the addition makes sense for the validity of a - * boundary matrix of a filtered complex. For example, a right-to-left addition could corrupt the computation + * @ref boundarymatrix "boundary matrix" of a filtered complex. For example, a right-to-left addition could corrupt the computation * of the barcode if done blindly. So should be used with care. * - * @param sourceColumnIndex MatIdx index of the source column. - * @param targetColumnIndex MatIdx index of the target column. + * @param sourceColumnIndex @ref MatIdx index of the source column. + * @param targetColumnIndex @ref MatIdx index of the target column. */ void add_to(index sourceColumnIndex, index targetColumnIndex); /** @@ -254,12 +257,12 @@ class RU_matrix : public Master_matrix::RU_pairing_option, * That is: targetColumn = (targetColumn * coefficient) + sourceColumn. * * @warning They will be no verification to ensure that the addition makes sense for the validity of a - * boundary matrix of a filtered complex. For example, a right-to-left addition could corrupt the computation + * @ref boundarymatrix "boundary matrix" of a filtered complex. For example, a right-to-left addition could corrupt the computation * of the barcode if done blindly. So should be used with care. * - * @param sourceColumnIndex MatIdx index of the source column. + * @param sourceColumnIndex @ref MatIdx index of the source column. * @param coefficient Value to multiply. - * @param targetColumnIndex MatIdx index of the target column. + * @param targetColumnIndex @ref MatIdx index of the target column. */ void multiply_target_and_add_to(index sourceColumnIndex, const Field_element_type& coefficient, @@ -269,12 +272,12 @@ class RU_matrix : public Master_matrix::RU_pairing_option, * That is: targetColumn += (coefficient * sourceColumn). The source column will **not** be modified. * * @warning They will be no verification to ensure that the addition makes sense for the validity of a - * boundary matrix of a filtered complex. For example, a right-to-left addition could corrupt the computation + * @ref boundarymatrix "boundary matrix" of a filtered complex. For example, a right-to-left addition could corrupt the computation * of the barcode if done blindly. So should be used with care. * * @param coefficient Value to multiply. - * @param sourceColumnIndex MatIdx index of the source column. - * @param targetColumnIndex MatIdx index of the target column. + * @param sourceColumnIndex @ref MatIdx index of the source column. + * @param targetColumnIndex @ref MatIdx index of the target column. */ void multiply_source_and_add_to(const Field_element_type& coefficient, index sourceColumnIndex, @@ -285,7 +288,7 @@ class RU_matrix : public Master_matrix::RU_pairing_option, * \f$ U \f$ if @p inR is false. Should be used with care to not destroy the validity of the persistence * related properties of the matrix. * - * @param columnIndex MatIdx index of the column of the cell. + * @param columnIndex @ref MatIdx index of the column of the cell. * @param rowIndex Row index of the row of the cell. * @param inR Boolean indicating in which matrix to zero: if true in \f$ R \f$ and if false in \f$ U \f$. * Default value: true. @@ -296,7 +299,7 @@ class RU_matrix : public Master_matrix::RU_pairing_option, * \f$ U \f$ if @p inR is false. Should be used with care to not destroy the validity of the persistence * related properties of the matrix. * - * @param columnIndex MatIdx index of the column to zero. + * @param columnIndex @ref MatIdx index of the column to zero. * @param inR Boolean indicating in which matrix to zero: if true in \f$ R \f$ and if false in \f$ U \f$. * Default value: true. */ @@ -305,7 +308,7 @@ class RU_matrix : public Master_matrix::RU_pairing_option, * @brief Indicates if the cell at given coordinates has value zero in \f$ R \f$ * if @p inR is true or in \f$ U \f$ if @p inR is false. * - * @param columnIndex MatIdx index of the column of the cell. + * @param columnIndex @ref MatIdx index of the column of the cell. * @param rowIndex Row index of the row of the cell. * @param inR Boolean indicating in which matrix to look: if true in \f$ R \f$ and if false in \f$ U \f$. * Default value: true. @@ -319,7 +322,7 @@ class RU_matrix : public Master_matrix::RU_pairing_option, * * Note that if @p inR is false, this method should usually return false. * - * @param columnIndex MatIdx index of the column. + * @param columnIndex @ref MatIdx index of the column. * @param inR Boolean indicating in which matrix to look: if true in \f$ R \f$ and if false in \f$ U \f$. * Default value: true. * @return true If the column has value zero. @@ -328,17 +331,17 @@ class RU_matrix : public Master_matrix::RU_pairing_option, bool is_zero_column(index columnIndex, bool inR = true); /** - * @brief Returns the MatIdx index of the column which has the given row index as pivot in \f$ R \f$. + * @brief Returns the @ref MatIdx index of the column which has the given row index as pivot in \f$ R \f$. * Assumes that the pivot exists. * * @param faceIndex Row index of the pivot, see [TODO: description]. - * @return MatIdx index of the column in \f$ R \f$ with the given pivot. + * @return @ref MatIdx index of the column in \f$ R \f$ with the given pivot. */ index get_column_with_pivot(index faceIndex) const; /** * @brief Returns the row index of the pivot of the given column in \f$ R \f$. * - * @param columnIndex MatIdx index of the column in \f$ R \f$. + * @param columnIndex @ref MatIdx index of the column in \f$ R \f$. * @return The row index of the pivot. */ index get_pivot(index columnIndex); @@ -403,7 +406,7 @@ class RU_matrix : public Master_matrix::RU_pairing_option, // TODO: make U not accessible by default and add option to enable access? Inaccessible, it // needs less options and we could avoid some ifs. u_matrix_type mirrorMatrixU_; /**< U. */ - dictionnary_type pivotToColumnIndex_; /**< Map from pivot row index to column MatIdx index. */ + dictionnary_type pivotToColumnIndex_; /**< Map from pivot row index to column @ref MatIdx index. */ pos_index nextEventIndex_; /**< Next birth or death index. */ Field_operators* operators_; /**< Field operators, can be nullptr if @ref PersistenceMatrixOptions::is_z2 is true. */ @@ -580,7 +583,7 @@ inline void RU_matrix::remove_last() if (nextEventIndex_ == 0) return; // empty matrix --nextEventIndex_; - // assumes PosIdx == MatIdx for boundary matrices. + // assumes @ref PosIdx == @ref MatIdx for @ref boundarymatrix "boundary matrices". if constexpr (Master_matrix::Option_list::has_column_pairings) { if constexpr (Master_matrix::hasFixedBarcode) { auto& bar = _barcode()[_indexToBar()[nextEventIndex_]]; diff --git a/src/Persistence_matrix/include/gudhi/Persistence_matrix/ru_pairing.h b/src/Persistence_matrix/include/gudhi/Persistence_matrix/ru_pairing.h index 1e70ea9b7c..8e45060e0d 100644 --- a/src/Persistence_matrix/include/gudhi/Persistence_matrix/ru_pairing.h +++ b/src/Persistence_matrix/include/gudhi/Persistence_matrix/ru_pairing.h @@ -23,6 +23,8 @@ namespace Gudhi { namespace persistence_matrix { /** + * @ingroup persistence_matrix + * * @brief Empty structure. * Inheritated instead of @ref RU_pairing, when the computation of the barcode was not enabled or if the pairing * is already managed by the vine update classes. @@ -34,6 +36,9 @@ struct Dummy_ru_pairing { }; /** + * @class RU_pairing ru_pairing.h gudhi/Persistence_matrix/ru_pairing.h + * @ingroup persistence_matrix + * * @brief Class managing the barcode for @ref RU_matrix if the option was enabled. * * @tparam Master_matrix An instanciation of @ref Matrix from which all types and options are deduced. @@ -84,7 +89,7 @@ class RU_pairing using dictionnary_type = typename Master_matrix::bar_dictionnary_type; barcode_type barcode_; /**< Bar container. */ - dictionnary_type indexToBar_; /**< Map from MatIdx index to bar index. */ + dictionnary_type indexToBar_; /**< Map from @ref MatIdx index to bar index. */ }; template diff --git a/src/Persistence_matrix/include/gudhi/Persistence_matrix/ru_rep_cycles.h b/src/Persistence_matrix/include/gudhi/Persistence_matrix/ru_rep_cycles.h index 7c2fda030d..d636638082 100644 --- a/src/Persistence_matrix/include/gudhi/Persistence_matrix/ru_rep_cycles.h +++ b/src/Persistence_matrix/include/gudhi/Persistence_matrix/ru_rep_cycles.h @@ -25,6 +25,8 @@ namespace Gudhi { namespace persistence_matrix { /** + * @ingroup persistence_matrix + * * @brief Empty structure. * Inheritated instead of @ref RU_representative_cycles, when the computation of the representative cycles * were not enabled. @@ -40,14 +42,18 @@ struct Dummy_ru_representative_cycles { // TODO: add coefficients ? Only Z2 token into account for now. /** + * @class RU_representative_cycles ru_rep_cycles.h gudhi/Persistence_matrix/ru_rep_cycles.h + * @ingroup persistence_matrix + * * @brief Class managing the representative cycles for @ref RU_matrix if the option was enabled. * * @tparam Master_matrix An instanciation of @ref Matrix from which all types and options are deduced. */ template -class RU_representative_cycles { +class RU_representative_cycles +{ public: - using index = typename Master_matrix::index; /**< MatIdx index type. */ + using index = typename Master_matrix::index; /**< @ref MatIdx index type. */ using Bar = typename Master_matrix::Bar; /**< Bar type. */ using cycle_type = typename Master_matrix::cycle_type; /**< Cycle type. */ diff --git a/src/Persistence_matrix/include/gudhi/Persistence_matrix/ru_vine_swap.h b/src/Persistence_matrix/include/gudhi/Persistence_matrix/ru_vine_swap.h index 3ee46671f9..fefe57cd2b 100644 --- a/src/Persistence_matrix/include/gudhi/Persistence_matrix/ru_vine_swap.h +++ b/src/Persistence_matrix/include/gudhi/Persistence_matrix/ru_vine_swap.h @@ -29,6 +29,8 @@ namespace Gudhi { namespace persistence_matrix { /** + * @ingroup persistence_matrix + * * @brief Empty structure. * Inheritated instead of @ref RU_vine_swap, when vine swappes are not enabled. */ @@ -41,6 +43,8 @@ struct Dummy_ru_vine_swap { }; /** + * @ingroup persistence_matrix + * * @brief Empty structure. * Inheritated instead of @ref RU_pairing, when the barcode is not stored. */ @@ -53,6 +57,9 @@ struct Dummy_ru_vine_pairing { }; /** + * @class RU_vine_swap ru_vine_swap.h gudhi/Persistence_matrix/ru_vine_swap.h + * @ingroup persistence_matrix + * * @brief Class managing the vine swaps for @ref RU_matrix. * * @tparam Master_matrix An instanciation of @ref Matrix from which all types and options are deduced. @@ -64,9 +71,9 @@ class RU_vine_swap : public std::conditional::type { public: - using index = typename Master_matrix::index; /**< MatIdx index type. */ - using id_index = typename Master_matrix::id_index; /**< IDIdx index type. */ - using pos_index = typename Master_matrix::pos_index; /**< PosIdx index type. */ + using index = typename Master_matrix::index; /**< @ref MatIdx index type. */ + using id_index = typename Master_matrix::id_index; /**< @ref IDIdx index type. */ + using pos_index = typename Master_matrix::pos_index; /**< @ref PosIdx index type. */ /** * @brief Default constructor. @@ -89,7 +96,7 @@ class RU_vine_swap : public std::conditional positionToRowIdx_; /**< Map from PosIdx index to row index. */ + std::vector positionToRowIdx_; /**< Map from @ref PosIdx index to row index. */ private: using RUP = typename std::conditional #include +/// Gudhi namespace. namespace Gudhi { +/// Persistence matrix namespace. namespace persistence_matrix { /** + * @class Matrix persistence_matrix.h gudhi/persistence_matrix.h + * @ingroup persistence_matrix + * * @brief Data structure for matrices, and in particular thought for matrices representing filtered complexes * in order to compute persistence and/or representative cycles. - * + * + * @anchor mp_matrices __%Matrix types:__ + * * The are roughly three types of matrices available and one is selected automatically depending on the options chosen: - * - a basic matrix which can represent any matrix and therefore will not make any assumption on its content. - * It is the only matrix type with the option of column compression (as it is the only one where it makes sense). - * This type is choosen by default when none of the homology related options are set to true: - * @ref has_column_pairings, @ref has_vine_update and @ref can_retrieve_representative_cycles. - * - a boundary matrix @f$ B = R \cdot U @f$ which either stores only @f$ R @f$ or the whole decomposition @f$ R @f$ - * and @f$ U @f$ depending on the options. This type is selected if @ref is_of_boundary_type is set to true and - * at least one of the following options: @ref has_column_pairings, @ref has_vine_update and - * @ref can_retrieve_representative_cycles. If only @ref has_column_pairings is true, then only @f$ R @f$ is stored, - * but if either @ref has_vine_update or @ref can_retrieve_representative_cycles is true, then @f$ U @f$ also needs - * to be stored. Note that the option @ref column_indexation_type will produce a small overhead when set to @ref Column_indexation_types::IDENTIFIER. - * - a chain complex matrix representing a `compatible base` of a filtered chain complex (see TODO: cite Clément's zigzag paper here). - * This matrix is deduced from the boundary matrix and therefore encodes more or less the same information - * but differently and can therefore be better suited for certain applications. This type can be used the same way - * than the precedent type, only the option @ref is_of_boundary_type has to be set to false. Note that the option - * @ref column_indexation_type will produce a small overhead when set to @ref Column_indexation_types::POSITION or @ref Column_indexation_types::IDENTIFIER. + * - @anchor basematrix a @ref basematrix "basic matrix" which can represent any matrix and therefore will not make any + * assumption on its content. It is the only matrix type with the option of column compression (as it is the only one + * where it makes sense). This type is choosen by default when none of the homology related options are set to true: + * @ref PersistenceMatrixOptions::has_column_pairings, @ref PersistenceMatrixOptions::has_vine_update and + * @ref PersistenceMatrixOptions::can_retrieve_representative_cycles. + * - @anchor boundarymatrix a @ref boundarymatrix "boundary matrix" @f$ B = R \cdot U @f$ which either stores only + * @f$ R @f$ or the whole decomposition @f$ R @f$ and @f$ U @f$ depending on the options. This type is selected if + * @ref PersistenceMatrixOptions::is_of_boundary_type is set to true and at least one of the following options: + * @ref PersistenceMatrixOptions::has_column_pairings, @ref PersistenceMatrixOptions::has_vine_update and + * @ref PersistenceMatrixOptions::can_retrieve_representative_cycles. If only + * @ref PersistenceMatrixOptions::has_column_pairings is true, then only @f$ R @f$ is stored, but if either + * @ref PersistenceMatrixOptions::has_vine_update or @ref PersistenceMatrixOptions::can_retrieve_representative_cycles + * is true, then @f$ U @f$ also needs to be stored. Note that the option + * @ref PersistenceMatrixOptions::column_indexation_type will produce a small overhead when set to + * @ref Column_indexation_types::IDENTIFIER. + * - @anchor chainmatrix a @ref chainmatrix "chain complex matrix" representing a "compatible base" of a filtered chain + * complex (see @cite zigzag). This matrix is deduced from the boundary matrix and therefore encodes more or less the + * same information but differently and can therefore be better suited for certain applications. This type can be used + * the same way than the precedent type, only the option @ref PersistenceMatrixOptions::is_of_boundary_type has to be + * set to false. Note that the option @ref PersistenceMatrixOptions::column_indexation_type will produce a small + * overhead when set to @ref Column_indexation_types::POSITION or @ref Column_indexation_types::IDENTIFIER. * - * __Indexation scheme:__ + * @anchor mp_indexation __Indexation scheme:__ * - * The indexation system for columns of the different matrix types can be a bit tricky and different methods will not always take - * the same type of index as input (for optimization purposes). So, to avoid confusion, we will name and define here the - * different possibilities, such that we can directly refer to it in the descriptions of the methods. - * Note that every column and row in a boundary or chain matrix is always associated to a single simplex/face, - * so in order to avoid repeating formulations like "of the simplex associated to the column" all the time, - * we will amalgamate both notions together. + * The indexation system for columns of the different matrix types can be a bit tricky and different methods will not + * always take the same type of index as input (for optimization purposes). So, to avoid confusion, we will name and + * define here the different possibilities, such that we can directly refer to it in the descriptions of the methods. + * Note that every column and row in a @ref boundarymatrix "boundary" or @ref chainmatrix "chain matrix" is always + * associated to a single simplex/face, so in order to avoid repeating formulations like "of the simplex associated to + * the column" all the time, we will amalgamate both notions together. * - * Let c be a column. - * - MatIdx: This will correspond to the position of c in the matrix, i.e., underlying_container[MatIdx] = c. - * This will be the only public indexing scheme for basic matrices (first of the list above). - * - PosIdx: This will correspond to the relative position of c in the current filtration compared to the other columns, - * starting the count at 0. For boundary matrices, PosIdx will always be equal to MatIdx, but this is not true for - * chain matrices, where MatIdx will correspond to the relative position of c in the original filtration - * (so PosIdx == MatIdx as long as no vine swaps are done). - * - IDIdx: This will correspond to the ID of c in the complex used to identify it in the boundaries. - * If at the insertion of c, its ID was not specified and it was the nth insertion, it is assumed that the ID is n - * (which means that IDIdx and PosIdx will only start to differ when swaps or removals are performed). - * If an ID is specified at the insertion of c, the ID is stored as the IDIdx of c. IDs can be freely choosed with - * the only restriction that they have to be strictly increasing in the order of the filtration. + * Let @f$ c @f$ be a column. + * - @anchor MatIdx @ref MatIdx "MatIdx": This will correspond to the position of @f$ c @f$ in the matrix, i.e., + * @f$ underlying\_container[MatIdx] = c @f$. This will be the only public indexing scheme for + * @ref basematrix "basic matrices". + * - @anchor PosIdx @ref PosIdx "PosIdx": This will correspond to the relative position of @f$ c @f$ in the current + * filtration compared to the other columns, starting the count at 0. For @ref boundarymatrix "boundary matrices", + * @ref PosIdx will always be equal to @ref MatIdx, but this is not true for @ref chainmatrix "chain matrices" when + * swaps or removals were performed. + * - @anchor IDIdx @ref IDIdx "IDIdx": This will correspond to the ID of @f$ c @f$ in the complex used to identify it in + * the boundaries. If at the insertion of @f$ c @f$, its ID was not specified and it was the @f$ n^{th} @f$ insertion, + * it is assumed that the ID is @f$ n @f$ (which means that @ref IDIdx and @ref PosIdx will only start to differ when + * swaps or removals are performed). If an ID is specified at the insertion of @f$ c @f$, the ID is stored as the + * @ref IDIdx of @f$ c @f$. IDs can be freely choosed with the only restriction that they have to be strictly + * increasing in the order of the filtration. * * In conclusion, with default values, if no vine swaps or removals occurs, all three indexing schemes are the same. * - * Let r be a row. Rows are indexed in two ways depending only if the matrix is a chain matrix or not. - * If the matrix is a chain matrix, r is always indexed by its ID, so it correspond to the IDIdx indexing scheme. - * If the matrix is not a chain matrix, r will originaly also be indexed by the ID, but when a swap occurs, - * the rows also swap IDs and the new ID has to be used to access r. This means that when the default IDIdx scheme - * is used, the indexation of the rows correspond to PosIdx. - * - * @tparam Options Structure encoding all the options of the matrix. - * See description of @ref Default_options for more details. + * @anchor rowindex Let @f$ r @f$ be a row. Rows are indexed in two ways depending only if the matrix is a + * @ref chainmatrix "chain matrix" or not. If the matrix is a @ref chainmatrix "chain matrix", @f$ r @f$ is always + * indexed by its ID, so it correspond to the @ref IDIdx indexing scheme. If the matrix is not a + * @ref chainmatrix "chain matrix", @f$ r @f$ will originaly also be indexed by the ID, but when a swap occurs, + * the rows also swap IDs and the new ID has to be used to access @f$ r @f$. This means that when the default + * @ref IDIdx scheme is used (the faces are numerated in order of appearence in the filtration starting at 0), + * the indexation of the rows correspond to @ref PosIdx. + * + * @tparam PersistenceMatrixOptions Structure encoding all the options of the matrix. + * See description of @ref PersistenceMatrixOptions for more details. */ template > class Matrix { public: using Option_list = PersistenceMatrixOptions; //to make it accessible from the other classes - using index = typename PersistenceMatrixOptions::index_type; /**< Type of MatIdx index. */ - using id_index = typename PersistenceMatrixOptions::index_type; /**< Type of IDIdx index. */ - using pos_index = typename PersistenceMatrixOptions::index_type; /**< Type of PosIdx index. */ + using index = typename PersistenceMatrixOptions::index_type; /**< Type of @ref MatIdx index. */ + using id_index = typename PersistenceMatrixOptions::index_type; /**< Type of @ref IDIdx index. */ + using pos_index = typename PersistenceMatrixOptions::index_type; /**< Type of @ref PosIdx index. */ using dimension_type = typename PersistenceMatrixOptions::dimension_type; /**< Type for dimension value. */ struct Dummy_field_operators{ @@ -139,11 +156,17 @@ class Matrix { static constexpr characteristic_type get_characteristic() { return 2; } }; + /** + * @brief Coefficiants field type. + */ using Field_operators = typename std::conditional::type; /**< Coefficiants field type. */ + >::type; + /** + * @brief Type of a field element. + */ using element_type = typename std::conditional; /** - * @brief Type used to identify a cell, for exemple when inserting a boundary. If @ref is_z2 is true, the type is - * an IDIdx and corresponds to the row index of the cell (the cell value is assumed to be 1). - * If @ref is_z2 is false, the type is a pair whose first element is the row index of the cell and - * the second element is the value of the cell (which again is assumed to be non-zero). The column index of the row - * is always deduced from the context in which the type is used. + * @brief Type used to identify a cell, for exemple when inserting a boundary. + * If @ref PersistenceMatrixOptions::is_z2 is true, the type is an @ref IDIdx and corresponds to the row index of the + * cell (the cell value is assumed to be 1). If @ref PersistenceMatrixOptions::is_z2 is false, the type is a pair + * whose first element is the row index of the cell and the second element is the value of the cell (which again is + * assumed to be non-zero). The column index of the row is always deduced from the context in which the type is used. */ using cell_rep_type = typename std::conditional >, Dummy_dimension_holder >::type; - //Extra information needed for a column when the matrix is a chain matrix. + //Extra information needed for a column when the matrix is a @ref chainmatrix "chain matrix". using Chain_column_option = typename std::conditional >, @@ -337,9 +361,9 @@ class Matrix { using Intrusive_set_column_type = Intrusive_set_column, Cell_constructor>; /** - * @brief Type of the columns stored in the matrix. The type depends on the value of @ref column_type defined - * in the given options. See @ref Column_types for a more detailed description. All columns follow the - * @ref PersistenceMatrixColumn concept. + * @brief Type of the columns stored in the matrix. The type depends on the value of + * @ref PersistenceMatrixOptions::column_type defined in the given options. See @ref Column_types for a more detailed + * description. All columns follow the @ref PersistenceMatrixColumn concept. */ using Column_type = typename std::conditional< PersistenceMatrixOptions::column_type == Column_types::HEAP, @@ -379,8 +403,8 @@ class Matrix { static const bool hasFixedBarcode = Option_list::is_of_boundary_type && !PersistenceMatrixOptions::has_vine_update; /** - * @brief Type of the computed barcode. If @ref has_map_column_container is true, it is a list of @ref Bar, - * otherwise it is a vector of @ref Bar. + * @brief Type of the computed barcode. It is either a list of @ref Matrix::Bar or a vector of @ref Matrix::Bar, + * depending if bars need to be removed from the container as some point or not. */ using barcode_type = typename std::conditional > >::type; - //i.e. is simple boundary matrix. Also, only needed because of the reduction algorithm. + //i.e. is simple @ref boundarymatrix "boundary matrix". Also, only needed because of the reduction algorithm. //TODO: remove the necessity and recalculate when needed or keep it like that? static const bool maxDimensionIsNeeded = PersistenceMatrixOptions::has_column_pairings && PersistenceMatrixOptions::is_of_boundary_type && @@ -481,7 +505,7 @@ class Matrix { >::type; /** - * @brief Type of a representative cycle. Vector of row indices, see [TODO: index paragraph]. + * @brief Type of a representative cycle. Vector of @ref rowindex "row indices". */ using cycle_type = std::vector; //TODO: add coefficients @@ -499,8 +523,8 @@ class Matrix { const Row_type, Row_type >::type; - //If the matrix is a chain matrix, the insertion method returns the pivots of its unpaired columns used to reduce - //the inserted boundary. Otherwise, void. + //If the matrix is a chain matrix, the insertion method returns the pivots of its unpaired columns used to reduce the + //inserted boundary. Otherwise, void. using insertion_return_type = typename std::conditional Matrix(const std::vector& columns, characteristic_type characteristic = 11); /** * @brief Constructs a new empty matrix and reserves space for the given number of columns. - * + * * @param numberOfColumns Number of columns to reserve space for. - * @param characteristic Characteristic of the coefficient field. If not specified and @ref is_z2 is false, - * the characteristic has to be set later with the use of `set_characteristic()` before calling for the first time - * a method needing it. Ignored if @ref is_z2 is true. + * @param characteristic Characteristic of the coefficient field. If not specified and + * @ref PersistenceMatrixOptions::is_z2 is false, the characteristic has to be set later with the use of + * @ref set_characteristic before calling for the first time a method needing it. Ignored if + * @ref PersistenceMatrixOptions::is_z2 is true. */ Matrix(int numberOfColumns, characteristic_type characteristic = 0); /** - * @brief Constructs a new empty matrix with the given comparator functions. Only available when those comparators - * are necessary, i.e., when **all** following options have following values: - * - @ref is_of_boundary_type = false - * - @ref has_vine_update = true - * - @ref has_column_pairings = false - * - * Those comparators are necesseray to distinguish cases in a vine update. When the matrix is of boundary type - * (i.e., a RU decomposition) or if the column pairing is activated (i.e., the barcode is stored), the comparators - * can be easily deduced without overhead. If neither are true, we assume that one has additional information - * outside of the matrix about the barcode to provide a better suited comparator adapted to the situation - * (as in the implementation of the Zigzag algorithm for example TODO: ref to zigzag module.) - * + * @brief Constructs a new empty matrix with the given comparator functions. Only available when those comparators + * are necessary. + * + * That is, when **all** following options have following values: + * - @ref PersistenceMatrixOptions::is_of_boundary_type = false + * - @ref PersistenceMatrixOptions::has_vine_update = true + * - @ref PersistenceMatrixOptions::has_column_pairings = false + * + * Those comparators are necesseray to distinguish cases in a vine update. When the matrix is of + * @ref boundarymatrix "boundary type" or if the column pairing is activated (i.e., the barcode is stored), + * the comparators can be easily deduced without overhead. If neither are true, we assume that one has additional + * information outside of the matrix about the barcode to provide a better suited comparator adapted to the situation + * (as in the implementation of the Zigzag algorithm @cite zigzag for example.) + * * @tparam EventComparatorFunction Type of the birth or death comparator: (@ref pos_index, @ref pos_index) -> bool - * @param birthComparator Method taking two PosIdx indices as parameter and returns true if and only if the first + * @param birthComparator Method taking two @ref PosIdx indices as parameter and returns true if and only if the first * face is associated to a bar with strictly smaller birth than the bar associated to the second one. - * @param deathComparator Method taking two PosIdx indices as parameter and returns true if and only if the first + * @param deathComparator Method taking two @ref PosIdx indices as parameter and returns true if and only if the first * face is associated to a bar with strictly smaller death than the bar associated to the second one. */ template Matrix(EventComparatorFunction&& birthComparator, EventComparatorFunction&& deathComparator); /** - * @brief Constructs a new matrix from the given ranges with the given comparator functions. - * Only available when those comparators are necessary, i.e., when **all** following options have following values: - * - @ref is_of_boundary_type = false - * - @ref has_vine_update = true - * - @ref has_column_pairings = false + * @brief Constructs a new matrix from the given ranges with the given comparator functions. + * Only available when those comparators are necessary. + * + * That is, when **all** following options have following values: + * - @ref PersistenceMatrixOptions::is_of_boundary_type = false + * - @ref PersistenceMatrixOptions::has_vine_update = true + * - @ref PersistenceMatrixOptions::has_column_pairings = false * - * See description of @ref Matrix(const std::vector& columns) for more information about - * @p orderedBoundaries and - * @ref Matrix(EventComparatorFunction&& birthComparator, EventComparatorFunction&& deathComparator) + * See description of @ref Matrix(const std::vector& columns, characteristic_type characteristic) + * for more information about @p orderedBoundaries and + * @ref Matrix(EventComparatorFunction&& birthComparator, EventComparatorFunction&& deathComparator) * for more information about the comparators. - * + * * @tparam EventComparatorFunction Type of the birth or death comparator: (@ref pos_index, @ref pos_index) -> bool - * @tparam Boundary_type Range type for a column. Assumed to have a begin(), end() and size() method. + * @tparam Boundary_type Range type for @ref cell_rep_type ranges. Assumed to have a begin(), end() and size() method. * @param orderedBoundaries Vector of ordered boundaries in filtration order. Indexed continously starting at 0. - * @param birthComparator Method taking two PosIdx indices as parameter and returns true if and only if the first + * @param birthComparator Method taking two @ref PosIdx indices as parameter and returns true if and only if the first * face is associated to a bar with strictly smaller birth than the bar associated to the second one. - * @param deathComparator Method taking two PosIdx indices as parameter and returns true if and only if the first + * @param deathComparator Method taking two @ref PosIdx indices as parameter and returns true if and only if the first * face is associated to a bar with strictly smaller death than the bar associated to the second one. - * @param characteristic Characteristic of the coefficient field. Has to be specified if @ref is_z2 is false. - * Default value is 11. Ignored if @ref is_z2 is true. + * @param characteristic Characteristic of the coefficient field. Has to be specified if + * @ref PersistenceMatrixOptions::is_z2 is false. Default value is 11. + * Ignored if @ref PersistenceMatrixOptions::is_z2 is true. */ template Matrix(const std::vector& orderedBoundaries, @@ -600,24 +631,27 @@ class Matrix { characteristic_type characteristic = 11); /** * @brief Constructs a new empty matrix and reserves space for the given number of columns. - * Only available when those comparators are necessary, i.e., when **all** following options have following values: - * - @ref is_of_boundary_type = false - * - @ref has_vine_update = true - * - @ref has_column_pairings = false + * Only available when those comparators are necessary. + * + * That is, when **all** following options have following values: + * - @ref PersistenceMatrixOptions::is_of_boundary_type = false + * - @ref PersistenceMatrixOptions::has_vine_update = true + * - @ref PersistenceMatrixOptions::has_column_pairings = false * - * See description of - * @ref Matrix(EventComparatorFunction&& birthComparator, EventComparatorFunction&& deathComparator) + * See description of + * @ref Matrix(EventComparatorFunction&& birthComparator, EventComparatorFunction&& deathComparator) * for more information about the comparators. - * + * * @tparam EventComparatorFunction Type of the birth or death comparator: (@ref pos_index, @ref pos_index) -> bool * @param numberOfColumns Number of columns to reserve space for. - * @param birthComparator Method taking two PosIdx indices as parameter and returns true if and only if the first + * @param birthComparator Method taking two @ref PosIdx indices as parameter and returns true if and only if the first * face is associated to a bar with strictly smaller birth than the bar associated to the second one. - * @param deathComparator Method taking two PosIdx indices as parameter and returns true if and only if the first + * @param deathComparator Method taking two @ref PosIdx indices as parameter and returns true if and only if the first * face is associated to a bar with strictly smaller death than the bar associated to the second one. - * @param characteristic Characteristic of the coefficient field. If not specified and @ref is_z2 is false, - * the characteristic has to be set later with the use of `set_characteristic()` before calling for the first time - * a method needing it. Ignored if @ref is_z2 is true. + * @param characteristic Characteristic of the coefficient field. If not specified and + * @ref PersistenceMatrixOptions::is_z2 is false, the characteristic has to be set later with the use of + * @ref set_characteristic before calling for the first time a method needing it. + * Ignored if @ref PersistenceMatrixOptions::is_z2 is true. */ template Matrix(unsigned int numberOfColumns, @@ -627,14 +661,14 @@ class Matrix { /** * @brief Copy constructor. * - * @param matrixToCopy Matrix to copy. + * @param matrixToCopy %Matrix to copy. */ Matrix(const Matrix& matrixToCopy); /** * @brief Move constructor. * After the move, the given matrix will be empty. * - * @param other Matrix to move. + * @param other %Matrix to move. */ Matrix(Matrix&& other) noexcept; @@ -644,7 +678,8 @@ class Matrix { // - set_characteristic(characteristic_type min, characteristic_type max) // - readapt reduction? /** - * @brief Sets the characteristic of the coefficient field if @ref is_z2 is false, does nothing otherwise. + * @brief Sets the characteristic of the coefficient field if @ref PersistenceMatrixOptions::is_z2 is false, + * does nothing otherwise. * Should be used if no characteristic could be specified at the creation of the empty matrix. * Do not change the value of the characteristic once used. * @@ -661,7 +696,7 @@ class Matrix { * @brief Inserts a new ordered column at the end of the matrix by copying the given range of @ref cell_rep_type. * The content of the range is assumed to be sorted by increasing ID value. * - * Only available for base matrices, see [TODO: description]. + * Only available for @ref basematrix "base matrices". * Otherwise use @ref insert_boundary which will deduce a new column from the boundary given. * * @tparam Container_type Range of @ref cell_rep_type. Assumed to have a begin(), end() and size() method. @@ -674,226 +709,241 @@ class Matrix { * There should not be any other column inserted at that index which was not explicitely removed before. * The content of the range is assumed to be sorted by increasing ID value. * - * Only available for base matrices without column compression and without row access, see [TODO: description and Options]. + * Only available for @ref basematrix "base matrices" without column compression and without row access. * * @tparam Container_type Range of @ref cell_rep_type. Assumed to have a begin(), end() and size() method. * @param column Column to be inserted. - * @param columnIndex MatIdx index to which the column has to be inserted. + * @param columnIndex @ref MatIdx index to which the column has to be inserted. */ template void insert_column(const Container_type& column, index columnIndex); //TODO: for simple boundary matrices, add an index pointing to the first column inserted after the last call of //get_current_barcode to enable several calls to get_current_barcode /** - * @brief Inserts at the end of the matrix a new ordered column corresponding to the given boundary. - * This means that it is assumed that this method is called on boundaries in the order of the filtration. - * It also assumes that the faces in the given boundary are identified by their relative position in the filtration, - * starting at 0. If it is not the case, use the other `insert_boundary` instead by indicating the face ID - * used in the boundaries when the face is inserted. + * @brief Inserts at the end of the matrix a new ordered column corresponding to the given boundary. + * This means that it is assumed that this method is called on boundaries in the order of the filtration. + * It also assumes that the faces in the given boundary are identified by their relative position in the filtration, + * starting at 0. If it is not the case, use the other + * @ref insert_boundary(id_index faceIndex, const Boundary_type& boundary, dimension_type dim) "insert_boundary" + * instead by indicating the face ID used in the boundaries when the face is inserted. * * Different to the constructor, the boundaries do not have to come from a simplicial complex, but also from * a more general cell complex. This includes cubical complexes or Morse complexes for example. * - * The content of the new column will vary depending on the underlying type of the matrix (see [TODO: description]): - * - If it is a basic matrix type, the boundary is copied as it is, i.e., the method is equivalent to - * @ref insert_column. - * - If it is a boundary type matrix and only R is stored, the boundary is also just copied. The column will only be - * reduced later when the barcode is requested in order to apply some optimisations with the additional knowledge. - * Hence, the barcode will also not be updated, so call @ref get_current_barcode only when the matrix is complete. - * - If it is a boundary type matrix and both R and U are stored, the new boundary is stored in its reduced form and - * the barcode, if active, is also updated. - * - If it is a chain type matrix, the new column is of the form - * `IDIdx + linear combination of older column IDIdxs`, where the combination is deduced while reducing the - * given boundary. If the barcode is stored, it will also be updated. - * + * The content of the new column will vary depending on the underlying @ref mp_matrices "type of the matrix": + * - If it is a @ref basematrix "basic matrix" type, the boundary is copied as it is, i.e., the method is equivalent + * to @ref insert_column. + * - If it is a @ref boundarymatrix "boundary type matrix" and only \f$ R \f$ is stored, the boundary is also just + * copied. The column will only be reduced later when the barcode is requested in order to apply some optimisations + * with the additional knowledge. Hence, the barcode will also not be updated, so call @ref get_current_barcode only + * when the matrix is complete. + * - If it is a @ref boundarymatrix "boundary type matrix" and both \f$ R \f$ and \f$ U \f$ are stored, the new + * boundary is stored in its reduced form and the barcode, if active, is also updated. + * - If it is a @ref chainmatrix "chain type matrix", the new column is of the form `IDIdx + linear combination of + * older column IDIdxs`, where the combination is deduced while reducing the given boundary. If the barcode is stored, + * it will also be updated. + * * @tparam Boundary_type Range of @ref cell_rep_type. Assumed to have a begin(), end() and size() method. * @param boundary Boundary generating the new column. The content should be ordered by ID. - * @param dim Dimension of the face whose boundary is given. If the complex is simplicial, + * @param dim Dimension of the face whose boundary is given. If the complex is simplicial, * this parameter can be omitted as it can be deduced from the size of the boundary. - * @return If it is a chain matrix, the method returns the MatIdx indices of the unpaired chains used to reduce - * the boundary. Otherwise, nothing. + * @return If it is a @ref chainmatrix "chain matrix", the method returns the @ref MatIdx indices of the unpaired + * chains used to reduce the boundary. Otherwise, nothing. */ template insertion_return_type insert_boundary(const Boundary_type& boundary, dimension_type dim = -1); /** - * @brief Only avalaible for non basic matrices. - * It does the same as the other version, but permits the boundary faces to be identified without restrictions + * @brief Only avalaible for @ref mp_matrices "non-basic matrices". + * It does the same as the other version, but allows the boundary faces to be identified without restrictions * except that all IDs have to be strictly increasing in the order of filtration. Note that you should avoid then * to use the other insertion method to avoid overwriting IDs. * * As a face has to be inserted before one of its cofaces in a valid filtration (recall that it is assumed that - * for non basic matrices, the faces are inserted by order of filtration), it is sufficient to indicate the ID - * of the face being inserted. - * + * for @ref mp_matrices "non-basic matrices", the faces are inserted by order of filtration), it is sufficient to + * indicate the ID of the face being inserted. + * * @tparam Boundary_type Range of @ref cell_rep_type. Assumed to have a begin(), end() and size() method. - * @param faceIndex IDIdx index to use to indentify the new face. - * @param boundary Boundary generating the new column. The indices of the boundary have to correspond to the - * @p faceIndex values of precedent calls of the method for the corresponding faces and should be ordered in + * @param faceIndex @ref IDIdx index to use to indentify the new face. + * @param boundary Boundary generating the new column. The indices of the boundary have to correspond to the + * @p faceIndex values of precedent calls of the method for the corresponding faces and should be ordered in * increasing order. - * @param dim Dimension of the face whose boundary is given. If the complex is simplicial, + * @param dim Dimension of the face whose boundary is given. If the complex is simplicial, * this parameter can be omitted as it can be deduced from the size of the boundary. - * @return If it is a chain matrix, the method returns the MatIdx indices of the unpaired chains used to reduce the boundary. - * Otherwise, nothing. + * @return If it is a @ref chainmatrix "chain matrix", the method returns the @ref MatIdx indices of the unpaired + * chains used to reduce the boundary. Otherwise, nothing. */ template insertion_return_type insert_boundary(id_index faceIndex, const Boundary_type& boundary, dimension_type dim = -1); /** - * @brief Returns the column at the given MatIdx index. - * For RU matrices, is equivalent to `get_column(columnIndex, true)`. + * @brief Returns the column at the given @ref MatIdx index. + * For @ref boundarymatrix "RU matrices", is equivalent to + * @ref get_column(index columnIndex, bool inR) "get_column(columnIndex, true)". * The type of the column depends on the choosen options, see @ref PersistenceMatrixOptions::column_type. - * - * @param columnIndex MatIdx index of the column to return. + * + * @param columnIndex @ref MatIdx index of the column to return. * @return Reference to the column. Is `const` if the matrix has column compression. */ returned_column_type& get_column(index columnIndex); /** - * @brief Only available for chain matrices. Returns the column at the given MatIdx index. + * @brief Only available for @ref chainmatrix "chain matrices". Returns the column at the given @ref MatIdx index. * The type of the column depends on the choosen options, see @ref PersistenceMatrixOptions::column_type. * - * @param columnIndex MatIdx index of the column to return. + * @param columnIndex @ref MatIdx index of the column to return. * @return Const reference to the column. */ const Column_type& get_column(index columnIndex) const; //TODO: there is no particular reason that this method is not available for identifier indexing, // just has to be added to the interface... /** - * @brief Only available for RU matrices without @ref Column_indexation_types::IDENTIFIER indexing. - * Returns the column at the given MatIdx index in R if @p inR is true and in U if @p inR is false. - * The type of the column depends on the choosen options, see @ref PersistenceMatrixOptions::column_type. - * - * @param columnIndex MatIdx index of the column to return. - * @param inR If true, returns the column in R, if false, returns the column in U. + * @brief Only available for @ref boundarymatrix "RU matrices" without @ref Column_indexation_types::IDENTIFIER + * indexing. Returns the column at the given @ref MatIdx index in \f$ R \f$ if @p inR is true and in \f$ U \f$ if + * @p inR is false. The type of the column depends on the choosen options, + * see @ref PersistenceMatrixOptions::column_type. + * + * @param columnIndex @ref MatIdx index of the column to return. + * @param inR If true, returns the column in \f$ R \f$, if false, returns the column in \f$ U \f$. * @return Const reference to the column. */ const Column_type& get_column(index columnIndex, bool inR); //TODO: update column indices when reordering rows (after lazy swap) such that always MatIdx are returned. /** - * @brief Only available if @ref has_row_access is true. Returns the row at the given row index, see [TODO: description]. - * For RU matrices, is equivalent to `get_row(columnIndex, true)`. - * The type of the row depends on the choosen options, see @ref PersistenceMatrixOptions::has_intrusive_rows. - * - * @param rowIndex Row index of the row to return: IDIdx for chain matrices or updated IDIdx for boundary matrices - * if swaps occured, see [TODO: description]. + * @brief Only available if @ref PersistenceMatrixOptions::has_row_access is true. Returns the row at the given + * @ref rowindex "row index". For @ref boundarymatrix "RU matrices", is equivalent to + * @ref get_row(id_index rowIndex, bool inR) "get_row(columnIndex, true)". The type of the row depends on the + * choosen options, see @ref PersistenceMatrixOptions::has_intrusive_rows. + * + * @param rowIndex @ref rowindex "Row index" of the row to return: @ref IDIdx for @ref chainmatrix "chain matrices" or + * updated @ref IDIdx for @ref boundarymatrix "boundary matrices" if swaps occured. * @return Reference to the row. Is `const` if the matrix has column compression. */ returned_row_type& get_row(id_index rowIndex); /** - * @brief Only available for chain matrices and matrices with column compression. - * Returns the row at the given row index, see [TODO: description]. + * @brief Only available for @ref chainmatrix "chain matrices" and matrices with column compression. + * Returns the row at the given @ref rowindex "row index". * The type of the row depends on the choosen options, see @ref PersistenceMatrixOptions::has_intrusive_rows. * - * @param rowIndex Row index of the row to return: IDIdx for chain matrices or updated IDIdx for boundary matrices - * if swaps occured, see [TODO: description]. + * @param rowIndex @ref rowindex "Row index" of the row to return: @ref IDIdx for @ref chainmatrix "chain matrices" + * or updated @ref IDIdx for @ref boundarymatrix "boundary matrices" if swaps occured. * @return Const reference to the row. */ const Row_type& get_row(id_index rowIndex) const; //TODO: there is no particular reason that this method is not available for identifier indexing, // just has to be added to the interface... /** - * @brief Only available for RU matrices without @ref Column_indexation_types::IDENTIFIER indexing. - * Returns the row at the given row index (see [TODO: description]) in R if @p inR is true and in U if @p inR is false. - * The type of the row depends on the choosen options, see @ref PersistenceMatrixOptions::has_intrusive_rows. - * - * @param rowIndex Row index of the row to return: updated IDIdx if swaps occured, see [TODO: description]. - * @param inR If true, returns the row in R, if false, returns the row in U. + * @brief Only available for @ref boundarymatrix "RU matrices" without @ref Column_indexation_types::IDENTIFIER + * indexing. Returns the row at the given @ref rowindex "row index" in \f$ R \f$ if @p inR is true and in \f$ U \f$ if + * @p inR is false. The type of the row depends on the choosen options, see + * @ref PersistenceMatrixOptions::has_intrusive_rows. + * + * @param rowIndex @ref rowindex "Row index" of the row to return: updated @ref IDIdx if swaps occured. + * @param inR If true, returns the row in \f$ R \f$, if false, returns the row in \f$ U \f$. * @return Const reference to the row. */ const Row_type& get_row(id_index rowIndex, bool inR); /** - * @brief Only available for base matrices without column compression and if @ref has_map_column_container is true. - * Otherwise, see @ref remove_last. - * Erases the given column from the matrix. - * If @ref has_row_access is also true, the deleted column cells are also automatically removed from their - * respective rows. - * - * @param columnIndex MatIdx index of the column to remove. + * @brief Only available for @ref basematrix "base matrices" without column compression and if + * @ref PersistenceMatrixOptions::has_map_column_container is true. Otherwise, see @ref remove_last. Erases the given + * column from the matrix. If @ref PersistenceMatrixOptions::has_row_access is also true, the deleted column cells are + * also automatically removed from their respective rows. + * + * @param columnIndex @ref MatIdx index of the column to remove. */ void remove_column(index columnIndex); //TODO: rename method to be less confusing. /** * @brief The effect varies depending on the matrices and the options: - * - Base matrix and boundary matrix: - * - @ref has_map_column_container and @ref has_column_and_row_swaps are true: - * cleans up maps used for the lazy row swaps. - * - @ref has_row_access and @ref has_removable_rows are true: assumes that the row is empty and removes it. + * - @ref basematrix "base matrix" and @ref boundarymatrix "boundary matrix": + * - @ref PersistenceMatrixOptions::has_map_column_container and @ref + * PersistenceMatrixOptions::has_column_and_row_swaps are true: cleans up maps used for the lazy row swaps. + * - @ref PersistenceMatrixOptions::has_row_access and @ref PersistenceMatrixOptions::has_removable_rows are true: + * assumes that the row is empty and removes it. * - Otherwise, does nothing. - * - Boundary matrix with U stored: only R is affected by the above. If properly used, U will never have empty rows. - * - Chain matrix: only available if @ref has_row_access and @ref has_removable_rows are true. - * Assumes that the row is empty and removes it. + * - @ref boundarymatrix "boundary matrix" with \f$ U \f$ stored: only \f$ R \f$ is affected by the above. If properly + * used, \f$ U \f$ will never have empty rows. + * - @ref chainmatrix "chain matrix": only available if @ref PersistenceMatrixOptions::has_row_access and + * @ref PersistenceMatrixOptions::has_removable_rows are true. Assumes that the row is empty and removes it. * * @warning The removed rows are always assumed to be empty. If it is not the case, the deleted row cells are not - * removed from their columns. And in the case of intrusive rows, this will generate a segmentation fault when + * removed from their columns. And in the case of intrusive rows, this will generate a segmentation fault when * the column cells are destroyed later. The row access is just meant as a "read only" access to the rows and the - * `erase_row` method just as a way to specify that a row is empty and can therefore be removed from dictionnaries. - * This allows to avoid testing the emptiness of a row at each column cell removal, what can be quite frequent. - * - * @param rowIndex Row index of the empty row to remove, see [TODO: description]. + * @ref erase_row method just as a way to specify that a row is empty and can therefore be removed from dictionnaries. + * This allows to avoid testing the emptiness of a row at each column cell removal, what can be quite frequent. + * + * @param rowIndex @ref rowindex "Row index" of the empty row to remove. */ void erase_row(id_index rowIndex); //TODO: for chain matrices, replace IDIdx input with MatIdx input to homogenise. /** - * @brief Only available for RU and chain matrices and if @ref has_removable_columns and @ref has_vine_update are true. - * For chain matrices, @ref has_map_column_container and @ref has_column_pairings also need to be true. - * Assumes that the face is maximal in the current complex and removes it such that the matrix remains consistent - * (i.e., RU is still an upper triangular decomposition of the boundary matrix and chain is still a compatible - * bases of the chain complex in the sense of @cite [TODO: zigzag paper]). - * The maximality of the face is not verified. - * Also updates the barcode if it was computed. + * @brief Only available for @ref boundarymatrix "RU" and @ref chainmatrix "chain matrices" and if + * @ref PersistenceMatrixOptions::has_removable_columns and @ref PersistenceMatrixOptions::has_vine_update are true. + * For @ref chainmatrix "chain matrices", @ref PersistenceMatrixOptions::has_map_column_container and + * @ref PersistenceMatrixOptions::has_column_pairings also need to be true. Assumes that the face is maximal in the + * current complex and removes it such that the matrix remains consistent (i.e., RU is still an upper triangular + * decomposition of the boundary matrix and chain is still a compatible bases of the chain complex in the sense + * of @cite zigzag). The maximality of the face is not verified. Also updates the barcode if it was computed. * - * For chain matrices, using the other version of the method could perform better depending on how the data is - * maintained on the side of the user. Then, @ref has_column_pairings also do not need to be true. + * For @ref chainmatrix "chain matrices", using the other version of the method could perform better depending on how + * the data is maintained on the side of the user. Then, @ref PersistenceMatrixOptions::has_column_pairings also do + * not need to be true. * * See also @ref remove_last and @ref remove_column. - * - * @param columnIndex If boundary matrix, MatIdx index of the face to remove, otherwise the IDIdx index. + * + * @param columnIndex If @ref boundarymatrix "boundary matrix", @ref MatIdx index of the face to remove, otherwise the + * @ref IDIdx index. */ void remove_maximal_face(index columnIndex); //TODO: See if it would be better to use something more general than a vector for columnsToSwap, such that // the user do not have to construct the vector from scratch. Like passing iterators instead. But it would be nice, // to still be able to do (face, {})... /** - * @brief Only available for chain matrices and if @ref has_removable_columns, @ref has_vine_update - * and @ref has_map_column_container are true. - * Assumes that the face is maximal in the current complex and removes it such that the matrix remains consistent - * (i.e., it is still a compatible bases of the chain complex in the sense of @cite [TODO: zigzag paper]). - * The maximality of the face is not verified. - * Also updates the barcode if it was computed. - * - * To maintain the compatibility, vine swaps are done to move the face up to the end of the filtration. Once at - * the end, the removal is trivial. But for chain matrices, swaps do not actually swap the position of the column - * every time, so the faces appearing after @p faceIndex in the filtration have to be searched first within the matrix. - * If the user has an easy access to the IDIdx of the faces in the order of filtration, passing them by argument with - * @p columnsToSwap allows to skip a linear search process. Typically, if the user knows that the face he wants to - * remove is already the last face of the filtration, calling `remove_maximal_face(faceIndex, {})` will be faster - * than `remove_last()`. + * @brief Only available for @ref chainmatrix "chain matrices" and if + * @ref PersistenceMatrixOptions::has_removable_columns, @ref PersistenceMatrixOptions::has_vine_update and + * @ref PersistenceMatrixOptions::has_map_column_container are true. Assumes that the face is maximal in the current + * complex and removes it such that the matrix remains consistent (i.e., it is still a compatible bases of the chain + * complex in the sense of @cite zigzag). The maximality of the face is not verified. Also updates the barcode if it + * was computed. + * + * To maintain the compatibility, vine swaps are done to move the face up to the end of the filtration. Once at the + * end, the removal is trivial. But for @ref chainmatrix "chain matrices", swaps do not actually swap the position of + * the column every time, so the faces appearing after @p faceIndex in the filtration have to be searched first within + * the matrix. If the user has an easy access to the @ref IDIdx of the faces in the order of filtration, passing them + * by argument with @p columnsToSwap allows to skip a linear search process. Typically, if the user knows that the + * face he wants to remove is already the last face of the filtration, calling + * @ref remove_maximal_face(id_index faceIndex, const std::vector& columnsToSwap) + * "remove_maximal_face(faceID, {})" will be faster than @ref remove_last(). * * See also @ref remove_last. - * - * @param faceIndex IDIdx index of the face to remove - * @param columnsToSwap Vector of IDIdx indices of the faces coming after @p faceIndex in the filtration. + * + * @param faceIndex @ref IDIdx index of the face to remove + * @param columnsToSwap Vector of @ref IDIdx indices of the faces coming after @p faceIndex in the filtration. */ void remove_maximal_face(id_index faceIndex, const std::vector& columnsToSwap); /** * @brief Removes the last inserted column/face from the matrix. - * If the matrix is non basic, @ref has_removable_columns has to be true for the method to be available. - * Additionnaly, if the matrix is a chain matrix, either @ref has_map_column_container has to be true or - * @ref has_vine_update has to be false. And if the matrix is a base matrix it should be without column compression. + * If the matrix is @ref mp_matrices "non basic", @ref PersistenceMatrixOptions::has_removable_columns has to be true + * for the method to be available. Additionnaly, if the matrix is a @ref chainmatrix "chain matrix", either + * @ref PersistenceMatrixOptions::has_map_column_container has to be true or + * @ref PersistenceMatrixOptions::has_vine_update has to be false. And if the matrix is a + * @ref basematrix "base matrix" it should be without column compression. * * See also @ref remove_maximal_face and @ref remove_column. * - * For chain matrices, if @ref has_vine_update is true, the last face does not have to be at the end of the matrix - * and therefore has to be searched first. In this case, if the user already knows the IDIdx of the last face, - * calling `remove_maximal_face(faceID, {})` instead allows to skip the search. + * For @ref chainmatrix "chain matrices", if @ref PersistenceMatrixOptions::has_vine_update is true, the last face + * does not have to be at the end of the matrix and therefore has to be searched first. In this case, if the user + * already knows the @ref IDIdx of the last face, calling + * @ref remove_maximal_face(id_index faceIndex, const std::vector& columnsToSwap) + * "remove_maximal_face(faceID, {})" instead allows to skip the search. */ void remove_last(); /** - * @brief Returns the maximal dimension of a face stored in the matrix. Only available for non basic matrices and - * if @ref has_matrix_maximal_dimension_access is true. - * + * @brief Returns the maximal dimension of a face stored in the matrix. Only available for + * @ref mp_matrices "non-basic matrices" and if @ref PersistenceMatrixOptions::has_matrix_maximal_dimension_access + * is true. + * * @return The maximal dimension. */ dimension_type get_max_dimension() const; @@ -904,75 +954,76 @@ class Matrix { */ index get_number_of_columns() const; /** - * @brief Returns the dimension of the given face. Only available for non basic matrices. + * @brief Returns the dimension of the given face. Only available for @ref mp_matrices "non-basic matrices". * - * @param columnIndex MatIdx index of the column representing the face. + * @param columnIndex @ref MatIdx index of the column representing the face. * @return Dimension of the face. */ dimension_type get_column_dimension(index columnIndex) const; /** * @brief Adds column at @p sourceColumnIndex onto the column at @p targetColumnIndex in the matrix. Is available - * for every matrix type, but should be used with care with non basic matrices, as they will be no verification - * to ensure that the addition makes sense for the meaning of the underlying object. For example, a right-to-left - * addition could corrupt the computation of the barcode or the representative cycles if done blindly. + * for every matrix type, but should be used with care with @ref mp_matrices "non-basic matrices", as they will be + * no verification to ensure that the addition makes sense for the meaning of the underlying object. For example, + * a right-to-left addition could corrupt the computation of the barcode or the representative cycles if done blindly. * - * For basic matrices with column compression, the representatives are summed together, which means that - * all column compressed together with the target column are affected by the change, not only the target. + * For @ref basematrix "basic matrices" with column compression, the representatives are summed together, which means + * that all column compressed together with the target column are affected by the change, not only the target. * * @tparam Index_type Any signed or unsigned integer type. - * @param sourceColumnIndex MatIdx index of the column to add. - * @param targetColumnIndex MatIdx index of the target column. + * @param sourceColumnIndex @ref MatIdx index of the column to add. + * @param targetColumnIndex @ref MatIdx index of the target column. */ template std::enable_if_t > add_to(Index_type sourceColumnIndex, Index_type targetColumnIndex); /** * @brief Adds the given range of @ref Cell onto the column at @p targetColumnIndex in the matrix. Only available - * for basic matrices. + * for @ref basematrix "basic matrices". * - * For basic matrices with column compression, the range is summed onto the representative, which means that - * all column compressed together with the target column are affected by the change, not only the target. + * For @ref basematrix "basic matrices" with column compression, the range is summed onto the representative, which + * means that all column compressed together with the target column are affected by the change, not only the target. * * @tparam Cell_range Range of @ref Cell. Needs a begin() and end() method. A column index does not need to be - * stored in the cells, even if @ref has_row_access is true. - * @param sourceColumn Source cell range. - * @param targetColumnIndex MatIdx index of the target column. + * stored in the cells, even if @ref PersistenceMatrixOptions::has_row_access is true. + * @param sourceColumn Source @ref Cell range. + * @param targetColumnIndex @ref MatIdx index of the target column. */ template std::enable_if_t > add_to(const Cell_range& sourceColumn, index targetColumnIndex); /** - * @brief Multiplies the target column with the coefficiant and then adds the source column to it. - * That is: targetColumn = (targetColumn * coefficient) + sourceColumn. - * Is available for every matrix type, but should be used with care with non basic matrices, as they will be no - * verification to ensure that the addition makes sense for the meaning of the underlying object. + * @brief Multiplies the target column with the coefficient and then adds the source column to it. + * That is: `targetColumn = (targetColumn * coefficient) + sourceColumn`. + * Is available for every matrix type, but should be used with care with @ref mp_matrices "non-basic matrices", + * as they will be no verification to ensure that the addition makes sense for the meaning of the underlying object. * For example, a right-to-left addition could corrupt the computation of the barcode or the representative cycles * if done blindly. * - * For basic matrices with column compression, the representatives are summed together, which means that - * all column compressed together with the target column are affected by the change, not only the target. + * For @ref basematrix "basic matrices" with column compression, the representatives are summed together, which means + * that all column compressed together with the target column are affected by the change, not only the target. * * @tparam Index_type Any signed or unsigned integer type. - * @param sourceColumnIndex MatIdx index of the column to add. + * @param sourceColumnIndex @ref MatIdx index of the column to add. * @param coefficient Value to multiply. - * @param targetColumnIndex MatIdx index of the target column. + * @param targetColumnIndex @ref MatIdx index of the target column. */ template std::enable_if_t > multiply_target_and_add_to(Index_type sourceColumnIndex, int coefficient, Index_type targetColumnIndex); /** - * @brief Multiplies the target column with the coefficiant and then adds the given range of @ref Cell to it. - * That is: targetColumn = (targetColumn * coefficient) + sourceColumn. Only available for basic matrices. + * @brief Multiplies the target column with the coefficient and then adds the given range of @ref Cell to it. + * That is: `targetColumn = (targetColumn * coefficient) + sourceColumn`. Only available for + * @ref basematrix "basic matrices". * - * For basic matrices with column compression, the range is summed onto the representative, which means that - * all column compressed together with the target column are affected by the change, not only the target. + * For @ref basematrix "basic matrices" with column compression, the range is summed onto the representative, which + * means that all column compressed together with the target column are affected by the change, not only the target. * * @tparam Cell_range Range of @ref Cell. Needs a begin() and end() method. A column index does not need to be - * stored in the cells, even if @ref has_row_access is true. - * @param sourceColumn Source cell range. + * stored in the cells, even if @ref PersistenceMatrixOptions::has_row_access is true. + * @param sourceColumn Source @ref Cell range. * @param coefficient Value to multiply. - * @param targetColumnIndex MatIdx index of the target column. + * @param targetColumnIndex @ref MatIdx index of the target column. */ template std::enable_if_t > multiply_target_and_add_to(const Cell_range& sourceColumn, @@ -980,38 +1031,38 @@ class Matrix { index targetColumnIndex); /** - * @brief Multiplies the source column with the coefficiant before adding it to the target column. - * That is: targetColumn += (coefficient * sourceColumn). The source column will **not** be modified. - * Is available for every matrix type, but should be used with care with non basic matrices, as they will be no - * verification to ensure that the addition makes sense for the meaning of the underlying object. + * @brief Multiplies the source column with the coefficient before adding it to the target column. + * That is: `targetColumn += (coefficient * sourceColumn)`. The source column will **not** be modified. + * Is available for every matrix type, but should be used with care with @ref mp_matrices "non-basic matrices", as + * they will be no verification to ensure that the addition makes sense for the meaning of the underlying object. * For example, a right-to-left addition could corrupt the computation of the barcode or the representative cycles * if done blindly. * - * For basic matrices with column compression, the representatives are summed together, which means that - * all column compressed together with the target column are affected by the change, not only the target. + * For @ref basematrix "basic matrices" with column compression, the representatives are summed together, which means + * that all column compressed together with the target column are affected by the change, not only the target. * * @tparam Index_type Any signed or unsigned integer type. * @param coefficient Value to multiply. - * @param sourceColumnIndex MatIdx index of the column to add. - * @param targetColumnIndex MatIdx index of the target column. + * @param sourceColumnIndex @ref MatIdx index of the column to add. + * @param targetColumnIndex @ref MatIdx index of the target column. */ template std::enable_if_t > multiply_source_and_add_to(int coefficient, Index_type sourceColumnIndex, Index_type targetColumnIndex); /** - * @brief Multiplies the source column with the coefficiant before adding it to the target column. - * That is: targetColumn += (coefficient * sourceColumn). The source column will **not** be modified. - * Only available for basic matrices. + * @brief Multiplies the source column with the coefficient before adding it to the target column. + * That is: `targetColumn += (coefficient * sourceColumn)`. The source column will **not** be modified. + * Only available for @ref basematrix "basic matrices". * - * For basic matrices with column compression, the range is summed onto the representative, which means that - * all column compressed together with the target column are affected by the change, not only the target. + * For @ref basematrix "basic matrices" with column compression, the range is summed onto the representative, which + * means that all column compressed together with the target column are affected by the change, not only the target. * * @tparam Cell_range Range of @ref Cell. Needs a begin() and end() method. A column index does not need to be - * stored in the cells, even if @ref has_row_access is true. + * stored in the cells, even if @ref PersistenceMatrixOptions::has_row_access is true. * @param coefficient Value to multiply. - * @param sourceColumn Source cell range. - * @param targetColumnIndex MatIdx index of the target column. + * @param sourceColumn Source @ref Cell range. + * @param targetColumnIndex @ref MatIdx index of the target column. */ template std::enable_if_t > multiply_source_and_add_to(int coefficient, @@ -1019,63 +1070,69 @@ class Matrix { index targetColumnIndex); /** - * @brief Zeroes the cell at the given coordinates. Not available for chain matrices and for base matrices with - * column compression. In general, should be used with care with non basic matrices to not destroy the validity - * of the persistence related properties of the matrix. + * @brief Zeroes the cell at the given coordinates. Not available for @ref chainmatrix "chain matrices" and for + * @ref basematrix "base matrices" with column compression. In general, should be used with care with + * @ref mp_matrices "non-basic matrices" to not destroy the validity of the persistence related properties of the + * matrix. * - * For RU matrices, equivalent to `zero_cell(columnIndex, rowIndex, true)`. - * - * @param columnIndex MatIdx index of the column of the cell. - * @param rowIndex Row index of the row of the cell. + * For @ref boundarymatrix "RU matrices", equivalent to + * @ref zero_cell(index columnIndex, id_index rowIndex, bool inR) "zero_cell(columnIndex, rowIndex, true)". + * + * @param columnIndex @ref MatIdx index of the column of the cell. + * @param rowIndex @ref rowindex "Row index" of the row of the cell. */ void zero_cell(index columnIndex, id_index rowIndex); /** - * @brief Only available for RU matrices. Zeroes the cell at the given coordinates in R if @p inR is true or in - * U if @p inR is false. Should be used with care to not destroy the validity of the persistence related properties - * of the matrix. - * - * @param columnIndex MatIdx index of the column of the cell. - * @param rowIndex Row index of the row of the cell. - * @param inR Boolean indicating in which matrix to zero: if true in R and if false in U. + * @brief Only available for @ref boundarymatrix "RU matrices". Zeroes the cell at the given coordinates in \f$ R \f$ + * if @p inR is true or in \f$ U \f$ if @p inR is false. Should be used with care to not destroy the validity of the + * persistence related properties of the matrix. + * + * @param columnIndex @ref MatIdx index of the column of the cell. + * @param rowIndex @ref rowindex "Row index" of the row of the cell. + * @param inR Boolean indicating in which matrix to zero: if true in \f$ R \f$ and if false in \f$ U \f$. */ void zero_cell(index columnIndex, id_index rowIndex, bool inR); /** - * @brief Zeroes the column at the given index. Not available for chain matrices and for base matrices with - * column compression. In general, should be used with care with non basic matrices to not destroy the validity - * of the persistence related properties of the matrix. + * @brief Zeroes the column at the given index. Not available for @ref chainmatrix "chain matrices" and for + * @ref basematrix "base matrices" with column compression. In general, should be used with care with + * @ref mp_matrices "non-basic matrices" to not destroy the validity of the persistence related properties of the + * matrix. * - * For RU matrices, equivalent to `zero_column(columnIndex, true)`. - * - * @param columnIndex MatIdx index of the column to zero. + * For @ref boundarymatrix "RU matrices", equivalent to + * @ref zero_column(index columnIndex, bool inR) "zero_column(columnIndex, true)". + * + * @param columnIndex @ref MatIdx index of the column to zero. */ void zero_column(index columnIndex); /** - * @brief Only available for RU matrices. Zeroes the column at the given index in R if @p inR is true or in - * U if @p inR is false. Should be used with care to not destroy the validity of the persistence related properties - * of the matrix. - * - * @param columnIndex MatIdx index of the column to zero. - * @param inR Boolean indicating in which matrix to zero: if true in R and if false in U. + * @brief Only available for @ref boundarymatrix "RU matrices". Zeroes the column at the given index in \f$ R \f$ if + * @p inR is true or in \f$ U \f$ if @p inR is false. Should be used with care to not destroy the validity of the + * persistence related properties of the matrix. + * + * @param columnIndex @ref MatIdx index of the column to zero. + * @param inR Boolean indicating in which matrix to zero: if true in \f$ R \f$ and if false in \f$ U \f$. */ void zero_column(index columnIndex, bool inR); /** * @brief Indicates if the cell at given coordinates has value zero. * - * For RU matrices, equivalent to `is_zero_cell(columnIndex, rowIndex, true)`. - * - * @param columnIndex MatIdx index of the column of the cell. - * @param rowIndex Row index of the row of the cell. + * For @ref boundarymatrix "RU matrices", equivalent to + * @ref is_zero_cell(index columnIndex, id_index rowIndex, bool inR) const + * "is_zero_cell(columnIndex, rowIndex, true)". + * + * @param columnIndex @ref MatIdx index of the column of the cell. + * @param rowIndex @ref rowindex "Row index" of the row of the cell. * @return true If the cell has value zero. * @return false Otherwise. */ bool is_zero_cell(index columnIndex, id_index rowIndex); /** - * @brief Only available for RU matrices. Indicates if the cell at given coordinates has value zero in R if - * @p inR is true or in U if @p inR is false. - * - * @param columnIndex MatIdx index of the column of the cell. - * @param rowIndex Row index of the row of the cell. - * @param inR Boolean indicating in which matrix to look: if true in R and if false in U. + * @brief Only available for @ref boundarymatrix "RU matrices". Indicates if the cell at given coordinates has value + * zero in \f$ R \f$ if @p inR is true or in \f$ U \f$ if @p inR is false. + * + * @param columnIndex @ref MatIdx index of the column of the cell. + * @param rowIndex @ref rowindex "Row index" of the row of the cell. + * @param inR Boolean indicating in which matrix to look: if true in \f$ R \f$ and if false in \f$ U \f$. * @return true If the cell has value zero. * @return false Otherwise. */ @@ -1083,52 +1140,56 @@ class Matrix { /** * @brief Indicates if the column at given index has value zero. * - * For RU matrices, equivalent to `is_zero_column(columnIndex, true)`. + * For @ref boundarymatrix "RU matrices", equivalent to + * @ref is_zero_column(index columnIndex, bool inR) "is_zero_column(columnIndex, true)". * - * Note that for chain matrices, this method should always return false, as a valid chain matrix never has - * empty columns. - * - * @param columnIndex MatIdx index of the column. + * Note that for @ref chainmatrix "chain matrices", this method should always return false, as a valid + * @ref chainmatrix "chain matrix" never has empty columns. + * + * @param columnIndex @ref MatIdx index of the column. * @return true If the column has value zero. * @return false Otherwise. */ bool is_zero_column(index columnIndex); /** - * @brief Only available for RU matrices. Indicates if the column at given index has value zero in R if - * @p inR is true or in U if @p inR is false. + * @brief Only available for @ref boundarymatrix "RU matrices". Indicates if the column at given index has value zero + * in \f$ R \f$ if @p inR is true or in \f$ U \f$ if @p inR is false. * * Note that if @p inR is false, this method should usually return false. * - * @param columnIndex MatIdx index of the column. - * @param inR Boolean indicating in which matrix to look: if true in R and if false in U. + * @param columnIndex @ref MatIdx index of the column. + * @param inR Boolean indicating in which matrix to look: if true in \f$ R \f$ and if false in \f$ U \f$. * @return true If the column has value zero. * @return false Otherwise. */ bool is_zero_column(index columnIndex, bool inR); /** - * @brief Returns the MatIdx index of the column which has the given row index as pivot. Only available for - * RU and chain matrices. Assumes that the pivot exists. For RU matrices, the column is returned from R. + * @brief Returns the @ref MatIdx index of the column which has the given @ref rowindex "row index" as pivot. Only + * available for @ref boundarymatrix "RU" and @ref chainmatrix "chain matrices". Assumes that the pivot exists. For + * @ref boundarymatrix "RU matrices", the column is returned from \f$ R \f$. * - * Recall that the row indices for chain matrices correspond to the IDIdx indices and that the row indices - * for a RU matrix correspond to the updated IDIdx indices which got potentially swapped by a vine swap. - * - * @param faceIndex Row index of the pivot. - * @return MatIdx index of the column with the given pivot. + * Recall that the @ref rowindex "row indices" for @ref chainmatrix "chain matrices" correspond to the @ref IDIdx + * indices and that the @ref rowindex "row indices" for a @ref boundarymatrix "RU matrix" correspond to the updated + * @ref IDIdx indices which got potentially swapped by a vine swap. + * + * @param faceIndex @ref rowindex "Row index" of the pivot. + * @return @ref MatIdx index of the column with the given pivot. */ index get_column_with_pivot(id_index faceIndex) const; /** - * @brief Returns the row index of the pivot of the given column. Only available for non basic matrices. - * - * @param columnIndex MatIdx index of the column - * @return The row index of the pivot. + * @brief Returns the @ref rowindex "row index" of the pivot of the given column. Only available for + * @ref mp_matrices "non-basic matrices". + * + * @param columnIndex @ref MatIdx index of the column + * @return The @ref rowindex "row index" of the pivot. */ id_index get_pivot(index columnIndex); /** * @brief Assign operator. * - * @param other Matrix to copy + * @param other %Matrix to copy * @return Reference to this object. */ Matrix& operator=(Matrix other); @@ -1148,46 +1209,50 @@ class Matrix { //TODO: change the behaviour for boundary matrices. /** - * @brief Returns the current barcode of the matrix. Available only if @ref has_column_pairings is true. + * @brief Returns the current barcode of the matrix. Available only if + * @ref PersistenceMatrixOptions::has_column_pairings is true. * * Recall that we assume that the boundaries were inserted in the order of filtration for the barcode to be valid. * - * @warning For simple boundary matrices (only storing R), we assume that `get_current_barcode` is only called - * once, when the matrix is completed. - * - * @return A reference to the barcode. The barcode is a vector of @ref Bar. A bar stores three informations: - * the PosIdx birth index, the PosIdx death index and the dimension of the bar. + * @warning For simple @ref boundarymatrix "boundary matrices" (only storing \f$ R \f$), we assume that + * @ref get_current_barcode is only called once the matrix is completed and won't be modified again. + * + * @return A reference to the barcode. The barcode is a vector of @ref Matrix::Bar. A bar stores three informations: + * the @ref PosIdx birth index, the @ref PosIdx death index and the dimension of the bar. */ const barcode_type& get_current_barcode(); /** - * @brief Returns the current barcode of the matrix. Available only if @ref has_column_pairings is true. + * @brief Returns the current barcode of the matrix. Available only if + * @ref PersistenceMatrixOptions::has_column_pairings is true. * * Recall that we assume that the boundaries were inserted in the order of filtration for the barcode to be valid. * - * @warning For simple boundary matrices (only storing R), we assume that `get_current_barcode` is only called - * once, when the matrix is completed. - * - * @return A reference to the barcode. The barcode is a vector of @ref Bar. A bar stores three informations: - * the PosIdx birth index, the PosIdx death index and the dimension of the bar. + * @warning For simple @ref boundarymatrix "boundary matrices" (only storing \f$ R \f$), we assume that + * @ref get_current_barcode is only called once the matrix is completed and won't be modified again. + * + * @return A const reference to the barcode. The barcode is a vector of @ref Matrix::Bar. A bar stores three + * informations: the @ref PosIdx birth index, the @ref PosIdx death index and the dimension of the bar. */ const barcode_type& get_current_barcode() const; /** - * @brief Only available for base matrices without column compression and simple boundary matrices (only storing R) - * and if @ref has_column_and_row_swaps is true. - * Swaps the two given columns. Note for boundary matrices, that it really just swaps two columns and do not updates - * anything else, nor performs additions to maintain some properties on the matrix. - * - * @param columnIndex1 First column MatIdx index to swap. - * @param columnIndex2 Second column MatIdx index to swap. + * @brief Only available for @ref basematrix "base matrices" without column compression and simple + * @ref boundarymatrix "boundary matrices" (only storing \f$ R \f$) and if + * @ref PersistenceMatrixOptions::has_column_and_row_swaps is true. Swaps the two given columns. Note for + * @ref boundarymatrix "boundary matrices", that it really just swaps two columns and does not update anything else, + * nor performs additions to maintain some properties on the matrix. + * + * @param columnIndex1 First column @ref MatIdx index to swap. + * @param columnIndex2 Second column @ref MatIdx index to swap. */ void swap_columns(index columnIndex1, index columnIndex2); /** - * @brief Only available for base matrices without column compression and simple boundary matrices (only storing R) - * and if @ref has_column_and_row_swaps is true. - * Swaps the two given rows. Note for boundary matrices, that it really just swaps two rows and do not updates - * anything else, nor performs additions to maintain some properties on the matrix. - * + * @brief Only available for @ref basematrix "base matrices" without column compression and simple + * @ref boundarymatrix "boundary matrices" (only storing \f$ R \f$) and if + * @ref PersistenceMatrixOptions::has_column_and_row_swaps is true. Swaps the two given rows. Note for + * @ref boundarymatrix "boundary matrices", that it really just swaps two rows and does not update anything else, + * nor performs additions to maintain some properties on the matrix. + * * @param rowIndex1 First row index to swap. * @param rowIndex2 Second row index to swap. */ @@ -1195,80 +1260,84 @@ class Matrix { //TODO: find better name. And benchmark also to verify if it is really worth it to have this extra version in addition //to vine_swap. /** - * @brief Only available if @ref has_vine_update is true and if it is either a bounary matrix or - * @ref column_indexation_type is set to @ref Column_indexation_types::POSITION. - * Does the same than @ref vine_swap, but assumes that the swap is non trivial and - * therefore skips a part of the case study. - * - * @param index PosIdx index of the first face to swap. The second one has to be at (@p index + 1). Recall that - * for boundary matrices, PosIdx == MatIdx. + * @brief Only available if @ref PersistenceMatrixOptions::has_vine_update is true and if it is either a bounary + * matrix or @ref PersistenceMatrixOptions::column_indexation_type is set to @ref Column_indexation_types::POSITION. + * Does the same than @ref vine_swap, but assumes that the swap is non trivial and therefore skips a part of the case + * study. + * + * @param index @ref PosIdx index of the first face to swap. The second one has to be at `index + 1`. Recall that for + * @ref boundarymatrix "boundary matrices", @ref PosIdx == @ref MatIdx. * @return true If the barcode changed from the swap. * @return false Otherwise. */ bool vine_swap_with_z_eq_1_case(pos_index index); /** - * @brief Only available if @ref has_vine_update is true and if it is either a chain matrix or - * @ref column_indexation_type is set to @ref Column_indexation_types::IDENTIFIER. - * Does the same than @ref vine_swap, but assumes that the swap is non trivial and - * therefore skips a part of the case study. - * - * @param columnIndex1 MatIdx index of the first face. - * @param columnIndex2 MatIdx index of the second face. It is assumed that the PosIdx of both only differs by one. - * @return Let pos1 be the PosIdx index of @p columnIndex1 and pos2 be the PosIdx index of @p columnIndex2. - * The method returns the MatIdx of the column which has now, after the swap, the PosIdx max(pos1, pos2). + * @brief Only available if @ref PersistenceMatrixOptions::has_vine_update is true and if it is either a + * @ref chainmatrix "chain matrix" or @ref PersistenceMatrixOptions::column_indexation_type is set to + * @ref Column_indexation_types::IDENTIFIER. Does the same than @ref vine_swap, but assumes that the swap is + * non-trivial and therefore skips a part of the case study. + * + * @param columnIndex1 @ref MatIdx index of the first face. + * @param columnIndex2 @ref MatIdx index of the second face. It is assumed that the @ref PosIdx of both only differs + * by one. + * @return Let \f$ pos1 \f$ be the @ref PosIdx index of @p columnIndex1 and \f$ pos2 \f$ be the @ref PosIdx index of + * @p columnIndex2. The method returns the @ref MatIdx of the column which has now, after the swap, the @ref PosIdx + * \f$ max(pos1, pos2) \f$. */ index vine_swap_with_z_eq_1_case(index columnIndex1, index columnIndex2); /** - * @brief Only available if @ref has_vine_update is true and if it is either a bounary matrix or - * @ref column_indexation_type is set to @ref Column_indexation_types::POSITION. - * Does a vine swap between two faces which are consecutives in the filtration. Roughly, if \f$ F \f$ is the current - * filtration represented by the matrix, the method modifies the matrix such that the new state corresponds to - * a valid state for the filtration \f$ F' \f$ equal to \f$ F \f$ but with the two faces at position @p index - * and @p index + 1 swapped. Of course, the two faces should not have a face/coface relation which each other ; - * \f$ F' \f$ has to be a valid filtration. - * See @cite [TODO: vineyard paper] for more information about vine and vineyards. - * - * @param index PosIdx index of the first face to swap. The second one has to be at (@p index + 1). Recall that - * for boundary matrices, PosIdx == MatIdx. + * @brief Only available if @ref PersistenceMatrixOptions::has_vine_update is true and if it is either a + * @ref boundarymatrix "boundary matrix" or @ref PersistenceMatrixOptions::column_indexation_type is set to + * @ref Column_indexation_types::POSITION. Does a vine swap between two faces which are consecutives in the + * filtration. Roughly, if \f$ F \f$ is the current filtration represented by the matrix, the method modifies the + * matrix such that the new state corresponds to a valid state for the filtration \f$ F' \f$ equal to \f$ F \f$ but + * with the two faces at position `index` and `index + 1` swapped. Of course, the two faces should not have a + * face/coface relation which each other ; \f$ F' \f$ has to be a valid filtration. + * See @cite vineyards for more information about vine and vineyards. + * + * @param index @ref PosIdx index of the first face to swap. The second one has to be at `index + 1`. Recall that for + * @ref boundarymatrix "boundary matrices", @ref PosIdx == @ref MatIdx. * @return true If the barcode changed from the swap. * @return false Otherwise. */ bool vine_swap(pos_index index); /** - * @brief Only available if @ref has_vine_update is true and if it is either a chain matrix or - * @ref column_indexation_type is set to @ref Column_indexation_types::IDENTIFIER. - * Does a vine swap between two faces which are consecutives in the filtration. Roughly, if \f$ F \f$ is - * the current filtration represented by the matrix, the method modifies the matrix such that the new state - * corresponds to a valid state for the filtration \f$ F' \f$ equal to \f$ F \f$ but with the two given faces - * at swapped positions. Of course, the two faces should not have a face/coface relation which each other ; - * \f$ F' \f$ has to be a valid filtration. - * See @cite [TODO: vineyard paper] for more information about vine and vineyards. - * - * @param columnIndex1 MatIdx index of the first face. - * @param columnIndex2 MatIdx index of the second face. It is assumed that the PosIdx of both only differs by one. - * @return Let pos1 be the PosIdx index of @p columnIndex1 and pos2 be the PosIdx index of @p columnIndex2. - * The method returns the MatIdx of the column which has now, after the swap, the PosIdx max(pos1, pos2). + * @brief Only available if @ref PersistenceMatrixOptions::has_vine_update is true and if it is either a + * @ref chainmatrix "chain matrix" or @ref PersistenceMatrixOptions::column_indexation_type is set to + * @ref Column_indexation_types::IDENTIFIER. Does a vine swap between two faces which are consecutives in the + * filtration. Roughly, if \f$ F \f$ is the current filtration represented by the matrix, the method modifies the + * matrix such that the new state corresponds to a valid state for the filtration \f$ F' \f$ equal to \f$ F \f$ but + * with the two given faces at swapped positions. Of course, the two faces should not have a face/coface relation + * which each other ; \f$ F' \f$ has to be a valid filtration. + * See @cite vineyards for more information about vine and vineyards. + * + * @param columnIndex1 @ref MatIdx index of the first face. + * @param columnIndex2 @ref MatIdx index of the second face. It is assumed that the @ref PosIdx of both only differs + * by one. + * @return Let \f$ pos1 \f$ be the @ref PosIdx index of @p columnIndex1 and \f$ pos2 \f$ be the @ref PosIdx index of + * @p columnIndex2. The method returns the @ref MatIdx of the column which has now, after the swap, the @ref PosIdx + * \f$ max(pos1, pos2) \f$. */ index vine_swap(index columnIndex1, index columnIndex2); //TODO: Rethink the interface for representative cycles /** - * @brief Only available if @ref can_retrieve_representative_cycles is true. Precomputes the representative cycles - * of the current state of the filtration represented by the matrix. - * It does not need to be called before `get_representative_cycles` is called for the first time, but needs to be - * called before calling `get_representative_cycles` again if the matrix was modified in between. Otherwise the - * old cycles will be returned. + * @brief Only available if @ref PersistenceMatrixOptions::can_retrieve_representative_cycles is true. Precomputes the + * representative cycles of the current state of the filtration represented by the matrix. It does not need to be + * called before @ref get_representative_cycles is called for the first time, but needs to be called before calling + * @ref get_representative_cycles again if the matrix was modified in between. Otherwise the old cycles will be + * returned. */ void update_representative_cycles(); /** - * @brief Only available if @ref can_retrieve_representative_cycles is true. + * @brief Only available if @ref PersistenceMatrixOptions::can_retrieve_representative_cycles is true. * Returns all representative cycles of the current filtration. * * @return A const reference to the vector of representative cycles. */ const std::vector& get_representative_cycles(); /** - * @brief Only available if @ref can_retrieve_representative_cycles is true. + * @brief Only available if @ref PersistenceMatrixOptions::can_retrieve_representative_cycles is true. * Returns the cycle representing the given bar. * * @param bar A bar from the current barcode. @@ -1317,57 +1386,63 @@ class Matrix { static constexpr void _assert_options(); }; -template -inline Matrix::Matrix() +template +inline Matrix::Matrix() : operators_(new Field_operators()), cellPool_(new Cell_constructor()), matrix_(operators_, cellPool_) { static_assert( - Options::is_of_boundary_type || !Options::has_vine_update || Options::has_column_pairings, + PersistenceMatrixOptions::is_of_boundary_type || !PersistenceMatrixOptions::has_vine_update || + PersistenceMatrixOptions::has_column_pairings, "When no barcode is recorded with vine swaps, comparaison functions for the columns have to be provided."); _assert_options(); } -template +template template -inline Matrix::Matrix(const std::vector& columns, characteristic_type characteristic) +inline Matrix::Matrix(const std::vector& columns, + characteristic_type characteristic) : operators_(new Field_operators(characteristic)), cellPool_(new Cell_constructor()), matrix_(columns, operators_, cellPool_) { - static_assert(Options::is_of_boundary_type || !Options::has_vine_update || Options::has_column_pairings, + static_assert(PersistenceMatrixOptions::is_of_boundary_type || !PersistenceMatrixOptions::has_vine_update || + PersistenceMatrixOptions::has_column_pairings, "When no barcode is recorded with vine swaps for chain matrices, comparaison functions for the columns " "have to be provided."); _assert_options(); } -template -inline Matrix::Matrix(int numberOfColumns, characteristic_type characteristic) +template +inline Matrix::Matrix(int numberOfColumns, characteristic_type characteristic) : operators_(new Field_operators(characteristic)), cellPool_(new Cell_constructor()), matrix_(numberOfColumns, operators_, cellPool_) { - static_assert(Options::is_of_boundary_type || !Options::has_vine_update || Options::has_column_pairings, + static_assert(PersistenceMatrixOptions::is_of_boundary_type || !PersistenceMatrixOptions::has_vine_update || + PersistenceMatrixOptions::has_column_pairings, "When no barcode is recorded with vine swaps for chain matrices, comparaison functions for the columns " "have to be provided."); _assert_options(); } -template +template template -inline Matrix::Matrix(EventComparatorFunction&& birthComparator, EventComparatorFunction&& deathComparator) +inline Matrix::Matrix(EventComparatorFunction&& birthComparator, + EventComparatorFunction&& deathComparator) : operators_(new Field_operators()), cellPool_(new Cell_constructor()), matrix_(operators_, cellPool_, birthComparator, deathComparator) { static_assert( - !Options::is_of_boundary_type && Options::has_vine_update && !Options::has_column_pairings, + !PersistenceMatrixOptions::is_of_boundary_type && PersistenceMatrixOptions::has_vine_update && + !PersistenceMatrixOptions::has_column_pairings, "Constructor only available for chain matrices when vine swaps are enabled, but barcodes are not recorded."); _assert_options(); } -template +template template -inline Matrix::Matrix(const std::vector& orderedBoundaries, +inline Matrix::Matrix(const std::vector& orderedBoundaries, EventComparatorFunction&& birthComparator, EventComparatorFunction&& deathComparator, characteristic_type characteristic) @@ -1376,14 +1451,15 @@ inline Matrix::Matrix(const std::vector& orderedBoundari matrix_(orderedBoundaries, operators_, cellPool_, birthComparator, deathComparator) { static_assert( - !Options::is_of_boundary_type && Options::has_vine_update && !Options::has_column_pairings, + !PersistenceMatrixOptions::is_of_boundary_type && PersistenceMatrixOptions::has_vine_update && + !PersistenceMatrixOptions::has_column_pairings, "Constructor only available for chain matrices when vine swaps are enabled, but barcodes are not recorded."); _assert_options(); } -template +template template -inline Matrix::Matrix(unsigned int numberOfColumns, +inline Matrix::Matrix(unsigned int numberOfColumns, EventComparatorFunction&& birthComparator, EventComparatorFunction&& deathComparator, characteristic_type characteristic) @@ -1392,13 +1468,14 @@ inline Matrix::Matrix(unsigned int numberOfColumns, matrix_(numberOfColumns, operators_, cellPool_, birthComparator, deathComparator) { static_assert( - !Options::is_of_boundary_type && Options::has_vine_update && !Options::has_column_pairings, + !PersistenceMatrixOptions::is_of_boundary_type && PersistenceMatrixOptions::has_vine_update && + !PersistenceMatrixOptions::has_column_pairings, "Constructor only available for chain matrices when vine swaps are enabled, but barcodes are not recorded."); _assert_options(); } -template -inline Matrix::Matrix(const Matrix& matrixToCopy) +template +inline Matrix::Matrix(const Matrix& matrixToCopy) : operators_(new Field_operators(matrixToCopy.operators_->get_characteristic())), cellPool_(new Cell_constructor()), matrix_(matrixToCopy.matrix_, operators_, cellPool_) @@ -1406,8 +1483,8 @@ inline Matrix::Matrix(const Matrix& matrixToCopy) _assert_options(); } -template -inline Matrix::Matrix(Matrix&& other) noexcept +template +inline Matrix::Matrix(Matrix&& other) noexcept : operators_(std::exchange(other.operators_, nullptr)), cellPool_(std::exchange(other.cellPool_, nullptr)), matrix_(std::move(other.matrix_)) @@ -1417,18 +1494,18 @@ inline Matrix::Matrix(Matrix&& other) noexcept _assert_options(); } -template -inline Matrix::~Matrix() +template +inline Matrix::~Matrix() { matrix_.reset(operators_, cellPool_); delete cellPool_; delete operators_; } -template -inline void Matrix::set_characteristic(characteristic_type characteristic) +template +inline void Matrix::set_characteristic(characteristic_type characteristic) { - if constexpr (!Options::is_z2) { + if constexpr (!PersistenceMatrixOptions::is_z2) { if (operators_->get_characteristic() != 0) { std::cerr << "Warning: Characteristic already initialised. Changing it could lead to incoherences in the matrice " "as the modulo was already applied to values in existing columns."; @@ -1438,9 +1515,9 @@ inline void Matrix::set_characteristic(characteristic_type characterist } } -template +template template -inline void Matrix::insert_column(const Container_type& column) +inline void Matrix::insert_column(const Container_type& column) { assert(operators_->get_characteristic() != 0 && "Columns cannot be initialized if the coefficient field characteristic is not specified."); @@ -1450,194 +1527,210 @@ inline void Matrix::insert_column(const Container_type& column) matrix_.insert_column(column); } -template +template template -inline void Matrix::insert_column(const Container_type& column, index columnIndex) +inline void Matrix::insert_column(const Container_type& column, index columnIndex) { assert(operators_->get_characteristic() != 0 && "Columns cannot be initialized if the coefficient field characteristic is not specified."); - static_assert(!isNonBasic && !Options::has_column_compression, + static_assert(!isNonBasic && !PersistenceMatrixOptions::has_column_compression, "'insert_column' with those parameters is not available for the chosen options."); - static_assert(!Options::has_row_access, + static_assert(!PersistenceMatrixOptions::has_row_access, "Columns have to be inserted at the end of the matrix when row access is enabled."); matrix_.insert_column(column, columnIndex); } -template +template template -inline typename Matrix::insertion_return_type Matrix::insert_boundary(const Boundary_type& boundary, - dimension_type dim) +inline typename Matrix::insertion_return_type +Matrix::insert_boundary(const Boundary_type& boundary, dimension_type dim) { assert(operators_->get_characteristic() != 0 && "Columns cannot be initialized if the coefficient field characteristic is not specified."); - if constexpr (isNonBasic && !Options::is_of_boundary_type && - Options::column_indexation_type == Column_indexation_types::CONTAINER) + + if constexpr (isNonBasic && !PersistenceMatrixOptions::is_of_boundary_type && + PersistenceMatrixOptions::column_indexation_type == Column_indexation_types::CONTAINER) return matrix_.insert_boundary(boundary, dim); else matrix_.insert_boundary(boundary, dim); } -template +template template -inline typename Matrix::insertion_return_type Matrix::insert_boundary(id_index faceIndex, - const Boundary_type& boundary, - dimension_type dim) +inline typename Matrix::insertion_return_type +Matrix::insert_boundary(id_index faceIndex, + const Boundary_type& boundary, + dimension_type dim) { assert(operators_->get_characteristic() != 0 && "Columns cannot be initialized if the coefficient field characteristic is not specified."); static_assert(isNonBasic, "Only enabled for non-basic matrices."); - if constexpr (!Options::is_of_boundary_type && - Options::column_indexation_type == Column_indexation_types::CONTAINER) + if constexpr (!PersistenceMatrixOptions::is_of_boundary_type && + PersistenceMatrixOptions::column_indexation_type == Column_indexation_types::CONTAINER) return matrix_.insert_boundary(faceIndex, boundary, dim); else matrix_.insert_boundary(faceIndex, boundary, dim); } -template -inline typename Matrix::returned_column_type& Matrix::get_column(index columnIndex) +template +inline typename Matrix::returned_column_type& Matrix::get_column( + index columnIndex) { return matrix_.get_column(columnIndex); } -template -inline const typename Matrix::Column_type& Matrix::get_column(index columnIndex) const +template +inline const typename Matrix::Column_type& Matrix::get_column( + index columnIndex) const { return matrix_.get_column(columnIndex); } -template -inline const typename Matrix::Column_type& Matrix::get_column(index columnIndex, bool inR) +template +inline const typename Matrix::Column_type& Matrix::get_column( + index columnIndex, bool inR) { // TODO: I don't think there is a particular reason why the indexation is forced, should be removed. - static_assert(isNonBasic && Options::is_of_boundary_type && - (Options::has_vine_update || Options::can_retrieve_representative_cycles) && - Options::column_indexation_type != Column_indexation_types::IDENTIFIER, - "Only enabled for position indexed RU matrices."); + static_assert( + isNonBasic && PersistenceMatrixOptions::is_of_boundary_type && + (PersistenceMatrixOptions::has_vine_update || PersistenceMatrixOptions::can_retrieve_representative_cycles) && + PersistenceMatrixOptions::column_indexation_type != Column_indexation_types::IDENTIFIER, + "Only enabled for position indexed RU matrices."); return matrix_.get_column(columnIndex, inR); } -template -inline typename Matrix::returned_row_type& Matrix::get_row(id_index rowIndex) +template +inline typename Matrix::returned_row_type& Matrix::get_row( + id_index rowIndex) { - static_assert(Options::has_row_access, "'get_row' is not available for the chosen options."); + static_assert(PersistenceMatrixOptions::has_row_access, "'get_row' is not available for the chosen options."); return matrix_.get_row(rowIndex); } -template -inline const typename Matrix::Row_type& Matrix::get_row(id_index rowIndex) const +template +inline const typename Matrix::Row_type& Matrix::get_row( + id_index rowIndex) const { - static_assert(Options::has_row_access, "'get_row' is not available for the chosen options."); + static_assert(PersistenceMatrixOptions::has_row_access, "'get_row' is not available for the chosen options."); return matrix_.get_row(rowIndex); } -template -inline const typename Matrix::Row_type& Matrix::get_row(id_index rowIndex, bool inR) +template +inline const typename Matrix::Row_type& Matrix::get_row( + id_index rowIndex, bool inR) { - static_assert(Options::has_row_access, "'get_row' is not available for the chosen options."); + static_assert(PersistenceMatrixOptions::has_row_access, "'get_row' is not available for the chosen options."); // TODO: I don't think there is a particular reason why the indexation is forced, should be removed. - static_assert(isNonBasic && Options::is_of_boundary_type && - (Options::has_vine_update || Options::can_retrieve_representative_cycles) && - Options::column_indexation_type != Column_indexation_types::IDENTIFIER, - "Only enabled for position indexed RU matrices."); + static_assert( + isNonBasic && PersistenceMatrixOptions::is_of_boundary_type && + (PersistenceMatrixOptions::has_vine_update || PersistenceMatrixOptions::can_retrieve_representative_cycles) && + PersistenceMatrixOptions::column_indexation_type != Column_indexation_types::IDENTIFIER, + "Only enabled for position indexed RU matrices."); return matrix_.get_row(rowIndex, inR); } -template -inline void Matrix::remove_column(index columnIndex) +template +inline void Matrix::remove_column(index columnIndex) { - static_assert(Options::has_map_column_container && !isNonBasic && !Options::has_column_compression, + static_assert(PersistenceMatrixOptions::has_map_column_container && !isNonBasic && + !PersistenceMatrixOptions::has_column_compression, "'remove_column' is not available for the chosen options."); matrix_.remove_column(columnIndex); } -template -inline void Matrix::erase_row(id_index rowIndex) +template +inline void Matrix::erase_row(id_index rowIndex) { - static_assert(!isNonBasic || Options::is_of_boundary_type || Options::has_removable_rows, - "'erase_row' is not available for the chosen options."); + static_assert( + !isNonBasic || PersistenceMatrixOptions::is_of_boundary_type || PersistenceMatrixOptions::has_removable_rows, + "'erase_row' is not available for the chosen options."); matrix_.erase_row(rowIndex); } -template -inline void Matrix::remove_maximal_face(index columnIndex) +template +inline void Matrix::remove_maximal_face(index columnIndex) { - static_assert(Options::has_removable_columns, + static_assert(PersistenceMatrixOptions::has_removable_columns, "'remove_maximal_face(id_index)' is not available for the chosen options."); - static_assert(isNonBasic && Options::has_vine_update, + static_assert(isNonBasic && PersistenceMatrixOptions::has_vine_update, "'remove_maximal_face(id_index)' is not available for the chosen options."); - static_assert(Options::is_of_boundary_type || (Options::has_map_column_container && Options::has_column_pairings), + static_assert(PersistenceMatrixOptions::is_of_boundary_type || (PersistenceMatrixOptions::has_map_column_container && + PersistenceMatrixOptions::has_column_pairings), "'remove_maximal_face(id_index)' is not available for the chosen options."); matrix_.remove_maximal_face(columnIndex); } -template -inline void Matrix::remove_maximal_face(id_index faceIndex, const std::vector& columnsToSwap) +template +inline void Matrix::remove_maximal_face(id_index faceIndex, + const std::vector& columnsToSwap) { - static_assert(Options::has_removable_columns, + static_assert(PersistenceMatrixOptions::has_removable_columns, "'remove_maximal_face(id_index,const std::vector&)' is not available for the chosen options."); - static_assert(isNonBasic && !Options::is_of_boundary_type, + static_assert(isNonBasic && !PersistenceMatrixOptions::is_of_boundary_type, "'remove_maximal_face(id_index,const std::vector&)' is not available for the chosen options."); - static_assert(Options::has_map_column_container && Options::has_vine_update, + static_assert(PersistenceMatrixOptions::has_map_column_container && PersistenceMatrixOptions::has_vine_update, "'remove_maximal_face(id_index,const std::vector&)' is not available for the chosen options."); matrix_.remove_maximal_face(faceIndex, columnsToSwap); } -template -inline void Matrix::remove_last() +template +inline void Matrix::remove_last() { - static_assert(Options::has_removable_columns || !isNonBasic, + static_assert(PersistenceMatrixOptions::has_removable_columns || !isNonBasic, "'remove_last' is not available for the chosen options."); - static_assert(!Options::has_column_compression || isNonBasic, + static_assert(!PersistenceMatrixOptions::has_column_compression || isNonBasic, + "'remove_last' is not available for the chosen options."); + static_assert(!isNonBasic || PersistenceMatrixOptions::is_of_boundary_type || + PersistenceMatrixOptions::has_map_column_container || !PersistenceMatrixOptions::has_vine_update, "'remove_last' is not available for the chosen options."); - static_assert( - !isNonBasic || Options::is_of_boundary_type || Options::has_map_column_container || !Options::has_vine_update, - "'remove_last' is not available for the chosen options."); matrix_.remove_last(); } -template -inline typename Matrix::dimension_type Matrix::get_max_dimension() const +template +inline typename Matrix::dimension_type Matrix::get_max_dimension() + const { static_assert(isNonBasic, "'get_max_dimension' is not available for the chosen options."); return matrix_.get_max_dimension(); } -template -inline typename Matrix::index Matrix::get_number_of_columns() const +template +inline typename Matrix::index Matrix::get_number_of_columns() const { return matrix_.get_number_of_columns(); } -template -inline typename Matrix::dimension_type Matrix::get_column_dimension(index columnIndex) const +template +inline typename Matrix::dimension_type Matrix::get_column_dimension( + index columnIndex) const { static_assert(isNonBasic, "'get_column_dimension' is not available for the chosen options."); return matrix_.get_column_dimension(columnIndex); } -template +template template -inline std::enable_if_t > Matrix::add_to(Index_type sourceColumnIndex, - Index_type targetColumnIndex) +inline std::enable_if_t > Matrix::add_to( + Index_type sourceColumnIndex, Index_type targetColumnIndex) { matrix_.add_to(sourceColumnIndex, targetColumnIndex); } -template +template template -inline std::enable_if_t > Matrix::add_to(const Cell_range& sourceColumn, - index targetColumnIndex) +inline std::enable_if_t > Matrix::add_to( + const Cell_range& sourceColumn, index targetColumnIndex) { static_assert(!isNonBasic, "For boundary or chain matrices, only additions with columns inside the matrix is allowed to maintain " @@ -1646,12 +1739,12 @@ inline std::enable_if_t > Matrix::add_t matrix_.add_to(sourceColumn, targetColumnIndex); } -template +template template -inline std::enable_if_t > Matrix::multiply_target_and_add_to( +inline std::enable_if_t > Matrix::multiply_target_and_add_to( Index_type sourceColumnIndex, int coefficient, Index_type targetColumnIndex) { - if constexpr (Options::is_z2) { + if constexpr (PersistenceMatrixOptions::is_z2) { // coef will be converted to bool, because of element_type matrix_.multiply_target_and_add_to(sourceColumnIndex, coefficient % 2, targetColumnIndex); } else { @@ -1659,16 +1752,16 @@ inline std::enable_if_t > Matrix::multip } } -template +template template -inline std::enable_if_t > Matrix::multiply_target_and_add_to( +inline std::enable_if_t > Matrix::multiply_target_and_add_to( const Cell_range& sourceColumn, int coefficient, index targetColumnIndex) { static_assert(!isNonBasic, "For boundary or chain matrices, only additions with columns inside the matrix is allowed to maintain " "algebraic consistency."); - if constexpr (Options::is_z2) { + if constexpr (PersistenceMatrixOptions::is_z2) { // coef will be converted to bool, because of element_type matrix_.multiply_target_and_add_to(sourceColumn, coefficient % 2, targetColumnIndex); } else { @@ -1676,12 +1769,12 @@ inline std::enable_if_t > Matrix::multi } } -template +template template -inline std::enable_if_t > Matrix::multiply_source_and_add_to( +inline std::enable_if_t > Matrix::multiply_source_and_add_to( int coefficient, Index_type sourceColumnIndex, Index_type targetColumnIndex) { - if constexpr (Options::is_z2) { + if constexpr (PersistenceMatrixOptions::is_z2) { // coef will be converted to bool, because of element_type matrix_.multiply_source_and_add_to(coefficient % 2, sourceColumnIndex, targetColumnIndex); } else { @@ -1689,16 +1782,16 @@ inline std::enable_if_t > Matrix::multip } } -template +template template -inline std::enable_if_t > Matrix::multiply_source_and_add_to( +inline std::enable_if_t > Matrix::multiply_source_and_add_to( int coefficient, const Cell_range& sourceColumn, index targetColumnIndex) { static_assert(!isNonBasic, "For boundary or chain matrices, only additions with columns inside the matrix is allowed to maintain " "algebraic consistency."); - if constexpr (Options::is_z2) { + if constexpr (PersistenceMatrixOptions::is_z2) { // coef will be converted to bool, because of element_type matrix_.multiply_source_and_add_to(coefficient % 2, sourceColumn, targetColumnIndex); } else { @@ -1706,253 +1799,274 @@ inline std::enable_if_t > Matrix::multi } } -template -inline void Matrix::zero_cell(index columnIndex, id_index rowIndex) +template +inline void Matrix::zero_cell(index columnIndex, id_index rowIndex) { - static_assert(Options::is_of_boundary_type && !Options::has_column_compression, + static_assert(PersistenceMatrixOptions::is_of_boundary_type && !PersistenceMatrixOptions::has_column_compression, "'zero_cell' is not available for the chosen options."); return matrix_.zero_cell(columnIndex, rowIndex); } -template -inline void Matrix::zero_cell(index columnIndex, id_index rowIndex, bool inR) +template +inline void Matrix::zero_cell(index columnIndex, id_index rowIndex, bool inR) { // TODO: I don't think there is a particular reason why the indexation is forced, should be removed. - static_assert(isNonBasic && Options::is_of_boundary_type && - (Options::has_vine_update || Options::can_retrieve_representative_cycles) && - Options::column_indexation_type != Column_indexation_types::IDENTIFIER, - "Only enabled for RU matrices."); + static_assert( + isNonBasic && PersistenceMatrixOptions::is_of_boundary_type && + (PersistenceMatrixOptions::has_vine_update || PersistenceMatrixOptions::can_retrieve_representative_cycles) && + PersistenceMatrixOptions::column_indexation_type != Column_indexation_types::IDENTIFIER, + "Only enabled for RU matrices."); return matrix_.zero_cell(columnIndex, rowIndex, inR); } -template -inline void Matrix::zero_column(index columnIndex) +template +inline void Matrix::zero_column(index columnIndex) { - static_assert(Options::is_of_boundary_type && !Options::has_column_compression, + static_assert(PersistenceMatrixOptions::is_of_boundary_type && !PersistenceMatrixOptions::has_column_compression, "'zero_column' is not available for the chosen options."); return matrix_.zero_column(columnIndex); } -template -inline void Matrix::zero_column(index columnIndex, bool inR) +template +inline void Matrix::zero_column(index columnIndex, bool inR) { // TODO: I don't think there is a particular reason why the indexation is forced, should be removed. - static_assert(isNonBasic && Options::is_of_boundary_type && - (Options::has_vine_update || Options::can_retrieve_representative_cycles) && - Options::column_indexation_type != Column_indexation_types::IDENTIFIER, - "Only enabled for RU matrices."); + static_assert( + isNonBasic && PersistenceMatrixOptions::is_of_boundary_type && + (PersistenceMatrixOptions::has_vine_update || PersistenceMatrixOptions::can_retrieve_representative_cycles) && + PersistenceMatrixOptions::column_indexation_type != Column_indexation_types::IDENTIFIER, + "Only enabled for RU matrices."); return matrix_.zero_column(columnIndex, inR); } -template -inline bool Matrix::is_zero_cell(index columnIndex, id_index rowIndex) +template +inline bool Matrix::is_zero_cell(index columnIndex, id_index rowIndex) { return matrix_.is_zero_cell(columnIndex, rowIndex); } -template -inline bool Matrix::is_zero_cell(index columnIndex, id_index rowIndex, bool inR) const +template +inline bool Matrix::is_zero_cell(index columnIndex, id_index rowIndex, bool inR) const { // TODO: I don't think there is a particular reason why the indexation is forced, should be removed. - static_assert(isNonBasic && Options::is_of_boundary_type && - (Options::has_vine_update || Options::can_retrieve_representative_cycles) && - Options::column_indexation_type != Column_indexation_types::IDENTIFIER, - "Only enabled for RU matrices."); + static_assert( + isNonBasic && PersistenceMatrixOptions::is_of_boundary_type && + (PersistenceMatrixOptions::has_vine_update || PersistenceMatrixOptions::can_retrieve_representative_cycles) && + PersistenceMatrixOptions::column_indexation_type != Column_indexation_types::IDENTIFIER, + "Only enabled for RU matrices."); return matrix_.is_zero_cell(columnIndex, rowIndex, inR); } -template -inline bool Matrix::is_zero_column(index columnIndex) +template +inline bool Matrix::is_zero_column(index columnIndex) { return matrix_.is_zero_column(columnIndex); } -template -inline bool Matrix::is_zero_column(index columnIndex, bool inR) +template +inline bool Matrix::is_zero_column(index columnIndex, bool inR) { // TODO: I don't think there is a particular reason why the indexation is forced, should be removed. - static_assert(isNonBasic && Options::is_of_boundary_type && - (Options::has_vine_update || Options::can_retrieve_representative_cycles) && - Options::column_indexation_type != Column_indexation_types::IDENTIFIER, - "Only enabled for RU matrices."); + static_assert( + isNonBasic && PersistenceMatrixOptions::is_of_boundary_type && + (PersistenceMatrixOptions::has_vine_update || PersistenceMatrixOptions::can_retrieve_representative_cycles) && + PersistenceMatrixOptions::column_indexation_type != Column_indexation_types::IDENTIFIER, + "Only enabled for RU matrices."); return matrix_.is_zero_column(columnIndex, inR); } -template -inline typename Matrix::index Matrix::get_column_with_pivot(id_index faceIndex) const +template +inline typename Matrix::index Matrix::get_column_with_pivot( + id_index faceIndex) const { - static_assert(isNonBasic && (!Options::is_of_boundary_type || - (Options::has_vine_update || Options::can_retrieve_representative_cycles)), + static_assert(isNonBasic && (!PersistenceMatrixOptions::is_of_boundary_type || + (PersistenceMatrixOptions::has_vine_update || + PersistenceMatrixOptions::can_retrieve_representative_cycles)), "'get_column_with_pivot' is not available for the chosen options."); return matrix_.get_column_with_pivot(faceIndex); } -template -inline typename Matrix::id_index Matrix::get_pivot(index columnIndex) +template +inline typename Matrix::id_index Matrix::get_pivot( + index columnIndex) { static_assert(isNonBasic, "'get_pivot' is not available for the chosen options."); return matrix_.get_pivot(columnIndex); } -template -inline Matrix& Matrix::operator=(Matrix other) +template +inline Matrix& Matrix::operator=(Matrix other) { swap(matrix_, other.matrix_); std::swap(operators_, other.operators_); std::swap(cellPool_, other.cellPool_); - // if constexpr (!Options::is_z2) matrix_.set_operators(&operators_); + // if constexpr (!PersistenceMatrixOptions::is_z2) matrix_.set_operators(&operators_); return *this; } -template -inline void Matrix::print() +template +inline void Matrix::print() { return matrix_.print(); } -template -inline const typename Matrix::barcode_type& Matrix::get_current_barcode() +template +inline const typename Matrix::barcode_type& +Matrix::get_current_barcode() { - static_assert(Options::has_column_pairings, "This method was not enabled."); + static_assert(PersistenceMatrixOptions::has_column_pairings, "This method was not enabled."); return matrix_.get_current_barcode(); } -template -inline const typename Matrix::barcode_type& Matrix::get_current_barcode() const +template +inline const typename Matrix::barcode_type& +Matrix::get_current_barcode() const { - static_assert(Options::has_column_pairings, "This method was not enabled."); + static_assert(PersistenceMatrixOptions::has_column_pairings, "This method was not enabled."); static_assert( - !Options::is_of_boundary_type || Options::has_vine_update || Options::can_retrieve_representative_cycles, + !PersistenceMatrixOptions::is_of_boundary_type || PersistenceMatrixOptions::has_vine_update || + PersistenceMatrixOptions::can_retrieve_representative_cycles, "'get_current_barcode' is not const for boundary matrices as the barcode is only computed when explicitely " "asked."); return matrix_.get_current_barcode(); } -template -inline void Matrix::swap_columns(index columnIndex1, index columnIndex2) +template +inline void Matrix::swap_columns(index columnIndex1, index columnIndex2) { - static_assert((!isNonBasic && !Options::has_column_compression) || - (isNonBasic && Options::is_of_boundary_type && !Options::has_vine_update && - !Options::can_retrieve_representative_cycles), - "This method was not enabled."); + static_assert( + (!isNonBasic && !PersistenceMatrixOptions::has_column_compression) || + (isNonBasic && PersistenceMatrixOptions::is_of_boundary_type && !PersistenceMatrixOptions::has_vine_update && + !PersistenceMatrixOptions::can_retrieve_representative_cycles), + "This method was not enabled."); return matrix_.swap_columns(columnIndex1, columnIndex2); } -template -inline void Matrix::swap_rows(index rowIndex1, index rowIndex2) +template +inline void Matrix::swap_rows(index rowIndex1, index rowIndex2) { - static_assert((!isNonBasic && !Options::has_column_compression) || - (isNonBasic && Options::is_of_boundary_type && !Options::has_vine_update && - !Options::can_retrieve_representative_cycles), - "This method was not enabled."); + static_assert( + (!isNonBasic && !PersistenceMatrixOptions::has_column_compression) || + (isNonBasic && PersistenceMatrixOptions::is_of_boundary_type && !PersistenceMatrixOptions::has_vine_update && + !PersistenceMatrixOptions::can_retrieve_representative_cycles), + "This method was not enabled."); return matrix_.swap_rows(rowIndex1, rowIndex2); } -template -inline bool Matrix::vine_swap_with_z_eq_1_case(pos_index index) +template +inline bool Matrix::vine_swap_with_z_eq_1_case(pos_index index) { - static_assert(Options::has_vine_update, "This method was not enabled."); - static_assert( - Options::column_indexation_type == Column_indexation_types::POSITION || - (Options::is_of_boundary_type && Options::column_indexation_type == Column_indexation_types::CONTAINER), - "This method was not enabled."); + static_assert(PersistenceMatrixOptions::has_vine_update, "This method was not enabled."); + static_assert(PersistenceMatrixOptions::column_indexation_type == Column_indexation_types::POSITION || + (PersistenceMatrixOptions::is_of_boundary_type && + PersistenceMatrixOptions::column_indexation_type == Column_indexation_types::CONTAINER), + "This method was not enabled."); return matrix_.vine_swap_with_z_eq_1_case(index); } -template -inline typename Matrix::index Matrix::vine_swap_with_z_eq_1_case(index columnIndex1, - index columnIndex2) +template +inline typename Matrix::index Matrix::vine_swap_with_z_eq_1_case( + index columnIndex1, index columnIndex2) { - static_assert(Options::has_vine_update, "This method was not enabled."); - static_assert( - Options::column_indexation_type == Column_indexation_types::IDENTIFIER || - (!Options::is_of_boundary_type && Options::column_indexation_type == Column_indexation_types::CONTAINER), - "This method was not enabled."); + static_assert(PersistenceMatrixOptions::has_vine_update, "This method was not enabled."); + static_assert(PersistenceMatrixOptions::column_indexation_type == Column_indexation_types::IDENTIFIER || + (!PersistenceMatrixOptions::is_of_boundary_type && + PersistenceMatrixOptions::column_indexation_type == Column_indexation_types::CONTAINER), + "This method was not enabled."); + return matrix_.vine_swap_with_z_eq_1_case(columnIndex1, columnIndex2); } -template -inline bool Matrix::vine_swap(pos_index index) +template +inline bool Matrix::vine_swap(pos_index index) { - static_assert(Options::has_vine_update, "This method was not enabled."); - static_assert( - Options::column_indexation_type == Column_indexation_types::POSITION || - (Options::is_of_boundary_type && Options::column_indexation_type == Column_indexation_types::CONTAINER), - "This method was not enabled."); + static_assert(PersistenceMatrixOptions::has_vine_update, "This method was not enabled."); + static_assert(PersistenceMatrixOptions::column_indexation_type == Column_indexation_types::POSITION || + (PersistenceMatrixOptions::is_of_boundary_type && + PersistenceMatrixOptions::column_indexation_type == Column_indexation_types::CONTAINER), + "This method was not enabled."); return matrix_.vine_swap(index); } -template -inline typename Matrix::index Matrix::vine_swap(index columnIndex1, index columnIndex2) +template +inline typename Matrix::index Matrix::vine_swap( + index columnIndex1, index columnIndex2) { - static_assert(Options::has_vine_update, "This method was not enabled."); - static_assert( - Options::column_indexation_type == Column_indexation_types::IDENTIFIER || - (!Options::is_of_boundary_type && Options::column_indexation_type == Column_indexation_types::CONTAINER), - "This method was not enabled."); + static_assert(PersistenceMatrixOptions::has_vine_update, "This method was not enabled."); + static_assert(PersistenceMatrixOptions::column_indexation_type == Column_indexation_types::IDENTIFIER || + (!PersistenceMatrixOptions::is_of_boundary_type && + PersistenceMatrixOptions::column_indexation_type == Column_indexation_types::CONTAINER), + "This method was not enabled."); return matrix_.vine_swap(columnIndex1, columnIndex2); } -template -inline void Matrix::update_representative_cycles() +template +inline void Matrix::update_representative_cycles() { - static_assert(Options::can_retrieve_representative_cycles, "This method was not enabled."); + static_assert(PersistenceMatrixOptions::can_retrieve_representative_cycles, "This method was not enabled."); matrix_.update_representative_cycles(); } -template -inline const std::vector::cycle_type>& Matrix::get_representative_cycles() +template +inline const std::vector::cycle_type>& +Matrix::get_representative_cycles() { - static_assert(Options::can_retrieve_representative_cycles, "This method was not enabled."); + static_assert(PersistenceMatrixOptions::can_retrieve_representative_cycles, "This method was not enabled."); return matrix_.get_representative_cycles(); } -template -inline const typename Matrix::cycle_type& Matrix::get_representative_cycle(const Bar& bar) +template +inline const typename Matrix::cycle_type& +Matrix::get_representative_cycle(const Bar& bar) { - static_assert(Options::can_retrieve_representative_cycles, "This method was not enabled."); + static_assert(PersistenceMatrixOptions::can_retrieve_representative_cycles, "This method was not enabled."); return matrix_.get_representative_cycle(bar); } -template -inline constexpr void Matrix::_assert_options() +template +inline constexpr void Matrix::_assert_options() { - static_assert(Options::column_type != Column_types::HEAP || !Options::has_row_access, - "Row access is not possible for heap columns."); - static_assert(!Options::has_vine_update || Options::is_z2, "Vine update currently works only for Z_2 coefficients."); - // static_assert(!Options::can_retrieve_representative_cycles || Options::is_z2, + static_assert( + PersistenceMatrixOptions::column_type != Column_types::HEAP || !PersistenceMatrixOptions::has_row_access, + "Row access is not possible for heap columns."); + static_assert(!PersistenceMatrixOptions::has_vine_update || PersistenceMatrixOptions::is_z2, + "Vine update currently works only for Z_2 coefficients."); + // static_assert(!PersistenceMatrixOptions::can_retrieve_representative_cycles || PersistenceMatrixOptions::is_z2, // "Representaive cycles can currently only be computed with Z_2 coefficients."); - static_assert(Options::column_type != Column_types::HEAP || !Options::has_column_compression, - "Column compression not compatible with heap columns."); - -// // This should be warnings instead, as Options::has_column_compression is just ignored in those cases and don't -// // produces errors as long as the corresponding methods are not called. -// static_assert(!Options::has_column_compression || !Options::has_column_pairings, -// "Column compression not available to compute persistence homology (it would bring no advantages; " -// "use it for co-homology instead)."); -// static_assert(!Options::has_column_compression || !Options::has_vine_update, -// "Column compression not available for vineyards."); -// static_assert(!Options::has_column_compression || !Options::can_retrieve_representative_cycles, -// "Column compression not available to retrieve representative cycles."); -// // Would column removal while column compression be useful? If yes, should erase() remove a single column or the -// // class of columns identical to the input? -// // For a single column, I have an implementation for union-find (not the current one) which allows deleting a -// // single element in constant time, but find becomes log n in worst case. -// // For a column class, we either just ignore the removed class (constant time), but this results in memory -// // residues, or, we have an erase method which is at least linear in the size of the class. -// static_assert(!Options::has_column_compression || !Options::has_map_column_container, -// "When column compression is used, the removal of columns is not implemented yet."); + static_assert( + PersistenceMatrixOptions::column_type != Column_types::HEAP || !PersistenceMatrixOptions::has_column_compression, + "Column compression not compatible with heap columns."); + + // // This should be warnings instead, as PersistenceMatrixOptions::has_column_compression is just ignored in those + // // cases and don't produces errors as long as the corresponding methods are not called. + // static_assert(!PersistenceMatrixOptions::has_column_compression || !PersistenceMatrixOptions::has_column_pairings, + // "Column compression not available to compute persistence homology (it would bring no advantages; " + // "use it for co-homology instead)."); + // static_assert(!PersistenceMatrixOptions::has_column_compression || !PersistenceMatrixOptions::has_vine_update, + // "Column compression not available for vineyards."); + // static_assert(!PersistenceMatrixOptions::has_column_compression || + // !PersistenceMatrixOptions::can_retrieve_representative_cycles, + // "Column compression not available to retrieve representative cycles."); + // // Would column removal while column compression be useful? If yes, should erase() remove a single column or the + // // class of columns identical to the input? + // // For a single column, I have an implementation for union-find (not the current one) which allows deleting a + // // single element in constant time, but find becomes log n in worst case. + // // For a column class, we either just ignore the removed class (constant time), but this results in memory + // // residues, or, we have an erase method which is at least linear in the size of the class. + // static_assert( + // !PersistenceMatrixOptions::has_column_compression || !PersistenceMatrixOptions::has_map_column_container, + // "When column compression is used, the removal of columns is not implemented yet."); } } // namespace persistence_matrix diff --git a/src/Persistence_matrix/include/gudhi/persistence_matrix_options.h b/src/Persistence_matrix/include/gudhi/persistence_matrix_options.h index 458e67a742..61db54bcda 100644 --- a/src/Persistence_matrix/include/gudhi/persistence_matrix_options.h +++ b/src/Persistence_matrix/include/gudhi/persistence_matrix_options.h @@ -23,34 +23,41 @@ namespace Gudhi { namespace persistence_matrix { /** + * @ingroup persistence_matrix + * * @brief List of column types. */ enum Column_types { - LIST, /**< Underlying container is a std::list. */ - SET, /**< Underlying container is a std::set. */ - HEAP, /**< Underlying container is a std::vector ordered as a heap. - Is not compatible with row access and column compression */ - VECTOR, /**< Underlying container is a std::vector with a lazy removal method. */ - NAIVE_VECTOR, /**< Underlying container is a std::vector. */ - UNORDERED_SET, /**< Underlying container is a std::unordered_set. */ - INTRUSIVE_LIST, /**< Underlying container is a boost::intrusive::list. */ - INTRUSIVE_SET /**< Underlying container is a boost::intrusive::set. */ + LIST, /**< @ref List_column "": Underlying container is a std::list<@ref Cell>. */ + SET, /**< @ref Set_column "": Underlying container is a std::set<@ref Cell>. */ + HEAP, /**< @ref Heap_column "": Underlying container is a std::vector<@ref Cell> ordered as a heap. + Is not compatible with row access and column compression. */ + VECTOR, /**< @ref Vector_column "": Underlying container is a std::vector<@ref Cell> with a lazy removal method. */ + NAIVE_VECTOR, /**< @ref Naive_vector_column "": Underlying container is a std::vector<@ref Cell>. */ + UNORDERED_SET, /**< @ref Unordered_set_column "": Underlying container is a std::unordered_set<@ref Cell>. */ + INTRUSIVE_LIST, /**< @ref Intrusive_list_column "": Underlying container is a boost::intrusive::list<@ref Cell>. */ + INTRUSIVE_SET /**< @ref Intrusive_set_column "": Underlying container is a boost::intrusive::set<@ref Cell>. */ }; /** - * @brief List if indexation schemes. See [TODO: ref to introduction] for more details about the meaning + * @ingroup persistence_matrix + * + * @brief List if indexation schemes. See @ref mp_indexation "description of indexation schemes" for more details about the meaning * of the indexation types. */ enum Column_indexation_types { - CONTAINER, /**< Default use of MatIdx indices. */ - POSITION, /**< All input and output MatIdx indices are replaced with PosIdx indices. */ - IDENTIFIER /**< All input and output MatIdx indices are replaced with IDIdx indices. */ + CONTAINER, /**< Default use of @ref MatIdx indices. */ + POSITION, /**< All input and output @ref MatIdx indices are replaced with @ref PosIdx indices. */ + IDENTIFIER /**< All input and output @ref MatIdx indices are replaced with @ref IDIdx indices. */ }; /** + * @struct Default_options persistence_matrix_options.h gudhi/persistence_matrix_options.h + * @ingroup persistence_matrix + * * @brief Default option structure for @ref Matrix class. - * See [TODO: concept] for a more detailed description of the fields. - * Produces a base matrix with no enabled option. + * See the @ref PersistenceMatrixOptions concept for a more detailed description of the fields. + * Produces a @ref basematrix "base matrix" with no enabled option. * * To create other matrix types, the easiest is to simply inherit from this structure and overwrite only the options * one is interested in. @@ -63,7 +70,7 @@ enum Column_indexation_types { */ template > + class FieldOperators = persistence_fields::Zp_field_operators<> > struct Default_options { using Field_coeff_operators = FieldOperators; @@ -145,7 +152,7 @@ struct Multi_persistence_options : Default_options */ template > + class FieldOperators = persistence_fields::Zp_field_operators<> > struct Cohomology_persistence_options : Default_options { static const bool has_row_access = true; diff --git a/src/Persistence_matrix/test/Persistence_matrix_field_operators_tests.cpp b/src/Persistence_matrix/test/Persistence_matrix_field_operators_tests.cpp index 2d0180a368..1ac8820fcd 100644 --- a/src/Persistence_matrix/test/Persistence_matrix_field_operators_tests.cpp +++ b/src/Persistence_matrix/test/Persistence_matrix_field_operators_tests.cpp @@ -17,10 +17,10 @@ #include "gudhi/Fields/Multi_field_operators.h" #include "gudhi/Fields/Multi_field_small_operators.h" -using Gudhi::persistence_matrix::Z2_field_operators; -using Gudhi::persistence_matrix::Zp_field_operators; -using Gudhi::persistence_matrix::Multi_field_operators; -using Gudhi::persistence_matrix::Multi_field_operators_with_small_characteristics; +using Gudhi::persistence_fields::Z2_field_operators; +using Gudhi::persistence_fields::Zp_field_operators; +using Gudhi::persistence_fields::Multi_field_operators; +using Gudhi::persistence_fields::Multi_field_operators_with_small_characteristics; template void test_z2_standart_field_operators(Z2& op) diff --git a/src/Persistence_matrix/test/Persistence_matrix_field_tests.cpp b/src/Persistence_matrix/test/Persistence_matrix_field_tests.cpp index a74491602d..1c7131c7f2 100644 --- a/src/Persistence_matrix/test/Persistence_matrix_field_tests.cpp +++ b/src/Persistence_matrix/test/Persistence_matrix_field_tests.cpp @@ -20,13 +20,13 @@ #include "gudhi/Fields/Multi_field_shared.h" #include "gudhi/Fields/Multi_field_small_shared.h" -using Gudhi::persistence_matrix::Z2_field_element; -using Gudhi::persistence_matrix::Zp_field_element; -using Gudhi::persistence_matrix::Shared_Zp_field_element; -using Gudhi::persistence_matrix::Multi_field_element; -using Gudhi::persistence_matrix::Multi_field_element_with_small_characteristics; -using Gudhi::persistence_matrix::Shared_multi_field_element; -using Gudhi::persistence_matrix::Shared_multi_field_element_with_small_characteristics; +using Gudhi::persistence_fields::Z2_field_element; +using Gudhi::persistence_fields::Zp_field_element; +using Gudhi::persistence_fields::Shared_Zp_field_element; +using Gudhi::persistence_fields::Multi_field_element; +using Gudhi::persistence_fields::Multi_field_element_with_small_characteristics; +using Gudhi::persistence_fields::Shared_multi_field_element; +using Gudhi::persistence_fields::Shared_multi_field_element_with_small_characteristics; template void test_z2_standart_field_constructors(){ diff --git a/src/Persistence_matrix/test/pm_column_tests_mastermatrix.h b/src/Persistence_matrix/test/pm_column_tests_mastermatrix.h index 0455cd1bca..d6fae3b1cb 100644 --- a/src/Persistence_matrix/test/pm_column_tests_mastermatrix.h +++ b/src/Persistence_matrix/test/pm_column_tests_mastermatrix.h @@ -42,8 +42,8 @@ using Gudhi::persistence_matrix::Dummy_row_access; using Gudhi::persistence_matrix::Pool_cell_constructor; using Gudhi::persistence_matrix::New_cell_constructor; -using Zp = Gudhi::persistence_matrix::Zp_field_operators<>; -using Z2 = Gudhi::persistence_matrix::Z2_field_operators; +using Zp = Gudhi::persistence_fields::Zp_field_operators<>; +using Z2 = Gudhi::persistence_fields::Z2_field_operators; template struct Column_mini_matrix diff --git a/src/Persistence_matrix/test/pm_matrix_tests.h b/src/Persistence_matrix/test/pm_matrix_tests.h index b7c4833e14..aae9d9ca75 100644 --- a/src/Persistence_matrix/test/pm_matrix_tests.h +++ b/src/Persistence_matrix/test/pm_matrix_tests.h @@ -325,47 +325,47 @@ void test_constructors(){ auto columns = build_simple_boundary_matrix(); //default constructor - // Matrix m; - // BOOST_CHECK_EQUAL(m.get_number_of_columns(), 0); - // test_content_equality(empty, m); + Matrix m; + BOOST_CHECK_EQUAL(m.get_number_of_columns(), 0); + test_content_equality(empty, m); //constructor from given boundary matrix Matrix mb(columns, 5); - // if constexpr (is_RU()){ - // columns[5].clear(); - // } else if constexpr (is_Chain()){ - // columns = build_simple_chain_matrix(); - // } - - // BOOST_CHECK_EQUAL(mb.get_number_of_columns(), 7); - // test_content_equality(columns, mb); - - // //constructor reserving column space - // Matrix mr(5); - // BOOST_CHECK_EQUAL(mr.get_number_of_columns(), 0); - // test_content_equality(empty, mr); - - // //copy constructor - // Matrix mc1(mb); - // Matrix mc2 = mb; - // BOOST_CHECK_EQUAL(mc1.get_number_of_columns(), 7); - // BOOST_CHECK_EQUAL(mc2.get_number_of_columns(), 7); - // test_content_equality(columns, mc1); - // test_content_equality(columns, mc2); - - // //move constructor - // Matrix mm(std::move(mb)); - // BOOST_CHECK_EQUAL(mm.get_number_of_columns(), 7); - // BOOST_CHECK_EQUAL(mb.get_number_of_columns(), 0); - // test_content_equality(columns, mm); - // test_content_equality(empty, mb); - - // //swap - // swap(mm, mb); - // BOOST_CHECK_EQUAL(mm.get_number_of_columns(), 0); - // BOOST_CHECK_EQUAL(mb.get_number_of_columns(), 7); - // test_content_equality(empty, mm); - // test_content_equality(columns, mb); + if constexpr (is_RU()){ + columns[5].clear(); + } else if constexpr (is_Chain()){ + columns = build_simple_chain_matrix(); + } + + BOOST_CHECK_EQUAL(mb.get_number_of_columns(), 7); + test_content_equality(columns, mb); + + //constructor reserving column space + Matrix mr(5); + BOOST_CHECK_EQUAL(mr.get_number_of_columns(), 0); + test_content_equality(empty, mr); + + //copy constructor + Matrix mc1(mb); + Matrix mc2 = mb; + BOOST_CHECK_EQUAL(mc1.get_number_of_columns(), 7); + BOOST_CHECK_EQUAL(mc2.get_number_of_columns(), 7); + test_content_equality(columns, mc1); + test_content_equality(columns, mc2); + + //move constructor + Matrix mm(std::move(mb)); + BOOST_CHECK_EQUAL(mm.get_number_of_columns(), 7); + BOOST_CHECK_EQUAL(mb.get_number_of_columns(), 0); + test_content_equality(columns, mm); + test_content_equality(empty, mb); + + //swap + swap(mm, mb); + BOOST_CHECK_EQUAL(mm.get_number_of_columns(), 0); + BOOST_CHECK_EQUAL(mb.get_number_of_columns(), 7); + test_content_equality(empty, mm); + test_content_equality(columns, mb); } inline bool birth_comp(unsigned int columnIndex1, unsigned int columnIndex2){ return false; }; @@ -379,7 +379,7 @@ void test_chain_constructors(){ Matrix m(birth_comp, death_comp); BOOST_CHECK_EQUAL(m.get_number_of_columns(), 0); - //constructor from given boundary matrix + //constructor from given @ref boundarymatrix "boundary matrix" Matrix mb(ordered_boundaries, birth_comp, death_comp, 5); BOOST_CHECK_EQUAL(mb.get_number_of_columns(), 7); BOOST_CHECK_EQUAL(mb.get_column_dimension(2), 0); @@ -443,7 +443,7 @@ void test_chain_constructors(){ // //base comp // //boundary // //ru: inR = true forced -// //chain: just for sanity checks as a valid chain matrix never has an empty column. +// //chain: just for sanity checks as a valid @ref chainmatrix "chain matrix" never has an empty column. // //id to pos // //pos to id // bool is_zero_column(index columnIndex); @@ -997,7 +997,7 @@ void test_ru_u_row_access(){ template void test_row_removal(){ auto columns = build_simple_boundary_matrix(); - columns[6].pop_back(); //empties row 5. Not a legit boundary matrix anymore, but for the test, should be fine, except for chain. + columns[6].pop_back(); //empties row 5. Not a legit @ref boundarymatrix "boundary matrix" anymore, but for the test, should be fine, except for chain. Matrix m(columns, 5); diff --git a/src/Persistence_matrix/test/pm_matrix_tests_boost_type_lists.h b/src/Persistence_matrix/test/pm_matrix_tests_boost_type_lists.h index f2ef951a20..41d6add2a5 100644 --- a/src/Persistence_matrix/test/pm_matrix_tests_boost_type_lists.h +++ b/src/Persistence_matrix/test/pm_matrix_tests_boost_type_lists.h @@ -161,7 +161,7 @@ using all_ra_values_list = boost::mp11::mp_list,ra_v using ra_values_list = boost::mp11::mp_list,ra_value,ra_value,ra_value >; using ra_r_values_list = boost::mp11::mp_list,ra_value >; -// Base matrices +// @ref basematrix "base matrices" template using base_option_template = boost::mp11::mp_remove_if, bool_is_z2, col_type_list, has_row_t, bool_rem_col, bool_swap> >, matrix_non_validity>; @@ -191,7 +191,7 @@ using opt_col_comp_zp = compression_option_template; using opt_col_comp_zp_ra_r = compression_option_template; -// Boundary matrices +// @ref boundarymatrix "boundary matrices" template using boundary_option_template = boost::mp11::mp_remove_if, bool_is_z2, col_type_list, has_row_t, bool_rem_col, bool_swap, bool_pos_idx> >, matrix_non_validity>; @@ -265,7 +265,7 @@ using opt_ru_rep_zp_ra_r = ru_option_template using opt_ru_rep_zp_r = ru_option_template; -// Chain matrices +// @ref chainmatrix "chain matrices" using z2_chain_vine_rep_values_list = boost::mp11::mp_product, true_value_list, true_value_list, true_value_list, true_value_list>; using z2_chain_vine_rep_no_barcode_values_list = boost::mp11::mp_product, true_value_list, false_value_list, true_value_list, true_value_list>; diff --git a/src/Persistence_matrix/test/pm_matrix_tests_options.h b/src/Persistence_matrix/test/pm_matrix_tests_options.h index dbd3c0104d..57485b8ee8 100644 --- a/src/Persistence_matrix/test/pm_matrix_tests_options.h +++ b/src/Persistence_matrix/test/pm_matrix_tests_options.h @@ -19,7 +19,7 @@ using Gudhi::persistence_matrix::Column_types; using Gudhi::persistence_matrix::Matrix; using Gudhi::persistence_matrix::Column_indexation_types; -using Zp = Gudhi::persistence_matrix::Zp_field_operators<> ; +using Zp = Gudhi::persistence_fields::Zp_field_operators<> ; template struct Base_options{ diff --git a/src/Persistence_matrix/test/pm_test_utilities.h b/src/Persistence_matrix/test/pm_test_utilities.h index de93d6c8b8..4775e527e1 100644 --- a/src/Persistence_matrix/test/pm_test_utilities.h +++ b/src/Persistence_matrix/test/pm_test_utilities.h @@ -23,7 +23,7 @@ using Gudhi::persistence_matrix::Heap_column; using Gudhi::persistence_matrix::Matrix; using Gudhi::persistence_matrix::Column_indexation_types; -using Zp = Gudhi::persistence_matrix::Zp_field_operators<> ; +using Zp = Gudhi::persistence_fields::Zp_field_operators<> ; inline Zp _g_operators = Zp(5); diff --git a/src/common/doc/main_page.md b/src/common/doc/main_page.md index cd173f6819..c6184f884e 100644 --- a/src/common/doc/main_page.md +++ b/src/common/doc/main_page.md @@ -383,6 +383,31 @@ +### Persistence Matrix + + + + + + + + + + +
+ \image html "3DTorus_poch.png" + + Matrix structure for filtered complexes with multiple functionnalities related to persistence homology, + such as representative cycles computation or vineyards. + TODO: picture + + Author: Hannah Schreiber
+ Introduced in: GUDHI 1.0.0
+ Copyright: MIT
+
+ User manual: \ref persistence_matrix +
+ ## Topological descriptors tools {#TopologicalDescriptorsTools} ### Bottleneck distance