random/distribution/BernoulliDistribution.hh

0001 //----------------------------------*-C++-*----------------------------------//
0002 // Copyright 2020-2024 UT-Battelle, LLC, and other Celeritas developers.
0003 // See the top-level COPYRIGHT file for details.
0004 // SPDX-License-Identifier: (Apache-2.0 OR MIT)
0005 //---------------------------------------------------------------------------//
0006 //! \file celeritas/random/distribution/BernoulliDistribution.hh
0007 //---------------------------------------------------------------------------//
0008 #pragma once
0009
0010 #include "corecel/Assert.hh"
0011 #include "corecel/Macros.hh"
0012 #include "corecel/Types.hh"
0013
0014 #include "GenerateCanonical.hh"
0015
0016 namespace celeritas
0017 {
0018 //---------------------------------------------------------------------------//
0019 /*!
0020  * Select one of two options with a given probability.
0021  *
0022  * The constructor argument is the chance of returning `true`, with an optional
0023  * second argument for normalizing with a fraction of `false` values.
0024  * \code
0025     BernoulliDistribution snake_eyes(1, 35);
0026     if (snake_eyes(rng))
0027     {
0028         // ...
0029     }
0030     BernoulliDistribution also_snake_eyes(1.0 / 36.0);
0031    \endcode
0032  */
0033 class BernoulliDistribution
0034 {
0035   public:
0036     //!@{
0037     //! \name Type aliases
0038     using result_type = bool;
0039     //!@}
0040
0041   public:
0042     // Construct with the probability of returning true
0043     explicit inline CELER_FUNCTION BernoulliDistribution(real_type p_true);
0044
0045     // Construct with the UNnormalized probability of returning true or false
0046     inline CELER_FUNCTION
0047     BernoulliDistribution(real_type scaled_true, real_type scaled_false);
0048
0049     // Sample true or false based on the probability
0050     template<class Generator>
0051     inline CELER_FUNCTION result_type operator()(Generator& rng);
0052
0053     //! Probability of returning `true` from operator()
0054     real_type p() const { return p_true_; }
0055
0056   private:
0057     real_type p_true_;
0058 };
0059
0060 //---------------------------------------------------------------------------//
0061 // INLINE DEFINITIONS
0062 //---------------------------------------------------------------------------//
0063 /*!
0064  * Construct with the probability of returning true.
0065  */
0066 CELER_FUNCTION BernoulliDistribution::BernoulliDistribution(real_type p_true)
0067     : p_true_(p_true)
0068 {
0069     CELER_EXPECT(p_true >= 0 && p_true <= 1);
0070 }
0071
0072 //---------------------------------------------------------------------------//
0073 /*!
0074  * Construct with the UNnormalized probability of returning true or false
0075  */
0076 CELER_FUNCTION
0077 BernoulliDistribution::BernoulliDistribution(real_type scaled_true,
0078                                              real_type scaled_false)
0079     : p_true_(scaled_true / (scaled_true + scaled_false))
0080 {
0081     CELER_EXPECT(scaled_true > 0 || scaled_false > 0);
0082     CELER_EXPECT(scaled_true >= 0 && scaled_false >= 0);
0083 }
0084
0085 //---------------------------------------------------------------------------//
0086 /*!
0087  * Construct with the probability of returning true.
0088  */
0089 template<class Generator>
0090 CELER_FUNCTION auto
0091 BernoulliDistribution::operator()(Generator& rng) -> result_type
0092 {
0093     return generate_canonical<real_type>(rng) < p_true_;
0094 }
0095
0096 //---------------------------------------------------------------------------//
0097 }  // namespace celeritas