External: add SimExample with two artificial sensitive detectors

A tiny, self-contained run/SimExamples entry demonstrating data-driven
injection of sensitive external detectors into o2-sim (no code compiled in):

  - ACYL : silicon barrel cylinder, DetID slot ITS, built-in action
  - BDISK: silicon endcap disk, DetID slot TST, custom JITed action

Both are instances of o2::ext::ExternalDetector producing the generic
o2::ext::Hit. Geometry is built at runtime from hand-written .macro stand-ins
for O2_CADtoTGeo.py output, so the example needs no CAD binaries. run.sh
transports a few boxgen events and inspect_hits.macro prints the per-detector
hit counts, exercising the parallel-mode hit-merger persistence path.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: sawenzel

run/SimExamples/External_Sensitive_Detectors/README.md

@@ -0,0 +1,54 @@
+# External sensitive detectors
+
+A minimal example showing how to add **sensitive** detectors to `o2-sim` without compiling
+anything into O2. Two artificial detectors are injected purely from data:
+
+| name    | geometry (runtime macro)      | DetID slot | sensitive action                |
+|---------|-------------------------------|------------|---------------------------------|
+| `ACYL`  | `geometry_innerCylinder.macro`| `ITS`      | built-in entrance/exit action   |
+| `BDISK` | `geometry_outerDisk.macro`    | `TST`      | custom action `sensitive_action.macro` |
+
+Both are instances of the single compiled `o2::ext::ExternalDetector` class and produce the
+single generic hit type `o2::ext::Hit`. They differ only in their data: geometry, the DetID
+slot they occupy, and (optionally) a sensitive-action macro.
+
+## Run
+
+```bash
+./run.sh
+```
+
+This transports a few `boxgen` events and prints the per-detector hit counts, e.g.
+
+```
+External sensitive detector hits:
+  ACYLHit                : ~430 hits over 5 events, mean radius 20.0 cm  [o2sim_HitsITS.root]
+  BDISKHit               : ~120 hits over 5 events, mean radius ...  cm  [o2sim_HitsTST.root]
+```
+
+## How it works
+
+* **Geometry** — each `"macro"` is a ROOT macro exporting `get_builder_hook_unchecked()`, the
+  same symbol `O2_CADtoTGeo.py` emits when converting CAD (STEP) files to TGeo. The macros here
+  are hand-written so the example is self-contained (no CAD binaries). The volumes whose names
+  match `"sensitiveVolumes"` are registered as sensitive.
+
+* **Sensitive action** — `ACYL` has none, so it uses the built-in action that records an
+  entrance/exit hit per track. `BDISK` points `"sensitiveMacro"` at a macro whose
+  `sensitiveAction()` returns the per-step callable; it is JIT-compiled at runtime via
+  `o2::conf::GetFromMacro` (the same mechanism as the generator / stepping hooks — no
+  recompilation, no ACLIC). The callable has the full `TVirtualMC` singleton and a few helpers
+  (`currentSensorID()`, `currentTrackID()`, `addHit()`).
+
+* **Persistence** — each detector is tied to a free **DetID** slot (`ITS`, `TST` here, chosen
+  because no real detector of that name is active). The DetID is the scarce resource: it fixes
+  the hit-file name (`o2sim_Hits<DetID>.root`) and lets the hit merger instantiate a matching
+  receiver, so hits are written in parallel multi-worker mode just like for any built-in
+  detector. The branch keeps the detector's own name (`ACYLHit`, `BDISKHit`).
+
+## Adding more detectors
+
+Append entries to `externalDetectors.json` (each on a different free DetID slot) and list their
+names in `detectorlist.json`. The mechanism is fully data-driven; nothing needs to be rebuilt.
+
+See also `Detectors/External` and `scripts/geometry/O2_CADtoTGeo.py`.

run/SimExamples/External_Sensitive_Detectors/detectorlist.json

@@ -0,0 +1,6 @@
+{
+  "EXTEXAMPLE": [
+    "ACYL",
+    "BDISK"
+  ]
+}

run/SimExamples/External_Sensitive_Detectors/externalDetectors.json

@@ -0,0 +1,23 @@
+{
+  "externalDetectors": [
+    {
+      "name": "ACYL",
+      "title": "artificial barrel cylinder - built-in entrance/exit action",
+      "macro": "geometry_innerCylinder.macro",
+      "anchor": "barrel",
+      "detID": "ITS",
+      "sensitiveVolumes": ["ACYL_SENS"],
+      "placement": { "translation": [0, 0, 0] }
+    },
+    {
+      "name": "BDISK",
+      "title": "artificial endcap disk - custom JITed sensitive action",
+      "macro": "geometry_outerDisk.macro",
+      "anchor": "barrel",
+      "detID": "TST",
+      "sensitiveVolumes": ["BDISK_SENS"],
+      "sensitiveMacro": "sensitive_action.macro",
+      "placement": { "translation": [0, 0, 0] }
+    }
+  ]
+}

run/SimExamples/External_Sensitive_Detectors/geometry_innerCylinder.macro

