ogs6py and VTUinterface: streamlining OpenGeoSys workflows in Python

We introduce two new Python modules that facilitate the preand post-processing of finite element calculations. ogs6py is a Python interface for the open-source package OpenGeoSys (Bilke et al., 2019), a finite element code for simulation of multi-field processes in fractured porous media. Modeling workflows can be further streamlined in Jupyter Notebooks (Kluyver et al., 2016) using the newly developed VTUinterface. The use of the modules is demonstrated with common workflow operations, including parameter variations, setting boundary conditions, changing solver settings, verification of simulation results by comparison to analytical solutions, set-up and evaluation of ensemble runs, and convenient analysis of results by line plots, time series, or transient contour plots.


Summary
We introduce two new Python modules that facilitate the pre-and post-processing of finite element calculations. ogs6py is a Python interface for the open-source package OpenGeoSys (Bilke et al., 2019), a finite element code for simulation of multi-field processes in fractured porous media. Modeling workflows can be further streamlined in Jupyter Notebooks (Kluyver et al., 2016) using the newly developed VTUinterface. The use of the modules is demonstrated with common workflow operations, including parameter variations, setting boundary conditions, changing solver settings, verification of simulation results by comparison to analytical solutions, set-up and evaluation of ensemble runs, and convenient analysis of results by line plots, time series, or transient contour plots.

Statement of need
Python has become a widely used framework for scientific data analysis and modeling. The development is driven by ease of use and flexibility, the vast modular ecosystem including powerful plotting libraries, and the Jupyter Notebook technology. The attractiveness of Python is not limited to post-processing; pre-processing tasks can be simply conducted, using packages such as the Python wrapper for GMSH (Geuzaine & Remacle, 2009) or the tool meshio (Schlömer et al., 2021). While many existing open-source tools force the user to learn a new syntax for interacting with the software, Python bindings allow control in a general language and thus are more accessible for a wider community of users.
In this contribution, we address interaction with the open-source code OpenGeoSys (OGS) (Bilke et al., 2019) version 6, aiming to facilitate both pre-and post-processing workflows with Python. This aim was partly inspired by the desire to design, control and evaluate ensemble runs Chaudhry et al., 2021) but has now taken on a wider perspective for general usability. A similar Python interface "ogs5py" exists for OGS version 5 ; however, conceptual differences between the versions, for example, the use of XML input files, required an entirely new package to be built from scratch.
The standard output format of OpenGeoSys is VTK (W. Schroeder et al., 2006) unstructured grid files (VTU) as time slices stacked together by a PVD file. These can be analyzed using Paraview (Ahrens et al., 2005), a Python wrapper for VTK (W. J. Schroeder et al., 2000), or visualization tools like PyVista (Sullivan & Kaszynski, 2019) or Mayavi (Ramachandran & Varoquaux, 2011). However, a finite-element-modeller's bread and butter business often include extracting single-or multiple point time-series data. The direct use of the VTK library * corresponding author is quite cumbersome for such tasks, especially when interpolation is required. The mentioned Python packages focus on visualization aspects, and except for Paraview, to our knowledge, do not have file support for PVD files or time-series data (Aboufirass, 2020;Sullivan, 2019).

Features
ogs6py allows creating complete OGS configuration files from scratch, altering existing files, running simulations and parsing OGS log files. The following example demonstrates some basic functionalities. The complete example demonstrating a typical ogs6py/VTUinterface workflow on a coupled thermo-hydro-mechanical (THM) problem of a tunnel excavation followed by the emplacement of a heat-emitting canister can be found in a Jupyter notebook located in the project repository.
Technical Details ogs6py requires python 3.8 or above and uses lxml (Behnel et al., 2005) to process OGS6 input files and uses the subprocess module to run OGS. Furthermore, pandas (McKinney & others, 2010) is required for holding OGS log file data. VTUinterface requires python 3.8 or above and uses the python wrapper for VTK to access VTU files and lxml for PVD files. In addition to VTK's own interpolation functionalities, we use pandas and SciPy (Virtanen et al., 2020) for interpolation.

Applications
Both of the packages introduced are relatively new, being only 1 to 2 years old. However, the adoption process in the OpenGeoSys community is gearing up. For example, a YouTube video was published explaining their use; both tools are also used for teaching at the TU Bergakademie Freiberg and they were also extensively utilized in two recent peer-reviewed publications .