Kernel/detail/RandomNumberDistributions.hpp

0001 // This file is part of the Acts project.
0002 //
0003 // Copyright (C) 2018 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 #pragma once
0010
0011 #include "Fatras/Kernel/detail/LandauQuantile.hpp"
0012 #include <random>
0013
0014 namespace Fatras {
0015
0016 /// The following standard random number distributions are supported:
0017 ///
0018 using GaussDist = std::normal_distribution<double>;         ///< Normal
0019 using UniformDist = std::uniform_real_distribution<double>; ///< Uniform
0020 using GammaDist = std::gamma_distribution<double>;          ///< Gamma
0021 using PoissonDist = std::poisson_distribution<int>;         ///< Poisson
0022 ///
0023 /// In addition, the Landau distribution is provided
0024 ///
0025 class LandauDist {
0026 public:
0027   /// A RandomNumberDistribution should provide a parameters struct
0028   struct param_type {
0029     double mean = 0.;  ///< Mean of the Landau distribution
0030     double scale = 1.; ///< Scale factor
0031
0032     /// Default constructor and constructor from raw parameters
0033     param_type() = default;
0034     param_type(double mean, double scale);
0035
0036     /// Parameters should be CopyConstructible and CopyAssignable
0037     param_type(const param_type &) = default;
0038     param_type &operator=(const param_type &) = default;
0039
0040     /// Parameters should be EqualityComparable
0041     bool operator==(const param_type &other) const;
0042     bool operator!=(const param_type &other) const { return !(*this == other); }
0043
0044     /// Parameters should link back to the host distribution
0045     using distribution_type = LandauDist;
0046   };
0047
0048   /// There should be a default constructor, a constructor from raw parameters,
0049   /// and a constructor from a parameters struct
0050   LandauDist() = default;
0051   LandauDist(double mean, double scale);
0052   LandauDist(const param_type &cfg);
0053
0054   /// A distribution should be copy-constructible and copy-assignable
0055   LandauDist(const LandauDist &) = default;
0056   LandauDist &operator=(const LandauDist &) = default;
0057
0058   /// Some standard ways to control the distribution's state should be provided
0059   void reset() { /* There is currently no state to reset here */
0060   }
0061   param_type param() const { return m_cfg; }
0062   void param(const param_type &p) { m_cfg = p; }
0063
0064   /// A RandomNumberDistribution should provide a result type typedef and some
0065   /// bounds on the values that can be emitted as output
0066   using result_type = double;
0067   result_type min() const;
0068   result_type max() const;
0069
0070   /// Generate a random number following a Landau distribution
0071   template <typename Generator> result_type operator()(Generator &engine) {
0072     return (*this)(engine, m_cfg);
0073   }
0074
0075   /// Do the same, but using custom Landau distribution parameters
0076   template <typename Generator>
0077   result_type operator()(Generator &engine, const param_type &params) {
0078     double x = std::generate_canonical<float, 10>(engine);
0079     double res = params.mean + landau_quantile(x, params.scale);
0080     return res;
0081   }
0082
0083   /// Provide standard comparison operators
0084   bool operator==(const LandauDist &other) const;
0085   bool operator!=(const LandauDist &other) const { return !(*this == other); }
0086
0087 private:
0088   param_type m_cfg; ///< configuration struct
0089 };
0090 } // namespace Fatras