GETSystem.hh

Go to the documentation of this file.

//======================================================================
/*! \file GETSystem.hh
 *
 *  Include file for the GETSystem class.
 */
//======================================================================

#ifndef GET_SYSTEM_HH
#define GET_SYSTEM_HH

//----------------------------------------------------------------------
#include "GETCoBo.hh"
#include "GETRunFile.hh"
#include "GETRunList.hh"
#include "GETRunSerie.hh"

#include "GETProcessSerie.hh"
#include "GETCalibProcess.hh"
#include "GETBaselineCorrection.hh"
#include "GETAutoBaseline.hh"
#include "GETAutoBLoffset.hh"
#include "GETFilterSmooth.hh"

#include "GETCfgSetup.hh"

#include "MFMCoboFrame.h"
#include "MFMCoboTopoFrame.h"
#include "MFMEbyedatFrame.h"
#include "MFMMutantFrame.h"
#include "MFMMergeFrame.h"
#include "MFMXmlFileHeaderFrame.h"

#include "GETLookupTable.hh"
#include "GETHitMask.hh"

#include <TH1D.h>
#include <TH2D.h>
#include <TH3D.h>

class GETSystemAnalyser;

///! Maximum number of bad read data
#define   GET_BAD_READ_MAX    512

/*! Structure for base data read in GET frames.*/
typedef struct
{
  int     Info;       ///< Information about the data: 0=Ok, 1=bad read, 2=removed channel
  u_short CoBo;       ///< Cobo module
  u_short AsAd;       ///< AsAd board
  u_short AGet;       ///< AGET chip
  u_short Channel;    ///< Channel
  u_short Bucket;     ///< Time bucket
  u_short Value;      ///< Value

} GETData;

//======================================================================
/*! \class GETSystem
 *
 *  This class defines a the full GET system, controlling a variable
 *  number of CoBo modules.
 *
 *  The static options may define general behaviour of the system,
 *  such as samples corrections at readout.
 *
 *  The class defines some automatic corrections of raw data samples
 *  when reading an event (see options defined in the GET namespace),
 *  independently of the output data correction processes:
 *
 *  - data-0 correction: set the first sample data to the second one
 *    (this is necessary when the first data is junk when using a reduced
 *     readout depth - seen only in full readout mode... - observed in
 *     2018, with the 2017/02 CoBo firmware)
 *
 *  - correction from FPN channels: 
 *    - GET::CoBoCorrectFPN for closest FPN channel correction
 *    - GET::CoBoCorrectFPN2 for half-chip FPN channels correction
 *    - GET::CoBoCorrectFPN4 for average (AGET chip) FPN channels correction
 *
 *  - apply a (software) zero suppresion on raw data:
 *    this option is not compatible with the FPN correction or with the
 *    automatic baseline correction
 *
 *  Illustration of the event processing with GETSystem class:
 *
 *  \image html GETEventProcessing.png
 *
 *
 *  \par Run files and run series
 *  
 *  When reading events with the GETSystem class (with ReadEvent function),
 *  a file must have been previously opened.
 *
 *  - A run file is either a single file, either a set of several files
 *    with the same name, but with additional prefix \.1, .2... in
 *    case of automatic change of file during acquisition.
 *    - in this case, use the GETSystem::OpenRunFile function
 *    - the input file name may contain a \b * character to indicate
 *      that there can be more than 1 file (for example "run_0201.dat*")
 *  - A run serie is a list of run files, with different run numbers.
 *    - in this case, use the GETSystem::OpenRunSerie function
 *    - the file name must contain a %R code to indicate where is the
 *      run number
 *    - for example, <B><TT> OpenRunSerie ( "run_%4R.dat*", "201:203,206" ) </TT></B>
 *      will request
 *      to process files "run_0201.dat*", "run_0202.dat*", "run_0203.dat*"
 *      and "run_0206.dat*" (see above for the meaning of *).
 *  
 *
 *  \par Lookup table
 *
 *  A lookup table is associated to the GET system object in order to
 *  associate the detector channels positions to the electronics channels.
 *
 *
 *  \par Hit mask and hit channels
 *
 *  A hit mask can be created (the look-up table must be defined) in
 *  order to select the channels for analysis.
 *
 *  The hit mask defines 2 information for each channel:
 *  - whether it is selected for analysis
 *  - whether its signal is large enough
 *
 *
 *  \par Hit channels
 *
 *  It should be noted that independently of the hit mask, the GET system
 *  class defines an array of logical values that indicates whether
 *  the channels have been filled with experimental data (for example
 *  in partial readout mode).
 *
 *  This hit channel information is checked when applying automatic
 *  corrections to the raw data: FPN, automatic baseline, ...
 *
 *
 *  \par Data analyser
 *
 *  The GETSystemAnalyser class is a base class for specific data analysis
 *  to be performed on the GETSystem data.
 *  Such an analyser can be defined with the GETSystem::SetAnalyser function.
 *
 *  If an anlyser is defined, its data analysis functions will be called
 *  before and after output correction when experimental data are read.
 */
