Integration Guide
Time Systems
All Vedākṣha computations use Julian Day numbers as their primary time input. This page covers what Julian Days are, how to convert to and from calendar dates, and the relationships between the various time scales used internally.
Julian Day Numbers
A Julian Day (JD) number is a continuous count of days since noon on 1 January 4713 BCE in the proleptic Julian calendar (approximately 6 November 4714 BCE in the Gregorian calendar). The fractional part of the JD represents the time of day, where 0.0 = noon and 0.5 = midnight.
Using a single monotonically increasing number eliminates ambiguities around calendar reforms, year-zero conventions, and timezone offsets. Every celestial event throughout history has a unique, unambiguous JD.
J2000.0
JD 2451545.01 January 2000, 12:00 TT. The standard astronomical reference epoch.
20 Mar 2024, noon
JD 2460389.02024 vernal equinox. All examples in this guide use this date.
1 Jan 1900, noon
JD 2415021.0Common epoch for older astronomical tables and algorithms.
Calendar Conversions
Vedākṣha provides two functions for converting between Gregorian calendar dates and Julian Day numbers. Both use the proleptic Gregorian calendar for dates before 15 October 1582.
use vedaksha::prelude::*;
// calendar_to_jd(year, month, day, hour_ut)
// hour_ut is decimal hours in Universal Time
let jd = calendar_to_jd(2024, 3, 20, 6.5);
// 6.5 = 06:30 UT
// → 2460388.771
// jd_to_calendar(jd) → CalendarDate
let date = jd_to_calendar(jd);
println!("{}-{:02}-{:02} {:05.2}h UT",
date.year, date.month, date.day, date.hour_ut);
// → 2024-03-20 06.50h UT
// Handling local time with UTC offset
let local_hour = 12.0_f64; // noon local
let utc_offset = 5.5_f64; // IST = UTC+5:30
let ut = local_hour - utc_offset;
let jd_local = calendar_to_jd(2024, 3, 20, ut);Time Zone Responsibility
Vedākṣha works in Universal Time (UT). Converting a local birth time to UT before calling calendar_to_jd is the caller's responsibility. Subtracting the UTC offset from the local hour (as shown above) is the standard approach.
Time Scale Relationships
Several time scales are used within an ephemeris computation. Understanding their relationships helps when debugging precision issues or integrating with external data sources.
UTC — Coordinated Universal Time
Civil timekeeping standard. Stays within 0.9 seconds of UT1 by inserting leap seconds. What your system clock returns.
UT1 — Universal Time 1
Earth's rotation angle relative to the Sun. Slightly irregular due to tidal braking and geophysical processes. Used to compute GMST (sidereal time).
TT — Terrestrial Time
Uniform atomic time scale used for ephemeris calculations. Currently runs about 69 seconds ahead of UT1 (ΔT = TT − UT1 ≈ 69 s in 2024).
TDB — Barycentric Dynamical Time
Like TT, but accounts for relativistic time dilation as Earth moves around the Sun. Differs from TT by at most ±1.7 ms. The JPL DE440 ephemeris is referenced to TDB.
What Vedākṣha Does For You
When you pass a Julian Day derived from a civil time to compute, Vedākṣha automatically applies ΔT to convert it to TT (and then TDB for the ephemeris query). You do not need to add ΔT manually. If you need to supply a TT-based Julian Day directly, use compute_tt instead.
Delta T (ΔT)
ΔT is the accumulated difference between TT and UT1. It is always positive and grows over time because Earth's rotation is slowly decelerating due to tidal friction from the Moon. Vedākṣha uses published USNO and IERS tables for historical dates and a polynomial extrapolation for future dates.
// Query ΔT for any Julian Day
let jd = calendar_to_jd(2024, 3, 20, 12.0);
let dt = delta_t(jd)?;
println!("ΔT = {:.2} seconds", dt); // ≈ 69.18 s
// Convert UT Julian Day to TT Julian Day manually
let jd_tt = ut_to_tt(jd)?;
// Or override ΔT if you have a more precise value
let custom = DeltaTConfig::fixed(69.22);
let jd_tt2 = ut_to_tt_with_config(jd, &custom)?;500 BCE
ΔT ≈ ~17,190 sDominates ancient chart uncertainty.
1900 CE
ΔT ≈ ~3 sWell-known from historical records.
2024 CE
ΔT ≈ ~69 sPublished monthly by IERS.
Sidereal Time Functions
let jd = calendar_to_jd(2024, 3, 20, 12.0);
let geo_lon = 77.2090; // New Delhi, degrees east
// Greenwich Mean Sidereal Time (hours)
let gmst = greenwich_mean_sidereal_time(jd)?;
// Greenwich Apparent Sidereal Time (hours, includes nutation)
let gast = greenwich_apparent_sidereal_time(jd)?;
// Local Apparent Sidereal Time (hours)
let last = local_apparent_sidereal_time(jd, geo_lon)?;
// RAMC in degrees (used for house computation)
let ramc = last * 15.0;
println!("GMST : {:.6} h", gmst);
println!("GAST : {:.6} h", gast);
println!("LAST : {:.6} h", last);
println!("RAMC : {:.4}°", ramc);