Time Representation

The satkit package makes use of a custom time class. This is wrapper around a custom rust class that adds the ability to represent time with different scales, or epochs, which is often necessary in the calculation of astronomical phenomena.

However, all functions in the satkit package that take time as an input can accept either the satkit.time class or the more commonly-used datetime.datetime class. For the latter, times are taken to have the UTC epoch.

class satkit.timescale

Specify time scale used to represent or convert between the “satkit.time” representation of time

Most of the time, these are not needed directly, but various time scales are needed to compute precise rotations between various inertial and Earth-fixed coordinate frames

For an excellent overview, see: https://spsweb.fltops.jpl.nasa.gov/portaldataops/mpg/MPG_Docs/MPG%20Book/Release/Chapter2-TimeScales.pdf

Values:

Invalid: Invalid time scale
UTC: Universal Time Coordinate
TT: Terrestrial Time
UT1: UT1
TAI: International Atomic Time
GPS: Global Positioning System (GPS) time
TDB: Barycentric Dynamical Time

class satkit.time(*py_args)

Bases: object

Representation of an instant in time

This has functionality similar to the “datetime” object, and in fact has the ability to convert to an from the “datetime” object. However, a separate time representation is needed as the “datetime” object does not allow for conversion between various time epochs (GPS, TAI, UTC, UT1, etc…)

Notes

If no arguments are passed in, the created object represents the current time
If year is passed in, month and day must also be passed in
If hour is passed in, minute and second must also be passed in

Args:

year (int, optional)

Gregorian year (e.g., 2024)
month (int, optional)

Gregorian month (1 = January, 2 = February, …)
day (int, optional)

Day of month, beginning with 1
hour (int, optional)

Hour of day, in range [0,23] (optional), default is 0
min (int, optional)

Minute of hour, in range [0,59], default is 0
sec (float, optional)

floating point second of minute, in range [0,60), default is 0
scale (satkit.timescale, optional)

Time scale , default is satkit.timescale.UTC
str (str, optional)

string representation of time, in format “YYYY-MM-DD HH:MM:SS.sssZ” or if other will try to guess

Returns:

satkit.time

Time object representing input date and time, or if no arguments, the current date and time

Example

>>> print(satkit.time(2023, 3, 5, 11, 3, 45.453))
2023-03-05 11:03:45.453Z

>>> print(satkit.time(2023, 3, 5))
2023-03-05 00:00:00.000Z

add_utc_days(days)

Add given number of UTC days to a time object, and return the result

Parameters:: days (float) – Number of days to add
Returns:: Time object representing input time plus given number of days
Return type:: satkit.time

Note:

A UTC days is defined as being exactly 86400 seconds long. This avoids the ambiguity of adding a “day” to a time that has a leap second

as_date()

Return tuple representing as UTC Gegorian date of the time object.

Returns:

tuple[int, int, int]

Tuple with 3 elements representing the Gregorian year, month, and day of the time object

Fractional component of day are truncated Month is in range [1,12] Day is in range [1,31]

as_datetime(utc=True)

Convert object to “datetime.datetime” object representing same instant in time.

Args:

utc (bool, optional)

Whether to make the “datetime.datetime” object represent time in the local timezone or “UTC”. Default is True

Returns:

datetime.datetime

“datetime.datetime” object representing the same instant in time as the “satkit.time” object

Example

>>> dt = satkit.time(2023, 6, 3, 6, 19, 34).as_datetime(True)
>>> print(dt)
2023-06-03 06:19:34+00:00
>>>
>>> dt = satkit.time(2023, 6, 3, 6, 19, 34).as_datetime(False)
>>> print(dt)
2023-06-03 02:19:34

as_gregorian()

Return tuple representing as UTC Gegorian date and time of the time object.

Args:

scale (timescale, optional)

Time scale. Default is satkit.timescale.UTC

Returns:

tuple[int, int, int, int, int, float]

Tuple with 6 elements representing the Gregorian year, month, day, hour, minute, and second of the time object

Month is in range [1,12] Day is in range [1,31]

