Geant4 GPS Users Manual

24/03/2012 Geant4 GPS Users Manual
1/26 reat.space.qinetiq.com/gps/ne_gps_sum_files/gps_sum.htm
Gean4 Geneal Paicle Soce Ue Manal
1. Inodcion
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 an
user 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. Oeie
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 the
technical 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 energy
distributions as well as incident particle types.
Figure 1. The class diagram of GPS.
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 and
parallelepiped.
To allow easy definition of the sources, the planes and shapes are assumed to be orientated in a particular
direction to the axes (Fig 2). To allow the user more freedom he/she can supply two vectors (x and a vector
in the plane xy) 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 change
this.
Figure 2. An illustration of the use of rotation matrices. A cvlinder is defined with its axis parallel to
the :-axis (black lines), but the definition of 2 vectors can rotate it into the frame given bv x, v, :
(red lines).
As mentioned above there are five planes (circle, annulus, ellipse, square and rectangle) and four
shapes (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 gives
the 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, from
which 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 to
give the radius and the z half-length. Parallelepipeds are defined by giving x, y and z half-lengths, plus the
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 the
source 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 the
co-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. Energ 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.
iv. Biasing
The user can bias distributions by entering a histogram. It is the random numbers from which the
quantities 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 the
same 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 the
reasons may be different the approach is the same. To choose a histogram the command hist/tvpe 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/point
command, 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 give
the 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.
Ho o e i
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 vourPrimarvGeneratorAction by globally replacing "G4ParticleGun" with "G4GeneralParticleSource".
The command
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 director /gps
Function: Contains all the replicae G4ParticleGun commands.
/gps/particle
Format: /gps/particle <aiceNae>
Arguments: G4String particleName.
Function: Defines the particle type.
Default: geantino
/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/energv
Format: /gps/energy <energy i>
Arguments: Double energv 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 1 MeV.
/gps/position
Format: /gps/position <X Y Z i>
Arguments: Three doubles x, v and : 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 <d d d>
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 <0 i>
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/polari:ation
Format: /gps/polarization 
Arguments: Three doubles P
x
, P
v
, P
:
.
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 <ebiLee>
Arguments: An integer verbositvLevel.
Function: This allows the user to control the amount of information printed out
by the GPS code. The possible values are 0, 1 and 2. 0 is for silent running and very
little 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 information
printed out including the debug arrrays.
ii. Sub command director /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
Format: /gps/source/add <iei>
Arguments: G4double intensitv
Function: add a new particle source with the specified intensity
Default: none
Errors: An error is flagged if intensitv is ommited or negative.
/gps/source/delete
Format: /gps/source/delete <ce_ide>
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 <ce_ide>
Arguments: G4int index
Function: set the specified particle source as the current one.
Default: none
Errors: An error is flagged if index is out of range.
/gps/source/intensitv
Format: /gps/source/intensity iei
Arguments: G4double intensitv
Function:set the inetnsity of the current particle source.
Default: none
Errors: An error is flagged if intensitv is omitted or negative.
/gps/source/multiplevertex
Format: /gps/source/multiplevertex 
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 director /gps/pos
Function: Contains all the commands for specification of position
/gps/pos/tvpe
Format: /gps/pos/type <DiTe>
Arguments: G4String DisTvpe
Function: Sets the source distribution type to Point, Beam, Plane, Surface or Volume. At the
moment 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
Jolume.
/gps/pos/shape
Format: /gps/pos/shape <Shae>
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,
Ellipsoid, Cylinder or Para (parallelepiped). Again, capitalisation is very important, only an exact
match will be recognised.
Default: NULL. The default source is a Point source and so Shape is not set to any of the
above types.
Errors: The entered string must be Circle, Annulus, Ellipse, Square, Rectangle, Sphere,
Ellipsoid, Cvlinder or Para. The G4GeneralParticleSource also checks that the choice is
appropriate for the distribution type i.e. a cylinder will give an error is the distribution type is
Plane.
/gps/pos/centre
Format: /gps/pos/centre <X Y Z i>
Function: Sets the centre co-ordinates of the source.
/gps/pos/rot1
Format: /gps/pos/rot1 <R1
, R1
, R1
>
Arguments: Three doubles R1
x
, R1
v
, R1
:
.
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 of
rotation.)
Default: The unit vector in x (1., 0., 0.).
/gps/pos/rot2
Format: /gps/pos/rot2 <R2
, R2
, R2
>
Arguments: Three doubles R2
x
, R2
v
, R2
:
.
Function: Defines a vector in the plane 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. (See Fig 1 for a summary
of rotation.)
Default: The unit vector in y (0., 1., 0.).
/gps/pos/halfx
Format: /gps/pos/halfx <Haf i>
Arguments: Double Halfx and a G4String giving the unit.
Function: Sets the x half-length of the source.
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/halfv
Format: /gps/pos/halfy <Haf i>
Arguments: Double Halfv 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.
/gps/pos/half:
Format: /gps/pos/halfz <Haf i>
Arguments: Double Half: 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.
/gps/pos/radius
Format: /gps/pos/radius <Radi i>
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/innerradius
Format: /gps/pos/inner_radius<Radi i>
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 <iga i>
Arguments: Double sigma and a G4String giving the unit.
Function: Sets the standard deviation of beam position profile in radial.
Default: 0 cm.
To be used in confunction with.
/gps/pos/tvpe Beam
/gps/pos/shape Circle
/gps/pos/sigmax
Format: /gps/pos/sigmax <iga i>
Function: Sets the standard deviation of beam position profile in the x-direction (2d case)
Default: 0 cm.
/gps/pos/sigmav
Format: /gps/pos/sigmay<iga i>
Function: Sets the standard deviation of beam position profile in the y-direction (2d case)
Default: 0 cm.
sigmax and sigmav are to be used in confunction with.
/gps/pos/tvpe Beam
/gps/pos/tvpe Square (or Rectangle)
/gps/pos/paralp
Format: /gps/pos/paralp <aha i>
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.
Errors: An error is flagged if the unit is anything other than rad or deg.
/gps/pos/parthe
Format: /gps/pos/parthe <hea i>
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).
/gps/pos/parphi
Format: /gps/pos/parphi <hi i>
Arguments: Double phi and a unit.
Function: Azimuth angle of the line connecting the centre of the face at z with the centre of
the face at +z. (See Fig 2).
/gps/pos/confine
Format: /gps/pos/confine <VNae>
Arguments: G4String JolName
Function: Confines source to volume given by JolName.
Default: By default this is set to NULL.
Errors: An error is flagged if an invalid physical volume name is given.
iv. Sub command director /gps/ang
Function: Contains all the commands for specification of direction.
/gps/ang/tvpe
Format: /gps/ang/type <AgDi>
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).
Errors: The only arguments are the ones defined.
/gps/ang/rot1
Format: /gps/ang/rot1 <AR1
, AR1
, AR1
>
Arguments: Three doubles AR1
x
, AR1
v
, AR1
:
.
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 <AR2
, AR2
, AR2
>
Arguments: Three doubles AR2
x
, AR2
v
, AR2
:
.
Function: Defines a vector in the x-y plane for the angular distribution. This does not necessarily
have to be a unit vector.
Default: The unit vector y (0., 1., 0.).
/gps/ang/mintheta
Format: /gps/ang/mintheta <MiThea i>
Arguments: Double MinTheta and G4String unit.
Function: Sets a minimum value for the theta distribution.
Errors: An error is flagged if the units are not rad or deg.
/gps/maxtheta
Format: /gps/ang/maxtheta <MaThea i>
Arguments: Double MaxTheta and G4String unit.
Function: Sets a maximum value for the theta distribution.
Default: p radians.
/gps/ang/minphi
Format: /gps/ang/minphi <MiPhi i>
Arguments: Double MinPhi and a G4String unit.
Function: Sets the minimum value for the phi distribution.
/gps/ang/maxphi
Format: /gps/ang/maxphi <MaPhi i>
Arguments: Double MaxPhi and a G4String unit.
Function: Sets the maximum value for the phi distribution.
Default: 2p radians.
/gps/ang/sigmar
Format: /gps/ang/sigmar <iga i>
Function: Sets the standard deviation of beam angular profile in radial.
Default: 0 rad
/gps/ang/tvpe beam1d
/gps/ang/sigmax
Format: /gps/ang/sigmax <iga i>
Function: Sets the standard deviation of beam angular profile in the x-direction (2d case)
Default: 0 rad.
/gps/ang/sigmav
Format: /gps/ang/sigmay<iga i>
Function: Sets the standard deviation of beam angular profile in the y-direction (2d case)
Default: 0 rad
ang/sigmax and ang/sigmav are to be used in confunction with.
/gps/ang/tvpe beam2d
/gps/ang/focuspoint
Format: /gps/ang/focuspoint <X Y Z i>
Function: Sets the focusing point.
/gps/ang/surfnorm
Format: /gps/ang/surfnorm 
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/usercoor
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 director /gps/ene
Function: Contains all the commands for specification of energy.
/gps/ene/tvpe
Format: /gps/ene/type <EegDi>
Arguments: G4String EnergvDis.
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 is
important, only strings given exactly as above will be recognised.
Default: Mono.
Errors: Only Mono, Lin, Pow, Exp, Gauss, Brem, Bbodv, Cdg, User, Arb and Epn are
acceptable arguments.
/gps/ene/min
Format: /gps/ene/min <ei i>
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 <ea i>
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.
/gps/ene/mono
Format: /gps/ene/mono<eeg i>
Arguments: Double monoenergv 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 1
MeV.
/gps/ene/sigma
Format: /gps/ene/sigma <iga i>
Function: Sets the standard deviation in energy for Gaussian energy distribution.
Default: 0 keV
/gps/ene/tvpe Gauss
/gps/ene/mono
/gps/ene/alpha
Format: /gps/ene/alpha <aha>
Arguments: Double alpha.
Function: Sets alpha for power-law distributions of the form y = AE
a
, where A is a constant.
Default: Zero.
/gps/ene/temp
Format: /gps/ene/temp <e>
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/e:ero
Format: /gps/ene/ezero <ee>
Arguments: Double e:ero.
Function: Sets E
0
for exponential distributions of the form
Default: Zero.
/gps/ene/gradient
Format: /gps/ene/gradient <gadie>
Arguments: Double gradient.
Function: Sets the gradient for linear distributions.
Default: Zero.
/gps/ene/intercept
Format: /gps/ene/intercept <iece>
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 Bbody
distributions. 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 case
of 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 obtained
from which the random energies are generated.
/gps/ene/emspec
Format: /gps/emspec <eec>
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 assumed
that these are entered as distributions in terms of energy, however by specifying energvspec 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 <diffec>
Arguments: Boolean diffspec.
Function: Toggles between differential (True) and integral (False) spectra. This option can
only 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 director /gps/hist
Function: Contains all the commands for specification of histograms.
/gps/hist/tvpe
Format: /gps/hist/type <HiTe>
Arguments: G4String HistTvpe.
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, biasv, bias:, biast, biasp, biaspt, biaspp, biase, theta, phi, energv,
arb and epn are acceptable arguments.
/gps/hist/point
Format: /gps/histpoint <Ehi Weigh>
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 the
restrictions specified in section 6(i) below

