Passive: inject external (CAD) geometry modules from JSON config

Make external geometry modules configurable from the outside instead of
hardcoding them in build_geometry.C. Adds:

- ExternalModule::createFromJSON(): builds a list of external passive
  modules from a JSON file ("externalModules" array of {name, macro,
  anchor, optional placement{translation, rotation_deg}}).
- SimConfig: new --extGeomFile option, carried through SimConfigData and
  exposed via getExtGeomFilename().
- build_geometry.C: replaces the single hardcoded EXT block with a loop
  that adds every external module whose name is in the active module list.

Also fixes a blocker for running several external modules at once: every
geom.C produced by O2_CADtoTGeo.py exports identical symbols
(build(), get_builder_hook_unchecked(), ...). Loading them all into the
single global Cling scope made the first definition win and silently
ignored later macros. initGeomBuilderHook() now JITs each macro into a
unique per-instance namespace (hoisting #include lines to global scope),
so multiple CAD modules coexist.

Tested with o2-sim-serial -n 1 injecting two CAD detectors (oTOF and IRIS,
the latter with materials from a BOM CSV) simultaneously.

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

Author: sawenzel

Common/SimConfig/include/SimConfig/SimConfig.h

@@ -88,8 +88,9 @@ struct SimConfigData {
   bool mForwardKine = false;                          // true if tracks and event headers are to be published on a FairMQ channel (for reading by other consumers)
   bool mWriteToDisc = true;                           // whether we write simulation products (kine, hits) to disc
   VertexMode mVertexMode = VertexMode::kDiamondParam; // by default we should use die InteractionDiamond parameter
+  std::string mExtGeomFile = "";                      // optional path to a JSON file describing external (CAD) geometry modules to inject
 
-  ClassDefNV(SimConfigData, 4);
+  ClassDefNV(SimConfigData, 5);
 };
 
 // A singleton class which can be used
@@ -178,6 +179,7 @@ class SimConfig
   bool forwardKine() const { return mConfigData.mForwardKine; }
   bool writeToDisc() const { return mConfigData.mWriteToDisc; }
   VertexMode getVertexMode() const { return mConfigData.mVertexMode; }
+  std::string getExtGeomFilename() const { return mConfigData.mExtGeomFile; }
 
   // returns the pair of collision context filename as well as event prefix encoded
   // in the mFromCollisionContext string. Returns empty string if information is not available or set.

Common/SimConfig/src/SimConfig.cxx

@@ -75,7 +75,8 @@ void SimConfig::initOptions(boost::program_options::options_description& options
     "asservice", bpo::value<bool>()->default_value(false), "run in service/server mode")(
     "noGeant", bpo::bool_switch(), "prohibits any Geant transport/physics (by using tight cuts)")(
     "forwardKine", bpo::bool_switch(), "forward kinematics on a FairMQ channel")(
-    "noDiscOutput", bpo::bool_switch(), "switch off writing sim results to disc (useful in combination with forwardKine)");
+    "noDiscOutput", bpo::bool_switch(), "switch off writing sim results to disc (useful in combination with forwardKine)")(
+    "extGeomFile", bpo::value<std::string>()->default_value(""), "Path to a JSON file describing external (CAD) geometry modules to inject (see Detectors/Passive ExternalModule). Modules are added when their 'name' is part of the active module list.");
   options.add_options()("fromCollContext", bpo::value<std::string>()->default_value(""), "Use a pregenerated collision context to infer number of events to simulate, how to embedd them, the vertex position etc. Takes precedence of other options such as \"--nEvents\". The format is COLLISIONCONTEXTFILE.root[:SIGNALNAME] where SIGNALNAME is the event part in the context which is relevant.");
 }
 
