How to Execute a Program

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 How to Set Up an Interactive Session. The first three modes are explained here.

‘Hard-coded’ Batch Mode

Below is a modified main program of the basic example B1 to represent an application which will run in batch mode.

Listing 19 An example of the main() routine for an application which will run in batch mode.
using namespace B1;

int main()
{
  // Construct the default run manager
  auto runManager = G4RunManagerFactory::CreateRunManager();

  // Set mandatory initialization classes
  runManager->SetUserInitialization(new DetectorConstruction);
  runManager->SetUserInitialization(new QGSP_BIC_EMY);
  runManager->SetUserInitialization(new ActionInitialization);

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

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

  // job termination
  delete runManager;
  return 0;
}

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

Batch Mode with Macro File

Below is a modified main program of the basic example B1 to represent an application which will run in batch mode, but reading a file of commands.

Listing 20 An example of the main() routine for an application which will run in batch mode, but reading a file of commands.
using namespace B1;

int main(int argc,char** argv)
{
  // Construct the default run manager
  auto runManager = G4RunManagerFactory::CreateRunManager();

  // Set mandatory initialization classes
  runManager->SetUserInitialization(new DetectorConstruction);
  runManager->SetUserInitialization(new QGSP_BIC_EMY);
  runManager->SetUserInitialization(new ActionInitialization);

  // 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);

  // job termination
  delete runManager;
  return 0;
}

This example will be executed with the command:

> exampleB1  run1.mac

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

Listing 21 A typical command macro.
#
# Macro file for myProgram
#
# 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

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

Note

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…

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.

Listing 22 An example of the main() routine for an application which will run interactively, waiting for commands from the keyboard.
using namespace B1;

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

  // Set mandatory initialization classes
  runManager->SetUserInitialization(new DetectorConstruction);
  runManager->SetUserInitialization(new QGSP_BIC_EMY);
  runManager->SetUserInitialization(new ActionInitialization);

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

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

  // job termination
  delete runManager;
  return 0;
}

This example will be executed with the command:

> exampleB1

where exampleB1 is the name of the executable.

The G4 kernel will prompt:

Idle>

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

Run 5 events:

Idle> /run/beamOn 5

Switch on tracking/verbose and run one more event:

Idle> /tracking/verbose 1
Idle> /run/beamOn 1

Change primary particle type an run more events:

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 as a state machine.

This mode is useful for running a few events in debug mode and visualizing them. How to include visualization will be shown in the next, general case, example.

General Case

All basic examples in the examples/basic subdirectory of the Geant4 source distribution have the following main() structure. The application can be run either in batch or interactive mode.

Listing 23 The typical main() routine from the examples directory.
using namespace B1;

int main(int argc,char** argv)
{
  // Detect interactive mode (if no arguments) and define UI session
  G4UIExecutive* ui = 0;
  if ( argc == 1 ) {
    ui = new G4UIExecutive(argc, argv);
  }

  // Optionally: choose a different Random engine...
  // G4Random::setTheEngine(new CLHEP::MTwistEngine);

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

  // Set mandatory initialization classes
  //
  // Detector construction
  runManager->SetUserInitialization(new DetectorConstruction());

  // Physics list
  G4VModularPhysicsList* physicsList = new QBBC;
  physicsList->SetVerboseLevel(1);
  runManager->SetUserInitialization(physicsList);

  // User action initialization
  runManager->SetUserInitialization(new ActionInitialization());

  // Initialize visualization
  G4VisManager* visManager = new G4VisExecutive;
  // G4VisExecutive can take a verbosity argument - see /vis/verbose guidance.
  // G4VisManager* visManager = new G4VisExecutive("Quiet");
  visManager->Initialize();

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

  // Process macro or start UI session
  if ( ! ui ) {
    // batch mode
    G4String command = "/control/execute ";
    G4String fileName = argv[1];
    UImanager->ApplyCommand(command+fileName);
  } else {
    // interactive mode
    UImanager->ApplyCommand("/control/execute init_vis.mac");
    ui->SessionStart();
    delete ui;
  }

  // Job termination
  // Free the store: user actions, physics_list and detector_description are
  // owned and deleted by the run manager, so they should not be deleted
  // in the main() program !

  delete visManager;
  delete runManager;
}
Listing 24 The init.mac macro
# Macro file for the initialization phase of example B1
# when running in interactive mode without visualization
#
# Set some default verbose
/control/verbose 2
/control/saveHistory
/run/verbose 2

The init_vis.mac macro has just added a line with a call to vis.mac:

# Macro file for the initialization phase of example B1
# when running in interactive mode with visualization
#
# Set some default verbose
#
/control/verbose 2
/control/saveHistory
/run/verbose 2
#
# Visualization setting
/control/execute vis.mac

The vis.mac macro defines a minimal setting for drawing volumes and trajectories accumulated for all events of a given run:

# Macro file for the visualization setting in the initialization phase
# of the B1 example when running in interactive mode
#
#
# Use this open statement to create an OpenGL view:
/vis/open OGL 600x600-0+0
#
# Draw geometry:
/vis/drawVolume
#
# Specify view angle:
/vis/viewer/set/viewpointThetaPhi 90. 180.
#
# Draw smooth trajectories at end of event, showing trajectory points
# as markers 2 pixels wide:
/vis/scene/add/trajectories smooth
#
# To superimpose all of the events from a given run:
/vis/scene/endOfEventAction accumulate
#
# Re-establish auto refreshing and verbosity:
/vis/viewer/set/autoRefresh true
/vis/verbose warnings
#
# For file-based drivers, use this to create an empty detector view:
#/vis/viewer/flush

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

Idle> /control/execute  mySubMacro.mac