Tracker Geometry Comparison Tool

Complete: 4


The goal of this tool is to be able to compare any two tracker geometries (built from a set of alignment constants). The idea is to have as general a functionality as possible for such a tool:

  • Can compare alignables at any hierarchy level
  • Can eliminate global displacements (both rotations and translations) at any level so that we can find relative displacements of any structure w.r.t to any other higher level structure
  • Allow to compare structures not created in the hierarchy
  • Allow for easy plotting
  • Provide tables of the shifts and mean positions

For the impatient user, go directly to the recipe.


As a small cartoon, we include an graphical example of how the tool would work:


In the cartoon, we emphasize the ability to get rid of a global shift of a certain structure to examine the structure at a lower hierarchical level.

Technical Implementation

There are three parts to running the tool:

  • Inputting the alignment constants to create the geometry
  • Configuring the tool to examine the hierarchical level you want
  • Output ROOT file for plotting

ROOT Inputs

The current tool allows for ROOT storage file inputs. The tool no longer supports POOLORA database file inputs.

The comparison tool reads in all the alignment constants stored in a standard ROOT input file. To create a standard ROOT input file, there is a class, TrackerGeometryIntoNtuples, located in the package Alignment/OfflineValidation. This class takes a POOLORA database file and turns it into a ROOT file. The advantage being that one does not need special configuration to read in multiple geometries. The comparison tool takes into its configuration 2 ROOT storage files, converts them into two different tracker geometries, and compares.

Configuration of Comparison Tool

Configuration of the Module

The full configuration of the comparison module can be found at Alignment/OfflineValidation/python/ The configuration is as follows:

