Introduction

All C++ applications distributed with EGSnrc use the same syntax for inputting information regarding geometry, source, run control and Monte Carlo transport parameters. Only the input blocks for scoring and variance reduction techniques vary between applications.

Tip: Comments are done with '#' hashtags! You can comment out an entire input block by just putting a '#' in front of the :start tag.

Tip 2: All distances are in units of cm, and energies in MeV.

Geometry

For full description of the geometry input, see the geometry module .

Most users spend the bulk of their effort defining geometries in input files. The physical parameters of a given experiment can be reproduced in a way that the simulation can model. A wide range of geometry libraries are available, from basic shapes to composite geometries, voxelized phantoms and repeating structures.

In an input file, the user must define a single geometry definition input block. Within this block, many geometries may be defined, between :start geometry: and :stop geometry: tags. To determine what should go inside a geometry definition to create a particular shape, refer to the online documentation, where there is a list of the available geometry libraries. Finally, at the end of the geometry definition, the user must specify the geometry in which the simulation will take place (yes, you can define geometries which are not used!). This is done using the input parameter simulation geometry, as show in the example below. The simulation geometry refers to the name of one geometry that has been defined, but that may be a composite of many other geometries (of particular interest may be EGS_CDGeometry and EGS_EnvelopeGeometry).

:start geometry definition:
    :start geometry:
       definition of a geometry
    :stop geometry:
    :start geometry:
       definition of another geometry
    :stop geometry:
    :start geometry:
       perhaps combine the above geometries into one
       name = my_geometry
    :stop geometry:

    simulation geometry = my_geometry

:stop geometry definition:

Here is an example, which was created using the EGS_Box documentation. Notice that the box was defined as pure water using a media input block. The actual material definition will be done for this example using pegsless mode, described in the next section. All distances are in units of cm.

:start geometry definition:
    :start geometry:
        name        = my_box
        library     = egs_box
        box size    = 1 2 3
        :start media input:
            media = water
        :stop media input:
    :stop geometry:

    simulation geometry = my_box

:stop geometry definition:

Remember to view your geometry using the egs_view GUI! This viewer is essential for many situations where you need to know the region numbers within your geometry. For more description, see the geometry module .

Media definitions

There are two ways to define media in EGSnrc, either with or without PEGS4 data files. If you are not dependent on old PEGS4 data, we recommend going with pegsless mode for improved versatility (you can now change AE in the input file!).

Pegsless mode

For pegsless mode, the user needs to define media within the input file! However, this can be done very simply by indicating the density correction file to use. This is done in the media definition input block. All of the density correction files distributed with EGSnrc can be found in $HEN_HOUSE/pegs4/density_corrections. Pegsless mode is described in more detail in PIRS-702.

:start media definition:

    ae  = lowest  energy for electron production (kinetic+0.511)
    ap  = lowest  energy for photon production   (kinetic)
    ue  = maximum energy for electrons (kinetic+0.511)
    up  = maximum energy for photons   (kinetic)

    :start myMedia:
        density correction file    = nameOfDensityCorrectionFile
    :stop myMedia:

:stop media definition:

For example, we can define a material named water by referencing the density correction file water_liquid. Note that you could change the name water to be any name you like, as long as it is referenced by the same name elsewhere in the input file (e.g. in the geometry).

:start media definition:

    # Threshold energies
    ae  = 0.521
    ap  = 0.01
    ue  = 50.511
    up  = 50

    :start water:
        density correction file    = water_liquid
    :stop water:

:stop media definition:

When using pegsless mode, an EGSnrc application can be launched without the -p input argument. For example:

myApp -i myInput

PEGS4 file mode

Historically, material data was specified within a PEG4 data file. Several of these are distributed with EGSnrc and contain a variety of materials, found in $HEN_HOUSE/pegs4/data. To use a PEGS4 data file, specify the name of the file as an argument after -p when launching the application:

myApp -i myInput -p myPegsFile

For example, if we use H2O521ICRU as a medium in the input file, then we must use the 521icru.pegs4dat data file. Note that the media in your input file must referenced by the same name as what is found in the PEGS4 data file.

myApp -i myInput -p 521icru

Particle source

For full description of the source input, see the particle sources module .

The source of particles is an essential component of any Monte Carlo simulation. Similar to geometries, many sources may be defined within the single source definition input block. The source to use in the simulation must be specified using the simulation source input parameter.

:start source definition:
    :start source:
        definition of a source
        name = my_source
    :stop source:

    simulation source = my_source

:stop source definition:

Here is an example, which was created using the EGS_CollimatedSource documentation. Notice that shapes are used by the source, which are defined using a shape input block. Similarly, the spectrum is defined using a spectrum input block. All energies are in units of MeV.

