Redesigned preCICE tutorials and documentation, preCICE distribution, and more news

News
1

Dear preCICE community,

If you were looking at our website and tutorials lately, you may had already noticed a wind of change (something that we discussed here a while ago). preCICE is growing and we never stop reflecting on what is working for you and what needs further improvement.

Redesigned tutorials (and website)

This is where you will find the preCICE tutorials from now on:

tutorials-home
tutorials-home1532Ă—1134 267 KB

Apart from the website itself, we also redesigned the tutorials of preCICE during the past months. Why? Well, previously, cases often had cryptic and inconsistent names (e.g. flap_perp), were offered only for specific combinations of solvers (e.g. OpenFOAM-CalculiX) and had quite some duplication in the related run & clean scripts. This worked for quite a while, but had started becoming… spaghetti :spaghetti: as we added more and more cases.

Until now, the workflow was to always get the latest master branch of the tutorials. We now introduce releases, starting from v202104.1.0 (and the following patch v202104.1.1), which you can rely upon and refer to for the next months. We will be following the scheme <yearmonth>.<minor>.<patch>, following the system used in the preCICE VM (Vagrant box).

Let’s go together through the release notes and add a few details:

  • No more scattering of documentation: Find everything directly in our redesigned preCICE website. The content is rendered directly from the README.md files in the tutorials repository. You can directly edit these pages on GitHub and even the smallest typo fix is welcome. Look for this button on each page of the website:

edit-me

  • No more scattering of case files among different repositories: We know, keeping the OpenFOAM-only cases in the OpenFOAM adapter repository did not really help.
  • New directory structure. Read more in the contributing guidelines.

contributing-tutorials
contributing-tutorials1415Ă—852 135 KB

  • Self-contained cases: The files for each case are inside its own sub-directory, e.g. fluid-openfoam.

  • Arbitrary combinations of solvers: Run OpenFOAM-CalculiX, OpenFOAM-deal.II, SU2-deal.II, … you name it!

  • A standard way to run each case: Get into the case folder you want to run and execute ./run.sh. We kept these scripts as short as possible, so that you can easily copy from them.

run-sh
run-sh1663Ă—620 202 KB

  • A standard way to clean: A clean<what>.sh script in each directory cleans up everything from this level and deeper.
  • An easy-to-run first tutorial: Have you ever met your friends wanting to play a new board game and decided to read the half-page “Quickstart” instead of the 16-pages rules book? Then this is for you! We created a quickstart tutorial to get everything you need and run a simple case on your laptop. In case you looked at this a few weeks back, try again, it is brand new!

quickstart
quickstart981Ă—376 53.2 KB

  • Better 2D cases: Two-dimensional cases such as the (now defined on the XY-plane) perpendicular flap are using the 2D interface of preCICE and every involved adapter supports a 2D mode. No more spurious RBF-related errors when running a tutorial.

  • A validated Turek-Hron FSI3: No more “cylinder-flap is almost like FSI3, but not exactly”. You can now validate your cases starting from this case, validated with OpenFOAM and a non-linear neo-Hookean solid model in deal.II.

  • Formatting & linting: Our Python scripts, shell scripts, and Markdown files are now a little bit more robust and pretty! Special thanks to PEP8, shellcheck, and markdownlint.

Update your adapters to their latest state and enjoy! :hugs:

More adapter releases

It may have been unclear for you which adapter versions you were running so far. We are continuously working on improving this, with the main challenge being deciding on a future-proof versioning and releasing strategy for each adapter. We have started fixing this on some adapters, such as the FEniCS adapter (since February).

We now also have the first OpenFOAM adapter release. This adapter now also includes a CHANGELOG.md and several tooling improvements that will make the development easier. As maintaining an adapter version for each actively used OpenFOAM version is becoming more and more challenging, we are going to support the latest OpenFOAM.com by default and try to provide archives for other versions with every release. Note, however, that we cannot test all the versions in the same depth.

The preCICE distribution and demo VM

As so far it has not been well documented which adapter versions work together with which version of the tutorials and which version of preCICE, we decided to collect all compatible versions in an overall snapshot, which we refer to as preCICE distribution. You can now also find a list of the latest versions of all components that are known to work together on the preCICE distribution page. We are working to also make this distribution citable.

You may also want to try the latest Demo virtual machine, which contains the latest versions of everything (now also code_aster).

With love,
:precice: the preCICE team

2 Likes