This checker in development for the coupling library preCICE.
Currently, through the preCICE native command precice-tools check, syntax and basic setup mistakes will get checked.
Our checker assumes that this command has been executed beforehand and returned without error. Cases that get handled beforehand do not get checked by this logical checker. Instead, we try to find logical mistakes in the configuration file, which adhere to the defined syntax of preCICE, but will lead to errors when actually running the simulation.
Here you will find an overview over all logical errors, which we categorize into 'rules'. Each rule defines what a “correct” configuration would have to look like. Most rules can be violated in multiple ways with differing severity.
We define three categories of severity:
error: Violations with this severity will always cause the simulation to crash.warning: Violations do not necessarily cause errors during the simulation, but should be checked manually to ensure a smooth execution.debug: These violations represent hints and most of the time do not cause a simulation to malfunction. They will not get checked by default, but only on a user's explicit request. Still, they represent common pitfalls and may help a user to find an error.
Rules with TODO before their names have not yet been implemented but will be soon.
Rules will be listed with a number (0) before them. In case a rule has multiple corresponding violations, each violation will be listed in a subheading and a brief explanation, as well as their severity.
If a preCICE config.xml is missing a coupling scheme (or a multi-coupling scheme), then no data gets exchanged between participants.
Since preCICE is a tool for running coupled simulations between multiple participants, not defining a coupling scheme is an error.
severity:error
A participant needs to be part of at least one coupling scheme.
Otherwise, the participant does not exchange data and is not part of a coupled simulation, which is an error.
severity:error
In order for the two solvers to exchange data between them, their participants have to be connected through an m2n node in the config.xml.
Otherwise, they are not partaking in the coupled simulation.
A participant needs to be part of at least one m2n data exchange to exchange data.
severity:error
A participant can be part of more than one m2n exchange, but an m2n-exchange between two participants is only allowed to be defined once.
severity:error
(4) TODO Read- and write-data are only valid on a participants own meshes or if explicitly requested
If a participant wants to read-/write-data from or to a mesh, then he needs to know the correct positions to do so.
He knows these coordinates if the mesh is his own (provide-mesh) or he explicitly states that he knows them from a
received mesh (with api-access="true").
If neither is satisfied, the participant has no permission to read from or write to the mesh.
severity:error
If a participant reads data from a mesh, then someone should write it beforehand. Similarly, if a participant writes data to a mesh, then someone should read from it later on.
severity:error
A coupling scheme needs to have at least one exchange element. Otherwise, it is redundant.
severity:error
Participants can be "connected" through coupling schemes.
When using serial couplings, the second participant waits for the first.
This means that when more than two participants get coupled in pairs of two, a circular dependency can
evolve, in which X waits for Y, Y waits for Z and Z for X, leading to a deadlock.
severity:error
Mappings are a central component of preCICE configs. They define how data is exchanged between two participants. It gets specified by a participant (here "Parent") and defines how data from Parent's mesh gets mapped to a different participants mesh (here "Stranger"), or vice versa.
A mapping has a mapping-method (specified in <mapping:method .../>),
a direction (read or write), an origin-mesh (specified by tag from="..."),
a destination mesh (specified by tag to="...") and a constraint (consistent, conservative,
scaled-consistent-surface or scaled-consistent-volume).
The combination of direction and constraint will be referred to as "format" here.
There are two main kinds of mappings: regular mappings and "just-in-time" (JIT) mappings. For JIT mappings, Parent can directly access Stranger's mesh, meaning there is no need to define a mesh of Parent to map the values from Stranger's mesh to.
A JIT mapping is only valid if Parent receives Stranger's mesh with the attribute api-access="true".
severity:error
For JIT mappings, only the mapping-methods nearest-neighbor, rbf-pum-direct and rbf are supported.
severity:error
For JIT mappings, the only supported formats are write-conservative and read-consistent.
A read-conservative mapping can be achieved by switching the direction to write and moving the mapping from Parent
to Stranger. Analogously, this also works to achieve a write-consistent mapping.
severity:error
If the direction is read, then the JIT mapping requires the tag from="...". If it instead has the tag
to="...",
then direction and tag don't fit and the mapping is in the wrong direction.
Similarly, a JIT write-mapping requires the tag to="...", otherwise its direction is wrong.
severity:error
This comprises both "JIT mapping has a wrong format" and "JIT mapping is in the wrong direction".
severity:error
Parent declares a read-mapping, but does not read from the corresponding mesh, i.e., Parent has no read-data element,
that reads from Stranger's mesh specified in the mapping.
Similarly, if Parent declares a write-mapping, a write-data element should exist, that writes data to Stranger's mesh
as specified in the mapping.
severity:error
For a "regular" (non-JIT) mapping, the direction read means, that Parent wants to read data from Stranger's mesh.
For this to work, data from Stranger's mesh has to be mapped to Parent's mesh.
This means, the from="..."-mesh has to be by provided Stranger and the to="..."-mesh has to be provided by Parent.
If the from-mesh is not by Stranger and the to-mesh not by Parent, then the direction is wrong.
Similarly, a write-mapping indicates that Parent wants to write data to Stranger's mesh.
For this to work, data from Parent's mesh has to be mapped to Stranger's mesh.
This means, the from="..."-mesh has to be provided by Parent and the to="..."-mesh has to be provided by Parent.
Otherwise, the direction of the mapping is wrong.
severity:error
Parent declares a read-mapping, but does not read from the corresponding mesh, i.e., Parent has no read-data element,
that reads from Parent's own mesh as specified in the mapping.
Similarly, if Parent declares a write-mapping, a write-data element should exist, writing to Parent's mesh as
specified in the mapping.
severity:error
A mapping between two participants only specifies how to map data between their meshes, but does not exchange it. In order for the data-exchange to work, both participants have to exchange data via an M2N exchange.
severity:error
In order for the exchange to function properly, both participants need to exchange data via a coupling scheme.
severity:error
Even if both participants share a common coupling scheme, it is not guaranteed, that they exchange data in it via an
<exchange data="..." from="..." to="..."/> tag.
severity:error
Even if both participants share a common coupling scheme with a data-exchange, it is not guaranteed that they
exchange data in correctly via an <exchange data="..." mesh="..." from="..." to="..." /> tag.
For any mapping, the participants specifying the to="..."- and from="..."-meshes in the mapping have to be the
to="..."- and from="..."-participants in the exchange.
The mesh used in the exchange should be Stranger's mesh,
otherwise, there exists no correct data-exchange between the participants.
severity:error
Both meshes mentioned in the mapping is provided by the same participant.
severity:error
A data element in a preCICE needs to be mentioned at many locations to finally allow it to be utilized by one or more participants. After declaration, data has to be:
- used in a mesh
- written by a participant
- read by a participant (or read through other means, e.g., of immediate export)
- exchanged in a coupling scheme if it gets written and read by different participants.
All other cases are checked here (minus the ones that get handled by precice-tools check).
Using, reading or writing data without the respective other tags is not as severe an error, as this data element is likely not used in the simulation yet, due to multiple tags missing.
For the exact implementation, see rules/data_use_read_write.py.
The data element is not exchanged between the participants which are accessing the data.
severity:error
The data element is used in a mesh, but no participant is reading or writing it.
severity:warning
The data element is used in a mesh and read by a participant (or other ways of acquiring the data), but no participant is writing the data.
severity:error
The data element is used in a mesh and written by a participant, but nobody is reading it (or acquiring the data through other means).
severity:warning
The data element gets declared but not used in a mesh, read or written by any participant.
severity:warning
A mesh is not used if no participant writes/reads data to/from it.
This does not necessarily cause the simulation to malfunction or misbehave.
severity:warning
A simulation between participants A and B and a second one between participants C and D can run simultaneously without using any of the coupling features of preCICE. This will, however, deteriorate the readability of the configuration and make it more prone to errors.
More precisely, simulations are considered disjoint, if there are no connections (data written to/read by, exchanges, coupling schemes, etc.) between groups of participants. In most cases, running multiple “disjoint simulations” simultaneously is intended.
severity:debug
There can be cases where there are multiple simulations that are mostly disjoint (in that they do not operate on common data in any way), but that reference the same data names. This is not considered an error, but it indicates that there might be an oversight here and will therefore be warned about.
severity:warning
Any mesh defined in the configuration must be provided by exactly one participant. Only then can the mesh be used in mappings, exchanges et cetera.
A mesh that gets mentioned in an arbitrary tag in the config does not get provided by any participant.
severity:error
A mesh that gets mentioned in an arbitrary tag in the config gets provided by multiple participants.
severity:error
If two participants define a coupling scheme between them, then they need a mapping or api-access to exchange data.
An exchange of the form from="A" to="B" mesh="A-Mesh" implies that A writes data to A-mesh,
exchanges it to B, who either has api-access and reads directly from it or defines a read-mapping to his own mesh.
Analogously, an exchange of the form from="A" to="B" mesh="B-Mesh" implies that A writes data to one of his meshes
(or directly to B-Meshwith api-access), maps it to B-Mesh, exchanges it to B, who then reads from it
The same applies to a multi-coupling scheme.
If A and B do not fulfill the criteria explained above, a violation will be returned.
severity:error
If A or B does have api-access to the correct mesh, it might still lead to an error in the simulation.
However, as this is a valid use-case, only in debug mode will a warning be displayed.
severity:debug
If participants receive a mesh, then they should use it.
If a participant receives a mesh without api-access, then they need to specify a mapping to use it. If they receive it with api-access, then they can write/read directly to/from it.
severity:warning
If a participant receives a mesh with api-access, then they do not have to specify a mapping to use it, as they can operate directly on it. However, if they still map to their own meshes, then this is not an error per se, but might not be wanted.
severity:debug