trueskill-tt/tests/joint_handle.rs

//! `History::joint` factorises once and answers many questions.
//!
//! The contract that matters is *identity*: a `Joint` must return exactly what
//! the one-shot call returns, bit for bit. A faster path that quietly disagreed
//! with the slow one would be worse than no fast path — a caller would get
//! different numbers depending on how many questions they happened to ask.

use smallvec::smallvec;
use trueskill_tt::{
    ConstantDrift, ConvergenceOptions, Event, History, InferenceError, Member, Outcome, Team,
    UnknownKeys,
};

type H = History;

fn duel(a: &'static str, b: &'static str, t: i64, sa: f64, sb: f64) -> Event<i64, &'static str> {
    Event {
        time: t,
        teams: smallvec![
            Team::with_members([Member::new(a)]),
            Team::with_members([Member::new(b)]),
        ],
        outcome: Outcome::scores([sa, sb]),
    }
}

fn ranked(a: &'static str, b: &'static str, t: i64) -> Event<i64, &'static str> {
    Event {
        time: t,
        teams: smallvec![
            Team::with_members([Member::new(a)]),
            Team::with_members([Member::new(b)]),
        ],
        outcome: Outcome::winner(0, 2),
    }
}

fn history(unknown: UnknownKeys) -> H {
    History::builder()
        .mu(0.0)
        .sigma(6.0)
        .beta(1.0)
        .score_sigma(2.0)
        .drift(ConstantDrift::new(0.5))
        .unknown_keys(unknown)
        .convergence(ConvergenceOptions {
            max_iter: 20_000,
            epsilon: 1e-13,
            alpha: 1.0,
        })
        .build()
}

/// Several slices, competitors with different last appearances, so `latest`
/// and `at_slice` both have work to do.
fn fitted(unknown: UnknownKeys) -> H {
    let mut h = history(unknown);
    h.add_events(vec![
        duel("a", "b", 1, 5.0, 2.0),
        duel("c", "d", 1, 3.0, 3.5),
        duel("a", "c", 2, 6.0, 1.0),
        duel("b", "d", 3, 4.0, 3.0),
        duel("a", "d", 4, 7.0, 2.0),
        duel("b", "c", 5, 2.0, 4.0),
    ])
    .unwrap();
    let report = h.converge().unwrap();
    assert!(report.converged, "fixture must converge");
    h
}

const PAIRS: [(&str, &str); 6] = [
    ("a", "b"),
    ("a", "c"),
    ("a", "d"),
    ("b", "c"),
    ("b", "d"),
    ("c", "d"),
];

/// A joint reused across questions answers exactly what a fresh one per
/// question does. That is the whole correctness claim behind caching the
/// factorisation (#51); it used to be checked against the `History` one-shot
/// wrappers, which were deleted in #78, so it is checked against a fresh
/// factorisation instead — the same comparison, without the wrapper.
#[test]
fn a_reused_joint_answers_exactly_what_a_fresh_one_does() {
    let h = fitted(UnknownKeys::Reject);
    let joint = h.joint().unwrap();

    for (a, b) in PAIRS {
        let terms = [(&a, 1.0), (&b, -1.0)];
        let one_shot = h.joint().unwrap().posterior_of(&terms).unwrap();
        let cached = joint.posterior_of(&terms).unwrap();
        assert_eq!(one_shot.mu(), cached.mu(), "{a} - {b}");
        assert_eq!(one_shot.variance(), cached.variance(), "{a} - {b}");
    }
}

#[test]
fn a_joint_agrees_at_a_pinned_time_too() {
    let h = fitted(UnknownKeys::Reject);
    let joint = h.joint().unwrap();

    for time in 1..=5 {
        for (a, b) in PAIRS {
            let terms = [(&a, 1.0), (&b, -1.0)];
            let one_shot = h.joint().unwrap().posterior_of_at(time, &terms);
            let cached = joint.posterior_of_at(time, &terms);
            match (one_shot, cached) {
                (Ok(x), Ok(y)) => {
                    assert_eq!(x.mu(), y.mu(), "t={time} {a} - {b}");
                    assert_eq!(x.variance(), y.variance(), "t={time} {a} - {b}");
                }
                (Err(x), Err(y)) => assert_eq!(x, y, "t={time} {a} - {b}"),
                (x, y) => panic!("t={time} {a} - {b}: disagreed on success: {x:?} vs {y:?}"),
            }
        }
    }
}

