Skip to content

Commit

Permalink
doc
Browse files Browse the repository at this point in the history
  • Loading branch information
@hschreiber
hschreiber committed Apr 10, 2024
1 parent cd1b83a commit 1a9349f
Show file tree
Hide file tree
Showing 58 changed files with 1,682 additions and 1,161 deletions.
35 changes: 29 additions & 6 deletions biblio/bibliography.bib
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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},
Expand All @@ -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,
Expand Down
9 changes: 6 additions & 3 deletions src/Persistence_matrix/concept/FieldOperators.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
{
Expand Down
27 changes: 15 additions & 12 deletions src/Persistence_matrix/concept/PersistenceMatrixColumn.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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. */
Expand Down Expand Up @@ -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<Row_type>.
* @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.
Expand Down Expand Up @@ -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<Row_type>.
* @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.
Expand Down Expand Up @@ -164,7 +167,7 @@ class PersistenceMatrixColumn :
* @tparam Row_container_type Either std::map if @ref PersistenceMatrixOptions::has_removable_rows is true or
* std::vector<Row_type>.
* @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.
Expand Down Expand Up @@ -227,27 +230,27 @@ 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 <class Map_type>
void reorder(const Map_type& valueMap, [[maybe_unused]] index columnIndex = -1);
/**
* @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.
Expand All @@ -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.
*/
Expand All @@ -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.
*/
Expand Down
75 changes: 41 additions & 34 deletions src/Persistence_matrix/concept/PersistenceMatrixOptions.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -61,41 +66,42 @@ 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;

/**
* @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<id_index>& 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<id_index>& 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;

Expand All @@ -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
Expand Down
12 changes: 12 additions & 0 deletions src/Persistence_matrix/doc/COPYRIGHT
View file
Original file line number Diff line number Diff line change
@@ -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.
Loading

0 comments on commit 1a9349f

Please sign in to comment.