CARMA C++
regcal.h
1 #ifndef regcal_h
2 #define regcal_h
3 
4 #include "carma/szaarrayutils/arraymap.h"
5 #include "carma/szaarrayutils/regset.h"
6 #include "carma/szaarrayutils/regdata.h"
7 #include "carma/szaarrayutils/input.h"
8 
9 typedef struct RegCal RegCal;
10 
11 /*
12  * This module provides facilities for converting selected 32-bit int
13  * archived data to physical double precision values. Calibration
14  * offsets and scale factors to be applied during this process are
15  * taken from a RegCal object. Such objects are initialized from text
16  * input streams. In addition, integrated registers are divided by the
17  * value of the frame.nsnap register to yield mean values per
18  * snapshot. This requires that the frame.nsnap register slot contain
19  * valid data (for this reason MonitorStream objects silently select
20  * this register if it isn't selected for monitoring).
21  *
22  * Some archive values such as bit-masks are inherently 32 bit
23  * integers and will presumably be promptly returned to that form.
24  * Assuming that the calibration file doesn't specify a non-unity
25  * scale factor or a non-zero offset, we can guarantee that the
26  * conversion to and from a double is lossless because ANSI/ISO C
27  * mandates that a double must be able to exactly represent any
28  * number of at least 10 decimal digits.
29  *
30  * The calibration of scalar registers is implemented as:
31  *
32  * reg[i] = offset + factor * reg[i].
33  *
34  * The calibration of complex registers is implemented as:
35  *
36  * real = reg[i]
37  * imag = reg[i+1]
38  * reg[i] = offset + factor * real;
39  * reg[i+1] = offset + factor * (imag/imag_gain + real * sin(phi)) / cos(phi);
40  */
41 
42 /*
43  * Create a calibration object for a given register map.
44  */
45 RegCal *new_RegCal(ArrayMap *arraymap);
46 
47 /*
48  * Delete a redundant calibration object.
49  */
50 RegCal *del_RegCal(RegCal *regcal);
51 
52 /*
53  * Load calibration parameters from a file. Note that this is just a
54  * convenient wrapper around load_cal_stream() that creates a
55  * temporary input stream and attaches it to the specified file.
56  */
57 int load_cal_file(ArrayMap *arraymap, RegCal *regcal, char *dir, char *name);
58 
59 /*
60  * Load calibration parameters from an input stream.
61  */
62 int load_cal_stream(ArrayMap *arraymap, RegCal *regcal, InputStream *stream);
63 
64 /*
65  * The following structure contains a double precision array having
66  * the same dimension as an archive frame. calibrate_regdata()
67  * returns its results in a container of this type.
68  */
69 typedef struct {
70  unsigned nslot; /* The number of elements in slot[] */
71  double *slots; /* The array of monitored registers */
72  int empty; /* True until the first successful call to */
73  /* calibrate_regdata(). */
74 } RegCalData;
75 
76 /*
77  * The following functions create and destroy RegCalData objects.
78  * Note that a given RegCalData object should only be used with
79  * the register map that was passed to new_RegCalData().
80  */
81 RegCalData *new_RegCalData(ArrayMap *arraymap);
82 RegCalData *del_RegCalData(RegCalData *cal);
83 
84 /*
85  * Calibrate selected registers while copying them from a raw archive
86  * array of 32-bit unsigned integers to a parallel double precision array.
87  */
88 int calibrate_regdata(ArrayMap *arraymap, RegCal *regcal, RegSet *regset,
89  RegRawData *raw, RegCalData *cal);
90 
91 /*
92  * Reset all calibration multipliers to 1.0 and zero all calibration
93  * offsets.
94  */
95 int reset_RegCal(RegCal *regcal);
96 
97 /*
98  * The following functions can be used to retrieve calibrated data
99  * from a RegCalData array. The reg argument should be a register
100  * specification that convers the register index range index..index+n-1.
101  */
102 int get_cal_float(RegCalData *cal, ArrRegMapReg *reg, unsigned index, unsigned n,
103  float *data);
104 int get_cal_double(RegCalData *cal, ArrRegMapReg *reg, unsigned index,
105  unsigned n, double *data);
106 int get_cal_uint(RegCalData *cal, ArrRegMapReg *reg, unsigned index,
107  unsigned n, unsigned *data);
108 int get_cal_int(RegCalData *cal, ArrRegMapReg *reg, unsigned index,
109  unsigned n, int *data);
110 int get_cal_ulong(RegCalData *cal, ArrRegMapReg *reg, unsigned index,
111  unsigned n, unsigned long *data);
112 int get_cal_long(RegCalData *cal, ArrRegMapReg *reg, unsigned index,
113  unsigned n, long *data);
114 int get_cal_string(RegCalData *cal, ArrRegMapReg *reg, unsigned nc, char *string);
115 
116 #endif