LAL  6.21.0.1-1696c80
DetResponse.h
Go to the documentation of this file.
1 /*
2 * Copyright (C) 2007 David Chin, Jolien Creighton, Kipp Cannon, Teviet Creighton
3 * Copyright (C) 2012 Matthew Pitkin
4 *
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
9 *
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
14 *
15 * You should have received a copy of the GNU General Public License
16 * along with with program; see the file COPYING. If not, write to the
17 * Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
18 * MA 02111-1307 USA
19 */
20 
21 #ifndef _DETRESPONSE_H
22 #define _DETRESPONSE_H
23 
24 #include <lal/LALStdlib.h>
25 #include <lal/LALStdio.h>
26 #include <lal/LALConstants.h>
27 #include <lal/DetectorSite.h>
28 #include <lal/SkyCoordinates.h>
29 #include <lal/Date.h>
30 
31 #ifdef __cplusplus
32 extern "C"
33 {
34 #endif
35 
36 /**
37  * \defgroup DetResponse_h Header DetResponse.h
38  * \ingroup lal_tools
39  * \author David Chin <dwchin@umich.edu>, Kipp Cannon <kipp@gravity.phys.uwm.edu>
40  *
41  * \brief Provides routines to compute gravitational wave detector response to
42  * polarized planar gravitational wave originating from a given source,
43  * detected at a given time.
44  *
45  * ### Synopsis ###
46  *
47  * \code
48  * #include <lal/DetResponse.h>
49  * \endcode
50  *
51  * ### Description ###
52  *
53  * These routines compute the antenna beam pattern for all supported detector
54  * types. <tt>XLALComputeDetAMResponse()</tt> computes the response at one
55  * instance in time, and <tt>XLALComputeDetAMResponseSeries()</tt> computes a
56  * vector of response for some length of time.
57  *
58  * ### Algorithm ###
59  *
60  * This code is a translation of the algorithm in the Maple worksheet by
61  * Anderson, <em>et al.</em> \cite ABCCRW_2001 . We compute the \f$h\f$-tensors for
62  * \f$+\f$- and \f$\times\f$-polarized in the Earth-fixed frame, and then contract
63  * them (take the scalar product) with the detector response tensors as
64  * described in the \ref LALDetectors_h section of the \c tools package.
65  *
66  * \ref LALDetectors_h provides predefined
67  * \c LALDetector structures representing most current detectors,
68  * including LIGO (Hanford and Livingston), and GEO.
69  *
70  * ### Notes ###
71  *
72  * For examples of usage, please see the test programs in the \c test directory.
73  *
74  */
75 /** @{ */
76 
77 /** \name Error Codes */
78 /** @{ */
79 #define DETRESPONSEH_ENULLINPUT 1 /**< Input is NULL */
80 #define DETRESPONSEH_ENULLOUTPUT 2 /**< Output is NULL */
81 #define DETRESPONSEH_ESRCNOTEQUATORIAL 3 /**< Source coordinates not in Equatorial system */
82 /** @} */
83 
84 /** \cond DONT_DOXYGEN */
85 #define DETRESPONSEH_MSGENULLINPUT "Input is NULL"
86 #define DETRESPONSEH_MSGENULLOUTPUT "Output is NULL"
87 #define DETRESPONSEH_MSGESRCNOTEQUATORIAL "Source coordinates not in Equatorial system"
88 /** \endcond */
89 
90 
91 /**
92  * This structure contains gravitational wave source position (in Equatorial
93  * coördinates), and orientation angle.
94  * The orientation is measured counter-clockwise with respect to the "line of ascending nodes",
95  * i.e. counter-clockwise with respect to a line perpendicular to the
96  * source's meridian and extending westwards. For a source in the Northern
97  * celestial hemisphere, and an observer in the Northern hemisphere standing
98  * such that they are facing South, this angle is measured counter-clockwise
99  * from a 3 o'clock position (pointing West) at the source. The polarization
100  * convention is chosen such that if the source orientation were zero, the
101  * source would be a pure \f$+\f$-polarized source.
102  */
103 typedef struct
104 tagLALSource
105 {
106  CHAR name[LALNameLength]; /**< name of source, eg catalog number */
107  SkyPosition equatorialCoords; /**< equatorial coordinates of source, in decimal RADIANS */
108  REAL8 orientation; /**< Orientation angle (\f$\psi\f$) of source:
109  * counter-clockwise angle \f$x\f$-axis makes with a line perpendicular to
110  * meridian of source in Westward direction (i.e. North of West),
111  * in decimal radians.
112  */
113 }
114 LALSource;
115 
116 /**
117  * This structure aggregates a pointer to a \c LALDetector and a
118  * \c LALSource. Its sole function is to allow the user to pass
119  * detector and source parameters to the functions
120  * LALComputeDetAMResponse() and
121  * LALComputeDetAMResponseSeries().
122  */
123 #ifdef SWIG /* SWIG interface directives */
124 SWIGLAL(IMMUTABLE_MEMBERS(tagLALDetAndSource, pDetector));
125 #endif /* SWIG */
126 typedef struct
127 tagLALDetAndSource
128 {
129  const LALDetector *pDetector;/**< Pointer to ::LALDetector object containing information about the detector */
130  LALSource *pSource; /**< Pointer to ::LALSource object containing information about the source */
131 }
133 
134 /**
135  * This structure encapsulates the detector AM (beam pattern) coefficients for
136  * one source at one instance in time.
137  */
138 typedef struct
139 tagLALDetAMResponse
140 {
141  REAL4 plus; /**< Detector response to \f$+\f$-polarized gravitational radiation */
142  REAL4 cross; /**< Detector response to \f$\times\f$-polarized gravitational radiation */
143  REAL4 scalar; /**< Detector response to scalar gravitational radiation (NB: ignored at present -- scalar response computation not yet implemented) */
144 }
146 
147 /**
148  * This structure aggregates together three ::REAL4TimeSeries objects containing
149  * time series of detector AM response.
150  */
151 typedef struct
152 tagLALDetAMResponseSeries
153 {
154  REAL4TimeSeries *pPlus; /**< timeseries of detector response to \f$+\f$-polarized gravitational radiation */
155  REAL4TimeSeries *pCross; /**< timeseries of detector response to \f$\times\f$-polarized gravitational radiation */
156  REAL4TimeSeries *pScalar; /**< timeseries of detector response to scalar gravitational radiation (NB: not yet implemented.) */
157 }
159 
160 
161 /**
162  * This structure encapsulates time and sampling information for computing a
163  * ::LALDetAMResponseSeries. Its fields correspond to some fields of the
164  * TimeSeries structures for easy conversion.
165  */
166 typedef struct
167 tagLALTimeIntervalAndNSample
168 {
169  LIGOTimeGPS epoch; /**< The start time \f$t_0\f$ of the time series */
170  REAL8 deltaT; /**< The sampling interval \f$\Delta t\f$, in seconds */
171  UINT4 nSample; /**< The total number of samples to be computed */
172 }
174 
175 /*
176  * Function prototypes
177  */
178 
179 void
181  LALDetAMResponse *pResponse,
182  const LALDetAndSource *pDetAndSrc,
183  const LIGOTimeGPS *gps);
184 
186  double *fplus,
187  double *fcross,
188  const REAL4 D[3][3],
189  const double ra,
190  const double dec,
191  const double psi,
192  const double gmst
193 );
194 
195 
197  double *fplus,
198  double *fcross,
199  double *fb,
200  double *fl,
201  double *fx,
202  double *fy,
203  const REAL4 D[3][3],
204  const double ra,
205  const double dec,
206  const double psi,
207  const double gmst
208 );
209 
210 
212  double beta,
213  double mu
214 );
215 
216 
218  double *armlen,
219  double *xcos,
220  double *ycos,
221  double *fxplus,
222  double *fyplus,
223  double *fxcross,
224  double *fycross,
225  const LALDetector *detector,
226  double ra,
227  double dec,
228  double psi,
229  double gmst
230 );
231 
232 /*
233  * Gives a time series of the detector's response to plus and cross
234  * polarization
235  */
236 void
238  LALDetAMResponseSeries *pResponseSeries,
239  const LALDetAndSource *pDetAndSource,
240  const LALTimeIntervalAndNSample *pTimeInfo);
241 
243  REAL4TimeSeries **fplus,
244  REAL4TimeSeries **fcross,
245  const REAL4 D[3][3],
246  const double ra,
247  const double dec,
248  const double psi,
249  const LIGOTimeGPS *start,
250  const double deltaT,
251  const int n
252 );
253 
255  REAL4TimeSeries **fplus,
256  REAL4TimeSeries **fcross,
257  REAL4TimeSeries **fb,
258  REAL4TimeSeries **fl,
259  REAL4TimeSeries **fx,
260  REAL4TimeSeries **fy,
261  const REAL4 D[3][3],
262  const double ra,
263  const double dec,
264  const double psi,
265  const LIGOTimeGPS *start,
266  const double deltaT,
267  const int n
268 );
269 
270 /** @} */
271 
272 #ifdef __cplusplus
273 }
274 #endif
275 
276 #endif /* !defined _DETRESPONSE_H */
void XLALComputeDetAMResponseParts(double *armlen, double *xcos, double *ycos, double *fxplus, double *fyplus, double *fxcross, double *fycross, const LALDetector *detector, double ra, double dec, double psi, double gmst)
Definition: DetResponse.c:234
LALSource * pSource
Pointer to LALSource object containing information about the source.
Definition: DetResponse.h:130
SkyPosition equatorialCoords
equatorial coordinates of source, in decimal RADIANS
Definition: DetResponse.h:107
void XLALComputeDetAMResponseExtraModes(double *fplus, double *fcross, double *fb, double *fl, double *fx, double *fy, const REAL4 D[3][3], const double ra, const double dec, const double psi, const double gmst)
An implementation of the detector response for all six tensor, vector and scalar polarisation modes o...
Definition: DetResponse.c:112
REAL4 scalar
Detector response to scalar gravitational radiation (NB: ignored at present – scalar response comput...
Definition: DetResponse.h:143
COMPLEX16 XLALComputeDetArmTransferFunction(double beta, double mu)
Definition: DetResponse.c:202
Epoch relative to GPS epoch, see LIGOTimeGPS type for more details.
Definition: LALDatatypes.h:458
char CHAR
One-byte signed integer, see Headers LAL(Atomic)Datatypes.h for more details.
REAL4TimeSeries * pPlus
timeseries of detector response to -polarized gravitational radiation
Definition: DetResponse.h:154
Detector structure.
Definition: LALDetectors.h:265
int XLALComputeDetAMResponseSeries(REAL4TimeSeries **fplus, REAL4TimeSeries **fcross, const REAL4 D[3][3], const double ra, const double dec, const double psi, const LIGOTimeGPS *start, const double deltaT, const int n)
Computes REAL4TimeSeries containing time series of response amplitudes.
Definition: DetResponse.c:432
This structure aggregates a pointer to a LALDetector and a LALSource.
Definition: DetResponse.h:126
int XLALComputeDetAMResponseExtraModesSeries(REAL4TimeSeries **fplus, REAL4TimeSeries **fcross, REAL4TimeSeries **fb, REAL4TimeSeries **fl, REAL4TimeSeries **fx, REAL4TimeSeries **fy, const REAL4 D[3][3], const double ra, const double dec, const double psi, const LIGOTimeGPS *start, const double deltaT, const int n)
Computes REAL4TimeSeries containing time series of the full general metric theory of gravity response...
Definition: DetResponse.c:470
This structure stores the two spherical coordinates of a sky position; ie a generic latitude and long...
float REAL4
Single precision real floating-point number (4 bytes).
void XLALComputeDetAMResponse(double *fplus, double *fcross, const REAL4 D[3][3], const double ra, const double dec, const double psi, const double gmst)
An implementation of the detector response formulae in Anderson et al PRD 63 042003 (2001) ...
Definition: DetResponse.c:44
const LALDetector * pDetector
Pointer to LALDetector object containing information about the detector.
Definition: DetResponse.h:129
void LALComputeDetAMResponse(LALStatus *status, LALDetAMResponse *pResponse, const LALDetAndSource *pDetAndSrc, const LIGOTimeGPS *gps)
Definition: DetResponse.c:401
REAL8 orientation
Orientation angle ( ) of source: counter-clockwise angle -axis makes with a line perpendicular to mer...
Definition: DetResponse.h:108
void LALComputeDetAMResponseSeries(LALStatus *status, LALDetAMResponseSeries *pResponseSeries, const LALDetAndSource *pDetAndSource, const LALTimeIntervalAndNSample *pTimeInfo)
Computes REAL4TimeSeries containing time series of response amplitudes.
Definition: DetResponse.c:526
UINT4 nSample
The total number of samples to be computed.
Definition: DetResponse.h:171
double REAL8
Double precision real floating-point number (8 bytes).
LAL status structure, see The LALStatus structure for more details.
Definition: LALDatatypes.h:947
REAL4TimeSeries * pCross
timeseries of detector response to -polarized gravitational radiation
Definition: DetResponse.h:155
LIGOTimeGPS epoch
The start time of the time series.
Definition: DetResponse.h:169
This structure encapsulates time and sampling information for computing a LALDetAMResponseSeries.
Definition: DetResponse.h:166
This structure encapsulates the detector AM (beam pattern) coefficients for one source at one instanc...
Definition: DetResponse.h:138
uint32_t UINT4
Four-byte unsigned integer.
REAL4TimeSeries * pScalar
timeseries of detector response to scalar gravitational radiation (NB: not yet implemented.)
Definition: DetResponse.h:156
double complex COMPLEX16
Double-precision floating-point complex number (16 bytes total)
This structure aggregates together three REAL4TimeSeries objects containing time series of detector A...
Definition: DetResponse.h:151
Time series of REAL4 data, see DATATYPE-TimeSeries types for more details.
Definition: LALDatatypes.h:570
This structure contains gravitational wave source position (in Equatorial coördinates), and orientation angle.
Definition: DetResponse.h:103
static double psi(double theta, double xi)
Definition: XLALMarcumQ.c:273
REAL4 plus
Detector response to -polarized gravitational radiation.
Definition: DetResponse.h:141
const char *const name
type name
Definition: UserInput.c:193
REAL8 deltaT
The sampling interval , in seconds.
Definition: DetResponse.h:170
REAL4 cross
Detector response to -polarized gravitational radiation.
Definition: DetResponse.h:142