MuonCalib Tutorial

Muon calibration tutorial

Welcome to the Muon Calibration Tutorial Page! After doing this tutorial, you will be able to run Athena, make your ntuples containing segment information. This ntuple can then be used as input to do analysis with help of the skeleton analysis package provided. This analysis package CalibSegmentAnalysis relies heavily on the Calibration framework but is Athena independent.

Much information on validation, calibration and alignment can be found at the MuonSpectrometer homepage.

Introduction

Calibration

General information about the need of calibration in the MuonSpectrometer.

Calibration framework

A clear Wiki page on the Calibration Framework by Domizia and Niels can be found on the MuonCalibrationFramework Wiki.

Why segments?

Maybe needed to explain the concept of segments and the calibration EDM, is to be written (work in progress). A starting point of Calibration Segments and its scope in the Reconstruction EDM can be found in a presentation given by Zdenko during the ATLAS Muonweek september-2005 called Calibration Segment Ntuple

Making segment ntuples

Setting up ATHENA

Making segment ntuples from scratch can be done with Athena running on release 10.5.0 or higher. It is recommended to run at the most recent release, in order to be up-to-date. If you do not have an ATLAS account yet you can get an account here.

The content of the Calibration Segment Ntuple can be found [MuonCalib_NtupleContent here].

The content of the ntuple described in the Calibration Segment Ntuple talk is not available in release 11.0.0 . In order to be able to make ntuples is this format one should use more recent versions of MuonCalib. These have to be checked out from CVS and to be recompiled in the right order (in order to set the libraries in the right way).

• log on to lxplus:

ssh <username>@lxplus.cern.ch

• create a work area (here called 11.0.0)

mkdir 11.0.0

cd 11.0.0/

• create a requirements file which should look like this:

set          CMTSITE          CERN

macro        ATLAS_DIST_AREA  "/afs/cern.ch/atlas/software/dist"
macro        ATLAS_RELEASE    "11.0.0"

