Homepage Books Releases Docs Discourse

Ogs5py - a Python API for OGS5

Hey there,

I wrote a Python-API for OGS5 as presented at the user-meeting on 2019-01-11.
You can find it on Github as part of the GeoStat-Framework:

I also wrote a script-generation routine, to convert existing models to an ogs5py-script.
I created a repository where I converted most of the Benchmark-scripts (about 300). You can find it here:

A presentation and short introduction to ogs5py can be found here:
Presentation User-Meeting (Jan 2019)

Feel free to contribute and I would be happy about any suggestions!



Hey Sebastian,
that’s a nice API and I love the script generator! At the moment there are 165 benchmark tests running after each pull request and not 300 I think. It needs a cleaning up off the list on github to distinguish between recently running and older benchmarks (archiv).

@bilke : is that correct`? 165 running benchmarks

1 Like

Hey Thomas,

I think the generator is a powerful tool to convince people to use ogs5py. Another nice side effect is, that the benchmarks now appear in a unique format and a key-word check was performed (I found some bugs in the benchmarks because of that).

But I’ve still got some questions:

  1. I ran into the problem, that there are some subkeywords, that can appear multiple times. In the current status of ogs5py this in not easily doable and I have to come up with a handy solution for that situation. Can you give me a list of sub-keywords this applies to?
  2. Is there a common format for the ASC files I could come up with?
  3. A list of the running benchmarks would be nice as you just said.
  4. You mentioned some keywords, where some data is written directly after the keyword. This is not covered by ogs5py yet. Could you provide a list of keys with this property? I just took care of the DDC files, where the number of the subdomain is written (redundantly) after the #DOMAIN keyword.


Hi Guys,

thanks Sebastian for sharing this project! I had a quick look at your presentation from last week and this looks really cool and useful! I think this would be a really powerful addition and we should think about integration this into the code mainline. Although we thought the current version 5.8 would be the last I already see this in an upcoming version 5.9 …

For the current list of tested benchmarks check this Jenkins page: https://jenkins.opengeosys.org/job/ufz/job/ogs5/job/master/lastBuild/testReport/(root)/projectroot/

At the moment we have 189 active benchmarks (165 of them in the standard configuration OGS_CONFIG=FEM).

Thanks bilke for the Link! I created a list of active benchmarks:

And again I found some bugs in the benchmark files. See:


Could you give an example please?

The ASC files relate to ESRI arcgis: http://desktop.arcgis.com/de/arcmap/10.3/manage-data/raster-and-images/esri-ascii-raster-format.htm

That’s just a handful keywords which are not that common. I will check it out.

  • lag2d repeated NEIGHBOR (cct)
  • decal repeated NEIGHBOR (cct)
  • 2D1P_transport repeated POROSITY (mmp)
  • Nuklidtransport repeated MASS_DISPERSION (mmp)
  • cement2d repeated KINETIC_GEM (gem)
  • model_1 repeated DAT_TYPE (out)
  • Leakage repeated TIM_TYPE (out)
  • CO2-FLOW repeated DAT_TYPE (out)
  • 2pf_2pt repeated SIMULATOR (pcs)

These are the ones I found.

I just released the first official Version: ogs5py v0.6

You can install it now via pip:

pip install ogs5py

I also created a first documentation:

There you can find a Quickstart and a simple tutorial. In addition all FileClasses are documented and linked against the Keyword documentation.

It was published on Zenodo:

I would love to hear what you think about this release!

After having a look on it, I would say:

SPECIALCASE: repeated NEIGHBOR (cct) refers to $NNEIGHBORS
SPECIALCASE: decal repeated NEIGHBOR (cct) refers to $NNEIGHBORS
NOT-REPEATED: 2D1P_transport repeated POROSITY (mmp)
INPUT_ERROR: Nuklidtransport repeated MASS_DISPERSION (mmp)
3rdParty_NOT_OGS: cement2dcement2d repeated KINETIC_GEM (gem)
INPUT_ERROR: model_1 repeated DAT_TYPE (out)
INPUT_ERROR: Leakage repeated TIM_TYPE (out)
NOT-REPEATED: 2pf_2pt repeated SIMULATOR (pcs)

I found a bug in my reading routine. Therefore a lot of false-positive results showed up. I took the first key that matched the beginning of the given key… therefore POROSITY_DISTRIBUTION was read as POROSITY and showed up two times afterwards.
I fixed that. will be in Version 0.6.1

I have to think about the $NNEIGHBORS keyword… this one needs special treatment.

ogs5py v0.6.4 released. Have a look at the changelog.
You can update resp. install it via:

pip install -U ogs5py



  • New routine to zip data by IDs: 9accf6e
  • reading routines in the OGS Class: 592bc50
  • New del_block routine in Blockfiles: 8d15a90

ogs5py v0.6.5 released. Have a look at the changelog.
You can update resp. install it via:

pip install -U ogs5py


  • gli.add_polyline: Adding polyline by given point IDs was not possible: 3ec23af


  • New swap_axis routine in msh and gli: You can now easily swap axis of a mesh. If you have generated a 2D mesh in x-y you can get a x-z cross-section by swapping the y and z axis: 3ec23af

First stable release: ogs5py 1.0

ogs5py v1.0.0 is finally released. There will be a publication about ogs5py in the near future.
You can update resp. install it via:

pip install -U ogs5py

ogs5py benchmarks

Almost all OGS5 Benchmarks were converted to an ogs5py script with the provided script generator. These benchmarks can be seen as a smorgasbord to provide a starting point for your own ogs5py model.

Release Notes


  • GLI.add_polyline now allows integer coordinates for points: bf5d684
  • MSH.centroids are now calculated as center of mass instead of center of element nodes: b0708a6
  • MSH.show was not working: 6a0489b
  • OGS.run_model has now a better check for OGS success: 143d0ab
  • GMSH interface was updated to new meshio-API: d3e0594
  • RFR file was not written: 41e55f3
  • BC new sub-key TIME_INTERVAL was missing: 94ec5c5


  • download_ogs downloads a system dependent OGS5 executable: ede32e4
  • add_exe add a self compiled OGS5 executable: ede32e4
  • MSH.import_mesh now allows the import of material_id and element_id if given as cell_data in the external mesh: 00a77fa
  • MSH.export_mesh now automatically exports material_id (already the case before) and element_id.
    Also you can now export additional point_data and field_data : 00a77fa
  • New method MSH.set_material_id to set the material IDs for specific elements: 4b11c6a
  • MSH.show now can show additional cell_data: ffd7604
  • New routine show_vtk to show vtk output with mayavi: f640c19
  • New method OGS.output_files to get a list of output files: 2f5f102
  • New attribute file_name for files: 632c2e7
  • BlockFile: new method append_to_block : efc9aac
  • OGS.gen_script now allowes multiple subkeys: 2cd344b


  • MSH.export_mesh argument add_data_by_id renamed to cell_data_by_id : 00a77fa
  • OGS.run_model argument ogs_root renamed to ogs_exe : 6fcdb61
  • Files that can occure multiple times (mpd, rfr, …) are better handled now: 4a9c9d2
  • ogs5py is now licensed under the MIT license: ae96c0e
  • Extra named files now get their name by keyword name : 632c2e7

New release: ogs5py v1.1

Release Notes


You can install ogs5py with pip:

pip install ogs5py


The documentation can be found at: https://ogs5py.readthedocs.io/

What’s new?


  • meshio 4 was not compatible
  • fixed integer type in exporting meshes with element/material IDs
  • better check for OGS5 success on Windows


  • drop py2.7 support

ogs5py got its own publication now:

Cite it, if you use it :wink: