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::detail::EngineCreator::seed_t
using	engine_t = CLHEP::HepRandomEngine
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 const &moduleLabel, std::string const &instanceName)
	Returns a seed for the engine with specified instance name. More...
seed_t	getSeed (std::string instanceName="")
	Returns a seed for the engine with specified 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...
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. 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 auto& engine = createEngine(seed, "HepJamesRandom", instanceName); // finally, complete the registration; seed will be set again Seeds.defineEngine(engine);
std::reference_wrapper< NuRandomService::engine_t >	registerAndSeedEngine (engine_t &engine, std::string type="", std::string instance="", std::optional< seed_t > const seed=std::nullopt)
	Creates an engine with art::RandomNumberGenerator service. More...
std::reference_wrapper< engine_t >	registerAndSeedEngine (engine_t &engine, std::string type, std::string instance, SeedAtom const &seedParam)
	Creates an engine with art::RandomNumberGenerator service. More...
std::reference_wrapper< engine_t >	registerAndSeedEngine (engine_t &engine, std::string type, SeedAtom const &seedParam)
	Creates an engine with art::RandomNumberGenerator service. More...
std::reference_wrapper< engine_t >	registerAndSeedEngine (engine_t &engine, SeedAtom const &seedParam)
	Creates an engine with art::RandomNumberGenerator service. More...
std::reference_wrapper< engine_t >	registerAndSeedEngine (engine_t &engine, std::string type, std::string instance, fhicl::ParameterSet const &pset, std::string pname)
	Creates an engine with art::RandomNumberGenerator service. More...
std::reference_wrapper< engine_t >	registerAndSeedEngine (engine_t &engine, std::string type, std::string instance, fhicl::ParameterSet const &pset, std::initializer_list< std::string > pnames)
	Creates an engine with art::RandomNumberGenerator service. More...
std::reference_wrapper< engine_t >	registerAndSeedEngine (engine_t &engine, std::string type, fhicl::ParameterSet const &pset, std::string pname)
	Creates an engine with art::RandomNumberGenerator service. More...
std::reference_wrapper< engine_t >	registerAndSeedEngine (engine_t &engine, std::string type, fhicl::ParameterSet const &pset, std::initializer_list< std::string > pnames)
	Creates an engine with art::RandomNumberGenerator service. More...
std::reference_wrapper< engine_t >	registerAndSeedEngine (engine_t &engine, fhicl::ParameterSet const &pset, std::string pname)
	Creates an engine with art::RandomNumberGenerator service. More...
std::reference_wrapper< engine_t >	registerAndSeedEngine (engine_t &engine, fhicl::ParameterSet const &pset, std::initializer_list< std::string > pnames)
	Creates an engine with art::RandomNumberGenerator service. More...
Register an existing engine
The life time of the engine is under user's control, while the seeding managed by this service.
seed_t	registerEngine (SeedMaster_t::Seeder_t seeder, std::string const instance="", std::optional< seed_t > const seed=std::nullopt)
	Registers an existing engine with rndm::NuRandomService. More...
seed_t	registerEngine (SeedMaster_t::Seeder_t seeder, std::string const instance, SeedAtom const &seedParam)
	Registers an existing engine with art::NuRandomService. More...
seed_t	registerEngine (SeedMaster_t::Seeder_t seeder, SeedAtom const &seedParam)
	Registers an existing engine with art::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 art::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 art::NuRandomService. More...
seed_t	registerEngine (SeedMaster_t::Seeder_t seeder, fhicl::ParameterSet const &pset, std::string pname)
	Registers an existing engine with art::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 art::NuRandomService. More...
seed_t	registerEngine (CLHEP::HepRandomEngine &engine, std::string instance="")
	Registers an existing CLHEP engine with art::NuRandomService. More...
seed_t	registerEngine (CLHEP::HepRandomEngine &engine, std::string instance, SeedAtom const &seedParam)
	Registers an existing CLHEP engine with art::NuRandomService. More...
