Pen Redguide 1

PenRed: User Manual
V. Giménez-Alventosa1 , V. Giménez Gómez2 , and S. Oliver3

1
Departament de Fı́sica Atòmica Molecular i Nuclear, Universitat de València , Dr.
Moliner, 50, 46100, Burjassot, València, Spain, [email protected]
2
Departament de Fı́sica Teòrica and IFIC, Universitat de València-CSIC , Dr.
Moliner, 50, 46100, Burjassot, València, Spain,
3
Instituto de Seguridad Industrial, Radiofı́sica y Medioambiental (ISIRYM),
Universitat Politècnica de València, Camı́ de Vera s/n, 46022, València, Spain,
[email protected]
September 15, 2023
Abstract
The present document is a manual of the PenRed code system which content is
focused on the description of the framework usage. PenRed is a general-purpose, stand-
alone and extensible framework code based on PENELOPE for parallel Monte Carlo
simulations of radiation transport through matter. It has been implemented in C++
programming language and takes advantage of modern object-oriented technologies.
In addition, PenRed offers, among other features, the capability to read and process
DICOM images to perform simulations. These feature facilitate its usage in medical ap-
plications. Our framework has been successfully tested against the original PENELOPE
Fortran code.
1 Introduction
The present document contains all the necessary information to use the PenRed [1] frame-
work. That is, all the available modules already included in the package and the provided
main program. This document is not intended to describe how to implement new compo-
nents or describe in detail the code structure. That information can be found in the PenRed
implementation manual and component manual (in development) respectively.
1.1 What is PenRed?

PenRed is a fully parallel, modular and customizable framework for Monte Carlo simula-
tions of the passage of radiation through matter. It is based on the PENELOPE [2] code
system, from which inherits its unique physics models and tracking algorithms for charged
particles. For further details on the interactions models, the reader is referred to the excel-
lent PENELOPE manual [3]. PenRed has been coded in C++ following an object-oriented
V. Giménez-Alventosa https://orcid.org/0000-0003-1646-6094
V. Giménez Gómez https://orcid.org/0000-0003-3855-2567
S. Oliver https://orcid.org/0000-0001-8258-3972
1
programming paradigm restricted to the C++11 standard. Our engine implements paral-
lelism via a double approach: on the one hand, by using standard C++ threads for shared
memory, improving the access and usage of the memory, and, on the other hand, via the
MPI standard for distributed memory infrastructures. Notice that both kinds of parallelism
can be combined together in the same simulation. In addition, PenRed provides a modular
structure with methods designed to easily extend its functionality. Thus, users can create
their own independent modules to adapt our engine to their needs without changing the
existing ones. Furthermore, user extensions will take advantage of the built-in parallelism
without any extra effort or knowledge of parallel programming.
1.2 Document structure

The manual is organized as follows. The section 2 shows a useful guide of installation and
execution of the framework to run simulations. Section 3 provides some information of
the internal data structure format used to configure the simulations. In section 4 a briefly
description of important definitions, constants, parameters and units is shown. Following,
section 5, shows how to execute the main program provided within the PenRed package, and
describes all the implemented tallies, sources, geometries, variance reduction techniques and
other parameters to configure the simulation. Then, in the section 6, the examples located
in the examples folder, which are ready to be simulated, are described. Finally, the offered
utilities in the PenRed package and how to use them are explained in the section 7.
Notice that the section 4 summarise some useful definitions necessary to understand the
code and its operation.
2
Contents
1 Introduction 1
1.1 What is PenRed? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2 Document structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2 Installation and execution 5

2.1 Linux instalation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2 Windows instalation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.3 Basic usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.4 Optional features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3 Internal data format 11

3.1 Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4 Constants, parameters and definitions 12

4.1 Important definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4.2 Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.3 Particle indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.4 Particle interaction indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.5 Atomic electron shells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
5 Framework usage 16
5.1 Materials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
5.1.1 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
5.2 Particle sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
5.2.1 Spatial source samplers . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.2.2 Direction samplers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.2.3 Energy samplers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.2.4 Time samplers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
5.2.5 Specific Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5.3 Geometries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5.3.1 Geometry visualization . . . . . . . . . . . . . . . . . . . . . . . . . 31
5.3.2 Quadric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5.3.3 Triangular Mesh Surfaces . . . . . . . . . . . . . . . . . . . . . . . . 32
5.3.4 Voxel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
5.3.5 DICOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
5.3.6 Combo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
5.4 Tallies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
5.4.1 Radial and Cylindrical Dose Distribution . . . . . . . . . . . . . . . 42
5.4.2 Emerging Particles Distribution . . . . . . . . . . . . . . . . . . . . . 43
5.4.3 Energy Deposition Body . . . . . . . . . . . . . . . . . . . . . . . . . 43
5.4.4 Energy Deposition Material . . . . . . . . . . . . . . . . . . . . . . . 44
5.4.5 Impact Detector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
5.4.6 Spatial Dose Distribution . . . . . . . . . . . . . . . . . . . . . . . . 46
5.4.7 Angular Detector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
5.4.8 Particle Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
5.4.9 Spherical Dose Distribution . . . . . . . . . . . . . . . . . . . . . . . 48
5.4.10 Phase Space File (PSF) . . . . . . . . . . . . . . . . . . . . . . . . . 49
5.4.11 Kerma track length estimator . . . . . . . . . . . . . . . . . . . . . . 49
3
5.4.12 CT tally . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
5.4.13 DICOM kerma tally (Dose Volume Histogram) . . . . . . . . . . . . 53
5.4.14 Primary and Scatter Separated (PSS) . . . . . . . . . . . . . . . . . 55
5.5 Variance Reduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
5.5.1 Context specific . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
5.5.2 Specific VR techniques . . . . . . . . . . . . . . . . . . . . . . . . . . 57
5.5.3 Generic VR techniques . . . . . . . . . . . . . . . . . . . . . . . . . . 58
5.6 Simulation parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
5.6.1 Dump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
5.6.2 Threading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
5.6.3 Seeds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
5.6.4 Simulation time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
5.7 Image output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
5.8 Load balance parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
6 Examples 63
6.1 1-disc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
6.1.1 1-disc-no-vr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
6.1.2 1-disc-vr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
6.2 2-plane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
6.3 3-detector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
6.4 4-x-ray-tube . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
6.5 5-accelerator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
6.5.1 5-accelerator-1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
6.5.2 5-accelerator-2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
6.5.3 5-accelerator-3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
6.6 6-polarisation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
6.7 7-aba . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
6.8 8-fake-chamber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
6.8.1 8-fake-chamber-novr . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
6.8.2 8-fake-chamber-vr . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
7 Utilities 67
7.1 Blender Geometry Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
7.1.1 Quadric Geometries . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
7.1.2 Triangular Mesh Surfaces . . . . . . . . . . . . . . . . . . . . . . . . 71
7.2 Mutren . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
7.3 iaeaPSF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
7.4 geo2voxel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
7.5 geo2mesh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
7.6 range . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
7.7 PSF spectrum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
7.8 PSF to ASCII . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
7.9 Registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
A Predefined materials 76
4
2 Installation and execution
Some PenRed features depends on few external libraries which should be installed to activate
the corresponding features (see below). It is the user’s responsibility to check that these
external dependencies are installed before activating a feature. The user should refer to the
appropriate installation guides of the optional packages.
PenRed should be able to compile with any compiler with C++ 11 standard support
and CMake version 3.4 or greater. It has been tested with g++ versions 4.7.3 to 11, Intel
icc version 2019, clang version 8 and MSVS 2019.
2.1 Linux instalation

The installation of PenRed is very easy. First, download PenRed sources from our GitHub
repository,
git clone https://github.com/PenRed/PenRed.git
The code must be compiled in the src folder, which includes a CMake file and a bash
script (compile.sh) to simplify the installation and compile the code automatically. In this
script, you can enable/disable the following main optional features,
• DICOMs: If it is enabled, PenRed capabilities to read and simulate DICOM images

will be active. This option requires the library dicom toolkit (dcmtk) [4].
• Multi-threading: This option enables multi-threading capabilities. PenRed imple-

ments multi-threading via the standard thread library specified in the C++11 stan-
dard. Thus, it is not required any extra library to enable this option.
• MPI: This option enables MPI simulations. It requires a library with an implemen-
tation of the MPI standard, such as openmpi [5] or mpich [6].
• Load balance: Enables load balancing system between threads and MPI processes.
This option requires, as least, multi-threading capabilities, because uses threads to
handle MPI communications.
Notice that all previous dependencies are optional. The corresponding libraries can be
found at most linux package repositories. For example, to compile PenRed with DICOM
support in Fedora, you can use the dnf command to install the dcmtk library,
sudo dnf install dcmtk dcmtk-devel
and the following to install its dependencies,
sudo dnf install libjpeg libjpeg-devel libxml2 libxml2-devel openssl openssl-devel
Once the dependencies are installed, the compilation can be done using the provided script,
bash compile.sh
or doing it yourself,
5
cd /path/to/PenRed/repository/src
mkdir build
cd build
ccmake ../
make -jN (with N the number of processes)
make install
With ccmake you can configure the optional PenRed features with a more friendly interface.
But, of course, you can use directly cmake ../ defining the appropriate flags like,
cmake -DWITH DICOM="ON" -DWITH MULTI THREADING="ON"

-DWITH MPI="OFF" -DWITH LB="OFF" -DDEVELOPMENT WARNINGS="OFF" ../
Once the code has been compiled, the user can found the executable of our provided main
program ready to simulate at,
src/compiled/mains/pen main
2.2 Windows instalation

To compile the PenRed code using MSVS on windows, first, select “Clonea repository” from
the Visual Studio start window (Figure 1).
Figure 1: Clone a repository in MSVS
Then, set the PenRed repository url and push on the clone button (Figure 2).
6
Figure 2: Clone PenRed repository with MSVS
The download will start automatically. Once the Cmake configuration ends, to avoid
compiling with a debug profile, add a new configuration with the configuration manager
(Figure 3).
Figure 3: Manage MSVS configurations
In the configuration panel to the left, click on the button with the green plus sign to
add a new configuration and select the release depending on your system. In the following
image, we selected a release for 64-bit system (Figure 4).
7
Figure 4: Add configuration in MSVS
Once you have selected the new configuration, and push on “Save and generate CMake
cache to load variables” to be able to change the CMake variables for this configuration and
compile it (Figure 5).
Figure 5: Select configuration in MSVS
Now, we can change all the Cmake configuration variables to enable or disable MPI
support and other features (Figure 6).
8
Figure 6: Set compilation flags in MSVS
Finally, build and install PenRed (Figure 7).
Figure 7: Build and install PenRed in MSVS
If the compilation finishes successfully, a new folder named compiled will be created
inside the src folder containing the PenRed’s main program and the executable for all other
enabled utilities (Figure 8).
Figure 8: PenRed compiled programs
9
2.3 Basic usage
To execute the program, the user needs a configuration file and, probably, the required
data base files, such as material and geometry files. Their path should be specified at the
configuration, remaining the configuration file path as the only program argument. All the
details regarding the simulations configuration can be found in the section 5. Moreover, the
examples folder contain several configuration file examples with the corresponding material
and geometry files ready to be executed (section 6). So, to execute the program, the user
must use
./pen main path/to/configuration/file
Otherwise, if the MPI capabilities have been enabled at the compilation, the code should
be executed as any MPI program, for example,
mpirun -np Nprocesses ./pen main path/to/configuration/file
where Nprocesses specify the number of MPI processes to use. Of course, the user can
use any other options of the mpirun command, such us specify the hosts where execute the
code via the hostfile option.
2.4 Optional features

The following list summarise the optional compilation flags available during the PenRed
compilation procedure.
• BUILD UTILITIES: Enables or disable the compilation of utilities, such as geo2vox,

sampler, geometry and tally registers or load balance server. If enabled, the compila-
tion of each utility can be enabled or disabled individually.
• WITH MULTI THREADING: Handles multithreading capabilities.
• WITH MPI: Handles MPI capabilities. Require an MPI library installed.
• WITH NATIVE: Switch on or off the compilation with native optimizations. Ac-
tually, this flag only works on GCC and Intel C++ compilers.
• WITH DICOM: Handles DICOM capabilities. Requires the dcmtk library.
• WITH LB: Enables or disables load balance capabilities. If enabled, some optional
features related with the balance system can be configured:
– WITH SSL: Enables or disables SSL secure connections for TCP or HTTPS
communications. Requires OpenSSL libraries and its dependences.
– WITH HTTP: Enables or disables connections to a HTTP/HTTPS rest api
as balance server (Experimental feature). Requires the libCurl library.
• BUILD TESTS: Enables or disable the compilation of test codes.
• DEVELOPMENT WARNINGS: Enables or disables development warning flags.
10
3 Internal data format
src/kernel/parsers
To provide a unified format for input and configuration, PenRed implements a set of data
structures. This implementation can be found in the following files,
src/kernel/parsers/includes/pen data.hh
and
src/kernel/parsers/source/pen data.cpp
The format used in PenRed is basically a key/value pair where the key format is based on
unix folder system, i.e. a generic key is a string with the following structure:
/f older1/f older2/.../element
On the other hand, the value can be a number, bool (True or False), character, string
or an array of numbers, bools or characters. Notice that these types can be combined in a
single array. Also, strings must be made with double quotes (”text”) to be parsed correctly.
For example, code 1 shows a configuration for a cylindrical dose distribution tally.
1 t a l l i e s / c y l D o s e D i s t r i b / type ”CYLINDRICAL DOSE DISTRIB”
2 t a l l i e s / c y l D o s e D i s t r i b / p r i n t −xyz t r u e
3 t a l l i e s / c y l D o s e D i s t r i b / rmin 0 . 0
4 t a l l i e s / c y l D o s e D i s t r i b /rmax 3 0 . 0
5 t a l l i e s / c y l D o s e D i s t r i b / n b i n s r 60
6 t a l l i e s / c y l D o s e D i s t r i b / zmin 0
7 t a l l i e s / c y l D o s e D i s t r i b /zmax 3 0 . 0
8 t a l l i e s / c y l D o s e D i s t r i b / n b i n s z 60
Code 1: Internal data example
3.1 Implementation
This section provides a brief explanation of internal data implementation. PenRed internal
data structure consists of four classes where each one uses the previous class to create a
more complex structure. First, pen parserData is basically a union with four allowed types:
char, int, double and bool. Notice that pen parserData can’t be a string or pointer. Next,
pen parserArray is a standard C++ vector of pen parserData variables. The third class is
pen parserElement, which can store a C++ string or a pen parserArray variable. Finally,
pen parserSection stores a C++ map where each key-value pair uses the types,
< std :: string|pen parserArray >
where the left element is the pair key and the right element is the pair value. As we
mentioned at previous section, key format follows the structure of Unix paths, i.e. ,
/folder1/folder2/element.
In our schema, each “folder” will be considered as a “section”. On the other hand, a key
with no sub-folders is considered an “element”. Notice that keys whose include an element
11
path as a section are not allowed and the program will return an error or overwrite this
element according to the called function. Thus, the following configuration can’t exist in a
input format map structure,
/folder1/folder2/element
/folder1/folder2/element/element2
since element is not a section and therefore cannot contain any other section nor element.
For further information and usage examples, consult the provided examples in src/tests/internalData
folder.
4 Constants, parameters and definitions

This section summarises some important constants and values of the PenRed engine.
4.1 Important definitions

• Void region/volume: Geometry region with material index 0.
• Primary particle: Particle produced directly by a source and not as a consequence

of any interaction of some other particle.
• Secondary particle: Particle produced by some interaction of other particle.
• History: A history consists of a primary particle and all its derived secondary parti-
cles.
• Particle simulation: Encompasses since the particle enters into a non void region
of the geometry system, until it is absorbed or escaped from the system.
• History simulation: Includes all the particle simulations of the particles conforming
the history.
• Source simulation: Includes all the history simulations due primary particles pro-
duced by the source.
• Global simulation: Consists of all source simulations.
• Particle state: All variables stored at the corresponding state structure, which base
type should be the provided pen particleState.
• Object state: We refer as a object state to the values of its internal variables, regard-
less if they are private, public or protected. Also, inherited variables are considered
as part of the object state. For example, lets see the objects defined at the code 2.
The state of an object of the first type A, consists of the variables a1, a2 and a3. On
the other hand, the state of an object B consists of a1, a2, a3, b1 and b2, due the
inheritance from the class A.
1
2 c l a s s A{
3 protected :
4 i n t a1 , a2 ;
5 public :
6 d o u b l e a3 ;
7
12
8 A( ) : a1 ( 0 ) , a2 ( 2 ) , a3 ( 5 . 3 ) {}
9
10 v o i d do1 ( ) ;
11 v o i d do2 ( ) ;
12 };
13
14 c l a s s B : p u b l i c A{
15 private :
16 i n t b1 ;
17 public :
18 d o u b l e b2 ;
19
20 B( ) : b1 ( 0 ) , { }
21
22 v o i d doB1 ( ) ;
23 v o i d doB2 ( ) ;
24 };
25
Code 2: Source configuration parameters
• Verbose levels: Verbose levels consists of a set of non negative indexes that indi-
cates how verbose will be our execution. The meaning of that levels are summarised
following,
– 0: Any message should be printed.

– 1: Only error messages should be printed.
– 2: Errors, warnings and important information should be printed.
– > 2: Prints all relevant information.
Optionally, greater verbose levels could be used to filter very verbose information.
• ILB values: ILB labels follows the definition of the PENELOPE package, which are
summarised at the table extracted from the PENELOPE manual [3]. Notice that our
index begins from 0 because C++ syntax but at the FORTRAN code the first index
is 1.
13
ILB description
ILB[0] Generation of the particle; 1 for primary particles, 2 for their direct descen-
dants and so on. Primary particles are assumed to be labelled with ILB[0] = 1.
ILB[1] Parent particle kpar index (see table 3), only if ILB[0] > 1.
ILB[2] Interaction mechanism ICOL (see tables at section 4.4) that originated the
particle, only when ILB[0] > 1.
ILB[3] A non-zero value identifies particles emitted from atomic relaxation events and
describes the atomic transition where the particle was released. The numerical
value is,
ILB[3] = Z × 106 + IS1 × 104 + IS2 × 100 + IS3 (1)

where Z is the atomic number of the emitting atom and IS1, IS2 and IS3
are the labels of the active atomic electron shells (see table 7).
For instance, ILB[3] = 29010300 designates a K − L2 x ray from copper
(Z = 29), and ILB[3] = 29010304 indicates a K − L2 − L3 Auger electron
from the same element.
When ILB[3] 6= 0, the value of ILB[2] indicates the itneraction mechanism
that caused the initial vacancy in the decaying atom.
ILB[4] This label can be defined by the user and must be transferred to all particle
descendants.
Table 1: Description of the ILB components
4.2 Units
PenRed supposes the use of specific units internally. These units are summarised at the
table 2.
Magnitude Unit
Length cm
Energy eV
Time s
Material mass g
Density g/cm3
Table 2: PenRed internal units.
4.3 Particle indexes

As we saw at section ??, each particle requires a index identifier provided via the enumer-
ation pen KPAR. Actually PenRed particle indexes and names are summarised at table
3.
particle name Enumeration identifier Numerical index

electron PEN ELECTRON 0
gamma PEN PHOTON 1
positron PEN POSITRON 2
Table 3: Particle indexes and names.
14
4.4 Particle interaction indexes
PenRed uses enumerations to indexing the interactions of each particle. This section show
the corresponding index for each particle interaction.
Interaction Enumeration identifier Numerical index

Elastic collision BETAe HARD ELASTIC 0
Inelastic collision BETAe HARD INELASTIC 1
Bremsstrahlung BETAe HARD BREMSSTRAHLUNG 2
Inner shell interaction BETAe HARD INNER SHELL 3
Delta interaction BETAe DELTA 4
Soft interaction BETAe SOFT INTERACTION 5
Table 4: Electron interaction indexes.

Rayleigh GAMMA RAYLEIGH 0
Compton GAMMA COMPTON 1
Photoelectric GAMMA PHOTOELECTRIC 2
Pair production GAMMA PAIR PRODUCTION 3
Delta interaction GAMMA DELTA 4
Table 5: Photon interaction indexes.

Elastic collision BETAp HARD ELASTIC 0
Inelastic collision BETAp HARD INELASTIC 1
Bremsstrahlung BETAp HARD BREMSSTRAHLUNG 2
Inner shell interaction BETAp HARD INNER SHELL 3
Annihilation BETAp ANNIHILATION 4
Delta interaction BETAp DELTA 5
Soft interaction BETAp SOFT INTERACTION 6
Table 6: Positron interaction indexes.
4.5 Atomic electron shells

