celestial_core/lib.rs
1//! Low-level astronomical calculations for coordinate transformations.
2//!
3//! `celestial-core` provides the mathematical building blocks for celestial mechanics:
4//! rotation matrices, nutation/precession models, angle handling, and geodetic conversions.
5//! It implements IAU 2000/2006 standards in pure Rust with no runtime FFI.
6//!
7//! # Modules
8//!
9//! | Module | Purpose |
10//! |--------|---------|
11//! | [`angle`] | Angle types, parsing (HMS/DMS), normalization, validation |
12//! | [`matrix`] | 3×3 rotation matrices and 3D vectors |
13//! | [`nutation`] | IAU 2000A/2000B/2006A nutation models |
14//! | [`precession`] | IAU 2000/2006 precession (Fukushima-Williams angles) |
15//! | [`cio`] | CIO-based GCRS↔CIRS transformations |
16//! | [`obliquity`] | Mean obliquity of the ecliptic (IAU 1980, 2006) |
17//! | [`location`] | Observer geodetic coordinates, geocentric conversion |
18//! | [`constants`] | Astronomical constants (J2000, WGS84, unit conversions) |
19//! | [`errors`] | [`AstroError`] and [`AstroResult`] |
20//!
21//! # Coordinate Transformation Pipeline
22//!
23//! GCRS → CIRS transformation (CIO-based):
24//!
25//! ```ignore
26//! // 1. Compute precession-nutation-bias matrix
27//! let fw = FukushimaWilliamsAngles::iau2006a(tt_centuries);
28//! let nutation = NutationIAU2006A::new().compute(jd1, jd2)?;
29//! let npb = fw.build_npb_matrix(nutation.delta_psi, nutation.delta_eps);
30//!
31//! // 2. Extract CIO quantities
32//! let cio = CioSolution::calculate(&npb, tt_centuries)?;
33//!
34//! // 3. Build GCRS→CIRS matrix
35//! let matrix = gcrs_to_cirs_matrix(cio.cip.x, cio.cip.y, cio.s);
36//! ```
37//!
38//! # Re-exports
39//!
40//! Common types are re-exported at the crate root for convenience:
41//!
42//! ```
43//! use celestial_core::{Angle, Vector3, RotationMatrix3, Location};
44//! use celestial_core::{AstroError, AstroResult, MathErrorKind};
45//! ```
46//!
47//! # Design Notes
48//!
49//! - **Two-part Julian Dates**: Functions accepting `(jd1, jd2)` preserve precision by
50//! splitting the date. Typically `jd1 = 2451545.0` (J2000.0) and `jd2` is days from epoch.
51//!
52//! - **Radians internally**: All angular computations use radians. The [`Angle`] type
53//! provides conversion methods for degrees/HMS/DMS display.
54//!
55//! - **No implicit state**: Models like [`NutationIAU2006A`](nutation::NutationIAU2006A)
56//! are stateless calculators. Call `compute(jd1, jd2)` with any epoch.
57
58pub mod angle;
59pub mod cio;
60pub mod constants;
61pub mod errors;
62pub mod location;
63pub mod math;
64pub mod matrix;
65pub mod nutation;
66pub mod obliquity;
67pub mod precession;
68pub mod utils;
69
70pub use angle::Angle;
71pub use cio::{gcrs_to_cirs_matrix, CioLocator, CioSolution, CipCoordinates, EquationOfOrigins};
72pub use errors::{AstroError, AstroResult, MathErrorKind};
73pub use location::Location;
74pub use matrix::{RotationMatrix3, Vector3};
75
76pub mod test_helpers;