Epp User Manual

Version 1.4.3



Jonas Lippuner, Harry R. Ingleby, Congwu Cui,
David N.M. Di Valentino and Idris A. lba!ri
Can"erCare Manitoba
#$% M"Der&ot Ave
'innipeg M( R) *V+
Canada


July ,*--



./e pp sour"e "ode and t/is do"u&ent are available online at
/ttp011www.p/ysi"s.u&anitoba."a12elba!ri1epp1

Conta"t0 3onas4lippuner."a

5Hyperlin!s in t/is 6D7 &ay not wor! properly.8


9 ,*-- Can"erCare Manitoba
pp :ser Manual ,
9 ,*-- Can"erCare Manitoba July +, ,*--
Abstract
pp 5asy parti"le propagation8 is a user "ode ;or t/e <=nr" "ode syste& 5-8 to run Monte Carlo si&ula>
tions o; parti"les propagating t/roug/ an arbitrary geo&etry. ./e p/otons leaving t/e si&ulation ge>
o&etry "an be propagated to a virtual dete"tor, and separate i&ages ;or pri&ary and s"attered p/otons
"an be generated allowing a detailed analysis o; t/e a&ount and distribution o; ?>ray s"attering. ./e de>
posited dose in a vo?eli@ed p/anto& "an also be re"orded, w/i"/ &a!es pp a viable alternative to t/e
widely used DA=BCDnr" 5,8.
Table of Contents
- Introdu"tion............................................................................................................................................. )
-.- Averview.......................................................................................................................................... )
-., 7eatures ........................................................................................................................................... E
-.) Li"ense ............................................................................................................................................. E
, Installation............................................................................................................................................... E
,.- ReFuire&ents................................................................................................................................... E
,., Installing pp.................................................................................................................................... E
) <etting =tarted wit/ pp ......................................................................................................................... %
).- Creating an Input 7ile ;or pp .......................................................................................................... %
).-.-. De;ining t/e =i&ulation <eo&etry ...................................................................................... #
).-.,. De;ining t/e =i&ulation =our"e............................................................................................ +
).-.). De;ining t/e Dete"tor, =i&ulation 6ara&eters and At/er Aptions................................... -*
)., Running t/e =i&ulation.................................................................................................................. --
).) Analy@ing t/e Autput ..................................................................................................................... -,
E Running pp as a =ingle 6ro"ess............................................................................................................ -,
% Running pp in 6arallel wit/ Multiple 6ro"esses................................................................................... -%
# Input 7ile................................................................................................................................................ -%
#.- Additional Input ............................................................................................................................. -%
#.-.-. Dete"tor De;inition ............................................................................................................ -#
#.-.,. Dose Cal"ulation................................................................................................................. -#
#.-.). Autput Aptions .................................................................................................................. -#
#., Re;eren"ing At/er 7iles.................................................................................................................. -$
#.) :sing *.egsphant 7iles................................................................................................................. -G
$ Autput 7iles............................................................................................................................................ -+
$.- 6/oton Autput 7iles....................................................................................................................... -+
$., Count and nergy Autput 7iles ...................................................................................................... ,*
$.) I&age Autput 7iles......................................................................................................................... ,-
$.E Dose Autput 7iles........................................................................................................................... ,-
G Version History ...................................................................................................................................... ,,
+ Re;eren"es ............................................................................................................................................. ,E
pp :ser Manual )
9 ,*-- Can"erCare Manitoba July +, ,*--
1 Introduction
1.1 Overview
pp is a user "ode ;or t/e Monte Carlo si&ulation pa"!age <=nr" 5-8 and "an be used to si&ulate dose
deposition in a vo?eli@ed volu&e and to generate i&ages ;ro& an ob3e"t illu&inated by an ?>ray sour"e.
./e i&aging part o; t/e so;tware is designed ;or analy@ing t/e a&ount and distribution o; Co&pton and
Rayleig/ s"attering arising in t/e i&aging pro"ess, but "an be e?tended and1or &odi;ied to suit ot/er
appli"ations as well.
pp is written entirely in CHH, and based on t/e <=nr" CHH "lass library 5)8 w/i"/ provides a wealt/ o;
pri&itive geo&etries t/at "an be used to "onstru"t a "o&ple? si&ulation geo&etry. ./e <=nr" CHH
"lass library also i&ple&ents various parti"le sour"es and provides a CHH inter;a"e to t/e <=nr" Monte
Carlo si&ulation written in MAR.RAN.
./e a"tual si&ulation o; t/e parti"les propagating t/roug/ and intera"ting wit/ &atter is done by t/e
<=nr" "ode syste&. ./e <=nr" CHH "lass library i&ple&ents t/e geo&etry and parti"le sour"e t/at t/e
user /as setup and also provides additional ;un"tionality ;or running t/e si&ulation in parallel wit/ &ul>
tiple pro"esses and "o&bining t/e results o; a parallel run. pp !eeps tra"! o; t/e nu&ber o; s"atter
events t/at a parti"le undergoes during t/e si&ulation and also t/e dose deposited in ea"/ vo?el o; t/e
volu&e in w/i"/ t/e user wants t/e dose to be re"orded. In addition to t/at, pp also propagates every
p/oton t/at leaves t/e si&ulation geo&etry to a virtual dete"tor spe"i;ied by t/e user and re"ords t/e
total nu&ber o; p/otons and1or total energy deposited in ea"/ pi?el. ./is data "an be written to binary
output ;iles and i&ages visuali@ing t/e data "an also be generated.
7or analy@ing t/e a&ount and distribution o; Co&pton and Rayleig/ s"atter, t/e p/otons are assigned to
one o; t/e ;ollowing "ategories ;or w/i"/ separate output ;iles "an be "reatedI see se"tion #.) ;or &ore
in;or&ation0
ri!ar"# p/otons t/at /ave not been s"attered
Co!pton# p/otons t/at /ave been Co&pton s"attered e?a"tly on"e
$a"lei%&# p/otons t/at /ave been Rayleig/ s"attered e?a"tly on"e
Multiple0 p/otons t/at /ave been s"attered &ore t/an on"e
./e "urrent i&ple&entation o; pp does not !eep tra"! o; ot/er intera"tions su"/ as pair produ"tion or
p/otoele"tri" e;;e"ts, but pp "ould be e?tended to a""ount ;or t/ese intera"tions as well. pp "ould
also be &odi;ied to tra"! ot/er parti"les.


