CMSSW: framework

Introduction

The framework represents the code base of CMSSW and follows the bus model to execute modularized pieces of functionality. In this section, the concepts of modules and how their are inserted into the bus are described.

In CVS, the location for standard sequences for simulation, reconstruction, etc. is:

• Configuration/StandardSequences/data

and example full workflows from simulation to reconstruction at:

• Configuration/ReleaseValidation/data

Framework

• Follows a bus model where modules are chained together to process data
  • Example: modules of track reconstruction
    1. Digitization of detector signals
    2. Clustering
    3. RecHit generation
    4. Seeding
    5. Pattern recognition
    6. Track fit
• One executable and one executable only: cmsRun
• Modules are configured and scheduled in a parameter-set which is passed to cmsRun as a command line parameter:

cmsRun <parameter-set>

Module types

CMSSW distinguishes following module types:

• EDProducer: takes input from the event and produces new output which is saved in the event
• EDAnalyzer: takes input from the event and processes the input without writing information back to the event
• EDFilter: decides if processing the event can be stopped and continued
• EventSetup: external service not bound to the event structure which provides information useable by all modules (e.g. Geometry, Magnetic Field, etc.)

MessageLogger

* A special service which provides a unified interface to messages (standard output, standard error, ...) from the cmsRun executable * The MessageLogger has the ability to restrict the output and redirect it to several destinations like the screen, ascii files, ... . * The default configuration of the MessageLogger is included in the parameter-set by including

include "FWCore/MessageLogger/data/MessageLogger.cfi"

• Should be included in every top level parameter-set.

• More information about the MessageLogger and its configuration possibilities can be found at the MessageLogger TWiki page.

Parameter-Set

Example: Configuration/ReleaseValidation/data/single_mu_pt_100_positive_allReco.cfg

process Rec = 
{
    include "Configuration/StandardSequences/data/FakeConditions.cff"
    untracked PSet options = {
       include "FWCore/Framework/test/cmsExceptionsFatalOption.cff"
       untracked bool wantSummary = true
       untracked bool makeTriggerResults = true 
    }
  source = FlatRandomPtGunSource 
  { 
    string psethack  = "single mu pt 100 pos"   
    untracked uint32 firstRun  =  1
    untracked int32 maxEvents =1 
    untracked PSet PGunParameters =
    {
      untracked vint32  PartID = {-13}
      untracked double MinEta = -2.5
      untracked double MaxEta =  2.5
      untracked double MinPhi = -3.14159265358979323846 # in radians
      untracked double MaxPhi =  3.14159265358979323846
      untracked double MinPt  =  99.99
      untracked double MaxPt  = 100.01
    }
    untracked int32 Verbosity = 0 # set to 1 (or greater)  for printouts
  }
  include "FWCore/MessageService/data/MessageLogger.cfi"
   replace MessageLogger.cout.threshold = "ERROR"
   replace MessageLogger.cerr.default.limit = 10
  
   service = RandomNumberGeneratorService
   {
      untracked uint32 sourceSeed = 123456789
      PSet moduleSeeds =
      {
         untracked uint32 VtxSmeared = 98765432
    untracked uint32 g4SimHits  = 11
    untracked uint32 mix        = 12345   
      }
   }


include "Configuration/StandardSequences/data/Reconstruction.cff"
include "Configuration/StandardSequences/data/Simulation.cff"
include "Configuration/StandardSequences/data/MixingNoPileUp.cff" 
include "Configuration/StandardSequences/data/VtxSmearedGauss.cff" 


    path p1 = {psim} # simulation
    path p2 = {pdigi} # digitization
    path p3 = {reconstruction_plusRS_plus_GSF} # reconstruction

   # Event output
include "Configuration/EventContent/data/EventContent.cff"
   module FEVT = PoolOutputModule 
   { 
        using FEVTSIMEventContent
   untracked string fileName = "single_mu_pt_100_positive.root"
   untracked PSet datasets ={
       untracked PSet dataset1 = {
      untracked string dataTier = "FEVT"
       }
       
   }
   }

   endpath outpath = {FEVT}

   schedule = {p1,p2,p3,outpath}

}

