Skip to main content

hpr_forensics/synthetic/
paired.rs

1//! Two recordings of one synthetic flight, and a logger in each stage of a staged one: the check
2//! of [`hpr_flightdata::timeline`]'s clock offset ([two recordings, in the plan for the readings][adr-280]).
3//!
4//! **What it is for.** A flight's truth says how each logger's clock stood against launch, so the
5//! offset two logs' liftoffs recover can be held to the true one. Each flight here carries two
6//! loggers, drawn independently from the ranges [`LoggerDraw::draw`] states, with their noise on
7//! streams of their own, each clock's zero moved by up to [`MAX_CLOCK_S`] either way, as a board's
8//! is by when it was switched on. The offset's bound must hold on every flight, and its 90%
9//! interval must pass [ADR-257][adr-257] ยง1's test on [`Set::PairA`] and [`Set::PairB`] with its
10//! shares fitted on [`Set::PairCalibration`], each on a seed of its own.
11//!
12//! **Stages** ([`Staged`]) fly `validation/designs/synthetic-two-stage-75mm-54mm.json`, handed in
13//! by the caller, as the designs are ([`super::designs`]), with a logger in each stage. The
14//! booster's truth after the split is HPR Sim's point-mass descent on the truth's grid, from the
15//! integrator's dense output (`docs/physics/staging.md`), so the check says how well two stages' liftoffs line their
16//! clocks up, not how well a booster's fall is modeled.
17//!
18//! **How far to trust it.** Two boards here share a flight and differ only in noise, rate and
19//! step. Real boards also sit at different stations, and may see the pad's shock differently; the
20//! one real pair checked, RocketPy's Prometheus, is on the guide's page.
21//!
22//! [adr-257]: https://github.com/nrdptel/fusionspace-eridanus/blob/main/docs/decisions/0257-the-2026-10-13-review-calibrated-intervals-and-the-post-flight-comparison.md
23//! [adr-280]: https://github.com/nrdptel/fusionspace-eridanus/blob/main/docs/decisions/0280-m7-2-in-seven-the-synthetic-flights-first.md
24
25use std::collections::BTreeMap;
26
27use hpr_flightdata::log::FlightLog;
28use hpr_flightdata::readings::interval::{self, Shares};
29use hpr_flightdata::readings::{self, Reading, Reason};
30use hpr_flightdata::timeline;
31use serde::{Deserialize, Serialize};
32
33use super::intervals::{Compared, Counts, Probe, Test};
34use super::logger::{self, LoggerDraw, Profile};
35use super::noise::between;
36use super::truth::{self, StagedTruth};
37use super::{Flyer, Key, Set, SyntheticError, draw, stream};
38
39/// The most a logger's clock zero is moved from where its log starts, s, either way: about five
40/// minutes on the pad, as a board switched on before the rocket went out to the rail is.
41pub const MAX_CLOCK_S: f64 = 300.0;
42/// What the second logger's noise streams add to the set's seed, so that two boards on one flight
43/// draw independent noise.
44const SECOND_LOGGER_STREAMS: u64 = 1_000_000;
45
46/// Two logs of one flight, each on its own clock.
47#[derive(Debug, Clone, PartialEq)]
48pub struct TwoLogs {
49    /// Its index in its set.
50    pub index: u64,
51    /// The first logger's profile.
52    pub first: Profile,
53    /// The second logger's profile.
54    pub second: Profile,
55    /// The first log.
56    pub first_log: FlightLog,
57    /// The second log.
58    pub second_log: FlightLog,
59    /// The second's clock less the first's at one instant, s: the truth an alignment recovers.
60    pub true_offset_s: f64,
61}
62
63/// `log` with `clock_s` added to every time it holds.
64pub fn on_clock(mut log: FlightLog, clock_s: f64) -> FlightLog {
65    for t in &mut log.time_s {
66        *t += clock_s;
67    }
68    for channel in &mut log.channels {
69        for t in &mut channel.time_s {
70            *t += clock_s;
71        }
72    }
73    for event in &mut log.events {
74        event.time_s += clock_s;
75    }
76    log
77}
78
79/// Flight `index`'s two clock moves, s.
80fn clocks(seed: u64, index: u64) -> (f64, f64) {
81    let mut rng = stream(seed, index, Key::Clocks);
82    let first = between(&mut rng, -MAX_CLOCK_S, MAX_CLOCK_S);
83    (first, between(&mut rng, -MAX_CLOCK_S, MAX_CLOCK_S))
84}
85
86/// A second logger for flight `index`: its draw, on a stream of its own.
87fn second_logger(seed: u64, index: u64) -> LoggerDraw {
88    let mut rng = stream(seed, index, Key::SecondLogger);
89    let profile = Profile::ALL
90        [((rng.uniform() * Profile::ALL.len() as f64) as usize).min(Profile::ALL.len() - 1)];
91    LoggerDraw::draw(&mut rng, profile)
92}
93
94/// Both logs of a flight whose first logger is `first`, on their clocks.
95fn logged(
96    set: Set,
97    index: u64,
98    (first, first_truth): (&LoggerDraw, &truth::Truth),
99    (second, second_truth): (&LoggerDraw, &truth::Truth),
100) -> Result<TwoLogs, SyntheticError> {
101    let seed = set.seed();
102    let (first_clock, second_clock) = clocks(seed, index);
103    let first_log = logger::log(first, first_truth, seed, index)?;
104    let second_log = logger::log(second, second_truth, seed + SECOND_LOGGER_STREAMS, index)?;
105    Ok(TwoLogs {
106        index,
107        first: first.profile,
108        second: second.profile,
109        first_log: on_clock(first_log, first_clock),
110        second_log: on_clock(second_log, second_clock),
111        // A log's time is since launch, plus its span on the pad, plus its clock's move.
112        true_offset_s: (second.pad_s + second_clock) - (first.pad_s + first_clock),
113    })
114}
115
116impl Flyer {
117    /// Flight `index` of `set`, with two loggers.
118    ///
119    /// # Errors
120    ///
121    /// As [`Flyer::flight`].
122    pub fn two_logs(&mut self, set: Set, index: u64) -> Result<TwoLogs, SyntheticError> {
123        let flight = self.flight(set, index)?;
124        let second = second_logger(set.seed(), index);
125        logged(
126            set,
127            index,
128            (&flight.draw.logger, &flight.truth),
129            (&second, &flight.truth),
130        )
131    }
132}
133
134/// The two-stage design's flights.
135#[derive(Debug, Clone)]
136pub struct Staged {
137    json: String,
138}
139
140impl Staged {
141    /// Flights of the two-stage design in `json`.
142    pub fn new(json: String) -> Self {
143        Self { json }
144    }
145
146    /// Flight `index` of [`Set::Staged`]: the truth of each stage, and two logs, the sustainer's
147    /// first and the booster's second. Its draw's design is unused.
148    ///
149    /// # Errors
150    ///
151    /// [`SyntheticError`] as [`truth::fly_staged`] and [`logger::log`].
152    pub fn flight(&self, index: u64) -> Result<(StagedTruth, TwoLogs), SyntheticError> {
153        let set = Set::Staged;
154        let drawn = draw(set, index);
155        let flown = truth::fly_staged(&drawn, &self.json)?;
156        let second = second_logger(set.seed(), index);
157        let logs = logged(
158            set,
159            index,
160            (&drawn.logger, &flown.sustainer),
161            (&second, &flown.booster),
162        )?;
163        Ok((flown, logs))
164    }
165}
166
167/// What a flight's two logs said of the clock offset.
168#[derive(Debug, Clone, PartialEq)]
169pub struct Said {
170    /// Its index in its set.
171    pub index: u64,
172    /// The two loggers' names, the alphabetically first first.
173    pub loggers: (&'static str, &'static str),
174    /// The offset against the truth, or why a log has no liftoff.
175    pub offset: Result<Compared, Reason>,
176}
177
178/// What `logs` say of the offset, by [`timeline`].
179pub fn said(logs: &TwoLogs) -> Said {
180    let (a, b) = (logs.first.name(), logs.second.name());
181    let loggers = if a <= b { (a, b) } else { (b, a) };
182    let first = timeline::place(&readings::read(&logs.first_log));
183    let second = timeline::place(&readings::read(&logs.second_log));
184    let offset = match (&first, &second) {
185        (Reading::Read(first), Reading::Read(second)) => {
186            let offset = timeline::offset(first, second);
187            match offset.interval_s {
188                Some(interval) => Ok(Compared {
189                    reading: offset.offset_s,
190                    bound: offset.bound_s,
191                    interval,
192                    truth: logs.true_offset_s,
193                }),
194                None => Err(Reason::BadRecord),
195            }
196        }
197        (Reading::Withheld(withheld), _) | (_, Reading::Withheld(withheld)) => Err(withheld.reason),
198    };
199    Said {
200        index: logs.index,
201        loggers,
202        offset,
203    }
204}
205
206/// How one pair of logger families' offsets did.
207#[derive(Debug, Clone, Copy, Default, PartialEq, Serialize, Deserialize)]
208pub struct PairCell {
209    /// Offsets given.
210    pub given: u64,
211    /// The largest error as a share of its bound.
212    pub largest_share: f64,
213}
214
215/// One set's check of the offset.
216#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
217pub struct Check {
218    /// Offsets given.
219    pub given: u64,
220    /// Those whose error stayed within the bound stated.
221    pub within_bound: u64,
222    /// The largest error as a share of its bound.
223    pub largest_share: f64,
224    /// The median error, s, its size.
225    pub median_error_s: f64,
226    /// The 90th percentile of its size, s.
227    pub p90_error_s: f64,
228    /// The largest error, s, its size.
229    pub largest_error_s: f64,
230    /// The median bound stated, s.
231    pub median_bound_s: f64,
232    /// The offsets withheld, by reason.
233    pub withheld: BTreeMap<Reason, u64>,
234    /// By pair of logger families.
235    pub by_loggers: BTreeMap<String, PairCell>,
236    /// The coverage test on the 90% interval.
237    pub test: Test,
238    /// The test on each probe's changed intervals.
239    pub probes: BTreeMap<Probe, Test>,
240}
241
242impl Check {
243    /// Whether every offset given stayed within its bound.
244    pub fn bound_holds(&self) -> bool {
245        self.given > 0 && self.within_bound == self.given
246    }
247}
248
249/// The `share`-th point of `sorted`, the nearest rank.
250fn point(sorted: &[f64], share: f64) -> f64 {
251    if sorted.is_empty() {
252        return f64::NAN;
253    }
254    let rank = (share * sorted.len() as f64).ceil() as usize;
255    sorted[rank.saturating_sub(1).min(sorted.len() - 1)]
256}
257
258/// The check of `flights`.
259pub fn check(flights: &[Said]) -> Check {
260    let mut withheld: BTreeMap<Reason, u64> = BTreeMap::new();
261    let mut by_loggers: BTreeMap<String, PairCell> = BTreeMap::new();
262    let mut counts = Counts::default();
263    let mut probes: BTreeMap<Probe, Counts> =
264        Probe::ALL.iter().map(|&p| (p, Counts::default())).collect();
265    let mut errors = Vec::new();
266    let mut bounds = Vec::new();
267    let (mut within_bound, mut largest_share) = (0, 0.0_f64);
268    for flight in flights {
269        match &flight.offset {
270            Err(reason) => *withheld.entry(*reason).or_default() += 1,
271            Ok(offset) => {
272                let error = (offset.reading - offset.truth).abs();
273                let share = error / offset.bound;
274                within_bound += u64::from(error <= offset.bound);
275                largest_share = largest_share.max(share);
276                errors.push(error);
277                bounds.push(offset.bound);
278                counts.add(offset.interval, offset.truth);
279                for (probe, probed) in &mut probes {
280                    probed.add(probe.apply(offset.interval), offset.truth);
281                }
282                let cell = by_loggers
283                    .entry(format!("{} + {}", flight.loggers.0, flight.loggers.1))
284                    .or_default();
285                cell.given += 1;
286                cell.largest_share = cell.largest_share.max(share);
287            }
288        }
289    }
290    errors.sort_by(f64::total_cmp);
291    bounds.sort_by(f64::total_cmp);
292    Check {
293        given: errors.len() as u64,
294        within_bound,
295        largest_share,
296        median_error_s: point(&errors, 0.5),
297        p90_error_s: point(&errors, 0.9),
298        largest_error_s: errors.last().copied().unwrap_or(f64::NAN),
299        median_bound_s: point(&bounds, 0.5),
300        withheld,
301        by_loggers,
302        test: Test::of(counts),
303        probes: probes
304            .into_iter()
305            .map(|(probe, counts)| (probe, Test::of(counts)))
306            .collect(),
307    }
308}
309
310/// The offset's shares fitted again on `flights`, which should be [`Set::PairCalibration`]'s.
311pub fn fitted(flights: &[Said]) -> Option<Shares> {
312    let shares: Vec<f64> = flights
313        .iter()
314        .filter_map(|flight| flight.offset.as_ref().ok().map(Compared::share))
315        .collect();
316    interval::fit(&shares)
317}
318
319#[cfg(test)]
320mod tests {
321    use super::super::designs::DesignFiles;
322    use super::*;
323
324    const TWO_STAGE: &str =
325        include_str!("../../../../validation/designs/synthetic-two-stage-75mm-54mm.json");
326
327    #[test]
328    fn moving_a_clock_moves_each_reading_by_as_much_and_changes_nothing_else() {
329        let mut flyer = Flyer::new(DesignFiles::committed());
330        for index in 0..6 {
331            let flight = flyer.flight(Set::PairA, index).unwrap();
332            let before = readings::read(&flight.log);
333            let after = readings::read(&on_clock(flight.log.clone(), 137.25));
334            let (Reading::Read(b), Reading::Read(a)) = (&before.liftoff, &after.liftoff) else {
335                assert_eq!(before.liftoff.reason(), after.liftoff.reason());
336                continue;
337            };
338            assert!(
339                (a.time_s - b.time_s - 137.25).abs() < 1e-9,
340                "flight {index}"
341            );
342            assert!((a.bound_s - b.bound_s).abs() < 1e-9, "flight {index}");
343        }
344    }
345
346    #[test]
347    fn the_true_offset_is_each_clock_less_the_other_and_the_flight_redraws_the_same() {
348        let mut flyer = Flyer::new(DesignFiles::committed());
349        let once = flyer.two_logs(Set::PairB, 4).unwrap();
350        let again = flyer.two_logs(Set::PairB, 4).unwrap();
351        assert_eq!(once, again);
352        let first = draw(Set::PairB, 4).logger;
353        let second = second_logger(Set::PairB.seed(), 4);
354        let (a, b) = clocks(Set::PairB.seed(), 4);
355        assert_eq!(once.true_offset_s, (second.pad_s + b) - (first.pad_s + a));
356        // The second board's noise is on streams of its own, not the first's.
357        let flight = flyer.flight(Set::PairB, 4).unwrap();
358        let seed = Set::PairB.seed();
359        let own = logger::log(&second, &flight.truth, seed + SECOND_LOGGER_STREAMS, 4).unwrap();
360        let shared = logger::log(&second, &flight.truth, seed, 4).unwrap();
361        assert_eq!(once.second_log, on_clock(own.clone(), b));
362        assert_ne!(own, shared);
363    }
364
365    #[test]
366    fn a_flight_says_its_offset_and_the_bound_holds_on_a_few() {
367        let mut flyer = Flyer::new(DesignFiles::committed());
368        let flights: Vec<Said> = (0..12)
369            .map(|k| said(&flyer.two_logs(Set::PairCalibration, k).unwrap()))
370            .collect();
371        let checked = check(&flights);
372        assert!(checked.given > 0, "{checked:?}");
373        assert!(checked.bound_holds(), "{checked:?}");
374    }
375
376    #[test]
377    fn an_offset_off_by_a_bound_and_a_bit_fails_the_bound() {
378        // The check can fail: a reading moved past its bound isn't counted as within.
379        let mut flyer = Flyer::new(DesignFiles::committed());
380        let mut flights: Vec<Said> = (0..12)
381            .map(|k| said(&flyer.two_logs(Set::PairCalibration, k).unwrap()))
382            .collect();
383        let offset = flights
384            .iter_mut()
385            .find_map(|f| f.offset.as_mut().ok())
386            .unwrap();
387        offset.reading = offset.truth + offset.bound * 1.01;
388        assert!(!check(&flights).bound_holds());
389    }
390
391    #[test]
392    fn the_staged_sets_draws_stay_inside_their_ranges_and_fly_hpr_sims_model() {
393        // 200 draws leave a gap at a range's end too often for the larger sets' test that each
394        // range fills: only that they stay inside. They come from the same `draw`.
395        for index in 0..Set::Staged.count() {
396            let d = draw(Set::Staged, index);
397            assert!((-15.0..=15.0).contains(&d.temperature_offset_k), "{d:?}");
398            assert!((0.0..=1_500.0).contains(&d.elevation_m), "{d:?}");
399            assert!(
400                (0.0..=crate::synthetic::MAX_WIND_M_S).contains(&d.wind_speed_m_s),
401                "{d:?}"
402            );
403            assert!((0.8..=1.2).contains(&d.drag_scale), "{d:?}");
404            assert!((0.94..=1.06).contains(&d.impulse_scale), "{d:?}");
405            assert!((0.90..=1.10).contains(&d.burn_time_scale), "{d:?}");
406            assert_eq!(d.model, crate::synthetic::Model::Same);
407        }
408    }
409
410    #[test]
411    fn a_staged_flight_parts_and_each_stage_has_its_own_truth_and_log() {
412        let staged = Staged::new(TWO_STAGE.to_owned());
413        let (truth, logs) = staged.flight(0).unwrap();
414        // The sustainer lights and goes higher; the booster falls alone from the split.
415        assert!(truth.separation_s > truth.booster.events.liftoff_s);
416        assert!(truth.sustainer.apogee_above_pad_m() > truth.booster.apogee_above_pad_m());
417        assert!(truth.booster.events.apogee_s > truth.separation_s);
418        assert_eq!(
419            truth.sustainer.events.liftoff_s,
420            truth.booster.events.liftoff_s
421        );
422        // Before the split the two truths are one stack; after it they part.
423        let before = truth.separation_s - 0.1;
424        assert_eq!(
425            truth.sustainer.at(before).unwrap().height_m,
426            truth.booster.at(before).unwrap().height_m
427        );
428        let after = truth.booster.events.apogee_s;
429        assert!(
430            (truth.sustainer.at(after).unwrap().height_m
431                - truth.booster.at(after).unwrap().height_m)
432                .abs()
433                > 1.0
434        );
435        // Its fall is the integrator's path on the truth's grid, not a few events' chords: from the
436        // split to the ground, each height is the last plus the speeds' mean over the time between,
437        // and the speed's rate is the specific force less gravity, away from the split's step.
438        let fall: Vec<_> = truth
439            .booster
440            .samples
441            .iter()
442            .filter(|s| s.time_s >= truth.separation_s)
443            .collect();
444        let span = truth.booster.events.landing_s - truth.separation_s;
445        assert!(
446            fall.len() as f64 > 0.9 * span / truth::TRUTH_STEP_S,
447            "{}",
448            fall.len()
449        );
450        for pair in fall.windows(2) {
451            let dt = pair[1].time_s - pair[0].time_s;
452            assert!(
453                dt <= truth::TRUTH_STEP_S * 1.5,
454                "{dt} s at {}",
455                pair[0].time_s
456            );
457            let by_speed = 0.5 * (pair[0].vertical_speed_m_s + pair[1].vertical_speed_m_s) * dt;
458            assert!(
459                (pair[1].height_m - pair[0].height_m - by_speed).abs() < 0.01,
460                "at {}: {pair:?}",
461                pair[0].time_s
462            );
463        }
464        // Well into the tumble it falls near its terminal speed: the force on it near its weight.
465        let settled = fall[fall.len() - 10];
466        assert!(
467            (settled.axial_specific_force_m_s2 - 9.8).abs() < 0.5,
468            "{settled:?}"
469        );
470        // The booster reaches the ground where its truth says.
471        let landing = truth.booster.at(truth.booster.events.landing_s).unwrap();
472        assert!(landing.height_m.abs() < 1.0, "{landing:?}");
473        let offset = said(&logs).offset.unwrap();
474        assert!(
475            (offset.reading - offset.truth).abs() <= offset.bound,
476            "{offset:?}"
477        );
478    }
479}