meekster 0.0.1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MzMyNTE4M2Q1YmUwMTRhNDQ4YjE2YzgzZmJkMmUwZWU4ZjYyOGNhZA==
+  data.tar.gz: !binary |-
+    OWJmYzcxYmJiNjI2Y2QxMDY3Yzk2YjM3YjY4MmEzNzBiNjI3OGQ4Mw==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    MDhlODM1MmJhYWNkYzUwMzc0NmI3NmJlOTI1YTJjNDQwZWRjZmVjNTQ1NmQw
+    MjMzYmQxZTAwMTZiYjY0ZjBhNjAwOTFjNmU0Y2JhYTg2OTJmMjJiYTA0MTA1
+    ZTQ4YjYzNjhlMTc5Mzg5ODRkMTA3YmE5MDY3ZmQwYzk3ZTY1NDI=
+  data.tar.gz: !binary |-
+    YWJmMTc0N2ZmNTM4MjJlNzFlYWM5ZmFjYzYzNTkxZDllMDdkNTRlYWE5ZDI1
+    MjRmZjZiZWEwMzEzNzNjZTZjZDQ1MDA5ODdmYjc2YTU4ZDk1MTBkNzEwZmJi
+    NWNmMTdiNTBiMjg2MzM3MGU1YWFiYzU2ZGNjYzAwMTQwMWM3Nzc=

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/README.md

