source: trunk/documents/UserDoc/DocBookUsersGuides/ForToolkitDeveloper/xml/OOAnalysisDesign/GlobalUsage/globalUsage.xml

<!-- ******************************************************** -->
<!--  Docbook Version:  For Toolkit Developers Guide          -->
<!-- ******************************************************** -->

<!-- ******************* Section (Level#1) ****************** -->
<sect1 id="sect.DsgnFuncGlobUsg">
<title>
Global Usage
</title>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.DsgnFuncGlobUsg.DsgPhlsp">
<title>
Design Philosophy
</title>

<para>
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 Geant4. 
No back-dependencies to other 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.
</para>

<para>
Within the management sub-category are ``utility'' classes generally used 
within the Geant4 kernel.  They are, for the most part, uncorrelated 
with one another and include:

<itemizedlist spacing="compact">
  <listitem><para>
    <emphasis role="italic">G4Allocator</emphasis>
  </para></listitem>
  <listitem><para>
    <emphasis role="italic">G4FastVector</emphasis>
  </para></listitem>
  <listitem><para>
    <emphasis role="italic">G4ReferenceCountedHandle</emphasis>
  </para></listitem>
  <listitem><para>
    <emphasis role="italic">G4PhysicsVector, G4LPhysicsFreeVector, 
    G4PhysicsOrderedFreeVector</emphasis>
  </para></listitem>
  <listitem><para>
    <emphasis role="italic">G4Timer</emphasis>
  </para></listitem>
  <listitem><para>
    <emphasis role="italic">G4UserLimits</emphasis>
  </para></listitem>
  <listitem><para>
    <emphasis role="italic">G4UnitsTable</emphasis>
  </para></listitem>
</itemizedlist>
</para>

<para>
A general description of these classes is given in section 3.2 of the 
Geant4 User's Guide for Application Developers. 
</para>

<para>
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 Geant4.  
</para>

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.DsgnFuncGlobUsg.ClassDsg">
<title>
Class Design
</title>

<para>
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.  
<xref linkend="fig.DsgnFuncGlobUsg_1" />
is a general picture of the static class diagram. 

<itemizedlist spacing="compact">
  <listitem><para>
    <emphasis role="bold">HepRandomEngine</emphasis> -
    abstract class defining the interface for each Random engine. Its pure 
    virtual methods must be defined by its subclasses representing the 
    concrete Random engines.
  </para></listitem> 
  <listitem><para>
    <emphasis role="bold">HepJamesRandom</emphasis> -
    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. 
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">DRand48Engine</emphasis> -
    class inheriting from HepRandomEngine and defining a flat random number 
    generator according to the drand48() and srand48() system functions from 
    the C standard library.
  </para></listitem> 
  <listitem><para>
    <emphasis role="bold">RandEngine</emphasis> -
    class inheriting from HepRandomEngine and defining a flat random number 
    generator according to the rand() and srand() system functions from the 
    C standard library. 
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">RanluxEngine</emphasis> -
    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]. 
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">RanecuEngine</emphasis> -
    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. 
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">HepRandom</emphasis> -
    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. 
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">RandFlat</emphasis> -
    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. 
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">RandExponential</emphasis> -
    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.
  </para></listitem> 
  <listitem><para>
    <emphasis role="bold">RandGauss</emphasis> -
    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. 
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">RandBreitWigner</emphasis> -
    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. 
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">RandPoisson</emphasis> -
    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.
  </para></listitem> 
</itemizedlist>

<figure id="fig.DsgnFuncGlobUsg_1">
<title>
HEPRandom module
</title>
<mediaobject>
  <imageobject role="fo">
    <imagedata fileref="./AllResources/OOAnalysisDesign/GlobalUsage/classDgmRandom.jpg" 
               format="JPG" contentwidth="10.0cm" align="center" />
  </imageobject>
  <imageobject role="html">
    <imagedata fileref="./AllResources/OOAnalysisDesign/GlobalUsage/classDgmRandom.jpg" 
               format="JPG" contentwidth="120%" align="center" />
  </imageobject>
</mediaobject>
</figure>
</para>