as_iso8601()

Represent time as ISO 8601 string

Returns:

str

ISO 8601 string representation of time: “YYYY-MM-DDTHH:MM:SS.sssZ”

as_jd(scale=Ellipsis)

Represent time instance as Julian Date with the provided time scale

If no time scale is provided, default is satkit.timescale.UTC

as_mjd(scale=Ellipsis)

Represent time instance as a Modified Julian Date with the provided time scale

If no time scale is provided, default is satkit.timescale.UTC

as_rfc3339()

Represent time as RFC 3339 string

Returns:

str

RFC 3339 string representation of time: “YYYY-MM-DDTHH:MM:SS.sssZ”

as_unixtime()

Represent time as unixtime

(seconds since Jan 1, 1970 UTC, excluding leap seconds)

Includes fractional component of seconds

datetime(utc=True)

Deprecated: use satkit.time.as_datetime().

Convert object to “datetime.datetime” object representing same instant in time.

Args:

utc (bool, optional)

Whether to make the “datetime.datetime” object represent time in the local timezone or “UTC”. Default is True

Returns:

datetime.datetime

“datetime.datetime” object representing the same instant in time as the “satkit.time” object

Example

>>> dt = satkit.time(2023, 6, 3, 6, 19, 34).datetime(True)
>>> print(dt)
2023-06-03 06:19:34+00:00
>>>
>>> dt = satkit.time(2023, 6, 3, 6, 19, 34).datetime(False)
>>> print(dt)
2023-06-03 02:19:34

day_of_year()

Return the 1-based Gregorian day of the year (1 = January 1, 365 = December 31)

Returns:

int

The 1-based day of the year

static from_date(year, month, day)

Return a time object representing the start of the input day (midnight)

Args:

year (int)

Gregorian year (e.g., 2024)
month (int)

Gregorian month (1 = January, 2 = February, …)
day (int)

Day of month, beginning with 1

Returns:

satkit.time

Time object representing the start of the input day (midnight)

static from_datetime(tm)

Convert input “datetime.datetime” object to an “satkit.time” object representing the same instant in time

Args:

dt (datetime.datetime)

“datetime.datetime” object to convert

Returns:

satkit.time

Time object representing the same instant in time as the input “datetime.datetime” object

static from_gps_week_and_second(week, seconds)

Return a time object representing input GPS week and second

Args:

week (int)

GPS week number
sec (float)

GPS seconds of week
scale (timescale, optional)

Time scale. Default is satkit.timescale.GPS

Returns:

satkit.time

Time object representing input GPS week and second

static from_gregorian(year, month, day, hour, min, sec)

Create time object from 6 input arguments representing UTC Gregorian time.

Args:

year (int)

Gregorian year
month (int)

Gregorian month (1 = January, 2 = February, …)
day (int)

Day of month, beginning with 1
hour (int)

Hour of day, in range [0,23]
min (int)

Minute of hour, in range [0,59]
sec (float)

floating point second of minute, in range [0,60)

Returns:

satkit.time

Time object representing input UTC Gregorian time

Example

>>> print(satkit.time.from_gregorian(2023, 3, 5, 11, 3,45.453))
2023-03-05 11:03:45.453Z

static from_jd(jd, scale)

Return a time object representing input Julian date and time scale

Args:

jd (float)

Julian date
scale (timescale, optional)

Time scale. Default is satkit.timescale.UTC

Returns:

satkit.time

Time object representing input Julian date and time scale

static from_mjd(mjd, scale)

Return a time object representing input modified Julian date and time scale

Args:

mjd (float)

Modified Julian date
scale (satkit.timescale, optional)

Time scale. Default is satkit.timescale.UTC

Returns:

satkit.time

Time object representing input modified Julian date and time scale

static from_rfc3339(s)

Create a “time” object from input RFC 3339 string

Args:

rfc (str)

RFC 3339 string representation of time

Notes

RFC 3339 is a subset of ISO 8601
Only allows a subset of the format: “YYYY-MM-DDTHH:MM:SS.sssZ” or “YYYY-MM-DDTHH:MM:SS.ssssssZ”

