30.10. Using Geant4 Verbose Output

Table of Contents

Understanding Geant4 Verbose Output

Geant4 provides several built in verbosity controls that print detailed text to the terminal while a simulation runs. For beginners, this output is one of the most useful tools for understanding what is happening internally and for diagnosing many common problems without a debugger.

Verbose output does not fix issues by itself, but it gives you a step by step view of runs, events, tracks, and steps, and also of the geometry and physics that are being used. You can enable and tune this output almost entirely with macro commands, without recompiling your application.

Verbosity Levels and Where They Apply

Most Geant4 components have a verbosity level that controls how much text they print. In general, a level of 0 means silent, and increasing numbers produce more information.

There are several separate verbosity controls that you will see often:

Table: Typical verbosity controls

Area	Controlled by	Typical range
Run management	`/run/verbose`	0 to 2
Event processing	`/event/verbose`	0 to 2
Tracking, stepping	`/tracking/verbose` and `/process/verbose`	0 to 3 or 4
Geometry / navigator	`/geometry/navigator/verbose`	0 to 2
Physics processes	`/process/verbose` and process specific	0 to 3 or 4
Stepping manager	`/tracking/verbose`	0 to 3
User code (optional)	`SetVerboseLevel()` in C++	0 to custom

Higher levels produce more detailed output, but can slow the simulation significantly and produce very large log files. For interactive debugging, it is best to start with low levels and increase them for only a few events.

Always restrict high verbosity to a small number of events and single threaded runs. Large verbose logs with many threads can be extremely slow and difficult to interpret.

Enabling Verbose Output with Macros

Verbose output is usually enabled with macro commands before you start a run. You can place these commands in a .mac file or type them in an interactive Geant4 session.

A typical debugging macro snippet might look like:

tcl

/run/verbose 1
/event/verbose 1
/tracking/verbose 2
/process/verbose 1
/run/initialize
/run/beamOn 1

The order is important. Set verbosity before /run/beamOn. You can change verbosity between runs without recompilation.

The meaning of the most common commands is:

/run/verbose n controls messages printed when runs are initialized and terminated, and sometimes when geometry or physics is built.

/event/verbose n controls messages at the beginning and end of each event, and, for higher values, may list basic information about primary particles and statistics.

/tracking/verbose n controls messages for each track and each step within a track. This is one of the most important tools for understanding particle transport.

/process/verbose n prints information from physics processes when they are invoked or when they propose interaction lengths and step limits.

If you only want to inspect a single event or a small batch, use:

tcl

/run/beamOn 1

tcl

/run/beamOn 10

With higher verbosity levels, even a few events can produce many pages of output.

Reading Tracking and Stepping Verbose Output

The tracking and stepping verbose output shows how a particle moves through your geometry, which processes act, and where energy is deposited. This is often the fastest way to see why no energy reaches a detector, or why a particle stops earlier than expected.

After setting:

tcl

/tracking/verbose 2
/process/verbose 1

and running a single event, you might see output similar to:

text

*******************************************************
* G4Track Information
*   Particle = gamma, track ID = 1, parent ID = 0
*   Kinetic energy = 1 MeV
*   Position = (0, 0, -5 cm)
*   Direction = (0, 0, 1)
*******************************************************
Step#   X(mm)   Y(mm)   Z(mm)   KinE(MeV)  dE(MeV)  StepLeng(mm)  Proc
 0      0.0     0.0   -50.0     1.0000     0.0000   0.0           initStep
 1      0.0     0.0   -10.0     1.0000     0.0000  40.0           Transportation
 2      0.0     0.0     0.0     0.8000     0.2000   10.0          Compt
 3      0.0     0.0     5.0     0.0000     0.8000   5.0           PhotoElectric

Although exact formatting can differ between Geant4 versions and verbosity levels, the essential columns are:

Step number counts the steps of the current track.

Position $(X, Y, Z)$ gives the global coordinates of the pre step point in millimeters.

Kinetic energy is the energy of the particle at the pre step point.

$dE$ is the energy lost during this step. This includes energy deposited in materials and energy given to secondary particles.

Step length is the physical distance between pre and post step points.

Process is the process that defined the step boundary. It can be Transportation, an electromagnetic or hadronic process, or a special process such as UserLimit.

To debug geometry and physics, focus on:

Whether the particle reaches the expected region. If the coordinates never enter the detector coordinates, your geometry placement or world size may be wrong.

Where Transportation steps occur. Very long transportation steps can indicate large empty regions, and very short transportation steps can indicate small volumes or navigation problems.

Which physical process kills the track. If the track stops with a process you did not expect, your physics list or cuts may need adjustment.

If the step table shows no energy loss (dE = 0) in a volume that should be active, check that:

The material is set correctly.
The physics list includes the relevant processes.
A sensitive detector is properly attached to the logical volume.

Using Verbose Output for Geometry and Navigation

Geometry and navigation verbose output helps when particles appear to miss volumes, when you suspect overlap problems, or when navigation enters the wrong volume.

Geant4 provides specialized commands for this:

tcl

/geometry/navigator/verbose 1
/geometry/navigator/check_mode true

/geometry/navigator/verbose 1 prints messages as the navigator locates volumes and crosses boundaries.