• A parameter-set is used to configure modules and to schedule their execution in a given order.
• It is based upon the concept of a set:

<identifier> <label> = <module or service name> 
{
...
<parameters>
...
}

• Parameters are defined like variables in code. They have a type which can be int32, bool, string, etc.
  • Special types like vstring specify vectors of strings
• Parameters are defined in two ways in the set
  1. tracked parameters change the outcome of the execution of a module and are stored in the provenance information persistet in the event file
  2. untracked parameters are not stored in the provenance

• The top level parameter-set handed over to the cmsRun executable is called the process set:

process <process name> = 
{
...
}

• The typical components of a process set are:
  • services which are not bound to the event separation and used by all modules (e.g. geometry, magnetic field, ...)
  • modules which should be executed (EDProducer, EDAnalyzer, EDFilter)
  • the endpath, paths and sequences which define ordered execution of modules and therefore specify what the cmsRun executable will do.

• For example, a module is configured in a parameter-set by:

module <module-label> = <module-name>
{
...
<module-parameter>
...
}

Scheduling

• The parameter-set uses sequences and paths to define what is executed and in which order
• EventSetups do not have to be scheduled as the are not bound to the event execution
• The module-label is used to identify a module within the parameter-set (has to be unique)

• A sequence groups together modules but does not execute them

sequence MySequenceLabel = { module-label1, module-lable2, ... }

• A path groups modules and sequences and executes them in the defined order
• There can be several paths defined in one process parameter-set
• The individual paths are executed after each other in no particular order

path MyPathLabel = { module-label3, MySequenceLabel, module-label4, ... }

• The special endpath is the only path which is guaranteed to be executed last
• There is only one endpath in the process parameter-set
• The endpath does not include other paths

endpath MyEndPathLabel = { module-label5, ... }

• The order in which paths and endpaths should be executed can be defined by using a schedule:

schedule = { path1, path2, endpath1, endpath2 }

Parameter-Set Inclusion

Example: Configuration/StandardSequences/data/Reconstruction.cff

#
# please understand that division global,highlevel is completely fake !
#

#local reconstruction

include "RecoLocalTracker/Configuration/data/RecoLocalTracker.cff"
include "RecoLocalMuon/Configuration/data/RecoLocalMuon.cff"
include "RecoLocalCalo/Configuration/data/RecoLocalCalo.cff"

sequence localreco =  {trackerlocalreco, muonlocalreco, calolocalreco }

# Global  reco

include "RecoEcal/Configuration/data/RecoEcal.cff"
include "RecoTracker/Configuration/data/RecoTracker.cff"
include "TrackingTools/Configuration/data/TrackingTools.cff"
include "RecoEcal/Configuration/data/RecoEcal.cff"
include "RecoJets/Configuration/data/RecoJets.cff"
include "RecoMET/Configuration/data/RecoMET.cff"
include "RecoMuon/Configuration/data/RecoMuon.cff"
#
# temporarily switching off recoGenJets; since this are MC and wil be moved to a proper sequence
#
sequence globalreco = {ckftracks, muonreco, ecalClusters, caloTowersRec, recoJets, metreco }
sequence globalreco_plusRS = {globalreco, rstracks }
sequence globalreco_plusGSF = {globalreco,  GsfGlobalElectronSequence}
sequence globalreco_plusRS_plusGSF = {globalreco, rstracks, GsfGlobalElectronSequence }

