random-draw.hpp

Go to the documentation of this file.

/*
  RANDOM-DRAW.hpp  -  randomly pick limited values

  Copyright (C)         Lumiera.org
    2023,               Hermann Vosseler <Ichthyostega@web.de>

  This program is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License as
  published by the Free Software Foundation; either version 2 of
  the License, or (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

*/

#ifndef LIB_RANDOM_DRAW_H
#define LIB_RANDOM_DRAW_H


#include "lib/error.h"
#include "lib/lazy-init.hpp"
#include "lib/meta/function.hpp"
#include "lib/meta/function-closure.hpp"
#include "lib/util-quant.hpp"
#include "lib/util.hpp"

#include <functional>
#include <utility>


namespace lib {
  namespace err = lumiera::error;
  
  using lib::meta::disable_if_self;
  using lib::meta::_Fun;
  using std::function;
  using std::forward;
  using std::move;
  
  
  
  template<typename T, T max, T min =T(0), T zero =min>
  struct Limited
    {
      static_assert (min < max);
      static_assert (min <= zero and zero < max);
      
      static constexpr T maxVal() { return max; }
      static constexpr T minVal() { return min; }
      static constexpr T zeroVal(){ return zero;}
      
      T val;
      
      template<typename X>
      Limited (X raw)
        : val(util::limited (X(minVal()), raw, X(maxVal())))
        { }
      
      operator T&()
        {
          return val;
        }
      operator T const&()  const
        {
          return val;
        }
    };
  
  
  
  namespace random_draw { // Policy definitions
    
