[df] Add example on thread-safe usage of RNGs

Using only one random number generator in an application running with ROOT::EnableImplicitMT() is a common pitfall. This may introduce race conditions that are not trivial to understand for the user.

This commit introduces an example of using random number generators in an RDataFrame computation graph in a parallel and thread-safe way. Two strategies are exemplified:

* Generating non-deterministic random numbers by using one generator per RDataFrame slot. In this case, different RDataFrame runs may produce different results.
* Generating deterministic random numbers by using one generator per RDataFrame slot and then using a unique identifier per entry to seed the generator. In this case, different RDataFrame runs produce the same results. This example assumes that there is such unique identifier: it must either come from the dataset or it must be generated somehow by RDataFrame. The example shows the usage of the 'rdfentry_' column, which in the case of the RDataFrame constructor taking one integer number will represent a truly unique identifier (i.e. a different entry will have a different, unique value of 'rdfentry_' irrespective of how many slots are present and running). This would not work at the moment instead with any other RDataFrame constructor.

As a note on the implementation: another possible way to implement the examples above would have been by instantiating 'thread_local' generators and seed them appropriately. This is not possible because cling does not work well with 'static' and 'thread_local' keywords in JITted code, so we choose to demonstrate the approach with the RDataFrame slots.

Co-authored-by: Vincenzo Eduardo Padulano <vincenzo.eduardo.padulano@cern.ch>

Author: dudarboh

tutorials/analysis/dataframe/df041_ThreadSafeRNG.C

@@ -0,0 +1,86 @@
+/// \file
+/// \ingroup tutorial_dataframe
+/// \notebook -nodraw
+/// Usage of multithreading mode with random generators.
+///
+/// This example illustrates how to define functions that generate random numbers and use them in an RDataFrame
+/// computation graph in a thread-safe way.
+///
+/// Using only one random number generator in an application running with ROOT::EnableImplicitMT() is a common pitfall.
+/// This pitfall creates race conditions resulting in a distorted random distribution. In the example, this issue is
+/// solved by creating one random number generator per RDataFrame processing slot, thus allowing for parallel and
+/// thread-safe access. The example also illustrates the difference between non-deterministic and deterministic random
+/// number generation.
+///
+/// \macro_code
+/// \macro_image
+/// \macro_output
+///
+/// \date February 2026
+/// \author Bohdan Dudar (JGU Mainz), Fernando Hueso-González (IFIC, CSIC-UV), Vincenzo Eduardo Padulano (CERN)
+
+#include <iostream>
+#include <memory>
+#include <TCanvas.h>
+#include <ROOT/RDataFrame.hxx>
+
+#include "df041_ThreadSafeRNG.hxx"
+
+// Canvas that should survive the running of this macro
+std::unique_ptr<TCanvas> myCanvas;
+
+void df041_ThreadSafeRNG()
+{
+   myCanvas = std::make_unique<TCanvas>("myCanvas", "myCanvas", 1000, 500);
+   myCanvas->Divide(3, 1);
+
+   unsigned int nEntries{10000000};
+
+   // 1. Single thread for reference
+   auto df1 = ROOT::RDataFrame(nEntries).Define("x", GetNormallyDistributedNumberFromGlobalGenerator);
+   auto h1 = df1.Histo1D({"h1", "Single thread (no MT)", 1000, -4, 4}, {"x"});
+   myCanvas->cd(1);
+   h1->DrawCopy();
+
+   // 2. One generator per RDataFrame slot, with random_device seeding
+   // Notes and Caveats:
+   // - How many numbers are drawn from each generator is not deterministic
+   //   and the result is not deterministic between runs.
+   unsigned int nSlots{8};
+   ROOT::EnableImplicitMT(nSlots);
+   // Before running the RDataFrame computation graph, we reinitialize the generators (one per slot), so they can
+   // be used accordingly during the execution.
+   ReinitializeGenerators(nSlots);
+   auto df2 = ROOT::RDataFrame(nEntries).DefineSlot("x", GetNormallyDistributedNumberPerSlotGenerator);
+   auto h2 = df2.Histo1D({"h2", "Thread-safe (MT, non-deterministic)", 1000, -4, 4}, {"x"});
+   myCanvas->cd(2);
+   h2->DrawCopy();
+
+   // 3. One generator per RDataFrame slot, with entry seeding
+   // Notes and Caveats:
+   // - With RDataFrame(INTEGER_NUMBER) constructor (as in the example),
+   //   the result is deterministic and identical on every run
+   // - With RDataFrame(TTree) constructor, the result is not guaranteed to be deterministic.
+   //   To make it deterministic, use something from the dataset to act as the event identifier
+   //   instead of rdfentry_, and use it as a seed.
+
+   // Before running the RDataFrame computation graph, we reinitialize the generators (one per slot), so they can
+   // be used accordingly during the execution.
+   ReinitializeGenerators(nSlots);
+   auto df3 =
+      ROOT::RDataFrame(nEntries).DefineSlot("x", GetNormallyDistributedNumberPerSlotGeneratorForEntry, {"rdfentry_"});
+   auto h3 = df3.Histo1D({"h3", "Thread-safe (MT, deterministic)", 1000, -4, 4}, {"x"});
+   myCanvas->cd(3);
+   h3->DrawCopy();
+
+   std::cout << std::fixed << std::setprecision(3) << "Final distributions                : " << "Mean " << " +- "
+             << "StdDev" << std::endl;
+   std::cout << std::fixed << std::setprecision(3) << "Theoretical                        : " << "0.000" << " +- "
+             << "1.000" << std::endl;
+   std::cout << std::fixed << std::setprecision(3) << "Single thread (no MT)              : " << h1->GetMean() << " +- "
+             << h1->GetStdDev() << std::endl;
+   std::cout << std::fixed << std::setprecision(3) << "Thread-safe (MT, non-deterministic): " << h2->GetMean() << " +- "
+             << h2->GetStdDev() << std::endl;
+   std::cout << std::fixed << std::setprecision(3) << "Thread-safe (MT, deterministic)    : " << h3->GetMean() << " +- "
+             << h3->GetStdDev() << std::endl;
+}