@@ -0,0 +1,31 @@
+Meekster
+========
+
+Meekster implements a Meek Single Transferable Vote (STV) voting system, as described in the [Proportional Representation Foundation's] [1] [Reference Meek Rule] [2], in Ruby.
+
+This software is a work-in-progress. You probably shouldn't use it for an actual election (yet).
+
+Some testing has been done against [Droop] [3], a Python Library that implements STV. Thanks to the authors of Droop for the software and test ballot files.
+
+License
+-------
+
+Copyright &copy; 2012 Chris Mear <chris@feedmechocolate.com>.
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+
+[1]: http://prfound.org/ "Proportional Representation Foundation"
+[2]: http://prfound.org/resources/reference/reference-meek-rule/ "Reference Meek Rule"
+[3]: http://code.google.com/p/droop/ "Droop"

data/Rakefile

@@ -0,0 +1,5 @@
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/lib/meekster.rb

@@ -0,0 +1,9 @@
+module Meekster
+end
+
+require 'meekster/ballot'
+require 'meekster/ballot_file'
+require 'meekster/candidate'
+require 'meekster/election'
+require 'meekster/round'
+require 'meekster/version'

data/lib/meekster/ballot.rb

@@ -0,0 +1,9 @@
+require File.expand_path('../meekster', File.dirname(__FILE__))
+
+class Meekster::Ballot
+  attr_accessor :ranking, :weight
+
+  def initialize(ranking=nil)
+    self.ranking = ranking
+  end
+end

data/lib/meekster/ballot_file.rb

@@ -0,0 +1,60 @@
+require File.expand_path('ballot', File.dirname(__FILE__))
+require File.expand_path('candidate', File.dirname(__FILE__))
+
+class Meekster::BallotFile
+  attr_accessor :candidates, :ballots, :seats
+
+  def initialize(options={})
+    if options[:filename]
+      @file = File.open(options[:filename], 'r')
+    elsif options[:string]
+      @file = StringIO.new(options[:string])
+    elsif options[:file]
+      @file = options[:file]
+    end
+
+    @read = false
+  end
+
+  def read!
+    @file.rewind
+
+    @ballots = []
+
+    candidates_and_seats = @file.gets
+    @candidate_count, @seats = candidates_and_seats.split(' ').map{|n| n.to_i}
+
+    @candidates = Array.new(@candidate_count){Meekster::Candidate.new}
+
+    ballot_line = @file.gets
+
+    until ballot_line.match(/^0/)
+      line_atoms = ballot_line.split(' ')
+
+      count = line_atoms.delete_at(0).to_i
+      line_atoms.delete_at(-1)
+
+      ranking = line_atoms.map{|id| @candidates[id.to_i - 1]}
+
+      count.times do
+        @ballots << Meekster::Ballot.new(ranking)
+      end
+
+      ballot_line = @file.gets
+
+    end
+
+    @candidate_count.times do |i|
+      candidate_name = @file.gets.strip
+      # Remove double-quotes
+      candidate_name = candidate_name.match(/\A\"(.*)\"\Z/)[1]
+      @candidates[i].name = candidate_name
+    end
+
+    @read = true
+  end
+
+  def read?
+    !!@read
+  end
+end

data/lib/meekster/candidate.rb

@@ -0,0 +1,13 @@
+require 'bigdecimal'
+
+class Meekster::Candidate
+  STATES = [:hopeful, :withdrawn, :elected, :defeated]
+
+  attr_accessor :name, :state, :keep_factor, :votes
+
+  def initialize(name=nil)
+    self.name = name
+    self.keep_factor = BigDecimal("1")
+    self.votes = BigDecimal('0')
+  end
+end

data/lib/meekster/election.rb

@@ -0,0 +1,85 @@
+require 'bigdecimal'
+require File.expand_path('../round', __FILE__)
+
+class Meekster::Election
+  attr_accessor :ballots, :candidates, :seats
+
+  def initialize(parameters={})
+    if parameters[:ballot_file]
+      bf = parameters[:ballot_file]
+      bf.read! unless bf.read?
+      self.ballots = bf.ballots
+      self.candidates = bf.candidates
+      self.seats = bf.seats
+    end
+    if parameters[:ballots]
+      self.ballots = parameters[:ballots]
+    end
+    if parameters[:candidates]
+      self.candidates = parameters[:candidates]
+    end
+    if parameters[:seats]
+      self.seats = parameters[:seats]
+    end
+  end
+
+
+
+  def run!
+    raise RuntimeError, "ballots not found" unless ballots
+    raise RuntimeError, "candidates not found" unless candidates
+    raise RuntimeError, "seats not found" unless seats
+
+    candidates.each do |candidate|
+      candidate.state = :hopeful
+    end
+
+    @omega = BigDecimal("0.000001")
+
+    @rounds = []
+
+    while true do
+
+      round = Meekster::Round.new(
+        :ballots => ballots,
+        :candidates => candidates,
+        :seats => seats,
+        :omega => @omega
+      )
+
+      round.run!
+
+      break if round.count_complete?
+
+      @rounds.push(round)
+    end
+
+    elected_candidates_count = candidates.select{|c| c.state == :elected}.length
+    hopeful_candidates = candidates.select{|c| c.state == :hopeful}
+    if elected_candidates_count < seats
+      hopeful_candidates.each do |hopeful_candidate|
+        hopeful_candidate.state = :elected
+      end
+    else
+      hopeful_candidates.each do |hopeful_candidate|
+        hopeful_candidate.state = :defeated
+      end
+    end
+
+    candidates
+  end
+
+  def results
+    output = ""
+    elected_candidates = candidates.select{|c| c.state == :elected}.sort{|a, b| a.votes <=> b.votes}
+    defeated_candidates = candidates.select{|c| c.state == :defeated}.sort{|a, b| a.name <=> b.name}
+
+    elected_candidates.each do |ec|
+      output << "Elected: #{ec.name} (#{ec.votes.to_f})\n"
+    end
+    output << "Defeated: "
+    output << defeated_candidates.map{|dc| dc.name}.join(', ')
+    output << "\n"
+    output
+  end
+end

data/lib/meekster/round.rb

@@ -0,0 +1,211 @@
+require 'bigdecimal'
+
+class Meekster::Round
+  attr_accessor :ballots, :candidates, :seats, :omega, :quota, :surplus
+
+  def initialize(parameters={})
+    self.ballots = parameters[:ballots]
+    self.candidates = parameters[:candidates]
+    self.seats = parameters[:seats]
+    self.omega = parameters[:omega]
+
+    @candidate_elected_this_round = false
+  end
+
+  def run!
+    if count_complete?
+      return # actually return something?
+    end
+
+    @previous_surpluses = []
+
+    while true do
+      log "STARTING NEW ITERATION"
+
+      log "Keep factors:"
+      candidates.each do |candidate|
+        log "  #{candidate.name} | #{candidate.keep_factor.to_f}"
+      end
+
+      reset_votes!
+
+      distribute_votes!
+
+      log "Counted votes:"
+      candidates.each do |candidate|
+        log "  #{candidate.name} | #{candidate.votes.to_f}"
+      end
+
+
+      update_quota!
+      find_winners!
+      calculate_total_surplus!
+
+      if candidate_elected_this_round?
+        return
+      end
+
+      if need_to_defeat_low_candidate?
+        defeat_low_candidate!
+        return
+      end
+
+      update_keep_factors!
+    end
+  end
+
+  def count_complete?
+    # Are all seats filled?
+    elected_candidates_count = candidates.select{|c| c.state == :elected}.length
+    if elected_candidates_count >= seats
+      log "Count complete: enough elected candidates to fill the seats"
+      return true
+    end
+
+    # Is number of elected plus hopeful candidates less than or equal to number of seats?
+    hopeful_candidates_count = candidates.select{|c| c.state == :hopeful}.length
+    if (elected_candidates_count + hopeful_candidates_count) <= seats
+      log "Count complete: elected+hopeful candidates less than or equal to seats"
+      return true
+    end
+
+    false
+  end
+
+  def reset_votes!
+    candidates.each do |candidate|
+      candidate.votes = BigDecimal('0')
+    end
+  end
+
+  def distribute_votes!
+    ballots.each do |ballot|
+      ballot.weight = BigDecimal('1')
+
+      ballot.ranking.each do |ranked_candidate|
+
+        weight_times_keep_factor = ballot.weight * ranked_candidate.keep_factor
+        weight_times_keep_factor = Meekster::Round.round_up_to_nine_decimal_places(weight_times_keep_factor)
+
+        ranked_candidate.votes += weight_times_keep_factor
+
+        ballot.weight -= weight_times_keep_factor
+
+        break if ballot.weight <= 0
+      end
+    end
+  end
+
+  def update_quota!
+    sum_of_votes = candidates.inject(BigDecimal('0')){|sum, c| sum + c.votes}
+    new_quota = sum_of_votes / (seats + 1)
+    # TODO truncate to nine decimal places
+    new_quota += BigDecimal('0.000000001')
+    log "Updating quota: #{new_quota.to_f}"
+    self.quota = new_quota
+  end
+
+  def find_winners!
+    candidates.select{|c| c.state == :hopeful}.each do |candidate|
+      if candidate.votes >= quota
+        log "Found winner: #{candidate.name}"
+        candidate.state = :elected
+        @candidate_elected_this_round = true
+      end
+    end
+  end
+
+  def calculate_total_surplus!
+    elected_candidates = candidates.select{|c| c.state == :elected}
+    sum_of_surpluses = elected_candidates.inject(BigDecimal('0')){|memo, c| memo + (c.votes - quota)}
+    log "Calculating total surplus. Sum of surpluses: #{sum_of_surpluses.to_f}"
+    if sum_of_surpluses < 0
+      self.surplus = 0
+      @previous_surpluses.push(surplus)
+    else
+      self.surplus = sum_of_surpluses
+      @previous_surpluses.push(surplus)
+    end
+  end
+
+  def candidate_elected_this_round?
+    !!@candidate_elected_this_round
+  end
+
+  def need_to_defeat_low_candidate?
+    if surplus < omega
+      log "Need to defeat low candidate."
+      return true
+    end
+
+    if @previous_surpluses.length > 1 && (surplus >= @previous_surpluses[-2])
+      log "Need to defeat low candidate (surplus greater than previous iteration)."
+      return true
+    end
+
+    log "Do not need to defeat low candidate."
+    false
+  end
+
+  def defeat_low_candidate!
+    log "Defeating lowest candidate:"
+    hopeful_candidates = candidates.select{|c| c.state == :hopeful}
+    candidate_with_lowest_vote = nil
+    hopeful_candidates.each do |hopeful_candidate|
+      if candidate_with_lowest_vote.nil? || hopeful_candidate.votes < candidate_with_lowest_vote.votes
+        candidate_with_lowest_vote = hopeful_candidate
+      end
+    end
+
+    log "  Lowest candidate: #{candidate_with_lowest_vote.name}"
+
+    # Detect ties
+
+    hopeful_candidates.delete(candidate_with_lowest_vote)
+    tied_candidates = hopeful_candidates.select{|c| c.votes <= (candidate_with_lowest_vote.votes + surplus)}
+
+    if tied_candidates.empty?
+      candidate_to_defeat = candidate_with_lowest_vote
+    else
+      candidates_with_lowest_votes = tied_candidates
+      candidates_with_lowest_votes.push(candidate_with_lowest_vote)
+      candidate_to_defeat = tiebreaker_select(candidates_with_lowest_votes)
+    end
+
+    candidate_to_defeat.state = :defeated
+    candidate_to_defeat.keep_factor = BigDecimal.new('0')
+  end
+
+  def update_keep_factors!
+    log "Updating keep factors:"
+    elected_candidates = candidates.select{|c| c.state == :elected}
+    quota_rounded = Meekster::Round.round_up_to_nine_decimal_places(quota)
+    elected_candidates.each do |elected_candidate|
+      elected_candidate_votes_rounded = Meekster::Round.round_up_to_nine_decimal_places(elected_candidate.votes)
+      new_keep_factor = elected_candidate.keep_factor * quota_rounded
+      new_keep_factor = new_keep_factor / elected_candidate_votes_rounded
+      log "  Candidate #{elected_candidate.name}: #{elected_candidate.keep_factor.to_f} -> #{new_keep_factor.to_f}"
+      elected_candidate.keep_factor = new_keep_factor
+    end
+  end
+
+  def self.round_up_to_nine_decimal_places(x)
+    ((x * BigDecimal('1E9')).ceil)/BigDecimal('1E9')
+  end
+
+  def self.truncate_to_nine_decimal_places(x)
+    ((x * BigDecimal('1E9')).floor)/BigDecimal('1E9')
+  end
+
+  def tiebreaker_select(array)
+    array[rand(array.length)]
+  end
+
+  # DEBUGGING
+
+  def log(msg)
+    return # Comment out to enable debugging
+    puts msg
+    gets
+  end
+end