seed_t	registerEngine (CLHEP::HepRandomEngine &engine, std::string instance, fhicl::ParameterSet const &pset, std::initializer_list< std::string > pnames)
	Registers an existing CLHEP engine with art::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 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 >	extractSeed (EngineId const &id, std::optional< seed_t > seed)
void	freezeSeed (EngineId const &id, seed_t frozen_seed)
	Forces NuRandomService not to change the seed of the specified engine. More...
void	registerEngineIdAndSeeder (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::ModuleContext const &mc)
void	postModuleBeginRun (art::ModuleContext const &)
void	preProcessEvent (art::Event const &evt, art::ScheduleContext)
void	preModule (art::ModuleContext const &mc)
void	postModule (art::ModuleContext const &)
void	postProcessEvent (art::Event const &, art::ScheduleContext)
void	preModuleEndJob (art::ModuleDescription const &md)
void	postModuleEndJob (art::ModuleDescription const &)
void	postEndJob ()
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 std::optional< seed_t >	readSeedParameter (fhicl::ParameterSet const &pset, std::string pname)
static std::optional< seed_t >	readSeedParameter (fhicl::ParameterSet const &pset, std::initializer_list< std::string > pnames)
static std::optional< seed_t >	readSeedParameter (SeedAtom const &param)

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

rndm::SeedMaster

rndm::NuRandomService centrally manages seeds for random generator engines.

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

The documentation is mantained in the rndm::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 rndm::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 for 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 registering an existing engine and its seeding function (see registerAndSeedEngine() and registerEngine() methods)
• by just declaring that an engine exists (see declareEngine() and getSeed() methods) The first methods set the seed of the engine they register (see below). In the second 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.

Here is 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
auto& engine = createEngine(seed, "HepJamesRandom", instanceName);

// finally, complete the registration; seed will be set again
Seeds.defineEngine(engine);

This is equivalent to the call

