SeedMaster.h

Go to the documentation of this file.

#ifndef NUTOOLS_RANDOMUTILS_PROVIDERS_SEEDMASTER_H
#define NUTOOLS_RANDOMUTILS_PROVIDERS_SEEDMASTER_H 1

// C/C++ standard libraries
#include <vector>
#include <string>
#include <map>
#include <memory> // std::unique_ptr<>
#include <utility> // std::forward()

// From art and its tool chain
#include "fhiclcpp/ParameterSet.h"
#include "canvas/Utilities/Exception.h"

// Some helper classes
#include "nutools/RandomUtils/Providers/MapKeyIterator.h"
#include "nutools/RandomUtils/Providers/EngineId.h"
#include "nutools/RandomUtils/Providers/Policies.h"
#include "nutools/RandomUtils/Providers/EventSeedInputData.h"

// more headers included in the implementation section below


// The master list of all the policies
#define SEED_SERVICE_POLICIES                   \
  SEED_SERVICE_POLICY(unDefined)                \
  SEED_SERVICE_POLICY(autoIncrement)            \
  SEED_SERVICE_POLICY(linearMapping)            \
  SEED_SERVICE_POLICY(preDefinedOffset)         \
  SEED_SERVICE_POLICY(preDefinedSeed)           \
  SEED_SERVICE_POLICY(random)                   \
  SEED_SERVICE_POLICY(perEvent)                 \
  


namespace rndm {
  
  template <typename SEED>
  class SeedMaster {
      public:
    using seed_t = SEED;                   
    using SeedMaster_t = SeedMaster<SEED>; 
      
    using EngineId = SeedMasterHelper::EngineId; 
    
    using Seeder_t = std::function<void(EngineId const&, seed_t)>;
    
      private:
    using PolicyImpl_t = details::RandomSeedPolicyBase<seed_t>;
    
    using map_type = std::map<EngineId, seed_t>;
    
    struct EngineInfo_t {
        public:
      bool hasSeeder() const { return bool(seeder); }
      bool isFrozen() const  { return !autoseed; }
      
      void freeze(bool doFreeze = true) { autoseed = !doFreeze; }
      void setSeeder(Seeder_t new_seeder) { seeder = new_seeder; }
      
      template <typename... Args>
      void applySeed(Args... args) const
        { if (hasSeeder()) seeder(std::forward<Args>(args)...); }
      
      template <typename... Args>
      void autoApplySeed(Args... args) const
        { if (!isFrozen()) applySeed(std::forward<Args>(args)...); }
      
        private:
      Seeder_t seeder;      
      bool autoseed = true; 
      
    }; // EngineInfo_t
    
    using EngineData_t = std::map<EngineId, EngineInfo_t>;
    
      public:
    using EventData_t = typename PolicyImpl_t::EventData_t;
    
    static constexpr seed_t InvalidSeed = PolicyImpl_t::InvalidSeed;
    
    enum Policy {
#define SEED_SERVICE_POLICY(x) x,
      SEED_SERVICE_POLICIES
#undef SEED_SERVICE_POLICY
    };
    
    static const std::vector<std::string>& policyNames();
    
    using EngineInfoIteratorBox
      = NuRandomServiceHelper::MapKeyConstIteratorBox<EngineData_t>;
    
    SeedMaster(const fhicl::ParameterSet&);
    
    // Accept compiler written c'tors, assignments and d'tor.
    
    bool hasEngine(EngineId const& id) const
      { return engineData.count(id) > 0; }
    
    bool hasSeeder(EngineId const& id) const
      { 
        auto iEngineInfo = engineData.find(id);
        return
          (iEngineInfo != engineData.end()) && iEngineInfo->second.hasSeeder();
      }
    
    seed_t getSeed(std::string moduleLabel);
    
    seed_t getSeed(std::string moduleLabel, std::string instanceName);
    
    seed_t getSeed(EngineId const&);
    
    seed_t getEventSeed
      (EventData_t const& data, std::string instanceName);
    seed_t getEventSeed(EventData_t const& data, EngineId const& id);
    
    seed_t getCurrentSeed(EngineId const& id) const
      { return getSeedFromMap(currentSeeds, id); }
    
    
    void registerSeeder(EngineId const& id, Seeder_t seeder);
    
    
    void registerNewSeeder(EngineId const& id, Seeder_t seeder);
    
    
    void freezeSeed(EngineId const& id, seed_t seed);
    
    
    seed_t reseed(EngineId const& id);
    
    seed_t reseedEvent(EngineId const& id, EventData_t const& data);
    
