TangoData.h

Go to the documentation of this file.

/****************************************************************************
           This interface can be used to get hardware detector data
             from Tango (Slow Control System) database
****************************************************************************/
#ifndef TANGODATA_H
#define TANGODATA_H 1
 
#include "TDatime.h"
#include "TObjArray.h"
#include "TString.h"
 
#include <vector>
 
// type of the Tango parameter defined by the table of the Tango database where the parameter is stored
// (values greater than 10 correspond to array parameters, i.e. several channels at every time point)
// The current Tango database (PgSQL) contains only scalar parameters, the arrays are used in the old MySQL database
enum Tango_Parameter_Type
{
    Tango_Bool = 1,           // boolean value (att_scalar_devboolean table)
    Tango_Double = 2,         // numeric value: double (att_scalar_devdouble table), e.g. GEM voltage (vmon_N), or
                              // integer (att_scalar_devshort, devlong, devlong64 and devstate tables), e.g. GEM
                              // channel power (pw_N) or device state; devstate value is the number of Tango
                              // DevState (0 - ON, 1 - OFF, 8 - FAULT, 11 - ALARM, 13 - UNKNOWN, see tango.idl)
    Tango_Bool_Array = 11,    // array of boolean values (att_array_devboolean table of the old MySQL database),
                              // e.g. GEM trips in old periods
    Tango_Double_Array = 12   // array of double values (att_array_devdouble table of the old MySQL database)
};
 
// value(s) of the Tango parameter at a time point, i.e. one element of the Tango data array of TangoData
// The time point is a transition to a new value: the value is valid up to the next time point
class TangoTimeParameter : public TObject
{
  public:
    // parameter time
    TDatime parameter_time;
    // parameter type
    Tango_Parameter_Type parameter_type;
    // parameter values for every channel (one value for a scalar parameter): bool_parameter_value is filled only for
    // boolean parameters, double_parameter_value - for all the types (boolean values are stored as 0 and 1)
    std::vector<bool> bool_parameter_value;
    std::vector<double> double_parameter_value;
 
    /** Default constructor **/
    TangoTimeParameter();
    /** Initialization constructor **/
    TangoTimeParameter(TDatime par_time, Tango_Parameter_Type par_type);
    /** Copy constructor **/
    TangoTimeParameter(const TangoTimeParameter& ttp);
 
    /** Destructor **/
    virtual ~TangoTimeParameter();
 
    ClassDef(TangoTimeParameter, 1);
};
 
// time interval from start_time to end_time, e.g. an interval where a Tango parameter satisfies a condition
// (result of TangoData::SearchTangoIntervals) or the time interval of a run
class TangoTimeInterval : public TObject
{
  public:
    TDatime start_time;
    TDatime end_time;
 
    /** Default constructor **/
    TangoTimeInterval();
 
    /** Initialization constructor **/
    TangoTimeInterval(TDatime start_time_interval, TDatime end_time_interval);
 
    /** Destructor **/
    virtual ~TangoTimeInterval();
 
    ClassDef(TangoTimeInterval, 1);
};
 
// class used to get hardware detector data from Tango database and to display results in console or graphs
// An object stores the values of one Tango parameter (domain/member/attribute) for a time interval or a run range
// as TObjArray of TangoTimeParameter objects (see GetTangoData), prints and draws them, calculates their average
// values and searches the time intervals satisfying a condition; static functions work with a set of parameters,
// e.g. all channels of the FHCal or GEM high voltage
// NOTE: the last archived value is extended up to the end time, even if the archiving was stopped before it
class TangoData
{
  public:
    // conditions for SearchTangoIntervals function comparing the parameter values with a numeric value
    // (conditionLike, conditionNull and conditionNotNull are not supported)
    enum enumConditions
    {
        conditionLess,
        conditionLessOrEqual,
        conditionEqual,
        conditionNotEqual,
        conditionGreater,
        conditionGreaterOrEqual,
        conditionLike,
        conditionNull,
        conditionNotNull
    };
 
