ZOOM CLEHP Random: New (or changed) Methods

ZOOM ZOOM

ZOOM CLEHP Random: New (or changed) Methods

HEP Random is a collection of random number engines and a variety of distributions which use those engines to generate pseudo-random numbers.

The ZOOM validation consists of

Verifying correct statistical properties of the engines and distributions
Testing the original code and correcting minor bugs
Providing a few additional methods requested by the Run II user community
Completing the set of distributions, to include the full list Review of Particle Properties.

The additional methods are listed here.

Constructors of Random Engines

Default Constructors

RandEngine();
DRand48Engine();
HepJamesRandom();
RanecuEngine();
RanluxEngine();

Note: The default constructor will assign a unique seed for each instance. Thus two default engines of the same type will produce two different sequences.
This differs from the original behavior, where each instance would be seeded with the same number so that they would produce identical sequences.
(The seeding is still deterministic: In a given run, the first engine of a given class instantiated with the default constructor will always have the same seed.)

Constructors with User-specified Seeds

Each engine contains a table (either physically or logically) of seeds; the user may specify a particular entry. This may be useful for two applications to "rendezvous" on using a particular sequence.

  RandEngine(HepInt rowIndex, HepInt colIndex);
  DRand48Engine(HepInt rowIndex, HepInt colIndex);
  HepJamesRandom(HepInt rowIndex, HepInt colIndex);
  RanecuEngine(HepInt index);
	For RanecuEngine the two-index form is not present; the
	single index form both acts as an index into the table and
	coincides with the behavior of the original package.
  RanluxEngine(HepInt rowIndex, HepInt colIndex, HepInt lux);
	RanecuEngine requires the user specify the lux level 
	when the row and column index form of 
	constructor is used.  Normally, the high luxury level
	(3) should be specified.

The constructor accepting a single long as a seed will behave exactly as in the original: It will assign a seed based on the long provided. Thus existing programs using this form of constructor will give the same random sequence as in the original package.

  RandEngine(long seed);
  DRand48Engine(long seed);
  HepJamesRandom(long seed);
  RanecuEngine(HepInt index);
  RanluxEngine(long seed, HepInt lux = 3);

Constructors accepting istream input

RandEngine(istream & is);
DRand48Engine(istream & is);
HepJamesRandom(istream & is);
RanecuEngine(istream & is);
RanluxEngine(istream & is);

Saving and Restoring Random Engine Status

Saving to a file / Restoring from a file

The user may now supply the file name. If the name is not supplied, the name chosen will be the same name as the original package would use.
The following are each methods one of the corresponding engine classes; the default filename is specific to the class.

void saveStatus( const char filename[] = "Rand.conf" ) const;
void saveStatus( const char filename[] = "DRand48.conf" ) const;
void saveStatus( const char filename[] = "JamesRand.conf" ) const;
void saveStatus( const char filename[] = "Ranecu.conf" ) const;
void saveStatus( const char filename[] = "Ranlux.conf" ) const;

void restoreStatus( const char filename[] = "Rand.conf" );
void restoreStatus( const char filename[] = "DRand48.conf" );
void restoreStatus( const char filename[] = "JamesRand.conf" );
void restoreStatus( const char filename[] = "Ranlux.conf" );

Saving or restoring from a stream

friend ostream& operator<< (ostream& os, const RandEngine& e);
friend ostream& operator<< (ostream& os, const DRand48Engine& e);
friend ostream& operator<< (ostream& os, const HepJamesRandom& e);
friend ostream& operator<< (ostream& os, const RanecuEngine& e);
friend ostream& operator<< (ostream& os, const RanluxEngine& e);

friend istream& operator>> (istream& is,       RandEngine& e);
friend istream& operator>> (istream& is,       DRand48Engine& e);
friend istream& operator>> (istream& is,       HepJamesRandom& e);
friend istream& operator>> (istream& is,       RanecuEngine& e);
friend istream& operator>> (istream& is,       RanluxEngine& e);