# Higher level objects
include "RecoVertex/Configuration/data/RecoVertex.cff"
include "RecoEgamma/Configuration/data/RecoEgamma.cff"
include "RecoPixelVertexing/Configuration/data/RecoPixelVertexing.cff"
include "RecoBTau/Configuration/data/RecoBTau.cff"
include "RecoBTag/Configuration/data/RecoBTag.cff"
include "RecoTauTag/Configuration/data/RecoTauTag.cff"
include "RecoLocalTracker/Configuration/data/RecoLocalTracker.cff"
include "Configuration/StandardSequences/data/RecoSim.cff"


sequence highlevelreco = {recopixelvertexing, vertexreco, jetTracksAssociator, btagging, coneIsolationTauJetTags, egammareco} # whatever
sequence highlevelreco_plusRS = {highlevelreco,vertexreco_rs} # whatever

#
# "Export" Section
#

# Default
sequence reconstruction = {localreco, globalreco, highlevelreco, RecoSim}
#other possibilities
sequence reconstruction_plusRS = {localreco, globalreco_plusRS, highlevelreco_plusRS}
sequence reconstruction_plusGSF = {localreco, globalreco_plusGSF, highlevelreco}
# the added _ is clearly a typo. for the moment I define both the correct and the wrong one!
sequence reconstruction_plusRS_plus_GSF = {localreco,globalreco_plusRS_plusGSF , highlevelreco_plusRS}
sequence reconstruction_plusRS_plusGSF = {reconstruction_plusRS_plus_GSF}
#

• Parameter-sets can include other parameter-sets via the inclusion mechanism:

include "<parameter-set>"

• the inclusion string is following the FileInPath structure
  • locations are given relative to CMSSW_X_Y_Z/src
  • local user project directory takes precedence over release area (see CMSSW user project area)
• The Framework resolves multiple inclusions of the same .cfi or .cff file.

Parameter-Set defaults and Cloning

• CMSSW modules do not contain hardcoded defaults for their parameters. Reason:
  • The used parameter-set completely defines what was done during execution
  • Avoid ambiguities with hardcoded defaults when different releases with potential different defaults have been used
  • Accountability for data management (MC samples, data samples, etc.)
• Each module has (should) a default parameter-set:

<Package>/<Module>/data/<Module-Label>.cfi

• Ending .cfi which configures only the module in question and defines the default parameters.
• The .cfi file of a Module is named after the Module Label.

Example: RecoTracker/RoadSearchCloudMaker/data/RoadSearchClouds.cfi

module roadSearchClouds = RoadSearchCloudMaker 
{

  # roads service label
  string RoadsLabel = ""

  # module label of RoadSearchSeedFinder
  InputTag SeedProducer = roadSearchSeeds

  # strip rechit collections
  InputTag matchedStripRecHits = siStripMatchedRecHits:matchedRecHit
  InputTag rphiStripRecHits    = siStripMatchedRecHits:rphiRecHit
  InputTag stereoStripRecHits  = siStripMatchedRecHits:stereoRecHit

  # module label of SiPixelRecHitConverter
  InputTag pixelRecHits        = siPixelRecHits

  # Use Pixels or not
  bool UsePixelsinRS = true

  # Use rphi RecHits in addition to matched RecHits (double modules only)
  bool UseRphiRecHits = false

  # Use stereo RecHits in addition to matched RecHits (double modules only)
  bool UseStereoRecHits = false

  # minimum half road parameter
  double MinimumHalfRoad = 0.13

  # maximal number of RecHits per DetId in RoadSearchCloud
  int32 MaxDetHitsInCloudPerDetId = 32

  # Size of R-Phi Road in Phi
  double RPhiRoadSize = 0.02

  # Size of Z-Phi Road in Phi
  double ZPhiRoadSize = 0.0020

  # minimal number of user layers per road
  int32 MinimalNumberOfUsedLayersPerRoad = 6

  # minimal number of missed layers per road
  int32 MaximalNumberOfMissedLayersPerRoad = 9999 

  # maximal number of consecutive missed layers per road
  int32 MaximalNumberOfConsecutiveMissedLayersPerRoad = 2

  # need true to reco field off cosmics
  bool StraightLineNoBeamSpotCloud = false

