Parameters for Modules (Release cycles 3_8_X through 6_0_X inclusive)

Complete:

Goal of this page

This page lists and describes configurable parameters in important EDM modules in release cycles CMSSW_3_8_X through CMSSW_6_0_X inclusive. For prior releases, refer to the following link in the TWIKI history of this page:

https://twiki.cern.ch/twiki/bin/view/CMSPublic/SWGuideEDMParametersForModules?rev=51

edmPluginHelp

One might consider using the executable edmPluginHelp instead of this TWIKI. It has been available since release CMSSW_3_1_0. It provides information that complements the information on this TWIKI. It can be used to get information about the configurable parameters of any producer, filter, analyzer, output module, source, ESSource, ESProducer, or service, not just the ones related to the EDM or Framework. For edmPluginHelp to work, the function in the C++ code that describes the parameters of the module must have been implemented. For almost all Framework related modules this function has been implemented. The number of other modules where it has been implemented is increasing.

For example for PoolSource, give the following command within the working area for a specific release:

           edmPluginHelp -p PoolSource

edmPluginHelp will give you the parameter names and types which the code that validates parameter sets uses. This part of the information is always 100% accurate because the validation and edmPlugInHelp get information from the same source.

Note that output of edmPluginHelp tends to be more terse and has less information than this TWIKI. One cannot get information about the "options" parameter set from edmPluginHelp.

We try to keep both edmPluginHelp and this TWIKI up to date and consistent. If you notice an error or a discrepancy between the output of edmPluginHelp and this TWIKI, post it to the Framework hypernews so it can be fixed. Note the information returned by edmPluginHelp is hard coded in the C++ and it cannot be fixed until the next release. The output of edmPluginHelp sometimes contains additional comments not used in the validation. It is possible for these comments to contain errors. It might also report parameters which are allowed by the validation, but which the module does not actually use (a mistake or for backward compatibility to old python scripts).

The options Parameter Set

One can define a parameter set named options at the top level that is attached directly to the process object. This parameter set will affect event processing for all modules. All the parameters within "options" are optional as is the parameter set itself. For example, it might look like this in a top level configuration file:

process.options = cms.untracked.PSet(
  fileMode = cms.untracked.string('FULLMERGE')
)

name	type	description
fileMode	untracked string	The two possible values are FULLMERGE and NOMERGE. The default mode is FULLMERGE. In NOMERGE mode, all output files are closed and new ones opened each time a new input file is opened. (See additional comments below related to releases before 3_8_0).
wantSummary	untracked bool	If true, a trigger summary report is written at the end of the job (to the MessageLogger FwkSummary category, which goes to std::cerr with the MessageLogger defaults). Default is false.
allowUnscheduled	untracked bool	If true, the Framework will execute Producer modules which were declared in the configuration but not scheduled in a path and which produce products requested by other modules (warning, this feature is fully implemented but has not been used much in CMS yet, please report any bugs you notice). Defaults to false.
emptyRunLumiMode	untracked string	The three possible values are doNotHandleEmptyRunsAndLumis, handleEmptyRuns, and handleEmptyRunsAndLumis (the default). If doNotHandleEmptyRunsAndLumis is specified, there will be no beginRun or endRun transitions for runs containing no events, and no beginLuminosityBlock or endLuminosityBlock transitions for luminosity blocks containing no events. If handleEmptyRuns is specified, beginRun or endRun transitions will occur normally for runs with no events, but there will be no beginLuminosityBlock or endLuminosityBlock transitions for luminosity blocks containing no events. If handleEmptyRunsAndLumis (the default) is specified, all transitions will occur normally for empty runs or luminosity blocks. If, for example, run transitions are suppressed for empty runs, there will be no beginRun or endRun calls made for empty runs, and therefore no new run products will be produced for empty runs. However, this parameter does not cause any existing run products from prior processes to be dropped.
makeTriggerResults	untracked bool	An obsolete parameter. Has no effect but as a matter of cleanup should be deleted from any configurations where it occurs.
The values the next five parameters hold are exception categories. See additional comments below.
Rethrow	untracked vstring	If an exception with this category is thrown, Event processing stops immediately. If caught, exceptions are rethrown so that they rise to the top level, then an error message prints, and the process stops. There is an attempt to call endLuminosityBlock, endRun, close open files, and perform other cleanup (although each cleanup step is attempted only once and may also fail).
SkipEvent	untracked vstring	If an exception with this category is thrown, it is caught and not rethrown. Processing is immediately stopped for the current path and no other regular paths are executed. TriggerResults is inserted into the Event (in TriggerResults the current path has the status Exception and paths not run have the status Ready). EndPaths are run, because this is necessary to keep the ROOT "Events" tree balanced in the event that fast cloning is taking place. Processing then proceeds normally with the next event or whatever comes next. However, see notes 1 and 2 below.
FailPath	untracked vstring	If an exception with this category is thrown, it is caught and not rethrown. The current regular path is recorded as failed in TriggerResults as if a filter had returned false (unless the filter was vetoed, in that case true) and stopped processing on that path in the same position as the module that threw the exception. No more modules are executed on the path. Event processing continues with the next path. If the module is encountered again on a different path for the same event, it will not be rerun and the same exception will be rethrown and handled the same way. However, see notes 1 and 2 below
IgnoreCompletely	untracked vstring	If an exception of this category is thrown, it is caught and not rethrown. An attempt is made to ignore the exception and continue processing the next module in the same path. However, see note 1 below.

NOTE 1: The behavior after exceptions described above only applies during a call to a user module function while processing an Event (EDProducer::produce, EDFilter::filter, EDAnalyzer::analyze or OutputModule::write). At all other times the behavior is similar to the Rethrow behavior described above.

NOTE 2: The behavior described above for SkipEvent and FailPath does not apply if the exception is thrown while processing an event in a module on an EndPath. In this case, SkipEvent and FailPath behave as IgnoreCompletely. This is because all modules on an EndPath are considered independent.

The default for all exception categories is Rethrow. (This is correct as of the time this documentation was written, look in FWCore/Framework/src/Actions.cc for the actual defaults for a given release).

The maxEvents Parameter Set

One can define a parameter set named maxEvents at the top level that is attached directly to the process object. This parameter set will affect event processing for all modules. Both parameters within "maxEvents" are optional. as is the parameter set itself. For example, it might look like this in a top level configuration file:

process.maxEvents = cms.untracked.PSet(
  input = cms.untracked.int32(100),
  output = cms.untracked.int32(20)
)

The above parameter set will cause processing to terminate after 100 events are read from the primary input source. It will also cause processing to terminate after every output module in the configuration has output 20 events. Both parameters default to -1, which mans no limit.

One can also customize the output limits to individual output modules. For example:

process.maxEvents = cms.untracked.PSet(
    input = cms.untracked.int32(100),
    output = cms.untracked.PSet(
       outputModule1 = cms.untracked.int32(20),
       outputModule2 = cms.untracked.int32(10)
    )
)

The above parameter set will cause processing to terminate after 100 events are read from the primary input source. It will also cause processing to terminate the output module with a module label of outputModule1 has output 20 events and the output module with a module label of outputModule12 has output 10 events.

The maxLuminosityBlocks Parameter Set

One can define a parameter set named maxLuminosityBlocks at the top level that is attached directly to the process object. This parameter set will affect event processing for all modules. For example, it might look like this in a top level configuration file:

process.maxLuminosityBlocks = cms.untracked.PSet(
  input = cms.untracked.int32(10)
)

The above parameter set will cause processing to terminate after 10 luminosity blocks are read from the primary input source.

InputSources

Generated Input Sources (e.g. EmptySource)

name	type	description
firstRun	untracked uint32	first run number to generate. Defaults to 1.
firstLuminosityBlock	untracked uint32	first luminosity block number to generate. Defaults to 1.
firstEvent	untracked uint32	first event number to generate. Defaults to 1.
numberEventsInRun	untracked uint32	number of events to generate per run. Defaults to maxEvents.
numberEventsInLuminosityBlock	untracked uint32	number of events to generate per lumi block. Defaults to maxEvents.
firstTime	untracked uint64	value before first event, in nanoseconds. Defaults to 1.
timeBetweenEvents	untracked uint64	increment before each event, in nanoseconds. Defaults to 1.
eventCreationDelay	untracked uint32	real-time delay between events, in microseconds. Defaults to 0.
processingMode	untracked string	"Runs" (i.e. don't process lumis or events), "RunsAndLumis" (i.e. don't process events), or "RunsLumisAndEvents". defaults to "RunsLumisAndEvents"

firstTime and timeBetweenEvents were uint32 before CMSSW_5_1_0_pre2.

External Input Sources (e.g. Test Beam sources)

name	type	description
firstRun	untracked uint32	first run number to generate. Defaults to 1.
firstLuminosityBlock	untracked uint32	first luminosity block number to generate. Defaults to 1.
firstEvent	untracked uint32	first event number to generate. Defaults to 1.
numberEventsInRun	untracked uint32	number of events to generate per run. Defaults to maxEvents.
numberEventsInLuminosityBlock	untracked uint32	number of events to generate per lumi block. Defaults to maxEvents.
firstTime	untracked uint64	value before first event, in nanoseconds. Defaults to 1.
timeBetweenEvents	untracked uint64	increment before each event, in nanoseconds. Defaults to 1.
eventCreationDelay	untracked uint32	real-time delay between events, in microseconds. Defaults to 0.
processingMode	untracked string	"Runs" (i.e. don't process lumis or events), "RunsAndLumis" (i.e. don't process events), or "RunsLumisAndEvents". defaults to "RunsLumisAndEvents"
fileNames	untracked vstring	file names, URL's or other input entities. Required

