Geant4 GPS Users Manual

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.



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



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.



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



/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>



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



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



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,



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>


Function: Sets the centre co-ordinates of the source.



/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.



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.


/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.


/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>



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 conjunction with:

/gps/pos/type Beam

/gps/pos/shape Circle

/gps/pos/sigmax

Format: /gps/pos/sigmax <sigma unit>


Function: Sets the standard deviation of beam position profile in the x-direction (2d case)

Default: 0 cm.


/gps/pos/sigmay

Format: /gps/pos/sigmay<sigma unit>


Function: Sets the standard deviation of beam position profile in the y-direction (2d case)

Default: 0 cm.


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.



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).



/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).



/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).



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.


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.


/gps/ang/minphi

Format: /gps/ang/minphi <MinPhi unit>

Arguments: Double MinPhi and a G4String unit.



Function: Sets the minimum value for the phi distribution.



/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.


/gps/ang/sigmar

Format: /gps/ang/sigmar <sigma unit>


Function: Sets the standard deviation of beam angular profile in radial.

Default: 0 rad



/gps/ang/type beam1d

/gps/ang/sigmax

Format: /gps/ang/sigmax <sigma unit>


Function: Sets the standard deviation of beam angular profile in the x-direction (2d case)

Default: 0 rad.


/gps/ang/sigmay

Format: /gps/ang/sigmay<sigma unit>


Function: Sets the standard deviation of beam angular profile in the y-direction (2d case)

Default: 0 rad




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>


Function: Sets the focusing point.



/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.



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.


/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.


/gps/ene/sigma

Format: /gps/ene/sigma <sigma unit>


Function: Sets the standard deviation in energy for Gaussian energy distribution.

Default: 0 keV





/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.



/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



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,



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.



/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


Sets the half-length in y of the source.

/gps/pos/halfz <Halfz unit> G4double Halfz and G4String unit. The units can


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.



/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.



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.



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



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



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.

Geant4 GPS Users Manual

Documents

Transcript of Geant4 GPS Users Manual