art::RandomNumberGenerator Class Reference

#include "RandomNumberGenerator.h"

Classes
struct	Config
struct	ScheduleData

Public Types
enum	EngineSource { EngineSource::Seed = 1, EngineSource::File = 2, EngineSource::Product = 3 }
using	base_engine_t = CLHEP::HepRandomEngine
using	seed_t = long
using	Parameters = ServiceTable< Config >

Public Member Functions
	RandomNumberGenerator (Parameters const &, ActivityRegistry &)
	RandomNumberGenerator (RandomNumberGenerator const &)=delete
	RandomNumberGenerator (RandomNumberGenerator &&)=delete
RandomNumberGenerator &	operator= (RandomNumberGenerator const &)=delete
RandomNumberGenerator &	operator= (RandomNumberGenerator &&)=delete
std::string const &	defaultEngineKind () const noexcept

Static Public Attributes
static long constexpr	maxCLHEPSeed {900000000}
static long constexpr	useDefaultSeed {-1}

Private Member Functions
CLHEP::HepRandomEngine &	createEngine (ScheduleID sid, std::string const &module_label, long seed, std::string const &kind_of_engine_to_make, std::string const &engine_label={})
void	validate_ (std::string const &user_specified_engine_kind, long user_specified_seed) noexcept(false)
void	takeSnapshot_ (ScheduleID)
void	restoreSnapshot_ (ScheduleID, Event const &)
std::vector< RNGsnapshot > const &	accessSnapshot_ (ScheduleID) const
void	saveToFile_ ()
void	restoreFromFile_ ()
void	print_ () const
bool	invariant_holds_ (ScheduleID)
void	preProcessEvent (Event const &, ScheduleContext)
void	postProcessEvent (Event const &, ScheduleContext)
void	postBeginJob ()
void	postEndJob ()

Private Attributes
std::recursive_mutex	mutex_ {}
std::string const	defaultEngineKind_
std::string const	restoreStateLabel_
std::string const	saveToFilename_
std::string const	restoreFromFilename_
bool const	debug_
unsigned const	nPrint_
bool	engine_creation_is_okay_ {true}
PerScheduleContainer< ScheduleData >	data_

Friends
class	EventProcessor
class	detail::EngineCreator
class	RandomNumberSaver

Detailed Description

Definition at line 158 of file RandomNumberGenerator.h.

Member Typedef Documentation

using art::RandomNumberGenerator::base_engine_t = CLHEP::HepRandomEngine

Definition at line 170 of file RandomNumberGenerator.h.

using art::RandomNumberGenerator::Parameters = ServiceTable<Config>

Definition at line 229 of file RandomNumberGenerator.h.

using art::RandomNumberGenerator::seed_t = long

Definition at line 171 of file RandomNumberGenerator.h.

Member Enumeration Documentation

enum art::RandomNumberGenerator::EngineSource

strong

Enumerator
Seed
File
Product

Definition at line 166 of file RandomNumberGenerator.h.

{ Seed = 1, File = 2, Product = 3 };

Constructor & Destructor Documentation

art::RandomNumberGenerator::RandomNumberGenerator	(	Parameters const &	config,
		ActivityRegistry &	actReg
	)

Definition at line 118 of file RandomNumberGenerator.cc.

References data_, debug_, art::Globals::instance(), nPrint_, postBeginJob(), postEndJob(), preProcessEvent(), restoreFromFilename_, restoreStateLabel_, and saveToFilename_.

    : defaultEngineKind_{config().defaultEngineKind()}
    , restoreStateLabel_{config().restoreStateLabel()}
    , saveToFilename_{config().saveTo()}
    , restoreFromFilename_{config().restoreFrom()}
    , debug_{config().debug()}
    , nPrint_{config().nPrint()}
  {
    actReg.sPostBeginJob.watch(this, &RandomNumberGenerator::postBeginJob);
    actReg.sPostEndJob.watch(this, &RandomNumberGenerator::postEndJob);
    actReg.sPreProcessEvent.watch(this,
                                  &RandomNumberGenerator::preProcessEvent);
    data_.resize(Globals::instance()->nschedules());
  }

art::RandomNumberGenerator::RandomNumberGenerator ( RandomNumberGenerator const &  )

delete

art::RandomNumberGenerator::RandomNumberGenerator ( RandomNumberGenerator &&  )

delete

Member Function Documentation

