Docker

We strongly encourage you to follow these steps if you begin with
{feelpp} in particular as an end-user.

People who would like to develop with and in {feelpp} should
read through the remaining sections of this chapter.

System requirements

Compilers

{feelpp} uses C++14 compilers such as GCC6 and Clang. Currently it is not mandatory to have a C++14 stantard library but it will be soon.

There used to be a major compatibility issue between llvm/clang and GCC
compilers since GCC5 released the ABI tag which makes it impossible to compile
{feelpp} using llvm/clang with GCC5 or GCC6 standard libraries for a
time. Please see the following table to understand the working C++ compiler /
C++ standard library combinations.

Table 1. Table C++ compilers and standard libraries combinations

Compiler

Standard Library

clang (3.6, 3.7, 3.8)

libstdc++ 4.9

clang

libc++ (corresponding clang version)

clang (3.8(requires patches), 3.9)

libstdc++ 6

GCC 6

libstdc++ 6

GCC 6.2.1 seems to be problematic on debian/testing — the tests in the testsuite fail. — GCC 6.3.1 or GCC 6.2.0 don’t have any problems.

Required tools and libraries

Other than C++14 compilers, {feelpp} requires only a few tools and libraries, namely CMake, Boost C++ libraries and an MPI implementation such as open-mpi or mpich. The table below provides information regarding the minimum and maximum version supported. A — means it has not necessarily been tested with the latest version but we do not expect any issues. Note that for MPI, an implementation with MPI-IO support would be best.

Table 2. Table required tools to compile Feel++

Name

Minimum Version

Maximum Version

Notes

CMake

3.0

—

MPI

—

—

openmpi or mpich

Boost

1.55

1.63

Recommended libraries

Here is a list of libraries that we recommend to use jointly with Feel++.

Table 3. Table optional external libraries

Library

Minimum Version

Maximum Version

Notes

HDF5

1.8.6

1.8.16

Enables high performance I/O; Enables MED Support; Be careful on Debian/sid a more recent version of HDF5 breaks MED support

PETSc

3.2

3.7

Last is best; a requirement for parallel and high performance computing

SLEPc

3.2

3.7

last is best; a requirement for eigenvalue problem; depends on PETSc

Gmsh

2.8.7

2.16

last is best; a requirement if you want to be able to read many file formats; HDF5 version in Debian/sid currently breaks MED format support.

Superlu

superlu and superlu_dist

Suitesparse

umfpack (colamd,amd)

OpenTURNS

2.0

Uncertainty quantification

Recommended tools

Here is a list of tools that we recommend to use jointly with Feel++.

Table 4. Table of recommended tools

Tool

License

Notes

Computer Aided Design

Gmsh

Open Source

Mesh Generation

Gmsh

Open Source

MeshGems

Commercial

Post-Processing

Paraview

Open Source

Ensight

Commercial

Octave

Open Source

Gmsh

Open Source

Note that all these packages are available under Debian GNU/Linux and Ubuntu. Once you have installed those dependencies, you can go to Compiling.

Suggested tools

Here is a list of tools that we suggest to use jointly with Feel++.

Table 5. Table of suggested tools

Tool

License

Notes

Computer Aided Design (CAD)

Freecad

Open Source

Salome

Open Source

HDF5 version in Debian/sid currently breaks MED format support.

Modeling, Compilation and Simulation Environment

Open Modelica

Open Source

Debugging and Profiling

Google perftools

Open Source

Valgrind

Open Source

Feel++ on Linux

We now turn to the installation of the Feel++ dependencies
on Linux. Feel++ is currently support on Ubuntu (16.04,
16.10) and Debian (Sid, Testing).

Ubuntu

Ubuntu 16.10 Yaketti Yak

Here is the suggested installation of the Feel++ dependencies on Ubuntu 16.10

Mac OS X

First step

The easiest way to do so is to go through the Apple Store application and to search for Xcode. Xcode will provide the programming environment, e.g clang, for the next steps.

Homebrew

Introduction to HomeBrew

Homebrew is a free/open source software introduced to simplify the installation of other free/open source software on MacOS X. Homebrew is distributed under the BSD 2 Clause (NetBSD) license. For more information, visit their website.

Installation

To install the latest version of Homebrew, simply
visit their website and follow the instructions. Each new package Homebrew installs is built into an intermediate place called the Cellar (usually /usr/local/Cellar) and
then the packages are symlinked into /usr/local (default).

Key commands

