Loading...
Searching...
No Matches
Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions > Class Template Reference
Persistence Matrix

Data structure for matrices, and in particular thought for matrices representing filtered complexes in order to compute persistence and/or representative cycles. More...

`#include <gudhi/matrix.h>`

## Classes

struct | RowEntryComp
| Compares two entries by their position in the row. They are assume to be in the same row. More...

## Public Types

using | Index = typename PersistenceMatrixOptions::Index
using | ID_index = typename PersistenceMatrixOptions::Index
using | Pos_index = typename PersistenceMatrixOptions::Index
using | Dimension = typename PersistenceMatrixOptions::Dimension
using | Field_operators
| coefficients field type.
using | Element = typename Field_operators::Element
| Type of a field element.
using | Bar = Persistence_interval<Dimension, Pos_index>
| Type for a bar in the computed barcode. Stores the birth, death and dimension of the bar.
using | Matrix_entry = Entry<Matrix<PersistenceMatrixOptions> >
| Type of a matrix entry. See Entry for a more detailed description.
using | Entry_constructor = Pool_entry_constructor<Matrix_entry>
| Entry constructor/destructor used by the matrix. Uses a pool of entries to accelerate memory management, as entries are constructed and destroyed a lot during reduction, swaps or additions.
using | Entry_representative

Type used to identify an entry, for example when inserting a boundary. If PersistenceMatrixOptions::is_z2 is true, the type is an IDIdx and corresponds to the row index of the entry (the entry value is assumed to be 1). If PersistenceMatrixOptions::is_z2 is false, the type is a pair whose first element is the row index of the entry and the second element is the value of the entry (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 | Row
| Type of the rows stored in the matrix. Is either an intrusive list of Matrix_entry (not ordered) if PersistenceMatrixOptions::has_intrusive_rows is true, or a set of Matrix_entry (ordered by column index) otherwise.
using | Column
| Type of the columns stored in the matrix. The type depends on the value of PersistenceMatrixOptions::column_type defined in the given options. See Column_types for a more detailed description. All columns follow the PersistenceMatrixColumn concept.
using | Barcode
| Type of the computed barcode. It is either a list of Matrix::Bar or a vector of Matrix::Bar, depending if bars need to be removed from the container as some point or not.
using | Cycle = std::vector<ID_index>
| Type of a representative cycle. Vector of row indices.

## Public Member Functions

| Matrix ()
| Default constructor. Initializes an empty matrix.
template<class Container = Boundary>
| Matrix (const std::vector< Container > &columns, Characteristic characteristic=11)
| Constructs a new matrix from the given ranges of Entry_representative. 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. If the columns are representing a boundary matrix, the IDs of the simplices are also assumed to be consecutive, ordered by filtration value, starting with 0.
| Matrix (unsigned int numberOfColumns, Characteristic characteristic=Matrix::get_null_value< Characteristic >())
| Constructs a new empty matrix and reserves space for the given number of columns.
| Matrix (const std::function< bool(Pos_index, Pos_index)> &birthComparator, const std::function< bool(Pos_index, Pos_index)> &deathComparator)
| Constructs a new empty matrix with the given comparator functions. Only available when those comparators are necessary.
template<class Boundary_range = Boundary>
| Matrix (const std::vector< Boundary_range > &orderedBoundaries, const std::function< bool(Pos_index, Pos_index)> &birthComparator, const std::function< bool(Pos_index, Pos_index)> &deathComparator, Characteristic characteristic=11)
| Constructs a new matrix from the given ranges with the given comparator functions. Only available when those comparators are necessary.
| Matrix (unsigned int numberOfColumns, const std::function< bool(Pos_index, Pos_index)> &birthComparator, const std::function< bool(Pos_index, Pos_index)> &deathComparator, Characteristic characteristic=Matrix::get_null_value< Characteristic >())
| Constructs a new empty matrix and reserves space for the given number of columns. Only available when those comparators are necessary.
| Matrix (const Matrix &matrixToCopy)
| Copy constructor.
| Matrix (Matrix &&other) noexcept
| Move constructor. After the move, the given matrix will be empty.
void | set_characteristic (Characteristic characteristic)
| Sets the characteristic of the coefficient field if 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.
template<class Container>
void | insert_column (const Container &column)
| Inserts a new ordered column at the end of the matrix by copying the given range of Entry_representative. The content of the range is assumed to be sorted by increasing ID value.
template<class Container>
void | insert_column (const Container &column, Index columnIndex)
| Inserts a new ordered column at the given index by copying the given range of Entry_representative. There should not be any other column inserted at that index which was not explicitly removed before. The content of the range is assumed to be sorted by increasing ID value.
template<class Boundary_range = Boundary>
Insertion_return | insert_boundary (const Boundary_range &boundary, Dimension dim=Matrix::get_null_value< Dimension >())

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 cells 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 cell ID used in the boundaries when the cell is inserted.

template<class Boundary_range = Boundary>
Insertion_return | insert_boundary (ID_index cellIndex, const Boundary_range &boundary, Dimension dim=Matrix::get_null_value< Dimension >())
| Only available for non-basic matrices. It does the same as the other version, but allows the boundary cells 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.
Returned_column & | get_column (Index columnIndex)
| Returns the column at the given MatIdx index. For RU matrices, is equivalent to get_column(columnIndex, true). The type of the column depends on the chosen options, see PersistenceMatrixOptions::column_type.
const Column & | get_column (Index columnIndex) const
| Only available for chain matrices. Returns the column at the given MatIdx index. The type of the column depends on the chosen options, see PersistenceMatrixOptions::column_type.
const Column & | get_column (Index columnIndex, bool inR)
| Only available for RU matrices without Column_indexation_types::IDENTIFIER indexing. Returns the column at the given MatIdx index in \( R \) if `inR` is true and in \( U \) if `inR` is false. The type of the column depends on the chosen options, see PersistenceMatrixOptions::column_type.
Returned_row & | get_row (ID_index rowIndex)
| Only available if PersistenceMatrixOptions::has_row_access is true. Returns the row at the given row index. For RU matrices, is equivalent to get_row(columnIndex, true). The type of the row depends on the chosen options, see PersistenceMatrixOptions::has_intrusive_rows.
const Row & | get_row (ID_index rowIndex) const
| Only available for chain matrices and matrices with column compression. Returns the row at the given row index. The type of the row depends on the chosen options, see PersistenceMatrixOptions::has_intrusive_rows.
const Row & | get_row (ID_index rowIndex, bool inR)
| Only available for RU matrices without Column_indexation_types::IDENTIFIER indexing. Returns the row at the given row index in \( R \) if `inR` is true and in \( U \) if `inR` is false. The type of the row depends on the chosen options, see PersistenceMatrixOptions::has_intrusive_rows.
void | remove_column (Index columnIndex)
| Only available for base matrices without column compression and if PersistenceMatrixOptions::has_map_column_container is true. Otherwise, see remove_last. Erases the given column from the matrix. If PersistenceMatrixOptions::has_row_access is also true, the deleted column entries are also automatically removed from their respective rows.
void | erase_empty_row (ID_index rowIndex)
| The effect varies depending on the matrices and the options:
void | remove_maximal_cell (Index columnIndex)

Only available for RU and chain matrices and if PersistenceMatrixOptions::has_removable_columns and PersistenceMatrixOptions::has_vine_update are true. For chain matrices, PersistenceMatrixOptions::has_map_column_container and PersistenceMatrixOptions::has_column_pairings also need to be true. Assumes that the cell 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 [zigzag]). The maximality of the cell is not verified. Also updates the barcode if it was computed.

