source: trunk/documents/UserDoc/UsersGuides/ForToolkitDeveloper/latex/OOAnalysisDesign/GlobalUsage/globalUsage.tex @ 1332

\chapter{Global Usage}

\section{Design Philosophy}
The global category covers the system of units, constants, numerics and 
random number handling.  It can be considered a place-holder for 
"general purpose" classes used by all categories defined in {\sc Geant4}. 
No back-dependencies to other {\sc Geant4} categories affect the "global" 
domain.  There are direct dependencies of the global category on external 
packages, such as CLHEP, STL, and miscellaneous system utilities.

Within the management sub-category are ``utility'' classes generally used 
within the {\sc Geant4} kernel.  They are, for the most part, uncorrelated 
with one another and include:
\begin{itemize}
\item {\it G4Allocator} 
\item {\it G4FastVector} 
\item {\it G4ReferenceCountedHandle}
\item {\it G4PhysicsVector, G4LPhysicsFreeVector, G4PhysicsOrderedFreeVector} 
\item {\it G4Timer} 
\item {\it G4UserLimits}
\item {\it G4UnitsTable} 
\end{itemize}
A general description of these classes is given in section 3.2 of the 
{\sc Geant4} User's Guide for Application Developers. 

In applications where it is necessary to generate random numbers (normally 
from the same engine) in many different methods and parts of the program, it 
is highly desirable not to rely on or require knowledge of the global objects 
instantiated.  By using static methods via a unique generator, the randomness 
of a sequence of numbers is best assured.  Hence the use of a static generator 
has been introduced in the original design of HEPRandom as a project 
requirement in {\sc Geant4}.  

\section{Class Design}

Analysis and design of the HEPRandom module have been achieved following 
the Booch Object-Oriented methodology.  Some of the original design 
diagrams in Booch notation are reported below.  Fig. \ref{figure:random-1} 
is a general picture of the static class diagram. 

\begin{itemize}
\item {\bf HepRandomEngine} -
    abstract class defining the interface for each Random engine. Its pure 
    virtual methods must be defined by its subclasses representing the 
    concrete Random engines. 
\item {\bf HepJamesRandom} -
    class inheriting from HepRandomEngine and defining a flat random number 
    generator according to the algorithm described in 
    "F.James, Comp.Phys.Comm. 60 (1990) 329". This class is instantiated by 
    default as the default random engine. 
\item {\bf DRand48Engine} -
    class inheriting from HepRandomEngine and defining a flat random number 
    generator according to the drand48() and srand48() system functions from 
    the C standard library. 
\item {\bf RandEngine} -
    class inheriting from HepRandomEngine and defining a flat random number 
    generator according to the rand() and srand() system functions from the 
    C standard library. 
\item {\bf RanluxEngine} -
    class inheriting from HepRandomEngine and defining a flat random number 
    generator according to the algorithm described in 
    "F.James, Comp.Phys.Comm. 60 (1990) 329-344" and originally implemented 
    in FORTRAN 77 as part of the MATHLIB HEP library. It provides 5 different 
    "luxury" levels [0..4]. 
\item {\bf RanecuEngine} -
    class inheriting from HepRandomEngine and defining a flat random number 
    generator according to the algorithm RANECU originally written in 
    FORTRAN 77 as part of the MATHLIB HEP library. It uses a table of seeds 
    which provides uncorrelated couples of seed values. 
\item {\bf HepRandom} -
    the main class collecting all the methods defining the different random 
    generators applied to HepRandomEngine. It is a singleton class which all 
    the distribution classes derive from.  This singleton is instantiated by 
    default. 
\item {\bf RandFlat} -
    distribution class for flat random number generation. It also provides 
    methods to fill an array of flat random values, given its size or shoot 
    bits. 
\item {\bf RandExponential} -
    distribution class defining exponential random number distribution, given 
    a mean.  It also provides a method to fill an array of flat random values, 
    given its size. 
\item {\bf RandGauss} -
    distribution class defining Gauss random number distribution, given a 
    mean or specifying also a deviation. It also provides a method to fill 
    an array of flat random values, given its size. 
\item {\bf RandBreitWigner} -
    distribution class defining the Breit-Wigner random number distribution. 
    It also provides a method to fill an array of flat random values, given 
    its size. 
\item {\bf RandPoisson} -
    distribution class defining Poisson random number distribution, given a 
    mean. It also provides a method to fill an array of flat random values, 
    given its size. 
\end{itemize}


\begin{figure}[h!]
\includegraphics[angle=0,scale=0.6]{OOAnalysisDesign/GlobalUsage/classDgmRandom.eps}
\vspace{10pt}
\caption{HEPRandom module}
\label{figure:random-1}
\end{figure}


Fig. \ref{figure:random-2} is a dynamic object diagram illustrating the 
situation when a single random number is thrown by the static generator 
according to one of the available distributions.  Only one engine is 
assumed to active at a time. 

\begin{figure}[h!]
\includegraphics[angle=0,scale=0.6]{OOAnalysisDesign/GlobalUsage/ObjDiagStat.eps}
\vspace{10pt}
\caption{Shooting via the generator}
\label{figure:random-2}
\end{figure}

Fig. \ref{figure:random-3} illustrates a random number being thrown by 
explicitly specifying an engine which can be shared by many distribution 
objects.  The static interface is skipped here. 

\begin{figure}[h!]
\includegraphics[angle=0,scale=0.6]{OOAnalysisDesign/GlobalUsage/ObjDiagDist.eps}
\vspace{10pt}
\caption{Shooting via distribution objects}
\label{figure:random-3}
\end{figure}

Fig. \ref{figure:random-4} illustrates the situation when many generators are 
defined, each by a distribution and an engine.  The static interface is 
skipped here. 

\begin{figure}[h!]
\includegraphics[angle=0,scale=0.6]{OOAnalysisDesign/GlobalUsage/ObjDiagEng.eps}
\vspace{10pt}
\caption{Shooting with arbitrary engines}
\label{figure:random-4}
\end{figure}

For detailed documentation about the HEPRandom classes see the 
CLHEP Reference Guide\newline
(http://cern.ch/clhep/manual/RefGuide)\newline
or the CLHEP User Manual\newline
(http://cern.ch/clhep/manual/UserGuide).\newline
 Informations written in this manual are extracted
from the original manifesto distributed with the HEPRandom package\newline
(http://cern.ch/clhep/manual/UserGuide/Random/Random.html). 

\paragraph{HEPNumerics}
The HEPNumerics module includes a set of classes which implement numerical 
algorithms for general use in {\sc Geant4}.  Section 3.2.3 of the User's Guide 
for Application Developers contains a description of each class.  Most of 
the algorithms were implemented using methods from the following books:
\mbox{}
\begin{itemize}
\item  B.H. Flowers, "An introduction to Numerical Methods In C++", 
       Claredon Press, Oxford 1995. 
\item M. Abramowitz, I. Stegun, "Handbook of mathematical functions", 
      DOVER Publications INC, New York 1965 ; chapters 9, 10, and 22. 
\end{itemize}

\paragraph{HEPGeometry}
Documentation for the HEPGeometry module is provided in the CLHEP 
Reference Guide\newline
(http://cern.ch/clhep/manual/RefGuide) 
or the CLHEP User Manual\newline
(http://cern.ch/clhep/manual/UserGuide) 

\section{Status of this chapter}

01.12.02 minor update by G. Cosmo \\
18.06.05 introductory paragraphs added and minor grammar changes by D.H. Wright \\