0.4.0

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)

0.3.1

Overview

0.3.1 is a maintenance release (mainly bug fixes and refactorings)

Supports Python: 3.9, 3.10,3.11, 3.12.

This is the last release with support of Python 3.9!

OGS

Updated to 6.5.2.

Feflow converter

• Conversion of component transport models with multiple components now possible
• automatic creation of OGS-6 project file template,
• bulk and boundary meshes, and
• calculation of retardation factor from sorption coefficient.
• detailed description for the example on the website.

Mesh: Borehole Heat Exchanger

• Bug fixes in layer computation
• Allow BHE begin at z=0 (Bug fix)
• Support multiple BHE begin depths

Function to sample properties along a user-defined polyline.

• It accepts polylines instead of simple lines and list of properties defined using Property-type.

  Changes:

• introduces sample_over_polyline function to meshlib

• adds two related plots into meshplotlib

• in propertylib, Scalars get default color and linestyle properties that can be used in for plotting

[meshlib] timevalue of min or max over timeseries

• This feature enables the visualization of when a minimum or maximum of a property happens at any point in a mesh.
• It uses the existing MeshSeries.aggregate function which can now be called with two additional "func" arguments: "min_time" and "max_time".

Refactorings

• Moved examples data to one dedicated folder

Bugfixes

• Meshplotlib: The streamlines in a slice of a 3D mesh are now corrected. This was due to 1) some wrong logic and 2) some floating point error when creating a Rectilineargrid to sample the values on.

0.3.0

OGSTools 0.3.0 Release Notes

Library

feflowlib got:

• OGS compatible conversion of 2D meshes.
• Conversion of hydro-thermal FEFLOW models.
• Bug fix - removed bulk_node and element_ids after assignment.
• Extended feflowlib to be able to convert user data from FEFLOW files. User data in the FEFLOW data can store data that are not necessary for the FEFLOW simulation.

logparser got:

• Added to OGSTools with extended documentation.

meshlib got:

• Function to compute differences of meshes.
  • The difference function from meshlib will now return one-to-one, pair-wise, or matrix difference depending on what input the user provides.
• Introduction of functionality to probe points on MeshSeries.
• Function to aggregate all timesteps in a MeshSeries given an aggregation function.

meshplotlib got:

• Functionality and documentation for (mechanical) stress analyses.
• Both, Custom figure and axes objects, can now be passed to plot function.
• Examples are added for:
  • Custom figure axes.
  • XY labels with shared axes (Adding or not adding labels can be handled semi-automatically based on whether axes are shared).
  • Differences of meshes.
  • Limit plots.
• Progress bars: for animation and convergence study evolution evaluation.
• Label in format "property name / property unit" can be obtained from Property.
• Small fix to how setting aspect ratio is handled.
• Enable use of external fig and ax in plot functions and plotting different variables within one figure.
• Reworked aspect ratios (with examples).
• Interactive PyVista examples.

msh2vtu got:

• A cleaner Python interface without the need to run argparse in between.
• A modification for msh2vtu to allow to convert BHE meshes.

Infrastructure & Development

• Use latest release of OGS ogstools.opengeosys.org: 6.5.1.
• Code quality report added.
• Various changes for building OGSTools with GNU Guix.

breaking API-Changes

• from 0.2.0 to 0.3.0

msh2vtu

• rename parameter
• argument defaults are now the same for both CLI and python interface

msh2vtu(
    rdcd --> reindex (Default changed from True to False)
    ogs --> keep_ids (Reverse meaning, new default of False is the same as ogs=True before)

propertylib

• rename function

Property(__Call__  --> transform )

0.2.0

OGSTools 0.2.0 Release Notes

Library

studies a new package that provides utility functions to compose studies from multiple simulation
runs. For now it contains functions to perform convergence studies on simulation results (with increasing spatial/temporal discretization) for specific timesteps or over all timesteps.

msh2vtu got a cleaner python interface without the need to run argparse in between.

feflowlib has been updated with new functionalities.
In particular, material properties can now be taken into account when converting and creating OGS models.
In addition, feflowlib now uses ogs6py to create prj files.
With these changes the conversion of FEFLOW models for steady state diffusion and liquid flow processes can generate a complete prj-file for OGS simulations.

Tools

feflow2ogs-tool now enables simulation-ready prj-files for steady state diffusion and liquid flow processes.

Infrastructure & Development

Web documentation for releases is now available on ogstools.opengeosys.org.
Documentation for previous releases will be available in the future and can be selected with a version dropdown in the navigation bar.

0.1.0

OGSTools 0.1.0 Release Notes

The second release of the ogstools-package brings lots of new library functionality for e.g. plotting and mesh generation as well as a new tool for converting FEFLOW meshes! A full-featured prebuilt Docker image is provided.

Library

feflowlib is a new package for accessing FEFLOW easily in pyvista.

meshlib is a new package for efficient mesh generation from surfaces. It can be used to create meshes from {ref}PyVista surfaces <sphx_glr_auto_examples_howto_meshlib_plot_meshlib_pyvista_input.py> and from {ref}.vtu surface files <sphx_glr_auto_examples_howto_meshlib_plot_meshlib_vtu_input.py>.

---

meshplotlib is a new package to visualize {ref}2D <sphx_glr_auto_examples_howto_meshplotlib_plot_meshplotlib_2d.py> and {ref}3D <sphx_glr_auto_examples_howto_meshplotlib_plot_meshplotlib_3d.py> mesh data. It also can generate {ref}animations <sphx_glr_auto_examples_howto_meshplotlib_plot_animation.py>:

---

propertylib is a new package which provides a base class to handle {ref}common mesh properties systematically <sphx_glr_auto_examples_howto_propertylib_plot_propertylib.py> (e.g. temperature, pressure, displacement, ...).

---

nuclearwasteheat provides an easy way to {ref}calculate the heat generated by nuclear waste repositories <sphx_glr_auto_examples_howto_nuclearwasteheat_plot_nuclearwasteheat.py>.

Tools

The new feflow2ogs-tool converts data stored in FEFLOW binary format to VTK format. It can only be used with a FEFLOW installation.

Infrastructure & Development

Examples on the web page are generated via sphinx_gallery which also allows for downloading the example as an Jupyter Notebook file.

We also added some shortcuts via make for development related tasks such as setting up the development environment, running the tests or creating a live preview of the documentation.

Development can now be done via VSCode's Dev Containers.

0.0.3

OGSTools 0.0.3 Release Notes

This is the first release of the ogstools-package, a joint effort of OGS users and developers to strengthen the OGS ecosystem!

Tools

msh2vtu

The msh2vtu-tool by Dominik Kern (TU Bergakademie Freiberg) has been integrated into ogstools. For more info see . Its former repository at GitHub dominik-kern/msh2vtu has been deprecated and development continues under the ogstools umbrella.

Infrastructure

Documentation web site

This documentation website has been implemented and is available at https://ogs.ogs.xyz/tools/ogstools.

Unit testing and style checks

A tox-based test driver for unit tests and style checks has been implemented.