void | remove_maximal_cell (ID_index cellIndex, const std::vector< ID_index > &columnsToSwap)

Only available for chain matrices and if PersistenceMatrixOptions::has_removable_columns, PersistenceMatrixOptions::has_vine_update and PersistenceMatrixOptions::has_map_column_container are true. Assumes that the cell 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 [zigzag]). The maximality of the cell is not verified. Also updates the barcode if it was computed.

void | remove_last ()

Removes the last inserted column/cell from the matrix. If the matrix is non basic, PersistenceMatrixOptions::has_removable_columns has to be true for the method to be available. Additionally, if the matrix is a chain matrix, either PersistenceMatrixOptions::has_map_column_container has to be true or PersistenceMatrixOptions::has_vine_update has to be false. And if the matrix is a base matrix it should be without column compression.

Dimension | get_max_dimension () const
| Returns the maximal dimension of a cell stored in the matrix. Only available for non-basic matrices and if PersistenceMatrixOptions::has_matrix_maximal_dimension_access is true.
Index | get_number_of_columns () const
| Returns the current number of columns in the matrix.
Dimension | get_column_dimension (Index columnIndex) const
| Returns the dimension of the given cell. Only available for non-basic matrices.
template<typename Integer_index>
std::enable_if_t< std::is_integral_v< Integer_index > > | add_to (Integer_index sourceColumnIndex, Integer_index targetColumnIndex)