firstTime and timeBetweenEvents were uint32 before CMSSW_5_1_0_pre2.

PoolSource

name	type	description
fileNames	untracked vstring	physical or logical file names. Required
processingMode	untracked string	"Runs" (i.e. don't process lumis or events), "RunsAndLumis" (i.e. don't process events), or "RunsLumisAndEvents". defaults to "RunsLumisAndEvents"
secondaryFileNames	untracked vstring	secondary physical or logical file names. defaults to empty
needSecondaryFileNames	untracked bool	throw if secondaryFileNames is not specified or empty. defaults to false
parametersMustMatch	untracked string	match requirement for parameter values for multiple input files. "permissive" or "strict". defaults to "permissive"
branchesMustMatch	untracked string	match requirement for branches for multiple input files. "permissive" or "strict". defaults to "permissive"
setRunNumber	untracked uint32	overrides run number in file (usable only with generated data). defaults to 0 (no override)
skipBadFiles	untracked bool	skip missing or inaccessible files. defaults to false
skipEvents	untracked uint32	Number of initial events to skip. Does not skip Runs or LuminosityBlocks. Does not count as skipped events, events that would have been skipped for some other reason. Defaults to 0
eventsToSkip	untracked VEventRange	Vector of EventRanges to skip. Skips the Events in those EventRanges. Defaults to empty vector
lumisToSkip	untracked VLuminosityBlockRange	Vector of LuminosityBlockRanges to skip. Skips the LuminosityBlocks and the Events in those LuminosityBlockRanges. Defaults to empty vector. If the vector is not empty, then Run's are also skipped if they do not contain any Lumi's that will be processed.
eventsToProcess	untracked VEventRange	Event ranges to process. Other events are not processed. Within a specific input file, only Runs and LuminosityBlocks associated with events that are both in ranges on the list and in that input file are processed. Default is an empty vector and this parameter is ignored.
lumisToProcess	untracked VLuminosityBlockRange	LuminosityBlock ranges to process. Other luminosity blocks, and the events in them, are not processed. Default is an empty vector and this parameter is ignored. If the vector is not empty, then Run's are also skipped if they do not contain any Lumi's that will be processed.
noEventSort	untracked bool	If true and constraints allow it, then events, runs, and lumis are processed in the order they appear in the TTree's. If false, they are sorted based on process history, run number, lumi number, and event number. One constraint is that everything in an input file associated with the same run number and process history must be processed contiguously. The other constraint is that everything in an input file associated with the same process history, run number and lumi number must be processed contiguously. Default is true. (see below for more details).
duplicateCheckMode	untracked string	Four possible values: "noDuplicateCheck", "checkEachFile", "checkEachRealDataFile", and "checkAllFilesOpened". In the first mode, no duplicate checking is done. In the other modes, when a duplicate Event is found it is skipped. An event is duplicate if it has the same process history, run number, lumi number, and event number as an event already encountered. In mode "checkEachFile", each event is compared with the other events in the same input file. In the "checkEachRealDataFile", this is done only for real data files, nothing is done for simulation. In the final mode, events are compared with all other events in all the input files. The default is "checkAllFilesOpened".
firstRun	untracked uint32	Runs, LuminosityBlocks, and Events associated with run numbers less than firstRun are not processed. Defaults to 1.
firstLuminosityBlock	untracked uint32	LuminosityBlocks and Events associated with firstRun and with luminosity block number less than firstLuminosityBlock are not processed. Defaults to 1.
firstEvent	untracked uint32	Events associated with firstRun and firstLuminosityBlock and also with event number less than firstEvent are not processed. Defaults to 1. There is a special case. If firstLuminosityBlock is 0, then Events associated with firstRun and with event number less than firstEvent are not processed.
inputCommands	untracked vstring	Used to drop selected branches on input. Defaults to "keep *"
dropDescendantsOfDroppedBranches	untracked bool	If a branch is dropped on input, drop other branches derived from this branch. Defaults to true.

See Example 6 in SWGuidePoolInputSources for an example of how to use inputCommands to implement drop on input.

noEventSort The processing order is determined as follows. If noEventSort is true, processing is ordered by the following criteria listed in order of precedence: input file, ProcessHistory/RunNumber ordered by first appearance in current file, ProcessHistory/RunNumber/LumiNumber ordered by first appearance in current file, and entry number in Events TTree. If noEventSort is false, then processing is ordered by the following criteria listed in order of precedence: input file, process history in order of appearance in the process, run number, luminosity number, event number, and Event TTree entry order.

parametersMustMatch and branchesMustMatch See SWGuideMultipleFiles for more information

