Getting started

This chapter explains the practical details to obtain the GAMOS code, compile and run it.

Getting the code and installing it

GAMOS has been tested in over ten Linux and MacOS distributions and compilers, and in Windows XP, 7 and 10 with Visual Studio 2012. Each new release is tested with over sixty tests in at least three different operating systems.

You can download GAMOS from http://fismed.ciemat.es/GAMOS

GAMOS depends on Geant4 and on ROOT [biblio.root]. To download and install everything you can follow the instruction in the ‘Code download’ area.

Installing in Linux and Mac OS

As explained in the web page you need to get first the installation scripts and decompress them in the scripts directory (you may do it automatically by downloading the scripts installation utility from the web page).

After that you just need to type the command

bash ./installGamos.sh <MY_INSTALLATION_DIR>

where <MY_INSTALLATION_DIR> is the directory where you want to install GAMOS. The directory name has to be an absolute path, i.e. starting with /. $HOME is OK because it means /home/…..

This command will download the GAMOS code as well as Geant4 and ROOT packages, and will compile them all. Be sure that you have installed in your system the X11 libraries in the directory /usr/X11R6/lib or /usr/local/lib or /usr/lib (check for the following libraries: libXmu.so , libXt.so, libXext.so, libX11.so, libICE.so.

as well as the OpenGL libraries (check for the following libraries: libGL.so, libGLU.so). If the OpenGL libraries are not found, GAMOS will ask you if you want to continue without them. In case of a positive answer, GAMOS will be installed without OpenGLX visualisation (but still with VRML visualisation). If the X11 libraries are not found, GAMOS will ask you if you want to continue without them. In case of positive answer, GAMOS will be installed without OpenGLX visualisation (but still with VRML visualisation) and without ROOT histograms. ROOT has some extra checks for libraries, namely libXpm.so, libXft.so and libXi.so, so you also have to install them.

To check that the libraries are present in your system, you may check for example with the command ‘locate libXmu.so’ to know where they are if they are not in the mentioned directories. See the subsections about Tips for installation in your favourite system.

After all the code is compiled, follow the instructions on how to run an example.

If the installation fails, you can find the cause of it in the file install.log at the directory where you tried to do the installation. Look for the first occurrence of the characters error (with a blank space first, as several class name have these characters). It is likely that the error is due to the fact that you are using a ROOT version not compatible with your system. If this is the case, try to find a new version number at the ROOT web page htt://root.cern.ch and change it at the file installGamosBaseDefs.sh that you will find at the scripts directory. Use an older version if you think your operative system is old and a new version if you think it is old. If you still are not able to install successfully GAMOS, please open a report at the GAMOS Users’ Forum, https://groups.google.com/forum/#!forum/gamos_users, and attach the install.log file (compress it first).

Tips for installation in Ubuntu

If you are using the Ubuntu Linux distribution you have to take into account that the default installation does not include the software for C++ developement. Therefore, it is likely that you have to install several extra packages. You can run, with superuser privileges, the following script:

bash ./installMissingPackages.Ubuntu.16.04.sh

before installing GAMOS.

Tips for installation in Fedora Core

If you are using the Fedora Core Linux distribution you have to select the software development tools at your installation. Else, it is likely that you have to install several extra packages. You can run, with superuser privileges, the following script:

bash ./installMissingPackages.Fedora.25.sh

before installing GAMOS.

Tips for installation in CentOS

If you are using the CentOS Linux distribution you have to take into account that the default installation does not include the software for C++ developement. Therefore, it is likely that you have to install several extra packages. You can run, with superuser privileges, the following script:

bash ./installMissingPackages.CentOS.7.sh

before installing GAMOS.

Downloading the files separately and installing afterwards

If you have poor connection it may be better to download the GAMOS installation files one by one first and then running the installation process. You have to download the following files:

  • GAMOS.6.2.0.tgz

  • geant4.10.05.p01.gamos.tar.gz

  • geant4.10.05.p01.gamos.data.tar.gz

  • root_v6.16.00.source.tar.gz

Put all the files in a directory, and then type

bash ./installGamos.sh <MY_INSTALLATION_DIR> MY_DOWNLOAD_DIR

where <MY_INSTALLATION_DIR> is the directory where you want to install GAMOS and MY_DOWNLOAD_DIR is the directory where you copied the installation files. Both directory names have to be absolute paths, i.e. starting with /. $HOME is OK because it means /home/…..

Copying GAMOS to a different place

If you have GAMOS installed at a given directory in a given computer and you want to copy it to another directory or to another computer, you can skip the downloading phase and go directly to the compilation (you should not try to use the original GAMOS distribution unless you are sure that the new computer has exactly the same operative system and the directory is the same as in the old computer). To re-install without downloading use the command:

bash ./reInstallGamos.sh <MY_INSTALLATION_DIR>

where <MY_INSTALLATION_DIR> is the directory where you have copied GAMOS. The directory name has to be an absolute path, i.e. starting with /. $HOME is OK because it means /home/…..

Installing in Windows

GAMOS 6.2.0 is still not available in Windows, please use GAMOS.5.0.0 instead or use the VMWARE virtual machine installation.

The first thing to do to install in Windows is selecting a directory, which we will call <MY_INSTALLATION_DIR>, and which can be for example c:\gamos. Before installing GAMOS you have to install ROOT. Get the executable file from the GAMOS web page and install it. GAMOS has to know automatically where ROOT is, so be careful not to use the Standard installation, but the Custom one, and change the default directory, to the directory <MY_INSTALLATION_DIR>\external\root\5.34.10\root.

To install GAMOS you have to download the GAMOS.6.2.0.zip file, copy it to your <MY_INSTALLATION_DIR> and decompress it. If your windows system does not have an unzip software and you do not have one, you may download a free one from http://7zip.com. After it is decompressed you just have to open the file <MY_INSTALLATION_DIR>/GAMOS.6.2.0/GAMOSGUI.exe. The first time it is opened it will configure GAMOS and create a GAMOSGUI.ini file. To run GAMOS you just have to select your input file clicking on the Open Input File and run it clicking on the Run button. All the output files will be written in the same directory where the input file is.

Checking your windows installation

As explained above, it is mandatory that the directory structure is correct, so that the GAMOS executable can find all the dynamic libraries. You should check that ROOT has been installed in the directory MY_DIRECTORY/external/root/5.34.10/root while GAMOS has been installed at MY_DIRECTORY/GAMOS.6.2.0/GAMOSGUI.exe, where MY_DIRECTORY is the directory you chose for GAMOS.

If the directory structure is OK, the first time you execute GAMOSGUI.exe, it does not find any file named GAMOSGUI.ini and then a command prompt window (a black window) pops up. This windows should stay for about 1 minute or more, and you should see a list of messages telling you that the GAMOS libraries are being processed. If the black window disappears quickly is that the library processing is giving some error message. In this case you probably are not able to read the messages fast enough before the windows disappears, so you should try to process the libraries in other way:

  • Open a command prompt window. In windows XP.

  • Type c:, or the disk unit where the GAMOS directories lie

  • Type cd MY_DIRECTORY where MY_DIRECTORY is the directory where GAMOSGUI.exe lies

  • Type cd config

  • Type genmap.win.bat > genmap.log

  • Open the genmap.log, for example with more genmap.log, or send this file to the GAMOS developers if you need help

Running an example in Linux or Mac OS

If you have done a standard installation, you will have your code compiled and ready to run.

Before running any example you have to set some configuration variables, mainly where you have installed GAMOS and the depending libraries. This is all done in the file

MY_GAMOS_DIR/config/confgamos.sh

By MY_GAMOS_DIR we mean the installation directory you have chosen, i.e. <MY_INSTALLATION_DIR>, plus the directory where the GAMOS version is installed, i.e.*<MY_INSTALLATION_DIR>/GAMOS.6.2.0*

or

MY_GAMOS_DIR/config/confgamos.csh

Therefore before running you have to source this file:

source MY_GAMOS_DIR/config/confgamos.sh

or

source MY_GAMOS_DIR/config/confgamos.csh

depending on your shell flavour. Remember to type this command every time you start a new session to run GAMOS.

To run your application inside GAMOS you do not have to write a ``main’’ program, as GAMOS provides a unique ``main’’ that serves to run any application.When you run the GAMOS ``main’’ it will load and call the components you want (geometry, physics, generator, hits building, histograms, …) by simply defining them in the input command file. Therefore to run your application simply type

gamos MY_INPUT_FILE

where MY_INPUT_FILE is a typical Geant4 macro file that includes Geant4 and GAMOS commands.

The minimum set of commands that you need are those to select a geometry, a physics list and a generator, to initialize Geant4 and to run N events. In this case your input file may look like this one:

/gamos/setParam GmGeometryFromText:FileName test.geom
/gamos/geometry GmGeometryFromText
/gamos/physicsList GmEMPhysics
/gamos/generator GmGenerator
/gamos/generator/addSingleParticleSource MY_SOURCE e- 1*MeV
/run/initialize
/run/beamOn 10

This will create a simple geometry, the one described in the file test.geom lying in the current directory or in the MY_GAMOS_DIR/data directory, set the physics as the low energy electromagnetic Geant4 physics and run 10 events with an electron of 1 MeV as primary particle.

You can then add any of the command described in this document, or any Geant4 command or any command you created yourself.

Beware that Geant4 is a state machine, and the list of available commands depends on the current state. The main state change is triggered by the /run/initialize command, which changes the state from G4State_PreInit to G4State_Idle. You may get a full list of the available commands at any moment with the command /control/manual.

Running an example in Windows

To run in Windows we recommend you to use the Graphical User Interface, that you can find at <MY_INSTALLATION_DIR>/GAMOS.6.2.0/GAMOSGUI.exe.

GAMOS Graphical User Interface

The first you should do is open an input file and then run it. Or alternatively you may create a new one. The list of buttons of this GUI is the following:

  • Open File: Open an existing input file

  • Run: run GAMOS with the input file in the screen (it is saved before run)

  • Open Log: open the log file of a GAMOS run (gamos.log in the same directory that the current input file

  • Open Error Log: open the error log file of a GAMOS run (gamos_error.log in the same directory that the current intput file

  • New File: create a new input file

  • Save File: save current input file using current name

  • Save File As: save current input file changing name

  • Select Font: select the font for input and log files

  • Help: open the pdf file of GAMOS User’s Guide

  • Exit: exit GUI

Compiling GAMOS

If you installed GAMOS as explained in the previous section, the compilation will be done automatically. Then you may run your application in GAMOS by writing your user commands without any need of compiling ever more, and therefore you do not need to read this section.

Only if you want to extend the GAMOS functionality by providing new code, you will have to follow the instructions in this section.

GAMOS uses the GNU make tool to manage the compilation and generation of executable files. It uses a set of configuration files based on the Geant4 ones. Therefore, if you are familiar to Geant4, you will find no difficulty in compiling GAMOS.

After untarring the installation file, you will have a directory called MY_GAMOS_DIR (substitute it by whatever name you used). This is the directory where the GAMOS code is, the rest are the external libraries used by GAMOS and the configuration utilities.

Before compiling, you have to define a few variables, mainly the location of the different external packages. All this is done by sourcing the file

source MY_GAMOS_DIR/config/confgamos.sh

or

source MY_GAMOS_DIR/config/confgamos.csh

To compile any directory of GAMOS, and all the directories below, you just have to go to that directory and type make. This will compile all the .cc files found in the src directory, build the library and the plug-in’s, and in the case of the directory GamosCore/GamosApplication it will also create the gamos executable. You may need to type the Linux command rehash to refresh your environmental variables in case there was no executable file before starting the compilation.

Compiling your new code

If you have created a new directory with your C++ code you have to compile it following the Geant4 way. The implementation files should have the suffix .cc and should be in a sub-directory called src. For the declaration files, you have a greater freedom; the Geant4 way is that they have the suffix .hh and lie in a sub-directory called include, but you can do it your own way (and after that, you have to be consistent in the GNUmakefile, as explained below).

You then have to build a GNUmakefile, that will steer the compilation and the building of the library and the plug-in’s, when you type the command make. For building it you may follow the examples in the GamosCore/GamosXXX directories. We take as example the file GamosCore/GamosGeometry/GNUmakefile:

name := GamosGeometry
G4TARGET := $(name)
G4EXLIB := true
.PHONY: all
all: lib
include $(GAMOSINSTALL)/config/binmake.gmk
include $(GAMOSINSTALL)/config/general.gmk
EXTRALIBS += -lGamosBase_Base -lGamosUtils -lGamosUserActionMgr -lGamosCore_GamosData_Distributions

Let’s go one by one through the lines: In the first one you define the name of your library:

name := GamosGeometry

The following two lines are used internally by the GAMOS scripts and are mandatory:

G4TARGET := $(name)
G4EXLIB := true

Then you define what you want to do when you type make:

.PHONY: all
all: lib

There are several possibilities:

  • lib Compile and build the library.

  • bin Build the executable. You will probably never need this, as GAMOS is based on dynamic loading and plug-in’s, so that there is only one GAMOS executable, which is built at installation.

The following two lines are needed for configuration

include $(GAMOSINSTALL)/config/binmake.gmk
include $(GAMOSINSTALL)/config/general.gmk

If you edit the file general.gmk, you will see that it is just including a different file for each package. Therefore, instead of using it, you may include all or only a subset of them if you do not need them all.

Finally, you define the GAMOS libraries that will be linked to yours, i.e. the libraries of each of the files that you have included in your code

For the external packages the set of libraries is fixed and defined in the configuration files

EXTRALIBS += -lGamosBase -lGamosUtils
-lGamosUserActionMgr -lGamosCore_GamosData_Distributions

If you have doubts about which GAMOS libraries to include, you may include them all, by including include $(GAMOSINSTALL)/config/gamos_libraries.gmk.

If you have built several levels of directories you may want to have the possibility of typing make at the top most directory to trigger the compilation of all the directories. To do this you just have to add a GNUmakefile at the top level directory similar to the one at $(GAMOSINSTALL)/source/GamosCore/GNUmakefile, that we reproduce here:

include $(GAMOSINSTALL)/config/architecture.gmk
SUBDIRS  = GamosUtils GamosBase GamosUserActionMgr GamosData
GamosAnalysis GamosGeometry GamosMovement GamosPhysics
GamosGenerator GamosSD GamosUtilsUA GamosReadDICOM
GamosScoring GamosRunManager GamosApplication
include $(GAMOSINSTALL)/config/globlib.gmk

You only have to change the line starting by SUBDIRS =, to list the name of your sub-directories.