Adds column at `sourceColumnIndex` onto the column at `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.

template<class Entry_range>
std::enable_if_t<!std::is_integral_v< Entry_range > > | add_to (const Entry_range &sourceColumn, Index targetColumnIndex)
| Adds the given range of Entry onto the column at `targetColumnIndex` in the matrix. Only available for basic matrices.
template<typename Integer_index>
std::enable_if_t< std::is_integral_v< Integer_index > > | multiply_target_and_add_to (Integer_index sourceColumnIndex, int coefficient, Integer_index targetColumnIndex)

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 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.

template<class Entry_range>
std::enable_if_t<!std::is_integral_v< Entry_range > > | multiply_target_and_add_to (const Entry_range &sourceColumn, int coefficient, Index targetColumnIndex)
| Multiplies the target column with the coefficient and then adds the given range of Entry to it. That is: targetColumn = (targetColumn * coefficient) + sourceColumn. Only available for basic matrices.
template<typename Integer_index>
std::enable_if_t< std::is_integral_v< Integer_index > > | multiply_source_and_add_to (int coefficient, Integer_index sourceColumnIndex, Integer_index targetColumnIndex)

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 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.

template<class Entry_range>
std::enable_if_t<!std::is_integral_v< Entry_range > > | multiply_source_and_add_to (int coefficient, const Entry_range &sourceColumn, Index targetColumnIndex)
| 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 basic matrices.
void | zero_entry (Index columnIndex, ID_index rowIndex)
| Zeroes the entry 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.
void | zero_entry (Index columnIndex, ID_index rowIndex, bool inR)
| Only available for RU matrices. Zeroes the entry at the given coordinates in \( R \) if `inR` is true or in \( U \) if `inR` is false. Should be used with care to not destroy the validity of the persistence related properties of the matrix.
void | zero_column (Index columnIndex)
| 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.
void | zero_column (Index columnIndex, bool inR)
| Only available for RU matrices. Zeroes the column at the given index in \( R \) if `inR` is true or in \( U \) if `inR` is false. Should be used with care to not destroy the validity of the persistence related properties of the matrix.
bool | is_zero_entry (Index columnIndex, ID_index rowIndex)
| Indicates if the entry at given coordinates has value zero.
bool | is_zero_entry (Index columnIndex, ID_index rowIndex, bool inR) const
| Only available for RU matrices. Indicates if the entry at given coordinates has value zero in \( R \) if `inR` is true or in \( U \) if `inR` is false.
bool | is_zero_column (Index columnIndex)
| Indicates if the column at given index has value zero.
bool | is_zero_column (Index columnIndex, bool inR)
| Only available for RU matrices. Indicates if the column at given index has value zero in \( R \) if `inR` is true or in \( U \) if `inR` is false.
Index | get_column_with_pivot (ID_index cellIndex) const
| 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 \).
ID_index | get_pivot (Index columnIndex)
| Returns the row index of the pivot of the given column. Only available for non-basic matrices.
Matrix & | operator= (Matrix other)
| Assign operator.
const Barcode & | get_current_barcode ()
| Returns the current barcode of the matrix. Available only if PersistenceMatrixOptions::has_column_pairings is true.
const Barcode & | get_current_barcode () const
| Returns the current barcode of the matrix. Available only if PersistenceMatrixOptions::has_column_pairings is true.
void | swap_columns (Index columnIndex1, Index columnIndex2)
| Only available for base matrices without column compression and simple boundary matrices (only storing \( R \)) and if PersistenceMatrixOptions::has_column_and_row_swaps is true. Swaps the two given columns. Note for 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.
void | swap_rows (Index rowIndex1, Index rowIndex2)
| Only available for base matrices without column compression and simple boundary matrices (only storing \( R \)) and if PersistenceMatrixOptions::has_column_and_row_swaps is true. Swaps the two given rows. Note for 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.
bool | vine_swap_with_z_eq_1_case (Pos_index index)
| Only available if PersistenceMatrixOptions::has_vine_update is true and if it is either a boundary matrix or PersistenceMatrixOptions::column_indexation_type is set to Column_indexation_types::POSITION. Does the same than vine_swap, but assumes that the swap is non trivial and therefore skips a part of the case study.
Index | vine_swap_with_z_eq_1_case (Index columnIndex1, Index columnIndex2)
| Only available if PersistenceMatrixOptions::has_vine_update is true and if it is either a chain matrix or PersistenceMatrixOptions::column_indexation_type is set to Column_indexation_types::IDENTIFIER. Does the same than vine_swap, but assumes that the swap is non-trivial and therefore skips a part of the case study.
bool | vine_swap (Pos_index index)

Only available if PersistenceMatrixOptions::has_vine_update is true and if it is either a boundary matrix or PersistenceMatrixOptions::column_indexation_type is set to Column_indexation_types::POSITION. Does a vine swap between two cells which are consecutive in the filtration. Roughly, if \( 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' \) equal to \( F \) but with the two cells at position index and index + 1 swapped. Of course, the two cells should not have a face/coface relation which each other ; \( F' \) has to be a valid filtration. See [vineyards] for more information about vine and vineyards.

Index | vine_swap (Index columnIndex1, Index columnIndex2)

Only available if PersistenceMatrixOptions::has_vine_update is true and if it is either a chain matrix or PersistenceMatrixOptions::column_indexation_type is set to Column_indexation_types::IDENTIFIER. Does a vine swap between two cells which are consecutive in the filtration. Roughly, if \( 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' \) equal to \( F \) but with the two given cells at swapped positions. Of course, the two cells should not have a face/coface relation which each other ; \( F' \) has to be a valid filtration. See [vineyards] for more information about vine and vineyards.

void | update_representative_cycles ()

Only available if PersistenceMatrixOptions::can_retrieve_representative_cycles is true. Pre-computes 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.

const std::vector< Cycle > & | get_representative_cycles ()
| Only available if PersistenceMatrixOptions::can_retrieve_representative_cycles is true. Returns all representative cycles of the current filtration.
const Cycle & | get_representative_cycle (const Bar &bar)
| Only available if PersistenceMatrixOptions::can_retrieve_representative_cycles is true. Returns the cycle representing the given bar.

## Static Public Member Functions

template<typename T>
static constexpr const T | get_null_value ()
| Returns value from a type when not set.

## Static Public Attributes

static New_entry_constructor< Matrix_entry > | defaultEntryConstructor
| Default entry constructor/destructor, using classic new and delete. For now, only used as default value for columns constructed independently outside of the matrix by the user. Could be used in the future when parallel options are implemented, as usual pools are not thread safe.

## Friends

void | swap (Matrix &matrix1, Matrix &matrix2)
| Swap operator for two matrices.

## Detailed Description

template<class PersistenceMatrixOptions = Default_options<>>
class Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >

Data structure for matrices, and in particular thought for matrices representing filtered complexes in order to compute persistence and/or representative cycles.

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 chosen by default when none of the homology related options are set to true: PersistenceMatrixOptions::has_column_pairings, PersistenceMatrixOptions::has_vine_update and PersistenceMatrixOptions::can_retrieve_representative_cycles.
- a boundary matrix \( B = R \cdot U \) which either stores only \( R \) or the whole decomposition \( R \) and \( U \) depending on the options. This type is selected if PersistenceMatrixOptions::is_of_boundary_type is set to true and at least one of the following options: PersistenceMatrixOptions::has_column_pairings, PersistenceMatrixOptions::has_vine_update and PersistenceMatrixOptions::can_retrieve_representative_cycles. If only PersistenceMatrixOptions::has_column_pairings is true, then only \( R \) is stored, but if either PersistenceMatrixOptions::has_vine_update or PersistenceMatrixOptions::can_retrieve_representative_cycles is true, then \( U \) also needs to be stored. Note that the option PersistenceMatrixOptions::column_indexation_type will produce a small overhead when set to Column_indexation_types::IDENTIFIER.
- a chain complex matrix representing a "compatible base" of a filtered chain complex (see [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 PersistenceMatrixOptions::is_of_boundary_type has to be set to false. Note that the option PersistenceMatrixOptions::column_indexation_type will produce a small overhead when set to Column_indexation_types::POSITION or Column_indexation_types::IDENTIFIER.

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/cell, 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.
- 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 when swaps or removals were performed.
- 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 \( n^{th} \) 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 chosen with the only restriction that they have to be strictly increasing in the order of the filtration at initialisation.

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 originally 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 cells are numerated in order of appearance in the filtration starting at 0), the indexation of the rows correspond to PosIdx.

Template Parameters

  PersistenceMatrixOptions | Structure encoding all the options of the matrix. See description of PersistenceMatrixOptions for more details.

Examples
  example_representative_cycles_from_matrix.cpp, and example_simplex_tree_to_matrix.cpp.

## Member Typedef Documentation

## Dimension

template<class PersistenceMatrixOptions = Default_options<>>

using Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::Dimension = typename PersistenceMatrixOptions::Dimension

Type for dimension value.

## ID_index

template<class PersistenceMatrixOptions = Default_options<>>

using Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::ID_index = typename PersistenceMatrixOptions::Index

Type of IDIdx index.

## Index

template<class PersistenceMatrixOptions = Default_options<>>

using Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::Index = typename PersistenceMatrixOptions::Index

Type of MatIdx index.

## Pos_index

template<class PersistenceMatrixOptions = Default_options<>>

using Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::Pos_index = typename PersistenceMatrixOptions::Index

Type of PosIdx index.

## Constructor & Destructor Documentation

## Matrix() [1/7]

template<class PersistenceMatrixOptions>
template<class Container>

Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::Matrix | ( | const std::vector< Container > & | columns,
|  | Characteristic | characteristic = 11 )

inline

Constructs a new matrix from the given ranges of Entry_representative. 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. If the columns are representing a boundary matrix, the IDs of the simplices are also assumed to be consecutive, ordered by filtration value, starting with 0.

See matrix descriptions for further details on how the given matrix is handled.

Template Parameters

  Container | Range type for Entry_representative ranges. Assumed to have a begin(), end() and size() method.

Parameters

  columns

  For a base matrix, the columns are copied as is. If options related to homology are activated, `columns` is interpreted as a boundary matrix of a simplicial complex. In this case, columns[i] should store the boundary of simplex i as an ordered list of indices of its facets (again those indices correspond to their respective position in the matrix). Therefore the indices of the simplices are assumed to be consecutive and starting with 0 (an empty boundary is interpreted as a vertex boundary and not as a non existing simplex). All dimensions up to the maximal dimension of interest have to be present. If only a higher dimension is of interest and not everything should be stored, then use the insert_boundary method instead (after creating the matrix with the Matrix(unsigned int numberOfColumns, Characteristic characteristic) constructor preferably). If the persistence barcode has to be computed from this matrix, the simplices are also assumed to be ordered by appearance order in the filtration. Also, depending of the options, the matrix is eventually reduced on the fly or converted into a chain complex base, so the new matrix is not always identical to the old one.

  characteristic | Characteristic of the coefficient field. Has to be specified if PersistenceMatrixOptions::is_z2 is false. Default value is 11. Ignored if PersistenceMatrixOptions::is_z2 is true.

## Matrix() [2/7]

template<class PersistenceMatrixOptions>

Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::Matrix | ( | unsigned int | numberOfColumns,
|  | Characteristic | characteristic = Matrix< PersistenceMatrixOptions >::get_null_value<Characteristic>() )

inline

Constructs a new empty matrix and reserves space for the given number of columns.

Parameters

  numberOfColumns | Number of columns to reserve space for.
  characteristic | Characteristic of the coefficient field. If not specified and PersistenceMatrixOptions::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 PersistenceMatrixOptions::is_z2 is true.

## Matrix() [3/7]

template<class PersistenceMatrixOptions>

Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::Matrix | ( | const std::function< bool(Pos_index, Pos_index)> & | birthComparator,
|  | const std::function< bool(Pos_index, Pos_index)> & | deathComparator )

inline

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:

- PersistenceMatrixOptions::is_of_boundary_type = false
- PersistenceMatrixOptions::has_vine_update = true
- PersistenceMatrixOptions::has_column_pairings = false

Those comparators are necessary to distinguish cases in a vine update. When the matrix is of 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 [zigzag] for example.)

Parameters

  birthComparator | Method taking two PosIdx indices as parameter and returns true if and only if the first cell is associated to a bar with strictly smaller birth than the bar associated to the second one.
  deathComparator | Method taking two PosIdx indices as parameter and returns true if and only if the first cell is associated to a bar with strictly smaller death than the bar associated to the second one.

## Matrix() [4/7]

template<class PersistenceMatrixOptions>
template<class Boundary_range>

Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::Matrix | ( | const std::vector< Boundary_range > & | orderedBoundaries,
|  | const std::function< bool(Pos_index, Pos_index)> & | birthComparator,
|  | const std::function< bool(Pos_index, Pos_index)> & | deathComparator,
|  | Characteristic | characteristic = 11 )

inline

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:

- PersistenceMatrixOptions::is_of_boundary_type = false
- PersistenceMatrixOptions::has_vine_update = true
- PersistenceMatrixOptions::has_column_pairings = false

See description of Matrix(const std::vector<Container>& columns, Characteristic characteristic) for more information about `orderedBoundaries` and Matrix(const std::function<bool(Pos_index,Pos_index)>&, const std::function<bool(Pos_index,Pos_index)>&) for more information about the comparators.

Template Parameters

  Boundary_range | Range type for Entry_representative ranges. Assumed to have a begin(), end() and size() method.

Parameters

  orderedBoundaries | Vector of ordered boundaries in filtration order. Indexed continuously starting at 0.
  birthComparator | Method taking two PosIdx indices as parameter and returns true if and only if the first cell is associated to a bar with strictly smaller birth than the bar associated to the second one.
  deathComparator | Method taking two PosIdx indices as parameter and returns true if and only if the first cell is associated to a bar with strictly smaller death than the bar associated to the second one.
  characteristic | Characteristic of the coefficient field. Has to be specified if PersistenceMatrixOptions::is_z2 is false. Default value is 11. Ignored if PersistenceMatrixOptions::is_z2 is true.

## Matrix() [5/7]

template<class PersistenceMatrixOptions>

Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::Matrix | ( | unsigned int | numberOfColumns,
|  | const std::function< bool(Pos_index, Pos_index)> & | birthComparator,
|  | const std::function< bool(Pos_index, Pos_index)> & | deathComparator,
|  | Characteristic | characteristic = Matrix< PersistenceMatrixOptions >::get_null_value<Characteristic>() )

inline

Constructs a new empty matrix and reserves space for the given number of columns. Only available when those comparators are necessary.

That is, when all following options have following values:

- PersistenceMatrixOptions::is_of_boundary_type = false
- PersistenceMatrixOptions::has_vine_update = true
- PersistenceMatrixOptions::has_column_pairings = false

See description of Matrix(const std::function<bool(Pos_index,Pos_index)>&, const std::function<bool(Pos_index,Pos_index)>&) for more information about the comparators.

Parameters

  numberOfColumns | Number of columns to reserve space for.
  birthComparator | Method taking two PosIdx indices as parameter and returns true if and only if the first cell is associated to a bar with strictly smaller birth than the bar associated to the second one.
  deathComparator | Method taking two PosIdx indices as parameter and returns true if and only if the first cell is associated to a bar with strictly smaller death than the bar associated to the second one.
  characteristic | Characteristic of the coefficient field. If not specified and PersistenceMatrixOptions::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 PersistenceMatrixOptions::is_z2 is true.

## Matrix() [6/7]

template<class PersistenceMatrixOptions>

Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::Matrix | ( | const Matrix< PersistenceMatrixOptions > & | matrixToCopy | ) |

inline

Copy constructor.

Parameters

  matrixToCopy | Matrix to copy.

## Matrix() [7/7]

template<class PersistenceMatrixOptions>

Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::Matrix | ( | Matrix< PersistenceMatrixOptions > && | other | ) |

inline noexcept

Move constructor. After the move, the given matrix will be empty.

Parameters

  other | Matrix to move.

## Member Function Documentation

## add_to() [1/2]

template<class PersistenceMatrixOptions>
template<class Entry_range>

std::enable_if_t<!std::is_integral_v< Entry_range > > Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::add_to | ( | const Entry_range & | sourceColumn,
|  | Index | targetColumnIndex )

inline

Adds the given range of Entry onto the column at `targetColumnIndex` in the matrix. Only available for 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.

Template Parameters

  Entry_range | Range of Entry. Needs a begin() and end() method. A column index does not need to be stored in the entries, even if PersistenceMatrixOptions::has_row_access is true.

Parameters

  sourceColumn | Source Entry range.
  targetColumnIndex | MatIdx index of the target column.

## add_to() [2/2]

template<class PersistenceMatrixOptions>
template<typename Integer_index>

std::enable_if_t< std::is_integral_v< Integer_index > > Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::add_to | ( | Integer_index | sourceColumnIndex,
|  | Integer_index | targetColumnIndex )

inline

Adds column at `sourceColumnIndex` onto the column at `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 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.

