TTK
Loading...
Searching...
No Matches
Public Types | Public Member Functions | Protected Attributes | List of all members
ttk::PersistenceDiagram Class Reference
base

TTK processing package for the computation of persistence diagrams. More...

#include <PersistenceDiagram.h>

Inheritance diagram for ttk::PersistenceDiagram:
ttk::Debug ttk::BaseClass ttkPersistenceDiagram ttkPersistenceDiagramApproximation

Public Types

enum class  BACKEND {
  FTM = 0 , PROGRESSIVE_TOPOLOGY = 1 , DISCRETE_MORSE_SANDWICH = 2 , APPROXIMATE_TOPOLOGY = 3 ,
  PERSISTENT_SIMPLEX = 4 , DISCRETE_MORSE_SANDWICH_MPI = 5
}
 

Public Member Functions

 PersistenceDiagram ()
 
void setBackend (const BACKEND be)
 
void setComputeMinSad (const bool data)
 
void setComputeSadSad (const bool data)
 
void setComputeSadMax (const bool data)
 
template<typename scalarType, typename triangulationType>
void augmentPersistenceDiagram (std::vector< PersistencePair > &persistencePairs, const scalarType *const scalars, const triangulationType *triangulation)
 Complete a ttk::DiagramType instance with scalar field values (useful for persistence) and 3D coordinates of critical vertices.
 
ttk::CriticalType getNodeType (ftm::FTMTree_MT *tree, ftm::TreeType treeType, const SimplexId vertexId) const
 
void sortPersistenceDiagram (std::vector< PersistencePair > &diagram, const SimplexId *const offsets) const
 
template<typename scalarType>
int computeCTPersistenceDiagram (ftm::FTMTreePP &tree, const std::vector< std::tuple< ttk::SimplexId, ttk::SimplexId, scalarType, bool > > &pairs, std::vector< PersistencePair > &diagram) const
 
template<typename scalarType, class triangulationType>
int execute (std::vector< PersistencePair > &CTDiagram, const scalarType *inputScalars, const size_t scalarsMTime, const SimplexId *inputOffsets, const triangulationType *triangulation, const std::vector< bool > *updateMask=nullptr)
 
template<typename scalarType, class triangulationType>
int executeFTM (std::vector< PersistencePair > &CTDiagram, const scalarType *inputScalars, const SimplexId *inputOffsets, const triangulationType *triangulation)
 
template<class triangulationType>
int executeProgressiveTopology (std::vector< PersistencePair > &CTDiagram, const SimplexId *inputOffsets, const triangulationType *triangulation)
 
template<typename scalarType, class triangulationType>
int executeApproximateTopology (std::vector< PersistencePair > &CTDiagram, const scalarType *inputScalars, const triangulationType *triangulation)
 
template<class triangulationType>
int executePersistentSimplex (std::vector< PersistencePair > &CTDiagram, const SimplexId *inputOffsets, const triangulationType *triangulation)
 
template<typename scalarType, class triangulationType>
int executeDiscreteMorseSandwich (std::vector< PersistencePair > &CTDiagram, const scalarType *inputScalars, const size_t scalarsMTime, const SimplexId *inputOffsets, const triangulationType *triangulation, const std::vector< bool > *updateMask=nullptr)
 
template<class triangulationType>
void checkProgressivityRequirement (const triangulationType *triangulation)
 
template<class triangulationType>
void checkManifold (const triangulationType *const triangulation)
 
void preconditionTriangulation (AbstractTriangulation *triangulation)
 
void setOutputMonotonyOffsets (void *data)
 
void setOutputOffsets (void *data)
 
void setOutputScalars (void *data)
 
void setDeltaApproximate (double data)
 
template<class triangulationType>
void checkProgressivityRequirement (const triangulationType *ttkNotUsed(triangulation))
 
- Public Member Functions inherited from ttk::Debug
 Debug ()
 
 ~Debug () override
 
virtual int setDebugLevel (const int &debugLevel)
 
int setWrapper (const Wrapper *wrapper) override
 
int printMsg (const std::string &msg, const debug::Priority &priority=debug::Priority::INFO, const debug::LineMode &lineMode=debug::LineMode::NEW, std::ostream &stream=std::cout) const
 
int printMsg (const std::vector< std::string > &msgs, const debug::Priority &priority=debug::Priority::INFO, const debug::LineMode &lineMode=debug::LineMode::NEW, std::ostream &stream=std::cout) const
 
