Compile tentative adapter checklist

[uekerman]

The adapter checklist should contain criteria that an adapter needs to fulfill to be "preCICE conforming". If necessary, criteria could also be organized in hierarchical quality levels (bronze, silver, gold). We then want to establish a clear review workflow. Once conforming, adapters are listed on the preCICE website together with the necessary metadata and get a "preCICE badge". Both should be independent of where the actual source code is hosted. Adapters hosted under the preCICE organization on GitHub, on the other hand, need to fulfill a fixed quality level (e.g., at least "bronze"). Similarly, all adapters with a fixed quality level (e.g., at least "silver"), are bundled into the preCICE distribution. Together with the checklist, we also want to compile templates, for example for adapter documentation and automation (formatting, documentation hosting, building, running tests, etc.).

Besides standard FAIR4RS criteria, one could include the following:

• adapter configuration, which adheres to a solver-independent standard (needs to be defined) if no
  solver-internal solution exists (such the OpenFOAM dictionary for the OpenFOAM adapter),
• coupling data and meshes adhere to a standard naming pattern (needs to be defined)
• defined (standard) versioning scheme, changelog, and clear information, which solver versions are
  supported
• documentation (provide README.md template) on how to build/configure/cite/...
• explanation of which preCICE features are supported or not supported (include potential list in
  README.md template)
• defined code style and provided formatter
• at least one provided application case to test the adapter
• unit tests
• configurable logging (use preCICE for logging through API?)
• contribution guidelines and potentially pull request template
• information on how the adapter was validated and how validation could be reproduced
• contact information of original developers and current maintainers
• citation of published overhead study

[fsimonis]

As @uekerman mentioned in precice/precice#1647, standardizing adapter profiling could also make sense.

defined code style and provided formatter

We have the precice-configuration-formatter, which is included in https://github.com/precice/precice-pre-commit-hooks/tree/main/format_precice_config
It may be worth moving that to a separate pypi package for easier integration.

configurable logging (use preCICE for logging through API?)

We did some groundwork regarding logging when working on the Fluent adapter precice/precice#1305 and when integrating the logging with ASTE precice/aste#73. It is currently possible to configure logging without an API in preCICE by going through the boost.log core.

[uekerman]

Reasons why using preCICE for logging could still be advantageous:

• Users that don't know any logging package don't need to learn one
• Language-independent solution
• Configuration of the logger (concerning all preCICE things) in single place

[fsimonis]

Possible API design

General:

• I would avoid any formatting capability in the API and only receive a message to log.
• We can still handle debug log in preCICE even if we use a Release build. Currently, we only turn the PRECICE_Debug() into a no-op.
• Should error logs still result in a crash?

Function + Enum

Participant::log("component", Severity::Info, "message");

Only 1 function, but requires handling an enum in bindings.

Function for severities

Participant::logDebug(  "component", "message");
Participant::logInfo(   "component", "message");
Participant::logWarning("component", "message");
Participant::logError(  "component", "message");

Easier to handle in bindings, but many functions.

[uekerman]

This is pretty much what I had in mind. I guess we could even remove component and set this always to "adapter".

[fsimonis]

Specifying the component could make run scripts that start both solver easier to follow.
But that is as far as I can come up with use-cases.

[MakisH]

I have the feeling this discussion should better be moved into a separate issue in precice/precice.

I like the logDebug, logInfo, etc. It should indeed be the most portable solution, and I don't think that the more functions is really an issue. These are just a few, very simple, very similar auxiliary functions.

I assume that, if preCICE is built without debug messages, but the adapter is built with debug messages enabled, the user should still see debug messages from the adapter, right? As an adapter developer, if I use preCICE built in release mode (e.g., on a cluster, installed by an admin), I would still like to see the debug messages I add in my adapter.

Specifying the component could make run scripts that start both solver easier to follow.

Do we still have such scripts anywhere? Users might, but we generally discourage it, no?

[fsimonis]

Do we still have such scripts anywhere? Users might, but we generally discourage it, no?

It can be convenient to quickly start both solvers. Especially when environment variables need to be set (including venv) or one is on a cluster. Realistically all of this should go into scripts though to make this easier to repeat.

[BenjaminRodenberg]

I would suggest to require data initialization to reach a certain level, because not having initial data makes the tutorials less flexible and can lead to bugs in the time stepping (degradation of convergence order). See precice/precice#2033.