#[test]
fn a_joint_scores_candidate_matchups_identically() {
    let h = fitted(UnknownKeys::Reject);
    let joint = h.joint().unwrap();
    let (a, b) = ("a", "b");
    let target = [(&a, 1.0), (&b, -1.0)];

    for (x, y) in PAIRS {
        let teams: [&[&&str]; 2] = [&[&x], &[&y]];
        let one_shot = h
            .joint()
            .unwrap()
            .expected_variance_reduction(&teams, &target)
            .unwrap();
        let cached = joint.expected_variance_reduction(&teams, &target).unwrap();
        assert_eq!(one_shot, cached, "{x} vs {y}");
    }
}

/// The whole point: a competitor appears once per slice, so the joint is over
/// appearances rather than competitors, and a caller sizing a batch needs to
/// know which.
#[test]
fn variables_counts_appearances_not_competitors() {
    let h = fitted(UnknownKeys::Reject);
    let joint = h.joint().unwrap();
    // Four competitors, twelve appearances across five slices, all with
    // positive drift between them, so no two collapse.
    assert_eq!(joint.variables(), 12);
}

/// How much the collapse is worth, which is the part a caller has to plan
/// around: a drift-free competitor contributes **one** variable however long
/// the history, so the same events at `gamma = 0` and `gamma > 0` differ by
/// roughly the slice count in problem size — and by its cube in solve time.
///
/// Reported by a consumer as an 8x difference in solve time on a ~2,000-node,
/// 76-slice model (787 ms career against 6,214 ms drifting). This pins the
/// mechanism behind that so a change to the collapse rule cannot quietly
/// remove it.
#[test]
fn drift_free_competitors_shrink_the_joint_by_the_slice_count() {
    fn variables(gamma: f64) -> usize {
        let mut h = History::builder()
            .mu(0.0)
            .sigma(6.0)
            .beta(1.0)
            .score_sigma(2.0)
            .drift(ConstantDrift::new(gamma))
            .convergence(ConvergenceOptions {
                max_iter: 20_000,
                epsilon: 1e-13,
                alpha: 1.0,
            })
            .build();
        h.add_events(
            (1..=10)
                .map(|t| duel("a", "b", t, 5.0, 2.0))
                .collect::<Vec<_>>(),
        )
        .unwrap();
        let _ = h.converge().unwrap();
        h.joint().unwrap().variables()
    }

    let drifting = variables(0.5);
    let career = variables(0.0);

    // Two competitors over ten slices: twenty appearances, or two variables.
    assert_eq!(drifting, 20);
    assert_eq!(career, 2);
    assert_eq!(
        drifting / career,
        10,
        "collapse should track the slice count"
    );
}

/// With `drift = 0` consecutive appearances are the same latent variable, so
/// the joint is smaller than the appearance count.
#[test]
fn pinned_competitors_collapse_consecutive_appearances() {
    let mut h = History::builder()
        .mu(0.0)
        .sigma(6.0)
        .beta(1.0)
        .score_sigma(2.0)
        .drift(ConstantDrift::new(0.0))
        .convergence(ConvergenceOptions {
            max_iter: 20_000,
            epsilon: 1e-13,
            alpha: 1.0,
        })
        .build();
    h.add_events(vec![
        duel("a", "b", 1, 5.0, 2.0),
        duel("a", "b", 2, 4.0, 3.0),
        duel("a", "b", 3, 6.0, 1.0),
    ])
    .unwrap();
    assert!(h.converge().unwrap().converged);
    assert_eq!(h.joint().unwrap().variables(), 2);
}

#[test]
fn a_ranked_history_has_no_exact_joint() {
    let mut h = history(UnknownKeys::Reject);
    h.add_events(vec![duel("a", "b", 1, 5.0, 2.0), ranked("a", "b", 2)])
        .unwrap();
    let _ = h.converge().unwrap();
    assert!(matches!(
        h.joint().unwrap_err(),
        InferenceError::JointRequiresScoredEvents
    ));
}

/// Distinguishable from the ranked case, which is the point of splitting
/// `JointUnavailable { reason: &str }` into three variants (#74): "add events"
/// and "use predict_win_probabilities" are different instructions, and telling
/// them apart used to mean matching on English prose.
#[test]
fn an_empty_history_has_no_joint() {
    let h = history(UnknownKeys::Reject);
    assert!(matches!(
        h.joint().unwrap_err(),
        InferenceError::EmptyHistory
    ));
}

