Tutorial case metadata

[fsimonis]

Problem description

The layout of the preCICE tutorials are designed to be easy to understand: case directories including participant directories for various solvers including scripts to clean and run the case. This layout is sometimes insufficient as some cases use a single solver to run multiple participants such as the paritioned-heat-equation or the aste-turbine case.

This leads to issues where it becomes unclear on how to actually run a scenario, or even which solvers are available for which participant.

This can become tedious when running some tutorials in all combinations.

Proposed solution 1 - case meta data

We add a small metadata file which encodes:

1. which participants are required
2. the options per participant
3. how to run them (default to ./run)

Example for the elastic-tube-3d which all provide a run-script:

# elastic-tube-3d/.case.yml
fluid:
  - fluid-openfoam
solid:
 - solid-calculix
 - solid-fenics

Example for paritioned-heat-equation which run scripts require arguments:

# partitioned-heat-equation/.case.yml
dirichlet:
  - fencis: ./run -d
  - nutils: ./run -d
  - openfoam-dirichlet
neumann:
  - fenics: ./run -n
  - nutils: ./run -n
  - openfoam-neumann

Proposed solution 2 - case and solver meta data

We add solver metadata which encodes:

1. what the solver is based on (say the openfoam-adapter)
2. all participants the solver provides
3. how to run them (default to ./run)

We could then also provide case metadata which encodes the participants of the case.

Example for the elastic-tube-3d:

# elastic-tube-3d/.case.yml
participants:
  - fluid
  - solid

# elastic-tube-3d/fluid-openfoam/.solver.yml
needs: openfoam-adapter
provides:
  - fluid

# elastic-tube-3d/solid-calculix/.solver.yml
needs: calculix-adapter
provides:
  - solid

# elastic-tube-3d/solid-fenics/.solver.yml
needs: fenics-adapter
provides:
  - solid

Example for paritioned-heat-equation:

# partitioned-heat-equation/.case.yml
participants:
  - dirichlet
  - neumann

# partitioned-heat-equation/fencis/.solver.yml
needs: fenics-adapter
provides:
  - dirichlet: ./run -d
  - neumann: ./run -n

# partitioned-heat-equation/openfoam-dirichlet/.solver.yml
# same for openfoam-neumann
needs: openfoam-adapter
provides:
  - dirichlet

Tooling

This allows tooling support based on these simple formats. Imagine:

$ cd tutorials
$ precice-tutorials --available=python list
Tutorial cases runnable with only: python-bindings:
elastic-tube-1d [fluid-cpp fluid-python solid-cpp solid-python]

$ precice-tutorials --available=openfoam-adapter list
Tutorial cases runnable with only: openfoam-adapter:
elastic-tube-1d [fluid-cpp solid-cpp]
partitioned-heat-conduction [dirichlet-openfoam neumann-openfoam]

$ precice-tutorials --available=openfoam-adapter,calculix-adapter list
Tutorial cases runnable with only: openfoam-adapter,calculix-adapter:
elastic-tube-1d [fluid-cpp solid-cpp]
elastic-tube-3d [fluid-openfoam solid-calculix]
partitioned-heat-conduction [dirichlet-openfoam neumann-openfoam]

$ cd elastic-tube-3d
$ precice-tutorials list
Tutorial elastic-tube-3d
Participants
 fluid [fluid-openfoam]
 solid [solid-calculix solid-fenics]

$ precice-tutorials run solid-calculix solid-fenics
Missing participant:
  fluid [fluid-openfoam]

$ precice-tutorials run fluid-openfoam solid-fenics
running ...

$ precice-tutorials run --all
Running 2 combinations:
  fluid-openfoam and solid-calculix
  fluid-openfoam and solid-fencis

Running fluid-openfoam and solid-calculix
...
Running fluid-openfoam and solid-fencis
...

This could easily be extended with solver based postprocessing and check scripts

[MakisH]

We have already defined such metadata in the test cases we use in the system tests, for example: https://github.com/precice/tutorials/blob/develop/flow-over-heated-plate/metadata.yaml

Next step is to add such files everywhere (and have a way to keep them consistent).