/gps/hist/inter
Format: /gps/hist/inter 
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<HiTe>
Arguments: G4String HistTvpe.
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, biasv, bias:, biast, biasp, biaspt, biaspp, biase, theta, phi, energv,
arb and epn are acceptable arguments.
vii. Command Summar

Command Arguments and argument
restrictions
Command function and
restrictions
/gps/parti cl e <parti cl eName> G4Stri ng parti cl eName. Defi nes the parti cl e 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 the
excitation 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 information
printed 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 <Di Te> G4Stri ng Di Te. Can onl y be "Pi ", "P ae",
"Beam", "Sface" or "V e".
Sets the source posi ti onal di stri buti on type.
/gps/pos/shape <Shape> G4Stri ng Shae. Li mi ted to "Ci c e", "A ",
"E i e", "Sae", "Recag e", "Shee",
"E i i d", "C i de" or "Paa".
Sets the source shape type. For a Pl ane thi s can
be Ci rcl e, El l i pse, Square or Rectangl e. For both
Surface or Vol ume sources thi s can be Sphere,
El l i psoi d, Cyl i nder or Para.
/gps/pos/centre <X Y Z i > G4doubl es X, Y, Z and G4stri ng i . The uni ts
can onl y be mi cron, mm, cm ,m or km.
Sets the centre co-ordi nates of the source.
/gps/pos/rot1 <R1
, R1
, R1
> G4doubl es R1
, R1
, R1
. Defi nes the vector x, whi ch does not need to be

