Install STAFSEA² and its Dependencies

Installing STAFSEA² and its prerequisites can be a very long and error prone journey. That is why an installation script was created which tries to automatize this procedure. A description on how to use this script and about what to customize (including recommended actions if something goes wrong) follows below:

Libraries used by STAFSEA²

STAFSEA² heavily relies on the well documented open source library SAMRAI and in addition hypre is used for solving linear systems. Further, a parallel built hdf5 library version is needed to manage the output data. Thus, you probably need to compile all these libraries on your own with special configurations, since most pre-installed versions miss the special features needed. Further, so far all developers use the mpich compiler for parallel MPI based computation. In theory any MPI compiler should suffice, but we have not tested others yet.

Here is a small table on combinations of required libraries that have been used recently and should work together:
Computer OS compiler MPI zlib boost hdf5 silo hypre SAMRAI
macbrain Mac OS X 10.10.5 gcc 4.9.3 mpich-3.1.4 (gcc49) 1.2.8 - 1.8.12 4.10.2bsd 2.10.1 v3.1.0-beta (fixed)
macbrain Mac OS X 10.8.5 gcc 4.5.4 mpich-3.1.2 (gcc45) 1.2.8 - 1.8.8 4.8bsd 2.8.0b (fixed) v3.1.0-beta (fixed)
waidmann Mac OS X 10.6.8 gcc 4.5.3 mpich2 1.4.1p1 1.2.7 - 1.8.8 4.8bsd 2.8.0b (fixed) v3.1.0-beta (fixed)
workhorse Fedora 15 gcc 4.6.3 mpich2 1.4.1p1   - 1.8.7 4.8bsd 2.8.0b (fixed) v3.1.0-beta (fixed)
workhorse Debian GNU/Linux 8 (jessie) gcc 4.9.2 mpich 3.1.4   - 1.8.12 4.10.2 2.8.0b (fixed) v3.1.0-beta (fixed)
HLRN II SUSE Linux (SLES) intel 11.0.083 mvapich2 1.7a2-intel   - 1.8.6-mvapich2-intel 4.8bsd 2.8.0b (fixed) v3.1.0-beta (fixed)
  Ubuntu 14.4 / CentOs 7 gcc 4.8.2 mpich2 1.4.1p1 1.2.8 - 1.8.8 4.8bsd 2.8.0b (fixed) v3.1.0-beta (fixed)
  Xubuntu 14.04.01 LTS gcc 4.8.2 mpich2 1.2.1   - 1.8.8 4.6.2 2.8.0b (fixed) v3.1.0-beta (fixed)
navier Debian wheezy 7.7 gcc 4.7.2 mpich-3.1.3 1.2.8 - 1.8.12 4.10 2.9.0b v3.1.0-beta (fixed)
navier Debian wheezy 7.7 gcc 4.7.2 mpich-3.1.3 1.2.8 1.57.0 1.8.12 4.10 2.9.0b v3.8.1
Note, that the official SAMRAI-v3.1.0-beta package contains some bugs. You need our fixed SAMRAI version SAMRAI-v3.1.0-beta-fixed.tar.gz from /group/ag_klima/SAMRAI-Framework/packages/ to make it work with STAFSEA². The same holds for hypre, if you want to use version 2.8.0b. However, hypre version 2.9.0b should contain the bug fixes and can be used instead of the fixed hypre-2.8.0b-fixed.tgz from /group/ag_klima/SAMRAI-Framework/packages/. The directory /group/ag_klima/SAMRAI-Framework/ is readable for all members of the group klima.

PREREQUISITES OPTION 1: Usage of department internal installation

You do not necessarily have to compile the prerequisites yourself. If you use a computer in our math/informatics department, you do not even have to install the prerequisites. The directory /group/ag_klima/SAMRAI-Framework/installation/ contains all libraries necessary to compile STAFSEA². If this is an alternative for you, go ahead and just link against these libraries. In this case you might skip this introduction and move to the section Compiling STAFSEA². The combination of installed packages is the one from workhorse under Debian GNU/Linux 8 in the table above.

PREREQUISITES OPTION 2: Using the installation script(s) to install locally (TO BE UPDATED)

