Skip to content

Refactor(rng): migrate core distributions from TRandom3 to std::mt19937_64#472

Open
HimanKing wants to merge 4 commits into
BioDynaMo:masterfrom
HimanKing:master
Open

Refactor(rng): migrate core distributions from TRandom3 to std::mt19937_64#472
HimanKing wants to merge 4 commits into
BioDynaMo:masterfrom
HimanKing:master

Conversation

@HimanKing

Copy link
Copy Markdown

Summary

Partially migrates BioDynaMo's random number generation subsystem away from
ROOT's TRandom3 by replacing the backing engine with std::mt19937_64 and
re-implementing the majority of distributions using C++17 standard library
equivalents in src/core/util/random.h and src/core/util/random.cc.

Note: ROOT remains a required dependency. Landau, BreitWigner, and
all UserDefinedDist variants still delegate to ROOT internally. This PR is
a first, self-contained step toward full dependency reduction.


Motivation

ROOT is a large external dependency that significantly increases build
complexity, installation time, and reduces portability — particularly for
researchers without access to high-specification hardware or system
administration expertise. This refactoring targets the random number generation
subsystem as a self-contained, well-tested module suitable for incremental
dependency reduction.This is the first step toward breaking BioDynaMo's
dependency on ROOT, proving the migration path is viable one subsystem at a time.


Files Modified

  • src/core/util/random.h
  • src/core/util/random.cc
  • test/unit/core/util/random_test.cc
  • test/unit/core/simulation_test.cc

Changes

RNG Engine

  • Replaced TRandom3 as the primary sampling engine with std::mt19937_64
    (mt_engine_).
  • Added GetEngine() public accessor returning a reference to mt_engine_,
    allowing DistributionRng subclasses to draw samples without requiring
    friend access or exposing private members.
  • SetSeed() seeds both mt_engine_ and the retained TRandom3 instance
    (generator_) with the same value, keeping unmigrated distributions
    reproducible under the same seed call.
  • GetSeed() now returns last_seed_ — a uint64_t member set directly by
    SetSeed(). This removes the previous delegation to generator_->GetSeed()
    (TRandom3) and ensures the returned value is authoritative and independent of
    the ROOT engine, including if GetEngine() is used to interact with
    mt_engine_ directly.

Distributions Migrated to stdlib

Function Original Replacement
Uniform() TRandom3::Uniform std::uniform_real_distribution
Gaus() TRandom3::Gaus std::normal_distribution
Exp() TRandom3::Exp std::exponential_distribution
PoissonD() TRandom3::PoissonD std::poisson_distribution<long>
Poisson() TRandom3::Poisson std::poisson_distribution<int>
Binomial() TRandom3::Binomial std::binomial_distribution
Integer() TRandom3::Integer std::uniform_int_distribution
Circle() TRandom3::Circle trigonometric + std::uniform_real_distribution
Sphere() TRandom3::Sphere Marsaglia method (std::normal_distribution)

Distributions Not Yet Migrated (future work)

  • Landau() — no standard library equivalent; still delegates to
    generator_->Landau(). Requires a custom rejection-sampling implementation.
  • BreitWigner() — no standard library equivalent; still delegates to
    generator_->BreitWigner().
  • UserDefinedDistRng1D/2D/3D — user-defined distributions backed by
    ROOT's TF1/TF2/TF3, sampled via GetRandom(). These use ROOT's global
    gRandom engine internally and are unaffected by SetSeed() on a Random
    instance. A full replacement requires a rejection-sampling framework and is
    deferred.

Architectural Note — Stale Virtual Interface

The DistributionRng<T>::SampleImpl(TRandom* rng) virtual interface retains
its ROOT-typed signature. Implementations that have been migrated to stdlib
silently ignore the rng parameter (marked /*rng*/ in source). This
interface will be updated to remove the TRandom* parameter once all
distributions are ported.


Testing

All unit tests pass under the refactored implementation alongside the full
suite of system-wide unit tests:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant