[904] | 1 | <!-- ******************************************************** --> |
---|
| 2 | <!-- Docbook Version: For Toolkit Developers Guide --> |
---|
| 3 | <!-- ******************************************************** --> |
---|
| 4 | |
---|
| 5 | <!-- ******************* Section (Level#1) ****************** --> |
---|
| 6 | <sect1 id="sect.DsgnFuncGlobUsg"> |
---|
| 7 | <title> |
---|
| 8 | Global Usage |
---|
| 9 | </title> |
---|
| 10 | |
---|
| 11 | <!-- ******************* Section (Level#2) ****************** --> |
---|
| 12 | <sect2 id="sect.DsgnFuncGlobUsg.DsgPhlsp"> |
---|
| 13 | <title> |
---|
| 14 | Design Philosophy |
---|
| 15 | </title> |
---|
| 16 | |
---|
| 17 | <para> |
---|
| 18 | The global category covers the system of units, constants, numerics and |
---|
| 19 | random number handling. It can be considered a place-holder for |
---|
| 20 | "general purpose" classes used by all categories defined in Geant4. |
---|
| 21 | No back-dependencies to other Geant4 categories affect the "global" |
---|
| 22 | domain. There are direct dependencies of the global category on external |
---|
| 23 | packages, such as CLHEP, STL, and miscellaneous system utilities. |
---|
| 24 | </para> |
---|
| 25 | |
---|
| 26 | <para> |
---|
| 27 | Within the management sub-category are ``utility'' classes generally used |
---|
| 28 | within the Geant4 kernel. They are, for the most part, uncorrelated |
---|
| 29 | with one another and include: |
---|
| 30 | |
---|
| 31 | <itemizedlist spacing="compact"> |
---|
| 32 | <listitem><para> |
---|
| 33 | <emphasis role="italic">G4Allocator</emphasis> |
---|
| 34 | </para></listitem> |
---|
| 35 | <listitem><para> |
---|
| 36 | <emphasis role="italic">G4FastVector</emphasis> |
---|
| 37 | </para></listitem> |
---|
| 38 | <listitem><para> |
---|
| 39 | <emphasis role="italic">G4ReferenceCountedHandle</emphasis> |
---|
| 40 | </para></listitem> |
---|
| 41 | <listitem><para> |
---|
| 42 | <emphasis role="italic">G4PhysicsVector, G4LPhysicsFreeVector, |
---|
| 43 | G4PhysicsOrderedFreeVector</emphasis> |
---|
| 44 | </para></listitem> |
---|
| 45 | <listitem><para> |
---|
| 46 | <emphasis role="italic">G4Timer</emphasis> |
---|
| 47 | </para></listitem> |
---|
| 48 | <listitem><para> |
---|
| 49 | <emphasis role="italic">G4UserLimits</emphasis> |
---|
| 50 | </para></listitem> |
---|
| 51 | <listitem><para> |
---|
| 52 | <emphasis role="italic">G4UnitsTable</emphasis> |
---|
| 53 | </para></listitem> |
---|
| 54 | </itemizedlist> |
---|
| 55 | </para> |
---|
| 56 | |
---|
| 57 | <para> |
---|
| 58 | A general description of these classes is given in section 3.2 of the |
---|
| 59 | Geant4 User's Guide for Application Developers. |
---|
| 60 | </para> |
---|
| 61 | |
---|
| 62 | <para> |
---|
| 63 | In applications where it is necessary to generate random numbers (normally |
---|
| 64 | from the same engine) in many different methods and parts of the program, it |
---|
| 65 | is highly desirable not to rely on or require knowledge of the global objects |
---|
| 66 | instantiated. By using static methods via a unique generator, the randomness |
---|
| 67 | of a sequence of numbers is best assured. Hence the use of a static generator |
---|
| 68 | has been introduced in the original design of HEPRandom as a project |
---|
| 69 | requirement in Geant4. |
---|
| 70 | </para> |
---|
| 71 | |
---|
| 72 | </sect2> |
---|
| 73 | |
---|
| 74 | <!-- ******************* Section (Level#2) ****************** --> |
---|
| 75 | <sect2 id="sect.DsgnFuncGlobUsg.ClassDsg"> |
---|
| 76 | <title> |
---|
| 77 | Class Design |
---|
| 78 | </title> |
---|
| 79 | |
---|
| 80 | <para> |
---|
| 81 | Analysis and design of the HEPRandom module have been achieved following |
---|
| 82 | the Booch Object-Oriented methodology. Some of the original design |
---|
| 83 | diagrams in Booch notation are reported below. |
---|
| 84 | <xref linkend="fig.DsgnFuncGlobUsg_1" /> |
---|
| 85 | is a general picture of the static class diagram. |
---|
| 86 | |
---|
| 87 | <itemizedlist spacing="compact"> |
---|
| 88 | <listitem><para> |
---|
| 89 | <emphasis role="bold">HepRandomEngine</emphasis> - |
---|
| 90 | abstract class defining the interface for each Random engine. Its pure |
---|
| 91 | virtual methods must be defined by its subclasses representing the |
---|
| 92 | concrete Random engines. |
---|
| 93 | </para></listitem> |
---|
| 94 | <listitem><para> |
---|
| 95 | <emphasis role="bold">HepJamesRandom</emphasis> - |
---|
| 96 | class inheriting from HepRandomEngine and defining a flat random number |
---|
| 97 | generator according to the algorithm described in |
---|
| 98 | "F.James, Comp.Phys.Comm. 60 (1990) 329". This class is instantiated by |
---|
| 99 | default as the default random engine. |
---|
| 100 | </para></listitem> |
---|
| 101 | <listitem><para> |
---|
| 102 | <emphasis role="bold">DRand48Engine</emphasis> - |
---|
| 103 | class inheriting from HepRandomEngine and defining a flat random number |
---|
| 104 | generator according to the drand48() and srand48() system functions from |
---|
| 105 | the C standard library. |
---|
| 106 | </para></listitem> |
---|
| 107 | <listitem><para> |
---|
| 108 | <emphasis role="bold">RandEngine</emphasis> - |
---|
| 109 | class inheriting from HepRandomEngine and defining a flat random number |
---|
| 110 | generator according to the rand() and srand() system functions from the |
---|
| 111 | C standard library. |
---|
| 112 | </para></listitem> |
---|
| 113 | <listitem><para> |
---|
| 114 | <emphasis role="bold">RanluxEngine</emphasis> - |
---|
| 115 | class inheriting from HepRandomEngine and defining a flat random number |
---|
| 116 | generator according to the algorithm described in |
---|
| 117 | "F.James, Comp.Phys.Comm. 60 (1990) 329-344" and originally implemented |
---|
| 118 | in FORTRAN 77 as part of the MATHLIB HEP library. It provides 5 different |
---|
| 119 | "luxury" levels [0..4]. |
---|
| 120 | </para></listitem> |
---|
| 121 | <listitem><para> |
---|
| 122 | <emphasis role="bold">RanecuEngine</emphasis> - |
---|
| 123 | class inheriting from HepRandomEngine and defining a flat random number |
---|
| 124 | generator according to the algorithm RANECU originally written in |
---|
| 125 | FORTRAN 77 as part of the MATHLIB HEP library. It uses a table of seeds |
---|
| 126 | which provides uncorrelated couples of seed values. |
---|
| 127 | </para></listitem> |
---|
| 128 | <listitem><para> |
---|
| 129 | <emphasis role="bold">HepRandom</emphasis> - |
---|
| 130 | the main class collecting all the methods defining the different random |
---|
| 131 | generators applied to HepRandomEngine. It is a singleton class which all |
---|
| 132 | the distribution classes derive from. This singleton is instantiated by |
---|
| 133 | default. |
---|
| 134 | </para></listitem> |
---|
| 135 | <listitem><para> |
---|
| 136 | <emphasis role="bold">RandFlat</emphasis> - |
---|
| 137 | distribution class for flat random number generation. It also provides |
---|
| 138 | methods to fill an array of flat random values, given its size or shoot |
---|
| 139 | bits. |
---|
| 140 | </para></listitem> |
---|
| 141 | <listitem><para> |
---|
| 142 | <emphasis role="bold">RandExponential</emphasis> - |
---|
| 143 | distribution class defining exponential random number distribution, given |
---|
| 144 | a mean. It also provides a method to fill an array of flat random values, |
---|
| 145 | given its size. |
---|
| 146 | </para></listitem> |
---|
| 147 | <listitem><para> |
---|
| 148 | <emphasis role="bold">RandGauss</emphasis> - |
---|
| 149 | distribution class defining Gauss random number distribution, given a |
---|
| 150 | mean or specifying also a deviation. It also provides a method to fill |
---|
| 151 | an array of flat random values, given its size. |
---|
| 152 | </para></listitem> |
---|
| 153 | <listitem><para> |
---|
| 154 | <emphasis role="bold">RandBreitWigner</emphasis> - |
---|
| 155 | distribution class defining the Breit-Wigner random number distribution. |
---|
| 156 | It also provides a method to fill an array of flat random values, given |
---|
| 157 | its size. |
---|
| 158 | </para></listitem> |
---|
| 159 | <listitem><para> |
---|
| 160 | <emphasis role="bold">RandPoisson</emphasis> - |
---|
| 161 | distribution class defining Poisson random number distribution, given a |
---|
| 162 | mean. It also provides a method to fill an array of flat random values, |
---|
| 163 | given its size. |
---|
| 164 | </para></listitem> |
---|
| 165 | </itemizedlist> |
---|
| 166 | |
---|
| 167 | <figure id="fig.DsgnFuncGlobUsg_1"> |
---|
| 168 | <title> |
---|
| 169 | HEPRandom module |
---|
| 170 | </title> |
---|
| 171 | <mediaobject> |
---|
| 172 | <imageobject role="fo"> |
---|
[921] | 173 | <imagedata fileref="./AllResources/OOAnalysisDesign/GlobalUsage/classDgmRandom.jpg" |
---|
| 174 | format="JPG" contentwidth="10.0cm" align="center" /> |
---|
[904] | 175 | </imageobject> |
---|
| 176 | <imageobject role="html"> |
---|
[921] | 177 | <imagedata fileref="./AllResources/OOAnalysisDesign/GlobalUsage/classDgmRandom.jpg" |
---|
[1208] | 178 | format="JPG" contentwidth="120%" align="center" /> |
---|
[904] | 179 | </imageobject> |
---|
| 180 | </mediaobject> |
---|
| 181 | </figure> |
---|
| 182 | </para> |
---|
| 183 | |
---|
| 184 | <para> |
---|
| 185 | <xref linkend="fig.DsgnFuncGlobUsg_2" /> is a dynamic object diagram illustrating the |
---|
| 186 | situation when a single random number is thrown by the static generator |
---|
| 187 | according to one of the available distributions. Only one engine is |
---|
| 188 | assumed to active at a time. |
---|
| 189 | |
---|
| 190 | <figure id="fig.DsgnFuncGlobUsg_2"> |
---|
| 191 | <title> |
---|
| 192 | Shooting via the generator |
---|
| 193 | </title> |
---|
| 194 | <mediaobject> |
---|
| 195 | <imageobject role="fo"> |
---|
[921] | 196 | <imagedata fileref="./AllResources/OOAnalysisDesign/GlobalUsage/ObjDiagStat.jpg" |
---|
| 197 | format="JPG" contentwidth="10.0cm" align="center" /> |
---|
[904] | 198 | </imageobject> |
---|
| 199 | <imageobject role="html"> |
---|
[921] | 200 | <imagedata fileref="./AllResources/OOAnalysisDesign/GlobalUsage/ObjDiagStat.jpg" |
---|
[1208] | 201 | format="JPG" contentwidth="120%" align="center" /> |
---|
[904] | 202 | </imageobject> |
---|
| 203 | </mediaobject> |
---|
| 204 | </figure> |
---|
| 205 | </para> |
---|
| 206 | |
---|
| 207 | <para> |
---|
| 208 | <xref linkend="fig.DsgnFuncGlobUsg_3" /> illustrates a random number being thrown by |
---|
| 209 | explicitly specifying an engine which can be shared by many distribution |
---|
| 210 | objects. The static interface is skipped here. |
---|
| 211 | |
---|
| 212 | <figure id="fig.DsgnFuncGlobUsg_3"> |
---|
| 213 | <title> |
---|
| 214 | Shooting via distribution objects |
---|
| 215 | </title> |
---|
| 216 | <mediaobject> |
---|
| 217 | <imageobject role="fo"> |
---|
[921] | 218 | <imagedata fileref="./AllResources/OOAnalysisDesign/GlobalUsage/ObjDiagDist.jpg" |
---|
| 219 | format="JPG" contentwidth="10.0cm" align="center" /> |
---|
[904] | 220 | </imageobject> |
---|
| 221 | <imageobject role="html"> |
---|
[921] | 222 | <imagedata fileref="./AllResources/OOAnalysisDesign/GlobalUsage/ObjDiagDist.jpg" |
---|
[1208] | 223 | format="JPG" contentwidth="120%" align="center" /> |
---|
[904] | 224 | </imageobject> |
---|
| 225 | </mediaobject> |
---|
| 226 | </figure> |
---|
| 227 | </para> |
---|
| 228 | |
---|
| 229 | <para> |
---|
| 230 | <xref linkend="fig.DsgnFuncGlobUsg_4" /> illustrates the situation when many |
---|
| 231 | generators are defined, each by a distribution and an engine. The static |
---|
| 232 | interface is skipped here. |
---|
| 233 | |
---|
| 234 | <figure id="fig.DsgnFuncGlobUsg_4"> |
---|
| 235 | <title> |
---|
| 236 | Shooting with arbitrary engines |
---|
| 237 | </title> |
---|
| 238 | <mediaobject> |
---|
| 239 | <imageobject role="fo"> |
---|
[921] | 240 | <imagedata fileref="./AllResources/OOAnalysisDesign/GlobalUsage/ObjDiagEng.jpg" |
---|
| 241 | format="JPG" contentwidth="10.0cm" align="center" /> |
---|
[904] | 242 | </imageobject> |
---|
| 243 | <imageobject role="html"> |
---|
[921] | 244 | <imagedata fileref="./AllResources/OOAnalysisDesign/GlobalUsage/ObjDiagEng.jpg" |
---|
[1208] | 245 | format="JPG" contentwidth="120%" align="center" /> |
---|
[904] | 246 | </imageobject> |
---|
| 247 | </mediaobject> |
---|
| 248 | </figure> |
---|
| 249 | </para> |
---|
| 250 | |
---|
| 251 | <para> |
---|
| 252 | For detailed documentation about the HEPRandom classes see the |
---|
| 253 | CLHEP Reference Guide(http://cern.ch/clhep/manual/RefGuide) |
---|
| 254 | or the CLHEP User Manua(http://cern.ch/clhep/manual/UserGuide). |
---|
| 255 | </para> |
---|
| 256 | |
---|
| 257 | <para> |
---|
| 258 | Informations written in this manual are extracted |
---|
| 259 | from the original manifesto distributed with the HEPRandom package |
---|
| 260 | (http://cern.ch/clhep/manual/UserGuide/Random/Random.html). |
---|
| 261 | </para> |
---|
| 262 | |
---|
| 263 | <!-- ******* Bridgehead ******* --> |
---|
| 264 | <bridgehead renderas='sect4'> |
---|
| 265 | HEPNumerics |
---|
| 266 | </bridgehead> |
---|
| 267 | |
---|
| 268 | <para> |
---|
| 269 | The HEPNumerics module includes a set of classes which implement numerical |
---|
| 270 | algorithms for general use in Geant4. The User's Guide |
---|
| 271 | for Application Developers contains a description of each class. Most of |
---|
| 272 | the algorithms were implemented using methods from the following books: |
---|
| 273 | |
---|
| 274 | <itemizedlist spacing="compact"> |
---|
| 275 | <listitem><para> |
---|
| 276 | B.H. Flowers, "An introduction to Numerical Methods In C++", |
---|
| 277 | Claredon Press, Oxford 1995. |
---|
| 278 | </para></listitem> |
---|
| 279 | <listitem><para> |
---|
| 280 | M. Abramowitz, I. Stegun, "Handbook of mathematical functions", |
---|
| 281 | DOVER Publications INC, New York 1965 ; chapters 9, 10, and 22. |
---|
| 282 | </para></listitem> |
---|
| 283 | </itemizedlist> |
---|
| 284 | </para> |
---|
| 285 | |
---|
| 286 | |
---|
| 287 | <!-- ******* Bridgehead ******* --> |
---|
| 288 | <bridgehead renderas='sect4'> |
---|
| 289 | HEPGeometry |
---|
| 290 | </bridgehead> |
---|
| 291 | |
---|
| 292 | <para> |
---|
| 293 | Documentation for the HEPGeometry module is provided in the CLHEP |
---|
| 294 | Reference Guide(http://cern.ch/clhep/manual/RefGuide) |
---|
| 295 | or the CLHEP User Manual(http://cern.ch/clhep/manual/UserGuide). |
---|
| 296 | </para> |
---|
| 297 | |
---|
| 298 | <!-- ******* Bridgehead ******* --> |
---|
| 299 | <bridgehead role="revisionHistory" renderas="sect4"> |
---|
| 300 | [Status of this chapter] |
---|
| 301 | </bridgehead> |
---|
| 302 | <para> |
---|
| 303 | <simplelist type="var"> |
---|
| 304 | <member> |
---|
| 305 | 01.12.02 minor update by G. Cosmo |
---|
| 306 | </member> |
---|
| 307 | <member> |
---|
| 308 | 18.06.05 introductory paragraphs added and minor grammar changes by D.H. Wright |
---|
| 309 | </member> |
---|
| 310 | <member> |
---|
| 311 | Dec. 2006 Conversion from latex to Docbook verson by K. Amako |
---|
| 312 | </member> |
---|
| 313 | </simplelist> |
---|
| 314 | </para> |
---|
| 315 | |
---|
| 316 | |
---|
| 317 | </sect2> |
---|
[1208] | 318 | </sect1> |
---|