Merge branch 'doc/update-grid' into 'master'

updated README of exercise-grids

See merge request !298

(cherry picked from commit 0c9e53a1)

0c236e59 Update exercise-grids README
7c1a6884 Create patch for updated exercise-grids

Co-authored-by: David Lipp <david.lipp@iws.uni-stuttgart.de>

.patches/exercise-grids/exercise-grids.patch

 diff -ruN exercises/exercise-grids/CMakeLists.txt exercises/solution/exercise-grids/CMakeLists.txt
---- exercises/exercise-grids/CMakeLists.txt	2025-03-07 10:42:02.613882973 +0100
-+++ exercises/solution/exercise-grids/CMakeLists.txt	2025-03-07 10:42:02.621882923 +0100
+--- exercises/exercise-grids/CMakeLists.txt	2025-03-19 10:40:25.785990564 +0100
++++ exercises/solution/exercise-grids/CMakeLists.txt	2025-03-19 10:40:25.793990576 +0100
 @@ -2,7 +2,7 @@
  # SPDX-License-Identifier: GPL-3.0-or-later
  
@@ -11,7 +11,7 @@ diff -ruN exercises/exercise-grids/CMakeLists.txt exercises/solution/exercise-gr
  
  # add a symlink for each input file
 diff -ruN exercises/exercise-grids/grids/grid_structured.dgf exercises/solution/exercise-grids/grids/grid_structured.dgf
---- exercises/exercise-grids/grids/grid_structured.dgf	2025-02-26 11:38:46.808817872 +0100
+--- exercises/exercise-grids/grids/grid_structured.dgf	2024-11-06 16:32:48.959523817 +0100
 +++ exercises/solution/exercise-grids/grids/grid_structured.dgf	1970-01-01 01:00:00.000000000 +0100
 @@ -1,6 +0,0 @@
 -DGF
@@ -21,7 +21,7 @@ diff -ruN exercises/exercise-grids/grids/grid_structured.dgf exercises/solution/
 -30 20   % cells in x and y direction
 -#
 diff -ruN exercises/exercise-grids/grids/grid_structured.geo exercises/solution/exercise-grids/grids/grid_structured.geo
---- exercises/exercise-grids/grids/grid_structured.geo	2025-02-26 11:38:46.808817872 +0100
+--- exercises/exercise-grids/grids/grid_structured.geo	2024-11-06 16:32:48.959523817 +0100
 +++ exercises/solution/exercise-grids/grids/grid_structured.geo	1970-01-01 01:00:00.000000000 +0100
 @@ -1,30 +0,0 @@
 -X = 60;
@@ -55,8 +55,8 @@ diff -ruN exercises/exercise-grids/grids/grid_structured.geo exercises/solution/
 -Transfinite Volume "*";
 -
 diff -ruN exercises/exercise-grids/main.cc exercises/solution/exercise-grids/main.cc
