Installation

Packages

The easiest way to install the Python version of GUDHI is using pre-built packages. We recommend conda

conda install -c conda-forge gudhi

Gudhi is also available on PyPI

pip install gudhi

Third party packages are also available, for instance on Debian or Ubuntu

apt install python3-gudhi

In all cases, you may still want to install some of the optional run time dependencies.

Compiling

These instructions are for people who want to compile gudhi from source, they are unnecessary if you installed a binary package of Gudhi as above. They assume that you have downloaded a release, with a name like gudhi.3.X.Y.tar.gz, then run tar xf gudhi.3.X.Y.tar.gz, which created a directory gudhi.3.X.Y, hereinafter referred to as /path-to-gudhi/. If you are instead using a git checkout, beware that the paths are a bit different, and in particular the python/ subdirectory is actually src/python/ there.

The library uses c++17 and requires Boost \(\geq\) 1.71.0, CMake \(\geq\) 3.8, Python \(\geq\) 3.5, NumPy \(\geq\) 1.15.0, Cython \(\geq\) 0.27 and pybind11 to compile the GUDHI Python module. It is a multi-platform library and compiles on Linux, Mac OSX and Visual Studio 2017 or later.

If you have several Python/python installed, the version 2.X may be used by default, but you can force it by adding -DPython_ADDITIONAL_VERSIONS=3 to the cmake command.

GUDHI Python module compilation

After making sure that the Compilation dependencies are properly installed, one can build the GUDHI Python module, by running the following commands in a terminal:

cd /path-to-gudhi/
mkdir build
cd build/
cmake -DCMAKE_BUILD_TYPE=Release ..
cd python
make

Note

make python (or make in python directory) is only a CMake custom targets to shortcut python setup.py build_ext --inplace command. No specific other options (-j8 for parallel, or even make clean, …) are available. But one can use python setup.py ... specific options in the python directory:

python setup.py clean --all               # Clean former compilation
python setup.py build_ext -j 8 --inplace  # Build in parallel

GUDHI Python module installation

Once the compilation succeeds, one can add the GUDHI Python module path to the PYTHONPATH:

# For windows, you have to set PYTHONPATH environment variable
export PYTHONPATH='$PYTHONPATH:/path-to-gudhi/build/python'

Or install it definitely in your Python packages folder:

cd /path-to-gudhi/build/python
python setup.py install # add --user to the command if you do not have the permission
# Or 'pip install .'

Note

It does not take into account CMAKE_INSTALL_PREFIX. But one can use alternate location installation.

Test suites

To test your build, py.test is required. Run the following Ctest (CMake test driver program) command in a terminal:

cd /path-to-gudhi/build/python
# For windows, you have to set PYTHONPATH environment variable
export PYTHONPATH='$PYTHONPATH:/path-to-gudhi/build/python'
ctest

Note

One can use ctest specific options in the python directory:

# Launch tests in parallel on 8 cores and set failing tests in verbose mode
ctest -j 8 --output-on-failure

Debugging issues

If tests fail, please check your PYTHONPATH and try to import gudhi and check the errors. The problem can come from a third-party library bad link or installation.

If import gudhi succeeds, please have a look to debug information:

import gudhi as gd
print(gd.__debug_info__)
print("+ Installed modules are: " + gd.__available_modules)
print("+ Missing modules are: " + gd.__missing_modules)

You shall have something like:

Pybind11 version 2.8.1
Python version 3.7.12
Cython version 0.29.25
Numpy version 1.21.4
Boost version 1.77.0
+ Installed modules are: off_utils;simplex_tree;rips_complex;cubical_complex;periodic_cubical_complex;
    persistence_graphical_tools;reader_utils;witness_complex;strong_witness_complex;
+ Missing modules are: bottleneck;nerve_gic;subsampling;tangential_complex;alpha_complex;euclidean_witness_complex;
    euclidean_strong_witness_complex;

