equalshares 0.1.0

data/lib/equalshares/pabulib/vote_row_parser.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Equalshares
+  module Pabulib
+    # Parses a single row of the VOTES section into the accumulator, turning the vote
+    # into approvals and (for scoring/cumulative/ordinal ballots) per-voter scores.
+    class VoteRowParser
+      def initialize(accumulator)
+        @acc = accumulator
+        vote_type = accumulator.meta["vote_type"]
+        @cardinal = CARDINAL_VOTE_TYPES.include?(vote_type)
+        @ordinal = vote_type == "ordinal"
+      end
+
+      def parse(row, header, line_number)
+        voter_id_idx = header.index("voter_id")
+        vote_idx = header.index("vote")
+        points_idx = header.index("points")
+
+        require_columns!(voter_id_idx, vote_idx, line_number)
+        validate_column_count!(row, header, line_number)
+
+        voter_id = row[voter_id_idx].strip
+        raise ParseError, "Line #{line_number}: Duplicate voter ID '#{voter_id}' found." if @acc.voter_ids_set[voter_id]
+
+        record_vote(row, vote_idx, points_idx, voter_id, line_number)
+        store_voter(row, header, voter_id)
+      end
+
+      private
+
+      def require_columns!(voter_id_idx, vote_idx, line_number)
+        return unless voter_id_idx.nil? || vote_idx.nil?
+
+        missing = []
+        missing << "voter_id " if voter_id_idx.nil?
+        missing << "vote" if vote_idx.nil?
+        raise ParseError, "Line #{line_number}: Missing required column(s) in votes section: #{missing.join}."
+      end
+
+      def validate_column_count!(row, header, line_number)
+        return if row.length == header.length
+
+        raise ParseError, "Line #{line_number}: Invalid number of columns in votes section."
+      end
+
+      def record_vote(row, vote_idx, points_idx, voter_id, line_number)
+        return if row[vote_idx] == ""
+
+        project_list = row[vote_idx].split(",")
+        points = points_list(row, points_idx)
+        project_list.each_with_index do |project_id, k|
+          pid = project_id.strip
+          unless @acc.project_ids_set[pid]
+            raise ParseError, "Line #{line_number}: Invalid project ID '#{pid}' found in vote."
+          end
+
+          add_support(pid, voter_id, score_for(project_list, points, k))
+        end
+      end
+
+      def points_list(row, points_idx)
+        return nil unless @cardinal && points_idx && row[points_idx] != ""
+
+        row[points_idx].split(",")
+      end
+
+      # Borda score for ordinal ballots (ballot length - rank - 1, last-ranked = 0);
+      # the raw points value for scoring/cumulative ballots; nil for plain approval.
+      def score_for(project_list, points, index)
+        if @ordinal
+          (project_list.length - index - 1).to_s
+        elsif points
+          points[index].to_s.strip
+        end
+      end
+
+      def add_support(pid, voter_id, score)
+        if @ordinal || score
+          return unless Float(score, exception: false)&.positive? # supporters have a positive score
+
+          @acc.approvers[pid] << voter_id
+          (@acc.scores[pid] ||= {})[voter_id] = score
+        else
+          @acc.approvers[pid] << voter_id
+        end
+      end
+
+      def store_voter(row, header, voter_id)
+        @acc.voter_ids_set[voter_id] = true
+        @acc.votes[voter_id] = {}
+        header.each_index { |idx| @acc.votes[voter_id][header[idx].strip] = row[idx].strip }
+      end
+    end
+  end
+end

data/lib/equalshares/pabulib/writer.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Equalshares
+  module Pabulib
+    # Serialises an Instance back to pabulib (.pb) text. Inverse of the parser:
+    # META / PROJECTS / VOTES sections, ';'-separated, with fields containing ';', '"'
+    # or newlines quoted (and embedded '"' doubled). Parsing the result yields an
+    # equivalent Instance (round-trip safe).
+    module Writer
+      module_function
+
+      def write_string(instance)
+        lines = ["META", "key;value"]
+        instance.meta.each { |key, value| lines << "#{escape(key)};#{escape(value)}" }
+        write_section(lines, "PROJECTS", instance.projects)
+        write_section(lines, "VOTES", instance.votes)
+        "#{lines.join("\n")}\n"
+      end
+
+      def write_file(instance, path)
+        File.write(path, write_string(instance))
+      end
+
+      def write_section(lines, header_name, rows_by_id)
+        lines << header_name
+        return if rows_by_id.empty?
+
+        header = rows_by_id.values.first.keys
+        lines << header.map { |h| escape(h) }.join(";")
+        rows_by_id.each_value do |row|
+          lines << header.map { |h| escape(row[h]) }.join(";")
+        end
+      end
+
+      # Inverse of the CSV field handling in Pabulib::Csv.parse_line.
+      def escape(value)
+        str = value.to_s
+        return str unless str.match?(/[;"\n]/)
+
+        %("#{str.gsub('"', '""')}")
+      end
+    end
+  end
+end

data/lib/equalshares/pabulib.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "pabulib/csv"
+require_relative "pabulib/project_row_parser"
+require_relative "pabulib/vote_row_parser"
+require_relative "pabulib/parser"
+require_relative "pabulib/writer"
+
+module Equalshares
+  # Reads and writes pabulib (.pb) files: a sectioned, semicolon-delimited CSV with
+  # META / PROJECTS / VOTES sections. Faithful port of js/pabulibParser.js, extended
+  # to cardinal (scoring/cumulative) and ordinal ballots.
+  #
+  # This module is a thin facade; the work lives in Pabulib::Parser (which delegates
+  # rows to Pabulib::ProjectRowParser / Pabulib::VoteRowParser) and Pabulib::Writer.
+  module Pabulib
+    module_function
+
+    SECTIONS = %w[meta projects votes].freeze
+    # vote_type values that carry per-voter cardinal scores (a `points` column).
+    CARDINAL_VOTE_TYPES = %w[scoring cumulative].freeze
+    # vote_type values that produce per-voter utilities (scores) for the general MES:
+    # cardinal ballots plus ordinal ballots (via Borda scores).
+    SCORED_VOTE_TYPES = %w[scoring cumulative ordinal].freeze
+
+    def parse_file(path)
+      parse_from_string(File.read(path))
+    end
+
+    # Returns an Equalshares::Instance.
+    def parse_from_string(filetext)
+      Parser.new.parse(filetext)
+    end
+
+    def write_string(instance)
+      Writer.write_string(instance)
+    end
+
+    def write_file(instance, path)
+      Writer.write_file(instance, path)
+    end
+  end
+end

data/lib/equalshares/params.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Equalshares
+  # Computation parameters. Mirrors the `equalSharesParams` object from js/main.js
+  # and the allowed values wired up in js/interface/formHandler.js.
+  class Params
+    TIE_BREAKING_METHODS = %w[maxVotes minCost maxCost].freeze
+    COMPLETIONS = %w[none utilitarian add1 add1e add1u add1eu].freeze
+    ADD1_OPTIONS = %w[exhaustive integral].freeze
+    COMPARISONS = %w[none satisfaction exclusionRatio].freeze
+    ACCURACIES = %w[floats fractions].freeze
+    SATISFACTIONS = Satisfaction::NAMES
+
+    attr_reader :tie_breaking, :completion, :add1_options, :comparison, :accuracy, :increment, :satisfaction
+
+    # Defaults match js/main.js:6-13. `satisfaction` selects the MES satisfaction
+    # measure (pabutools parity); "cost" is the equalshares.net default.
+    def initialize(tie_breaking: [], completion: "add1u", add1_options: %w[exhaustive integral],
+                   comparison: "none", accuracy: "floats", increment: 1, satisfaction: "cost")
+      @tie_breaking = Array(tie_breaking)
+      @completion = completion
+      @add1_options = Array(add1_options)
+      @comparison = comparison
+      @accuracy = accuracy
+      @increment = increment
+      @satisfaction = satisfaction
+      validate!
+    end
+
+    def add1_option?(name)
+      @add1_options.include?(name)
+    end
+
+    private
+
+    def validate!
+      @tie_breaking.each do |m|
+        # A tie-breaking method is a known keyword, an explicit candidate-order list
+        # (Array), or a total order ({ lexico: [...] }).
+        next if m.is_a?(Array) || m.is_a?(Hash) || TIE_BREAKING_METHODS.include?(m)
+
+        raise ComputeError, "Unknown tie-breaking method: #{m}"
+      end
+      validate_inclusion(:completion, @completion, COMPLETIONS)
+      validate_inclusion(:comparison, @comparison, COMPARISONS)
+      validate_inclusion(:accuracy, @accuracy, ACCURACIES)
+      validate_inclusion(:satisfaction, @satisfaction, SATISFACTIONS)
+      @add1_options.each { |o| validate_inclusion(:add1_options, o, ADD1_OPTIONS) }
+      return if @increment.is_a?(Integer) && @increment.positive?
+
+      raise ComputeError,
+            "increment must be a positive integer"
+    end
+
+    def validate_inclusion(field, value, allowed)
+      return if allowed.include?(value)
+
+      raise ComputeError, "Invalid #{field}: #{value.inspect} (allowed: #{allowed.join(', ')})"
+    end
+  end
+end

data/lib/equalshares/phragmen.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Equalshares
+  # Facade for Phragmén's sequential rule; delegates to Rules::Phragmen.
+  module Phragmen
+    module_function
+
+    def sequential(instance, params = Params.new, progress: nil)
+      Rules::Phragmen.call(instance, params, progress: progress)
+    end
+  end
+end

data/lib/equalshares/result.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Equalshares
+  # The outcome of a voting rule: the winning project ids together with outcome
+  # statistics, timing and any rule-specific notes (endowment, effective vote counts,
+  # comparison message, greedy statistics, ...).
+  class Result
+    attr_reader :winners, :notes
+
+    def initialize(winners:, notes:)
+      @winners = winners
+      @notes = notes
+    end
+
+    def stats
+      notes[:stats]
+    end
+
+    def time
+      notes[:time]
+    end
+
+    def total_cost
+      stats[:total_cost]
+    end
+
+    def endowment
+      notes[:endowment]
+    end
+
+    # Last recorded effective vote count for a project (Method of Equal Shares only),
+    # or nil for rules/projects without one.
+    def effective_vote_count(project_id)
+      (notes[:effective_vote_count] || {})[project_id]&.last
+    end
+
+    def to_h
+      { winners: winners, notes: notes }
+    end
+
+    def to_json(*)
+      to_h.to_json(*)
+    end
+  end
+end

data/lib/equalshares/rules/base.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Equalshares
+  # Voting rules as objects. Each concrete rule is a Rules::Base subclass that computes
+  # winners from an instance; the thin module facades (Equalshares::Phragmen, etc.)
+  # delegate to these classes.
+  module Rules
+    # Holds the (instance, params) and the derived Election numeric view, and assembles
+    # the { winners:, notes: } result with statistics and timing. Subclasses implement
+    # #call and return `result(winners, start, extra_notes)`.
+    class Base
+      def self.call(instance, params = Params.new, progress: nil)
+        new(instance, params, progress: progress).call
+      end
+
+      def initialize(instance, params = Params.new, progress: nil)
+        @instance = instance
+        @params = params
+        @progress = progress
+        @election = Election.new(instance, params)
+      end
+
+      def call
+        raise NotImplementedError, "#{self.class} must implement #call"
+      end
+
+      private
+
+      attr_reader :instance, :params, :election, :progress
+
+      def now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      # Build the Result, adding outcome statistics and elapsed time to any
+      # rule-specific notes.
+      def result(winners, since, extra_notes = {})
+        notes = extra_notes.merge(stats: election.statistics(winners),
+                                  time: format("%.1f", now - since))
+        Result.new(winners: winners, notes: notes)
+      end
+    end
+  end
+end

data/lib/equalshares/rules/cardinal_mes.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Equalshares
+  module Rules
+    # Method of Equal Shares for ballots carrying per-voter utilities (vote_type
+    # "scoring"/"cumulative", or "ordinal" via Borda), where each voter i has a
+    # per-project utility u_i(c). Faithful port of the core of pabutools'
+    # method_of_equal_shares with an additive satisfaction (the "poor/rich"
+    # affordability computation), for the pure rule (no completion).
+    #
+    # The approval path (Rules::MethodOfEqualShares) is kept separate; this general
+    # path is used when instance.cardinal? is true.
+    class CardinalMes < Base
+      def call
+        unless instance.cardinal?
+          raise ComputeError,
+                "CardinalMes applies to instances with per-voter scores (scoring/cumulative/ordinal)"
+        end
+
+        start = now
+        voter_ids = election.voter_ids
+        project_ids = election.project_ids
+        approvers = election.approvers
+        cost = election.costs
+        budget_limit = election.budget
+        util = project_ids.to_h { |c| [c, election.utilities(c)] }
+        n = voter_ids.length
+
+        budget = {}
+        voter_ids.each { |i| budget[i] = budget_limit / n } # endowment B/|N|
+
+        remaining = project_ids.select { |c| cost[c].positive? && !approvers[c].empty? }
+        winners = []
+
+        loop do
+          argmin = argmin_by_affordability(remaining, approvers, budget, util, cost)
+          break if argmin.empty?
+
+          selected = Tie.resolve_one(project_ids, cost, approvers, params, argmin)
+          charge(selected, approvers, budget, util, cost)
+          winners << selected
+          remaining.delete(selected)
+          progress&.call((100 * winners.sum { |c| cost[c] } / budget_limit).floor)
+        end
+
+        result(winners, start)
+      end
+
+      private
+
+      def argmin_by_affordability(remaining, approvers, budget, util, cost)
+        min_rho = nil
+        argmin = []
+        remaining.dup.each do |c|
+          supporters = approvers[c]
+          if supporters.sum { |i| budget[i] } < cost[c]
+            remaining.delete(c) # can never become affordable again
+            next
+          end
+          rho = affordability(supporters, budget, util[c], cost[c])
+          if min_rho.nil? || rho < min_rho
+            min_rho = rho
+            argmin = [c]
+          elsif rho == min_rho
+            argmin << c
+          end
+        end
+        argmin
+      end
+
+      def charge(selected, approvers, budget, util, cost)
+        rho = affordability(approvers[selected], budget, util[selected], cost[selected])
+        zero = election.exact? ? 0 : 0.0
+        approvers[selected].each do |i|
+          payment = rho * util[selected][i]
+          budget[i] = budget[i] > payment ? budget[i] - payment : zero
+        end
+      end
+
+      # The "poor/rich" affordability factor rho: minimal rho such that
+      # sum_i min(budget_i, rho * u_i(c)) == cost(c). Port of pabutools'
+      # affordability_poor_rich.
+      def affordability(supporters, budget, util, cost)
+        rich = supporters.dup
+        poor_budget = 0
+        loop do
+          denominator = rich.sum { |i| util[i] }
+          rho = (cost - poor_budget) / denominator
+          new_poor = rich.select { |i| budget[i] < rho * util[i] }
+          return rho if new_poor.empty?
+
+          poor_budget += new_poor.sum { |i| budget[i] }
+          rich -= new_poor
+        end
+      end
+    end
+  end
+end

data/lib/equalshares/rules/greedy.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Equalshares
+  module Rules
+    # Greedy approximation of utilitarian welfare, generalised over a satisfaction
+    # measure. Faithful port of pabutools' greedy_utilitarian_welfare (additive,
+    # resolute case).
+    #
+    # Projects are picked in order of decreasing "satisfaction density" = total
+    # satisfaction of the project divided by its cost, resolving ties by the
+    # tie-breaking order; any project that still fits the remaining budget is taken
+    # (knapsack greedy). For Cost_Sat the density is the approver count.
+    class Greedy < Base
+      def call
+        start = now
+        project_ids = election.project_ids
+        approvers = election.approvers
+        cost = election.costs
+        sat = Satisfaction.for(params.satisfaction)
+
+        order = Tie.total_order(project_ids, cost, approvers, params)
+        order_index = order.each_with_index.to_h
+        ranked = project_ids.sort_by { |c| [-density(c, cost, approvers, sat), order_index[c]] }
+
+        winners = []
+        remaining_budget = election.budget
+        ranked.each do |c|
+          next unless cost[c] <= remaining_budget
+
+          winners << c
+          remaining_budget -= cost[c]
+        end
+
+        result(winners, start)
+      end
+
+      private
+
+      def density(project_id, cost, approvers, sat)
+        total_sat = sat.call(cost[project_id], approvers[project_id].length) * approvers[project_id].length
+        if total_sat.positive?
+          cost[project_id].positive? ? total_sat / cost[project_id] : Float::INFINITY
+        else
+          0
+        end
+      end
+    end
+  end
+end

data/lib/equalshares/rules/maximin.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Equalshares
+  module Rules
+    # The maximin support rule (Aziz, Lee & Talmon 2018; "Generalised Sequential
+    # Phragmén"), for approval ballots. Faithful port of pabutools' maximin_support.
+    #
+    # At each step, for every still-affordable project, the minimum achievable maximum
+    # voter load of the committee W ∪ {c} is computed, and the project minimising it is
+    # bought. Rather than an LP (as pabutools uses), the minimum max-load is computed
+    # exactly: it equals the max-density subgraph value
+    #     z*(W) = max_{S ⊆ W, S≠∅} cost(S) / |approvers(S)|
+    # solved via a parametric max-flow (Dinkelbach iterations) in exact rational
+    # arithmetic. This keeps the rule pure-Ruby, dependency-free and exact.
+    #
+    # Requires integer project costs (as in real pabulib data).
+    class Maximin < Base
+      def call
+        start = now
+        project_ids = election.project_ids
+        approvers = election.approvers
+        # maximin needs integer costs to scale the max-flow network exactly.
+        cost = project_ids.to_h { |c| [c, integer_cost(instance.projects[c]["cost"])] }
+        budget_limit = integer_cost(instance.budget)
+
+        available = project_ids.select { |c| cost[c].between?(0, budget_limit) }
+        winners = []
+        remaining_budget = budget_limit
+
+        loop do
+          available = available.select { |c| !winners.include?(c) && cost[c] <= remaining_budget }
+          break if available.empty?
+
+          argmin = argmin_by_load(available, winners, cost, approvers)
+          selected = Tie.resolve_one(project_ids, cost, approvers, params, argmin)
+
+          winners << selected
+          remaining_budget -= cost[selected]
+          progress&.call((100 * winners.sum { |c| cost[c] } / budget_limit).floor)
+        end
+
+        result(winners, start)
+      end
+
+      private
+
+      def argmin_by_load(available, winners, cost, approvers)
+        min_load = nil
+        argmin = []
+        available.each do |c|
+          load = min_max_load(winners + [c], cost, approvers)
+          if min_load.nil? || load < min_load
+            min_load = load
+            argmin = [c]
+          elsif load == min_load
+            argmin << c
+          end
+        end
+        argmin
+      end
+
+      # Minimum achievable maximum voter load for the committee, in exact rationals.
+      # Equals the max-density subgraph value; Float::INFINITY if some project has cost
+      # but no approvers (its cost cannot be distributed).
+      def min_max_load(committee, cost, approvers)
+        projects = committee.select { |c| cost[c].positive? }
+        return 0 if projects.empty?
+        return Float::INFINITY if projects.any? { |c| approvers[c].empty? }
+
+        total_cost = projects.sum { |c| cost[c] }
+        density = Rational(0)
+        (projects.length + 2).times do
+          source_side = feasible_or_violating_set(projects, cost, approvers, density, total_cost)
+          return density if source_side.nil? # feasible at this level: density is optimal
+
+          covered = source_side.flat_map { |c| approvers[c] }.uniq.length
+          density = Rational(source_side.sum { |c| cost[c] }, covered)
+        end
+        density
+      end
+
+      # Build the parametric max-flow at load level `density` and return the set of
+      # projects on the source side of the min cut (a set denser than `density`), or nil
+      # if the whole cost can be routed (density is >= the true max-density).
+      def feasible_or_violating_set(projects, cost, approvers, density, total_cost)
+        den = density.denominator
+        num = density.numerator
+        voters = projects.flat_map { |c| approvers[c] }.uniq
+
+        source = 0
+        sink = 1
+        project_node = {}
+        projects.each_with_index { |c, i| project_node[c] = 2 + i }
+        voter_node = {}
+        voters.each_with_index { |v, i| voter_node[v] = 2 + projects.length + i }
+
+        flow = MaxFlow.new(2 + projects.length + voters.length)
+        infinity = total_cost * den # >= any single project's scaled cost
+        projects.each do |c|
+          flow.add_edge(source, project_node[c], cost[c] * den)
+          approvers[c].each { |v| flow.add_edge(project_node[c], voter_node[v], infinity) }
+        end
+        voters.each { |v| flow.add_edge(voter_node[v], sink, num) }
+
+        pushed = flow.max_flow(source, sink)
+        return nil if pushed == total_cost * den # all cost routed -> feasible
+
+        reachable = flow.reachable_from(source)
+        projects.select { |c| reachable[project_node[c]] }
+      end
+
+      def integer_cost(value)
+        Integer(value.to_s)
+      rescue ArgumentError, TypeError
+        raise ComputeError, "The maximin support rule requires integer costs (got #{value.inspect})"
+      end
+    end
+  end
+end