rndm::NuRandomService Class Reference

An art service to assist in the distribution of guaranteed unique seeds to all engines within an art job. More...

#include "NuRandomService.h"

Classes
class	CLHEPengineSeeder
	Seeder_t functor setting the seed of a CLHEP::HepRandomEngine engine (untested!) More...

Public Types
using	seed_t = art::RandomNumberGenerator::seed_t
using	SeedMaster_t = SeedMaster< seed_t >
	type of object providing seeds More...
using	EngineId = SeedMaster_t::EngineId
	type of random engine ID More...

Public Member Functions
	NuRandomService (const fhicl::ParameterSet &, art::ActivityRegistry &)
	NuRandomService (NuRandomService const &)=delete
NuRandomService const &	operator= (NuRandomService const &)=delete
	NuRandomService (NuRandomService &&)=delete
NuRandomService const &	operator= (NuRandomService &&)=delete
	~NuRandomService ()=default
seed_t	getSeed (std::string instanceName)
	Returns a seed for the engine with specified instance name. More...
seed_t	getSeed ()
	Returns a seed for the engine with default instance name. More...
seed_t	getGlobalSeed (std::string instanceName)
	Returns a seed for the global engine with specified instance name. More...
seed_t	getCurrentSeed (std::string instanceName) const
	Returns the last computed seed for specified engine of current module. More...
seed_t	getCurrentSeed () const
	Returns the last computed seed for the default engine of current module. More...
seed_t	getGlobalCurrentSeed (std::string instanceName) const
	Returns the last computed seed for the specified global engine. More...
seed_t	registerEngine (CLHEP::HepRandomEngine &engine, std::string instance="")
	Registers an existing CLHEP engine with NuRandomService. More...
seed_t	registerEngine (CLHEP::HepRandomEngine &engine, std::string instance, fhicl::ParameterSet const &pset, std::initializer_list< std::string > pnames)
template<class Stream >
void	print (Stream &&out) const
	Prints known (EngineId,seed) pairs. More...
void	print () const
	Prints to the framework Info logger. More...
Create and register an engine
The life time of the engine is managed by art::RandomNumberGenerator, while the seeding is managed by this service. This is a replacement of art::EngineCreator-derived classes. The use of createEngine() class of function is discouraged and this function might be removed in the future, because of its non-clean use of module interfaces. The recommended approach is more verbose; here an example for an engine with a non-default instance name: std::string const instanceName = "instanceName"; auto& Seeds = *(art::ServiceHandle<rndm::NuRandomService>()); // declare an engine; NuRandomService associates an (unknown) engine, in // the current module and an instance name, with a seed (returned) auto const seed = Seeds.declareEngine(instanceName); // now create the engine (for example, use art); seed will be set createEngine(seed, "HepJamesRandom", instanceName); // finally, complete the registration; seed will be set again art::ServiceHandle<art::RandomNumberGenerator> RNG; Seeds.defineEngine(RNG->getEngine(instanceName)); This is equivalent to the discouraged call auto& Seeds = *(art::ServiceHandle<rndm::NuRandomService>()); Seeds.createEngine(*this, "HepJamesRandom", "instanceName");
seed_t	createEngine (art::EngineCreator &module, std::string type, std::string instance="")
	Creates an engine with RandomNumberGenerator service. More...
seed_t	createEngine (art::EngineCreator &module)
	Creates an engine with RandomNumberGenerator service. More...
seed_t	createEngine (art::EngineCreator &module, std::string type, std::string instance, fhicl::ParameterSet const &pset, std::string pname)
	Creates an engine with RandomNumberGenerator service. More...
seed_t	createEngine (art::EngineCreator &module, std::string type, std::string instance, fhicl::ParameterSet const &pset, std::initializer_list< std::string > pnames)
	Creates an engine with RandomNumberGenerator service. More...
seed_t	createEngine (art::EngineCreator &module, std::string type, fhicl::ParameterSet const &pset, std::string pname)
	Creates an engine with RandomNumberGenerator service. More...
seed_t	createEngine (art::EngineCreator &module, std::string type, fhicl::ParameterSet const &pset, std::initializer_list< std::string > pnames)
	Creates an engine with RandomNumberGenerator service. More...
seed_t	createEngine (art::EngineCreator &module, fhicl::ParameterSet const &pset, std::string pname)
	Creates an engine with RandomNumberGenerator service. More...
seed_t	createEngine (art::EngineCreator &module, fhicl::ParameterSet const &pset, std::initializer_list< std::string > pnames)
	Creates an engine with RandomNumberGenerator service. More...
Register an existing engine
The life time of the engine is under user's control, while the seeding is managed by this service.
seed_t	registerEngine (SeedMaster_t::Seeder_t seeder, std::string instance="")
	Registers an existing engine with NuRandomService. More...
seed_t	registerEngine (SeedMaster_t::Seeder_t seeder, std::string instance, fhicl::ParameterSet const &pset, std::string pname)
	Registers an existing engine with NuRandomService. More...
seed_t	registerEngine (SeedMaster_t::Seeder_t seeder, std::string instance, fhicl::ParameterSet const &pset, std::initializer_list< std::string > pnames)
	Registers an existing engine with NuRandomService. More...
seed_t	registerEngine (SeedMaster_t::Seeder_t seeder, fhicl::ParameterSet const &pset, std::string pname)
	Registers an existing engine with NuRandomService. More...
seed_t	registerEngine (SeedMaster_t::Seeder_t seeder, fhicl::ParameterSet const &pset, std::initializer_list< std::string > pnames)
	Registers an existing engine with NuRandomService. More...
Declare the presence of an engine
seed_t	declareEngine (std::string instance="")
	Declares the presence of an engine with a given instance name. More...
seed_t	declareEngine (std::string instance, fhicl::ParameterSet const &pset, std::string pname)
	Declares the presence of an engine with a given instance name. More...
seed_t	declareEngine (std::string instance, fhicl::ParameterSet const &pset, std::initializer_list< std::string > pnames)
	Declares the presence of an engine with a given instance name. More...
seed_t	declareEngine (fhicl::ParameterSet const &pset, std::string pname)
	Declares the presence of an engine with a default instance name. More...
seed_t	declareEngine (fhicl::ParameterSet const &pset, std::initializer_list< std::string > pnames)
	Declares the presence of an engine with a default instance name. More...
seed_t	defineEngine (SeedMaster_t::Seeder_t seeder, std::string instance={})
	Defines a seeder for a previously declared engine. More...
seed_t	defineEngine (CLHEP::HepRandomEngine &engine, std::string instance={})
	Defines a seeder for a previously declared engine. More...

Static Public Member Functions
static constexpr bool	isSeedValid (seed_t seed)
	Returns whether the specified seed is valid. More...
static void	RandomNumberGeneratorSeeder (EngineId const &id, seed_t seed)
	Seeder_t function setting the seed of an engine in RandomNumberGenerator. More...

Static Public Attributes
static constexpr seed_t	InvalidSeed = SeedMaster_t::InvalidSeed
	An invalid seed. More...

Private Member Functions
seed_t	registerEngineID (EngineId const &id, SeedMaster_t::Seeder_t seeder=SeedMaster_t::Seeder_t())
	Register an engine and seeds it with the seed from the master. More...
seed_t	defineEngineID (EngineId const &id, SeedMaster_t::Seeder_t seeder)
	Set the seeder of an existing engine. More...
bool	hasEngine (EngineId const &id) const
	Returns whether the specified engine is already registered. More...
seed_t	getSeed (EngineId const &)
seed_t	getEventSeed (EngineId const &)
seed_t	reseedInstance (EngineId const &id)
	Reseeds the specified engine instance in the current module. More...
void	reseedGlobal ()
	Reseed all the global engines. More...
seed_t	prepareEngine (EngineId const &id, SeedMaster_t::Seeder_t seeder)
	Registers the engine ID into SeedMaster. More...
void	ensureValidState (bool bGlobal=false) const
seed_t	querySeed (EngineId const &id)
	Query a seed from the seed master. More...
std::pair< seed_t, bool >	findSeed (EngineId const &id, fhicl::ParameterSet const &pset, std::initializer_list< std::string > pnames)
void	freezeSeed (EngineId const &id, seed_t frozen_seed)
	Forces NuRandomService not to change the seed of the specified engine. More...
void	registerEngineAndSeeder (EngineId const &id, SeedMaster_t::Seeder_t seeder)
	Registers an engine and its seeder. More...
seed_t	seedEngine (EngineId const &id)
	Calls the seeder with the specified seed and engine ID. More...
