Adapter and tool configuration schema

[uekerman]

We currently have a zoo of configuration options:

Adapter or tool	Format
CalculiX adapter	yml
code_aster adapter	comm solver-specific
deal.II adapter	prm solver-specific
DUNE adapter	?
DuMuX adapter	?
FEniCS adapter	JSON
Nutils adapter	hard-coded
OpenFOAM adapter	dict solver-specific
SU2 adapter	hard-coded & command-line parser
ASTE	JSON
FMI runner	JSON
Micro manager	JSON

Some solver-specific solutions are quite meaningful. Other solutions reinvent the wheel. We have no standard and no schema yet. The latter could also enable quite some tooling support.

Example:

FEniCS adapter: precice-adapter-config.json

{
  "participant_name": "Solid",
  "config_file_name": "../precice-config.xml",
  "interface": {
      "coupling_mesh_name": "Solid-Mesh",
      "write_data_name": "Heat-Flux",
      "read_data_name": "Temperature",
      "interpolation_type": "rbf"
    }
}

FMI runner: precice-settings.json

{
    "coupling_params": {
        "participant_name": "Mass-Left",
        "config_file_name": "../precice-config.xml",
        "mesh_name": "Mass-Left-Mesh",
        "write_data_name": "Force-Left",
        "read_data_name": "Force-Right"
    }
}

ASTE replay:

{
  "participant": "Fluid",
  "startdt": "1",
  "meshes": [
    {
      "mesh": "Fluid-Mesh",
      "meshfileprefix": "./exported-meshes/Fluid-Mesh-Fluid",
      "read-data": {
        "vector": ["Displacement"]
      },
      "write-data": {
        "vector": ["Force"]
      }
    }
  ],
  "precice-config": "../precice-config.xml"
}

[uekerman]

A schema could look like this (very first draft):

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "participant_name": {
      "type": "string",
      "description": "Name of the participant."
    },
    "config_file_name": {
      "type": "string",
      "description": "Path to the configuration file."
    },
    "interfaces": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "mesh_name": {
            "type": "string",
            "description": "Name of the mesh associated with this interface."
          },
          "write_data_names": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of data fields to be written on this mesh."
          },
          "read_data_names": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of data fields to be read on this mesh."
          }
        },
        "oneOf": [
          {
            "required": ["write_data_names"]
          },
          {
            "required": ["read_data_names"]
          }
        ],
        "required": ["mesh_name"]
      }
    }
  },
  "required": ["participant_name", "config_file_name", "interfaces"]
}

This now enables tooling, for example to get a GUI via the MetaConfigurator.

[fsimonis]

If we want to use something less verbose and significantly easier to read than JSON, we should strongly consider TOML.

Language support

Possible dealbreaker is that TOML doesn't feature a validation schema yet.

Examples

FEniCS adapter: precice-adapter-config.json

participant_name = "Solid"
config_file_name = "../precice-config.xml"

[interface]
coupling_mesh_name = "Solid-Mesh"
write_data_name = "Heat-Flux"
read_data_name = "Temperature"
interpolation_type = "rbf"

FMI runner: precice-settings.json

[coupling_params]
participant_name = "Mass-Left"
config_file_name = "../precice-config.xml"
mesh_name = "Mass-Left-Mesh"
write_data_name = "Force-Left"
read_data_name = "Force-Right"

ASTE replay:

participant = "Fluid"
startdt = 1
precice-config = "../precice-config.xml"

[[meshes]]
mesh = "Fluid-Mesh"
meshfileprefix = "./exported-meshes/Fluid-Mesh-Fluid"

  [meshes.read-data]
  vector = [ "Displacement" ]

  [meshes.write-data]
  vector = [ "Force" ]

[davidscn]

Just a side comment:

deal.II adapter prm solver-specific

while that's true, json format is also supported and available in deal.II.

[uekerman]

@Logende This is the schema I just talked about. Could be an additional showcase for your thesis.

[fsimonis]

An initial step may be to unify the syntax of all configuration files.

There are tools that allow checking various formats against json schema files:
https://www.npmjs.com/package/pajv

There are also some format-specific toolkits that offer json schema validation:
https://taplo.tamasfe.dev/

[MakisH]

Some solver-specific solutions are quite meaningful. Other solutions reinvent the wheel. We have no standard and no schema yet. The latter could also enable quite some tooling support.

An initial step may be to unify the syntax of all configuration files.

I think we first need to agree on whether we want to enforce every adapter to use the same configuration file format, even in the case the solver-specific solution makes sense.

History:

1. We (well... @uekerman / the developers back then) tried this in 2016/2017 with Lucia's thesis. This is why the CalculiX adapter still has a YAML-based file: we wanted to enforce all adapters to have the same format, to be able to prepare the files automatically.
2. In the OpenFOAM adapter, we switched to an OpenFOAM dictionary for two reasons:
   • A technical reason: It was tricky to get a compatible combination of yaml-cpp and OpenFOAM, as they were linking to different std::string ABI (pre- and post-C++11). This specific reason should not hold today, but we anyway wanted to reduce dependencies.
   • A usability reason: Users had to write one config in XML, another in YAML, and then also in the formats of each solver. We thought that if adapters are native to the solver, then it should be easier, because users anyway need to know or learn the config formats of each solver.
3. In some adapters where no standard was common (e.g., FEniCS), we started with JSON, because this is one of the established machine-readable data-exchange formats. Not particularly ergonomic for writing (as a user, I would prefer writing YAML/TOML), I would argue, but that's irrelevant.

In the proposal, we also don't really specify the enforcement:

Finally, we want to take advantage of the standardization process of work package WP2 to also generate standard adapter configurations for all coupled participants, in case a standard is not already in place (e.g., for the OpenFOAM adapter, see WP2).

I think that:

• Yes, having a standard helps tooling (both tools that will need to write these files).
• Having a standard could also help validating the files with our own tools (but maybe not let the solvers validate the files based on their knowledge).
• We need to choose this standard carefully, and not only based on what most adapters are already using.
• The arguments for solver-native files are weak, provided that all adapters can actually read the established format without issues. We should do a thorough check first for the suitability for each adapter.
• Tooling could generate solver-specific files. But of course, we would need to maintain these tools. In the end, it is a matter of where we handle the maintenance: in these tools, or in the adapters.

Going one step further, I still think that many (not all) of the options we currently provide via adapter configurations could be sourced from the preCICE configuration file, see the older issue precice/precice#474.

[fsimonis]

I think we first need to agree on whether we want to enforce every adapter to use the same configuration file format, even in the case the solver-specific solution makes sense.

To my understanding, @uekerman proposed to use a solver-native solution if available and use a uniform format as the default fallback.

[uekerman]

Even if we continue to also allow solver-native solutions (we have indeed learned in the past that this is very helpful), we could still make them use the same (language-independent) schema. Currently, OpenFOAM, for example, already follows a very similar schema, only in a different language.

preciceConfig "precice-config.xml";

participant Fluid;

modules (CHT);

interfaces
{
  Interface1
  {
    mesh              Fluid-Mesh;
    patches           (interface);
    locations         faceCenters;

    readData
    (
      Heat-Flux
    );

    writeData
    (
      Temperature
    );
  };
};

[uekerman]

If you give ChatGPT the schema and the OpenFOAM config, it can convert to JSON:

{
  "participant_name": "Fluid",
  "config_file_name": "precice-config.xml",
  "interfaces": [
    {
      "mesh_name": "Fluid-Mesh",
      "patches": [
        "interface"
      ],
      "location": "faceCenters",
      "read_data_names": [
        "Heat-Flux"
      ],
      "write_data_names": [
        "Temperature"
      ]
    }
  ]
}

[uekerman]

The reverse direction seems to work as well. We could generate the following at least:

preciceConfig "../precice-config1.xml";

participant Fluid;

interfaces
{
  Interface1
  {
    mesh              Fluid-Mesh;
    writeData
    (
      Displacement
      Temperature
    );

    readData
    (
      Velocity
    );
  };
};

[uekerman]

@Logende How could we integrate the latter two use cases into MetaConfigurator?

Assumption: We have our fixed JSON schema.

• Import OpenFOAM dictionary from file and convert into JSON.
• Edit some JSON (e.g. via GUI) and then export as OpenFOAM dictionary.

Similarly, it would be good if we could import / export yaml.

[Logende]

@Logende How could we integrate the latter two use cases into MetaConfigurator?

Assumption: We have our fixed JSON schema.

• Import OpenFOAM dictionary from file and convert into JSON.
• Edit some JSON (e.g. via GUI) and then export as OpenFOAM dictionary.

Similarly, it would be good if we could import / export yaml.

On the first one I am working right now: creation of JSON document according to schema based on data in a different format.
The second one is more a niche use case, I will work on that next and determine a suitable place for that feature. Probably in the menu a file can not only be exported as JSON but also in different formats, given some example input by the user.

YAML export is already possible.

[uekerman]

given some example input by the user

Maybe in the settings, the user could add any arbitrary niche export format, together with a url for an example?

[MakisH]

I think we need to find a simpler name/acronym than "preATCS" (no better ideas yet, but let's brainstorm). I have a strong feeling that most people (including most of us) will have trouble remembering or pronouncing this name.

[uekerman]

I think we need to find a simpler name/acronym than "preATCS" (no better ideas yet, but let's brainstorm). I have a strong feeling that most people (including most of us) will have trouble remembering or pronouncing this name.

Yes, was merely a placeholder for the moment. I simply wanted to talk about "the" schema, not "a" schema to make things more urgent.

[fsimonis]

Your goal is to establish a uniform schema for adapter configs.

Lets's cut all the obscurities and call it "the adapter schema".

[uekerman]

For adapters and tools. And I think we need the "configuration" to make things clearer.
"preCICE" is required to make the schema understandable outside the preCICE namespace. Imagine somebody searching in a schema database for "preCICE".
Current long name is: "preCICE Adapter and Tooling Configuration Schema".

[MakisH]

Can we consider "tools" also as "adapters"? The definition of an "adapter" is rather vague at the moment in our context.

I agree that in the long run, we will end up calling this "the adapter schema". We then need:

• title of the documentation page: could remain "preCICE adapter configuration schema", in short "adapter schema".
• filename: precice-adapter-config-schema.json? Long, yes, but also clear.

[uekerman]

Besides the title of the documentation, there is also a title of the schema, but those two should probably have the same name.

preeco-orga/adapter-config-schema/preatcs.json

Line 10 in 81708ec

"title": "preCICE Adapter and Tooling Configuration Schema (preATCS)",

precice-adapter-config-schema.json is short enough IMO.