Time & Dates

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() -> int

day_of_year() -> int

decimal_seconds() -> float

femtosecond() -> int

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

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

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

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

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

hour() -> int

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

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

microsecond() -> int

millisecond() -> int

minute() -> int

month() -> int

nanosecond() -> int

picosecond() -> int

scale() -> TimeScale

second() -> int

seconds() -> int

subsecond() -> float

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

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

two_part_julian_date() -> tuple[float, float]

year() -> int

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() -> int

decimal_seconds() -> float

from_iso(iso: str) -> Self

hour() -> int

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

microsecond() -> int

millisecond() -> int

minute() -> int

month() -> int

nanosecond() -> int

picosecond() -> int

second() -> int

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

year() -> int

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 –

  Create from integer attoseconds.

• from_days –

  Create from days.

• from_femtoseconds –

  Create from integer femtoseconds.

• from_hours –

  Create from hours.

• from_julian_centuries –

  Create from Julian centuries (36525 days).

• from_julian_years –

  Create from Julian years (365.25 days).

• from_microseconds –

  Create from integer microseconds.

• from_milliseconds –

  Create from integer milliseconds.

• from_minutes –

  Create from minutes.

• from_nanoseconds –

  Create from integer nanoseconds.

• from_picoseconds –

  Create from integer picoseconds.

• from_seconds –

  Create from integer seconds.

• range –

  Generate a range of TimeDelta values.

• seconds –

  Return integer seconds.

• subsecond –

  Return the fractional part of the second.

• to_decimal_seconds –

  Return the duration as decimal seconds.

from_attoseconds(atto: int) -> Self

from_days(days: float) -> Self

from_femtoseconds(fs: int) -> Self

from_hours(hours: float) -> Self

from_julian_centuries(centuries: float) -> Self

from_julian_years(years: float) -> Self

from_microseconds(us: int) -> Self

from_milliseconds(ms: int) -> Self

from_minutes(minutes: float) -> Self

from_nanoseconds(ns: int) -> Self

from_picoseconds(ps: int) -> Self

from_seconds(seconds: int) -> Self

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

seconds() -> int

subsecond() -> float

to_decimal_seconds() -> float

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() -> str

name() -> str

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: Time

first() -> tuple[Time, float]

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

interpolate(time: Time) -> float

last() -> tuple[Time, float]

times() -> list[Time]

values() -> list[float]