void	preModuleConstruction (art::ModuleDescription const &md)
void	postModuleConstruction (art::ModuleDescription const &)
void	preModuleBeginRun (art::ModuleDescription const &md)
void	postModuleBeginRun (art::ModuleDescription const &)
void	preProcessEvent (art::Event const &evt)
void	preModule (art::ModuleDescription const &md)
void	postModule (art::ModuleDescription const &)
void	postProcessEvent (art::Event const &)
void	preModuleEndJob (art::ModuleDescription const &md)
void	postModuleEndJob (art::ModuleDescription const &)
void	postEndJob ()
void	reseedModule (std::string currentModule)
	Reseeds all the engines in the current module. More...
void	reseedModule ()
	Reseeds all the engines in the current module. More...
EngineId	qualify_engine_label (std::string moduleLabel, std::string instanceName) const
	Returns a fully qualified EngineId. More...
EngineId	qualify_engine_label (std::string instanceName="") const
	Returns a fully qualified EngineId. More...
EngineId	qualify_global_engine (std::string instanceName="") const
	Returns a fully qualified EngineId. More...

Static Private Member Functions
static bool	readSeedParameter (seed_t &seed, fhicl::ParameterSet const &pset, std::string pname)
static bool	readSeedParameter (seed_t &seed, fhicl::ParameterSet const &pset, std::initializer_list< std::string > pnames)

Private Attributes
SeedMaster_t	seeds
	Class managing the seeds. More...
NuRandomServiceHelper::ArtState	state
int	verbosity = 0
	Control the level of information messages. More...
bool	bPrintEndOfJobSummary = false
	print a summary at the end of job More...

Detailed Description

An art service to assist in the distribution of guaranteed unique seeds to all engines within an art job.

See also

SeedMaster

NuRandomService centrally manages seeds for random generator engines.

The NuRandomService acts as an interface between art framework and the SeedMaster class.

The documentation is mantained in the SeedMaster class. The configuration of NuRandomService is exactly the same as SeedMaster's, and in art it's read from services.NuRandomService. The following documentation describes features of NuRandomService that are built on top of SeedMaster to have a more convenient interaction within the art framework.

Before asking NuRandomService for its seed, an engine must be in some way registered. Once the engine is registered, its original seed can be queried again by calling getSeed() methods.

Glossary

Here "engine" means a class that is able to generate random numbers according to a flat distribution. Both art and NuRandomService are module-based, that means that the engines are in the context of a specific module instance, and different module instances have independent engines. That is the reason why you don't need to specify anything about the module when creating or obtaining a random engine, and it is also the reason why engines outside module context are not supported by the framework.

Each module can need more than one engine. A module can have any number of engines, and each of them is identified by an "instance name" that is unique within the module. Nonetheless, most modules need just one engine. In that case, a default instance name can be used (that is an empty string).

A "seeder" is a callable object (e.g. a function) that sets the seed of a certain engine. The seeder is expected to find out by its own which engine it has to seed, and fot that it is provided an engine ID.

Registration of a random generator engine

Registration must happen in art module constructor, in one of the following ways:

• by asking this service to create an engine via RandomNumberGenerator (see createEngine() methods) [discouraged]
• by registering an existing engine and its seeding function (see registerEngine() methods)
• by just declaring that an engine exists (see declareEngine() and getSeed() methods) The first method and, when a seeder or an engine is provided, also the second method, set the seed of the engine they register (see below). In the third case, it is generally the caller's responsibility to seed the engine. The registration of an engine which has been only declared can be "completed" by calling defineEngine() to provide the actual seeder for that engine. The pair of calls declareEngine()/defineEngine() (or getSeed()/defineEngine()) is equivalent to a single call to registerEngine(), with the added flexibility of having the seed for the engine already available before the registration is completed.

The use of createEngine() class of function is discouraged and this function might be removed in the future, because of its non-clean use of module interfaces. The recommended approach is more prolix; here an example for an engine with a non-default instance name:

std::string const instanceName = "instanceName";
auto& Seeds = *(art::ServiceHandle<rndm::NuRandomService>());

// declare an engine; NuRandomService associates an (unknown) engine, in
// the current module and an instance name, with a seed (returned)
auto const seed = Seeds.declareEngine(instanceName);

// now create the engine (for example, use art); seed will be set
createEngine(seed, "HepJamesRandom", instanceName);

// finally, complete the registration; seed will be set again
art::ServiceHandle<art::RandomNumberGenerator> RNG;
Seeds.defineEngine(RNG->getEngine(instanceName));

This is equivalent to the discouraged call

auto& Seeds = *(art::ServiceHandle<rndm::NuRandomService>());
Seeds.createEngine(*this, "HepJamesRandom", "instanceName");

Please read carefully the documentation of the method of your choice, since they have different requirements and apply to different usage patterns.

The registration must happen in the constructor of the module. That is because we don't want engines to be initialized in the middle of a job.

Setting the seed of an engine

NuRandomService is able to set the seed of an engine when the engine is registered via either:

• createEngine() (creation of a new CLHEP engine)
• registerEngine() (registration of an engine or a seeder function), if the registered seeder function is valid (non-null) or if a CLHEP engine is being registered (in which case the seeder is automatically created valid)
• defineEngine() (registration of a seeder for an engine that was already declared), again if the seed is valid NuRandomService is not able to automatically set the seed of an engine if it was registered via either:
• declareEngine() (declaration of the existence of an engine), that does not even require the engine to exist
• getSeed() (query of a seed), when it (implicitly) declares an engine which had not been declared yet

If NuRandomService is able to set the seed, it will do so only once, as soon as it can. This means that if the policy allows the seed to be known immediately, the seed will be set on registration. In the case of a per-event policy that requires the presence of an event, the seed can be known only when the event is available, and NuRandomService will set the seed before the module the engine is associated with starts its main processing method (produce(), filter() or analyze()).

Changing the seeder

Currently, changing the seeder of an engine after the engine has been fully registered is not supported. As a consequence, changing the engine is also not supported.

Since only the seeder function is registered in NuRandomService, a seeder function that is flexible enough to change the engine it seeds may work around this limitation.

Querying the seed of an engine

If necessary, the seed that NuRandomService has assigned to an engine can be requested by one of the following two calls:

art::ServiceHandle<NuRandomService>->getSeed();
art::ServiceHandle<NuRandomService>->getSeed("instanceName");

depending on whether the engine has a non-empty instance name, Note that this call implicitly "declares" the engine it refers to.

For most policies, the seed is set according to the configuration, once for all. In those cases, getSeed() will always return the same value. If the policy prescribes different seeds at different times, the method returns the seed that is assigned to the engine at the time of the call.

Also note that the seed assigned by NuRandomService might not match the current seed of the engine, if:

• NuRandomService is not in charge of setting the seed of the engine, and the engine seed has not been set yet
• the seed was reset directly after NuRandomService set the engine seed Both circumstances should be avoided.

Creating the engines independently of NuRandomService

A number of things must happen for an engine to correctly work with NuRandomService:

• the engine instance needs to exist or be created
• the engine must be "registered" into NuRandomService
• the seed must be obtained from NuRandomService
• the seed must be provided to the engine

A recipe for creating a ROOT engine and let NuRandomService take care of its seeds is:

// create the engine; ROOT will set some (temporary) seed
fRandom = std::make_unique<TRandom3>();

// declare the engine; NuRandomService associates its seeder, in
// the current module and an instance name, with a seed (returned);
// the seed is also set in the engine
auto& Seeds = *(art::ServiceHandle<rndm::NuRandomService>());
Seeds.registerEngine(TRandomSeeder(fRandom), "instanceName");

Here fRandom is supposed to be a member function of the module. The TRandomSeeder object is an object that knows how to set the seed of the TRandom-derived ROOT generator passed as constructor argument. For an example of implementation, see the source code of NuRandomService.

Overriding the seed from NuRandomService at run time

NuRandomService (and SeedMaster, which the former relies upon) will decide which seed to give to each registered engine and, when possible (see above), will set that seed too.

All registration functions offer an extended signature to tell NuRandomService that if there is an explicitly configured seed, that should take presedence over the one automatically assigned by SeedMaster policy. This extended signature includes:

• a FHiCL parameter set
• a configuration parameter name, or a list of them NuRandomService will look in the specified parameter set and if it finds a value corresponding to any of the specified parameter names, will set the seed of the engine to that value, and it will mark the engine as "frozen" (meaning that NuRandomService will not ever set a seed again on that engine). [see also the exception to this rule below]