class GETSystem : public GETObject
{
  //------------------------------------------------------------
  /*! \object_doc */
  GObject(GETSystem);
  //------------------------------------------------------------

  friend class GETCfgSetup;
  friend class GETHitMask;
  friend class GETSystemAnalyser;


  protected:
    // GET architecture
    u_int         cobo_number;  ///< Number of CoBo modules controlled
    GETCoBo     * cobo;         ///< Array of CoBo modules

    u_int         channel_count;    ///< Total number of channels
    GETChannel ** channel_summary;  ///< Summary of channels pointers
    bool        * channel_hit;      ///< Whether the channel contains data

    u_int         mult_channel;     ///< Multiplicity of non empty channels
    u_int         mult_aget;        ///< Multiplicity of non empty AGet
    u_int         mult_asad;        ///< Multiplicity of non empty AsAd
    u_int         mult_cobo;        ///< Multiplicity of non empty CoBo

    int           test_channel;     ///< Channel index for test outputs (-1 for none)

    // GET system options
    static  u_int   options;    ///< Options for GET system

    // GET configuration
    GETCfgSetup * config;       ///< Configuration data

    // data file
    GETRunFile      * run_file;         ///< Pointer to the input run data

    u_int             mfm_frame_count;  ///< Frame number in current file
    MFMCommonFrame  * mfm_frame;        ///< Common frame for MFM in/out
    MFMCoboFrame    * mfm_frame_cobo;   ///< Specific CoBo frame for MFM in/out

    bool              mfm_event_set;    ///< Test is event number / time stamp is set
    int               mfm_event_num;    ///< Event number from MFM frames
    uint64_t          mfm_event_clock;  ///< Event clock time from MFM frames
    double            mfm_event_time;   ///< Event time (sec) from MFM frames

    char  * mfm_buffer;             ///< MFM frames data buffer
    int     mfm_buffer_size;        ///< Size of allocated buffer
    char ** mfm_buffer_adr;         ///< Pointer of allocated buffer

    u_int   event_count;            ///< Number of events read (in file)
    bool    cor_data;               ///< Whether processing corrected data

    // look-up table
    GETLookupTable  lookup_table;   ///< Lookup table
    GETHitMask    * hit_mask;       ///< Pointer to the hit mask

    // CoBo red data check (current CoBo/AsAd read frame)
    int   cobo_filled     [ASAD_SIZE*AGET_SIZE*GET_MAX_DEPTH];  ///< Memorization of data read in CoBo frame
    int   cobo_last_bucket[ASAD_SIZE*AGET_SIZE];                ///< Memorization of last time bucket read / channel

    u_int   cobo_frame_read;                            ///< Total number of CoBo frames
    u_int   cobo_frame_error;                           ///< Number of CoBo frames with errors
    u_int   cobo_frame_recover;                         ///< Number of CoBo frames with errors that could be recovered

    u_int   bad_cobo_read_count;                        ///< Number of bad data read
    u_int   bad_cobo_read_check;                        ///< Counter of bad data needed for missing channels in data check
    GETData bad_cobo_read_data[GET_BAD_READ_MAX];       ///< Bad data array
    u_int   bad_cobo_read_min;                          ///< Minimum number of data to keep channels in data

    u_int   bad_cobo_channel_count;                     ///< Number for bad channels in CoBo read
    int     bad_cobo_channel_aget [GET_BAD_READ_MAX];   ///< Memorize AGET number for bad channels
    int     bad_cobo_channel_index[GET_BAD_READ_MAX];   ///< Memorize Channel number for bad channels

    // bad data read (remaining after CoBo read analysis)
    u_int   bad_read_count;                     ///< Number of bad data read
    GETData bad_read_data[GET_BAD_READ_MAX];    ///< Bad data array

    // zero suppression
    double  zero_threshold;         ///< Threshold for raw data zero suppression

    u_int   data0_num;              ///< Number of time buckets to set to 0 at beginning of data samples
    u_int   dataN_num;              ///< Number of time buckets to set to 0 at end of data samples

    u_int   saturation_value;       ///< Coder value for channel saturation (set to 0 not to perform the analysis)
    u_int   saturation_mult;        ///< Number of saturated data to consider a channel as saturated
    u_int   saturation_count;       ///< Number of saturated channels (computed at raw event analysis)

    // data analyser
    u_short             selected_analysis;  ///< Flag for selected analysis (see GETSystem::SelectAnalysis function)
    GETSystemAnalyser * analyser;           ///< Pointer to a data analyser

