BasePolicies.h

Go to the documentation of this file.

#ifndef NURANDOM_RANDOMUTILS_PROVIDERS_BASEPOLICY_H
#define NURANDOM_RANDOMUTILS_PROVIDERS_BASEPOLICY_H 1

// C/C++ standard libraries
#include <vector>
#include <string>
#include <bitset>
#include <sstream>
#include <ostream> // std::endl
#include <memory> // std::unique_ptr<>
#include <random> // std::uniform_int_distribution, std::default_random_engine
#include <chrono> // std::system_clock

// From art and its tool chain
#include "messagefacility/MessageLogger/MessageLogger.h"
#include "fhiclcpp/ParameterSet.h"

// Art include files
#include "canvas/Utilities/Exception.h"

// Some helper classes
#include "nurandom/RandomUtils/Providers/EngineId.h"
#include "nurandom/RandomUtils/Providers/EventSeedInputData.h"


namespace rndm {
  
  namespace details {
    
    template <typename SEED>
    class RandomSeedPolicyBase {
        public:
      using seed_t = SEED; 
      
      using EventData_t = NuRandomServiceHelper::EventSeedInputData;
      
      static constexpr seed_t InvalidSeed = 0;
      
      RandomSeedPolicyBase(std::string policy_name):
        name(policy_name) {}
      
      // Virtual destructor
      virtual ~RandomSeedPolicyBase() {}
      
      virtual void configure(fhicl::ParameterSet const&) {}
      
      virtual seed_t getSeed(SeedMasterHelper::EngineId const& id)
        { return createSeed(id); }
      
      virtual seed_t getEventSeed
        (SeedMasterHelper::EngineId const& id, EventData_t const& eventInfo)
        { return createEventSeed(id, eventInfo); }
      
      std::string getName() const { return name; }
      
      virtual void print(std::ostream& out) const
        { out << "Random policy: '" << getName() << "'"; }
      
      virtual bool yieldsUniqueSeeds() const override { return true; }
      
        protected:
      std::string name; 
      
      virtual seed_t createSeed(SeedMasterHelper::EngineId const&) = 0;
      
      virtual seed_t createEventSeed
        (SeedMasterHelper::EngineId const&, EventData_t const&)
        { return InvalidSeed; }
      
    }; // class RandomSeedPolicyBase
    
    
    
    template <typename SEED>
    class RangeCheckHelper {
        public:
      using seed_t = SEED;
      
      RangeCheckHelper(
        std::string maxSeedsLabel = "maxUniqueEngines",
        std::string baseSeedLabel = "baseSeed",
        std::string checkRangeLabel = "checkRange"
        )
        { SetConfigLabels(maxSeedsLabel, baseSeedLabel, checkRangeLabel); }
      
      
      void SetConfigLabels(
        std::string maxSeedsLabel = "maxUniqueEngines",
        std::string baseSeedLabel = "baseSeed",
        std::string checkRangeLabel = "checkRange"
        );
      
      bool configure(fhicl::ParameterSet const& pset);
      
      
      void SetCheck(bool doCheck = true)
        { bCheck = doCheck; hasParameters.set(pmDoCheck); }
      
      void SetBaseSeed(seed_t base_seed)
        { BaseSeed = base_seed; hasParameters.set(pmBaseSeed); }
      
      void SetNSeeds(seed_t nSeeds)
        { MaxSeeds = nSeeds; hasParameters.set(pmMaxSeeds); }
      
      bool operator() (seed_t seed) const
        {
          return
            !bCheck || ((seed >= BaseSeed) && (seed < BaseSeed + MaxSeeds));
        } // operator()
      
      void EnsureRange
        (std::string policy, SeedMasterHelper::EngineId const& id, seed_t seed)
        const;

      bool isConfigured() const;
      
      std::vector<std::string> missingConfig() const;
      
      template <typename STREAM>
      void print(STREAM& out, std::string indent = std::string()) const;
        
        protected:
      typedef enum {
        pmMaxSeeds,
        pmBaseSeed,
        pmDoCheck,
        pmNParams
      } Params_t;
      static constexpr unsigned int NParams = (unsigned int) pmNParams;
      
      std::array<std::string, NParams> paramLabels;
      std::bitset<NParams> hasParameters;
      
      bool bCheck = true; 
      seed_t BaseSeed; 
      seed_t MaxSeeds; 
      
    }; // class RangeCheckHelper
    
    
    template <typename SEED>
    void RangeCheckHelper<SEED>::SetConfigLabels(
      std::string maxSeedsLabel   /* = "maxUniqueEngines" */,
      std::string baseSeedLabel   /* = "baseSeed" */,
      std::string checkRangeLabel /* = "checkRange" */
    ) {
      paramLabels[pmMaxSeeds] = maxSeedsLabel;
      paramLabels[pmBaseSeed] = baseSeedLabel;
      paramLabels[pmDoCheck]  = checkRangeLabel;
    } // RangeCheckHelper::SetConfigLabels()
    
    
    template <typename SEED>
    bool RangeCheckHelper<SEED>::configure(fhicl::ParameterSet const& pset) {
      if (!paramLabels[pmMaxSeeds].empty()) {
        seed_t seed;
        if (pset.get_if_present(paramLabels[pmMaxSeeds], seed)) SetNSeeds(seed);
      }
      if (!paramLabels[pmBaseSeed].empty()) {
        seed_t seed;
        if (pset.get_if_present(paramLabels[pmBaseSeed], seed))
          SetBaseSeed(seed);
      }
      if (!paramLabels[pmDoCheck].empty()) {
        bool flag;
        if (pset.get_if_present(paramLabels[pmDoCheck], flag)) SetCheck(flag);
      }
      return isConfigured();
    } // RangeCheckHelper<SEED>::configure()
    
    
    template <typename SEED>
    bool RangeCheckHelper<SEED>::isConfigured() const {
      return (hasParameters.test(pmDoCheck) && !bCheck) || hasParameters.all();
    } // RangeCheckHelper<SEED>::isConfigured()
    
    
    template <typename SEED>
    void RangeCheckHelper<SEED>::EnsureRange(
      std::string policy,
      SeedMasterHelper::EngineId const& id, seed_t seed
    ) const {
      if (operator()(seed)) return;
      seed_t offset = seed - BaseSeed;
      throw art::Exception(art::errors::LogicError)
        << "NuRandomService (policy: " << policy << ") for engine: "
        << id << " the offset of seed " << seed << " is: " << offset << "."
        "\nAllowed seed offsets are in the range 0....(N-1) where N is: "
        << MaxSeeds << " (as configured in maxUniqueEngines)";
    } // RangeCheckHelper<SEED>::EnsureRange()
    
    
    template <typename SEED> template <typename STREAM>
    void RangeCheckHelper<SEED>::print
      (STREAM& out, std::string indent /* = "" */) const
    {
      if (!isConfigured())
        out << indent << "seed range checker not configured!";
      else if (bCheck)
        out << indent << "maximum number of seeds: " << MaxSeeds;
      else
        out << indent << "no limit on number of seeds.";
    } // RangeCheckHelper<SEED>::print()
    
    
    template <typename SEED>
    std::vector<std::string> RangeCheckHelper<SEED>::missingConfig() const {
      if (hasParameters.test(pmDoCheck) && !bCheck) return {};
      std::vector<std::string> missing;
      for (unsigned int i = 0; i < NParams; ++i)
        if (!hasParameters.test(i)) missing.push_back(paramLabels[i]);
      return missing;
    } // RangeCheckHelper<SEED>::missingConfig()
    
    
    
    template <typename SEED>
    class CheckedRangePolicy: public RandomSeedPolicyBase<SEED> {
        public:
      using base_t = RandomSeedPolicyBase<SEED>;
      using this_t = CheckedRangePolicy<SEED>;
      using seed_t = typename base_t::seed_t;
      
      CheckedRangePolicy
        (std::string policy_name, fhicl::ParameterSet const& pset):
        base_t(policy_name)
        { this_t::configure(pset); }
      
      virtual void configure(fhicl::ParameterSet const& pset) override
        { base_t::configure(pset); static_configure(pset); }
      
      virtual seed_t getSeed(SeedMasterHelper::EngineId const& id)
        {
          seed_t seed = this->createSeed(id);
          ensureRange(id, seed);
          return seed;
        } // getSeed()
      
      virtual void print(std::ostream& out) const override
        {
          base_t::print(out);
          range_check.print(out << "\n", "  ");
        } // print()
      
        protected:
      RangeCheckHelper<seed_t> range_check;
      
      CheckedRangePolicy(std::string policy_name): base_t(policy_name) {}
      
      virtual void ensureRange
        (SeedMasterHelper::EngineId const& id, seed_t seed) const
        { range_check.EnsureRange(this->getName(), id, seed); }
      
      void CheckRangeConfiguration() const;
      
      void static_configure(fhicl::ParameterSet const& pset);

    }; // class CheckedRangePolicy
    
    
    template <typename SEED>
    void CheckedRangePolicy<SEED>::static_configure
      (fhicl::ParameterSet const& pset)
    {
      range_check.configure(pset);
    } // CheckedRangePolicy<SEED>::static_configure()
    
    template <typename SEED>
    void CheckedRangePolicy<SEED>::CheckRangeConfiguration() const {
      if (!range_check.isConfigured()) {
        std::ostringstream sstr;
        sstr << "configuration of policy '" << this->getName()
          << "' incomplete:";
        for (std::string const& name: range_check.missingConfig())
          sstr << " " << name;
        throw art::Exception(art::errors::Configuration) << sstr.str();
      }
    } // CheckedRangePolicy<SEED>::CheckRangeConfiguration()
    
    
    
    template <typename SEED>
    class AutoIncrementPolicy: public CheckedRangePolicy<SEED> {
        public:
      using base_t = CheckedRangePolicy<SEED>;
      using this_t = AutoIncrementPolicy<SEED>;
      using seed_t = typename base_t::seed_t;
      
      AutoIncrementPolicy(fhicl::ParameterSet const& pset):
        base_t("autoIncrement")
        { this_t::configure(pset); }
      
      
      virtual void configure(fhicl::ParameterSet const& pset) override
        {
          base_t::range_check.SetConfigLabels
            ("maxUniqueEngines", "", "checkRange");
          base_t::configure(pset);
          static_configure(pset);
        } // configure()
      
      virtual void print(std::ostream& out) const override;
      
        protected:
      seed_t first_seed;
      seed_t next_seed; 
      
      virtual seed_t createSeed(SeedMasterHelper::EngineId const&) override
        { return next_seed++; }
      
      void static_configure(fhicl::ParameterSet const&);
    }; // class AutoIncrementPolicy<>
    
    
    template <typename SEED>
    void AutoIncrementPolicy<SEED>::static_configure
      (fhicl::ParameterSet const& pset)
    {
      first_seed = pset.get<seed_t>("baseSeed");
      base_t::range_check.SetBaseSeed(first_seed);
      base_t::CheckRangeConfiguration();
      next_seed = first_seed;
    } // AutoIncrementPolicy<SEED>::configure()
    
    
    template <typename SEED>
    void AutoIncrementPolicy<SEED>::print(std::ostream& out) const {
      base_t::print(out);
      out << "\n  first seed: " << first_seed;
    } // AutoIncrementPolicy<SEED>::print()
    
    
    template <typename SEED>
    class LinearMappingPolicy: public CheckedRangePolicy<SEED> {
        public:
      using base_t = CheckedRangePolicy<SEED>;
      using this_t = LinearMappingPolicy<SEED>;
      using seed_t = typename base_t::seed_t;
      
      LinearMappingPolicy(fhicl::ParameterSet const& pset):
        base_t("linearMapping")
        { this_t::configure(pset); }
      
      
      virtual void configure(fhicl::ParameterSet const& pset) override
        {
          base_t::range_check.SetConfigLabels("", "", "checkRange");
          base_t::configure(pset);
          static_configure(pset);
        }
      
      virtual void print(std::ostream& out) const override;
      
        protected:
      seed_t first_seed; 
      seed_t next_seed; 
      unsigned int nSeedsPerJob;
      
      virtual seed_t createSeed(SeedMasterHelper::EngineId const&) override
        { return next_seed++; }
      
      void static_configure(fhicl::ParameterSet const& pset);
      
    }; // class LinearMappingPolicy<>
    
    
    template <typename SEED>
    void LinearMappingPolicy<SEED>::static_configure
      (fhicl::ParameterSet const& pset)
    {
      // this code is for legacy support, and it could disappear in the future
      if (!pset.get_if_present<seed_t>("nJob", first_seed)) {
        if (!pset.get_if_present<seed_t>("baseSeed", first_seed)) {
          // this is going to fail; I am doing this just to get
          // the more appropriate error message possible
          first_seed = pset.get<seed_t>("nJob");
        }
        else {
          mf::LogWarning("SeedMaster") <<
            std::string(80, '*') <<
            "\nDEPRECATION WARNING: 'baseSeed' parameter has been deprecated"
              " for linearMapping policy, in favour of 'nJob'."
            "\nPlease update your configuration accordingly."
            << "\n" << std::string(80, '*');
        }
      }
    //  first_seed = pset.get<seed_t>("nJob");
      nSeedsPerJob = pset.get<seed_t>("maxUniqueEngines");
      first_seed *= nSeedsPerJob;
      ++first_seed; // we don't want 0 as a seed
      next_seed = first_seed;
      base_t::range_check.SetBaseSeed(next_seed);
      base_t::range_check.SetNSeeds(nSeedsPerJob);
      base_t::CheckRangeConfiguration();
    } // LinearMappingPolicy<SEED>::configure()
    
    
    template <typename SEED>
    void LinearMappingPolicy<SEED>::print(std::ostream& out) const {
      base_t::print(out);
      out
        << "\n  first seed:    " << first_seed
        << "\n  seeds per job: " << nSeedsPerJob;
    } // LinearMappingPolicy<SEED>::print()
    
    
    
    template <typename SEED>
    class PerInstancePolicy: public CheckedRangePolicy<SEED> {
        public:
      using base_t = CheckedRangePolicy<SEED>;
      using this_t = PerInstancePolicy<SEED>;
      using seed_t = typename base_t::seed_t;
      
      PerInstancePolicy(std::string name, fhicl::ParameterSet const& pset):
        base_t(name)
        { this_t::configure(pset); }
      
      virtual void configure(fhicl::ParameterSet const& pset) override
        { base_t::configure(pset); static_configure(pset); }
      
        protected:
      fhicl::ParameterSet parameters; 
      
      PerInstancePolicy(std::string name): base_t(name) {}
      
