equalshares 0.1.0

data/lib/equalshares/fixed_budget.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+module Equalshares
+  # The fixed-budget Method of Equal Shares loop.
+  #
+  # This unifies the two near-identical JS implementations
+  # (equalSharesFixedBudgetFractions and equalSharesFixedBudgetFloats in
+  # js/methodOfEqualSharesWorker.js) into a single loop driven by the numeric type
+  # of the values passed in:
+  #   - fractions mode: `cost` values and `b_total` are Rational  -> exact arithmetic
+  #   - floats mode:    `cost` values and `b_total` are Float      -> IEEE-754 arithmetic
+  #
+  # The arithmetic (order and types) is kept bit-identical to the JS tool; the class
+  # below only reorganises the control flow into evaluate/charge steps.
+  module FixedBudget
+    module_function
+
+    # Dispatch on params.accuracy, preparing cost/budget in the right numeric type.
+    # `cost_source` maps project_id => original cost string; `budget_source` is the
+    # budget string. This mirrors JS where costs come from parseFloat, then (in the
+    # fractions path) get wrapped by new Fraction(...).
+    def run(voter_ids, project_ids, cost_source, approvers, budget_source, params,
+            report_details: false, progress: nil)
+      case params.accuracy
+      when "fractions"
+        cost = cost_source.transform_values { |c| Election.rational_of(c) }
+        b_total = Election.rational_of(budget_source)
+      when "floats"
+        cost = cost_source.transform_values { |c| Float(c) }
+        b_total = Float(budget_source)
+      else
+        raise ComputeError, "Unknown accuracy parameter"
+      end
+      Loop.new(voter_ids, project_ids, cost, approvers, b_total, params,
+               report_details: report_details, progress: progress).run
+    end
+
+    # Collects the per-candidate explanation data produced while running the rule
+    # (money behind each candidate and its effective vote count over the rounds, plus
+    # the per-voter endowment). Kept separate from the selection logic; #to_h yields the
+    # same hash shape the callers consume.
+    class Report
+      def initialize(project_ids, endowment)
+        @endowment = endowment
+        @money_behind_candidate = {}
+        @effective_vote_count = {}
+        project_ids.each do |c|
+          @money_behind_candidate[c] = []
+          @effective_vote_count[c] = []
+        end
+      end
+
+      def record_money_behind(project_id, value)
+        @money_behind_candidate[project_id] << value.to_f
+      end
+
+      def record_effective_vote_count(project_id, value)
+        @effective_vote_count[project_id] << value.to_f
+      end
+
+      def record_unaffordable(project_id)
+        @effective_vote_count[project_id] << 0
+      end
+
+      def to_h
+        { money_behind_candidate: @money_behind_candidate,
+          effective_vote_count: @effective_vote_count,
+          endowment: @endowment }
+      end
+    end
+
+    # One fixed-budget MES run. Generalises the shared logic of
+    # equalSharesFixedBudgetFractions/Floats over an additive satisfaction measure (see
+    # Equalshares::Satisfaction): the payment mechanics are unchanged (each project
+    # raises its full cost), while the selection criterion is effective vote count =
+    # u(c) / maxPayment, with u(c) the per-approver utility. For Cost_Sat (u = cost)
+    # this is exactly the original rule.
+    #
+    # Ruby's Hash preserves insertion order and mirrors the JS Map semantics used for
+    # `remaining` (re-assigning an existing key keeps its position; delete removes it).
+    class Loop
+      CandidateEvaluation = Struct.new(:project_id, :money_behind, :effective_vote_count,
+                                       :max_payment, :affordable?, keyword_init: true)
+
+      def initialize(voter_ids, project_ids, cost, approvers, b_total, params,
+                     report_details: false, progress: nil)
+        @project_ids = project_ids
+        @cost = cost
+        @approvers = approvers
+        @b_total = b_total
+        @params = params
+        @report_details = report_details
+        @progress = progress
+        @sat = Satisfaction.for(params.satisfaction)
+        @n = voter_ids.length
+
+        initialize_budget(voter_ids)
+        initialize_report
+        initialize_remaining
+      end
+
+      def run
+        winners = []
+        loop do
+          best, max_payment_of = select_best
+          if best.empty?
+            # no remaining candidates are affordable
+            unless @remaining.empty?
+              raise ComputeError,
+                    "No available candidate found even though there are still affordable candidates: " \
+                    "#{@remaining.keys}"
+            end
+
+            break
+          end
+
+          best = Tie.resolve_one(@project_ids, @cost, @approvers, @params, best)
+          winners << best
+          @progress&.call((100 * winners.sum { |c| @cost[c] } / @b_total).floor)
+          charge_winner(best, max_payment_of[best])
+          @remaining.delete(best)
+        end
+
+        { winners: winners, report: @report.to_h }
+      end
+
+      private
+
+      def initialize_budget(voter_ids)
+        @budget = {}
+        voter_ids.each { |i| @budget[i] = @b_total / @n }
+      end
+
+      def initialize_report
+        @report = Report.new(@project_ids, @b_total.to_f / @n)
+      end
+
+      def initialize_remaining
+        @remaining = {} # candidate -> previous effective vote count
+        @project_ids.each do |c|
+          next unless @cost[c].positive? && !@approvers[c].empty?
+
+          # effective vote count when budgets are ample: u(c) * |approvers| / cost(c)
+          @remaining[c] =
+            (@sat.call(@cost[c], @approvers[c].length) * @approvers[c].length) / @cost[c]
+        end
+      end
+
+      # Pick the affordable candidate(s) with the highest effective vote count this
+      # round, returning [tied_best, max_payment_by_candidate].
+      def select_best
+        best = []
+        best_eff_vote_count = 0
+        max_payment_of = {} # candidate -> per-approver payment cap computed this round
+
+        # Walk remaining candidates in order of decreasing previous effective vote count.
+        # Stable descending sort (ties keep insertion order), matching JS Array.sort.
+        remaining_sorted = @remaining.keys.each_with_index
+                                     .sort_by { |c, idx| [-@remaining[c], idx] }
+                                     .map(&:first)
+
+        remaining_sorted.each do |c|
+          # c cannot beat the best so far (optimization only when not reporting details).
+          break if @remaining[c] < best_eff_vote_count && !@report_details
+
+          evaluation = evaluate_candidate(c)
+          record_evaluation(evaluation)
+          next unless evaluation.affordable?
+
+          max_payment_of[c] = evaluation.max_payment
+          if evaluation.effective_vote_count > best_eff_vote_count
+            best_eff_vote_count = evaluation.effective_vote_count
+            best = [c]
+          elsif evaluation.effective_vote_count == best_eff_vote_count
+            best << c
+          end
+        end
+
+        [best, max_payment_of]
+      end
+
+      # Effective vote count and per-approver payment cap for candidate c this round, or
+      # an unaffordable result if c cannot raise its cost with current supporter budgets.
+      def evaluate_candidate(project_id)
+        money_behind_now = @approvers[project_id].sum(numeric_zero) { |i| @budget[i] }
+        if money_behind_now < @cost[project_id]
+          return CandidateEvaluation.new(project_id: project_id, money_behind: money_behind_now,
+                                         effective_vote_count: 0,
+                                         max_payment: nil, affordable?: false)
+        end
+
+        # Split the cost as equally as possible among approvers. Sort a copy by budget so
+        # the instance's approver order is not mutated during computation.
+        supporters_by_budget = @approvers[project_id].sort_by { |i| @budget[i] }
+        paid_so_far = 0
+        denominator = supporters_by_budget.length # approvers who can afford the max payment
+        supporters_by_budget.each do |i|
+          max_payment = (@cost[project_id] - paid_so_far) / denominator # if remaining approvers pay equally
+          if max_payment > @budget[i]
+            # i cannot afford the max payment, so pays entire remaining budget
+            paid_so_far += @budget[i]
+            denominator -= 1
+          else
+            eff_vote_count = @sat.call(@cost[project_id], @approvers[project_id].length) / max_payment
+            return CandidateEvaluation.new(project_id: project_id, money_behind: money_behind_now,
+                                           effective_vote_count: eff_vote_count,
+                                           max_payment: max_payment, affordable?: true)
+          end
+        end
+        raise ComputeError, "Candidate #{project_id} was affordable but no payment cap could be computed."
+      end
+
+      # Apply an evaluation: update the core `remaining` state and record the numbers in
+      # the report (the latter delegated to the Report collaborator).
+      def record_evaluation(evaluation)
+        project_id = evaluation.project_id
+        @report.record_money_behind(project_id, evaluation.money_behind)
+
+        if evaluation.affordable?
+          @remaining[project_id] = evaluation.effective_vote_count
+          @report.record_effective_vote_count(project_id, evaluation.effective_vote_count)
+        else
+          @remaining.delete(project_id)
+          @report.record_unaffordable(project_id)
+        end
+      end
+
+      # Charge each approver of the winning candidate its per-approver payment cap
+      # (equals cost/eff only for Cost_Sat), capped at their remaining budget.
+      def charge_winner(best, best_max_payment)
+        @approvers[best].each do |i|
+          @budget[i] = @budget[i] > best_max_payment ? @budget[i] - best_max_payment : numeric_zero
+        end
+      end
+
+      # Additive identity in the same numeric family as the budget (0 or 0.0).
+      def numeric_zero
+        @b_total.is_a?(Float) ? 0.0 : 0
+      end
+    end
+  end
+end