  public:
  //----------------------------------------------------------
  /** @name Constructors, affectation, destructor */
  //@{
    GETSystem ( u_int n_cobo = 1, u_int dim = 0, double dt = 0.01L );
    virtual ~GETSystem ( );
  //@}

  //----------------------------------------------------------
  /** @name Options functions */
  //@{
    static  void  SetOptions ( u_int opts );                  // inline
    static  void  SetOption  ( u_int flags, bool b = true );  // inline
    static  u_int GetOptions ( );                             // inline
    static  bool  GetOption  ( u_int flags );                 // inline

    virtual void  SetZeroSuppressMode ( double thr = 0. );

    virtual void  SetSaturationValue ( int val );     // inline
    virtual int   GetSaturationValue ( ) const;       // inline
    virtual int   GetSaturationCount ( ) const;       // inline

    virtual bool  IsChannelSaturated ( u_int ich );               // inline
    virtual bool  IsChannelSaturated ( const GETChannel & ch );   // inline
  //@}

  //----------------------------------------------------------
  /** @name GET configuration */
  //@{
    virtual int         ResetConfig ( );
    virtual int         InitConfig ( );

    const GETCfgSetup * GetConfig ( ) const;    // inline
          GETCfgSetup * GetConfig ( );          // inline

    virtual int ReadXMLConfig ( const string & fname ); // inline
  //@}

  //----------------------------------------------------------
  /** @name Initialization functions */
  //@{
    virtual void  Reset ( );
    virtual int   Init ( u_int n_cobo, u_int n, double dt );
    virtual void  ClearEvent ( );

    u_int           GetBadReadCount ( ) const;        // inline
    const GETData * GetBadReadData  ( ) const;        // inline
          GETData * GetBadReadData  ( );              // inline
    void            SetBadDataCorrection ( bool b );  // inline

    bool          ChannelHasData ( u_int ic ) const;        // inline
    u_int         CalcMultiplicity ( bool fpn = true );
    u_int         GetChannelMultiplicity ( ) const;   // inline
    u_int         GetAGetMultiplicity    ( ) const;   // inline
    u_int         GetAsAdMultiplicity    ( ) const;   // inline
    u_int         GetCoBoMultiplicity    ( ) const;   // inline
  //@}

  //----------------------------------------------------------
  /** @name GET system core objects functions */
  //@{
    virtual string  GetObjectId ( ) const;                  // inline

    virtual u_int   GetChildrenNumber ( ) const;            // inline
    virtual const   GETObject * GetChild ( u_int i ) const; // inline
    virtual         GETObject * GetChild ( u_int i );       // inline

    const GETCoBo & operator [] ( u_int n ) const;  // inline
          GETCoBo & operator [] ( u_int n );        // inline

    virtual u_int GetCoBoNumber ( ) const;          // inline
    virtual u_int GetAsAdNumber ( ) const;

    virtual int   GetChannelIndex ( const GETChannel * ch );
  //@}

  //----------------------------------------------------------
  /** @name Look-up table and analysis tools */
  //@{
    const GETLookupTable & LookupTable ( ) const;   // inline
          GETLookupTable & LookupTable ( );         // inline

    virtual u_int         GetChannelCount ( ) const;                // inline
    virtual int           GetChannelIndex ( int ix, int iy ) const; // inline
    virtual GETChannel  * GetChannel      ( int ix, int iy ) const; // inline
    virtual GETChannel  * GetChannel      ( u_int n );              // inline

    virtual int           GetTestChannelIndex ( );                  // inline
    virtual GETChannel  * GetTestChannel      ( );                  // inline
    virtual GETChannel  * SetTestChannel      ( int i );            // inline

    virtual GETHitMask  * SetHitMask ( GETHitMask * mask );
    GETHitMask          * GetHitMask ( ) const;          // inline

    virtual int           SetAnalyser ( GETSystemAnalyser * a );
    GETSystemAnalyser   * GetAnalyser ( ) const;        // inline
  //@}


  //----------------------------------------------------------
  /** @name Data correction and processes */
  //@{

    // output corrections
    virtual int SetCalibProcess          ( const string & calib_file, u_short opt = 0 );
    virtual int SetBaselineCorrection    ( const string & bl_file );
    virtual int SetTimeCorrectionProcess ( const string & shift_file );

    virtual int SetOutputSmoothing ( double width );

    virtual int SetAutoBaseline ( u_short num_lo, u_short num_hi,
                                  u_short off_lo = 0, u_short off_hi = 0 );
    virtual int SetAutoBLoffset ( u_short itmin, u_short itmax );

    // response function
    virtual int SetResponseFunctions     ( const string & rf_file );
    virtual int SetAsAdResponseFunctions ( const string & rf_file );