Homebrew base command is brew. Here is a list of base available commands:

brew doctor: Check if the system has any problem with the current installation of Homebrew;

brew install mypackage: This command installs the package mypackage;

brew install [--devel|--HEAD] mypackage: These options respectively installs either the development version or the HEAD version of the package mypackage, if such versions are specified in the Formula file;

Formulas

A Formula is a Ruby script format specific to Homebrew. It allows to describe the installation process of a package. Feel++ uses specific Formulae that you can get in the Feel++ github repository: feelpp/homebrew-feelpp.

Installation

This section is aimed at users that do not have Homebrew already installed.
In order to build Feel++ from Homebrew, you have to do the following steps:

Customizing builds

If you want to customize the compilation process for a dependency (Set debug mode, Remove checking steps, Remove the link with certain libraries, etc.), you can access to the building options with the info flag. For exemple, with open-mpi:

Then, you then just have to pass the needed flags, when installing the dependency.

Important:boost has to be installed with mpi and c++11 support and mumps needs to be installed with the following scotch5 support.

MacPorts

Introduction

MacPorts is an open-source community projet which aims to design an easy-to-use system for compiling, installing and upgrading open-source software on Mac OS X operating system. It is distributed under BSD License and facilitate the access to thousands of ports (software) without installing or compiling open-source software. MacPorts provides a single software tree which includes the latest stable releases of approximately 17700 ports targeting the current Mac OS X release (10.9). If you want more information, please visit their website.

MacPorts Installation

To install the latest version of MacPorts, please go
to Installing
MacPorts page and follow the instructions. The simplest way is to
install it with the Mac OS X Installer using the pkg file
provided on their website. It is recommended that you install X11 (X Window System) which is normally used to display X11 applications.
If you have installed with the package installer (MacPorts-2.x.x.pkg) that means MacPorts will be installed in
/opt/local. From now on, we will suppose that macports has
been installed in /opt/local which is the default MacPorts
location. Note that from now on, all tools installed by MacPorts will be installed in /opt/local/bin or /opt/local/sbin
for example (that’s here you’ll find gcc4.7 or later e.g
/opt/local/bin/g++-mp-4.7 once being installed).

Key commands

In your command-line, the software MacPorts is called by the command port. Here is a list of key commands for using MacPorts, if you want more informations please go to MacPorts Commands.

sudo port -v selfupdate: This action should be used regularly to update the local tree with the global MacPorts ports. The option -v enables verbose which generates verbose messages.

port info mypackage: This action is used to get information about a port. (description, license, maintainer, etc.)

port installed: This action displays all ports installed and their versions, variants and activation status. You can also use the -v option to also display the platform and CPU architecture(s) for which the ports were built, and any variants which were explicitly negated.

sudo port upgrade mypackage: This action updgrades installed ports and their dependencies when a Portfile in the repository has been updated. To avoid the upgrade of a port’s dependencies, use the option -n.

Portfile

A Portfile is a TCL script which usually contains simple
keyword values and TCL expressions. Each package/port has a
corresponding Portfile but it’s only a part of a port description.
Feel++ provides some mandatory Portfiles for its compilation which are either not available in MacPorts or are buggy but Feel++ also provides some Portfiles which are already available in MacPorts such as gmsh or petsc. They usually provide either some fixes to ensure Feel++ works properly or new version not yet available in MacPorts. These Portfiles are installed in ports/macosx/macports.

Installation

To be able to install Feel++, add the following line in
/opt/local/etc/macports/source.conf at the top of the file
before any other sources:

It might take some time (possibly an entire day) to compile all the requirements for Feel++ to compile properly. If you have several cores on your MacBook Pro, iMac or MacBook, we suggest that you configure macports to use all or some of them.

To do that uncomment the following line in the file
/opt/local/etc/macports/macports.conf

buildmakejobs 0 $\#$ all the cores

At the end of the sudo port install feel++, you have all
dependencies installed. To build all the Makefile, \cmake is
automatically launched but can have some libraries may not be found but they are not mandatory for build Feel++, only the features related to the missing libraries will be missing.

Missing ports

cmake can build Makefiles even if some packages are missing (latex2html, VTK …​). It’s not necessary to install them but you can complete the installation with MacPorts, cmake will find them by itself once they have been installed.

Building Feel++

Once the steps to install on Linux or MacOS X has been followed, we explain, in this section, how to download and build Feel++ from source.

For the impatient

First retrieve the source

$ git clone https://github.com/feelpp/feelpp.git

