tournament-system 0.1.4 → 0.1.5

data/lib/tournament/algorithm/util.rb

@@ -0,0 +1,100 @@
+module Tournament
+  module Algorithm
+    # This module provides utility functions for helping implement other
+    # algorithms.
+    module Util
+      extend self
+
+      # Padd an array of teams to be even.
+      #
+      # @param teams [Array<team>]
+      # @return [Array<team, nil>]
+      def padd_teams(teams)
+        if teams.length.odd?
+          teams + [nil]
+        else
+          teams
+        end
+      end
+
+      # Padd the count of teams to be even.
+      #
+      # @example
+      #   padded_teams_count(teams.length/) == padd_teams(teams).length
+      #
+      # @param teams_count [Integer] the number of teams
+      # @return [Integer]
+      def padded_teams_count(teams_count)
+        (teams_count / 2.0).ceil * 2
+      end
+
+      # rubocop:disable Metrics/MethodLength
+
+      # Collect all values in an array with a minimum value.
+      #
+      # @param array [Array<element>]
+      # @yieldparam element an element of the array
+      # @yieldreturn [#<, #==] some value to find the minimum of
+      # @return [Array<element>] all elements with the minimum value
+      def all_min_by(array)
+        min_elements = []
+        min_value = nil
+
+        array.each do |element|
+          value = yield element
+
+          if !min_value || value < min_value
+            min_elements = [element]
+            min_value = value
+          elsif value == min_value
+            min_elements << element
+          end
+        end
+
+        min_elements
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # rubocop:disable Metrics/MethodLength
+      # :reek:NestedIterators
+
+      # Iterate all perfect matches of a specific size.
+      # A perfect matching is a unique grouping of all elements with a specific
+      # group size. For example +[[1, 2], [3, 4]]+ is a perfect match of
+      # +[1, 2, 3, 4]+ with group size of +2+.
+      #
+      # This is useful for example when a pairing algorithm needs to iterate all
+      # possible pairings of teams to determine which is the best.
+      #
+      # Warning, this currently only works for +size = 2+.
+      #
+      # @param array [Array<element>]
+      # @param size [Integer] the size of groups
+      # @overload all_perfect_matches(array, size)
+      #   @return [Enumerator<Array<element>>] enumerator for all perfect
+      #                                        matches
+      # @overload all_perfect_matches(array, size) { |group| ... }
+      #   @yieldparam group [Array(element, size)] a group of elements
+      #   @return [void]
+      def all_perfect_matches(array, size)
+        size = 2
+        return to_enum(:all_perfect_matches, array, size) unless block_given?
+
+        if array.empty?
+          yield []
+          return
+        end
+
+        array[1..-1].combination(size - 1) do |group|
+          group.unshift array[0]
+
+          remaining = array.reject { |element| group.include?(element) }
+          all_perfect_matches(remaining, size) do |groups|
+            yield [group] + groups
+          end
+        end
+      end
+      # rubbocop:enable Metrics/MethodLength
+    end
+  end
+end

data/lib/tournament/algorithm.rb

@@ -0,0 +1,6 @@
+module Tournament
+  # This module provides abtraction-less implementations of all algorithms
+  # used for tournament systems.
+  module Algorithm
+  end
+end

data/lib/tournament/driver.rb

@@ -1,4 +1,6 @@
 module Tournament
+  # :reek:UnusedParameters
+
   # An interface for external tournament data.
   #
   # To use any tournament system implemented in this gem, simply subclass this
@@ -11,42 +13,72 @@ module Tournament
   # Certain tournament systems will not make use of certain parts of this
   # interface. You can for example leave out `#get_team_score` if you're not
   # using the Swiss tournament system.
-  # :reek:UnusedParameters
+  #
+  # This class caches certain calculations/objects, it is designed to be a
+  # one-time use with any one tournament system. Reusing an instance may result
+  # in undefined behaviour.
   class Driver
     # rubocop:disable Lint/UnusedMethodArgument
     # :nocov:
 
