Header LALSimBurst.h

Detailed Description

Routines to generate burst waveforms.

Author

Kipp Cannon, Jolien Creighton

These routines generate several burst waveforms used in searches for gravitational waves, including sine-Gaussian waveforms, cosmic string cusp, kink and kinkkink waveforms, and band- and time-limited white-noise burst waveforms. Also included are several general-purpose routines to measure the properties of gravitational wave waveforms like the "hrss" and peak strain. These are useful for imposing normalizations and other diagnostic activities.

\[ \DeclareMathOperator{\order}{O} \newcommand{\Msol}{{M_{\Sol}}} \newcommand{\Sol}{\odot} \newcommand{\aye}{\mathrm{i}} \newcommand{\conj}[1]{#1^{*}} \newcommand{\diff}{\,\mathrm{d}} \newcommand{\ee}{\mathrm{e}} \newcommand{\magnitude}[1]{\left|#1\right|} \newcommand{\mean}[1]{\left\langle#1\right\rangle} \]

Prototypes
int	XLALGenerateImpulseBurst (REAL8TimeSeries **hplus, REAL8TimeSeries **hcross, REAL8 hpeak, REAL8 delta_t)
	Genereates a single-sample impulse waveform. More...
int	XLALGenerateBandAndTimeLimitedWhiteNoiseBurst (REAL8TimeSeries **hplus, REAL8TimeSeries **hcross, REAL8 duration, REAL8 frequency, REAL8 bandwidth, REAL8 eccentricity, REAL8 phase, REAL8 int_hdot_squared, REAL8 delta_t, gsl_rng *rng)
	Generate a band- and time-limited white-noise burst waveform with Gaussian envelopes in the time and frequency domains. More...
int	XLALGenerateStringCusp (REAL8TimeSeries **hplus, REAL8TimeSeries **hcross, REAL8 amplitude, REAL8 f_high, REAL8 delta_t)
	Generates cosmic string cusp waveforms. More...
int	XLALGenerateStringKink (REAL8TimeSeries **hplus, REAL8TimeSeries **hcross, REAL8 amplitude, REAL8 f_high, REAL8 delta_t)
	Generates cosmic string kink waveforms. More...
int	XLALGenerateStringKinkKink (REAL8TimeSeries **hplus, REAL8TimeSeries **hcross, REAL8 amplitude, REAL8 delta_t)
	Generates cosmic string kink waveforms. More...
int	XLALSimBurstCherenkovRadiation (REAL8TimeSeries **hplus, REAL8TimeSeries **hcross, double source_length, double dE_over_dA, double deltaT)
	Generates Cherenkov like waveforms. More...
double	XLALSimBurstCherenkov_dE_dA (double power, double beta, double r)
	energy calculating function for Cherenkov burst. More...
double	XLALSimBurstSineGaussianQ (double duration, double centre_frequency)
	Compute the Q of a sine-Gaussian waveform from the duration and centre frequency. More...
double	XLALSimBurstSineGaussianDuration (double Q, double centre_frequency)
	Compute the duration of a sine-Gaussian waveform from the Q and centre frequency. More...
int	XLALSimBurstSineGaussian (REAL8TimeSeries **hplus, REAL8TimeSeries **hcross, REAL8 Q, REAL8 centre_frequency, REAL8 hrss, REAL8 eccentricity, REAL8 phase, REAL8 delta_t)
	Generate sine- and cosine-Gaussian waveforms with various polarizations and phases. More...
int	XLALSimBurstGaussian (REAL8TimeSeries **hplus, REAL8TimeSeries **hcross, REAL8 duration, REAL8 hrss, REAL8 delta_t)
	Generate Gaussian waveforms. More...
int	XLALSimBurstImg (REAL8TimeSeries **hplus, REAL8TimeSeries **hcross, REAL8Array *image, double dt, double df, double fstart, double hrss, double deltaT, gsl_rng *rng)
	Generates a burst injection with a time-frequency structure specified in an image array. More...
int	XLALSimUnicorn (REAL8TimeSeries **hplus, REAL8TimeSeries **hcross, double f_min, double f_max, double V, double hrss, double deltaT, gsl_rng *rng)
	Generates a time-frequency unicorn signal. More...
COMPLEX16	XLALMeasureHPeak (const REAL8TimeSeries *, const REAL8TimeSeries *, unsigned *)
	Return the strain of the sample with the largest magnitude. More...
REAL8	XLALMeasureIntS1S2DT (const REAL8TimeSeries *, const REAL8TimeSeries *)
	Computes the integral of the product of two time series. More...
REAL8	XLALMeasureHrss (const REAL8TimeSeries *, const REAL8TimeSeries *)
	Computes "root-sum-square strain", or \(h_{\mathrm{rss}}\). More...
REAL8	XLALMeasureIntHDotSquaredDT (const COMPLEX16FrequencySeries *)
	Computes the integral of the square of a real-valued time series' first derivative from its Fourier transform. More...
REAL8	XLALMeasureEoverRsquared (REAL8TimeSeries *, REAL8TimeSeries *)
	Computes the areal energy density carried by a gravitational wave. More...

Function Documentation

XLALGenerateImpulseBurst()

int XLALGenerateImpulseBurst	(	REAL8TimeSeries **	hplus,
		REAL8TimeSeries **	hcross,
		REAL8	hpeak,
		REAL8	delta_t
	)

Genereates a single-sample impulse waveform.

Places a single non-zero sample into the middle of the time series. The \(h_{+}\) and \(h_{\times}\) time series both have an odd number of samples all set to 0 except for a single sample with amplitude hpeak in the middle of the \(h_{+}\) time series.

Parameters

[out]	hplus	Address of a REAL8TimeSeries pointer to be set to the address of the newly allocated \(h_{+}\) time series. Set to NULL on failure.
[out]	hcross	Address of a REAL8TimeSeries pointer to be set to the address of the newly allocated \(h_{\times}\) time series. Set to NULL on failure.
[in]	hpeak	Strain amplitude of the impulse.
[in]	delta_t	Sample period of output time series in seconds.

Return values

0	Success
<0	Failure

Definition at line 419 of file LALSimBurst.c.

XLALGenerateBandAndTimeLimitedWhiteNoiseBurst()

int XLALGenerateBandAndTimeLimitedWhiteNoiseBurst	(	REAL8TimeSeries **	hplus,
		REAL8TimeSeries **	hcross,
		REAL8	duration,
		REAL8	frequency,
		REAL8	bandwidth,
		REAL8	eccentricity,
		REAL8	phase,
		REAL8	int_hdot_squared,
		REAL8	delta_t,
		gsl_rng *	rng
	)

Generate a band- and time-limited white-noise burst waveform with Gaussian envelopes in the time and frequency domains.

Generates two time series containing \(h_{+}(t)\) and \(h_{x}(t)\), with the time-domain Gaussian envelope's peak located at \(t = 0\) (as defined by the epoch and deltaT). The \(+\) and \(\times\) time series are statistically independent.

The construction of a BTLWNB waveform with duration \(\Delta t\) and bandwidth \(\Delta f\) centred on \(f_{0}\) begins by populating a time series with independent Gaussian random numbers. The origin of the time co-ordinate corresponds to the middle sample in the time series. We apply an initial time-limiting window function to the time series by multiplying the time series with a Gaussian window function

\begin{equation} w_{1}(t) \propto \ee^{-\frac{1}{2} t^{2} / \sigma_{t}^{2}}, \end{equation}

where \(\sigma_{t}\) sets the duration of the window. The windowed time series is then Fourier transformed and a second Gaussian window applied in the frequency domain

\begin{equation} \tilde{w}_{2}(f) \propto \ee^{-\frac{1}{2} (f - f_{0})^{2} / \sigma_{f}^{2}}, \end{equation}

where \(\sigma_{f} = \frac{1}{2} \Delta f\).

Since the inital time series is real-valued, the negative frequency components of the Fourier transform are the complex conjugates of the positive frequency components and need not be stored. The frequency-domain filter is real-valued (phase preserving), and so when the positive frequency components are the only ones being stored applying the window function to them alone achieves the correct result.

The multiplication of the frequency domain data by the window function is equivalent to convolving the time domain data with the Fourier transform of the window. Since the Fourier transform of the frequency window is not a \(\delta\) function, the application of the band-limiting window has the effect of spreading the signal in the time domain, i.e. increasing its duration. We can compensate for this by choosing an appropriate value for \(\sigma_{t}\) so that the waveform has the correct duration after application of the frequency domain window. The inverse Fourier transform of \(\tilde{w}_{2}(f)\) is

\begin{equation} w_{2}(t) \propto \ee^{-2 \pi^{2} \sigma_{f}^{2} t^{2}}. \end{equation}

The result of convolving two Gaussians with one another is another Gaussian, so the effective time-domain window is

\begin{equation} w(t) = w_{1}(t) \otimes w_{2}(t) \propto \ee^{-\frac{1}{2} t^{2} / \sigma^{2}}, \end{equation}

where

\begin{equation} \sigma^{2} = \sigma_{t}^{2} + \frac{1}{4 \pi^{2} \sigma_{f}^{2}} = \sigma_{t}^{2} + \frac{1}{\pi^{2} \Delta f^{2}} \end{equation}

We wish this Gaussian's width to be \(\sigma = \frac{1}{2} \Delta t\), therefore

\begin{equation} \sigma_{t} = \sqrt{\frac{1}{4} \Delta t^{2} - \frac{1}{\pi^{2} \Delta f^{2}}}. \end{equation}

Note that \(\sigma_{t}\) is only real-valued when

\begin{equation} \Delta t \Delta f \geq \frac{2}{\pi}. \end{equation}

After application of the frequency domain window the data is inverse transformed to the time domain for injection into the strain data.

Details

This function produces both \(h_{+}\) and \(h_{\times}\) waveforms. These are independent waveforms constructed by applying the time series construction algorithm twice. The length of the result is \(21 \Delta t\) rounded to the nearest odd integer,

\begin{equation} L = 2 \left\lfloor \frac{1}{2} \frac{21 \Delta t}{\delta t} \right\rfloor + 1 \end{equation}

where \(\delta t\) is the sample period of the time series. The middle sample is \(t = 0\), so the first and last samples are at \(t = \pm \delta t (L - 1) / 2\). The time-domain Gaussian window is constructed with a call to XLALCreateGaussREAL8Window() with a shape parameter of

\begin{equation} \beta = \frac{(L - 1) \delta t / 2}{\sigma_{t}}. \end{equation}

The numerator transforms the normalized co-ordinate \(y \in [-1, +1]\) in the definition of the window function to \(t\). (See the LAL documentation for more information. Sample index 0 is \(y = -1\), sample index \(L - 1\) is \(y = +1\), so there are \((L - 1) / 2\) sample indexes per unit of \(y\).)

The time series is transformed to the frequency domain with a call to XLALREAL8TimeFreqFFT(), which populates the metadata of the output frequency series with the appropriate values. There are \((L + 1) / 2\) complex-valued frequency components with a bin spacing of \(\delta f = (L \delta t)^{-1}\). The frequency domain Gaussian window is constructed with a call to XLALCreateGaussREAL8Window() requesting a window with a length of \(L + 2\) (twice the length of the frequency series rounded up to the next odd integer), and a shape parameter of

\begin{equation} \beta = \frac{(L + 1) \delta f / 2}{\sigma_{f}}. \end{equation}

The numerator in the shape parameter converts the normalized co-ordinate \(y \in [-1, +1]\) in the definition of the window function to frequency. (See the LAL documentation for more information. The window has \(L + 2\) samples, sample index 0 is \(y = -1\), sample index \(L + 1\) is \(y = +1\), so there are \((L + 1) / 2\) sample indexes per unit of \(y\).) The window is created with the peak in the middle sample at index \((L + 1) / 2\), and we use XLALResizeREAL8Sequence() to extract as many samples as there are in the frequency series with the peak shifted to the correct bin. We want the peak to be at sample index \(f_{0} / \delta f\), so we extract \((L + 1) / 2\) samples starting at index \((L + 1) / 2 - \lfloor f_{0} / \delta f + 0.5 \rfloor\).

Following application of the frequency-domain window, the injection is transformed back to the time domain with a call to XLALREAL8FreqTimeFFT(). If \(\tilde{h}_{k}\) are the complex values in the frequency bins, the output time series is

\begin{equation} h_{j} = \delta f \sum_{k = 0}^{L - 1} \tilde{h}_{k} \ee^{2 \pi \aye j k / L} = \delta f \sum_{k = 0}^{L - 1} \tilde{h}_{k} \ee^{2 \pi \aye t k / (L \delta t)}, \end{equation}

where \(t = j \delta t\). Differentiating with respect to \(t\),

\begin{equation} \dot{h}_{j} = \delta f \sum_{k = 0}^{L - 1} \left( \frac{2 \pi \aye k}{L \delta t} \right) \tilde{h}_{k} \ee^{2 \pi \aye j k / L}, \end{equation}

and so

\begin{align} \sum_{j = 0}^{L - 1} \dot{h}_{j}^{2} \delta t & = \delta f^{2} \delta t \sum_{k = 0}^{L - 1} \sum_{k' = 0}^{L - 1} \left( \frac{4 \pi^{2} k k'}{L^{2} \delta t^{2}} \right) \tilde{h}_{k} \conj{\tilde{h}_{k'}} \sum_{j = 0}^{L - 1} \ee^{2 \pi \aye j (k - k') / L} \\ & = \delta f^{2} L \delta t \sum_{k = 0}^{L - 1} \left( \frac{4 \pi^{2} k^{2}}{L^{2} \delta t^{2}} \right) \magnitude{\tilde{h}_{k}}^{2} \\ & = 4 \pi^{2} \delta f \sum_{k = 0}^{L - 1} (k \delta f)^{2} \magnitude{\tilde{h}_{k}}^{2}. \end{align}

This relationship is used to normalize the injection time series. The expression on the left hand side is \(\int \dot{h}^{2} \diff t\). For both polarizations the right hand side is computed in the frequency domain following application of the Gaussian window, and the amplitudes of the frequency components scaled prior to conversion to the time domain so that \(\int (\dot{h}_{+}^{2} + \dot{h}_{\times}^{2}) \diff t\) has the desired value.

To ensure no discontinuities in the strain time series when the injection is added to it, a final Tukey window is applied to the injection in the time domain. The Tukey window is constructed with a call to XLALCreateTukeyREAL8Window() with a shape parameter of \(\beta = 0.5\) so that the tapers span a total of 50% of the time series. Because the Tukey window is flat with unit amplitude in the middle, it has no effect on the injection time series where the bulk of the energy is concentrated, and the large tapers ensure the Tukey window induces negligble spread of the injection in the frequency domain. Because the injection is normalized in the frequency domain prior to transformation to the time domain, the application of the Tukey window does bias the normalization slightly by reducing the total energy in the injection, however the Tukey window's tapers start several \(\sigma_{t}\) away from the injection's peak and so this effect is negligble.

In order that the waveforms be reproducable so that an analysis can be repeated, or the waveforms constructed multiple times for injection into the strain data from more than one instrument, it is necessary to specify how the initial time series of independent Gaussian random numbers is to be constructed. This is done by specifying the seed to be used with the random number generator. The random number generator is not specified, so the same seed may produce different injections with different versions of the code, but a seed and revision tag combination should be guaranteed to produce the same injection. Note also that changing the length of the injection time series changes the number of random numbers used to construct it, so the injection waveform also depends on the time series' sample rate. One has to be careful when constructing injection waveforms for instruments with different sample rates (e.g., LIGO and VIRGO). The injection must be constructed at the same sample rate for both instruments and then up- or down-sampled as needed when injected into each instrument's time series.

Example of the \(+\) and \(\times\) polarizations of a band- and time-limited white-noise burst injection waveforms with different degrees of freedom.

Parameters

[out]	hplus	Address of a REAL8TimeSeries pointer to be set to the address of the newly allocated \(h_{+}\) time series. Set to NULL on failure.
[out]	hcross	Address of a REAL8TimeSeries pointer to be set to the address of the newly allocated \(h_{\times}\) time series. Set to NULL on failure.
[in]	duration	Width of the Gaussian envelope in the time domain in seconds. The time domain envelope is \(\propto \exp ( -\frac{1}{2} t^{2} / \mathrm{duration}^{2} )\)
[in]	frequency	Centre frequency, \(f_{0}\), of the Gaussian envelope in the frequency domain in Hertz.
[in]	bandwidth	Width of the Gaussian envelope in the frequency domain in Hertz. The frequency domain envelope is \(\propto \exp ( -\frac{1}{2} (f - f_{0})^{2} / \mathrm{bandwidth}^{2} )\)
[in]	eccentricity	The eccentricity, \(\epsilon = \sqrt{1 - ({h_{0}}_{\times} / {h_{0}}_{+})^{2}}\), of the polarization ellipse setting the relative amplitudes of the \(h_{+}\) and \(h_{\times}\) components' Gaussian envelopes. With eccentricity = 0 the two components have equal amplitudes (circularly polarized); with eccentricity = 1 the amplitude of the \(h_{\times}\) component is 0 (linearly polarized). Note that this controls the relationship between the expected amplitudes, not the realized amplitudes.
[in]	phase	The phase, \(\phi\), of the sinusoidal oscillations that get multiplied by the Gaussian envelope. With \(\phi=0\), \(h_{+}\) is cosine-like and \(h_{\times}\) is sine-like. With \(\phi=\pi/2\), \(h_{+}\) is sine-like and \(h_{\times}\) is cosine-like.
[in]	int_hdot_squared	The output is normalized so that \(\int (\stackrel{.}{h}_{+}^{2} + \stackrel{.}{h}_{\times}^{2}) \diff t\) equals this. Note that the normalization is not on the expected amplitude of the waveform but on the realized amplitude of the waveform.
[in]	delta_t	Sample period of output time series in seconds.
[in]	rng	GSL random number generator instance. Will be used to generate normally distributed random variables to seed the \(h_{+}(t)\) and \(h_{x}(t)\) components.

Return values

0	Success
<0	Failure

Note

Because the injection is constructed with a random number generator, any changes to this function that change how random numbers are chosen will indirectly have the effect of altering the relationship between injection waveform and random number seed. For example, increasing the length of the time series will change the injection waveforms. There's nothing wrong with this, the waveforms are still correct, but if there is a need to reproduce a waveform exactly then it will be necessary to tag the code before making such changes.

The algorithm's low degree-of-freedom limit is equivalent to XLALSimBurstSineGaussian() but instead of Q and centre frequency the duration and centre frequency are the degrees of freedom, which allows the algorithm to also be evaluated in the low-frequency limit where (when eccentricity = 1) it yields output equivalent to XLALSimBurstGaussian(). If 2-degree-of-freedom waveforms or Gaussian waveforms are required, the other functions are substantially more efficient ways to generate them, but this function provides an interface that yields sine-Gaussian family waveforms that is valid in all regimes.

Definition at line 745 of file LALSimBurst.c.

XLALGenerateStringCusp()

int XLALGenerateStringCusp	(	REAL8TimeSeries **	hplus,
		REAL8TimeSeries **	hcross,
		REAL8	amplitude,
		REAL8	f_high,
		REAL8	delta_t
	)

Generates cosmic string cusp waveforms.

Generates the \(h_{+}\) and \(h_{\times}\) components of a cosmic string cusp waveform.

Parameters

[out]	hplus	Address of a REAL8TimeSeries pointer to be set to the address of the newly allocated \(h_{+}\) time series. Set to NULL on failure.
[out]	hcross	Address of a REAL8TimeSeries pointer to be set to the address of the newly allocated \(h_{\times}\) time series. Set to NULL on failure.
[in]	amplitude	Waveform's amplitude parameter, \(A\), in units of \(\mathrm{strain}\,\mathrm{s}^{-\frac{1}{3}}\).
[in]	f_high	High frequency cut-off, \(f_{\mathrm{high}}\), in Hertz.
[in]	delta_t	Sample period of output time series in seconds.

Return values

0	Success
<0	Failure

Definition at line 1520 of file LALSimBurst.c.

XLALGenerateStringKink()

int XLALGenerateStringKink	(	REAL8TimeSeries **	hplus,
		REAL8TimeSeries **	hcross,
		REAL8	amplitude,
		REAL8	f_high,
		REAL8	delta_t
	)

Generates cosmic string kink waveforms.

Generates the \(h_{+}\) and \(h_{\times}\) components of a cosmic string kink waveform.

Parameters

[out]	hplus	Address of a REAL8TimeSeries pointer to be set to the address of the newly allocated \(h_{+}\) time series. Set to NULL on failure.
[out]	hcross	Address of a REAL8TimeSeries pointer to be set to the address of the newly allocated \(h_{\times}\) time series. Set to NULL on failure.
[in]	amplitude	Waveform's amplitude parameter, \(A\), in units of \(\mathrm{strain}\,\mathrm{s}^{-\frac{1}{3}}\).
[in]	f_high	High frequency cut-off, \(f_{\mathrm{high}}\), in Hertz.
[in]	delta_t	Sample period of output time series in seconds.

Return values

0	Success
<0	Failure

Definition at line 1571 of file LALSimBurst.c.

XLALGenerateStringKinkKink()

int XLALGenerateStringKinkKink	(	REAL8TimeSeries **	hplus,
		REAL8TimeSeries **	hcross,
		REAL8	amplitude,
		REAL8	delta_t
	)

Generates cosmic string kink waveforms.

Generates the \(h_{+}\) and \(h_{\times}\) components of a cosmic string kink waveform.

Parameters

[out]	hplus	Address of a REAL8TimeSeries pointer to be set to the address of the newly allocated \(h_{+}\) time series. Set to NULL on failure.
[out]	hcross	Address of a REAL8TimeSeries pointer to be set to the address of the newly allocated \(h_{\times}\) time series. Set to NULL on failure.
[in]	amplitude	Waveform's amplitude parameter, \(A\), in units of \(\mathrm{strain}\,\mathrm{s}^{-\frac{1}{3}}\).
[in]	delta_t	Sample period of output time series in seconds.

Return values

0	Success
<0	Failure

Definition at line 1619 of file LALSimBurst.c.

XLALSimBurstCherenkovRadiation()

int XLALSimBurstCherenkovRadiation	(	REAL8TimeSeries **	hplus,
		REAL8TimeSeries **	hcross,
		double	source_length,
		double	dE_over_dA,
		double	deltaT
	)

Generates Cherenkov like waveforms.

Generates the \(h_{+}\) and \(h_{\times}\) components of a Cherenkov like waveforms. Since cherenkov radiation is linealy polirized, \(h_{\times}\) component is set to be zero.

the power spectrum of chrenkov radiation is given by the Frank-Tamm formula as follows

\begin{equation} \frac{\diff W}{\diff x\diff \omega} = \frac{e^2}{c^2}\left(1-\frac{1}{\beta^2n^2(\omega)}\right)\omega,n\beta>1 \end{equation}

\(n\beta\) represents the ratio of velocity of the source and wave speed of the medium. On the purpose to mimic the situation into gravitational Cherenkov radiation, we choose \(n\beta\) as a speed of velocity in light speed units. The refractive index of the medium is actually a function of frequency, however, it should be considered as a fixed value for the situation where the source moving in vacuum. In the end, free parameter we can choose is length of the source which limits the cut off frequency although the nyquist frequency is sufficiently lower than the calculated cut off frequency assuming the length of the source to be about 100 meters order.

Parameters

[out]	hplus	Address of a REAL8TimeSeries pointer to be set to the address of the newly allocated \(h_{+}\) time series. Set to NULL on failure.
[out]	hcross	Adress of a REAL8TimeSeries pointer to be set to the address of the newly allocated \(h_{\times}\) time series. Set to NULL on failure.
[in]	source_length	The length of the source in meters.
[in]	dE_over_dA	The waveform which is created with this arbitrary amplitude.in Joules per square metre.
[in]	deltaT	Sample period of output time series in seconds.

Return values

0	Success
<0	Failure

Definition at line 1683 of file LALSimBurst.c.

XLALSimBurstCherenkov_dE_dA()

double XLALSimBurstCherenkov_dE_dA	(	double	power,
		double	beta,
		double	r
	)

energy calculating function for Cherenkov burst.

Calculate the energy intensity for the Cherenkov burst considering that Cherenkov radiation would make cone shaped wavefront.

Parameters

[in]	power	power of the source in watts
[in]	beta	the velocity of the source in units of light speed
[in]	r	impact parameter. perpendicular distance between antenna and particle path in metres

Return values

0	Success
<0	Failure

Definition at line 1819 of file LALSimBurst.c.

XLALSimBurstSineGaussianQ()

double XLALSimBurstSineGaussianQ	(	double	duration,
		double	centre_frequency
	)

Compute the Q of a sine-Gaussian waveform from the duration and centre frequency.

The relationship is

\begin{equation} Q = 2 \pi f_{0} \Delta t. \end{equation}

The result becomes independent of duration at 0 Hz.

Parameters

[in]	duration	The duration, \(\Delta t\), of the sine-Gaussian in seconds.
[in]	centre_frequency	The centre frequency, \(f_{0}\), of the sine-Gaussian in Hertz.

Return values

Q	The \(Q\) of the sine-Gaussian.

See also: XLALSimBurstSineGaussianDuration()

Definition at line 975 of file LALSimBurst.c.

XLALSimBurstSineGaussianDuration()

double XLALSimBurstSineGaussianDuration	(	double	Q,
		double	centre_frequency
	)

Compute the duration of a sine-Gaussian waveform from the Q and centre frequency.

The relationship is

\begin{equation} Q = 2 \pi f_{0} \Delta t. \end{equation}

The relationship is undefined at 0 Hz.

Parameters

[in]	Q	The \(Q\) of the sine-Gaussian.
[in]	centre_frequency	The centre frequency, \(f_{0}\), of the sine-Gaussian in Hertz.

Return values

duration

The duration of the sine-Gaussian, \(\Delta t\), in seconds.

See also: XLALSimBurstSineGaussianQ()

Definition at line 1007 of file LALSimBurst.c.

XLALSimBurstSineGaussian()

int XLALSimBurstSineGaussian	(	REAL8TimeSeries **	hplus,
		REAL8TimeSeries **	hcross,
		REAL8	Q,
		REAL8	centre_frequency,
		REAL8	hrss,
		REAL8	eccentricity,
		REAL8	phase,
		REAL8	delta_t
	)

Generate sine- and cosine-Gaussian waveforms with various polarizations and phases.

Generates two time series, \(h_{+}\) and \(h_{\times}\), containing add-mixtures of cosine-Gaussian and sine-Gaussian waveforms. The Gaussian envelope peaks in both at t = 0 as defined by epoch and deltaT. By setting the eccentricity and phase to appropriate values any linearly, elliptically, or cicularly polarized sine- or cosine-Gaussian waveform can be generated. The dominant polarization is placed in the \(h_{+}\) component.

A Tukey window is applied to make the waveform go to 0 smoothly at the start and end.

Sine-Gaussian examples.

Parameters

[out]	hplus	Address of a REAL8TimeSeries pointer to be set to the address of the newly allocated \(h_{+}\) time series. Set to NULL on failure.
[out]	hcross	Address of a REAL8TimeSeries pointer to be set to the address of the newly allocated \(h_{\times}\) time series. Set to NULL on failure.
[in]	Q	The "Q" of the waveform. The Gaussian envelope is \(\propto \exp(-\frac{1}{2} t^{2} / \sigma_{t}^{2})\) where \(\sigma_{t} = Q / (2 \pi f)\). See also XLALSimBurstSineGaussianQ() and XLALSimBurstSineGaussianDuration().
[in]	centre_frequency	The frequency of the sinusoidal oscillations that get multiplied by the Gaussian envelope.
[in]	hrss	The \(h_{\mathrm{rss}}\) of the waveform to be generated. See K. Riles, LIGO-T040055-00.pdf. This function normalizes the waveform algebraically assuming it to be an ideal sine-Gaussian (continuous in time, with no time boundaries and no tapering window), so the actual numerical normalization might be slightly different. See also XLALMeasureHrss().
[in]	eccentricity	The eccentricity, \(\epsilon = \sqrt{1 - ({h_{0}}_{\times} / {h_{0}}_{+})^{2}}\), of the polarization ellipse setting the relative amplitudes of the \(h_{+}\) and \(h_{\times}\) components' Gaussian envelopes. With eccentricity = 0 the two components have equal amplitudes (circularly polarized); with eccentricity = 1 the amplitude of the \(h_{\times}\) component is 0 (linearly polarized).
[in]	phase	The phase, \(\phi\), of the sinusoidal oscillations that get multiplied by the Gaussian envelope. With \(\phi=0\), \(h_{+}\) is cosine-like and \(h_{\times}\) is sine-like. With \(\phi=\pi/2\), \(h_{+}\) is sine-like and \(h_{\times}\) is cosine-like.
[in]	delta_t	Sample period of output time series in seconds.

Return values

0	Success
<0	Failure

Definition at line 1080 of file LALSimBurst.c.

XLALSimBurstGaussian()

int XLALSimBurstGaussian	(	REAL8TimeSeries **	hplus,
		REAL8TimeSeries **	hcross,
		REAL8	duration,
		REAL8	hrss,
		REAL8	delta_t
	)

Generate Gaussian waveforms.

The burst working group has traditionally treated these as a distinct class of waveform rather than, say, the low-frequency limit of the sine-Gaussian class of waveform. Therefore, for convenience, a separate interface is provided to generate these waveforms.

Generates two time series, \(h_{+}\) and \(h_{\times}\), containing a Gaussian in \(h_{+}\). \(h_{\times}\) is set to 0. The Gaussian peaks at t = 0 as defined by epoch and deltaT. The degrees of freedom are the duration and the \(h_{\mathrm{rss}}\). The function is

\begin{equation} h_{+}(t) = \frac{h_{\mathrm{rss}}}{\sqrt{\sqrt{\pi} \Delta t}} \exp -\frac{1}{2} \frac{t^{2}}{\Delta t^{2}}. \end{equation}

A Tukey window is applied to make the waveform go to 0 smoothly at the start and end.

Parameters

[out]	hplus	Address of a REAL8TimeSeries pointer to be set to the address of the newly allocated \(h_{+}\) time series. Set to NULL on failure.
[out]	hcross	Address of a REAL8TimeSeries pointer to be set to the address of the newly allocated \(h_{\times}\) time series. Set to NULL on failure.
[in]	duration	The width of the Gaussian, \(\Delta t\).
[in]	hrss	The \(h_{\mathrm{rss}}\) of the waveform to be generated. This function normalizes the waveform algebraically assuming it to be an ideal Gaussian (continuous in time, with no time boundaries and no tapering window), so the actual numerical normalization might be slightly different. See also XLALMeasureHrss().
[in]	delta_t	Sample period of output time series in seconds.

Return values

0	Success
<0	Failure

Definition at line 1215 of file LALSimBurst.c.

XLALSimBurstImg()

int XLALSimBurstImg	(	REAL8TimeSeries **	hplus,
		REAL8TimeSeries **	hcross,
		REAL8Array *	image,
		double	dt,
		double	df,
		double	fstart,
		double	hrss,
		double	deltaT,
		gsl_rng *	rng
	)

Generates a burst injection with a time-frequency structure specified in an image array.

Note

The image array data is ordered so that the first point corresponds to the upper-left point of the image. The number of rows in the image is given in NUMROWS = image->dimLength->data[0] and the number of columns in the image is given in NUMCOLUMNS = image->dimLength->data[1]. The data is packed in row-major order so that offset = row * NUMCOLUMNS + column.

The time-frequency volume of each pixel, dt * df, must be at least 2/pi.

Parameters

hplus	plus-polarization waveform [returned]
hcross	cross-polarization waveform [returned]
image	image array
dt	pixel time duration (s)
df	pixel frequency bandwidth (Hz)
fstart	start frequency of image (Hz)
hrss	root-sum-squared value of the waveform (s)
deltaT	sampleing interval (s)
rng	random number generator

Definition at line 26 of file LALSimBurstImg.c.

XLALSimUnicorn()

int XLALSimUnicorn	(	REAL8TimeSeries **	hplus,
		REAL8TimeSeries **	hcross,
		double	f_min,
		double	f_max,
		double	V,
		double	hrss,
		double	deltaT,
		gsl_rng *	rng
	)

Generates a time-frequency unicorn signal.

Warning

Unicorns are rare and are hard to catch.

Parameters

hplus	plus-polarization waveform [returned]
hcross	cross-polarization waveform [returned]
f_min	minimum frequency of the unicorn (Hz)
f_max	maximum frequency of the unicorn (Hz)
V	time-frequency volume of image pixels
hrss	root-sum-squared value of the waveform (s)
deltaT	sampleing interval (s)
rng	random number generator

Definition at line 139 of file LALSimUnicorn.c.

XLALMeasureHPeak()

COMPLEX16 XLALMeasureHPeak	(	const REAL8TimeSeries *	hplus,
		const REAL8TimeSeries *	hcross,
		unsigned *	index
	)

Return the strain of the sample with the largest magnitude.

The input must have non-zero length.

Parameters

[in]	hplus	A time series.
[in]	hcross	A time series. Optional. Pass NULL to disregard.
[out]	index	The index of the peak sample will be written to this address. Optional. NULL to disregard.

Returns

The strain of the sample with the largest magnitude. The \(+\) polarization amplitude is in the real component, the imaginary component contains the \(\times\) polarization's amplitude (or is 0 if hcross is not supplied).

Return values

XLAL_REAL8_FAIL_NAN

Falure.

Definition at line 113 of file LALSimBurst.c.

XLALMeasureIntS1S2DT()

REAL8 XLALMeasureIntS1S2DT	(	const REAL8TimeSeries *	s1,
		const REAL8TimeSeries *	s2
	)

Computes the integral of the product of two time series.

From two time series, \(s_{1}\) and \(s_{2}\), computes and returns

\begin{equation} \int s_{1}(t) s_{2}(t) \diff t. \end{equation}

Parameters

[in]	s1	A time series.
[in]	s2	A time series.

Returns

The integral of the product.

Return values

XLAL_REAL8_FAIL_NAN

Failure

Definition at line 164 of file LALSimBurst.c.

XLALMeasureHrss()

REAL8 XLALMeasureHrss	(	const REAL8TimeSeries *	hplus,
		const REAL8TimeSeries *	hcross
	)

Computes "root-sum-square strain", or \(h_{\mathrm{rss}}\).

In fact, this is

\begin{equation} h_{\mathrm{rss}} = \sqrt{\sum (h_{+}^{2} + h_{x}^{2}) \Delta t}, \end{equation}

(includes a factor of \(\Delta t\)), which is an approximation of the square root of the square integral, \(\sqrt{\int (h_{+}^{2} + h_{x}^{2}) \diff t}\).

The input time series must start and end at the same times and have the same sample rates.

Parameters

[in]	hplus	\(h_{+}\) time series.
[in]	hcross	\(h_{\times}\) time series.

Returns

The \(h_{\mathrm{rss}}\)

Return values

XLAL_REAL8_FAIL_NAN

Failure.

Definition at line 218 of file LALSimBurst.c.

XLALMeasureIntHDotSquaredDT()

REAL8 XLALMeasureIntHDotSquaredDT

(

const COMPLEX16FrequencySeries *

fseries

)

Computes the integral of the square of a real-valued time series' first derivative from its Fourier transform.

Given the Fourier transform of a real-valued function \(h(t)\), compute and return the integral of the square of its derivative,

\begin{equation} \int \stackrel{.}{h}^{2} \diff t. \end{equation}

The normalization factors in this function assume that XLALREAL8FreqTimeFFT() will be used to convert the frequency series to the time domain.

Parameters

[in]

fseries

The Fourier transform of a real-valued function of time. See also XLALREAL8TimeFreqFFT().

Returns

\(\int \stackrel{.}{h}^{2} \diff t\)

Return values

XLAL_REAL8_FAIL_NAN

Failure.

Definition at line 250 of file LALSimBurst.c.

XLALMeasureEoverRsquared()

REAL8 XLALMeasureEoverRsquared	(	REAL8TimeSeries *	hplus,
		REAL8TimeSeries *	hcross
	)

Computes the areal energy density carried by a gravitational wave.

The local gravitational wave flux density in the two independent polarizations, \(h_{+}(t)\) and \(h_{\times}(t)\), is [Isaacson 1968]

\begin{equation} \frac{\diff E}{\diff A \diff t} = \frac{1}{16 \pi} \frac{c^{3}}{G} \left( \dot{h}_{+}^{2} + \dot{h}_{\times}^{2} \right). \end{equation}

For a source at non-cosmological distances (distances small enough that for spheres of that radius \(A = 4 \pi r^{2}\)), the equivalent isotropic radiated energy in a gravitational wave for a source at a distance \(r\) is

\begin{equation} E = \frac{c^{3}}{4 G} r^{2} \int \left( \dot{h}_{+}^{2}(t) + \dot{h}_{\times}^{2}(t) \right) \diff t. \end{equation}

Given \(h_{+}(t)\) and \(h_{\times}(t)\) in the waveframe, this function returns

\begin{equation} \frac{E}{r^{2}} = \frac{c^{3}}{4 G} \int ( \stackrel{.}{h}_{+}^{2} + \stackrel{.}{h}_{\times}^{2} ) \diff t. \end{equation}

The input time series must start and end at the same times and have the same sample rates. The square integrals of the derivatives are evaluated in the frequency domain so this function implicitly assumes the input time series are periodic on their intervals. The calling code must ensure appropriate conditioning (e.g., tapering and padding) has been applied to the time series for this to be a good approximation. Waveforms that have been conditioned for use as software injections are almost certainly suitably conditioned for this function.

Parameters

[in]	hplus	The \(h_{+}\) time series.
[in]	hcross	The \(h_{\times}\) time series.

Returns

Energy per unit area in Joules per square metre.

Return values

XLAL_REAL8_FAIL_NAN

Falure.

Definition at line 340 of file LALSimBurst.c.