source: trunk/documents/UserDoc/DocBookUsersGuides/ForApplicationDeveloper/xml/TrackingAndPhysics/trackErrorPropagation.xml @ 1208

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

<para>
The error propagation package serves to propagate one particle together with its error from a given trajectory state until a user-defined target is reached (a surface, a volume, a given track length,...).
</para>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.G4Error.Physics">
<title>
Physics
</title>

<para>
The error propagator package computes the average trajectory that a particle would follow.  
This means that the physics list must have the following characteristics:
</para>

<itemizedlist>
<listitem> No multiple scattering </listitem>
<listitem> No random fluctuations for energy loss </listitem>
<listitem> No creation of secondary tracks </listitem>
<listitem> No hadronic processes </listitem>
</itemizedlist>

<para>
It has also to be taken into account that when the propagation is done backwards (in the direction opposed to the one the original track traveled) the energy loss has to be changed into an energy gain. 
</para>

<para>
All this is done in the <literal>G4ErrorPhysicsList</literal> class, that is automatically set by <literal>G4ErrorPropagatorManager</literal> as the GEANT4 physics list. 
It sets <literal>G4ErrorEnergyLoss</literal> as unique electromagnetic process. This process uses the GEANT4 class <literal>G4EnergyLossForExtrapolator</literal> to compute the average energy loss for forwards or backwards propagation. 
To avoid getting too different energy loss calculation when the propagation is done forwards (when the energy at the beginning of the step is used) or backwards (when the energy at the end of the step is used, always smaller than at the beginning) <literal>G4ErrorEnergyLoss</literal> computes once the energy loss and then replaces the original energy loss by subtracting/adding half of this value (what is approximately the same as computing the energy loss with the energy at the middle of the step). 
In this way, a better calculation of the energy loss is obtained with a minimal impact on the total CPU time.
</para>

<para>
The user may use his/her own physics list instead of <literal>G4ErrorPhysicsList</literal>. As it is not needed to define a physics list when running this package, the user may have not realized that somewhere else in his/her application it has been defined; therefore a warning will be sent to advert the user that he is using a physics list different to <literal>G4ErrorPhysicsList</literal>. If a new physics list is used, it should also initialize the <literal>G4ErrorMessenger</literal> with the classes that serve to limit the step:

<informalexample>
<programlisting>
  G4ErrorEnergyLoss* eLossProcess = new G4ErrorEnergyLoss;
  G4ErrorStepLengthLimitProcess* stepLengthLimitProcess = new G4ErrorStepLengthLimitProcess;
  G4ErrorMagFieldLimitProcess* magFieldLimitProcess = new G4ErrorMagFieldLimitProcess;
  new G4ErrorMessenger( stepLengthLimitProcess, magFieldLimitProcess, eLossProcess );
</programlisting>
</informalexample>

</para>

<para>
To ease the use of this package in the reconstruction code, the physics list, whether <literal>G4ErrorPhysicsList</literal> or the user's one, will be automatically initialized before starting the track propagation if it has not been done by the user.
</para>

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.G4Error.TrajState">
<title>
Trajectory state
</title>

<para>
The user has to provide the particle trajectory state at the initial point. 
To do this it has to create an object of one of the children classes of <literal>G4ErrorTrajState</literal>, providing: 
</para>

<itemizedlist>
<listitem> Particle type </listitem>
<listitem> Position </listitem>
<listitem> Momentum </listitem>
<listitem> Trajectory error matrix </listitem>
</itemizedlist>

<informalexample>
<programlisting>
 G4ErrorTrajState( const G4String&amp; partType, 
                   const G4Point3D&amp; pos, 
                   const G4Vector3D&amp; mom, 
                   const G4ErrorTrajErr&amp; errmat = G4ErrorTrajErr(5,0) );
</programlisting>
</informalexample>

<para>
A particle trajectory is characterized by five independent variables as a function of one parameter (e.g. the path length).
Among the five variables, one is related to the curvature (to the absolute value of the momentum), two are related to the direction of the particle and the other two are related to the spatial location. 
</para>

<para>
There are two possible representations of these five parameters in the error propagator package: as a free trajectory state, class <literal>G4ErrorTrajStateFree</literal>, or as a trajectory state on a surface, class <literal>G4ErrorTrajStateonSurface</literal>. 
</para>


<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.G4Error.TrajState.FreTrajState">
<title>
Free trajectory state
</title>

In the free trajectory state representation the five trajectory parameters are

