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

phgasnets

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.

Documentation:

Table of Contents

• Getting Started
• Run using docker container
• Run using spack
• Run using vcpkg
• Compile and build manually
  • 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
• Build and run natively (using spack or vcpkg): Recommended to reproduce results natively if containers are not an option.
• 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.

The compiled image from Dockerfile is already shared on docker hub. Pull the image which contains the environment, includes the source code and builds executables,

docker pull ashwinsnayak/phgasnets:1.1.0

Create a folder named results to store results in the host and run the container by sharing the results folder within and user id information to manage the generated file permissions,

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

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.

Run using spack

Spack is a package management tool which fetches, builds and installs multiple versions and configurations of the dependencies that phgasnets need in isolated environments.

A spack.yaml configuration file is included with the project containing the dependencies required.

Prerequisites:

• git for cloning repositories

1. Clone this repository and spack repository within.

git clone https://github.com/mpimd-csc/phgasnets.git
cd phgasnets

git clone --depth 1 https://github.com/spack/spack.git .spack

2. Create, activate spack environment from within the project directory,

.spack/bin/spack env create phgasnets
eval "$(./.spack/bin/spack env activate --sh -p .)"
.spack/bin/spack install

This command should technically parse spack.yaml and install the C++ and Python dependencies required.

3. Build phgasnets,

cmake -B build -S .
cmake --build build

Since you are in the spack environment, CMake should find all the right dependencies.

4. Run the demos

./RUNME.sh

Run using vcpkg

The project offers a vcpkg.json file to fetch and build all dependencies which minimizes efforts in their installation. Unfortunately, python dependencies need to be installed manually.

Prerequisites:

• gcc (or any C++17-compliant compiler)
• CMake >=3.9 for building
• git for cloning the repository
• Python3 >=3.9 interpreter for plots. See uv or pyenv for managing Python versions.

1. Clone this repository and vcpkg repository within

git clone https://github.com/mpimd-csc/phgasnets.git
cd phgasnets
git clone --depth 1 https://github.com/microsoft/vcpkg.git .vcpkg

2. Build phgasnets using vcpkg to handle dependencies,

cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=./.vcpkg/scripts/buildsystems/vcpkg.cmake
cmake --build build

3. Install Python dependencies for plotting scripts

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -r requirements.txt

4. Run the demos

./RUNME.sh

This should produce all the results in the results folder.

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.9 interpreter,
• numpy package for handling arrays,
• matplotlib plotting package,

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

python3 -m venv .venv
. .venv/bin/activate
python3 -m 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.