How to build

Installation

To make this work from plain Ubuntu installation, run

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

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! Note: If you are told the packages cannot be located, try doing a sudo apt-get update.

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.

Linker errors

When trying out different classes, you might come along linker errors such as

Scanning dependencies of target cantilever_beam [100%] Building CXX object examples/linear_elasticity/CMakeFiles/cantilever_beam.dir/cantilever_beam.cpp.o [100%] Linking CXX executable ../../../examples/linear_elasticity/cantilever_beam /usr/bin/ld: CMakeFiles/cantilever_beam.dir/cantilever_beam.cpp.o: in function `main': cantilever_beam.cpp:(.text.startup+0x162): undefined reference to `void mm::FindBalancedSupport::operator()<mm::DomainDiscretization<Eigen::Matrix<double, 2, 1, 0, 2, 1> > >(mm::DomainDiscretization<Eigen::Matrix<double, 2, 1, 0, 2, 1> >&) const' collect2: error: ld returned 1 exit status

This is expected and is the result of some optimizations of compilation time. The medusa library can actually be included in two ways: as #include <medusa/Medusa_fwd.hpp> or #include <medusa/Medusa.hpp>. The first version contains the declarations of all symbols, but not all the definitions. Some of the more commonly used template instantiations are included, but by far not all. Using a template instantiation that is not precompiled will cause your program to compile fine, but will fail to link, due to the missing definitions. In this case you have a few options: include the full Medusa library (the header without the _fwd) and it should just work, but you will have to wait a bit longer for it to compile. Include only the missing header (in the case above medusa/bits/domains/FindBalancedSupport.hpp) and pay for whay you use. Or, add your instantiation among the already precompiled instantiations (located in .cpp files, such as e.g. this one).

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 -t

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!

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

OpenMP

Sometimes, OpenMP cmake errors might occure. This happens mainly due to limited multi-thread support. One can fix such issues, by adding the following code into their CMakeLists.txt

find_package(OpenMP)
if (OPENMP_FOUND)
    set (CMAKE_C_FLAGS "${CMAKE_C_FLAGS} ${OpenMP_C_FLAGS}")
    set (CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${OpenMP_CXX_FLAGS}")
    set (CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} ${OpenMP_EXE_LINKER_FLAGS}")
endif()

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)

Install Intel MKL and take not of installation directories.

Proper include and link directories need to be set to use the Intel MKL.

include_directories(SYSTEM /opt/intel/compilers_and_libraries/linux/mkl/include)    # change these to your installation path
link_directories(SYSTEM /opt/intel/compilers_and_libraries/linux/mkl/lib/intel64)
link_directories(SYSTEM /opt/intel/compilers_and_libraries/linux/lib/intel64)

Eigen has great support for MKL. You can see more detailed instructions on their website. To use MKL for math operations, define EIGEN_USE_MKL_VML when compiling. You must also link the appropriate libraries and define MKL_LP64 for use on a 64bit system. With parallelism enabled, the configuration looks as follows

target_compile_options(my_target PRIVATE "-fopenmp")
target_compile_definitions(my_target PUBLIC EIGEN_USE_MKL_VML MKL_LP64)
target_link_libraries(my_target medusa mkl_intel_lp64 mkl_intel_thread mkl_core pthread iomp5)

If you have Intel Parallel Studio installed this also enables you to use the Pardiso paralle direct sparse solver through its Eigen interface.

Using Intel C/C++ Compiler

In order to use Intel's compiler when compiling Medusa, you have several standard optionas for cmake. Make sure compilers and installed and in your PATH by running which icc, which should return something like /opt/intel/bin/icc.

You can define the compiler when *first* calling cmake like so

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

If this is not your first call, remove the build directory and start anew.

You can also 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"