Configuring DigiSim and its modifiers
An arbitrary number of modifiers can be defined and used within any
DigiSim run. It is possible to configure and use any number of
modifiers of any single existing modifier type. DigiSimProcessor
is a Marlin processor, therefore it can receive any number of
parameters from the Marlin steering file. The modifiers can then
be configured on-the-fly, using parameters from the steering file (see this simple example).
In the C++/Marlin version, the ability to convert from RawCalorimeterHits to calibrated
CalorimeterHits and from RawCalorimeterHits to SimCalorimeterHits has recently
been implemented. For more information, see the 'Processors in DigiSim' section below.
In the C++/Marlin version, the ability to convert between different types of calorimeter hits
has been added (RawCalorimeterHits to CalorimeterHits
In the java version, the DigiSim configuration is very similar.
Note that by design, the very same Marlin steering file can also be
used in the Java version as well, and this simplifies the maintenance
of the configuration files in the long term.
Processors in DigiSim
There are currently three utility processors in DigiSim that aid in the handling of hit collections. The
first is CalHitMapProcessor which fills hit maps
for use by other processors and it is implemented in both the Java and C++ versions of DigiSim.
The second and third are CalorimeterHitsProcessor and SimCalorimeterHitsProcessor and are implemented only in the C++ version of DigiSim.
CalHitMapProcessor
CalHitMapProcessor is a utility processor that fills hit maps for use by other processors
so that they do not have to fill the same maps themselves. CalHitMapProcessor takes no input
arguments and is used in the steering file as shown below:
# ################################
.begin CalHitMapProcessor
ProcessorType CalHitMapProcessor
.end ----------------------------
CalorimeterHitsProcessor
CalorimeterHitsProcessor is a utility processor to convert raw hits into calibrated hits. At the
moment, the conversion process is based on the multiplication of the raw hit timing and energy/amplitude information
by a given factor. As the calibration process is developed further, the conversion process will modified to
match the calibration process.
An example of using CalorimeterHitsProcessor is shown below:
###########################################################
# 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 CalorimeterHitsProcessor is similar to using a modifier. InputCollections and
OutputCollections define the names of the input and output hit collections that are to be converted.
EnergyFactor and TimeFactor are the factors by which the raw hit timing and energy/amplitude information
are to be multiplied by.
SimCalorimeterHitsProcessor
SimCalorimeterHitsProcessor functions the same way as CalorimeterHitsProcessor with the
exception that it converts RawCalorimeterHits into SimCalorimeterHits. An example is shown below:
###########################################################
# 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.
Existing modifiers
There are currently a few general modifiers implemented and ready for
use. Many of the existing modifiers implement a smeared linear transformation.
See Fig. 3 for a graphical representation of what we mean with smeared
linear
transformation, but please note that SmearedLinear modifier has been
deprecated, and replaced by simpler modifiers SmearedGain and
SmearedTiming.
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:
virtual
double transformEnergy(const TempCalHit& hit) const = 0;
The values returned from this function will overwrite the ADC counts of
the transient hits.
- 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), SmearedTiming
does not alter the
input values, thus acting like an identity transformation on the hit
timing.
Real-life digitization: creating new
modifiers
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
cell ganging, random
noise or crosstalk. These effects
typically require
external
information, like cell neighborhood, which is not readily available in
the
hit itself. Geometry-dependent modifiers have been developed to model
crosstalk, exponential and gaussian noise, while keeping
the geometry-dependent processing isolated into reusable geometry-aware
classes like CellSelector.
In general, such modifiers should inherit directly from CalHitModifier, and implement
its virtual methods init(),
processHits(), print() and newInstance(). See
Crosstalk modifier for a good example of a modifier which depends on
external classes.
