source: trunk/documents/UserDoc/DocBookUsersGuides/ForApplicationDeveloper/xml/TrackingAndPhysics/tracking.xml @ 921

<!-- ******************************************************** -->
<!--                                                          -->
<!--  [History]                                               -->
<!--    Changed by: Katsuya Amako, 30-Nov-1998                -->
<!--    Changed by: Katsuya Amako, 10-Jul-1998                -->
<!--    Proof read by: Joe Chuma,  30-Jun-1999                -->
<!--    Changed by: Takashi SasakI,  15-Nov-2001              -->
<!--    Changed by: Dennis Wright, 27-Nov-2001                -->
<!--    Converted to DocBook: Katsuya Amako, Aug-2006         -->
<!--    Changed by: Hisaya Kurashige, 01-Dec-2007             -->
<!--                                                          -->
<!-- ******************************************************** -->


<!-- ******************* Section (Level#1) ****************** -->
<sect1 id="sect.Track">
<title>
Tracking
</title>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.Track.Basic">
<title>
Basic Concepts
</title>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Philosophy of Tracking
</bridgehead>

<para>
All Geant4 processes, including the transportation of particles,
are treated generically. In spite of the name "<emphasis>tracking</emphasis>",
particles are not <emphasis>transported</emphasis> in the tracking category.
<emphasis>G4TrackingManager</emphasis> 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 <emphasis>G4EventManager</emphasis> class.
</para>

<para>
The tracking manager receives a track from the event manager and
takes the actions required to finish tracking it.
<emphasis>G4TrackingManager</emphasis> aggregates the pointers to
<emphasis>G4SteppingManager,</emphasis> <emphasis>G4Trajectory</emphasis> and
<emphasis>G4UserTrackingAction</emphasis>. Also there is a "use" relation to
<emphasis>G4Track</emphasis> and <emphasis>G4Step</emphasis>.
</para>

<para>
<emphasis>G4SteppingManager</emphasis> 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
<literal>Stepping()</literal> steers the stepping of the particle. The
algorithm to handle one step is given below.

<orderedlist spacing="compact">
  <listitem><para>
    The particle's velocity at the beginning of the step is
    calculated.
  </para></listitem>
  <listitem><para>
    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.
  </para></listitem>
  <listitem><para>
    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.
  </para></listitem>
  <listitem><para>
    If the minimum physical-step-length from the processes is
    longer than "Safety", the distance to the next boundary is
    re-calculated.
  </para></listitem>
  <listitem><para>
    The smaller of the minimum physical-step-length and the
    geometric step length is taken.
  </para></listitem>
  <listitem><para>
    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.
  </para></listitem>
  <listitem><para>
    The track is checked to see whether or not it has been
    terminated by a continuous process.
  </para></listitem>
  <listitem><para>
    The current track properties are updated before discrete
    processes are invoked. This includes:

    <itemizedlist spacing="compact">
      <listitem><para>
        updating the kinetic energy of the current track particle (note
        that 'sumEnergyChange' is the sum of the new kinetic energy after
        each continuos process was invoked, and NOT the sum of the energy
        difference before and after the process invocation) and
      </para></listitem>
      <listitem><para>
        updating position and time.
      </para></listitem>
    </itemizedlist>
  </para></listitem>
  <listitem><para>
    The discrete process is invoked. After the invocation,

    <itemizedlist spacing="compact">
      <listitem><para>
        the energy of the current track particle is updated, and
      </para></listitem>
      <listitem><para>
        the secondaries from ParticleChange are stored in
        SecondaryList. This includes constructing "G4Track" objects, and
        setting their member data. Note that the stepping manager is
        responsible for deleting secodaries from ParticleChange.
      </para></listitem>
    </itemizedlist>
  </para></listitem>
  <listitem><para>
    The track is checked to see whether or not it has been
    terminated by the discrete process.
  </para></listitem>
  <listitem><para>
    "Safety" is updated.
  </para></listitem>
  <listitem><para>
    If the step was limited by the volume boundary, push the
    particle into the next volume.
  </para></listitem>
  <listitem><para>
    Invoke the user intervention <emphasis>G4UserSteppingAction</emphasis>.
  </para></listitem>
  <listitem><para>
    Handle hit information.
  </para></listitem>
  <listitem><para>
    Save data to Trajectory.
  </para></listitem>
  <listitem><para>
    Update the mean free paths of the discrete processes.
  </para></listitem>
  <listitem><para>
    If the parent particle is still alive, reset the maximum
    interaction length of the discrete process which has occurred.
  </para></listitem>
  <listitem><para>
    One step completed.
  </para></listitem>
</orderedlist>
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
What is a Step?
</bridgehead>

<para>
<emphasis>G4Step</emphasis> stores the transient information of a step. This
includes the two endpoints of the step, <literal>PreStepPoint</literal> and
<literal>PostStepPoint</literal>, which contain the points' coordinates and
the volumes containing the points. <emphasis>G4Step</emphasis> 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.
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
What is a Track?
</bridgehead>

<para>
<emphasis>G4Track</emphasis> keeps information on the final status of the
particle after the completion of one step. This means that
<emphasis>G4Track</emphasis> has information on the previous step while the
<literal>AlongStepDoIt</literal>s are being invoked for the step in progress.
Only after finishing all <literal>AlongStepDoIt</literal>s, will
<emphasis>G4Track</emphasis> have the final information (e.g., the final
position) for the step in progress. Also, <emphasis>G4Track</emphasis> will be
updated after each invocation of a <literal>PostStepDoIt</literal>.
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.Track.AccInfo">
<title>
Access to Track and Step Information
</title>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
How to Get Track Information
</bridgehead>

<para>
Track information may be accessed by invoking various
<literal>Get</literal> methods provided in the <emphasis>G4Track</emphasis> 
class. For details, see the 
<emphasis role="bold">Software Reference Manual</emphasis>. 
Typical information available includes:

<itemizedlist spacing="compact">
  <listitem><para>
    (x,y,z)
  </para></listitem>
  <listitem><para>
   Global time (time since the event was created)
  </para></listitem>
  <listitem><para>
    Local time (time since the track was created)
  </para></listitem>
  <listitem><para>
    Proper time (time in its rest frame since the track was created )
  </para></listitem>
  <listitem><para>
    Momentum direction ( unit vector )
  </para></listitem>
  <listitem><para>
    Kinetic energy
  </para></listitem>
  <listitem><para>
    Accumulated geometrical track length
  </para></listitem>
  <listitem><para>
    Accumulated true track length
  </para></listitem>
  <listitem><para>
    Pointer to dynamic particle
  </para></listitem>
  <listitem><para>
    Pointer to physical volume
  </para></listitem>
  <listitem><para>
    Track ID number
  </para></listitem>
  <listitem><para>
    Track ID number of the parent
  </para></listitem>
  <listitem><para>
    Current step number
  </para></listitem>
  <listitem><para>
    Track status
  </para></listitem>
  <listitem><para>
    (x,y,z) at the start point (vertex position) of the track
  </para></listitem>
  <listitem><para>
    Momentum direction at the start point (vertex position) of the
    track
  </para></listitem>
  <listitem><para>
    Kinetic energy at the start point (vertex position) of the track
  </para></listitem>
  <listitem><para>
    Pinter to the process which created the current track
  </para></listitem>
</itemizedlist>
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
How to Get Step Information
</bridgehead>

<para>
Step and step-point information can be retrieved by invoking
various <literal>Get</literal> methods provided in the
<emphasis>G4Step</emphasis>/<emphasis>G4StepPoint</emphasis> 
classes. For details, see the
<emphasis role="bold">Software Reference Manual</emphasis>. 
</para>

<para>
Information in <emphasis>G4Step</emphasis>
includes:

<itemizedlist spacing="compact">
  <listitem><para>
    Pointers to <literal>PreStep</literal> and 
    <literal>PostStepPoint</literal>
  </para></listitem>
  <listitem><para>
    Geometrical step length (step length before the correction of
    multiple scattering)
  </para></listitem>
  <listitem><para>
    True step length (step length after the correction of multiple
    scattering)
  </para></listitem>
  <listitem><para>
    Increment of position and time between <literal>PreStepPoint</literal>
    and <literal>PostStepPoint</literal>
  </para></listitem>
  <listitem><para>
    Increment of momentum and energy between  <literal>PreStepPoint</literal>
    and <literal>PostStepPoint</literal>. (Note: to get the energy deposited in
    the step, you cannot use this 'Delta energy'. You have to use
    'Total energy deposit' as below.)
  </para></listitem>
  <listitem><para>
    Pointer to <literal>G4Track</literal>
  </para></listitem>
  <listitem><para>
    Total energy deposited during the step - this is the sum of
    <para>
    <itemizedlist spacing="compact">
      <listitem><para>
        the energy deposited by the energy loss process, and
      </para></listitem>
      <listitem><para>
        the energy lost by secondaries which have NOT been generated
        because each of their energies was below the cut threshold
      </para></listitem>
    </itemizedlist>
    </para>
  </para></listitem>
  <listitem><para>
    Energy deposited not by ionization during the step 
  </para></listitem>
</itemizedlist>
</para>

<para>
Information in <emphasis>G4StepPoint</emphasis> 
(<literal>PreStepPoint</literal> and <literal>PostStepPoint</literal>) 
includes:

<itemizedlist spacing="compact">
  <listitem><para>
    (x, y, z, t)
  </para></listitem>
  <listitem><para>
    (px, py, pz, Ek)
  </para></listitem>
  <listitem><para>
    Momentum direction (unit vector)
  </para></listitem>
  <listitem><para>
    Pointers to physical volumes
  </para></listitem>
  <listitem><para>
    Safety
  </para></listitem>
  <listitem><para>
    Beta, gamma
  </para></listitem>
  <listitem><para>
    Polarization
  </para></listitem>
  <listitem><para>
    Step status
  </para></listitem>
  <listitem><para>
    Pointer to the physics process which defined the current step
    and its <literal>DoIt</literal> type
  </para></listitem>
  <listitem><para>
    Pointer to the physics process which defined the previous step
    and its <literal>DoIt</literal> type
  </para></listitem>
  <listitem><para>
    Total track length
  </para></listitem>
  <listitem><para>
    Global time (time since the current event began)
  </para></listitem>
  <listitem><para>
    Local time (time since the current track began)
  </para></listitem>
  <listitem><para>
    Proper time
  </para></listitem>
</itemizedlist>
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
How to Get "particle change"
</bridgehead>

<para>
Particle change information can be accessed by invoking various
<literal>Get</literal> methods provided in the 
<emphasis>G4ParticleChange</emphasis> class.
Typical information available includes (for details, see the
<emphasis role="bold">Software Reference Manual</emphasis>):

<itemizedlist spacing="compact">
  <listitem><para>
    final momentum direction of the parent particle
  </para></listitem>
  <listitem><para>
    final kinetic energy of the parent particle
  </para></listitem>
  <listitem><para>
    final position of the parent particle
  </para></listitem>
  <listitem><para>
    final global time of the parent particle
  </para></listitem>
  <listitem><para>
    final proper time of the parent particle
  </para></listitem>
  <listitem><para>
    final polarization of the parent particle
  </para></listitem>
  <listitem><para>
    status of the parent particle (<emphasis>G4TrackStatus</emphasis>)
  </para></listitem>
  <listitem><para>
    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)
  </para></listitem>
  <listitem><para>
    local energy deposited - this consists of either
    <para>
    <itemizedlist spacing="compact">
      <listitem><para>
        energy deposited by the energy loss process, or
      </para></listitem>
      <listitem><para>
        the energy lost by secondaries which have NOT been generated
        because each of their energies was below the cut threshold.
      </para></listitem>
    </itemizedlist>
    </para>
  </para></listitem>
  <listitem><para>
    number of secondaries particles
  </para></listitem>
  <listitem><para>
    list of secondary particles (list of <emphasis>G4Track</emphasis>)
  </para></listitem>
</itemizedlist>
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.Track.SecPar">
<title>
Handling of Secondary Particles
</title>

<para>
Secondary particles are passed as <emphasis>G4Track</emphasis>s from a physics
process to tracking. <emphasis>G4ParticleChange</emphasis> provides the following
four methods for a physics process:

<itemizedlist spacing="compact">
  <listitem><para>
    <literal>AddSecondary( G4Track* aSecondary )</literal>
  </para></listitem>
  <listitem><para>
    <literal>AddSecondary( G4DynamicParticle* aSecondary )</literal>
  </para></listitem>
  <listitem><para>
    <literal>AddSecondary( G4DynamicParticle* aSecondary, G4ThreeVector
    position )</literal>
  </para></listitem>
  <listitem><para>
    <literal>AddSecondary( G4DynamicParticle* aSecondary, G4double time)</literal>
  </para></listitem>
</itemizedlist>
</para>

<para>
In all but the first, the construction of <emphasis>G4Track</emphasis> is done in
the methods using informaton given by the arguments.
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.Track.UserAct">
<title>
User Actions
</title>

<para>
There are two classes which allow the user to intervene in the
tracking. These are:

<itemizedlist spacing="compact">
  <listitem><para>
    <emphasis>G4UserTrackingAction</emphasis>, and
  </para></listitem>
  <listitem><para>
    <emphasis>G4UserSteppingAction</emphasis>.
  </para></listitem>
</itemizedlist>
</para>

<para>
Each provides methods which allow the user access to the Geant4
kernel at specific points in the tracking. For details, see the
<emphasis role="bold">Software Reference Manual</emphasis>.
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.Track.Verb">
<title>
Verbose Outputs
</title>

<para>
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,

<informalexample>
<programlisting>
  G4UImanager* UI = G4UImanager::GetUIpointer();

  UI-&gt;ApplyCommand("/tracking/verbose 1");
</programlisting>
</informalexample>
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.Track.Traj">
<title>
Trajectory and Trajectory Point
</title>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
G4Trajectory and G4TrajectoryPoint
</bridgehead>

<para>
<emphasis>G4Trajectory</emphasis> and <emphasis>G4TrajectoryPoint</emphasis> 
are default concrete classes provided by Geant4, which are derived from the
<emphasis>G4VTrajectory</emphasis> and <emphasis>G4VTrajectoryPoint</emphasis> 
base classes, respectively. 
A <emphasis>G4Trajectory</emphasis> class object is created by
<emphasis>G4TrackingManager</emphasis> when a <emphasis>G4Track</emphasis> 
is passed from the <emphasis>G4EventManager</emphasis>. 
<emphasis>G4Trajectory</emphasis> has the following data
members:

<itemizedlist spacing="compact">
  <listitem><para>
    ID numbers of the track and the track's parent
  </para></listitem>
  <listitem><para>
    particle name, charge, and PDG code
  </para></listitem>
  <listitem><para>
    a collection of <emphasis>G4TrajectoryPoint</emphasis> pointers
  </para></listitem>
