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<i64, ConstantDrift, trueskill_tt::NullObserver, &'static str>;

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(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"),
];

#[test]
fn a_joint_answers_exactly_what_the_one_shot_call_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.posterior_of(&terms).unwrap();
        let cached = joint.posterior_of(&terms).unwrap();
        assert_eq!(one_shot.pi(), cached.pi(), "{a} - {b}");
        assert_eq!(one_shot.tau(), cached.tau(), "{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.posterior_of_at(time, &terms);
            let cached = joint.posterior_of_at(time, &terms);
            match (one_shot, cached) {
                (Ok(x), Ok(y)) => {
                    assert_eq!(x.pi(), y.pi(), "t={time} {a} - {b}");
                    assert_eq!(x.tau(), y.tau(), "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.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(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(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::JointUnavailable { .. }
    ));
}

#[test]
fn an_empty_history_has_no_joint() {
    let h = history(UnknownKeys::Reject);
    assert!(matches!(
        h.joint().unwrap_err(),
        InferenceError::JointUnavailable { .. }
    ));
}

/// 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 the cached path must add the same prior variance the one-shot
/// path does.
#[test]
fn unseen_competitors_match_the_one_shot_path() {
    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.posterior_of(&terms).unwrap();
    let cached = joint.posterior_of(&terms).unwrap();
    assert_eq!(one_shot.pi(), cached.pi());
    assert_eq!(one_shot.tau(), cached.tau());
}