Create a build directory

$ mkdir build
$ cd build

Configure Feel++

$ CXX=clang++ ../feelpp/configure -r

Compile the Feel++ library

$ make feelpp

you can speed up the make process by passing the option -j<N> where N is the number of concurrent make sub-processes. It compiles N files at a time and respect dependencies. For example -j4 compiles 4 C++ files at a time.

Be aware that Feel++ consumes memory. The Feel++ library compile with 2Go of RAM. But to be more comfortable, 4Go or more would be best. The more, the better.

Compiling Feel++

Once cmake or configure have done their work successfully, you are ready to compile Feel++

$ make

You can speed up the compilation process, if you have a multicore processor by specifying the number of parallel jobs make will be allowed to spawn using the -j flag:

Listing build Feel++ library using 4 concurrent jobs

$ make -j4 feelpp

From now on, all commands should be typed in build directory (e.g feel.opt) or its subdirectories.

Running the Feel++ Testsuite

If you encounter issues with Feel++, you can run the testsuite and send the resulting report. Feel++ has more than 300 tests running daily on our servers. Most of the tests are run both in sequential and in parallel.

The testsuite is in the testsuite directory.

$ cd testsuite

The following command will compile 10 tests at a time

$ make -j10

Listing: Running the Feel++ testsuite

$ ctest -j4 -R .

It will run 4 tests at a time thanks to the option -j4.

Docker

Docker is the recommended way if you are beginning using Feel++.

This chapter explains step by step how to get the Feel++ Container
System(FCS), how to execute a precompiled application, how to
parameter and run models.

Introduction

Container based technologies are revolutionizing development,
deployment and execution of softwares. Containers encapsulate a
software and allow to run seamlessly on different platforms — clusters, workstations, laptops — The developer doesn’t have to worry
about specific environments and users spend less time in configuring
and installing the software. Containers appear to be lightweight
virtual machines (VMs) — they are started in a fraction of a second — but they, in fact, have important differences.

One of the differences is the isolation process. The VMs share only
the hypervisor, the OS and hardware whereas containers may share,
between each other, large parts of filesystems rather than having
copies. Another difference is that, unlike in VMs, processes in a
container are similar to native processes and they do not incur the
overhead due to the VM hypervisor. The figure below illustrates these
fundamental differences. We see in particular that the applications 2
and 3 are sharing lib 2 without redundancy.

Figure 1. Figure : VMs vs Containers

Docker is a container technology providing:

an engine to start and stop containers,

a user friendly interface from the creation to the distribution of containers and

a hub — cloud service for container distribution — that provides publicly a huge number of containers to download and avoid duplicating work.

Installation

This section covers briefly the installation of Docker. It should be a relatively simple smooth process to install Docker.

Channels

Docker offers two channels: the stable and beta channels.

stable channel

is fully baked and tested software providing a reliable platform to work with. Releases are not frequent.

beta channel

offers cutting edge features and experimental versions of the Docker Engine. This is a continuation of the initial Beta program of Docker to experiment with the latest features in development. It incurs far more instabilities than the stable channel but releases are done frequently — possibly several releases per month.

In the latter we shall consider only installing and using the stable channel.

Installing Docker

At the time of writing this section, Docker is available on Linux, Mac and Windows.

Mac and Windows

The support for Mac and Windows as Host OS was recently released and Docker Inc provides installation processes Docker For Mac and Docker for Windows which are the recommended way of installing Docker on these platforms.

Linux

Most Linux distributions have their own packages but they tend to lag behind the stable releases of Docker which could be a serious issue considering the development speed of Docker.

Installing Binaries

The last possibility is to use Docker Binaries to install Docker. This should be used at the last resort if packages are provided neither by your distribution nor by Docker Inc.

Tested with Docker 1.12

At the time of writing this book, the Docker version we used is Docker 1.12. All commands have been tested with this version.

Running without sudo

On Linux, Docker is a priviledged binary, you need to prefix all your commands with sudo, e.g. on Ubuntu. You need first to belong to the docker group with the following command on Ubuntu

$ sudo usermod -aG docker

It creates the docker group if it doesn’t already exist and adds the current user to the docker group. Then you need to log out and log in again. Similar process is available on other distributions. You need also to restart the docker service

$ sudo service docker restart

From now on, we omit the sudo command when using Docker for the sake of brevity.

Adding a user to the docker group has security implications. On a shared machine, you should consider reading the Docker security page.

Checking Docker

