morgen - Model Order Reduction for Gas and Energy Networks (1.2)

morgen is an open-source MATLAB and OCTAVE test platform to compare models, solvers, and model reduction methods (reductors) for gas networks and other energy network systems that are based on the (isothermal) Euler equations.

Version

Current Version: morgen 1.2 (2022-10-07)

Compatibility

Mathworks MATLAB >= 2020b
GNU Octave >= 6.1

Dependencies

emgr == 5.99 (included, see reductors/private)

License

Disclaimer

morgen is research software.

Citation

Please cite the morgen platform via its companion paper:

C. Himpe, S. Grundel, P. Benner: Model Order Reduction for Gas and Energy Networks; Journal of Mathematics in Industry 11: 13, 2021. doi:10.1186/s13362-021-00109-4

You can link to morgen via: git.io/morgen

Getting Started

To setup simulation and reduction tests and demos:

> SETUP % adds the "tests" folder to the path and lists scripts

Tests can then be called directly as listed. To try morgen:

> DEMO  % runs a sample pipeline model reduction code

Reproducibility

To reproduce the experiments from the companion paper, Model Order Reduction for Gas and Energy Networks, run:

> RUNME_HimpeGB21

To reproduce the experiments from the first add-on paper, Next-Gen Gas Network Simulation, run:

> RUNME_HimpeGB22

To reproduce the experiments from the second add-on paper, System Order Reduction for Gas and Energy Networks, run:

> RUNME_HimpeG22

Extending morgen

morgen's modules can be easily extended in the following ways:

to add a new model, see and modify: models/template_model.m
to add a new solver, see and modify: solvers/template_solver.m
to add a new reductor, see and modify: reductors/template_reductor.m
to add a new network, see and modify: networks/template_network.net
to add a new scenario, see and modify: networks/template_network/training.ini
to add a new simulation test, see and modify: tests/sim_template.m
to add a new reduction test, see and modify: tests/mor_template.m

Usage

Main Function

<details><summary markdown="span">(click to expand)</summary>

The morgen platform is called via the morgen.m function:

R = morgen(network_id,scenario_id,model_id,solver_id,reductor_ids,varargin)

and has four mandatory arguments:

network_id (string) The network identifier
scenario_id (string) The scenario identifier
model_id (string) The model identifier
solver_id (string) The solver identifier

as well as an optional argument and an additional variable length argument list:

reductor_ids (cell) An array of reductor identifiers (can be empty, too)
varargin Variable argument list each containing a string (see below)

All admissible additional (string) arguments are described below:

dt=X - Override time step in configuration with X (in seconds)
tf=X - Override tunable efficiency factor in configuration with X (positive real)
ys=X - Force minimum y-scale for error plots with 10^X (default: -16)
ord=X - Override maximum reduced order in configuration with X (natural number)
pid=X - Add custom string identifier to plot files (default: '')
notest - Do not test the reduced order models
compact - Display plots all in one figure

The morgen.m function returns a structure R with members depending on the arguments. If only reduced order models are computed:

.reductors (cell) Array of strings with names of the reductors
.offline (cell) Array of offline times for the reductors

If reduced order models are computed and tested:

.name (string) Output name of the experiment (as used by saved plots and scores)
.reductors (cell) Array of strings with names of the reductors
.orders (vector) The tested reduced orders
.l0error , .l1error , .l2error , .l8error (cell) Arrays of per reduced order average errors
.l0score , .l1score , .l2score , .l8score (cell) Arrays of per reduced order average MORscores
.offline (cell) Array of offline times for the reductors
.online (cell) Array of average relative online times for the reductors
.breven (cell) Array of average relative offline/online break even numbers

If only a simulation is run, R is a matrix, and contains the discrete output trajectory with dimensions outputs-times-time-steps.

</details>

Network

<details><summary markdown="span">(click to expand)</summary>

A network is described by a (directed) graph, given through an edgelist, which also specifies its edge type, and their physical dimensions and properties.

Network Topology Rules

A network must have at least one supply node!
All boundary nodes (supply or demand) must connect by exactly one edge!
- Short pipes can be inserted to enforce this.
The edge from a supply node must be directed away from it!
- Hence, no two supply nodes can be directly connected.
The edge to a demand node must be directed toward it!
- Hence, no two demand nodes can be directly connected.

Available Networks

All available network datasets are listed with the network's number of

internal junction nodes (n0),
supply boundary nodes (nS), and
demand boundary nodes (nD).

Test Networks

diamond - Diamond Network (n0=8, nS=1, nD=1, nC=0)
fork1 - Forked Pipeline (n0=12, nS=1, nD=2, nC=0)
fork2 - Forked Pipeline (n0=12, nS=2, nD=1, nC=0)
comptest - Compressor Test (n0=1, nS=1, nD=1, nC=1)
paratest - Parallel Pipes Test (n0=2, nS=1, nD=1, nC=0)
PamDB16 - Triangle Network (n0=0, nS=1, nD=2, nC=0)

Synthetic Networks

MORGEN - Small Network (n0=27, nS=2, nD=4, nC=1)
AzeJ07 - Small Network (n0=5, nS=1, nD=2, nC=1)
GruHKetal13 - Small Network (n0=11, nS=1, nD=8, nC=0)
Kiu94 - Small Network (n0=8, nS=1, nD=14, nC=0)
GruJHetal14 - Medium Network (n0=45, nS=4, nD=2, nC=0)
GasLib11 - Medium Network (n0=6, nS=3, nD=3, nC=2)
GasLib24 - Medium Network (n0=14, nS=3, nD=5, nC=3)
GasLib40 - Medium Network (n0=40, nS=3, nD=29, nC=6)
GasLib135 - Medium Network (n0=135, nS=3, nD=45, nC=29)
PelLL17a - Medium Network (n0=41, nS=1, nD=15, nC=5)

Pipelines

pipeline - Pipeline (n0=0, nS=1, nD=1, nC=0)
Cha09 - Pipeline (n0=0, nS=1, nD=1, nC=0)
RodS18 - Tree (n0=6, nS=1, nD=4, nC=0)
Guy67 - Tree (n0=8, nS=1, nD=8, nC=0)
LotH67a - Pipeline (n0=0, nS=1, nD=1, nC=0)
LotH67b - Pipeline (n0=0, nS=1, nD=1, nC=0)
LotH67c - Tree (n0=6, nS=2, nD=2, nC=2)
LotH67d - Tree (n0=4, nS=2, nD=2, nC=1)

Realistic Networks

AzePA19 - Portugal (n0=0, nS=1, nD=1, nC=0)
BerS19 - Spain (n0=6, nS=1, nD=5, nC=0)
DeWS00 - Belgium (n0=20, nS=6, nD=9, nC=0)
EkhDLetal19 - Ireland (n0=26, nS=3, nD=10, nC=0)
GasLib134 - Greece (n0=134, nS=3, nD=45, nC=1)
GasLib582 - Germany (n0=582, nS=31, nD=129, nC=5)
GasLib4197 - Germany (n0=4197, nS=11, nD=1009, nC=12)
SciGrid_NO - Norway (n0=44, nS=11, nD=9, nC=0)
JinW - China (n0=45, nS=5, nD=3, nC=38)

Data Origin

The GasLib network data-sets are derived from:

M. Schmidt, D. Aßmann, R. Burlacu, J. Humpola, I. Joormann, N. Kanelakis, T. Koch, D. Oucherif, M.E. Pfetsch, L. Schewe, R. Schwarz, M. Sirvent: GasLib - A Library of Gas Network Instances; Data 2(4): 40, 2017.

and licensed under CC-BY 3.0, see: https://gaslib.zib.de

The SciGrid network data-sets are derived from:

J. Dasenbrock, J. Diettrich, A. Pluta, W. Medjroubi: SciGRID_gas NO_Raw; Zenodo: 10.5281/zenodo.3985268, 2020.

and licensed under CC-BY 4.0, see: https://www.gas.scigrid.de

File Format

A network is encoded in a CSV file with the file extension .net. The first line is a comment header with a description of the columns, their meaning, and units.

# type, identifier-in, identifier-out, pipe-length [m], pipe diameter [m], height difference [m], pipe roughness [m]

Each line below the first holds one edge definition with the columns:

Edge type (P:pipe, S:shortpipe, C:compressor, V:valve)
Start node identifier (positive integer)
End node identifier (positive integer)
Pipe length [m] (positive real)
Pipe diameter [m] (positive real)
Pipe height difference [m] (positive real)
Pipe roughness [m] (positive real)

Thus, the gas network's directed graph is represented as an edge list, whereas the edge directions are not corresponding to flow directions except for boundary nodes. Note, currently only positive integers can be used as start and end identifiers.

Parsed Network Structure

A parsed network .net file is given as a network structure with members:

network (struct)
- .length (vector) Pipe lengths
- .incline (vector) Pipe inclines
- .diameter (vector) Pipe diameters
- .roughness (vector) Pipe roughnesses
- .nomLen (vector) Per pipe length
- .A0 (matrix) Incidence matrix re

Morgen

Install / Use

README