From fa953baac92008d15728e273af57209a75c07873 Mon Sep 17 00:00:00 2001
From: Frederik Hennig <frederik.hennig@fau.de>
Date: Fri, 28 Mar 2025 09:08:48 +0100
Subject: [PATCH] add symbolic geometry functions to docs

---
 user_manual/CMakeSetup/CMakeSetup.md          | 18 +----
 user_manual/index.md                          |  1 +
 .../reference/PystencilsLanguageExtensions.md | 78 +++++++++++++++++++
 3 files changed, 80 insertions(+), 17 deletions(-)
 create mode 100644 user_manual/reference/PystencilsLanguageExtensions.md

diff --git a/user_manual/CMakeSetup/CMakeSetup.md b/user_manual/CMakeSetup/CMakeSetup.md
index d4ce0d3..ef5f1fc 100644
--- a/user_manual/CMakeSetup/CMakeSetup.md
+++ b/user_manual/CMakeSetup/CMakeSetup.md
@@ -43,7 +43,7 @@ Now, you can run `cmake` to configure your build system:
 
 ```bash
 mkdir build
-cmake -S . -B build -DWALBERLA_CODEGEN_PRIVATE_VENV=ON
+cmake -S . -B build
 ```
 
 If, near the end of the long configuration log, you see two messages like this:
@@ -55,19 +55,3 @@ If, near the end of the long configuration log, you see two messages like this:
 
 Then your build system setup was successful!
 Now you can get down to business and populate your project with simulation applications.
-
-(adding_examples)=
-## Adding Examples from this Manual
-
-As you explore the examples in this book,
-you can try out each by downloading, extracting, and including them into your project.
-For example, to include the [force-driven poiseulle channel example](#ForceDrivenChannel),
-extract its code into the `ForceDrivenChannel` subdirectory and add
-
-```CMake
-add_subdirectory( ForceDrivenChannel )
-```
-
-to your root `CMakeLists.txt`.
-
-[FetchContent]: https://cmake.org/cmake/help/latest/module/FetchContent.html
diff --git a/user_manual/index.md b/user_manual/index.md
index 20dee50..21a0e11 100644
--- a/user_manual/index.md
+++ b/user_manual/index.md
@@ -38,6 +38,7 @@ examples/ForceDrivenChannel/ForceDrivenChannel
 :caption: Reference
 :maxdepth: 1
 
+reference/PystencilsLanguageExtensions
 reference/PythonEnvironment
 :::
 
diff --git a/user_manual/reference/PystencilsLanguageExtensions.md b/user_manual/reference/PystencilsLanguageExtensions.md
new file mode 100644
index 0000000..df1d863
--- /dev/null
+++ b/user_manual/reference/PystencilsLanguageExtensions.md
@@ -0,0 +1,78 @@
+# Extensions to the pystencils Language
+
+The waLBerla code generator provides several extensions to the symbolic
+language of pystencils, representing waLBerla-specific features and modelling aspects.
+These are available through the `walberla.codegen.symbolic` module.
+
+## Blockforest, Block, and Cell Geometry
+
+WaLBerla's blockforest comprises a hierarchy of geometry-defining objects:
+The global simulation domain, which has one or more refinement levels,
+each home to a set of blocks, which in turn define a grid of cells.
+Many of these geometric properties are modelled as symbolic functions
+and therefore accessible to kernels.
+As Sweep kernels are always defined with respect to a single archetypical cell,
+these symbolic functions always relate to that cell and its parent block.
+
+The following tables lists the available symbolic functions,
+the geometric concept they represent,
+as well as equivalent methods of the waLBerla C++ API.
+All Python APIs are listed relative to `walberla.codegen.symbolic`.
+
+### Domain Geometry
+
+:::{list-table}
+:header-rows: 1
+:widths: auto
+
+*   - Concept
+    - Symbolic Functions
+    - C++ API
+*   - Domain Axis-Aligned Bounding Box
+    - `domain.[xyz]_min()`, `domain.[xyz]_max()`
+    - `StructuredBlockForest::getDomain()`
+*   - Domain Cell Bounding Box (Current Refinement Level)
+    - `domain_cell_bb.[xyz]_min()`, `domain_cell_bb.[xyz]_max()`
+    - `StructuredBlockStorage::getDomainCellBB()`
+:::
+
+### Block Geometry
+
+:::{list-table}
+:header-rows: 1
+:widths: auto
+
+*   - Concept
+    - Symbolic Functions
+    - C++ API
+*   - Block Cell Bounding Box
+    - `block_cell_bb.[x|y|z]_min()`, `block_cell_bb.[x|y|z]_max()`
+    - `StructuredBlockForest::getBlockCellBB()`
+:::
+
+
+### Cell Geometry
+
+:::{list-table}
+:header-rows: 1
+:widths: auto
+
+*   - Concept
+    - Symbolic Functions
+    - C++ API
+*   - Cell Center Coordinates in Global Coordinate System
+    - `cell.[x|y|z]()`
+    - `StructuredBlockForest::getBlockLocalCellCenter()`
+*   - Cell Center Coordinates in Block-Local Coordinate System
+    - `cell.local_[x|y|z]()`
+    - *No Equivalent*
+*   - Cell Spacing
+    - `cell.[dx|dy|dz]()`
+    - `StructuredBlockForest::[dx|dy|dz]()`
+*   - Cell Index in the Global Cell Grid
+    - `cell_index.[x|y|z]_global()`
+    - `StructuredBlockForest::transformBlockLocalToGlobalCell()`
+*   - Cell Index in the Block-Local Cell Grid
+    - `cell_index.[x|y|z]_local()`
+    - `StructuredBlockForest::transformGlobalToBlockLocalCell()`
+:::
-- 
GitLab