Installation instructions for TOPAS Version 3.6.1

All use of TOPAS is governed by the TOPAS License Agreement provided in this directory as LICENSE.txt.

This README shows how to install and run TOPAS with and without user extensions.

In case of problems, see the TOPAS Monte Carlo User Forum at:
topasmc.org

These instructions are written for single user installations.
Systems administrators performing multi-user installations may need to adapt these recipes.

These instructions assume the user has basic familiarity with the use of paths, shells and environment variables on their chosen operating system.
For users who have that familiarity, it should be obvious how to adapt these recipes to their own installations.
For others who do not have that familiarity, we suggest you first read some general tutorials for paths, shells and environment variables.

This product includes software developed by Members of the Geant4 Collaboration ( http://cern.ch/geant4 ), GDCM ( http://gdcm.sourceforge.net ) and The Qt Company ( http://qt.io ).

0) Pre-Requisites:
You will only need to do this part one time for each new computer.

MacOS 10.14 or earlier: Install XQuartz from:
http://xquartz.macosforge.org
If you already had XQuartz, check that you have at least version 2.7.11
If you have just installed XQuartz, you will need to reboot for it to work.
This step is NOT required for users on MacOS 10.15 Catalina.

Debian Users: Install the following:
apt install -y libexpat1-dev
apt install -y libgl1-mesa-dev
apt install -y libglu1-mesa-dev
apt install -y libxt-dev
apt install -y xorg-dev
apt install -y build-essential

CentOS Users: Install the following:
yum groupinstall -y "Development Tools"
yum install -y expat-devel
yum install -y libXmu-devel
yum install -y mesa-libGL-devel
yum install -y mesa-libGLU-devel


1) Install TOPAS:
You will only need to do this part one time for each new TOPAS version.

Mac:
Double-click on the topas_3_5_*.zip file to unzip it.
Move the resulting directory so that you have /Applications/topas

And if your Mac version is 10.15 (Catalina):
Before you can run TOPAS for the first time, you need to tell the Mac Gatekeeper that TOPAS is OK to run.
You do this by right clicking (that is, Control click) on the file: topas/bin/topas
and selecting Open.
This will not actually start TOPAS successfully, but it will tell Gatekeeper that you approve of running topas.
After that, you can run topas from the terminal window in the usual way that is explained in step 3 below.

Linux:
Unpack the tar.gz file:
tar -zxvf topas_3_5_*.tar.gz
Move the result so that you have ~/topas


2) Install Data Files:
You may only need to do this one time for your first TOPAS version.

In most cases, when we upgrade TOPAS you do not need to upgrade these Data files.
The TOPAS release notes will tell you if you actually need to update these Data files.
(it only needs doing when we change the underlying Geant4 release inside of TOPAS).

The only part of Geant4 that you need to install are the data files.
You do not need to download or build any other part of Geant4 since the necessary
Geant4 libraries and header files are already included in TOPAS.

Download and Install Geant4 Data files into your /Applications/G4Data directory.

Mac:
You do this by issuing the following commands from a Terminal window:
mkdir /Applications/G4Data
cd /Applications/G4Data
curl -O https://geant4-data.web.cern.ch/geant4-data/datasets/G4NDL.4.6.tar.gz
curl -O https://geant4-data.web.cern.ch/geant4-data/datasets/G4EMLOW.7.9.1.tar.gz
curl -O https://geant4-data.web.cern.ch/geant4-data/datasets/G4PhotonEvaporation.5.5.tar.gz
curl -O https://geant4-data.web.cern.ch/geant4-data/datasets/G4RadioactiveDecay.5.4.tar.gz
curl -O https://geant4-data.web.cern.ch/geant4-data/datasets/G4PARTICLEXS.2.1.tar.gz
curl -O https://geant4-data.web.cern.ch/geant4-data/datasets/G4SAIDDATA.2.0.tar.gz
curl -O https://geant4-data.web.cern.ch/geant4-data/datasets/G4ABLA.3.1.tar.gz
curl -O https://geant4-data.web.cern.ch/geant4-data/datasets/G4INCL.1.0.tar.gz
curl -O https://geant4-data.web.cern.ch/geant4-data/datasets/G4PII.1.3.tar.gz
curl -O https://geant4-data.web.cern.ch/geant4-data/datasets/G4ENSDFSTATE.2.2.tar.gz
curl -O https://geant4-data.web.cern.ch/geant4-data/datasets/G4RealSurface.2.1.1.tar.gz
curl -O https://geant4-data.web.cern.ch/geant4-data/datasets/G4TENDL.1.3.2.tar.gz
tar -zxf G4NDL.4.6.tar.gz
tar -zxf G4EMLOW.7.9.1.tar.gz
tar -zxf G4PhotonEvaporation.5.5.tar.gz
tar -zxf G4RadioactiveDecay.5.4.tar.gz
tar -zxf G4PARTICLEXS.2.1.tar.gz
tar -zxf G4SAIDDATA.2.0.tar.gz
tar -zxf G4ABLA.3.1.tar.gz
tar -xzf G4INCL.1.0.tar.gz
tar -zxf G4PII.1.3.tar.gz
tar -zxf G4ENSDFSTATE.2.2.tar.gz
tar -zxf G4RealSurface.2.1.1.tar.gz
tar -zxf G4TENDL.1.3.2.tar.gz

