CGAL 6.3-dev - Homological Discrete Vector Fields
Loading...
Searching...
No Matches
CGAL::Homological_discrete_vector_field::Hdvf_persistence< ChainComplex, Degree, Filtration_ > Class Template Reference

#include <CGAL/HDVF/Hdvf_persistence.h>

Inherits from

CGAL::Homological_discrete_vector_field::Hdvf_core< ChainComplex >.

Definition

template<typename ChainComplex, typename Degree, typename Filtration_>
class CGAL::Homological_discrete_vector_field::Hdvf_persistence< ChainComplex, Degree, Filtration_ >

The class Hdvf_persistence computes persistent homology using HDVFs.

Warning
The ring of coefficients provided should be a field.

Unlike other persistence computation libraries, beside standard persistent intervals informations (birth/death indices, degrees, associated cells), Hdvf_persistence also provides homology and cohomology generators for persistent pairs (see user manual for details, including the link to cascades). Intuitively, holes die when they are "filled" by a cell: associated homology and cohomology generators provide a representation of the hole and of the cells filling the hole.

Given a Filtration, the Hdvf_persistence class computes persistent homology as a perfect HDVF adapted to the filtration (through the compute_perfect_hdvf() method). If the reduction \(g\) map is computed (depending the the computation option), HDVFs also provide persistent homology generators, together with the corresponding "filling" chains.

Is model of
HDVF
Template Parameters
ChainComplexa model of the AbstractChainComplex concept, providing the type of abstract chain complex used (the underlying ring of coefficients must be a model of Field). The sparse matrix provided by ChainComplex must be an instance of the Sub_sparse_matrix_structure template.
Degreea scalar data type used for the degrees of the filtration (a model of RealEmbeddable concept).
Filtration_a model of the Filtration concept, providing the filtration used to compute persistence.
Warning
  • The sparse matrix provided by ChainComplex must be an instance of the Sub_sparse_matrix_structure template.
  • For persistent homology computation, the selection of cells paired by the A() operation is totally determined by the filtration. Hence, the find_pair_A() family of functions and A() operation are private to Hdvf_persistence.

Classes

struct  Persistence_interval
 Structure storing (full) persistent interval data: More...
struct  Persistent_hole
 Hole information returned by the persistent diagram iterator. More...
struct  iterator
 Iterator over (finite) persistent intervals. More...

Public Types

typedef ChainComplex Chain_complex
 Chain complex type.
typedef Chain_complex::Coefficient_ring Coefficient_ring
 Type of coefficients used to compute homology.
typedef Hdvf_core< ChainComplex > Base
 Type of parent HDVF class (Hdvf_core with appropriate template parameters) The SparseMatrix model is set to Sub_sparse_matrix_structure to activate (co)homology computation over a subcomplex.
typedef Filtration_ Filtration
 Type of filtrations used to compute persistence.
Public Types inherited from CGAL::Homological_discrete_vector_field::Hdvf_core< ChainComplex >
typedef ChainComplex Chain_complex
 Type of the underlying chain complex.
typedef ChainComplex::Coefficient_ring Coefficient_ring
 Type of coefficients used to compute homology.
typedef ChainComplex::Sparse_matrix_structure Sparse_matrix_structure
 Type of sparse matrix structure used to compute homology.
template<typename CR, int SF>
using Sparse_chain_base = typename Sparse_matrix_structure::template Sparse_chain_type<CR, SF>
 Template type of underlying sparse chains.
template<typename CR, int SF>
using Sparse_matrix_base = typename Sparse_matrix_structure::template Sparse_matrix_type<CR, SF>
 Template type of underlying sparse matrices.
typedef Sparse_chain_base< Coefficient_ring, CGAL::OSM::COLUMN > Column_chain
 Type of column-major chains.
typedef Sparse_chain_base< Coefficient_ring, CGAL::OSM::ROW > Row_chain
 Type of row-major chains.
typedef Sparse_matrix_base< Coefficient_ring, CGAL::OSM::COLUMN > Column_matrix
 Type of column-major sparse matrices.
typedef Sparse_matrix_base< Coefficient_ring, CGAL::OSM::ROW > Row_matrix
 Type of row-major sparse matrices.

Public Member Functions

 Hdvf_persistence (const Chain_complex &K, const Filtration &f, int hdvf_opt=OPT_BND, bool with_export=false, int dimension_restriction=-1)
 Hdvf_persistence default constructor.
std::vector< Cell_pair > compute_perfect_hdvf (bool verbose=false)
 Computes a perfect persistent HDVF.
bool with_export () const
 Gets the "with_export" Boolean flag.
const Filtration & filtration () const
 Get a constant reference on the filtration.
std::ostream & print_hdvf_persistence_information (std::ostream &out) const
 Prints informations related to the filtration.
iterator begin (bool discard_small=true) const
 Iterator to the beginning of persistent intervals.
iterator end () const
 Iterator past-the-end of persistent intervals.
Public Member Functions inherited from CGAL::Homological_discrete_vector_field::Hdvf_core< ChainComplex >
 Hdvf_core (const ChainComplex &K, int hdvf_opt=OPT_FULL, int dimension_restriction=-1)
 Constructor from a chain complex.
 Hdvf_core (const Hdvf_core &hdvf)
 Copy constructor.
Hdvf_core & operator= (const Hdvf_core &hdvf)
 Affectation operator.
 Hdvf_core (const ChainComplex &K, const std::vector< std::vector< PSC_flag > > &flags, bool with_build_reduction=false, int hdvf_opt=OPT_FULL, int dimension_restriction=-1)
 Constructor from the PRIMARY/SECONDARY/CRITICAL labels.
