1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
//! The public eclipse search engine.
use crate::ephemeris::{apparent_sun_longitude_deg, sample_sun_moon};
use crate::error::{EclipseError, WINDOW_END_JD, WINDOW_START_JD};
use crate::geometry::{classify_lunar, classify_solar, sub_shadow_point};
use crate::saros::saros_series;
use crate::syzygy::{find_syzygies, Syzygy, STEP_DAYS};
use crate::types::{Eclipse, EclipseFilter, EclipseKind, EclipseType, Node};
use pleiades_backend::EphemerisBackend;
use pleiades_types::{Instant, JulianDay, Longitude, TimeScale};
/// Searches for global/geocentric eclipses over a chosen [`EphemerisBackend`].
///
/// Backed by the packaged data, results are valid only within the
/// 1900-01-01..2100-01-01 window (see [`crate`]); out-of-window requests fail
/// closed with [`EclipseError::OutOfWindow`].
pub struct EclipseEngine<B> {
backend: B,
}
impl<B: EphemerisBackend> EclipseEngine<B> {
/// Creates an engine that draws Sun/Moon positions from `backend`.
pub fn new(backend: B) -> Self {
Self { backend }
}
/// Returns every eclipse admitted by `filter` with greatest eclipse in
/// `[start, end]`, in chronological order. Fails closed if either bound is
/// outside the supported window.
pub fn eclipses_in_range(
&self,
start: Instant,
end: Instant,
filter: EclipseFilter,
) -> Result<Vec<Eclipse>, EclipseError> {
let start_jd = start.julian_day.days();
let end_jd = end.julian_day.days();
self.check_window(start_jd)?;
self.check_window(end_jd)?;
// The syzygy scanner (`find_one`) probes one STEP_DAYS past its
// requested end for sign-change detection, and `sample_sun_moon` issues a
// light-time-retarded Sun query ~0.006 days before the nominal epoch.
// Together these mean:
// - At the END: the scanner queries up to `scan_end + STEP_DAYS`; the
// packaged backend has no data beyond WINDOW_END_JD, so we clamp
// `scan_end` to `WINDOW_END_JD - STEP_DAYS`.
// - At the START: the retarded query falls `~light_time` before the
// first sample; clamping `scan_start` to `WINDOW_START_JD + STEP_DAYS`
// (> max light time ~0.006 d) keeps every retarded lookup within coverage.
// Both clamps are safe: no corpus eclipse falls within 0.5 d of either bound.
let scan_start = start_jd.max(WINDOW_START_JD + STEP_DAYS);
let scan_end = end_jd.min(WINDOW_END_JD - STEP_DAYS);
let mut out = Vec::new();
for event in find_syzygies(&self.backend, scan_start, scan_end)? {
if let Some(eclipse) = self.build(event.syzygy, event.julian_day)? {
if filter.admits(eclipse.kind) {
out.push(eclipse);
}
}
}
Ok(out)
}
/// Returns the first eclipse admitted by `filter` whose greatest eclipse is
/// strictly after `after`, or `None` if none remains before the window end.
pub fn next_eclipse(
&self,
after: Instant,
filter: EclipseFilter,
) -> Result<Option<Eclipse>, EclipseError> {
let after_jd = after.julian_day.days();
// `eclipses_in_range` clamps the scan end to WINDOW_END_JD - STEP_DAYS,
// so passing WINDOW_END_JD directly is safe and correct.
let end = Instant::new(JulianDay::from_days(WINDOW_END_JD), TimeScale::Tdb);
Ok(self
.eclipses_in_range(after, end, filter)?
.into_iter()
.find(|e| e.greatest_eclipse.julian_day.days() > after_jd))
}
/// Returns the last eclipse admitted by `filter` whose greatest eclipse is
/// strictly before `before`, or `None` if none exists after the window start.
pub fn previous_eclipse(
&self,
before: Instant,
filter: EclipseFilter,
) -> Result<Option<Eclipse>, EclipseError> {
let before_jd = before.julian_day.days();
let start = Instant::new(JulianDay::from_days(WINDOW_START_JD), TimeScale::Tdb);
Ok(self
.eclipses_in_range(start, before, filter)?
.into_iter()
.rev()
.find(|e| e.greatest_eclipse.julian_day.days() < before_jd))
}
fn check_window(&self, jd: f64) -> Result<(), EclipseError> {
if !(WINDOW_START_JD..=WINDOW_END_JD).contains(&jd) {
Err(EclipseError::OutOfWindow { julian_day: jd })
} else {
Ok(())
}
}
fn build(&self, syzygy: Syzygy, syzygy_jd: f64) -> Result<Option<Eclipse>, EclipseError> {
let greatest_jd = self.refine_greatest(syzygy, syzygy_jd)?;
let sample = sample_sun_moon(&self.backend, greatest_jd)?;
let greatest_eclipse = Instant::new(JulianDay::from_days(greatest_jd), TimeScale::Tdb);
// Compute the apparent geocentric solar longitude of date for eclipsed_longitude.
// Geometric sampling (separation, classification) uses the Mean frame — that is
// correct and unchanged. But eclipsed_longitude must be apparent-of-date per the
// spec (Task 10 gate: ≤1 arcsecond); mean would be ~20–25″ off.
let apparent_sun_lon = apparent_sun_longitude_deg(&self.backend, greatest_jd)?;
let eclipsed_longitude = match syzygy {
Syzygy::NewMoon => Longitude::from_degrees(apparent_sun_lon),
// For lunar eclipses the eclipsed body is the Moon, which is opposite the Sun;
// eclipsed_longitude is the apparent solar longitude + 180° (corpus MANIFEST).
Syzygy::FullMoon => Longitude::from_degrees(apparent_sun_lon + 180.0),
};
// Node: ascending (North) if the Moon's latitude is increasing through 0.
let later = sample_sun_moon(&self.backend, greatest_jd + 0.01)?;
let near_node = if later.moon_latitude_deg >= sample.moon_latitude_deg {
Node::North
} else {
Node::South
};
let eclipse = match syzygy {
Syzygy::NewMoon => {
let Some(c) = classify_solar(&sample) else {
return Ok(None);
};
Eclipse {
kind: EclipseKind::Solar,
eclipse_type: EclipseType::Solar(c.eclipse_type),
greatest_eclipse,
magnitude: c.magnitude,
gamma: c.gamma,
saros_series: saros_series(EclipseKind::Solar, greatest_jd),
eclipsed_longitude,
near_node,
greatest_eclipse_location: Some(sub_shadow_point(&sample, greatest_jd)),
}
}
Syzygy::FullMoon => {
let Some(c) = classify_lunar(&sample) else {
return Ok(None);
};
Eclipse {
kind: EclipseKind::Lunar,
eclipse_type: EclipseType::Lunar(c.eclipse_type),
greatest_eclipse,
magnitude: c.magnitude,
gamma: c.gamma,
saros_series: saros_series(EclipseKind::Lunar, greatest_jd),
eclipsed_longitude,
near_node,
greatest_eclipse_location: None,
}
}
};
Ok(Some(eclipse))
}
/// Golden-section minimize the Sun–Moon (or Moon–antisolar) separation in a
/// ±0.25-day bracket around the syzygy to find greatest eclipse.
fn refine_greatest(&self, syzygy: Syzygy, syzygy_jd: f64) -> Result<f64, EclipseError> {
use crate::geometry::separation_for;
let phi = 0.618_033_988_75_f64;
let (mut a, mut b) = (syzygy_jd - 0.25, syzygy_jd + 0.25);
let mut c = b - (b - a) * phi;
let mut d = a + (b - a) * phi;
let mut fc = separation_for(syzygy, &sample_sun_moon(&self.backend, c)?);
let mut fd = separation_for(syzygy, &sample_sun_moon(&self.backend, d)?);
while (b - a) > 0.5 / 86_400.0 {
if fc < fd {
b = d;
d = c;
fd = fc;
c = b - (b - a) * phi;
fc = separation_for(syzygy, &sample_sun_moon(&self.backend, c)?);
} else {
a = c;
c = d;
fc = fd;
d = a + (b - a) * phi;
fd = separation_for(syzygy, &sample_sun_moon(&self.backend, d)?);
}
}
Ok(0.5 * (a + b))
}
}
#[cfg(test)]
mod tests {
use super::*;
use pleiades_backend::test_backend::LinearSunMoon;
use pleiades_types::{Instant, JulianDay, TimeScale};
fn at(jd: f64) -> Instant {
Instant::new(JulianDay::from_days(jd), TimeScale::Tdb)
}
#[test]
fn out_of_window_start_fails_closed() {
let engine = EclipseEngine::new(LinearSunMoon::new_moon_at(2_451_550.0));
let err = engine
.eclipses_in_range(at(2_400_000.0), at(2_451_551.0), EclipseFilter::All)
.unwrap_err();
assert!(matches!(err, EclipseError::OutOfWindow { .. }));
}
#[test]
fn filter_excludes_lunar() {
// The on-node analytic backend yields a solar eclipse at every new moon
// and a lunar one at every full moon; SolarOnly must drop the lunar ones.
let engine =
EclipseEngine::new(LinearSunMoon::new_moon_at(2_451_550.0).with_moon_latitude(0.0));
let solar = engine
.eclipses_in_range(at(2_451_549.0), at(2_451_551.0), EclipseFilter::SolarOnly)
.unwrap();
assert!(solar.iter().all(|e| e.kind == EclipseKind::Solar));
}
}