Implementation of the "perEvent" policy. More...

#include "PerEventPolicy.h"

Inheritance diagram for rndm::details::PerEventPolicy< SEED >:

Public Types
enum	SeedAlgo_t { saEventTimestamp_v1, NAlgos, saUndefined, saDefault = saEventTimestamp_v1 }

using	base_t = RandomSeedPolicyBase< SEED >

using	this_t = PerEventPolicy< SEED >

using	seed_t = typename base_t::seed_t

using	EventData_t = NuRandomServiceHelper::EventSeedInputData
	type for contextual event information More...

Public Member Functions
	PerEventPolicy (fhicl::ParameterSet const &pset)

virtual bool	yieldsUniqueSeeds () const override
	Returns whether the returned seed should be unique: for us it "no". More...

virtual void	configure (fhicl::ParameterSet const &pset) override
	Configure this policy. More...

virtual void	print (std::ostream &out) const override
	Prints the details of the configuration of the random generator. More...

virtual seed_t	getSeed (SeedMasterHelper::EngineId const &id)
	Returns the next random number. More...

virtual seed_t	getSeed (SeedMasterHelper::EngineId const &id)
	Returns the next random number. More...

virtual seed_t	getEventSeed (SeedMasterHelper::EngineId const &id, EventData_t const &eventInfo)
	Returns a random number specific to an event. More...

virtual seed_t	getEventSeed (SeedMasterHelper::EngineId const &id, EventData_t const &eventInfo)
	Returns a random number specific to an event. More...

std::string	getName () const
	Returns the given name of the policy. More...

std::string	getName () const
	Returns the given name of the policy. More...

Static Public Member Functions
template<typename Hashable >
static seed_t	SeedFromHash (Hashable const &info)
	Converts some information into a valid seed by means of hash values. More...

static std::string	UniqueEventIDString (EventData_t const &info)
	Converts run, subrun and event numbers into a string. More...

static std::string	UniqueEventString (EventData_t const &info)
	Converts event ID and timestamp information into a string. More...

Static Public Attributes
static constexpr const char *	DefaultVersion = "v1"
	Default algorithm version. More...

static constexpr seed_t	InvalidSeed = 0
	An invalid seed. More...

Protected Attributes
std::string	name
	name of the policy More...

Private Types
using	SeedOffset_t = typename std::make_signed< seed_t >::type
	type for seed offset More...

Private Member Functions
virtual seed_t	createSeed (SeedMasterHelper::EngineId const &id) override
	Per-job seed: pre-event seeds are returned (or invalid if none). More...

virtual seed_t	createEventSeed (SeedMasterHelper::EngineId const &id, EventData_t const &info) override
	Returns a seed proper for the specified event information. More...

Static Private Member Functions
template<typename T >
static seed_t	makeValid (T value)
	Renders a seed valid. More...

static seed_t	EventTimestamp_v1 (SeedMasterHelper::EngineId const &id, EventData_t const &info)
	Implementation of the EventTimestamp_v1 algorithm. More...

Private Attributes
SeedAlgo_t	algo
	the algorithm to extract the seed More...

SeedOffset_t	offset
	offset added to all the seeds More...

PolicyStruct_t< seed_t >	initSeedPolicy
	Policy used for initialization before the event (none by default). More...

static const std::vector< std::string >	algoNames = PerEventPolicy<SEED>::InitAlgoNames()
	Algorithm name (manual) handling. More...

static std::vector< std::string >	InitAlgoNames ()
	Algorithm name (manual) handling. More...

Detailed Description

template<typename SEED>
class rndm::details::PerEventPolicy< SEED >

Implementation of the "perEvent" policy.

This policy extracts seeds depending on contextual information from the event. The information that enters the seed is the event ID (run, subrun, event), the process name, and the engine ID.

The policy is only effective if an event is being processed. Before the first event is processed, seeds are initialized to a fixed value, while in between the events they are not modified and the random numbers extracted at that time will depend on which event was processed last.

