NuRandomService.h

Go to the documentation of this file.

#ifndef NURANDOM_RANDOMUTILS_NuRandomService_H
#define NURANDOM_RANDOMUTILS_NuRandomService_H 1

#ifndef NURANDOM_RANDOMUTILS_NuRandomService_USECLHEP
#  define NURANDOM_RANDOMUTILS_NuRandomService_USECLHEP 1
#endif // NURANDOM_RANDOMUTILS_NuRandomService_USECLHEP

// ROOT libraries
#ifndef NURANDOM_RANDOMUTILS_NuRandomService_USEROOT
#  define NURANDOM_RANDOMUTILS_NuRandomService_USEROOT 0
#endif // NURANDOM_RANDOMUTILS_NuRandomService_USEROOT


// C/C++ standard libraries
#include <functional>
#include <string>
#include <utility> // std::forward()
#include <initializer_list>

// Some helper classes.
#include "nurandom/RandomUtils/ArtState.h"
#include "nurandom/RandomUtils/Providers/SeedMaster.h"

// CLHEP libraries
#if (NURANDOM_RANDOMUTILS_NuRandomService_USECLHEP)
#  include "CLHEP/Random/RandomEngine.h"
#endif // NURANDOM_RANDOMUTILS_NuRandomService_USECLHEP

// ROOT libraries
#if (NURANDOM_RANDOMUTILS_NuRandomService_USEROOT)
#  include "TRandom.h"
#endif // NURANDOM_RANDOMUTILS_NuRandomService_USEROOT

// From art and its tool chain.
#include "fhiclcpp/types/OptionalAtom.h"
#include "fhiclcpp/ParameterSet.h"
#include "art/Framework/Core/detail/EngineCreator.h"
#include "art/Framework/Services/Optional/RandomNumberGenerator.h"
#include "art/Framework/Services/Registry/ServiceDeclarationMacros.h"
#include "art/Persistency/Provenance/ScheduleContext.h"

// Forward declarations
namespace art {
  class ActivityRegistry;
  class ModuleDescription;
  class ModuleContext;
  class Run;
  class SubRun;
}

namespace rndm {

  using seed_t = art::detail::EngineCreator::seed_t;

  using SeedAtom = fhicl::OptionalAtom<seed_t>;

  class NuRandomService {
      public:
    using seed_t = art::detail::EngineCreator::seed_t;
    using engine_t = CLHEP::HepRandomEngine;

    using SeedMaster_t = SeedMaster<seed_t>; 

    using EngineId = SeedMaster_t::EngineId; 

    static constexpr seed_t InvalidSeed = SeedMaster_t::InvalidSeed;

    NuRandomService(const fhicl::ParameterSet&, art::ActivityRegistry&);

    // Accept compiler written d'tor.  Not copyable or assignable.
    // This class is not copyable or assignable: these methods are not implemented.
    NuRandomService(NuRandomService const&) = delete;
    NuRandomService const& operator=(NuRandomService const&) = delete;
    NuRandomService(NuRandomService&&) = delete;
    NuRandomService const& operator=(NuRandomService&&) = delete;
    ~NuRandomService() = default;

    static constexpr bool isSeedValid(seed_t seed)
      { return seed != InvalidSeed; }


    seed_t getSeed
      (std::string const& moduleLabel, std::string const& instanceName);

    seed_t getSeed(std::string instanceName = "");


    seed_t getGlobalSeed(std::string instanceName);


    seed_t getCurrentSeed(std::string instanceName) const
      { return seeds.getCurrentSeed(qualify_engine_label(instanceName)); }

    seed_t getCurrentSeed() const
      { return seeds.getCurrentSeed(qualify_engine_label()); }

    seed_t getGlobalCurrentSeed(std::string instanceName) const
      { return seeds.getCurrentSeed(qualify_global_engine(instanceName)); }


    // --- BEGIN --- Create and register an engine -----------------------------
#if (NURANDOM_RANDOMUTILS_NuRandomService_USECLHEP)


    std::reference_wrapper<NuRandomService::engine_t> registerAndSeedEngine(
      engine_t& engine,
      std::string type = "", std::string instance = "",
      std::optional<seed_t> const seed = std::nullopt
      );

    [[nodiscard]] std::reference_wrapper<engine_t> registerAndSeedEngine(
      engine_t& engine, std::string type, std::string instance,
      SeedAtom const& seedParam
      );

    [[nodiscard]] std::reference_wrapper<engine_t> registerAndSeedEngine
      (engine_t& engine, std::string type, SeedAtom const& seedParam)
      { return registerAndSeedEngine(engine, type, "", seedParam); }

    [[nodiscard]] std::reference_wrapper<engine_t> registerAndSeedEngine
      (engine_t& engine, SeedAtom const& seedParam)
      { return registerAndSeedEngine(engine, "", "", seedParam); }

    [[nodiscard]] std::reference_wrapper<engine_t> registerAndSeedEngine(
      engine_t& engine, std::string type, std::string instance,
      fhicl::ParameterSet const& pset, std::string pname
      )
      { return registerAndSeedEngine(engine, type, instance, pset, { pname }); }

    [[nodiscard]] std::reference_wrapper<engine_t> registerAndSeedEngine(
      engine_t& engine, std::string type, std::string instance,
      fhicl::ParameterSet const& pset, std::initializer_list<std::string> pnames
      );


    [[nodiscard]] std::reference_wrapper<engine_t> registerAndSeedEngine(
      engine_t& engine, std::string type,
      fhicl::ParameterSet const& pset, std::string pname
      )
      { return registerAndSeedEngine(engine, type, "", pset, pname); }

    [[nodiscard]] std::reference_wrapper<engine_t> registerAndSeedEngine(
      engine_t& engine, std::string type,
      fhicl::ParameterSet const& pset, std::initializer_list<std::string> pnames
      )
      { return registerAndSeedEngine(engine, type, "", pset, pnames); }

    [[nodiscard]] std::reference_wrapper<engine_t> registerAndSeedEngine(
      engine_t& engine,
      fhicl::ParameterSet const& pset, std::string pname
      )
      { return registerAndSeedEngine(engine, pset, { pname }); }

    [[nodiscard]] std::reference_wrapper<engine_t> registerAndSeedEngine(
      engine_t& engine,
      fhicl::ParameterSet const& pset, std::initializer_list<std::string> pnames
      )
      { return registerAndSeedEngine(engine, "", "", pset, pnames); }

#endif // NURANDOM_RANDOMUTILS_NuRandomService_USECLHEP
    // --- END --- Create and register an engine -------------------------------



    // --- BEGIN --- Register an existing engine -------------------------------

    seed_t registerEngine(
      SeedMaster_t::Seeder_t seeder, std::string const instance = "",
      std::optional<seed_t> const seed = std::nullopt
      );


    seed_t registerEngine(
      SeedMaster_t::Seeder_t seeder, std::string const instance,
      SeedAtom const& seedParam
      );

    seed_t registerEngine
      (SeedMaster_t::Seeder_t seeder, SeedAtom const& seedParam)
      { return registerEngine(seeder, "", seedParam); }

    seed_t registerEngine(
      SeedMaster_t::Seeder_t seeder, std::string instance,
      fhicl::ParameterSet const& pset, std::string pname
      )
      { return registerEngine(seeder, instance, pset, { pname }); }

    seed_t registerEngine(
      SeedMaster_t::Seeder_t seeder, std::string instance,
      fhicl::ParameterSet const& pset, std::initializer_list<std::string> pnames
      );

    seed_t registerEngine(
      SeedMaster_t::Seeder_t seeder,
      fhicl::ParameterSet const& pset, std::string pname
      )
      { return registerEngine(seeder, "", pset, pname); }

    seed_t registerEngine(
      SeedMaster_t::Seeder_t seeder,
      fhicl::ParameterSet const& pset, std::initializer_list<std::string> pnames
      )
      { return registerEngine(seeder, "", pset, pnames); }

#if (NURANDOM_RANDOMUTILS_NuRandomService_USECLHEP)

    seed_t registerEngine
      (CLHEP::HepRandomEngine& engine, std::string instance = "")
      { return registerEngine(CLHEPengineSeeder(engine), instance); }

    seed_t registerEngine(
      CLHEP::HepRandomEngine& engine, std::string instance,
      SeedAtom const& seedParam
      )
      { return registerEngine(CLHEPengineSeeder(engine), instance, seedParam); }

    seed_t registerEngine(
      CLHEP::HepRandomEngine& engine, std::string instance,
      fhicl::ParameterSet const& pset, std::initializer_list<std::string> pnames
      )
      {
        return registerEngine
          (CLHEPengineSeeder(engine), instance, pset, pnames);
      }
#endif // NURANDOM_RANDOMUTILS_NuRandomService_USECLHEP

    // --- END --- Register an existing engine ---------------------------------



    seed_t declareEngine(std::string instance = "");

    seed_t declareEngine
      (std::string instance, fhicl::ParameterSet const& pset, std::string pname)
      { return declareEngine(instance, pset, { pname }); }

    seed_t declareEngine(
      std::string instance,
      fhicl::ParameterSet const& pset, std::initializer_list<std::string> pnames
      );

    seed_t declareEngine(fhicl::ParameterSet const& pset, std::string pname)
      { return declareEngine("", pset, pname); }

    seed_t declareEngine(
      fhicl::ParameterSet const& pset, std::initializer_list<std::string> pnames
      )
      { return declareEngine("", pset, pnames); }


    seed_t defineEngine
      (SeedMaster_t::Seeder_t seeder, std::string instance = {});

#if (NURANDOM_RANDOMUTILS_NuRandomService_USECLHEP)

    seed_t defineEngine
      (CLHEP::HepRandomEngine& engine, std::string instance = {})
      { return defineEngine(CLHEPengineSeeder(engine), instance); }
#endif // NURANDOM_RANDOMUTILS_NuRandomService_USECLHEP


    template<class Stream>
    void print(Stream&& out) const
      { seeds.print(std::forward<Stream>(out)); }

    void print() const { print(mf::LogInfo("NuRandomService")); }

#if (NURANDOM_RANDOMUTILS_NuRandomService_USEROOT)
    class TRandomSeeder {
        public:
      TRandomSeeder(TRandom* engine): pRandom(engine) {}
      void operator() (EngineId const&, seed_t seed)
        { if (pRandom) pRandom->SetSeed(seed); }
        protected:
      TRandom* pRandom = nullptr;
    }; // class TRandomSeeder
#endif // NURANDOM_RANDOMUTILS_NuRandomService_USEROOT

#if (NURANDOM_RANDOMUTILS_NuRandomService_USECLHEP)
    class CLHEPengineSeeder {
        public:
      CLHEPengineSeeder(CLHEP::HepRandomEngine& e): engine(e) {}
      CLHEPengineSeeder(CLHEP::HepRandomEngine* e): engine(*e) {}
      void operator() (EngineId const&, seed_t seed)
        {
          engine.setSeed(seed, 0);
          MF_LOG_DEBUG("CLHEPengineSeeder")
            << "CLHEP engine: '" << engine.name() << "'[" << ((void*) &engine)
            << "].setSeed(" << seed << ", 0)";
        }
        protected:
      CLHEP::HepRandomEngine& engine;
    }; // class CLHEPengineSeeder
#endif // NURANDOM_RANDOMUTILS_NuRandomService_USECLHEP

  private:

    SeedMaster_t seeds;

    NuRandomServiceHelper::ArtState state;

    int verbosity = 0;
    bool bPrintEndOfJobSummary = false; 

    seed_t registerEngineID(
      EngineId const& id,
      SeedMaster_t::Seeder_t seeder = SeedMaster_t::Seeder_t()
      );

    seed_t defineEngineID(EngineId const& id, SeedMaster_t::Seeder_t seeder);


    bool hasEngine(EngineId const& id) const { return seeds.hasEngine(id); }

    // Main logic for computing and validating a seed.
    seed_t getSeed(EngineId const&);

    // Main logic for computing and validating a seed.
    seed_t getEventSeed(EngineId const&);

    seed_t reseedInstance(EngineId const& id);

    void reseedModule(std::string currentModule);
    void reseedModule();

    void reseedGlobal();

    seed_t prepareEngine(EngineId const& id, SeedMaster_t::Seeder_t seeder);

    // Helper functions for all policies
    void ensureValidState(bool bGlobal = false) const;

    EngineId qualify_engine_label
      (std::string moduleLabel, std::string instanceName) const;
    EngineId qualify_engine_label(std::string instanceName = "") const;
    EngineId qualify_global_engine(std::string instanceName = "") const
      { return EngineId(instanceName, EngineId::global); }

    static std::optional<seed_t> readSeedParameter
      (fhicl::ParameterSet const& pset, std::string pname)
      { return readSeedParameter(pset, { pname }); }
    static std::optional<seed_t> readSeedParameter(
      fhicl::ParameterSet const& pset,
      std::initializer_list<std::string> pnames
      );
    static std::optional<seed_t> readSeedParameter(SeedAtom const& param);

    seed_t querySeed(EngineId const& id);


    std::pair<seed_t, bool> extractSeed
      (EngineId const& id, std::optional<seed_t> seed);

    void freezeSeed(EngineId const& id, seed_t frozen_seed);

    void registerEngineIdAndSeeder
      (EngineId const& id, SeedMaster_t::Seeder_t seeder);

    seed_t seedEngine(EngineId const& id) { return seeds.reseed(id); }

    // Call backs that will be called by art.
    void preModuleConstruction (art::ModuleDescription const& md);
    void postModuleConstruction(art::ModuleDescription const&);
    void preModuleBeginRun     (art::ModuleContext const& mc);
    void postModuleBeginRun    (art::ModuleContext const&);
    void preProcessEvent       (art::Event const& evt, art::ScheduleContext);
    void preModule             (art::ModuleContext const& mc);
    void postModule            (art::ModuleContext const&);
    void postProcessEvent      (art::Event const&, art::ScheduleContext);
    void preModuleEndJob       (art::ModuleDescription const& md);
    void postModuleEndJob      (art::ModuleDescription const&);
    void postEndJob            ();


  }; // class NuRandomService


#if (NURANDOM_RANDOMUTILS_NuRandomService_USECLHEP)
  //----------------------------------------------------------------------------
  // FIXME: See if the engine preparation can be done similarly to how
  //        it is described in the "Create and register an engine"
  //        documentation above.

  //----------------------------------------------------------------------------
  inline std::reference_wrapper<NuRandomService::engine_t>
  NuRandomService::registerAndSeedEngine(engine_t& engine,
                                         std::string type,
                                         std::string instance,
                                         std::optional<seed_t> const seed)
  {
    EngineId const id = qualify_engine_label(instance);
    registerEngineIdAndSeeder(id, CLHEPengineSeeder{engine});
    auto const [seedValue, frozen] = extractSeed(id, seed);
    engine.setSeed(seedValue, 0);
    mf::LogInfo("NuRandomService")
      << "Seeding " << type << " engine \"" << id.artName()
      << "\" with seed " << seedValue << ".";
    if (frozen) freezeSeed(id, seedValue);
    return engine;
  } // NuRandomService::registerAndSeedEngine(seed_t)


  inline std::reference_wrapper<NuRandomService::engine_t>
  NuRandomService::registerAndSeedEngine(engine_t& engine,
                                std::string type,
                                std::string instance,
                                SeedAtom const& seedParam)
  {
    return registerAndSeedEngine(engine, type, instance, readSeedParameter(seedParam));
  } // NuRandomService::registerAndSeedEngine(ParameterSet)


  inline std::reference_wrapper<NuRandomService::engine_t>
  NuRandomService::registerAndSeedEngine(engine_t& engine,
                                std::string type,
                                std::string instance,
                                fhicl::ParameterSet const& pset,
                                std::initializer_list<std::string> pnames)
  {
    return
      registerAndSeedEngine(engine, type, instance, readSeedParameter(pset, pnames));
  }


#endif // NURANDOM_RANDOMUTILS_NuRandomService_USECLHEP

} // namespace rndm

DECLARE_ART_SERVICE(rndm::NuRandomService, LEGACY)

#endif // NURANDOM_RANDOMUTILS_NuRandomService_H