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

Global Positioning System (GPS) time

property Invalid

Invalid time scale

TAI()

International Atomic Time (nice because it is monotonically increasing)

TDB()

Barycentric Dynamical Time

TT()

Terrestrial Time

UT1()

UT1

property UTC

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

Parameters:

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

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

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

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

  • min (int) – Minute of hour, in range [0,59] (optional), default is 0

  • sec (float) – floating point second of minute, in range [0,60) (optional), defialt is 0

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

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
datetime(utc: bool = True)

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)

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(dt: datetime.datetime)

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

Parameters:

dt (datetime.datetime) – “datetime.datetime” object to convert

Returns:

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

Return type:

satkit.time

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

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_gregorian(2023, 3, 5, 11, 3,45.453))
2023-03-05 11:03:45.453Z
static from_jd(jd: float, scale: timescale = timescale.UTC)

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)

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 now()

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

to_date()

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]

to_gregorian(scale=timescale.UTC)

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]

to_jd(scale: timescale = timescale.UTC)

Represent time instance as Julian Date with the provided time scale

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

to_mjd(scale: timescale = timescale.UTC)

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

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

to_unixtime()

Represent time as unixtime

(seconds since Jan 1, 1970 UTC)

Includes fractional comopnent of seconds

class satkit.duration

Representation of a time duration

days()

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)

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)

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)

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)

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

Floating point number of hours represented by duration

Returns:

Floating point number of hours represented by duration

Return type:

float

minutes()

Floating point number of minutes represented by duration

Returns:

Floating point number of minutes represented by duration

Return type:

float

seconds()

Floating point number of seconds represented by duration

Returns:

Floating point number of seconds represented by duration

Return type:

float