vector< RNGsnapshot > const & art::RandomNumberGenerator::accessSnapshot_ ( ScheduleID  sid ) const

private

Definition at line 258 of file RandomNumberGenerator.cc.

References data_, and mutex_.

  {
    std::lock_guard sentry{mutex_};
    return data_[sid].snapshot_;
  }

CLHEP::HepRandomEngine & art::RandomNumberGenerator::createEngine ( ScheduleID  sid, std::string const &  module_label, long  seed, std::string const &  kind_of_engine_to_make, std::string const &  engine_label = {}  )

private

Definition at line 135 of file RandomNumberGenerator.cc.

References data_, defaultEngineKind_, engine_creation_is_okay_, art::ScheduleID::id(), invariant_holds_(), mutex_, Seed, useDefaultSeed, and validate_().

  {
    std::lock_guard sentry{mutex_};
    if (!engine_creation_is_okay_) {
      throw cet::exception("RANDOM")
        << "RNGservice::createEngine():\n"
        << "Attempt to create engine \"" << engine_label << "\" is too late.\n";
    }
    if (sid.id() >= data_.size()) {
      throw cet::exception("RANDOM")
        << "RNGservice::createEngine():\n"
        << "Attempt to create engine with out-of-range ScheduleID: " << sid
        << '\n';
    }
    string const& label = qualify_engine_label(sid, module_label, engine_label);
    if (data_[sid].tracker_.find(label) != data_[sid].tracker_.cend()) {
      throw cet::exception("RANDOM")
        << "RNGservice::createEngine():\n"
        << "Engine \"" << label << "\" has already been created.\n";
    }
    string engineKind{requested_engine_kind};
    if (requested_engine_kind.empty()) {
      engineKind = defaultEngineKind_;
    }

    validate_(engineKind, seed);

    shared_ptr<CLHEP::HepRandomEngine> eptr;
    if (engineKind == "G4Engine"s) {
      eptr = engine_factory(defaultEngineKind_, seed);
      // We set CLHEP's random-number engine to be of type
      // defaultEngineKind_.
      CLHEP::HepRandom::setTheEngine(eptr.get());
      if (seed != RandomNumberGenerator::useDefaultSeed) {
        CLHEP::HepRandom::setTheSeed(seed);
      }
    } else if (engineKind == "NonRandomEngine"s) {
      eptr = std::make_shared<CLHEP::NonRandomEngine>();
    } else {
      eptr = engine_factory(engineKind, seed);
    }
    if (!eptr) {
      throw cet::exception("RANDOM")
        << "RNGservice::createEngine():\n"
        << "Engine \"" << label << "\" could not be created.\n";
    }
    data_[sid].dict_[label] = eptr;
    data_[sid].tracker_[label] = EngineSource::Seed;
    data_[sid].kind_[label] = engineKind;
    mf::LogInfo{"RANDOM"} << "Instantiated " << engineKind << " engine \""
                          << label << "\" with "
                          << ((seed == useDefaultSeed) ? "default seed " :
                                                         "seed ")
                          << seed << '.';
    assert(invariant_holds_(sid) &&
           "RNGservice::createEngine() invariant failed");
    return *eptr;
  }

std::string const& art::RandomNumberGenerator::defaultEngineKind ( ) const

inlinenoexcept

Definition at line 239 of file RandomNumberGenerator.h.

References seed.

    {
      return defaultEngineKind_;
    }

bool art::RandomNumberGenerator::invariant_holds_ ( ScheduleID  sid )

private

Definition at line 111 of file RandomNumberGenerator.cc.

Referenced by createEngine(), restoreFromFile_(), and restoreSnapshot_().

  {
    std::lock_guard sentry{mutex_};
    return (data_[sid].dict_.size() == data_[sid].tracker_.size()) &&
           (data_[sid].dict_.size() == data_[sid].kind_.size());
  }

RandomNumberGenerator& art::RandomNumberGenerator::operator= ( RandomNumberGenerator const &  )

delete

RandomNumberGenerator& art::RandomNumberGenerator::operator= ( RandomNumberGenerator &&  )

delete

void art::RandomNumberGenerator::postBeginJob ( )

private

Definition at line 416 of file RandomNumberGenerator.cc.

References engine_creation_is_okay_, mutex_, and restoreFromFile_().