-    # Get all matches
+    # Get all matches. Required to implement.
+    #
+    # @return [Array<match>]
     def matches
       raise 'Not Implemented'
     end
 
-    # Get the teams playing with their initial seedings
+    # Get the teams with their initial seedings. Required to implement.
+    #
+    # @return [Array<team>]
     def seeded_teams
       raise 'Not Implemented'
     end
 
-    # Get the teams playing, ranked by their current position in the tournament
+    # Get the teams ranked by their current position in the tournament.
+    # Required to implement.
+    #
+    # @return [Array<team>]
     def ranked_teams
       raise 'Not Implemented'
     end
 
-    # Get the winning team of a match
+    # Get the winning team of a match. Required to implement.
+    #
+    # @param match [] a match, eg. one returned by {#matches}
+    # @return [team, nil] the winner of the match if applicable
     def get_match_winner(match)
       raise 'Not Implemented'
     end
 
-    # Get both teams playing for a match
+    # Get the pair of teams playing for a match. Required to implement.
+    #
+    # @param match [] a match, eg. one returned by {#matches}
+    # @return [Array(team, team)] the pair of teams playing in the match
     def get_match_teams(match)
       raise 'Not Implemented'
     end
 
-    # Get a specific score for a team
+    # Get a specific score for a team. Required to implement.
+    #
+    # @param team [] a team, eg. one returned by {#seeded_teams}
+    # @return [Number] the score of the team
     def get_team_score(team)
       raise 'Not Implemented'
     end
 
-    # Handle for matches that are created by tournament systems
+    # Called when a match is created by a tournament system. Required to
+    # implement.
+    #
+    # @example rails
+    #   def build_match(home_team, away_team)
+    #     Match.create!(home_team, away_team)
+    #   end
+    #
+    # @param home_team [team] the home team for the match, never +nil+
+    # @param away_team [team, nil] the away team for the match, may be +nil+ for
+    #     byes.
+    # @return [void]
     def build_match(home_team, away_team)
       raise 'Not Implemented'
     end
@@ -54,17 +86,76 @@ module Tournament
     # :nocov:
     # rubocop:enable Lint/UnusedMethodArgument
 
-    # Get the losing team of a specific match
+    # Get the losing team of a specific match. By default uses
+    # {#get_match_winner} and {#get_match_teams} to determine which team lost.
+    # Override if you have better access to this information.
+    #
+    # @return [team, nil] the lower of the match, if applicable
     def get_match_loser(match)
       winner = get_match_winner(match)
+
+      return nil unless winner
       get_match_teams(match).reject { |team| team == winner }.first
     end
 
+    # Get a hash of unique team pairs and their number of occurences. Used by
+    # tournament systems.
+    #
+    # @return [Hash{Set(team, team) => Integer}]
+    def matches_hash
+      @matches_hash ||= build_matches_hash
+    end
+
+    # Count the number of times each pair of teams has played already. Used by
+    # tournament systems.
+    #
+    # @param matches [Array<match>]
+    # @return [Integer] the number of duplicate matches
+    def count_duplicate_matches(matches)
+      matches.map { |match| matches_hash[Set.new match] }.reduce(0, :+)
+    end
+
+    # Create a match. Used by tournament systems.
+    #
+    # Specially handles byes, swapping home/away if required.
+    #
+    # @param home_team [team, nil]
+    # @param away_team [team, nil]
+    # @return [void]
+    # @raise when both teams are +nil+
     def create_match(home_team, away_team)
       home_team, away_team = away_team, home_team unless home_team
       raise 'Invalid match' unless home_team
 
       build_match(home_team, away_team)
     end
