Prototypes
static gsl_matrix *	SM_ComputePhaseMetric (const DopplerCoordinateSystem coords, const LIGOTimeGPS ref_time, const LIGOTimeGPS start_time, const LIGOTimeGPS end_time, const MultiLALDetector detectors, const MultiNoiseFloor detector_weights, const DetectorMotionType detector_motion, const EphemerisData *ephemerides)
	Call XLALComputeDopplerPhaseMetric() to compute the phase metric for a given coordinate system. More...

static int	SM_ComputeFittedSuperskyMetric (gsl_matrix fitted_ssky_metric, SuperskyTransformData rssky_transf, const gsl_matrix ussky_metric, const gsl_matrix orbital_metric, const DopplerCoordinateSystem ocoords, const LIGOTimeGPS start_time, const LIGOTimeGPS *end_time)
	Find a least-squares linear fit to the orbital X and Y metric elements using the frequency and spindown metric elements. More...

static int	SM_ComputeDecoupledSuperskyMetric (gsl_matrix decoupled_ssky_metric, SuperskyTransformData rssky_transf, const gsl_matrix *fitted_ssky_metric)
	Decouple the sky–sky and freq+spin–freq+spin blocks of the fitted supersky metric. More...

static int	SM_ComputeAlignedSuperskyMetric (gsl_matrix aligned_ssky_metric, SuperskyTransformData rssky_transf, const gsl_matrix *decoupled_ssky_metric)
	Align the sky–sky block of the decoupled supersky metric with its eigenvalues by means of a rotation. More...

static int	SM_ComputeReducedSuperskyMetric (gsl_matrix rssky_metric, SuperskyTransformData rssky_transf, const size_t spindowns, const gsl_matrix ussky_metric, const DopplerCoordinateSystem ucoords, const gsl_matrix orbital_metric, const DopplerCoordinateSystem ocoords, const LIGOTimeGPS ref_time, const LIGOTimeGPS start_time, const LIGOTimeGPS *end_time)
	Compute the reduced supersky metric. More...

SuperskyMetrics *	XLALComputeSuperskyMetrics (const SuperskyMetricType type, const size_t spindowns, const LIGOTimeGPS ref_time, const LALSegList segments, const double fiducial_freq, const MultiLALDetector detectors, const MultiNoiseFloor detector_weights, const DetectorMotionType detector_motion, const EphemerisData *ephemerides)
	Compute the supersky metrics, which are returned in a `SuperskyMetrics` struct. More...

SuperskyMetrics *	XLALCopySuperskyMetrics (const SuperskyMetrics *metrics)
	Copy a `SuperskyMetrics` struct. More...

void	XLALDestroySuperskyMetrics (SuperskyMetrics *metrics)
	Destroy a `SuperskyMetrics` struct. More...

static int	fits_table_init_SuperskyTransformData (FITSFile *file)
	Initialise a FITS table for writing/reading a table of SuperskyTransformData entries. More...

int	XLALFITSWriteSuperskyMetrics (FITSFile file, const SuperskyMetrics metrics)
	Write a `SuperskyMetrics` struct to a FITS file. More...

int	XLALFITSReadSuperskyMetrics (FITSFile file, SuperskyMetrics *metrics)
	Read a `SuperskyMetrics` struct from a FITS file. More...

int	XLALSuperskyMetricsDimensions (const SuperskyMetrics metrics, size_t spindowns)
	Return dimensions of the supersky metrics. More...

static int	SM_ScaleSuperskyMetricFiducialFreq (gsl_matrix rssky_metric, SuperskyTransformData rssky_transf, const double new_fiducial_freq)
	Scale a given supersky metric and its coordinate transform data to a new fiducial frequency. More...

int	XLALScaleSuperskyMetricsFiducialFreq (SuperskyMetrics *metrics, const double new_fiducial_freq)
	Scale all supersky metrics and their coordinate transform data to a new fiducial frequency. More...

int	XLALEqualizeReducedSuperskyMetricsFreqSpacing (SuperskyMetrics *metrics, const double coh_max_mismatch, const double semi_max_mismatch)
	Project and rescale the reduced supersky metrics in the frequency dimension, such that all reduced supersky metrics have the same frequency spacing for the given maximum mismatches. More...

int	XLALSetPhysicalPointSuperskyRefTime (PulsarDopplerParams out_phys, const SuperskyTransformData rssky_transf)
	Set the reference time of a physical point to that of the reduced supersky coordinates. More...

static void	SM_ReducedToAligned (double as[3], const gsl_vector *rss, const double hemi)
	Convert from 2-dimensional reduced supersky coordinates to 3-dimensional aligned sky coordinates. More...

static void	SM_AlignedToReduced (gsl_vector *rss, const double as[3])
	Convert from 3-dimensional aligned sky coordinates to 2-dimensional reduced supersky coordinates. More...

int	XLALConvertPhysicalToSuperskyPoint (gsl_vector out_rssky, const PulsarDopplerParams in_phys, const SuperskyTransformData *rssky_transf)
	Convert a point from physical to supersky coordinates. More...

int	XLALConvertSuperskyToPhysicalPoint (PulsarDopplerParams out_phys, const gsl_vector in_rssky, const gsl_vector ref_rssky, const SuperskyTransformData rssky_transf)
	Convert a point from supersky to physical coordinates. More...

int	XLALConvertSuperskyToSuperskyPoint (gsl_vector out_rssky, const SuperskyTransformData out_rssky_transf, const gsl_vector in_rssky, const gsl_vector ref_rssky, const SuperskyTransformData *in_rssky_transf)
	Convert a point between supersky coordinates. More...

int	XLALConvertPhysicalToSuperskyPoints (gsl_matrix *out_rssky, const gsl_matrix in_phys, const SuperskyTransformData *rssky_transf)
	Convert a set of points from physical to supersky coordinates. More...

int	XLALConvertSuperskyToPhysicalPoints (gsl_matrix *out_phys, const gsl_matrix in_rssky, const SuperskyTransformData *rssky_transf)
	Convert a set of points from supersky to physical coordinates. More...

static void	SkyBoundCache (const size_t dim UNUSED, const gsl_vector point, gsl_vector cache)

static double	PhysicalSkyBound (const void data, const size_t dim UNUSED, const gsl_matrix cache UNUSED, const gsl_vector *point)

int	XLALSetSuperskyPhysicalSkyBounds (LatticeTiling tiling, gsl_matrix rssky_metric, SuperskyTransformData *rssky_transf, const double alpha1, const double alpha2, const double delta1, const double delta2)
	Set parameter-space bounds on the physical sky position \( (\alpha, \delta) \) for a lattice tiling using the reduced supersky metric. More...

static double	ConstantBoundB (const void data, const size_t dim UNUSED, const gsl_matrix cache UNUSED, const gsl_vector *point)

static double	EqualAreaSkyBoundSolverA (double A1, void *params)

static double	EqualAreaSkyBoundSolverB (double B1, void *params)

int	XLALSetSuperskyEqualAreaSkyBounds (LatticeTiling tiling, const gsl_matrix rssky_metric, const double max_mismatch, const UINT4 patch_count, const UINT4 patch_index)
	Divide the reduced supersky parameter space into `patch_count` equal-area patches, and set parameter-space bounds on the reduced supersky coordinates \( (n_a,n_b) \) for the patch indexed by `patch_index`. More...

static double	PhysicalSpinBound (const void data, const size_t dim UNUSED, const gsl_matrix cache, const gsl_vector *point UNUSED)

int	XLALSetSuperskyPhysicalSpinBound (LatticeTiling tiling, const SuperskyTransformData rssky_transf, const size_t s, const double bound1, const double bound2)
	Set parameter-space bounds on the physical frequency/spindowns \( f^{(s)} \) for a lattice tiling using the reduced supersky metric. More...

int	XLALSetSuperskyPhysicalSpinBoundPadding (LatticeTiling tiling, const SuperskyTransformData rssky_transf, const size_t s, const bool padding)
	Set parameter-space bound padding on the physical frequency/spindowns \( f^{(s)} \) for a lattice tiling using the reduced supersky metric. More...

static int	SM_LatticePhysicalRangeCallback (const bool first_call, const LatticeTiling tiling, const LatticeTilingIterator itr, const gsl_vector point, const size_t changed_i, const void param, void *out)

