diff --git a/README.md b/README.md index 3ef8f48..98e27dd 100644 --- a/README.md +++ b/README.md @@ -196,7 +196,31 @@ stay available at any size: - `predict_ranking(teams, ranks)` — one specific finishing order. Unknown keys are an error, not a silent omission: a team the history has never -seen cannot produce a confident-looking probability. +seen cannot produce a confident-looking probability. The error names the key, and +every key must already be known — pre-filter with `lookup` or `current_skill` if +your caller cannot guarantee that. + +### Asking about one competitor + +`Gaussian` answers tail questions directly, which is what a stopping rule needs: + +```rust +use trueskill_tt::History; + +let mut h = History::builder().build(); +h.record_winner(&"alice", &"bob", 1).unwrap(); +let _ = h.converge().unwrap(); + +let skill = h.current_skill(&"alice").unwrap(); + +// "How sure am I that this is below the cutoff?" — a probability, not a +// `mu + z * sigma` band whose confidence drifts as sigma changes. +let _ = skill.probability_below(20.0); + +// Use this rather than `1.0 - probability_below(x)`: the complement cancels +// away every digit in the upper tail, which is where a stopping rule lives. +let _ = skill.probability_above(30.0); +``` ## Which match to play next diff --git a/benches/history_converge.rs b/benches/history_converge.rs index d13fbdf..aff9a0c 100644 --- a/benches/history_converge.rs +++ b/benches/history_converge.rs @@ -82,7 +82,7 @@ fn bench_converge(c: &mut Criterion) { b.iter_batched( || build_history_1v1(500, 100, 10, 42), |mut h| { - h.converge().unwrap(); + let _ = h.converge().unwrap(); }, BatchSize::SmallInput, ); @@ -92,7 +92,7 @@ fn bench_converge(c: &mut Criterion) { b.iter_batched( || build_history_1v1(2000, 200, 20, 42), |mut h| { - h.converge().unwrap(); + let _ = h.converge().unwrap(); }, BatchSize::SmallInput, ); @@ -106,7 +106,7 @@ fn bench_converge(c: &mut Criterion) { b.iter_batched( || build_history_1v1(5000, 50000, 5000, 42), |mut h| { - h.converge().unwrap(); + let _ = h.converge().unwrap(); }, BatchSize::SmallInput, ); diff --git a/benches/scored.rs b/benches/scored.rs index 19883f2..6a3909d 100644 --- a/benches/scored.rs +++ b/benches/scored.rs @@ -29,7 +29,7 @@ fn bench_scored_history(c: &mut Criterion) { }); } h.add_events(events).unwrap(); - h.converge().unwrap(); + let _ = h.converge().unwrap(); }); }); } diff --git a/examples/atp.rs b/examples/atp.rs index 4478924..2a967d8 100644 --- a/examples/atp.rs +++ b/examples/atp.rs @@ -46,14 +46,33 @@ fn main() { .sigma(1.6) .drift(ConstantDrift(0.036)) .convergence(trueskill_tt::ConvergenceOptions { - max_iter: 10, + // This history needs 30 sweeps to reach the epsilon below. It was + // capped at 10 until the `#[must_use]` on `ConvergenceReport` + // surfaced that the example had been shipping a short fit. + max_iter: 100, epsilon: 0.01, alpha: 1.0, }) .build(); hist.add_events(events).unwrap(); - hist.converge().unwrap(); + + // Read the report rather than discarding it. A fit that hits `max_iter` + // without reaching `epsilon` is not an error and does not look wrong — every + // rating comes back finite and sensibly ordered — so this flag is the only + // thing that says the numbers were still moving when the sweep stopped. + let report = hist.converge().unwrap(); + eprintln!( + "converged={} after {} sweeps, final step {:?}", + report.converged, report.iterations, report.final_step + ); + if !report.converged { + eprintln!( + "warning: stopped after {} sweeps with a final step of {:?}, \ + short of epsilon — raise ConvergenceOptions::max_iter", + report.iterations, report.final_step + ); + } let players = [ ("aggasi", "a092", 38800i64), diff --git a/src/convergence.rs b/src/convergence.rs index 114da2d..10309f8 100644 --- a/src/convergence.rs +++ b/src/convergence.rs @@ -63,6 +63,9 @@ impl Default for ConvergenceOptions { /// Post-hoc summary of a `History::converge` call. #[derive(Clone, Debug)] +#[must_use = "a ConvergenceReport carries `converged`, and a fit that stopped \ + at `max_iter` is wrong by a little rather than loudly broken — \ + check it, or bind it to `_` to say you have decided not to"] pub struct ConvergenceReport { pub iterations: usize, pub final_step: (f64, f64), diff --git a/src/error.rs b/src/error.rs index eb038ef..777a030 100644 --- a/src/error.rs +++ b/src/error.rs @@ -50,7 +50,17 @@ pub enum InferenceError { /// /// Reported rather than skipped: dropping unknown keys turns a team of /// strangers into a confident-looking probability about nobody. - UnknownKey { team: usize, member: usize }, + /// + /// `key` is the offending key's `Debug` rendering. It is carried because + /// the indices alone are not actionable: a caller that logs + /// `UnknownKey { team: 0, member: 0 }` learns nothing about *which* of its + /// keys the history has not seen, and the natural handling — fall back to a + /// neutral value — turns the whole thing into a plausible constant. + UnknownKey { + team: usize, + member: usize, + key: String, + }, /// A prediction was given a team with no members. EmptyTeam { team: usize }, /// Fewer than two teams were supplied to a prediction. @@ -108,10 +118,12 @@ impl fmt::Display for InferenceError { "competitor {competitor}: this batch sets {field} to two different values" ) } - Self::UnknownKey { team, member } => { + Self::UnknownKey { team, member, key } => { write!( f, - "team {team}, member {member}: no skill recorded for this key" + "team {team}, member {member}: no skill recorded for key {key} \ + (every key must already be known to the history; pre-filter \ + with `lookup` or `current_skill` if that is not guaranteed)" ) } Self::EmptyTeam { team } => { diff --git a/src/gaussian.rs b/src/gaussian.rs index 52fa2b7..23cc261 100644 --- a/src/gaussian.rs +++ b/src/gaussian.rs @@ -145,6 +145,45 @@ impl Gaussian { Self::from_mv(self.mu(), self.variance() + variance_delta) } + /// `P(X < x)` under this Gaussian. + /// + /// The question a stopping rule asks: *how sure am I that this competitor's + /// true skill is below the cutoff?* Expressing that as a probability keeps + /// its meaning as sigma changes, where a `mu + z * sigma` band silently + /// means different confidence at different uncertainties — which is exactly + /// the regime a stopping rule operates in. + /// + /// Accurate in the *lower* tail. For the upper tail use + /// [`Gaussian::probability_above`] rather than `1.0 - probability_below(x)`, + /// which cancels away every significant digit once the result is small. + /// + /// An improper Gaussian (non-positive precision) has no defined mean, so + /// this returns `0.5` — the same convention `mu()` and `sigma()` follow. + #[must_use] + pub fn probability_below(&self, x: f64) -> f64 { + if self.pi <= 0.0 { + return 0.5; + } + crate::cdf(x, self.mu(), self.sigma()) + } + + /// `P(X > x)` under this Gaussian. + /// + /// Computed as a survival function rather than `1 - cdf`, so it keeps full + /// relative precision in the upper tail: `1 - cdf` returns exactly zero + /// past about 8.3 sigma, where the true value is still 1e-19 and perfectly + /// representable. A stopping rule is evaluated precisely there — the + /// interesting cases are the ones near certainty. + /// + /// An improper Gaussian returns `0.5`, as [`Gaussian::probability_below`]. + #[must_use] + pub fn probability_above(&self, x: f64) -> f64 { + if self.pi <= 0.0 { + return 0.5; + } + crate::sf(x, self.mu(), self.sigma()) + } + /// EP damping in natural-parameter space: `α·new + (1−α)·self`. /// /// Used by within-game inference to stabilise oscillating fixed-point @@ -340,3 +379,68 @@ mod tests { assert!((damped.tau() - expected_tau).abs() < 1e-12); } } + +#[cfg(test)] +mod tail_probability_tests { + use super::*; + + #[test] + fn probability_below_matches_published_quantiles() { + let g = Gaussian::from_ms(0.0, 1.0); + for (x, expected) in [ + (-1.959_963_984_540_054, 0.025), + (0.0, 0.5), + (1.281_551_565_544_6, 0.9), + (1.959_963_984_540_054, 0.975), + ] { + let got = g.probability_below(x); + assert!( + (got - expected).abs() < 1e-12, + "P(X < {x}) = {got}, expected {expected}" + ); + } + } + + #[test] + fn the_two_tails_partition_the_mass() { + let g = Gaussian::from_ms(3.0, 2.0); + for x in [-4.0f64, 0.0, 3.0, 7.5] { + let total = g.probability_below(x) + g.probability_above(x); + assert!((total - 1.0).abs() < 1e-15, "at {x}: {total}"); + } + } + + /// The reason `probability_above` exists rather than `1 - probability_below`. + #[test] + fn probability_above_keeps_precision_where_the_complement_collapses() { + let g = Gaussian::from_ms(0.0, 1.0); + for (x, expected) in [(9.0f64, 1.128_588e-19), (20.0, 2.753_624e-89)] { + let got = g.probability_above(x); + assert!( + (got - expected).abs() / expected < 1e-6, + "P(X > {x}) = {got}, expected ~{expected}" + ); + assert_eq!( + 1.0 - g.probability_below(x), + 0.0, + "the complement should still collapse at {x}" + ); + } + } + + #[test] + fn a_scaled_gaussian_shifts_and_stretches() { + let g = Gaussian::from_ms(25.0, 6.0); + assert!((g.probability_below(25.0) - 0.5).abs() < 1e-15); + // One sigma either side of the mean. + assert!((g.probability_below(31.0) - 0.841_344_746_068_543).abs() < 1e-12); + assert!((g.probability_above(19.0) - 0.841_344_746_068_543).abs() < 1e-12); + } + + #[test] + fn an_improper_gaussian_is_uninformative_rather_than_nan() { + let improper = Gaussian::from_ms(0.0, f64::INFINITY); + assert_eq!(improper.probability_below(5.0), 0.5); + assert_eq!(improper.probability_above(5.0), 0.5); + } +} diff --git a/src/history.rs b/src/history.rs index 493689f..562f317 100644 --- a/src/history.rs +++ b/src/history.rs @@ -583,7 +583,10 @@ impl, O: Observer, K: Eq + Hash + Clone> History Result>, InferenceError> { + fn member_skills(&self, teams: &[&[&K]]) -> Result>, InferenceError> + where + K: std::fmt::Debug, + { if teams.len() < 2 { return Err(InferenceError::NotEnoughTeams { got: teams.len() }); } @@ -600,6 +603,7 @@ impl, O: Observer, K: Eq + Hash + Clone> History, O: Observer, K: Eq + Hash + Clone> History Result<(Vec, Vec), InferenceError> { + fn performances(&self, teams: &[&[&K]]) -> Result<(Vec, Vec), InferenceError> + where + K: std::fmt::Debug, + { let skills = self.member_skills(teams)?; let performances = skills @@ -669,10 +676,23 @@ impl, O: Observer, K: Eq + Hash + Clone> History Result { + pub fn predict_quality(&self, teams: &[&[&K]]) -> Result + where + K: std::fmt::Debug, + { let groups = self.member_skills(teams)?; let group_refs: Vec<&[Gaussian]> = groups.iter().map(Vec::as_slice).collect(); Ok(crate::quality(&group_refs, self.beta)) @@ -697,9 +717,22 @@ impl, O: Observer, K: Eq + Hash + Clone> History Result { + pub fn expected_information_gain(&self, teams: &[&[&K]]) -> Result + where + K: std::fmt::Debug, + { let skills = self.member_skills(teams)?; let ratings: Vec>> = skills @@ -737,10 +770,23 @@ impl, O: Observer, K: Eq + Hash + Clone> History Result, InferenceError> { + pub fn predict_win_probabilities(&self, teams: &[&[&K]]) -> Result, InferenceError> + where + K: std::fmt::Debug, + { let (performances, sizes) = self.performances(teams)?; Ok(crate::predict::win_probabilities( &performances, @@ -770,10 +816,23 @@ impl, O: Observer, K: Eq + Hash + Clone> History Result { + pub fn predict_outcome(&self, teams: &[&[&K]]) -> Result + where + K: std::fmt::Debug, + { if teams.len() > crate::MAX_PREDICTED_TEAMS { return Err(InferenceError::TooManyTeams { got: teams.len(), @@ -800,9 +859,22 @@ impl, O: Observer, K: Eq + Hash + Clone> History Result { + pub fn predict_ranking(&self, teams: &[&[&K]], ranks: &[u32]) -> Result + where + K: std::fmt::Debug, + { if ranks.len() != teams.len() { return Err(InferenceError::MismatchedShape { kind: "ranks vs teams", @@ -1513,7 +1585,7 @@ mod tests { epsilon = 1e-6 ); - h1.converge().unwrap(); + let _ = h1.converge().unwrap(); assert_ulps_eq!( h1.time_slices[0].skills.get(a).unwrap().posterior(), @@ -1558,7 +1630,7 @@ mod tests { epsilon = 1e-6 ); - h2.converge().unwrap(); + let _ = h2.converge().unwrap(); assert_ulps_eq!( h2.time_slices[2].skills.get(a).unwrap().posterior(), @@ -1591,7 +1663,7 @@ mod tests { &[5, 6, 7], ); h.add_events(events).unwrap(); - h.converge().unwrap(); + let _ = h.converge().unwrap(); let lc_a = h.learning_curve("a"); let lc_c = h.learning_curve("c"); @@ -1633,7 +1705,7 @@ mod tests { &[1, 2, 3], ); h.add_events(events).unwrap(); - h.converge().unwrap(); + let _ = h.converge().unwrap(); let a = h.keys.get("a").unwrap(); let b = h.keys.get("b").unwrap(); @@ -1724,7 +1796,7 @@ mod tests { let evidence_third_event = h.log_evidence_internal(false, &[a]).exp() * 2.0; assert_ulps_eq!(0.669885, evidence_third_event, epsilon = 1e-6); - h.converge().unwrap(); + let _ = h.converge().unwrap(); let loocv_hat = h.log_evidence_internal(false, &[]).exp(); let p_d_m_hat = h.log_evidence_internal(true, &[]).exp(); @@ -1789,7 +1861,7 @@ mod tests { let b = h.keys.get("b").unwrap(); let c = h.keys.get("c").unwrap(); - h.converge().unwrap(); + let _ = h.converge().unwrap(); assert_eq!(h.time_slices[2].skills.get(b).unwrap().elapsed, 2); assert_eq!(h.time_slices[2].skills.get(c).unwrap().elapsed, 1); @@ -1838,7 +1910,7 @@ mod tests { ] ); - h.converge().unwrap(); + let _ = h.converge().unwrap(); assert_ulps_eq!( h.time_slices[0].skills.get(a).unwrap().posterior(), @@ -1886,7 +1958,7 @@ mod tests { let b = h.keys.get("b").unwrap(); let c = h.keys.get("c").unwrap(); - h.converge().unwrap(); + let _ = h.converge().unwrap(); assert_eq!(h.time_slices[2].skills.get(b).unwrap().elapsed, 2); assert_eq!(h.time_slices[2].skills.get(c).unwrap().elapsed, 1); @@ -1935,7 +2007,7 @@ mod tests { ] ); - h.converge().unwrap(); + let _ = h.converge().unwrap(); assert_ulps_eq!( h.time_slices[0].skills.get(a).unwrap().posterior(), @@ -2001,7 +2073,7 @@ mod tests { epsilon: EPSILON, alpha: 1.0, }; - h.converge().unwrap(); + let _ = h.converge().unwrap(); let loocv_approx_2 = h.log_evidence_internal(false, &[]).exp().sqrt(); @@ -2052,7 +2124,7 @@ mod tests { &[0, 10, 20], ); h.add_events(events).unwrap(); - h.converge().unwrap(); + let _ = h.converge().unwrap(); let a = h.keys.get("a").unwrap(); let b = h.keys.get("b").unwrap(); @@ -2116,7 +2188,7 @@ mod tests { assert_eq!(h.time_slices[0].skills.get(b).unwrap().elapsed, 0); assert_eq!(h.time_slices[end].skills.get(b).unwrap().elapsed, 5); - h.converge().unwrap(); + let _ = h.converge().unwrap(); assert_ulps_eq!( h.time_slices[0].skills.get(b).unwrap().posterior(), @@ -2155,7 +2227,7 @@ mod tests { &[0, 10, 20], ); h2.add_events(events).unwrap(); - h2.converge().unwrap(); + let _ = h2.converge().unwrap(); let a = h2.keys.get("a").unwrap(); let b = h2.keys.get("b").unwrap(); @@ -2219,7 +2291,7 @@ mod tests { assert_eq!(h2.time_slices[0].skills.get(b).unwrap().elapsed, 0); assert_eq!(h2.time_slices[end].skills.get(b).unwrap().elapsed, 5); - h2.converge().unwrap(); + let _ = h2.converge().unwrap(); assert_ulps_eq!( h2.time_slices[0].skills.get(b).unwrap().posterior(), @@ -2294,7 +2366,7 @@ mod tests { epsilon = 1e-6 ); - h.converge().unwrap(); + let _ = h.converge().unwrap(); let lc_a = h.learning_curve("a"); let lc_b = h.learning_curve("b"); @@ -2368,11 +2440,11 @@ mod tests { }) .build(); events_for(&mut h_capped); - h_capped.converge().unwrap(); + let _ = h_capped.converge().unwrap(); let mut h_full: History = History::builder().build(); events_for(&mut h_full); - h_full.converge().unwrap(); + let _ = h_full.converge().unwrap(); let curves_capped = h_capped.learning_curves(); let curves_full = h_full.learning_curves(); @@ -2409,7 +2481,7 @@ mod tests { let mut h_undamped: History = History::builder().build(); events_for(&mut h_undamped); - h_undamped.converge().unwrap(); + let _ = h_undamped.converge().unwrap(); let mut h_damped: History = History::builder() .convergence(ConvergenceOptions { @@ -2419,7 +2491,7 @@ mod tests { }) .build(); events_for(&mut h_damped); - h_damped.converge().unwrap(); + let _ = h_damped.converge().unwrap(); let curves_u = h_undamped.learning_curves(); let curves_d = h_damped.learning_curves(); @@ -2453,7 +2525,7 @@ mod tests { outcome: Outcome::scores_with_sigma([3.0, 1.0], 0.5), }]) .unwrap(); - h_a.converge().unwrap(); + let _ = h_a.converge().unwrap(); // Path B: history-wide default 0.5, no per-event override. let mut h_b = crate::History::builder().score_sigma(0.5).build(); @@ -2466,7 +2538,7 @@ mod tests { outcome: Outcome::scores([3.0, 1.0]), }]) .unwrap(); - h_b.converge().unwrap(); + let _ = h_b.converge().unwrap(); // Inheritance: posteriors must be bit-equal. let curves_a = h_a.learning_curves(); @@ -2495,7 +2567,7 @@ mod tests { outcome: Outcome::scores_with_sigma([3.0, 1.0], 2.0), }]) .unwrap(); - h_a.converge().unwrap(); + let _ = h_a.converge().unwrap(); // Path B: history-wide default 2.0, no per-event override. let mut h_b = crate::History::builder().score_sigma(2.0).build(); @@ -2508,7 +2580,7 @@ mod tests { outcome: Outcome::scores([3.0, 1.0]), }]) .unwrap(); - h_b.converge().unwrap(); + let _ = h_b.converge().unwrap(); // Override == default-set-to-the-override-value: bit-equal. let curves_a = h_a.learning_curves(); @@ -2532,7 +2604,7 @@ mod tests { outcome: Outcome::scores([3.0, 1.0]), }]) .unwrap(); - h_c.converge().unwrap(); + let _ = h_c.converge().unwrap(); let curves_c = h_c.learning_curves(); let mut max_diff: f64 = 0.0; @@ -2561,7 +2633,7 @@ mod tests { .scores_with_sigma([3.0, 1.0], 2.0) .commit() .unwrap(); - h_a.converge().unwrap(); + let _ = h_a.converge().unwrap(); // Path B: same outcome via the explicit Outcome constructor. let mut h_b = crate::History::builder().score_sigma(0.5).build(); @@ -2574,7 +2646,7 @@ mod tests { outcome: Outcome::scores_with_sigma([3.0, 1.0], 2.0), }]) .unwrap(); - h_b.converge().unwrap(); + let _ = h_b.converge().unwrap(); let curves_a = h_a.learning_curves(); let curves_b = h_b.learning_curves(); diff --git a/src/lib.rs b/src/lib.rs index 49237fa..d340fb7 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -158,6 +158,23 @@ pub const SIGMA: f64 = BETA * 6.0; pub const GAMMA: f64 = BETA * 0.03; pub const P_DRAW: f64 = 0.0; pub const EPSILON: f64 = 1e-6; +/// Default cap on convergence sweeps. +/// +/// **This is a floor, not a recommendation.** It is adequate for small +/// histories and is quickly outgrown: a history of 400 events over 100 +/// competitors already stops here with a final step of ~7e-3 against the 1e-6 +/// default tolerance — four orders of magnitude short — and a dense joint model +/// of ~2,000 nodes over ~3,300 events has been measured needing 76 to 161. +/// +/// Overrunning it is not an error, and deliberately so: `converge` returns a +/// [`ConvergenceReport`] whose `converged` flag says what happened. But a fit +/// that stopped short is *wrong by a little*, which is the worst available +/// failure — every rating is finite and ordered sensibly, and nothing in the +/// numbers themselves says they were still moving. Read the report; the type is +/// `#[must_use]` for that reason. +/// +/// Raise it via [`ConvergenceOptions`]. Convergence cost is roughly linear in +/// the cap, and for anything but a toy the extra sweeps are milliseconds. pub const ITERATIONS: usize = 30; /// Largest team count `History::predict_outcome` will enumerate. diff --git a/tests/api_shape.rs b/tests/api_shape.rs index 0331be5..6a56e0d 100644 --- a/tests/api_shape.rs +++ b/tests/api_shape.rs @@ -65,7 +65,7 @@ fn add_events_draw() { outcome: Outcome::draw(2), }]; h.add_events(events).unwrap(); - h.converge().unwrap(); + let _ = h.converge().unwrap(); } #[test] @@ -123,7 +123,7 @@ fn fluent_event_builder_winner_convenience() { .winner(0) .commit() .unwrap(); - h.converge().unwrap(); + let _ = h.converge().unwrap(); } #[test] @@ -141,7 +141,7 @@ fn fluent_event_builder_draw() { .draw() .commit() .unwrap(); - h.converge().unwrap(); + let _ = h.converge().unwrap(); } #[test] @@ -155,7 +155,7 @@ fn current_skill_and_learning_curve() { .build(); h.record_winner(&"a", &"b", 1).unwrap(); h.record_winner(&"a", &"b", 2).unwrap(); - h.converge().unwrap(); + let _ = h.converge().unwrap(); let a = h.current_skill(&"a").unwrap(); assert!(a.mu() > 25.0); @@ -201,7 +201,7 @@ fn predict_quality_two_teams() { .p_draw(0.0) .build(); h.record_winner(&"a", &"b", 1).unwrap(); - h.converge().unwrap(); + let _ = h.converge().unwrap(); let q = h.predict_quality(&[&[&"a"], &[&"b"]]).unwrap(); assert!(q > 0.0 && q <= 1.0); @@ -217,7 +217,7 @@ fn predict_outcome_two_teams_sums_to_one() { .p_draw(0.0) .build(); h.record_winner(&"a", &"b", 1).unwrap(); - h.converge().unwrap(); + let _ = h.converge().unwrap(); let p = h.predict_outcome(&[&[&"a"], &[&"b"]]).unwrap(); let wins = p.win_probabilities(); @@ -245,7 +245,7 @@ fn fluent_event_builder_scores() { .scores([12.0, 4.0]) .commit() .unwrap(); - h.converge().unwrap(); + let _ = h.converge().unwrap(); let a = h.current_skill(&"alice").unwrap(); let b = h.current_skill(&"bob").unwrap(); diff --git a/tests/competitor_config.rs b/tests/competitor_config.rs index 468d580..ba0cc0f 100644 --- a/tests/competitor_config.rs +++ b/tests/competitor_config.rs @@ -64,13 +64,13 @@ fn a_prior_applies_to_a_new_competitor() { let mut with = history(); with.add_events(vec![bout("a", "b", 0, Some(seeded), None)]) .unwrap(); - with.converge().unwrap(); + let _ = with.converge().unwrap(); let mut without = history(); without .add_events(vec![bout("a", "b", 0, None, None)]) .unwrap(); - without.converge().unwrap(); + let _ = without.converge().unwrap(); assert!( (skill_of(&with, "a").mu() - skill_of(&without, "a").mu()).abs() > 1.0, @@ -91,7 +91,7 @@ fn a_prior_applies_to_a_competitor_the_history_already_knows() { // "a" now exists. Configuring it here used to do nothing whatsoever. late.add_events(vec![bout("a", "b", 1, Some(seeded), None)]) .unwrap(); - late.converge().unwrap(); + let _ = late.converge().unwrap(); let mut never = history(); never @@ -100,7 +100,7 @@ fn a_prior_applies_to_a_competitor_the_history_already_knows() { bout("a", "b", 1, None, None), ]) .unwrap(); - never.converge().unwrap(); + let _ = never.converge().unwrap(); assert!( (skill_of(&late, "a").mu() - skill_of(&never, "a").mu()).abs() > 1.0, @@ -122,7 +122,7 @@ fn a_prior_is_whole_history_scoped_not_per_event() { .unwrap(); late.add_events(vec![bout("a", "b", 1, Some(seeded), None)]) .unwrap(); - late.converge().unwrap(); + let _ = late.converge().unwrap(); let mut early = history(); early @@ -131,7 +131,7 @@ fn a_prior_is_whole_history_scoped_not_per_event() { bout("a", "b", 1, Some(seeded), None), ]) .unwrap(); - early.converge().unwrap(); + let _ = early.converge().unwrap(); let (l, e) = (skill_of(&late, "a"), skill_of(&early, "a")); assert!( @@ -150,7 +150,7 @@ fn repeating_the_same_prior_is_inert() { bout("a", "b", 1, None, None), ]) .unwrap(); - once.converge().unwrap(); + let _ = once.converge().unwrap(); let mut every_time = history(); every_time @@ -159,7 +159,7 @@ fn repeating_the_same_prior_is_inert() { bout("a", "b", 1, Some(seeded), None), ]) .unwrap(); - every_time.converge().unwrap(); + let _ = every_time.converge().unwrap(); let (o, e) = (skill_of(&once, "a"), skill_of(&every_time, "a")); assert!( @@ -203,7 +203,7 @@ fn setting_one_field_late_leaves_the_other_alone() { // Only the scale this time — the prior above must survive. h.add_events(vec![bout("a", "b", 1, None, Some(0.5))]) .unwrap(); - h.converge().unwrap(); + let _ = h.converge().unwrap(); let mut both_upfront = history(); both_upfront @@ -212,7 +212,7 @@ fn setting_one_field_late_leaves_the_other_alone() { bout("a", "b", 1, None, None), ]) .unwrap(); - both_upfront.converge().unwrap(); + let _ = both_upfront.converge().unwrap(); let (a, b) = (skill_of(&h, "a"), skill_of(&both_upfront, "a")); assert!( diff --git a/tests/degenerate_inputs.rs b/tests/degenerate_inputs.rs index 667999a..3c783b2 100644 --- a/tests/degenerate_inputs.rs +++ b/tests/degenerate_inputs.rs @@ -351,7 +351,7 @@ fn zero_weight_does_not_produce_a_non_finite_posterior() { .commit() .expect("a zero weight is accepted today; update this test if that changes"); - h.converge().unwrap(); + let _ = h.converge().unwrap(); assert_curve_finite(&h, &["a", "b"], "zero weight"); } @@ -368,7 +368,7 @@ fn negative_weight_does_not_produce_a_non_finite_posterior() { .commit() .expect("a negative weight is accepted today; update this test if that changes"); - h.converge().unwrap(); + let _ = h.converge().unwrap(); assert_curve_finite(&h, &["a", "b"], "negative weight"); } @@ -389,7 +389,7 @@ fn out_of_order_timestamps_converge_to_the_same_answer() { h.record_winner(&"a", &"b", time).unwrap(); } - h.converge().unwrap(); + let _ = h.converge().unwrap(); h } @@ -416,7 +416,7 @@ fn extreme_beta_and_sigma_stay_finite() { h.record_winner(&"a", &"b", 1).unwrap(); h.record_winner(&"a", &"b", 2).unwrap(); - h.converge().unwrap(); + let _ = h.converge().unwrap(); assert_curve_finite(&h, &["a", "b"], &format!("beta={beta} sigma={sigma}")); } diff --git a/tests/determinism.rs b/tests/determinism.rs index ce0ebae..006f25b 100644 --- a/tests/determinism.rs +++ b/tests/determinism.rs @@ -47,7 +47,7 @@ fn build_and_converge(seed: u64) -> Vec<(i64, trueskill_tt::Gaussian)> { }); } h.add_events(events).unwrap(); - h.converge().unwrap(); + let _ = h.converge().unwrap(); // Sample one competitor's curve for the comparison. h.learning_curve("p0") } diff --git a/tests/drift_scale.rs b/tests/drift_scale.rs index ff60bb8..50d8904 100644 --- a/tests/drift_scale.rs +++ b/tests/drift_scale.rs @@ -58,7 +58,7 @@ fn fit(events: Vec>, gamma: f64) -> Fit { .build(); h.add_events(events).unwrap(); - h.converge().unwrap(); + let _ = h.converge().unwrap(); h } @@ -385,7 +385,7 @@ fn drift_scale_applies_when_set_after_first_appearance() { outcome: Outcome::winner(1, 2), }]) .unwrap(); - late.converge().unwrap(); + let _ = late.converge().unwrap(); let applied = curve(&late, "anchor"); let pinned_from_the_start = curve(&fit(distant_pair(Some(0.0)), 25.0 / 300.0), "anchor"); diff --git a/tests/filtered.rs b/tests/filtered.rs index 452f0a0..7265f09 100644 --- a/tests/filtered.rs +++ b/tests/filtered.rs @@ -47,7 +47,7 @@ fn tight() -> ConvergenceOptions { fn filtered_evidence_sits_between_coin_flip_and_batch() { let mut history = repeated_winner(5); - history.converge().unwrap(); + let _ = history.converge().unwrap(); let coin_flip = 5.0 * 0.5f64.ln(); let batch = history.log_evidence(); @@ -71,7 +71,7 @@ fn filtered_evidence_sits_between_coin_flip_and_batch() { fn filtered_first_point_is_less_certain_than_smoothed() { let mut history = repeated_winner(12); - history.converge().unwrap(); + let _ = history.converge().unwrap(); let smoothed = history.learning_curve("a"); let filtered = history.filtered_learning_curve("a"); @@ -121,7 +121,7 @@ fn filtered_first_point_is_less_certain_than_smoothed() { fn filtered_curves_plural_agrees_with_singular() { let mut history = repeated_winner(4); - history.converge().unwrap(); + let _ = history.converge().unwrap(); let curves = history.filtered_learning_curves(); @@ -180,7 +180,7 @@ fn single_slice_filtered_matches_smoothed() { ]) .unwrap(); - history.converge().unwrap(); + let _ = history.converge().unwrap(); let smoothed = history.learning_curve("a"); let filtered = history.filtered_learning_curve("a"); @@ -223,13 +223,13 @@ fn filtered_curves_do_not_depend_on_ingestion_order() { let mut batched = History::builder().convergence(tight()).build(); batched.add_events(all.clone()).unwrap(); - batched.converge().unwrap(); + let _ = batched.converge().unwrap(); let mut incremental = History::builder().convergence(tight()).build(); for event in all { incremental.add_events([event]).unwrap(); } - incremental.converge().unwrap(); + let _ = incremental.converge().unwrap(); let from_batched = batched.filtered_learning_curve("a"); let from_incremental = incremental.filtered_learning_curve("a"); diff --git a/tests/large_history_converges_finite.rs b/tests/large_history_converges_finite.rs index 98a5cc7..30e6d24 100644 --- a/tests/large_history_converges_finite.rs +++ b/tests/large_history_converges_finite.rs @@ -46,7 +46,7 @@ fn nan_after_fit(players: usize) -> usize { let (w, l) = if rng.coin() { (a, b) } else { (b, a) }; h.record_winner(&ids[w], &ids[l], 0).unwrap(); } - h.converge().unwrap(); + let _ = h.converge().unwrap(); ids.iter() .filter(|id| { diff --git a/tests/observer.rs b/tests/observer.rs index cd6adef..a6295c9 100644 --- a/tests/observer.rs +++ b/tests/observer.rs @@ -42,7 +42,7 @@ fn every_observer_callback_fires() { h.record_winner(&"a", &"b", 1).unwrap(); h.record_winner(&"b", &"c", 2).unwrap(); h.record_winner(&"c", &"a", 3).unwrap(); - h.converge().unwrap(); + let _ = h.converge().unwrap(); assert!( !recorder.iterations.lock().unwrap().is_empty(), @@ -65,7 +65,7 @@ fn slice_callbacks_report_the_slice_they_swept() { h.record_winner(&"a", &"b", 10).unwrap(); h.record_winner(&"a", &"b", 20).unwrap(); - h.converge().unwrap(); + let _ = h.converge().unwrap(); let slices = recorder.slices.lock().unwrap(); @@ -93,7 +93,7 @@ fn a_single_slice_history_still_reports_its_sweep() { let mut h = History::builder().observer(Arc::clone(&recorder)).build(); h.record_winner(&"a", &"b", 1).unwrap(); - h.converge().unwrap(); + let _ = h.converge().unwrap(); let slices = recorder.slices.lock().unwrap(); assert!( @@ -112,7 +112,7 @@ fn a_shared_observer_reaches_the_callers_handle() { let mut h = History::builder().observer(Arc::clone(&recorder)).build(); h.record_winner(&"a", &"b", 1).unwrap(); - h.converge().unwrap(); + let _ = h.converge().unwrap(); assert!(!recorder.iterations.lock().unwrap().is_empty()); assert!(!recorder.slices.lock().unwrap().is_empty()); @@ -125,12 +125,12 @@ fn a_trait_object_observer_works() { let boxed: Box> = Box::new(Recorder::default()); let mut h = History::builder().observer(boxed).build(); h.record_winner(&"a", &"b", 1).unwrap(); - h.converge().unwrap(); + let _ = h.converge().unwrap(); let shared: Arc> = Arc::new(Recorder::default()); let mut h = History::builder().observer(Arc::clone(&shared)).build(); h.record_winner(&"a", &"b", 1).unwrap(); - h.converge().unwrap(); + let _ = h.converge().unwrap(); } /// A non-shared observer can be reclaimed after convergence instead. @@ -138,7 +138,7 @@ fn a_trait_object_observer_works() { fn into_observer_returns_the_accumulated_state() { let mut h = History::builder().observer(Recorder::default()).build(); h.record_winner(&"a", &"b", 1).unwrap(); - h.converge().unwrap(); + let _ = h.converge().unwrap(); // Readable in place... assert!(!h.observer().iterations.lock().unwrap().is_empty()); @@ -155,7 +155,7 @@ fn a_borrowed_observer_works() { { let mut h = History::builder().observer(&recorder).build(); h.record_winner(&"a", &"b", 1).unwrap(); - h.converge().unwrap(); + let _ = h.converge().unwrap(); } assert!(!recorder.iterations.lock().unwrap().is_empty()); } diff --git a/tests/prediction.rs b/tests/prediction.rs index b67573c..8a7b31f 100644 --- a/tests/prediction.rs +++ b/tests/prediction.rs @@ -9,7 +9,7 @@ fn history_with(names: &[&'static str], p_draw: f64) -> History { for pair in names.windows(2) { h.record_winner(&pair[0], &pair[1], 1).unwrap(); } - h.converge().unwrap(); + let _ = h.converge().unwrap(); h } @@ -20,7 +20,14 @@ fn unknown_keys_are_reported_not_silently_dropped() { let err = h .predict_outcome(&[&[&"a"], &[&"ghost"]]) .expect_err("an unknown key must not yield a confident prediction"); - assert_eq!(err, InferenceError::UnknownKey { team: 1, member: 0 }); + assert_eq!( + err, + InferenceError::UnknownKey { + team: 1, + member: 0, + key: "\"ghost\"".to_owned(), + } + ); // Every prediction entry point, not just one. assert!( @@ -35,7 +42,14 @@ fn unknown_keys_are_reported_not_silently_dropped() { fn an_entirely_unknown_team_is_an_error() { let h = history_with(&["a", "b"], 0.0); let err = h.predict_outcome(&[&[&"a"], &[&"x", &"y"]]).unwrap_err(); - assert_eq!(err, InferenceError::UnknownKey { team: 1, member: 0 }); + assert_eq!( + err, + InferenceError::UnknownKey { + team: 1, + member: 0, + key: "\"x\"".to_owned(), + } + ); } #[test] @@ -184,7 +198,7 @@ fn the_stronger_competitor_is_favoured() { for t in 1..=10 { h.record_winner(&"strong", &"weak", t).unwrap(); } - h.converge().unwrap(); + let _ = h.converge().unwrap(); let p = h.predict_outcome(&[&[&"strong"], &[&"weak"]]).unwrap(); let (best, _) = p.most_likely().expect("a most likely outcome"); @@ -206,7 +220,7 @@ fn team_size_affects_the_prediction() { .winner(0) .commit() .unwrap(); - h.converge().unwrap(); + let _ = h.converge().unwrap(); let p = h.predict_outcome(&[&[&"a", &"b"], &[&"c"]]).unwrap(); assert!((p.total() - 1.0).abs() < 1e-6, "total = {}", p.total()); @@ -229,7 +243,7 @@ fn information_gain_prefers_the_uncertain_pairing() { h.record_winner(&"rival", &"known", t + 100).unwrap(); } h.record_winner(&"known", &"newcomer", 500).unwrap(); - h.converge().unwrap(); + let _ = h.converge().unwrap(); let settled = h .expected_information_gain(&[&[&"known"], &[&"rival"]]) @@ -271,7 +285,11 @@ fn information_gain_reports_unknown_keys() { assert_eq!( h.expected_information_gain(&[&[&"a"], &[&"ghost"]]) .unwrap_err(), - InferenceError::UnknownKey { team: 1, member: 0 } + InferenceError::UnknownKey { + team: 1, + member: 0, + key: "\"ghost\"".to_owned(), + } ); } @@ -289,3 +307,33 @@ fn information_gain_accounts_for_draws() { let dist = with_draws.predict_outcome(&[&[&"a"], &[&"b"]]).unwrap(); assert!(dist.probability_of(&[0, 0]) > 0.0); } + +/// The defect that cost a consumer a day: `UnknownKey { team: 0, member: 0 }` +/// says nothing about *which* key is unknown, so the natural handling — log it, +/// fall back to a neutral value — converts a total miss into a plausible +/// constant. The key has to be in the error, and in its `Display`. +#[test] +fn unknown_key_names_the_key_it_could_not_find() { + let h = history_with(&["a", "b"], 0.0); + let err = h.predict_outcome(&[&[&"a"], &[&"never_seen"]]).unwrap_err(); + + match &err { + InferenceError::UnknownKey { key, .. } => { + assert!( + key.contains("never_seen"), + "the error should name the key, got {key}" + ); + } + other => panic!("expected UnknownKey, got {other:?}"), + } + + let rendered = err.to_string(); + assert!( + rendered.contains("never_seen"), + "Display should name the key: {rendered}" + ); + assert!( + rendered.contains("pre-filter"), + "Display should say what to do about it: {rendered}" + ); +} diff --git a/tests/properties.rs b/tests/properties.rs index 7db9a5a..91ec38d 100644 --- a/tests/properties.rs +++ b/tests/properties.rs @@ -61,7 +61,7 @@ proptest! { fn converged_posteriors_are_always_finite(games in pairs()) { let mut h = history_from(&games); - h.converge().unwrap(); + let _ = h.converge().unwrap(); for key in KEYS { for (time, g) in h.learning_curve(key) { @@ -79,7 +79,7 @@ proptest! { fn log_evidence_is_a_finite_log_probability(games in pairs()) { let mut h = history_from(&games); - h.converge().unwrap(); + let _ = h.converge().unwrap(); let batch = h.log_evidence(); let filtered = h.filtered_log_evidence(); @@ -98,7 +98,7 @@ proptest! { let before = h.filtered_log_evidence(); - h.converge().unwrap(); + let _ = h.converge().unwrap(); let after = h.filtered_log_evidence(); @@ -114,7 +114,7 @@ proptest! { fn ingestion_order_does_not_change_the_answer(games in pairs()) { let batched = { let mut h = history_from(&games); - h.converge().unwrap(); + let _ = h.converge().unwrap(); h }; @@ -139,7 +139,7 @@ proptest! { .unwrap(); } - h.converge().unwrap(); + let _ = h.converge().unwrap(); h }; diff --git a/tests/quality.rs b/tests/quality.rs index 0fb138e..4b2570d 100644 --- a/tests/quality.rs +++ b/tests/quality.rs @@ -108,7 +108,7 @@ fn history_predict_quality_supports_three_teams() { let mut h = History::default(); h.record_winner(&"a", &"b", 1).unwrap(); h.record_winner(&"b", &"c", 2).unwrap(); - h.converge().unwrap(); + let _ = h.converge().unwrap(); let q = h.predict_quality(&[&[&"a"], &[&"b"], &[&"c"]]).unwrap(); assert!( diff --git a/tests/record_winner.rs b/tests/record_winner.rs index 659cccc..d040d62 100644 --- a/tests/record_winner.rs +++ b/tests/record_winner.rs @@ -15,7 +15,7 @@ fn record_winner_builds_history() { .build(); h.record_winner(&"alice", &"bob", 1).unwrap(); - h.converge().unwrap(); + let _ = h.converge().unwrap(); let a_idx = h.lookup(&"alice").unwrap(); let b_idx = h.lookup(&"bob").unwrap(); @@ -48,7 +48,7 @@ fn record_draw_with_p_draw_set() { .build(); h.record_draw(&"alice", &"bob", 1).unwrap(); - h.converge().unwrap(); + let _ = h.converge().unwrap(); assert!(h.lookup(&"alice").is_some()); assert!(h.lookup(&"bob").is_some());