tutorials/analysis/dataframe/df041_ThreadSafeRNG.hxx

@@ -0,0 +1,55 @@
+#ifndef ROOT_TUTORIALS_ANALYSIS_DATAFRAME_DF041
+#define ROOT_TUTORIALS_ANALYSIS_DATAFRAME_DF041
+
+#include <random>
+
+// NOTE: these globals are intentionally NOT protected by a mutex.
+// This function is only safe to call from a single thread (used as reference).
+inline std::random_device globalRandomDevice{};
+inline std::mt19937 globalGenerator(globalRandomDevice());
+inline std::normal_distribution<double> globalGaus(0., 1.);
+
+double GetNormallyDistributedNumberFromGlobalGenerator()
+{
+   return globalGaus(globalGenerator);
+}
+
+// One generator per slot — initialized once before the event loop
+// An alternative to these global vectors could be to have thread_local
+// variables within a function scope and then call that function from RDataFrame
+inline std::vector<std::mt19937> generators;
+inline std::vector<std::normal_distribution<double>> gaussians;
+
+void ReinitializeGenerators(unsigned int nSlots)
+{
+   std::random_device rd;
+   generators.resize(nSlots);
+   for (auto &gen : generators)
+      gen.seed(rd());
+   gaussians.resize(nSlots, std::normal_distribution<double>(0., 1.));
+}
+
+double GetNormallyDistributedNumberPerSlotGenerator(unsigned int slot)
+{
+   return gaussians[slot](generators[slot]);
+}
+
+double GetNormallyDistributedNumberPerSlotGeneratorForEntry(unsigned int slot, unsigned long long entry)
+{
+   // We want to generate a random number distributed according to a normal distribution in a thread-safe way and such
+   // that it is reproducible across different RDataFrame runs, i.e. given the same input to the generator it will
+   // produce the same value. This is one way to do it. It assumes that the input argument represents a unique entry ID,
+   // such that any thread processing an RDataFrame task will see this number once throughout the entire execution of
+   // the computation graph
+   // Calling both `reset` and `seed` methods is fundamental here to ensure reproducibility: without them the same
+   // generator could be seeded by a different entry (depending on which is the first entry ID seen by a thread) or
+   // could be at a different step of the sequence (depending how many entries this particular thread is processing).
+   // Alternatively, if both the generator and the distribution objects were recreated from scratch at every function
+   // call (i.e. by removing the global std::vector stores), then the next two method calls would not be necessary, at
+   // the cost of a possible performance degradation.
+   gaussians[slot].reset();
+   generators[slot].seed(entry);
+   return gaussians[slot](generators[slot]);
+}
+
+#endif // ROOT_TUTORIALS_ANALYSIS_DATAFRAME_DF041

tutorials/analysis/dataframe/df041_ThreadSafeRNG.py

