Merge pull request #89 from osu-tournament-rating/hotfix/cleanup-testing

Major cleanup and refactoring with testing and documentation improvements

Cargo.toml

@@ -30,6 +30,10 @@ strum_macros = "0.26.4"
 criterion = "0.5.1"
 tokio-postgres = { version = "0.7.11", features = ["with-chrono-0_4"] }
 postgres-types = "0.2.7"
+rand_chacha = "0.3.1"
+rand = "0.8.5"
+thiserror = "1.0.56"
+log = "0.4.22"
 
 [dev-dependencies]
 criterion = {  version = "0.5.1", features = ["html_reports"] }
@@ -40,7 +44,3 @@ unused_variables = "allow"
 
 [profile.release]
 debug = true
-
-[[bench]]
-name = "match_processing"
-harness = false

src/database/db_structs.rs

@@ -53,7 +53,7 @@ pub struct GameScore {
     pub placement: i32
 }
 
-#[derive(Debug, Clone, Serialize)]
+#[derive(Debug, Clone, Serialize, PartialEq)]
 pub struct PlayerRating {
     /// Unknown until insertion
     pub id: i32,
@@ -71,7 +71,7 @@ pub struct PlayerRating {
     pub adjustments: Vec<RatingAdjustment>
 }
 
-#[derive(Debug, Clone, Serialize)]
+#[derive(Debug, Clone, Serialize, PartialEq)]
 pub struct RatingAdjustment {
     pub player_id: i32,
     pub ruleset: Ruleset,

src/model/constants.rs

@@ -1,18 +1,55 @@
-// Model constants
-pub const MULTIPLIER: f64 = 60.0;
-pub const DEFAULT_VOLATILITY: f64 = 5.0 * MULTIPLIER;
-pub const DEFAULT_RATING: f64 = 15.0 * MULTIPLIER;
-pub const TAU: f64 = DEFAULT_VOLATILITY / 100.0;
+/// The absolute minimum rating any player can have, regardless of performance or decay
+pub const ABSOLUTE_RATING_FLOOR: f64 = 100.0;
+
+/// Beta parameter for the PlackettLuce rating model
+/// Controls how quickly ratings change based on expected vs actual performance
 pub const BETA: f64 = DEFAULT_VOLATILITY / 2.0;
-pub const KAPPA: f64 = 0.0001;
-pub const DECAY_DAYS: u64 = 121;
+
+/// Number of days a player can be inactive before their rating begins to decay
+pub const DECAY_DAYS: u64 = 121; // Approximately 4 months
+
+/// Minimum rating that any player can decay to, based on their peak rating
 pub const DECAY_MINIMUM: f64 = 15.0 * MULTIPLIER;
+
+/// Amount of rating lost per decay cycle
 pub const DECAY_RATE: f64 = 0.06 * MULTIPLIER;
-pub const ABSOLUTE_RATING_FLOOR: f64 = 100.0;
-// Default rating constants for osu!
-pub const OSU_RATING_FLOOR: f64 = MULTIPLIER * 5.0;
-pub const OSU_RATING_CEILING: f64 = MULTIPLIER * 30.0;
-pub const VOLATILITY_GROWTH_RATE: f64 = 0.08 * (MULTIPLIER * MULTIPLIER);
+
+/// Initial volatility, higher values indicate more uncertainty in the rating
+pub const DEFAULT_VOLATILITY: f64 = 5.0 * MULTIPLIER;
+
+/// Fallback default rating used when rating cannot be identified from osu! rank information
+pub const FALLBACK_RATING: f64 = 15.0 * MULTIPLIER;
+
+/// Arbitrary regularization parameter
+pub const KAPPA: f64 = 0.0001;
+
+/// Base multiplier used throughout the system to scale ratings
+/// This brings ratings into a more readable range (e.g., 900 instead of 15)
+pub const MULTIPLIER: f64 = 60.0;
+
+/// Maximum possible initial rating in the osu! ruleset
+pub const OSU_INITIAL_RATING_CEILING: f64 = MULTIPLIER * 30.0; // 1800.0
+
+/// Minimum possible initial rating in the osu! ruleset before decay
+pub const OSU_INITIAL_RATING_FLOOR: f64 = MULTIPLIER * 5.0; // 300.0
+
+/// Scaling factor applied to rating changes based on performance frequency
+/// Lower values reduce the impact of infrequent participation
 pub const PERFORMANCE_SCALING_FACTOR: f64 = 0.3;
+
+/// Tau parameter for the PlackettLuce rating model
+/// Controls the system's confidence in new ratings
+pub const TAU: f64 = DEFAULT_VOLATILITY / 100.0;
+
+/// Rate at which volatility increases during decay periods
+/// Squared due to working with variance rather than standard deviation
+pub const DECAY_VOLATILITY_GROWTH_RATE: f64 = 0.08 * (MULTIPLIER * MULTIPLIER);
+
+/// Weight applied to Method A in the final rating calculation
+/// Method A: Uses current rating for unplayed games
 pub const WEIGHT_A: f64 = 0.9;
+
+/// Weight applied to Method B in the final rating calculation
+/// Method B: Assumes last place for unplayed games
+/// Always equals 1 - WEIGHT_A to ensure weights sum to 1
 pub const WEIGHT_B: f64 = 1.0 - WEIGHT_A;