Linux:
You do this by issuing the following commands from a Terminal window:
mkdir ~/G4Data
cd ~/G4Data
wget https://geant4-data.web.cern.ch/geant4-data/datasets/G4NDL.4.6.tar.gz
wget https://geant4-data.web.cern.ch/geant4-data/datasets/G4EMLOW.7.9.1.tar.gz
wget https://geant4-data.web.cern.ch/geant4-data/datasets/G4PhotonEvaporation.5.5.tar.gz
wget https://geant4-data.web.cern.ch/geant4-data/datasets/G4RadioactiveDecay.5.4.tar.gz
wget https://geant4-data.web.cern.ch/geant4-data/datasets/G4PARTICLEXS.2.1.tar.gz
wget https://geant4-data.web.cern.ch/geant4-data/datasets/G4SAIDDATA.2.0.tar.gz
wget https://geant4-data.web.cern.ch/geant4-data/datasets/G4ABLA.3.1.tar.gz
wget https://geant4-data.web.cern.ch/geant4-data/datasets/G4INCL.1.0.tar.gz
wget https://geant4-data.web.cern.ch/geant4-data/datasets/G4PII.1.3.tar.gz
wget https://geant4-data.web.cern.ch/geant4-data/datasets/G4ENSDFSTATE.2.2.tar.gz
wget https://geant4-data.web.cern.ch/geant4-data/datasets/G4RealSurface.2.1.1.tar.gz
wget https://geant4-data.web.cern.ch/geant4-data/datasets/G4TENDL.1.3.2.tar.gz
tar -zxf G4NDL.4.6.tar.gz
tar -zxf G4EMLOW.7.9.1.tar.gz
tar -zxf G4PhotonEvaporation.5.5.tar.gz
tar -zxf G4RadioactiveDecay.5.4.tar.gz
tar -zxf G4PARTICLEXS.2.1.tar.gz
tar -zxf G4SAIDDATA.2.0.tar.gz
tar -zxf G4ABLA.3.1.tar.gz
tar -xzf G4INCL.1.0.tar.gz
tar -zxf G4PII.1.3.tar.gz
tar -zxf G4ENSDFSTATE.2.2.tar.gz
tar -zxf G4RealSurface.2.1.1.tar.gz
tar -zxf G4TENDL.1.3.2.tar.gz


3) Set up the environment:
You will need to do this every time you open a fresh Terminal window.

You may choose to put this setup information into one of your startup files,
but we recommend you only do that if you are very comfortable with such things,
as you may accidentally affect other processes.

Mac:
export TOPAS_G4_DATA_DIR=/Applications/G4Data
export QT_QPA_PLATFORM_PLUGIN_PATH=/Applications/topas/Frameworks

Linux Bourne shell:
export TOPAS_G4_DATA_DIR=~/G4Data
CentOS6 Users also do: export LD_LIBRARY_PATH=~/topas/libexternal/:$LD_LIBRARY_PATH

Linux C shell:
setenv TOPAS_G4_DATA_DIR ~/G4Data
CentOS6 Users also do: setenv LD_LIBRARY_PATHv~/topas/libexternal/:$LD_LIBRARY_PATH


4) Run TOPAS:
Mac: cd /Applications/topas
Linux: cd ~/topas

To run a whole set of examples:
source rundemos.csh

To run a single example:
cd to the directory that the example is in, then run topas from there, for example:
cd examples/SpecialComponents
../../bin/topas MultiLeafCollimator_sequence.txt

To test TOPAS with DICOM:
Unzip the example DICOM directories in examples/Patient
cd examples/Patient
../../bin/topas ViewAbdomen.txt