int	XLALRegisterSuperskyLatticePhysicalRangeCallback (LatticeTiling tiling, const SuperskyTransformData rssky_transf, const PulsarDopplerParams min_phys, const PulsarDopplerParams max_phys)
	Register a lattice tiling callback function which computes the physical range covered by a reduced supersky lattice tiling. More...

static int	SM_LatticeSuperskyRangeCallback (const bool first_call, const LatticeTiling tiling, const LatticeTilingIterator itr, const gsl_vector point, const size_t changed_i, const void param, void *out)

int	XLALRegisterSuperskyLatticeSuperskyRangeCallback (LatticeTiling tiling, const SuperskyTransformData rssky_transf, const SuperskyTransformData rssky2_transf, const gsl_vector min_rssky2, const gsl_vector *max_rssky2)
	Register a lattice tiling callback function which computes the range covered by a reduced supersky lattice tiling in another set of reduced supersky coordinates. More...

int	XLALSetSuperskyRangeBounds (LatticeTiling tiling, const gsl_vector min_rssky, const gsl_vector *max_rssky)
	Set parameter-space bounds on an entire lattice tiling given minimum and maximum ranges in reduced supersky coordinates. More...

Data Structures
struct	SuperskyTransformData
	Supersky metric coordinate transform data. More...

struct	SM_CallbackParam

struct	SM_CallbackOut

struct	PhysicalSkyBoundPiece

struct	PhysicalSkyBoundData

Macros
#define	SQR(x) ((x)*(x))

#define	RE_SQRT(x) sqrt(GSL_MAX(DBL_EPSILON, (x)))

#define	DOT2(x, y) ((x)[0](y)[0] + (x)[1](y)[1])

#define	DOT3(x, y) ((x)[0](y)[0] + (x)[1](y)[1] + (x)[2]*(y)[2])

#define	MAX_SKY_OFFSETS PULSAR_MAX_SPINS

#define	SMAX nspins

#define	CHECK_RSSKY_METRIC_TRANSF(M, RT) ((M) != NULL && CHECK_RSSKY_TRANSF(RT) && (M)->size1 == (RT)->ndim && (M)->size2 == (RT)->ndim)

#define	CHECK_RSSKY_TRANSF(RT) ((RT) != NULL && (RT)->ndim > 0 && (RT)->fiducial_freq > 0 && (RT)->nsky_offsets == 1 + (RT)->nspins)

#define	RSSKY_FKDOT_OFFSET(RT, S) (((S) == 0) ? ((RT)->SMAX) : ((size_t)((S) - 1)))

#define	RSSKY_FKDOT_DIM(RT, S) (2 + RSSKY_FKDOT_OFFSET(RT, S))

Variables
const double	fiducial_calc_freq = 100.0
	Fiducial frequency at which to numerically calculate metrics, which are then rescaled to user-requested frequency based on known scalings. More...

Macro Definition Documentation

◆ SQR

#define SQR ( x ) ((x)*(x))

Definition at line 48 of file SuperskyMetrics.c.

◆ RE_SQRT

#define RE_SQRT ( x ) sqrt(GSL_MAX(DBL_EPSILON, (x)))

Definition at line 51 of file SuperskyMetrics.c.

◆ DOT2

#define DOT2	(	x,
		y
	)	((x)[0](y)[0] + (x)[1](y)[1])

Definition at line 54 of file SuperskyMetrics.c.

◆ DOT3

#define DOT3	(	x,
		y
	)	((x)[0](y)[0] + (x)[1](y)[1] + (x)[2]*(y)[2])

Definition at line 55 of file SuperskyMetrics.c.

◆ MAX_SKY_OFFSETS

#define MAX_SKY_OFFSETS PULSAR_MAX_SPINS

Definition at line 58 of file SuperskyMetrics.c.

◆ SMAX

#define SMAX nspins

Definition at line 61 of file SuperskyMetrics.c.

◆ CHECK_RSSKY_METRIC_TRANSF

#define CHECK_RSSKY_METRIC_TRANSF	(	M,
		RT
	)	((M) != NULL && CHECK_RSSKY_TRANSF(RT) && (M)->size1 == (RT)->ndim && (M)->size2 == (RT)->ndim)

Definition at line 75 of file SuperskyMetrics.c.

◆ CHECK_RSSKY_TRANSF

#define CHECK_RSSKY_TRANSF ( RT ) ((RT) != NULL && (RT)->ndim > 0 && (RT)->fiducial_freq > 0 && (RT)->nsky_offsets == 1 + (RT)->nspins)

Definition at line 77 of file SuperskyMetrics.c.

◆ RSSKY_FKDOT_OFFSET

#define RSSKY_FKDOT_OFFSET	(	RT,
		S
	)	(((S) == 0) ? ((RT)->SMAX) : ((size_t)((S) - 1)))

Definition at line 81 of file SuperskyMetrics.c.

◆ RSSKY_FKDOT_DIM

#define RSSKY_FKDOT_DIM	(	RT,
		S
	)	(2 + RSSKY_FKDOT_OFFSET(RT, S))

Definition at line 82 of file SuperskyMetrics.c.

Function Documentation

◆ SM_ComputePhaseMetric()

static gsl_matrix * SM_ComputePhaseMetric	(	const DopplerCoordinateSystem *	coords,
		const LIGOTimeGPS *	ref_time,
		const LIGOTimeGPS *	start_time,
		const LIGOTimeGPS *	end_time,
		const MultiLALDetector *	detectors,
		const MultiNoiseFloor *	detector_weights,
		const DetectorMotionType	detector_motion,
		const EphemerisData *	ephemerides
	)

static

Call XLALComputeDopplerPhaseMetric() to compute the phase metric for a given coordinate system.

Parameters

[in]	coords	Coordinate system to compute metric for
[in]	ref_time	Reference time of the metric
[in]	start_time	Start time of the metric
[in]	end_time	End time of the metric
[in]	detectors	List of detectors to average metric over
[in]	detector_weights	Weights used to combine single-detector metrics (default: unit weights)
[in]	detector_motion	Which detector motion to use
[in]	ephemerides	Earth/Sun ephemerides

Definition at line 107 of file SuperskyMetrics.c.

◆ SM_ComputeFittedSuperskyMetric()

static int SM_ComputeFittedSuperskyMetric	(	gsl_matrix *	fitted_ssky_metric,
		SuperskyTransformData *	rssky_transf,
		const gsl_matrix *	ussky_metric,
		const gsl_matrix *	orbital_metric,
		const DopplerCoordinateSystem *	ocoords,
		const LIGOTimeGPS *	start_time,
		const LIGOTimeGPS *	end_time
	)

static

Find a least-squares linear fit to the orbital X and Y metric elements using the frequency and spindown metric elements.

Outputs the intermediate fitted supersky metric, and updates the reduced supersky metric coordinate transform data.

Parameters

[out]	fitted_ssky_metric	Fitted supersky metric
[in,out]	rssky_transf	Reduced supersky metric coordinate transform data
[in]	ussky_metric	Unrestricted supersky metric
[in]	orbital_metric	Orbital metric in ecliptic coordinates
[in]	ocoords	Coordinate system of orbital metric
[in]	start_time	Start time of the metrics
[in]	end_time	End time of the metrics

Definition at line 192 of file SuperskyMetrics.c.

◆ SM_ComputeDecoupledSuperskyMetric()

static int SM_ComputeDecoupledSuperskyMetric	(	gsl_matrix *	decoupled_ssky_metric,
		SuperskyTransformData *	rssky_transf,
		const gsl_matrix *	fitted_ssky_metric
	)

static

Decouple the sky–sky and freq+spin–freq+spin blocks of the fitted supersky metric.

Outputs the intermediate decoupled supersky metric, and updates the reduced supersky metric coordinate transform data.

Parameters

[out]	decoupled_ssky_metric	Decoupled supersky metric
[in,out]	rssky_transf	Reduced supersky metric coordinate transform data
[in]	fitted_ssky_metric	Fitted supersky metric

Definition at line 346 of file SuperskyMetrics.c.

◆ SM_ComputeAlignedSuperskyMetric()

static int SM_ComputeAlignedSuperskyMetric	(	gsl_matrix *	aligned_ssky_metric,
		SuperskyTransformData *	rssky_transf,
		const gsl_matrix *	decoupled_ssky_metric
	)

static