  # do cloud cleaning in CloudMaker instead of separate module
  bool DoCloudCleaning = true
 
  # minimal fraction of hits which has to lap between RawRoadSearchClouds to be merged
  double MergingFraction = 0.80
 
  # maximal number of RecHits per RoadSearchCloud
  int32 MaxRecHitsInCloud = 100

  # scale factor for window around phi in which detid's are looked up within a ring
  double scalefactorRoadSeedWindow = 1.5

}

• To make the life of the user easier, every module also has a .cff file which has the same name as the .cfi file. It includes
  • the .cfi file of the module
  • all needed services by inclusion of their .cfi files

Example: RecoTracker/RoadSearchCloudMaker/data/RoadSearchClouds.cff

# magnetic field
include "Geometry/CMSCommonData/data/cmsMagneticFieldXML.cfi"
include "MagneticField/Engine/data/volumeBasedMagneticField.cfi"

# cms geometry
include "Geometry/CMSCommonData/data/cmsIdealGeometryXML.cfi"

# tracker geometry
include "Geometry/TrackerGeometryBuilder/data/trackerGeometry.cfi"

# tracker numbering
include "Geometry/TrackerNumberingBuilder/data/trackerNumberingGeometry.cfi"

# roads
include "RecoTracker/RoadMapESSource/data/RoadMapESSource.cff"

# RoadSearchCloudMaker
include "RecoTracker/RoadSearchCloudMaker/data/RoadSearchClouds.cfi"

Change default parameter's or a module

• To change the parameters from their default, change individual variables via the replace mechanism.

replace roadSearchClouds.MaxRecHitsInCloud = 10

• A replace is only allowed for a module which has been defined without an include (plain definition in top parameter-set (.cfg>)) or a _cloned module_.
• A cloned module at the same time enables the usage of the same module twice because it changes the module label

Example: RecoTracker/RoadSearchCloudMaker/data/RoadSearchCloudsTIF.cff

# magnetic field
include "Geometry/CMSCommonData/data/cmsMagneticFieldXML.cfi"
include "MagneticField/Engine/data/uniformMagneticField.cfi"

# cms geometry
include "Geometry/CMSCommonData/data/cmsIdealGeometryXML.cfi"

# tracker geometry
include "Geometry/TrackerGeometryBuilder/data/trackerGeometry.cfi"

# tracker numbering
include "Geometry/TrackerNumberingBuilder/data/trackerNumberingGeometry.cfi"

# roads
include "RecoTracker/RoadMapESSource/data/RoadMapESSourceTIF.cff"

# RoadSearchCloudMaker
module  roadSearchCloudsTIF                                    = roadSearchClouds from "RecoTracker/RoadSearchCloudMaker/data/RoadSearchClouds.cfi"
replace roadSearchCloudsTIF.RoadsLabel                         = "TIF"
replace roadSearchCloudsTIF.SeedProducer                       = roadSearchSeedsTIF
replace roadSearchCloudsTIF.UsePixelsinRS                      = false
replace roadSearchCloudsTIF.UseRphiRecHits                     = true
replace roadSearchCloudsTIF.UseStereoRecHits                   = true
replace roadSearchCloudsTIF.scalefactorRoadSeedWindow          = 150
replace roadSearchCloudsTIF.MinimumHalfRoad                    = 0.50
replace roadSearchCloudsTIF.RPhiRoadSize                       = 5.
replace roadSearchCloudsTIF.MinimalNumberOfUsedLayersPerRoad   = 4 #3
replace roadSearchCloudsTIF.MaximalNumberOfMissedLayersPerRoad = 6 #3
replace roadSearchCloudsTIF.StraightLineNoBeamSpotCloud        = true

Conclusions

The parameter-set is the most important point of user interaction with CMSSW. Please make all effort to understand what your parameter-set is doing, learn how to read them and navigate the various includes by using the CVS browser and LXR