Misalignment Tools [CMSSW]

Complete:

Goal of this page

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

Introduction

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:

process.AlignmentProducer.doMisalignmentScenario=True
process.AlignmentProducer.applyDbAlignment=True
from Alignment.TrackerAlignment.Scenarios_cff import *
process.AlignmentProducer.MisalignmentScenario = <YourScenario>
process.AlignmentProducer.saveToDB=True
process.AlignmentProducer.saveApeToDB=True

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 ( for the tracker or 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 and the muon system . They are then used in the .cfi.py files of the ESProducer for the muon system and the tracker , respectively (or in the AlignmentProducer ).

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 , 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):
    • TOBBarrel → TOBHalfBarrel, → TOBLayer → TOBRod → Det → DetUnit
    • TIBBarrel → TIBHalfBarrel → TIBLayer → TIBHalfShell → TIBSurface → TIBString → Det → DetUnit
    • TIDEndcap → TIDDisk → TIDRing → TIDSide → Det → DetUnit
    • TECEndcap → TECDisk → TECSide → TECPetal → TECRing → Det → DetUnit
      • 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:
    • TPBBarrel → TPBHalfBarrel → TPBLayer → TPBLadder → DetUnit
    • TPEEndcap → TPEHalfCylinder → TPEHalfDisk → TPEBlade → TPEPanel → DetUnit
  • 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:
  • DTBarrel → DTWheel → DTStation → DTChamber → DTSuperLayer → DetUnit
  • CSCEndcap → CSCStation → CSCRing → CSCChamber → DetUnit
  • 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

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.

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 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 )

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.load("Alignment.TrackerAlignment.MisalignedTracker_cfi")
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