How to build

Installation

To make this work from plain Ubuntu installation, run

sudo apt-get install git g++ python3 cmake libhdf5-serial-dev
git clone https://gitlab.com/e62Lab/medusa.git --branch master --single-branch
cd medusa
./run_tests.py

which installs dependencies, clones the repository, goes into the root folder of the repository and runs tests. This will build and run all tests. If this works, you are ready to go! Otherwise install any missing packages and if it still fails, raise an issue!

For instructions on how to use this library in you project, see Including this library in your project.

Building

List of dependencies:

• Build tools, like cmake >= 2.8.12, g++ >= 4.8, make, python3
• HDF5 library for IO
• doxygen >= 1.8.8 and Graphviz for generating the documentation

Out of source builds are preferred. Run

mkdir -p build
cd build
cmake ..
make

Note that you only have to run cmake once, after that only make is sufficient.

Binaries are placed into bin/ folder. Tests can be run all at once via make medusa_run_tests or individually via e. g. make operators_run_tests.

HDF5

In order to use HDF5 IO you need the HDF5 library. You can install it easily using the command sudo apt-get install libhdf5-dev or sudo pacman -S hdf5.

Ubuntu places (at least on older versions) hdf5 headers and libraries in a weird folder /usr/{lib, include}/x86_64-linux-gnu/hdf5/serial/.

If you get an error like HDF5 sample failed to compile. See errors above. during cmake execution then the sample hdf test file located in test/test_hdf_compile.cpp failed to compile. Perhaps it is good to make this file compile first, before tackling the whole project.

If you get an error similar to fatal error: hdf5.h: No such file or directory, then your compiler cannot see the HDF5 header files. Some distributions, notably (older) Ubuntu, place them into nonstandard folders /usr/include/hdf5/serial/ or /usr/include/x86_64-linux-gnu/hdf5/serial/. Check these two folders or check your distributions hdf package for the locations of these files. After you have determined the location, add that directory to the include directories, using -I flag or in CMakeLists.txt by using

include_directories(/usr/include/hdf5/serial/)  # or your appropriate directory

If you wish to fix this problem permanently, you can create soft links to the headers in your /usr/include directory, by typing

sudo ln -s /usr/include/hdf5/serial/ /usr/include

After this, there should be no compile time errors. If there are, please raise an issue.

If you get error similar to -lhdf5 not found and you have hdf5 installed, you might have to link the libraries into a discoverable place, like /usr/lib/ or add the above directory to the linker path. Similarly to above, check the /usr/lib/x86_64-linux-gnu/hdf5/serial/ directory and look for file libhdf5.a. When found, specify the location using -L flag or CMakeLists.txt by using

link_directories(/usr/lib/x86_64-linux-gnu/hdf5/serial/)  # or your appropriate directory

or fix the problem permanently by soft-linking

sudo ln -s /usr/lib/x86_64-linux-gnu/hdf5/serial/ /usr/lib

Linear Algebra

We use Eigen as our matrix library. See here for use reference and documentation. For a quick transition from Matlab see here.

Using Intel Math Kernel Library (MKL)

Warning: This section is out of date. Some information might be wrong or incomplete.

Eigen has great support for MKL all you have to do is define a EIGEN_USE_MKL_ALL macro before any includes. You can see further instructions on their website.

Besides setting #define EIGEN_USE_MKL_ALL in your code, some linker and compilation fixes are needed. You have to set MKL and MKLROOT variables in cmake. You can define the variable MKLROOT as a system variable (using export) which is enough. You can also define it manually when calling cmake. If it is not set in either way it will default to "/opt/intel/compilers_and_libraries_2017.2.174/linux/mkl".

cmake .. -DMKL=ON -DMKLROOT=/opt/intel/compilers_and_libraries_2016.1.150/linux/mkl

Your target has to be linked with some MKL libraries so make sure to add the following link to your cmake file.

target_link_libraries(target ${LMKL})

Building on macOS

This method was tested on macOS Mojave 10.14.2.

First install Xcode via App Store and then Xcode Command Line Tools with

xcode-select --install

After that, install all dependencies from homebrew

brew install cmake hdf5 boost python doxygen graphviz

Now you can clone and build the project using the following commands

git clone https://gitlab.com/e62Lab/medusa.git
cd medusa
mkdir build
cd build
cmake ..
cd ..
python3 run_tests.py

This will also run all tests. If it works, you are ready to go! Otherwise install any missing packages and if it still fails, raise an issue!

Using Intel C/C++ Compiler

Warning: This section is out of date. Some information might be wrong or incomplete.

In order to use Intel's compiler you have to first set the CXX and CC bash variables. Before calling cmake for the first time you have to export the following:

export CXX="icpc"
export CC="icc"

or you can define the compiler when first calling cmake like so:

cmake .. -DCMAKE_C_COMPILER=$(which icc) -DCMAKE_CXX_COMPILER=$(which icpc)

You can also compile it directly for Intel® Xeon Phi™ Coprocessor. You do this by adding -Dmmic=ON flag to the cmake command:

cmake .. -Dmmic=ON -DCMAKE_C_COMPILER=$(which icc) -DCMAKE_CXX_COMPILER=$(which icpc)

Note: All features that depend on system third-party libraries are not available on MIC (Many Integrated Core). This includes:

• HDF class in io.hpp