The typical use of this function is to read a parameter ("Seed" is the suggested name) from the configuration of the module. Note that this is in contrast with the location where NuRandomService seeds are normally configured, that is in the configuration of NuRandomService service itself. For example:

// within module construction:
art::ServiceHandle<rndm::NuRandomService>()->registerEngine
  (engine, "instanceName", pset, { "Seed", "MySeed" });

Here NuRandomService will provide a seed only if it does not find in the parameter set pset any of the specified configuration parameters (first "Seed", then "MySeed" in this example). In other words, if "Seed" exists, its value is used as seed, otherwise if "MySeed" exists, its value is used instead, and otherwise NuRandomService is given control on that seed. The exception is that if the specified seed is a "magic value", the InvalidSeed (0), it is interpreted as a request to ignore the parameter and use the service to get the seed. This is made as a quick way to remove the seed override from an existing FHiCL file with one line. Note that if NuRandomService does not get the control on the seed, policies that reseed on event-by-event basis will not act on the engine.

Engines outside of the module context

It is possible to have engines that are not associated with any module. If no module is current, an engine will be registered in a "global" context. This happens during service construction, and once the service construction phase is completed, no more global engines can be registered. Would one ever need to access the seed of such engine, a specific interface needs to be used: getGlobalSeed() to get the configured seed at the beginning of the job, or getGlobalCurrentSeed() to get the seed specific for the current event, if any. These are equivalent to the module context methods getSeed() and getCurrentSeed().

The art service RandomNumberGenerator does not support the creation of module-independent engines. The ownership of each global engine is by the using service, as well as the management of engine's lifetime. After an engine has been instantiated, it can be registered with registerEngine(). Likewise, a global engine can be declared first with declareEngine(), then instantiated, and then optionally defined with defineEngine(). This is completely analogous to the module-context engines. The only difference is that no createEngine() interface is available for global engines. Whether these methods create a global or module engine depends only on the context they are called in.

NuRandomService does not manage the engine life in any way. If a service owns an engine, it also needs a way to access it, as nothing equivalent to RandomNumberGenerator's getEngine() is provided. NuRandomService does manage the seeding of the registered engines, even the global ones. If the seed policy involves a event-dependent seed, all global engines are seeded together at the beginning of the event, before any module is executed. This mechanism relies on the fact that NuRandomService gets its preProcessEvent callback executed before the ones of the services that own any engine. This is guaranteed if the service constructors invoke NuRandomService before they register their callbacks.

For an example of usage, see GlobalEngineUserTestService service in the test suite. Here is an excerpt using a ROOT TRandom3 engine, that can be constructed without seed. In the service constructor, the code:

// create a new engine, that we own (engine be a class data member)
engine = std::make_unique<TRandom3>();
auto seed = Seeds.registerEngine
  (rndm::NuRandomService::TRandomSeeder(engine.get()), "MyService");

// MyService callback registrations in the ActivityRegistry
// should follow the first call to NuRandomService!

where rndm::NuRandomService::TRandomSeeder is a seeder class for TRandom engines (optionally provided in NuRandomService.h, and very easy to write). This excerpt creates and owns a TRandom3 engine, and then it registers it to NuRandomService, which immediately sets its seed and will take care of reseeding the engine at each event, should the policy require it. The service will access the engine as a data member, and should it need the seed it will use:

art::ServiceHandle<rndm::NuRandomService>()->getGlobalSeed("MyService");

Note that is a good idea to give the engine an instance name after the service name itself, since the instance name is global and it's the only thing distinguishing global engines, and name conflicts between different services may easily arise.

Definition at line 360 of file NuRandomService.h.

Member Typedef Documentation

using rndm::NuRandomService::EngineId = SeedMaster_t::EngineId

type of random engine ID

Definition at line 366 of file NuRandomService.h.

using rndm::NuRandomService::seed_t = art::RandomNumberGenerator::seed_t

Definition at line 362 of file NuRandomService.h.

using rndm::NuRandomService::SeedMaster_t = SeedMaster<seed_t>

type of object providing seeds

Definition at line 364 of file NuRandomService.h.

Constructor & Destructor Documentation

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

rndm::NuRandomService::NuRandomService ( NuRandomService const &  )

delete

rndm::NuRandomService::NuRandomService ( NuRandomService &&  )

delete

rndm::NuRandomService::~NuRandomService ( )

default

Member Function Documentation

NuRandomService::seed_t rndm::NuRandomService::createEngine	(	art::EngineCreator &	module,
		std::string	type,
		std::string	instance = ""
	)

Creates an engine with RandomNumberGenerator service.

Parameters

module	module who will own the new engine
type	the type of engine
instance	the name of the engine instance

Returns

the seed used

See also

registerEngine()

This method creates a new engine by calling RandomNumberGenerator::createEngine() with the seed from getSeed(). The meaning of the two parameters is the same as in that function, including the somehow inconvenient order of the arguments

Note

The module parameter is needed since the interface to create an engine by RandomNumberGenerator service is private and open only to friends.

Definition at line 132 of file NuRandomService_service.cc.

References art::EngineCreator::createEngine(), prepareEngine(), qualify_engine_label(), RandomNumberGeneratorSeeder(), and seed.

Referenced by evwgh::WeightManager::Configure().

    {
    EngineId id = qualify_engine_label(instance);
    const seed_t seed = prepareEngine(id, RandomNumberGeneratorSeeder);
    module.createEngine(seed, type, instance);
    mf::LogInfo("NuRandomService")
      << "Seeding " << type << " engine \"" << id.artName()
      << "\" with seed " << seed << ".";
    return seed;
  } // NuRandomService::createEngine(strings)

NuRandomService::seed_t rndm::NuRandomService::createEngine

(

art::EngineCreator &

module

)

Creates an engine with RandomNumberGenerator service.

Parameters

module	module who will own the new engine
type	the type of engine
instance	the name of the engine instance

Returns

the seed used

See also

registerEngine()

This method creates a new engine by calling RandomNumberGenerator::createEngine() with the seed from getSeed(). The meaning of the two parameters is the same as in that function, including the somehow inconvenient order of the arguments

Note

The module parameter is needed since the interface to create an engine by RandomNumberGenerator service is private and open only to friends.

Definition at line 146 of file NuRandomService_service.cc.

References art::EngineCreator::createEngine(), prepareEngine(), qualify_engine_label(), RandomNumberGeneratorSeeder(), and seed.

                                                                              {
    EngineId id = qualify_engine_label();
    const seed_t seed = prepareEngine(id, RandomNumberGeneratorSeeder);
    module.createEngine(seed);
    mf::LogInfo("NuRandomService")
      << "Seeding default-type engine \"" << id.artName()
      << "\" with seed " << seed << ".";
    return seed;
  } // NuRandomService::createEngine()

seed_t rndm::NuRandomService::createEngine ( art::EngineCreator &  module, std::string  type, std::string  instance, fhicl::ParameterSet const &  pset, std::string  pname  )

inline

Creates an engine with RandomNumberGenerator service.

Parameters

module	module who will own the new engine
type	the type of engine
instance	the name of the engine instance
pset	parameter set to read parameters from
pname	name or names of the seed parameters

Returns

the seed used

See also

registerEngine()

This method creates a new engine by calling RandomNumberGenerator::createEngine() with the seed from getSeed(). The meaning of the two parameters is the same as in that function, including the somehow inconvenient order of the arguments

The engine seed is set. First, the seed is retrieved from the specified configuration, looking for the first of the parameters in pname that is avaialble. If no parameter is found, the seed is obtained from NuRandomService.

Note

The module parameter is needed since the interface to create an engine by RandomNumberGenerator service is private and open only to friends.

Definition at line 539 of file NuRandomService.h.

      { return createEngine(module, type, instance, pset, { pname }); }

NuRandomService::seed_t rndm::NuRandomService::createEngine	(	art::EngineCreator &	module,
		std::string	type,
		std::string	instance,
		fhicl::ParameterSet const &	pset,
		std::initializer_list< std::string >	pnames
	)

Creates an engine with RandomNumberGenerator service.

Parameters

module	module who will own the new engine
type	the type of engine
instance	the name of the engine instance
pset	parameter set to read parameters from
pname	name or names of the seed parameters

Returns

the seed used

See also

registerEngine()

This method creates a new engine by calling RandomNumberGenerator::createEngine() with the seed from getSeed(). The meaning of the two parameters is the same as in that function, including the somehow inconvenient order of the arguments

The engine seed is set. First, the seed is retrieved from the specified configuration, looking for the first of the parameters in pname that is avaialble. If no parameter is found, the seed is obtained from NuRandomService.

Note