    template<typename Stream> void print(Stream&&) const;
    
    EngineInfoIteratorBox engineIDsRange() const { return { engineData }; }
    
    void onNewEvent();
    
    void print() const { print(mf::LogVerbatim("SEEDS")); }    
    
      private:
    int verbosity;
    
    Policy policy;
    
    map_type configuredSeeds;
    
    map_type knownEventSeeds;
    
    map_type currentSeeds;
    
    EngineData_t engineData; 

    void setPolicy(std::string policyName);
    
    void ensureUnique
      (EngineId const& id, seed_t seed, map_type const& map) const;
    void ensureUnique(EngineId const& id, seed_t seed) const
      { return ensureUnique(id, seed, configuredSeeds); }
    
    std::unique_ptr<PolicyImpl_t> policy_impl;
    
    
    static seed_t getSeedFromMap(map_type const& seeds, EngineId const& id)
      {
        auto iSeed = seeds.find(id);
        return (iSeed == seeds.end())? InvalidSeed: iSeed->second;
      }
    
  }; // class SeedMaster
  
} // namespace rndm


//==============================================================================
//===  Template implementation
//===


// C++ include files
#include <ostream>
#include <iomanip> // std::setw()
#include <ostream> // std::endl
#include <algorithm> // std::find(), std::copy()
#include <iterator> // std::ostream_iterator<>, std::distance()

// Supporting library include files
#include "messagefacility/MessageLogger/MessageLogger.h"

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


//----------------------------------------------------------------------------
template <typename SEED>
std::vector<std::string> const& rndm::SeedMaster<SEED>::policyNames() {
  static std::vector<std::string> names;
  if(names.empty()) {
    const char *cnames[] = {
#define SEED_SERVICE_POLICY(x) #x,
      SEED_SERVICE_POLICIES
#undef SEED_SERVICE_POLICY
    };
    names = std::vector<std::string>
      (cnames, cnames + sizeof(cnames)/sizeof(cnames[0]));
  }

  return names;
} // SeedMaster<SEED>::policyNames()



//----------------------------------------------------------------------------
template <typename SEED>
rndm::SeedMaster<SEED>::SeedMaster(fhicl::ParameterSet const& pSet):
  verbosity(pSet.get<int>("verbosity",0)),
  policy(unDefined),
  configuredSeeds(),
  knownEventSeeds(),
  currentSeeds(),
  engineData()
{
  
  // Throw if policy is not recognized.
  const std::string strPolicy = pSet.get<std::string>("policy");
  setPolicy(strPolicy);
  
  // Finish parsing the parameter set, as required by the selected policy
  switch(policy) {
  case autoIncrement:
    policy_impl.reset(new details::AutoIncrementPolicy<seed_t>(pSet));
    break;
  case linearMapping:
    policy_impl.reset(new details::LinearMappingPolicy<seed_t>(pSet));
    break;
  case preDefinedOffset:
    policy_impl.reset(new details::PredefinedOffsetPolicy<seed_t>(pSet));
    break;
  case preDefinedSeed:
    policy_impl.reset(new details::PredefinedSeedPolicy<seed_t>(pSet));
    break;
  case random:
    policy_impl.reset(new details::RandomPolicy<seed_t>(pSet));
    break;
  case perEvent:
    policy_impl.reset(new details::PerEventPolicy<seed_t>(pSet));
    break;
  default:
    throw art::Exception(art::errors::LogicError)
      << "SeedMaster(): Internal error: unknown policy_ value";
  } // switch
  
  if ( verbosity > 0 )
    print(mf::LogVerbatim("SeedMaster"));
  
} // SeedMaster<SEED>::SeedMaster()



//----------------------------------------------------------------------------
template <typename SEED>
inline typename rndm::SeedMaster<SEED>::seed_t
rndm::SeedMaster<SEED>::getSeed
  (std::string moduleLabel)
{
  return getSeed(EngineId(moduleLabel));
} // SeedMaster<SEED>::getSeed(string)


//----------------------------------------------------------------------------
template <typename SEED>
typename rndm::SeedMaster<SEED>::seed_t rndm::SeedMaster<SEED>::getSeed
  (std::string moduleLabel, std::string instanceName)
{
  return getSeed(EngineId(moduleLabel,instanceName));
} // SeedMaster<SEED>::getSeed(string, string)


//----------------------------------------------------------------------------
template <typename SEED>
void rndm::SeedMaster<SEED>::registerSeeder
  (EngineId const& id, Seeder_t seeder)
{
  engineData[id].setSeeder(seeder); // creates anew and sets
} // SeedMaster<SEED>::registerSeeder()


