_                                      _        
       | |                                    | |       
 _ __  | |__    __ _   __ _  ___  _ __    ___ | |_  ___ 
| '_ \ | '_ \  / _` | / _` |/ __|| '_ \  / _ \| __|/ __|
| |_) || | | || (_| || (_| |\__ \| | | ||  __/| |_ \__ \
| .__/ |_| |_| \__, | \__,_||___/|_| |_| \___| \__||___/
| |             __/ |                                   
|_|            |___/                                    

phgasnets-cpp

Code supplement for "Modelling Gas Networks with Compressors: A Port-Hamiltonian Approach"

A speedy C++ implementation of port-Hamiltonian model for Gas Network with Compressors.

Details:

• Isothermal Euler equation model for pipes.
• Emphasis on including four different compressor models.
• Space discretization with second-order central finite differences.
• Time discretization with implicit midpoint method.
• Jacobian computation through automatic differentiation.
• Nonlinear solve using Levenberg–Marquardt algorithm.

Authors:

• Ashwin S. Nayak
• Thomas Bendokat

Affiliation:

• Max Planck Institute for Dynamics of Complex Technical Systems, Magdeburg, Germany.

Repository:

• https://gitlab.mpi-magdeburg.mpg.de/anayak/phgasnets-cpp

License:

• GNU GPL v3, see LICENSE.md.

Table of Contents

• Getting Started
• Run using docker container
• Compile and build
  • Dependencies (if not using the container)
  • Compile
  • Run demos
• Development container (for developers)

Getting Started

The library is structured into the following directories:

Directory	Information
src	phgasnets library source code; implementation of port-Hamiltonian formulation
include/phgasnets	phgasnets library headers; the public interface of the library
demos	the testcase demos which uses the phgasnets library

To use the code, you must first set the environment and dependent libraries. Instructions provided here are provided for standard UNIX distributions, but maybe easily adopted(but not tested) in other operating systems.

You may either choose to use,

• Build and run in containers: Recommended to primarily reproduce results
• Manually configure and build source code: Recommended for fine-grained customizations and develop source.

Once the library is built, you can run the demos provided in the demos/ folder.

For developers, a development container is also available to ease the workflow.

The following demos are provided within demos/:

• single_pipe runs a transient simulation of the Yamal-Europe pipeline configuration (without a compressor).
• four_compressor_types runs the Yamal-Europe pipeline configuration with a compressor placed midway modeled in four configurations.

Run using docker container

The project offers a Dockerfile to automate the configuration and execution by, setting relevant dependencies, hosting the source code, building executables and running the demos.

Necessary tools:

• Docker Desktop specifically Docker Engine (tested with 26.1.3).

Build the phgasnets image which contains the environment, copies the source code and builds executables

docker build -f Dockerfile --tag phgasnets .

Create a folder named results to store results in the host,

mkdir results

Run the container by sharing the results folder within and user id information to manage the generated file permissions,

docker run --rm -u $(id -u):$(id -g) -v ${PWD}/results:/phgasnets/run phgasnets

This should run all the demos in a disposable container and store the generated PDFs in the results folder.

Ensure that the directory to store the results exists before running, since this needs to be mounted as shared volume within the host and container. This also preserves user permissions on the files that are created within the container.

Compile and Build

Dependencies (if not using the container)

Building requires installing the following dependencies:

• gcc (or any C++17-compliant compiler)
• CMake >=3.9 for building,
• Eigen3 >=3.4.0 for handling linear algebra,
• Ceres >=2.0.0 for solving non-linear system of equations,
• HDF5 library with HighFive >=2.8 interface for writing/reading states to HDF5 format,
• nlohmann_json >=3.10 for reading JSON configuration files.

All these dependencies except HighFive are available through standard UNIX package managers. Instructions to install HighFive can be obtained in their repository.

CMake offers version compatibility check for all these dependencies.

Note the locations of all the libraries in case any were not installed through standard package managers.

Additional requirements are required for plot scripts in the demo,

• Python3 >=3.4 interpreter,
• h5py package to parse HDF5 files,
• numpy package for handling arrays,
• matplotlib plotting package,
• (optional) Latin Modern Math font.

All these libraries are also available either through standard UNIX package managers (for a system-wide installation) or Python package manager, pip (for a local installation).

A requirements.txt file is also included to install python dependencies for convenience, and maybe installed using

pip install -r requirements.txt

Configure and Compile

Once the dependencies are available, the following sequence of commands builds the project executables.

Current working directory is assumed as the top-level project directory and the build files will be placed in build directory.

cmake -B build -S .

This configures the project by finding the dependencies and generating host-specific build instructions.

CMake looks for the dependencies in standard UNIX paths, but if any of the dependencies are at a custom location their paths may be indicated by e.g.,-DCMAKE_PREFIX_PATH="/path/to/ceres;/path/to/highfive".

Automatic differentiation is enabled by default for Jacobian construction. If you prefer to use finite-difference based numeric differentiation, configure with -DPHGASNETS_NUMERICDIFF=ON flag. Read more about how automatic derivatives are computed here.

To compile in debug mode, you need to disable excessive compiler optimizations so as to utilize debuggers like gdb. Configure using -DCMAKE_BUILD_TYPE="Debug" flag.

To compile and create executables,

cmake --build build

Run Demos

The demo executables are available in the build directory and take configuration parameters config.json as input.

A convenience script RUNME.sh is provided to run all the demos and plot results,

./RUNME.sh

For detailed description on each demo, refer to the READMEs within.

Development Container (for developers)

If you intend to develop the source code without modifying/installing any dependencies on your host computer, you can make use of development containers for setting up the requisite environment.

A specification file .devcontainer.json is provided for building the devcontainer and can be utilized by supporting editors.

Necessary tools :

• Docker Engine (tested with 26.1.3),
• Visual Studio Code with Dev Containers extension (support since 2019. Tested with version 1.87.2).

Start VS Code, run the "Dev Containers: Open Folder in Container..." command from the Command Palette (F1), and select the project folder. While done for the first time, this should start building the container and can take a while (~5-10 min) and subsequently open the project within the container. The build is cached for subsequent runs and should be fairly quick thereon.

Proceed to compiling phgasnets in the terminal and once the library is built, you can run the demos.