Loading [MathJax]/extensions/TeX/AMSsymbols.js
LALInspiral 5.0.3.1-b246709
All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
GeneratePPNInspiral.h
Go to the documentation of this file.
1/*
2* Copyright (C) 2007 Philip Charlton, Duncan Brown, Jolien Creighton, David McKechan, Stephen Fairhurst, Teviet Creighton, Thomas Cokelaer, 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 _GENERATEPPNINSPIRAL_H
21#define _GENERATEPPNINSPIRAL_H
22
23#include <lal/LALAtomicDatatypes.h>
24#include <lal/LALDatatypes.h>
25#include <lal/Random.h>
26#include <lal/SimulateCoherentGW.h>
27#include <lal/SkyCoordinates.h>
28
29#if defined(__cplusplus)
30extern "C" {
31#elif 0
32} /* so that editors will match preceding brace */
33#endif
34
35/**
36 * \defgroup GeneratePPNInspiral_h Header GeneratePPNInspiral.h
37 * \ingroup lalinspiral_inject
38 * \author Creighton, T. D.
39 *
40 * \brief Provides routines to generate restricted parametrized
41 * post\f${}^{5/2}\f$-Newtonian inspiral waveforms.
42 *
43 * ### Synopsis ###
44 *
45 * \code
46 * #include <lal/GeneratePPNInspiral.h>
47 * \endcode
48 *
49 * ### Description ###
50 *
51 * This header covers routines to generate a "restricted" parametrized
52 * post\f${}^{5/2}\f$-Newtonian binary inspiral waveform in the time domain.
53 * That is, the calculation of the wave phase is accurate to
54 * post\f${}^{5/2}\f$-Newtonian order (including corrections up to order
55 * \f$v^5/c^5\f$, where \f$v\f$ is the orbital speed), but the wave amplitudes
56 * are accurate only to leading (post\f${}^0\f$-Newtonian) order.
57 * Furthermore, at each order the post\f${}^{n/2}\f$-Newtonian correction can
58 * be turned on, off, or set to an unphysical value, by adjusting a
59 * parameter \f$p_n\f$.
60 *
61 * The post-Newtonian expansion implicitly assumes an \e adiabatic
62 * inspiral, where one can represent the waveform by an "instantaneous"
63 * amplitude and frequency that vary over timescales longer than one wave
64 * period. The \e orbital frequency of the system to
65 * post\f${}^{5/2}\f$-Newtonian order is given in Eqs.\ 6.4.1 and 6.9.1
66 * of \cite GRASP2000; here we work entirely in terms of the
67 * <em>gravitational-wave</em> frequency, which is twice the orbital
68 * frequency:
69 * \f{eqnarray}{
70 * \label{eq_ppn_freq}
71 * f(t) & = & \frac{M_\odot}{8\pi T_\odot m_\mathrm{tot}}\left\{
72 * p_0\Theta^{-3/8}+
73 * p_1\Theta^{-1/2}+
74 * p_2\left(\frac{743}{2688}+\frac{11}{32}\eta\right)\Theta^{-5/8}-
75 * p_3\frac{3\pi}{10}\Theta^{-3/4} \right. \\
76 * & & \left.+ p_4\left(\frac{1855099}{14450688}+\frac{56975}{258048}\eta+
77 * \frac{371}{2048}\eta^2\right)\Theta^{-7/8}-
78 * p_5\left(\frac{7729}{21504}+\frac{3}{256}\eta\right)\pi\Theta^{-1}
79 * \right\} \; ,
80 * \f}
81 * where \f$M_\odot\f$ is the mass of the Sun,
82 * \f$T_\odot=GM_\odot/c^3=4.925491\times10^{-6}\f$s is the "geometrized"
83 * solar mass in time units, \f$m_\mathrm{tot}=m_1+m_2\f$ is the total mass
84 * of the binary, \f$\eta=m_1m_2/m_\mathrm{tot}^2\f$ is the (symmetric) mass
85 * ratio parameter, and \f$\Theta\f$ is a dimensionless time parameter:
86 * \f{equation}{
87 * \label{eq_ppn_theta}
88 * \Theta(t) = \frac{\eta M_\odot}{5T_\odot m_\mathrm{tot}}(t_c-t) \; .
89 * \f}
90 * Here \f$t_c\f$ is the time of coalescence of the two masses in the
91 * point-mass approximation. The post-Newtonian parameters \f$p_k\f$ are
92 * defined such that in a normal (physical) post\f${}^{n/2}\f$-Newtonian
93 * expansion, one sets \f$p_1=0\f$ and \f$p_{k>n}=0\f$, and \f$p_k=1\f$ for all other
94 * \f$k\f$. However, changing this convention can be used to model in an
95 * approximate way things such as spin, eccentricity, or non-GR theories
96 * of gravity. We also note that while most terms are normalized to
97 * their normal post-Newtonian values, the normalization on the \f$p_1\f$
98 * term is completely arbitrary, since it is zero in a normal
99 * post-Newtonian expansion.
100 *
101 * The wave phase as a function of time can be computed analytically from
102 * \eqref{eq_ppn_freq} as \f$\phi_\mathrm{orb}=2\pi\int f\,dt\f$:
103 * \f{eqnarray}{
104 * \label{eq_ppn_phi}
105 * \phi(t) & = & \phi_c - \frac{2}{\eta}\left\{
106 * p_0\Theta^{5/8}+
107 * p_1\frac{5}{4}\Theta^{1/2}+
108 * p_2\left(\frac{3715}{8064}+\frac{55}{96}\eta\right)\Theta^{3/8}-
109 * p_3\frac{3\pi}{4}\Theta^{1/4} \right. \\
110 * & & \left.+ p_4\left(\frac{9275495}{14450688}+\frac{284875}{258048}\eta+
111 * \frac{1855}{2048}\eta^2\right)\Theta^{1/8}-
112 * p_5\left(\frac{38645}{172032}+\frac{15}{2048}\eta\right)\pi
113 * \log\left(\frac{\Theta}{\Theta_0}\right)\right\} \; .
114 * \f}
115 * Here \f$\Theta_0\f$ is an arbitrary constant; changing it is equivalent to
116 * changing \f$\phi_c\f$. We note that the post\f${}^{5/2}\f$-Newtonian term
117 * introduces a late-time divergence in phase which renders meaningless
118 * the interpretation of \f$\phi_c\f$ as "phase at coalescence"; in our
119 * convention we define \f$\phi_c\f$ to correspond to the case \f$\Theta_0=1\f$.
120 *
121 * We refer the interested reader to Sec.\ 6.6 of\ \cite GRASP2000
122 * for a discussion of how propagation effects shift the phase of the
123 * waveform relative to the orbital phase. To summarize, though: A
124 * changing propagation delay does introduce a time-dependent phase shift
125 * in the waveform, but the dependence on \f$t\f$ is weak except at very late
126 * times; although it looks like a post\f${}^{3/2}\f$-Newtonian phase
127 * correction, it can in fact be represented as a post\f${}^{3}\f$-Newtonian
128 * phase correction combined with a post\f${}^{3/2}\f$-Newtonian amplitude
129 * correction. Since we are concerned with \e restricted
130 * post\f${}^{5/2}\f$-Newtonian waveforms, which model the amplitude only to
131 * leading (post\f${}^0\f$-Newtonian) order, we can ignore these propagation
132 * effects.
133 *
134 * To leading order, then, the amplitude of the + and \f$\times\f$
135 * polarizations of the wave are given by Eqs.\ 6.6.1--6.6.4
136 * of\ \cite GRASP2000 as:
137 * \f{eqnarray}{
138 * \label{eq_ppn_aplus}
139 * A_+(t) & = & -\frac{2T_\odot c}{D}(1+\cos^2 i)
140 * \left(\frac{\eta m_\mathrm{tot}}{M_\odot}\right)
141 * \left[\frac{\pi T_\odot m_\mathrm{tot}f(t)}{M_\odot}
142 * \right]^{2/3} \; , \\
143 * \label{eq_ppn_across}
144 * A_\times(t) & = & -\frac{2T_\odot c}{D}(2\cos i)
145 * \left(\frac{\eta m_\mathrm{tot}}{M_\odot}\right)
146 * \left[\frac{\pi T_\odot m_\mathrm{tot}f(t)}{M_\odot}
147 * \right]^{2/3} \; ,
148 * \f}
149 * where \f$D\f$ is the distance to the source and \f$i\f$ is the inclination of
150 * the axis of the source to the line of sight. The normal polarization
151 * convention in\ \cite Will_C_1996 is used, where the reference
152 * \f$x\f$-coordinate axis for the + and \f$\times\f$ polarization tensors is the
153 * ascending node of the rotational plane as it crosses the plane
154 * transverse to the propagation direction. This convention implies that
155 * the + and \f$\times\f$ waveforms are elliptically polarized as follows:
156 * \f{eqnarray}{
157 * \label{eq_ppn_hplus}
158 * h_+(t) & = & A_+(t)\cos\phi(t) \; , \\
159 * \label{eq_ppn_hcross}
160 * h_\times(t) & = & A_\times(t)\sin\phi(t) \; .
161 * \f}
162 *
163 */
164/** @{ */
165
166/** \name Error Codes */
167/** @{ */
168#define GENERATEPPNINSPIRALH_ENUL 1 /**< Unexpected null pointer in arguments */
169#define GENERATEPPNINSPIRALH_EOUT 2 /**< output field a, f, phi, or shift already exists */
170#define GENERATEPPNINSPIRALH_ETBAD 3 /**< Bad sampling interval */
171#define GENERATEPPNINSPIRALH_EFBAD 4 /**< Bad starting frequency; could not get valid start time */
172#define GENERATEPPNINSPIRALH_EPBAD 5 /**< Bad post-Newtonian parameters */
173#define GENERATEPPNINSPIRALH_EMBAD 6 /**< Bad masses */
174#define GENERATEPPNINSPIRALH_EDBAD 7 /**< Bad distance */
175#define GENERATEPPNINSPIRALH_EMEM 8 /**< Out of memory */
176/** @} */
177
178/** \cond DONT_DOXYGEN */
179#define GENERATEPPNINSPIRALH_MSGENUL "Unexpected null pointer in arguments"
180#define GENERATEPPNINSPIRALH_MSGEOUT "output field a, f, phi, or shift already exists"
181#define GENERATEPPNINSPIRALH_MSGETBAD "Bad sampling interval"
182#define GENERATEPPNINSPIRALH_MSGEFBAD "Bad starting frequency; could not get valid start time"
183#define GENERATEPPNINSPIRALH_MSGEPBAD "Bad post-Newtonian parameters"
184#define GENERATEPPNINSPIRALH_MSGEMBAD "Bad masses"
185#define GENERATEPPNINSPIRALH_MSGEDBAD "Bad distance"
186#define GENERATEPPNINSPIRALH_MSGEMEM "Out of memory"
187/** \endcond */
188
189/**
190 * \name More Termination conditions
191 * In addition to the error conditions above, there are a number of ways
192 * that the signal generation routine can terminate gracefully while
193 * still returning a valid waveform. In many cases one \e wants to
194 * continue generating a waveform "until things fall apart"; the
195 * following codes, returned in the \c PPNParamStruc below, allow the
196 * waveform generator to report exactly \e how things fell apart.
197 *
198 * For the sake of LAL namespace conventions, these termination codes are
199 * <tt>\#define</tt>d and autodocumented exactly like error codes.
200 */
201/** @{ */
202#define GENERATEPPNINSPIRALH_EFSTOP 0 /**< Reached requested termination frequency */
203#define GENERATEPPNINSPIRALH_ELENGTH 1 /**< Reached maximum length, or end of provided time series vector */
204#define GENERATEPPNINSPIRALH_EFNOTMON 2 /**< Frequency no longer increasing monotonically */
205#define GENERATEPPNINSPIRALH_EPNFAIL 3 /**< Evolution dominated by higher-order PN terms */
206#define GENERATEPPNINSPIRALH_ERTOOSMALL 4 /**< Orbital radius too small for PN approximation */
207/** @} */
208
209/** \cond DONT_DOXYGEN */
210#define GENERATEPPNINSPIRALH_MSGEFSTOP "Reached requested termination frequency"
211#define GENERATEPPNINSPIRALH_MSGELENGTH "Reached maximum length, or end of provided time series vector"
212#define GENERATEPPNINSPIRALH_MSGEFNOTMON "Frequency no longer increasing monotonically"
213#define GENERATEPPNINSPIRALH_MSGEPNFAIL "Evolution dominated by higher-order PN terms"
214#define GENERATEPPNINSPIRALH_MSGERTOOSMALL "Orbital radius too small for PN approximation"
215/** \endcond */
216
217/*
218 * FIXME: SWIG with -Werror won't let const CHAR *termDescription pass,
219 * as it leaves a lot of potential for memory leaks. I choose to
220 * make this an opaque struct.
221 */
222#ifndef SWIG
223/**
224 * This structure stores the parameters for constructing a restricted
225 * post-Newtonian waveform. It is divided into three parts: parameters
226 * passed along to the output structure but not used by waveform
227 * generator, parameters used as input to the waveform generator, and
228 * parameters set by the generator to evaluate its success.
229 */
230typedef struct tagPPNParamStruc {
231 /** \name Passed parameters. */
232 /** @{ */
233 SkyPosition position; /**< location of source on sky */
234 REAL4 psi; /**< polarization angle (radians) */
235 LIGOTimeGPS epoch; /**< start time of output time series */
236 /** @} */
237
238 /**\name Input parameters. */
239 /** @{ */
240 REAL4 mTot; /**< The total mass \f$m_\mathrm{tot}=m_1+m_2\f$ of the binary system, in solar masses */
241 REAL4 eta; /**< The mass ratio \f$\eta=m_1m_2/m_\mathrm{tot}^2\f$ of the binary system; Physically this
242 * parameter must lie in the range \f$\eta\in(0,1/4]\f$; values outside of
243 * this range may be permitted in order to represent "nonphysical"
244 * post-Newtonian expansions
245 */
246 REAL4 d; /**< The distance to the system, in metres */
247 REAL4 inc; /**< The inclination of the system to the line of sight, in radians */
248 REAL4 phi; /**< The phase at coalescence \f$\phi_c\f$ (or arbitrary reference phase for a post\f${}^{5/2}\f$-Newtonian
249 * approximation), in radians
250 */
251 REAL8 deltaT; /**< The requested sampling interval of the waveform, in s */
252 REAL4 fStartIn; /**< The requested starting frequency of the waveform, in Hz */
253 REAL4 fStopIn; /**< The requested termination frequency of
254 * the waveform, in Hz; If set to 0, the waveform will be generated
255 * until a termination condition (above) is met; If set to a negative
256 * number, the generator will use its absolute value as the terminating
257 * frequency, but will ignore post-Newtonian breakdown; it will terminate
258 * only at the requested frequency \f$-\mathtt{fStopIn}\f$, a local maximum
259 * frequency, or the central singularity
260 */
261 UINT4 lengthIn; /**< The maximum number of samples in the generated waveform; If zero, the waveforms can be arbitrarily long */
262 REAL4Vector *ppn; /**< The parameters \f$p_n\f$ selecting the type of post-Newtonian expansion; If \c ppn=\c NULL, a "normal" (physical) expansion is assumed */
263 INT4 ampOrder; /**< PN amplitude selection 0-5 */
264 /** @} */
265
266 /** \name Output parameters. */
267 /** @{ */
268 REAL8 tc; /**< The time \f$t_c-t\f$ from the start of the waveform to coalescence (in the point-mass approximation), in s */
269 REAL4 dfdt; /**< The maximum value of \f$\Delta f\Delta t\f$ encountered over any timestep \f$\Delta t\f$ used in generating the waveform */
270 REAL4 fStart; /**< The actual starting frequency of the waveform, in Hz (normally close but not identical to \c fStartIn) */
271 REAL4 fStop; /**< The frequency at the termination of the waveform, in Hz */
272 UINT4 length; /**< The length of the generated waveform */
273 INT4 termCode; /**< The termination condition (above) that stopped computation of the waveform */
274 const CHAR *termDescription; /**< The termination code description (above) */
275 /** @} */
277#else /* SWIG */
278typedef struct tagPPNParamStruc PPNParamStruc;
279#endif /* SWIG */
280
281/**
282 * This structure stores the position and mass parameters of a galactic inspiral event.
283 */
284typedef struct tagGalacticInspiralParamStruc {
285 REAL4 rho; /**< The distance of the binary system from the Galactic axis, in kpc */
286 REAL4 z; /**< The distance of the system from the Galactic plane, in kpc */
287 REAL4 lGal; /**< The Galactocentric Galactic longitude of the system (ie the Galactic longitude of the direction <em>from
288 * the Galactic centre</em> through the system), in radians; See\ \ref SkyCoordinates_h for the definition of this quantity
289 */
290 REAL4 m1, m2; /**< The masses of the binary components, in solar masses */
291 LIGOTimeGPS geocentEndTime; /**< The geocentric end time of the inspiral event */
293
294
295
296/* ---------- Function prototypes. ---------- */
297void
299 CoherentGW *output,
301
302
303
304
305void
307 CoherentGW *output,
309
310
311
312
313
314
315void
317 PPNParamStruc *output,
320
321
322/** @} */ /* end:GeneratePPNInspiral_h */
323
324
325#if 0
326{ /* so that editors will match succeeding brace */
327#elif defined(__cplusplus)
328}
329#endif
330
331#endif /* _GENERATEPPNINSPIRAL_H */
void LALGeneratePPNInspiral(LALStatus *, CoherentGW *output, PPNParamStruc *params)
Computes a parametrized post-Newtonian inspiral waveform.
void LALGeneratePPNAmpCorInspiral(LALStatus *, CoherentGW *output, PPNParamStruc *params)
Computes a parametrized post-Newtonian inspiral waveform with ampltidude corrections.
void LALGetInspiralParams(LALStatus *, PPNParamStruc *output, GalacticInspiralParamStruc *input, RandomParams *params)
Computes the input parameters for a PPN inspiral.
double REAL8
char CHAR
uint32_t UINT4
int32_t INT4
float REAL4
This structure stores the position and mass parameters of a galactic inspiral event.
REAL4 lGal
The Galactocentric Galactic longitude of the system (ie the Galactic longitude of the direction from ...
REAL4 z
The distance of the system from the Galactic plane, in kpc.
LIGOTimeGPS geocentEndTime
The geocentric end time of the inspiral event.
REAL4 rho
The distance of the binary system from the Galactic axis, in kpc.
This structure stores the parameters for constructing a restricted post-Newtonian waveform.
REAL4 fStopIn
The requested termination frequency of the waveform, in Hz; If set to 0, the waveform will be generat...
REAL4Vector * ppn
The parameters selecting the type of post-Newtonian expansion; If ppn=NULL, a "normal" (physical) ex...
const CHAR * termDescription
The termination code description (above)
INT4 termCode
The termination condition (above) that stopped computation of the waveform.
REAL4 dfdt
The maximum value of encountered over any timestep used in generating the waveform.
LIGOTimeGPS epoch
start time of output time series
REAL4 phi
The phase at coalescence (or arbitrary reference phase for a post -Newtonian approximation),...
REAL4 psi
polarization angle (radians)
REAL4 fStart
The actual starting frequency of the waveform, in Hz (normally close but not identical to fStartIn)
INT4 ampOrder
PN amplitude selection 0-5.
SkyPosition position
location of source on sky
UINT4 length
The length of the generated waveform.
REAL4 fStop
The frequency at the termination of the waveform, in Hz.
REAL4 eta
The mass ratio of the binary system; Physically this parameter must lie in the range ; values outsid...
REAL8 tc
The time from the start of the waveform to coalescence (in the point-mass approximation),...
REAL4 mTot
The total mass of the binary system, in solar masses.
REAL4 fStartIn
The requested starting frequency of the waveform, in Hz.
REAL8 deltaT
The requested sampling interval of the waveform, in s.
REAL4 d
The distance to the system, in metres.
UINT4 lengthIn
The maximum number of samples in the generated waveform; If zero, the waveforms can be arbitrarily lo...
REAL4 inc
The inclination of the system to the line of sight, in radians.