int printErr (const std::string &msg, const debug::LineMode &lineMode=debug::LineMode::NEW, std::ostream &stream=std::cerr) const
 
int printWrn (const std::string &msg, const debug::LineMode &lineMode=debug::LineMode::NEW, std::ostream &stream=std::cerr) const
 
int printMsg (const std::string &msg, const double &progress, const double &time, const int &threads, const double &memory, const debug::LineMode &lineMode=debug::LineMode::NEW, const debug::Priority &priority=debug::Priority::PERFORMANCE, std::ostream &stream=std::cout) const
 
int printMsg (const std::string &msg, const double &progress, const double &time, const debug::LineMode &lineMode=debug::LineMode::NEW, const debug::Priority &priority=debug::Priority::PERFORMANCE, std::ostream &stream=std::cout) const
 
int printMsg (const std::string &msg, const double &progress, const double &time, const int &threads, const debug::LineMode &lineMode=debug::LineMode::NEW, const debug::Priority &priority=debug::Priority::PERFORMANCE, std::ostream &stream=std::cout) const
 
int printMsg (const std::string &msg, const double &progress, const debug::LineMode &lineMode=debug::LineMode::NEW, const debug::Priority &priority=debug::Priority::PERFORMANCE, std::ostream &stream=std::cout) const
 
int printMsg (const std::string &msg, const double &progress, const debug::Priority &priority, const debug::LineMode &lineMode=debug::LineMode::NEW, std::ostream &stream=std::cout) const
 
int printMsg (const std::vector< std::vector< std::string > > &rows, const debug::Priority &priority=debug::Priority::INFO, const bool hasHeader=true, const debug::LineMode &lineMode=debug::LineMode::NEW, std::ostream &stream=std::cout) const
 
int printMsg (const debug::Separator &separator, const debug::LineMode &lineMode=debug::LineMode::NEW, const debug::Priority &priority=debug::Priority::INFO, std::ostream &stream=std::cout) const
 
int printMsg (const debug::Separator &separator, const debug::Priority &priority, const debug::LineMode &lineMode=debug::LineMode::NEW, std::ostream &stream=std::cout) const
 
int printMsg (const std::string &msg, const debug::Separator &separator, const debug::LineMode &lineMode=debug::LineMode::NEW, const debug::Priority &priority=debug::Priority::INFO, std::ostream &stream=std::cout) const
 
void setDebugMsgPrefix (const std::string &prefix)
 
- Public Member Functions inherited from ttk::BaseClass
 BaseClass ()
 
virtual ~BaseClass ()=default
 
int getThreadNumber () const
 
virtual int setThreadNumber (const int threadNumber)
 

Protected Attributes

bool IgnoreBoundary {false}
 
ftm::FTMTreePP contourTree_ {}
 
dcg::DiscreteGradient dcg_ {}
 
PersistentSimplexPairs psp_ {}
 
DiscreteMorseSandwich dms_ {}
 
BACKEND BackEnd {BACKEND::DISCRETE_MORSE_SANDWICH}
 
ttk::ProgressiveTopology progT_ {}
 
ttk::ApproximateTopology approxT_ {}
 
int StartingResolutionLevel {0}
 
int StoppingResolutionLevel {-1}
 
bool UseTasks {true}
 
bool IsResumable {false}
 
double TimeLimit {}
 
void * outputScalars_ {}
 
void * outputOffsets_ {}
 
void * outputMonotonyOffsets_ {}
 
double Epsilon
 
- Protected Attributes inherited from ttk::Debug
int debugLevel_
 
std::string debugMsgPrefix_
 
std::string debugMsgNamePrefix_
 
- Protected Attributes inherited from ttk::BaseClass
bool lastObject_
 
int threadNumber_
 
Wrapper * wrapper_
 

Additional Inherited Members

- Protected Member Functions inherited from ttk::Debug
int printMsgInternal (const std::string &msg, const std::string &right, const std::string &filler, const debug::Priority &priority=debug::Priority::INFO, const debug::LineMode &lineMode=debug::LineMode::NEW, std::ostream &stream=std::cout) const
 
int printMsgInternal (const std::string &msg, const debug::Priority &priority, const debug::LineMode &lineMode, std::ostream &stream=std::cout) const
 
int welcomeMsg (std::ostream &stream)
 
- Static Protected Attributes inherited from ttk::Debug
static COMMON_EXPORTS debug::LineMode lastLineMode = ttk::debug::LineMode::NEW
 

Detailed Description

TTK processing package for the computation of persistence diagrams.

Compute the persistence diagram of a function on a triangulation. TTK assumes that the input dataset is made of only one connected component.

Author
Guillaume Favelier guill.nosp@m.aume.nosp@m..fave.nosp@m.lier.nosp@m.@lip6.nosp@m..fr
Julien Tierny julie.nosp@m.n.ti.nosp@m.erny@.nosp@m.lip6.nosp@m..fr
Date
September 2016.

This package computes the persistence diagram of the extremum-saddle pairs of an input scalar field. The X-coordinate of each pair corresponds to its birth, while its smallest and highest Y-coordinates correspond to its birth and death respectively.

In practice, each extremity of a persistence pair is represented by its vertexId and critical type. Based on that, the persistence of the pair and its 2D embedding can easily be obtained.

Persistence diagrams are useful and stable concise representations of the topological features of a data-set. It is useful to fine-tune persistence thresholds for topological simplification or for fast similarity estimations for instance.

Related publication
"Computational Topology: An Introduction"
Herbert Edelsbrunner and John Harer
American Mathematical Society, 2010

Five backends are available for the computation:

1) FTM
Related publication
"Task-based Augmented Contour Trees with Fibonacci Heaps" Charles Gueunet, Pierre Fortin, Julien Jomier, Julien Tierny IEEE Transactions on Parallel and Distributed Systems, 2019

2) Progressive Approach
Related publication
"A Progressive Approach to Scalar Field Topology"
Jules Vidal, Pierre Guillou, Julien Tierny
IEEE Transactions on Visualization and Computer Graphics, 2021

3) Discrete Morse Sandwich (default)
Related publication
"Discrete Morse Sandwich: Fast Computation of Persistence Diagrams for Scalar Data -- An Algorithm and A Benchmark"
Pierre Guillou, Jules Vidal, Julien Tierny
IEEE Transactions on Visualization and Computer Graphics, 2023.
arXiv:2206.13932, 2023.
Fast and versatile algorithm for persistence diagram computation.

4) Approximate Approach
Related publication
"Fast Approximation of Persistence Diagrams with Guarantees"
Jules Vidal, Julien Tierny
IEEE Symposium on Large Data Visualization and Analysis (LDAV), 2021

5) Persistent Simplex
This is a textbook (and very slow) algorithm, described in "Algorithm and Theory of Computation Handbook (Second Edition) - Special Topics and Techniques" by Atallah and Blanton on page 97.

6) Distributed Discrete Morse Sandwich
Related publication
"Distributed Discrete Morse Sandwich: Efficient Computation of Persistence Diagrams for Massive Scalar Data"
Eve Le Guillou, Pierre Fortin, Julien Tierny
IEEE Transactions on Parallel and Distributed Systems, 2025.
https://arxiv.org/abs/2505.21266, 2025.
Fast, hybrid MPI-OpenMP backend for large-scale datasets on supercomputers.

See also
ttkPersistenceDiagram.cpp for a usage example.

Online examples:

Definition at line 189 of file PersistenceDiagram.h.

Member Enumeration Documentation

◆ BACKEND

enum class ttk::PersistenceDiagram::BACKEND
strong
Enumerator
FTM 
PROGRESSIVE_TOPOLOGY 
DISCRETE_MORSE_SANDWICH 
APPROXIMATE_TOPOLOGY 
PERSISTENT_SIMPLEX 
DISCRETE_MORSE_SANDWICH_MPI 

Definition at line 192 of file PersistenceDiagram.h.

Constructor & Destructor Documentation

◆ PersistenceDiagram()

PersistenceDiagram::PersistenceDiagram ( )

Definition at line 8 of file PersistenceDiagram.cpp.

Member Function Documentation

◆ augmentPersistenceDiagram()

template<typename scalarType, typename triangulationType>
void ttk::PersistenceDiagram::augmentPersistenceDiagram ( std::vector< PersistencePair > & persistencePairs,
const scalarType *const scalars,
const triangulationType * triangulation )

Complete a ttk::DiagramType instance with scalar field values (useful for persistence) and 3D coordinates of critical vertices.

