// // File : EyeEventHeader.hh // // Purpose: Header file for EyeEventHeader.cc, // containing TEyeEventHeader class declaration // // $Id: EyeEventHeader.hh 12083 2011-02-21 17:11:42Z mathes $ // #ifndef _EyeEventHeader_hh_ #define _EyeEventHeader_hh_ /** @file EyeEventHeader.hh * Declaration of the class TEyeEventHeader. * @author H.-J. Mathes, FzK */ #include #include #include #include #include #include // --- forward declaration(s) class TMirrorEventHeader; class TFADCData; namespace Evb { class EyeEventConverter; } /** Class for the event header of an Eye event. * * This class contains the following data: * @li the number (id) of the Eye where the event comes from. * @li data and time of the event (via a TTimeStamp object) * @li a bit mask indicating which Mirrors participate in the RUN. * @li a bit mask indicating from which Mirror data are present in this event. * @li the time offset of the individual mirrors for this event. * * FD-Time calculation * * For the time tagging of the FD events the Motorola Oncore UT+ module is * used. This clock delivers a signal with a period of 1 seconds (1 pps * signal) which has due to an internal oscillator of 10 MHz a granularity of * 100 ns. In addition the 1 pps pulses might happen slightly shifted with * respect to the true GPS 1 pps. Therefor the so called negative sawtooth * correction values have to be applied to obtain the correct time. Details * about that could be found at the following URL:
* @see http://www.obs-besancon.fr/www/auger/ttagtests.pdf * * According to the conventions for the Pierre Auger Observatory,
* @see https://edms.cern.ch/cedar/plsql/doc.info?document_id=317390 * the earliest time of a collection of times should be assigned to this * collection as its time and all the other times have to be expressed with * the offset with respect to the eraliest time. Therefor after this class * calculates also the time offsets for all the mirrors which are present * in the current event. */ class TEyeEventHeader : public TObject { friend class TEyeEvent; friend class Evb::EyeEventConverter; public: /** Constants exported by this class. */ enum { /** The default number of ticks per second (assuming 80 MHz clock of * the Motorola Oncore UT+ module). */ kTicksPerSecond = 80000000, /** Number of nanosecs per second. */ kNanoSecPerSecond = 1000000000 }; /** Enumeration type for the various event types. The event type is * determined by the trigger type which gives that event. */ typedef enum { /** Event type is not known or not set. */ kUnknown, /** A physics event, the real purpose of the DAQ. */ kPhysics, /** Any type of artificial (calibration) event. */ kCalibration, /** A simulated event, usually generated by the DAQ simulation * (no physics). */ kSimulated, /** Event happened in the time window (offset) assigned to the * laser shooting. */ kLaserOffset, /** Event happened in the time window (offset) assigned to the * flasher shooting. */ kFlasherOffset, /** Event happened in the time window (offset) assigned to any * calibration light sources activity. */ kCalibrationOffset, /** Event happened in the time window (offset) assigned to the * LIDAR shooting. */ kLidarOffset, /** Event happened in the time window (offset) assigned to any * Aerosol Phase Function shooting. */ kAPFOffset, /** Last, but invalid event type. */ kInvalidType } EEventType; /** Event classes which are used as attributed for analysed events. * * If an event contains for example muon pattern and shower data pattern * it will be finally classified as a shower as the muon data should be * removed from the event. */ typedef enum { /** No classification of the event was done so far. */ kUnClassified, /** Event is a calibration or simulation event. */ kNoPhysicsEvent, /** Event has too many pixels to be something reasonable. */ kLargeEvent, /** Event could be everything but the algorithmus is not able to deal * with the found signature ... */ kUnhandledSignature, /* No pixels matching pattern. */ kEmpty, /** Event has muon signature. It contains only 4 pixels * with the same T1. */ kIsMuon, /** Event has muon signature. It contains >= 4 pixels. * The pixels FADC data * are analized to perform this classification. */ kLongMuon, /** Event has close shower signature, i.e. shower close * to the telescope with duration smaller than 1 micros. * It contains >= 4 pixels. The pixels FADC data are * analized to perform this classification. T3 is not sent * to CDAS. */ kCloseShower, /** Event has noise signature. */ kNoise, /** Event has muon and noise signature. */ kMuonAndNoise, /** This event is excluded because of a certain time signature. * This could be for example be ralated to a laser shot. */ kVetoedEvent, /** Event has shower candidate signature, * with duration greater than 1 microsec. */ kShowerCandidate, /** Event has horizontal shower candidate signature. * No extrapolation to ground can be performed. */ kHorizontalShower, /** Event has shower signature, with duration greater * than 1 microsec. T3 sent to CDAS. */ kIsShower, // >>> more classes might come in here ... // ... // >>> some place holders for user defined event classes /** 1st user defined event class. */ kUserDefined1 = 90, /** 2nd user defined event class. */ kUserDefined2, /** 3rd user defined event class. */ kUserDefined3, /** 4th user defined event class. */ kUserDefined4, // >>> explicitely named, user defined event classes /** Used to tag noise events identified by the UBA T3 extension. */ kUBANoise = kUserDefined1, /** Event is rejected (by TLT) but kept in the data stream * for trigger performance/efficiency studies. */ kRejected = 98, /** Last, but invalid event class. */ kInvalidClass } EEventClass; /** This enum defines the menaing of the different status bits in the * fStatusBits member. */ typedef enum { kLidarIsTriggered = 0x00000001, //<<< LIDAR was active kT3IsCDASVetoRejected = 0x00000002, //<<< T3 rejected by T3-CDAS VETO kT3IsDelayRejected = 0x00000004, //<<< T3 rejected 'cos too late kT3IsCDASRejected = 0x00000008 //<<< T3 rejected by CDAS (remote) } EHeaderStatusBits; /** This enum is used to qualify the quality of the GPS time correction * done. In detail we have: @li kCorrectionNotSet is set when the data contains no time correction information at all, i.e. for very old data, or periods where the DAQ was not able to handle a missing/fauklty GPS clock @li kUnknownQuality is set when nothing is known about the fact if a time correction was done, used probably for some old data @li kAveragedPeriod is set when the DAQ has no access to the GPS clock and therefor uses the T1 from an ini-file @li kFullQuality is set when both time correction constants are present * */ typedef enum { kCorrectionNotSet = -1, //<<< default before corr. parms are set kUnknownQuality = 0, //<<< unknown quality kAveragedPeriod, //<<< average T10 is set kFullQuality //<<< T10 and offset are set } ETimeCorrectionQuality; public: /** Constructor for the class TEyeEventHeader. * * The following fields are initialized: * @li the eye number is initialized to FD_FIRST_EYE * @li the event number is set to 0. * @li the mirror data status bits (preset to all 0). * @li the mirror present bits (preset to all 0). * @li the time offsets of all Mirrors to 0. * @li the time correction contants to: *
    *
  • the second start offset to 0 *
  • the second end offset to 0 *
  • the number of ticks per second to kTicksPerSecond *
