Time Representation¶

The satkit package makes use of a custom time class. This is a 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.

`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

`Invalid` `class-attribute` ¶

Invalid time scale

`UTC` `class-attribute` ¶

Universal Time Coordinate

`TT` `class-attribute` ¶

Terrestrial Time

`UT1` `class-attribute` ¶

UT1

`TAI` `class-attribute` ¶

International Atomic Time (nice because it is monotonically increasing)

`GPS` `class-attribute` ¶

Global Positioning System (GPS) time

`TDB` `class-attribute` ¶

Barycentric Dynamical Time

`time` ¶

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

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

`init(year=..., month=..., day=..., hour=0, min=0, sec=0.0, *, scale=..., str=...)` ¶

Create a time object representing input date and 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:

Name	Type	Description	Default
`year`	`int`	Gregorian year (e.g., 2024)	`...`
`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], default is 0	`0`
`min`	`int`	Minute of hour, in range [0,59], default is 0	`0`
`sec`	`float`	Floating point second of minute, in range [0,60), default is 0	`0.0`
`scale`	`timescale`	Time scale, default is satkit.timescale.UTC	`...`
`str`	`str`	String representation of time, in format "YYYY-MM-DD HH:MM:SS.sssZ" or if other will try to guess	`...`

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

`now()` `staticmethod` ¶

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

Returns:

Type	Description
`time`	satkit.time: Time object representing the current time

`from_string(str)` `staticmethod` ¶

Create a "time" object from input string

Parameters:

Name	Type	Description	Default
`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	required

Note

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

Returns:

Type	Description
`time`	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

`from_rfc3339(rfc)` `staticmethod` ¶

Create a "time" object from input RFC 3339 string

Parameters:

Name	Type	Description	Default
`rfc`	`str`	RFC 3339 string representation of time	required

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:

Type	Description
`time`	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

`strptime(str, format)` `staticmethod` ¶

Create a "time" object from input string with given formatting

Parameters:

Name	Type	Description	Default
`str`	`str`	string representation of time	required
`format`	`str`	format of the string	required

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:

Type	Description
`time`	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

`from_date(year, month, day)` `staticmethod` ¶

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

Parameters:

Name	Type	Description	Default
`year`	`int`	Gregorian year (e.g., 2024)	required
`month`	`int`	Gregorian month (1 = January, 2 = February, ...)	required
`day`	`int`	Day of month, beginning with 1	required

Returns:

Type	Description
`time`	satkit.time: Time object representing the start of the input day (midnight)

Example

t = satkit.time.from_date(2023, 6, 15)
print(t)
# 2023-06-15 00:00:00.000Z

`from_jd(jd, scale=timescale.UTC)` `staticmethod` ¶

Return a time object representing input Julian date and time scale

Parameters:

Name	Type	Description	Default
`jd`	`float`	Julian date	required
`scale`	`timescale`	Time scale. Default is satkit.timescale.UTC	`UTC`

Returns:

Type	Description
`time`	satkit.time: Time object representing input Julian date and time scale

Example

t = satkit.time.from_jd(2460000.5)
print(t)

`from_unixtime(ut)` `staticmethod` ¶

Return a time object representing input unixtime

Parameters:

Name	Type	Description	Default
`ut`	`float`	unixtime, UTC seconds since Jan 1, 1970 00:00:00 (leap seconds are not included)	required

Returns:

Type	Description
`time`	satkit.time: Time object representing input unixtime

Example

t = satkit.time.from_unixtime(1700000000)
print(t)
# 2023-11-14 22:13:20.000Z

`from_gps_week_and_second(week, sec)` `staticmethod` ¶

Return a time object representing input GPS week and second

Parameters:

Name	Type	Description	Default
`week`	`int`	GPS week number	required
`sec`	`float`	GPS seconds of week	required

Returns:

Type	Description
`time`	satkit.time: Time object representing input GPS week and second

`weekday()` ¶

Return the day of the week

Returns:

Type	Description
`weekday`	satkit.weekday: Day of the week

`day_of_year()` ¶

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

Returns:

Name	Type	Description
`int`	`int`	The 1-based day of the year

`from_mjd(mjd, scale=timescale.UTC)` `staticmethod` ¶

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

Parameters:

Name	Type	Description	Default
`mjd`	`float`	Modified Julian date	required
`scale`	`timescale`	Time scale. Default is satkit.timescale.UTC	`UTC`

Returns:

Type	Description
`time`	satkit.time: Time object representing input modified Julian date and time scale

Example

t = satkit.time.from_mjd(60000.0)
print(t)

`as_date()` ¶

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

Returns:

Type	Description
`tuple[int, int, int]`	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_gregorian(scale=timescale.UTC)` ¶

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

