Time
time
ModifiedJulianDate
A high-precision epoch represented as a Modified Julian Date (MJD).
The value is stored as a split (days, nanoseconds) pair to avoid
floating-point rounding at sub-second resolution. MJD zero corresponds
to 1858-11-17T00:00:00.
Every instance carries an explicit time-system tag (UTC, TAI, TT, UT1,
TDB, or GPS). Use to_system to convert between systems.
Attributes:
| Name | Type | Description |
|---|---|---|
days |
int
|
Whole-day MJD component [days since 1858-11-17]. |
nanoseconds |
int
|
Intra-day nanosecond component [ns; 0..86_400_000_000_000). |
time_system |
TimeSystem
|
Time system of this epoch. |
greenwich_angle |
float
|
Greenwich Mean Sidereal Time (GMST) computed on access [rad; 0..2π); requires EOP data. |
days
property
Whole-day MJD component [days since 1858-11-17].
greenwich_angle
property
Greenwich Mean Sidereal Time (GMST) angle [rad; 0..2π).
Computed using the IAU 1982 formula (Vallado 2006 §2.6.2). Requires EOP data to be loaded for the UT1 conversion.
Raises:
| Type | Description |
|---|---|
ValueError
|
If the UT1 conversion or EOP lookup fails. |
nanoseconds
property
Intra-day nanosecond component [ns; 0..86_400_000_000_000).
time_system
property
Time system of this epoch.
__add__(other)
Returns this epoch shifted later by other, in the same time system.
__eq__(other)
Returns componentwise (days, nanoseconds, time_system) equality.
No time-system conversion is performed, so the same instant tagged in two systems compares unequal.
__float__()
Returns the MJD value as a float [days since 1858-11-17]; precision loss below ~µs.
__ge__(other)
Returns self >= other; same raw-component ordering as __lt__.
__gt__(other)
Returns self > other; same raw-component ordering as __lt__.
__hash__()
Returns a hash of the (days, nanoseconds) pair; the time system is not hashed.
__init__(days, nanoseconds, time_system)
Creates a ModifiedJulianDate from explicit component parts.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
days
|
int
|
Whole-day MJD component [days since 1858-11-17]. |
required |
nanoseconds
|
int
|
Intra-day nanosecond component [ns]. |
required |
time_system
|
TimeSystem
|
Time system of the epoch. |
required |
__le__(other)
Returns self <= other; same raw-component ordering as __lt__.
__lt__(other)
Returns self < other on the raw (days, nanoseconds) pair, without time-system conversion.
__ne__(other)
Returns the negation of __eq__.
__radd__(other)
Returns other + self; equivalent to __add__.
__repr__()
Returns ModifiedJulianDate(days=…, nanoseconds=…, time_system='…').
__str__()
Returns the ISO 8601 calendar representation of this epoch.
as_julian_centuries_past_j2000()
Returns elapsed Julian centuries since J2000.0.
J2000.0 is defined as 2000-01-01T12:00:00 TT (MJD 51544.5 TT).
Returns:
| Type | Description |
|---|---|
float
|
Elapsed time since J2000.0 [Julian centuries; 1 century = 36 525 days]. |
float
|
Negative for epochs before J2000.0. |
as_julian_date()
Returns the epoch as a Julian Date (JD).
JD zero is 4713-01-01T12:00:00 UT (proleptic Julian calendar).
Returns:
| Type | Description |
|---|---|
float
|
Julian Date [days since JD 0.0]. |
doy_and_local_solar_time(longitude_deg)
Computes fractional day-of-year and local solar time at a longitude.
The epoch is first converted to UTC so both outputs are referenced to the civil UTC day; this conversion requires EOP data to be loaded. This is the authoritative DOY/LST helper used by Jacchia-family atmosphere models.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
longitude_deg
|
float
|
Observer longitude [deg; −180..180 or 0..360]. |
required |
Returns:
| Type | Description |
|---|---|
float
|
|
float
|
[days; 1.0..366.0] referenced to UTC and |
Tuple[float, float]
|
time [h; 0..24). |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the UTC conversion is unavailable (e.g. the required EOP tables are not loaded). |
from_datetime(dt)
staticmethod
Creates a ModifiedJulianDate from a timezone-aware datetime.datetime.
The datetime is converted to UTC via astimezone(timezone.utc) before
parsing, so any timezone-aware input is accepted. Precision is limited to
microseconds by the datetime type.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dt
|
datetime
|
A timezone-aware datetime object. |
required |
Returns:
| Type | Description |
|---|---|
ModifiedJulianDate
|
Epoch in UTC rounded to microsecond precision. |
Raises:
| Type | Description |
|---|---|
TypeError
|
If |
ValueError
|
If the ISO string produced by |
from_float(mjd, time_system)
staticmethod
Creates a ModifiedJulianDate from a floating-point MJD value.
The fractional day is rounded to the nearest nanosecond.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mjd
|
float
|
Modified Julian Date [days since 1858-11-17]. |
required |
time_system
|
TimeSystem
|
Time system of the epoch. |
required |
Returns:
| Type | Description |
|---|---|
ModifiedJulianDate
|
Epoch rounded to nanosecond precision. |
from_gps_seconds(gps_seconds)
staticmethod
Creates a ModifiedJulianDate from continuous GPS seconds since the GPS epoch.
The GPS epoch is 1980-01-06T00:00:00 UTC (MJD 44244). GPS time runs
continuously without leap seconds, so the input is interpreted directly
in the GPS timescale: the returned value is tagged TimeSystem.GPS
and conversion to other systems goes through TAI (TAI = GPS + 19 s).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
gps_seconds
|
float
|
Continuous seconds since the GPS epoch in the GPS timescale [s]. |
required |
Returns:
| Type | Description |
|---|---|
ModifiedJulianDate
|
Epoch tagged |
from_iso(iso)
staticmethod
Parses a ModifiedJulianDate from an ISO 8601 datetime string.
Supported formats:
"YYYY-MM-DDTHH:MM:SS[.nnnnnnnnn]Z"– parsed as UTC."YYYY-MM-DDTHH:MM:SS[.nnnnnnnnn] <TS>"– where<TS>is one ofUTC,TAI,TT,UT1,TDB.
Fractional seconds accept 1–9 digits; shorter strings are zero-padded on the right to nanosecond precision.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
iso
|
str
|
ISO 8601 datetime string. |
required |
Returns:
| Type | Description |
|---|---|
ModifiedJulianDate
|
Parsed epoch. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the string cannot be parsed. |
from_saal_ds50(ds50, time_system)
staticmethod
Creates a ModifiedJulianDate from a Saal / AFSPC days-since-1950 (DS50) epoch.
DS50 counts days elapsed since 1950-01-00.0 (= 1949-12-31T00:00:00). This format appears in TLE data and legacy AFSPC software.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ds50
|
float
|
Days since 1950-01-00.0 [days]. |
required |
time_system
|
TimeSystem
|
Time system of the epoch. |
required |
Returns:
| Type | Description |
|---|---|
ModifiedJulianDate
|
Epoch rounded to nanosecond precision. |
from_year_doy(year, day_of_year, time_system)
staticmethod
Creates a ModifiedJulianDate from a calendar year and a fractional day-of-year.
Day 1.0 corresponds to midnight of January 1st; day 1.5 corresponds to
noon on January 1st, and so on. This matches the TLE two-line element
epoch convention. See to_yydoy
for the inverse.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
year
|
int
|
Calendar year (e.g. 2024). |
required |
day_of_year
|
float
|
Day of year, 1-based with fractional day [days; 1.0..366.0]. |
required |
time_system
|
TimeSystem
|
Time system of the epoch. |
required |
Returns:
| Type | Description |
|---|---|
ModifiedJulianDate
|
Epoch rounded to nanosecond precision. |
now()
staticmethod
Returns the current UTC time as a ModifiedJulianDate.
Precision is limited to microseconds by Python's datetime.datetime.
Returns:
| Type | Description |
|---|---|
ModifiedJulianDate
|
Current time in UTC. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the system clock cannot be converted. |
to_datetime()
Converts this epoch to a timezone-aware datetime.datetime.
Only UTC epochs are supported. Sub-microsecond precision is truncated
(not rounded) to fit the datetime type.
Returns:
| Type | Description |
|---|---|
datetime
|
UTC-aware datetime object. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the epoch is not in the UTC time system. |
to_iso()
Formats this epoch as an ISO 8601 datetime string.
UTC epochs are formatted with a trailing Z; all other time systems
append the abbreviation (e.g. " TAI"). The fractional seconds field
always contains exactly 9 digits (nanosecond precision).
Returns:
| Type | Description |
|---|---|
str
|
ISO 8601 string, e.g. |
to_system(time_system)
Converts this epoch to a different time system.
Uses the IERS Finals 2000A table for UTC↔UT1 offsets.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
time_system
|
TimeSystem
|
Target time system. |
required |
Returns:
| Type | Description |
|---|---|
ModifiedJulianDate
|
A new epoch in |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the conversion path is unsupported or EOP lookup fails. |
to_tdb()
Converts this epoch to Barycentric Dynamical Time (TDB).
Convenience alias for to_system(TimeSystem.TDB).
Returns:
| Type | Description |
|---|---|
ModifiedJulianDate
|
A new epoch in TDB. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If EOP lookup fails. |
to_yydoy()
Returns the two-digit year and fractional day-of-year in TLE epoch format.
The two-digit year is the calendar year modulo 100 (e.g. 2025 → 25).
Day-of-year is 1-based with the fractional part encoding the time within
the day. This format matches the fixed-column epoch field in TLE line 1.
See from_year_doy for
the (four-digit year) inverse.
Returns:
| Type | Description |
|---|---|
int
|
|
float
|
is the fractional day of year [days; 1.0..366.0]. |
TimeSpan
A signed duration with nanosecond precision.
Stored internally as a (days, nanoseconds) pair so that sub-second
arithmetic does not lose precision to floating-point rounding.
__init__(days, nanoseconds)
Creates a TimeSpan from explicit days and nanoseconds components.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
days
|
int
|
Whole-day component [days]. May be negative. |
required |
nanoseconds
|
int
|
Intra-day nanosecond component [ns]. |
required |
__repr__()
Returns TimeSpan(days=…, nanoseconds=…).
__str__()
Returns <days>d <nanoseconds>ns.
from_days(days)
classmethod
Creates a TimeSpan from a duration in days.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
days
|
float
|
Duration [days]. May be negative. |
required |
Returns:
| Type | Description |
|---|---|
TimeSpan
|
A normalized TimeSpan rounded to nanosecond precision. |
from_hours(hours)
classmethod
Creates a TimeSpan from a duration in hours.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
hours
|
float
|
Duration [hr]. May be negative. |
required |
Returns:
| Type | Description |
|---|---|
TimeSpan
|
A normalized TimeSpan rounded to nanosecond precision. |
from_minutes(minutes)
classmethod
Creates a TimeSpan from a duration in minutes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
minutes
|
float
|
Duration [min]. May be negative. |
required |
Returns:
| Type | Description |
|---|---|
TimeSpan
|
A normalized TimeSpan rounded to nanosecond precision. |
from_seconds(seconds)
classmethod
Creates a TimeSpan from a duration in seconds.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
seconds
|
float
|
Duration [s]. May be negative. |
required |
Returns:
| Type | Description |
|---|---|
TimeSpan
|
A normalized TimeSpan rounded to nanosecond precision. |
in_centuries()
Returns the total duration in Julian centuries (36 525 days each).
Returns:
| Type | Description |
|---|---|
float
|
Total duration [Julian centuries]. |
in_days()
Returns the total duration as days.
Returns:
| Type | Description |
|---|---|
float
|
Total duration [days]. |
in_hours()
Returns the total duration as hours.
Returns:
| Type | Description |
|---|---|
float
|
Total duration [hr]. |
in_minutes()
Returns the total duration as minutes.
Returns:
| Type | Description |
|---|---|
float
|
Total duration [min]. |
in_seconds()
Returns the total duration as seconds.
Returns:
| Type | Description |
|---|---|
float
|
Total duration [s]. Precision degrades for spans exceeding |
float
|
roughly ±104 days due to f64 mantissa limits. |