Detailed Description

Provides routines to place search meshes for two-dimensional parameter spaces with varying metric.

Author: Creighton, T. D.

Synopsis

#include <lal/TwoDMesh.h>

This header covers routines that lay out a mesh of points on an 2-dimensional parameter space \( \{(x,y)\} \) , placed such that no point in the space lies further than some maximum proper distance \( m_\mathrm{thresh} \) from a mesh point.

The intended purpose of these routines is to place a set of `‘target’' search points over a parameter space, in order to detect signals with unknown parameters. The formalism for defining a proper distance metric on the parameter space is defined in FlatMesh.h. However, whereas the routines under FlatMesh.h require the metric \( \mathsf{g}_{ab} \) to be constant over the parameter space, the routines under this header only treat \( \mathsf{g}_{ab} \) as constant over distances \( \lesssim m_\mathrm{thresh} \) .

Mesh placement using parallelogram tiling. (a) The left and right sides of a tile are required to be vertical; the top and bottom sides can tilt to maximize the tile area. (b) Tiles can be stacked in fixed-width columns\, even as the elliptical contours change. (c) Extra overlapping tiles are sometimes required at the corners of columns.

Since the metric is treated as constant over distances \( \lesssim m_\mathrm{thresh} \) , this distance defines an elliptical contour around any mesh point. We define a `‘tile’' as a parallelogram inscribed within the ellipse, with its left and right sides aligned with the \( y \) axis. This is shown in this figure (a), above. A `‘column’' is a set of tiles of constant horizontal width stacked one on top of the other, as shown in this figure (b). As the metric changes over space, the vertical height and tilt of the tiles in a column may change, so long as their width remains fixed; we note that if the tilt changes, the tiles will overlap slightly to ensure complete coverage. Finally, the boundary of the parameter space may extend outside the `‘corners’' of the column, crossing the end of a tile between its centre and its edge, as shown in this figure (c). These triangular corners can be covered with one or more extra overlapping tiles of reduced width.

In a parameter space with constant metric, the tile area is maximized (and the number of covering tiles minimized) when the column width is \( \sqrt{2} \) times smaller than the projected horizontal width of the ellipses. When the ellipses vary, it is generally best to determine the column width from the narrowest ellipse in a column, to avoid singular effects when tile widths approach the ellipse widths and become infinitesimally high.

For the column-placement algorithm to work effectively, we require that the parameter space be representable as a range \( y\in[y_1(x),y_2(x)] \) between two single-valued functions defined on a domain \( x\in[x_\mathrm{min},x_\mathrm{max}] \) . If a desired search region is too complicated to express this way (e.g. it has disconnected regions, or `‘branches’' where a vertical line intersects the boundary more than twice), then one should divide the region up into subregions with well-behaved boundary functions and tile these subregions separately.

This header and its associated modules are placed in the pulsar package because they were originally intended for use in searches over sky position, but they can be used generically for any two-dimensional parameter space search where the metric is not too poorly behaved.

Prototypes
void	LALCreateTwoDMesh (LALStatus status, TwoDMeshNode mesh, TwoDMeshParamStruc params)

void	LALDestroyTwoDMesh (LALStatus status, TwoDMeshNode mesh, UINT4 nFree)

void	LALRefineTwoDMesh (LALStatus status, TwoDMeshNode coarseMesh, TwoDMeshNode *fineMesh)

void	LALTwoDMesh (LALStatus status, TwoDMeshNode tail, TwoDMeshParamStruc params)

void	LALTwoDColumn (LALStatus status, TwoDMeshNode tail, TwoDColumnParamStruc columnParams, TwoDMeshParamStruc *params)

void	LALTwoDNodeCopy (LALStatus status, TwoDMeshNode new_, TwoDMeshNode old)

Data Structures
struct	TwoDMeshNode
	This structure represents a single node in a linked list of mesh points, specified in the coordinate system used to place it. More...

struct	TwoDMeshParamStruc
	This structure stores the parameters required by the two-dimensional mesh placement functions. More...

struct	TwoDColumnParamStruc
	This structure stores additional parameters required when laying down a single column of a two-dimensional mesh. More...

Files
file	TwoDMesh.c
	Creates or destroys a hierarchical mesh of templates on an 2-dimensional parameter space.

file	TwoDMeshInternal.c
	Low-level routines to place a mesh of templates on an 2-dimensional parameter space.

Error Codes
#define	TWODMESHH_ENUL 1

#define	TWODMESHH_EOUT 2

#define	TWODMESHH_EMEM 3

