Update OverlayTiming to support BIB random mixing

CMakeLists.txt

@@ -28,6 +28,7 @@ set(${PROJECT_NAME}_VERSION "${${PROJECT_NAME}_VERSION_MAJOR}.${${PROJECT_NAME}_
 
 find_package(ROOT COMPONENTS RIO Tree REQUIRED)
 find_package(Gaudi REQUIRED)
+find_package(TBB REQUIRED)
 find_package(podio 1.3 REQUIRED)
 find_package(EDM4HEP 1.0)
 if (NOT EDM4HEP_FOUND)

doc/OverlayTiming.md

@@ -33,7 +33,10 @@ It uses [`UniqueIDGenSvc`](uniqueIDGen.md) to seed the internal random number ge
 
 | Property | Default | Description |
 |----------|---------|-------------|
-| `BackgroundFileNames` | `[]` | List of groups of background input files, one group per overlay stream |
+| `BackgroundFileNames` | `[]` | List of groups of background input files, one group per overlay stream. Entries may also be directories, in which case their `.root` files are used. |
+| `RandomMixBackgroundFiles` | `false` | Treat each file in a background group as an independent pseudo-event source and pick a random file for every overlaid pseudo-event (one-event-per-file mixing) |
+| `MergeMCParticles` | `true` | Merge background MCParticles into the output. If `false`, background particles are not stored: tracker hits keep the momentum of their originating particle instead of a particle link, and calorimeter contributions get an empty particle |
+| `OverlayThreads` | `1` | Number of worker threads used to read and decompress background files within a single event (`1` = serial). Only the reading is parallelized; the merge stays serial and in-order, so the result is unchanged and deterministic. Most effective with `RandomMixBackgroundFiles` and many input files |
 | `NumberBackground` | `[]` | Number of background events to overlay per stream (fixed or Poisson mean) |
 | `Poisson_random_NOverlay` | `[]` | If true, draw the number of events from a Poisson distribution with mean `NumberBackground` |
 | `NBunchtrain` | `1` | Number of bunch crossings in the bunch train |
@@ -93,3 +96,64 @@ ApplicationMgr(
     OutputLevel=INFO,
 )
 ```
+
+## Random background mixing
+
+For setups where the background is split across a large number of files, each
+containing a single pseudo-event (e.g. Muon Collider beam-induced background), set
+`RandomMixBackgroundFiles = True`. Each file in a group is then treated as an
+independent event source, and a random number of files (set by NumberBackground)
+is chosen for every overlaid event.
+`BackgroundFileNames` entries may point at directories, whose `.root` files are
+collected automatically:
+
+```python
+overlay.RandomMixBackgroundFiles = True
+overlay.BackgroundFileNames = [["/path/to/bib_files/"]]
+```
+
+## Parallel background reading
+
+With many large background files the algorithm is dominated by reading and
+decompressing them. Set `OverlayThreads` to a value greater than 1 to read and
+decompress the background files of a single event on several threads:
+
+```python
+overlay.RandomMixBackgroundFiles = True
+overlay.OverlayThreads = 4
+```
+
+Only the reading is parallelized. The randomness (which files, how many, in
+which bunch crossing) is drawn up front, and the merging of the background hits
+into the output collections is always done serially and in the same order, so
+the result is **identical and deterministic** regardless of `OverlayThreads`.
+Because ROOT I/O is made thread-safe with `ROOT::EnableThreadSafety()`, the
+algorithm also remains safe to run under Gaudi's intra-event multithreading.
+
+The speed-up is largest when reading dominates (many large files, tight time
+windows that keep the merge cheap); when the merge is the bottleneck the gain is
+correspondingly smaller.
+
+### Interplay with the Gaudi scheduler
+
+`OverlayThreads` and the scheduler's `ThreadPoolSize` are not independent: they
+draw from the same pool of threads. `ThreadPoolSvc` sets a process-wide TBB
+`global_control` of `ThreadPoolSize + maxParallelismExtra + 1` and creates the
+task arena into which `AvalancheSchedulerSvc` enqueues every algorithm, and the
+parallel reading runs inside that same arena. This means the machine is never
+oversubscribed, but it also means:
+
+- Gaudi has no way of knowing about the extra parallelism. The scheduler counts
+  algorithms in flight, not threads, so it keeps dispatching other algorithms
+  while `OverlayTiming` is fanned out.
+- `OverlayThreads` bounds the number of background reads in flight, not the
+  number of threads actually available. With `ThreadPoolSize = 1` the arena has
+  two threads, and a large `OverlayThreads` will not buy more than that.
+
+There is currently no way for a functional algorithm to declare its internal
+parallelism to the scheduler (`Asynchronous` is the Boost.Fiber path for
+offloaded work, not this). In practice `OverlayThreads > 1` pays off when
+`ThreadPoolSize` is small -- branching out inside a single event rather than
+running many events concurrently -- and raising both just repartitions the same
+threads. If the extra threads should come on top of the scheduler's pool,
+`AvalancheSchedulerSvc.maxParallelismExtra` raises the TBB limit accordingly.

k4FWCore/CMakeLists.txt

@@ -39,7 +39,7 @@ gaudi_add_module(k4FWCorePlugins
                    components/Reader.cpp
                    components/UniqueIDGenSvc.cpp
                    components/Writer.cpp
-                 LINK Gaudi::GaudiKernel k4FWCore k4FWCore::k4Interface ROOT::Core ROOT::RIO ROOT::Tree EDM4HEP::edm4hep)
+                 LINK Gaudi::GaudiKernel k4FWCore k4FWCore::k4Interface ROOT::Core ROOT::RIO ROOT::Tree EDM4HEP::edm4hep TBB::tbb)
 
 target_include_directories(k4FWCorePlugins PUBLIC
   $<BUILD_INTERFACE:${CMAKE_CURRENT_LIST_DIR}/include>