Contents Previous Next Geant4 User's Guide
For Application Developers
Toolkit Fundamentals

3.2 Global Usage Classes

The "global" category in Geant4 collects all classes, types, structures and constants which are considered of general use within the Geant4 toolkit. This category also defines the interface with third-party software libraries (CLHEP, STL, etc.) and system-related types, by defining, where appropriate, typedefs according to the Geant4 code conventions.

3.2.1 Signature of Geant4 classes

In order to keep an homogeneous naming style, and according to the Geant4 coding style conventions, each class part of the Geant4 kernel has its name beginning with the prefix G4, e.g., G4VHit, G4GeometryManager, G4ProcessVector, etc. Instead of the raw C types, G4 types are used within the Geant4 code. For the basic numeric types (int, float, double, etc.), different compilers and different platforms provide different value ranges. In order to assure portability, the use of G4int, G4float, G4double, which are base classes globally defined, is preferable. G4 types implement the right generic type for a given architecture.

Basic types

The basic types in Geant4 are considered to be the following:

G4int, G4long, G4float, G4double, G4bool, G4complex and G4String

which currently consist of simple typedefs to respective types defined in the CLHEP, STL or system libraries. Most definitions of these basic types come with the inclusion of a single header file, globals.hh. This file also provides inclusion of required system headers, as well as some global utility functions needed and used within the Geant4 kernel.

Typedefs to CLHEP classes and their usage

The following classes are typedefs to the corresponding classes of the CLHEP (Computing Library for High Energy Physics) distribution. For more detailed documentation please refer to the CLHEP reference guide [1] and the CLHEP user manual [2].

3.2.2 The HEPRandom module in CLHEP

The HEPRandom module, originally part of the Geant4 kernel, and now distributed as a module of CLHEP, has been designed and developed starting from the Random class of MC++, the original CLHEP's HepRandom module and the Rogue Wave approach in the Math.h++ package. For detailed documentation on the HEPRandom classes see the CLHEP Reference Guide [1] or the CLHEP User Manual [2].

Information written in this manual is extracted from the original manifesto [3] distributed with the HEPRandom package.

The HEPRandom module consists of classes implementing different random ``engines'' and different random ``distributions''. A distribution associated to an engine constitutes a random ``generator''. A distribution class can collect different algorithms and different calling sequences for each method to define distribution parameters or range-intervals. An engine implements the basic algorithm for pseudo-random numbers generation.

There are 3 different ways of shooting random values:

  1. Using the static generator defined in the HepRandom class: random values are shot using static methods shoot() defined for each distribution class. The static generator will use, as default engine, a HepJamesRandom object, and the user can set its properties or change it with a new instantiated engine object by using the static methods defined in the HepRandom class.
  2. Skipping the static generator and specifying an engine object: random values are shot using static methods shoot(*HepRandomEngine) defined for each distribution class. The user must instantiate an engine object and give it as argument to the shoot method. The generator mechanism will then be by-passed by using the basic flat() method of the specified engine. The user must take care of the engine objects he/she instantiates.
  3. Skipping the static generator and instantiating a distribution object: random values are shot using fire() methods (NOT static) defined for each distribution class. The user must instantiate a distribution object giving as argument to the constructor an engine by pointer or by reference. By doing so, the engine will be associated to the distribution object and the generator mechanism will be by-passed by using the basic flat() method of that engine.

In this guide, we'll only focus on the static generator (point 1.), since the static interface of HEPRandom is the only one used within the Geant4 toolkit.

HEPRandom engines

The class HepRandomEngine is the abstract class defining the interface for each random engine. It implements the getSeed() and getSeeds() methods which return the `initial seed' value and the initial array of seeds (if any) respectively. Many concrete random engines can be defined and added to the structure, simply making them inheriting from HepRandomEngine. Several different engines are currently implemented in HepRandom, we describe here five of them:

Except for the RanecuEngine, for which the internal status is represented by just a couple of longs, all the other engines have a much more complex representation of their internal status, which currently can be obtained only through the methods saveStatus(), restoreStatus() and showStatus(), which can also be statically called from HepRandom. The status of the generator is needed for example to be able to reproduce a run or an event in a run at a given stage of the simulation.

RanecuEngine is probably the most suitable engine for this kind of operation, since its internal status can be fetched/reset by simply using getSeeds()/setSeeds() (getTheSeeds()/setTheSeeds() for the static interface in HepRandom).

The static interface in the HepRandom class

HepRandom a singleton class and using a HepJamesRandom engine as default algorithm for pseudo-random number generation. HepRandom defines a static private data member, theGenerator, and a set of static methods to manipulate it. By means of theGenerator, the user can change the underlying engine algorithm, get and set the seeds, and use any kind of defined random distribution. The static methods setTheSeed() and getTheSeed() will set and get respectively the `initial' seed to the main engine used by the static generator. For example: 

      HepRandom::setTheSeed(seed);  // to change the current seed to 'seed'
      int startSeed = HepRandom::getTheSeed();  // to get the current initial seed
      HepRandom::saveEngineStatus();    // to save the current engine status on file
      HepRandom::restoreEngineStatus(); // to restore the current engine to a previous
                                        // saved configuration
      HepRandom::showEngineStatus();    // to display the current engine status to stdout
      ...
      int index=n;
      long seeds[2];
      HepRandom::getTheTableSeeds(seeds,index);
        // fills `seeds' with the values stored in the global
        // seedTable at position `index'

Only one random engine can be active at a time, the user can decide at any time to change it, define a new one (if not done already) and set it. For example: 

      RanecuEngine theNewEngine;
      HepRandom::setTheEngine(&theNewEngine);
       ...

or simply setting it to an old instantiated engine (the old engine status is kept and the new random sequence will start exactly from the last one previously interrupted). For example: 

      HepRandom::setTheEngine(&myOldEngine);

Other static methods defined in this class are:

HEPRandom distributions

A distribution-class can collect different algorithms and different calling sequences for each method to define distribution parameters or range-intervals; it also collects methods to fill arrays, of specified size, of random values, according to the distribution. This class collects either static and not static methods. A set of distribution classes are defined in HEPRandom. Here is the description of some of them:

3.2.3 The HEPNumerics module

A set of classes implementing numerical algorithms has been developed in Geant4. Most of the algorithms and methods have been implemented mainly based on recommendations given in the books:

This set of classes includes:

3.2.4 General management classes

The `global' category defines also a set of `utility' classes generally used within the kernel of Geant4. These classes include:

[1] cern.ch/clhep/manual/RefGuide.
[2] cern.ch/clhep/manual/UserGuide.
[3] cern.ch/wwwasd/geant/geant4_public/Random.html.

About the authors