Editing General Geant4 Overview (section)

==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.