Chapter 2. Getting Started with Geant4 - Running a Simple Example

2.1. How to Define the main() Program

2.1.1. A Sample `main()` Method

The contents of main() will vary according to the needs of a given simulation application and therefore must be supplied by the user. The Geant4 toolkit does not provide a main() method, but a sample is provided here as a guide to the beginning user. Example 2.1 is the simplest example of main() required to build a simulation program.

Example 2.1. Simplest example of main()

 #include "G4RunManager.hh"
 #include "G4UImanager.hh"

 #include "ExG4DetectorConstruction01.hh"
 #include "ExG4PhysicsList00.hh"
 #include "ExG4ActionInitialization01.hh"

 int main()
 {
   // construct the default run manager
   G4RunManager* runManager = new G4RunManager;

   // set mandatory initialization classes
   runManager->SetUserInitialization(new ExG4DetectorConstruction01);
   runManager->SetUserInitialization(new ExG4PhysicsList00);
   runManager->SetUserInitialization(new ExG4ActionInitialization01);

   // initialize G4 kernel
   runManager->Initialize();

   // get the pointer to the UI manager and set verbosities
   G4UImanager* UI = G4UImanager::GetUIpointer();
   UI->ApplyCommand("/run/verbose 1");
   UI->ApplyCommand("/event/verbose 1");
   UI->ApplyCommand("/tracking/verbose 1");

   // start a run
   int numberOfEvent = 3;
   runManager->BeamOn(numberOfEvent);

   // job termination
   delete runManager;
   return 0;
 }

The main() method is implemented by two toolkit classes, G4RunManager and G4UImanager, and three classes, ExG4DetectorConstruction01, ExG4PhysicsList00 and ExG4ActionInitialization01, which are derived from toolkit classes. Each of these are explained in the following sections.

2.1.2. `G4RunManager`

The first thing main() must do is create an instance of the G4RunManager class. This is the only manager class in the Geant4 kernel which should be explicitly constructed in the user's main(). It controls the flow of the program and manages the event loop(s) within a run. If the user wants to make the simulation code multi-threaded, G4MTRunManager should be instantiated instead of G4RunManager.

When G4RunManager is created, the other major manager classes are also created. They are deleted automatically when G4RunManager is deleted. The run manager is also responsible for managing initialization procedures, including methods in the user initialization classes. Through these the run manager must be given all the information necessary to build and run the simulation, including

how the detector should be constructed,
all the particles and all the physics processes to be simulated,
how the primary particle(s) in an event should be produced, and
any additional requirements of the simulation.

In the sample main() the lines

  runManager->SetUserInitialization(new ExG4DetectorConstruction01);
  runManager->SetUserInitialization(new ExG4PhysicsList00);
  runManager->SetUserInitialization(new ExG4ActionInitialization01);

create objects which specify the detector geometry, physics processes and primary particle, respectively, and pass their pointers to the run manager. ExG4DetectorConstruction01 is an example of a user initialization class which is derived from G4VUserDetectorConstruction. This is where the user describes the entire detector setup, including

its geometry,
the materials used in its construction,
a definition of its sensitive regions and
the readout schemes of the sensitive regions.

Similarly ExG4PhysicsList01 is derived from G4VUserPhysicsList and requires the user to define

the particles to be used in the simulation,
all the physics processes to be simulated.

User can also override the default implementation for

the range cuts for these particles and

Also ExG4ActionInitialization01 is derived from G4VUserActionInitialization and requires the user to define

so-called user action classes (see next section) that are invoked during the simulation,
which includes one mandatory user action to define the primary particles.

The next instruction

  runManager->Initialize();

performs the detector construction, creates the physics processes, calculates cross sections and otherwise sets up the run. The final run manager method in main()

  int numberOfEvent = 3;
  runManager->beamOn(numberOfEvent);

begins a run of three sequentially processed events. The beamOn() method may be invoked any number of times within main() with each invocation representing a separate run. Once a run has begun neither the detector setup nor the physics processes may be changed. They may be changed between runs, however, as described in Section 3.4.4. More information on G4RunManager in general is found in Section 3.4.

As mentioned above, other manager classes are created when the run manager is created. One of these is the user interface manager, G4UImanager. In main() a pointer to the interface manager must be obtained

  G4UImanager* UI = G4UImanager::getUIpointer();

in order for the user to issue commands to the program. In the present example the applyCommand() method is called three times to direct the program to print out information at the run, event and tracking levels of simulation. A wide range of commands is available which allows the user detailed control of the simulation. A list of these commands can be found in Section 7.1.

2.1.3. User Initialization and Action Classes

2.1.3.1. User Classes

