#rating #statistics #player #game #competitive #elo #probability

whr

Implementation of Rémi Coulom's Whole-History Rating (WHR) algorithm for Rust

4 releases

0.2.1 Sep 21, 2024
0.2.0 Aug 31, 2024
0.1.1 Aug 30, 2024
0.1.0 Aug 30, 2024

#638 in Algorithms

Download history 156/week @ 2024-08-24 190/week @ 2024-08-31 6/week @ 2024-09-07 177/week @ 2024-09-21 13/week @ 2024-09-28

204 downloads per month

MIT/Apache

32KB
699 lines

Whole History Rating

Implementation of Rémi Coulom's Whole History Rating (WHR) algorithm as a Rust library.

It notably supports:

  • handicaps (first player advantage)
  • draws

WHR is used to rate players in competitive games, akin to the Elo or TrueSkill systems. It can estimate the probability of winning between two players even if they have never competed against one another. It is more accurate than say the Elo system, at the cost of requiring more computation.

WHR is notably used in Go, Warcraft 3, Renju, and is even used in some sports!

Future work

I hope to generalize the library further, notably by supporting:

  • games with more than two players
  • teams as was stated to be possible in Rémi Coulom's paper introducing WHR.

Installation

The library can be used in any Cargo project by running:

cargo add whr

or by adding the following to your Cargo.toml:

[dependencies]
whr = "0.1"

Exemple usage

The library works following the builder pattern.

use whr::WhrBuilder;

let whr = WhrBuilder::default()
  .with_iterations(50) // Maximum number of iterations for the algorithm to converge.
  .with_epsilon(1e-5) // Target stability between iterations
  // Register games, with:
  // - two named players,
  // - an optional winner, 
  // - a timestep,
  // - and optional handicap (first player advantage)
  .with_game("alice", "bob", Some("bob"), 1, None)
  .with_game("alice", "bob", None, 2, None)
  .with_game("bob", "alice", Some("alice"), 2, None)
  .build();

See the documentation for more parameters and information.

Benchmarks

Dependencies

~455KB