| Geant4 User's Guide For Application Developers Getting Started with Geant4

2.9 How to Execute a Program

## 2.9.1 Introduction

A Geant4 application can be run either in

- `purely hard-coded` batch mode
- batch mode, but reading a macro of commands
- interactive mode, driven by command lines
- interactive mode via a Graphical User Interface

The last mode will be covered in Section 2.8. The first three modes are explained here.

## 2.9.2 'Hard-coded' Batch Mode

Below is an example of the main program for an application which will run in batch mode.

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

      // set mandatory initialization classes
      runManager->SetUserInitialization(new ExN01DetectorConstruction);
      runManager->SetUserInitialization(new ExN01PhysicsList);

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

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

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

      // job termination
      delete runManager;
      return 0;
    }
Source listing 2.9.1 An example of the `main()` routine for an application which will run in batch mode.

Even the number of events in the run is `frozen`. To change this number you must at least recompile `main()`.

## 2.9.3 Batch Mode with Macro File

Below is an example of the main program for an application which will run in batch mode, but reading a file of commands.

    int main(int argc,char** argv) {

       // Construct the default run manager
      G4RunManager * runManager = new G4RunManager;

      // set mandatory initialization classes
      runManager->SetUserInitialization(new MyDetectorConstruction);
      runManager->SetUserInitialization(new MyPhysicsList);

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

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

      //read a macro file of commands
      G4UImanager * UI = G4UImanager::getUIpointer();
      G4String command = "/control/execute ";
      G4String fileName = argv[1];
      UI->applyCommand(command+fileName);

      delete runManager;
      return 0;
    }
Source listing 2.9.2 An example of the `main()` routine for an application which will run in batch mode, but reading a file of commands.

This example will be executed with the command:

        > myProgram  run1.mac

where `myProgram` is the name of your executable and `run1.mac` is a macro of commands located in the current directory, which could look like:

    #
    # Macro file for "myProgram.cc"
    #
    # set verbose level for this run
    #
    /run/verbose      2
    /event/verbose    0
    /tracking/verbose 1
    #
    # Set the initial kinematic and run 100 events
    # electron 1 GeV to the direction (1.,0.,0.)
    #
    /gun/particle e-
    /gun/energy 1 GeV
    /run/beamOn 100
Source listing 2.9.3 A typical command macro.

Indeed, you can re-execute your program with different run conditions without recompiling anything.

Digression: | many G4 category of classes have a verbose flag which controls the level of 'verbosity'. Usually `verbose=0` means silent. For instance /run/verbose is for the RunManager /event/verbose is for the EventManager /tracking/verbose is for the TrackingManager ...etc...

## 2.9.4 Interactive Mode Driven by Command Lines

Below is an example of the main program for an application which will run interactively, waiting for command lines entered from the keyboard.

    int main(int argc,char** argv) {

      // Construct the default run manager
      G4RunManager * runManager = new G4RunManager;

      // set mandatory initialization classes
      runManager->SetUserInitialization(new MyDetectorConstruction);
      runManager->SetUserInitialization(new MyPhysicsList);

      // visualization manager
      G4VisManager* visManager = new G4VisExecutive;
      visManager->Initialize();

      // set user action classes
      runManager->SetUserAction(new MyPrimaryGeneratorAction);
      runManager->SetUserAction(new MyRunAction);
      runManager->SetUserAction(new MyEventAction);
      runManager->SetUserAction(new MySteppingAction);

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

      // Define UI terminal for interactive mode
      G4UIsession * session = new G4UIterminal;
      session->SessionStart();
      delete session;

      // job termination
      delete visManager;
      delete runManager;

      return 0;
    }
Source listing 2.9.4 An example of the `main()` routine for an application which will run interactively, waiting for commands from the keyboard.

This example will be executed with the command:

      > myProgram

where `myProgram` is the name of your executable.

The G4 kernel will prompt:

      Idle>

and you can start your session. An example session could be:

Create an empty scene ("world" is default):

      Idle> /vis/scene/create

