Home

Awesome

morgen logo 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

Dependencies

License

morgen is licensed under the BSD-2-Clause license, with copyright (c) 2020--2022: Christian Himpe, Sara Grundel; see 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:

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:

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

All admissible additional (string) arguments are described below:

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

If reduced order models are computed and tested:

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

Available Networks

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

Test Networks
Synthetic Networks
Pipelines
Realistic Networks

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:

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:

</details>

Scenario

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

A scenario data set describes the boundary values and external inhomogeneities of the gas net. Transient behaviour of supply and demand functions is represented as step functions in compressed form by only marking changes. Each network has a training scenario (training.ini), which has constant boundary values for reduced order model assembly.

File Format

A scenario is encoded in an INI file, with the extension .ini. Each line holds a key-value pair, for the following keys:

Parsed Scenario Structure

A parsed network .ini file is given as:

</details>

Model

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

A model encodes a spatially discrete input-output system of the form:

E(p) x'(t) = A x(t) + B u(t) + F c_p + f(x(t),u(t),p)

      y(t) = C x(t)

which consists of an implicit nonlinear ordinary differential equation, and an (uni-directionally coupled algebraic) output equation.

Interface

discrete = model(network,config)

Arguments

Returns

Available Models

Notes

</details>

Solver

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

A solver is a time stepper that simulates a trajectory of a model and a scenario. The prerequisite steady-state initial value is computed from the scenario's boundary values.

Interface

solution = solver(discrete,scenario,config)

Arguments

Returns

Available Solvers

Model Export

The linear_export "solver" is not an actual solver, but exports a linearization with fixed parametrization:

E x'(t) = A x(t) + B u(t) + F,

   y(t) = C x(t),

of the selected network-scenario as a (E,A,B,C,F) state-space model, with the load vector F jointly describing the compressors, steady-state, and steady-state effects:

F := F * c_p + A * xs + B * us.

These sparse system matrices are stored in a .mat file and named network_id--scenario_id--IySxOy.mat, where y is the number of boundary ports (inputs and outputs), and x is the discretized state-space dimension.

</details>

Reductors

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

A reductor computes a reduced order discrete model, aiming to approximate the input-output (boundary-quantity-of-interest) behavior.

Interface

[proj,name] = reductor(solver,discrete,scenario,config)

Arguments

Returns

Available Reductors

These structured reductors approximate pressure and mass-flux components separately ("Structured" is abbreviated as "Struct."):

All reductors utilizing observability information are available in two variants. By default the nonlinear variant (no suffix) is used. The _l suffix signifies a "linear" variant of the reductor, which assumes a dual system is available. While either method can be applied to both, ode_mid and ode_end, models, theory suggest to use the linear variant only with the port-Hamiltonian ode_end.

</details>

Tests

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

A test defines an experiment, which is implemented as a script whose filename consists of a prefix and the tested network's name. Two types of experiments are currently implemented:

Note that tests can only be called from the morgen base directory, after running the SETUP script, or manually adding the tests folder to the path:

addpath('tests');

Available Tests

The available experiments are listed by running the SETUP script, which lists the contents of the tests folder.

Reduced Order Models

Reduced order models are saved in the z_roms folder (or the folder specified by the morgen_roms configuration entry).

A reduced order model is saved by storing the projectors and encoding the associated: network, model, and reductor in the filename as follows:

network--model--reductor--pid.rom

with pid being custom identifier configurable via optional arguments.

To load a reduced order model provide a filename of a saved reduced order model instead of the reductor identifier.

Results

Plots and MORscores computed by morgen.m are stored in the z_plots folder (or the folder specified by the morgen_plots configuration entry).

MORscore

The MORscore is a benchmark index measuring the area above the model reduction error graph, which is also plotted. This score jointly assesses the model reduction goals of minimum size and maximum accuracy. Unstable reduced order models are counted as evaluated with relative error of 1.0.

</details>

Configuration

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

The morgen platform assumes a configuration INI-file in the base folder named morgen.ini, if not found hard-coded default values are used.

Internal Configuration Structure

Internally, the configuration is stored in a structure of structures as follows:

Temperature Units

All input temperatures, i.e., in:

and all output temperatures are in Celsius. Internally, all temperatures are in Kelvin.

</details>

Tools

<details><summary markdown="span">(click to expand)</summary> 
xsltproc -o GasLib-X.csv xml2net.xsl GasLib-X.xml

csv2net('X_Y_PipeSegments.csv','myX_Y')

json2net('X.json','myX')

vf2kgs(value,vol_unit,time_unit,density)

b = psi2bar(p)

randscen(network,scenario_name)

cmp_friction(Re,D,k)

cmp_compressibility(p,T,pc,Tc)
</details>

Notes

Based on numerous numerical experiments we currently recommend the following model-solver-reductor ensemble(s):

Log

References

For references see also: GasMOR

Roadmap

2.0

Development Guidelines

Authors

Origin

The morgen gas network simulation, testing and benchmarking platform was developed as part of the MathEnergy project.