Alignment algorithms

Complete:

Goal of this page

Description of the configuration and operation common to all algorithms. Details on how to use the different algorithms can be found in the links section.

Known problems

Running on data from many different runs in CMSSW_2_2_X

• Symptom: Memory exhaustion.
• Cause: By default Framework keeps information corresponding to Runs or Lumi sections in memory until the last event is processed (in case of presence of an output module)
• Hacking shell solution: Increase the memory budget that your shell allows, e.g. on lxplus the default is 1.5 GB, but you can increase to 3 GB. How to do that is shell dependent. In zsh/bash do ulimit -v 3072000 (number interpreted in kB). Check current limit using ulimit -v.
• CMSSW Solutions/Workarounds, probably to be combined with hacking shell solution: make use of process.options.fileMode
  1. Tell framework not to cache anything, by using process.options.fileMode = cms.untracked.string('NOMERGE'). Note that beginRun(), beginLuminosityBlock() and corresponding endXy() are called at file boundaries, even if the same run/luminosity block continues in next/other file. But this should be OK for alignment validation.
  2. Tell framework to cache only luminosity blocks, but rely on events in files being ordered by run: process.options.fileMode = cms.untracked.string('FULLLUMIMERGE')
     • Let DBS sort your files by run using this query: find run, file where dataset = /your/dataset/foo/bah order by run
     • Remove possible file duplications by hand. Note that this will not work in case file A contains parts of two runs and file B other parts of the same two runs.
     • Needs more memory than NOMERGE mode.
  3. Tell framework to cache neither runs nor luminosity blocks, but rely on events in files being ordered by run and luminosity block: process.options.fileMode = cms.untracked.string('MERGE')
     • Ordering probably hard to achieve.
     • Memory consumption should be in between NOMERGE and FULLLUMIMERGE.
• See also the following example or more details in section The options Parameter Set of SWGuideEDMParametersForModules.

process.options = cms.untracked.PSet(
    Rethrow = cms.untracked.vstring("ProductNotFound") # make this exception fatal
#    , fileMode  =  cms.untracked.string('FULLMERGE') # any file order (default): caches all lumi/run products (memory!)
#    , fileMode  =  cms.untracked.string('FULLLUMIMERGE') # needs files sorted in run, caches lumi
#    , fileMode  =  cms.untracked.string('MERGE') # needs files sorted in run and within run in lumi sections (hard to achieve)
    , fileMode  =  cms.untracked.string('NOMERGE') # no ordering needed, but calls endRun/beginRun etc. at file boundaries
    )

Rotation instability

• Short description: the global orientation of an Alignable becomes divergent when repeating a rotation n times (n ≥10)
• Fix: try align::rectify() between iterations. A more centralised solution is under study.
• Details: see this thread: https://hypernews.cern.ch/HyperNews/CMS/get/alignment/62.html
• Additional note: rotations are, in general, not stable against numerical approximations.

Links to algorithms

• HIP algorithm use in the tracker
• HIP algorithm use in the muon chambers
• Kalman Alignment Algorithm
• Millepede

Versions

See SWGuideTrackAlignmentVersions for changes between releases and possible tag son top of releases.

Configuration

Selection of what to align

Which Alignables and which of their (usually) six parameters should be taken into account is determined in the class AlignmentParameterSelector. It is configured by the PSet Selector which is a part of the PSet ParameterBuilder. The latter belongs to the configuration of the AlignmentProducer. Example:

PSet Selector = {
  vstring alignParams = { "TIBRods,101001", "TOBLayers,11111" }
}

Each string in alignParams consists of two (or three, cf. below) comma separated parts. The first is a string determining a subdetector and the Alignable level. The second determines which of the (rigid body) parameters are active, the order is u, v, w, alpha, beta, gamma. Thus 101001 selects u, w and gamma and deselects v, alpha and beta. Other letters than 0 and 1 also select the parameter, but may be interpreted in a special way, e.g. f, r and c in millepede.

There are two separate ways to specify the Alignables. Both use as entry point the method unsigned int AlignmentParameterSelector::addSelection(const std::string &nameInput, const std::vector &paramSel) (in CVS).

The first method is to use pre-defined strings, e.g. BarrelRods, TIBDets, PXECLayers or MuonCSCChambers, which can be looked up in the source code. If an unknown string is found, and exception is thrown.

