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 reprsent time with different scales, or epochs, which is often necessary in the calcluation 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

GPS() → int

Global Positioning System (GPS) time

property Invalid: int

Invalid time scale

TAI() → int

International Atomic Time (nice because it is monotonically increasing)

TDB() → int

Barycentric Dynamical Time

TT() → int

Terrestrial Time

UT1() → int

UT1

property UTC: int

Universal Time Coordinate

class satkit.time(*args)

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

Parameters:

  • 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:

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

Return type:

satkit.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
as_date() → Tuple[int, int, int]

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

Returns:

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

Return type:

tuple[int, int, int]

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

as_gregorian(scale=timescale.UTC) → Tuple[int, int, int, int, int, float]

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

Parameters:

scale (timescale, optional) – Time scale. Default is satkit.timescale.UTC

Returns:

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

Return type:

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

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

as_iso8601() → str

Represent time as ISO 8601 string

Returns:

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

Return type:

str

as_jd(scale: timescale = timescale.UTC) → float

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: timescale = timescale.UTC) → float

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() → str

Represent time as RFC 3339 string

Returns:

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

Return type:

str

as_unixtime() → float

Represent time as unixtime

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

Includes fractional comopnent of seconds

datetime(utc: bool = True) → datetime.datetime

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

Parameters:

utc (bool, optional) – Whether to make the “datetime.datetime” object represent time in the local timezone or “UTC”. Default is True

Returns:

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

Return type:

datetime.datetime

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
static from_date(year: int, month: int, day: int) → time

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

Parameters:

  • year (int) – Gregorian year (e.g., 2024)

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

  • day (int) – Day of month, beginning with 1

Returns:

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

Return type:

satkit.time

static from_datetime(self, year: int, month: int, day: int, hour: int, min: int, sec: float, scale: timescale = timescale.UTC) → time

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

Parameters:

  • 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)

  • scale (timescale, optional) – Time scale. Default is satkit.timescale.UTC

Returns:

Time object representing input UTC Gregorian time

Return type:

satkit.time

Example

>>> print(satkit.time.from_datetime(2023, 3, 5, 11, 3,45.453))
2023-03-05 11:03:45.453Z
static from_gps_week_and_second(week: int, sec: float) → time

Return a time object representing input GPS week and second

Parameters:

  • week (int) – GPS week number

  • sec (float) – GPS seconds of week

  • scale (timescale, optional) – Time scale. Default is satkit.timescale.GPS

Returns:

Time object representing input GPS week and second

Return type:

satkit.time

static from_gregorian(year: int, month: int, day: int, hour: int, min: int, sec: float) → time

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

Parameters:

  • 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:

Time object representing input UTC Gregorian time

Return type:

satkit.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: float, scale: timescale = timescale.UTC) → time

Return a time object representing input Julian date and time scale

Parameters:

  • jd (float) – Julian date

  • scale (timescale, optional) – Time scale. Default is satkit.timescale.UTC

Returns:

Time object representing input Julian date and time scale

Return type:

satkit.time

static from_mjd(mjd: float, scale: timescale = timescale.UTC) → time

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

Parameters:

  • mjd (float) – Modified Julian date

  • scale (satkit.timescale, optional) – Time scale. Default is satkit.timescale.UTC

Returns:

Time object representing input modified Julian date and time scale

Return type:

satkit.time

static from_rfc3339(rfc: str) → time

Create a “time” object from input RFC 3339 string

Parameters:

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:

Time object representing input RFC 3339 string

Return type:

satkit.time

Example

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

Create a “time” object from input string

Parameters:

  • str (str) – string representation of time, in format “YYYY-MM-DD HH:MM:SS.sssZ” or if other will try

  • parse (to intelligently)

  • guarantees (but no)

Note

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

Returns:

Time object representing input string

Return type:

satkit.time

Example

>>> print(satkit.time.from_string("2023-03-05 11:03:45.453Z"))
2023-03-05 11:03:45.453Z
static from_unixtime(ut: float) → time

Return a time object representing input unixtime

Parameters:

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

Returns:

Time object representing input unixtime

Return type:

satkit.time

static now() → time

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

Returns:

Time object representing the current time

Return type:

satkit.time

strftime(format: str) → str

Represent time as string with given format

Parameters:

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:

string representation of time

Return type:

str

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(str: time.strptime.str, format: time.strptime.str) → time

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

Parameters:

  • 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:

Time object representing input string

Return type:

satkit.time

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

class satkit.duration

Representation of a time duration

days() → float

Floating point number of days represented by duration

Returns:

Floating point number of days represented by duration

Return type:

float

A day is defined as 86,400 seconds

static from_days(d: float) → duration

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

Parameters:

d (float) – Number of days

Returns:

Duration object representing input number of days

Return type:

satkit.duration

static from_hours(h: float) → duration

Create duration object representing input number of hours

Parameters:

h (float) – Number of hours

Returns:

Duration object representing input number of hours

Return type:

satkit.duration

static from_minutes(m: float) → duration

Create duration object representing input number of minutes

Parameters:

m (float) – Number of minutes

Returns:

Duration object representing input number of minutes

Return type:

satkit.duration

static from_seconds(s: float) → duration

Create duration object representing input number of seconds

Parameters:

s (float) – Number of seconds

Returns:

Duration object representing input number of seconds

Return type:

satkit.duration

hours() → float

Floating point number of hours represented by duration

Returns:

Floating point number of hours represented by duration

Return type:

float

minutes() → float

Floating point number of minutes represented by duration

Returns:

Floating point number of minutes represented by duration

Return type:

float

seconds() → float

Floating point number of seconds represented by duration

Returns:

Floating point number of seconds represented by duration

Return type:

float