aboutsummaryrefslogtreecommitdiff
path: root/docs/options.md
blob: e974f9b175b4a88c41a8b676bb180d2944c6123f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
1# Options and advanced options
2
3## Preset
4
5The preset dropdown allows you to choose from a hardcoded list of preloaded STV counting rules. These are:
6
7| Method | Description | Exceptions | Validated |
8|-|-|-|-|
9| [OpenTally WIGM](https://yingtongli.me/blog/2021/07/24/opentally-wigm.html) | Recommended set of simple STV rules designed for computer counting, using the weighted inclusive Gregory method, exact quotas and rational arithmetic. | | |
10| Scottish STV | Rules from the [*Scottish Local Government Elections Order 2011*](https://www.legislation.gov.uk/ssi/2011/399/schedule/1/made), using the weighted inclusive Gregory method. | | ✓ |
11| Meek STV | Advanced STV rules designed for computer counting, recognised by the Proportional Representation Society of Australia (Victoria–Tasmania) as the superior STV system. | | |
12| • OpenTally Meek | Recommended rules for Meek STV. Operates according to the original 1987 Hill–Wichmann–Woodall ‘Algorithm 123’ specification ([*The Computer Journal* 1987;30(3):277–81](https://www.dia.govt.nz/diawebsite.NSF/Files/meekm/%24file/meekm.pdf)), except that (a) ties are broken backwards then at random, (b) fixed-point arithmetic with 5 decimal places is used, and (c) candidates are elected on strictly exceeding the quota. | | ✓ |
13| • Meek STV (2006) | Operates according to Hill's 2006 revisions ([*Voting Matters* 2006;(22):7–10](http://www.votingmatters.org.uk/ISSUE22/I22P2.pdf)). This is the algorithm referred to in OpenSTV/OpaVote as ‘Meek STV’, and forms the basis of New Zealand's Meek STV rules. | [E1] | ✓ |
14| • Meek STV (New Zealand) | Operates according to Schedule 1A of the [*Local Electoral Regulations 2001*](https://www.legislation.govt.nz/regulation/public/2001/0145/latest/DLM57125.html). | [E1] | ✓ |
15| Australian Senate STV | Rules from the [*Commonwealth Electoral Act 1918*](https://www.legislation.gov.au/Details/C2020C00400/Html/Text#_Toc59107700), using the unweighted inclusive Gregory method. | [E2] [E3] [E4] | ✓ |
16| Western Australia STV | Rules from the [*Electoral Act 1907* (WA)](https://www.legislation.wa.gov.au/legislation/prod/filestore.nsf/FileURL/mrdoc_29498.pdf/$FILE/Electoral%20Act%201907%20-%20[17-a0-06].pdf), using the weighted inclusive Gregory method. | [E2] [E3] | |
17| Australian Capital Territory STV | Rules from the [*Electoral Act 1992* (ACT)](https://www.legislation.act.gov.au/View/a/1992-71/current/PDF/1992-71.PDF), using the exclusive Gregory method. | | ✓ |
18| Minneapolis STV | Rules from chapter 167 of the [*Minneapolis Code of Ordinances*](https://library.municode.com/mn/minneapolis/codes/code_of_ordinances?nodeId=COOR_TIT8.5EL_CH167MUELRUCO), using the weighted inclusive Gregory method. | [E5] | ✓ |
19| Cambridge STV | Rules in force in Cambridge, Massachusetts, using random sample transfers. These rules are derived from the [former chapter 54A of the Massachusetts General Laws](https://www.cambridgema.gov/-/media/Files/electioncommission/massachusettsgenerallawschapter54a.pdf), but have by regulation been modified to incorporate the procedures set out in Article IX of the former [1938 Charter of the City of Cincinnati](https://catalog.hathitrust.org/Record/001754258). See also [here](https://web.archive.org/web/20081118104049/http://www.fairvote.org/media/1993countmanual.pdf). | | ✓ |
20| Dáil Éireann STV | Rules from the [*Electoral Act 1992* (Ireland)](http://www.irishstatutebook.ie/eli/1992/act/23/enacted/en/print), using stratified random sample transfers. | [E4] [E6] | ✓ |
21| [Wright STV](https://www.aph.gov.au/Parliamentary_Business/Committees/House_of_Representatives_Committees?url=em/elect07/subs/sub051.1.pdf) | Rules proposed by Anthony van der Craats designed for computer counting, involving reset and re-iteration of the count after each candidate exclusion. | | ✓ |
22| [PRSA 1977](https://www.prsa.org.au/rule1977.htm) | Simple rules designed for hand counting, using the exclusive Gregory method, with counting performed in thousandths of a vote. | | ✓ |
23| [ERS97](https://www.electoral-reform.org.uk/latest-news-and-research/publications/how-to-conduct-an-election-by-the-single-transferable-vote-3rd-edition/) | More complex rules designed for hand counting, using the exclusive Gregory method. | [E7] | ✓ |
24| • ERS76 | Former rules from the 1976 2nd edition. | [E7] [E8] | ✓ |
25| • ERS73 | Former rules from the 1973 1st edition. | [E7] [E8] | |
26| Church of England | Rules from the Church of England [*Single Transferable Vote Rules 2020*](https://www.churchofengland.org/sites/default/files/2020-02/STV%20Rules%202020%20-%20final.pdf), similar to ERS73. | | ✓ |
27
28Exceptions:
29
30* [E1] When generating random numbers, OpenTally uses a [deterministic random number generator based on SHA-256](https://yingtongli.me/git/OpenTally/about/docs/rng.md), rather than the Wichmann–Hill(-based) algorithm.
31* [E2] When breaking ties backwards, OpenTally selects the candidate who had more/fewer votes at the last stage when *any* tied candidate had more/fewer votes, rather than the method described in the legislation (when each all had unequal votes). The OpenTally developers regard the method described in the legislation as a defect. For an independent discussion, see <a href="https://dl.acm.org/doi/10.1145/3014812.3014837">Conway et al.</a>
32* [E3] A tie between 2 candidates for the final vacancy will be broken backwards then at random, rather than the method described in the legislation.
33* [E4] Bulk exclusion is not performed, as the prescribed rules are more conservative than OpenTally's. See also the section on *Bulk exclusion* for further discussion.
34* [E5] The ‘mathematically eliminated by the sum of all ranked-choice votes comparison’ is not implemented.
35* [E6] The ‘quarter of a quota’ provision is disregarded when determining whether to defer surplus distributions.
36* [E7] No distinction is made between stages and substages (during exclusion). This affects only the numbering of stages and not the result.
37* [E8] By default, the quota is always calculated to 2 decimal places. For full ERS76 (ERS73) compliance, set *Round quota to 0 d.p.* when the quota is more than 100 (100 or more).
38
39For details of validation, see [validation.md](https://yingtongli.me/git/OpenTally/about/docs/validation.md).
40
41This functionality is not available on the command line.
42
43## Quota-related options
44
45### Quota (-q/--quota)
46
47The 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:
48
49* *Droop* (default) and *Droop (exact)*: *V*/(*S*+1)
50* *Hare* and *Hare (exact)*: *V*/*S*
51
52where *V* is the number of votes and *S* is the number of seats.
53
54The ‘*(exact)*’ version of each quota has effect only if *Round quota to [n] d.p.* is enabled. When that setting is enabled, *Droop* and *Hare* will increment the quota up to the next available rounded unit (even if the quotient is exact already), while the ‘*(exact)*’ versions will round the quota up if and only if the quotient is not already exact.
55
56When *Round quota to [n] d.p.* is not enabled, or when the exact form is used, the Droop quota is also known as the Newland–Britton or Hagenbach-Bischoff quota.
57
58### Quota criterion (-c/--quota-criterion)
59
60The quota criterion may be set to *>=* (candidates are elected if they meet or exceed the quota) or *>* (default; candidates are elected only if they strictly exceed the quota).
61
62Note that the combination ‘*>= Droop (exact)*’ (or, when *Round quota to [n] d.p.* is disabled, ‘*>= Droop*’) can result in more candidates meeting the quota than there are available vacancies, hence this particular combination is not recommended.
63
64### Quota mode (--quota-mode)
65
66This option allows you to specify whether the votes required for election can change during the count. The options are:
67
68* *Static quota* (default): The quota is calculated once after all first-preference votes are allocated, and remains constant throughout the count.
69* *Static with ERS97/ERS76 rules*: The quota is static, but candidates may be elected if their vote exceeds (or equals, according to the *Quota criterion*) the active vote, divided by one more than the number of remaining vacancies (with minor variations in details between ERS97 and ERS76). Additionally, under ERS97 rules, the quota is reduced if ballot papers exhaust before any candidate is elected.
70* *Dynamic by total vote*: The quota is recalculated at the end of each stage, according to the *Quota* option.
71* *Dynamic by active vote*: The quota is recalculated at the end of each stage, according to the *Quota* option, but where *V* is the active vote and *S* is the number of remaining vacancies.
72
73When a dynamic quota is used, then unless *Surplus method* is set to *Meek*, the quota that applies to an elected candidate is the quota at the start of the stage when the candidate's surplus is distributed. Further distributions are not performed later, even if the quota is later reduced.
74
75## STV variants
76
77### Surplus order (--surplus-order)
78
79This dropdown allows you to select in what order surpluses are distributed:
80
81* *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).
82* *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.
83
84Some 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). In this case, the option ‘*By order*’ should be selected.
85
86### Surplus method (-s/--surplus)
87
88This dropdown allows you to select how ballots are transferred during surplus transfers. The recommended methods are:
89
90* *Weighted inclusive Gregory* (default): During surplus transfers, all applicable ballot papers of the elected candidate are examined. Transfers are weighted according to the values of the ballot papers.
91* *Meek method*: Transfers are computed as described at <http://www.dia.govt.nz/diawebsite.NSF/Files/meekm/%24file/meekm.pdf>.
92
93Other Gregory methods are supported, but not recommended:
94
95* *Unweighted inclusive Gregory*: During surplus transfers, all applicable ballot papers of the elected candidate are examined. Transfers are not weighted, and each ballot paper has equal value in the calculation.
96* *Exclusive Gregory (last bundle)*: During surplus transfers, only the ballot papers received in the last transfer (all of one value) are examined.
97
98Random sample methods are also supported, but also not recommended:
99
100* *Hare (exclusive sample)*: During surplus transfers, a subset of the ballot papers received in the last transfer, equal in size to the surplus, is examined.
101* *Inclusive Hare (sample)*: During surplus transfers, a subset of the elected candidate's ballot papers, equal in size to the surplus, is examined.
102
103The use of a random sample method requires *Normalise ballots* to be enabled, and will usually be used with a *Quota criterion* set to *>=*.
104
105### Papers to examine in surplus transfer (--transferable-only)
106
107* *Include non-transferable papers* (default): When this option is selected, all ballot papers of the transferring candidate are examined. Non-transferable papers are always exhausted at the relevant surplus fractions. This is the method typically used with the weighted inclusive Gregory or Meek methods.
108* *Use transferable papers only*: When this option is selected, only transferable papers of the transferring candidate are examined. Non-transferable papers are exhausted only if the value of the transferable papers is less than the surplus. This is the method typically used with other surplus distribution methods.
109
110### (Gregory) Exclusion method (--exclusion)
111
112When *Surplus method* is set to a Gregory method, this option controls how candidates are excluded:
113
114* *Single stage* (default): When excluding candidate(s), transfer all their ballot papers in one stage.
115* *By value*: When excluding candidate(s), transfer their ballot papers in descending order of accumulated transfer value. Each transfer of all ballots of a certain transfer value forms a separate stage, i.e. if a transfer allows another candidate to meet the quota, no further papers are transferred to that candidate.
116* *By source*: When excluding candidate(s), transfer their ballot papers according to the candidate from which those papers were received, in the order the transferring candidates were elected or excluded. Each transfer of all ballots received from a certain candidate forms a separate stage.
117* *By parcel (by order)*: When excluding a candidate, transfer their ballot papers one parcel at a time, in the order each was received. Each parcel forms a separate stage. This option cannot be combined with bulk exclusion.
118* *Wright method (re-iterate)*: When excluding candidate(s), reset the count from the distribution of first preferences, disregarding the excluded candidates.
119
120### (Meek) NZ-style exclusion (--meek-nz-exclusion)
121
122When *Surplus method* is set to *Meek method*, this option controls how candidate keep values are updated when candidates are excluded:
123
124* When NZ-style exclusion is disabled (default), the excluded candidate's keep value is immediately reduced to 0. This is the method specified in the 1987 and 2006 Meek rules.
125* When NZ-style exclusion is enabled, all elected candidates' keep values are first updated by one further iteration; only then is the excluded candidate's keep value reduced to 0. This is the method specified in the New Zealand *Local Electoral Regulations 2001*.
126
127### (Sample) Sample method (--sample)
128
129When *Surplus method* is set to a random sample method, this option controls which subset of ballot papers is selected for transfer during surplus distributions:
130
131* *Stratify* (default): The candidate's ballot papers are first stratified into subparcels according to next available preference, and an equal proportion of each subparcel is transferred, with the subset transferred comprising the ballot papers in each subparcel most recently received by the candidate. In the calculation of proportions, the largest remainders are rounded up so there is no loss by fraction. This is the method specified by the [*Electoral Act 1992* (Ireland)](http://www.irishstatutebook.ie/eli/1992/act/23/section/121/enacted/en/html#sec121).
132* *By order*: The subset transferred comprises the ballot papers most recently received by the candidate.
133* *Cincinnati*: The subset is selected using the deterministic method used in [Cambridge, Massachusetts](https://web.archive.org/web/20081118104049/http://www.fairvote.org/media/1993countmanual.pdf) (derived from Article IX of the former 1938 Cincinnati *Code of Ordinances*).
134
135In any case, the subset selected depends on the order of ballot papers in the BLT file, and is independent of the *Random seed* option.
136
137### (Sample) Transfer ballot-by-ballot (--sample-per-ballot)
138
139When *Surplus method* is set to a random sample method, this option controls when candidates are declared elected:
140
141* When ballot-by-ballot transfer is disabled (default), candidates are declared elected only at the end of a stage, as usual.
142* When ballot-by-ballot transfer is enabled, candidates are declared elected immediately on meeting the quota after the transfer of any single ballot paper. Consequential surpluses therefore do not arise, and surpluses only occur during the count of first preferences.
143
144### Ties (-t/--ties)
145
146This dropdown allows you to select how ties (in surplus transfer or exclusion) are broken. The options are:
147
148* *Backwards*: Ties are broken according to which tied candidate had the most/fewest votes at the end of the *previous* stage. If a tie for most/fewest votes exists in the previous stage also, that tie is broken based on the next previous stage, and so on. This is the method specified, for example, by the [*Electoral Act 1992* (ACT)](https://www.legislation.act.gov.au/View/a/1992-71/current/PDF/1992-71.PDF).
149* *Fowards*: Ties are broken according to which tied candidate had the most/fewest votes at the end of the *earliest* stage where one tied candidate had more/fewer votes than the others, if such a stage exists. This is also known as the ‘ahead at first difference’ method.
150* *Random*: Ties are broken at random (see *Random seed*).
151* *Prompt*: The user is prompted to break the tie.
152
153Multiple 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, 4 options are available (‘*Backwards then random*’, ‘*Forwards then random*’, ‘*Random*’ and ‘*Prompt*’). On the command line, the `--ties` option can take multiple arguments (e.g. `--ties backwards random`).
154
155### Random seed (--random-seed)
156
157This 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.
158
159The default value is the current date, formatted YYYYMMDD.
160
161The algorithm used by the random number generator is specified at [rng.md](https://yingtongli.me/git/OpenTally/about/docs/rng.md).
162
163## Constraints (--constraints)
164
165This file selector allows you to load a [CON file](https://yingtongli.me/git/OpenTally/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.
166
167OpenTally 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.
168
169Multiple constraints are supported using the method described by Hill ([*Voting Matters* 1998;(9):2–4](http://www.votingmatters.org.uk/ISSUE9/P1.HTM)) and Otten ([*Voting Matters* 2001;(13):4–7](http://www.votingmatters.org.uk/ISSUE13/P3.HTM)).
170
171## Report options
172
173### Report style
174
175* *Votes only*: The result sheet displays the number of votes held by each candidate at each stage of the count.
176* *Votes (transposed)*: Same as *Votes only*, but transfers are displayed to the left of, rather than above, progress totals.
177* *Ballots and votes*: The result sheet displays the number of votes *and ballot papers* held by each candidate at each stage of the count.
178
179This functionality is not available on the command line.
180
181### Display up to [n] d.p. (--pp-decimals)
182
183This option allows you to specify to how many decimal places votes will be reported in the results report. It does not affect the internal precision of calculations.
184
185## Numeric representation
186
187### Numbers (-n/--numbers), Decimal places (--decimals)
188
189This dropdown allows you to select how numbers (vote totals, etc.) are represented internally in memory. The options are:
190
191* *Fixed*: Numbers are represented as fixed-precision decimals, up to a certain number of decimal places (default: 5).
192* *Fixed (guarded)*: Numbers are represented as fixed-precision decimals with ‘guard digits’ – also known as [‘quasi-exact’ arithmetic](http://www.votingmatters.org.uk/ISSUE24/I24P2.pdf). If *n* decimal places are requested, numbers are represented up to 2*n* decimal places, and two values are considered equal if the absolute difference is less than (10<sup>−*n*</sup>)/2.
193* *Rational* (default): 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.
194* *Float (64-bit)*: Numbers are represented as native 64-bit floating-point numbers. This is fast, but not recommended as unexpectedly large rounding errors may be introduced in some circumstances.
195
196### Normalise ballots (--normalise-ballots)
197
198In the BLT file format, each set of preferences can have a specified weight – this is typically used to indicate multiple voters who had the same preferences.
199
200When ballots are not normalised (default), a set of preferences with weight *n* > 1 is represented as a single ballot with value *n*. This is known as [list-packed ballots](http://www.votingmatters.org.uk/ISSUE21/I21P1.pdf).
201
202When ballots are normalised, a set of preferences with weight *n* > 1 is instead converted to *n* ballots each with value 1.
203
204## Count optimisations
205
206### Early bulk election (--no-early-bulk-elect)
207
208When early bulk election is enabled (default), the count terminates as soon as the set of winning candidates is known. Specifically:
209
210* At the beginning of each stage, if the number of continuing candidates exactly equals the number of remaining vacancies, all continuing candidates are declared elected in a single stage. This is typical of most STV rules.
211* If a proposed exclusion would cause the number of continuing candidates to exactly equal the number of remaining vacancies, all other continuing candidates are declared elected without transfers arising from the proposed exclusion being performed.
212* At the end of any stage, if *n* vacancies remain and the *n*-th top continuing candidate has more votes than all lower continuing candidates (plus votes awaiting transfer), the *n* top continuing candidates are immediately declared elected.
213
214If an early bulk election is performed, further surplus distributions are not performed, and outstanding exclusions are not completed, even if they could change the order of election.
215
216When early bulk election is disabled, surpluses continue to be distributed, and outstanding exclusions continue to be completed, even once the number of continuing candidates exactly equals the number of remaining vacancies. Bulk election is performed only as a final measure once there are no more surpluses to distribute, and no exclusions to complete.
217
218In either case, candidates are declared elected in descending order of votes. This ensures that only one candidate is ever elected at a time and the order of election is well-defined, which is required e.g. for affirmative action rules.
219
220Note that the OpenTally rules for early bulk election are aggressive, and many STV rules do not implement all 3 (if any at all). It is not possible at this time to selectively apply only some of the rules. In order to reproduce the result of a count performed by others, where not all rules were implemented, consider disabling early bulk election and comparing the results at the time a bulk election would have been made.
221
222### Bulk exclusion (--bulk-exclude)
223
224When bulk exclusion is disabled (default), only one candidate is ever excluded per stage.
225
226When bulk exclusion is enabled, as many candidates as possible are excluded together in each single stage, provided that sufficient candidates remain to fill the vacancies, and the bulk exclusion could not change the order of exclusion. If 2 or more candidates are tied, either all are bulk excluded or none are. The ballot papers of all excluded candidates are considered together, and transferred according to the *Exclusion method*.
227
228Note that some rules (such as the Australian Senate rules) provide for more conservative ‘bulk exclusion’ which additionally requires that the bulk exclusion cannot cause a candidate to be elected. This form of bulk exclusion accordingly cannot change the result compared with no bulk exclusion (except as far as rounding may be concerned), and is not supported.
229
230### Defer surpluses (--defer-surpluses)
231
232When deferred surpluses is disabled (default), all surpluses must be transferred before candidates can be excluded.
233
234When deferred surpluses is enabled, the transfer of all surpluses is deferred if doing so could not change the order of exclusion (including of a bulk exclusion, if that is enabled).
235
236### Immediate election (--no-immediate-elect)
237
238When *Surplus method* is set to a Gregory or random sample method, this option controls when candidates are elected:
239
240* When immediate election is enabled (default), a candidate is declared at the end of the stage once reaching the quota. This is typical of most STV rules.
241* When immediate election is disabled, a candidate is declared elected only once their surplus is transferred. This is the method specified by the Minneapolis rules.
242
243Likewise, when *Surplus method* is set to *Meek method*:
244
245* When immediate election is enabled (default), a candidate meeting the quota interrupts a surplus distribution. The candidate is immediately declared elected, before the distribution of all surpluses of all now-elected candidates continues. This is the method specified in the 2006 Meek rules.
246* When immediate election is disabled, all current surpluses are distributed and keep values finalised, before any candidates exceeding the quota are then declared elected. This is the method specified in the 1987 Meek rules.
247
248### Minimum threshold (--min-threshold)
249
250When candidates are first to be excluded, all candidates with votes less than or equal to this threshold are excluded at once. The default value is 0, i.e. all candidates with no votes are excluded at once.
251
252## Rounding
253
254### Round quota/votes/surplus fractions/ballot values to [n] d.p. (--round-quota, --round-votes, --round-surplus-fractions, --round-values)
255
256When rounding is enabled, the specified values are rounded to the specified number of decimal places. This enables, for example, votes to be counted only in integers, while ballot values and surplus fractions are calculated to higher precision (according to the *Numbers* option).
257
258When enabled, the quota is incremented or rounded up (according to the *Quota* option). When *Surplus method* is set to a Gregory method, votes, surplus fractions and ballot values are always rounded down.
259
260In relation to *Round surplus fractions to [n] d.p.* – note that surplus fractions are used in STV in calculations of the form *A* × (*B*/*C*), where (*B*/*C*) is the surplus fraction. The order of operations depends on this setting:
261
262* When this option is disabled (default), (*A* × *B*) is calculated first, then divided by *C*. This minimises rounding errors.
263* When this option is enabled, (*B*/*C*) is calculated separately first and rounded to the specified precision, before being multiplied by *A*. Many STV rules designed for hand counting prescribe this method of manipulating surplus fractions.
264
265Surplus fractions are often known as ‘transfer values’; however, the term ‘value’ is reserved in OpenTally for referring to the values of votes.
266
267When *Surplus method* is set to *Meek method*:
268
269* --round-values instead controls the rounding of candidate keep values
270* --round-surplus-fractions instead controls the rounding of each intermediate product when computing candidates' votes
271* --round-votes controls the rounding of the final number of votes credited to each candidate
272* Keep values, intermediate products and candidate votes are rounded *up*
273
274### (Gregory) Sum surplus transfers (--sum-surplus-transfers)
275
276When *Surplus method* is set to a Gregory method, this option allows you to specify how the numbers of votes credited to candidates in a surplus transfer is calculated. In each case, votes are grouped according to the next available preference for a continuing candidate. Subsequently:
277
278* *By value*: The votes expressing a next available preference for that candidate are further divided according to value. For each group of votes at a particular value, the total value of all such votes is multiplied by the surplus fraction. The product is credited to that candidate.
279* *Per ballot*: For each individual vote expressing a next available preference for that candidate, the value of the vote is multiplied by the surplus fraction. The product is credited to that candidate.
280
281This option affects the result only as far as rounding (due to use of fixed-precision/floating-point arithmetic, or an explicit rounding option) is concerned.
282
283### (Meek) Surplus tolerance (--meek-surplus-tolerance)
284
285When *Surplus method* is set to *Meek method*, this option allows you to specify when the distribution of surpluses will be considered complete. The tolerance may be specified either as a percentage (ends with a `%`) or absolute number of votes (no `%`):
286
287* Percentage: Surplus distributions will be considered complete when every elected candidate's surplus exceeds the quota by no more than the specified percentage. This is the method specified in the 1987 Meek rules.
288* Absolute number of votes: Surplus distributions will be considered complete when the total surpluses of all elected candidates is no greater than the specified number of votes. This is the simpler method specified in the 2006 Meek rules.
Contact (issues, pull requests, etc.) at git@yingtongli.me. Generated by cgit.