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 tests now actually check whether the resulting figure is as expected

  • Added comprehensive tests for new framework components:

    • test_framework.py: Tests for Model, Simulation, Result integration

    • test_model.py: Model class functionality

    • test_simulation.py: Simulation lifecycle and storage

    • test_storage.py: Storage system, backup, and archive functionality

Imports#

  • Top-level API now exports additionally: Model, Simulation, SimulationController, Execution, Log

Maintainer TODOs#

next sub release#

next main release#