There are two kinds of user classes, user initialization classes and user action classes. User initialization classes are used during the initialization phase, while user action classes are used during the run. User initialization classes should be directly set to G4RunManager through SetUserInitialization() method, while user action classes should de defined in G4VUserActionInitialization class.

2.1.3.2. User Initialization Classes

All three user initialization classes are mandatory. They must be derived from the abstract base classes provided by Geant4:

G4VUserDetectorConstruction
G4VUserPhysicsList
G4VUserActionInitialization

Geant4 does not provide default behavior for these classes. G4RunManager checks for the existence of these mandatory classes when the Initialize() and BeamOn() methods are invoked.

As mentioned in the previous section, G4VUserDetectorConstruction requires the user to define the detector and G4VUserPhysicsList requires the user to define the physics. Detector definition will be discussed in Sections Section 2.2 and Section 2.3. Physics definition will be discussed in Sections Section 2.4 and Section 2.5. The user action G4VUserPrimaryGeneratorAction requires that the initial event state be defined. Primary event generation will be discussed in Section 2.8.

G4VUserActionInitialization should include at least one mandatory user action class G4VUserPrimaryGeneratorAction. All user action classes are descrived in the next section.

Example 2.2. Simplest example of ExG4ActionInitialization01

 #include "ExG4ActionInitialization01.hh"
 #include "ExG4PrimaryGeneratorAction01.hh"

 void ExG4ActionInitialization01::Build() const
 {
   SetUserAction(new ExG4PrimaryGeneratorAction01);
 }

2.1.3.3. User Action Classes

G4VUserPrimaryGeneratorAction is a mandatory class the user has to provide. It creates an instance of a primary particle generator. ExG4PrimaryGeneratorAction01 is an example of a user action class which is derived from G4VUserPrimaryGeneratorAction. In this class the user must describe the initial state of the primary event. This class has a public virtual method named GeneratePrimaries() which will be invoked at the beginning of each event. Details will be given in Section 2.6. Note that Geant4 does not provide any default behavior for generating a primary event.

Geant4 provides additional five user hook classes:

G4UserRunAction
G4UserEventAction
G4UserStackingAction
G4UserTrackingAction
G4UserSteppingAction

These optional user action classes have several virtual methods which allow the specification of additional procedures at all levels of the simulation application. Details of the user initialization and action classes are provided in Chapter 6.

2.1.4. `G4UImanager` and UI CommandSubmission

Geant4 provides a category named intercoms. G4UImanager is the manager class of this category. Using the functionalities of this category, you can invoke set methods of class objects of which you do not know the pointer. In Example 2.3, the verbosities of various Geant4 manager classes are set. Detailed mechanism description and usage of intercoms will be given in the next chapter, with a list of available commands. Command submission can be done all through the application.

Example 2.3. An example of main() using interactive terminal and visualization. Code modified from the previous example are shown in blue.

 #include "G4RunManager.hh"
 #include "G4UImanager.hh"

#ifdef G4UI_USE
 #include "G4VisExecutive.hh"
#endif


 #include "ExG4DetectorConstruction01.hh"
 #include "ExG4PhysicsList00.hh"
 #include "ExG4PrimaryGeneratorAction01.hh"

 int main()
 {
   // construct the default run manager
   G4RunManager* runManager = new G4RunManager;

   // set mandatory initialization classes
   runManager->SetUserInitialization(new ExG4DetectorConstruction01);
   runManager->SetUserInitialization(new ExG4PhysicsList00);

   // set mandatory user action class
   runManager->SetUserAction(new ExG4PrimaryGeneratorAction01);

   // initialize G4 kernel
   runManager->Initialize();

  // Get the pointer to the User Interface manager
  G4UImanager* UImanager = G4UImanager::GetUIpointer();


  if ( argc == 1 ) {
    // interactive mode : define UI session
#ifdef G4UI_USE
    G4UIExecutive* ui = new G4UIExecutive(argc, argv);
    UImanager->ApplyCommand("/control/execute init.mac"); 
    ui->SessionStart();
    delete ui;
#endif
  }
  else {
    // batch mode
    G4String command = "/control/execute ";
    G4String fileName = argv[1];
    UImanager->ApplyCommand(command+fileName);
  }


   // job termination
   delete runManager;
   return 0;
 }

2.1.5. `G4cout` and `G4cerr`

Although not yet included in the above examples, output streams will be needed. G4cout and G4cerr are iostream objects defined by Geant4. The usage of these objects is exactly the same as the ordinary cout and cerr, except that the output streams will be handled by G4UImanager. Thus, output strings may be displayed on another window or stored in a file. Manipulation of these output streams will be described in Section 7.2.4. These objects should be used instead of the ordinary cout and cerr.


1.2. How to use this manual		2.2. How to Define a Detector Geometry