 |
LAL
7.5.0.1-bede9b2
|
|
|
LAL
7.5.0.1-bede9b2
|
|
XLAL routines for converting civil time structures to GPS times.
Civil time structures, represented in the C library by the struct tm structure, known as a broken down time structure, gives the time by normal measures (hours, minutes, seconds since midnight, day of the month, month of the year, and year). LAL uses seconds since the the GPS epoch as its reference. The GPS epoch is defined to be 0h UTC 6 Jan 1980 in civil time. The process of converting between a civil time and a GPS time is almost done by standard C library functions, though the C library functions use a different reference epoch, which is called the UNIX epoch.
The tricky bits are:
This code does not deal with time zones at all. All civil time structures are taken to be in Coordinated Universal Time or UTC. The user must convert local times into UTC before using these routines.
Leap seconds are accounted for. But since the addition and subtraction of leap seconds is not deterministic, a leap second table needs to be maintained to account for the number of leap seconds in effect at a particular time.
Leap seconds are defined as the difference between UTC and a (yet another) standard of time called the International Atomic Time or TAI. UTC is ultimately determined by the position of the stars, so it is occationally altered by a second to keep the location of fixed points on the celestial sphere correct to within plus or minus 0.9 seconds. TAI, like the GPS time used in LAL, is just the number of seconds since some epoch and is not affected by leap seconds. The difference between TAI and UTC, TAI-UTC, is the number of leap seconds.
Note that UTC is fixed to atomic time, though there are an integer number of leap seconds. The real civil time, as measured in terms of points on the celestial sphere, is UT1. UTC and UT1 are kept within 0.9 seconds of each other by the introduction of leap seconds. But if what you want is UT1 note that UTC can be off by up to about a seconds. For this reason, we assume that accuracy at the second scale is sufficient, so the routines have only second precision. If you need more accuracy, you'll need to be monitoring UT1.
Another way of representing the civil time in in terms of Julian days. There is a routine for converting a civil time into Julian days [in the same time system]. The inverse conversion is not attempted.
Prototypes | |
| static int | delta_tai_utc (INT4 gpssec) |
| int | XLALLeapSeconds (INT4 gpssec) |
| Returns the leap seconds TAI-UTC at a given GPS second. More... | |
| int | XLALGPSLeapSeconds (INT4 gpssec) |
| Returns the leap seconds GPS-UTC at a given GPS second. More... | |
| int | XLALLeapSecondsUTC (const struct tm *utc) |
| Returns the leap seconds TAI-UTC for a given UTC broken down time. More... | |
| struct tm * | XLALFillUTC (struct tm *utc) |
| Fill in derived fields, e.g. More... | |
| time_t | XLALSecondsSinceUnixEpoch (const struct tm *utc) |
| Compute Unix epoch time: seconds since 1970 January 1 0h UTC (POSIX:2001 definition of Unix Epoch). More... | |
| INT4 | XLALUTCToGPS (const struct tm *utc) |
| Returns the GPS seconds since the GPS epoch for a specified UTC time structure. More... | |
| 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. More... | |
| REAL8 | XLALConvertCivilTimeToJD (const struct tm *civil) |
| Returns the Julian Day (JD) corresponding to the civil date and time given in a broken down time structure. More... | |
| REAL8 | XLALConvertCivilTimeToMJD (const struct tm *civil) |
| Returns the Modified Julian Day MJD corresponding to the civil date and time given in a broken down time structure (using the same time system as the input). More... | |
| REAL8 | XLALJulianDay (const struct tm *civil) |
| INT4 | XLALModifiedJulianDay (const struct tm *civil) |
|
static |
Definition at line 101 of file XLALCivilTime.c.
| int XLALLeapSeconds | ( | INT4 | gpssec | ) |
Returns the leap seconds TAI-UTC at a given GPS second.
| gpssec | [In] Seconds relative to GPS epoch. |
Definition at line 123 of file XLALCivilTime.c.
| int XLALGPSLeapSeconds | ( | INT4 | gpssec | ) |
Returns the leap seconds GPS-UTC at a given GPS second.
| gpssec | [In] Seconds relative to GPS epoch. |
Definition at line 144 of file XLALCivilTime.c.
| int XLALLeapSecondsUTC | ( | const struct tm * | utc | ) |
Returns the leap seconds TAI-UTC for a given UTC broken down time.
| utc | [In] UTC as a broken down time. |
Definition at line 160 of file XLALCivilTime.c.
| struct tm* XLALFillUTC | ( | struct tm * | utc | ) |
Fill in derived fields, e.g.
tm_wday and tm_yday, in a given UTC time structure
| utc | [In] UTC time in a broken down time structure. |
Definition at line 187 of file XLALCivilTime.c.
| time_t XLALSecondsSinceUnixEpoch | ( | const struct tm * | utc | ) |
Compute Unix epoch time: seconds since 1970 January 1 0h UTC (POSIX:2001 definition of Unix Epoch).
Note: all fields of utc must be filled; you may need to use XLALFillUTC().
| utc | [In] UTC time in a broken down time structure. |
Definition at line 272 of file XLALCivilTime.c.
| INT4 XLALUTCToGPS | ( | const struct tm * | utc | ) |
Returns the GPS seconds since the GPS epoch for a specified UTC time structure.
| utc | [In] UTC time in a broken down time structure. |
Definition at line 296 of file XLALCivilTime.c.
| 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.
| utc | [Out] Pointer to tm struct where result is stored. |
| gpssec | [In] Seconds since the GPS epoch. |
Definition at line 335 of file XLALCivilTime.c.
| REAL8 XLALConvertCivilTimeToJD | ( | const struct tm * | civil | ) |
Returns the Julian Day (JD) corresponding to the civil date and time given in a broken down time structure.
The time system of the returned JD is the same as that of the input time.
See [25] and [13] for details. First, some definitions:
Mean Julian Year = 365.25 days Julian Epoch = 1 Jan 4713BCE, 12:00 GMT (4713 BC Jan 01d.5 GMT) Fundamental Epoch J2000.0 = 2001-01-01.5 TDB
Julian Date is the amount of time elapsed since the Julian Epoch, measured in days and fractions of a day. There are a couple of complications arising from the length of a year: the Tropical Year is 365.2422 days. First, the Gregorian correction where 10 days (1582-10-05 through 1582-10-14) were eliminated. Second, leap years: years ending with two zeroes (e.g., 1700, 1800) are leap only if divisible by 400; so, 400 civil years contain 400 * 365.25 - 3 = 146097 days. So, the Julian Date of J2000.0 is JD 2451545.0, and thus the Julian Epoch = J2000.0 + (JD - 2451545) / 365.25, i.e., number of years elapsed since J2000.0.
One algorithm for computing the Julian Day is from [27] based on a formula in [25] where the algorithm is due to [10] and `‘compactified’' by P. M. Muller and R. N. Wimberly. The formula is
\[ jd = 367 \times y - 7 \times (y + (m + 9)/12)/4 - 3 \times ((y + (m - 9)/7)/100 + 1)/4 + 275 \times m/9 + d + 1721029 \]
where jd is the Julian day number, y is the year, m is the month (1-12), and d is the day (1-31). This formula is valid only for JD > 0, i.e., after -4713 Nov 23 = 4712 BCE Nov 23.
A shorter formula from the same reference, but which only works for dates since 1900 March is:
\[ jd = 367 \times y - 7 \times (y + (m + 9)/12)/4 + 275 \times m/9 + d + 1721014 \]
We will use this shorter formula since there is unlikely to be any analyzable data from before 1900 March.
| civil | [In] civil time in a broken down time structure. |
Definition at line 407 of file XLALCivilTime.c.
| REAL8 XLALConvertCivilTimeToMJD | ( | const struct tm * | civil | ) |
Returns the Modified Julian Day MJD corresponding to the civil date and time given in a broken down time structure (using the same time system as the input).
Note:
| civil | [In] civil time in a broken down time structure. |
Definition at line 440 of file XLALCivilTime.c.
| REAL8 XLALJulianDay | ( | const struct tm * | civil | ) |
(see #1856)
Definition at line 449 of file XLALCivilTime.c.
| INT4 XLALModifiedJulianDay | ( | const struct tm * | civil | ) |
(see #1856)
Definition at line 459 of file XLALCivilTime.c.
1.9.1