MCFast Utilities

July 3, 1998

The subroutines described below are found in: $MCFAST_DIR/simulator/util/src

Notice that many of the routines below end in a suffix _d; these routines operate on real*8 arguments and return real*8 values. There are corresponding routines with the suffix _f which operate on real*4 arguments and return real*4 values.

This convention was a short lived abberation from the standard MCFast convention of using the compile time parameter DFLOAT to determine the precision.

In general, routines returning a status code as a function value use the convention that 0 is success.

If the description here is a little vague, further details can probably be found in the source file.

Operations on 3-vectors and 4-vectors

The following routines take either 3 vectors or 4 vectors as their input, where the expected orders are (px,py,pz) and (px,py,pz,e). Of course a 4-vector is a perfectly good 3 vector argument and a wtrack is a perfectly good 3-vector or 4-vector arguement. In all cases the code checks for precision problems which might lead to sqrt(negative), log(0.0) or division by zero. Remember that this can mask real problems which lead to the above conditions for reasons other than precision problems.

beta_d:: Return the value of beta ( relativistic v/c ) of a momentum 4 vector.
real*8 function beta_d ( p )
real*8 p(4)
beta_gamma_d:: Return the value of relativistic beta*gamma of a momentum 4 vector.
real*8 function beta_gamma_d ( p )
real*8 p(4)
cos_d:: Return the value of the cosine of the polar angle of a 3 vector.
real*8 function cos_d ( p )
real*8 p(4)
eta_d:: Return the value of the pseudo-rapidity of a 3 vector.
real*8 function eta_d ( p )
real*8 p(3)
pt_d:: Return the value of the momentum transverse to the z direction of a 3 vector.
real*8 function pt_d ( a )
real*8 a(4)
v3mag_d:: Return the magnitude of a 3-vector.
real*8 function v3mag_d ( a )
real*8 a(3)
v4mag_d:: Return the magnitude of a 4-vector.
real*8 function v4mag_d ( a )
real*8 a(4)
sum_4_vectors_d:: Compute the sum of n 4 vectors.
subroutine sum_4_vectors_d ( n, psum, p1, p2, .... )
integer n
real*8 psum(4), p1(4), p2(4)

The sum is accumulated in a running sum will work:
real*8 psum(4), p(4,10)
do i = 1, 10
if ( .... ) call sum_4_vectors_d ( 2, psum, psum, p(1,i) )
sum_4vec_cov_d:: Compute the sum of n 4 vectors. Also compute the covariance matrix of the sum.
subroutine sum_4vec_cov_d ( n, m, psum, vsum, p1, v1, p2, v2, ... )
integer n, m
real*8 psum(4), p1(4), p2(4)
real*8 vsum(m,4), v1(m,4), v2(m,4)

As above, one can accumulate a running sum with this routine.
proper_decay_time:: Compute proper decay time, without error.
function proper_decay_time ( p, d )

! Return value, 4-momentum and decay length.
DFLOAT proper_decay_time, p(4), d

Theta, eta, and all that

The functions in this section convert among the various measures of the polar angle.

cos_to_cot_d:: Convert cosine to cotangent.
real*8 function cos_to_cot_d ( cos )
real*8 cos
cos_to_eta_d:: Convert cosine to psuedo rapidity.
real*8 function cos_to_eta_d ( cos )
real*8 eta
cot_to_cos_d:: Convert cotangent to cosine.
real*8 function cot_to_cos_d ( cot )
real*8 cot
eta_to_cos_d:: Convert eta to cosine.
real*8 function eta_to_cos_d ( eta )
real*8 eta
phi_small:: Take a value of phi and return it in the range [-pi,pi].
function phi_small(arg)
DFLOAT phi_small, arg
phi_norm:: Take a value of phi and return it in the range [0,2.*pi].
function phi_norm(arg)
DFLOAT phi_small, arg

Error propagation

Compute various quantities and the errors on those quantities.

