Project 1: Instant Runo Voting

CS 201; Spring 2011 Due: Monday Jan 24, 11:59AM

Objectives
Practice taking a somewhat non-trivial specication to a Java implementation. Working with Files and Command Line arguments General freshening of Java skills

Introduction
Suppose we are holding an election for Dog Catcher (or Mayor or whatever). In the system probably most familar to you, each voter selects one of the candidates (of which there may be many). Whoever gets the most votes wins (assuming there isnt an exact tie). In this system (commonly called plurality voting, or First past the poll voting) the winner may not have a majority of the votes. In the 1992 presidential election, Bill Clinton received about 43% of the popular vote, George Bush about 37.5% of the popular vote and Ross Perot about 18.9%. Supposing that presidential elections were based on popular vote1 using plurality voting, Clinton won even though he did not receive more than 50% of the vote. Some criticize this system for many reasons including the spoiler eect. For example, it may have been the case that had Ross Perot not been in the election, more of his votes would have gone to Bush rather than Clinton i.e., more people may have preferred Bush to Clinton. But plurality voting isnt the only system. An alternative is called Instant Runo Voting (IRV). In IRV, voters do not pick a single candidate, instead they rank all of the candidates according to their preference. For example suppose there are three candidates Alice, Bob and Cathy. As a voter I can ll out my ballot in one of six dierent ways: Candidate Alice Bob Cathy Option 1 1 2 3 Option 2 1 3 2 Option 3 2 1 3 Option 4 3 1 2 Option 5 2 3 1 Option 6 3 2 1

In general if we assume there are n candidates are given in some order (candidate 1, candidate 2, etc.) then a completed ballot can be represented as an ordering or permutation of the integers 1..n. There are n! ways of completing such a ballot.

Determining a Winner in IRV

Given m the ballots as described, we determine the winner of the election in IRV by proceeding in rounds as follows (from Wikipedia). 1. In the rst round, votes are counted by tallying rst preferences (in the same way as plurality voting, or First-past-the-post). 2. If no candidate has a majority of the votes, the candidate with the fewest number of votes is eliminated and that candidates votes are counted at full value for the remaining candidates according to the next preference on each ballot. 3. This process repeats until one candidate obtains a majority of votes among the remaining candidates (or only two candidates remain with exactly 50% each and a tie is declared).
1

In fact its a little more complex because of the Electoral College system, but we can pretend

The table below continues the previous example by adding the results of an election with 100 voters. The bottom line indicates the number of voters selecting each of the 6 possible ballot congurations. Candidate Alice Bob Cathy Ballots Option 1 1 2 3 23 Option 2 1 3 2 20 Option 3 2 1 3 10 Option 4 3 1 2 28 Option 5 2 3 1 3 Option 6 3 2 1 16

Applying the rules of IRV, we rst examine the top choice of each ballot: 43 of the 100 voters listed Alice as their top choice, 38 listed Bob as their top choice 19 listed Cathy as their top choice Since none of the candidates received more than 50 votes, the lowest vote getter, Cathy is eliminated. The votes that had Cathy as their preferred candidate are redistributed to the remaining candidates based on their next preference. Among the 19 voters who rated Cathy as their top choice, 3 listed Alice as their next choice and 16 listed Bob as their next choice. As a result, Alice now has 46 of the votes (43 + 3) and Bob has 54 (38 + 16) and Bob is declared the winner. If there are more than three candidates, this process may repeat several times before a candidate has over 50% of the vote. During any round, the vote of a ballot is awarded to the highest ranked candidate on the ballot which has not yet been eliminated.

Program Specications
It is very important that your program behaves as specied below. Deviations from this specication will be penalized Your program will be called Irv i.e., you will have a le Irv.java containing the class Irv which has a main method. It will take two le names as command line arguments.2 The rst contains the election data (your program will read this le) and the second is the name of the le to which you will write a report of the results. For example at the Linux shell, you should be able to do this:

$ javac Irv.java $ java Irv dogCatcher.inp dogCatcher.rpt The rst command compiles the program. The second runs the program with input le dogCatcher.inp and output le dogCatcher.rpt You may write other classes in other les with names of your choice; but the main method must be in Irv class.

Input File Format

Input les contain election results by rst listing the candidates, one per line, followed by the ballots (as sequences of integers). To indicate the beginning of a ballot, the string <b> will be used (without the quotes). The order in which the candidates are listed implicitly indicates their position (candidate 1, 2, etc.) For example a le might look like this:
2

If you ever wondered why the main method always has an array of Strings as a parameter, you are about to nd out.

Larry Smith Moe Jones Curly Sampson <b> 1 3 2 <b> 2 1 3 <b> 2 3 1 Here, the rst ballot ranks Larry rst, Curly second and Moe third. The le format is intended to be easy to parse (e.g., by having one candidate per line). As in the example, the rank list for the ballots may span multiple lines; the individual ranks are just separated by white space (e.g., a space character, tab or newline). Illegal Ballots: For the purposes of this project, a legal ballot must rank each candidate and no two candidates can have the same rank. Ranks, of course, must be in the range 1..n where n is the number of candidates. Equivalently, a legal ballot must be a permutation of integers 1..n. For a three candidate race like above, the following would all be illegal ballots: <b> 1 3 1 <b> 1 2 <b> 3 1 2 4 Illegal ballots are simply discarded and you tally the results for the remaining legal ballots.

Output File
In the output le you will write the following information (in this order): The name of the election results le. The number of candidates followed by the candidate names (in the same order as in the input le). The number of submitted ballots, the number of legal ballots and the number of discarded ballots. A round-by-round summary of the process. For each round include the following: the number of votes and vote percentage for each candidate that has not been eliminated in a previous round. If a winner can be declared it is reported and the output is complete. If there are only two candidates left and the exactly tie, this is reported and the output is complete. Otherwise, the report states which candidate has been eliminated for the next round. For example, suppose we had an input le for the 3-way election between Alice, Bob and Cathy. My output le might look like this (lets suppose the input le is mayor.inp and that there were 117 ballots of which 100 were legal): Election input file: dogCatcher.inp Number of candidates: 3 Candidates: Alice Bob Cathy Total ballots: 117 Legal ballots: 100 Discarded ballots: 17

Round 1 results: Alice: 43 (43%) Bob: 38 (38%) Cathy: 19 (19%) No winner. Cathy eliminated Round 2 results: Alice: 46 (46%) Bob: 54 (54%) Bob declared winner

Submission
You will submit all of your source les using the turnin command on the CS Department machines. The project name will simply be project1

Rules of the Road

You may of course use any classes of your own creation, arrays, etc. But your usage of classes from the JDK should be limited to ArrayList, String, File, FileInputStream, Scanner and FileOutputStream. If there is some other class you want to use, feel free to ask. Avoid/eliminate global variables. In the context of Java, these are basically static class variables. Apply the principles of problem decomposition. Avoid overly-long methods (break them down). Dene classes as appropriate to decouple components/concepts in your code (e.g., I havent written my version yet, but Im thinking about having a Ballot class.) Use good variable and method names; document your code as you are writing not as an afterthought! Suggestion: do some pencil and paper planning before jumping on the computer!

Resources
1. Wikipedia entry on IRV: http://en.wikipedia.org/wiki/Instant-runo voting 2. Chapter 11 of online free Java book (includes info on File I/O and the Scanner class): http://math.hws.edu/javanotes/ 3. Also take advantage of the discussion board opened for the project and FAQs that the TAs and I may post.