As a partial mitigation to this, it is possible to specify a "pre-event" policy that is used to initialize the random engines on construction, just like the policies which do not depend on the event (like autoIncrement and random) do. This is achieved by specifying in the initSeedPolicy configuration table the whole configuration of this "fallback" policy. For example:

NuRandomService: {
  policy            : "perEvent"
  initSeedPolicy: {
    policy            : "preDefinedSeed"
    baseSeed          :     1
    maxUniqueEngines  :     6
    checkRange        :  true
    Module1: { a : 3  b : 5 }
    Module2: { a : 7  c : 9 }
  } # initSeedPolicy
  verbosity         :     2
  endOfJobSummary   :  false
}

sets up the perEvent policy, and uses a preDefinedSeed for the seeds before the first event.

Definition at line 78 of file PerEventPolicy.h.

Member Typedef Documentation

template<typename SEED>

using rndm::details::PerEventPolicy< SEED >::base_t = RandomSeedPolicyBase<SEED>

Definition at line 80 of file PerEventPolicy.h.

template<typename SEED>

using rndm::details::PerEventPolicy< SEED >::EventData_t = NuRandomServiceHelper::EventSeedInputData

type for contextual event information

Definition at line 85 of file PerEventPolicy.h.

template<typename SEED>

using rndm::details::PerEventPolicy< SEED >::seed_t = typename base_t::seed_t

Definition at line 82 of file PerEventPolicy.h.

template<typename SEED>

using rndm::details::PerEventPolicy< SEED >::SeedOffset_t = typename std::make_signed<seed_t>::type

private

type for seed offset

Definition at line 143 of file PerEventPolicy.h.

template<typename SEED>

using rndm::details::PerEventPolicy< SEED >::this_t = PerEventPolicy<SEED>

Definition at line 81 of file PerEventPolicy.h.

Member Enumeration Documentation

template<typename SEED>

enum rndm::details::PerEventPolicy::SeedAlgo_t

Enumerator
saEventTimestamp_v1	event timestamp algorithm (v1)
NAlgos	total number of seed algorithms
saUndefined	algorithm not defined
saDefault	default algorithm

Definition at line 87 of file PerEventPolicy.h.

                    {
         saEventTimestamp_v1,             
         NAlgos,                          
         saUndefined,                     
         saDefault = saEventTimestamp_v1  
       } SeedAlgo_t; 

Constructor & Destructor Documentation

template<typename SEED>

rndm::details::PerEventPolicy< SEED >::PerEventPolicy ( fhicl::ParameterSet const & pset )

inline

Configures from a parameter set

See also: configure()

Definition at line 96 of file PerEventPolicy.h.

References rndm::details::PerEventPolicy< SEED >::configure().

96 : base_t("perEvent")

97 { this_t::configure(pset); }

rndm::details::PerEventPolicy::configure

virtual void configure(fhicl::ParameterSet const &pset) override

Configure this policy.

Definition: PerEventPolicy.h:253

rndm::details::PerEventPolicy::base_t

RandomSeedPolicyBase< SEED > base_t

Definition: PerEventPolicy.h:80

Member Function Documentation

template<typename SEED >

void rndm::details::PerEventPolicy< SEED >::configure ( fhicl::ParameterSet const & pset )

overridevirtual

Configure this policy.

Parameters

pset	the parameter set for the configuration

Parameters:

algorithm (string, default: "EventTimestamp_v1"): the name of the algorithm to get the seed
offset (integer, optional): if specified, all the final seeds are incremented by this value; the resulting seed is not checked, it might even be invalid. This is considered an emergency hack when one absolutely needs to have a different seed than the one assigned to the event. This also defies the purpose of the policy, since after this, to reproduce the random sequences the additional knowledge of which offset was used is necessary.

Reimplemented from rndm::details::RandomSeedPolicyBase< SEED >.

Definition at line 253 of file PerEventPolicy.h.