Align the sky–sky block of the decoupled supersky metric with its eigenvalues by means of a rotation.

Outputs the intermediate aligned supersky metric, and updates the reduced supersky metric coordinate transform data.

Parameters

[out]	aligned_ssky_metric	Aligned supersky metric
[in,out]	rssky_transf	Reduced supersky metric coordinate transform data
[in]	decoupled_ssky_metric	Decoupled supersky metric

Definition at line 413 of file SuperskyMetrics.c.

◆ SM_ComputeReducedSuperskyMetric()

static int SM_ComputeReducedSuperskyMetric	(	gsl_matrix **	rssky_metric,
		SuperskyTransformData **	rssky_transf,
		const size_t	spindowns,
		const gsl_matrix *	ussky_metric,
		const DopplerCoordinateSystem *	ucoords,
		const gsl_matrix *	orbital_metric,
		const DopplerCoordinateSystem *	ocoords,
		const LIGOTimeGPS *	ref_time,
		const LIGOTimeGPS *	start_time,
		const LIGOTimeGPS *	end_time
	)

static

Compute the reduced supersky metric.

Parameters

[out]	rssky_metric	Reduced supersky metric
[out]	rssky_transf	Reduced supersky metric coordinate transform data
[in]	spindowns	Number of frequency+spindown coordinates
[in]	ussky_metric	Unrestricted supersky metric
[in]	ucoords	Coordinate system of unrestricted supersky metric
[in]	orbital_metric	Orbital metric in ecliptic coordinates
[in]	ocoords	Coordinate system of orbital metric
[in]	ref_time	Reference time of the metrics
[in]	start_time	Start time of the metrics
[in]	end_time	End time of the metrics

Definition at line 488 of file SuperskyMetrics.c.

◆ fits_table_init_SuperskyTransformData()

static int fits_table_init_SuperskyTransformData ( FITSFile * file )

static

Initialise a FITS table for writing/reading a table of SuperskyTransformData entries.

Definition at line 762 of file SuperskyMetrics.c.

◆ SM_ScaleSuperskyMetricFiducialFreq()

static int SM_ScaleSuperskyMetricFiducialFreq	(	gsl_matrix *	rssky_metric,
		SuperskyTransformData *	rssky_transf,
		const double	new_fiducial_freq
	)

static

Scale a given supersky metric and its coordinate transform data to a new fiducial frequency.

Parameters

[in]	rssky_metric	Reduced supersky metric
[in]	rssky_transf	Reduced supersky metric coordinate transform data
[in]	new_fiducial_freq	New fiducial frequency

Definition at line 918 of file SuperskyMetrics.c.

◆ SM_ReducedToAligned()

static void SM_ReducedToAligned	(	double	as[3],
		const gsl_vector *	rss,
		const double	hemi
	)

static

Convert from 2-dimensional reduced supersky coordinates to 3-dimensional aligned sky coordinates.

The 2-dimensional reduced supersky coordinates rss = (A, B) encode the two hemispheres of the sky as two neighbouring unit disks. The conversion to 3-dimensional aligned sky coordinates is illustrated in the following diagram:

| as[1] =    __________________________________________
|     B = 1_|         _____             _____         |
|           |      .-'     '-.       .-'     '-.      |
|           |    .'           '.   .'           '.    |
|           |   /               \ /               \   |
|           |  ;                 ;                 ;  |
|         0-|  |                 |                 |  |
|           |  ;                 ;                 ;  |
|           |   \               / \               /   |
|           |    '.           .'   '.           .'    |
|          _|      '-._____.-'       '-._____.-'      |
|        -1 |__.________.________.________.________.__|
|              '        '        '        '        '
|         A = -2       -1        0        1        2
|     as[0] =  1        0       -1        0        1
|     as[2] =  0       -1        0        1        0

Points outside the unit disks are moved radially onto their boundaries.

Parameters

[out]	as	3-dimensional aligned sky coordinates
[in]	rss	2-dimensional reduced supersky coordinates
[in]	hemi	Supersky coordinate hemisphere; only sign is used

Definition at line 1075 of file SuperskyMetrics.c.

◆ SM_AlignedToReduced()

static void SM_AlignedToReduced	(	gsl_vector *	rss,
		const double	as[3]
	)

