/** @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 */