DOCSEARCHbyAlgolia
Submit Docs

Dionysus 2

repository·master·Indexed 41 days ago

https://github.com/mrzv/dionysus

A C++ library with Python bindings for computing persistent homology, persistence diagrams, and related geometric structures in topological data analysis. Version 2.2.3 features support for homology and cohomology persistence, zigzag persistence, vineyards for linear homotopies, and tools for calculating Wasserstein and bottleneck distances between diagrams.

Tokens
13K
Snippets
46
Records
58
Agent score
50%

What's inside Dionysus

  1. Dionysus 2 Overview and Dependencies

    master

    Dionysus 2 is a C++ computational topology package focused on persistent homology, featuring Python bindings via PyBind11.

    Key Features:

    • Supports arbitrary fields in algorithms.
    • Includes omni-field persistence, Wasserstein and bottleneck distance computation, and Matplotlib-based plotting.
    • Provides vineyards for updating persistence under adjacent filtration transpositions and linear homotopies.
    • Better integration with NumPy.

    Dependencies:

    • Boost (>= 1.55): Required for building, but no libraries are linked.
    • PyBind11: Used for Python bindings.
    • SciPy (Optional): Required for the LSQR routine used in circular coordinates.
    • Matplotlib (Optional): Required for plotting routines.

  2. Dionysus 2 Dependencies and Requirements

    master

    Dionysus 2 is a C++ library with Python bindings. Ensure your environment meets the following requirements:

    Core Requirements:

    • Boost: Version 1.55 or higher is required (though Dionysus 2 does not link any Boost libraries directly, making it easier to build).
    • GCC: If using GCC, the oldest supported version is 5.4.
    • PyBind11: Used for Python bindings (replaces the old dependency on Boost.Python).

    Optional Dependencies:

    • SciPy: Required for the LSQR routine used in circular computations.
    • Matplotlib: Required for plotting routines.

    Key Features & Integrations:

    • NumPy: Better integration with NumPy for data handling.
    • Vineyards: Allows updating persistence under adjacent filtration transpositions and linear homotopies.
    • Alpha shape filtrations: Available via DioDe.
    • Fast-zigzag-apex: Efficiently computes zigzag persistence and compatible representatives.

  3. Understand numeric precision in Dionysus

    master
    Dionysus uses C++ float (single precision) for storing simplex filtration values and persistence diagram coordinates. When you provide Python float or NumPy double inputs, they will be rounded to single precision when converted into simplex data or diagram coordinates. Be mindful of this precision loss when working with very small differences in filtration values.

  4. How Vineyards track persistence changes

    master

    Vineyards in Dionysus are used to track how persistence pairings and diagram points evolve as the filtration order changes. There are two primary interfaces:

    1. VineyardV and VineyardU: These maintain a reduced boundary matrix under explicit adjacent transpositions. VineyardV is the default (using the matrix_v method), while VineyardU maintains trails (using the matrix_u method).
    2. vineyard_linear_homotopy: This function computes the adjacent transpositions induced by a straight-line interpolation between two filtration functions and records the resulting vines.

    Stable cell IDs are used throughout these interfaces. Even when cells are transposed (swapped in position), their stable IDs remain constant, allowing methods like pair(), low(), pivot(), reduced_column(), chain(), and trail() to reference them reliably.

    import dionysus as d
# Example of initializing a VineyardV from a filtration
f = d.Filtration([[0], [1], [0, 1]])
v = d.Vineyard(f, field=d.Zp(2))
print(isinstance(v, d.VineyardV)) # True

  5. Understand the structure of zigzag persistence diagrams

    master

    The diagrams returned by dionysus.init_zigzag_diagrams are organized by dimension. Each dimension contains a dictionary with up to four entries, representing different extended persistence diagram types. These types correspond to different interval types in zigzag persistence:

    • cc: closed-closed
    • co: closed-open
    • oc: open-closed
    • oo: open-open

    Each entry in the dictionary contains points (tuples) representing the birth and death times.

  6. Construct symmetric upper-star filtrations

    master

    A symmetric upper-star filtration can be created by assigning the minimum vertex value to each simplex. In Dionysus, this is achieved by passing reverse = True to the dionysus.Filtration.sort method (or when using the fill_freudenthal helper).

    # Using the helper function