This option has to be chosen if you want to be able to work offline (e.g. remotely on a laptop without internet connection available) with STAFSEA². To install STAFSEA² and its prerequisites locally on your computer you will need to have the usual compiler and installation tools (e.g. autoconf and a gcc compiler) on your machine. So make sure, that you can use commands like make and configure and have a C, C++ and fortran compiler on your computer (gcc recommended). Using the installation script (in /stafseasquared/tools) can be as easy as typing the following line into your console:

$ ./install.suggest original | xargs ./install

The following two sections will go in some more detail on how you can customize the installation for your needs.

Use install.suggest to get the configuration you like

STAFSEA² comes with two installation files install.suggest and install. The install.suggest is an executable providing a standard configuration for the actual install script which should work on most systems. Usage:

$ ./install.suggest <configuration>

For available configurations type:

$ ./install.suggest --help

You can easily add new configurations into the install.suggest file. That script is basically one big case statement of the form

case $1 in

cat <<-EOF

# maybe more ...
# ...


You can add any option which is known to the actual install script, e. g. specific package paths. Do not shy away from adding your personalized configuration to install.suggest in order to prepare for the actual installation. If you do not know what to do, simply use the original configuration.

Using the install script

The install script takes several options which customize your installation. If not explicitly stated with the --prefix option, the script will use your current directory as prefix and tries to install the libraries therein. You should either specify each package to be installed using the --install-<pkg>=<path> option or provide a path to a pre-installed package using the --with-<pkg>=<path> option, if the package is currently not located in the prefix path set. Each <path> should point to a folder containing the standard bin/, lib/, include/ folders e. g., /usr/ or /usr/local/ or specific package paths like /home/username/samrai/v3.1.0-beta/. The following options are available in order to control the installation:

Option Description
set the default installation target path for all packages
do not install package (pkg) but use installation under path
install version of package (pkg)
installation path for a specific package (pkg)
store the downloaded source code there (path)

Example: How /storage/mi/guttula (OPTION 1) was installed

$ cd /storage/mi/guttula
$ cp ~/stafseasquared/Utilities/install* .
$ ./install.suggest original | xargs ./install --prefix-samrai=samrai/v3.1.0-beta
(some output)
$ ./install --install-boost=1.57.0 --install-samrai=v3.8.1 --prefix-samrai=samrai/v3.8.1
(some output)

These lines install all prerequisites into the /storage/mi/guttula folder as described here. SAMRAI is explicitly installed different from the original setting in install.suggest, namely in two different folders: /storage/mi/guttula/samrai/v3.1.0-beta and /storage/mi/username/guttula/samrai/v3.8.1, one per library version. In the above example v3.1.0-beta is installed together with the other prerequisites and v3.8.1 separately afterwards.

What if something went wrong

When the installation fails the installation script leaves the build directory with its log files in your current folder as sub directory in ./src/package-version. Examine the log files, for instance config.log or similar files, then try to fix the error and remove the source folder from the ./src directory. You can restart the ./install script using exaclty the same command you have used first to start the installation. The script will automatically detect what package have been successfully installed before and restart appropriately.

PREREQUISITES OPTION 3: Manual local installation

As stated in the introduction above, manual step by step installation can - depending on your system - be quite time consuming and annoying, so you first should check if PREREQUISITES OPTION 2 works on your system if a local installation is required. If you, nevertheless, need to do the installation by hand, hints for doing that (including configuration settings and package fixes) are given in the STAFSEA² User's Guide in section 3 and 4. The required prerequisites in yet successfully installed combinations are listed in the table above and need to be installed from left to right. The packages can be found in /group/ag_klima/SAMRAI-Framework/packages/. Extract the archives by using
$ tar xvfz <packageFileName.extension(s)>
If this does not work, omit the z and use
$ tar xvf <packageFileName.extension(s)>
instead. The folder /group/ag_klima/SAMRAI-Framework/configures/ contains the config.log files of each package, from each of which the ./configure ... line, used for installation to /group/ag_klima/SAMRAI-Framework/installation/, can be copied and applied after adaption to your local needs.

