Epoch

Defined in: mod.rs:119

pub struct Epoch\<S: [TimeScale](../../traits/timescale/) = [Utc](../utc/), P: [Precision](../../traits/precision/) = [Precise](../precise/)\>

An astronomical epoch represented as Julian Date in scale S, stored at precision tier P.

S defaults to Utc and P to Precise, so that Epoch (without type parameters) means Epoch<Utc, Precise> — the most common user-facing scale at sub-nanosecond precision.

内部表現: canonical TAI

内部は canonical な TAI instant を精度 tier P の表現 (P::Repr(Precision::Repr)) で保持し、S は読み出しレンズである。P = Precise なら two-part TwoPartJd、 P = Coarse なら単一 f64。jd() は格納された TAI を scale S の JD に 変換して返す: Epoch<Utc>::from_jd(x).jd() == x (UTC JD として round-trip)、 Epoch<Tdb>::from_jd_tdb(x).jd() == x (TDB JD として round-trip)。

scale 変換 (to_tt(), to_tdb() 等) は同じ TAI instant の 非破壊な再ラベルで、 leap second / Fairhead 補正は構築時 (from_*) と読み出し時 (jd()) の lens (TaiLens) でのみ適用される。同一物理 instant は同一内部値なので duration_since は leap 跨ぎ・cross-scale でも厳密な SI 秒を返す。

精度 tier の選択

豊富なコンストラクタ (from_jd, from_gregorian, …) は既定の Precise を 作る。Coarse が欲しい場合は to_precision(Self::to_precision) で 変換する (例: epoch.to_precision::<Coarse>())。tier は型の一部なので、 別 tier の Epoch 同士の演算は明示的な変換を要する。

Methods

to_tai()

fn to_tai(&self) -> [Epoch<Tai, P>](/)

Convert to TAI (re-tag of the shared canonical instant).

---

to_tt()

fn to_tt(&self) -> [Epoch<Tt, P>](/)

Convert to TT (re-tag of the shared canonical instant).

---

to_tdb()

fn to_tdb(&self) -> [Epoch<Tdb, P>](/)

Convert to TDB (re-tag of the shared canonical instant).

---

to_gps()

fn to_gps(&self) -> [Epoch<Gps, P>](/)

Convert to GPS Time (re-tag of the shared canonical instant). GPS − UTC equals the current leap count minus 19 s (18 s since 2017).

---

to_ut1_naive()

fn to_ut1_naive(&self) -> Ut1Epoch

Convert to UT1 assuming UT1 ≈ UTC (naive, legacy behavior).

真の UT1 が必要な場合は Epoch::<Utc>::to_ut1 (Ut1Offset provider を 引数に取る) を使う。本 method は NullEop 相当の dUT1 = 0 仮定で、 current arika の gmst() 実装との bit-level 互換を保つため提供される。

---

to_ut1()

fn to_ut1<E: Ut1Offset + ?Sized>(&self, eop: &E) -> Ut1Epoch

Convert to UT1 using the dUT1 = UT1 − UTC correction provided by an EOP provider.

JD_UT1 = JD_UTC + dUT1 / 86400

dUT1 is looked up at the current UTC MJD and is typically in the range ±0.9 s. This is the precise UT1 conversion — the NullEop placeholder type does not implement Ut1Offset(crate::earth::eop::Ut1Offset), so passing it is a compile error (see arika/tests/trybuild/).

The ?Sized bound lets callers pass trait objects directly (e.g. &dyn Ut1Offset or Box<dyn Ut1Offset>::as_ref()) alongside concrete types.

For a naive dUT1 = 0 conversion used by the legacy simple rotation path, use Epoch::<Utc>::to_ut1_naive instead.

---

from_jd_tai()

fn from_jd_tai(jd: f64) -> Self

Create a TAI epoch from a Julian Date value interpreted as TAI JD.

---

to_utc()

fn to_utc(&self) -> [Epoch<Utc, P>](/)

Convert to UTC (re-tag of the shared canonical instant).

---

to_tt()

