Vulcan
Aerospace Engineering Utilities Built on Janus
Loading...
Searching...
No Matches
vulcan::time Namespace Reference

Classes

class  Epoch
struct  LeapSecondEntry
 Leap second entry: date and cumulative offset. More...

Typedefs

using NumericEpoch = Epoch<double>
 Numeric epoch (double-precision).
using SymbolicEpoch = Epoch<janus::SymbolicScalar>
 Symbolic epoch (CasADi MX).

Enumerations

enum class  GpsDayOfWeek {
  Sunday = 0 , Monday = 1 , Tuesday = 2 , Wednesday = 3 ,
  Thursday = 4 , Friday = 5 , Saturday = 6
}
 GPS day of week enumeration. More...
enum class  TimeScale {
  UTC , TAI , TT , TDB ,
  GPS , UT1
}

Functions

constexpr int full_gps_week (int week_mod, int rollover_count=GPS_CURRENT_ROLLOVER)
 Calculate full GPS week number from a potentially rolled-over week.
template<typename Scalar>
Scalar gps_week_to_utc_jd (int week, const Scalar &seconds_of_week, int delta_at=37)
 Convert GPS week/seconds to UTC Julian Date.
template<typename Scalar>
Scalar gps_week_to_tai_jd (int week, const Scalar &seconds_of_week)
 Convert GPS week/seconds to TAI Julian Date.
std::pair< int, double > utc_jd_to_gps_week (double utc_jd, int delta_at)
 Convert UTC Julian Date to GPS week and seconds.
std::pair< int, double > utc_jd_to_gps_week_auto (double utc_jd)
 Convert UTC Julian Date to GPS week and seconds (auto leap second lookup).
int gps_utc_offset (double utc_jd)
 Get GPS - UTC offset for a given UTC Julian Date.
constexpr int gps_utc_offset (int delta_at)
 Get GPS - UTC offset (templated with explicit delta_at).
GpsDayOfWeek gps_day_of_week (double seconds_of_week)
 Get GPS day of week from seconds into the week.
double gps_time_of_day (double seconds_of_week)
 Get time of day from GPS seconds of week.
double calendar_to_jd (int year, int month, int day, int hour=0, int min=0, double sec=0.0)
 Convert calendar date/time to Julian Date.
std::tuple< int, int, int, int, int, double > jd_to_calendar (double jd)
 Convert Julian Date to calendar date/time (numeric only).
template<typename Scalar>
constexpr Scalar jd_to_mjd (const Scalar &jd)
 Convert Julian Date to Modified Julian Date.
template<typename Scalar>
constexpr Scalar mjd_to_jd (const Scalar &mjd)
 Convert Modified Julian Date to Julian Date.
template<typename Scalar>
constexpr Scalar jd_to_j2000_seconds (const Scalar &jd)
 Convert Julian Date to seconds since J2000.0.
template<typename Scalar>
constexpr Scalar j2000_seconds_to_jd (const Scalar &sec)
 Convert seconds since J2000.0 to Julian Date.
template<typename Scalar>
constexpr Scalar jd_to_j2000_centuries (const Scalar &jd)
 Convert Julian Date to Julian centuries since J2000.0.
template<typename Scalar>
constexpr Scalar j2000_centuries_to_jd (const Scalar &T)
 Convert Julian centuries since J2000.0 to Julian Date.
constexpr bool is_leap_year (int year)
int day_of_year (int year, int month, int day)
std::tuple< int, int > doy_to_month_day (int year, int doy)
int leap_seconds_at_tai (double tai_jd)
 Get TAI - UTC offset (leap seconds) for a given TAI Julian Date.
int leap_seconds_at_utc (double utc_jd)
 Get TAI - UTC offset for a given UTC Julian Date.
bool is_leap_second (int year, int month, int day, int hour, int min, double sec)
 Check if a given UTC date/time is during a leap second.
double next_leap_second (double utc_jd)
 Get the date of the next leap second after a given date.
const janus::Interpolator & leap_second_interpolator ()
 Get a symbolic-compatible leap second interpolator.
template<typename Scalar>
Scalar leap_seconds_symbolic (const Scalar &utc_jd)
 Symbolic leap second lookup (smooth approximation).
template<typename Scalar>
constexpr Scalar tai_to_tt (const Scalar &tai_jd)
 Convert TAI Julian Date to TT Julian Date.
template<typename Scalar>
constexpr Scalar tt_to_tai (const Scalar &tt_jd)
 Convert TT Julian Date to TAI Julian Date.
template<typename Scalar>
constexpr Scalar tai_to_gps (const Scalar &tai_jd)
 Convert TAI Julian Date to GPS Julian Date.
template<typename Scalar>
constexpr Scalar gps_to_tai (const Scalar &gps_jd)
 Convert GPS Julian Date to TAI Julian Date.
template<typename Scalar>
constexpr Scalar utc_to_tai (const Scalar &utc_jd, int delta_at)
 Convert UTC Julian Date to TAI Julian Date (templated).
template<typename Scalar>
constexpr Scalar tai_to_utc (const Scalar &tai_jd, int delta_at)
 Convert TAI Julian Date to UTC Julian Date (templated).
double utc_to_tai (double utc_jd)
 Convert UTC Julian Date to TAI Julian Date (numeric, auto lookup).
double tai_to_utc (double tai_jd)
 Convert TAI Julian Date to UTC Julian Date (numeric, auto lookup).
template<typename Scalar>
constexpr Scalar utc_to_gps (const Scalar &utc_jd, int delta_at)
 Convert UTC Julian Date to GPS Julian Date (templated).
template<typename Scalar>
constexpr Scalar gps_to_utc (const Scalar &gps_jd, int delta_at)
 Convert GPS Julian Date to UTC Julian Date (templated).
double utc_to_gps (double utc_jd)
 Convert UTC Julian Date to GPS Julian Date (numeric, auto lookup).
double gps_to_utc (double gps_jd)
 Convert GPS Julian Date to UTC Julian Date (numeric, auto lookup).
template<typename Scalar>
Scalar tt_to_tdb (const Scalar &tt_jd)
 Convert TT Julian Date to TDB Julian Date.
template<typename Scalar>
Scalar tdb_to_tt (const Scalar &tdb_jd)
 Convert TDB Julian Date to TT Julian Date.
template<typename Scalar>
Scalar utc_to_tai_symbolic (const Scalar &utc_jd)
 Convert UTC Julian Date to TAI Julian Date (fully symbolic).
template<typename Scalar>
Scalar tai_to_utc_symbolic (const Scalar &tai_jd)
 Convert TAI Julian Date to UTC Julian Date (fully symbolic).

Variables

constexpr int GPS_WEEK_ROLLOVER = 1024
 GPS week number rollover constant.
constexpr int GPS_CURRENT_ROLLOVER = 2
 Current GPS week rollover count (post-April 2019).
constexpr std::array< LeapSecondEntry, 28 > LEAP_SECOND_TABLE
 Complete leap second table from 1972 to present.

Typedef Documentation

◆ NumericEpoch

Numeric epoch (double-precision).

Examples
/home/runner/work/vulcan/vulcan/include/vulcan/time/Epoch.hpp.

◆ SymbolicEpoch

using vulcan::time::SymbolicEpoch = Epoch<janus::SymbolicScalar>

Enumeration Type Documentation

◆ GpsDayOfWeek

enum class vulcan::time::GpsDayOfWeek
strong

GPS day of week enumeration.

GPS weeks start on Sunday (0).

Enumerator
Sunday 
Monday 
Tuesday 
Wednesday 
Thursday 
Friday 
Saturday 

◆ TimeScale

enum class vulcan::time::TimeScale
strong
Enumerator
UTC 

Coordinated Universal Time (civil time, has leap seconds).

TAI 

International Atomic Time (continuous SI seconds).

TT 

Terrestrial Time (TT = TAI + 32.184s).

TDB 

Barycentric Dynamical Time (for solar system dynamics).

GPS 

GPS Time (GPS = TAI - 19s, continuous since 1980).

UT1 

Universal Time 1 (Earth rotation, requires IERS data).

Function Documentation

◆ calendar_to_jd()

double vulcan::time::calendar_to_jd ( int year,
int month,
int day,
int hour = 0,
int min = 0,
double sec = 0.0 )
inlinenodiscard

Convert calendar date/time to Julian Date.

Uses the algorithm from Vallado's "Fundamentals of Astrodynamics and Applications" Valid for dates from 4713 BCE to far future.

Note
This is numeric-only as calendar conversions are I/O operations. For symbolic computations, create an Epoch from numeric calendar then use templated arithmetic.
Examples
/home/runner/work/vulcan/vulcan/include/vulcan/time/Epoch.hpp.

◆ day_of_year()

int vulcan::time::day_of_year ( int year,
int month,
int day )
inlinenodiscard

◆ doy_to_month_day()

std::tuple< int, int > vulcan::time::doy_to_month_day ( int year,
int doy )
inlinenodiscard

◆ full_gps_week()

int vulcan::time::full_gps_week ( int week_mod,
int rollover_count = GPS_CURRENT_ROLLOVER )
inlinenodiscardconstexpr

Calculate full GPS week number from a potentially rolled-over week.

GPS receivers may report week numbers modulo 1024. This function recovers the full week number based on expected rollover.

Parameters
week_modWeek number modulo 1024 (from receiver)
rollover_countWhich rollover epoch (0, 1, 2, ...)
Returns
Full GPS week number

◆ gps_day_of_week()

GpsDayOfWeek vulcan::time::gps_day_of_week ( double seconds_of_week)
inlinenodiscard

Get GPS day of week from seconds into the week.

◆ gps_time_of_day()

double vulcan::time::gps_time_of_day ( double seconds_of_week)
inlinenodiscard

Get time of day from GPS seconds of week.

Parameters
seconds_of_weekSeconds into GPS week
Returns
Seconds into the current day (0 to 86399.999...)

◆ gps_to_tai()

template<typename Scalar>
Scalar vulcan::time::gps_to_tai ( const Scalar & gps_jd)
nodiscardconstexpr

Convert GPS Julian Date to TAI Julian Date.

Examples
/home/runner/work/vulcan/vulcan/include/vulcan/time/Epoch.hpp.

◆ gps_to_utc() [1/2]

template<typename Scalar>
Scalar vulcan::time::gps_to_utc ( const Scalar & gps_jd,
int delta_at )
nodiscardconstexpr

Convert GPS Julian Date to UTC Julian Date (templated).

◆ gps_to_utc() [2/2]

double vulcan::time::gps_to_utc ( double gps_jd)
inlinenodiscard

Convert GPS Julian Date to UTC Julian Date (numeric, auto lookup).

◆ gps_utc_offset() [1/2]

int vulcan::time::gps_utc_offset ( double utc_jd)
inlinenodiscard

Get GPS - UTC offset for a given UTC Julian Date.

GPS tracks TAI with a fixed 19-second offset, while UTC has leap seconds. GPS - UTC = (TAI - UTC) - 19 = delta_at - 19

Parameters
utc_jdJulian Date in UTC scale
Returns
GPS - UTC in seconds

◆ gps_utc_offset() [2/2]

int vulcan::time::gps_utc_offset ( int delta_at)
inlinenodiscardconstexpr

Get GPS - UTC offset (templated with explicit delta_at).

◆ gps_week_to_tai_jd()

template<typename Scalar>
Scalar vulcan::time::gps_week_to_tai_jd ( int week,
const Scalar & seconds_of_week )
nodiscard

Convert GPS week/seconds to TAI Julian Date.

◆ gps_week_to_utc_jd()

template<typename Scalar>
Scalar vulcan::time::gps_week_to_utc_jd ( int week,
const Scalar & seconds_of_week,
int delta_at = 37 )
nodiscard

Convert GPS week/seconds to UTC Julian Date.

Parameters
weekFull GPS week number
seconds_of_weekSeconds into the week (0 to 604799.999...)
delta_atTAI - UTC offset (default: 37 for post-2017)
Returns
Julian Date in UTC scale

◆ is_leap_second()

bool vulcan::time::is_leap_second ( int year,
int month,
int day,
int hour,
int min,
double sec )
inlinenodiscard

Check if a given UTC date/time is during a leap second.

Leap seconds occur at 23:59:60 UTC on June 30 or December 31.

Parameters
yearYear
monthMonth (1-12)
dayDay of month
hourHour (0-23)
minMinute (0-59)
secSecond (0-60)
Returns
true if this is a leap second instant

◆ is_leap_year()

bool vulcan::time::is_leap_year ( int year)
inlinenodiscardconstexpr

◆ j2000_centuries_to_jd()

template<typename Scalar>
Scalar vulcan::time::j2000_centuries_to_jd ( const Scalar & T)
nodiscardconstexpr

Convert Julian centuries since J2000.0 to Julian Date.

◆ j2000_seconds_to_jd()

template<typename Scalar>
Scalar vulcan::time::j2000_seconds_to_jd ( const Scalar & sec)
nodiscardconstexpr

Convert seconds since J2000.0 to Julian Date.

Examples
/home/runner/work/vulcan/vulcan/include/vulcan/time/Epoch.hpp.

◆ jd_to_calendar()

std::tuple< int, int, int, int, int, double > vulcan::time::jd_to_calendar ( double jd)
inlinenodiscard

Convert Julian Date to calendar date/time (numeric only).

Examples
/home/runner/work/vulcan/vulcan/include/vulcan/time/Epoch.hpp.

◆ jd_to_j2000_centuries()

template<typename Scalar>
Scalar vulcan::time::jd_to_j2000_centuries ( const Scalar & jd)
nodiscardconstexpr

Convert Julian Date to Julian centuries since J2000.0.

◆ jd_to_j2000_seconds()

template<typename Scalar>
Scalar vulcan::time::jd_to_j2000_seconds ( const Scalar & jd)
nodiscardconstexpr

Convert Julian Date to seconds since J2000.0.

Template Parameters
ScalarNumeric or symbolic type
Examples
/home/runner/work/vulcan/vulcan/include/vulcan/time/Epoch.hpp.

◆ jd_to_mjd()

template<typename Scalar>
Scalar vulcan::time::jd_to_mjd ( const Scalar & jd)
nodiscardconstexpr

Convert Julian Date to Modified Julian Date.

Template Parameters
ScalarNumeric or symbolic type
Examples
/home/runner/work/vulcan/vulcan/include/vulcan/time/Epoch.hpp.

◆ leap_second_interpolator()

const janus::Interpolator & vulcan::time::leap_second_interpolator ( )
inlinenodiscard

Get a symbolic-compatible leap second interpolator.

Returns a cached Interpolator that maps UTC JD to TAI-UTC offset. Uses linear interpolation for smooth (differentiable) approximation.

Note
The returned interpolator is constructed once and cached.
Linear interpolation gives a smooth ramp during leap second transitions. For gradient-based optimization spanning months, this smooth approximation provides well-defined gradients.

◆ leap_seconds_at_tai()

int vulcan::time::leap_seconds_at_tai ( double tai_jd)
inlinenodiscard

Get TAI - UTC offset (leap seconds) for a given TAI Julian Date.

Parameters
tai_jdJulian Date in TAI scale
Returns
TAI - UTC in integer seconds
Note
Returns 10 for dates before 1972-01-01 (approximation)
Returns latest value (37) for dates after the table

◆ leap_seconds_at_utc()

int vulcan::time::leap_seconds_at_utc ( double utc_jd)
inlinenodiscard

Get TAI - UTC offset for a given UTC Julian Date.

Parameters
utc_jdJulian Date in UTC scale
Returns
TAI - UTC in integer seconds
Warning
During a leap second (23:59:60 UTC), this function returns the new offset. The leap second itself is ambiguous in JD.
Examples
/home/runner/work/vulcan/vulcan/include/vulcan/time/Epoch.hpp.

◆ leap_seconds_symbolic()

template<typename Scalar>
Scalar vulcan::time::leap_seconds_symbolic ( const Scalar & utc_jd)
nodiscard

Symbolic leap second lookup (smooth approximation).

Uses janus::Interpolator for symbolic-compatible table lookup. Linear interpolation provides smooth transitions at leap second boundaries.

Template Parameters
ScalarNumeric or symbolic type
Parameters
utc_jdJulian Date in UTC scale
Returns
TAI - UTC offset (smooth approximation for symbolic, exact at table points)

◆ mjd_to_jd()

template<typename Scalar>
Scalar vulcan::time::mjd_to_jd ( const Scalar & mjd)
nodiscardconstexpr

Convert Modified Julian Date to Julian Date.

◆ next_leap_second()

double vulcan::time::next_leap_second ( double utc_jd)
inlinenodiscard

Get the date of the next leap second after a given date.

Parameters
utc_jdJulian Date in UTC scale
Returns
Julian Date of next leap second, or 0.0 if unknown/none scheduled

◆ tai_to_gps()

template<typename Scalar>
Scalar vulcan::time::tai_to_gps ( const Scalar & tai_jd)
nodiscardconstexpr

Convert TAI Julian Date to GPS Julian Date.

GPS = TAI - 19 seconds (exact, GPS was synchronized with TAI at epoch)

Examples
/home/runner/work/vulcan/vulcan/include/vulcan/time/Epoch.hpp.

◆ tai_to_tt()

template<typename Scalar>
Scalar vulcan::time::tai_to_tt ( const Scalar & tai_jd)
nodiscardconstexpr

Convert TAI Julian Date to TT Julian Date.

TT = TAI + 32.184 seconds (exact, by definition)

Template Parameters
ScalarNumeric or symbolic type
Examples
/home/runner/work/vulcan/vulcan/include/vulcan/time/Epoch.hpp.

◆ tai_to_utc() [1/2]

template<typename Scalar>
Scalar vulcan::time::tai_to_utc ( const Scalar & tai_jd,
int delta_at )
nodiscardconstexpr

Convert TAI Julian Date to UTC Julian Date (templated).

Template Parameters
ScalarNumeric or symbolic type
Parameters
tai_jdJulian Date in TAI scale
delta_atTAI - UTC offset in seconds
Returns
Julian Date in UTC scale
Examples
/home/runner/work/vulcan/vulcan/include/vulcan/time/Epoch.hpp.

◆ tai_to_utc() [2/2]

double vulcan::time::tai_to_utc ( double tai_jd)
inlinenodiscard

Convert TAI Julian Date to UTC Julian Date (numeric, auto lookup).

◆ tai_to_utc_symbolic()

template<typename Scalar>
Scalar vulcan::time::tai_to_utc_symbolic ( const Scalar & tai_jd)
nodiscard

Convert TAI Julian Date to UTC Julian Date (fully symbolic).

Uses janus::Interpolator for smooth leap second lookup. Note: For TAI→UTC, we approximate by using the TAI JD directly in the interpolator (small error during leap second transitions).

◆ tdb_to_tt()

template<typename Scalar>
Scalar vulcan::time::tdb_to_tt ( const Scalar & tdb_jd)
nodiscard

Convert TDB Julian Date to TT Julian Date.

Inverse of tt_to_tdb. Since the correction is small (~1.7 ms max), a single iteration is sufficient.

◆ tt_to_tai()

template<typename Scalar>
Scalar vulcan::time::tt_to_tai ( const Scalar & tt_jd)
nodiscardconstexpr

Convert TT Julian Date to TAI Julian Date.

Examples
/home/runner/work/vulcan/vulcan/include/vulcan/time/Epoch.hpp.

◆ tt_to_tdb()

template<typename Scalar>
Scalar vulcan::time::tt_to_tdb ( const Scalar & tt_jd)
nodiscard

Convert TT Julian Date to TDB Julian Date.

TDB = TT + periodic terms due to Earth's orbital eccentricity. Uses the simplified formula from Fairhead & Bretagnon (1990): TDB - TT ≈ 0.001657 * sin(g) + 0.000022 * sin(L - D)

where g is the mean anomaly of Earth's orbit. Accuracy: ~2 ms (sufficient for most applications)

Template Parameters
ScalarNumeric or symbolic type
Examples
/home/runner/work/vulcan/vulcan/include/vulcan/time/Epoch.hpp.

◆ utc_jd_to_gps_week()

std::pair< int, double > vulcan::time::utc_jd_to_gps_week ( double utc_jd,
int delta_at )
inlinenodiscard

Convert UTC Julian Date to GPS week and seconds.

Parameters
utc_jdJulian Date in UTC scale
delta_atTAI - UTC offset
Returns
Pair of (week, seconds_of_week)

◆ utc_jd_to_gps_week_auto()

