Rate games accounting for first move advantage (fix #6818)

modules/puzzle/src/main/PuzzleFinisher.scala

@@ -205,11 +205,12 @@ final private[puzzle] class PuzzleFinisher(
     colls.puzzle.map(_.incFieldUnchecked($id(puzzleId), Puzzle.BSONFields.plays))
 
   private def updateRatings(u1: glicko2.Rating, u2: glicko2.Rating, win: PuzzleWin): Unit =
-    val results = glicko2.GameRatingPeriodResults(
+    val ratings = Set(u1, u2)
+    val results = glicko2.BinaryRatingPeriodResults(
       List(
-        if win.yes then glicko2.GameResult(u1, u2, false)
-        else glicko2.GameResult(u2, u1, false)
+        if win.yes then glicko2.BinaryResult(u1, u2, false)
+        else glicko2.BinaryResult(u2, u1, false)
       )
     )
-    try calculator.updateRatings(results)
+    try calculator.updateRatings(ratings, results)
     catch case e: Exception => logger.error("finisher", e)

modules/rating/src/main/Glicko.scala

@@ -6,6 +6,7 @@ import lila.core.perf.Perf
 import lila.core.rating.Glicko
 import lila.db.BSON
 import lila.rating.PerfExt.*
+import lila.rating.glicko2.ColorAdvantage
 
 object GlickoExt:
 
@@ -80,10 +81,12 @@ object Glicko:
   // rating that can be lost or gained with a single game
   val maxRatingDelta = 700
 
-  val system = glicko2.RatingCalculator(glicko2.Tau.default, ratingPeriodsPerDay)
+  val calculator = glicko2.RatingCalculator(glicko2.Tau.default, ratingPeriodsPerDay)
+  def calculatorWithAdvantage(advantage: ColorAdvantage) =
+    glicko2.RatingCalculator(glicko2.Tau.default, ratingPeriodsPerDay, advantage)
 
   def liveDeviation(p: Perf, reverse: Boolean): Double = {
-    system.previewDeviation(p.toRating, nowInstant, reverse)
+    calculator.previewDeviation(p.toRating, nowInstant, reverse)
   }.atLeast(minDeviation).atMost(maxDeviation)
 
   given glickoHandler: BSONDocumentHandler[Glicko] = new BSON[Glicko]:

modules/rating/src/main/glicko2/Rating.scala

@@ -21,6 +21,10 @@ final class Rating(
     */
   def getGlicko2Rating: Double = convertRatingToGlicko2Scale(this.rating)
 
+  def getGlicko2RatingWithAdvantage(advantage: ColorAdvantage): Double = convertRatingToGlicko2Scale(
+    this.rating + advantage.value
+  )
+
   /** Set the average skill value, taking in a value in Glicko2 scale.
     */
   def setGlicko2Rating(r: Double) =

modules/rating/src/main/glicko2/RatingCalculator.scala

@@ -5,6 +5,13 @@ opaque type Tau = Double
 object Tau extends OpaqueDouble[Tau]:
   val default: Tau = 0.75d
 
+opaque type ColorAdvantage = Double
+object ColorAdvantage extends OpaqueDouble[ColorAdvantage]:
+  val zero: ColorAdvantage                                 = 0d
+  val standard: ColorAdvantage                             = 7.786d
+  val crazyhouse: ColorAdvantage                           = 15.171d
+  extension (c: ColorAdvantage) def negate: ColorAdvantage = -c
+
 opaque type RatingPeriodsPerDay = Double
 object RatingPeriodsPerDay extends OpaqueDouble[RatingPeriodsPerDay]:
   val default: RatingPeriodsPerDay = 0d
@@ -29,7 +36,8 @@ object RatingCalculator:
 
 final class RatingCalculator(
     tau: Tau = Tau.default,
-    ratingPeriodsPerDay: RatingPeriodsPerDay = RatingPeriodsPerDay.default
+    ratingPeriodsPerDay: RatingPeriodsPerDay = RatingPeriodsPerDay.default,
+    advantage: ColorAdvantage = ColorAdvantage.zero
 ):
 
   import RatingCalculator.*
@@ -41,15 +49,17 @@ final class RatingCalculator(
 
   private val ratingPeriodsPerMilli: Double = ratingPeriodsPerDay.value * DAYS_PER_MILLI
 
-  /** <p>Run through all players within a resultset and calculate their new ratings.</p> <p>Players within the
-    * resultset who did not compete during the rating period will have see their deviation increase (in line
-    * with Prof Glickman's paper).</p> <p>Note that this method will clear the results held in the association
-    * resultset.</p>
+  /** Run through all players within a resultset and calculate their new ratings. Players within the resultset
+    * who did not compete during the rating period will have see their deviation increase (in line with Prof
+    * Glickman's paper). Note that this method will clear the results held in the association resultset.
     *
     * @param results
     */
-  def updateRatings(results: RatingPeriodResults[?], skipDeviationIncrease: Boolean = false) =
-    val players = results.getParticipants
+  def updateRatings(
+      players: Iterable[Rating],
+      results: RatingPeriodResults[?],
+      skipDeviationIncrease: Boolean = false
+  ) =
     players.foreach { player =>
       val elapsedRatingPeriods = if skipDeviationIncrease then 0 else 1
       if results.getResults(player).sizeIs > 0 then
@@ -175,13 +185,17 @@ final class RatingCalculator(
     for result <- results do
       v = v + ((Math.pow(g(result.getOpponent(player).getGlicko2RatingDeviation), 2))
         * E(
-          player.getGlicko2Rating,
-          result.getOpponent(player).getGlicko2Rating,
+          player.getGlicko2RatingWithAdvantage(result.getAdvantage(advantage, player)),
+          result
+            .getOpponent(player)
+            .getGlicko2RatingWithAdvantage(result.getAdvantage(advantage, player).negate),
           result.getOpponent(player).getGlicko2RatingDeviation
         )
         * (1.0 - E(
-          player.getGlicko2Rating,
-          result.getOpponent(player).getGlicko2Rating,
+          player.getGlicko2RatingWithAdvantage(result.getAdvantage(advantage, player)),
+          result
+            .getOpponent(player)
+            .getGlicko2RatingWithAdvantage(result.getAdvantage(advantage, player).negate),
           result.getOpponent(player).getGlicko2RatingDeviation
         )))
     1 / v
@@ -202,8 +216,10 @@ final class RatingCalculator(
       outcomeBasedRating = outcomeBasedRating
         + (g(result.getOpponent(player).getGlicko2RatingDeviation)
           * (result.getScore(player) - E(
-            player.getGlicko2Rating,
-            result.getOpponent(player).getGlicko2Rating,
+            player.getGlicko2RatingWithAdvantage(result.getAdvantage(advantage, player)),
+            result
+              .getOpponent(player)
+              .getGlicko2RatingWithAdvantage(result.getAdvantage(advantage, player).negate),
             result.getOpponent(player).getGlicko2RatingDeviation
           )))
     outcomeBasedRating

modules/rating/src/main/glicko2/RatingPeriodResults.scala

@@ -4,9 +4,11 @@ package lila.rating.glicko2
 trait RatingPeriodResults[R <: Result]():
   val results: List[R]
   def getResults(player: Rating): List[R] = results.filter(_.participated(player))
-  def getParticipants: Set[Rating]        = results.flatMap(_.players).toSet
 
-class GameRatingPeriodResults(val results: List[GameResult]) extends RatingPeriodResults[GameResult]
+final class BinaryRatingPeriodResults(val results: List[BinaryResult])
+    extends RatingPeriodResults[BinaryResult]
 
-class FloatingRatingPeriodResults(val results: List[FloatingResult])
+final class FloatingRatingPeriodResults(val results: List[FloatingResult])
     extends RatingPeriodResults[FloatingResult]
+
+final class GameRatingPeriodResults(val results: List[DuelResult]) extends RatingPeriodResults[DuelResult]

modules/rating/src/main/glicko2/Result.scala

@@ -1,51 +1,53 @@
 package lila.rating.glicko2
 
+import chess.Outcome
+
 trait Result:
 
-  def getScore(player: Rating): Double
+  val first: Rating
+  val second: Rating
+
+  def getAdvantage(advantage: ColorAdvantage, player: Rating): ColorAdvantage =
+    if player == first then advantage.map(_ / 2.0d) else advantage.map(_ / 2.0d).negate
 
-  def getOpponent(player: Rating): Rating
+  def getScore(player: Rating): Double
 
-  def participated(player: Rating): Boolean
+  def getOpponent(player: Rating) = if player == first then second else first
 
-  def players: List[Rating]
+  def participated(player: Rating): Boolean = player == first || player == second
 
-// score from 0 (opponent wins) to 1 (player wins)
-class FloatingResult(player: Rating, opponent: Rating, score: Float) extends Result:
+  private def players: List[Rating] = List(first, second)
 
-  def getScore(p: Rating) = if p == player then score else 1 - score
+final class BinaryResult(val first: Rating, val second: Rating, score: Boolean) extends Result:
+  private val POINTS_FOR_WIN  = 1.0d
+  private val POINTS_FOR_LOSS = 0.0d
 
-  def getOpponent(p: Rating) = if p == player then opponent else player
+  def getScore(p: Rating): Double =
+    if p == first then if score then POINTS_FOR_WIN else POINTS_FOR_LOSS
+    else if score then POINTS_FOR_LOSS
+    else POINTS_FOR_WIN
 
-  def participated(p: Rating) = p == player || p == opponent
+// ASSUME score is between unit interval [0.0d, 1.0d]
+final class FloatingResult(val first: Rating, val second: Rating, score: Double) extends Result:
+  private val ONE_HUNDRED_PCT = 1.0d
 
-  def players = List(player, opponent)
+  def getScore(p: Rating): Double =
+    if p == first then score else ONE_HUNDRED_PCT - score
 
-final class GameResult(winner: Rating, loser: Rating, isDraw: Boolean) extends Result:
+final class DuelResult(val first: Rating, val second: Rating, outcome: Outcome) extends Result:
   private val POINTS_FOR_WIN  = 1.0d
-  private val POINTS_FOR_LOSS = 0.0d
   private val POINTS_FOR_DRAW = 0.5d
-
-  def players = List(winner, loser)
-
-  def participated(player: Rating) = player == winner || player == loser
+  private val POINTS_FOR_LOSS = 0.0d
 
   /** Returns the "score" for a match.
     *
-    * @param player
     * @return
-    *   1 for a win, 0.5 for a draw and 0 for a loss
+    *   1 for a first player win, 0.5 for a draw and 0 for a first player loss
     * @throws IllegalArgumentException
     */
-  def getScore(player: Rating): Double =
-    if isDraw then POINTS_FOR_DRAW
-    else if winner == player then POINTS_FOR_WIN
-    else if loser == player then POINTS_FOR_LOSS
-    else throw new IllegalArgumentException("Player did not participate in match");
-
-  def getOpponent(player: Rating) =
-    if winner == player then loser
-    else if loser == player then winner
-    else throw new IllegalArgumentException("Player did not participate in match");
-
-  override def toString = s"$winner vs $loser = $isDraw"
+  def getScore(player: Rating): Double = outcome.winner match
+    case Some(chess.White) => if player == first then POINTS_FOR_WIN else POINTS_FOR_LOSS
+    case Some(chess.Black) => if player == first then POINTS_FOR_LOSS else POINTS_FOR_WIN
+    case _                 => POINTS_FOR_DRAW
+
+  override def toString = s"$first vs $second = $outcome"