a uni t vector, and i s used to create the rotati on
matri x of the shape defi ned wi th /gps/shape.
/gps/pos/rot2 <R2
, R2
, R2
> G4doubl es R2
, R2
, R2
. Defi nes a vector i n the xy, whi ch does not need

to be a uni t vector, and i s used to create the
rotati on matri x of the shape defi ned wi th
/gps/shape.
/gps/pos/hal fx <Ha f i > G4doubl e Ha f and G4Stri ng i . The uni ts can
onl y be mi cron, mm, cm, m or km.
Sets the hal f-l ength i n x of the source.
/gps/pos/hal fy <Ha f i > G4doubl e Ha f and G4Stri ng i . The uni ts can
Sets the hal f-l ength i n y of the source.
/gps/pos/hal fz <Ha f i > G4doubl e Ha f and G4Stri ng i . The uni ts can
Sets the hal f-l ength i n z of the source.
/gps/pos/radi us <Radi i > G4doubl e Radi and G4Stri ng i . The uni ts
can onl y be mi cron, mm, cm, m or km.
Sets the radi us of the source or the outer radi us
for annul i .
/gps/pos/i nner_radi us <Radi i > G4doubl e Radi and G4Stri ng i . The uni ts
can onl y be mi cron, mm, cm, m or km.
Sets the i nner radi us for annul i .
/gps/pos/sigmar <sigma unit> Double sigma and a G4String giving the unit. Sets the standard deviation of beam position profile in
radial.
/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/paral p <a ha i > G4doubl e a ha and a G4Stri ng i . The uni ts
can onl y be deg or rad.
Used wi th a Paral l el epi ped. The angl e formed by
the y-axi s and by the pl ane j oi i ng the centre of
the faces paral l el to the zx pl ane at y and +y.
/gps/pos/parthe <hea i > G4doubl e hea and a G4Stri ng i . The uni ts
can onl y be deg or rad.
Used wi th a Paral l el epi ped. Pol ar angl e of the
l i ne connecti ng the centre of the face at z to the
centre of the face at +z.
/gps/pos/parphi <hi i > G4doubl e hi and a G4Stri ng i . The uni ts can
onl y be deg or rad.
Used wi th a Paral l el epi ped. The azi muth angl e
of the l i ne connecti ng the centre of the face at z
wi th the centre of the face at +z.
/gps/pos/confi ne <V Nae> G4Stri ng V Nae. Has to be a val i d physi cal
vol ume name.
Al l ows the user to confi ne the source to the
physi cal vol ume V Nae.
/gps/ang/type <AgDi > G4Stri ng AgDi . The arguments are l i mi ted to
"i ", "c","pl annar","beam1d","beam2d",
"focused" and "e"..
Sets the angul ar di stri buti on type to ei ther
i sotropi c, cosi ne-l aw or user-defi ned.
/gps/ang/rot1 <AR1
, AR1
, AR1
> G4doubl es AR1
, AR1
, AR1
. Sets the x vector for the angul ar di stri buti on and