//----------------------------------------------------------------------------
template <typename SEED>
void rndm::SeedMaster<SEED>::registerNewSeeder
  (EngineId const& id, Seeder_t seeder)
{
  if (hasEngine(id)) {
    throw art::Exception(art::errors::LogicError)
      << "SeedMaster(): Engine with ID='" << id << "' already registered";
  }
  registerSeeder(id, seeder);
} // SeedMaster<SEED>::registerNewSeeder()


//----------------------------------------------------------------------------
template <typename SEED>
void rndm::SeedMaster<SEED>::freezeSeed(EngineId const& id, seed_t seed) {
  engineData.at(id).freeze();
  configuredSeeds[id] = seed;
  currentSeeds[id] = seed;
} // SeedMaster<>::freezeSeed()


//----------------------------------------------------------------------------
template <typename SEED>
typename rndm::SeedMaster<SEED>::seed_t rndm::SeedMaster<SEED>::reseed
  (EngineId const& id)
{
  auto const& engineInfo = engineData.at(id);
  if (engineInfo.isFrozen()) return InvalidSeed;
  seed_t seed = getSeed(id);
  if (seed != InvalidSeed) { // reseed
    engineInfo.applySeed(id, seed);
  }
  return seed;
} // SeedMaster<SEED>::reseed()


template <typename SEED>
typename rndm::SeedMaster<SEED>::seed_t rndm::SeedMaster<SEED>::reseedEvent
  (EngineId const& id, EventData_t const& data)
{
  auto const& engineInfo = engineData.at(id);
  if (engineInfo.isFrozen()) return InvalidSeed;
  seed_t seed = getEventSeed(data, id);
  if (seed != InvalidSeed) { // reseed
    engineInfo.autoApplySeed(id, seed);
  }
  return seed;
} // SeedMaster<SEED>::reseedEvent()



//----------------------------------------------------------------------------
template <typename SEED> template <typename Stream>
void rndm::SeedMaster<SEED>::print(Stream&& log) const {
  log << "\nSummary of seeds computed by the NuRandomService";
  
  // allow the policy implementation to print whatever it feels to
  std::ostringstream sstr;
  policy_impl->print(sstr);
  if (!sstr.str().empty()) log << '\n' << sstr.str();
  
  if ( !currentSeeds.empty() ) {
    
    constexpr unsigned int ConfSeedWidth = 18;
    constexpr unsigned int SepWidth1 = 2;
    constexpr unsigned int LastSeedWidth = 18;
    constexpr unsigned int SepWidth2 = SepWidth1 + 1;
    
    log << "\n "
      << std::setw(ConfSeedWidth) << "Configured value"
      << std::setw(SepWidth1) << ""
      << std::setw(LastSeedWidth) << "Last value"
      << std::setw(SepWidth2) << ""
      << "ModuleLabel.InstanceName";
    
    for (auto const& p: currentSeeds) {
      EngineId const& ID = p.first;
      seed_t configuredSeed = getSeedFromMap(configuredSeeds, ID);
      seed_t currentSeed = p.second;
      
      if (configuredSeed == InvalidSeed) {
        if (currentSeed == InvalidSeed) {
          log << "\n "
            << std::setw(ConfSeedWidth) << "INVALID!!!"
            << std::setw(SepWidth1) << ""
            << std::setw(LastSeedWidth) << ""
            << std::setw(SepWidth2) << ""
            << ID;
        }
        else { // if seed was configured, it should be that one all the way!!
          log << "\n "
            << std::setw(ConfSeedWidth) << "(per event)"
            << std::setw(SepWidth1) << ""
            << std::setw(LastSeedWidth) << currentSeed
            << std::setw(SepWidth2) << ""
            << ID;
        }
      }
      else {
        if (configuredSeed == currentSeed) {
          log << "\n "
            << std::setw(ConfSeedWidth) << configuredSeed
            << std::setw(SepWidth1) << ""
            << std::setw(LastSeedWidth) << "(same)"
            << std::setw(SepWidth2) << ""
            << ID;
        }
        else { // if seed was configured, it should be that one all the way!!
          log << "\n "
            << std::setw(ConfSeedWidth) << configuredSeed
            << std::setw(SepWidth1) << ""
            << std::setw(LastSeedWidth) << currentSeed
            << std::setw(SepWidth2) << ""
            << ID << "  [[ERROR!!!]]";
        }
      } // if per job
      if (ID.isGlobal()) log << " (global)";
      if (hasEngine(ID) && engineData.at(ID).isFrozen()) log << " [overridden]";
    } // for all seeds
  } // if any seed
  log << '\n' << std::endl;
} // SeedMaster<SEED>::print(Stream)


