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

#include <CGAL/HDVF/Hdvf.h>

Inherits from

CGAL::Homological_discrete_vector_field::Hdvf_core< ChainComplex >.

Definition

template<typename ChainComplex>
class CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >

The class Hdvf implements homology and cohomology computation via homological discrete vector fields (HDVF for short).

It derives from Hdvf_core and shares all its data and methods.

Perfect HDVFs provide various topological results:

  • Betti numbers: are well known topological descriptors (providing the number of holes in each dimension). For a perfect HDVF, Betti numbers equal the number of critical cells (that can be obtained through psc_flag() with the CRITICAL``PSC_flag as argument).
  • Homology/cohomology generators are actually algebraic objects, namely chains. Methods homology_chain() and cohomology_chain() return the homology and cohomology generator chain associated to a given critical cell. VTK export functions output all the cells of such chains with non zero coefficients. Figures here above illustrate such homology and co-homology generators.
  • Homology/cohomology annotation: use get_annotation() or get_coannotation() to get the annotation/co-annotation of a cycle/co-cycle in the homology/cohomology basis (as a chain of critical cells).
  • Homology/cohomology comparison: use are_same_cycles() or are_same_cocycles() to check if two cycles (or co-cycles) belong to the same homology / cohomology class.

Figure 99.1 Illustration of cycles annotation and comparison. Left: Generator \(g(\sigma)\) associated to the critical cell \(\sigma\); Middle: A cycle \(\alpha\) ; Right: A second cycle \(\beta\).

For \(\mathbb Z_2\) homology, the annotation of \(\alpha\) is \(\sigma\) ( \(\alpha\) equals \(g(\sigma)\) up to a boundary), while the annotation of \(\beta\) is \(\sigma+\tau+\gamma\) ( \(\beta\) equals \(g(\sigma)+g(\tau)+g(\gamma)\) up to a boundary).

Therefore, are_same_cycles will return true for \(\alpha\) and \(g(\sigma)\), but false for \(\beta\) and \(g(\sigma)\).


Besides construction operations and methods (using the A() operation), the Hdvf class implements four other HDVF operations: R, M, W and MW together with appropriate find_pair_xxx() functions (see user documentation for more details).

Is model of
HDVF
Template Parameters
ChainComplexa model of the AbstractChainComplex concept, providing the type of abstract chain complex used.

Classes

struct  Hole_information
 Hole information returned by iterator. More...
struct  iterator
 Iterator over homology/cohomology generators. 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< Chain_complex > Base
 Type of parent Hdvf_core class.
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 (const Chain_complex &K, int hdvf_opt=OPT_FULL, int dimension_restriction=-1)
 Builds an "empty" HDVF associated to K (with all cells critical).
