OpenSTV was started in in the Fall of 2002 by Jeff O'Neill, who needed an excuse to get away from the mountain of reading required by the first year of law school. The code was first released in October 2003 under the name pSTV. The "p" in pSTV stood for Python as the code was and is written entirely in the Python programing language. The name was changed from pSTV to OpenSTV in October 2006 to better reflect the nature of the software. Jeff started OpenSTV partly out of an academic interest and partly out of frustration for the lack of available tools for conducting STV elections.
OpenSTV is released under version 2 of the GNU General Public License. More information about OpenSTV can be found in the links on the sidebar.
Any support in improving OpenSTV would be greatly appreciated. The following types of people would be most useful:
Questions and comments should be sent to the email list openstv at googlegroups.com.
I. Overview
This Help assumes that you already understand the basics of an STV election and guides the process of using OpenSTV. There are three basic steps to running an election:
These three steps are described in more detail below.
II. File Menu
The file menu contains only two items. The Reset option puts OpenSTV mostly back into its initial state. The Exit option exits.
III. Edit Menu
You can copy selected text from the current tab and paste it into another program. You can also select all of the text in the current tab.
IV. Ballots Menu
Ballots may be loaded from a file or entered through the program. Two ballot file formats are supported: text format and BLT format. The BLT format is preferred. The program will ask you to save modified ballots before exiting or loading a new set of ballots, but you can save the ballots at any time.
The first ballot file format supported is the text format. Here is an example:
Amy Bob Chuck
Bob Amy
Chuck
Chuck Bob
The first ballot lists Amy first, Bob second, and Chuck third. Note that candidate names must be alphanumeric. You can also add a weight to a ballot by prefixing it with a number and a colon:
10: Amy Bob Chuck
5: Bob Amy
Chuck
2: Chuck Bob
The second format is the BLT format used by the Electoral Reform Society. Here is an example:
4 2 # four candidates are competing for two seats
-2 # Bob has withdrawn (optional)
1 4 1 3 2 0 # first ballot
1 2 4 1 3 0
1 1 4 2 3 0 # The first number is the ballot weight (>= 1).
1 1 2 4 3 0 # The last 0 is an end of ballot marker.
1 1 4 3 0 # Numbers inbetween correspond to the candidates
1 3 2 4 1 0 # on the ballot.
1 3 4 1 2 0
1 3 4 1 2 0 # Chuck, Diane, Amy, Bob
1 4 3 2 0
1 2 3 4 1 0 # last ballot
0 # end of ballots marker
"Amy" # candidate 1
"Bob" # candidate 2
"Chuck" # candidate 3
"Diane" # candidate 4
"Gardening Club Election" # title
Unlike the above example, comments are not allowed in a BLT file.
There is also a menu item that allows BLT files to be appended. First load one BLT file and then append the others. All the BLT files must have the same number of candidates, the same number of seats, and identical candidate names.
Ballots may also be entered through the program. If no ballot file has been loaded, then a new ballot file is created. If a ballot file has been loaded, then ballots can be edited, added, and deleted. You can mix appending and editing of ballots.
The program accepts only valid ballots. You don't need to rank all of the candidates on each ballot, but you cannot skip rankings. You also cannot give two or more candidates the same ranking.
Finally, you can shuffle the order of the ballots. This could be interesting for Cambridge STV and Random Transfer STV because the outcome can depend on the order of the ballots.
V. Method Menu
A variety of election methods are available and are listed roughly in order of increasing complexity. See Method Details in the help menu for more information on each method. If Method->Options is gray, then there are no options. By default, only the more common methods are shown. Choose "Show All Methods" to see the others.
VI. Election Menu
Set the number of candidates to elect, a title for the election, and for some methods, the precision to be displayed on the screen. The election results will be displayed in a new tab.
You can also select candidates to eliminate from the election. The eliminated candidates are removed from the ballots before counting the votes.
VII. Results Menu
Unwanted tabs can be deleted, but you can't delete the console tab. The font size in any tab can be changed to the desired size. If the election results are wider than the window size, then choosing a smaller font size may allow for easier viewing of election results.
The results can be saved into a file and two formats are supported. The text format is exactly what you see on the screen. The CSV (comma separated value) output is used by the Electoral Reform Society and can be loaded into any spreadsheet program. The CSV format is not available for all methods.
VIII. Help Menu
From the Help Menu you can also find more details on the election methods available and the GNU General Public License.
IX. Advanced Use
You can also write your own Python scripts to run elections. To do this, you would use the Python modules STV.py and ballots.py. (OpenSTV.py and wxPython are not needed). Here is an example:
from ballots import *
from STV import *
b = Ballots()
b.loadBLT("ballots.blt")
e = CambridgeSTV(b)
e.runElection()
Q. Where do I get my questions answered?
A. Send an email to openstv at googlegroups.com.
Q. Which voting method should I use?
A. There is no clear answer to this question and you will get different answers from different people, but we will give our recommendations here.
If you are electing one person and simplicity is important, then we recommend instant runoff voting. Instant runoff voting is easy to explain and gives good results.
If you are electing one person and simplicity is not important, then we recommend Condorcet voting. Most people agree that Condorcet is the best method for electing one person, but it is more difficult to explain.
If you are electing multiple people and simplicity is important, then we recommend Scottish STV, as it is the simplest of all the STV methods.
If you are electing multiple people and simplicity is not important, then we recommend Meek STV. Most people agree that Meek STV is the best variant of STV, but it can only be implemented with a computer program.
Q. Will you implement a feature that I would like to see in OpenSTV?
A. It depends.
The main factors include (1) how worthwhile the desired feature is, (2) how important you or your organization is, and (3) how hard it is to implement the desired feature.
For example, if we have no idea who you are, but your request is a really good one and it is easy to implement, it will probably make the next release. On the other hand, if the United States Senate asks us to implement a really crummy feature, then we probably wouldn't do it.
Q. Will you implement duplicate rankings?
A. No.
Some STV implementations allow voters to use duplicate rankings or give multiple candidates the same ranking. For example, rank Bob first, rank both Mary and Jim second, and rank Jane third. In our opinion, this is a really bad idea. When implementing any feature, it is necessary to trade off the benefits the feature would provide against the costs of implementing the feature.
Duplicate rankings do not provide any significant benefit. If a voter considers multiple candidate to be equally good, then the voter suffers no harm if required to order them. If a voter does use duplicate rankings, then the ballot can be reordered before the votes are counted. For example, the above ballot could be randomly reordered to the following: (1) Bob, (2) Mary, (3) Jim, and (4) Jane. Since the voter does not see any difference between Mary and Jim, the voter is not harmed by randomly picking Mary to be second and Jim to be third.
Duplicate rankings are difficult to implement. While it is certainly possible to implement duplicate rankings, the code is necessarily more complicated, which increases the likelihood of bugs and an error in the outcome.
For example, the City of Burlington, Vermont allows duplicate rankings in its implementation of IRV, but this will not be implemented in OpenSTV.
The authors of OpenSTV would like to thank the following people for their much appreciated assistance:
OpenSTV depends on other open-source and/or free software:
Jeff is the founder of the OpenSTV project and its primary programmer. When not working on OpenSTV, Jeff is an intellectual property attorney at Wolf Greenfield in Boston. Jeff previously worked as a senior speech scientist writing speech recognition software, has a J.D. from Cornell Law School, a Ph.D. in electrical engineering from the University of Michigan, and a B.S. in electrical engineering from Cornell University. You can reach Jeff at jco8 at cornell.edu.
Selected publications:
Jonathan is the CTO at Resilience Corp in Mountain View, California. He joined the OpenSTV project after helping to implement internal STV elections for the Green Party of the United States and the Green Party of California.
Jonathan studied philosophy at New College of Florida ('66), but drifted into computer technology to pay the rent. He blogs occasionally at Pragmatos.
STV-related publications:
Brian is a Software Engineer who has retired from the National Physical
Laboratory. While at NPL, he worked on the Pascal standard and was responsible for the design of the numerics in the Ada programming language. He is currently Editor of Voting matters.
Selected publications: