Loading [MathJax]/extensions/TeX/AMSsymbols.js
LALPulsar 7.1.1.1-8a6b96f
All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
Header PtoleMetric.h

Detailed Description

Provides routines to compute pulsar parameter-space metrics using the `‘Ptolemaic’' approximation.

Author
Jones, D. I. Owen, B. J.
Date
2001 – 2006

Synopsis

#include <lal/PtoleMetric.h>

This module covers routines for using a `‘Ptolemaic’' (epicyclic) approximation to the detector motion to compute the parameter-space metric for a pulsar search. (At the moment, the search is assumed to be a single coherent integration.) The results should be very similar to those under StackMetric.h, and reading that documention is a good background for this documentation.

Why this extra module? Two words: simplicity and speed. The metric components can be expressed analytically in terms of trig functions, allowing one to get a feel for what the parameter space will look like before using a single CPU cycle. In addition, CPU usage is much reduced (compared to the routines in StackMetric.h) in numerical explorations such as testing the suitability of various tiling codes. Thus, the functions in this header can be very useful in the current stage of exploring parameter space and wondering how we can practically take advantage of correlations. It's also good at catching bugs and errors in the numerical routines under StackMetric.h. The effectiveness of the tiling at catching signals should be very little reduced by the approximation. Jones, Owen, and Whitbeck will write a short paper on this and other details.

Prototypes

void LALPtoleMetric (LALStatus *status, REAL8Vector *metric, PtoleMetricIn *input)
 Computes metric components for a pulsar search in the `‘Ptolemaic’' approximation; both the Earth's spin and orbit are included. More...
 
void LALPulsarMetric (LALStatus *status, REAL8Vector **metric, PtoleMetricIn *input)
 Unified "wrapper" to provide a uniform interface to LALPtoleMetric() and LALCoherentMetric(). More...
 
void LALProjectMetric (LALStatus *, REAL8Vector *metric, BOOLEAN errors)
 Project out the zeroth dimension of a metric. More...
 
int XLALFindMetricDim (const REAL8Vector *metric)
 Figure out dimension of a REAL8Vector -encoded metric (see PMETRIC_INDEX() ). More...
 
int XLALSpindownMetric (gsl_matrix *metric, double Tspan)
 Frequency and frequency derivative components of the metric, suitable for a directed search with only one fixed sky position. More...
 

Data Structures

struct  PtoleMetricIn
 This structure will likely be changed to match up better with those under StackMetric.h; it contains the bare necessities, not needing function pointers etc. More...
 

Enumerations

enum  LALPulsarMetricType { LAL_PMETRIC_NONE = 0 , LAL_PMETRIC_COH_PTOLE_ANALYTIC , LAL_PMETRIC_LAST }
 Constants defining different types of pulsar-metrics. More...
 

Macros

#define PMETRIC_MIN(x, y)   ((x) < (y) ? (x) : (y))
 
#define PMETRIC_MAX(x, y)   ((x) > (y) ? (x) : (y))
 
#define PMETRIC_INDEX(a, b)   (PMETRIC_MIN((a),(b))+PMETRIC_MAX((a),(b))*(PMETRIC_MAX((a),(b)) + 1 ) / 2 )
 Translate metrix matrix-indices (a,b) into vector-index l. More...
 

Files

file  GeneralMeshTest.c
 Tests and showcases the combination of a LAL metric function (of the user's specification) and Header TwoDMesh.h modules by producing a template mesh.
 
file  GeneralMetricTest.c
 Tests the various LAL metric functions, by outputting the metric at a point in parameter space, and also producing an array of ellipses of constant mismatch.
 
file  PtoleMeshTest.c
 Tests and showcases the combination of Header PtoleMetric.h and Header TwoDMesh.h modules.
 
file  PtoleMetricTest.c
 Tests the LALPtoleMetric() function.
 

Error conditions

#define PTOLEMETRICH_ENULL   1
 
#define PTOLEMETRICH_EPARM   2
 
#define PTOLEMETRICH_EDIM   3
 
#define PTOLEMETRICH_ENONULL   4
 
#define PTOLEMETRICH_EMETRIC   5
 
#define PTOLEMETRICH_MSGENULL   "unexpected null pointer"
 
#define PTOLEMETRICH_MSGEPARM   "bad parameter value"
 
#define PTOLEMETRICH_MSGEDIM   "bad array length"
 
#define PTOLEMETRICH_MSGENONULL   "unexpected non-null pointer"
 
#define PTOLEMETRICH_MSGEMETRIC   "unknown metric type"
 

Function Documentation

◆ LALPtoleMetric()

void LALPtoleMetric ( LALStatus status,
REAL8Vector metric,
PtoleMetricIn input 
)

Computes metric components for a pulsar search in the `‘Ptolemaic’' approximation; both the Earth's spin and orbit are included.

