LifeV Installation Tutorial

Last update: February 1^th, 2013

Remarks

This tutorial, even if meant to be used on GNU/Linux, applies well also on other POSIX-compliant systems, such as MacOS X, with minor modifications.

Most of the basic dependencies are available on those systems, but probably with different names. As a rule of thumb, we suppose that for a given package (for instance HDF5), we will look for something named <pkgname>-openmpi-dev (so hdf5-openmpi-dev), where openmpi means that we want the OpenMPI-enabled version (parallel) with also developers files (includes and so on). We hope this covers most of the dubious cases.

It's also possible that on your system some packages are already installed (good for you ☺).

1 Development Environment

Basic requirement of LifeV and its major dependency Trilinos is a working development environment (such as GCC suite). We need:

GCC version ≥ 4.4.x, with g++ and gfortran available. Any other compiler (such as Intel or Clang) are probably fine, but not covered by the present tutorial;
CMake version ≥ 2.8.x;
Boost version ≥ 1.44.x. It's preferrable to install the full library (all component), although the basic one should be enough;
OpenMPI version ≥ 1.4.x. As stated concerning the compilers, any other MPI2 compliant implementation is fine, but not considered here;
Doxygen version ≤ 1.7.5.x or ≥ 1.8.x (1.7.6.x is buggy), Graphviz and LaTeX (facultative packages, required only if documentation generation is enabled).

Of course, these packages have many dependencies, but your favorite package manager will take care of this.

For instance, on Ubuntu 11.10, let's open a Terminal and write:

user@hostname:~$ sudo apt-get install g++ gfortran cmake \
libboost-all-dev openmpi-bin libopenmpi-dev doxygen doxygen-latex graphviz

Note: it's not a problem if you want to run parallel LifeV on a ordinary machine and not on a cluster: MPI simply runs the selected number of processes and the operating system will take care of executing them using different cores. Of course, every process has its own protected memory.

2 Basic Scientific Libraries

There're several optional dependencies for Trilinos concerning scientific libraries. From LifeV viewpoint, we can limit ourself to:

BLAS and LAPACK for linear algebra. ATLAS implementation is the most common one, but there are several options out there (Intel MKL for instance);
ParMETIS version 3.x (4.x not supported by Trilinos) for mesh partitioning;
HDF5 library version 1.8.x, which handles particular heterogeneous and distribuite files, well suited for scientific computing;
UMFPACK and AMD, contained inside SuiteSparse collection, which implements direct solvers for linear systems.

Again, on Ubuntu 11.10, it looks like this:

user@hostname:~$ sudo apt-get install libblas-dev \
liblapack-dev libparmetis-dev libhdf5-openmpi-dev libsuitesparse-dev

3 Setting up the Environment

Inside your home directory (tipically /home/<username>) create a directory that will contain LifeV and Trilinos.
If you prefer to install the libraries in /usr/local, you need to set that path accordingly during configuration (CMAKE_INSTALL_PREFIX).
We'll call this directory lifev-env.

user@hostname:~$ mkdir lifev-env && cd lifev-env

4 Trilinos

