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

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_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_unixtime() → float

Represent time as unixtime

(seconds since Jan 1, 1970 UTC)

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

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) → 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_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_unixtime(ut: float) → time

Return a time object representing input unixtime

Parameters:

ut (float) – unixtime, UTC seconds since Jan 1, 1970 00:00:00

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

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