Release notes 0.4.0

docs/releases/index.md

@@ -5,6 +5,7 @@
 maxdepth: 3
 ---
 0.x (upcoming release)  <ogstools-0.x>
+0.4.0 <ogstools-0.4.0>
 0.3.1 <ogstools-0.3.1>
 0.3.0 <ogstools-0.3.0>
 0.2.0 <ogstools-0.2.0>

docs/releases/ogstools-0.4.0.md

+# 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](https://github.com/joergbuchwald/ogs6py/releases/tag/v.403) (only light API changes, see Features/Project file)
+
+## OGS
+
+[OpenGeoSys](https://www.opengeosys.org/) 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:
+
+```python
+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:
+
+```python
+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](https://ogs.ogs.xyz/tools/ogstools/auto_examples/howto_plot/plot_timeslice.html#))
+
+![time_slice](https://ogs.ogs.xyz/tools/ogstools/_images/sphx_glr_plot_timeslice_001.png)
+
+- 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
+  ![Mesh_triangle](https://ogs.ogs.xyz/tools/ogstools/_images/sphx_glr_plot_remeshing_002.png)
+- MeshSeries has a performant algorithm for integration point tessellation called `MeshSeries.ip_tesselated()` -  [example for analyzing integration point data](https://ogs.ogs.xyz/tools/ogstools/auto_examples/howto_postprocessing/plot_ipdata.html#sphx-glr-auto-examples-howto-postprocessing-plot-ipdata-py)
+- MeshSeries allows multidimensional indexing on ndarrays <https://numpy.org/doc/stable/user/basics.indexing.html>
+
+```python
+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
+  1. 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)