In this section we will install Trilinos directly from source code, because the package inside Ubuntu Repositories is not well suited for our purposes (it's too old).

The recommended version as of January 2013 is 10.12.x. We are still working to ensure full compatibility with Trilinos 11.

user@hostname:~/lifev-env$ wget http://trilinos.sandia.gov/download/files/trilinos-10.12.2-Source.tar.gz
--2013-02-01 14:21:13--  http://trilinos.sandia.gov/download/files/trilinos-10.12.2-Source.tar.gz
Resolving trilinos.sandia.gov... 132.175.81.4
Connecting to trilinos.sandia.gov|132.175.81.4|:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 100694138 (96M) [application/x-gzip]
Saving to: ‘trilinos-10.12.2-Source.tar.gz’

100%[======================================>] 100,694,138 8.29MB/s   in 19s    

2013-02-01 14:21:33 (4.95 MB/s) - ‘trilinos-10.12.2-Source.tar.gz’ saved [100694138/100694138]

user@hostname:~/lifev-env$ tar xfz trilinos-10.12.2-Source.tar.gz
user@hostname:~/lifev-env$ mkdir trilinos-{build,install}

Only if you are using Trilinos 10.10.x, see section 4.1.

Now, create a new script file named config-trilinos:

user@hostname:~/lifev-env$ gedit config-trilinos &

and paste this code:

#!/bin/bash 
pushd $HOME/lifev-env/trilinos-build || return 1
cmake \
  -D CMAKE_BUILD_TYPE:STRING=RELEASE \
  -D CMAKE_INSTALL_PREFIX:STRING="$HOME/lifev-env/trilinos-install" \
  -D TPL_ENABLE_MPI:BOOL=ON \
  -D TPL_ENABLE_BLAS:BOOL=ON \
  -D TPL_ENABLE_LAPACK:BOOL=ON \
  -D TPL_ENABLE_HDF5:BOOL=ON \
  -D TPL_ENABLE_ParMETIS:BOOL=ON \
  -D TPL_ENABLE_UMFPACK:BOOL=ON \
  -D TPL_ENABLE_AMD:BOOL=ON \
  -D TPL_ENABLE_Boost:BOOL=ON \
  -D TPL_ENABLE_Zlib:BOOL=ON \
  -D TPL_ENABLE_Pthread:BOOL=ON \
  -D Trilinos_ENABLE_Teuchos:BOOL=ON \
  -D Trilinos_ENABLE_Epetra:BOOL=ON \
  -D Trilinos_ENABLE_EpetraExt:BOOL=ON \
  -D Trilinos_ENABLE_Zoltan:BOOL=ON \
  -D Trilinos_ENABLE_AztecOO:BOOL=ON \
  -D Trilinos_ENABLE_Belos:BOOL=ON \
  -D Trilinos_ENABLE_Anasazi:BOOL=ON \
  -D Trilinos_ENABLE_Amesos:BOOL=ON \
  -D Trilinos_ENABLE_Ifpack:BOOL=ON \
  -D Trilinos_ENABLE_ML:BOOL=ON \
  -D Trilinos_ENABLE_NOX:BOOL=ON \
  -D Trilinos_ENABLE_Rythmos:BOOL=ON \
  -D Trilinos_ENABLE_Thyra:BOOL=ON \
  -D UMFPACK_INCLUDE_DIRS:PATH="/usr/include/suitesparse" \
  -D AMD_INCLUDE_DIRS:PATH="/usr/include/suitesparse" \
  ../trilinos-10.10.1-Source || return 1
popd

In principle, no modification is needed. Save & close and return back to the shell.

user@hostname:~/lifev-env$ chmod +x config-trilinos
user@hostname:~/lifev-env$ ./config-trilinos

[...]

-- Configuring done
-- Generating done
-- Build files have been written to: /home/lifev/lifev-env/trilinos-build
user@hostname:~/lifev-env$ cd trilinos-buid
user@hostname:~/lifev-env/trilinos-build$ make -j3 install
user@hostname:~/lifev-env/trilinos-build$ cd ..

The compilation takes a while, depending on your system. Trilinos should be installed in ~/lifev-env/trilinos-install.

4.1 Patching Trilinos 10.10.x

Unfortunately, there is a small bug in the HDF5 Exporter in Trilinos 10.10.x, that prevents the correct behavior of specific parts of LifeV (FSI tests), so we need a patch.
Open your favorite text editor (gedit for example):

user@hostname:~/lifev-env$ gedit EpetraExt_HDF5.patch &

and paste this code:

--- a/packages/epetraext/src/inout/EpetraExt_HDF5.cpp
+++ b/packages/epetraext/src/inout/EpetraExt_HDF5.cpp
@@ -371,15 +371,23 @@ void EpetraExt::HDF5::Open(const std::string FileName, int AccessType)

   FileName_ = FileName;

-  // create the file collectively and release property list identifier.
-  file_id_ = H5Fopen(FileName.c_str(), AccessType, H5P_DEFAULT);
+  // Set up file access property list with parallel I/O access
+  plist_id_ = H5Pcreate(H5P_FILE_ACCESS);

 #ifdef HAVE_MPI
-// FIXME: DO I NEED THE MPIO_COLLECTIVE??
-//  plist_id_ = H5Pcreate(H5P_DATASET_XFER);
-//  H5Pset_dxpl_mpio(plist_id_, H5FD_MPIO_COLLECTIVE);
+  // Create property list for collective dataset write.
+  const Epetra_MpiComm* MpiComm ( dynamic_cast<const Epetra_MpiComm*> (&Comm_) );
+
+  if (MpiComm == 0)
+    H5Pset_fapl_mpio(plist_id_, MPI_COMM_WORLD, MPI_INFO_NULL);
+  else
+    H5Pset_fapl_mpio(plist_id_, MpiComm->Comm(), MPI_INFO_NULL);
 #endif

+  // create the file collectively and release property list identifier.
+  file_id_ = H5Fopen(FileName.c_str(), AccessType, plist_id_);
+  H5Pclose(plist_id_);
+
   IsOpen_ = true;
 }

