Aleph

A library for exploring persistent homology

View the Project on GitHub

Building Aleph

Aleph uses the CMake build system. In the best case, all dependencies will automatically be identified. Please use your package manager to install the following dependencies:

Aleph is meant to be used as a header-only library on top of which you can develop your own projects based on persistent homology. However, Aleph ships with numerous unit tests, some example programs, and tools required for my current research. For building them, please clone the repository to some local directory on your computer. Running the following commands within this directory should be sufficient in most cases:

$ mkdir build
$ cd build
$ cmake ../
$ make

It is advisable to test that Aleph works correctly on your system, so you can run the unit tests with:

$ make test

A typical output of this command should look like this:

Running tests...
Test project /home/bastian/Projects/Aleph/build
      Start  1: bootstrap
 1/22 Test  #1: bootstrap ........................   Passed    0.00 sec
      Start  2: boundary_matrix_reduction
 2/22 Test  #2: boundary_matrix_reduction ........   Passed    0.00 sec
      Start  3: clique_enumeration
 3/22 Test  #3: clique_enumeration ...............   Passed    0.00 sec
      Start  4: clique_graph
 4/22 Test  #4: clique_graph .....................   Passed    0.00 sec
      Start  5: connected_components
 5/22 Test  #5: connected_components .............   Passed    0.05 sec
      Start  6: data_descriptors
 6/22 Test  #6: data_descriptors .................   Passed    0.23 sec
      Start  7: filesystem
 7/22 Test  #7: filesystem .......................   Passed    0.00 sec
      Start  8: graph_generation
 8/22 Test  #8: graph_generation .................   Passed    0.00 sec
      Start  9: io_functions
 9/22 Test  #9: io_functions .....................   Passed    0.00 sec
      Start 10: io_gml
10/22 Test #10: io_gml ...........................   Passed    0.02 sec
      Start 11: io_pajek
11/22 Test #11: io_pajek .........................   Passed    0.01 sec
      Start 12: io_vtk
12/22 Test #12: io_vtk ...........................   Passed    0.63 sec
      Start 13: mesh
13/22 Test #13: mesh .............................   Passed    0.00 sec
      Start 14: munkres
14/22 Test #14: munkres ..........................   Passed    0.00 sec
      Start 15: nearest_neighbours
15/22 Test #15: nearest_neighbours ...............   Passed    0.10 sec
      Start 16: persistence_diagrams
16/22 Test #16: persistence_diagrams .............   Passed    5.50 sec
      Start 17: persistent_homology_complete
17/22 Test #17: persistent_homology_complete .....   Passed    0.18 sec
      Start 18: point_clouds
18/22 Test #18: point_clouds .....................   Passed    0.09 sec
      Start 19: rips_expansion
19/22 Test #19: rips_expansion ...................   Passed    0.00 sec
      Start 20: rips_skeleton
20/22 Test #20: rips_skeleton ....................   Passed    0.04 sec
      Start 21: step_function
21/22 Test #21: step_function ....................   Passed    0.00 sec
      Start 22: union_find
22/22 Test #22: union_find .......................   Passed    0.00 sec

100% tests passed, 0 tests failed out of 22

Total Test time (real) =   6.87 sec

Please submit any issues you may encounter. If you want to help, please take a look at the contribution guidelines.

Binding to Python

If you want to install Aleph and bind it to its python function, do make sure you have PYBIND11 installed. If you don’t, you might get something like the following output when trying to use it:

$ python3
>>> import aleph
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/.../python3.x/site-packages/aleph/__init__.py", line 1, in <module>
    from .aleph import *
ModuleNotFoundError: No module named 'aleph.aleph'

Furthermore, you might get something like the following as part of the output when you run ccmake . inside the build/ directory.

PYBIND11_DIR                                                                                                  
PYBIND11_INCLUDE_DIR             PYBIND11_INCLUDE_DIR-NOTFOUND

In this case, install PYBIND11 both for python3 and for c/c++. For this, do:

pip3 install pybind11

and

# Clone, build and install
git clone https://github.com/pybind/pybind11.git
cd pybind11
mkdir build
cd build
cmake ..
make install

After this, reinstall the package once more and ensure it passes all the tests. Then try the import again.

Use Aleph with python inside Docker

Using this package inside is a bit complicated, but it is possible to make it work using this (relatively unorthodox solution).

  1. DO NOT include Aleph as a requirement inside a requirements.txt. Instead, create a requirement_docker.txt where Aleph is not included.
  2. Inside build/bindings/python/aleph, create a file called setup_docker.py looking like this:
# Set this one up in aleph/build/bindings/python/aleph
from setuptools import setup

setup(
    name="Aleph",
    version="0.0.0",
    packages=["aleph"],
    package_dir={"": "./Aleph/build/bindings/python/"},
    package_data={"": ["aleph.so"]},
    zip_safe=False,
)
  1. A sample Docker image that should work is the following. ```Dockerfile FROM python:3.7.6-buster

Install cmake

RUN apt-get update && apt-get -y install cmake protobuf-compiler

Install dependencies

RUN python -m pip install –upgrade pip COPY {PATH_TO_ALEPH}/Aleph/build/bindings/python/aleph ./Aleph/build/bindings/python/aleph

requirements_docker.txt should include all your requirements EXCEPT Aleph

COPY requirements_docker.txt requirements_docker.txt RUN python3 ./Aleph/build/bindings/python/aleph/setup_docker.py install RUN pip3 install -r requirements_docker.txt

COPY test_file.py test_file.py

CMD [“python3”, “test_file.py”]

```

Additional options

Some of the components of Aleph may be disabled if you want to increase performance of the build. Currently, these components include the examples and the tools. Use ccmake . in the build directory to get an overview of the available options. A typical output of this command would be:

BUILD_EXAMPLES        ON
BUILD_PYTHON_BINDINGS ON
BUILD_TOOLS           ON

Toggle the required options and re-configure the project in order to change what is built.

Installing Aleph

Having built Aleph, you can install the library as follows:

$ make install

It is possible to change the installation prefix of Aleph using either cmake or ccmake, the console front-end. To set another prefix upon building Aleph, you may use the following command:

$ cmake -DCMAKE_INSTALL_PREFIX=/path/to/installation/directory ../
$ make install

Package files (for certain Linux distributions) are forthcoming. Please refer to this issue for more details.