search

precice / preeco-orga

Organization and material for the preECO project
MIT License
3 stars 0 forks source link

Compile tentative adapter checklist #7

Open uekerman opened 3 months ago

uekerman commented 3 months ago

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:

fsimonis commented 2 months ago

As @uekerman mentioned in https://github.com/precice/precice/issues/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 https://github.com/precice/precice/issues/1305 and when integrating the logging with ASTE https://github.com/precice/aste/issues/73. It is currently possible to configure logging without an API in preCICE by going through the boost.log core.

uekerman commented 2 months ago

Reasons why using preCICE for logging could still be advantageous:

fsimonis commented 2 months ago

Possible API design

General:

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 commented 2 months ago

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

fsimonis commented 2 months ago

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 commented 2 months ago

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 commented 2 months ago

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 commented 1 month ago

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 https://github.com/precice/precice/issues/2033.

uekerman commented 3 days ago

Outcome of the first discussion with @MakisH. Further discussion is planned for the coding days.

Main idea

What is an adapter? An adapter can be an independent code, but can also mean solver + integrated adapter. Adapter can be a class, a patch, a library, or something else. But it needs to be something > 0. The "Nutils adapter" in this sense is no adapter as it is only a collection of application cases. We could even go one step further and include tools as well, i.e. everything that calls preCICE, or even everything that concerns preCICE.

We distinguish between metadata and best practices. The latter has three level, i.e. bronze, silver, and gold. We list on the website every adapter that has all required metadata and at least bronze level. If an adapter has at least silver level, hosting under the preCICE GitHub organization is possible, but no must.

Metadata

The usual things. Non-complete list:

Best practices

Each level has a main theme to simplify orientation. The lists are not complete yet, but should rather give some first impression.

Bronze

Findable and Accessible, i.e., the adapter is working and documented. Others can find, build, and run the code and they should understand what is does. The bare minimum. We need a low entry barrier.

Silver

Interoperable and maintainable. The adapter plays well with other adapters from the community and feels part of the preCICE ecosystem. The preCICE maintainers are, if necessary, able to maintain the adapter (e.g. update it to newer preCICE versions).

Gold

Reusable, community-ready, and integrated. Others can easily reuse and extend the adapter for their own needs. Maintaining the adapter could be shared among many. We can integrate the adapter and corresponding application cases into our development workflows and make sure that we will not break it. All tooling works seamlessly.