Referenced by RandomNumberGenerator().

  {
    std::lock_guard sentry{mutex_};
    restoreFromFile_();
    engine_creation_is_okay_ = false;
  }

void art::RandomNumberGenerator::postEndJob ( )

private

Definition at line 434 of file RandomNumberGenerator.cc.

References data_, art::ScheduleIteration::for_each_schedule(), mutex_, saveToFile_(), and takeSnapshot_().

Referenced by RandomNumberGenerator().

  {
    // For normal termination, we wish to save the state at the *end* of
    // processing, not at the beginning of the last event.
    std::lock_guard sentry{mutex_};
    ScheduleIteration iteration(data_.size());
    iteration.for_each_schedule(
      [this](ScheduleID const sid) { takeSnapshot_(sid); });
    saveToFile_();
  }

void art::RandomNumberGenerator::postProcessEvent ( Event const &  , ScheduleContext    )

private

void art::RandomNumberGenerator::preProcessEvent ( Event const &  e, ScheduleContext  sc  )

private

Definition at line 424 of file RandomNumberGenerator.cc.

References art::ScheduleContext::id(), mutex_, restoreSnapshot_(), and takeSnapshot_().

Referenced by RandomNumberGenerator().

  {
    auto const sid = sc.id();
    std::lock_guard sentry{mutex_};
    takeSnapshot_(sid);
    restoreSnapshot_(sid, e);
  }

void art::RandomNumberGenerator::print_ ( ) const

private

Definition at line 235 of file RandomNumberGenerator.cc.

References d, data_, debug_, mutex_, and nPrint_.

  {
    std::lock_guard sentry{mutex_};
    static unsigned ncalls = 0;
    if (!debug_ || (++ncalls > nPrint_)) {
      return;
    }
    auto print_per_stream = [](size_t const i, auto const& d) {
      mf::LogInfo log{"RANDOM"};
      if (d.snapshot_.empty()) {
        log << "No snapshot has yet been made.\n";
        return;
      }
      log << "Snapshot information:";
      for (auto const& ss : d.snapshot_) {
        log << "\nEngine: " << ss.label() << "  Kind: " << ss.ekind()
            << "  Schedule ID: " << i << "  State size: " << ss.state().size();
      }
    };
    cet::for_all_with_index(data_, print_per_stream);
  }

void art::RandomNumberGenerator::restoreFromFile_ ( )

private

Definition at line 355 of file RandomNumberGenerator.cc.

References art::errors::Configuration, d, data_, File, invariant_holds_(), art::errors::LogicError, mutex_, restoreFromFilename_, and Seed.

Referenced by postBeginJob().

  {
    std::lock_guard sentry{mutex_};
    if (restoreFromFilename_.empty()) {
      return;
    }
    HEP_CONCURRENCY_ASSERT_ONLY_ONE_THREAD();
    // access the file:
    ifstream infile{restoreFromFilename_.c_str()};
    if (!infile) {
      throw cet::exception("RANDOM")
        << "RNGservice::restoreFromFile_():\n"
        << "Can't open file \"" << restoreFromFilename_
        << "\" to initialize engines\n";
    }
    // restore engines:
    for (string label{}; infile >> label;) {
      // Get schedule ID from engine label
      assert(count(label.cbegin(), label.cend(), ':') == 2u);
      auto const p1 = label.find_first_of(':');
      auto const p2 = label.find_last_of(':');
      ScheduleID const sid{
        static_cast<ScheduleID::size_type>(stoi(label.substr(p1 + 1, p2)))};
      auto d = data_[sid].dict_.find(label);
      if (d == data_[sid].dict_.end()) {
        throw Exception(errors::Configuration, "RANDOM")
          << "Attempt to restore an engine with label " << label
          << " not configured in this job.\n";
      }
      assert((data_[sid].tracker_.find(label) != data_[sid].tracker_.cend()) &&
             "RNGservice::restoreFromFile_()");
      EngineSource& how{data_[sid].tracker_[label]};
      if (how == EngineSource::Seed) {
        auto& eptr = d->second;
        assert(eptr && "RNGservice::restoreFromFile_()");
        if (!eptr->get(infile)) {
          throw cet::exception("RANDOM")
            << "RNGservice::restoreFromFile_():\n"
            << "Failed during restore of state of engine for label " << label
            << "from file \"" << restoreFromFilename_ << '"';
        }
        how = EngineSource::File;
      } else if (how == EngineSource::File) {
        throw Exception(errors::Configuration, "RANDOM")
          << "Engine state file contains two engine states with the same "
             "label: "
          << label << "\n.";
      } else {
        throw Exception(errors::LogicError, "RANDOM")
          << "Internal error: attempt to restore an engine state " << label
          << " from file\n"
          << "which was originally initialized via an unknown or impossible "
             "method.\n";
      }
      assert(invariant_holds_(sid) &&
             "RNGservice::restoreFromFile_() invariant failure");
    }
  }

