Detailed Description

Utility functions for working with Long Fourier Transforms and Time Series.

Author: Reinhard Prix, Chris Messenger

Date: 2009

Prototypes
SFTtype *	XLALSFTVectorToLFT (SFTVector *sfts, REAL8 upsampling)
	Turn the given multi-IFO SFTvectors into one long Fourier transform (LFT) over the total observation time. More...

COMPLEX8TimeSeries *	XLALSFTVectorToCOMPLEX8TimeSeries (const SFTVector *sftsIn)
	Turn the given SFTvector into one long time-series, properly dealing with gaps. More...

MultiCOMPLEX8TimeSeries *	XLALMultiSFTVectorToCOMPLEX8TimeSeries (const MultiSFTVector *multisfts)
	Turn the given multiSFTvector into multiple long COMPLEX8TimeSeries, properly dealing with gaps. More...

int	XLALReorderFFTWtoSFT (COMPLEX8Vector *X)
	Change frequency-bin order from fftw-convention to a 'SFT' ie. More...

int	XLALReorderSFTtoFFTW (COMPLEX8Vector *X)
	Change frequency-bin order from 'SFT' to fftw-convention ie. More...

int	XLALTimeShiftSFT (SFTtype *sft, REAL8 shift)
	Time-shift the given SFT by an amount of 'shift' seconds, using the frequency-domain expression \( \widetilde{y}(f) = \widetilde{x}(f) \, e^{i 2\pi\,f\,\tau} \) , which shifts \( x(t) \) into \( y(t) = x(t + \tau) \). More...

int	XLALFrequencyShiftMultiCOMPLEX8TimeSeries (MultiCOMPLEX8TimeSeries *x, const REAL8 shift)
	Multi-detector wrapper for XLALFrequencyShiftCOMPLEX8TimeSeries NOTE: this modifies the MultiCOMPLEX8Timeseries in place. More...

int	XLALFrequencyShiftCOMPLEX8TimeSeries (COMPLEX8TimeSeries *x, const REAL8 shift)
	Freq-shift the given COMPLEX8Timeseries by an amount of 'shift' Hz, using the time-domain expression y(t) = x(t) * e^(-i 2pi df t), which shifts x(f) into y(f) = x(f + df) More...

int	XLALSpinDownCorrectionMultiTS (MultiCOMPLEX8TimeSeries multiTimeSeries, const PulsarDopplerParams doppler)
	Apply a spin-down correction to the complex8 timeseries using the time-domain expression y(t) = x(t) * e^(-i 2pi sum f_k * (t-tref)^(k+1)),. More...

void	XLALDestroyMultiCOMPLEX8TimeSeries (MultiCOMPLEX8TimeSeries *multiTimes)
	Destroy a MultiCOMPLEX8TimeSeries structure. More...

MultiCOMPLEX8TimeSeries *	XLALDuplicateMultiCOMPLEX8TimeSeries (MultiCOMPLEX8TimeSeries *multiTimes)
	Duplicates a MultiCOMPLEX8TimeSeries structure. More...

COMPLEX8TimeSeries *	XLALDuplicateCOMPLEX8TimeSeries (COMPLEX8TimeSeries *ttimes)
	Duplicates a COMPLEX8TimeSeries structure. More...

int	XLALCopyMultiCOMPLEX8TimeSeries (MultiCOMPLEX8TimeSeries multiTimesOut, MultiCOMPLEX8TimeSeries multiTimesIn)
	Copies a MultiCOMPLEX8TimeSeries structure, output must be allocated of identical size as input! More...

int	XLALCopyCOMPLEX8TimeSeries (COMPLEX8TimeSeries ts_out, COMPLEX8TimeSeries ts_in)
	Copies a COMPLEX8TimeSeries structure, output must be allocated of identical size as input! More...

int	XLALCompareCOMPLEX8Vectors (VectorComparison result, const COMPLEX8Vector x, const COMPLEX8Vector y, const VectorComparison tol)
	Compare two COMPLEX8 vectors using various different comparison metrics. More...

int	XLALCompareREAL4Vectors (VectorComparison result, const REAL4Vector x, const REAL4Vector y, const VectorComparison tol)
	Compare two REAL4 vectors using various different comparison metrics. More...

int	XLALCheckVectorComparisonTolerances (const VectorComparison result, const VectorComparison tol)
	Check VectorComparison result against specified tolerances, to allow for standardized comparison and reporting. More...

int	XLALSincInterpolateCOMPLEX8TimeSeries (COMPLEX8Vector y_out, const REAL8Vector t_out, const COMPLEX8TimeSeries *ts_in, UINT4 Dterms)
	Interpolate a given regularly-spaced COMPLEX8 timeseries 'ts_in = x_in(j * dt)' onto new samples 'y_out(t_out)' using windowed Shannon sinc interpolation, windowed to (2*Dterms+1) terms, namely. More...

int	XLALSincInterpolateCOMPLEX8FrequencySeries (COMPLEX8Vector y_out, const REAL8Vector f_out, const COMPLEX8FrequencySeries *fs_in, UINT4 Dterms)
	Interpolate a given regularly-spaced COMPLEX8 frequency-series 'fs_in = x_in( k * df)' onto new samples 'y_out(f_out)' using (complex) Sinc interpolation (obtained from Dirichlet kernel in large-N limit), truncated to (2*Dterms+1) terms, namely. More...

SFTtype *	XLALSincInterpolateSFT (const SFTtype *sft_in, REAL8 f0Out, REAL8 dfOut, UINT4 numBinsOut, UINT4 Dterms)
	(Complex)Sinc-interpolate an input SFT to an output SFT. More...

COMPLEX8Vector *	XLALrefineCOMPLEX8Vector (const COMPLEX8Vector *in, UINT4 refineby, UINT4 Dterms)
	Interpolate frequency-series to newLen frequency-bins. More...

Data Structures
struct	MultiCOMPLEX8TimeSeries
	Multi-IFO container for COMPLEX8 resampled timeseries. More...

struct	VectorComparison
	Struct holding the results of comparing two floating-point vectors (real-valued or complex), using various different comparison metrics. More...

Macros
#define	NhalfPosDC(N) ( (UINT4)( N / 2 ) + 1 )

#define	NhalfNeg(N) ( (N) - NhalfPosDC(N) ) /* making sure NhalfPosDC(N) + NhalfNeg(N) = N */

Function Documentation

◆ XLALSFTVectorToLFT()

SFTtype * XLALSFTVectorToLFT	(	SFTVector *	sfts,
		REAL8	upsampling
	)

Turn the given multi-IFO SFTvectors into one long Fourier transform (LFT) over the total observation time.

Parameters

sfts	input SFT vector (gets modified!)
upsampling	upsampling factor >= 1

Definition at line 64 of file LFTandTSutils.c.

◆ XLALSFTVectorToCOMPLEX8TimeSeries()

COMPLEX8TimeSeries * XLALSFTVectorToCOMPLEX8TimeSeries ( const SFTVector * sftsIn )

Turn the given SFTvector into one long time-series, properly dealing with gaps.

Parameters

[in] sftsIn SFT vector

Definition at line 146 of file LFTandTSutils.c.

◆ XLALMultiSFTVectorToCOMPLEX8TimeSeries()

MultiCOMPLEX8TimeSeries * XLALMultiSFTVectorToCOMPLEX8TimeSeries ( const MultiSFTVector * multisfts )

Turn the given multiSFTvector into multiple long COMPLEX8TimeSeries, properly dealing with gaps.

Memory allocation for the output MultiCOMPLEX8TimeSeries is done within this function.

Parameters

[in] multisfts multi SFT vector

Definition at line 266 of file LFTandTSutils.c.

◆ XLALReorderFFTWtoSFT()

int XLALReorderFFTWtoSFT ( COMPLEX8Vector * X )

Change frequency-bin order from fftw-convention to a 'SFT' ie.

from FFTW: f[0], f[1],...f[N/2], f[-(N-1)/2], ... f[-2], f[-1] to: f[-(N-1)/2], ... f[-1], f[0], f[1], .... f[N/2]

Definition at line 296 of file LFTandTSutils.c.

◆ XLALReorderSFTtoFFTW()

int XLALReorderSFTtoFFTW ( COMPLEX8Vector * X )

Change frequency-bin order from 'SFT' to fftw-convention ie.

from f[-(N-1)/2], ... f[-1], f[0], f[1], .... f[N/2] to FFTW: f[0], f[1],...f[N/2], f[-(N-1)/2], ... f[-2], f[-1]

Definition at line 327 of file LFTandTSutils.c.

◆ XLALTimeShiftSFT()

int XLALTimeShiftSFT	(	SFTtype *	sft,
		REAL8	shift
	)

Time-shift the given SFT by an amount of 'shift' seconds, using the frequency-domain expression \( \widetilde{y}(f) = \widetilde{x}(f) \, e^{i 2\pi\,f\,\tau} \) , which shifts \( x(t) \) into \( y(t) = x(t + \tau) \).

NOTE: this modifies the SFT in place

Parameters

sft	[in/out] SFT to time-shift
shift	time-shift \( \tau \) in seconds

Definition at line 362 of file LFTandTSutils.c.

◆ XLALFrequencyShiftMultiCOMPLEX8TimeSeries()

int XLALFrequencyShiftMultiCOMPLEX8TimeSeries	(	MultiCOMPLEX8TimeSeries *	x,
		const REAL8	shift
	)

Multi-detector wrapper for XLALFrequencyShiftCOMPLEX8TimeSeries NOTE: this modifies the MultiCOMPLEX8Timeseries in place.

Parameters

	x	[in/out] timeseries to time-shift
[in]	shift	freq-shift in Hz

Definition at line 395 of file LFTandTSutils.c.

◆ XLALFrequencyShiftCOMPLEX8TimeSeries()

int XLALFrequencyShiftCOMPLEX8TimeSeries	(	COMPLEX8TimeSeries *	x,
		const REAL8	shift
	)

Freq-shift the given COMPLEX8Timeseries by an amount of 'shift' Hz, using the time-domain expression y(t) = x(t) * e^(-i 2pi df t), which shifts x(f) into y(f) = x(f + df)

NOTE: this modifies the COMPLEX8TimeSeries in place

Parameters

	x	[in/out] timeseries to time-shift
[in]	shift	freq-shift in Hz

Definition at line 425 of file LFTandTSutils.c.

◆ XLALSpinDownCorrectionMultiTS()

int XLALSpinDownCorrectionMultiTS	(	MultiCOMPLEX8TimeSeries *	multiTimeSeries,
		const PulsarDopplerParams *	doppler
	)

Apply a spin-down correction to the complex8 timeseries using the time-domain expression y(t) = x(t) * e^(-i 2pi sum f_k * (t-tref)^(k+1)),.

NOTE: this modifies the input COMPLEX8TimeSeries in place

Parameters

multiTimeSeries	[in/out] timeseries to time-shift
doppler	parameter-space point to correct for

Definition at line 467 of file LFTandTSutils.c.

◆ XLALDestroyMultiCOMPLEX8TimeSeries()

void XLALDestroyMultiCOMPLEX8TimeSeries ( MultiCOMPLEX8TimeSeries * multiTimes )

Destroy a MultiCOMPLEX8TimeSeries structure.

Note, this is "NULL-robust" in the sense that it will not crash on NULL-entries anywhere in this struct, so it can be used for failure-cleanup even on incomplete structs

Definition at line 526 of file LFTandTSutils.c.

◆ XLALDuplicateMultiCOMPLEX8TimeSeries()

MultiCOMPLEX8TimeSeries * XLALDuplicateMultiCOMPLEX8TimeSeries ( MultiCOMPLEX8TimeSeries * multiTimes )

Duplicates a MultiCOMPLEX8TimeSeries structure.

Allocates memory and copies contents.

Definition at line 551 of file LFTandTSutils.c.

◆ XLALDuplicateCOMPLEX8TimeSeries()

COMPLEX8TimeSeries * XLALDuplicateCOMPLEX8TimeSeries ( COMPLEX8TimeSeries * ttimes )

Duplicates a COMPLEX8TimeSeries structure.

Allocates memory and copies contents.

Definition at line 578 of file LFTandTSutils.c.

◆ XLALCopyMultiCOMPLEX8TimeSeries()

int XLALCopyMultiCOMPLEX8TimeSeries	(	MultiCOMPLEX8TimeSeries *	multiTimesOut,
		MultiCOMPLEX8TimeSeries *	multiTimesIn
	)

Copies a MultiCOMPLEX8TimeSeries structure, output must be allocated of identical size as input!

Definition at line 603 of file LFTandTSutils.c.

◆ XLALCopyCOMPLEX8TimeSeries()

int XLALCopyCOMPLEX8TimeSeries	(	COMPLEX8TimeSeries *	ts_out,
		COMPLEX8TimeSeries *	ts_in
	)

Copies a COMPLEX8TimeSeries structure, output must be allocated of identical size as input!

Definition at line 626 of file LFTandTSutils.c.

◆ XLALCompareCOMPLEX8Vectors()

int XLALCompareCOMPLEX8Vectors	(	VectorComparison *	result,
		const COMPLEX8Vector *	x,
		const COMPLEX8Vector *	y,
		const VectorComparison *	tol
	)

