Getting Started

This section describes the available ways to to download, compile and install Feel++.


Using {feelpp} inside Docker is the recommended and fastest way to use {feelpp}. The Docker chapter is dedicated to Docker and {feelpp} containers chapter is dedicated to {feelpp} in 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


{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


libc++ (corresponding clang version)

clang (3.8(requires patches), 3.9)

libstdc++ 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







openmpi or mpich




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




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




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




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




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 and superlu_dist


umfpack (colamd,amd)



Uncertainty quantification

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


Open Source

Mesh Generation


Open Source





Open Source




Open Source


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)


Open Source


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


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 16.10 Yaketti Yak

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

$ sudo apt-get -qq update
$ sudo apt-get install automake autoconf libtool libboost-all-dev\
  bash-completion emacs24 gmsh libgmsh-dev libopenturns-dev \
  libbz2-dev libhdf5-openmpi-dev libeigen3-dev libcgal-dev \
  libopenblas-dev libcln-dev libcppunit-dev libopenmpi-dev \
  libann-dev libglpk-dev libpetsc3.7-dev libslepc3.7-dev \
  liblapack-dev libmpfr-dev paraview python-dev libhwloc-dev \
  libvtk6-dev libpcre3-dev python-h5py python-urllib3 xterm tmux \
  screen python-numpy python-vtk6 python-six python-ply wget \
  bison sudo xauth cmake flex gcc-6 g++-6 clang-3.9 \
  clang++-3.9 git ipython openmpi-bin pkg-config

Ubuntu 16.04

Here is the suggested installation of the Feel++ dependencies on Ubuntu LTS 16.04

$ sudo apt-get install autoconf automake bash-completion bison\
 clang++-3.8 clang-3.8 cmake emacs24 flex g++-6 gcc-6 git gmsh\
  ipython libann-dev libbz2-dev libcgal-dev libcln-dev \
  libcppunit-dev libeigen3-dev libglpk-dev libgmsh-dev \
  libhdf5-openmpi-dev libhwloc-dev liblapack-dev libmpfr-dev\
   libopenblas-dev libopenmpi-dev libopenturns-dev libpcre3-dev \
   libpetsc3.6.2-dev libproj-dev libslepc3.6.1-dev libtool \
   libvtk6-dev openmpi-bin paraview pkg-config python-dev \
   python-h5py python-numpy python-ply python-six \
   python-urllib3 python-vtk6 screen sudo tmux wget xauth xterm
We are unfortunately stung by the ABI change in GCC 6 when using clang. You need to recompile the Boost C++ libraries to be able to use clang, see the section in the Annexes on Compiling Boost.


Debian Sid and Testing

At the time of writing there is little difference between Sid and Testing, here is the recommend dependencies installation command line:

$ apt-get -y install \
    autoconf automake bash-completion bison cmake emacs24 \
    flex git gmsh ipython libann-dev libboost-all-dev \
    libbz2-dev libcgal-dev libcln-dev libcppunit-dev \
    libeigen3-dev libglpk-dev libgmsh-dev \
    libhdf5-openmpi-dev libhwloc-dev liblapack-dev \
    libmpfr-dev libopenblas-dev libopenmpi-dev \
    libopenturns-dev libpcre3-dev libtool libvtk6-dev \
    openmpi-bin paraview petsc-dev pkg-config python-dev \
    python-h5py python-numpy python-ply python-six \
    python-urllib3 python-vtk6 screen slepc-dev sudo \
    tmux wget xauth xterm zsh

Older distributions

Unfortunately the older distributions have the ABI GCC issue with clang, e.g. Debian/jessie, or they are too old to support a simple installation procedure.

Mac OS X

Feel++ is supported on Mac OSX, starting from OS X 10.9 Mavericks to OS X 10.12 Sierra using Homebrew or MacPorts.

First step

Xcode is required on Mac OSX to install Feel++.

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.


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.


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;

  • brew uninstall mypackage: This command allows to uninstall the package mypackage.


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.


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:

First install Homebrew

$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

then check your Homebrew installation and fix warnings/errors if necessary

$ brew doctor

Install Homebrew-science tap to get the scientific software recommended or suggested for Feel++.

$ brew tap homebrew/homebrew-science

you should see something like

==> Tapping homebrew/science
Cloning into '/usr/local/Homebrew/Library/Taps/homebrew/homebrew-science'...
remote: Counting objects: 661, done.
remote: Compressing objects: 100% (656/656), done.
remote: Total 661 (delta 0), reused 65 (delta 0), pack-reused 0
Receiving objects: 100% (661/661), 591.93 KiB | 0 bytes/s, done.
Tapped 644 formulae (680 files, 1.9M)

Next you install Feel++ tap with

brew tap feelpp/homebrew-feelpp

you should read something like

==> Tapping feelpp/feelpp
Cloning into '/usr/local/Homebrew/Library/Taps/feelpp/homebrew-feelpp'...
remote: Counting objects: 5, done.
remote: Compressing objects: 100% (5/5), done.
remote: Total 5 (delta 0), reused 4 (delta 0), pack-reused 0
Unpacking objects: 100% (5/5), done.
Tapped 1 formula (30 files, 60.7K)

The final step is to either install Feel++

$ brew install feelpp

or just Feel++ dependencies if you plan to build Feel++ from sources yourself

$ brew install --only-dependencies feelpp

Note If you encounter problems, you can fix them using brew doctor. A frequent issue is to force open-mpi with brew link --overwrite open-mpi

Advanced usage

If Homebrew is already installed on your system, you might want to customize your installation for the correct dependencies to be met for Feel++.

Feel++ Dependencies

You can browse Feel++ dependencies using the following command:

$ brew deps feelpp | column

you get the list of formulas Feel++ depends on for its installation

