What is a Toolbox

Feel++ comes with toolboxes. What are they ?

Definition: A Feel++ Toolbox

For a given set of partial differential equations for a given physics (e.g. computational fluid dynamics) or set of physics (e.g. fluid structure interaction), a Feel++ toolbox provides:

  • the configuration the set of equations through one or several (.json) files and (.cfg) files

  • one or more solution strategies to solve the set of equations

Using the JSON and CFG, it is possible to configure and run models by defining the relevant physical quantities—such as material properties, loads, constraints, sources, and fluxes.

1. JSON files

The Model JSON (.json) files allow to configure a set of partial differential equations, more precisely they define:

1.1. Names

A model JSON file starts by giving names (long and short).

"Name": "Turek-Hron cfd2", (1)
"ShortName":"cfd2", (2)
1 Name of the example, usually printed on-screen and in log files during simulations
2 Short name of the example, it is used to create directories to store the results of the simulation of the model
These names are not used currently, but it should be the case in the future.

1.2. Models

A section Models can appear if the toolbox has several kinds of model (typically for select the PDE used). In most toolboxes, this section is optional and a model by default is choosen. The latter allows to configure the set of equations associated with fluid toolbox.

"Models": (1)
{
   "equations":"Navier-Stokes" (2)
}
1 Section Models defined by the toolbox to define the main configuration of a toolbox and in particular the set of equations to be solved
2 toolbox specific option to define set of equations to be solved, read the toolbox manual to learn about the possible options.

1.3. Parameters

This section of the Model JSON file defines the parameters that may enter expressions used in the subsequent sections.

Example of a Parameters section
"Parameters": (1)
    {
        "ubar":"1.0" (2)
    }
1 name of the section
2 defines a new parameter ubar and its associated value

1.4. Materials

This section of the Model JSON file defines material properties linking the Physical Entities in the mesh data structures to these properties.

Example of Materials section
"Materials":
    {
        "Water": (1)
        {
            "physics":"fluid", (2)
            "markers":"[marker1,marker2]", (3)
            "rho":"1.0e3", (4)
            "mu":"1.0" (5)
        }
    }
1 gives the name of the physical entity (here Physical Surface) associated to the Material.
2 defined which kind of physics is applied in this material. This is an optional section, by default all physics are applied. The value can be also a vector of physic.
3 defined mesh marker(s) where the material properties are applied. This is an optional section, by default the marker is take as the name <1>.
4 density \(\rho\) is called rho and is given in SI units
5 viscosity \(\mu\) is called mu and is given in SI units

1.5. BoundaryConditions

This section of the Model JSON file defines the boundary conditions.

Example of a BoundaryConditions section
"BoundaryConditions":
    {
        "velocity":  (1)
        {
            "Dirichlet": (2)
            {
                "inlet": (3)
                {
                    "expr":"{ 1.5*ubar*(4./0.1681)*y*(0.41-y),0}:ubar:y" (4)
                },
                "wall1": (5)
                {
                    "expr":"{0,0}" (6)
                },
                "wall2": (7)
                {
                    "expr":"{0,0}" (8)
                }
            }
        },
        "fluid": (9)
        {
            "outlet": (10)
            {
                "outlet": (11)
                {
                    "expr":"0" (12)
                }
            }
        }
    }
1 the field name of the toolbox to which the boundary condition is associated
2 the type of boundary condition to apply, here Dirichlet
3 the physical entity (associated to the mesh) to which the condition is applied
4 the mathematical expression associated to the condition, note that the parameter ubar is used
5 another physical entity to which Dirichlet conditions are applied
6 the associated expression to the entity
7 another physical entity to which Dirichlet conditions are applied
8 the associated expression to the entity
9 the variable toolbox to which the condition is applied, here fluid which corresponds to velocity and pressure \((\mathbf{u},p)\)
10 the type of boundary condition applied, here outlet or outflow boundary condition
11 the hysical entity to which outflow condition is applied
12 the expression associated to the outflow condition, note that it is scalar and corresponds in this case to the condition \(\sigma(\mathbf{u},p) \normal = 0 \normal\)

1.6. PostProcessing

This section allows to define the output fields and quantities to be computed and saved for e.g. visualization.

Template of a PostProcess section
"PostProcess":
{
    "Exports":
    {
        "fields":["field1","field2",...]
    },
    "Measures":
    {
        "<measure type>":
        {
            ....
        }
    }
}

1.7. Exports

The Exports section is implemented when you want to visualize some fields with ParaView software for example. The entry fields should be filled with names which are available in the toolbox used.

1.8. Measures

Several quantities can be computed after each time step for transient simulation or after the solve of a stationary simulation. The values computed are stored in a CSV file format and named <toolbox>.measures.csv. In the template of PostProcess section, <measure type> is the name given of a measure. In next subsection, we present some types of measure that are common for all toolbox. Other types of measure are available but depend on the toolbox used, and the description is given in the specific toolbox documentation.

The common measures are :

1.8.1. Points

TODO

