Structured datatypes

These datatypes embed primitive and aggregate datatypes inside structures that define their physical meaning. Most of these structures are wrappers for aggregate datatypes that store a physical quantity as a function of time or frequency. Other structures store specific physical information, such as the GPS time, or the factored response function of a filter.

LIGOTimeGPS

This structure stores the time, to nanosecond precision, synchronized to the Global Positioning System time reference. The zero time for the GPS standard is the moment of midnight beginning January 6, 1980, UTC. The LIGOTimeGPS structure can represent times up to 68 years on either side of this epoch. (Note that this is better than an equivalently-sized REAL8 representation of time, which can maintain nanosecond precision only for times within 104 days of its reference point. However, the REAL8 representation does allow one to cover arbitrarily long timescales at correspondingly lower precision.) The fields are:

INT4 gpsSeconds

The number of seconds since the GPS reference time.

INT4 gpsNanoSeconds

The number of nanoseconds since the last GPS second.

LALUnit

This structure stores units in the mksA system (plus Kelvin, Strain, and ADC Count). It also stores an overall power-of-ten scaling factor. The fields are:

INT2 powerOfTen

The power $p$ of ten scaling factor.

INT2 unitNumerator[LALNumUnits]

Array of unit numerators, $N_i$, $i=0\ldots\textrm{LALNumUnits}-1$.

INT2 unitDenominatorMinusOne[LALNumUnits]

Array of unit denominators-minus-one, $D_i$, $i=0\ldots\textrm{LALNumUnits}-1$.

Thus, the units are given by

$$10^p\times\textrm{m}^{N_0/(1+D_0)}\times\textrm{kg}^{N_1/(1... ...xtrm{strain}^{N_5/(1+D_5)} \times\textrm{count}^{N_6/(1+D_6)}$$ (8.1)

The indexes of the units can be specified using the constants LALUnitIndexMeter, LALUnitIndexKiloGram, LALUnitIndexSecond, LALUnitIndexAmpere, LALUnitIndexKelvin, LALUnitIndexStrain, LALUnitIndexADCCount, while LALNumUnits is the total number of units.

<datatype>TimeSeries

This structure represents a sequence of data of type <datatype> (where <datatype> can be any primitive datatype), sampled over uniform time intervals $t_0, t_0+\Delta t, \ldots , t_0+l\Delta t$. Essentially this is a <datatype>Sequence with extra fields defining the sample times and the type of data being sampled. The raw data may also have been heterodyned; that is, multiplied by a sinusoid of some frequency $f_0$, low-pass filtered, and resampled, in order to extract the behaviour in a small bandwidth about $f_0$. The fields are:

CHAR name[LALNameLength]

The name of the data series (i.e. the type of data being sampled).

LIGOTimeGPS epoch

The start time $t_0$ of the data series.

REAL8 deltaT

The sampling interval $\Delta t$, in seconds.

REAL8 f0

The heterodyning frequency $f_0$, in hertz.

LALUnit sampleUnits

The physical units of the quantity being sampled.

<datatype>Sequence *data

The sequence of sampled data.

<datatype>TimeVectorSeries

Like <datatype>TimeSeries, above, except that the sampled data are of type type <datatype>Vector (where <datatype> can be any primitive datatype). The fields are:

CHAR name[LALNameLength]

The name of the data series (i.e. the type of data being sampled).

LIGOTimeGPS epoch

The start time of the data series.

REAL8 deltaT

The sampling interval, in seconds.

REAL8 f0

The heterodyning frequency, in hertz.

LALUnit sampleUnits

The physical units of the quantity being sampled.

<datatype>VectorSequence *data

The sequence of sampled data.

<datatype>TimeArraySeries

Like <datatype>TimeSeries, above, except that the sampled data are of type type <datatype>Array (where <datatype> can be any primitive datatype). The fields are:

CHAR name[LALNameLength]

The name of the data series (i.e. the type of data being sampled).

LIGOTimeGPS epoch

The start time of the data series.

REAL8 deltaT

The sampling interval, in seconds.

REAL8 f0

The heterodyning frequency, in hertz.

LALUnit sampleUnits

The physical units of the quantity being sampled.

<datatype>ArraySequence *data

The sequence of sampled data.

<datatype>FrequencySeries

This structure represents a frequency spectrum of data of type <datatype> (where <datatype> can be any primitive datatype), sampled over uniform frequency intervals $f_0, f_0+\Delta f, \ldots , f_0+l\Delta f$. Essentially this is a <datatype>Sequence with extra fields defining the sample frequencies, the timestamp of the spectrum, and the type of data being sampled. The fields are:

CHAR name[LALNameLength]

The name of the data series (i.e. the type of data being sampled).

LIGOTimeGPS epoch

The start time of the time series from which the spectrum was calculated.

REAL8 f0

The lowest frequency $f_0$ being sampled, in hertz.

REAL8 deltaF

The frequency sampling interval $\Delta f$, in hertz.

LALUnit sampleUnits

The physical units of the quantity being sampled.

<datatype>Sequence *data

The sequence of sampled data.

<datatype>ZPGFilter

This structure stores the complex frequency response of a filter or transfer function in a factored form, where <datatype> can be either COMPLEX8 or COMPLEX16. One defines a (dimensionless) complex frequency variable $\zeta(f\Delta t)$, where $\Delta t$ is the time sampling interval of the data to which the filter will be applied (in the case of a digital filter), or some other reference timescale (in the case of an analog filter). The complex response function can then be given (or approximated) as $H(f)=g\times\prod_k(\zeta-z_k)/\prod_l(\zeta-p_l)$, where $z_k$ are the complex zeros, $p_l$ are the complex poles, and $g$ is the complex gain of the response function. Some common complex frequency representations are the $z$-plane representation $\zeta(f\Delta t)=\exp(2\pi if\Delta t)$, which maps the Nyquist interval $f\in[0,1/2\Delta t)$ onto the upper-half unit circle in $\zeta$, and the $w$-plane representation $\zeta(f\Delta t)=\tan(\pi f\Delta t)$, which maps the Nyquist interval onto the positive real axis in $\zeta$. The fields of <datatype>ZPGFilter are:

CHAR name[LALNameLength]

The name of the filter or transfer function. This should also mention its complex frequency representation.

REAL8 deltaT

The sampling time or reference timescale $\Delta t$ for the filter, in seconds. If zero, it will be treated as being equal to the sampling interval of the data being filtered.

<datatype>Vector *zeros

Pointer to a vector storing the zeros $z_k$ of the filter.

<datatype>Vector *poles

Pointer to a vector storing the poles $p_k$ of the filter.

<datatype> gain

The gain $g$ of the filter.