FMD/AliFMD.h

   1 #ifndef ALIFMD_H
   2 #define ALIFMD_H
   3 /* Copyright(c) 1998-1999, ALICE Experiment at CERN, All rights
   4  * reserved.
   5  *
   6  * Latest changes by Christian Holm Christensen <cholm@nbi.dk>
   7  *
   8  * See cxx source for full Copyright notice
   9  */
  10 /** @mainpage ALICE FMD Off-line code
  11
  12     @b Contents
  13     - @ref intro
  14     - @ref structure
  15       - @ref base  (see also @ref FMD_base)
  16       - @ref sim   (see also @ref FMD_sim)
  17       - @ref rec   (see also @ref FMD_rec)
  18       - @ref util  (see also @ref FMD_util)
  19     - @ref quick
  20     - @ref authors
  21
  22     @section intro Introduction:
  23
  24     This file contains a short overview of the FMD code.   It is by no
  25     means authoritative  - only the code is good for that.  However,
  26     I'll try to explain things a bit here.
  27
  28     @section structure Structure:
  29
  30     There are 4 libraries build for the FMD.  These are
  31
  32     - libFMDbase: This contains the basic stuff, like data classes and
  33       managers.
  34     - libFMDsim: This contains code used by the simulation only.  That
  35       includes the detector class AliFMD and it's derivatives.  It
  36       also contains the code for building the geometry, as well as the
  37       digitisers and raw data writer.
  38     - libFMDrec: Code needed for the reconstruction.  This include the
  39       reconstruction code itself, as well as a raw data reader.
  40     - libFMDutil: This is a special library that contains various
  41       utility classes for the FMD expert/developer/tester.  It
  42       includes code to read all data produced by the FMD, a simple
  43       event display, and code to make fake calibration and alignment
  44       data.  This library is @e not loaded by aliroot
  45       automatically. The user has to load it herself:
  46       @code
  47       gSystem->Load("libFMDutil.so");
  48       @endcode
  49     The content of these libraries is detailed more below.
  50
  51     @subsection base libFMDbase:
  52
  53     This currently (18th or March 2006) contains the classes
  54
  55     - AliFMDBaseDigit, AliFMDDigit, AliFMDSDigit: Base class for
  56       digits, real digits, and summable digits.  The are all data
  57       classes that holds the ADC value(s) for a single strip.
  58     - AliFMDBoolMap: A map of booleans, one for each strip.
  59     - AliFMDUShortMap: A map of unsigned short integers, one for each
  60       strip.
  61     - AliFMDDetector, AliFMD1, AliFMD2, AliFMD3: 3 classes that holds
  62       the parameters for each of the 3 FMD sub-detectors.  These
  63       derive from AliFMDDetector, and are managed by AliFMDGeometry.
  64       Each of these also contains the translation from sensor
  65       reference frame to global reference frame.
  66     - AliFMDRing: Parameters for the FMD rings (inner and outer type).
  67       These are managed by AliFMDGeometry.
  68     - AliFMDGeometry: Manager of FMD geometry data. All code queries
  69       this manager for geometry parameters, so that the data is always
  70       consistent.
  71     - AliFMDParameters: Manager of FMD parameters, like calibration
  72       parameters.  This class fetches data from CDB if necessary.
  73       All code queries this manager for parameters, so that the data
  74       is always consistent.
  75     - AliFMDCalibPedestal, AliFMDCalibGain, AliFMDCalibSampleRate,
  76       AliFMDAltroMapping: Containers of calibration parameters.  These
  77       correspond to the pedestal and its width, the gain of each
  78       strip, the oversampling rate used in read-out, and the map from
  79       hardware address to detector.
  80     - AliFMDAltroIO, AliFMDAltroReader, AliFMDAltroWriter: Low-level
  81       classes to do input/output on ALTRO formated buffers.
  82
  83
  84
  85     @subsection sim libFMDsim:
  86
  87     This currently (18th or March 2006) contains the classes
  88
  89     - AliFMDEdepMap: Cache of energy deposited and total number of
  90       hits for each strip.  The digitiser AliFMDDigitizer uses this to
  91       store simulation data before making digits.
  92     - AliFMDHit: A hit in the FMD active elements, as described by the
  93       simulation back-end during transport.
  94     - AliFMD, AliFMDv0, AliFMDv1: Simulation drivers for the FMD.
  95       AliFMD is the base class. AliFMDv0 corresponds to a simulation
  96       where no hits are created, but the material distribution is
  97       right.  AliFMDv1 is like AliFMDv0, except that hits are
  98       produced.
  99     - AliFMDGeometryBuilder: Build the FMD geometry in terms of TGeo
 100       objects.  The information for building the geometry is retrieved
 101       from AliFMDGeometry.
 102     - AliFMDBaseDigitizer, AliFMDDigitizer, AliFMDSDigitizer: Base
 103       class for the digitisers.  AliFMDDigitizer makes `real' digits
 104       (AliFMDDigit) from hits, and AliFMDSDigitizer makes summable
 105       digits from hits.
 106     - AliFMDRawWriter: Writes a pseudo raw data file from the digits
 107       created by the digitisers.  It uses the AliFMDAltroMapping from
 108       AliFMDParameters to make the mapping from detector coordinates
 109       to hardware addresses.
 110
 111     @subsection rec libFMDrec:
 112
 113     This currently (18th or March 2006) contains the classes
 114
 115     - AliFMDReconstructor: Reconstruct (in a naiive way) the charged
 116       particle multiplicity in the FMD strips.  This also writes an
 117       AliESDFMD object to the ESD files (that class is in libESD).
 118
 119     - AliFMDRecPoint: Reconstructed point in the FMD.  These objects
 120       are made AliFMDReconstructor.
 121
 122     - AliFMDRawReader: Classes to read raw data files.
 123
 124     @subsection util libFMDutil:
 125
 126     This currently (18th or March 2006) contains the classes
 127
 128     - AliFMDInput, AliFMDInputHits, AliFMDInputDigits,
 129       AliFMDInputSDigits, AliFMDInputRecPoints: Base class, and
 130       concrete classes to read in FMD generated data.  These provide a
 131       simple and unified way of getting the data.  Hooks are defined
 132       to process hits, tracks, digits, and reconstructed points, as
 133       well as geometry and ESD data.   See for example the scripts
 134       @c DrawHits.C, @c DrawHitsDigits.C, @c DrawHitsRecs.C, @c
 135       DrawDigitsRecs.C in the @c FMD/scripts sub-directory.
 136
 137     - AliFMDDisplay: Simple event display for FMD data, including
 138       hits, digits, reconstructed points and ESD data.
 139
 140     - AliFMDCalibFaker, AliFMDAlignFaker: Classes to write fake (or
 141       dummy) calibration and alignment  data.  These derive from
 142       TTask.
 143
 144     @section quick Quick start
 145
 146     First, install ROOT.  Then Install TGeant3:
 147     @verbatim
 148     > cd ~/
 149     > mkdir alice
 150     > cd alice
 151     > cvs -d :pserver:cvs@root.cern.ch:/user/cvs login
 152     Password: cvs
 153     > cvs -d :pserver:cvs@root.cern.ch:/user/cvs co geant3
 154     > cd geant3
 155     > make
 156     @endverbatim
 157
 158     Now you can install AliRoot
 159     @verbatim
 160     > cd ../
 161     > cvs -d :pserver:cvs@alisoft.cern.ch:/soft/cvsroot login
 162     Password: <empty>
 163     > cvs -d :pserver:cvs@alisoft.cern.ch:/soft/cvsroot co AliRoot
 164     > cd AliRoot
 165     > export ALICE_TARGET=`root-config --arch`
 166     > export ALICE=${HOME}/alice
 167     > export ALICE_ROOT=${ALICE}/AliRoot
 168     > export ALICE_LEVEL=new
 169     > export LD_LIBRARY_PATH=${ALICE_ROOT}/lib/tgt_${ALICE_TERGET}:${LD_LIBRARY_PATH}
 170     > export PATH=${ALICE_ROOT}/bin/tgt_${ALICE_TERGET}:${PATH}
 171     > export G3SYS=${ALICE}/geant3
 172     > make
 173     @endverbatim
 174
 175     To simulate one event, do something like
 176
 177     @verbatim
 178     > aliroot ${ALICE_ROOT}/FMD/Simulate.C
 179     @endverbatim
 180
 181     To reconstruct the generated event, do
 182     @verbatim
 183     > aliroot ${ALICE_ROOT}/FMD/Reconstruct.C
 184     @endverbatim
 185
 186     Now, open the file `AliESDs.root' in AliRoot, and browse through  that.
 187
 188     @section authors Authors:
 189
 190     - Alla Maevskaya            <Alla.Maevskaia@cern.ch>
 191     - Christian Holm Christensen        <cholm@nbi.dk>
 192 */
 193 /** @defgroup FMD_sim Simulation */
 194
 195 //____________________________________________________________________
 196 //
 197 //  Manager class for the FMD - Base class.
 198 //  AliFMDv1, AliFMDv0, and AliFMDAlla
 199 //  provides concrete implementations.
 200 //  This class is sooooo crowded
 201 //
 202 #ifndef ALIDETECTOR_H
 203 # include <AliDetector.h>
 204 #endif
 205 #ifndef ROOT_TBranch
 206 # include <TBranch.h>
 207 #endif
 208 class TBranch;
 209 class TClonesArray;
 210 class TBrowser;
 211 class TMarker3DBox;
 212 class AliDigitizer;
 213 class AliFMDHit;
 214
 215 //____________________________________________________________________
 216 /** @class AliFMD AliFMD.h <FMD/AliFMD.h>
 217     @brief Forward Multiplicity Detector based on Silicon wafers.
 218     This class is the driver for especially simulation.
 219
 220     The Forward Multiplicity Detector consists of 3 sub-detectors FMD1,
 221     FMD2, and FMD3, each of which has 1 or 2 rings of silicon sensors.
 222
 223     This is the base class for all FMD manager classes.
 224
 225     The actual code is done by various separate classes.   Below is
 226     diagram showing the relationship between the various FMD classes
 227     that handles the simulation
 228
 229     @verbatim
 230           +----------+   +----------+
 231           | AliFMDv1 |   | AliFMDv0 |
 232           +----------+   +----------+
 233                |              |                    +-----------------+
 234           +----+--------------+                 +--| AliFMDDigitizer |
 235           |                                     |  +-----------------+
 236           |           +---------------------+   |
 237           |        +--| AliFMDBaseDigitizer |<--+
 238           V     1  |  +---------------------+   |
 239      +--------+<>--+                            |  +------------------+
 240      | AliFMD |                                 +--| AliFMDSDigitizer |
 241      +--------+<>--+                               +------------------+
 242                1  |  +---------------------+
 243                   +--| AliFMDReconstructor |
 244                      +---------------------+
 245     @endverbatim
 246
 247     -  AliFMD
 248        This defines the interface for the various parts of AliROOT that
 249        uses the FMD, like AliFMDSimulator, AliFMDDigitizer,
 250        AliFMDReconstructor, and so on.
 251     -  AliFMDv0
 252        This is a concrete implementation of the AliFMD interface.
 253        It is the responsibility of this class to create the FMD
 254        geometry.
 255     -  AliFMDv1
 256        This is a concrete implementation of the AliFMD interface.
 257        It is the responsibility of this class to create the FMD
 258        geometry, process hits in the FMD, and serve hits and digits to
 259        the various clients.
 260     -  AliFMDSimulator
 261        This is the base class for the FMD simulation tasks.   The
 262        simulator tasks are responsible to implment the geoemtry, and
 263        process hits.
 264     -  AliFMDReconstructor
 265        This is a concrete implementation of the AliReconstructor that
 266        reconstructs pseudo-inclusive-multiplicities from digits (raw or
 267        from simulation)
 268
 269     Calibration and geometry parameters are managed by separate
 270     singleton managers.  These are AliFMDGeometry and
 271     AliFMDParameters.  Please refer to these classes for more
 272     information on these.
 273  */
 274 class AliFMD : public AliDetector
 275 {
 276 public:
 277   /** Default constructor.  Do not use. */
 278   AliFMD();
 279   /** Normal constructor
 280       @param name  Name of object.
 281       @param title Title of object. */
 282   AliFMD(const char *name, const char *title);
 283   /** Copy constructor
 284       @param other Object to copy from */
 285   AliFMD(const AliFMD& other);
 286   /** Destructor */
 287   virtual ~AliFMD();
 288   /** Assignment operator
 289       @param other Object to assign from
 290       @return Reference to this object  */
 291   AliFMD& operator=(const AliFMD& other);
 292   /** Wheter to make a detailed geometry
 293       @param use If true, make detailed geometry  */
 294   void UseDetailed(Bool_t use=kTRUE) { fDetailed = use; }
 295
 296   /** @{*/
 297   /** @name GEometry ANd Tracking (GEANT :-) */
 298   /** Define the geometry.  This is done by asking the manager
 299       AliFMDGeometry to construct the geometry.  This in turn calls
 300       AliFMDGeometryBuilder.   */
 301   virtual void   CreateGeometry();
 302   /** Create the tracking mediums used by the FMD.  This associates
 303       the tracking mediums defined with the FMD in the
 304       TVirtualMCApplication (AliMC).
 305
 306       The defined mediums are
 307       - @c FMD @c Si$   Silicon (active medium in sensors)
 308       - @c FMD @c C$    Carbon fibre (support cone for FMD3 and vacuum pipe)
 309       - @c FMD @c Al$   Aluminium (honeycomb support plates)
 310       - @c FMD @c PCB$  Printed Circuit Board (FEE board with VA1_3)
 311       - @c FMD @c Chip$ Electronics chips (currently not used)
 312       - @c FMD @c Air$  Air (Air in the FMD)
 313       - @c FMD @c Plastic$ Plastic (Support legs for the hybrid cards)
 314   */
 315   virtual void   CreateMaterials();
 316   /** Initialize this detector */
 317   virtual void   Init();
 318   /** This member function is called when ever a track deposites
 319       energy (or similar) in an FMD tracking medium.  In this base
 320       class this member function is pure abstract.   In concrete
 321       sub-classes, the member function may make hits or other
 322       stuff. */
 323   virtual void   StepManager() = 0;
 324   /** Called at the end of each simulation event.  If the debug level
 325       is high enough a list of @e bad hits is printed. */
 326   virtual void   FinishEvent();
 327   /** @}*/
 328
 329   /** @{*/
 330   /** @name Graphics and event display */
 331   /** Build simple ROOT TNode geometry for event display. With the new
 332       geometry modeller, TGeoManager, this seems rather redundant. */
 333   virtual        void   BuildGeometry();
 334   /** Draw a shaded view of the Forward multiplicity detector.  This
 335       isn't really useful anymore. */
 336   virtual        void   DrawDetector();
 337   /** Calculate the distance from the mouse to the FMD on the screen
 338       Dummy routine */
 339   virtual        Int_t  DistanceToPrimitive(Int_t px, Int_t py);
 340   /** Store x, y, z of all hits in memory for display.
 341       Normally, the hits are drawn using TPolyMarker3D - however, that
 342       is not very useful for the FMD.  Therefor, this member function
 343       is overloaded to make TMarker3D, via the class AliFMDPoints.
 344       AliFMDPoints is a local class.
 345       @param track the track number to load the hits for */
 346   virtual        void   LoadPoints(Int_t track);
 347   /** @}*/
 348
 349   /** @{ */
 350   /** @name Hit and digit management */
 351   /* Create Tree branches for the FMD.
 352      @param opt  One of
 353      - @c H Make a branch of TClonesArray of AliFMDHit's
 354      - @c D Make a branch of TClonesArray of AliFMDDigit's
 355      - @c S Make a branch of TClonesArray of AliFMDSDigit's */
 356   virtual void          MakeBranch(Option_t *opt=" ");
 357   /** Set the TClonesArray to read hits into.
 358       @param b The branch to containn the hits */
 359   virtual void          SetHitsAddressBranch(TBranch *b);
 360   /** Set branch address for the Hits, Digits, and SDigits Tree. */
 361   virtual void          SetTreeAddress();
 362   /** Get the array of summable digits
 363       @return summable digits */
 364   virtual TClonesArray* SDigits() { return fSDigits; }
 365   /** Reset the array of summable digits */
 366   virtual void          ResetSDigits();
 367   /** Add a hit to the hits tree
 368       @param  track  Track #
 369       @param  vol Volume parameters, interpreted as
 370       - ivol[0]  [UShort_t ] Detector #
 371       - ivol[1]  [Char_t   ] Ring ID
 372       - ivol[2]  [UShort_t ] Sector #
 373       - ivol[3]  [UShort_t ] Strip #
 374       @param hits Hit information
 375       - hits[0]  [Float_t  ] Track's X-coordinate at hit
 376       - hits[1]  [Float_t  ] Track's Y-coordinate at hit
 377       - hits[3]  [Float_t  ] Track's Z-coordinate at hit
 378       - hits[4]  [Float_t  ] X-component of track's momentum
 379       - hits[5]  [Float_t  ] Y-component of track's momentum
 380       - hits[6]  [Float_t  ] Z-component of track's momentum
 381       - hits[7]  [Float_t  ] Energy deposited by track
 382       - hits[8]  [Int_t    ] Track's particle Id #
 383       - hits[9]  [Float_t  ] Time when the track hit */
 384   virtual void          AddHit(Int_t track, Int_t *vol, Float_t *hits);
 385   /** Add a hit to the list
 386       @param track     Track #
 387       @param detector  Detector # (1, 2, or 3)
 388       @param ring      Ring ID ('I' or 'O')
 389       @param sector    Sector # (For inner/outer rings: 0-19/0-39)
 390       @param strip     Strip # (For inner/outer rings: 0-511/0-255)
 391       @param x         Track's X-coordinate at hit
 392       @param y         Track's Y-coordinate at hit
 393       @param z         Track's Z-coordinate at hit
 394       @param px        X-component of track's momentum
 395       @param py        Y-component of track's momentum
 396       @param pz        Z-component of track's momentum
 397       @param edep      Energy deposited by track
 398       @param pdg       Track's particle Id #
 399       @param t         Time when the track hit
 400       @param len       Track length through the material.
 401       @param stopped   Whether track was stopped or disappeared */
 402   virtual AliFMDHit*    AddHitByFields(Int_t    track,
 403                                        UShort_t detector,
 404                                        Char_t   ring,
 405                                        UShort_t sector,
 406                                        UShort_t strip,
 407                                        Float_t  x=0,
 408                                        Float_t  y=0,
 409                                        Float_t  z=0,
 410                                        Float_t  px=0,
 411                                        Float_t  py=0,
 412                                        Float_t  pz=0,
 413                                        Float_t  edep=0,
 414                                        Int_t    pdg=0,
 415                                        Float_t  t=0,
 416                                        Float_t  len=0,
 417                                        Bool_t   stopped=kFALSE);
 418   /** Add a digit to the Digit tree
 419       @param digits
 420       - digits[0]  [UShort_t] Detector #
 421       - digits[1]  [Char_t]   Ring ID
 422       - digits[2]  [UShort_t] Sector #
 423       - digits[3]  [UShort_t] Strip #
 424       - digits[4]  [UShort_t] ADC Count
 425       - digits[5]  [Short_t]  ADC Count, -1 if not used
 426       - digits[6]  [Short_t]  ADC Count, -1 if not used
 427       @param notused Not used */
 428   virtual        void   AddDigit(Int_t *digits, Int_t* notused=0);
 429   /** add a real digit
 430       @param detector  Detector # (1, 2, or 3)
 431       @param ring         Ring ID ('I' or 'O')
 432       @param sector       Sector # (For inner/outer rings: 0-19/0-39)
 433       @param strip        Strip # (For inner/outer rings: 0-511/0-255)
 434       @param count1    ADC count (a 10-bit word)
 435       @param count2    ADC count (a 10-bit word), or -1 if not used
 436       @param count3    ADC count (a 10-bit word), or -1 if not used */
 437   virtual        void   AddDigitByFields(UShort_t detector=0,
 438                                          Char_t   ring='\0',
 439                                          UShort_t sector=0,
 440                                          UShort_t strip=0,
 441                                          UShort_t count1=0,
 442                                          Short_t  count2=-1,
 443                                          Short_t  count3=-1);
 444   /** Add a digit to the Digit tree
 445       @param digits
 446       - digits[0]  [UShort_t] Detector #
 447       - digits[1]  [Char_t]   Ring ID
 448       - digits[2]  [UShort_t] Sector #
 449       - digits[3]  [UShort_t] Strip #
 450       - digits[4]  [UShort_t] ADC Count
 451       - digits[5]  [Short_t]  ADC Count, -1 if not used
 452       - digits[6]  [Short_t]  ADC Count, -1 if not used  */
 453   virtual        void   AddSDigit(Int_t *digits);
 454   /** add a summable digit - as coming from data
 455       @param detector  Detector # (1, 2, or 3)
 456       @param ring      Ring ID ('I' or 'O')
 457       @param sector    Sector # (For inner/outer rings: 0-19/0-39)
 458       @param strip     Strip # (For inner/outer rings: 0-511/0-255)
 459       @param edep      Energy deposited
 460       @param count1    ADC count (a 10-bit word)
 461       @param count2    ADC count (a 10-bit word), or -1 if not used
 462       @param count3    ADC count (a 10-bit word), or -1 if not used */
 463   virtual        void   AddSDigitByFields(UShort_t detector=0,
 464                                           Char_t   ring='\0',
 465                                           UShort_t sector=0,
 466                                           UShort_t strip=0,
 467                                           Float_t  edep=0,
 468                                           UShort_t count1=0,
 469                                           Short_t  count2=-1,
 470                                           Short_t  count3=-1);
 471   /** @}*/
 472
 473   /** @{ */
 474   /** @name Digitisation */
 475   /** Create a digitizer object
 476       @param manager Digitization manager
 477       @return a newly allocated AliFMDDigitizer */
 478   virtual AliDigitizer* CreateDigitizer(AliRunDigitizer* manager) const;
 479   /** Create AliFMDDigit's from AliFMDHit's.  This is done by creating
 480       an AliFMDDigitizer object, and executing it.  */
 481   virtual        void   Hits2Digits();
 482   /** Create AliFMDSDigit's from AliFMDHit's.  This is done by creating
 483       an AliFMDSDigitizer object, and executing it.  */
 484   virtual        void   Hits2SDigits();
 485   /** @}*/
 486
 487   /** @{ */
 488   /** @name Raw data */
 489   /** Turn digits into raw data. This uses the class AliFMDRawWriter
 490       to do the job.   Please refer to that class for more
 491       information. */
 492   virtual        void   Digits2Raw();
 493   /** @}*/
 494
 495   /** @{ */
 496   /** @name Utility */
 497   /** Browse this object
 498       @param b Browser to show this object in */
 499   void   Browse(TBrowser* b);
 500   /** @}*/
 501 protected:
 502   /** Initialize hit array if not already done, and return pointert.
 503       @return Hit array */
 504   TClonesArray*      HitsArray();
 505   /** Initialize digit array if not already done, and return pointert.
 506       @return Digit array */
 507   TClonesArray*      DigitsArray();
 508   /** Initialize summable digit array if not already done, and return
 509       pointert.
 510       @return Summable digit array */
 511   TClonesArray*      SDigitsArray();
 512
 513   TClonesArray*      fSDigits;              // Summable digits
 514   Int_t              fNsdigits;             // Number of digits
 515   Bool_t             fDetailed;             // Use detailed geometry
 516   Bool_t             fUseOld;               // Use old approx geometry
 517   Bool_t             fUseAssembly;          // Use divided volumes
 518
 519   enum {
 520     kSiId,                 // ID index of Si medium
 521     kAirId,                // ID index of Air medium
 522     kPlasticId,            // ID index of Plastic medium
 523     kPcbId,                // ID index of PCB medium
 524     kSiChipId,             // ID index of Si Chip medium
 525     kAlId,                 // ID index of Al medium
 526     kCarbonId,             // ID index of Carbon medium
 527     kCopperId,             // ID index of Copper Medium
 528     kKaptonId              // ID index of Kapton Medium
 529   };
 530
 531   TObjArray*         fBad;                  //! debugging - bad hits
 532
 533   ClassDef(AliFMD,11)     // Base class FMD entry point
 534 };
 535
 536 #endif
 537 //____________________________________________________________________
 538 //
 539 // Local Variables:
 540 //   mode: C++
 541 // End:
 542 //
 543 // EOF
 544 //