pub const SPEED_OF_LIGHT: f64 = 299_792_458.0;
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Transit {
pub delay: f64,
pub emit: f64,
pub receive: f64,
}
impl Transit {
#[must_use]
pub fn path(&self) -> f64 {
SPEED_OF_LIGHT * self.delay
}
}
fn distance(a: [f64; 3], b: [f64; 3]) -> f64 {
let d = [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
libm::sqrt(d[0] * d[0] + d[1] * d[1] + d[2] * d[2])
}
pub fn down_leg<E>(
receive: f64,
receiver: [f64; 3],
emitter: E,
tolerance: f64,
max_iterations: usize,
) -> Option<Transit>
where
E: Fn(f64) -> Option<[f64; 3]>,
{
let mut delay = 0.0;
let mut source = emitter(receive)?;
for _ in 0..max_iterations {
let next = distance(source, receiver) / SPEED_OF_LIGHT;
source = emitter(receive - next)?;
let step = libm::fabs(next - delay);
delay = next;
if step < tolerance {
return Some(Transit {
delay,
emit: receive - delay,
receive,
});
}
}
None
}
#[cfg(test)]
mod tests {
#![allow(clippy::expect_used)]
use spacelab_testkit::assert_within_ulps;
use super::*;
const EARTH_RADIUS: f64 = 6_378_137.0;
const LEO: f64 = EARTH_RADIUS + 500_000.0;
#[test]
fn the_separation_is_the_euclidean_norm_in_all_three_components() {
assert_within_ulps(
distance([10.0, 20.0, 30.0], [11.0, 22.0, 32.0]),
3.0,
0,
"the (1, 2, 2) quadruple",
);
assert_within_ulps(
distance([-4.0, 13.0, -8.0], [-8.0, 1.0, -5.0]),
13.0,
0,
"the (4, 12, 3) quadruple through the origin",
);
let (p, q) = ([1.0, -5.0, 7.0], [-2.0, 3.0, -4.0]);
assert_within_ulps(distance(p, q), distance(q, p), 0, "the swapped pair");
}
#[test]
fn a_frozen_emitter_returns_the_geometric_distance() {
let t = 1234.5;
let receiver = [EARTH_RADIUS, 0.0, 0.0];
let transit = down_leg(t, receiver, |_| Some([LEO, 0.0, 0.0]), 1e-15, 20)
.expect("a frozen geometry converges");
assert_within_ulps(transit.delay, 500_000.0 / SPEED_OF_LIGHT, 1, "the delay");
assert_within_ulps(transit.path(), 500_000.0, 2, "the path length");
assert_within_ulps(transit.receive, t, 0, "the reception epoch");
assert_within_ulps(transit.emit, t - transit.delay, 0, "the emission epoch");
}
#[test]
fn the_emitter_is_taken_before_reception_and_not_after() {
let speed = 7_600.0;
let receiver = [EARTH_RADIUS, 0.0, 0.0];
let receding = |t: f64| Some([LEO + speed * t, 0.0, 0.0]);
let transit = down_leg(0.0, receiver, receding, 1e-18, 20).expect("converges");
let instantaneous = LEO - EARTH_RADIUS;
assert!(
transit.path() < instantaneous,
"a receding source gave a path {} m longer than the instantaneous separation",
transit.path() - instantaneous
);
let expected = speed * transit.delay;
let observed = instantaneous - transit.path();
assert!(
libm::fabs(observed - expected) < 1e-6,
"{observed} m of shortening against the {expected} m the recession implies"
);
}
#[test]
fn the_solution_satisfies_the_light_time_equation() {
let receiver = [EARTH_RADIUS * 0.6, EARTH_RADIUS * 0.5, EARTH_RADIUS * 0.6];
let orbiting = |t: f64| Some([LEO - 1_000.0 * t, 7_500.0 * t, 2_000.0 * t]);
let transit = down_leg(0.0, receiver, orbiting, 1e-18, 30).expect("converges");
let residual = transit.delay
- distance(orbiting(transit.emit).expect("in range"), receiver) / SPEED_OF_LIGHT;
assert!(
libm::fabs(residual) < 1e-18,
"{residual} s of residual in the light-time equation"
);
}
#[test]
fn a_step_that_only_equals_the_tolerance_is_not_convergence() {
let receiver = [EARTH_RADIUS, 0.0, 0.0];
let source = |_: f64| Some([LEO, 0.0, 0.0]);
let first_step = (LEO - EARTH_RADIUS) / SPEED_OF_LIGHT;
assert!(
down_leg(0.0, receiver, source, first_step, 1).is_none(),
"a step that only equals the tolerance was taken as convergence"
);
down_leg(0.0, receiver, source, first_step, 2).expect("converges on the second pass");
}
#[test]
fn a_gap_behind_the_reception_epoch_is_reported_rather_than_extrapolated() {
let receiver = [EARTH_RADIUS, 0.0, 0.0];
let starts_at_zero = |t: f64| (t >= 0.0).then_some([LEO, 0.0, 0.0]);
assert!(down_leg(0.0, receiver, starts_at_zero, 1e-15, 20).is_none());
let after = 2.0 * (LEO - EARTH_RADIUS) / SPEED_OF_LIGHT;
down_leg(after, receiver, starts_at_zero, 1e-15, 20).expect("the gap is behind us");
}
#[test]
fn a_non_convergent_ephemeris_terminates() {
let receiver = [EARTH_RADIUS, 0.0, 0.0];
let calls = core::cell::Cell::new(0_u32);
let jumpy = |_: f64| {
calls.set(calls.get() + 1);
let jump = if calls.get().is_multiple_of(2) {
0.0
} else {
1e7
};
Some([LEO + jump, 0.0, 0.0])
};
assert!(down_leg(0.0, receiver, jumpy, 1e-18, 8).is_none());
assert!(
calls.get() <= 9,
"{} evaluations is past the cap",
calls.get()
);
}
#[test]
fn an_exhausted_budget_never_returns_the_starting_guess() {
let receiver = [EARTH_RADIUS, 0.0, 0.0];
assert!(down_leg(0.0, receiver, |_| Some([LEO, 0.0, 0.0]), 1e-15, 0).is_none());
}
}