eventgenerator/particleGun/README.md

0001 \page ExampleparticleGun Example particleGun
0002
0003  History:
0004  - 10-06-2010 : Makoto Asai - merge into one example
0005  - 13-05-2010 : Michel Maire - create as three examples
0006
0007  This example demonstrates 5 ways of the use of G4ParticleGun shooting
0008  primary particles in different cases. These are
0009  -#  uniform particle direction in a given solid angle
0010  -#  Generate several vertices and particles per event
0011  -#  Show how to sample a tabulated function (eg. energy spectrum)
0012  -#  Divergent beam in an arbitrary direction
0013  -#  Shooting primaries in spherical coordinates with rotation matrix.
0014
0015  These use cases can be chosen by a UI command
0016 ```
0017 /gunExample/selectGunAction actionID
0018 ```
0019  where <i>actionID</i> corresponds to the above cases.
0020
0021 ## Geometry construction
0022
0023  It is a simple box which represents an 'infinite' homogeneous medium.
0024
0025 ## Physics list
0026
0027 PhysicsList defines only geantino and transportation process.
0028
0029 ## Primary generator
0030
0031  There are 5 concrete primary generator action classes
0032  (PrimaryGeneratorActionN, N=0,1,2,3,4) which can be used as an independent sample
0033  code.
0034  PrimaryGeneratorAction is the class which uses and switches between these
0035  5 concrete action classes. Each concrete generator action shoots geantinoes
0036  in a distribution decribed below.
0037
0038 ### 0. Uniform particle direction in a given solid angle
0039
0040  spherical angles (alpha,psi) respective to z axis
0041  Histograms 5,6 show momentum direction in master frame.
0042
0043  See: PrimaryGeneratorAction0::GeneratePrimaries()
0044
0045 ### 1. Generate several vertices and particles per event
0046
0047  - particle 1 : a geantino uniformly randomized on a cylinder surface.
0048  - particle 2 and 3 : symetric to particle 1.
0049  In addition, time_zero of each event is randomized.
0050
0051  See: PrimaryGeneratorAction1::GeneratePrimaries()
0052
0053 ### 2. Show how to sample a tabulated function (energy spectrum)
0054
0055  Energy is sampled from a tabulated function defined in InitFunction().
0056  The function is assumed positive, linear per segment, continuous.
0057  Two sampling methods are illustrated : RejectAccept() and InverseCumul()
0058  (see Particle Data Group: pdg.lbl.gov --> Monte Carlo techniques)
0059
0060  Histogram 1 shows generated energy spectrum.
0061
0062  See: PrimaryGeneratorAction2::GeneratePrimaries()
0063
0064 ### 3. Divergent beam in an arbitrary direction with rotation matrix
0065
0066  A geantino uniformly randomized around a given direction (theta, phi).
0067  One wants to limit particle direction uniformly around this direction.
0068  First, one generates momentum direction in the master frame (eg. World).
0069  AlphaMax = opening angle around z axis.
0070  Then one rotates momentum in local frame, using rotateUz() function.
0071  RotateUz() transforms uz to newUz. It is composition of two simple rotations:
0072  theta around oy, then phi around oz (non commutative). \n
0073  See: https://proj-clhep.web.cern.ch/proj-clhep/  \n
0074  Histograms 5,6 show momentum direction in local frame.
0075
0076  See: PrimaryGeneratorAction3::GeneratePrimaries()
0077
0078 ### 4. Shooting primaries in spherical coordinates with rotation matrix
0079
0080  A geantino uniformly randomized within a spherical shell.
0081
0082  a) Vertex position
0083  One wishes to shoot uniformly within a spherical shell.
0084  One works in spherical coordinates. One uses inverse cumulative method with
0085  analytical formulae. \n
0086  Histograms 2,3,4 demonstrate uniform distribution of vertex position.
0087
0088  b) Momentum direction
0089  One wants to limit particle direction uniformly within (alphaMin, alphaMax).
0090  First, one generates momentum direction in the master frame (eg. World).
0091  Then, one rotates momentum in vertex_position frame, using rotateUz() function.
0092  RotateUz() transforms uz to ur. It is composition of two elementary rotations:
0093  theta around oy, then phi around oz (non commutative). \n
0094  See: https://proj-clhep.web.cern.ch/proj-clhep/ \n
0095
0096  Histograms 5,6 show momentum direction in vertex_position frame.
0097
0098  See: PrimaryGeneratorAction4::GeneratePrimaries()
0099
0100 ## Visualisation
0101
0102  Visualization Manager is set in the main().
0103  Initialisation of the drawing is done via the commands
0104  `/vis/..`` in the macro vis.mac. This macro is automatically read from the main
0105  in case of interactive running mode.
0106
0107 ## How to start ?
0108
0109   - Execute particleGun in 'batch' mode from macro files
0110 ```
0111 % ./particleGun   run1.mac
0112 ```
0113
0114   - Execute particleGun2 in 'interactive mode' with visualization
0115 ```
0116 % ./particleGun
0117 ....
0118 Idle>      ---> type your commands. For instance:
0119 Idle> /gunExample/selectGunAction 1
0120 Idle> /run/beamOn 10
0121 ....
0122 Idle> exit
0123 ```
0124
0125   - Macros provided in this example:
0126       - run0.mac: see above primaryGenerator, case 0
0127       - run1.mac: see above primaryGenerator, case 1
0128       - run2.mac: see above primaryGenerator, case 2
0129       - run3.mac: see above primaryGenerator, case 3
0130       - run4.mac: see above primaryGenerator, case 4
0131       - particleGun.in: macro used in Geant4 testing (similar to run0.mac)
0132
0133 ## Histograms
0134
0135   particleGun produces several 1D histograms which are saved as
0136   particleGun.root by default.
0137
0138     - 1 : energy spectrum dN/dE = f(E)
0139     - 2 : vertex position: radial distr dN/dv = f(r)
0140     - 3 : vertex position: cos(theta)
0141     - 4 : vertex position: phi
0142     - 5 : particle direction in local frame: cos(alpha)
0143     - 6 : particle direction in local frame: psi
0144
0145   Please note that histogram 1 will be filled only if you use
0146   PrimaryGeneratorAction2, histos 5,6 with PrimaryGeneratorAction0 and 3
0147   and 2 through 6 will be filled with PrimaryGeneratorAction4.
0148
0149   The histograms are managed by the HistoManager class and its messenger.
0150   The histos can be individually activated with the command :
0151 ```
0152 /analysis/h1/set id nbBins  valMin valMax unit
0153 ```
0154   where unit is the desired unit for the histo (MeV or keV, deg or mrad, etc..)
0155
0156   One can control the name of the histograms file with the command:
0157 ```
0158 /analysis/h1/setFileName  name  (default particleGun)
0159 ```
0160
0161    It is possible to choose the format of the histogram file : root (default),
0162    xml, csv by setting default file type in HistoManager::Book().
0163
0164    It is also possible to print selected histograms on an ascii file:
0165 ```
0166 /analysis/h1/setAscii id
0167 ```
0168    All selected histos will be written on a file name.ascii (default gunExample)