LArSoft
v09_90_00
Liquid Argon Software toolkit - https://larsoft.org/
|
A class to assist in the distribution of guaranteed unique seeds to all engine IDs. More...
#include "SeedMaster.h"
Classes | |
struct | EngineInfo_t |
Information for each engine. More... | |
Public Types | |
using | seed_t = SEED |
type of served seeds More... | |
using | SeedMaster_t = SeedMaster< SEED > |
type of this class More... | |
using | EngineId = SeedMasterHelper::EngineId |
type of engine ID More... | |
using | Seeder_t = std::function< void(EngineId const &, seed_t)> |
type of a function setting a seed More... | |
using | EventData_t = typename PolicyImpl_t::EventData_t |
type of data used for event seeds More... | |
using | Policy = details::Policy |
Enumeration of the available policies. More... | |
using | EngineInfoIteratorBox = NuRandomServiceHelper::MapKeyConstIteratorBox< EngineData_t > |
An iterator to the configured engine IDs. More... | |
Public Member Functions | |
SeedMaster (const fhicl::ParameterSet &) | |
bool | hasEngine (EngineId const &id) const |
Returns whether the specified engine is already registered. More... | |
bool | hasSeeder (EngineId const &id) const |
Returns whether the specified engine has a valid seeder. More... | |
seed_t | getSeed (std::string moduleLabel) |
Returns the seed value for this module label. More... | |
seed_t | getSeed (std::string moduleLabel, std::string instanceName) |
Returns the seed value for this module label and instance name. More... | |
seed_t | getSeed (EngineId const &) |
Returns the seed value for the engine with the specified ID. More... | |
seed_t | getCurrentSeed (EngineId const &id) const |
Returns the last computed seed value for the specified engine ID. More... | |
void | registerSeeder (EngineId const &id, Seeder_t seeder) |
Register the specified function to reseed the engine id. More... | |
void | registerNewSeeder (EngineId const &id, Seeder_t seeder) |
Register the specified function to reseed the engine id. More... | |
void | freezeSeed (EngineId const &id, seed_t seed) |
Forces SeedMaster not to change the seed of a registered engine. More... | |
seed_t | reseed (EngineId const &id) |
Reseeds the specified engine with a global seed (if any) More... | |
seed_t | reseedEvent (EngineId const &id, EventData_t const &data) |
Reseeds the specified engine with an event seed (if any) More... | |
template<typename Stream > | |
void | print (Stream &&) const |
Prints known (EngineId,seed) pairs. More... | |
EngineInfoIteratorBox | engineIDsRange () const |
Returns an object to iterate in range-for through configured engine IDs. More... | |
void | onNewEvent () |
Prepares for a new event. More... | |
void | print () const |
Prints to the framework Info logger. More... | |
seed_t | getEventSeed (EventData_t const &data, std::string instanceName) |
Returns the seed value for the event with specified data. More... | |
seed_t | getEventSeed (EventData_t const &data, EngineId const &id) |
Returns the seed value for the event with specified data. More... | |
Static Public Member Functions | |
static const std::vector< std::string > & | policyNames () |
Static Public Attributes | |
static constexpr seed_t | InvalidSeed = PolicyImpl_t::InvalidSeed |
An invalid seed. More... | |
Private Types | |
using | PolicyImpl_t = details::RandomSeedPolicyBase< seed_t > |
Type of abstract class for policy implementation. More... | |
using | map_type = std::map< EngineId, seed_t > |
Type for seed data base. More... | |
using | EngineData_t = std::map< EngineId, EngineInfo_t > |
type of map of seeders associated with the engines More... | |
Private Member Functions | |
void | setPolicy (std::string policyName) |
Helper function to parse the policy name. More... | |
void | ensureUnique (EngineId const &id, seed_t seed, map_type const &map) const |
Throws if the seed has already been used. More... | |
void | ensureUnique (EngineId const &id, seed_t seed) const |
Throws if the seed has already been used. More... | |
Static Private Member Functions | |
static seed_t | getSeedFromMap (map_type const &seeds, EngineId const &id) |
Returns a seed from the specified map, or InvalidSeed if not present. More... | |
Private Attributes | |
int | verbosity |
Control the level of information messages. More... | |
Policy | policy |
Which of the supported policies to use? More... | |
map_type | configuredSeeds |
List of seeds computed from configuration information. More... | |
map_type | knownEventSeeds |
List of event seeds already computed. More... | |
map_type | currentSeeds |
List of seeds already computed. More... | |
EngineData_t | engineData |
list of all engine information More... | |
std::unique_ptr< PolicyImpl_t > | policy_impl |
the instance of the random policy More... | |
A class to assist in the distribution of guaranteed unique seeds to all engine IDs.
SEED | type of random engine seed |
rndm::NuRandomService
instead.This class is configured from a FHiCL parameter set. The complete configuration depends on the policy chosen; the following parameters are common to all the policies:
NuRandomService : { policy : "autoIncrement" // Required: Other legal value are listed in SEED_SERVICE_POLICIES verbosity : 0 // Optional: default=0, no informational printout endOfJobSummary : false // Optional: print list of all managed seeds at end of job. }
The policy parameter tells the service to which algorithm to use. If the value of the policy parameter is not one of the known policies, the code will throw an exception.
Code instanciating a SeedMaster can request a seed by making one of the following two calls:
SeedMasterInstance.getSeed("moduleLabel"); SeedMasterInstance.getSeed("moduleLabel", "instanceName");
art module code requests a seed directly to NuRandomService service.
It is the callers responsibility to use the appropriate form.
When getSeed
is called with a particular module label and instance name, it computes a seed value, saves it and returns it. If there is a subsequent call to getSeed
with the same module label and instance name, the class will return the saved value of the seed. The following text will use the phrase "unique calls to `getSeed`"; two calls with the same module label and instance names are not considered unique.
If the policy is defined as autoIncrement
, the additional configurable items are:
NuRandomService : { policy : "autoIncrement" // ... and all the common ones, plus: baseSeed : 0 // Required: An integer >= 0. checkRange : true // Optional: legal values true (default) or false maxUniqueEngines : 20 // Required iff checkRange is true. }
In this policy, the seed is set to baseSeed
+offset
, where on the first unique call to getSeed
the offset
is set to 0; on the second unique call to getSeed
it is set to 1, and so on.
If the policy is defined as linearMapping
, the additional configurable items are:
NuRandomService : { policy : "linearMapping" // ... and all the common ones, plus: nJob : 0 // Required: An integer >= 0. checkRange : true // Optional: legal values true (default) or false maxUniqueEngines : 20 // Required iff checkRange is true. }
In this policy, the seed is set to maxUniqueEngines
*nJob
+offset
, where on the first unique call to getSeed
the offset
is set to 0; on the second unique call to getSeed
it is set to 1, and so on.
If the policy is defined as preDefinedOffset
, the additional configurable items are:
NuRandomService : { policy : "preDefinedOffset" // ... and all the common ones, plus: baseSeed : 0 // Required: An integer >= 0. checkRange : true // Optional: legal values true (default) or false maxUniqueEngines : 20 // Required iff checkRange is true module_label1: offset1 // for each module with a nameless engine module_label2: { // for each module with nemed engine instances instance_name1: offset21 // ... one entry for each instance name instance_name2: offset22 } }
In this policy, when getSeed
is called, the class will look into the parameter set to find a defined offset for the specified module label and instance name. The returned value of the seed will be baseSeed
+offset
.
If the policy is defined as preDefinedSeed
, the additional configurable items are:
NuRandomService : { policy : "preDefinedSeed" // ... and all the common ones, plus: module_label1: seed1 // for each module with a nameless engine module_label2: { // for each module with nemed engine instances instance_name1: seed21 // ... one entry for each instance name instance_name2: seed22 } }
This policy allows to specify the actual seed to be used. Note that the policy does not impose any constraint on the user-provided set of seeds. In particular, the uniqueness of the seeds is not enforced. Intended for debugging and special tests, use with care.
If the policy is defined as random
, the additional configurable items are:
NuRandomService : { policy : "random" // ... and all the common ones, plus: masterSeed: master_seed // optional: an integer >= 0 }
With this policy, the seed is extracted from a local random number generator. The seed used to initialize this additional random number generatot is taken from the clock, unless the masterSeed
parameter is set to specify the actual seed. This policy is meant as a quick way to disentangle the code from the random seed policy used, and it's meant for special needs only and definitely not for production. You can enable this policy instead of whatever is already in your configuration by adding at the end of your configuration:
services.NuRandomService.policy: "random"
(this assumes that the configuration of the SeedMaster is read from services.NuRandomService
, that is the case in the art framework).
The FHiCL grammar to specify the offsets takes two forms. If no instance name is given, the offset is given by:
moduleLabel : offset
When a module has multiple instances, the offsets are given by:
moduleLabel : { instanceName1 : offset1 instanceName2 : offset2 }
SeedMaster
does several additional checks, except for the preDefinedSeed
policy.
If one (module label, instance name) has the same seed as another (module label, instance name), the class will throw an exception.
If the checkRange
parameter is set to true
, and if an offset is generated with a value outside the allowed range (typically 0<= offset < maxUniqueEngines-1
) then the class will also throw an exception.
It is the responsibility of the user to ensure that the parameters (e.g. nJob
and maxUniqueEngines
) are chosen it a way that ensures the required level of uniqueness of seeds. The example grid jobs have a single point of maintenance to achieve this: the user must specify the starting job number for each grid submission.
Definition at line 198 of file SeedMaster.h.
|
private |
type of map of seeders associated with the engines
Definition at line 241 of file SeedMaster.h.
using rndm::SeedMaster< SEED >::EngineId = SeedMasterHelper::EngineId |
type of engine ID
Definition at line 203 of file SeedMaster.h.
using rndm::SeedMaster< SEED >::EngineInfoIteratorBox = NuRandomServiceHelper::MapKeyConstIteratorBox<EngineData_t> |
An iterator to the configured engine IDs.
Definition at line 257 of file SeedMaster.h.
using rndm::SeedMaster< SEED >::EventData_t = typename PolicyImpl_t::EventData_t |
type of data used for event seeds
Definition at line 245 of file SeedMaster.h.
|
private |
Type for seed data base.
Definition at line 213 of file SeedMaster.h.
using rndm::SeedMaster< SEED >::Policy = details::Policy |
Enumeration of the available policies.
Definition at line 251 of file SeedMaster.h.
|
private |
Type of abstract class for policy implementation.
Definition at line 210 of file SeedMaster.h.
using rndm::SeedMaster< SEED >::seed_t = SEED |
type of served seeds
Definition at line 200 of file SeedMaster.h.
using rndm::SeedMaster< SEED >::Seeder_t = std::function<void(EngineId const&, seed_t)> |
type of a function setting a seed
Definition at line 206 of file SeedMaster.h.
using rndm::SeedMaster< SEED >::SeedMaster_t = SeedMaster<SEED> |
type of this class
Definition at line 201 of file SeedMaster.h.
rndm::SeedMaster< SEED >::SeedMaster | ( | const fhicl::ParameterSet & | ) |
Definition at line 435 of file SeedMaster.h.
References rndm::SeedMaster< SEED >::getSeed(), rndm::SeedMaster< SEED >::policy_impl, rndm::SeedMaster< SEED >::print(), and rndm::SeedMaster< SEED >::verbosity.
|
inline |
Returns an object to iterate in range-for through configured engine IDs.
Definition at line 352 of file SeedMaster.h.
|
private |
Throws if the seed has already been used.
It does not take into account per-event seeds, but only configured ones.
Definition at line 692 of file SeedMaster.h.
References art::errors::LogicError.
Referenced by rndm::SeedMaster< seed_t >::ensureUnique(), rndm::SeedMaster< SEED >::getEventSeed(), rndm::SeedMaster< SEED >::getSeed(), and rndm::SeedMaster< SEED >::setPolicy().
|
inlineprivate |
Throws if the seed has already been used.
It does not take into account per-event seeds, but only configured ones.
Definition at line 387 of file SeedMaster.h.
void rndm::SeedMaster< SEED >::freezeSeed | ( | EngineId const & | id, |
seed_t | seed | ||
) |
Forces SeedMaster not to change the seed of a registered engine.
Definition at line 496 of file SeedMaster.h.
References rndm::SeedMaster< SEED >::configuredSeeds, rndm::SeedMaster< SEED >::currentSeeds, rndm::SeedMaster< SEED >::engineData, rndm::SeedMaster< SEED >::reseed(), and seed.
Referenced by rndm::SeedMaster< seed_t >::getCurrentSeed().
|
inline |
Returns the last computed seed value for the specified engine ID.
Definition at line 292 of file SeedMaster.h.
rndm::SeedMaster< SEED >::seed_t rndm::SeedMaster< SEED >::getEventSeed | ( | EventData_t const & | data, |
std::string | instanceName | ||
) |
Returns the seed value for the event with specified data.
Definition at line 665 of file SeedMaster.h.
Referenced by rndm::SeedMaster< SEED >::getEventSeed(), rndm::SeedMaster< SEED >::getSeed(), rndm::SeedMaster< seed_t >::hasSeeder(), and rndm::SeedMaster< SEED >::reseedEvent().
rndm::SeedMaster< SEED >::seed_t rndm::SeedMaster< SEED >::getEventSeed | ( | EventData_t const & | data, |
EngineId const & | id | ||
) |
Returns the seed value for the event with specified data.
Definition at line 637 of file SeedMaster.h.
References rndm::SeedMaster< SEED >::currentSeeds, rndm::SeedMaster< SEED >::ensureUnique(), rndm::SeedMaster< SEED >::getEventSeed(), rndm::SeedMaster< SEED >::InvalidSeed, rndm::SeedMaster< SEED >::knownEventSeeds, rndm::SeedMaster< SEED >::policy_impl, and seed.
|
inline |
Returns the seed value for this module label.
Definition at line 457 of file SeedMaster.h.
Referenced by rndm::SeedMaster< SEED >::getSeed(), rndm::SeedMaster< seed_t >::hasSeeder(), rndm::SeedMaster< SEED >::print(), rndm::SeedMaster< SEED >::reseed(), and rndm::SeedMaster< SEED >::SeedMaster().
rndm::SeedMaster< SEED >::seed_t rndm::SeedMaster< SEED >::getSeed | ( | std::string | moduleLabel, |
std::string | instanceName | ||
) |
Returns the seed value for this module label and instance name.
Definition at line 466 of file SeedMaster.h.
References rndm::SeedMaster< SEED >::getSeed(), and rndm::SeedMaster< SEED >::registerSeeder().
rndm::SeedMaster< SEED >::seed_t rndm::SeedMaster< SEED >::getSeed | ( | EngineId const & | id | ) |
Returns the seed value for the engine with the specified ID.
Definition at line 609 of file SeedMaster.h.
References rndm::SeedMaster< SEED >::configuredSeeds, rndm::SeedMaster< SEED >::currentSeeds, rndm::SeedMaster< SEED >::ensureUnique(), rndm::SeedMaster< SEED >::getEventSeed(), rndm::SeedMaster< SEED >::InvalidSeed, rndm::SeedMaster< SEED >::policy_impl, and seed.
|
inlinestaticprivate |
Returns a seed from the specified map, or InvalidSeed if not present.
Definition at line 396 of file SeedMaster.h.
Referenced by rndm::SeedMaster< seed_t >::getCurrentSeed(), and rndm::SeedMaster< SEED >::print().
|
inline |
Returns whether the specified engine is already registered.
Definition at line 264 of file SeedMaster.h.
Referenced by rndm::NuRandomService::hasEngine(), rndm::SeedMaster< SEED >::print(), and rndm::SeedMaster< SEED >::registerNewSeeder().
|
inline |
Returns whether the specified engine has a valid seeder.
Definition at line 268 of file SeedMaster.h.
|
inline |
Prepares for a new event.
Definition at line 674 of file SeedMaster.h.
References rndm::SeedMaster< SEED >::knownEventSeeds.
Referenced by rndm::SeedMaster< seed_t >::engineIDsRange().
|
static |
Definition at line 428 of file SeedMaster.h.
References rndm::details::policyNames().
void rndm::SeedMaster< SEED >::print | ( | Stream && | log | ) | const |
Prints known (EngineId,seed) pairs.
Definition at line 535 of file SeedMaster.h.
References rndm::SeedMaster< SEED >::configuredSeeds, rndm::SeedMaster< SEED >::currentSeeds, rndm::SeedMaster< SEED >::engineData, rndm::SeedMaster< SEED >::getSeed(), rndm::SeedMaster< SEED >::getSeedFromMap(), rndm::SeedMaster< SEED >::hasEngine(), rndm::SeedMaster< SEED >::InvalidSeed, rndm::SeedMasterHelper::EngineId::isGlobal(), and rndm::SeedMaster< SEED >::policy_impl.
|
inline |
Prints to the framework Info logger.
Definition at line 358 of file SeedMaster.h.
Referenced by rndm::SeedMaster< seed_t >::getCurrentSeed(), rndm::SeedMaster< seed_t >::print(), and rndm::SeedMaster< SEED >::SeedMaster().
void rndm::SeedMaster< SEED >::registerNewSeeder | ( | EngineId const & | id, |
Seeder_t | seeder | ||
) |
Register the specified function to reseed the engine id.
id | ID of the engine to be associated to the seeder |
seeder | function to be used for seeding the engine |
art::Exception | (art::errors::LogicError) if already registered |
This method registers a seeder for a given engine ID, just as registerSeeder() does, except that it throws an exception if a seeder has already been registered for it.
Definition at line 484 of file SeedMaster.h.
References rndm::SeedMaster< SEED >::hasEngine(), art::errors::LogicError, and rndm::SeedMaster< SEED >::registerSeeder().
Referenced by rndm::SeedMaster< seed_t >::getCurrentSeed(), and rndm::SeedMaster< SEED >::registerSeeder().
void rndm::SeedMaster< SEED >::registerSeeder | ( | EngineId const & | id, |
Seeder_t | seeder | ||
) |
Register the specified function to reseed the engine id.
id | ID of the engine to be associated to the seeder |
seeder | function to be used for seeding the engine |
SeedMaster keeps a list of functions that can be used to reseed an existing engine. When reseedEvent() (or reseed()) is called, these functions are invoked to set the seed to the engine.
Definition at line 475 of file SeedMaster.h.
References rndm::SeedMaster< SEED >::engineData, and rndm::SeedMaster< SEED >::registerNewSeeder().
Referenced by rndm::SeedMaster< seed_t >::getCurrentSeed(), rndm::SeedMaster< SEED >::getSeed(), and rndm::SeedMaster< SEED >::registerNewSeeder().
rndm::SeedMaster< SEED >::seed_t rndm::SeedMaster< SEED >::reseed | ( | EngineId const & | id | ) |
Reseeds the specified engine with a global seed (if any)
id | ID of the engine to be reseeded |
Reseeding does not happen if either there is no seeder registered with that engine, or if that engine is already frozen.
Definition at line 506 of file SeedMaster.h.
References rndm::SeedMaster< SEED >::engineData, rndm::SeedMaster< SEED >::getSeed(), rndm::SeedMaster< SEED >::InvalidSeed, rndm::SeedMaster< SEED >::reseedEvent(), and seed.
Referenced by rndm::SeedMaster< SEED >::freezeSeed(), rndm::SeedMaster< seed_t >::getCurrentSeed(), and rndm::NuRandomService::seedEngine().
rndm::SeedMaster< SEED >::seed_t rndm::SeedMaster< SEED >::reseedEvent | ( | EngineId const & | id, |
EventData_t const & | data | ||
) |
Reseeds the specified engine with an event seed (if any)
id | ID of the engine to be reseeded |
data | event data to extract the seed from |
Reseeding does not happen if either there is no seeder registered with that engine, or if that engine is already frozen.
Definition at line 520 of file SeedMaster.h.
References rndm::SeedMaster< SEED >::engineData, rndm::SeedMaster< SEED >::getEventSeed(), rndm::SeedMaster< SEED >::InvalidSeed, and seed.
Referenced by rndm::SeedMaster< seed_t >::getCurrentSeed(), and rndm::SeedMaster< SEED >::reseed().
|
private |
Helper function to parse the policy name.
Definition at line 682 of file SeedMaster.h.
References rndm::SeedMaster< SEED >::ensureUnique(), rndm::SeedMaster< SEED >::policy, and rndm::details::policyFromName().
|
private |
List of seeds computed from configuration information.
Definition at line 368 of file SeedMaster.h.
Referenced by rndm::SeedMaster< SEED >::freezeSeed(), rndm::SeedMaster< SEED >::getSeed(), and rndm::SeedMaster< SEED >::print().
|
private |
List of seeds already computed.
Definition at line 374 of file SeedMaster.h.
Referenced by rndm::SeedMaster< SEED >::freezeSeed(), rndm::SeedMaster< seed_t >::getCurrentSeed(), rndm::SeedMaster< SEED >::getEventSeed(), rndm::SeedMaster< SEED >::getSeed(), and rndm::SeedMaster< SEED >::print().
|
private |
list of all engine information
Definition at line 376 of file SeedMaster.h.
Referenced by rndm::SeedMaster< seed_t >::engineIDsRange(), rndm::SeedMaster< SEED >::freezeSeed(), rndm::SeedMaster< seed_t >::hasEngine(), rndm::SeedMaster< seed_t >::hasSeeder(), rndm::SeedMaster< SEED >::print(), rndm::SeedMaster< SEED >::registerSeeder(), rndm::SeedMaster< SEED >::reseed(), and rndm::SeedMaster< SEED >::reseedEvent().
|
static |
An invalid seed.
Definition at line 248 of file SeedMaster.h.
Referenced by rndm::SeedMaster< SEED >::getEventSeed(), rndm::SeedMaster< SEED >::getSeed(), rndm::SeedMaster< SEED >::print(), rndm::SeedMaster< SEED >::reseed(), and rndm::SeedMaster< SEED >::reseedEvent().
|
private |
List of event seeds already computed.
Definition at line 371 of file SeedMaster.h.
Referenced by rndm::SeedMaster< SEED >::getEventSeed(), and rndm::SeedMaster< SEED >::onNewEvent().
|
private |
Which of the supported policies to use?
Definition at line 365 of file SeedMaster.h.
Referenced by rndm::SeedMaster< SEED >::setPolicy().
|
private |
the instance of the random policy
Definition at line 392 of file SeedMaster.h.
Referenced by rndm::SeedMaster< SEED >::getEventSeed(), rndm::SeedMaster< SEED >::getSeed(), rndm::SeedMaster< SEED >::print(), and rndm::SeedMaster< SEED >::SeedMaster().
|
private |
Control the level of information messages.
Definition at line 362 of file SeedMaster.h.
Referenced by rndm::SeedMaster< SEED >::SeedMaster().