DopplerScan.h File Reference

Author:: Reinhard Prix, Karl Wette Header file defining the API for DopplerScan.

#include <lal/LALDatatypes.h>
#include <lal/SkyCoordinates.h>
#include <lal/PtoleMetric.h>
#include <lal/StackMetric.h>
#include <lal/LALBarycenter.h>
#include <lal/PulsarDataTypes.h>
#include <lal/ComputeFstat.h>

Include dependency graph for DopplerScan.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct SkyRegion

structure describing a polygon-region in the sky More...

struct DopplerRegion

struct tagDopplerSkyGrid

sky grid More...

struct DopplerSkyScanInit

initialization-structure passed to InitDopplerSkyScan() More...

struct DopplerSkyScanState

this structure reflects the current state of a DopplerSkyScan More...

struct MetricEllipse

a "sky-ellipse", described by the two major axes and it's angle wrt x-axis More...

Defines

#define DOPPLERSCANH_ENULL   1

#define DOPPLERSCANH_ENOTREADY   2

#define DOPPLERSCANH_ESYS   3

#define DOPPLERSCANH_E2DSKY   4

#define DOPPLERSCANH_E2DSTEP   5

#define DOPPLERSCANH_EGRIDCRPT   6

#define DOPPLERSCANH_ESKYPARAM   7

#define DOPPLERSCANH_EMETRICTYPE   8

#define DOPPLERSCANH_ENONULL   9

#define DOPPLERSCANH_EMEM   10

#define DOPPLERSCANH_ESKYREGION   11

#define DOPPLERSCANH_EINPUT   12

#define DOPPLERSCANH_ENEGMETRIC   13

#define DOPPLERSCANH_EXLAL   14

#define DOPPLERSCANH_MSGENULL   "Arguments contained an unexpected null pointer"

#define DOPPLERSCANH_MSGENOTREADY   "Doppler scan is uninitialized or has finished"

#define DOPPLERSCANH_MSGESYS   "System call failed (probably file IO)"

#define DOPPLERSCANH_MSGE2DSKY   "Either need one sky-point or a polygon. (2 sky-points where given)"

#define DOPPLERSCANH_MSGE2DSTEP   "If not using the metric, you need to specify _both_ dDelta and dAlpha"

#define DOPPLERSCANH_MSGEGRIDCRPT   "Unexpected NULL in grid-list. This points to a bug in the code... "

#define DOPPLERSCANH_MSGESKYPARAM   "Invalid sky region! We need 0<= alpha < 2Pi and -Pi/2 <= delta <= PI/2"

#define DOPPLERSCANH_MSGEMETRICTYPE   "Unknown type of metric specified."

#define DOPPLERSCANH_MSGENONULL   "Output pointer is not NULL"

#define DOPPLERSCANH_MSGEMEM   "Out of memory"

#define DOPPLERSCANH_MSGESKYREGION   "Could not parse sky-region correctly"

#define DOPPLERSCANH_MSGEINPUT   "Invald input parameter"

#define DOPPLERSCANH_MSGENEGMETRIC   "Negative metric encountered"

#define DOPPLERSCANH_MSGEXLAL   "XLAL call failed"

Typedefs

typedef tagDopplerSkyGrid DopplerSkyGrid

sky grid

Enumerations

enum scan_state_t { STATE_IDLE = 0, STATE_READY, STATE_FINISHED, STATE_LAST }

Different 'states' a Doppler-scan can be in. More...

enum DopplerGridType {
  GRID_FLAT = 0, GRID_ISOTROPIC = 1, GRID_METRIC = 2, GRID_FILE_SKYGRID = 3,
  GRID_METRIC_SKYFILE = 4, GRID_SKY_LAST, GRID_FILE_FULLGRID = 6, GRID_METRIC_LATTICE = 7,
  GRID_SPINDOWN_SQUARE = 8, GRID_SPINDOWN_AGEBRK = 9, GRID_LAST
}

different types of grids: More...

Functions

NRCSID (DOPPLERSCANH,"$Id: DopplerScan.h,v 1.4 2008/07/30 10:24:10 kwwette Exp $")

void InitDopplerSkyScan (LALStatus *, DopplerSkyScanState *skyScan, const DopplerSkyScanInit *init)

Initialize the Doppler sky-scanner.

int XLALNextDopplerSkyPos (PulsarDopplerParams *pos, DopplerSkyScanState *skyScan)

NextDopplerSkyPos(): step through sky-grid return 0 = OK, -1 = ERROR.

void FreeDopplerSkyScan (LALStatus *, DopplerSkyScanState *skyScan)

Destroy the DopplerSkyScanState structure.

int XLALFreeDopplerSkyScan (DopplerSkyScanState *skyScan)

void writeSkyGridFile (LALStatus *, const DopplerSkyGrid *grid, const CHAR *fname)

Write the given sky-grid to a file.

void ParseSkyRegionString (LALStatus *, SkyRegion *region, const CHAR *input)

parse a skyRegion-string into a SkyRegion structure: the expected string-format is " (ra1, dec1), (ra2, dec2), (ra3, dec3), ... "

void SkySquare2String (LALStatus *, CHAR **string, REAL8 Alpha, REAL8 Delta, REAL8 AlphaBand, REAL8 DeltaBand)

parse a 'classical' sky-square (Alpha, Delta, AlphaBand, DeltaBand) into a "SkyRegion"-string of the form '(a1,d1), (a2,d2),.

void getMCDopplerCube (LALStatus *, DopplerRegion *cube, PulsarDopplerParams signal, UINT4 PointsPerDim, const DopplerSkyScanInit *params)

Determine a (randomized) cubic DopplerRegion around a search-point with (roughly) the given number of grid-points in each non-projected dimension.

void getMetricEllipse (LALStatus *, MetricEllipse *ellipse, REAL8 mismatch, const REAL8Vector *metric, UINT4 dim0)

get "metric-ellipse" for given metric.

int fprintfDopplerParams (FILE *fp, const PulsarDopplerParams *params)

Debug-output of PulsarDopplerParams struct.

DopplerSkyGrid * XLALEquiPartitionSkygrid (const DopplerSkyGrid *skygrid, UINT4 jPart, UINT4 numPartitions)

Equi-partition (approximately) a given skygrid into numPartitions, and return partition 0<= partitionIndex < numPartitions.

Variables

const DopplerSkyGrid empty_DopplerSkyGrid

const DopplerSkyScanState empty_DopplerSkyScanState

const DopplerSkyScanInit empty_DopplerSkyScanInit

const PulsarDopplerParams empty_PulsarDopplerParams

const DopplerRegion empty_DopplerRegion

const SkyRegion empty_SkyRegion

Detailed Description

Author:: Reinhard Prix, Karl Wette Header file defining the API for DopplerScan.

Date:: 2004, 2005, 2006, 2007, 2008

Id: DopplerScan.h,v 1.4 2008/07/30 10:24:10 kwwette Exp

Definition in file DopplerScan.h.

Define Documentation

#define DOPPLERSCANH_ENULL 1

Definition at line 51 of file DopplerScan.h.

#define DOPPLERSCANH_ENOTREADY 2

Definition at line 52 of file DopplerScan.h.

#define DOPPLERSCANH_ESYS 3

Definition at line 53 of file DopplerScan.h.

#define DOPPLERSCANH_E2DSKY 4

Definition at line 54 of file DopplerScan.h.

#define DOPPLERSCANH_E2DSTEP 5

Definition at line 55 of file DopplerScan.h.

#define DOPPLERSCANH_EGRIDCRPT 6

Definition at line 56 of file DopplerScan.h.

#define DOPPLERSCANH_ESKYPARAM 7

Definition at line 57 of file DopplerScan.h.

#define DOPPLERSCANH_EMETRICTYPE 8

Definition at line 58 of file DopplerScan.h.

#define DOPPLERSCANH_ENONULL 9

Definition at line 59 of file DopplerScan.h.