@@ -354,6 +355,7 @@ bool SimConfig::resetFromParsedMap(boost::program_options::variables_map const&
   if (vm.count("noemptyevents")) {
     mConfigData.mFilterNoHitEvents = true;
   }
+  mConfigData.mExtGeomFile = vm["extGeomFile"].as<std::string>();
   mConfigData.mFromCollisionContext = vm["fromCollContext"].as<std::string>();
   auto collcontext_simprefix = getCollContextFilenameAndEventPrefix();
   adjustFromCollContext(collcontext_simprefix.first, collcontext_simprefix.second);

Detectors/Passive/CMakeLists.txt

@@ -24,7 +24,8 @@ o2_add_library(DetectorsPassive
                        src/HallSimParam.cxx
                        src/PassiveBase.cxx
                        src/ExternalModule.cxx
-               PUBLIC_LINK_LIBRARIES O2::Field O2::DetectorsBase O2::SimConfig)
+               PUBLIC_LINK_LIBRARIES O2::Field O2::DetectorsBase O2::SimConfig
+                                     RapidJSON::RapidJSON)
 
 o2_target_root_dictionary(DetectorsPassive
                           HEADERS include/DetectorsPassive/Absorber.h

Detectors/Passive/include/DetectorsPassive/ExternalModule.h

@@ -14,6 +14,8 @@
 
 #include "DetectorsPassive/PassiveBase.h" // base class of passive modules
 #include "Rtypes.h"                       // for Pipe::Class, ClassDef, Pipe::Streamer
+#include <string>
+#include <vector>
 
 class TGeoVolume;
 class TGeoTransformation;
@@ -41,6 +43,13 @@ class ExternalModule : public PassiveBase
   ~ExternalModule() override = default;
   void ConstructGeometry() override;
 
+  /// Build a list of external (passive) modules from a JSON description file.
+  /// The file must contain an "externalModules" array; each entry needs at least
+  /// "name", "macro" and "anchor"; an optional "placement" object may carry
+  /// "translation":[x,y,z] (cm) and "rotation_deg":[rx,ry,rz] (degrees).
+  /// Ownership of the returned modules is transferred to the caller.
+  static std::vector<ExternalModule*> createFromJSON(const std::string& jsonfile);
+
   /// Clone this object (used in MT mode only)
   FairModule* CloneModule() const override { return nullptr; }
 

Detectors/Passive/src/ExternalModule.cxx

@@ -14,14 +14,25 @@
 #include <DetectorsPassive/ExternalModule.h>
 #include <CommonUtils/ConfigurationMacroHelper.h>
 #include <filesystem>
+#include <fstream>
+#include <atomic>
+#include <cctype>
 #include <CommonUtils/FileSystemUtils.h>
 #include <TGeoManager.h>
 #include <TGeoVolume.h>
+#include <TGeoMatrix.h>
+#include <TInterpreter.h>
+#include <TROOT.h>
+#include <TString.h>
+#include <TGlobal.h>
 #include <unordered_map>
 #include <unordered_set>
 #include <TGeoMaterial.h>
 #include <TGeoMedium.h>
 #include <DetectorsBase/MaterialManager.h>
+#include <rapidjson/document.h>
+#include <rapidjson/error/en.h>
+#include <rapidjson/istreamwrapper.h>
 
 // ClassImp(o2::passive::ExternalModule)
 
@@ -157,19 +168,163 @@ void ExternalModule::ConstructGeometry()
   anchor->AddNode(const_cast<TGeoVolume*>(module_top), 1, const_cast<TGeoMatrix*>(mOptions.placement));
 }
 
