IRV-Vote - a Perl/CGI script for conducting Instant Runoff Voting (IRV) elections and polls on the web. Current Version 0.6, as of 03/20/2004. Download: http://www.tedsowinski.com/irv/IRV-Vote.0.6.tar.gz Written by Ted Sowinski, email: t_sowinski@yahoo.com License: GPL For more information about IRV visit www.instantrunoff.com and www.fairvote.org. Features. - easily installed and configured - no special requirements except Perl Compatibility. IRV-Vote is written in perl and was developed under Red Hat Linux 6.1 and Apache 1.3. It should run with only slight changes on all Linux and Unix Apache web servers. If you're stuck with Microsoft's web server, too bad! Files in this package: README - this file common.pl - shared CGI functions, courtesy of Shishir Gundavaram irv_vote.cgi - voting script irv_tally.cgi - vote tallying script irv_vote.conf - sample configuration file b1.txt, b2.txt - sample data files (cast ballots) mk_test_cases.pl - a Perl script to generate random votes for testing the tally script. irv_head.html - a sample head file. irv_tail.html - a sample tail file. irv_ballot_instructions.html - a sample ballot instructions file. irv_login.cgi - login script irv_register.cgi - registration script borda_tally.cgi - tallies votes using the Borda Count method condorcet_tally.cgi - tallies votes using the Condorcet method Installation. Install files. 1) Create a subdirectory under your cgi-bin directory, say "irv". 2) Download http://www.tedsowinski.com/irv/IRV-Vote.0.6.tar.gz into this directory. 3) Run "tar zxf IRV-Vote.0.6.tar.gz" Configure the perl scripts for your machine. All the perl scripts assume perl is at /usr/local/bin/perl. If not edit the first line of each script. Test install. Try it from your browser: Voting script: http://www.yourhome.com/cgi-bin/irv/irv_vote.cgi Tally script: http://www.yourhome.com/cgi-bin/irv/irv_tally.cgi They should look and work the same as mine: http://www.tedsowinski.com/irv/irv_vote.cgi http://www.tedsowinski.com/irv/irv_tally.cgi How to customize. Edit the default config file, irv_vote.conf -- you can create multiple conf files, but more on this later. In one config file you can set up multiple ballots that can be displayed on a menu. Clicking on a ballot brings up the voting ballot (irv_vote.cgi) or the results for that election (irv_tally.cgi). Each ballot can contain multiple "offices". Candidates are defined for each office. Blank lines and lines beginning with # are ignored. The conf file is divided into sections, delimited by [...]. There are three types of sections: 1. [global] is for customizing the menu of ballots. 2. [ballot=x] is for defining ballots. 3. [office=y] is for defining offices within a ballot. In each section there are key=value pairs for customizing HTML bgcolor, text color, title, headings, and office and candidate names. Valid options. [global] options: title, h1, h2, h3, bgcolor, text [ballot=x] options: title, h1, h2, h3, bgcolor, text, sort_candidates, head_file, tail_file, ballot_instructions_file, one_vote_per_ip, polls_open, polls_close, hide_results_until_polls_close. [office=y] options: title, cand x and y are used internally to name the ballots and offices. x is also used to name the ballot data files, i.e., x.txt. Make sure all ballots are uniquely named -- across all config files! Office names must only be unique within the same ballot. Candidates are normally listing on the ballot sorted by name; this can be turned off by adding "sort_candidates=0" to the ballot section and before the first office section. "head_file" allows you to customize the top of all HTML pages. You can have a different head_file for each ballot. If omitted it uses file irv_head.html, if it exists. "tail_file" allows you to customize the bottom of all HTML pages. You can have a different tail_file for each ballot. If omitted it uses file irv_tail.html, if it exists. "ballot_instructions_file" allows you to customize the header at the top of the ballot page. You can have different files for different ballots. If omitted it uses file irv_ballot_instructions.html, if it exists. "one_vote_per_ip" - If set to "1" voters can still vote multiple times, but only the last ballot is counted. Note: this will not work right is your users are behind a firewall; I use their IP address as the key. The default is count all ballots. If you turn this option on, it may be a good idea to tell the voters only their last vote will count in the ballot_instructions_file. "polls_open" - Set this to a date and time in this format: mm/dd/yyyy hh:mm to prevent voters from voting until the polls open. (They will still see a "Sample Ballot".) "polls_close" - Set this to a date and time in this format: mm/dd/yyyy hh:mm to prevent voters from voting after the polls close. (A link is provided to see the results.) "hide_results_until_polls_close" - set to "1" to prevent voters from seeing the results until the polls close. "login_required" - set to "1" to require voters to register and login before voting. "passwd_file" - set to the name of a password file (if login_required=1). The default is "users" and it will be in the same directory as the scripts. For better security put it in some directory not under the webserver's document root, for example, passwd_file=/etc/httpd/irv_users. (Don't forget to touch this file and check it's permissions.) "one_vote_per_user" - Like "one_vote_per_ip", except if login_required=1, only counts the user's last ballot (regardless of the ip address). "my_email=" - if login_required=1, this is the "from:" email address used to send the user a confirmation. "verify_email" - if login_required=1, users must open the confirmation email and click on the link in order to vote. By default, after they register they can click on a link on the confirmation page and go right to the ballot to vote, whether the email address is valid or not. Well, not quite. They can also go back to the login page and enter their new username and password and then vote. "tie_resolution_strategy" - set to either "use_lower_ranks" or "by_lot". The default is "use_lower_ranks". See the sample config file, irv_vote.conf, for details. How to link it into your web site. Both scripts have a built in menu, so you can just refer to them (as above), but you can link to a particular ballot using CGI variables in the URL; i.e., http://www.tedsowinski.com/cgi-bin/irv/download/irv_vote.cgi?b=b2 will take you directly to the Favorite Fruit ballot and http://www.tedsowinski.com/cgi-bin/irv/download/irv_tally.cgi?b=b2 will take you directly to the Favorite Fruit election results. Alternate conf files. If you need more than one config file, just create another one and point to it in the URL using "c=" (without the .conf extension); for example, http://www.tedsowinski.com/cgi-bin/irv/download/irv_vote.cgi?c=best_movie Change History. 02/09/2002 v0.1 - Initial release. 02/13/2002 v0.2 - Minor bug fixes and enhancements to irv_vote.cgi. - If there were candidates with the same name, but for different offices, this was a problem on the confirmation page. Fixed - Changed the CGI method from GET to POST to hide all the votes. - More puctuation allowed in candidate names (:?!"();). - New config options, head_file, tail_file, and ballot_instructions_file, allow better customization of the generated HTML. - Better configuration instructions in the README. 02/21/2002 v0.3 - Minor enhancements to irv_tally.cgi. - Count the eliminated candidates; print the count on all reports, print the eliminated candidates on the summary report. - Changed the tie resolution logic when eliminating the weakest candidates. The "Golden Rule" of IRV says, "your less prefered choices must not affect your higher choices." This means when counting rank 2, 3, etc. votes, don't count votes where there is a higher preference for one of the other tied candidates on the same ballot. 03/05/2002 v0.4 - Minor enhancements to irv_vote.cgi and irv_tally.cgi. - Added new config file options: one_vote_per_ip, polls_open, polls_close, hide_results_until_polls_close. 11/13/2003 v0.5 - Some major enhancements. Note these were developed using Perl v5.8.0 and Apache v2.0. - New scripts for tallying the votes using the Borda Count and Condorcet methods for comparision with IRV. - Support for registered users -- see scripts irv_login.cgi, irv_register.cgi, and conf file option login_required above. - If the conf file only has one ballot, do not display the menu, go right to the ballot or the results. - Remove the choice for the tie resolution method from the tally results page and let the administrator set it in the conf file; it's probably confusing for the voter and should be the choice of the administrator. 03/20/2004 v0.6 - Minor bug fix. Some implementors had a problem during installation where if the sample conf file got contaminated with DOS carriage returns, the cgi scripts did not work properly. This change strips out DOS carriage returns as the files are read. To Do's. - Add other tie for the weakest candidate resolution methods: 1) compare round 1, rank 1 votes (fewest "core" supporters) and 2) Condorcet style comparisons to find the candidate least prefered by all voters. - The tally script can only handle a few hundred votes before it bogs down. Since this is only a demo, that's okay -- or is it? - Add graphics to the tally script. - Create a new script for setting up ballots online, a web editor for conf files.