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 with unit constants
t2 = t + 1.5 * lox.hours
dt = 30 * lox.minutes

# 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_attoseconds classmethod 

from_attoseconds(atto: int) -> Self

Create from integer attoseconds.

from_days classmethod 

from_days(days: float) -> Self

Create from days.

from_femtoseconds classmethod 

from_femtoseconds(fs: int) -> Self

Create from integer femtoseconds.

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_microseconds classmethod 

from_microseconds(us: int) -> Self

Create from integer microseconds.

from_milliseconds classmethod 

from_milliseconds(ms: int) -> Self

Create from integer milliseconds.

from_minutes classmethod 

from_minutes(minutes: float) -> Self

Create from minutes.

from_nanoseconds classmethod 

from_nanoseconds(ns: int) -> Self

Create from integer nanoseconds.

from_picoseconds classmethod 

from_picoseconds(ps: int) -> Self

Create from integer picoseconds.

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.

TimeSeries

Time-indexed interpolation series.

Wraps a Series with a start epoch, allowing interpolation by Time values rather than raw float offsets.

Parameters:

  • times

    –

    List of Time objects (must be in chronological order).

  • values

    –

    List of y values (same length as times).

  • interpolation

    –

    Interpolation method ("linear" or "cubic").

Examples:

>>> epoch = lox.Time("TAI", 2024, 1, 1)
>>> times = [epoch, epoch + 60 * lox.seconds, epoch + 120 * lox.seconds]
>>> ts = lox.TimeSeries(times, [1.0, 2.0, 3.0])
>>> ts.interpolate(epoch + 30 * lox.seconds)
1.5

Methods:

  • first –

    Return the first data point as (time, value).

  • from_offsets –

    Create a TimeSeries from an epoch and relative offsets in seconds.

  • interpolate –

    Interpolate a y value at the given time.

  • last –

    Return the last data point as (time, value).

  • times –

    Return absolute timestamps for each data point.

  • values –

    Return the y values.

Attributes:

  • epoch (Time) –

    The reference epoch of this time series.

epoch property 

epoch: Time

The reference epoch of this time series.

first 

first() -> tuple[Time, float]

Return the first data point as (time, value).

from_offsets classmethod 

from_offsets(
    epoch: Time,
    x: list[float],
    y: list[float],
    interpolation: Literal["linear", "cubic"] = "linear",
) -> TimeSeries

Create a TimeSeries from an epoch and relative offsets in seconds.

interpolate 

interpolate(time: Time) -> float

Interpolate a y value at the given time.

last 

last() -> tuple[Time, float]

Return the last data point as (time, value).

times 

times() -> list[Time]

Return absolute timestamps for each data point.

values 

values() -> list[float]

Return the y values.