Merge pull request #3 from marceljuenemann/bh-cut

Buchholz with modifiers (Cut-1 etc.)

Author: marceljuenemann

README.md

@@ -11,7 +11,8 @@ Tiebreak is a TypeScript library for calculating various tournament tiebreak sco
 **Calculation of the following tiebreakers:**
 
 - Buchholz
-- (more to come!)
+- Buchholz with modifiers (Cut-1, Cut-2, Median-1 etc.)
+- (more to come)
 
 **Configurable adjustments for unplayed games:**
 

src/__tests__/testcases/README.md

@@ -0,0 +1,4 @@
+# Test Cases
+
+**fide-exercise-2023.csv:**
+Exercises for the new FIDE regulations published on 2024-03-18 at https://tec.fide.com/2024/03/18/tie-break-exercise/

src/__tests__/tiebreak.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from "vitest"
 
 import { Results, RoundResults, Score, TournamentType } from "../results.js"
-import { Modifier, Tiebreak, Tiebreaker, UnplayedRoundsAdjustment } from "../tiebreak.js"
+import { Tiebreak, Tiebreaker, UnplayedRoundsAdjustment } from "../tiebreak.js"
 import { readTestCases } from "./util/test-case-reader.js"
 
 describe("TiebreakCalculation", () => {
@@ -118,6 +118,39 @@ describe("TiebreakCalculation", () => {
         expect(tiebreak.buchholz("16", 5)).toEqual(12.5)
         expect(tiebreak.buchholz("4", 5)).toEqual(15.0)
       })
+
+      it("should pass FIDE exercise 5 (2023)", async () => {
+        const rounds = await readTestCases("fide-exercise-2023")
+        const tiebreak = new Tiebreaker(rounds, UnplayedRoundsAdjustment.FIDE_2023)
+        expect(tiebreak.buchholz("5", 5, 1)).toEqual(7.5)
+        expect(tiebreak.buchholz("8", 5, 1)).toEqual(12)
+        expect(tiebreak.buchholz("11", 5, 1)).toEqual(12)
+      })
+
+      it("should pass FIDE exercise 6 (2023)", async () => {
+        const rounds = await readTestCases("fide-exercise-2023")
+        const tiebreak = new Tiebreaker(rounds, UnplayedRoundsAdjustment.FIDE_2023)
+        expect(tiebreak.buchholz("7", 5, 1)).toEqual(12.5)
+        expect(tiebreak.buchholz("9", 5, 1)).toEqual(7.5)
+        expect(tiebreak.buchholz("13", 5, 1)).toEqual(12)
+      })
+
+      it("should pass FIDE exercise 7 (2023)", async () => {
+        const rounds = await readTestCases("fide-exercise-2023")
+        const tiebreak = new Tiebreaker(rounds, UnplayedRoundsAdjustment.FIDE_2023)
+        expect(tiebreak.buchholz("1", 5, 1)).toEqual(11.0)
+        expect(tiebreak.buchholz("3", 5, 1)).toEqual(13)
+        expect(tiebreak.buchholz("4", 5, 1)).toEqual(11.5)
+        expect(tiebreak.buchholz("16", 5, 1)).toEqual(11)
+      })
+
+      it("should pass FIDE exercise 8 (2023)", async () => {
+        const rounds = await readTestCases("fide-exercise-2023")
+        const tiebreak = new Tiebreaker(rounds, UnplayedRoundsAdjustment.FIDE_2023)
+        expect(tiebreak.buchholz("12", 5, 1)).toEqual(9.5)
+        expect(tiebreak.buchholz("14", 5, 1)).toEqual(9)
+        expect(tiebreak.buchholz("15", 5, 1)).toEqual(11)
+      })
     })
 
     describe("with FIDE_2009 unplayed rounds adjustment", () => {
@@ -154,18 +187,20 @@ describe("TiebreakCalculation", () => {
         expect(tiebreak.buchholz("B", 3)).toEqual(1 + 2 * 0.5 + (0 + 1 + 0.5) + (0 + 1))
       })
     })
-  })
 
