pleiades_eclipse/lib.rs
1//! Global geocentric solar and lunar eclipse computation for the `pleiades`
2//! workspace, derived entirely from pleiades' validated Sun and Moon positions.
3//!
4//! ## Scope
5//!
6//! - **Window:** 1900-01-01 (JD 2 415 020.5 TDB) through 2100-01-01
7//! (JD 2 488 069.5 TDB), bounded by the packaged ephemeris data. Four
8//! NASA-canon eclipses falling in mid/late 2100 are uncomputable with the
9//! packaged data and are excluded.
10//! - **Coverage:** global / geocentric only. No per-observer local circumstances.
11//! - **Outputs per eclipse:** type, instant of greatest eclipse, magnitude,
12//! gamma, Saros series, eclipsed longitude (apparent tropical ecliptic of
13//! date; no ayanamsa), and (solar only) geographic location of greatest
14//! eclipse. Lunar eclipses have no greatest-eclipse location.
15//! - **Validation:** the fail-closed `validate-eclipses` gate recomputes every
16//! in-window NASA-canon eclipse and compares against ≤ 60 s (time),
17//! ≤ 0.01 (magnitude), exact type, exact Saros, and ≤ 1.0″ (eclipsed
18//! longitude). Of the 909 in-window NASA-canon rows, 908 pass all five
19//! tolerances; one documented knife-edge eclipse (1948-05-09, Saros 137,
20//! annular vs hybrid at magnitude ≈ 1.0) is allowlisted for the exact-type
21//! check only (its four other tolerances are still verified).
22//!
23//! ## Example
24//!
25//! ```rust
26//! use pleiades_data::packaged_backend;
27//! use pleiades_eclipse::{EclipseEngine, EclipseFilter};
28//! use pleiades_types::{Instant, JulianDay, TimeScale};
29//!
30//! let engine = EclipseEngine::new(packaged_backend());
31//! let after = Instant::new(JulianDay::from_days(2_451_545.0), TimeScale::Tdb);
32//! let next = engine.next_eclipse(after, EclipseFilter::All).unwrap();
33//! assert!(next.is_some());
34//! ```
35#![forbid(unsafe_code)]
36#![deny(missing_docs)]
37
38mod engine;
39mod ephemeris;
40mod error;
41mod geometry;
42mod saros;
43mod syzygy;
44mod types;
45
46pub use engine::EclipseEngine;
47pub use error::{EclipseError, WINDOW_END_JD, WINDOW_START_JD};
48pub use types::{
49 Eclipse, EclipseFilter, EclipseKind, EclipseType, GeoLocation, LunarEclipseType, Node,
50 SolarEclipseType,
51};