Template Parameters

  Integer_index | Any signed or unsigned integer type.

Parameters

  sourceColumnIndex | MatIdx index of the column to add.
  targetColumnIndex | MatIdx index of the target column.

## erase_empty_row()

template<class PersistenceMatrixOptions>

void Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::erase_empty_row | ( | ID_index | rowIndex | ) |

inline

The effect varies depending on the matrices and the options:

- base matrix and boundary matrix:
  - PersistenceMatrixOptions::has_map_column_container and PersistenceMatrixOptions::has_column_and_row_swaps are true: cleans up maps used for the lazy row swaps.
  - PersistenceMatrixOptions::has_row_access and 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 PersistenceMatrixOptions::has_row_access and 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 entries are not removed from their columns. And in the case of intrusive rows, this will generate a segmentation fault when the column entries are destroyed later. The row access is just meant as a "read only" access to the rows and the erase_empty_row method just as a way to specify that a row is empty and can therefore be removed from dictionaries. This allows to avoid testing the emptiness of a row at each column entry removal, what can be quite frequent.

Parameters

  rowIndex | Row index of the empty row to remove.

## get_column() [1/3]

template<class PersistenceMatrixOptions>

Matrix< PersistenceMatrixOptions >::Returned_column & Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::get_column | ( | Index | columnIndex | ) |

