Install EGSnrc on VirtualBox - nrc-cnrc/EGSnrc GitHub Wiki

Overview

A reliable way to install EGSnrc in its native GNU/Linux environment is to create a Linux virtual machine (a guest OS) on your physical machine (the host OS). The following instructions will guide you through the required steps using the free VirtualBox software (https://www.virtualbox.org/).

This EGSnrc installation method affords many advantages:

install on any computer that can run the VirtualBox software
quickly install EGSnrc in a fail-safe way
dodge installation issues on macOS or Windows
enjoy a consistent EGSnrc experience across different computing platforms
create a portable installation on a USB storage device
shelter your working copy against changes in the host OS
install on a system with limited administration rights
practice before installing on your main Linux system

Inevitably, a virtual machine installation also suffers drawbacks:

incurs a computing performance penalty
limits the number of virtual cpus to the number of physical cores in the host computer. For example, the Intel Core i9-9900K features 16 threads, but only 8 physical cores (2 threads per core). Hence only 8 cpus are available to the guest OS).
requires at least 10 GB of disk space (compared to about 200 MB for EGSnrc proper)

Installing EGSnrc in a VirtualBox guest Linux system involves 5 steps:

Install VirtualBox
Create a Linux virtual machine
Install a Linux distribution
Install the VirtualBox guest additions
Install EGSnrc

Apart from the time required to download files, the entire installation process takes about 20 minutes on a modern computer.

1. Install VirtualBox

Download the latest VirtualBox installer for your computer from https://www.virtualbox.org/ and follow the corresponding installation instructions. You should at this point be able to launch the VirtualBox program.

macOS High Sierra: VirtualBox might fail to install properly, or once a virtual machine is created and booted it might fail with the error Kernel driver not installed (rc=-1908). This occurs because the Oracle VirtualBox macOS kernel extension has not been approved officially yet, following a security policy update by Apple in High Sierra. You may solve this problem by allowing the kernel extension from Oracle via System Preferences > Security & Privacy [General]. See Technical Note TN2459 from Apple for details.

2. Create a Linux virtual machine