1.8.2. Statistics

The next table presents the several statistics that you can evaluate :

Statistics Type Expression

min

\( \underset{x\in\Omega}{\min} u(x) \)

max

\( \underset{x\in\Omega}{\max} u(x) \)

mean

\( \frac{1}{ | \Omega |} \int_{\Omega} u \)

integrate

\( \int_{\Omega} u \)

with u a function and \( \Omega\) the definition domain where the statistic is applied.

The next source code shows an example of Statistics section with several kinds of computation. The results are stored in a CSV file at columns named Statistics_mystatA_mean, Statistics_mystatB_min, Statistics_mystatB_max, Statistics_mystatB_mean, Statistics_mystatB_integrate.

Example of a Statistics section
"Statistics":
{
    "mystatA": (1)
    {
        "type":"mean", (2)
        "field":"temperature" (3)
    },
    "mystatB": (4)
    {
        "type":["min","max","mean","integrate"], (5)
        "expr":"2*x+y:x:y", (6)
        "markers":"omega" (7)
    }
}
1 the name associated with the first Statistics computation
2 the Statistics type
3 the field u evaluated in the Statistics (here the temperature field in the heat toolbox)
4 the name associated with the second Statistics computation
5 the Statistics type
6 the field u evaluated in the Statistics
7 the mesh marker where the Statistics is computed (\(\Omega\) in the previous table). This entry can be a vector of marker

The function u can be a finite element field or a symbolic expression. We use the field entry for a finite element field and expr for symbolic expression. field and expr can not be used simultaneously.

All expressions can depend on specifics symbols related to the toolboxes used. For example, in the heat toolboxes :

"expr":"2*heat_T+3*x:heat_T:x"

where heat_T is the temperature solution computed at last solve. It can also depend on a parameter defined in the Parameters section of the JSON.

The quadrature order used in the statistical evaluation can be specified. By default, the quadrature order is 5. For example, use a quadrature order equal to 10 is done by adding :

"quad":10
Quadrature order is also used with min and max statistics. We get the min/max values by evaluating the expression on each quadrature points.
In the mean and integrate Statistics, the quadrature order is automatically chosen when field is used. In this case, the quad entry has no effect.

The expression can be a scalar, a vector or a matrix. However, there is a particularity in the case of mean or integrate statistics with non-scalar expression. The result is not a scalar value but a vector or matrix. We store in the CSV file each entry of this vector/matrix.

1.8.3. Norm

The next table presents the several norms that you can evaluate :

Norm Type Expression

L2

\( \| u \|_{L^2} = \left ( \int_{\Omega} \| u \|^2 \right)^{\frac{1}{2}}\)

SemiH1

\( | u |_{H^1} = \left ( \int_{\Omega} \| \nabla u \|^2 \right)^{\frac{1}{2}} \)

H1

\( \| u \|_{H^1} = \left ( \int_{\Omega} \| u \|^2 + \int_{\Omega} \| \nabla u \|^2 \right)^{\frac{1}{2}} \)

L2-error

\( \| u-v \|_{L^2} = \left ( \int_{\Omega} \| u-v \|^2 \right)^{\frac{1}{2}}\)

SemiH1-error

\( | u-v |_{H^1} = \left ( \int_{\Omega} \| \nabla u-\nabla v \|^2 \right)^{\frac{1}{2}} \)

H1-error

\( \| u-v \|_{H^1} = \left ( \int_{\Omega} \| u-v \|^2 + \int_{\Omega} \| \nabla u-\nabla v \|^2 \right)^{\frac{1}{2}} \)

where \(\| . \|\) represents the norm of the generalized inner product. The symbol u represents a field or an expression and v an expression.

The next source code shows an example of Norm section with two norm computations. The results are stored in a CSV file at columns named Norm_mynorm_L2 and Norm_myerror_L2-error.

Example of a Norm section
"Norm":
{
    "mynorm": (1)
    {
        "type":"L2", (2)
        "field":"velocity" (3)
     },
     "myerror": (4)
     {
         "type":"L2-error", (5)
         "field":"velocity", (6)
         "solution":"{2*x,cos(y)}:x:y", (7)
         "markers":"omega" (8)
     }
}
1 the name associated with the first norm computation
2 the norm type
3 the field u evaluated in the norm (here the velocity field in the fluid toolbox)
4 the name associated with the second norm computation
5 the norm type
6 the field u evaluated in the norm
7 the expression v with the error norm type
8 the mesh marker where the norm is computed (\(\Omega\) in the previous table). This entry can be a vector of marker
with the H1-error or SemiH1-error norm, the gradient of the solution must be given with grad_solution entry. Probably this input should be automatically deduced in the near future.

Several norms can be computed by listing it in the type section :

"type":["L2-error","H1-error","SemiH1-error"],
"solution":"{2*x,cos(y)}:x:y",
"grad_solution":"{2,0,0,-sin(y)}:x:y",

An expression (scalar/vector/matrix) can be also passed to evaluate the norm. But in this case, the field entry must be removed and this expression replaces the symbol u.

"expr":"2*x*y:x:y"
As before, in the case of H1 or SemiH1 norm type, the grad_expr entry must be given.
"grad_expr":"{2*y,2*x}:x:y"

All expressions can depend on specifics symbols related to the toolboxes used. For example, in the heat toolboxes :

"expr":"2*heat_T+3*x:heat_T:x"

where heat_T is the temperature solution computed at last solve. It can also depend on a parameter defined in the Parameters section of the JSON.

The quadrature order used in the norm computed can be also given if an analytical expression is used. By default, the quadrature order is 5. For example, use a quadrature order equal to 10 is done by adding :

"quad":10

1.9. An example

"PostProcess": (1)
    {
        "Exports": (2)
        {
            "fields":["velocity","pressure","pid"] (3)
        },
        "Measures": (4)
        {
            "Forces":"wall2", (5)
            "Points": (6)
            {
                "pointA": (7)
                {
                    "coord":"{0.6,0.2,0}", (8)
                    "fields":"pressure" (9)
                },
                "pointB": (10)
                {
                    "coord":"{0.15,0.2,0}", (11)
                    "fields":"pressure" (12)
                }
            }
        }
    }
1 the name of the section
2 the Exports identifies the toolbox fields that have to be exported for visualisation
3 the list of fields to be exported
4 the Measures section identifies outputs of interest such as
5 Forces applied to a surface given by the physical entity wall2
6 Points values of fields
7 name of the point
8 coordinates of the point
9 fields to be computed at the point coordinate
10 name of the point
11 coordinates of the point
12 fields to be computed at the point coordinate

Here is a biele example from the Toolbox examples.

2. CFG files

The Model CFG (.cfg) files allow to pass command line options to Feel++ applications. In particular, it allows to

  • setup the output directory

  • setup the mesh

  • setup the time stepping

  • define the solution strategy and configure the linear/non-linear algebraic solvers.

  • other options specific to the toolbox used

directory=toolboxes/fluid/TurekHron/cfd3/P2P1G1 (1)

case.dimension=2 (2)
case.discretization=P2P1G1 (3)

[fluid] (4)
filename=$cfgdir/cfd3.json (5)

mesh.filename=$cfgdir/cfd.geo (6)
gmsh.hsize=0.03 (7)

solver=Newton (8)

pc-type=lu (9)

bdf.order=2 (10)

[ts]
time-step=0.01 (11)
time-final=10 (12)
1 the directory where the results are stored
2 the dimension (2d/3d) of the application
3 the discretization choosen (specific to the toolbox)
4 the prefix of option
5 the path of the json file
6 the path of geo/mesh file
7 characterist size of the mesh
8 type of non linear solver (specific to fluid toolbox)
9 type of preconditioner
10 order of BDF tiem scheme (specific to fluid toolbox)
11 time step
12 time final

If the mesh file is stored on a remote storage as Girder, the mesh.filename option in the previous listing can be replaced by

mesh.filename=girder:{file:5af862d6b0e9574027047fc8}

where 5af862d6b0e9574027047fc8 is the id of the mesh file in the Girder platform. All options for Girder access are listed here :

Option Default value Description

url

girder.math.unistra.fr

url of a Girder platform

file

<no default value>

one or several file id(s)

api_key

<no default value>

an authentication key

3. Run an application

Each toolbox are compiled in an executable named feelpp_toolbox_<tbname> where <tbname> is name of a toolbox. A non-exhaustive list of toolbox executables is :

  • feelpp_toolbox_fluid

  • feelpp_toolbox_solid

  • feelpp_toolbox_heat

  • feelpp_toolbox_heatfluid

  • feelpp_toolbox_thermoelectric

  • feelpp_toolbox_fsi_2d

  • feelpp_toolbox_fsi_3d

  • feelpp_toolbox_advection_2d

With this executable, a cfg file must be given in the command line thanks to the config-file option :

feelpp_toolbox_fluid --config-file myfile.cfg

Another way is to use the case option, where case represents a folder containing a cfg, json files and eventually a geometry or mesh file.

feelpp_toolbox_fluid --case mydir

If the folder contains only one cfg, the programme use this one. Else it’s possible to specify the cfg file to choose by adding case.config-file option

feelpp_toolbox_fluid --case mydir --case.config-file myfile.cfg

The case option can also define a folder which represents a remote data in a github repository.

feelpp_toolbox_fluid --case "github:{path:toolboxes/fluid/TurekHron}" --case.config-file cfd2.cfg

The remote data from github can be configured by several parameters :

Option Default value Description

owner

feelpp

the github organization

repo

feelpp

the github repository in organization

branch

<default in github>

the branch in the git repository

path

<root of repository>

the path in the git repository

token

<no default value>

an authentication token

feelpp_toolbox_fluid --case "github:{owner:feelpp,repo:feelpp,branch:develop,path:toolboxes/fluid/TurekHron,token:xxxxx}" --case.config-file cfd2.cfg