astro/doc/manual/en/timescale.md

Time scales

中文 | README

UTC, UT1 and TT express the same physical instant using different scales. UTC is civil time, UT1 follows Earth's rotation, and TT is used for ephemerides. The relevant differences are ΔT = TT − UT1 and DUT1 = UT1 − UTC, both in seconds.

Contents

• Time arguments
• time.Time conversion API
• Julian-day conversion API
• TCG, TCB and TDB
• ΔT models
  • Comparing models
  • Supplying an external model
• UTC assumptions beyond the observed interval
• SVG, GeoJSON and KML labels

Time arguments

Most observing APIs accept a civil instant as time.Time, obtain its UTC value, and convert to UT1 or TT as needed. Changing Location changes the displayed clock reading.

Date-based searches such as rise/set also use it to identify the local civil date.

Before 1972-01-01, this library treats civil time as UT1. This is a library convention, not a claim that UTC did not exist. From 1972 onward, the leap-second table, selected policy or explicit override supplies TT−UTC, while the ΔT model supplies TT−UT1.

Some inputs have separate conventions:

Input	Interpretation
Argument to astro.TTFromUTC / UT1FromUTC	Civil instant in any time zone
Argument to astro.UTCFromTT / UTCFromUT1	TT / UT1 reading carried in a UTC Location
Argument to astro.TCGFromTT / TCBFromTT / TDBFromTT	TT reading, not a civil UTC instant
orbit.Elements.EpochJD / TpJD	TT/TDB Julian day; see Orbits
Numerical JD arguments in basic	Scale specified by the function contract; the number carries no scale metadata
calendar.Date2JD / basic.Date2JD	Reads calendar and clock fields without converting zones; pass date.UTC() for a UTC JD
Chinese calendar conversion	Date semantics described in Calendars, using Beijing time by default

time.Time cannot represent the leap-second reading 23:59:60. Historical dates also require care: the library's Julian/Gregorian transition differs from Go's proleptic Gregorian calendar.

time.Time conversion API

These functions belong to the root package b612.me/astro.

Function	Result
TTFromUTC(date)	TT reading for the same instant
UTCFromTT(tt)	Civil instant corresponding to a TT reading
UT1FromUTC(date)	UT1 reading for the same instant
UTCFromUT1(ut1)	Civil instant corresponding to a UT1 reading
DUT1(date)	UT1−UTC in seconds
LabelIn(scale, date)	Original input for TimeScaleUTC; UT1 reading for TimeScaleUT1
TCGFromTT(tt) / TTFromTCG(tcg)	Convert between TT and Geocentric Coordinate Time
TCBFromTT(tt) / TTFromTCB(tcb)	Convert between TT and Barycentric Coordinate Time using a geocentric approximation
TDBFromTT(tt) / TTFromTDB(tdb)	Convert between TT and Barycentric Dynamical Time using a geocentric approximation
TCBFromTDB(tdb) / TDBFromTCB(tcb)	Linear conversions between TDB and TCB
TCGMinusTT(tt) / TCBMinusTT(tt) / TDBMinusTT(tt)	Offset from TT in seconds; input is a TT reading

Converted TT, UT1, TCG, TCB and TDB values use time.Time and a UTC Location, but their fields are readings on the named scale. Passing them to an API expecting civil time, such as the Sun and Moon functions, would shift the calculation instant again.

Use the inverse conversion to recover civil time.

package main

import (
	"fmt"
	"time"

	"b612.me/astro"
)

func main() {
	date := time.Date(2026, 4, 1, 0, 0, 0, 0, time.UTC)
	tt := astro.TTFromUTC(date)
	ut1 := astro.UT1FromUTC(date)
	fmt.Println("UTC:", date.Format(time.RFC3339Nano))
	fmt.Println("TT:", tt.Format("2006-01-02 15:04:05.000000"))
	fmt.Println("UT1:", ut1.Format("2006-01-02 15:04:05.000000"))
	fmt.Printf("DUT1: %.6f s\n", astro.DUT1(date))
	fmt.Println("UTC from TT:", astro.UTCFromTT(tt).Format(time.RFC3339Nano))
}

Conversions pass through floating-point Julian days, so round trips can have small rounding differences. The TT/UT1 display formats omit Z to avoid presenting them as UTC timestamps.

Julian-day conversion API

The following basic functions use float64. Conversion functions return Julian days; offset functions return seconds.