    template<uint max>
    struct LimitedRandomGenerate
      : function<Limited<uint, max>(void)>
      {
        static double defaultSrc() { return rand()/double(RAND_MAX); }
      };
    
  }//(End)Policy definitions
  
  
  
  
  /**********************************************************/
  template<class POL>
  class RandomDraw
    : public LazyInit<POL>
    {
      using Lazy = LazyInit<POL>;
      using Disabled = typename Lazy::MarkDisabled;
      
      using Sig = typename _Fun<POL>::Sig;
      using Fun = function<Sig>;
      using Tar = typename _Fun<POL>::Ret;
      
      Tar    maxResult_{Tar::maxVal()};      
      Tar    minResult_{Tar::minVal()};      
      double probability_{0};                
      size_t shuffle_{0};                    
      
      
      Tar
      limited (double val)
        {
          if (probability_ == 0.0)
            return Tar::zeroVal();
          //
          REQUIRE (Tar::minVal() <= minResult_);
          REQUIRE (Tar::maxVal() >= maxResult_);
          REQUIRE (minResult_ < maxResult_);
          REQUIRE (0.0 <= probability_);
          REQUIRE (probability_ <= 1.0);
          double q = (1.0 - probability_);
          if (val < q) // control probability of values ≠ neutral
            return Tar::zeroVal();
          if (val > 1.0)
            val = 1.0;
          val -= q;                          // [0 .. [q .. 1[
          val /= probability_;               // [0 .. 1[
          auto org = Tar::zeroVal();
          if  (org == minResult_)
            { // simple standard case
              val *= maxResult_ - org;       // [0 .. m[
              val += org+1;                  // [1 .. m]
              val += CAP_EPSILON;            // round down yet absorb dust
              return Tar{floor (val)};
            }
          else
          if (org < minResult_ or org > maxResult_)
            { // disjoint form origin, but compact
              org = minResult_;              // ensure all values covered
              val *= maxResult_ - org + 1;   // [o .. m]
              val += org;
              val += CAP_EPSILON;
              return Tar{floor (val)};
            }
          else// Origin is somewhere within value range
            {//  ==> wrap "negative" part above max
            //       to map 0.0 ⟼ org (≙neutral)
              val *= maxResult_ - minResult_;
              val += org+1;                  // max inclusive but <0 ⟼ org
              if (val >= maxResult_+1)       // wrap the "negatives"
                val -= maxResult_+1 - minResult_;
              val += CAP_EPSILON;
              return Tar{floor (val)};
            }
        }                             //----headroom to accommodate low probabilities
      static size_t constexpr QUANTISER   = 1 << 4 + util::ilog2 (Tar::maxVal()-Tar::minVal());
      static double constexpr CAP_EPSILON = 1/(2.0 * QUANTISER);
      
      
      double
      asRand (size_t hash)
        {
          if (shuffle_)
            hash *= shuffle_++;
          return double(hash % QUANTISER) / QUANTISER;
        }
      
      Tar
      drawLimited (size_t hash)
        {
           return limited (asRand (hash));
        }
      
      
    public:
      RandomDraw()
        : Lazy{Disabled()}
        {
          mapping (POL::defaultSrc);
        }
      
      template<class FUN,      typename =disable_if_self<RandomDraw, FUN>>
      RandomDraw(FUN&& fun)
        : Lazy{Disabled()}
        , probability_{1.0}
        {
          mapping (forward<FUN> (fun));
        }
      
      
      
      /* ===== Builder API ===== */
      
      RandomDraw&&
      probability (double p)
        {
          probability_ = util::limited (0.0, p ,1.0);
          return move (*this);
        }
      
      RandomDraw&&
      maxVal (Tar m)
        {
          maxResult_ = util::min (m, Tar::maxVal());
          if (minResult_>=maxResult_)
            minVal (--m);
          return move (*this);
        }
      
      RandomDraw&&
      minVal (Tar m)
        {
          minResult_ = util::max (m, Tar::minVal());
          if (maxResult_<=minResult_)
            maxVal (++m);
          return move (*this);
        }
      
      RandomDraw&&
      shuffle (size_t seed =55)
        {
          shuffle_ = seed;
          return move (*this);
        }
      
      RandomDraw&&
      fixedVal (Tar v)
        {
          mapping ([v](size_t){ return v; });
          return move (*this);
        }
      
      template<class FUN>
      RandomDraw&&
      mapping (FUN&& fun)
        {
          Fun& thisMapping = static_cast<Fun&> (*this);
          Lazy::installInitialiser (thisMapping
                                   ,[theFun = forward<FUN> (fun)]
                                    (RandomDraw* self)
                                       { // when lazy init is performed....
                                         self->installAdapted (theFun);
                                       });
          return move (*this);
        }
      
      
      
      
    private:
      template<class FUN>
      void
      installAdapted (FUN&& fun)
        {
          Fun& thisMapping = static_cast<Fun&> (*this);
          thisMapping = adaptOut(adaptIn(std::forward<FUN> (fun)));
        }
      
      
      template<class FUN>
      auto
      adaptIn (FUN&& fun)
        {
          using lib::meta::func::applyFirst;
          using _Fun = lib::meta::_Fun<FUN>;
          static_assert (_Fun(), "Need something function-like.");
          
          using Sig     = typename _Fun::Sig;
          using Args    = typename _Fun::Args;
          using BaseIn  = typename lib::meta::_Fun<POL>::Args;
          
          if constexpr (std::is_same_v<Args, BaseIn>)
             // function accepts same arguments as this RandomDraw
            return forward<FUN> (fun); // pass-through directly
          else
            {// attempt to find a custom adaptor via Policy template
              using Adaptor = typename POL::template Adaptor<Sig>;
              return Adaptor::build (forward<FUN> (fun));
            }
        }
      
      template<class FUN>
      auto
      adaptOut (FUN&& fun)
        {
          static_assert (lib::meta::_Fun<FUN>(), "Need something function-like.");
          
          using Res = typename lib::meta::_Fun<FUN>::Ret;
          using lib::meta::func::chained;
          using lib::meta::_FunRet;
          
          if constexpr (std::is_same_v<Res, Tar>)//  ◁──────────────────────────┨ function produces result directly
            return std::forward<FUN>(fun);
          else
          if constexpr (std::is_same_v<Res, size_t>)//  ◁───────────────────────┨ function yields random source to draw value
            return chained (std::forward<FUN>(fun)
                           ,[this](size_t hash){ return drawLimited(hash); }
                           );
          else
          if constexpr (std::is_same_v<Res, double>)//  ◁───────────────────────┨ function yields mapping value to be quantised
            return chained (std::forward<FUN>(fun)
                           ,[this](double rand){ return limited(rand); }
                           );
          else
          if constexpr (std::is_same_v<Res, RandomDraw>) // ◁───────────────────┨ RandomDraw with dynamically adjusted parameters
            return [functor=std::forward<FUN>(fun)]
                   (auto&& ...inArgs) -> _FunRet<RandomDraw>
                      {                               // invoke manipulator with copy
                        RandomDraw adaptedDraw = functor(inArgs...);
                        return adaptedDraw (forward<decltype(inArgs)> (inArgs)...);
                      };                           //    forward arguments to mapping-fun
          else
            static_assert (not sizeof(Res), "unable to adapt / handle result type");
          NOTREACHED("Handle based on return type");
        }
    };
  
  
} // namespace lib
#endif /*LIB_RANDOM_DRAW_H*/