f_upper_star = d.fill_freudenthal(a, reverse=True)

# Or using the sort method on an existing filtration
filtration.sort(reverse=True)

  7. Compute persistence over all fields using OmniFieldPersistence

    master

    The OmniFieldPersistence abstraction allows you to compute persistence over all finite fields $\mathbb{Z}_p$ simultaneously by performing extra bookkeeping during the reduction process. This is useful for identifying which primes $p$ result in different homology groups or special reduction behaviors.

    To use this, pass a Filtration object to dionysus.omnifield_homology_persistence(f). The resulting object can be used to inspect special primes and generate persistence diagrams for specific primes.

    import dionysus as d

# Create a triangulation (e.g., Klein bottle)
klein_bottle = [[0], [1], [2], [3], [4], [5], [6], [7], [8],
               [0,1], [1,2], [2,0], [0,3], [3,4], [4,0],
               [1,5], [5,6], [6,2], [2,7], [7,8], [8,1],
               [3,5], [5,7], [7,3], [4,6], [6,8], [8,4],
               [0,5], [1,7], [2,3], [3,6], [5,8], [7,4],
               [4,2], [6,1], [8,0],
               [0,3,5], [0,1,5], [1,5,7], [1,2,7], [2,7,3], [2,3,0],
               [3,4,6], [3,5,6], [5,6,8], [5,7,8], [7,8,4], [7,3,4],
               [4,0,2], [4,6,2], [6,2,1], [6,8,1], [8,1,0], [8,4,0]]

f = d.Filtration(klein_bottle)

# Compute persistence over all fields
ofp = d.omnifield_homology_persistence(f)

  8. Configure Python bindings for manual builds

    master

    If you built Dionysus 2 from source, you must make the Python bindings discoverable by Python. You can do this by either launching Python from the build/bindings/python directory or by adding that directory to your PYTHONPATH environment variable.

    To add it to your shell configuration (e.g., ~/.bashrc or ~/.zshrc):

    export PYTHONPATH=.../build/bindings/python:$PYTHONPATH

    (Note: Replace ... with the actual absolute path to your build directory.)

    export PYTHONPATH=.../build/bindings/python:$PYTHONPATH

  9. Visualize diagram density with plot_diagram_density

    master

    When a persistence diagram is very dense, use dionysus.plot.plot_diagram_density to view a histogram of the point density instead of a scatter plot.

    import dionysus as d
# Assuming dgms is a list of diagrams
d.plot.plot_diagram_density(dgms[1], show=True)

  11. Install Dionysus 2 via pip

    master

    The simplest way to install Dionysus 2 as a Python package is using pip. You can install it from PyPI or directly from the development repository to get the latest version.

    To install from PyPI:

    pip install --verbose dionysus

    To install the latest version directly from the GitHub repository:

    pip install --verbose git+https://github.com/mrzv/dionysus.git

    If you already have a version installed and want to update it, use the --upgrade flag.

  12. Construct lower-star and upper-star filtrations using fill_freudenthal

    master

    To compute the persistent homology of sublevel sets of a continuous function defined on a grid, you can use the fill_freudenthal helper function. This function builds a Freudenthal triangulation on a grid where the values are provided by a NumPy array.

    • Lower-star filtration: Assigns to each simplex the value of its maximum vertex. This is the default behavior of fill_freudenthal(a).
    • Upper-star filtration: Assigns to each simplex the minimum of its vertices. To construct this, pass reverse = True to the function.

    Once the filtration is constructed, you can compute persistence using homology_persistence and initialize diagrams with init_diagrams.

    import dionysus as d
import numpy as np

# Create a random 10x10 grid of values
a = np.random.random((10, 10))

# Construct lower-star filtration
f_lower_star = d.fill_freudenthal(a)

# Construct upper-star filtration
f_upper_star = d.fill_freudenthal(a, reverse=True)

# Compute persistence and initialize diagrams
p = d.homology_persistence(f_lower_star)
dgms = d.init_diagrams(p, f_lower_star)

# Plot the diagrams
d.plot.plot_diagram(dgms[0])
d.plot.plot_diagram(dgms[1])