    /** Time Range Constructor: fill Tango data array according to the given parameters
     *  Tango database connection is defined in the 'tango_db_settings.h' file
     *  Parameters:
     *  start_date - time from which to start reading the parameter, format: "YYYY-MM-DD HH:MM:SS"
     *               (e.g. "2015-03-13 23:00:00")
     *  end_date - end time of reading the parameter, the same format (e.g. "2015-03-13 24:00:00")
     *  system_name - name of the system, i.e. Tango domain (e.g. "magnet", "fhcal" or "gem")
     *  parameter_name - name of hardware parameter stored in Tango, i.e. Tango attribute
     *                   (e.g. "vch_2_1" for FHCal or "vmon_0" for GEM)
     *  member_name - name of the Tango member, i.e. device (e.g. "hv_1" for FHCal or "mod_0" for GEM),
     *                it can be given with the Tango family as "family/member" if the member name is not unique
     *                in the domain (e.g. "caen_232/mod_2" for CSC or "plane1_top/adcsc_7_temp" for FSD),
     *                empty string - the member is not used
     **/
    TangoData(const char* start_date,
              const char* end_date,
              const char* system_name,
              const char* parameter_name,
              const char* member_name = "",
              int verbose = 0);
 
    /** Run Range Constructor: fill Tango data array for the time interval from the start time of the first run
     *  to the end time of the last run of the given range (the gaps between runs are included)
     *  The run times are taken from the Unified Condition Database
     *  Parameters:
     *  period_number - period (session) number of the runs (e.g. 8)
     *  start_run - number of the first run of the range (e.g. 6000)
     *  end_run - number of the last run of the range (set equal to start_run to read a single run)
     *  system_name, parameter_name, member_name, verbose - the same as in the constructor above
     *  Use GetRunAverageTangoData() to average the parameter only over the time of the runs
     **/
    TangoData(int period_number,
              int start_run,
              int end_run,
              const char* system_name,
              const char* parameter_name,
              const char* member_name = "",
              int verbose = 0);
    // empty destructor
    virtual ~TangoData();
 
    TObjArray* GetTangoData() { return arrTangoData; }
 
    TString GetStartDate() { return strStartDate; }
    TString GetEndDate() { return strEndDate; }
    TString GetSystemName() { return strSystemName; }
    TString GetParameterName() { return strParameterName; }
    TString GetMemberName() { return strMemberName; }
    // period and run range set by the Run Range Constructor (-1 if the object was created for a time interval)
    int GetPeriodNumber() { return iPeriodNumber; }
    int GetStartRun() { return iStartRun; }
    int GetEndRun() { return iEndRun; }
    TString GetUserName() { return strUserName; }
    void SetUserName(TString user_name) { strUserName = user_name; }
    TString GetFullName();
 
    // Function displays hardware data obtained from Tango, e.g. FHCal voltage in time interval, in console
    void PrintTangoDataConsole();
    // Function displays a set of "simple" parameters obtained from Tango, e.g. GEMs high voltages voltage, in console
    static void PrintTangoArrayConsole(std::vector<TangoData*> vecTangoData);
    // Function displays hardware vector data obtained from Tango, e.g. FHCal voltage in time interval, graphically as
    // 2D Surface Graph Parameter: y_axis - label of Y axis
    void PrintTangoDataSurface(const char* y_axis = "tango parameter");
    // Function displays hardware vector data obtained from Tango, e.g. FHCal voltage in time interval, graphically as a
    // set of Line Graphs Parameters: y_axis - label of Y axis, is3D - whether show in 3D view Returns: 0 - in case of
    // the success, < 0 - if an error occured
    // The values are drawn as steps: every value is held up to the time point of the next one
    int PrintTangoDataMultiGraph(const char* y_axis = "parameter", bool is3D = false);
    // Function displays a set of "simple" parameters obtained from Tango, e.g. GEMs high voltages voltage, graphically
    // as a set of Line Graphs
    // The values are drawn as steps: every value is held up to the time point of the next one
    static int PrintTangoArrayMultiGraph(std::vector<TangoData*> vecTangoData,
                                         const char* y_axis = "parameter",
                                         bool is3D = false);
    /** Function displays a set of "simple" parameters obtained from Tango, e.g. FHCal or GEM high voltages,
     *  graphically as 2D Surface (X - time, Y - channel, i.e. index of the parameter in the array, Z - parameter value)
     *  The time interval of the first parameter is divided into equal time bins, and every bin is filled with
     *  the time-weighted average value of the channel in the bin (every value is valid up to the next time point)
     *  Parameters:
     *  z_axis - label of Z axis (parameter values), y_axis - label of Y axis (channels)
     *  draw_option - draw option of the 2D histogram: "SURF1" - surface (default), "LEGO2" - columns,
     *                "COLZ" - 2D color map, etc.
     *  time_bins - number of the time bins
     *  Returns: 0 - in case of the success, < 0 - if an error occured
     **/
    static int PrintTangoArraySurface(std::vector<TangoData*> vecTangoData,
                                      const char* z_axis = "parameter",
                                      const char* y_axis = "channel",
                                      const char* draw_option = "SURF1",
                                      int time_bins = 100);
 
    // Function calculates and returns average value for Tango data array (result vector with size > 1 is used in case
    // of many channels)
    std::vector<double> GetAverageTangoData();
    // Function calculates and returns time-weighted average value for Tango data array only over the time of the runs,
    // i.e. the gaps between runs are excluded (result vector with size > 1 is used in case of many channels)
    // It is available only if the object was created by the Run Range Constructor
    std::vector<double> GetRunAverageTangoData();
 
    /** Function SearchTangoIntervals gets time intervals for defined condition on the parameter values
     *  (e.g. the intervals where a GEM channel was switched off: pw_N parameter, conditionEqual, value = 0)
     *  NOTE: it works only if channel count is constant during given time period
     *  Parameters:
     *  condition - condition of time interval sampling, default: conditionEqual (the possible list is presented above
     *              in 'enumConditions', except conditionLike, conditionNull and conditionNotNull)
     *  value - numeric value for the condition with which the comparison is performed, default: 1 (true);
     *          boolean values of the parameter are compared as 0 (false) and 1 (true)
     *  mapChannel - vector of integer values (map) to change the order of result TObjArray-s in the common result
     *               array, if, for example, channels go in a different sequence; nullptr - if not used
     *  Returns common TObjArray with TObjArray objects containing TangoTimeInterval for every channel
     *  (i.e. conditionally TObjArray<TObjArray<TangoTimeInterval*>>). If there are no intervals found, it returns
     *  an empty TObjArray with zero elements. In case of errors it returns nullptr
     **/
    TObjArray* SearchTangoIntervals(enumConditions condition = conditionEqual,
                                    double value = 1,
                                    std::vector<int>* mapChannel = nullptr);
    /** Function displays (in console) time intervals obtained from Tango for a defined condition
     *  Parameters:
     *  tango_intervals - TObjArray with TObjArray objects containing TangoTimeInterval objects obtained from
     *'SearchTangoIntervals' function channel_name - name of the dimension to display on the screen, default: Channel
     *  isShowOnlyExists - if true, print only intervals which satisfy the condition (skip empty intervals)
     **/
    void PrintTangoIntervalConsole(TObjArray* tango_intervals,
                                   TString channel_name = "Channel",
                                   bool isShowOnlyExists = false);
 
  private:
    bool IsOldMySQL = false;
    TString strSystemName = "", strParameterName = "", strMemberName = "", strUserName = "", strStartDate = "",
            strEndDate = "";
    TObjArray* arrTangoData = nullptr;
    int iVerbose;
    // period and run range, and time intervals of the runs (set only by the Run Range Constructor)
    int iPeriodNumber = -1, iStartRun = -1, iEndRun = -1;
    std::vector<TangoTimeInterval> vecRunIntervals;
 
    // non-user function SetRunRangeDates sets strStartDate and strEndDate to the start time of the first run
    // and the end time of the last run existing in the given run range of the period,
    // and fills vecRunIntervals with the time intervals of the runs (runs without end time are skipped)
    // The last successfully read run range is cached, so the objects for the same runs do not request the database
    // Returns: 0 - in case of the success, < 0 - if an error occured
    int SetRunRangeDates(int period_number, int start_run, int end_run);
 
    // non-user function InitTangoData selects the Tango database (MySQL before 2020-03-25, PgSQL after)
    // by the start date and fills the Tango data array
    void InitTangoData();
 
    // non-user function GetTimeWeightedAverage calculates average value for Tango data array over the given time
    // intervals, where every value is weighted by the length of its validity period inside the intervals
    // Returns empty vector in case of errors
    std::vector<double> GetTimeWeightedAverage(const std::vector<TangoTimeInterval>& time_intervals);
 
    // non-user function GetValuePeriod gets the time period where the value of the i-th Tango time point is valid:
    // from its time point to the next one, the first value is also used from the start date (data_start),
    // the last one - up to the end date (data_end)
    void GetValuePeriod(int i, UInt_t data_start, UInt_t data_end, UInt_t& value_start, UInt_t& value_end);
 
    // non-user function GetTangoParameter gets hardware data from the Tango database and write to the arrTangoData
    // First, name of the target table with required parameter is extracted from the Tango Base Table,
    // then required data are selected from the target table corresponding the given time interval.
    // Returns: 0 - in case of the success, < 0 - if an error occured
    int GetTangoParameter();
 
    // delete Tango parameter
    void DeleteTangoParameter();
 
    ClassDef(TangoData, 3)
};
 
#endif