Alignment Position Error (APE) Estimator

Complete: 4

Goal of this page

Description of the configuration and operation of the tool for estimating the Alignment Position Error (APE).


The tool is called ApeEstimator and resides in Alignment/APEEstimation. The code was implemented into the official release in CMSSW_7_6_0. Working versions can be found for CMSSW_7_4_X, CMSSW_7_5_X. It also uses subtools located in Alignment/CommonAlignmentAlgorithm and Alignment/TrackerAlignment and contains several scripts to run the procedure and to produce validation plots.

Recipe for CMSSW_9_4_X

cmsrel CMSSW_9_4_0_pre3

cd CMSSW_9_4_0_pre3/src


git cms-addpkg Alignment/APEEstimation

git cms-addpkg Alignment/TrackerAlignment

scram b


If you want to run quickly the tool with the current configuration without knowing anything about details, you can read only Setting up the Tool, Scripts for Automated Workflow and Scripts producing Validation Plots, and read the other parts only if you need them.

Setting up the Tool

After setting up the CMSSW area, do the following:

  • bash Alignment/APEEstimation/scripts/initialise.bash

The command creates all relevant folders needed for the outputs, thus automated procedures in the scripts. It also copies some scripts for easier handling.

Now, it is necessary to create a .root-file containing the TTree with all relevant information about the silicon modules of the tracker. This is done by a simple standalone tool named TrackerTreeGenerator, placed in Alignment/TrackerAlignment, which uses the ideal geometry. The ideal geometry is chosen, since it guarantees that selections of modules via their position space coordinates chose always the same modules. E.g. TOB modules on the same rod have the same design position in phi, but misalignment could cause a selection choosing only some modules if the cut is by accident selected around the nominal position. The file is created with:

  • cmsRun Alignment/TrackerAlignment/test/

The .root-file containing the TTree can be found and browsed in Alignment/TrackerAlignment/hists/TrackerTree.root, and there it is read from in the APE calculation.

Now, the tool is set up and the procedure for calculating APEs can be configured and started. However, in order to allow fast iterations and parallelisation, a private skim of the files which should be used is created, as explained in the following step.

Creation of Private Skim

Default Creation

In order to allow parallelisation and fast iterations, a private skim of files is created from the AlCaReco files. The event content is minimised to the needs for the ApeEstimator, a tighter preselection is also applied, and the files are split in size for optimising between number of files and number of events inside. To do so, the file Alignment/APEEstimation/test/batch/skimProducer.bash is run on the batch farm. It uses the configuration in Alignment/APEEstimation/test/SkimProducer/ There, the used track selection is defined in Alignment/APEEstimation/python/, and the trigger selection in Alignment/APEEstimation/python/ The event content is defined in Alignment/APEEstimation/python/

Which dataset to process is steered via a configurable parameter using the VarParsing, which also allows a local test run.

In order to have the file names correct for the automated workflow, it is necessary to run after the skim production the script Alignment/APEEstimation/test/SkimProducer/

After having run those two scripts for each dataset that one wants to process, the skim is ready for the automated workflow of the APE estimation. However, the folder of the CAF user diskpool to store the output, and later read it in, is not automated. This needs to be adjusted by the user.

The APE Estimation Tool

In order to allow parallel processing, the tool is based on two different modules. The first one (ApeEstimator) reads the events and gathers all relevant information in several .root-files. The second one (ApeEstimatorSummary) then calculates the APE values afterwards, requiring to merge the files from the first step. The tool is automated and based on 4 scripts, which need to be run sequentially, starting the next one only after all actions initiated by the previous one have finished successfully. Since the method is a local method, iterations are necessary, so the chain needs to be repeated. In the following, the configuration of the two modules is explained, the scripts to run are explained in a later section.

In general, all configurations should be done in your final, and in Alignment/APEEstimation/test/cfTemplate. The files in Alignment/APEEstimation/python define the configurable parameters, mainly without doing any selection, and should never be changed, they are only templates. The files in the same folder give the default settings, and should only be changed in exceptional cases.

Configuration of ApeEstimator

The ApeEstimator module is coded in Alignment/APEEstimation/plugins/, having the configuration template in Alignment/APEEstimation/python/ with documentation of the configurable parameters, and the default settings in Alignment/APEEstimation/python/

