Upload
raj
View
2.196
Download
31
Tags:
Embed Size (px)
Citation preview
24/03/2012 Geant4 GPS Users Manual
1/26reat.space.qinetiq.com/gps/new_gps_sum_files/gps_sum.htm
Geant4 General Particle Source Users Manual
1. Introduction
The G4GeneralParticleSource (GPS) is part of the Geant4 toolkit for Monte-Carlo, high-energy particle transport.
Specifically, it allows the specifications of the spectral, spatial and angular distribution of the primary source particles.
In section 2 of this manual an overview of the GPS class is presented. Section 3 covers the instanciation GPS in anuser application, and section 4 describes the commands of GPS. Section 5 gives a number of example input file to
guide the first time user and section 6 lists the limitations and known bugs.
2. Overview
In all Monte Carlo simulations, it is necessary to have some simple way of specifying the properties of the incident
source. The GPS software allows the user to specify the energy spectrum, position distribution and direction of the
source particles. This can be done via command line, or macro based, input. The experienced user can of course
simply hard-code distributions using the methods and classes of the GPS that are described in more detail in thetechnical note [1]. In class diagram of GPS is shown in Figure 1. The G4GeneralParticleSource class can have
multiple instanciations of the G4SingleParticlesource class, each with independent positional, angular and energydistributions as well as incident particle types.
Figure 1. The class diagram of GPS.
24/03/2012 Geant4 GPS Users Manual
2/26reat.space.qinetiq.com/gps/new_gps_sum_files/gps_sum.htm
i. Position distribution
The position distribution can be defined by using several basic shapes to contain the starting positions of the
particles. The easiest source distribution to define is a point source. One could also define planar sources,where the particles emanate from circles, annuli, ellipses, squares or rectangles. There are also methods for
defining 1D or 2D accelerator beam spots. More complicated still, one can define surface or volume sources
where the input particles can be confined to either the surface of a three dimensional shape or to within its
entire volume. The four 3D shapes used within G4GeneralParticleSource are sphere, ellipsoid, cylinder andparallelepiped.
To allow easy definition of the sources, the planes and shapes are assumed to be orientated in a particulardirection to the axes (Fig 2). To allow the user more freedom he/she can supply two vectors (x’ and a vector
in the plane x’y’) to rotate the co-ordinate axes of the shape with respect to the overall co-ordinate system.
The rotation matrix is automatically calculated within G4GeneralParticleSource. The starting points of
particles are always distributed homogeneously over the 2D or 3D surfaces, although biasing can changethis.
Figure 2. An illustration of the use of rotation matrices. A cylinder is defined with its axis parallel to
the z-axis (black lines), but the definition of 2 vectors can rotate it into the frame given by x', y', z'(red lines).
As mentioned above there are five planes (circle, annulus, ellipse, square and rectangle) and fourshapes (sphere, ellipsoid, cylinder and parallelepiped) used to confine the starting positions of the input
particles.
The five planes are oriented in the x-y plane. To define a circle one gives the radius, for an annulus one givesthe inner and outer radii, and for an ellipse, a square or a rectangle one gives the half-lengths in x and y. To
rotate the plane the user can supply two rotation vectors, defining x’ and a vector in the x’-y’ plane, fromwhich the axes (x’, y’, z’) will be calculated.
A sphere can be defined simply by specifying the radius. Ellipsoids are defined by giving their half-lengths in
x, y and z. Cylinders are defined such that the axis is parallel to the z-axis, the user is therefore required togive the radius and the z half-length. Parallelepipeds are defined by giving x, y and z half-lengths, plus the
24/03/2012 Geant4 GPS Users Manual
3/26reat.space.qinetiq.com/gps/new_gps_sum_files/gps_sum.htm
angles a, q, and f (Fig 3). Supplying two vectors, as with the planes, can rotate all of these shapes.
Figure 3. The angles used in the definition of a Parallelepiped.
2. Angular distribution
The angular distribution is used to control the directions in which the particles emanate from/incident upon thesource point. In general there are three main choices, isotropic, cosine-law or user-defined. In addition there
are options for specifying parallel beam as well as diversed accelerator beams. The isotropic distribution
represents what would be seen from a uniform 4p flux. The cosine-law represents the distribution seen at a
plane from a uniform 2p flux. The user defined distribution requires the user to enter a histogram in either q
or f or both. The user can also set lower and upper limits to q and f. The user has to be careful to rotate theco-ordinate axes of the angular distribution if they have rotated the position distribution. The user can specify
user-defined distributions with respect to the surface normal of bodies instead of the co-ordinate axes. It is
also possible to bias both q and f distributions.
The direction cosines are calculated as
Px = - sin(q) cos(f)
Py = - sin(q) sin(f)
Pz = - cos(q)
So incident with zenith angle q=0 means the particle is travelling along the -z axis. It is important to
bearing this in mind when defining user-defined co-ordinates for angular distribution.
iii. Energy distribution
Using G4GeneralParticleSource the energy of the input particles can be set to follow several built in functions
or a user-defined one. The functions available are mono-energetic, linear, exponential, power-law, gaussian,bremsstrahlung, black body and cosmic diffuse gamma ray. There is also the option for the user to define a
histogram (in energy or energy per nucleon) or to give an arbitrary point-wise spectrum that can be fit with
various simple functions. The user can bias the energy distribution in order to speedup the simulation.
24/03/2012 Geant4 GPS Users Manual
4/26reat.space.qinetiq.com/gps/new_gps_sum_files/gps_sum.htm
iv. Biasing
The user can bias distributions by entering a histogram. It is the random numbers from which thequantities are picked that are biased and so one only needs a histogram from 0 to 1. Great care
must be taken when using this option, as the way a quantity is calculated will affect how the
biasing works. This will be explained further in sections 5,6. Bias histograms are entered in thesame way as other user-defined histograms.
v. User-defined histograms
The user can define histograms for several reasons: angular distributions in either q or f, energy
distributions, energy per nucleon distributions or biasing of x, y, z, q, f, or energy. Even though thereasons may be different the approach is the same. To choose a histogram the command hist/type is
used and this is explained in section 5. If one wanted to enter an angular distribution one would type
theta or phi as the argument. The histogram is loaded, one bin at a time, by using the hist/pointcommand, followed by its two arguments – the upper boundary of the bin and the weight (or area) of
the bin. Histograms are therefore differential functions.
The user has to be aware of the limitations of histograms. For example, in general q is defined between
0 and p and f is defined between 0 and 2p , so histograms defined outside of these limits may not givethe user what they want (this idiosyncrasy of G4GeneralParticleSource is expanded on in section 6)
vi. G4ParticleGun replacement functions
Certain methods are present within G4GeneralParticleSource to allow it to act as a replacement for
G4ParticleGun.
How to use it
The GPS is distributed as part of the Geant4 kernel in the "event" catagory, along side the G4ParticleGun class.
G4GeneralParticleSource is used exactly the same way as G4ParticleGun in a Geant4 application. In existing application one
can simply change yourPrimaryGeneratorAction by globally replacing "G4ParticleGun" with "G4GeneralParticleSource".
The commands
The G4GeneralParticleSource can be utilised by typing commands from the /gps command directory, or include the /gps
commands in a g4macro file.
i. Top command directory /gps
Function: Contains all the replicae G4ParticleGun commands.
/gps/particle
Format: /gps/particle <particleName>
Arguments: G4String particleName.
Function: Defines the particle type.
Default: geantino
24/03/2012 Geant4 GPS Users Manual
5/26reat.space.qinetiq.com/gps/new_gps_sum_files/gps_sum.htm
/gps/ion
Format: /gps/ion <Z A Q E>
Arguments: Integers Z (the Atomic number), A (the Atomic mass) and Q (ionic charge
in units of e). Double E the excitation energy of the ion in keV.
Function: Sets the properties of the ion. Should be used after /gps/particle ion.
/gps/List
Format: /gps/List
Arguments: None
Function: List available incident particles
Default: N/A
/gps/energy
Format: /gps/energy <energy unit>
Arguments: Double energy and a G4String unit.
Function: Sets the energy for mono-energetic sources.
Default: The default source is mono-energetic and so by default monoenergyis set to 1 MeV.
/gps/position
Format: /gps/position <X Y Z unit>
Arguments: Three doubles x, y and z plus a string giving the unit.
Function: Sets the centre co-ordinates of the source.
Default: The origin (0., 0., 0.) and the default unit is cm.
Errors: An error is flagged if the units do not belong to cm, mm, micron, etc.
/gps/direction
Format: /gps/direction <dx dy dz>
Arguments: dx, dy, dz are direction cosines
Function: set the momentum direction.
Default: The unit vector x (1., 0., 0.).
/gps/time
Format: /gps/time <t0 unit>
24/03/2012 Geant4 GPS Users Manual
6/26reat.space.qinetiq.com/gps/new_gps_sum_files/gps_sum.htm
Arguments: Double t0 and a G4String for the unit.
Function: Sets the particle time.
Default: 0 ns.
Errors: An error is flagged if the units are not ns.
/gps/polarization
Format: /gps/polarization <Px Py Pz>
Arguments: Three doubles Px, Py, Pz.
Function: Sets the polarization of the source.
/gps/number
Format: /gps/number <N>
Arguments: Integer N.
Function: Sets the number of particles to simulate.
Default: 1
/gps/verbose
Format: /gps/verbose <verbosityLevel>
Arguments: An integer verbosityLevel.
Function: This allows the user to control the amount of information printed outby the GPS code. The possible values are 0, 1 and 2. 0 is for silent running and verylittle information will be printed from the GPS. 1 is a medium level where some
limited information is printed, and 2 is the most verbose with a lot of informationprinted out including the debug arrrays.
ii. Sub command directory /gps/source
Function: Contains all the commands for specification of multiple particle sources.
/gps/source/list
Format: /gps/source/list
Arguments: none
Function: list the particle sources defined.
Default: N/A
Errors: none
/gps/source/add
24/03/2012 Geant4 GPS Users Manual
7/26reat.space.qinetiq.com/gps/new_gps_sum_files/gps_sum.htm
Format: /gps/source/add <intensity>
Arguments: G4double intensity
Function: add a new particle source with the specified intensity
Default: none
Errors: An error is flagged if intensity is ommited or negative.
/gps/source/delete
Format: /gps/source/delete <source_index>
Arguments: G4int index
Function: remove the specified particle source.
Default: none
Errors: An error is flagged if index is out of range.
/gps/source/clear
Format: /gps/source/clear
Arguments: none
Function: remove all defined particle sources.
Default: none
Errors: none.
/gps/source/show
Format: /gps/source/show
Arguments: none
Function: display the current particle source
Default: none
Errors: none
/gps/source/set
Format: /gps/source/set <source_index>
Arguments: G4int index
Function: set the specified particle source as the current one.
Default: none
24/03/2012 Geant4 GPS Users Manual
8/26reat.space.qinetiq.com/gps/new_gps_sum_files/gps_sum.htm
Errors: An error is flagged if index is out of range.
/gps/source/intensity
Format: /gps/source/intensity intensity
Arguments: G4double intensity
Function:set the inetnsity of the current particle source.
Default: none
Errors: An error is flagged if intensity is omitted or negative.
/gps/source/multiplevertex
Format: /gps/source/multiplevertex <Bool>
Arguments: G4bool Bool
Function: If true, a vertex is generated for each of the source defined. Default: false,i.e. only one vertex is generated choosing from the sources defined.
Default: false
Errors: none.
iii. Sub command directory /gps/pos
Function: Contains all the commands for specification of position
/gps/pos/type
Format: /gps/pos/type <DisType>
Arguments: G4String DisType
Function: Sets the source distribution type to Point, Beam, Plane, Surface or Volume. At themoment the capitalisation is very important, only an exact match will be recognised.
Default: Point.
Errors: An error is flagged if DisType is anything other than Point, Beam, Plane, Surface or
Volume.
/gps/pos/shape
Format: /gps/pos/shape <Shape>
Arguments: G4String Shape
Function: Sets the source shape type. For a Plane source this can be Circle, Annulus,
Ellipsoid, Square or Rectangle. For both Surface and Volume sources this can be Sphere,
24/03/2012 Geant4 GPS Users Manual
9/26reat.space.qinetiq.com/gps/new_gps_sum_files/gps_sum.htm
Ellipsoid, Cylinder or Para (parallelepiped). Again, capitalisation is very important, only an exactmatch will be recognised.
Default: NULL. The default source is a Point source and so Shape is not set to any of theabove types.
Errors: The entered string must be Circle, Annulus, Ellipse, Square, Rectangle, Sphere,
Ellipsoid, Cylinder or Para. The G4GeneralParticleSource also checks that the choice isappropriate for the distribution type i.e. a cylinder will give an error is the distribution type isPlane.
/gps/pos/centre
Format: /gps/pos/centre <X Y Z unit>
Arguments: Three doubles x, y and z plus a string giving the unit.
Function: Sets the centre co-ordinates of the source.
Default: The origin (0., 0., 0.) and the default unit is cm.
Errors: An error is flagged if the units do not belong to cm, mm, micron, etc.
/gps/pos/rot1
Format: /gps/pos/rot1 <R1x, R1y, R1z>
Arguments: Three doubles R1x, R1y, R1z.
Function: Defines the vector x’, which does not need to be a unit vector, and is used to
create the rotation matrix of the shape defined with /gps/shape. (See Fig 1 for a summary ofrotation.)
Default: The unit vector in x (1., 0., 0.).
/gps/pos/rot2
Format: /gps/pos/rot2 <R2x, R2y, R2z>
Arguments: Three doubles R2x, R2y, R2z.
Function: Defines a vector in the plane x’-y’, which does not need to be a unit vector, and isused to create the rotation matrix of the shape defined with /gps/shape. (See Fig 1 for a summary
of rotation.)
Default: The unit vector in y (0., 1., 0.).
/gps/pos/halfx
Format: /gps/pos/halfx <Halfx unit>
Arguments: Double Halfx and a G4String giving the unit.
Function: Sets the x half-length of the source.
24/03/2012 Geant4 GPS Users Manual
10/26reat.space.qinetiq.com/gps/new_gps_sum_files/gps_sum.htm
Default: Since the default source is a point, halfx is by default set to 0 cm.
Errors: An error is flagged if the units are not micron, mm, cm, m or km.
/gps/pos/halfy
Format: /gps/pos/halfy <Halfy unit>
Arguments: Double Halfy and a G4String giving the unit.
Function: Sets the y half-length of the source.
Default: Since the default source is a point, halfy is by default set to 0 cm.
Errors: An error is flagged if the units are not micron, mm, cm, m or km.
/gps/pos/halfz
Format: /gps/pos/halfz <Halfz unit>
Arguments: Double Halfz and a G4String giving the unit.
Function: Sets the z half-length of the source.
Default: Since the default source is a point, halfz is by default set to 0 cm.
Errors: An error is flagged if the units are not micron, mm, cm, m or km.
/gps/pos/radius
Format: /gps/pos/radius <Radius unit>
Arguments: Double Radius and a G4String for the unit.
Function: Sets the radius of the source or outer radius for annuli.
Default: Since the default source is a point, Radius is by default set to 0 cm.
Errors: An error is flagged if the units are not micron, mm, cm, m or km
/gps/pos/inner_radius
Format: /gps/pos/inner_radius<Radius unit>
Arguments: Double Radius and a G4String for the unit.
Function: Sets the inner radius of annular sources.
Default: 0 cm.
Errors: An error is flagged if the units are not micron, mm, cm, m or km
/gps/pos/sigmar
Format: /gps/pos/sigmar <sigma unit>
24/03/2012 Geant4 GPS Users Manual
11/26reat.space.qinetiq.com/gps/new_gps_sum_files/gps_sum.htm
Arguments: Double sigma and a G4String giving the unit.
Function: Sets the standard deviation of beam position profile in radial.
Default: 0 cm.
Errors: An error is flagged if the units are not micron, mm, cm, m or km.
To be used in conjunction with:
/gps/pos/type Beam
/gps/pos/shape Circle
/gps/pos/sigmax
Format: /gps/pos/sigmax <sigma unit>
Arguments: Double sigma and a G4String giving the unit.
Function: Sets the standard deviation of beam position profile in the x-direction (2d case)
Default: 0 cm.
Errors: An error is flagged if the units are not micron, mm, cm, m or km.
/gps/pos/sigmay
Format: /gps/pos/sigmay<sigma unit>
Arguments: Double sigma and a G4String giving the unit.
Function: Sets the standard deviation of beam position profile in the y-direction (2d case)
Default: 0 cm.
Errors: An error is flagged if the units are not micron, mm, cm, m or km.
sigmax and sigmay are to be used in conjunction with:
/gps/pos/type Beam
/gps/pos/type Square (or Rectangle)
/gps/pos/paralp
Format: /gps/pos/paralp <alpha unit>
Arguments: Double alpha and a unit.
Function: Angle formed by the y-axis and by the plane joining the centre of the faces parallel
to the z-x plane at –y and +y. (See Fig 2).
Default: Zero radians.
24/03/2012 Geant4 GPS Users Manual
12/26reat.space.qinetiq.com/gps/new_gps_sum_files/gps_sum.htm
Errors: An error is flagged if the unit is anything other than rad or deg.
/gps/pos/parthe
Format: /gps/pos/parthe <theta unit>
Arguments: Double theta and a unit.
Function: Polar angle of the line connecting the centre of the face at –z to the centre of the
face at +z. (See Fig 2).
Default: Zero radians.
Errors: An error is flagged if the unit is anything other than rad or deg.
/gps/pos/parphi
Format: /gps/pos/parphi <phi unit>
Arguments: Double phi and a unit.
Function: Azimuth angle of the line connecting the centre of the face at –z with the centre ofthe face at +z. (See Fig 2).
Default: Zero radians.
Errors: An error is flagged if the unit is anything other than rad or deg.
/gps/pos/confine
Format: /gps/pos/confine <VolName>
Arguments: G4String VolName
Function: Confines source to volume given by VolName.
Default: By default this is set to NULL.
Errors: An error is flagged if an invalid physical volume name is given.
iv. Sub command directory /gps/ang
Function: Contains all the commands for specification of direction.
/gps/ang/type
Format: /gps/ang/type <AngDis>
Arguments: G4String AngDis.
Function: Sets the angular distribution type to either isotropic (iso), cosine-law (cos), planar wave
(planar), 1-d accelerator beam (beam1d), 2-d accelerator beam (beam2d), focusing to a point(focused) or user-defined (user).
Default: Isotropic (iso).
24/03/2012 Geant4 GPS Users Manual
13/26reat.space.qinetiq.com/gps/new_gps_sum_files/gps_sum.htm
Errors: The only arguments are the ones defined.
/gps/ang/rot1
Format: /gps/ang/rot1 <AR1x, AR1y, AR1z>
Arguments: Three doubles AR1x, AR1y, AR1z.
Function: Sets the x’ vector for the angular distribution. This does not necessarily have to be a unit
vector.
Default: The unit vector x (1., 0., 0.).
/gps/ang/rot2
Format: /gps/ang/rot2 <AR2x, AR2y, AR2z>
Arguments: Three doubles AR2x, AR2y, AR2z.
Function: Defines a vector in the x’-y’ plane for the angular distribution. This does not necessarilyhave to be a unit vector.
Default: The unit vector y (0., 1., 0.).
/gps/ang/mintheta
Format: /gps/ang/mintheta <MinTheta unit>
Arguments: Double MinTheta and G4String unit.
Function: Sets a minimum value for the theta distribution.
Default: Zero radians.
Errors: An error is flagged if the units are not rad or deg.
/gps/maxtheta
Format: /gps/ang/maxtheta <MaxTheta unit>
Arguments: Double MaxTheta and G4String unit.
Function: Sets a maximum value for the theta distribution.
Default: p radians.
Errors: An error is flagged if the units are not rad or deg.
/gps/ang/minphi
Format: /gps/ang/minphi <MinPhi unit>
Arguments: Double MinPhi and a G4String unit.
24/03/2012 Geant4 GPS Users Manual
14/26reat.space.qinetiq.com/gps/new_gps_sum_files/gps_sum.htm
Function: Sets the minimum value for the phi distribution.
Default: Zero radians.
Errors: An error is flagged if the units are not rad or deg.
/gps/ang/maxphi
Format: /gps/ang/maxphi <MaxPhi unit>
Arguments: Double MaxPhi and a G4String unit.
Function: Sets the maximum value for the phi distribution.
Default: 2p radians.
Errors: An error is flagged if the units are not rad or deg.
/gps/ang/sigmar
Format: /gps/ang/sigmar <sigma unit>
Arguments: Double sigma and a G4String giving the unit.
Function: Sets the standard deviation of beam angular profile in radial.
Default: 0 rad
Errors: An error is flagged if the units are not rad or deg.
To be used in conjunction with:
/gps/ang/type beam1d
/gps/ang/sigmax
Format: /gps/ang/sigmax <sigma unit>
Arguments: Double sigma and a G4String giving the unit.
Function: Sets the standard deviation of beam angular profile in the x-direction (2d case)
Default: 0 rad.
Errors: An error is flagged if the units are not rad or deg.
/gps/ang/sigmay
Format: /gps/ang/sigmay<sigma unit>
Arguments: Double sigma and a G4String giving the unit.
Function: Sets the standard deviation of beam angular profile in the y-direction (2d case)
Default: 0 rad
24/03/2012 Geant4 GPS Users Manual
15/26reat.space.qinetiq.com/gps/new_gps_sum_files/gps_sum.htm
Errors: An error is flagged if the units are not rad or deg.
ang/sigmax and ang/sigmay are to be used in conjunction with:
/gps/ang/type beam2d
/gps/ang/focuspoint
Format: /gps/ang/focuspoint <X Y Z unit>
Arguments: Three doubles x, y and z plus a string giving the unit.
Function: Sets the focusing point.
Default: The origin (0., 0., 0.) and the default unit is cm.
Errors: An error is flagged if the units do not belong to cm, mm, micron, etc.
/gps/ang/surfnorm
Format: /gps/ang/surfnorm <Bool>
Arguments: Boolean Bool.
Function: If Bool is true then the user defined angular distribution is calculated with respect to the
surface normals, otherwise it is with respect to the co-ordinate system.
Default: False.
/gps/ang/user_coor
Format: /gps/ang/user_coor <Bool>
Arguments: .Boolean Bool.
Function: If Bool is true then the angular distribution is calculated with respect to the user definded
co-ordinate system, otherwise it is with respect to the global co-ordinate system
Default: False.
v. Sub command directory /gps/ene
Function: Contains all the commands for specification of energy.
/gps/ene/type
Format: /gps/ene/type <EnergyDis>
Arguments: G4String EnergyDis.
Function: Sets the energy distribution type. Candidates are mono-energetic (Mono), linear(Lin), power-law (Pow), exponential (Exp), Gaussian (Gauss), bremsstrahlung (Brem), black-
body (Bbody), cosmic diffuse gamma ray (Cdg), user-defined histogram (User), arbitrary point-
wise spectrum (Arb) and user-defined energy per nucleon histogram (Epn). Again, capitalisation isimportant, only strings given exactly as above will be recognised.
24/03/2012 Geant4 GPS Users Manual
16/26reat.space.qinetiq.com/gps/new_gps_sum_files/gps_sum.htm
Default: Mono.
Errors: Only Mono, Lin, Pow, Exp, Gauss, Brem, Bbody, Cdg, User, Arb and Epn are
acceptable arguments.
/gps/ene/min
Format: /gps/ene/min <emin unit>
Arguments: Double emin and a G4String unit.
Function: Sets the minimum for the energy distribution.
Default: The default source is mono-energetic and so by default emin is 0 keV.
Errors: An error is flagged if the units are not eV, keV, MeV, GeV, TeV or PeV.
/gps/ene/max
Format: /gps/ene/max <emax unit>
Arguments: Double emax and a G4String unit.
Function: Sets the maximum for the energy distribution.
Default: The default source is mono-energetic and so by default emax is 0 keV.
Errors: An error is flagged if the units are not eV, keV, MeV, GeV, TeV or PeV.
/gps/ene/mono
Format: /gps/ene/mono<monoenergy unit>
Arguments: Double monoenergy and a G4String unit.
Function: Sets the energy for mono-energetic sources.
Default: The default source is mono-energetic and so by default monoenergy is set to 1MeV.
Errors: An error is flagged if the units are not eV, keV, MeV, GeV, TeV or PeV.
/gps/ene/sigma
Format: /gps/ene/sigma <sigma unit>
Arguments: Double sigma and a G4String giving the unit.
Function: Sets the standard deviation in energy for Gaussian energy distribution.
Default: 0 keV
Errors: An error is flagged if the units are not eV, keV, MeV, GeV, TeV or PeV.
To be used in conjunction with:
24/03/2012 Geant4 GPS Users Manual
17/26reat.space.qinetiq.com/gps/new_gps_sum_files/gps_sum.htm
/gps/ene/type Gauss
/gps/ene/mono
/gps/ene/alpha
Format: /gps/ene/alpha <alpha>
Arguments: Double alpha.
Function: Sets alpha for power-law distributions of the form y = AEa, where A is a constant.
Default: Zero.
/gps/ene/temp
Format: /gps/ene/temp <temp>
Arguments: Double temp.
Function: Sets temperature (in Kelvin) for Bbody and Brem distributions. The black body
equation is
And the equation of the bremsstrahlung is
Default: Zero.
/gps/ene/ezero
Format: /gps/ene/ezero <ezero>
Arguments: Double ezero.
Function: Sets E0 for exponential distributions of the form
Default: Zero.
/gps/ene/gradient
Format: /gps/ene/gradient <gradient>
Arguments: Double gradient.
Function: Sets the gradient for linear distributions.
Default: Zero.
24/03/2012 Geant4 GPS Users Manual
18/26reat.space.qinetiq.com/gps/new_gps_sum_files/gps_sum.htm
/gps/ene/intercept
Format: /gps/ene/intercept <intercept>
Arguments: Double intercept.
Function: Sets the intercept for the linear distribution.
Default: Zero.
/gps/ene/calculate
Format: /gps/ene/calculate
Arguments: None
Function: Calculates the integral probability distribution functions for the Cdg and Bbodydistributions. In the case of the Bbody distribution, it proved very difficult to obtain an indefinite
integral of the black-body equation from which random energies could be generated. It was
decided therefore to use the black-body equation to calculate a 10,000 bin histogram, which
could then be used to obtain the integral PDF necessary to generate random energies. In the caseof the Cdg distribution, the use of a broken power-law meant that generating an integral PDF was
problematic. With this command the cosmic diffuse gamma ray equation is generated, depending
on the minimum and maximum energies given by the user, and then an integral PDF is obtainedfrom which the random energies are generated.
/gps/ene/emspec
Format: /gps/emspec <emspec>
Arguments: Boolean emspec.
Function: Toggles between energy (True) and momentum (False) spectra. This option can be
used with user-defined energy histograms or arbitrary point-wise spectra. By default it is assumedthat these are entered as distributions in terms of energy, however by specifying energyspec as
false the user can tell the GPS that they are in terms of momentum. Internally GPS will then
convert from momentum to energy distributions before generating random energies.
Default: True.
/gps/ene/diffspec
Format: /gps/ene/diffspec <diffspec>
Arguments: Boolean diffspec.
Function: Toggles between differential (True) and integral (False) spectra. This option canonly be used with user-defined arbitrary point-wise spectra. These are by default given as
differential functions, however by specifying diffspec as false the user can tell GPS that the
function they have defined is integral.
Default: True.
vi. Sub command directory /gps/hist
24/03/2012 Geant4 GPS Users Manual
19/26reat.space.qinetiq.com/gps/new_gps_sum_files/gps_sum.htm
Function: Contains all the commands for specification of histograms.
/gps/hist/type
Format: /gps/hist/type <HistType>
Arguments: G4String HistType.
Function: Sets the histogram type. Choices are bias x, y, z, angle_q (t), angle_ f (p),
position_q (pt), position_ f (pp),energy (e) (biasx, biasy, biasz, biast, biasp, biaspt,
biaspp, biase) or for user-defined histograms: theta, phi, energy, arb, epn.
Default: biasx.
Errors: Only biasx, biasy, biasz, biast, biasp, biaspt, biaspp, biase, theta, phi, energy,arb and epn are acceptable arguments.
/gps/hist/point
Format: /gps/histpoint <Ehi Weight>
Arguments: Two doubles Ehi, Weight.
Function: Allows the user to define a histogram bin, or a data pair. Note: Ehi should
be in Geant4 default units, i.e. MeV for energy and Rad for angle. Also please note therestrictions specified in section 6(i) below
/gps/hist/inter
Format: /gps/hist/inter <int>
Arguments: G4String int.
Function: Sets arbitrary interpolation type. This can be either linear (Lin), logarithmic
(Log), exponential (Exp) or cubic spline (Spline).
Default: NULL
Errors: Only Lin, Log, Exp and Spline are acceptable arguments.
/gps/hist/reset
Format: /gps/hist/reset<HistType>
Arguments: G4String HistType.
Function: Re-sets the histogram defined. Choices are bias x, y, z, angle_q (t), angle_
f (p), position_q (pt), position_ f (pp),energy (e) (biasx, biasy, biasz, biast, biasp, biaspt,
biaspp, biase) or for user-defined histograms: theta, phi, energy, arb, epn.
Default: biasx.
Errors: Only biasx, biasy, biasz, biast, biasp, biaspt, biaspp, biase, theta, phi, energy,
24/03/2012 Geant4 GPS Users Manual
20/26reat.space.qinetiq.com/gps/new_gps_sum_files/gps_sum.htm
arb and epn are acceptable arguments.
vii. Command Summary
Command Arguments and argumentrestrictions
Command function andrestrictions
/gps/particle <particleName> G4String particleName. Defines the particle type.
/gps/ion <Z A Q E> Integers Z (the Atomic number), A (the Atomic mass)and Q (ionic charge in units of e). Double E theexcitation energy of the ion in keV.
Sets the properties of the ion. Should be used after/gps/particle ion.
/gps/List None List available incident particles
/gps/energy <energy unit> Double energy and a G4String unit. Sets the energy for mono-energetic sources.
/gps/position <X Y Z unit> Three doubles x, y and z plus a string giving the unit. Sets the centre co-ordinates of the source.
/gps/direction <dx dy dz> dx, dy, dz are direction cosines set the momentum direction.
/gps/time <t0 unit> Double t0 and a G4String for the unit. Sets the particle time.
/gps/polarization <Px Py Pz> Three doubles Px, Py, Pz. Sets the polarization of the source.
/gps/number <N> Integer N. Sets the number of particles to simulate.
/gps/verbose <verbosityLevel> An integer verbosityLevel. This allows the user to control the amount of informationprinted out by the GPS code.
/gps/source/list none list the particle sources defined.
/gps/source/add <intensity> G4double intensity add a new particle source with the specified intensity
gps/source/delete <source_index> G4int index remove the specified particle source.
/gps/source/clear none remove all defined particle sources.
/gps/source/show none display the current particle source
/gps/source/set <source_index> G4int index set the specified particle source as the current one.
/gps/source/multiplevertex G4bool true for simulaneous generation mutiple vertices
/gps/source/intensity <intensity> G4double intensity reset the current source to the specified intensity
/gps/pos/type <DisType> G4String DisType. Can only be "Point", "Plane",
"Beam", "Surface" or "Volume".
Sets the source positional distribution type.
/gps/pos/shape <Shape> G4String Shape. Limited to "Circle", "Annulus",
"Ellipse", "Square", "Rectangle", "Sphere",
"Ellipsoid", "Cylinder" or "Para".
Sets the source shape type. For a Plane this can
be Circle, Ell ipse, Square or Rectangle. For both
Surface or Volume sources this can be Sphere,
Ellipsoid, Cylinder or Para.
/gps/pos/centre <X Y Z unit> G4doubles X, Y, Z and G4string unit. The units
can only be micron, mm, cm ,m or km.
Sets the centre co-ordinates of the source.
/gps/pos/rot1 <R1x, R1y, R1z> G4doubles R1x, R1y, R1z. Defines the vector x’, which does not need to be
a unit vector, and is used to create the rotation
matrix of the shape defined with /gps/shape.
/gps/pos/rot2 <R2x, R2y, R2z> G4doubles R2x, R2y, R2z. Defines a vector in the x’y’, which does not need
to be a unit vector, and is used to create the
rotation matrix of the shape defined with
/gps/shape.
24/03/2012 Geant4 GPS Users Manual
21/26reat.space.qinetiq.com/gps/new_gps_sum_files/gps_sum.htm
/gps/pos/halfx <Halfx unit> G4double Halfx and G4String unit. The units can
only be micron, mm, cm, m or km.
Sets the half-length in x of the source.
/gps/pos/halfy <Halfy unit> G4double Halfy and G4String unit. The units can
only be micron, mm, cm, m or km.
Sets the half-length in y of the source.
/gps/pos/halfz <Halfz unit> G4double Halfz and G4String unit. The units can
only be micron, mm, cm, m or km.
Sets the half-length in z of the source.
/gps/pos/radius <Radius unit> G4double Radius and G4String unit. The units
can only be micron, mm, cm, m or km.
Sets the radius of the source or the outer radius
for annuli.
/gps/pos/inner_radius <Radius unit> G4double Radius and G4String unit. The units
can only be micron, mm, cm, m or km.
Sets the inner radius for annuli.
/gps/pos/sigmar <sigma unit> Double sigma and a G4String giving the unit. Sets the standard deviation of beam position profile inradial.
/gps/pos/sigmax<sigma unit> Double sigma and a G4String giving the unit. Sets the standard deviation of beam position profile in x-direction.
/gps/pos/sigmay<sigma unit> Double sigma and a G4String giving the unit. Sets the standard deviation of beam position profile in y-direction.
/gps/pos/paralp <alpha unit> G4double alpha and a G4String unit. The units
can only be deg or rad.
Used with a Parallelepiped. The angle formed by
the y-axis and by the plane joiing the centre of
the faces parallel to the zx plane at –y and +y.
/gps/pos/parthe <theta unit> G4double theta and a G4String unit. The units
can only be deg or rad.
Used with a Parallelepiped. Polar angle of the
line connecting the centre of the face at –z to the
centre of the face at +z.
/gps/pos/parphi <phi unit> G4double phi and a G4String unit. The units can
only be deg or rad.
Used with a Parallelepiped. The azimuth angle
of the line connecting the centre of the face at –z
with the centre of the face at +z.
/gps/pos/confine <VolName> G4String VolName. Has to be a valid physical
volume name.
Allows the user to confine the source to the
physical volume VolName.
/gps/ang/type <AngDis> G4String AngDis. The arguments are limited to
"iso", "cos","plannar","beam1d","beam2d",
"focused" and "user"..
Sets the angular distribution type to either
isotropic, cosine-law or user-defined.
/gps/ang/rot1 <AR1x, AR1y, AR1z> G4doubles AR1x, AR1y, AR1z. Sets the x’ vector for the angular distribution and
is not necessarily a unit vector.
/gps/ang/rot2 <AR2x, AR2y, AR2z> G4doubles AR2x, AR2y, AR2z. Defines a vector in the plane x’y’ for the angular
distribution, which does not necessarily have to
be a unit vector.
/gps/ang/mintheta <MinTheta unit> G4double MinTheta and G4String unit. Units can
be deg or rad.
Sets a minimum value for the theta distribution.
/gps/ang/maxtheta <MaxTheta unit> G4double MaxTheta and G4String unit. Units
can be deg or rad.
Sets a maximum value for the theta distribution.
/gps/ang/minphi <MinPhi unit> G4double MinPhi and G4String unit. Units can
be deg or rad.
Sets a minimum value for the phi distribution.
/gps/ang/maxphi <MaxPhi unit> G4double MaxPhi and G4String unit. Units can
be deg or rad.
Sets a maximum value for the phi distribution.
/gps/ang/sigmar <sigma unit> Double sigma and a G4String giving the unit. Sets the standard deviation of beam directional profile inradial.
/gps/ang/sigmax<sigma unit> Double sigma and a G4String giving the unit. Sets the standard deviation of beam directional profile inx-direction.
/gps/ang/sigmay<sigma uniit> Double sigma and a G4String giving the unit. Sets the standard deviation of beam directional profile iny-direction.
24/03/2012 Geant4 GPS Users Manual
22/26reat.space.qinetiq.com/gps/new_gps_sum_files/gps_sum.htm
/gps/ang/focuspoint <x,y,z,unit> G4doubles X, Y, Z and G4string unit. The units
can only be micron, mm, cm ,m or km.
Set the focusing point for the beam
/gps/ang/user_coor <Bool> Boolean Bool.
If Bool is true then the angular distribution is calculatedwith respect to the user definded co-ordinate system,otherwise it is with respect to the global co-ordinatesystem
/gps/ang/surfnorm <Bool> Bool Bool. Allows user to choose whether angular
distributions are with respect to the co-ordinate
system or surface normals for user-defined
distributions.
/gps/ene/type <EnergyDis> G4String EnergyDis. The only valid arguments
are "Mono", "Lin", "Pow", "Exp", "Gauss", "Brem",
"Bbody", "Cdg", "User", "Arb" or "Epn".
Sets the energy distribution type.
/gps/ene/min <emin unit> G4double emin and G4String unit. The units can
be eV, keV, MeV, GeV, TeV or PeV.
Sets the minimum for the energy distribution.
/gps/ene/max <emax unit> G4double emax and G4String unit. The units can
be eV, keV, MeV, GeV, TeV or PeV.
Sets the maximum for the energy distribution.
/gps/ene/mon <monoenergy unit> G4double monoenergy and G4String unit. Sets the energy for mono-energetic sources.
/gps/ene/sigma <sigma unit> Double sigma and a G4String giving the unit.The units
can be eV, keV, MeV, GeV, TeV or PeV.
Sets the standard deviation in energy for Gaussian energydistribution.
/gps/ene/alpha <alpha> G4double alpha. Sets the index for a power-law distribution.
/gps/ene/temp <temp> G4double temp. Sets the Temperature for black body and
bremsstrahlung spectra.
/gps/ene/ezero <ezero> G4double ezero. Sets E0 for exponential distributions.
/gps/ene/gradient <gradient> G4double gradient. Sets the gradient for l inear distributions.
/gps/ene/intercept <intercept> G4double intercept. Sets the intercept for the linear distributions.
/gps/ene/calculate Prepares integral PDFs for cosmic diffuse gamma
ray and black body distributions.
/gps/ene/emspec <energyspec> Boolean energyspec. Allows user to specify distributions are in
momentum or energy.
/gps/ene/diffspec <diffspec> Boolean diffspec. Allows user to specify whether a point-wise
function is integral or differential.
/gps/his/type <HistType> G4String HistType. The valid arguments are
"biasx", "biasy", "biasz", "biast", "biasp",
"biaspt", "biaspp", "biase", "theta", "phi",
"energy", "arb" and "epn".
Set the histogram type.
/gps/his/reset <HistType> G4String HistType. The valid arguments are
"biasx", "biasy", "biasz", "biast", "biasp",
"biaspt", "biaspp", "biase", "theta", "phi",
"energy", "arb" and "epn".
re-set the histogram.
/gps/hist/point <Ehi Weight> G4doubles Ehi and Weight. Allows the user to define both histograms and
point-wise distributions.
/gps/hist/inter <inter> G4String inter. The only valid arguments are
"Lin", "Log", "Exp" or "Spline".
Sets the interpolation type for point-wise spectra.
24/03/2012 Geant4 GPS Users Manual
23/26reat.space.qinetiq.com/gps/new_gps_sum_files/gps_sum.htm
5. Examples
Macro filess showing how to use all the functionalities of G4GeneralParticleSource can be found in the example pages. Weshow one example, test2.g4mac, here and explain what it does.
# Macro test2.g4mac
/control/verbose 0/tracking/verbose 0
/event/verbose 0
/gps/verbose 2/gps/particle gamma
/gps/pos/type Plane
/gps/pos/shape Square/gps/pos/centre 1 2 1 cm
/gps/pos/halfx 2 cm/gps/pos/halfy 2 cm/gps/ang/type cos
/gps/ene/type Lin/gps/ene/min 2 MeV/gps/ene/max 10 MeV
/gps/ene/gradient 1/gps/ene/intercept 1/run/beamOn 10000
The above macro defines a planar source, square in shape, 4 cm by 4 cm and centred at (1,2,1) cms. By default the normal
of this plane is the z-axis. The angular distribution is to follow the cosine-law. The energy spectrum is linear, with gradientand intercept equal to 1, and extends from 2 to 10 MeV. 10,000 primaries are to be generated. The standard Geant4 outputshould show that the primary particles start from between –1, 0, 1 and 3, 4, 1 (in cm) and have energies between 2 and 10
MeV, which is clearly the case as shown in figure 4, in which we plotted the actual energy, position and angular distributionsof the primary particles generated by the above macro file.
24/03/2012 Geant4 GPS Users Manual
24/26reat.space.qinetiq.com/gps/new_gps_sum_files/gps_sum.htm
Figure 4. Energy, position and angular distributions of the primary particles as generated by the macro file
test2.g4mac shown above.
6. Code idiosyncrasies
i. Histograms
Currently histograms are limited to 1024 bins. The first value of the user input data pair is treated as the upper
edge of the histogram bin and the second value is the bin content. The exception is the very first data pair theuser input whose first value is the treated as the lower edge of the first bin of the histogram, and the secondvalue is not used. This rule applies to all distribution histograms, as well as histograms for biasing.
ii. Point-wise energy distributions
The data points are inputted the same way as that for histograms, but each data pair is treated as one point
describing the distribution. Random energy is generated by interpolation of the inputed data points. The generatedrandom energy will be limited in between the minimum and maximum energy points inputed. Further the max/min
24/03/2012 Geant4 GPS Users Manual
25/26reat.space.qinetiq.com/gps/new_gps_sum_files/gps_sum.htm
energy limits explicitely specified by the user are applied.
The interpolation command /gps/hist/inter has to be issued immediated after inputing the last data point.
iii. Order of the data pairs
Data pairs for defining the histograms or point-wise energy distributions have to be inputed in ascending orders of its
abscissa values.
iv. Energy or momentum spectrum
Option for momentum spectrum is only valid (in effect) for "User" or "Arb" type energy distributions.
v. Differential or integral energy spectrum
Integral type energy spectrum input is valid only for "Arb" type energy distribution.
For integral spectrum, user has to ensure the inputted spectrum is indeed of the integral type, i.e. s(e1) > =s(e2), ife1<e2. No check is carried out in GPS.
The maximum energy limit is defined by the last but one data point. This is because GPS convert integral spectruminto differntial spectrum internally.
vi. Energy per nucleon
The "Epn" is for histogramed energy distribution only. All other energy distrbution types are for the incident particles.
vii. The black-body spectrum
Unlike the other spectral distributions it has proved difficult to integrate indefinitely the black-body spectrum and this
has lead to an alternative approach. Instead it has been decided to use the black-body formula to create a 10,000bin histogram and then to produce random energies from this.
viii. Directional cosines
The directional cosines are calculated with the formula
Px = - sin(q) cos(f)
Py = - sin(q) sin(f)
Pz = - cos(q)
The same formula should be used when reconstructing the incident angles.
ix. Rotation matrices
At the moment it is possible to specify vectors to create rotation matrices for both the angular and position
distributions separately. This was originally intended to give flexibility to the user, but it does make it possible to havethe angular distribution oriented wrongly with respect to the position distribution. For this reason this may bereconsidered in the future.
x. Biasing
When creating biasing histograms it is important to bare in mind the way quantities are generated from those
numbers. For example let us compare the biasing of a theta distribution with that of a phi distribution. Let us divide
24/03/2012 Geant4 GPS Users Manual
26/26reat.space.qinetiq.com/gps/new_gps_sum_files/gps_sum.htm
the theta and phi ranges up into 10 bins, and then decide we want to restrict the generated values to the first and last
bins. This gives a new phi range of 0 to 0.628 and 5.655 to 6.283. Since phi is calculated using f = 2p * RNDM,
this simple biasing will work correctly. If we now look at theta however, we have an expected range of 0 to 0.314
and 2.827 to 3.142. Theta is calculated from the formula q = cos-1(1-2*RNDM), and so compare the expectedvalues of theta with those generated we can verify the correctness of the biasing. It is expected that 0.1 will give atheta of 0.314, however from the equation it is found that 0.1 gives a theta of 0.644 and a RNDM of 0.9 gives a
theta of 2.498. This means that the above will not bias the distribution as the user had wished. The user musttherefore take into account the method used to generate random quantities when trying to apply a biasing scheme to
them. Some quantities such as x, y, z and f will be relatively easy to bias, but others may require more thought.
Biasing dose not apply to user defined angular distributions.
xi. Angular distribution with respect to the surface normal
This option is available/valid only for "user" type angular distribution. When using the angular distribution with respect
to the surface normal it is important to remember that theta only needs to be defined between 0 and p/2, not the
usual 0 to p limit. This is not automatically taken into account and so the user has to remember this.