+namespace
+{
+// Build a TGeoCombiTrans from an optional JSON "placement" object carrying
+// "translation":[x,y,z] (cm) and/or "rotation_deg":[rx,ry,rz] (deg, applied X,Y,Z).
+TGeoMatrix* makePlacementFromJSON(const rapidjson::Value& placement)
+{
+  auto combi = new TGeoCombiTrans();
+  if (placement.HasMember("rotation_deg") && placement["rotation_deg"].IsArray()) {
+    const auto& r = placement["rotation_deg"];
+    if (r.Size() == 3) {
+      combi->RotateX(r[0].GetDouble());
+      combi->RotateY(r[1].GetDouble());
+      combi->RotateZ(r[2].GetDouble());
+    } else {
+      LOG(warning) << "ExternalModule placement 'rotation_deg' must have 3 entries; ignoring";
+    }
+  }
+  if (placement.HasMember("translation") && placement["translation"].IsArray()) {
+    const auto& t = placement["translation"];
+    if (t.Size() == 3) {
+      combi->SetDx(t[0].GetDouble());
+      combi->SetDy(t[1].GetDouble());
+      combi->SetDz(t[2].GetDouble());
+    } else {
+      LOG(warning) << "ExternalModule placement 'translation' must have 3 entries; ignoring";
+    }
+  }
+  return combi;
+}
+} // namespace
+
+std::vector<ExternalModule*> ExternalModule::createFromJSON(const std::string& jsonfile)
+{
+  std::vector<ExternalModule*> result;
+
+  auto expanded = o2::utils::expandShellVarsInFileName(jsonfile);
+  std::ifstream fileStream(expanded, std::ios::in);
+  if (!fileStream.is_open()) {
+    LOG(error) << "Cannot open external geometry config file '" << expanded << "'";
+    return result;
+  }
+
+  rapidjson::IStreamWrapper isw(fileStream);
+  rapidjson::Document doc;
+  doc.ParseStream(isw);
+  if (doc.HasParseError()) {
+    LOG(error) << "Error parsing external geometry JSON '" << expanded << "': "
+               << rapidjson::GetParseError_En(doc.GetParseError())
+               << " (offset " << doc.GetErrorOffset() << ")";
+    return result;
+  }
+  if (!doc.HasMember("externalModules") || !doc["externalModules"].IsArray()) {
+    LOG(error) << "External geometry JSON '" << expanded << "' must contain an 'externalModules' array";
+    return result;
+  }
+
+  auto getString = [](const rapidjson::Value& v, const char* key) -> std::string {
+    if (v.HasMember(key) && v[key].IsString()) {
+      return v[key].GetString();
+    }
+    return std::string();
+  };
+
+  for (const auto& entry : doc["externalModules"].GetArray()) {
+    if (!entry.IsObject()) {
+      LOG(error) << "Skipping non-object entry in 'externalModules'";
+      continue;
+    }
+    const auto name = getString(entry, "name");
+    if (name.empty()) {
+      LOG(error) << "Skipping external module entry without 'name'";
+      continue;
+    }
+    ExternalModuleOptions options;
+    options.root_macro_file = getString(entry, "macro");
+    options.anchor_volume = getString(entry, "anchor");
+    if (options.root_macro_file.empty() || options.anchor_volume.empty()) {
+      LOG(error) << "External module '" << name << "' requires both 'macro' and 'anchor'; skipping";
+      continue;
+    }
+    if (entry.HasMember("placement") && entry["placement"].IsObject()) {
+      options.placement = makePlacementFromJSON(entry["placement"]);
+    }
+    auto title = getString(entry, "title");
+    if (title.empty()) {
+      title = name;
+    }
+    LOG(info) << "Configured external module '" << name << "' from macro '" << options.root_macro_file
+              << "' anchored to volume '" << options.anchor_volume << "'";
+    result.push_back(new ExternalModule(name.c_str(), title.c_str(), options));
+  }
+  return result;
+}
+
 bool ExternalModule::initGeomBuilderHook()
 {
-  if (mOptions.root_macro_file.size() > 0) {
-    LOG(info) << "Initializing the hook for geometry module building";
-    auto expandedHookFileName = o2::utils::expandShellVarsInFileName(mOptions.root_macro_file);
-    if (std::filesystem::exists(expandedHookFileName)) {
-      // if this file exists we will compile the hook on the fly (the last one is an identifier --> maybe make it dependent on this class)
-      mGeomHook = o2::conf::GetFromMacro<GeomBuilderFcn>(mOptions.root_macro_file, "get_builder_hook_unchecked()", "function<TGeoVolume*()>", "o2_passive_extmodule_builder");
-      LOG(info) << "Hook initialized from file " << expandedHookFileName;
-      return true;
+  if (mOptions.root_macro_file.empty()) {
+    return false;
+  }
+  LOG(info) << "Initializing the hook for geometry module building";
+  auto expandedHookFileName = o2::utils::expandShellVarsInFileName(mOptions.root_macro_file);
+  if (!std::filesystem::exists(expandedHookFileName)) {
+    LOG(error) << "External geometry macro " << expandedHookFileName << " does not exist";
+    return false;
+  }
+
+  // We JIT the macro into a *unique* namespace per module instance. This is essential
+  // when several external modules are present at the same time: every macro produced by
+  // O2_CADtoTGeo.py exports identically named symbols (build(), get_builder_hook_unchecked(),
+  // LoadFacets(), ...). Loading them all into the single global Cling scope would collide
+  // (the first definition wins and subsequent macros are silently ignored). By wrapping each
+  // macro body in its own namespace we keep the symbols separate. The preprocessor #include
+  // lines must stay at global scope, so we hoist them out of the namespace.
+  std::ifstream macroStream(expandedHookFileName, std::ios::in);
+  if (!macroStream.is_open()) {
+    LOG(error) << "Cannot open external geometry macro " << expandedHookFileName;
+    return false;
+  }
+  std::string preamble; // #include (and other top-level preprocessor) lines -> global scope
+  std::string body;     // everything else -> wrapped into a unique namespace
+  std::string line;
+  while (std::getline(macroStream, line)) {
+    auto firstNonSpace = line.find_first_not_of(" \t");
+    if (firstNonSpace != std::string::npos && line[firstNonSpace] == '#') {
+      preamble += line + "\n";
+    } else {
+      body += line + "\n";
+    }
+  }
+
+  // build a unique, valid C++ identifier for the namespace
+  static std::atomic<int> instanceCounter{0};
+  std::string ns = std::string("o2_ext_") + GetName() + "_" + std::to_string(instanceCounter++);
+  for (auto& c : ns) {
+    if (!std::isalnum(static_cast<unsigned char>(c)) && c != '_') {
+      c = '_';
     }
   }
-  return false;
+
+  const std::string wrapped = preamble + "\nnamespace " + ns + " {\n" + body + "\n}\n";
+  if (!gInterpreter->Declare(wrapped.c_str())) {
+    LOG(error) << "Failed to JIT external geometry macro " << expandedHookFileName;
+    return false;
+  }
+
+  // retrieve the builder hook from the unique namespace
+  const std::string globalName = "__" + ns + "_hook__";
+  gROOT->ProcessLine(Form("std::function<TGeoVolume*()> %s = %s::get_builder_hook_unchecked();",
+                          globalName.c_str(), ns.c_str()));
+  auto global = gROOT->GetGlobal(globalName.c_str());
+  if (!global) {
+    LOG(error) << "Could not retrieve geometry builder hook from macro " << expandedHookFileName;
+    return false;
+  }
+  mGeomHook = *reinterpret_cast<GeomBuilderFcn*>(global->GetAddress());
+  LOG(info) << "Hook initialized from file " << expandedHookFileName << " (namespace " << ns << ")";
+  return true;
 }
 
 } // namespace o2::passive

macro/build_geometry.C

@@ -184,16 +184,18 @@ void build_geometry(FairRunSim* run = nullptr)
   }
 #endif
 