Note: omit the --with-hdf5= option during configuration of silo (see STAFSEA² User's Guide) if this causes problems such as in finding hdf5 headers.

Roughly, the installation process of each package is similar to the following one: * Extract the package as described above * move (mv) the extracted package folder to the desired location * go into that folder (cd) and create (mkdir) a folder (e.g. objs) for the object files to be installed to * go to the sub-folder level at which the configure file can be found * do the configure according to the config.log files in /group/ag_klima/SAMRAI-Framework/configures/ or as described in STAFSEA² User's Guide * compile the package (make -j ...) * install the package (_make install) After that you should find folders like lib or include in the respective objects folder.

Compiling STAFSEA²

If you still do not have the source code on your computer yet, it is time to get it now. Currently there are two different build versions available.

Classic Method

The classic variant simply loads the Makefile generated by SAMRAI, takes its compilation and linking flags and compiles all necessary C++ files into one binary. Thus, you have to tell this classic build system where to find SAMRAI. This is done by defining two environment variables.

The following example shows how to compile the current master branch from the git repository using the libraries according to PREREQUISITES OPTION 1. The following code lines set up the necessary environment and can be added to the .bashrc file in your home folder in order to be set with every new shell:
$ export PATH=/group/ag_klima/SAMRAI-Framework/installation/mpich-3.1.4/objs/bin:${PATH}
$ export LOC="/group/ag_klima"
$ export SAMRAI="${LOC}/SAMRAI-Framework/installation"
$ export SAMRAIDIR="${SAMRAI}/SAMRAI-v3.1.0-beta-fixed"
$ export SAMRAIDIRobjs="${SAMRAIDIR}/objs"
$ a visit='${SAMRAI}/visit2_9_2.linux-x86_64/bin/visit'
If added to your .bashrc, do not forget to type bash, followed by the enter key, in the commend line after saving the .bashrc file. The SAMRAIDIR variable points to the SAMRAI main directory in which e.g. the config.log file and folders like source and tools are located, and the SAMRAIDIRobjs variable points to the directory which was set in the SAMRAI configuration as --prefix (see SAMRAI config.log). Thus, they can, but do not necessarily have to, be equal. After that the following lines will compile STAFSEA² after proper setting of the preprocessor flags (for choosing various code options) in file Makefile.para.

$ cd path/to/stafseasquared
$ vim Makefile.para
... edit ... save and quit (:wq)
$ make -j 8

Note: the -j 8 option in line 4 above just tells make to use 8 parallel threads while compiling. It is recommended to use as many threads as available processors.

Autotools Method (TO BE UPDATED)

The classic method has some drawbacks:

  1. you can build the executable in the source directory only. This can be a great disadvantage.
  2. if, since your last SAMRAI compilation, something has changed with your paths or similar (even if you delete some sources) it breaks this method.

That is why a new autotools based method is introduced in order to address both problems. Just change your current git branch to "autotools" via the command

$ cd path/to/stafseasquared
$ git checkout autotools

Now we need to create a configure file via autotools. (This only needs to be done once at the first time. In future this won't be necessary anymore at all)

$ aclocal
$ autoconf
$ automake --add-missing

These commands will create a configure and a file called within the repository.

To create a Makefile use the following command:
$ <own_path>/stafseasquared/configure --with-samrai=<installations-path> --with-hypre=<installations-path> --with-mpi=<installations-path> --with-hdf5=<installations-path>
The installations-path specifies the folder of the respective object files.

Example: The following commands show how the build directory was set up during installation of PREREQUISITES OPTION 1:
$ mkdir -p /storage/mi/guttula/stafseasquared/builds/autotools
$ cd /storage/mi/guttula/stafseasquared/builds/autotools
$ ~/stafseasquared/configure --with-samrai=/storage/mi/guttula/samrai/v3.1.0-beta --with-hypre=/storage/mi/guttula --with-mpi=/storage/mi/guttula --with-hdf5=/storage/mi/guttula

This will create a Makefile in the build folder, which is configured with these paths. Now you can simply invoke make to compile STAFSEA².

$ make -j 8


Topic revision: r19 - 08 Sep 2016, waidmann
  • Printable version of this topic (p) Printable version of this topic (p)