---- exercises/exercise-grids/main.cc	2025-03-07 10:42:02.614882967 +0100
-+++ exercises/solution/exercise-grids/main.cc	2025-03-07 10:42:02.621882923 +0100
+--- exercises/exercise-grids/main.cc	2025-03-19 10:40:25.785990564 +0100
++++ exercises/solution/exercise-grids/main.cc	2025-03-19 10:40:25.793990576 +0100
 @@ -6,7 +6,7 @@
  //
  /*!
@@ -67,8 +67,8 @@ diff -ruN exercises/exercise-grids/main.cc exercises/solution/exercise-grids/mai
  #include <config.h>
  
 diff -ruN exercises/exercise-grids/params.input exercises/solution/exercise-grids/params.input
---- exercises/exercise-grids/params.input	2025-03-07 11:30:34.875192028 +0100
-+++ exercises/solution/exercise-grids/params.input	2025-03-07 11:30:34.878192008 +0100
+--- exercises/exercise-grids/params.input	2025-03-19 10:40:25.785990564 +0100
++++ exercises/solution/exercise-grids/params.input	2025-03-19 10:40:25.793990576 +0100
 @@ -3,13 +3,34 @@
  TEnd = 3.154e9 # in seconds, i.e ten years
  
@@ -110,8 +110,8 @@ diff -ruN exercises/exercise-grids/params.input exercises/solution/exercise-grid
  [Problem]
  Name = grid_exercise
 diff -ruN exercises/exercise-grids/properties.hh exercises/solution/exercise-grids/properties.hh
---- exercises/exercise-grids/properties.hh	2025-03-07 11:30:34.875192028 +0100
-+++ exercises/solution/exercise-grids/properties.hh	2025-03-07 11:30:34.878192008 +0100
+--- exercises/exercise-grids/properties.hh	2025-03-19 10:40:25.785990564 +0100
++++ exercises/solution/exercise-grids/properties.hh	2025-03-19 10:40:25.793990576 +0100
 @@ -5,9 +5,9 @@
  // SPDX-License-Identifier: GPL-3.0-or-later
  //
@@ -163,17 +163,22 @@ diff -ruN exercises/exercise-grids/properties.hh exercises/solution/exercise-gri
  // Set the problem property
  template<class TypeTag>
 diff -ruN exercises/exercise-grids/README.md exercises/solution/exercise-grids/README.md
---- exercises/exercise-grids/README.md	2025-02-26 11:38:46.808817872 +0100
+--- exercises/exercise-grids/README.md	2025-03-19 10:35:32.496309991 +0100
 +++ exercises/solution/exercise-grids/README.md	1970-01-01 01:00:00.000000000 +0100
-@@ -1,159 +0,0 @@
+@@ -1,206 +0,0 @@
 -# Exercise Grids (DuMuX course)
--<br>
+-The aim of this exercise is to show how to use and adapt different grid implementations in _DuMu<sup>x</sup>_. The DUNE core module dune-grid provides `YaspGrid`, `OneDGrid`, and the meta-grid manager `GeometryGrid`.
+-
+-Further grid implementations are available as additional modules. For a summary of the grid types that you can use in _DuMu<sup>x</sup>_, you can have a look at the [grid types overview](
+-#overview-of-dune-grid-types-selection) at the end of this exercise.
+-
+-**Note:** ALUGrid, which you will need in Task 4 is not contained in the dune core modules. It needs to be installed separately.
 -
 -## Problem set-up
 -
--Here we will expand on what we've covered in the basics exercise, and the problem set up will remain the same.
+-Here, we will expand on what we've covered in the basics exercise, and the problem set up will remain the same.
 -
--## Preparing the exercise
+-## Preparing the Exercise
 -
 -* Navigate to the directory `dumux-course/exercises/exercise-grids/`
 -
@@ -325,3 +330,45 @@ diff -ruN exercises/exercise-grids/README.md exercises/solution/exercise-grids/R
 -This grid is made up of triangles (simplices of dimension 2). This element type can be set in the grid properties section.
 -
 -* > __Task 5__: Change the grid property element type to include `Dune::simplex` instead of `Dune::cube`. Read in the unstructured grid via the input file and run the simulation.
+-
+-<br>
+-
+-# Overview of DUNE Grid Types (selection)
+-
+-## The dune-grid Core Module
+-The dune-grid module contains the implementations of `OneDGrid`, `YaspGrid` and `GeometryGrid`.
+-
+-`OneDGrid` and `YaspGrid` are native DUNE grid implementations. OneDGrid provides an unstructured and adaptive one-dimensional grid whereas YaspGrid is a structured, parallel grid. Elements of that grid can be instantiated with uniform sizes or with a spatial grading. Its domain is a d-dimensional hypercube in \(\mathbb{R}^d\), with axis-aligned d-dimensional hypercubes as elements.
+-
+-`GeometryGrid` is a meta grid manager. That means it wraps any other grid implementation ("host grid") and transforms the geometry of that host grid using a user-provided coordinate transformation.
+-
+-For more information, see:<br>
+-DUNE — The Distributed and Unified Numerics Environment https://doi.org/10.1007/978-3-030-59702-3
+-
+-## dune-alugrid
+-`ALUGrid` offers cube grids and unstructured simplices. The grids can be two- or three-dimensional. Two-dimensional grids can be embedded into a three-dimensional world space if the represented domain is a manifold.
+-
+-It is a powerful grid for large distributed problems and provides different load-balancing algorithms. 
+-
+-For more information, see:<br>
+-DUNE — The Distributed and Unified Numerics Environment https://doi.org/10.1007/978-3-030-59702-3<br>
+-The DUNE-ALUGrid Module https://doi.org/10.11588/ans.2016.1.23252
+-
+-## dune-foamgrid
+-This module is used for one- or two-dimensional grids embedded in a space of arbitrary dimensions. The grids are not required to have a manifold structure, meaning a facet may be shared by more than two elements.
+-
+-The geometry approximation for curved domains can be improved by using element parametrizations. At runtime, elements can be added to or removed from the grid, allowing FoamGrid to grow and shrink. 
+-
+-It can for example be used to model foams, discrete fractures or network flow problems.
+-
+-For more information, see:<br>
+-The Dune FoamGrid implementation for surface and network grids https://doi.org/10.11588/ans.2017.1.28490
+-
+-## dune-uggrid
+-`UGGrid` supports unstructured grids in both 2D and 3D. 2D grids can contain triangles and quadrilaterals, while 3D grids can include tetrahedra, hexahedra, prisms, and pyramids. Different element types can be combined in one grid. The grid dimension is a template parameter of the `UGGrid` class. Multiple `UGGrid` instances can coexist as long as memory allows. `UGGrid` supports adaptive red-green refinement and non-conforming refinement, as well as anisotropic refinement.
+-
+-For more information, see:<br>
+-https://www.dune-project.org/modules/dune-uggrid/
+-
+-## Further Grid Modules
+-This section should have given you an overview of the grid implementations that come with the core DUNE installation as well as some additional, regularly-used grid modules. More grid modules are presented on https://dune-project.org/groups/grid/.

exercises/exercise-grids/README.md

 # Exercise Grids (DuMuX course)
-<br>
+The aim of this exercise is to show how to use and adapt different grid implementations in _DuMu<sup>x</sup>_. The DUNE core module dune-grid provides `YaspGrid`, `OneDGrid`, and the meta-grid manager `GeometryGrid`.
+
+Further grid implementations are available as additional modules. For a summary of the grid types that you can use in _DuMu<sup>x</sup>_, you can have a look at the [grid types overview](
+#overview-of-dune-grid-types-selection) at the end of this exercise.
+
+**Note:** ALUGrid, which you will need in Task 4 is not contained in the dune core modules. It needs to be installed separately.
 
 ## Problem set-up
 
-Here we will expand on what we've covered in the basics exercise, and the problem set up will remain the same.
+Here, we will expand on what we've covered in the basics exercise, and the problem set up will remain the same.
 
-## Preparing the exercise
+## Preparing the Exercise
 
 * Navigate to the directory `dumux-course/exercises/exercise-grids/`
 
@@ -157,3 +162,45 @@ An example of an unstructured grid is located in the `grid/` folder (`grid_unstr
 This grid is made up of triangles (simplices of dimension 2). This element type can be set in the grid properties section.
 
 * > __Task 5__: Change the grid property element type to include `Dune::simplex` instead of `Dune::cube`. Read in the unstructured grid via the input file and run the simulation.
+
+<br>
+
+# Overview of DUNE Grid Types (selection)
+
+## The dune-grid Core Module
+The dune-grid module contains the implementations of `OneDGrid`, `YaspGrid` and `GeometryGrid`.
+
+`OneDGrid` and `YaspGrid` are native DUNE grid implementations. OneDGrid provides an unstructured and adaptive one-dimensional grid whereas YaspGrid is a structured, parallel grid. Elements of that grid can be instantiated with uniform sizes or with a spatial grading. Its domain is a d-dimensional hypercube in \(\mathbb{R}^d\), with axis-aligned d-dimensional hypercubes as elements.
+
+`GeometryGrid` is a meta grid manager. That means it wraps any other grid implementation ("host grid") and transforms the geometry of that host grid using a user-provided coordinate transformation.
+
+For more information, see:<br>
+DUNE — The Distributed and Unified Numerics Environment https://doi.org/10.1007/978-3-030-59702-3
+
+## dune-alugrid
+`ALUGrid` offers cube grids and unstructured simplices. The grids can be two- or three-dimensional. Two-dimensional grids can be embedded into a three-dimensional world space if the represented domain is a manifold.
+
+It is a powerful grid for large distributed problems and provides different load-balancing algorithms. 
+
+For more information, see:<br>
+DUNE — The Distributed and Unified Numerics Environment https://doi.org/10.1007/978-3-030-59702-3<br>
+The DUNE-ALUGrid Module https://doi.org/10.11588/ans.2016.1.23252
+
+## dune-foamgrid
+This module is used for one- or two-dimensional grids embedded in a space of arbitrary dimensions. The grids are not required to have a manifold structure, meaning a facet may be shared by more than two elements.
+
+The geometry approximation for curved domains can be improved by using element parametrizations. At runtime, elements can be added to or removed from the grid, allowing FoamGrid to grow and shrink. 
+
+It can for example be used to model foams, discrete fractures or network flow problems.
+
+For more information, see:<br>
+The Dune FoamGrid implementation for surface and network grids https://doi.org/10.11588/ans.2017.1.28490
+
+## dune-uggrid
+`UGGrid` supports unstructured grids in both 2D and 3D. 2D grids can contain triangles and quadrilaterals, while 3D grids can include tetrahedra, hexahedra, prisms, and pyramids. Different element types can be combined in one grid. The grid dimension is a template parameter of the `UGGrid` class. Multiple `UGGrid` instances can coexist as long as memory allows. `UGGrid` supports adaptive red-green refinement and non-conforming refinement, as well as anisotropic refinement.
+
+For more information, see:<br>
+https://www.dune-project.org/modules/dune-uggrid/
+
+## Further Grid Modules
+This section should have given you an overview of the grid implementations that come with the core DUNE installation as well as some additional, regularly-used grid modules. More grid modules are presented on https://dune-project.org/groups/grid/.