@@ -0,0 +1,35 @@
+// Geometry builder for the "ACYL" artificial detector: a thin silicon cylindrical shell.
+//
+// This is a hand-written stand-in for the macros that O2_CADtoTGeo.py produces from CAD
+// files. It exports the same builder-hook symbol (get_builder_hook_unchecked) that
+// o2::base::buildCADVolumeFromMacro expects, so it is injected exactly like a CAD module
+// through the external-geometry JSON. Media are placeholders here; remapCADMedia()
+// re-registers them under O2's MaterialManager at construction time.
+#include <TGeoManager.h>
+#include <TGeoTube.h>
+#include <TGeoMaterial.h>
+#include <TGeoMedium.h>
+#include <TGeoVolume.h>
+#include <functional>
+#include <stdexcept>
+
+TGeoVolume* build(bool /*check*/ = true)
+{
+  if (!gGeoManager) {
+    throw std::runtime_error("gGeoManager is null when building ACYL");
+  }
+  auto* mat = new TGeoMaterial("SiACYL", 28.0855, 14., 2.33, 9.37, 45.5);
+  double params[8] = {1., 0., 0., 0., 0., 0., 0., 0.}; // isvol=1, no field, defaults
+  auto* med = new TGeoMedium("SiACYL", 1, mat, params);
+
+  // 2 mm thick shell, R = 20 cm, half-length 40 cm
+  auto* tube = new TGeoTube("ACYL_SENS", 20.0, 20.2, 40.0);
+  auto* sens = new TGeoVolume("ACYL_SENS", tube, med);
+
+  auto* top = new TGeoVolumeAssembly("ACYL");
+  top->AddNode(sens, 1, nullptr);
+  return top;
+}
+
+std::function<TGeoVolume*()> get_builder_hook_checked() { return []() { return build(true); }; }
+std::function<TGeoVolume*()> get_builder_hook_unchecked() { return []() { return build(false); }; }

run/SimExamples/External_Sensitive_Detectors/geometry_outerDisk.macro

@@ -0,0 +1,35 @@
+// Geometry builder for the "BDISK" artificial detector: a thin silicon endcap disk.
+//
+// Hand-written stand-in for a CAD-exported macro (see geometry_innerCylinder.macro). Exports the
+// same builder-hook symbol consumed by o2::base::buildCADVolumeFromMacro. Together with ACYL
+// this gives two geometrically distinct artificial detectors (a barrel shell and an endcap
+// disk) sharing one generic o2::ext::Hit type but writing into separate DetID slots.
+#include <TGeoManager.h>
+#include <TGeoTube.h>
+#include <TGeoMaterial.h>
+#include <TGeoMedium.h>
+#include <TGeoVolume.h>
+#include <TGeoMatrix.h>
+#include <functional>
+#include <stdexcept>
+
+TGeoVolume* build(bool /*check*/ = true)
+{
+  if (!gGeoManager) {
+    throw std::runtime_error("gGeoManager is null when building BDISK");
+  }
+  auto* mat = new TGeoMaterial("SiBDISK", 28.0855, 14., 2.33, 9.37, 45.5);
+  double params[8] = {1., 0., 0., 0., 0., 0., 0., 0.}; // isvol=1, no field, defaults
+  auto* med = new TGeoMedium("SiBDISK", 1, mat, params);
+
+  // a 2 mm thick disk: inner r = 5 cm, outer r = 40 cm, placed at z = +70 cm (endcap)
+  auto* disk = new TGeoTube("BDISK_SENS", 5.0, 40.0, 0.1);
+  auto* sens = new TGeoVolume("BDISK_SENS", disk, med);
+
+  auto* top = new TGeoVolumeAssembly("BDISK");
+  top->AddNode(sens, 1, new TGeoTranslation(0., 0., 70.0));
+  return top;
+}
+
+std::function<TGeoVolume*()> get_builder_hook_checked() { return []() { return build(true); }; }
+std::function<TGeoVolume*()> get_builder_hook_unchecked() { return []() { return build(false); }; }

run/SimExamples/External_Sensitive_Detectors/inspect_hits.macro