Compare two COMPLEX8 vectors using various different comparison metrics.

Parameters

[out]	result	return comparison results
[in]	x	first input vector
[in]	y	second input vector
[in]	tol	accepted tolerances on comparisons, or NULL for no check

Definition at line 653 of file LFTandTSutils.c.

◆ XLALCompareREAL4Vectors()

int XLALCompareREAL4Vectors	(	VectorComparison *	result,
		const REAL4Vector *	x,
		const REAL4Vector *	y,
		const VectorComparison *	tol
	)

Compare two REAL4 vectors using various different comparison metrics.

Parameters

[out]	result	return comparison results
[in]	x	first input vector
[in]	y	second input vector
[in]	tol	accepted tolerances on comparisons, or NULL for no check

Definition at line 738 of file LFTandTSutils.c.

◆ XLALCheckVectorComparisonTolerances()

int XLALCheckVectorComparisonTolerances	(	const VectorComparison *	result,
		const VectorComparison *	tol
	)

Check VectorComparison result against specified tolerances, to allow for standardized comparison and reporting.

Parameters

[in]	result	comparison result from XLALCompareREAL4Vectors() or XLALCompareCOMPLEX8Vectors()
[in]	tol	accepted tolerances on comparisons: if NULL=> always accept the result

Definition at line 821 of file LFTandTSutils.c.

◆ XLALSincInterpolateCOMPLEX8TimeSeries()

int XLALSincInterpolateCOMPLEX8TimeSeries	(	COMPLEX8Vector *	y_out,
		const REAL8Vector *	t_out,
		const COMPLEX8TimeSeries *	ts_in,
		UINT4	Dterms
	)

Interpolate a given regularly-spaced COMPLEX8 timeseries 'ts_in = x_in(j * dt)' onto new samples 'y_out(t_out)' using windowed Shannon sinc interpolation, windowed to (2*Dterms+1) terms, namely.

\[ \newcommand{\Dterms}{\mathrm{Dterms}} \]

\begin{equation} x(t) = \sum_{j = j^* - \Dterms}^{j^* + \Dterms} x_j \, w_j \, \frac{\sin(\pi\delta_j)}{\pi\delta_j}\,,\quad\text{with}\quad \delta_j \equiv \frac{t - t_j}{\Delta t}\,, \end{equation}

where \( j^* \equiv \mathrm{round}(t / \Delta t) \) , and where \( w_j \) is the window used (here: Hamming)

In order to implement this more efficiently, we observe that \( \sin(\pi\delta_j) = (-1)^{(j-j0)}\sin(\pi\delta_{j0}) \) for integer \( j \) , and therefore

\begin{equation} x(t) = \frac{\sin(\pi\,\delta_{j0})}{\pi} \, \sum_{j = j^* - \Dterms}^{j^* + \Dterms} (-1)^{(j-j0)}\frac{x_j \, w_j}{\delta_j}\,, \end{equation}

NOTE: Using Dterms=0 corresponds to closest-bin interpolation

NOTE2: samples outside the original timespan are returned as 0

NOTE3: we're using a Hamming window of length L = 2*Dterms + 1, which has a pass-band wiggle of delta_p ~ 0.0022, and a transition bandwidth of (4/L) * Bandwidth. You need to make sure to include sufficient effective sidebands to the input timeseries, so that the transition band can be safely ignored or 'cut out' at the end

Parameters

[out]	y_out	output series of interpolated y-values [must be same size as t_out]
[in]	t_out	output time-steps to interpolate input to
[in]	ts_in	regularly-spaced input timeseries
[in]	Dterms	window sinc kernel sum to +-Dterms around max

Definition at line 891 of file LFTandTSutils.c.

◆ XLALSincInterpolateCOMPLEX8FrequencySeries()

int XLALSincInterpolateCOMPLEX8FrequencySeries	(	COMPLEX8Vector *	y_out,
		const REAL8Vector *	f_out,
		const COMPLEX8FrequencySeries *	fs_in,
		UINT4	Dterms
	)

Interpolate a given regularly-spaced COMPLEX8 frequency-series 'fs_in = x_in( k * df)' onto new samples 'y_out(f_out)' using (complex) Sinc interpolation (obtained from Dirichlet kernel in large-N limit), truncated to (2*Dterms+1) terms, namely.

\begin{equation} \widetilde{x}(f) = \sum_{k = k^* - \Delta k}^{k^* + \Delta k} \widetilde{x}_k \, \frac{ 1 - e^{-i 2\pi\,\delta_k} }{ i 2\pi\,\delta_k}\,, \end{equation}

where \( k^* \equiv \mathrm{round}(f / \Delta f) \) , and \( \delta_k \equiv \frac{f - f_k}{\Delta f} \) .

In order to implement this more efficiently, we observe that \( e^{-i 2\pi\,\delta_k} = e^{-i 2\pi\,\delta_{k*}} \) for integer \( k \) , and therefore

\begin{equation} \widetilde{x}(f) = \frac{\sin(2\pi\delta_{k*}) + i(\cos(2\pi\delta_{k*}) - 1)}{2\pi} \sum_{k = k^* - \Delta k}^{k^* + \Delta k} \frac{\widetilde{x}_k}{\delta_k}\,, \end{equation}

NOTE: Using Dterms=0 corresponds to closest-bin interpolation

NOTE2: frequencies outside the original frequency band are returned as 0

Parameters

[out]	y_out	output series of interpolated y-values [must be alloc'ed already]
[in]	f_out	output frequency-values to interpolate input to
[in]	fs_in	regularly-spaced input frequency-series
[in]	Dterms	truncate interpolation kernel sum to +-Dterms around max

Definition at line 979 of file LFTandTSutils.c.

◆ XLALSincInterpolateSFT()

SFTtype * XLALSincInterpolateSFT	(	const SFTtype *	sft_in,
		REAL8	f0Out,
		REAL8	dfOut,
		UINT4	numBinsOut,
		UINT4	Dterms
	)

(Complex)Sinc-interpolate an input SFT to an output SFT.

This is a simple convenience wrapper to XLALSincInterpolateCOMPLEX8FrequencySeries() for the special case of interpolating onto new SFT frequency bins

Parameters

[in]	sft_in	input SFT
[in]	f0Out	new start frequency
[in]	dfOut	new frequency step-size
[in]	numBinsOut	new number of bins
[in]	Dterms	truncate interpolation kernel sum to +-Dterms around max

Definition at line 1044 of file LFTandTSutils.c.

◆ XLALrefineCOMPLEX8Vector()

COMPLEX8Vector * XLALrefineCOMPLEX8Vector	(	const COMPLEX8Vector *	in,
		UINT4	refineby,
		UINT4	Dterms
	)

Interpolate frequency-series to newLen frequency-bins.

This is using DFT-interpolation (derived from zero-padding).

Definition at line 1083 of file LFTandTSutils.c.

Macro Definition Documentation

◆ NhalfPosDC

#define NhalfPosDC ( N ) ( (UINT4)( N / 2 ) + 1 )

Definition at line 46 of file LFTandTSutils.h.

◆ NhalfNeg

#define NhalfNeg ( N ) ( (N) - NhalfPosDC(N) ) /* making sure NhalfPosDC(N) + NhalfNeg(N) = N */

Definition at line 47 of file LFTandTSutils.h.

Detailed Description

Prototypes

Data Structures

Macros

Function Documentation

◆ XLALSFTVectorToLFT()

◆ XLALSFTVectorToCOMPLEX8TimeSeries()

◆ XLALMultiSFTVectorToCOMPLEX8TimeSeries()

◆ XLALReorderFFTWtoSFT()

◆ XLALReorderSFTtoFFTW()

◆ XLALTimeShiftSFT()

◆ XLALFrequencyShiftMultiCOMPLEX8TimeSeries()

◆ XLALFrequencyShiftCOMPLEX8TimeSeries()

◆ XLALSpinDownCorrectionMultiTS()

◆ XLALDestroyMultiCOMPLEX8TimeSeries()

◆ XLALDuplicateMultiCOMPLEX8TimeSeries()

◆ XLALDuplicateCOMPLEX8TimeSeries()

◆ XLALCopyMultiCOMPLEX8TimeSeries()

◆ XLALCopyCOMPLEX8TimeSeries()

◆ XLALCompareCOMPLEX8Vectors()

◆ XLALCompareREAL4Vectors()

◆ XLALCheckVectorComparisonTolerances()

◆ XLALSincInterpolateCOMPLEX8TimeSeries()

◆ XLALSincInterpolateCOMPLEX8FrequencySeries()

◆ XLALSincInterpolateSFT()

◆ XLALrefineCOMPLEX8Vector()

Macro Definition Documentation

◆ NhalfPosDC

◆ NhalfNeg