Parameters:

Name	Type	Description	Default
`scale`	`timescale`	Time scale. Default is satkit.timescale.UTC	`UTC`

Returns:

Type	Description
`tuple[int, int, int, int, int, float]`	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]

`from_gregorian(year, month, day, hour, min, sec)` `staticmethod` ¶

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

Parameters:

Name	Type	Description	Default
`year`	`int`	Gregorian year	required
`month`	`int`	Gregorian month (1 = January, 2 = February, ...)	required
`day`	`int`	Day of month, beginning with 1	required
`hour`	`int`	Hour of day, in range [0,23]	required
`min`	`int`	Minute of hour, in range [0,59]	required
`sec`	`float`	floating point second of minute, in range [0,60)	required

Returns:

Type	Description
`time`	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

`as_datetime(utc=True)` ¶

Convert object to "datetime.datetime" object representing same instant in time.

Parameters:

Name	Type	Description	Default
`utc`	`bool`	Whether to make the "datetime.datetime" object represent time in the local timezone or "UTC". Default is True	`True`

Returns:

Type	Description
`datetime`	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

`datetime(utc=True)` ¶

Deprecated: use :meth:satkit.time.as_datetime.

Convert object to "datetime.datetime" object representing same instant in time.

Parameters:

Name	Type	Description	Default
`utc`	`bool`	Whether to make the "datetime.datetime" object represent time in the local timezone or "UTC". Default is True	`True`

Returns:

Type	Description
`datetime`	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

`as_mjd(scale=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

`as_jd(scale=timescale.UTC)` ¶

Represent time instance as Julian Date with the provided time scale

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

`as_unixtime()` ¶

Represent time as unixtime

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

Includes fractional component of seconds

`as_iso8601()` ¶

Represent time as ISO 8601 string

Returns:

Name	Type	Description
`str`	`str`	ISO 8601 string representation of time: "YYYY-MM-DDTHH:MM:SS.sssZ"

`as_rfc3339()` ¶

Represent time as RFC 3339 string

Returns:

Name	Type	Description
`str`	`str`	RFC 3339 string representation of time: "YYYY-MM-DDTHH:MM:SS.sssZ"

`strftime(format)` ¶

Represent time as string with given format

Parameters:

Name	Type	Description	Default
`format`	`str`	format of the string	required

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:

Name	Type	Description
`str`	`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

`le(other)` ¶

Compare two time objects for less than or equal to

Parameters:

Name	Type	Description	Default
`other`	`time`	time object to compare with	required

Returns:

Name	Type	Description
`bool`	`bool`	True if "self" time is less than or equal to "other" time, False otherwise

`lt(other)` ¶

Compare two time objects for less than

Parameters:

Name	Type	Description	Default
`other`	`time`	time object to compare with	required

Returns:

Name	Type	Description
`bool`	`bool`	True if "self" time is less than "other" time, False otherwise

`ge(other)` ¶

Compare two time objects for greater than or equal to

Parameters:

Name	Type	Description	Default
`other`	`time`	time object to compare with	required

Returns:

Name	Type	Description
`bool`	`bool`	True if "self" time is greater than or equal to "other" time, False otherwise

`gt(other)` ¶

Compare two time objects for greater than

Parameters:

Name	Type	Description	Default
`other`	`time`	time object to compare with	required

Returns:

Name	Type	Description
`bool`	`bool`	True if "self" time is greater than "other" time, False otherwise

`eq(value)` ¶

Compare two time objects for equality

Parameters:

Name	Type	Description	Default
`value`	`object`	object to compare with	required

Returns:

Name	Type	Description
`bool`	`bool`	True if "self" time is equal to "value", False otherwise

`ne(value)` ¶

Compare two time objects for inequality

Parameters:

Name	Type	Description	Default
`value`	`object`	object to compare with	required

Returns:

Name	Type	Description
`bool`	`bool`	True if "self" time is not equal to "value", False otherwise

`duration` ¶

Representation of a duration, or interval of time

`days` `property` ¶

Floating point number of days represented by duration

Returns:

Name	Type	Description
`float`	`float`	Floating point number of days represented by duration

A day is defined as 86,400 seconds

`hours` `property` ¶

Floating point number of hours represented by duration

Returns:

Name	Type	Description
`float`	`float`	Floating point number of hours represented by duration

`minutes` `property` ¶

Floating point number of minutes represented by duration

Returns:

Name	Type	Description
`float`	`float`	Floating point number of minutes represented by duration

`seconds` `property` ¶

Floating point number of seconds represented by duration

Returns:

Name	Type	Description
`float`	`float`	Floating point number of seconds represented by duration

`init(*, days=0, hours=0, minutes=0, seconds=0.0, microseconds=0.0)` ¶

Create a duration object representing input time duration

Parameters:

Name	Type	Description	Default
`days`	`float`	Number of days, default is 0	`0`
`hours`	`float`	Number of hours, default is 0	`0`
`minutes`	`float`	Number of minutes, default is 0	`0`
`seconds`	`float`	Number of seconds, default is 0.0	`0.0`
`microseconds`	`float`	Number of microseconds, default is 0.0	`0.0`

Notes

If no arguments are passed in, the created object represents a duration of 0 seconds

Example

print(satkit.duration(days=1, hours=2, minutes=3, seconds=4.5))
# Duration: 1 days, 2 hours, 3 minutes, 4.500 seconds

`from_days(d)` `staticmethod` ¶

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

Parameters:

Name	Type	Description	Default
`d`	`float`	Number of days	required

Returns:

Type	Description
`duration`	satkit.duration: Duration object representing input number of days

Example

d = satkit.duration.from_days(1.5)
print(d.hours)
# 36.0

`from_seconds(s)` `staticmethod` ¶

Create duration object representing input number of seconds

Parameters:

Name	Type	Description	Default
`s`	`float`	Number of seconds	required

Returns:

Type	Description
`duration`	satkit.duration: Duration object representing input number of seconds

Example

d = satkit.duration.from_seconds(3600)
print(d.hours)
# 1.0

`from_minutes(m)` `staticmethod` ¶

Create duration object representing input number of minutes

Parameters:

Name	Type	Description	Default
`m`	`float`	Number of minutes	required

Returns:

Type	Description
`duration`	satkit.duration: Duration object representing input number of minutes

`from_hours(h)` `staticmethod` ¶

Create duration object representing input number of hours

Parameters:

Name	Type	Description	Default
`h`	`float`	Number of hours	required

Returns:

Type	Description
`duration`	satkit.duration: Duration object representing input number of hours

`sub(other)` ¶

Take the difference between two durations

Parameters:

Name	Type	Description	Default
`other`	`duration`	duration to subtract from the current duration	required

Returns:

Name	Type	Description
`duration`	`duration`	Duration object representing the difference between the two durations

Example

print(duration.from_hours(1) - duration.from_minutes(1))
# Duration: 59 minutes, 0.000 seconds

`mul(other)` ¶

Multiply (or scale) duration by given value

Parameters:

Name	Type	Description	Default
`other`	`float`	value by which to multiply duration	required

Returns:

Name	Type	Description
`duration`	`duration`	Duration object representing the input duration scaled by the input value

Example

print(duration.from_days(1) * 2.5)
# Duration: 2 days, 12 hours, 0 minutes, 0.000 seconds

`gt(other)` ¶

Compare two durations for greater than

Parameters:

Name	Type	Description	Default
`other`	`duration`	duration to compare with	required

Returns: bool: True if "self" duration is greater than "other" duration, False otherwise

Example

print(duration.from_hours(1) > duration.from_minutes(30))
# True

`lt(other)` ¶

Compare two durations for less than

Parameters:

Name	Type	Description	Default
`other`	`duration`	duration to compare with	required

Returns: bool: True if "self" duration is less than "other" duration, False otherwise

Example

print(duration.from_hours(1) < duration.from_minutes(30))
# False

`ge(other)` ¶

Compare two durations for greater than or equal to

Parameters:

Name	Type	Description	Default
`other`	`duration`	duration to compare with	required

Returns: bool: True if "self" duration is greater than or equal to "other" duration, False otherwise

Example

print(duration.from_hours(1) >= duration.from_minutes(30))
# True

`le(other)` ¶

Compare two durations for less than or equal to

Parameters:

Name	Type	Description	Default
`other`	`duration`	duration to compare with	required

Returns: bool: True if "self" duration is less than or equal to "other" duration, False otherwise

