0.8.2

OGSTools 0.8.2 Release Notes

Python 3.12-3.14
OGS 6.5.8

3rd of September 2026

Breaking changes

API breaking changes

• ogs6py: BHE flow_and_temperature_control types were renamed/consolidated to match OGS 6.5.8.dev (e.g. FixedPowerConstantFlow and the various curve-based variants are replaced by InflowTemperature, Power, BuildingPower), and flow_rate must now be supplied for every type (as a string, e.g. referencing an OGS parameter by name). (!455)

Changes (non API-breaking)

Bugfixes

• fixed sorting in Meshes.from_files (if domain_key was not in the beginning, it didn't sort correctly) (!465)
• allow values for group based parameters in Project.parameters (allows to set vectorial or anisotropic group values. Previously, only allowed scalars) (!465)
• fixed Project.process_variables.add_bc and Project.process_variables.add_st to allow all different kinds of types. Previously, some
  checks caused unintentional errors. (!471)
• fixed MeshSeries.probe with linear interpolation and cell_data yielding nan at the mesh boundary as cell centers are used for interpolation. Now used nearest neighbor as a fallback. (!473)
• fixed reading .xdmf data where some data field are only present in the first timestep. Now they will also be read for later timesteps. (!473)
• fixed Model.plot_constraints unintentionally deleting meshes from the Model as a side effect; it now operates on a copy. (!463)
• fixed plot.contourf raising unexpected keyword argument 'mask'. (!467)
• fixed the data aspect ratio in plot.contourf when xlim/ylim are given. (!470)
• fixed the error message raised by StorageBase._pre_save to reference the correct overwrite argument. (!479)
• relaxed datatype validation for point coordinates and MaterialIDs so float32/int32/uint32 variants are also accepted, not just the exact reference dtype. (!475)
• ot.mesh.difference no longer drops the spatial_unit attribute of the resulting mesh. (!468)
• storage paths/filenames may now contain ~. (!461)

Features

• plot
  • added xlim and ylim as arguments for contourf (!465)
  • improved Meshes.plot (!465)
  • fixed line ordering by trying to sort by cell adjacency (!465)
  • contourf: corner elements were missing if none of their points were in the selected x- or y-limits; now they are checked explicitly. (!482)
• Meshes
  • Meshes.from_mesh supports quadratic mesh (!465)
  • Meshes now support output_names, saved/restored via Meshes.save()/from_file()/from_folder() and used by Meshes.plot and Model.plot_constraints for labeling (!484)
• mesh
  • filepath is now attached to the mesh upon reading (with ot.mesh.read) (!465)
  • added ogstools.mesh.utils.pv_set_attr helper, replacing direct use of the deprecated pyvista.set_new_attribute (!474)
  • node_reordering (and the NodeReordering CLI call it wraps) gained a log parameter to control/silence its log output (!488)
• Project
  • BuildTree.populate_tree now can handle dicts as the element text
    (in this case the key and value pairs will create corresponding subelements) (!472)
  • Added deactivate_subdomain to Project.process_variables (!472)
• Variable
  • data_name of a Variable is now also looked for in the attributes of a mesh (e.g. points) or MeshSeries (e.g. timevalues) (!487)
  • functions of nested Variables are now stored internally as a list (instead of nested lambdas), which allows retrospectively modifying arguments and parameters (!487)
  • arguments of these stored functions can be strings which represent the names of data inside a mesh or MeshSeries, to allow for Variables depending on different input data (!487)
  • output_name can now explicitly be an empty string (!487)

Infrastructure

• added a make link_check command, running lychee, to check for broken links in the docs (!465)
• CI no longer pins a specific Python version, just 3.x. (!480)
• gallery hash checks now exclude plots whose figures embed computational metrics (e.g. solver time), since those vary between runs; pre-commit no longer reformats paper.md, and codespell now also skips *.svg/*.html. (!321)

Documentation

• added CONTRIBUTING.md and linked it from README.md, the docs nav, and the docs site; split developer and maintainer guides; fixed install instructions per the JOSS review. (!480)
• fixed broken weblinks in documentation (!465)
• submitted the OGSTools paper to the Journal of Open Source Software (paper/paper.md, paper/paper.bib); added a graphical abstract linked from README.md. (!321)

New Examples

• new Meshes example (Selke) (!465)

Updated Examples

• reworked simple simulation example, added missing print()/plt.show() calls across gallery examples, and other example polish from the JOSS paper review. (!480)
• BHE example additionally shows how to access temperatures via the Components_BHE structure. (!480)
• quickstart examples now plot_convergence behaviour as a heatmap of the relative error per iteration/timestep (sim.log.plot_convergence(metric="dx_x")) instead of clock time per solver phase. (!321)

Tests

• added end-to-end example-Project test coverage and shared property-type-registry tests for materiallib. (!464)

Beta testing features

• materiallib YAML schema tightened: a property entry must now be a single mapping (lists of entries are no longer accepted), the type key is required, and unsupported keys are rejected. Property parameters are validated against a shared type registry. (!464)
• materiallib YAML schema: materials must now group their properties under top-level domains (medium/phase/component) instead of a flat properties block. Bundled example materials were migrated accordingly. (!451)

JOSS paper

• OGSTools paper draft submitted to the Journal of Open Source Software (paper/paper.md, paper/paper.bib) (!321)

0.8.1

OGSTools 0.8.1 Release Notes

1/June/2026

Python 3.12-3.14
OGS 6.5.8

Changes (non API-breaking)

Bugfixes

• MeshSeries: could not be read if xdmf-file was a symbolic link
• added missing tools to cli interface (mergeMeshToBulkMesh, CreateAnchors)
• identifysubdomains will ignore anchor meshes to not wrongly overwrite the special id mapping
• fixed sorting of ot.plot.line in some edge cases
• A Matrix Variable transformed to the polar coordinate system
  (ot.variables.Matrix.to_polar()) is now also able to use .transform on a MeshSeries
• .xdmf MeshSeries which only contain points (and no cells) can now be properly
  read
• Project: Curves (bin) and chemical solver database (dat) are now copied and saved with Project
• Materiallib: fix bug with selecting multiple materials in a copy
• ip_mesh: fix for meshes with mixed cell types
• plot.contourf: fix when used in notebooks
• MeshSeries.from_data: fix save and scale behavior
• OGS-Restart: minor fixes

Features

• added the Class ogstools.mesh.IPdata to interface with the integration point
  metadata
• variable components can now be plotted via strings e.g. "displacement_x" will
  plot the same thing as ot.variables.displacement["x"]
• added standalone type hinted methods, to set parameters to a project per
  parameter type e.g. prj.parameters.set_constant_parameter / prj.parameters[name] = int_or_float or
  prj.parameters.set_function_parameter / prj.parameters[name] = str
• added prj.parameters.set_group_parameter
• ogsmonitor is now a standalone CLI tool (previously only usable from Jupyter
  notebooks). New CLI features include automatic port selection, pipe support, better
  error codes, and the logfile path is now a positional argument.
• temporary files are now all consistently written und /tmp/ogstools_<username>/<functionname>/

0.8.0

OGSTools 0.8.0 Release Notes

Python 3.11-3.14
OGS 6.5.7

Breaking changes

API breaking changes

New Core Framework and Storage System

• New unified framework: Introduced Model, Simulation, and Result classes
  that provide a complete workflow from setup to analysis. See the new
  plot_framework_short.py example for a quick overview.
• Storage system: All major classes (Model, Meshes, MeshSeries, Project)
  now inherit from SaveBase and support:
  • Unified save() / from_folder() / from_id() interface
  • Automatic backup on overwrite (configurable via SaveBase.Backup)
  • Archive mode for creating self-contained copies
  • ID-based organization in user-defined storage paths
• Simulation controllers:
  • Removed deprecated ogstools.simulation module
  • New SimulationController base class with OGSInteractiveController and
    OGSNativeController implementations
• Log parsing: Added Log class for parsing and analyzing OGS log files with
  methods for convergence analysis and simulation status tracking

MeshSeries and Meshes

• removed the Mesh class entirely, MeshSeries is now a Sequence of native
  pyvista.UnstructuredGrid's.
• MeshSeries.scale changes the calling object and returns it.
• MeshSeries.read_interp -> MeshSeries.mesh_interp
• MeshSeries.probe -> MeshSeries.probe_vals
• MeshSeries.extract_probe -> MeshSeries.probe
• MeshSeries.aggregate_over_domain -> MeshSeries.aggregate_spatial
• MeshSeries.aggregate_over_time -> MeshSeries.aggregate_temporal
• MeshSeries.plot_domain_aggregate -> ms.plot_line(variable.max/mean/...)
• removed deprecated MeshSeries.plot_probe -> probe = MeshSeries.probe(...); probe.plot_line(...)
• MeshSeries.save() signature changed: now uses unified storage interface with
  target, overwrite, dry_run, and archive parameters
• Meshes now supports storage operations: save(), from_folder(), from_id()
• Meshes.__init__() now accepts optional id parameter
• Meshes implements __eq__() and __deepcopy__() for proper comparison and copying

Project

• Project.__init__() signature changed:
  • output_file is now optional (defaults to auto-generated path if using IDs)
  • Added id parameter for storage system integration
• Project now inherits from SaveBase and supports save(), from_folder(),
  from_id() operations
• Project.inputfile renamed to Project.input_file
• Project implements __eq__(), __deepcopy__(), __repr__(), and __str__()
• Removed Project.restart; use Simulation.restart instead.

Logfile Parser

• Add monitor for live logfile parsing in a Jupyter notebook
• step_start_time column added to time_step_vs_iterations() analysis

Execution

• Support for parallel execution with MPI

Logparser

• OGS V1 log format no longer supported; only V2 is parsed

Other API Changes

• Matrix.mean -> Matrix.tensor_mean
• meshlib has been renamed to mesh - classes to generate a new mesh (e.g.
  Layer, LayerSet, Surface, ...) have been moved to a submodule create.
• ot.mesh.create.LayerSet.to_region_tetraeder -> ot.mesh.create.LayerSet.to_region_tetrahedron
• ot.mesh.create.dataframe_from_csv doesn't require a parameters .csv anymore,
  but either a mapping of layer_id to surface files, or the directory containing
  all surfaces files (in that case the layer_ids map to the sorted file list)
• ot.mesh.geo.depth now requires top_mesh as an argument.
• ot.mesh.geo.p_fluid was removed. See the Stress analysis example for how
  to calculate fluid pressure now.
• ot.mesh.file_io.save() signature changed: mesh parameter now comes first

Deprecations

Removed Modules

• Removed ogstools.simulation module (replaced by ogstools.core framework)

Examples

Changes (non API-breaking)

Bugfixes

• plot.line seems to have been missing the very first point of a linesample, now fixed
• cli dashed arguments now work as expected
• cli tools with legitimately underscored arguments (e.g. addDataToRaster, checkMesh,
  generateGeometry) no longer have their argument names incorrectly converted to hyphens

Features

New Core Framework

• Model: New class combining project file, meshes, and execution settings into
  a complete OGS model. Can be created from components or loaded from disk.
  • Model.run() executes the simulation and returns a Simulation object
  • Model.run(<path>) writes the simulation results into the specified folder
  • Model.cmd property to inspect or reuse the full OGS command string
  • Model.plot_constraints() visualizes boundary conditions and source terms
  • Supports all storage operations (save, load by folder or ID)
• Simulation: Represents a completed (ongoing by SimulationController) OGS simulation with model and results.
  • Simulation.meshseries provides access to the simulation output
  • Simulation.log provides access to parsed log file as a Log object
  • Simulation.status and Simulation.status_str track simulation state
  • Full save/load support with automatic storage of model, results, and logs
  • Simulation.restart allows restarting a simulation from a previous run.
• Execution: Manages OGS execution parameters (parallelization, logging, etc.)
  • Configurable OMP threads and assembly threads
  • Execution from YAML files or programmatic configuration
  • ogs parameter accepts binary directory, container path (.sif/.squashfs), or URL
  • Built-in container URLs: Execution.CONTAINER_SERIAL / CONTAINER_PARALLEL (OGS 6.5.7)
  • Auto-detection via OGS_BIN_PATH env var or $PATH if ogs is not specified
  • Site-wide defaults via OGS_EXECUTION_DEFAULTS env var pointing to a YAML file
    (see execution_default_example.yml for reference)
  • Execution.from_default() / Execution.default for sharing a session-wide config
  • cmd property exposes the full OGS command string
• Log: Parser and analyzer for OGS log files
  • convergence_newton_iteration() and convergence_coupling_iteration() extract
    convergence data
  • plot_convergence() visualizes convergence behavior
  • simulation_info() and termination_info() provide simulation metadata
• Storage System (SaveBase): Unified base class for all saveable objects
  • Configurable user path via SaveBase.Userpath and backup strategy via SaveBase.Backup flag
  • ID-based organization in class-specific subdirectories
  • Archive mode for creating portable, self-contained copies
  • Temporary storage support for intermediate objects

mesh

• added ot.mesh.node_reordering to fix node ordering of a mesh to comply with OGS standards
• added ot.mesh.validate to check, whether a mesh complies with OGS standards

gmsh_tools

• added more control over the discretization for remesh_with_triangles.

MeshSeries

• added support for logarithmic scaling in ot.MeshSeries.plot_time_slice.
• new functions for renaming domain and subdomains
• can now be scaled spatially / temporally in the Constructor
• added interpolate method, to interpolate the MeshSeries data on a new mesh
• added compare method to ot.MeshSeries.
• Storage support: can be saved and loaded by folder or ID

Meshes

• save function performs partmesh if number of partitions are given, with optional dry_run
  • create_partitioning() and create_metis if vtu files are already present
• subdomains() -> subdomain, domain_name() -> domain_name (with setter)
• plot method displays domain mesh and subdomains (2D domain only for now)
• remove_material method removes specified material id from domain and
  updates subdomains accordingly
• modify_names method extends mesh names with prefix and/or suffix
• Meshes.from_mesh now also works for 3D domain meshes
• now checks datatypes of MaterialIDs, bulk_node_ids, bulk_element_ids and coordinates upon saving
• from_file() method to restore from meta.yaml
• Storage support with metadata preservation

Project

• dependencies() return a list of referenced/needed files (meshes, xml includes, python scripts)
• plot_constraints() -> overview plot with boundary conditions and source terms
• Enhanced __repr__() and __str__() for better object inspection
• Storage support with proper XML handling

plot

• add option to plot legend outside of plots.
• added support for continuous contourplots via continuous_cmap=True.
• Allow user to set arrowsize parameter in contourf

Variable

• added aggregation methods min, max, mean, median, sum, std, var.

Infrastructure

• uv.lock added for reproducible installs
• scripts/pull_containers.py — helper to pre-pull serial/parallel OGS containers
• Temporary files now isolated under tmp/ogstools/ instead of the system temp root
• Drop Python 3.10 support
• Add Python 3.14 support
• Updated pinned environment
• Test with container from 3.10 to 3.12
• Dependency and tooling update
• Use Intersphinx for 3rd party package documentation reference
• Monitor (Bokeh) is optional dependency

Documentation

New Examples

• plot_framework_short.py: Condensed workflow demonstrating the complete OGSTools
  framework (Setup → Compose → Run → Analyze → Store)
• plot_storage.py: Comprehensive guide to the storage system covering basic usage,
  ID-based organization, overwriting with backup, archiving, and advanced topics

Updated Examples

• Updated simulation examples to use new Model and Simulation classes
• Modified examples to demonstrate the new storage system capabilities
• Added example data: small_deformation simulation with complete model, execution,
  meshes, and results

Tests

• plotting tes...

0.7.1

OGSTools 0.7.1 Release Notes

• Works with ogs==6.5.6
• Python: 3.10 - 3.13

Breaking changes

API breaking changes

• meshlib.gen_bhe_mesh uses now shapely for meshing geometries see !324:
  • Supports georeferenced modeling in any metric CRS.
  • Flexible model area shapes (no rectangle restriction).
  • Prism mesh works for all cases; structured mesh for well-arranged setups.
  • Limitation: multiple refinement lines in one split surface not yet supported.
  • now output an additional submesh for groundwater downstream
  • how to specify the input, to get the same behavior as before:
    • length and width need to be replaced by model_area
    • Example: length=150, width=100: model_area=Polygon.from_bounds(xmin=0, ymin=0, xmax=150, ymax=100)
    • dist_box_x and dist_box_y need to be replaced by refinement_area (defined in global coordinate system and not relative to the BHE as before)
      • Example:

        dist_box_x=10, dist_box_y=5:
        Polygon.from_bounds(
          xmin=min(bhe.x for bhe in bhe_array)-10,
          ymin=min(bhe.y for bhe in bhe_array)- 5,
          xmax=max(bhe.x for bhe in bhe_array)+10,
          ymax=max(bhe.y for bhe in bhe_array)+ 5,
          )
        

    • Groundwater.flow_direction needs to be replaced by upstream and downstream
      • Example: "x": upstream=(179,181), downstream=(359,1)

Deprecations

• Planned for ot.meshes_from_gmsh (replacement already available: Meshes.from_gmsh)

Examples

Changes (non API-breaking)

Bugfixes

• plot: Fixed contour plots with very small value ranges (< 1e-12) to display correctly
• Project
  • run_model : Fix execution of wrapper commands (e.g. source MKL)
  • Add the missing tag outputs to allow multiple output definitions
• Logparser: fix model_time analysis
• MeshSeries:
  • Fixed accessing meshes of extended MeshSeries from PVD files by ensuring timestep_files is updated correctly after extend().
  • Improved scale method to prevent crashes in complex, performance-intensive workflows; new implementation reuses cached meshes for better stability and memory efficiency.
  • fix extract probe for MeshSeries with a single point meshes
• Mesh:
  • Fixed crash in Mesh.difference() when meshes contain _active datasets; computation now handles active field arrays
• Feflow:
  • Fixed handling of vector and tensor properties with NaN values (#135): tuples containing only NaNs are now dropped correctly, and tensor values are no longer misclassified

Features

• Added MaterialManager and MediaSet to core API and further helper classes: Phase, Medium, Material, Component
  • It introduces a modular and schema-driven material handling system for OGS project files.
  • It includes:
    • A YAML-based material database
    • Schema filtering via MaterialList
    • Export to XML (.to_prj()) compatible with OGS
    • Examples for TH2M
  • It is limited to TH2M for now
• Added Meshes class
  • from_simulator works directly with the OGS mesh in a running simulation
  • from_gmsh is ot.meshes_from_gmsh
  • save performs identify_subdomains, and checks for overwrite
  • from_msh
    • Uses the newly introduced extract_boundaries for simple extraction of boundary meshes from a 2D domain mesh
  • from_yaml
    • Introduces a new tool to generate Gmsh meshes from YAML geometry descriptions.
      • Based on a simple declarative schema (parameters, points, lines, surfaces, groups)
      • Generates .msh files via Gmsh, meshes_from_yaml
• Added plot.contourf_pv for pyvista plots which work with Variables.
• plot.contourf now dispatches depending on the value of the new argument interactive:
  • None (default): 2D mesh -> matplotlib plot, 3D mesh -> interactive pyvista plot
  • True: always interactive pyvista plot
  • False: 2D mesh -> matplotlib plot, 3D mesh -> pyvista plot screenshot
• Added to_polar method for Variables. Useful, to convert stresses to a cylindrical or spherical coordinate system.
• Added SimulationController as wrapper for OGSSimulation to allow interruption and continuing simulations
• BHE
  • Allow ID notation

Infrastructure

• Updated requirements!
• Added Binder links to example notebooks for interactive execution.
• Removed EXPERIMENTAL folder -> see Gitlab open issues
• Re-enable testing for Mac
• Faster pipeline execution (10min -> 6min)

Documentation

• Added tutorials for interactive ogs simulation

next main release

• deprecation notice for ot.meshes_from_gmsh

0.7.0

OGSTools 0.7.0 Release Notes

OGS version: 6.5.4
Python: 3.10 - 3.13

Breaking changes

• OGS Wheel (pip install ogs) is now an optional (before mandatory) dependency of OGSTools. OGSTools requests either a OGS wheel OR a custom OGS made available on PATH or OGS_BIN_PATH.

API breaking changes

• mesh.read_shape (removed function, functionality is not covered anymore)

Deprecations

• meshseries.plot_probe (instead use MeshSeries.extract_probe and plot.line)

Examples

• removed all examples with shape files

Changes (non API-breaking)

Bugfixes

• meshes_from_gmsh (msh2vtu): Physical groups, which include other physical groups needed to be defined after the subgroups otherwise groups were comprised of the wrong elements, now it's fixed
• MeshSeries: probe() failed with output meshes only consisting of multiple lines representing BHEs, this is for example the case by using the output option by material id
• MeshSeries: indexing failed with numpy data types
• Feflow converter: Heterogeneous material for properties fixed (for KF only)
• Feflow converter: In CLI extraction of topsurface domain fixed
• BHE: Fix for huge BHE arrays
• plot: Fix for plots from parallel computation (vtkGhostType)

Features

• Logparser: analysis to inspect simulation behaviour over clock time and model time
• Logparser: plot to create an overview of the convergence behavior for the
  entire simulation (ot.logparser.plot_error, ot.logparser.plot_convergence_order)
• Logparser: Functionality for real time monitoring
• Logparser: Can consume new version (2) of OGS log files (can still consume version 1)
• OGS simulation can be run in a background process via ot.Project.run_model(..., background=True)
• MeshSeries.extract_probe/probe/values accept str/Variables and lists of them as arguments (with improved performance)
• plot: handle gaps in sampling lines and disjoined line meshes, such that each individual region is drawn separately.
• Project: Run simulations in background
• Project: Showcasing a second variant of setting well defined initial pressures in the gallery

Infrastructure

• Several fixes for pyvista>=0.45
• Pagefind index generation

Tests

• Hypothesis testing introduction
• More parallel and parameterized tests

Usability

• Clarify what is expected from the user-provided list of observation points in plot_probe.
• Some improved error messages

Maintainer TODOs

next sub release

next main release

• MeshSeries: from_data() constructor -> init()

0.6.0

OGSTools 0.6.0 Release Notes

OGS version: 6.5.4 (But OGS is from now on optional!)

Python: 3.10 - 3.13

API breaking changes

• meshseries.probe now squeezes the returned array: it seems more intuitive to return a 1D array if no list of points is provided (just a single tuple)
• meshseries.plot_time_slice has a new user interface - see the update example or the API reference. The interpolate argument was removed, as it tempts you to be used as a default (as it produces a nice image), but in doing so, can easily lead to wrong conclusions as the interpolated image might differ significantly from the raw data.
• generalized meshseries.animate: it is now a freestanding function (plot.animate) and can take any plotting function - see the updated example or the API reference

Features

• MeshSeries can now be initialized with from_data(meshes, timevalues)
• MeshSeries now has an .items() iterator
• MeshSeries has now an .extend function to combine 2 MeshSeries (e.g. for simulation restart/continuation)
• plot.line now automatically sorts the data
• User can select format when saving animation (gif or mp4)
• variables.vector add BHE vector with support for slicing its components
• Variables now have methods to create Variables related to absolute error, relative error and analytical solution corresponding to the parent Variable
• Variable.transform now also works on MeshSeries
• plot.line now can also handle MeshSeries - this allows to draw an array of lines in one call (e.g. lines for each pt in the MeshSeries over time or lines for each timestep over a spatial coordinate)
• plot.contourf now only returns a figure if it wasn't given one as an argument
• improved axis labelling for shared axes (only the outer axes should get labelled now)
• new: meshseries.resample to interpolate the meshseries to new timevalues
• new: extract_probe to create a new meshseries consisting only of points and probed data at these points
• OGS_BIN_PATH is read, this allows to specify a location of a custom OGS (ogs wheel not needed)
• Improved errors and warnings when system has multiple or no OGS on PATH
• ogstools.status(verbose=True) prints status of OGS installation

Infrastructure

Tests

• Tests can be marked as system and tools
  • system tests: Invoke running a simulation with OGS
  • tools tests: Invoke calls to OGS binary tools and pybind11 functionality (in future)
• Mac Tests added

Imports

• When imports are actually implementation details, they should be loaded within the calling function (delayed initialization). Applied to imports that rely on OGS installation.

0.5.0

OGSTools 0.5.0 Release Notes

• Recommended OGS Version: 6.5.4

API breaking changes

• MeshSeries.data --> MeshSeries.values
• MeshSeries.clear --> MeshSeries.clear_cache
• In aggregate functions func str is replaced by callables (e.g. numpy.min)
• meshlib.gmsh_meshing.remesh_with_triangle --> meshlib.gmsh_meshing.remesh_with_triangles
• msh2vtu python interface was replaced with meshes_from_gmsh
  • CLI tool msh2vtu is not affected by this
  • parameter keep_ids was removed (in our OGS world there is no reason to keep the gmsh data names and the wrong data types in the meshes, which would happen if k was used)
  • parameter log_level was changed to log (True or False)
• removed:
  • MeshSeries.spatial_data_unit/spatial_output_unit/time_unit (see
    MeshSeries.scale())
  • plot.linesample/linesample_contourf
  • meshlib.data_processing.interp_points/distance_in_profile/sample_polyline
    (see updated line sample example)

Bugfixes

• Failed sub library imports led to incomplete and unhandled package import
• MeshSeries was unable to handle xdmf with just one timestep correctly
• MeshSeries kept the hdf5 file handle open - parallel read access was not possible
• OMP_NUM_THREADS was not working on Windows
• Feflow mesh did not allow mixed celltypes
• plot functions had sometimes different color schemes in the color bar
• Tortuosity was not a medium property
• BHE mesh (z coordinate negative)

Features

• MeshSeries gets copy() method.
• MeshSeries gets transform() method, that applies an arbitrary transformation function to all time steps.
• MeshSeries get extract() method to select points or cells via ids
• MeshSeries can be sliced to get new MeshSeries with the selected subset of timesteps
• MeshSeries gets a modify function that applies arbitrary function to all timestep - meshes.
• MeshSeries gets a save function (only for pvd implemented yet)
• difference() between two meshes is now possible even with different topologies
• Project write_input, path can be specified
• MeshSeries gets scale() method to scale spatially or temporally
• variables.get_preset will now return a Variable corresponding to the spatial
  coordinates if given "x", "y" or "z"
• plot module gets line() function as a general purpose 1D plotting function
• plot.setup get spatial_unit and time_unit which are used for labeling

Infrastructure

• Python 3.13 support (CI testing)
• Testing of all supported Python version 3.10-3.13 (pip and conda)
• Testing with pinned dependencies in regression tests and with open dependencies in maintenance tests
• msh2vtu - complete overhaul

Examples

• All examples use import ogstools as ot. To not be confused with ogs python bindings

Footnotes

• All related Merge requests are tagged with 0.5.0 Release https://gitlab.opengeosys.org/ogs/tools/ogstools/-/merge_requests?scope=all&state=merged&milestone_title=0.5.0%20Release

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 )