equalshares 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bedaa40769542c8d4c0354779a69cecd2f7194f2470ef22127a87eae54a904df
+  data.tar.gz: 0c16a5cc2254befb86a5edcb919e17e9c32832a3debcd754ee6fdf208ce6aafb
+SHA512:
+  metadata.gz: 7eb39a0cebd691d353e114b43bdb1dd155dfe6915e042c2ae1ebba86498cbc0efd310cfb0a0acb0b99cfb66493948230be3a970c9b4bcfd78d1c06ac2baa4f8b
+  data.tar.gz: a1f8fe965faa1be02260e0218ab207cc7aae627197b6ac6421d7a9b4f43c713f8453b65012e77221f7528832ea69b35017de15966fcc232ac9b4c41dc5b0a523

data/LICENSE.txt

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2023 Dominik Peters (original author)
+Copyright (c) 2026 Masayoshi Takahashi (Ruby version)
+
+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,121 @@
+# Equalshares
+
+A Ruby implementation of the [equalshares.net](https://equalshares.net/tools/compute/) compute tool for participatory budgeting.
+It parses [pabulib](http://pabulib.org/) `.pb` files and computes winning projects using the [Method of Equal Shares](https://equalshares.net/) and related rules.
+
+This started as a faithful port of the vanilla-JavaScript
+[equalshares-compute-tool](https://github.com/equalshares/equalshares-compute-tool)
+(parser + Method of Equal Shares) and was then extended for parity with
+[pabutools](https://github.com/COMSOC-Community/pabutools), the academic reference
+implementation. Every rule and satisfaction measure is cross-checked against pabutools
+(see [Tests](#tests)).
+
+Highlights:
+
+- **Rules**: Method of Equal Shares (`mes`), Phragmén's sequential rule (`phragmen`),
+  greedy utilitarian welfare (`greedy`), maximin support (`maximin`).
+- **Ballots**: approval, cardinal (`scoring` / `cumulative`), and ordinal (via Borda).
+- **Satisfaction measures**: `cost` (the equalshares.net default), `cardinality`, `effort`.
+- **Exact or fast**: exact rational arithmetic (`fractions`) or floating point (`floats`).
+- **No runtime dependencies**; the maximin rule is solved with a pure-Ruby max-flow
+  instead of an LP solver.
+
+## Installation
+
+Install from git (or build the gem locally):
+
+```bash
+gem install equalshares
+```
+
+or add to a Gemfile:
+
+```ruby
+gem "equalshares"
+```
+
+## Command line
+
+```bash
+# Compute winners with exact arithmetic
+equalshares path/to/instance.pb --completion add1 --accuracy fractions
+
+# Choose the rule and satisfaction measure
+equalshares instance.pb --rule phragmen
+equalshares instance.pb --rule greedy --satisfaction cardinality
+equalshares instance.pb --rule maximin
+
+# Output formats and tie-breaking
+equalshares instance.pb --format csv
+equalshares instance.pb --format json
+equalshares instance.pb --tie-breaking maxVotes,minCost --comparison satisfaction --progress
+```
+
+Options: `--rule` (`mes`/`phragmen`/`greedy`/`maximin`), `--completion`
+(`none`/`utilitarian`/`add1`/`add1u`/…), `--accuracy` (`floats`/`fractions`),
+`--satisfaction` (`cost`/`cardinality`/`effort`), `--tie-breaking`
+(comma-separated `maxVotes,minCost,maxCost`), `--add1-options` (`exhaustive,integral`),
+`--comparison` (`none`/`satisfaction`/`exclusionRatio`), `--increment N`, `--format`
+(`human`/`csv`/`json`), `--progress`.
+
+## Library
+
+```ruby
+require "equalshares"
+
+instance = Equalshares::Pabulib.parse_file("instance.pb")
+params   = Equalshares::Params.new(completion: "add1u", accuracy: "fractions")
+
+result = Equalshares::Compute.equal_shares(instance, params)
+result[:winners]        # => ["24", "41", ...] winning project IDs
+result[:notes][:stats]  # => total_cost, avg_approved_projects, utility_distribution, ...
+
+# Other rules
+Equalshares::Phragmen.sequential(instance, params)
+Equalshares::Greedy.utilitarian_welfare(instance, Equalshares::Params.new(satisfaction: "cardinality"))
+Equalshares::Maximin.support(instance)
+
+# Serialise back to .pb
+Equalshares::Pabulib.write_file(instance, "out.pb")
+```
+
+### Satisfaction measures
+
+By default MES uses **cost** satisfaction (the equalshares.net rule). `cardinality`
+(each funded approved project counts as 1) and `effort` (cost divided by approver count)
+are also supported and match pabutools' `Cost_Sat`, `Cardinality_Sat` and `Effort_Sat`.
+
+### Ballot types
+
+`scoring` / `cumulative` instances carry per-voter scores (a `points` column); `ordinal`
+instances carry rankings, converted to per-voter **Borda** scores (ballot length − rank
+− 1). In all cases `instance.cardinal?` is true and the utilities feed the general MES
+(`Equalshares::MesGeneral`), verified against pabutools' `Additive_Cardinal_Sat` and
+`Additive_Borda_Sat`.
+
+### Tie-breaking
+
+`params.tie_breaking` is a priority list of: the criteria `"maxVotes"`, `"minCost"`,
+`"maxCost"`; a total order `{ lexico: [ids...] }` that ranks tied projects by their
+position in the list (matches pabutools' lexicographic tie-breaking — the recommended
+form); or a bare `Array`, which reproduces the equalshares.net tool's explicit-list
+behaviour but does **not** respect the list ordering.
+
+## Tests
+
+```bash
+bundle install
+bundle exec rake test
+```
+
+The suite cross-checks the implementation against the original JavaScript tool and
+against pabutools. The pabutools reference fixtures under `test/fixtures/` are committed,
+so the tests run without pabutools installed (the pabutools cross-checks skip if their
+reference JSON is absent). To regenerate a reference, install `pabutools`
+(`pip install pabutools`) and run the corresponding `test/fixtures/generate_*.py` script.
+
+## License
+
+MIT. The Method of Equal Shares algorithm and pabulib parser are ports of the
+MIT-licensed [equalshares-compute-tool](https://github.com/equalshares/equalshares-compute-tool)
+by Dominik Peters. See `LICENSE.txt`.

data/exe/equalshares

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/equalshares"
+require_relative "../lib/equalshares/cli"
+
+exit Equalshares::CLI.start(ARGV)

data/lib/equalshares/cli/formatter.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "json"
+require "csv"
+
+module Equalshares
+  class CLI
+    # Renders a computation Result for a given instance as human-readable text, CSV or
+    # JSON. Each renderer returns a String (including the trailing newline).
+    class Formatter
+      def initialize(instance, result)
+        @instance = instance
+        @result = result
+      end
+
+      def render(format)
+        case format
+        when "json" then json
+        when "csv" then csv
+        else human
+        end
+      end
+
+      def json
+        "#{JSON.pretty_generate(@result.to_h)}\n"
+      end
+
+      def csv
+        CSV.generate do |csv|
+          csv << %w[project_id name cost votes effective_vote_count]
+          @result.winners.each do |c|
+            csv << [c, project(c, "name"), project(c, "cost"),
+                    @instance.approvers[c].length, @result.effective_vote_count(c)]
+          end
+        end
+      end
+
+      def human
+        lines = summary_lines + [""]
+        rows = @result.winners.map do |c|
+          [c, truncate(project(c, "name"), 50), project(c, "cost"),
+           @instance.approvers[c].length.to_s, format_number(@result.effective_vote_count(c))]
+        end
+        "#{(lines + table(%w[id name cost votes eff.votes], rows)).join("\n")}\n"
+      end
+
+      private
+
+      def project(project_id, field)
+        @instance.projects[project_id][field]
+      end
+
+      def summary_lines
+        lines = ["Winners: #{@result.winners.length} projects, " \
+                 "total cost #{format_number(@result.total_cost)} of budget #{@instance.budget}"]
+        lines << "Voter endowment: #{format_number(@result.endowment)}" if @result.endowment
+        lines << "Avg. approved winning projects per voter: #{@result.stats[:avg_approved_projects].round(3)}"
+        lines << "Computation time: #{@result.time}s"
+      end
+
+      def table(headers, rows)
+        widths = headers.each_index.map do |i|
+          ([headers[i]] + rows.map { |r| r[i].to_s }).map(&:length).max
+        end
+        line = ->(cells) { cells.each_index.map { |i| cells[i].to_s.ljust(widths[i]) }.join("  ") }
+        [line.call(headers), widths.map { |w| "-" * w }.join("  ")] + rows.map { |r| line.call(r) }
+      end
+
+      def truncate(str, max)
+        str.to_s.length > max ? "#{str[0, max - 1]}…" : str.to_s
+      end
+
+      def format_number(value)
+        f = value.to_f
+        f == f.round ? f.round.to_s : f.round(2).to_s
+      end
+    end
+  end
+end

data/lib/equalshares/cli.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+require_relative "cli/formatter"
+
+module Equalshares
+  # Command-line interface: parse a .pb file and print the Method of Equal Shares outcome.
+  class CLI
+    def self.start(argv)
+      new.run(argv)
+    end
+
+    # Each rule name maps to a runner (instance, params, progress) -> Result.
+    RULE_RUNNERS = {
+      "mes" => ->(instance, params, progress) { Compute.equal_shares(instance, params, progress: progress) },
+      "phragmen" => ->(instance, params, progress) { Phragmen.sequential(instance, params, progress: progress) },
+      "greedy" => ->(instance, params, _progress) { Greedy.utilitarian_welfare(instance, params) },
+      "maximin" => ->(instance, params, progress) { Maximin.support(instance, params, progress: progress) }
+    }.freeze
+    RULES = RULE_RUNNERS.keys.freeze
+
+    def run(argv)
+      options = { format: "human", progress: false, rule: "mes" }
+      param_opts = {}
+      parser = build_parser(options, param_opts)
+      files = parser.parse(argv)
+
+      if files.length != 1
+        warn parser.help
+        return 2
+      end
+
+      params = Params.new(**param_opts)
+      progress = options[:progress] ? ->(pct) { warn "\rComputing... #{pct}%" } : nil
+
+      instance = Pabulib.parse_file(files.first)
+      result = RULE_RUNNERS.fetch(options[:rule]).call(instance, params, progress)
+      warn "" if options[:progress]
+
+      print Formatter.new(instance, result).render(options[:format])
+      0
+    rescue OptionParser::ParseError => e
+      warn "Error: #{e.message}"
+      2
+    rescue ParseError, ComputeError, Errno::ENOENT => e
+      warn "Error: #{e.message}"
+      1
+    end
+
+    private
+
+    def build_parser(options, param_opts)
+      OptionParser.new do |o|
+        o.banner = "Usage: equalshares [options] FILE.pb"
+        o.separator ""
+        o.separator "Computation options:"
+        o.on("--rule NAME", RULES, "Voting rule: mes (default), phragmen, greedy, maximin") do |v|
+          options[:rule] = v
+        end
+        o.on("--completion NAME", Params::COMPLETIONS, "Completion method (default: add1u)") do |v|
+          param_opts[:completion] = v
+        end
+        o.on("--accuracy NAME", Params::ACCURACIES, "floats (default) or fractions") do |v|
+          param_opts[:accuracy] = v
+        end
+        o.on("--satisfaction NAME", Params::SATISFACTIONS,
+             "MES satisfaction: cost (default), cardinality, effort") do |v|
+          param_opts[:satisfaction] = v
+        end
+        o.on("--tie-breaking LIST", Array, "Comma-separated: maxVotes,minCost,maxCost") do |v|
+          param_opts[:tie_breaking] = v
+        end
+        o.on("--add1-options LIST", Array, "Comma-separated: exhaustive,integral") do |v|
+          param_opts[:add1_options] = v
+        end
+        o.on("--comparison NAME", Params::COMPARISONS, "none (default), satisfaction, exclusionRatio") do |v|
+          param_opts[:comparison] = v
+        end
+        o.on("--increment N", Integer, "Budget increment for Add1 (default: 1)") do |v|
+          param_opts[:increment] = v
+        end
+        o.separator ""
+        o.separator "Output options:"
+        o.on("--format FMT", %w[human csv json], "human (default), csv, or json") do |v|
+          options[:format] = v
+        end
+        o.on("--progress", "Show computation progress on stderr") { options[:progress] = true }
+        o.on("-h", "--help", "Show this help") do
+          puts o
+          exit 0
+        end
+        o.on("-v", "--version", "Show version") do
+          puts Equalshares::VERSION
+          exit 0
+        end
+      end
+    end
+  end
+end

data/lib/equalshares/comparison.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Equalshares
+  # Comparison step. Faithful port of comparisonStep() in
+  # js/methodOfEqualSharesWorker.js. Compares the MES committee against the greedy
+  # committee; if a strict majority of voters prefer greedy, the outcome switches.
+  module Comparison
+    module_function
+
+    def comparison_step(voter_ids, approvers, greedy, winners, params)
+      prefers_mes = 0
+      prefers_greedy = 0
+
+      case params.comparison
+      when "satisfaction"
+        mes_satisfaction = Hash.new(0)
+        greedy_satisfaction = Hash.new(0)
+        [[winners, mes_satisfaction], [greedy, greedy_satisfaction]].each do |candidates, satisfaction|
+          candidates.each do |c|
+            approvers[c].each { |i| satisfaction[i] += 1 }
+          end
+        end
+        voter_ids.each do |i|
+          if mes_satisfaction[i] > greedy_satisfaction[i]
+            prefers_mes += 1
+          elsif greedy_satisfaction[i] > mes_satisfaction[i]
+            prefers_greedy += 1
+          end
+        end
+      when "exclusionRatio"
+        mes_approvals = {}
+        winners.each { |c| approvers[c].each { |i| mes_approvals[i] = true } }
+        greedy_approvals = {}
+        greedy.each { |c| approvers[c].each { |i| greedy_approvals[i] = true } }
+        voter_ids.each do |i|
+          if mes_approvals[i] && !greedy_approvals[i]
+            prefers_mes += 1
+          elsif greedy_approvals[i] && !mes_approvals[i]
+            prefers_greedy += 1
+          end
+        end
+      end
+
+      stick_to_mes = prefers_greedy <= prefers_mes
+      { stick_to_mes: stick_to_mes, prefers_mes: prefers_mes, prefers_greedy: prefers_greedy }
+    end
+  end
+end

data/lib/equalshares/completion.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Equalshares
+  # Completion methods. Faithful port of equalSharesAdd1() and utilitarianCompletion()
+  # in js/methodOfEqualSharesWorker.js.
+  module Completion
+    module_function
+
+    # Method of Equal Shares with Add1 completion: repeatedly re-run fixed-budget MES
+    # with increasing per-voter budgets until adding more would exceed the real budget.
+    def add1(voter_ids, project_ids, cost_source, approvers, budget_source, params, progress: nil)
+      n = voter_ids.length
+      b = Float(budget_source)
+
+      start_budget = budget_source
+      if params.add1_option?("integral")
+        per_voter = (b / n).floor
+        start_budget = per_voter * n
+      end
+      start_budget = parse_number(start_budget)
+
+      # The virtual budget is raised in steps of `step`. The linear scan (as in the JS tool)
+      # stops at the first step whose outcome is either exhaustive (if enabled) or exceeds the
+      # real budget b. Both stopping conditions are monotone in the number of steps (once true
+      # they stay true as the budget grows), so we binary-search for the last accepted step and
+      # compute O(log) fixed-budget outcomes instead of O(steps). The result is identical to the
+      # scan: FixedBudget never mutates `approvers`, so the final reported run is independent of
+      # which budgets were probed.
+      step = n * params.increment
+      exhaustive_enabled = params.add1_option?("exhaustive")
+      memo = {}
+
+      eval_step = lambda do |k|
+        memo[k] ||= begin
+          winners = FixedBudget.run(voter_ids, project_ids, cost_source, approvers,
+                                    start_budget + (k * step), params).fetch(:winners)
+          step_cost = winners.sum { |c| float_cost(cost_source, c) }
+          exhaustive = exhaustive_enabled &&
+                       project_ids.none? do |extra|
+                         !winners.include?(extra) && step_cost + float_cost(cost_source, extra) <= b
+                       end
+          progress&.call((100 * [step_cost, b].min / b).floor)
+          { winners: winners, cost: step_cost, exhaustive: exhaustive }
+        end
+      end
+
+      # Would the linear scan reach and accept the budget at step k? Step 0 is the starting point;
+      # step k >= 1 is accepted iff no earlier step was exhaustive and step k is still within
+      # budget (monotonicity lets us test only the preceding exhaustiveness and this cost).
+      accepts = lambda do |k|
+        next true if k <= 0
+        next false if exhaustive_enabled && eval_step.call(k - 1)[:exhaustive]
+
+        eval_step.call(k)[:cost] <= b
+      rescue ComputeError
+        # Far above the accepted region the outcome can become unresolvable (e.g. an unbreakable
+        # tie); the linear scan never reaches there, so treat it as past the boundary.
+        false
+      end
+
+      # gallop to bracket the boundary, then binary-search the last accepted step
+      hi = 1
+      hi *= 2 while accepts.call(hi)
+      lo = hi / 2 # accepts(lo) is true
+      while lo + 1 < hi
+        mid = (lo + hi) / 2
+        accepts.call(mid) ? (lo = mid) : (hi = mid)
+      end
+      budget = start_budget + (lo * step)
+
+      # recompute with final budget while reporting details
+      FixedBudget.run(voter_ids, project_ids, cost_source, approvers, budget, params, report_details: true)
+    end
+
+    # Greedy completion by number of approvers (also used to build the greedy committee).
+    # `cost` here is the numeric cost map (Float or Rational).
+    def utilitarian(_voter_ids, project_ids, cost, approvers, budget_total, already_winners)
+      winners = already_winners.dup
+      cost_so_far = winners.sum { |c| cost[c] }
+      added = []
+      # Stable descending sort by approver count (ties keep original order), matching JS Array.sort.
+      sorted = project_ids.each_with_index
+                          .sort_by { |c, idx| [-approvers[c].length, idx] }
+                          .map(&:first)
+      sorted.each do |c|
+        next if winners.include?(c) || cost_so_far + cost[c] > budget_total
+
+        winners << c
+        added << c
+        cost_so_far += cost[c]
+      end
+      { winners: winners, added: added }
+    end
+
+    def float_cost(cost_source, cost_id)
+      Float(cost_source[cost_id])
+    end
+
+    # Preserve integer budgets (Add1 increments are integral); fall back to float.
+    def parse_number(value)
+      Integer(value.to_s)
+    rescue ArgumentError, TypeError
+      Float(value)
+    end
+  end
+end

data/lib/equalshares/compute.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Equalshares
+  # Facade for the Method of Equal Shares. Delegates to the rule objects: cardinal
+  # ballots (per-voter utilities) go to Rules::CardinalMes, approval ballots to
+  # Rules::MethodOfEqualShares (with the equalshares.net completion/comparison steps).
+  module Compute
+    module_function
+
+    # Returns { winners: Array<String>, notes: Hash }.
+    def equal_shares(instance, params = Params.new, progress: nil)
+      if instance.cardinal?
+        Rules::CardinalMes.call(instance, params, progress: progress)
+      else
+        Rules::MethodOfEqualShares.call(instance, params, progress: progress)
+      end
+    end
+  end
+end

data/lib/equalshares/election.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Equalshares
+  # A numeric view of an instance for a given accuracy. It exposes the voters,
+  # projects and supporters together with the per-project cost, the budget and the
+  # per-voter utilities, all converted to the right numeric type (exact Rational for
+  # "fractions", Float for "floats"). This centralises the setup that every rule
+  # previously repeated, and provides the float-based statistics used for reporting.
+  class Election
+    attr_reader :instance, :params
+
+    def initialize(instance, params = Params.new)
+      @instance = instance
+      @params = params
+      @exact = params.accuracy == "fractions"
+      @costs = instance.project_ids.to_h { |c| [c, numeric(instance.projects[c]["cost"])] }
+      @float_costs = instance.project_ids.to_h { |c| [c, Float(instance.projects[c]["cost"])] }
+    end
+
+    def voter_ids
+      instance.voter_ids
+    end
+
+    def project_ids
+      instance.project_ids
+    end
+
+    def approvers
+      instance.approvers
+    end
+
+    def supporters(project_id)
+      instance.approvers[project_id]
+    end
+
+    def exact?
+      @exact
+    end
+
+    # Per-project cost in the accuracy's numeric type, as a Hash{project_id => Numeric}.
+    attr_reader :costs
+
+    # Per-project cost as floats, as a Hash{project_id => Float} (for statistics and the
+    # cost/comparison bookkeeping that the equalshares.net tool always does in floats).
+    attr_reader :float_costs
+
+    def budget
+      @budget ||= numeric(instance.budget)
+    end
+
+    def float_budget
+      @float_budget ||= Float(instance.budget)
+    end
+
+    # Per-project voter utilities for cardinal/ordinal ballots: { voter_id => Numeric }.
+    def utilities(project_id)
+      (instance.scores[project_id] || {}).transform_values { |score| numeric(score) }
+    end
+
+    def statistics(winners)
+      Statistics.gather(voter_ids, @float_costs, instance.approvers, winners)
+    end
+
+    # Convert a cost/budget/score string to the accuracy's numeric type.
+    def numeric(value)
+      @exact ? self.class.rational_of(value) : Float(value)
+    end
+
+    # Exact rational from a cost/budget string, matching fraction.js's decimal handling
+    # ("5000" -> 5000, "5000.5" -> 10001/2).
+    def self.rational_of(value)
+      Rational(value.to_s)
+    rescue ArgumentError
+      Float(value).to_r
+    end
+  end
+end

data/lib/equalshares/errors.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Equalshares
+  class Error < StandardError; end
+
+  # Raised when a pabulib (.pb) file cannot be parsed.
+  class ParseError < Error; end
+
+  # Raised for invalid parameters or unresolvable ties during computation.
+  class ComputeError < Error; end
+end