Time

class Time

Represents a moment in time, stored internally as TDB (SPICE ET).

The Time class provides a unified interface for working with astronomical time, supporting conversion between multiple timescales and representations (Julian Date, Modified Julian Date, calendar strings).

Internally, time is stored as seconds past J2000.0 TDB, which is the convention used by SPICE (“Ephemeris Time” or ET).

Example Usage

// From a UTC date string (common case)
Time t1("2024-03-15T12:00:00");

// From a Julian Date in TT (e.g., for catalog epoch calculations)
Time t2 = Time::from_julian_date(2451545.0, TimeScale::TT);  // J2000.0

// Get Julian Date in TT for proper motion calculations
double jd_tt = t1.to_julian_date(TimeScale::TT);

// Compute years since J2000.0 (in TT, for catalog work)
double dt = t1.julian_years_since_j2000(TimeScale::TT);

Note

All factory methods and accessors that involve Julian Dates or calendar representations require explicit specification of the timescale to prevent silent errors from timescale confusion.

Comparison Operators

Compare two Time objects by their internal TDB representation.

inline bool operator==(const Time &other) const
inline bool operator!=(const Time &other) const
inline bool operator<(const Time &other) const
inline bool operator<=(const Time &other) const
inline bool operator>(const Time &other) const
inline bool operator>=(const Time &other) const
inline Time operator+(units::Second delta) const

Public Functions

inline explicit Time(const std::string &utc_string)

Constructs a Time from a UTC date-time string.

Parses a variety of date-time string formats and converts to internal TDB representation. The input is assumed to be in UTC.

Note

This constructor assumes UTC. For other timescales, use the factory methods with explicit TimeScale specification.

Parameters:

utc_string – A date-time string in a format recognized by SPICE, such as:

  • ”2024-03-15T12:00:00”

  • ”2024-03-15 12:00:00”

  • ”March 15, 2024 12:00:00”

  • ”2024-MAR-15 12:00:00.000”

Throws:

std::runtime_error – if the string cannot be parsed.

inline double et() const

Returns the time as SPICE ephemeris time (TDB seconds past J2000).

Returns:

Ephemeris time in seconds.

inline double ephemeris_time() const

Returns the time as SPICE ephemeris time (TDB seconds past J2000).

Returns:

Ephemeris time in seconds.

inline double to_julian_date(TimeScale scale = TimeScale::TDB) const

Returns the time as a Julian Date in the specified timescale.

Note

For stellar catalog work (e.g., proper motion from J2000.0), use TimeScale::TT since catalog epochs are defined in TT.

Parameters:

scale – The desired output timescale (default: TDB).

Returns:

Julian Date in the specified timescale.

inline double to_modified_julian_date(TimeScale scale = TimeScale::TDB) const

Returns the time as a Modified Julian Date in the specified timescale.

Parameters:

scale – The desired output timescale (default: TDB).

Returns:

Modified Julian Date (JD - 2400000.5) in the specified timescale.

inline double julian_years_since_j2000(TimeScale scale = TimeScale::TT) const

Returns the elapsed Julian years since J2000.0.

Computes (JD - 2451545.0) / 365.25 in the specified timescale. This is the standard formula for proper motion calculations.

Example

Time obs_time("2024-06-15T00:00:00");
double dt = obs_time.julian_years_since_j2000(TimeScale::TT);
// dt ≈ 24.45 years

// Apply proper motion: new_ra = ra_j2000 + pm_ra * dt

Note

For stellar proper motion calculations, use TimeScale::TT since J2000.0 and catalog positions are defined in TT.

Parameters:

scale – The timescale for the calculation (default: TT).

Returns:

Elapsed time in Julian years (365.25 days each).

inline std::string to_iso_8601() const

Returns the time as an ISO 8601 formatted UTC string.

Note

The trailing ‘Z’ indicates UTC (Zulu time).

Returns:

String in the format “YYYY-MM-DDTHH:MM:SS.sssZ”.

inline std::string to_utc_string(const std::string &format = "YYYY-MM-DD HR:MN:SC.### UTC") const

Returns the time as a formatted UTC string.

Note

Output is always in UTC regardless of format string content.

Parameters:

format – SPICE-compatible format string. Common tokens:

  • YYYY: 4-digit year

  • MM: 2-digit month

  • DD: 2-digit day

  • HR: 2-digit hour

  • MN: 2-digit minute

  • SC: 2-digit second

  • ###: milliseconds

Returns:

Formatted time string in UTC.

Public Static Functions

static inline Time from_et(double et)

Constructs a Time from SPICE ephemeris time (TDB seconds past J2000).

This is the most direct construction method, as ET is the internal representation.

Parameters:

et – Ephemeris time in seconds past J2000.0 TDB.

Returns:

Time object representing the specified moment.

static inline Time from_ephemeris_time(double et)

Constructs a Time from SPICE ephemeris time (TDB seconds past J2000).

This is the most direct construction method, as ET is the internal representation.

Note

Alias for from_et() for clarity in code that uses the full name.

Parameters:

et – Ephemeris time in seconds past J2000.0 TDB.

Returns:

Time object representing the specified moment.

static inline Time from_julian_date(double jd, TimeScale scale)

Constructs a Time from a Julian Date in the specified timescale.

Example

// J2000.0 epoch (January 1, 2000, 12:00:00 TT)
Time j2000 = Time::from_julian_date(2451545.0, TimeScale::TT);

Note

J2000.0 is defined as JD 2451545.0 TT (not TDB), though the difference is sub-millisecond.

Parameters:

  • jd – Julian Date value.

  • scale – The timescale of the input Julian Date.

Returns:

Time object representing the specified moment.

static inline Time from_modified_julian_date(double mjd, TimeScale scale)

Constructs a Time from a Modified Julian Date in the specified timescale.

Modified Julian Date is defined as MJD = JD - 2400000.5, shifting the epoch to midnight of November 17, 1858.

Parameters:

  • mjd – Modified Julian Date value.

  • scale – The timescale of the input MJD.

Returns:

Time object representing the specified moment.

Public Static Attributes

static double J2000_JD = 2451545.0

Julian Date of J2000.0 epoch (2451545.0).

Defined as January 1, 2000, 12:00:00 TT.

static double DAYS_PER_JULIAN_YEAR = 365.25

Days per Julian year (365.25).

Used for proper motion calculations and epoch conversions.

static double MJD_OFFSET = 2400000.5

Offset between Julian Date and Modified Julian Date.

MJD = JD - 2400000.5

static double TT_TAI_OFFSET = 32.184

Offset between TAI and TT in seconds.

TT = TAI + 32.184s (exact, by definition).