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

Classes
struct	Bar
	Type for a bar in the computed barcode. Stores the birth, death and dimension of the bar. More...

struct	RowCellComp
	Compaires two cells by their position in the row. They are assume to be in the same row. More...

Public Types
using	index = typename PersistenceMatrixOptions::index_type

using	id_index = typename PersistenceMatrixOptions::index_type

using	pos_index = typename PersistenceMatrixOptions::index_type

using	dimension_type = typename PersistenceMatrixOptions::dimension_type

using	Field_operators = typename std::conditional< PersistenceMatrixOptions::is_z2, Gudhi::persistence_fields::Z2_field_operators, typename PersistenceMatrixOptions::Field_coeff_operators >::type
	Coefficiants field type.

using	element_type = typename Field_operators::element_type
	Type of a field element.

using	Cell_type = Cell< Matrix< PersistenceMatrixOptions > >
	Type of a matrix cell. See Cell for a more detailed description.

using	Cell_constructor = Pool_cell_constructor< Cell_type >
	Cell constructor/destructor used by the matrix. Uses a pool of cells to accelerate memory management, as cells are constructed and destroyed a lot during reduction, swaps or additions.

using	cell_rep_type = typename std::conditional< PersistenceMatrixOptions::is_z2, id_index, std::pair< id_index, element_type > >::type
	Type used to identify a cell, for exemple when inserting a boundary. If PersistenceMatrixOptions::is_z2 is true, the type is an IDIdx and corresponds to the row index of the cell (the cell value is assumed to be 1). If PersistenceMatrixOptions::is_z2 is false, the type is a pair whose first element is the row index of the cell and the second element is the value of the cell (which again is assumed to be non-zero). The column index of the row is always deduced from the context in which the type is used.

using	Row_type = typename std::conditional< PersistenceMatrixOptions::has_intrusive_rows, boost::intrusive::list< Cell_type, boost::intrusive::constant_time_size< false >, boost::intrusive::base_hook< base_hook_matrix_row > >, std::set< Cell_type, RowCellComp > >::type
	Type of the rows stored in the matrix. Is either an intrusive list of Cell_type (not ordered) if PersistenceMatrixOptions::has_intrusive_rows is true, or a set of Cell_type (ordered by get_column_index) otherwise.

using	Column_type = typename std::conditional< PersistenceMatrixOptions::column_type==Column_types::HEAP, Heap_column_type, typename std::conditional< PersistenceMatrixOptions::column_type==Column_types::LIST, List_column_type, typename std::conditional< PersistenceMatrixOptions::column_type==Column_types::SET, Set_column_type, typename std::conditional< PersistenceMatrixOptions::column_type==Column_types::UNORDERED_SET, Unordered_set_column_type, typename std::conditional< PersistenceMatrixOptions::column_type==Column_types::VECTOR, Vector_column_type, typename std::conditional< PersistenceMatrixOptions::column_type==Column_types::INTRUSIVE_LIST, Intrusive_list_column_type, typename std::conditional< PersistenceMatrixOptions::column_type==Column_types::NAIVE_VECTOR, Naive_vector_column_type, Intrusive_set_column_type >::type >::type >::type >::type >::type >::type >::type
	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 = typename std::conditional< hasFixedBarcode, std::vector< Bar >, typename std::conditional< PersistenceMatrixOptions::has_removable_columns, std::list< Bar >, std::vector< Bar > >::type >::type
	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_type = 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_type = boundary_type>
	Matrix (const std::vector< Container_type > &columns, characteristic_type characteristic=11)
	Constructs a new matrix from the given ranges of cell_rep_type. Each range corresponds to a column (the order of the ranges are preserved). The content of the ranges is assumed to be sorted by increasing IDs. If the columns are representing a boundary matrix, the IDs of the simplices are also assumed to be consecutifs, ordered by filtration value, starting with 0. More...

	Matrix (int numberOfColumns, characteristic_type characteristic=static_cast< characteristic_type >(-1))
	Constructs a new empty matrix and reserves space for the given number of columns. More...

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

template<class Boundary_type = boundary_type>
	Matrix (const std::vector< Boundary_type > &orderedBoundaries, const std::function< bool(pos_index, pos_index)> &birthComparator, const std::function< bool(pos_index, pos_index)> &deathComparator, characteristic_type characteristic=11)
	Constructs a new matrix from the given ranges with the given comparator functions. Only available when those comparators are necessary. More...

	Matrix (unsigned int numberOfColumns, const std::function< bool(pos_index, pos_index)> &birthComparator, const std::function< bool(pos_index, pos_index)> &deathComparator, characteristic_type characteristic=static_cast< characteristic_type >(-1))
	Constructs a new empty matrix and reserves space for the given number of columns. Only available when those comparators are necessary. More...

	Matrix (const Matrix &matrixToCopy)
	Copy constructor. More...

	Matrix (Matrix &&other) noexcept
	Move constructor. After the move, the given matrix will be empty. More...

void	set_characteristic (characteristic_type 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. More...

template<class Container_type >
void	insert_column (const Container_type &column)
	Inserts a new ordered column at the end of the matrix by copying the given range of cell_rep_type. The content of the range is assumed to be sorted by increasing ID value. More...

template<class Container_type >
void	insert_column (const Container_type &column, index columnIndex)
	Inserts a new ordered column at the given index by copying the given range of cell_rep_type. There should not be any other column inserted at that index which was not explicitely removed before. The content of the range is assumed to be sorted by increasing ID value. More...

template<class Boundary_type = boundary_type>
insertion_return_type	insert_boundary (const Boundary_type &boundary, dimension_type dim=-1)
	Inserts at the end of the matrix a new ordered column corresponding to the given boundary. This means that it is assumed that this method is called on boundaries in the order of the filtration. It also assumes that the faces in the given boundary are identified by their relative position in the filtration, starting at 0. If it is not the case, use the other insert_boundary instead by indicating the face ID used in the boundaries when the face is inserted. More...

template<class Boundary_type >
insertion_return_type	insert_boundary (id_index faceIndex, const Boundary_type &boundary, dimension_type dim=-1)
	Only avalaible for non-basic matrices. It does the same as the other version, but allows the boundary faces to be identified without restrictions except that all IDs have to be strictly increasing in the order of filtration. Note that you should avoid then to use the other insertion method to avoid overwriting IDs. More...

returned_column_type &	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 choosen options, see PersistenceMatrixOptions::column_type. More...

const Column_type &	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 choosen options, see PersistenceMatrixOptions::column_type. More...

const Column_type &	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 choosen options, see PersistenceMatrixOptions::column_type. More...

returned_row_type &	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 choosen options, see PersistenceMatrixOptions::has_intrusive_rows. More...

const Row_type &	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 choosen options, see PersistenceMatrixOptions::has_intrusive_rows. More...

const Row_type &	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 choosen options, see PersistenceMatrixOptions::has_intrusive_rows. More...

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 cells are also automatically removed from their respective rows. More...

void	erase_empty_row (id_index rowIndex)
	The effect varies depending on the matrices and the options: More...

void	remove_maximal_face (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 face is maximal in the current complex and removes it such that the matrix remains consistent (i.e., RU is still an upper triangular decomposition of the boundary matrix and chain is still a compatible bases of the chain complex in the sense of [41]). The maximality of the face is not verified. Also updates the barcode if it was computed. More...

void	remove_maximal_face (id_index faceIndex, 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 face is maximal in the current complex and removes it such that the matrix remains consistent (i.e., it is still a compatible bases of the chain complex in the sense of [41]). The maximality of the face is not verified. Also updates the barcode if it was computed. More...

void	remove_last ()
	Removes the last inserted column/face from the matrix. If the matrix is non basic, PersistenceMatrixOptions::has_removable_columns has to be true for the method to be available. Additionnaly, 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. More...

dimension_type	get_max_dimension () const
	Returns the maximal dimension of a face stored in the matrix. Only available for non-basic matrices and if PersistenceMatrixOptions::has_matrix_maximal_dimension_access is true. More...

index	get_number_of_columns () const
	Returns the current number of columns in the matrix. More...

dimension_type	get_column_dimension (index columnIndex) const
	Returns the dimension of the given face. Only available for non-basic matrices. More...

template<typename Index_type >
std::enable_if_t< std::is_integral_v< Index_type > >	add_to (Index_type sourceColumnIndex, Index_type 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. More...

template<class Cell_range >
std::enable_if_t<!std::is_integral_v< Cell_range > >	add_to (const Cell_range &sourceColumn, index targetColumnIndex)
	Adds the given range of Cell onto the column at `targetColumnIndex` in the matrix. Only available for basic matrices. More...

template<typename Index_type >
std::enable_if_t< std::is_integral_v< Index_type > >	multiply_target_and_add_to (Index_type sourceColumnIndex, int coefficient, Index_type 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. More...

template<class Cell_range >
std::enable_if_t<!std::is_integral_v< Cell_range > >	multiply_target_and_add_to (const Cell_range &sourceColumn, int coefficient, index targetColumnIndex)
	Multiplies the target column with the coefficient and then adds the given range of Cell to it. That is: `targetColumn = (targetColumn * coefficient) + sourceColumn`. Only available for basic matrices. More...

template<typename Index_type >
std::enable_if_t< std::is_integral_v< Index_type > >	multiply_source_and_add_to (int coefficient, Index_type sourceColumnIndex, Index_type 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. More...

template<class Cell_range >
std::enable_if_t<!std::is_integral_v< Cell_range > >	multiply_source_and_add_to (int coefficient, const Cell_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. More...

void	zero_cell (index columnIndex, id_index rowIndex)
	Zeroes the cell at the given coordinates. Not available for chain matrices and for base matrices with column compression. In general, should be used with care with non-basic matrices to not destroy the validity of the persistence related properties of the matrix. More...

void	zero_cell (index columnIndex, id_index rowIndex, bool inR)
	Only available for RU matrices. Zeroes the cell 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. More...

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

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

bool	is_zero_cell (index columnIndex, id_index rowIndex)
	Indicates if the cell at given coordinates has value zero. More...

bool	is_zero_cell (index columnIndex, id_index rowIndex, bool inR) const
	Only available for RU matrices. Indicates if the cell at given coordinates has value zero in \( R \) if `inR` is true or in \( U \) if `inR` is false. More...

bool	is_zero_column (index columnIndex)
	Indicates if the column at given index has value zero. More...

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

index	get_column_with_pivot (id_index faceIndex) 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 \). More...

id_index	get_pivot (index columnIndex)
	Returns the row index of the pivot of the given column. Only available for non-basic matrices. More...

Matrix &	operator= (Matrix other)
	Assign operator. More...

const barcode_type &	get_current_barcode ()
	Returns the current barcode of the matrix. Available only if PersistenceMatrixOptions::has_column_pairings is true. More...

const barcode_type &	get_current_barcode () const
	Returns the current barcode of the matrix. Available only if PersistenceMatrixOptions::has_column_pairings is true. More...

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

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

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

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

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 faces which are consecutives 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 faces at position `index` and `index + 1` swapped. Of course, the two faces should not have a face/coface relation which each other ; \( F' \) has to be a valid filtration. See [21] for more information about vine and vineyards. More...

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 faces which are consecutives 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 faces at swapped positions. Of course, the two faces should not have a face/coface relation which each other ; \( F' \) has to be a valid filtration. See [21] for more information about vine and vineyards. More...

void	update_representative_cycles ()
	Only available if PersistenceMatrixOptions::can_retrieve_representative_cycles is true. Precomputes the representative cycles of the current state of the filtration represented by the matrix. It does not need to be called before 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_type > &	get_representative_cycles ()
	Only available if PersistenceMatrixOptions::can_retrieve_representative_cycles is true. Returns all representative cycles of the current filtration. More...

const cycle_type &	get_representative_cycle (const Bar &bar)
	Only available if PersistenceMatrixOptions::can_retrieve_representative_cycles is true. Returns the cycle representing the given bar. More...

Static Public Attributes
static New_cell_constructor< Cell_type >	defaultCellConstructor
	Default cell 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 futur when parallel options are implemented, as usual pools are not thread safe.

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

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 choosen 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 [41]). 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/face, so in order to avoid repeating formulations like "of the simplex associated to the column" all the time, we will amalgamate both notions together.

Let \( c \) be a column.

MatIdx: This will correspond to the position of \( c \) in the matrix, i.e., \( underlying\_container[MatIdx] = c \). This will be the only public indexing scheme for basic matrices.
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 choosen 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 originaly also be indexed by the ID, but when a swap occurs, the rows also swap IDs and the new ID has to be used to access \( r \). This means that when the default IDIdx scheme is used (the faces are numerated in order of appearence 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: representative_cycles_from_matrix.cpp, and simplex_tree_to_matrix.cpp.

Member Typedef Documentation

◆ dimension_type

template<class PersistenceMatrixOptions = Default_options<>>

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

Type for dimension value.

◆ id_index

template<class PersistenceMatrixOptions = Default_options<>>

using Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::id_index = typename PersistenceMatrixOptions::index_type

Type of IDIdx index.

◆ index

template<class PersistenceMatrixOptions = Default_options<>>

using Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::index = typename PersistenceMatrixOptions::index_type

Type of MatIdx index.

◆ pos_index

template<class PersistenceMatrixOptions = Default_options<>>

using Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::pos_index = typename PersistenceMatrixOptions::index_type

Type of PosIdx index.

Constructor & Destructor Documentation

◆ Matrix() [1/7]

template<class PersistenceMatrixOptions >

template<class Container_type >

Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::Matrix	(	const std::vector< Container_type > &	columns,
		characteristic_type	characteristic = `11`
	)

inline

Constructs a new matrix from the given ranges of cell_rep_type. Each range corresponds to a column (the order of the ranges are preserved). The content of the ranges is assumed to be sorted by increasing IDs. If the columns are representing a boundary matrix, the IDs of the simplices are also assumed to be consecutifs, ordered by filtration value, starting with 0.

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

Template Parameters

Container_type Range type for cell_rep_type 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 consecutifs 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(int numberOfColumns, characteristic_type 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	(	int	numberOfColumns,
		characteristic_type	characteristic = `static_cast<characteristic_type>(-1)`
	)

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 necesseray 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 [41] for example.)

Parameters

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

◆ Matrix() [4/7]

template<class PersistenceMatrixOptions >

template<class Boundary_type >

Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::Matrix	(	const std::vector< Boundary_type > &	orderedBoundaries,
		const std::function< bool(pos_index, pos_index)> &	birthComparator,
		const std::function< bool(pos_index, pos_index)> &	deathComparator,
		characteristic_type	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_type>& columns, characteristic_type 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_type Range type for cell_rep_type ranges. Assumed to have a begin(), end() and size() method.

Parameters

orderedBoundaries	Vector of ordered boundaries in filtration order. Indexed continously starting at 0.
birthComparator	Method taking two PosIdx indices as parameter and returns true if and only if the first face is associated to a bar with strictly smaller birth than the bar associated to the second one.
deathComparator	Method taking two PosIdx indices as parameter and returns true if and only if the first face is associated to a bar with strictly smaller death than the bar associated to the second one.
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_type	characteristic = `static_cast<characteristic_type>(-1)`
	)

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 face 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 face 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 )

inlinenoexcept

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

std::enable_if_t<!std::is_integral_v< Cell_range > > Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::add_to	(	const Cell_range &	sourceColumn,
		index	targetColumnIndex
	)

inline

Adds the given range of Cell 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

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

Parameters

sourceColumn	Source Cell range.
targetColumnIndex	MatIdx index of the target column.

◆ add_to() [2/2]

template<class PersistenceMatrixOptions >

template<typename Index_type >

std::enable_if_t< std::is_integral_v< Index_type > > Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::add_to	(	Index_type	sourceColumnIndex,
		Index_type	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

Index_type 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 cells are not removed from their columns. And in the case of intrusive rows, this will generate a segmentation fault when the column cells are destroyed later. The row access is just meant as a "read only" access to the rows and the erase_empty_row method just as a way to specify that a row is empty and can therefore be removed from dictionnaries. This allows to avoid testing the emptiness of a row at each column cell removal, what can be quite frequent.

Parameters

rowIndex Row index of the empty row to remove.

◆ get_column() [1/3]

template<class PersistenceMatrixOptions >

Matrix< PersistenceMatrixOptions >::returned_column_type & 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 choosen 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: simplex_tree_to_matrix.cpp.

◆ get_column() [2/3]

template<class PersistenceMatrixOptions >

const Matrix< PersistenceMatrixOptions >::Column_type & 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 choosen 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_type & 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 choosen 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_type Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::get_column_dimension ( index columnIndex ) const

inline

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

Parameters

columnIndex MatIdx index of the column representing the face.

Returns: Dimension of the face.

◆ get_column_with_pivot()

template<class PersistenceMatrixOptions >

Matrix< PersistenceMatrixOptions >::index Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::get_column_with_pivot ( id_index faceIndex ) 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

faceIndex 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_type & 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 informations: 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_type & 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 const reference to the barcode. The barcode is a vector of Matrix::Bar. A bar stores three informations: the PosIdx birth index, the PosIdx death index and the dimension of the bar.

◆ get_max_dimension()

template<class PersistenceMatrixOptions >

Matrix< PersistenceMatrixOptions >::dimension_type Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::get_max_dimension

inline

Returns the maximal dimension of a face 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

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

◆ get_row() [1/3]

template<class PersistenceMatrixOptions >

Matrix< PersistenceMatrixOptions >::returned_row_type & 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 choosen 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 occured.

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

◆ get_row() [2/3]

template<class PersistenceMatrixOptions >

const Matrix< PersistenceMatrixOptions >::Row_type & 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 choosen 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 occured.

Returns: Const reference to the row.

◆ get_row() [3/3]

template<class PersistenceMatrixOptions >

const Matrix< PersistenceMatrixOptions >::Row_type & 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 choosen options, see PersistenceMatrixOptions::has_intrusive_rows.

Parameters

rowIndex	Row index of the row to return: updated IDIdx if swaps occured.
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_type >

Matrix< PersistenceMatrixOptions >::insertion_return_type Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::insert_boundary	(	const Boundary_type &	boundary,
		dimension_type	dim = `-1`
	)

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 faces in the given boundary are identified by their relative position in the filtration, starting at 0. If it is not the case, use the other insert_boundary instead by indicating the face ID used in the boundaries when the face is inserted.

Different to the constructor, the boundaries do not have to come from a simplicial complex, but also from a more general cell complex. This includes cubical complexes or Morse complexes for example.

The content of the new column will vary depending on the underlying type of the matrix:

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 optimisations 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_type Range of cell_rep_type. 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 face whose boundary is given. If the complex is simplicial, this parameter can be omitted as it can be deduced from the size of the boundary.

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: simplex_tree_to_matrix.cpp.

◆ insert_boundary() [2/2]

template<class PersistenceMatrixOptions >

template<class Boundary_type >

Matrix< PersistenceMatrixOptions >::insertion_return_type Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::insert_boundary	(	id_index	faceIndex,
		const Boundary_type &	boundary,
		dimension_type	dim = `-1`
	)

inline

Only avalaible for non-basic matrices. It does the same as the other version, but allows the boundary faces to be identified without restrictions except that all IDs have to be strictly increasing in the order of filtration. Note that you should avoid then to use the other insertion method to avoid overwriting IDs.

As a face has to be inserted before one of its cofaces in a valid filtration (recall that it is assumed that for non-basic matrices, the faces are inserted by order of filtration), it is sufficient to indicate the ID of the face being inserted.

Template Parameters

Boundary_type Range of cell_rep_type. Assumed to have a begin(), end() and size() method.

Parameters

faceIndex	IDIdx index to use to indentify the new face.
boundary	Boundary generating the new column. The indices of the boundary have to correspond to the `faceIndex` values of precedent calls of the method for the corresponding faces and should be ordered in increasing order.
dim	Dimension of the face whose boundary is given. If the complex is simplicial, this parameter can be omitted as it can be deduced from the size of the boundary.

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

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

inline

Inserts a new ordered column at the end of the matrix by copying the given range of cell_rep_type. 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_type Range of cell_rep_type. 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_type >

void Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::insert_column	(	const Container_type &	column,
		index	columnIndex
	)

inline

Inserts a new ordered column at the given index by copying the given range of cell_rep_type. There should not be any other column inserted at that index which was not explicitely removed before. The content of the range is assumed to be sorted by increasing ID value.

Only available for base matrices without column compression and without row access.

Template Parameters

Container_type Range of cell_rep_type. 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_cell() [1/2]

template<class PersistenceMatrixOptions >

bool Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::is_zero_cell	(	index	columnIndex,
		id_index	rowIndex
	)

inline

Indicates if the cell at given coordinates has value zero.

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

Parameters

columnIndex	MatIdx index of the column of the cell.
rowIndex	Row index of the row of the cell.

Returns: true If the cell has value zero.; false Otherwise.

◆ is_zero_cell() [2/2]

template<class PersistenceMatrixOptions >

bool Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::is_zero_cell	(	index	columnIndex,
		id_index	rowIndex,
		bool	inR
	)		const

inline

Only available for RU matrices. Indicates if the cell 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 cell.
rowIndex	Row index of the row of the cell.
inR	Boolean indicating in which matrix to look: if true in \( R \) and if false in \( U \).

Returns: true If the cell has value zero.; false Otherwise.

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

◆ multiply_source_and_add_to() [1/2]

template<class PersistenceMatrixOptions >

template<class Cell_range >

std::enable_if_t<!std::is_integral_v< Cell_range > > Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::multiply_source_and_add_to	(	int	coefficient,
		const Cell_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

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

Parameters

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

◆ multiply_source_and_add_to() [2/2]

template<class PersistenceMatrixOptions >

template<typename Index_type >

std::enable_if_t< std::is_integral_v< Index_type > > Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::multiply_source_and_add_to	(	int	coefficient,
		Index_type	sourceColumnIndex,
		Index_type	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

Index_type 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 Cell_range >

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

inline

Multiplies the target column with the coefficient and then adds the given range of Cell 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

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

Parameters

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

◆ multiply_target_and_add_to() [2/2]

template<class PersistenceMatrixOptions >

template<typename Index_type >

std::enable_if_t< std::is_integral_v< Index_type > > Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::multiply_target_and_add_to	(	Index_type	sourceColumnIndex,
		int	coefficient,
		Index_type	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

Index_type 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 cells 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/face from the matrix. If the matrix is non basic, PersistenceMatrixOptions::has_removable_columns has to be true for the method to be available. Additionnaly, 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_face and remove_column.

For chain matrices, if PersistenceMatrixOptions::has_vine_update is true, the last face does not have to be at the end of the matrix and therefore has to be searched first. In this case, if the user already knows the IDIdx of the last face, calling remove_maximal_face(faceID, {}) instead allows to skip the search.

◆ remove_maximal_face() [1/2]

template<class PersistenceMatrixOptions >

void Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::remove_maximal_face	(	id_index	faceIndex,
		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 face is maximal in the current complex and removes it such that the matrix remains consistent (i.e., it is still a compatible bases of the chain complex in the sense of [41]). The maximality of the face is not verified. Also updates the barcode if it was computed.

To maintain the compatibility, vine swaps are done to move the face up to the end of the filtration. Once at the end, the removal is trivial. But for chain matrices, swaps do not actually swap the position of the column every time, so the faces appearing after faceIndex in the filtration have to be searched first within the matrix. If the user has an easy access to the IDIdx of the faces in the order of filtration, passing them by argument with columnsToSwap allows to skip a linear search process. Typically, if the user knows that the face he wants to remove is already the last face of the filtration, calling remove_maximal_face(faceID, {}) will be faster than remove_last().

◆ remove_maximal_face() [2/2]

template<class PersistenceMatrixOptions >

void Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::remove_maximal_face ( 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 face is maximal in the current complex and removes it such that the matrix remains consistent (i.e., RU is still an upper triangular decomposition of the boundary matrix and chain is still a compatible bases of the chain complex in the sense of [41]). The maximality of the face is not verified. Also updates the barcode if it was computed.

For chain matrices, using the other version of the method could perform better depending on how the data is maintained on the side of the user. Then, PersistenceMatrixOptions::has_column_pairings also do not need to be true.

◆ set_characteristic()

template<class PersistenceMatrixOptions >

void Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::set_characteristic ( characteristic_type 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 cell 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 faces which are consecutives 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 faces at swapped positions. Of course, the two faces should not have a face/coface relation which each other ; \( F' \) has to be a valid filtration. See [21] for more information about vine and vineyards.

Parameters

columnIndex1	MatIdx index of the first face.
columnIndex2	MatIdx index of the second face. 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 faces which are consecutives 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 faces at position index and index + 1 swapped. Of course, the two faces should not have a face/coface relation which each other ; \( F' \) has to be a valid filtration. See [21] for more information about vine and vineyards.

Parameters

index PosIdx index of the first face 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 face.
columnIndex2	MatIdx index of the second face. 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 bounary 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 face 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_cell() [1/2]

template<class PersistenceMatrixOptions >

void Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::zero_cell	(	index	columnIndex,
		id_index	rowIndex
	)

inline

Zeroes the cell at the given coordinates. Not available for chain matrices and for base matrices with column compression. In general, should be used with care with non-basic matrices to not destroy the validity of the persistence related properties of the matrix.

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

Parameters

columnIndex	MatIdx index of the column of the cell.
rowIndex	Row index of the row of the cell.

◆ zero_cell() [2/2]

template<class PersistenceMatrixOptions >

void Gudhi::persistence_matrix::Matrix< PersistenceMatrixOptions >::zero_cell	(	index	columnIndex,
		id_index	rowIndex,
		bool	inR
	)

inline

Only available for RU matrices. Zeroes the cell 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 cell.
rowIndex	Row index of the row of the cell.
inR	Boolean indicating in which matrix to zero: if true in \( R \) and if false in \( U \).

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

Friends And Related Function 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

faceIndex	IDIdx index of the face to remove
columnsToSwap	Vector of IDIdx indices of the faces coming after `faceIndex` in the filtration.

Classes

Public Types

Public Member Functions

Static Public Attributes

Friends

Detailed Description

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

Member Typedef Documentation

◆ dimension_type

◆ id_index

◆ index

◆ pos_index

Constructor & Destructor Documentation

◆ Matrix() [1/7]

◆ Matrix() [2/7]

◆ Matrix() [3/7]

◆ Matrix() [4/7]

◆ Matrix() [5/7]

◆ Matrix() [6/7]

◆ Matrix() [7/7]

Member Function Documentation

◆ add_to() [1/2]

◆ add_to() [2/2]

◆ erase_empty_row()

◆ get_column() [1/3]

◆ get_column() [2/3]

◆ get_column() [3/3]

◆ get_column_dimension()

◆ get_column_with_pivot()

◆ get_current_barcode() [1/2]

◆ get_current_barcode() [2/2]

◆ get_max_dimension()

◆ get_number_of_columns()

◆ get_pivot()

◆ get_representative_cycle()

◆ get_representative_cycles()

◆ get_row() [1/3]

◆ get_row() [2/3]

◆ get_row() [3/3]

◆ insert_boundary() [1/2]

◆ insert_boundary() [2/2]

◆ insert_column() [1/2]

◆ insert_column() [2/2]

◆ is_zero_cell() [1/2]

◆ is_zero_cell() [2/2]

◆ is_zero_column() [1/2]

◆ is_zero_column() [2/2]

◆ multiply_source_and_add_to() [1/2]

◆ multiply_source_and_add_to() [2/2]

◆ multiply_target_and_add_to() [1/2]

◆ multiply_target_and_add_to() [2/2]

◆ operator=()

◆ remove_column()

◆ remove_last()

◆ remove_maximal_face() [1/2]

◆ remove_maximal_face() [2/2]

◆ set_characteristic()

◆ swap_columns()

◆ swap_rows()

◆ vine_swap() [1/2]

◆ vine_swap() [2/2]

◆ vine_swap_with_z_eq_1_case() [1/2]

◆ vine_swap_with_z_eq_1_case() [2/2]

◆ zero_cell() [1/2]

◆ zero_cell() [2/2]

◆ zero_column() [1/2]

◆ zero_column() [2/2]

Friends And Related Function Documentation

◆ swap

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