i s not necessari l y a uni t vector.
/gps/ang/rot2 <AR2
, AR2
, AR2
> G4doubl es AR2
, AR2
, AR2
. Defi nes a vector i n the pl ane xy for the angul ar

di stri buti on, whi ch does not necessari l y have to
be a uni t vector.
/gps/ang/mi ntheta <Mi Thea i > G4doubl e Mi Thea and G4Stri ng i . Uni ts can
be deg or rad.
Sets a mi ni mum val ue for the theta di stri buti on.
/gps/ang/maxtheta <MaThea i > G4doubl e MaThea and G4Stri ng i . Uni ts
can be deg or rad.
Sets a maxi mum val ue for the theta di stri buti on.
/gps/ang/mi nphi <Mi Phi i > G4doubl e Mi Phi and G4Stri ng i . Uni ts can
be deg or rad.
Sets a mi ni mum val ue for the phi di stri buti on.
/gps/ang/maxphi <MaPhi i > G4doubl e MaPhi and G4Stri ng i . Uni ts can
be deg or rad.
Sets a maxi mum val ue for the phi di stri buti on.
/gps/ang/sigmar <sigma unit> Double sigma and a G4String giving the unit. Sets the standard deviation of beam directional profile in
radial.
/gps/ang/sigmax<sigma unit> Double sigma and a G4String giving the unit. Sets the standard deviation of beam directional profile in
x-direction.
/gps/ang/sigmay<sigma uniit> Double sigma and a G4String giving the unit. Sets the standard deviation of beam directional profile in
y-direction.
/gps/ang/focuspoint <x,y,z,unit> G4doubl es X, Y, Z and G4stri ng i . The uni ts
can onl y be mi cron, 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 calculated
with respect to the user definded co-ordinate system,
otherwise it is with respect to the global co-ordinate
system
/gps/ang/surfnorm Bool B . Al l ows user to choose whether angul ar
di stri buti ons are wi th respect to the co-ordi nate
system or surface normal s for user-defi ned
di stri buti ons.
/gps/ene/type <EegDi > G4Stri ng EegDi . The onl y val i d arguments
are "M", "Li ", "P", "E", "Gauss", "Be",
"Bbd", "Cdg", "Ue", "Ab" or "E".
Sets the energy di stri buti on type.
/gps/ene/mi n <ei i > G4doubl e ei and G4Stri ng i . The uni ts can
be eV, keV, MeV, GeV, TeV or PeV.
Sets the mi ni mum for the energy di stri buti on.
/gps/ene/max <ea i > G4doubl e ea and G4Stri ng i . The uni ts can
be eV, keV, MeV, GeV, TeV or PeV.
Sets the maxi mum for the energy di stri buti on.
/gps/ene/mon <eeg i > G4doubl e eeg and G4Stri ng i . Sets the energy for mono-energeti c sources.
/gps/ene/sigma <sigma unit> Double sigma and a G4String giving the unit.The uni ts
can be eV, keV, MeV, GeV, TeV or PeV.
Sets the standard deviation in energy for Gaussian energy
distribution.
/gps/ene/al pha <a ha> G4doubl e a ha. Sets the i ndex for a power-l aw di stri buti on.
/gps/ene/temp <e> G4doubl e e. Sets the Temperature for bl ack body and
bremsstrahl ung spectra.
/gps/ene/ezero <ee> G4doubl e ee. Sets E
0
for exponenti al di stri buti ons.
/gps/ene/gradi ent <gadi e> G4doubl e gadi e. Sets the gradi ent for l i near di stri buti ons.
/gps/ene/i ntercept G4doubl e i ece. Sets the i ntercept for the l i near di stri buti ons.
/gps/ene/cal cul ate