Definition at line 438 of file PersistenceDiagram.h.

◆ checkManifold()

template<class triangulationType>
void ttk::PersistenceDiagram::checkManifold ( const triangulationType *const triangulation)

Definition at line 1199 of file PersistenceDiagram.h.

◆ checkProgressivityRequirement() [1/2]

template<class triangulationType>
void ttk::PersistenceDiagram::checkProgressivityRequirement ( const triangulationType * triangulation)

◆ checkProgressivityRequirement() [2/2]

template<class triangulationType>
void ttk::PersistenceDiagram::checkProgressivityRequirement ( const triangulationType * ttkNotUsedtriangulation)

Definition at line 1183 of file PersistenceDiagram.h.

◆ computeCTPersistenceDiagram()

template<typename scalarType>
int ttk::PersistenceDiagram::computeCTPersistenceDiagram ( ftm::FTMTreePP & tree,
const std::vector< std::tuple< ttk::SimplexId, ttk::SimplexId, scalarType, bool > > & pairs,
std::vector< PersistencePair > & diagram ) const

Definition at line 386 of file PersistenceDiagram.h.

◆ execute()

template<typename scalarType, class triangulationType>
int ttk::PersistenceDiagram::execute ( std::vector< PersistencePair > & CTDiagram,
const scalarType * inputScalars,
const size_t scalarsMTime,
const SimplexId * inputOffsets,
const triangulationType * triangulation,
const std::vector< bool > * updateMask = nullptr )
Precondition
For this function to behave correctly in the absence of the VTK wrapper, ttk::preconditionOrderArray() needs to be called to fill the inputOffsets buffer prior to any computation (the VTK wrapper already includes a mechanism to automatically generate such a preconditioned buffer).
See also
examples/c++/main.cpp for an example use.

Definition at line 458 of file PersistenceDiagram.h.

◆ executeApproximateTopology()

template<typename scalarType, class triangulationType>
int ttk::PersistenceDiagram::executeApproximateTopology ( std::vector< PersistencePair > & CTDiagram,
const scalarType * inputScalars,
const triangulationType * triangulation )

Definition at line 1042 of file PersistenceDiagram.h.

◆ executeDiscreteMorseSandwich()

template<typename scalarType, class triangulationType>
int ttk::PersistenceDiagram::executeDiscreteMorseSandwich ( std::vector< PersistencePair > & CTDiagram,
const scalarType * inputScalars,
const size_t scalarsMTime,
const SimplexId * inputOffsets,
const triangulationType * triangulation,
const std::vector< bool > * updateMask = nullptr )

Definition at line 596 of file PersistenceDiagram.h.

◆ executeFTM()

template<typename scalarType, class triangulationType>
int ttk::PersistenceDiagram::executeFTM ( std::vector< PersistencePair > & CTDiagram,
const scalarType * inputScalars,
const SimplexId * inputOffsets,
const triangulationType * triangulation )

Definition at line 1129 of file PersistenceDiagram.h.

◆ executePersistentSimplex()

template<class triangulationType>
int ttk::PersistenceDiagram::executePersistentSimplex ( std::vector< PersistencePair > & CTDiagram,
const SimplexId * inputOffsets,
const triangulationType * triangulation )

Definition at line 524 of file PersistenceDiagram.h.

◆ executeProgressiveTopology()

template<class triangulationType>
int ttk::PersistenceDiagram::executeProgressiveTopology ( std::vector< PersistencePair > & CTDiagram,
const SimplexId * inputOffsets,
const triangulationType * triangulation )

Definition at line 1086 of file PersistenceDiagram.h.

◆ getNodeType()

CriticalType PersistenceDiagram::getNodeType ( ftm::FTMTree_MT * tree,
ftm::TreeType treeType,
const SimplexId vertexId ) const

Definition at line 15 of file PersistenceDiagram.cpp.

◆ preconditionTriangulation()

void ttk::PersistenceDiagram::preconditionTriangulation ( AbstractTriangulation * triangulation)
inline

Definition at line 311 of file PersistenceDiagram.h.

◆ setBackend()

void ttk::PersistenceDiagram::setBackend ( const BACKEND be)
inline

Definition at line 203 of file PersistenceDiagram.h.

◆ setComputeMinSad()

void ttk::PersistenceDiagram::setComputeMinSad ( const bool data)
inline

Definition at line 207 of file PersistenceDiagram.h.