Author
Jones D. I., Owen, B. J., and Whitbeck, D. M.
Date
2001-2005

Description

This function computes metric components in a way that yields results very similar to those of LALCoherentMetric() called with the output of LALTBaryPtolemaic(). The CPU demand, however, is less, and the metric components can be expressed analytically, lending themselves to better understanding of the behavior of the parameter space. For short durations (less than about 70000 seconds or 20 hours) a Taylor series expansion is used to improve the accuracy with which several terms are computed.

Algorithm

For speed and checking reasons, a minimum of numerical computation is involved. The metric components can be expressed analytically (though not tidily) in terms of trig functions and are much too large to be worth writing down here. More comprehensive documentation on the derivation of the metric components can be found in the pulgroup CVS archive as docs/S2/FDS/Isolated/ptolemetric.tex. Jones, Owen, and Whitbeck will write up the calculation and some tests as a journal article.

The function XLALGetEarthTimes() is used to calculate the spin and rotational phase of the Earth at the beginning of the observation.

On output, the metric->data is arranged with the same indexing scheme as in LALCoherentMetric(). The order of the parameters is \( (f_0, \alpha, \delta) \) .

Notes

The analytic metric components were derived separately by Jones and Whitbeck (and partly by Owen) and found to agree. Also, the output of this function has been compared against that of the function combination (CoherentMetric + TDBaryPtolemaic), which is a numerical implementation of the Ptolemaic approximation, and found to agree up to the fourth significant figure or better. Even using DTEphemeris.c for the true Earth's orbit only causes errors in the metric components of order 10%, with (so far) no noticeable effect on the sky coverage.

At present, only one spindown parameter can be included with the sky location. The code contains (commented out) expressions for spindown-spindown metric components for an arbitrary number of spindowns, but the (commented out) spindown-sky components neglect orbital motion.

A separate routine, XLALSpindownMetric(), has been added to compute the metric for multiple spindowns but for fixed sky position, suitable for e.g. directed searches.

Definition at line 91 of file PtoleMetric.c.

◆ LALPulsarMetric()

void LALPulsarMetric ( LALStatus stat,
REAL8Vector **  metric,
PtoleMetricIn input 
)

Unified "wrapper" to provide a uniform interface to LALPtoleMetric() and LALCoherentMetric().

Author
Reinhard Prix

The parameter structure of LALPtoleMetric() was used, because it's more compact.

Definition at line 625 of file PtoleMetric.c.

◆ LALProjectMetric()

void LALProjectMetric ( LALStatus stat,
REAL8Vector metric,
BOOLEAN  errors 
)

Project out the zeroth dimension of a metric.

Author
Creighton, T. D.
Date
2000

Description

This function takes a metric \( g_{\alpha\beta} \) , where \( \alpha,\beta=0,1,\ldots,n \) , and computes the projected metric \( \gamma_{ij} \) on the subspace \( i,j=1,\ldots,n \) , as described in the header StackMetric.h.

The argument *metric stores the metric components in the manner used by the functions LALCoherentMetric() and LALStackMetric(), and errors indicates whether error estimates are included in *metric. Thus *metric is a vector of length \( (n+1)(n+2)/2 \) if errors is zero, or of length \( (n+1)(n+2) \) if errors is nonzero; see LALCoherentMetric() for the indexing scheme.

Upon return, *metric stores the components of \( \gamma_{ij} \) in the same manner as above, with the physically meaningless components \( \gamma_{\alpha0} = \gamma_{0\alpha} \) (and their uncertainties) set identically to zero.

Algorithm

The function simply implements Eq. \eqref{eq_gij_gab} in StackMetric.h. The formula used to convert uncertainties \( s_{\alpha\beta} \) in the metric components \( g_{\alpha\beta} \) into uncertainties \( \sigma_{ij} \) in \( \gamma_{ij} \) is:

\[ \sigma_{ij} = s_{ij} + s_{0i}\left|\frac{g_{0j}}{g_{00}}\right| + s_{0j}\left|\frac{g_{0i}}{g_{00}}\right| + s_{00}\left|\frac{g_{0i}g_{0j}}{(g_{00})^2}\right| \; . \]

