navcore_enc_check/

bench.rs

//! Reference routes for the `bench` subcommand: a fixed set of
//! positions in Slovenian and Italian waters, checked against a real
//! chart on every run, for measuring the effect of a change to
//! `route-find`'s search or its caches.
//!
//! Every position is verified against a real chart as open, safe
//! water -- a reference case sitting on a rock or in charted shallows
//! would only prove itself broken, not detect a regression. A
//! zero-length `enc-check leg --from P --to P` probe cannot verify a
//! candidate point reliably: a degenerate leg has no corridor band for
//! `check_leg` to test, so it reports "nothing found" for any
//! position, land included. Instead, each candidate point is checked
//! with a short real leg (a tenth of a nautical mile) in a few
//! directions; `route-find`'s own `Hazards::blocked` (private to that
//! crate) tests a small square around the point directly, without
//! this gap.

use nav_math::Position;

/// One route `bench` measures on every run: a name, and the two
/// positions [`route_find::find_route`] searches between.
pub struct ReferenceRoute {
    /// What this case is meant to exercise, for the table `bench`
    /// prints.
    pub name: &'static str,
    /// Where the route starts.
    pub from: Position,
    /// Where the route ends.
    pub to: Position,
}

/// A spread of distances and difficulty; each entry tests something
/// specific:
///
/// - the two short routes are the baseline case: lattice search only,
///   at the low end of wall-clock time;
/// - the medium route sits between the short and long cases, still
///   lattice-only, at real cross-gulf scale;
/// - "around Istria (moderate)" is a long case the lattice's own
///   margin escalation resolves without the visibility-graph
///   fallback -- worth checking if a future change makes it need that
///   fallback;
/// - "around Istria (DEPARE-heavy)" is the hardest lattice-only case,
///   exercising `fetch_preferring_detail`'s cost against dense
///   `DEPARE` coverage; the most regression-sensitive figure in this
///   list;
/// - Naples-Palermo, Bari-Brindisi, and Chioggia-Koper extend the
///   geographic spread beyond the northern Adriatic, each a real,
///   direct or near-direct route;
/// - Palermo-Olbia, Salerno-Napoli, and Marina di Campo (Elba)-La
///   Spezia extend it further: open-sea crossings and short coastal
///   hops;
/// - "La Maddalena to Porto Cervo" is short (about 10 NM) but tests
///   the archipelago it crosses: dense small `DEPARE` tiles there
///   make `route_find::visibility::significant_shallow_areas`'s own
///   `geo::unary_union` slow if fetched over too wide an area, rather
///   than the tight area `find_route`'s own margin schedule actually
///   uses;
/// - "Licata to Catania" is the hardest included case: rounding
///   Sicily's Cape Passero requires the visibility-graph fallback's
///   basemap-derived corners, adaptive edge subdivision, and per-edge
///   bisection together. Tens of seconds on a real chart, slower than
///   every other case here; a future change that makes this
///   meaningfully slower, or shifts the route's shape away from
///   hugging the cape, is worth noticing.
pub const REFERENCE_ROUTES: &[ReferenceRoute] = &[
    ReferenceRoute {
        name: "short hop, open Gulf of Trieste",
        from: Position::new(45.60, 13.55),
        to: Position::new(45.65, 13.55),
    },
    ReferenceRoute {
        name: "short hop, near-shore Gulf of Trieste",
        from: Position::new(45.55, 13.62),
        to: Position::new(45.60, 13.55),
    },
    ReferenceRoute {
        name: "medium, across the gulf toward Istria",
        from: Position::new(45.65, 13.55),
        to: Position::new(45.45, 13.20),
    },
    ReferenceRoute {
        name: "around Istria (moderate)",
        from: Position::new(45.60, 13.65),
        to: Position::new(43.58, 13.60),
    },
    ReferenceRoute {
        name: "around Istria (DEPARE-heavy)",
        from: Position::new(45.70, 13.65),
        to: Position::new(42.50, 14.50),
    },
    ReferenceRoute {
        name: "Naples to Palermo",
        from: Position::new(40.75, 14.20),
        to: Position::new(38.25, 13.20),
    },
    ReferenceRoute {
        name: "Bari to Brindisi",
        from: Position::new(41.10, 17.10),
        to: Position::new(40.65, 18.15),
    },
    ReferenceRoute {
        name: "Chioggia to Koper",
        from: Position::new(45.15, 12.35),
        to: Position::new(45.55, 13.65),
    },
    ReferenceRoute {
        name: "Palermo to Olbia",
        from: Position::new(38.19, 13.40),
        to: Position::new(40.90, 9.65),
    },
    ReferenceRoute {
        name: "Salerno to Napoli",
        from: Position::new(40.62, 14.78),
        to: Position::new(40.78, 14.27),
    },
    ReferenceRoute {
        name: "Marina di Campo (Elba) to La Spezia",
        from: Position::new(42.70, 10.24),
        to: Position::new(44.02, 9.80),
    },
    ReferenceRoute {
        name: "La Maddalena to Porto Cervo",
        from: Position::new(41.19, 9.43),
        to: Position::new(41.10, 9.60),
    },
    ReferenceRoute {
        name: "Licata to Catania",
        from: Position::new(37.05, 13.85),
        to: Position::new(37.45, 15.20),
    },
    ReferenceRoute {
        name: "Piran to Izola",
        from: Position::new(45.5450, 13.5550),
        to: Position::new(45.5650, 13.6550),
    },
    ReferenceRoute {
        name: "Izola to Koper",
        from: Position::new(45.5650, 13.6550),
        to: Position::new(45.5520, 13.7150),
    },
    ReferenceRoute {
        name: "Koper to Trieste",
        from: Position::new(45.5520, 13.7150),
        to: Position::new(45.6300, 13.7300),
    },
    ReferenceRoute {
        name: "Trieste to Muggia",
        from: Position::new(45.6300, 13.7300),
        to: Position::new(45.6150, 13.7500),
    },
    ReferenceRoute {
        name: "Trieste to Grado",
        from: Position::new(45.6300, 13.7300),
        to: Position::new(45.6000, 13.5200),
    },
    ReferenceRoute {
        name: "Grado to Lignano",
        from: Position::new(45.6000, 13.5200),
        to: Position::new(45.6500, 13.2000),
    },
    ReferenceRoute {
        name: "Lignano to Caorle",
        from: Position::new(45.6500, 13.2000),
        to: Position::new(45.5700, 12.9500),
    },
    ReferenceRoute {
        name: "Caorle to Venezia",
        from: Position::new(45.5700, 12.9500),
        to: Position::new(45.4000, 12.5500),
    },
    ReferenceRoute {
        name: "Venezia to Chioggia",
        from: Position::new(45.4000, 12.5500),
        to: Position::new(45.1500, 12.3500),
    },
    ReferenceRoute {
        name: "Chioggia to Ravenna",
        from: Position::new(45.1500, 12.3500),
        to: Position::new(44.4600, 12.4000),
    },
    ReferenceRoute {
        name: "Ravenna to Rimini",
        from: Position::new(44.4600, 12.4000),
        to: Position::new(44.0600, 12.6100),
    },
    ReferenceRoute {
        name: "Rimini to Ancona",
        from: Position::new(44.0600, 12.6100),
        to: Position::new(43.6500, 13.6500),
    },
    ReferenceRoute {
        name: "Koper to Venezia",
        from: Position::new(45.5520, 13.7150),
        to: Position::new(45.4000, 12.5500),
    },
];