Here, you can see that the modules that need CGAL are missing, because CGAL is not installed. persistence_graphical_tools is installed, but its functions will produce an error as matplotlib is not available. Unitary tests cannot be run as pytest is missing.

A complete configuration would be :

Pybind11 version 2.8.1
Python version 3.9.7
Cython version 0.29.24
Pytest version 6.2.5
Matplotlib version 3.5.0
Numpy version 1.21.4
Scipy version 1.7.3
Scikit-learn version 1.0.1
POT version 0.8.0
HNSWlib found
PyKeOps version [pyKeOps]: 2.1
EagerPy version 0.30.0
TensorFlow version 2.7.0
Sphinx version 4.3.0
Sphinx-paramlinks version 0.5.2
pydata_sphinx_theme version 0.13.1
NetworkX version 3.0
Eigen3 version 3.4.0
Boost version 1.74.0
CGAL version 5.3
GMP_LIBRARIES = /usr/lib/x86_64-linux-gnu/libgmp.so
GMPXX_LIBRARIES = /usr/lib/x86_64-linux-gnu/libgmpxx.so
MPFR_LIBRARIES = /usr/lib/x86_64-linux-gnu/libmpfr.so
TBB version 2021.7.0 found and used
TBB_LIBRARY = /usr/lib/x86_64-linux-gnu/libtbb.so
TBB_MALLOC_LIBRARY = /usr/lib/x86_64-linux-gnu/libtbbmalloc.so
+ Installed modules are: bottleneck;off_utils;simplex_tree;rips_complex;cubical_complex;periodic_cubical_complex;
    persistence_graphical_tools;reader_utils;witness_complex;strong_witness_complex;nerve_gic;subsampling;
    tangential_complex;alpha_complex;euclidean_witness_complex;euclidean_strong_witness_complex;
+ Missing modules are:

Documentation

To build the documentation, sphinx-doc, sphinxcontrib-bibtex, sphinxcontrib-paramlinks and pydata-sphinx-theme \(\geq\) 0.8.0 are required. As the documentation is auto-tested, CGAL, Eigen, Matplotlib, NumPy, POT, Scikit-learn and SciPy are also mandatory to build the documentation.

Run the following commands in a terminal:

cd /path-to-gudhi/build/python
make sphinx

Optional third-party library

Compilation dependencies

These third party dependencies are detected by CMake. They have to be installed before performing the GUDHI Python module compilation.

CGAL

Some GUDHI modules (cf. modules list), and few examples require CGAL version \(\geq\) 5.1.0, a C++ library that provides easy access to efficient and reliable geometric algorithms.

The procedure to install this library according to your operating system is detailed here.

The following examples require CGAL:

• alpha_complex_diagram_persistence_from_off_file_example.py

• alpha_complex_from_points_example.py

• bottleneck_basic_example.py

• tangential_complex_plain_homology_from_off_file_example.py

• euclidean_strong_witness_complex_diagram_persistence_from_off_file_example.py

• euclidean_witness_complex_diagram_persistence_from_off_file_example.py

Eigen

Some GUDHI modules (cf. modules list), and few examples require Eigen version \(\geq\) 3.3.0, a C++ template library for linear algebra: matrices, vectors, numerical solvers, and related algorithms.

The following examples require Eigen:

• alpha_complex_diagram_persistence_from_off_file_example.py

• alpha_complex_from_points_example.py

• tangential_complex_plain_homology_from_off_file_example.py

• euclidean_strong_witness_complex_diagram_persistence_from_off_file_example.py

• euclidean_witness_complex_diagram_persistence_from_off_file_example.py

oneAPI Threading Building Blocks

Intel® oneAPI TBB lets you easily write parallel C++ programs that take full advantage of multicore performance, that are portable and composable, and that have future-proof scalability.

Having Intel® oneAPI TBB (version 20.19.7 or higher) installed is recommended to parallelize and accelerate some GUDHI computations.

Run time dependencies

These third party dependencies are detected by Python import mechanism at run time. They can be installed when required.

EagerPy

