GUDHI installation

Table of Contents

• Compiling
  • Utilities and examples
  • Installation
  • Test suites
  • C++ documentation
  • Hello world !
• Optional third-party library
  • GMP
  • CGAL
  • Eigen
  • oneAPI Threading Building Blocks
• Bug reports and contributions

As GUDHI is a header only library, there is no need to install the library.

Examples of GUDHI headers inclusion can be found in Utilities and examples.

Compiling

The library uses c++17 and requires Boost ≥ 1.71.0 and CMake ≥ 3.8. It is a multi-platform library and compiles on Linux, Mac OSX and Visual Studio 2017.

Utilities and examples

To build the utilities, run the following commands in a terminal:

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

By default, examples are disabled. You can activate their compilation with ccmake (on Linux and Mac OSX), cmake-gui (on Windows) or by modifying the cmake command as follows :

cmake -DCMAKE_BUILD_TYPE=Release -DWITH_GUDHI_EXAMPLE=ON ..
make 

A list of utilities and examples is available here.

Installation

To install the library (headers and activated utilities), run the following command in a terminal:

make install 

This action may require to be in the sudoer or administrator of the machine in function of the operating system and of CMAKE_INSTALL_PREFIX.

Note

Python module will be compiled by the make command, but make install will not install it. Please refer to the Python module installation documentation.

Test suites

To test your build, run the following command in a terminal:

make test 

make test is using Ctest (CMake test driver program). If some of the tests are failing, please send us the result of the following command:

ctest --output-on-failure 

Testing fetching datasets feature requires the use of the internet and is disabled by default. If you want to include this test, set WITH_GUDHI_REMOTE_TEST to ON when building in the previous step (note that this test is included in the python module):

cmake -DCMAKE_BUILD_TYPE=Release -DWITH_GUDHI_TEST=ON -DWITH_GUDHI_REMOTE_TEST=ON --DWITH_GUDHI_PYTHON=ON .. 

C++ documentation

To generate the C++ documentation, the doxygen program is required (version ≥ 1.9.5 is advised). Run the following command in a terminal:

make doxygen 

Documentation will be generated in a folder named html.

In case there is not a full setup present and only the documentation should be build the following command sequence can be used:

cmake -DWITH_GUDHI_THIRD_PARTY=OFF ..
make doxygen

Hello world !

The Hello world for GUDHI project is an example to help developers to make their own C++ project on top of the GUDHI library.

Optional third-party library

GMP

The multi-field persistent homology algorithm requires GMP which is a free library for arbitrary-precision arithmetic, operating on signed integers, rational numbers, and floating point numbers.

The following example requires the GNU Multiple Precision Arithmetic Library (GMP) and will not be built if GMP is not installed:

• Persistent_cohomology/rips_multifield_persistence.cpp

Having GMP version 4.2 or higher installed is recommended.

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.

Note

There is no need to install CGAL, you can just cmake -DCMAKE_BUILD_TYPE=Release . && make CGAL (or even cmake -DCMAKE_BUILD_TYPE=Release -DCGAL_HEADER_ONLY=ON .), thereafter you will be able to compile GUDHI by calling cmake -DCMAKE_BUILD_TYPE=Release -DCGAL_DIR=/your/path/to/CGAL-X.Y .. && make

The procedure to install this library according to your operating system is detailed here http://doc.cgal.org/latest/Manual/installation.html

The following examples/utilities require the Computational Geometry Algorithms Library (CGAL [44]) and will not be built if CGAL version 4.11.0 or higher is not installed:

• Simplex_tree/example_alpha_shapes_3_simplex_tree_from_off_file.cpp
• Witness_complex/strong_witness_persistence.cpp
• Witness_complex/weak_witness_persistence.cpp
• Witness_complex/example_strong_witness_complex_off.cpp
• Witness_complex/example_witness_complex_off.cpp
• Witness_complex/example_witness_complex_sphere.cpp
• Alpha_complex/Alpha_complex_from_off.cpp
• Alpha_complex/Alpha_complex_from_points.cpp
• Alpha_complex/alpha_complex_persistence.cpp
• Persistent_cohomology/custom_persistence_sort.cpp
• Bottleneck_distance/alpha_rips_persistence_bottleneck_distance.cpp
• Bottleneck_distance/bottleneck_basic_example.cpp
• Bottleneck_distance/bottleneck_distance.cpp
• Nerve_GIC/CoordGIC.cpp
• Nerve_GIC/FuncGIC.cpp
• Nerve_GIC/Nerve.cpp
• Nerve_GIC/VoronoiGIC.cpp
• Spatial_searching/example_spatial_searching.cpp
• Subsampling/example_choose_n_farthest_points.cpp
• Subsampling/example_pick_n_random_points.cpp
• Subsampling/example_sparsify_point_set.cpp
• Tangential_complex/example_basic.cpp
• Tangential_complex/example_with_perturb.cpp
• Alpha_complex/Weighted_alpha_complex_3d_from_points.cpp
• Alpha_complex/alpha_complex_3d_persistence.cpp
• Coxeter_triangulation/manifold_tracing_flat_torus_with_boundary.cpp

