time_conversions module

Timing conversions between reference frames for times.

Frame options are described in detail at on the documentation website: https://gnss-lib-py.readthedocs.io/en/latest/reference/reference.html#timing-conventions

Frame options include:

• gps_millis : GPS milliseconds

• unix_millis : UNIX milliseconds

• tow : Time of week which includes GPS week and time of week in secs

• datetime : Time assumed to be in UTC timezone

time_conversions.datetime_to_gps_millis(t_datetimes)

Convert datetime to milliseconds since GPS Epoch.

GPS Epoch starts at the 6th January 1980. If no timezone is specified, assumes UTC as timezone and returns milliseconds in GPS time frame of reference by adding leap seconds. Leap seconds are always added because UTC time is adjusted for leap seconds while GPS milliseconds are not.

Parameters:

t_datetime (datetime.datetime or array-like of datetime.datetime) – UTC time as a datetime object.

Returns:

gps_millis – Milliseconds since GPS Epoch (6th January 1980 GPS). Either float or np.ndarray with dtype = float.

Return type:

float or np.ndarray

time_conversions.datetime_to_tow(t_datetimes)

Convert Python datetime object to GPS Week and time of week.

For the gnss_lib_py convention, except for specific applications, we assume that the time recorded by the datetime.datetime object is UTC time. As a result, on converting to TOW, we add leap seconds.

Parameters:

t_datetimes (datetime.datetime or array-like of datetime.datetime) – Datetime object for Time of Clock, assumed to be in UTC time frame.

Returns:

• gps_weeks (int or np.ndarray) – GPS week. Either int or np.ndarray with dtype = int.

• tows (float or np.ndarray) – GPS time of week [s]. Either float or np.ndarray with dtype = float.

time_conversions.datetime_to_unix_millis(t_datetimes)

Convert datetime to milliseconds since UNIX Epoch (1/1/1970 UTC).

If no timezone is specified, assumes UTC as timezone. This function does not add leapseconds to the datetime to get unix millis.

Parameters:

t_datetimes (datetime.datetime or array-like of datetime.datetime) – UTC time as a datetime object.

Returns:

unix_millis – Milliseconds since UNIX Epoch (1/1/1970 UTC). Either float or np.ndarray with dtype = float.

Return type:

float or np.ndarray

time_conversions.get_leap_seconds(gps_time)

Compute leap seconds to be added in time conversions.

Computed by comparing the time to LEAPSECONDS_TABLE.

Parameters:

gps_time (float or datetime.datetime) – Time of clock can be float [ms] or datetime.datetime object.

Returns:

out_leapsecs – Leap seconds at given time [s].

Return type:

float

time_conversions.gps_datetime_to_gps_millis(t_gps)

Convert datetime in GPS time of reference to milliseconds since GPS Epoch.

GPS Epoch starts at the 6th January 1980. This function assumes that the input datetime is in the GPS time frame of reference and converts that to GPS milliseconds.

Parameters:

t_gps (datetime.datetime or array-like of datetime.datetime) – GPS time as a datetime object.

Returns:

gps_millis – Milliseconds since GPS Epoch (6th January 1980 GPS). Either float or np.ndarray with dtype = float.

Return type:

float or np.ndarray

time_conversions.gps_millis_to_datetime(gps_millis)

Convert milliseconds since GPS epoch to datetime.

GPS millis is from the start of the GPS in GPS reference. The initial GPS epoch is defined by the variable GPS_EPOCH_0 at which the week number is assumed to be 0.

The datetime instances are assumed to be in UTC time and leap seconds are removed from the gps_millis as a result.

Parameters:

gps_millis (float or array-like of float) – Float object for Time of Clock [ms].

Returns:

t_utc – UTC time as a datetime object. Either datetime.datetime or np.ndarray with dtype = datetime.datetime.

Return type:

datetime.datetime or np.ndarray

time_conversions.gps_millis_to_tow(millis)

Convert milliseconds since GPS epoch to GPS week number and time.

The initial GPS epoch is defined by the variable GPS_EPOCH_0 at which the week number is assumed to be 0.

Both of these times are in the GPS time frame of reference and as a result, leap seconds do not need to be accounted for here.

Parameters:

millis (float or array-like of floats) – Float object for Time of Clock [ms].

Returns:

• gps_weeks (int or np.ndarray) – GPS week. Either int or np.ndarray with dtype = int.

• tows (float or np.ndarray) – GPS time of week [s]. Either float or np.ndarray with dtype = float.

time_conversions.gps_to_unix_millis(gps_millis)