Add a volume to the scene:

      Idle> /vis/scene/add/volume

Create a scene handler for a specific graphics system. Change the next line to choose another graphic system:

      Idle> /vis/sceneHandler/create OGLIX

Create a viewer:

      Idle> /vis/viewer/create

Draw the scene, etc.:

      Idle> /vis/scene/notifyHandlers
      Idle> /run/verbose      0
      Idle> /event/verbose    0
      Idle> /tracking/verbose 1
      Idle> /gun/particle mu+
      Idle> /gun/energy 10 GeV
      Idle> /run/beamOn 1
      Idle> /gun/particle proton
      Idle> /gun/energy 100 MeV
      Idle> /run/beamOn 3
      Idle> exit

For the meaning of the machine state `Idle`, see Section 3.4.2.

This mode is useful for running a few events in debug mode and visualizing them. Notice that the VisManager is created in the `main()`, and the visualization system is choosen via the command:

      /vis/sceneHandler/create OGLIX

## 2.9.5 General Case

Most of the examples in the `$G4INSTALL/examples/` directory have the following `main()`, which covers cases 2 and 3 above. Thus, the application can be run either in batch or interactive mode.

    int main(int argc,char** argv) {

      // Construct the default run manager
      G4RunManager * runManager = new G4RunManager;

      // set mandatory initialization classes
      N03DetectorConstruction* detector = new N03DetectorConstruction;
      runManager->SetUserInitialization(detector);
      runManager->SetUserInitialization(new N03PhysicsList);

    #ifdef G4VIS_USE
      // visualization manager
      G4VisManager* visManager = new G4VisExecutive;
      visManager->Initialize();
    #endif

      // set user action classes
      runManager->SetUserAction(new N03PrimaryGeneratorAction(detector));
      runManager->SetUserAction(new N03RunAction);
      runManager->SetUserAction(new N03EventAction);
      runManager->SetUserAction(new N03SteppingAction);

      // get the pointer to the User Interface manager
        G4UImanager* UI = G4UImanager::GetUIpointer();

      if (argc==1)   // Define UI terminal for interactive mode
        {
         G4UIsession * session = new G4UIterminal;
         UI->ApplyCommand("/control/execute prerunN03.mac");
         session->SessionStart();
         delete session;
        }
      else           // Batch mode
        {
         G4String command = "/control/execute ";
         G4String fileName = argv[1];
         UI->ApplyCommand(command+fileName);
        }

      // job termination
    #ifdef G4VIS_USE
      delete visManager;
    #endif
      delete runManager;

      return 0;
    }
Source listing 2.9.5 The typical `main()` routine from the examples directory.

Notice that the visualization system is under the control of the precompiler variable `G4VIS_USE`. Notice also that, in interactive mode, few intializations have been put in the macro `prerunN03.mac` which is executed before the session start.

     # Macro file for the initialization phase of "exampleN03.cc"
     #
     # Sets some default verbose flags
     # and initializes the graphics.
     #
     /control/verbose 2
     /control/saveHistory
     /run/verbose 2
     #
     /run/particle/dumpCutValues
     #
     # Create empty scene ("world" is default)
     /vis/scene/create
     #
     # Add volume to scene
     /vis/scene/add/volume
     #
     # Create a scene handler for a specific graphics system
     # Edit the next line(s) to choose another graphic system
     #
     #/vis/sceneHandler/create DAWNFILE
     /vis/sceneHandler/create OGLIX
     #
     # Create a viewer
     /vis/viewer/create
     #
     # Draw scene
     /vis/scene/notifyHandlers
     #
     # for drawing the tracks
     # if too many tracks cause core dump => storeTrajectory 0
     /tracking/storeTrajectory 1
     #/vis/scene/include/trajectories
Source listing 2.9.6 The `prerunN03.mac` macro.

Also, this example demonstrates that you can read and execute a macro interactively:

      Idle> /control/execute  mySubMacro.mac

About the authors