The module parameter is needed since the interface to create an engine by RandomNumberGenerator service is private and open only to friends.

Definition at line 157 of file NuRandomService_service.cc.

References art::EngineCreator::createEngine(), findSeed(), freezeSeed(), qualify_engine_label(), RandomNumberGeneratorSeeder(), and registerEngineAndSeeder().

    {
    EngineId id = qualify_engine_label(instance);
    registerEngineAndSeeder(id, RandomNumberGeneratorSeeder);
    std::pair<seed_t, bool> seedInfo = findSeed(id, pset, pnames);
    module.createEngine(seedInfo.first, type, instance);
    mf::LogInfo("NuRandomService")
      << "Seeding " << type << " engine \"" << id.artName()
      << "\" with seed " << seedInfo.first << ".";
    if (seedInfo.second) freezeSeed(id, seedInfo.first);
    return seedInfo.first;
  } // NuRandomService::createEngine(ParameterSet)

seed_t rndm::NuRandomService::createEngine ( art::EngineCreator &  module, std::string  type, fhicl::ParameterSet const &  pset, std::string  pname  )

inline

Creates an engine with RandomNumberGenerator service.

Parameters

module	module who will own the new engine
type	the type of engine
instance	the name of the engine instance
pset	parameter set to read parameters from
pname	name or names of the seed parameters

Returns

the seed used

See also

registerEngine()

This method creates a new engine by calling RandomNumberGenerator::createEngine() with the seed from getSeed(). The meaning of the two parameters is the same as in that function, including the somehow inconvenient order of the arguments

The engine seed is set. First, the seed is retrieved from the specified configuration, looking for the first of the parameters in pname that is avaialble. If no parameter is found, the seed is obtained from NuRandomService.

Note

The module parameter is needed since the interface to create an engine by RandomNumberGenerator service is private and open only to friends.

Definition at line 548 of file NuRandomService.h.

      { return createEngine(module, type, "", pset, pname); }

seed_t rndm::NuRandomService::createEngine ( art::EngineCreator &  module, std::string  type, fhicl::ParameterSet const &  pset, std::initializer_list< std::string >  pnames  )

inline

Creates an engine with RandomNumberGenerator service.

Parameters

module	module who will own the new engine
type	the type of engine
instance	the name of the engine instance
pset	parameter set to read parameters from
pname	name or names of the seed parameters

Returns

the seed used

See also

registerEngine()

This method creates a new engine by calling RandomNumberGenerator::createEngine() with the seed from getSeed(). The meaning of the two parameters is the same as in that function, including the somehow inconvenient order of the arguments

The engine seed is set. First, the seed is retrieved from the specified configuration, looking for the first of the parameters in pname that is avaialble. If no parameter is found, the seed is obtained from NuRandomService.

Note

The module parameter is needed since the interface to create an engine by RandomNumberGenerator service is private and open only to friends.

Definition at line 553 of file NuRandomService.h.

      { return createEngine(module, type, "", pset, pnames); }

seed_t rndm::NuRandomService::createEngine ( art::EngineCreator &  module, fhicl::ParameterSet const &  pset, std::string  pname  )

inline

Creates an engine with RandomNumberGenerator service.

Parameters

module	module who will own the new engine
type	the type of engine
instance	the name of the engine instance
pset	parameter set to read parameters from
pname	name or names of the seed parameters

Returns

the seed used

See also

registerEngine()

This method creates a new engine by calling RandomNumberGenerator::createEngine() with the seed from getSeed(). The meaning of the two parameters is the same as in that function, including the somehow inconvenient order of the arguments

The engine seed is set. First, the seed is retrieved from the specified configuration, looking for the first of the parameters in pname that is avaialble. If no parameter is found, the seed is obtained from NuRandomService.

Note

The module parameter is needed since the interface to create an engine by RandomNumberGenerator service is private and open only to friends.

Definition at line 558 of file NuRandomService.h.

      { return createEngine(module, pset, { pname }); }

NuRandomService::seed_t rndm::NuRandomService::createEngine	(	art::EngineCreator &	module,
		fhicl::ParameterSet const &	pset,
		std::initializer_list< std::string >	pnames
	)

Creates an engine with RandomNumberGenerator service.

Parameters

module	module who will own the new engine
type	the type of engine
instance	the name of the engine instance
pset	parameter set to read parameters from
pname	name or names of the seed parameters

Returns

the seed used

See also

registerEngine()

This method creates a new engine by calling RandomNumberGenerator::createEngine() with the seed from getSeed(). The meaning of the two parameters is the same as in that function, including the somehow inconvenient order of the arguments

The engine seed is set. First, the seed is retrieved from the specified configuration, looking for the first of the parameters in pname that is avaialble. If no parameter is found, the seed is obtained from NuRandomService.

Note

The module parameter is needed since the interface to create an engine by RandomNumberGenerator service is private and open only to friends.

Definition at line 174 of file NuRandomService_service.cc.

References art::EngineCreator::createEngine(), findSeed(), freezeSeed(), qualify_engine_label(), RandomNumberGeneratorSeeder(), registerEngine(), and registerEngineAndSeeder().

    {
    EngineId id = qualify_engine_label();
    registerEngineAndSeeder(id, RandomNumberGeneratorSeeder);
    std::pair<seed_t, bool> seedInfo = findSeed(id, pset, pnames);
    module.createEngine(seedInfo.first);
    mf::LogInfo("NuRandomService")
      << "Seeding default-type engine \"" << id.artName()
      << "\" with seed " << seedInfo.first << ".";
    if (seedInfo.second) freezeSeed(id, seedInfo.first);
    return seedInfo.first;
  } // NuRandomService::createEngine(ParameterSet)

NuRandomService::seed_t rndm::NuRandomService::declareEngine

(

std::string

instance = ""

)

Declares the presence of an engine with a given instance name.

Parameters

instance

name of the instance of the engine (empty by default)

Returns

the seed assigned to the engine (may be invalid)

The existence of an engine with the specified instance name is recorded, and a seed is assigned to it. The engine will be identified by the instance name and by context information (the current module).

Differently from createEngine() and registerEngine(), the actual existence of a engine is not required. It is up to the user to manage the engine, if any at all, including the seeding.

Definition at line 211 of file NuRandomService_service.cc.

References registerEngine().

                                                                         {
    return registerEngine(SeedMaster_t::Seeder_t(), instance);
  } // NuRandomService::declareEngine(string)

seed_t rndm::NuRandomService::declareEngine ( std::string  instance, fhicl::ParameterSet const &  pset, std::string  pname  )

inline

Declares the presence of an engine with a given instance name.

Parameters

instance	name of the instance of the engine
pset	parameter set where to find a possible fixed seed request
pname	the name of the parameter for the fixed seed request

Returns

the seed assigned to the engine (may be invalid)

The existence of an engine with the specified instance name is recorded, and a seed is assigned to it. The engine will be identified by the instance name and by context information (the current module).

The preferred way to obtain the seed is from configuration. First, the seed is retrieved from the specified configuration, looking for the first of the parameters in pname that is available. If no parameter is found, the seed is obtained from NuRandomService.

Differently from createEngine() and registerEngine(), the actual existence of a engine is not required. It is up to the user to manage the engine, if any at all, including the seeding.

Definition at line 720 of file NuRandomService.h.

      { return declareEngine(instance, pset, { pname }); }

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

Declares the presence of an engine with a given instance name.

Parameters

instance	name of the instance of the engine
pset	parameter set where to find a possible fixed seed request
pnames	name of the parameters for the fixed seed request

Returns

the seed assigned to the engine (may be invalid)

See also

declareEngine(std::string, fhicl::ParameterSet const&, std::string)

This method provides the same function as declareEngine(std::string, fhicl::ParameterSet const&, std::string), but it can pick the seed from the first parameter among the ones in pset whose name is in pnames.

Definition at line 216 of file NuRandomService_service.cc.

References defineEngine(), and registerEngine().

    {
    return registerEngine(SeedMaster_t::Seeder_t(), instance, pset, pnames);
  } // NuRandomService::declareEngine(string, ParameterSet, init list)

seed_t rndm::NuRandomService::declareEngine ( fhicl::ParameterSet const &  pset, std::string  pname  )

inline

Declares the presence of an engine with a default instance name.

Parameters

pset	parameter set where to find a possible fixed seed request
pname	the name of the parameter for the fixed seed request

Returns

the seed assigned to the engine (may be invalid)

See also

declareEngine(fhicl::ParameterSet const&, std::string)

This method provides the same function as declareEngine(std::string, fhicl::ParameterSet const&, std::string), but it gives the engine a empty instance name.