Prepares i ntegral PDFs for cosmi c di ffuse gamma
ray and bl ack body di stri buti ons.
/gps/ene/emspec <eegec> Bool ean eegec. Al l ows user to speci fy di stri buti ons are i n
momentum or energy.
/gps/ene/di ffspec <di ffec> Bool ean di ffec. Al l ows user to speci fy whether a poi nt-wi se
functi on i s i ntegral or di fferenti al .
/gps/hi s/type <Hi Te> G4Stri ng Hi Te. The val i d arguments are
"bi a", "bi a", "bi a", "bi a", "bi a",
"bi a", "bi a", "bi ae", "hea", "hi ",
"eeg", "ab" and "e".
Set the hi stogram type.
/gps/hi s/reset <Hi Te> G4Stri ng Hi Te. The val i d arguments are
"bi a", "bi a", "bi a", "bi a", "bi a",
"bi a", "bi a", "bi ae", "hea", "hi ",
"eeg", "ab" and "e".
re-set the hi stogram.
/gps/hi st/poi nt <E
hi
Wei gh> G4doubl es E
hi
and Wei gh. Al l ows the user to defi ne both hi stograms and
poi nt-wi se di stri buti ons.
/gps/hi st/i nter G4Stri ng i e. The onl y val i d arguments are
"Li ", "Lg", "E" or "S i e".
Sets the i nterpol ati on type for poi nt-wi se spectra.


5. Eample
Macro filess showing how to use all the functionalities of G4GeneralParticleSource can be found in the example pages. We
show one example, test2.g4mac, here and explain what it does.
= Macro test2.g4mac
/c/ebe 0
/acig/ebe 0
/ee/ebe 0
/g/ebe 2
/g/aice gaa
/g//e Pae
/g//hae Sae
/g//cee 1 2 1 c
/g//haf 2 c
/g//haf 2 c
/g/ag/e c
/g/ee/e Li
/g/ee/i 2 MeV
/g/ee/a 10 MeV
/g/ee/gadie 1
/g/ee/iece 1
//beaO 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 gradient
and intercept equal to 1, and extends from 2 to 10 MeV. 10,000 primaries are to be generated. The standard Geant4 output
should 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 distributions
of the primary particles generated by the above macro file.
Figure 4. Energv, position and angular distributions of the primarv particles as generated bv the macro file
test2.g4mac shown above.
6. Code idioncaie
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 the
user input whose first value is the treated as the lower edge of the first bin of the histogram, and the second
value is not used. This rule applies to all distribution histograms, as well as histograms for biasing.
ii. Point-wise energ 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 generated
random energy will be limited in between the minimum and maximum energy points inputed. Further the max/min
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. Energ or momentum spectrum
Option for momentum spectrum is only valid (in effect) for "User" or "Arb" type energy distributions.
v. Differential or integral energ 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), if
e1<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 spectrum
into differntial spectrum internally.
vi. Energ per nucleon
The "Epn" is for histogramed energy distribution only. All other energy distrbution types are for the incident particles.
vii. The black-bod 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,000
bin 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 have
the angular distribution oriented wrongly with respect to the position distribution. For this reason this may be
reconsidered 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
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 expected
values of theta with those generated we can verify the correctness of the biasing. It is expected that 0.1 will give a
theta 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 must
therefore 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.

Geant4 GPS Users Manual

Uploaded by

Document Information

Original Description:

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Geant4 GPS Users Manual

Uploaded by

Copyright:

Available Formats

24/03/2012 Geant4 GPS Users Manual

. Defi nes the vector x, whi ch does not need to be

. Defi nes a vector i n the xy, whi ch does not need

> G4doubl es AR1

. Sets the x vector for the angul ar di stri buti on and

> G4doubl es AR2

. Defi nes a vector i n the pl ane xy for the angul ar

You might also like