Multipers

Scikit-style multiparameter persistent homology python library. This librairy aims to provide easy to use and performant strategies for applied multiparameter topology. A non-exhaustive list of features can be found in the Features section.
Meant to be integrated in the Gudhi library.

Installation

Some dependencies are needed, e.g., using conda

conda create -n python311
conda activate python311
conda install python=3.11 numpy matplotlib gudhi scikit-learn scipy sympy tqdm shapely -c conda-forge
pip install filtration-domination pykeops

Other libraries may be required for some specific functions, e.g., pytorch for to compute the rank invariant.

Using pip (Recommended)

Precompiled versions, for linux and macos, are available on PyPI. Just use

pip install multipers

Building from source

Clone the repo, and in a terminal, in the root folder

conda install python=3.11 cxx-compiler boost tbb tbb-devel numpy matplotlib gudhi scikit-learn cython sympy tqdm cycler typing shapely -c conda-forge
pip install .

Mostly tested on latest everything on linux. For macos users, this command may fail, see a fix at the end.

How to use

To get a first idea on how this library works, we provide a few tutorial notebooks, in the tutorial folder.
If something is not clear, or a function not covered, feel free to open an issue to ask for an example (or open a PR with a new notebook).
As the example zoo is far from covering everything, don't hesitate to submit something if you find an interesting example.

Features, and linked projects

This librairy features a bunch of different functions and helpers. See below for a non-exhaustive list.
Filled box refers to implemented or interfaced code.

• Multiparameter Module Approximation provides the multiparameter simplicial structure, aswell as technics of approximating modules, via interval decompostion modules. It is also very useful for visualization.
• Stable Vectorization of Multiparameter Persistent Homology using Signed Barcodes as Measures provides fast representations of multiparameter persistence modules, by using their signed barcodes decompositions, and encoding it into signed measures. Implemented decompositions : Euler surfaces, Hilbert function, rank invariant (i.e. rectangles). It also provides representation technics for Machine Learning, i.e., Sliced Wasserstein kernels, Vectorizations.
• A Framework for Fast and Stable Representations of Multiparameter Persistent Homology Decompositions Provides a vectorization framework for interval decomposable modules, for Machine Learning. Currently implemented as an extension of MMA.
• Multiparameter Persistence Landscapes A vectoriazation technic for multiparameter persistence modules.
• Filtration-Domination in Bifiltered Graphs Allows for 2-parameter edge collapses for 1-critical clique complexes. Very useful to speed up, e.g., Rips-Codensity bifiltrations.
• Chunk Reduction for Multi-Parameter Persistent Homology Multi-filtration preprocessing algorithm.
• Computing Minimal Presentations and Bigraded Betti Numbers of 2-Parameter Persistent Homology Minimal presentation of multiparameter persistence modules, using mpfree. Hilbert Decomposition Signed Measures, and MMA decompositions can be computed using the mpfree backend.
• Delaunay Bifiltrations of Functions on Point Clouds Provides an alternative to function rips bifiltrations, using Delaunay complexes. Very good alternative to Rips-Density like bi-filtrations.
• Rivet Interactive two parameter persistence
• [Backend only] Projected distances for multi-parameter persistence modules Provides a strategy to estimate the convolution distance between multiparameter persistence module using projected barcodes. Implementation is a WIP.
• [Partial, and experimental] Efficient Two-Parameter Persistence Computation via Cohomology Minimal presentations for 2-parameter persistence algorithm.

If I missed something, or you want to add something, feel free to open an issue.

Authors

David Loiseaux,
Hannah Schreiber (Persistence backend code),
Luis Scoccola (Möbius inversion in python, degree-rips using persistable and RIVET),
Mathieu Carrière (Sliced Wasserstein)

Contributions

Feel free to contribute, report a bug on a pipeline, or ask for documentation by opening an issue.

For mac users

Due to apple's clang compiler, one may have to disable a compilator optimization to compile multipers: in the setup.py file, add the

-fno-aligned-new

line in the extra_compile_args list. You should have should end up with something like the following.

extensions = [
    Extension(
        f"multipers.{module}",
        sources=[
            f"multipers/{module}.pyx",
        ],
        language="c++",
        extra_compile_args=[
            "-Ofast",
            "-std=c++20",
            "-fno-aligned-new", # Uncomment this if you have trouble compiling on macos.
            "-Wall",
        ],
        include_dirs=cpp_dirs,
        define_macros=[("NPY_NO_DEPRECATED_API", "NPY_1_7_API_VERSION")],
        libraries=["tbb", "tbbmalloc"],
        library_dirs=library_dirs,
    )
    for module in cython_modules
]

Alternatives

One may try to use the clang compiler provided by conda or brew. If you have a simpler alternative, please let me know ;)