calc_dkl_d:: Compute a decay length and its error.
Mode=0 do not compute the error.
Mode=1 compute the error.
subroutine calc_dkl_d ( mode, x1, v1, x2, v2, dist, sdist )
integer mode
real*8 x1(3), v1(3,3)
real*8 x2(3), v2(3,3)
real*8 dist, sdist
err_mass:: Compute the mass of a 4 vector and the error on the mass. The first argument specifies the first dimension of the covariance matrix so that p can either be an array of dimension 4 or it can be a wtrack and v can be a 7x7 covariance matrix.
integer function err_mass( na, p, v, m, vm)
integer na
real*8 p(4), v(na,4), m, vm
err_p:: Compute the error on the magnitude of a 3 vector. Again the covariance matix is variably dimensioned to allow several sorts of inputs.
real*8 function err_p( na, p, v )
integer na
real*8 p(3), v(na,3)
err_tau:: Compute the proper time of a decay and the error on the proper time. It is assumed that the trajectory of the track is a straight line.
integer function err_tau ( w, wcov, v, vcov, tau, sigtau )
! B candidate and its full covariance matrix,
record /wtrack_struct/ w
DFLOAT wcov(7,7)

! Main vertex and its covariance matrix.
DFLOAT v(3), vcov(3,3)

! Proper decay time and its error.
DFLOAT tau, sigtau
wtk_impact_3d:: Given a wtrack and a vertex, compute the 3D distance of closest approach (DCA) between the line and the point. If requested, also compute the error on this distance, using the covariance matrices of the line and the point. The code works in an arbitrarily oriented magnetic field, so long as the field is constant along the trajectory from the intial point to the PCA.

integer function wtk_impact_3d ( mode, w, wcov, m, mcov, dd, err_dd )

! 0= do not compute error. 1= do compute error.
integer mode

! Track and its covarinace matrix.
record /wtrack_struct/ w
real*8 wcov(7,7)

! Vertex and its covariance matrix.
real*8 m(3), mcov(3,3)

! Output value and its error.
real*8 dd, err_dd
wtk_impact_3d_line:: Linear approximation to the previous routine.

integer function wtk_impact_3d_line ( mode, w, wcov, m, mcov, dd, err_dd )

See above for meaning of arguments.
wtk_impact_2d_line:: Given a straight line and a point, compute the 2D distance of closest approach (DCA) between the line and the point ( in the x-y plane ). If requested, also compute the error on this distance, using the covariance matrices of the line and the point.

integer function wtk_impact_2d_line ( mode, w, wcov, m, mcov, dd, err_dd )

Arguments have same meaning as for previous two routines.

Mass and Vertex Fitters

The mass fitter and vertex fitters which operate in the mcfast environment are found in:
$MCFAST_DIR/simulator/vertex/src
Documentation for these fitting routines is available, as are some examples which exercise them.

Conversions among Track Representations

MCFast supports three different representations of tracks, ctk, ftk, wtk. The first is a helical representation and is used during track fitting in central detectors. The second is a forward representation which is used, not too surprisingly, in the forward tracking fitters. After the fits are completed, the tracks are always converted to the wtk format, which is a 4-vector and a space point. This is the format in which the offline track bank is stored and is also the format used by all of the examples.

The detailed descriptions of these formats are found in:
$MCFAST_DIR/inc/event/ctrack_struct.inc
$MCFAST_DIR/inc/event/ftrack_struct.inc
$MCFAST_DIR/inc/event/wtrack_struct.inc

Two things to watch for when comparing to code used by other experiments. The ctk representation uses the CLEO mystery factor of 2 in the definition of the curvature: that is the curvature is 1/(diameter of curvature), not 1/(radius of curvature). The ftk representation uses 1/p_z, not 1/p, as its bending parameter.

cvt_ctk_ftk:: Convert ctrack to ftrack.
cvt_ctk_wtk:: Convert ctrack to wtrack.
cvt_ftk_ctk:: Convert ftrack to ctrack.
cvt_ftk_wtk:: Convert ftrack to wtrack.
cvt_wtk_ctk:: Convert wtrack to ctrack.
cvt_wtk_ftk:: Convert wtrack to ftrack.
ccov_to_wcov:: Convert ctrack covariance matrix to wtrack format.
fcov_to_wcov:: Convert ftrack covariance matrix to wtrack format.
wcov_to_ccov:: Convert wtrack covariance matrix to ctrack format.
wcov_to_fcov:: Convert wtrack covariance matrix to ftrack format.
wcov_to_wcov_point:: Transport wtrack covariance matrix to a different space point.

Track Transport

Below is the start of a list describing the track transport routines:

move_ctk_point.F: Transform ctrack to have a new local origin. This is the same as doing a vacuum transport of the track from the PCAO of the first system to the PCAO of the second. ( PCAO = point of closest approach, in the r-phi plane, to the local z axis. )
move_ctk_point_cov.F: the same, but also transform the covariance matrix.

Lynn Garren garren@fnal.gov

Rob Kutschke kutschke@fnal.gov

Patricia McBride mcbride@fnal.gov