Saving and Restoring States of CLHEP Random Engines and Distributions

Saving and Restoring States of CLHEP Random Engines and Distributions

We have added new (as of late 2004) methods to the CLHEP Random classes allowing more convenient and natural saving and restoring of engines and distributions. Some inconvenient features of the original methods are:

The usual idiom for saving data would be to write to an ostream and read from an istream. It is assumed that users know how to construct an fstream (ofstream or ifstream) to work with a file, and using these fstreams as ostreams and istreams.

We are adding methods that stick to this idiom, which greatly helps matters. (In fact, the first two of these inconveniences are immediately resolved, and the structure is right for dealing with the third.)

Use Cases

Each of these motivating use cases are based on the following theme: An experiment wishes, when running a simulation job in "debuggable" mode, to capture before each event enough information that a subsequent job can restart at an arbitrary critical event and get the same results (or more typically, exhibit the same problem for investigation). The states of all random engines evolve across events, so this state information must be saved with each event (and restored for the critical event).

One static distribution

The user employs one static distribution, calling (say) RandGauss::shoot(). She wishes to save/restore the full state (including underlying engine) of just that distribution. This is completely analogous to doing RandGauss::saveState("filename"), but it is desired that this state be added to a file rather than placed in its own file.

One instance of a distribution

The user has an instance of a distribution, which uses some instance of an engine. She wishes to save/restore its full state, including that of the underlying engine.

Some distributions sharing various engines

The user has several instances of a distributions of various types, (and/or uses the shoot() method of several static distributions) and one or more instances of engines of various types. To conserve I/O space, she wishes to separately save each engine and the non-engine-dependant state of each distribution. Since she knows which engines are used by which distributions, she will be able to restore the full states of all the distributions after restoring individual engine and distribution states.

All the static distributions

A multi-module program written by a collaboration makes extensive use of the shoot() method of various static distributions. They wish to make a single call to save/restore the states of all the static distributions in the CLHEP Randoms package. This method needs to take care of making sure that states of shared engines are saved only once, and that all needed engine instances are saved.

Since most or all the static distributions will be sharing one instance of an engines, and since the (non-engine) state of a distribution itself is miniscule, the "wasted" cost of saving the unused static distributions is acceptable.

(For this method to work, either the program has never modified the types of endgines underlying the various static distributions, or if these have been modified, the restoring program must know how to set up the matching engine type for each static distribution.)

Added Methods in CLHEP Random

There are two types of save and restore activities on a distribution, just as there are two modes of using a distribution to generate a random variate, depending on whether you want the static distribution or an instance of the distribution. For the generation activity, the methods are Class::shoot() to use the static distribution, and instance.fire() to use an instance.

For these added methods which deal with saving and restoring to an fstream, the static methods all take the stream as an argument, while the instance methods use the ostream << whatever or istream >> whatever syntax.

As in the case of variate generation, all the methods dealing with just an engine are based on an instance.

Static methods in the distribution classes

Each distribution has six new static methods, which override static methods of the same names in the HepRandom class:
static ostream& saveFullState   (ostream& os) const;
static ostream& restoreFullState(ostream& os);
static ostream& saveDistState   (ostream& os) const;
static ostream& restoreDistState(ostream& os);
static ostream& saveStaticRandomStates (ostream& os) const;
static ostream& restoreStaticRandomStates(ostream& os);
The user could implement this last pair in terms of theEngine and engine and distribution save/restore methods, but it would be awkward, so we have put this combination into the library.

Instance methods in the distribution classes

ostream& operator << (ostream& os, const HepRandom & distribution);
istream& operator >> (ostream& os,       HepRandom & distribution);
RandomEngine * HepRandom::engine();
Conventionally, when saving the full state of a distribution, one should follow the order used by the methods for static distributions, which save the engine and then the remainder of the distribution state.

Instance methods in the engine classes

One added method of engine is provided, as a tool for future implementation of "generic engine" capability:
string RandomEngine::name();
Methods for I/O of engine states to streams are already present. Though not "additional methods," this are listed here because they are logically on the same footing as the distribution I/O methods, and will appear in the section describing how to code the use cases.
ostream& operator << (ostream& os, const RandomEngine & engine);
istream& operator >> (ostream& os,       RandomEngine & engine);

Caveat concerning RandEngine

We do not supply the additional save/restore capability in the case of an engine based on system random generator engine whose internal state is not controllable by the Random package, such as RandEngine. In such a case, it is unclear whether it is possible to modfy the engine state to accomplish the restore functionality.

How the Use Cases Can Be Coded

One static distribution

The "saving job" does:
  e = new DualRand(24681357);   // illustrating that the engine need not 
  RandGauss::setTheEngine (e);  // be the default engine for RandGauss
  ofstream fs(filename);      // or pass an ofstream already in use
  codeUsingRandGaussManyTimes();
 
  RandGauss::saveFullState(fs);

The "restoring job" does:
  e = new DualRand();   
  RandGauss::setTheEngine (e);  
  ifstream file(filename);      // or pass an ifstream already in use
 
  RandGauss::restoreFullState(fs);  

One instance of a distribution

The "saving job" does:
  e = new DualRand(24681357);   
  RandGauss g(e);               // normal distribution, based on engine e;  
  ofstream fs(filename);        
  codeUsing_g_ManyTimes();
 
  fs << g.engine() << g;

The "restoring job" does:
  e = new DualRand();   
  RandGauss g(e);
  ifstream fs(filename);      
 
  fs >> g.engine() >> g; 

Some distributions sharing various engines

The "saving job" does:
  e1 = new DualRand(24681357);  
  e2 = new MTwistEngine(135797531); 
  RandGauss g(e1);
  RandFlat  f(e1); 
  RandBit   b(e2);                
  ofstream fs(filename);        
  codeUsing_g_f_and_b();
 
  fs << e1 << e2 << g << f << b;

The "restoring job" does:
  e = new DualRand();   
  RandGauss g(e);
  ifstream fs(filename);      
 
  fs >> e1 >> e2 >> g >> f >> b;

To save and restore successfully in the general case, you must know not only which types of engines underlie the various distributions, but also which distributions share an engine.

All the static distributions

The "saving job" does:
  e = new DualRand(24681357);   // illustrating that the some distributions 
  RandGauss::setTheEngine (e);  // need not use the default engine
  ofstream fs(filename);        
  codeUsingVariousDistributions();
 
  saveStaticRandomStates(fs);

The "restoring job" does:
  e = new DualRand();   
  RandGauss::setTheEngine (e);  
  ifstream file(filename);      
 
  restoreStaticRandomStates(fs);


Author:
Mark Fischler

Last modified: December 1, 2004