Detailed Description

Routines for building and updating the space of partial Hough map derivatives and related functions needed for the construction of total Hough maps at different frequencies and possible residual spin down parameters.

Author: Alicia Sintes, Badri Krishnan

Synopsis

#include <lal/LALHough.h>

As we mention before, the issue is to build histograms, the Hough map (HM), in the parameter space: for each intrinsic frequency \( f_0 \) , each residual spin-down parameter, and each refined sky location inside the patch. Notice, from the master equation, that the effect of the residual spin-down parameter is just a change in \( F_0 \) , and, at any given time, \( F_0 \) can be considered constant. Also, the Hough map is a histogram, thus additive. It can be seen as the sum of several partial Hough maps constructed using just one periodogram.

Therefore, we can construct the HM for any \( f_0 \) and spin-down value by adding together, at different times, partial Hough maps (PHM) corresponding to different \( F_0 \) values (or equivalently, adding their derivatives and then integrating the result).

In practice this means that in order to obtain the HM for a given frequency and all possible residual spin-down parameters, we have to construct a CYLINDER of around the frequency \( f_0 \) . All of the phmd coming from data demodulated with the same parameters. The coordinates of the phmd locate the position of the source in the sky, and by summing along different directions inside the cylinder we refine the spin-down value. To analyze another frequency, for all possible spin-down parameters, we just need to add a new line to the cylinder (and remove another one, in a circular buffer) and then proceed making all the possible sums again.

For the case of only 1 spin-down parameter we have to sum following straight lines whose slope is related to the grid in the residual spin-down parameter. We can distinguish (at most) as many lines as the number of the different periodograms used.

Prototypes
void	LALHOUGHConstructSpacePHMD (LALStatus status, PHMDVectorSequence phmdVS, HOUGHPeakGramVector pgV, HOUGHptfLUTVector lutV)
	constructs the space of `phmd` `PHMDVectorSequence phmdVS`, given a HOUGHPeakGramVector pgV and HOUGHptfLUTVector *lutV. More...

void	LALHOUGHupdateSpacePHMDup (LALStatus status, PHMDVectorSequence phmdVS, HOUGHPeakGramVector pgV, HOUGHptfLUTVector lutV)
	This function updates the space of `phmd` increasing the frequency `phmdVS->fBinMin` by one. More...

void	LALHOUGHupdateSpacePHMDdn (LALStatus status, PHMDVectorSequence phmdVS, HOUGHPeakGramVector pgV, HOUGHptfLUTVector lutV)
	Function for shifting the cylindrical buffer of PHMDs down by one frequency bin – the highest frequency bin is dropped and an extra frequency bin is added at the lowest frequency. More...

void	LALHOUGHConstructHMT (LALStatus status, HOUGHMapTotal ht, UINT8FrequencyIndexVector freqInd, PHMDVectorSequence phmdVS)
	Given PHMDVectorSequence phmdVS, the space of `phmd`, and UINT8FrequencyIndexVector freqInd, a structure containing the frequency indices of the `phmd` at different time stamps that have to be combined to form a Hough map, the function LALHOUGHConstructHMT() produces the total Hough map. More...

void	LALHOUGHComputeFBinMap (LALStatus status, UINT8 fBinMap, UINT8 f0Bin, HOUGHResidualSpinPar rs)
	This function computes the corresponding frequency bin of a `phmd` `UINT8 fBinMap` for a given intrinsic frequency bin of a source `UINT8 f0Bin`, and information regarding the time and the residual spin down parameters HOUGHResidualSpinPar *rs. More...

void	LALHOUGHConstructHMT_W (LALStatus status, HOUGHMapTotal ht, UINT8FrequencyIndexVector freqInd, PHMDVectorSequence phmdVS)
	Calculates the total hough map for a given trajectory in the time-frequency plane and a set of partial hough map derivatives allowing each PHMD to have a different weight factor to account for varying sensitivity at different sky-locations. More...

void	LALHOUGHWeighSpacePHMD (LALStatus status, PHMDVectorSequence phmdVS, REAL8Vector *weightV)
	Adds weight factors for set of partial hough map derivatives – the weights must be calculated outside this function. More...

void	LALHOUGHInitializeWeights (LALStatus status, REAL8Vector weightV)
	Initializes weight factors to unity. More...

void	LALHOUGHNormalizeWeights (LALStatus status, REAL8Vector weightV)
	Normalizes weight factors so that their sum is N. More...

void	LALHOUGHComputeAMWeights (LALStatus status, REAL8Vector weightV, LIGOTimeGPSVector timeV, LALDetector detector, EphemerisData *edat, REAL8 alpha, REAL8 delta)
	Computes weight factors arising from amplitude modulation – it multiplies an existing weight vector. More...

void	LALHOUGHComputeMultiIFOAMWeights (LALStatus status, REAL8Vector weightV, SFTCatalog catalog, EphemerisData edat, REAL8 UNUSED alpha, REAL8 UNUSED delta)
	Computes weight factors arising from amplitude modulation – it multiplies an existing weight vector. More...

static void	LALComputeAM (LALStatus status, AMCoeffs coe, LIGOTimeGPS ts, AMCoeffsParams params)
	Original antenna-pattern function by S Berukoff. More...

void	LALHOUGHComputeMultiIFOAMWeights (LALStatus status, REAL8Vector weightV, SFTCatalog catalog, EphemerisData edat, REAL8 alpha, REAL8 delta)

Data Structures
struct	UINT8FrequencyIndexVector
	This structure stores the frequency indexes of the partial-Hough map derivatives at different time stamps that have to be combined to form a Hough map for a given (null or) residual spin-down parameters. More...

struct	UINT8FrequencyIndexVectorSequence
	This structure stores a set of frequency-index vectors. More...

struct	HOUGHPeakGramVector
	This structure contains a vector of peak-grams (for the different time stamps) More...

struct	HOUGHptfLUTVector
	This structure contains a vector of partial look up tables (for the different time stamps) More...

struct	HOUGHMapTotalVector
	This structure contains a vector of Hough maps. More...

struct	PHMDVectorSequence
	This structure contains a vector sequence of partial-Hough maps derivatives (for different time stamps and different frequencies) representing a circular buffer for the frequency indexes. More...

struct	HOUGHResidualSpinPar
	This structure stores the residual spin-down parameters at a given time. More...

Files
file	DriveHoughTest.c
	Tests the construction.

file	DriveNDHoughTest.c
	Tests the construction.

Error Codes
#define	LALHOUGHH_ENULL 1

#define	LALHOUGHH_ESIZE 2

#define	LALHOUGHH_ESZMM 4

#define	LALHOUGHH_EINT 6

#define	LALHOUGHH_ESAME 8

#define	LALHOUGHH_EFREQ 10

#define	LALHOUGHH_EVAL 12

#define	LALHOUGHH_EMEM 32

#define	LALHOUGHH_MSGENULL "Null pointer"

#define	LALHOUGHH_MSGESIZE "Invalid input size"

#define	LALHOUGHH_MSGESZMM "Size mismatch"

#define	LALHOUGHH_MSGEINT "Invalid interval"

#define	LALHOUGHH_MSGESAME "Input/Output pointers are the same"

#define	LALHOUGHH_MSGEFREQ "Invalid frequency"

#define	LALHOUGHH_MSGEVAL "Invalid value"

#define	LALHOUGHH_MSGEMEM "malloc() failed / Out of memory"

Function Documentation

◆ LALHOUGHConstructSpacePHMD()

void LALHOUGHConstructSpacePHMD	(	LALStatus *	status,
		PHMDVectorSequence *	phmdVS,
		HOUGHPeakGramVector *	pgV,
		HOUGHptfLUTVector *	lutV
	)

constructs the space of phmd PHMDVectorSequence *phmdVS, given a HOUGHPeakGramVector *pgV and HOUGHptfLUTVector *lutV.

The minimum frequency bin present corresponds to phmdVS->fBinMin and the total number of different frequencies is phmdVS->nfSize. At this moment the fBinMin line corresponds to the first row of the cylinder and phmdVS->breakLine is set to zero. phmdVS->breakLine \( \in\, [0, \) nfSize) is the pointer which identifies the position of the fBinMin row in the circular-cylinder buffer.

Parameters

status	pointer to LALStatus structure
phmdVS	Cylindrical buffer of PHMDs
pgV	Vetor of peakgrams
lutV	vector of look up tables

Definition at line 54 of file DriveHough.c.

◆ LALHOUGHupdateSpacePHMDup()

void LALHOUGHupdateSpacePHMDup	(	LALStatus *	status,
		PHMDVectorSequence *	phmdVS,
		HOUGHPeakGramVector *	pgV,
		HOUGHptfLUTVector *	lutV
	)

This function updates the space of phmd increasing the frequency phmdVS->fBinMin by one.

Definition at line 130 of file DriveHough.c.

◆ LALHOUGHupdateSpacePHMDdn()

void LALHOUGHupdateSpacePHMDdn	(	LALStatus *	status,
		PHMDVectorSequence *	phmdVS,
		HOUGHPeakGramVector *	pgV,
		HOUGHptfLUTVector *	lutV
	)

Function for shifting the cylindrical buffer of PHMDs down by one frequency bin – the highest frequency bin is dropped and an extra frequency bin is added at the lowest frequency.

Definition at line 215 of file DriveHough.c.

◆ LALHOUGHConstructHMT()

void LALHOUGHConstructHMT	(	LALStatus *	status,
		HOUGHMapTotal *	ht,
		UINT8FrequencyIndexVector *	freqInd,
		PHMDVectorSequence *	phmdVS
	)

Given PHMDVectorSequence *phmdVS, the space of phmd, and UINT8FrequencyIndexVector *freqInd, a structure containing the frequency indices of the phmd at different time stamps that have to be combined to form a Hough map, the function LALHOUGHConstructHMT() produces the total Hough map.

Parameters

status	pointer to LALStatus structure
ht	The output hough map
freqInd	time-frequency trajectory
phmdVS	set of partial hough map derivatives

Definition at line 301 of file DriveHough.c.

◆ LALHOUGHComputeFBinMap()

void LALHOUGHComputeFBinMap	(	LALStatus *	status,
		UINT8 *	fBinMap,
		UINT8 *	f0Bin,
		HOUGHResidualSpinPar *	rs
	)

This function computes the corresponding frequency bin of a phmd UINT8 *fBinMap for a given intrinsic frequency bin of a source UINT8 *f0Bin, and information regarding the time and the residual spin down parameters HOUGHResidualSpinPar *rs.

Definition at line 408 of file DriveHough.c.

◆ LALHOUGHConstructHMT_W()

void LALHOUGHConstructHMT_W	(	LALStatus *	status,
		HOUGHMapTotal *	ht,
		UINT8FrequencyIndexVector *	freqInd,
		PHMDVectorSequence *	phmdVS
	)

Calculates the total hough map for a given trajectory in the time-frequency plane and a set of partial hough map derivatives allowing each PHMD to have a different weight factor to account for varying sensitivity at different sky-locations.

Parameters

status	pointer to LALStatus structure
ht	The output hough map
freqInd	time-frequency trajectory
phmdVS	set of partial hough map derivatives

Definition at line 474 of file DriveHough.c.

◆ LALHOUGHWeighSpacePHMD()

void LALHOUGHWeighSpacePHMD	(	LALStatus *	status,
		PHMDVectorSequence *	phmdVS,
		REAL8Vector *	weightV
	)

Adds weight factors for set of partial hough map derivatives – the weights must be calculated outside this function.

Parameters

status	pointer to LALStatus structure
phmdVS	partial hough map derivatives
weightV	vector of weights

Definition at line 580 of file DriveHough.c.

◆ LALHOUGHInitializeWeights()

void LALHOUGHInitializeWeights	(	LALStatus *	status,
		REAL8Vector *	weightV
	)

Initializes weight factors to unity.

Parameters

status	pointer to LALStatus structure
weightV	vector of weights

Definition at line 633 of file DriveHough.c.

◆ LALHOUGHNormalizeWeights()

void LALHOUGHNormalizeWeights	(	LALStatus *	status,
		REAL8Vector *	weightV
	)

Normalizes weight factors so that their sum is N.

Parameters

status	pointer to LALStatus structure
weightV	vector of weights

Definition at line 668 of file DriveHough.c.

◆ LALHOUGHComputeAMWeights()

void LALHOUGHComputeAMWeights	(	LALStatus *	status,
		REAL8Vector *	weightV,
		LIGOTimeGPSVector *	timeV,
		LALDetector *	detector,
		EphemerisData *	edat,
		REAL8	alpha,
		REAL8	delta
	)

Computes weight factors arising from amplitude modulation – it multiplies an existing weight vector.

Definition at line 712 of file DriveHough.c.

◆ LALHOUGHComputeMultiIFOAMWeights() [1/2]

void LALHOUGHComputeMultiIFOAMWeights	(	LALStatus *	status,
		REAL8Vector *	weightV,
		SFTCatalog *	catalog,
		EphemerisData *	edat,
		REAL8 UNUSED	alpha,
		REAL8 UNUSED	delta
	)

Computes weight factors arising from amplitude modulation – it multiplies an existing weight vector.

Definition at line 865 of file DriveHough.c.

◆ LALComputeAM()

void LALComputeAM	(	LALStatus *	status,
		AMCoeffs *	coe,
		LIGOTimeGPS *	ts,
		AMCoeffsParams *	params
	)

static

Original antenna-pattern function by S Berukoff.

Definition at line 900 of file DriveHough.c.

◆ LALHOUGHComputeMultiIFOAMWeights() [2/2]

void LALHOUGHComputeMultiIFOAMWeights	(	LALStatus *	status,
		REAL8Vector *	weightV,
		SFTCatalog *	catalog,
		EphemerisData *	edat,
		REAL8	alpha,
		REAL8	delta
	)

Macro Definition Documentation

◆ LALHOUGHH_ENULL

#define LALHOUGHH_ENULL 1

Definition at line 110 of file LALHough.h.

◆ LALHOUGHH_ESIZE

#define LALHOUGHH_ESIZE 2

Definition at line 111 of file LALHough.h.

◆ LALHOUGHH_ESZMM

#define LALHOUGHH_ESZMM 4

Definition at line 112 of file LALHough.h.

◆ LALHOUGHH_EINT

#define LALHOUGHH_EINT 6

Definition at line 113 of file LALHough.h.

◆ LALHOUGHH_ESAME

#define LALHOUGHH_ESAME 8

Definition at line 114 of file LALHough.h.

◆ LALHOUGHH_EFREQ

#define LALHOUGHH_EFREQ 10

Definition at line 115 of file LALHough.h.

◆ LALHOUGHH_EVAL

#define LALHOUGHH_EVAL 12

Definition at line 116 of file LALHough.h.

◆ LALHOUGHH_EMEM

#define LALHOUGHH_EMEM 32

Definition at line 117 of file LALHough.h.

◆ LALHOUGHH_MSGENULL

#define LALHOUGHH_MSGENULL "Null pointer"

Definition at line 119 of file LALHough.h.

◆ LALHOUGHH_MSGESIZE

#define LALHOUGHH_MSGESIZE "Invalid input size"

Definition at line 120 of file LALHough.h.

◆ LALHOUGHH_MSGESZMM

#define LALHOUGHH_MSGESZMM "Size mismatch"

Definition at line 121 of file LALHough.h.

◆ LALHOUGHH_MSGEINT

#define LALHOUGHH_MSGEINT "Invalid interval"

Definition at line 122 of file LALHough.h.

◆ LALHOUGHH_MSGESAME

#define LALHOUGHH_MSGESAME "Input/Output pointers are the same"

Definition at line 123 of file LALHough.h.

◆ LALHOUGHH_MSGEFREQ

#define LALHOUGHH_MSGEFREQ "Invalid frequency"

Definition at line 124 of file LALHough.h.

◆ LALHOUGHH_MSGEVAL

#define LALHOUGHH_MSGEVAL "Invalid value"

Definition at line 125 of file LALHough.h.

◆ LALHOUGHH_MSGEMEM

#define LALHOUGHH_MSGEMEM "malloc() failed / Out of memory"

Definition at line 126 of file LALHough.h.

Detailed Description

Synopsis

Prototypes

Data Structures

Files

Error Codes

Function Documentation

◆ LALHOUGHConstructSpacePHMD()

◆ LALHOUGHupdateSpacePHMDup()

◆ LALHOUGHupdateSpacePHMDdn()

◆ LALHOUGHConstructHMT()

◆ LALHOUGHComputeFBinMap()

◆ LALHOUGHConstructHMT_W()

◆ LALHOUGHWeighSpacePHMD()

◆ LALHOUGHInitializeWeights()

◆ LALHOUGHNormalizeWeights()

◆ LALHOUGHComputeAMWeights()

◆ LALHOUGHComputeMultiIFOAMWeights() [1/2]

◆ LALComputeAM()

◆ LALHOUGHComputeMultiIFOAMWeights() [2/2]

Macro Definition Documentation

◆ LALHOUGHH_ENULL

◆ LALHOUGHH_ESIZE

◆ LALHOUGHH_ESZMM

◆ LALHOUGHH_EINT

◆ LALHOUGHH_ESAME

◆ LALHOUGHH_EFREQ

◆ LALHOUGHH_EVAL

◆ LALHOUGHH_EMEM

◆ LALHOUGHH_MSGENULL

◆ LALHOUGHH_MSGESIZE

◆ LALHOUGHH_MSGESZMM

◆ LALHOUGHH_MSGEINT

◆ LALHOUGHH_MSGESAME

◆ LALHOUGHH_MSGEFREQ

◆ LALHOUGHH_MSGEVAL

◆ LALHOUGHH_MSGEMEM