Matrix structure to store the ordered boundary matrix \( R \) of a filtered complex in order to compute its persistent homology. Provides an access to its columns and rows as well as the possibility to remove the last cells of the filtration while maintaining a valid barcode. More...

#include <gudhi/Persistence_matrix/Boundary_matrix.h>

Public Types
using	Index = typename Master_matrix::Index

using	ID_index = typename Master_matrix::ID_index

using	Dimension = typename Master_matrix::Dimension

using	Field_operators = typename Master_matrix::Field_operators
	Field operators class. Necessary only if PersistenceMatrixOptions::is_z2 is false.

using	Field_element = typename Master_matrix::Element

using	Column = typename Master_matrix::Column

using	Boundary = typename Master_matrix::Boundary

using	Row = typename Master_matrix::Row

using	Entry_constructor = typename Master_matrix::Entry_constructor

using	Column_settings = typename Master_matrix::Column_settings

Public Member Functions
	Boundary_matrix (Column_settings *colSettings)
	Constructs an empty matrix. More...

template<class Boundary_range = Boundary>
	Boundary_matrix (const std::vector< Boundary_range > &orderedBoundaries, Column_settings *colSettings)
	Constructs a new matrix from the given ranges of Matrix::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. The IDs of the simplices are also assumed to be consecutive, ordered by filtration value, starting with 0. More...

	Boundary_matrix (unsigned int numberOfColumns, Column_settings *colSettings)
	Constructs a new empty matrix and reserves space for the given number of columns. More...

	Boundary_matrix (const Boundary_matrix &matrixToCopy, Column_settings *colSettings=nullptr)
	Copy constructor. If `colSettings` is not a null pointer, its value is kept instead of the one in the copied matrix. More...

	Boundary_matrix (Boundary_matrix &&other) noexcept
	Move constructor. More...