Definition at line 752 of file NuRandomService.h.

      { return declareEngine("", pset, pname); }

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

inline

Declares the presence of an engine with a default instance name.

Parameters

pset	parameter set where to find a possible fixed seed request
pnames	name of the parameters for the fixed seed request

Returns

the seed assigned to the engine (may be invalid)

See also

declareEngine(std::string, fhicl::ParameterSet const&, std::string)

This method provides the same function as declareEngine(std::string, fhicl::ParameterSet const&, std::string), but it can pick the seed from the first parameter among the ones in pset whose name is in pnames. Also, it gives the engine a empty instance name.

Definition at line 768 of file NuRandomService.h.

      { return declareEngine("", pset, pnames); }

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

Defines a seeder for a previously declared engine.

Parameters

seeder	seeder associated to the engine
instance	name of engine instance (default: empty)

Returns

the seed assigned to the engine (may be invalid)

See also

declareEngine()

The seeder is the same object as in registerEngine(). This function can be used to finalise the declaration of an engine. If the engine was just declared with declareEngine() (as opposed to registered with registerEngine() or created with createEngine()), "defining" the engine will hook it to NuRandomService, that will take care of setting seeds automatically when needed. This step is not mandatory, but no automatic seeding will happen if it is omitted.

Definition at line 225 of file NuRandomService_service.cc.

References defineEngineID(), and qualify_engine_label().

Referenced by declareEngine().

  {
    return defineEngineID(qualify_engine_label(instance), seeder);
  } // NuRandomService::defineEngine(string, Seeder_t)

seed_t rndm::NuRandomService::defineEngine ( CLHEP::HepRandomEngine &  engine, std::string  instance = {}  )

inline

Defines a seeder for a previously declared engine.

Parameters

instance	name of engine instance
engine	CLHEP engine to be associated to the instance

Returns

the seed assigned to the engine (may be invalid)

See also

declareEngine()

This method operates on the default engine instance and performs the same operations as defineEngine(std::string, Seeder_t). A seeder is internally created for the CLHEP random engine.

Definition at line 807 of file NuRandomService.h.

                                                          {})
      { return defineEngine(CLHEPengineSeeder(engine), instance); }

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

private

Set the seeder of an existing engine.

Definition at line 242 of file NuRandomService_service.cc.

References ensureValidState(), hasEngine(), rndm::SeedMaster< SEED >::hasSeeder(), art::errors::LogicError, rndm::SeedMaster< SEED >::registerSeeder(), seed, seedEngine(), and seeds.

Referenced by defineEngine(), and registerEngineID().

  {
    if (!hasEngine(id)) {
      throw art::Exception(art::errors::LogicError)
        << "Attempted to define engine '" << id.artName()
        << "', that was not declared\n";
    }
    
    if (seeds.hasSeeder(id)) {
      throw art::Exception(art::errors::LogicError)
        << "Attempted to redefine engine '" << id.artName()
        << "', that has already been defined\n";
    }
    
    ensureValidState();
    
    seeds.registerSeeder(id, seeder);
    seed_t const seed = seedEngine(id);
    return seed;
  } // NuRandomService::defineEngineID()

void rndm::NuRandomService::ensureValidState ( bool  bGlobal = false ) const

private

Definition at line 265 of file NuRandomService_service.cc.

References rndm::NuRandomServiceHelper::ArtState::inModuleConstructor, rndm::NuRandomServiceHelper::ArtState::inServiceConstructor, art::errors::LogicError, rndm::NuRandomServiceHelper::ArtState::state(), and state.

Referenced by defineEngineID(), and registerEngineAndSeeder().

                                                             {
    if (bGlobal) {
      // registering engines may only happen in a service c'tor
      // In all other cases, throw.
      if ( (state.state() != NuRandomServiceHelper::ArtState::inServiceConstructor))
      {
        throw art::Exception(art::errors::LogicError)
          << "NuRandomService: not in a service constructor."
          << " May not register \"global\" engines.\n";
      }
    }
    else { // context-aware engine
      // registering engines may only happen in a c'tor
      // (disabling the ability to do that or from a beginRun method)
      // In all other cases, throw.
      if ( (state.state() != NuRandomServiceHelper::ArtState::inModuleConstructor)
      //  && (state.state() != NuRandomServiceHelper::ArtState::inModuleBeginRun)
        )
      {
        throw art::Exception(art::errors::LogicError)
          << "NuRandomService: not in a module constructor."
          << " May not register engines.\n";
      }
    } // if
  } // NuRandomService::ensureValidState()

std::pair< NuRandomService::seed_t, bool > rndm::NuRandomService::findSeed ( EngineId const &  id, fhicl::ParameterSet const &  pset, std::initializer_list< std::string >  pnames  )

private

Helper to retrieve a seed including configuration

Returns

the seed, and whether it is fixed (that is, from configuration)

Definition at line 113 of file NuRandomService_service.cc.

References InvalidSeed, querySeed(), readSeedParameter(), and seed.

Referenced by createEngine(), and registerEngine().

    {
    seed_t seed = InvalidSeed;
    // try and read the seed from configuration; if succeed, it's "frozen"
    bool const bFrozen = readSeedParameter(seed, pset, pnames);
    
    // if we got a valid seed, use it as frozen
    if (bFrozen && (seed != InvalidSeed))
      return { seed, true };  
    
    // seed was not good enough; get the seed from the master
    return { querySeed(id), false };
    
  } // NuRandomService::findSeed()

void rndm::NuRandomService::freezeSeed ( EngineId const &  id, seed_t  frozen_seed  )

private

Forces NuRandomService not to change the seed of the specified engine.

Definition at line 357 of file NuRandomService_service.cc.

References rndm::SeedMaster< SEED >::freezeSeed(), prepareEngine(), and seeds.

Referenced by createEngine(), and registerEngine().

    { seeds.freezeSeed(id, frozen_seed); }

seed_t rndm::NuRandomService::getCurrentSeed ( std::string  instanceName ) const

inline

Returns the last computed seed for specified engine of current module.

Definition at line 444 of file NuRandomService.h.

      { return seeds.getCurrentSeed(qualify_engine_label(instanceName)); }

seed_t rndm::NuRandomService::getCurrentSeed ( ) const

inline

Returns the last computed seed for the default engine of current module.

Definition at line 448 of file NuRandomService.h.

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

seed_t rndm::NuRandomService::getEventSeed ( EngineId const &  )

private

seed_t rndm::NuRandomService::getGlobalCurrentSeed ( std::string  instanceName ) const

inline

Returns the last computed seed for the specified global engine.

Definition at line 452 of file NuRandomService.h.

References art::module.

      { return seeds.getCurrentSeed(qualify_global_engine(instanceName)); }

NuRandomService::seed_t rndm::NuRandomService::getGlobalSeed

(

std::string

instanceName

)

Returns a seed for the global engine with specified instance name.

Parameters

instanceName

name of the engine instance

Returns

a seed for the global engine with specified instance name

See also

getSeed()

A "global" engine is not bound to a specific execution context. The only context NuRandomService is aware of is the module, so this translates into engines that are not bound to any module. To instruct NuRandomService to ignore the current context (that may be a running module, or no running module at all), getGlobalSeed() is used instead of getSeed(), that will consider the context and in fact consider the absence of context an error.

The engine needs to have been registered before, in any of the supported ways. If it has not, this call will declare it with declareEngine() and no further registration will be allowed.

While this method can be called at any time, the registration of an engine can happen only at construction time, and it will make the call to this method fail if it is called at any other time.

Definition at line 82 of file NuRandomService_service.cc.

References getSeed(), rndm::SeedMasterHelper::EngineId::global, and LOG_DEBUG.

                                                                             {
    EngineId ID(instanceName, EngineId::global);
    LOG_DEBUG("NuRandomService")
      << "NuRandomService::getGlobalSeed(\"" << instanceName << "\")";
    return getSeed(ID);
  } // NuRandomService::getGlobalSeed()

NuRandomService::seed_t rndm::NuRandomService::getSeed

(

std::string

instanceName

)

Returns a seed for the engine with specified instance name.

Parameters

instanceName

name of the engine instance

Returns

a seed for the engine with specified instance name

See also

getGlobalSeed()

The seed for an engine in the context of the current module is returned. If you need the seed for an engine outside that context, use getGlobalSeed() instead.

The engine needs to have been registered before, in any of the supported ways. If it has not, this call will declare it with declareEngine() and no further registration will be allowed.

While this method can be called at any time, the registration of an engine can happen only at construction time, and it will make the call to this method fail if it is called at any other time.