The second method is to use the tracker hierarchy (possible since CMSSW_2_0_X). All tracker hierarchy levels can be accessed generically: If a string starts with Tracker, this is stripped off. The remaining part should be something like TIBHalfShell. All possible strings can be taken from the source code by prepending "Tracker". If the string is unkown, an exception is thrown, telling all known strings. Here TIBModuleUnit means the 1D modules that form the 2D AlignableDets (and analogous for TID, TOB and TEC).

For both methods there are additional ways to further restrict the selection of Alignables given by the first part (before first comma) of the string:

1. Since CMSSW_2_0_X: The 1D modules that are part of an AlignableDet in the 2D strip modules can be separately selected by the selection strings TrackerTIBModuleUnitRphi and TrackerTIBModuleUnitStereo and analog for TID, TOB and TEC. (The following LayersNM selection can be give on top of that.)
2. Special string extensions:

   LayersNM

   If the first string ends with Layers followed by two digits, e.g. 24, only the layers from the first to the second digit are selected. The numbering starts at 1. E.g. TIBRodsLayers24 selects TIB rods of layers 2, 3 and 4, TOBDetsLayers66 selects TOB Dets of the sixth (and last) layer. For TID and TEC selects wheels and for PixelEndcap disks.

   SS or DS (valid only for TIB and TOB, ignored elsewhere, see below how to select TID/TEC 1D/2D-dets geometrically)

   If the first string part contains at any place DS, only Dets/Rods/Layers with stereo (double sided) modules are selected, whereas SS at any place selects single sided modules (based on the layer). SS and DS are removed from the string before it is further interpreted.

3. Geometrical selection in eta, phi, r, x, y and z (x and y since CMSSW_1_6_0 only) by use of extra PSets: If an item in alignParams contains a third comma-separated part, a PSet with that name is expected within Selector, defining arrays for ranges in eta, phi, r, x, y and z. These arrays must have an even number of entries and the alignable positions are required to fulfil ('x'Range[0] <= 'x' < 'x'Range[1]) || ('x'Range[2] <= 'x' < 'x'Range[3]) || etc. Note that currently the alignable positions which have to fulfil the selection are the nominal positions (or those read from the database). Here is an example that e.g. assigns different parameters for 1D and 2D modules in TEC:

      PSet Selector = {
        vstring alignParams = { "TIBRods,101001,aSelection", "TECDets,101001,endCapSS","TECDets,111001,endCapDS"}
        PSet aSelection = { # name defined above
          vdouble etaRanges =  {-2., -0.4, 0., 1.5} # either (-2 <= eta < -0.4) or (0 <= eta < 1.5)
          vdouble phiRanges =  {1.5, -0.5}          # a phi-slice covering the +-pi sign flip
          vdouble rRanges   =  {}                   # empty arrays mean no restriction in that variable
          vdouble xRanges   =  {}   vdouble yRanges = {}   vdouble zRanges = {}   # but all need to be mentioned
        }
        PSet endCapSS = { # valid for TID and TEC
          vdouble etaRanges = {}  vdouble phiRanges = {} vdouble zRanges = {}
          vdouble rRanges   = {40., 60., 75., 999.}
          vdouble xRanges = {}  vdouble yRanges = {}
        }
        PSet endCapDS = { # valid for TID and TEC
          vdouble etaRanges = {}  vdouble phiRanges = {} vdouble zRanges = {}
          vdouble rRanges   = {0., 40., 60., 75.}
          vdouble xRanges = {}  vdouble yRanges = {}
        }
      }

Monitoring

Starting in 1_5_0_pre3, AlignmentProducer maintains a list of histogram modules implemented in the CommonAlignmentMonitor package. The idea is that each group working on alignment can create a module, fill it with histograms, and point AlignmentProducer to it. As AlignmentProducer runs the selected algorithm, it also calls the histogram module, filling plots. This "on-board monitoring" has access to the same data as the alignment algorithm itself, so it can create histograms/profile plots from

• the selected set of alignables and parameters,
• every iteration, and
• the aligned geometry after each iteration step.

The monitoring package manages the output ROOT file, including a directory structure based on iteration number and collecting and merging histograms from distributed jobs.

Configuring Alignment Monitors before CMSSW_2_1_X

The default configuration is to use no monitors: in Alignment/CommonAlignmentProducer/data/AlignmentProducer.cff, the relevant lines are

PSet monitorConfig = {
    untracked vstring monitors = {}
}

In your configuration file, you can replace the whole PSet. A typical configuration is:

replace AlignmentProducer.monitorConfig = {
    untracked vstring monitors = {"AlignmentMonitorHIP"}
    untracked PSet AlignmentMonitorHIP = {
        string outpath = "./"
        string outfile = "histograms.root"

        bool collectorActive = false
        int32 collectorNJobs = 0
        string collectorPath = "./"
    }
}

The vstring monitors is a list of selected monitors, only one element long in the above (typical case). A PSet for each follows; this PSet is passed to the alignment monitor for parsing. The above example contains the minimum parameters:

• an outpath for the output ROOT file (must end in slash)
• an outfile for the output ROOT file
• collectorActive is true if this invocation of AlignmentProducer is collecting and merging intermediate results. This parameter should be true if and only if *AlignmentAlgorithm.collectorActive is true.
• collectorNJobs is the number of ROOT files to merge
• collectorPath is the base directory for all intermediate alignment results, including histograms (must end in slash). The full directory hierarchy is [collectorPath]/job[N]/[outfile].

Configuring Alignment Monitors in CMSSW_2_1_X and beyond

The default configuration is still to have no monitors, with the same syntax.

To add a monitor, you now need a TFileService

service = TFileService {string fileName = "file.root"}

which puts all your histograms from different modules into the same file.

Monitor packages no longer have outpath, outfile, collectorActive, collectorNJobs, or collectorPath parameters, so only those parameters directly needed by the monitoring package need to be specified (e.g. how to book the histograms, etc.). You still need a PSet, even if it's empty.

replace AlignmentProducer.monitorConfig = {
    untracked vstring monitors = {"AlignmentMonitorHIP"}
    untracked PSet AlignmentMonitorHIP = {}
}

Changes in capabilities

These changes were motivated by problems interfacing with new versions of ROOT. TFileService properly handles the new ROOT interface, so we made CommonAlignmentMonitor a shell around that. While it is convenient having histograms from different modules in the same output file, we have lost the following features:

• CommonAlignmentMonitor can only put histograms from multiple iterations into the same file if all of those iterations were performed in the same cmsRun process, using AlignmentProducer as a looper. If each of your iterations involves a separate cmsRun invocation, for example because you are parallel-processing, each iteration will be in a directory named iter1.
• CommonAlignmentMonitor no longer merges histograms in a collector step (combining histograms at the end of an iteration, from different sub-jobs in a parallel-processing step). To merge histograms in a file created by TFileService, see the documentation.

However, the following is now possible:

• Monitoring packages can now be run as an analyzer outside of AlignmentProducer, for example in an offline validation process. The analyzer is configured like this:

module AlignmentMonitorAsAnalyzer = AlignmentMonitorAsAnalyzer {
    InputTag tjTkAssociationMapTag = # same as you would have passed to AlignmentProducer
    PSet ParameterStore = # same as you would have passed to AlignmentProducer
    untracked vstring monitors = {"AlignmentMonitorHIP"}
    untracked PSet AlignmentMonitorHIP = {}
}

This also paves the way to turn monitoring packages into DQM--- the DQM source would be another analyzer with much the same interface.

Creating an alignment monitor

The full documentation on creating a monitoring module is located at SWGuideAlignmentMonitors.

Refitting

To obtain the TrajectoryStateOnSurface (TSOS) for each hit, the tracks have to be refitted using the TrackRefitter. During this refit constraints can be applied, see SWGuideRefitterWithConstraints.

From CMSSW_2_0_0 on, the final tracks will not anymore contain SiStripMatchedRecHit2D, these will be replaced in the final fit by their constituents. To run alignment with split RecHits already in previous releases, follow the recipe given in hypernews.

ReferenceTrajectory

Used in Kalman and Millepede algorithms. As long as no documentation is available here, please refer to this cff in CVS or for >= CMSSW_2_1_0 its python equivalent.

Default ReferenceTrajectory

Without B-field: BzeroReferenceTrajectory

Mass and Vertex Constraints: TwoBodyDecayReferenceTrajectory

CombinedTrajectoryFactory

Review Status

Editor/Reviewer and date	Comments
Main.cklae - 16 Mar 2007	Added links to algorithms
JennyWilliams - 28 Mar 2007	editing for inclusion in SWGuide
JennyWilliams - 24 Apr 2007	added millipede link
FredericRonga - 25 Apr 2007	Re-organize page
FredericRonga - 02 May 2007	Add Known Problems
FredericRonga - 01 Nov 2007	Added 1_6_X backport of new tracker hierarchy

Responsible: FredericRonga
Last reviewed by: Reviewer