Tracking¶
Basic Concepts¶
Philosophy of Tracking
All Geant4 processes, including the transportation of particles, are
treated generically. In spite of the name “tracking”, particles are
not transported in the tracking category. G4TrackingManager
is an
interface class which brokers transactions between the event, track and
tracking categories. An instance of this class handles the message
passing between the upper hierarchical object, which is the event
manager, and lower hierarchical objects in the tracking category. The
event manager is a singleton instance of the G4EventManager
class.
The tracking manager receives a track from the event manager and takes
the actions required to finish tracking it. G4TrackingManager
aggregates the pointers to G4SteppingManager,
G4Trajectory
and
G4UserTrackingAction
. Also there is a “use” relation to G4Track
and G4Step
.
G4SteppingManager
plays an essential role in tracking the particle.
It takes care of all message passing between objects in the different
categories relevant to transporting a particle (for example, geometry
and interactions in matter). Its public method Stepping()
steers the
stepping of the particle. The algorithm to handle one step is given
below.
If the particle stop (i.e. zero kinetic energy), each active AtRest process proposes a step length in time based on the interaction it describes. And the process proposing the smallest step length will be invoked.
Each active discrete or continuous process must propose a step length based on the interaction it describes. The smallest of these step lengths is taken.
The geometry navigator calculates “Safety”, the distance to the next volume boundary. If the minimum physical-step-length from the processes is shorter than “Safety”, the physical-step-length is selected as the next step length. In this case, no further geometrical calculations will be performed.
If the minimum physical-step-length from the processes is longer than “Safety”, the distance to the next boundary is re-calculated.
The smaller of the minimum physical-step-length and the geometric step length is taken.
All active continuous processes are invoked. Note that the particle’s kinetic energy will be updated only after all invoked processes have completed. The change in kinetic energy will be the sum of the contributions from these processes.
The current track properties are updated before discrete processes are invoked. In the same time, the secondary particles created by processes are stored in SecondaryList. The updated properties are:
the kinetic energy of the current track particle (note that ‘sumEnergyChange’ is the sum of the energy difference before and after each process invocation)
position and time
The kinetic energy of the particle is checked to see whether or not it has been terminated by a continuous process. If the kinetic energy goes down to zero, AtRest processes will be applied at the next step if applicable.
The discrete process is invoked. After the invocation,
the energy, position and time of the current track particle are updated, and
the secondaries are stored in SecondaryList.
The track is checked to see whether or not it has been terminated by the discrete process.
“Safety” is updated.
If the step was limited by the volume boundary, push the particle into the next volume.
Handle hit information.
Invoke the user intervention
G4UserSteppingAction
.Save data to Trajectory.
Update the mean free paths of the discrete processes.
If the parent particle is still alive, reset the maximum interaction length of the discrete process which has occurred.
One step completed.
What is a Process?
Only processes can change information of G4Track
and add secondary
tracks via ParticleChange
. G4VProcess
is a base class of all
processes and it has 3 kinds of DoIt
and GetPhysicalInteraction
methods in order to describe interactions generically. If a user want to
modify information of G4Track
, he (or she) SHOULD create a special
process for the purpose and register the process to the particle.
What is a Track?
G4Track
keeps ‘current’ information of the particle. (i.e.
energy,momentum, position ,time and so on) and has ‘static’ information
(i.e. mass, charge, life and so on) also. Note that G4Track
keeps
information at the beginning of the step while the AlongStepDoIt
s
are being invoked for the step in progress.After finishing all
AlongStepDoIt
s, G4Track
is updated. On the other hand,
G4Track
is updated after each invocation of a PostStepDoIt
.
What is a Step?
G4Step
stores the transient information of a step. This includes the
two endpoints of the step, PreStepPoint
and PostStepPoint
, which
contain the points’ coordinates and the volumes containing the points.
G4Step
also stores the change in track properties between the two
points. These properties, such as energy and momentum, are updated as
the various active processes are invoked.
What is a ParticleChange?
Processes do NOT change any information of G4Track
directly in their
DoIt
. Instead, they proposes changes as a result of interactions by
using ParticleChange
. After each DoIt
, ParticleChange
updates PostStepPoint
based on proposed changes. Then, G4Track
is updated after finishing all AlongStepDoIt
s and after each
PostStepDoIt
.
Access to Track and Step Information¶
How to Get Track Information
Track information may be accessed by invoking various Get
methods
provided in the G4Track
class. For details, see the
G4Track.hh
header file in $G4INCLUDE
. Typical information available includes:
(x,y,z)
Global time (time since the event was created)
Local time (time since the track was created)
Proper time (time in its rest frame since the track was created )
Momentum direction ( unit vector )
Kinetic energy
Accumulated geometrical track length
Accumulated true track length
Pointer to dynamic particle
Pointer to physical volume
Track ID number
Track ID number of the parent
Current step number
Track status
(x,y,z) at the start point (vertex position) of the track
Momentum direction at the start point (vertex position) of the track
Kinetic energy at the start point (vertex position) of the track
Pointer to the process which created the current track
How to Get Step Information
Step and step-point information can be retrieved by invoking various
Get
methods provided in the G4Step
/G4StepPoint
classes..
Information in G4Step includes:
Pointers to
PreStep
andPostStepPoint
Geometrical step length (step length before the correction of multiple scattering)
True step length (step length after the correction of multiple scattering)
Increment of position and time between
PreStepPoint
andPostStepPoint
Increment of momentum and energy between
PreStepPoint
andPostStepPoint
. (Note: to get the energy deposited in the step, you cannot use this ‘Delta energy’. You have to use ‘Total energy deposit’ as below.)Pointer to
G4Track
Total energy deposited during the step - this is the sum of
the energy deposited by the energy loss process, and
the energy lost by secondaries which have NOT been generated because each of their energies was below the cut threshold
Energy deposited not by ionization during the step
Secondary tracks created during tracking for the current track.
NOTE: all secondaries are included. NOT only secondaries created in the CURRENT step.
Information in
G4StepPoint
(PreStepPoint
and PostStepPoint
) includes:
(x, y, z, t)
(px, py, pz, Ek)
Momentum direction (unit vector)
Pointers to physical volumes
Safety
Beta, gamma
Polarization
Step status
Pointer to the physics process which defined the current step and its
DoIt
typePointer to the physics process which defined the previous step and its
DoIt
typeTotal track length
Global time (time since the current event began)
Local time (time since the current track began)
Proper time
How to Get “particle change”
Particle change information can be accessed by invoking various Get
methods provided in the
G4ParticleChange
class. Typical information available includes:
final momentum direction of the parent particle
final kinetic energy of the parent particle
final position of the parent particle
final global time of the parent particle
final proper time of the parent particle
final polarization of the parent particle
status of the parent particle (
G4TrackStatus
)true step length (this is used by multiple scattering to store the result of the transformation from the geometrical step length to the true step length)
local energy deposited - this consists of either
energy deposited by the energy loss process, or
the energy lost by secondaries which have NOT been generated because each of their energies was below the cut threshold.
number of secondaries particles
list of secondary particles (list of
G4Track
)
Handling of Secondary Particles¶
Secondary particles are passed as G4Track
s from a physics process
to tracking. G4ParticleChange
provides the following four methods
for a physics process:
AddSecondary( G4Track* aSecondary )
AddSecondary( G4DynamicParticle* aSecondary )
AddSecondary( G4DynamicParticle* aSecondary, G4ThreeVector position )
AddSecondary( G4DynamicParticle* aSecondary, G4double time)
In all but the first, the construction of G4Track
is done in the
methods using information given by the arguments.
User Actions¶
There are two classes which allow the user to intervene in the tracking. These are:
G4UserTrackingAction
, andG4UserSteppingAction
.
Each provides methods which allow the user access to the Geant4 kernel at specific points in the tracking.
Note
Users SHOULD NOT (and CAN NOT) change G4Track
in
UserSteppingAction
. The only exception is the TrackStatus
.
Note
Users have to be cautious to implement an unnatural/unphysical action in these user actions. See the section Killing Tracks in User Actions and Energy Conservation for more details.
Verbose Outputs¶
The verbose information output flag can be turned on or off. The amount of information printed about the track/step, from brief to very detailed, can be controlled by the value of the verbose flag, for example,
G4UImanager* UI = G4UImanager::GetUIpointer();
UI->ApplyCommand("/tracking/verbose 1");
Trajectory and Trajectory Point¶
G4Trajectory and G4TrajectoryPoint¶
G4Trajectory
and G4TrajectoryPoint
are default concrete classes
provided by Geant4, which are derived from the G4VTrajectory
and
G4VTrajectoryPoint
base classes, respectively. A G4Trajectory
class object is created by G4TrackingManager
when a G4Track
is
passed from the G4EventManager
. G4Trajectory
has the following
data members:
ID numbers of the track and the track’s parent
particle name, charge, and PDG code
a collection of
G4TrajectoryPoint
pointers
G4TrajectoryPoint
corresponds to a step point along the path
followed by the track. Its position is given by a G4ThreeVector
. A
G4TrajectoryPoint
class object is created in the AppendStep()
method of G4Trajectory
and this method is invoked by
G4TrackingManager
at the end of each step. The first point is
created when the G4Trajectory
is created, thus the first point is
the original vertex.
The creation of a trajectory can be controlled by invoking
G4TrackingManager::SetStoreTrajectory(G4bool)
. The UI command
/tracking/storeTrajectory _bool_ does the same. The user can set
this flag for each individual track from his/her
G4UserTrackingAction::PreUserTrackingAction()
method.
Note
The user should not create trajectories for secondaries in a shower due to the large amount of memory consumed.
All the created trajectories in an event are stored in
G4TrajectoryContainer
class object and this object will be kept by
G4Event
. To draw or print trajectories generated in an event, the
user may invoke the DrawTrajectory()
or ShowTrajectory()
methods
of G4VTrajectory
, respectively, from his/her
G4UserEventAction::EndOfEventAction()
. The geometry must be drawn
before the trajectory drawing. The color of the drawn trajectory depends
on the particle charge:
negative: red
neutral: green
positive: blue
Note
Due to improvements in G4Navigator
, a track can execute more
than one turn of its spiral trajectory without being broken into
smaller steps as long as the trajectory does not cross a geometrical
boundary. Thus a drawn trajectory may not be circular.
Customizing trajectory and trajectory point¶
G4Track
and G4Step
are transient classes; they are not available
at the end of the event. Thus, the concrete classes G4VTrajectory
and G4VTrajectoryPoint
are the only ones a user may employ for
end-of-event analysis or for persistency. As mentioned above, the
default classes which Geant4 provides, i.e. G4Trajectory
and
G4TrajectoryPoint
, have only very primitive quantities. The user can
customize his/her own trajectory and trajectory point classes by
deriving directly from the respective base classes.
To use the customized trajectory, the user must construct a concrete
trajectory class object in the
G4UserTrackingAction::PreUserTrackingAction()
method and make its
pointer available to G4TrackingManager
by using the
SetTrajectory()
method. The customized trajectory point class object
must be constructed in the AppendStep()
method of the user’s
implementation of the trajectory class. This AppendStep()
method
will be invoked by G4TrackingManager
.
To customize trajectory drawing, the user can override the
DrawTrajectory()
method in his/her own trajectory class.
When a customized version of G4Trajectory declares any new class
variables, operator new and operator delete must be provided. It is
also useful to check that the allocation size in operator new is equal
to sizeof(G4Trajectory)
. These two points do not apply to
G4VTrajectory
because it has no operator new or operator delete.