Definition at line 76 of file NuRandomService_service.cc.

References getSeed(), and qualify_engine_label().

                                                                       {
    return getSeed(qualify_engine_label(instanceName));
  } // NuRandomService::getSeed(string)

NuRandomService::seed_t rndm::NuRandomService::getSeed

(

)

Returns a seed for the engine with default instance name.

Returns

a seed for the engine with default instance name

This method is equivalent to getSeed(std::string) with an empty instance name.

Definition at line 70 of file NuRandomService_service.cc.

References qualify_engine_label().

Referenced by getGlobalSeed(), and getSeed().

                                                 {
    return getSeed(qualify_engine_label());
  } // NuRandomService::getSeed()

NuRandomService::seed_t rndm::NuRandomService::getSeed ( EngineId const &  id )

private

Definition at line 91 of file NuRandomService_service.cc.

References hasEngine(), querySeed(), and registerEngineID().

                                                                   {
    
    // We require an engine to have been registered before we yield seeds;
    // this should minimise unexpected conflicts.
    if (hasEngine(id)) return querySeed(id); // ask the seed to seed master
    
    // if it hasn't been declared, we declare it now
    // (this is for backward compatibility with the previous behaviour).
    // registerEngineID() will eventually call this function again to get the
    // seed... so we return it directly.
    // Also note that this effectively "freezes" the engine since no seeder
    // is specified.
    return registerEngineID(id);
        
  } // NuRandomService::getSeed(EngineId)

bool rndm::NuRandomService::hasEngine ( EngineId const &  id ) const

inlineprivate

Returns whether the specified engine is already registered.

Definition at line 886 of file NuRandomService.h.

References rndm::SeedMaster< SEED >::hasEngine().

Referenced by defineEngineID(), getSeed(), and registerEngineAndSeeder().

{ return seeds.hasEngine(id); }

static constexpr bool rndm::NuRandomService::isSeedValid ( seed_t  seed )

inlinestatic

Returns whether the specified seed is valid.

Definition at line 382 of file NuRandomService.h.

      { return seed != InvalidSeed; }

NuRandomService const& rndm::NuRandomService::operator= ( NuRandomService const &  )

delete

NuRandomService const& rndm::NuRandomService::operator= ( NuRandomService &&  )

delete

void rndm::NuRandomService::postEndJob ( )

private

Definition at line 442 of file NuRandomService_service.cc.

References bPrintEndOfJobSummary, DEFINE_ART_SERVICE, print(), and verbosity.

                                   {
    if ((verbosity > 0) || bPrintEndOfJobSummary)
      print(); // framework logger decides whether and where it shows up
  } // NuRandomService::postEndJob()

void rndm::NuRandomService::postModule ( art::ModuleDescription const &  )

private

Definition at line 423 of file NuRandomService_service.cc.

References rndm::NuRandomServiceHelper::ArtState::reset_module(), rndm::NuRandomServiceHelper::ArtState::reset_state(), and state.

                                                              {
    state.reset_module();
    state.reset_state();
  } // NuRandomService::postModule()

void rndm::NuRandomService::postModuleBeginRun ( art::ModuleDescription const &  )

private

Definition at line 398 of file NuRandomService_service.cc.

References rndm::NuRandomServiceHelper::ArtState::reset_state(), and state.

                                                                      {
    state.reset_state();
  } // NuRandomService::postModuleBeginRun()

void rndm::NuRandomService::postModuleConstruction ( art::ModuleDescription const &  )

private

Definition at line 389 of file NuRandomService_service.cc.

References rndm::NuRandomServiceHelper::ArtState::reset_state(), and state.

                                                                          {
    state.reset_state();
  } // NuRandomService::postModuleConstruction()

void rndm::NuRandomService::postModuleEndJob ( art::ModuleDescription const &  )

private

Definition at line 438 of file NuRandomService_service.cc.

References rndm::NuRandomServiceHelper::ArtState::reset_state(), and state.

                                                                    {
    state.reset_state();
  } // NuRandomService::preModuleBeginRun()

void rndm::NuRandomService::postProcessEvent ( art::Event const &  )

private

Definition at line 428 of file NuRandomService_service.cc.

References rndm::NuRandomServiceHelper::ArtState::reset_event(), rndm::NuRandomServiceHelper::ArtState::reset_state(), and state.

                                                        {
    state.reset_event();
    state.reset_state();
  } // NuRandomService::postProcessEvent()

void rndm::NuRandomService::preModule ( art::ModuleDescription const &  md )

private

Definition at line 412 of file NuRandomService_service.cc.

References rndm::NuRandomServiceHelper::ArtState::inModuleEvent, LOG_DEBUG, art::ModuleDescription::moduleLabel(), reseedModule(), rndm::NuRandomServiceHelper::ArtState::set_module(), state, and rndm::NuRandomServiceHelper::ArtState::transit_to().

                                                                {
    state.transit_to(NuRandomServiceHelper::ArtState::inModuleEvent);
    state.set_module(md);
    
    // Reseed all the engine of this module... maybe
    // (that is, if the current policy alows it).
    LOG_DEBUG("NuRandomService") << "preModule(): will reseed engines for module '"
      << md.moduleLabel() << "'";
    reseedModule(md.moduleLabel());
  } // NuRandomService::preModule()

void rndm::NuRandomService::preModuleBeginRun ( art::ModuleDescription const &  md )

private

Definition at line 393 of file NuRandomService_service.cc.

References rndm::NuRandomServiceHelper::ArtState::inModuleBeginRun, rndm::NuRandomServiceHelper::ArtState::set_module(), state, and rndm::NuRandomServiceHelper::ArtState::transit_to().

                                                                        {
    state.transit_to(NuRandomServiceHelper::ArtState::inModuleBeginRun);
    state.set_module(md);
  } // NuRandomService::preModuleBeginRun()

void rndm::NuRandomService::preModuleConstruction ( art::ModuleDescription const &  md )

private

Definition at line 384 of file NuRandomService_service.cc.

References rndm::NuRandomServiceHelper::ArtState::inModuleConstructor, rndm::NuRandomServiceHelper::ArtState::set_module(), state, and rndm::NuRandomServiceHelper::ArtState::transit_to().

                                                                             {
    state.transit_to(NuRandomServiceHelper::ArtState::inModuleConstructor);
    state.set_module(md);
  } // NuRandomService::preModuleConstruction()

void rndm::NuRandomService::preModuleEndJob ( art::ModuleDescription const &  md )

private

Definition at line 433 of file NuRandomService_service.cc.

References rndm::NuRandomServiceHelper::ArtState::inEndJob, rndm::NuRandomServiceHelper::ArtState::set_module(), state, and rndm::NuRandomServiceHelper::ArtState::transit_to().

                                                                      {
    state.transit_to(NuRandomServiceHelper::ArtState::inEndJob);
    state.set_module(md);
  } // NuRandomService::preModuleBeginRun()

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

private

Registers the engine ID into SeedMaster.

Definition at line 363 of file NuRandomService_service.cc.

References querySeed(), and registerEngineAndSeeder().

Referenced by createEngine(), freezeSeed(), and registerEngineID().

  {
    registerEngineAndSeeder(id, seeder);
    return querySeed(id);
  } // NuRandomService::prepareEngine()

void rndm::NuRandomService::preProcessEvent ( art::Event const &  evt )

private

Definition at line 402 of file NuRandomService_service.cc.

References rndm::NuRandomServiceHelper::ArtState::inEvent, LOG_DEBUG, rndm::SeedMaster< SEED >::onNewEvent(), reseedGlobal(), seeds, rndm::NuRandomServiceHelper::ArtState::set_event(), state, and rndm::NuRandomServiceHelper::ArtState::transit_to().

                                                           {
    state.transit_to(NuRandomServiceHelper::ArtState::inEvent);
    state.set_event(evt);
    seeds.onNewEvent(); // inform the seed master that a new event has come
    
    LOG_DEBUG("NuRandomService") << "preProcessEvent(): will reseed global engines";
    reseedGlobal(); // why don't we do them all?!?
    
  } // NuRandomService::preProcessEvent()

template<class Stream >

void rndm::NuRandomService::print ( Stream &&  out ) const

inline

Prints known (EngineId,seed) pairs.

Definition at line 815 of file NuRandomService.h.

      { seeds.print(std::forward<Stream>(out)); }

void rndm::NuRandomService::print ( ) const

inline

Prints to the framework Info logger.

Definition at line 819 of file NuRandomService.h.

References print(), and seed.

Referenced by postEndJob(), and print().

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

