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 an example or a benchmark 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 example or the benchmark.

3. How to contribute an example or a benchmark?

To contribute an example or a benchmark, 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.

is how the example tree directory looks like

examples
└── modules
    ├── ROOT
    │   └── pages
    ├── cfd (1)
    │   ├── examples (2)
    │   │   ├── cyclone
    │   │   │   └── attic
    │   │   └── flow_past_cylinder (3)
    │   └── pages (4)
    │       └── flow_past_cylinder
    └── csm (5)
        ├── assets (6)
        │   └── images (7)
        │       ├── ribs (8)
        │       ├── rotating-winch (8)
        │       ├── sensor (8)
        │       ├── sheet-rounding (8)
        │       ├── suspension (8)
        │       ├── t-beam (8)
        │       ├── torsion-bar (8)
        │       └── vierendeel-truss (8)
        └── pages (4)
            ├── ribs (9)
            ├── rotating-winch (9)
            ├── sensor (9)
            ├── sheet-rounding (9)
            ├── suspension (9)
            ├── t-beam (9)
            ├── torsion-bar (9)
            └── vierendeel-truss (9)
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 assets directory contains images or data associated to the examples.
7 the assets/images contains the images of each example
8 the images of each example are organized by directory named using the slug name of the example,
9 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 an example 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:

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

example/modules/<slug toolbox name>

3.3. Documentation setup

Follow the steps to setup the documentation:

  • clone the feelpp/toolbox repository

  • create a branch [example|benchmark]-#nn-<shortname>-<toolbox shortname> where

    • [example|benchmark] is either example or benchmark

    • #nn is the corresponding issue number in github

    • <shortname> is the code name of the example or benchmark

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

  • edit in antora.yml the field version and use wip-[example|benchmark]-#nn-<shortname>, wip meaning that it is a work in progress. The work done in the branch will appear in the documentation under development.

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

  • start filling up README.adoc using the template.

3.4. Implementation

Follow these steps :

  • create the directory examples/modules

  • create the geometry and add it or upload to Girder

  • add the cfg and .json files to examples/modules/<slug toolbox name>/examples/<slug example name>/

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

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.

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?

  • Learn about the toolboxes and how to create the .json and .cfg files