To test TOPAS with the Qt Graphical User Interface (works on all systems except CentOS6):
cd examples/Graphics
../../bin/topas QtTest.txt

CentOS8 Users:
If you get the message "error while loading shared librareis: libicudata.so.60: cannot open shared object file", get the following file from the topas code repository and place it into your topas/lib directory:
libicudata.so.60


5) To add User Extensions:

Linux users (but not required for CentOS6):
We could not fit all the required external libraries into the 50M file size limit
of a single tar.gz on our web site system, so please do the following:
Download from the Topas code repository the following file:
Geant4Headers_106P3.zip
Do not unzip the file yet, but just put the entire zip file into your topas directory
and rename it so that you will now have topas/Geant4Headers.zip.

You will need a tool called CMake (version 3.8 or newer).
Type "which cmake" to see if you already have this tool
and "cmake -version" to see what version you may have.

If you need to install CMake, install it as follows:

CMake for Mac: get the binary distribution at:
http://www.cmake.org/cmake/resources/software.html
Run the cmake.app
and follow the instructions in CMake's menu item: "Tools"... "How to Install for Command Line Use"

CMake for Debian 10:
apt install -y cmake

CMake for Debian8 and 9:
cd /usr
wget https://cmake.org/files/v3.8/cmake-3.8.2-Linux-x86_64.sh -P /usr/
chmod 755 /usr/cmake-3.8.2-Linux-x86_64.sh
./cmake-3.8.2-Linux-x86_64.sh
Answer y to accept the license.
Answer n to putting this new cmake into a subdirectory.

CMake for CentOS8:
yum install -y cmake

CMake for CentOS6 and 7:
cd /usr
wget https://cmake.org/files/v3.8/cmake-3.8.2-Linux-x86_64.sh -P /usr/
chmod 755 /usr/cmake-3.8.2-Linux-x86_64.sh
./cmake-3.8.2-Linux-x86_64.sh
Answer y to accept the license.
Answer n to putting this new cmake into a subdirectory.

Next, check that you have an appropriate compiler.

Compiler for Mac Users: You must have Mac OS X 10.12 or newer.
Users of earlier OSX versions or those using the above OSX versions with earlier Xcode versions
can run the pre-built TOPAS, but can not add extensions.
Install the Xcode compiler, version 8.3.2 or newer, from:
https://developer.apple.com/xcode/downloads/

Compiler for Linux Users:
Debian10 comes with appropriate g++ --version 8.3.0
Debian9 comes with appropriate g++ --version 6.3.0
Debian8 comes with appropriate g++ --version 4.9.2
CentOS8 comes with appropriate g++ --version 8.2.1
CentOS7 comes with appropriate g++ --version 4.8.5

CentOS6 does NOT come with an appropriate compiler.
It comes with version 4.4.7, but you will need at least 4.8.5.

Some research clusters may have their default compilers set to some different g++ version.
In that case, you may need to issue some command provided by your system administrators to change compilers.

If you are maintaining your own CentOS6 system, you may use the following:
yum install -y centos-release-scl
yum install -y devtoolset-7

CentOS6: then, each time you open a terminal window, activate this new compiler by doing:
source /opt/rh/devtoolset-7/enable

Once you are sure you have an appropriate compiler,
unzip the full set of Geant4 header files from topas/Geant4Headers.zip.
You should end up with a new directory: topas/Geant4Headers.
Do not use headers from any other version of Geant4 as they could appear to run OK but give wrong results!

Place your extra TOPAS code into a directory that is NOT inside of the topas directory.

The rest of these instructions will assume you have your extra TOPAS code in the directory
/Applications/topas_extensions
Adjust the instructions as necessary to point to the actual location of your extra TOPAS code
(on linux, for example, this might instead be ~/topas_extensions)

cmake -DTOPAS_EXTENSIONS_DIR=/Applications/topas_extensions
make

Don't worry about any "Warning" messages. Only worry about messages that say "Error".

If you get any error messages, confirm that you unzipped the Geant4 header files as explained above.
Also check that you have an appropriate compiler (see notes earlier in this section).

Then set up the environment and run as in steps 3 and 4 above.

CMake caches the name of your extensions directory and watches for subsequent changes there. If you make changes to any of the extensions you were already including (such as while you are debugging your extensions), you just need to re-run
make

If you add additional extensions to your extensions directory, again run the full
cmake -DTOPAS_EXTENSIONS_DIR=/Applications/topas_extensions
make