README

RubyVote: Election Methods Library in Ruby
=============================================

.. Caution::

   This software is pre release software. The authors of this software
   are neither expert Ruby programmers or elections in election
   methods. We are hackers and enthusiasts in both. This software has
   bugs and it's quite possible that is has bugs that may skew
   results. If you understand Ruby or election methods, please audit
   the code.

Overview
---------

**Latest Version:** 0.2

**Download Latest Version:** `here
<http://rubyforge.org/projects/rubyvote>`__

`RubyVote` is an election methods library implemented in Ruby.  It is
designed to make it very easy to implement a variety of different types
of elections in Ruby including relatively complex election methods like
Condorcet.  It could be useful for any sort of election, poll, or
decision making.

New Versions
*************

`RubyVote` is graciously hosted by `RubyForge
<http://rubyforge.org/>`__.

You can visit the `RubyVote` homepage (a version of this file) here:

 http://rubyvote.rubyforge.org/

You can visit the RubyForge project page to download the latest
version of software, get access to the latest development version from
Subversion, to file or bug, to look through documentation, to
participate in the forums, or to contribute in other ways. That page
is here:

 http://rubyforge.org/projects/rubyvote


More Information
*****************

`RubyVote` is a library -- not an application or a voting machine. It
simply takes the raw "tallies" of votes and computes the results.
Currently, it does not include any sample interfaces (although if
contributed, these may be included).

`RubyVote` currently includes a set of classes to tally votes and compute
winners in elections or votes using a series of different methods.
Currently these include:

* `Plurality`__ or "winner-take-all"
* `Approval`__
* `Borda`__
* `Simple Condorcet`__
* `Condorcet with Cloneproof SSD`__
* `Instant Runnoff Voting`__ (Thanks Alexis Darrasse!)

__ http://en.wikipedia.org/wiki/Plurality_electoral_system
__ http://en.wikipedia.org/wiki/Approval_voting
__ http://en.wikipedia.org/wiki/Borda_count
__ http://en.wikipedia.org/wiki/Condorcet_method
__ http://en.wikipedia.org/wiki/Schulze_method
__ http://en.wikipedia.org/wiki/Instant_Runoff_Voting

Writing support for a currently unsupported voting method is a fantastic
way to to contribute to this module.

How To Use This Library
-------------------------

Using this library is relatively simple but will differ per election
methods. In each case, you will need to ``require`` the appropriate
file for the type of election you will be running and then create a
new vote object. You should then either pass an array of votes to the
object upon creation or pass votes in one at at a time.


.. Note::

   *You* are responsible for ensuring that the votes are in correct
   form before you hand them to this module. This will not currently
   check for most types of invalid votes and does not (currently)
   accept a list of candidates at creation from which it checks all
   votes. As such, new candidates will be created when seen. If you
   think this is a meaningful addition to this library, please send a
   patch. Otherwise, please check for the validity of votes BEFORE you
   pass them to this election module.

Examples of each type of election currently supported can be seen in
the test.rb file distributed in this archive.

ElectionVote Objects
*********************

Each ElectionVote object has the following exposed attributions:

* ElectionVote#votes -- returns a list of votes that have been tallied
* ElectionVote#candidates -- returns a list of candidates

Additionally, each subclass will create a #results method which will
return an ElectionResult subclass of the appropriate type.

Currently, you use this module by creating any of the following types
of vote objects:

Plurality
^^^^^^^^^^

This is the most simple "winner-take-all" system. The array passed to
the new vote object should be an array of strings. Each string is
counted as one vote for a candidate.

Example::

 require 'election'
 vote_array = [ "A", "B", "B", "A" ]
 resultobject = PluralityVote.new(vote_array).result

Approval
^^^^^^^^^

Approval is similar to plurality voting except that users can vote for
more than one candidate at once naming all of the candidates that they
approve of.

Example::

 require 'election'
 vote_array = [ ["A", "B"],  ["B", "A"], ["B"] ]
 resultobject = ApprovalVote.new(vote_array).result

Borda
^^^^^^

Borda is a positional voting system and, as a result, takes a list of
ranked candidates and assigns points to each candidates based on their
order. In Borda, there are *n* candidate and the first candidates is
assigned *n* - 1 points and each subsequent candidate is assigned one
less point. The candidate is assigned no points.

Currently, all candidates should be ranked in each ballot.

Example::

 require 'positional'
 vote_array = [ ["A", "B"],  ["B", "A"], ["B", "A"] ]
 resultobject = BordaVote.new(vote_array).result

Pure Condorcet
^^^^^^^^^^^^^^^^

Condorcet is a preferential system and, as such, each vote must list
of ranked preferences from most to least preferred. Currently, all
candidates must be listed. No ties are allowed on ballots with the
current implementation.

Example::

 require 'condorcet'
 vote_array = [ ["A", "B"],  ["B", "A"], ["B", "A"] ]
 resultobject = PureCondorcetVote.new(vote_array).result

Cloneproof Schwartz Sequential Dropping
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

`Cloneproof SSD` is a Condorcet variant with the ability to create
winners in circular defeats (e.g., A beats B, B beats C, C beats A)
where this is no clear winner in Condorcet. It is used identically to
Pure Condorcet.

Example::

 require 'condorcet'
 vote_array = [ ["A", "B"],  ["B", "A"], ["B", "A"] ]
 resultobject = CloneproofSSDVote.new(vote_array).result

Instant Runnoff Voting (IRV)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

IRV is a preferential voting system used widely for government elections
in Australia and New Zealand and elsewhere. IRV asks voters to rank
candidates in preference and then holds a series of "runoff" elections
by eliminating the weakest candidate and recomputing the election
results until there exists a candidate who has a majority of the
remaining votes.

Example::

 require 'runoff'
 vote_array = [ ["A", "B"],  ["B", "A"], ["B", "A"] ]
 resultobject = InstantRunoffVote.new(vote_array).result


ElectionResult Objects
***********************

Each election result object will have the following methods:

* #winner? -- return Boolean as to the winner or winners of an election
* #winners -- an array of winners of the election
* #ranked_candidates -- (where available) a list of ranked candidates


License
--------

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 2 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, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301, USA.

Look in the COPYING file for the text of the GNU GPL.

Authors
--------

Currently, the only contributor to this program is Benjamin Mako Hill
working at the MIT Media Lab. Please feel free to contribute to this
module and get your name added here.

For more information about Mako and his programs, you can see his
homepage here:

 http://mako.cc

For more information about the MIT Media Lab, you can see its homepage
here:

 http://www.media.mit.edu