ActsExamples/Framework/RandomNumbers.hpp

0001 // This file is part of the Acts project.
0002 //
0003 // Copyright (C) 2017 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 http://mozilla.org/MPL/2.0/.
0008
0009 //
0010 //  RandomNumbers.hpp
0011 //  ActsExamples
0012 //
0013 //  Created by Andreas Salzburger on 17/05/16.
0014 //
0015 //
0016
0017 #pragma once
0018
0019 #include "ActsExamples/Framework/AlgorithmContext.hpp"
0020
0021 #include <cstdint>
0022 #include <random>
0023
0024 namespace ActsExamples {
0025 struct AlgorithmContext;
0026
0027 /// The random number generator used in the framework.
0028 using RandomEngine = std::mt19937;  ///< Mersenne Twister
0029
0030 /// Provide event and algorithm specific random number generator.s
0031 ///
0032 /// This provides local random number generators, allowing for
0033 /// thread-safe, lock-free, and reproducible random number generation across
0034 /// single-threaded and multi-threaded test framework runs.
0035 ///
0036 /// The role of the RandomNumbers is only to spawn local random number
0037 /// generators. It does not, in and of itself, accommodate requests for specific
0038 /// random number distributions (uniform, gaussian, etc). For this purpose,
0039 /// clients should spawn their own local distribution objects
0040 /// as needed, following the C++11 STL design.
0041 class RandomNumbers {
0042  public:
0043   struct Config {
0044     uint64_t seed = 1234567890u;  ///< random seed
0045   };
0046
0047   RandomNumbers(const Config& cfg);
0048
0049   /// Spawn an algorithm-local random number generator. To avoid inefficiencies
0050   /// and multiple uses of a given RNG seed, this should only be done once per
0051   /// Algorithm invocation, after what the generator object should be reused.
0052   ///
0053   /// It calls generateSeed() for an event driven seed
0054   ///
0055   /// @param context is the AlgorithmContext of the host algorithm
0056   RandomEngine spawnGenerator(const AlgorithmContext& context) const;
0057
0058   /// Generate a event and algorithm specific seed value.
0059   ///
0060   /// This should only be used in special cases e.g. where a custom
0061   /// random engine is used and `spawnGenerator` can not be used.
0062   uint64_t generateSeed(const AlgorithmContext& context) const;
0063
0064  private:
0065   Config m_cfg;
0066 };
0067
0068 }  // namespace ActsExamples