Time Representation¶

satkit.time is an instant with microsecond resolution that converts between the UTC, TAI, TT, TDB, UT1 and GPS time scales; satkit.duration is a time interval. What the scales are, how leap seconds and Earth orientation data enter, and which scale each part of the library uses are explained, with runnable examples, in Time Systems.

Python `datetime` interoperability¶

All functions in the satkit package that take time as an input accept either the satkit.time class or the more commonly-used datetime.datetime class, as well as a numpy.datetime64 (see below). Functions that take many times accept a list or 1-D numpy object array of any of these, or a 1-D numpy.datetime64 array. A datetime.datetime is converted with Python's own convention (datetime.timestamp()):

A naive datetime (no tzinfo) is interpreted in the machine's local time zone, not UTC.
An aware datetime uses its own UTC offset.

For UTC, pass tzinfo=datetime.timezone.utc or build a satkit.time directly. satkit.time.to_datetime() returns an aware UTC datetime; to_datetime(utc=False) returns a naive local-time datetime, which round-trips through satkit.time.from_datetime. Both directions are exact to the microsecond.

import datetime
import satkit as sk

sk.time.from_datetime(datetime.datetime(2024, 6, 15, 12, 30, tzinfo=datetime.timezone.utc))
# 2024-06-15T12:30:00.000000Z, on any machine

sk.time.from_datetime(datetime.datetime(2024, 6, 15, 12, 30))
# 12:30 local time: 2024-06-15T16:30:00.000000Z on a machine set to US Eastern (EDT)

numpy `datetime64`¶

A numpy.datetime64 scalar, or a 1-D datetime64 array of any unit (years through attoseconds), is read as a UTC label. numpy's datetime64 has no time zone and no leap seconds, so unlike a naive datetime it is never local time; it is converted exactly as an aware-UTC datetime with the same fields would be, including the pre-1972 UTC model. Like a datetime, it cannot name a leap second (23:59:60).

Values finer than a microsecond round to the nearest microsecond; a value exactly halfway goes to the later microsecond.
Year and month units go through the calendar (a datetime64[M] is the first of its month).
NaT raises ValueError, and a value beyond satkit's range (about ±292,000 years) raises OverflowError; both name the array index.
An array is read as its int64 counts, not element by element, which makes large time arrays cheap to build and pass: np.arange or arithmetic on a datetime64 array replaces a Python loop over satkit.time objects.

import numpy as np
import satkit as sk

tle = sk.TLE.from_lines([
    "1 25544U 98067A   24001.50000000  .00016717  00000-0  10270-3 0  9005",
    "2 25544  51.6400 208.9163 0006317  69.9862  25.2906 15.49560000 00001",
])[0]
times = np.datetime64("2024-01-01T12:00") + np.arange(1440) * np.timedelta64(1, "m")
pos, vel = sk.sgp4(tle, times)  # one day at one-minute steps, shape (1440, 3)

sk.frametransform.gmst(np.datetime64("2024-01-01T12:00:00.5"))  # scalars work too

