diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 92d426fa722cb997c8caae6c03b84ae1a5984a1e..ff76fd6def6b550f3aa703a12871f704be8ffc17 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -49,7 +49,7 @@ tests feflow:
image: registry.opengeosys.org/ogs/tools/feflow-python-docker:8.0.1
script:
- python -m venv .venv --upgrade-deps
- - .venv/bin/pip install --extra-index-url https://gitlab.opengeosys.org/api/v4/projects/120/packages/pypi/simple -e .[dev,test,docs,feflow]
+ - .venv/bin/pip install -e .[dev,test,docs,feflow]
- make setup_headless
- source .venv/bin/activate
- make coverage
@@ -66,7 +66,7 @@ tests win:
before_script:
- python -m venv .venv
- .venv\Scripts\Activate.ps1
- - pip install --extra-index-url https://gitlab.opengeosys.org/api/v4/projects/120/packages/pypi/simple -e ".[dev,test]"
+ - pip install -e ".[dev,test]"
script:
- tox -p
# Bug: -e docs only works on Windows when called from docs/-dir.
@@ -74,7 +74,10 @@ tests win:
- tox -e docs
.docs-script: &docs-script
- - *setup-headless
+ - python -m venv .venv --upgrade-deps
+ - .venv/bin/pip install -e .[dev,test,docs,feflow]
+ - make setup_headless
+ - source .venv/bin/activate
- make docs
- mv docs/_build/html public
diff --git a/Makefile b/Makefile
index 910dd0bd495c8f0c55c766358f97a90093f960d3..19d118187f2d862247b5779eb497ced10f17656e 100644
--- a/Makefile
+++ b/Makefile
@@ -5,16 +5,16 @@ help: ## Show this help
setup: ## Setup a virtual environment and install all development dependencies
python -m venv .venv --upgrade-deps
- .venv/bin/pip install --extra-index-url https://gitlab.opengeosys.org/api/v4/projects/120/packages/pypi/simple -e .[dev,test,docs]
+ .venv/bin/pip install -e .[dev,test,docs]
.venv/bin/pre-commit install
@echo
@echo ATTENTION: You need to activate the virtual environment in every shell with:
@echo source .venv/bin/activate
setup_headless: ## Install vtk-osmesa and gmsh without X11 dependencies
- .venv/bin/pip uninstall vtk -y
+ .venv/bin/pip uninstall gmsh vtk -y
.venv/bin/pip install --extra-index-url https://wheels.vtk.org vtk-osmesa
- .venv/bin/pip install -i https://gmsh.info/python-packages-dev-nox --force-reinstall --no-cache-dir gmsh
+ .venv/bin/pip install -i https://gmsh.info/python-packages-dev-nox gmsh
test: ## Runs the unit tests
pytest
diff --git a/README.md b/README.md
index 10cb329ea367b84713a7a9f417406c7012efbc47..e171c6276cb9822136dfa5798977778058d62f6e 100644
--- a/README.md
+++ b/README.md
@@ -1,30 +1,47 @@
-# ogstools
+
-A collection of Python tools aimed at evolving into a modeling toolchain around OpenGeoSys.
+is a:
-In this project we'll collect existing pre and postprocessing scripts for
-OpenGeoSys at first. Over time we'll develop an entire toolchain out of that
-collection. Currently we are at the stage of code collection.
+- python library for streamlined usage of [OpenGeoSys](https://www.opengeosys.org),
+- set of interconnected modules for pre- and postprocessing of simulations with [OpenGeoSys](https://www.opengeosys.org),
+- valuable resource that includes documentation, Jupyter notebooks, and workflows for guidance and reference.
-See the [Documentation](https://ogs.ogs.xyz/tools/ogstools/) for more information.
+
-## Please donate your existing Python tools for OpenGeoSys
+# Overview
-This can be done via merge request or via issue. For both we have set up
-templates for the merge request or issue description that will ask you for some
-details, e.g., purpose, features, application background of your contribution.
+- **Website:** <https://www.opengeosys.org>
+- **Documentation:** <https://ogs.ogs.xyz/tools/ogstools>
+- **Source code:** <https://gitlab.opengeosys.org/ogs/tools/ogstools>
+- **Contributing:** <https://ogs.ogs.xyz/tools/ogstools/development/index.html>
+- **Bug reports:** <https://discourse.opengeosys.org>
-Use the merge request option if you want to contribute some tool that is very
-likely useful for many users of OGS.
+# Installation
-Use the issue option if you have a bunch of scripts in some repository, out of
-which some might be useful for others and some are too special. However, the
-merge request option is preferred.
+Install the latest version of ogstools:
-## Minimum requirements for a donation
+```bash
+pip install ogstools
+```
-- The Python scripts must be syntactically correct code.
-- There should be a short feature and usage description, e.g., in form of a README file
-- Please do not add large amounts of data.
-- You as a donator must have the right to donate the code, i.e., you are the
- sole author or all authors agree.
+For further details see the [User Guide](https://ogs.ogs.xyz/tools/ogstools/user-guide/index.html).
+
+# Getting started
+
+For first steps, please take a look at our [examples](https://ogs.ogs.xyz/tools/ogstools/auto_examples/index.html).
+
+# Contribution
+
+Please report bugs on [Discourse](https://discourse.opengeosys.org) or fork the repository on our [GitLab](https://gitlab.opengeosys.org/ogs/tools/ogstools) and create a merge request. We also welcome contributions in the form of merge requests and are here to assist in ensuring that the code passes all quality checks. We recommend starting with the [Developer Guide](https://ogs.ogs.xyz/tools/ogstools/development/index.html) as your initial point of reference.
+
+You may also contribute by [donating](https://gitlab.opengeosys.org/ogs/tools/ogstools/-/blob/release-notes/donation.md) your existing code snippets.
+
+# Related projects
+
+- [ogs](https://pypi.org/project/ogs)
+- [ogs6py](https://pypi.org/project/ogs6py)
+- [VTUInterface](https://pypi.org/project/VTUinterface)
+
+# License
+
+`ogstools` is distributed under the Modified BSD License. See the `LICENSE`-file for the license text.
diff --git a/docs/_static/ogstools.png b/docs/_static/ogstools.png
new file mode 100644
index 0000000000000000000000000000000000000000..0a4f521953a389b9add5efe1a7b7f8ee4ce6dda4
Binary files /dev/null and b/docs/_static/ogstools.png differ
diff --git a/docs/conf.py b/docs/conf.py
index d09a3d216b415dbea86beb118a1cfd7303703062..020299cc0c268556061ae77f168ccae2df62ea21 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -93,18 +93,6 @@ autodoc_member_order = "bysource"
autodoc_preserve_defaults = True
autodoc_typehints = "description"
-# fe2vtu is optional
-gallery_ignore_pattern = ""
-try:
- import ifm_contrib as ifm # noqa: F401
-except ImportError:
- msg = "Could not import ifm. A working Feflow Python setup is required!"
- exclude_patterns.extend(
- ["reference/ogstools.fe2vtu.*", "user-guide/fe2vtu*"]
- )
- apidoc_excluded_paths.append("../**/fe2vtu/**")
- gallery_ignore_pattern = r".*fe2vtu\.py"
-
### sphinx-gallery setup ###
# necessary when building the sphinx gallery
pyvista.BUILDING_GALLERY = True
@@ -116,10 +104,20 @@ sphinx_gallery_conf = {
"show_signature": False,
"download_all_examples": False,
"image_scrapers": ("matplotlib", "pyvista"),
- "ignore_pattern": gallery_ignore_pattern,
"matplotlib_animations": True,
}
+# fe2vtu is optional
+try:
+ import ifm_contrib as ifm # noqa: F401
+except ImportError:
+ print("Skipping FEFLOW-related functionality for the documentation!")
+ exclude_patterns.extend(
+ ["reference/ogstools.fe2vtu.*", "user-guide/fe2vtu*"]
+ )
+ apidoc_excluded_paths.append("../**/fe2vtu/**")
+ sphinx_gallery_conf["ignore_pattern"] = r".*fe2vtu\.py"
+
# Suppress sphinx warning for multiple documents generated by sphinx-gallery
# May break myst-nb?
diff --git a/docs/development/index.md b/docs/development/index.md
index 89c4b879c5dca029b1e89058548edb4a118f660e..63003f0419287489b9eb855144b0b6dad253a02c 100644
--- a/docs/development/index.md
+++ b/docs/development/index.md
@@ -5,7 +5,7 @@ Create a virtual environment, activate it and install required packages:
```bash
python -m venv .venv
source .venv/bin/activate
-pip install --extra-index-url https://gitlab.opengeosys.org/api/v4/projects/120/packages/pypi/simple -e ".[dev,test,docs]"
+pip install -e ".[dev,test,docs]"
# enable basic style checks once
pre-commit install
@@ -43,6 +43,7 @@ msh2vtu --help
:::{admonition} Using `make` for shortcuts!
:class: tip
+:name: make-shortcut
Development-related tasks can also be done with `make` (requires a Bash shell with `make`). The above development setup can also be generated with:
@@ -111,6 +112,12 @@ The examples can be downloaded from the final website as Jupyter notebook files.
You can interactively run and debug these files in Visual Studio Code, see the [Python Interactive window documentation](https://code.visualstudio.com/docs/python/jupyter-support-py).
+If you want to link to a gallery page from another page use the following syntax (prefix with `sphx_glr_`, replace directory separator with `_`):
+
+```md
+{ref}`meshlib example <sphx_glr_auto_examples_howto_meshlib_plot_meshlib_pyvista_input.py>`
+```
+
### Further information
For syntax references and extension usage see the following links:
diff --git a/docs/index.md b/docs/index.md
index 3780f00134ba69852443a8ed98c8f49a274b0a83..bda08a3a8c39730ff1a3dc4eed3681f300aaa61d 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -17,8 +17,6 @@ Release notes <releases/index>
`ogstools` is a collection of Python tools aimed at evolving into a modeling toolchain around [OpenGeoSys](https://www.opengeosys.org), a finite element solver for coupled thermo-hydro-chemo-mechanical problems in the subsurface.
-In this project we’ll collect existing pre and postprocessing scripts for OpenGeoSys at first. Over time we’ll develop an entire toolchain out of that collection. Currently we are at the stage of code collection.
-
**Date:** {sub-ref}`today` **Version:** {sub-ref}`version`
**Useful links:** [Source repository](https://gitlab.opengeosys.org/ogs/tools/ogstools) | [Issues](https://gitlab.opengeosys.org/ogs/tools/ogstools/-/issues) | [OpenGeoSys Website](https://www.opengeosys.org) | [OpenGeoSys Forum](https://discourse.opengeosys.org)
diff --git a/docs/releases/index.md b/docs/releases/index.md
index 1044dc7fafd0c2db8958985f9fab07d494f2b10b..bc57a45e5a40af0d1ab1a4e75b5704e6383482fb 100644
--- a/docs/releases/index.md
+++ b/docs/releases/index.md
@@ -5,4 +5,5 @@
maxdepth: 3
---
0.0.3 <ogstools-0.0.3>
+0.1.0 <ogstools-0.1.0>
```
diff --git a/docs/releases/ogstools-0.0.3.md b/docs/releases/ogstools-0.0.3.md
index 5c38f972e87d12fb399d189b6abcfe2c09fe63df..91502fc847d0aa5b5b40dfac5b3e3a2a94881b02 100644
--- a/docs/releases/ogstools-0.0.3.md
+++ b/docs/releases/ogstools-0.0.3.md
@@ -8,10 +8,6 @@ This is the first release of the `ogstools`-package, a joint effort of OGS users
The `msh2vtu`-tool by Dominik Kern (TU Bergakademie Freiberg) has been integrated into ogstools. For more info see [](../user-guide/msh2vtu.md). Its former repository at GitHub [dominik-kern/msh2vtu](https://github.com/dominik-kern/msh2vtu) has been deprecated and development continues under the ogstools umbrella.
-### meshplotlib
-
-A python package to visualize mesh data. For more info see [](../user-guide/meshplotlib.md).
-
## Infrastructure
### Documentation web site
diff --git a/docs/releases/ogstools-0.1.0.md b/docs/releases/ogstools-0.1.0.md
new file mode 100644
index 0000000000000000000000000000000000000000..b9123b759d6b405ed484223650fa3d605254b31e
--- /dev/null
+++ b/docs/releases/ogstools-0.1.0.md
@@ -0,0 +1,31 @@
+# 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!
+
+## Library
+
+[`meshlib`](../user-guide/meshlib.md) 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`](../user-guide/meshplotlib.md) 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`](../user-guide/propertylib.md) 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`](../user-guide/nuclearwasteheat.md) 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 [`fe2vtu`](../user-guide/fe2vtu.md)-tool convert data stored in FEFLOW binary format to VTK format. It can only be used with a [FEFLOW installation](../user-guide/fe2vtu.md#installation).
+
+## Infrastructure & Development
+
+[Examples](../auto_examples/index.rst) on the web page are generated via [sphinx_gallery](https://sphinx-gallery.github.io/stable/index.html) which also allows for downloading the example as an Jupyter Notebook file.
+
+We also added some shortcuts via `make` for [development related tasks](../development/index.md) such as setting up the development environment, running the tests or creating a live preview of the documentation.
diff --git a/donation.md b/donation.md
new file mode 100644
index 0000000000000000000000000000000000000000..88d3551f212332b8b4b59b922dcd9d422ae24e8a
--- /dev/null
+++ b/donation.md
@@ -0,0 +1,20 @@
+## Please donate your existing Python tools for OpenGeoSys
+
+This can be done via merge request or via issue. For both we have set up
+templates for the merge request or issue description that will ask you for some
+details, e.g., purpose, features, application background of your contribution.
+
+Use the merge request option if you want to contribute some tool that is very
+likely useful for many users of OGS.
+
+Use the issue option if you have a bunch of scripts in some repository, out of
+which some might be useful for others and some are too special. However, the
+merge request option is preferred.
+
+## Minimum requirements for a donation
+
+- The Python scripts must be syntactically correct code.
+- There should be a short feature and usage description, e.g., in form of a README file
+- Please do not add large amounts of data.
+- You as a donator must have the right to donate the code, i.e., you are the
+ sole author or all authors agree.
diff --git a/pyproject.toml b/pyproject.toml
index 666ac139b908bfa530962b349778c9964318dda7..0d6522cf52c912a52dc6068a8329452137bdeb68 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -20,7 +20,6 @@ dependencies = [
"Pint>=0.22",
"Pillow>=9.5.0",
"pandas>=2.0.3",
- # needs PIP_EXTRA_INDEX_URL=https://gitlab.opengeosys.org/api/v4/projects/120/packages/pypi/simple
"ogs>=6.4.5.dev0",
]
@@ -42,7 +41,7 @@ msh2vtu = 'ogstools.msh2vtu._cli:cli'
fe2vtu = 'ogstools.fe2vtu._cli:cli'
[project.optional-dependencies]
-dev = ["pre-commit>=2.20", "tox>=4.1", "build"]
+dev = ["pre-commit>=2.20", "tox>=4.1", "build", "black"]
test = ["pytest", "coverage", "gmsh"]
docs = [
"sphinx",
@@ -60,7 +59,13 @@ feflow = ["ifm_contrib@git+https://github.com/red5alex/ifm_contrib"]
[tool.pytest.ini_options]
minversion = "6.0"
-addopts = ["-ra", "--showlocals", "--strict-markers", "--strict-config"]
+addopts = [
+ "-ra",
+ "--showlocals",
+ "--strict-markers",
+ "--strict-config",
+ "--import-mode=importlib",
+]
xfail_strict = true
# TODO: LB enable this again, deal with MatplotlibDeprecationWarning in fe2vtu
# tests
diff --git a/tox.ini b/tox.ini
index ae5c101229ac2d2173c45ca571d7ebc837b3338f..0b389be6bb36360578ae39aafa9b0e8a6ca31de2 100644
--- a/tox.ini
+++ b/tox.ini
@@ -13,7 +13,6 @@ commands =
coverage run -m pytest {posargs}
setenv =
COVERAGE_FILE={toxworkdir}/.coverage.{envname}
- PIP_EXTRA_INDEX_URL=https://gitlab.opengeosys.org/api/v4/projects/120/packages/pypi/simple
description = Run tests with {envname}
depends =
report: py3{9,10,11}