Skip to content

Time & Dates

High-precision time handling with femtosecond resolution and support for multiple astronomical time scales.

Time Scales

Lox supports the following astronomical time scales:

Scale Name Description
TAI International Atomic Time Primary atomic time scale
TT Terrestrial Time Used for geocentric ephemerides
TDB Barycentric Dynamical Time Used for solar system ephemerides
TCB Barycentric Coordinate Time Relativistic coordinate time
TCG Geocentric Coordinate Time Relativistic coordinate time
UT1 Universal Time Tied to Earth's rotation

Quick Example

import lox_space as lox

# Create a time instant
t = lox.Time("TAI", 2024, 6, 15, 12, 30, 45.5)

# From ISO string
t = lox.Time.from_iso("2024-06-15T12:30:45.5 TAI")

# Convert between scales
t_tt = t.to_scale("TT")

# Time arithmetic
dt = lox.TimeDelta.from_hours(1.5)
t2 = t + dt

# Work with UTC
utc = lox.UTC(2024, 6, 15, 12, 30, 45.5)
t_tai = utc.to_scale("TAI")

Time

Represents an instant in time on a specific astronomical time scale.

Time provides femtosecond precision and support for multiple astronomical time scales (TAI, TT, TDB, TCB, TCG, UT1).

Parameters:

  • scale

    –

    Time scale ("TAI", "TT", etc.) or TimeScale object.

  • year

    –

    Calendar year.

  • month

    –

    Calendar month (1-12).

  • day

    –

    Day of month (1-31).

  • hour

    –

    Hour (0-23, default 0).

  • minute

    –

    Minute (0-59, default 0).

  • seconds

    –

    Seconds including fractional part (default 0.0).

Examples:

>>> t = lox.Time("TAI", 2024, 1, 1, 12, 0, 0.0)
>>> t.to_scale("TT")
Time(TT, 2024, 1, 1, 12, 0, 32.184)

Methods:

  • day –

    Return the day of month (1-31).

  • day_of_year –

    Return the day of year (1-366).

  • decimal_seconds –

    Return the decimal seconds within the current minute.

  • femtosecond –

    Return the femtosecond component (0-999).

  • from_day_of_year –

    Create a Time from a day-of-year representation.

  • from_iso –

    Parse a Time from an ISO 8601 string.

  • from_julian_date –

    Create a Time from a Julian date.

  • from_seconds –

    Create a Time from seconds since J2000.

  • from_two_part_julian_date –

    Create a Time from a two-part Julian date for maximum precision.

  • hour –

    Return the hour (0-23).

  • isclose –

    Check if two times are approximately equal.

  • julian_date –

    Return the Julian date.

  • microsecond –

    Return the microsecond component (0-999).

  • millisecond –

    Return the millisecond component (0-999).

  • minute –

    Return the minute (0-59).

  • month –

    Return the calendar month (1-12).

  • nanosecond –

    Return the nanosecond component (0-999).

  • picosecond –

    Return the picosecond component (0-999).

  • scale –

    Return the time scale of this time.

  • second –

    Return the integer second (0-59).

  • seconds –

    Return integer seconds since J2000.

  • subsecond –

    Return the fractional part of the second.

  • to_scale –

    Convert to a different time scale.

  • to_utc –

    Convert to UTC.

  • two_part_julian_date –

    Return the two-part Julian date for maximum precision.

  • year –

    Return the calendar year.

day 

day() -> int

Return the day of month (1-31).

day_of_year 

day_of_year() -> int

Return the day of year (1-366).

decimal_seconds 

decimal_seconds() -> float

Return the decimal seconds within the current minute.

femtosecond 

femtosecond() -> int

Return the femtosecond component (0-999).

from_day_of_year classmethod 

from_day_of_year(
    scale: Scale | TimeScale,
    year: int,
    doy: int,
    hour: int = 0,
    minute: int = 0,
    seconds: float = 0.0,
) -> Self

Create a Time from a day-of-year representation.

from_iso classmethod 

from_iso(iso: str, scale: Scale | TimeScale | None = None) -> Self

Parse a Time from an ISO 8601 string.

from_julian_date classmethod 

from_julian_date(scale: Scale | TimeScale, jd: float, epoch: str = 'jd') -> Self

Create a Time from a Julian date.

from_seconds classmethod 

from_seconds(scale: Scale | TimeScale, seconds: int, subsecond: float) -> Self

Create a Time from seconds since J2000.

from_two_part_julian_date classmethod 

from_two_part_julian_date(scale: Scale | TimeScale, jd1: float, jd2: float) -> Self

Create a Time from a two-part Julian date for maximum precision.

hour 

hour() -> int

Return the hour (0-23).

isclose 

isclose(other: Time, rel_tol: float = 1e-08, abs_tol: float = 1e-14) -> bool

Check if two times are approximately equal.

julian_date 

julian_date(epoch: Epoch = 'jd', unit: Unit = 'days') -> float

Return the Julian date.

microsecond 

microsecond() -> int

Return the microsecond component (0-999).

millisecond 

millisecond() -> int

Return the millisecond component (0-999).

minute 

minute() -> int

Return the minute (0-59).

month 

month() -> int

Return the calendar month (1-12).

nanosecond 

nanosecond() -> int

Return the nanosecond component (0-999).