<itemizedlist>
<listitem> G4double fInvP </listitem> 
<listitem> G4double fLambda </listitem> 
<listitem> G4double fPhi </listitem> 
<listitem> G4double fYPerp </listitem> 
<listitem> G4double fZPerp </listitem> 
</itemizedlist>

<para>
where <literal>fInvP</literal> is the inverse of the momentum.
<literal>fLambda</literal> and <literal>fPhi</literal> are the dip and azimuthal angles related to the momentum components in the following way:
</para>

<literal>
            p_x = p cos(lambda) cos(phi)
            p_y = p cos(lambda) sin(phi)   
            p_z = p sin(lambda) 
</literal>

<para>
that is, <literal>lambda = 90 - theta</literal>, where <literal>theta</literal> is the usual angle with respect to the Z axis.
</para>

<para>
<literal>fYperp</literal> and <literal>fZperp</literal> are the coordinates of the trajectory in a local orthonormal reference frame with the X axis along the particle direction, the Y axis being parallel to the X-Y plane (obtained by the vectorial product of the global Z axis and the momentum).
</para>
</sect3>

<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.G4Error.TrajState.SurfaceTrajState">
<title>
Trajectory state on a surface
</title>

<para>
In the trajectory state on a surface representation the five trajectory parameters are
</para>

<itemizedlist>
<listitem> G4double fInvP </listitem> 
<listitem> G4double fPV </listitem> 
<listitem> G4double fPW </listitem> 
<listitem> G4double fV </listitem> 
<listitem> G4double fW </listitem> 
</itemizedlist>

<para>
where <literal>fInvP</literal> is the inverse of the momentum;
<literal>fPV</literal> and <literal>fPW</literal> are the momentum components in an orthonormal coordinate system with axis U, V and W; 
<literal>fV</literal> and <literal>fW</literal> are the position components on this coordinate system.
</para>

For this representation the user has to provide the plane where the parameters are calculated. 
This can be done by providing two vectors, V and W, contained in the plane:

<informalexample>
<programlisting>
  G4ErrorSurfaceTrajState( const G4String&amp; partType,
                           const G4Point3D&amp; pos,
                           const G4Vector3D&amp; mom, 
                           const G4Vector3D&amp; vecV,
                           const G4Vector3D&amp; vecW,
                           const G4ErrorTrajErr&amp; errmat = G4ErrorTrajErr(5,0) );
</programlisting>
</informalexample>

 or by providing a plane

<informalexample>
<programlisting>
  G4ErrorSurfaceTrajState( const G4String&amp; partType, 
                           const G4Point3D&amp; pos,
                           const G4Vector3D&amp; mom, 
                           const G4Plane3D&amp; plane,
                           const G4ErrorTrajErr&amp; errmat = G4ErrorTrajErr(5,0) );
</programlisting>
</informalexample>

In this second case the vector V is calculated as the vector in the plane perpendicular to the global vector X (if the plane normal is equal to X, Z is used instead) and W is calculated as the vector in the plane perpendicular to V. 

</sect3>
</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.G4Error.Err">
<title>
Trajectory state error
</title>

<para>
The 5X5 error matrix should also be provided at the creation of the trajectory state as a <literal>G4ErrorTrajErr</literal> object. 
If it is not provided a default object will be created filled with null values.
</para>

<para>
Currently the <literal>G4ErrorTrajErr</literal> is a <literal>G4ErrorSymMatrix</literal>, a simplified version of <literal>CLHEP HepSymMatrix</literal>. 
</para>

<para>
The error matrix is given in units of GeV and cm. Therefore you should do the conversion if your code is using other units.
</para>

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.G4Error.Target">
<title>
Targets 
</title>

<para>
The user has to define up to where the propagation must be done: the target. 
The target can be a surface <literal>G4ErrorSurfaceTarget</literal>, which is not part of the GEANT4 geometry. 
It can also be the surface of a GEANT4 volume  <literal>G4ErrorGeomVolumeTarget</literal>, so that the particle will be stopped when it enters this volume.
Or it can be that the particle is stopped when a certain track length is reached, by implementing a <literal>G4ErrorTrackLengthTarget</literal>.
</para>


<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.G4Error.Target.SurfaceTarget">
<title>
Surface target
</title>