/geometry/navigator/check_mode true enables additional checks to detect when the navigator becomes stuck or when a step cannot be completed correctly.

To inspect geometry without running physics, you can also use:

tcl

/geometry/test/run

which sends a test particle through the geometry and prints navigation information. The exact commands and options can depend on the Geant4 version, but the idea is always to ask the navigator component to report its decisions.

From the navigator verbose output, you can learn:

Which volume is currently containing the track.

Which daughter volume is entered or left at each step.

Whether the navigator detects that the point is outside any volume, which can indicate unbounded geometry or wrong placements.

If you see repeated messages about "stuck tracks" or repeated attempts to relocate the same point, this suggests overlapping or touching volumes that are not modeled correctly. In that case, combine navigator verbosity with the geometry overlap checking tools described in the geometry debugging chapter.

If navigator verbose output shows the track repeatedly bouncing at a boundary or failing to leave a volume, suspect overlapping volumes or ill defined placements. Fixing geometry issues usually requires correcting the solid sizes or placement transforms, not changing physics.

Physics Process Verbosity

The process manager in Geant4 decides which process limits the step, how much energy is lost, and which secondary particles are created. When results look physically wrong, it can help to see which processes are being considered.

You can enable process verbosity with:

tcl

/process/verbose 1

At level 1, for each step, Geant4 prints the process that defined the step length, and sometimes reports secondaries created. Higher levels can list the table of proposed interaction lengths and the mean free paths, but they can generate very large output.

For electromagnetic or hadronic physics debugging, you may also find process specific verbosity useful, for example for some processes that provide SetVerboseLevel methods in C++. However, in a beginner course, it is usually enough to use /process/verbose.

When reading process verbose output, look for:

Whether the expected process appears at all for your particle and material. If you never see Compt for gammas in matter, for example, check that the electromagnetic physics is enabled.

Whether step lengths are being limited by a process you did not expect, such as StepLimiter or UserSpecialCuts. This may indicate that cuts or user limits are too strong.

The energy and position at which a process starts to act. If a process acts at unphysical energies, check your physics list selection.

Run and Event Verbose Output

Run and event level verbosity is less detailed, but useful for a quick consistency check. They tell you how many events are processed, whether the random seeds are set, and whether there were warnings or errors at the start or end of runs.

You can enable them with:

tcl

/run/verbose 1
/event/verbose 1

Run verbose output typically shows:

Initialization of geometry and physics.

Messages about multithreading, if used.

Start and end of runs, with run IDs.

Event verbose output typically shows:

Start and end of each event.

IDs of events.

Some summary information about primary particles.

Use these levels to confirm that the number of events processed matches what you requested with /run/beamOn, and to see if specific events are skipped or aborted.

If you want to combine detailed tracking output with event level context, use:

tcl

/event/verbose 1
/tracking/verbose 2
/run/beamOn 1

This way you see the event header followed by all its tracks and steps, which makes it easier to associate tracks with events during debugging.

Verbose Output and Multithreading

In multithreaded mode, each worker thread processes events independently. If you enable high verbosity with many threads, the console output from different threads will interleave. The result is usually unreadable, and the overhead can eliminate the performance benefit of multithreading.

For debugging with verbose output, it is best to run with a single thread:

tcl

/run/numberOfThreads 1

or configure your application to start in sequential mode, then:

tcl

/run/initialize
/tracking/verbose 2
/run/beamOn 1

In general, use multithreading for production runs and sequential runs for debugging with verbose output. If you must debug multithreading specific issues, limit the verbosity to run or event level messages, not detailed stepping output.

When using verbose output, prefer sequential runs by setting one thread. High verbosity with many threads can cause extremely slow simulations and garbled logs.

Practical Strategy for Debugging with Verbose Output

To use verbose output efficiently, apply a step by step strategy and only increase detail when needed.

First, confirm that events are being processed:

Set run and event verbosity to 1.
Run a small number of events.
Ensure that the run and event IDs appear and match your expectations.

Next, check geometry traversal:

Set /run/numberOfThreads 1 if using multithreading.
Set /tracking/verbose 2.
Run /run/beamOn 1.
Inspect the step table to see whether the particle enters your detector region.

If geometry looks incorrect:

Enable /geometry/navigator/verbose 1.
Re run a single event and examine which volumes are entered.
Use geometry visualization and overlap checking as described in the geometry debugging chapter.

If physics behavior looks wrong:

Set /process/verbose 1 along with tracking verbose output.
Compare which processes act and at what energies with what you expect theoretically.
If necessary, adjust the physics list or production cuts.

Finally, once the issue is identified, turn verbose output back to 0 or low levels for production runs:

tcl

/run/verbose 0
/event/verbose 0
/tracking/verbose 0
/process/verbose 0

Verbose output is most useful as a temporary magnifying glass to inspect specific parts of your simulation, not as a permanent setting.

Use verbose output selectively:

Limit events, often to 1.
Limit verbosity to the relevant level (run, event, tracking, or process).
Return verbosity to 0 for production runs.

By learning how to enable and read Geant4 verbose output at different levels, you gain a direct view inside the simulation engine, which is essential for diagnosing most logical and physics related problems in beginner and intermediate applications.