/// Unknown keys are decided per query, not when the joint is factorised — the
/// factorisation does not depend on the question.
#[test]
fn unknown_keys_are_rejected_per_query() {
    let h = fitted(UnknownKeys::Reject);
    let joint = h.joint().unwrap();
    let (a, z) = ("a", "nobody");
    assert!(matches!(
        joint.posterior_of(&[(&a, 1.0), (&z, -1.0)]).unwrap_err(),
        InferenceError::UnknownKey { .. }
    ));
    // The handle is still usable afterwards.
    let b = "b";
    assert!(joint.posterior_of(&[(&a, 1.0), (&b, -1.0)]).is_ok());
}

/// Under `Prior`, an unseen competitor is independent of everything in the
/// history, and a reused joint must add the same prior variance a fresh one
/// does.
#[test]
fn unseen_competitors_match_a_fresh_factorisation() {
    let h = fitted(UnknownKeys::Prior);
    let joint = h.joint().unwrap();
    let (a, z) = ("a", "nobody");
    let terms = [(&a, 1.0), (&z, -1.0)];
    let one_shot = h.joint().unwrap().posterior_of(&terms).unwrap();
    let cached = joint.posterior_of(&terms).unwrap();
    assert_eq!(one_shot.mu(), cached.mu());
    assert_eq!(one_shot.variance(), cached.variance());
}

/// A drift too small to represent must collapse, not corrupt the matrix.
///
/// The collapse rule used to fire only at `drift <= 0.0` exactly. Anything
/// smaller-but-positive got an explicit `1.0 / drift` precision, and at
/// `drift = 1e-16` that entry is `1e16` — so `1e16 + 0.28` rounds back to
/// `1e16` and the prior and contrasts are annihilated in the stored `f64`.
///
/// Measured before the fix, at `drift_scale = 1e-10` this returned a variance
/// **12 000x too small** (a 111x overconfident interval) as `Ok`, with a band
/// just above it returning a misleading `JointUnavailable`.
#[test]
fn a_drift_too_small_to_represent_collapses_rather_than_corrupting() {
    fn variance(scale: f64) -> f64 {
        let mut h: History<String> = History::builder()
            .key_type::<String>()
            .mu(0.0)
            .sigma(6.0)
            .beta(1.0)
            .score_sigma(2.0)
            .drift(ConstantDrift::new(0.5))
            .convergence(ConvergenceOptions {
                max_iter: 20_000,
                epsilon: 1e-13,
                alpha: 1.0,
            })
            .build();
        let mut events = Vec::new();
        for t in 0..15i64 {
            for k in 0..4usize {
                let x = format!("p{}", (t as usize * 4 + k) % 8);
                let y = format!("p{}", (t as usize * 4 + k + 3) % 8);
                events.push(Event {
                    time: t,
                    teams: smallvec![
                        Team::with_members([Member::new(x).with_drift_scale(scale)]),
                        Team::with_members([Member::new(y).with_drift_scale(scale)]),
                    ],
                    outcome: Outcome::scores([3.0, 1.0]),
                });
            }
        }
        h.add_events(events).unwrap();
        assert!(h.converge().unwrap().converged);
        let (a, b) = ("p0".to_string(), "p1".to_string());
        let joint = h
            .joint()
            .expect("a tiny drift must not make the joint unavailable");
        let g = joint.posterior_of(&[(&a, 1.0), (&b, -1.0)]).unwrap();
        g.sigma() * g.sigma()
    }

    let collapsed = variance(0.0);

    // Below the threshold every scale must reach the collapsed answer exactly,
    // and none may error.
    for scale in [1e-3, 1e-4, 1e-6, 1e-8, 1e-10, 1e-12] {
        let v = variance(scale);
        assert_eq!(
            v.to_bits(),
            collapsed.to_bits(),
            "drift_scale {scale:e}: {v} vs collapsed {collapsed}"
        );
    }

    // Above it, real drift is still modelled — otherwise this test would pass
    // by collapsing everything.
    let drifting = variance(1e-2);
    assert!(
        (drifting - collapsed).abs() / collapsed > 1e-5,
        "a drift of 1e-2 must still move the answer: {drifting} vs {collapsed}"
    );
}