Understanding, handling and debugging preCICE configuration files can be difficult and tedious. As so many problems, also this problem grows superlinear with the size of the input. Especially the configuration of the data-flow can be tricky to get right for beginners and sometimes even seasoned preCICE users.
This tool is supposed to tackle this issue.
It naively interprets the given configuration file and visualizes it as a graph. This has a few important benefits:
- Configuration mistakes can be difficult to spot in XML, but are often trivial to spot in a graph.
- Students and co-workers have less trouble understanding relations of components in a graph format.
- A graph is a good format to present the simulation scenario in presentations
Please first install the dependencies:
graphvizfor rendering the result.
We recommend installing the
config-visualizer straight from GitHub:
pip3 install --user https://github.com/precice/config-visualizer/archive/master.zip
In case you want to tinker with the software, you can clone the repository and install the package locally.
git clone https://github.com/precice/config-visualizer.git pip3 install --user -e config-visualizer
Note: You maybe need to add your user pip installations to your path to make the config visualizer findable, i.e.
The config visualizer can be used interactively:
Alternatively, you can generate a graph and transform it to a readable format, e.g., pdf.
precice-config-visualizer -o config.dot precice-config.xmlto generate the graph in the
dot -Tpdf -ofile config.pdf config.dotto layout the result and output a given format such as pdf. This program is part of graphviz.
These commands support piping, so you can also execute:
cat precice-config.xml | precice-config-visualizer | dot -Tpdf > config.pdf
Controlling the output
For big cases, the generated output can be visually too busy. This is why the tool allows you to control the verbosity of some elements. For some properties, the following options are available:
- full shows the available information in full detail. This is the default.
- merged shows available relations between components without full detail. Multiple edges between components will be merged into a single one.
- hide hides all relations.
These options are currently available for:
- data access participants using
write-datato access data on meshes.
- data exchange participants
exchangeing data between meshes.
- communicators configured
m2nconnections between participants.
- coupling schemes configured
cplschemes between participants.
These examples are based on the elastictube1d example.
The full picture
precice-config-visualizer precice-config.xml | dot -Tpdf > graph.pdf
Reduced information of coupling schemes and communicators
precice-config-visualizer --communicators=merged --cplschemes=merged precice-config.xml | dot -Tpdf > graph.pdf
Data flow visualization
precice-config-visualizer --communicators=hide --cplschemes=hide precice-config.xml | dot -Tpdf > graph.pdf