data/lib/equalshares/greedy.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Equalshares
+  # Facade for greedy utilitarian welfare; delegates to Rules::Greedy.
+  module Greedy
+    module_function
+
+    def utilitarian_welfare(instance, params = Params.new)
+      Rules::Greedy.call(instance, params)
+    end
+  end
+end

data/lib/equalshares/instance.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Equalshares
+  # A parsed pabulib instance.
+  #
+  # Mirrors the JS `{ meta, projects, votes, approvers }` shape:
+  #   meta      - Hash{String => String} key/value metadata (includes "budget", "vote_type")
+  #   projects  - Hash{String => Hash{String => String}} project_id => raw row fields (incl "cost", "name")
+  #   votes     - Hash{String => Hash{String => String}} voter_id => raw row fields
+  #   approvers - Hash{String => Array<String>} project_id => list of voter_ids approving it
+  class Instance
+    attr_reader :meta, :projects, :votes, :approvers, :scores
+
+    # `scores` is nil for approval instances; for cardinal ballots (vote_type
+    # "scoring"/"cumulative") it is Hash{project_id => Hash{voter_id => score string}}.
+    def initialize(meta:, projects:, votes:, approvers:, scores: nil)
+      @meta = meta
+      @projects = projects
+      @votes = votes
+      @approvers = approvers
+      @scores = scores
+    end
+
+    # True for cardinal (scoring/cumulative) instances that carry per-voter scores.
+    def cardinal?
+      !@scores.nil?
+    end
+
+    def vote_type
+      @meta["vote_type"]
+    end
+
+    # Voter IDs (JS: Object.keys(votes))
+    def voter_ids
+      @voter_ids ||= self.class.js_key_order(@votes.keys)
+    end
+
+    # Project IDs (JS: Object.keys(projects))
+    def project_ids
+      @project_ids ||= self.class.js_key_order(@projects.keys)
+    end
+
+    def budget
+      @meta["budget"]
+    end
+
+    # Replicate the iteration order of JavaScript's Object.keys, which the original
+    # tool relies on (C = Object.keys(projects), N = Object.keys(votes)): integer
+    # "array index" keys come first in ascending numeric order, followed by all
+    # other keys in insertion order. Project/voter IDs are typically numeric strings,
+    # so this ordering affects tie stability (e.g. greedy utilitarian completion).
+    ARRAY_INDEX = /\A(?:0|[1-9]\d*)\z/
+    UINT32_MAX = (2**32) - 1
+
+    def self.js_key_order(keys)
+      indices, others = keys.partition { |k| ARRAY_INDEX.match?(k) && k.to_i < UINT32_MAX }
+      indices.sort_by(&:to_i) + others
+    end
+  end
+end

data/lib/equalshares/max_flow.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Equalshares
+  # Dinic's maximum-flow algorithm with integer capacities. Used by the maximin
+  # support rule to compute the exact minimum max-load (a max-density subgraph) via
+  # a parametric max-flow, keeping the gem pure-Ruby and dependency-free.
+  class MaxFlow
+    def initialize(num_nodes)
+      @num_nodes = num_nodes
+      @graph = Array.new(num_nodes) { [] } # node -> array of edges [to, cap, rev_index]
+    end
+
+    def add_edge(from, to, cap)
+      @graph[from] << [to, cap, @graph[to].size]
+      @graph[to] << [from, 0, @graph[from].size - 1]
+    end
+
+    def max_flow(source, sink)
+      flow = 0
+      while build_levels(source, sink)
+        @iter = Array.new(@num_nodes, 0)
+        while (pushed = augment(source, sink, Float::INFINITY)).positive?
+          flow += pushed
+        end
+      end
+      flow
+    end
+
+    # Nodes reachable from `source` in the residual graph (the source side of a
+    # minimum cut after max_flow has run).
+    def reachable_from(source)
+      visited = Array.new(@num_nodes, false)
+      visited[source] = true
+      queue = [source]
+      until queue.empty?
+        node = queue.shift
+        @graph[node].each do |edge|
+          to, cap, = edge
+          next unless cap.positive? && !visited[to]
+
+          visited[to] = true
+          queue << to
+        end
+      end
+      visited
+    end
+
+    private
+
+    # Builds the BFS level graph; returns whether the sink is reachable.
+    def build_levels(source, sink) # rubocop:disable Naming/PredicateMethod
+      @level = Array.new(@num_nodes, -1)
+      @level[source] = 0
+      queue = [source]
+      until queue.empty?
+        node = queue.shift
+        @graph[node].each do |edge|
+          to, cap, = edge
+          next unless cap.positive? && @level[to].negative?
+
+          @level[to] = @level[node] + 1
+          queue << to
+        end
+      end
+      !@level[sink].negative?
+    end
+
+    # The level graph is at most a few layers deep (source-project-voter-sink), so
+    # this recursion stays shallow.
+    def augment(node, sink, limit)
+      return limit if node == sink
+
+      while @iter[node] < @graph[node].size
+        edge = @graph[node][@iter[node]]
+        to, cap = edge
+        if cap.positive? && @level[node] < @level[to]
+          delta = augment(to, sink, [limit, cap].min)
+          if delta.positive?
+            edge[1] -= delta
+            @graph[to][edge[2]][1] += delta
+            return delta
+          end
+        end
+        @iter[node] += 1
+      end
+      0
+    end
+  end
+end

data/lib/equalshares/maximin.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Equalshares
+  # Facade for the maximin support rule; delegates to Rules::Maximin.
+  module Maximin
+    module_function
+
+    def support(instance, params = Params.new, progress: nil)
+      Rules::Maximin.call(instance, params, progress: progress)
+    end
+  end
+end

data/lib/equalshares/mes_general.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Equalshares
+  # Facade for the Method of Equal Shares on cardinal/ordinal ballots; delegates to
+  # Rules::CardinalMes.
+  module MesGeneral
+    module_function
+
+    def equal_shares(instance, params = Params.new, progress: nil)
+      Rules::CardinalMes.call(instance, params, progress: progress)
+    end
+  end
+end

data/lib/equalshares/pabulib/csv.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Equalshares
+  module Pabulib
+    # Low-level lexing shared by the parser: the ';'-delimited, double-quote-escaped
+    # field splitter (port of parseCSVLine in js/pabulibParser.js) and the JS-style
+    # numeric check.
+    module Csv
+      module_function
+
+      def parse_line(line)
+        result = []
+        current = +""
+        in_quotes = false
+        i = 0
+
+        while i < line.length
+          char = line[i]
+          if char == '"'
+            if in_quotes && i + 1 < line.length && line[i + 1] == '"'
+              current << '"'
+              i += 2
+            else
+              in_quotes = !in_quotes
+              i += 1
+            end
+          elsif char == ";" && !in_quotes
+            result << current
+            current = +""
+            i += 1
+          else
+            current << char
+            i += 1
+          end
+        end
+
+        result << current
+        result
+      end
+
+      # Whether a string parses as a number the way JavaScript's Number() does: empty
+      # or whitespace-only strings count as numeric (they coerce to 0), nil does not.
+      def numeric_string?(value)
+        return false if value.nil?
+
+        str = value.strip
+        return true if str.empty?
+
+        Float(str)
+        true
+      rescue ArgumentError, TypeError
+        false
+      end
+    end
+  end
+end

data/lib/equalshares/pabulib/parser.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Equalshares
+  module Pabulib
+    # Mutable bag of results filled in as the sections are read.
+    Accumulator = Struct.new(:meta, :projects, :votes, :approvers, :scores,
+                             :project_ids_set, :voter_ids_set, keyword_init: true)
+
+    # Reads a pabulib (.pb) document: drives the META / PROJECTS / VOTES section state
+    # machine and delegates each data row to the appropriate row parser.
+    class Parser
+      def parse(text)
+        @acc = Accumulator.new(meta: {}, projects: {}, votes: {}, approvers: {}, scores: {},
+                               project_ids_set: {}, voter_ids_set: {})
+        @encountered = {}
+        @section = ""
+        @header = []
+        @line_number = 0
+
+        text.split("\n").each do |line|
+          @line_number += 1
+          handle_line(line) unless line.strip.empty?
+        end
+
+        finish
+      end
+
+      private
+
+      def handle_line(line)
+        row = Csv.parse_line(line)
+        if section_header?(row)
+          start_section(row)
+        elsif @header.empty?
+          read_header(row)
+        else
+          dispatch_row(row)
+        end
+      end
+
+      def section_header?(row)
+        SECTIONS.include?(row[0].strip.downcase)
+      end
+
+      def start_section(row)
+        @section = row[0].strip.downcase
+        @encountered[@section] = true
+        @header = []
+      end
+
+      def read_header(row)
+        @header = row.map(&:strip)
+        return unless @section == "meta" && (@header[0] != "key" || @header[1] != "value")
+
+        raise ParseError, "Line #{@line_number}: Invalid header in meta section (expecting \"key;value\")."
+      end
+
+      def dispatch_row(row)
+        case @section
+        when "meta"
+          @acc.meta[row[0]] = row[1].strip
+        when "projects"
+          (@project_row_parser ||= ProjectRowParser.new(@acc)).parse(row, @header, @line_number)
+        when "votes"
+          (@vote_row_parser ||= VoteRowParser.new(@acc)).parse(row, @header, @line_number)
+        end
+      end
+
+      def finish
+        SECTIONS.each do |section_name|
+          next if @encountered[section_name]
+
+          raise ParseError, "The file is missing the required '#{section_name}' section."
+        end
+        unless Csv.numeric_string?(@acc.meta["budget"])
+          raise ParseError, "The 'budget' in the meta section is not a numeric value."
+        end
+
+        scored = SCORED_VOTE_TYPES.include?(@acc.meta["vote_type"])
+        Instance.new(meta: @acc.meta, projects: @acc.projects, votes: @acc.votes,
+                     approvers: @acc.approvers, scores: scored ? @acc.scores : nil)
+      end
+    end
+  end
+end

data/lib/equalshares/pabulib/project_row_parser.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Equalshares
+  module Pabulib
+    # Parses a single row of the PROJECTS section into the accumulator.
+    class ProjectRowParser
+      def initialize(accumulator)
+        @acc = accumulator
+      end
+
+      def parse(row, header, line_number)
+        project_id_idx = header.index("project_id")
+        cost_idx = header.index("cost")
+        name_idx = header.index("name")
+
+        require_columns!(project_id_idx, cost_idx, line_number)
+        # Validate the column count before any indexed access, so a short row raises a
+        # ParseError rather than a NoMethodError on nil.
+        validate_column_count!(row, header, line_number)
+
+        project_id = row[project_id_idx].strip
+        if @acc.project_ids_set[project_id]
+          raise ParseError, "Line #{line_number}: Duplicate project ID '#{project_id}' found."
+        end
+        if row[project_id_idx].to_s.empty? || !Csv.numeric_string?(row[cost_idx])
+          raise ParseError, "Line #{line_number}: Invalid or missing values in projects section."
+        end
+
+        store(row, header, project_id, name_idx)
+      end
+
+      private
+
+      def require_columns!(project_id_idx, cost_idx, line_number)
+        return unless project_id_idx.nil? || cost_idx.nil?
+
+        missing = []
+        missing << "project_id " if project_id_idx.nil?
+        missing << "cost" if cost_idx.nil?
+        raise ParseError, "Line #{line_number}: Missing required column(s) in projects 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 projects section."
+      end
+
+      def store(row, header, project_id, name_idx)
+        @acc.project_ids_set[project_id] = true
+        @acc.projects[project_id] = {}
+        @acc.approvers[project_id] = []
+        header.each_index { |idx| @acc.projects[project_id][header[idx].strip] = row[idx].strip }
+
+        name = @acc.projects[project_id]["name"]
+        @acc.projects[project_id]["name"] = project_id if name_idx.nil? || name.nil? || name.strip.empty?
+      end
+    end
+  end
+end