install.rst 6.04 KB
Newer Older
1
2
3
4
5
6
7
8
.. _installing:

Installing STEMsalabim
======================

Requirements
------------

9
The following libraries and tools are needed to successfully compile the code:
10

11
* A C++11 compiler (such as `gcc/g++ <https://gcc.gnu.org/>`_ or `intel compiler suite <https://software.intel.com/en-us/compilers>`_).
12
* `CMake <https://cmake.org/>`_ > 3.3
13
* `NetCDF <https://www.unidata.ucar.edu/software/netcdf/>`_
14
* `libConfig <http://www.hyperrealm.com/libconfig/>`_ >= 1.5
15
* `FFTW3 <http://www.fftw.org/>`_ or `Intel's MKL <https://software.intel.com/en-us/mkl>`_
16
* An MPI implementation (such as `OpenMPI <http://www.open-mpi.de/>`_)
17

18
.. note:: You may find some of the requirements in the repositories of your Linux distribution, at least the compiler,
19
          CMake, and OpenMPI. On Debian or Ubuntu Linux, for example, you can simply run the following command
20
21
22
          to download and install all the requirements:
          ::

23
24
25
26
27
28
29
              $ apt-get install build-essential      \
                                cmake                \
                                libconfig++-dev      \
                                libfftw3-dev         \
                                libnetcdf-dev        \
                                libopenmpi-dev       \
                                openmpi-bin
30

31

32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
.. Tip:: Most of the computing time is spent calculating Fourier transforms, so it is beneficial for STEMsalabim
         to use optimized FFT libraries. Sometimes, compiling FFTW or MKL on the target machine enables
         optimizations that are not available in precompiled binaries, so this may be worth a try.


Downloading the source code
---------------------------

We recommend you download the latest stable release (|release|) from the
`Releases page <https://gitlab.com/STRL/STEMsalabim/tags>`_. If you want the latest features and/or bugfixes,
you can also clone the repository using

::

    $ git clone https://gitlab.com/STRL/STEMsalabim.git
    $ git checkout devel # only if you want the devel code.
48

49

50
51
52
53
54
55
56
57
58
59
Building STEMsalabim
--------------------

Extract the code archive to some folder on your hard drive, e.g.

::

    $ cd /tmp
    $ tar xzf stemsalabim-VERSION.tar.gz

60
Then, create a build directory and run CMake to generate the build configuration:
61
62
63
64
65
66
67
68
69

::

    $ mkdir /tmp/stemsalabim-build
    $ cd /tmp/stemsalabim-build
    $ cmake ../stemsalabim-VERSION

Please refer to the `CMake documentation <https://cmake.org/documentation/>`_ for instructions how to specify library
paths and other environment variables, in case the above commands failed. When your libraries exist at non-standard places
70
in your file system, you can specify the search paths as follows:
71
72
73
74
75

::

    $ cmake ../stemsalabim-VERSION                                            \
        -DFFTW_ROOT=/my/custom/fftw/                                          \
76
77
        -DLIBCONFIG_ROOT=/my/custom/libconfig/                                \
        -DNETCDF_INCLUDE_DIR=/my/custom/netcdf/include                        \
78
79
80
81
82
83
84
85
86
87
88
89
        -DCMAKE_INSTALL_PREFIX=/usr/local                                     \
        -DCMAKE_EXE_LINKER_FLAGS='-Wl,-rpath,/my/custom/lib64:/my/custom/lib' \
        -DCMAKE_CXX_COMPILER=/usr/bin/g++

In the above example, some custom library paths are specified and the program's run-time search path is modified.
If cmake doesn't detect the correct compiler automatically, you can specify it with ``-DCMAKE_CXX_COMPILER=``.

Having generated the necessary build files with CMake, simply compile the program using ``make`` and move it to the
install location with ``make install``:

::

90
91
    $ make -j8           # use 8 cores for compilation
    $ make install       # move the binaries and libraries to the INSTALL_PREFIX path
92

93
94
95
96
You are now ready to execute your first simulation.


Building with Intel MKL, Intel compiler (and Intel MPI)
97
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
98
99
100

It is possible to use the `Intel® Parallel Studio <https://software.intel.com/en-us/parallel-studio-xe>`_
for compilation, which includes the `Intel® Math Kernel Library (MKL) <https://software.intel.com/en-us/mkl>`_
101
that STEMsalabim can use for discrete fourier transforms instead of FFTW3. If the
102
`Intel® MPI Library <https://software.intel.com/en-us/intel-mpi-library>`_ is also available, it can be used
103
for MPI communication.
104

105
.. note:: We have tested compiling and running STEMsalabim only with Parallel Studio 2017 so far.
106

107
STEMsalabim's CMake files try to find the necessary libraries themselves, when the folling conditions are true:
108
109
110
111
112
113
114
115
116
117
118
119

 1. Either the environment variable :code:`MKLROOT` is set to a valid install location of the MKL, or
    the CMake variable :code:`MKL_ROOT` (pointing at the same location) is specified.
 2. The CMake variable :code:`GCCDIR` points to the install directory of a C++11 compatible GCC compiler.
    This is important, because the :code:`libstdc++` from a GCC install is required for the Intel compilers
    to use modern C++ features.

For example, let's say the Intel suite is installed in :code:`/opt/intel` and we have GCC 6.3 installed in
:code:`/opt/gcc-6.3`, then CMake could be invoked like this: ::

    $ export PATH=$PATH:/opt/intel/... # mpicxx and icpc should be in the path!
    $ LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/gcc-6.3/lib64 \
120
121
122
123
124
         cmake ../source                                  \
            -DMKL_ROOT=/opt/intel                         \
            -DCMAKE_CXX_COMPILER=icpc                     \
            -DGCCDIR=/opt/gcc-6.3                         \
            -D... more CMAKE arguments as described above.
125
126

Depending on how your environment variables are set, you may be able to skip the :code:`LD_LIBRARY_PATH=..` part.
127
When STEMsalabim is executed, you may again need to specify the library path of the :code:`libstdc++`, using ::
128
129
130
131
132
133

    $ LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/gcc-6.3/lib64 mpirun -np ... /path/to/stemsalabim -p ...

.. note:: Some fiddling with paths and environment variables is probably necessary. It may help to know
          basic CMake syntax and have a look at :code:`/path/to/stemsalabim/cmake/FindMKL.cmake` if
          CMake is unable to find something.