:start source definition:
    :start source:
        library = egs_collimated_source
        name = my_source
        :start source shape:
            type = point
            position = 0 0 5
        :stop source shape:
        :start target shape:
            library   = egs_rectangle
            rectangle = -1 -1 1 1
        :stop target shape:
        distance = 5
        charge = -1
        :start spectrum:
            type = monoenergetic
            energy = 20
        :stop spectrum:
    :stop source:

    simulation source = my_source

:stop source definition:

Ausgab (output) definitions

Optionally, ausgab definitions allow for additional output from the simulation. These correspond to EGS_AusgabObject objects, and include dose output by region or medium, and particle tracks.

:start ausgab object definition:
    :start ausgab object:
        definition of an ausgab object
    :stop ausgab object:
    :start ausgab object:
        definition of another ausgab object
    :stop ausgab object:
:stop ausgab object definition:

To learn about possible inputs, see EGS_DoseScoring and EGS_TrackScoring. Here is an example for dose output by region and track scoring of 1000 tracks.

:start ausgab object definition:
    :start ausgab object:
        name    = my_tracks
        library = egs_track_scoring
        stop scoring = 1024
    :stop ausgab object:
    :start ausgab object:
        name         = my_dose
        library      = egs_dose_scoring
        medium dose  = no
        region dose  = yes
        volume       = 6 # in cm**3 (for the geometry above = 1*2*3)
        dose regions = 1 # list of individual region numbers (we just have 1)
    :stop ausgab object:
:stop ausgab object definition:

Run control

The run control input block specifies generic parameters about the simulation. Importantly, this is where the user selects the number of histories to simulate (usually corresponding to the number of source particles to use). A simple run control object (RCO) is used to control a single run. A simple RCO understands the following inputs:

:start run control:
    ncase                       = number of histories to run
    nbatch                      = [optional] number of batches to use (default is 10)
    statistical accuracy sought = [optional] required uncertainty in %
    max cpu hours allowed       = [optional] max. CPU time allowed
    calculation                 = [optional] first or restart or combine or analyze
    geometry error limit        = [optional] number of geometry errors allowed before crashing
:stop run control:

For example, to simulate 1 million histories:

:start run control:
    ncase = 1e5
:stop run control:

The only required input is the number of histories. The nbatch input determines how many times the simulation will report its progress (and not, as one might expect, the number of statistical batches as a history-by-history statistical analysis is used). With the statistical accuracy sought input one can make the calculation terminate when the specified uncertainty is reached for the cavity dose. Note, however, that after ncase histories the simulation does not continue until this uncertainty is obtained. With the max cpu hours allowed input one can limit the simulation time to some maximum time in hours. With the calculation input one determines the type of simulation:

first means a fresh simulation (the default)
with restart one can restart a previously performed simulation
with combine one can combine the results of parallel runs. This is needed when one or more of the parallel jobs has not finished so that the results are not automatically combined or when one uses a simple RCO for parallel runs (see below).
the analyze option is used to read the simulation data from the .egsdat file and output the results to the standard output.

A "job-control-file" (JCF) RCO is used by default for parallel runs. A JCF RCO understands, in addition to the above, the optional input

nchunk = [optional] number of simulation chunks (default is 10)

In parallel runs the simulation is split into nchunk*n_parallel portions and each parallel job simulates one portion at a time until no histories are left. Note that a functioning file locking functionality is needed on the system in order to use a JCF-RCO. As some users have reported problems with file locking, one can force the use of a simple RCO by specifying -s on the command line. In this case, all parallel jobs will execute the same number of histories as specified in the input file.

Random numbers

The random number block specifies the random generator used for the simulation. Currently, the only generator available in egs++ is the ranmar generator. This block is optional but useful to ensure simulation reproducibility by explicitly setting initial seeds. For parallel runs, each job uses a different set of seeds based on the seeds in the input file. The high resolution input can be used to obtain higher quality results with the tradeoff of increased runtime (which varies depending on the simulation).

:start rng definition:
    type            = ranmar      # generator type
    initial seeds   = 33 97       # initial seeds
    high resolution = yes         # no (default), yes
:stop rng definition:

Monte Carlo transport parameters

The Monte Carlo transport parameters have important and significant influence on both the accuracy of the simulation, and the efficiency. If you are unsure, neglect this input block entirely to use the defaults. If you are publishing an article using EGSnrc, make sure to disclose the transport parameters in use, as well as the release version.