picosecond 

picosecond() -> int

Return the picosecond component (0-999).

scale 

scale() -> TimeScale

Return the time scale of this time.

second 

second() -> int

Return the integer second (0-59).

seconds 

seconds() -> int

Return integer seconds since J2000.

subsecond 

subsecond() -> float

Return the fractional part of the second.

to_scale 

to_scale(scale: Scale | TimeScale, provider: EOPProvider | None = None) -> Self

Convert to a different time scale.

to_utc 

to_utc(provider: EOPProvider | None = None) -> UTC

Convert to UTC.

two_part_julian_date 

two_part_julian_date() -> tuple[float, float]

Return the two-part Julian date for maximum precision.

year 

year() -> int

Return the calendar year.

UTC

Represents a UTC (Coordinated Universal Time) timestamp.

UTC is the basis for civil time worldwide. Unlike Time, UTC handles leap seconds and is discontinuous.

Parameters:

  • year

    –

    Calendar year.

  • month

    –

    Calendar month (1-12).

  • day

    –

    Day of month (1-31).

  • hour

    –

    Hour (0-23, default 0).

  • minute

    –

    Minute (0-59, default 0).

  • seconds

    –

    Seconds including fractional part (default 0.0).

Examples:

>>> utc = lox.UTC(2024, 1, 1, 12, 0, 0.0)
>>> t = utc.to_scale("TAI")

Methods:

  • day –

    Return the day of month (1-31).

  • decimal_seconds –

    Return the decimal seconds within the current minute.

  • from_iso –

    Parse from an ISO 8601 string.

  • hour –

    Return the hour (0-23).

  • isclose –

    Check if two UTC times are approximately equal.

  • microsecond –

    Return the microsecond component (0-999).

  • millisecond –

    Return the millisecond component (0-999).

  • minute –

    Return the minute (0-59).

  • month –

    Return the calendar month (1-12).

  • nanosecond –

    Return the nanosecond component (0-999).

  • picosecond –

    Return the picosecond component (0-999).

  • second –

    Return the integer second (0-60, 60 for leap seconds).

  • to_scale –

    Convert to a continuous time scale.

  • year –

    Return the calendar year.

day 

day() -> int

Return the day of month (1-31).

decimal_seconds 

decimal_seconds() -> float

Return the decimal seconds within the current minute.

from_iso classmethod 

from_iso(iso: str) -> Self

Parse from an ISO 8601 string.

hour 

hour() -> int

Return the hour (0-23).

isclose 

isclose(other: UTC, rel_tol: float = 1e-08, abs_tol: float = 1e-14) -> bool

Check if two UTC times are approximately equal.

microsecond 

microsecond() -> int

Return the microsecond component (0-999).

millisecond 

millisecond() -> int

Return the millisecond component (0-999).

minute 

minute() -> int

Return the minute (0-59).

month 

month() -> int

Return the calendar month (1-12).

nanosecond 

nanosecond() -> int

Return the nanosecond component (0-999).

picosecond 

picosecond() -> int

Return the picosecond component (0-999).

second 

second() -> int

Return the integer second (0-60, 60 for leap seconds).

to_scale 

to_scale(scale: Scale | TimeScale, provider: EOPProvider | None = None) -> Time

Convert to a continuous time scale.

year 

year() -> int

Return the calendar year.

TimeDelta

Represents a duration or time difference.

TimeDelta represents a time interval with femtosecond precision.

Parameters:

  • seconds

    –

    Duration in seconds.

Examples:

>>> dt = lox.TimeDelta(3600.0)  # 1 hour
>>> dt = lox.TimeDelta.from_hours(1.0)
>>> t2 = t1 + dt

Methods:

from_days classmethod 

from_days(days: float) -> Self

Create from days.

from_hours classmethod 

from_hours(hours: float) -> Self

Create from hours.

from_julian_centuries classmethod 

from_julian_centuries(centuries: float) -> Self

Create from Julian centuries (36525 days).

from_julian_years classmethod 

from_julian_years(years: float) -> Self

Create from Julian years (365.25 days).

from_minutes classmethod 

from_minutes(minutes: float) -> Self

Create from minutes.

from_seconds classmethod 

from_seconds(seconds: int) -> Self

Create from integer seconds.

range classmethod 

range(start: int, end: int, step: int | None = None) -> list[Self]

Generate a range of TimeDelta values.

seconds 

seconds() -> int

Return integer seconds.

subsecond 

subsecond() -> float

Return the fractional part of the second.

to_decimal_seconds 

to_decimal_seconds() -> float

Return the duration as decimal seconds.

TimeScale

Represents an astronomical time scale.

Supported time scales: - TAI: International Atomic Time - TT: Terrestrial Time - TDB: Barycentric Dynamical Time - TCB: Barycentric Coordinate Time - TCG: Geocentric Coordinate Time - UT1: Universal Time (requires EOP data)

Parameters:

  • abbreviation

    –

    Time scale abbreviation.

Examples:

>>> tai = lox.TimeScale("TAI")
>>> tai.name()
'International Atomic Time'

Methods:

  • abbreviation –

    Return the time scale abbreviation.

  • name –

    Return the full name of the time scale.

abbreviation 

abbreviation() -> str

Return the time scale abbreviation.

name 

name() -> str

Return the full name of the time scale.