Detailed Description

Provides routines to generate Taylor-parameterized continuous waveforms.

Author: Creighton, T. D.

Synopsis

#include <lal/GenerateTaylorCW.h>

This header covers routines to generate continuous quasiperiodic waveforms whose frequency varies slowly and smoothly with time. For such sources the frequency function is normally described by its Taylor "spindown" (or spin-up) coefficients. This type of waveform may be typical of objects such as neutron stars that are gradually shedding angular momentum, or are accelerating in the gravitational potential of a star cluster. The Taylor expansion is likely not suitable for long-term modelling of the frequency of waves from glitching neutron stars, neutron stars in close binary orbits, or neutron stars that are accreting or shedding angular momentum in a stochastic manner.

The frequency and phase of such slowly-varying quasiperiodic sources are given by their Taylor series:

\begin{eqnarray} \label{eq_taylorcw-freq} f(t) & = & f_0 \left[ 1 + \sum_{k=1}^n f_k(t-t_0)^k \right] \;, \\ \label{eq_taylorcw-phi} \phi(t) & = & \phi_0 + 2\pi f_0 \left[ (t-t_0) + \sum_{k=1}^n \frac{f_k}{k+1}(t-t_0)^{k+1} \right] \;, \end{eqnarray}

where \( f_k \) are the spin-normalized Taylor coefficients. If the source's spin is varying over some timescale \( \tau \) , one typically expects that \( f_k\sim\tau^{-k} \) . Note that in this and later discussions, \( f \) and \( \phi \) refer to the frequency and phase of the gravitational wave, which are typically some constant multiple of (often twice) the frequency and phase of the rotating source.

The PulsarCoherentGW structure allows for a very general description of waveforms with modulations in the amplitudes or relative phases of the wave polarizations, as described in Header PulsarSimulateCoherentGW.h. However, in this simplest model of quasiperiodic waveforms, we neglect such phenomena as precession that would produce these effects. Thus for any given source one can choose a polarization basis (described by some polarization angle \( \psi \) ) in which the wave has a constant elliptical polarization of the form:

\begin{eqnarray} \label{eq_taylorcw-hplus} h_+(t) & = & A_+ \cos\phi(t) \;, \\ \label{eq_taylorcw-hcross} h_\times(t) & = & A_\times \sin\phi(t) \;. \end{eqnarray}

Prototypes
void	LALGenerateTaylorCW (LALStatus , PulsarCoherentGW output, TaylorCWParamStruc *params)
	Computes a Taylor-parametrized continuous waveform. More...

Data Structures
struct	TaylorCWParamStruc
	This structure stores the parameters for constructing a gravitational waveform with a Taylor-polynomial frequency and phase. More...

Files
file	SimulateTaylorCWTest.c
	Generates a quasiperiodic waveform.

Error Codes
#define	GENERATETAYLORCWH_ENUL 1
	Unexpected null pointer in arguments. More...

#define	GENERATETAYLORCWH_EOUT 2
	Output field a, f, phi, or shift already exists. More...

#define	GENERATETAYLORCWH_EMEM 3
	Out of memory. More...

Function Documentation

◆ LALGenerateTaylorCW()

void LALGenerateTaylorCW	(	LALStatus *	stat,
		PulsarCoherentGW *	output,
		TaylorCWParamStruc *	params
	)

Computes a Taylor-parametrized continuous waveform.

Author: Creighton, T. D.

Description

This function computes a quaiperiodic waveform using the parameters in *params, storing the result in *output.

In the *params structure, the routine uses all the "input" fields specified in TaylorCWParamStruc, and sets all of the "output" fields. If params->f=NULL, a precisely periodic (monochromatic) waveform is generated.

In the *output structure, the field output->h is ignored, but all other pointer fields must be set to NULL. The function will create and allocate space for output->a, output->f, and output->phi as necessary. The output->shift field will remain set to NULL.

Algorithm

This function is a fairly straightforward calculation of Eq. \eqref{eq_taylorcw-freq} and Eq. \eqref{eq_taylorcw-phi} in Header GenerateTaylorCW.h. There are no real tricks involved, except to note that the phase \( \phi \) and the time elapsed \( t-t_0 \) are computed and stored as REAL8s in order to provide waveforms that are accurate to small fractions of a cycle over many years.

Since the waveform does not include any effects such as precession, the amplitudes \( A_+ \) , \( A_\times \) and the shift angle \( \Phi \) , as defined in Header PulsarSimulateCoherentGW.h, are constant. This is dealt with by setting output->a to be a REAL4TimeVectorSequence of two identical vectors \( (A_+,A_\times) \) spanning the requested time of the waveform, under the assumption that any routine using this output data (such as the routines in Header PulsarSimulateCoherentGW.h) will interpolate these two endpoints to get the instantaneous values of \( A_+ \) , \( A_\times \) . The field output->shift is left as NULL, so the constant value of \( \Phi \) must be subsumed into the polarization angle \( \psi \) .

The fields output->f and output->phi are created and filled at the requested sampling interval params->deltaT; it is up to the calling routine to ensure that this sampling interval is reasonable. As a guideline, we want to be able to determine the instantaneous wave phase accurately to within a fraction of a cycle. For functions that compute the phase by linear interpolation of output->phi, this means sampling on timescales \( \Delta t\lesssim\dot{f}^{-1/2}\sim\max\{\sqrt{kf_0f_kT^{k-1}}\} \) , where \( T \) is the duration of the waveform. More precisely, the largest deviation from linear phase evolution will typically be on the order of \( \Delta\phi\approx(1/2)\ddot{\phi}(\Delta t/2)^2\approx(\pi/4)\Delta f\Delta t \) , where \( \Delta f \) is the frequency shift over the timestep. So if we want our interpolated phase to agree with the true phase to within, say, \( \pi/2 \) radians, then we would like to have

\[ \Delta f \Delta t \lesssim 2 \;. \]

This routine provides a check by setting the output parameter field params->dfdt equal to the maximum value of \( \Delta f\Delta t \) encountered during the integration.

Definition at line 94 of file GenerateTaylorCW.c.

Macro Definition Documentation

◆ GENERATETAYLORCWH_ENUL

#define GENERATETAYLORCWH_ENUL 1

Unexpected null pointer in arguments.

Definition at line 93 of file GenerateTaylorCW.h.

◆ GENERATETAYLORCWH_EOUT

#define GENERATETAYLORCWH_EOUT 2

Output field a, f, phi, or shift already exists.

Definition at line 94 of file GenerateTaylorCW.h.

◆ GENERATETAYLORCWH_EMEM

#define GENERATETAYLORCWH_EMEM 3

Out of memory.

Definition at line 95 of file GenerateTaylorCW.h.