|
|
[[_TOC_]]
|
|
|
|
|
|
# Installing via Conda
|
|
|
|
|
|
Maybe the simplest way to install `graph-tool` is using the [Conda](https://conda.io) package manager for both GNU/Linux and MacOS, via [conda-forge](https://anaconda.org/conda-forge/graph-tool). The packages are binary, so no compilation is necessary. This mode of installation is particularly useful when a system-wide installation is not possible due to lack of permissions, e.g. in HPC environments, since conda allows for unprivileged installations in a home directory.
|
|
|
|
|
|
The easiest way to install `graph-tool` is to create a new environment and install it there:
|
|
|
|
|
|
```
|
|
|
conda create --name gt -c conda-forge graph-tool
|
|
|
conda activate gt
|
|
|
```
|
|
|
|
|
|
After that, install additional packages to the environment as needed:
|
|
|
|
|
|
```
|
|
|
conda install -n gt -c conda-forge ipython jupyter
|
|
|
```
|
|
|
|
|
|
You can also install `graph-tool` to a pre-existing environment with the following command,
|
|
|
but the solver is likely to fail (or hang) if your environment already contains many
|
|
|
packages already, whose dependencies may conflict with the `graph-tool` dependencies.
|
|
|
This is particularly likely if your environment contains packages from the official
|
|
|
`Anaconda` distribution, rather than the `conda-forge` distribution.
|
|
|
|
|
|
```
|
|
|
conda install -c conda-forge graph-tool
|
|
|
```
|
|
|
|
|
|
Note: Rather than specifying `-c conda-forge` on every command, you can add `conda-forge` to your channels with:
|
|
|
|
|
|
```
|
|
|
conda config --add channels conda-forge
|
|
|
```
|
|
|
|
|
|
It is possible to list all of the versions of `graph-tool` available for your platform with:
|
|
|
|
|
|
```
|
|
|
conda search graph-tool --channel conda-forge
|
|
|
```
|
|
|
|
|
|
If experiencing problems with the `conda` package, please open an issue at the [`conda-forge` github page](https://github.com/conda-forge/graph-tool-feedstock).
|
|
|
|
|
|
# Installing using Docker
|
|
|
|
|
|
The most OS-agnostic way to install `graph-tool` is using [Docker](https://www.docker.com/). If you have Docker installed, this can be done simply by running:
|
|
|
```bash
|
|
|
docker pull tiagopeixoto/graph-tool
|
|
|
```
|
|
|
This will download a Docker image based on [Arch GNU/Linux](https://www.archlinux.org/), that contains `graph-tool`, and can be run in any modern GNU/Linux distribution, MacOS X and Windows. It contains some other useful Python packages, such as [matplotlib](http://matplotlib.org/), [Pandas](http://pandas.pydata.org/), [IPython](https://ipython.org/) and [Jupyter](https://jupyter.org/).
|
|
|
|
|
|
## Interactive sessions
|
|
|
|
|
|
After the image is pulled, you can start an interactive python shell in the container by running:
|
|
|
```bash
|
|
|
docker run -it -u user -w /home/user tiagopeixoto/graph-tool ipython
|
|
|
```
|
|
|
which will give you a Python 3 environment with `graph-tool` installed:
|
|
|
```
|
|
|
Python 3.6.5 (default, May 11 2018, 04:00:52)
|
|
|
Type 'copyright', 'credits' or 'license' for more information
|
|
|
IPython 6.3.1 -- An enhanced Interactive Python. Type '?' for help.
|
|
|
|
|
|
In [1]: from graph_tool.all import *
|
|
|
In [2]:
|
|
|
```
|
|
|
|
|
|
### Interactive visualizations
|
|
|
|
|
|
If you want to use interactive visualization from within docker, you have first to enable local connections to the X server:
|
|
|
```bash
|
|
|
xhost +local:
|
|
|
```
|
|
|
and then run the container with
|
|
|
```bash
|
|
|
docker run -ti -u user -w /home/user --rm -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix tiagopeixoto/graph-tool ipython
|
|
|
```
|
|
|
|
|
|
### Jupyter notebooks
|
|
|
|
|
|
To run jupyter notebooks from inside the docker image, you need to forward the necessary ports to the container, so that your native browser can connect to it at http://localhost:8888/. You need first to start an interactive shell session
|
|
|
```bash
|
|
|
docker run -p 8888:8888 -p 6006:6006 -it -u user -w /home/user tiagopeixoto/graph-tool bash
|
|
|
```
|
|
|
and then start the notebook server
|
|
|
```bash
|
|
|
[user@c20b92b8c4bf ~]$ jupyter notebook --ip 0.0.0.0
|
|
|
```
|
|
|
**Do not forget to connect to http://localhost:8888/ instead of http://0.0.0.0:8888/, otherwise the connection to the kernel will not work!**
|
|
|
|
|
|
(MacOS and Windows users still need to bind the above ports in the VM, as described [here](https://stackoverflow.com/questions/33636925/how-do-i-start-tensorflow-docker-jupyter-notebook))
|
|
|
|
|
|
## Development snapshots
|
|
|
|
|
|
Continuous snapshots of the most current development version of `graph-tool` are available as the [graph-tool-git](https://hub.docker.com/r/tiagopeixoto/graph-tool-git) docker repository. This repository is updated automatically after every commit is made to the upstream git repository.
|
|
|
|
|
|
The development version can be installed simply by running:
|
|
|
```bash
|
|
|
docker pull tiagopeixoto/graph-tool-git
|
|
|
```
|
|
|
And following the same usage instructions as above.
|
|
|
|
|
|
**WARNING:** The development version may contain bugs! Prefer the stable releases whenever possible.
|
|
|
|
|
|
# Installing using Apptainer/Singularity (useful for HPC systems)
|
|
|
|
|
|
[Apptainer/singularity](https://apptainer.org/) is a platform for virtualization similar to docker, but is simpler to use and does not require administration privileges — it can be run as a regular user in a shared environment. One of the main uses of Apptainer/Singularity is to bring containers and reproducibility to scientific computing and the high-performance computing (HPC) systems. The idea is that you can setup your own up-to-date software stack in a container and use it to run jobs in your HPC cluster, which usually contains only outdated software, liberating you from depending on admins to install software!
|
|
|
|
|
|
``graph-tool`` can also be used with singularity via its docker images, which can be easily converted to Apptainer/singularity images. This is done with:
|
|
|
```bash
|
|
|
singularity pull docker://tiagopeixoto/graph-tool
|
|
|
```
|
|
|
This will create an image file ``graph-tool_latest.sif``, which you then can use, e.g. with:
|
|
|
```
|
|
|
singularity exec graph-tool-git_latest.sif python3 -c "import graph_tool.all"
|
|
|
```
|
|
|
The development versions are available as well in the [graph-tool-git](https://hub.docker.com/r/tiagopeixoto/graph-tool-git) repository.
|
|
|
|
|
|
**IMPORTANT:** The docker images contain a version of the glibc library which is compatible with linux kernel versions as old as 4, but not older.
|
|
|
|
|
|
# Native installation
|
|
|
|
|
|
Python modules are usually very easy to install, typically requiring nothing more that `pip install <package>` for basically any operating system. For `graph-tool`, however, the situation is different. This is because, in reality, `graph-tool` is a C++ library wrapped in Python, and it has many C++ dependencies such as [Boost](http://www.boost.org/), [CGAL](http://www.cgal.org/) and [expat](http://expat.sourceforge.net/), which are not installable via Python-only package management systems such as [pip](http://www.pip-installer.org/). Because the module lives between the C++ and Python worlds, its installation is done more like a C++ library rather than a typical python module. This means it inherits some of the complexities common of the C++ world that some Python users do not expect.
|
|
|
|
|
|
The easiest way to get going is to use a package manager, for which the installation is fairly straightforward. This is the case for some [GNU/Linux distributions](#gnulinux) (Arch, Gentoo, Debian & Ubuntu) as well as for [MacOS](#macos-x) users using either [Macports](http://www.macports.org/) or [Homebrew](http://brew.sh/). As discussed before, it is also possible to install it via [anaconda](https://anaconda.com) for both GNU/Linux and MacOS, through [conda-forge](https://conda-forge.org).
|
|
|
|
|
|
Alternatively, `graph-tool` can be installed from source, by [manual compilation](#manual-compilation). The module uses the standard [GNU build system](https://en.wikipedia.org/wiki/GNU_Build_System) for this (i.e. `./configure; make; make install`), and users wishing to go on this route are recommended to familiarize themselves with it. [Basic instructions](#manual-compilation) are given below, and an in-depth resource is the [Autotools Mythbuster](https://autotools.io/index.html).
|
|
|
|
|
|
## Installation via package managers
|
|
|
### GNU/Linux
|
|
|
|
|
|
#### Arch
|
|
|
|
|
|
[Packages for Arch](https://aur.archlinux.org/packages/python-graph-tool/) are available in the Arch User Repository. You can install it with pikaur:
|
|
|
|
|
|
```
|
|
|
pikaur -S python-graph-tool
|
|
|
```
|
|
|
|
|
|
#### Gentoo
|
|
|
|
|
|
An ebuild for graph-tool is included in the default [Gentoo](https://www.gentoo.org/) repository. Just do
|
|
|
|
|
|
```
|
|
|
emerge graph-tool
|
|
|
```
|
|
|
to install it.
|
|
|
|
|
|
#### Debian & Ubuntu
|
|
|
|
|
|
##### Official repository
|
|
|
There is a package on the official Debian repository for the unstable (``sid``) and testing (``bookworm``) releases, called [``python3-graph-tool``](https://packages.debian.org/sid/python3-graph-tool). If using any of these releases, it's enough to do
|
|
|
```
|
|
|
apt-get install python3-graph-tool
|
|
|
```
|
|
|
The latest versions are typically available only in the [``experimental``](https://wiki.debian.org/DebianExperimental) repository. You can use it by adding the following line to your `/etc/apt/sources.list`,
|
|
|
```
|
|
|
deb https://deb.debian.org/debian experimental main
|
|
|
```
|
|
|
After running `apt-get update`, you can install ``graph-tool`` with:
|
|
|
```
|
|
|
apt -t experimental install python3-graph-tool
|
|
|
```
|
|
|
The ``experimental`` repository can also be typically added to Ubuntu systems.
|
|
|
|
|
|
##### Upstream repository
|
|
|
We also provide an upstream repository for ``graph-tool``. This is useful for other [Debian](http://www.debian.org/) or [Ubuntu](http://www.ubuntu.com/) releases not covered by the official repositories, or if you want to install a newer version that has not yet made it there. New ``graph-tool`` versions are made available in the upstream repository almost immediately after release, while they can take some days to appear in the ``experimental`` Debian repository, and much longer on the other repositories. The Upstream repository is the easiest way to remain on the bleeding edge.
|
|
|
|
|
|
To use it, you need to add the following line to your `/etc/apt/sources.list`,
|
|
|
```
|
|
|
deb https://downloads.skewed.de/apt DISTRIBUTION main
|
|
|
```
|
|
|
where `DISTRIBUTION` can be any one of
|
|
|
|
|
|
```
|
|
|
bookworm, bullseye, buster, sid
|
|
|
```
|
|
|
for Debian, or any of the following
|
|
|
```
|
|
|
bionic, focal, jammy, kinetic
|
|
|
```
|
|
|
for Ubuntu releases.
|
|
|
|
|
|
You should then download the public key [`612DEFB798507F25`](https://keys.openpgp.org/search?q=612DEFB798507F25) to verify the packages, with the command:
|
|
|
```
|
|
|
apt-key adv --keyserver keyserver.ubuntu.com --recv-key 612DEFB798507F25
|
|
|
```
|
|
|
|
|
|
After running `apt-get update`, the package can be installed with
|
|
|
|
|
|
```
|
|
|
apt-get install python3-graph-tool
|
|
|
```
|
|
|
##### Git snapshots
|
|
|
Packages are also available for development versions of ``graph-tool``. They correspond to the current ``HEAD`` of the ``master`` branch of the git repository, and are build shortly after commits are made to it.
|
|
|
To use these packages, you need to add the following line to your `/etc/apt/sources.list`,
|
|
|
```
|
|
|
deb [trusted=yes] https://downloads.skewed.de/apt-git DISTRIBUTION main
|
|
|
```
|
|
|
where ``DISTRIBUTION`` is any of the ones for the stable release repository above. Note that both repositories are compatible, and can be installed side by side, and the newest version of the library will be selected correctly.
|
|
|
|
|
|
Please note that, unlike the stable releases, this repository is **unsigned**, and this is why the "`[trusted=yes]`" parameter is needed above.
|
|
|
|
|
|
#### Fedora
|
|
|
|
|
|
There's a fedora package for graph-tool called [python3-graph-tool](https://packages.fedoraproject.org/pkgs/python-graph-tool/python3-graph-tool/). To install it, just run:
|
|
|
```
|
|
|
dnf install python3-graph-tool
|
|
|
```
|
|
|
|
|
|
### MacOS X
|
|
|
|
|
|
#### Homebrew
|
|
|
|
|
|
With [Homebrew](http://brew.sh/) the installation is also straightforward, since a formula for it is included in the main repository:
|
|
|
```
|
|
|
brew install graph-tool
|
|
|
```
|
|
|
Note that since current versions of Homebrew, **pre-compiled binaries ("bottles") of graph-tool are available!**
|
|
|
|
|
|
If you encounter an error installing graph-tool via Homebrew, please file a bug report to that project directly, not graph-tool: https://github.com/Homebrew/homebrew-core/issues
|
|
|
|
|
|
#### Macports
|
|
|
|
|
|
A portfile is available for installation in MacOS X systems with [Macports](http://www.macports.org/). It is included in the [standard macports list](http://www.macports.org/ports.php?by=name&substr=graph-tool). Just run the following command to install it:
|
|
|
|
|
|
```
|
|
|
port install py-graph-tool
|
|
|
```
|
|
|
|
|
|
If you encounter an error installing graph-tool via Macports, please file a bug report to that project directly, not graph-tool: https://trac.macports.org/wiki/Tickets
|
|
|
|
|
|
### Windows
|
|
|
|
|
|
To use ``graph-tool`` on windows, you need to first install Windows Subsystem for Linux (WSL) as described here: https://learn.microsoft.com/en-us/windows/wsl/install
|
|
|
|
|
|
Usually, this requires simply running the command below on the power shell:
|
|
|
```
|
|
|
wsl --install
|
|
|
```
|
|
|
and then rebooting. You will be asked to provide a username and password.
|
|
|
|
|
|
This will install an Ubuntu subsystem alongside your windows OS. You then can install ``graph-tool`` just like described in the [Debian/Ubuntu](#debian-ubuntu) section above, i.e. you should open the file
|
|
|
```
|
|
|
sudo nano /etc/apt/sources.list
|
|
|
```
|
|
|
and add the following line to the bottom:
|
|
|
```
|
|
|
deb https://downloads.skewed.de/apt jammy main
|
|
|
```
|
|
|
**(``jammy`` is the current version of Ubuntu at the time of this writing, it should replaced with most current version, or with whatever version you happen to be using.)**
|
|
|
You should then add the signing key:
|
|
|
```
|
|
|
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-key 612DEFB798507F25
|
|
|
```
|
|
|
and update the package list:
|
|
|
```
|
|
|
sudo apt-get update
|
|
|
```
|
|
|
To enable all functionalities, the following extra packages need to be installed:
|
|
|
```
|
|
|
sudo apt-get install python3-cairo python3-gi-cairo python3-gi gnome pip
|
|
|
sudo pip install zstandard
|
|
|
```
|
|
|
Finally, the package itself can be installed via:
|
|
|
```
|
|
|
sudo apt-get install python3-graph-tool
|
|
|
```
|
|
|
If you want interactive visualization to work, follow the guide here: https://learn.microsoft.com/en-us/windows/wsl/tutorials/gui-apps
|
|
|
|
|
|
---------------------------------------
|
|
|
|
|
|
## Manual compilation
|
|
|
|
|
|
Graph-tool was tested extensively only on
|
|
|
[GNU/Linux](http://www.gnu.org) and MacOS X systems, but should also be
|
|
|
usable on other systems where the below requirements are met.
|
|
|
|
|
|
- [x] A C++17 compiler ([GCC]() version 7 or above, or [clang](http://clang.llvm.org/) version 5 or above).
|
|
|
- [x] The [Boost](http://www.boost.org/) libraries, version 1.55 or above.
|
|
|
- [x] [Python](http://www.python.org/) version 3 or above.
|
|
|
- [x] The [expat](http://expat.sourceforge.net/) XML library.
|
|
|
- [x] The [SciPy](http://www.scipy.org/) python module.
|
|
|
- [x] The [Numpy](http://numpy.scipy.org/) python module, version 1.7 or above.
|
|
|
- [x] The [CGAL](http://www.cgal.org/) C++ geometry library, version 3.5 or above.
|
|
|
- [ ] The [sparsehash](http://code.google.com/p/sparsehash/) template library (optional, but recommended).
|
|
|
- [ ] The [GTK+ 3](http://www.gtk.org/), [cairomm](http://cairographics.org/cairomm), [pycairo](http://cairographics.org/pycairo/) and [matplotlib](http://matplotlib.sourceforge.net/) libraries, used for graph drawing (optional).
|
|
|
- [ ] The [Graphviz](http://www.graphviz.org/) packaged for graph drawing, with the python bindings enabled (optional, deprecated).
|
|
|
|
|
|
### Generic instructions
|
|
|
|
|
|
Having installed the above dependencies (which can be done either manually, or preferably via a package manager), the module can be compiled in the usual way:
|
|
|
|
|
|
```bash
|
|
|
$ ./configure
|
|
|
$ make
|
|
|
```
|
|
|
|
|
|
After compilation, the module can be installed in the default Python module directory by running:
|
|
|
``` bash
|
|
|
$ make install
|
|
|
```
|
|
|
The above will install the library in the standard directories, and usually the final step requires root privileges.
|
|
|
|
|
|
Deviations from the standard directories will require that we inform the `configure` script in specific ways. This is done via configuration options or environment variables passed to the script. The most important ones are listed below:
|
|
|
|
|
|
#### Options to the `configure` script
|
|
|
* `--prefix=DIR`: This sets the general installation prefix. If left unspecified, this defaults to `DIR=/usr/local`. Note that this is used to install only peripheral parts of the library, such as README and pkgconfig files. The location of the module itself is specified with the following option.
|
|
|
* `--with-python-module-path=DIR`: This sets the location where the Python module will be installed. If left unspecified, this will be automatically determined using the Python interpreter. The default values may be something like `DIR=/usr/lib/python3.6/site-packages`, but this varies between OSs, virtualenvs, etc.
|
|
|
* `--with-boost-<libname>=NAME`: The Boost libraries are installed with different names across OSs. The `configure` script tries to guess the names using common patterns, but this can fail. With this option, the user can specify the correct name (either the entire library name or just a suffix). For example, if the boost-python library is name `libboost-python-mt-gcc6-py36-foobar`, this can be passed to `configure` as `--with-boost-python=-mt-gcc6-py36-foobar`.
|
|
|
|
|
|
#### Environment variables
|
|
|
The configure script will consult some shell environment variables that will affect its configuration.
|
|
|
|
|
|
* `CXX`: If defined, this variable should point to C++ compiler that will be used.
|
|
|
* `PYTHON`: If defined, this variable should point to the Python interpreter that will be used.
|
|
|
* `CPPFLAGS`: If defined, this variable will be used to pass extra flags to the C++ preprocessor (e.g. include flags of the form `-I/some/path`)
|
|
|
* `CXXFLAGS` : If defined, this variable will be used to pass extra flags to the C++ compiler (e.g. debugging and optimization options, `-O0 -g`)
|
|
|
* `LDFLAGS`: If defined, this variable will be used to pass extra flags to the shared object linker (e.g. paths to search for libraries, `-L/some/path`)
|
|
|
|
|
|
Below are some examples of using the above to achieve some common installation goals.
|
|
|
|
|
|
### Installing in a specific location (e.g. in a home directory)
|
|
|
|
|
|
The library can be installed in non-standard locations. For example, the usual convention of installing local programs in the `.local` subdirectory of a user's home can be achieved by:
|
|
|
|
|
|
```bash
|
|
|
$ ./configure --prefix=$HOME/.local --with-python-module-path=$HOME/.local/lib/python3.6/site-packages
|
|
|
$ make install
|
|
|
```
|
|
|
|
|
|
After the library has been installed, we need to make sure that the Python interpreter knows where to find it. In modern OSs, the above should already be in the interpreter's path. But otherwise (or in case some other path is being used), we need to modify the `PYTHONPATH` environment variable
|
|
|
```bash
|
|
|
$ export PYTHONPATH="$PYTHONPATH:$HOME/.local/lib/python3.6/site-packages"
|
|
|
```
|
|
|
|
|
|
#### Dependencies installed in a nonstandard directory
|
|
|
|
|
|
If any of the dependencies have been installed in a nonstandard directory, we need to pass this information to the `configure` script. Suppose again these have been installed in the `$HOME/.local` directory. In this case we need
|
|
|
```bash
|
|
|
$ ./configure CPPFLAGS="-I$HOME/.local/include" LDFLAGS="-L$HOME/.local/lib -Wl,-rpath=$HOME/.local/lib"
|
|
|
$ make install
|
|
|
```
|
|
|
(typically, in such cases we also want to install the library itself in the home directory; for this we need to combine with the options in the previous section.)
|
|
|
|
|
|
#### Installing in a [virtualenv](http://docs.python-guide.org/en/latest/dev/virtualenvs/)
|
|
|
|
|
|
To install graph-tool in a virtualenv we need to activate it before running configure
|
|
|
```bash
|
|
|
$ cd my_project
|
|
|
$ source venv/bin/activate
|
|
|
$ cd graph-tool-X.XX
|
|
|
$ ./configure --prefix=$HOME/.local
|
|
|
$ make install
|
|
|
```
|
|
|
The `--prefix` is necessary only so that non-python-related parts are installed in the correct place.
|
|
|
|
|
|
**Important:** The boost-python dependency **must** be compiled against the same Python version that is used in the virtualenv.
|
|
|
|
|
|
### Troubleshooting
|
|
|
|
|
|
If errors occur when running `configure`, look inside the `config.log` file for information on why the tests failed. Do not forget to include the contents of this file when reporting problems.
|
|
|
|
|
|
### Memory requirements for compilation
|
|
|
|
|
|
Graph-tool requires relatively large amounts of RAM (~ 3 GB) during compilation, because it uses [template metaprogramming](http://en.wikipedia.org/wiki/Template_metaprogramming) extensively. Most compilers are still not not very well optimized for this, which means that even though the program is relatively small, it will still use up lots of RAM during compilation, specially if optimizations are used (and you do want to use them). Below you can see the memory usage during compilation using GCC 5.2.0 and clang 3.7.0, on a 64-bit GNU/Linux system with an Intel(R) Core(TM) i7-5500U CPU @ 2.40GHz.
|
|
|
|
|
|
![compilation](/uploads/f1adc8f96193dc74b79f278c7455ea39/compilation.svg)
|
|
|
|
|
|
GCC finishes under 80 minutes, and uses at most slightly below 3 GB. On the other hand, clang takes around 100 minutes, and has a memory use peak around 4 GB.
|
|
|
|
|
|
### Parallel algorithms
|
|
|
graph-tool can run several of its algorithms in [parallel](http://en.wikipedia.org/wiki/Parallel_programming). It makes use of [OpenMP](http://en.wikipedia.org/wiki/Openmp) to do this, which provides a straightforward way of converting serial code into parallel code. OpenMP is an extension to the Fortran, C and C++ languages, which uses compiler directives to achieve automated code parallelization. Since it uses [compiler directives](http://en.wikipedia.org/wiki/Compiler_directive) (`#pragma `in C/C++), it maintains backwards compatibility with compilers that do not support OpenMP, and the code is then compiled cleanly as regular serial code. Thus, support for parallel code in graph-tool is quite optional. It is enabled by default, but if you wish to disable it, just pass the option `--disable-openmp` to the configure script.
|
|
|
|
|
|
# Google Colab
|
|
|
|
|
|
Colaboratory (also known as Colab) is a free Jupyter notebook environment that runs in the cloud and stores its notebooks on Google Drive. Since it's based on an Ubuntu system, we can install graph-tool on it using the instructions above. Please see here for a working Colab installation of graph-tool: https://colab.research.google.com/github/count0/colab-gt/blob/master/colab-gt.ipynb
|
|
|
|
|
|
|
|
|
Moved here: https://graph-tool.skewed.de/installation.html |