Some Python functions can handle automatic differentiation (possibly only when a flag enable_autodiff=True is used). In order to reduce code duplication, we use EagerPy which wraps arrays from PyTorch, TensorFlow and JAX in a common interface.

Joblib

Joblib is used both as a dependency of Scikit-learn, and directly for parallelism in some modules (KNearestNeighbors, pairwise_persistence_diagram_distances()).

Hnswlib

KNearestNeighbors can use the Python package Hnswlib as a backend if explicitly requested, to speed-up queries.

LaTeX

If a sufficiently complete LaTeX toolchain is available (including dvipng and ghostscript), the LaTeX option of matplotlib is enabled for prettier captions (cf. matplotlib text rendering with LaTeX). It also requires type1cm LaTeX package (not detected by matplotlib).

If you are facing issues with LaTeX rendering, like this one:

Traceback (most recent call last):
  File "/usr/lib/python3/dist-packages/matplotlib/texmanager.py", line 302, in _run_checked_subprocess
    report = subprocess.check_output(command,
...
! LaTeX Error: File `type1cm.sty' not found.
...

This is because the LaTeX package is not installed on your system. On Ubuntu systems you can install texlive-full (for all LaTeX packages), or more specific packages like texlive-latex-extra, cm-super.

You can still deactivate LaTeX rendering by saying:

import gudhi as gd
gd.persistence_graphical_tools._gudhi_matplotlib_use_tex=False

Matplotlib

The persistence graphical tools module requires Matplotlib, a Python 2D plotting library which produces publication quality figures in a variety of hardcopy formats and interactive environments across platforms.

The following examples require the Matplotlib:

• alpha_complex_diagram_persistence_from_off_file_example.py

• gudhi_graphical_tools_example.py

• periodic_cubical_complex_barcode_persistence_from_perseus_file_example.py

• rips_complex_diagram_persistence_from_off_file_example.py

• rips_persistence_diagram.py

• rips_complex_diagram_persistence_from_distance_matrix_file_example.py

• tangential_complex_plain_homology_from_off_file_example.py

• euclidean_strong_witness_complex_diagram_persistence_from_off_file_example.py

• euclidean_witness_complex_diagram_persistence_from_off_file_example.py

NetworkX

The GraphInducedComplex, MapperComplex and NerveComplex get_networkx methods require NetworkX, a Python library for studying and visualizing graphs and networks.

Pandas

Pandas is an optional Run time dependency of Scikit-learn. For instance sklearn.datasets.fetch_openml, used in Cubical complex persistence scikit-learn like interface example requires pandas with Scikit-learn \(\geq\) 1.5.0.

PyKeOps

KNearestNeighbors can use the Python package PyKeOps as a backend if explicitly requested, to speed-up queries using a GPU.

Python Optimal Transport

The Wasserstein distance module requires POT, a library that provides several solvers for optimization problems related to Optimal Transport.

PyTorch

PyTorch is currently only used as a dependency of PyKeOps, and in some tests.

Scikit-learn

The persistence representations module requires Scikit-learn, a Python-based ecosystem of open-source software for machine learning.

Some classes of the cover complex module also follow and require the Scikit-learn interface.

KNearestNeighbors can use the Python package Scikit-learn as a backend if explicitly requested.

SciPy

The persistence graphical tools and Wasserstein distance modules require SciPy, a Python-based ecosystem of open-source software for mathematics, science, and engineering.

KNearestNeighbors can use the Python package SciPy \(\geq\) 1.6.0 as a backend if explicitly requested.

TensorFlow

Perslay from the persistence representations module requires TensorFlow. The cubical complex, simplex tree and Rips complex modules require TensorFlow for incorporating them in neural nets.

TensorFlow is also used in some automatic differentiation tests.

Bug reports and contributions

Please help us improving the quality of the GUDHI library. You may report bugs or contact us for any suggestions.

GUDHI is open to external contributions. If you want to join our development team, please take some time to read our contributing guide.