openskill 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a7fcde3a56dfbdd99df6a10cfdebf1fb95c0b2b0fe21513792a3e3103e0606f1
+  data.tar.gz: be466ac8799195ba2a0353ac2bc94be71857c6c27d824c37db59d1ab088c13ca
+SHA512:
+  metadata.gz: 9d3c96ae581d28403b828e90788582b06a6d77c7c6a418dfbe1b98abf0e164abdfcf4b1b28151a486a2ed7ab0ab902f7803fca4eb7861ca27c5550ab73c2e4a7
+  data.tar.gz: 867ce922496ccac80c0ea67195d2bf339afb253c7d52d73dbfd2c830848e9d762591b182e725f9e19262d06d209415b7b49921dffdb19b8fee92e8a12dca3903

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenSkill Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,384 @@
+# OpenSkill
+
+A Ruby implementation of the OpenSkill rating system for multiplayer games. OpenSkill is a Bayesian skill rating system that can handle teams of varying sizes, asymmetric matches, and complex game scenarios.
+
+[![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)]()
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.1.0-red.svg)]()
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+## Features
+
+- 🎮 **Multiplayer Support**: Handle 2+ teams of any size
+- ⚖️ **Asymmetric Teams**: Teams don't need equal player counts
+- 🎯 **Multiple Ranking Methods**: Use ranks or scores
+- 📊 **Prediction Methods**: Predict win probabilities, draws, and final rankings
+- 🔢 **Player Weights**: Account for partial participation or contribution
+- 📈 **Score Margins**: Factor in impressive wins
+- 🔄 **Tie Handling**: Properly handle drawn matches
+- ⚡ **Fast**: Efficient Ruby implementation
+- 🧪 **Well Tested**: Comprehensive test suite matching reference implementation
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'openskill'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install openskill
+```
+
+## Quick Start
+
+```ruby
+require 'openskill'
+
+# Create a model (Plackett-Luce by default)
+model = OpenSkill::Models::PlackettLuce.new
+
+# Create player ratings
+alice = model.create_rating(name: "Alice")
+bob = model.create_rating(name: "Bob")
+charlie = model.create_rating(name: "Charlie")
+dave = model.create_rating(name: "Dave")
+
+# Simple 1v1 match (alice wins)
+team1 = [alice]
+team2 = [bob]
+new_ratings = model.calculate_ratings([team1, team2])
+alice, bob = new_ratings.flatten
+
+puts "Alice: #{alice.mu.round(2)} ± #{alice.sigma.round(2)}"
+puts "Bob: #{bob.mu.round(2)} ± #{bob.sigma.round(2)}"
+```
+
+## Usage
+
+### Creating Ratings
+
+```ruby
+model = OpenSkill::Models::PlackettLuce.new
+
+# Create with defaults (mu=25, sigma=8.333)
+player = model.create_rating
+
+# Create with custom values
+player = model.create_rating(mu: 30.0, sigma: 5.0, name: "Alice")
+
+# Load from database [mu, sigma]
+player = model.load_rating([28.5, 7.2], name: "Bob")
+```
+
+### Calculating New Ratings
+
+#### Simple Match (Team 1 wins)
+
+```ruby
+team1 = [alice, bob]
+team2 = [charlie, dave]
+
+updated_teams = model.calculate_ratings([team1, team2])
+```
+
+#### Match with Explicit Ranks
+
+Lower rank = better performance (0 is best)
+
+```ruby
+teams = [[alice], [bob], [charlie]]
+# Charlie wins, Bob second, Alice third
+updated = model.calculate_ratings(teams, ranks: [2, 1, 0])
+```
+
+#### Match with Scores
+
+Higher score = better performance
+
+```ruby
+teams = [[alice, bob], [charlie, dave]]
+# Team 2 wins 100-80
+updated = model.calculate_ratings(teams, scores: [80, 100])
+```
+
+#### Match with Ties
+
+```ruby
+teams = [[alice], [bob], [charlie]]
+# Alice and Charlie tie for first, Bob comes third
+updated = model.calculate_ratings(teams, ranks: [0, 2, 0])
+```
+
+#### Player Contribution Weights
+
+When players contribute different amounts:
+
+```ruby
+teams = [
+  [alice, bob],      # Alice contributed more
+  [charlie, dave]    # Dave carried the team
+]
+
+updated = model.calculate_ratings(
+  teams,
+  weights: [[2.0, 1.0], [1.0, 2.0]]
+)
+```
+
+#### Score Margins (Impressive Wins)
+
+Factor in score differences:
+
+```ruby
+model = OpenSkill::Models::PlackettLuce.new(margin: 5.0)
+
+# Large score difference means more rating change
+updated = model.calculate_ratings(
+  [[alice], [bob]],
+  scores: [100, 20]  # Alice dominated
+)
+```
+
+### Predictions
+
+#### Win Probability
+
+```ruby
+teams = [[alice, bob], [charlie, dave], [eve]]
+probabilities = model.predict_win_probability(teams)
+# => [0.35, 0.45, 0.20] (sums to 1.0)
+```
+
+#### Draw Probability
+
+Higher values mean more evenly matched:
+
+```ruby
+probability = model.predict_draw_probability([[alice], [bob]])
+# => 0.25
+```
+
+#### Rank Prediction
+
+```ruby
+teams = [[alice], [bob], [charlie]]
+predictions = model.predict_rank_probability(teams)
+# => [[1, 0.504], [2, 0.333], [3, 0.163]]
+# Format: [predicted_rank, probability]
+```
+
+### Rating Display
+
+The `ordinal` method provides a conservative rating estimate:
+
+```ruby
+player = model.create_rating(mu: 30.0, sigma: 5.0)
+
+# 99.7% confidence (3 standard deviations)
+puts player.ordinal  # => 15.0 (30 - 3*5)
+
+# 99% confidence
+puts player.ordinal(z: 2.576)  # => 17.12
+
+# For leaderboards
+players.sort_by(&:ordinal).reverse
+```
+
+### Model Options
+
+```ruby
+model = OpenSkill::Models::PlackettLuce.new(
+  mu: 25.0,           # Initial mean skill
+  sigma: 25.0 / 3,    # Initial skill uncertainty
+  beta: 25.0 / 6,     # Performance variance
+  kappa: 0.0001,      # Minimum variance (regularization)
+  tau: 25.0 / 300,    # Skill decay per match
+  margin: 0.0,        # Score margin threshold
+  limit_sigma: false, # Prevent sigma from increasing
+  balance: false      # Emphasize rating outliers in teams
+)
+```
+
+### Advanced Features
+
+#### Prevent Rating Uncertainty from Growing
+
+```ruby
+# Useful for active players
+updated = model.calculate_ratings(teams, limit_sigma: true)
+```
+
+#### Balance Outliers in Teams
+
+```ruby
+model = OpenSkill::Models::PlackettLuce.new(balance: true)
+# Gives more weight to rating differences within teams
+```
+
+#### Custom Tau (Skill Decay)
+
+```ruby
+# Higher tau = more rating volatility
+updated = model.calculate_ratings(teams, tau: 1.0)
+```
+
+## How It Works
+
+OpenSkill uses a Bayesian approach to model player skill as a normal distribution:
+
+- **μ (mu)**: The mean skill level
+- **σ (sigma)**: The uncertainty about the skill level
+
+After each match:
+1. Compute team strengths from individual player ratings
+2. Calculate expected outcomes based on team strengths
+3. Update ratings based on actual vs expected performance
+4. Reduce uncertainty (sigma) as more matches are played
+
+The **ordinal** value (`μ - 3σ`) provides a conservative estimate where the true skill is 99.7% likely to be higher.
+
+## Why OpenSkill?
+
+### vs Elo
+- ✅ Handles multiplayer (3+ players/teams)
+- ✅ Works with team games
+- ✅ Accounts for rating uncertainty
+- ✅ Faster convergence to true skill
+
+### vs TrueSkill
+- ✅ Open source (MIT license)
+- ✅ Faster computation
+- ✅ Similar accuracy
+- ✅ More flexible (weights, margins, custom parameters)
+
+## API Design Philosophy
+
+This Ruby implementation uses idiomatic Ruby naming conventions:
+
+| Python API | Ruby API |
+|------------|----------|
+| `model.rating()` | `model.create_rating` |
+| `model.create_rating([25, 8.3])` | `model.load_rating([25, 8.3])` |
+| `model.rate(teams)` | `model.calculate_ratings(teams)` |
+| `model.predict_win(teams)` | `model.predict_win_probability(teams)` |
+| `model.predict_draw(teams)` | `model.predict_draw_probability(teams)` |
+| `model.predict_rank(teams)` | `model.predict_rank_probability(teams)` |
+
+## Examples
+
+### 2v2 Team Game
+
+```ruby
+model = OpenSkill::Models::PlackettLuce.new
+
+# Create players
+alice = model.create_rating(name: "Alice")
+bob = model.create_rating(name: "Bob")
+charlie = model.create_rating(name: "Charlie")
+dave = model.create_rating(name: "Dave")
+
+# Match: Alice + Bob vs Charlie + Dave (Team 1 wins)
+teams = [[alice, bob], [charlie, dave]]
+updated = model.calculate_ratings(teams)
+
+# Updated ratings
+updated[0].each { |p| puts "#{p.name}: #{p.ordinal.round(1)}" }
+updated[1].each { |p| puts "#{p.name}: #{p.ordinal.round(1)}" }
+```
+
+### Free-for-All (5 players)
+
+```ruby
+players = 5.times.map { model.create_rating }
+
+# Player 3 wins, 1 second, 4 third, 0 fourth, 2 fifth
+updated = model.calculate_ratings(
+  players.map { |p| [p] },
+  ranks: [3, 1, 4, 0, 2]
+)
+```
+
+### Tracking Player Progress
+
+```ruby
+class Player
+  attr_accessor :name, :mu, :sigma
+  
+  def initialize(name, model)
+    @name = name
+    rating = model.create_rating
+    @mu = rating.mu
+    @sigma = rating.sigma
+  end
+  
+  def to_rating(model)
+    model.load_rating([@mu, @sigma], name: @name)
+  end
+  
+  def update_from_rating!(rating)
+    @mu = rating.mu
+    @sigma = rating.sigma
+  end
+  
+  def ordinal(z: 3.0)
+    @mu - z * @sigma
+  end
+end
+
+# Usage
+model = OpenSkill::Models::PlackettLuce.new
+alice = Player.new("Alice", model)
+bob = Player.new("Bob", model)
+
+# Play match
+teams = [[alice.to_rating(model)], [bob.to_rating(model)]]
+updated = model.calculate_ratings(teams)
+
+# Update players
+alice.update_from_rating!(updated[0][0])
+bob.update_from_rating!(updated[1][0])
+```
+
+## Testing
+
+```bash
+bundle install
+bundle exec rake test
+```
+
+## Development
+
+This gem follows the [OpenSkill specification](https://openskill.me) and maintains compatibility with the Python reference implementation.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.
+
+## References
+
+- [OpenSkill Python Implementation](https://github.com/vivekjoshy/openskill.py)
+- [OpenSkill Documentation](https://openskill.me)
+- Original Paper: [A Bayesian Approximation Method for Online Ranking](https://jmlr.org/papers/v12/weng11a.html) by Ruby C. Weng and Chih-Jen Lin
+
+## Acknowledgments
+
+This Ruby implementation is based on the excellent [openskill.py](https://github.com/vivekjoshy/openskill.py) Python library by Vivek Joshy.
+
+The Plackett-Luce model implemented here is based on the work by Weng and Lin (2011), providing a faster and more accessible alternative to Microsoft's TrueSkill system.

data/lib/openskill/models/common.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module OpenSkill
+  module Models
+    # Common utility functions shared across models
+    module Common
+      # Normalize a vector to a target range
+      #
+      # @param vector [Array<Numeric>] the input vector
+      # @param target_min [Numeric] the target minimum value
+      # @param target_max [Numeric] the target maximum value
+      # @return [Array<Float>] the normalized vector
+      def self.normalize(vector, target_min, target_max)
+        return [] if vector.empty?
+
+        source_min = vector.min
+        source_max = vector.max
+        source_range = source_max - source_min
+
+        # If all values are the same, return target_min for all
+        return Array.new(vector.size, target_min.to_f) if source_range.zero?
+
+        target_range = target_max - target_min
+
+        vector.map do |value|
+          ((value - source_min) / source_range) * target_range + target_min
+        end
+      end
+
+      # Transpose a 2D matrix
+      #
+      # @param matrix [Array<Array>] the input matrix
+      # @return [Array<Array>] the transposed matrix
+      def self.matrix_transpose(matrix)
+        return [] if matrix.empty? || matrix[0].empty?
+
+        matrix[0].zip(*matrix[1..])
+      end
+
+      # Sort objects by tenet and return both sorted objects and indices to restore order
+      #
+      # @param tenet [Array<Numeric>] values to sort by
+      # @param objects [Array] objects to sort
+      # @return [Array<(Array, Array<Numeric>)>] sorted objects and restoration indices
+      def self.unwind(tenet, objects)
+        return [[], []] if objects.empty?
+
+        # Create array of [tenet_value, [object, original_index]]
+        indexed = tenet.each_with_index.map { |t, i| [t, [objects[i], i]] }
+
+        # Sort by tenet value
+        sorted = indexed.sort_by { |t, _| t }
+
+        # Extract sorted objects and their indices
+        sorted_objects = sorted.map { |_, (obj, _)| obj }
+        restoration_indices = sorted.map { |_, (_, idx)| idx }
+
+        [sorted_objects, restoration_indices]
+      end
+    end
+  end
+end

data/lib/openskill/models/plackett_luce.rb

@@ -0,0 +1,694 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require_relative '../statistics/normal'
+require_relative 'common'
+
+module OpenSkill
+  module Models
+    # Plackett-Luce rating model
+    #
+    # This is a Bayesian rating system for multiplayer games that can handle
+    # teams of varying sizes and asymmetric matches.
+    class PlackettLuce
+      attr_reader :mu, :sigma, :beta, :kappa, :tau, :margin, :limit_sigma, :balance, :gamma
+
+      # Default gamma function for PlackettLuce
+      DEFAULT_GAMMA = lambda do |_c, _k, _mu, sigma_squared, _team, _rank, _weights|
+        Math.sqrt(sigma_squared) / _c
+      end
+
+      # @param mu [Float] initial mean skill rating
+      # @param sigma [Float] initial standard deviation
+      # @param beta [Float] performance uncertainty
+      # @param kappa [Float] minimum variance (regularization)
+      # @param gamma [Proc] custom gamma function
+      # @param tau [Float] dynamics factor (skill decay)
+      # @param margin [Float] score margin for impressive wins
+      # @param limit_sigma [Boolean] prevent sigma from increasing
+      # @param balance [Boolean] emphasize rating outliers
+      def initialize(
+        mu: 25.0,
+        sigma: 25.0 / 3.0,
+        beta: 25.0 / 6.0,
+        kappa: 0.0001,
+        gamma: DEFAULT_GAMMA,
+        tau: 25.0 / 300.0,
+        margin: 0.0,
+        limit_sigma: false,
+        balance: false
+      )
+        @mu = mu.to_f
+        @sigma = sigma.to_f
+        @beta = beta.to_f
+        @kappa = kappa.to_f
+        @gamma = gamma
+        @tau = tau.to_f
+        @margin = margin.to_f
+        @limit_sigma = limit_sigma
+        @balance = balance
+      end
+
+      # Create a new rating with default or custom parameters
+      #
+      # @param mu [Float, nil] override default mu
+      # @param sigma [Float, nil] override default sigma
+      # @param name [String, nil] optional player name
+      # @return [Rating] a new rating object
+      def create_rating(mu: nil, sigma: nil, name: nil)
+        Rating.new(
+          mu: mu || @mu,
+          sigma: sigma || @sigma,
+          name: name
+        )
+      end
+
+      # Load a rating from an array [mu, sigma]
+      #
+      # @param rating_array [Array<Numeric>] [mu, sigma]
+      # @param name [String, nil] optional player name
+      # @return [Rating] a new rating object
+      # @raise [ArgumentError] if rating_array is invalid
+      def load_rating(rating_array, name: nil)
+        raise ArgumentError, "Rating must be an Array, got #{rating_array.class}" unless rating_array.is_a?(Array)
+        raise ArgumentError, 'Rating array must have exactly 2 elements' unless rating_array.size == 2
+        raise ArgumentError, 'Rating values must be numeric' unless rating_array.all? { |v| v.is_a?(Numeric) }
+
+        Rating.new(mu: rating_array[0], sigma: rating_array[1], name: name)
+      end
+
+      # Calculate new ratings after a match
+      #
+      # @param teams [Array<Array<Rating>>] list of teams
+      # @param ranks [Array<Numeric>, nil] team ranks (lower is better, 0-indexed)
+      # @param scores [Array<Numeric>, nil] team scores (higher is better)
+      # @param weights [Array<Array<Numeric>>, nil] player contribution weights
+      # @param tau [Float, nil] override tau for this match
+      # @param limit_sigma [Boolean, nil] override limit_sigma for this match
+      # @return [Array<Array<Rating>>] updated teams
+      def calculate_ratings(teams, ranks: nil, scores: nil, weights: nil, tau: nil, limit_sigma: nil)
+        validate_teams!(teams)
+        validate_ranks!(teams, ranks) if ranks
+        validate_scores!(teams, scores) if scores
+        validate_weights!(teams, weights) if weights
+
+        # Can't have both ranks and scores
+        raise ArgumentError, 'Cannot provide both ranks and scores' if ranks && scores
+
+        # Deep copy teams to avoid mutating input
+        original_teams = teams
+        teams = deep_copy_teams(teams)
+
+        # Apply tau (skill decay over time)
+        tau_value = tau || @tau
+        tau_squared = tau_value**2
+        teams.each do |team|
+          team.each do |player|
+            player.sigma = Math.sqrt(player.sigma**2 + tau_squared)
+          end
+        end
+
+        # Convert scores to ranks if provided
+        if !ranks && scores
+          ranks = scores.map { |s| -s }
+          ranks = calculate_rankings(teams, ranks)
+        end
+
+        # Normalize weights to [1, 2] range
+        weights = weights.map { |w| Common.normalize(w, 1, 2) } if weights
+
+        # Sort teams by rank and track original order
+        tenet = nil
+        if ranks
+          sorted_objects, restoration_indices = Common.unwind(ranks, teams)
+          teams = sorted_objects
+          tenet = restoration_indices
+
+          weights, = Common.unwind(ranks, weights) if weights
+
+          ranks = ranks.sort
+        end
+
+        # Compute new ratings
+        result = compute_ratings(teams, ranks: ranks, scores: scores, weights: weights)
+
+        # Restore original order
+        result, = Common.unwind(tenet, result) if ranks && tenet
+
+        # Apply sigma limiting if requested
+        limit_sigma_value = limit_sigma.nil? ? @limit_sigma : limit_sigma
+        if limit_sigma_value
+          result = result.each_with_index.map do |team, team_idx|
+            team.each_with_index.map do |player, player_idx|
+              player.sigma = [player.sigma, original_teams[team_idx][player_idx].sigma].min
+              player
+            end
+          end
+        end
+
+        result
+      end
+
+      # Predict win probability for each team
+      #
+      # @param teams [Array<Array<Rating>>] list of teams
+      # @return [Array<Float>] probability each team wins
+      def predict_win_probability(teams)
+        validate_teams!(teams)
+
+        n = teams.size
+
+        # Special case for 2 teams
+        if n == 2
+          team_ratings = calculate_team_ratings(teams)
+          a = team_ratings[0]
+          b = team_ratings[1]
+
+          result = phi_major(
+            (a.mu - b.mu) / Math.sqrt(2 * @beta**2 + a.sigma_squared + b.sigma_squared)
+          )
+          return [result, 1 - result]
+        end
+
+        # For n teams, compute pairwise probabilities
+        team_ratings = teams.map { |team| calculate_team_ratings([team])[0] }
+
+        win_probs = []
+        team_ratings.each_with_index do |team_i, i|
+          prob_sum = 0.0
+          team_ratings.each_with_index do |team_j, j|
+            next if i == j
+
+            prob_sum += phi_major(
+              (team_i.mu - team_j.mu) / Math.sqrt(2 * @beta**2 + team_i.sigma_squared + team_j.sigma_squared)
+            )
+          end
+          win_probs << prob_sum / (n - 1)
+        end
+
+        # Normalize to sum to 1
+        total = win_probs.sum
+        win_probs.map { |p| p / total }
+      end
+
+      # Predict draw probability
+      #
+      # @param teams [Array<Array<Rating>>] list of teams
+      # @return [Float] probability of a draw
+      def predict_draw_probability(teams)
+        validate_teams!(teams)
+
+        total_player_count = teams.sum(&:size)
+        draw_probability = 1.0 / total_player_count
+        draw_margin = Math.sqrt(total_player_count) * @beta * phi_major_inverse((1 + draw_probability) / 2)
+
+        pairwise_probs = []
+        teams.combination(2).each do |team_a, team_b|
+          team_a_ratings = calculate_team_ratings([team_a])
+          team_b_ratings = calculate_team_ratings([team_b])
+
+          mu_a = team_a_ratings[0].mu
+          sigma_a = team_a_ratings[0].sigma_squared
+          mu_b = team_b_ratings[0].mu
+          sigma_b = team_b_ratings[0].sigma_squared
+
+          denominator = Math.sqrt(2 * @beta**2 + sigma_a + sigma_b)
+
+          pairwise_probs << (
+            phi_major((draw_margin - mu_a + mu_b) / denominator) -
+            phi_major((mu_b - mu_a - draw_margin) / denominator)
+          )
+        end
+
+        pairwise_probs.sum / pairwise_probs.size
+      end
+
+      # Predict rank probability for each team
+      #
+      # @param teams [Array<Array<Rating>>] list of teams
+      # @return [Array<Array(Integer, Float)>] rank and probability for each team
+      def predict_rank_probability(teams)
+        validate_teams!(teams)
+
+        n = teams.size
+        team_ratings = calculate_team_ratings(teams)
+
+        # Calculate win probability for each team against all others
+        win_probs = team_ratings.map do |team_i|
+          prob = 0.0
+          team_ratings.each do |team_j|
+            next if team_i == team_j
+
+            prob += phi_major(
+              (team_i.mu - team_j.mu) /
+              Math.sqrt(2 * @beta**2 + team_i.sigma_squared + team_j.sigma_squared)
+            )
+          end
+          prob / (n - 1)
+        end
+
+        # Normalize probabilities
+        total = win_probs.sum
+        normalized_probs = win_probs.map { |p| p / total }
+
+        # Sort by probability (descending) and assign ranks
+        sorted_indices = normalized_probs.each_with_index.sort_by { |prob, _| -prob }
+        ranks = Array.new(n)
+
+        current_rank = 1
+        sorted_indices.each_with_index do |(prob, team_idx), i|
+          current_rank = i + 1 if i > 0 && prob < sorted_indices[i - 1][0]
+          ranks[team_idx] = current_rank
+        end
+
+        ranks.zip(normalized_probs)
+      end
+
+      private
+
+      # Helper for log(1 + x)
+      def log1p(value)
+        Math.log(1 + value)
+      end
+
+      # Rating class for individual players
+      class Rating
+        attr_accessor :mu, :sigma, :name
+        attr_reader :id
+
+        def initialize(mu:, sigma:, name: nil)
+          @id = SecureRandom.hex
+          @mu = mu.to_f
+          @sigma = sigma.to_f
+          @name = name
+        end
+
+        # Calculate display rating (conservative estimate)
+        #
+        # @param z [Float] number of standard deviations
+        # @param alpha [Float] scaling factor
+        # @param target [Float] target adjustment
+        # @return [Float] the ordinal rating
+        def ordinal(z: 3.0, alpha: 1.0, target: 0.0)
+          alpha * ((@mu - z * @sigma) + (target / alpha))
+        end
+
+        def <=>(other)
+          return nil unless other.is_a?(Rating)
+
+          ordinal <=> other.ordinal
+        end
+
+        def <(other)
+          raise ArgumentError, 'comparison with non-Rating' unless other.is_a?(Rating)
+
+          ordinal < other.ordinal
+        end
+
+        def >(other)
+          raise ArgumentError, 'comparison with non-Rating' unless other.is_a?(Rating)
+
+          ordinal > other.ordinal
+        end
+
+        def <=(other)
+          raise ArgumentError, 'comparison with non-Rating' unless other.is_a?(Rating)
+
+          ordinal <= other.ordinal
+        end
+
+        def >=(other)
+          raise ArgumentError, 'comparison with non-Rating' unless other.is_a?(Rating)
+
+          ordinal >= other.ordinal
+        end
+
+        def ==(other)
+          return false unless other.is_a?(Rating)
+
+          @mu == other.mu && @sigma == other.sigma
+        end
+
+        def hash
+          [@id, @mu, @sigma].hash
+        end
+
+        def eql?(other)
+          self == other
+        end
+
+        def to_s
+          "Rating(mu=#{@mu}, sigma=#{@sigma}#{", name=#{@name}" if @name})"
+        end
+
+        def inspect
+          to_s
+        end
+      end
+
+      # Internal class for team ratings
+      class TeamRating
+        attr_reader :mu, :sigma_squared, :team, :rank
+
+        def initialize(mu:, sigma_squared:, team:, rank:)
+          @mu = mu.to_f
+          @sigma_squared = sigma_squared.to_f
+          @team = team
+          @rank = rank.to_i
+        end
+
+        def ==(other)
+          return false unless other.is_a?(TeamRating)
+
+          @mu == other.mu &&
+            @sigma_squared == other.sigma_squared &&
+            @team == other.team &&
+            @rank == other.rank
+        end
+
+        def hash
+          [@mu, @sigma_squared, @team, @rank].hash
+        end
+
+        def to_s
+          "TeamRating(mu=#{@mu}, sigma_squared=#{@sigma_squared}, rank=#{@rank})"
+        end
+      end
+
+      # Validate teams structure
+      def validate_teams!(teams)
+        raise ArgumentError, 'Teams must be an Array' unless teams.is_a?(Array)
+        raise ArgumentError, 'Must have at least 2 teams' if teams.size < 2
+
+        teams.each_with_index do |team, idx|
+          raise ArgumentError, "Team #{idx} must be an Array" unless team.is_a?(Array)
+          raise ArgumentError, "Team #{idx} must have at least 1 player" if team.empty?
+
+          team.each do |player|
+            raise ArgumentError, "All players must be Rating objects, got #{player.class}" unless player.is_a?(Rating)
+          end
+        end
+      end
+
+      # Validate ranks
+      def validate_ranks!(teams, ranks)
+        raise ArgumentError, "Ranks must be an Array, got #{ranks.class}" unless ranks.is_a?(Array)
+        raise ArgumentError, 'Ranks must have same length as teams' if ranks.size != teams.size
+
+        ranks.each do |rank|
+          raise ArgumentError, "All ranks must be numeric, got #{rank.class}" unless rank.is_a?(Numeric)
+        end
+      end
+
+      # Validate scores
+      def validate_scores!(teams, scores)
+        raise ArgumentError, "Scores must be an Array, got #{scores.class}" unless scores.is_a?(Array)
+        raise ArgumentError, 'Scores must have same length as teams' if scores.size != teams.size
+
+        scores.each do |score|
+          raise ArgumentError, "All scores must be numeric, got #{score.class}" unless score.is_a?(Numeric)
+        end
+      end
+
+      # Validate weights
+      def validate_weights!(teams, weights)
+        raise ArgumentError, "Weights must be an Array, got #{weights.class}" unless weights.is_a?(Array)
+        raise ArgumentError, 'Weights must have same length as teams' if weights.size != teams.size
+
+        weights.each_with_index do |team_weights, idx|
+          raise ArgumentError, "Weights for team #{idx} must be an Array" unless team_weights.is_a?(Array)
+          unless team_weights.size == teams[idx].size
+            raise ArgumentError, "Weights for team #{idx} must match team size"
+          end
+
+          team_weights.each do |weight|
+            raise ArgumentError, "All weights must be numeric, got #{weight.class}" unless weight.is_a?(Numeric)
+          end
+        end
+      end
+
+      # Deep copy teams to avoid mutation
+      def deep_copy_teams(teams)
+        teams.map do |team|
+          team.map do |player|
+            Rating.new(mu: player.mu, sigma: player.sigma, name: player.name).tap do |new_player|
+              # Preserve the original player's ID
+              new_player.instance_variable_set(:@id, player.id)
+            end
+          end
+        end
+      end
+
+      # Calculate collective team sigma (c)
+      def collective_team_sigma(team_ratings)
+        beta_squared = @beta**2
+        sum = team_ratings.sum { |team| team.sigma_squared + beta_squared }
+        Math.sqrt(sum)
+      end
+
+      # Calculate sum_q values for PlackettLuce algorithm
+      def sum_q_values(team_ratings, c_value, scores: nil)
+        score_mapping = {}
+        if scores && scores.size == team_ratings.size
+          team_ratings.each_with_index do |_team, i|
+            score_mapping[i] = scores[i]
+          end
+        end
+
+        sum_q = {}
+        team_ratings.each_with_index do |team_i, i|
+          adjusted_mu = team_i.mu
+
+          # Apply margin factor if scores provided
+          if scores && score_mapping.key?(i)
+            margin_adjustment = 0.0
+            comparison_count = 0
+
+            team_ratings.each_with_index do |team_j, j|
+              next if i == j || !score_mapping.key?(j)
+
+              score_diff = (score_mapping[i] - score_mapping[j]).abs
+              next unless score_diff > 0
+
+              margin_factor = 1.0
+              margin_factor = log1p(score_diff / @margin) if score_diff > @margin && @margin > 0.0
+
+              if score_mapping[i] > score_mapping[j]
+                margin_adjustment += (team_i.mu - team_j.mu) * (margin_factor - 1.0)
+              else
+                margin_adjustment -= (team_j.mu - team_i.mu) * (margin_factor - 1.0)
+              end
+              comparison_count += 1
+            end
+
+            adjusted_mu += comparison_count > 0 ? (margin_adjustment / comparison_count) : margin_adjustment
+          end
+
+          summed = Math.exp(adjusted_mu / c_value)
+
+          team_ratings.each_with_index do |team_q, q|
+            next unless team_i.rank >= team_q.rank
+
+            sum_q[q] = (sum_q[q] || 0) + summed
+          end
+        end
+
+        sum_q.sort.map { |_, v| v }
+      end
+
+      # Count how many teams share each rank
+      def count_rank_occurrences(team_ratings)
+        team_ratings.map do |team_i|
+          team_ratings.count { |team_q| team_q.rank == team_i.rank }
+        end
+      end
+
+      # Calculate team ratings from individual player ratings
+      def calculate_team_ratings(game, ranks: nil, weights: nil)
+        ranks ||= calculate_rankings(game)
+
+        game.each_with_index.map do |team, idx|
+          sorted_team = team.sort_by { |p| -p.ordinal }
+          max_ordinal = sorted_team.first.ordinal
+
+          mu_sum = 0.0
+          sigma_squared_sum = 0.0
+
+          sorted_team.each do |player|
+            balance_weight = if @balance
+                               ordinal_diff = max_ordinal - player.ordinal
+                               1 + (ordinal_diff / (max_ordinal + @kappa))
+                             else
+                               1.0
+                             end
+
+            mu_sum += player.mu * balance_weight
+            sigma_squared_sum += (player.sigma * balance_weight)**2
+          end
+
+          TeamRating.new(
+            mu: mu_sum,
+            sigma_squared: sigma_squared_sum,
+            team: team,
+            rank: ranks[idx].to_i
+          )
+        end
+      end
+
+      # Calculate rankings from scores or indices
+      def calculate_rankings(game, ranks = nil)
+        return [] if game.empty?
+
+        team_scores = if ranks
+                        ranks.each_with_index.map { |rank, idx| rank || idx }
+                      else
+                        game.each_index.to_a
+                      end
+
+        sorted_scores = team_scores.sort
+        rank_map = {}
+        sorted_scores.each_with_index do |value, index|
+          rank_map[value] ||= index
+        end
+
+        team_scores.map { |score| rank_map[score].to_f }
+      end
+
+      # Core rating computation algorithm
+      def compute_ratings(teams, ranks: nil, scores: nil, weights: nil)
+        team_ratings = calculate_team_ratings(teams, ranks: ranks)
+        c_value = collective_team_sigma(team_ratings)
+        sum_q = sum_q_values(team_ratings, c_value, scores: scores)
+        a_values = count_rank_occurrences(team_ratings)
+
+        # Build score mapping for margin calculations
+        score_mapping = {}
+        if scores && scores.size == team_ratings.size
+          team_ratings.each_with_index do |_, i|
+            score_mapping[i] = scores[i]
+          end
+        end
+
+        # Group teams by rank for tie handling
+        rank_groups = {}
+        team_ratings.each_with_index do |team, i|
+          rank_groups[team.rank] ||= []
+          rank_groups[team.rank] << i
+        end
+
+        result = team_ratings.each_with_index.map do |team_i, i|
+          omega = 0.0
+          delta = 0.0
+
+          # Calculate adjusted mu with margin
+          adjusted_mu_i = team_i.mu
+          if scores && score_mapping.key?(i)
+            margin_adjustment = 0.0
+            comparison_count = 0
+
+            team_ratings.each_with_index do |team_j, j|
+              next if i == j || !score_mapping.key?(j)
+
+              score_diff = (score_mapping[i] - score_mapping[j]).abs
+              next unless score_diff > 0
+
+              margin_factor = 1.0
+              margin_factor = log1p(score_diff / @margin) if score_diff > @margin && @margin > 0.0
+
+              if score_mapping[i] > score_mapping[j]
+                margin_adjustment += (team_i.mu - team_j.mu) * (margin_factor - 1.0)
+              else
+                margin_adjustment -= (team_j.mu - team_i.mu) * (margin_factor - 1.0)
+              end
+              comparison_count += 1
+            end
+
+            adjusted_mu_i += comparison_count > 0 ? (margin_adjustment / comparison_count) : margin_adjustment
+          end
+
+          i_mu_over_c = Math.exp(adjusted_mu_i / c_value)
+
+          # Calculate omega and delta
+          team_ratings.each_with_index do |team_q, q|
+            next unless team_q.rank <= team_i.rank
+
+            i_mu_over_ce_over_sum_q = i_mu_over_c / sum_q[q]
+
+            delta += i_mu_over_ce_over_sum_q * (1 - i_mu_over_ce_over_sum_q) / a_values[q]
+
+            if q == i
+              omega += (1 - i_mu_over_ce_over_sum_q) / a_values[q]
+            else
+              omega -= i_mu_over_ce_over_sum_q / a_values[q]
+            end
+          end
+
+          omega *= team_i.sigma_squared / c_value
+          delta *= team_i.sigma_squared / (c_value**2)
+
+          # Apply gamma
+          team_weights = weights ? weights[i] : nil
+          gamma_value = @gamma.call(
+            c_value,
+            team_ratings.size,
+            team_i.mu,
+            team_i.sigma_squared,
+            team_i.team,
+            team_i.rank,
+            team_weights
+          )
+          delta *= gamma_value
+
+          # Update each player in the team
+          team_i.team.each_with_index.map do |player, j|
+            weight = weights ? weights[i][j] : 1.0
+
+            new_mu = player.mu
+            new_sigma = player.sigma
+
+            if omega >= 0
+              new_mu += (new_sigma**2 / team_i.sigma_squared) * omega * weight
+              new_sigma *= Math.sqrt(
+                [1 - (new_sigma**2 / team_i.sigma_squared) * delta * weight, @kappa].max
+              )
+            else
+              new_mu += (new_sigma**2 / team_i.sigma_squared) * omega / weight
+              new_sigma *= Math.sqrt(
+                [1 - (new_sigma**2 / team_i.sigma_squared) * delta / weight, @kappa].max
+              )
+            end
+
+            player.mu = new_mu
+            player.sigma = new_sigma
+            player
+          end
+        end
+
+        # Handle ties - average mu changes for tied teams
+        rank_groups.each do |_rank, indices|
+          next unless indices.size > 1
+
+          avg_mu_change = indices.sum { |i| result[i][0].mu - teams[i][0].mu } / indices.size.to_f
+
+          indices.each do |i|
+            result[i].each_with_index do |player, j|
+              player.mu = teams[i][j].mu + avg_mu_change
+            end
+          end
+        end
+
+        result
+      end
+
+      # Normal distribution CDF
+      def phi_major(value)
+        Statistics::Normal.cdf(value)
+      end
+
+      # Normal distribution inverse CDF
+      def phi_major_inverse(value)
+        Statistics::Normal.inv_cdf(value)
+      end
+    end
+  end
+end

data/lib/openskill/statistics/normal.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'distribution'
+
+module OpenSkill
+  module Statistics
+    # Wrapper for normal distribution functions
+    class Normal
+      # Normal cumulative distribution function (CDF)
+      #
+      # @param x [Float] the value
+      # @return [Float] the cumulative probability
+      def self.cdf(x)
+        Distribution::Normal.cdf(x)
+      end
+
+      # Normal inverse cumulative distribution function (inverse CDF)
+      #
+      # @param x [Float] the probability (0 to 1)
+      # @return [Float] the value at that probability
+      def self.inv_cdf(x)
+        Distribution::Normal.p_value(x)
+      end
+
+      # Normal probability density function (PDF)
+      #
+      # @param x [Float] the value
+      # @return [Float] the probability density
+      def self.pdf(x)
+        Distribution::Normal.pdf(x)
+      end
+    end
+  end
+end

data/lib/openskill/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module OpenSkill
+  VERSION = '0.1.0'
+end

data/lib/openskill.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative 'openskill/version'
+require_relative 'openskill/statistics/normal'
+require_relative 'openskill/models/common'
+require_relative 'openskill/models/plackett_luce'
+
+module OpenSkill
+  class Error < StandardError; end
+end

metadata

@@ -0,0 +1,118 @@
+--- !ruby/object:Gem::Specification
+name: openskill
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tamas Erdos
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bigdecimal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: distribution
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: prime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: A Ruby implementation of the OpenSkill rating system, providing Bayesian
+  skill ratings for multiplayer games
+email:
+- tamas at tamaserdos.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/openskill.rb
+- lib/openskill/models/common.rb
+- lib/openskill/models/plackett_luce.rb
+- lib/openskill/statistics/normal.rb
+- lib/openskill/version.rb
+homepage: https://github.com/erdostom/openskill-ruby
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Multiplayer rating system for Ruby
+test_files: []