--- a/packages/epetraext/src/inout/EpetraExt_HDF5.h
+++ b/packages/epetraext/src/inout/EpetraExt_HDF5.h
@@ -45,6 +45,10 @@
 #include "EpetraExt_ConfigDefs.h"
 #ifdef HAVE_EPETRAEXT_HDF5

+#define H5Gopen_vers 2
+#define H5Dopen_vers 2
+#define H5Gcreate_vers 2
+#define H5Dcreate_vers 2
 #include <string>
 #include "hdf5.h"
 class Epetra_Map;

Save & quit, then:

user@hostname:~/lifev-env$ patch -p1 -d trilinos-10.10.1-Source < EpetraExt_HDF5.patch

5 LifeV

The following instructions are meant to be used for installing versions of LifeV up to 2.x (available for download at http://www.lifev.org/downloads). For version 3, please refer to our GitHub webpage and our source management portal.

Download the latest release of LifeV at the address http://www.lifev.org/downloads, and save it in lifev-env directory (the same one of Trilinos).

user@hostname:~/lifev-env$ tar xfj lifev-2.2.1.tar.bz2
user@hostname:~/lifev-env$ mkdir lifev-{build,install}

As done before, reopen your favorite text editor for LifeV configuration:

user@hostname:~/lifev-env$ gedit config-lifev &

and paste this code:

#!/bin/bash 
pushd $HOME/lifev-env/lifev-build || return 1
../lifev-2.2.1/configure \
  --prefix="${HOME}/lifev-env/lifev-install" \
  CC="mpicc" \
  CXX="mpicxx" \
  FC="mpif90" \
  F77="mpif77" \
  --enable-opt \
  --with-trilinos="${HOME}/lifev-env/trilinos-install" \
  --with-umfpack-include="/usr/include/suitesparse" \
  --with-umfpack-lib="/usr/lib" \
  --with-amd-include="/usr/include/suitesparse" \
  --with-amd-lib="/usr/lib" \
  --with-hdf5="/usr" || return 1
popd

Close and return back to the shell:

user@hostname:~/lifev-env$ chmod +x config-lifev
user@hostname:~/lifev-env$ ./config-lifev

[...]

Good - your configure finished. Start make now

user@hostname:~/lifev-env/lifev-build$ cd lifev-build
user@hostname:~/lifev-env/lifev-build$ make && make install
user@hostname:~/lifev-env/lifev-build$ cd ..

Congratulations! Now LifeV should be installed in ~/lifev-env/lifev-install. Have fun!

6 Running a testcase

Just to be sure that everything works correctly, you can run a testcase. This is important not only because we can check if the installation is correct, but also because it is a good starting point for working with LifeV.

For example, we can try to solve a simple Fluid-Structure Interaction (FSI) problem with 2 processes:

user@hostname:~/lifev-env$ cd lifev-build/testsuite/test_fsi
user@hostname:~/lifev-env/lifev-build/testsuite/test_fsi$ make check
user@hostname:~/lifev-env/lifev-build/testsuite/test_fsi$ make link
user@hostname:~/lifev-env/lifev-build/testsuite/test_fsi$ mpirun -np 2 test_fsi

Note: the command make link simply creates symbolic links for the data file and the mesh.

If you want to try all the tests inside testsuite directory, you can try make check on top directory $HOME/lifev-env/lifev-build.

7 Visualising Output

One of the most used tool for scientific visualization is ParaView. You can install it directly with the package manager:

user@hostname:~$ sudo apt-get install paraview

or download it directly from www.paraview.org to get a newer version. Now you can open output files with ParaView!

8 Documentation

LifeV is a complex library, so if you need API documentation you can just type (Doxygen, Graphviz and LaTeX are needed):

user@hostname:~/lifev-env$ cd lifev-build
user@hostname:~/lifev-env/lifev-build$ make apidox && make install-apidox

Documentation main file is ~/lifev-install/share/doc/lifev/api/html/index.html.

LifeV Project

Installation Tutorial

LifeV Installation Tutorial

1 Development Environment

2 Basic Scientific Libraries

3 Setting up the Environment

4 Trilinos

4.1 Patching Trilinos 10.10.x

5 LifeV

6 Running a testcase

7 Visualising Output

8 Documentation