Skip to main content

hpr_validate/
census.rs

1//! The accuracy census: the numbers the committed reports hold hpr to, counted once, classed by
2//! what they were compared with and how fast the flight went, and held to the census last
3//! accepted.
4//!
5//! The reports say how each case came out. The census says what they add up to, and it is the
6//! gate against a regression that a regenerated report would otherwise carry in unnoticed. Four
7//! reports feed it:
8//!
9//! - the harness's (`validation/reports/latest.json`): every metric of every case, and each known
10//!   gap;
11//! - the real flights' (`real-flights.json`): each flight's apogee and the RMS of its climb;
12//! - OpenRocket's flights of its examples and of the private designs (`openrocket-flights.json`,
13//!   `openrocket-library-flights.json`): apogee, largest speed, stability margin, mass at launch
14//!   and at rod clearance, and center of mass there, and each configuration hpr doesn't fly.
15//!
16//! Each becomes a [`Row`], keyed by its report's [`Group`], its case and its metric, and a key seen
17//! twice is refused, so a case counts once ([Loft lesson L84][l84]).
18//!
19//! The census accepted last is committed (`validation/reports/census.json`). A run is held to it
20//! ([`compare`]): a row that moves by more than its slack in either direction, that changes its
21//! standing (a miss that starts passing too, [L85][l85]), or that comes or goes, a group whose
22//! reference changes, or a changed slack, is a [`Change`], and any change fails the check until the
23//! census is accepted again with a written reason. A predicted-mode row, whose 3% is only a target
24//! ([ADR-023][adr-023], predicted mode), is held the same way, so hpr's own aerodynamics can't
25//! drift unnoticed inside its target ([L88][l88]). Each group's headline names what it was
26//! compared with, the kind of comparison, how many flights and their speeds ([L86][l86]).
27//!
28//! A row's slack is [`SLACK_SHARE`] of its scale: the tolerance it is held to, or for a row held
29//! to none, the bar its kind is judged by. It is never less than the harness's own reproduction
30//! bound, [`reproduction_bound`].
31//!
32//! [l84]: https://hpr.fusionspace.co/decisions-and-roadmap.html#l84
33//! [l85]: https://hpr.fusionspace.co/decisions-and-roadmap.html#l85
34//! [l86]: https://hpr.fusionspace.co/decisions-and-roadmap.html#l86
35//! [l88]: https://hpr.fusionspace.co/decisions-and-roadmap.html#l88
36//! [adr-023]: https://github.com/nrdptel/fusionspace-eridanus/blob/main/docs/DECISIONS.md#adr-023-predicted-mode-each-codes-own-drag-reported-against-a-target-2026-09-18
37
38use std::collections::{BTreeMap, BTreeSet};
39use std::fmt::Write as _;
40
41use serde::{Deserialize, Serialize};
42use serde_json::Value;
43
44use crate::real_flight::{APOGEE_TARGET_PERCENT, RealFlightReport};
45use crate::report::{Report, Verdict};
46
47/// The share of a row's scale it may move by before the census calls it a change: 0.1%.
48///
49/// On a 3% tolerance that is 3e-5 of the reference. The committed reports are regenerated on one
50/// machine and compared as files, so the noise that matters is a regeneration's: within
51/// [`reproduction_bound`] for the harness, and at most 5e-7 per cent on an OpenRocket corpus rerun.
52pub const SLACK_SHARE: f64 = 1e-3;
53
54/// How far a harness value may move between runs and platforms and still reproduce: `2e-6` or
55/// `1e-7` of the value, whichever is larger (`Report::reproduces`). A harness row's slack is never
56/// less than this.
57#[must_use]
58pub fn reproduction_bound(value: f64) -> f64 {
59    2e-6_f64.max(1e-7 * value.abs())
60}
61
62/// The scale of a harness row held to no tolerance: 3% of its reference, the bound
63/// [M2.1][m2-1] set on each metric and that no committed gate or target exceeds
64/// (`tests::no_committed_gate_is_looser_than_the_milestone_says`).
65///
66/// [m2-1]: https://hpr.fusionspace.co/decisions-and-roadmap.html#m2-1
67pub const NOT_SCORED_SCALE: f64 = 0.03;
68
69/// The bar an OpenRocket apogee or largest speed is judged by, per cent: the apogee difference
70/// that needs a written cause ([ADR-070][adr-070], the corpus's rules), and the bar the staging
71/// milestone set on both ([M1.9c][m1-9c]).
72///
73/// [m1-9c]: https://hpr.fusionspace.co/decisions-and-roadmap.html#m1-9c
74/// [adr-070]: https://github.com/nrdptel/fusionspace-eridanus/blob/main/docs/DECISIONS.md#adr-070-m22e-split-mass-and-centre-of-mass-first-then-the-corpus-2026-09-25
75pub const OPENROCKET_BAR_PERCENT: f64 = 5.0;
76
77/// The bar an OpenRocket mass difference is judged by, per cent: the 1% the mass comparison was
78/// measured against when it began ([M2.2a][m2-2a]).
79///
80/// [m2-2a]: https://hpr.fusionspace.co/decisions-and-roadmap.html#m2-2a
81pub const MASS_BAR_PERCENT: f64 = 1.0;
82
83/// The bar a stability margin or a center of mass is judged by, calibers. It was 0.5, the
84/// center-of-pressure target set before the transonic normal force was measured ([M1.8a][m1-8a]);
85/// [ADR-220][adr-220] tightened it to 0.2 when every difference but one public margin (−1.08,
86/// over either bar) measured within 0.111 calibers, about half the new bar, in both corpora. A
87/// difference in either moves the margin by as many calibers.
88///
89/// [m1-8a]: https://hpr.fusionspace.co/decisions-and-roadmap.html#m1-8a
90/// [adr-220]: https://github.com/nrdptel/fusionspace-eridanus/blob/main/docs/DECISIONS.md#adr-220-the-margin-bar-tightened-to-02-calibres-m114-held-to-release-03s-target-2026-10-09
91pub const MARGIN_BAR_CAL: f64 = 0.2;
92
93/// The bar a real flight's climb is judged by, per cent of its apogee: the bound the harness holds
94/// a whole flight's height series to ([ADR-024][adr-024], the series RMS).
95///
96/// [adr-024]: https://github.com/nrdptel/fusionspace-eridanus/blob/main/docs/DECISIONS.md#adr-024-the-time-series-rms-aligned-at-ignition-held-to-3-of-its-traces-scale-2026-09-18
97pub const TRACE_BAR_PERCENT: f64 = 3.0;
98
99/// The largest Mach number of a subsonic flight, as the OpenRocket library report classes them.
100pub const SUBSONIC_BELOW: f64 = 0.8;
101/// The largest Mach number of a transonic flight; past it a flight is supersonic.
102pub const SUPERSONIC_ABOVE: f64 = 1.2;
103
104/// Which report a row comes from, and so what it was compared with.
105#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
106#[serde(rename_all = "snake_case")]
107#[non_exhaustive]
108pub enum Group {
109    /// The harness's descents under a parachute against RocketPy, on the same inputs: gated.
110    Descent,
111    /// The harness's whole flights against RocketPy on the same drag: gated.
112    SameDrag,
113    /// The harness's whole flights, each code on its own drag: a target, not a gate.
114    Predicted,
115    /// OpenRocket's calm flights of its own examples.
116    OpenRocketExamples,
117    /// OpenRocket's calm flights of the private designs, under anonymized ids.
118    OpenRocketLibrary,
119    /// Real flights: the public flights' altimeter logs.
120    FlightLogs,
121}
122
123impl Group {
124    /// Every group, in the census's order.
125    pub const ALL: [Self; 6] = [
126        Self::Descent,
127        Self::SameDrag,
128        Self::Predicted,
129        Self::OpenRocketExamples,
130        Self::OpenRocketLibrary,
131        Self::FlightLogs,
132    ];
133
134    /// What was flown, in a few words.
135    #[must_use]
136    pub const fn what(self) -> &'static str {
137        match self {
138            Self::Descent => "descents under a parachute",
139            Self::SameDrag => "whole flights on the same drag",
140            Self::Predicted => "whole flights, each code on its own drag",
141            Self::OpenRocketExamples => "calm flights of OpenRocket's examples",
142            Self::OpenRocketLibrary => "calm flights of the private designs",
143            Self::FlightLogs => "real flights",
144        }
145    }
146
147    /// The kind of evidence: another program's answer or a measurement.
148    #[must_use]
149    pub const fn kind(self) -> &'static str {
150        match self {
151            Self::Descent | Self::SameDrag => "code-to-code, same inputs",
152            Self::Predicted => "code-to-code, each code's own drag",
153            Self::OpenRocketExamples | Self::OpenRocketLibrary => {
154                "code-to-code, each code's own model"
155            }
156            Self::FlightLogs => "measured",
157        }
158    }
159
160    /// What its numbers are held to in their own report. A gate fails the run, a target is
161    /// reported and not enforced, and where there is neither, a bar marks a difference that needs
162    /// a written cause. The census holds every number to where it was, whatever this says.
163    #[must_use]
164    pub const fn bar(self) -> &'static str {
165        match self {
166            Self::Descent => "gate: each metric's tolerance, 0.1% to 3%",
167            Self::SameDrag => "gate: each metric's tolerance, 0.05% to 3%",
168            Self::Predicted => {
169                "target: each metric's tolerance, 0.1% to 3%, reported, not enforced"
170            }
171            Self::OpenRocketExamples | Self::OpenRocketLibrary => {
172                "no target; an apogee more than 5% off needs a written cause"
173            }
174            Self::FlightLogs => "target: mean absolute apogee error 5%",
175        }
176    }
177
178    /// The noun for its cases.
179    const fn noun(self, count: usize) -> &'static str {
180        match (self, count) {
181            (Self::Descent, 1) => "descent",
182            (Self::Descent, _) => "descents",
183            (_, 1) => "flight",
184            _ => "flights",
185        }
186    }
187
188    const fn report(self) -> &'static str {
189        match self {
190            Self::Descent | Self::SameDrag | Self::Predicted => HARNESS,
191            Self::FlightLogs => REAL,
192            Self::OpenRocketExamples => EXAMPLES,
193            Self::OpenRocketLibrary => LIBRARY,
194        }
195    }
196}
197
198/// How fast a case flew: the class of its largest Mach number.
199#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
200#[serde(rename_all = "snake_case")]
201#[non_exhaustive]
202pub enum Regime {
203    /// A descent under a parachute, slow by construction.
204    Descent,
205    /// Below Mach [`SUBSONIC_BELOW`].
206    Subsonic,
207    /// From Mach [`SUBSONIC_BELOW`] to [`SUPERSONIC_ABOVE`].
208    Transonic,
209    /// Above Mach [`SUPERSONIC_ABOVE`].
210    Supersonic,
211    /// Not known: a flight hpr doesn't fly, or one its report gives no Mach number for.
212    Unknown,
213}
214
215impl Regime {
216    /// The class of a flight whose largest Mach number is `mach`; [`Regime::Unknown`] for a
217    /// number that isn't finite.
218    #[must_use]
219    pub fn of_mach(mach: f64) -> Self {
220        if !mach.is_finite() {
221            Self::Unknown
222        } else if mach < SUBSONIC_BELOW {
223            Self::Subsonic
224        } else if mach <= SUPERSONIC_ABOVE {
225            Self::Transonic
226        } else {
227            Self::Supersonic
228        }
229    }
230
231    /// Its name, as the census writes it.
232    #[must_use]
233    pub const fn name(self) -> &'static str {
234        match self {
235            Self::Descent => "under a parachute",
236            Self::Subsonic => "subsonic",
237            Self::Transonic => "transonic",
238            Self::Supersonic => "supersonic",
239            Self::Unknown => "of unknown speed",
240        }
241    }
242}
243
244/// Where a row stands against what it is held to.
245#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
246#[serde(rename_all = "snake_case")]
247#[non_exhaustive]
248pub enum Standing {
249    /// Inside its gate.
250    Pass,
251    /// Outside its gate.
252    Fail,
253    /// Inside its target.
254    WithinTarget,
255    /// Outside its target.
256    OutsideTarget,
257    /// Measured and held to nothing, for a written reason.
258    NotScored,
259    /// Inside the bar its kind is judged by, where there is no gate or target.
260    WithinBar,
261    /// Over that bar.
262    OverBar,
263    /// Not compared: the report withholds it, and says why.
264    Withheld,
265    /// A known gap: a harness flight hpr refuses, compared with nothing.
266    Gap,
267    /// A configuration an OpenRocket report lists and hpr doesn't fly, with the report's reason.
268    NotFlown,
269}
270
271impl Standing {
272    /// Its name, as the census writes it.
273    #[must_use]
274    pub const fn name(self) -> &'static str {
275        match self {
276            Self::Pass => "pass",
277            Self::Fail => "fail",
278            Self::WithinTarget => "within target",
279            Self::OutsideTarget => "outside target",
280            Self::NotScored => "not scored",
281            Self::WithinBar => "within the bar",
282            Self::OverBar => "over the bar",
283            Self::Withheld => "withheld",
284            Self::Gap => "known gap",
285            Self::NotFlown => "not flown",
286        }
287    }
288
289    /// Whether it stands for a case hpr doesn't fly, rather than a compared number.
290    const fn unflown(self) -> bool {
291        matches!(self, Self::Gap | Self::NotFlown)
292    }
293
294    /// How good it is, higher better, for telling a fall from a rise.
295    const fn rank(self) -> u8 {
296        match self {
297            Self::Fail => 0,
298            Self::Gap | Self::NotFlown => 1,
299            Self::Withheld | Self::NotScored => 2,
300            Self::OutsideTarget | Self::OverBar => 3,
301            Self::WithinTarget | Self::WithinBar => 4,
302            Self::Pass => 5,
303        }
304    }
305}
306
307/// The unit a row's difference is in.
308#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
309#[serde(rename_all = "snake_case")]
310#[non_exhaustive]
311pub enum Unit {
312    /// The metric's own unit, as its name says (`_m`, `_s`, `_m_s`, or none for a Mach number).
313    Metric,
314    /// Per cent of the reference.
315    Percent,
316    /// Calibers. Censuses accepted before October 11, 2026 wrote the key `calibre`, which still
317    /// reads.
318    #[serde(alias = "calibre")]
319    Caliber,
320}
321
322impl Unit {
323    const fn suffix(self) -> &'static str {
324        match self {
325            Self::Metric => "",
326            Self::Percent => "%",
327            Self::Caliber => " cal",
328        }
329    }
330}
331
332/// One compared number, or one case that isn't flown.
333#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
334pub struct Row {
335    /// The report it comes from.
336    pub group: Group,
337    /// The case: a harness case id, an OpenRocket design and configuration, an anonymized id, or
338    /// a real flight's id.
339    pub case: String,
340    /// The metric; empty for a case that isn't flown.
341    pub metric: String,
342    /// hpr less the reference, in [`Row::unit`]; for a climb, the RMS itself.
343    pub difference: f64,
344    /// The difference as a percentage of the reference, where it is one.
345    #[serde(default, skip_serializing_if = "Option::is_none")]
346    pub percent: Option<f64>,
347    /// The unit of the difference, the scale and the slack.
348    pub unit: Unit,
349    /// What the difference is measured against: the row's tolerance, or its kind's bar.
350    pub scale: f64,
351    /// How far the difference may move before the census calls it a change.
352    pub slack: f64,
353    /// Where it stands.
354    pub standing: Standing,
355    /// How fast its case flew.
356    pub regime: Regime,
357}
358
359impl Row {
360    fn key(&self) -> (Group, &str, &str) {
361        (self.group, &self.case, &self.metric)
362    }
363
364    /// Its difference as a share of its scale; not a number for a row with no scale.
365    #[must_use]
366    pub fn share(&self) -> f64 {
367        if self.scale > 0.0 {
368            self.difference.abs() / self.scale
369        } else {
370            f64::NAN
371        }
372    }
373
374    fn describe(&self) -> String {
375        format!(
376            "{}: {} {}",
377            self.group.what(),
378            self.case,
379            if self.metric.is_empty() {
380                "(the case)"
381            } else {
382                &self.metric
383            }
384        )
385    }
386
387    /// A row that isn't a compared number: a case that isn't flown.
388    fn unflown(group: Group, case: String, standing: Standing, regime: Regime) -> Self {
389        Self {
390            group,
391            case,
392            metric: String::new(),
393            difference: 0.0,
394            percent: None,
395            unit: Unit::Metric,
396            scale: 0.0,
397            slack: 0.0,
398            standing,
399            regime,
400        }
401    }
402}
403
404/// What the census counts: every row, and what each group was compared with.
405#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
406pub struct Census {
407    /// [`SLACK_SHARE`] when it was taken.
408    pub slack_share: f64,
409    /// Each group's reference, as its report names it (a program and its version, or the logs).
410    pub references: BTreeMap<Group, String>,
411    /// Every row, sorted by group, case and metric.
412    pub rows: Vec<Row>,
413}
414
415/// Why a census could not be taken.
416#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
417#[non_exhaustive]
418pub enum CensusError {
419    /// A report said something the census can't read.
420    #[error("{report}: {what}")]
421    Report {
422        /// The report.
423        report: &'static str,
424        /// What is wrong.
425        what: String,
426    },
427    /// A row's key came twice: a case would count twice.
428    #[error("{report}: {case} {metric} is compared twice; a case counts once (L84)")]
429    Duplicate {
430        /// The report.
431        report: &'static str,
432        /// The case.
433        case: String,
434        /// The metric.
435        metric: String,
436    },
437}
438
439/// The reports the census reads, as parsed from their committed files.
440#[derive(Debug, Clone, Copy)]
441pub struct Reports<'a> {
442    /// `validation/reports/latest.json`.
443    pub harness: &'a Report,
444    /// `validation/reports/real-flights.json`.
445    pub real_flights: &'a RealFlightReport,
446    /// `validation/reports/openrocket-flights.json`.
447    pub openrocket_examples: &'a Value,
448    /// `validation/reports/openrocket-library-flights.json`.
449    pub openrocket_library: &'a Value,
450}
451
452const HARNESS: &str = "latest.json";
453const REAL: &str = "real-flights.json";
454const EXAMPLES: &str = "openrocket-flights.json";
455const LIBRARY: &str = "openrocket-library-flights.json";
456
457impl Census {
458    /// Takes the census of `reports`.
459    ///
460    /// # Errors
461    ///
462    /// [`CensusError::Duplicate`] when a case's metric comes twice, and [`CensusError::Report`]
463    /// when a report is partial or holds something the census has no class for.
464    pub fn take(reports: Reports<'_>) -> Result<Self, CensusError> {
465        let mut rows = Vec::new();
466        let mut references = BTreeMap::new();
467        harness_rows(reports.harness, &mut rows, &mut references)?;
468        real_flight_rows(reports.real_flights, &mut rows, &mut references);
469        openrocket_example_rows(reports.openrocket_examples, &mut rows, &mut references)?;
470        openrocket_library_rows(reports.openrocket_library, &mut rows, &mut references)?;
471        let mut seen = BTreeSet::new();
472        for row in &rows {
473            if !seen.insert(row.key()) {
474                return Err(CensusError::Duplicate {
475                    report: row.group.report(),
476                    case: row.case.clone(),
477                    metric: row.metric.clone(),
478                });
479            }
480        }
481        let unflown: BTreeSet<(Group, &str)> = rows
482            .iter()
483            .filter(|row| row.standing.unflown())
484            .map(|row| (row.group, row.case.as_str()))
485            .collect();
486        if let Some(row) = rows.iter().find(|row| {
487            !row.standing.unflown() && unflown.contains(&(row.group, row.case.as_str()))
488        }) {
489            return Err(CensusError::Report {
490                report: row.group.report(),
491                what: format!("{} is both compared and not compared", row.case),
492            });
493        }
494        rows.sort_by(|a, b| a.key().cmp(&b.key()));
495        Ok(Self {
496            slack_share: SLACK_SHARE,
497            references,
498            rows,
499        })
500    }
501
502    /// What each group adds up to, in [`Group::ALL`]'s order, leaving out a group with no rows.
503    #[must_use]
504    pub fn summaries(&self) -> Vec<Summary> {
505        Group::ALL
506            .into_iter()
507            .filter_map(|group| Summary::of(self, group))
508            .collect()
509    }
510}
511
512pub(crate) fn harness_group(case: &str) -> Result<Group, CensusError> {
513    if case.starts_with("descent-") {
514        Ok(Group::Descent)
515    } else if case.starts_with("flight-") {
516        Ok(Group::SameDrag)
517    } else if case.starts_with("predicted-") {
518        Ok(Group::Predicted)
519    } else {
520        Err(CensusError::Report {
521            report: HARNESS,
522            what: format!(
523                "case {case} is neither a descent, a same-drag flight nor a predicted one, by its id"
524            ),
525        })
526    }
527}
528
529fn harness_rows(
530    report: &Report,
531    rows: &mut Vec<Row>,
532    references: &mut BTreeMap<Group, String>,
533) -> Result<(), CensusError> {
534    if report.fast || !report.skipped.is_empty() {
535        return Err(CensusError::Report {
536            report: HARNESS,
537            what: "a partial run: the census counts the whole suite".to_owned(),
538        });
539    }
540    let mut oracles: BTreeMap<Group, BTreeSet<&str>> = BTreeMap::new();
541    for source in &report.sources {
542        oracles
543            .entry(harness_group(&source.case)?)
544            .or_default()
545            .insert(&source.oracle);
546    }
547    for (group, names) in oracles {
548        references.insert(group, names.into_iter().collect::<Vec<_>>().join("; "));
549    }
550    let regime = |case: &str| -> Result<Regime, CensusError> {
551        if harness_group(case)? == Group::Descent {
552            return Ok(Regime::Descent);
553        }
554        if let Some(gap) = report.gaps.iter().find(|gap| gap.case == case) {
555            return Ok(Regime::of_mach(gap.mach));
556        }
557        report
558            .comparisons
559            .iter()
560            .find(|row| row.case == case && row.metric == "max_mach")
561            .map(|row| Regime::of_mach(row.reference))
562            .ok_or_else(|| CensusError::Report {
563                report: HARNESS,
564                what: format!("case {case} has no max_mach row to class its speed by"),
565            })
566    };
567    for comparison in &report.comparisons {
568        let scale = if comparison.tolerance.is_set() {
569            comparison.tolerance.allowed(comparison.reference)
570        } else {
571            NOT_SCORED_SCALE * comparison.reference.abs()
572        };
573        rows.push(Row {
574            group: harness_group(&comparison.case)?,
575            case: comparison.case.clone(),
576            metric: comparison.metric.clone(),
577            difference: comparison.difference,
578            percent: comparison.relative.map(|relative| 100.0 * relative),
579            unit: Unit::Metric,
580            scale,
581            slack: (SLACK_SHARE * scale).max(reproduction_bound(comparison.reference)),
582            standing: match comparison.verdict {
583                Verdict::Pass => Standing::Pass,
584                Verdict::Fail => Standing::Fail,
585                Verdict::NotScored => Standing::NotScored,
586                Verdict::WithinTarget => Standing::WithinTarget,
587                Verdict::OutsideTarget => Standing::OutsideTarget,
588            },
589            regime: regime(&comparison.case)?,
590        });
591    }
592    for gap in &report.gaps {
593        rows.push(Row::unflown(
594            harness_group(&gap.case)?,
595            gap.case.clone(),
596            Standing::Gap,
597            Regime::of_mach(gap.mach),
598        ));
599    }
600    Ok(())
601}
602
603/// A row judged by a bar: within it or over it, by the difference's magnitude; withheld where the
604/// report gives no difference.
605fn barred(
606    group: Group,
607    case: &str,
608    metric: &str,
609    difference: Option<f64>,
610    (unit, scale): (Unit, f64),
611    regime: Regime,
612) -> Row {
613    let (difference, standing) = match difference.filter(|value| value.is_finite()) {
614        Some(value) if value.abs() <= scale => (value, Standing::WithinBar),
615        Some(value) => (value, Standing::OverBar),
616        None => (0.0, Standing::Withheld),
617    };
618    Row {
619        group,
620        case: case.to_owned(),
621        metric: metric.to_owned(),
622        difference,
623        percent: (unit == Unit::Percent && standing != Standing::Withheld).then_some(difference),
624        unit,
625        scale,
626        slack: SLACK_SHARE * scale,
627        standing,
628        regime,
629    }
630}
631
632fn real_flight_rows(
633    report: &RealFlightReport,
634    rows: &mut Vec<Row>,
635    references: &mut BTreeMap<Group, String>,
636) {
637    references.insert(
638        Group::FlightLogs,
639        "the public flights' altimeter logs".to_owned(),
640    );
641    for flight in &report.flights {
642        let regime = Regime::of_mach(flight.hpr_max_mach);
643        // The 5% target is on the mean; one flight's apogee is judged by it as a bar.
644        rows.push(barred(
645            Group::FlightLogs,
646            &flight.id,
647            "apogee",
648            Some(flight.apogee_error_percent),
649            (Unit::Percent, APOGEE_TARGET_PERCENT),
650            regime,
651        ));
652        rows.push(barred(
653            Group::FlightLogs,
654            &flight.id,
655            "climb",
656            Some(flight.trace_rms_percent),
657            (Unit::Percent, TRACE_BAR_PERCENT),
658            regime,
659        ));
660    }
661    // The flights predicted first are compared at their apogee only: no climb row.
662    for flight in &report.predicted_first {
663        rows.push(barred(
664            Group::FlightLogs,
665            &flight.id,
666            "apogee",
667            Some(flight.apogee_error_percent),
668            (Unit::Percent, APOGEE_TARGET_PERCENT),
669            Regime::of_mach(flight.hpr_max_mach),
670        ));
671    }
672}
673
674fn openrocket_reference(report: &Value, name: &'static str) -> Result<String, CensusError> {
675    match (
676        report["reference"]["tool"].as_str(),
677        report["reference"]["version"].as_str(),
678    ) {
679        (Some(tool), Some(version)) => Ok(format!("{tool} {version}")),
680        _ => Err(CensusError::Report {
681            report: name,
682            what: "no reference tool and version".to_owned(),
683        }),
684    }
685}
686
687fn array<'a>(
688    report: &'a Value,
689    key: &str,
690    name: &'static str,
691) -> Result<&'a Vec<Value>, CensusError> {
692    report[key].as_array().ok_or_else(|| CensusError::Report {
693        report: name,
694        what: format!("no `{key}` list"),
695    })
696}
697
698/// A difference an OpenRocket report scored, or `None` where it withheld it.
699fn scored(
700    outcome: Option<&str>,
701    value: Option<f64>,
702    case: &str,
703    metric: &str,
704    name: &'static str,
705) -> Result<Option<f64>, CensusError> {
706    match (outcome, value) {
707        (Some("scored"), Some(value)) if value.is_finite() => Ok(Some(value)),
708        (Some("scored"), _) => Err(CensusError::Report {
709            report: name,
710            what: format!("{case} {metric} is scored with no finite difference"),
711        }),
712        (Some(_), _) => Ok(None),
713        (None, _) => Err(CensusError::Report {
714            report: name,
715            what: format!("{case} {metric} has no outcome"),
716        }),
717    }
718}
719
720/// A mass or center-of-mass difference: `None` only for an aborted flight, which the reports
721/// withhold them from. An absent or null value on a flight that ran is a partial report.
722fn measured(
723    value: Option<f64>,
724    flight: &Value,
725    case: &str,
726    metric: &str,
727    name: &'static str,
728) -> Result<Option<f64>, CensusError> {
729    let aborted = flight["aborted"]
730        .as_bool()
731        .ok_or_else(|| CensusError::Report {
732            report: name,
733            what: format!("{case} doesn't say whether it was aborted"),
734        })?;
735    match value.filter(|value| value.is_finite()) {
736        Some(value) => Ok(Some(value)),
737        None if aborted => Ok(None),
738        None => Err(CensusError::Report {
739            report: name,
740            what: format!("{case} {metric} is missing from a flight that ran"),
741        }),
742    }
743}
744
745/// Per cent of `openrocket`'s by which `hpr` differs, as `cargo xtask ork-flights` computes it.
746fn percent_of(hpr: &Value, openrocket: &Value) -> Option<f64> {
747    hpr.as_f64()
748        .zip(openrocket.as_f64())
749        .map(|(h, o)| 100.0 * (h - o) / o)
750        .filter(|p| p.is_finite())
751}
752
753const APOGEE_BAR: (Unit, f64) = (Unit::Percent, OPENROCKET_BAR_PERCENT);
754const MASS_BAR: (Unit, f64) = (Unit::Percent, MASS_BAR_PERCENT);
755const CALIBER_BAR: (Unit, f64) = (Unit::Caliber, MARGIN_BAR_CAL);
756
757fn openrocket_example_rows(
758    report: &Value,
759    rows: &mut Vec<Row>,
760    references: &mut BTreeMap<Group, String>,
761) -> Result<(), CensusError> {
762    let group = Group::OpenRocketExamples;
763    references.insert(group, openrocket_reference(report, EXAMPLES)?);
764    let case_of = |flight: &Value| -> Result<String, CensusError> {
765        match (flight["design"].as_str(), flight["configuration"].as_str()) {
766            (Some(design), Some(configuration)) => Ok(format!("{design} / {configuration}")),
767            _ => Err(CensusError::Report {
768                report: EXAMPLES,
769                what: "a flight has no design or configuration".to_owned(),
770            }),
771        }
772    };
773    for flight in array(report, "flights", EXAMPLES)? {
774        let case = case_of(flight)?;
775        let regime = Regime::of_mach(flight["max_mach_openrocket"].as_f64().unwrap_or(f64::NAN));
776        let metrics = &flight["metrics"];
777        for key in metrics.as_object().into_iter().flat_map(|map| map.keys()) {
778            if !matches!(
779                key.as_str(),
780                "apogee_m" | "max_speed_m_s" | "rod_clearance_margin_cal"
781            ) {
782                return Err(CensusError::Report {
783                    report: EXAMPLES,
784                    what: format!("{case}: the census has no bar for the metric {key}"),
785                });
786            }
787        }
788        for (key, metric, field, bar) in [
789            ("apogee_m", "apogee", "relative_percent", APOGEE_BAR),
790            ("max_speed_m_s", "max_speed", "relative_percent", APOGEE_BAR),
791            (
792                "rod_clearance_margin_cal",
793                "margin",
794                "difference",
795                CALIBER_BAR,
796            ),
797        ] {
798            let entry = &metrics[key];
799            let value = scored(
800                entry["outcome"]["outcome"].as_str(),
801                entry[field].as_f64(),
802                &case,
803                metric,
804                EXAMPLES,
805            )?;
806            rows.push(barred(group, &case, metric, value, bar, regime));
807        }
808        let at = &flight["at_rod_clearance"];
809        let (hpr, openrocket) = (&at["hpr"], &at["openrocket"]);
810        let cg = hpr["cg_from_nose_m"]
811            .as_f64()
812            .zip(openrocket["cg_from_nose_m"].as_f64())
813            .zip(openrocket["reference_length_m"].as_f64())
814            .map(|((h, o), reference)| (h - o) / reference)
815            .filter(|cal| cal.is_finite());
816        let launch = &flight["launch_mass_kg"];
817        for (metric, value, bar) in [
818            (
819                "launch_mass",
820                percent_of(&launch["hpr"], &launch["openrocket"]),
821                MASS_BAR,
822            ),
823            (
824                "rod_clearance_mass",
825                percent_of(&hpr["mass_kg"], &openrocket["mass_kg"]),
826                MASS_BAR,
827            ),
828            ("rod_clearance_cg", cg, CALIBER_BAR),
829        ] {
830            let value = measured(value, flight, &case, metric, EXAMPLES)?;
831            rows.push(barred(group, &case, metric, value, bar, regime));
832        }
833    }
834    for flight in array(report, "not_flown", EXAMPLES)? {
835        rows.push(Row::unflown(
836            group,
837            case_of(flight)?,
838            Standing::NotFlown,
839            Regime::Unknown,
840        ));
841    }
842    Ok(())
843}
844
845fn openrocket_library_rows(
846    report: &Value,
847    rows: &mut Vec<Row>,
848    references: &mut BTreeMap<Group, String>,
849) -> Result<(), CensusError> {
850    let group = Group::OpenRocketLibrary;
851    references.insert(group, openrocket_reference(report, LIBRARY)?);
852    let case_of = |flight: &Value| -> Result<String, CensusError> {
853        flight["flight"]
854            .as_str()
855            .map(str::to_owned)
856            .ok_or_else(|| CensusError::Report {
857                report: LIBRARY,
858                what: "a flight has no id".to_owned(),
859            })
860    };
861    for flight in array(report, "flights", LIBRARY)? {
862        let case = case_of(flight)?;
863        let regime = match flight["mach"].as_str() {
864            Some("subsonic") => Regime::Subsonic,
865            Some("transonic") => Regime::Transonic,
866            Some("supersonic") => Regime::Supersonic,
867            Some("unknown") => Regime::Unknown,
868            other => {
869                return Err(CensusError::Report {
870                    report: LIBRARY,
871                    what: format!("{case}: no Mach class the census knows ({other:?})"),
872                });
873            }
874        };
875        for (metric, field, outcome, bar) in [
876            ("apogee", "apogee_percent", "apogee_outcome", APOGEE_BAR),
877            (
878                "max_speed",
879                "max_speed_percent",
880                "max_speed_outcome",
881                APOGEE_BAR,
882            ),
883            ("margin", "margin_cal", "margin_outcome", CALIBER_BAR),
884        ] {
885            let value = scored(
886                flight[outcome].as_str(),
887                flight[field].as_f64(),
888                &case,
889                metric,
890                LIBRARY,
891            )?;
892            rows.push(barred(group, &case, metric, value, bar, regime));
893        }
894        for (metric, field, bar) in [
895            ("launch_mass", "launch_mass_percent", MASS_BAR),
896            ("rod_clearance_mass", "rod_clearance_mass_percent", MASS_BAR),
897            ("rod_clearance_cg", "rod_clearance_cg_cal", CALIBER_BAR),
898        ] {
899            let value = measured(flight[field].as_f64(), flight, &case, metric, LIBRARY)?;
900            rows.push(barred(group, &case, metric, value, bar, regime));
901        }
902    }
903    for flight in array(report, "not_flown", LIBRARY)? {
904        rows.push(Row::unflown(
905            group,
906            case_of(flight)?,
907            Standing::NotFlown,
908            Regime::Unknown,
909        ));
910    }
911    Ok(())
912}
913
914/// A spread of per-cent differences: the least, the largest and the mean magnitude.
915#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
916pub struct Spread {
917    /// How many.
918    pub count: usize,
919    /// The least.
920    pub min: f64,
921    /// The largest.
922    pub max: f64,
923    /// The mean of their magnitudes.
924    pub mean_absolute: f64,
925    /// How many are within the scale they are judged by.
926    pub within: usize,
927}
928
929impl Spread {
930    fn of(rows: &[&Row]) -> Option<Self> {
931        let values: Vec<(f64, bool)> = rows
932            .iter()
933            .filter_map(|row| {
934                row.percent
935                    .map(|percent| (percent, row.difference.abs() <= row.scale))
936            })
937            .collect();
938        if values.is_empty() {
939            return None;
940        }
941        #[allow(
942            clippy::cast_precision_loss,
943            reason = "a count of rows, far below 2^52"
944        )]
945        let count = values.len() as f64;
946        Some(Self {
947            count: values.len(),
948            min: values.iter().map(|v| v.0).fold(f64::INFINITY, f64::min),
949            max: values.iter().map(|v| v.0).fold(f64::NEG_INFINITY, f64::max),
950            mean_absolute: values.iter().map(|v| v.0.abs()).sum::<f64>() / count,
951            within: values.iter().filter(|v| v.1).count(),
952        })
953    }
954}
955
956/// How many of one metric's numbers are within the bar they are judged by.
957#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
958pub struct BarCount {
959    /// The metric.
960    pub metric: String,
961    /// Its bar.
962    pub scale: f64,
963    /// The bar's unit.
964    pub unit: Unit,
965    /// How many are within it.
966    pub within: usize,
967    /// How many were compared.
968    pub compared: usize,
969}
970
971/// The metrics judged by a bar, in the order the census reads them out, with their names and
972/// what their bar is a share of, where that isn't the reference's own value.
973const BARRED: [(&str, &str, &str); 7] = [
974    ("apogee", "apogee", ""),
975    ("max_speed", "largest speed", ""),
976    ("margin", "margin", ""),
977    ("launch_mass", "launch mass", ""),
978    ("rod_clearance_mass", "mass at rod clearance", ""),
979    ("rod_clearance_cg", "center of mass at rod clearance", ""),
980    ("climb", "climb's RMS height error", " of apogee"),
981];
982
983/// What one group adds up to.
984#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
985pub struct Summary {
986    /// The group.
987    pub group: Group,
988    /// What it was compared with.
989    pub reference: String,
990    /// Its cases compared, or refused as known gaps: flights, or descents.
991    pub cases: usize,
992    /// Its cases the report lists as not flown.
993    pub not_flown: usize,
994    /// Its cases by speed, not-flown ones left out.
995    pub regimes: BTreeMap<Regime, usize>,
996    /// Its rows.
997    pub rows: usize,
998    /// Its rows by standing.
999    pub standings: BTreeMap<Standing, usize>,
1000    /// Each metric judged by a bar, in the census's order.
1001    pub bars: Vec<BarCount>,
1002    /// The apogee differences, per cent: the harness's relative to RocketPy's, OpenRocket's and the
1003    /// logs' as their reports give them. `None` for descents.
1004    pub apogee_percent: Option<Spread>,
1005}
1006
1007impl Summary {
1008    fn of(census: &Census, group: Group) -> Option<Self> {
1009        let rows: Vec<&Row> = census
1010            .rows
1011            .iter()
1012            .filter(|row| row.group == group)
1013            .collect();
1014        if rows.is_empty() {
1015            return None;
1016        }
1017        let mut cases: BTreeMap<&str, Regime> = BTreeMap::new();
1018        let mut not_flown = BTreeSet::new();
1019        let mut standings = BTreeMap::new();
1020        for row in &rows {
1021            if row.standing == Standing::NotFlown {
1022                not_flown.insert(row.case.as_str());
1023            } else {
1024                cases.insert(&row.case, row.regime);
1025            }
1026            *standings.entry(row.standing).or_insert(0) += 1;
1027        }
1028        let mut regimes = BTreeMap::new();
1029        for regime in cases.values() {
1030            *regimes.entry(*regime).or_insert(0) += 1;
1031        }
1032        let bars = BARRED
1033            .iter()
1034            .filter_map(|(metric, ..)| {
1035                let judged: Vec<&Row> = rows
1036                    .iter()
1037                    .copied()
1038                    .filter(|row| {
1039                        row.metric == *metric
1040                            && matches!(row.standing, Standing::WithinBar | Standing::OverBar)
1041                    })
1042                    .collect();
1043                let first = judged.first()?;
1044                Some(BarCount {
1045                    metric: (*metric).to_owned(),
1046                    scale: first.scale,
1047                    unit: first.unit,
1048                    within: judged
1049                        .iter()
1050                        .filter(|row| row.standing == Standing::WithinBar)
1051                        .count(),
1052                    compared: judged.len(),
1053                })
1054            })
1055            .collect();
1056        let apogees: Vec<&Row> = rows
1057            .iter()
1058            .copied()
1059            .filter(|row| matches!(row.metric.as_str(), "apogee" | "apogee_agl_m"))
1060            .collect();
1061        Some(Self {
1062            group,
1063            reference: census.references.get(&group).cloned().unwrap_or_default(),
1064            cases: cases.len(),
1065            not_flown: not_flown.len(),
1066            regimes,
1067            rows: rows.len(),
1068            standings,
1069            bars,
1070            apogee_percent: Spread::of(&apogees),
1071        })
1072    }
1073
1074    fn count(&self, standing: Standing) -> usize {
1075        self.standings.get(&standing).copied().unwrap_or(0)
1076    }
1077
1078    /// Its cases by speed, in words: "7 subsonic, 1 transonic". Descents are left out: their noun
1079    /// already says it.
1080    #[must_use]
1081    pub fn regimes_in_words(&self) -> String {
1082        self.regimes
1083            .iter()
1084            .filter(|(regime, _)| **regime != Regime::Descent)
1085            .map(|(regime, count)| format!("{count} {}", regime.name()))
1086            .collect::<Vec<_>>()
1087            .join(", ")
1088    }
1089
1090    /// Its population in words: "33 flights (32 subsonic, 1 transonic); 24 more not flown".
1091    #[must_use]
1092    pub fn population(&self) -> String {
1093        let mut out = format!("{} {}", self.cases, self.group.noun(self.cases));
1094        let regimes = self.regimes_in_words();
1095        if !regimes.is_empty() {
1096            let _ = write!(out, " ({regimes})");
1097        }
1098        if self.not_flown > 0 {
1099            let _ = write!(out, "; {} more not flown", self.not_flown);
1100        }
1101        out
1102    }
1103
1104    /// Its result in words: the counts against its gate, target or bars, and its apogees.
1105    #[must_use]
1106    pub fn result(&self) -> String {
1107        self.result_spaced(" ")
1108    }
1109
1110    /// [`Summary::result`], with `space` between a bar's figure and its unit: the census table
1111    /// gives the README `&nbsp;` ([`table`]).
1112    fn result_spaced(&self, space: &str) -> String {
1113        let mut parts = Vec::new();
1114        let gated = self.count(Standing::Pass) + self.count(Standing::Fail);
1115        let targeted = self.count(Standing::WithinTarget) + self.count(Standing::OutsideTarget);
1116        if gated > 0 {
1117            parts.push(format!(
1118                "{} of {gated} gated metrics pass",
1119                self.count(Standing::Pass)
1120            ));
1121        }
1122        if targeted > 0 {
1123            parts.push(format!(
1124                "{} of {targeted} metrics within target",
1125                self.count(Standing::WithinTarget)
1126            ));
1127        }
1128        if let (Group::FlightLogs, Some(apogee)) = (self.group, self.apogee_percent) {
1129            parts.push(format!(
1130                "mean absolute apogee error {:.2}% (target {APOGEE_TARGET_PERCENT}%, {}); apogee \
1131                 {} to {}",
1132                apogee.mean_absolute,
1133                if apogee.mean_absolute <= APOGEE_TARGET_PERCENT {
1134                    "met"
1135                } else {
1136                    "missed"
1137                },
1138                signed_percent(apogee.min),
1139                signed_percent(apogee.max),
1140            ));
1141        } else if let Some(apogee) = self.apogee_percent {
1142            parts.push(format!(
1143                "apogee {} to {}",
1144                signed_percent(apogee.min),
1145                signed_percent(apogee.max)
1146            ));
1147        }
1148        let bars: Vec<String> = self
1149            .bars
1150            .iter()
1151            .map(|bar| {
1152                let (name, of) = BARRED
1153                    .iter()
1154                    .find(|(metric, ..)| *metric == bar.metric)
1155                    .map_or((bar.metric.as_str(), ""), |(_, name, of)| (name, of));
1156                format!(
1157                    "{name} within {}{}{of} on {} of {}",
1158                    bar.scale,
1159                    match bar.unit {
1160                        Unit::Caliber => format!("{space}calibers"),
1161                        Unit::Percent => "%".to_owned(),
1162                        Unit::Metric => String::new(),
1163                    },
1164                    bar.within,
1165                    bar.compared
1166                )
1167            })
1168            .collect();
1169        if !bars.is_empty() {
1170            parts.push(bars.join(", "));
1171        }
1172        for (standing, words) in [
1173            (Standing::NotScored, "not scored, each for a written reason"),
1174            (Standing::Withheld, "values withheld by the report"),
1175            (Standing::Gap, "known gaps"),
1176        ] {
1177            if self.count(standing) > 0 {
1178                parts.push(format!("{} {words}", self.count(standing)));
1179            }
1180        }
1181        parts.join("; ")
1182    }
1183
1184    /// Its headline: what was flown, against what and of which kind, how many and how fast, and
1185    /// the result ([Loft lesson L86][l86]).
1186    ///
1187    /// [l86]: https://hpr.fusionspace.co/decisions-and-roadmap.html#l86
1188    #[must_use]
1189    pub fn headline(&self) -> String {
1190        format!(
1191            "{} against {} ({}; {}): {}; {}.",
1192            capitalized(self.group.what()),
1193            self.reference,
1194            self.group.kind(),
1195            self.group.bar(),
1196            self.population(),
1197            self.result()
1198        )
1199    }
1200}
1201
1202fn capitalized(text: &str) -> String {
1203    let mut chars = text.chars();
1204    chars.next().map_or_else(String::new, |first| {
1205        first.to_uppercase().chain(chars).collect()
1206    })
1207}
1208
1209/// A reference as the table shows it: RocketPy's name and version, marked when patched, and
1210/// every other reference as its report names it. The census page gives each in full.
1211#[must_use]
1212pub fn short_reference(reference: &str) -> String {
1213    reference
1214        .split("; ")
1215        .map(|one| match one.strip_prefix("rocketpy ") {
1216            Some(rest) => {
1217                let (version, more) = rest.split_once(' ').unwrap_or((rest, ""));
1218                if more.is_empty() {
1219                    format!("RocketPy {version}")
1220                } else {
1221                    format!("RocketPy {version}, patched")
1222                }
1223            }
1224            None => one.to_owned(),
1225        })
1226        .collect::<Vec<_>>()
1227        .join("; ")
1228}
1229
1230/// How the committed reports differ from the census accepted last.
1231#[derive(Debug, Clone, PartialEq)]
1232#[non_exhaustive]
1233pub enum Change {
1234    /// A row the accepted census doesn't have.
1235    Added(Row),
1236    /// A row the accepted census has and this one doesn't.
1237    Removed(Row),
1238    /// A known gap, or a configuration not flown, that hpr flies now.
1239    Flown {
1240        /// The case's row as accepted.
1241        accepted: Row,
1242        /// Its rows now.
1243        now: Vec<Row>,
1244    },
1245    /// A row whose standing changed, better or worse.
1246    Standing {
1247        /// As accepted.
1248        accepted: Row,
1249        /// Now.
1250        now: Row,
1251    },
1252    /// A row that moved by more than its slack, further from its reference.
1253    Regressed {
1254        /// As accepted.
1255        accepted: Row,
1256        /// Now.
1257        now: Row,
1258    },
1259    /// A row that moved by more than its slack, closer to its reference or across it.
1260    Improved {
1261        /// As accepted.
1262        accepted: Row,
1263        /// Now.
1264        now: Row,
1265    },
1266    /// A row whose unit, scale, slack or speed class changed, or whose percentage no longer
1267    /// follows its difference (its reference moved): it is not the same comparison.
1268    Redefined {
1269        /// As accepted.
1270        accepted: Row,
1271        /// Now.
1272        now: Row,
1273    },
1274    /// A group compared with another reference, or another version of it.
1275    Reference {
1276        /// The group.
1277        group: Group,
1278        /// As accepted; empty if it had none.
1279        accepted: String,
1280        /// Now; empty if it has none.
1281        now: String,
1282    },
1283    /// The census's slack rule changed.
1284    Rule {
1285        /// [`Census::slack_share`] as accepted.
1286        accepted: f64,
1287        /// Now.
1288        now: f64,
1289    },
1290}
1291
1292impl Change {
1293    /// One line saying what changed.
1294    #[must_use]
1295    pub fn describe(&self) -> String {
1296        let moved = |accepted: &Row, now: &Row| {
1297            format!(
1298                "{:+.6}{unit} ({:.2}% of its scale) to {:+.6}{unit} ({:.2}%), slack {:.2e}",
1299                accepted.difference,
1300                100.0 * accepted.share(),
1301                now.difference,
1302                100.0 * now.share(),
1303                accepted.slack,
1304                unit = now.unit.suffix()
1305            )
1306        };
1307        match self {
1308            Self::Added(row) => format!("added: {} ({})", row.describe(), row.standing.name()),
1309            Self::Removed(row) => format!("removed: {} ({})", row.describe(), row.standing.name()),
1310            Self::Flown { accepted, now } => format!(
1311                "flown: {}, {} before: hpr flies it now (L85); {}",
1312                accepted.describe(),
1313                accepted.standing.name(),
1314                now.iter()
1315                    .map(|row| format!(
1316                        "{} {:+.6}{} ({})",
1317                        row.metric,
1318                        row.difference,
1319                        row.unit.suffix(),
1320                        row.standing.name()
1321                    ))
1322                    .collect::<Vec<_>>()
1323                    .join(", ")
1324            ),
1325            Self::Standing { accepted, now } => format!(
1326                "{}: {} to {}; {}",
1327                now.describe(),
1328                accepted.standing.name(),
1329                now.standing.name(),
1330                moved(accepted, now)
1331            ),
1332            Self::Regressed { accepted, now } => {
1333                format!("regressed: {}: {}", now.describe(), moved(accepted, now))
1334            }
1335            Self::Improved { accepted, now } => {
1336                format!("improved: {}: {}", now.describe(), moved(accepted, now))
1337            }
1338            Self::Redefined { accepted, now } => format!(
1339                "redefined: {}: unit, scale, slack, speed class or percentage changed ({:?}, {}, \
1340                 {:.2e}, {}, {:?} to {:?}, {}, {:.2e}, {}, {:?})",
1341                now.describe(),
1342                accepted.unit,
1343                accepted.scale,
1344                accepted.slack,
1345                accepted.regime.name(),
1346                accepted.percent,
1347                now.unit,
1348                now.scale,
1349                now.slack,
1350                now.regime.name(),
1351                now.percent
1352            ),
1353            Self::Reference {
1354                group,
1355                accepted,
1356                now,
1357            } => format!(
1358                "reference: {} compared with `{accepted}` before and `{now}` now",
1359                group.what()
1360            ),
1361            Self::Rule { accepted, now } => {
1362                format!("rule: the slack's share of a row's scale was {accepted} and is {now}")
1363            }
1364        }
1365    }
1366
1367    /// Whether it makes the record worse: a regression, a row lost, a standing that fell, a
1368    /// wider scale or slack, a changed unit, or a case flown now that fails or misses a bar.
1369    #[must_use]
1370    pub fn is_worse(&self) -> bool {
1371        match self {
1372            Self::Regressed { .. } | Self::Removed(_) => true,
1373            Self::Standing { accepted, now } => now.standing.rank() < accepted.standing.rank(),
1374            Self::Rule { accepted, now } => now > accepted,
1375            Self::Redefined { accepted, now } => {
1376                now.unit != accepted.unit
1377                    || now.scale > accepted.scale
1378                    || now.slack > accepted.slack
1379            }
1380            Self::Flown { now, .. } => now.iter().any(|row| {
1381                matches!(
1382                    row.standing,
1383                    Standing::Fail | Standing::OverBar | Standing::OutsideTarget
1384                )
1385            }),
1386            Self::Added(_) | Self::Improved { .. } | Self::Reference { .. } => false,
1387        }
1388    }
1389}
1390
1391/// Every way `now` differs from `accepted`. Empty when the census holds.
1392///
1393/// A row is a change when its unit, scale, slack, speed class or percentage's reference differs
1394/// ([`Change::Redefined`], listed as well as what follows), when its standing differs, or when its
1395/// difference moved by more than the accepted slack either way: a ratchet that only watched for
1396/// regressions would let an improvement slip back unseen. A case that was a known gap or not
1397/// flown, and is compared now, is one [`Change::Flown`] carrying its new rows.
1398#[must_use]
1399pub fn compare(accepted: &Census, now: &Census) -> Vec<Change> {
1400    let mut changes = Vec::new();
1401    if accepted.slack_share.to_bits() != now.slack_share.to_bits() {
1402        changes.push(Change::Rule {
1403            accepted: accepted.slack_share,
1404            now: now.slack_share,
1405        });
1406    }
1407    let groups: BTreeSet<&Group> = accepted
1408        .references
1409        .keys()
1410        .chain(now.references.keys())
1411        .collect();
1412    for group in groups {
1413        let (was, is) = (
1414            accepted.references.get(group).cloned().unwrap_or_default(),
1415            now.references.get(group).cloned().unwrap_or_default(),
1416        );
1417        if was != is {
1418            changes.push(Change::Reference {
1419                group: *group,
1420                accepted: was,
1421                now: is,
1422            });
1423        }
1424    }
1425    let before: BTreeMap<_, &Row> = accepted.rows.iter().map(|row| (row.key(), row)).collect();
1426    let after: BTreeMap<_, &Row> = now.rows.iter().map(|row| (row.key(), row)).collect();
1427    // The cases compared now, and those among them that were known gaps or not flown before:
1428    // their new rows come with them.
1429    let compared_now: BTreeSet<(Group, &str)> = now
1430        .rows
1431        .iter()
1432        .filter(|row| !row.standing.unflown())
1433        .map(|row| (row.group, row.case.as_str()))
1434        .collect();
1435    let newly_flown: BTreeSet<(Group, &str)> = accepted
1436        .rows
1437        .iter()
1438        .filter(|row| row.standing.unflown() && !after.contains_key(&row.key()))
1439        .map(|row| (row.group, row.case.as_str()))
1440        .filter(|case| compared_now.contains(case))
1441        .collect();
1442    let keys: BTreeSet<_> = before.keys().chain(after.keys()).copied().collect();
1443    let differs = |a: f64, b: f64| (a - b).abs() > 1e-9 * a.abs().max(b.abs());
1444    for key in keys {
1445        let flown = newly_flown.contains(&(key.0, key.1));
1446        match (before.get(&key), after.get(&key)) {
1447            (Some(was), None) if flown => changes.push(Change::Flown {
1448                accepted: (*was).clone(),
1449                now: now
1450                    .rows
1451                    .iter()
1452                    .filter(|row| row.group == key.0 && row.case == key.1)
1453                    .cloned()
1454                    .collect(),
1455            }),
1456            (Some(was), None) => changes.push(Change::Removed((*was).clone())),
1457            (None, Some(_)) if flown => {}
1458            (None, Some(is)) => changes.push(Change::Added((*is).clone())),
1459            (Some(was), Some(is)) => {
1460                let (was, is) = ((*was).clone(), (*is).clone());
1461                if was.unit != is.unit
1462                    || was.regime != is.regime
1463                    || differs(was.scale, is.scale)
1464                    || differs(was.slack, is.slack)
1465                    || !percent_follows(&was, &is)
1466                {
1467                    changes.push(Change::Redefined {
1468                        accepted: was.clone(),
1469                        now: is.clone(),
1470                    });
1471                }
1472                if was.standing != is.standing {
1473                    changes.push(Change::Standing {
1474                        accepted: was,
1475                        now: is,
1476                    });
1477                } else if (is.difference - was.difference).abs() > was.slack {
1478                    if is.difference.abs() > was.difference.abs() {
1479                        changes.push(Change::Regressed {
1480                            accepted: was,
1481                            now: is,
1482                        });
1483                    } else {
1484                        changes.push(Change::Improved {
1485                            accepted: was,
1486                            now: is,
1487                        });
1488                    }
1489                }
1490            }
1491            (None, None) => {}
1492        }
1493    }
1494    changes
1495}
1496
1497/// Whether `now`'s percentage is still its difference over the reference `accepted`'s was: a
1498/// percentage that moved on its own means the reference moved, which the difference can't show.
1499/// Held to the accepted slack, carried into per cent.
1500fn percent_follows(accepted: &Row, now: &Row) -> bool {
1501    match (accepted.percent, now.percent) {
1502        (None, None) => true,
1503        // A zero difference has a zero percentage, and says nothing of its reference.
1504        (Some(was), Some(_)) if accepted.difference == 0.0 => was == 0.0,
1505        (Some(was), Some(is)) => {
1506            // Per cent per unit of difference: 100 over the reference, as accepted.
1507            let per_unit = was / accepted.difference;
1508            let expected = now.difference * per_unit;
1509            (is - expected).abs()
1510                <= accepted.slack * per_unit.abs() + 1e-9 * is.abs().max(expected.abs())
1511        }
1512        // A difference withheld, or no longer withheld, is a change of standing, not of definition.
1513        _ => accepted.standing == Standing::Withheld || now.standing == Standing::Withheld,
1514    }
1515}
1516
1517/// The census as accepted: the rows, what they add up to, and why it was last accepted.
1518#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
1519pub struct Accepted {
1520    /// The command that writes it.
1521    pub generated_by: String,
1522    /// Why the census was last accepted, in the words of whoever accepted it.
1523    pub reason: String,
1524    /// What changed then, one line each.
1525    pub changes: Vec<String>,
1526    /// What each group added up to: [`Census::summaries`], written out for a reader, and
1527    /// never read back: [`Accepted::refreshed`] computes them again.
1528    #[serde(default, skip_deserializing)]
1529    pub summaries: Vec<Summary>,
1530    /// The census.
1531    pub census: Census,
1532}
1533
1534impl Accepted {
1535    /// The census `census`, accepted over `previous` for `reason`.
1536    #[must_use]
1537    pub fn new(census: Census, previous: Option<&Census>, reason: &str) -> Self {
1538        let changes = previous.map_or_else(
1539            || vec![format!("the first census: {} rows", census.rows.len())],
1540            |previous| {
1541                compare(previous, &census)
1542                    .iter()
1543                    .map(Change::describe)
1544                    .collect()
1545            },
1546        );
1547        Self {
1548            generated_by: "cargo xtask census --accept".to_owned(),
1549            reason: reason.trim().to_owned(),
1550            changes,
1551            summaries: census.summaries(),
1552            census,
1553        }
1554    }
1555
1556    /// The same, with its summaries computed again from its rows.
1557    #[must_use]
1558    pub fn refreshed(&self) -> Self {
1559        Self {
1560            summaries: self.census.summaries(),
1561            ..self.clone()
1562        }
1563    }
1564
1565    /// The census page, `validation/reports/census.md`.
1566    #[must_use]
1567    pub fn to_markdown(&self) -> String {
1568        let summaries = self.census.summaries();
1569        let mut out = String::new();
1570        let _ = writeln!(out, "# Accuracy census\n");
1571        let _ = writeln!(
1572            out,
1573            "Generated by `{}` from the committed reports; do not edit. `cargo xtask validate \
1574             --check` holds those reports to this census, row by row: a row that moves by more \
1575             than its slack, changes its standing, or comes or goes, a reference that changes, or \
1576             a changed slack rule fails it until the census is accepted again with a reason. It \
1577             holds {} rows.\n",
1578            self.generated_by,
1579            self.census.rows.len()
1580        );
1581        let _ = writeln!(out, "## Headlines\n");
1582        for summary in &summaries {
1583            let _ = writeln!(out, "- {}", summary.headline());
1584        }
1585        let _ = writeln!(out);
1586        let _ = writeln!(out, "{}", table(&summaries, None, " "));
1587        let _ = writeln!(out, "{}", reading(self.census.slack_share));
1588        let _ = writeln!(out, "## Rows by standing\n");
1589        let _ = writeln!(out, "| group | metric | standing | rows |");
1590        let _ = writeln!(out, "|---|---|---|---:|");
1591        let mut counts: BTreeMap<(Group, &str, Standing), usize> = BTreeMap::new();
1592        for row in &self.census.rows {
1593            let metric = if row.metric.is_empty() {
1594                "(the case)"
1595            } else {
1596                row.metric.as_str()
1597            };
1598            *counts.entry((row.group, metric, row.standing)).or_insert(0) += 1;
1599        }
1600        for ((group, metric, standing), count) in counts {
1601            let _ = writeln!(
1602                out,
1603                "| {} | {metric} | {} | {count} |",
1604                group.what(),
1605                standing.name()
1606            );
1607        }
1608        let _ = writeln!(out);
1609        let _ = writeln!(out, "## Last accepted\n");
1610        let _ = writeln!(out, "Reason: {}\n", self.reason);
1611        const SHOWN: usize = 50;
1612        for change in self.changes.iter().take(SHOWN) {
1613            let _ = writeln!(out, "- {change}");
1614        }
1615        if self.changes.len() > SHOWN {
1616            let _ = writeln!(
1617                out,
1618                "- and {} more, in `census.json`",
1619                self.changes.len() - SHOWN
1620            );
1621        }
1622        out
1623    }
1624}
1625
1626/// How to read the census: its speed classes, its slack and each kind of row's scale, from the
1627/// constants that set them.
1628fn reading(slack_share: f64) -> String {
1629    // A worked example: a relative tolerance on a round apogee.
1630    let (tolerance, apogee_m) = (NOT_SCORED_SCALE, 1000.0);
1631    let allowed_m = tolerance * apogee_m;
1632    let mut out = String::new();
1633    let _ = writeln!(out, "## How to read it\n");
1634    let _ = writeln!(
1635        out,
1636        "Each flight is classed by its largest Mach number: subsonic below {SUBSONIC_BELOW}, \
1637         transonic from {SUBSONIC_BELOW} to {SUPERSONIC_ABOVE}, supersonic above \
1638         {SUPERSONIC_ABOVE}. The harness's flights are classed by RocketPy's largest Mach \
1639         number, OpenRocket's by OpenRocket's, and the logged flights by hpr's, since a log has \
1640         none.\n"
1641    );
1642    let _ = writeln!(
1643        out,
1644        "A row's slack is {}% of its scale, and for a harness row never less than the harness's \
1645         reproduction bound, 2e-6 or 1e-7 of the value, whichever is larger. The scale is the \
1646         row's own tolerance where it has one, and otherwise the bar of its kind:\n",
1647        100.0 * slack_share
1648    );
1649    let _ = writeln!(out, "| row | scale |");
1650    let _ = writeln!(out, "|---|---|");
1651    for (row, scale) in [
1652        (
1653            "harness metric, held to a tolerance",
1654            "that tolerance".to_owned(),
1655        ),
1656        (
1657            "harness metric, not scored",
1658            format!("{}% of its reference", 100.0 * NOT_SCORED_SCALE),
1659        ),
1660        (
1661            "OpenRocket apogee or largest speed",
1662            format!("{OPENROCKET_BAR_PERCENT}%"),
1663        ),
1664        (
1665            "OpenRocket mass, at launch or at rod clearance",
1666            format!("{MASS_BAR_PERCENT}%"),
1667        ),
1668        (
1669            "OpenRocket stability margin, or center of mass",
1670            format!("{MARGIN_BAR_CAL} calibers"),
1671        ),
1672        ("logged apogee", format!("{APOGEE_TARGET_PERCENT}%")),
1673        (
1674            "logged climb (the RMS of the climb's heights, as a share of the apogee)",
1675            format!("{TRACE_BAR_PERCENT}%"),
1676        ),
1677    ] {
1678        let _ = writeln!(out, "| {row} | {scale} |");
1679    }
1680    let _ = writeln!(
1681        out,
1682        "\nFor example, a {}% tolerance on a {apogee_m} m apogee allows {allowed_m} m, and the \
1683         census lets the difference move by {} m before it fails.",
1684        100.0 * tolerance,
1685        slack_share * allowed_m
1686    );
1687    out
1688}
1689
1690/// A difference in percent with its sign, to two places, and a real minus sign (U+2212) as the
1691/// product system writes one on screen (`data.md`, *Numbers*): `+1.21%`, `−7.28%`.
1692fn signed_percent(value: f64) -> String {
1693    format!("{value:+.2}%").replace('-', "\u{2212}")
1694}
1695
1696/// The census table, as the README and the accuracy page show it, each row's reference linked to
1697/// `link` (the census page) where one is given, and `space` between a bar's figure and its unit:
1698/// `&nbsp;` for the README, which GitHub shows as written (`data.md`, *Numbers*: a line never
1699/// ends between them).
1700#[must_use]
1701pub fn table(summaries: &[Summary], link: Option<&str>, space: &str) -> String {
1702    let mut out = String::new();
1703    let _ = writeln!(
1704        out,
1705        "| compared with | kind | held to | flights (speed) | result |"
1706    );
1707    let _ = writeln!(out, "|---|---|---|---|---|");
1708    for summary in summaries {
1709        let reference = short_reference(&summary.reference);
1710        let _ = writeln!(
1711            out,
1712            "| {}: {} | {} | {} | {} | {} |",
1713            link.map_or_else(
1714                || reference.clone(),
1715                |link| format!("[{reference}]({link})")
1716            ),
1717            summary.group.what(),
1718            summary.group.kind(),
1719            summary.group.bar(),
1720            summary.population(),
1721            summary.result_spaced(space)
1722        );
1723    }
1724    out
1725}
1726
1727// The badges' colors and type: the light theme's roles and signal fills of the FusionSpace
1728// product system's foundations (Rev A, `product/foundations.md`, "Semantic roles" and "Type";
1729// ADR-164), the colors `cargo xtask figures` allows.
1730/// The label's cell and an unjudged message's.
1731const SURFACE: &str = "#FFFFFF";
1732/// The outline and the rule between the cells (`rule-strong`), and an unjudged message's text
1733/// (`ink-muted`).
1734const RULE_STRONG: &str = "#566079";
1735/// The label's text, and the text on the caution fill.
1736const INK: &str = "#0B0F1C";
1737/// Normal, within its target: `ok-fill`, with white text on it.
1738const OK_FILL: &str = "#0A6355";
1739/// A failed gate or a missed target, a fault to fix: `caution-fill`, with ink on it.
1740const CAUTION_FILL: &str = "#F5AF20";
1741/// The system's data family, with the fallbacks the figure check measures.
1742const BADGE_FONT: &str = "'Cascadia Mono', ui-monospace, Menlo, Consolas, monospace";
1743
1744/// What a badge's message says of its state, which sets its cell's fill and text.
1745#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1746enum BadgeState {
1747    /// Within its gate or target.
1748    Ok,
1749    /// Outside it.
1750    Caution,
1751    /// Nothing judged.
1752    Unjudged,
1753}
1754
1755/// One badge: a flat SVG, the label on the left on white, the message on the right on its
1756/// state's fill, square, outlined, in Cascadia Mono at 12 px (the system's `label` size).
1757fn badge(label: &str, message: &str, state: BadgeState) -> String {
1758    // 7.5 px a character covers the widest monospace face the figure check measures at 12 px;
1759    // 8 px of padding each side.
1760    let width = |text: &str| 16 + (15 * text.chars().count()).div_ceil(2);
1761    let (left, right) = (width(label), width(message));
1762    let total = left + right;
1763    let (fill, text) = match state {
1764        BadgeState::Ok => (OK_FILL, SURFACE),
1765        BadgeState::Caution => (CAUTION_FILL, INK),
1766        BadgeState::Unjudged => (SURFACE, RULE_STRONG),
1767    };
1768    format!(
1769        "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"{total}\" height=\"20\" role=\"img\" \
1770         aria-label=\"{label}: {message}\">\n\
1771         <title>{label}: {message}</title>\n\
1772         <rect width=\"{left}\" height=\"20\" fill=\"{SURFACE}\"/>\n\
1773         <rect x=\"{left}\" width=\"{right}\" height=\"20\" fill=\"{fill}\"/>\n\
1774         <g fill=\"none\" stroke=\"{RULE_STRONG}\" stroke-width=\"1\">\n\
1775         <rect x=\"0.5\" y=\"0.5\" width=\"{}\" height=\"19\"/>\n\
1776         <line x1=\"{}.5\" y1=\"0\" x2=\"{}.5\" y2=\"20\"/>\n\
1777         </g>\n\
1778         <g font-family=\"{BADGE_FONT}\" font-size=\"12\">\n\
1779         <text x=\"8\" y=\"14\" fill=\"{INK}\">{label}</text>\n\
1780         <text x=\"{}\" y=\"14\" fill=\"{text}\">{message}</text>\n\
1781         </g>\n\
1782         </svg>\n",
1783        total - 1,
1784        left,
1785        left,
1786        left + 8
1787    )
1788}
1789
1790/// The badges, by file name: the gated code-to-code metrics that pass, of all of them, and the
1791/// real flights' mean apogee error against its target. Two, so the one measurement stands beside
1792/// the agreement with another program.
1793#[must_use]
1794pub fn badges(summaries: &[Summary]) -> Vec<(&'static str, String)> {
1795    let (pass, gated) = summaries
1796        .iter()
1797        .filter(|summary| matches!(summary.group, Group::Descent | Group::SameDrag))
1798        .fold((0, 0), |(pass, gated), summary| {
1799            (
1800                pass + summary.count(Standing::Pass),
1801                gated + summary.count(Standing::Pass) + summary.count(Standing::Fail),
1802            )
1803        });
1804    let mut out = vec![(
1805        "census-badge.svg",
1806        badge(
1807            "vs RocketPy, same inputs",
1808            &format!("{pass} of {gated} gated metrics pass"),
1809            if pass == gated && gated > 0 {
1810                BadgeState::Ok
1811            } else {
1812                BadgeState::Caution
1813            },
1814        ),
1815    )];
1816    let flights = summaries
1817        .iter()
1818        .find(|summary| summary.group == Group::FlightLogs)
1819        .and_then(|summary| summary.apogee_percent);
1820    // Always written, so a badge from an earlier census can't linger unchecked.
1821    out.push((
1822        "real-flights-badge.svg",
1823        flights.map_or_else(
1824            || badge("real flights", "none compared", BadgeState::Unjudged),
1825            |apogee| {
1826                let met = apogee.mean_absolute <= APOGEE_TARGET_PERCENT;
1827                badge(
1828                    &format!("{} real flights", apogee.count),
1829                    &format!(
1830                        "mean absolute apogee error {:.2}% (target {APOGEE_TARGET_PERCENT}%, {})",
1831                        apogee.mean_absolute,
1832                        if met { "met" } else { "missed" }
1833                    ),
1834                    if met {
1835                        BadgeState::Ok
1836                    } else {
1837                        BadgeState::Caution
1838                    },
1839                )
1840            },
1841        ),
1842    ));
1843    out
1844}
1845
1846#[cfg(test)]
1847mod tests;