fn to_tt(&self) -> [Epoch<Tt, P>](/)

Convert to TT (re-tag of the shared canonical instant).

---

to_gps()

fn to_gps(&self) -> [Epoch<Gps, P>](/)

Convert to GPS Time (re-tag of the shared canonical instant).

---

from_jd_gps()

fn from_jd_gps(jd: f64) -> Self

Create a GPS epoch from a Julian Date value interpreted as GPS JD.

---

to_tai()

fn to_tai(&self) -> [Epoch<Tai, P>](/)

Convert to TAI (re-tag of the shared canonical instant).

---

to_utc()

fn to_utc(&self) -> [Epoch<Utc, P>](/)

Convert to UTC (re-tag of the shared canonical instant).

---

from_jd_tt()

fn from_jd_tt(jd: f64) -> Self

Create a TT epoch from a Julian Date value interpreted as TT JD.

---

centuries_since_j2000()

fn centuries_since_j2000(&self) -> f64

Return TT Julian centuries since J2000.0.

この値が IAU 2006 precession / IAU 2000A/B nutation の独立変数。

---

to_tai()

fn to_tai(&self) -> [Epoch<Tai, P>](/)

Convert to TAI (re-tag of the shared canonical instant).

---

to_tdb()

fn to_tdb(&self) -> [Epoch<Tdb, P>](/)

Convert to TDB (re-tag of the shared canonical instant).

---

from_jd_tdb()

fn from_jd_tdb(jd: f64) -> Self

Create a TDB epoch from a Julian Date value interpreted as TDB JD.

JPL DE ephemerides use Teph which is for practical purposes indistinguishable from TDB (IAU 2006 Resolution B3).

---

centuries_since_j2000()

fn centuries_since_j2000(&self) -> f64

Return TDB Julian centuries since J2000.0.

Meeus / JPL DE ephemeris と IAU 2009 WGCCRE body rotation の独立変数。

---

to_tt()

fn to_tt(&self) -> [Epoch<Tt, P>](/)

Convert to TT (re-tag of the shared canonical instant).

---

from_week_seconds()

fn from_week_seconds(week: GpsWeek, sow: SecondsOfWeek) -> Self

Construct a GPS epoch from a continuous week and seconds-of-week.

---

to_week_seconds()