static

Convert from 3-dimensional aligned sky coordinates to 2-dimensional reduced supersky coordinates.

Parameters

[out]	rss	2-dimensional reduced supersky coordinates
[in]	as	3-dimensional aligned sky coordinates

Definition at line 1094 of file SuperskyMetrics.c.

◆ SkyBoundCache()

static void SkyBoundCache	(	const size_t dim	UNUSED,
		const gsl_vector *	point,
		gsl_vector *	cache
	)

static

Definition at line 1355 of file SuperskyMetrics.c.

◆ PhysicalSkyBound()

static double PhysicalSkyBound	(	const void *	data,
		const size_t dim	UNUSED,
		const gsl_matrix *cache	UNUSED,
		const gsl_vector *	point
	)

static

Definition at line 1393 of file SuperskyMetrics.c.

◆ ConstantBoundB()

static double ConstantBoundB	(	const void *	data,
		const size_t dim	UNUSED,
		const gsl_matrix *cache	UNUSED,
		const gsl_vector *	point
	)

static

Definition at line 2029 of file SuperskyMetrics.c.

◆ EqualAreaSkyBoundSolverA()

static double EqualAreaSkyBoundSolverA	(	double	A1,
		void *	params
	)

static

Definition at line 2056 of file SuperskyMetrics.c.

◆ EqualAreaSkyBoundSolverB()

static double EqualAreaSkyBoundSolverB	(	double	B1,
		void *	params
	)

static

Definition at line 2072 of file SuperskyMetrics.c.

◆ PhysicalSpinBound()

static double PhysicalSpinBound	(	const void *	data,
		const size_t dim	UNUSED,
		const gsl_matrix *	cache,
		const gsl_vector *point	UNUSED
	)

static

Definition at line 2350 of file SuperskyMetrics.c.

◆ SM_LatticePhysicalRangeCallback()

static int SM_LatticePhysicalRangeCallback	(	const bool	first_call,
		const LatticeTiling *	tiling,
		const LatticeTilingIterator *	itr,
		const gsl_vector *	point,
		const size_t	changed_i,
		const void *	param,
		void *	out
	)

static

Definition at line 2439 of file SuperskyMetrics.c.

◆ SM_LatticeSuperskyRangeCallback()

static int SM_LatticeSuperskyRangeCallback	(	const bool	first_call,
		const LatticeTiling *	tiling,
		const LatticeTilingIterator *	itr,
		const gsl_vector *	point,
		const size_t	changed_i,
		const void *	param,
		void *	out
	)

static

Definition at line 2537 of file SuperskyMetrics.c.

Variable Documentation

◆ fiducial_calc_freq

const double fiducial_calc_freq = 100.0

Fiducial frequency at which to numerically calculate metrics, which are then rescaled to user-requested frequency based on known scalings.

Definition at line 88 of file SuperskyMetrics.c.

Prototypes

Data Structures

Macros

Variables

Macro Definition Documentation

◆ SQR

◆ RE_SQRT

◆ DOT2

◆ DOT3

◆ MAX_SKY_OFFSETS

◆ SMAX

◆ CHECK_RSSKY_METRIC_TRANSF

◆ CHECK_RSSKY_TRANSF

◆ RSSKY_FKDOT_OFFSET

◆ RSSKY_FKDOT_DIM

Function Documentation

◆ SM_ComputePhaseMetric()

◆ SM_ComputeFittedSuperskyMetric()

◆ SM_ComputeDecoupledSuperskyMetric()

◆ SM_ComputeAlignedSuperskyMetric()

◆ SM_ComputeReducedSuperskyMetric()

◆ fits_table_init_SuperskyTransformData()

◆ SM_ScaleSuperskyMetricFiducialFreq()

◆ SM_ReducedToAligned()

◆ SM_AlignedToReduced()

◆ SkyBoundCache()

◆ PhysicalSkyBound()

◆ ConstantBoundB()

◆ EqualAreaSkyBoundSolverA()

◆ EqualAreaSkyBoundSolverB()

◆ PhysicalSpinBound()

◆ SM_LatticePhysicalRangeCallback()

◆ SM_LatticeSuperskyRangeCallback()

Variable Documentation

◆ fiducial_calc_freq