Time utils
jimgw.core.single_event.time_utils
¤
This module computes a JAX-compatible conversion from GPS to UTC time and Julian day. Following the implementation in LALSuite and Bilby.
The conversion from GPS time to UTC date is typically done using the following packages
- datetime, astropy, numpy
but none of them are JAX-compatible.
There is the new jax_datetime package, but it does not compute the year and month.
See: https://github.com/google/jax-datetime/
GPS_EPOCH: int = 315964800
module-attribute
¤
EPOCH_J2000_0_JD: float = 2451545.0
module-attribute
¤
- Leap seconds list *
- JD and GPS time of leap seconds and the value of TAI-UTC. *
- reference: http://maia.usno.navy.mil/
- http://maia.usno.navy.mil/ser7/tai-utc.dat *
- notes: the list below must be updated whenever a leap second is added
- See also: https://lscsoft.docs.ligo.org/lalsuite/lal/_x_l_a_l_leap_seconds_8h_source.html
- https://data.iana.org/time-zones/data/leap-seconds.list
LEAP_SECONDS = jnp.array([46828800, 78364801, 109900802, 173059203, 252028804, 315187205, 346723206, 393984007, 425520008, 457056009, 504489610, 551750411, 599184012, 820108813, 914803214, 1025136015, 1119744016, 1167264017])
module-attribute
¤
SECONDS_IN_DAY = 24 * 60 * 60
module-attribute
¤
SECONDS_IN_YEAR = 365 * SECONDS_IN_DAY
module-attribute
¤
LEAP_YEAR_SECONDS = 366 * SECONDS_IN_DAY
module-attribute
¤
MONTH_ARRAY = jnp.arange(1, 13)
module-attribute
¤
DAYS_IN_MONTH = jnp.array([31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31])
module-attribute
¤
UNIX_EPOCH_YEAR = 1970
module-attribute
¤
YEAR_ARRAY = jnp.arange(UNIX_EPOCH_YEAR, 2510)
module-attribute
¤
IS_LEAP_YEARS = is_leap_year(YEAR_ARRAY)
module-attribute
¤
LEAP_SEC_ARRAY = jnp.where(IS_LEAP_YEARS, LEAP_YEAR_SECONDS, SECONDS_IN_YEAR)
module-attribute
¤
int_div(a: Int, b: Int) -> Int
¤
This is to emulate the C-style integer division in Python. See: https://stackoverflow.com/a/61386872
n_leap_seconds(date: Int) -> Int
¤
Find the number of leap seconds required for the specified date.
Search in reverse order as in practice, almost all requested times will be after the most recent leap.
The Bilby Cython implementation: NUM_LEAPS: int = 18 n_leaps: int = NUM_LEAPS
if date > LEAP_SECONDS[NUM_LEAPS - 1]: return NUM_LEAPS while (n_leaps > 0) and (date < LEAP_SECONDS[n_leaps - 1]): n_leaps -= 1 return n_leaps
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
date
|
int
|
The date in seconds since the GPS epoch. |
required |
Returns: int: The number of leap seconds.
is_leap_year(year: Int) -> Int
¤
Check whether a year is a leap year.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
year
|
Int
|
The year to check. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Int |
Int
|
1 if the year is a leap year, 0 otherwise (JAX boolean as integer). |
utc_date_from_timestamp(timestamp: Int) -> tuple[Int, Int, Int, Int]
¤
This function converts a UTC timestamp to a UTC date (year, month, day, seconds).
This sole intention of this function is to be JAX-compatible and be used within Jim . While it has been agressively tested against the C-implementation in LAL, and the datetime module, it is advised to use those other modules for other purposes.
Note that the current implementation has an upper limit of year up to 2500, which is sufficient for most practical purposes.
gps_to_utc_date(gps_time: Float) -> tuple[Int, Int, Int, Int]
¤
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
gps_time
|
float
|
The GPS time to convert. |
required |
Returns: tuple (int): A tuple containing the year, month, day, and seconds.
gps_to_julian_day(gps_time: Float) -> Float
¤
Convert from UTC to Julian day, this is a necessary intermediate step in converting from GPS to GMST.
The type-cast on the second is necessary for consistency with the C implementation. Without which the error is of order 0.1.
The int_div function is introduced to emulate the C-style integer division.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
gps_time
|
float
|
The GPS time to convert. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
float |
Float
|
The Julian day corresponding to the given UTC time. |
greenwich_mean_sidereal_time(gps_time: Float) -> Float
¤
Compute the Greenwich Mean Sidereal Time (GMST) from the GPS time.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
gps_time
|
Float
|
GPS time in seconds. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Float |
Float
|
Greenwich Mean Sidereal Time in radians. |
greenwich_sidereal_time(gps_time: Float, equation_of_equinoxes: Float) -> Float
¤
Compute the Greenwich mean sidereal time from the GPS time and equation of equinoxes.
Based on XLALGreenwichSiderealTime in lalsuite/lal/lib/XLALSiderealTime.c.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
gps_time
|
float
|
The GPS time to convert |
required |
equation_of_equinoxes
|
float
|
The equation of equinoxes |
required |
Returns: float: The Greenwich sidereal time in radians.