Install EGSnrc on Windows

Overview

Installing EGSnrc on Windows involves 3 steps:

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

1. Install prerequisite software

Before installing EGSnrc on Windows, ensure the following software is installed:

1. a Fortran compiler
2. a C compiler
3. a C++ compiler
4. the GNU make utility
5. optional: the git utility (strongly recommended)
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

Compilers

You may use any working Fortran, C and C++ compilers on your system. The open source suite of GNU compilers gfortran, gcc and g++ is an excellent choice. These compilers generate executables that are comparably fast to commercial compilers. The configuration GUI recognizes most common compilers. However, if this is not the case, 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 command prompt and issue the following commands (or equivalent ones if you are using other compilers):

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

Note that by default, some parts of EGSnrc require a compiler that supports standard C++11 (g++ option -std=c++11), and will soon require C++14 (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.

Obtaining and setting up the GNU compilers

NOTE: Currently the latest version of MinGW (8.1.0) is not compatible! In the MinGW installer, select version 7.3.0. If you change compiler versions after installing EGSnrc, it is recommended that you remove (or rename) your existing EGSnrc directory and do a completely fresh installation.

SourceForge.net hosts binary executables of the software development environment MinGW-w64 (Minimalist GNU for Windows with 64 bit support), for 64 bit and 32 bit architectures. The downloaded archive contains a compressed folder named either mingw32 or mingw64 depending on the architecture.

To use these compilers the only requirement is to update the PATH environment variable with the absolute path to the bin directory inside either mingw32 or mingw64. This can be done in the Advanced tab of the Computer Settings dialog if the user has the required privileges.

Alternatively, one can set the PATH variable temporarily in a command prompt session by typing:

set PATH=C:\mingw64\bin;%PATH%   # If folder for 64 bit located in C:

This can be set permanently by creating a command prompt session shortcut on the Desktop that invokes the above command. To accomplish this, right click on the shortcut icon, select Properties and set the target to be:

%COMPSPEC% /k "set PATH=C:\mingw64\bin;%PATH%"

If you choose to set the environment variables with the configuration GUI (recommended), it will create or update the environment variables for the user globally, including the path to the compilers.

Windows 10 example
Download mingw-w64-install.exe:
Run the mingw installer:
Version 7.3.0 is strongly recommended, many of the newer versions are not compatible. Select x86_64 for a 64-bit install. It's OK to install in the default directory.
Once you're done, it's time to set-up environment variables. The following method will only work if you have administrator privileges (if you don't, see above). Type environment in your windows search bar and click Edit the system environment variables. In the System Properties window that opens, click Environment Variables.
Click on the PATH variable, and click Edit.... Then click New and type in the path to the bin folder in your mingw installation directory.

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. The MinGW-w64 software development environment also includes GNU make under the name mingw32-make. To check that mingw32-make is available, open a command prompt and issue the following command:

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

Windows 10 example
Test that it works! Open a Command Prompt or Windows PowerShell and type mingw32-make.exe --version to look for standard output.

Tcl/Tk

While Tcl/Tk is not essential to run EGSnrc simulations, it is necessary if you want to use EGSnrc graphical user interfaces: previewRZ, beamnrc_gui, dosxyznrc_gui, and beamdp_gui. You can download an installer for Tcl/Tk from http://www.activestate.com/activetcl/downloads.

Windows 10 example
If you want to use the Tcl/Tk GUIs, download ActiveTcl. Install the Windows 64-bit, x64 installer. In this example, we use version 8.6.4.1.
Run the ActiveTcl installer. The installer should automatically update your PATH environment variable.

Grace on Windows: QtGrace

While Grace is not essential to run EGSnrc simulations, it proves useful if you want to display data plots generated by EGSnrc applications. The easiest way to get the Grace plotting tool on Windows is to install QtGrace, which is a port of the original Grace software to the Qt toolkit and which can run under Linux, OS X and Windows. You can download QtGrace from http://sourceforge.net/projects/qtgrace/.

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 folder name with blank spaces or '@' characters. 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. C:/EGSnrc), due to 80 character limits on file paths in Mortran.

Do not try to install in C:/Program Files/ - the space in the path will result in the installation failing.

Option 1: Clone the git repository (strongly recommended)

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

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 operating system and software environment, using the configuration GUI:

1. Download the EGSnrc-configure-windows.exe executable from the latest release on the release page
2. Launch the installer: ./EGSnrc-configure-windows.exe
3. Read the first page and click Next
4. Choose a name for your configuration
5. Pick a HEN_HOUSE directory, normally inside the EGSnrc top-level directory
6. Choose your personal EGSnrc user directory. We recommend you call it egs_home, inside your EGSnrc top-level directory. If this directory does not exist, it will be created
7. If you come to the next page and compilers are not automatically selected but you did install them already (and set your PATH environment variable), then you may just need to reboot your computer.
8. If compilers are correctly selected, click Next, review the License notice, and click Next again.
9. Before you click Install, it is recommended to check both Set environment and Desktop shortcuts. This will try to automatically set your environment variables, and create shortcuts to the GUIs on your desktop. These shortcuts are the easiest way to get the GUIs! Now click 'Install'
10. Congratulations! You have successfully installed EGSnrc.