auto& Seeds = *(art::ServiceHandle<rndm::NuRandomService>());
Seeds.registerAndSeedEngine(createEngine(0, "HepJamesRandom", "instanceName"),
                            "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

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

• registerAndSeedEngine() (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. A call not declaring anything is instead:

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

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 rndm::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 rndm::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 precedence over the one automatically assigned by rndm::SeedMaster policy. This extended signature includes:

• a FHiCL parameter set
• a configuration parameter name, or a list of them
• a optional atom of type rndm::seed_t, also available with the name rndm::SeedAtom 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] Likewise, if the optional parameter is specified, its value will be honored, and the service will be queried for an automatic seed otherwise. 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: {cpp} // 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. An example of the use of the validated configuration, for an analyzer containing in its definition: {cpp} CLHEP::HepRandomEngine& fEngine; public: struct Config { rndm::SeedAtom Seed{ fhicl::Name("Seed"), fhicl::Comment("optional seed for random engine") }; }; // struct Config using Parameters = art::EDAnalyzer::Table<Config>; is to have an entry in the initializer list of the constructor such as: {cpp} my_ns::MyAnalyzer::MyAnalyzer(Parameters const& config) : art::EDAnalyzer(config) , fEngine(art::ServiceHandle<rndm::NuRandomService>()->registerAndSeedEngine (*this, config().Seed)) // ... 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. 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 400 of file NuRandomService.h.

Member Typedef Documentation

using rndm::NuRandomService::engine_t = CLHEP::HepRandomEngine

Definition at line 403 of file NuRandomService.h.

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

type of random engine ID

Definition at line 407 of file NuRandomService.h.

using rndm::NuRandomService::seed_t = art::detail::EngineCreator::seed_t

Definition at line 402 of file NuRandomService.h.

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

type of object providing seeds

Definition at line 405 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::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 registerAndSeedEngine() 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 159 of file NuRandomService.cc.

                                                                         {
    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 registerAndSeedEngine() 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 1043 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 164 of file NuRandomService.cc.

    {
    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 1075 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 1091 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 registerAndSeedEngine()), "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 173 of file NuRandomService.cc.

  {
    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 1130 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 190 of file NuRandomService.cc.

References art::errors::LogicError, seed, and tca::seeds.

  {
    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 213 of file NuRandomService.cc.

References art::errors::LogicError.

                                                             {
    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()

auto rndm::NuRandomService::extractSeed ( EngineId const &  id, std::optional< seed_t >  seed  )

private

Helper to retrieve a seed including configuration.

Returns

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

Definition at line 117 of file NuRandomService.cc.

  {
    // if we got a valid seed, use it as frozen
    if (seed && (seed.value() != InvalidSeed))
      return { seed.value(), true };

    // seed was not good enough; get the seed from the master
    return { querySeed(id), false };
  } // NuRandomService::extractSeed()

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 293 of file NuRandomService.cc.

References tca::seeds.

    { 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 495 of file NuRandomService.h.

References tca::seeds.

      { 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 499 of file NuRandomService.h.

References tca::seeds.

      { 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 503 of file NuRandomService.h.

References instance, seed, and tca::seeds.

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

auto 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 85 of file NuRandomService.cc.

References MF_LOG_DEBUG.

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

auto rndm::NuRandomService::getSeed	(	std::string const &	moduleLabel,
		std::string const &	instanceName
	)

Returns a seed for the engine with specified instance name.

Parameters

moduleLabel	label of the module the engine is assigned to
instanceName	name of the engine instance within that module

Returns

a seed for the engine with specified instance name

See also

getGlobalSeed()

The seed for an engine in the context of the specified module label 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: if it is called at any other time and if the call triggers such registration as described above, it will make the call to this method fail.

Note

This method is thread-safe.

Definition at line 80 of file NuRandomService.cc.

    { return getSeed(qualify_engine_label(moduleLabel, instanceName)); }

auto 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. See getSeed(std::string const&, std::string const&) for details.

Note

This method is not thread-safe.

Definition at line 72 of file NuRandomService.cc.

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

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

private

Definition at line 94 of file NuRandomService.cc.

                                                                   {

    // 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 1205 of file NuRandomService.h.

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

{ return seeds.hasEngine(id); }

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

inlinestatic

Returns whether the specified seed is valid.

Definition at line 423 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 387 of file NuRandomService.cc.

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

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

private

Definition at line 368 of file NuRandomService.cc.

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

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

private

Definition at line 343 of file NuRandomService.cc.

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

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

private

Definition at line 334 of file NuRandomService.cc.

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

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

private

Definition at line 383 of file NuRandomService.cc.

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

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

private

Definition at line 373 of file NuRandomService.cc.

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

void rndm::NuRandomService::preModule ( art::ModuleContext const &  mc )

private

Definition at line 357 of file NuRandomService.cc.

References MF_LOG_DEBUG, art::ModuleContext::moduleDescription(), and art::ModuleContext::moduleLabel().

                                                            {
    state.transit_to(NuRandomServiceHelper::ArtState::inModuleEvent);
    state.set_module(mc.moduleDescription());

    // Reseed all the engine of this module... maybe
    // (that is, if the current policy alows it).
    MF_LOG_DEBUG("NuRandomService") << "preModule(): will reseed engines for module '"
      << mc.moduleLabel() << "'";
    reseedModule(mc.moduleLabel());
  } // NuRandomService::preModule()

void rndm::NuRandomService::preModuleBeginRun ( art::ModuleContext const &  mc )

private

Definition at line 338 of file NuRandomService.cc.

References art::ModuleContext::moduleDescription().

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

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

private

Definition at line 329 of file NuRandomService.cc.

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

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

private

Definition at line 378 of file NuRandomService.cc.

                                                                      {
    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 299 of file NuRandomService.cc.

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

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

private

Definition at line 347 of file NuRandomService.cc.

References MF_LOG_DEBUG, and tca::seeds.

                                                                               {
    state.transit_to(NuRandomServiceHelper::ArtState::inEvent);
    state.set_event(evt);
    seeds.onNewEvent(); // inform the seed master that a new event has come

    MF_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 1138 of file NuRandomService.h.

References tca::seeds.

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

void rndm::NuRandomService::print ( ) const

inline

Prints to the framework Info logger.

Definition at line 1142 of file NuRandomService.h.

References print(), and seed.

Referenced by 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 63 of file NuRandomService.cc.

    { return { moduleLabel, instanceName }; }

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

private

Returns a fully qualified EngineId.

Definition at line 67 of file NuRandomService.cc.

    { 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 1240 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 111 of file NuRandomService.cc.

References tca::seeds.

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

static std::optional<seed_t> rndm::NuRandomService::readSeedParameter ( fhicl::ParameterSet const &  pset, std::string  pname  )

inlinestaticprivate

Reads the seed from the first of the specified parameters available.

Returns

the value of the seed if found, no value otherwise

Definition at line 1248 of file NuRandomService.h.

References seed.

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

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

staticprivate

Reads the seed from the first of the specified parameters available.

Returns

the value of the seed if found, no value otherwise

Definition at line 307 of file NuRandomService.cc.

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

    {
    seed_t seed;
    for (std::string const& key: pnames)
      if (pset.get_if_present(key, seed)) return { seed };
    return std::nullopt;
  } // NuRandomService::readSeedParameter(ParameterSet, strings)

std::optional< seed_t > rndm::NuRandomService::readSeedParameter ( SeedAtom const &  param )

staticprivate

Reads the seed from the first of the specified parameters available.

Returns

the value of the seed if found, no value otherwise

Definition at line 320 of file NuRandomService.cc.

References seed.

  {
    seed_t seed;
    return param(seed)? std::make_optional(seed): std::nullopt;
  } // NuRandomService::readSeedParameter(SeedAtom)

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

inline

Creates an engine with art::RandomNumberGenerator service.

Parameters

engine	the engine to register with the service
type	the type of engine
instance	the name of the engine instance
seed	the seed to use for this engine (optional)

Returns

the seed used

See also

registerEngine()

The engine seed is set. If the seed optional parameter has a value, that value is used as seed. Otherwise, the seed is obtained from rndm::NuRandomService.

If the seed is not specified, it is obtained in a way equivalent to getSeed() (but multi-treading safe).

If also instance is not specified, the engine is created with no instance name (equivalent to an empty instance name).

If also type is not specified, the type of the engine is the default one from art::RandomNumberGenerator.

Note

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

Definition at line 1301 of file NuRandomService.h.

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

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

std::reference_wrapper< NuRandomService::engine_t > rndm::NuRandomService::registerAndSeedEngine ( engine_t &  engine, std::string  type, std::string  instance, SeedAtom const &  seedParam  )

inline

Creates an engine with art::RandomNumberGenerator service.

Parameters

module	module who will own the new engine
type	the type of engine
instance	the name of the engine instance
seedParam	the optional seed configuration parameter

Returns

the seed used

See also

registerEngine()

This method operates like registerAndSeedEngine(engine_t&, std::string, std::string, std::optional<seed_t> const) with the difference that the seed is read from seedParam; if that optional parameter is not present, then the seed is obtained from rndm:::NuRandomService.

Definition at line 1319 of file NuRandomService.h.

  {
    return registerAndSeedEngine(engine, type, instance, readSeedParameter(seedParam));
  } // NuRandomService::registerAndSeedEngine(ParameterSet)

std::reference_wrapper<engine_t> rndm::NuRandomService::registerAndSeedEngine ( engine_t &  engine, std::string  type, SeedAtom const &  seedParam  )

inline

Creates an engine with art::RandomNumberGenerator service.

Parameters

module	module who will own the new engine
type	the type of engine
seedParam	the optional seed configuration parameter

Returns

the seed used

See also

registerEngine()

This method operates like registerAndSeedEngine(engine_t&, std::string, std::string, std::optional<seed_t> const) with the difference that the seed is read from seedParam; if that optional parameter is not present, then the seed is obtained from rndm:::NuRandomService. Also, the engine is always associated with an empty instance name.

Definition at line 601 of file NuRandomService.h.

      { return registerAndSeedEngine(engine, type, "", seedParam); }

std::reference_wrapper<engine_t> rndm::NuRandomService::registerAndSeedEngine ( engine_t &  engine, SeedAtom const &  seedParam  )

inline

Creates an engine with art::RandomNumberGenerator service.

Parameters

module	module who will own the new engine
seedParam	the optional seed configuration parameter

Returns

the seed used

See also

registerEngine()

This method operates like registerAndSeedEngine(engine_t&, std::string, std::string, std::optional<seed_t> const) with the difference that the seed is read from seedParam; if that optional parameter is not present, then the seed is obtained from rndm:::NuRandomService. Also, the engine is always created of the default type and associated with an empty instance name.

Definition at line 620 of file NuRandomService.h.

      { return registerAndSeedEngine(engine, "", "", seedParam); }

std::reference_wrapper<engine_t> rndm::NuRandomService::registerAndSeedEngine ( engine_t &  engine, std::string  type, std::string  instance, fhicl::ParameterSet const &  pset, std::string  pname  )

inline

Creates an engine with art::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 of the seed parameters

Returns

the seed used

See also

registerEngine()

This method operates like registerAndSeedEngine(engine_t&, std::string, std::string, std::optional<seed_t> const) with the difference that 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 rndm::NuRandomService.

Definition at line 640 of file NuRandomService.h.

      { return registerAndSeedEngine(engine, type, instance, pset, { pname }); }

std::reference_wrapper< NuRandomService::engine_t > rndm::NuRandomService::registerAndSeedEngine ( engine_t &  engine, std::string  type, std::string  instance, fhicl::ParameterSet const &  pset, std::initializer_list< std::string >  pnames  )

inline

Creates an engine with art::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
pnames	names of the seed parameters

Returns

the seed used

See also

registerEngine()

This method operates like registerAndSeedEngine(engine_t&, std::string, std::string, fhicl::ParameterSet const&, std::string) with the difference that the seed can be specified by any of the parameters named in pnames: the first match will be used. As usual, if no parameter is found, the seed is obtained from rndm:::NuRandomService.

Definition at line 1329 of file NuRandomService.h.

References DECLARE_ART_SERVICE, and art::LEGACY.

  {
    return
      registerAndSeedEngine(engine, type, instance, readSeedParameter(pset, pnames));
  }

std::reference_wrapper<engine_t> rndm::NuRandomService::registerAndSeedEngine ( engine_t &  engine, std::string  type, fhicl::ParameterSet const &  pset, std::string  pname  )

inline

Creates an engine with art::RandomNumberGenerator service.

Parameters

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

Returns

the seed used

See also

registerEngine()

This method operates like registerAndSeedEngine(engine_t&, std::string, std::string, fhicl::ParameterSet const&, std::string) with the difference that the engine is given no instance name.

Definition at line 682 of file NuRandomService.h.

      { return registerAndSeedEngine(engine, type, "", pset, pname); }

std::reference_wrapper<engine_t> rndm::NuRandomService::registerAndSeedEngine ( engine_t &  engine, std::string  type, fhicl::ParameterSet const &  pset, std::initializer_list< std::string >  pnames  )

inline

Creates an engine with art::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
pnames	names of the seed parameters

Returns

the seed used

See also

registerEngine()

This method operates like registerAndSeedEngine(engine_t&, std::string, std::string, fhicl::ParameterSet const&, std::string) with the difference that the engine is not given any instance name and that seed can be specified by any of the parameters named in pnames: the first match will be used. As usual, if no parameter is found, the seed is obtained from rndm:::NuRandomService.

Definition at line 705 of file NuRandomService.h.

      { return registerAndSeedEngine(engine, type, "", pset, pnames); }

std::reference_wrapper<engine_t> rndm::NuRandomService::registerAndSeedEngine ( engine_t &  engine, fhicl::ParameterSet const &  pset, std::string  pname  )

inline

Creates an engine with art::RandomNumberGenerator service.

Parameters

module	module who will own the new 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 operates like registerAndSeedEngine(engine_t&, std::string, std::string, fhicl::ParameterSet const&, std::string) with the difference that the default engine is used (determined by art::RandomNumberGenerator) and no instance name is given to it.

Definition at line 725 of file NuRandomService.h.

      { return registerAndSeedEngine(engine, pset, { pname }); }

std::reference_wrapper<engine_t> rndm::NuRandomService::registerAndSeedEngine ( engine_t &  engine, fhicl::ParameterSet const &  pset, std::initializer_list< std::string >  pnames  )

inline

Creates an engine with art::RandomNumberGenerator service.

Parameters

module	module who will own the new engine
pset	parameter set to read parameters from
pnames	names of the seed parameters

Returns

the seed used

See also

registerEngine()

This method operates like registerAndSeedEngine(engine_t&, std::string, std::string, fhicl::ParameterSet const&, std::string) with the difference that the engine is created with the default type (determined in art::RandomNumberGenerator), not given any instance name and that seed can be specified by any of the parameters named in pnames: the first match will be used. As usual, if no parameter is found, the seed is obtained from rndm:::NuRandomService.

Definition at line 747 of file NuRandomService.h.

References seed.

      { return registerAndSeedEngine(engine, "", "", pset, pnames); }

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

Registers an existing engine with rndm::NuRandomService.

Parameters

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

Returns

the seed assigned to the engine (may be invalid)

See also

registerAndSeedEngine()

This function works similarly to registerAndSeedEngine(), but it uses an existing engine instead of creating a new one via art::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 art::RandomNumberGenerator or not.

Three standard functions are provided as seeders, for use with art::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.

The engine seed will be set. If the seed optional parameter has a value, that value is used as seed. Otherwise, the seed is obtained from rndm::NuRandomService.

If the seed is not specified, it is obtained in a way equivalent to getSeed() (but multi-treading safe).

If also instance is not specified, the engine is created with no instance name (equivalent to an empty instance name).

Definition at line 128 of file NuRandomService.cc.

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

    {
    EngineId id = qualify_engine_label(instance);
    registerEngineIdAndSeeder(id, seeder);
    auto const [ seedValue, frozen ] = extractSeed(id, seed);
    seedEngine(id); // seed it before freezing
    if (frozen) freezeSeed(id, seedValue);
    return seedValue;
  } // NuRandomService::registerEngine(Seeder_t, string, ParameterSet, init list)

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

Registers an existing engine with art::NuRandomService.

Parameters

seeder	function used to set the seed of the existing engine
instance	name of the engine
seedParam	the optional seed configuration parameter

Returns

the seed assigned to the engine (may be invalid)

See also

registerEngine()

This method works similarly to registerEngine(SeedMaster_t::Seeder_t, std::string const, std::optional<seed_t> const, with the difference that the seed is read from seedParam; if that optional parameter is not present, then the seed is obtained from rndm:::NuRandomService.

Definition at line 150 of file NuRandomService.cc.

  {
    return registerEngine(seeder, instance, readSeedParameter(seedParam));
  } // NuRandomService::registerEngine(Seeder_t, string, ParameterSet, init list)

seed_t rndm::NuRandomService::registerEngine ( SeedMaster_t::Seeder_t  seeder, SeedAtom const &  seedParam  )

inline

Registers an existing engine with art::NuRandomService.

Parameters

seeder	function used to set the seed of the existing engine
seedParam	the optional seed configuration parameter

Returns

the seed assigned to the engine (may be invalid)

See also

registerEngine()

This method works similarly to registerEngine(SeedMaster_t::Seeder_t, std::string const, std::optional<seed_t> const, with the difference that the seed is read from seedParam; if that optional parameter is not present, then the seed is obtained from rndm:::NuRandomService. In addition, the engine is always registered with no instance name.

Definition at line 853 of file NuRandomService.h.

      { return registerEngine(seeder, "", seedParam); }

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 art::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 of the optional seed parameter

Returns

the seed assigned to the engine (may be invalid)

See also

registerAndSeedEngine()

This method works similarly to registerEngine(SeedMaster_t::Seeder_t, std::string const, std::optional<seed_t> const, but the preferred way to obtain the seed is from the configuration parameter named pname in pset. If that parameter is found, the seed is obtained from rndm::NuRandomService.

Definition at line 871 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 art::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
pnames	names of the seed parameters

Returns

the seed assigned to the engine (may be invalid)

See also

registerAndSeedEngine()

This method works similarly to registerEngine(SeedMaster_t::Seeder_t, std::string const, std::optional<seed_t> const, but the preferred way to obtain the seed is from the first available configuration parameter in pset among the ones listed in pnames. If that parameter is found, the seed is obtained from rndm::NuRandomService.

Definition at line 141 of file NuRandomService.cc.

  {
    return registerEngine(seeder, instance, readSeedParameter(pset, pnames));
  } // 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 art::NuRandomService.

Parameters

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

Returns

the seed assigned to the engine (may be invalid)

See also

registerAndSeedEngine()

This method works similarly to registerEngine(SeedMaster_t::Seeder_t, std::string const, std::optional<seed_t> const, but the preferred way to obtain the seed is from the configuration parameter named pname in pset. If that parameter is found, the seed is obtained from rndm::NuRandomService. Also, the engine is assigned no instance name.

Definition at line 913 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 art::NuRandomService.

Parameters

seeder	function used to set the seed of the existing engine
pset	parameter set to read parameters from
pnames	names of the seed parameters

Returns

the seed assigned to the engine (may be invalid)

See also

registerAndSeedEngine()

This method works similarly to registerEngine(SeedMaster_t::Seeder_t, std::string const, std::optional<seed_t> const, but the preferred way to obtain the seed is from the first available configuration parameter in pset among the ones listed in pnames. If that parameter is found, the seed is obtained from rndm::NuRandomService. Also, the engine is assigned no instance name.

Definition at line 934 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 art::NuRandomService.

Parameters

engine	a reference to the CLHEP random generator engine
instance	(default: none) name of the engine

Returns

the seed assigned to the engine (may be invalid)

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

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

Definition at line 954 of file NuRandomService.h.

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

seed_t rndm::NuRandomService::registerEngine ( CLHEP::HepRandomEngine &  engine, std::string  instance, SeedAtom const &  seedParam  )

inline

Registers an existing CLHEP engine with art::NuRandomService.

Parameters

engine	a reference to the CLHEP random generator engine
instance	name of the engine
seedParam	the optional seed configuration parameter

Returns

the seed assigned to the engine (may be invalid)

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

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

Definition at line 970 of file NuRandomService.h.

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

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

inline

Registers an existing CLHEP engine with art::NuRandomService.

Parameters

engine	a reference to the CLHEP random generator engine
instance	name of the engine
pset	parameter set to read parameters from
pnames	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 art::RandomNumberGenerator service.

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

Definition at line 990 of file NuRandomService.h.

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

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 180 of file NuRandomService.cc.

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

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

private

Registers an engine and its seeder.

Definition at line 278 of file NuRandomService.cc.

References art::errors::LogicError, and tca::seeds.

  {
    // 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::registerEngineIdAndSeeder()

void rndm::NuRandomService::reseedGlobal ( )

private

Reseed all the global engines.

Definition at line 268 of file NuRandomService.cc.

References tca::seeds.

                                     {
    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 241 of file NuRandomService.cc.

References seed, and tca::seeds.

                                                                          {
    // 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 258 of file NuRandomService.cc.

References tca::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 265 of file NuRandomService.cc.

{ 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 1274 of file NuRandomService.h.

References tca::evt, and rndm::SeedMaster< SEED >::reseed().

{ return seeds.reseed(id); }

Member Data Documentation

bool rndm::NuRandomService::bPrintEndOfJobSummary = false

private

print a summary at the end of job

Definition at line 1192 of file NuRandomService.h.

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

static

An invalid seed.

Definition at line 410 of file NuRandomService.h.

SeedMaster_t rndm::NuRandomService::seeds

private

Class managing the seeds.

Definition at line 1177 of file NuRandomService.h.

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 1188 of file NuRandomService.h.

int rndm::NuRandomService::verbosity = 0

private

Control the level of information messages.

Definition at line 1191 of file NuRandomService.h.

---

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

• nurandom/RandomUtils/NuRandomService.h
• nurandom/RandomUtils/NuRandomService.cc