NuRandomService::EngineId rndm::NuRandomService::qualify_engine_label ( std::string  moduleLabel, std::string  instanceName  ) const

private

Returns a fully qualified EngineId.

Definition at line 62 of file NuRandomService_service.cc.

Referenced by createEngine(), defineEngine(), getSeed(), qualify_engine_label(), and registerEngine().

    { return { moduleLabel, instanceName }; }

NuRandomService::EngineId rndm::NuRandomService::qualify_engine_label ( std::string  instanceName = "" ) const

private

Returns a fully qualified EngineId.

Definition at line 66 of file NuRandomService_service.cc.

References rndm::NuRandomServiceHelper::ArtState::moduleLabel(), qualify_engine_label(), and state.

    { return qualify_engine_label( state.moduleLabel(), instanceName); }

EngineId rndm::NuRandomService::qualify_global_engine ( std::string  instanceName = "" ) const

inlineprivate

Returns a fully qualified EngineId.

Definition at line 921 of file NuRandomService.h.

      { return EngineId(instanceName, EngineId::global); }

NuRandomService::seed_t rndm::NuRandomService::querySeed ( EngineId const &  id )

private

Query a seed from the seed master.

Definition at line 108 of file NuRandomService_service.cc.

References rndm::SeedMaster< SEED >::getSeed(), and seeds.

Referenced by findSeed(), getSeed(), and prepareEngine().

                                                                     {
    return seeds.getSeed(id); // ask the seed to seed master
  } // NuRandomService::querySeed()

void rndm::NuRandomService::RandomNumberGeneratorSeeder ( EngineId const &  id, seed_t  seed  )

static

Seeder_t function setting the seed of an engine in RandomNumberGenerator.

Definition at line 330 of file NuRandomService_service.cc.

References art::RandomNumberGenerator::getEngine(), and registerEngineAndSeeder().

Referenced by createEngine(), and reseedGlobal().

  {
    // no check is performed to verify that the current module is the one
    // specified in id.moduleLabel -- but that is required!
    art::ServiceHandle<art::RandomNumberGenerator> rng;
    CLHEP::HepRandomEngine& engine = rng->getEngine(id.instanceName);
    engine.setSeed(seed, 0); // the 0 is dummy... or so one hopes
  } // NuRandomService::RandomNumberGeneratorSeeder()

static bool rndm::NuRandomService::readSeedParameter ( seed_t &  seed, fhicl::ParameterSet const &  pset, std::string  pname  )

inlinestaticprivate

Reads the seed from the first of the specified parameters available

Returns

whether any parameter was found

Definition at line 929 of file NuRandomService.h.

Referenced by findSeed().

      { return readSeedParameter(seed, pset, { pname }); }

bool rndm::NuRandomService::readSeedParameter ( seed_t &  seed, fhicl::ParameterSet const &  pset, std::initializer_list< std::string >  pnames  )

staticprivate

Reads the seed from the first of the specified parameters available

Returns

whether any parameter was found

Definition at line 371 of file NuRandomService_service.cc.

References fhicl::ParameterSet::get_if_present(), and InvalidSeed.

    {
    for (std::string const& key: pnames)
      if (pset.get_if_present(key, seed)) return true;
    seed = InvalidSeed;
    return false;
  } // NuRandomService::readSeedParameter()

NuRandomService::seed_t rndm::NuRandomService::registerEngine	(	SeedMaster_t::Seeder_t	seeder,
		std::string	instance = ""
	)

Registers an existing engine with NuRandomService.

Parameters

seeder	function used to set the seed of the existing engine
instance	name of the engine

Returns

the seed assigned to the engine (may be invalid)

See also

createEngine()

This function works similarly to createEngine(), but it uses an existing engine instead of creating a new one by RandomNumberGenerator service. The seeder function must be provided for the service to be of any use: registerEngine() will set the seed immediately, and the seeder function will be used to set the seed for policies that do that on each event. The instance name must also be unique, since for NuRandomService purposes the registered engine is no different from any other, created by RandomNumberGenerator or not.

Three standard functions are provided as seeders, for use with RandomNumberGenerator engines (RandomNumberGeneratorSeeder()), with a CLHEP::HepRandomEngine (CLHEPengineSeeder class) and with ROOT's TRandom (TRandomSeeder class). Note that CLHEP and ROOT classes are not compiled in NuRandomService by default, and the recommendation is to take their implementation as an example and create your own after them). Any seeder function with the prototype of NuRandomService::Seeder_t:

void Seeder(EngineId const&, seed_t);

or a functor with

void operator() (EngineId const&, seed_t);

can be used as seeder.

Definition at line 191 of file NuRandomService_service.cc.

References qualify_engine_label(), and registerEngineID().

Referenced by evgen::ActiveVolumeVertexSampler::ActiveVolumeVertexSampler(), createEngine(), declareEngine(), and evgen::MARLEYHelper::MARLEYHelper().

  {
    return registerEngineID(qualify_engine_label(instance), seeder);
  } // NuRandomService::registerEngine(Seeder_t, string)

seed_t rndm::NuRandomService::registerEngine ( SeedMaster_t::Seeder_t  seeder, std::string  instance, fhicl::ParameterSet const &  pset, std::string  pname  )

inline

Registers an existing engine with NuRandomService.

Parameters

seeder	function used to set the seed of the existing engine
instance	name of the engine
pset	parameter set to read parameters from
pname	name or names of the seed parameters

Returns

the seed assigned to the engine (may be invalid)

See also

createEngine()

These functions work similarly to registerEngine(), but the preferred way to obtain the seed is from configuration. First, the seed is retrieved from the specified configuration, looking for the first of the parameters in pname that is avaialble. If no parameter is found, the seed is obtained from NuRandomService.

Definition at line 630 of file NuRandomService.h.

      { return registerEngine(seeder, instance, pset, { pname }); }

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

Registers an existing engine with NuRandomService.

Parameters

seeder	function used to set the seed of the existing engine
instance	name of the engine

Returns

the seed assigned to the engine (may be invalid)

See also

createEngine()

This function works similarly to createEngine(), but it uses an existing engine instead of creating a new one by RandomNumberGenerator service. The seeder function must be provided for the service to be of any use: registerEngine() will set the seed immediately, and the seeder function will be used to set the seed for policies that do that on each event. The instance name must also be unique, since for NuRandomService purposes the registered engine is no different from any other, created by RandomNumberGenerator or not.

Three standard functions are provided as seeders, for use with RandomNumberGenerator engines (RandomNumberGeneratorSeeder()), with a CLHEP::HepRandomEngine (CLHEPengineSeeder class) and with ROOT's TRandom (TRandomSeeder class). Note that CLHEP and ROOT classes are not compiled in NuRandomService by default, and the recommendation is to take their implementation as an example and create your own after them). Any seeder function with the prototype of NuRandomService::Seeder_t:

void Seeder(EngineId const&, seed_t);

or a functor with

void operator() (EngineId const&, seed_t);

can be used as seeder.

Definition at line 197 of file NuRandomService_service.cc.

References findSeed(), freezeSeed(), qualify_engine_label(), registerEngineAndSeeder(), seed, and seedEngine().

    {
    EngineId id = qualify_engine_label(instance);
    registerEngineAndSeeder(id, seeder);
    std::pair<seed_t, bool> seedInfo = findSeed(id, pset, pnames);
    seedEngine(id); // seed it before freezing
    if (seedInfo.second) freezeSeed(id, seedInfo.first);
    seed_t const seed = seedInfo.first;
    return seed;
  } // NuRandomService::registerEngine(Seeder_t, string, ParameterSet, init list)

seed_t rndm::NuRandomService::registerEngine ( SeedMaster_t::Seeder_t  seeder, fhicl::ParameterSet const &  pset, std::string  pname  )

inline

Registers an existing engine with NuRandomService.

Parameters

seeder	function used to set the seed of the existing engine
instance	name of the engine

Returns

the seed assigned to the engine (may be invalid)

See also

createEngine()

This function works similarly to createEngine(), but it uses an existing engine instead of creating a new one by RandomNumberGenerator service. The seeder function must be provided for the service to be of any use: registerEngine() will set the seed immediately, and the seeder function will be used to set the seed for policies that do that on each event. The instance name must also be unique, since for NuRandomService purposes the registered engine is no different from any other, created by RandomNumberGenerator or not.

Three standard functions are provided as seeders, for use with RandomNumberGenerator engines (RandomNumberGeneratorSeeder()), with a CLHEP::HepRandomEngine (CLHEPengineSeeder class) and with ROOT's TRandom (TRandomSeeder class). Note that CLHEP and ROOT classes are not compiled in NuRandomService by default, and the recommendation is to take their implementation as an example and create your own after them). Any seeder function with the prototype of NuRandomService::Seeder_t:

void Seeder(EngineId const&, seed_t);

or a functor with

void operator() (EngineId const&, seed_t);

can be used as seeder.

Definition at line 639 of file NuRandomService.h.

      { return registerEngine(seeder, "", pset, pname); }

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

inline

Registers an existing engine with NuRandomService.

Parameters

seeder	function used to set the seed of the existing engine
instance	name of the engine

Returns

the seed assigned to the engine (may be invalid)

See also

createEngine()

This function works similarly to createEngine(), but it uses an existing engine instead of creating a new one by RandomNumberGenerator service. The seeder function must be provided for the service to be of any use: registerEngine() will set the seed immediately, and the seeder function will be used to set the seed for policies that do that on each event. The instance name must also be unique, since for NuRandomService purposes the registered engine is no different from any other, created by RandomNumberGenerator or not.

Three standard functions are provided as seeders, for use with RandomNumberGenerator engines (RandomNumberGeneratorSeeder()), with a CLHEP::HepRandomEngine (CLHEPengineSeeder class) and with ROOT's TRandom (TRandomSeeder class). Note that CLHEP and ROOT classes are not compiled in NuRandomService by default, and the recommendation is to take their implementation as an example and create your own after them). Any seeder function with the prototype of NuRandomService::Seeder_t:

void Seeder(EngineId const&, seed_t);

or a functor with

void operator() (EngineId const&, seed_t);

can be used as seeder.

Definition at line 644 of file NuRandomService.h.

      { return registerEngine(seeder, "", pset, pnames); }

seed_t rndm::NuRandomService::registerEngine ( CLHEP::HepRandomEngine &  engine, std::string  instance = ""  )

inline

Registers an existing CLHEP engine with NuRandomService.

Parameters

engine	a reference to the CLHEP random generator engine
instance	name of the engine
pset	parameter set to read parameters from
pname	name or names of the seed parameters

Returns

the seed assigned to the engine (may be invalid)

The specified engine is not managed. It may be owned by RandomNumberGenerator service.

The engine is expected to be valid as long as this service performs reseeding.

Definition at line 667 of file NuRandomService.h.

      { return registerEngine(CLHEPengineSeeder(engine), instance); }

seed_t rndm::NuRandomService::registerEngine ( CLHEP::HepRandomEngine &  engine, std::string  instance, fhicl::ParameterSet const &  pset, std::initializer_list< std::string >  pnames  )

inline

Definition at line 669 of file NuRandomService.h.

      {
        return registerEngine
          (CLHEPengineSeeder(engine), instance, pset, pnames);
      }

void rndm::NuRandomService::registerEngineAndSeeder ( EngineId const &  id, SeedMaster_t::Seeder_t  seeder  )

private

Registers an engine and its seeder.

Definition at line 342 of file NuRandomService_service.cc.

References ensureValidState(), hasEngine(), art::errors::LogicError, rndm::SeedMaster< SEED >::registerNewSeeder(), and seeds.

Referenced by createEngine(), prepareEngine(), RandomNumberGeneratorSeeder(), and registerEngine().

  {
    // Are we being called from the right place?
    ensureValidState(id.isGlobal());
    
    if (hasEngine(id)) {
      throw art::Exception(art::errors::LogicError)
        << "NuRandomService: an engine with ID '" << id.artName()
        << "' has already been created!\n";
    }
    seeds.registerNewSeeder(id, seeder);
  } // NuRandomService::registerEngineAndSeeder()

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

private

Register an engine and seeds it with the seed from the master.

Definition at line 232 of file NuRandomService_service.cc.

References defineEngineID(), prepareEngine(), and seedEngine().

Referenced by getSeed(), and registerEngine().

    {
    prepareEngine(id, seeder);
    return seedEngine(id);
  } // NuRandomService::registerEngine()

void rndm::NuRandomService::reseedGlobal ( )

private

Reseed all the global engines.

Definition at line 320 of file NuRandomService_service.cc.

References rndm::SeedMaster< SEED >::engineIDsRange(), RandomNumberGeneratorSeeder(), reseedInstance(), and seeds.

Referenced by preProcessEvent().

                                     {
    for (EngineId const& ID: seeds.engineIDsRange()) {
      if (!ID.isGlobal()) continue; // not global? neeext!!
      reseedInstance(ID);
    } // for
  } // NuRandomService::reseedGlobal()

NuRandomService::seed_t rndm::NuRandomService::reseedInstance ( EngineId const &  id )

private

Reseeds the specified engine instance in the current module.

Parameters

instance

the name of the engine instance

Returns

the seed set, or InvalidSeed if no reseeding happened

Definition at line 293 of file NuRandomService_service.cc.

References rndm::NuRandomServiceHelper::ArtState::getEventSeedInputData(), InvalidSeed, rndm::SeedMaster< SEED >::reseedEvent(), seed, seeds, and state.

Referenced by reseedGlobal(), and reseedModule().

                                                                          {
    // get all the information on the current process, event and module from
    // ArtState:
    SeedMaster_t::EventData_t const data(state.getEventSeedInputData());
    seed_t const seed = seeds.reseedEvent(id, data);
    if (seed == InvalidSeed) {
      mf::LogDebug("NuRandomService")
        << "No random seed specific to this event for engine '" << id << "'";
    }
    else {
      mf::LogInfo("NuRandomService") << "Random seed for this event, engine '"
        << id << "': " << seed;
    }
    return seed;
  } // NuRandomService::reseedInstance()

void rndm::NuRandomService::reseedModule ( std::string  currentModule )

private

Reseeds all the engines in the current module.

Definition at line 310 of file NuRandomService_service.cc.

References rndm::SeedMaster< SEED >::engineIDsRange(), reseedInstance(), and seeds.

                                                            {
    for (EngineId const& ID: seeds.engineIDsRange()) {
      if (ID.moduleLabel != currentModule) continue; // not our module? neeext!!
      reseedInstance(ID);
    } // for
  } // NuRandomService::reseedModule(string)

void rndm::NuRandomService::reseedModule ( )

private

Reseeds all the engines in the current module.

Definition at line 317 of file NuRandomService_service.cc.

References rndm::NuRandomServiceHelper::ArtState::moduleLabel(), and state.

Referenced by preModule().

{ reseedModule(state.moduleLabel()); }

seed_t rndm::NuRandomService::seedEngine ( EngineId const &  id )

inlineprivate

Calls the seeder with the specified seed and engine ID.

Definition at line 955 of file NuRandomService.h.

References DECLARE_ART_SERVICE, art::LEGACY, and rndm::SeedMaster< SEED >::reseed().

Referenced by defineEngineID(), registerEngine(), and registerEngineID().

{ return seeds.reseed(id); }

Member Data Documentation

bool rndm::NuRandomService::bPrintEndOfJobSummary = false

private

print a summary at the end of job

Definition at line 873 of file NuRandomService.h.

Referenced by postEndJob().

constexpr seed_t rndm::NuRandomService::InvalidSeed = SeedMaster_t::InvalidSeed

static

An invalid seed.

Definition at line 369 of file NuRandomService.h.

Referenced by findSeed(), readSeedParameter(), and reseedInstance().

SeedMaster_t rndm::NuRandomService::seeds

private

Class managing the seeds.

Definition at line 858 of file NuRandomService.h.

Referenced by defineEngineID(), freezeSeed(), preProcessEvent(), querySeed(), registerEngineAndSeeder(), reseedGlobal(), reseedInstance(), and reseedModule().

NuRandomServiceHelper::ArtState rndm::NuRandomService::state

private

Helper to track state of art.

The state is updated by NuRandomService itself, and therefore knows only about what it is notified about, when it is notified about. For example, service construction phase may start before the service was even constructed, but the state will be updated only on NuRandomService construction.

Definition at line 869 of file NuRandomService.h.

Referenced by ensureValidState(), postModule(), postModuleBeginRun(), postModuleConstruction(), postModuleEndJob(), postProcessEvent(), preModule(), preModuleBeginRun(), preModuleConstruction(), preModuleEndJob(), preProcessEvent(), qualify_engine_label(), reseedInstance(), and reseedModule().

int rndm::NuRandomService::verbosity = 0

private

Control the level of information messages.

Definition at line 872 of file NuRandomService.h.

Referenced by postEndJob().

---

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

• nutools/RandomUtils/NuRandomService.h
• nutools/RandomUtils/NuRandomService_service.cc