`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

The scales follow Chapter 10 of the IERS Conventions (2010), IERS Technical Note 36 (https://iers-conventions.obspm.fr/content/tn36.pdf); UTC and leap seconds are defined by ITU-R TF.460-6. 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
UTC before 1972 follows the "rubber second" model of USNO tai-utc.dat / ERFA dat from 1961-01-01: TAI - UTC drifts linearly and steps by fractions of a second (positive steps are labelled 23:59:60.x). Before 1961, UTC is taken to equal TAI (unlike ERFA, which also models 1960).

Example

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

print(satkit.time(2023, 3, 5))
# 2023-03-05T00:00:00.000000Z

`J2000` `class-attribute` ¶

The J2000 epoch: 2000-01-01 12:00:00 TT

`GPS_EPOCH` `class-attribute` ¶

The GPS epoch: 1980-01-06 00:00:00 UTC

`MJD_EPOCH` `class-attribute` ¶

The Modified Julian Date epoch: 1858-11-17 00:00:00 UTC

`UNIX_EPOCH` `class-attribute` ¶

The Unix epoch: 1970-01-01 00:00:00 UTC

`weekday` `property` ¶

Day of the week (UTC)

`day_of_year` `property` ¶

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

`now()` `staticmethod` ¶

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

Returns:

Type	Description
`time`	Time object representing the current time

`from_string(string)` `staticmethod` ¶

Create a "time" object from a string, guessing its format

RFC 3339 is tried first (see :meth:from_rfc3339). Otherwise the numbers in the string are read in year, month, day, hour, minute, second order, so ISO-ordered strings ("2024-01-04 13:14:12.123") and month-name strings ("March 4 2024") work, but locale-ordered dates such as MM/DD/YYYY are not supported: use :meth:strptime for those.

Parameters:

Name	Type	Description	Default
`string`	`str`	String representation of time	required

Notes

A number after . following the seconds is the fraction of a second, rounded to the nearest microsecond.
A number after + or - following the minutes is a UTC offset (±HHMM, ±HH:MM or ±HH; hours 00-23, minutes 00-59) and is applied: "2024-01-04 13:14:12 +0100" is 12:14:12Z. Any other extra number is an error.
Seconds default to 0 ("2024-01-04 13:14"); an hour without minutes is an error, and a date alone is midnight.
Words other than month names (weekday names, T, Z, UTC, ...) are ignored, so a zone name is not applied: without a numeric offset the time is UTC.
This is probably not what you want. Use with caution, and prefer :meth:from_rfc3339 or :meth:strptime when the format is known.

Returns:

Type	Description
`time`	Time object representing input string

Raises:

Type	Description
`ValueError`	If the string cannot be parsed; the message gives the reason

Example

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

`from_rfc3339(rfc3339)` `staticmethod` ¶

Create a "time" object from an RFC 3339 string

Parameters:

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

Notes

Format YYYY-MM-DDTHH:MM:SS[.fff...][zone]. T may be t. The fraction has one or more digits and is rounded to the nearest microsecond beyond six. Surrounding whitespace is ignored; anything else left over is an error.
The zone is Z / z, or a UTC offset ±HH:MM (RFC 3339), ±HHMM or ±HH (ISO 8601 forms, also accepted), with hours 00-23 and minutes 00-59. The offset is applied: 2024-01-01T12:00:00+01:00 is 11:00:00Z. It shifts the calendar label, so it is exact across a leap second.
Without a zone the time is taken as UTC (RFC 3339 itself requires one).
The year is four digits, or a sign and at least four digits (ISO 8601 expanded years such as -0001 or +10000, as :meth:to_rfc3339 writes them outside 0000-9999).

Returns:

Type	Description
`time`	Time object representing input RFC 3339 string

Raises:

Type	Description
`ValueError`	If the string cannot be parsed; the message gives the reason

Example

print(satkit.time.from_rfc3339("2023-03-05T11:03:45.453Z"))
# 2023-03-05T11:03:45.453000Z

print(satkit.time.from_rfc3339("2023-03-05T12:03:45.453+01:00"))
# 2023-03-05T11:03:45.453000Z

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

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

Parameters:

Name	Type	Description	Default
`date_string`	`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. Characters other than format codes must match literally, and the whole string must be consumed: leftover input is an error.
Format Codes:
- %Y - year: exactly four digits, or a sign and at least four digits (ISO 8601 expanded years such as -0044 or +10000, as :meth:strftime writes them outside 0000-9999)
- %m - month, exactly two digits (01-12)
- %d - day of month, exactly two digits (01-31)
- %H - hour, exactly two digits (00-23)
- %M - minute, exactly two digits (00-59)
- %S - second, exactly two digits (00-59, or 60 in a leap second)
- %f - fraction of a second: one or more digits (5 is 500 ms), rounded to the nearest microsecond beyond six
- %b - abbreviated month name (Jan, Feb, ...)
- %B - full month name (January, February, ...)
- %z - UTC offset ±HH:MM, ±HHMM or ±HH (exactly two digits per field, hours 00-23, minutes 00-59), or Z / z for UTC. +HHMM means local time is ahead of UTC, so 12:00:00+0100 is 11:00:00Z; the offset shifts the calendar label, so it is exact across a leap second
- %% - a literal %

Returns:

Type	Description
`time`	Time object representing input string

Raises:

