Update documentation

docs/options.md

@@ -0,0 +1,84 @@
+# Options and advanced options
+
+## Preset
+
+The preset dropdown allows you to choose from a hardcoded list of preloaded STV counting rules. These are:
+
+* [Scottish STV](https://www.opavote.com/methods/scottish-stv-rules)
+* pyRCV STV-C: Our recommended rules for a computerised STV count
+* [Wright STV](https://www.aph.gov.au/Parliamentary_Business/Committees/House_of_Representatives_Committees?url=em/elect07/subs/sub051.1.pdf)
+
+This functionality is not available on the Python command line.
+
+## Quota (-q/--quota, -c/--quota-criterion)
+
+The quota dropdowns allow you to define the quota used in the election, and the quota criterion used to elect candidates. The quota may be set to:
+
+* Droop: ⌊*V*/(*S*+1)⌋ + 1
+* Droop (exact): *V*/(*S*+1) (also known as the Newland-Britton or Hagenbach-Bischoff quota)
+* Hare: *V*/*S*
+* Hare (exact): ⌊*V*/*S*⌋ + 1
+
+where *V* is the number of votes, *S* is the number of seats and ⌊…⌋ denotes the floor function (round down to the nearest integer, discarding any remainder).
+
+The quota criterion may be set to >= (candidates are elected if they meet or exceed the quota) or > (candidates are elected only if they strictly exceed the quota).
+
+Note that the combination ‘>= Droop (exact)’ can result in more candidates meeting the quota than there are available vacancies, hence this particular combination is not recommended.
+
+The default is ‘>= Droop’, which is the most common STV quota, but we recommend ‘> Droop (exact)’ as this prevents the quota being unnecessarily large when fractional surplus distribution methods (as in pyRCV2) are used.
+
+## Progressive quota (--prog-quota)
+
+When this option is disabled (default), the quota is calculated once after all first-preference votes are allocated, and remains constant throughout the count. [OpaVote](https://www.opavote.com/help/online-counts) calls this a ‘static threshold’.
+
+When this option is enabled, the quota is recalculated at the end of every stage, and may decrease throughout the count as votes are exhausted. OpaVote calls this a ‘dynamic threshold’.
+
+## Numbers (-n/--numbers), Decimal places (--decimals)
+
+This dropdown allows you to select how numbers (vote totals, etc.) are represented internally in memory. The options are:
+
+* Fixed: Numbers are represented as fixed-precision decimals, up to a certain number of decimal places (default: 5).
+* Rational: Numbers are represented exactly as fractions, resulting in the elimination of rounding error, but increasing computational complexity when the number of surplus transfers is very large.
+* Native float: Numbers are represented as floating-point numbers. This is fast, but not recommended as unexpectedly large rounding errors may be introduced in some circumstances.
+* Native int: Numbers are represented as integers.
+
+Note that, when unweighted inclusive Gregory surplus transfers are used (see *Method*), ballot weights are always represented internally as fractions, while candidate totals are represented according to this option.
+
+## Surplus order (-s/--surplus-order)
+
+This dropdown allows you to select in what order surpluses are distributed:
+
+* By size (default): When multiple candidates exceed the quota, the largest surplus is transferred (even if it arose at a later stage of the count).
+* By order: When multiple candidates exceed the quota, the surplus of the candidate elected first is transferred (even if it is smaller than another). Candidates are always declared elected in descending order of number of votes.
+
+Some STV counting rules provide, for example, that ‘no surplus shall be transferred before a surplus that arose earlier in the counting whether larger or not’ ([PRSA 1977 rules](https://www.prsa.org.au/rule1977.htm)). In this case, the option ‘By order’ should be selected.
+
+## Method (-m/--method)
+
+This dropdown allows you to select how ballots are transferred during surplus transfers or exclusions:
+
+* Weighted inclusive Gregory: During surplus transfers, a transfer value is calculated as the candidate's excess votes divided by the candidate's votes. Ballot weights are multiplied by the transfer value.
+* Unweighted inclusive Gregory: During surplus transfers, a transfer value is calculated as the candidate's excess votes divided by the candidate's ballot papers. Ballot weights are set to the transfer value. Transferred votes are credited in parcels to avoid excessive rounding.
+* Wright STV: Same as weighted inclusive Gregory, but when a candidate is excluded, the count is reset from the beginning (minus the excluded candidate).
+
+Note that, when unweighted inclusive Gregory surplus transfers are used, ballot weights are always represented internally as fractions, while candidate totals are represented according to the *Numbers* option.
+
+Other surplus transfer methods, such as exclusive Gregory (‘last bundle’) or non-fractional transfers (e.g. random sample) are not recommended and not supported.
+
+## Ties (-t/--ties)
+
+This dropdown allows you to select how ties (in surplus transfer or exclusion) are broken. The options are:
+
+* Backwards: Ties are broken according to which tied candidate had the most/fewest votes at the end of the last stage where one tied candidate had more/fewer votes than the others, if such a stage exists.
+* Random: Ties are broken at random (see *Random seed*).
+* Prompt: The user is prompted to break the tie. This option is not available in the web application.
+
+Multiple tie breaking methods can be specified. If the first method cannot resolve the tie, the next is tried, and so on. In the web application, 2 options are available (‘Backwards then random’ and ‘Random’). On the Python command line, the `--ties` option can be specified multiple times (e.g. `--ties backwards --ties random`).
+
+## Random seed (--random-seed)
+
+This option allows you to input an arbitrary value to seed the deterministic random number generator used to break ties when *Ties* is set to *Random*. When the same seed value is used, ties will always be broken in the same way, allowing the breaking of ties to be independently verified.
+
+The default value is the current date, formatted YYYYMMDD.
+
+The algorithm used by the random number generator is specified at [rng.md](rng.md).

docs/rng.md

@@ -0,0 +1,11 @@
+# Deterministic random number generator specification
+
+The deterministic random number generator used in pyRCV2 is based on an algorithm by [Ronald L Rivest](https://people.csail.mit.edu/rivest/sampler.py).
+
+The algorithm takes a *seed* value, which is an arbitrary character string. The algorithm has, in its internal state, a *counter*, whose value is initially 0.
+
+In order to generate a value between 0 (inclusive) and *n* (exclusive), to the state is appended a comma (",") followed by the value of the counter, and a SHA-256 hash *H* is computed of the resulting string encoded using UTF-8. The hash *H* is represented as an unsigned hexadecimal integer, *k*. The counter is incremented by 1.
+
+In order to avoid modulo bias, if *k* ≥ ⌊*M*/*n*⌋ × *n* (where *M* is the maximum possible value of *k*, 2^256 - 1), *k* is discarded and the algorithm is repeated.
+
+Otherwise, the result is *k* modulo *n*.