See also:

SWGuidePoolInputSources - How to specify a POOL/ROOT file as a source of events.

SWGuideMultipleFiles - How to read multiple POOL/ROOT files in one job.

OutputModules

PoolOutputModule

name	type	description
fileName	untracked string	output file or URL. Required
catalog	untracked string	output catalog name. Default: file:PoolFileCatalog.xml
logicalFileName	untracked string	logical file name. Defaults to empty string.
compressionLevel	untracked int32	ROOT compression level (0-9). Default: 7.
compressionAlgorithm	untracked string	ROOT compression algorithm. Allowed values "ZLIB" (default) or "LZMA". You probably want a compression level less than 7 with the "LZMA" algorithm
basketSize	untracked int32	default ROOT buffer size in bytes. Default: 16384.
splitLevel	untracked int32	default ROOT split level (0-99). Default: 99.
overrideInputFileSplitLevels	untracked bool	for copied branches, override ROOT split levels and basket sizes in input files. Default: false
maxSize	untracked int32	Max file size before starting new file, in kilobytes. Default: ~2TB.
fastCloning	untracked bool	If false, fast copying is disabled. Default: true.
sortBaskets	untracked string	"sortbasketsbyoffset", "sortbasketsbyentry" or "sortbasketsbybranch". Default: "sortbasketsbyoffset". Passed directly to ROOT when the Events tree is fast cloned.
dropMetaData	untracked string	"NONE", "DROPPED", "PRIOR", or "ALL" Default: "NONE".
outputCommands	untracked vstring	Used to drop selected branches. Defaults to "keep *"
SelectEvents	untracked PSet	Used to select only events satisfying certain triggers. See Paths and trigger bits -

The outputCommands and SelectEvents parameters are supported for all output modules, not just PoolOutputModule.

For a more detailed explanation of outputCommands, see SWGuideSelectingBranchesForOutput - How to configure output modules to write specific branches

If dropMetaData is "ALL", all per product per event metadata will be dropped. If dropMetaData is "PRIOR", all per product per event metadata for products produced in prior processes will be dropped. If dropMetaData is "DROPPED", all per product per event metadata for dropped products produced in prior processes will be dropped.

compressionAlgorithm was not supported in releases before CMSSW_5_0_0_pre1.

The maxSize parameter is checked only when a primary input file is closed. So, events from the same input file will always go into the same output file, regardless of the value of maxSize.

The catalog and logicalFileName parameters are passed to the job report, and are otherwise unused.

See also Paths and trigger bits - How to configure output modules to write specific events

EDProducers

EDAnalyzers

EventContentAnalyzer

This module prints to standard out a list of all products within the Event. A 'verbose' option will actually print the contents of the requested products.

name	type	description
indentation	untracked string	string prepended to output (defaults to "++")
verbose	untracked bool	when true it prints the contents of Event products. Default is false.
verboseForModuleLabels	untracked vstring	prints the contents of the products made by those modules. If 'verbose=true' and this is empty, print contents of all products. Default is empty.
verboseIndentation	untracked string	string used to indent verbose information (defaults to " ")

EventSetupRecordDataGetter

This module can be configured to get any data from any EventSetup Record.

name	type	description
verbose	untracked bool	when true it prints a statement for each successful get. Default is false.
toGet	VPSet	holds records and data to get

Parameters expected in toGet parameter

name	type	description
record	string	name of the record holding the data
data	vstring	names of the data types to get from the record. If a label is needed, give the type followed by '/' and then ending with the label.

EDFilters

ESSources

EmptyESSource

This module creates empty EventSetup Records using the IOVs provided.

name	type	description
recordName	string	name of the Record which should be created
iovIsRunNotTime	bool	?
firstValid	vuint32	a list of the run numbers for the start of each IOV transition. Set to '1' if you want valid for all time

Services

Tracer

Prints 'tracing' information to standard out which tells you want cmsRun is doing.

name	type	description
indention	untracked string	string prepended to tracing output (defaults to "++")

Review Status

Reviewer/Editor and Date (copy from screen)	Comments
WilliamTanenbaum - 21 Aug 2012	add maxEvents and maxLuminosityBlocks parameter sets
WilliamTanenbaum - 19 Dec 2011	updating
WilliamTanenbaum - 31 Jan 2011	updating
WilliamTanenbaum - 22 jun 2009	updating
WilliamTanenbaum - 05 jun 2009	updating
WilliamTanenbaum - 30 Apr 2009	updating
WilliamTanenbaum - 09 Apr 2009	updating
WilliamTanenbaum - 20 Jan 2009	updating
WilliamTanenbaum - 15 Jan 2007	page last content editor
JennyWilliams - 31 Jan 2007	editing to include in SWGuide

Responsible: WilliamTanenbaum
Last reviewed by: Reviewer