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 "Acts/Utilities/HashCombine.hpp"
0012
0013 #include <cstddef>
0014 #include <cstdint>
0015 #include <random>
0016
0017 #include <boost/functional/hash.hpp>
0018
0019 namespace ActsExamples {
0020
0021 struct AlgorithmContext;
0022
0023 /// The seed type used in the framework.
0024 using RandomSeed = std::uint64_t;
0025
0026 /// The random number generator used in the framework.
0027 ///
0028 /// Thin wrapper around std::mt19937_64 that remembers the seed it was
0029 /// constructed with so that downstream consumers (e.g. lumi-block vertex
0030 /// generators) can derive reproducible, user-seed-dependent sub-sequences.
0031 class RandomEngine {
0032  public:
0033   using result_type = std::mt19937_64::result_type;
0034
0035   /// Default constructor. Uses mt19937_64 default seed.
0036   RandomEngine() : m_seed(0) {}
0037
0038   /// Construct with a specific seed.
0039   explicit RandomEngine(RandomSeed seed) : m_seed(seed), m_engine(seed) {}
0040
0041   /// Return the seed this engine was constructed with.
0042   RandomSeed seed() const { return m_seed; }
0043
0044   /// Create a new engine whose seed combines this engine's seed with an
0045   /// additional value. Useful for deriving deterministic sub-sequences
0046   /// (e.g. per-lumi-block seeds) that depend on the user's original seed.
0047   RandomEngine combinedWith(std::uint64_t extra) const {
0048     return RandomEngine(Acts::hashMixAndCombine(m_seed, extra));
0049   }
0050
0051   result_type operator()() { return m_engine(); }
0052
0053   static constexpr result_type min() { return std::mt19937_64::min(); }
0054   static constexpr result_type max() { return std::mt19937_64::max(); }
0055
0056  private:
0057   RandomSeed m_seed;
0058   std::mt19937_64 m_engine;
0059 };
0060
0061 /// Provide event and algorithm specific random number generator.s
0062 ///
0063 /// This provides local random number generators, allowing for
0064 /// thread-safe, lock-free, and reproducible random number generation across
0065 /// single-threaded and multi-threaded test framework runs.
0066 ///
0067 /// The role of the RandomNumbers is only to spawn local random number
0068 /// generators. It does not, in and of itself, accommodate requests for specific
0069 /// random number distributions (uniform, gaussian, etc). For this purpose,
0070 /// clients should spawn their own local distribution objects
0071 /// as needed, following the C++11 STL design.
0072 class RandomNumbers {
0073  public:
0074   struct Config {
0075     RandomSeed seed = 1234567890u;  ///< random seed
0076   };
0077
0078   explicit RandomNumbers(const Config& cfg);
0079
0080   /// Spawn an algorithm-local random number generator. To avoid inefficiencies
0081   /// and multiple uses of a given RNG seed, this should only be done once per
0082   /// Algorithm invocation, after what the generator object should be reused.
0083   ///
0084   /// It calls generateSeed() for an event driven seed
0085   ///
0086   /// @param context is the AlgorithmContext of the host algorithm
0087   RandomEngine spawnGenerator(const AlgorithmContext& context) const;
0088
0089   /// Generate a event and algorithm specific seed value.
0090   ///
0091   /// This should only be used in special cases e.g. where a custom
0092   /// random engine is used and `spawnGenerator` can not be used.
0093   RandomSeed generateSeed(const AlgorithmContext& context) const;
0094
0095  private:
0096   Config m_cfg;
0097 };
0098
0099 }  // namespace ActsExamples