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
    );
  };
};