//----------------------------------------------------------------------------
template <typename SEED>
typename rndm::SeedMaster<SEED>::seed_t rndm::SeedMaster<SEED>::getSeed
  (EngineId const& id)
{
  // Check for an already computed seed.
  typename map_type::const_iterator iSeed = configuredSeeds.find(id);
  seed_t seed = InvalidSeed;
  if (iSeed != configuredSeeds.end()) return iSeed->second;

  // Compute the seed.
  seed = policy_impl->getSeed(id);
  if (policy_impl->yieldsUniqueSeeds()) ensureUnique(id, seed);
  
  // Save the result.
  configuredSeeds[id] = seed;
  
  // for per-event policies, configured seed is invalid;
  // in that case we don't expect to change the seed,
  // and we should not record it as current; this should not matter anyway
  // we still store it if there is nothing (emplace does not overwrite)
  if (seed != InvalidSeed) currentSeeds[id] = seed;
  else                     currentSeeds.emplace(id, seed);
  
  return seed;
} // SeedMaster<SEED>::getSeed()


//----------------------------------------------------------------------------
template <typename SEED>
typename rndm::SeedMaster<SEED>::seed_t rndm::SeedMaster<SEED>::getEventSeed
  (EventData_t const& data, EngineId const& id)
{
  // Check for an already computed seed.
  typename map_type::iterator iSeed = knownEventSeeds.find(id);
  seed_t seed = InvalidSeed;
  if (iSeed != knownEventSeeds.end()) return iSeed->second;

  // Compute the seed.
  seed = policy_impl->getEventSeed(id, data);
  if ((seed != InvalidSeed) && policy_impl->yieldsUniqueSeeds())
    ensureUnique(id, seed, knownEventSeeds);
    
  // Save the result.
  knownEventSeeds[id] = seed;
  
  // for configured-seed policies, per-event seed is invalid;
  // in that case we don't expect to change the seed,
  // and we should not record it as current
  // we still store it if there is nothing (emplace does not overwrite)
  if (seed != InvalidSeed) currentSeeds[id] = seed;
  else                     currentSeeds.emplace(id, seed);
  
  return seed;
} // SeedMaster<SEED>::getEventSeed(EngineId)


template <typename SEED>
typename rndm::SeedMaster<SEED>::seed_t rndm::SeedMaster<SEED>::getEventSeed
  (EventData_t const& data, std::string instanceName)
{
  return getEventSeed(data, EngineId(data.moduleLabel, instanceName));
} // SeedMaster<SEED>::getEventSeed(string)



//----------------------------------------------------------------------------
template <typename SEED>
inline void rndm::SeedMaster<SEED>::onNewEvent() {
  // forget all we know about the current event
  knownEventSeeds.clear();
} // SeedMaster<SEED>::onNewEvent()


//----------------------------------------------------------------------------
template <typename SEED>
void rndm::SeedMaster<SEED>::setPolicy(std::string policyName) {
  
  std::vector<std::string>::const_iterator iter
    = std::find(policyNames().begin(), policyNames().end(), policyName);
  if (iter != policyNames().end()) {
    policy = Policy(std::distance(policyNames().begin(), iter));
  }
  
  if (policy == unDefined) {
    std::ostringstream os;
    os<< "NuRandomService::setPolicy(): Unrecognized policy: "
      << policyName
      << "\n Known policies are: ";
    
    std::copy(policyNames().begin(), policyNames().end(),
      std::ostream_iterator<std::string>(os, ", "));
    
    throw art::Exception(art::errors::Configuration) << os.str();
  }
} // SeedMaster<SEED>::setPolicy()


//----------------------------------------------------------------------------
template <typename SEED>
void rndm::SeedMaster<SEED>::ensureUnique
  (EngineId const& id, seed_t seed, map_type const& seeds) const
{
  
  for (auto const& p: seeds) {
    
    // Do not compare to self
    if ( p.first == id ) continue;
    
    if ( p.second == seed ){
      throw art::Exception(art::errors::LogicError)
        << "NuRandomService::ensureUnique() seed: "<<seed
        << " already used by module.instance: " << p.first << "\n"
        << "May not be reused by module.instance: " << id;
    }
  } // for
} // SeedMaster<SEED>::ensureUnique()


#endif // NUTOOLS_RANDOMUTILS_PROVIDERS_SEEDMASTER_H