Read me file for CandFitTrackMS package.

by Tom Bringley

last edited on 8/17/01

they fixed the geometry problem - they just need to rebuild all of the 
root files.  i think this should be done by monday.

now, on to the readme:


The general idea:

the CandFitTrackMS package fits CandTracks and creates CandFitTracks.
i.e.  it finds the initial momentum, position, and trajectory
of the particle - generally a muon - that made the track.  it does
this by looking at how the particle curves in the magnetic field of
the detector - and at how much it scatters.


The classes:

the controller for the class is the FitTrackMSListModule - meaning you 
call it and it calls and does everything else.  so - if
you've already created CandTracks - all you need to do is call the
FitTrackMSListModule::Reco function from your job control script to
run this package.

look on the web to find out about job control scripts.  or look at the 
ones i have made -- anything that is a .jcm file.  there are some also 
in the macros directory of the main code.

so - look on the web users manual to see how this module ends up creating
a CandFitTrackList and gives it to the Minos Object Mapper (MOM).
its a somewhat complicated process, but its essentially the same for
all modules like this.

this is the stuff we went over in my code:

the gyst is:

the FitTrackMSListModule gets a CandTrackList from the MOM - which is
just a collection of objects that you can access.  it then
calls a function called MakeCandidate which makes a CandFitTrackMSList
by running an AlgFitTrackMSList and giving it the CandTrackList.  this 
algorithm, though, just creates a bunch of CandFitTrackMSs by calling
AlgFitTrackMS and compiles them into a list.  its this last algorithm
which does all the work.


the algorithm:

it's controlled by the AlgFitTrackMS::RunAlg method.  from there, the
algorithm is pretty self explanatory.  the code is heavily commented - 
so make sure to read that.  the algorithm itself is pretty standard
and procedural.  it creates some data members of AlgFitTrackMS for
storing info and passing it between functions.


problems with the algorithm:

most of these are mentioned in the comments in the code, but lets list 
them here anyway.

- the ROOT linear algebra package is a piece of crap, so there are
some workarounds to deal with the large matrices we are using.  first
- the TCL class is used to invert the matrix.  this 
requires writing the matrix first to a fortran style.  second - we
need the matrix determinant.  lots of problems doing this have forced
me to use a constant of proportionality instead of an actual
determinant.

- the value of the radiation length and the dE/dx constant are
hard-coded in and still seem to be having problems.  currently, i am
using Roy Lee's values from FitTrackSRListModule.  these are in the
form of X0 per plane and energy loss per plane, which is too ambiguous 
in my opinion - but i've tried to copy what he did.  as of now, it
doesnt look like it is working.

- the charge determination is screwy.  currently we're running the fit 
for both + and - charge and taking the best one.  we can improve
this.

- the MC truth table is currently set up to give the momentum of the
muon with the highest energy in the event as the true momentum for any 
track in the event.  this is a problem when there are more than one
tracks.  may be able to fix this by looking at initial trajectory or
something.  all this stuff is in the CandEventSR package in the
EventSRListModule.cxx file.  it's pretty complicated.  i've already
modified the file a bit too - so use my version instead of the one in
the main code.  talk to roy lee about this.  he's been pretty helpful.

- other stuff -- code needs to be prettier.  adding ability to change
the constants "on the fly" by setting their values in a job control
script would be ideal and easy to do.

- can always improve the momentum convergence.

- need to get the right answer.


analysis stuff:

i've created the fitTrackMS.jcm file which runs the job after running
Roy Lee's reconstruction packages and finally creates ntuples with the 
CandEventSR package.  i've modified the CandEvertSR package slightly
to get the right monte carlo and to automatically create an error in
1/p plot for easy testing.

so - running fitTrackMS.jcm with demojob -bqx fitTrackMS.jcm creates 2 
output files.  

eventsr.root creates the ntuples.  use root to look at them.  the
pdiff plot is the error in 1/p.  when plotting anything, i suggest
cutting such that it only takes events where pdiff!=0.  this excludes
events that didnt have tracks.  also - sometimes the fit fails and the 
program default uses the length determination of the momentum.  when
it does this, it sets the trkq variable to +2.0.  also - if the track
has over 400 hits the program has been running out of memory and dying 
- so any track that large also uses the length determination.  the
trkq variable is then set to -2.0.

so - to get only the events in which the fit did not fail and there
were tracks - use the cut:
"pdiff!=0&&trkq!=-2&&trkq!=2"


as of now - the IRIX version of demojob still does not work.  so -
i've been testing on Linux, which does not let you run a job for more
than 30 minutes.  to get around this, i've created some scripts which
break large jobs into pieces and run them one piece at a time.

this method uses a template job control script fitTrackMSt.jcm that
skips a variable number of records before running.  the method is
controled by the file driverscript which sets the number of records
for the template to skip, runs the job, and saves the output files.

to run this way - edit fitTrackMSt.jcm and driverscript to use the
right root file and write to the right directory etc.  then run:
source driverscript

then - to look at the results - in root run:
.x makeHists.C(n)  where n is the number of eventsr.root files that
you have - or want to include in the histograms.  this creates 3
histograms - pdiff (the error on 1/p), trke (the fit momentum), and
stdhepe (the true momentum).  you can access them by those names, and
use them like any other histogram.

to create your own histogram use:
.x histsr.C(n,"equation","weight/cut equation",lower bound,upper bound) 

put in the equations you want and it will create the histogram and be
available at the variable hist.

edit these files to make them do other stuff - they are pretty makeshift.



the other output file the gets created is fitTrackMS.root.  this file
contains TPolyLine3D objects with show the hit and the fit.  to look
at these - in root, run:
.x runShowFit.C("fitTrackMS.root")

this calls showFit.C for each event.  you can look at them in order,
or at random access.  this is good for testing if the fits are
reasonable - this viewing macro needs some improvement too.

as of now, however, this just shows the fit for the last trial - so,
because mu minus is tested before mu plus (see the algorithm) - if the 
particle has negative charge this display will not look right.


a note:  a new fitTrackMS.root is not created every time a job is run
- it just keeps adding events to the existing one.



well - that's about it.  getting the hang of this will take some
looking at the code.

some things to work on that i'd suggest:

obviously, fixing some of the major problems.

try to do fits where you put in either no B field effects or no MS
effects - this can be done easily by multiplying by zero at a couple
of places. -- use this to break down the problem.

look at lots of histograms with various cuts to see if we can somehow
predict whether we'll get a good fit.

do some MC analysis to get an accurate dE/dx.  you can set the nofit
variable to true and it will use the length momentum determination.
Roy had some thing where he corrected the length determination by
adding or subtracting a factor -- look into that.

look at the data in terms of the charge determination.  you can make a 
histogram of "trkq/stdhepid*13" which will be +1 if you got the right
charge and -1 if you got the wrong charge and something else if the
particle was not a muon or the fit was bad.  use this to make cuts.


oh - to compile your changes...  save all the code files and go to the 
main test directory -- i.e. the one with the fitTrackMS.jcm file in it 
- and run:
gmake all

on the web there are more instruction for how to commit to CVS etc.

well - i'm sure i'm forgetting a whole bunch of stuff but that's ok.
email me any time you have a question.

thanks a lot.

Tom