General Geant4 Overview

About This Page

This page is meant to briefly explain some features of Geant4 and related topics. Many of these topics are explained in depth elsewhere, and some external links are also provided that may be helpful.

Getting Started

At first glance a Geant4 program looks very sporadic and disorganized; However once a basic understanding of the program structure is developed the program becomes easier to navigate. A Geant4 program is made up of a collection of files in two folders, one under the program's name and the other under the program's name, then a hyphen, then build (<example>,<example-build>). There are several different types of files is these folders and they will be discussed later. To actually run a program, first it must be compiled. After compiling, the machine produces an executable file with the same name as the program (<example>.exe), which is actually run. This process is also discussed later.

Understanding the File System

There are two folders that contain all the files for a Geant4 program, one carries the program name (<example>) and one that carries the program's name hyphenated with build (<example>-build). I will call these the program folder and the build folder respectively from here on. When creating classes and other types of files it is important to know which of these folders should contain them.

The Program Folder (<example>)

All files in this folder get compiled, and if changes are made to any of them the program should be recompiled. There are typically two sub folders called src (meaning source) and include as well as some additional files found in the program folder.

src - This folder contains all the class files for the program except the main. These files are discussed in more detail later, but any additional classes should be added here.

include - This folder contains all the header files for the classes in the source folder. There should be a header for each source file created.

the main class - This file is the main class for a simulation. It should have the same name as the project (<example>.cc), and will not have an associated header file. The file will be discussed in greater detail later.

The Build Folder (<example>-build)

All files in this folder can be edited at any time without having to recompile. Any files not directly associated to the simulation (ROOT macros, data files, etc.) should be saved in this build folder. There is a sub folder called CMakeFiles that contains files necessary to the compiler, and they should not be edited or moved.

the executable file - After compilation, this file is created in the build folder. It cannot be read, but it will run the simulation.

input files - These files can be used to manipulate variables between runs. This technique is discussed in detail on another page. These files can have arbitrary names (<example>.ini), and multiple input files can be created for any project.

run macros - These files are used to run the simulation in batch mode. This technique is discussed in detail later. These files can have arbitrary names (<example>.mac), and multiple macros can be created for any project.

Compiling and Running a Simulation

After creating all the necessary files for a simulation are created, the next step to running the simulation is to compile the program. To start, open a terminal window and navigate to the build folder.

Compiling the program

First, navigate to the build folder. To compile the program type the command "make". Some output should pop up in the window as the computer compiles. Be aware that some error messages may appear if the compiler encounters a bug. If this happens, the bugs must be fixed and then try to compile again. The compiler will only recompile files you have changed since the last attempt, or files it couldn't compile because of an error. If the compile is successful an executable file is produced in the build folder. If you wish to erase the executable file after compiling simply type the command "make clean".

Running through the GUI

To run the simulation with the visualization package, first open a terminal window and navigate to the build folder. Next run the executable file. To do this type the command "./<example>" with your program name in place of the example here. The visualization window will then pop up. At the bottom of the window there is an input box where commands can be typed. To run a simulation, type the command "run/beamOn <number>". The number in this command will be the number of events to run.

Running in batch mode

To run the simulation in batch mode (without visualization), first open a terminal window and navigate to the build folder. Next run the executable file with an appropriate run macro. To do this type the command "./<example> <exampleMacro>.mac" where the example is the name of the program and exampleMacro is the name of the macro to be run.

Geant4 Basics

Geant4 is highly adaptable, so what is presented here and throughout this wiki should be considered as a starting point and tool for understanding how a program works, and not as an exhaustive guide. The easiest way to create an appropriate simulation is to find an example program similar to the desired program and adapt it, instead of trying to start fresh. Below are some basic elements of any Geant4 program, and some basic concepts used commonly in any program.

Required Files to Run a Simulation

There are several basic source files necessary to have a functional program. They should all be saved in the program folder in the src sub folder, with the exception of the main, which should be saved in the program folder. Below are listed these necessary files, with a brief description of their role to the program.

The Main

This is the primary driver of the program. It will call the various other elements of the program.

Detector Construction

This is where the environment and the objects in it get defined. There are two required elements for any simulation: the world and the envelope. These two parts can be thought of as the containers that then hold the objects of a particular simulation. The objects need to be built as combinations of various volumes. There are three basic types of volumes: solid, logical, and physical volumes. To build your environment, you will have to create and combine as many of these different volumes as necessary.

Primary Generator Action

