Add documentation on constraints

README.md

@@ -10,7 +10,7 @@ pyRCV2 may be used in a number of different ways:
 
 ## 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))
 * 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
 * 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
+* multiple constraints (e.g. affirmative action rules)
 * extensible API for other counting methods
 
 ## 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).
 

docs/blt.md

@@ -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.

docs/con.md

@@ -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.

docs/options.md

@@ -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 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)).

tests/test_constraints_otten.py

@@ -20,6 +20,7 @@ class CounterStub:
 	pass
 
 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._constraint_matrix = constraints.ConstraintMatrix([2, 3])
 	cm = counter._constraint_matrix