-  describe("buchholz with Cut-1 modifier", () => {
-    describe("with FIDE_2023 unplayed rounds adjustment", () => {
-      it("should pass FIDE exercise 5 (2023)", async () => {
-        const rounds = await readTestCases("fide-exercise-2023")
-        const tiebreak = new Tiebreaker(rounds, UnplayedRoundsAdjustment.FIDE_2023)
-        expect(tiebreak.buchholz("5", 5, Modifier.CUT_1)).toEqual(7.5)
-        expect(tiebreak.buchholz("8", 5, Modifier.CUT_1)).toEqual(12)
-        expect(tiebreak.buchholz("11", 5, Modifier.CUT_1)).toEqual(12)
-      })
+    /*
+    TODO: Test more modifiers with old FIDE unplayed rounds adjustments
+    - Cut-1
+    - Median-1
+    - Cut-2
+    - Very high cut numbers
+
+    describe("with modifiers", () => {
+
+    
+
     })
+    */
   })
 
   describe("ranking", () => {
@@ -185,11 +220,13 @@ describe("TiebreakCalculation", () => {
         },
       ])
       const tiebreak = new Tiebreaker(results, UnplayedRoundsAdjustment.FIDE_2023)
-      expect(tiebreak.ranking(2, [Tiebreak.SCORE, Tiebreak.BUCHHOLZ])).toEqual([
-        { playerId: "B", rank: 1, scores: [2, 2.5] }, // BH: 2 for unplayed + 0.5 for A
-        { playerId: "C", rank: 2, scores: [1.5, 2] }, // BH: 0.5 for A + 1.5 for bye
-        { playerId: "A", rank: 3, scores: [0.5, 3.5] }, // BH: 1.5 for C + 2 for B
-        { playerId: "D", rank: 4, scores: [0, 0] }, // BH: 2 * 0 for unplayed rounds
+      expect(
+        tiebreak.ranking(2, [Tiebreak.SCORE, Tiebreak.BUCHHOLZ, Tiebreak.BUCHHOLZ_CUT1]),
+      ).toEqual([
+        { playerId: "B", rank: 1, scores: [2, 2.5, 2] }, // BH: 2 for unplayed + 0.5 for A
+        { playerId: "C", rank: 2, scores: [1.5, 2, 1.5] }, // BH: 0.5 for A + 1.5 for bye
+        { playerId: "A", rank: 3, scores: [0.5, 3.5, 2] }, // BH: 1.5 for C + 2 for B
+        { playerId: "D", rank: 4, scores: [0, 0, 0] }, // BH: 2 * 0 for unplayed rounds
       ])
     })
 

src/tiebreak.ts

@@ -17,6 +17,16 @@ export enum Tiebreak {
    * The sum of the scores of each of the opponents of a participant.
    */
   BUCHHOLZ = "BH",
+
+  /**
+   * Buchholz with the least significant opponent cut. Note that voluntarily
+   * unplayed rounds will be cut first if FIDE_2023 regulations are applied.
+   */
+  BUCHHOLZ_CUT1 = "BH-C1",
+
+  BUCHHOLZ_CUT2 = "BH-C2",
+  BUCHHOLZ_MEDIAN1 = "BH-M1",
+  BUCHHOLZ_MEDIAN2 = "BH-M2",
 }
 
 export enum UnplayedRoundsAdjustment {
@@ -46,31 +56,19 @@ export enum UnplayedRoundsAdjustment {
   FIDE_2009 = "FIDE_2009",
 }
 
-/**
- * Modifiers for tiebreaks that are based on a sum of values, such as Buchholz
- * and Sonneborn-Berger. These modifiers are defined in the FIDE Tiebreak Regulations,
- * Article 14.
- */
-export enum Modifier {
-  // 14.1 Cut-1: Cut the Least Significant Value
-  CUT_1 = "Cut-1",
-
-  // 14.2 Cut-2: Cut the two Least Significant Values
-  CUT_2 = "Cut-2",
-
-  // 14.3 Median­1: Cut the Least and the Most Significant Values (in that order)
-  MEDIAN_1 = "Median1",
-
-  // 14.4 Median­2: Cut the two Least and the two Most Significant Values (in that order)
-  MEDIAN_2 = "Median2",
-}
-
 export interface PlayerRanking {
   rank: number
   playerId: PlayerId
   scores: number[]
 }
 
+interface AdjustedGame {
+  round: number
+  gameScore: number
+  opponentScore: number
+  isVur: boolean
+}
+
 /**
  * Calculates tiebreaks for a tournament with the given results and configuration.
  */
@@ -130,6 +128,14 @@ export class Tiebreaker {
 
       case Tiebreak.BUCHHOLZ:
         return this.buchholz(player, round)
+      case Tiebreak.BUCHHOLZ_CUT1:
+        return this.buchholz(player, round, 1, 0)
+      case Tiebreak.BUCHHOLZ_CUT2:
+        return this.buchholz(player, round, 2, 0)
+      case Tiebreak.BUCHHOLZ_MEDIAN1:
+        return this.buchholz(player, round, 1, 1)
+      case Tiebreak.BUCHHOLZ_MEDIAN2:
+        return this.buchholz(player, round, 2, 2)
     }
   }
 
@@ -186,36 +192,64 @@ export class Tiebreaker {
   }
 
   /**
-   * Buchholz score. Note that unplayed games are adjusted according to the configured UnplayedRoundsAdjustment.
+   * Returns all opponents of the given player with their adjusted scores for the purpose of
+   * calculating tiebreaks like Buchholz and SoBerg.
    */
-  public buchholz(player: PlayerId, round: number, modifier?: Modifier): number {
-    const opponentScores = this.results.getAll(player, round).map((result, index) => {
-      const currentRound = index + 1
-      switch (this.unplayedRoundsAdjustment) {
-        case UnplayedRoundsAdjustment.NONE:
-          return isPaired(result) ? this.adjustedScore(result.opponent, round) : 0
-
-        case UnplayedRoundsAdjustment.FIDE_2023:
-          if (isPlayed(result)) {
-            return this.adjustedScore(result.opponent, round)
-          } else {
-            // Use a dummy opponent with same score.
-            return this.score(player, round)
-          }
-
-        case UnplayedRoundsAdjustment.FIDE_2009:
-          if (isPlayed(result)) {
-            return this.adjustedScore(result.opponent, round)
-          } else {
-            // Use a virtual opponent.
-            const initialScore = this.score(player, currentRound - 1)
-            const gameScore = 1 - this.scoreForResult(result)
-            const virtualPoints = (round - currentRound) * 0.5
-            return initialScore + gameScore + virtualPoints
-          }
+  private adjustedGames(player: PlayerId, round: number): AdjustedGame[] {
+    return this.results.getAll(player, round).map((result, index) => {
+      const game: AdjustedGame = {
+        round: index + 1,
+        gameScore: this.scoreForResult(result),
+        opponentScore: isPaired(result) ? this.adjustedScore(result.opponent, round) : 0,
+        isVur: isVoluntarilyUnplayedRound(result),
+      }
+
+      // Apply unplayed round adjustments.
+      if (!isPlayed(result)) {
+        // 2023: Use a dummy opponent with same score as the player.
+        if (this.unplayedRoundsAdjustment === UnplayedRoundsAdjustment.FIDE_2023) {
+          game.opponentScore = this.score(player, round)
+        }
+
+        // 2009: Use a virtual opponent that starts with the same score.
+        if (this.unplayedRoundsAdjustment === UnplayedRoundsAdjustment.FIDE_2009) {
+          const initialScore = this.score(player, game.round - 1)
+          const opponentGameScore = 1 - game.gameScore
+          const virtualPoints = (round - game.round) * 0.5
+          game.opponentScore = initialScore + opponentGameScore + virtualPoints
+        }
       }
+      return game
     })
-    return this.sumWithModifier(opponentScores, modifier)
+  }
+
+  /**
+   * Buchholz score. Note that unplayed games are adjusted according to the configured UnplayedRoundsAdjustment.
+   */
+  public buchholz(
+    player: PlayerId,
+    round: number,
+    cutLowest: number = 0,
+    cutHighest: number = 0,
+  ): number {
+    let games = this.adjustedGames(player, round)
+
+    if (cutLowest || cutHighest) {
+      games.sort((a, b) => {
+        // Since 2023, voluntarily unplayed rounds should get cut first.
+        if (
+          this.unplayedRoundsAdjustment === UnplayedRoundsAdjustment.FIDE_2023 &&
+          a.isVur !== b.isVur
+        ) {
+          return Number(a.isVur) - Number(b.isVur)
+        }
+        return b.opponentScore - a.opponentScore
+      })
+
+      games = games.slice(cutHighest, -cutLowest)
+    }
+
+    return this.sum(games.map((g) => g.opponentScore))
   }
 
   // TODO: Maybe turn PlayerResult into a class which returns the score?
@@ -232,20 +266,6 @@ export class Tiebreaker {
     }
   }
 
-  /**
-   * Applies the given modifier to the values (e.g. cutting least significant values)
-   * and returns the sum of the remaining values.
-   */
-  private sumWithModifier(values: number[], modifier?: Modifier): number {
-    values.sort()
-    switch (modifier) {
-      case Modifier.CUT_1:
-        values = values.splice(1)
-        break
-    }
-    return this.sum(values)
-  }
-
   private sum(numbers: number[]): number {
     return numbers.reduce((prev, curr) => prev + curr, 0)
   }