@@ -0,0 +1,89 @@
+# \file
+# \ingroup tutorial_dataframe
+# \notebook -nodraw
+# Usage of multithreading mode with random generators.
+#
+# This example illustrates how to define functions that generate random numbers and use them in an RDataFrame
+# computation graph in a thread-safe way.
+#
+# Using only one random number generator in an application running with ROOT.EnableImplicitMT() is a common pitfall.
+# This pitfall creates race conditions resulting in a distorted random distribution. In the example, this issue is
+# solved by creating one random number generator per RDataFrame processing slot, thus allowing for parallel and
+# thread-safe access. The example also illustrates the difference between non-deterministic and deterministic random
+# number generation.
+#
+# \macro_code
+# \macro_image
+# \macro_output
+#
+# \date February 2026
+# \author Bohdan Dudar (JGU Mainz), Fernando Hueso-González (IFIC, CSIC-UV), Vincenzo Eduardo Padulano (CERN)
+
+import os
+
+import ROOT
+
+
+def df041_ThreadSafeRNG():
+
+    # First, we declare the functions needed by the RDataFrame computation graph to the interpreter
+    ROOT.gInterpreter.Declare(
+        f'#include "{os.path.join(str(ROOT.gROOT.GetTutorialDir()), "analysis", "dataframe", "df041_ThreadSafeRNG.hxx")}"'
+    )
+
+    myCanvas = ROOT.TCanvas("myCanvas", "myCanvas", 1000, 500)
+    myCanvas.Divide(3, 1)
+
+    nEntries = 10000000
+
+    # 1. Single thread for reference
+    df1 = ROOT.RDataFrame(nEntries).Define("x", ROOT.GetNormallyDistributedNumberFromGlobalGenerator)
+    h1 = df1.Histo1D(("h1", "Single thread (no MT)", 1000, -4, 4), "x")
+    myCanvas.cd(1)
+    h1.DrawCopy()
+
+    # 2. One generator per RDataFrame slot, with random_device seeding
+    # Notes and Caveats:
+    # - How many numbers are drawn from each generator is not deterministic
+    #   and the result is not deterministic between runs.
+    nSlots = 8
+    ROOT.EnableImplicitMT(nSlots)
+    # Before running the RDataFrame computation graph, we reinitialize the generators (one per slot), so they can
+    # be used accordingly during the execution.
+    ROOT.ReinitializeGenerators(nSlots)
+    df2 = ROOT.RDataFrame(nEntries).DefineSlot("x", ROOT.GetNormallyDistributedNumberPerSlotGenerator)
+    h2 = df2.Histo1D(("h2", "Thread-safe (MT, non-deterministic)", 1000, -4, 4), "x")
+    myCanvas.cd(2)
+    h2.DrawCopy()
+
+    # 3. One generator per RDataFrame slot, with entry seeding
+    # Notes and Caveats:
+    # - With RDataFrame(INTEGER_NUMBER) constructor (as in the example),
+    #   the result is deterministic and identical on every run
+    # - With RDataFrame(TTree) constructor, the result is not guaranteed to be deterministic.
+    #   To make it deterministic, use something from the dataset to act as the event identifier
+    #   instead of rdfentry_, and use it as a seed.
+
+    # Before running the RDataFrame computation graph, we reinitialize the generators (one per slot), so they can
+    # be used accordingly during the execution.
+    ROOT.ReinitializeGenerators(nSlots)
+    df3 = ROOT.RDataFrame(nEntries).DefineSlot(
+        "x", ROOT.GetNormallyDistributedNumberPerSlotGeneratorForEntry, ["rdfentry_"]
+    )
+    h3 = df3.Histo1D(("h3", "Thread-safe (MT, deterministic)", 1000, -4, 4), "x")
+    myCanvas.cd(3)
+    h3.DrawCopy()
+
+    print(f"{'{:<40}'.format('Final distributions')}: Mean +- StdDev")
+    print(f"{'{:<40}'.format('Theoretical')}: 0.000 +- 1.000")
+    print(f"{'{:<40}'.format('Single thread (no MT)')}: {h1.GetMean():.3f} +- {h1.GetStdDev():.3f}")
+    print(f"{'{:<40}'.format('Thread-safe (MT, non-deterministic)')}: {h2.GetMean():.3f} +- {h2.GetStdDev():.3f}")
+    print(f"{'{:<40}'.format('Thread-safe (MT, deterministic)')}: {h3.GetMean():.3f} +- {h3.GetStdDev():.3f}")
+
+    # We draw the canvas with block=True to stop the execution before end of the
+    # function and to be able to interact with the canvas until necessary
+    myCanvas.Draw(block=True)
+
+
+if __name__ == "__main__":
+    df041_ThreadSafeRNG()

tutorials/analysis/dataframe/index.md

@@ -64,6 +64,7 @@ A collection of building block examples for your analysis.
 | df036_missingBranches.C | df036_missingBranches.py | Deal with missing values due to a missing branch when switching to a new file in a chain. |
 | df037_TTreeEventMatching.C | df037_TTreeEventMatching.py | Deal with missing values due to not finding a matching event in an auxiliary dataset. |
 | df040_RResultPtr_lifetimeManagement.C | | Lifetime management of RResultPtr and the underlying objects. |
+| df041_ThreadSafeRNG.C | df041_ThreadSafeRNG.py | Thread-safe usage of random number generators in multithreading. |
 
 
 \anchor readwrite