Type	Description
`ValueError`	If the string does not match the format; the message gives the reason

Example

# %f reads any number of fraction digits: ".453" is 453 ms
print(satkit.time.strptime("2023-03-05 11:03:45.453Z", "%Y-%m-%d %H:%M:%S.%fZ"))
# 2023-03-05T11:03:45.453000Z

`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`	Time object representing the start of the input day (midnight)

Example

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

`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, days	required
`scale`	`timescale`	Time scale. Default is satkit.timescale.UTC	`UTC`

Returns:

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

Example

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

`from_unixtime(unixtime)` `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); rounded to the nearest microsecond	required

Returns:

Type	Description
`time`	Time object representing input unixtime

Example

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

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

Return a time object representing input GPS week and second

Parameters:

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

Returns:

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

`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, days	required
`scale`	`timescale`	Time scale. Default is satkit.timescale.UTC	`UTC`

Returns:

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

Example

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

`to_date()` ¶

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

Returns:

Type	Description
`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_date()` ¶

Deprecated since 0.23, removed in 0.25. Use :meth:time.to_date.

`to_gregorian()` ¶

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

Returns:

Type	Description
`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_gregorian()` ¶

Deprecated since 0.23, removed in 0.25. Use :meth:time.to_gregorian.

`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`	Time object representing input UTC Gregorian time

Example

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

`from_datetime(dt)` `staticmethod` ¶

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

Follows Python's own convention (datetime.timestamp()):

A naive datetime (no tzinfo) is interpreted in the machine's local time zone, not UTC.
An aware datetime uses its own UTC offset.

For UTC, pass tzinfo=datetime.timezone.utc or build a satkit.time directly. The conversion is exact to the microsecond (it does not go through the float timestamp()), and so is to_datetime().

Parameters:

Name	Type	Description	Default
`dt`	`datetime`	"datetime.datetime" object to convert	required

Returns:

Type	Description
`time`	Time object representing the same instant in time as the input "datetime.datetime" object

`to_datetime(utc=True)` ¶

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

Parameters:

Name	Type	Description	Default
`utc`	`bool`	If True (default), return an aware datetime in UTC. If False, return a naive datetime in the machine's local time zone, which round-trips through :meth:`time.from_datetime`.	`True`

Returns:

Type	Description
`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).to_datetime(True)
print(dt)
# 2023-06-03 06:19:34+00:00

dt = satkit.time(2023, 6, 3, 6, 19, 34).to_datetime(False)
print(dt)
# 2023-06-03 02:19:34

`as_datetime(utc=True)` ¶

Deprecated since 0.23, removed in 0.25. Use :meth:time.to_datetime.

`datetime(utc=True)` ¶

Deprecated: use :meth:satkit.time.to_datetime.

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

Parameters:

Name	Type	Description	Default
`utc`	`bool`	If True (default), return an aware datetime in UTC. If False, return a naive datetime in the machine's local time zone, which round-trips through :meth:`time.from_datetime`.	`True`

Returns:

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

`add_utc_days(days)` ¶

Return a new time offset by a whole number of UTC days.

A UTC day is defined as exactly 86400 seconds, avoiding the ambiguity of adding a "day" across a leap second.

Parameters:

Name	Type	Description	Default
`days`	`float`	Number of UTC days to add	required

Returns:

Type	Description
`time`	satkit.time: Time object offset by the given number of UTC days

`to_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

Returns:

Name	Type	Description
`float`	`float`	Modified Julian Date, days

`as_mjd(scale=timescale.UTC)` ¶

Deprecated since 0.23, removed in 0.25. Use :meth:time.to_mjd.

`to_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

Returns:

Name	Type	Description
`float`	`float`	Julian Date, days

`as_jd(scale=timescale.UTC)` ¶

Deprecated since 0.23, removed in 0.25. Use :meth:time.to_jd.

`to_unixtime()` ¶

Represent time as unixtime

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

Includes fractional component of seconds

Returns:

Name	Type	Description
`float`	`float`	Unix time, seconds

`as_unixtime()` ¶

Deprecated since 0.23, removed in 0.25. Use :meth:time.to_unixtime.

`to_iso8601()` ¶

Represent time as ISO 8601 string

Returns:

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