pp :ser Manual E
9 ,*-- Can"erCare Manitoba July +, ,*--
1.' (eatures
./e &ain ;eatures o; pp are t/e ;ollowing0
Input ;ile allows re;eren"ing ot/er ;iles
*.egsphant ;iles generated by ctcreate "an be dire"tly used ;or si&ulations
=i&ulation in"ludes propagation o; p/otons to a virtual dete"tor
Re"ords t/e total nu&ber o; p/otons and t/e total energy deposited in ea"/ pi?el o; t/e dete"tor
Results o; parallel runs get "o&bined auto&ati"ally
Autput ;iles "an be turned on and o;; individually
1.3 )icense
pp is ;ree so;twareI you "an redistribute it and1or &odi;y it under t/e ter&s o; t/e <N: <eneral 6ubli"
Li"ense as publis/ed by t/e 7ree =o;tware 7oundationI eit/er version , o; t/e Li"ense, or 5at your op>
tion8 any later version.
pp is distributed in t/e /ope t/at it will be use;ul, but 'I.HA:. ANC 'ARRAN.CI wit/out even t/e i&>
plied warranty o; MRCHAN.A(ILI.C or 7I.N== 7AR A 6AR.IC:LAR 6:R6A=. =ee t/e <N: <eneral
6ubli" Li"ense ;or &ore details.
' Installation
pp /as been designed to run in a Linu? environ&ent and /as only been tested under Linu?. ./e sour"e
"ode o; pp is available online at /ttp011www.p/ysi"s.u&anitoba."a12elba!ri1epp1.
'.1 $e*uire!ents
pp is a user "ode ;or <=nr" and t/us reFuires <=nr" to be installed and ;ully "on;igured. ./is version
o; pp was only tested wit/ <=nr" VE ,.).-. <=nr" "an be obtained ;ree o; "/arge ;ro&
/ttp011irs.in&s.nr"."a1so;tware1egsnr"1. =in"e pp is derived ;ro& t/e <=nr" CHH "lass library, t/e "lass
library &ust /ave been su""ess;ully "o&piled prior to "o&piling pp. ./e <=nr" CHH "lass library is part
o; t/e <=nr" distribution pa"!age and s/ould be auto&ati"ally "o&piled during t/e installation pro"ess.
'.' Installin% Epp
.o install pp on your Linu? syste&, ;ollow t/ese steps0
-. Download 5/ttp011irs.in&s.nr"."a1so;tware1egsnr"18 and install t/e <=nr" VE "ode syste& version
,.).- and &a!e sure it is ;ully "on;igured, i.e. all t/e environ&ent variables are set, t/is &ay reFuire
you to logout and login againI note t/at you need to /ave a 7AR.RAN, C and CHH "o&piler installed
on your syste&, see t/e <=nr" website ;or &ore in;or&ation
pp :ser Manual %
9 ,*-- Can"erCare Manitoba July +, ,*--
,. Download 5/ttp011www.p/ysi"s.u&anitoba."a12elba!ri1epp18 t/e pp sour"e "ode and e?tra"t t/e
;older Epp into your $EGS_HOME dire"tory 5typi"ally egsnrc or egsnrc_mp8
). C/ange into t/e pp dire"tory, e.g. /home/user/egsnrc/Epp, and run make make make make
I; t/e above steps /ave all been su""ess;ully "o&pleted, pp s/ould now be installed on your syste& and
ready to be used.
3 +ettin% ,tarted wit& Epp
./is se"tion des"ribes /ow to set up a si&ple input ;ile and ;or an i&aging and a dose si&ulation and
/ow to run t/e si&ulations. An e?isting J.egsp/ant ;ile will be used as t/e p/anto& ;or t/e dose si&ula>
tion. It is assu&ed t/at <=nr" and pp were su""ess;ully installed and "o&piledI see above ;or t/e in>
stallation instru"tions o; pp.
./is se"tion only provides a very brie; introdu"tion to t/e <=nr" CHH "lass library and users not ;a&iliar
wit/ t/e <=nr" CHH "lass library are strongly en"ouraged to /ave a loo! at t/e "o&pre/ensive do"u>
&entation o; t/e "lass library 5)8. pp relies /eavily on t/e <=nr" CHH "lass library and t/e input and
;eatures des"ribed in t/e <=nr" CHH "lass library do"u&entation "an be dire"tly used in pp. pp uses
so&e additional input ele&ents and ;eatures w/i"/ are des"ribed in se"tion #.
3.1 Creatin% an Input (ile for Epp
./e input ;ile ;or pp 5*.egsinp8 is a si&ple te?t ;ile and organi@ed in !ey>value and !ey>sub!ey pairs.
Anyt/ing ;ollowing a K will be treated as a "o&&ent wit/ t/e e?"eption o; two spe"ial dire"tives e?>
plained in se"tions #., and #.). ./e ;ollowing e?a&ple illustrates t/e basi" synta? ;or an *.egsinp ;ile.
E-a!ple
# a key with a value
key 1 = value

# a key with subkeys
:start key 2:

# a simple subkey with a value
subkey 1 = value

# another subkey with a value
subkey 2 = value

# a subkey with one subkey
:start subkey 3:
subsubkey = value
:stop subkey 3:
:stop key 2:
pp :ser Manual #
9 ,*-- Can"erCare Manitoba July +, ,*--
?"ept ;or t/e &odi;i"ations des"ribed in se"tion #, pp uses e?a"tly t/e sa&e input as t/e <=nr" CHH
"lass library, and t/e user s/ould re;er to t/at &anual 5)8 ;or a detailed des"ription o; t/e stru"ture o;
t/e input ;ile as well as t/e available options.
All nu&eri"al values t/at de;ine a lengt/ or "oordinates /ave units "enti&etre 5"&8.
3.1.1. .efinin% t&e ,i!ulation +eo!etr"
./e si&ulation geo&etry, i.e. t/e p/anto&, is "onstru"ted ;ro& various geo&etri" pri&itives li!e bo?es,
sp/eres, "ylinders, "ones et". ./ose pri&itives "an be rotated, translated and "o&bined wit/ ot/er
pri&itives. A geo&etry ob3e"t, /en"e;ort/ si&ply "alled geo&etry, is eit/er a single pri&itive geo&etry,
a trans;or&ation o; anot/er geo&etry or a "o&bination o; two or &ore ot/er geo&etries. a"/ geo&e>
try is de;ined wit/ a :geometry: !ey t/at "ontains several sub!eys. ./e sub!ey name is "o&&on to
all geo&etries and used to assign a na&e to ea"/ geo&etry by w/i"/ t/at geo&etry "an be re;eren"ed
later. ./e na&e s/ould be uniFue and "annot "ontain spa"es. ./e <=nr" CHH "lass library do"u&enta>
tion 5)8 des"ribes in detail /ow t/e di;;erent geo&etries are de;ined. Note t/at by de;ault, all geo&etri"
pri&itives are "entred at t/e origin.
a"/ geo&etry de;ines one or &ore regions wit/ a /o&ogenous &ediu&. =o in addition to spe"i;ying
t/e geo&etries t/at &a!e up t/e p/anto&, t/e user also /as to spe"i;y t/e &ediu& ;or ea"/ region.
All geo&etries are sub!eys o; geometry definition w/i"/ will also be re;erred to as t/e geome-
try definition se"tion. ./is se"tion &ust "ontain a single !ey simulation geometry w/i"/
de;ines w/i"/ o; all t/e previously de;ined geo&etries will a"tually be used ;or t/e si&ulation. ./e order
in w/i"/ t/e various geo&etries are de;ined does not &atter. ./e only restri"tion is t/at a geo&etry /as
to be de;ined be;ore it "an be re;eren"ed.
./e ;ollowing e?a&ples are distributed wit/ pp and are lo"ated in t/e installation dire"tory o; pp.
Example Example Example Example_ __ _1.eg 1.eg 1.eg 1.egsinp sinp sinp sinp# Anal"tical /ater C"linder
./is e?a&ple de;ines a water "ylinder "oa?ial wit/ t/e y>a?is and wit/ radius %"& and /eig/t -,"&. ./e
"ylinder is t/en rotated by E%L around t/e @>a?is and e&bedded into a -%"& air "ube. =ee "o&&ents in
t/e e?a&ple ;or additional in;or&ation.
# all geometries are contained in the geometry definition key
:start geometry definition:

# first we define air hull which is a cube
:start geometry:
library = egs_box # refer to the class library manual
type = EGS_Box # refer to the class library manual
box size = 15 # if only one value is specified it will be
# used for all 3 dimensions thus creating a cube
name = air_hull # we call this geometry object "air_hull"
:start media input:
media = AIR700ICRU # we fill the cube with air
:stop media input:
:stop geometry:
pp :ser Manual $
9 ,*-- Can"erCare Manitoba July +, ,*--
# next we define a cylinder coaxial with the y-axis and radius 5cm
# NOTE: this cylinder extends indefinitely in +/-y direction
:start geometry:
library = egs_cylinders
type = EGS_YCylinders
radii = 5
name = water_cylinder
:stop geometry:

# to terminate the cylinder, i.e. give it a finite height, we define
# two planes perpendicular to the y-axis at those positions where
# we want to cut the cylinder; so to get a cylinder that is 12cm high
# and centred at the origin we need a plane at y = -6 and one at y = 6
:start geometry:
library = egs_planes
type = EGS_Yplanes
positions = -6, 6
name = y_planes
:stop geometry:

