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.
General information about the need of calibration in the MuonSpectrometer.
A clear Wiki page on the Calibration Framework by Domizia and Niels can be found on the MuonCalibrationFramework Wiki. At this site, the Calibration EDM is explained.
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
In order to get started one should know that this field is prone to many changes over time. Backward compatibility is surely broken since the ntuple format changed a lot in the period of november 2005. The ntuple format is defined by the MuonCalib package (MuonCalibNtuple), and the analysis package needs a certain ntuple format to be able to fill the MuonCalib EDM classes offline. In the following sections, recipes will be provided for different kinds of ntuple formats.
To summarize the procedure:
- Choose your ntuple-format and wich version to run in
- Follow the recipes below to make your ntuple, customize jobOption file where needed
- Build the appropriate version of the CalibSegmentAnalysis package (depending on ntuple format)
- Run your analysis, customize the analyse routine where needed
Different versions of Ntuple Content
Currently, there are two different formats of the Calibration Segment Ntuple, described in the following tables:
- Calibration Segment Ntuple Content A. Information on patterns, segments en Mdt hits. All segments appear twice on the ntuple since a refit-flag is performed during ntuple-writing. This ntuple should be obsolete since release 11.X.0.
- Calibration Segment Ntuple Content B. Information on patterns, segments and hits of all technologies (Mdt's containing extra calibration information, the other technologies are not yet fully implemented). No extra refit is performed, so no double segments. In addition, truth information and event information (run and event number) is available.
- Calibration Segment Ntuple Content C. Is non-existent at the moment. It is sure that one will be defined in the future, the difference with Ntuple Content B will be a better description of the other technology hits, and timing information on event-level.
Which recipe to use to make the Ntuple
The different formats of Ntuples can be produced with different recipes. The following recipes sets up athena and guides you to running the Muon Calibration package. With this running you can proceed to the next section below.
- Recipe for Ntuple A in 10.5.0 Works out-of-the-box though outdated
- Recipe for Ntuple A in 11.0.0 Works out-of-the-box though outdated
- Recipe for Ntuple B in 11.0.0 This recipe requires MuonCalib to be checked out of CVS and to be recompiled. This is a time-costly procedure, but the best available until a newer release is present. RECOMMENDED
- Recipe for Ntuple B in 11.X.0 This release has the new MuonCalib compiled so this should run out-of-the-box.
A deeper look into the jobOptions
- For version 10.5.0: a good example of a jobOptions file that produces segment ntuples is provided in Domizia's public:
cp /afs/cern.ch/user/d/domizia/public/MuonCalib_files/myTopOptions.py .
- For version 11.0.0: 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/MuonCalib_files/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 produced, one can proceed Athena-independent.
A little word about 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 linked segments, as potential tracks, containing information such as the Chi Squared of the pattern, the track parameters (z0, r0, , , 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
Since there exists two ntuple formats, different versions of the CalibNtupleAnalysis package exist. Recipes to run the skeleton analysis are given here:
- CalibNtupleAnalysis-00-00-01 Capable of processing ntuple format A
- CalibNtupleAnalysis-00-00-02 Capable of processing ntuple format B
- 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 SegmentsDisplays.
Customizing your favorite analysis
A skeleton needs some 'meat'... Some example routines will be provided:
plotATLAS(MuonCalibSegment*) 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(MuonCalibSegment*) Dumps MdtCalibSegment information. Invaluable for debugging. refitSegment(MuonCalibSegment) Refits the MdtCalibSegment with a DCSLFitter provided by the Calibration framework. showSegment(MuonCalibSegment*) 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(MuonCalibSegment*) 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(MuonCalibSegment*) 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.