From 77fb58c65c6e8f6cbca41e8c39d189cbd7de89d6 Mon Sep 17 00:00:00 2001
From: Patrick Jaap <patrick.jaap@wias-berlin.de>
Date: Wed, 10 Dec 2025 09:37:32 +0100
Subject: [PATCH 1/2] Add showcase examples to README

---
 README.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)

diff --git a/README.md b/README.md
index 4fae2f1e..a775f13e 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,67 @@ grids for finite element and finite volume methods.
 Used by [VoronoiFVM](https://github.com/WIAS-PDELib/VoronoiFVM.jl) and  [ExtendableFEM](https://github.com/WIAS-PDELib/ExtendableFEM.jl),
 a package for novel, gradient robust finite element methods.
 
+
+## Showcase
+
+### Create a grid and discover basic adjacencies
+
+```julia
+using ExtendableGrids
+
+# create a 3D unit cube made of tetrahedra
+unitcube = grid_unitcube(Tetrahedron3D)
+
+@show num_cells(unitcube) # = 6 (the unit cube consists of 6 tetrahedra)
+@show num_nodes(unitcube) # = 8 (the unit cube has 8 corners)
+
+cellnodes = unitcube[CellNodes]  # this is the mapping cell index -> node indices
+typeof(cellnodes) <: Matrix # true: each cell (tetrahedron!) has 4 nodes:
+                            # store mapping as a matrix!
+
+@show cellnodes[: , 2] # = [1,3,4,7], the nodes of the second cell
+
+# create a 2D unit square made of triangles
+unitsquare = grid_unitsquare(Triangle2D)
+
+nodecells = unitsquare[NodeCells] # the node index -> cell indices mapping
+typeof(cellnodes) <: Matrix # false!
+                            # each node has a different number of adjacent cells:
+                            # stored as `VariableTargetAdjacency`
+
+@show nodecells[: , 2] # = [1,2]
+@show nodecells[: , 5] # = [1,2,3,4] # (center node)
+```
+Other adjacency mappings are constructed by combining grid components, see [Notations](https://wias-pdelib.github.io/ExtendableGrids.jl/stable/extendablegrid/#Notations).
+
+### Grid data and plotting
+
+```julia
+using ExtendableGrids
+
+unitsquare = grid_unitsquare(Triangle2D)
+
+coords = unitsquare[Coordinates] # matrix of all node coordinates
+@show coords[: , 5]              # = [ 0.5, 0.5 ] (center node)
+
+regions = unitsquare[CellRegions] # mapping cell index -> region number
+@show all( ==(1), regions)        # in this grid, all cell regions are = 1
+
+ # mapping boundary face index -> boundary region number
+bfaceregions = unitsquare[BFaceRegions]
+@show bfaceregions # = [1,2,3,4], the four boundary regions are labeled by 1,2,3,4
+
+# Plotting is done via GridVisualize.jl and a Plotter (PythonPlot.jl,
+# GLMakie.jl, Plutovista.jl, ...)
+using GridVisualize, PythonPlot
+gridplot(unitsquare, Plotter=PythonPlot) # this opens a window with a plot
+```
+
+Example plots are shown in [GridVisualize.jl](https://wias-pdelib.github.io/GridVisualize.jl/stable/script_examples/plotting/#2D-grids).
+
+
+
+
 ## Additional functionality:
 
 

From 7aa9f64be9b9236714bef90c44e768b381dfeeae Mon Sep 17 00:00:00 2001
From: Patrick Jaap <patrick.jaap@wias-berlin.de>
Date: Wed, 10 Dec 2025 12:47:22 +0100
Subject: [PATCH 2/2] Add some examples in README

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index a775f13e..b9b5c1bc 100644
--- a/README.md
+++ b/README.md
@@ -42,7 +42,7 @@ typeof(cellnodes) <: Matrix # false!
 @show nodecells[: , 2] # = [1,2]
 @show nodecells[: , 5] # = [1,2,3,4] # (center node)
 ```
-Other adjacency mappings are constructed by combining grid components, see [Notations](https://wias-pdelib.github.io/ExtendableGrids.jl/stable/extendablegrid/#Notations).
+Other adjacency mappings are constructed by combining grid components, see [Notations](https://wias-pdelib.github.io/ExtendableGrids.jl/stable/extendablegrid/#Notations). For example `FaceCells`, `BFaceNodes`, `NodeEdges`, ...
 
 ### Grid data and plotting