Header LALDetectors.h

This header defines structures to hold the basic data describing a gravitational wave detector.

#include <lal/LALDetectors.h>

According to the common frame format specification [18] the geometry of an interferometric detector will be stored in a `FrDetector`

structure, specifying the location of the detector vertex and the orientation of its arms in geodetic coördinates suited to geographical surveying. Resonant bars and other sorts of detectors, if they write their data to frames, are expected to fill this structure with their location and orientation in some way suited to the detector type.

For most data analysis tasks, however, any gravitational wave detector can be described by its location in an Earth-fixed rotating reference frame, as well as a *response tensor* \(d^{ab}\), constant in the same frame, which defines the "strain" \(h\) measured by the detector in terms of the metric perturbation \(h_{ab}\) as

\begin{equation} h = h_{ab} \, d^{ab} \ . \end{equation}

This header defines a `LALFrDetector`

structure which contains essentially the same information as the `FrDetector`

structure, as well as a `LALDetector`

structure which contains the Cartesian coördinates of the detector along with the components of the response tensor \(d^{ab}\) in the same coördinate system.

Geodetic coördinates are spheroidal coördinates based on the WGS-84 Earth Model, which is an oblate spheroid with equatorial radius \(a=6.378137\times 10^6\,\textrm{m}\) and polar radius \(b=6.356752314\times 10^6\,\textrm{m}\). Any point in space can be located according to its longitude, latitude, and elevation. The *longitude* \(\lambda\) is the angle between the half-plane bounded by the symmetry axis of the reference ellipsoid containing the point in question and the half-plane plane containing the Prime Meridian; it is measured in radians, increases to the East, and ranges from \(-\pi\) to \(\pi\). The *latitude* \(\beta\) is the angle between the ray which is normal to the ellipsoid and passes through the point in question and the equatorial plane; it is measured in radians, increases to the North, and ranges from \(-\pi/2\) to \(\pi/2\). The *elevation* \(h\) is the signed distance along this ray from the reference ellipsoid to the point in question. This coördinate system is described in more detail in [3] .

The `LALFrDetector`

structure stores the directions along the two arms of an interferometer in an altitude/azimuth representation with respect to the local tangent plane to the reference ellipsoid, known as the local horizontal. The altitude \({\mathcal{A}}\) is the angle the direction vector makes with the horizontal, \({\mathcal{A}} > 0\) meaning above horizontal, \({\mathcal{A}} < 0\) below. The azimuth angle \(\zeta\) is found by projecting the direction onto the local horizontal plane, then measuring the angle clockwise from North to this projected direction.

The position vector and response tensor contained in the `LALDetector`

structure are defined in a simple orthonormal coördinate system with its origin at the center of the earth, an \(x^1\) axis which pierces the Earth's surface at the intersection of the equator and the prime meridian, an \(x^2\) axis which pierces the earth's surface at \(\pi/2\) radians East longitude on the equator, and an \(x^3\) axis which pierces the Earth's surface at the North Pole. The coördinates \(x^1\), \(x^2\), \(x^3\) correspond to the Earth-fixed coördinates \(X_E\), \(Y_E\), \(Z_E\) defined in [3] , respectively.

The relationship between geodetic and Cartesian coördinates is given by

\begin{align} \label{tools_e_cart1} x^1 &=\left( \frac{a^2}{\sqrt{a^2\cos^2\beta+b^2\sin^2\beta}} + h \right) \cos\beta\cos\lambda \\ \label{tools_e_cart2} x^2 &=\left( \frac{a^2}{\sqrt{a^2\cos^2\beta+b^2\sin^2\beta}} + h \right) \cos\beta\sin\lambda \\ \label{tools_e_cart3} x^3 &=\left( \frac{b^2}{\sqrt{a^2\cos^2\beta+b^2\sin^2\beta}} + h \right) \sin\beta \\ \end{align}

In practice, we will often be working with fixed unchanging site geometry, e.g., for the LIGO interferometers; to avoid constantly reconstructing the corresponding `LALDetectors`

, we should define some constant `LALDetectors`

describing them. Those are stored in a constant array of `LALDetector`

structures known as `lalCachedDetectors`

, which is declared `extern`

in this header and defined in Module CreateDetector.c.

The `LALCreateDetector()`

routine will first look through the `lalCachedDetectors`

array for a `LALDetector`

structure with matching `type`

and `frDetector.name`

fields; if it finds one, it returns a copy of that; if not, it creates one.

For example, the `LALDetector`

representing LIGO Hanford 4km (H1) in differential mode is `lalCachedDetectors[LAL_LHO_4K_DETECTOR]`

.

## Modules | |

Module CreateDetector.c | |

Creates a `LALDetector` structure from a `LALFrDetector` structure and the type of detector. | |

Detector Constants | |

Constants describing various gravitational wave detectors. | |

## Data Structures | |

struct | LALFrDetector |

Detector frame data structure Structure to contain the data that appears in a FrDetector structure in frame data. More... | |

struct | LALDetector |

Detector structure. More... | |

## Enumerations | |