inline

Returns the column at the given MatIdx index. For RU matrices, is equivalent to get_column(columnIndex, true). The type of the column depends on the chosen options, see PersistenceMatrixOptions::column_type.

Parameters

  columnIndex | MatIdx index of the column to return.

Returns
  Reference to the column. Is const if the matrix has column compression.

Examples
  example_simplex_tree_to_matrix.cpp.

## get_column() [2/3]

template<class PersistenceMatrixOptions>

const Matrix< PersistenceMatrixOptions >::Column & Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::get_column | ( | Index | columnIndex | ) | const

inline

Only available for chain matrices. Returns the column at the given MatIdx index. The type of the column depends on the chosen options, see PersistenceMatrixOptions::column_type.

Parameters

  columnIndex | MatIdx index of the column to return.

Returns
  Const reference to the column.

## get_column() [3/3]

template<class PersistenceMatrixOptions>

const Matrix< PersistenceMatrixOptions >::Column & Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::get_column | ( | Index | columnIndex,
|  | bool | inR )

inline

Only available for RU matrices without Column_indexation_types::IDENTIFIER indexing. Returns the column at the given MatIdx index in \( R \) if `inR` is true and in \( U \) if `inR` is false. The type of the column depends on the chosen options, see PersistenceMatrixOptions::column_type.

Parameters

  columnIndex | MatIdx index of the column to return.
  inR | If true, returns the column in \( R \), if false, returns the column in \( U \).

Returns
  Const reference to the column.

## get_column_dimension()

template<class PersistenceMatrixOptions>

Matrix< PersistenceMatrixOptions >::Dimension Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::get_column_dimension | ( | Index | columnIndex | ) | const

inline

Returns the dimension of the given cell. Only available for non-basic matrices.

Parameters

  columnIndex | MatIdx index of the column representing the cell.

Returns
  Dimension of the cell.

## get_column_with_pivot()

template<class PersistenceMatrixOptions>

Matrix< PersistenceMatrixOptions >::Index Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::get_column_with_pivot | ( | ID_index | cellIndex | ) | const

inline

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 \).

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.

Parameters

  cellIndex | Row index of the pivot.

Returns
  MatIdx index of the column with the given pivot.

## get_current_barcode() [1/2]

template<class PersistenceMatrixOptions>

const Matrix< PersistenceMatrixOptions >::Barcode & Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::get_current_barcode | ( |  | ) |

inline

Returns the current barcode of the matrix. Available only if 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 the matrix is completed and won't be modified again.

Returns
  A reference to the barcode. The barcode is a vector of Matrix::Bar. A bar stores three information: the PosIdx birth index, the PosIdx death index and the dimension of the bar.

## get_current_barcode() [2/2]

template<class PersistenceMatrixOptions>

const Matrix< PersistenceMatrixOptions >::Barcode & Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::get_current_barcode | ( |  | ) | const

inline

Returns the current barcode of the matrix. Available only if 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 the matrix is completed and won't be modified again.

Returns
  A const reference to the barcode. The barcode is a vector of Matrix::Bar. A bar stores three information: the PosIdx birth index, the PosIdx death index and the dimension of the bar.

## get_max_dimension()

template<class PersistenceMatrixOptions>

Matrix< PersistenceMatrixOptions >::Dimension Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::get_max_dimension | ( |  | ) | const

inline

Returns the maximal dimension of a cell stored in the matrix. Only available for non-basic matrices and if PersistenceMatrixOptions::has_matrix_maximal_dimension_access is true.

Returns
  The maximal dimension.

## get_number_of_columns()

template<class PersistenceMatrixOptions>

Matrix< PersistenceMatrixOptions >::Index Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::get_number_of_columns | ( |  | ) | const

inline

Returns the current number of columns in the matrix.

Returns
  The number of columns.

## get_pivot()

template<class PersistenceMatrixOptions>

Matrix< PersistenceMatrixOptions >::ID_index Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::get_pivot | ( | Index | columnIndex | ) |

inline

Returns the row index of the pivot of the given column. Only available for non-basic matrices.

Parameters

  columnIndex | MatIdx index of the column

Returns
  The row index of the pivot.

## get_representative_cycle()

template<class PersistenceMatrixOptions>

const Matrix< PersistenceMatrixOptions >::Cycle & Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::get_representative_cycle | ( | const Bar & | bar | ) |

inline

Only available if PersistenceMatrixOptions::can_retrieve_representative_cycles is true. Returns the cycle representing the given bar.

Parameters

  bar | A bar from the current barcode.

Returns
  A const reference to the cycle representing `bar`.

## get_representative_cycles()

template<class PersistenceMatrixOptions>

const std::vector< typename Matrix< PersistenceMatrixOptions >::Cycle > & Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::get_representative_cycles | ( |  | ) |

inline

Only available if PersistenceMatrixOptions::can_retrieve_representative_cycles is true. Returns all representative cycles of the current filtration.

Returns
  A const reference to the vector of representative cycles.

Examples
  example_representative_cycles_from_matrix.cpp.

## get_row() [1/3]

template<class PersistenceMatrixOptions>

Matrix< PersistenceMatrixOptions >::Returned_row & Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::get_row | ( | ID_index | rowIndex | ) |

inline

Only available if PersistenceMatrixOptions::has_row_access is true. Returns the row at the given row index. For RU matrices, is equivalent to get_row(columnIndex, true). The type of the row depends on the chosen options, see PersistenceMatrixOptions::has_intrusive_rows.

Parameters

  rowIndex | Row index of the row to return: IDIdx for chain matrices or updated IDIdx for boundary matrices if swaps occurred.

Returns
  Reference to the row. Is const if the matrix has column compression.

## get_row() [2/3]

template<class PersistenceMatrixOptions>

const Matrix< PersistenceMatrixOptions >::Row & Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::get_row | ( | ID_index | rowIndex | ) | const

inline

Only available for chain matrices and matrices with column compression. Returns the row at the given row index. The type of the row depends on the chosen options, see PersistenceMatrixOptions::has_intrusive_rows.

Parameters

  rowIndex | Row index of the row to return: IDIdx for chain matrices or updated IDIdx for boundary matrices if swaps occurred.

Returns
  Const reference to the row.

## get_row() [3/3]

template<class PersistenceMatrixOptions>

const Matrix< PersistenceMatrixOptions >::Row & Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::get_row | ( | ID_index | rowIndex,
|  | bool | inR )

inline

Only available for RU matrices without Column_indexation_types::IDENTIFIER indexing. Returns the row at the given row index in \( R \) if `inR` is true and in \( U \) if `inR` is false. The type of the row depends on the chosen options, see PersistenceMatrixOptions::has_intrusive_rows.

Parameters

  rowIndex | Row index of the row to return: updated IDIdx if swaps occurred.
  inR | If true, returns the row in \( R \), if false, returns the row in \( U \).

Returns
  Const reference to the row.

## insert_boundary() [1/2]

template<class PersistenceMatrixOptions>
template<class Boundary_range>

Matrix< PersistenceMatrixOptions >::Insertion_return Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::insert_boundary | ( | const Boundary_range & | boundary,
|  | Dimension | dim = Matrix< PersistenceMatrixOptions >::get_null_value<Dimension>() )

inline

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 cells 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 cell ID used in the boundaries when the cell is inserted.

Different to the constructor, the boundaries do not have to come from a simplicial complex, but also from a more general entry 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:

- If it is a basic matrix type, the boundary is copied as it is, i.e., the method is equivalent to 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 optimizations with the additional knowledge. Hence, the barcode will also not be updated, so call 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.

Template Parameters

  Boundary_range | Range of Entry_representative. Assumed to have a begin(), end() and size() method.

Parameters

  boundary | Boundary generating the new column. The content should be ordered by ID.
  dim | Dimension of the cell 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.

Returns
  If it is a chain matrix, the method returns the MatIdx indices of the unpaired chains used to reduce the boundary. Otherwise, nothing.

Examples
  example_simplex_tree_to_matrix.cpp.

## insert_boundary() [2/2]

template<class PersistenceMatrixOptions>
template<class Boundary_range>

Matrix< PersistenceMatrixOptions >::Insertion_return Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::insert_boundary | ( | ID_index | cellIndex,
|  | const Boundary_range & | boundary,
|  | Dimension | dim = Matrix< PersistenceMatrixOptions >::get_null_value<Dimension>() )

inline

Only available for non-basic matrices. It does the same as the other version, but allows the boundary cells 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 cell has to be inserted before one of its cofaces in a valid filtration (recall that it is assumed that for non-basic matrices, the cells are inserted by order of filtration), it is sufficient to indicate the ID of the cell being inserted.

Template Parameters

  Boundary_range | Range of Entry_representative. Assumed to have a begin(), end() and size() method.

Parameters

  cellIndex | IDIdx index to use to identify the new cell.
  boundary | Boundary generating the new column. The indices of the boundary have to correspond to the `cellIndex` values of precedent calls of the method for the corresponding cells and should be ordered in increasing order.
  dim | Dimension of the cell 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.

Returns
  If it is a chain matrix, the method returns the MatIdx indices of the unpaired chains used to reduce the boundary. Otherwise, nothing.

## insert_column() [1/2]

template<class PersistenceMatrixOptions>
template<class Container>

void Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::insert_column | ( | const Container & | column | ) |

inline

Inserts a new ordered column at the end of the matrix by copying the given range of Entry_representative. The content of the range is assumed to be sorted by increasing ID value.

Only available for base matrices. Otherwise use insert_boundary which will deduce a new column from the boundary given.

Template Parameters

  Container | Range of Entry_representative. Assumed to have a begin(), end() and size() method.

Parameters

  column | Column to be inserted.

## insert_column() [2/2]

template<class PersistenceMatrixOptions>
template<class Container>

void Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::insert_column | ( | const Container & | column,
|  | Index | columnIndex )

inline

Inserts a new ordered column at the given index by copying the given range of Entry_representative. There should not be any other column inserted at that index which was not explicitly 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.

Template Parameters

  Container | Range of Entry_representative. Assumed to have a begin(), end() and size() method.

Parameters

  column | Column to be inserted.
  columnIndex | MatIdx index to which the column has to be inserted.

## is_zero_column() [1/2]

template<class PersistenceMatrixOptions>

bool Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::is_zero_column | ( | Index | columnIndex | ) |

inline

Indicates if the column at given index has value zero.

For RU matrices, equivalent to 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.

Parameters

  columnIndex | MatIdx index of the column.

Returns
  true If the column has value zero.
  false Otherwise.

## is_zero_column() [2/2]

template<class PersistenceMatrixOptions>

bool Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::is_zero_column | ( | Index | columnIndex,
|  | bool | inR )

inline

Only available for RU matrices. Indicates if the column at given index has value zero in \( R \) if `inR` is true or in \( U \) if `inR` is false.

Note that if `inR` is false, this method should usually return false.

Parameters

  columnIndex | MatIdx index of the column.
  inR | Boolean indicating in which matrix to look: if true in \( R \) and if false in \( U \).

Returns
  true If the column has value zero.
  false Otherwise.

## is_zero_entry() [1/2]

template<class PersistenceMatrixOptions>

bool Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::is_zero_entry | ( | Index | columnIndex,
|  | ID_index | rowIndex )

inline

Indicates if the entry at given coordinates has value zero.

For RU matrices, equivalent to is_zero_entry(columnIndex, rowIndex, true).

Parameters

  columnIndex | MatIdx index of the column of the entry.
  rowIndex | Row index of the row of the entry.

Returns
  true If the entry has value zero.
  false Otherwise.

## is_zero_entry() [2/2]

template<class PersistenceMatrixOptions>

bool Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::is_zero_entry | ( | Index | columnIndex,
|  | ID_index | rowIndex,
|  | bool | inR ) const

inline

Only available for RU matrices. Indicates if the entry at given coordinates has value zero in \( R \) if `inR` is true or in \( U \) if `inR` is false.

Parameters

  columnIndex | MatIdx index of the column of the entry.
  rowIndex | Row index of the row of the entry.
  inR | Boolean indicating in which matrix to look: if true in \( R \) and if false in \( U \).

Returns
  true If the entry has value zero.
  false Otherwise.

## multiply_source_and_add_to() [1/2]

template<class PersistenceMatrixOptions>
template<class Entry_range>

std::enable_if_t<!std::is_integral_v< Entry_range > > Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::multiply_source_and_add_to | ( | int | coefficient,
|  | const Entry_range & | sourceColumn,
|  | Index | targetColumnIndex )

inline

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 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.

Template Parameters

  Entry_range | Range of Entry. Needs a begin() and end() method. A column index does not need to be stored in the entries, even if PersistenceMatrixOptions::has_row_access is true.

Parameters

  coefficient | Value to multiply.
  sourceColumn | Source Entry range.
  targetColumnIndex | MatIdx index of the target column.

## multiply_source_and_add_to() [2/2]

template<class PersistenceMatrixOptions>
template<typename Integer_index>

std::enable_if_t< std::is_integral_v< Integer_index > > Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::multiply_source_and_add_to | ( | int | coefficient,
|  | Integer_index | sourceColumnIndex,
|  | Integer_index | targetColumnIndex )

inline

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 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.

Template Parameters

  Integer_index | Any signed or unsigned integer type.

Parameters

  coefficient | Value to multiply.
  sourceColumnIndex | MatIdx index of the column to add.
  targetColumnIndex | MatIdx index of the target column.

## multiply_target_and_add_to() [1/2]

template<class PersistenceMatrixOptions>
template<class Entry_range>

std::enable_if_t<!std::is_integral_v< Entry_range > > Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::multiply_target_and_add_to | ( | const Entry_range & | sourceColumn,
|  | int | coefficient,
|  | Index | targetColumnIndex )

inline

Multiplies the target column with the coefficient and then adds the given range of Entry to it. That is: targetColumn = (targetColumn * coefficient) + sourceColumn. Only available for 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.

Template Parameters

  Entry_range | Range of Entry. Needs a begin() and end() method. A column index does not need to be stored in the entries, even if PersistenceMatrixOptions::has_row_access is true.

Parameters

  sourceColumn | Source Entry range.
  coefficient | Value to multiply.
  targetColumnIndex | MatIdx index of the target column.

## multiply_target_and_add_to() [2/2]

template<class PersistenceMatrixOptions>
template<typename Integer_index>

std::enable_if_t< std::is_integral_v< Integer_index > > Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::multiply_target_and_add_to | ( | Integer_index | sourceColumnIndex,
|  | int | coefficient,
|  | Integer_index | targetColumnIndex )

inline

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 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.

Template Parameters

  Integer_index | Any signed or unsigned integer type.

Parameters

  sourceColumnIndex | MatIdx index of the column to add.
  coefficient | Value to multiply.
  targetColumnIndex | MatIdx index of the target column.

## operator=()

template<class PersistenceMatrixOptions>

Matrix< PersistenceMatrixOptions > & Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::operator= | ( | Matrix< PersistenceMatrixOptions > | other | ) |

inline

Assign operator.

Parameters

  other | Matrix to copy

Returns
  Reference to this object.

## remove_column()

template<class PersistenceMatrixOptions>

void Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::remove_column | ( | Index | columnIndex | ) |

inline

Only available for base matrices without column compression and if PersistenceMatrixOptions::has_map_column_container is true. Otherwise, see remove_last. Erases the given column from the matrix. If PersistenceMatrixOptions::has_row_access is also true, the deleted column entries are also automatically removed from their respective rows.

Parameters

  columnIndex | MatIdx index of the column to remove.

## remove_last()

template<class PersistenceMatrixOptions>

void Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::remove_last | ( |  | ) |

inline

Removes the last inserted column/cell from the matrix. If the matrix is non basic, PersistenceMatrixOptions::has_removable_columns has to be true for the method to be available. Additionally, if the matrix is a chain matrix, either PersistenceMatrixOptions::has_map_column_container has to be true or PersistenceMatrixOptions::has_vine_update has to be false. And if the matrix is a base matrix it should be without column compression.

See also remove_maximal_cell and remove_column.

For chain matrices, if PersistenceMatrixOptions::has_vine_update is true, the last cell 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 cell, calling remove_maximal_cell(cellID, {}) instead allows to skip the search.

## remove_maximal_cell() [1/2]

template<class PersistenceMatrixOptions>

void Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::remove_maximal_cell | ( | ID_index | cellIndex,
|  | const std::vector< ID_index > & | columnsToSwap )

inline

Only available for chain matrices and if PersistenceMatrixOptions::has_removable_columns, PersistenceMatrixOptions::has_vine_update and PersistenceMatrixOptions::has_map_column_container are true. Assumes that the cell 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 [zigzag]). The maximality of the cell is not verified. Also updates the barcode if it was computed.

To maintain the compatibility, vine swaps are done to move the cell 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 cells appearing after `cellIndex` in the filtration have to be searched first within the matrix. If the user has an easy access to the IDIdx of the cells in the order of filtration, passing them by argument with `columnsToSwap` allows to skip a linear search process. Typically, if the user knows that the cell he wants to remove is already the last cell of the filtration, calling remove_maximal_cell(cellID, {}) will be faster than remove_last().

See also remove_last.

Parameters

  cellIndex | IDIdx index of the cell to remove
  columnsToSwap | Vector of IDIdx indices of the cells coming after `cellIndex` in the filtration.

## remove_maximal_cell() [2/2]

template<class PersistenceMatrixOptions>

void Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::remove_maximal_cell | ( | Index | columnIndex | ) |

inline

Only available for RU and chain matrices and if PersistenceMatrixOptions::has_removable_columns and PersistenceMatrixOptions::has_vine_update are true. For chain matrices, PersistenceMatrixOptions::has_map_column_container and PersistenceMatrixOptions::has_column_pairings also need to be true. Assumes that the cell 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 [zigzag]). The maximality of the cell 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, PersistenceMatrixOptions::has_column_pairings also do not need to be true.

See also remove_last and remove_column.

Parameters

  columnIndex | If boundary matrix, MatIdx index of the cell to remove, otherwise the IDIdx index.

## set_characteristic()

template<class PersistenceMatrixOptions>

void Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::set_characteristic | ( | Characteristic | characteristic | ) |

inline

Sets the characteristic of the coefficient field if 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.

Warning
  The coefficient values stored in the matrix are stored after computing the corresponding modulo. Therefore, changing the characteristic after is very likely to invalidate all entry values.

Parameters

  characteristic | The characteristic to set.

## swap_columns()

template<class PersistenceMatrixOptions>

void Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::swap_columns | ( | Index | columnIndex1,
|  | Index | columnIndex2 )

inline

Only available for base matrices without column compression and simple boundary matrices (only storing \( R \)) and if PersistenceMatrixOptions::has_column_and_row_swaps is true. Swaps the two given columns. Note for 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.

