Add documentation on constraints

This commit is contained in:
RunasSudo 2021-05-22 17:04:33 +10:00
parent 9f198c5e0f
commit 86695aa67e
Signed by: RunasSudo
GPG Key ID: 7234E476BF21C61A
5 changed files with 70 additions and 2 deletions

View File

@ -10,7 +10,7 @@ pyRCV2 may be used in a number of different ways:
## Features ## Features
pyRCV2 accepts data in the [BLT file format](http://www.dia.govt.nz/diawebsite.NSF/Files/meekm/%24file/meekm.pdf), and can count votes using: pyRCV2 accepts data in the [BLT file format](https://yingtongli.me/git/pyRCV2/about/docs/blt.md), and can count votes using:
* weighted inclusive Gregory STV (e.g. [Scottish STV](https://www.opavote.com/methods/scottish-stv-rules)) * weighted inclusive Gregory STV (e.g. [Scottish STV](https://www.opavote.com/methods/scottish-stv-rules))
* unweighted inclusive Gregory STV (e.g. [Australian Senate STV](https://www.legislation.gov.au/Details/C2020C00400/Html/Text#_Toc59107700)) * unweighted inclusive Gregory STV (e.g. [Australian Senate STV](https://www.legislation.gov.au/Details/C2020C00400/Html/Text#_Toc59107700))
@ -23,11 +23,12 @@ pyRCV2 is highly customisable, including options for:
* different quotas and quota rules (e.g. exact Droop, Hare) or progressively reducing quota * different quotas and quota rules (e.g. exact Droop, Hare) or progressively reducing quota
* calculations using fixed-point arithmetic, guarded fixed-point ([quasi-exact](http://www.votingmatters.org.uk/ISSUE24/I24P2.pdf)) or exact rational numbers * calculations using fixed-point arithmetic, guarded fixed-point ([quasi-exact](http://www.votingmatters.org.uk/ISSUE24/I24P2.pdf)) or exact rational numbers
* different tie breaking rules (backwards, random, manual) with auditable deterministic random number generation * different tie breaking rules (backwards, random, manual) with auditable deterministic random number generation
* multiple constraints (e.g. affirmative action rules)
* extensible API for other counting methods * extensible API for other counting methods
## Online usage ## Online usage
After preparing the BLT file, head to <https://yingtongli.me/rcv/>. Select the BLT file, and click *Count*. pyRCV2 will count the election and display the results in a count sheet. See [here](https://yingtongli.me/blog/2020/12/24/pyrcv2.html) for more detailed instructions. After preparing the [BLT file](https://yingtongli.me/git/pyRCV2/about/docs/blt.md), head to <https://yingtongli.me/rcv/>. Select the BLT file, and click *Count*. pyRCV2 will count the election and display the results in a count sheet. See [here](https://yingtongli.me/blog/2020/12/24/pyrcv2.html) for more detailed instructions.
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/pyRCV2/about/docs/options.md). 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/pyRCV2/about/docs/options.md).

34
docs/blt.md Normal file
View File

@ -0,0 +1,34 @@
# BLT file format
pyRCV2 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.

24
docs/con.md Normal file
View File

@ -0,0 +1,24 @@
# CON file format
pyRCV2 accepts the specification of constraints in a nonstandard file format, referred to as a CON file. The CON format is inspired by the standard [BLT file format](https://yingtongli.me/git/pyRCV2/about/docs/blt.md) used for ballot data.
Suppose there are 7 candidates in the election. An example CON file is as follows:
```
"Gender" "Men" 0 99 2 3 4 6
"Gender" "Women" 2 99 1 5 7
"District" "District 1" 2 2 1 2 3
"District" "District 2" 2 2 4 5 6 7
```
For the purpose of constraints, one or more *categories* are established (in the example, ‘Gender’ and ‘District’). Each category contains one or more *groups*. Within each category, every candidate must be assigned to exactly one group. The constraints are placed on groups, such that a certain minimum number, and a certain maximum number, must be elected from each group.
If there is no minimum for a particular group, specify `0`. If there is no maximum for a particular group, specify any number greater than or equal to the number of candidates in the group.
If there are candidates who do not fit into any group within a particular category, assign those candidates to a placeholder group with a minimum of 0 and a maximum greater than or equal to the number of candidates in the group.
For example, the line `"Gender" "Men" 0 99 2 3 4 6` means that within the ‘Gender’ category ‘Men’ group, a minimum of 0 candidates and a maximum of 99 candidates can be elected (i.e. there are no constraints). The candidates in the ‘Men’ group are candidates 2, 3, 4 and 6 (in the order listed in the BLT file).
The remaining lines indicate that a minimum of 2 women must be elected (with a maximum of 99, i.e. no maximum), and exactly 2 candidates must be elected from each of districts 1 and 2.
Every line describes one group within a category, and every group must be described on its own line.

View File

@ -135,3 +135,11 @@ This option allows you to input an arbitrary value to seed the deterministic ran
The default value is the current date, formatted YYYYMMDD. The default value is the current date, formatted YYYYMMDD.
The algorithm used by the random number generator is specified at [rng.md](rng.md). The algorithm used by the random number generator is specified at [rng.md](rng.md).
## Constraints (--constraints)
This file selector allows you to load a [CON file](https://yingtongli.me/git/pyRCV2/about/docs/con.md) specifying constraints on the election. For example, if a certain minimum or maximum number of candidates can be elected from a particular category.
pyRCV2 applies constraints using the Grey–Fitzgerald method. Whenever a candidate is declared elected or excluded, any candidate who must be elected to secure a conformant result is deemed *guarded*, and any candidate who must not be elected to secure a conformant result is deemed *doomed*. Any candidate who is doomed is excluded at the next opportunity. Any candidate who is guarded is prevented from being excluded.
Multiple constraints are supported using the method described by Hill ([*Voting Matters* 1998;9(1):2–4](http://www.votingmatters.org.uk/ISSUE9/P1.HTM)) and Otten ([*Voting Matters* 2001;13(3):4–7](http://www.votingmatters.org.uk/ISSUE13/P3.HTM)).

View File

@ -20,6 +20,7 @@ class CounterStub:
pass pass
def test_constraints_otten(): def test_constraints_otten():
"""Check constraints matrix is stabilised correctly, according to example by Otten J. Voting Matters 2001;13(3):4-7"""
counter = CounterStub() counter = CounterStub()
counter._constraint_matrix = constraints.ConstraintMatrix([2, 3]) counter._constraint_matrix = constraints.ConstraintMatrix([2, 3])
cm = counter._constraint_matrix cm = counter._constraint_matrix