</itemizedlist>
</para>

<para>
<emphasis>G4TrajectoryPoint</emphasis> corresponds to a step point along 
the path followed by the track. Its position is given by a
<emphasis>G4ThreeVector</emphasis>. A <emphasis>G4TrajectoryPoint</emphasis> 
class object is created in the <emphasis>AppendStep()</emphasis> method of 
<emphasis>G4Trajectory</emphasis> and this method is invoked by 
<emphasis>G4TrackingManager</emphasis> at the end of each step. 
The first point is created when the <emphasis>G4Trajectory</emphasis> 
is created, thus the first point is the original vertex.
</para>

<para>
The creation of a trajectory can be controlled by invoking
<emphasis>G4TrackingManager::SetStoreTrajectory(G4bool)</emphasis>. The UI
command <emphasis>/tracking/storeTrajectory _bool_</emphasis> does the same. The
user can set this flag for each individual track from his/her
<emphasis>G4UserTrackingAction::PreUserTrackingAction()</emphasis> method.
</para>

<note><title></title>
<para>
The user should not create trajectories for secondaries in a shower 
due to the large amount of memory consumed.
</para>
</note>

<para>
All the created trajectories in an event are stored in
<emphasis>G4TrajectoryContainer</emphasis> class object and this object will be
kept by <emphasis>G4Event</emphasis>. To draw or print trajectories generated in
an event, the user may invoke the <emphasis>DrawTrajectory()</emphasis> or
<emphasis>ShowTrajectory()</emphasis> methods of <emphasis>G4VTrajectory</emphasis>,
respectively, from his/her
<emphasis>G4UserEventAction::EndOfEventAction()</emphasis>. The geometry must be
drawn before the trajectory drawing. The color of the drawn
trajectory depends on the particle charge:

<itemizedlist spacing="compact">
  <listitem><para>
    negative: red
  </para></listitem>
  <listitem><para>
    neutral: green
  </para></listitem>
  <listitem><para>
    positive: blue
  </para></listitem>
</itemizedlist>
</para>

<note><title></title>
<para>
Due to improvements in <emphasis>G4Navigator</emphasis>, 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.
</para>
</note>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Customizing trajectory and trajectory point
</bridgehead>

<para>
<emphasis>G4Track</emphasis> and <emphasis>G4Step</emphasis> are 
transient classes; they are not available at the end of the event. 
Thus, the concrete classes <emphasis>G4VTrajectory</emphasis> and 
<emphasis>G4VTrajectoryPoint</emphasis> 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. <emphasis>G4Trajectory</emphasis> and 
<emphasis>G4TrajectoryPoint</emphasis>,
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.
</para>

<para>
To use the customized trajectory, the user must construct a
concrete trajectory class object in the
<emphasis>G4UserTrackingAction::PreUserTrackingAction()</emphasis> method and
make its pointer available to <emphasis>G4TrackingManager</emphasis> by using the
<emphasis>SetTrajectory()</emphasis> method. The customized trajectory point
class object must be constructed in the <emphasis>AppendStep()</emphasis> method
of the user's implementation of the trajectory class. This
<emphasis>AppendStep()</emphasis> method will be invoked by
<emphasis>G4TrackingManager</emphasis>.
</para>

<para>
To customize trajectory drawing, the user can override the
<emphasis>DrawTrajectory()</emphasis> method in his/her own trajectory class.
</para>

<para>
When a customized version of G4Trajectory declares any new class
variables, <emphasis>operator new</emphasis> and 
<emphasis>operator delete</emphasis> must be
provided. It is also useful to check that the allocation size in
<emphasis>operator new</emphasis> is equal to 
<emphasis>sizeof(G4Trajectory)</emphasis>. These two points do not 
apply to <emphasis>G4VTrajectory</emphasis> because it has no
<emphasis>operator new</emphasis> or <emphasis>operator delete</emphasis>.
</para>


</sect2>
</sect1>