This is where the particles that will be studied get defined. This sounds like a simple task, but this file can be fairly complex, usually because there typically is some distribution that will dictate the particle's energy, direction of motion, etc. A simple algorithm to do this is discussed on another page.

Run Action

This file governs actions that take place during each run. Typically this is where an NTuple is created and data is saved. An explanation of a run comes later. A discussion of data collection and NTuple use can be found on another page.

Event Action

This file governs actions that take place during each event. An explanation of an event comes later.

Stepping Action

This file governs actions that take place during each step. An explanation of a step comes later.

Runs, Events, and Steps

Geant4 simulations are broken into three levels runs, events, and steps. A run is a complete simulation, as in each time you run the program. Tasks executed at this level happen once per execution of the program. An event is the level below a run. When you use the run/beamOn command, your actually giving the program the number of events to execute after the command. An event is fairly flexible, but often it is a single particle being shot. The smallest level is a step. Each event is broken into a series of steps. Steps can be a certain amount of time passing, entering or exiting a volume, or a particle decaying. It is important to note that variables created in one level must be included in the others to be seen. This is done by including (#include "<example>.hh") the header file of the other class that holds the variable that needs to be used. Also, the variable in the other class must be public, or getters and setters must be used. Understanding at what level specific tasks should be handled is essential to designing a properly functioning program, so be sure to consider these concepts when deciding how to code your simulation.

Handling Data

With any simulation you want to record and access data produced during the simulation. This is done primarily by creating an Ntuple, which is saved at the end of the simulation as a ROOT file.

Capturing data during simulation

The easiest way to record data from a simulation for later analysis is by use of an Ntuple. This is a built in function of the analysis manager class, which is used throughout a Geant4 in other ways. Typically the Ntuple is created in the RunAction file, in the constructor. This ensures that one Ntuple is created per run, and because the RunAction header file is included in almost all other files the Ntuple is accessable almost everywhere else. A simple example of the creation:

G4AnalysisManager* analysisManager = G4AnalysisManager::Instance();

analysisManager->CreateNtuple("<fileName>", "<NtupleName>");

//column of integers
analysisManager->CreateNtupleIColumn("<name>");	//column 0

//column of doubles
analysisManager->CreateNtupleDColumn("<name>");	//column 1

//column of floats
analysisManager->CreateNtupleFColumn("<name>");	//column 2

An Ntuple can hold as many columns as desired, and each column can be different size. Note the columns are be type-specific. After creating the desired columns, be sure to finish the Ntuple:

analysisManager->FinishNtuple();

To fill the columns:

G4AnalysisManager* analysisManager = G4AnalysisManager::Instance();
analysisManager->FillNtupleDColumn(<columnNumber>,<valueToBeSaved>);

The first line is necessary to get the analysis manager that is created in another class. Be sure to use the appropriate column type and number, which is established when the column was created. Also remember to put this in the appropriate file when trying to save data throughout a simulation. For example, if you wish to save the energy of the particle throughout the simulation, it would be best to save the value during each step, and thus the line should be somewhere in the stepping action class.

At the end of the run, the Ntuple will be saved as a ROOT file (<example>.root) with the name specified in the constructor. This file requires the use of the ROOT package to read and manipulate the data contained within.

ROOT file basics

Writing ROOT macros is an entire subject to itself, but here some basics of accessing and extracting data in a ROOT macro are addressed.

First, the file to be read must be identified and opened:

TFile *file = TFile::Open(<fileName>);

If reading multiple files, looping and using the form command may be beneficial. Next create a TTree by casting the file. Create a TTree for each column you wish to read:

TTree *tree = (TTree*)file->Get(<filename>);

Next, create a variable which will hold the value once ROOT reads it, and set the branch address to that variable:

Double_t holder;
tree->SetBranchAddress("<nameOfNtupleColumn>",&holder);

Note that the holder must be the same type as the values in the column, or must be casted appropriately. Also note that the column name is defined in the Geant4 program, when the column is created. Next the program should read through the variables, which is almost always done in a loop. Below is an example that simply saves the values into an array:

Int_t numOfEntries = (Int_t)t->GetEntries();
Double_t array[numOfEntries];
for(Int_t i=0;i<numOfEntries;i++)
{
     tree->GetEntry(i);
     array[i] = holder;
}

Note that when the tree is told to get a entry, the value is inserted into the holder: The value is not returned by the GetEntry function.

As always, don't forget to close the file once finished reading values:

file->Close();

Depending upon how you wish to use the data the macro may run in almost an infinite number of ways, but the commands above are the basic ones used to read data from a ROOT file.