References rndm::details::PerEventPolicy< SEED >::algo, rndm::details::PerEventPolicy< SEED >::algoNames, art::errors::Configuration, e, fhicl::ParameterSet::get(), rndm::details::PerEventPolicy< SEED >::initSeedPolicy, rndm::details::PerEventPolicy< SEED >::NAlgos, rndm::details::PerEventPolicy< SEED >::offset, rndm::details::PerEventPolicy< SEED >::saDefault, and rndm::details::PerEventPolicy< SEED >::saUndefined.

Referenced by rndm::details::PerEventPolicy< SEED >::PerEventPolicy(), and rndm::details::PerEventPolicy< SEED >::yieldsUniqueSeeds().

                                                                       {
       // set the per-event algorithm
       algo = saUndefined;
       std::string algorithm_name
          = pset.get<std::string>("algorithm", "default");
       
       if (algorithm_name == "default") algo = saDefault;
       else {
         for (size_t iAlgo = 0; iAlgo < (size_t) NAlgos; ++iAlgo) {
           if (algorithm_name != algoNames[iAlgo]) continue;
           algo = (SeedAlgo_t) iAlgo;
           break;
         } // for
       }
       if (algo == saUndefined) {
         throw art::Exception(art::errors::Configuration)
           << "No valid event random seed algorithm specified!\n";
       }
       
       // read an optional overall offset
       offset = pset.get<SeedOffset_t>("offset", 0);
       
       // EventTimestamp_v1 does not require specific configuration
       
       
       // set the pre-event algorithm
       auto const& initSeedConfig
         = pset.get<fhicl::ParameterSet>("initSeedPolicy", {});
       if (!initSeedConfig.is_empty()) {
         try {
           initSeedPolicy = makeRandomSeedPolicy<seed_t>(initSeedConfig);
         }
         catch(cet::exception const& e) {
           throw cet::exception{ "PerEventPolicy", "", e }
             << "Error creating the pre-event policy of `perEvent` random policy"
             " from configuration:\n"
             << initSeedConfig.to_indented_string(2);
         }
       } // if pre-event policy
       
     } // PerEventPolicy<SEED>::configure()

template<typename SEED >

PerEventPolicy< SEED >::seed_t rndm::details::PerEventPolicy< SEED >::createEventSeed	(	SeedMasterHelper::EngineId const &	id,
		EventData_t const &	info
	)

overrideprivatevirtual

Returns a seed proper for the specified event information.

Parameters

id	random number engine ID (moule label and instance name)
info	event information

Returns: a seed specific to the information provided

The algorithm used to combine the provided information into a seed is defined by the configuration. The following algorithms are supported:

EventTimestamp_v1: includes event ID (run, subrun and event numbers), event timestamp, process name and engine ID into a hash value, used for the seed

Reimplemented from rndm::details::RandomSeedPolicyBase< SEED >.

Definition at line 325 of file PerEventPolicy.h.

References rndm::details::PerEventPolicy< SEED >::algo, art::errors::Configuration, rndm::details::PerEventPolicy< SEED >::EventTimestamp_v1(), rndm::details::RandomSeedPolicyBase< SEED >::InvalidSeed, art::errors::LogicError, rndm::details::PerEventPolicy< SEED >::offset, rndm::details::PerEventPolicy< SEED >::saEventTimestamp_v1, rndm::details::PerEventPolicy< SEED >::saUndefined, and seed.

Referenced by rndm::details::PerEventPolicy< SEED >::createSeed().

     {
       seed_t seed = base_t::InvalidSeed;
       switch (algo) {
         case saEventTimestamp_v1:
           seed = EventTimestamp_v1(id, info);
           break;
         case saUndefined:
           throw art::Exception(art::errors::Configuration)
             << "Per-event random number seeder not configured!\n";
         default:
           throw art::Exception(art::errors::LogicError)
             << "Unsupported per-event random number seeder (#"
             << ((int) algo) << ")\n";
       } // switch
       return seed + offset;
     } // PerEventPolicy<SEED>::createEventSeed()

template<typename SEED >

PerEventPolicy< SEED >::seed_t rndm::details::PerEventPolicy< SEED >::createSeed ( SeedMasterHelper::EngineId const & id )

overrideprivatevirtual

