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, plus per-observer local circumstances
11//! (contact times, magnitude/obscuration, az/alt, visibility) via
12//! [`EclipseEngine::local_circumstances`] and `next/previous_local_eclipse`.
13//! - **Outputs per eclipse:** type, instant of greatest eclipse, magnitude,
14//! gamma, Saros series, eclipsed longitude (apparent tropical ecliptic of
15//! date; no ayanamsa), and (solar only) geographic location of greatest
16//! eclipse. Lunar eclipses have no greatest-eclipse location.
17//! - **Validation:** the fail-closed `validate-eclipses` gate recomputes every
18//! in-window NASA-canon eclipse and compares against ≤ 60 s (time),
19//! ≤ 0.01 (magnitude), exact type, exact Saros, and ≤ 1.0″ (eclipsed
20//! longitude). Of the 909 in-window NASA-canon rows, 908 pass all five
21//! tolerances; one documented knife-edge eclipse (1948-05-09, Saros 137,
22//! annular vs hybrid at magnitude ≈ 1.0) is allowlisted for the exact-type
23//! check only (its four other tolerances are still verified).
24//!
25//! ## Example
26//!
27//! ```rust
28//! use pleiades_data::packaged_backend;
29//! use pleiades_eclipse::{EclipseEngine, EclipseFilter};
30//! use pleiades_types::{Instant, JulianDay, TimeScale};
31//!
32//! let engine = EclipseEngine::new(packaged_backend());
33//! let after = Instant::new(JulianDay::from_days(2_451_545.0), TimeScale::Tdb);
34//! let next = engine.next_eclipse(after, EclipseFilter::All).unwrap();
35//! assert!(next.is_some());
36//! ```
37#![forbid(unsafe_code)]
38#![deny(missing_docs)]
39
40mod engine;
41mod ephemeris;
42mod error;
43mod geometry;
44mod local;
45mod saros;
46mod syzygy;
47mod types;
48
49pub use engine::EclipseEngine;
50pub use error::{EclipseError, WINDOW_END_JD, WINDOW_START_JD};
51pub use local::{
52 LocalCircumstances, LocalContact, LocalLunarCircumstances, LocalSolarCircumstances,
53};
54pub use types::{
55 Eclipse, EclipseFilter, EclipseKind, EclipseType, GeoLocation, LunarEclipseType, Node,
56 SolarEclipseType,
57};