#define DOPPLERSCANH_EMEM 10

Definition at line 60 of file DopplerScan.h.

#define DOPPLERSCANH_ESKYREGION 11

Definition at line 61 of file DopplerScan.h.

#define DOPPLERSCANH_EINPUT 12

Definition at line 62 of file DopplerScan.h.

#define DOPPLERSCANH_ENEGMETRIC 13

Definition at line 63 of file DopplerScan.h.

#define DOPPLERSCANH_EXLAL 14

Definition at line 64 of file DopplerScan.h.

#define DOPPLERSCANH_MSGENULL "Arguments contained an unexpected null pointer"

Definition at line 67 of file DopplerScan.h.

#define DOPPLERSCANH_MSGENOTREADY "Doppler scan is uninitialized or has finished"

Definition at line 68 of file DopplerScan.h.

#define DOPPLERSCANH_MSGESYS "System call failed (probably file IO)"

Definition at line 69 of file DopplerScan.h.

#define DOPPLERSCANH_MSGE2DSKY "Either need one sky-point or a polygon. (2 sky-points where given)"

Definition at line 70 of file DopplerScan.h.

#define DOPPLERSCANH_MSGE2DSTEP "If not using the metric, you need to specify _both_ dDelta and dAlpha"

Definition at line 71 of file DopplerScan.h.

#define DOPPLERSCANH_MSGEGRIDCRPT "Unexpected NULL in grid-list. This points to a bug in the code... "

Definition at line 72 of file DopplerScan.h.

#define DOPPLERSCANH_MSGESKYPARAM "Invalid sky region! We need 0<= alpha < 2Pi and -Pi/2 <= delta <= PI/2"

Definition at line 73 of file DopplerScan.h.

#define DOPPLERSCANH_MSGEMETRICTYPE "Unknown type of metric specified."

Definition at line 74 of file DopplerScan.h.

#define DOPPLERSCANH_MSGENONULL "Output pointer is not NULL"

Definition at line 75 of file DopplerScan.h.

#define DOPPLERSCANH_MSGEMEM "Out of memory"

Definition at line 76 of file DopplerScan.h.

#define DOPPLERSCANH_MSGESKYREGION "Could not parse sky-region correctly"

Definition at line 77 of file DopplerScan.h.

#define DOPPLERSCANH_MSGEINPUT "Invald input parameter"

Definition at line 78 of file DopplerScan.h.

#define DOPPLERSCANH_MSGENEGMETRIC "Negative metric encountered"

Definition at line 79 of file DopplerScan.h.

#define DOPPLERSCANH_MSGEXLAL "XLAL call failed"

Definition at line 80 of file DopplerScan.h.

Typedef Documentation

typedef struct tagDopplerSkyGrid DopplerSkyGrid

sky grid

Enumeration Type Documentation

enum scan_state_t

Different 'states' a Doppler-scan can be in.

Enumerator:

STATE_IDLE	not initialized yet
STATE_READY	initialized and ready
STATE_FINISHED	all templates have been read
STATE_LAST

Definition at line 85 of file DopplerScan.h.

enum DopplerGridType

different types of grids:

Enumerator:

GRID_FLAT	"flat" sky-grid: fixed step-size (dAlpha,dDelta)
GRID_ISOTROPIC	approximately isotropic sky-grid
GRID_METRIC	generate grid using a 2D sky-metric
GRID_FILE_SKYGRID	read skygrid from a file
GRID_METRIC_SKYFILE	'hybrid' grid-construction: use skygrid from file, metric for others
GRID_SKY_LAST	end-marker for factored grid types
GRID_FILE_FULLGRID	load the full D-dim grid from a file
GRID_METRIC_LATTICE	'optimal' covering using An*-lattice and flat metric
GRID_SPINDOWN_SQUARE	spindown tiling for a single sky position and square parameter space
GRID_SPINDOWN_AGEBRK	spindown tiling for a single sky position and non-square parameter space defined by spindown age and braking indices
GRID_LAST

Definition at line 93 of file DopplerScan.h.

Function Documentation

NRCSID	(	DOPPLERSCANH	,
		"$Id: DopplerScan.	h,
		v 1.4 2008/07/30 10:24:10 kwwette Exp $"
	)

void InitDopplerSkyScan	(	LALStatus *	,
		DopplerSkyScanState *	skyScan,
		const DopplerSkyScanInit *	init
	)

Initialize the Doppler sky-scanner.

Parameters:

skyScan	[out] the initialized scan-structure
init	[in] init-params

Definition at line 189 of file DopplerScan.c.

int XLALNextDopplerSkyPos	(	PulsarDopplerParams *	pos,
		DopplerSkyScanState *	skyScan
	)

NextDopplerSkyPos(): step through sky-grid return 0 = OK, -1 = ERROR.

Definition at line 144 of file DopplerScan.c.

void FreeDopplerSkyScan	(	LALStatus *	,
		DopplerSkyScanState *	skyScan
	)

Destroy the DopplerSkyScanState structure.

Definition at line 330 of file DopplerScan.c.

int XLALFreeDopplerSkyScan ( DopplerSkyScanState * skyScan )

void writeSkyGridFile	(	LALStatus *	status,
		const DopplerSkyGrid *	skyGrid,
		const CHAR *	fname
	)

Write the given sky-grid to a file.

Possibly including some comments containing the parameters of the grid (?).

Definition at line 1122 of file DopplerScan.c.

void ParseSkyRegionString	(	LALStatus *	status,
		SkyRegion *	region,
		const CHAR *	input
	)

parse a skyRegion-string into a SkyRegion structure: the expected string-format is " (ra1, dec1), (ra2, dec2), (ra3, dec3), ... "

If input == NULL or input == "allsky":==> sky-region covering the whole sky.

Definition at line 1323 of file DopplerScan.c.

void SkySquare2String	(	LALStatus *	status,
		CHAR **	string,
		REAL8	Alpha,
		REAL8	Delta,
		REAL8	AlphaBand,
		REAL8	DeltaBand
	)

parse a 'classical' sky-square (Alpha, Delta, AlphaBand, DeltaBand) into a "SkyRegion"-string of the form '(a1,d1), (a2,d2),.

..'

Parameters:

string	OUT: skyRegion string
Alpha	longitude of first point
Delta	latitude of first point
AlphaBand	longitude-interval
DeltaBand	latitude-interval

Definition at line 1410 of file DopplerScan.c.

void getMCDopplerCube	(	LALStatus *	status,
		DopplerRegion *	cube,
		PulsarDopplerParams	signal,
		UINT4	PointsPerDim,
		const DopplerSkyScanInit *	params
	)

Determine a (randomized) cubic DopplerRegion around a search-point with (roughly) the given number of grid-points in each non-projected dimension.

Motivation: mainly useful for MC tests of the search-grid. For this we need to simulate a 'small' search-grid around the signal-location.

This function tries to estimate a region in parameter-space with roughly the given number of grid-points in each non-projected dimension.

NOTE: if the frequency has been projected, we need to search the *whole* possible Doppler-range of frequencies, in which the signal can show up. This range is bounded by (from circle-equation) |FreqBand/Freq| < beta_orb Delta_n, where beta_orb = V_orb/c ~1e-4, and Delta_n = |{n} - {n}_sig| can be estimated from the metric sky-ellipses: Delta_n ~ smajor of the sky-ellipse

The region will be randomized wrt the central point within one grid-spacing in order to avoid systematic effects in MC simulations.

PointsPerDim == 0: trivial search-region consisting just of the signal-location ( no randomization! ) PointsPerDim == 1: DopplerRegion is only one point (randomized within one cell)

Parameters:

cube	OUT: 'cube' around signal-position
signal	signal-position: approximate cube-center
PointsPerDim	desired number of grid-points per dim.
params	search+metric parameters

Definition at line 1590 of file DopplerScan.c.

void getMetricEllipse	(	LALStatus *	status,
		MetricEllipse *	ellipse,
		REAL8	mismatch,
		const REAL8Vector *	metric,
		UINT4	dim0
	)

get "metric-ellipse" for given metric.

Note:: This function uses only 2 dimensions starting from dim0 of the given metric!

Definition at line 1705 of file DopplerScan.c.

int fprintfDopplerParams	(	FILE *	fp,
		const PulsarDopplerParams *	params
	)

Debug-output of PulsarDopplerParams struct.

Definition at line 1748 of file DopplerScan.c.

DopplerSkyGrid* XLALEquiPartitionSkygrid	(	const DopplerSkyGrid *	skygrid,
		UINT4	jPart,
		UINT4	numPartitions
	)

Equi-partition (approximately) a given skygrid into numPartitions, and return partition 0<= partitionIndex < numPartitions.

Definition at line 1765 of file DopplerScan.c.

Variable Documentation

const DopplerSkyGrid empty_DopplerSkyGrid

Definition at line 105 of file DopplerScan.c.

const DopplerSkyScanState empty_DopplerSkyScanState

Definition at line 106 of file DopplerScan.c.

const DopplerSkyScanInit empty_DopplerSkyScanInit

Definition at line 107 of file DopplerScan.c.

const PulsarDopplerParams empty_PulsarDopplerParams

Definition at line 48 of file PulsarDataTypes.c.

const DopplerRegion empty_DopplerRegion

Definition at line 108 of file DopplerScan.c.

const SkyRegion empty_SkyRegion

Definition at line 109 of file DopplerScan.c.

Generated on Tue Oct 7 02:40:56 2008 for LAL by

1.5.2


Data Structures
struct	SkyRegion
	structure describing a polygon-region in the sky More...
struct	DopplerRegion
struct	tagDopplerSkyGrid
	sky grid More...
struct	DopplerSkyScanInit
	initialization-structure passed to InitDopplerSkyScan() More...
struct	DopplerSkyScanState
	this structure reflects the current state of a DopplerSkyScan More...
struct	MetricEllipse
	a "sky-ellipse", described by the two major axes and it's angle wrt x-axis More...
Defines
#define	DOPPLERSCANH_ENULL 1
#define	DOPPLERSCANH_ENOTREADY 2
#define	DOPPLERSCANH_ESYS 3
#define	DOPPLERSCANH_E2DSKY 4
#define	DOPPLERSCANH_E2DSTEP 5
#define	DOPPLERSCANH_EGRIDCRPT 6
#define	DOPPLERSCANH_ESKYPARAM 7
#define	DOPPLERSCANH_EMETRICTYPE 8
#define	DOPPLERSCANH_ENONULL 9
#define	DOPPLERSCANH_EMEM 10
#define	DOPPLERSCANH_ESKYREGION 11
#define	DOPPLERSCANH_EINPUT 12
#define	DOPPLERSCANH_ENEGMETRIC 13
#define	DOPPLERSCANH_EXLAL 14
#define	DOPPLERSCANH_MSGENULL "Arguments contained an unexpected null pointer"
#define	DOPPLERSCANH_MSGENOTREADY "Doppler scan is uninitialized or has finished"
#define	DOPPLERSCANH_MSGESYS "System call failed (probably file IO)"
#define	DOPPLERSCANH_MSGE2DSKY "Either need one sky-point or a polygon. (2 sky-points where given)"
#define	DOPPLERSCANH_MSGE2DSTEP "If not using the metric, you need to specify _both_ dDelta and dAlpha"
#define	DOPPLERSCANH_MSGEGRIDCRPT "Unexpected NULL in grid-list. This points to a bug in the code... "
#define	DOPPLERSCANH_MSGESKYPARAM "Invalid sky region! We need 0<= alpha < 2Pi and -Pi/2 <= delta <= PI/2"
#define	DOPPLERSCANH_MSGEMETRICTYPE "Unknown type of metric specified."
#define	DOPPLERSCANH_MSGENONULL "Output pointer is not NULL"
#define	DOPPLERSCANH_MSGEMEM "Out of memory"
#define	DOPPLERSCANH_MSGESKYREGION "Could not parse sky-region correctly"
#define	DOPPLERSCANH_MSGEINPUT "Invald input parameter"
#define	DOPPLERSCANH_MSGENEGMETRIC "Negative metric encountered"
#define	DOPPLERSCANH_MSGEXLAL "XLAL call failed"
Typedefs
typedef tagDopplerSkyGrid	DopplerSkyGrid
	sky grid
Enumerations
enum	scan_state_t { STATE_IDLE = 0, STATE_READY, STATE_FINISHED, STATE_LAST }
	Different 'states' a Doppler-scan can be in. More...
enum	DopplerGridType { GRID_FLAT = 0, GRID_ISOTROPIC = 1, GRID_METRIC = 2, GRID_FILE_SKYGRID = 3, GRID_METRIC_SKYFILE = 4, GRID_SKY_LAST, GRID_FILE_FULLGRID = 6, GRID_METRIC_LATTICE = 7, GRID_SPINDOWN_SQUARE = 8, GRID_SPINDOWN_AGEBRK = 9, GRID_LAST }
	different types of grids: More...
Functions
	NRCSID (DOPPLERSCANH,"$Id: DopplerScan.h,v 1.4 2008/07/30 10:24:10 kwwette Exp $")
void	InitDopplerSkyScan (LALStatus , DopplerSkyScanState skyScan, const DopplerSkyScanInit *init)
	Initialize the Doppler sky-scanner.
int	XLALNextDopplerSkyPos (PulsarDopplerParams pos, DopplerSkyScanState skyScan)
	NextDopplerSkyPos(): step through sky-grid return 0 = OK, -1 = ERROR.
void	FreeDopplerSkyScan (LALStatus , DopplerSkyScanState skyScan)
	Destroy the DopplerSkyScanState structure.
int	XLALFreeDopplerSkyScan (DopplerSkyScanState *skyScan)
void	writeSkyGridFile (LALStatus , const DopplerSkyGrid grid, const CHAR *fname)
	Write the given sky-grid to a file.
void	ParseSkyRegionString (LALStatus , SkyRegion region, const CHAR *input)
	parse a skyRegion-string into a SkyRegion structure: the expected string-format is " (ra1, dec1), (ra2, dec2), (ra3, dec3), ... "
void	SkySquare2String (LALStatus , CHAR *string, REAL8 Alpha, REAL8 Delta, REAL8 AlphaBand, REAL8 DeltaBand)
	parse a 'classical' sky-square (Alpha, Delta, AlphaBand, DeltaBand) into a "SkyRegion"-string of the form '(a1,d1), (a2,d2),.
void	getMCDopplerCube (LALStatus , DopplerRegion cube, PulsarDopplerParams signal, UINT4 PointsPerDim, const DopplerSkyScanInit *params)
	Determine a (randomized) cubic DopplerRegion around a search-point with (roughly) the given number of grid-points in each non-projected dimension.
void	getMetricEllipse (LALStatus , MetricEllipse ellipse, REAL8 mismatch, const REAL8Vector *metric, UINT4 dim0)
	get "metric-ellipse" for given metric.
int	fprintfDopplerParams (FILE fp, const PulsarDopplerParams params)
	Debug-output of PulsarDopplerParams struct.
DopplerSkyGrid *	XLALEquiPartitionSkygrid (const DopplerSkyGrid *skygrid, UINT4 jPart, UINT4 numPartitions)
	Equi-partition (approximately) a given skygrid into numPartitions, and return partition 0<= partitionIndex < numPartitions.
Variables
const DopplerSkyGrid	empty_DopplerSkyGrid
const DopplerSkyScanState	empty_DopplerSkyScanState
const DopplerSkyScanInit	empty_DopplerSkyScanInit
const PulsarDopplerParams	empty_PulsarDopplerParams
const DopplerRegion	empty_DopplerRegion
const SkyRegion	empty_SkyRegion