For testing purposes there is one configuration file Alignment/APEEstimation/test/, but the general configuration used in the automated workflow can be found elsewhere as explained later.

Event, Track and Hit Selections

The module contains the possibility of a dedicated hit and cluster selection. However, the cluster selection is common for all pixel modules, respectively common for all strip modules. Some selections are applied to both pixel and strip hits. These selections are based on intervals, you need to specify always pairs of numbers to select specific intervals, e.g for one interval (0.3,0.4) or for three intervals (0.3,0.4, 1.8,1.9,-1.7,-1.5). In case of integers, a single number can be selected by e.g. (3,3). If no number is given, no selection is applied.

The track selection is hardcoded and can only be switched on and off. This has historical reasons, and should probably be excluded, and instead the official AlignmentTrackSelector should be used before the applied refit. This would also guarantee, that the track selection is identical during the iterations, since the change of the APE values might lead to small migrations of the track parameters inside/outside the selection window due to the refit.

Some additional selections and configurations can be applied.

Choose between APE Calculation and Control Plots

Furthermore, there are two important switches, since the module can be used for the calculation of APE values, but also as analyzer only, producing zillions of control plots, including plots for track parameters. Calculating APEs is defined in the as the module ApeEstimator, setting the switch calculateApe = True. Using the analyzer is defined in the as the module ApeAnalyzer, setting the switch analyzerMode = True. In principle, one could use both things simultaneously in one module, but this often makes no sense due to the sector definitions explained later: the APEs should be calculated for the whole tracker, while the huge amount of detailed validation plots should be chosen for some exemplary regions. The APE calculation also contains some validation plots which are in principle not necessary for the calculation, but since these are the most important basic validation plots, they are implemented there in order to understand the general quality of the estimated APEs.

Granularity of APEs: Sector Definition

A group of modules which should be analysed combined, and for which the same APE value is calculated and assigned, is called "sector". The sectors can be defined based on all module information stored in the TTree produced by the standalone tool mentioned above. The sector definitions need to be given to the ApeEstimator using the parameter Sectors, which is a VPSet. An empty template, not selecting anything but defining all selection parameters, is in Alignment/APEEstimation/python/, explaining the possible arguments. Each sector is defined as a PSet, already defined sectors for the subdetectors are given in,,,,, in Alignment/APEEstimation/python. Further subdefinitions should be built in the same way as shown there. It is important to assign to each sector a name reflecting clearly the exact definition, because this can be found in all .root-files and in printouts and also histogram names, in order to see which sector the results are for. All sector definitions are then gathered in the only file to include, Alignment/APEEstimation/python/ There, the two important sector definitions (VPSets) which are used at present can be found, it is ValidationSectors for the tool in analyzer mode having the full set of validation plots, and should contain only those sectors where one wants to have a closer look at, and RecentSectors, which defines the granularity for the APE calculations, and should span the whole tracker.

Configuration of the Cluster Parameter Estimator (CPE)

The configuration of the CPE which should be used in the refit is given in Alignment/APEEstimation/python/ There it is chosen which PixelCPE and which StripCPE should be used. The recent one in use is called TTRHBuilderAngleAndTemplate (from CMSSW_10_0_X on), but of course the parameters can be changed also in the specific, your configuration. But you need to ensure that it is also included in the refit definition, see below.

Configuration of the Refit

The refit itself is also defined in Alignment/APEEstimation/python/ There the CPE has to be specified by its ComponentName, which is for the one mentioned above WithAngleAndTemplate (again, from CMSSW_10_0_X on. For older CMSSW versions, you have to change it manually to WithAngleAndTemplate). Very important parameters which might have an influence on the results are the ones steering the hit rejection (outliers and bad pixel template fits). Again, this can be overwritten in your specific configuration.

For the refitter, a sequence is defined which needs to be included in the, since the refit also needs the offlineBeamSpot. It also contains the selection of tracks flagged as of highPurity, since in many alignment tasks only those are selected, and so it is done here. There, one could also apply the track selection instead of within the ApeEstimator, but in the present configuration this is not done, it selects only for highPurity.

Configuration of the Geometry and the GlobalTag

The global tag and the geometry need to be specified in the But never change the APE, this always has to be the design one with zero APE everywhere. During the iterations of the automated workflow, the correct APE object as created in the previous iteration is taken automatically.


