Misalignment Tools [CMSSW]

Complete: 3

Goal of this page

This page describes the TrackerAlignment and CMS.MuonAlignment packages used to produce misalignment scenarios.

Warning, important These tools are not intended for direct use in a misalignment study. The output provided by the tools should be used instead (see SWGuideMisAlignCalib).


Optimal alignment of the detector units of the tracking devices will only be reached after several months of LHC running, and the knowledge of their position and orientation will never be perfect. Misalignment tools have been developed in order to study the impact of this misalignment on Physics analysis.

The tools we describe here allow to modify the ideal geometry according to different "scenarios" reflecting the alignment precision expected at various stages of the experiment. The output is a set of global positions and alignment errors that can then be used in a normal User Job.

General concept

The misalignment tools are implemented in an ESProducer called MisalignedTrackerESProducer or MisalignedMuonESProducer, for the tracker or muon devices, respectively. (During alignment jobs the AlignmentProducer does it in a similar way.) This module first creates the tracker (resp. muon) geometry from the ideal geometry. It then create a hierarchy of alignable structures and modifies it according to a misalignment scenario, in the form of a configuration file. The modification are propagated through the hierarchy to the detector unit level. The output are two POOL-ORA objects: one containing the (new) global positions of all detector units, another one containing the corresponding alignment position errors.

Note 1 In the muon system only DT and CSC are considered by the misalignment tools, the RPC is not affected.

Note 2 If you wanted to start from a geometry different from ideal one (i.e. a DB input files) and apply a misalignment scenario on top of it, you can do this directly in your alignment job (via AlignmentProducer) by configuring:

from Alignment.TrackerAlignment.Scenarios_cff import *
process.AlignmentProducer.MisalignmentScenario = <YourScenario>
taking care that your algorithm does not apply any corrections and save the results into an sqlite file, which can be used as input of your analysis job. Note that in this case even the APE of the scenario will be 'added' to the DB input.

Running the example

The misalignment packages contain a few tests for the tool. In particular, the configuration file test-misalign_cfg.py (CVS for the tracker or CVS for the muon system) will run the misalignment tools and apply one of the scenarios. A root file is created with some quantities related to all detector units in the TOB. An info.txt file contains the details of all applied movements. You can modify the parameters of the _cfi.py files using python syntax as shown in the _cfg.py file (see the SWGuide documentation on Configuration Files for details).

test-misalign_cfg.py can serve as an example of how to misalign the data on the fly (i.e. not using DB objects, so not recommended).

Standard misalignment scenarios

Scenarios are implemented in python/Scenarios_cff.py files both for the tracker CVS and the muon system CVS. They are then used in the .cfi.py files of the ESProducer for the muon system CVS and the tracker CVS, respectively (or in the AlignmentProducer CVS).

More information for the tracker and links to relevant CMS notes can be found here.

Configuration of misalignment

Movements applied to the tracker or the muon system in the misalignment tools are driven by CMSSW configuration files. We describe here how to write such a configuration file. The impatients can jump to the configuration example and come back to details later...

This description refers to CMSSW_4_2_0 and later.

Hierarchical structure

The movements are applied through the hierarchical structure of the tracker and the muon system. The misalignment configuration file reflects this hierarchy in a hierarchy of ParameterSets. The general layout of the PSet passed by MisalignedTrackerESProducer, MisalignedMuonESProducer or AlignmentProducer to the actual helper class interpreting the misalignment is then:

