Fast Random number Generator using on xorshift1024* [arXiv:1402.6246]. More...

#include <RandomGenerator.h>

Inheritance diagram for RandomGenerator:

Collaboration diagram for RandomGenerator:

Public Types
enum	EGeneratorMode { c_independent , c_runDependent , c_eventDependent }
	Generator mode: determines which information is used to generate the internal state. More...

Public Member Functions
	RandomGenerator (const std::string &name="Belle2 Random Generator")
	Default constructor, does not initialize the generator.

virtual	~RandomGenerator ()
	Destructor to free the seed information.

void	setSeed (const unsigned char *seed, unsigned int n)
	Set the seed information. More...

void	setMode (EGeneratorMode mode)
	Set the generator mode.

EGeneratorMode	getMode () const
	Get the generator mode.

const std::vector< unsigned char > &	getSeed () const
	return the seed object

void	initialize ()
	set the State from event meta information like experiment, run, and event number. More...

void	barrier ()
	increase the barrier index. More...

void	setBarrier (int barrierIndex)
	manually set the barrier index to a fixed value

int	getBarrier () const
	obtain the currently active barrier id

uint64_t	random64 ()
	Generate one 64bit unsigned integer between 0 and UINT64_MAX (both inclusive). More...

uint32_t	random32 ()
	Generate one 32bit unsigned integer between 0 and UINT32_MAX (both inclusive) More...

double	random01 ()
	Generate a random double value between 0 and 1, both limits excluded. More...

Double_t	Rndm ()
	Generate a random value in (0,1), both limits excluded.

Double_t	Rndm (Int_t)
	Generate a random value in (0,1), both limits excluded (backward compatibility with root < 6.08).

void	RndmArray (Int_t n, Float_t *array)
	Fill an array of floats with random values in (0,1), both limits excluded. More...

void	RndmArray (Int_t n, Double_t *array)
	Fill an array of doubles with random values in (0,1), both limits excluded. More...

void	RndmArray (Int_t n, ULong64_t *array)
	Fill an array of unsigned 64bit integers with random values in [0, UINT64_MAX], both limits included. More...

void	RndmArray (Int_t n, UInt_t *array)
	Fill an array of unsigned integers with random values in [0, UINT32_MAX], both limits included. More...

void	RndmArray (Int_t n, Int_t *array)
	Fill an array of 32bit integers with random values in [INT32_MIN, INT32_MAX], both limits included. More...

void	RndmArray (Int_t n, Long64_t *array)
	Fill an array of 64bit integers with random values in [INT64_MIN, INT64_MAX], both limits included. More...

void	RndmArray (Int_t n, unsigned char *array)
	Fill an array with random data. More...

Private Member Functions
void	SetSeed (UInt_t)
	override base class SetSeed to do nothing, we don't need it but it gets called by parent constructor

void	SetSeed (ULong_t)
	argument type was changed in root 6.08.

void	setState (int barrier)
	Set the state of the random number generator. More...

	ClassDef (RandomGenerator, 2)
	and the root dictionary macro needs to be documented as well :) Version 2: merge m_eventDependent and m_useEventData into a general generator mode m_mode

Private Attributes
uint64_t	m_state [16]
	Internal state of the random number generator.

unsigned int	m_index
	currently active index in the internal state

int	m_barrier
	current barrier index. More...

std::vector< unsigned char >	m_seed
	seed information

EGeneratorMode	m_mode
	Current generator mode.

Detailed Description

Fast Random number Generator using on xorshift1024* [arXiv:1402.6246].

It has a period of 2^{1024-1} and passes the Big Crush test while being very small and fast with an internal state of just 1024bit. We seed the generator at the beginning of each event with a combination of a seed value and the experiment/run/event number information of that event to ensure maximum reproducibility even in multiprocessing environments.

The seeding is done using the Keccak secure hash algorithm (SHA-3, FIPS 202 Draft) with arbitrary hash length (set to 1024bit). This ensures evenly distributed generator states even with only small changes in the event information and large numbers of zeros in the seed information. We generate the hash from the (optional) arbitrary seed information followed by the event meta data in big endian representation.

See BELLE2-NOTE-TE-2015-031: Belle II UNICORN – UNIfied Calculation Of Random Numbers for details. Available at: https://docs.belle2.org/record/292?ln=en