/// One [`ReferenceRoute`]'s own previously measured result, against which
/// `bench` compares a later run's own result to decide whether it
/// regressed -- see [`distance_regressed`] and [`time_regressed`].
#[derive(Clone, Copy)]
pub struct BaselineEntry {
    /// The route length measured by `run_bench`, in NM.
    pub route_nm: f64,
    /// How long [`route_find::find_route`] took, in milliseconds.
    pub elapsed_ms: u128,
}

/// Every [`ReferenceRoute`]'s own [`BaselineEntry`], keyed by
/// [`ReferenceRoute::name`].
pub type Baseline = std::collections::HashMap<String, BaselineEntry>;

/// How much a route may grow, relative to its own baseline length,
/// before [`distance_regressed`] reports a regression -- whichever is
/// larger, this or [`DISTANCE_REGRESSION_FLOOR_NM`].
///
/// Route length is deterministic for a given chart and code version,
/// so any growth is technically a real change. One percent allows for
/// a legitimate tweak (a smoothing tolerance, a lattice cell size)
/// shifting a route slightly, while remaining far below what an
/// actual regression in this crate produces -- a route lengthening
/// from roughly 118 NM to 695 NM, not from 118 to 119.
const DISTANCE_REGRESSION_RELATIVE: f64 = 0.01;

/// The absolute floor [`distance_regressed`] applies alongside
/// [`DISTANCE_REGRESSION_RELATIVE`], in NM, so a short hop's own tiny
/// baseline (the two short Gulf of Trieste cases measure a bare 3-4 NM)
/// does not make one percent tighter than floating-point noise can
/// actually promise.
const DISTANCE_REGRESSION_FLOOR_NM: f64 = 0.05;

/// How much slower a route may run, relative to its own baseline
/// time, before [`time_regressed`] reports a regression -- whichever
/// is larger, this or [`TIME_REGRESSION_FLOOR_MS`].
///
/// Measured rather than assumed: running this suite twice in a row on
/// the same machine varies each case's time by at most a few percent,
/// even the slowest case (Licata to Catania, tens of seconds). Fifty
/// percent stays comfortably above that margin, with room for a
/// shared CI runner's noisier hardware, while still catching an
/// actual regression in this crate -- a sevenfold slowdown, not a
/// fifty-percent one.
const TIME_REGRESSION_RELATIVE: f64 = 0.50;

/// The absolute floor [`time_regressed`] applies alongside
/// [`TIME_REGRESSION_RELATIVE`], in milliseconds, so the two fastest
/// cases here (the short Gulf of Trieste hops, under 100 ms each) are
/// not held to a tighter margin in absolute terms than scheduler jitter
/// alone can already account for.
const TIME_REGRESSION_FLOOR_MS: u128 = 100;

/// Whether `current_nm` counts as a regression against `baseline_nm` --
/// see [`DISTANCE_REGRESSION_RELATIVE`] and [`DISTANCE_REGRESSION_FLOOR_NM`]
/// for the margin. A route that got *shorter* never regresses here,
/// whatever the reason.
#[must_use]
pub fn distance_regressed(baseline_nm: f64, current_nm: f64) -> bool {
    let allowance = (baseline_nm * DISTANCE_REGRESSION_RELATIVE).max(DISTANCE_REGRESSION_FLOOR_NM);
    current_nm > baseline_nm + allowance
}

/// Whether `current_ms` counts as a regression against `baseline_ms` --
/// see [`TIME_REGRESSION_RELATIVE`] and [`TIME_REGRESSION_FLOOR_MS`] for
/// the margin. A run that got *faster* never regresses here, whatever
/// the reason.
#[must_use]
pub fn time_regressed(baseline_ms: u128, current_ms: u128) -> bool {
    #[allow(clippy::cast_precision_loss, clippy::cast_possible_truncation, clippy::cast_sign_loss)]
    let allowance_ms = ((baseline_ms as f64) * TIME_REGRESSION_RELATIVE).max(TIME_REGRESSION_FLOOR_MS as f64) as u128;
    current_ms > baseline_ms + allowance_ms
}

/// The one-line, tab-separated format [`load_baseline`] reads and
/// [`write_baseline`] writes: `name\troute_nm\telapsed_ms`, one
/// [`ReferenceRoute`] per line, blank lines and `#`-comments ignored.
///
/// Hand-rolled rather than reached for a serialisation crate for the
/// same reason `hazards::restricts_entry`'s own doc gives for reading
/// `RESTRN` codes as digits instead of JSON: three plain fields split on
/// a tab is not a format worth a dependency to read.
fn parse_baseline_line(line: &str) -> Option<(String, BaselineEntry)> {
    let mut fields = line.split('\t');
    let name = fields.next()?;
    let route_nm: f64 = fields.next()?.parse().ok()?;
    let elapsed_ms: u128 = fields.next()?.parse().ok()?;
    Some((name.to_string(), BaselineEntry { route_nm, elapsed_ms }))
}

/// Loads a [`Baseline`] from `path`. A missing file reads as an empty
/// baseline, not an error -- the ordinary state before `bench` has ever
/// been run with `--write-baseline`, or for a [`ReferenceRoute`] just
/// added and not yet measured.
///
/// # Errors
///
/// If `path` exists but cannot be read.
pub fn load_baseline(path: &std::path::Path) -> std::io::Result<Baseline> {
    let text = match std::fs::read_to_string(path) {
        Ok(text) => text,
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(Baseline::new()),
        Err(error) => return Err(error),
    };
    Ok(text
        .lines()
        .map(str::trim)
        .filter(|line| !line.is_empty() && !line.starts_with('#'))
        .filter_map(parse_baseline_line)
        .collect())
}

/// Writes `entries` to `path` as [`parse_baseline_line`]'s own format, in
/// [`REFERENCE_ROUTES`]'s own order rather than whatever order a
/// [`Baseline`]'s own hash map would iterate in -- so the file reads the
/// same top-to-bottom as `bench`'s own printed table, and so a diff
/// between two baselines is a diff between two runs, not shuffled noise.
///
/// # Errors
///
/// If `path` cannot be written.
pub fn write_baseline(path: &std::path::Path, entries: &[(String, BaselineEntry)]) -> std::io::Result<()> {
    let mut text = String::from(
        "# enc-check bench baseline -- generated by `enc-check bench --write-baseline`; do not hand-edit\n",
    );
    for (name, entry) in entries {
        text.push_str(&format!("{name}\t{:.2}\t{}\n", entry.route_nm, entry.elapsed_ms));
    }
    std::fs::write(path, text)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn distance_regressed_ignores_noise_within_the_margin() {
        assert!(!distance_regressed(100.0, 100.9), "well within the 1% relative margin");
        assert!(!distance_regressed(2.0, 2.04), "within the absolute floor for a short route");
    }

    #[test]
    fn distance_regressed_catches_real_growth() {
        assert!(distance_regressed(100.0, 105.0), "5% growth on a long route is a real regression");
        assert!(distance_regressed(2.0, 2.10), "growth past the absolute floor on a short route");
    }

    #[test]
    fn distance_regressed_never_flags_a_shorter_route() {
        assert!(!distance_regressed(100.0, 50.0));
    }

    #[test]
    fn time_regressed_ignores_noise_within_the_margin() {
        assert!(!time_regressed(20_000, 21_000), "5% is well within the 50% relative margin");
        assert!(!time_regressed(90, 130), "within the absolute floor for a fast route");
    }

    #[test]
    fn time_regressed_catches_real_slowdown() {
        assert!(time_regressed(13_500, 90_000), "a real regression this crate has seen before");
    }

    #[test]
    fn time_regressed_never_flags_a_faster_run() {
        assert!(!time_regressed(20_000, 5_000));
    }

    #[test]
    fn parse_baseline_line_reads_a_well_formed_line() {
        let (name, entry) = parse_baseline_line("Licata to Catania\t118.32\t23491").unwrap();
        assert_eq!(name, "Licata to Catania");
        assert!((entry.route_nm - 118.32).abs() < 1e-9);
        assert_eq!(entry.elapsed_ms, 23491);
    }

    #[test]
    fn parse_baseline_line_rejects_a_malformed_line() {
        assert!(parse_baseline_line("only one field").is_none());
        assert!(parse_baseline_line("name\tnot-a-number\t123").is_none());
    }

    #[test]
    fn load_baseline_of_a_missing_file_is_empty_not_an_error() {
        let path = std::path::Path::new("/nonexistent/enc-check-bench-baseline-test.tsv");
        let baseline = load_baseline(path).expect("a missing file is not an error");
        assert!(baseline.is_empty());
    }

    #[test]
    fn write_then_load_baseline_round_trips() {
        let path = std::env::temp_dir().join(format!("enc-check-bench-baseline-test-{}.tsv", std::process::id()));
        let entries = vec![
            ("first route".to_string(), BaselineEntry { route_nm: 12.34, elapsed_ms: 567 }),
            ("second route".to_string(), BaselineEntry { route_nm: 89.0, elapsed_ms: 1234 }),
        ];

        write_baseline(&path, &entries).unwrap();
        let loaded = load_baseline(&path).unwrap();

        assert_eq!(loaded.len(), 2);
        for (name, entry) in &entries {
            let round_tripped = loaded.get(name).unwrap();
            assert!((round_tripped.route_nm - entry.route_nm).abs() < 1e-9);
            assert_eq!(round_tripped.elapsed_ms, entry.elapsed_ms);
        }

        let _ = std::fs::remove_file(&path);
    }

    #[test]
    fn load_baseline_skips_comments_and_blank_lines() {
        let path = std::env::temp_dir().join(format!("enc-check-bench-baseline-comment-test-{}.tsv", std::process::id()));
        std::fs::write(&path, "# a comment\n\nreal route\t1.00\t100\n").unwrap();

        let baseline = load_baseline(&path).unwrap();
        assert_eq!(baseline.len(), 1);
        assert!(baseline.contains_key("real route"));

        let _ = std::fs::remove_file(&path);
    }
}