Per-job seed: pre-event seeds are returned (or invalid if none).

Implements rndm::details::RandomSeedPolicyBase< SEED >.

Definition at line 318 of file PerEventPolicy.h.

References rndm::details::PerEventPolicy< SEED >::createEventSeed(), rndm::details::RandomSeedPolicyBase< SEED >::getSeed(), rndm::details::PerEventPolicy< SEED >::initSeedPolicy, and rndm::details::RandomSeedPolicyBase< SEED >::InvalidSeed.

Referenced by rndm::details::PerEventPolicy< SEED >::print().

319 { return initSeedPolicy? initSeedPolicy->getSeed(id): base_t::InvalidSeed; }

rndm::details::RandomSeedPolicyBase::getSeed

virtual seed_t getSeed(SeedMasterHelper::EngineId const &id)

Returns the next random number.

Definition: BasePolicies.h:64

rndm::details::RandomSeedPolicyBase::InvalidSeed

static constexpr seed_t InvalidSeed

An invalid seed.

Definition: BasePolicies.h:51

rndm::details::PerEventPolicy::initSeedPolicy

PolicyStruct_t< seed_t > initSeedPolicy

Policy used for initialization before the event (none by default).

Definition: PerEventPolicy.h:150

template<typename SEED >

auto rndm::details::PerEventPolicy< SEED >::EventTimestamp_v1	(	SeedMasterHelper::EngineId const &	id,
		EventData_t const &	info
	)

staticprivate

Implementation of the EventTimestamp_v1 algorithm.

Definition at line 232 of file PerEventPolicy.h.

References art::errors::InvalidNumber, rndm::NuRandomServiceHelper::EventSeedInputData::isTimeValid, MF_LOG_DEBUG, rndm::NuRandomServiceHelper::EventSeedInputData::processName, seed, rndm::details::PerEventPolicy< SEED >::SeedFromHash(), and rndm::details::PerEventPolicy< SEED >::UniqueEventString().

Referenced by rndm::details::PerEventPolicy< SEED >::createEventSeed(), rndm::details::PerEventPolicy< SEED >::makeValid(), and rndm::details::PerEventPolicy< SEED >::UniqueEventString().

     {
       if (!info.isTimeValid) {
         throw art::Exception(art::errors::InvalidNumber)
           << "Input event has an invalid timestamp,"
           " random seed per-event policy EventTimestamp_v1 can't be used.\n";
       }
       std::string s = UniqueEventString(info)
         + " Process: " + info.processName
         + " Module: " + id.moduleLabel;
       if (!id.instanceName.empty())
         s.append(" Instance: ").append(id.instanceName);
       seed_t seed = SeedFromHash(s);
       MF_LOG_DEBUG("PerEventPolicy") << "Seed from: '" << s << "': " << seed;
       return seed;
     } // PerEventPolicy<SEED>::EventTimestamp_v1()

template<typename SEED>

virtual seed_t rndm::details::RandomSeedPolicyBase< SEED >::getEventSeed	(	SeedMasterHelper::EngineId const &	id,
		EventData_t const &	eventInfo
	)

inlinevirtualinherited

Returns a random number specific to an event.

Definition at line 69 of file BasePolicies.h.

Referenced by rndm::details::RandomSeedPolicyBase< seed_t >::getSeed().

70 { return createEventSeed(id, eventInfo); }

rndm::details::RandomSeedPolicyBase::createEventSeed

virtual seed_t createEventSeed(SeedMasterHelper::EngineId const &, EventData_t const &)

Extracts a seed for specified event information; returns InvalidSeed.

Definition: BasePolicies.h:90

template<typename SEED>

virtual seed_t rndm::details::RandomSeedPolicyBase< SEED >::getEventSeed	(	SeedMasterHelper::EngineId const &	id,
		EventData_t const &	eventInfo
	)

inlinevirtualinherited

Returns a random number specific to an event.

Definition at line 114 of file RandomSeedPolicyBase.h.

115 { return createEventSeed(id, eventInfo); }

rndm::details::RandomSeedPolicyBase::createEventSeed

