Motivation
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
Installation
Please first install the dependencies:
python3
andpip
graphviz
for 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.
export PATH=$PATH:$HOME/.local/bin
Usage
The config visualizer can be used interactively:
precice-config-visualizer-gui precice-config.xml
Alternatively, you can generate a graph and transform it to a readable format, e.g., pdf.
-
Use
precice-config-visualizer -o config.dot precice-config.xml
to generate the graph in the.dot
format. -
Use
dot -Tpdf -ofile config.pdf config.dot
to 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
read-data
andwrite-data
to access data on meshes. - data exchange participants
exchange
ing data between meshes. - communicators configured
m2n
connections between participants. - coupling schemes configured
cplscheme
s between participants.
Examples
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