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.
You'll probably want to run VoteEngine from the console/shell. You can do this by typing
python voteengine.pyVoteEngine 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 >outputfileIf your system can run python scripts in that way.
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.
If you have some knowledge of python, you can use the python console to run VoteEngine.
from votemain import vote_engine
Comments may appear anywhere in the input file. Any part of an input line after a "#" is ignored.
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
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
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
c//irv Condorcet winner if one exists. Otherwise IRV
irv Commonly used successive lowest plurality elimination method
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.
schulze Apply the minmax floyd algorithm.
table Not actually a method. Just prints the pairwise table.
rp Ranked Pairs
ukvt apply the rules used by the uk.* usenet hierarchy.
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
means that the numbers 1 through 12 will be used to designate candidates. You can also use letters.
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,
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
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
More characters and sequences are legal in this form than in a range. You can also combine ranges with separately specified candidates.
For, example if you have designations with a special meaning. For example "SQ" for Status Quo, or "RO" for re-open discussion.
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.
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.
# 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.
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.
Here is an example ballot line.
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.
B C A
A C B
Each of the ballots above is scored as 1 vote.
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.
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.
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.
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.