<para>
<xref linkend="fig.DsgnFuncGlobUsg_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. 

<figure id="fig.DsgnFuncGlobUsg_2">
<title>
Shooting via the generator
</title>
<mediaobject>
  <imageobject role="fo">
    <imagedata fileref="./AllResources/OOAnalysisDesign/GlobalUsage/ObjDiagStat.jpg" 
               format="JPG" contentwidth="10.0cm" align="center" />
  </imageobject>
  <imageobject role="html">
    <imagedata fileref="./AllResources/OOAnalysisDesign/GlobalUsage/ObjDiagStat.jpg" 
               format="JPG" contentwidth="120%" align="center" />
  </imageobject>
</mediaobject>
</figure>
</para>

<para>
<xref linkend="fig.DsgnFuncGlobUsg_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. 

<figure id="fig.DsgnFuncGlobUsg_3">
<title>
Shooting via distribution objects
</title>
<mediaobject>
  <imageobject role="fo">
    <imagedata fileref="./AllResources/OOAnalysisDesign/GlobalUsage/ObjDiagDist.jpg" 
               format="JPG" contentwidth="10.0cm" align="center" />
  </imageobject>
  <imageobject role="html">
    <imagedata fileref="./AllResources/OOAnalysisDesign/GlobalUsage/ObjDiagDist.jpg" 
               format="JPG" contentwidth="120%" align="center" />
  </imageobject>
</mediaobject>
</figure>
</para>

<para>
<xref linkend="fig.DsgnFuncGlobUsg_4" /> illustrates the situation when many 
generators are defined, each by a distribution and an engine.  The static 
interface is skipped here. 

<figure id="fig.DsgnFuncGlobUsg_4">
<title>
Shooting with arbitrary engines
</title>
<mediaobject>
  <imageobject role="fo">
    <imagedata fileref="./AllResources/OOAnalysisDesign/GlobalUsage/ObjDiagEng.jpg" 
               format="JPG" contentwidth="10.0cm" align="center" />
  </imageobject>
  <imageobject role="html">
    <imagedata fileref="./AllResources/OOAnalysisDesign/GlobalUsage/ObjDiagEng.jpg" 
               format="JPG" contentwidth="120%" align="center" />
  </imageobject>
</mediaobject>
</figure>
</para>

<para>
For detailed documentation about the HEPRandom classes see the 
CLHEP Reference Guide(http://cern.ch/clhep/manual/RefGuide)
or the CLHEP User Manua(http://cern.ch/clhep/manual/UserGuide).
</para>

<para>
Informations written in this manual are extracted
from the original manifesto distributed with the HEPRandom package
(http://cern.ch/clhep/manual/UserGuide/Random/Random.html). 
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
HEPNumerics
</bridgehead>

<para>
The HEPNumerics module includes a set of classes which implement numerical 
algorithms for general use in Geant4.  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:

<itemizedlist spacing="compact">
  <listitem><para> 
    B.H. Flowers, "An introduction to Numerical Methods In C++", 
    Claredon Press, Oxford 1995.
  </para></listitem> 
  <listitem><para>
    M. Abramowitz, I. Stegun, "Handbook of mathematical functions", 
    DOVER Publications INC, New York 1965 ; chapters 9, 10, and 22. 
  </para></listitem>
</itemizedlist>
</para>


<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
HEPGeometry
</bridgehead>

<para>
Documentation for the HEPGeometry module is provided in the CLHEP 
Reference Guide(http://cern.ch/clhep/manual/RefGuide) 
or the CLHEP User Manual(http://cern.ch/clhep/manual/UserGuide). 
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead role="revisionHistory" renderas="sect4">
[Status of this chapter]
</bridgehead>
<para>
<simplelist type="var">
  <member>
    01.12.02 minor update by G. Cosmo
  </member>
  <member>
    18.06.05 introductory paragraphs added and minor grammar changes by D.H. Wright
  </member>
  <member>
    Dec. 2006 Conversion from latex to Docbook verson by K. Amako
  </member>
</simplelist>
</para>
    

</sect2>
</sect1>