When the user chooses a <literal>G4ErrorSurfaceTarget</literal> as target, the track is propagated until the surface is reached. 
This surface is not part of GEANT4 geometry, but usually traverses many GEANT4 volumes.
The class <literal>G4ErrorNavigator</literal> takes care of the double navigation: for each step the step length is calculated as the minimum of the step length in the full geometry (up to a GEANT4 volume surface) and the distance to the user-defined surface. 
To do it, <literal>G4ErrorNavigator</literal> inherits from <literal>G4Navigator</literal> and overwrites the methods <literal>ComputeStep()</literal> and <literal>ComputeSafety()</literal>.

Two types of surface are currently supported (more types could be easily implemented at user request): plane and cylindrical.

<!-- ******************* Section (Level#4) ****************** -->
<sect4 id="sect.G4Error.Target.SurfaceTarget.PlaneSurfaceTarget">
<title>
Plane surface target
</title>

<literal>G4ErrorPlaneSurfaceTarget</literal> implements an infinite plane surface.
The surface can be given as the four coefficients of the plane equation <literal>ax+by+cz+d = 0</literal>:

<informalexample>
<programlisting>
    G4ErrorPlaneSurfaceTarget(G4double a=0, 
                              G4double b=0,
                              G4double c=0, 
                              G4double d=0);
</programlisting>
</informalexample>

or as the normal to the plane and a point contained in it:

<informalexample>
<programlisting>
    G4ErrorPlaneSurfaceTarget(const G4Normal3D &amp;n,
                              const G4Point3D &amp;p);
</programlisting>
</informalexample>

or as three points contained in it:

<informalexample>
<programlisting>
    G4ErrorPlaneSurfaceTarget(const G4Point3D &amp;p1,
                              const G4Point3D &amp;p2,
                              const G4Point3D &amp;p3);
</programlisting>
</informalexample>
</sect4>

<!-- ******************* Section (Level#4) ****************** -->
<sect4 id="sect.G4Error.Target.SurfaceTarget.CylSurfaceTarget">
<title>
Cylindrical surface target
</title>

<literal>G4ErrorCylSurfaceTarget</literal> implements an infinite-length cylindrical surface (a cylinder without end-caps).
The surface can be given as the radius, the translation and the rotation

<informalexample>
<programlisting>
    G4ErrorCylSurfaceTarget( const G4double&amp; radius,
                             const G4ThreeVector&amp; trans=G4ThreeVector(),
                             const G4RotationMatrix&amp; rotm=G4RotationMatrix() );
</programlisting>
</informalexample>

or as the radius and the affine transformation

<informalexample>
<programlisting>
    G4ErrorCylSurfaceTarget( const G4double&amp; radius,
                             const G4AffineTransform&amp; trans );
</programlisting>
</informalexample>

</sect4>

</sect3>

<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.G4Error.Target.VolumeTarget">
<title>
Geometry volume target
</title>

<para>
When the user chooses a <literal>G4ErrorGeomVolumeTarget</literal> as target, the track is propagated until the surface of a GEANT4 volume is reached. User can choose if the track will be stopped only when the track enters the volume, only when the track exits the volume or in both cases.
</para>

The object has to be instantiated giving the name of a logical volume existing in the geometry:

<informalexample>
<programlisting>
  G4ErrorGeomVolumeTarget( const G4String&amp; name );
</programlisting>
</informalexample>

</sect3>

<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.G4Error.Target.TrkLenTarget">
<title>
Track Length target
</title>

<para>
When the user chooses a <literal>G4ErrorTrackLengthTarget</literal> as target, the track is propagated until the given track length is reached.
</para>

The object has to be instantiated giving the value of the track length:
<informalexample>
<programlisting>
  G4ErrorTrackLengthTarget(const G4double maxTrkLength );
</programlisting>
</informalexample>

<para>
It is implemented as a <literal>G4VDiscreteProcess</literal> and it limits the step in <literal>PostStepGetPhysicalInteractionLength</literal>. 
To ease its use, the process is registered to all particles in the constructor.
</para>

</sect3>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.G4Error.Propagation">
<title>
Managing the track propagation
</title>

<para>
The user needs to propagate just one track, so there is no need of run and events. neither of <literal>G4VPrimaryGeneratorAction</literal>.

<literal>G4ErrorPropagator</literal> creates a track from the information given in the <literal>G4ErrorTrajState</literal> and manages the step propagation. 
The propagation is done by the standard GEANT4 methods, invoking <literal>G4SteppingManager::Stepping() </literal> to propagate each step. 
</para>

<para>
After one step is propagated, <literal>G4ErrorPropagator</literal> takes cares of propagating the track errors for this step, what is done by <literal>G4ErrorTrajStateFree::PropagateError()</literal>.
The equations of error propagation are only implemented in the representation of  <literal>G4ErrorTrajStateFree</literal>. 
Therefore if the user has provided instead a <literal>G4ErrorTrajStateOnSurface</literal> object, it will be transformed into a <literal>G4ErrorTrajStateFree</literal> at the beginning of tracking, and at the end it is converted back into <literal>G4ErrorTrajStateOnSurface</literal> on the target surface (on the normal plane to the surface at the final point).
</para>

<para>
The user <literal>G4VUserTrackingAction::PreUserTrackingAction( const G4Track* )</literal> and  <literal>G4VUserTrackingAction::PreUserTrackingAction( const G4Track* )</literal> are also invoked at the beginning and at the end of the track propagation. 
</para>

<para>
<literal>G4ErrorPropagator</literal> stops the tracking when one of the three conditions is true:

<itemizedlist>
<listitem> Energy is exhausted </listitem>
<listitem> World boundary is reached </listitem>
<listitem> User-defined target is reached  </listitem>
</itemizedlist>

In case the defined target is not reached, <literal>G4ErrorPropagator::Propagate()</literal> returns a negative value.
</para>

<para>
The propagation of a trajectory state until a user defined target can be done by invoking the method of <literal>G4ErrorPropagatorManager</literal>
<informalexample>
<programlisting>
  G4int Propagate( G4ErrorTrajState* currentTS, const G4ErrorTarget* target, 
                   G4ErrorMode mode = G4ErrorMode_PropForwards );
</programlisting>
</informalexample>
</para>

You can get the pointer to the only instance of <literal>G4ErrorPropagatorManager</literal> with

<informalexample>
<programlisting>
  G4ErrorPropagatorManager* g4emgr = G4ErrorPropagatorManager::GetErrorPropagatorManager();
</programlisting>
</informalexample>

Another possibility is to invoke the propagation step by step, returning control to the user after each step. This can be done with the method

<informalexample>
<programlisting>
  G4int PropagateOneStep( G4ErrorTrajState* currentTS,
                          G4ErrorMode mode = G4ErrorMode_PropForwards );
</programlisting>
</informalexample>

In this case you should register the target first with the command

<informalexample>
<programlisting>
  G4ErrorPropagatorData::GetG4ErrorPropagatorData()->SetTarget( theG4eTarget );
</programlisting>
</informalexample>
 

<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.G4Error.Propagation.ErrorPropagation">
<title>
Error propagation
</title>

As in the GEANT3-based GEANE package, the error propagation is based on the equations of the European Muon Collaboration, that take into account:

<itemizedlist>
<listitem> Error from curved trajectory in magnetic field </listitem>
<listitem> Error from multiple scattering </listitem>
<listitem> Error from ionization </listitem>
</itemizedlist>

<para>
The formulas assume propagation along an helix.
This means that it is necessary to make steps small enough to assure magnetic field constantness and not too big energy loss.
</para>

</sect3>
</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.G4Error.StepLimits">
<title>
Limiting the step
</title>

There are three ways to limit the step. 
The first one is by using a fixed length value. This can be set by invoking the user command :

<informalexample>
<programlisting>
G4UImanager::GetUIpointer()->ApplyCommand("/geant4e/limits/stepLength MY_VALUE MY_UNIT");
</programlisting>
</informalexample>

The second one is by setting the maximum percentage of energy loss in the step (or energy gain is propagation is backwards). 
This can be set by invoking the user command :

<informalexample>
<programlisting>
G4UImanager::GetUIpointer()->ApplyCommand("/geant4e/limits/energyLoss MY_VALUE");
</programlisting>
</informalexample>

The last one is by setting the maximum difference between the value of the magnetic field at the beginning and at the end of the step. Indeed what is limited is the curvature, or exactly the value of the magnetic field divided by the value of the momentum transversal to the field.
This can be set by invoking the user command :

<informalexample>
<programlisting>
G4UImanager::GetUIpointer()->ApplyCommand("/geant4e/limits/magField MY_VALUE");
</programlisting>
</informalexample>

The classes that limit the step are implemented as GEANT4 processes. Therefore, the invocation of the above-mentioned commands should only be done after the initialization (for example after <literal>G4ErrorPropagatorManager::InitGeant4e()</literal>.

</sect2>
</sect1>