+
+    # Create a bunch of matches. Used by tournament systems.
+    # @see #create_match
+    #
+    # @param matches [Array<Array(team, team)>] a collection of pairs
+    # @return [void]
+    def create_matches(matches)
+      matches.each do |home_team, away_team|
+        create_match(home_team, away_team)
+      end
+    end
+
+    # Get a hash of the scores of all ranked teams. Used by tournament systems.
+    #
+    # @return [Hash{team => Number}] a mapping from teams to scores
+    def scores_hash
+      @scores_hash = ranked_teams.map { |team| [team, get_team_score(team)] }
+                                 .to_h
+    end
+
+    private
+
+    def build_matches_hash
+      matches.each_with_object(Hash.new(0)) do |match, counter|
+        match = Set.new get_match_teams(match)
+        counter[match] += 1
+      end
+    end
   end
 end

data/lib/tournament/page_playoff.rb

@@ -1,8 +1,17 @@
+require 'tournament/algorithm/page_playoff'
+require 'tournament/algorithm/pairers/adjacent'
+
 module Tournament
   # Implements the page playoff system.
   module PagePlayoff
     extend self
 
+    # Generate matches with the given driver.
+    #
+    # @param driver [Driver]
+    # @option options [Integer] round the round to generate
+    # @option options [Boolean] bronze_match whether to generate a bronze match
+    #     on the final round.
     def generate(driver, options = {})
       teams = driver.ranked_teams
       raise 'Page Playoffs only works with 4 teams' if teams.length != 4
@@ -18,32 +27,26 @@ module Tournament
       end
     end
 
-    def total_rounds
-      3
+    # The total number of rounds in a page playoff tournament
+    #
+    # @param _ for keeping the same interface as other tournament systems.
+    # @return [Integer]
+    def total_rounds(_ = nil)
+      Algorithm::PagePlayoff::TOTAL_ROUNDS
     end
 
+    # Guess the next round number (starting at 0) from the state in a driver.
+    #
+    # @param driver [Driver]
+    # @return [Integer]
     def guess_round(driver)
-      count = driver.matches.length
-
-      case count
-      when 0 then 0
-      when 2 then 1
-      when 3 then 2
-      else
-        raise 'Invalid number of matches'
-      end
+      Algorithm::PagePlayoff.guess_round(driver.matches.length)
     end
 
     private
 
-    def create_matches(driver, matches)
-      matches.each do |match|
-        driver.create_match match[0], match[1]
-      end
-    end
-
     def semi_finals(driver, teams)
-      create_matches driver, [[teams[0], teams[1]], [teams[2], teams[3]]]
+      driver.create_matches Algorithm::Pairers::Adjacent.pair(teams)
     end
 
     def preliminary_finals(driver)

data/lib/tournament/round_robin.rb

@@ -1,58 +1,52 @@
+require 'tournament/algorithm/util'
+require 'tournament/algorithm/round_robin'
+
 module Tournament
   # Implements the round-robin tournament system.
-  # Requires a consistent seeder, defaulting to Seeder::None
   module RoundRobin
     extend self
 
+    # Generate matches with the given driver.
+    #
+    # @param driver [Driver]
+    # @option options [Integer] round the round to generate
+    # @return [void]
     def generate(driver, options = {})
       round = options[:round] || guess_round(driver)
 
-      teams = seed_teams driver.seeded_teams, options
+      teams = Algorithm::Util.padd_teams(driver.seeded_teams)
 
-      teams = rotate_to_round teams, round
+      matches = Algorithm::RoundRobin.round_robin_pairing(teams, round)
 
-      create_matches driver, teams, round
+      create_matches driver, matches, round
     end
 
+    # The total number of rounds needed for a round robin tournament with the
+    # given driver.
+    #
+    # @param driver [Driver]
+    # @return [Integer]
     def total_rounds(driver)
-      team_count(driver) - 1
+      Algorithm::RoundRobin.total_rounds(driver.seeded_teams.length)
     end
 
+    # Guess the next round number (starting at 0) from the state in driver.
+    #
+    # @param driver [Driver]
+    # @return [Integer]
     def guess_round(driver)
-      match_count = driver.matches.length
-
-      match_count / (team_count(driver) / 2)
+      Algorithm::RoundRobin.guess_round(driver.seeded_teams.length,
+                                        driver.matches.length)
     end
 
     private
 
