ActsExamples/Framework/RandomNumbers.hpp

0001 // This file is part of the ACTS project.
0002 //
0003 // Copyright (C) 2016 CERN for the benefit of the ACTS project
0004 //
0005 // This Source Code Form is subject to the terms of the Mozilla Public
0006 // License, v. 2.0. If a copy of the MPL was not distributed with this
0007 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
0008
0009 #pragma once
0010
0011 #include <cstdint>
0012 #include <random>
0013
0014 namespace ActsExamples {
0015 struct AlgorithmContext;
0016
0017 /// The random number generator used in the framework.
0018 using RandomEngine = std::mt19937;  ///< Mersenne Twister
0019
0020 /// The seed type used in the framework.
0021 using RandomSeed = std::uint32_t;
0022
0023 /// Provide event and algorithm specific random number generator.s
0024 ///
0025 /// This provides local random number generators, allowing for
0026 /// thread-safe, lock-free, and reproducible random number generation across
0027 /// single-threaded and multi-threaded test framework runs.
0028 ///
0029 /// The role of the RandomNumbers is only to spawn local random number
0030 /// generators. It does not, in and of itself, accommodate requests for specific
0031 /// random number distributions (uniform, gaussian, etc). For this purpose,
0032 /// clients should spawn their own local distribution objects
0033 /// as needed, following the C++11 STL design.
0034 class RandomNumbers {
0035  public:
0036   struct Config {
0037     RandomSeed seed = 1234567890u;  ///< random seed
0038   };
0039
0040   explicit RandomNumbers(const Config& cfg);
0041
0042   /// Spawn an algorithm-local random number generator. To avoid inefficiencies
0043   /// and multiple uses of a given RNG seed, this should only be done once per
0044   /// Algorithm invocation, after what the generator object should be reused.
0045   ///
0046   /// It calls generateSeed() for an event driven seed
0047   ///
0048   /// @param context is the AlgorithmContext of the host algorithm
0049   RandomEngine spawnGenerator(const AlgorithmContext& context) const;
0050
0051   /// Generate a event and algorithm specific seed value.
0052   ///
0053   /// This should only be used in special cases e.g. where a custom
0054   /// random engine is used and `spawnGenerator` can not be used.
0055   RandomSeed generateSeed(const AlgorithmContext& context) const;
0056
0057  private:
0058   Config m_cfg;
0059 };
0060
0061 }  // namespace ActsExamples