TrackerGeometryCompare = cms.EDFilter("TrackerGeometryCompare",
    writeToDB = cms.untracked.bool(False),
    outputFile = cms.untracked.string('output.root'),
    setCommonTrackerSystem = cms.untracked.string('NONE'), ##must be "NONE" if you don't want to use this option

    detIdFlag = cms.untracked.bool(False),
    detIdFlagFile = cms.untracked.string('blah.txt'),
    weightById = cms.untracked.bool(False),
    #   untracked vstring levels = {"PixelEndcap","PixelHalfBarrel","TID","HalfBarrel","Endcap","DetUnit"}
    levels = cms.untracked.vstring('Det'),
    weightBy = cms.untracked.string('DetUnit'),
    weightByIdFile = cms.untracked.string('blah2.txt'),
    treeName = cms.untracked.string('alignTree'),
    inputROOTFile1 = cms.untracked.string('IDEAL'),
    inputROOTFile2 = cms.untracked.string('idealtracker2.root'),
   moduleList = cms.untracked.string('moduleList.txt')
Explaining the parameters, we have:

  • inputROOTFile1 is the filename for the first ROOT input, "IDEAL" means you are using the design geometry and does not require a ROOT input
  • inputROOTFile2 is the filename for the second ROOT input, "IDEAL" means you are using the design geometry and does not require a ROOT input
  • outputFile is the filename of the output file where all comparisons are stored, more details in the Output section.
  • treeName is the name of the tree in the ROOT file, usually do not touch
  • levels are the hierarchical levels being considered in the comparison, more details in Choosing Hierarchies section.
  • moduleList is a list of modules that can be given to the tool to be plotted in a different style (e.g. bad modules). Default is an empty list.
  • writeToDB is a bool parameter, true if you would like to write out inputROOTFile2 to a sqlite database file AFTER doing the comparison to inputROOTFile1
  • setCommonTrackerSystem is a string parameter corresponding to a specific hierarchy level where you can set a common system between two geometries, usually used with writeToDB=true. As an example, to configure it such that we set a common reference as pixel barrel, write out the object and nothing else, the following parameters set are: setCommonTrackerSystem = "TPBBarrel"; writeToDB = True; levels = []

The following additional options can be given via the compare:Tracker section in the configuration of the All-In-One Meta Tool:

  • modulesToPlot is a parameter to choose which modules are plotted. There are three categories: modules with a bad quality tag, modules from a given list and "good" modules which do not fall into one of the previous categories. Parameter can be all, list (good modules and those in the list are plotted), and good (only good modules plotted)
  • useDefaultRange: If this is set to true, modules in the y-range 200 mu (mu*rad) for translations and 100 mrad for rotations are taken into account. The default value is false which means all modules are plotted except for variables where an individual min/max of the range is given.
  • var_min/max is the min/max value of a difference for which modules are taken into account. Possible variables are dx, dy, dz, dr, rdphi, dalpha, dbeta, and dgamma (e.g. dx_min, dx_max). Signs are taken into account (so min values should usually be negative). It is possible just to set the upper/lower edge for a variable and not to change the other one. var_min/max overrides the ranges given by useDefaultRange
  • plotPng is a switch to choose whether png plots are created. These plots look nicer than pdf but take a lot more time. If one just wants to check something and is not interested in nicely looking plots, this switch can be set to false to reduce the running time of the tool significantly. Default value is true.
  • plotOnlyGlobal is a switch to reduce the number of produced plots. If it is set to true only the summary plots (global_tracker, global_PXB, ...) are created. Default value is false.
  • makeProfilePlots is a switch to produce "profile plots" that contain the mean and standard deviation for all modules in a certain x-bin. Default value is true. A PR containing these plots is running. A working version in 90X can be found here

For expert use, these parameters are usually not used:

  • detIdFlag/detIdFlagFile are parameters which can be used to flag certain modules for later use
  • weightBy/weightByIdFile are parameters which can be used to weight specific modules differently (default is to take each module with equal weight)

Choosing Hierarchies
The configuration parameter, levels, is used to choose hierarchies to overlay and is a vector of strings of the hierarchical objects. We start with the highest level hierarchical objects and work our way down to the lowest level objects. For example, a configuration of {"Tracker", "TPEEndcap", "Det"} will have the following functionality:

  1. Overlay the entire Trackers over each other and write their relative global displacement to the output ROOT file
  2. After overlaying the Trackers, overlay the Pixel Endcaps over each other and write their relative global displacement to the output ROOT file
  3. After overlaying the Pixel Endcaps, overlay all the Dets on top of their corresponding Dets and write their relative global displacement to the output ROOT file

Note the inputROOTFile1 is considered the reference geometry and the inputROOTFile2 is overlaid onto the first geometry.

For each structure that is compare, a set of data is stored into output file. The idea is to have as much information stored into the output tree such that plotting can be as general as possible. Differences are calculated by value(reference geometry) - value(second geometry). The output tree is currently configured to have these branches:

  • raw ID: for composites, this will be the raw ID of its lowest first daughter in 17X and above
  • mother's raw ID: -1 for the AlignableTracker
  • alignable object ID: the ID which determines its level of hierarchy
  • mother's alignable object ID: -1 for the AlignableTracker
  • sublevel: the subdetID that the alignable belongs to
  • inModuleList: Check if the module is in a list given by the user
  • badModuleQuality: Check if the module quality tag is bad
  • X, Y, Z, R, Φ: the global position of the object (read from the global tag of the reference geometry)
  • α, β, γ: the global orientation of the object (read from the global tag of the reference geometry)
  • Δ X, Δ Y, Δ Z, Δ R, Δ Φ: displacement of the alignable in the global reference frame
  • Δ α, Δ β, Δ γ: rotational displacement of the alignable in global reference frame
  • Δ u, Δ v, Δ w: translational displacement of the alignable in local reference frame
  • Δ a, Δ b, Δ g: rotational displacement of the alignable in local reference frame
  • identifiers: 6 numbers which can identify the module based on which sublevel it lives. Based on individual subdetector IDs for pixels and strips.
    • PXB: (module, ladder, layer, NaN, NaN, NaN)
    • PXF: (module, panel, blade, disk, side, NaN)
    • TIB: (module, string, string_fw_bw, string_int_ext, layer, NaN)
    • TID: (module, module_fw_bw, ring, wheel, side, NaN)
    • TOB: (module, rod, rod_fw_bw, layer, NaN, NaN)
    • TEC: (module, ring, petal, petal_fw_bw, wheel, side)
The next set of branches is only for use by the visualization package:
  • surL : surface length
  • surW : surface width
  • surRot : matrix which is the orientation of the surface


The geometry comparison tool is included in the All-In-One Meta Tool and should be used via this tool.

cmsrel CMSSW_X_Y_Z
cd CMSSW_X_Y_Z/src
git cms-addpkg Alignment/OfflineValidation
scram b -j 4
rehash    # for csh
hash -r   # for sh

Alignment/OfflineValidation/scripts/ -N <task_name> -c geometry_comparison.ini -m --getImages

The .ini file has to contain a compare:Tracker section and to follow the convention of the all-in-one-tool.

For important CMSSW versions there is often an existing version of the all-in-one-tool in the common validation area.

Using the Geometry Comparison Plotter from the common repository on lxplus

Load CMSSW_7_2_1_patch1_AlignmentCamp to produce the Geometry Comparison Plots (working area is /afs/

Here is a procedure to produce a GCP:

  • Load the right CMSS version with in the src directory with cmsenv
  • copy mp1687/geometry_comparison.ini in your mpXXXX directory
    • if necessary, specify the general output directory of the GCP utility at the line
            datadir = /afs/$USER/output_geometry_comparison
    • add a slot for the current geometry you want to compare with such information such as, e.g.
            globaltag = GR_P_V49::All
            condition TrackerAlignmentRcd           = sqlite_file:/afs/, Alignments_2
            condition TrackerSurfaceDeformationRcd  = sqlite_file:/afs/, Deformations_2
            condition TrackerAlignmentErrorRcd      = zeroAPE
            color = 2
            style = 1
      where the sqlite file alignments_split_MP.db is to be found in the mpXXXX/jobData/jobm directory, the number X of Aligments_X and Deformations_X corresponding to the index of the IOV as deduced from mpXXXX/alignables.txt (to see explicitely the structure of file, use the command cmscond_list_iov -a -c "sqlite_file:alignments_split_MP.db")
    • change the last line and compare the geometries of interest using their correct labels.
  • run the geometry_comparison.ini with the command -N \<new_directory\> -c geometry_comparison.ini -m --getImages where \<new_directory\> corresponds to the subdirectory of the directory defined at the beginning of the geometry_comparison.ini file.
  • wait a few minutes (note: there may appear some error messages, but they are not to be necessarily taken into account ... the currently only way to now wether it worked or not is to check in the final directory if the GCP files have indeed been produced).

Using the Geometry Comparison Plotter in CMSSW_7_4_X and upwards

From CMSSW_7_4_0 upwards an extended version of the muon and tracker APE replaces the non extended one which was used before. The same is true for the corresponding global tags. Therefore, there is no downward compatibility when using older global tags (previous to e.g. GR_P_V53). For an overview of the recommended global tags see Global Tags for Conditions Data .

The updated version of the tool is included from CMSSW_7_4_5_patch1 and 7_5_0_pre6 upwards and can be used via the All-In-One Meta Tool, following the recipe.

A working environment can also be found in /afs/


There are a few options to visualize the results of a geometry comparison.

  1. Alignment/OfflineValidation/scripts/compareTrackerGeometries.C: 3x3 matrix of plots in cylindrical plots - a quick and dirty script
  2. Alignment/OfflineValidation/scripts/makeArrowPlots.C: visualizes the difference between two geometries as arrows per module in various 2D slices
  3. Alignment/OfflineValidation/scripts/visualizationTracker.C: visualizes the differences as a 3D interactive plot using the ROOT geometry package


A few noteworthy topics. There is a known rounding precision on the order of 1e-2 microns which is neglible for alignment purposes, but one might see it when doing comparisons. There are some common ROOT storage files that one might need a lot such as the ideal geometry. So that it does not have to be created several times, some are located in ~ntran/public/ROOTStorageFiles . Ideal geometries for 13X, 16X, and 17X are there as well as the new realistic misalignment scenarios implemented by Zijin Guo.


Here we present an example of the final output of the tool. The study here is to perform comparison of different ideal geometries from different CMSSW releases (link to this twiki). After running the comparison tool, we printed out the variables Δ R, Δ Z, Δ Φ versus R, Z, Φ.

Review Status

Editor/Reviewer and Comments Comments
NhanTran - 11 and 12 Oct 2007 page author
JennyWilliams - 12 Oct 2007 minor wikiword, type and swguide edits

Responsible: NhanTran

Topic attachments
I Attachment History Action Size Date Who Comment
PNGpng cartoon.png r1 manage 42.8 K 2007-10-11 - 20:19 NhanTran shows functionality of tool
PNGpng fpixcompare.png r1 manage 161.8 K 2007-10-11 - 21:01 NhanTran fpix comparison
Unix shell scriptsh r1 manage 2.7 K 2008-07-09 - 16:45 GeroFlucke transforms older sqlite files for use in >= CMSSW_2_X_X
Edit | Attach | Watch | Print version | History: r39 < r38 < r37 < r36 < r35 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r39 - 2017-05-17 - ChristianSchomakers

    • 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-2021 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
or Ideas, requests, problems regarding TWiki? use Discourse or Send feedback