source: trunk/documents/UserDoc/DocBookUsersGuides/ForToolkitDeveloper/xml/OOAnalysisDesign/Tracking/tracking.xml @ 904

<!-- ******************************************************** -->
<!--  Docbook Version:  For Toolkit Developers Guide          -->
<!-- ******************************************************** -->

<!-- ******************** Top of Section ******************** -->
<sect1 id="sect.DsgnFuncTracking">
<title>
Tracking
</title>

<para>
The tracking category manages the contribution of the processes to the 
evolution of a track's state and provides information in sensitive volumes 
for hits and digitization.
</para>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.DsgnFuncTracking.DsgPhlsp">
<title>
Design Philosophy
</title>

<para>
It is well known that the overall performance of a detector 
simulation depends critically on the CPU time spent
propagating the particle through one step.  The most 
important consideration in the object design of the tracking 
category is maintaining high execution speed in the Geant4
simulation while utilizing the power of the object-oriented
approach. 
</para>

<para>
An extreme approach to the particle tracking design would be
to integrate all functionalities required for the propagation
of a particle into a single class.  This design approach looks 
object-oriented because a particle in the real world 
propagates by itself while interacting with the material 
surrounding it.  However, in terms of data hiding, which is 
one of the most important ingredients in the object-oriented 
approach, the design can be improved.
</para>

<para>
Combining all the necessary functionalities into a single 
class exposes all the data attributes to a large number of 
methods in the class.  This is basically equivalent to using 
a common block in Fortran.
</para>

<para>
Instead of the 'big-class' approach, a hierarchical design
was employed by Geant4.  The hierarchical approach, which 
includes inheritance and aggregation, enables large, complex 
software systems to be designed in a structured way.  The 
simulation of a particle passing through matter is
a complex task involving particles, detector geometry, physics 
interactions and hits in the detector.  It is well-suited to
the hierarchical approach.  The hierarchical design manages the 
complexity of the tracking category by separating the system 
into layers.  Each layer may then be designed independently of 
the others. 
</para>

<para>
In order to maintain high-performance tracking, use of the 
inheritance ('is-a' relation) hierarchy in the tracking category
was avoided as much as possible.  For example, <literal>track</literal> 
and <literal>particle</literal> classes might have been designed so that a 
<literal>track</literal> 'is a' <literal>particle</literal>.  In this 
scheme, however, whenever a <literal>track</literal> object is used, 
time is spent copying the data from the <literal>particle</literal> object 
into the <literal>track</literal> 
object.  Adopting the aggregation ('has-a' relation) hierarchy 
requires only pointers to be copied, thus providing a 
performance advantage.
</para>

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.DsgnFuncTracking.DsgClass">
<title>
Class Design
</title>

<para>
<xref linkend="fig.DsgnFuncTracking_1" /> shows a general overview of the 
tracking design in Unified Modelling Language Notation.

<figure id="fig.DsgnFuncTracking_1">
<title>
  Tracking design
</title>
<mediaobject>
  <imageobject role="fo">
    <imagedata fileref="./AllResources/OOAnalysisDesign/Tracking/classDgmTracking.gif"
               format="GIF" contentwidth="10.0cm" align="center" />
  </imageobject>
  <imageobject role="html">
    <imagedata fileref="./AllResources/OOAnalysisDesign/Tracking/classDgmTracking.gif"
               format="GIF" align="center" />
  </imageobject>
</mediaobject>
</figure>


