/**
@mainpage EUTelescope
Welcome to the EUTelescope documentation server. This is the place
where you can find all the explanation and the examples you may need
to run the EUTelescope processors within Marlin.
If you know already something about this software project, then you
can browse the documentation clicking on the button above or putting a
keyword in the search field in top right corner of this page.
If you feel you don't know enough on the EUTelescope then we encourage
you take have a look at the following pages:
New Added a histogram ROOT utility to show and print standard reference histograms. Click on \ref histogramPackage.
@li @ref intro
@li @ref preparation
@li @ref analysis
@li @ref downinst
Have a look at the \ref changelog
If those information are not yet enough, consider contact us
on the Linear Collider Forum.
*/
*****************************************************************************
/**
@page intro Introduction
This is the documentation page of the EUTelescope software
project. EUTelescope is a group of Marlin processors to be used
for analysis and reconstruction of data taken using the EUDET JRA1 pixel telescope.
The
main goal of the EUTelescope software is to go from raw data acquired
by a set of data aquisition boards to high level objects like tracks
crossing the telescope. Those tracks are used to characterized both
the telescope itself and any other position sensitive detector (DUT)
that can be inserted into the telescope setup.
The structure of
EUTelescope is very modular and the each processor is just taking care
of doing a particular task on the input collection and eventually add
other output collections that can be used by other following
processors. This approach has many advantages but some disadvantages
as well when compare against a monolithic approach where one processor
only is doing the full job from the beginning to the end (see below
@ref modular).
The main input of the full analysis chain is the
LCIO output file produced by the DAQ system containing the pixel raw
data. Along with that other data are also needed: as for example
calibration constants (pedestal and noise), eta distribution for each
sensor and alignment constants. These preparation steps (@ref
preparation) can be done using a complex conditional steering file, or
they can be processed beforehand using much simpler steering file.
When the preparation steps are done, then the complete analysis chain
can be executed (@ref analysis).
@section modular Pros and cons of a modular approach
The basic idea of having a modular approach is to keep things as
simple as possible. Every single step of the full analysis chain that
goes from raw data to tracks can be processed step by step and the
output of each step is still self consistent and can be fed in to the
next step without any manipulation. Of course this is particularly
valuable during the debug phase when each processor has to be
controlled and checked against bugs.
From an end user point of
view, having so many steps might result in a too complicated and
useless structure. In this case it would be better to have just one
big piece of code the user run it and the result file pops up at the
end.
For the time being we would like to stick to the modular
approach that is also Marlin inherited and for the laziest end user,
we are providing example of complete steering files to have (almost)
everything done just launching a command.
*/
*****************************************************************************
/**
@page analysis The analysis chain
In this page we would like to summarize which processors have to be
used to go from raw data to tracks.
\section histogram The histogram interface
The first processor one may want to add to the steering file is an
histogram interface. This processor is making the handling of
histograms very user friendly and available to all other
processor. This is not a compulsory element of the analysis chain, but
it is very encouraged.
Within the EUTelescope framework there are
actually two available histogramming interfaces:
@li the marlin::AIDAProcessor: provided by Marlin,
@li the eutelescope::ROOTProcessor: that is instead typical of
EUTelescope but still under development.
The user can decide which of one or even both should be used. Here
below is a typical xml configuration the AIDAProcessor
@code
@endcode
Another tool offered by the EUTelescope framework is the
eutelescope::EUTelHistogramManager. This is an XML interpreter for the so
called "histoinfo.xml" file. This file contains the booking
information of the great part of the histograms booked and filled by
the EUTelescope processors. This is allowing to have well defined (and
not automatic) binning without the need of modify the hardcoded
binning information and re-compile.
This is an example of a histogram information file:
@code
@endcode
\section conditionload Loading the condition file
The second step in the analysis chain is to load the calibration file
also known as pedestal file and the eta function files. Those can prepared beforehand (@ref
pedestal and @ref eta) and the pedestal, noise and status collections should made
available to the following processors using a ConditionProcessor. In
fact those files can be real files or an entries of a
condition database.
Here below an example of ConditionProcessor
to be used to load collection from an LCIO file:
@code
pedestalDB pedestal_db.slcio pedestalDB
noiseDB pedestal_db.slcio noiseDB
statusDB pedestal_db.slcio statusDB
xEtaCondition etafile_db.slcio xEtaCondition
yEtaCondition etafile_db.slcio yEtaCondition
@endcode
With this configuration the ContionsProcessors is loading from a file
named @c pedestal_db.slcio three different conditions and from a file
named @c etafile_db.slcio other two collections. A drawback of this
ConditionProcessor is that collections taken from LCIO file are made
read only and the user cannot modify them. This sounds reasonable for
calibration data until the user wants to keep the calibration
constants updated during the running analysis chain. If this is true,
i.e. if the user wants to run a pedestal update algorithm
(eutelescope::EUTelUpdatePedestalNoiseProcessor) then those
collections should be locally copied to writable ones. This second
task can be accomplished by the
eutelescope::EUTelCopyPedestalProcessor configured as follows:
@code
noiseDB
pedestalDB
statusDB
noise
pedestal
status
@endcode
One can do the exactly the same also for the eta conditions.
@todo Consider renaming EUTelCopyPedestalProcessor in EUTelCopyConditionProcessor
\section calibrate Apply the pedestal correction
Finally it is time to start doing something. The first thing to do is
to apply to the input data the calibration constants previously loaded
and now available in the event. This operation is taking the input
TrackerRawData and transforming them into TrackerData containing
calibrated data. This operation is done by the
eutelescope::EUTelCalibrateEventProcessor that is also responsible to
apply common mode suppression. The user can ask to this processor also
to fill the so-called detector low level debug histograms, a bunch of
big histograms containing information about the detector
functionality.
This is a typical configuration for this processor.
@code
noise
pedestal
rawdata
status
data
@endcode
\section clustering Search for clusters
With the calibrated data, it is possible to scan the matrix looking
for clusters, i.e. group of space correlated pixels all having signals
above a certain threshold. There are several different cluster
searching algorithm one can imagine, code and apply. Within the EUTelClusteringProcessor, the user can select
which searching criteria should be used, but irrespectively of that,
the output of this clustering processor should be a TrackerPulse
collection having for each pulse a TrackerData attached. The
TrackerPulse contains only general information about the cluster,
while the TrackerData contains the full set of information. For this
reason the TrackerData structure may depend of the clusterization
algorithm and for that purpose the user can apply on top of that the
eutelescope::EUTelVirtualCluster.
@see eutelescope::EUTelClusteringProcessor for more
details.
Here below an example of the configuration of eutelescope::EUTelClusteringProcessor
@code
data
noise
status
cluster
@endcode
A further and more precise selection of clusters fulfilling a list of
selection criteria is available in the eutelescope::EUTelClusterFilter
processor.
After the clusters were found, the user may want to apply a cluster
separation processor in order to try to split clusters that were
merged. This task is accomplished by the
eutelescope::EUTelClusterSeparationProcessor that can be configured as below:
@code
cluster
@endcode
After the cluster searching, the user may want to update the
calibration constants using the current event. For that purpose, the
pedestal, noise and status collection should be made writable by the
eutelescope::EUTelCopyPedestalProcessor and then the
eutelescope::EUTelUpdatePedestalNoiseProcessor can be called with a
configuration similar to the follow one:
@code
noise
pedestal
rawdata
status
0 10 15
@endcode
@section spacepoint From clusters to space points
The next step in the analysis procedure is to move from TrackerPulse
to TrackerHit or in other word we need to move from local cluster in
the detector frame of reference to space point in the telescope frame
of reference. This task is accomplished by the
eutelescope::EUTelHitMaker and this is the first processor that is
accessing to the geometry repository through GEAR. The xml file
describing the geometry has to be provided as a global information in
the steering file.
@code
...
...
@endcode
The user can also decide to apply or not the Eta function correction
just selecting a switch in steering file. For the time being, since
the geometry description of the telescope is still in a development
phase, some parameters are hard coded in the software.
Again an configuration example for this processor.
@code
cluster
hit
xEtaCondition yEtaCondition
@endcode
@section tracking The track fitting
To be added
@section outputfile Saving the results
Saving the output file with all the needed collections is the task of
the eutelescope::EUTelOutputProcessor. The reason why we have a custom
output processor and we don't use the standard
marlin::LCIOOutputProcessor is because of the event structure in the
EUDAQ software. In fact the acquisition system is appending at the end
of a run an empty event called End Of Run Event that can be used by
serial input/output protocol (like SIO) to identify which is the last
event before the real end of file. The EUTelOutputProcessor just check
the presence of the EORE event at the end of the run and if it is
missing a new EORE is appended. Many EUTelescope processors are using
the EORE to finish up the calculation or to throw a
RewindDataFilesException.
If more than one input files are
processed at the same time, the user can decide to keep, or skip the
intermediate EORE in the output file. The behavior of the processor
can be changed using the SkipIntermediateEORE steering parameter.
This output processor has to be used in every step because if we want
to be self consistent every step output file has to finish with an
EORE.
Another interesting use of this processor is the file
fix. If, in fact, for any reason should the DAQ fails to write the
EORE, this LCIO can be fed into this output processor that will append
at the end the EORE. The configuration of EUTelOutputProcessor is
almost identical to the one of the LCIOOutputProcessor but the
SkipIntermediateEORE.
@code
@endcode
*/
*****************************************************************************
/**
@page preparation The preparation steps
For the time being there are three preparation steps available within
the EUTelescope package, for the raw DAQ native format conversion
(@ref conversion), for the calculation of calibration constants (@ref
pedestal) and for eta functions (@ref eta).
@section conversion The raw data converter
This is the step zero of the analysis chain. The final DAQ software
will save an output file directly formatted in LCIO with the proper
event structure and the correct event model. For the time, especially
for debug reason, the DAQ is saving data on file according to its own
native data format using its built-in Serializer.
To translate from the native raw format to the LCIO raw format, a
specific data reader has been developed (eutelescope::EUTelMimoTelReader).
The basic idea behind this reader is instead of re-writing and
re-inventing the deserializing procedure the DAQ software is using to
write the output file, the EUTelescope is linking against the
libeudaq shared library and using directly the native
deserializer. This imply that the EUDAQ software should be installed
in the system and available. To avoid building problem, this reader
is actually built only if the USE_EUDAQ is defined. Here below an
example of what should be added to the userlib.gmk and to the env.sh
@code
#--------------------------------------------------------------------------------
# EUDAQ
#--------------------------------------------------------------------------------
USERLIBS += -L/home/toto/ilc/eudaq/main -leudaq
USERINCLUDES += -DUSE_EUDAQ -DEUDAQ_FUNC=__PRETTY_FUNCTION__
USERINCLUDES += -DEUDAQ_PLATFORM=PF_LINUX -I/home/toto/ilc/eudaq/main/include
@endcode
@code
#--------------------------------------------------------------------------------
# EUDAQ
#--------------------------------------------------------------------------------
export EUDAQ=/home/toto/ilc/eudaq/pro
export LD_LIBRARY_PATH="$EUDAQ/main:$LD_LIBRARY_PATH"
@endcode
Another reader (eutelescope::EUTelStrasMimoTelReader) has been
prepared in order to convert the output of the IPHC DAQ in LCIO
format. In this case we didn't follow the approach used for the EUDAQ
since we don't have any compatible libraries. So binary data are
reintrepret according to
eutelescope::EUTelStrasMimoTelReader::StrasEventHeader,
eutelescope::EUTelStrasMimoTelReader::StrasEventTrailer and
eutelescope::EUTelStrasMimoTelReader::StrasRunHeader.
This reader should be improved and refurbished in order to make it
more general.
@section pedestal The pedestal and noise calculator
The first step to be done is to calibrate the output of each pixel
detector in order to remove the constant and useless signal. Together
with this pedestal value also the noise figure is estimated as the
width of the pedestal distribution.
The output of this step is a condition file having two TrackerData and
one TrackerRawData for each detector module:
@li Pedestal collection (TrackerData): one per detector with the mean
output value of each pixel
@li Noise collection (TrackerData): one per detector with the noise
value for each pixel
@li Status collection (TrackerRawData): one per detector with the
status of each pixel. This can be used to hide some very bad pixels
from the rest of the analysis.
Those collections are meant to be condition data and for the time
being are saved to LCIO files but they can be moved to a
database.
There are two ways to generate good pedestal and noise
constants:
@li Producing them from a specific run (@ref pedestalnoisecalculator)
@li Assuming a known initial value and then keep them update (@ref
autopedestal)
@subsection pedestalnoisecalculator Calculating pedestal and noise
The standard approach for pedestal and noise calculation consists on
having a special run with no or very few particles arriving on the
telescope (a so called pedestal run, indeed) that should be processed
in order to retrieve the mean value of the output signal of each pixel
and the correponding noise figure. This task is accomplished by a
specific processor named
eutelescope::EUTelPedestalNoiseProcessor. More details about the
calculation algorithms already implemented are provided within the
class description.
Here below is an example of a steering file to produce the pedestal,
noise and status collection using eutelescope::EUTelPedestalNoiseProcessor
@code
pedestal-run.slcio
rawdata
@endcode
It should be noted that the AIDAProcessor can be removed, but then no
control histogram will be produced. Another remark concerns the
absence of a LCIOOutputProcessor; this is not needed since is the
eutelescope::EUTelPedestalNoiseProcessor taking care of saving the
final pedestal/noise/status collection on the disk when the
calculation is over.
The eutelescope::EUTelPedestalNoiseProcessor can be runned also in the
complete analysis scheme using a more complicated conditional steering
file, but for simplicity this is not recommended.
@subsection autopedestal Assuming initial pedestal value
Another possible approach for the preparation of good pedestal and
noise collection is to assume a certain reasonable value for both the
pedestal and noise of every pixel in the matrix and then let the
system update (correct) this value to a more correct one. This
approach is particularly interesting when dealing with detector having
a pretty uniform pedestal distribution over the full sensitive
area.
An advantage of this approach is that the user does not need to
execute a specific run to have the pedestal output, but she/he has
just to put the eutelescope::EUTelAutoPedestalNoiseProcessor at the
beginning of the analysis chain and the
eutelescope::EUTelUpdatePedestalNoiseProcessor soon after the
clusterization processor. Here below an example of a steering file
using the automatic pedestal calculation, for more info also refer to
the eutelescope::EUTelAutoPedestalNoiseProcessor and
eutelescope::EUTelUpdatePedestalNoiseProcessor class description.
@code
simuldata-run.slcio
noise
pedestal
status
1 1 1 1 1 1
0 0 0 0 0 0
noise
pedestal
rawdata
status
data
data
noise
status
cluster
cluster
noise
pedestal
rawdata
status
0 10 15
rawdata data pedestal noise status
@endcode
@section eta Eta function calculation
The Eta function is used to calculate the center of a cluster. It is
used as a non linear weighting function in the charge center of mass
calculation. An a priori calculation of the Eta function starting from
the pixel detector design and consequently the field distribution
within the sensor is practically unfeasible. An experimental approach
based on probability distribution is, instead, easy to apply and
assure good results. This is based on the fact that the probability to
find the cluster center is flat over the pixel surface; in other
words, there are no physical reasons way a certain region of a pixel
should collect more cluster centers than another. If there is such a
region, this can only derive from an artifact due to pixel design and
the way the charge is collected within the sensitive volume.
Correcting the charge center of mass algorithm, introducing non linear
weights, can solve this problem and flat the probability
distribution. This non linear weighting function is called Eta
function. To calculate it starting from the experimental data, one
need as an input a large enough collection of clusters for each
detector layers in order to have a statistically significant amount of
cluster centers and apply to that the
eutelescope::EUTelCalculateEtaProcessor. This processor is taking care
of calculating the eta function of each detector in the two orthogonal
directions. More on the Eta function can be found in the
eutelescope::EUTelCalculateEtaProcessor class description.
The output file of the Eta calculation phase is a condition LCIO file
(as for pedestal also this file can be moved to a condition database
through the abstract interface provided by LCCD) containing two
collections of eutelescope::EUTelEtaFunctionImpl one for each of the
two directions. Each collection contains as many objects as the number
of detectors in telescope.
Also for Eta calculation one can imagine to have a complicated
conditional steering file performing on one loop the eta calculation
and the apply the calculation results on the second loop, but to keep
the procedure the simplest possible, the user should run on some input
files the Eta calculator processor and then, afterward, apply the
results to the hits. Exploiting the modular approach, one can
calculate the Eta functions (using for example the steering file
provided below) and save as an output file the TrackerPulse found. The
next run can then start directly with the eutelescope::EUTelHitMaker
processor using as input the output of the previous step.
@code
simuldata-run.slcio
pedestalDB pedestal_db.slcio pedestalDB
noiseDB pedestal_db.slcio noiseDB
statusDB pedestal_db.slcio statusDB
noiseDB
pedestalDB
statusDB
noise
pedestal
status
noise
pedestal
rawdata
status
data
data
noise
status
cluster
cluster
cluster
1000 1000
3 3
rawdata data pedestal noise status
@endcode
*/
*****************************************************************************
/**
@page downinst Download and installation
@section donwload How to download
To download the source code of the EUTelescope project there at least
two possibility. The first and easiest one is to get a Tarball of the
tagged release you wish from our CVS
web server.
Otherwise you can access directly the CVS repository as anonymous user
following the instructions
given here.
@section install How to install
Installation is even easier than donwloading the source code because
the The ilcinstall
is helping you in donwload and install all the needed piecese of
software needed by Eutelescope.
You can choose in between two different kinds of installation:
@li \ref minimal . This has the minimum number of dependencies and
can be done in a couple of minutes. Of course this is not offering all
the bell and whistles that come along the Eutelescope, for example you
will not have the graphical event viewer or the perform alignment
calculation. The minimal configuration contains: lcio,
Marlin,
Java, CMake and CMakeModules.
@li \ref complete. This is the complete installation you have to do
to fully enjoy Eutelescope. Along with the modules coming with the
Minimal installation there are also the following packages: GEAR,
RAIDA,
ROOT, LCCD,
MarlinUtil,
CED,
CLHEP, GSL and Overlay,
eudaq.
To install follow these steps:
@li Download ilcinstall
@li Untar ilcinstall into the folder where you want to install the ilc
software.
@li Download one of the examplary configuration: \ref minimal
or \ref complete
@li Open the configuration file into a text editor and modified the
installation path (ilcsoft) and the location of the eudaq library
(eudaqPath) according to your wishes.
@li Run ./ilcinstall -i minimal.cfg (or complete.cfg)
@section dcache Accessing data in the DESY dCache
If your computer is registered in the DESY network, you can access
data directly from the dCache without having to copy them locally to
your storage. This is particularly useful if you are in DESY and you
don't have a GRID certificate.
Add to your environment script the following line:
@code
export LD_PRELOAD=/opt/products/lib/libpdcap.so
@endcode
where the path to libpdcap.so may depend from one machine to the other.
*/
/**
@page cdsPage CDS calculation
CDS is a very powerful technique to reduce the noise in particle
detectors. MAPS uses CDS very extensively and even if it is based on
the difference between two following sampling of the same pixel
signal, it is worth to explain how CDS is calculated in a test beam
setup.
@section cds3frame Calculating CDS in RAW3 mode.
When working in RAW3 mode, the EUDRB DAQ producer is streaming out for
each triggered event, three following full frames, being the trigger
accepted by the EUDRB during the second one. Oversimplifying the
situation let us start considering the detector linear. Each frame
contains all the readout pixels chronologically sorted, starting from
the first one.
@image html cdsraw3.png "CDS algorithm with RAW 3".
The trigger is arriving sometime during the readout of the second
frame. The arrow in the figure is showing which pixel is readout when
the trigger is accepted by the DAQ and not the hit pixel. The position
of the arrow is dividing the second frame in two parts:
@li the preceding one (region 1) made by pixels that are
already readout at the trigger time,
@li the following part (region 2) made by pixels that are readout after the trigger.
A priori, we do not know whether the particle is passing through the
detector and consequently we have to analyze both region 1 and 2
separately. If it is on region 1, the signal will
pop up only at the next reading, so during the first part of the third
frame (yellow part in the picture). Instead, if it is on region 2,
the particle signal is going to be sampled and then as reference
signal the second part of the first frame should be used (cyan part in
the picture).
The EUDRB is making available the trigger arrival position. To simplify the
calculation, the EUDRB producer via the EUDRBDecoder::GetArrays is
providing four vectors with one component per pixel.
@li @c "m_adc[0]", @c "m_adc[1]", @c "m_adc[2]" contain the reading of the
first, second and third frames respectively.
@li @c "m_pivot" is an array of boolean, that is 0 till the trigger
arrival and then it is 1 till the end.
*/
/**
@page minimal Minimal configuration
\include minimal.cfg
*/
/**
@page complete Complete configuration
\include complete.cfg
*/
/**
@page changelog History (CVS changelog)
\include ChangeLog
*/