astro_math/lib.rs
1//! # Astro Math
2//!
3//! Astronomy library for Rust implementing algorithms from Jean Meeus and ERFA.
4//! Built for telescope control, observation planning, and celestial mechanics.
5//!
6//! ## Core Capabilities
7//!
8//! This library provides everything needed for astronomical calculations:
9//!
10//! ### Time Systems
11//! - [`time`] — Julian Date conversions, J2000 epoch calculations
12//! - [`time_scales`] — UTC ↔ TT conversions with proper leap second handling
13//! - [`sidereal`] — Greenwich Mean Sidereal Time (GMST), Local Mean/Apparent Sidereal Time
14//!
15//! ### Observer Location
16//! - [`location`] — Earth coordinates with flexible parsing (27+ formats)
17//! - Support for decimal degrees, DMS, HMS, aviation formats, Unicode symbols
18//!
19//! ### Coordinate Transformations
20//! - [`transforms`] — RA/Dec ↔ Alt/Az conversions with spherical trigonometry
21//! - [`galactic`] — Equatorial ↔ Galactic coordinate system conversions
22//! - [`projection`] — Gnomonic/TAN projection for astrometry and plate solving
23//!
24//! ### Precision Corrections
25//! - [`precession`] — Convert coordinates between epochs (J2000 ↔ current date)
26//! - [`nutation`] — Earth's axis wobble corrections (±18.6" longitude, ±9.2" obliquity)
27//! - [`aberration`] — Annual stellar aberration corrections (±20.5 arcseconds)
28//! - [`proper_motion`] — Linear and rigorous 3D space motion calculations
29//! - [`parallax`] — Diurnal and annual parallax corrections
30//!
31//! ### Solar System Objects
32//! - [`moon`] — Lunar position, phase, illumination, distance calculations
33//! - [`sun`] — Solar position and rise/set calculations
34//! - [`rise_set`] — Rise, set, and meridian transit times for any object
35//!
36//! ### Atmospheric Effects
37//! - [`refraction`] — Multiple atmospheric refraction models (Bennett, Saemundsson, radio)
38//! - [`airmass`] — Various airmass formulas for extinction calculations
39//!
40//! ### High Performance
41//! - Parallel batch processing with Rayon for coordinate transformations
42//! - ERFA (Essential Routines for Fundamental Astronomy) integration
43//! - Input validation and clear error messages
44//!
45//! ## Architecture Overview
46//!
47//! The library is structured around these core concepts:
48//!
49//! ```text
50//! ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
51//! │ Observer │ │ Celestial │ │ Corrections │
52//! │ Location │───▶│ Coordinates │───▶│ & Effects │
53//! │ │ │ │ │ │
54//! └─────────────────┘ └──────────────────┘ └─────────────────┘
55//! ```
56//!
57//! ### 1. Observer Location ([`Location`])
58//! Earth-based observer coordinates with flexible coordinate parsing supporting
59//! 27+ formats (decimal degrees, DMS, HMS, aviation, Unicode symbols).
60//! Handles local sidereal time calculations and coordinate validation.
61//!
62//! ### 2. Time Systems ([`time`], [`time_scales`], [`sidereal`])
63//! - Julian Date conversions and J2000 epoch calculations
64//! - UTC ↔ TT conversions with proper leap second handling
65//! - Greenwich Mean Sidereal Time (GMST) and Local Sidereal Time (LST)
66//!
67//! ### 3. Coordinate Systems ([`transforms`], [`galactic`], [`projection`])
68//! - RA/Dec ↔ Alt/Az transformations using spherical trigonometry
69//! - Equatorial ↔ Galactic coordinate system conversions
70//! - Gnomonic/TAN projection for astrometry and plate solving
71//!
72//! ### 4. Astrometric Corrections
73//! - [`precession`] — Convert coordinates between epochs (J2000 ↔ current date)
74//! - [`nutation`] — Earth's axis wobble (±18.6" longitude, ±9.2" obliquity)
75//! - [`aberration`] — Annual stellar aberration (±20.5 arcseconds)
76//! - [`proper_motion`] — Linear and rigorous 3D space motion calculations
77//! - [`parallax`] — Diurnal and annual parallax corrections
78//! - [`refraction`] — Atmospheric refraction (Bennett, Saemundsson, radio models)
79//!
80//! ### 5. Solar System Objects ([`sun`], [`moon`], [`rise_set`])
81//! - Solar and lunar position calculations
82//! - Rise, set, and meridian transit times for any celestial object
83//! - Moon phase, illumination, and distance calculations
84//!
85//! ## Accuracy & Standards
86//!
87//! This library implements algorithms from:
88//! - **Jean Meeus**: *Astronomical Algorithms* (2nd edition)
89//! - **IAU SOFA**: Standards of Fundamental Astronomy
90//! - **ERFA**: Essential Routines for Fundamental Astronomy
91//! - **USNO**: US Naval Observatory references
92//!
93//! ## Quick Example: Compute LST and Alt/Az for Vega
94//!
95//! ```
96//! use chrono::{Utc, TimeZone};
97//! use astro_math::{julian_date, Location, ra_dec_to_alt_az};
98//!
99//! let dt = Utc.with_ymd_and_hms(2024, 8, 4, 6, 0, 0).unwrap();
100//! let loc = Location {
101//! latitude_deg: 31.9583,
102//! longitude_deg: -111.6,
103//! altitude_m: 2120.0,
104//! };
105//!
106//! let jd = julian_date(dt);
107//! let lst = loc.local_sidereal_time(dt);
108//! let (alt, az) = ra_dec_to_alt_az(279.23473479, 38.78368896, dt, &loc).unwrap();
109//!
110//! println!("JD: {:.5}", jd);
111//! println!("LST: {:.5} h", lst);
112//! println!("Vega Alt: {:.3}°, Az: {:.3}°", alt, az);
113//! ```
114//!
115//! This computes the Julian Date, sidereal time, and sky position of Vega
116//! from Kitt Peak at 06:00 UTC on August 4, 2024.
117//!
118//! You can verify this output against Astropy using:
119//!
120//! ```python
121//! from astropy.coordinates import SkyCoord, EarthLocation, AltAz
122//! from astropy.time import Time
123//! import astropy.units as u
124//!
125//! time = Time("2024-08-04T06:00:00", location=EarthLocation(lat=31.9583*u.deg, lon=-111.6*u.deg, height=2120*u.m))
126//! coord = SkyCoord(ra=279.23473479*u.deg, dec=38.78368896*u.deg)
127//! altaz = coord.transform_to(AltAz(obstime=time, location=time.location))
128//! print(altaz.alt.deg, altaz.az.deg)
129//! ```
130
131pub mod aberration;
132pub mod airmass;
133pub mod erfa;
134pub mod error;
135pub mod galactic;
136pub mod location;
137pub mod moon;
138pub mod nutation;
139pub mod parallax;
140pub mod precession;
141pub mod projection;
142pub mod proper_motion;
143pub mod refraction;
144pub mod rise_set;
145pub mod sidereal;
146pub mod sun;
147pub mod time;
148pub mod time_scales;
149pub mod transforms;
150
151pub use aberration::*;
152pub use airmass::*;
153pub use error::{AstroError, Result};
154pub use galactic::*;
155pub use location::*;
156pub use moon::*;
157pub use parallax::*;
158pub use precession::*;
159pub use projection::*;
160pub use proper_motion::*;
161pub use refraction::*;
162pub use rise_set::*;
163pub use sidereal::*;
164pub use time::*;
165pub use time_scales::*;
166pub use transforms::*;
167
168#[cfg(test)]
169pub mod tests;