      seed_t getInstanceSeed(SeedMasterHelper::EngineId const& id) const
        { return getInstanceParameter<seed_t>(parameters, id); }
      
      
      template <typename T>
      static T getInstanceParameter
        (fhicl::ParameterSet const& pset, SeedMasterHelper::EngineId const& id);
      
      
      void static_configure(fhicl::ParameterSet const& pset);
      
    }; // class PerInstancePolicy<>
    
    
    template <typename SEED>
    void PerInstancePolicy<SEED>::static_configure
      (fhicl::ParameterSet const& pset)
    {
      parameters = pset; // copy the parameters locally
    } // PerInstancePolicy<SEED>::configure()
    
    
    // This method reads a element of type T from the instance configuration
    template <typename SEED> template <typename T>
    T PerInstancePolicy<SEED>::getInstanceParameter(
      fhicl::ParameterSet const& pset, SeedMasterHelper::EngineId const& id
    ) {
      // there must be /some/ configuration for the module
      // FIXME: use ParameterSet::has_key() as soon as it's available
      const auto cfgKeys = pset.get_names();
      if (std::find(cfgKeys.begin(), cfgKeys.end(), id.moduleLabel) == cfgKeys.end()) {
        throw art::Exception(art::errors::Configuration)
          << "A seed for the nameless instance '" << id
          << "' was requested, but there is no configuration for '"
          << id.moduleLabel << "' module label.";
      }
      
      T param;
      if (!id.hasInstanceName()) { // Case 1: no instance name.
        // We expect the element to be just an item.
        if (pset.is_key_to_table(id.moduleLabel)) {
          // this is mostly a limitation of the FHiCL syntax,
          // that we can overcome with some cumbersomeness if we need to.
          throw art::Exception(art::errors::Configuration)
            << "A seed for the nameless instance '" << id
            << "' was requested, but the configuration sets named instances ("
            << pset.get<fhicl::ParameterSet>(id.moduleLabel).to_compact_string()
            << ").\nNameless and named engine instances can't coexist.";
        }
        if (!pset.get_if_present(id.moduleLabel, param)) {
          throw art::Exception(art::errors::Configuration)
            << "NuRandomService: unable to find the parameter for '" << id << "'";
        }
      } // if no instance name
      else { // Case 2: instance name is given.
        
        if (pset.is_key_to_atom(id.moduleLabel)) {
          // see above
          throw art::Exception(art::errors::Configuration)
            << "A seed for '" << std::string(id) << "' was requested,"
               " but the configuration sets a nameless instance of '"
            << id.moduleLabel << "'.\n"
            << "Nameless and named engine instances can't coexist.";
        }
        fhicl::ParameterSet subSet;
        if (!pset.get_if_present(id.moduleLabel, subSet)) {
          throw art::Exception(art::errors::Configuration)
            << "NuRandomService: unable to find the parameter block for: '"
            << id << "'";
        }
        
        if (!subSet.get_if_present(id.instanceName, param)) {
          throw art::Exception(art::errors::Configuration)
            << "NuRandomService: unable to find the parameter value for: '"
            << id << "'";
        }
      } // if instance name
      
      return param;
    } // PerInstancePolicy<SEED>::getInstanceParameter<>()
    
    
    template <typename SEED>
    class PredefinedSeedPolicy: public PerInstancePolicy<SEED> {
        public:
      using base_t = PerInstancePolicy<SEED>;
      using this_t = PredefinedSeedPolicy<SEED>;
      using seed_t = typename base_t::seed_t;
      
      PredefinedSeedPolicy(fhicl::ParameterSet const& pset):
        base_t("preDefinedSeed")
        { this_t::configure(pset); }
      
      
      virtual void configure(fhicl::ParameterSet const& pset) override
        { base_t::configure(pset); static_configure(pset); }
      
      virtual void print(std::ostream& out) const override;
      
      
      virtual bool yieldsUniqueSeeds() const override { return false; }
      
        protected:
      
      virtual seed_t createSeed(SeedMasterHelper::EngineId const& id) override
        { return base_t::getInstanceSeed(id); }
      
      void static_configure(fhicl::ParameterSet const&)
        { base_t::range_check.SetCheck(false); }
      
    }; // class PredefinedSeedPolicy<>
    
    
    template <typename SEED>
    void PredefinedSeedPolicy<SEED>::print(std::ostream& out) const {
      base_t::print(out);
      out << "\n  seeds directly from the configuration";
    } // PredefinedSeedPolicy<SEED>::print()
    
    
    
    template <typename SEED>
    class PredefinedOffsetPolicy: public PerInstancePolicy<SEED> {
        public:
      using base_t = PerInstancePolicy<SEED>;
      using this_t = PredefinedOffsetPolicy<SEED>;
      using seed_t = typename base_t::seed_t;
      