The final output of the ApeEstimator is one file containing the relevant distributions for the second step, the ApeEstimatorSummary, and all validation plots. The output is structured in numerated folders for the defined sectors. Within each folder there is a histogram z_name, which contains only the name given to the sector and allows its identification.

Configuration of ApeEstimatorSummary

The ApeEstimator module is coded in Alignment/APEEstimation/plugins/, having the configuration template in Alignment/APEEstimation/python/ with documentation of the configurable parameters, and the default settings in Alignment/APEEstimation/python/ The module needs as input a file (parameter InputFile) produced with the ApeEstimator.

For testing purposes there is one configuration file Alignment/APEEstimation/test/, but the general configuration used in the automated workflow can be found elsewhere as explained later.

Choose between Calculation of APEs or Setting the Baseline from Design MC

When setting the flag setBaseline = True, the nominal residual width for each defined sector is estimated. I.e. that not APE values are calculated, but the nominal residual width which returns exactly APE=0 is estimated. This should be done on design MC only, to get this as a reference instead of a fixed assumption of the nominal residual width. A .root-file containing a TTree is created, specified by parameter BaselineFile.

If the flag is not set, APEs are calculated. If a baseline .root-file was produced and is specified by BaselineFile, then the nominal residual width is read from this file for each sector. If no such file is found, the assumption of residual width equal to 1 is used for each sector. The calculated APE values are also stored in a TTree of a .root-file, specified by IterationFile. However, this file is not created newly when you run the tool again, since it is used for iterations of the APE. If it is found, the last stored entry is assumed to be the squared APE as estimated in the previous iteration, and the estimated squared correction is added to it and gives the new APE, which is stored as new entry in the TTree. The APE values for each module contained in a sector are written to an ASCII-file specified by ApeOutputFile in the format needed to use the module Alignment/CommonAlignmentAlgorithm/python/ to create a DB object. The configuration of the tool creating the DB object as it is used during the automated workflow can be found in Alignment/APEEstimation/test/cfgTemplate/

Parameters steering the APE Calculation

How the weight of the individual intervals in the residual resolution for the APE calculation within one sector should be estimated is specified by apeWeight, where the variant with "entriesOverSigmaX2" works best.

The minimum number of hits for using an interval in the calculation is defined by minHitsPerInterval.

The parameter sigmaFactorFit was used earlier to use a two-step Gaussian fit procedure, but it caused some instabilities due to obvious non-Gaussian behaviour in several intervals. Thus it is not used at all in the present implementation of the code, except for additional plots. In the recent implementation, a Gaussian is fit to each residual distribution in each interval spanning the full range. This second fit should then fit only the core, with +- the specified factor times the width of the first fit around the mean of the first fit.

The parameter correctionScaling is used as the damping factor to avoid overestimations and thus convergence problems due to the correlations of the APEs of all modules penetrated by a track. The estimated squared correction is scaled with this factor.

The two parameters smoothIteration and smoothFraction should not be used and removed from the code. This was another implementation of the damping factor for the iterations, which is mathematically equivalent.


The output of the tool are the following files. There is a .root-file containing a set of validation plots important for the APE estimate. In the mode setting the baseline, the baseline .root-file mentioned above is produced. In the mode for calculating the APE, the .root-file for the iterations of the APE value and the ASCII-file with the APE values used for producing a DB object as mentioned above is produced. Additionally, a root file similar to the one for the iterations is included which contains the default APEs from the global tag before aplying the tool.

Scripts for Automated Workflow

The automated workflow is based on four scripts, which need to be run in the specific order, starting the next one only after all actions of the previous one have finished successfully. They are run for each iteration, and do the following action:

  • createStep1.bash iterationNumber [ lastIteration ]
This produces all relevant scripts defining the ApeEstimator step. It creates scripts for parallel processing, one for each regarded skimmed file. The scripts can be found in Alignment/APEEstimation/test/batch/workingArea/. It is the only script which needs to be adjusted, the other three are identical for each possible operation. The samples which should be read, and the alignment geometry, are specified here. But in fact, there are only parameters specified which are then used in the config template Alignment/APEEstimation/test/cfgTemplate/, using the VarParsing. So what is really selected is coded in the config template.

  • startStep1.bash
