OGSTools 0.4.0 Release Notes

Overview

Supports Python: 3.10, 3.11, 3.12.

First release after integration of ogs6py. The state of ogs6py corresponds to the functionality of v.403 of ogs6py (only light API changes, see Features/Project file)

OGS

OpenGeoSys version: 6.5.3

Migration strategy from ogs6py to ogstools

The recommended strategy is:

• Back up your environment with pip freeze > yourfile.txt
• Upgrade ogs6py to 0.403 first and resolve issues (see breaking changes).
• Uninstall ogs6py and install ogstools
• Remove import ogs6py. Add import ogstools as ogs. The former OGS becomes Project and function parameters of OGS.__init__() are now with lower case names. See example in Features

API changes

plot

• renamed meshplotlib to plot
• renamed plot function to contourf
• renamed setup.p_min -> setup.vmin, setup.p_max -> setup.vmax
• added several setup options available as kwargs

variables

• renamed propertylib to variables (to align with OpenGeoSys vocabulary)
• presets are now directly accessible as variables
• renamed presets to properties
• renamed Property class to Variable

meshlib

• renamed aggregate function to time_aggregate
• renamed MeshSeries.read to MeshSeries.mesh

Features

ogs6py

• new version with significant parts of the codebase rewritten. Changes visible to the user:

example

before:

import ogstools as ogs

prj = ogs.Project(input_file="mechanics.prj", output_file="old_parameter_add.prj")
prj.add_block(
    blocktag="parameter",
    parent_xpath="./parameters",
    taglist=["name", "type", "value"],
    textlist=["density", "Constant", "1900"],
)
prj.write_input()

now:

import ogstools as ogs

prj = ogs.Project(input_file="mechanics.prj", output_file="new_parameter_add.prj")
prj.parameters.add_parameter(name="density", type="Constant", value="1900")
prj.write_input()

• support for combining replacement- and build-method commands
• breaking changes: some methods renamed closer to project file tags:

• add_process_variable() split-up into add_secondary_variable() and add_process_variable()
• geo.add_geom() -> geometry.add_geometry(), timeloop -> time_loop etc.

• support for more MPL properties
• several bugfixes and tiny new features

• integration into ogstools

plot

• Time slice plots can be created easily: filled contour plots of transient data along a sampling line (example)

• Variables now have default symbols (e.g. used for labels in plots)

Mesh and MeshSeries

• Mesh can be created from a shapefile

mesh = ogs.Mesh.read(test_shapefile)

• Mesh can be remeshed with triangle
• MeshSeries has a performant algorithm for integration point tessellation called MeshSeries.ip_tesselated() - example for analyzing integration point data
• MeshSeries allows multidimensional indexing on ndarrays https://numpy.org/doc/stable/user/basics.indexing.html

import ogstools as ogs

ms = ogs.MeshSeries("filepath/filename_pvd_or_xdmf")
ms.data("darcy_velocity")[-2:, 1:4, :]  # shape is(2, 3, 2)
result_mesh = ms[-1]
for mesh in ms:
    print(mesh)

• Added function argument to Meshseries.animate functions has more flexible parameter that allow
  1. transformation of the mesh and
  2. customization of the plot
• Meshseries has domain_aggregate function (e.g. min/max of a variable per time step)

Project files

• ogs6py added (this version corresponds to https://github.com/joergbuchwald/ogs6py/releases/tag/v.403)
• OGS class is renamed to Project
• Function parameters are with now lower case letters
• project_file is now output_file

Documentation, examples and more

• Documentation got new structure of examples (now all organized under ogstools/examples/)
• pip requirements.txt files (of tested environment) are added for stable test environment reproduction (To be used by developers. Do not use it in your projects!)

Bugfixes

• Several small fixes in plotting functions (visual)
• MeshSeries closes file handle to h5 file after reading is finished
• Dependency compatibility (e.g., remove restriction to matplotlib and relaxing requirements)