Installation¶
Compiling¶
The library uses c++14 and requires Boost ≥ 1.56.0, CMake ≥ 3.1 to generate makefiles, NumPy, Cython and pybind11 to compile the GUDHI Python module. It is a multi-platform library and compiles on Linux, Mac OSX and Visual Studio 2017.
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¶
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 ..
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
# May require sudo or administrator privileges
make install
Note
make install
is only a
CMake custom targets
to shortcut python setup.py install
command.
It does not take into account CMAKE_INSTALL_PREFIX
.
But one can use python setup.py install ...
specific options in the python directory:
python setup.py install --prefix /home/gudhi # Install in /home/gudhi directory
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
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, 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, 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 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:
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.
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.
Hnswlib¶
KNearestNeighbors
can use the Python package
Hnswlib as a backend if explicitly
requested, to speed-up queries.
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:
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.
Scikit-learn¶
The persistence representations module require scikit-learn, a Python-based ecosystem of open-source software for machine learning.
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 as a backend if explicitly requested.
Bug reports and contributions¶
Please help us improving the quality of the GUDHI library. You may report bugs or suggestions to:
Contact: gudhi-users@lists.gforge.inria.fr
GUDHI is open to external contributions. If you want to join our development team, please contact us.