#define	TWODMESHH_EMETRIC 4

#define	TWODMESHH_EWIDTH 5

#define	TWODMESHH_EDIM 6

#define	TWODMESHH_EINT 7

#define	TWODMESHH_MSGENUL "Unexpected null pointer in arguments"

#define	TWODMESHH_MSGEOUT "Output handle points to a non-null pointer"

#define	TWODMESHH_MSGEMEM "Memory allocation error"

#define	TWODMESHH_MSGEMETRIC "Non-positive metric"

#define	TWODMESHH_MSGEWIDTH "Column width too small"

#define	TWODMESHH_MSGEDIM "Incorrect dimensions"

#define	TWODMESHH_MSGEINT "Non-positive interval"

Function Documentation

◆ LALCreateTwoDMesh()

void LALCreateTwoDMesh	(	LALStatus *	status,
		TwoDMeshNode **	mesh,
		TwoDMeshParamStruc *	params
	)

Definition at line 106 of file TwoDMesh.c.

◆ LALDestroyTwoDMesh()

void LALDestroyTwoDMesh	(	LALStatus *	status,
		TwoDMeshNode **	mesh,
		UINT4 *	nFree
	)

Definition at line 159 of file TwoDMesh.c.

◆ LALRefineTwoDMesh()

void LALRefineTwoDMesh	(	LALStatus *	status,
		TwoDMeshNode *	coarseMesh,
		TwoDMeshNode *	fineMesh
	)

Definition at line 195 of file TwoDMesh.c.

◆ LALTwoDMesh()

void LALTwoDMesh	(	LALStatus *	status,
		TwoDMeshNode **	tail,
		TwoDMeshParamStruc *	params
	)

Definition at line 321 of file TwoDMeshInternal.c.

◆ LALTwoDColumn()

void LALTwoDColumn	(	LALStatus *	status,
		TwoDMeshNode **	tail,
		TwoDColumnParamStruc *	columnParams,
		TwoDMeshParamStruc *	params
	)

Definition at line 466 of file TwoDMeshInternal.c.

◆ LALTwoDNodeCopy()

void LALTwoDNodeCopy	(	LALStatus *	status,
		TwoDMeshNode **	new_,
		TwoDMeshNode *	old
	)

Definition at line 772 of file TwoDMeshInternal.c.

Macro Definition Documentation

◆ TWODMESHH_ENUL

#define TWODMESHH_ENUL 1

Definition at line 103 of file TwoDMesh.h.

◆ TWODMESHH_EOUT

#define TWODMESHH_EOUT 2

Definition at line 104 of file TwoDMesh.h.

◆ TWODMESHH_EMEM

#define TWODMESHH_EMEM 3

Definition at line 105 of file TwoDMesh.h.

◆ TWODMESHH_EMETRIC

#define TWODMESHH_EMETRIC 4

Definition at line 106 of file TwoDMesh.h.

◆ TWODMESHH_EWIDTH

#define TWODMESHH_EWIDTH 5

Definition at line 107 of file TwoDMesh.h.

◆ TWODMESHH_EDIM

#define TWODMESHH_EDIM 6

Definition at line 108 of file TwoDMesh.h.

◆ TWODMESHH_EINT

#define TWODMESHH_EINT 7

Definition at line 109 of file TwoDMesh.h.

◆ TWODMESHH_MSGENUL

#define TWODMESHH_MSGENUL "Unexpected null pointer in arguments"

Definition at line 111 of file TwoDMesh.h.

◆ TWODMESHH_MSGEOUT

#define TWODMESHH_MSGEOUT "Output handle points to a non-null pointer"

Definition at line 112 of file TwoDMesh.h.

◆ TWODMESHH_MSGEMEM

#define TWODMESHH_MSGEMEM "Memory allocation error"

Definition at line 113 of file TwoDMesh.h.

◆ TWODMESHH_MSGEMETRIC

#define TWODMESHH_MSGEMETRIC "Non-positive metric"

Definition at line 114 of file TwoDMesh.h.

◆ TWODMESHH_MSGEWIDTH

#define TWODMESHH_MSGEWIDTH "Column width too small"

Definition at line 115 of file TwoDMesh.h.

◆ TWODMESHH_MSGEDIM

#define TWODMESHH_MSGEDIM "Incorrect dimensions"

Definition at line 116 of file TwoDMesh.h.

◆ TWODMESHH_MSGEINT

#define TWODMESHH_MSGEINT "Non-positive interval"

Definition at line 117 of file TwoDMesh.h.