use          AtlasSettings v* $(ATLhttp://agenda.cern.ch/fullAgenda.php?ida=a057588AS_DIST_AREA)

path_remove  CMTPATH          ${PWD}
path_prepend CMTPATH          ${PWD}

• build your CMT environment:

source /afs/cern.ch/sw/contrib/CMT/v1r18p20050501/mgr/setup.(c)sh

cmt config

source setup.(c)sh -tag=opt

• the last command line must be typed in every time you open a new terminal. If you want to fill your ntuple with segments from ATLAS reconstructed muons check out the RecExCommon package. For other environments (such as CTB etcetera take a closer look at the MuonCalibrationFramework page.

cmt co Reconstruction/RecExample/RecExCommon (at head) or

cmt co -r RecExCommon-version Reconstruction/RecExample/RecExCommon for your favorite version. Currently, the head version of RecExCommon fails to run quickly. A working version is for instance RecExCommon-00-04-20.

• build RecExCommon

cd Recontruction/RecExample/RecExCommon/RecExCommon-*/cmt

cmt config

source setup.(c)sh

gmake

• go to the run directory and load some auxilliary libraries:

cd ../run/

source ../share/RecExCommon_links.(c)sh

• now we can run Athena, provided to have the right jobOptions files. (The following command dumps the messages and writes them to the logfile.)

athena jobOptions.py | tee athena.log

Running on single muons samples

• a good example of a jobOptions file that produces segment ntuples is provided in Zdenko's public:

cp /afs/cern.ch/user/z/zvankest/public/myTopOptions.py .

• you can customize this jobOption file to your own needs...

Change the number of events in the ntuple
Change the tracking software (Moore <-> MuonBoy, and Jochem's cosmic pattern finder package in the future)
Change the muon-sample (note! The file should be present in your PoolFileCatalog):
        in your run directory, add the file to your PoolFileCatalog by calling
              pool_insertFileToCatalog <physical path of your favorite POOL file>
        in your myTopOptions.py, replace the following line
              PoolRDOInput = [ "rfio:/castor/*/*.pool.root" ]
        by
              PoolRDOInput = [ "<POOl file path>" ]

From the ntuple on, we can operate Athena-independent.

Segment analysis

The Calibration Event Data Model (EDM)

The MuonCalibration-framework works with a Calibration EDM, which defines the objects used in the Calibration. The structure is more or less like this:

• each event contains a certain number of Patterns. Concider these as potential tracks, containing information such as the Chi Squared of the pattern, the track parameters (z0, r0, $\vartheta$, $\varphi$, q/p). These patterns are described in the class MuonCalib::MuonGlobalPattern. Patterns are built from a number of segments.

• a segment is described by MuonCalib::MuonCalibSegment, which is basically a line segment which matches the hits stored in the segment. So segments describe the premature track at chamber level. A line is given by a vector and a direction. This information can be found on the segment as well, in two co-ordinate systems: the global ATLAS co-ordinates and the local chamber co-ordinates.

• the hits on the segment are implemented as MuonCalib::XxxCalibHitBase 's with Xxx the technology which recorded the hits (i.e. Mdt, Tgc, Csc or Rpc). Each hitBase has their own dedicated content relevant for doing calibration; thus RPCs do not have drifttimes and MDTs do not provide timemeasurements. They do have common members such as (local en global) position and MuonCalib::MuonFixedId 's. Since the Calibration EDM classes are Athena-independent, the identifiers defined for the hit classes are decoupled from the ATLAS data-base (which is Athena-dependent).

In order to do an analysis on segment level from the ntuple, the content from the ntuple must be casted into the Calibration EDM. This can be done with help of a skeleton analysis package.

The CalibNtupleAnalysis package

<<work in progress>> At this moment, the tarfile containing the CalibNtupleAnalysis package treats ntuples made by release 10.5.0 and 11.0.0 without updated Calibration Service. Since half november 2005, the content of the Calibration Segment Ntuple has changed, causing a mismatch of ntuple format of what the analysis package expects. This will be repaired before the 5th of december .

The 'old MuonCalib ntuple' contains only patterns, segments and Mdthits (called 'hits'). The 'new MuonCalib ntuple' contains the information given above.

This package consists of a number of objects:

CalibNtupleAnalysis

                   NTReader                    Reads the ntuple and stores events in Calibration EDM classes
                   MuonCalibEvent              Container class for the MuonCalib::MuonGlobalPatterns
                   SegmentAnalysis             Steers the analysis performed on the ntuple

Setting up the analysis package

• go to your work space at your ATLAS account

cd 11.0.0/

• get the CalibNtupleAnalysis package (in the future this can be checked out from the release):

cp ~zvankest/public/CalibNtupleAnalysis.tgz

• and get the hacked MuonSpectrometer/MuonCalib/MuonCalibEventBase package from the same place. This is needed because some incompatibility problems of the MuonCalibEvent class and the MuonGlobalPattern class. In the future this won't be needed, so bear with this for the moment.

cp ~zvankest/public/MuonSpectrometer.tgz

• unpack the tarred files

tar -xvfz <package>.tgz

• An example of an analysis is given in the executable exe/Main.cxx. Try running it after building the package:

cd CalibNtupleAnalysis/v*/cmt/

cmt config

source setup.(c)sh

gmake

../i686-slc3-gcc323-opt/Run.exe

• After a succesfull Run, you will be provided with the following files:

SegmentAnalysis.root               Containing the Histograms and SegmentDisplays generated by the 
                                   SegmentAnalysis framework. Note that one event may generate over
                                   100 segments.

Customizing your favorite analysis

A skeleton needs some 'meat'... Some example routines will be provided:

plotATLAS(MdtCalibSegment*)         Plots the hits on the segment in global coordinates. In the example
                                    an extra feature is shown; one can select MDTchambers by stationtype
                                    with a simple call on the MuonFixedId.
dumpSegment(MdtCalibSegment*)       Dumps MdtCalibSegment information. Invaluable for debugging.
refitSegment(MdtCalibSegment)       Refits the MdtCalibSegment with a DCSLFitter provided by the 
                                    Calibration framework.
showSegment(MdtCalibSegment*)       Calls a simple eventdisplay in which the hits are drawn as drifcircles
                                    and the segment as line. The displays can be written to a PSfile.
circleResidual(MdtCalibSegment*)    Given the trackparameters and the hits on the segment, this routine
                                    calculates the expected residuals by extrapolating the track in the
                                    local y-z plane in which the driftradii of the hits are circles.
stripResidual(MdtCalibSegment*)     Given the trackparameters and the hits on the segment, this routine
                                    calculates the expected residuals by extrapolating the track in the
                                    local x-y plane in which the RPC strips are the precision coordinates.