Saving or restoring an engine state, as an object in memory

This ability was requested by several users. The nature of C++ objects makes this natural and easy; ZOOM did not have to change anything to get this for free. For example:

  RanluxEngine e;
  RanGauss g(e);
  double x = g();  ... 
  // Exercise the engine several times.
  RanluxEngine savedEngine (e);  // The key step:
                                 // Use the copy constructor!
  double x = g(); ...
  // Exercise the engine several more times.
  // Now if we want to get back to that saved state, 
  e = savedEngine;

New Methods in the Original Distribution Classes

Non-default parameters in "apply" operator()

Each distribution has always had an "apply" operator, as in


RandEngine e;  
 
RandGauss r(e); 
 
x = r();

Each distribution has also had fire() methods, accepting non-standard values of distribution parameters, as in



r.fire ( mean, sigma );

We have extended the signatures available for the "apply" operator to include all the options available for the fire operator. The default, as before, is to use the standard default parameters.

  RandBreitWigner::HepDouble operator()(HepDouble a, HepDouble b );
  RandBreitWigner::HepDouble operator()(HepDouble a, HepDouble b, HepDouble c);
  RandExponential::HepDouble operator()(HepDouble mean );
  RandFlat::HepDouble        operator()(HepDouble width );
  RandFlat::HepDouble        operator()(HepDouble a, HepDouble b );
  RandGauss::HepDouble       operator()(HepDouble mean, HepDouble stdDev );
  RandPoisson::HepDouble     operator()(HepDouble m);

Saving engine status to a specific file

The base class of all the distributions, HepRandom, has methods to save and restore the status of the engine it the distribution is attached to. We have provided a signature to let the user specify the name of the file. The default remains "config.conf" to match the original behavior.

  void HepRandom::saveStatus(    const char filename[] = "Config.conf" ) const;
  void HepRandom::restoreStatus( const char filename[] = "Config.conf" ) const;

Alternate Distribution Classes

ZMRandFlat
ZMRandGauss
ZMRandPoisson
ZMRandExponential
ZMRandBreitWigner

These are present to avoid any chance of affecting legacy user code by changes in the distribution classes.

The main point is that given the ability to construct a distribution with non-standard default parameters, the behavior of the original shoot() method becomes misleading or confusing. We intend to re-unify these classes soon, after the CLHEP and GEANT4 people resolve help this issue.

Constructors specifying non-standard default parameters

  ZMRandFlat ( HepRandomEngine& anEngine,
                 HepDouble defaultRmin=0.0, HepDouble defaultRmax=1.0 );

  ZMRandGauss ( HepRandomEngine& anEngine,
                 HepDouble mean=0.0, HepDouble sig=1.0 )

  ZMRandPoisson ( HepRandomEngine& anEngine, 
                 HepDouble mean = 1.0 );

  ZMRandExponential ( HepRandomEngine& anEngine, 
                 HepDouble mean=1.0 );

  ZMRandBreitWigner ( HepRandomEngine& anEngine, 
                 HepDouble mean=1.0, HepDouble gamma=0.2, HepDouble cut=1.0 );

(Corresponding constructors accepting HepRandomEngine* are also present.)

For example:

  JamesRandom e;
  ZMRandGauss g0 (e);  
  ZMRandGauss g3 (e, 3.0, 1.5);  
  double x;  
  g0.fire();          // Random Gaussian with mean = 0, sigma = 1 
  g0.fire(5.0, 2.0);  // Random Gaussian with mean = 5, sigma = 2
  g3.fire();          // Random Gaussian with mean = 3, sigma = 1.5
  g0.fire(6.0, 3.0);  // Random Gaussian with mean = 6, sigma = 3

Methods not present in alternate distribution classes

shoot()
Copy constructor and assignment operator

CLHEP Random Validation Page - ZOOM Home Page - Fermilab at Work - Fermilab Home

John Marraffino

and

Mark Fischler

Last modified: January 26, 1998