Installation

Conda

The easiest way to install the Python version of GUDHI is using conda.

Compiling

The library uses c++14 and requires Boost ≥ 1.56.0, CMake ≥ 3.1 to generate makefiles, NumPy and Cython to compile the GUDHI Python module. It is a multi-platform library and compiles on Linux, Mac OSX and Visual Studio 2015.

On Windows , only Python ≥ 3.5 are available because of the required Visual Studio version.

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

GUDHI Python module compilation

To build the GUDHI Python module, run the following commands in a terminal:

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

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
# May require sudo or administrator privileges
make install

Test suites

To test your build, py.test is optional. Run the following 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'
make test

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
print(gudhi.__debug_info__)

You shall have something like:

Python version 2.7.15
Cython version 0.26.1
Numpy version 1.14.1
Eigen3 version 3.1.1
Installed modules are: off_reader;simplex_tree;rips_complex;
    cubical_complex;periodic_cubical_complex;reader_utils;witness_complex;
    strong_witness_complex;alpha_complex;
Missing modules are: bottleneck_distance;nerve_gic;subsampling;
    tangential_complex;persistence_graphical_tools;
    euclidean_witness_complex;euclidean_strong_witness_complex;
CGAL version 4.7.1000
GMP_LIBRARIES = /usr/lib/x86_64-linux-gnu/libgmp.so
GMPXX_LIBRARIES = /usr/lib/x86_64-linux-gnu/libgmpxx.so
TBB version 9107 found and used

Here, you can see that bottleneck_distance, nerve_gic, subsampling and tangential_complex are missing because of the CGAL version. persistence_graphical_tools is not available as matplotlib is not available. Unitary tests cannot be run as pytest is missing.

A complete configuration would be :

Python version 3.6.5
Cython version 0.28.2
Pytest version 3.3.2
Matplotlib version 2.2.2
Numpy version 1.14.5
Eigen3 version 3.3.4
Installed modules are: off_reader;simplex_tree;rips_complex;
    cubical_complex;periodic_cubical_complex;persistence_graphical_tools;
    reader_utils;witness_complex;strong_witness_complex;
    persistence_graphical_tools;bottleneck_distance;nerve_gic;subsampling;
    tangential_complex;alpha_complex;euclidean_witness_complex;
    euclidean_strong_witness_complex;
CGAL header only version 4.11.0
GMP_LIBRARIES = /usr/lib/x86_64-linux-gnu/libgmp.so
GMPXX_LIBRARIES = /usr/lib/x86_64-linux-gnu/libgmpxx.so
TBB version 9107 found and used

Documentation

To build the documentation, sphinx-doc and sphinxcontrib-bibtex are required. As the documentation is auto-tested, CGAL, Eigen, Matplotlib, NumPy 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

CGAL

Some GUDHI modules (cf. modules list), and few examples require CGAL, 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 requires CGAL version ≥ 4.11.0:

Eigen

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

The following examples require Eigen version ≥ 3.1.0:

SciPy

The persistence graphical tools module requires SciPy, a Python-based ecosystem of open-source software for mathematics, science, and engineering.

Threading Building Blocks

Intel® 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® TBB installed is recommended to parallelize and accelerate some GUDHI computations.

Bug reports and contributions

Please help us improving the quality of the GUDHI library. You may report bugs or suggestions to:

GUDHI is open to external contributions. If you want to join our development team, please contact us.