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