We now check your installation by running docker version
To make sure everything is installed correctly and working, try running the docker version command. You should see something like the following on Linux or Mac.

then it means that the Docker daemon is not running or that the client cannot access it.

To investigate the problem you can try running the daemon manually — e.g. sudo docker daemon. This should give you some informations of
what might have gone wrong with your installation.

Feel++ Containers

Feel++ leverages the power of Docker and provides a stack of container images.

First steps

To test Docker is installed properly, try

$ docker run feelpp/feelpp-env echo 'Hello World!'

We have called the docker run command which takes care of executing
containers. We passed the argument feelpp/feelpp-env which is a
Feel++ Ubuntu 16.10 container with the required programming
and execution environment for Feel++.

feelpp/ in feelpp/feelpp-env provides the organization name (or namespace) of the image and feelpp-env is the image name. Note also that Docker specifies a more complete name feelpp/feelpp-env:latest including the tag name :latest. We will see later how we defined the latest tag at the Feel++ organization. See Feel++ Container System for more details.

This may take a while depending on your internet connection but
eventually you should see something like

The first line tells us that there is no local copy of this Feel++
image. Docker checks automatically online on the
Docker Hub if an image is available.

Once the image is downloaded, Docker launches the container and
executes the command we provided echo 'Hello World!' from inside the
container. The result of the command is showed on the last line of the
output log above.

If you run the command again, you won’t see the download part and the
command will be executed very fast.

We can ask Docker to give us a shell using the following command

$ docker run -it feelpp/feelpp-env

It provides a shell prompt from inside the container which is very
similar to what you obtain when login with ssh on a remote
machine. The flags -i and -t tell Docker to provide an interactive
session (-i) with a TTY attached (-t).

Feel++ Container System

The Feel++ Container System (FCS) is organized in layers and provides a set of images.

Naming

The naming convention of the FCS allows the user to know where they
come from and where they are stored on the
Docker Hub. The name of the images is
built as follows

feelpp/feelp-<component>[:tag]

where

feelpp/ is the namespace of the image and organization name

feelpp-<component> the image name and Feel++ component

[:tag] an optional tag for the image, by default set to :latest

Feel++ images(components) are defined as layers in the FCS in the table below.

Table 6. Table of the current components of the FCS

Component

Description

Built From

feelpp-env

Execution and Programming environment

<OS>

feelpp-libs

Feel++ libraries and tools

feelpp-env

feelpp-base

Feel++ base applications

feelpp-libs

feelpp-toolboxes

Feel++ toolboxes

feelpp-toolboxes

| Note:feelpp-env depends on an operating system image <OS>, the recommended and default <OS> is Ubuntu 16.10. In the future, we will build upon the next Ubuntu LTS or Debian Stable releases.

Tags

By default, the :latest tag is assumed in the name of the images, for example when running

$ docker run -it feelpp/feelpp-base

it is in fact feelpp/feelpp-base:latest which is being launched.
The following table displays how the different images depend from one another.

Image

Built from

feelpp-env:latest

Ubuntu 16.10

feelpp-libs:latest

feelpp-env:latest

feelpp-base:latest

feelpp-libs:latest

feelpp-toolboxes:latest

feelpp-base:latest

Host OS

As we said before the default Host OS is Ubuntu 16.10.
However Docker shines in continuous integration. It provides a large set of operating system to build upon and allows to check the software in various contexts. The FCS takes advantage of Docker to build feelpp-libs for several operating systems provided by feelpp-env and with different compilers any time a commit in the Feel++ repository is done.

Table 7. Table providing the list of supported Host OS

Operating system

version

feelpp-env Tags

Compilers

Ubuntu

16.10

ubuntu-16.10, latest

GCC 6.x, Clang 3.9

Ubuntu

16.04

ubuntu-16.04

GCC 6.x, Clang 3.8

Debian

sid

debian-sid

GCC 6.x, Clang 3.9,4.0

Debian

testing

debian-testing

GCC 6.x, Clang 3.9

If you are interested in testing Feel++ in these systems, you can run these flavors.

You see on the last but one line the directory $HOME/feel mounted on /feel in the Docker image.

Note that mouting a host sub-directory on /feel is
mandatory. If you don’t, the Feel++ applications will exit due to lack
of permissions. If you prefer running inside the docker environment
you can type unset FEELPP_REPOSITORY and then all results from
Feel++ applications will be store in $HOME/feel. But then
you will have to use `rsync or ssh to copy your results out of the
docker image if needed.