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
SimulateCoherentGW.h
Go to the documentation of this file.
1/*
2 * Copyright (C) 2007 Jolien Creighton, Reinhard Prix, Teviet Creighton, John Whelan
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 _SIMULATECOHERENTGW_H
21#define _SIMULATECOHERENTGW_H
22
23#include <lal/LALStdlib.h>
24#include <lal/DetectorSite.h>
25#include <lal/SkyCoordinates.h>
26
27#if defined(__cplusplus)
28extern "C" {
29#elif 0
30} /* so that editors will match preceding brace */
31#endif
32
33/**
34 * \defgroup SimulateCoherentGW_h Header SimulateCoherentGW.h
35 * \ingroup lal_inject
36 * \author Creighton, T. D.
37 * \deprecated This module is deprecated, please see LALSimulation for a replacement.
38 *
39 * \brief Provides routines to simulate generic gravitational waveforms
40 * originating from a particular source.
41 *
42 * ### Synopsis ###
43 *
44 * \code
45 * #include <lal/SimulateCoherentGW.h>
46 * \endcode
47 *
48 * This header covers generic routines and structures to represent and
49 * simulate the effects of a plane gravitational wave propagating from a
50 * distinct point on the sky.
51 *
52 * Any plane gravitational wave is specified by a direction
53 * \f$\mathbf{\hat{n}}\f$ to its apparent source (i.e.\ opposite to its direction
54 * of propagation), and by the inistantaneous values \f$h_+(t)\f$,
55 * \f$h_\times(t)\f$ of its plus and cross polarizations as functions of
56 * (retarded) time \f$t=t_0+\mathbf{\hat{n}}\cdot(\mathbf{x}-\mathbf{x}_0)\f$, where
57 * \f$t_0\f$ is the time measured at some local reference point \f$\mathbf{x}_0\f$,
58 * and \f$t\f$ is the time measured by a synchronized clock at \f$\mathbf{x}\f$. We
59 * adopt the standard meaning of the instantaneous strain amplitudes
60 * \f$h_{+,\times}\f$: in some reference transverse \f$x\f$-\f$y\f$ coordinate system
61 * oriented such that \f$\mathbf{\hat{x}}\times\mathbf{\hat{y}}=-\mathbf{\hat{n}}\f$
62 * points in the direction of propagation, two free observers originally
63 * separated by a displacement \f$(x,y)\f$ will experience an additional
64 * tidal displacement \f$\delta x=(xh_+ + yh_\times)/2\f$, \f$\delta
65 * y=(xh_\times - yh_+)/2\f$.
66 *
67 * \par Quasiperiodic waves:
68 * Most astrophysical sources of
69 * gravitational radiation are described as \e quasiperiodic (or,
70 * less accurately, as "adiabatic"), in that they can be said to have
71 * an instantaneous frequency, amplitude, and polarization, all of which
72 * vary on timescales much longer than a wave period. Mathematically we
73 * write this as:
74 * \f[
75 * h_{+,\times}(t) = A_{+,\times}(t)\cos\phi(t)
76 * + B_{+,\times}(t)\sin\phi(t) \; ,
77 * \f]
78 *
79 * \anchor inject_phase_diagram
80 * \image html inject_phase_diagram.png "Polarization phase diagram for a quasiperiodic gravitational wave. The phase point p(t) traces out the indicated ellipse in the h_+\,h_x plane; the parameters A1\, A2 and Phi remain roughly constant over many cycles in phi."
81 *
82 * where \f$\phi(t)=2\pi\int f(t)\,dt\f$, and the <em>evolution timescale</em>
83 * \f$\tau=\min\{A/\dot{A},B/\dot{B},f/\dot{f}\}\f$ is much greater than
84 * \f$h/\dot{h}\sim1/f\f$. Obviously it is mathematically impossible for the
85 * physical functions \f$h_{+,\times}(t)\f$ to specify uniquely more than two
86 * other functions of time; we rely on the notion of quasiperiodicity to
87 * define "natural" choices of instantaneous frequency and amplitude.
88 * The ambiguity in this choice is on the order of the amount that these
89 * quantities change over a cycle.
90 *
91 * While the above formula appears to have five degrees of freedom (two
92 * quadrature amplitudes \f$A\f$ and \f$B\f$ for each polarization, plus a common
93 * phase function \f$\phi\f$), there is a degeneracy between the two
94 * quadrature amplitudes and a shift in phase. One could simply treat
95 * each polarization independently and represent the system with two
96 * amplitude functions \f$A_{+,\times}\f$ and two phase functions
97 * \f$\phi_{+,\times}\f$, but we would like to preserve the notion that the
98 * phases of the two waveforms derive from a single underlying
99 * instantaneous frequency. We therefore write the waveforms in terms of
100 * two polarization amplitudes \f$A_1(t)\f$ and \f$A_2(t)\f$, a single phase
101 * function \f$\phi(t)\f$, and a polarization shift \f$\Phi(t)\f$:
102 * \f{eqnarray}{
103 * \label{eq_quasiperiodic_hpluscross}
104 * h_+(t) & = & A_1(t)\cos\Phi(t)\cos\phi(t)
105 * - A_2(t)\sin\Phi(t)\sin\phi(t) \; , \\
106 * h_\times(t) & = & A_1(t)\sin\Phi(t)\cos\phi(t)
107 * + A_2(t)\cos\Phi(t)\sin\phi(t) \; .
108 * \f}
109 * The physical meaning of these functions is shown in \ref inject_phase_diagram "this figure".
110 *
111 * There is a close relationship between the polarization shift \f$\Phi\f$
112 * and the orientation of the \f$x\f$-\f$y\f$ coordinates used to define our
113 * polarization basis: if we rotate the \f$x\f$ and \f$y\f$ axes by an angle
114 * \f$\Delta\psi\f$, we change \f$\Phi\f$ by an amount \f$-2\Delta\psi\f$. (The
115 * factor of 2 comes from the fact that the + and \f$\times\f$ modes are
116 * quadrupolar: a + mode rotated \f$45^\circ\f$ is a \f$\times\f$ mode, and a
117 * mode rotated \f$90^\circ\f$ is the opposite of itself.) We use the
118 * <em>polarization angle</em> \f$\psi\f$ to define the orientation of the
119 * \f$x\f$-axis of the polarization basis relative to an Earth-fixed
120 * reference frame (see the coordinate conventions below). If \f$\Phi\f$ is
121 * constant, one can redefine \f$\psi\f$ such that \f$\Phi=0\f$; however, when
122 * \f$\Phi\f$ changes with time, we would nonetheless like our polarization
123 * basis to remain fixed. We therefore retain the constant \f$\psi\f$ and
124 * the function \f$\Phi(t)\f$ as distinct quantities.
125 *
126 * The advantage of this quasiperiodic representation of a gravitational
127 * wave is that a physical sampling of the parameters \f$A_1\f$, \f$A_2\f$,
128 * \f$\phi\f$, and \f$\Phi\f$ need only be done on timescales \f$\Delta
129 * t\lesssim\tau\f$, whereas the actual wave functions \f$h_{+,\times}\f$ need
130 * to be sampled on timescales \f$\Delta t\lesssim1/f\f$.
131 *
132 * The following coordinate conventions are assumed:
133 * <ol>
134 * <li> Fig. 7 of \cite Will_C_1996 defines standard coordinate
135 * conventions for nonprecessing binaries, and by extension, for any
136 * fixed-axis rotating source: If \f$\mathbf{\hat{z}}\f$ points in the direction
137 * of wave propagation (away from the source), and \f$\mathbf{\hat{l}}\f$ points
138 * in the (constant) direction of the source's angular momentum vector,
139 * then the \f$x\f$-\f$y\f$ coordinates used to define the + and \f$\times\f$
140 * polarizations are given by \f$\mathbf{\hat{x}}=|\csc
141 * i|\mathbf{\hat{z}}\times\mathbf{\hat{l}}\f$ and
142 * \f$\mathbf{\hat{y}}=\mathbf{\hat{z}}\times\mathbf{\hat{x}}\f$, where
143 * \f$i=\arccos(\mathbf{\hat{z}}\cdot\mathbf{\hat{l}})\f$ is the inclination angle
144 * between \f$\mathbf{\hat{l}}\f$ and \f$\mathbf{\hat{z}}\f$. Such a system will
145 * generically have \f$A_1(t)=A(t)(1+\cos^2i)\f$, \f$A_2(t)=2A(t)\cos i\f$,
146 * \f$\Phi(t)=0\f$, and \f$f(t)>0\f$ (i.e.\ \f$\phi(t)\f$ increasing with time). For
147 * precessing systems, prescriptions for \f$\mathbf{\hat{x}}\f$ and
148 * \f$\mathbf{\hat{y}}\f$ become ambiguous, but they \e must be fixed; the
149 * relations for \f$A_1\f$, \f$A_2\f$, and \f$\Phi\f$ will no longer be maintained.</li>
150 *
151 * <li> Appendix B of \cite ABCF2001 defines a convention for
152 * the overal polarization angle \f$\psi\f$: Let \f$\mathbf{\hat{N}}\f$ be the
153 * direction of the Earth's north celestial pole, and define the
154 * direction of the <em>ascending node</em>
155 * \f$\mathbf{\hat{\Omega}}=|\csc\alpha|\mathbf{\hat{N}}\times\mathbf{\hat{z}}\f$, where
156 * \f$\alpha\f$ is the right ascension of the source. Then \f$\psi\f$ is the
157 * angle, right-handed about \f$\mathbf{\hat{z}}\f$, from \f$\mathbf{\hat{\Omega}}\f$ to
158 * \f$\mathbf{\hat{x}}\f$.</li>
159 *
160 * <li> The direction of propagation of the wave is defined by the right
161 * ascension \f$\alpha\f$ and declination \f$\delta\f$ of the \e source, as
162 * seen from the point of measurement. See \ref SkyCoordinates_h for a
163 * definition of these quantities. We expect that these will be
164 * effectively constant for almost any gravitational wave source of
165 * interest.</li>
166 * </ol>
167 *
168 * \par The polarization response:
169 * The relative strain induced in
170 * the test masses of a detector by a passing gravitational wave depends
171 * not only on the amplitudes \f$h_{+,\times}\f$ of the gravitational wave,
172 * but also on the design of the detector and its orientation with
173 * relative to the \f$x\f$-\f$y\f$ coordinate system used to define the + and
174 * \f$\times\f$ polarizations. For a given detector, the response to each
175 * polarization thus depends on the right ascension \f$\alpha\f$, declination
176 * \f$\delta\f$, and polarization angle \f$\psi\f$ of the source (which define
177 * the orientation of the + and \f$\times\f$ polarization axes relative to
178 * the Earth), and on the time \f$t\f$ (which determines the orientation of
179 * the detector as the Earth rotates). The strain \f$h(t)\f$ induced in the
180 * detector is thus given by two polarization response functions
181 * \f$F_{+,\times}(\alpha,\delta,\psi;t)\f$ by:
182 * \f[
183 * h(t) = h_+(t)F_+(\alpha,\delta,\psi;t) +
184 * h_\times(t)F_\times(\alpha,\delta,\psi;t) \; .
185 * \f]
186 * We will not discuss the computation of these functions \f$F_{+,\times}\f$,
187 * as these are covered under the header \ref DetResponse_h.
188 *
189 * \par The transfer function:
190 * All gravitational wave detectors
191 * incorporate a set of analog and digital filters that convert a
192 * gravitational excitation on the test masses into a measurable output
193 * time series. The effects of these functions are aggregated into a
194 * complex-valued <em>transfer function</em> \f${\cal T}(f)\f$, which gives the
195 * instrumental response (in units of "counts" from an
196 * analog\f$\rightarrow\f$digital converter) to gravitational waves of unit
197 * amplitued at the frequency \f$f\f$. Specifically, if the strain exerted
198 * on the antenna is given by \f$h(t)=\mathrm{Re}[{\cal H}e^{2\pi ift}]\f$
199 * (where the complex amplitude \f$\cal H\f$ includes the phase of the wave),
200 * then the ADC output of the instrument is given by:
201 * \f[
202 * o(t) = \mathrm{Re}\left[ {\cal T}(f) {\cal H}e^{2\pi ift} \right] \; .
203 * \f]
204 * The transfer function has a strong frequency dependence in order to
205 * "whiten" the highly-coloured instrumental noise, and thus preserve
206 * instrumental sensitivity across a broad band of frequencies.
207 *
208 * We note that although the transfer function measures the response of
209 * the instrument to a gravitational wave, the term <em>response
210 * function</em> refers to inverse transformation of taking an instrumental
211 * response and computing a gravitational waveform; that is, \f${\cal
212 * R}(f)=1/{\cal T}(f)\f$. This confusing bit of nomenclature arises from
213 * the fact that most data analysis deals with extracting gravitational
214 * waveforms from the instrumental output, rather than injecting
215 * waveforms into the output.
216 *
217 * For quasiperiodic waveforms with a well-defined instantaneous
218 * frequency \f$f(t)\f$ and phase \f$\phi(t)\f$, we can compute the response of
219 * the instrument entirely in the time domain in the adiabatic limit: if
220 * our instrumental excitation is a linear superposition of waveforms
221 * \f$h(t)=\mathrm{Re}[{\cal H}(t)e^{i\phi(t)}]\f$, then the output is a
222 * superposition of waves of the form
223 * \f[
224 * o(t) \approx \mathrm{Re}\left[ {\cal T}\{f(t)\}
225 * {\cal H}(t)e^{i\phi(t)} \right] \; .
226 * \f]
227 * This expression is approximate to the extent that \f${\cal T}(f)\f$ varies
228 * over the range \f$f\pm1/\tau\f$, where \f$\tau\f$ is the evolution timescale
229 * of \f${\cal H}(t)\f$ and \f$f(t)\f$. Since the transfer function and
230 * polarization response (above) are linear operators, we can apply them
231 * in either order.
232 *
233 * \par A note on terminology:
234 * We use the word "coherent" in the
235 * name of this header in the loosest possible sense, refering to any
236 * wave with a well-defined direction of propagation, whose wave
237 * amplitudes \f$h_{+,\times}\f$ are deterministic functions of retarded
238 * time. Given a knowledge of these parameters, such a waveform is
239 * amenable to "coherent" detection in a network of detectors, through
240 * time-shifted matched filtering.
241 *
242 * However, coherence is often used to refer to a more restricted class
243 * of waveforms that are "effectively monochromatic" over some
244 * coherence timescale \f$t_\mathrm{coh}\f$; i.e.\ in any timespan
245 * \f$t_\mathrm{coh}\f$ there is a fixed-frequency sinusoid that is never
246 * more than \f$90^\circ\f$ out of phase with the waveform. This is more
247 * retrictive even than our concept of quasiperiodic waves; for
248 * smoothly-varying waveforms one has \f$t_\mathrm{coh}\sim\dot{f}^{-1/2}\f$,
249 * which is much shorter than the evolution timescale \f$\tau\sim
250 * f/\dot{f}\f$ (provided \f$\tau\gg1/f\f$, as we have assumed).
251 *
252 */
253
254/* This structure stores a representation of a plane
255 * gravitational wave propagating from a particular point on the sky.
256 * Several alternate representations are permitted to allow a more
257 * natural characterization of quasiperiodic waveforms.
258 *
259 * \note It is permissible to set only some of the
260 * \c REAL4TimeSeries or \c REAL4TimeVectorSeries fields above,
261 * but the waveform is treated as being zero except during those times
262 * when either \c h, or both \c a and \c phi, are defined.
263 * Where \c shift is not specified, it is assumed that \f$\Phi\f$ is
264 * zero; where \c f is not specified but \c phi is, \f$f(t)\f$ can be
265 * computed as \f$\dot{\phi}(t)/2\pi\f$. Where \c f and \c phi
266 * overlap, or where \c h and any other time series overlap, they
267 * must be defined consistently.
268 *
269 */
270typedef struct tagCoherentGW {
271 SkyPosition position; /*< The location of the source in the sky; this should be in equatorial celestial coordinates, but routines may be able to do the conversion */
272 REAL4 psi; /*< The polarization angle \f$\psi\f$, in radians, as defined in Appendix B of \cite ABCF2001 */
273 REAL4TimeVectorSeries *h; /*< A time-sampled two-dimensional vector storing the waveforms \f$h_+(t)\f$ and \f$h_\times(t)\f$, in dimensionless strain */
274 REAL4TimeVectorSeries *a; /*< A time-sampled two-dimensional vector storing the amplitudes \f$A_1(t)\f$ and \f$A_2(t)\f$, in dimensionless strain */
275 REAL4TimeSeries *f; /*< A time-sampled sequence storing the instantaneous frequency \f$f(t)\f$, in Hz. */
276 REAL8TimeSeries *phi; /*< A time-sampled sequence storing the phase function \f$\phi(t)\f$, in radians */
277 REAL4TimeSeries *shift; /*< A time-sampled sequence storing the polarization shift \f$\Phi(t)\f$, in radians */
278 UINT4 dtDelayBy2; /*< A user specified half-interval time step for the Doppler delay look-up table (will default to 400s if set to 0) */
279 UINT4 dtPolBy2; /*< A user defined half-interval time step for the polarisation response look-up table (will default to 300s if set to 0) */
280} CoherentGW;
281
282/* This structure contains information required to determine the response
283 * of a detector to a gravitational waveform.
284 */
285typedef struct tagDetectorResponse {
286 COMPLEX8FrequencySeries *transfer; /*< The frequency-dependent transfer function of the interferometer, in ADC counts per unit strain amplitude at any given frequency;
287 * if absent, the response will be given in raw strain rather than ADC output */
288 LALDetector *site; /*< A structure storing site and polarization information, used to compute the polarization response and the propagation delay;
289 * if absent, the response will be computed to the plus mode waveform with no time delay */
290 LIGOTimeGPS heterodyneEpoch; /*< A reference time for heterodyned detector output time series, where the phase of the mixing signal is zero.
291 * This parameter is only used when generating detector output time series with nonzero heterodyne frequency \c f0.
292 * (Note: This should really be a parameter stored in the \c TimeSeries structure along with \c f0, but it isnt, so we
293 * have to add it here.)
294 */
296
297/* Function prototypes. */
298
299/** \deprecated This function is deprecated, please see LALSimulation for a replacement. */
300void
303 CoherentGW *input,
304 DetectorResponse *detector );
305
306
307#if 0
308{ /* so that editors will match succeeding brace */
309#elif defined(__cplusplus)
310}
311#endif
312
313#endif /* _SIMULATECOHERENTGW_H */
void LALSimulateCoherentGW(LALStatus *status, REAL4TimeSeries *output, CoherentGW *input, DetectorResponse *detector)
uint32_t UINT4
Four-byte unsigned integer.
float REAL4
Single precision real floating-point number (4 bytes).
See DATATYPE-FrequencySeries types for documentation.
Definition: LALDatatypes.h:899
REAL4TimeSeries * shift
SkyPosition position
REAL4TimeVectorSeries * a
REAL8TimeSeries * phi
REAL4TimeVectorSeries * h
REAL4TimeSeries * f
LIGOTimeGPS heterodyneEpoch
COMPLEX8FrequencySeries * transfer
Detector structure.
Definition: LALDetectors.h:278
LAL status structure, see The LALStatus structure for more details.
Definition: LALDatatypes.h:947
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
Time series of REAL4 vectors, see DATATYPE-TimeVectorSeries for more details.
Definition: LALDatatypes.h:673
Time series of REAL8 data, see DATATYPE-TimeSeries types for more details.
Definition: LALDatatypes.h:580
This structure stores the two spherical coordinates of a sky position; ie a generic latitude and long...
void output(int gps_sec, int output_type)
Definition: tconvert.c:440