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 1a9349f commit cf41344
Show file tree
Hide file tree
Showing 4 changed files with 114 additions and 96 deletions.
24 changes: 13 additions & 11 deletions src/Persistence_matrix/concept/FieldOperators.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,10 @@ namespace persistence_matrix {
*
* @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.
* 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 Expand Up @@ -68,7 +70,7 @@ class FieldOperators
*
* @param e1 First element.
* @param e2 Second element.
* @return ( @p e1 + @p e2 ) % characteristic, such that the result is positive.
* @return `(e1 + e2) % characteristic`, such that the result is positive.
*/
element_type add(element_type e1, element_type e2) const;

Expand All @@ -77,7 +79,7 @@ class FieldOperators
*
* @param e1 First element.
* @param e2 Second element.
* @return ( @p e1 - @p e2 ) % characteristic, such that the result is positive.
* @return `(e1 - e2) % characteristic`, such that the result is positive.
*/
element_type substract(element_type e1, element_type e2) const;

Expand All @@ -86,7 +88,7 @@ class FieldOperators
*
* @param e1 First element.
* @param e2 Second element.
* @return ( @p e1 * @p e2 ) % characteristic, such that the result is positive.
* @return `(e1 * e2) % characteristic`, such that the result is positive.
*/
element_type multiply(element_type e1, element_type e2) const;

Expand All @@ -96,7 +98,7 @@ class FieldOperators
* @param e First element.
* @param m Second element.
* @param a Third element.
* @return ( @p e * @p m + @p a ) % characteristic, such that the result is positive.
* @return `(e * m + a) % characteristic`, such that the result is positive.
*/
element_type multiply_and_add(element_type e, element_type m, element_type a) const;

Expand All @@ -107,7 +109,7 @@ class FieldOperators
* @param e First element.
* @param m Second element.
* @param a Third element.
* @return ( ( @p e + @p a ) * @p m ) % characteristic, such that the result is positive.
* @return `((e + a) * m) % characteristic`, such that the result is positive.
*/
element_type add_and_multiply(element_type e, element_type a, element_type m) const;

Expand All @@ -116,7 +118,7 @@ class FieldOperators
*
* @param e1 First element to compare.
* @param e2 Second element to compare.
* @return true If @p e1 % characteristic == @p e2 % characteristic.
* @return true If `e1 % characteristic == e2 % characteristic`.
* @return false Otherwise.
*/
bool are_equal(element_type e1, element_type e2) const;
Expand All @@ -125,13 +127,13 @@ class FieldOperators
* @brief Returns the inverse of the given element in the field.
*
* @param e Element to get the inverse from.
* @return Inverse in the current field of @p e % characteristic.
* @return Inverse in the current field of `e % characteristic`.
*/
element_type get_inverse(element_type e) const;
/**
* @brief In the case the field is a multi-field, returns the inverse of the given element in the fields
* corresponding to the given sub-product of the product of all characteristics in the multi-field.
* See [TODO: cite multi field paper] for more details.
* See @cite boissonnat:hal-00922572 for more details.
* If the field is a usual field, simply returns the inverse in the field.
*
* @param e Element to get the inverse from.
Expand All @@ -156,7 +158,7 @@ class FieldOperators
static constexpr element_type get_multiplicative_identity();
/**
* @brief For multi-fields, returns the partial multiplicative identity of the field from the given product.
* See [TODO: cite multi field paper] for more details.
* See @cite boissonnat:hal-00922572 for more details.
* Otherwise, simply returns the multiplicative identity of the field.
*
* @param productOfCharacteristics Product of the different characteristics to take into account in the multi-field.
Expand Down
116 changes: 64 additions & 52 deletions src/Persistence_matrix/concept/PersistenceMatrixColumn.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,42 +17,50 @@
namespace Gudhi {
namespace persistence_matrix {

/**
* @ingroup persistence_matrix
*
* @brief If PersistenceMatrixOptions::has_row_access is true, then @ref Row_access. Otherwise @ref Dummy_row_access.
* Can eventually be removed if the structure of the column does not allow row access (as for @ref Heap_column), but
* then it needs to be notified in the documentation of @ref Column_types and as static_assert in
* @ref Matrix::_assert_options.
*/
using Row_access_option = Row_access;
/**
* @ingroup persistence_matrix
*
* @brief If @ref PersistenceMatrixOptions::has_column_pairings or @ref PersistenceMatrixOptions::has_vine_update or
* @ref PersistenceMatrixOptions::can_retrieve_representative_cycles is true, then @ref Column_dimension_holder.
* Otherwise @ref Dummy_dimension_holder.
*/
using Column_dimension_option = Column_dimension_holder;
/**
* @ingroup persistence_matrix
*
* @brief If @ref PersistenceMatrixOptions::is_of_boundary_type is false, and,
* @ref PersistenceMatrixOptions::has_column_pairings or @ref PersistenceMatrixOptions::has_vine_update or
* @ref PersistenceMatrixOptions::can_retrieve_representative_cycles is true, then @ref Chain_column_extra_properties.
* Otherwise @ref Dummy_chain_properties.
*/
using Chain_column_option = Chain_column_extra_properties;

/**
* @ingroup persistence_matrix
*
* @brief Concept of the column classes used by the @ref Matrix class.
* @brief Concept of the column classes used by the @ref Matrix class. The classes the columns inheritates from
* are either real or dummy classes, see @ref Row_access_option, @ref Column_dimension_option, @ref Chain_column_option.
*
* 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.
* @ref Set_column, @ref Unordered_set_column, @ref Intrusive_list_column and @ref Intrusive_set_column.
*/
class PersistenceMatrixColumn :
/**
* @brief If PersistenceMatrixOptions::has_row_access is true, then @ref Row_access.
* Otherwise @ref Dummy_row_access. Can eventually be removed if the structure of the column does not allow
* row access (as for @ref Heap_column), but then it needs to be notified in the documentation of @ref Column_types
* and as static_assert in @ref Matrix::_assert_options.
*/
public Row_access_option,
/**
* @brief If PersistenceMatrixOptions::has_column_pairings ||
PersistenceMatrixOptions::has_vine_update ||
PersistenceMatrixOptions::can_retrieve_representative_cycles is true, then @ref
Column_dimension_holder. Otherwise @ref Dummy_dimension_holder.
*
*/
public Column_dimension_option,
/**
* @brief If (PersistenceMatrixOptions::has_column_pairings ||
PersistenceMatrixOptions::has_vine_update ||
PersistenceMatrixOptions::can_retrieve_representative_cycles) &&
!PersistenceMatrixOptions::is_of_boundary_type is true, then @ref Chain_column_extra_properties.
Otherwise @ref Dummy_chain_properties.
*/
public Chain_column_option
public Chain_column_option
{
public:
using Master = unspecified; /**< Master matrix. */
using Cell_constructor = unspecified; /**< @ref Cell factory. */
using Master = unspecified; /**< Master matrix, that is a templated @ref Matrix. */
using Cell_constructor = unspecified; /**< @ref Cell factory. E.g., @ref Pool_cell_constructor. */
using Field_operators = unspecified; /**< Follows the @ref FieldOperators concept. */
using Field_element_type = unspecified; /**< Type of a field element. */
using index = unspecified; /**< Type of @ref MatIdx index. */
Expand All @@ -66,7 +74,7 @@ class PersistenceMatrixColumn :
using const_reverse_iterator = unspecified; /**< Column const_reverse_iterator type. */

/**
* @brief Constructs an empty column. If @p cellConstructor is not specified or is set to nullptr, the column
* @brief Constructs an empty column. If @p cellConstructor is not specified or is set to `nullptr`, the column
* can only be used as a dummy, i.e., no modifying method should be used or there will be a segmentation fault.
* Same goes for @p operators if @ref PersistenceMatrixOptions::is_z2 is false.
*
Expand All @@ -76,10 +84,10 @@ class PersistenceMatrixColumn :
PersistenceMatrixColumn(Field_operators* operators = nullptr, Cell_constructor* cellConstructor = nullptr);
/**
* @brief Constructs a column from the given range of @ref Matrix::cell_rep_type. If the dimension is stored,
* the face is assumed to be simplicial and its dimension to be @ref nonZeroRowIndices length - 1 or 0.
* the face is assumed to be simplicial and its dimension to be `nonZeroRowIndices length - 1` or `0`.
* Otherwise, the dimension should be specified with another constructor.
*
* @tparam Container_type Range of @ref Matrix::cell_rep_type. Assumed to have a begin(), end() and size() method.
* @tparam Container_type Range of @ref Matrix::cell_rep_type. Assumed to have a %begin(), %end() and %size() method.
* @param nonZeroRowIndices Range of @ref Matrix::cell_rep_type representing all rows with non zero values.
* @param operators Pointer to the field operators.
* @param cellConstructor Pointer to the cell factory.
Expand All @@ -92,9 +100,9 @@ class PersistenceMatrixColumn :
* @brief Constructs a column from the given range of @ref Matrix::cell_rep_type such that the rows can be accessed.
* Each new cell in the column is also inserted in a row using @ref Row_access::insert_cell.
* If the dimension is stored, the face is assumed to be simplicial and its dimension to be
* @ref nonZeroRowIndices length - 1 or 0. Otherwise, the dimension should be specified with another constructor.
* `nonZeroRowIndices length - 1` or `0`. Otherwise, the dimension should be specified with another constructor.
*
* @tparam Container_type Range of @ref Matrix::cell_rep_type. Assumed to have a begin(), end() and size() method.
* @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 @ref MatIdx column index that should be specified to the cells.
Expand All @@ -113,7 +121,7 @@ class PersistenceMatrixColumn :
* @brief Constructs a column from the given range of @ref Matrix::cell_rep_type and stores the given dimension
* if @ref Column_dimension_option is not a dummy.
*
* @tparam Container_type Range of @ref Matrix::cell_rep_type. Assumed to have a begin(), end() and size() method.
* @tparam Container_type Range of @ref Matrix::cell_rep_type. Assumed to have a %begin(), %end() and %size() method.
* @param nonZeroChainRowIndices 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 operators Pointer to the field operators.
Expand All @@ -129,7 +137,7 @@ class PersistenceMatrixColumn :
* Each new cell in the column is also inserted in a row using @ref Row_access::insert_cell.
* Stores the given dimension if @ref Column_dimension_option is not a dummy.
*
* @tparam Container_type Range of @ref Matrix::cell_rep_type. Assumed to have a begin(), end() and size() method.
* @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 @ref MatIdx column index that should be specified to the cells.
Expand Down Expand Up @@ -230,9 +238,9 @@ 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 @ref boundarymatrix "boundary matrices" using lazy swaps.
* Only useful for @ref basematrix "base" and @ref boundarymatrix "boundary matrices" using lazy swaps.
*
* @tparam Map_type Map with an `at` method.
* @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 @ref MatIdx column index of the column. If -1, the index does not change. Ignored if
Expand All @@ -243,14 +251,15 @@ class PersistenceMatrixColumn :
/**
* @brief Zeros/empties the column.
*
* Only useful for base and @ref boundarymatrix "boundary matrices". Used in `zero_column` and in the reduction algorithm
* for the persistence barcode.
* Only useful for @ref basematrix "base" and @ref boundarymatrix "boundary matrices".
* Used in @ref Matrix::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 @ref boundarymatrix "boundary matrices". Used in `zero_cell` and during vine swaps.
* Only useful for @ref basematrix "base" and @ref boundarymatrix "boundary matrices".
* Used in @ref Matrix::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 @@ -262,7 +271,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 @ref chainmatrix "chain matrices".
* Only useful for @ref boundarymatrix "boundary" and @ref chainmatrix "chain matrices".
*
* @return Row index of the pivot or -1.
*/
Expand All @@ -272,7 +281,7 @@ class PersistenceMatrixColumn :
*
* Has to have value 1 if \f$ Z_2 \f$ coefficients are used.
*
* Only useful for boundary and @ref chainmatrix "chain matrices".
* Only useful for @ref boundarymatrix "boundary" and @ref chainmatrix "chain matrices".
*
* @return The value of the pivot or 0.
*/
Expand Down Expand Up @@ -356,9 +365,10 @@ class PersistenceMatrixColumn :
/**
* @brief Adds the given @ref Cell range onto the column.
*
* @tparam Cell_range @ref Cell range with `begin` and `end` method.
* @param column @ref Cell range. Every cell has to return the right value when using `get_row_index` and,
* if @ref PersistenceMatrixOptions::is_z2 is false, also when using `get_element`.
* @tparam Cell_range @ref Cell range with %begin() and %end() method.
* @param column @ref Cell range. Every cell has to return the right value when using @ref Cell::get_row_index and,
* if @ref PersistenceMatrixOptions::is_z2 is false, also when using
* @ref Cell_field_element::get_element "Cell::get_element".
* @return Reference to this column.
*/
template <class Cell_range>
Expand All @@ -380,37 +390,39 @@ class PersistenceMatrixColumn :
PersistenceMatrixColumn& operator*=(const Field_element_type& val);

/**
* @brief @p this = @p val * @p this + @p column
* @brief `this = val * this + column`
*
* @tparam Cell_range @ref Cell range with `begin` and `end` method.
* @tparam Cell_range @ref Cell range with %begin() and %end() method.
* @param val Value to multiply.
* @param column @ref Cell range. Every cell has to return the right value when using `get_row_index` and,
* if @ref PersistenceMatrixOptions::is_z2 is false, also when using `get_element`.
* @param column @ref Cell range. Every cell has to return the right value when using @ref Cell::get_row_index and,
* if @ref PersistenceMatrixOptions::is_z2 is false, also when using
* @ref Cell_field_element::get_element "Cell::get_element".
* @return Reference to this column.
*/
template <class Cell_range>
PersistenceMatrixColumn& multiply_and_add(const Field_element_type& val, const Cell_range& column);
/**
* @brief @p this = @p val * @p this + @p column
* @brief `this = val * this + column`
*
* @param val Value to multiply.
* @param column Column to add.
* @return Reference to this column.
*/
PersistenceMatrixColumn& multiply_and_add(const Field_element_type& val, PersistenceMatrixColumn& column);
/**
* @brief @p this = @p this + @p column * @p val
* @brief `this = this + column * val`
*
* @tparam Cell_range @ref Cell range with `begin` and `end` method.
* @param column @ref Cell range. Every cell has to return the right value when using `get_row_index` and,
* if @ref PersistenceMatrixOptions::is_z2 is false, also when using `get_element`.
* @tparam Cell_range @ref Cell range with %begin() and %end() method.
* @param column @ref Cell range. Every cell has to return the right value when using @ref Cell::get_row_index and,
* if @ref PersistenceMatrixOptions::is_z2 is false, also when using
* @ref Cell_field_element::get_element "Cell::get_element".
* @param val Value to multiply.
* @return Reference to this column.
*/
template <class Cell_range>
PersistenceMatrixColumn& multiply_and_add(const Cell_range& column, const Field_element_type& val);
/**
* @brief @p this = @p this + @p column * @p val
* @brief `this = this + column * val`
*
* @param column Column to add.
* @param val Value to multiply.
Expand Down
Loading

0 comments on commit cf41344

Please sign in to comment.