<itemizedlist spacing="compact">
  <listitem><para>
    <emphasis role="bold">G4TrackingManager</emphasis> is an interface 
    between the event and track categories and the tracking category.  
    It handles the message passing between the upper hierarchical object, 
    which is the event manager (<literal>G4EventManagerz</literal>), 
    and lower hierarchical objects in the tracking category.  
    <literal>G4TrackingManager</literal> is responsible for processing 
    one track which it receives from the event manager.
    </para>
    <para>
    <literal>G4TrackingManager</literal> aggregates the pointers to 
    <literal>G4SteppingManager</literal>, <literal>G4Trajectory</literal> 
    and <literal>G4UserTrackingAction</literal>.  It also has a 'use' 
    relation to <literal>G4Track</literal>. 
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">G4SteppingManager</emphasis>  plays an essential 
    role in particle tracking.  It performs message passing to objects 
    in all categories related to particle transport, such as 
    geometry and physics processes.  Its public method 
    <literal>Stepping()</literal> steers the stepping of the particle.  
    The algorithm employed in this method is basically the same as that 
    in Geant3.  The Geant4 implementation, however, relies on the inheritance 
    hierarchy of the physics interactions.  The hierarchical 
    design of the physics interactions enables the stepping 
    manager to handle them as abstract objects.  Hence, the manager 
    is not concerned with concrete interaction objects such as 
    bremsstrahlung or pair creation.  The actual invocations of 
    various interactions during the stepping are done through a
    dynamic binding mechanism.  This mechanism shields the 
    tracking category from any change in the design of the physics 
    process classes, including the addition or subtraction of new
    processes.
    </para>
    <para>
    <literal>G4SteppingManager</literal> also aggregates 
    <itemizedlist spacing="compact">
      <listitem><para>
        the pointers to <literal>G4Navigator</literal> from the geometry 
        category, to the current <literal>G4Track</literal>, and
      </para></listitem>
      <listitem><para>
        the list of secondaries from the current track 
        (through a <literal>G4TrackVector</literal>) to 
        <literal>G4UserSteppingAction</literal> and to 
        <literal>G4VSteppingVerbose</literal>.
      </para></listitem>
    </itemizedlist>
     It also has a 'use' relation to <literal>G4ProcessManager</literal> 
     and <literal>G4ParticleChange</literal> in the physics processes 
     class category. 
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">G4Track</emphasis> - the class 
    <literal>G4Track</literal> represents a particle 
    which is pushed by <literal>G4SteppingManager</literal>.  It holds 
    information required for stepping a particle, for example, the 
    current position, the time since the start of stepping, the 
    identification of the geometrical volume which contains the particle, 
    etc.  Dynamic information, such as particle momentum and energy, 
    is held in the class through a pointer to the 
    <literal>G4DynamicParticle</literal> class.  Static 
    information, such as the particle mass and charge is stored in the 
    <literal>G4DynamicParticle</literal> class through the pointer to the 
    <literal>G4ParticleDefinition</literal> class.  Here the aggregation 
    hierarchical design is extensively employed to maintain high tracking 
    performance.
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">G4TrajectoryPoint and G4Trajectory</emphasis>  - 
    the class  <literal>G4TrajectoryPoint</literal> holds the state of 
    the particle after propagating one step.  Among other things, it 
    includes information on space-time, energy-momentum and geometrical 
    volumes.
    </para>
    <para>
    <literal>G4Trajectory</literal> aggregates all 
    <literal>G4TrajectoryPoint</literal> objects which belong to the 
    particle being propagated. 
    <literal>G4TrackingManager</literal> takes care of adding the 
    <literal>G4TrajectoryPoint</literal> to a <literal>G4Trajectory</literal> 
    object if the user requested it (see 
    <ulink url="http://geant4.web.cern.ch/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/index.html">
    Geant4 User's Guide - For Application Developers</ulink>. 
    The life of a <literal>G4Trajectory</literal> object spans an event, contrary to 
    <literal>G4Track</literal> objects, which are deleted from memory after being 
    processed.
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">G4UserTrackingAction and G4UserSteppingAction</emphasis> - 
    <literal>G4UserTrackingAction</literal> is a base class from which user actions 
    at the beginning or end of tracking may be derived.  Similarly, 
    <literal>G4UserSteppingAction</literal> is a base class from which user actions 
    at the beginning or end of each step may be derived. 
  </para></listitem>
</itemizedlist>
</para>

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.DsgnFuncTracking.TrkAlgo">
<title>
Tracking Algorithm
</title>

<para>
The key classes for tracking in Geant4 are 
<literal>G4TrackingManager</literal> and <literal>G4SteppingManager</literal>.  
The singleton object "TrackingManager" from <literal>G4TrackingManager</literal> 
keeps all information related to a particular track, and it 
also manages all actions necessary to complete the tracking.  The 
tracking proceeds by pushing a particle by a step, the length 
of which is defined by one of the active processes.
The "TrackingManager" object delegates management of each of the 
steps to the "SteppingManager" object.  This object keeps all 
information related to a particular step. 
</para>

<para>
The public method <literal>ProcessOneTrack()</literal> in 
<literal>G4TrackingManager</literal> 
is the key to managing the tracking, while the public method 
<literal>Stepping()</literal> is the key to managing one step.  The algorithms 
used in these methods are explained below.
</para>

<para>
<emphasis role="bold">ProcessOneTrack() in G4TrackingManager</emphasis>

<orderedlist spacing="compact">
  <listitem><para>
    Actions before tracking the particle: Clear secondary particle vector  
  </para></listitem>
  <listitem><para>
    Pre tracking user intervention process. 
  </para></listitem>
  <listitem><para>
    Construct a trajectory if it is requested
  </para></listitem>
  <listitem><para>
    Give SteppingManager the pointer to the track which will be tracked
  </para></listitem>
  <listitem><para>
    Inform beginning of tracking to physics processes
  </para></listitem>
  <listitem><para>
    Track the particle Step-by-Step while it is alive
    <itemizedlist spacing="compact">
      <listitem><para>
        Call Stepping method of G4SteppingManager
      </para></listitem>
      <listitem><para>
        Append a trajectory point to the trajectory object if it is requested    
      </para></listitem>
    </itemizedlist>
  </para></listitem>
  <listitem><para>
    Post tracking user intervention process. 
  </para></listitem>
  <listitem><para>
    Destroy the trajectory if it was created
  </para></listitem>
</orderedlist>
</para>

<para>
<emphasis role="bold">Stepping() in G4SteppingManager</emphasis>

<orderedlist spacing="compact">
  <listitem><para>
    Initialize current step
  </para></listitem>
  <listitem><para>
    If particle is stopped, get the minimum life time from all the at rest 
    processes and invoke InvokeAtRestDoItProcs for the selected AtRest 
    processes
  </para></listitem>
  <listitem><para>
    If particle is not stopped:
    <itemizedlist spacing="compact">
      <listitem><para>
        Invoke DefinePhysicalStepLength, that finds the minimum 
        step length demanded by the active processes 
      </para></listitem>
      <listitem><para>
        Invoke InvokeAlongStepDoItProcs
      </para></listitem>
      <listitem><para>
        Update current track properties by taking into account all 
        changes by AlongStepDoIt
      </para></listitem>
      <listitem><para>
        Update the <emphasis role="bold">safety</emphasis>
      </para></listitem>
      <listitem><para>
        Invoke PostStepDoIt of the active discrete process.
      </para></listitem>
      <listitem><para>
        Update the track length
      </para></listitem>
      <listitem><para>
        Send G4Step information to Hit/Dig if the volume is sensitive
      </para></listitem>
      <listitem><para>
        Invoke the user intervention process.
      </para></listitem>
      <listitem><para>
        Return the value of the StepStatus.
      </para></listitem>
    </itemizedlist>
  </para></listitem>
</orderedlist>
</para>

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.DsgnFuncTracking.IntPhysProc">
<title>
Interaction with Physics Processes
</title>

<para>
The interaction of the tracking category with the physics processes 
is done in two ways.  First each process can limit the step length 
through one of its three <literal>GetPhysicalInteractionLength()</literal> 
methods, AtRest, AlongStep, or PostStep.  Second, for the selected processes 
the DoIt (AtRest, AlongStep or PostStep) methods are invoked. 
All this interaction is managed by the Stepping method of 
<literal>G4SteppingManager</literal>.  To calculate the step length, the 
<literal>DefinePhysicalStepLength()</literal> method is called.  The flow of 
this method is the following:

<itemizedlist spacing="compact">
  <listitem><para>
    Obtain maximum allowed Step in the volume define by the user 
    through G4UserLimits.
  </para></listitem>
  <listitem><para>
    The PostStepGetPhysicalInteractionLength of all active processes 
    is called.  Each process returns a step length and the minimum
    one is chosen.  This method also returns a G4ForceCondition flag, 
    to indicate if the process is forced or not:
        = Forced    : Corresponding PostStepDoIt is forced.
        = NotForced : Corresponding PostStepDoIt is not forced 
                      unless this process limits the step.
        = Conditionally : Only when AlongStepDoIt limits the 
                          step, corresponding PoststepDoIt is invoked.
        = ExclusivelyForced : Corresponding PostStepDoIt is exclusively 
                              forced.
    All other DoIt including AlongStepDoIts are ignored.
  </para></listitem>
  <listitem><para>
    The AlongStepGetPhysicalInteractionLength method of all active 
    processes is called.  Each process returns a step length and the 
    minimum of these and the 
    This method also returns a fGPILSelection flag, to indicate if 
    the process is the selected one can be is forced or not:
        = CandidateForSelection: this process can be the winner.  If 
          its step length is the smallest, it will be the process 
          defining the step (the process 
        = NotCandidateForSelection: this process cannot be the winner. 
          Even if its step length is taken as the smallest, it will not 
          be the process defining the step 
  </para></listitem>
</itemizedlist>
</para>

<para>
The method <literal>G4SteppingManager::InvokeAlongStepDoIts()</literal> 
is in charge of calling the AlongStepDoIt methods of the different 
processes:

<itemizedlist spacing="compact">
  <listitem><para>
    If the current step is defined by a 'ExclusivelyForced' 
    PostStepGetPhysicalInteractionLength, no AlongStepDoIt method will be invoked
  </para></listitem>
  <listitem><para>
    Else, all the active continuous processes will be invoked, and they return 
    the ParticleChange. After it for each process the following is executed:
    <itemizedlist spacing="compact">
      <listitem><para>
        Update the G4Step information by using final state information of the 
        track given by a physics process. This is done through the 
        UpdateStepForAlongStep method of the ParticleChange
      </para></listitem>
      <listitem><para>
        Then for each secondary:
        <itemizedlist spacing="compact">
          <listitem><para>
            It is checked if its kinetic energy is smaller than the energy 
            threshold for the material. In this case the particle is assigned a 0. 
            kinetic energy and its energy is added as deposited energy of the 
            parent track. This check is only done if the flag ApplyCutFlag is set 
            for the particle (by default it is set to 'false' for all particles, 
            user may change it in its G4VUserPhysicsList). 
            If the track has the flag IsGoodForTracking 'true' this check will 
            have no effect (used mainly to track particles below threshold)
          </para></listitem>
          <listitem><para>
            The parentID and the process pointer which created this track are set    
          </para></listitem>
          <listitem><para>
            The secondary track is added to the list of secondaries. If it has 0. 
            kinetic energy, it is only added if it it invokes a rest process at 
            the beginning of the tracking
          </para></listitem>
        </itemizedlist>
      </para></listitem>
      <listitem><para>
        The track status is set according to what the process defined
      </para></listitem>
    </itemizedlist>
  </para></listitem>
</itemizedlist>
</para>

<para>
The method <literal>G4SteppingManager::InvokePostStepDoIts</literal> is on 
charge of calling the PostStepDoIt methods of the different processes.

<itemizedlist spacing="compact">
  <listitem><para>
    Invoke the PostStepDoIt methods of the specified discrete process 
    (the one selected by the PostStepGetPhysicalInteractionLength, and they 
    return the ParticleChange. The order of invocation of processes is 
    inverse to the order used for the GPIL methods.
    After it for each process the following is executed:
    <itemizedlist spacing="compact">
      <listitem><para>
        Update PostStepPoint of Step according to ParticleChange 
      </para></listitem>
      <listitem><para>
        Update G4Track according to ParticleChange after each PostStepDoIt
      </para></listitem>
      <listitem><para>
        Update safety after each invocation of PostStepDoIts
      </para></listitem>
      <listitem><para>
        The secondaries from ParticleChange are stored to SecondaryList
      </para></listitem>
      <listitem><para>
        Then for each secondary:
        <itemizedlist spacing="compact">
          <listitem><para>
            It is checked if its kinetic energy is smaller than the energy 
            threshold for the material. In this case the particle is assigned a 0. 
            kinetic energy and its energy is added as deposited energy of the 
            parent track. This check is only done if the flag ApplyCutFlag is set 
            for the particle (by default it is set to 'false' for all particles, 
            user may change it in its G4VUserPhysicsList). 
            If the track has the flag IsGoodForTracking 'true' this check will 
            have no effect (used mainly to track particles below threshold)
          </para></listitem>
          <listitem><para>
            The parentID and the process pointer which created this track are set
          </para></listitem>
          <listitem><para>
            The secondary track is added to the list of secondaries. If it has 0. 
            kinetic energy, it is only added if it it invokes a rest process at 
            the beginning of the tracking
          </para></listitem>
        </itemizedlist>
      </para></listitem>
      <listitem><para>
        The track status is set according to what the process defined
      </para></listitem>
    </itemizedlist>
  </para></listitem>
</itemizedlist>
</para>

<para>
The method <literal>G4SteppingManager::InvokeAtRestDoIts</literal> is called 
instead of the three above methods in case the track status is 
<emphasis role="bold">fStopAndALive</emphasis>. It is on charge of selecting 
the rest process which has the shortest time before and then invoke it:

<itemizedlist spacing="compact">
  <listitem><para>
    To select the process with shortest tiem, the AtRestGPIL method of all 
    active processes is called. 
    Each process returns an lifetime and the minimum one is chosen.
    This method returm also a G4ForceCondition flag, to indicate if the process 
    is forced or not:
        = Forced    : Corresponding AtRestDoIt is forced.
        = NotForced : Corresponding AtRestDoIt is not forced 
                      unless this process limits the step.
  </para></listitem>
  <listitem><para>
    Set the step length of current track and step to 0.
  </para></listitem>
  <listitem><para>
    Invoke the AtRestDoIt methods of the specified at rest process, and they 
    return the ParticleChange. The order of invocation of processes is 
    inverse to the order used for the GPIL methods.
    </para>
    <para>
    After it for each process the following is executed:
    <itemizedlist spacing="compact">
      <listitem><para>
        Set the current process as a process which defined this Step length.
      </para></listitem>
      <listitem><para>
        Update the G4Step information by using final state information of the 
        track given by a physics process. This is done through the 
        UpdateStepForAtRest method of the ParticleChange.
      </para></listitem>
      <listitem><para>
        The secondaries from ParticleChange are stored to SecondaryList
      </para></listitem>
      <listitem><para>
        Then for each secondary:
        <itemizedlist spacing="compact">
          <listitem><para>
            It is checked if its kinetic energy is smaller than the energy 
            threshold for the material. In this case the particle is assigned a 0. 
            kinetic energy and its energy is added as deposited energy of the 
            parent track. 
            This check is only done if the flag ApplyCutFlag is set for the 
            particle (by default it is set to 'false' for all particles, user may 
            change it in its G4VUserPhysicsList). 
            If the track has the flag IsGoodForTracking 'true' this check will 
            have no effect (used mainly to track particles below threshold)
          </para></listitem>
          <listitem><para>
            The parentID and the process pointer which created this track are set
          </para></listitem>
          <listitem><para>
            The secondary track is added to the list of secondaries. If it has 0. 
            kinetic energy, it is only added if it it invokes a rest process at 
            the beginning of the tracking
          </para></listitem>
        </itemizedlist>
      </para></listitem>
      <listitem><para>
        The track is updated and its status is set according to what the process 
        defined
      </para></listitem>
    </itemizedlist>
  </para></listitem>
</itemizedlist>
</para>

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.DsgnFuncTracking.OrderPhysProc">
<title>
Ordering of Methods of Physics Processes
</title>

<para>
The ProcessManager of a particle is responsible for providing the 
correct ordering of process invocations.  <literal>G4SteppingManager</literal> 
invokes the processes at each phase just following the order given 
by the ProcessManager of the corresponding particle. 
</para>

<para>
For some processes the order is important.
Geant4 provides by default the right ordering. 
It is always possible for the user to choose the order of process 
invocations at the initial set up phase of Geant4. 
This default ordering is the following:

<orderedlist spacing="compact">
  <listitem><para>
    Ordering of GetPhysicalInteractionLength 
    <itemizedlist spacing="compact">
      <listitem><para>
        In the loop of GetPhysicalInteractionLength of AlongStepDoIt, 
        the Transportation process has to be invoked at the end.
      </para></listitem>
      <listitem><para>
        In the loop of GetPhysicalInteractionLength of AlongStepDoIt, 
        the Multiple Scattering process has to be invoked just before 
        the Transportation process.
      </para></listitem>
    </itemizedlist>
  </para></listitem>
  <listitem><para>
    Ordering of DoIts
    <itemizedlist spacing="compact">
      <listitem><para>
        There is only some special cases. For example, the Cherenkov 
        process needs the energy loss information of the current step 
        for its DoIt invocation. Therefore, the EnergyLoss process has 
        to be invoked before the Cherenkov process. This ordering is 
        provided by the process manager. Energy loss information 
        necessary for the Cherenkov process is passed using G4Step 
        (or the static dE/dX table is used together with the step length 
        information in G4Step to obtain the energy loss information). 
        Any other?
      </para></listitem>
    </itemizedlist> 
  </para></listitem>
</orderedlist>
</para>


<!-- ******* Bridgehead ******* -->
<bridgehead role="revisionHistory" renderas='sect4'>
[Status of this chapter]
</bridgehead>

<para>
<simplelist type="var">
  <member>
    Nov. 1998 created by K. Amako
  </member>
  <member>
    10.06.02 partially re-written by D.H. Wright
  </member>
  <member>
    14.11.02 updated and partially re-written by P. Arce
  </member>
  <member>
    Dec. 2006 Converted from latex to Docbook by K. Amako
  </member>
</simplelist>
</para>

</sect2>
</sect1>