      PredefinedOffsetPolicy(fhicl::ParameterSet const& pset):
        base_t("preDefinedOffset")
        { this_t::configure(pset); }
      
      
      virtual void configure(fhicl::ParameterSet const& pset) override
        {
          base_t::range_check.SetConfigLabels
            ("maxUniqueEngines", "", "checkRange");
          base_t::configure(pset);
          static_configure(pset);
        }
      
      virtual void print(std::ostream& out) const override;
      
        protected:
      seed_t base_seed;
      
      virtual seed_t createSeed(SeedMasterHelper::EngineId const& id) override
        { return base_seed + base_t::getInstanceSeed(id); }
      
      void static_configure(fhicl::ParameterSet const&);
      
    }; // class PredefinedOffsetPolicy<>
    
    
    template <typename SEED>
    void PredefinedOffsetPolicy<SEED>::static_configure
      (fhicl::ParameterSet const& pset)
    {
      base_seed = pset.get<seed_t>("baseSeed");
      base_t::range_check.SetBaseSeed(base_seed);
      base_t::CheckRangeConfiguration();
    } // PredefinedOffsetPolicy<SEED>::configure()
    
    
    template <typename SEED>
    void PredefinedOffsetPolicy<SEED>::print(std::ostream& out) const {
      base_t::print(out);
      out << "\n  base seed: " << base_seed;
    } // PredefinedOffsetPolicy<SEED>::print()
    
    
    
    template <typename SEED>
    class RandomPolicy: public RandomSeedPolicyBase<SEED> {
        public:
      using base_t = RandomSeedPolicyBase<SEED>;
      using this_t = RandomPolicy<SEED>;
      using seed_t = typename base_t::seed_t;
      
      RandomPolicy(fhicl::ParameterSet const& pset): base_t("random")
        { this_t::configure(pset); }
      
      
      virtual void configure(fhicl::ParameterSet const& pset) override;
      
      virtual void print(std::ostream& out) const override;
      
      
        private:
      class RandomImpl {
          public:
        RandomImpl(seed_t master_seed, seed_t min_seed, seed_t max_seed):
          seed(master_seed),
          generator(master_seed), distribution(min_seed, max_seed)
          {}
        
        seed_t master_seed() const { return seed; }
        seed_t min() const { return distribution.min(); }
        seed_t max() const { return distribution.max(); }
        seed_t operator() () { return distribution(generator); }
        
          private:
        seed_t seed; 
        std::default_random_engine generator; 
        std::uniform_int_distribution<seed_t> distribution; 
      }; // RandomImpl
      
      std::unique_ptr<RandomImpl> random_seed;
      
      virtual seed_t createSeed(SeedMasterHelper::EngineId const&) override
        { return (*random_seed)(); }
      
    }; // class RandomPolicy<>
    
    
    template <typename SEED>
    void RandomPolicy<SEED>::configure(fhicl::ParameterSet const& pset) {
      constexpr seed_t MagicMaxSeed = 900000000;
      seed_t master_seed = 0;
      if (!pset.get_if_present("masterSeed", master_seed)) {
        // get the base seed randomly too, from the clock,
        // and within [1; MagicMaxSeed]
        master_seed = 1 +
          std::chrono::system_clock::now().time_since_epoch().count()
          % MagicMaxSeed;
      }
      random_seed.reset(new RandomImpl(master_seed, 1, MagicMaxSeed));
    } // RandomPolicy<SEED>::configure()
    
    
    template <typename SEED>
    void RandomPolicy<SEED>::print(std::ostream& out) const {
      base_t::print(out);
      out
        << "\n  master seed: " << random_seed->master_seed()
        << "\n  seed within: [ " << random_seed->min()
                << " ; " << random_seed->max() << " ]"
        ;
    } // RandomPolicy<SEED>::print()
    
    
  } // namespace details
  
} // namespace rndm


#endif // NURANDOM_RANDOMUTILS_PROVIDERS_BASEPOLICY_H