Function	Input → output	Notes
UTC2TT	UTC JD → TT JD	Uses UT1 before 1972, then the TT−UTC model
TT2UTC	TT JD → UTC JD	Inverse conversion
UT12TT	UT1 JD → TT JD	Uses the active ΔT model
TT2UT1	TT JD → UT1 JD	Inverse conversion
UTC2UT1	UTC JD → UT1 JD	Equivalent to TT2UT1(UTC2TT(jd))
UT12UTC	UT1 JD → UTC JD	Inverse conversion
TTMinusUTCSeconds	UTC JD → seconds	32.184 + (TAI−UTC) in the built-in leap-second interval, unless overridden
DUT1Seconds	UTC JD → seconds	(TT−UTC) − ΔT
DeltaT	JD or decimal year → seconds	Second argument true: UT Julian day; false: decimal year
TT2TCG / TCG2TT	TT JD ↔ TCG JD	Linear conversion
TT2TCB / TCB2TT	TT JD ↔ TCB JD	Geocentric approximation
TT2TDB / TDB2TT	TT JD ↔ TDB JD	Geocentric approximation
TCB2TDB / TDB2TCB	TCB JD ↔ TDB JD	Linear conversion including TDB0
TCGMinusTTSeconds / TCBMinusTTSeconds / TDBMinusTTSeconds	TT JD → seconds	Offset from TT

A leap second or simulated leap hour introduces a step. The inverse TT-to-civil conversion has an unrepresentable interval of that width, so pointwise round-trip identity cannot hold across it.

TTMinusUTCSeconds and DefaultTTMinusUTC() expose the leap-table value (or the override for the former); they do not apply the future-policy extrapolation used by UTC2TT. For future civil-to-TT conversion, call UTC2TT or TTFromUTC directly.

TCG, TCB and TDB

TCG is Geocentric Coordinate Time. TCB and TDB are Barycentric Coordinate Time and Barycentric Dynamical Time, referring to the Solar System barycenter rather than the center of the Sun. TT/TCG and TCB/TDB have defining linear relations. The TT/TDB relation implemented here is a geocentric approximation, without observer-dependent diurnal terms.

With T0 = 2443144.5003725, LG = 6.969290134e-10, LB = 1.550519768e-8 and TDB0 = −65.5e-6 seconds, the relations for JD readings are:

TCG − TT = LG / (1 − LG) × (TT − T0)
TDB = TCB − LB × (TCB − T0) + TDB0 / 86400
TCB − TT = [LB × (TT − T0) + (TDB − TT) − TDB0 / 86400] / (1 − LB)

The reference epoch T0 does not imply that all four scales have equal readings there. Near modern dates, the main annual TDB−TT term has an amplitude of about 1.7 ms. TCG−TT increases by about 0.022 seconds per year and TCB−TT by about 0.489 seconds per year.

TDB−TT uses a 40-term truncated series with mass adjustments. Over years −3000 to +6000, the sum of omitted absolute amplitudes gives a conservative truncation-error bound of 11 µs relative to the full 787-term geocentric series. Sampling every 31 days gives a maximum difference of about 2.0 µs. A sampled maximum is not an all-time guarantee, and truncation error excludes the error of the full model itself. No accuracy is promised outside that interval.

A single float64 JD has a resolution of about 40 µs near modern dates; the time.Time wrappers pass through the same rounding. For microsecond-level offsets, use *MinusTT or *MinusTTSeconds rather than subtracting two full Julian days and converting to seconds.

ΔT models

The default combines SMH2016 and Morrison 2021 splines and long-term extrapolation, using a monthly observed ΔT table wherever available. The table currently extends to September 1, 2026; the last point is a rapid observation, not yet a final solution. Constant endpoint adjustments keep extrapolation continuous.

DeltaT returns NaN outside ±40000 years.

Constant	Model
DeltaTModelDefault / DeltaTModelSMH2016	Built-in default
DeltaTModelMS2004	Morrison & Stephenson 2004: ΔT = −20 + 32u², u = (year−1820)/100
DeltaTModelEspenakMeeus2006	Espenak & Meeus 2006 piecewise polynomials
DeltaTModelNASACanon2006	Those polynomials plus the NASA canon pairing term −0.000012932(year−1955)² before 1955
DeltaTModelManual	Status indicating an injected function; not an installable named model

SetDeltaTModel(model, keepObserved) changes the process-wide model and reports success. Unknown models leave the current state unchanged. With keepObserved=true, observations take precedence; false uses the selected model everywhere.

