A Ruby gem that implements a FIDE-compliant Swiss pairing system for chess tournaments. This gem follows the official FIDE Swiss Rules with full support for ratings, titles, and color allocation rules.
- FIDE-compliant Swiss pairing system implementation
- Support for player ratings and official FIDE titles (GM, IM, WGM, FM, WIM, CM, WFM, WCM)
- Sophisticated color allocation following FIDE rules
- Proper handling of byes for odd numbers of players
- Prevention of rematches between players
- Tournament acceleration option for large events
- Complete tournament management with results tracking
- Comprehensive error handling and validation
- Full test coverage with RSpec
Add this line to your application's Gemfile:
gem 'swisspairing'And then execute:
$ bundle installOr install it yourself as:
$ gem install swisspairingrequire 'swisspairing'
# Create players with ratings and optional FIDE titles
players = [
Swisspairing::Player.new(name: "GM Smith", rating: 2500, title: "GM", id: 1),
Swisspairing::Player.new(name: "IM Jones", rating: 2400, title: "IM", id: 2),
Swisspairing::Player.new(name: "FM Brown", rating: 2300, title: "FM", id: 3),
Swisspairing::Player.new(name: "Alice", rating: 2200, id: 4)
]# Create a new tournament with players and number of rounds
tournament = Swisspairing::Tournament.new(
players: players,
total_rounds: 5,
accelerated: false # Optional: enable acceleration for large tournaments
)# Generate pairings for the current round
pairings = tournament.generate_pairings
# Process each pairing
pairings.each do |pairing|
if pairing.is_bye
puts "#{pairing.white.name} receives a bye"
tournament.apply_result(pairing, "1") # Full point for bye
else
puts "#{pairing.white.name} (White) vs #{pairing.black.name} (Black)"
# After the game, apply the result using one of:
# "1-0" -> White win
# "0-1" -> Black win
# "1/2-1/2" -> Draw
# "0-0" -> Double forfeit
tournament.apply_result(pairing, "1-0") # Example: white wins
end
endFor tournaments with many players, acceleration helps strong players meet each other earlier:
tournament = Swisspairing::Tournament.new(
players: players,
total_rounds: 5,
accelerated: true # Enable acceleration
)The system implements strict FIDE color allocation rules:
- Players should alternate colors when possible
- No player gets the same color three times in a row
- The color difference cannot exceed +2 or -2
- The system considers previous tournament history
Each player object has the following attributes:
player = Swisspairing::Player.new(
name: "GM Smith",
rating: 2500,
title: "GM", # Optional FIDE title
id: 1 # Optional unique identifier
)
player.score # Current tournament score
player.opponents # Array of opponent IDs played against
player.colors # Array of colors played ('W', 'B', or '=' for bye)Track tournament progress and history:
tournament.current_round # Current round number
tournament.total_rounds # Total number of rounds
tournament.results # Array of [pairing, result] for all completed gamesThe system includes comprehensive error handling:
begin
tournament.generate_pairings
rescue Swisspairing::Error => e
puts "Tournament error: #{e.message}"
endCommon errors handled:
- Invalid result formats
- Tournament already complete
- Invalid player data
- Color allocation conflicts
This gem strictly follows FIDE Swiss Rules from the FIDE Handbook C.04:
- Initial ranking by rating and title
- Score-based pairing groups
- FIDE color allocation rules
- Acceleration method for large tournaments
- Proper bye handling
- Prevention of repeating pairings
After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.
Bug reports and pull requests are welcome on GitHub at https://github.com/LapoElisacci/swisspairing.
The gem is available as open source under the terms of the MIT License.