LAL  7.5.0.1-8083555
Date.h
Go to the documentation of this file.
1 /*
2 * Copyright (C) 2007 Duncan Brown, David Chin, Jolien Creighton, Kipp Cannon, Reinhard Prix, Stephen Fairhurst
3 *
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License as published by
6 * the Free Software Foundation; either version 2 of the License, or
7 * (at your option) any later version.
8 *
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
13 *
14 * You should have received a copy of the GNU General Public License
15 * along with with program; see the file COPYING. If not, write to the
16 * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
17 * MA 02110-1301 USA
18 */
19 
20 #ifndef _DATE_H
21 #define _DATE_H
22 
23 #include <stdio.h>
24 #include <stdlib.h>
25 #include <time.h>
26 
27 #include <lal/LALConstants.h>
28 #include <lal/LALAtomicDatatypes.h>
29 #include <lal/LALDatatypes.h>
30 #include <lal/LALStdio.h>
31 
32 #include <lal/DetectorSite.h>
33 
34 #ifdef __cplusplus
35 extern "C"
36 {
37 #endif
38 
39 #define XLAL_BILLION_INT4 1000000000
40 #define XLAL_BILLION_INT8 LAL_INT8_C( 1000000000 )
41 #define XLAL_BILLION_REAL8 1e9
42 
43 /**
44  * \defgroup Date_h Header Date.h
45  * \ingroup lal_date
46  * \author D.W. Chin, J.D.E. Creighton and Kipp Cannon
47  * \brief Provides routines for manipulating date and time information.
48  *
49  * ### Synopsis ###
50  *
51  * \code
52  * #include <lal/Date.h>
53  * \endcode
54  *
55  * This header covers routines for manipulating date and time
56  * information. The various time systems are discussed in \cite esaa1992 .
57  *
58  */
59 /** @{ */
60 
61 /**
62  * The UNIX time of the GPS origin epoch.
63  * 1980 6 JAN 0h UTC is 3657 days after 1970 1 JAN 0h UTC:
64  * 8 standard years of 365 days = 2920 days
65  * 2 leap years of 366 days = 734 days
66  * 5 extra days.
67  * Hence 3657*86400=315964800.
68  *
69  * Note that this deliberately does not account for any leap seconds in the
70  * interval. POSIX:2001 defines the relation between the UNIX time
71  * \c time_t \c t and a broken down time \c struct \c tm \c utc as
72  * \code
73  * t = utc.tm_sec + utc.tm_min*60 + utc.tm_hour*3600
74  * + utc.tm_yday*86400 + (utc.tm_year-70)*31536000
75  * + ((utc.tm_year-69)/4)*86400 - ((utc.tm_year-1)/100)*86400
76  * + ((utc.tm_year+299)/400)*86400;
77  * \endcode
78  * so if you were to set \c utc.tm_sec=utc.tm_min=utc.tm_hour=0,
79  * \c utc.tm_yday=5, and \c utc.tm_year=80, then you get
80  * \c t=315964800. That is what this is.
81  */
82 #define XLAL_EPOCH_UNIX_GPS 315964800
83 
84 #define XLAL_EPOCH_J2000_0_JD 2451545.0 /**< Julian Day (UTC) of the J2000.0 epoch (2000 JAN 1 12h UTC). */
85 #define XLAL_EPOCH_J2000_0_TAI_UTC 32 /**< Leap seconds (TAI-UTC) on the J2000.0 epoch (2000 JAN 1 12h UTC). */
86 #define XLAL_EPOCH_J2000_0_GPS 630763213 /**< GPS seconds of the J2000.0 epoch (2000 JAN 1 12h UTC). */
87 #define XLAL_EPOCH_GPS_JD 2444244.5 /**< Julian Day (UTC) of the GPS epoch (1980 JAN 6 0h UTC) */
88 #define XLAL_EPOCH_GPS_TAI_UTC 19 /**< Leap seconds (TAI-UTC) on the GPS epoch (1980 JAN 6 0h UTC) */
89 #define XLAL_MJD_REF 2400000.5 /**< Reference Julian Day for Mean Julian Day. */
90 #define XLAL_JD_TO_MJD(jd) ((jd) - XLAL_MJD_REF) /**< Modified Julian Day for specified civil time structure. */
91 
92 /**
93  * This structure stores pointers to a \c LALDetector and a
94  * \c LIGOTimeGPS. Its sole purpose is to aggregate these
95  * structures for passing to functions.
96  */
97 #ifdef SWIG /* SWIG interface directives */
98 SWIGLAL(IMMUTABLE_MEMBERS(tagLALPlaceAndGPS, p_detector));
99 #endif /* SWIG */
100 typedef struct
101 tagLALPlaceAndGPS
102 {
103  const LALDetector *p_detector; /**< pointer to a detector */
104  LIGOTimeGPS *p_gps; /**< Pointer to a GPS time structure */
105 }
107 
108 /**
109  * \name Format macros for printing LIGOTimeGPS
110  *
111  * ### Example ###
112  *
113  * @code
114  * LIGOTimeGPS t = { 1122334455, 666777888 };
115  * printf("The time is %" LAL_GPS_FORMAT "\n", LAL_GPS_PRINT(t));
116  * @endcode
117  */
118 /** @{ */
119 #define LAL_GPS_FORMAT LAL_INT8_FORMAT ".%09" LAL_INT4_FORMAT
120 #define LAL_GPS_PRINT(gps) (INT8)(XLALGPSToINT8NS(&(gps)) / XLAL_BILLION_INT8), (INT4)labs(XLALGPSToINT8NS(&(gps)) % XLAL_BILLION_INT8)
121 /** @} */
122 
123 /** @} */
124 
125 /* ---------- Function prototypes : see respective source.c files for doxygen documentation ---------- */
126 
127 #ifndef SWIG /* exclude from SWIG interface */
128 
129 /* Converts GPS time to nano seconds stored as an INT8. */
131 
132 /* Converts nano seconds stored as an INT8 to GPS time. */
134 
135 /* Sets GPS time given GPS integer seconds and residual nanoseconds. */
136 LIGOTimeGPS * XLALGPSSet( LIGOTimeGPS *epoch, INT4 gpssec, INT8 gpsnan );
137 
138 /* Sets GPS time given GPS seconds as a REAL8. */
140 
141 /* Returns GPS time as a REAL8. */
143 
144 /**
145  * Breaks the GPS time into REAL8 integral and fractional parts,
146  * each of which has the same sign as the epoch. Returns the
147  * fractional part, and stores the integral part (as a REAL8)
148  * in the object pointed to by iptr. Like the standard C math
149  * library function modf().
150  */
151 REAL8 XLALGPSModf( REAL8 *iptr, const LIGOTimeGPS *epoch );
152 
153 /* Adds dt to a GPS time. */
155 
156 /* Adds two GPS times. */
158 
159 /* Subtract a GPS time from a GPS time. Computes t1 - t0. */
161 
162 /* Difference between two GPS times as a double. Returns t1 - t0. */
163 REAL8 XLALGPSDiff( const LIGOTimeGPS *t1, const LIGOTimeGPS *t0 );
164 
165  /* Compares two GPS times. */
166 int XLALGPSCmp( const LIGOTimeGPS *t0, const LIGOTimeGPS *t1 );
167 
168 /* Multiply a GPS time by a REAL8 */
170 
171 /* Divide a GPS time by a REAL8 */
173 
174 /* Parse an ASCII string into a LIGOTimeGPS structure */
175 int XLALStrToGPS(LIGOTimeGPS *t, const char *nptr, char **endptr);
176 
177 /* Return a string containing the ASCII base 10 representation of a LIGOTimeGPS. */
178 char *XLALGPSToStr(char *, const LIGOTimeGPS *t);
179 
180 #endif /* !SWIG */
181 
182 #ifdef SWIG /* SWIG interface directives */
183 SWIGLAL(NEW_EMPTY_ARGUMENT(LIGOTimeGPS*, gpstime));
184 #endif
185 
186 /* This function returns the current GPS time according to the system clock */
188 
189 #ifdef SWIG /* SWIG interface directives */
190 SWIGLAL_CLEAR(NEW_EMPTY_ARGUMENT(LIGOTimeGPS*, gpstime));
191 #endif
192 
193 /* Returns the leap seconds TAI-UTC at a given GPS second. */
194 int XLALLeapSeconds( INT4 gpssec );
195 
196 /* Returns the leap seconds GPS-UTC at a given GPS second. */
197 int XLALGPSLeapSeconds( INT4 gpssec );
198 
199 /* Returns the leap seconds TAI-UTC for a given UTC broken down time. */
200 int XLALLeapSecondsUTC( const struct tm *utc );
201 
202 /* Fill in derived fields in a given UTC time structure */
203 struct tm *XLALFillUTC( struct tm *utc );
204 
205 /* Compute Unix epoch time: seconds since 1970 January 1 0h UTC */
206 time_t XLALSecondsSinceUnixEpoch( const struct tm *utc );
207 
208 /* Returns the GPS seconds since the GPS epoch for a specified UTC time structure. */
209 INT4 XLALUTCToGPS( const struct tm *utc );
210 
211 #ifdef SWIG /* SWIG interface directives */
212 SWIGLAL(EMPTY_ARGUMENT(struct tm*, utc));
213 #endif
214 
215 /* Returns a pointer to a tm structure representing the time
216  * specified in seconds since the GPS epoch. */
217 struct tm* XLALGPSToUTC( struct tm *utc, INT4 gpssec );
218 
219 #ifdef SWIG /* SWIG interface directives */
220 SWIGLAL_CLEAR(EMPTY_ARGUMENT(struct tm*, utc));
221 #endif
222 
223 /* Returns the Julian Day JD corresponding to the civil date given in a broken
224  * down time structure (using same time system as input). */
225 REAL8 XLALConvertCivilTimeToJD ( const struct tm *civil );
226 
227 /* Returns the Modified Julian Day MJD corresponding to the date given in a broken down time structure (using same time system as input).*/
228 REAL8 XLALConvertCivilTimeToMJD ( const struct tm *civil );
229 
230 /* deprecated wrapper to XLALModifiedJulianDayUTC() for pylal backwards compatibility (see #1856) */
231 INT4 XLALModifiedJulianDay( const struct tm *utc );
232 /* deprecated wrapper to XLALJulianDayUTC() for pylal backwards compatibility (see #1856) */
233 REAL8 XLALJulianDay( const struct tm *utc );
234 
235 /* Returns the Greenwich mean or aparent sideral time in radians. */
237  const LIGOTimeGPS *gpstime,
238  REAL8 equation_of_equinoxes
239 );
240 
241 /* Returns the Greenwich Mean Sidereal Time in RADIANS for a specified GPS time. */
243  const LIGOTimeGPS *gpstime
244 );
245 
246 /* Returns the GPS time for the given Greenwich mean sidereal time (in radians). */
248  REAL8 gmst,
249  LIGOTimeGPS *gps
250 );
251 
252 /* Returns the GPS time for the given Greenwich sidereal time (in radians). */
254  REAL8 gmst,
255  REAL8 equation_of_equinoxes,
256  LIGOTimeGPS *gps
257 );
258 
259 #ifdef __cplusplus
260 }
261 #endif
262 
263 #endif /* _DATE_H */
int XLALStrToGPS(LIGOTimeGPS *t, const char *nptr, char **endptr)
Parse an ASCII string into a LIGOTimeGPS structure.
Definition: StrToGPS.c:91
char * XLALGPSToStr(char *, const LIGOTimeGPS *t)
Return a string containing the ASCII base 10 representation of a LIGOTimeGPS.
Definition: StrToGPS.c:274
LIGOTimeGPS * XLALGPSTimeNow(LIGOTimeGPS *gpstime)
Populate the LIGOTimeGPS argument with the current system time as returned by time(2) converted to GP...
Definition: GPSTimeNow.c:43
double REAL8
Double precision real floating-point number (8 bytes).
int64_t INT8
Eight-byte signed integer; on some platforms this is equivalent to long int instead.
int32_t INT4
Four-byte signed integer.
REAL8 XLALConvertCivilTimeToJD(const struct tm *civil)
Returns the Julian Day (JD) corresponding to the civil date and time given in a broken down time stru...
int XLALGPSLeapSeconds(INT4 gpssec)
Returns the leap seconds GPS-UTC at a given GPS second.
REAL8 XLALJulianDay(const struct tm *utc)
INT4 XLALUTCToGPS(const struct tm *utc)
Returns the GPS seconds since the GPS epoch for a specified UTC time structure.
int XLALLeapSeconds(INT4 gpssec)
Returns the leap seconds TAI-UTC at a given GPS second.
time_t XLALSecondsSinceUnixEpoch(const struct tm *utc)
Compute Unix epoch time: seconds since 1970 January 1 0h UTC (POSIX:2001 definition of Unix Epoch).
struct tm * XLALFillUTC(struct tm *utc)
Fill in derived fields, e.g.
int XLALLeapSecondsUTC(const struct tm *utc)
Returns the leap seconds TAI-UTC for a given UTC broken down time.
REAL8 XLALConvertCivilTimeToMJD(const struct tm *civil)
Returns the Modified Julian Day MJD corresponding to the civil date and time given in a broken down t...
INT4 XLALModifiedJulianDay(const struct tm *utc)
struct tm * XLALGPSToUTC(struct tm *utc, INT4 gpssec)
Returns a pointer to a tm structure representing the time specified in seconds since the GPS epoch.
LIGOTimeGPS * XLALGreenwichMeanSiderealTimeToGPS(REAL8 gmst, LIGOTimeGPS *gps)
Inverse of XLALGreenwichMeanSiderealTime().
REAL8 XLALGreenwichSiderealTime(const LIGOTimeGPS *gpstime, REAL8 equation_of_equinoxes)
Returns the Greenwich Sidereal Time IN RADIANS corresponding to a specified GPS time.
LIGOTimeGPS * XLALGreenwichSiderealTimeToGPS(REAL8 gmst, REAL8 equation_of_equinoxes, LIGOTimeGPS *gps)
Convenience wrapper of XLALGreenwichMeanSiderealTimeToGPS(), adjusting the input by the equation of e...
REAL8 XLALGreenwichMeanSiderealTime(const LIGOTimeGPS *gpstime)
Convenience wrapper, calling XLALGreenwichSiderealTime() with the equation of equinoxes set to 0.
LIGOTimeGPS * XLALGPSAdd(LIGOTimeGPS *epoch, REAL8 dt)
Adds a double to a GPS time.
Definition: XLALTime.c:131
REAL8 XLALGPSModf(REAL8 *iptr, const LIGOTimeGPS *epoch)
Breaks the GPS time into REAL8 integral and fractional parts, each of which has the same sign as the ...
Definition: XLALTime.c:103
LIGOTimeGPS * XLALGPSDivide(LIGOTimeGPS *gps, REAL8 x)
Divide a GPS time by a number.
Definition: XLALTime.c:290
LIGOTimeGPS * XLALGPSAddGPS(LIGOTimeGPS *epoch, const LIGOTimeGPS *dt)
Adds two GPS times.
Definition: XLALTime.c:117
LIGOTimeGPS * XLALGPSSetREAL8(LIGOTimeGPS *epoch, REAL8 t)
Sets GPS time given GPS seconds as a REAL8.
Definition: XLALTime.c:73
int XLALGPSCmp(const LIGOTimeGPS *t0, const LIGOTimeGPS *t1)
Compares two GPS times.
Definition: XLALTime.c:174
REAL8 XLALGPSGetREAL8(const LIGOTimeGPS *epoch)
Returns the GPS time as a REAL8.
Definition: XLALTime.c:91
LIGOTimeGPS * XLALGPSMultiply(LIGOTimeGPS *gps, REAL8 x)
Multiply a GPS time by a number.
Definition: XLALTime.c:228
REAL8 XLALGPSDiff(const LIGOTimeGPS *t1, const LIGOTimeGPS *t0)
Difference between two GPS times as double.
Definition: XLALTime.c:157
LIGOTimeGPS * XLALGPSSet(LIGOTimeGPS *epoch, INT4 gpssec, INT8 gpsnan)
Sets GPS time given GPS integer seconds and residual nanoseconds.
Definition: XLALTime.c:63
LIGOTimeGPS * XLALINT8NSToGPS(LIGOTimeGPS *epoch, INT8 ns)
Converts nano seconds stored as an INT8 to GPS time.
Definition: XLALTime.c:46
INT8 XLALGPSToINT8NS(const LIGOTimeGPS *epoch)
Converts GPS time to nano seconds stored as an INT8.
Definition: XLALTime.c:36
LIGOTimeGPS * XLALGPSSubGPS(LIGOTimeGPS *t1, const LIGOTimeGPS *t0)
Difference between two GPS times.
Definition: XLALTime.c:144
Detector structure.
Definition: LALDetectors.h:278
This structure stores pointers to a LALDetector and a LIGOTimeGPS.
Definition: Date.h:102
LIGOTimeGPS * p_gps
Pointer to a GPS time structure.
Definition: Date.h:104
const LALDetector * p_detector
pointer to a detector
Definition: Date.h:103
Epoch relative to GPS epoch, see LIGOTimeGPS type for more details.
Definition: LALDatatypes.h:458
enum @1 epoch