Parameters

  columnIndex1 | First column MatIdx index to swap.
  columnIndex2 | Second column MatIdx index to swap.

## swap_rows()

template<class PersistenceMatrixOptions>

void Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::swap_rows | ( | Index | rowIndex1,
|  | Index | rowIndex2 )

inline

Only available for base matrices without column compression and simple boundary matrices (only storing \( R \)) and if PersistenceMatrixOptions::has_column_and_row_swaps is true. Swaps the two given rows. Note for 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.

Parameters

  rowIndex1 | First row index to swap.
  rowIndex2 | Second row index to swap.

## vine_swap() [1/2]

template<class PersistenceMatrixOptions>

Matrix< PersistenceMatrixOptions >::Index Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::vine_swap | ( | Index | columnIndex1,
|  | Index | columnIndex2 )

inline

Only available if PersistenceMatrixOptions::has_vine_update is true and if it is either a chain matrix or PersistenceMatrixOptions::column_indexation_type is set to Column_indexation_types::IDENTIFIER. Does a vine swap between two cells which are consecutive in the filtration. Roughly, if \( 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' \) equal to \( F \) but with the two given cells at swapped positions. Of course, the two cells should not have a face/coface relation which each other ; \( F' \) has to be a valid filtration. See [vineyards] for more information about vine and vineyards.

Parameters

  columnIndex1 | MatIdx index of the first cell.
  columnIndex2 | MatIdx index of the second cell. It is assumed that the PosIdx of both only differs by one.

Returns
  Let \( pos1 \) be the PosIdx index of `columnIndex1` and \( pos2 \) be the PosIdx index of `columnIndex2`. The method returns the MatIdx of the column which has now, after the swap, the PosIdx \( max(pos1, pos2) \).

## vine_swap() [2/2]

template<class PersistenceMatrixOptions>

bool Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::vine_swap | ( | Pos_index | index | ) |

inline

Only available if PersistenceMatrixOptions::has_vine_update is true and if it is either a boundary matrix or PersistenceMatrixOptions::column_indexation_type is set to Column_indexation_types::POSITION. Does a vine swap between two cells which are consecutive in the filtration. Roughly, if \( 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' \) equal to \( F \) but with the two cells at position index and index + 1 swapped. Of course, the two cells should not have a face/coface relation which each other ; \( F' \) has to be a valid filtration. See [vineyards] for more information about vine and vineyards.

Parameters

  index | PosIdx index of the first cell to swap. The second one has to be at index + 1. Recall that for boundary matrices, PosIdx == MatIdx.

Returns
  true If the barcode changed from the swap.
  false Otherwise.

## vine_swap_with_z_eq_1_case() [1/2]

template<class PersistenceMatrixOptions>

Matrix< PersistenceMatrixOptions >::Index Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::vine_swap_with_z_eq_1_case | ( | Index | columnIndex1,
|  | Index | columnIndex2 )

inline

Only available if PersistenceMatrixOptions::has_vine_update is true and if it is either a chain matrix or PersistenceMatrixOptions::column_indexation_type is set to Column_indexation_types::IDENTIFIER. Does the same than vine_swap, but assumes that the swap is non-trivial and therefore skips a part of the case study.

Parameters

  columnIndex1 | MatIdx index of the first cell.
  columnIndex2 | MatIdx index of the second cell. It is assumed that the PosIdx of both only differs by one.

Returns
  Let \( pos1 \) be the PosIdx index of `columnIndex1` and \( pos2 \) be the PosIdx index of `columnIndex2`. The method returns the MatIdx of the column which has now, after the swap, the PosIdx \( max(pos1, pos2) \).

## vine_swap_with_z_eq_1_case() [2/2]

template<class PersistenceMatrixOptions>

bool Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::vine_swap_with_z_eq_1_case | ( | Pos_index | index | ) |

inline

Only available if PersistenceMatrixOptions::has_vine_update is true and if it is either a boundary matrix or PersistenceMatrixOptions::column_indexation_type is set to Column_indexation_types::POSITION. Does the same than vine_swap, but assumes that the swap is non trivial and therefore skips a part of the case study.

Parameters

  index | PosIdx index of the first cell to swap. The second one has to be at index + 1. Recall that for boundary matrices, PosIdx == MatIdx.

Returns
  true If the barcode changed from the swap.
  false Otherwise.

## zero_column() [1/2]

template<class PersistenceMatrixOptions>

void Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::zero_column | ( | Index | columnIndex | ) |

inline

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.

For RU matrices, equivalent to zero_column(columnIndex, true).

Parameters

  columnIndex | MatIdx index of the column to zero.

## zero_column() [2/2]

template<class PersistenceMatrixOptions>

void Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::zero_column | ( | Index | columnIndex,
|  | bool | inR )

inline

Only available for RU matrices. Zeroes the column at the given index in \( R \) if `inR` is true or in \( U \) if `inR` is false. Should be used with care to not destroy the validity of the persistence related properties of the matrix.

Parameters

  columnIndex | MatIdx index of the column to zero.
  inR | Boolean indicating in which matrix to zero: if true in \( R \) and if false in \( U \).

## zero_entry() [1/2]

template<class PersistenceMatrixOptions>

void Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::zero_entry | ( | Index | columnIndex,
|  | ID_index | rowIndex )

inline

Zeroes the entry 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.

For RU matrices, equivalent to zero_entry(columnIndex, rowIndex, true).

Parameters

  columnIndex | MatIdx index of the column of the entry.
  rowIndex | Row index of the row of the entry.

## zero_entry() [2/2]

template<class PersistenceMatrixOptions>

void Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::zero_entry | ( | Index | columnIndex,
|  | ID_index | rowIndex,
|  | bool | inR )

inline

Only available for RU matrices. Zeroes the entry at the given coordinates in \( R \) if `inR` is true or in \( U \) if `inR` is false. Should be used with care to not destroy the validity of the persistence related properties of the matrix.

Parameters

  columnIndex | MatIdx index of the column of the entry.
  rowIndex | Row index of the row of the entry.
  inR | Boolean indicating in which matrix to zero: if true in \( R \) and if false in \( U \).

## Friends And Related Symbol Documentation

## swap

template<class PersistenceMatrixOptions = Default_options<>>

void swap | ( | Matrix< PersistenceMatrixOptions > & | matrix1,
|  | Matrix< PersistenceMatrixOptions > & | matrix2 )

friend

Swap operator for two matrices.

Parameters

  matrix1 | First matrix to swap.
  matrix2 | Second matrix to swap.

The documentation for this class was generated from the following file:

- include/gudhi/Matrix.h