Definition at line 37 of file RandomGenerator.h.

Member Enumeration Documentation

◆ EGeneratorMode

enum EGeneratorMode

Generator mode: determines which information is used to generate the internal state.

Enumerator
c_independent	Don't use event info to generate state.
c_runDependent	Use experiment and run number to generate state.
c_eventDependent	Use experiment, run and event number to generate state.

Definition at line 41 of file RandomGenerator.h.

Member Function Documentation

◆ barrier()

void barrier ( )

inline

increase the barrier index.

This will reseed the generator with the current event information and and a new barrier index to make random number state independent between different parts of the steering file.

Definition at line 86 of file RandomGenerator.h.

◆ initialize()

void initialize ( void )

inline

set the State from event meta information like experiment, run, and event number.

The event number is only used if the generator is set to event dependent on construction.

Definition at line 80 of file RandomGenerator.h.

◆ random32()

uint32_t random32 ( )

inline

Generate one 32bit unsigned integer between 0 and UINT32_MAX (both inclusive)

Returns: random value in [0, UINT32_MAX]

Definition at line 104 of file RandomGenerator.h.

◆ RndmArray() [1/3]

void RndmArray	(	Int_t	n,
		Int_t *	array
	)

inline

Fill an array of 32bit integers with random values in [INT32_MIN, INT32_MAX], both limits included.

Parameters

n	number of ints to generate
array	pointer to an array where the numbers should be stored

Definition at line 144 of file RandomGenerator.h.

◆ RndmArray() [2/3]

void RndmArray	(	Int_t	n,
		Long64_t *	array
	)

inline

Fill an array of 64bit integers with random values in [INT64_MIN, INT64_MAX], both limits included.

Parameters

n	number of ints to generate
array	pointer to an array where the numbers should be stored

Definition at line 151 of file RandomGenerator.h.

◆ RndmArray() [3/3]

void RndmArray	(	Int_t	n,
		unsigned char *	array
	)

Fill an array with random data.

Parameters

n	number of bytes to generate
array	pointer to an array where the data should be stored

Definition at line 120 of file RandomGenerator.cc.

 {
   //First we fill the array using 64bit blocks
   RndmArray(n / sizeof(ULong64_t), (ULong64_t*)array);
   const Int_t remainder = n % sizeof(ULong64_t);
   //If the size is not divisible by 8 we fill the remainder from one additional
   //random value
   if (remainder) {
     const ULong64_t r = random64();
     std::copy_n((unsigned char*)&r, remainder, array + (n - remainder - 1));
   }
 }

◆ setSeed()

void setSeed	(	const unsigned char *	seed,
		unsigned int	n
	)

Set the seed information.

This can be an arbitrary sequence of bytes: strings, values, etc. It should be less or equal to 128 bytes as this is the size of the random generator state but it can be longer. The seed is copied when calling this function so the original buffer can be freed afterwards

Parameters

seed	pointer to seed data
n	of the seed data in bytes

Definition at line 42 of file RandomGenerator.cc.

◆ setState()

void setState ( int barrier )

private

Set the state of the random number generator.

To achieve maximum reproducibility the generator is reset at the begin of every event using a combination of the seed data and the experiment/run/event number and possible some extra information.

To achieve a good separation of the state for similar event information we use the Keccak hash algorithm (SHAKE, FIPS202 draft) where we select the hashsize to be equal to the generator state. This generates evenly distributed generator states even for input data which contains many zeros.

Parameters

barrier index to use when setting the state. m_barrier will be set to his value

Definition at line 51 of file RandomGenerator.cc.

Member Data Documentation

◆ m_barrier

int m_barrier

private

current barrier index.

This is used to separate random numbers in different modules by resetting the state between modules using a different barrier index.

Definition at line 188 of file RandomGenerator.h.

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

framework/core/include/RandomGenerator.h
framework/core/src/RandomGenerator.cc

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ EGeneratorMode

Member Function Documentation

◆ barrier()

◆ initialize()

◆ random32()

◆ RndmArray() [1/3]

◆ RndmArray() [2/3]

◆ RndmArray() [3/3]

◆ setSeed()

◆ setState()

Member Data Documentation

◆ m_barrier