"""
Module to contain time conversions used in pycbc
"""
from datetime import timezone
from astropy.time import Time
def _ensure_utc_datetime(date):
"""
Ensure a datetime is timezone-aware in UTC.
- If `date` is naive, assume it represents UTC and attach UTC tzinfo.
- If `date` is timezone-aware, convert it to UTC.
"""
if date.tzinfo is None:
return date.replace(tzinfo=timezone.utc)
return date.astimezone(timezone.utc)
[docs]
def gps_to_utc_datetime(gps):
"""
Convert a GPS time to a UTC datetime.
Parameters
----------
gps : float
The GPS time to convert.
Returns
-------
datetime
"""
dt = Time(gps, format="gps", scale="utc").to_datetime()
return _ensure_utc_datetime(dt)
def datetime_to_str(date, format="%Y-%m-%d %H:%M:%S"):
"""
Convert a datetime to a string.
Parameters
----------
date : datetime
The datetime to convert.
format : str
The format to use for the string. Default is yyyy-mm-dd HH:MM:SS.
Supply as a format according to datetime documentation
https://docs.python.org/3/library/datetime.html#strftime-strptime-behavior
Returns
-------
str
"""
return date.strftime(format)
[docs]
def gps_to_utc_str(gps, format="%Y-%m-%d %H:%M:%S"):
"""
Convert a GPS time to a UTC string.
Parameters
----------
gps : float
The GPS time to convert.
format : str
Returns
-------
str
"""
return datetime_to_str(gps_to_utc_datetime(gps), format=format)
[docs]
def strip_time_from_date(date):
"""
Strip the time from a datetime object.
Parameters
----------
date : datetime
The datetime object to strip the time from.
Returns
-------
datetime
"""
stripped = date.replace(hour=0, minute=0, second=0, microsecond=0)
return _ensure_utc_datetime(stripped)
[docs]
def strip_time_from_gps(gps, format="%Y-%m-%d"):
"""
Round a GPS time to the midnight of the same UTC day, and return the date of that day as a string.
Parameters
----------
gps : float
The GPS time to strip the time from.
Returns
-------
float, str
"""
gps_datetime = gps_to_utc_datetime(gps)
midnight_datetime = strip_time_from_date(gps_datetime)
return utc_datetime_to_gps(midnight_datetime), datetime_to_str(
midnight_datetime, format=format
)
[docs]
def utc_datetime_to_gps(date):
"""
Convert a UTC datetime to a GPS time.
Parameters
----------
date : datetime
The UTC datetime to convert.
Returns
-------
float
"""
date_utc = _ensure_utc_datetime(date)
return float(Time(date_utc, format="datetime", scale="utc").gps)
[docs]
def gps_now():
"""
Return the current GPS time as a float using Astropy.
Returns
-------
float
"""
return float(Time.now().gps)
[docs]
def gmst_accurate(gps_time):
"""
Calculate the Greenwich Mean Sidereal Time in radians
for a given GPS time.
Parameters
----------
gps_time : float
The GPS time to calculate the GMST for.
Returns
-------
float
"""
gmst = (
Time(gps_time, format="gps", scale="utc", location=(0, 0))
.sidereal_time("mean")
.rad
)
return gmst
__all__ = [
"gmst_accurate",
"gps_now",
"gps_to_utc_datetime",
"gps_to_utc_str",
"strip_time_from_date",
"strip_time_from_gps",
"utc_datetime_to_gps",
]