celestial_core/precession/
mod.rs

1//! Precession models for transforming coordinates between epochs.
2//!
3//! Precession is the slow, continuous change in the orientation of Earth's rotational
4//! axis caused by gravitational torques from the Sun and Moon acting on Earth's
5//! equatorial bulge. The axis traces a cone in space with a period of approximately
6//! 26,000 years (the "Platonic year"), causing the celestial pole to drift among
7//! the stars and the vernal equinox to move westward along the ecliptic.
8//!
9//! This module provides rotation matrices that transform celestial coordinates from
10//! one epoch to another, accounting for the accumulated precession between epochs.
11//!
12//! # Available Models
13//!
14//! ## IAU 2000
15//!
16//! The IAU 2000 precession model ([`PrecessionIAU2000`]) uses the Lieske (1977)
17//! precession angles with corrections from the IAU 2000A nutation model. It computes
18//! three rotation angles (psi_A, omega_A, chi_A) to construct the precession matrix.
19//!
20//! The frame bias matrix accounts for the offset between the J2000.0 dynamical frame
21//! and the ICRS (International Celestial Reference System), which amounts to a few
22//! milliarcseconds.
23//!
24//! ## IAU 2006
25//!
26//! The IAU 2006 precession model ([`PrecessionIAU2006`]) uses the Fukushima-Williams
27//! four-angle formulation (gamma_bar, phi_bar, psi_bar, epsilon_A). This parameterization
28//! provides improved numerical stability and separates the frame bias from the
29//! precession proper.
30//!
31//! The Fukushima-Williams angles represent:
32//! - **gamma_bar**: Frame bias in right ascension
33//! - **phi_bar**: Obliquity of the ecliptic at J2000.0
34//! - **psi_bar**: Precession in longitude
35//! - **epsilon_A**: Mean obliquity of date
36//!
37//! IAU 2006 is the current standard and should be preferred for new applications.
38//!
39//! # Output Matrices
40//!
41//! Both models produce a [`PrecessionResult`] containing:
42//!
43//! - **bias_matrix**: Transforms from GCRS (Geocentric Celestial Reference System)
44//!   to the mean equator and equinox of J2000.0. This is constant for a given model.
45//!
46//! - **precession_matrix**: Transforms from the mean equator and equinox of J2000.0
47//!   to the mean equator and equinox of date. At J2000.0 (t=0), this is the identity.
48//!
49//! - **bias_precession_matrix**: The combined transformation from GCRS to the mean
50//!   equator and equinox of date (bias_precession = precession * bias for IAU 2000,
51//!   computed directly via Fukushima-Williams for IAU 2006).
52//!
53//! # Time Argument
54//!
55//! IAU 2000 takes time as Julian centuries of TT (Terrestrial Time) since J2000.0.
56//! IAU 2006 takes a two-part Julian Date in TT for improved numerical precision.
57
58pub mod iau2000;
59pub mod iau2006;
60pub mod types;
61
62pub use iau2000::PrecessionIAU2000;
63pub use iau2006::PrecessionIAU2006;
64pub use types::{BiasMatrix, PrecessionMatrix, PrecessionResult};
65
66/// Trait for types that can compute precession matrices.
67///
68/// Implementors provide access to both IAU 2000 and IAU 2006 precession models,
69/// allowing consistent precession calculations across different time representations.
70pub trait PrecessionCalculator {
71    /// Computes precession using the IAU 2000 model.
72    ///
73    /// # Arguments
74    ///
75    /// * `tt_centuries` - Julian centuries of TT since J2000.0
76    fn precession_iau2000(&self, tt_centuries: f64) -> crate::AstroResult<PrecessionResult>;
77
78    /// Computes precession using the IAU 2006 model.
79    ///
80    /// # Arguments
81    ///
82    /// * `tt_centuries` - Julian centuries of TT since J2000.0
83    fn precession_iau2006(&self, tt_centuries: f64) -> crate::AstroResult<PrecessionResult>;
84}
celestial_core/precession/mod.rs

celestial_core/precession/
mod.rs
