Install EGSnrc on Linux

Overview

Installing EGSnrc on Linux involves 3 steps:

1. Install prerequisite software
2. Download EGSnrc
3. Configure EGSnrc

1. Install prerequisite software

Before installing EGSnrc on Linux, ensure the software packages listed below are installed. These are very common and widely available, often installed by default on many Linux distributions (otherwise you can find them through your package manager, or else ask your system administrator to install them). The optional components are highly recommended, even though the core EGSnrc simulation toolkit will work without 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. optional: the Tcl/Tk interpreter and widget toolkit, version 8.0 or later
6. optional: the Grace plotting tool (providing the xmgrace command), version 5.0 or later
7. optional: Open Motif development package, to compile dosxyz_show (e.g. libmotif-dev)
8. optional: the Qt4 or Qt5 development tools (e.g. qt5-default and qt5-qmake), to re-compile the Qt GUIs
9. optional: a job scheduler 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

Note that EGSnrc require a compiler that supports the C++14 standard (g++ option -std=c++14). If you have an older compiler that does not recognize this option, please adjust or remove it from the list of proposed flags during the EGSnrc configuration.

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

Tcl/Tk

While Tcl/Tk is not essential to run EGSnrc simulations, it proves useful if you want to use EGSnrc graphical user interfaces. Note that Tcl/Tk is normally installed by default in most Linux distributions. If you want to check that Tcl/Tk is available on your system, open a terminal shell and issue the following command:

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

Grace

Grace proves useful if you want to display data plots generated by EGSnrc applications. It is packaged for major Linux distributions. To check if Grace is installed on your system, open a terminal shell and issue either of these commands:

grace -version      # should report Grace-5.0 or newer
xmgrace             # should launch the Grace graphical user interface

On some Red Hat systems, it may be necessary to add the epel.repo (https://fedoraproject.org/wiki/EPEL), then install the grace package.

Open Motif

You don't need Open Motif to run EGSnrc simulations. However, to compile the dosxyz_show application (for visualizing voxelized phantoms and dose distributions), you need the Open Motif library development files. The corresponding package is generally available in major Linux distributions, under different names: libmotif-dev, libmotif-devel, libopenmotif-devel, openmotif-devel, motif-devel.

Qt GUIs

Compiling the Qt GUIs is not normally required - precompiled versions are provided through the installation tool, and on the release page. However, for developers see the instructions here.

Job scheduler

You don't need a job scheduler to run EGSnrc simulations. A job scheduler simplifies the queuing, managing and monitoring of parallel calculations on a many-core system. Examples of popular schedulers are: OpenPBS, Torque, Slurm, Grid Engine, Moab. EGSnrc is compatible with any scheduling software. We provide the script $HEN_HOUSE/scripts/bin/egs-parallel to facilitate job submission out-of-the-box on OpenPBS and Torque schedulers, as well as on multi-core machines.

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 or '@' character. We recommend that you use git to clone the EGSnrc repository, but alternatively you may download a compressed image of the EGSnrc directory.

Make sure to install EGSnrc in a short path (e.g. /home/you/EGSnrc), because there is a limit of 80 characters on path lengths in the Mortran codes.

Option 1: Clone the git repository (strongly recommended)

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

Consider the Upgrading instructions which propose a few additional steps in the installation procedure to manage upgrades more easily with the git version control software, and to facilitate citing your local code modifications unequivocally.

Option 2: Download 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 software environment, using either a configuration GUI or a configuration shell script that prompts you for configuration options on the command-line.

Option 1: Configure using the GUI

1. Download the EGSnrc-configure-linux executable from the latest release on the release 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

Option 2: Configure using the shell script

1. Open a terminal bash shell
2. If you have installed EGSnrc before and would like 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 (e.g. ~/.bashrc), 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. From the latest release, download EGSnrc-guis-linux.tar.gz, which provides pre-compiled EGSnrc graphical user interfaces. Or better yet, consider compiling them yourself.