Hdvf & operator= (const Hdvf &hdvf)
 Affectation operator.
 Hdvf (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.
bool is_valid_pair_for_M (size_t pi, size_t gamma, int q)
 Checks if the pair of cells \((\pi, \gamma)\), of dimension q, is valid for M.
Cell_pair find_pair_M (int q, bool &found) const
 Finds a valid Cell_pair of dimension q for M.
Cell_pair find_pair_M (int q, bool &found, size_t tau) const
 Finds a valid Cell_pair of dimension q for M cointaining tau.
std::vector< Cell_pair > find_pairs_M (int q, bool &found) const
 Finds all valid Cell_pair of dimension q for M.
std::vector< Cell_pair > find_pairs_M (int q, bool &found, size_t tau) const
 Finds all valid Cell_pair of dimension q for M cointaining tau.
bool is_valid_pair_for_W (size_t sigma, size_t gamma, int q)
 Checks if the pair of cells \((\sigma, \gamma)\), of dimension q, is valid for W.
Cell_pair find_pair_W (int q, bool &found) const
 Finds a valid Cell_pair of dimension q for W.
Cell_pair find_pair_W (int q, bool &found, size_t tau) const
 Finds a valid Cell_pair of dimension q for W cointaining tau.
std::vector< Cell_pair > find_pairs_W (int q, bool &found) const
 Finds all valid Cell_pair of dimension q for W.
std::vector< Cell_pair > find_pairs_W (int q, bool &found, size_t tau) const
 Finds all valid Cell_pair of dimension q for W cointaining tau.
bool is_valid_pair_for_MW (size_t pi, size_t sigma, int q)
 Checks if the pair of cells \((\pi, \sigma)\), of dimension q, is valid for MW.
Cell_pair find_pair_MW (int q, bool &found) const
 Finds a valid Cell_pair of dimension q for MW.
Cell_pair find_pair_MW (int q, bool &found, size_t tau) const
 Finds a valid Cell_pair of dimension q for MW cointaining tau.
std::vector< Cell_pair > find_pairs_MW (int q, bool &found) const
 Finds all valid Cell_pair of dimension q for MW.
std::vector< Cell_pair > find_pairs_MW (int q, bool &found, size_t tau) const
 Finds all valid Cell_pair of dimension q for W cointaining tau.
bool is_valid_pair_for_R (size_t pi, size_t sigma, int q)
 Checks if the pair of cells \((\pi, \sigma)\), of dimensions q / q+1, is valid for R.
void R (size_t pi, size_t sigma, int q)
 R operation (cancels a A operation).
void R (const Cell_pair &p)
 R operation (cancels a A operation).
void M (size_t pi, size_t gamma, int q)
 M operation.
void M (const Cell_pair &p)
 M operation.
void W (size_t sigma, size_t gamma, int q)
 W operation.
void W (const Cell_pair &p)
 W operation.
void MW (size_t pi, size_t sigma, int q)
 MW operation.
void MW (const Cell_pair &p)
 MW operation.
Column_chain z (size_t sigma, int q)
 Compute \(z_q\) function on a cell of dimension q.
Column_chain co_z (size_t sigma, int q)
 Compute \(z^q\) function on a cell of dimension q.
Column_chain hd (size_t sigma, int q)
 Computes \(h_{q-1}\circ \partial_q(\sigma)\).
Coefficient_ring hd (size_t sigma, size_t tau, int q)
 Computes \(\langle h_{q-1}\circ \partial_q(\sigma), \tau\rangle\).
Column_chain dh (size_t sigma, int q)
 Computes \(\partial_{q+1}\circ h_{q}(\sigma)\).
Coefficient_ring dh (size_t sigma, size_t tau, int q)
 Computes \(\langle \partial_{q+1}\circ h_{q}(\sigma), \tau\rangle\).
Column_chain get_annotation (Column_chain chain, int dim) const
 Gets the annotation of a cycle in the homology basis.
Row_chain get_coannotation (Row_chain chain, int dim) const
 Gets the co-annotation of a co-cycle in the cohomology basis.
bool are_same_cycles (Column_chain chain1, Column_chain chain2, int dim)
 Checks if two cycles belong to the same homology class.
bool are_same_cocycles (Row_chain chain1, Row_chain chain2, int dim)
 Checks if two co-cycles belong to the same cohomology class.
iterator begin (int q=-1, Iterator_mode mode=Iterator_mode(0)) const
 Iterator to the beginning of homology/cohomology generators.
iterator end () const
 Iterator past-the-end of homology/cohomology generators.
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.

Constructor & Destructor Documentation

◆ Hdvf() [1/2]

template<typename ChainComplex>
CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::Hdvf ( const Chain_complex & K,
int hdvf_opt = OPT_FULL,
int dimension_restriction = -1 )

Builds an "empty" HDVF associated to K (with all cells critical).

By default, the HDVF option is set to OPT_FULL (full reduction computed).

Parameters
KA chain complex (a model of AbstractChainComplex)
hdvf_optOption for HDVF computation (OPT_BND, OPT_F, OPT_G or OPT_FULL)
dimension_restrictionDetermines if perfect HDVFs are computed along any dimensions (if dimension_restriction is -1) or a single dimension (specified by dimension_restrictions)
Exceptions
Ifthe complex `K` is empty, raises a `std::runtime_error`.

◆ Hdvf() [2/2]

template<typename ChainComplex>
CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::Hdvf ( 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.

If with_build_reduction is false check the combinatorial coherence of labels. If with_build_reduction is true checks that labels describe a valid HDVF (ie. \(\partial(S)\_P\) is invertible).

Parameters
KA chain complex (a model of AbstractChainComplex)
flagsVector of PSC labels along each dimensions.
with_build_reductionIf false, loads labels without building the reduction, if true builds the reduction ( \(\mathscr O(n^3)\)).
hdvf_optOption for HDVF computation (OPT_BND, OPT_F, OPT_G or OPT_FULL)
dimension_restrictionDetermines if perfect HDVFs are computed along any dimensions (if dimension_restriction is -1) or a single dimension (specified by dimension_restrictions)
Exceptions
Incoherent_flagsIf the flags provided are incoherent (or do not define an HDVF), raises a `std::invalid_argument`.

Member Function Documentation

◆ are_same_cocycles()

template<typename ChainComplex>
bool CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::are_same_cocycles ( Row_chain chain1,
Row_chain chain2,
int dim )

Checks if two co-cycles belong to the same cohomology class.

Warning
Will raise an error is chains provided are not co-cycles.
The HDVF must be perfect.
Parameters
chain1First co-cycle.
chain2Second co-cycle.
dimDimension of both co-cycles.
Exceptions
Invalid_argumentIf `chain1` or `chain2` are not co-cycle, raises a `std::invalid_argument` exception.

◆ are_same_cycles()

template<typename ChainComplex>
bool CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::are_same_cycles ( Column_chain chain1,
Column_chain chain2,
int dim )

Checks if two cycles belong to the same homology class.

Warning
Will raise an error is chains provided are not cycles.
The HDVF must be perfect.
Parameters
chain1First cycle.
chain2Second cycle.
dimDimension of both cycles.
Exceptions
Invalid_argumentIf `chain1` or `chain2` are not cycles, raises a `std::invalid_argument` exception.

◆ begin()

template<typename ChainComplex>
iterator CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::begin ( int q = -1,
Iterator_mode mode = Iterator_mode(0) ) const

Iterator to the beginning of homology/cohomology generators.

Parameters
qIf positive, the iterator visits only holes of dimension q, if negative (default), visits holes in any dimension computed (depending on dimension restriction)
modeDefines which information is returned by the iterator (HOMOLOGY, COHOMOLOGY or BOTH). This argument must be coherent with the HDVF option chosen for computation. By default, copies the current HDVF options.
Returns
The iterator to the first hole visited.

◆ co_z()

template<typename ChainComplex>
Column_chain CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::co_z ( size_t sigma,
int q )

Compute \(z^q\) function on a cell of dimension q.

This function was first defined in tri-partitions; formally \(z^q = \mathrm{Id} - h_{q}^*\circ \partial_{q+1}^*\).

When the HDVF is perfect, \(z_q(\sigma)\) is the canonical cocycle associated to \(\sigma\). Intuitively:

  • if \(\sigma\) is SECONDARY, \(z^q(\sigma)\) is a cochain of PRIMARY cells ; if the HDVF is perfect \(z^q(\sigma)\) is a cocycle (the unique cocycle containing \(\sigma\) and PRIMARY cells).
  • if \(\sigma\) is PRIMARY, this cocycle is null
  • if \(\sigma\) is CRITICAL, \(z^q(\sigma)\) matches \(f^*(\sigma)\) ; if the HDVF is perfect \(z^q(\sigma)\) hence provides the cohomology generator associated to \(\sigma\)).

Moreover, in HDVF_persistent, co_z function provides persistent cohomology generators.

Parameters
sigmaCell index.
qCell dimension.

◆ dh() [1/2]

template<typename ChainComplex>
Column_chain CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::dh ( size_t sigma,
int q )

Computes \(\partial_{q+1}\circ h_{q}(\sigma)\).

The \(\partial_{q+1}\circ h_{q}(\sigma)\) function is used both in MW operation and in tri-partitions. As the matrix is not stored in the reduction, we provide methods to compute if efficiently.

Parameters
sigmaIndex of the cell
qDimension of the cell

◆ dh() [2/2]

template<typename ChainComplex>
Coefficient_ring CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::dh ( size_t sigma,
size_t tau,
int q )

Computes \(\langle \partial_{q+1}\circ h_{q}(\sigma), \tau\rangle\).

The \(\partial_{q+1}\circ h_{q}\) function is used both in MW operation and in tri-partitions. As the matrix is not stored in the reduction, we provide methods to compute if efficiently.

Parameters
sigmaIndex of the first cell
tauIndex of the second cell
qDimension of the cell

◆ end()

template<typename ChainComplex>
iterator CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::end ( ) const

Iterator past-the-end of homology/cohomology generators.

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

◆ find_pair_M() [1/2]

template<typename ChainComplex>
Cell_pair CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::find_pair_M ( int q,
bool & found ) const

Finds a valid Cell_pair of dimension q for M.

The function searches a pair of cells \((\pi, \gamma)\) with \(\pi\) PRIMARY and \(\gamma\) CRITICAL, valid for M (ie. such that \(\langle f(\pi), \gamma \rangle\) invertible). It returns the first valid pair found by iterators.

Parameters
qDimension of the pair searched.
foundReference to a Boolean variable. The method sets found to true if a valid pair is found, false otherwise.

◆ find_pair_M() [2/2]

template<typename ChainComplex>
Cell_pair CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::find_pair_M ( int q,
bool & found,
size_t tau ) const

Finds a valid Cell_pair of dimension q for M cointaining tau.

The function searches a pair of cells \((\pi, \gamma)\) with \(\pi\) PRIMARY and \(\gamma\) CRITICAL (one of them is tau), valid for M (ie. such that \(\langle f(\pi), \gamma \rangle\) invertible). It returns the first valid pair found by iterators.

Parameters
qDimension of the pair searched.
foundReference to a Boolean variable. The method sets found to true if a valid pair is found, false otherwise.
tauCell of dimension q to pair.

◆ find_pair_MW() [1/2]

template<typename ChainComplex>
Cell_pair CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::find_pair_MW ( int q,
bool & found ) const

Finds a valid Cell_pair of dimension q for MW.

The function searches a pair of cells \((\pi, \sigma)\) with \(\pi\) PRIMARY and \(\sigma\) SECONDARY, valid for MW (ie. such that \(\langle h_{q-1}\partial_q(\pi), \sigma \rangle\) invertible and \(\langle \partial_{q+1} h_q(\sigma), \pi \rangle\) invertible). It returns the first valid pair found by iterators.

Parameters
qDimension of the pair searched.
foundReference to a Boolean variable. The method sets found to true if a valid pair is found, false otherwise.

◆ find_pair_MW() [2/2]

template<typename ChainComplex>
Cell_pair CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::find_pair_MW ( int q,
bool & found,
size_t tau ) const

Finds a valid Cell_pair of dimension q for MW cointaining tau.

The function searches a pair of cells \((\pi, \sigma)\) with \(\pi\) PRIMARY and \(\sigma\) SECONDARY (one of them is tau), valid for MW (ie. such that \(\langle h_{q-1}\partial_q(\pi), \sigma \rangle\) invertible and \(\langle \partial_{q+1} h_q(\sigma), \pi \rangle\) invertible). It returns the first valid pair found by iterators.

Parameters
qDimension of the pair searched.
foundReference to a Boolean variable. The method sets found to true if a valid pair is found, false otherwise.
tauCell of dimension q to pair.

◆ find_pair_W() [1/2]

template<typename ChainComplex>
Cell_pair CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::find_pair_W ( int q,
bool & found ) const

Finds a valid Cell_pair of dimension q for W.

The function searches a pair of cells \((\sigma, \gamma)\) with \(\sigma\) SECONDARY and \(\gamma\) CRITICAL, valid for W (ie. such that \(\langle g(\gamma), \sigma \rangle\) invertible). It returns the first valid pair found by iterators.

Parameters
qDimension of the pair searched.
foundReference to a Boolean variable. The method sets found to true if a valid pair is found, false otherwise.

◆ find_pair_W() [2/2]

template<typename ChainComplex>
Cell_pair CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::find_pair_W ( int q,
bool & found,
size_t tau ) const

Finds a valid Cell_pair of dimension q for W cointaining tau.

The function searches a pair of cells \((\sigma, \gamma)\) with \(\sigma\) SECONDARY and \(\gamma\) CRITICAL (one of them is tau), valid for W (ie. such that \(\langle g(\gamma), \sigma \rangle\) invertible). It returns the first valid pair found by iterators.

Parameters
qDimension of the pair searched.
foundReference to a Boolean variable. The method sets found to true if a valid pair is found, false otherwise.
tauCell of dimension q to pair.

◆ find_pairs_M() [1/2]

template<typename ChainComplex>
std::vector< Cell_pair > CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::find_pairs_M ( int q,
bool & found ) const

Finds all valid Cell_pair of dimension q for M.

The function searches all pairs of cells \((\pi, \gamma)\) with \(\pi\) PRIMARY and \(\gamma\) CRITICAL, valid for M (ie. such that \(\langle f(\pi), \gamma \rangle\) invertible). It returns a vector of such pairs.

Parameters
qDimension of the pair searched.
foundReference to a Boolean variable. The method sets found to true if a valid pair is found, false otherwise.

◆ find_pairs_M() [2/2]

template<typename ChainComplex>
std::vector< Cell_pair > CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::find_pairs_M ( int q,
bool & found,
size_t tau ) const

Finds all valid Cell_pair of dimension q for M cointaining tau.

The function searches all pairs of cells \((\pi, \gamma)\) with \(\pi\) PRIMARY and \(\gamma\) CRITICAL (one of them is tau), valid for M (ie. such that \(\langle f(\pi), \gamma \rangle\) invertible). It returns a vector of such pairs.

Parameters
qDimension of the pair searched.
foundReference to a Boolean variable. The method sets found to true if a valid pair is found, false otherwise.
tauCell of dimension q to pair.

◆ find_pairs_MW() [1/2]

template<typename ChainComplex>
std::vector< Cell_pair > CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::find_pairs_MW ( int q,
bool & found ) const

Finds all valid Cell_pair of dimension q for MW.

The function searches all pairs of cells \((\pi, \sigma)\) with \(\pi\) PRIMARY and \(\sigma\) SECONDARY, valid for MW (ie. such that \(\langle h_{q-1}\partial_q(\pi), \sigma \rangle\) invertible and \(\langle \partial_{q+1} h_q(\sigma), \pi \rangle\) invertible). It returns a vector of such pairs.

Parameters
qDimension of the pair searched.
foundReference to a Boolean variable. The method sets found to true if a valid pair is found, false otherwise.

◆ find_pairs_MW() [2/2]

template<typename ChainComplex>
std::vector< Cell_pair > CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::find_pairs_MW ( int q,
bool & found,
size_t tau ) const

Finds all valid Cell_pair of dimension q for W cointaining tau.

The function searches all pairs of cells \((\pi, \sigma)\) with \(\pi\) PRIMARY and \(\sigma\) SECONDARY (one of them is tau), valid for MW (ie. such that \(\langle h_{q-1}\partial_q(\pi), \sigma \rangle\) invertible and \(\langle \partial_{q+1} h_q(\sigma), \pi \rangle\) invertible). It returns a vector of such pairs.

Parameters
qDimension of the pair searched.
foundReference to a Boolean variable. The method sets found to true if a valid pair is found, false otherwise.
tauCell of dimension q to pair.

◆ find_pairs_W() [1/2]

template<typename ChainComplex>
std::vector< Cell_pair > CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::find_pairs_W ( int q,
bool & found ) const

Finds all valid Cell_pair of dimension q for W.

The function searches all pairs of cells \((\sigma, \gamma)\) with \(\sigma\) SECONDARY and \(\gamma\) CRITICAL, valid for W (ie. such that \(\langle g(\gamma), \sigma \rangle\) invertible). It returns a vector of such pairs.

Parameters
qDimension of the pair searched.
foundReference to a Boolean variable. The method sets found to true if a valid pair is found, false otherwise.

◆ find_pairs_W() [2/2]

template<typename ChainComplex>
std::vector< Cell_pair > CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::find_pairs_W ( int q,
bool & found,
size_t tau ) const

Finds all valid Cell_pair of dimension q for W cointaining tau.

The function searches all pairs of cells \((\sigma, \gamma)\) with \(\sigma\) SECONDARY and \(\gamma\) CRITICAL (one of them is tau), valid for W (ie. such that \(\langle g(\gamma), \sigma \rangle\) invertible). It returns the first valid pair found by iterators. It returns a vector of such pairs.

Parameters
qDimension of the pair searched.
foundReference to a Boolean variable. The method sets found to true if a valid pair is found, false otherwise.
tauCell of dimension q to pair.

◆ get_annotation()

template<typename ChainComplex>
Column_chain CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::get_annotation ( Column_chain chain,
int dim ) const

Gets the annotation of a cycle in the homology basis.

The method returns the image of a cycle by the morphism \(f\), that is, a linear combination of critical cells (corresponding to the decomposition of the cycle in the homology basis). If the annotation has a single non zero coefficient for a given critical cell \(\sigma\), then the cycle belongs to the class of the homology generator \(g(\sigma)\).

Warning
Will raise an error is the chain provided is not a cycle.
Precondition
The HDVF must be perfect.
Parameters
chainThe cycle to annotate in the homology basis.
dimDimension of the cycle.
Exceptions
Invalid_argumentIf the `chain` provided is not a cycle, raises a `std::invalid_argument` exception.

◆ get_coannotation()

template<typename ChainComplex>
Row_chain CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::get_coannotation ( Row_chain chain,
int dim ) const

Gets the co-annotation of a co-cycle in the cohomology basis.

The method returns the image of a co-cycle by the morphism \(g^*\), that is, a linear combination of critical cells (corresponding to the decomposition of the co-cycle in the cohomology basis). If the annotation has a single non zero coefficient for a given critical cell \(\sigma\), then the co-cycle belongs to the class of the cohomology generator \(f^*(\sigma)\).

Warning
Will raise an error is the chain provided is not a co-cycle.
The HDVF must be perfect.
Parameters
chainThe co-cycle to annotate in the homology basis.
dimDimension of the co-cycle.
Exceptions
Invalid_argumentIf the `chain` provided is not a co-cycle, raises a `std::invalid_argument` exception.

◆ hd() [1/2]

template<typename ChainComplex>
Column_chain CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::hd ( size_t sigma,
int q )

Computes \(h_{q-1}\circ \partial_q(\sigma)\).

The \(h_{q-1}\circ \partial_q\) function is used both in MW operation and in tri-partitions. As the matrix is not stored in the reduction, we provide methods to compute if efficiently.

Parameters
sigmaIndex of the cell
qDimension of the cell

◆ hd() [2/2]

template<typename ChainComplex>
Coefficient_ring CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::hd ( size_t sigma,
size_t tau,
int q )

Computes \(\langle h_{q-1}\circ \partial_q(\sigma), \tau\rangle\).

The \(h_{q-1}\circ \partial_q\) function is used both in MW operation and in tri-partitions. As the matrix is not stored in the reduction, we provide methods to compute if efficiently.

Parameters
sigmaIndex of the first cell
tauIndex of the second cell
qDimension of the cell

◆ is_valid_pair_for_M()

template<typename ChainComplex>
bool CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::is_valid_pair_for_M ( size_t pi,
size_t gamma,
int q )

Checks if the pair of cells \((\pi, \gamma)\), of dimension q, is valid for M.

The pair is valid if \(\langle \mathrm f(\pi),\gamma\rangle\) is invertible.

Parameters
piIndex of the first cell (dimension q).
gammaIndex of the second cell (dimension q+1).
qDimension of cells.

◆ is_valid_pair_for_MW()

template<typename ChainComplex>
bool CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::is_valid_pair_for_MW ( size_t pi,
size_t sigma,
int q )

Checks if the pair of cells \((\pi, \sigma)\), of dimension q, is valid for MW.

The pair is valid if \(\langle \parital h(\pi),\sigma\rangle \text{ and } \langle h\partial(\sigma),\pi\rangle\) is invertible.

Parameters
piIndex of the first cell.
sigmaIndex of the second cell.
qDimension of cells.

◆ is_valid_pair_for_R()

template<typename ChainComplex>
bool CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::is_valid_pair_for_R ( size_t pi,
size_t sigma,
int q )

Checks if the pair of cells \((\pi, \sigma)\), of dimensions q / q+1, is valid for R.

The pair is valid if \(\langle h(\pi),\sigma\rangle\) is invertible.

Parameters
piIndex of the first cell.
sigmaIndex of the second cell.
qLower dimension of cells.

◆ is_valid_pair_for_W()

template<typename ChainComplex>
bool CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::is_valid_pair_for_W ( size_t sigma,
size_t gamma,
int q )

Checks if the pair of cells \((\sigma, \gamma)\), of dimension q, is valid for W.

The pair is valid if \(\langle \mathrm g(\gamma),\sigma\rangle\) is invertible.

Parameters
sigmaIndex of the first cell.
gammaIndex of the second cell.
qDimension of cells.

◆ M() [1/2]

template<typename ChainComplex>
void CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::M ( const Cell_pair & p)

M operation.

A pair of cells \((\pi, \gamma)\) of dimension q, with \(\pi\) PRIMARY and \(\gamma\) CRITICAL, is valid for M if \(\langle f(\pi), \gamma \rangle\) is invertible. After the M operation, \(\pi\) becomes CRITICAL and \(\gamma\) become PRIMARY. The M method updates the reduction accordingly (in time \(\mathcal O(n^2)\)).

Parameters
pArgument Cell_pair containing \(\pi\), \(\gamma\) and the dimension of the pair.

◆ M() [2/2]

template<typename ChainComplex>
void CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::M ( size_t pi,
size_t gamma,
int q )

M operation.

A pair of cells \((\pi, \gamma)\) of dimension q, with \(\pi\) PRIMARY and \(\gamma\) CRITICAL, is valid for M if \(\langle f(\pi), \gamma \rangle\) is invertible. After the M operation, \(\pi\) becomes CRITICAL and \(\gamma\) become PRIMARY. The M method updates the reduction accordingly (in time \(\mathcal O(n^2)\)).

Parameters
piFirst cell of the pair (dimension q)
gammaSecond cell of the pair (dimension q)
qDimension of the pair
Exceptions
Invalid_operationIf `q` is the dimension of the complex, `M`operation is not valid and the method raises a `std::runtime_error` exception.
Invalid_argumentsIf \(\langle f(\pi), \gamma \rangle\) is not invertible, raises a `std::invalid_argument` exception.
Incorrect_hdvf_optionsOperations can be computed only under HDVF_FULL options, raises a `std::runtime_error` exception otherwise.

◆ MW() [1/2]

template<typename ChainComplex>
void CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::MW ( const Cell_pair & p)

MW operation.

A pair of cells \((\pi, \sigma)\) of dimension q, with \(\pi\) PRIMARY and \(\sigma\) SECONDARY, is valid for MW if \(\langle h_{q-1}\partial_q(\pi), \sigma \rangle\) is invertible and \(\langle \partial_{q+1} h_q(\sigma), \pi \rangle\) is invertible. After the MW operation, \(\pi\) becomes SECONDARY and \(\sigma\) become PRIMARY. The MW method updates the reduction accordingly (in time \(\mathcal O(n^2)\)).

Parameters
pArgument Cell_pair containing \(\pi\), \(\sigma\) and the dimension of the pair.

◆ MW() [2/2]

template<typename ChainComplex>
void CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::MW ( size_t pi,
size_t sigma,
int q )

MW operation.

A pair of cells \((\pi, \sigma)\) of dimension q, with \(\pi\) PRIMARY and \(\sigma\) SECONDARY, is valid for MW if \(\langle h_{q-1}\partial_q(\pi), \sigma \rangle\) is invertible and \(\langle \partial_{q+1} h_q(\sigma), \pi \rangle\) is invertible. After the MW operation, \(\pi\) becomes SECONDARY and \(\sigma\) become PRIMARY. The MW method updates the reduction accordingly (in time \(\mathcal O(n^2)\)).

Parameters
piFirst cell of the pair (dimension q)
sigmaSecond cell of the pair (dimension q)
qDimension of the pair
Exceptions
Invalid_operationIf `q` is 0 or the dimension of the complex, `MW`operation is not valid and the method raises a `std::runtime_error` exception.
Invalid_argumentsIf \(\langle h_{q-1}\partial_q(\pi), \sigma \rangle\) or \(\langle \partial_{q+1} h_q(\sigma), \pi \rangle\) are not invertible, raises a `std::invalid argument` exception.
Incorrect_hdvf_optionsOperations can be computed only under HDVF_FULL options, raises a `std::runtime_error` exception otherwise.

◆ operator=()

template<typename ChainComplex>
Hdvf & CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::operator= ( const Hdvf< ChainComplex > & hdvf)

Affectation operator.

Exceptions
Invalid_underlying_complexIf `hdvf` does not share the same underlying complex, raises a `std::runtime_error`.

◆ R() [1/2]

template<typename ChainComplex>
void CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::R ( const Cell_pair & p)

R operation (cancels a A operation).

A pair of cells \((\pi, \sigma)\) of respective dimension q and q+1, with \(\pi\) PRIMARY and \(\sigma\) SECONDARY, is valid for R if \(\langle h(\pi), \sigma \rangle\) is invertible. After the R operation, \(\pi\) and \(\sigma\) become CRITICAL. The R method updates the reduction accordingly (in time \(\mathcal O(n^2)\)).

Parameters
pArgument Cell_pair containing \(\pi\), \(\sigma\) and the dimension of the pair.

◆ R() [2/2]

template<typename ChainComplex>
void CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::R ( size_t pi,
size_t sigma,
int q )

R operation (cancels a A operation).

A pair of cells \((\pi, \sigma)\) of respective dimension q and q+1, with \(\pi\) PRIMARY and \(\sigma\) SECONDARY, is valid for R if \(\langle h(\pi), \sigma \rangle\) is invertible. After the R operation, \(\pi\) and \(\sigma\) become CRITICAL. The R method updates the reduction accordingly (in time \(\mathcal O(n^2)\)).

Parameters
piFirst cell of the pair (dimension q)
sigmaSecond cell of the pair (dimension q+1)
qDimension of the pair
Exceptions
Invalid_argumentsIf \(\langle h(\pi), \sigma \rangle\) is not invertible, raises a `std::invalid_argument` exception.
Incorrect_hdvf_optionsOperations can be computed only under HDVF_FULL options, raises a `std::runtime_error` exception otherwise.

◆ W() [1/2]

template<typename ChainComplex>
void CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::W ( const Cell_pair & p)

W operation.

A pair of cells \((\sigma, \gamma)\) of dimension q, with \(\sigma\) SECONDARY and \(\gamma\) CRITICAL, is valid for W if \(\langle g(\gamma), \sigma \rangle\) is invertible. After the W operation, \(\sigma\) becomes CRITICAL and \(\gamma\) become SECONDARY. The W method updates the reduction accordingly (in time \(\mathcal O(n^2)\)).

Parameters
pArgument Cell_pair containing \(\sigma\), \(\gamma\) and the dimension of the pair.

◆ W() [2/2]

template<typename ChainComplex>
void CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::W ( size_t sigma,
size_t gamma,
int q )

W operation.

A pair of cells \((\sigma, \gamma)\) of dimension q, with \(\sigma\) SECONDARY and \(\gamma\) CRITICAL, is valid for W if \(\langle g(\gamma), \sigma \rangle\) is invertible. After the W operation, \(\sigma\) becomes CRITICAL and \(\gamma\) become SECONDARY. The W method updates the reduction accordingly (in time \(\mathcal O(n^2)\)).

Parameters
sigmaFirst cell of the pair (dimension q)
gammaSecond cell of the pair (dimension q)
qDimension of the pair
Exceptions
Invalid_operationIf `q` is 0, `W`operation is not valid and the method raises a `std::runtime_error` exception.
Invalid_argumentsIf \(\langle g(\gamma), \sigma \rangle\) is not invertible, raises a `std::invalid_argument` exception.
Incorrect_hdvf_optionsOperations can be computed only under HDVF_FULL options, raises a `std::runtime_error` exception otherwise.

◆ z()

template<typename ChainComplex>
Column_chain CGAL::Homological_discrete_vector_field::Hdvf< ChainComplex >::z ( size_t sigma,
int q )

Compute \(z_q\) function on a cell of dimension q.

This function was first defined in tri-partitions; formally \(z_q = \mathrm{Id} - h_{q-1}\circ \partial_q\).

When the HDVF is perfect, \(z_q(\sigma)\) is the canonical cycle associated to \(\sigma\). Intuitively:

  • if \(\sigma\) is PRIMARY, \(z_q(\sigma)\) is a chain of SECONDARY cells ; if the HDVF is perfect \(z_q(\sigma)\) is a cycle (the unique cycle containing \(\sigma\) and SECONDARY cells).
  • if \(\sigma\) is SECONDARY, this cycle is null
  • if \(\sigma\) is CRITICAL, \(z_q(\sigma)\) matches \(g(\sigma)\) ; if the HDVF is perfect \(z_q(\sigma)\) hence provides the homology generator associated to \(\sigma\)).

Moreover, in HDVF_persistent, z function provides persistent homology generators.

Parameters
sigmaCell index.
qCell dimension.