template<class Boundary_range = Boundary>
Index	insert_boundary (const Boundary_range &boundary, Dimension dim=Master_matrix::template 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. More...

template<class Boundary_range = Boundary>
Index	insert_boundary (ID_index cellIndex, const Boundary_range &boundary, Dimension dim=Master_matrix::template get_null_value< Dimension >())
	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. More...

Column &	get_column (Index columnIndex)
	Returns the column at the given MatIdx index. The type of the column depends on the chosen options, see PersistenceMatrixOptions::column_type. More...

Row &	get_row (Index rowIndex)
	Only available if PersistenceMatrixOptions::has_row_access is true. Returns the row at the given row index of the matrix. The type of the row depends on the chosen options, see PersistenceMatrixOptions::has_intrusive_rows. More...

Index	remove_last ()
	Only available if PersistenceMatrixOptions::has_removable_columns is true. Removes the last cell in the filtration from the matrix and updates the barcode if this one was already computed. More...

void	erase_empty_row (Index rowIndex)
	If PersistenceMatrixOptions::has_row_access and PersistenceMatrixOptions::has_removable_rows are true: assumes that the row is empty and removes it. If PersistenceMatrixOptions::has_map_column_container and PersistenceMatrixOptions::has_column_and_row_swaps are true: cleans up maps used for the lazy row swaps. Otherwise, does nothing. More...

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

Dimension	get_column_dimension (Index columnIndex) const
	Returns the dimension of the given column. More...

void	add_to (Index sourceColumnIndex, Index targetColumnIndex)
	Adds column at `sourceColumnIndex` onto the column at `targetColumnIndex` in the matrix. More...

void	multiply_target_and_add_to (Index sourceColumnIndex, const Field_element &coefficient, Index targetColumnIndex)
	Multiplies the target column with the coefficient and then adds the source column to it. That is: `targetColumn = (targetColumn * coefficient) + sourceColumn`. More...

void	multiply_source_and_add_to (const Field_element &coefficient, Index sourceColumnIndex, 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. More...

void	zero_entry (Index columnIndex, Index rowIndex)
	Zeroes the entry at the given coordinates. More...

void	zero_column (Index columnIndex)
	Zeroes the column at the given index. More...

bool	is_zero_entry (Index columnIndex, Index rowIndex) const
	Indicates if the entry at given coordinates has value zero. More...

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

Index	get_pivot (Index columnIndex)
	Returns the pivot of the given column. More...

void	reset (Column_settings *colSettings)
	Resets the matrix to an empty matrix. More...

Boundary_matrix &	operator= (const Boundary_matrix &other)
	Assign operator.

Friends
void	swap (Boundary_matrix &matrix1, Boundary_matrix &matrix2)
	Swap operator.

Detailed Description

template<class Master_matrix>
class Gudhi::persistence_matrix::Boundary_matrix< Master_matrix >

Matrix structure to store the ordered boundary matrix \( R \) of a filtered complex in order to compute its persistent homology. Provides an access to its columns and rows as well as the possibility to remove the last cells of the filtration while maintaining a valid barcode.

Template Parameters

Master_matrix An instantiation of Matrix from which all types and options are deduced.

Member Typedef Documentation

◆ Boundary

template<class Master_matrix >

using Gudhi::persistence_matrix::Boundary_matrix< Master_matrix >::Boundary = typename Master_matrix::Boundary

Type of an input column.

◆ Column

template<class Master_matrix >

using Gudhi::persistence_matrix::Boundary_matrix< Master_matrix >::Column = typename Master_matrix::Column

Column type.

◆ Column_settings

template<class Master_matrix >

using Gudhi::persistence_matrix::Boundary_matrix< Master_matrix >::Column_settings = typename Master_matrix::Column_settings

Structure giving access to the columns to necessary external classes.

◆ Dimension

template<class Master_matrix >

using Gudhi::persistence_matrix::Boundary_matrix< Master_matrix >::Dimension = typename Master_matrix::Dimension

Dimension value type.

◆ Entry_constructor

template<class Master_matrix >

using Gudhi::persistence_matrix::Boundary_matrix< Master_matrix >::Entry_constructor = typename Master_matrix::Entry_constructor

Factory of Entry classes.

◆ Field_element

template<class Master_matrix >

using Gudhi::persistence_matrix::Boundary_matrix< Master_matrix >::Field_element = typename Master_matrix::Element

Type of an field element.

◆ ID_index

template<class Master_matrix >

using Gudhi::persistence_matrix::Boundary_matrix< Master_matrix >::ID_index = typename Master_matrix::ID_index

IDIdx index type.

◆ Index

template<class Master_matrix >

using Gudhi::persistence_matrix::Boundary_matrix< Master_matrix >::Index = typename Master_matrix::Index

Container index type.

◆ Row

template<class Master_matrix >

using Gudhi::persistence_matrix::Boundary_matrix< Master_matrix >::Row = typename Master_matrix::Row

Row type, only necessary with row access option.

Constructor & Destructor Documentation

◆ Boundary_matrix() [1/5]

template<class Master_matrix >

Gudhi::persistence_matrix::Boundary_matrix< Master_matrix >::Boundary_matrix ( Column_settings * colSettings )

inline

Constructs an empty matrix.

Parameters

colSettings Pointer to an existing setting structure for the columns. The structure should contain all the necessary external classes specifically necessary for the chosen column type, such as custom allocators.

◆ Boundary_matrix() [2/5]

template<class Master_matrix >

template<class Boundary_range >

Gudhi::persistence_matrix::Boundary_matrix< Master_matrix >::Boundary_matrix	(	const std::vector< Boundary_range > &	orderedBoundaries,
		Column_settings *	colSettings
	)

inline

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

Template Parameters

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

Parameters

orderedBoundaries Range of boundaries: orderedBoundaries is interpreted as a boundary matrix of a filtered simplicial complex, whose boundaries are ordered by filtration order. Therefore, orderedBoundaries[i] should store the boundary of the \( i^{th} \) simplex in the filtration, as an ordered list of indices of its facets (again those indices correspond to their respective position in the matrix). That is why 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 Boundary_matrix(unsigned int numberOfColumns, Column_settings* colSettings) constructor preferably).

colSettings Pointer to an existing setting structure for the columns. The structure should contain all the necessary external classes specifically necessary for the chosen column type, such as custom allocators.

◆ Boundary_matrix() [3/5]

template<class Master_matrix >

Gudhi::persistence_matrix::Boundary_matrix< Master_matrix >::Boundary_matrix	(	unsigned int	numberOfColumns,
		Column_settings *	colSettings
	)

inline

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

Parameters

numberOfColumns	Number of columns to reserve space for.
colSettings	Pointer to an existing setting structure for the columns. The structure should contain all the necessary external classes specifically necessary for the chosen column type, such as custom allocators.

◆ Boundary_matrix() [4/5]

template<class Master_matrix >

Gudhi::persistence_matrix::Boundary_matrix< Master_matrix >::Boundary_matrix	(	const Boundary_matrix< Master_matrix > &	matrixToCopy,
		Column_settings *	colSettings = `nullptr`
	)

inline

Copy constructor. If colSettings is not a null pointer, its value is kept instead of the one in the copied matrix.

Parameters

matrixToCopy	Matrix to copy.
colSettings	Either a pointer to an existing setting structure for the columns or a null pointer. The structure should contain all the necessary external classes specifically necessary for the chosen column type, such as custom allocators. If null pointer, the pointer stored in `matrixToCopy` is used instead.

◆ Boundary_matrix() [5/5]

template<class Master_matrix >

Gudhi::persistence_matrix::Boundary_matrix< Master_matrix >::Boundary_matrix ( Boundary_matrix< Master_matrix > && other )

inlinenoexcept

Move constructor.

Parameters

other Matrix to move.

Member Function Documentation

◆ add_to()

template<class Master_matrix >

void Gudhi::persistence_matrix::Boundary_matrix< Master_matrix >::add_to	(	Index	sourceColumnIndex,
		Index	targetColumnIndex
	)

inline

Adds column at sourceColumnIndex onto the column at targetColumnIndex in the matrix.

Warning: They will be no verification to ensure that the addition makes sense for the validity of a boundary matrix of a filtered complex. For example, a right-to-left addition could corrupt the computation of the barcode if done blindly. So should be used with care.

Parameters

sourceColumnIndex	MatIdx index of the source column.
targetColumnIndex	MatIdx index of the target column.

◆ erase_empty_row()

template<class Master_matrix >

void Gudhi::persistence_matrix::Boundary_matrix< Master_matrix >::erase_empty_row ( Index rowIndex )

inline

If PersistenceMatrixOptions::has_row_access and PersistenceMatrixOptions::has_removable_rows are true: assumes that the row is empty and removes it. If PersistenceMatrixOptions::has_map_column_container and PersistenceMatrixOptions::has_column_and_row_swaps are true: cleans up maps used for the lazy row swaps. Otherwise, does nothing.

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.

◆ get_column()

template<class Master_matrix >

Boundary_matrix< Master_matrix >::Column & Gudhi::persistence_matrix::Boundary_matrix< Master_matrix >::get_column ( Index columnIndex )

inline

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

Note that before returning the column, all column entries can eventually be reordered, if lazy swaps occurred. It is therefore recommended to avoid calling get_column between column or row swaps, otherwise the benefits of the the laziness is lost.

Parameters

columnIndex MatIdx index of the column to return.

Returns: Reference to the column.

◆ get_column_dimension()

template<class Master_matrix >

Boundary_matrix< Master_matrix >::Dimension Gudhi::persistence_matrix::Boundary_matrix< Master_matrix >::get_column_dimension ( Index columnIndex ) const

inline

Returns the dimension of the given column.

Parameters

columnIndex MatIdx index of the column representing the cell.

Returns: Dimension of the cell.

◆ get_number_of_columns()

template<class Master_matrix >

Boundary_matrix< Master_matrix >::Index Gudhi::persistence_matrix::Boundary_matrix< Master_matrix >::get_number_of_columns

inline

Returns the current number of columns in the matrix.

Returns: The number of columns.

◆ get_pivot()

template<class Master_matrix >

Boundary_matrix< Master_matrix >::Index Gudhi::persistence_matrix::Boundary_matrix< Master_matrix >::get_pivot ( Index columnIndex )

inline

Returns the pivot of the given column.

Parameters

columnIndex MatIdx index of the column.

Returns: Pivot of the column at columnIndex.

◆ get_row()

template<class Master_matrix >

Boundary_matrix< Master_matrix >::Row & Gudhi::persistence_matrix::Boundary_matrix< Master_matrix >::get_row ( Index rowIndex )

inline

Only available if PersistenceMatrixOptions::has_row_access is true. Returns the row at the given row index of the matrix. The type of the row depends on the chosen options, see PersistenceMatrixOptions::has_intrusive_rows.

Note that before returning the row, all column entries can eventually be reordered, if lazy swaps occurred. It is therefore recommended to avoid calling get_row between column or row swaps, otherwise the benefits of the the laziness is lost.

Parameters

rowIndex Row index of the row to return.

Returns: Reference to the row.

◆ insert_boundary() [1/2]

template<class Master_matrix >

template<class Boundary_range >

Boundary_matrix< Master_matrix >::Index Gudhi::persistence_matrix::Boundary_matrix< Master_matrix >::insert_boundary	(	const Boundary_range &	boundary,
		Dimension	dim = `Master_matrix::template 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.

At the insertion, the boundary will be copied as is. 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.

Template Parameters

Boundary_range Range of Matrix::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: The MatIdx index of the inserted boundary.

◆ insert_boundary() [2/2]

template<class Master_matrix >

template<class Boundary_range >

Boundary_matrix< Master_matrix >::Index Gudhi::persistence_matrix::Boundary_matrix< Master_matrix >::insert_boundary	(	ID_index	cellIndex,
		const Boundary_range &	boundary,
		Dimension	dim = `Master_matrix::template get_null_value<Dimension>()`
	)

inline

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 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 Matrix::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: The MatIdx index of the inserted boundary.

◆ is_zero_column()

template<class Master_matrix >

bool Gudhi::persistence_matrix::Boundary_matrix< Master_matrix >::is_zero_column ( Index columnIndex )

inline

Indicates if the column at given index has value zero.

Parameters

columnIndex MatIdx index of the column.

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

◆ is_zero_entry()

template<class Master_matrix >

bool Gudhi::persistence_matrix::Boundary_matrix< Master_matrix >::is_zero_entry	(	Index	columnIndex,
		Index	rowIndex
	)		const

inline

Indicates if the entry at given coordinates has value zero.

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.

◆ multiply_source_and_add_to()

template<class Master_matrix >

void Gudhi::persistence_matrix::Boundary_matrix< Master_matrix >::multiply_source_and_add_to	(	const Field_element &	coefficient,
		Index	sourceColumnIndex,
		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.

Warning: They will be no verification to ensure that the addition makes sense for the validity of a boundary matrix of a filtered complex. For example, a right-to-left addition could corrupt the computation of the barcode if done blindly. So should be used with care.

Parameters

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

◆ multiply_target_and_add_to()

template<class Master_matrix >

void Gudhi::persistence_matrix::Boundary_matrix< Master_matrix >::multiply_target_and_add_to	(	Index	sourceColumnIndex,
		const Field_element &	coefficient,
		Index	targetColumnIndex
	)

inline

Multiplies the target column with the coefficient and then adds the source column to it. That is: targetColumn = (targetColumn * coefficient) + sourceColumn.

Warning: They will be no verification to ensure that the addition makes sense for the validity of a boundary matrix of a filtered complex. For example, a right-to-left addition could corrupt the computation of the barcode if done blindly. So should be used with care.

Parameters

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

◆ remove_last()

template<class Master_matrix >

Boundary_matrix< Master_matrix >::Index Gudhi::persistence_matrix::Boundary_matrix< Master_matrix >::remove_last

inline

Only available if PersistenceMatrixOptions::has_removable_columns is true. Removes the last cell in the filtration from the matrix and updates the barcode if this one was already computed.

Returns: The pivot of the removed cell.

◆ reset()

template<class Master_matrix >

void Gudhi::persistence_matrix::Boundary_matrix< Master_matrix >::reset ( Column_settings * colSettings )

inline

Resets the matrix to an empty matrix.

Parameters

colSettings Pointer to an existing setting structure for the columns. The structure should contain all the necessary external classes specifically necessary for the chosen column type, such as custom allocators.

◆ zero_column()

template<class Master_matrix >

void Gudhi::persistence_matrix::Boundary_matrix< Master_matrix >::zero_column ( Index columnIndex )

inline

Zeroes the column at the given index.

Warning: They will be no verification to ensure that the zeroing makes sense for the validity of a boundary matrix of a filtered complex. So should be used while knowing what one is doing.

Parameters

columnIndex MatIdx index of the column to zero.

◆ zero_entry()

template<class Master_matrix >

void Gudhi::persistence_matrix::Boundary_matrix< Master_matrix >::zero_entry	(	Index	columnIndex,
		Index	rowIndex
	)

inline

Zeroes the entry at the given coordinates.

Warning: They will be no verification to ensure that the zeroing makes sense for the validity of a boundary matrix of a filtered complex. So should be used while knowing what one is doing.

Parameters

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

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

include/gudhi/Persistence_matrix/Boundary_matrix.h

Public Types

Public Member Functions

Friends

Detailed Description

Member Typedef Documentation

◆ Boundary

◆ Column

◆ Column_settings

◆ Dimension

◆ Entry_constructor

◆ Field_element

◆ ID_index

◆ Index

◆ Row

Constructor & Destructor Documentation

◆ Boundary_matrix() [1/5]

◆ Boundary_matrix() [2/5]

◆ Boundary_matrix() [3/5]

◆ Boundary_matrix() [4/5]

◆ Boundary_matrix() [5/5]

Member Function Documentation

◆ add_to()

◆ erase_empty_row()

◆ get_column()

◆ get_column_dimension()

◆ get_number_of_columns()

◆ get_pivot()

◆ get_row()

◆ insert_boundary() [1/2]

◆ insert_boundary() [2/2]

◆ is_zero_column()

◆ is_zero_entry()

◆ multiply_source_and_add_to()

◆ multiply_target_and_add_to()

◆ remove_last()

◆ reset()

◆ zero_column()

◆ zero_entry()