PSC_flag psc_flag (size_t tau, int q) const
 Gets the PSC_flag of the cell tau in dimension q.

Friends

std::ostream & operator<< (std::ostream &out_stream, const Hdvf_persistence &per_hdvf)
 Overload of operator<<() for Hdvf_persistence.

Member Typedef Documentation

◆ Base

template<typename ChainComplex, typename Degree, typename Filtration_>
typedef Hdvf_core<ChainComplex> CGAL::Homological_discrete_vector_field::Hdvf_persistence< ChainComplex, Degree, Filtration_ >::Base

Type of parent HDVF class (Hdvf_core with appropriate template parameters) The SparseMatrix model is set to Sub_sparse_matrix_structure to activate (co)homology computation over a subcomplex.

Todo
Check that the SparseMatrix provided by ChainComplex is a Sub_sparse_matrix_structure (and not a generic Sparse_matrix_structure).

Constructor & Destructor Documentation

◆ Hdvf_persistence()

template<typename ChainComplex, typename Degree, typename Filtration_>
CGAL::Homological_discrete_vector_field::Hdvf_persistence< ChainComplex, Degree, Filtration_ >::Hdvf_persistence ( const Chain_complex & K,
const Filtration & f,
int hdvf_opt = OPT_BND,
bool with_export = false,
int dimension_restriction = -1 )

Hdvf_persistence default constructor.

Builds an "empty" HDVF_persistence (with all cells critical) associated to the chain complex K and the filtration f. By default, the HDVF option is set to OPT_FULL (full reduction computed).

If the with_exportparameter is set to true, homology and cohomology generators of persistent pairs, together with the corresponding HDVFs (see user manual for details) are stored along the computation; they can then be visited via the persistent pairs iterator.

Parameters
KA chain complex (a model of AbstractChainComplex).
fA filtration (a model of Filtration).
hdvf_optOption for HDVF computation (OPT_BND, OPT_F, OPT_G or OPT_FULL)
with_exportBoolean option to activate or not the storage of the Persistent_hole informations (PSC labels and homology/cohomology generators) for persistent intervals of positive duration. This information is required for vtk exporters.
dimension_restrictionDetermines if persistence is computed along any dimensions (if dimension_restriction is -1) or a single dimension (specified by dimension_restrictions)
Exceptions
Empty_complexIf the complex `K` is empty, raises a `std::runtime_error`.

Member Function Documentation

◆ begin()

template<typename ChainComplex, typename Degree, typename Filtration_>
iterator CGAL::Homological_discrete_vector_field::Hdvf_persistence< ChainComplex, Degree, Filtration_ >::begin ( bool discard_small = true) const

Iterator to the beginning of persistent intervals.

Parameters
discard_smallIf true, the iterator visits only persistent intervals of (strictly) positive degree duration. Otherwise, visit all persistent intervals.
Returns
The iterator to the beginning of the chain indices.

◆ compute_perfect_hdvf()

template<typename ChainComplex, typename Degree, typename Filtration_>
std::vector< Cell_pair > CGAL::Homological_discrete_vector_field::Hdvf_persistence< ChainComplex, Degree, Filtration_ >::compute_perfect_hdvf ( bool verbose = false)

Computes a perfect persistent HDVF.

This method follows the filtration and considers cells one by one. For each of them, it searches the youngest possible cell valid for A() and applies the corresponding operation. By definition of persistent homology, the IntegralDomainWithoutDivision of coefficients must be a Field.

If dimension_restriction is a positive parameter (in the HDVF), then persistence is computed only in dimension dimension_restriction.

Parameters
verboseIf this parameter is true, all intermediate reductions are printed out.
Returns
The vector of all Cell_pair paired with A.

◆ end()

template<typename ChainComplex, typename Degree, typename Filtration_>
iterator CGAL::Homological_discrete_vector_field::Hdvf_persistence< ChainComplex, Degree, Filtration_ >::end ( ) const

Iterator past-the-end of persistent intervals.

Returns
The past-the-end iterator of persistent intervals.

◆ print_hdvf_persistence_information()

template<typename ChainComplex, typename Degree, typename Filtration_>
std::ostream & CGAL::Homological_discrete_vector_field::Hdvf_persistence< ChainComplex, Degree, Filtration_ >::print_hdvf_persistence_information ( std::ostream & out) const

Prints informations related to the filtration.

Prints out the filtration and associated permutations (_K_to_per and _per_to_K) between indices of cells in each dimension in the basis of K and indices along the filtration.

Parameters
outReference to an output stream.

◆ with_export()

template<typename ChainComplex, typename Degree, typename Filtration_>
bool CGAL::Homological_discrete_vector_field::Hdvf_persistence< ChainComplex, Degree, Filtration_ >::with_export ( ) const

Gets the "with_export" Boolean flag.

If the flag is true, homology/cohomology generators and corresponding PSC labels are exported for each persistent interval of positive duration.

◆ operator<<

template<typename ChainComplex, typename Degree, typename Filtration_>
std::ostream & operator<< ( std::ostream & out_stream,
const Hdvf_persistence< ChainComplex, Degree, Filtration_ > & per_hdvf )
friend

Overload of operator<<() for Hdvf_persistence.

Prints out finite and infinite persistence intervals in a user friendly way.

Parameters
out_streamReference to an output stream.
per_hdvfConstant reference on the Hdvf_persistence to print.