Example

print(duration.from_hours(1) <= duration.from_minutes(30))
# False

Time Representation¶

timescale ¶

Invalid class-attribute ¶

UTC class-attribute ¶

TT class-attribute ¶

UT1 class-attribute ¶

TAI class-attribute ¶

GPS class-attribute ¶

TDB class-attribute ¶

time ¶

__init__(year=..., month=..., day=..., hour=0, min=0, sec=0.0, *, scale=..., str=...) ¶

now() staticmethod ¶

from_string(str) staticmethod ¶

from_rfc3339(rfc) staticmethod ¶

strptime(str, format) staticmethod ¶

from_date(year, month, day) staticmethod ¶

from_jd(jd, scale=timescale.UTC) staticmethod ¶

from_unixtime(ut) staticmethod ¶

from_gps_week_and_second(week, sec) staticmethod ¶

weekday() ¶

day_of_year() ¶

from_mjd(mjd, scale=timescale.UTC) staticmethod ¶

as_date() ¶

as_gregorian(scale=timescale.UTC) ¶

from_gregorian(year, month, day, hour, min, sec) staticmethod ¶

as_datetime(utc=True) ¶

datetime(utc=True) ¶

as_mjd(scale=timescale.UTC) ¶

as_jd(scale=timescale.UTC) ¶

as_unixtime() ¶

as_iso8601() ¶

as_rfc3339() ¶

strftime(format) ¶

__le__(other) ¶

__lt__(other) ¶

__ge__(other) ¶

__gt__(other) ¶

__eq__(value) ¶

__ne__(value) ¶

duration ¶

days property ¶

hours property ¶

minutes property ¶

seconds property ¶

__init__(*, days=0, hours=0, minutes=0, seconds=0.0, microseconds=0.0) ¶

from_days(d) staticmethod ¶

from_seconds(s) staticmethod ¶

from_minutes(m) staticmethod ¶

from_hours(h) staticmethod ¶

__sub__(other) ¶

__mul__(other) ¶

__gt__(other) ¶

__lt__(other) ¶

__ge__(other) ¶

__le__(other) ¶

`timescale` ¶

`Invalid` `class-attribute` ¶

`UTC` `class-attribute` ¶

`TT` `class-attribute` ¶

`UT1` `class-attribute` ¶

`TAI` `class-attribute` ¶

`GPS` `class-attribute` ¶

`TDB` `class-attribute` ¶

`time` ¶

`init(year=..., month=..., day=..., hour=0, min=0, sec=0.0, *, scale=..., str=...)` ¶

`now()` `staticmethod` ¶

`from_string(str)` `staticmethod` ¶

`from_rfc3339(rfc)` `staticmethod` ¶

`strptime(str, format)` `staticmethod` ¶

`from_date(year, month, day)` `staticmethod` ¶

`from_jd(jd, scale=timescale.UTC)` `staticmethod` ¶

`from_unixtime(ut)` `staticmethod` ¶

`from_gps_week_and_second(week, sec)` `staticmethod` ¶

`weekday()` ¶

`day_of_year()` ¶

`from_mjd(mjd, scale=timescale.UTC)` `staticmethod` ¶

`as_date()` ¶

`as_gregorian(scale=timescale.UTC)` ¶

`from_gregorian(year, month, day, hour, min, sec)` `staticmethod` ¶

`as_datetime(utc=True)` ¶

`datetime(utc=True)` ¶

`as_mjd(scale=timescale.UTC)` ¶

`as_jd(scale=timescale.UTC)` ¶

`as_unixtime()` ¶

`as_iso8601()` ¶

`as_rfc3339()` ¶

`strftime(format)` ¶

`le(other)` ¶

`lt(other)` ¶

`ge(other)` ¶

`gt(other)` ¶

`eq(value)` ¶

`ne(value)` ¶

`duration` ¶

`days` `property` ¶

`hours` `property` ¶

`minutes` `property` ¶

`seconds` `property` ¶

`init(*, days=0, hours=0, minutes=0, seconds=0.0, microseconds=0.0)` ¶

`from_days(d)` `staticmethod` ¶

`from_seconds(s)` `staticmethod` ¶

`from_minutes(m)` `staticmethod` ¶

`from_hours(h)` `staticmethod` ¶

`sub(other)` ¶

`mul(other)` ¶

`gt(other)` ¶

`lt(other)` ¶

`ge(other)` ¶

`le(other)` ¶