Software tutorial at IFT

Introduction and overview

This page is meant as a recipe for the software day at IFT, March 20 2017. We have decided that this should take place on Monday, March 20 between 09.00 am and 3.00 pm at the Department of Physics and Technology (our usual meeting room in the 5th floor).

There are certain steps you need to take prior to the meeting. We do not wish to loose time on installation and configuration of the software needed. Thus, it is imperative that you come with your laptops which already have the following installed and configured properly:

1. ROOT installation
2. Geant 4 installation
3. Gate installation
4. DTC Toolkit for reconstruction

Agenda for the day is as follows:

1. An introduction to GATE macros, i.e. GATE input scripts
2. Setting up a simple simulation geometry in GATE using a proton bencil beam and a water phantom
3. Running short simulations
4. Examination of the GATE-output files

We think that the above mentioned mini introduction to GATE should take no longer than 1 – 1.5 hours. Rest of the day, we will focus on a more in-depth review of the analysis code written by Helge P.

1. Setting up a tracking calorimeter geometry in GATE
2. Running short simulations with the detector geometry
3. Using the results of the MC simulations, a short «hands-on» introduction to Helge P.’s analysis code written in the Root framework
4. A review of all the different modules in the above mentioned analysis code

The final goals of the day will be:

1. Setting up a GATE simulation of an example tracking calorimeter including geometry, material specifications and proton beam definition
2. Being able to work with the GATE output files (identifying primary protons, secondary particles, calculating deposited dose etc…)
3. Being able to run a complete analysis using the Root-analysis code written by Helge P.

As always, check the User guide and tutorial for the DTC Toolkit to find a Wiki-friendly guide.

GATE

Simulations of Preclinical and Clinical Scans in Emission Tomography, Transmission Tomography and Radiation Therapy

Geant4 is a C++ library, where an application / simulation is built by writing certain C++ classes (geometry, beam, scoring, output, physics), and compiling the binaries from where the simulations are run. Only certain modifications to the simulations can be made with the binaries, such as beam settings, certain physics settings as well as geometry objects pre-defined to be variable.

GATE is an application written for Geant4. It was originally meant for PET and SPECT uses, however it is very flexible so many different kinds of detectors can be designed. To run GATE, only macro files written in the Geant4 scripting language (with some GATE specific commands) are needed to build the geometry, scoring, physics and beam. The output is also defined in the macro files, either to ASCII files or to ROOT files.

In each simulation, the user has to:

1. define the scanner geometry
2. set up the physics processes
3. initialize the simulation
4. set up the detector model
5. define the source(s)
6. specify the data output format
7. start the acquisition

Introduction to GATE macros

Gate, just as GEANT4, is a program in which the user interface is based on scripts. To perform actions, the user must either enter commands in interactive mode, or build up macro files containing an ordered collection of commands.

Each command performs a particular function, and may require one or more parameters. The Gate commands are organized following a tree structure, with respect to the function they represent. For example, all geometry-control commands start with geometry, and they will all be found under the /geometry/ branch of the tree structure.

When Gate is run, the Idle> prompt appears. At this stage the command interpreter is active; i.e. all the Gate commands entered will be interpreted and processed on-line. All functions in Gate can be accessed to using command lines. The geometry of the system, the description of the radioactive source(s), the physical interactions considered, etc., can be parameterized using command lines, which are translated to the Gate kernel by the command interpreter. In this way, the simulation is defined one step at a time, and the actual construction of the geometry and definition of the simulation can be seen on-line. If the effect is not as expected, the user can decide to re-adjust the desired parameter by re-entering the appropriate command on-line. Although entering commands step by step can be useful when the user is experimenting with the software or when he/she is not sure how to construct the geometry, there remains a need for storing the set of commands that led to a successful simulation.

Macros are ASCII files (with '.mac' extension) in which each line contains a command or a comment. Commands are GEANT4 or Gate scripted commands; comments start with the character ' #'. Macros can be executed from within the command interpreter in Gate, or by passing it as a command-line parameter to Gate, or by calling it from another macro. A macro or set of macros must include all commands describing the different components of a simulation in the right order. Usually these components are visualization, definitions of volumes (geometry), systems, digitizer, physics, initialization, source, output and start. These steps are described in the next sections. A single simulation may be split into several macros, for instance one for the geometry, one for the physics, etc. Usually, there is a master macro which calls the more specific macros. Splitting macros allows the user to re-use one or more of these macros in several other simulations, and/or to organize the set of all commands. To execute a macro (mymacro.mac in this example) from the Linux prompt, just type :

Gate mymacro.mac 

To execute a macro from inside the Gate environment, type after the "Idle>" prompt:

Idle>/control/execute mymacro.mac 

And finally, to execute a macro from inside another macro, simply write in the master macro:

/control/execute mymacro.mac 

Setting up a simple simulation geometry in GATE using a pencil beam and a water phantom

Visualization

First we may want to set up a visualization engine to see what's going on. This is optional, and runs in batch mode should not be visualized! Here we use the opengl visualizer, but different kinds of visualization engines are discussed in the GATE Wiki / [[1]]

  /vis/open/OGL

Review of the analysis code by Helge Pettersen

A review of the different modeuls in the code

DISCLAIMED: Some of the materials have been copied from the GATE v7.2 User's guide: http://wiki.opengatecollaboration.org/index.php/Users_Guide_V7.2