The atomic electron shells labels are designed following the indexes used at PENELOPE
code. These indexes are summarised at the table 7, which has been extracted from the
PENELOPE manual [3].
15
Label Shell Label Shell Label Shell
1 K (1s1/2 ) 11 N2 (4p1/2 ) 21 O5 (5d5/2 )
2 L1 (2s1/2 ) 12 N3 (4p3/2 ) 22 O6 (5f5/2 )
3 L2 (2p1/2 ) 13 N4 (4d3/2 ) 23 O7 (5f7/2 )
4 L3 (2p3/2 ) 14 N5 (4d5/2 ) 24 P1 (6s1/2 )
5 M1 (3s1/2 ) 15 N6 (4f5/2 ) 25 P2 (6p1/2 )
6 M2 (3p1/2 ) 16 N7 (4f7/2 ) 26 P3 (6p3/2 )
7 M3 (3p3/2 ) 17 O1 (5s1/2 ) 27 P4 (6d3/2 )
8 M4 (3d3/2 ) 18 O2 (5p1/2 ) 28 P5 (6d5/2 )
9 M5 (3d5/2 ) 19 O3 (5p3/2 ) 29 Q1 (7s1/2 )
10 N1 (4s1/2 ) 20 O4 (5d3/2 ) 30 outer shells
Table 7: Atomic electron shells indexes.
5 Framework usage
This section, address how to use the main program provided within the PenRed package.
This one allows the user to make simulations without programming. Instead, the user will
use a configuration file which structure is explained following.
First, all configuration files must follow the PenRed’s internal data library format, which
has been explained in section 3. Secondly, all configuration files must include some manda-
tory sections to specify the simulation characteristics. These sections are, sources, geometry,
materials, tallies and global parameters, and all of them are described in the following sec-
tions.
5.1 Materials
The material properties, such as cross sections, density, components, etc. are described
inside material files. These ones are the same as those used in the original PENELOPE
FORTRAN code. Therefore, material files can be generated using the tools and data bases
provided at original PENELOPE package, which are also included in the PenRed package.
The material data base is located in the folder
dataBases/penmaterials
where both, the program code to build materials and the database are stored. That code is
a literal translation to C++ of the original FORTRAN code used by PENELOPE to create
the materials. Thus, outputs of both C++ and FORTRAN versions must be perfectly
equivalent and usable as input for PenRed and PENELOPE. To compile the material build
program, the user must compile the “material.cpp” file. For instance, the following line can
be used to compile this code using the C++ GNU GCC compiler,
g++ -o createMat material.cpp
where createMat is the executable name. Once the code has been compiled, execute it in
the same folder where the database is (folder pdfiles) and follow the program instructions to
create the material. As in the FORTRAN code, a set of predefined materials can be build
via numerical codes, which are specified in the appendix A, in the tables 10 and 11.
16
5.1.1 Configuration
To specify a material in the configuration file, the user must follow the pattern of code 3,
where materials is a constant text, material-name is a text identifier, or name, selected by
the user and, finally, parameter/path and value are the parameters and values to specify for
that material.
1 m a t e r i a l s / m a t e r i a l −name/ parameter / path v a l u e
Code 3: Material configuration pattern
For instance, the code 4 shows the copper material configuration used in the first example
provided in the package.
1 m a t e r i a l s / cu /number 1
2
3 m a t e r i a l s / cu / e a b s e − 1 . 0 e3
4 m a t e r i a l s / cu / e a b s e+ 1 . 0 e3
5 m a t e r i a l s / cu / eabs gamma 1 . 0 e3
6
7 m a t e r i a l s / cu /C1 0 . 0 5
8 m a t e r i a l s / cu /C2 0 . 0 5
9
10 m a t e r i a l s / cu /WCC 1 . 0 e3
11 m a t e r i a l s / cu /WCR 1 . 0 e3
12
13 m a t e r i a l s / cu / f i l e n a m e ”Cu . mat”
Code 4: Complete material configuration example
As is shown, the parameters to specify for each material are analogous to the required by
the PENELOPE FORTRAN version. First, the material number is used for the geometry
material assignation. This one must be greater than 0, thus material 0 is considered as
void. Following the remaining parameters are explained.
Notice that PenRed provides default values, being the only mandatory parameters the
material number and filename. However it is advisable to select these parameters according
to the characteristics of the simulation.
5.1.1.1 Absorption energy

Absorption energy can be provided on both a global and local scale for each particle. When
a particle reaches its absorption energy threshold, it will be absorbed within its respective
material. Similarly, if secondary particles are generated with a energy below this threshold,
they will be considered locally absorbed and will not be simulated. To set a default absorp-
tion energy value for all materials, use the following path:
material-eabs/particle-name value
Alternatively, to apply the absorption energy to a specific material, use the following path:
materials/material-name /eabs/particle-name value
Here, material-name represents the user-defined name of the material, particle-name

refers to the particle to which the material-specific absorption energy will be applied, and
value denotes the absorption energy in electronvolts (eV). If no global or local values are
specified, a default value of 1 keV will be used.
17
Important!
The parameters eabs e−, eabs e+ and eabs gamma have been replaced by the pattern
materials/material-name/eabs/particle-name value
Therefore, for electrons, positrons and photons, the corresponding parameters, in each
material, are:
• eabs/electron
• eabs/positron
• eabs/gamma
respectively. To not break compatibility, the older parameters can still be used but
the program will show a deprecated warning. This change applies since version 1.9.0.
5.1.1.2 Limiting range

Instead of absorption energy, it can be defined the minimum range to simulate each particle
type. Thus, a particle whose energy corresponds to a smaller path than the one specified
will be absorbed. To specify this parameter, the following pattern must be used in the
corresponding material configuration section,
range/particle-name value
where range is a constant key and particle-name must be replaced by the particle name to
which the range constraint is to be applied. Finally, the value specify the limiting range in
cm.
In addition, global particle limiting ranges can be specified for all materials. These can
be specified following the pattern,
material-ranges/particle-name value
outside the material section. There, material-ranges is a constant key, particle-name is the
particle name to apply the limiting range and value specify the limiting range in cm.
Notice that default range values can be overwritten by local material ranges. For ex-
ample, the configuration shown in the Code 5 sets the the default range for electron and
gamma to 0.1 cm for all materials. Then, a infinite absorption energy is set to positrons to
avoid their transport. Finally, in the water material, the default range value is overwritten
for gammas to 0.05 cm. Because the electron transport parameters are not specified, all
materials use the default ones.
1
2 m a t e r i a l −r a n g e s / e l e c t r o n s 0 . 1
3 m a t e r i a l −r a n g e s /gamma 0 . 1
4
5 m a t e r i a l s / cu /number 1
6 m a t e r i a l s / cu / e a b s / p o s i t r o n 1 . 0 e35
7 m a t e r i a l s / cu / f i l e n a m e ”Cu . mat”
8
18
9 m a t e r i a l s /Fe/number 2
10 m a t e r i a l s /Fe/ e a b s / p o s i t r o n 1 . 0 e35
11 m a t e r i a l s /Fe/ f i l e n a m e ”Fe . mat”
12
13 m a t e r i a l s / water /number 3
14 m a t e r i a l s / water / r a n g e /gamma 0 . 0 5
15 m a t e r i a l s / water / e a b s / p o s i t r o n 1 . 0 e35
16 m a t e r i a l s / water / f i l e n a m e ”H2O . mat”
Code 5: Configuration example with different absorption limits
5.1.1.3 Electron and positron transport parameters

Next, the C1, C2, W CC and W CR parameters are used to control the class II transport of
electrons and positrons. To be able to select the appropriate parameters, the corresponding
description follows, which has been extracted from the PENELOPE manual [3], where are
further explained,
• C1: Average angular deflection, C1 ≈ 1− < cosθ >, produced by multiple elastic
scattering along a path length equal to the mean free path between consecutive hard
elastic events. The maximum allowed value is 0.2, but a value of 0.05 is usually
adequate.
• C2: Maximum average fractional energy loss between consecutive hard elastic events.
As C1, the maximum allowed value is 0.2 and a value of about 0.05 is, usually,
adequate.
• WCC: Cutoff energy loss, in eV, for hard inelastic collisions.
• WCR: Cutoff energy loss, in eV, for hard bremsstrahlung emission.
The election of these parameters determine the simulation trade off between speed and
accuracy. For better accuracy, C1 and C2 should have small values (0.01). Larger values
makes the simulation faster but less accurate. On the other hand, the cutoff energies W CC
and W CR speed up the simulation when using larger values, but if these are too large, the
tallied energy distributions could be distorted. To avoid this effect, the values of W CC and
W CR should be lesser than the bin width used to tally the energy distributions. Finally,
to ensure the reliability of the simulation, the user must ensure that the number of steps,
or random hinges, per primary track is “statistically sufficient”, which should be achieved
with more than 10 steps.
If the overmentioned parameters are not specified by the user, PenRed will set the
parameters automatically.
5.1.1.4 Filename
Finally, the f ilename parameter specify the relative path to the material file, which has
been previously created with the material builder program. The path to the material file
must be enclosed by quotes to be identified as text.
Notice that the configuration shown in the code 4 must be repeated for each used
material, changing the corresponding name and parameter values.
19
5.2 Particle sources
Particle sources handle the creation of particles to be simulated. The created particles
can be both primary or secondary depending on the selected source. In addition, multiple
sources can be specified in the same configuration file. In this case, the sources will be
computed sequentially, simulating the first particle of a source after the simulations end of
the last particle of the previous source.
To specify a particle source, the user must follow the pattern shown in code 6,
1 s o u r c e s / type /name/ parameter / path v a l u e
Code 6: Source configuration parameters
where type must be set to generic or polarized, whose are used to specify if the source
samples generic particle states or gamma polarized states respectively. Via the field name,
the user specifies a custom name for the particle source. Finally, parameter/path specifies
the configuration parameter to set with the corresponding value. For example, the code 7
shows the basic parameters used by all generic sources type, which name has been set to
source1.
1 s o u r c e s / g e n e r i c / s o u r c e 1 / n h i s t 1 . 0 e6 ( mandatory )
2 s o u r c e s / g e n e r i c / s o u r c e 1 / kpar ”gamma” ( mandatory )
3 s o u r c e s / g e n e r i c / s o u r c e 1 / r e c o r d −time t r u e ( optional )
4 s o u r c e s / g e n e r i c / s o u r c e 1 / s o u r c e −body 1 ( optional )
5 s o u r c e s / g e n e r i c / s o u r c e 1 / s o u r c e −m a t e r i a l 1 ( optional )
Code 7: Source generic configuration parameters
That source will produce 106 primary gamma particles and enables time recording. So
the parameter nhist, kpar and record-time sets the number of particles to generate by the
source, the particles type (electron, gamma or positron) and if time recording is enabled or
disabled respectively.
In addition we can specify if the particles creation must be restricted to a specific
body or material using the parameters source-body and source-material respectively. Both
parameters expects an integer index, which specify the source body or material. However,
notice that only one restriction can be used for each source. If specified, when a particle
is sampled in a different body or material, the spatial sampling will be repeated until the
condition is fulfilled.
Note that each parameter requires a specific type. nhist requires a number, kpar a text
(using the double quotes) and record-time a boolean (true or false). Now, we have the
generic parameters, but the sampler has not knowledge about how to sampling the initial
state of the particle, i.e. position, direction, energy, time etc. Therefore, we need to specify
the samplers to use, which are classified in spatial, direction, energy, time and specific
samplers. Accordingly, to specify what kind of sampler we are configuring, we will use the
keywords spatial, direction, energy, time and specific. Each sampler type is used with a
specific purpose, being spatial, direction, energy and time samplers in charge of determine
the particle initial position, direction, energy and live time, respectively. These samplers
are cataloged as generic samplers. Nevertheless, specific samplers can set the whole particle
state or a portion of it. Therefore, specific samplers can be combined with generic ones
depending on the sampler implementation or handle the whole state itself.
Although each sampler has its own parameters, whose can include custom paths, all of
them require a parameter named type, which sets the sampler to use. For example, to select
a mono-energetic energy sampler on the previous source, the line with the required type is
shown in code 8. Notice that the source type has been specified after the source name, i.e.
with the keyword energy and the type value specify which sampler to use among all the
available energy samplers.
20
1 s o u r c e s / g e n e r i c / s o u r c e 1 / e n e r g y / type ”MONOENERGETIC”
Code 8: Mono-energetic sampler configuration example
In addition, mono-energetic sources only require a single parameter, the particle energy.
The next line sets a sampling energy of 30 keV,
1 s o u r c e s / g e n e r i c / s o u r c e 1 / e n e r g y / e n e r g y 3 . 0 e7
Code 9: Mono-energetic sampler configuration example
The other samplers are configured analogously, but using their own parameters. To put
it all together, a complete generic source configuration is shown in the code 10, i.e. with no
specific sampler. In that code, the lines that begins with # are considered comments and
ignored by the parser.
1 #−−−−−−−−−−−−−−−−−−−−−−−−
2 # Source 1
3 #########################
4
5 s o u r c e s / g e n e r i c / s o u r c e 1 / n h i s t 1 . 0 e6
6 s o u r c e s / g e n e r i c / s o u r c e 1 / kpar ”gamma”
7 s o u r c e s / g e n e r i c / s o u r c e 1 / r e c o r d −time t r u e
8
9 # D i r e c t i o n a l sampling
10 #########################
11
12 s o u r c e s / g e n e r i c / s o u r c e 1 / d i r e c t i o n / type ”CONE”
13
14
15 # Set theta
16 sources / generic / source1 / d i r e c t i o n / theta 0.0
17
18 # Set phi
19 s o u r c e s / g e n e r i c / source1 / d i r e c t i o n / phi 0.0
20
21 # Set oberture ( alpha )
22 s o u r c e s / g e n e r i c / source1 / d i r e c t i o n / alpha 5.0
23
24
25 # Energy s a m p l i n g
26 #########################
27
29
30 # Set energy
32
33
34 # S p a t i a l sampling
35 #########################
36
37 s o u r c e s / g e n e r i c / s o u r c e 1 / s p a t i a l / type ”POINT”
38
39 # Set p a r t i c l e o r i g i n
40 s o u r c e s / g e n e r i c / s o u r c e 1 / s p a t i a l / p o s i t i o n /x 0 . 0
41 s o u r c e s / g e n e r i c / s o u r c e 1 / s p a t i a l / p o s i t i o n /y 0 . 0
42 s o u r c e s / g e n e r i c / s o u r c e 1 / s p a t i a l / p o s i t i o n / z −25.0
Code 10: Complete source configuration example
A source without specific sampler, like the previous one, requires at least spatial, energy
and direction samplers, being the time sampler optional. If a specific sampler is used, the
21
required generic samplers depends on the specific sampler itself, and may need some or
any generic sampler. In the examples folder we can find configuration files with different
sources. In addition, all the available samplers classified by type will be described following.
5.2.1 Spatial source samplers

5.2.1.1 Point
The spatial point sampler needs the (x, y, z) coordinates to fill the position of generation
particles. These values are doubles and are specified in cm. Following there is a configuration
example of this kind of source sampling corresponding to the 1-disc example.
2 #########################
3
4 s o u r c e s / g e n e r i c / s o u r c e 1 / s p a t i a l / type ”POINT”
5
Code 11: Spatial source POINT sampler
5.2.1.2 Box
This spatial sampler creates a box where particles are generated with uniform probability.
The configuration file contains the information of the box origin introducing the (x, y, z)
coordinates values, in cm. In addition, the configuration requires the size of the box in each
axis (dx, dy, dz) in cm, which must be positive or zero. All these values are interpreted as
doubles. An example of configuration file is shown below.
2 #########################
3
4 s o u r c e s / g e n e r i c / s o u r c e 1 / s p a t i a l / type ”BOX”
5
6
7 # S e t box s i z e
8 s o u r c e s / g e n e r i c / s o u r c e 1 / s p a t i a l / s i z e /dx 0 . 7 5
9 s o u r c e s / g e n e r i c / s o u r c e 1 / s p a t i a l / s i z e /dy 0 . 7 5
10 s o u r c e s / g e n e r i c / s o u r c e 1 / s p a t i a l / s i z e / dz 1 . 2 5
11
Code 12: Spatial source BOX sampler
5.2.1.3 Cylindrical shell

This spatial sampler generates particles within a cylindrical shell. It is defined by sub-
tracting a smaller cylinder from a bigger one where it is included. The sampling region
corresponds to the shaded area in the Figure 9.
Notice that the center of both cylinders coincide. The parameters to define the region
are listed following:
22
dzmax dzmin
rmin
rmax
Figure 9: Cylindrical shell sampling region and values to define.
• type: Must be set to “CYLINDER”.
• size/rmin: Inner cylinder radius in cm.
• size/rmax: External cylinder radius in cm.
• size/dzmin: Inner cylinder height in cm.
• size/dzmax: External cylinder height in cm
• position/x: X coordinate of the cylinders center in cm.
• position/y: Y coordinate of the cylinders center in cm.
• position/z: Z coordinate of the cylinders center in cm.
For example, the Code 13 shows the configuration to sample particles in a thin layer of
radioactive paint on a brachytherapy seed located at the origin.
2 #########################
3
4 s o u r c e s / g e n e r i c / s o u r c e 1 / s p a t i a l / type ”CYLINDER”
5
6 # Set c y l s i z e
7 s o u r c e s / g e n e r i c / s o u r c e 1 / s p a t i a l / s i z e / rmin 0 . 0 2 5
8 s o u r c e s / g e n e r i c / s o u r c e 1 / s p a t i a l / s i z e /rmax 0 . 0 2 5 1 7 5
9 s o u r c e s / g e n e r i c / s o u r c e 1 / s p a t i a l / s i z e / dzmin 0 . 2 8
10 s o u r c e s / g e n e r i c / s o u r c e 1 / s p a t i a l / s i z e /dzmax 0 . 2 9 5
11
12 # Set p o s i t i o n
15 sources / generic / source1 / s p a t i a l / position /z 0.0
Code 13: Spatial source CYLINDER sampler
23
5.2.2 Direction samplers
5.2.2.1 Cone
Particles generated by the source are sampled in a conical beam. In this sample the overture
of the cone must be specified to sample the particles direction uniformly inside the corre-
sponding solid angle. Therefore, the required parameters are the polar (theta) and azimutal
(phi) angles to determine the solid angle direction, and the semiaperture (alpha). Notice
that all values are expected in degrees. To reproduce a monodirectional source, the overture
must be set to alpha = 0.0. However, to obtain a isotropic source, the semiaperture must
be set to alpha = 180.0. All values are expected to be doubles.
The following lines show the directional sampling of the configuration file of example
2-plane.
1
3 #########################
4
5 s o u r c e s / g e n e r i c / s o u r c e 1 / d i r e c t i o n / type ”CONE”
6
7
8 # Set theta
9 sources / generic / source1 / d i r e c t i o n / theta 0.0
10
11 # Set phi
12 s o u r c e s / g e n e r i c / source1 / d i r e c t i o n / phi 0.0
13
15 s o u r c e s / g e n e r i c / source1 / d i r e c t i o n / alpha 5.0
Code 14: Direction CONE sampler
5.2.2.2 Sphere
In this case the direction of the particles generated are sampled in a sphere section. The
information needed in this directional sampler is the direction components in each axis
(u, v, w), the polar overture introducing the minimum and maximum value of the polar
angle (theta0, theta1), and the azimutal overture introducing the minimum value of the phi
angle (phi0) and its overture (dphi). All of this values types must be doubles. The Core 15
shows an example corresponding to a sphere section pointing to +Z axis with a symmetric
overture from −30 to 30 degrees in all the azimutal interval.
1
3 #########################
4
5 s o u r c e s / g e n e r i c / s o u r c e 1 / d i r e c t i o n / type ”SOLID ANGLE”
6
7
8 # Set d i r e c t i o n vector
9 s o u r c e s / g e n e r i c / s o u r c e 1 / d i r e c t i o n /u 0 . 0
10 s o u r c e s / g e n e r i c / s o u r c e 1 / d i r e c t i o n /v 0 . 0
11 s o u r c e s / g e n e r i c / s o u r c e 1 / d i r e c t i o n /w 1 . 0
12
13 # Set polar overture
14
15 s o u r c e s / g e n e r i c / s o u r c e 1 / d i r e c t i o n / t h e t a 0 −30.0
16 sources / generic / source1 / d i r e c t i o n / theta1 30.0
17
24
18
19 # Set azimutal overture
20 s o u r c e s / g e n e r i c / source1 / d i r e c t i o n / phi0 0.0
21 s o u r c e s / g e n e r i c / s o u r c e 1 / d i r e c t i o n / dphi 3 6 0 . 0
Code 15: Direction SOLID ANGLE sampler
5.2.3 Energy samplers

5.2.3.1 Monoenergetic
This energy sampler generates a monoenergetic beam of particles with the specified energy
in eV. The only required parameter is the energy value, which is interpreted as double and
expected to be positive. An example of its usage can be found in the configuration file
shown below. These lines correspond to the example 4-x-ray-tube, file tube.in.
1
3 #########################
4
6
7 # Set energy
Code 16: Energy samplers MONOENERGETIC
5.2.3.2 Intervals
Intervals sampler generates energies within the specified spectral lines according to the
probability assigned to each one. To define the spectral lines in the configuration file, first,
the user must specify the number of intervals, ninterval, using a integer value. Then, the
energy range of each interval, [lowE, topE], are specified as follows. A single array named
lowE will contain all the low energy boundaries of all energy intervals. In the same way,
all values for top energy limits must be grouped in an array named topE. Finally, the
probabilities of each interval are wrote in a third array named probabilities. Therefore, the
first position of the array lowE specify the low boundary for the first interval or spectral line,
the first position of the array topE the top limit and the first position of the probabilities
array the corresponding probability. The same is applied to the second position, which
specify the second interval or spectral line, and so on. Notice that the probabilities are not
required to be normalised, as is shown in the following example code, which corresponds to
the 3-detector example, file detector1.in. Regarding the variable types, the energy range
values and probabilities are doubles and must be, at least, zero.
1
3 #########################
4
5 s o u r c e s / g e n e r i c / s o u r c e 1 / e n e r g y / type ”INTERVALS”
6
7
8 # Set i n t e r v a l s
9 sources / g e n e r i c / source1 / energy / n i n t e r v a l s 2
10
11
12 # Set e n e r g i e s
13 s o u r c e s / g e n e r i c / s o u r c e 1 / e n e r g y /lowE [ 1 . 1 7 e6 , 1 . 3 3 e6 ]
14 s o u r c e s / g e n e r i c / s o u r c e 1 / e n e r g y / topE [ 1 . 1 7 e6 , 1 . 3 3 e6 ]
25
15
16 # Set p r o b a b i l i t i e s
17 sources / g e n e r i c / source1 / energy / p r o b a b i l i t i e s [ 5 0 . 0 , 5 0 . 0 ]
Code 17: Energy samplers INTERVALS
5.2.3.3 File spectrum

This energy sampler has been implemented to provide compatibility between the PenEasy
[7] (v.2020-03-25) energy spectrum format and PenRed. Although this one is described in
the PenEasy manual [8], it is also described following for the user convenience.
The format consists on a piecewise function where each entry in the spectrum contains
two numbers. The first one, specify the starting energy of a channel, and the second
its unnormalized probability. The probabilities must be non-negative and don’t require
to be normalized to unity. The program interprets a negative probability as the end of
the spectrum. For example, a valid spectrum format is shown in the code 18, where the
character # is interpreted as a comment. Notice that the spectrum file must contain only
comments or valid spectrum values until the end of the spectrum. For example, blank lines
are not allowed. However, all the text beyond the end of the spectrum is ignored by the
sampler.
1 #Spectrum ( c h a r a c t e r ’# ’ i s i n t e r p r e t e d a s a comment )
2 1 . 2 0 e3 10 1 s t c h a n n e l : [ 1 . 2 0 , 1 . 6 1 ] keV
3 1 . 6 1 e3 0 . 0 2nd c h a n n e l : [ 1 . 6 1 , 5 . 0 0 ] keV , no e m i s s i o n s
4 5 . 0 0 e3 20 m o n o e n e r g e t i c l i n e a t 5 . 0 0 keV
5 5 . 0 0 e3 0 3 rd c h a n n e l : [ 5 . 0 0 , 6 . 2 4 ] keV , no e m i s s i o n s
6 6 . 2 4 e3 3 3 . 3 4 th c h a n n e l : [ 6 . 2 4 , 7 . 3 2 ] keV
7 7 . 3 2 e3 5 . 0 2 5 th c h a n n e l : [ 7 . 3 2 , 8 . 0 0 ] keV
8 8 . 0 0 e3 1 0 . 2 6 th c h a n n e l : [ 8 . 0 0 , 9 . 7 6 ] keV
9 9 . 7 6 e3 1 5 . 2 7 th c h a n n e l : [ 9 . 7 6 , 1 0 . 0 ] keV
10 1 0 . 0 e3 0 . 0 8 th c h a n n e l : [ 1 0 . 0 , 1 5 . 0 ] keV , no e m i s s i o n s
11 1 5 . 0 e3 20 m o n o e n e r g e t i c l i n e a t 1 5 . 0 keV
12 1 5 . 0 e3 −1 end o f t h e spectrum
Code 18: File energy spectrum format
This sampler only requires two configuration values. As the other samplers, the first one
is the type, which must be set to “FILE SPECTRUM”. The other is the spectrum filename
which is introduced as a string, as is shown in the code 19.
1
3 #########################
4
5 s o u r c e s / g e n e r i c / s o u r c e 1 / e n e r g y / type ”FILE SPECTRUM”
6 s o u r c e s / g e n e r i c / s o u r c e 1 / e n e r g y / f i l e n a m e ” spectrum . s p c ”
Code 19: File spectrum configuration
5.2.4 Time samplers

5.2.4.1 Decay
This sampler generates, randomly, an exponential timing decay of events from a radioactive
element. The time interval is introduced by the user with [time0, time1] and negative values
are not allowed. In addition, the half Lif e of the radioactive element is required.
26
5.2.5 Specific Sources
5.2.5.1 Phase Space File
This type of source uses the phase space file created with the tally type “PSF” to run the
simulation, from where the particles will be read. An example where this type of source is
used is the example 5-accelerator-2, which configuration is shown in the code 20.
Regarding the required parameters, the filename is the relative path to of the file from
where the particles will be read, and the parameter Emax specify the maximum energy value
of all particles in the PSF. Then, the two next parameters are related with VR techniques.
The first one, wght-window, sets the interval to apply splitting and Russian Roulette. How
both VR techniques are applied is explained following. First, Russian roulette is applied
to particles with a weight value lower than the minimum value of the interval. Instead,
splitting is applied to particles with a weight value larger than the maximum value of this
interval. Therefore, particles with a weight value inside the interval remain unaltered. The
second parameter, split, sets the number of splits per particle.
Finally there are two groups of optional parameters to be able to rotate and translate
the particles in the PSF file. First, the rotation is specified as a ‘ZYZ’ rotation using the
Euler angles omega, theta and phi. Then, the user can apply a displacement using the dx
parameter for translations in the x axis, and dy and dz for y, z axes respectively. Notice
that the rotation is applied before the translation.
1 # Source 1
2 #########################
3
4 s o u r c e s / g e n e r i c / s o u r c e −p s f / n h i s t 1 . 0 e6
5 s o u r c e s / g e n e r i c / s o u r c e −p s f / s p e c i f i c / type ”PSF”
6 s o u r c e s / g e n e r i c / s o u r c e −p s f / s p e c i f i c / f i l e n a m e ” p s f −merged . dat ”
7 s o u r c e s / g e n e r i c / s o u r c e −p s f / s p e c i f i c /Emax 7 e6
8
9 s o u r c e s / g e n e r i c / s o u r c e −p s f / s p e c i f i c /wght−window [ 5 e −4 , 1 e −3]
10 s o u r c e s / g e n e r i c / s o u r c e −p s f / s p e c i f i c / n s p l i t 10
11
12 s o u r c e s / g e n e r i c / s o u r c e −p s f / s p e c i f i c / r o t a t i o n /omega 0
13 s o u r c e s / g e n e r i c / s o u r c e −p s f / s p e c i f i c / r o t a t i o n / t h e t a 90
14 s o u r c e s / g e n e r i c / s o u r c e −p s f / s p e c i f i c / r o t a t i o n / p h i 0
15
16 s o u r c e s / g e n e r i c / s o u r c e −p s f / s p e c i f i c / t r a n s l a t i o n /dx 0
17 s o u r c e s / g e n e r i c / s o u r c e −p s f / s p e c i f i c / t r a n s l a t i o n /dy 0
18 s o u r c e s / g e n e r i c / s o u r c e −p s f / s p e c i f i c / t r a n s l a t i o n / dz 10
Code 20: Phase Space File Source
5.2.5.2 Computed Tomography (CT)

This source has been developed to emit particles along a circumference by two different
ways. The particles are emitted following discrete and regular steps specified by the user.
On the one hand, reading the particles from a previously generated Phase Space File.
As this source uses internally the Phase Space File source (section 5.2.5.1), it inherits
some parameters already defined in the PSF source. That parameters are: filename, Emax,
wght-window, nsplit. Moreover, the PSF translation and rotation can be applied to this
source.
On the other hand, a generic source can be used with the corresponding directional,
energy and spatial sampling. Additionally, as the output particles in a CT accelerator are,
usually, secondary particles, a field named nSecondaries must be set to specify the number
27
of secondary particles sampled by each history. Therefore, in a single history, nSecondaries
particles will be sampled before increasing the history number.
Regarding the source type, it must be set to “CT” in the configuration file. Then, the
specific parameters to configure the CT source are divided in three subsections, which are
described following,
• Angular information: On the one hand, the parameters phi-ini and phi-end specify
the initial and and final angular position of the CT source. On the other hand, the
parameter angularStep sets the angular step between two consecutive projections. All
values must be set in degrees.
• Position information: To specify the source position, the [CTx0, CTy0, CTz0] is
required. This corresponds to the CT origin, where the source will be translated.
Finally, the CT radious, (rad), is needed to apply the final source translation to this
point.
• Time information: The time between projections must be set using the parameters
tmin, for the minimum time stamp of the psf particles, and dt, for the time interval.
An example of CT source using PSF generated previously is shown in 21, while an

example in which a generic source is used is shown in the code 22.
1 # Source 1
2 #########################
3
4 s o u r c e s / g e n e r i c / s o u r c e −c t / n h i s t 1 . 5 e8
5 s o u r c e s / g e n e r i c / s o u r c e −c t / s p e c i f i c / type ”CT”
6 s o u r c e s / g e n e r i c / s o u r c e −c t / s p e c i f i c / f i l e n a m e ” p s f −merged . dat ”
7 s o u r c e s / g e n e r i c / s o u r c e −c t / s p e c i f i c /Emax 1 . 0 e5
8
9 s o u r c e s / g e n e r i c / s o u r c e −c t / s p e c i f i c /wght−window [ 5 e −4 , 1 e −3]
10 s o u r c e s / g e n e r i c / s o u r c e −c t / s p e c i f i c / n s p l i t 100
11
12 # Angular i n f o r m a t i o n
13 ##############################
14 s o u r c e s / g e n e r i c / s o u r c e −c t / s p e c i f i c / phi−i n i 180
15 s o u r c e s / g e n e r i c / s o u r c e −c t / s p e c i f i c / phi−end 540
16 s o u r c e s / g e n e r i c / s o u r c e −c t / s p e c i f i c / a n g u l a r S t e p 1 . 0
17
18
19 # Position information
20 ##############################
21 s o u r c e s / g e n e r i c / s o u r c e −c t / s p e c i f i c /CTx0 0
22 s o u r c e s / g e n e r i c / s o u r c e −c t / s p e c i f i c /CTy0 0
23 s o u r c e s / g e n e r i c / s o u r c e −c t / s p e c i f i c /CTz0 0
24 s o u r c e s / g e n e r i c / s o u r c e −c t / s p e c i f i c / rad 5 2 . 0
25
26 # Time i n f o r m a t i o n
27 ##############################
28 s o u r c e s / g e n e r i c / s o u r c e −c t / s p e c i f i c / tmin 0 . 0
29 s o u r c e s / g e n e r i c / s o u r c e −c t / s p e c i f i c / dt 1 2 0 . 0
Code 21: PSF Computed Tomography Source
1 # Source 1
2 #########################
3
4 s o u r c e s / g e n e r i c / s o u r c e −c t / n h i s t 1 e8
5 s o u r c e s / g e n e r i c / s o u r c e −c t / s p e c i f i c / type ”CT”
28
6
7 s o u r c e s / g e n e r i c / s o u r c e −c t / s p e c i f i c / n S e c o n d a r i e s 80
8
9 s o u r c e s / g e n e r i c / s o u r c e −c t / kpar ”gamma”
10
11
13 #########################
14 s o u r c e s / g e n e r i c / s o u r c e −c t / d i r e c t i o n / type ”CONE”
15
16 # Set theta
17 s o u r c e s / g e n e r i c / s o u r c e −c t / d i r e c t i o n / t h e t a 9 0 . 0
18
19 # Set phi
20 s o u r c e s / g e n e r i c / s o u r c e −c t / d i r e c t i o n / p h i 1 8 0 . 0
21
23 s o u r c e s / g e n e r i c / s o u r c e −c t / d i r e c t i o n / a l p h a 11
24
25
27 #########################
28
29 s o u r c e s / g e n e r i c / s o u r c e −c t / e n e r g y / type ”MONOENERGETIC”
30
31 # Set energy
32 s o u r c e s / g e n e r i c / s o u r c e −c t / e n e r g y / e n e r g y 1 . 2 0 e5
33
35 #########################
36
37 s o u r c e s / g e n e r i c / s o u r c e −c t / s p a t i a l / type ”POINT”
38
40 s o u r c e s / g e n e r i c / s o u r c e −c t / s p a t i a l / p o s i t i o n /x 0 . 0
41 s o u r c e s / g e n e r i c / s o u r c e −c t / s p a t i a l / p o s i t i o n /y 0 . 0
42 s o u r c e s / g e n e r i c / s o u r c e −c t / s p a t i a l / p o s i t i o n / z 0 . 0
43
44
45 # Angular i n f o r m a t i o n t o do
46 ##############################
47 s o u r c e s / g e n e r i c / s o u r c e −c t / s p e c i f i c / phi−i n i 180
48 s o u r c e s / g e n e r i c / s o u r c e −c t / s p e c i f i c / phi−end 540
49 s o u r c e s / g e n e r i c / s o u r c e −c t / s p e c i f i c / a n g u l a r S t e p 0 . 5
50
51
52
53 # Position information
54 ##############################
55 s o u r c e s / g e n e r i c / s o u r c e −c t / s p e c i f i c /CTx0 1 9 . 1 5
56 s o u r c e s / g e n e r i c / s o u r c e −c t / s p e c i f i c /CTy0 1 9 . 1 5
57 s o u r c e s / g e n e r i c / s o u r c e −c t / s p e c i f i c /CTz0 1 4 . 8
58 s o u r c e s / g e n e r i c / s o u r c e −c t / s p e c i f i c / rad 1 0 6 . 0
59
60
61
62 # Time i n f o r m a t i o n
63 ########################################
64
65 s o u r c e s / g e n e r i c / s o u r c e −c t / s p e c i f i c / tmin 0 . 0
29
66 s o u r c e s / g e n e r i c / s o u r c e −c t / s p e c i f i c / dt 1 2 0 . 0
Code 22: Generic Computed Tomography Source
5.2.5.3 PENNUC
The PENNUC source has been adapted from the original FORTRAN code published in
[9] and developed by the CIEMAT, Laboratoire National Henri Becquerel, and Universitat
de Barcelona. This one allows to simulate the decay of radioactive nuclides and use the
resulting particles in a generic simulation. The decay characteristics for each nuclide, using
the PENNUC format, can be downloaded from a public database 1 . In addition, the files
pdatconf.p14 and pdrelax.p11 must be contained in the simulation folder to be able to
process the decay data. Both files are available in the following database folder,
dataBases/penmaterials/pdfiles/
Moreover, a complete example of simulation using the PENNUC source can be found
in the folder
examples/quadrics/3-detector-2/
To perform the spatial sampling, the PENNUC source requires a generic spatial sam-
pler, for example, the box sampler. In addition, the source must be configured with the
parameters shown in the code 23 and explained following.
• type: The source type must be set to PENNUC
• nucleide filename: Specify the file with the decay data downloaded from the nucle-
ide database 2 .
• age: Optional parameter to enable or disable the age recording.
• source-material: Forces the particle to be generated only in a specific material.
1
2 # PENNUC s a m p l i n g
3 #########################
4
5 s o u r c e s / g e n e r i c / s o u r c e 1 / s p e c i f i c / type ”PENNUC” ( mandatory )
6 s o u r c e s / g e n e r i c / s o u r c e 1 / s p e c i f i c / n u c l e i d e f i l e n a m e ”Co−60. nuc ” ( mandatory )
7 s o u r c e s / g e n e r i c / s o u r c e 1 / s p e c i f i c / age t r u e ( optional )
8 s o u r c e s / g e n e r i c / s o u r c e 1 / s p e c i f i c / s o u r c e −m a t e r i a l 1 ( optional )
Code 23: PENNUC source configuration
Notice that PENNUC will sample the direction isotropically, and only the spatial sam-
pling step can be controlled, using a spatial sampler.
5.2.5.4 Brachytherapy seeds source

This source has been implemented to simulate brachytherapy treatments, in which the seed
information can be read from the DICOM plan of the patient provided by the user. To
be able to use this source, first, a phase space file must be obtained to characterize the
brachytherapy seed. That PSF will be moved and rotated according to the information
provided in the DICOM plan to sample particles in each seed position. However, the PSF
must be created accomplishing some conditions, which are listed below,
1
http://www.nucleide.org/DDEP WG/DDEPdata.htm
2
http://www.nucleide.org/DDEP WG/DDEPdata.htm
30
• The center of the seed geometry must be located at the (0, 0, 0).
• The seed geometry must look upwards (+Z axis).
This conditions must be satisfied to ensure that the location and rotation of the PSF is
done properly for every seed position. Nevertheless, notice that the PSF can be translated
and rotated via the configuration file. Therefore, if the original provided PSF does not ac-
complish the conditions, the required transformations can be specified in the configuration.
To use this source in the configuration file, the following parameters must be specified.
The type of the source must be set to “BRACHY”. Then, a subsection named psf must be
created to configure the PSF source used internally by the brachytherapy source. The PSF
configuration is described in the section 5.2.5.1. An example of a complete configuration is
shown in the code 24.
1
2 #−−−−−−−−−−−−−−−−−−−−−−−−
3 # Source 1
4 #########################
5
6 s o u r c e s / g e n e r i c / s o u r c e −p s f / n h i s t 5 . 0 e7
7 s o u r c e s / g e n e r i c / s o u r c e −p s f / s p e c i f i c / type ”BRACHY”
8 s o u r c e s / g e n e r i c / s o u r c e −p s f / s p e c i f i c / p s f / f i l e n a m e ” p s f −merged . dat ”
9 s o u r c e s / g e n e r i c / s o u r c e −p s f / s p e c i f i c / p s f /Emax 1 . 4 0 e6
10
11 s o u r c e s / g e n e r i c / s o u r c e −p s f / s p e c i f i c / p s f /wght−window [ 5 e −4 , 1 e −3]
12 s o u r c e s / g e n e r i c / s o u r c e −p s f / s p e c i f i c / p s f / n s p l i t 10
Code 24: Brachytherapy source
Notice that the DICOM is not specified in the source configuration. This is because the
DICOM image is taken directly from the geometry. Therefore, this source is only intended
to be used with DICOM based geometries. In addition, if no DICOM plan file is provided
in the specified DICOM, or the plan has not any seed, a warning will be shown in the log
and the particles will be created at the (0, 0, 0) cm.
5.3 Geometries
Each simulation only allows to use a single geometry which configuration parameters are
specified by the prefix geometry to be correctly identified. Like sources, geometries require
to specify its type, and other specific parameters.
5.3.1 Geometry visualization