Eigen

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

The following examples/utilities require the Eigen and will not be built if Eigen is not installed:

• Alpha_complex/Alpha_complex_from_off.cpp
• Alpha_complex/Alpha_complex_from_points.cpp
• Alpha_complex/alpha_complex_persistence.cpp
• Alpha_complex/alpha_complex_3d_persistence.cpp
• Alpha_complex/Weighted_alpha_complex_3d_from_points.cpp
• Bottleneck_distance/alpha_rips_persistence_bottleneck_distance.cpp
• Persistent_cohomology/custom_persistence_sort.cpp
• Spatial_searching/example_spatial_searching.cpp
• Subsampling/example_choose_n_farthest_points.cpp
• Subsampling/example_pick_n_random_points.cpp
• Subsampling/example_sparsify_point_set.cpp
• Tangential_complex/example_basic.cpp
• Tangential_complex/example_with_perturb.cpp
• Witness_complex/strong_witness_persistence.cpp
• Witness_complex/weak_witness_persistence.cpp
• Witness_complex/example_strong_witness_complex_off.cpp
• Witness_complex/example_witness_complex_off.cpp
• Witness_complex/example_witness_complex_sphere.cpp
• Coxeter_triangulation/cell_complex_from_basic_circle_manifold.cpp
• Coxeter_triangulation/manifold_tracing_custom_function.cpp
• Coxeter_triangulation/manifold_tracing_flat_torus_with_boundary.cpp

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.

The following examples/utilities are using Intel® oneAPI TBB if installed:

• Alpha_complex/Alpha_complex_from_off.cpp
• Alpha_complex/Alpha_complex_from_points.cpp
• Alpha_complex/alpha_complex_3d_persistence.cpp
• Alpha_complex/alpha_complex_persistence.cpp
• Bitmap_cubical_complex/cubical_complex_persistence.cpp
• Bitmap_cubical_complex/periodic_cubical_complex_persistence.cpp
• Bitmap_cubical_complex/Random_bitmap_cubical_complex.cpp
• Nerve_GIC/CoordGIC.cpp
• Nerve_GIC/FuncGIC.cpp
• Nerve_GIC/Nerve.cpp
• Nerve_GIC/VoronoiGIC.cpp
• Simplex_tree/simple_simplex_tree.cpp
• Simplex_tree/example_alpha_shapes_3_simplex_tree_from_off_file.cpp
• Simplex_tree/simplex_tree_from_cliques_of_graph.cpp
• Simplex_tree/graph_expansion_with_blocker.cpp
• Persistent_cohomology/alpha_complex_3d_persistence.cpp
• Persistent_cohomology/alpha_complex_persistence.cpp
• Persistent_cohomology/rips_persistence_via_boundary_matrix.cpp
• Persistent_cohomology/persistence_from_file.cpp
• Persistent_cohomology/persistence_from_simple_simplex_tree.cpp
• Persistent_cohomology/plain_homology.cpp
• Persistent_cohomology/rips_multifield_persistence.cpp
• Persistent_cohomology/rips_persistence_step_by_step.cpp
• Persistent_cohomology/custom_persistence_sort.cpp
• Rips_complex/example_one_skeleton_rips_from_points.cpp
• Rips_complex/example_rips_complex_from_off_file.cpp
• Rips_complex/rips_distance_matrix_persistence.cpp
• Rips_complex/rips_persistence.cpp
• Witness_complex/strong_witness_persistence.cpp
• Witness_complex/weak_witness_persistence.cpp
• Witness_complex/example_nearest_landmark_table.cpp

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.