Install EGSnrc on Linux

1. Install prerequisite software

Before installing EGSnrc on Linux, ensure the following software is installed. These are very common and widely available software packages, often installed by default on many Linux distributions. Otherwise you can easily find and install them through your package manager, or else ask your system administrator to install them:

1. a Fortran compiler (preferably gfortran)
2. a C compiler (preferably gcc)
3. a C++ compiler (preferably g++)
4. the GNU make utility
5. Open Motif, for dosxyz_show (libmotif-dev)
6. [optional] the Tcl/Tk interpreter and widget toolkit, version 8.0 or later
7. [optional] the Grace plotting tool (providing the xmgrace command), version 5.0 or later
8. [optional] a batching system of your choice (e.g. the package at), for parallel processing

Compilers

You may use any working Fortran, C and C++ compilers on your system. We develop and use EGSnrc with the GNU compilers gfortran, gcc and g++, so these are recommended. If you use other compilers, you might have to adjust compilation options in the configuration stage in order for EGSnrc to work as expected. To check that you have working Fortran, C and C++ compilers, open a terminal shell and issue the following commands (or equivalent ones if you are using other compilers):

gfortran --version          # should report your Fortran compiler version
gcc --version               # should report your C compiler version
g++ --version               # should report your C++ compiler version

GNU make

EGSnrc relies on a make tool, which controls and automates the software building process: most EGSnrc applications are built by issuing the make command in the appropriate directory. There are various implementations of make, but EGSnrc relies on features of the GNU implementation (also called gmake on some systems). To check that make invokes GNU make on your system, open a terminal shell and issue the following command:

make --version              # should report "GNU Make" on first line

Open Motif

The dosxyz_show application in EGSnrc (for visualizing voxelized phantoms and dose distributions) requires the Open Motif library to be installed. This library should be available for your favourite linux distribution - on Ubuntu you can install it as the package libmotif-dev.

Tcl/Tk and Grace

While Tcl/Tk and Grace are not essential to run EGSnrc simulations, they prove useful if you want to use EGSnrc graphical user interfaces and display data plots generated by EGSnrc applications. Note that Tcl/Tk is normally installed by default in most Linux distributions. If you want to check that Tcl/Tk and Grace are available on your system, open a terminal shell and issue the following commands:

echo 'puts [info patchlevel]; exit 0' | wish    # should report version 8.0 or newer
grace -version                                  # should report Grace-5.0 or newer

A batching system

Batching systems are used to manage the queuing and prioritizing of parallel calculations for one or many users. It is up to you to decide which batching system suits your needs, and whether you need one at all. While EGSnrc is compatible with any batching system in theory, we provide some tools to make the process easier out-of-the-box. For example, the script $HEN_HOUSE/scripts/run_user_code_batch has built in support for the batching systems at and pbsdsh.

Here is an example. If you have installed pbsdsh on the current computer, you might queue a multi-core egs_chamber job with a command like the following:

$HEN_HOUSE/scripts/run_user_code_batch egs_chamber myInputFileName pegsless long batch=pbsdsh p=8

The above queues an 8-core calculation of egs_chamber for the input file myInputFileName.egsinp in pegsless mode onto the long queue of the batching system pbsdsh. If you are not using pegsless mode, use the name of the PEGS data file instead (e.g. 700icru).

2. Download EGSnrc

To use the EGSnrc toolkit you must copy the entire EGSnrc directory tree to your computer. All the project files are grouped in a single top-level EGSnrc directory which you can put just about anywhere on your system (preferably under your home directory for a single-user installation) as long as the path contains no blank space. We recommend that you use git to clone the EGSnrc repository, but alternatively you may download a compressed image of the EGSnrc directory.

Option 1: Clone the git repository

1. Open a terminal shell
2. Check that git is available on your system: git --version
3. Change directory to the desired install location (note that cloning the repository with create a new directory EGSnrc in your current directory): cd path/to/your/install/location
4. Clone the EGSnrc repository: git clone https://github.com/nrc-cnrc/EGSnrc.git

Option 2: Download as a zipped archive

1. Download the compressed image EGSnrc-master.zip
2. Move the EGSnrc-master.zip file to the desired install location
3. Uncompress the archive using the unzip command-line tool, or your favorite utility
4. If you want, you can rename the inflated EGSnrc-master directory to EGSnrc

3. Configure EGSnrc

Once you have the EGSnrc source code on your computer, you must configure EGSnrc for your particular operating system and software environment, using either a configuration GUI or a configuration shell script that prompts you for configuration options on the command-line.

Configure using the GUI

1. Download the EGSnrc-configure-linux executable from the EGSnrc web page
2. Turn on the execute permission for this file: chmod +x EGSnrc-configure-linux
3. Clear EGSnrc environment variables: export HEN_HOUSE= EGS_HOME= EGS_CONFIG=
4. Launch the installer: ./EGSnrc-configure-linux
5. Read the first page and click Next
6. Choose a name for your configuration
7. Pick a HEN_HOUSE directory, normally inside the EGSnrc top-level directory
8. Choose your personal EGSnrc user directory; we recommend you call it egs_home, inside your EGSnrc top-level directory
9. Click Next, review the Licence notice, and click Next
10. Select whether you want the program to set your environment variables and create desktop icons at the end of the configuration, and click Install to proceed

Configure using the shell script

1. Open a terminal bash shell
2. For a fresh install, clear existing EGSnrc environment variables with the command:
   export HEN_HOUSE="" EGS_HOME="" EGS_CONFIG=""
3. Go to your EGSnrc directory: cd path/to/EGSnrc/directory
4. Launch the configuration script: ./HEN_HOUSE/scripts/configure
5. Answer prompts and follow instructions rigorously
6. In your shell resource file, insert commands to define $EGS_HOME, $EGS_CONFIG and source EGSnrc additions, as prescribed at the end of the user configuration script
7. Start a new terminal (or log out and back in again) to ensure the shell resource file is read
8. Download EGSnrc-guis-linux.zip, which provides pre-compiled EGSnrc graphical user interfaces, from the latest release