https://github.com/precice/config-graph
A python library that builds a graph from a preCICE configuration file for validation and visualization purposes.
https://github.com/precice/config-graph
Last synced: 5 months ago
JSON representation
A python library that builds a graph from a preCICE configuration file for validation and visualization purposes.
- Host: GitHub
- URL: https://github.com/precice/config-graph
- Owner: precice
- License: mit
- Created: 2025-06-20T09:29:38.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2025-07-01T12:02:43.000Z (12 months ago)
- Last Synced: 2025-07-01T12:28:56.973Z (12 months ago)
- Language: Python
- Homepage:
- Size: 319 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](https://github.com/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:
```bash
git clone https://github.com/precice/config-graph
cd config-graph
```
2. Create a new Python Virtual Environment (optional, but recommended):
```bash
python -m venv venv
source venv/bin/activate # On Windows, use `venv\Scripts\activate`
```
3. Install required dependencies:
```bash
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
│ └──
│ ├── 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
```bash
pip install precice-config-graph
```
Otherwise, it can also be imported into your `pyproject.toml` like so:
```toml
# …
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:
```python
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
```bash
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`.