The scripts produced in the previous step are sent to the batch farm, i.e. the ApeEstimator is run parallelised, based on the config template Alignment/APEEstimation/test/cfgTemplate/ In order to gain speed, the optimised skimmed files as explained above are copied to the batch machine and processed there locally. The output is stored in Alignment/APEEstimation/hists/workingArea/.

  • createStep2.bash iterationNumber [ setBaseline ]
This script does all necessary preparatory action for the final calculations. The final output directory is created which is specific for baseline setting or APE calculation mode, and in the latter case also to the iteration number. All .root-files which are the result of the first step are merged using hadd, the merged file is moved to the final output directory. The script needed for the second iteration is created, which is Alignment/APEEstimation/test/batch/workingArea/summary.bash. The script is based on the template Alignment/APEEstimation/test/cfgTemplate/summaryTemplate.bash. In case of iterations the .root-file containing the APE value of the previous iteration is copied to the final output directory.

  • startStep2.bash
This script runs the script prepared in the previous step. This means running the ApeEstimatorSummary based on the template Alignment/APEEstimation/test/cfgTemplate/, and the output is stored in the final output directory created in the previous step. Furthermore, in case of APE calculation mode, it runs the creation of the DB object, based on the template Alignment/APEEstimation/test/cfgTemplate/ Finally it does a cleanup of all scripts used in this iteration (produced in the two create-steps). In case of the creation of a DB object for the APEs (APE calculation mode), the printout of the cmsRun job shows one error. This is expected, since the DB object creation is based on the AlignmentProducer, which is a generic tool and expects some information which is not given and not necessary for writing the APE object. The DB object should be created correctly.

The way of how to use these scripts is explained in the following for setting the baseline respectively calculating APEs.

Set Baseline from Design Simulation

The scripts are in Alignment/APEEstimation/test/cfgTemplateDesign/. But only the createStep1.bash is also in this folder in the release, the others are copied from Alignment/APEEstimation/test/cfgTemplate/, since they are identical for all possible operations.

The scripts need to be run only once, since iterations make no sence for setting the baseline. Do the following steps:

  • cd Alignment/APEEstimation/test/cfgTemplateDesign/workingArea/
  • bash ../createStep1.bash 0
  • bash ../startStep1.bash
  • bash ../createStep2.bash 0 True
  • bash ../startStep2.bash

The final output directory where all files end up is Alignment/APEEstimation/hists/Design/baseline/.

Calculate APE Parameters

There is one directory prepared for calculating APEs on MC using misaligned geometries, and one directory for calculating APEs on data. Depending on what you want to analyse, do for MC:

  • cd Alignment/APEEstimation/test/cfgTemplateMc/workingArea/

or do for real data:

  • cd Alignment/APEEstimation/test/cfgTemplateData/workingArea/

The relevant scripts are placed in this folder, but only the createStep1.bash is also in this folder in the release, the others are copied from Alignment/APEEstimation/test/cfgTemplate/, since they are identical for all possible operations.

For all but the last iteration, do the following steps, where iterationNumber needs to be replaced by the number of the iteration, starting with 0:

  • bash ../createStep1.bash iterationNumber
  • bash ../startStep1.bash
  • bash ../createStep2.bash iterationNumber
  • bash ../startStep2.bash

For the last iteration, do:

  • bash ../createStep1.bash iterationNumber True
  • bash ../startStep1.bash
  • bash ../createStep2.bash iterationNumber
  • bash ../startStep2.bash

In the first iteration (called iteration 0), also validation plots of the analyzer mode of ApeEstimator are created automatically. During the iterations, this is not done, only the relevant things for the iterations are produced. If you specified your last iteration as stated above, again a set of validation plots is created. This allows the comparison and the automated production (see later) of validation plots, comparing the distributions before iterations (with APE=0) to distributions after iterations (final APE as estimated by the tool). The tool is normally used with 15 iterations, so running iteration 0,...14 with the first set of commands, and then running iteration 15 with the second set of commands. This very last iteration (called iteration 15) is not to do another iteration, but to get the validation on the APE after the 15 iterations 0,...14. If you would like to use another number of iterations, it is not a problem, but some of the automated scripts producing validation plots as explained later need to be adjusted.

Be aware that the APE DB object of the iteration called iteration 14 is your final result, and not the APE DB object of the one called iteration 15!

All output except of the DB object is stored in Alignment/APEEstimation/hists/workingArea/iter*/, where the * corresponds to the number of the given iteration. The important ones are iter0 (containing the validations with zero APE), iter14 (containing the results concerning the estimated final APE values), and iter15 (containing the validations with the final APE).

The DB objects are stored in Alignment/APEEstimation/hists/apeObjects/. Always use the one named apeIter14.db as final result, the one named apeIter15.db is only produced due to the automation.

For a more automated workflow there are scripts which can be run via

  • bash ../run15Iterations.bash


  • bash ../run10Iterations.bash

if one finds that 10 iterations are sufficient. These scripts automatically sleep until the sent batch jobs are finished. If one wishes to manually set the sleep time for batch jobs to finish, one can instead run

  • bash ../run10Iterations_manual.bash
  • bash ../run15Iterations_manual.bash

depending on the desired number of iterations.

Scripts producing Validation Plots

Scripts for producing validation plots based on root-macros can be found in Alignment/APEEstimation/macros/. There are two different scripts to run. First do:

  • cd Alignment/APEEstimation/macros/

The first script produces all validation plots of iteration 0, and prints them in .pdf-files. This is done for the design MC (the baseline), and for the geometry under study (data or misaligned MC). They are mainly used for optimising the track and hit selection. These validation plots can only be obtained for the sectors which are defined in the analyzer mode module of the ApeEstimator, but there are also files with specific validation plots which are produced for each sector defined in the APE calculation of the ApeEstimator. To produce them run:

  • bash ./

The output is stored in Alignment/APEEstimation/hists/plots/, the subfolder ideal/ contains those of the design MC, the subfolder data/ those of the geometry under study.

The other script produces single .eps-files containing one histogram each, and overlays them for design geometry, and geometry under study. These are the most important plots, but others could in principle be added in the root-macros. To produce them run:

  • bash ./
  • bash ./

The output is stored in Alignment/APEEstimation/hists/workingArea/iter*/plots/, where the * stands for 0, 14 or 15, corresponding to the iteration where they are obtained from. They are sorted in subfolders. Important are the following plots in the following subfolders.

  • The calculated APE values can be found in iter14/plots/result/.
  • The important validation plots are in iter15/plots/Sector/ and iter15/plots/Track/.
  • For the modelling of data, look at iter0/plots/Sector/ and iter0/plots/Track/.

The last bullet (iter0) is not that important, since the distributions are also overaid in the the one above (iter15), together with the distributions of the final APE. But there the distributions are not scaled to integral, in order to see the absolute number of events/tracks/hits, thus the statistics of the modelling.

If one wants to overlay the resulting APE values for different geometries, this can be done with the corresponding root-macro, no explicit script exists. The macro is Alignment/APEEstimation/macros/commandsDrawComparison.C.

Addtional Tools

The following tools are not needed for measuring Ape or creating validation plots but provide extra functions that are useful.

Writing and reading Ape payloads

Using Alignment/APEEstimation/test/, one can read/write Ape payloads from/to db files. This is useful if one wishes to define a custom Ape based on measurements. The Ape payloads themselves are configured in Alignment/APEEstimation/macros/writeAPEsInASCII.C, where one can set the individual Ape values for an arbitrary granularity. These values are then written to an ASCII file that is used by the

Writing Ape payload to Tree

In the case that one wishes to plot existing Ape payloads using the Ape comparison tools, these payloads have to be converted to .root format first. One possibility is to load one payload as reference in Alignment/APEEstimation/test/cfgTemplate/ using ESPrefer. However this requires you to run at least one iteration of a measurement (including sending and retrieving batch jobs) and only allows for one Ape payload to be converted. For a more convenient workflow, Alignment/APEEstimation/test/ can be used. In this file, the used global tag, IOV and Ape tag can be specified along with the desired granularity. Note that all trees that are compared to each other need to have the same granularity with the same sector definitions. The sectors are defined in Alignment/APEEstimation/python/


The method used for the APE estimation is described in the following two documents:

-- JohannesHauk - 24-Jul-2012

Edit | Attach | Watch | Print version | History: r31 | r18 < r17 < r16 < r15 | Backlinks | Raw View | Raw edit | More topic actions...
Topic revision: r16 - 2018-01-24 - MariusTeroerde
    • 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-2020 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