#  Modify here parameters that should be different from their defaults.
:start MC transport parameter:
    Global ECUT                    = 0.521          # Global electron transport cutoff
    Global PCUT                    = 0.001          # Global photon transport cutoff
    Global SMAX                    = 1e10           # Global maximum step-size restriction for e- transport
    ESTEPE                         = 0.25           # Default is 0.25
    XIMAX                          = 0.5            # Default is 0.5, max. value is 1.
    Boundary crossing algorithm    = exact          # exact (default), PRESTA-I
    Skin depth for BCA             = 3              # Default value is 3 for exact boundary crossing
    Electron-step algorithm        = PRESTA-II      # PRESTA-II (default),PRESTA-I
    Spin effects                   = On             # On (default),Off
    Brems angular sampling         = KM             # Simple,KM (default)
    Brems cross sections           = BH             # BH (default), NIST, NRC
    Pair angular sampling          = Simple         # Off, Simple (default),KM
    Triplet production             = Off            # On or Off (default)
    Electron Impact Ionization     = Off            # On, Off (default), casnati, kolbenstvedt, gryzinski
    Bound Compton scattering       = norej          # On, Off, Simple, norej (default)
    Radiative Compton corrections  = Off            # On,  Off (default)
    Rayleigh scattering            = Off            # On ,Off (default), custom
    Photoelectron angular sampling = On             # On (default),Off
    Atomic relaxations             = On             # On (default),Off
    Photon cross sections          = xcom           # si, epdl, xcom (default) or user-supplied
    Photon cross-sections output   = Off            # Off (default) or On
    Compton cross sections         = comp_xsections # user-supplied
    Photonuclear attenuation       = Off            # Off (default) or On
    Photonuclear cross sections    = default        # default (default) or user-supplied
:stop MC transport parameter:

Default values used in EGSnrc are set to provide an accurate simulation of the electron-photon transport, except for the exclusion of coherent (Rayleigh) scattering in low-energy photon problems. The reason for this is that until very recently users needed to specifically request the inclusion of Rayleigh cross sections in the PEGS4 data sets. Currently, Rayleigh cross sections are generated on the fly (see Rayleigh in PIRS-701). Default values may often only add time to your calculation. One can speed things up by turning them off. The user is referred to section 2.6 of the PIRS-702 manual for a detailed description of these parameters.

Input loops

Sometimes it is necessary to repeat a geometry or other part of the input file, while just changing one parameter in a loop. If you are a programmer and comfortable with scripting (e.g. python), feel free to generate input files from a script - this is the most flexible and powerful method. However, there is a basic loop and variable replacement functionality built into egs++ input files, called input loops.

For a complete description of input loops, see the documentation linked above.

A simple example

Putting together the examples suggested above, we have a complete input file. Note that we are using default transport parameters. This input file will work with any egs++ application that doesn't require additional inputs. For example, it will work with tutor7pp.

:start geometry definition: # Only one geometry definition block allowed
    :start geometry: # There may be many geometry blocks
        name        = my_box # A name of your choosing
        library     = egs_box # As shown in the egs_box documentation
        box size    = 1 2 3 # Side-length along x,y,z in cm
        :start media input:
            media = water # The whole box is water
        :stop media input:
    :stop geometry:

    simulation geometry = my_box # The geometry to actually run the simulation in

:stop geometry definition:

:start media definition:

    # Threshold energies
    ae  = 0.521
    ap  = 0.01
    ue  = 50.511
    up  = 50

    # Give materials any name and refer to it in the geometry
    :start water:
        # This file must exist in $HEN_HOUSE/pegs4/density_corrections
        density correction file    = water_liquid
    :stop water:

:stop media definition:

:start source definition:
    :start source:
        library = egs_collimated_source # See the collimated source documentation
        name = my_source # A name of your choosing
        :start source shape: # Origin is a point
            type = point
            position = 0 0 5 # Distances in cm
        :stop source shape:
        :start target shape: # Target shape for collimated source
            library   = egs_rectangle
            rectangle = -1 -1 1 1
        :stop target shape:
        distance = 5
        charge = -1 # Electrons
        :start spectrum:
            type = monoenergetic
            energy = 20 # A beam of 20 MeV electrons
        :stop spectrum:
    :stop source:

    simulation source = my_source # Refer to your source by name

:stop source definition:

:start ausgab object definition: # Output options
    :start ausgab object: # Track scoring (view in egs_view)
        name    = my_tracks
        library = egs_track_scoring
        stop scoring = 1024
    :stop ausgab object:
    :start ausgab object: # Dose scoring
        name         = my_dose
        library      = egs_dose_scoring
        medium dose  = no
        region dose  = yes
        volume       = 6 # in cm**3 (for the geometry above = 1*2*3)
        dose regions = 1 # list of individual region numbers (we just have 1)
    :stop ausgab object:
:stop ausgab object definition:

:start rng definition:
    type = ranmar
    initial seeds = 33 97
    high resolution = yes
:stop rng definition:

:start run control:
    ncase = 1e5 # Number of histories to run
:stop run control: