The following README.txt is also bundled with the TOPAS software downloaded from

TOPAS Version 3.0.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:

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 ( ) and GDCM ( )

0) Pre-Requisites:

Mac OSX 10.9 or newer: Install XQuartz
To run TOPAS on OSX 10.9 or newer, you must also install the X11 application from:
Users of previous OSX versions do not need to perform this step.

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

1) Install TOPAS:

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

2) Install Data Files:
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 include and pre-built in TOPAS.
If you are simply upgrading from a previous TOPAS version that uses the same Geant4 version,
you will already have these data files and can skip this step.

Mac: Download Geant4 Data files from the command line using curl:
curl -O
curl -O
curl -O
curl -O
curl -O
curl -O
curl -O
curl -O
curl -O
curl -O
curl -O

Linux: Download Geant4 Data files from the command line using wget:

Mac: Unpack and move to:

Linux: Unpack and move to:

3) Set up the environment:
export G4LEDATA=/Applications/G4Data/G4EMLOW6.48
export G4NEUTRONHPDATA=/Applications/G4Data/G4NDL4.5
export G4LEVELGAMMADATA=/Applications/G4Data/PhotonEvaporation3.2
export G4RADIOACTIVEDATA=/Applications/G4Data/RadioactiveDecay4.4
export G4SAIDXSDATA=/Applications/G4Data/G4SAIDDATA1.1
export G4NEUTRONXSDATA=/Applications/G4Data/G4NEUTRONXS1.4
export G4PIIDATA=/Applications/G4Data/G4PII1.3
export G4REALSURFACEDATA=/Applications/G4Data/RealSurface1.0
export G4ABLADATA=/Applications/G4Data/G4ABLA3.0
export G4ENSDFSTATEDATA=/Applications/G4Data/G4ENSDFSTATE1.2.1
export G4TENDLDATA=/Applications/G4Data/G4TENDL1.0
export DYLD_LIBRARY_PATH=/Applications/topas/libexternal:$DYLD_LIBRARY_PATH

Linux Bourne shell:
export G4LEDATA=~/G4Data/G4EMLOW6.48
export G4NEUTRONHPDATA=~/G4Data/G4NDL4.5
export G4LEVELGAMMADATA=~/G4Data/PhotonEvaporation3.2
export G4RADIOACTIVEDATA=~/G4Data/RadioactiveDecay4.4
export G4PIIDATA=~/G4Data/G4PII1.3
export G4REALSURFACEDATA=~/G4Data/RealSurface1.0
export G4ABLADATA=~/G4Data/G4ABLA3.0
export G4TENDLDATA=~/G4Data/G4TENDL1.0
export LD_LIBRARY_PATH=~/topas/libexternal/:$LD_LIBRARY_PATH

Linux C shell:
setenv G4LEDATA ~/G4Data/G4EMLOW6.48
setenv G4NEUTRONHPDATA ~/G4Data/G4NDL4.5
setenv G4LEVELGAMMADATA ~/G4Data/PhotonEvaporation3.2
setenv G4RADIOACTIVEDATA ~/G4Data/RadioactiveDecay4.4
setenv G4PIIDATA ~/G4Data/G4PII1.3
setenv G4REALSURFACEDATA ~/G4Data/RealSurface1.0
setenv G4ABLADATA ~/G4Data/G4ABLA3.0
setenv G4TENDLDATA ~/G4Data/G4TENDL1.0
setenv LD_LIBRARY_PATH ~/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
../../topas MultiLeafCollimator_sequence.txt

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

Remember that some parameters have changed since Topas 2.0.
We provide a script that you can run to convert your parameter files from Topas2 style to Topas3 style.
Download the script:
Mac: curl -O
Linux: wget

Then for any OS:
chmod +x topas2to3
/path/to/topas2to3 your_parameter_file.txt

This will replace your_parameter_file.txt with a new copy, and will save the previous version with a .bak file extension.

5) To add User Extensions:
You will need a tool called CMake (version 3.3 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 from a binary distribution at:
Run the
and follow the instructions in CMake's menu item: "Tools"... "How to Install for Command Line Use"

Because our underlying Geant4 version requries a compiler that supports C++11,
you will need gcc >=4.8.3
To check your gcc version, gcc --version
If your gcc version is not sufficient, ask your sysadmin if there is already a newer version in some non-default installation on your system. They may be able to tell you how to switch to that version.
Otherwise, you will need to install a newer version or ask your sysadmin to do so.
Then locate the file and add this directory to your LD_LIBRARY_PATH environment variable
(`export LD_LIBRARY_PATH=/path/to/gcc/lib:$LD_LIBRARY_PATH`).

Unzip the full set of Geant4 header files from topas/
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.
For example, you might have TOPAS in:
and the extensions in:

Mac: cd /Applications/topas
Linux: cd ~/topas

cmake -DTOPAS_EXTENSIONS_DIR=/Applications/topas_extensions
make -j8

In the make statement, the value after -j, such as -j8 indicates how many threads make should use at once.
This depends on your computer's capabilties. A typical quad-core machine with hyperthreading run efficiently with 8 threads.

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 -j8

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