void art::RandomNumberGenerator::restoreSnapshot_ ( ScheduleID  sid, Event const &  event  )

private

Definition at line 281 of file RandomNumberGenerator.cc.

References data_, File, invariant_holds_(), mutex_, Product, and restoreStateLabel_.

Referenced by preProcessEvent().

  {
    std::lock_guard sentry{mutex_};
    if (restoreStateLabel_.empty()) {
      return;
    }
    // access the saved-states product:
    auto const& saved =
      event.getProduct<vector<RNGsnapshot>>(restoreStateLabel_);
    // restore engines from saved-states product:
    for (auto const& snapshot : saved) {
      string const& label = snapshot.label();
      mf::LogInfo log("RANDOM");
      log << "RNGservice::restoreSnapshot_(): label \"" << label << "\"";
      auto t = data_[sid].tracker_.find(label);
      if (t == data_[sid].tracker_.end()) {
        log << " could not be restored;\n"
            << "no established engine bears this label.\n";
        continue;
      }
      if (t->second == EngineSource::File) {
        throw cet::exception("RANDOM")
          << "RNGservice::restoreSnapshot_():\n"
          << "The state of engine \"" << label
          << "\" has been previously read from a file;\n"
          << "it is therefore not restorable from a snapshot product.\n";
      }
      shared_ptr<CLHEP::HepRandomEngine> ep{data_[sid].dict_[label]};
      assert(ep && "RNGservice::restoreSnapshot_()");
      data_[sid].tracker_[label] = EngineSource::Product;
      auto const& est = snapshot.restoreState();
      if (ep->get(est)) {
        log << " successfully restored.\n";
      } else {
        throw cet::exception("RANDOM")
          << "RNGservice::restoreSnapshot_():\n"
          << "Failed during restore of state of engine for \"" << label
          << "\"\n";
      }
    }
    assert(invariant_holds_(sid) && "RNGsnapshot::restoreSnapshot_()");
  }

void art::RandomNumberGenerator::saveToFile_ ( )

private

Definition at line 326 of file RandomNumberGenerator.cc.

References d, data_, mutex_, and saveToFilename_.

Referenced by postEndJob().

  {
    std::lock_guard sentry{mutex_};
    if (saveToFilename_.empty()) {
      return;
    }
    HEP_CONCURRENCY_ASSERT_ONLY_ONE_THREAD();
    // access the file:
    ofstream outfile{saveToFilename_.c_str()};
    if (!outfile) {
      mf::LogWarning("RANDOM")
        << "Can't create/access file \"" << saveToFilename_ << "\"\n";
    }
    // save each engine:
    for (auto const& d : data_) {
      for (auto const& [label, eptr] : d.dict_) {
        outfile << label << '\n';
        assert(eptr && "RNGservice::saveToFile_()");
        eptr->put(outfile);
        if (!outfile) {
          mf::LogWarning("RANDOM")
            << "This module's engine has not been saved;\n"
            << "file \"" << saveToFilename_ << "\" is likely now corrupted.\n";
        }
      }
    }
  }

void art::RandomNumberGenerator::takeSnapshot_ ( ScheduleID  sid )

private

Definition at line 265 of file RandomNumberGenerator.cc.

References data_, and mutex_.

Referenced by postEndJob(), and preProcessEvent().

  {
    std::lock_guard sentry{mutex_};
    mf::LogDebug log{"RANDOM"};
    log << "RNGservice::takeSnapshot_() of the following engine labels:\n";
    data_[sid].snapshot_.clear();
    for (auto const& [label, eptr] : data_[sid].dict_) {
      assert(eptr && "RNGservice::takeSnapshot_()");
      data_[sid].snapshot_.emplace_back(
        data_[sid].kind_[label], label, eptr->put());
      log << " | " << label;
    }
    log << " |";
  }