GetDeltaTModel() returns both settings.

Comparing models

DeltaTModelSeconds evaluates a model without changing process state:

package main

import (
	"fmt"
	"time"

	"b612.me/astro"
	"b612.me/astro/basic"
)

func main() {
	date := time.Date(2100, 1, 1, 0, 0, 0, 0, time.UTC)
	jd := basic.Date2JD(date)
	for _, model := range []astro.DeltaTModel{
		astro.DeltaTModelSMH2016,
		astro.DeltaTModelEspenakMeeus2006,
		astro.DeltaTModelNASACanon2006,
	} {
		fmt.Println(model, astro.DeltaTModelSeconds(model, jd, false))
	}
}

Future ΔT is uncertain. The current Espenak–Meeus 2006 and default models differ by about 11, 21, 116 and 275 seconds in 2035, 2050, 2100 and 2200. This affects future eclipse times and ground paths.

Match ΔT models before comparing eclipse catalogs.

Supplying an external model

Root-package function	Purpose
DeltaT() / SetDeltaT(fn)	Get/set a ΔT function of type func(float64, bool) float64
DefaultDeltaT()	Obtain the built-in default ΔT function
TTMinusUTC() / SetTTMinusUTC(fn)	Get/set a TT−UTC override of type func(float64) float64; argument is a civil JD
DefaultTTMinusUTC()	Built-in leap-second-table function, ignoring overrides and future policy

Both callbacks return seconds. SetDeltaT(nil) restores default ΔT; SetTTMinusUTC(nil) restores the built-in leap-second table and future policy. TTMinusUTC() returns nil when no override is installed.

The corresponding basic functions are GetDeltaTFn / SetDeltaTFn and GetTTMinusUTCFn / SetTTMinusUTCFn. They share root-package state. A TT−UTC override takes precedence over future policy for queries from 1972 onward; dates before 1972 retain the UT1 convention.

These settings affect subsequent calculations throughout the process. Configure them before calculating. Restore the original function or named model after temporary comparisons; a model change is not a per-call option.

UTC assumptions beyond the observed interval

SetTimeScaleFuturePolicy and GetTimeScaleFuturePolicy select the civil-time conversion policy, defaulting to TimeScaleLeapSecond. All policies apply only after the observed interval except TimeScaleUT1Civil, which replaces the scale throughout the timeline. An explicit TT−UTC override takes precedence from 1972 onward. This setting is separate from the output-scale options TimeScaleUTC and TimeScaleUT1.

Policy	Assumption
TimeScaleLeapSecond (zero value, default)	Applies the fewest integer-second corrections to the final TT−UTC offset to bring extrapolated DUT1 within ±0.9 seconds
TimeScaleAssumeUT1Tracking	Holds the final observed DUT1 constant, allowing TT−UTC to follow extrapolated ΔT smoothly
TimeScaleFreezeUTCOffset	Holds TT−UTC at its final built-in value, currently 69.184 seconds
TimeScaleLeapHour	Applies the fewest whole-hour corrections to bring DUT1 within ±3600 seconds; intended for scenario calculations
TimeScaleUT1Civil	Treats civil time as UT1 throughout the timeline, including the historical leap-table interval; DUT1 is zero unless explicitly overridden

These are calculation assumptions, not predictions of future leap seconds or international decisions. Integer-second or hour corrections depend on ΔT at the queried instant; they do not track prior corrections or restrict steps to announcement calendar boundaries. Pointwise round trips need not be identical near a step. A stepping policy returns NaN when its ΔT is invalid or outside the model range, rather than falling back to a normal offset.

The default does not guarantee an error below 0.9 seconds against real future UTC. Precise civil timing requires published data for the relevant date.

SVG, GeoJSON and KML labels

SVG and GeoJSON default to civil labels. For UT1, use a ...InUT1 result-conversion function or set TimeScale: astro.TimeScaleUT1 in export options. UT1 output requires Location to be nil or time.UTC.

Changing a label scale leaves existing geometry at the same physical instant. Time markers aligned to whole ticks of the selected scale may sample different instants, so their positions can move. GeoJSON records the scale in time_scale.

KML requires UTC <when> values, so the converter changes UT1 labels back to UTC using the active model and preserves the original time_scale property.

Use the same time-scale model when generating GeoJSON and converting it to KML. Export options, marker steps and KML playback are described in Maps and data export.