Rework the DD4hep and Gaudi tutorials

.gitignore

@@ -248,6 +248,14 @@ test/k4FWCoreTest/**/*.root
 test/inputFiles/*.slcio
 test/gaudi_opts/testConverterConstants.py
 
-# Files produced during running examples
-*root
-*png
+# Files produced during running examples. Anchored on the dot so that names that
+# merely end in "root" or "png" (and directories called root/) stay tracked.
+*.root
+*.png
+
+# Small deterministic input that keeps the EDM4hep notebook runnable after a fresh clone.
+!DD4hepTutorials/data/
+!DD4hepTutorials/data/simplecalo2_sample.root
+
+# geoWebDisplay writes this next to the geometry it is showing.
+viewer.cxx

.pre-commit-config.yaml

@@ -36,4 +36,4 @@ repos:
         "-o", "Key4hep-Project",
         "-n", "Key4hep",
         "-u", "https://key4hep.github.io/key4hep-doc/",
-        "-x", ".github/*", ".pre-commit-config.yaml", "README.md", "doc/ReleaseNotes.md", "*.xml", "-f"]
+        "-x", ".github/*", ".pre-commit-config.yaml", "README.md", "doc/ReleaseNotes.md", "*.xml", "*.ipynb", "-f"]

CMakeLists.txt

@@ -18,6 +18,11 @@ limitations under the License.
 ]]
 CMAKE_MINIMUM_REQUIRED(VERSION 3.12)
 
+# DD4hep 1.36 still uses CMake's FindBoost module. Keep that compatibility
+# mode explicitly on CMake 3.30+ instead of emitting a CMP0167 developer warning.
+if(POLICY CMP0167)
+  cmake_policy(SET CMP0167 OLD)
+endif()
 
 project(SoftwareTutorials LANGUAGES CXX)
 

DD4hepTutorials/CMakeLists.txt

@@ -17,6 +17,12 @@ See the License for the specific language governing permissions and
 limitations under the License.
 ]]
 CMAKE_MINIMUM_REQUIRED(VERSION 3.12)
+
+# DD4hep 1.36 still relies on CMake's legacy FindBoost compatibility mode.
+if(POLICY CMP0167)
+  cmake_policy(SET CMP0167 OLD)
+endif()
+
 project(DD4hepTutorials)
 
 include(GNUInstallDirs)

DD4hepTutorials/README.md

@@ -18,17 +18,88 @@ limitations under the License.
 -->
 # DD4hepTutorials for DRDCalo
 
-Welcome to the DD4hep Tutorials of DRDCalo repository!
+Hands-on exercises for DD4hep, a detector description framework:
 
-This repository contains hands-on exercises to help you learn DD4hep, a powerful detector description framework. The exercises are organized into separate folders:
+ - **simplecalo1**: the fundamentals, by building a simplified calorimeter.
+ - **simplecalo2**: a custom Geant4 sensitive detector on top of it.
 
- - **simplecalo1**: Learn the fundamentals of DD4hep by building your first simplified calorimeter.
- - **simplecalo2**: Build on simplecalo1 and explore how to set up a custom Geant4 Sensitive Detector.
-
-For instructions on **simplecalo1** and **simplecalo2** follow [this presentation](https://indico.cern.ch/event/1618975/sessions/635708/attachments/3252510/5805581/DRDCaloDD4hepTutorial_April2026.pdf).
+Follow [this presentation](https://indico.cern.ch/event/1618975/sessions/635708/attachments/3252510/5805581/DRDCaloDD4hepTutorial_April2026.pdf) for both.
 
 ## Previous editions of this tutorial
 - April 2026, DRDCalo Collaboration Meeting [presentation](https://indico.cern.ch/event/1618975/sessions/635708/attachments/3252510/5805581/DRDCaloDD4hepTutorial_April2026.pdf)
 - April 2025, DRDCalo Collaboration Meeting [presentation](https://indico.ijclab.in2p3.fr/event/11400/sessions/5873/attachments/25413/37372/DRD6DD4hepTutorial_April2025.pdf)
 
+## Analysing the output
+
+| What | Notebook |
+|---|---|
+| Section 1: cell energy sum, Gaussian fit, energy resolution | `notebooks/plot_cell_energy_sum.ipynb` |
+| Hands-on 6: hits, layers, lateral shape, contributions | `notebooks/readEdm4hep.ipynb` |
+
+Hands-on 6 has six questions to complete; the finished version sits next to it as
+`notebooks/readEdm4hepSolution.ipynb`.
+
+Each notebook prefers the full simulation — `simplecalo1.root` and `simplecalo2.root`, which the
+steering files always write into this directory whatever directory `ddsim` was launched from —
+and otherwise falls back to the bundled 10-event `data/simplecalo2_sample.root`, saying so when
+it does. `SIMPLECALO1_FILE` and `SIMPLECALO2_FILE` override the choice; the rules live in
+`python/drdcalo_tutorials/__init__.py`.
+
+Hands-on 6 reads the cell size and grid dimensions out of `simplecalo2/compact/simplecalo2.xml`,
+the same constants `sc2_solution1.h` places the cells from, so changing `CellX` and re-running
+`ddsim` needs no code edit. Its last cell checks a decoded cell index against the stored hit
+position, which catches an input file produced before the geometry was changed.
+
+### Running the notebooks
+
+Open `SoftwareTutorials` itself as the VS Code workspace folder — not a parent directory — then
+**Select Kernel** → **Python Environments** → `.venv/bin/python`. VS Code applies
+`${workspaceFolder}/.env`, which `setup.sh` fills with the key4hep runtime. A `No module named
+'awkward'` error means it did not, almost always because the workspace folder is a level too
+high; see the main README.
+
+For JupyterLab instead, run `jupyter lab --no-browser --port 8888` from a shell that has sourced
+`setup.sh`, and forward that port.
+
+## Viewing the geometry
+
+`geoWebDisplay simplecalo1/compact/simplecalo1.xml` starts a web server and asks the operating
+system to open a browser. On a remote machine that launch usually fails silently — the server is
+still running, on the port it printed:
+
+```
+Info in <THttpEngine::Create>: Starting HTTP server on port 127.0.0.1:9427
+```
+
+Leave the `root [0]` prompt open, since quitting it stops the server, and forward that port to
+your own machine — either through the VS Code **PORTS** panel, or:
+
+``` bash
+# on your laptop. Use the exact node name: lxplus.cern.ch is load balanced and would
+# send you to a different machine, where nothing is listening.
+ssh -N -L 9427:127.0.0.1:9427 <user>@lxplus8sXX.cern.ch
+```
+
+Then browse to **<http://localhost:9427/win1/>**. The `/win1/` matters: ROOT serves each GUI panel
+as a separate named window, so the bare URL returns *404*. `/win2/` is the volume hierarchy
+browser, useful on its own during Hands-on 1 and 2.
+
+> ROOT also appends a single-use key to the URL and hands it only to the browser it launches
+> itself, so a typed address returns *404* as well. To type one, put `WebGui.OnetimeKey: no` into
+> a `.rootrc` in the directory you start `geoWebDisplay` from.
+
+`geoWebDisplay` also drops a `viewer.cxx` in the current directory; it is a ROOT by-product,
+ignored by git, and can be deleted.
+
+### Without port forwarding
+
+Export the geometry and look at it locally:
+
+``` bash
+geoConverter -compact2tgeo -input simplecalo1/compact/simplecalo1.xml -output simplecalo1_geo.root
+# or -compact2gdml for a GDML file
+```
+
+Open the result in ROOT, or drag it onto <https://root.cern/js/>.
+
 Happy coding! :rocket:

DD4hepTutorials/data/README.md

@@ -0,0 +1,59 @@
+<!--
+Copyright (c) 2020-2024 Key4hep-Project.
+
+This file is part of Key4hep.
+See https://key4hep.github.io/key4hep-doc/ for further info.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+# Bundled EDM4hep sample
+
+`simplecalo2_sample.root` is a deterministic 10-event input shared by the DD4hep analysis tools
+and the Gaudi exercises. It contains `EventHeader`, `MCParticles`, `simplecaloRO`, and
+`simplecaloROContributions` and was generated with the completed simplecalo2 geometry using
+key4hep release `2026-04-08` and random seed `12345`.
+
+All lengths are in **mm** and all times in **ns**, as EDM4hep specifies: `simplecaloRO.position`
+is the centre of the cell, `simplecaloROContributions.stepPosition` the position of the
+individual Geant4 step that contributed. Energies are in GeV for hits and contributions.
+
+The small sample lets the notebook run after a fresh clone. It is not intended to replace the
+full 500-event simulation when producing statistically meaningful plots — the notebooks say so
+out loud when they fall back to it. After completing the cell-placement exercise, regenerate a
+full `DD4hepTutorials/simplecalo2.root` with:
+
+```bash
+ddsim --steeringFile DD4hepTutorials/simplecalo2/sc2SteeringFile.py
+```
+
+The steering file names both its compact file and its output relative to itself, so the command
+above works from any directory and always writes `DD4hepTutorials/simplecalo2.root`, which is
+where the notebooks look. Pass `--outputFile` to put it somewhere else, and point the notebooks
+at it with `SIMPLECALO2_FILE`.
+
+To reproduce the bundled fixture after enabling the completed cell-placement implementation:
+
+```bash
+ddsim --steeringFile DD4hepTutorials/simplecalo2/sc2SteeringFile.py \
+  --numberOfEvents 10 \
+  --outputFile DD4hepTutorials/data/simplecalo2_sample.root \
+  --random.seed 12345 \
+  --random.enableEventSeed
+```
+
+The geometry it was produced with is the one in `simplecalo2/compact/simplecalo2.xml` at the time:
+10 x 10 cells of 10 cm. Change `CellX` there and this file no longer matches — the last cell of
+`readEdm4hepSolution.ipynb` compares a decoded cell index against the stored hit position and will
+say so.
+
+SHA-256: `a4faa81b48a13e48f4363224e039c41f949d3452acdd223ebaba61b9f1b672b2`