ExampleScenario = cms.PSet(
    <top-level parameters>

    structs = cms.PSet(
       <movements for all struct>
       substructs = cms.PSet(<movements for all substruct> ),
       substruct1 = cms.PSet(<movements for substruct 1> ),
       substruct2 = cms.PSet(<movements for substruct 2>,
                             subsubstructs = cms.PSet(<movements for all subsubstruct of substruct 2>)
       substruct3_5_6 = cms.PSet(<movements for substruct 3, 5 and 6>)

Here, movements are actually any known parameters: parameters defining movements (only applied to current structure), general parameters that are propagated to sub-structures, etc.

The PSet name determines which structure the movements it contains have to be applied to: PSet substruct# will be applied to the #-th sub-structure of struct called substruct (similarly for PSet substruct2_4_5 being applied to 2nd, 4th and 5th sub-structure) , while PSet substructs will be applied to all sub-structures called substruct. (Note that substruct need not be a direct component of struct.)

For example if struct is TIBBarrel, substruct can be TIBHalfBarrel, but also TIBString or even DetUnit. In particular, if a PSet DetUnits is defined at top-level, movements it contains will be applied directly to all detector units of the tracker/muon.

Movements are never added: only the lowest-level definition is kept. In the following example, all rods of barrel layer 1 of the forward TOB are modified by phiXlocal = 0.2 only (see here for definition of parameters):

TOBHalfBarrel1 = cms.PSet(
   TOBRods = cms.PSet(phiXlocal = cms.double(0.3)),
   TOBLayer1 = cms.PSet(
       TOBRods = cms.PSet(phiXlocal = cms.double(0.2)

Hierarchy of structures

  • For the tracker (see CVS, but note that the T*Module levels do not exist):
    • Highest level object is the Tracker, containing Strip and Pixel.
    • The Strip contains (note that Det is missing in 1D strip barrel layers and 1D strip TID/TECRings):
      • TOBBarrelTOBHalfBarrel, → TOBLayerTOBRodDetDetUnit
      • TIBBarrelTIBHalfBarrelTIBLayerTIBHalfShellTIBSurfaceTIBStringDetDetUnit
      • TIDEndcapTIDDiskTIDRingTIDSideDetDetUnit
      • TECEndcapTECDiskTECSideTECPetalTECRingDetDetUnit
        • Note that the numbering of rings is confusing: TECRing1 is always the innermost ring present in the concerned disk wheras "usually" one talks about absolute ring numbering from 1 to 7. This means that "usual" ring 4 is called TECRing4 in TECDisk1_2_3, TECRing3 in TECDisk4_5_6, TECRing2 in TECDisk7_8 and TECRing1 in TECDisk9.
    • The Pixel contains:
      • TPBBarrelTPBHalfBarrelTPBLayerTPBLadderDetUnit
      • TPEEndcapTPEHalfCylinderTPEHalfDiskTPEBladeTPEPanelDetUnit
    • The T*HalfBarrel and T*Endcap structures (TOBHalfBarrel, TECEndcap, etc., except TPBHalfBarrel) have a forward and backward part, denoted as T*1 and T*2, respectively (e.g. TOBHalfBarrel1 and TOBHalfBarrel2). TPBHalfBarrel1 and TPBHalfBarrel2 correspond to the +x and -x shells, respectively.
    • In double-sided strip layers DetUnit1 denotes the r-phi component, while DetUnit2 the stereo one.
    • Note that prior to CMSSW_3_1_0_pre5
      • the hierarchy levels Tracker, Strip, Pixel, TPBBarrel, TOBBarrel and TIBBarrel could not be used,
      • TIBHalfBarrel was TIB, TOBHalfBarrel was TOB, TIDEndcap was TID, TECEndcap was TEC, TPBHalfBarrel was TPB and TPEEndcap was TPE,
      • and TIB, TOB, TID, TEC, TPB and TPE had to be stated as highest level.

  • For the muon devices:
    • DTBarrelDTWheelDTStationDTChamberDTSuperLayerDetUnit
    • CSCEndcapCSCStationCSCRingCSCChamberDetUnit
    • There is special treatment for DTSectors, CSCSectors and Muon not really documented here (these PSets must be given at highest level).
    • The forward muon endcap is denoted by CSCEndcap1, and the backward one by CSCEndcap2.

Order of misalignment

The movements are applied in the following order:

  • global displacements;
  • local displacements;
  • global rotations in order x, y, z;
  • local rotations in order x, y, z.

List of known parameters

Mandatory parameters

The job will throw an exception if these parameters are not defined.

Type Name Description Values Default
int32 seed Random number generator seed. If 0, ask RandomNumberGenerator service No default

Tip, idea The seed parameter is required at top level only.

Parameters that propagate down

These parameters are propagated to components recursively, unless redefined.

Type Name Description Values Default
string distribution Indicates which distribution to use for movements (e.g. phiX=0.1). 'fixed', 'gaussian', 'flat' 'gaussian'
double scale Factor by which movements and errors are scaled. any > 0. 1.
bool setError Switch to set alignment position errors. True or False False
double scaleError Factor by which errors are scaled. any > 0. 1.

Tip, idea If distribution is 'fixed', movements will be applied strictly as defined. Otherwise, a random movement is applied: in case of 'gaussian', the random movement follows a gaussian distribution of σ given by the parameter; in case of 'flat', the random number is in the range defined by the parameter (e.g. ]-phiX,+phiX[).

Parameters that define movements

Type Name Description Values Default Comment
double phiX Rotation angle around global X [rad] any (> 0. if random) 0.  
double phiY Rotation angle around global Y [rad] any (> 0. if random) 0.  
double phiZ Rotation angle around global Z [rad] any (> 0. if random) 0.  
double phiXlocal Rotation angle around local X [rad] any (> 0. if random) 0.  
double phiYlocal Rotation angle around local Y [rad] any (> 0. if random) 0.  
double phiZlocal Rotation angle around local Z [rad] any (> 0. if random) 0.  
double dX Displacement along global X [cm] any (> 0. if random) 0.  
double dY Displacement along global Y [cm] any (> 0. if random) 0.  
double dZ Displacement along global Z [cm] any (> 0. if random) 0.  
double dXlocal Displacement along local X [cm] any (> 0. if random) 0.  
double dYlocal Displacement along local Y [cm] any (> 0. if random) 0.  
double dZlocal Displacement along local Z [cm] any (> 0. if random) 0.  
double localX Rotation angle around local X [rad] any (> 0. if random) 0. (deprecated)
double localY Rotation angle around local Y [rad] any (> 0. if random) 0. (deprecated)
double localZ Rotation angle around local Z [rad] any (> 0. if random) 0. (deprecated)
PSet deformation See below   --- Currently (CMSSW_5_3_X) can only be member of a PSet refering to the hierarchy level DetUnit, i.e. propagating down does not work?!?. Otherwise exception...

The PSet deformation is used to apply SurfaceDeformation corrections to the hit positions (to account for so called bows and kinks, see CMS AN-2011/531). The PSet must contain two parameters:

Type Name Values Comment
string type 'BowedSurfaceDeformation' or 'TwoBowedSurfacesDeformation' see CVS in case this Twiki is outdated
vdouble parameters length 3 for BowedSurfaceDeformation, length 13 for TwoBowedSurfacesDeformation 13th value for TwoBowedSurfacesDeformation must match the position of the y-value of the gap between the sensors (0. for TOB, 0.6 for TEC R7, -0.56 for TEC R6, -0.9 for TEC R5, see CVS )

Other general parameters

The MisalignedTrackerESProducer and MisalignedMuonESProducer have both two parameters:

Type Name Description Values Default in cfi.py
untracked bool saveToDbase Save alignments to the database? (True requires proper configuration of the PoolDBOutputService). True or False False
PSet scenario The PSet descibed above.   no movement

The configuration parameters of the AlignmentProducer steering the use of the misalignment tools are bool doMisalignmentScenario and PSet MisalignmentScenario, see SWGuideAlignmentAlgorithms for more details.

An example

Here is an example configuration:

process.MisalignedTracker.scenario = cms.PSet(
      // -- Top-level --//
      distribution = cms.string('gaussian'),
      seed = cms.int32(0),

      // -- specific -- //
      TOBHalfBarrel1 = cms.PSet(
        TOBLayers = cms.PSet( dXlocal = cms.double(0.1)  ),
        TOBLayer1 = cms.PSet( dXlocal = cms.double(0.2)  ),
        deformations = cms.PSet(type = cms.string('TwoBowedSurfacesDeformation'), # same values will be applied to all DetUnits
                                parameters = cms.vdouble(0.035, 0.025, 0.01, 0.01, 0., 0.015, 
                                                          0.00015, 0.0003, 0.00025, 0.008, 0.005, 0.003, 0.)))
      TOBHalfBarrels = cms.PSet(
        TOBLayer1 = cms.PSet( phiXlocal = cms.double(0.03) ),
        dY = cms.double(0.2)
      Pixel1 = cms.PSet( # or Pixels...
        dZ = cms.double(0.1),
        TPEBlades = cms.PSet(
          dXlocal = cms.double(0.03),
          phiXlocal = cms.double(5.e-4),
          # different random values will be applied to all DetUnits:
          DetUnits = cms.PSet(deformations = cms.PSet(type = cms.string('BowedSurfaceDeformation'),
                                                     parameters = cms.vdouble(0.035, 0.025, 0.01))))

Implementation details

See http://cmssw.cvs.cern.ch/cgi-bin/cmssw.cgi/CMSSW/Alignment/TrackerAlignment/?cvsroot=CMSSW for the tracker misalignment.

See http://cmssw.cvs.cern.ch/cgi-bin/cmssw.cgi/CMSSW/Alignment/MuonAlignment/?cvsroot=CMSSW for the muon misalignment.

Review Status

Editor/Reviewer and date Comments
GeroFlucke - 24 May 2013 Reviewed for CMSSW_5_3_X

Responsible: AndreasMussgiller
Last reviewed by: GeroFlucke - 24-May-2013

Edit | Attach | Watch | Print version | History: r44 < r43 < r42 < r41 < r40 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r44 - 2013-05-24 - GeroFlucke

    • Cern Search Icon Cern Search
    • TWiki Search Icon TWiki Search
    • Google Search Icon Google Search

    CMSPublic All webs login

This site is powered by the TWiki collaboration platform Powered by PerlCopyright & 2008-2019 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback