equalshares 0.1.0

data/lib/equalshares/rules/method_of_equal_shares.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Equalshares
+  module Rules
+    # The Method of Equal Shares for approval ballots — the equalshares.net rule,
+    # including its completion methods (none/utilitarian/add1/...) and comparison step.
+    # Faithful port of equalShares() in js/methodOfEqualSharesWorker.js.
+    #
+    # Cost and budget are treated as floats at this level (statistics, comparison,
+    # utilitarian/greedy committees, the everything-affordable check); only the inner
+    # fixed-budget MES loop switches to exact rationals for accuracy "fractions".
+    class MethodOfEqualShares < Base
+      ADD1_COMPLETIONS = %w[add1 add1e add1u add1eu].freeze
+      UTILITARIAN_COMPLETIONS = %w[utilitarian add1u].freeze
+
+      def call
+        start = now
+        voter_ids = election.voter_ids
+        project_ids = election.project_ids
+        approvers = election.approvers
+
+        # Strings for the MES loop (it wraps them per accuracy); floats for the
+        # completion/comparison/statistics bookkeeping (as the JS does).
+        cost_source = project_ids.to_h { |c| [c, instance.projects[c]["cost"]] }
+        cost = election.float_costs
+        b_float = election.float_budget
+
+        mes = run_mes(cost_source, instance.budget)
+        winners = mes.fetch(:winners)
+        report = mes.fetch(:report)
+        notes = {
+          endowment: report[:endowment],
+          money_behind_candidate: report[:money_behind_candidate],
+          effective_vote_count: report[:effective_vote_count]
+        }
+
+        # utilitarian completion if needed
+        if UTILITARIAN_COMPLETIONS.include?(params.completion)
+          completion = Completion.utilitarian(voter_ids, project_ids, cost, approvers, b_float, winners)
+          winners = completion.fetch(:winners)
+          notes[:added_by_utilitarian_completion] = completion.fetch(:added)
+        end
+
+        # comparison step
+        greedy = Completion.utilitarian(voter_ids, project_ids, cost, approvers, b_float, []).fetch(:winners)
+        unless params.comparison == "none"
+          cmp = Comparison.comparison_step(voter_ids, approvers, greedy, winners, params)
+          unless cmp[:stick_to_mes]
+            winners = greedy
+            notes[:comparison] =
+              "The committee chosen by the greedy algorithm is preferred by #{cmp[:prefers_greedy]} voters, " \
+              "while the committee chosen by the method of equal shares is preferred by #{cmp[:prefers_mes]} voters."
+          end
+        end
+
+        notes[:greedy_stats] = election.statistics(greedy)
+        result(winners, start, notes)
+      end
+
+      private
+
+      def run_mes(cost_source, budget_source)
+        voter_ids = election.voter_ids
+        project_ids = election.project_ids
+        approvers = election.approvers
+        everything_affordable = election.float_costs.values.sum <= election.float_budget
+
+        if %w[none utilitarian].include?(params.completion) || everything_affordable
+          # don't use Add1 if everything is affordable
+          FixedBudget.run(voter_ids, project_ids, cost_source, approvers, budget_source, params,
+                          report_details: true, progress: progress)
+        elsif ADD1_COMPLETIONS.include?(params.completion)
+          Completion.add1(voter_ids, project_ids, cost_source, approvers, budget_source, params, progress: progress)
+        else
+          raise ComputeError, "Unknown completion rule: #{params.completion}"
+        end
+      end
+    end
+  end
+end

data/lib/equalshares/rules/phragmen.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Equalshares
+  module Rules
+    # Phragmén's sequential rule for approval participatory budgeting. Faithful port of
+    # pabutools' sequential_phragmen (resolute case).
+    #
+    # Voters accumulate "load" (starting at 0). Buying a project raises all its
+    # approvers to a common load level (sum of their loads + cost) / |approvers|. At
+    # each step the project minimising that new maximum load is bought; the rule stops
+    # once the next project to buy would exceed the budget.
+    class Phragmen < Base
+      def call
+        start = now
+        project_ids = election.project_ids
+        approvers = election.approvers
+        cost = election.costs
+        budget_limit = election.budget
+        approval_score = project_ids.to_h { |c| [c, approvers[c].length] }
+
+        loads = Hash.new(0) # voter id -> current load
+        remaining = project_ids.select { |c| cost[c] <= budget_limit }
+        winners = []
+        current_cost = 0
+
+        loop do
+          break if remaining.empty?
+
+          min_maxload, argmin = min_new_maxload(remaining, approvers, loads, cost, approval_score)
+
+          # Stop as soon as the next project to be bought would violate the budget.
+          break if argmin.any? { |c| current_cost + cost[c] > budget_limit }
+
+          selected = Tie.resolve_one(project_ids, cost, approvers, params, argmin)
+          approvers[selected].each { |i| loads[i] = min_maxload }
+          winners << selected
+          current_cost += cost[selected]
+          remaining.delete(selected)
+          progress&.call((100 * current_cost / budget_limit).floor)
+        end
+
+        result(winners, start)
+      end
+
+      private
+
+      def min_new_maxload(remaining, approvers, loads, cost, approval_score)
+        min_maxload = nil
+        argmin = []
+        remaining.each do |c|
+          new_maxload =
+            if approval_score[c].zero?
+              Float::INFINITY
+            else
+              (approvers[c].sum { |i| loads[i] } + cost[c]) / approval_score[c]
+            end
+          if min_maxload.nil? || new_maxload < min_maxload
+            min_maxload = new_maxload
+            argmin = [c]
+          elsif new_maxload == min_maxload
+            argmin << c
+          end
+        end
+        [min_maxload, argmin]
+      end
+    end
+  end
+end

data/lib/equalshares/satisfaction.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Equalshares
+  # Additive satisfaction measures for approval ballots, matching pabutools.
+  #
+  # For the Method of Equal Shares, only the per-approver marginal utility u_i(c)
+  # of a project matters, and for these measures it is uniform across all approvers
+  # of c (it depends on c, not on i). This lets the fixed-budget loop stay unchanged
+  # in its payment mechanics (each project still has to raise its full cost, split as
+  # equally as possible) while the *selection* criterion becomes u(c) / maxPayment.
+  #
+  #   Cost_Sat        u(c) = cost(c)                 (equalshares.net default)
+  #   Cardinality_Sat u(c) = 1
+  #
+  # Both are verified to match pabutools exactly (Cost_Sat and Cardinality_Sat).
+  # Each strategy returns the per-approver utility in the same numeric family as the
+  # cost passed in (Rational for exact mode, Float for float mode), so downstream
+  # arithmetic keeps its accuracy.
+  module Satisfaction
+    module_function
+
+    NAMES = %w[cost cardinality effort].freeze
+
+    def for(name)
+      case name
+      when "cost" then COST
+      when "cardinality" then CARDINALITY
+      when "effort" then EFFORT
+      else
+        raise ComputeError, "Unknown satisfaction measure: #{name} (allowed: #{NAMES.join(', ')})"
+      end
+    end
+
+    # Each measure is a callable per_voter(cost_c, num_approvers) -> Numeric.
+    COST = ->(cost_c, _n) { cost_c }
+    CARDINALITY = ->(_cost_c, _n) { 1 }
+    EFFORT = ->(cost_c, n) { cost_c / n }
+  end
+end

data/lib/equalshares/statistics.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Equalshares
+  # Outcome statistics. Faithful port of gatherOutcomeStatistics() in
+  # js/methodOfEqualSharesWorker.js.
+  module Statistics
+    module_function
+
+    # `cost` is the numeric cost map (Float or Rational).
+    def gather(voter_ids, cost, approvers, winners)
+      n = voter_ids.length
+      total_cost = winners.sum { |c| cost[c] }
+      avg_approved_projects = winners.sum { |c| approvers[c].length }.to_f / n
+      avg_cost_of_winning_approved = winners.sum { |c| approvers[c].length * cost[c] }.to_f / n
+
+      voter_utility = Hash.new(0)
+      winners.each do |c|
+        approvers[c].each { |i| voter_utility[i] += 1 }
+      end
+
+      # For each r, how many voters approve exactly r winning projects?
+      utility_distribution = {}
+      (0..winners.length).each { |util| utility_distribution[util] = 0 }
+      voter_ids.each { |i| utility_distribution[voter_utility[i]] += 1 }
+
+      {
+        total_cost: total_cost,
+        avg_approved_projects: avg_approved_projects,
+        avg_cost_of_winning_approved_projects: avg_cost_of_winning_approved,
+        utility_distribution: utility_distribution
+      }
+    end
+  end
+end

data/lib/equalshares/tie_breaker.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Equalshares
+  # Tie-breaking strategies. Each element of params.tie_breaking maps to one strategy
+  # object (via TieBreaker.for). A strategy can either narrow a tied set (#filter, used
+  # to resolve a single tie in priority order) or contribute a sort key (#sort_key, used
+  # to build a total order over all projects). Mirrors pabutools' TieBreakingRule.
+  module TieBreaker
+    # Cost/approver lookups a strategy needs. `cost` is the rule's numeric cost map.
+    Context = Struct.new(:cost, :approvers)
+
+    module_function
+
+    def for(method)
+      case method
+      when "maxVotes" then MaxVotes.new
+      when "minCost" then MinCost.new
+      when "maxCost" then MaxCost.new
+      when Hash then Lexico.new(lexico_order(method))
+      when Array then ExplicitList.new(method)
+      else
+        raise ComputeError, "Unknown tie-breaking method: #{method}"
+      end
+    end
+
+    def lexico_order(method)
+      order = method[:lexico] || method["lexico"]
+      raise ComputeError, "Unknown tie-breaking method: #{method}" unless order.is_a?(Array)
+
+      order
+    end
+
+    # Keep the projects tied at the best value of some key.
+    class Extreme
+      def filter(remaining, ctx)
+        best = remaining.map { |c| key(c, ctx) }.public_send(extreme)
+        remaining.select { |c| key(c, ctx) == best }
+      end
+    end
+
+    class MaxVotes < Extreme
+      def key(project_id, ctx) = ctx.approvers[project_id].length
+      def extreme = :max
+      def sort_key(project_id, ctx) = -ctx.approvers[project_id].length
+    end
+
+    class MinCost < Extreme
+      def key(project_id, ctx) = ctx.cost[project_id]
+      def extreme = :min
+      def sort_key(project_id, ctx) = ctx.cost[project_id]
+    end
+
+    class MaxCost < Extreme
+      def key(project_id, ctx) = ctx.cost[project_id]
+      def extreme = :max
+      def sort_key(project_id, ctx) = -ctx.cost[project_id]
+    end
+
+    # A total order (pabutools-style): rank tied projects by their position in the list
+    # and keep the first.
+    class Lexico
+      def initialize(order)
+        @order = order
+        @position = order.each_with_index.to_h
+      end
+
+      def filter(remaining, _ctx)
+        [remaining.min_by { |c| @position[c] || @order.length }]
+      end
+
+      def sort_key(project_id, _ctx)
+        @position[project_id] || @order.length
+      end
+    end
+
+    # JS-faithful explicit list: keep the first *choice* that appears anywhere in the
+    # list (does NOT respect the list's ordering). Kept for bit-compatibility with the
+    # equalshares.net tool; prefer Lexico for an order-respecting tie-break.
+    class ExplicitList
+      def initialize(list)
+        @list = list
+        @position = list.each_with_index.to_h
+      end
+
+      def filter(remaining, _ctx)
+        found = remaining.find { |c| @list.include?(c) }
+        found ? [found] : remaining
+      end
+
+      def sort_key(project_id, _ctx)
+        @position[project_id] || @list.length
+      end
+    end
+  end
+end

data/lib/equalshares/tie_breaking.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Equalshares
+  # Tie-breaking facade. Composes the TieBreaker strategies named in params.tie_breaking
+  # to either resolve a single tie (break_ties) or build a total order (total_order).
+  module Tie
+    module_function
+
+    # Resolve a tie among `choices` by applying each tie-breaking strategy in priority
+    # order, narrowing the set. Returns the surviving candidates (callers treat more
+    # than one as an unresolved tie).
+    def break_ties(_project_ids, cost, approvers, params, choices)
+      ctx = TieBreaker::Context.new(cost, approvers)
+      remaining = params.tie_breaking.reduce(choices.dup) do |current, method|
+        TieBreaker.for(method).filter(current, ctx)
+      end
+
+      raise ComputeError, "Tie-breaking failed in a way that should not happen: #{choices}" if remaining.empty?
+
+      remaining
+    end
+
+    # Resolve a tie down to a single winner, raising if the tie-breaking rules leave
+    # more than one candidate. Used by the sequential rules.
+    def resolve_one(project_ids, cost, approvers, params, choices)
+      resolved = break_ties(project_ids, cost, approvers, params, choices)
+      if resolved.length > 1
+        raise ComputeError,
+              "Tie-breaking failed: tie between projects #{resolved.join(', ')} could not be resolved. " \
+              "Another tie-breaking needs to be added."
+      end
+      resolved[0]
+    end
+
+    # A total order of all projects induced by params.tie_breaking, used by rules that
+    # need a full ordering (e.g. greedy welfare). Projects are sorted by each strategy's
+    # sort key in priority order, falling back to their original (JS Object.keys) order.
+    def total_order(project_ids, cost, approvers, params)
+      ctx = TieBreaker::Context.new(cost, approvers)
+      strategies = params.tie_breaking.map { |method| TieBreaker.for(method) }
+      base_index = project_ids.each_with_index.to_h
+
+      project_ids.sort_by do |c|
+        strategies.map { |strategy| strategy.sort_key(c, ctx) } + [base_index[c]]
+      end
+    end
+  end
+end

data/lib/equalshares/version.rb

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

data/lib/equalshares.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "equalshares/version"
+require_relative "equalshares/errors"
+require_relative "equalshares/instance"
+require_relative "equalshares/satisfaction"
+require_relative "equalshares/params"
+require_relative "equalshares/pabulib"
+require_relative "equalshares/tie_breaker"
+require_relative "equalshares/tie_breaking"
+require_relative "equalshares/statistics"
+require_relative "equalshares/election"
+require_relative "equalshares/fixed_budget"
+require_relative "equalshares/completion"
+require_relative "equalshares/comparison"
+require_relative "equalshares/max_flow"
+require_relative "equalshares/result"
+
+# Rule objects
+require_relative "equalshares/rules/base"
+require_relative "equalshares/rules/method_of_equal_shares"
+require_relative "equalshares/rules/cardinal_mes"
+require_relative "equalshares/rules/phragmen"
+require_relative "equalshares/rules/greedy"
+require_relative "equalshares/rules/maximin"
+
+# Facades over the rule objects (stable public API)
+require_relative "equalshares/phragmen"
+require_relative "equalshares/greedy"
+require_relative "equalshares/maximin"
+require_relative "equalshares/mes_general"
+require_relative "equalshares/compute"
+
+module Equalshares
+  # Convenience: parse a .pb file and compute the outcome in one call.
+  def self.compute_file(path, params = Params.new, progress: nil)
+    instance = Pabulib.parse_file(path)
+    Compute.equal_shares(instance, params, progress: progress)
+  end
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: equalshares
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- takahashim
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: A Ruby implementation of the equalshares.net compute tool. Parses pabulib
+  (.pb) files and computes winning projects using the Method of Equal Shares (with
+  tie-breaking, Add1/utilitarian completion and a comparison step), plus Phragmén's
+  sequential rule, greedy utilitarian welfare and maximin support. Supports approval,
+  cardinal (scoring/cumulative) and ordinal ballots, several satisfaction measures,
+  and both exact (Rational) and floating-point arithmetic. Cross-checked against pabutools.
+email:
+- takahashimm@gmail.com
+executables:
+- equalshares
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- exe/equalshares
+- lib/equalshares.rb
+- lib/equalshares/cli.rb
+- lib/equalshares/cli/formatter.rb
+- lib/equalshares/comparison.rb
+- lib/equalshares/completion.rb
+- lib/equalshares/compute.rb
+- lib/equalshares/election.rb
+- lib/equalshares/errors.rb
+- lib/equalshares/fixed_budget.rb
+- lib/equalshares/greedy.rb
+- lib/equalshares/instance.rb
+- lib/equalshares/max_flow.rb
+- lib/equalshares/maximin.rb
+- lib/equalshares/mes_general.rb
+- lib/equalshares/pabulib.rb
+- lib/equalshares/pabulib/csv.rb
+- lib/equalshares/pabulib/parser.rb
+- lib/equalshares/pabulib/project_row_parser.rb
+- lib/equalshares/pabulib/vote_row_parser.rb
+- lib/equalshares/pabulib/writer.rb
+- lib/equalshares/params.rb
+- lib/equalshares/phragmen.rb
+- lib/equalshares/result.rb
+- lib/equalshares/rules/base.rb
+- lib/equalshares/rules/cardinal_mes.rb
+- lib/equalshares/rules/greedy.rb
+- lib/equalshares/rules/maximin.rb
+- lib/equalshares/rules/method_of_equal_shares.rb
+- lib/equalshares/rules/phragmen.rb
+- lib/equalshares/satisfaction.rb
+- lib/equalshares/statistics.rb
+- lib/equalshares/tie_breaker.rb
+- lib/equalshares/tie_breaking.rb
+- lib/equalshares/version.rb
+homepage: https://github.com/takahashim/equalshares
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/takahashim/equalshares
+  source_code_uri: https://github.com/takahashim/equalshares
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Method of Equal Shares computation for participatory budgeting
+test_files: []