30.9. Segmentation Faults

Understanding Segmentation Faults in Geant4

Segmentation faults are among the most common and frustrating errors you will meet when developing Geant4 applications. They indicate that your program tried to access memory that it was not allowed to use. This is not specific to Geant4, but Geant4 applications use many dynamically created objects, pointers, and callbacks, so segmentation faults are particularly easy to trigger if there is a mistake in your user code.

This chapter focuses on how segmentation faults typically appear in Geant4, how to read backtraces, and how to approach debugging them systematically. Concepts like geometry, physics lists, and user actions are assumed to be known from previous chapters; here we only look at them from the perspective of failure and debugging.

Typical Symptoms and When They Occur

Segmentation faults can occur at almost any time in a Geant4 run. Recognizing at what stage the crash happens is the first step.

If the program crashes before you see any Geant4 banner or version information, the fault is usually in your main() or in static initialization of global objects.

If the crash appears immediately after /run/initialize, it often relates to detector construction, geometry, materials, physics list initialization, or user actions being registered incorrectly.

If the crash happens when you call /run/beamOn, it is often tied to event, tracking, stepping, or sensitive detector code.

If the crash occurs only after many events have run successfully, consider uninitialized variables, use of deleted objects, accumulation of invalid pointers, or logical errors that appear only for rare particles or rare geometrical situations.

It is very useful to note exactly which UI command was executed just before the crash and what parameters you had set for the run.

Reading the Backtrace

When a segmentation fault occurs, you will usually see a short message such as:

Segmentation fault (core dumped)

On its own this is not very helpful. The most effective way to start is to run the program inside a debugger such as gdb or lldb. Here is a typical sequence on Linux with gdb:

gdb ./yourApp
(gdb) run
# reproduce the crash
(gdb) backtrace

The backtrace command lists the function call stack at the moment of the crash. For a Geant4 application, the stack may be very long, but you should look for the first frame that points into your own code rather than a Geant4 library. That is usually where the bug is.

A simplified backtrace might look like:

#0  0x00007f... in G4LogicalVolume::AddDaughter(...)
#1  0x000055... in MyDetectorConstruction::Construct() at MyDetectorConstruction.cc:74
#2  0x00007f... in G4RunManager::InitializeGeometry()
...

Here frame #1 points directly at a line in MyDetectorConstruction::Construct(). This is your primary suspect.

If the backtrace is full of template code or internal Geant4 details, move down through the frames until you see a file and line location in your own project. In gdb you can use:

(gdb) frame 3
(gdb) list

to display the source around that point.

In multithreaded applications, the crashing code may be in a worker thread. Use:

(gdb) info threads
(gdb) thread <id>
(gdb) backtrace

to see the stack for each thread and find the one that crashed.

Common Causes in User Geometry

Many segmentation faults in Geant4 originate in user geometry construction. Typical problems include null pointers, objects that go out of scope, or inconsistently defined volumes.

One frequent mistake is to create solids or logical volumes as local variables in Construct() and then store pointers to them for later use. When Construct() returns, local variables are destroyed and their addresses become invalid. Accessing such pointers in other methods leads to undefined behavior and often segmentation faults.

Correct practice is to allocate volumes that must survive beyond Construct() using new and keep owning pointers at class scope, or rely on Geant4 to manage them via its store classes when they are created on the heap.

Another common error is passing null pointers to placement constructors such as G4PVPlacement, either as mother volumes or logical volumes. This might happen if material creation failed, or if a G4LogicalVolume was not actually constructed before being used. If you see a fault inside G4PVPlacement or G4LogicalVolume methods, verify that every pointer you pass to them is valid and that any material name looked up by G4NistManager exists.

Geometry overlap checking, which is discussed in another chapter, can also help catch problems before they cause segmentation faults. Some invalid geometries are caught by internal checks that may abort with an error message before a segmentation fault occurs.

Common Causes in User Actions

User action classes such as RunAction, EventAction, SteppingAction, TrackingAction, and StackingAction are frequent locations for segmentation faults, because they often deal with pointers supplied by Geant4 at runtime.

A typical pattern is to retrieve information from G4Step, G4Track, or from collections of hits, but then assume that some pointer is never null or that a certain index always exists. If a step does not have an associated process, or if a hit collection is missing for a particular event, your code may dereference a null pointer or perform out of bounds access.

For example, in SteppingAction, calling methods on a pointer returned by GetPostStepPoint()->GetTouchable() without checking that GetTouchable() is not null can cause a crash in unusual circumstances, such as when a track is killed at the world boundary.

In EventAction, accessing hit collections requires that the corresponding sensitive detectors have been attached and that the event actually contains hits. If you request a collection by index and then assume its pointer is always non null, you might crash for events where no hits were produced.

The safe pattern is to check pointers and collection handles before use, and to handle missing information gracefully. For absolute beginners it can feel tedious to add these checks, but it prevents many subtle crashes that are difficult to reproduce.

Sensitive Detectors and Hits

Sensitive detector code is another source of segmentation faults because it bridges between Geant4 steps and your own data structures. Mistakes often occur in ProcessHits() implementations or in hit classes.