All geometries compatible with the PenRed framework can be visualized using the viewer
provided in the following repository,
https://github.com/PenRed/GeometryViewer
which includes the documentation to install and use the viewer.
5.3.2 Quadric
This geometry type is used in all the PENELOPE based examples which have been trans-
lated to be reproduced with PenRed. For instance, the code 25 shows the geometry configu-
ration for the first simulation example (1-disc). The geometries for this type are defined in a
31
external file following as is explained in the PENELOPE manual [3] in the Chapter 6 Con-
structive quadric geometry. Moreover, PenRed is compatible with the PENELOPE
geometry files, allowing to use them directly from PENELOPE simulations.
1 geometry / type ”PEN QUADRIC”
2 geometry / input − f i l e ” d i s c . geo ”
3 geometry / p r o c e s s e d −geo− f i l e ” r e p o r t . geo ”
4
5 geometry /dsmax /1 1 . 0 e−4
6 geometry / kdet /1 1
Code 25: Complete geometry configuration example
As other configuration examples, the type is specified by the type parameter. Then,
the input-file parameter specify the relative path to the file where the geometry has been
defined. The other parameters processed-geo-file, dsmax and kdet are optional and described
following. The first one, processed-geo-file, specify a file to generate a geometry report.
Secondly, dsmax specify the maximum distance allowed for electrons and positrons to jump
when class II transport is active. This one is used in thin regions to ensure a minimum
number of steps in the specified body. Notice that the body where the dsmax is applied is
specified via its alias in the parameter path, geomtry/dsmax/*alias*. For instance, in the
previous code, the dsmax is applied to the body with the alias ”1”. Finally, the parameter
kdet specify the detector identifier which the body belongs. Again, the body is specified
using its alias in the parameter path, geometry/kdet/*alias*.
Optionally, it is possible to specify local absorption energies for any body and particle.
In the code 26 we shown an example where the local energy absorption for each particle
is set to 10 keV for the body with alias “2”. Notice that the most restrictive absorption
energy is applied, either the assigned to the corresponding material or the one assigned to
the body.
1 geometry / e a b s /2/ e l e c t r o n 1 . 0 e4
2 geometry / e a b s /2/gamma 1 . 0 e4
3 geometry / e a b s /2/ p o s i t r o n 1 . 0 e4
Code 26: Configuration of geometry absorption energy example
5.3.3 Triangular Mesh Surfaces

This type of geometry uses triangular mesh surfaces to define the geometry system bodies.
For this purpose, PenRed defines its own format for input files. However, with the provided
Blender plugin (Section 7.1), several mesh formats can be easily transformed to the PenRed
one.
Notice that this geometry is still under testing and could be changed in future versions.
5.3.3.1 Input file format

In the examples folder, several triangular mesh based geometry files can be found.
examples/triangular surfaces
These geometry files must contain the following elements, in order,
• A line with a integer which indicates the total number of bodies in the geometry.
• Then, the specification of each body in the defined geometry follows. For each one,
the information to be specified is,
32
– Body metadata: Consists of a line with the following information, in order:
∗ Material number
∗ Number of triangles
∗ Number of vertex
∗ Body name
∗ Parent body name
An example is shown in the Code 27. Notice that lines beginning with # are
considered as comments and are ignored when the input is processed. In all
geometries, one body acts as the world, i.e. it has no parent and all other
bodies are included inside it. To specify which body is considered as the world,
its parent name must be set to void. Therefore, void can’t be used as a body
name.
1
2 #MAT #NFACES #NVERTEX #NAME #PARENT NAME
3 002 0040796 00020400 Capsule cyl Phantom
Code 27: Body metadata for triangular mesh geometries.
– Vertex list: A list of all mesh vertex. Each one is specified in a single line with
the following format,
vertex number X Y Z
An example is shown in the Code 28.

1 # VERTEX LIST
2 # Index (X Y Z )
3 0000 +0.000000E+00 −8.000000E−02 +7.566000E−02
4 0001 +0.000000E+00 −8.000000E−02 −1.731400E−01
5 0002 +2.513000E−03 −7.996000E−02 +7.566000E−02
6 0003 +2.513000E−03 −7.996000E−02 −1.731400E−01
7 0004 +5.023000E−03 −7.984200E−02 +7.566000E−02
8 .
9 .
10 .
Code 28: Body vertex list in triangular mesh geometries.
Notice that vertex coordinates are relative to the geometry origin (0, 0, 0), not
to the body center.
– Triangle list: A list with all mesh triangles. As vertex, each one is specified in
a single line, which contains the three vertex indexes that defines the triangle.
Notice that the order of the vertex is used to calculate the direction of the triangle
normal vector. The normals are assumed to point outward from the body. Most
3D design softwares uses this schema by default and provide tools both to check
the geometry normals and to recalculate them.
An input example is shown in the Code 29.
1 # FACES( t r i a n g l e s )
2 499 001 003
3 499 003 599
4 599 003 005
5 599 005 699
6 699 005 007
7 699 007 799
33
8 .
9 .
10 .
Code 29: Body triangle list in triangular mesh geometries.
5.3.3.2 Configuration
The mandatory configuration parameters to use this type of geometry are shown in the
code 30 and are listed following,
• type: Must be set to MESH BODY.
• input-file: Path to the input file with the geometry description. This must follow
the format described in the section 5.3.3.1.
In addition, the report-file parameter can be specified to print a processed geometry

report.
Regarding specific parameters for each body, the user can specify the dsmax and kdet
parameters as is done for quadric geometries.
In this kind of geometries, to check if a particle crosses a body, this one is split in
several regions containing a subset of the body triangles, allowing to check only the triangles
belonging to crossed regions. In turn, this regions are grouped in super-regions, following
the same approach. That clustering avoids checking many triangles and saves computational
time.
To control how the clustering is done, the user can specify two parameters to control
how these regions are constructed, which are described following,
• RegionElements: Specify the objective number of triangles in each region for the
specified body.
• SuperRegions: Specify the objective number of regions in each super-region for the
specified body.
These parameters can be different for each body. For example, in the code 30, the body
named Capsule cyl has an objective number of triangles per region of 50 and will try to
group 20 regions in each super-region. Notice that the real number of elements in each
cluster could be different depending on the body structure. For example, regions with a
small number of triangles are merged with boundary regions.
1
2 geometry / type ”MESH BODY” ( mandatory )
3 geometry / input − f i l e ” seedMesh . geo ” ( mandatory )
4 geometry / r e p o r t − f i l e ” r e p o r t . geo ” ( optional )
5
6 geometry / RegionElements / C a p s u l e c y l 50 ( optional )
7
8 geometry / S u p e r R e g i o n s / C a p s u l e c y l 20 ( optional )
Code 30: Triangular mesh geometry configuration example.
5.3.3.3 Limitations
Unlike in quadric geometries, the bodies surfaces in triangular mesh geometries can’t cross
the surface of another body. The equivalent in quadric geometries should be consider all
bodies as modules. However, the surface of two different bodies can be in contact.
34
5.3.4 Voxel
Voxelized geometries consists of a 3D matrix of regular prisms elements with a specific
material and density factor for each one. The density factor is used to specify heterogeneities
in the density of the materials. For instance, a voxel with a density factor of 1.10 will have
a density 10% greater than the material nominal density (specified in the material file).
Likewise, a voxel with a density factor of 0.8 is considered to have a density 20% lower than
the nominal material density. To use the original material density in a voxel, this factor
must be set to 1.
This kind of geometries requires to set V OXEL as geometry type and provide the
path to the file where the geometry has been defined (filename). The files which stores
the voxelized geometry, consists of a binary data dumped by the pen voxelGeo class. One
example of how to create a geometry file using that class can be found at the test code,
src/tests/geometry/voxels/read Dump.cpp
which creates a random filled voxel geometry, stores it to a file and, finally, loads the
file to be compared with the original created geometry. In addition, another example can
be found at the utility geo2voxel, which source file is located at,
src/utilities/geometry/geo2voxel.cpp
This utility, instantiate a geometry with type and configuration specified by the user,
and creates a voxelized geometry file according to that geometry. To do that, the locate
method is used to map each voxel material and density. As can be found in the mentioned
codes, the function to fill a voxel geometry class class is named setVoxels, and is shown
in the code 31, where the initialization of voxels materials and densities is not shown. The
required parameters are, a three elements array (nvox) with the number of voxels in each
axis (nx, ny, nz), the voxels sizes in each axis (sizes) (dx, dy, dz) in cm, a one dimensional
array with the material assignation of each voxel (voxM ats), i.e., with nx×ny×nz elements,
a one dimensional array with the density factor of each voxel, also with nx×ny×nz elements,
and a verbose level. Then, once the voxel mesh has been created, the geometry file can be
printed in binary format ready to simulate using the function dump2File. Also, the voxel
geometry information can be printed in ASCII format for visualization purposes using the
function printImage.
1
2 u n s i g n e d nvox [ 3 ] = . . .
3 double s i z e s [ 3 ] = . . .
4 u n s i g n e d ∗ voxMats = . . .
5 d o u b l e ∗ voxDensFact = . . .
6
7 p e n v o x e l G eo v o x e l g e o ;
8 i n t e r r = v o x e l g e o . s e t V o x e l s ( nvox , s i z e s , voxMats , voxDensFact , 3 ) ;
9 i f ( e r r != 0 ) {
10 p r i n t f ( ” E r r o r u s i n g ’ s e t V o x e l s ’ : %d\n” , e r r ) ;
11 r e t u r n −1;
12 }
13 // P r i n t ASCII f i l e
14 v o x e l g e o . p r i n t I m a g e ( ” voxelGeo . a s c i i ” ) ;
15 //Dump b i n a r y f i l e
16 v o x e l g e o . dump2File ( ” voxelGeo . b i n ” ) ;
Code 31: Set voxels function and geometry file creation
35
Regarding the geometry configuration step, the user must specify the parameters (nx, ny, nz)
and (dx, dy, dz) to describe the number of voxels and its dimensions, respectively, in each
axis. Also, dsmax can be specified as we done for quadric geometries. This one is done
following the template,
../../dsmax/n value
where n selects the material where dsmax will be applied and value the dsmax value.
Finally, the parameters to define a box enclosure surrounding the mesh must be specified.
These parameters are the enclosure-margin, which defines the distance, in cm, between
the enclosure and the mesh limits in all axes, and the enclosure-material, which sets the
enclosure material. An example of configuration file for voxelized geometries is shown in
the code 32.
1 geometry / type ”VOXEL”
2 geometry / f i l e n a m e ” 3 b l o c k s . vx ”
3 geometry / n v o x e l s /nx 60
4 geometry / n v o x e l s /ny 60
5 geometry / n v o x e l s / nz 80
6 geometry / v o x e l −s i z e /dx 0 . 2
7 geometry / v o x e l −s i z e /dy 0 . 2
8 geometry / v o x e l −s i z e / dz 0 . 1
9
10 geometry / e n c l o s u r e −margin 20
11 geometry / e n c l o s u r e −m a t e r i a l 5
12
13 geometry /dsmax /1 0.05
Code 32: Configuration of voxelized geometry example
5.3.5 DICOM
Medical images are usually stored using the international standard of Digital Imaging and
Communications in Medicine (DICOM). PenRed implements a DICOM geometry module
to convert the DICOM file to a voxel geometry automatically, which is ready to be simulated
directly. As other PenRed components, DICOM geometries require a specific configuration
structure to be used. This configuration includes the following parameters,
• type: Geometry type, must be set to “DICOM”.
• directory: Specifies the relative path where the DICOM images are stored. Notice
that all the DICOM images found in that folder are expected to be from the same
image.
• calibration: This optional parameter is only used for CT images. This must be
specified as an array of numbers which belong to a polynomial calibration to convert
from Hounsfield Units (HU) to density (g/cm3 ). If the calibration is not specified for
CT images, the raw data will be used and the density must be assigned using other
techniques, as we will see below.
• default/material: Specifies default material index for all voxels which material has
not been assigned by other methods.
36
• default/density: Specifies default density for all voxels which density has not been
assigned by any of the available methods.
• intensity-ranges: Provides a subsection to assign a material index and density value
to all voxels inside the specified pixel value ranges. This subsection consists of the
following parameters,
– material: Material index to assign.
– density: Density value (g/cm3 ) to assign.
– low: Lower range pixel value to assign this material and density.
– top: Upper range pixel value to assign this material and density.
So, all voxels with intensity values in the range [low, top) will be assigned with the
material index material and the density value density. To differentiate between ranges,
each one requires a unique name. This name must not be the material name, but is
advisable for debug purposes. An example of this configuration is shown in code 33,
where we define an interval named Air.
1 geometry / i n t e n s i t y −r a n g e s / Air / m a t e r i a l 1
2 geometry / i n t e n s i t y −r a n g e s / Air / low −2000
3 geometry / i n t e n s i t y −r a n g e s / Air / top −500
4 geometry / i n t e n s i t y −r a n g e s / Air / d e n s i t y 0 . 0 0 1 2 9 0
Code 33: DICOM intensity ranges configuration
• ranges: Subsection analogous to intensity-ranges but using density ranges instead of

pixel values. Thus it could be used to specify the voxels material indexes via density
ranges. Notice that it is required a calibration curve to previously convert HU units
to densities. This subsection consists of the following parameters,
– material: Material index to assign.
– density-low: Minimum density value for this range.
– density-top: Maximum density value for this range.
All voxels with a density value between (density − low, density − top] will be
assigned with the material index material.
• contours: Subsection that allows to the user to assign materials and densities accord-
ing to contours stored inside the DICOM image. Each subsection of this type defines a
single contour which name is specified in the corresponding parameters paths. Notice
that the contour name must coincide with the contour name stored in the DICOM
file. This subsection contains the following parameters,
– material: Default material to assign to this contour. This is an optional field.
If it is not provided, the existing material assign will not be overwritten.
– density: Default density to assign to this contour (g/cm3 ). This is an optional
field. If it is not provided, the voxel density will be not overwritten.
– priority: A priority value to control which contours are overwritten by other
ones. Contours with lower priority values will be overwritten by contours with
higher priority values.
– intensity-ranges: Material and density can also be assigned defining intensity
ranges specific for each contour. This method overwrites the specified default
material and density for the contour. To define the ranges, use the same pattern
explained for global intensity-ranges.
37
– ranges: Materials can also be assigned defining density ranges specific for each
contour. This method overwrites the specified default material for the contour.
To define the ranges, use the same pattern explained for global ranges.
For example, to configure a contour named target, with air in some regions, the con-
figuration file should contain something like the lines shown in code 34.
1 geometry / c o n t o u r s / t a r g e t / m a t e r i a l 1
2 geometry / c o n t o u r s / t a r g e t / d e n s i t y 1 . 0 5
3 geometry / c o n t o u r s / t a r g e t / p r i o r i t y 1 . 0
4
5 geometry / c o n t o u r s / t a r g e t / i n t e n s i t y −r a n g e s / Air / m a t e r i a l 2
6 geometry / c o n t o u r s / t a r g e t / i n t e n s i t y −r a n g e s / Air / low −2000
7 geometry / c o n t o u r s / t a r g e t / i n t e n s i t y −r a n g e s / Air / top −500
8 geometry / c o n t o u r s / t a r g e t / i n t e n s i t y −r a n g e s / Air / d e n s i t y 0 . 0 0 1 2 9 0
Code 34: DICOM contour configuration
To assign a uniform material and density in the contour, just don’t specify any range.
• enclosure-margin: Like the voxel based geometry case, specify the distance between
the DICOM mesh corner and the limit of an external enclosure, in cm.
• enclosure-material: Specify the enclosure material index.
• print-ASCII: This true/false optional configuration parameter, can be set to true to

print the processed DICOM in ASCII format. The data will be stored in a file named
dicomASCII.rep.
Notice that this geometry type presents several ways to assign material indexes and
densities to voxels. Due to this characteristic, exists a method hierarchy where preferential
methods overwrite the others. This preference is shown in the Figure 10.
Figure 10: DICOM voxels material an density assign methods hierarchy.
Notice also that the allowed image modalities for DICOM geometry type are, by the
moment, Computed Tomography (CT), Ultrasound (US), Radiotherapy Structure Set (RT-
STRUCT) and Radio-therapy Plan (RTPLAN). Positron emission tomography (PT) is also
38
accepted, but not for geometry construction purposes. Instead, PET images can be used
to create a spatial sampling.
A DICOM example where voxel density and material are set using only intensity ranges
can be found at the example folder. This one reproduces the GEANT IV DICOM simulation
example using the DICOM image developed at [10]. So, the user must download that
DICOM to reproduce the example.
5.3.6 Combo
The geometry type “COMBO” provides the capability to merge different geometries of any
type in a single one. There is no limit to the number of geometries that can be combined.
To determine which geometry exists in each region, each one must be assigned with an
integer priority in the range [0, N ), where N is the number of geometries to combine. Then,
the geometry with priority 0 will overwrite geometries with priorities [1, N ), the priority 1
will overwrite the priorities [2, N ), and so on.
Regarding geometries with higher priority numbers, these will overwrite only the void
regions of geometries with lesser priority index. Therefore, a particle will only “see” the
geometry with priority n, at the position (x, y, z), if all geometries with priority indexes in
the range [0, n) are void at (x, y, z).
Notice that is not possible to define a “transparent” material to be overwrite by higher
priority indexes as is done for void. This feature has not been implemented because its high
impact on simulation speed.
The parameters to configure this type of geometry are listed below,
• type: Must be set to “COMBO”
• geometries: Is a subsection containing the information of each combined geometry.

Each geometry is identified by a name. Therefore, to specify the parameters of geom-
etry accelerator we must use the path,
geometries/accelerator/path/to/parameter
The parameters to be specified for each geometry are:
– priority: The priority integer index in the range [0, N ), where N is the number
of combined geometries.
– config: A subsection containing all the required parameters to configure the
geometry. Therefore, this subsection depends on the type of the geometry to be
combined.
An example of configuration is shown in the Code 35, where three quadric geometries,
named 1, 2, 3, are combined.
1 geometry / type ”COMBO”
2
3 geometry / g e o m e t r i e s /1/ p r i o r i t y 2
6
7 geometry / g e o m e t r i e s /1/ c o n f i g / type ”PEN QUADRIC”
8 geometry / g e o m e t r i e s /1/ c o n f i g / input − f i l e ” 1 . geo ”
9 geometry / g e o m e t r i e s /1/ c o n f i g / p r o c e s s e d −geo− f i l e ” r e p o r t 1 . geo ”
10
39
14
Code 35: Geometry “COMBO” type configuration example.
Although combining geometries is generally slower, it could simplify the optimization
in some cases, for example allowing the usage of modules in combined quadric geometries.
Therefore, in some particular cases, in addition to simplify the geometry construction, it
could speed-up the simulation.
A more interesting usage case is the combination of different types of geometries. For
example, the Code 36 shows the combination of a seed constructed using quadric geometries
with a DICOM based geometry where the materials are assigned via contours. In this
example, the seed geometry overwrites the DICOM.
1
2 geometry / type ”COMBO”
3
4 geometry / g e o m e t r i e s / s e e d / p r i o r i t y 0
5 geometry / g e o m e t r i e s /DICOM/ p r i o r i t y 1
6
7 geometry / g e o m e t r i e s / s e e d / c o n f i g / type ”PEN QUADRIC”
8 geometry / g e o m e t r i e s / s e e d / c o n f i g / input − f i l e ” s e e d . geo ”
9 geometry / g e o m e t r i e s / s e e d / c o n f i g / p r o c e s s e d −geo− f i l e ” r e p o r t . geo ”
10
11 geometry / g e o m e t r i e s /DICOM/ c o n f i g / type ”DICOM”
12 geometry / g e o m e t r i e s /DICOM/ c o n f i g / d i r e c t o r y ”test mamaHDR”
13
14 #Contour a s s i g n
15 geometry / g e o m e t r i e s /DICOM/ c o n f i g / e n c l o s u r e −margin 20
16 geometry / g e o m e t r i e s /DICOM/ c o n f i g / e n c l o s u r e −m a t e r i a l 4
17
18 geometry / g e o m e t r i e s /DICOM/ c o n f i g / d e f a u l t / m a t e r i a l 4
19 geometry / g e o m e t r i e s /DICOM/ c o n f i g / d e f a u l t / d e n s i t y 1 . 2 0 0 0E−03
20
21 geometry / g e o m e t r i e s /DICOM/ c o n f i g / c o n t o u r s / body / m a t e r i a l 1
22 geometry / g e o m e t r i e s /DICOM/ c o n f i g / c o n t o u r s / body / d e n s i t y 1 . 0
23 geometry / g e o m e t r i e s /DICOM/ c o n f i g / c o n t o u r s / body / p r i o r i t y 2 . 2
24
25 geometry / g e o m e t r i e s /DICOM/ c o n f i g / c o n t o u r s / h e a r t / m a t e r i a l 2
26 geometry / g e o m e t r i e s /DICOM/ c o n f i g / c o n t o u r s / h e a r t / d e n s i t y 1 . 5
27 geometry / g e o m e t r i e s /DICOM/ c o n f i g / c o n t o u r s / h e a r t / p r i o r i t y 2 . 6
28
29 geometry / g e o m e t r i e s /DICOM/ c o n f i g / c o n t o u r s / s k i n / m a t e r i a l 3
30 geometry / g e o m e t r i e s /DICOM/ c o n f i g / c o n t o u r s / s k i n / d e n s i t y 1 . 1
31 geometry / g e o m e t r i e s /DICOM/ c o n f i g / c o n t o u r s / s k i n / p r i o r i t y 2 . 3
32
33 geometry / g e o m e t r i e s /DICOM/ c o n t o u r s / l e f t l u n g / m a t e r i a l 4
34 geometry / g e o m e t r i e s /DICOM/ c o n t o u r s / l e f t l u n g / d e n s i t y 1 . 2 E−03
35 geometry / g e o m e t r i e s /DICOM/ c o n t o u r s / l e f t l u n g / p r i o r i t y 2 . 3
36
37 geometry / g e o m e t r i e s /DICOM/ c o n t o u r s / r i g h t l u n g / m a t e r i a l 4
38 geometry / g e o m e t r i e s /DICOM/ c o n t o u r s / r i g h t l u n g / d e n s i t y 1 . 2 E−03
39 geometry / g e o m e t r i e s /DICOM/ c o n t o u r s / r i g h t l u n g / p r i o r i t y 2 . 3
40
41 geometry / g e o m e t r i e s /DICOM/ c o n t o u r s / l e f t r i b s / m a t e r i a l 5
42 geometry / g e o m e t r i e s /DICOM/ c o n t o u r s / l e f t r i b s / d e n s i t y 1 . 9 2
43 geometry / g e o m e t r i e s /DICOM/ c o n t o u r s / l e f t r i b s / p r i o r i t y 2 . 3
40
44
45 geometry / g e o m e t r i e s /DICOM/ c o n t o u r s / r i g h t r i b s / m a t e r i a l 5
46 geometry / g e o m e t r i e s /DICOM/ c o n t o u r s / r i g h t r i b s / d e n s i t y 1 . 9 2
47 geometry / g e o m e t r i e s /DICOM/ c o n t o u r s / r i g h t r i b s / p r i o r i t y 2 . 3
48
49 geometry / g e o m e t r i e s /DICOM/ c o n t o u r s / ptv / m a t e r i a l 6
50 geometry / g e o m e t r i e s /DICOM/ c o n t o u r s / ptv / d e n s i t y 1 . 0
51 geometry / g e o m e t r i e s /DICOM/ c o n t o u r s / ptv / p r i o r i t y 2 . 5
Code 36: Geometry “COMBO” with quadric and DICOM geometries.
5.4 Tallies
Configurations for tallies are similar to sources. The pattern to configure tallies is exempli-
fied in the code 37, where tallies is a constant text, tally-name is a user defined name for
the tally, and parameter/path and value sets the tally parameters, whose depends on tally
type.
1 t a l l i e s / t a l l y −name/ parameter / path v a l u e
Code 37: Tally configuration pattern
As sources and geometries, exists several tally types, so the user must specify the pa-
rameter type on each created tally. In addition to tally type, a path to save the tally results
can be specified via the outputdir parameter. Both parameters are common to all tallies,
and are shown in the Code 38.
1 t a l l i e s / t a l l y −name/ type ”TYPE STRING”
2 t a l l i e s / t a l l y −name/ o u t p u t d i r ” path / t o / r e s u l t s / d i r / ”
Code 38: Tally common parameters
Notice that, in the outputdir value, the remaining path after the last slash (“/” or
“\” for unix and windows based systems respectively) will be appended as a prefix to the
results filename instead of be interpreted as a directory. The Table 8 shows some cases to
exemplify this behaviour, where the left column represents the value of outputdir specified
in the configuration file, and the right column the final file path in the OS file system.
If the specified path does not exists, i.e. one or more directories have been not created
by the user, PenRed will try to append the prefix “not-found” to the filename and create
the corresponding file in the execution directory, in order to avoid losing the simulation
progress.
outputdir path final path

dir1/ dir1/filename
dir1 dir1filename
dir1/dir2/ dir1/dir2/filename
dir1/dir2 dir1/dir2filename
Table 8: Tally outputdir behaviour examples.
An example of complete tally configuration is shown in the Code 39, which corresponds
to a cylindrical dose distribution tally. This one requires limits for radial distance (rmin to
rmax), number of radial bins nbinsr, limits for z axis (zmin to zmax) and the number of z
bins (nbinsz).
2 t a l l i e s / c y l D o s e D i s t r i b / p r i n t −xyz t r u e
3 t a l l i e s / c y l D o s e D i s t r i b / rmin 0 . 0
41
4 t a l l i e s / c y l D o s e D i s t r i b /rmax 3 0 . 0
5 t a l l i e s / c y l D o s e D i s t r i b / n b i n s r 60
6 t a l l i e s / c y l D o s e D i s t r i b / zmin 0
7 t a l l i e s / c y l D o s e D i s t r i b /zmax 3 0 . 0
8 t a l l i e s / c y l D o s e D i s t r i b / n b i n s z 60
Code 39: Tally configuration pattern
An aspect to consider when we are choosing the limits, is that the behaviour of the
intervals is [min, max). Thus, in the previous example, rmax and zmax are out of their
respective intervals.
The next subsections describe briefly the data measured in each tally and provide an
example to use them at the configuration file.
5.4.1 Radial and Cylindrical Dose Distribution

This tally measures the absorbed dose in (eV/g) for each radial bin in the range of [rmin, rmax),
in cm and can be configured to measure the depth absorbed dose distribution. Regarding
the units, all results are expressed in (eV cm/g) per history. Below is shown the available
parameters of this tally,
• type “CYLINDRICAL DOSE DISTRIB”: Type name of the tally.
• print-xyz: This variable can be set to true to print more information in the results
file. If activated, two extra values per bin coordinate are printed, which corresponds
to the coordinates low and the average values. For z coordinates, the average value
is considered at the middle point of the bin. For the r coordinate, the average is
weighted with a weight proportional to the radius r. If print − xyz is not specified, is
set to false by default.
• rmin: Minimum value of the radial coordinate. Must be greater than zero and lower
than rmax.
• rmax: Maximum value of the radial coordinate.
• nbinsr: Number of radial bins. Must be at least 1.
• zmin: Minimum value of the depth coordinate. Must be lower than zmax when nbinsz
is set greater to zero.
• zmax: Maximum value of the depth coordinate. Must be set to zmin when depth
absorbed dose is not measured.
• nbinsz: Number of depth bins. Must be set to zero when depth absorbed dose is not
measured, otherwise, must be at least 1.
• nbinsPhi: Number of angular (φ) bins. By default, this parameter is set to 1.
Regarding the value types, the limits of radial and depth intervals must be doubles,
while the number of bins in each case must be integers. The output filename of this tally
ends with cylindricalDoseDistrib.dat but, if we disable the depth absorbed dose measure in
the configuration, the output filename will end with radialDoseDistrib.dat.
An example of configuration for this tally is shown in the code 40, which has been
extracted from the file disc.in of the example 1-disc.
42
2 t a l l i e s / c y l D o s e D i s t r i b / p r i n t −xyz t r u e ( optional )
3 t a l l i e s / c y l D o s e D i s t r i b / rmin 0 . 0 ( mandatory )
4 t a l l i e s / c y l D o s e D i s t r i b /rmax 0 . 0 1 ( mandatory )
5 t a l l i e s / c y l D o s e D i s t r i b / n b i n s r 50 ( mandatory )
6 t a l l i e s / c y l D o s e D i s t r i b / zmin 0 . 0 ( mandatory )
7 t a l l i e s / c y l D o s e D i s t r i b /zmax 0 . 0 0 5 ( mandatory )
8 t a l l i e s / c y l D o s e D i s t r i b / n b i n s z 100 ( mandatory )
9 t a l l i e s / cylDoseDistrib / nbinsPhi 1 ( optional )
Code 40: Cylindrical dose distribution tally configuration
5.4.2 Emerging Particles Distribution

This tally measures the energy distribution of particles that left the geometry within a
specific energy range of [emin, emax), expressed in particles/(eV history). We consider
two cases in this tally. First, down bound emerging particles, which W direction is lower
or equal to zero. Then, the up bound case when the W value is greater than zero. Also,
the tally measures the number of particles that left the geometry per steradian determined
by the theta and phi angular values, in degrees, of the particle deviation. In this case,
measurements are in particles/(sr history).
The tally information needed in the configuration file is shown below,
• type “EMERGING PART DISTRIB”: Type name of the tally.
• emin: Minimum energy value. Must be lower than emax.
• emax: Maximum energy value.
• nBinsE: Number of energy bins. Must be at least 1.
• nBinsTheta: Number of polar bins. Must be greater than zero.
• nBinsPhi: Number of azimuthal bin, Must be greater than zero.
Regarding the values types, the energy limits must be doubles, while the bin numbers
must be integers. The output files of this tally end as: emergin-downbound.dat, emergin-
upbound.dat, emergin-angle.dat, with information for theta and phi values and emergin-
polar-angle.dat with only angular information of theta values.
The code 41 is an example of this tally, which has been extracted from the configuration
file detector1.in of the example 3-detector-1:
1 t a l l i e s / E m e r g i n g P a r t D i s t r i b / type ”EMERGING PART DISTRIB”
2 t a l l i e s / E m e r g i n g P a r t D i s t r i b / emin 0 . 0 ( mandatory )
3 t a l l i e s / E m e r g i n g P a r t D i s t r i b /emax 1 . 4 5 e6 ( mandatory )
4 t a l l i e s / E m e r g i n g P a r t D i s t r i b / nBinsE 280 ( mandatory )
5 t a l l i e s / E m e r g i n g P a r t D i s t r i b / nBinsTheta 45 ( mandatory )
6 t a l l i e s / E m e r g i n g P a r t D i s t r i b / nBinsPhi 18 ( mandatory )
Code 41: Emerging particles tally configuration
5.4.3 Energy Deposition Body

This tally measures the energy, in eV per history, deposited in each body. To use it, only
the type parameter, to select the tally itself, is required,
• type “EDEP BODY”: Type name of the tally.
43
The output filename ends with bodyEnergyDeposition.dat.
A configuration example of this tally is show in the code 42, which belongs to the file
plane.in of the example 2-plane.
1 t a l l i e s /bodyEDep/ type ”EDEP BODY”
Code 42: Energy deposition in body tally configuration
5.4.4 Energy Deposition Material

This tally measures the energy, in eV per history, deposited in each material. To use it,
only the type parameter, to select the tally itself, is required,
• type “EDEP MAT”: Type name of the tally.
The corresponding output file ends with materialEnergyDeposition.dat

The code 43 shows a configuration example obtained from the configuration file detec-
tor1.in belonging to the example 3-detector-1.
1 t a l l i e s /matEDep/ type ”EDEP MAT”
Code 43: Energy deposition in material tally configuration
5.4.5 Impact Detector

This tally is cabaple to measure different magnitudes: fluence spectrum, particle energy
spectrum and particle age. Each one is described following,
• Fluence: integrates the spectral fluence over the detector volume in cm/eV. The
output file contains the fluence for each particle type and the total fluence in the
specified detector. The filename ends with fluenceTackLength-num.dat, where num is
the corresponding detector number.
• Energy spectrum: reports the energy spectrum of particles which enter in the specified
detector volume. Particles created inside the detector, for example secondary particles,
are not considered in this tally. Units are expressed in 1/(eV history). The output
file contains the energy spectrum for each particle type and the total spectrum in the
specified detector is also measured. The filename ends with spectrum-impdet-num.dat,
where num is the number of the assigned detector.
• Age: reports the age distribution of particles which impact to the considered detector,
in units of 1/(seconds history). The output file that ends with age-impdet-num.dat,
contains the probability distribution along each time interval over all simulated par-
ticles. As in the previous cases, num is the number that identifies the the detector.
• Energy deposition: reports the energy deposited spectrum measured in the consid-
ered detector. Units are expressed in 1/(eV history). The output file ends with
energyDeposition-impdet-num.dat, where num is the number of the detector. This
file contains the probability distribution along each energy interval for the specific
detector over all simulated particles.
Regarding the configuration parameters, these are listed below:

• type “IMPACT DET”: Type name of the tally.
• detector: Detector index where the measurements of this tally are taken.
44
• fluence: Must be set to true to obtain fluence measurements, otherwise set it to
false. If this information is not specified, false value will be assigned by default.
• emin: Minimum energy value for tallied particles in fluence, energy spectrum and
energy deposition measurements.
• emax: Maximum energy value for tallied particles in fluence, energy spectrum and
energy deposition measurements. Must be greater than emin.
• nbin-energy: Number of energy bins, which is used for fluence, energy spectrum and
energy deposition. Must be at least 1.
• spectrum: Must be set to true to obtain spectrum measurements, otherwise set it

to false. If this information is not specified, false is set as default value.
• age: Must be set to true to obtain age measurements, otherwise set it to false. If
this information is not specified, false is set as default value.
• enegy-dep: Must be set to true to obtain energy deposition measurements, otherwise

set it to false. If this information is not specified, false value will be assigned by
default.
• linearScale-spc: Determines if energy spectrum measurements will be tallied using a

liner scale (true) or a logarithmic scale (false). When this parameter is not specified,
linear scale is selected by default (true).
• linearScale-edep: By default is set to true, meaning that the energy deposition

will be tallied using a linear scale. Instead, if set to false, the tally will be created
following a logarithmic scale.
• linearScale-age: Determines if the output measurements for the age spectrum are
expressed using a linear scale (true) or a logarithmic scale (false). If not specified, a
linear scale is selected by default (true).
• nbin-age: Number of age interval bins. Is only required if age is active and must be
at least 1.
• age-min: Minimum value of the age interval.
• age-max: Maximum value of the age interval. Must be greater than age-min.
Regarding the parameter types, the interval limits in each case must be doubles and the
bin numbers must be specified as integers.
To exemplify the tally usage, next are two examples to show diferent configurations for
this tally. First, code 44 shows a part of the configuration file plane.in of the 2-plane exam-
ple, where we the fluence, spectrum and age information are tallied. If fluence, spectrum,
age or energy deposition are activated, their corresponding fields are mandatory, otherwise
are neither used or expected.
1 t a l l i e s / I m p a c t D e t e c t o r / type ”IMPACT DET”
2 t a l l i e s / ImpactDetector / d e t e c t o r 1 ( mandatory )
3 t a l l i e s / ImpactDetector / f l u e n c e true ( optional )
4 t a l l i e s / I m p a c t D e t e c t o r / emin 1 . 0 e5 ( mandatory / o p t i o n a l )
5 t a l l i e s / I m p a c t D e t e c t o r /emax 3 . 5 e7 ( mandatory / o p t i o n a l )
6 t a l l i e s / I m p a c t D e t e c t o r / nbin−e n e r g y 100 ( mandatory / o p t i o n a l )
7 t a l l i e s / I m p a c t D e t e c t o r / l i n e a r S c a l e −f l n t r u e ( optional )
8 t a l l i e s / I m p a c t D e t e c t o r / spectrum t r u e ( optional )
45
9 t a l l i e s / I m p a c t D e t e c t o r / age t r u e ( optional )
10 t a l l i e s / I m p a c t D e t e c t o r / l i n e a r S c a l e −age f a l s e ( mandatory / o p t i o n a l )
11 t a l l i e s / I m p a c t D e t e c t o r / nbin−age 100 ( mandatory / o p t i o n a l )
12 t a l l i e s / I m p a c t D e t e c t o r / age−min 1 . 0 e−9 ( mandatory / o p t i o n a l )
13 t a l l i e s / I m p a c t D e t e c t o r / age−max 1 . 0 e−8 ( mandatory / o p t i o n a l )
Code 44: Impact detector tally configuration example 1
Secondly, code 45 shows some lines of the configuration file detector1.in that belongs to
the example 3-detector-1. In this example, only the energy deposition information is tallied.
1 t a l l i e s / I m p a c t D e t e c t o r / type ”IMPACT DET”
2 t a l l i e s / ImpactDetector / d e t e c t o r 1 ( mandatory )
3 t a l l i e s / I m p a c t D e t e c t o r / emin 0 . 0 e0 ( mandatory / o p t i o n a l )
4 t a l l i e s / I m p a c t D e t e c t o r /emax 1 . 4 5 e6 ( mandatory / o p t i o n a l )
5 t a l l i e s / I m p a c t D e t e c t o r / nbin−e n e r g y 280 ( mandatory / o p t i o n a l )
6 t a l l i e s / I m p a c t D e t e c t o r / energy−dep t r u e ( optional )
7 t a l l i e s / I m p a c t D e t e c t o r / l i n e a r S c a l e −edep t r u e ( optional )
Code 45: Impact detector tally configuration example 2
5.4.6 Spatial Dose Distribution

This tally measures the 3D absorbed dose distribution along the intervals [xmin, xmax),
[ymin, ymax) , [zmin, zmax) in cm. The units of dose values are eV/g per history. For
each coordinates, the user must select the number of bins used to report the data in each
axis (nx, ny, nz). In addition, the tally reports the depth dose distribution along the z
coordinate in eV/(g/cm2 ) .
The available tally parameters to configure are explained below,
• type “SPATIAL DOSE DISTRIB”: Type name of the tally.
• xmin: Minimum value of coordinate x.
• xmax: Maximum value of coordinate x. Must be greater than xmin.
• nx: Number of x bins. Must be, at least, 1.
• ymin: Minimum value of coordinate y.
• ymax: Maximum value of coordinate y. Must be greater than ymin.
• ny: Number of y bins. Must be at least 1.
• zmin: Minimum value of coordinate z.
• zmax: Maximum value of coordinate y. Must be greater than ymin.
• nz: Number of z bins. Must be at least 1.
• print-depthDose: Enables/disables printing depth dose information. Notice that

this depth dose is discretized only in the Z axis, i.e. scores all energy depositions
regardless the X and Y component. Therefore, in voxelized geometries, the enclosure
is considered in the calculus. By default is disabled.
Considering the parameters type, those who specify coordinate values must be doubles,
while the number of bins for each coordinate must be specified as integer. For plotting
purposes, two values per bin coordinate are given: the low and the middle point of each
46
bin. Output filenames end with spatialDoseDistrib-3D.dat for 3D absorbed dose distribu-
tion and depth-dose.dat for depth dose distribution. To exemplify the configuration, the
code 46 shows an example extracted from the configuration file disc.in that belongs to the
example 1-disc-novr.
1 t a l l i e s / S p a t i a l D o s e D i s t r i b / type ”SPATIAL DOSE DISTRIB”

2 t a l l i e s / S p a t i a l D o s e D i s t r i b / p r i n t −xyz t r u e ( optional )
3 t a l l i e s / S p a t i a l D o s e D i s t r i b /xmin 0 . 0 ( mandatory )
4 t a l l i e s / S p a t i a l D o s e D i s t r i b /xmax 1 . 0 ( mandatory )
5 t a l l i e s / S p a t i a l D o s e D i s t r i b /nx 1 ( mandatory )
6 t a l l i e s / S p a t i a l D o s e D i s t r i b /ymin 0 . 0 ( mandatory )
7 t a l l i e s / S p a t i a l D o s e D i s t r i b /ymax 1 . 0 ( mandatory )
8 t a l l i e s / S p a t i a l D o s e D i s t r i b /ny 1 ( mandatory )
9 t a l l i e s / S p a t i a l D o s e D i s t r i b / zmin 0 . 0 ( mandatory )
10 t a l l i e s / S p a t i a l D o s e D i s t r i b /zmax 0 . 0 0 5 ( mandatory )
11 t a l l i e s / S p a t i a l D o s e D i s t r i b / nz 100 ( mandatory )
12 t a l l i e s / S p a t i a l D o s e D i s t r i b / p r i n t −depthDose f a l s e ( optional )
Code 46: Spatial Dose Distribution tally configuration
5.4.7 Angular Detector

This tally reports the angular energy spectrum in a specified detector. This information
is tallied in the energy interval [emin, emax), specified in eV, and the angular intervals
[theta1, theta2), [phi1, phi2), specified in degrees. The energy spectra of particles is tallied
in units of 1/(eV sr particle).
Below, we describe the parameters used to configure this tally,
• type “ANGULAR DET ”: Tally type name.
• detector: Detector index where the angular detector will be calculated.
• emin: Minimum energy value.
• emax: Maximum energy value. Must be greater than emin.
• theta1: Minimum value of polar angle.
• theta2: Maximum value of polar angle. The polar interval must be in the range
(0, 180) and theta2 must be greater than theta1.
• phi1: Minimum value of azimuthal angle.
• phi2: Maximum value of azimuthal angle. The azimuthal interval must be in the
range (0, 360) or (−180, 180) and phi2 must be greater than phi1.
• nBinsE: Number of energy bins.
• linearScale: Determines if the output measurements are expressed in linear scale

(true) or in logarithmic scale (false). If scale is not specified, linear scale will be set.
The expected parameter types are integers for detector and and the number of bins,
and doubles for the energy and angular limits. The output filename for this tally ends with
spc-angdet-num.dat where num is the number of the assigned detector.
The code 47 belongs to the configuration of the example 1-disc-novr, where this tally
is used. The configuration file is named disc.in.
47
1 t a l l i e s / A n g u l a r D e t e c t o r / type ”ANGULAR DET”
2 t a l l i e s / AngularDetector / d e t ec t o r 1 ( mandatory )
3 t a l l i e s / A n g u l a r D e t e c t o r / emin 0 . 0 ( mandatory )
4 t a l l i e s / A n g u l a r D e t e c t o r /emax 4 0 . 5 e3 ( mandatory )
5 t a l l i e s / AngularDetector / theta1 90.0 ( mandatory )
6 t a l l i e s / AngularDetector / theta2 180.0 ( mandatory )
7 t a l l i e s / AngularDetector / phi1 0.0 ( mandatory )
8 t a l l i e s / AngularDetector / phi2 360.0 ( mandatory )
9 t a l l i e s / A n g u l a r D e t e c t o r / nBinsE 200 ( mandatory )
10 t a l l i e s / AngularDetector / l i n e a r S c a l e true ( optional )
Code 47: Angular detector tally configuration
5.4.8 Particle Generation

This tally reports information about the number of primary and secondary particles simu-
lated. First, counts the number of primary particles that escape up bound and down bound
and the number of absorbed particles. In addition, calculates the probabilities for secondary
particles to go up bound, down bound and be absorbed.
This tally doesn’t require to specify any parameter in the configuration file, only the
tally type,
• type “SECONDARY GEN”: Tally type name.
The output filename ends with particleGeneration.dat.

An example of the configuration file of this tally is code 48. This line is the same for all
examples where this tally will be used.
1 t a l l i e s / s e c o n d a r y / type ”SECONDARY GEN”
Code 48: Particle generation tally configuration
5.4.9 Spherical Dose Distribution

This tally reports the absorbed dose distribution, in (eV/g) per history, in a spherical
distribution, i.e. the bins follows spherical coordinates. By default, a single bin is used for
each angular coordinate and only a radial distribution is tallied in the range [rmin, rmax),
specified in cm. The number of radial bins are denoted by nbin and, optionally, the user
can activate the boolean print − xyz (true) to print different values for radial coordinate
in the output file: the low value and the average value. This average value is weighted
proportionally to r2 .
Tally configuration parameters are listed following:
• type “SPHERICAL DOSE DISTRIB ”: Type name of the tally.
• print-xyz: Can be set to true to print different values for radial coordinate in the
output file i.e the low value and the average value. This average value is weighted
proportionally to r2 . If this parameter is not specified, will be set to false by default.
• rmin: Minimum value of radial coordinate. Must be greater than zero.
• rmax: Maximum value of radial coordinate. Must be greater than rmin.
• nr: Number of radial bins. Must be at least 1.
• ntheta: Number of polar (θ) bins. By default, this parameter is 1.
48
• nphi: Number of azimuth (φ) bins. By default, this parameter is 1.
Regarding the parameter types, all limits are expected to be doubles and the number of
bins integers. The output filename ends with sphericalDoseDistrib.dat. Any of the provided
examples use this tally. However, a configuration example is shown in the code 49.
1 t a l l i e s / S p h e r i c a l D o s e / type ”SPHERICAL DOSE DISTRIB) ”
2 t a l l i e s / S p h e r i c a l D o s e / p r i n t −xyz t r u e ( optional )
3 t a l l i e s / S p h e r i c a l D o s e / rmin 0 . 0 ( mandatory )
4 t a l l i e s / S p h e r i c a l D o s e /rmax 0 . 0 6 ( mandatory )
5 t a l l i e s / S p h e r i c a l D o s e / nr 65 ( mandatory )
6 t a l l i e s / SphDoseDistrib / ntheta 1 ( optional )
7 t a l l i e s / S p h D o s e D i s t r i b / nphi 1 ( optional )
Code 49: Spherical dose distribution tally configuration
5.4.10 Phase Space File (PSF)

This tally creates a particle phase space file which store all particles that impact at the
specified detector. Also, the stored particles can be limited by a energy range.
The available tally parameters for the configuration file are listed following:
• type “PSF ”: Type name of the tally.
• detector: Detector index where this tally will be calculated.
• emin: Minimum energy value.
• emax: Maximum energy value. Must be greater than emin.
1 t a l l i e s / p s f / type ”PSF” ( mandatory )

2 t a l l i e s / psf / detector 1 ( mandatory )
3 t a l l i e s / p s f / emin 0 . 0 ( mandatory )
4 t a l l i e s / p s f /emax 6 . 1 e6 ( mandatory )
Code 50: Phase space file tally configuration
This tally can be used with multiple threads. In that case, each thread will store,
temporally, their psf particles in an independent file. Then, when the simulation finishes,
all files will be concatenated automatically ordered by the thread ID ascending order.
5.4.11 Kerma track length estimator

This tally is based on the equivalence of particle fluence and the total photon path length
per unit volume. A complete description of the estimator can be found at [11]. The
estimator could be tallied using three type of meshes: Voxel or cartesian based, cylindrical
and spherical meshes. The required configuration for this tally is listed below.
• type “KERMA TRACK LENGTH”: Type name of the tally.
• emin: Photon minimum energy to be considered (eV).
• emax: Photon maximum energy to be considered (eV).
• dataFiles: One data filename with the µen /ρ (cm2 /g) coefficients per tallied material
is required. However, if the file does not exists, the tally will create the corresponding
µen /ρ data automatically. Then, the data will be stored in the specified file.
49
Each filename is specified following this pattern:
path/to/tally/dataFiles/material-number "filename"
The data files format consists of two columns. The first one stores the energy in eV
and the second the corresponding µen /ρ value in (cm2 /g). The provided points must
contain the energy range [emin, emax]. However, is not required a constant energy
distance between points. Furthermore, there are no limit to the number of points in
each data file. Notice that materials with no µen /ρ data filename provided will be
ignored by the tally. To obtain the µen /ρ coefficients manually, the utility mutren
can be used. This one is provided in the PenRed package and described in the section
7.2. On the other hand, the user can let it be calculated automatically, as discussed
before.
• cartesian: If this optional section exists, the tally will record the estimator using a
regular voxel mesh. The required parameters are listed below:
– cartesian/nx: Number of bins on the X axis.

– cartesian/xmin: Init mesh point on X axis in cm.
– cartesian/xmax: Limit mesh point on X axis in cm.
– cartesian/ny: Number of bins on the Y axis.
– cartesian/ymin: Init mesh point on Y axis in cm.
– cartesian/ymax: Limit mesh point on Y axis in cm.
– cartesian/nz: Number of bins on the Z axis.
– cartesian/zmin: Init mesh point on Z axis in cm.
– cartesian/zmax: Limit mesh point on Z axis in cm.
• cylindrical: If this optional section exists, the tally will record the estimator using a
cylindrical mesh. The required parameters are listed below:
– cylindrical/nr: Number of radial bins.

– cylindrical/rmin: Cylinder minimum radius in cm.
– cylindrical/rmax: Cylinder maximum radius in cm.
– cylindrical/nphi: Number of angular (φ) bins.
– cylindrical/nz: Number of Z bins.
– cylindrical/zmin: Init mesh point on Z axis in cm.
– cylindrical/zmax: Limit mesh point on Z axis in cm.
• spherical: If this optional section exists, the tally will record the estimator using a
spherical mesh. The required parameters are listed below:
– spherical/nr: Number of radial bins

– spherical/rmin: Sphere minimum radius in cm.
– spherical/rmax: Sphere maximum radius in cm.
– spherical/ntheta: Number of polar angular (θ) bins.
– spherical/nphi: Number of azimuth angular (φ) bins.
50
Notice that more than one mesh type could be active at the same tally. In these cases,
the tally will generate one report for each mesh type. In code 51 we show a configuration
example for that tally.
1 t a l l i e s / kermaTrackLength / type ”KERMA TRACK LENGTH” ( mandatory )
2 t a l l i e s / kermaTrackLength / emin 1 . 0 e3 ( mandatory )
3 t a l l i e s / kermaTrackLength /emax 1 . 5 e6 ( mandatory )
4 t a l l i e s / kermaTrackLength / d a t a F i l e s /1 ”mu−Water1000 . mat” ( mandatory )
5
6 #O p t i o n a l s e c t i o n :
7 t a l l i e s / kermaTrackLength / c y l i n d r i c a l / nr 10 ( mandatory )
8 t a l l i e s / kermaTrackLength / c y l i n d r i c a l / rmin 0 . 1 ( optional )
9 t a l l i e s / kermaTrackLength / c y l i n d r i c a l /rmax 1 0 . 0 ( mandatory )
10 t a l l i e s / kermaTrackLength / c y l i n d r i c a l / nphi 10 ( mandatory )
11 t a l l i e s / kermaTrackLength / c y l i n d r i c a l / nz 10 ( mandatory )
12 t a l l i e s / kermaTrackLength / c y l i n d r i c a l / zmin −10.0 ( mandatory )
13 t a l l i e s / kermaTrackLength / c y l i n d r i c a l /zmax 1 0 . 0 ( mandatory )
14
16 t a l l i e s / kermaTrackLength / c a r t e s i a n /nx 10 ( mandatory )
17 t a l l i e s / kermaTrackLength / c a r t e s i a n /xmin −10.0 ( mandatory )
18 t a l l i e s / kermaTrackLength / c a r t e s i a n /xmax 1 0 . 0 ( mandatory )
19 t a l l i e s / kermaTrackLength / c a r t e s i a n /ny 10 ( mandatory )
20 t a l l i e s / kermaTrackLength / c a r t e s i a n /ymin −10.0 ( mandatory )
21 t a l l i e s / kermaTrackLength / c a r t e s i a n /ymax 1 0 . 0 ( mandatory )
22 t a l l i e s / kermaTrackLength / c a r t e s i a n / nz 10 ( mandatory )
23 t a l l i e s / kermaTrackLength / c a r t e s i a n / zmin −10.0 ( mandatory )
24 t a l l i e s / kermaTrackLength / c a r t e s i a n /zmax 1 0 . 0 ( mandatory )
25
27 t a l l i e s / kermaTrackLength / s p h e r i c a l / nr 10 ( mandatory )
28 t a l l i e s / kermaTrackLength / s p h e r i c a l /min 0 . 2 ( optional )
29 t a l l i e s / kermaTrackLength / s p h e r i c a l /rmax 1 0 . 0 ( mandatory )
30 t a l l i e s / kermaTrackLength / s p h e r i c a l / n t h e t a 10 ( mandatory )
31 t a l l i e s / kermaTrackLength / s p h e r i c a l / nphi 10 ( mandatory )
Code 51: Kerma track length tally configuration
Notice that the elements inside an optional section are mandatory only if the section
exists. For example, if the section tallies/kermaTrackLength/cartesian doesn’t exists,
any of the cartesian parameters are required, such as cartesian/nx or cartesian/xmin.
Regarding the parameter types, all bin number are expected to be integers, while the
corresponding limits are expected to be doubles.
5.4.12 CT tally
This tally has been created to collect the photons that arrive to a virtual detector. This
tally provides a file with CT sinogram report and a material energy deposition report by
projection. The tally information needed in the configuration file is described below.
• type “CT SINOGRAM”: Type name of the tally.
• emin: Photon minimum energy to be collect (eV).
• emax: Photon maximum energy to be collect (eV).
• npixels: Number of pixels of the virtual detector.
• pixel-depth: Size of pixel deph (cm).
51
• r-inner: Radius of the virtual detector. Corresponds to the isocenter-detector dis-
tance.
• xOrigin, yOrigin, zOrigin: x,y and z values of the CT origin. Corresponds to the
position of the CT isocenter.
• phi-ini: Initial angular position of the CT detector, in degrees. Must be set in front
of the CT source with an angular increment of 180 degrees.
• phi-end: Final angular position of the CT detector, in degrees. Must be set in front
of the CT source with an angular increment of 180 degrees.
• angularStep: Angular step between CT projection. Must be set with the same value
of the CT source angular step.
• aperture: Angle subtended by the detector with respect to the isocenter.
Usually, the angular aperture is provided by CT manufacturers as the angle subtended

with respect the CT source instead of with respect to the isocenter. The change to
the aperture needed by the configuration file can be done easily if the distance source-
detector is twice the distance isocenter-detector. In this case, the user can apply the
theorem of the central angle: The central angle subtended by two points on a circle is
twice the inscribed angle subtended by those points. This theorem only holds when
the source point is in the major arc. If this point is in the minor arc, it is, between the
detector limits, the relationship between these two angles is that the inscribed angle
is the supplement of half the central angle.
• particle: particle type that will be collect by the detector.
• tmin: Minimum time stamp of the particles of the first projection.
• timeInterval: Time interval between projections.
• scattered: This parameter offers the possibility to collect all the photons in the
energy range if it is set to true or collect only photons which have not been suffer
scatter. This is an optional parameter which is set to true by default.
1 t a l l i e s / CTsinogram / type ”CT SINOGRAM” ( mandatory )

2 t a l l i e s / CTsinogram / emin 0 . 0 ( mandatory )
3 t a l l i e s / CTsinogram /emax 1 . 0 e5 ( mandatory )
4 t a l l i e s / CTsinogram / n p i x e l s 700 ( mandatory )
5 t a l l i e s / CTsinogram / p i x e l −depth 4 ( mandatory )
6 t a l l i e s / CTsinogram / r−i n n e r 5 2 . 0 ( mandatory )
7 t a l l i e s / CTsinogram / x O r i g i n 0 . 0 ( mandatory )
8 t a l l i e s / CTsinogram / y O r i g i n 0 . 0 ( mandatory )
9 t a l l i e s / CTsinogram / z O r i g i n 0 . 0 ( mandatory )
10 t a l l i e s / CTsinogram / phi−i n i 0 ( mandatory )
11 t a l l i e s / CTsinogram / phi−end 360 ( mandatory )
12 t a l l i e s / CTsinogram / a n g u l a r S t e p 0 . 5 ( mandatory )
13 t a l l i e s / CTsinogram / a p e r t u r e 4 4 . 0 ( mandatory )
14 t a l l i e s / CTsinogram / p a r t i c l e ”gamma” ( mandatory )
15 t a l l i e s / CTsinogram / tmin 0 . 0 ( mandatory )
16 t a l l i e s / CTsinogram / t i m e I n t e r v a l 1 2 0 . 0 ( mandatory )
17 t a l l i e s / CTsinogram / s c a t t e r e d t r u e ( mandatory )
Code 52: CT tally configuration
52
5.4.13 DICOM kerma tally (Dose Volume Histogram)
This tally has been implemented to obtain the Dose Volume Cummulative Histogram (DVH)
for each contoured structure of a DICOM image. Therefore, this tally requires a DICOM
based geometry to be used. In addition, the specified DICOM must include a RTSTRUCT
file with the contour information.
To obtain the absorbed dose in Gy for each volume, this tally calculates the kerma,
using the kerma track length tally described in the section 5.4.11. However, because the
voxelized structure of DICOM images, it uses only the cartesian scoring method. The tally
information needed in the configuration file is described following:
• type “DICOM KERMA TRACK LENGTH”: Type name of the tally.
• kerma/emin: Photon minimum energy to be considered (eV).
• kerma/emax: Photon maximum energy to be considered (eV).
• kerma/dataFiles: One data file with the µen /ρ (cm2 /g) coefficients per tallied ma-
terial is required. This parameter is detailed in the Kerma track length estimator
tally, section 5.4.11.
• prescribedDose: Treatment prescribed dose, in Gy. If this parameter has not been
specified, it is set to 1 Gy.
• MCkerma2Dose: Conversion factor from kerma MC simulation units (eV/g per

history) to absolute dose units, which must be set in Gy/(eV/g per history).
The MCkerma2Dose factor is calculated using the equation 2.
1 Sk,P LAN
M Ckerma2Dose = ·t (2)
100 Sk,M C
where Sk,P LAN is the source air-kerma strength [12] which can be found in the DICOM
plan in U units (1U = cm2 · cGy/h). The Sk,M C value is the source air-kerma strength
obtained for the source with Monte Carlo simulation. The last one can be calculated
with the following relation,
eV · cm2

2
Sk,M C = KM C (d)d (3)
g · history
where KM C is the kerma in air in a thin air cell, such as a ring with 0.1cm width and
0.1cm depth, located on the seed transversal axis at a reference distance d, which is
usually set to d = 10 cm or d = 100 cm. Also, the source must be located in a vacuum
media. This configuration example is shown in the figure 11.
Thus, the resulting units for the Sk quotient are,
g · history cm2 · cGy

Sk,P LAN
·t [h]
Sk,M C eV · cm2 h

Sk,P LAN cGy · history
·t (4)
Sk,M C (eV /g)
Converting to Gy, we obtain the units of the equation 2.
53
Vacuum
Source
media
Air
cell
Figure 11: Geometry schema to calculate the Sk,M C factor using a ring air cell situated at
a reference distance d. The left image shows the central Z plane. The right image shows
the central X or Y plane.

1 Sk,P LAN Gy · history
M Ckerma2Dose = ·t (5)
100 Sk,M C (eV /g)
If the conversion factor is not specified, it will be set to 1.
• DVH-maxDose: Maximum dose value for the DVHs. If it is not specified, its value
is set to 3 times the prescribedDose.
• DVH-bins: Number of bins for the DVHs. If this parameter has not been specified,
it is set to 200.
1
2 t a l l i e s /DICOMkerma/ type ”DICOM KERMA TRACK LENGTH” ( mandatory )
3
4 t a l l i e s /DICOMkerma/ kerma / emin 2 . 5 e3 ( mandatory )
5 t a l l i e s /DICOMkerma/ kerma /emax 1 . 3 9 9 5 0E+06 ( mandatory )
6 t a l l i e s /DICOMkerma/ kerma / d a t a F i l e s /1 ” p r o s t a t e −mutren . dat ” ( mandatory )
7 t a l l i e s /DICOMkerma/ kerma / d a t a F i l e s /2 ” u r e t r a −mutren . dat ” ( mandatory )
8 t a l l i e s /DICOMkerma/ kerma / d a t a F i l e s /3 ” rectum−mutren . dat ” ( mandatory )
9 t a l l i e s /DICOMkerma/ kerma / d a t a F i l e s /4 ” b l a d d e r −mutren . dat ” ( mandatory )
10 t a l l i e s /DICOMkerma/ kerma / d a t a F i l e s /5 ”body−mutren . dat ” ( mandatory )
11 t a l l i e s /DICOMkerma/ kerma / d a t a F i l e s /6 ” bone−mutren . dat ” ( mandatory )
12
13 t a l l i e s /DICOMkerma/ p r e s c r i b e d D o s e 15 ( optional )
14 t a l l i e s /DICOMkerma/MCkerma2Dose 0 . 0 6 8 3 1 ( optional )
15 t a l l i e s /DICOMkerma/DVH−maxDose 40 ( optional )
16 t a l l i e s /DICOMkerma/DVH−b i n s 1000 ( optional )
Code 53: DICOM kerma tally configuration
Notice that the DICOM is not specified in the source configuration. This is because the
DICOM image is taken directly from the geometry.
54
5.4.14 Primary and Scatter Separated (PSS)
This one is a wrapper tally which score the contribution of primary, scattered and multi-
scattered radiation in three independent counters. To be able to combine it with differ-
ent counting procedures, it delegates the counting process to another existing tally type.
However, it has been designed for tallies scoring energy/dose deposition and will not be
compatible with all existing tallies.
To determine if a particle is considered primary, scattered or multi-scattered radiation, a
counter or bookkeeping (bkp) is used for each generated particle. However, only interactions
and productions of the selected particle type will increase the counter. For example, for
photons as the main particle, the following rules applies:
• Primary photons (γ1 ) start with bkp = 0. Any photon interaction (e.g., Compton)
occurring outside the source generates bkp+ = 1 (e.g., bkpγ1 = 1)
• Any secondary particle (e.g., Compton electrons), e1 , inherits the generation of the
incident photon (e.g., bkpe1 = 0).
• Any photon produced by these secondary particles (e.g., bremsstrahlung photon), γ2 ,

needs bkp+ = 1 (e.g., bkpγ2 = 1).
• The source materials (e.g., active core and encapsulation) don’t play any role in the
bkp of primary photons. However, once the primary particle is scattered once in the
phantom (e.g., water), the source starts acting like any other material, adding +1 to
the scattered photons’ bkp.
The configuration of this tally contains the following parameters,
• type ”PSS”: Type name of the tally.
• PSS-particle: Specify which particle must be considered as main radiation. If it is

not specified, photons are selected by default.
• PSS-source-mats: Consists of an array with the material indexes considered as

source materials. If it is not specified, no material will be considered as source.
• PSS-tally: Specify the tally type to be used to perform the scoring. For example
SPATIAL DOSE DISTRIB could be used. As discused, not all tallies are com-
patible with the PSS. The following tally types are compatible,
– ”ANGULAR DET”
– ”CYLINDRICAL DOSE DISTRIB”
– ”DICOM DOSE DISTRIB”
– ”DICOM KERMA TRACK LENGTH”
– ”EDEP BODY”
– ”EDEP MAT”
– ”EMERGING PART DISTRIB”
– ”KERMA TRACK LENGTH”
– ”SPATIAL DOSE DISTRIB”
– ”SPHERICAL DOSE DISTRIB”
and the non compatible types are,
55
– ”CT SINOGRAM”
– ”IMPACT DET”
– ”PSF”
– ”PSS”
– ”SECONDARY GEN”
– ”TRACK”
If the specified tally is not in either of the two lists a warning will be shown and the
correct behaviour of the tally is not guaranted.
In addition to the PSS parameters, the specific parameters of the selected tally must
be specified to configure them, as is shown in the Code 54. In this example, a cylindrical
dose tally is used and materials 1 and 2 are considered as source materials.
1 t a l l i e s / c y l D o s e D i s t r i b P S S / type ”PSS”
2 t a l l i e s / c y l D o s e D i s t r i b P S S /PSS−s o u r c e −mats [ 1 , 2 ]
3 t a l l i e s / c y l D o s e D i s t r i b P S S /PSS−t a l l y ”CYLINDRICAL DOSE DISTRIB”
4 t a l l i e s / c y l D o s e D i s t r i b P S S / p r i n t −xyz t r u e
5 t a l l i e s / c y l D o s e D i s t r i b P S S / rmin 0 . 0
6 t a l l i e s / c y l D o s e D i s t r i b P S S /rmax 0 . 0 1
7 t a l l i e s / c y l D o s e D i s t r i b P S S / n b i n s r 50
8 t a l l i e s / c y l D o s e D i s t r i b P S S / zmin 0 . 0
9 t a l l i e s / c y l D o s e D i s t r i b P S S /zmax 0 . 0 0 5
10 t a l l i e s / c y l D o s e D i s t r i b P S S / n b i n s z 100
Code 54: PSS tally configuration example combined with a cylindrical dose distribution
5.5 Variance Reduction

PenRed implements the very same variance reduction (VR) techniques as the original FOR-
TRAN code and some more. These are, for generic simulations, interaction forcing (IF),
x-ray and bremsstrahlung splitting. Then, phase space file based simulations adds particle
splitting and Russian Roulette techniques. Note that variance reduction for phase space file
will be configured via the corresponding particle source parameters, as we saw on section
5.2. In addition, PenRed implements generic splitting and Russian roulette as VR modules
and provide the capabilities to add new ones, as is explained in the section 5.5.
We have two types of VR techniques. First, the context specific techniques, which are
implemented inside the particle class, such as interaction forcing or bremsstrahlung splitting.
On the other hand, we have the VR techniques implemented as independent modules, such
as x-ray and generic splitting or Russian roulette.
5.5.1 Context specific

To use the first kind of techniques, the parameters in the configuration file use the pre-
fix VR, as shows code 55. There, vr-technique can be interaction forcing (IForcing) or
bremsstrahlung splitting (bremss). Then, on objectToApply, the user can select bodies or
materials to apply the variance reduction technique to a single body or to an entire material
respectively. Next, name is a user defined text identifier for this VR technique. Finally,
parameter/path and value depends on the VR type.
1 VR/ vr−t e c h n i q u e / objectToApply /name/ parameter / path / path v a l u e
Code 55: Variance reduction configuration pattern
56
First, lets see the interaction forcing (IF) configuration. The code 56 shows a complete
interaction forcing configuration used in the example 4-x-ray. As we can see, this example
enables interaction forcing in a single body, which alias is specified by the parameter body
as a string. Then, specify the kind of particle to force using the parameter particle and
the interaction numerical identifier to force (interaction). That identifier can be found on
section 4.4. The next parameter, factor, sets the interaction forcing amplification factor
and, finally, min-weight and max-weight limits the weight window where apply this VR
technique. Notice that a negative factor value will be interpreted as in the PENELOPE
main program, i.e., is assumed to mean that a particle with energy E = EP M AX should
interact, on average, +factor times in the course of its slowing down to rest, for electrons
and positrons, or along a mean free path, for photons.
1 VR/ I F o r c i n g / b o d i e s /VR1/ body ” 1 ”
2 VR/ I F o r c i n g / b o d i e s /VR1/ p a r t i c l e ” e l e c t r o n ”
3 VR/ I F o r c i n g / b o d i e s /VR1/ i n t e r a c t i o n 2
4 VR/ I F o r c i n g / b o d i e s /VR1/ f a c t o r 400
5 VR/ I F o r c i n g / b o d i e s /VR1/min−w e i g h t 0 . 1
6 VR/ I F o r c i n g / b o d i e s /VR1/max−w e i g h t 2
Code 56: Interaction forcing configuration for bodies
To set the same interaction forcing on materials, simply substitute bodies by materials,
body parameter by mat-index and set the material index where apply VR as a integer value.
For example, to apply this IF on material 2 the configuration should look like code 57.
1 VR/ I F o r c i n g / m a t e r i a l s /VR1/mat−i n d e x 2
2 VR/ I F o r c i n g / m a t e r i a l s /VR1/ p a r t i c l e ” e l e c t r o n ”
3 VR/ I F o r c i n g / m a t e r i a l s /VR1/ i n t e r a c t i o n 2
4 VR/ I F o r c i n g / m a t e r i a l s /VR1/ f a c t o r 400
5 VR/ I F o r c i n g / m a t e r i a l s /VR1/min−w e i g h t 0 . 1
6 VR/ I F o r c i n g / m a t e r i a l s /VR1/max−w e i g h t 2
Code 57: Interaction forcing configuration for materials
Next technique, bremsstrahlung splitting, requires one or two parameters depending on

whether the VR is specified for bodies or materials respectively. Both patterns are shown
in the code 58, where body-alias must be substituted by the body alias where we want to
apply the splitting, splitting-factor specify the number of times bremsstrahlung photons will
be cloned and imat is the material index where apply splitting.
1 VR/ bremss / b o d i e s /body−a l i a s / s p l i t t i n g s p l i t t i n g −f a c t o r
2
3 VR/ bremss / m a t e r i a l s /mat−i n d e x imat
4 VR/ bremss / m a t e r i a l s / s p l i t t i n g s p l i t t i n g −f a c t o r
Code 58: Bremsstrahlung splitting configuration for bodies and materials
5.5.2 Specific VR techniques

A specific VR techniques can be used only on a specific particle state type. All of them,
when used in the PenRed provided main program, follows the configuration pattern code
59.
1 VR/ ty pe / vr−name/ parameter / path v a l u e
Code 59: Specific VR technique parameter configuration pattern
Actually, PenRed only provides specific VR techniques for photons. Thus, the only
possible value for the specific VR type is photon.
57
1 VR/ photon / vr−name/ parameter / path v a l u e
Code 60: Photons VR technique parameter configuration pattern
The parameter vr-name specify a name for this VR instance and is only used for iden-
tification purposes.
5.5.2.1 X-Ray splitting

X-Ray splitting uses a pattern similar to bremsstrahlung case, an example can be found in
the example 1-disc-vr and all the available parameters are summarised in the code 61.
1 VR/ photon / vr−name/ type ”XRAY SPLITTING” ( mandatory )
2
3 VR/ photon / vr−name/ b o d i e s /body−a l i a s / s p l i t t i n g s p l i t t i n g −f a c t o r ( optional )
4
5 VR/ photon / vr−name/ m a t e r i a l s /mat−i n d e x imat ( optional )
6 VR/ photon / vr−name/ m a t e r i a l s / s p l i t t i n g s p l i t t i n g −f a c t o r ( optional )
Code 61: X-ray splitting configuration for bodies and materials
First, the VR type is specified by the parameter type. Then, the other parameters
VR/photon/name/bodies/... and VR/photon/name/materials/... are analogous to the
bremsstrahlung case.
5.5.3 Generic VR techniques

Generic VR techniques can be used on all particle state types. All of them, when used in
the PenRed provided main program, follows the configuration pattern shown in the code
62.
1 VR/ g e n e r i c / vr−name/ parameter / path v a l u e
Code 62: Specific VR technique parameter configuration pattern
where vr-name specify the VR instance name for identification purposes.
5.5.3.1 Splitting
The splitting VR technique consists of cloning the particle and reducing its weight by a
factor equal to the number of clones. Thus, if a particle with a weight W GHT is split
in 10 clones, counting itself, the weight of all the resulting particles will be W GHT /10.
An example of configuration can be found in the example 8-fake-chamber. Also, all the
parameters are shown in the code 63 and explained below,
• type: Specify the VR type, must be set to ”SPLITTING”.
• minWght: Specify the minimum particle weight to apply splitting. Particles with
lesser weight than the specified will not be split.
• maxWght: Specify the maximum particle weight to apply splitting. Particles with
greater weight than the specified will not be split.
• materials/mat-name: Subsection to specify splitting parameters for materials. No-

tice that mat-name is only used as identifier in the VR instance, and will not be
identified with the name used in the geometry configuration. Instead, the material is
specified by the integer index mat-index. Finally, the number of cloned particles in
this material is specified by the splitting parameter. This parameter can be repeated
for different material indexes.
58
• bodies/body-alias/splitting: There, body-alias must identify a valid body in the
configured geometry. The specified value of splitting will be used in this body. Notice
that bodies configuration overwrite materials ones. This parameter can be repeated
for different bodies.
1 VR/ g e n e r i c / vr−name/ type ”SPLITTING” ( mandatory )

2 VR/ g e n e r i c / vr−name/minWght 0 . 0 5 ( mandatory )
3 VR/ g e n e r i c / vr−name/maxWght 2 1 . 0 ( mandatory )
4
5 VR/ g e n e r i c / vr−name/ m a t e r i a l s /mat−name/mat−i n d e x 2 ( optional )
6 VR/ g e n e r i c / vr−name/ m a t e r i a l s /mat−name/ s p l i t t i n g 20 ( optional )
7
8 VR/ g e n e r i c /name/ b o d i e s /body−a l i a s / s p l i t t i n g 20 ( optional )
Code 63: Splitting configuration for bodies and materials
Notice that the splitting is only applied when a particle enter to the material/body
after crossing an interface. Therefore, is not applied to secondary particles generated inside
the material and is not triggered in bodies if the geometry has not an interface in their
boundaries. To force a interface, the user can create a detector or use different materials.
5.5.3.2 Russian roulette

Russian roulette technique kills the particles with a probability specified in the configuration
(prob). If the particle survive, its weight is multiplied by a factor 1/prob. All the parameters
of the Russian roulette technique are equivalent to the splitting class parameters (section
5.5.3.1). The only difference is that the splitting parameter is substituted by the prob
parameter, which specify the particle survival probability. The parameters are summarised
in the code 64. In addition, the type parameter must be set to ”RUSSIAN ROULETTE”
instead of ”SPLITTING”. An example of configuration can be found in the example 8-
fake-chamber.
1 VR/ g e n e r i c / vr−name/ type ”RUSSIAN ROULETTE” ( mandatory )
2 VR/ g e n e r i c / vr−name/minWght 0 . 0 5 ( mandatory )
3 VR/ g e n e r i c / vr−name/maxWght 2 1 . 0 ( mandatory )
4
5 VR/ g e n e r i c / vr−name/ m a t e r i a l s /mat−name/mat−i n d e x 2 ( optional )
6 VR/ g e n e r i c / vr−name/ m a t e r i a l s /mat−name/ prob 20 ( optional )
7
8 VR/ g e n e r i c /name/ b o d i e s /body−a l i a s / prob 20 ( optional )
Code 64: Russian roulette configuration for bodies and materials
Like in the splitting case, Russian roulette only triggers when a particle cross an interface.
5.6 Simulation parameters

Simulation parameters are main specific, unlike source, tally, geometry or material config-
urations. This section will explain the available parameters for the “pen main” program.
All parameters follows the pattern in the code 65.
1 s i m u l a t i o n / parameter / path v a l u e
Code 65: Simulation parameters configuration pattern
59
5.6.1 Dump
PenRed main program provides the capability to dump the current state of the whole sim-
ulation. This dump can be used to resume a crashed simulation, store the final results in
binary format, or add the results of simulations with the same configuration. To config-
ure this feature, the user can use a set of configuration parameters, which are explained
following.
• dump-interval: Specify the time, in seconds, between successive dumps
• dump2read: Expects a string with the name of a dump file to be resumed. This
file will be read before the simulation beginning to continue a previous simulation.
Notice that, if multiple threads are used, the simulation must be resumed with the
same number of threads as the original one. Each thread will try to read the specified
file name with a prefix thN, where N specify the thread number. For example, if the
filename is “dump.dat”, the file corresponding to the thread number 2 must be named
“th2dump.dat”.
• dump2write: Specify the file name used to save the dumps. Each thread will append
the thN prefix to the filename automatically, where N specify the thread number. If
is not specified, dump files will be named with the default value dump.dat.
• dump2ascii: Is a bool value that must be used with the dump2read parameter. If
enabled, the simulation will not be resumed. Instead, the program will load the state
stored in the specified dump file and extract the tally contents using the usual ASCII
data reports. Is disabled by default.
• finalDump: This bool value can be used to force a dump in each thread at the end
of the simulation. Is disabled by default.
• ascii-results: A bool value that enables or disables the result reports in ASCII for-
mat. If disabled, the result reports will be write in a dump file named results.dump.
In addition, no partial results will be printed during the simulation. Is enabled by
default.
• partial-results: If ascii-results is enabled, this bool value can enable or disable the
ASCII printing of partial results. Is disabled by default.
An example of dump configuration can be found in the code 66, where the simulation
will resume the stored state at dump file dump.dat and store the new generated dumps to
dump2.dat. New dumps will be generated every 3600 s and the final dump is disabled.
1 s i m u l a t i o n /dump−i n t e r v a l 3600
2 s i m u l a t i o n / dump2read ”dump . dat ”
3 s i m u l a t i o n / dump2write ”dump2 . dat ”
4 s i m u l a t i o n / finalDump f a l s e
5 s i m u l a t i o n / dump2ascii f a l s e
6 s i m u l a t i o n / a s c i i −r e s u l t s t r u e
Code 66: Dump configuration parameters
5.6.1.1 Adding dumps

Another feature related with dumped simulations is the possibility to add dump files. This
can be done via the command line with the option --addDumps. To use this option, the
60
user must provide the usual configuration file of the simulation, and all the dump files to
be added as follows,
./pen main config.in --addDumps dumpFile1 dumpFile2 dumpFile3
where can be specified as many files as required. Notice that no simulation will be carried
on when this option is specified in the command line. Also, all added dump files must
have been generated using the same configuration. As result, a new dump file named
mergedDump.dump will be generated with the added information from all specified files.
Furthermore, if ascii-results is enabled, the corresponding ASCII reports will be saved
too.
5.6.2 Threading
Another type of simulation parameters are those that control the multi-threading capabili-
ties. These parameters are described following.
• nthreads: Expects an integer value that specify the number of threads to be used. If
this parameter is set to 0 or less, the number of threads will be calculated automatically
according to the value returned by the function,
std::thread::hardware concurrency()
By default a single thread is used. In MPI executions, this value is used to specify
the number of threads in each MPI rank.
• thread-affinity: This parameter expects a boolean value to enable or disable CPU

affinity. Actually, this feature can be used only if threads are implemented via pthreads
package, i.e., in most Unix environments. Is disabled by default.
• simulation/rank/N/threads: This parameter specify the number of threads to be

used in the MPI rank number N , which value must be set to the desired rank. Notice
that this one overwrites the nthreads parameter. An example is shown in the code
68.
The number of histories to simulate on each source will be distributed among all specified
threads.
1 simulation / threads 2
2 s i m u l a t i o n / thread −a f f i n i t y t r u e
Code 67: Number of threads specification
Notice that MPI can be combined with multi-threading. However, the number of MPI
processes is not specified in the configuration file. Instead, this is specified via the mpirun
parameters (see section 2). So, when both kinds of parallelism are combined, the number
of threads spawned in each MPI rank is calculated according to the parameters specified in
the configuration file. This approach “suggests” to the user to create a single MPI process
for each node in a distributed memory infrastructure and use threads instead of more MPI
processes. With this method, each node will use less memory because data bases will be
shared by all threads in the same node. Furthermore, the memory access will be more
efficient due to the memory sharing between threads.
In addition, it is possible to specify a different number of threads for each MPI process.
For example, the configuration in the code 68 specify two threads for each MPI rank except
for the ranks 1 and 2, which will use 4 and 8 threads respectively.
1 simulation / threads 2
2 s i m u l a t i o n / rank /1/ t h r e a d s 4
61
3 s i m u l a t i o n / rank /2/ t h r e a d s 8
Code 68: Number of threads specification
5.6.3 Seeds
The user can specify the initial random generator seeds using seed1 and seed2 parameters.
Another option consists of selecting a seed pair provided by rand0 [13] function via the
seedPair parameter. Notice that on multi-threading and/or MPI simulations, only the
parameter seedPair can be used to set initial seeds. This restriction is necessary to ensure
that each random number chain is truly independent.
1 simulation / seed1 1
2 simulation / seed2 1
3 s i m u l a t i o n / s e e d P a i r 12
Code 69: Initial seeds
There are 1001 possible seed pairs to be used.
5.6.4 Simulation time

It is possible to limit the maximum allowed simulation time. If this limit is reached, PenRed
will produce the corresponding dump files with the simulation state and finish its execution.
To specify that time, only one parameter is required,
• max-time: Maximum simulation time in seconds.
For example, the Code 70 shows a configuration line specifying a maximum simulation
time of 5 minutes.
1 s i m u l a t i o n /max−time 300
Code 70: Maximum simulation time
5.7 Image output

The provided main program allows to export some of the simulation outputs as images.
Which outputs can be exported as images depends on each component implementation, for
example, many tallies uses this capability. To enable the image exporter, the field images
must be included in the simulation section followed by the format to enable/disable, as is
shown in the code 71. Actually, the two available image formats are MHD [14], which is
supported by many viewers and can be read with the ITK library, and GNU, which consists
of a format ready to be plotted as a matrix with the Gnuplot [15] tool. Each format can
be enabled or disabled independently of the others. For instance, the code 71 shows how to
enable both formats
1 s i m u l a t i o n / images /mhd t r u e
2 s i m u l a t i o n / images /gnu t r u e
Code 71: Image export
62
5.8 Load balance parameters
As simulation parameters, load balance parameters are main dependent. This optional
feature can be enabled during the ccmake configuration with the option WITH LB. Actually,
the only mandatory parameter to configure the load balance system is balance-interval (code
72). This one specify the minimum balance time interval in seconds. Specifying this simple
parameter, PenRed simulation threads and MPI processes, if enabled, will be balanced
automatically.
In addition, PenRed simulations can be balanced using a centralised server to provide a
method to balance simulations across the internet. To start a balance server, the PenRed
package provides a balance server example code in src/utilities/LB/LBserver.cpp. In
addition, in the configuration, the user must specify the balance server hostname or IP as
string (loadBalance/host) and port (loadBalance/port). Also, a worker number identi-
fication must be specified (loadBalance/worker).
Finally, if the SSL support has been enabled at the ccmake configuration with the
parameter WITH SSL, the communications between workers and the balance server will be
secured with the SSL protocol. This feature requires a set of certificates listed below.
• CA-cert: Certification chain file of the trusted CA.
• cert-file: Filename of the worker certificate file.
• key-file: Filename of the worker key file.
• key-password: Worker key password.
• hostname: Expected server certificate hostname.
1 l o a d B a l a n c e / b a l a n c e −i n t e r v a l 500 ( mandatory )
2 l o a d B a l a n c e / h o s t ” s e r v e r −hostname ” ( optional )
3 l o a d B a l a n c e / p o r t 5555 ( mandatory i f enabled ” host ” )
4 l o a d B a l a n c e / worker 0 ( mandatory i f enabled ” host ” )
5 l o a d B a l a n c e /CA−c e r t ( optional )
6 loadBalance / cert −f i l e ( mandatory i f e n a b l e d ”CA−c e r t ” )
7 l o a d B a l a n c e / key− f i l e ( mandatory i f e n a b l e d ”CA−c e r t ” )
8 l o a d B a l a n c e / key−password ( optional )
9 l o a d B a l a n c e / hostname ( optional )
Code 72: Load balance parameters
6 Examples
PenRed has been tested against the original PENELOPE FORTRAN code, on which it is
based, using, among other methods, the provided PENELOPE examples. Some parts of
the configuration files of these examples have been shown in previous sections to exemplify
the different samplers options, source, materials, geometry and tally definitions. At this
section, all of the examples included in the distributed package are briefly described.
To execute the examples, geometry file, configuration file and material files are required.
They must be at the same directory. Moreover, the executable file created after the program
compilation is needed. As we have explained at section 2, the executable is compiled at
src/compiled/mains/pen main. To run the simulation, the executable must be copied at
the same folder where the example will be run with the other required files. After that,
user can start the execution as follows,
63
./pen main path/to/configuration/file
6.1 1-disc
This example presents a point source of electrons and a homogeneous disc phantom of
Cu. The source is a monoenergetic beam with energy of 40KeV and it is located at
(x, y, z) = (0, 0, −0.0001) cm. The phantom size is a radius of 0.01 cm at plane XY and
height of 0.005 cm at z axis with the base at z = 0 cm.
6.1.1 1-disc-no-vr
This is the first version of the disc example, without variance reduction techniques. The
required material files to execute this example is only Cu.mat file, and the configuration file
is named disc.in. The geometry is read from the geometry file named disc.geo. The output
of this example execution are the cylindrical and spatial dose distribution, the emerging
particles distribution, the impact detector tallies for fluence and energy spectrum and the
material energy deposition information.
6.1.2 1-disc-vr
The second version of the disc example includes variance reduction techniques. The material
and geometry file are the same than the first version and, although the configuration file
has the same name, there are some differences between these two versions. This second one
is an example of the interaction forcing, x-ray and bremsstrahlung splitting capabilities of
the PenRed code. At the configuration file is specified which is the body that suffers the
variance reduction techniques and the kind of particle and interaction to force, electrons
in this case. The output of this example execution is the same than at the first version.
Notice that, when variance reduction techniques are used, the number of histories of the
simulation is reduced because of the splitting applied to them.
6.2 2-plane
This example is a semi-infinite water plane with a spherical detector inside. The source is a
photon monoenergetic beam of 30 MeV. The detector located in the water plane is defined
as an impact detector for fluence measurements. No VR is applied in the plane example.
The single material required to execute this example is the Water.mat file. The geometry
information is read from the plane.geo file. The output of this example are the emerging
particles distribution, cylindrical and spatial dose distribution, the impact detector tallies
corresponding to fluence and energy spectrum measures and output files for material and
body energy deposition.
6.3 3-detector
The geometry of this example consists of a NaI cylindrical detector with 5.08 cm of diameter
and 5.08 cm height, with 1.27 cm Fe backing. A point-like Co-60 gamma-ray source emits
a photon pencil beam in the −Z direction with equiprobable energies 1.17 and 1.33 MeV.
The photons impinge on the NaI crystal from above. No VR is applied in this example.
Materials required to execute this example are NaI.mat and Fe.mat files and the geometry
is defined in the detector.geo file. In this case, the output files correspond to the material
and energy deposition and to the emerging particles distribution.
64
6.4 4-x-ray-tube
The fourth example corresponds to a simple x-ray generator. It consists of a wolframium
anode, a filter of aluminium and a silicon detector. The source emits a monoenergetic
electron beam of 150 KeV directed to the anode to produce bremsstrahlung photon beam.
For this purpose VR techniques are applied to produce splitting in this body. The filter is
added to increase the average energy of the resulting beam, and the detector is defined to
measure fluence, energy spectrum, and particle age. Materials required for this example are
W.mat, Al.mat, Si.mat. The geometry information is in the tube.geo file. The output files
are the emerging particles distribution, body and material energy deposition and detector
measurements of spectrum, fluence and particle age.
6.5 5-accelerator
The accelerator example simulates a simple electron accelerator and calculates the dose
distribution in a water phantom in two steps described following.
6.5.1 5-accelerator-1
In the first step, a phase space file (PSF) is generated at a plane beyond the bottom of the
accelerator head, using a planar impact detector. The geometry description of the accel.geo
file consists of a tungsten target in which impinge an electron beam of 6 MeV, a collimator
of the same material and a water phantom. The whole geometry is defined inside an air
enclosure. Materials needed to run this simulation are W.mat, H2O.mat and Air.mat. The
output files are the body and material energy deposition, the emerging particles distribution
and the impact detector spectrum. Moreover, a psf-merged.dat file is generated with the
PSF information.
In the second step, the initial particle states from that PSF is read and the dose distribution
in the water phantom is obtained. The same materials and geometry file are used in this
second step. In this case the output files are the emerging particle distribution, body and
material energy deposition and the spatial dose distribution in the water phantom.
This example has been created to test the phase space file translation and rotation ca-
pabilities. Two variants of this example are created, 5-accelerator-orig and 5-accelerator-
rot trans. The geometry used, accel.geo, consists of the same geometry of the previous
example 5-accelerator-2 but with some modifications. In this case the water phantom
is composed by different water slices with 2 cm of thickness instead of a solid water cube.
In the first variation of this example 5-accelerator-orig, the phase space file and the
geometry of the problem have not been rotated nor translated. An EDEP BODY tally type
has been set to obtain the deposited energy in each body of the geometry, including the
different water slices. Moreover, three impact detector have been created with the tally
type IMPACT DET to obtain fluence and spectrum.
In the second variation, 5-accelerator-rot trans, the same geometry is used, but a
rotation and translation is applied.
• Rotation:
– omega = 20 degrees
65
– theta = 45 degrees
– phi = 20 degrees
• Translation:
– y shift = 10 cm
The same rotation and translation have been applied to the phase space file in the
config.in file. The same EDEP BODY and IMPACT DET tallies used in the first variation
have been set
6.6 6-polarisation
This example reproduces the Namito et al.’s (1993) scattering experiment with polarised
photons. The source of this example is a monoenergetic polarised photon beam of 40 KeV,
defined using the stokes parameters. Interaction forcing is used in this example. The
geometry file corresponds to gpol.geo and the material files are Cu.mat and Vacuum.mat.
The output files of the execution of this example are the emerging particle distribution, the
material energy deposition and the energy spectrum.
6.7 7-aba
This example consist of a 60 Co gamma rays source on a three layer cylinder phantom
of water-Al-water. The source has equiprobable energies of 1.17 and 1.33 MeV. No VR
is applied in this example. The geometry description of the cylinders is defined in the
3discs.geo, and the material files needed are water.mat and Al.mat. The output files of
this example corresponds to the emerging particles distribution, the impact detector energy
deposition, the spatial dose distribution and the material and body energy deposition.
6.8 8-fake-chamber
This example describes an ionization chamber geometry inside a water phantom of 30 ×
30 × 30 cm3 . The source is a monoenergetic photon beam of 4 MeV. The source-surface
distance between the source and the surface of the water phantom is 90 cm. The ionization
chamber is located 10 cm from the water surface. The geometry file of this example is the
chamber.geo and the materials used for its simulation are air.mat, pmma.mat, water.mat.
The same files are used for both versions of this example, without and with VR respectively.
6.8.1 8-fake-chamber-novr
In the first version of this example no VR is applied. The output files are the spatial dose
distribution and the material energy deposition.
6.8.2 8-fake-chamber-vr
In the second version of this example VR is applied. Splitting and russian roulette are used.
The output files are the same that in the first version, the spatial dose distribution and the
material energy deposition.
66
7 Utilities
This section describes the utilities provided with the PenRed package that can be useful for
the user. The code of each utility described in this section can be found in the corresponding
folder in the directory
src/utilities/
7.1 Blender Geometry Plugin

This utility consists of a python plugin to be used in the Blender3 software. The plugin
takes advantage of the Blender UI and tools for 3D design to facilitate the construction of
both Quadric (Section 5.3.2) and Triangular Mesh Surface (Section 5.3.3) based geometries.
The plugin can be found in the folder,
src/utilities/Blender
and requires, at least, the blender version 3.3.0. When a geometry is constructed in Blender
to be exported to PenRed, the default Blender units are already considered as centimeters.
Therefore, no further transformations are required. The specific considerations of each
geometry type will be discussed in next sections. However, this manual does not contains
an introduction to Blender usage, since it is already well documented and the user can
found many tutorials in the internet.
Therefore, to use this plugin, we assume that the user has a basic knowledge about how
to use Blender. The most important features to know are, moving in the 3D viewport,
create objects and edit their properties, set relations between objects, edit meshes and
install addons.
Indeed, the plugin uses blender’s parentage mechanics to determine which
object is included in another. Therefore, the user must construct the objects
tree according to the geometry.
Regardless the geometry type to be constructed, the PenRed exporter can be found in
the File menu, as is shown in the Figure 12.
On the save window, we can found a switch menu to select the geometry format to
export, and a integer input box to specify the number of decimals to round the exported
vaules (Figure 13).
3
https://www.blender.org/
67
Figure 12: PenRed geometry export in Blender.
68
Figure 13: PenRed geometry export window in Blender.

Once all parameters and the filename has been specified, the user can export the geom-
etry with the export button.
7.1.1 Quadric Geometries

This plugin is not capable to transform a generic mesh surface to quadric geometries.
Instead, it provides a set of predefined objects to construct the geometry. These objects
are listed in a submenu named Quaric in the Add menu, as is shown in the Figure 14.
Figure 14: Predefined objects for quadric geometries
Notice that only the listed objects in the Quadric submenu can be exported as Quadric
surfaces. Other type of objects will be ignored by the quadrics exporter.
All predefined objects have some common parameters to be specified. These can be
defined in the Quadric properties submenu, which is inside the Object properties menu
(Figure 15). The parameters are,
• Material: Specify the material number to be assigned to the object.
• Module: If enabled (disabled), this object will be defined as a module (body).
The only objects that use some extra parameters are the CONE and the CONE SHELL.
For both, the top (r2) and bottom (r1) radius can be specified. Once introduced, the user
must apply the changes using the remesh button or recover the original size with the reset
button (Figure 16).
69
Figure 15: Common quadric parameters.
Figure 16: Cone parameters.
70
Notice that, when exported, the body or module is located according to the object
origin. Therefore, the user should not change the origin relative position to the object
mesh. Nevertheless, all objects can be scaled, moved and rotated according to user needs.
7.1.2 Triangular Mesh Surfaces

Unlike the quadric geometry exporter (Section 7.1.1), the triangular mesh surfaces exporter
can convert any mesh constructed with blender to the PenRed format. Therefore, it is
not necessary to use the defined quadric objects. Moreover, we can use Blender to import
meshes constructed with other programs to export them to the PenRed format.
The only parameter required to be specified for each body is its material, which can be
found in the Quadric properties submenu, inside the Object properties menu (Figure 15).
Notice that the module option is ignored for this geometry type.
7.2 Mutren
The Mutren utility is based on the original mutren.f code of the PENELOPE package.
This one, calculates the µen coefficients of the specified material for the specified energies.
It consists of a command line program which takes the following parameters as input,
./mutren material-file energy-spectrum-file tolerance sim-time
Each parameter is described following,
• material-file: Path to the input material file.
• energy-spectrum-file: Path to the energy spectrum file. The format of this file
consists of rows where each one contains a single energy in eV.
• tolerance: Relative error to stop the simulation, usually set to 0.1%
• sim-time: Allowed time to simulate each provided energy in seconds.
The program will calculate the coefficients for each provided energy and store them in
a file named mutren.dat. Notice that the simulation of each energy point will finish if the
objective tolerance has been achieved or if the simulation time reaches the specified limit
(sim-time).
7.3 iaeaPSF
PenRed writes and reads the PSF in its own binary format. However, the International
Atomic Energy Agency (IAEA) provides a standard PSF format. To be able to run IAEA
PSF with PenRed, in the utilities folder, user can found iaeaPSF folder which includes the
IAEA package of routines needed to obtain iaea2PenRed and penRed2iaea conversion tools.
These tools can be found at
src/compiled/iaeaPSF/
The compilation can be set ON or OFF in the ‘compile.sh’ file. On the one hand,
the iaea2PenRed program allows to convert PSF in IAEA format to PSF in internal binary
PenRed format. To do it, user needs both header and phase space file of the IAEA standard
format, “.IAEAheader” and “.IAEAphsp” respectively. To execute this tool the command
line needed is
71
./iaea2PenRed input filename (without extension) and output file name
On the other hand, the penRed2iaea program converts a PenRed PSF in to IAEA PSF.
In this case the comand line to execute it is
./penRed2iaea input filename and output file name (without extension)
providing two new files with extensions “.IAEAheader” and “.IAEAphsp”, respectively.
7.4 geo2voxel
This utility converts any geometry type in a voxelized one. As program arguments, the
geo2voxel requires a configuration file which format is the same as pen main, i.e. the
format described in the section 3. This configuration file, must include all the configuration
parameters to load a geometry of any type, following the descriptions provided in the section
5.3, and the parameters listed below,
• voxelized/nx: Number of voxels in the X axis.
• voxelized/ny: Number of voxels in the Y axis.
• voxelized/nz: Number of voxels in the Z axis.
• voxelized/dx: Voxel size in the X axis, in cm.
• voxelized/dy: Voxel size in the Y axis, in cm.
• voxelized/dz: Voxel size in the Z axis, in cm.
• voxelized/ox: Voxelized geometry origin in the X axis, in cm.
• voxelized/oy: Voxelized geometry origin in the Y axis, in cm.
• voxelized/oz: Voxelized geometry origin in the Z axis, in cm.
• voxelized/granularity: Granularity used to determine the material and density of

each voxel.
• materials/material-name/ID: Identification number of the material. There the

material-name must be specified by the user and it is used only to distinguish different
materials in the configuration file, i.e. has no influence in the converted geometry. This
parameter must be repeated for different materials.
• materials/material-name/density: Density value of each material of the geome-

try, in g/cm3 . This parameter must be repeated for different materials. This density
is assigned to the material number with the same material-name.
where granularity and the number of bins are expected to be integers, and the remaining
parameters doubles. The origin of the voxelized geometry (ox, oy, oz) is interpreted as
the position of the left bottom corner of the lower Z voxelized geometry plane i.e., is not
considered as the center of the first voxel of the mesh. Then, the granularity specify how
many points per axis are generated inside each voxel to determine the material and density
of each one. The density is obtained from the mean value of all generated points, while the
material assignation will be done according to the material index with more points inside
the voxel.
72
An example of configuration to generate a voxelized geometry from a quadric geometry
file is shown in the code 73, where 43 points are generated in each voxel to determine the
material and density and the center of the voxelized mesh has been set to the (0, 0, 0) of
the quadric geometry.
2 geometry / input − f i l e ” d i s c . geo ”
4
5 v o x e l i z e d /nx 300
6 v o x e l i z e d /ny 300
7 v o x e l i z e d / nz 120
8
9 v o x e l i z e d /dx 0 . 1
10 v o x e l i z e d /dy 0 . 1
11 v o x e l i z e d / dz 0 . 2
12
13 v o x e l i z e d / ox −15.0
14 v o x e l i z e d / oy −15.0
15 v o x e l i z e d / oz −12.0
16
17 voxelized / granularity 4
18
19 m a t e r i a l s / water /ID 1
20 m a t e r i a l s / water / d e n s i t y 0 . 9 9 8 2 1
Code 73: Complete geo2voxel configuration example to convert a quadric geometry.
7.5 geo2mesh
The ’geo2mesh’ utility converts any geometry file compatible with PenRed into a simplified
Wavefront file that can be used with the PenRed-GUI program. To accomplish this, the
program creates a regular voxelized mesh with material information, allowing for the cre-
ation of the final triangular surface boundary. To use this utility, the user needs an input
configuration file with the following parameters:
• geometry: This section contains information to configure the geometry, and its con-
tents vary depending on the geometry type. It is structured as the used for a simula-
tion.
• nx: The number of voxels used in the X-axis.
• ny: The number of voxels used in the Y-axis.
• nz: The number of voxels used in the Z-axis.
• dx: The voxel size in the X-direction, measured in centimeters.
• dy: The voxel size in the Y-direction, measured in centimeters.
• dz: The voxel size in the Z-direction, measured in centimeters.
• ox: The X-coordinate of the mesh origin, measured in centimeters.
• oy: The Y-coordinate of the mesh origin, measured in centimeters.
• oz: The Z-coordinate of the mesh origin, measured in centimeters.
73
• granularity: The number of points created within each voxel along each axis to assign
the material number. It is advisable to use lower values to minimize computational
costs. Typically, a value of 2 or 3 is sufficient.
• smooth/steps: The number of smoothing steps to apply to the mesh. This param-
eter is optional and is set to 50 by default.
• smooth/factor: The strength of the smoothing filter. This is also optional and is
set to 0.2 by default.
Notice that the mesh origin is located at the first corner in the direction of increasing
coordinates of the first mesh voxel. To use the configuration file, run the program as follows:
./geo2mesh config-file
the program will generate two files: one containing vertex information named ’geo.obj’ and
another with material information named ’geoMats.mtl’. The code 74 shows an example of
configuration file to convert the ’tube.geo’ geometry of the quadric example to a mesh.
1
2 #########################
3 # GEOMETRY PARAMETERS #
4 #########################
5
7 geometry / input − f i l e ” tube . geo ”
9
10 #########################
11 # GEO2MESH PARAMETERS #
12 #########################
13
14 ox −10
15 oy −10
16 oz −10
17
18 dx 0 . 1
19 dy 0 . 1
20 dz 0 . 1
21
22 nx 200
23 ny 200
24 nz 200
25
26 granularity 3
27
28 smooth / s t e p s 20
29 smooth / f a c t o r 0 . 2
Code 74: Complete geo2mesh configuration example to convert a quadric geometry.
7.6 range
The range utility prints the electron, positron and photon ranges for the specified material
and energies. The corresponding code is located in the folder penMats. The program must
be executed via the command line as follows,
74
./range material-file E1 E2 E3
where range is the executable name, material-file is the material file with the material
information, the same as the used for simulations, and the following arguments (E1, E2, E3)
are a list of energies to calculate the corresponding ranges. Notice that in the execution
example we have used 3 energies. However, any number of energies can be used.
7.7 PSF spectrum

The psf spectre utility extracts the energy spectrum distribution of the particles registered
in a PSF file, and the corresponding source code can be found in the psf/psf spectre.cpp
file. This utility is used via the command line as follows,
./psf spectre PSFfilename emin emax nbins
where psf spectre is the utility executable, PSFfilename the path to the PSF file to be pro-
cessed, emin the minimum energy, in eV, of the extracted spectrum, emax the corresponding
spectrum maximum energy and nbins the number of spectrum bins.
7.8 PSF to ASCII

The psf2ascii utility converts a binary PSF file into a ASCII file format. The source code
can be found in psf/psf2ascii.cpp and must be used via the command line as follows,
./psf2ascii inputFile outputFile
where psf2ascii is the executable, inputFile the binary PSF file path and outputFile the
filename of the generated ASCII file.
7.9 Registers
The registers folder contains a set of sources which compiled programs show all the
available types of a specific component. The shown types correspond to the ones used in
the configuration files to specify the component type parameter. All the available registers
are summarised in the Table 9. This ones are executed with no arguments via the command
line.
Executable Registered information

regGenericVR Generic VR types
regPhotonVR Specific photon VR types
regGeometries Geometry types
regSamplers Particle sampler types
regTallies Tally types
Table 9: Available register programs with the corresponding registered information.
75
A Predefined materials
ID Name ID Name ID Name

1 Hydrogen 34 Selenium 67 Holmium
2 Helium 35 Bromine 68 Erbium
3 Lithium 36 Krypton 69 Thulium
4 Beryllium 37 Rubidium 70 Ytterbium
5 Boron 38 Strontium 71 Lutetium
6 Amorphous carbon 39 Yttrium 72 Hafnium
7 Nitrogen 40 Zirconium 73 Tantalum
8 Oxygen 41 Niobium 74 Tungsten
9 Fluorine 42 Molybdenum 75 Rhenium
10 Neon 43 Technetium 76 Osmium
11 Sodium 44 Ruthenium 77 Iridium
12 Magnesium 45 Rhodium 78 Platinum
13 Aluminium 46 Palladium 79 Gold
14 Silicon 47 Silver 80 Mercury
15 Phosphorus 48 Cadmium 81 Thallium
16 Sulfur 49 Indium 82 Lead
17 Chlorine 50 Tin 83 Bismuth
18 Argon 51 Antimony 84 Polonium
19 Potassium 52 Tellurium 85 Astatine
20 Calcium 53 Iodine 86 Radon
21 Scandium 54 Xenon 87 Francium
22 Titanium 55 Cesium 88 Radium
23 Vanadium 56 Barium 89 Actinium
24 Chromium 57 Lanthanum 90 Thorium
25 Manganese 58 Cerium 91 Protactinium
26 Iron 59 Praseodymium 92 Uranium
27 Cobalt 60 Neodymium 93 Neptunium
28 Nickel 61 Promethium 94 Plutonium
29 Copper 62 Samarium 95 Americium
30 Zinc 63 Europium 96 Curium
31 Gallium 64 Gadolinium 97 Berkelium
32 Germanium 65 Terbium 98 Californium
33 Arsenic 66 Dysprosium 99 Einsteinium
Table 10: Elements predefined materials extracted from [3]. Material ID corresponds to the
element atomic number.
76
ID Name
100 Acetone
101 Acetylene
102 Adenine
103 Adipose tissue (ICRP)
104 Air, dry (near sea level)
105 Alanine
106 Aluminum oxide
107 Amber
108 Ammonia
109 Aniline
110 Anthracene
111 B-100 bone-equivalent plastic
112 Bakelite
113 Barium fluoride
114 Barium sulfate
115 Benzene
116 Beryllium oxide
117 Bismuth germanium oxide
118 Blood (ICRP)
119 Bone, compact (ICRU)
120 Bone, cortical (ICRP)
121 Boron carbide
122 Boron oxide
123 Brain (ICRP)
124 Butane
125 N-butyl alcohol
126 C-552 air-equivalent plastic
127 Cadmium telluride
128 Cadmium tungstate
129 Calcium carbonate
130 Calcium fluoride
131 Calcium oxide
132 Calcium sulfate
133 Calcium tungstate
134 Carbon dioxide
135 Carbon tetrachloride
136 Cellulose acetate, cellophane
137 Cellulose acetate butyrate
138 Cellulose nitrate
139 Ceric sulfate dosimeter solution
140 Cesium fluoride
141 Cesium iodide
142 Chlorobenzene
143 Chloroform
144 Concrete, portland
145 Cyclohexane
146 1,2-dichlorobenzene
147 Dichlorodiethyl ether
148 1,2-dichloroethane
77
149 Diethyl ether
150 N,n-dimethyl formamide
151 Dimethyl sulfoxide
152 Ethane
153 Ethyl alcohol
154 Ethyl cellulose
155 Ethylene
156 Eye lens (ICRP)
157 Ferric oxide
158 Ferroboride
159 Ferrous oxide
160 Ferrous sulfate dosimeter solution
161 Freon-12
162 Freon-12b2
163 Freon-13
164 Freon-13b1
165 Freon-13i1
166 Gadolinium oxysulfide
167 Gallium arsenide
168 Gel in photographic emulsion
169 Pyrex glass
170 Glass, lead
171 Glass, plate
172 Glucose
173 Glutamine
174 Glycerol
175 Graphite
176 Guanine
177 Gypsum, plaster of Paris
178 N-heptane
179 N-hexane
180 Kapton polyimide film
181 Lanthanum oxybromide
182 Lanthanum oxysulfide
183 Lead oxide
184 Lithium amide
185 Lithium carbonate
186 Lithium fluoride
187 Lithium hydride
188 Lithium iodide
189 Lithium oxide
190 Lithium tetraborate
191 Lung (ICRP)
192 M3 wax
193 Magnesium carbonate
194 Magnesium fluoride
195 Magnesium oxide
196 Magnesium tetraborate
197 Mercuric iodide
198 Methane
78
199 Methanol
200 Mixed wax
201 Ms20 tissue substitute
202 Muscle, skeletal (ICRP)
203 Muscle, striated (ICRU)
204 Muscle-equivalent liquid, with sucrose
205 Muscle-equivalent liquid, without sucrose
206 Naphthalene
207 Nitrobenzene
208 Nitrous oxide
209 Nylon, du Pont elvamide 8062
210 Nylon, type 6 and type 6/6
211 Nylon, type 6/10
212 Nylon, type 11 (rilsan)
213 Octane, liquid
214 Paraffin wax
215 N-pentane
216 Photographic emulsion
217 Plastic scintillator (vinyltoluene based)
218 Plutonium dioxide
219 Polyacrylonitrile
220 Polycarbonate (makrolon, lexan)
221 Polychlorostyrene
222 Polyethylene
223 Polyethylene terephthalate (mylar)
224 Polymethyl methacrilate (lucite, perspex, plexiglass)
225 Polyoxymethylene
226 Polypropylene
227 Polystyrene
228 Polytetrafluoroethylene (teflon)
229 Polytrifluorochloroethylene
230 Polyvinyl acetate
231 Polyvinyl alcohol
232 Polyvinyl butyral
233 Polyvinyl chloride
234 Polyvinylidene chloride (saran)
235 Polyvinylidene fluoride
236 Polyvinyl pyrrolidone
237 Potassium iodide
238 Potassium oxide
239 Propane
240 Propane, liquid
241 N-propyl alcohol
242 Pyridine
243 Rubber, butyl
244 Rubber, natural
245 Rubber, neoprene
246 Silicon dioxide
247 Silver bromide
248 Silver chloride
79
249 Silver halides in photographic emulsion
250 Silver iodide
251 Skin (ICRP)
252 Sodium carbonate
253 Sodium iodide
254 Sodium monoxide
255 Sodium nitrate
256 Stilbene
257 Sucrose
258 Terphenyl
259 Testes (ICRP)
260 Tetrachloroethylene
261 Thallium chloride
262 Tissue, soft (ICRP)
263 Tissue, soft (ICRU four-component)
264 Tissue-equivalent gas (methane based)
265 Tissue-equivalent gas (propane based)
266 Tissue-equivalent plastic (A-150)
267 Titanium dioxide
268 Toluene
269 Trichloroethylene
270 Triethyl phosphate
271 Tungsten hexafluoride
272 Uranium dicarbide
273 Uranium monocarbide
274 Uranium oxide
275 Urea
276 Valine
277 Viton fluoroelastomer
278 Water, liquid
279 Water vapour
280 Xylene
Table 11: Predefined compounds extracted from [3].
References
[1] V. Giménez-Alventosa, V. Giménez Gómez, S. Oliver, Penred: An extensible and paral-
lel monte-carlo framework for radiation transport based on penelope, Computer Physics
Communications 267 (2021) 108065. doi:https://doi.org/10.1016/j.cpc.2021.
108065.
URL https://www.sciencedirect.com/science/article/pii/S0010465521001776
[2] Salvat F., Penelope. a code system for monte carlo simulation of electron and photon
transport, Issy-Les-Moulineaux: OECD Nuclear Energy Agengy (2014).
[3] F. Salvat, penelope-2018: A code System for Monte Carlo Simulation of Electron
and Photon Transport, OECD/NEA Data Bank, Issy-les-Moulineaux, France, 2019,
available from http://www.nea.fr/lists/penelope.html.
[4] Dcmtk, https://github.com/DCMTK/dcmtk, accessed: 2019-09-28.
80
[5] R. L. Graham, T. S. Woodall, J. M. Squyres, Open mpi: A flexible high performance
mpi, in: R. Wyrzykowski, J. Dongarra, N. Meyer, J. Waśniewski (Eds.), Parallel Pro-
cessing and Applied Mathematics, Springer Berlin Heidelberg, Berlin, Heidelberg, 2006,
pp. 228–239.
[6] W. Gropp, Mpich2: A new start for mpi implementations, in: Proceedings of the 9th
European PVM/MPI Users’ Group Meeting on Recent Advances in Parallel Virtual
Machine and Message Passing Interface, Springer-Verlag, Berlin, Heidelberg, 2002, p. 7.
[7] J. Sempau, A. Badal and L. Brualla, A PENELOPE-based system for the automated
Monte Carlo simulation of clinacs and voxelized geometries–application to far-from-
axis fields, Med. Phys. 38 (2011) 5887–5895.
URL http://dx.doi.org/10.1118/1.3643029
[8] J. Sempau, Penelope/peneasy user manual, Tech. rep., Version 2019-01-01.
[9] E. Garcı́a-Toraño, V. Peyres, F. Salvat, Pennuc: Monte carlo simulation of the decay
of radionuclides, Computer Physics Communications 245 (2019) 106849. doi:https:
//doi.org/10.1016/j.cpc.2019.08.002.
URL https://www.sciencedirect.com/science/article/pii/S0010465519302267
[10] V. Giacometti, S. Guatelli, M. Bazalova-Carter, A. Rosenfeld, R. Schulte, Development

of a high resolution voxelised head phantom for medical physics applications, Physica
Medica 33 (2017) 182 – 188. doi:https://doi.org/10.1016/j.ejmp.2017.01.007.
URL http://www.sciencedirect.com/science/article/pii/S1120179717300078
[11] J. F. Williamson, Monte carlo evaluation of kerma at a point for photon transport prob-
lems, Medical Physics 14 (4) (1987) 567–576. arXiv:https://aapm.onlinelibrary.
wiley.com/doi/pdf/10.1118/1.596069, doi:10.1118/1.596069.
URL https://aapm.onlinelibrary.wiley.com/doi/abs/10.1118/1.596069
[12] N. Ravinder et al, Dosimetry of interstitial brachytherapy sources: recommendations

of the AAPM radiation therapy committee task group no 43, Med. Phys. 22 (1995)
209–34. doi:10.1118/1.597458.
[13] A. Badal, J. Sempau, A package of linux scripts for the parallelization of monte carlo
simulations, Computer Physics Communications 175 (6) (2006) 440 – 450. doi:https:
//doi.org/10.1016/j.cpc.2006.05.009.
URL http://www.sciencedirect.com/science/article/pii/S001046550600230X
[14] Mhd/raw image format, https://itk.org/Wiki/ITK/MetaIO/Documentation, ac-

cessed: 2022-07-15.
[15] Gnuplot, http://www.gnuplot.info/, accessed: 2022-07-15.
81

Pen Redguide 1

Uploaded by

Copyright:

Available Formats

Pen Redguide 1

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Pen Redguide 1

Uploaded by

Copyright:

Available Formats

PenRed: User Manual

V. Giménez-Alventosa1 , V. Giménez Gómez2 , and S. Oliver3

September 15, 2023

1.1 What is PenRed?

1.2 Document structure

2 Installation and execution 5

3 Internal data format 11

4 Constants, parameters and definitions 12

2.1 Linux instalation

git clone https://github.com/PenRed/PenRed.git

• DICOMs: If it is enabled, PenRed capabilities to read and simulate DICOM images

• Multi-threading: This option enables multi-threading capabilities. PenRed imple-

sudo dnf install dcmtk dcmtk-devel

and the following to install its dependencies,

sudo dnf install libjpeg libjpeg-devel libxml2 libxml2-devel openssl openssl-devel

make -jN (with N the number of processes)

cmake -DWITH DICOM="ON" -DWITH MULTI THREADING="ON"

2.2 Windows instalation

Figure 1: Clone a repository in MSVS

Figure 3: Manage MSVS configurations

Figure 5: Select configuration in MSVS

Finally, build and install PenRed (Figure 7).

Figure 7: Build and install PenRed in MSVS

Figure 8: PenRed compiled programs

./pen main path/to/configuration/file

mpirun -np Nprocesses ./pen main path/to/configuration/file

2.4 Optional features

• BUILD UTILITIES: Enables or disable the compilation of utilities, such as geo2vox,

• WITH MULTI THREADING: Handles multithreading capabilities.

• WITH MPI: Handles MPI capabilities. Require an MPI library installed.

• WITH DICOM: Handles DICOM capabilities. Requires the dcmtk library.

• BUILD TESTS: Enables or disable the compilation of test codes.

• DEVELOPMENT WARNINGS: Enables or disables development warning flags.

< std :: string|pen parserArray >

4 Constants, parameters and definitions

4.1 Important definitions

• Primary particle: Particle produced directly by a source and not as a consequence

• Secondary particle: Particle produced by some interaction of other particle.

• Global simulation: Consists of all source simulations.

Code 2: Source configuration parameters

– 0: Any message should be printed.

ILB[3] = Z × 106 + IS1 × 104 + IS2 × 100 + IS3 (1)

Table 1: Description of the ILB components

Table 2: PenRed internal units.

4.3 Particle indexes

particle name Enumeration identifier Numerical index

Table 3: Particle indexes and names.

Interaction Enumeration identifier Numerical index

Table 4: Electron interaction indexes.

Interaction Enumeration identifier Numerical index

Table 5: Photon interaction indexes.

Interaction Enumeration identifier Numerical index

Table 6: Positron interaction indexes.

4.5 Atomic electron shells

Table 7: Atomic electron shells indexes.

g++ -o createMat material.cpp

5.1.1.1 Absorption energy

materials/material-name /eabs/particle-name value

Here, material-name represents the user-defined name of the material, particle-name