ann		fftw		libtool		slepc
arpack		gcc		metis		suite-sparse
autoconf	glpk		mumps		sundials
automake	gmp		netcdf		superlu
boost		gmsh		open-mpi	superlu_dist
cln		hdf5		parmetis	szip
cmake		hwloc		petsc		tbb
eigen		hypre		scalapack	veclibfort
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:

$ brew info open-mpi

You get various information about the open-mpi formula

open-mpi: stable 2.0.1 (bottled), HEAD
High performance message passing library
Conflicts with: lcdf-typetools, mpich
/usr/local/Cellar/open-mpi/2.0.1 (688 files, 8.6M) *
  Built from source on 2016-09-26 at 10:36:46 with: --c++11 --with-mpi-thread-multiple
From: https://github.com/Homebrew/homebrew-core/blob/master/Formula/open-mpi.rb
==> Dependencies
Required: libevent ✔
==> Requirements
Recommended: fortran ✔
Optional: java ✔
==> Options
	Build using C++11 mode
	Enable C++ MPI bindings (deprecated as of MPI-3.0)
	Build with java support
	Build without fortran support
	Install HEAD version

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 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.)

  • sudo port install mypackage: This action install the port mypackage.

  • sudo port uninstall mypackage: This action uninstall the port mypackage.

  • 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.


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.


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:

file:///<path to feel top directory>/ports/macosx/macports

Once it’s done, type in a command-line:

 $ cd <your path to feel top directory>/ports/macosx/macports
 $ sudo portindex -f

You should have an output like this:

Reading port index in $<$your path to feel top directory$>$/ports/macosx/macports
Adding port science/feel++
Adding port science/gmsh
Adding port science/petsc

Total number of ports parsed:   3
Ports successfully parsed:      3
Ports failed:                   0
Up-to-date ports skipped:       0

Your are now able to type

$ sudo port install feel++

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.

Compile your first Feel++ applications

$ make quickstart

Execute your first Feel++ application in sequential

$ cd quickstart
$ ./feelpp_qs_laplacian_2d --config-file qs_laplacian_2d.cfg

Execute your first Feel++ application using 4 mpi processes

$ mpirun -np 4 feelpp_qs_laplacian_2d --config-file qs_laplacian_2d.cfg

Downloading sources

Using Tarballs

Feel is distributed as tarballs following each major release. The tarballs are available on the Feel Releases web page.

Download the latest tarball, then uncompress it with:

$ tar -xzf feelpp-X.YY.0.tar.gz
$ cd feelpp-X.YY.0

You can now move to the section Using cmake.

Using Git

Alternatively, you can download the sources of Feel++ directly from the Git repository.

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

You should read something like

Cloning into 'feelpp'...
remote: Counting objects: 129304, done.
remote: Compressing objects: 100% (18/18), done.
remote: Total 129304 (delta 6), reused 0 (delta 0), pack-reused 129283
Receiving objects: 100% (129304/129304), 150.52 MiB | 1.69 MiB/s, done.
Resolving deltas: 100% (94184/94184), done.
Checking out files: 100% (7237/7237), done.
$ cd feelpp

The first level directory tree is as follows

$ tree -L 1 -d | column
.			├── databases		├── research
├── applications	├── doc			├── testsuite
├── benchmarks		├── feel		└── tools
├── cmake		├── ports		14 directories
├── contrib		├── projects
├── data		├── quickstart

Configuring Feel++

For now on, we assume that clang++ has been installed in /usr/bin. Yor mileage may vary depending on your installation of course.

It is not allowed to build the library in the top source directory.

It is recommended to have a directory (e.g. FEEL) in which you have both the sources and build directories, as follows

$ ls FEEL
feelpp/ # Sources
feel.opt/ # Build directory

feelpp is the top directory where the source have been downloaded, using git or tarballs.

Using cmake

The configuration step with cmake is as follows

$ cd FEEL/feel.opt
$ cmake ../feelpp -DCMAKE_CXX_COMPILER=/usr/bin/clang++-3.6 -DCMAKE_C_COMPILER=/usr/bin/clang-3.6 -DCMAKE_BUILD_TYPE=RelWithDebInfo

CMake supports different build type that you can set with -DCMAKE_BUILD_TYPE (case insensitive) : * None * Debug : typically -g * Release : typically -O3 -DNDEBUG * MinSizeRel : typically -Os * RelWithDebInfo : typically -g -O2 -DNDEBUG

Using configure

Alternatively you can use the configure script which calls cmake. configure --help will provide the following help.

Listing Configure help
 -b, --build                         build type: Debug, Release, RelWithDebInfo
 -d, --debug                         debug mode
-rd, --relwithdebinfo                relwithdebinfo mode
 -r, --release                       release mode
     --std=c++xx                     c++ standard: c++14, c++1z (default: c++14)
     --stdlib=libxx                  c++ standard library: stdc++(GCC), c++(CLANG) (default: stdc++)
     --max-order=x                   maximum polynomial order to instantiate(default: 3)
     --cxxflags                      override cxxflags
     --cmakeflags                    add extra cmake flags
     --prefix=PATH                   define install path
 -v, --verbose                       enable verbose output
 -h, --help                          help page
     --<package>-dir=PACKAGE_PATH    define <package> install directory
     --disable-<package>             disable <package>
     --generator=GENERATOR           cmake generator

We display below a set of possible configurations:

Compile using Release build type, default c compiler and libstdc

Listing compiling using default compilers
$ ../feelpp/configure -r

Compile using Release build type, clang compiler and libstdc

Listing compiling using clang++
$ CXX=clang++ ../feelpp/configure -r

Compile using Debug build type, clang compiler and libc

Listing compiling using clang/libc in Debug mode
CXX=clang++ ../feelpp/configure -d -stdlib=c++

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.