`as_iso8601()` ¶

Deprecated since 0.23, removed in 0.25. Use :meth:time.to_iso8601.

`to_rfc3339()` ¶

Represent time as RFC 3339 string

Returns:

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

`as_rfc3339()` ¶

Deprecated since 0.23, removed in 0.25. Use :meth:time.to_rfc3339.

`strftime(format)` ¶

Represent time as string with given format

Parameters:

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

Notes

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:

Type	Description
`str`	string representation of time

Example

print(satkit.time(2023, 6, 3, 6, 19, 34).strftime("%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:

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

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

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

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

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

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

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

__init__() -> None

__init__(string: str) -> None

__init__(year: int, month: int, day: int, /, *, scale: timescale = ...) -> None

__init__(year: int, month: int, day: int, hour: int, min: int, sec: float, /, *, scale: timescale = ...) -> None

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

Accepted forms (all positional):

time(): the current time
time(string): parse a string, RFC 3339 first (e.g. "2023-03-05T11:03:45.453Z"), then other common formats
time(year, month, day): midnight at the start of the day
time(year, month, day, hour, min, sec): all six components

Parameters:

Name	Type	Description	Default
`string`		String representation of time	required
`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
`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); up to 61 within a UTC leap second (e.g. `23:59:60.5` on 2016-12-31), and within a pre-1972 positive UTC step (e.g. `23:59:60.05` on 1963-10-31, up to 61.422818 on 1960-12-31). Rounded to the nearest microsecond, so the seconds from `to_gregorian()` round-trip exactly	required
`scale`	`timescale`	Time scale in which the Gregorian components are interpreted, default is satkit.timescale.UTC. Ignored for the string and no-argument forms.	`...`

Raises:

Type	Description
`ValueError`	If the string form cannot be parsed

Example

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

print(satkit.time(2023, 3, 5))
# 2023-03-05T00:00:00.000000Z

`add(other)` ¶

__add__(other: duration) -> time

__add__(other: float) -> time

__add__(other: list[duration]) -> npt.NDArray[Any]

__add__(other: npt.NDArray[np.floating[Any]] | npt.NDArray[np.integer[Any]] | list[float] | list[int]) -> npt.NDArray[Any]

Return a numpy array of time objects, with each object representing an element-wise addition of days to the "self" time object

Parameters:

Name	Type	Description	Default
`other`	`NDArray[floating] \| NDArray[integer] \| list[float]`	1-D array or list of days to add to the current time (integer and float32 arrays are converted to float64)	required

Raises:

Type	Description
`ValueError`	if an element is NaN or infinite
`OverflowError`	if an element is too large for a duration, or a result is beyond about ±292,000 years

Returns:

Type	Description
`NDArray[Any]`	Object array of time objects representing the element-wise addition of days to the current time

`sub(other)` ¶

__sub__(other: duration) -> time

__sub__(other: time) -> duration

__sub__(other: float) -> time

__sub__(other: npt.NDArray[np.floating[Any]] | npt.NDArray[np.integer[Any]] | list[float] | list[int]) -> npt.NDArray[Any]

__sub__(other: list[duration]) -> npt.NDArray[Any]

__sub__(other: list[time]) -> npt.NDArray[Any]

Return a numpy array of time objects, with each object representing an element-wise subtraction of days from the "self" time object

Parameters:

Name	Type	Description	Default
`other`	`NDArray[floating] \| NDArray[integer] \| list[float]`	1-D array or list of days to subtract from the current time (integer and float32 arrays are converted to float64)	required

Returns:

Type	Description
`NDArray[Any]`	Object array of time objects representing the element-wise subtraction of days from the current time

`duration` ¶

Representation of a duration, or interval of time

`days` `property` ¶

Floating point number of days represented by duration

Returns:

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

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

`microseconds` `property` ¶

Number of whole microseconds represented by duration

Returns:

Type	Description
`int`	Integer number of microseconds represented by duration

`minutes` `property` ¶

Floating point number of minutes represented by duration

Returns:

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

`seconds` `property` ¶

Floating point number of seconds represented by duration

Returns:

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

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

Create a duration object representing input time duration

Parameters:

Name	Type	Description	Default
`days`	`float`	Number of days, default is 0	`0.0`
`hours`	`float`	Number of hours, default is 0	`0.0`
`minutes`	`float`	Number of minutes, default is 0	`0.0`
`seconds`	`float`	Number of seconds, default is 0.0	`0.0`
`microseconds`	`int`	Number of microseconds (an integer), default is 0	`0`

Notes

If no arguments are passed in, the created object represents a duration of 0 seconds
A duration is an integer number of microseconds; each floating-point argument is rounded to the nearest microsecond
A NaN or infinite argument raises ValueError, and one too large for a duration (beyond about ±292,000 years) raises OverflowError; the same holds for the from_* constructors, and for arguments that fit one by one but not summed
Adding or subtracting durations and times raises OverflowError when the result is beyond that range (it used to wrap around)

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`	Duration object representing input number of days

Example

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

`from_seconds(seconds)` `staticmethod` ¶

Create duration object representing input number of seconds

Parameters:

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

Returns:

Type	Description
`duration`	Duration object representing input number of seconds

Example

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

`from_minutes(minutes)` `staticmethod` ¶

Create duration object representing input number of minutes

Parameters:

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

Returns:

Type	Description
`duration`	Duration object representing input number of minutes

`from_hours(hours)` `staticmethod` ¶

Create duration object representing input number of hours

Parameters:

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

Returns:

Type	Description
`duration`	Duration object representing input number of hours

`from_milliseconds(d)` `staticmethod` ¶

Create duration object representing input number of milliseconds

Parameters:

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

Returns:

Type	Description
`duration`	Duration object representing input number of milliseconds

`sub(other)` ¶

Take the difference between two durations

Parameters:

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

Raises:

Type	Description
`OverflowError`	if the result is beyond about ±292,000 years

Returns:

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

Example

print(satkit.duration.from_hours(1) - satkit.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:

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

Example

print(satkit.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: True if "self" duration is greater than "other" duration, False otherwise

Example

print(satkit.duration.from_hours(1) > satkit.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: True if "self" duration is less than "other" duration, False otherwise

Example

print(satkit.duration.from_hours(1) < satkit.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: True if "self" duration is greater than or equal to "other" duration, False otherwise

Example

print(satkit.duration.from_hours(1) >= satkit.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: True if "self" duration is less than or equal to "other" duration, False otherwise

Example

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

`add(other)` ¶

__add__(other: duration) -> duration

__add__(other: time) -> time

Add a duration to another duration

Parameters:

Name	Type	Description	Default
`other`	`duration`	duration to add to the current duration	required

Raises:

Type	Description
`OverflowError`	if the result is beyond about ±292,000 years

Returns:

Type	Description
`duration`	Duration object representing the sum, or concatenation, of both durations

Example

print(satkit.duration.from_hours(1) + satkit.duration.from_minutes(1))
# Duration: 1 hours, 1 minutes, 0.000 seconds

`truediv(other)` ¶

__truediv__(other: float) -> duration

__truediv__(other: duration) -> float

Divide (or scale) duration by given value

Parameters:

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

Returns:

Type	Description
`duration`	Duration object representing the input duration divided by the input value

Raises:

Type	Description
`ZeroDivisionError`	if `other` is zero
`ValueError`	if `other` is NaN

Example

print(satkit.duration.from_days(1) / 2)
# Duration: 12 hours, 0 minutes, 0.000 seconds

Time Representation¶

Python datetime interoperability¶

numpy datetime64¶

timescale ¶

Invalid class-attribute ¶

UTC class-attribute ¶

TT class-attribute ¶

UT1 class-attribute ¶

TAI class-attribute ¶

GPS class-attribute ¶

TDB class-attribute ¶

time ¶

J2000 class-attribute ¶

GPS_EPOCH class-attribute ¶

MJD_EPOCH class-attribute ¶

UNIX_EPOCH class-attribute ¶

weekday property ¶

day_of_year property ¶

now() staticmethod ¶

from_string(string) staticmethod ¶

from_rfc3339(rfc3339) staticmethod ¶

strptime(date_string, format) staticmethod ¶

from_date(year, month, day) staticmethod ¶

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

from_unixtime(unixtime) staticmethod ¶

from_gps_week_and_second(week, seconds) staticmethod ¶

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

to_date() ¶

as_date() ¶

to_gregorian() ¶

as_gregorian() ¶

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

from_datetime(dt) staticmethod ¶

to_datetime(utc=True) ¶

as_datetime(utc=True) ¶

datetime(utc=True) ¶

add_utc_days(days) ¶

to_mjd(scale=timescale.UTC) ¶

as_mjd(scale=timescale.UTC) ¶

to_jd(scale=timescale.UTC) ¶

as_jd(scale=timescale.UTC) ¶

to_unixtime() ¶

as_unixtime() ¶

to_iso8601() ¶

as_iso8601() ¶

to_rfc3339() ¶

as_rfc3339() ¶

strftime(format) ¶

__le__(other) ¶

__lt__(other) ¶

__ge__(other) ¶

__gt__(other) ¶

__eq__(value) ¶

__ne__(value) ¶

__init__(year, month, day, hour, min, sec, /, *, scale=...) ¶

__add__(other) ¶

__sub__(other) ¶

duration ¶

days property ¶

hours property ¶

microseconds property ¶

minutes property ¶

seconds property ¶

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

from_days(d) staticmethod ¶

from_seconds(seconds) staticmethod ¶

from_minutes(minutes) staticmethod ¶

from_hours(hours) staticmethod ¶

from_milliseconds(d) staticmethod ¶

__sub__(other) ¶

__mul__(other) ¶

__gt__(other) ¶

__lt__(other) ¶

__ge__(other) ¶

__le__(other) ¶

__add__(other) ¶

__truediv__(other) ¶

Python `datetime` interoperability¶

numpy `datetime64`¶

`timescale` ¶

`Invalid` `class-attribute` ¶

`UTC` `class-attribute` ¶

`TT` `class-attribute` ¶

`UT1` `class-attribute` ¶

`TAI` `class-attribute` ¶

`GPS` `class-attribute` ¶

`TDB` `class-attribute` ¶

`time` ¶

`J2000` `class-attribute` ¶

`GPS_EPOCH` `class-attribute` ¶

`MJD_EPOCH` `class-attribute` ¶

`UNIX_EPOCH` `class-attribute` ¶

`weekday` `property` ¶

`day_of_year` `property` ¶

`now()` `staticmethod` ¶

`from_string(string)` `staticmethod` ¶

`from_rfc3339(rfc3339)` `staticmethod` ¶

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

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

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

`from_unixtime(unixtime)` `staticmethod` ¶

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

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

`to_date()` ¶

`as_date()` ¶

`to_gregorian()` ¶

`as_gregorian()` ¶

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

`from_datetime(dt)` `staticmethod` ¶

`to_datetime(utc=True)` ¶

`as_datetime(utc=True)` ¶

`datetime(utc=True)` ¶

`add_utc_days(days)` ¶

`to_mjd(scale=timescale.UTC)` ¶

`as_mjd(scale=timescale.UTC)` ¶

`to_jd(scale=timescale.UTC)` ¶

`as_jd(scale=timescale.UTC)` ¶

`to_unixtime()` ¶

`as_unixtime()` ¶

`to_iso8601()` ¶

`as_iso8601()` ¶

`to_rfc3339()` ¶

`as_rfc3339()` ¶

`strftime(format)` ¶

`le(other)` ¶

`lt(other)` ¶

`ge(other)` ¶

`gt(other)` ¶

`eq(value)` ¶

`ne(value)` ¶

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

`add(other)` ¶

`sub(other)` ¶

`duration` ¶

`days` `property` ¶

`hours` `property` ¶

`microseconds` `property` ¶

`minutes` `property` ¶

`seconds` `property` ¶

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

`from_days(d)` `staticmethod` ¶

`from_seconds(seconds)` `staticmethod` ¶

`from_minutes(minutes)` `staticmethod` ¶

`from_hours(hours)` `staticmethod` ¶

`from_milliseconds(d)` `staticmethod` ¶

`sub(other)` ¶

`mul(other)` ¶

`gt(other)` ¶

`lt(other)` ¶

`ge(other)` ¶

`le(other)` ¶

`add(other)` ¶

`truediv(other)` ¶