Note that if the metric is highly degenerate, one may find that one or more projected components are comparable in magnitude to their estimated numerical uncertainties. This can occur when the observation times are very short or very long compared to the timescales over which the timing derivatives are varying. In the former case, one is advised to use analytic approximations or a different parameter basis. In the latter case, the degenerate components are often not relevant for data analysis, and can be effectively set to zero.

Technically, starting from a full metric \( g_{\alpha\beta}(\mathbf{\lambda}) \) , the projection \( \gamma_{ij}(\vec\lambda) \) is the metric of a subspace \( \{\vec\lambda\} \) passing through the point \( \mathbf{\lambda} \) on a plane orthogonal to the \( \lambda^0 \) axis. In order for \( \gamma_{ij} \) to measure the maximum distance between points \( \vec\lambda \) , it is important to evaluate \( g_{\alpha\beta} \) at the value of \( \lambda^0 \) that gives the largest possible separations. For the pulsar search formalism discussed in StackMetric.h, this is always achieved by choosing the largest value of \( \lambda^0=f_\mathrm{max} \) that is to be covered in the search.

Definition at line 732 of file PtoleMetric.c.

◆ XLALFindMetricDim()

int XLALFindMetricDim ( const REAL8Vector metric)

Figure out dimension of a REAL8Vector -encoded metric (see PMETRIC_INDEX() ).

Return error if input-vector is NULL or not consistent with a quadratic matrix.

Definition at line 793 of file PtoleMetric.c.

◆ XLALSpindownMetric()

int XLALSpindownMetric ( gsl_matrix *  metric,
double  Tspan 
)

Frequency and frequency derivative components of the metric, suitable for a directed search with only one fixed sky position.

The units are those expected by ComputeFstat.

Parameters
[in]metricMatrix containing the metric
[in]TspanTime span of the data set

Definition at line 828 of file PtoleMetric.c.

Enumeration Type Documentation

◆ LALPulsarMetricType

Constants defining different types of pulsar-metrics.

Enumerator
LAL_PMETRIC_NONE 
LAL_PMETRIC_COH_PTOLE_ANALYTIC 
LAL_PMETRIC_LAST 

Definition at line 95 of file PtoleMetric.h.

Macro Definition Documentation

◆ PMETRIC_MIN

#define PMETRIC_MIN (   x,
  y 
)    ((x) < (y) ? (x) : (y))

Definition at line 72 of file PtoleMetric.h.

◆ PMETRIC_MAX

#define PMETRIC_MAX (   x,
  y 
)    ((x) > (y) ? (x) : (y))

Definition at line 73 of file PtoleMetric.h.

◆ PMETRIC_INDEX

#define PMETRIC_INDEX (   a,
 
)    (PMETRIC_MIN((a),(b))+PMETRIC_MAX((a),(b))*(PMETRIC_MAX((a),(b)) + 1 ) / 2 )

Translate metrix matrix-indices (a,b) into vector-index l.

Definition at line 76 of file PtoleMetric.h.

◆ PTOLEMETRICH_ENULL

#define PTOLEMETRICH_ENULL   1

Definition at line 80 of file PtoleMetric.h.

◆ PTOLEMETRICH_EPARM

#define PTOLEMETRICH_EPARM   2

Definition at line 81 of file PtoleMetric.h.

◆ PTOLEMETRICH_EDIM

#define PTOLEMETRICH_EDIM   3

Definition at line 82 of file PtoleMetric.h.

◆ PTOLEMETRICH_ENONULL

#define PTOLEMETRICH_ENONULL   4

Definition at line 83 of file PtoleMetric.h.

◆ PTOLEMETRICH_EMETRIC

#define PTOLEMETRICH_EMETRIC   5

Definition at line 84 of file PtoleMetric.h.

◆ PTOLEMETRICH_MSGENULL

#define PTOLEMETRICH_MSGENULL   "unexpected null pointer"

Definition at line 86 of file PtoleMetric.h.

◆ PTOLEMETRICH_MSGEPARM

#define PTOLEMETRICH_MSGEPARM   "bad parameter value"

Definition at line 87 of file PtoleMetric.h.

◆ PTOLEMETRICH_MSGEDIM

#define PTOLEMETRICH_MSGEDIM   "bad array length"

Definition at line 88 of file PtoleMetric.h.

◆ PTOLEMETRICH_MSGENONULL

#define PTOLEMETRICH_MSGENONULL   "unexpected non-null pointer"

Definition at line 89 of file PtoleMetric.h.

◆ PTOLEMETRICH_MSGEMETRIC

#define PTOLEMETRICH_MSGEMETRIC   "unknown metric type"

Definition at line 90 of file PtoleMetric.h.