Difference between revisions of "How to build"

From Medusa: Coordinate Free Mehless Method implementation
Jump to: navigation, search
(→‎HDF5)
 
(22 intermediate revisions by 5 users not shown)
Line 2: Line 2:
 
To make this work from plain Ubuntu installation, run
 
To make this work from plain Ubuntu installation, run
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
−
sudo apt-get install git g++ python cmake libhdf5-serial-dev
+
sudo apt-get install git g++ python3 cmake libhdf5-serial-dev doxygen graphviz
−
git clone https://gitlab.com/e62Lab/medusa.git --branch master --single-branch
+
git clone https://gitlab.com/e62Lab/medusa.git --branch dev --single-branch
 
cd medusa
 
cd medusa
−
./run_tests.py
+
./run_tests.py -t
 
</syntaxhighlight>
 
</syntaxhighlight>
 
which installs dependencies, clones the repository, goes into the root folder of
 
which installs dependencies, clones the repository, goes into the root folder of
Line 11: Line 11:
 
works, you are ready to go! Otherwise install any missing packages and if it
 
works, you are ready to go! Otherwise install any missing packages and if it
 
still fails, raise an issue!
 
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
 
For instructions on how to use this library in you project, see
−
Including this library in your project.
+
[[Including this library in your project]].
  
 
=Building=
 
=Building=
Line 19: Line 20:
 
List of dependencies:
 
List of dependencies:
  
−
* Build tools, like <code> cmake >= 2.8.12</code>, <code> g++ >= 4.8</code>, <code>make</code>, <code>python</code>
+
* Build tools, like <code> cmake >= 2.8.12</code>, <code> g++ >= 4.8</code>, <code>make</code>, <code>python3</code>
 
* [https://www.hdfgroup.org/ HDF5 library] for IO  
 
* [https://www.hdfgroup.org/ HDF5 library] for IO  
 
* <code>doxygen >=  1.8.8 </code> and Graphviz for generating the documentation
 
* <code>doxygen >=  1.8.8 </code> and Graphviz for generating the documentation
Line 32: Line 33:
 
Note that you only have to run <code>cmake</code> once, after that only <code>make</code> is sufficient.
 
Note that you only have to run <code>cmake</code> once, after that only <code>make</code> is sufficient.
  
−
Binaries are placed into <code>bin/</code> folder. Test can be run all at once via <code>make medusa_run_tests</code>  
+
Binaries are placed into <code>bin/</code> folder. Tests can be run all at once via <code>make medusa_run_tests</code>  
−
or individually via e.g. <code>make operators_run_tests</code>.
+
or individually via e. g. <code>make operators_run_tests</code>.
 +
 
 +
== Linker errors ==
 +
 
 +
When trying out different classes, you might come along linker errors such as
 +
 
 +
<code>
 +
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
 +
</code>
 +
 
 +
This is expected and is the result of some optimizations of compilation time. The medusa library can actually be included in two ways: as
 +
<code>#include <medusa/Medusa_fwd.hpp></code> or <code>#include <medusa/Medusa.hpp></code>. 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 <i>full</i> Medusa library (the header without the <code>_fwd</code>) 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 <code>medusa/bits/domains/FindBalancedSupport.hpp</code>) and pay for whay you use. Or, add your instantiation among the already precompiled instantiations (located in <code>.cpp</code> files, such as e.g. [https://gitlab.com/e62Lab/medusa/-/blob/dev/src/domains/DomainDiscretization.cpp 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
 +
<syntaxhighlight lang="bash">
 +
xcode-select --install
 +
</syntaxhighlight>
 +
 
 +
After that, install all dependencies from homebrew
 +
<syntaxhighlight lang="bash">
 +
brew install cmake hdf5 boost python doxygen graphviz
 +
</syntaxhighlight>
 +
 
 +
Now you can clone and build the project using the following commands
 +
<syntaxhighlight lang="bash">
 +
git clone https://gitlab.com/e62Lab/medusa.git
 +
cd medusa
 +
mkdir build
 +
cd build
 +
cmake ..
 +
cd ..
 +
python3 run_tests.py -t
 +
</syntaxhighlight>
 +
 
 +
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==
 
==HDF5==
Line 59: Line 102:
 
by typing
 
by typing
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
−
sudo ln -s /usr/include/hdf5/serial/ /usr/include
+
sudo ln -s /usr/include/hdf5/serial/* /usr/include
 
</syntaxhighlight>
 
</syntaxhighlight>
 
After this, there should be no compile time errors. If there are, please raise an issue.
 
After this, there should be no compile time errors. If there are, please raise an issue.
Line 73: Line 116:
 
or fix the problem permanently by soft-linking
 
or fix the problem permanently by soft-linking
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
−
sudo ln -s /usr/lib/x86_64-linux-gnu/hdf5/serial/ /usr/lib
+
sudo ln -s /usr/lib/x86_64-linux-gnu/hdf5/serial/* /usr/lib
 +
</syntaxhighlight>
 +
 
 +
== 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
 +
 
 +
<syntaxhighlight lang="cmake">
 +
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()
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Line 83: Line 138:
  
 
== Using Intel Math Kernel Library (MKL) ==
 
== Using Intel Math Kernel Library (MKL) ==
−
{{Warning|This section is out of date. Some information might be wrong or incomplete. }}
+
Install [https://software.intel.com/en-us/mkl Intel MKL] and take not of installation directories.
 +
 
 +
Proper include and link directories need to be set to use the Intel MKL.  
 +
<syntaxhighlight lang="cmake">
 +
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)
 +
</syntaxhighlight>
  
−
Eigen has great support for MKL all you have to do is define a EIGEN_USE_MKL_ALL macro before any includes.
+
Eigen has great support for MKL. You can see more detailed instructions [https://eigen.tuxfamily.org/dox/TopicUsingIntelMKL.html on their website].
−
You can see further instructions [https://eigen.tuxfamily.org/dox/TopicUsingIntelMKL.html on their website].
+
To use MKL for math operations, define <code>EIGEN_USE_MKL_VML</code> when compiling. You must also link
 +
the appropriate libraries and define <code>MKL_LP64</code> for use on a 64bit system.
 +
With parallelism enabled, the configuration looks as follows
  
−
Besides setting <syntaxhighlight lang="c++" inline>#define EIGEN_USE_MKL_ALL</syntaxhighlight> 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".
 
−
<syntaxhighlight lang="bash">
 
−
cmake .. -DMKL=ON -DMKLROOT=/opt/intel/compilers_and_libraries_2016.1.150/linux/mkl
 
−
</syntaxhighlight>
 
−
Your target has to be linked with some MKL libraries so make sure to add the following link to your cmake file.
 
 
<syntaxhighlight lang="cmake">
 
<syntaxhighlight lang="cmake">
−
target_link_libraries(target ${LMKL})
+
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)
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
== Building on Mac OSX ==
+
If you have Intel Parallel Studio installed this also enables you to use the Pardiso paralle direct sparse solver through its [https://eigen.tuxfamily.org/dox/group__PardisoSupport__Module.html Eigen interface].
−
{{Warning|This section is out of date. Some information might be wrong or incomplete. }}
+
 
−
This method was tested on El Capitan.
+
== Using Intel C/C++ Compiler ==
 +
 
 +
In order to use Intel's compiler when compiling Medusa, you have several standard optionas for <code>cmake</code>.
 +
Make sure compilers and installed and in your <code>PATH</code> by running <code>which icc</code>, which
 +
should return something like <code>/opt/intel/bin/icc</code>.
  
−
First install all dependencies from homebrew
+
You can define the compiler when *first* calling cmake like so
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
−
brew install llvm cmake homebrew/science/hdf5 boost
+
cmake .. -DCMAKE_C_COMPILER=$(which icc) -DCMAKE_CXX_COMPILER=$(which icpc)
−
</syntaxhighlight>
 
−
Now you can clone and build the project with CLang using the following commands
 
−
<syntaxhighlight lang="bash">
 
−
git clone https://gitlab.com/e62Lab/medusa.git
 
−
cd medusa
 
−
mkdir build
 
−
cd build
 
−
cmake .. -DCMAKE_C_COMPILER=/usr/local/opt/llvm/bin/clang -DCMAKE_CXX_COMPILER=/usr/local/opt/llvm/bin/clang++
 
−
make domain_run_tests
 
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
If this is not your first call, remove the <code>build</code> directory and start anew.
  
−
== Using Intel C/C++ Compiler ==
+
You can also set the <code>CXX</code> and <code>CC</code> bash variables. Before calling
−
{{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 <code>CXX</code>
 
−
and <code>CC</code> bash variables. Before calling
 
 
<code> cmake </code> for the first time you have to export the following:
 
<code> cmake </code> for the first time you have to export the following:
−
 
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
 
export CXX="icpc"
 
export CXX="icpc"
Line 129: Line 179:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
or you can define the compiler when first calling cmake like so:
+
<!--
−
<syntaxhighlight lang="bash">
 
−
cmake .. -DCMAKE_C_COMPILER=$(which icc) -DCMAKE_CXX_COMPILER=$(which icpc)
 
−
</syntaxhighlight>
 
−
 
 
−
 
 
 
You can also compile it directly for Intel® Xeon Phi™ Coprocessor. You do this by adding <code>-Dmmic=ON</code>
 
You can also compile it directly for Intel® Xeon Phi™ Coprocessor. You do this by adding <code>-Dmmic=ON</code>
 
flag to the <code>cmake</code> command:
 
flag to the <code>cmake</code> command:
Line 140: Line 185:
 
cmake .. -Dmmic=ON -DCMAKE_C_COMPILER=$(which icc) -DCMAKE_CXX_COMPILER=$(which icpc)  
 
cmake .. -Dmmic=ON -DCMAKE_C_COMPILER=$(which icc) -DCMAKE_CXX_COMPILER=$(which icpc)  
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
  
 
<b>Note:</b> All features that depend on system third-party libraries are not available on MIC (Many Integrated Core).
 
<b>Note:</b> All features that depend on system third-party libraries are not available on MIC (Many Integrated Core).
Line 145: Line 191:
  
 
* HDF class in <code>io.hpp</code>
 
* HDF class in <code>io.hpp</code>
 +
 +
-->

Latest revision as of 15:19, 7 July 2023

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"


Retrieved from "http://e6.ijs.si/medusa/wiki/index.php?title=How_to_build&oldid=3553"