# now we combine the cylinder with the planes to crop it; the NDGeometry
# used here is very powerful but also quite abstract and not necessarily
# intuitive, refer to the EGSnrc C++ class library manual for details
:start geometry:
library = egs_ndgeometry
dimensions = water_cylinder y_planes
name = cropped_cylinder
:start media input:
media = H2O700ICRU
:stop media input:
:stop geometry:

# now we rotate the cropped cylinder by 45 degrees around the z-axis
# the values of the rotation key represent rotation around the x-, y- and
# z-axis in radians, the rotations are applied in the order z, y then x
:start geometry:
library = egs_gtransformed
my geometry = cropped_cylinder
name = rotated_cylinder
:start transformation:
rotation = 0, 0, 0.7854 # angles in radians
:stop transformation:
:stop geometry:

# now we put the rotated cylinder inside the air hull to create our phantom
# NOTE: we can give a list of geometries in the "inscribed geometries" key
# (separated by spaces), but we have to make sure that all inscribed
# geometries are completely contained in the base geometry and don't overlap
:start geometry:
library = egs_genvelope
name = phantom
base geometry = air_hull
inscribed geometries = rotated_cylinder
:stop geometry:

# finally we specify which geometry object should be used for the simulation
simulation geometry = phantom

:stop geometry definition:
pp :ser Manual G
9 ,*-- Can"erCare Manitoba July +, ,*--
Example_2.egsinp Example_2.egsinp Example_2.egsinp Example_2.egsinp# Vo-eli0ed &anto! in Air
./is e?a&ple de;ines a vo?eli@ed p/anto& i&ported ;ro& an e?isting *.egsphant ;ile inside an air vol>
u&e. ./e vo?eli@ed p/anto& is rotated by -%L around t/e y>a?is.
:start geometry definition:

# first we define air volume which will fill the space between the source
# and the phantom
:start geometry:
library = egs_box
type = EGS_Box
box size = 15, 15, 40
name = air
:start media input:
media = AIR700ICRU
:stop media input:
:stop geometry:

# now we translate the air volume to get it between the source and phantom
:start geometry:
library = egs_gtransformed
my geometry = air
name = translated_air
:start transformation:
translation = 0, 0, -12.5
:stop transformation:
:stop geometry:

# next we import the existing egsphant file phantom_10cm.egsphant which is
# in the same directory as this input file and call it "voxels", the file
# contains a cubic voxelized phantom with side length 10cm

#egsphant voxels phantom_10cm.egsphant

# now we rotate the voxelized phantom by 15 degrees around the y-axis
:start geometry:
library = egs_gtransformed
my geometry = voxels
name = rotated_voxels
:start transformation:
rotation = 0, 0.2618, 0 # angles in radians
:stop transformation:
:stop geometry:

# now we put the rotated voxels inside the air volume
:start geometry:
library = egs_genvelope
name = phantom
base geometry = translated_air
inscribed geometries = rotated_voxels
:stop geometry:

# finally we specify which geometry object should be used for the simulation
simulation geometry = phantom

:stop geometry definition:

pp :ser Manual +
9 ,*-- Can"erCare Manitoba July +, ,*--
3.1.'. .efinin% t&e ,i!ulation ,ource
./ere are a ;ew basi" sour"e types, li!e parallel, "olli&ated and isotropi" sour"e, w/i"/ "an be used to
de;ine a spe"i;i" sour"e. ./e spe"i;i" sour"es are "onstru"ted ;ro& abstra"t s/apes su"/ as, points, lines,
"ir"les, re"tangles, bo?es et". =our"es "an be arbitrarily rotated and translated and &ultiple sour"es "an
be "o&bined wit/ di;;erent weig/ts. ./e <=nr" CHH "lass library do"u&entation 5)8 des"ribes in detail
w/at sour"es and s/apes are available and /ow t/ey are spe"i;ied in t/e input ;ile. Note t/at by de;ault,
all s/apes are "entred at t/e origin.
Analogous to t/e de;inition o; t/e geo&etry ob3e"ts, t/e sour"e ob3e"ts are en"losed by :start
source: and :stop source: and all sour"e ob3e"ts &ust be inside t/e source !e"inition se"tion.
./e sour"e used ;or t/e si&ulation is de;ined wit/ t/e !ey simulation source.
E-a!ple# Colli!ated oint ,ource
./is e?a&ple de;ines a &ono"/ro&ati" point sour"e "olli&ated onto a -%"& by -%"& re"tangle w/i"/ is
perpendi"ular to t/e @>a?is and lo"ated at @ M >$.%"&. ./e point sour"e is lo"ated on t/e @>a?is at
@ M >),.%"& and radiates )G!eV p/otons. ./is sour"e is used in bot/ e?a&ple ;iles.
# all sources are contained in the source definition key
:start source definition:

# we define a new source object which is a collimated source
:start source:
library = egs_collimated_source
name = point_src

# the source shape is the shape that radiates the particles
:start source shape:
type = point # we use a point as the source
position = 0, 0, -32.5 # shape coordinates of the point
:stop source shape:

# the target shape is the collimator of the source, this is a virtual
# collimator, i.e. there is no leakage
:start target shape:
library = egs_rectangle # we use a rectangle as collimator
rectangle = -7.5, -7.5, 7.5, 7.5 # x and y coordinates of the upper
# left and lower right corners of
# the rectangle, which is initially
# located at z = 0
:start transformation:
translation = 0, 0, -7.5 # now we translate the rectangle by
# 7.5cm in the negative z direction
:stop transformation:
:stop target shape:

# the spectrum of the source is monochromatic (monoenergetic) with
# energy 38keV
:start spectrum:
type = monoenergetic
energy = 0.038 # the energy is specified in MeV
:stop spectrum:

pp :ser Manual -*
9 ,*-- Can"erCare Manitoba July +, ,*--
# to get a photon source we set the charge of the particles to 0
charge = 0
:stop source:

# finally we specify which source object should be used for the simulation
simulation source = point_src

:stop source definition:

3.1.3. .efinin% t&e .etector1 ,i!ulation ara!eters and Ot&er Options
7or an i&aging si&ulation, a dete"tor /as to be de;ined, w/i"/ is a virtual i&age plane 5-**N e;;i"ien"y8.
very p/oton leaving t/e si&ulation geo&etry is propagated onto t/e dete"tor 5t/e &ediu& outside o;
t/e si&ulation geo&etry is treated as va"uu&8 and t/e total nu&ber o; p/otons and1or t/e total energy
deposited in ea"/ pi?el o; t/e dete"tor is re"orded. ./e dete"tor is always perpendi"ular to t/e @>a?is,
see se"tion #.-.- ;or details.
Example_1.egsinp Example_1.egsinp Example_1.egsinp Example_1.egsinp
:start detector definition:
position = 0, 0, 32.5 # coordinates of the centre of the detector
size = 512, 512 # number of pixels in x and y direction
pixel size = 0.1, 0.1 # size of one pixel in x and y direction
:stop detector definition

I; t/e dose in a vo?eli@ed volu&e s/ould be re"orded t/e na&e o; t/e geo&etry ob3e"t in w/i"/ t/e dose
s/ould be re"orded &ust be spe"i;ied. ./is &ust be an <=OBCD<eo&etry. Note t/at i&porting t/e vo?>
eli@ed volu&e ;ro& an *.egsphant ;ile wit/ t/e #egsphant dire"tive auto&ati"ally "reates an
<=OBCD<eo&etry wit/ t/e na&e spe"i;ied in t/e #egsphant dire"tive. =ee se"tion #.-., ;or details.
=in"e dose output is disabled by de;ault, it /as to be enabled in order ;or dose output ;iles to be "reated,
see se"tion #.-.) ;or &ore in;or&ation. 7urt/er&ore, i; no i&aging output is desired, it /as to be turned
o;; sin"e it is enabled by de;ault.
Example_2.egsinp Example_2.egsinp Example_2.egsinp Example_2.egsinp
:start dose calculation:
phantom = voxels # the name of the voxelized volume in which the dose
# should be recorded
:stop dose calculation:

:start output options:
count = n # turn off binary photon count output
img-cnt = n # turn off image photon count output
dose = textbin # turn on dose output and specifies that the dose
# should be written to a text and a binary file
:stop output options:

pp :ser Manual --
9 ,*-- Can"erCare Manitoba July +, ,*--
7inally, regardless w/et/er an i&aging or dose si&ulation is run, t/e user also needs to spe"i;y t/e nu&>
ber o; /istories, rando& nu&ber seeds and si&ulation para&eters. =ee se"tion P=u&&ary o; transport
para&eterP in t/e <=nr" Re;eren"e Manual 5-8 ;or details about t/e si&ulation para&eters. ./e ;ollow>
ing e?a&ple is used in bot/ e?a&ple ;iles.
E-a!ple
# specifying the number of histories to be simulated
:start run control:
ncase = 10000000
:stop run control:

# specifying the random number generator and initial seed values
:start rng definition:
type = ranmar
initial seeds = 123, 4567 # the two seed values
:stop rng definition:

# specifying the simulation paramters
:start MC transport parameter:
Global ECUT = 0
Global PCUT = 0
Global SMAX = 1e10
ESTEPE = 0.25
XIMAX = 0.5
Boundary crossing algorithm = EXACT
Skin depth for BCA = 0
Electron-step algorithm = PRESTA-II
Spin effects = On
Brems angular sampling = Simple
Brems cross sections = BH
Bound Compton scattering = Off
Pair angular sampling = Simple
Photoelectron angular sampling = Off
Rayleigh scattering = On
Atomic relaxations = On
Electron impact ionization = On
:stop MC transport parameter:

3.' $unnin% t&e ,i!ulation
.o run t/e si&ulation one si&ply e?e"utes t/e ;ollowing "o&&and in a ter&inal0
Epp $i Example_1.egsinp $p %&&icru.pegs'!at
=e"tion E provides detailed in;or&ation on /ow to run pp and t/e available "o&&and line options. ./e
input ;ile, Example_1.egsinp in t/e above e?a&ple, &ust be lo"ated in t/e pp user "ode dire"tory,
i.e. t/e dire"tory w/ere pp was installed. It "annot be in any ot/er lo"ation or even a subdire"tory in
t/e pp dire"tory. ./e 6<=E ;ile "ontains t/e &aterial data used in t/e si&ulation and it is spe"i;ied
wit/ $p. ./e argu&ent a;ter $p &ust eit/er be an absolute pat/ to t/e 6<=E ;ile or relative to
$HE(_HO)SE/pegs'/!ata/ or $EGS_HOME/pegs'/!ata/.
pp :ser Manual -,
9 ,*-- Can"erCare Manitoba July +, ,*--
pp will display detailed output about t/e si&ulation t/at is running. I; an error o""urs, pp displays a
detailed error &essage. Note t/at pp will not run i; output ;ro& a previous si&ulation would be over>
written. '/ile t/e si&ulation is running, pp s/ows t/e progress in bat"/es, but t/e displayed result and
un"ertainty ;or ea"/ bat"/ will be * and -**N respe"tively be"ause pp is not re"ording partial results.
pp "an also be run in parallel &ode w/ere t/e w/ole si&ulation is split up a&ong di;;erent instan"es o;
pp. ./is allows t/e user to ta!e advantage o; &ultiple C6:s or C6: "ores or even a sop/isti"ated dis>
tributed "o&puting networ!. =e"tion % brie;ly e?plains /ow to run pp in parallel, ;or &ore details see
se"tion PRunning a standard <=nr" user>"ode in bat"/ &odeP in <=nr"M60 t/e &ulti>plat;or& envi>
ron&ent ;or <=nr" 5E8.
3.3 Anal"0in% t&e Output
Depending on t/e spe"i;ied output options, see se"tion E and #.-.), pp "reates various output ;iles. A
detailed des"ription o; all output is given in se"tion $I only a brie; su&&ary is provided /ere.
7or i&aging si&ulations, t/e total nu&ber o; p/otons and1or t/e total energy deposited in ea"/ pi?el
"an be re"orded by pp. Individual output ;iles ;or pri&ary p/otons, single Co&pton, single Rayleig/,
&ultiple s"attered p/otons and all p/otons "an be generated by pp. pp "an "reate bit&ap i&ages
s/owing t/e i&ages on t/e dete"tor and1or binary ;iles "ontaining t/e sa&e in;or&ation. ./e binary ;iles
"an be easily read into ot/er so;tware ;or ;urt/er analysis. ./e stru"ture o; t/e binary ;iles is des"ribed
in detail in se"tion $.,. ./e ;ile *ea!EppOutput.m in t/e pp installation dire"tory "an be used to read
t/ese output ;iles dire"tly into MA.LA(.
Dose output "an be written to a te?t and1or binary ;ile. ./e stru"ture o; t/ose ;iles is des"ribed in se">
tion $.E. ./e te?t ;ile /as t/e sa&e stru"ture as t/e te?t output ;ro& DA=BCDnr". pp "an also "reate
p/ase spa"e ;iles "ontaining detailed in;or&ation about every p/oton t/at le;t t/e si&ulation geo&etry,
see se"tion $.- ;or details.
I; pp was run in parallel, t/e output o; all pro"esses will be "o&bined be;ore any output ;iles are "re>
ated. ./e only e?"eptions are p/oton output ;iles, as t/ey tend to be very large.
4 $unnin% Epp as a ,in%le rocess
Usa%e# Epp $i +(,)-_.+/E $p ,EGS_.+/E 0O,-+O(S1
+(,)-_.+/E +(,)-_.+/E +(,)-_.+/E +(,)-_.+/E is t/e na&e o; t/e input ;ile ;or t/e si&ulationI t/e input ;ile &ust be in t/e pp user "ode
dire"tory.
,EGS_.+/E ,EGS_.+/E ,EGS_.+/E ,EGS_.+/E is t/e pat/ to t/e 6<=E ;ile to be used ;or t/e si&ulationI t/e pat/ &ust eit/er be absolute
or relative to $HE(_HO)SE/pegs'/!ata/ or $EGS_HOME/pegs'/!ata/.
O,-+O(S O,-+O(S O,-+O(S O,-+O(S are additional "o&&and line argu&ents and swit"/es ;ro& t/e list below 5optional8.
pp :ser Manual -)
9 ,*-- Can"erCare Manitoba July +, ,*--
./e ;ollowing additional "o&&and line argu&ents "an be used to "/ange t/e be/aviour o; t/e progra&0
$o O)-,)-_.+/E
$$output O)-,)-_.+/E
=ets t/e base na&e ;or t/e output ;iles to O)-,)-_.+/E O)-,)-_.+/E O)-,)-_.+/E O)-,)-_.+/E.
(y de;ault t/e na&e o; t/e input ;ile is used.
$pr +(,)-_.+/E
$$parse +(,)-_.+/E
pp will parse +(,)-_.+/E +(,)-_.+/E +(,)-_.+/E +(,)-_.+/E and resolve all #inclu!e and #egsphant
dire"tives and "reate a single "o&pleted input ;ile. ./is is use;ul to
"/e"! and debug #inclu!e dire"tives and to "reate an input ;ile
w/ose geo&etry "an be viewed wit/ egs_2ie3, as egs_2ie3 does
not understand #inclu!e and #egsphant.
./is option overrides all ot/er options e?"ept $h and $$help.
$o, ./4GS
$$output$photout ./4GS
=pe"i;ies w/i"/ p/oton output ;iles will be "reated.
./4GS ./4GS ./4GS ./4GS is any "o&bination o; t/e ;ollowing letters 5any order, wit/out
separators80
n nn n# none 5turn o;; all ;iles8
a aa a# all 5turn on all ;iles8
p pp p# pri&ary
c cc c# Co&pton
m mm m# &ultiple
r rr r# Rayleig/
t tt t# total 5su& o; p pp p, c cc c, m mm m and r rr r8
Note t/at n nn n overrides all ot/er ;lags and a aa a overrides t/e individual
;lags 5p pp p, c cc c, m mm m, r rr r, t tt t8.
E-a!ples
mcr mcr mcr mcr# only &ultiple, Co&pton and Rayleig/ ;iles will be "reated
ptn ptn ptn ptn# no ;iles will be "reated be"ause n nn n overrides all ot/er ;lags
an an an an# no ;iles will be "reated be"ause n nn n overrides all ot/er ;lags
cart cart cart cart# all ;iles will be "reated be"ause a aa a overrides all individual ;lags
./e de;ault is n nn n 5none8.
$o5 ./4GS
$$output$count ./4GS
=pe"i;ies w/i"/ "ount output ;iles will be "reated.
=ee above ;or t/e des"ription o; ./4GS ./4GS ./4GS ./4GS.
./e de;ault is a aa a 5all8.
$oE ./4GS
$$output$energ6 ./4GS
=pe"i;ies w/i"/ energy output ;iles will be "reated.
=ee above ;or t/e des"ription o; ./4GS ./4GS ./4GS ./4GS.
./e de;ault is n nn n 5none8.
$o+5 ./4GS
$$output$img$cnt ./4GS
=pe"i;ies w/i"/ i&age "ount output ;iles will be "reated.
=ee above ;or t/e des"ription o; ./4GS ./4GS ./4GS ./4GS.
pp :ser Manual -E
9 ,*-- Can"erCare Manitoba July +, ,*--
./e de;ault is a aa a 5all8.
$o+E ./4GS
$$output$img$e ./4GS
=pe"i;ies w/i"/ i&age energy output ;iles will be "reated.
=ee above ;or t/e des"ription o; ./4GS ./4GS ./4GS ./4GS.
./e de;ault is n nn n 5none8.
$o7 O,-+O(
$$output$!ose O,-+O(
=pe"i;ies t/at t/e dose s/ould be re"orded in a vo?eli@ed geo&etry
spe"i;ied in t/e input ;ile.
O,-+ O,-+ O,-+ O,-+O( O( O( O( is be one o; t/e ;ollowing0
text text text text# write dose to te?t ;ile
8in 8in 8in 8in# write dose to binary ;ile
text8in text8in text8in text8in# write dose to te?t and binary ;iles
Any ot/er value ;or O,-+O( O,-+O( O,-+O( O,-+O( will result in no dose output being "re>
ated.
./e de;ault is no value and t/us no dose output.
$e ,4-H
$$egs$home ,4-H
=ets t/e EGS_HOME EGS_HOME EGS_HOME EGS_HOME pat/ to ,4-H ,4-H ,4-H ,4-H instead o; t/e standard pat/ de;ined
by t/e EGS_HOME EGS_HOME EGS_HOME EGS_HOME environ&ent variable.
$H ,4-H
$$hen$house ,4-H
=ets t/e HE(_HO)SE HE(_HO)SE HE(_HO)SE HE(_HO)SE pat/ to ,4-H ,4-H ,4-H ,4-H instead o; t/e standard pat/ de>
;ined by t/e HE(_HO)SE HE(_HO)SE HE(_HO)SE HE(_HO)SE environ&ent variable.
$8
$$8atch
Runs t/e si&ulation in bat"/ &ode, i.e. an *.egslog output ;ile will
be "reated.
$, (
$$parallel (
=pe"i;ies t/e nu&ber 5( (( (8 o; parallel 3obs.
$9 +
$$9o8 +
=pe"i;ies t/e inde? 5+ ++ +8 o; t/is pro"ess in t/e list o; all pro"esses run>
ning in parallel.
$s
$$simple$run
=pe"i;ies t/at a si&ple run "ontrol ob3e"t s/ould be used ;or parallel
runs. ./is option is use;ul i; t/ere are issues wit/ lo"!ing t/e run "on>
trol ;ile ot/erwise reFuired ;or parallel runs.
$h
$$help
6rints t/is &essage.
./is option overrides all ot/er options.

Note t/at it is not re"o&&ended to use t/e $, and $9 "o&&and line argu&ents to run a si&ulation in
parallel &ode, instead t/e ex8 s"ript s/ould be used as des"ribed in t/e ne?t se"tion.
Also note t/at t/e si&ulation will not start i; t/e pp user "ode dire"tory "ontains previous output ;iles.
pp :ser Manual -%
9 ,*-- Can"erCare Manitoba July +, ,*--
2 $unnin% Epp in arallel wit& Multiple rocesses
./e si&ulation "an be run in parallel using &ultiple pro"esses. ./e easiest &et/od to laun"/ a parallel
run is to use t/e ex8 s"ript0
Usa%e# ex8 Epp +(,)-_.+/E ,EGS_.+/E p:(
+(,)-_.+/E +(,)-_.+/E +(,)-_.+/E +(,)-_.+/E is t/e na&e o; t/e input ;ile ;or t/e si&ulationI t/e input ;ile &ust be in t/e pp user "ode
dire"tory.
,EGS_.+/E ,EGS_.+/E ,EGS_.+/E ,EGS_.+/E is t/e pat/ to t/e 6<=E ;ile to be used ;or t/e si&ulationI t/e pat/ &ust eit/er be absolute
or relative to $HE(_HO)SE/pegs'/!ata/ or $EGS_HOME/pegs'/!ata/.
( (( ( is t/e nu&ber o; parallel pro"esses t/at will be runI t/is nu&ber s/ould not be &u"/ larger t/an t/e
nu&ber o; available p/ysi"al pro"essors be"ause t/ere is an over/ead "ost asso"iated wit/ swit"/ing be>
tween pro"esses, and t/us a larger nu&ber o; pro"esses will ta!e a longer ti&e to "o&plete.
Note t/at t/e swit"/es $i and $p are not present. 7or &ore in;or&ation about ex8, one "an si&ply e?e>
"ute ex8 wit/out any "o&&and line argu&ents.
A;ter sub&itting a parallel run, t/e user s/ould "/e"! w/et/er t/e pro"esses are a"tually running, by us>
ing top ;or e?a&ple, sin"e it is possible t/at t/e si&ulation ;ailed to start due to a &is"on;igured input
;ile, previous output ;iles being present in t/e output dire"tory or ot/er reasons.
An"e all 3obs /ave been sub&itted and it /as been veri;ied t/at t/ey are running, t/e user "an sa;ely
"lose t/e "onne"tion to t/e server and logout. A;ter t/e last pro"ess /as ;inis/ed its part o; t/e si&ula>
tion, it will auto&ati"ally "o&bine all t/e results ;ro& t/e ot/er pro"esses into single output ;iles. '/en
t/is is done, t/e user will be noti;ied by &ail 5in /2ar/mail8. ./e &ail "ontains t/e output ;ro& all pro">
esses and "ould provide /ints to w/at went wrong in "ase t/e si&ulation ;ailed to "o&plete.
3 Input (ile
./e input ;ile "ontains all in;or&ation reFuired to run t/e si&ulation, i.e. t/e geo&etry setup, t/e parti>
"le sour"e, t/e si&ulation para&eters, t/e dete"tor de;inition and ot/er para&eters.
?"ept ;or t/e &odi;i"ations des"ribed below, pp uses e?a"tly t/e sa&e input as t/e <=nr" CHH "lass
library, and t/e user s/ould re;er to t/at &anual 5)8 ;or a detailed des"ription o; t/e stru"ture o; t/e in>
put ;ile as well as t/e available options.
3.1 Additional Input
In addition to t/e standard <=nr" CHH "lass library input, an pp input ;ile "an "ontain t/e ;ollowing ad>
ditional in;or&ation. All o; t/e se"tions &ust be on t/e sa&e level as t/e geometry definition
se"tion.
pp :ser Manual -#
9 ,*-- Can"erCare Manitoba July +, ,*--
3.1.1. .etector .efinition
7or propagating t/e p/otons t/at le;t t/e si&ulation geo&etry onto a virtual dete"tor, t/e input ;ile
&ust "ontain t/e ;ollowing spe"i;i"ations ;or t/e dete"tor0
position t/e ?, y and @ "oordinates o; t/e
"enter o; t/e dete"tor
pi-el4si0e t/e si@e o; t/e individual pi?els in "&
in ? and y dire"tion
si0e t/e nu&ber o; pi?els on t/e dete"tor in ? and y dire"tion
Note t/at in t/e "urrent i&ple&entation o; pp, t/e dete"tor is always perpendi"ular to t/e @>a?is.
./is input is &andatory i; any "ount, energy or i&age output ;iles s/ould be "reated.
3.1.'. .ose Calculation
./e dose deposited in a vo?eli@ed volu&e, i.e. an <=OBCD<eo&etry, "an be re"orded and written to a
;ile. ./is reFuires t/at t/e user spe"i;ies t/e <=OBCD<eo&etry in w/i"/ t/e dose s/ould be re"orded
using t/e ;ollowing input ele&ent0
p&anto! t/e na&e o; t/e <=OBCD<eo&etry
5as de;ined in t/e geometry
definition se"tion or i&ported
wit/ an #egsphant dire"tive8 in
w/i"/ t/e dose s/ould be re"orded
./is input is &andatory i; any dose output ;iles s/ould be "reated.
3.1.3. Output Options
./e output options "an be spe"i;ied in t/e input ;ile as ;ollows0
p&otout spe"i;ies w/i"/ p/oton output ;iles
will be "reated
count spe"i;ies w/i"/ "ount output ;iles
will be "reated
ener%" spe"i;ies w/i"/ energy output ;iles
will be "reated
i!%5cnt spe"i;ies w/i"/ i&age "ount output ;iles will be "reated
i!%5e spe"i;ies w/i"/ i&age energy output ;iles will be "reated
dose spe"i;ies w/i"/ dose output ;iles will be "reated
:start detector definition:
position = 0, 0, 25
pixel size = 0.1, 0.1
size = 512, 512
:stop detector definition:
:start dose calculation:
phantom = my_phantom
:stop dose calculation:
:start output options:
photout = n
count = a
energy = a
img-cnt = n
img-e = n
dose = text
:stop output options:
pp :ser Manual -$
9 ,*-- Can"erCare Manitoba July +, ,*--
./ese options are eFuivalent to t/e $o,, $o5, $oE, $o+5, $o+E and $o7 "o&&and line argu&ents and
t/e possible values are t/e sa&e as t/e values ;or ./4GS ./4GS ./4GS ./4GS wit/ t/e "o&&and line argu&ents. =ee t/e
se"tion E ;or &ore in;or&ation.
Note t/at a "o&&and line argu&ent overrides t/e "orresponding option in t/e input ;ile. ./is input is
optional.
3.' $eferencin% Ot&er (iles
.o &a!e t/e input ;iles s&aller and &ore ;le?ible, t/ey "an "ontain re;eren"es to ot/er ;iles. Ane "an
re;eren"e anot/er ;ile using an #include PATH dire"tive. An #include dire"tive "an o""ur at any
pla"e in t/e input ;ile and also in re;eren"ed ;ilesI t/e only restri"tion is t/at t/e #include dire"tive
&ust be on a separate line. I&&ediately ;ollowing #include and e?tending to t/e end o; t/e line is
t/e PATH to t/e ;ile t/at is to be in"luded at t/is point in t/e re;eren"ing ;ile. PATH "an be a relative or
absolute pat/, i; it is a relative pat/, it &ust be relative to t/e dire"tory "ontaining t/e ;ile in w/i"/ t/e
#include dire"tive o""urs.
E-a!ple
./e two sa&ple ;iles on t/e le;t are in t/e sa&e dire"tory and result in t/e input on t/e rig/t.
input.egsinp input.egsinp input.egsinp input.egsinp

:start geometry definition:

#include box.geom

# more geometries
:stop geometry definition:

# more input
8ox.geom 8ox.geom 8ox.geom 8ox.geom
:start geometry:
library = egs_box
type = EGS_Box
box size = 5, 5, 10
name = my_box
:start media input:
media = water
:stop media input:
:stop geometry:

resulting input

:start geometry definition:

:start geometry:
library = egs_box
type = EGS_Box
box size = 5, 5, 10
name = my_box
:start media input:
media = water
:stop media input:
:stop geometry:

# more geometries
:stop geometry definition:

# more input

Note t/at proper indentation is not part o; t/e input synta? and only serves legibility. Also note t/at it is
t/e userQs responsibility to ensure t/at no "ir"ular re;eren"es o""ur.
pp :ser Manual -G
9 ,*-- Can"erCare Manitoba July +, ,*--
3.3 Usin% *.egsphant *.egsphant *.egsphant *.egsphant (iles
*.egsphant ;iles as used by DA=BCDnr" "an be dire"tly used wit/ pp as well. .o use an *.egsphant
;ile in an pp si&ulation t/e user /as to put a re;eren"e to t/e *.egsphant ;ile in t/e geometry
definition se"tion o; t/e input ;ile. An *.egsphant ;ile is re;eren"ed wit/ t/e #egsphant NAME
PATH dire"tive, w/i"/ will be auto&ati"ally repla"ed wit/ t/e de;inition o; an <=OBCD<eo&etry. NAME
is t/e na&e o; t/e <=OBCD<eo&etry and &ay not "ontain any spa"es. PATH is t/e pat/ to t/e
*.egsphant ;ile ;ro& w/i"/ t/e <=OBCD<eo&etry s/ould be "onstru"ted. ./e pat/ "an eit/er be abso>
lute or relativeI i; it is a relative pat/, it &ust be relative to t/e dire"tory "ontaining t/e ;ile in w/i"/ t/e
#egsphant dire"tive o""urs.
E-a!ple
./e ;ollowing e?a&ple de&onstrates t/e use o; an #egsphant dire"tive and /ow pp translates it into
an <=OBCD<eo&etry de;inition.
input.egsinp input.egsinp input.egsinp input.egsinp
:start geometry definition:

#egsphant my_phantom_name [path to the *.egsphant file]

# more geometries
:stop geometry definition:

# more input

resulting input
:start geometry definition:

:start geometry:
library = egs_ndgeometry
type = EGS_XYZGeometry
name = my_phantom_name
density matrix = [path to the density matrix file]
ct ramp = [path to the ct ramp file]
:stop geometry:

# more geometries
:stop geometry definition:

# more input

Note t/at t/e #egsphant dire"tive &ust be on a separate line and t/e pat/ o; to t/e *.egsphant ;ile
e?tends to t/e end o; t/at line.
pp :ser Manual -+
9 ,*-- Can"erCare Manitoba July +, ,*--
pp will auto&ati"ally "reate t/e density &atri? and "t ra&p ;iles based on t/e *.egsphant ;ile, and will
also re&ove t/e& a;ter t/e si&ulation /as su""ess;ully ;inis/ed. ./e two ;iles will be stored in t/e pp
dire"tory under t/e na&es (4ME.!ensit6_matrix and (4ME.ct_ramp.
6 Output (iles
./e p/oton and i&aging results o; t/e si&ulation are stored in ;ive di;;erent types o; output ;iles. ./ere
"an be up to ;ive ;iles ;or ea"/ type depending on t/e output options spe"i;ied wit/ t/e "o&&and line
argu&ents or in t/e input ;ileI see se"tions E and #.- ;or &ore in;or&ation. Dose output "an be stored in
te?t and1or binary ;or&at.
All ;iles o; t/e sa&e type /ave a di;;erent su;;i? 5p, c, m, r, or t8 t/at "orresponds to t/e p/oton "ategory
pri&ary, Co&pton, &ultiple, Rayleig/ or total.
In addition to t/ese output ;iles, pp also "reates an *.egs!at ;ile ;or ea"/ pro"ess t/at was run. ./ese
;iles "ontain t/e results o; t/e individual pro"esses and are reFuired to "o&bine t/e results o; all pro">
esses at t/e end o; a parallel run. Also, i; pp is e?e"uted in bat"/ &ode, an *.egslog ;ile "ontaining t/e
"o&&and line output will be "reated ;or ea"/ pro"ess.
6.1 &oton Output (iles
./e p/oton output ;iles 5*.phot_0p;c;m;r;t1.out8 "ontain detailed in;or&ation about every p/oton
t/at /as le;t t/e si&ulation geo&etry travelling in positive D dire"tion. ./e in;or&ation is stored in bi>
nary and ea"/ p/oton entry is e?a"tly ), bytes long. Ane p/oton entry "onsists o; eig/t E>byte single
pre"ision ;loating point nu&bers.
./e ;ollowing diagra& illustrates t/e ;or&at o; a p/oton output ;ile0
? y @ u v w wt ? y ... R
;loat ;loat ;loat ;loat ;loat ;loat ;loat ;loat ;loat ;loat ... R
;irst p/oton S ), bytes ne?t p/oton S ), bytes ot/er p/otons

./e eig/t nu&bers &a!ing up one p/oton entry /ave t/e ;ollowing &eaning0
-1 "1 0 are t/e ?, y, and @ "oordinates o; t/e "urrent lo"ation o; t/e p/oton
u1 v1 w are t/e ?, y, and @ "o&ponents o; a unit ve"tor des"ribing t/e "urrent dire"tion o; travel o;
t/e p/oton, alternatively t/ese nu&bers "an also be interpreted as t/e "osines o; t/e an>
gles o; t/e "urrent dire"tion o; t/e p/oton wit/ t/e ?>, y>, and @>a?is
E is t/e energy o; t/e p/oton in MeV
wt is t/e statisti"al weig/t o; t/e p/oton
pp :ser Manual ,*
9 ,*-- Can"erCare Manitoba July +, ,*--
Due to t/e way t/at t/e <=nr" CHH "lass library parti"le sour"es are i&ple&ented, one "annot si&ply
"ount dis"rete p/otons on t/e dete"torI instead one /as to su& t/e statisti"al weig/ts o; t/e p/otons.
=i&ilarly, ;or re"ording t/e total energy deposited in t/e dete"tor, t/e energy o; ea"/ individual p/oton
/as to be &ultiplied by its statisti"al weig/t and t/en t/is produ"t will "ontribute towards t/e total en>
ergy. ./e su& o; t/e statisti"al weig/ts or t/e su& o; t/e energies &ultiplied by t/e statisti"al weig/ts
&ust t/en be divided by t/e average statisti"al weig/t o; all p/otons generated by t/e sour"e. ./is step
is ne"essary to obtain &eaning;ul values so t/at t/e su& o; t/e statisti"al weig/tsTeven t/oug/ it is a
;ra"tionT"orresponds to t/e nu&ber o; p/otons.
pp applies t/is "orre"tion auto&ati"ally to t/e output ;iles des"ribed below, but i; t/e user wants to
read t/e si&ulation results ;ro& t/e p/oton output ;iles dire"tly, t/e "orre"tions /ave to be done &anu>
ally. 7or t/is purpose, pp "reates anot/er output ;ile 5*.a2erage<eight.out8 "ontaining t/e overall
average statisti"al weig/t as one E>byte single pre"ision ;loating point nu&ber in binary. ./is ;ile is only
"reated i; at least one p/oton output ;ile was "reated.
Note t/at pp does not "o&bine t/e p/oton output ;iles o; di;;erent pro"esses running in parallel. 7or
ea"/ pro"ess, di;;erent p/oton output ;iles will be "reated as spe"i;ied by t/e output options.
(y de;ault no p/oton output ;iles will be "reated.
6.' Count and Ener%" Output (iles
./e "ount 5*.count_0p;c;m;r;t1.out8 and energy 5*.energ6_0p;c;m;r;t1.out8 output ;iles "on>
tain t/e nu&ber o; p/otonsTa"tually t/e su& o; t/e statisti"al weig/ts as e?plained aboveTand t/e to>
tal energy deposited in ea"/ pi?el o; t/e dete"tor. ./e in;or&ation is stored in binary and ;or ea"/ pi?el
t/ere is one E>byte single pre"ision ;loating point nu&ber. ./e pi?els are arranged in row>&a3or order,
i.e. one ;ull row is stored a;ter anot/er. 7or one row t/e pi?els are stored ;ro& le;t to rig/t and t/e rows
are stored ;ro& top to botto&.
In addition to t/e data ;or ea"/ individual pi?el o; t/e dete"tor, t/e ;irst eig/t bytes o; t/e ;ile "ontain
two E>byte integers t/at spe"i;y t/e nu&ber o; pi?els in ? dire"tion 5"olu&ns8 and y dire"tion 5rows8.
./e ;ollowing diagra& illustrates t/e ;or&at o; a "ount or energy output ;ile0
N? Ny 65-,-8 65-,,8 65-,)8 R 65,,-8 65,,,8 65,,)8 R ...
int int ;loat ;loat ;loat R ;loat ;loat ;loat R ...
E bytes E bytes ;irst row S N? U E bytes se"ond row S N? U E bytes ot/er rows

7-1 7" are t/e nu&ber o; pi?els in ? dire"tion 5"olu&ns8 and y dire"tion 5rows8
8i19: is t/e total nu&ber o; p/otons or total energy 5ad3usted su& o; statisti"al weig/ts8 t/at
was deposited in t/e pi?el in t/e i>t/ row and 3>t/ "olu&n, i M - . . Ny, 3 M - .. N?
pp :ser Manual ,-
9 ,*-- Can"erCare Manitoba July +, ,*--
./e ;ile *ea!EppOutput.m in t/e pp installation dire"tory "an be used to read t/ese output ;iles di>
re"tly into MA.LA(.
Note t/at a;ter t/e last pro"ess o; a parallel run /as ;inis/ed, t/e results o; all pro"esses are "o&bined
and stored into single "ount and energy output ;iles.
(y de;ault all "ount and no energy output ;iles will be "reated.
6.3 I!a%e Output (iles
./e i&age "ount 5*.image$count_0p;c;m;r;t1.8mp8 and i&age energy 5*.image$energ6_
0p;c;m;r;t1.8mp8 output ;iles "ontain t/e "ount and energy on t/e dete"tor visuali@ed as i&ages. ./e
pi"tures are in gray s"ale wit/ @ero p/otons1energy being bla"! and t/e /ig/est nu&ber o; p/otons1 en>
ergy in t/at "ategory being w/ite. All values in between are linearly s"aled.
Note t/at a;ter t/e last pro"ess o; a parallel run /as ;inis/ed, t/e results o; all pro"esses are "o&bined
and stored into single i&age output ;iles.
(y de;ault all i&age "ount and no i&age energy output ;iles will be "reated
6.4 .ose Output (iles
./e dose deposited in a vo?eli@ed volu&e, i.e. an <=OBCD<eo&etry, "an be re"orded and written to a
te?t 5*.=!!ose8 and1or binary ;ile 5*.!ose.out8. ./e ;or&at o; t/e *.=!!ose ;ile is e?a"tly t/e sa&e as
t/e *.=!!ose ;iles "reated by DA=BCDnr" 5,8, but unli!e DA=BCDnr", pp does not nor&ali@e t/e dose
wit/ t/e in"ident parti"le ;luen"e. All values e?"ept t/e ;irst t/ree integers are stored as G>byte double
pre"ision ;loating point nu&bers.
./e ;ollowing diagra& illustrates t/e ;or&at o; t/e *.!ose.out binary ;ile0
N? Ny N@ ?b5*8 ?b5-8 R yb5*8 yb5-8 R @b5*8 @b5-8 R

int int int double double R double double R double double R

E bytes E bytes E bytes ?>bounds S 5N? H -8 U G bytes y>bounds S 5Ny H -8 U G bytes @>bounds S 5N@ H -8 U G bytes



d5*8 d5-8 d5,8 R err5*8 err5-8 err5,8 R

double double double R double double double R
dose values S N? U Ny U N@ U G bytes error values S N? U Ny U N@ U G bytes




pp :ser Manual ,,
9 ,*-- Can"erCare Manitoba July +, ,*--
./e *.=!!ose te?t ;ile /as t/e ;ollowing ;or&at0
)ine ; Content
1
2
3
4
5
6
Nx Ny Nz
xb(0) xb(1) ... [Nx + 1 values]
yb(0) yb(1) ... [Ny + 1 values]
zb(0) zb(1) ... [Nz + 1 values]
d(0) d(1) d(2) ... [Nx Ny Nz values]
err(0) err(1) err(2) ... [Nx Ny Nz values]

7-1 7"1 70 are t/e nu&ber o; vo?els in ?, y and @ dire"tion
-b8i: is t/e i>t/ vo?el boundary in B dire"tion, i M * .. N?
"b8i: is t/e i>t/ vo?el boundary in C dire"tion, i M * .. Ny
0b8i: is t/e i>t/ vo?el boundary in D dire"tion, i M * .. N@
d8id-: is t/e dose 5unit <rays8 in t/e vo?el wit/ inde? id?, id? M * .. N? U Ny U N@ > -
err8id-: is t/e relative error o; t/e dose value in t/e vo?el wit/ inde? id?, id? M * .. N? U Ny U N@ > -
id? M ? H y U N? H @ U N? U Ny, w/ere ?, y and @ are t/e indi"es o; t/e vo?el in ?, y and @ dire"tion,
? M * .. N? > -, y M * .. Ny > -, @ M * .. N@ > -
Note t/at a;ter t/e last pro"ess o; a parallel run /as ;inis/ed, t/e results o; all pro"esses are "o&bined
and stored into single dose output ;iles.
(y de;ault no dose output ;iles will be "reated.
< Version =istor"
Version 1.>.> Tue '1 ?ul '>>@
7irst stable version wit/ all "ore ;eatures i&ple&ented.
Version 1.1.> (ri '4 ?ul '>>@
Added ;eature ;or re"ording deposited energy on t/e dete"tor.
Version 1.'.> Mon 31 Au% '>>@
Added support ;or reading J.egsp/ant ;iles wit/ t/e #egsphant dire"tive.
Version 1.'.1 /ed >' ,ep '>>@
7i?ed a bug t/at "aused so&e s"attered p/otons to be ;alsely labelled as pri&ary p/otons.
7i?ed a bug t/at "aused a substantial nu&ber o; pri&ary p/otons to be ;alsely labelled as Co&p>
ton s"attered w/en bound Co&pton s"attering was turned on.
pp :ser Manual ,)
9 ,*-- Can"erCare Manitoba July +, ,*--
Version 1.'.' Tue >3 7ov '>>@
C/anged propagation o; p/otons to t/e dete"tor to re&ove an o;;set o; t/e w/ole i&age on t/e
dete"tor.
Version 1.3.> (ri '> 7ov '>>@
Dropped BML support ;or input ;iles and regressed to t/e original <=nr" CHH Classs Library input
;or&at.
Version 1.3.1 /ed '2 7ov '>>@
7i?ed so&e &inor bugs related to t/e na&es o; t/e output ;iles and ;i?ed a bug related to i&port>
ing J.egsp/ant ;iles ;ro& a di;;erent dire"tory.
Version 1.3.' /ed >3 (eb '>1>
7i?ed a bug related to running pp in parallel.
Version 1.4.> T&u '@ Apr '>1>
:pdated to use version ,.).- o; <=nr" VE.
Redu"ed t/e "/anges &ade to t/e original <=nr" CHH "lass library sour"e "ode.
C/anged t/e opti&i@ation level to - instead o; ) to avoid an arte;a"t t/at would ot/erwise s/ow
up on generated i&ages.
7i?ed a bug t/at prevented t/e "o&&and line argu&ents $h and $$help ;ro& /aving any e;;e"t.
Introdu"ed a "/e"! to &a!e sure t/at t/e input and pegs ;ile are spe"i;ied.
Added a new "o&&and line option $pr or $$parse t/at parses a given ;ile and resolves all #in$
clu!e and #egsphant dire"tives, w/i"/ is very use;ul to view an input ;ile t/at uses t/ese dire">
tives wit/ egs_2ie3, ;or e?a&ple.
Version 1.4.1 T&u >3 ?un '>1>
7i?ed bug t/at ;alsely labelled so&e p/otons as Co&pton s"attered w/en bound Co&pton s"atter>
ing is turned on. ./is ;i? was introdu"ed in version -.,.-, but it got lost.
Version 1.4.' (ri >3 Ma" '>11
7i?ed a bug t/at propagated p/otons to t/e dete"tor ba"!wards w/en t/e p/oton would not /it
t/e dete"tor going in its "urrent dire"tion. Now only p/otons t/at /it t/e dete"tor going ;orward
5in t/e "urrent dire"tion w/en t/ey leave t/e si&ulation geo&etry8 are s"ored on t/e dete"tor.
Re&oved restri"tion t/at only propagated p/otons to t/e dete"tor t/at were going in t/e positive
@ dire"tion. Now pp "an be used to analy@e ba"!s"atter as well.
7i?ed phantom_1&cm.egsphant, w/i"/ was an air "ylinder inside water instead o; a water "ylin>
der inside air.
Version 1.4.3 ,at >@ ?ul '>11
7i?ed a bug t/at did not ;ree so&e allo"ated &e&ory.
pp :ser Manual ,E
9 ,*-- Can"erCare Manitoba July +, ,*--
@ $eferences
-. I. AawraBow1 E. Maine%ra5=in%1 ../.O. $o%ers1 (. Tessier and C.$.C. /alters. The EGSnrc Code
System: Monte Carlo Simulation of Electron and Photon Transport. Attawa, Canada 0 National Resear"/
Coun"il o; Canada, ,*-*. Available online at /ttp011irs.in&s.nr"."a1so;tware1egsnr"1do"u&entation1
pirs$*-1. NRCC Report 6IR=>$*-.
,. C. /alters1 I. AawraBow and ../.O. $o%ers. DOSXYnrc !sers Manual. Attawa, Canada 0 National
Resear"/ Coun"il o; Canada, ,**+. Available online at /ttp011irs.in&s.nr"."a1so;tware1bea&nr"1
do"u&entation1pirs$+E1. NRCC Report 6IR=>$+Erev(.
). I. AawraBow1 E. Maine%ra5=in%1 (. Tessier and C.$.C. /alters. The EGSnrc C"" class li#rary. Attawa,
Canada 0 National Resear"/ Coun"il o; Canada, ,**+. Available online at /ttp011irs.in&s.nr"."a1so;tware1
egsnr"1do"u&entation1pirsG+G1. NRC Report 6IR=>G+G 5rev A8.
E. I. AawraBow1 E. Maine%ra5=in% and .. /. O. $o%ers. EGSnrcMP: the multi$platform en%ironment for
EGSnrc. Attawa, Canada 0 National Resear"/ Coun"il o; Canada, ,**#. Available online at
/ttp011irs.in&s.nr"."a1so;tware1egsnr"1do"u&entation1pirsG$$1. NRCC Report 6IR=>G$$.