Step by step into Feel++ Programming

Output Directories

Feel++ generates various files that are spread over various directories.
For this tutorial, it would be beneficial to check the content of these files
to familiarize yourself with Feel++.

Environment variables

Some of Feel++ behavior can be driven by environment variables such as

FEELPP_REPOSITORY

FEELPP_WORKDIR

Both variables should point to the same place. They define the root directory where the simulation results will be stored. By default they are set to $HOME/feel.

If you want to change the root directory where the results are stored, define e.g. FEELPP_REPOSITORY. For example in the docker image feel/apps:latest, it points to /feel.

For running,

docker run -it -v $HOME/feel:/feel feelpp/apps:latest

should get you this output

# Feel++ applications
This image provides the Feel++ applications in
. advection
. fluid mechanics
. solid mechanics
. fluid-structure interaction
. thermodynamics
The testcases are in $HOME/Testcases/ and the results are in
$HOME/feel
Follow the steps described in
http://book.feelpp.org/content/Applications/Models/readme.html
to use the models.
feelpp@50381de2bd23:~$

Adding options

We pass command line options using the Boost Program Options, library using the prefix po:: which is a {feelpp} alias for the Boost::program_options namespace. To add a new {feelpp} option, we must create a new {feelpp} options_description. You must add the default {feelpp} options
and the new one that we choose here as a double value. Note that the default value will be assigned if not specified by the user.

Compilation execution and logs

To compile a tutorial, just use the GNU make command.

make feelpp_tut_<appname>

where <appname> is the name of the application you wish to compile (here, myapp). Go to the execution directory as specified in the program, and execute it.You can list the log files created :

ls /tmp/<your login>/feelpp/feelpp_tut_myapp/

If you open one of these log, you should be able to see your value and the processor number used to compute. You can run your application on several processors using MPI :

mpirun -np 2 feelpp_tut_myapp

Note that there will be one log for each processor in that case.

Config files

A config file can be parsed to the program to profile your options. The default config paths are,

current dir

$HOME/Feelpp/config/

$INSTALL_PREFIX/share/Feelpp/config/

then you have to write inside one of these folders a file called
<app_name>.cfg or feelpp_<app_name>.cfg. For example, our
myapp.cfg would look like :

value=0.53

Note that you can specify the config file through the option --config-file=<path>

It’s also possible to give several configuration files with the option --config-files <path1> <path2> <path3>

./feelpp_tut_myapp --config-files ex1.cfg ex2.cfg ex3.cfg

In the case where some options are duplicated in the files, the priority is given at the end :

ex3.cfg can overwrite options in ex2.cfg and ex1.cfg

ex2.cfg can overwrite options in ex1.cfg

All files in --config-files can overwrite options given by --config-file. And all options in the command line can overwrite all options given in cfg files.

Initializing PETSc, SLEPc and other third party libraries

PETSc is a suite of data structures and routines for the scalable (parallel) solution of scientific applications modeled by partial differential equations. It employs the MPI standard for parallelism.

Loading a Mesh

The next step is to load a mesh.

The loadMesh function has a _name option set by default as the
default value of the --gmsh.filename option that point either to a
.geo, either to a .msh, or a .h5 file. Meshes in general are
more detail into this section.

automesh=loadMesh(_mesh=newMesh<Simplex<2>>);

Exporting the Mesh for visualisation

See this section for more details about exporting and visualizing meshes.

You can print back the expression to the screen to check that
everything is ok. You want to use as expression a*x+b*y, you have to
define a and b as option (either in your code, either in the
library).

Visualizing functions over a mesh

The next step is to visualize function over the mesh. The source code that generate our output is
available in myexporter.cpp, presented in the previous section.

You can visualize data via :

link::https://www.ceisoftware.com/[ensight]

link::http://www.paraview.org/[paraview]

link::http://geuz.org/gmsh[gmsh]

The results files are in

$HOME/feel/myexporter/np_1

or

$FEELPP_WORKDIR/feel/myexporter/np_1.