-  if (isActivated("EXT")) {
-    // EXAMPLE!! how to pick geometry generated from external (CAD) module via `O2_CADtoTGeo.py`
-    o2::passive::ExternalModuleOptions options;
-    options.root_macro_file = "PATH_TO_EXTERNAL_GEOM_MODULE/geom.C";
-    options.anchor_volume = "barrel"; // hook this into barrel
-    auto rot = new TGeoCombiTrans();
-    rot->RotateX(90);
-    rot->SetDy(30); // we need to compensate for a shift of barrel with respect to zero
-    options.placement = rot;
-    run->AddModule(new o2::passive::ExternalModule("FOO", "BAR", options));
+  // external (e.g. CAD-derived) geometry modules are injected from the outside via a JSON
+  // description file given with `--extGeomFile` (geometry generated via `O2_CADtoTGeo.py`).
+  // Each module is added when its 'name' is part of the active module list (so it can be
+  // switched on/off via the detector list, like any other module).
+  if (auto extGeomFile = confref.getExtGeomFilename(); !extGeomFile.empty()) {
+    for (auto* extmod : o2::passive::ExternalModule::createFromJSON(extGeomFile)) {
+      if (isActivated(extmod->GetName())) {
+        run->AddModule(extmod);
+      } else {
+        delete extmod; // not requested in the active module list
+      }
+    }
   }
 
   // the absorber