Tutorial case metadata

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

Start by comparing the two proposed metadata designs against the tutorial case directories and the example .case.yml and .solver.yml files in the issue. Resolve which format and tooling scope should be implemented before making changes. Done means the metadata model and its supported tutorial-listing or run behavior are agreed and documented.