We discriminate output directories based on the name of the simulation
(the parameter _name in the environment), the number of process
(mpirun -np …​) and the type of the chosen exporter

--exporter.format={ensight|ensightgold|gmsh|...}

Spaces and elements

You’ve learned how to discretize the space you want to compute on.
You now have to learn how to define and use function spaces and
elements of functions spaces. For advanced informations on this
subject, you can look in the Function Space documentation.

Computing integrals over mesh

The next step is to compute integrals over the mesh ( See this for detailed methods ).

Step by step explanations

We start by loading a Mesh in 2D

then we define the Feel++ expression that we are going to integrate
using the soption function that retrieves the command line option
string functions.g. We then transform this string into a Feel++
expression using expr().

then we compute two integrals over the domain and its boundary respectively

\$\int_\Omega g\$

\$\int_{\partial \Omega} g\$

and we print the results to the screen.

Only the rank 0 process (thanks to Environment) isMasterRank()
prints to the screen as the result is the same over all mpi processes
if the application was run in parallel. Note also that the code
actually prints the expression passed by the user through the command
line option functions.g.

Some results

We start with the following function \$g=1\$. Recall that by default
the domain is the unit square, hence the \$\int_\Omega g\$ and
\$\int_{\partial\Omega} g\$ should be equal to 1 and 4 respectively.

Note that we don’t get the exact results due to the fact that
[stem]:[\Omega_h = \cup_{K \in \mathcal{T}_h} K] which we use for the numerical integration is different from the exact domain \$\Omega = \{ (x,y)\in \mathbb{R}^2 | x^2+y^2 < 1\}\$.

Using a backend

Introduction

After the discretization process, one may have to solve a (non) linear
system. Feel++ interfaces with PETSc/SLEPc and Eigen3. Consider this
system

\$A x = b\$

We call Backend an object that manages the solution strategy to
solve it. Some explanation are available at
Solver and
Preconditioner.

Feel++ provides a default backend that is mostly hidden to the final
user. In many examples, you do not have to take care of the
backend. You change the backend behavior via the command line or
config files. For example

./feelpp_doc_mybackend --backend.pc-type=id

will use the identity matrix as a right preconditionner for the
default backend. The size of the preconditionner will be defined from
the size of the A matrix.

If you try to solve a different system \$A_1 y= c\$ (in size) with
the same backend or the default without rebuilding it, it will fail.

backend(_rebuild=true)->solve(_matrix=A1,_rhs=c,_sol=y);

Each of that options can be retrieved via the --help-lib argument in the command line.

Non default Backend

You may need to manage more than one backend in an application: you
have different systems to solve and you want to keep some already
computed objects such as preconditioners.

The default backend is in fact an unnamed backend: in order to
distinguish between backend you have to name them. For example

Defining a Model

Introduction

It is well known an equation can describe a huge range of physical
problems. Each of theses problems will have a particular environment,
but the equation to solve will be the same. To make our program
applicable to theses range of problem, we have defined a model. Models
definitions can be retrieve in this
section.

What is a model

A model is defined by :

a Name

a Description

a Model

Parameters

Materials

Boundary Conditions

Post Processing

Parameters

A parameter is a non physical property for a model.

Materials

To retrieve the materials properties, we use :

ModelMaterialsmaterials=model.materials();

BoundaryConditions

Thanks to GiNaC, we handle boundary conditions (Dirichlet, Neumann, Robin) as expression. You have to indicate in the json file the quantity to handle (velocity, pressure…​) and the associated expression.

Naming Convention

In {feelpp}, we basically follow the same naming conventions as in Qt and
KDE.

Class names starts with a capital. The rest is in camel case. Function
names starts with a lower case, but the first letter of each successive
word is capitalized.

Functions and classes should be in the Feel namespace.

The prefix set is used for setters, but the prefix get is not used
for accessors. Accessors are simply named with the name of the property
they access. The exception is for accessors of a boolean which may start
with the prefix is.