-    def team_count(driver)
-      count = driver.seeded_teams.length
-      count += 1 if count.odd?
-      count
-    end
-
-    def seed_teams(teams, options)
-      teams << nil if teams.length.odd?
-
-      seeder = options[:seeder] || Seeder::None
-      seeder.seed teams
-    end
-
-    def rotate_to_round(teams, round)
-      rotateable = teams[1..-1]
-
-      [teams[0]] + rotateable.rotate(-round)
-    end
-
-    def create_matches(driver, teams, round)
-      teams[0...teams.length / 2].each_with_index do |home_team, index|
-        away_team = teams[-index - 1]
-
+    def create_matches(driver, matches, round)
+      matches.each do |match|
         # Alternate home/away
-        home_team, away_team = away_team, home_team if round.odd?
+        match = match.reverse if round.odd? && match[0]
 
-        driver.create_match(home_team, away_team)
+        driver.create_match(*match)
       end
     end
   end

data/lib/tournament/single_elimination.rb

@@ -1,62 +1,49 @@
+require 'tournament/algorithm/single_bracket'
+require 'tournament/algorithm/pairers/adjacent'
+
 module Tournament
   # Implements the single bracket elimination tournament system.
   module SingleElimination
     extend self
 
-    def generate(driver, options = {})
+    # Generate matches with the given driver
+    #
+    # @param driver [Driver]
+    # @return [void]
+    def generate(driver, _options = {})
       round = guess_round(driver)
 
       teams = if driver.matches.empty?
-                seed_teams driver.seeded_teams, options
+                padded = Algorithm::SingleBracket.padd_teams driver.seeded_teams
+                Algorithm::SingleBracket.seed padded
               else
                 last_matches = previous_round_matches driver, round
                 get_match_winners driver, last_matches
               end
 
-      create_matches driver, teams
+      driver.create_matches Algorithm::Pairers::Adjacent.pair(teams)
     end
 
+    # The total number of rounds needed for a single elimination tournament with
+    # the given driver.
+    #
+    # @param driver [Driver]
+    # @return [Integer]
     def total_rounds(driver)
-      total_rounds_for_teams(driver.seeded_teams)
+      Algorithm::SingleBracket.total_rounds(driver.seeded_teams.length)
     end
 
+    # Guess the next round number (starting at 0) from the state in driver.
+    #
+    # @param driver [Driver]
+    # @return [Integer]
     def guess_round(driver)
-      rounds = total_rounds(driver)
-      teams_count = 2**rounds
-      matches_count = driver.matches.length
-
-      # Make sure we don't have too many matches
-      raise ArgumentError, 'Too many matches' unless teams_count > matches_count
-
-      round = rounds - Math.log2(teams_count - matches_count)
-      # Make sure we don't have some weird number of matches
-      raise ArgumentError, 'Invalid number of matches' unless (round % 1).zero?
-      round.to_i
+      Algorithm::SingleBracket.guess_round(driver.seeded_teams.length,
+                                           driver.matches.length)
     end
 
     private
 
-    def seed_teams(teams, options)
-      teams = padd_teams teams
-
-      seeder = options[:seeder] || Seeder::SingleBracket
-      seeder.seed teams
-    end
-
-    def padd_teams(teams)
-      required = 2**total_rounds_for_teams(teams)
-      padding = required - teams.length
-
-      # Insert the padding at the bottom to give top teams byes
-      teams + [nil] * padding
-    end
-
-    def total_rounds_for_teams(teams)
-      team_count = teams.length
-
-      Math.log2(team_count).ceil
-    end
-
     def get_match_winners(driver, matches)
       matches.map { |match| driver.get_match_winner(match) }
     end
@@ -67,13 +54,5 @@ module Tournament
 
       driver.matches.last(previous_matches_count)
     end
-
-    def create_matches(driver, teams)
-      teams.each_slice(2) do |slice|
-        next if slice.all?(&:nil?)
-
-        driver.create_match(slice[0], slice[1])
-      end
-    end
   end
 end