KAHIBARO
14.5 StackingAction
Table of Contents
Managing secondary particles
In Geant4, the stacking action gives you control over the life of tracks before they are transported. While SteppingAction and TrackingAction look at tracks that are already being propagated, G4UserStackingAction lets you decide what should happen to each new track as soon as it is created and placed on the stack.
To use this mechanism, you create a class that inherits from G4UserStackingAction and override at least the ClassifyNewTrack(const G4Track* track) method. Geant4 calls this method whenever a new track is created, including primary particles and all secondary particles generated by physical processes. Inside this method you can inspect the track and return a classification value that controls how Geant4 will treat it.
The most common reason to implement a stacking action is to manage secondary particles. For example, you can kill low energy secondary electrons that do not contribute to your observable, or keep only optical photons that hit a particular region, or give priority to certain particles for faster response.
The G4Track object passed to ClassifyNewTrack gives you access to particle type, energy, position, creator process, and whether the particle is primary or secondary. This allows very fine control over which secondaries you allow to propagate. For instance, you might allow all primary particles, but reject secondaries that fall outside a given energy window, or secondaries created in a region that is not of interest.
You can also use the stacking action to count or tag secondaries without necessarily killing them. Because every track passes through this method once, it is a convenient central point to increment counters in your run or event actions, for example to monitor total numbers of secondary neutrons, gammas, or optical photons.
Another aspect of managing secondaries is performance. Many Geant4 simulations generate huge numbers of low energy secondaries that have little impact on the quantities you want to measure. By using the stacking action to stop those tracks early, you can greatly reduce CPU time. However, this must always be done with care, because removing secondaries can change physical results. You should only kill particles that are demonstrably irrelevant to your observables.
When you implement your stacking action, you typically keep it simple and local. The class itself should only decide what to do with the track based on its properties and perhaps some configuration parameters, while the rest of the application records the effects through sensitive detectors and analysis. This keeps your stacking logic focused on secondary management rather than mixing it with geometry or analysis code.
To activate your stacking action, you register your G4UserStackingAction subclass in your ActionInitialization class. Once registered, Geant4 will automatically call your methods during tracking, and every newly created secondary will pass through your custom logic before it is transported.
Careless killing of secondary particles can introduce significant and hidden biases in your simulation results. Only suppress secondaries when you have a clear physical justification and, whenever possible, validate the impact by comparison with a full simulation.
Classifying tracks
Track classification is the central feature of the stacking action. In Geant4, each new track is assigned to a stack according to the value returned by ClassifyNewTrack. The typical enum values are fUrgent, fWaiting, fPostponeToNextEvent, and fKill, which you return from ClassifyNewTrack. These classifications decide whether the track is transported immediately, later, in a different event, or not at all.
The simplest classification scheme is to return fUrgent for every track, which reproduces the default Geant4 behavior. More advanced schemes use the track information to choose between the available categories. For example, you can send certain secondary tracks to a waiting stack with fWaiting and process them only after all urgent tracks have been transported.
A common pattern is to keep primary particles as urgent and treat secondaries selectively. You can check if a track is primary by examining its parent ID. Typically, a parent ID of zero indicates a primary track. For all primary particles you then return fUrgent so that they always propagate. For secondaries, you inspect particle type, kinetic energy, or creation process and possibly return fKill to discard tracks that are not needed.
Another use of classification is to manage rare or special particles. For instance, you might classify all neutrons as urgent and push other particles to the waiting stack. By controlling the processing order, you can study particular components of the radiation field separately or ensure that important tracks are followed first.
Geant4 also allows you to override methods for stack manipulation, such as NewStage() and PrepareNewEvent(). NewStage() is called when the urgent stack becomes empty and Geant4 wants to move tracks from the waiting stack to the urgent stack. Inside NewStage(), you can implement custom logic for handling tracks that were previously classified as waiting. This gives you an additional level of control over when different groups of tracks are transported.
Track classification is part of the overall strategy to balance accuracy, statistics, and performance. By carefully designing your classification rules, you can prioritize interesting tracks, defer less important ones, or reject irrelevant ones. However, every classification rule should be physically motivated, especially when it uses fKill, since that removes tracks completely from the simulation.
In practice, you often design your classification scheme around the measurement you want from the simulation. If your goal is to study dose from primary protons, you might classify all protons as urgent, keep only selected secondaries that contribute significantly to dose, and kill other low impact particles. If your goal is to study neutron backgrounds, you might classify neutrons as urgent and demote or suppress other particles that do not contribute to the background of interest.
Any track classified with fKill is completely removed from the simulation, including all of its potential secondaries. This can change shower development, dose distributions, and detector signals. Always verify that your classification rules do not remove particles that are important for your target observables.
Views: 8