fn to_week_seconds(&self) -> [Option<(GpsWeek, SecondsOfWeek)>](https://doc.rust-lang.org/std/option/enum.Option.html)

Decompose into (continuous week, seconds-of-week).

Returns None unless this is a valid GPS instant — finite and at or after the GPS epoch. On that domain it is the inverse of from_week_seconds(Self::from_week_seconds), up to the f64 JD precision floor (~tens of µs at modern epochs). Returning Option keeps the SecondsOfWeek [0, 604800) invariant intact for non-finite jd() (NaN/±∞), which would otherwise slip past the float guards below.

---

scale_name()

fn scale_name() -> &‘static str

The human-readable scale name (e.g. “UTC”, “TDB”).

---

precision_name()

fn precision_name() -> &‘static str

The precision-tier name (“precise” / “coarse”).

---

duration_since()

fn duration_since<T: TimeScale>(&self, earlier: &Epoch<T, P>) -> Duration

Exact SI-second interval since earlier, measured on the shared TAI timeline — correct across leap seconds and across any scales (both epochs store canonical TAI, so earlier may be in a different scale).

Both epochs must share the precision tier P; difference a mixed pair by first aligning tiers with to_precision(Self::to_precision).

---

to_precision()

fn to_precision<Q: Precision>(&self) -> Epoch<S, Q>

Re-express this epoch at precision tier Q, preserving the same scale S and canonical TAI instant.

The instant is carried across via its (hi, lo) parts: Precise → Precise is exact, Coarse → Precise lifts the f64 (residual zero), and Precise → Coarse collapses to hi + lo (dropping the sub-f64 residual the coarse tier cannot hold).

---

jd()

fn jd(&self) -> f64

Return the Julian Date, interpreted in this scale (lens read-out of the canonical TAI instant; single-f64 collapse).

---

jd_parts()

fn jd_parts(&self) -> (f64, f64)

The Julian Date as a precise two-part (hi, lo) value — for feeding SOFA-style two-part consumers without the jd() collapse.

On the Precise tier lo carries the conversion’s sub-f64 residual; since every constructor currently ingests a single f64, it reflects the lens arithmetic, not user-supplied sub-f64 input precision (a two-part ingestion path is future work). On the Coarse tier lo is always 0.0.

---

mjd()

fn mjd(&self) -> f64

Return the Modified Julian Date, interpreted in this scale.

---

jd()

fn jd(&self) -> f64

Return the Julian Date, interpreted in this scale (lens read-out of the canonical TAI instant; single-f64 collapse).

---

jd_parts()

fn jd_parts(&self) -> (f64, f64)

The Julian Date as a precise two-part (hi, lo) value — for feeding SOFA-style two-part consumers without the jd() collapse.

On the Precise tier lo carries the conversion’s sub-f64 residual; since every constructor currently ingests a single f64, it reflects the lens arithmetic, not user-supplied sub-f64 input precision (a two-part ingestion path is future work). On the Coarse tier lo is always 0.0.

---

mjd()

fn mjd(&self) -> f64

Return the Modified Julian Date, interpreted in this scale.

---

jd()

fn jd(&self) -> f64

Return the Julian Date, interpreted in this scale (lens read-out of the canonical TAI instant; single-f64 collapse).

---

jd_parts()

fn jd_parts(&self) -> (f64, f64)

The Julian Date as a precise two-part (hi, lo) value — for feeding SOFA-style two-part consumers without the jd() collapse.

On the Precise tier lo carries the conversion’s sub-f64 residual; since every constructor currently ingests a single f64, it reflects the lens arithmetic, not user-supplied sub-f64 input precision (a two-part ingestion path is future work). On the Coarse tier lo is always 0.0.

---

mjd()

fn mjd(&self) -> f64

Return the Modified Julian Date, interpreted in this scale.

---

jd()

fn jd(&self) -> f64

Return the Julian Date, interpreted in this scale (lens read-out of the canonical TAI instant; single-f64 collapse).

---

jd_parts()

fn jd_parts(&self) -> (f64, f64)

The Julian Date as a precise two-part (hi, lo) value — for feeding SOFA-style two-part consumers without the jd() collapse.

On the Precise tier lo carries the conversion’s sub-f64 residual; since every constructor currently ingests a single f64, it reflects the lens arithmetic, not user-supplied sub-f64 input precision (a two-part ingestion path is future work). On the Coarse tier lo is always 0.0.

---

mjd()

fn mjd(&self) -> f64

Return the Modified Julian Date, interpreted in this scale.

---

jd()

fn jd(&self) -> f64

Return the Julian Date, interpreted in this scale (lens read-out of the canonical TAI instant; single-f64 collapse).

---

jd_parts()

fn jd_parts(&self) -> (f64, f64)

The Julian Date as a precise two-part (hi, lo) value — for feeding SOFA-style two-part consumers without the jd() collapse.

On the Precise tier lo carries the conversion’s sub-f64 residual; since every constructor currently ingests a single f64, it reflects the lens arithmetic, not user-supplied sub-f64 input precision (a two-part ingestion path is future work). On the Coarse tier lo is always 0.0.

---

mjd()

fn mjd(&self) -> f64

Return the Modified Julian Date, interpreted in this scale.

---

from_jd()

fn from_jd(jd: f64) -> Self

Create a UTC epoch from a Julian Date (treated as UTC JD).

Epoch<Utc>::from_jd(x).jd() == x (round-trip identity). The value is stored internally as the corresponding canonical TAI instant.

---

from_mjd()

fn from_mjd(mjd: f64) -> Self

Create a UTC epoch from a Modified Julian Date value.

---

j2000()

fn j2000() -> Self

The J2000.0 reference epoch (JD 2451545.0).

歴史的には J2000.0 = 2000-01-01 12:00:00 TT だが、本実装では UTC scale で JD 2451545.0 を返す (後方互換のため)。厳密な TT J2000 を得るには Epoch::<Tt>::from_jd_tt を使う。

---

from_datetime()

fn from_datetime(dt: &DateTime) -> Self

Create a UTC epoch from a DateTime value.

---

from_gregorian()

fn from_gregorian(year: i32, month: u32, day: u32, hour: u32, min: u32, sec: f64) -> Self

Create a UTC epoch from Gregorian calendar date and time.

Uses the standard Julian Date algorithm valid for dates after the Gregorian calendar reform (1582-10-15).

---

from_iso8601()

fn from_iso8601(s: &str) -> Option<Self>

Parse a UTC epoch from ISO 8601 (CCSDS-compatible).

Accepts both the calendar form YYYY-MM-DDTHH:MM:SS[.fff] and the ordinal / day-of-year form YYYY-DDDTHH:MM:SS[.fff] (used by CCSDS OMM). The Z suffix is optional — the timestamp is interpreted as UTC either way. Returns None if parsing fails.

---

now()

fn now() -> Self

Available on crate feature std only.

Create a UTC epoch from the current system time.

---

from_year_day_of_year()

fn from_year_day_of_year(year: i32, day_of_year: f64) -> Self

Create a UTC epoch from a 4-digit year and a fractional day of year (1.0 = Jan 1 00:00, 1.5 = Jan 1 12:00, …).

---

from_tle_epoch()

fn from_tle_epoch(year_2digit: u32, day_of_year: f64) -> Self

Create a UTC epoch from a TLE epoch (2-digit year + fractional day of year).

2-digit year convention (NORAD): 57-99 → 1957-1999, 00-56 → 2000-2056.

---

centuries_since_j2000()

fn centuries_since_j2000(&self) -> f64

Julian centuries since J2000.0, computed directly from the UTC JD.

Note: This treats the UTC JD as if it were a dynamical-time JD, which is strictly incorrect for high-precision ephemeris calculations. For Meeus/JPL DE usage, prefer epoch.to_tdb().centuries_since_j2000(). This method is kept for legacy bit-level compatibility where UTC centuries were used interchangeably with dynamical-time centuries.

---

add_seconds()

fn add_seconds(&self, dt: f64) -> Self

Advance the epoch by dt seconds using naive UTC-JD arithmetic (utc_jd + dt/86400). Does NOT handle leap second boundaries.

Legacy API. For leap-second-aware (SI-second) arithmetic use add_si_seconds(Self::add_si_seconds) instead.

---

add_si_seconds()

fn add_si_seconds(&self, dt: f64) -> Self

Advance the epoch by dt SI seconds, handling leap second boundaries.

Adds dt directly on the stored canonical TAI instant (a uniform SI timeline), so leap seconds are handled automatically on read-out: 5 SI seconds from 2016-12-31T23:59:58 lands at 2017-01-01T00:00:02 (not 00:00:03), because one SI second is “consumed” by the 2017-01-01 leap.

---

to_datetime()

fn to_datetime(&self) -> DateTime

Convert to Gregorian calendar date and time (UTC).

---

to_datetime_normalized()

fn to_datetime_normalized(&self) -> DateTime

Convert to Gregorian calendar date and time (UTC), with leap second instants normalized to 00:00:00 of the next day.

Alias for to_datetime(Self::to_datetime) in Phase 1A (leap-instant display 23:59:60 is not yet distinguished).

---

gmst()

fn gmst(&self) -> f64

Greenwich “sidereal time” in radians. Legacy method.

Actually computes the Earth Rotation Angle (IAU 2000 B1.8 / SOFA iauEra00) assuming UT1 ≈ UTC (ignores dUT1). For the proper canonical form use Ut1Epoch::era after an explicit UT1 conversion via a proper EOP provider.

Kept on Epoch<Utc> for bit-level compatibility with the pre-refactor Epoch::gmst method. Will be removed when downstream callers migrate to Ut1Epoch::era.

---

Trait Implementations

• Clone
• Copy
• PartialEq
• Debug