std::pair< int, double > vulcan::time::utc_jd_to_gps_week_auto ( double utc_jd)
inlinenodiscard

Convert UTC Julian Date to GPS week and seconds (auto leap second lookup).

◆ utc_to_gps() [1/2]

template<typename Scalar>
Scalar vulcan::time::utc_to_gps ( const Scalar & utc_jd,
int delta_at )
nodiscardconstexpr

Convert UTC Julian Date to GPS Julian Date (templated).

GPS = TAI - 19s, so GPS = UTC + (delta_at - 19)

◆ utc_to_gps() [2/2]

double vulcan::time::utc_to_gps ( double utc_jd)
inlinenodiscard

Convert UTC Julian Date to GPS Julian Date (numeric, auto lookup).

◆ utc_to_tai() [1/2]

template<typename Scalar>
Scalar vulcan::time::utc_to_tai ( const Scalar & utc_jd,
int delta_at )
nodiscardconstexpr

Convert UTC Julian Date to TAI Julian Date (templated).

Template Parameters
ScalarNumeric or symbolic type
Parameters
utc_jdJulian Date in UTC scale
delta_atTAI - UTC offset in seconds (from leap second table)
Returns
Julian Date in TAI scale
Note
For symbolic mode, user provides delta_at as constant for their epoch
Examples
/home/runner/work/vulcan/vulcan/include/vulcan/time/Epoch.hpp.

◆ utc_to_tai() [2/2]

double vulcan::time::utc_to_tai ( double utc_jd)
inlinenodiscard

Convert UTC Julian Date to TAI Julian Date (numeric, auto lookup).

Automatically looks up leap seconds from the table.

◆ utc_to_tai_symbolic()

template<typename Scalar>
Scalar vulcan::time::utc_to_tai_symbolic ( const Scalar & utc_jd)
nodiscard

Convert UTC Julian Date to TAI Julian Date (fully symbolic).

Uses janus::Interpolator for smooth leap second lookup. Suitable for optimization problems spanning leap second boundaries.

Template Parameters
ScalarNumeric or symbolic type
Parameters
utc_jdJulian Date in UTC scale
Returns
Julian Date in TAI scale (with smooth leap second approximation)

Variable Documentation

◆ GPS_CURRENT_ROLLOVER

int vulcan::time::GPS_CURRENT_ROLLOVER = 2
inlineconstexpr

Current GPS week rollover count (post-April 2019).

◆ GPS_WEEK_ROLLOVER

int vulcan::time::GPS_WEEK_ROLLOVER = 1024
inlineconstexpr

GPS week number rollover constant.

GPS week numbers roll over every 1024 weeks (~19.7 years). First rollover: August 22, 1999 Second rollover: April 6, 2019

◆ LEAP_SECOND_TABLE

std::array<LeapSecondEntry, 28> vulcan::time::LEAP_SECOND_TABLE
inlineconstexpr
Initial value:
= {{
{1972, 1, 1, 10},
{1972, 7, 1, 11}, {1973, 1, 1, 12}, {1974, 1, 1, 13}, {1975, 1, 1, 14},
{1976, 1, 1, 15}, {1977, 1, 1, 16}, {1978, 1, 1, 17}, {1979, 1, 1, 18},
{1980, 1, 1, 19}, {1981, 7, 1, 20}, {1982, 7, 1, 21}, {1983, 7, 1, 22},
{1985, 7, 1, 23}, {1988, 1, 1, 24}, {1990, 1, 1, 25}, {1991, 1, 1, 26},
{1992, 7, 1, 27}, {1993, 7, 1, 28}, {1994, 7, 1, 29}, {1996, 1, 1, 30},
{1997, 7, 1, 31}, {1999, 1, 1, 32}, {2006, 1, 1, 33}, {2009, 1, 1, 34},
{2012, 7, 1, 35}, {2015, 7, 1, 36}, {2017, 1, 1, 37},
}}

Complete leap second table from 1972 to present.

Source: IERS Bulletin C (https://hpiers.obspm.fr/iers/bul/bulc/bulletinc.dat) Last updated: Bulletin C 69 (July 2024) - no leap second through June 2025

Note
Before 1972, UTC used fractional offsets (not supported here). For pre-1972 dates, use TAI = UTC + 10s as approximation.