Add README.md

README.md

@@ -0,0 +1,37 @@
+# OpenTally
+
+OpenTally is an application for counting various preferential voting elections, with an academic focus, and emphasis on configurability.
+
+OpenTally may be used in a number of different ways:
+
+* as an online web application, no installation or special software required
+* as a standalone command line application
+* as a Rust library within another application
+
+## Features
+
+OpenTally accepts data in the [BLT file format](https://yingtongli.me/git/OpenTally/about/docs/blt.md), and can count votes using:
+
+* weighted inclusive Gregory STV (e.g. [Scottish STV](https://www.legislation.gov.uk/ssi/2011/399/schedule/1/made))
+* unweighted inclusive Gregory STV (e.g. [Australian Senate STV](https://www.legislation.gov.au/Details/C2020C00400/Html/Text#_Toc59107700))
+* exclusive Gregory STV (e.g. [PRSA 1977](https://www.prsa.org.au/rule1977.htm) and [ERS97](https://www.electoral-reform.org.uk/latest-news-and-research/publications/how-to-conduct-an-election-by-the-single-transferable-vote-3rd-edition/))
+
+OpenTally is highly customisable, including options for:
+
+* different quotas and quota rules (e.g. exact Droop, Hare)
+* calculations using fixed-point arithmetic or exact rational numbers
+* different tie breaking rules (backwards, random, manual) with auditable deterministic random number generation
+
+## Online usage
+
+After preparing the [BLT file](https://yingtongli.me/git/OpenTally/about/docs/blt.md), open the web UI. Select the BLT file, and click *Count*. OpenTally will count the election and display the results in a count sheet.
+
+By clicking *Show advanced options*, you can customise the options used for the count. A detailed explanation of the various options can be found [here](https://yingtongli.me/git/OpenTally/about/docs/options.md).
+
+Once the count is complete, you can click *Print result* to generate a printable result report.
+
+## Command line usage
+
+OpenTally may also be invoked as a command line application. Run `./opentally --help` to view help.
+
+For example, run `./opentally stv path/to/blt_file.blt --ties backwards random --random-seed foobar`.

docs/blt.md

@@ -0,0 +1,34 @@
+# BLT file format
+
+OpenTally accepts ballot data in the BLT file format, as described by [Hill, Wichmann & Woodall](https://www.dia.govt.nz/diawebsite.NSF/Files/meekm/%24file/meekm.pdf) for their implementation of Meek STV. The BLT file format is also used by [OpenSTV/OpaVote](https://www.opavote.com/openstv), Lundell's [Droop](https://github.com/jklundell/droop/wiki/BltFileFormat) and Otten's [eSTV](https://web.archive.org/web/20020606014623/http://estv.otten.co.uk/) (where it is known as a DAT data transfer file).
+
+The file format is as follows:
+
+```
+4 2
+-2
+3 1 3 4 0
+4 1 3 2 0
+2 4 1 3 0
+1 2 0
+2 2 4 3 1 0
+1 3 4 2 0
+0
+"Adam"
+"Basil"
+"Charlotte"
+"Donald"
+"Title"
+```
+
+The first line (`4 2`) indicates that there are 4 candidates for 2 vacancies. This must be on its own line.
+
+The second line (`-2`), which is optional, indicates that the 2nd candidate (Basil) has withdrawn. Multiple withdrawn candidates may be specified on this line, e.g. `-2 -3 -4`. This must, if present, be on its own line.
+
+The third line (second, if there are no withdrawn candidates) begins the ballot data. `3 1 3 4 0` indicates that there were 3 ballots which voted, in order of preference, for the 1st candidate (Adam), then the 3rd candidate (Charlotte), then the 4th candidate (Donald). A `0` optionally indicates the end of the list of preferences. Each such set of ballots must be on its own line.
+
+The end of the list of ballots must be indicated with a single `0`, which must be on its own line.
+
+The next lines give the names of the candidates, up to the number of candidates specified on the first line (in this case, 4). Each candidate's name must be surrounded by quotation marks, and must appear on its own line.
+
+The final line gives the name of the election, which must appear on its own line.