enum | { LAL_TAMA_300_DETECTOR = 0, LAL_VIRGO_CITF_DETECTOR = 1, LAL_VIRGO_DETECTOR = 2, LAL_GEO_600_DETECTOR = 3, LAL_LHO_2K_DETECTOR = 4, LAL_LHO_4K_DETECTOR = 5, LAL_LLO_4K_DETECTOR = 6, LAL_CIT_40_DETECTOR = 7, LAL_ALLEGRO_DETECTOR = 8, LAL_AURIGA_DETECTOR = 9, LAL_EXPLORER_DETECTOR = 10, LAL_NIOBE_DETECTOR = 11, LAL_NAUTILUS_DETECTOR = 12, LAL_ACIGA_DETECTOR = 13, LAL_KAGRA_DETECTOR = 14, LAL_LIO_4K_DETECTOR = 15, LAL_ET1_DETECTOR = 16, LAL_ET2_DETECTOR = 17, LAL_ET3_DETECTOR = 18, LAL_ET0_DETECTOR = 19, LAL_NUM_DETECTORS = 20 } |

Enumeration of Detectors: follows order of DQ bit assignments. More... | |

enum | { LAL_TAMA_300_DETECTOR_BIT = LAL_INT8_C(1) << 2 * LAL_TAMA_300_DETECTOR, LAL_VIRGO_CITF_DETECTOR_BIT = LAL_INT8_C(1) << 2 * LAL_VIRGO_CITF_DETECTOR, LAL_VIRGO_DETECTOR_BIT = LAL_INT8_C(1) << 2 * LAL_VIRGO_DETECTOR, LAL_GEO_600_DETECTOR_BIT = LAL_INT8_C(1) << 2 * LAL_GEO_600_DETECTOR, LAL_LHO_2K_DETECTOR_BIT = LAL_INT8_C(1) << 2 * LAL_LHO_2K_DETECTOR, LAL_LHO_4K_DETECTOR_BIT = LAL_INT8_C(1) << 2 * LAL_LHO_4K_DETECTOR, LAL_LLO_4K_DETECTOR_BIT = LAL_INT8_C(1) << 2 * LAL_LLO_4K_DETECTOR, LAL_CIT_40_DETECTOR_BIT = LAL_INT8_C(1) << 2 * LAL_CIT_40_DETECTOR, LAL_ALLEGRO_DETECTOR_BIT = LAL_INT8_C(1) << 2 * LAL_ALLEGRO_DETECTOR, LAL_AURIGA_DETECTOR_BIT = LAL_INT8_C(1) << 2 * LAL_AURIGA_DETECTOR, LAL_NIOBE_DETECTOR_BIT = LAL_INT8_C(1) << 2 * LAL_NIOBE_DETECTOR, LAL_NAUTILUS_DETECTOR_BIT = LAL_INT8_C(1) << 2 * LAL_NAUTILUS_DETECTOR, LAL_ACIGA_DETECTOR_BIT = LAL_INT8_C(1) << 2 * LAL_ACIGA_DETECTOR, LAL_KAGRA_DETECTOR_BIT = LAL_INT8_C(1) << 2 * LAL_KAGRA_DETECTOR, LAL_LIO_4K_DETECTOR_BIT = LAL_INT8_C(1) << 2 * LAL_LIO_4K_DETECTOR, LAL_ET1_DETECTOR_BIT = LAL_INT8_C(1) << 2 * LAL_ET1_DETECTOR, LAL_ET2_DETECTOR_BIT = LAL_INT8_C(1) << 2 * LAL_ET2_DETECTOR, LAL_ET3_DETECTOR_BIT = LAL_INT8_C(1) << 2 * LAL_ET3_DETECTOR, LAL_ET0_DETECTOR_BIT = LAL_INT8_C(1) << 2 * LAL_ET0_DETECTOR } |

Detector DQ bit assignments (2 bits per detector) More... | |

enum | LALDetectorType { LALDETECTORTYPE_ABSENT, LALDETECTORTYPE_IFODIFF, LALDETECTORTYPE_IFOXARM, LALDETECTORTYPE_IFOYARM, LALDETECTORTYPE_IFOCOMM, LALDETECTORTYPE_CYLBAR } |

Detector type, which determines how the detector response is determined. More... | |

## Files | |

file | DetectorSiteTest.c |

Tests the detector response and site parameter structures and the routine to create one from the other. | |

## Variables | |

const LALDetector | lalCachedDetectors [LAL_NUM_DETECTORS] |

Pre-existing detectors. More... | |

## Error Codes | |

#define | LALDETECTORSH_ENULLP 1 |

Null pointer. More... | |

#define | LALDETECTORSH_ETYPE 2 |

Unsupported detector type. More... | |

anonymous enum |

Enumeration of Detectors: follows order of DQ bit assignments.

Definition at line 168 of file LALDetectors.h.

anonymous enum |

Detector DQ bit assignments (2 bits per detector)

Definition at line 193 of file LALDetectors.h.

enum LALDetectorType |

Detector type, which determines how the detector response is determined.

Since data from bars as well as interferometers can be written to frames, we need an additional piece of information to interpret the site geometry data specified in the `LALFrDetector`

structure; for instance, is the x arm really the x arm or is it the long axis of a bar? The `LALDetectorType`

enumeration provides a way to keep track of that.

Definition at line 226 of file LALDetectors.h.

#define LALDETECTORSH_ENULLP 1 |

Null pointer.

Definition at line 156 of file LALDetectors.h.

#define LALDETECTORSH_ETYPE 2 |

Unsupported detector type.

Definition at line 157 of file LALDetectors.h.

const LALDetector lalCachedDetectors[LAL_NUM_DETECTORS] |

Pre-existing detectors.

Definition at line 577 of file CreateDetector.c.