4.3 The Main Program

Table of Contents

Creating the run manager

The main program is the starting point of every Geant4 application. It is a normal C++ main() function that creates and connects the high level Geant4 objects, then hands control to Geant4 to run the simulation.

The central object you create first is the run manager. In modern Geant4 you typically use the generic run manager class G4RunManager for sequential applications. For multithreaded applications there is a dedicated multithreaded run manager, but that topic is covered in the multithreading chapter, so here we focus on the basic case.

A minimal skeleton of main() using the run manager looks like:

cpp

#include "G4RunManager.hh"
#include "G4UImanager.hh"
#include "DetectorConstruction.hh"
#include "PhysicsList.hh"
#include "ActionInitialization.hh"
int main(int argc, char** argv)
{
  // 1. Create the run manager
  auto* runManager = new G4RunManager();
  // 2. User initializations will be attached here
  //    (geometry, physics list, actions)
  // 3. Initialize and start the simulation
  //    ...
  delete runManager;
  return 0;
}

The run manager owns and controls the major parts of the simulation. It calls your user initialization classes, creates the geometry and physics, and manages the event loop. You create it once, at the beginning of main(), and delete it at the end after all simulation work is complete.

At this stage, the run manager still does not know anything about your detector or physics. That connection is made by registering your user initialization classes, which is described in the dedicated chapter on user initialization classes. In the main program, you only call the registration functions on the run manager, for example:

cpp

runManager->SetUserInitialization(new DetectorConstruction);
runManager->SetUserInitialization(new PhysicsList);
runManager->SetUserInitialization(new ActionInitialization);

These calls tell the run manager which user classes to use for geometry, physics, and actions. Geant4 will later invoke them at the right time during initialization and during each run.

The run manager must be created exactly once and must be configured with all required user initialization classes before you call its initialization method. Changing geometry or physics after initialization requires explicit reinitialization and is not part of a minimal beginner main program.

Initializing Geant4

Once the run manager exists and has been given your user initialization classes, you need to initialize the simulation kernel. In a minimal main program, this is done by a single call:

cpp

runManager->Initialize();

This triggers a series of actions inside Geant4. The run manager calls your detector construction class to build the geometry, constructs the world volume, sets up the physics list, and prepares your user action classes. It also loads necessary physics data and prepares the tracking and stepping infrastructure.

The initialization step is separate from construction of the run manager because you often want to attach all user initialization classes before any expensive work occurs. After Initialize() returns, the simulation is ready to process events.

In some applications you will see an extra step where visualization and user interface components are created before or after Initialize(). The typical pattern is:

cpp

// Create visualization manager (optional, for graphics)
auto* visManager = new G4VisExecutive();
visManager->Initialize();
// Initialize the run manager and kernel
runManager->Initialize();
// Get the UI manager to execute macro commands
auto* uiManager = G4UImanager::GetUIpointer();

The exact order of visualization initialization can vary, but the key point for the main program is that you must not start processing events before the run manager is initialized.

If you are running in interactive mode, you usually also create a UI session around the initialization stage. A common pattern is to check whether a macro file was passed on the command line. If not, you start an interactive session that will be described in more depth in the macro and visualization chapters. In minimal form:

cpp

#ifdef G4UI_USE
#include "G4UIExecutive.hh"
#endif
int main(int argc, char** argv)
{
  auto* runManager = new G4RunManager();
  // Attach user initializations here
  // ...
  runManager->Initialize();
#ifdef G4UI_USE
  G4UIExecutive* ui = nullptr;
  if (argc == 1) {
    ui = new G4UIExecutive(argc, argv);
  }
#endif
  // Later, you will start the UI or execute macros
  delete runManager;
  return 0;
}

Always call runManager->Initialize() before /run/beamOn or any commands that start a run. If you forget initialization, Geant4 will not have a valid geometry or physics configuration, and your simulation will fail or behave unpredictably.

Starting a simulation

After the run manager has been initialized, the simulation is ready to process events. In Geant4, starting a simulation means instructing the run manager to begin a run and simulate a certain number of events. There are two common ways to do this from the main program.

The first way is to call the C++ method directly:

cpp

runManager->BeamOn(1000);

This simulates 1000 events in a single run using whatever primary generator and configuration you have defined. This approach is simple but gives you less flexibility for interactive control, and it is mostly used in small, fixed simulations or in tests.

The second way, which is the standard for most applications, is to use macro commands through the Geant4 user interface system. From the main program, you obtain the G4UImanager pointer and ask it to execute strings that correspond to UI commands:

cpp

auto* uiManager = G4UImanager::GetUIpointer();
// Initialize run (if not already done by your logic or macros)
uiManager->ApplyCommand("/run/initialize");
// Start a run of 1000 events
uiManager->ApplyCommand("/run/beamOn 1000");

In practice, you normally collect these commands inside macro files that you can modify without recompiling. Your main program then simply chooses which macro to execute.

There are two typical modes your main program supports.

In batch mode, you provide a macro file on the command line, and the main program executes it without interactive input:

cpp

if (argc > 1) {
  G4String command = "/control/execute ";
  G4String macroFile = argv[1];
  uiManager->ApplyCommand(command + macroFile);
}

The macro file might contain commands such as:

/run/initialize
/run/beamOn 10000

In interactive mode, with no macro on the command line, you start a UI session after basic initialization and optionally execute a default visualization macro:

cpp

if (ui) {
  uiManager->ApplyCommand("/control/execute vis.mac");
  ui->SessionStart();
  delete ui;
}

Inside vis.mac or other macros, you will set up visualization, primary particles, and then start the simulation with /run/beamOn. The main program simply opens the session and lets the user drive the simulation through commands.

At the end of the simulation, either in batch or interactive mode, you must clean up resources created in main(). Typically you delete the visualization manager, then the run manager:

cpp

delete visManager;
delete runManager;

Geant4 will automatically delete objects that the run manager owns, such as the detector construction and physics list.

A run begins only when BeamOn is called, either in C++ or via the /run/beamOn UI command. Make sure that the run manager is fully initialized and any necessary macro configuration has been applied before you start BeamOn, otherwise the events will not use your intended geometry, physics, or source settings.

4.3 The Main Program

Creating the run manager

Initializing Geant4

Starting a simulation

Comments

Where to Move