Note: we opt here for the "Lubuntu" Linux (https://lubuntu.me/) virtual machine, but feel free to pick your favorite Linux flavor instead (and tweak these instructions accordingly). If you are new to Linux, stick to Lubuntu, so that you can follow these instructions exactly.

Download the .iso image file for the latest Lubuntu 64-bit linux distribution: https://lubuntu.me/downloads/. The file is about 2 GB in size, so it might take a little while...
In VirtualBox, click on New to create a New virtual machine instance. Specify a name for this machine, choose the Linux type, and the Ubuntu (64-bit) version. Click Next.
Specify the amount of virtual RAM, say 4096 MB (4 GB), or whatever makes sense given the amount of physical RAM in your computer. Click Next.
Select Create a virtual hard disk now and click Next.
Select the disk type VDI (VirtualBox Disk Image). Click Next.
Select the Dynamically allocated storage on physical hard disk. This means that the virtual disk file grows in stride with the virtual disk size, up to a maximum size (specified in the next step). Click Next.
Specify a name and location for the virtual disk image file, as well as the maximum disk size, say 32 GB (keep in mind that the Lubuntu OS itself requires almost 10 GB). Click Create.
The virtual machine is created, and you are back to the Virtual main dashboard so to speak. Feel free to set other parameters for you new machine under Settings, such as the number of virtual processors, the amount of video memory, 3D acceleration, etc. Defaults should be fine, and these parameters can be changed later on.

At this point you have what amounts to a "bare metal" machine, i.e., the specified hardware (RAM, disk, etc.), but without any software, not even an operating system. In the next section we boot this empty machine and install Linux on it.

3. Install Linux

Click Start to boot your new virtual machine. Since the the virtual disk is empty, it will prompt you to select a startup disk. Select the Lubuntu .iso image downloaded earlier: you are thus effectively booting from a DVD, saved as a disk image. Select the proper file and click Start.
Select the installer language, and press Enter.
Select Start Lubuntu, and press Enter.
You are now running a "live" version of Lubuntu, from the .iso disk image.
Double-click on the Install Lubuntu icon to launch the Lubuntu installer.

At this point perhaps the default virtual screen resolution is too low, and you cannot see the buttons at the bottom right of the installer window (as shown in the image above) In that case, right-click on the bottom panel, click on Configure panel and check the Auto-hide option. You can also adjust the resolution via Preferences > LXQt settings > Monitor settings:

If the entire virtual screen is minuscule (typical on a very high resolution host screen), zoom the entire display via the VirtualBox menu View > Scale Factor or View > Virtual Screen 1.
Click Next, select your location and keyboard layout, to reach the Partitions step. This is where you format your virtual disk. This will not affect your physical disk on the host OS, so you can safely select the default partition scheme with Erase disk and click Next.
Specify your name, a login name, a name for the computer, and your password. Optionally you can select to login automatically when the virtual machine is booted, which is convenient if you are the only one with access to this virtual machine. Click Next.
Review the installation Summary, click Install, and in the confirmation dialog, click Install now.
The installation now proceeds, which takes a little while... Take a break, have a coffee.
Once the installation is all done, select Restart now and click Done.
Your virtual machine will reboot, and once you get to the screen below, press Enter.

4. Install the VirtualBox guest additions

The VirtualBox guest additions add software components (kernel modules) in your new Lubuntu guest OS to improve interactions between the virtual machine and the host system. While not strictly required, it is highly recommended.

Depending on how VirtualBox was installed on your computer, you may be able to simply load the .iso disk image for these guest additions via Devices > Insert Guest Additions CD image.... Otherwise, download the VBoxGuestAdditions_*.iso file from http://download.virtualbox.org/virtualbox/, inside the directory corresponding to your VirtualBox version; load it via the menu Devices > Optical Drives > Choose disk image....
Open the file manager, navigate to the VBOXADDITIONS disk and open a terminal via Tool > Open Terminal (or type Ctrl+Alt+T).
Issue the command sudo ./VBoxLinuxAdditions.run, and enter the password for the user account you created during the Lubuntu installation. Let the installation complete, which might take a minute or so.
Disconnect the guest additions disk image via the Devices > Optical Drives menu (you can safely click on Force Unmount if prompted). Reboot the virtual machine via Leave > Reboot.
Optional: take a snapshot of your virtual machine via Machine > Take Snapshot..., specifying a name and clicking Ok. This allows you to revert back to this fresh Lubuntu state if anything goes wrong, or clone this fresh Lubuntu system without having do go through the foregoing installation steps again.
Optional: create a shared folder in your virtual machine, a convenient way to access files on the host OS from within the guest OS. Add a shared folder via Devices > Shared Folders > Shared Folder Settings...: click on the folder with a + sign, specify the path of the folder on the host OS, then a folder name for the share, say myshare. If you want a permanent share, across reboots, do the same thing while the virtual machine is powered off.

Open a terminal (Ctrl+Alt+T) and create a new directory as a mount point for this share, e.g., mkdir ~/shared (the ~ character is shorthand for your home directory path). Mount the shared folder with the command:
```
sudo mount -t vboxsf myshare ~/shared
```
where myshare is the label you specified earlier in shared folder settings, while shared is the directory you just created. You should now see your host files in this directory. You can unmount the shared folder with sudo umount myshare. If you want this shared folder to be mounted automatically at boot time, add a corresponding entry in the /etc/fstab file in your virtual machine (replace yourname with the login name you picked earlier!):
```
myshare   /home/yourname/shared   vboxsf   defaults  0   0
```

5. Install EGSnrc

At this point you have a basic Lubuntu Linux system, and you can follow the instructions to Install EGSnrc on Linux as usual. For completeness we provide below detailed step for quick installation on a Lubuntu base system.

Open a terminal (Ctrl+Alt+T) and issue the following commands to install the pre-requisite software, and some optional ones:

sudo apt -y install git gcc g++ gfortran make tk expect
sudo apt -y install libmotif-dev qt5-default 
sudo apt -y install imagej kate

Note: On Ubuntu 24, install qt5-qmake instead of qt5-default.

Clone the EGSnrc repository and (optionally) checkout the develop branch, with the following commands:
```
git clone https://github.com/nrc-cnrc/EGSnrc.git
cd EGSnrc
git checkout develop
```
Configure EGSnrc on your machine, using the default options, with the command:
```
./HEN_HOUSE/scripts/configure.expect linux.conf 1
```
For a faster installation, you can skip the compilation of all EGSnrc applications by entering a 3 instead of 1 in the command above, and compile any individual application you want to use later on by going to the application directory and issuing the make command. If you want to enter different configuration options interactively, run ./HEN_HOUSE/scripts/configure instead.
Important: edit the text file .bashrc in your home directory to add the 3 configuration text lines specified at the end of the configuration script (for editing you can use Application menu > Accessories > FeatherPad, or Kate):
```
export EGS_HOME=~/EGSnrc/egs_home/
export EGS_CONFIG=~/EGSnrc/HEN_HOUSE/specs/linux.conf
source ~/EGSnrc/HEN_HOUSE/scripts/egsnrc_bashrc_additions
```
Close the terminal window, and open a new one (Ctrl+Alt+T) to ensure that the definitions above are loaded. You can verify that is the case with echo $EGS_HOME, which should return the string /home/yourname/EGSnrc/egs_home/ (where yourname is your chosen login name).

Compile the EGSnrc gui applications: issue the following commands in the terminal (takes a while, and don't worry about compiler warnings):

export QTDIR=/usr/lib/qt5
cd ~/EGSnrc/HEN_HOUSE/gui/ && make --quiet --print-directory
cd ~/EGSnrc/HEN_HOUSE/egs++/view/ && make --quiet --print-directory
cd ~/EGSnrc

Run a sample egs_app simulation of a 20 MeV electron pencil beam impinging on a 1 cm thick water slab, and display the geometry and some particle tracks with the egs_view utility:
```
cd ~/EGSnrc/egs_home/egs_app
make
egs_app -i slab.egsinp
egs_view slab.egsinp slab.ptracks
```
Congratulations, you are done, enjoy your fresh EGSnrc installation! Again, you might want to take a snapshot of your virtual machine at this point to be able to revert to or clone this machine state later on.