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

modules/puzzle/src/main/PuzzleFinisher.scala

@@ -78,15 +78,15 @@ final private[puzzle] class PuzzleFinisher(
                     )
                     (round, none, perf)
                 case None =>
-                  val userRating = perf.toRating
-                  val puzzleRating = glicko2.Rating(
+                  val userOldRating = perf.toRating
+                  val puzzleOldRating = glicko2.Rating(
                     puzzle.glicko.rating.atLeast(lila.rating.Glicko.minRating.value),
                     puzzle.glicko.deviation,
                     puzzle.glicko.volatility,
                     puzzle.plays,
                     none
                   )
-                  updateRatings(userRating, puzzleRating, win)
+                  val (userRating, puzzleRating) = computeRatings(userOldRating, puzzleOldRating, win)
                   userApi
                     .dubiousPuzzle(me.userId, perf)
                     .map: dubiousPuzzleRating =>
@@ -204,12 +204,16 @@ final private[puzzle] class PuzzleFinisher(
   def incPuzzlePlays(puzzleId: PuzzleId): Funit =
     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(
-      List(
-        if win.yes then glicko2.GameResult(u1, u2, false)
-        else glicko2.GameResult(u2, u1, false)
+  private def computeRatings(u1: glicko2.Rating, u2: glicko2.Rating, win: PuzzleWin): Set[glicko2.Rating] =
+    val results = glicko2.RatingPeriodResults[glicko2.BinaryResult](
+      u1 -> List(
+        if win.yes then glicko2.BinaryResult(u2, true)
+        else glicko2.BinaryResult(u2, false)
+      ),
+      u2 -> List(
+        if win.yes then glicko2.BinaryResult(u1, false)
+        else glicko2.BinaryResult(u1, true)
       )
     )
-    try calculator.updateRatings(results)
+    try calculator.computeRatings(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

@@ -2,29 +2,33 @@ package lila.rating.glicko2
 
 // rewrite from java https://github.com/goochjs/glicko2
 final class Rating(
-    var rating: Double,
-    var ratingDeviation: Double,
-    var volatility: Double,
-    var numberOfResults: Int,
-    var lastRatingPeriodEnd: Option[java.time.Instant] = None
+    val rating: Double,
+    val ratingDeviation: Double,
+    val volatility: Double,
+    val numberOfResults: Int,
+    val lastRatingPeriodEnd: Option[java.time.Instant] = None
 ):
 
   import RatingCalculator.*
 
   // the following variables are used to hold values temporarily whilst running calculations
-  private[glicko2] var workingRating: Double          = scala.compiletime.uninitialized
-  private[glicko2] var workingRatingDeviation: Double = scala.compiletime.uninitialized
-  private[glicko2] var workingVolatility: Double      = scala.compiletime.uninitialized
+  private[glicko2] var workingRating: Double          = 0d
+  private[glicko2] var workingRatingDeviation: Double = 0d
+  private[glicko2] var workingVolatility: Double      = 0d
 
   /** Return the average skill value of the player scaled down to the scale used by the algorithm's internal
     * workings.
     */
   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) =
-    rating = convertRatingToOriginalGlickoScale(r)
+  private def setGlicko2Rating(r: Double) =
+    convertRatingToOriginalGlickoScale(r)
 
   /** Return the rating deviation of the player scaled down to the scale used by the algorithm's internal
     * workings.
@@ -33,20 +37,22 @@ final class Rating(
 
   /** Set the rating deviation, taking in a value in Glicko2 scale.
     */
-  def setGlicko2RatingDeviation(rd: Double) =
-    ratingDeviation = convertRatingDeviationToOriginalGlickoScale(rd)
+  private def setGlicko2RatingDeviation(rd: Double) =
+    convertRatingDeviationToOriginalGlickoScale(rd)
 
   /** Used by the calculation engine, to move interim calculations into their "proper" places.
     */
   def finaliseRating() =
-    setGlicko2Rating(workingRating)
-    setGlicko2RatingDeviation(workingRatingDeviation)
-    volatility = workingVolatility
-    workingRatingDeviation = 0d
-    workingRating = 0d
-    workingVolatility = 0d
+    Rating(
+    convertRatingToOriginalGlickoScale(workingRating),
+    convertRatingDeviationToOriginalGlickoScale(workingRatingDeviation),
+    workingVolatility,
+    numberOfResults,
+    lastRatingPeriodEnd
+    )
+
 
   override def toString = s"$rating / $ratingDeviation / $volatility / $numberOfResults"
 
   def incrementNumberOfResults(increment: Int) =
-    numberOfResults = numberOfResults + increment
+    Rating(rating, ratingDeviation, volatility, numberOfResults + increment, lastRatingPeriodEnd)

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,19 +49,19 @@ 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
-    players.foreach { player =>
+  def computeRatings(
+      results: RatingPeriodResults[Result],
+      skipDeviationIncrease: Boolean = false
+  ): Set[Rating] =
+    results.map { case (player, results) =>
       val elapsedRatingPeriods = if skipDeviationIncrease then 0 else 1
-      if results.getResults(player).sizeIs > 0 then
-        calculateNewRating(player, results.getResults(player), elapsedRatingPeriods)
+      if results.sizeIs > 0 then calculateNewRating(player, results, elapsedRatingPeriods)
       else
         // if a player does not compete during the rating period, then only Step 6 applies.
         // the player's rating and volatility parameters remain the same but deviation increases
@@ -64,7 +72,7 @@ final class RatingCalculator(
     }
 
     // now iterate through the participants and confirm their new ratings
-    players.foreach { _.finaliseRating() }
+    results.keySet.map { _.finaliseRating() }
 
   /** This is the formula defined in step 6. It is also used for players who have not competed during the
     * rating period.
@@ -91,7 +99,7 @@ final class RatingCalculator(
     * @param results
     * @param elapsedRatingPeriods
     */
-  def calculateNewRating(player: Rating, results: List[Result], elapsedRatingPeriods: Double): Unit =
+  def calculateNewRating(player: Rating, results: List[Result], elapsedRatingPeriods: Double): Rating =
     val phi   = player.getGlicko2RatingDeviation
     val sigma = player.volatility
     val a     = Math.log(Math.pow(sigma, 2))
@@ -175,13 +183,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)),
+          result
+            .getOpponent(player)
+            .getGlicko2RatingWithAdvantage(result.getAdvantage(advantage).negate),
           result.getOpponent(player).getGlicko2RatingDeviation
         )
         * (1.0 - E(
-          player.getGlicko2Rating,
-          result.getOpponent(player).getGlicko2Rating,
+          player.getGlicko2RatingWithAdvantage(result.getAdvantage(advantage)),
+          result
+            .getOpponent(player)
+            .getGlicko2RatingWithAdvantage(result.getAdvantage(advantage).negate),
           result.getOpponent(player).getGlicko2RatingDeviation
         )))
     1 / v
@@ -202,8 +214,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)),
+            result
+              .getOpponent(player)
+              .getGlicko2RatingWithAdvantage(result.getAdvantage(advantage).negate),
             result.getOpponent(player).getGlicko2RatingDeviation
           )))
     outcomeBasedRating

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

@@ -1,12 +1,8 @@
 package lila.rating.glicko2
 
 // rewrite from java https://github.com/goochjs/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
+type RatingPeriodResults[R <: Result] = Map[Rating, List[R]]
 
-class GameRatingPeriodResults(val results: List[GameResult]) extends RatingPeriodResults[GameResult]
-
-class FloatingRatingPeriodResults(val results: List[FloatingResult])
-    extends RatingPeriodResults[FloatingResult]
+object RatingPeriodResults:
+  def apply[R <: Result](a: (Rating, List[R]))                       = Map[Rating, List[R]](a)
+  def apply[R <: Result](a: (Rating, List[R]), b: (Rating, List[R])) = Map[Rating, List[R]](a, b)

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

@@ -1,51 +1,20 @@
 package lila.rating.glicko2
 
-trait Result:
+import chess.{ Color, White }
 
-  def getScore(player: Rating): Double
+// ASSUME score is between unit interval [0.0d, 1.0d]
+class Result(opponent: Rating, score: Double):
 
-  def getOpponent(player: Rating): Rating
+  def getAdvantage(advantage: ColorAdvantage): ColorAdvantage = advantage.map(_ / 2.0d)
 
-  def participated(player: Rating): Boolean
+  def getScore(player: Rating): Double = score
 
-  def players: List[Rating]
+  def getOpponent(player: Rating): Rating = opponent
 
-// score from 0 (opponent wins) to 1 (player wins)
-class FloatingResult(player: Rating, opponent: Rating, score: Float) extends Result:
+class BinaryResult(val opponent: Rating, val win: Boolean)
+    extends Result(opponent, if win then 1.0d else 0.0d)
 
-  def getScore(p: Rating) = if p == player then score else 1 - score
+class DuelResult(val opponent: Rating, val score: Double, color: Color) extends Result(opponent, score):
 
-  def getOpponent(p: Rating) = if p == player then opponent else player
-
-  def participated(p: Rating) = p == player || p == opponent
-
-  def players = List(player, opponent)
-
-final class GameResult(winner: Rating, loser: Rating, isDraw: Boolean) 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
-
-  /** Returns the "score" for a match.
-    *
-    * @param player
-    * @return
-    *   1 for a win, 0.5 for a draw and 0 for a 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"
+  override def getAdvantage(advantage: ColorAdvantage): ColorAdvantage =
+    if color == White then advantage.map(_ / 2.0d) else advantage.map(_ / 2.0d).negate