LAL  7.1.7.1-2d066e5
Calibration.h
Go to the documentation of this file.
1 /*
2 * Copyright (C) 2007 Bernd Machenschalk, Jolien Creighton, Patrick Brady, Stephen Fairhurst, Xavier Siemens
3 *
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License as published by
6 * the Free Software Foundation; either version 2 of the License, or
7 * (at your option) any later version.
8 *
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
13 *
14 * You should have received a copy of the GNU General Public License
15 * along with with program; see the file COPYING. If not, write to the
16 * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
17 * MA 02110-1301 USA
18 */
19 
20 #ifndef _CALIBRATION_H
21 #define _CALIBRATION_H
22 
23 #include <lal/LALDatatypes.h>
24 #include <lal/BandPassTimeSeries.h>
25 
26 #if defined(__cplusplus)
27 extern "C" {
28 #elif 0
29 } /* so that editors will match preceding brace */
30 #endif
31 
32 /**
33  * \defgroup Calibration_h Header Calibration.h
34  * \ingroup lal_tools
35  * \author P. R. Brady, J. D. E. Creighton
36  * \brief Calibration API
37  *
38  * ### Synopsis ###
39  *
40  * \code
41  * #include <lal/Calibration.h>
42  * \endcode
43  *
44  */
45 /** @{ */
46 
47 /**\name Error Codes */
48 /** @{ */
49 #define CALIBRATIONH_ENULL 001 /**< Null pointer */
50 #define CALIBRATIONH_ESIZE 002 /**< Invalid size */
51 #define CALIBRATIONH_ESZMM 004 /**< Size mismatch */
52 #define CALIBRATIONH_EZERO 010 /**< Zero factor */
53 #define CALIBRATIONH_ETIME 020 /**< Time out of range */
54 #define CALIBRATIONH_EUNIT 040 /**< Incompatible units */
55 /** @} */
56 
57 /** \cond DONT_DOXYGEN */
58 #define CALIBRATIONH_MSGENULL "Null pointer"
59 #define CALIBRATIONH_MSGESIZE "Invalid size"
60 #define CALIBRATIONH_MSGESZMM "Size mismatch"
61 #define CALIBRATIONH_MSGEZERO "Zero factor"
62 #define CALIBRATIONH_MSGETIME "Time out of range"
63 #define CALIBRATIONH_MSGEUNIT "Incompatible units"
64 /** \endcond */
65 
66 /** UNDOCUMENTED */
67 typedef enum
68 tagCalibrationType
69 {
75 }
77 
78 
79 /** UNDOCUMENTED */
80 typedef struct
81 tagCalFactors
82 {
89 }
91 
92 
93 /** UNDOCUMENTED */
94 typedef struct
95 tagUpdateFactorsParams
96 {
104 }
106 
107 
108 /** UNDOCUMENTED */
109 typedef struct
110 tagCalibrationRecord
111 {
115  CHAR reference[LALNameLength];
125 }
127 
128 /**
129  * The type CalibrationFunctions contains two calibration functions,
130  * the sensing function \f$C(f)\f$ and the response function \f$R(f)\f$. While the
131  * response function is the function that is most often wanted, the sensing
132  * function is needed in updating calibration from one epoch to another.
133  */
134 typedef struct
135 tagCalibrationFunctions
136 {
139 }
141 
142 /**
143  * The type \c CalibrationUpdateParams contains two time series
144  * representing an overall gain factor for the open-loop gain function \f$H(f)\f$
145  * and the sensing function \f$C(f)\f$. These transfer functions are known to
146  * change (by an overall factor) with time, and these two factors can be
147  * tracked using the injected calibration lines. The factors are stored
148  * in this structure as (very-slowly varying) time series, and are to be
149  * used in updating the calibration functions described previously.
150  * (The response function can be computed from the open-loop gain and the
151  * sensing function. It is simply \f$R(f)=[1+H(f)]/C(f)\f$.) In addition, this
152  * structure contains the present epoch and the duration of the data to be
153  * calibrated to identify the particular set of
154  * factors (from those recorded in the time series) to use.
155  */
156 typedef struct
157 tagCalibrationUpdateParams
158 {
166 }
168 
169 /** UNDOCUMENTED */
170 typedef
171 struct tagStrainOut {
172  REAL8TimeSeries h; /**< timeseries containing h(t) */
173  REAL8TimeSeries hC; /**< timeseries containing the control signal */
174  REAL8TimeSeries hR; /**< timeseries containing the residual signal */
175  COMPLEX16TimeSeries alpha; /**< alpha time series */
176  COMPLEX16TimeSeries beta; /**< beta time series */
177  COMPLEX16TimeSeries alphabeta;/**< alpha time series */
178  INT2TimeSeries science_mode; /**< flag = 1 for science mode, 0 otherwise */
179 } StrainOut;
180 
181 /** UNDOCUMENTED */
182 typedef
183 struct tagStrainIn {
184  REAL4TimeSeries AS_Q ; /**< timeseries containing ASQ */
185  REAL4TimeSeries DARM_ERR;/**< timeseries containing DARM_ERR */
186  REAL4TimeSeries DARM ; /**< timeseries containing DARM_CTRL */
187  REAL4TimeSeries EXC ; /**< timeseries containing the excitation */
188  REAL4TimeSeries StateVector; /**< timeseries containing the State Vector (IFO-SV_STATE_VECTOR) */
189  REAL4TimeSeries LAX; /**< timeseries containing the Light-in-X-arm (LSC-LA_PTRX_NORM) */
190  REAL4TimeSeries LAY; /**< timeseries containing the Light-in-Y-arm (LSC-LA_PTRY_NORM) */
191  COMPLEX16 Do; /**< digital filter at cal line frequency */
192  COMPLEX16 Go; /**< OLG at cal line frequency */
193  COMPLEX16 Wo; /**< Whitening filter at cal line frequency */
194  REAL8 f; /**< calibration line frequency */
195  REAL4 To; /**< factors integration time */
196  char filter_vc_info[1024]; /**< version control information in the filters file */
197  char filter_chksum[64]; /**< checksum of the contents of the filters file */
198  REAL8IIRFilter *Cinv; /**< Filters for inverse of sensing function */
199  INT4 CinvUSF; /**< Upsampling factor for sensing function */
200  INT4 CinvDelay; /**< Overall inverse sensing function delay */
201  REAL8IIRFilter *A; /**< Filters for analog actuation function */
202  REAL8IIRFilter *D; /**< Filters for analog actuation function */
203  REAL8IIRFilter *AW; /**< Filters for analog actuation function */
204  REAL8 gamma_fudgefactor; /**< UNDOCUMENTED */
205  INT4 delta; /**< UNDOCUMENTED */
206  INT4 usefactors; /**< UNDOCUMENTED */
207  INT4 wings; /**< size of wings in seconds */
208  INT4 fftconv; /**< UNDOCUMENTED */
209  INT4 outalphas;/**< UNDOCUMENTED */
210  INT4 darmctrl;/**< UNDOCUMENTED */
211  /* Stuff needed to run old IIR code */
212  REAL8IIRFilter *AA; /**< Filters for analog actuation function */
213  INT4 AADelay; /**< Overall analog actuation function delay */
214  REAL8IIRFilter *AX; /**< Digital filters for x arm actuation function */
215  REAL8IIRFilter *AY; /**< Digital filters for y arm actuation function */
216  INT4 NCinv; /**< Numbers of filters of each type */
217  INT4 ND;/**< UNDOCUMENTED */
218  INT4 NAA;/**< UNDOCUMENTED */
219  INT4 NAX;/**< UNDOCUMENTED */
220  INT4 NAY;/**< UNDOCUMENTED */
221 } StrainIn;
222 
223 /** UNDOCUMENTED */
224 typedef
225 struct tagMyIIRFilter {
228  REAL8 a[20];
229  REAL8 b[20];
230  REAL8 yhist[20];
231  REAL8 xhist[20];
232 } MyIIRFilter;
233 
234 /** @} */
235 
236 /* ----- Prototypes ----- */
237 
239 
240 
241 void
243  LALStatus *status,
244  CalibrationFunctions *output,
245  CalibrationFunctions *input,
247  );
248 
249 void
251  LALStatus *status,
252  COMPLEX8FrequencySeries *output,
254  );
255 
256 INT4
258  COMPLEX8FrequencySeries *output,
260  );
261 
263  LALStatus *status,
264  CalFactors *output,
265  UpdateFactorsParams *input
266  );
267 
268 void LALComputeStrain(
269  LALStatus *status,
270  StrainOut *output,
271  StrainIn *input
272  );
273 
275  LALStatus *status,
276  StrainOut *output,
277  StrainIn *input
278  );
279 
280 void LALGetFactors(
281  LALStatus *status,
282  StrainOut *output,
283  StrainIn *input
284  );
285 
287  REAL8IIRFilter *G,
288  int USF);
289 
291  REAL8IIRFilter *G);
292 
294  REAL8IIRFilter *G);
295 
296 int XLALFIRFilter(REAL8TimeSeries *tseries,
297  REAL8IIRFilter *FIR);
298 
300  REAL8TimeSeries *tseries,
301  REAL8IIRFilter *FIR);
302 
303 void LALFreeFilter(LALStatus *status, REAL8IIRFilter *F2, int ORDER);
304 void LALCopyFilter(LALStatus *status, REAL8IIRFilter **F2, REAL8IIRFilter *F1, int ORDER);
305 
307 int XLALUpsample(REAL8TimeSeries *uphR, REAL8TimeSeries *hR, int up_factor);
308 int XLALUpsampleLinear(REAL8TimeSeries *uphR, REAL8TimeSeries *hR, int up_factor);
309 
310 #if 0
311 { /* so that editors will match succeeding brace */
312 #elif defined(__cplusplus)
313 }
314 #endif
315 
316 #endif /* _CALIBRATION_H */
INT4 wings
size of wings in seconds
Definition: Calibration.h:207
COMPLEX8FrequencySeries * sensingFunction
Definition: Calibration.h:138
This structure stores units in the mksA system (plus Kelvin, Strain, and ADC Count).
Definition: LALDatatypes.h:498
void LALResponseConvert(LALStatus *status, COMPLEX8FrequencySeries *output, COMPLEX8FrequencySeries *input)
UNDOCUMENTED.
REAL8TimeSeries hR
timeseries containing the residual signal
Definition: Calibration.h:174
INT4 darmctrl
UNDOCUMENTED.
Definition: Calibration.h:210
REAL8 f
calibration line frequency
Definition: Calibration.h:194
This structure stores the direct and recursive REAL8 filter coefficients, as well as the history of t...
Definition: IIRFilter.h:168
INT4 CinvDelay
Overall inverse sensing function delay.
Definition: Calibration.h:200
UNDOCUMENTED.
Definition: Calibration.h:80
COMPLEX8TimeSeries * openLoopFactor
Definition: Calibration.h:164
REAL4TimeSeries DARM
timeseries containing DARM_CTRL
Definition: Calibration.h:186
REAL4TimeSeries * asQ
Definition: Calibration.h:102
COMPLEX16 alpha
Definition: Calibration.h:83
REAL4TimeSeries LAY
timeseries containing the Light-in-Y-arm (LSC-LA_PTRY_NORM)
Definition: Calibration.h:190
UNDOCUMENTED.
Definition: Calibration.h:109
REAL8 gamma_fudgefactor
UNDOCUMENTED.
Definition: Calibration.h:204
REAL8IIRFilter * D
Filters for analog actuation function.
Definition: Calibration.h:202
Time series of COMPLEX16 data, see DATATYPE-TimeSeries types for more details.
Definition: LALDatatypes.h:600
LIGOTimeGPS epoch
Definition: Calibration.h:113
Epoch relative to GPS epoch, see LIGOTimeGPS type for more details.
Definition: LALDatatypes.h:458
void LALGetFactors(LALStatus *status, StrainOut *output, StrainIn *input)
char CHAR
One-byte signed integer, see Headers LAL(Atomic)Datatypes.h for more details.
COMPLEX8TimeSeries * sensingFactor
Definition: Calibration.h:165
float complex COMPLEX8
Single-precision floating-point complex number (8 bytes total)
INT4 CinvUSF
Upsampling factor for sensing function.
Definition: Calibration.h:199
COMPLEX8FrequencySeries * transfer
Definition: Calibration.h:121
REAL8IIRFilter * A
Filters for analog actuation function.
Definition: Calibration.h:201
INT4 NAX
UNDOCUMENTED.
Definition: Calibration.h:219
REAL4TimeSeries LAX
timeseries containing the Light-in-X-arm (LSC-LA_PTRX_NORM)
Definition: Calibration.h:189
INT4 ND
UNDOCUMENTED.
Definition: Calibration.h:217
REAL4TimeSeries * exc
Definition: Calibration.h:103
COMPLEX16 Go
OLG at cal line frequency.
Definition: Calibration.h:192
static const INT4 a
Definition: Random.c:79
float REAL4
Single precision real floating-point number (4 bytes).
void LALUpdateCalibration(LALStatus *status, CalibrationFunctions *output, CalibrationFunctions *input, CalibrationUpdateParams *params)
UNDOCUMENTED.
COMPLEX16TimeSeries alphabeta
alpha time series
Definition: Calibration.h:177
COMPLEX16 beta
Definition: Calibration.h:85
REAL4TimeSeries StateVector
timeseries containing the State Vector (IFO-SV_STATE_VECTOR)
Definition: Calibration.h:188
COMPLEX16 exc
Definition: Calibration.h:86
REAL8Vector * zeros
Definition: Calibration.h:122
REAL8TimeSeries h
timeseries containing h(t)
Definition: Calibration.h:172
int XLALDivideTimeSeries(REAL8TimeSeries *hR, REAL8TimeSeries *ALPHAS)
UNDOCUMENTED.
Definition: Calibration.h:182
INT2TimeSeries science_mode
flag = 1 for science mode, 0 otherwise
Definition: Calibration.h:178
COMPLEX16 Do
digital filter at cal line frequency
Definition: Calibration.h:191
REAL4TimeSeries DARM_ERR
timeseries containing DARM_ERR
Definition: Calibration.h:185
REAL8IIRFilter * AY
Digital filters for y arm actuation function.
Definition: Calibration.h:215
INT4 NAA
UNDOCUMENTED.
Definition: Calibration.h:218
COMPLEX16TimeSeries alpha
alpha time series
Definition: Calibration.h:175
UNDOCUMENTED.
Definition: Calibration.h:170
REAL8TimeSeries hC
timeseries containing the control signal
Definition: Calibration.h:173
int XLALFIRFilter(REAL8TimeSeries *tseries, REAL8IIRFilter *FIR)
INT4 AADelay
Overall analog actuation function delay.
Definition: Calibration.h:213
See DATATYPE-FrequencySeries types for documentation.
Definition: LALDatatypes.h:899
void LALMakeFIRLPALPHAS(LALStatus *status, REAL8IIRFilter *G)
double REAL8
Double precision real floating-point number (8 bytes).
Vector of type REAL8, see DATATYPE-Vector types for more details.
Definition: LALDatatypes.h:154
INT4 delta
UNDOCUMENTED.
Definition: Calibration.h:205
void LALCopyFilter(LALStatus *status, REAL8IIRFilter **F2, REAL8IIRFilter *F1, int ORDER)
INT4 NCinv
Numbers of filters of each type.
Definition: Calibration.h:216
REAL4TimeSeries * darmCtrl
Definition: Calibration.h:101
CalibrationType
UNDOCUMENTED.
Definition: Calibration.h:67
REAL8IIRFilter * Cinv
Filters for inverse of sensing function.
Definition: Calibration.h:198
LAL status structure, see The LALStatus structure for more details.
Definition: LALDatatypes.h:947
INT4 XLALResponseConvert(COMPLEX8FrequencySeries *output, COMPLEX8FrequencySeries *input)
UNDOCUMENTED.
COMPLEX16TimeSeries beta
beta time series
Definition: Calibration.h:176
REAL4TimeSeries AS_Q
timeseries containing ASQ
Definition: Calibration.h:184
REAL8Vector * poles
Definition: Calibration.h:123
uint32_t UINT4
Four-byte unsigned integer.
void LALComputeStrain(LALStatus *status, StrainOut *output, StrainIn *input)
Definition: ComputeStrain.c:63
COMPLEX16 asq
Definition: Calibration.h:87
void LALFreeFilter(LALStatus *status, REAL8IIRFilter *F2, int ORDER)
double complex COMPLEX16
Double-precision floating-point complex number (16 bytes total)
void LALComputeCalibrationFactors(LALStatus *status, CalFactors *output, UpdateFactorsParams *input)
REAL4 To
factors integration time
Definition: Calibration.h:195
INT4 NAY
UNDOCUMENTED.
Definition: Calibration.h:220
INT4 outalphas
UNDOCUMENTED.
Definition: Calibration.h:209
COMPLEX16 openloop
Definition: Calibration.h:98
INT4 usefactors
UNDOCUMENTED.
Definition: Calibration.h:206
Time series of REAL4 data, see DATATYPE-TimeSeries types for more details.
Definition: LALDatatypes.h:570
Time series of COMPLEX8 data, see DATATYPE-TimeSeries types for more details.
Definition: LALDatatypes.h:590
void LALMakeFIRLP(LALStatus *status, REAL8IIRFilter *G, int USF)
REAL8IIRFilter * AA
Filters for analog actuation function.
Definition: Calibration.h:212
int XLALUpsample(REAL8TimeSeries *uphR, REAL8TimeSeries *hR, int up_factor)
UNDOCUMENTED.
Definition: Calibration.h:224
int32_t INT4
Four-byte signed integer.
void LALComputeTransfer(LALStatus *status, CalibrationRecord *calrec)
UNDOCUMENTED.
COMPLEX16 darm
Definition: Calibration.h:88
COMPLEX16 Wo
Whitening filter at cal line frequency.
Definition: Calibration.h:193
REAL8IIRFilter * AW
Filters for analog actuation function.
Definition: Calibration.h:203
The type CalibrationUpdateParams contains two time series representing an overall gain factor for the...
Definition: Calibration.h:156
void LALMakeFIRHP(LALStatus *status, REAL8IIRFilter *G)
COMPLEX8FrequencySeries * responseFunction
Definition: Calibration.h:137
Time series of INT2 data, see DATATYPE-TimeSeries types for more details.
Definition: LALDatatypes.h:511
COMPLEX16 alphabeta
Definition: Calibration.h:84
const char *const name
type name
Definition: UserInput.c:193
Time series of REAL8 data, see DATATYPE-TimeSeries types for more details.
Definition: LALDatatypes.h:580
UNDOCUMENTED.
Definition: Calibration.h:94
int XLALUpsampleLinear(REAL8TimeSeries *uphR, REAL8TimeSeries *hR, int up_factor)
The type CalibrationFunctions contains two calibration functions, the sensing function and the respo...
Definition: Calibration.h:134
REAL4TimeSeries EXC
timeseries containing the excitation
Definition: Calibration.h:187
REAL8IIRFilter * AX
Digital filters for x arm actuation function.
Definition: Calibration.h:214
void LALComputeStrainDMT(LALStatus *status, StrainOut *output, StrainIn *input)
void LALFFTFIRFilter(LALStatus *status, REAL8TimeSeries *tseries, REAL8IIRFilter *FIR)
INT4 fftconv
UNDOCUMENTED.
Definition: Calibration.h:208