Loading [MathJax]/extensions/TeX/AMSsymbols.js
LAL 7.7.0.1-3a66518
All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
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., 51 Franklin Street, Fifth Floor, Boston,
18* MA 02110-1301 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
32extern "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 */
103typedef struct
104tagLALSource
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}
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 */
124SWIGLAL(IMMUTABLE_MEMBERS(tagLALDetAndSource, pDetector));
125#endif /* SWIG */
126typedef struct
127tagLALDetAndSource
128{
129 const LALDetector *pDetector;/**< Pointer to \c LALDetector object containing information about the detector */
130 LALSource *pSource; /**< Pointer to \c 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 */
138typedef struct
139tagLALDetAMResponse
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 \c REAL4TimeSeries objects containing
149 * time series of detector AM response.
150 */
151typedef struct
152tagLALDetAMResponseSeries
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 * \c LALDetAMResponseSeries. Its fields correspond to some fields of the
164 * TimeSeries structures for easy conversion.
165 */
166typedef struct
167tagLALTimeIntervalAndNSample
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
179void
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 */
236void
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 */
const char *const name
type name
Definition: UserInput.c:193
static double psi(double theta, double xi)
Definition: XLALMarcumQ.c:273
void LALComputeDetAMResponse(LALStatus *status, LALDetAMResponse *pResponse, const LALDetAndSource *pDetAndSrc, const LIGOTimeGPS *gps)
Definition: DetResponse.c:401
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
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
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
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
COMPLEX16 XLALComputeDetArmTransferFunction(double beta, double mu)
Definition: DetResponse.c:202
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
void LALComputeDetAMResponseSeries(LALStatus *status, LALDetAMResponseSeries *pResponseSeries, const LALDetAndSource *pDetAndSource, const LALTimeIntervalAndNSample *pTimeInfo)
Computes REAL4TimeSeries containing time series of response amplitudes.
Definition: DetResponse.c:526
double complex COMPLEX16
Double-precision floating-point complex number (16 bytes total)
double REAL8
Double precision real floating-point number (8 bytes).
char CHAR
One-byte signed integer, see Headers LAL(Atomic)Datatypes.h for more details.
uint32_t UINT4
Four-byte unsigned integer.
float REAL4
Single precision real floating-point number (4 bytes).
@ LALNameLength
Definition: LALDatatypes.h:508
This structure encapsulates the detector AM (beam pattern) coefficients for one source at one instanc...
Definition: DetResponse.h:140
REAL4 plus
Detector response to -polarized gravitational radiation
Definition: DetResponse.h:141
REAL4 scalar
Detector response to scalar gravitational radiation (NB: ignored at present – scalar response computa...
Definition: DetResponse.h:143
REAL4 cross
Detector response to -polarized gravitational radiation.
Definition: DetResponse.h:142
This structure aggregates together three REAL4TimeSeries objects containing time series of detector A...
Definition: DetResponse.h:153
REAL4TimeSeries * pCross
timeseries of detector response to -polarized gravitational radiation
Definition: DetResponse.h:155
REAL4TimeSeries * pPlus
timeseries of detector response to -polarized gravitational radiation
Definition: DetResponse.h:154
REAL4TimeSeries * pScalar
timeseries of detector response to scalar gravitational radiation (NB: not yet implemented....
Definition: DetResponse.h:156
This structure aggregates a pointer to a LALDetector and a LALSource.
Definition: DetResponse.h:128
LALSource * pSource
Pointer to LALSource object containing information about the source.
Definition: DetResponse.h:130
const LALDetector * pDetector
Pointer to LALDetector object containing information about the detector.
Definition: DetResponse.h:129
Detector structure.
Definition: LALDetectors.h:278
This structure contains gravitational wave source position (in Equatorial coördinates),...
Definition: DetResponse.h:105
SkyPosition equatorialCoords
equatorial coordinates of source, in decimal RADIANS
Definition: DetResponse.h:107
REAL8 orientation
Orientation angle ( ) of source: counter-clockwise angle -axis makes with a line perpendicular to mer...
Definition: DetResponse.h:108
LAL status structure, see The LALStatus structure for more details.
Definition: LALDatatypes.h:947
This structure encapsulates time and sampling information for computing a LALDetAMResponseSeries.
Definition: DetResponse.h:168
LIGOTimeGPS epoch
The start time of the time series.
Definition: DetResponse.h:169
UINT4 nSample
The total number of samples to be computed.
Definition: DetResponse.h:171
REAL8 deltaT
The sampling interval , in seconds.
Definition: DetResponse.h:170
Epoch relative to GPS epoch, see LIGOTimeGPS type for more details.
Definition: LALDatatypes.h:458
Time series of REAL4 data, see DATATYPE-TimeSeries types for more details.
Definition: LALDatatypes.h:570
This structure stores the two spherical coordinates of a sky position; ie a generic latitude and long...