virtual seed_t createEventSeed(SeedMasterHelper::EngineId const &, EventData_t const &)

Extracts a seed for specified event information; returns InvalidSeed.

Definition: BasePolicies.h:90

template<typename SEED>

std::string rndm::details::RandomSeedPolicyBase< SEED >::getName ( ) const

inlineinherited

Returns the given name of the policy.

Definition at line 73 of file BasePolicies.h.

Referenced by rndm::details::CheckedRangePolicy< SEED >::CheckRangeConfiguration(), rndm::details::CheckedRangePolicy< SEED >::ensureRange(), and rndm::details::RandomSeedPolicyBase< seed_t >::print().

73 { return name; }

rndm::details::RandomSeedPolicyBase::name

std::string name

name of the policy

Definition: BasePolicies.h:83

template<typename SEED>

std::string rndm::details::RandomSeedPolicyBase< SEED >::getName ( ) const

inlineinherited

Returns the given name of the policy.

Definition at line 118 of file RandomSeedPolicyBase.h.

118 { return name; }

rndm::details::RandomSeedPolicyBase::name

std::string name

name of the policy

Definition: BasePolicies.h:83

template<typename SEED>

virtual seed_t rndm::details::RandomSeedPolicyBase< SEED >::getSeed ( SeedMasterHelper::EngineId const & id )

inlinevirtualinherited

Returns the next random number.

Reimplemented in rndm::details::CheckedRangePolicy< SEED >, and rndm::details::CheckedRangePolicy< SEED >.

Definition at line 64 of file BasePolicies.h.

Referenced by rndm::details::PerEventPolicy< SEED >::createSeed().

65 { return createSeed(id); }

rndm::details::RandomSeedPolicyBase::createSeed

virtual seed_t createSeed(SeedMasterHelper::EngineId const &)=0

Extracts the next random number seed.

template<typename SEED>

virtual seed_t rndm::details::RandomSeedPolicyBase< SEED >::getSeed ( SeedMasterHelper::EngineId const & id )

inlinevirtualinherited

Returns the next random number.

Reimplemented in rndm::details::CheckedRangePolicy< SEED >, and rndm::details::CheckedRangePolicy< SEED >.

Definition at line 109 of file RandomSeedPolicyBase.h.

110 { return createSeed(id); }

rndm::details::RandomSeedPolicyBase::createSeed

virtual seed_t createSeed(SeedMasterHelper::EngineId const &)=0

Extracts the next random number seed.

template<typename SEED >

std::vector< std::string > rndm::details::PerEventPolicy< SEED >::InitAlgoNames ( )

staticprivate

Algorithm name (manual) handling.

Definition at line 194 of file PerEventPolicy.h.

References rndm::details::PerEventPolicy< SEED >::NAlgos, rndm::details::PerEventPolicy< SEED >::saEventTimestamp_v1, and rndm::details::PerEventPolicy< SEED >::UniqueEventIDString().

Referenced by rndm::details::PerEventPolicy< SEED >::makeValid().

                                                              {
       
       std::vector<std::string> names((size_t) NAlgos);
       
       names[saEventTimestamp_v1] = "EventTimestamp_v1";
       
       return names;
     } // PerEventPolicy<SEED>::InitAlgoNames()

template<typename SEED>

template<typename T >

static seed_t rndm::details::PerEventPolicy< SEED >::makeValid ( T value )

inlinestaticprivate

Renders a seed valid.

Definition at line 173 of file PerEventPolicy.h.

References rndm::details::PerEventPolicy< SEED >::algoNames, rndm::details::PerEventPolicy< SEED >::EventTimestamp_v1(), rndm::details::PerEventPolicy< SEED >::InitAlgoNames(), and value.

Referenced by rndm::details::PerEventPolicy< SEED >::SeedFromHash().

173 { return ValidSeed<seed_t>(value); }

value

double value

Definition: spectrum.C:18

template<typename SEED >

void rndm::details::PerEventPolicy< SEED >::print ( std::ostream & out ) const

overridevirtual

Prints the details of the configuration of the random generator.

Reimplemented from rndm::details::RandomSeedPolicyBase< SEED >.

Definition at line 299 of file PerEventPolicy.h.

References rndm::details::PerEventPolicy< SEED >::algo, rndm::details::PerEventPolicy< SEED >::algoNames, rndm::details::PerEventPolicy< SEED >::createSeed(), rndm::details::PerEventPolicy< SEED >::initSeedPolicy, rndm::details::PerEventPolicy< SEED >::offset, rndm::details::PolicyStruct_t< SEED >::policy, rndm::details::policyName(), and rndm::details::RandomSeedPolicyBase< SEED >::print().

Referenced by rndm::details::PerEventPolicy< SEED >::yieldsUniqueSeeds().

                                                           {
       base_t::print(out);
       out
         << "\n  algorithm version: " << algoNames[algo];
       if (offset != 0)
         out << "\n  constant offset:   " << offset;
       if (initSeedPolicy) {
         out << "\n  special policy for random seeds before the event: '"
           << policyName(initSeedPolicy.policy)
           << "'\n" << std::string(60, '-');
         initSeedPolicy->print(out);
         out << "\n" << std::string(60, '-');
       }
     } // PerEventPolicy<SEED>::print()

template<typename SEED>

template<typename Hashable >

static seed_t rndm::details::PerEventPolicy< SEED >::SeedFromHash ( Hashable const & info )

inlinestatic

Converts some information into a valid seed by means of hash values.

Definition at line 130 of file PerEventPolicy.h.

References rndm::details::PerEventPolicy< SEED >::makeValid(), rndm::details::PerEventPolicy< SEED >::UniqueEventIDString(), and rndm::details::PerEventPolicy< SEED >::UniqueEventString().

Referenced by rndm::details::PerEventPolicy< SEED >::EventTimestamp_v1().

131 { return makeValid(std::hash<Hashable>()(info)); }

rndm::details::PerEventPolicy::makeValid

static seed_t makeValid(T value)

Renders a seed valid.

Definition: PerEventPolicy.h:173

template<typename SEED >

std::string rndm::details::PerEventPolicy< SEED >::UniqueEventIDString ( EventData_t const & info )

static

Converts run, subrun and event numbers into a string.

Definition at line 212 of file PerEventPolicy.h.

References rndm::NuRandomServiceHelper::EventSeedInputData::eventNumber, rndm::NuRandomServiceHelper::EventSeedInputData::runNumber, rndm::NuRandomServiceHelper::EventSeedInputData::subRunNumber, util::to_string(), and rndm::details::PerEventPolicy< SEED >::UniqueEventString().

Referenced by rndm::details::PerEventPolicy< SEED >::InitAlgoNames(), rndm::details::PerEventPolicy< SEED >::SeedFromHash(), and rndm::details::PerEventPolicy< SEED >::UniqueEventString().

     {
       return "Run: " + std::to_string(info.runNumber)
         + " Subrun: " + std::to_string(info.subRunNumber)
         + " Event: "  + std::to_string(info.eventNumber)
         ;
     } // PerEventPolicy<SEED>::UniqueEventIDString()

template<typename SEED >

std::string rndm::details::PerEventPolicy< SEED >::UniqueEventString ( EventData_t const & info )

static

Converts event ID and timestamp information into a string.

Definition at line 223 of file PerEventPolicy.h.

References rndm::details::PerEventPolicy< SEED >::EventTimestamp_v1(), rndm::NuRandomServiceHelper::EventSeedInputData::time, util::to_string(), and rndm::details::PerEventPolicy< SEED >::UniqueEventIDString().

Referenced by rndm::details::PerEventPolicy< SEED >::EventTimestamp_v1(), rndm::details::PerEventPolicy< SEED >::SeedFromHash(), and rndm::details::PerEventPolicy< SEED >::UniqueEventIDString().

     {
       return UniqueEventIDString(info)
         + " Timestamp: " + std::to_string(info.time);
     } // PerEventPolicy<SEED>::UniqueEventString()