@@ -0,0 +1,50 @@
+// Inspect the hits produced by the two artificial external detectors of this example.
+//
+// In parallel mode (o2-sim) the hit merger writes one file per detector, named after the
+// DetID slot the detector borrows: ACYL -> o2sim_HitsITS.root, BDISK -> o2sim_HitsTST.root.
+// The branch inside keeps the detector's own name: "ACYLHit" / "BDISKHit".
+//
+// Run: root -l -b -q inspect_hits.macro
+#if !defined(__CLING__) || defined(__ROOTCLING__)
+#include "ExternalDetectors/Hit.h"
+#include <TFile.h>
+#include <TTree.h>
+#include <vector>
+#include <cmath>
+#endif
+
+void inspectOne(const char* fname, const char* branch)
+{
+  auto* f = TFile::Open(fname);
+  if (!f || f->IsZombie()) {
+    printf("  %-22s : file not found (%s)\n", branch, fname);
+    return;
+  }
+  auto* t = (TTree*)f->Get("o2sim");
+  if (!t || !t->GetBranch(branch)) {
+    printf("  %-22s : no '%s' branch in %s\n", branch, branch, fname);
+    delete f;
+    return;
+  }
+  std::vector<o2::ext::Hit>* hits = nullptr;
+  t->SetBranchAddress(branch, &hits);
+  long total = 0;
+  double rsum = 0.;
+  for (Long64_t e = 0; e < t->GetEntries(); ++e) {
+    t->GetEntry(e);
+    for (auto& h : *hits) {
+      ++total;
+      rsum += std::hypot(h.GetX(), h.GetY());
+    }
+  }
+  printf("  %-22s : %ld hits over %lld events, mean radius %.1f cm  [%s]\n",
+         branch, total, t->GetEntries(), total ? rsum / total : 0., fname);
+  delete f;
+}
+
+void inspect_hits()
+{
+  printf("External sensitive detector hits:\n");
+  inspectOne("o2sim_HitsITS.root", "ACYLHit");  // barrel cylinder, built-in action
+  inspectOne("o2sim_HitsTST.root", "BDISKHit"); // endcap disk, custom JITed action
+}

run/SimExamples/External_Sensitive_Detectors/run.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+#
+# Minimal example injecting two artificial *sensitive* external detectors into o2-sim.
+#
+# Neither detector is compiled into O2: both are described purely by data. The geometry of
+# each is built at runtime from a ROOT macro (here hand-written stand-ins for what
+# O2_CADtoTGeo.py produces from CAD files), and each is tied to a free DetID slot so its hits
+# are written like those of any built-in detector -- including in parallel (multi-worker) mode,
+# where the hit merger instantiates a matching receiver per detector.
+#
+#   ACYL  : thin silicon barrel cylinder, DetID slot ITS, built-in entrance/exit action
+#   BDISK : thin silicon endcap disk,     DetID slot TST, custom JITed sensitive action
+#
+# Both share the single generic hit type o2::ext::Hit. Multiplicity is data-driven: add more
+# entries (on more free DetID slots) to externalDetectors.json and detectorlist.json.
+
+set -x
+
+# run from this example's directory so the relative macro/JSON paths resolve
+cd "$(dirname "$0")"
+
+NWORKERS=2
+EVENTS=5
+
+o2-sim -j ${NWORKERS} -n ${EVENTS} -g boxgen \
+       --detectorList EXTEXAMPLE:detectorlist.json \
+       --extGeomFile externalDetectors.json \
+       --configKeyValues 'BoxGun.number=50' \
+       > sim.log 2>&1
+
+# count and locate the produced hits (one file per detector / DetID slot)
+root -l -b -q inspect_hits.macro

run/SimExamples/External_Sensitive_Detectors/sensitive_action.macro

@@ -0,0 +1,44 @@
+// Custom sensitive action for the "BDISK" artificial detector.
+//
+// The action is JIT-compiled at runtime via o2::conf::GetFromMacro (the same mechanism used
+// for generator and stepping hooks) and fully replaces ExternalDetector's built-in
+// entrance/exit action. It runs for every MC step inside one of the detector's sensitive
+// volumes and has the full TVirtualMC singleton available, plus a few convenience helpers on
+// the detector (currentSensorID(), currentTrackID(), addHit()).
+//
+// IMPORTANT: the return type must be spelled exactly as the typedef name passed to
+// GetFromMacro ("o2::ext::ExternalDetector::SensitiveFcn"); the loader compares the function's
+// return-type name textually, so std::function<...> would not match.
+//
+// This example records a single point-like hit whenever a charged particle enters a sensitive
+// volume.
+#if !defined(__CLING__) || defined(__ROOTCLING__)
+#include "ExternalDetectors/ExternalDetector.h"
+#include "ExternalDetectors/Hit.h"
+#include <TVirtualMC.h>
+#include <TLorentzVector.h>
+#endif
+
+o2::ext::ExternalDetector::SensitiveFcn sensitiveAction()
+{
+  return [](o2::ext::ExternalDetector* det) -> bool {
+    auto vmc = TVirtualMC::GetMC();
+    if (vmc->TrackCharge() == 0) {
+      return false; // ignore neutral particles
+    }
+    if (!vmc->IsTrackEntering()) {
+      return false; // record only the entrance point
+    }
+    const int sensor = det->currentSensorID();
+    if (sensor < 0) {
+      return false; // not one of our sensitive volumes
+    }
+    TLorentzVector pos, mom;
+    vmc->TrackPosition(pos);
+    vmc->TrackMomentum(mom);
+    det->addHit(det->currentTrackID(), sensor, pos.Vect(), pos.Vect(), mom.Vect(),
+                mom.E(), pos.T(), 0. /*eLoss*/, o2::ext::Hit::kTrackEntering, o2::ext::Hit::kTrackEntering,
+                vmc->TrackPid(), vmc->TrackLength());
+    return true;
+  };
+}