Returns:

satkit.time

Time object representing input RFC 3339 string

Example

>>> print(satkit.time.from_rfctime("2023-03-05T11:03:45.453Z"))
2023-03-05 11:03:45.453Z

static from_string(s)

Create a “time” object from input string

Args:

str (str)

string representation of time, in format “YYYY-MM-DD HH:MM:SS.sssZ” or if other will try to intelligently parse, but no guarantees

Note

This is probably not what you want. Use with caution.

Returns:

satkit.time

Time object representing input string

Example

>>> print(satkit.time.from_string("2023-03-05 11:03:45.453Z"))
2023-03-05 11:03:45.453Z

static from_unixtime(t)

Return a time object representing input unixtime

Args:

ut (float)

unixtime, UTC seconds since Jan 1, 1970 00:00:00 (leap seconds are not included)

Returns:

satkit.time

Time object representing input unixtime

static now()

Create a “time” object representing the instant of time at the calling of the function.

Returns:

satkit.time

Time object representing the current time

strftime(fmt)

Represent time as string with given format

Args:

format (str)

format of the string

Format Codes:

%Y - year
%m - month with leading zeros (01-12)
%d - day of month with leading zeros (01-31)
%H - hour with leading zeros (00-23)
%M - minute with leading zeros (00-59)
%S - second with leading zeros (00-59)
%f - microsecond, allowing for trailing zeros
%b - abbreviated month name (Jan, Feb, …)
%B - full month name (January, February, …)
%A - full weekday name (Sunday, Monday, …)
%w - weekday as a decimal number (0=Sunday, 1=Monday, …)

Returns:

str

string representation of time

Example

>>> print(satkit.time(2023, 6, 3, 6, 19, 34).strptime("%Y-%m-%d %H:%M:%S"))
2023-06-03 06:19:34

static strptime(s, fmt)

Create a “time” object from input string with given formatting

Args:

str (str)

string representation of time
format (str)

format of the string

Notes:

The format string is a subset of the strptime format string in the Python “datetime” module

Format Codes:

%Y - year
%m - month with leading zeros (01-12)
%d - day of month with leading zeros (01-31)
%H - hour with leading zeros (00-23)
%M - minute with leading zeros (00-59)
%S - second with leading zeros (00-59)
%f - microsecond, allowing for trailing zeros
%b - abbreviated month name (Jan, Feb, …)
%B - full month name (January, February, …)

Returns:

satkit.time

Time object representing input string

Example

# Note the microsecond %f actually is represented as milliseconds in the input string >>> print(satkit.time.strptime(“2023-03-05 11:03:45.453Z”, “%Y-%m-%d %H:%M:%S.%fZ”)) 2023-03-05 11:03:45.453Z

weekday()

Return the day of the week

Returns:

satkit.weekday

Day of the week

class satkit.duration(**kwargs)

Bases: object

Representation of a duration, or interval of time

days

Floating point number of days represented by duration

Returns:

float

Floating point number of days represented by duration

A day is defined as 86,400 seconds

static from_days(d)

Create duration object given input number of days. Note: a day is defined as 86,400 seconds

Args:

d (float)

Number of days

Returns:

satkit.duration

Duration object representing input number of days

static from_hours(d)

Create duration object representing input number of hours

Args:

h (float)

Number of hours

Returns:

satkit.duration

Duration object representing input number of hours

static from_minutes(d)

Create duration object representing input number of minutes

Args:

m (float)

Number of minutes

Returns:

satkit.duration

Duration object representing input number of minutes

static from_seconds(d)

Create duration object representing input number of seconds

Args:

s (float)

Number of seconds

Returns:

satkit.duration

Duration object representing input number of seconds

hours

Floating point number of hours represented by duration

Returns:

float

Floating point number of hours represented by duration

minutes

Floating point number of minutes represented by duration

Returns:

float

Floating point number of minutes represented by duration

seconds

Floating point number of seconds represented by duration

Returns:

float

Floating point number of seconds represented by duration