Convert milliseconds since GPS epoch to UNIX millis.

GPS millis is from the start of the GPS in GPS reference. The initial GPS epoch is defined by the variable GPS_EPOCH_0 at which the week number is assumed to be 0.

Leap seconds are removed from gps_millis because of the difference between how GPS and Unix time handle milliseconds.

Parameters:

gps_millis (float or array-like of float) – Float object for Time of Clock [ms].

Returns:

unix_millis – Milliseconds since UNIX Epoch (1/1/1970 UTC). Either float or np.ndarray with dtype = float.

Return type:

float or np.ndarray

time_conversions.tow_to_datetime(gps_weeks, tows)

Convert GPS week and time of week (seconds) to datetime.

Because we assume that datetime.datetime objects are in UTC time, leap seconds are removed from the given TOW.

Parameters:

• gps_weeks (int or array-like of ints) – GPS week.

• tows (float or array-like of floats) – GPS time of week [s].

Returns:

t_datetimes – Datetime in UTC timezone, with or without leap seconds based on flag. If single gps_weeks, tows is given, output is single datetime.datetime instance and np.ndarray of datetime.datetime if multiple inputs are given.

Return type:

datetime.datetime or np.ndarray<datetime.datetime>

time_conversions.tow_to_gps_millis(gps_week, tow)

Convert GPS week and time of week (seconds) to GPS milliseconds.

Convert GPS week and time of week (seconds) to milliseconds since GPS epoch. No leap seconds adjustments are made because both times are in the same frame of reference.

Parameters:

• gps_week (int or array-like of int) – GPS week.

• tow (float or array-like of floats) – GPS time of week [s].

Returns:

gps_millis – Milliseconds since GPS epoch (midnight 6th January, 1980 UTC with leap seconds). Either float or np.ndarray with dtype = float.

Return type:

float or np.ndarray

time_conversions.tow_to_unix_millis(gps_weeks, tows)

Convert GPS week and time of week (seconds) to UNIX milliseconds.

Convert GPS week and time of week (seconds) to milliseconds since UNIX epoch. Leap seconds will always be removed from tow because GPS millis is a continuous time reference while unix millis adjust for leap seconds.

Parameters:

• gps_weeks (int or array-like of int) – GPS week.

• tows (float or array-like of int) – GPS time of week [s].

Returns:

unix_millis – Milliseconds since UNIX epoch (midnight 1/1/1970 UTC). Either float or np.ndarray with dtype = float.

Return type:

float or np.ndarray

time_conversions.tzinfo_to_utc(t_datetime)

Raises warning if time doesn’t have timezone and converts to UTC.

If datetime object is offset-naive, then this function will interpret the timezone as UTC and add the appropriate timezone info.

Parameters:

t_datetime (datetime.datetime) – Datetime object with no timezone, UTC timezone, or local timezone.

Returns:

t_datetime – Datetime object in UTC, added if no timezone was given and converted to UTC if datetime was in local timezone.

Return type:

datetime.datetime

time_conversions.unix_millis_to_datetime(unix_millis)

Convert milliseconds since UNIX epoch (1/1/1970) to UTC datetime.

Parameters:

unix_millis (float or int or np.ndarray) – Milliseconds that have passed since UTC epoch. np.ndarray of float or int to be passed in for cases with multiple values.

Returns:

t_utc – UTC time as a datetime object. Either datetime.datetime or np.ndarray with dtype = datetime.datetime.

Return type:

datetime.datetime or np.ndarray

time_conversions.unix_millis_to_tow(unix_millis)

Convert UNIX milliseconds to GPS week and time of week (seconds).

UNIX milliseconds are since UNIX epoch (1/1/1970). Always adds leap seconds to convert from UTC to GPS time reference.

Parameters:

unix_millis (float or array-like of float) – Milliseconds that have passed since UTC epoch.

Returns:

• gps_week (int or np.ndarray) – GPS week. Either int or np.ndarray with dtype = int.

• tow (float or np.ndarray) – GPS time of week [s]. Either float or np.ndarray with dtype = float.

time_conversions.unix_to_gps_millis(unix_millis)

Convert milliseconds since UNIX epoch (1/1/1970) to GPS millis.

Adds leap seconds by default but time can be kept in UTC frame by setting to False.

Parameters:

unix_millis (float or array-like of float) – Milliseconds that have passed since UTC epoch.

Returns:

gps_millis – Milliseconds since GPS Epoch (6th January 1980 GPS). Either int or np.ndarray with dtype = int.

Return type:

int or np.ndarray