In the C++/Marlin version, the ability to convert from

In the C++/Marlin version, the ability to convert between different types of calorimeter hits has been added (

# ################################ .begin CalHitMapProcessor ProcessorType CalHitMapProcessor .end ----------------------------

An example of using

########################################################### # A processor to convert raw hits into calibrated hits. .begin CalorimeterHitsProcessor # mandatory processor type (the name of the class) ProcessorType CalorimeterHitsProcessor # Input collections to be converted InputCollections EcalBarrRawHits HcalBarrRawHits # Output collections with calibrated hits OutputCollections EcalBarrCalibHits HcalBarrCalibHits # Conversions based on simple factors (at least for now) EnergyFactor 1.0e-8 TimeFactor 1.0e-6 .end -------------------------------------------------Using

########################################################### # A processor to convert raw hits into simulated calorimeter hits. .begin SimCalorimeterHitsProcessor # mandatory processor type (the name of the class) ProcessorType SimCalorimeterHitsProcessor # Input collections to be converted InputCollections EcalBarrRawHits HcalBarrRawHits Raw2SimCollections EcalBarrRaw2sim HcalBarrRaw2sim # Output collections with calibrated hits OutputCollections EcalBarrDigiHits HcalBarrDigiHits # Conversions based on simple factors (at least for now) EnergyFactor 1.0e-8 TimeFactor 1.0e-6 .end -------------------------------------------------To see an example of these processors in a steering file, please click here.

Figure 3
- Illustration of the hit
smearing procedure implemented by a typical modifier,

and an explanation of some of the
existing modifiers. (Click on the figure for better resolution)

This is an alphabetical listing of the existing
modifiers, with a brief description:

- AbsValueDiscrimination

Configuration line example:

# Two parameters: (1) threshold, and (2) width of smearing on threshold

HBdiscrim AbsValueDiscrimination 8 1

A modifier for basic discrimination on the absolute value of energy. This means that hits with energies in the range [-threshold;+threshold] are discarded.

Negative contributions are due to random noise, and large negative values of random noise may be kept in an attempt to cancel large positive noise, thus avoiding a positive biasing of the total average energy deposition due to random noise.

- Crosstalk

Configuration line example:

# Two parameters: (1) mean value of crosstalk to first neighbors; and (2) width of smearing on the first parameter

HBcrosstalk Crosstalk 0.020 0.005

This modifier models the light crosstalk on scintillator cells, so it uses the Segmentation.getNeighbourIDs() method to find what are the neighbors. Only first neighbors are assigned crosstalk contributions.

- DeadCell

# Five parameters: cellID components of a specific cell:

# (1) system, (2) barrel/endcap flag, (3) layer index, (4) theta index, (5) phi index

HBDeadCell DeadCell 3 0 12 34 56

This modifier always removes any hit for the specified cellID. Please note that there is no consistency check on the validity of the cellID provided. If a bad ID is provided, no hit will ever get removed. One modifier has to be provided for each dead cell.

- ExponentialNoise

# First five parameters from RandomNoise: (1) system, (2) barrel/endcap flag, (3) noise-only threshold

# (4) nominal time and (5) sigma of time smearing

# One additional parameter: (6) ยต = mean of the exponential distribution

HBExpoNoise ExponentialNoise 3 0 7 100 100 0.6

This modifier inherits from RandomNoise, and defines an exponential noise distribution, with probability=0 for negative amplitudes. The implementation uses the exponential distribution from Apache's commons-math library, see http://jakarta.apache.org/commons/math/userguide/distribution.html.

Please read RandomNoise documentation for more details.

- FunctionModifier
(abstract)

An*abstract*function-based modifier. Its subclasses must implement the following abstract function:The values returned from this function will overwrite the ADC counts of the transient hits.

virtual double transformEnergy(const TempCalHit& hit) const = 0;

- GainDiscrimination

# Four parameters: (1) nominal gain, (2) gain width, (3) nominal threshold, and (4) threshold width

HBlightCollEff GainDiscrimination 0.0111 0.0029 1 0

A simple modifier inheriting directly from CalHitModifier. In the example above, a smeared factor of (0.0111 +/- 0.0029) is applied to each hit independently, and then hits with the "energy" field below 1 get removed. Please note that the field is called "energy", but the interpretation may be different, like "number of photons collected" in the example above. Therefore, a threshold of 1 means that it does not make sense to have a fraction of a photon collected. A fixed gain or threshold is applied if the widths (parameters 2 or 4) are set to zero.

- GaussianNoise

# First five parameters from RandomNoise: (1) system, (2) barrel/endcap flag, (3) noise-only threshold

# (4) nominal time and (5) sigma of time smearing

# Two additional parameters: (6) mean, and (7) width of the gaussian distribution.

# width<0 means that noise-only threshold acts on absolute values only, thus both negative and positive tails are used

HBGaussNoise GaussianNoise 3 0 7 100 100 0.0 -1.6

This modifier inherits from RandomNoise, and defines a gaussian noise distribution. The implementation uses the gaussian distribution from Apache's commons-math library, see http://jakarta.apache.org/commons/math/userguide/distribution.html.

Please read RandomNoise documentation for more details.

- HotCell

# Modifier parameters:

# (1) amplitude mean and (2) sigma of the smearing on the amplitude around the mean

# (3) timing mean and (4) sigma of the smearing on the timing around the mean

# (5-9) are the cellID components of a specific cell: (5) system, (6) barrel/endcap flag,

# (7) layer index, (8) theta index, (9) phi index

HBHotCell HotCell 252525 0 101010 0 3 0 12 123 345

A simplistic modifier for hot cells. While RandomNoise selects random cell for noise assignment, HotCell picks a specific cell, and randomly draws the amplitude and timing of the noise to be assigned to that cell. In the configuration line above, the cell (12,123,345) will get fixed (non-random, sigma=0) amplitudes and timestamps according to the values provided above. These values were present in the final hits. Please note that, similarly to the DeadCell modifier described above, no check is made on the validity of the last five parameters. In particular, system=3, barrelEndcapFlag=0 needs to be compatible with an HB (HcalBarrel) cell, and the other cell indices must also be valid.

- RandomNoise

# Five common parameters: (1) system, (2) barrel/endcap flag, (3) noise-only threshold

# (4) nominal time and (5) sigma of time smearing

An abstract modifier, suggests a common behavior for noise modeling modifiers. Its subclasses define the specific noise distribution to be used for noise modeling. The common behavior implemented in RandomNoise modifier assumes that noise should be added to all cells, but that the noise assigned to most cells is actually significantly small, and will not survive discrimination. Considering the huge number of cells in typical ILC hadron calorimeters, and for performance reasons, the random noise is added to random cells, in a two-stage processing, as explained below.

In the first step, the full noise distribution is used to add noise to all existing hits, as the additional noise may contribute to make some hits survive discrimination. All hits, therefore, will have some noise contribution after this first step.

The second step's purpose is to add noise-only cells, when the noise is large enough to maybe survive discrimination. An operational noise-only threshold is defined in the configuration line, which is used to calculate the probability of any cell to receive noise with amplitude larger than the noise-only threshold. The mean number (`Nmean`

) of cells above the noise-only threshold is then given by [the total number of cells in a given component (say Hcal barrel)] times [the probability of any cell being above the noise-only threshold].`Nmean`

