EGSnrc 2016

Introduction

The follwing description can also be found here:

NRC’s electron gamma shower (EGS) software tool can meet your specific requirements relating to modelling the passage of electrons and photons through matter. EGSnrc relies on Monte Carlo, which is the most accurate method to model the transport of radiation.

EGSnrc is used to address a broad range of questions about the propagation of radiation in materials. It is particularly well-suited for medical physics purposes, such as the research and development of devices that allow medical professionals to detect radiation, image a patient’s anatomy using x-rays, or deliver a prescribed radiation dose to a tumour while sparing healthy tissue. The software is also employed directly by medical physicists in cancer clinics for research and for verifying radiation treatment plans.

The software is freely available for research and other non-commercial purposes, see [1] for details. The latest version is now available on GitHub[2] and uses a new license model (free GNU license). Please read the documentation and license information on GitHub. By using EGSnrc on the cluster you are accepting the terms of the license. Also cite EGSnrc in any work published, the relevant citation can be found on GitHub as well.

The modules also includes the package BEAMnrc, see [3] for more information. Since version 2016 BEAMnrc is included in EGSnrc, no extra package need installation.

Installed version

The currently installed version of EGSnrc is 2017.

Using EGSnrc

If you want to find out more about EGSnrc on the HPC cluster, you can use the command

module spider egsnrc

This will show you basic informations e.g. a short description and the currently installed version.

To load the module in version 2017, you need to use the command

module load EGSnrc/2017

Always remember: this command is case sensitive!

After loading the module, you can check if its succesfully loaded with the command

module list

First time usage

EGSnrc requires a directory in user space to store the so-called user codes. If you are using any version of EGSnrc for the first time on the cluster, you need to create a directory where these user codes can be copied to. Before you can start the script for doing this, you will need to load the module for EGSnrc. Do this by using the following command

module load EGSnrc

The rest of the process can be started by running the provided scripts for EGSnrc. Simply type

 ./finalize_egs_foruser

The script will ask you for a directory name to store the user codes:

 Input the directory where you want to keep your user codes 
      [/user/abcd1234/egsnrc-2017]: 

It is strongly recommended that you use the following directories which are also the suggested defaults: for EGSnrc 2016 or later the default is $HOME/egsnrc-VERSION where version is replaced by the version number (2017 in our case) The default is accepted by simply typing Return. The default directory is also set by loading the module as can be seen with

 echo $EGS_HOME

after loading the module for the desired version. If you are not using the recommended setting here you will need to change $EGS_HOME after loading the module.

Then you will be asked which user codes should be installed where you can enter e.g. 1 for Compile all. After that you should a few messages about codes being successfully compiled. This may take a few minutes.

After the installation of the user codes you will see the following message:

#######################################################################################

The EGSnrc configuration for abcd1234 is ALMOST complete ...

EGSnrc requires various environment variables and aliases to be defined.
Typically you add these definitions to your shell resource file located in
your home directory, to ensure the EGSnrc environment is properly set up
every time you log in.

Your default shell is /bin/bash
Add the following statements to your .bashrc file: 

export EGS_HOME=/user/abcd1234/egsnrc-2017/
export EGS_CONFIG=/cm/shared/uniol/software/EGSnrc/2017/HEN_HOUSE/specs/linux.conf
source /cm/shared/uniol/software/EGSnrc/2017/HEN_HOUSE/scripts/egsnrc_bashrc_additions

#######################################################################################

You do not need to modify your .bashrc-file as all the required settings are done by loading the module as described above.

Testing the setup

You can quickly test if everything is setup correctly by using the command

tutor1 -p tutor_data

which should produce about 100 lines of output in ca. one second.

Using EGSnrc on the HPC cluster

Since there many people working with the HPC cluster, its important that everyone has an equal chance to do so. Therefore, every job should be processed by SLURM.

For this reason, you have to create a jobscript for your tasks.

Example:

#!/bin/bash
               
#SBATCH --ntasks=1                  
#SBATCH --mem=2G 
#SBATCH --partition=carl.p                 
#SBATCH --time=0-2:00  
#SBATCH --job-name EGSNRC-TEST              
#SBATCH --output=EGSnrc-test.%j.out        
#SBATCH --error=EGSnrc-test.%j.err

#load EGSnrc
module load EGSnrc

#settings (here you need to make your own modifitcations)
# NOTE: the input file has to be in the directory $EGS_HOME/$USERCODE
#       the PEGS4DATA files can be located in different locations
#       one is the HEN_HOUSE which is automatically set
USERCODE=cavrznrc
INPUTFILE=cavrznrc_template
PEGS4DATA=521icru

1. run code, e.g. the example from cavrznrc

$USERCODE -i $INPUTFILE -p $PEGS4DATA

Documentation

The documentation of EGSnrc can be found on here. (PDF viewer required!)