Multi-Physics Toolboxes Contribution Guide

In the spirit of free software, everyone is encouraged to help improve our Multi-Physics toolboxes. New contributors are always welcome! Here, we discuss the different ways to contribute to Feel++ multiphysics toolboxes. You can contribute

We start first with explaining the difference between an example and a benchmark.

1. What is the difference between an example and a benchmark?

A benchmark is essentially an example which contains data that allows to either:

  • verify that the model(the equation set) was solved correctly, this is called verification. Synthetic data is provided to make the verification or data provived by another software

  • verify that the model solved is the correct one, this is called validation. Experimental data is provided to make the validation or data provided by another software which have been validated.

  • verify that the performance of the model scale properly, this includes weak and strong scalability benchmarking.

2. How to contribute a case description?

Anyone can propose or suggest a new example to be added to the Feel++ toolbox repository. To do so, start a new issue and select the Example Request template. You just then have to fill out the example or benchmark request.

The answers provided can, almost directly, be used to document the case documentation file.

3. How to contribute a case?

To contribute a case description, you need to follow the steps:

But first you need to understand the file organization of the examples and benchmarks directory tree.

3.1. File organization

It is important that you read Antora File Organization section before continuing.

This is how the examples tree directory may look like

examples
└── modules
    ├── ROOT
    │   └── pages
    ├── cfd (1)
    │   ├── examples (2)
    │   │   ├── cyclone
    │   │   │   └── attic
    │   │   └── flow_past_cylinder (3)
    │   └── pages (4)
    │       └── flow_past_cylinder
    └── csm (5)
        ├─── images (6)
        │    ├── ribs (7)
        │    ├── rotating-winch (7)
        │    ├── sensor (7)
        │    ├── sheet-rounding (7)
        │    ├── suspension (7)
        │    ├── t-beam (7)
        │    ├── torsion-bar (7)
        │    └── vierendeel-truss (7)
        └── pages (4)
            ├── ribs (8)
            ├── rotating-winch (8)
            ├── sensor (8)
            ├── sheet-rounding (8)
            ├── suspension (8)
            ├── t-beam (8)
            ├── torsion-bar (8)
            └── vierendeel-truss (8)
1 example module for the computational fluid dynamic (cfd) toolbox
2 examples contains the examples input dataset
3 example directory flow_past_cylinder containing the configuration files (cfg, json, geo, …​)
4 pages contains the documentation pages where Antora look into to transform .adoc files into .html files
5 example module for the computational solid mechanics (csm) toolbox
6 the images directory contains images associated to the examples.
7 the images of each example are organized by directory named using the slug name of the example,
8 each example documentation is located in a topic directory named using the slug name of the example. The topic directory contains .adoc files.
the slug name of a case does not contain spaces or dots or any special characters and can for example be used in url.

3.2. Toolbox

You need to identify which toolbox the example belongs to. here is the list of slug toolbox name:

cfd

Computational Fluid Dynamics

csm

Computation Solid Mechanics

heat

Heat transfer

heatfluid

Heat and CFD coupling

fsi

Fluid Structure Interaction (FSI), CFD and CSM coupling

thermoelectric

Electrostatic and heat coupling

The example is then located in the model named after The slug name of the toolbox:

examples/modules/<slug toolbox name>

3.3. Documentation setup

Follow the steps to setup the documentation:

  • clone the feelpp/toolbox repository

  • create a branch case-#nn-<shortname>-<toolbox shortname> where

    • #nn is the corresponding issue number in github

    • <shortname> is the code name of the case

    • <toolbox shortname> is the code name of the toolbox used, it is optional

  • edit in antora.yml the field version and use <latest version>-case-#nn-<shortname>, <latest version> meaning the latest version number upon which we build the documentation, e.g 0.105. The work done in the branch will appear in the documentation under development.

    here is an example

0.105-case-20-cylinder

  • create a topic in `[examples]/modules/<toolbox>/pages/<short name>/README.adoc

  • start filling up README.adoc using the case template file.

3.4. Implementation

Follow this step :

  • create the geometry (e.g. .geo), .cfg and .json files to cases/modules/<slug toolbox name>/examples/<slug case name>/

The input files for the example electromagnet in the thermoelectric toolbox are in examples/modules/thermoelectric/examples/electromagnet/

3.5. Documenting numerical results

Once the test case description and implementation are done, there remains to document the numerical results obtained with Feel++. This step may require

  • generating images (.png format) using e.g. Paraview to show the mesh and fields

  • generating Vtkjs files to have 3D interactive models embedded in the browser to show the mesh and fields

  • generating Plot.ly interactive graphics embedded in the browser to show 2D data, convergence plots, …​

The generation of Vtkjs files is now preferred as it permits interaction. Have a look at the examples in computational solid mechanics providing both images and Vtkjs files.

The image files for the example electromagnet in the thermoelectric toolbox are in examples/modules/thermoelectric/images/electromagnet/
Read about how to create and use Vtkjs files and about contributing data using girder.

3.6. Submission

Once you have started working and committing to Github, propose a pull request (PR) for merging into the master branch.

4. What’s next?