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 "GETAutoBaselineLow.hh"
#include "GETAutoBaselineHigh.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;

//======================================================================
/*! \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:
 *
 *  - 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;


  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

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

    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)

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

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

    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
    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 ( );

    bool          ChannelHasData ( u_int ic ) 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 GETHitMask  * SetHitMask ( GETHitMask * mask );
    GETHitMask          * GetHitMask ( ) const;          // inline

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


  //----------------------------------------------------------
  /** @name Data (output) correction processes */
  //@{
    virtual int SetCalibProcess       ( const string & calib_file );
    virtual int SetBaselineCorrection ( const string & bl_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 SetAutoBaselineLow  ( u_short num_lo, u_short off_lo = 0 );
    virtual int SetAutoBaselineHigh ( u_short num_hi, u_short off_hi = 0 );
  //@}


  //----------------------------------------------------------
  /** @name Access to class data */
  //@{
    u_int   GetEventCount   ( ) const;      // inline
    string  GetRunFileName  ( ) const;      // inline
  //@}


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

    virtual int   ReadEvent      ( bool process = true );

    virtual int   AnalyseRawEvent ( );
    virtual int   AnalyseCorEvent ( );

    // 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   ProcessMergeFrameData   ( MFMMergeFrame   * frame );
    virtual int   ProcessCoBoFrameData    ( MFMCoboFrame    * frame );
    virtual int   ProcessEbyedatFrameData ( MFMEbyedatFrame * frame );

  //@}

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

    // corrections of raw events
    virtual int   OutputCorrectFPN  ( u_int opt_fpn = GET::CoBoCorrectFPN4 );
    virtual int   ZeroSuppression   ( double thr = 0. );
  //@}

  //----------------------------------------------------------
  /** @name User hook functions */
  //@{

    virtual int   AnyFrameUser     ( MFMCommonFrame  & frame );
    virtual int   MergeFrameUser   ( MFMMergeFrame   & frame );
    virtual int   CoBoFrameUser    ( MFMCoboFrame    & frame );
    virtual int   EbyedatFrameUser ( MFMEbyedatFrame & frame );

  //@}

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

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


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


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