precice-config-graph 3.0.0

A Library that builds a graph from a preCICE configuration file for validation and visualization purposes

preCICE Config Graph

A Python library that builds a graph from a preCICE configuration file for validation and visualization purposes and enables to recreate a precice-config.xml from it.

How does this differ from the preCICE Config-Visualizer? The graph built by this library is not (directly) meant to be displayed. The focus is on building a graph that represents the structure of a preCICE configuration in a way that is useful in checking for logical errors. This logic can also be used to generate a precice-config.xml from a given set of nodes.

[!NOTE] This library assumes the config file to adhere to preCICE conguration-file syntax. For example, references by name are assumed to exist. If the config file passes the preCICE-built-in checks (precice-tools check before preCICE version 3.3.0; precice-config-validate after preCICE version 3.3.0) without errors, then it is also read correctly by this library. If precice-config-validate does not succeed, the behavior of this library is undefined (it will probably crash).

Requirements

• Python 3.10+
• Pip
• Git for cloning the repository
• PyQt6

Installation

1. Clone this repository:

git clone https://github.com/precice/config-graph
cd config-graph

2. Create a new Python Virtual Environment (optional, but recommended):

python -m venv venv
source venv/bin/activate  # On Windows, use `venv\Scripts\activate`

3. Install required dependencies:

pip install .

Project Structure

config-graph
├── .github, .idea, etc…
│
├── docs                       # Useful information for understanding how this library works
│   └── …
│
├── debugging                  # Utility for debugging graph generation. See section in this README on the topic.
│   └── cli.py                 # Call this script to visualize a provided config
│
├── precice_config_graph       # Main library files
│   ├── edges.py               # Definition of edge types
│   ├── graph.py               # Main logic for building the graph from parsed XML
│   ├── nodes.py               # Definition of node types
│   ├── enums.py               # Definition enums used for node-creation
│   └── xml_processing.py      # preCICE-specific utilities for reading XML files correctly
│
├── test                       # All files for automated testing
│   └── example-configs        # Contains sample configurations that are then tested one by one
│       └── <case-name>
│           ├── precice-config.xml
│           └── test.py        # File that tests the graph that is produced from precice-config.xml for validity
│
├── .gitignore, LICENSE, README.md
│
├── pyproject.toml             # Project configuration (dependencies etc.)
└── shell.nix                  # Dependencies for anyone using NixOS / the nix-package manager. Should be replaced by a flake in the future.

Using in your project

This library is published to PyPi as precice-config-graph. It can be installed via

pip install precice-config-graph

Otherwise, it can also be imported into your pyproject.toml like so:

# …
dependencies = [
    "precice_config_graph @ git+https://github.com/precice/config-graph.git",
    # …
]
# …

Then, run pip install . in your project. To build a graph, use the following code snippet:

from precice_config_graph import graph, xml_processing

path = "./some/path/to/your/precice-config.xml"
root = xml_processing.parse_file(path)
G = graph.get_graph(root)
# use, traverse inspect the graph

# to view the graph
graph.print_graph(G)

Debugging graph generation

This module includes a small utility that helps with debugging the output graph. You can pass a custom precice-config.xml and it displays the graph it built in a pop-up window.

To get started, run

python debugging/cli.py "./path-to-your/precice-config.xml"

Graph structure

The types of nodes and edges are documented under docs/Nodes-and-Edges.md.