  //@}


  //----------------------------------------------------------
  /** @name Experimental data readout */
  //@{
    virtual int   OpenRunFile   ( const string & fname );
    virtual int   OpenRunSerie  ( const string & pattern, const string & serie );
    virtual int   CloseRunFile  ( );

    void          IncrEventCount ( );         // inline
    u_int         GetEventCount  ( ) const;   // inline
    string        GetRunFileName ( ) const;   // inline
    bool          IsRunFileOpen  ( ) const;   // inline
    GETRunFile  * GetRunFile     ( );         // inline

    ////virtual int   ReadEvent      ( bool process = true );
    virtual int   ReadEvent     ( );

    MFMCommonFrame  * GetCurrentMFMFrame   ( );         // inline
    int               GetAcqEventNumber    ( ) const;   // inline
    uint64_t          GetAcqEventTimeStamp ( ) const;   // inline
    double            GetAcqEventTimeSec   ( ) const;   // inline

    virtual void  SelectAnalysis      ( u_short sel );    // inline
    virtual void  SetAnalysis         ( u_short sel, bool b = true ); // inline
    virtual void  SetInputRecAnalysis ( bool b = true );  // inline
    virtual void  SetRawDataAnalysis  ( bool b = true );  // inline
    virtual void  SetCorDataAnalysis  ( bool b = true );  // inline
    u_short       GetAnalysisFlags ( ) const;       // inline
    bool          AnalyseInputRec  ( ) const;       // inline
    bool          AnalyseRawData   ( ) const;       // inline
    bool          AnalyseCorData   ( ) const;       // inline

    virtual int   AnalyseEvent ( );
    virtual int   AnalyseRawEvent ( );
    virtual int   AnalyseCorEvent ( );
    virtual bool  AnalysingRaw ( ) const;           // inline
    virtual bool  AnalysingCor ( ) const;           // inline

    // read the frames
    virtual int   ExtractXMLFileHeaderFrame ( );
    virtual int   ExtractCoboTopoFrame      ( );
    virtual int   ExtractCoboFrame          ( );
    virtual int   ExtractEbyedatFrame       ( );
    virtual int   ExtractMergeFrame         ( );

    // get the data
    virtual int   ProcessFrameData        ( MFMCommonFrame  * frame );
    virtual int   ProcessEbyedatFrameData ( MFMEbyedatFrame * frame );
    virtual int   ProcessMergeFrameData   ( MFMMergeFrame   * frame );
    virtual int   ProcessCoBoFrameData    ( MFMCoboFrame    * frame );

    u_int         GetCoBoFrameRead    ( ) const;    // inline
    u_int         GetCoBoFrameError   ( ) const;    // inline
    u_int         GetCoBoFrameRecover ( ) const;    // inline

    virtual void  ClearCoBoDataRead ( );
    virtual int   CheckCoBoData     ( u_int cobo, u_int asad, u_int & aget, u_int & chan, u_int & buck, u_int val );

    virtual u_int CheckCoBoFrameBadChannels ( int ico, int ias );
    virtual u_int CorrectCoBoFrameBadData   ( int ico, int ias );
  //@}

  //----------------------------------------------------------
  /** @name Events processing and correction */
  //@{
    virtual GETChannel  * GetMaximumChannel ( u_short info = GET::signalOut, bool integ = false );

    // corrections of raw events
    void          SetOutputData0correction ( u_int n );
    void          SetOutputDataNcorrection ( u_int n );
    u_int         GetOutputData0correction ( ) const;     // inline
    u_int         GetOutputDataNcorrection ( ) const;     // inline

    virtual int   OutputCorrectData0 ( );
    virtual int   OutputCorrectDataN ( );
    virtual int   OutputCorrectFPN   ( u_int opt_fpn = GET::CoBoCorrectFPN4 );
    virtual int   ZeroSuppression    ( double thr = 0. );
  //@}

  //----------------------------------------------------------
  /** @name User hook functions */
  //@{
    virtual int   UserRawEvent ( );
    virtual int   UserCorEvent ( );

    virtual int   UserAnyFrame     ( MFMCommonFrame  & frame );
    virtual int   UserMergeFrame   ( MFMMergeFrame   & frame );
    virtual int   UserCoBoFrame    ( MFMCoboFrame    & frame );
    virtual int   UserEbyedatFrame ( MFMEbyedatFrame & frame );

  //@}

  //----------------------------------------------------------
  /** @name ROOT related functions */
  //@{
  public:

    /*! for use within ROOT.*/
    ClassDef(GETSystem,0);
  //@}
};


//----------------------------------------------------------------------
//  Inline functions
#include "icc/GETSystem.icc"


//======================================================================
#endif