A typical problem is to allocate hits on the stack and then store their addresses in a G4THitsCollection. Geant4 expects hits to be allocated with new and takes ownership of them for the duration of the event. If you store the address of a local variable, the pointer becomes invalid as soon as ProcessHits() returns, and when Geant4 later tries to use or delete the hit, a segmentation fault is likely.

Another pitfall is casting hit pointers incorrectly when accessing them later. If you use a base class pointer or retrieve a hit collection with the wrong template type, you may access memory inconsistently. Always use your specific hit type consistently, and ensure that the type used in the collection definition matches the actual hit class.

Finally, be careful when using indices to identify detector elements. If you store information in arrays or vectors indexed by copy numbers or detector IDs, you must ensure that these IDs are within expected bounds. Using a volume copy number as an array index without checking its range can cause out-of-bounds writes leading to crashes some time later in the run.

Uninitialized and Deleted Pointers

Because Geant4 uses C++ and relies on your user code for many tasks, you must manage pointers carefully. Two common categories of errors are uninitialized pointers and use of deleted objects.

Uninitialized pointers may hold any random memory address. If you forget to set a pointer to nullptr initially, or forget to assign a valid object before using it, the first dereference can immediately cause a segmentation fault.

Use of deleted objects is more subtle. If you delete an object but keep a pointer to it around, a later access to that pointer can crash. This can occur with custom managers, analysis objects, or geometry helper classes that you create and destroy manually.

To reduce these risks, prefer smart pointers from the C++ standard library for objects that are not controlled by Geant4 itself. For example, using std::unique_ptr for analysis managers or helper classes ensures that ownership and lifetimes are clear, and that you do not accidentally call delete twice. Geant4 objects that are managed internally, such as volumes and hits, should continue to follow the memory management patterns recommended by Geant4 itself.

When debugging a segmentation fault that might be related to such memory issues, tools like valgrind can be very helpful. Running your application under valgrind can show invalid reads and writes and indicate where memory was allocated and freed.

Macro Commands and Invalid States

Geant4 macro commands allow you to change many aspects of the simulation at runtime without recompiling. However, they can also put your application into inconsistent states if used incorrectly.

Common problematic scenarios include changing geometry-related parameters after the geometry has been constructed, modifying physics lists in ways that are not supported for a running application, or starting a run with incomplete initialization. In many cases Geant4 issues warnings or errors if commands are used in an invalid order, but if user code assumes certain initialization steps have already occurred, a mismatch can lead to null pointers or uninitialized objects.

For example, if you access geometry-dependent pointers in BeginOfRunAction assuming that /run/initialize has already completed, but you actually start a run without proper initialization, your pointers may be invalid and can cause a crash. Similarly, if macro commands define a new detector configuration but your code still refers to old volumes, subtle segmentation faults can appear.

As a basic rule, treat /run/initialize as the point after which geometry and physics are guaranteed to be constructed. Do not rely on internal pointers before that, and if you allow geometry changes at runtime, make sure your user code updates any cached pointers when geometry is rebuilt.

Using Debug Builds and Compiler Checks

Debugging segmentation faults is much easier if you compile your application with debug information and with compiler checks and sanitizers enabled.

When building Geant4 and your application with CMake, turn on debug symbols by configuring with a debug build type, for example:

cmake -DCMAKE_BUILD_TYPE=Debug ...

This ensures that backtraces generated by gdb or other debuggers include line numbers and file names for both your code and Geant4 libraries.

Modern compilers also provide address sanitizers and undefined behavior sanitizers that can detect invalid memory accesses and many other errors before they turn into segmentation faults. For example, you can add flags such as:

-fsanitize=address -fno-omit-frame-pointer

to your compile options. This is usually done by setting appropriate CMake variables for your project. Running your program with sanitizers enabled can yield very informative messages describing exactly where an invalid memory access occurred.

While sanitizers may slow down execution, they are extremely useful during development, especially when you are still learning Geant4 and C++.

Step-by-Step Strategy for Debugging a Crash

When you encounter a segmentation fault, resist the temptation to guess. Follow a systematic strategy instead.

First, reproduce the crash with a small number of events, ideally just one or a few, using the same macro commands and parameters. If possible, simplify the run conditions by reducing complexity in geometry, physics, or analysis while still triggering the crash.

Second, run the application inside a debugger and obtain a backtrace at the crash point. Identify the first stack frame in your own source files, and inspect the values of relevant pointers and variables in that frame. Look for null pointers, unexpected indices, or obviously incorrect data.

Third, review the corresponding source code carefully, paying attention to assumptions about pointers, collection existence, initialization order, and array bounds. Add defensive checks and additional logging or G4cout statements to understand the control flow.

Fourth, if memory corruption is suspected, run the application under valgrind or with address sanitizers enabled. Pay attention to earlier reports in the log, not only to the final crash.

Finally, once you believe you have fixed the problem, rerun the scenario in both debug and optimized builds, and if you are using multithreading, test with multiple threads as well. Some errors appear only under concurrent execution, and a fix must be robust in that environment.

By applying these practices consistently, you will gradually become comfortable diagnosing and fixing segmentation faults in Geant4 applications. This is an essential skill for any realistic simulation project, and the effort invested in understanding these crashes will significantly improve the reliability and quality of your code.

Views: 9