void art::RandomNumberGenerator::validate_ ( std::string const &  user_specified_engine_kind, long  user_specified_seed  )

privatenoexcept

Definition at line 199 of file RandomNumberGenerator.cc.

References defaultEngineKind_, maxCLHEPSeed, and useDefaultSeed.

Referenced by createEngine().

  {
    // The only time a user-specified seed can be negative is for
    // indicating to this service that the default seed for the
    // requested engine kind should be used.
    if (user_specified_seed == useDefaultSeed)
      return;

    if (user_specified_seed < 0) {
      throw cet::exception("RANGE") << "RNGservice::throw_if_invalid_seed():\n"
                                    << "Seed " << user_specified_seed
                                    << " is not permitted to be negative.\n";
    }

    if (user_specified_seed <= maxCLHEPSeed)
      return;

    // For now, only MixMaxRng engines can be constructed with a seed
    // value greater than maxCLHEPSeed.
    if (user_specified_engine_kind == "MixMaxRng"s)
      return;

    if (user_specified_engine_kind == "G4Engine"s &&
        defaultEngineKind_ == "MixMaxRng"s)
      return;

    throw cet::exception("RANGE")
      << "RNGservice::throw_if_invalid_seed():\n"
      << "Seed " << user_specified_seed << " exceeds permitted maximum of "
      << maxCLHEPSeed << " for engine type " << user_specified_engine_kind
      << ".\n";
  }

Friends And Related Function Documentation

friend class detail::EngineCreator

friend

Definition at line 161 of file RandomNumberGenerator.h.

friend class EventProcessor

friend

Definition at line 160 of file RandomNumberGenerator.h.

friend class RandomNumberSaver

friend

Definition at line 162 of file RandomNumberGenerator.h.

Member Data Documentation

PerScheduleContainer<ScheduleData> art::RandomNumberGenerator::data_

private

Definition at line 321 of file RandomNumberGenerator.h.

Referenced by accessSnapshot_(), createEngine(), postEndJob(), print_(), RandomNumberGenerator(), restoreFromFile_(), restoreSnapshot_(), saveToFile_(), and takeSnapshot_().

bool const art::RandomNumberGenerator::debug_

private

Definition at line 293 of file RandomNumberGenerator.h.

Referenced by print_(), and RandomNumberGenerator().

std::string const art::RandomNumberGenerator::defaultEngineKind_

private

Definition at line 281 of file RandomNumberGenerator.h.

Referenced by createEngine(), and validate_().

bool art::RandomNumberGenerator::engine_creation_is_okay_ {true}

private

Definition at line 297 of file RandomNumberGenerator.h.

Referenced by createEngine(), and postBeginJob().

long constexpr art::RandomNumberGenerator::maxCLHEPSeed {900000000}

static

Definition at line 168 of file RandomNumberGenerator.h.

Referenced by validate_().

std::recursive_mutex art::RandomNumberGenerator::mutex_ {}

mutableprivate

Definition at line 279 of file RandomNumberGenerator.h.

Referenced by accessSnapshot_(), createEngine(), postBeginJob(), postEndJob(), preProcessEvent(), print_(), restoreFromFile_(), restoreSnapshot_(), saveToFile_(), and takeSnapshot_().

unsigned const art::RandomNumberGenerator::nPrint_

private

Definition at line 294 of file RandomNumberGenerator.h.

Referenced by print_(), and RandomNumberGenerator().

std::string const art::RandomNumberGenerator::restoreFromFilename_

private

Definition at line 290 of file RandomNumberGenerator.h.

Referenced by RandomNumberGenerator(), and restoreFromFile_().

std::string const art::RandomNumberGenerator::restoreStateLabel_

private

Definition at line 284 of file RandomNumberGenerator.h.

Referenced by RandomNumberGenerator(), and restoreSnapshot_().

std::string const art::RandomNumberGenerator::saveToFilename_

private

Definition at line 287 of file RandomNumberGenerator.h.

Referenced by RandomNumberGenerator(), and saveToFile_().

long constexpr art::RandomNumberGenerator::useDefaultSeed {-1}

static

Definition at line 169 of file RandomNumberGenerator.h.

Referenced by createEngine(), and validate_().

---

The documentation for this class was generated from the following files:

• art/Framework/Services/Optional/RandomNumberGenerator.h
• art/Framework/Services/Optional/RandomNumberGenerator.cc