Provides routines to compute pulsar parameter-space metrics using the `‘Ptolemaic’' approximation.
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" |
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.
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.
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) \) .
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.
void LALPulsarMetric | ( | LALStatus * | stat, |
REAL8Vector ** | metric, | ||
PtoleMetricIn * | input | ||
) |
Unified "wrapper" to provide a uniform interface to LALPtoleMetric() and LALCoherentMetric().
The parameter structure of LALPtoleMetric() was used, because it's more compact.
Definition at line 625 of file PtoleMetric.c.
void LALProjectMetric | ( | LALStatus * | stat, |
REAL8Vector * | metric, | ||
BOOLEAN | errors | ||
) |
Project out the zeroth dimension of a metric.
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.
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.
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.
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.
[in] | metric | Matrix containing the metric |
[in] | Tspan | Time span of the data set |
Definition at line 828 of file PtoleMetric.c.
enum 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.
#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.
Definition at line 76 of file PtoleMetric.h.
#define PTOLEMETRICH_ENULL 1 |
Definition at line 80 of file PtoleMetric.h.
#define PTOLEMETRICH_EPARM 2 |
Definition at line 81 of file PtoleMetric.h.
#define PTOLEMETRICH_EDIM 3 |
Definition at line 82 of file PtoleMetric.h.
#define PTOLEMETRICH_ENONULL 4 |
Definition at line 83 of file PtoleMetric.h.
#define PTOLEMETRICH_EMETRIC 5 |
Definition at line 84 of file PtoleMetric.h.
#define PTOLEMETRICH_MSGENULL "unexpected null pointer" |
Definition at line 86 of file PtoleMetric.h.
#define PTOLEMETRICH_MSGEPARM "bad parameter value" |
Definition at line 87 of file PtoleMetric.h.
#define PTOLEMETRICH_MSGEDIM "bad array length" |
Definition at line 88 of file PtoleMetric.h.
#define PTOLEMETRICH_MSGENONULL "unexpected non-null pointer" |
Definition at line 89 of file PtoleMetric.h.
#define PTOLEMETRICH_MSGEMETRIC "unknown metric type" |
Definition at line 90 of file PtoleMetric.h.