home

Documentation for VoteEngine 0.99

VoteEngine comes with no warranty. It may not work. See the notice at the bottom of this document.

VoteEngine is actually made up of a few Python scripts. As a result, you need to have both Python, and the Numeric python package (Numpy) installed to use VoteEngine. 


There are multiple ways to run VoteEngine.  How you choose to do so will depend both on your own preference, and on the operating system you are using.

Linux/Unix
You'll probably want to run VoteEngine from the console/shell.  You can do this by typing
python voteengine.py
VoteEngine uses the standard input and output.  These may be re-directed as usual.  If the execution bit is set for voteengine.py, you may be able to run it like this
./voteengine.py <inputfile >outputfile
If your system can run python scripts in that way.

Windows

To run VoteEngine in Windows, double-click the ve.py script.  This script looks for a file named "input.txt" and produces an output file called "output.txt".  Just put whatever input you want into the "input.txt" file.

Python

If you have some knowledge of python, you can use the python console to run VoteEngine.

from votemain import vote_engine
vote_engine(open("inputfile"),open("outputfile","w"),"-m borda")

Input File

Comments

Comments may appear anywhere in the input file. Any part of an input line after a "#" is ignored.

-cands A-C # this comment will be ignored

Commands

Any line beginning with a "-" is interpreted as one or more commands. Each new command on a line begins with its own "-" following a space of tab. For example

-m minmax -cands A-C -tie A B C

This line provides three different commands. Notice that the hyphen in "A-C" does not introduce a new command, because there is no space before it.

You may also place commands as initial arguments on the command line, for example

python voteengine.py <test -m tideman -cands A-C

-m ### choose method

This command is required, and must precede all other commands, as well as the ballots. This command allows you to choose the method for tabulation. The following methods are available. See Method Definitions

borda

borda-elim

bucklin

c//irv     Condorcet winner if one exists. Otherwise IRV

copeland

irv     Commonly used successive lowest plurality elimination method

minmax 

nanson     Nansons's orginal method

pw_elim     successively eliminate candidate with greatest pairwise defeat.

s//irv     eliminates candidates outside the Smith set, then does IRV.

s//minmax 

schulze     Apply the minmax floyd algorithm.

smith

table     Not actually a method. Just prints the pairwise table.

rp     Ranked Pairs

ukvt     apply the rules used by the uk.* usenet hierarchy.

-cands ### Designate candidates

The "-cands" command is required. It should come after the "-m" command, but before everything else.

The "-cands" command must be given a list of candidate designations that will be used in the various printouts provided by the programming. Candidates actual names would be too long, so instead each candidate is assigned a letter or number. This command allows you to specify a range for use by the candidates. For example

-cands 1-12

means that the numbers 1 through 12 will be used to designate candidates. You can also use letters.

-cands A-F

designates the candidates as A through F. To allow more that 26 candidates, VoteEngine allows you to make use of a letter sequence that proceeds A to Z, then AA to ZZ, then AAA to ZZZ and so on. So, you can say,

-cands V-RS

which means V, W, X, Y, Z, AA, AB, AC, AD … AZ, ZA, ZB, … RS

You can also use special ranges that combine a letter and number series, as follows

-cands A1-C3

This produces the sequence, A1, A2, A3, B1, B2, B3, C1, C2, C3.

It is important to note that only the <letter><number> form is supported.

You don’'t have to use ranges, however, you can specify specific candidates, like

-cands 7A AB Q R+ C’ D

More characters and sequences are legal in this form than in a range. You can also combine ranges with separately specified candidates.

-cands A-F SQ RO

For, example if you have designations with a special meaning. For example "SQ" for Status Quo, or "RO" for re-open discussion.

-tie ### tie breaking order

It is possible that the ballots listed will result in a tie for the particular method chosen. The "-tie" command allows you to list candidates in an order that will be used to break ties, with the preferred candidates listed earlier. You must list all candidates.

/dir -tie A B C D

Just how the tie-breaking order will be used is dependent on the method chosen.

-table ## enter a table

The table command allows you to enter pairwise data in the form of a table, rather than as ballots. The table data is added to any other data entered, so you could use this to sum two or more tables, if you wanted to. It only works if the selected method is exclusively a pairwise method. This includes the "table" method, which can be used to add up tables.

-table

# A B C D

A X 5 3 7 # comments are allowed here

B 4 X 9 2

C 8 7 X 6

D 5 3 9 X

The table entry format is meant to be forgiving. It counts back from the end of the line to determine how many words or numbers it reads in. This means that you can put whatever you want at the beginning of the line and it will be ignored. Similarly, you can put any single word in the long diagonal where the row and column are equal. I prefer "X", as above, but you could also use "N/A" or 0, or anything else that is one word long.

You can also use comments to provide extra information, for example, column headers as above, or comments after the information on the line.

-wv ## winning-votes mode

When a method uses a pairwise table, it normally uses the marginal pairwise table.  However, with this option you can cause the procedure to zero-out pairwise non-wins, resulting in a "winning-votes" table.   So, for example, 10 to 9 is treated like 10 to 0.

Ballots

Here is an example ballot line.

30: A B= C > D E # comments allowed

An "=" declares that two candidates are ranked as equal. If no equal sign is present, candidates are assumed to be listed in descending preference. You may use a ">" sign to express this, but one is not required. Any candidates not listed are ranked as equal to one another, but lesser than all listed candidates.

The "30" says that 30 votes will be scored according to the ranking given.

If the number and colon are omitted, then it is assumed that only one ballot is being counted.

A B C

B C A

A C B

Each of the ballots above is scored as 1 vote.

Output

The output produced by VoteEngine varies with the method being used. If you don’t use any method, the pairwise table is calculated, and the program exits.

Most methods will provide a ranking of the candidates. Usually, this ranking will be straightforward.

A > B > C > D

This simply orders the candidates from highest (A) to lowest (D). However, if some form of tie results, the ranking may be more complicated. In this case, the "," is used to remain non-committal about the relative value of two candidates. For example.

If a complete ranking cannot be determined, VoteEngine prints a Win/Loss/Unknown table.

Future Directions

I hope to improve this program over time. If you have any suggestions, especially of actual code, please let me know. I don't expect many people to use this program, so I'm interested in hearing from anyone who does. In any case, I hope you find VoteEngine useful.

Disclaimer of all warranty

IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.