source: trunk/documents/UserDoc/UsersGuides/ForApplicationDeveloper/html/Fundamentals/global.html @ 1358

Last change on this file since 1358 was 1208, checked in by garnier, 15 years ago

CVS update
File size: 20.9 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
2<html>
3
4<head>
5<title></title>
6<!-- Changed by: Katsuya Amako, 21-Sep-1998 -->
7<!-- Changed by: Katsuya Amako,  9-Jul-1998 -->
8<!-- Changed by: Katsuya Dosanjh, 15-Jul-2000 -->
9<!-- Changed by: Dennis Wright, 29-Nov-2001 -->
10<!-- Proof read by: Joe Chuma,   2-Jul-1999 -->
11<meta NAME="GENERATOR" CONTENT="Microsoft FrontPage 3.0">
12</head>
13
14<body>
15
16<table WIDTH="100%">
17<tr>
18<td>
19
20 
21<a HREF="index.html">
22<img SRC="../../../../resources/html/IconsGIF/Contents.gif" ALT="Contents" HEIGHT="16" WIDTH="59"></a> 
23<a HREF="classCategory.html">
24<img SRC="../../../../resources/html/IconsGIF/Previous.gif" ALT="Previous" HEIGHT="16" WIDTH="59"></a> 
25<a HREF="unitSystem.html">
26<img SRC="../../../../resources/html/IconsGIF/Next.gif" ALT="Next" HEIGHT="16" WIDTH="59"></a> 
27</td>
28<td ALIGN="Right"><font SIZE="-1" COLOR="#238E23"><b>Geant4 User's Guide</b> 
29<br>
30<b>For Application Developers</b> <br>
31<b>Toolkit Fundamentals</b> </font></td>
32</tr>
33</table>
34<font SIZE="+3" COLOR="#238E23">
35<b><p align="center">3.2 Global Usage Classes</b> </font><br>
36<br>
37</p>
38
39<hr ALIGN="Center" SIZE="7%">
40
41<p>The "global" category in Geant4 collects all classes, types, structures and constants
42which are considered of general use within the Geant4 toolkit. This category also defines
43the interface with third-party software libraries (CLHEP, STL, etc.) and
44system-related types, by defining, where appropriate, <tt>typedef</tt>s according to the
45Geant4 code conventions. </p>
46
47<a name="3.2.1">
48
49<h2>3.2.1 Signature of Geant4 classes</h2>
50</a>
51
52<p>In order to keep an homogeneous naming style, and according to the Geant4 coding style
53conventions, each class part of the Geant4 kernel has its name beginning with the prefix <i>G4</i>, e.g., <i>G4VHit,
54G4GeometryManager, G4ProcessVector,</i> etc. Instead of the raw C types, <i>G4</i> types
55are used within the Geant4 code. For the basic numeric types (<tt>int, float, double,</tt>
56etc.), different compilers and different platforms provide different value ranges. In
57order to assure portability, the use of <i>G4int, G4float, G4double,</i> which are base
58classes globally defined, is preferable. <i>G4</i> types implement the right generic type
59for a given architecture. </p>
60
61<b>Basic types</b>
62
63<p>The basic types in Geant4 are considered to be the following: </p>
64
65<p><i>G4int, G4long, G4float, G4double, G4bool, G4complex</i> and <i>G4String</i> </p>
66
67<p>which currently consist of simple <tt>typedef</tt>s to respective types defined in the
68<b>CLHEP</b>, <b>STL</b> or system libraries.
69Most definitions of these basic types come with the inclusion of a
70single header file, <tt>globals.hh</tt>. This file also provides inclusion of
71required system headers, as well as some global utility functions needed and used within
72the Geant4 kernel. </p>
73
74<b>Typedefs to CLHEP classes and their usage</b>
75
76<p>The following classes are <tt>typedef</tt>s to the corresponding classes of the <b>CLHEP</b>
77(<b>Computing Library for High Energy Physics</b>) distribution. For more detailed
78documentation please refer to the
79<a href="http://cern.ch/clhep/manual/RefGuide"><b>CLHEP reference guide</b></a>
80<a href="#CLHEP-ref">[1]</a> and the
81<a href="http://cern.ch/clhep/manual/UserGuide"><b>CLHEP user manual</b></a>
82<a href="#CLHEP-use">[2]</a>.
83
84<ul>
85  <li><i>G4ThreeVector, G4RotationMatrix, G4LorentzVector</i> and <i>G4LorentzRotation</i><p>Vector
86    classes: defining 3-component (x,y,z) vector entities, rotation of such objects as 3x3
87    matrices,<br>
88    4-component (x,y,z,t) vector entities and their rotation as 4x4 matrices.</p>
89  </li>
90  <li><i>G4Plane3D, G4Transform3D, G4Normal3D, G4Point3D</i>, and <i>G4Vector3D</i><p>Geometrical
91    classes: defining geometrical entities and transformations in 3D space. </p>
92  </li>
93</ul>
94
95<hr>
96<a name="3.2.2">
97
98<h2>3.2.2 The <i>HEPRandom</i> module in CLHEP</h2>
99</a>
100
101<p>The <i>HEPRandom</i> module, originally part of the Geant4 kernel, and now distributed
102as a module of <b>CLHEP</b>, has been designed and developed starting from the <i>Random</i>
103class of MC++, the original <b>CLHEP</b>'s <i>HepRandom</i> module and the <b>Rogue Wave</b>
104approach in the <b>Math.h++</b> package. For detailed documentation on the <i>HEPRandom</i>
105classes see the
106<a href="http://cern.ch/clhep/manual/RefGuide"><b>CLHEP Reference Guide</b></a>
107<a href="#CLHEP-ref">[1]</a> or the
108<a href="http://cern.ch/clhep/manual/UserGuide"><b>CLHEP User Manual</b></a>
109<a href="#CLHEP-use">[2]</a>. </p>
110
111<p>Information written in this manual is extracted from the original <a
112href="http://cern.ch/wwwasd/geant/geant4_public/Random.html">manifesto</a>
113<a href="#Random-doc">[3]</a> distributed with the <i>HEPRandom</i> package. </p>
114
115<p>The <i>HEPRandom</i> module consists of classes implementing different random
116``engines'' and different random ``distributions''. A distribution associated to an engine
117constitutes a random ``generator''. A distribution class can collect different algorithms
118and different calling sequences for each method to define distribution parameters or
119range-intervals. An engine implements the basic algorithm for pseudo-random numbers
120generation. </p>
121
122<p>There are 3 different ways of shooting random values:
123
124<ol>
125  <li>Using the static generator defined in the <i>HepRandom</i> class: random values are shot
126    using static methods <tt>shoot()</tt> defined for each distribution class. The static
127    generator will use, as default engine, a <i>HepJamesRandom</i> object, and the user can
128    set its properties or change it with a new instantiated engine object by using the static
129    methods defined in the <i>HepRandom</i> class.</li>
130  <li>Skipping the static generator and specifying an engine object: random values are shot
131    using static methods <tt>shoot(*HepRandomEngine)</tt> defined for each distribution class.
132    The user must instantiate an engine object and give it as argument to the shoot method.
133    The generator mechanism will then be by-passed by using the basic <tt>flat()</tt> method
134    of the specified engine. The user must take care of the engine objects he/she
135    instantiates.</li>
136  <li>Skipping the static generator and instantiating a distribution object: random values are
137    shot using <tt>fire()</tt> methods (NOT static) defined for each distribution class. The
138    user must instantiate a distribution object giving as argument to the constructor an
139    engine by pointer or by reference. By doing so, the engine will be associated to the
140    distribution object and the generator mechanism will be by-passed by using the basic <tt>flat()</tt>
141    method of that engine. </li>
142</ol>
143
144<p>In this guide, we'll only focus on the static generator (point 1.), since the static
145interface of <i>HEPRandom</i> is the only one used within the Geant4 toolkit. </p>
146
147<b><i>HEPRandom</i> engines</b>
148
149<p>The class <i>HepRandomEngine</i> is the abstract class defining the interface for each
150random engine. It implements the <tt>getSeed()</tt> and <tt>getSeeds()</tt> methods which
151return the `initial seed' value and the initial array of seeds (if any) respectively. Many
152concrete random engines can be defined and added to the structure, simply making them
153inheriting from <i>HepRandomEngine</i>. Several different engines are currently
154implemented in <i>HepRandom</i>, we describe here five of them:
155
156<ul>
157  <li><i>HepJamesRandom</i><p>It implements the algorithm described in ``F.James, Comp. Phys.
158    Comm. 60 (1990) 329'' for pseudo-random number generation. This is the default random
159    engine for the static generator; it will be invoked by each distribution class unless the
160    user sets a different one. </p>
161  </li>
162  <li><i>DRand48Engine</i><p>Random engine using the <tt>drand48()</tt> and <tt>srand48()</tt>
163    system functions from C standard library to implement the <tt>flat()</tt> basic
164    distribution and for setting seeds respectively. <i>DRand48Engine</i> uses the <tt>seed48()</tt>
165    function from C standard library to retrieve the current internal status of the generator,
166    which is represented by 3 short values. <i>DRand48Engine</i> is the only engine defined in
167    <i>HEPRandom</i> which intrinsically works in 32 bits precision. Copies of an object of
168    this kind are not allowed. </p>
169  </li>
170  <li><i>RandEngine</i><p>Simple random engine using the <tt>rand()</tt> and <tt>srand()</tt>
171    system functions from the C standard library to implement the <tt>flat()</tt> basic
172    distribution and for setting seeds respectively. Please note that it's well known that the
173    spectral properties of <tt>rand()</tt> leave a great deal to be desired, therefore the
174    usage of this engine is not recommended if a good randomness quality or a long period is
175    required in your code. Copies of an object of this kind are not allowed. </p>
176  </li>
177  <li><i>RanluxEngine</i><p>The algorithm for <i>RanluxEngine</i> has been taken from the
178    original implementation in FORTRAN77 by Fred James, part of the <b>MATHLIB HEP</b>
179    library. The initialisation is carried out using a Multiplicative Congruential generator
180    using formula constants of L'Ecuyer as described in ``F.James, Comp. Phys. Comm. 60 (1990)
181    329-344''. The engine provides five different luxury levels for quality of random
182    generation. When instantiating a <i>RanluxEngine</i>, the user can specify the luxury
183    level to the constructor (if not, the default value 3 is taken). For example: </p>
184    <pre>
185      RanluxEngine theRanluxEngine(seed,4);
186      // instantiates an engine with `seed' and the best luxury-level
187      ... or
188      RanluxEngine theRanluxEngine;
189      // instantiates an engine with default seed value and luxury-level
190      ...
191      </pre>
192    <p>The class provides a <tt>getLuxury()</tt> method to get the engine luxury level. </p>
193    <p>The <tt>SetSeed()</tt> and <tt>SetSeeds()</tt> methods to set the initial seeds for the
194    engine, can be invoked specifying the luxury level. For example: </p>
195    <pre>
196      // static interface
197      HepRandom::setTheSeed(seed,4);  // sets the seed to `seed' and luxury to 4
198      HepRandom::setTheSeed(seed);    // sets the seed to `seed' keeping
199                                      // the current luxury level
200      </pre>
201  </li>
202  <li><i>RanecuEngine</i><p>The algorithm for <i>RanecuEngine</i> is taken from the one
203    originally written in FORTRAN77 as part of the <b>MATHLIB HEP</b> library. The
204    initialisation is carried out using a Multiplicative Congruential generator using formula
205    constants of L'Ecuyer as described in ``F.James, Comp. Phys. Comm. 60 (1990) 329-344''.
206    Handling of seeds for this engine is slightly different than the other engines in <i>HEPRandom</i>.
207    Seeds are taken from a seed table given an index, the <tt>getSeed()</tt> method returns
208    the current index of seed table. The <tt>setSeeds()</tt> method will set seeds in the
209    local <tt>SeedTable</tt> at a given position index (if the index number specified exceeds
210    the table's size, <tt>[index%size]</tt> is taken). For example: </p>
211    <pre>
212      // static interface
213      const G4long* table_entry;
214      table_entry = HepRandom::getTheSeeds();
215      // it returns a pointer `table_entry' to the local SeedTable
216      // at the current `index' position. The couple of seeds
217      // accessed represents the current `status' of the engine itself !
218      ...
219      G4int index=n;
220      G4long seeds[2];
221      HepRandom::setTheSeeds(seeds,index);
222      // sets the new `index' for seeds and modify the values inside
223      // the local SeedTable at the `index' position. If the index
224      // is not specified, the current index in the table is considered.
225      ...
226      </pre>
227    <p>The <tt>setSeed()</tt> method resets the current `status' of the engine to the original
228    seeds stored in the static table of seeds in <i>HepRandom</i>, at the specified index. </p>
229  </li>
230</ul>
231
232<p>Except for the <i>RanecuEngine</i>, for which the internal status is represented by
233just a couple of longs, all the other engines have a much more complex representation of
234their internal status, which currently can be obtained only through the methods <tt>saveStatus()</tt>,
235<tt>restoreStatus()</tt> and <tt>showStatus()</tt>, which can also be statically called
236from <i>HepRandom</i>. The status of the generator is needed for example to be able to
237reproduce a run or an event in a run at a given stage of the simulation. </p>
238
239<p><i>RanecuEngine</i> is probably the most suitable engine for this kind of operation,
240since its internal status can be fetched/reset by simply using <tt>getSeeds()</tt>/<tt>setSeeds()</tt>
241(<tt>getTheSeeds()</tt>/<tt>setTheSeeds()</tt> for the static interface in <i>HepRandom</i>).
242</p>
243
244<b>The static interface in the <i>HepRandom</i> class</b>
245<i>
246
247<p>HepRandom</i> a singleton class and using a <i>HepJamesRandom</i> engine as default
248algorithm for pseudo-random number generation. <i>HepRandom</i> defines a static private
249data member, <tt>theGenerator</tt>, and a set of static methods to manipulate it. By means
250of <tt>theGenerator</tt>, the user can change the underlying engine algorithm, get and set
251the seeds, and use any kind of defined random distribution. The static methods <tt>setTheSeed()</tt>
252and <tt>getTheSeed()</tt> will set and get respectively the `initial' seed to the main
253engine used by the static generator. For example: </p>
254
255<pre>
256      HepRandom::setTheSeed(seed);  // to change the current seed to 'seed'
257      int startSeed = HepRandom::getTheSeed();  // to get the current initial seed
258      HepRandom::saveEngineStatus();    // to save the current engine status on file
259      HepRandom::restoreEngineStatus(); // to restore the current engine to a previous
260                                        // saved configuration
261      HepRandom::showEngineStatus();    // to display the current engine status to stdout
262      ...
263      int index=n;
264      long seeds[2];
265      HepRandom::getTheTableSeeds(seeds,index);
266        // fills `seeds' with the values stored in the global
267        // seedTable at position `index'
268 </pre>
269
270<p>Only one random engine can be active at a time, the user can decide at any time to
271change it, define a new one (if not done already) and set it. For example: </p>
272
273<pre>
274      RanecuEngine theNewEngine;
275      HepRandom::setTheEngine(&amp;theNewEngine);
276       ...
277 </pre>
278
279<p>or simply setting it to an old instantiated engine (the old engine status is kept and
280the new random sequence will start exactly from the last one previously interrupted). For
281example: </p>
282
283<pre>
284      HepRandom::setTheEngine(&amp;myOldEngine);
285 </pre>
286
287<p>Other static methods defined in this class are:
288
289<ul>
290  <li><tt>void setTheSeeds(const G4long* seeds, G4int)</tt> </li>
291  <li><tt>const G4long* getTheSeeds()</tt><p>To set/get an array of seeds for the generator,
292    in the case of a <i>RanecuEngine</i> this corresponds also to set/get the current status
293    of the engine. </p>
294  </li>
295  <li><tt>HepRandomEngine* getTheEngine()</tt><p>To get a pointer to the current engine used
296    by the static generator. </p>
297  </li>
298</ul>
299
300<b><i>HEPRandom</i> distributions</b>
301
302<p>A distribution-class can collect different algorithms and different calling sequences
303for each method to define distribution parameters or range-intervals; it also collects
304methods to fill arrays, of specified size, of random values, according to the
305distribution. This class collects either static and not static methods. A set of
306distribution classes are defined in <i>HEPRandom</i>. Here is the description of some of
307them:
308
309<ul>
310  <li><i>RandFlat</i><p>Class to shoot flat random values (integers or double) within a
311    specified interval. The class provides also methods to shoot just random bits. </p>
312  </li>
313  <li><i>RandExponential</i><p>Class to shoot exponential distributed random values, given a
314    mean (default mean = 1) </p>
315  </li>
316  <li><i>RandGauss</i><p>Class to shoot Gaussian distributed random values, given a mean
317    (default = 0) or specifying also a deviation (default = 1). Gaussian random numbers are
318    generated two at the time, so every other time a number is shot, the number returned is
319    the one generated the time before. </p>
320  </li>
321  <li><i>RandBreitWigner</i><p>Class to shoot numbers according to the Breit-Wigner
322    distribution algorithms (plain or mean^2). </p>
323  </li>
324  <li><i>RandPoisson</i><p>Class to shoot numbers according to the Poisson distribution, given
325    a mean (default = 1) (Algorithm taken from ``W.H.Press et al., Numerical Recipes in C,
326    Second Edition''). </p>
327  </li>
328</ul>
329
330<hr>
331<a name="3.2.3">
332
333<h2>3.2.3 The <i>HEPNumerics</i> module</h2>
334</a>
335
336<p>A set of classes implementing numerical algorithms has been developed in Geant4. Most
337of the algorithms and methods have been implemented mainly based on recommendations given
338in the books:
339
340<ul>
341  <li>B.H. Flowers, ``An introduction to Numerical Methods In C++'', Claredon Press, Oxford
342    1995. </li>
343  <li>M. Abramowitz, I. Stegun, ``Handbook of mathematical functions'', DOVER Publications
344    INC, New York 1965 ; chapters 9, 10, and 22. </li>
345</ul>
346
347<p>This set of classes includes:
348
349<ul>
350  <li><i>G4ChebyshevApproximation</i><p>Class creating the Chebyshev approximation for a
351    function pointed by fFunction data member. The Chebyshev polynomial approximation provides
352    an efficient evaluation of the minimax polynomial, which (among all polynomials of the
353    same degree) has the smallest maximum deviation from the true function. </p>
354  </li>
355  <li><i>G4DataInterpolation</i><p>Class providing methods for data interpolations and
356    extrapolations: Polynomial, Cubic Spline, ... </p>
357  </li>
358  <li><i>G4GaussChebyshevQ</i> </li>
359  <li><i>G4GaussHermiteQ</i> </li>
360  <li><i>G4GaussJacobiQ</i> </li>
361  <li><i>G4GaussLaguerreQ</i><p>Classes implementing the Gauss-Chebyshev, Gauss-Hermite,
362    Gauss-Jacobi, Gauss-Laguerre and Gauss-Legendre quadrature methods. Roots of orthogonal
363    polynomials and corresponding weights are calculated based on iteration method (by
364    bisection Newton algorithm). </p>
365  </li>
366  <li><i>G4Integrator</i><p>Template class collecting integrator methods for
367    generic functions (Legendre, Simpson, Adaptive Gauss, Laguerre, Hermite,
368    Jacobi). </p>
369  </li>
370  <li><i>G4SimpleIntegration</i><p>Class implementing simple numerical methods (Trapezoidal,
371    MidPoint, Gauss, Simpson, Adaptive Gauss, for integration of functions with signature:
372    double f(double). </p>
373  </li>
374</ul>
375
376<hr>
377<a name="3.2.4">
378
379<h2>3.2.4 General management classes</h2>
380</a>
381
382<p>The `global' category defines also a set of `utility' classes generally used within the
383kernel of Geant4. These classes include:
384
385<ul>
386  <li><i>G4Allocator</i><p>A class for fast allocation of objects to the heap through paging
387    mechanism. It's meant to be used by associating it to the object to be allocated and
388    defining for it <tt>new</tt> and <tt>delete</tt> operators via <tt>MallocSingle()</tt> and
389    <tt>FreeSingle()</tt> methods of <i>G4Allocator</i>. </p>
390  </li>
391  <li><i>G4ReferenceCountedHandle</i><p>Template class acting as a smart pointer and
392    wrapping the type to be counted. It performs the reference counting during the life-time
393    of the counted object.</p>
394  </li>
395  <li><i>G4FastVector</i><p>Template class defining a vector of pointers, not performing
396    boundary checking.</p>
397  </li>
398  <li><i>G4PhysicsVector</i><p>Defines a physics vector which has values of energy-loss,
399    cross-section, and other physics values of a particle in matter in a given range of the
400    energy, momentum, etc. This class serves as the base class for a vector having various
401    energy scale, for example like 'log' (<i>G4PhysicsLogVector</i>) 'linear' (<i>G4PhysicsLinearVector</i>),
402    'free' (<i>G4PhysicsFreeVector</i>), etc. </p>
403  </li>
404  <li><i>G4LPhysicsFreeVector</i><p>Implements a free vector for low energy physics
405    cross-section data. A subdivision method is used to find the energy|momentum bin. </p>
406  </li>
407  <li><i>G4PhysicsOrderedFreeVector</i><p>A physics ordered free vector inherits from <i>G4PhysicsVector</i>.
408    It provides, in addition, a method for the user to insert energy/value pairs in sequence.
409    Methods to retrieve the max and min energies and values from the vector are also provided.
410    </p>
411  </li>
412  <li><i>G4Timer</i><p>Utility class providing methods to measure elapsed user/system process
413    time.<br>
414    Uses <tt>&lt;sys/times.h&gt;</tt> and <tt>&lt;unistd.h&gt;</tt> - POSIX.1. </p>
415  </li>
416  <li><i>G4UserLimits</i><p>Class collecting methods for get and set any kind of step
417    limitation allowed in Geant4. </p>
418  </li>
419  <li><i>G4UnitsTable</i><p>Placeholder for the system of units in Geant4. </p>
420  </li>
421</ul>
422
423<p>
424<table>
425<tr><td valign=top><a name="CLHEP-ref">[1]</a>
426<td><a href="http://cern.ch/clhep/manual/RefGuide">
427    cern.ch/clhep/manual/RefGuide</a>.
428<tr><td valign=top><a name="CLHEP-use">[2]</a>
429<td><a href="http://cern.ch/clhep/manual/UserGuide">
430    cern.ch/clhep/manual/UserGuide</a>.
431<tr><td valign=top><a name="Random-doc">[3]</a>
432<td><a href="http://cern.ch/wwwasd/geant/geant4_public/Random.html">
433    cern.ch/wwwasd/geant/geant4_public/Random.html</a>.
434</table>
435<P>
436
437<hr>
438<i><a HREF="../../../../Authors/html/subjectsToAuthors.html">
439
440<p>About the authors</a></i> </p>
441</body>
442</html>
Note: See TracBrowser for help on using the repository browser.