◆ setComputeSadMax()

void ttk::PersistenceDiagram::setComputeSadMax ( const bool data)
inline

Definition at line 219 of file PersistenceDiagram.h.

◆ setComputeSadSad()

void ttk::PersistenceDiagram::setComputeSadSad ( const bool data)
inline

Definition at line 213 of file PersistenceDiagram.h.

◆ setDeltaApproximate()

void ttk::PersistenceDiagram::setDeltaApproximate ( double data)
inline

Definition at line 352 of file PersistenceDiagram.h.

◆ setOutputMonotonyOffsets()

void ttk::PersistenceDiagram::setOutputMonotonyOffsets ( void * data)
inline

Definition at line 343 of file PersistenceDiagram.h.

◆ setOutputOffsets()

void ttk::PersistenceDiagram::setOutputOffsets ( void * data)
inline

Definition at line 346 of file PersistenceDiagram.h.

◆ setOutputScalars()

void ttk::PersistenceDiagram::setOutputScalars ( void * data)
inline

Definition at line 349 of file PersistenceDiagram.h.

◆ sortPersistenceDiagram()

void ttk::PersistenceDiagram::sortPersistenceDiagram ( std::vector< PersistencePair > & diagram,
const SimplexId *const offsets ) const

Definition at line 46 of file PersistenceDiagram.cpp.

Member Data Documentation

◆ approxT_

ttk::ApproximateTopology ttk::PersistenceDiagram::approxT_ {}
protected

Definition at line 369 of file PersistenceDiagram.h.

◆ BackEnd

BACKEND ttk::PersistenceDiagram::BackEnd {BACKEND::DISCRETE_MORSE_SANDWICH}
protected

Definition at line 366 of file PersistenceDiagram.h.

◆ contourTree_

ftm::FTMTreePP ttk::PersistenceDiagram::contourTree_ {}
protected

Definition at line 358 of file PersistenceDiagram.h.

◆ dcg_

dcg::DiscreteGradient ttk::PersistenceDiagram::dcg_ {}
protected

Definition at line 359 of file PersistenceDiagram.h.

◆ dms_

DiscreteMorseSandwich ttk::PersistenceDiagram::dms_ {}
protected

Definition at line 361 of file PersistenceDiagram.h.

◆ Epsilon

double ttk::PersistenceDiagram::Epsilon
protected

Definition at line 381 of file PersistenceDiagram.h.

◆ IgnoreBoundary

bool ttk::PersistenceDiagram::IgnoreBoundary {false}
protected

Definition at line 357 of file PersistenceDiagram.h.

◆ IsResumable

bool ttk::PersistenceDiagram::IsResumable {false}
protected

Definition at line 374 of file PersistenceDiagram.h.

◆ outputMonotonyOffsets_

void* ttk::PersistenceDiagram::outputMonotonyOffsets_ {}
protected

Definition at line 380 of file PersistenceDiagram.h.

◆ outputOffsets_

void* ttk::PersistenceDiagram::outputOffsets_ {}
protected

Definition at line 379 of file PersistenceDiagram.h.

◆ outputScalars_

void* ttk::PersistenceDiagram::outputScalars_ {}
protected

Definition at line 378 of file PersistenceDiagram.h.

◆ progT_

ttk::ProgressiveTopology ttk::PersistenceDiagram::progT_ {}
protected

Definition at line 368 of file PersistenceDiagram.h.

◆ psp_

PersistentSimplexPairs ttk::PersistenceDiagram::psp_ {}
protected

Definition at line 360 of file PersistenceDiagram.h.

◆ StartingResolutionLevel

int ttk::PersistenceDiagram::StartingResolutionLevel {0}
protected

Definition at line 371 of file PersistenceDiagram.h.

◆ StoppingResolutionLevel

int ttk::PersistenceDiagram::StoppingResolutionLevel {-1}
protected

Definition at line 372 of file PersistenceDiagram.h.

◆ TimeLimit

double ttk::PersistenceDiagram::TimeLimit {}
protected

Definition at line 375 of file PersistenceDiagram.h.

◆ UseTasks

bool ttk::PersistenceDiagram::UseTasks {true}
protected

Definition at line 373 of file PersistenceDiagram.h.

The documentation for this class was generated from the following files:
Generated on Fri Apr 10 2026 10:02:13 for TTK by doxygen 1.13.2