Installation

Note

This is the comprehensive installation guide. For a quick intro, see our quickstart guide.

Download

Magritte has to be compiled from its source code, which can be cloned using:

git clone --recursive https://github.com/Magritte-code/Magritte.git

from our GitHub repository. This creates the directory, Magritte, which will be refered to as the Magritte root directory. Ensure to include the --recursive to also clone the required submodules.

Dependencies

Magritte has several dependencies, some of which are optional.

Submodules

  • Eigen, version 3.3.7 or later, for some of the linear algebra;

  • pybind11, version 2.2.4 or later, for binding C++ to python;

  • googletest version 1.10.0 or later, for some of the tests;

  • Paracabs, our custom parallelization and acceleration abstractions.

Required

  • GCC, version 5.0.0 or later, to compile the C++ part of Magritte;

  • CMake, version 3.18.0 or later, for building the library, organising compilation and linking;

Optional

  • Anaconda, for managing the required Python packages;

Please note that Paracabs might have further dependencies depending on which paralellization and acceleration libraries are used. See advanced compilation for further details.

Python packages & Environment

To make Magritte useful, some python packages have to be installed which is best done using a conda environment.

The following python packages are used in Magritte, mainly for io and to create the model files.

  • numpy, to bind the Magritte data;

  • h5py, to read and write HDF5 data files;

  • scipy, for interpolation and spatial functions such as nearest neighbour calculations;

  • healpy, to sample directions from a discretized unit sphere;

  • astropy, for unit conversions and physical constants;

  • pyyaml, for reading and writing yaml files;

  • mpi4py, for MPI (Message Passing Interface) functionality in Python;

  • tqdm, for progress bars;

  • numba, for just-in-time compilation of some Python functions;

  • palettable, for nice colourmaps;

  • matplotlib, for basic plotting;

  • plotly, for advanced plotting;

  • nodejs, for interactivity in some advanced plots;

  • ipywidgets, for interactive plotting;

  • jupyterlab, for convenient use of the jupyter notebooks;

  • plons, for importing Phantom sph models;

All of these packages can also be found in the conda environment file.

Hint

The simplest way to setup the required python packages is using the anaconda package manager. The Magritte conda environment can be created from the environment file conda_env.yml located in the dependencies directory, with

conda env create -f conda_env.yml

This will download and install all required python packages in a newly created magritte conda environment. The environment can be activated with

conda activate magritte

Please ensure that this environment is active whenever Magritte is compiled or used.

Warning

Magritte uses plotly for some interactive plots. Plotly requires additional extensions to be able to render plots in a jupyter notebook or in jupyter lab. Please consult their installation notes to get plotly working with jupyter.

Compilation

Once all dependencies are in place, Magritte can be compiled.

Hint

There is a shortcut script to build Magritte in the default configuration. From within the Magritte root directory, run:

bash build.sh

This will create a bin directory in the Magritte root directory containing the library binary files and the executables for the tests. It will also create a shared object file core.so in the magritte python package, located in the magritte directory.

See advanced compilation for further options.

Advanced compilation

Compilers

Corrently only the GNU gcc compiler is fully supported. We are currently further investigating Clang and Intel compiler (icc) support.

GPU acceleration

A GPU-enabled port of Magritte to python using pytorch can be found on GitHub. Unless GPU acceleration is required, the C++ version of Magritte should be used, as the compiled C++ code is faster on CPU than the python version. Not all features of the C++ version are available in the python version.