is calculated during initialization of the modifier, and then for each event, the number of cells above theshold (`Nabove`

) is drawn from a Poisson distribution, with mean`Nmean`

. Then a total of`Nabove`

cells are randomly drawn to receive random noise. The noise amplitude is then forced to be above the noise-only threshold, but still following the distribution provided. CellSelector is the class responsible for randomly drawing valid cells from a given subdetector.

In order to be usable in the context of the two-steps processing described above, the RandomNoise subclasses have to define the noise distribution, while implement the following methods based on that distribution:

abstract public double drawRandomNoise();

abstract public double getProbabilityAboveThreshold();

abstract public double drawRandomNoiseAboveThreshold();

After reading about the two-steps processing in RandomNoise modifier, the purpose of these methods should be clear. Method`drawRandomNoise()`

must return noise amplitudes according to the full distribution to be used in the first step, while`drawRandomNoiseAboveThreshold()`

returns noise amplitudes forced to be above the noise-only threshold, to be used in the second step. Method`getProbabilityAboveThreshold()`

is used during the initialization of the modifier, to determine the`Nmean`

parameter.

This modifier currently needs to know the system and barrel/endcap flags, which are used to encode the cellID/rawID of the newly added noise-only cells. For some examples, please take a look at the ExponentialNoise and GaussianNoise modifiers.

- SiPMSaturation

# Two parameters: (1) nominal gain for the linear regime, and (2) lower limit of the saturation region

HBSiPMSaturat SiPMSaturation 1 2200

A "quick-and-dirty" implementation of photosensor saturation effects. This modifier models a linear regime for amplitudes below the limit, and a constant output for amplitudes above the limit. Considering the numbers above, a maximum output of 2200 would be provided, for a total number of 2200 PEs or more. This modifier inherits from FunctionModifier.

- SmearedGain

# Two parameters: (1) nominal gain, and (2) width of the gain smearing

HBlightYield SmearedGain 10000000 0

The simplest non-trivial function-based modifier. It models a smeared linear transformation on energy. If the nominal gain is set to 1 without smearing (zero width),`SmearedGain`

does not alter the input values, thus acting like an identity transformation.

- SmearedTiming

# Two parameters: (1) nominal factor on timing, and
(2) width of the smearing on the first parameter

HBtimeSmear SmearedTiming 1000000 10000

Very similar to SmearedGain modifier, but it applies the smeared linear transformation on the timing instead. If the nominal factor on timing is set to 1 without smearing (zero width),

HBtimeSmear SmearedTiming 1000000 10000

Very similar to SmearedGain modifier, but it applies the smeared linear transformation on the timing instead. If the nominal factor on timing is set to 1 without smearing (zero width),

`SmearedTiming`

does not alter the
input values, thus acting like an identity transformation on the hit
timing.In order to be properly controlled by the Digitizer, all modifiers should inherit the interface from the abstract class CalHitModifier, implementing

`init(), processEvent(), print()`

and `newInstance()`

methods, see
figure below.Figure
4 - Creating new modifiers. The member functions in red
are the ones which need to be implemented by the new modifiers. (Click
on the figure for better resolution). Please note that this
figure is somewhat obsolete: transformTime(hit) has been deprecated,
and a current subclass of FunctionModifier is SmearedGain.

In spite of their simplicity, several of the typical effects from the digitization processes can be represented quite well by appropriate configuration of one of these very simple-minded modifiers. Examples are uniform inefficiencies of say (97.8+/- 0.5)%, or zero-suppression say below (100+/-2) ADC counts. Both cases can be represented well by an instance of the existing GainDiscrimination modifier. The first one can also be modeled by the simpler SmearedGain modifier.

At the next step of increasing complexity, one anticipates that some other effects, like charge saturation or signal integration, can be realized with function calls, like:

double
smearedEnergy = transformEnergy(aHit);

Such modifiers can be created very easily, e.g. by inheriting from FunctionModifier and implementing the transformEnergy() function shown in red in Fig.4, or by copying the code from SmearedTiming modifier, changing the class name appropriately and modifying the transformTime() method.

Another set of effects would fall in the next level of complexity, like

`Crosstalk`

modifier for a good example of a modifier which depends on
external classes.