*/ TEyeEventHeader(); /** Copy constructor of the class TEyeEventHeader. */ TEyeEventHeader(const TEyeEventHeader&); /** Destructor for the class TEyeEventHeader. */ virtual ~TEyeEventHeader(); /** Assignment operator for the class TEyeEventHeader. */ TEyeEventHeader& operator=(const TEyeEventHeader&); /** operator==() for the class TEyeEventHeader. */ bool operator==(const TEyeEventHeader& rhs) const { return this == &rhs; } /** Calculate the correct event times for all added Mirrors and for the Eye. * * This works only, if: * @li the raw mirror time has been set (method SetRawMirrorTime()) * @li the correction factors for the absolute time are set (method(s) * SetTimeCorrectionParameters() * * Only after this step, the fields fMirrorTimeOffset[] and fTimeStamp * will have correct values. */ void AdjustMirrorTimes(); /** Correct the time tuple (sec, nsec) by using the time correction * constants stored in this class. */ bool DoTimeCorrection(unsigned int sec_in,int nsec_in, unsigned int* sec_out,unsigned int* nsec_out); /** Print the events content to cout (or any other stream). */ void Show(std::ostream& ostr=std::cout) const; // --- getters ... /** Get a mirrors individual accumulated Dead time (in units of 100ns). */ unsigned long long GetDeadTimeCounter(unsigned int) const; /** Get the event class asigned (by the T3) to this event. */ EEventClass GetEventClass() const { return (EEventClass)fEventClass; } /** Get the event type (trigger type) asigned to this event. */ EEventType GetEventType() const { return (EEventType)fEventType; } /** Return the event number of the current event. */ unsigned int GetEventNo() const { return fEventNumber; } /** Get the dead time [sec] caused by the DAQ of the EyePC. */ unsigned long long GetEyeDaqDeadTime() const { return fEyeDaqDeadTime; } /** Get the official number of the Eye which measured that event. */ unsigned int GetEyeNo() const { return fEyeNumber; } /** Get the (eventually corrected) nano time of the specified bin * for the passed FADC. */ unsigned int GetFADCBinNanoTime(const TFADCData*,unsigned int); /** Get the (eventually corrected) time of the specified bin * for the passed FADC. */ unsigned int GetFADCBinTime(const TFADCData*,unsigned int); /** Get the start nano time of the FADC trace of the passed FADC. */ unsigned int GetFADCTraceStartNanoTime(TFADCData* fadc) { return GetFADCBinNanoTime( fadc, 0 ); } /** Get the start time of the FADC trace of the passed FADC. */ unsigned int GetFADCTraceStartTime(TFADCData* fadc) { return GetFADCBinTime( fadc, 0 ); } /** Get the dead time [sec] caused by the individual DAQ of a MirrorPC. */ unsigned long long GetMirrorDaqDeadTime(unsigned int mirror_id) const; /** Get a telescopes individual event label (TLT class): */ int GetMirrorEventLabel(unsigned int mirror_id) const; /** Convert the EEventType to the EMiEventType. */ static TMirrorEventHeader::EMiEventType GetMirrorEventType(EEventType); /** Get the number of skipped triggers caused by each individual Mirror DAQs burst rejection. */ unsigned int GetMirrorNSkippedTriggers(unsigned int) const; /** Get the data present status vector which indicates which Mirrors have * data in this event. */ unsigned int GetMirrorDataBits() const { return (unsigned int)fMirrorDataBits; } /** Get the status vector which indicates which Mirrors have participiated * in the DAQ. */ unsigned int GetMirrorStatusBits() const { return (unsigned int)fMirrorStatus; } /** Get the time offset of the specified mirror in nanoseconds. * * If the specified mirror is not present in the data, 0 is returned. */ unsigned int GetMirrorTimeOffset(unsigned int) const; /** Get the number of rejected (by all active T3 VETOs) T3s for this run. */ unsigned int GetNRejectedT3() const { return fNRejectedT3; } /** Get the raw mirror time for the individual mirror. * * If the selected Mirror is not existing, NULL is returned. */ const FdRoot::TTimeStamp *GetRawMirrorTimeStamp(unsigned int) const; /** Get the number of the current RUN. * * If this number has not been previously initialized, 0 is returned. */ unsigned int GetRunNo() const { return fRunNo; } /** Get a mirrors individual accumulated RUN time (in units of 100ns). */ unsigned long long GetRunTimeCounter(unsigned int) const; /** Get the status bit flags (vector) of the event header. */ EHeaderStatusBits GetStatusBits() const { return (EHeaderStatusBits)fStatusBits; } /** Get the GPS time correction quality. */ ETimeCorrectionQuality GetTimeCorrectionQuality() const { return (ETimeCorrectionQuality)fTimeCorrectionQuality; } /** Get the total dead time [sec] for T3-CDAS due to the T3-CDAS VETO. */ float GetTotalT3DeadTime() const { return fTotalT3DeadTime; } #ifndef __CINT__ /** Get the trigger sopurce for an individual mirror. */ TMirrorEventHeader::EMiTriggerSource GetTriggerSource(unsigned int) const; #endif // __CINT__ /** Get the 'trigger time stamp' of the selected Mirror. * * Note: This method will return 0 in case the selected Mirror is not * present in the data or outside the allowed range for Mirror ids. */ unsigned int GetTriggerTimeStamp(unsigned int) const; /** Get the current values for the time correction parameters. * * Time correction parameters are only available when they have been * set by using the SetTimeCorrectionParameters() methods or when * streaming an event from file. */ void GetTimeCorrectionParameters(Float_t *t10,Float_t *offset) const; /** Get the time stamp of the current event. */ const FdRoot::TTimeStamp *GetTimeStamp() const { return (FdRoot::TTimeStamp*)&fTimeStamp; } /** Get the T3 id which has been assigned to this event by the T3 processor * of the event builder. If no id has been assigned, 0 is returned. */ UShort_t GetT3Id() const { return fT3Id; } /** Get the time stamp for the T3 at ground. */ const FdRoot::TTimeStamp *GetT3TimeStamp() const { return (FdRoot::TTimeStamp*)&fT3TimeAtGround; } /** Get the accumulated VETO time until this event (in units of 100ns). */ unsigned long long GetVetoTimeCounter() const { return fVetoTimeCounter[0]; } /** Check if the time correction parameters are set. * * @return true if the time correction parameters are set */ bool IsTimeCorrectionSet(); /** Check if the current TEyeEvent has been classified and return false if * this is the case. */ bool IsUnclassified() const { return ( fEventClass == kUnClassified ) ? true : false; } /** Test if data of the specified mirror is present. * * @param mirror_id the mirrors id, range 1 .. 6 * * If an incorrect mirror id is specified the function returns kFALSE, * otherwise the status of the flag. */ bool IsMirrorDataPresent(unsigned int mirror_id) const; /** Query the status vector flag for the specified mirror. * * This function will return kTRUE, if the specified Mirror participiated * in the DAQ. * * @param mirror_id the mirrors id, range 1 .. 6 * * If an incorrect mirror id is specified the function returns kFALSE, * otherwise the status of the flag. */ bool IsMirrorPresent(unsigned int mirror_id) const; /** Get the value of the status bits which indicate that this event is a rejected T3 (by the T3-CDAS VETO). */ bool IsRejectedT3() const { return ( (fStatusBits & kT3IsCDASVetoRejected) || (fStatusBits & kT3IsDelayRejected) || (fStatusBits & kT3IsCDASRejected) ) ? true : false; } /** Get the status of the LIDAR trigger during that event. */ bool IsLidarTriggered() const { return (fStatusBits & kLidarIsTriggered) ? true : false; } // --- setters ... /** Set the value for a Mirrors individual DEAD time counter. */ void SetDeadTimeCounter(unsigned long long,unsigned int); /** Set the internal event number for this event. */ void SetEventNo(unsigned int evnum) { fEventNumber = evnum; } /** Assign an event class (result of the T3) to this event. */ void SetEventClass(EEventClass cl) { fEventClass = cl; } /** Assign an event type (trigger type) to this event. */ void SetEventType(EEventType type) { fEventType = type; } /** Set the dead time which is caused by the Eye DAQ. */ void SetEyeDaqDeadTime(unsigned long long dead_time) { fEyeDaqDeadTime= dead_time; } /** Set the number of the Eye which measured that event in the data. */ void SetEyeNo(unsigned int eye_no) { fEyeNumber = eye_no; } /** Set a status bit that event is a T3 rejected by CDAS (unknown reason). */ void SetIsCDASRejectedT3() { fStatusBits |= kT3IsCDASRejected; } /** Set a status bit that event is a T3 rejected by the T3-CDAS VETO. */ void SetIsCDASVetoRejectedT3() { fStatusBits |= kT3IsCDASVetoRejected; } /** Set a status bit that event is a T3 rejected by the T3 Delay VETO. */ void SetIsDelayRejectedT3() { fStatusBits |= kT3IsDelayRejected; } /** Set the current status of the LIDAR trigger during that event. */ void SetLidarIsTriggered() { fStatusBits |= kLidarIsTriggered; } /** Set the dead time caused by the individual Mirror DAQ. */ void SetMirrorDaqDeadTime(unsigned long long,unsigned int mirror_id); /** Set a flag that mirror data is present in this event. * * The EyeEventHeader contains a status vector with the information about * the data of each mirror belonging to that eye. * * When an invalid mirror id is specified the function prints a warning * but doesn't modify the status vector flags. */ void SetMirrorDataPresent(unsigned int); /** Set a telescopes individual event label (TLT class): */ void SetMirrorEventLabel(Int_t,unsigned int mirror_id); /** Set the number of skipped triggers caused by each individual Mirror * DAQs burst rejection. */ void SetMirrorNSkippedTriggers(unsigned int,unsigned int mirror_id); /** Set a flag that mirror is present in this RUN. */ void SetMirrorPresent(unsigned int); /** Set the number of T3 so far rejected (= not sent to CDAS etc.) by * any T3 rejection. * * This includes: * @li T3s rejected by T3-CDAS-VETO (inside Evb), bit 'kT3IsCDASVetoRejected' * @li T3s rejected by T3-DELAY-VETO (inside Evb), bit 'kT3IsDelayRejected' * @li T3s sent to CDAS but rejected there (not implemented), * bit 'kT3IsCDASRejected' */ void SetNRejectedT3(unsigned int n_rejected) { fNRejectedT3 = n_rejected; } /** Set time information for the specified mirror. */ void SetRawMirrorTime(unsigned int,FdRoot::TTimeStamp&); /** Set the RUN number of the current RUN. */ void SetRunNo(unsigned int run_no) { fRunNo = run_no; } /** Set the value for a Mirrors individual RUN time counter. */ void SetRunTimeCounter(unsigned long long,unsigned int); /** Set the 'raw' correction parameters for the correction of the * absolute event time. * * The plausibility of the passed parameters is checked before the final * time correction parameters are calculated form them. * * The adjustment of the absolute time is then done with the call of the * method AdjustMirrorTimes(). */ void SetTimeCorrectionParameters(short start_offset,short end_offset, unsigned int ticks_per_sec, unsigned int pps_phase=0); /** Set the 'final' correction parameters for the correction of the * absolute event time. * * The plausibility of the passed parameters is checked. */ void SetTimeCorrectionParameters(Float_t t10,Float_t offset=0); /** Set the time stamp for the current event. */ void SetTimeStamp(UInt_t,UInt_t); /** Set the time stamp for the current event. */ void SetTimeStamp(FdRoot::TTimeStamp* datime) { fTimeStamp = *datime; } /** Set the time stamp for the current event. */ void SetTimeStamp(FdRoot::TTimeStamp& datime) { fTimeStamp = datime; } #ifndef __CINT__ /** Set the trigger source for each individual Mirror. * * Usually all trigger sources should be the same (more or less). */ void SetTriggerSource(TMirrorEventHeader::EMiTriggerSource,UInt_t); #endif // __CINT__ /** Set the 'trigger time stamp' (hardware register value) for the * specified Mirror. */ void SetTriggerTimeStamp(UInt_t timestamp,UInt_t); /** Set the T3 id of the current event. */ void SetT3Id(UShort_t t3_id) { fT3Id = t3_id; } /** Set the time stamp for the T3 at ground. */ void SetT3TimeStamp(UInt_t,UInt_t); /** Set the time stamp for the T3 at ground. */ void SetT3TimeStamp(FdRoot::TTimeStamp* t3) { fT3TimeAtGround = *t3; } /** Set the time stamp for the T3 at ground. */ void SetT3TimeStamp(FdRoot::TTimeStamp& t3) { fT3TimeAtGround = t3; } /** Set the total dead time accumulated by the T3-CDAS VETO. */ void SetTotalT3DeadTime(float total_time) { fTotalT3DeadTime = total_time; } /** Set the value for the VETO time counter. This value is the * same for all telescopes of an Eye building. */ void SetVetoTimeCounter(unsigned long long veto_ctr) { fVetoTimeCounter[0] = veto_ctr; } public: /** Get verbose EEventClass string. */ static const char* GetVerboseEventClass(TEyeEventHeader::EEventClass); /** Get verbose EEventType string. */ static const char* GetVerboseEventType(TEyeEventHeader::EEventType); /** Get verbose ETimeCorrectionQuality string. */ static const char* GetVerboseTimeCorrectionQuality(TEyeEventHeader::ETimeCorrectionQuality); protected: /** Convert the 'raw' time corrections parameters in the two final * parameters 'T10MHz' and 'offset'. */ void ConvertTimeCorrectionParameters(); /** Set the actual quality of the time correction. */ void SetTimeCorrectionQuality(ETimeCorrectionQuality quality) { fTimeCorrectionQuality = quality; } // --- Streamer() methods to read old data /** Streamer method for V4 data, CVS tags v0r8 ... v0r8p6. */ void StreamerV4(TBuffer&); /** Streamer method for V5 data, CVS tags v0r8p7(!?), v0r9 ... v1r0p4. */ void StreamerV5(TBuffer&); /** Streamer method for V6 data, CVS tags v1r1 ... v1r1p2. */ void StreamerV6(TBuffer&); /** Streamer method for V7 data, CVS tags v1r1p5(!?),v1r2 ... v1r4p2. */ void StreamerV7(TBuffer&); /** Streamer method for V8 data, CVS tags v1r5 ... v1r6p7. */ void StreamerV8(TBuffer&); private: Version_t fStreamerVersion; //! version read from file // --- general eye related stuff UInt_t fEventNumber; // The internal number of the event UChar_t fEyeNumber; // Official eye number (1..4) Int_t fEventClass; // T3 class assigned to this event Int_t fEventType; // type of event (assigned by trigger) // --- general, run related stuff UChar_t fMirrorDataBits; // Bit for each mirror present in evt. UChar_t fMirrorStatus; // Bit for each mirror in DAQ UInt_t fRunNo; // the number of this run UChar_t fTriggerSource[6]; // mirrors actual trigger sources UInt_t fStatusBits; // some status bits (EHeaderStatusBits) // --- event time related stuff FdRoot::TTimeStamp fTimeStamp; // Time & date of the event, corrected (NxPage) Short_t fSecStartOffset; //! Shift of second start Short_t fSecEndOffset; //! Shift of second end UInt_t fTicksPerSecond; //! 80 MHz ticks per second UInt_t fPPSPhase; //! Delay between PPS and SecondStrobe // only these parameters are stored ! Int_t fTimeCorrectionQuality; // quality of time corr. Float_t fT10Mhz; // Average duration of a '10 MHz' cycle Float_t fOffset; // Offset between SecStrb - real second UInt_t fMirrorTimeOffset[FdUtil::Fd::kEYE_NMIRRORS]; // Adjusted offsets FdRoot::TTimeStamp fRawMirrorTime[FdUtil::Fd::kEYE_NMIRRORS]; // Uncorr. mirror time UInt_t fTriggerTimeStamp[FdUtil::Fd::kEYE_NMIRRORS]; // HW value // --- accumulated DEAD, VETO & RUN times since start of RUN #ifndef __CINT__ unsigned long long fDeadTimeCounter[FdUtil::Fd::kEYE_NMIRRORS]; #else UInt_t fDeadTimeCounter[2][FdUtil::Fd::kEYE_NMIRRORS]; #endif // __CINT__ // Note: we don't need an array but the CINT generated code has/had // problems with the type 'long long'. #ifndef __CINT__ unsigned long long fVetoTimeCounter[1]; #else UInt_t fVetoTimeCounter[2][1]; #endif // __CINT__ unsigned long long fRunTimeCounter[FdUtil::Fd::kEYE_NMIRRORS]; // --- accumulated dead times caused by the DAQ ULong64_t fEyeDaqDeadTime; ULong64_t fMirrorDaqDeadTime[FdUtil::Fd::kEYE_NMIRRORS]; UInt_t fMirrorNSkippedTriggers[FdUtil::Fd::kEYE_NMIRRORS]; // --- more, telescope relates stuff Int_t fMirrorEventLabel[FdUtil::Fd::kEYE_NMIRRORS]; // --- T3 related stuff UShort_t fT3Id; // T3 id, assigned by the T3 proc. FdRoot::TTimeStamp fT3TimeAtGround; // T3 time at ground UInt_t fNRejectedT3; // number of T3s rejected so far Float_t fTotalT3DeadTime; // total T3 dead time ClassDef(TEyeEventHeader,EyeEVENTVERSIONv10) }; #endif // _EyeEventHeader_hh_